The Agent Loop

The development lifecycle with AI agents follows four phases: Plan, Build, Test, and Ship. Each phase has clear ownership between you and the agents, ensuring productive collaboration with predictable outcomes.

The Four Phases

Every feature flows through this loop. The key insight: you stay in control of what gets built, while agents handle the implementation details.

1. PLAN

Define Requirements

Create PRDs with clear user stories and acceptance criteria.

2. BUILD

Implement Features

Agents write code, commit changes, and track progress.

3. TEST

Verify Quality

Run quality gates, tests, and code review.

4. SHIP

Deploy Changes

Create PR, merge to main, and deploy.

Plan Phase
Build Phase
Test Phase
Ship Phase
1

Plan

YouOwnership

  • •Describe the feature you want at a high level
  • •Review and refine generated user stories
  • •Review Planner-authored acceptance criteria
  • •Mark the PRD as ready for implementation

Agent@planner

  • •Generate structured PRD with user stories
  • •Define acceptance criteria for each story
  • •Order stories by dependency
  • •Suggest branch name and scope boundaries
  • •Identify credential/service access requirements
@planner I want to add dark mode support. Users should toggle between light/dark themes, and their preference should persist.

Completion: PRD is saved to docs/prd.json with status "ready" and all stories have clear acceptance criteria.

Credential Planning

When your feature requires API keys, secrets, or third-party service access, the Planner captures this in the PRD's credentialRequirements section:

upfront

Credentials are requested before building begins. Use when the feature cannot be implemented without the service integration.

after-initial-build

Build starts with stubbed integration code. Credentials are requested before the story that first requires them.

2

Build

YouOwnership

  • •Kick off implementation with @builder
  • •Monitor progress in progress.txt
  • •Answer clarifying questions if any arise
  • •Let agent complete stories without interruption

Agent@builder

  • •Create/checkout the feature branch
  • •Implement stories in priority order
  • •Delegate to specialist sub-agents as needed
  • •Commit after each completed story
@builder Implement docs/prd.json. Start with the first incomplete story.

Completion: Each story is committed with passes: true in the PRD, and progress.txt documents learnings.

Credential Readiness Prompts

Builder checks credential requirements at key moments during implementation:

1

At PRD start: If credentials are marked upfront, Builder prompts for them before implementing any stories.

2

At story boundaries: For after-initial-build timing, Builder prompts when reaching a story that lists requiredCredentials.

This ensures you're not interrupted mid-implementation for credentials you don't have ready yet.

3

Test

YouOwnership

  • •Review code changes manually if desired
  • •Test in browser for UI changes
  • •Request critic review for deeper analysis
  • •Decide if changes meet your standards

Agent@builder + critics

  • •Run quality gates (lint, typecheck, tests)
  • •Generate unit tests for new code
  • •Queue E2E tests for UI changes
  • •Fix any issues before proceeding
@critic Review the changes on this branch for security and performance issues.

Completion: All quality gates pass (lint, typecheck, tests), critic feedback is addressed, and you're confident in the changes.

4

Ship

YouOwnership

  • •Approve the PR for merge
  • •Verify deployment succeeds
  • •Confirm feature works in production
  • •Archive the completed PRD

Agent@builder

  • •Create PR with summary of all changes
  • •List implemented user stories
  • •Include testing notes
  • •Move PRD to docs/completed/

Git Completion Workflow (7 Steps)

Both PRD mode and ad-hoc mode use the same canonical git shipping process, driven by the git.agentWorkflow configuration:

  1. 1Validate config — Check git.agentWorkflow exists (fail fast if missing)
  2. 2Stage & commit — Run git add . and commit with descriptive message
  3. 3Push to remote — Push to pushTo branch
  4. 4Check protection — Is createPrTo in requiresHumanApproval?
  5. 5Prompt user — "Create PR to [branch]? (y/n)"
  6. 6Create PR — Run gh pr create to createPrTo branch
  7. 7Auto-merge? — Only if target is NOT in requiresHumanApproval

User Prompt Before PR Creation

Both PRD mode and ad-hoc mode now prompt the user before creating a PR. This ensures you always have the opportunity to review changes before they become a pull request. The prompt shows the target branch and a summary of commits.

@builder Create a PR for this branch with a summary of all changes.

Completion: PR is merged to main, feature branch is deleted, and PRD is archived.

Trunk-Based Git Workflow

The toolkit follows a trunk-based development model. All work flows through short-lived feature branches that merge directly to main.

main
← Integration branch (always deployable)
branch off
feature/dark-mode
← Short-lived feature branch
PR & merge
main
← Feature merged, branch deleted

Do

  • • Branch from main for all features
  • • Keep branches short-lived (hours to days)
  • • Merge via PR after review passes
  • • Delete branches after merge

Don't

  • • Don't use long-lived develop branches
  • • Don't create release/* branches
  • • Don't let branches diverge for weeks
  • • Don't stack multiple features on one branch

Why trunk-based? Smaller, more frequent merges reduce integration pain. Feature flags handle incomplete features in production. This matches how agents work — each PRD produces one branch with focused, reviewable changes.

Agent Workflow Configuration

Control where agents push code and create PRs via the git.agentWorkflow setting in your project.json:

{ "git": { "defaultBranch": "main", "autoCommit": true, "agentWorkflow": { "workBranch": "main", "pushTo": "main", "createPrTo": "main", "requiresHumanApproval": ["production"] } } }
workBranch— Where agents create feature branches from
pushTo— Where to push changes (same as workBranch for trunk-based)
createPrTo— Target branch for PRs
requiresHumanApproval— Branches where agents can create PRs but cannot auto-merge

Protected Branch Behavior

For branches listed in requiresHumanApproval:

  • • Direct push — BLOCKED (agents cannot push directly)
  • • Create PR — ALLOWED (agents can create PRs for review)
  • • Auto-merge — BLOCKED (human must approve and merge)
PR-baseddefault

Agent creates feature branches and opens PRs for review before merging. Standard workflow for teams with code review requirements.

Direct push

When pushTo equals workBranch, agent commits directly to trunk. Ideal for solo developers.

Deprecated Settings

The following settings are deprecated and replaced by git.agentWorkflow:

  • • agents.trunkMode
  • • agents.autoPush
  • • git.trunkMode
  • • git.autoPush

Multi-Session Coordination

Session coordination is now always-on. The toolkit automatically detects when multiple sessions are active and uses locks, lazy heartbeats, and PRD claiming to prevent conflicts and enable seamless resumption.

How Session Locks Work

1

Claim: When a session starts work on a PRD, it writes a lock entry to session-locks.json with session ID, timestamp, and claimed PRD path.

2

Lazy Heartbeat: In solo sessions, heartbeat is local-only (no git operations). When multiple sessions are detected, it switches to full git round-trip for coordination. If a session crashes, the stale heartbeat (10+ min old) signals that the lock can be reclaimed.

3

Conflict avoidance: Other sessions check for locks before claiming a PRD. If locked, they report who holds it and suggest waiting or picking a different PRD.

4

Release: When a PRD is completed (PR created or merged), the lock is released and the entry is removed from the lock file.

Resumable Sessions

Each story's passes flag is persisted in the PRD. When you resume, the agent reads this state and continues from the first incomplete story—no manual tracking needed.

Merge Queue

When multiple PRDs complete in parallel, they enter a merge queue. Each branch rebases from trunk before merging, ensuring clean integration without conflicts.

Pending Updates System

As agents work on your projects, they sometimes discover improvements needed for project-specific configuration, conventions, or toolkit settings. These changes are queued as pending updates for review before being applied.

Update Sources

Updates can come from three locations, checked in priority order:

1

Project-Local

docs/pending-updates/ — Updates specific to this project. Applied first.

2

Central Registry

~/.config/opencode/pending-updates/ — Cross-project updates with affinity rules.

3

Legacy Per-Project

~/pending-updates/ — Legacy location for backward compatibility.

Affinity Rules

Central registry updates can target specific projects using affinity rules in the update file's frontmatter:

---
createdBy: developer
date: 2026-02-28
priority: normal
affinity:
  projectId: my-saas-app      # Match by project ID
  stack:
    frontend: react           # Match by stack
    backend: node
  integrations:
    - stripe                  # Match if project uses Stripe
---

# Update Request: Add Stripe webhook patterns

## What to change
Add webhook handler patterns to CONVENTIONS.md...

Matching Logic

Updates without affinity rules are shown to all projects. Updates with affinity rules only appear for projects that match all specified criteria.

Applied Updates Tracking

Each project tracks which updates have been applied in docs/applied-updates.json:

{
  "appliedUpdates": [
    {
      "filename": "2026-02-28-add-stripe-patterns.md",
      "appliedAt": "2026-02-28T14:30:00Z",
      "appliedBy": "builder"
    }
  ]
}

This prevents the same update from being applied multiple times. When an update is applied, agents delete the source file and record it here.

Who Writes Updates

Any agent can queue updates: @developer for conventions, @builder for PRD patterns, @toolkit for system improvements. You can also create them manually.

When They're Applied

@planner checks for pending updates at the start of each session. It presents matching updates for review before proceeding with project work.

Best Practices

Do

  • • Start with clear, specific acceptance criteria
  • • Review PRD stories before implementation begins
  • • Let agents complete stories before interrupting
  • • Use critics for systematic code review
  • • Keep PRDs focused (5-15 stories max)

Don't

  • • Don't skip quality gates to save time
  • • Don't give vague requirements ("make it better")
  • • Don't ignore critic feedback
  • • Don't combine unrelated features in one PRD