The Human in the Loop (you)

The Draft-to-Ready Journey

Most features go through a refinement loop before they're ready for implementation. Here's what that looks like:

Draft Refinement Tips

Clarifying Scope

A good PRD explicitly states boundaries. When refining with Planner, address these questions:

Practical Prompts for Planning Sessions

Here are copy-ready prompts for common planning scenarios:

When to Use Planner vs Builder

Two Operating Modes

Builder operates in two distinct modes depending on what you need. Choose the right mode to get the best results.

When to Use Each Mode

The Update Flow

Builder participates in a continuous improvement cycle. When specialist agents discover gaps or toolkit changes require project updates, the update flow keeps everything in sync.

Expected Outcomes

Here's what you can expect when working with Builder in each mode:

Practical Prompts for Builder Sessions

Here are copy-ready prompts for common Builder scenarios:

Advanced Reliability Features

Builder applies techniques from AI delegation research to ensure sub-agent work is verifiable, resumable, and recoverable — even under adverse conditions.

The Key Distinction: Toolkit vs Project

Understanding which level you're working at prevents confusion and keeps changes in the right place.

What Toolkit Changes

Toolkit owns the "meta" layer—the definitions that control how agents behave across all projects.

When to Use Toolkit vs Project Flows

The Pending-Updates Handoff Flow

Project agents can't modify toolkit files directly. Instead, they queue requests that @toolkit reviews and applies. This keeps toolkit changes intentional and coordinated.

Practical Prompts for Toolkit Sessions

Here are copy-ready prompts for common Toolkit scenarios:

Website Sync Modes

When Toolkit makes changes that affect documentation websites (like this one), it uses configurable sync modes to determine how updates are handled. The mode is resolved from your local overrides file, with a safe public default.

{
  "websiteSync": {
    "mode": "owner-managed",
    "projectId": "opencode-toolkit-website"
  }
}

Use this loop when building a new capability that requires planning, multiple stories, and structured implementation.

Use this loop for bug fixes, small improvements, and one-off tasks that don't warrant full planning.

Use this loop periodically to apply queued improvements and keep your toolkit evolving based on real project learnings.

Choosing the Right Loop

Rate Limit Handling

When the AI provider temporarily limits requests (HTTP 429), agents detect it immediately and pause gracefully instead of retrying in a loop.

Session Resumability

Builder tracks an activeWork object in builder-state.json throughout every session. This unified state model covers both PRD and ad-hoc work — if a session ends unexpectedly (power loss, network drop, or a browser close), the next session reads this state and offers to resume exactly where work stopped.

The analysis gate checkpoint (analysisCompleted) and probe status (probeStatus) are particularly important: they survive context compaction, ensuring Builder never starts implementing without your prior approval and live DOM confirmation — even in very long sessions where earlier conversation history has been summarized.

Tool Error Recovery

Transient errors — network timeouts, brief disconnects — are retried automatically once before escalating. Rate limits are never auto-retried; they always pause and notify you.

Commit Gate

Builder will not commit code for a completed story if the required post-change checks have not passed. This prevents half-finished work from landing in your codebase silently.

Root Cause Analysis Requirement

Before attempting any fix, agents must diagnose the root cause first. This prevents band-aid fixes that hide real bugs and create technical debt.

Instead, agents trace the problem systematically — checking for duplicate selectors, cascade conflicts, conditional branches, and data flow — before forming a hypothesis and making a targeted single-change fix.

Identity Lock Protection

When agents commit code, they verify the git identity matches your configured user to prevent commits under the wrong identity. This is especially important when working across multiple machines with different git configurations.

Use these prompts to plan features and create PRDs.

@planner I want to add [feature]. The main user goal is [what they accomplish]. Key constraints: [any limitations].

@planner Review the draft PRD at docs/prds/[name].json. Add edge cases for [specific area] and tighten the acceptance criteria.

@planner The PRD looks good. Mark it ready and copy to docs/prd.json.

@planner US-[number] has too many acceptance criteria. Break it into smaller, focused stories.

Use these prompts for PRD implementation and ad-hoc tasks.

@builder Implement docs/prd.json. Start with the first incomplete story.

@builder Continue with the PRD. Pick up the next incomplete story.

@builder Implement US-[number] from the current PRD.

@builder Fix [describe the bug]. It happens when [trigger condition].

@builder Add [small feature]. It should [expected behavior].

@builder Refactor [component/function]. Extract [what to extract] into a shared utility.

@builder Add unit tests for [file or component]. Cover the main flows and edge cases.

Use these prompts to evolve agents, skills, and scaffolds.

@toolkit Review pending updates. Show what's queued and let me decide what to apply.

@toolkit Create a skill for [pattern]. It should help agents [what it enables]. Reference [project] for examples.

@toolkit Update @builder to [behavior change]. This addresses [problem observed].

@toolkit Audit toolkit coverage for [project path]. What skills or agents are missing?

@toolkit Create a scaffold for [stack]. Base it on [existing scaffold] with [modifications].