Execute Work Package

Skill: Execute Work Package

This skill standardizes execution/implementation once planning is gated.

It is a small, repeatable protocol:

1. BLUEPRINT: Subagent returns an Execution Blueprint (step list)
2. GATE: Primary approves (primary-internal)
3. EXECUTE: Subagent implements and verifies (same task_id)
4. DIGEST: Subagent returns a compact digest (no raw logs/diffs)

This skill deliberately does not create new persistent artifacts in docs/ or plans/.

When to Use

Use this skill when:

• A plan/phase (or a major slice of a phase) already has a clear DoD and verification approach; or
• A self-contained work package has an inline gated brief with its task, DoD, constraints, and approved broad/full final verification.
• You want to offload implementation to a subagent without causing primary context bloat.
• You want predictable, reviewable execution with a single explicit gate.

If persistent phase work has a vague or unverified implementation plan, run author-and-verify-implementation-plan first. Do not create a persistent plan solely because a bounded inline work package is significant or non-trivial.

Multi-phase ordering: When a plan has multiple phases, create all implementation plans first (via author-and-verify-implementation-plan), then execute phases sequentially — one at a time. Do not alternate between planning and executing per phase; the cross-phase view catches conflicts early and sequential execution avoids errors from interdependencies.

Do not use this skill to:

• (Re-)do planning (scope, risks, alternatives) — that is Primary work.
• Generate documentation/planning artifacts — use generate-docs, create-plan, update-plan, update-docs.

Execution Model

Roles

• Primary (maintainer)

  • Owns scope/DoD/risk decisions and gating.
  • Chooses the work package (phase, significant phase slice, or self-contained inline brief).
  • Owns Git operations (stage/commit/PR) unless explicitly delegated.
  • Updates plan/todo via update-plan as needed when a persistent plan exists.

• Subagent (implementer)

  • Does execution only for exactly one phase/work package in a fresh session.
  • First returns a step list.
  • May add a concise optional Package Sizing Note when natural execution slices exist, but never splits scope or chooses a slice; the Primary decides whether to approve the full package or issue a smaller fresh package.
  • After approval, executes those steps and returns a digest.
  • Uses retriever by default for separable evidence collection while retaining ownership of the Blueprint, edits, and verification.
  • Directly reads scoped source and compact targeted evidence, but keeps uncurated bulk evidence out of its context. It uses reliable focused filtering when sufficient and retriever for complete raw or coherent multi-file evidence.
  • BLUEPRINT remains command-free. In EXECUTE, potentially verbose output is spooled to a predictable path under /tmp/opencode/; the immediate context receives only path, command, exit status, and compact metadata/evidence.
  • Retires after the digest, subject only to the same-package review-fix exception under Statefulness; another phase/work package starts with a fresh implementer.
  • Does not do Git operations.
  • Checkpoints after approved Blueprint steps or bounded parts of a large step, consulting the latest possibly lagged telemetry before deliberately starting another context-heavy unit.
  • Uses browser-walkthrough for approved automated browser acceptance; agent-observed walkthroughs belong to a Delegate, while user-attended walkthroughs remain Primary-coordinated and may use a retained Delegate session for bounded browser segments.

Routing Matrix (Who does what)

• Writes: code files in the target repository (working tree changes) and runs verification commands.
• Does NOT write: plans/** or docs/** artifacts.
• Primary: owns gating/approval, Git operations, and, when a persistent plan exists, updates to plans/** (typically via update-plan).
• implementer: execution only (blueprint → execute → digest), no Git.
• Session boundary: one fresh implementer per phase/work package; its BLUEPRINT and EXECUTE calls share a session. Post-digest reuse is limited to the review-fix exception under Statefulness.
• retriever: default leaf for separable evidence collection by the implementer; no edits, decisions, or artifact ownership.
• browser walkthroughs: automated acceptance is Implementer-owned during EXECUTE, agent-observed walkthroughs route to a Delegate, and user-attended walkthroughs are Primary-coordinated with optional retained-Delegate execution; no browser-specific persona is created.
• doc-explorer: not used for this skill (unless you explicitly want docs/plan artifacts, in which case use the appropriate planning/doc skills).

Authority and navigation

• plans/ provides gated intent/DoD and references when the package belongs to a persistent plan lifecycle.
• Otherwise, the inline gated work-package brief is authoritative and supplies the task, DoD, constraints, and final verification.
• docs/ (if present) provides curated inventories (modules/features/symbols) so the subagent does not rediscover everything.

Scope and Specification Boundary

Gold-plating is work not required by an explicit user requirement, gated scope/DoD, or a concrete existing invariant necessary for the requested behavior to function. It includes invented product rules or guardrails, speculative configurability, generalized abstractions or future-proofing, and exhaustive treatment of hypothetical edge cases. Do not invent product, policy, or operational rules or guardrails, and do not implement every conceivable edge case.

Minimal means the smallest complete solution, never an incomplete implementation: the requested behavior must work, affected real paths must integrate, applicable existing invariants must be preserved, and the approved verification must pass. Functionality and correctness come first; scope discipline is not permission to omit necessary work or obstruct progress.

Stop only when missing specification creates a genuine user-owned fork that changes observable behavior, scope/DoD, policy or rules, configuration behavior, or acceptance. Resolve codebase-answerable questions and choose local, reversible technical details that do not change observable behavior. An Implementer cannot ask the user: in BLUEPRINT or EXECUTE, return the exact blocking decision to the Primary and stop before dependent work rather than fabricating a product decision. After user input changes or completes the authority, require an updated/re-approved gate as appropriate before dependent execution.

Required values that users or operators may reasonably change across environments—including URLs, addresses, ports, timeouts, and similar runtime values—belong in the project's existing configuration location or pattern, not in hidden code defaults or fallbacks. Do not invent a new configuration system or extra options unless gated scope requires them. If a required configurable value has no established project configuration location, or its behavior is a user-owned choice, return the exact decision to the Primary and stop dependent work. Fixed protocol or domain constants authorized by requirements do not become configurable merely to appear flexible.

Statefulness

The protocol relies on continuing the subagent in the same session via the same task_id:

• Call 1 (task): request "Step List only" → receive Blueprint
• Primary reviews and approves (internal gate)
• Call 2 (task with same task_id): request "Execute approved steps" → receive Digest

This reuse remains mandatory even when a fresh lean session would normally be preferred: EXECUTE depends on the retained Blueprint inspection and explicit approval context.

The execution protocol ends with that package's digest and the Implementer retires by default. Narrow exception: the Primary may resume the same session through review-fix for explicitly accepted, evidence-backed defects of the same completed package, when its retained review/diagnosis context/output is correct and sufficient. That skill owns authorization (an explicit Primary instruction naming accepted defects and scope, not an approval token), eligibility/fallback, verification, and the one-pass digest-and-stop contract. This preserves secured evidence; it does not reopen EXECUTE or permit another phase/package or indefinite continuation. A new phase/work package always starts with a fresh Implementer.

CRITICAL: Two separate task calls required.

BLUEPRINT and EXECUTE are always two separate task tool invocations. The primary must:

1. Make Call 1 (task(subagent_type="implementer", prompt="MODE: BLUEPRINT ...")) and wait for the response.
2. Review the Blueprint, then gate/approve internally.
3. Make Call 2 (task(task_id="<from call 1>", subagent_type="implementer", prompt="MODE: EXECUTE ...")) as a new, separate tool call.

Anti-pattern (WRONG): Combining Blueprint and Execute in a single task call, or sending the Execute prompt before receiving the Blueprint response. The subagent session is still in BLUEPRINT mode until the first call completes — any Execute instructions in the same call will be ignored.

Platform-specific session resumption

The two-call pattern requires session resumption — continuing a subagent in the same conversation context. The mechanism differs by platform:

Note: In Claude Code v2.1.63+, the Task tool was renamed to Agent (the old name still works as an alias). The SendMessage tool is only available when Agent Teams are enabled.

Protocol

0) Primary inputs (for any work package)

Before delegating:

• Ensure the work package is already gated (scope/DoD decided).
• Provide exactly one authoritative scope source:
  • Persistent plan references: an explicit task statement plus the relevant planning artifacts. The subagent reads these references itself (the primary does not paste their contents). Recommended references:
    • plans/<plan>/plan.md
    • plans/<plan>/phases/phase-N.md
    • plans/<plan>/implementation/phase-N-impl.md
    • plans/<plan>/todo.md (optional)
  • Inline gated work-package brief: task, DoD, constraints, and approved broad/full final verification. No plans/ artifact is required.
• If project documentation exists, also provide references to it so the subagent can use the curated inventories (symbols, modules, features) instead of rediscovering everything from scratch:
  • docs/overview.md (optional)
  • docs/modules/*.md (optional)
  • docs/features/*.md (optional)
• Provide the approved broad/full Verify Command if one is already decided. If not, the subagent proposes exactly one verify command in the BLUEPRINT (more only when the work package DoD genuinely requires them), to be gated by the primary.

1) MODE: BLUEPRINT (Execution Blueprint)

Primary delegates to implementer with a prompt based on tpl-implementer-preflight-prompt.md.

Gate: Primary reviews the step list and either:

• Approves (GO)
• Requests revision (feedback)
• Aborts and replans

When the Blueprint contains an optional Package Sizing Note, it is advisory only. The Primary either approves the complete package or aborts and issues a smaller fresh work package. The Implementer must not split the approved scope, select a slice, or emit a hard FIT/SPLIT state.

Invariant: explicit approval token

Primary provides an explicit approval token before execution (primary-internal gate). Example:

• APPROVE-WP1

If the user requests changes, the step list must be revised and re-approved with a new approval token.

2) Execute (same task_id)

Primary resumes the same subagent task_id and instructs it to execute the approved steps (see tpl-implementer-execute-prompt.md).

Invariant: MODE lock

The execute resume prompt MUST start with a clear mode indicator:

• MODE: EXECUTE

and MUST include the approval token.

3) Digest back to Primary

Subagent responds with a compact digest:

• Outcome (succeeded/failed/BLOCKED)
• Files changed (paths)
• Verification result (command + exit)
• If failure: only a small, relevant excerpt (no full logs)

Owning verification does not imply consuming raw verbose output directly. The implementer spools complete potentially verbose output under /tmp/opencode/, then uses a reliable focused filter or asks retriever to analyze the raw path with a focused question. Spools support same-machine continuation after an agent or process interruption, not reboot durability. Numeric tool truncation is a safety net, not the routing rule.

The digest closes this execution pass and retires the Implementer subject only to the review-fix exception under Statefulness.

4) Primary post-processing

Read the digest carefully. The subagent's verification result determines next steps:

• Verification passed: Spot-check with git diff --stat to confirm expected changes. Do not re-run the full test suite yourself – the subagent already did.
• Verification failed or incomplete: Decide whether the digest identifies accepted defects of the completed package eligible for the review-fix exception under Statefulness; if so, explicitly instruct that bounded remediation. Otherwise issue the unfinished work as a fresh Implementer package. If source context/output is faulty, insufficient, or unavailable, include a finding-source pointer as a hint in the fresh task, not claimed inherited context. Do not run large test suites in the Primary session.
• BLOCKED / no verification ran: Decide whether to provide missing input and re-delegate, or run a targeted check yourself.

If the Implementer began work but the digest is empty or missing, treat the call as interrupted rather than successful. Do not resume the bloated session. Use this recovery sequence:

1. Call checkpoint_path with the failed Implementer task_id to select its JSONL log.
2. Inspect that log and identify the last attempted and next announced units.
3. Inspect the current working tree without discarding or overwriting partial changes.
4. Map the logged units and current edits to the approved Blueprint, distinguishing completed, attempted, and remaining work.
5. Issue the unfinished bounded scope as a smaller fresh work package; its Implementer inspects current state rather than blindly replaying the original package.

This uses the existing Blueprint, checkpoint log, and working tree. It creates no new handoff format, digest outcome, partial state, or recovery schema.

Then:

• If a persistent plan exists, updates plans/<plan>/todo.md and phase status via update-plan.
• Commits / creates PR only when explicitly requested by the user

Optional (Primary):

• Before execute: capture baseline via git status / git diff --name-only

The after-execute confirmation is not optional: it is the git diff --stat spot-check required in the Verification passed branch above.

Output Contracts

Step List Contract (Subagent -> Primary)

Subagent returns an Execution Blueprint in the format of tpl-execution-blueprint.md.

The blueprint is expected to be concrete (file paths and/or symbol/component targets), not a restatement of plan text.

It may contain the template's optional Package Sizing Note only when natural execution slices would help the Primary gate a context-heavy package. The note is concise and non-binding; it proposes cuts but neither changes scope nor chooses one.

Mode: BLUEPRINT

In BLUEPRINT mode, the subagent must NOT:

• apply patches
• run commands
• claim that code was changed

If a genuine user-owned fork blocks dependent steps, return the Blueprint with the exact blocking decision and no dependent steps. The Primary obtains user input and supplies an updated/re-approved gate before execution.

Digest Contract (Subagent -> Primary)

Subagent MUST return only:

• Outcome: succeeded | failed | BLOCKED
• Edits: list of files changed + 1-line note each
• Verify: command + exit code + (if failed) small excerpt
• Environment (optional): <category>: <symptom> when an environment, harness, or tooling issue blocked or degraded work; otherwise omit
• Next: 1–3 bullets (or “ready for Primary Git/commit”)

For a user-owned blocker, use Outcome: BLOCKED, make no dependent edits, and put the exact decision needed from the Primary under Next. User input that changes or completes scope requires an updated/re-approved gate before work continues.

Mode: EXECUTE

In EXECUTE mode, the subagent must:

• implement changes (typically via patch/apply_patch)
• run the verify command (via bash)
• if neither happened: return BLOCKED with a concrete reason

Rules

• Subagent must not run Git operations (commit, rebase, push).
• Start a fresh Implementer for each phase/work package. Reuse its task_id for that package's BLUEPRINT → EXECUTE pair, then retire it subject only to the same-package review-fix exception under Statefulness.
• Skill-first: when this skill is invoked, follow its MODE + output contracts before doing anything else.
• Keep the Blueprint to one explicit approved broad/full verify command unless the work package DoD genuinely requires more. It must exercise the changed behavior (for example, run relevant tests, hit the affected endpoint, or trigger the modified flow), not just compile, lint, or type-check.
• During EXECUTE, checkpoint after each approved Blueprint step or a bounded part of a large step. Telemetry may lag the active turn, and unknown remains unknown. Base capacity and cost decisions only on reported input usage and input K-tokens. Across providers, approximately 205k input tokens are a soft planning signal; at or above approximately 272k, stop expanding the task and use the remaining budget for a coherent checkpointed digest or handoff. The 372k rejection boundary is emergency headroom, not a working target.
• During implementation and fixing, run the smallest targeted tests that exercise or reproduce the changed or problematic behavior. Do not run the approved broad/full command after every change or use it as the first iterative diagnostic step when a targeted test is known or can be identified.
• When browser behavior is in scope, load browser-walkthrough and use available Playwright MCP/browser tools without provisioning or configuring Playwright. Keep its automated acceptance subordinate to the approved Blueprint and final verify command.
• Run the approved broad/full command once only when implementation is ready, as the final gate. If that final gate exposes a failure, return to targeted diagnosis, fix, and retest. Only after targeted tests pass may the broad/full final gate run again. Never weaken or omit the final broad gate.
• No raw diffs or long logs in responses.
• If targeted verification or the final gate fails, apply minimal, targeted fixes (no refactors) under the staged sequence above. If a larger change is required, stop and report a digest with a minimal relevant excerpt.
• If the step list must change during execution: stop and ask Primary for a new gate.
• Never fabricate a product decision in BLUEPRINT or EXECUTE. For a genuine user-owned fork, report the exact blocking decision to the Primary and stop dependent work.

Coding Standards

These apply to all code written during execution – by the implementer subagent or the primary.

1. No hidden configurable defaults. Required runtime values that users or operators may reasonably change across environments—including URLs, addresses, ports, timeouts, and similar values—use the project's existing configuration location or pattern, not embedded code defaults or fallbacks. Do not invent a configuration system or extra options unless gated scope requires them; fixed authorized protocol/domain constants remain fixed.
2. Analyze root cause. Don't patch symptoms. Understand why something is broken before changing code.
3. Minimal changes. Only touch what the work package requires. Don't refactor adjacent code you weren't asked to change.
4. Preserve existing patterns. Match the conventions already established in the codebase (naming, structure, error handling).
5. No silent failures. Don't swallow errors or add fallbacks that hide problems. If something fails, it should be visible.
6. Respect the dependency boundary. Don't introduce new dependencies without explicit approval from the primary/user.

If docs/coding-standards.md exists in the target repo, read and follow it as well – project-specific standards take precedence.

Templates

• tpl-implementer-preflight-prompt.md — Primary -> Subagent (MODE: BLUEPRINT) prompt
• tpl-implementer-execute-prompt.md — Primary -> Subagent (MODE: EXECUTE) prompt (same task_id)
• tpl-execution-blueprint.md — canonical blueprint format (step list)
• tpl-execution-digest.md — canonical digest format