---
name: execute-work-package
description: Execute a significant implementation unit (phase or major slice) using a gated subagent loop (blueprint -> gate -> execute -> digest) without creating new persistent artifacts.
license: MIT
compatibility:
  opencode: ">=0.1"
  claude-code: ">=1.0"
  cursor: ">=0.40"
  copilot: ">=1.0"
  codex: ">=0.1"
  windsurf: ">=1.0"
metadata:
  category: execution
  phase: implementation
  transport_options: [mcp, stateful, fresh]
---

# Skill: Execute Work Packet

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**: Fresh subagent implements and verifies
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.
- You want to offload implementation to a subagent without causing primary context bloat.
- You want predictable, reviewable execution with a single explicit gate.

If your phase implementation plan is still vague or unverified against the repo, run `author-and-verify-implementation-plan` first.

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 packet (phase or significant phase slice).
  - Owns Git operations (stage/commit/PR) unless explicitly delegated.
  - Updates plan/todo via `update-plan` as needed.

- **Subagent (implementer)**
  - Does execution only.
  - First returns a **step list**.
  - After approval, executes those steps and returns a **digest**.
  - Does not do Git operations.

## 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 any updates to `plans/**` (typically via `update-plan`).
- **implementer**: execution only (blueprint → execute → digest), no Git.
- **doc-explorer**: not used for this skill (unless you explicitly want docs/plan artifacts, in which case use the appropriate planning/doc skills).

### Why `docs/` and `plans/` matter here

- `plans/` provides the gated intent/DoD and references for what to implement.
- `docs/` (if present) provides curated inventories (modules/features/symbols) so the subagent does not rediscover everything.

### Transport

This skill supports three transport mechanisms. **If l4l-oci MCP tools are available** (check: do you have `create_handle`, `generate_blueprint`, `submit_gate`, `execute_handle`, `get_digest` tools?), **always use Option A.** Only fall back to B/C if MCP is not configured.

#### Pre-flight: Ensure l4l-oci server is running

Before using Option A, run the bundled helper:

```bash
skills/execute-work-package/scripts/start-l4l-oci.sh
```

Behavior:
- Uses `L4L_OCI_ROOT` (default: `$HOME/git/l4l-oci`)
- Starts `python -m l4l_oci` in background if needed
- Waits for MCP `health` to return `ok`
- Exports `L4L_OCI_DEFAULT_MODEL=qwen-openrouter` for startup unless already set

Prerequisites:
- `OPENROUTER_API_KEY` (or `QWEN_API_KEY`) must be available in the environment

#### Option A: MCP via l4l-oci (Default)

Use the l4l-oci MCP server. The primary calls MCP tools directly — no Agent spawning needed:

1. `create_handle(project_root)` → returns `handle_id`
2. `generate_blueprint(handle_id, prompt)` → async; poll with `get_status(handle_id)` until complete
3. `get_blueprint(handle_id, format="markdown")` → review the Execution Blueprint
4. `submit_gate(handle_id, decision="accept"|"reject", notes=...)` → explicit gate
5. `execute_handle(handle_id)` → async; poll with `get_status(handle_id)` until complete
6. `get_digest(handle_id, format="markdown")` → returns Execution Digest
7. `cleanup_handle(handle_id)` → optional cleanup

Benefits: state persistence across restarts, model decoupling (cheap Sub-LLM), scope enforcement, iterative blueprint refinement.

Additional tools: `health()` (service health check), `list_handles()` (list all active handles).

#### Option B: Stateful Subagent (OpenCode)

Original design using `resumeSessionId` to maintain subagent state between BLUEPRINT and EXECUTE:

- BLUEPRINT and EXECUTE use the **same** session (resumed via `resumeSessionId`)
- The subagent retains context from the BLUEPRINT phase

This is the native OpenCode pattern.

#### Option C: Fresh Agent (Claude Code / Cursor / Copilot)

BLUEPRINT and EXECUTE use **separate** Agent invocations (not SendMessage to resume):

- **BLUEPRINT Agent**: spawned with `mode: auto`, returns the step list, then terminates.
- **EXECUTE Agent**: spawned as a **new** Agent with the approved step list baked into the prompt. This avoids unreliable SendMessage-based resumption of idle agents.

The EXECUTE prompt must include the full approved step list and all references — the agent has no memory of the BLUEPRINT agent's context.

#### Platform Decision Table

| Platform | Recommended | Fallback |
|----------|------------|----------|
| Claude Code | Option A (MCP) | Option C (Fresh Agent) |
| Cursor | Option A (MCP) | Option C (Fresh Agent) |
| Copilot | Option A (MCP) | Option C (Fresh Agent) |
| Codex | Option C (Fresh Agent) | — |
| Windsurf | Option A (MCP) | Option C (Fresh Agent) |
| OpenCode | Option B (Stateful) | Option A (MCP) |

---

## Protocol

### 0) Primary inputs (for any work packet)

Before delegating:

- Ensure the work packet is already gated (scope/DoD decided).
- Provide an explicit **task statement** plus **references** to the relevant planning artifacts.
  The subagent should read these references itself (the primary does not need to paste content).
  Recommended references:
  - `plans/<plan>/plan.md`
  - `plans/<plan>/phases/phase-N.md`
  - `plans/<plan>/implementation/phase-N-impl.md`
  - `plans/<plan>/todo.md` (optional)
- 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 a **Verify Command** if one is already decided.
  If not, the subagent proposes exactly **one** verify command in the BLUEPRINT (to be gated by the primary).

### 1) MODE: BLUEPRINT (Execution Blueprint)

> **Option A (MCP):** Call `create_handle(project_root)`, then `generate_blueprint(handle_id, prompt)`. Poll `get_status(handle_id)` until complete, then `get_blueprint(handle_id, format="markdown")` to review.

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

#### 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 (new Agent)

> **Option A (MCP):** Call `submit_gate(handle_id, decision="accept")` then `execute_handle(handle_id)`. Poll `get_status(handle_id)` until complete, then `get_digest(handle_id, format="markdown")` for the digest.

Primary spawns a **new** `implementer` Agent with a prompt based on `tpl-implementer-execute-prompt.md`. The prompt includes the full approved step list, all references, and the verify command. Do NOT use SendMessage to resume the BLUEPRINT agent — spawn a fresh Agent instead.

#### Invariant: MODE lock

The execute prompt MUST start with a clear mode indicator:

- `MODE: EXECUTE`

and MUST include the approval token.

> **Option A (MCP):** Skip the Agent spawn above. Call `submit_gate` → `execute_handle` → poll `get_status` → `get_digest` directly via MCP tools.

### 3) Digest back to Primary

Subagent responds with a compact digest:

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

### 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:** If additional testing is needed, spawn a new subagent with specific test instructions and relevant references. 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.

Then:

- Updates `plans/<plan>/todo.md` and phase status via `update-plan`
- Commits / creates PR **only** when explicitly requested by the user

Optional but recommended (Primary):

- Before execute: capture baseline via `git status` / `git diff --name-only`
- After execute: confirm changes exist via `git diff --stat`

---

## 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.

#### Mode: BLUEPRINT

In BLUEPRINT mode, the subagent must NOT:

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

### Digest Contract (Subagent -> Primary)

Subagent MUST return only:

- **Outcome**: succeeded | failed
- **Edits**: list of files changed + 1-line note each
- **Verify**: command + exit code + (if failed) small excerpt
- **Next**: 1–3 bullets (or “ready for Primary Git/commit”)

#### 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).
- Skill-first: when this skill is invoked, follow its MODE + output contracts before doing anything else.
- Keep verification minimal: **one** explicit verify command unless the work packet DoD requires more. The verify command must **exercise the changed behavior** (e.g., run relevant tests, hit the affected endpoint, trigger the modified flow) — not just compile, lint, or type-check.
- No raw diffs or long logs in responses.
- If verify fails: apply **minimal, targeted fixes** (no refactors) and re-run verify. If still failing or 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.

---

## Coding Standards

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

1. **No hardcoded defaults.** Use configuration files or environment variables for values that may change across environments.
2. **Analyze root cause.** Don't patch symptoms. Understand why something is broken before changing code.
3. **Minimal changes.** Only touch what the work packet 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