---
name: execute
description: |
  Execute a plan with cabinet member checkpoints. Reads the plan, activates
  relevant cabinet members, then implements step by step with checkpoint
  reviews. This is a skeleton skill using the phases/ directory pattern.
  Use when: "execute this plan", "implement this", "/execute".
related:
  - type: skill
    name: validate
  - type: file
    path: .claude/cabinet/checkpoint-protocol.md
    role: "The cabinet checkpoint mechanism — read and followed at Checkpoints 1/2/3"
  - type: file
    path: .claude/skills/execute/phases/load-plan.md
    role: "Project-specific: where plans live and how to read them"
  - type: file
    path: .claude/skills/execute/phases/cabinet.md
    role: "Project-specific: which cabinet members to activate for execution"
  - type: file
    path: .claude/skills/execute/phases/verification-tools.md
    role: "Project-specific: tools for checking acceptance criteria"
  - type: file
    path: .claude/skills/execute/phases/validators.md
    role: "Project-specific: what validation to run"
  - type: file
    path: .claude/skills/execute/phases/commit-and-deploy.md
    role: "Project-specific: how to persist and deploy changes"
  - type: file
    path: .claude/skills/execute/phases/post-impl-checklist.md
    role: "Instruction: surface targeted QA checks from qa-dimensions.yaml before CP3"
  - type: file
    path: cabinet/_briefing.md
    role: "Project identity and configuration"
argument-hint: "plan reference — e.g., 'act:abc123' or plan title"
---

# /execute — Plan Execution with Cabinet Checkpoints

## Arguments

If `$ARGUMENTS` is provided, use it to identify which plan to execute.
Match against pib-db action fids (e.g., "act:abc123") or search action
text for a title match. If a unique match is found, load that plan. If
multiple matches, present them and ask the user to pick. If no match,
tell the user and ask which plan to execute.

Empty arguments: Ask the user which plan to execute (default workflow).

## Purpose

Execute a plan with cabinet members providing checkpoint reviews along
the way. This is the inner loop: take one plan and implement it with
guardrails. The cabinet checkpoints catch issues that code review alone
would miss: security gaps, data
integrity violations, boundary condition failures.

This is a **skeleton skill** using the `phases/` directory pattern. The
orchestration (checkpoints, escalation, verification protocol) is generic.
Your project defines the specifics in phase files under `phases/`.

### Phase File Protocol

Phase files have three states:

| State | Meaning |
|-------|---------|
| Absent or empty | Use this skeleton's **default behavior** for the phase |
| Contains only `skip: true` | **Explicitly opted out** — skip this phase entirely |
| Contains content | **Custom behavior** — use the file's content instead |

The skeleton always does something reasonable when a phase file is absent.
Phase files customize, not enable. Use `skip: true` when you actively
don't want a phase to run — not even the default.

## Why This Matters

Without structured execution, the common failure mode is: implement,
compile, commit, mark done. The feature looks complete but acceptance
criteria were never verified, the pre-commit sweep never happened,
and the edge case that a boundary-man cabinet member would have
flagged ships to production.

The checkpoint protocol catches issues at three scales:
1. **Pre-implementation** — is the plan safe to start?
2. **Per-file-group** — do these changes look right in isolation?
3. **Pre-commit** — do all changes work together?

Each checkpoint is a chance to stop before the cost of fixing goes up.

## Workflow

### 0. Worktree-Invocation Contract (core — runs before plan load)

Running `/execute` from a mux/linked git worktree is the **normal case**,
not an error. **Read `.claude/cabinet/worktree-invocation-contract.md` and
follow it** — detect a linked worktree, sync main *into* it before reading
plan/code state, and resolve every completion artifact to the MAIN checkout.
Two points specific to `/execute`:

- **`/execute` merges at close-out, not before.** Finished worktree work is
  merged into main by the lane itself (the standing convention: Claude
  merges worktree → main; a qa-handoff describes work ALREADY on main).
  Step 0 only syncs main *into* the worktree (so the staleness guard and
  the checkpoints read current state); the merge OUT happens once, at
  Step 8's close-out, via `/qa-handoff`'s merge-now recipe.
- **Sync conflict → HALT the whole skill** per the contract (don't
  auto-resolve, don't implement on a half-synced tree); surface the
  conflicted-worktree recovery and stop.

On the main checkout the detection no-ops: artifacts resolve to cwd (which
IS main) and no qa-handoff is filed — `/execute` behaves exactly as before.

### 1. Load the Plan

Read `phases/load-plan.md` for where your project stores plans and how
to read them (action notes, markdown files, issue tracker, etc.).

**Default (absent/empty):** Expect the plan to be provided in
conversation or referenced by the user. Ask which plan to execute if
it's not clear.

Identify from the plan:
- **Implementation steps** — what to do
- **Surface area** — which files
- **Acceptance criteria** — how to confirm it works
- **Plan type** — code plan (has file changes) or walkthrough plan
  (manual setup, configuration, purchase)

#### Load full spec and write breadcrumb

After identifying the action to execute:

1. Call `pib_get_action` with the action's fid to get complete notes.
   If unavailable, use `pib_query` with:
   `SELECT * FROM actions WHERE fid = '<fid>'`
2. Read the FULL notes. Do not proceed if notes appear truncated.
3. Create the verification breadcrumb:

```bash
# Resolve the MAIN checkout (worktree-invocation contract, Step 0): a
# worktree's .claude/verification/ is gitignored and lost on cleanup, and the
# completion-gate hook READS breadcrumbs from MAIN. On the main checkout $MAIN
# is the cwd, so this line is correct in both places.
MAIN="$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")"
mkdir -p "$MAIN/.claude/verification"
cat > "$MAIN/.claude/verification/<fid>.json" << 'BREADCRUMB'
{
  "fid": "<fid>",
  "spec_read": true,
  "spec_read_at": "<ISO timestamp>",
  "ac_verified": false,
  "verification_summary": null,
  "deviations": []
}
BREADCRUMB
```

The completion hook blocks marking this action done without this
breadcrumb. Do NOT skip this step.

#### Walkthrough Plans (non-code)

If the plan has no code changes, skip the file-group implementation
loop (Steps 4-5) and instead:
1. Present each step conversationally
2. Walk the user through each step, confirming completion
3. Help troubleshoot if something doesn't work as expected
4. Verify acceptance criteria as each step completes

### 2. Activate Cabinet Members

Read `phases/cabinet.md` for which cabinet members to activate during
execution, any always-on cabinet members, and any project-specific rules.

**Default (absent/empty):** Use `.claude/skills/_index.json` to select
cabinet members whose convening criteria match:
- **`standingMandate` includes `"execute"`** — always included
- **File patterns** — any file in the plan's surface area matches
- **Topic keywords** — any keyword in the plan description matches

Fall back to reading `cabinet-*/SKILL.md` if the index is missing.

Err toward inclusion. A cabinet member that activates unnecessarily costs
a few seconds; one that doesn't activate when needed costs rework.

Prepare reusable briefing for agent prompts: read `.claude/cabinet/_briefing.md` once and
keep the essential facts ready to paste into each agent's prompt. When a
member has a `directives.execute`, include it in the agent prompt to
sharpen their focus during execution checkpoints.

If no cabinet members exist in the project, skip all checkpoint steps
(3, 4b, 5) and execute the plan directly. Checkpoints add depth, not
structure.

### 3. Checkpoint 1: Pre-Implementation Review

Before writing any code, **read `.claude/cabinet/checkpoint-protocol.md`
and follow it, scoped to `pre-impl`.** The protocol covers which members
to spawn, what each receives, the verdict shape, and the escalation
rules. The reviewed material at this scope is the plan text and the list
of files that will change — the question each member answers is "is this
plan safe to start?"

When you surface a checkpoint to the operator for a proceed/drop/override
decision, brief it in **plain English** — what each concern means and
what's at stake in the call — not a raw dump of member findings with
paths and symbols (see `cabinet/skill-output-conventions.md` §9). The
full findings stay available; the decision framing is what you lead with.

### 4. Implement (File Group by File Group)

Group the plan's implementation steps by logical file groups
(e.g., "backend API changes", "frontend components", "types and schemas").

For each group:
1. Make the changes
2. **Post-change verification:**
   - **After component extraction or file splitting:** Immediately run
     the project's type checker (`tsc --noEmit`, `mypy`, `pyright`, etc.)
     before writing any further code. Extraction frequently orphans
     imports — the type checker catches this before it compounds.
   - **Before using unfamiliar UI component props:** Read the component's
     `.d.ts` file from `node_modules/<package>/` or check the type
     definitions. Never guess prop names from memory of prior framework
     versions — prop APIs change between major versions and guessing
     wastes build cycles.
3. **Checkpoint 2: File Group Review** — if cabinet members are active,
   **read `.claude/cabinet/checkpoint-protocol.md` and follow it, scoped
   to `this file group`.** The reviewed material is the git diff for this
   file group plus plan context; member selection narrows to those
   matching the changed files.
4. If all continue, move to the next group

File-group granularity keeps reviews focused. A cabinet member reviewing
3 changed files gives better feedback than one reviewing 30.

### 4b. Change-Impact Checklist (Instruction Phase)

Read `phases/post-impl-checklist.md` and follow it. This phase runs
after the implementation loop and before the pre-commit sweep. It
classifies the diff against the project's QA dimensions config and
surfaces targeted checks as pre-context for the CP3 cabinet members.

If the phase file is absent or the project has no `qa-dimensions.yaml`,
this step is a silent no-op.

### 5. Checkpoint 3: Pre-Commit Sweep

After all implementation is complete, **read
`.claude/cabinet/checkpoint-protocol.md` and follow it, scoped to
`pre-commit`.** The reviewed material is the full git diff of all changes
plus plan context. As the protocol notes for this scope, earlier
"continue" concerns are re-checked — a concern that was minor in
isolation may be significant in the aggregate.

### 6. Verify Acceptance Criteria (QA Gate — MANDATORY)

Walk through **every** acceptance criterion in the plan, one by one.

Read `phases/verification-tools.md` for what tools your project has
for verifying criteria.

**Default (absent/empty):** Use whatever tools are available in the
environment. For [auto] criteria, run the command. For [manual] criteria,
attempt verification with available tools before deferring to the user.

For each criterion, determine its category and verify accordingly:

- **[auto] criteria** — RUN the check. Execute the command, curl the
  endpoint, run the test. Record the actual output.

- **[manual] criteria** — Use whatever verification tools are available
  (preview tools, browser automation, test runners). **Use tools before
  deferring to the user.** Only defer when tools genuinely cannot verify
  the criterion.

- **[deferred] criteria** — Note them as not yet verifiable. This
  category is for criteria that depend on infrastructure not yet
  available. It is NOT a bucket for checks you could do with tools.

**Report format:**
```
## AC Verification
Criteria: N total (X auto, Y verified-via-tools, Z needs-user, W deferred)
- [pass] [criterion] — verified: [actual result]
- [pass] [criterion] — verified via tools: [evidence]
- [user] [criterion] — needs-user: [why tools can't verify]
- [wait] [criterion] — deferred: [why not testable now]
- [FAIL] [criterion] — expected [X], got [Y]
```

**If any [auto] criterion fails: STOP.** Fix the issue before proceeding.
Do not mark the work item complete with failing AC.

#### Update verification breadcrumb

After verifying all ACs, update the breadcrumb:

```bash
# Same MAIN checkout as Step 1 (worktree-invocation contract).
MAIN="$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")"
cat > "$MAIN/.claude/verification/<fid>.json" << 'BREADCRUMB'
{
  "fid": "<fid>",
  "spec_read": true,
  "spec_read_at": "<original timestamp>",
  "ac_verified": true,
  "ac_verified_at": "<ISO timestamp>",
  "verification_summary": "<1-2 sentence summary>",
  "deviations": ["<any deviations, or empty array>"]
}
BREADCRUMB
```

If deviations is non-empty, do NOT mark action complete. Address
deviations or escalate to user first.

### 7. Validate and Commit

After AC verification passes:

**a. Run validators.** Read `phases/validators.md` for what validation
to run.

**Default (absent/empty):** Run whatever the project's `/validate` skill
does. If no validate skill exists, at minimum check that the code
compiles and lints cleanly.

If validation fails, fix issues and re-run Checkpoint 3 for the fix.

**b. Commit and deploy.** Read `phases/commit-and-deploy.md` for how
your project persists and deploys changes.

**Default (absent/empty):** Commit with a clear message describing the
implementation. Don't push or deploy unless the phase file says to —
deployment strategy is project-specific.

### 8. Close the Loop

Mark the work item as complete (if your project has a work tracker) —
"done" = implemented + committed + breadcrumb-on-main, the same milestone
`/execute-group` uses. **In a worktree, mark done only after the close-out
below succeeds** (merge landed on main + handoff filed — or, without
watchtower, the loud no-handoff note surfaced; or the explicitly-gated
merge-pending handoff filed): a HALTed merge leaves the action open with a
loud note — a closed action must never point at unmerged work. Run debrief
if this was a full session. At minimum, ensure the work is committed,
validated, and verified before considering it done.

#### Worktree close-out: merge first, then file the qa-handoff (worktree only)

When Step 0 detected a linked worktree, `/execute` has committed to the
worktree branch. Close out **merge-first** (act:3d1ac2b7 — a qa-handoff
describes work ALREADY on main; the history of why the old merge-pending
default was retired lives in `/qa-handoff`'s "Merge state" section):

1. **Re-sync and re-gate.** Sync main into the worktree once more (the
   contract's §2 — conflict HALTs) and, if the sync brought new commits,
   re-run the proportionate gate so what merges is what was tested.
2. **Merge + push via `/qa-handoff`'s merge-now recipe** (Step 1's fork —
   the single hardened recipe: dirty/wrong-branch preconditions on the
   MAIN checkout, merge --no-edit, push, post-merge ancestry re-verify,
   re-derived post-merge `merged_commit`). Do NOT prompt for the fork —
   merge-now IS the close-out's default. **Every failure HALTs loudly**:
   name the failed step, leave the action open, file nothing. Never
   launder an internal failure (conflict, red gate, rejected push) into a
   merge gate.
3. **Build the payload per `/qa-handoff` Step 4** with
   `merge_state: "merged"` and the post-merge sha (what merged, what the
   worktree could not runtime-verify, what hangs on the next step).
4. **File per `/qa-handoff` Step 5 and dispatch per Step 6** — dispatch
   runs unconditionally on the merged path (`createItem` verifies the sha
   is really an ancestor of `origin/<main>`; merged-by-construction).
   Print the id: "Merged <branch> at <short-sha>; filed qa-handoff
   dec-XXXX — dispatched to the QA station." The "file nothing" HALT rule
   above applies BEFORE this step; if filing succeeded and only the
   dispatch call failed, the handoff is already durable in the inbox
   (`/briefing` resurfaces it) — say so loudly and note the badge may not
   light until `mux qa dispatch` is retried.

**Merge-pending is the exception, never the default.** Only when the plan
or operator EXPLICITLY gates the merge on something external (an in-flight
staging deploy, a release window) does the close-out skip steps 1–2 and
file `merge_state: "merge-pending"` with `evidence.merge_gate` naming the
blocker and its clear condition (the queue API rejects a gateless
merge-pending filing). On THIS path the action is still marked done at
filing — the handoff carries the merge + QA debt, and the queue's guards
guarantee it can't leak (a merge-pending item resolves only after
`markHandoffMerged` records the verified merge; leaving the action open
would orphan it). Dispatch defers; when the gate clears and the branch
merges, `markHandoffMerged` (queue API) records the flip and fires the
deferred dispatch.

**If watchtower is not installed** (no `~/.claude-cabinet/watchtower/
scripts/watchtower-queue.mjs` — `/execute` ships in the planning module;
the inbox queue is the opt-in watchtower module), the queue does not
exist. Still merge (steps 1–2 above), then do NOT fail the close-out and
do NOT skip silently — surface a loud, plain-English note:

> Worktree branch `<branch>` is merged to main at `<short-sha>` and the
> action is marked done, but watchtower isn't installed, so I couldn't
> file a tracked qa-handoff. QA the merge manually (or install watchtower
> for the tracked handoff). See `/qa-handoff`.

On the **main checkout** this subsection is skipped — no worktree boundary
means no handoff; do the merge/QA tail inline.

#### Check downstream impact

If deviations were found:
1. List remaining actions in the same project: `pib_list_actions --project <project_fid>`
2. For each, check if its surface area overlaps with files you modified
   (use `git diff --name-only` from before this action)
3. Flag overlapping actions: "Action [fid] may need spec updates"

### 9. Discover Custom Phases

Check for any additional phase files in `phases/` that the skeleton
doesn't define. Execute them at their declared position.

## Phase Summary

| Phase | Absent = | What it customizes |
|-------|----------|-------------------|
| `load-plan.md` | Default: plan from conversation | Where plans live, how to read them |
| `cabinet.md` | Default: match by convening criteria | Which cabinet members, special rules |
| `verification-tools.md` | Default: use available env tools | Project-specific verification tools |
| `validators.md` | Default: run validate skill or linter | What validation to run |
| `commit-and-deploy.md` | Default: commit, don't push/deploy | How to persist and deploy changes |
| `post-impl-checklist.md` | **Instruction: always runs** | Surface targeted QA checks from qa-dimensions.yaml before CP3 |

## Principles

The principles governing the checkpoints themselves — guardrails not
gates, err toward inclusion, tight scoping, the pre-commit sweep — live
in `.claude/cabinet/checkpoint-protocol.md` (the single source of truth
the checkpoints read). The principle specific to `/execute`:

- **Verify every acceptance criterion before marking work done.** The
  checkpoints catch design and review issues; the QA gate (Step 6)
  catches "looks complete but the AC was never actually run." Neither
  substitutes for the other.

## Calibration

**Core failure this targets:** Marking work complete without verifying
every acceptance criterion. The most dangerous variant isn't skipping
AC entirely — it's running some, fixing what fails, and not re-verifying
that the fix didn't break something else.

### Without Skill (Bad)

Plan says to add a new API endpoint + UI page. Claude implements the
endpoint and page, runs the type checker, sees it compiles. Commits.
Marks the work item complete. The plan had "[auto] POST /api/foo
returns 201" — never tested. The endpoint has a typo in the route
handler that returns 404. The "[manual] New page shows data table
with sorting" criterion was never checked — the page renders but the
sort handler throws. Two failing criteria, marked complete.

### With Skill (Good)

Same plan. Claude implements file-group by file-group with checkpoint
reviews. After implementation, walks through every AC line by line.
The auto criterion fails — route typo found and fixed. Re-verifies.
Manual criteria checked with available tools. Only marks complete
when all criteria pass. The next session inherits verified work, not
an assumption.