5-phase-workflow 2.0.6 → 2.1.0

package/bin/install.js

@@ -388,6 +388,11 @@ function getWorkflowManagedFiles() {
       'verification-agent.md'
     ],
 
+    // Workflows: Claude Code only (Workflow tool). Not installed for Codex.
+    workflows: [
+      '5-implement.js'
+    ],
+
     // Skills: specific skill directories
     skills: [
       'configure-docs-index',
@@ -451,6 +456,13 @@ function getFileManifest() {
     manifest.push(`agents/${agent}`);
   }
 
+  // Workflows are files (Claude Code only)
+  if (managed.workflows) {
+    for (const wf of managed.workflows) {
+      manifest.push(`workflows/${wf}`);
+    }
+  }
+
   // Skills are directories
   for (const skill of managed.skills) {
     manifest.push(`skills/${skill}`);
@@ -557,8 +569,20 @@ This skill was authored for Claude Code. Map these tool references:
 | \`Glob\` | \`glob\` / \`list_directory\` |
 | \`Grep\` | \`grep\` / \`search\` |
 | \`TaskCreate/TaskUpdate\` | Track progress internally |
+| \`Workflow\` | Not available — run the command's prose fallback loop instead |
 | \`EnterPlanMode\` | Not available — use structured output instead |
 
+## Model Mapping (single source of truth)
+When a skill, plan, or \`state.json\` component names a model, map it to Codex as:
+
+| Named model | Codex model | reasoning_effort |
+|-------------|-------------|------------------|
+| \`haiku\` (or unset) | \`gpt-5.4-mini\` | \`low\` |
+| \`sonnet\` | \`gpt-5.4\` | \`medium\` |
+| Explore / explorer agent | \`gpt-5.4-mini\` (\`agent_type: explorer\`) | \`low\` |
+
+This table is authoritative — skill bodies do not repeat per-call model mappings.
+
 ## Codex Token Budget
 - Default to \`gpt-5.4-mini\` with \`reasoning_effort: low\` for exploration, orchestration, simple implementation, and mechanical file edits.
 - Use \`gpt-5.4\` with \`reasoning_effort: medium\` only for complex logic, cross-module behavior, security-sensitive changes, data migrations, final verification with meaningful logic review, or retries after failure.
@@ -696,6 +720,25 @@ function selectiveUpdate(targetPath, sourcePath) {
     log.success('Updated agents/ (workflow files only)');
   }
 
+  // Update workflow scripts (Claude Code only — Workflow tool)
+  if (managed.workflows && managed.workflows.length > 0) {
+    const workflowsSrc = path.join(sourcePath, 'workflows');
+    const workflowsDest = path.join(targetPath, 'workflows');
+    if (!fs.existsSync(workflowsDest)) {
+      fs.mkdirSync(workflowsDest, { recursive: true });
+    }
+    for (const wf of managed.workflows) {
+      const src = path.join(workflowsSrc, wf);
+      const dest = path.join(workflowsDest, wf);
+      if (fs.existsSync(src)) {
+        fs.copyFileSync(src, dest);
+      } else {
+        log.warn(`Workflow source missing, skipped: ${wf}`);
+      }
+    }
+    log.success('Updated workflows/ (workflow files only)');
+  }
+
   // Update specific skills
   const skillsSrc = path.join(sourcePath, 'skills');
   const skillsDest = path.join(targetPath, 'skills');
@@ -1059,8 +1102,8 @@ function performFreshInstall(targetPath, sourcePath, isGlobal) {
     log.success(`Created ${targetPath}`);
   }
 
-  // Copy directories
-  const dirs = ['commands', 'agents', 'skills', 'hooks', 'templates', 'references'];
+  // Copy directories (workflows is Claude Code only; performCodexFreshInstall never copies it)
+  const dirs = ['commands', 'agents', 'workflows', 'skills', 'hooks', 'templates', 'references'];
   for (const dir of dirs) {
     const src = path.join(sourcePath, dir);
     const dest = path.join(targetPath, dir);
@@ -1668,6 +1711,17 @@ function uninstall() {
   }
   log.success('Removed workflow agents (preserved user-created agents)');
 
+  // Remove only workflow-managed workflow scripts (Claude Code only)
+  if (managed.workflows) {
+    for (const wf of managed.workflows) {
+      const wfPath = path.join(targetPath, 'workflows', wf);
+      if (fs.existsSync(wfPath)) {
+        fs.unlinkSync(wfPath);
+      }
+    }
+    log.success('Removed workflow scripts');
+  }
+
   // Remove only workflow-managed skills
   for (const skill of managed.skills) {
     const skillPath = path.join(targetPath, 'skills', skill);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "5-phase-workflow",
-  "version": "2.0.6",
+  "version": "2.1.0",
   "description": "A dev-workflow for Claude Code and Codex",
   "bin": {
     "foifi": "bin/install.js"

package/src/agents/step-executor-agent.md

@@ -21,7 +21,7 @@ You follow the plan, state entry, and existing codebase patterns. You do not wid
 
 ## Simplicity
 
-Write the minimum that satisfies the component. Before writing code, stop at the first step that solves it: does it need to exist (YAGNI) → standard library → native platform/framework feature → already-installed dependency → a single clear expression → minimum viable implementation. Add no new dependency for this. Do not add abstractions for single-use code, flexibility that was not requested, or error handling for impossible scenarios. Follow `Simplicity First` in the project `AGENTS.md`. This sharpens "smallest coherent change" — it never widens scope.
+Write the minimum that satisfies the component (the "smallest coherent change"): prefer the standard library, a native framework feature, or an already-installed dependency over anything new. Add no new dependency, no abstraction for single-use code, no unrequested flexibility, and no error handling for impossible cases. Follow `Simplicity First` in the project `AGENTS.md`.
 
 End with exactly:
 
@@ -40,12 +40,10 @@ Keep the result block concise. Do not include command logs, diffs, or long expla
 
 ## Deviation Rules
 
-| Trigger | Action |
-|---------|--------|
-| Missing import, type mismatch, lint failure caused by your change | Fix and note in deviations |
-| Existing nearby convention contradicts the plan | Follow the convention and note it |
-| Required dependency or package is absent | Stop and report |
-| Database/schema/auth/API contract change not listed in plan | Stop and report |
-| Verify command fails from pre-existing unrelated failures | Report the exact evidence |
+**Fix and note** in deviations: imports, type mismatches, or lint you caused; a nearby existing convention that contradicts the plan (follow the convention).
+
+**Stop and report** as failed: a required dependency/package is absent; a database/schema/auth/API contract change not in the plan.
+
+**Report the exact evidence, but do not mark the component failed**, when verify fails only from pre-existing unrelated issues (your change is complete and correct; record the failure as a deviation so verification can treat it as pre-existing).
 
 Do not make more than three attempts on the same failing issue.

package/src/agents/step-orchestrator-agent.md

@@ -20,7 +20,6 @@ Turn the human-readable component checklist in `plan.md` into execution state th
 - Tests normally run after the components they validate.
 - Choose `model: "haiku"` by default for simple mechanical work, localized UI changes, tests, docs, config edits, and single-file changes.
 - Choose `model: "sonnet"` only for complex logic, cross-module behavior, security/auth, data migrations, public API contracts, or work likely to require reasoning.
-- For Codex installs, `haiku` maps to `gpt-5.4-mini` with low reasoning and `sonnet` maps to `gpt-5.4` with medium reasoning.
 - Pick `patternRefs` from `Existing Patterns to Follow`, `codebase-scan.md`, or nearby existing files found with Glob/Grep. Prefer one primary reference; use a second only when it adds a distinct convention. Include line ranges or symbols when known so executors avoid reading whole files.
 - Pick `verifyCommands` from `.5/config.json`, the scan, package scripts, and target-specific checks. Prefer narrow checks first, then project-level build/test.
 - Preserve user decisions exactly. Exclude `[DEFERRED]` work.

package/src/agents/verification-agent.md

@@ -48,7 +48,7 @@ Update `state.json`:
   "verificationResults": {
     "completeness": "passed|partial|failed",
     "infrastructure": "passed|failed",
-    "acceptanceCriteria": "passed|partial|failed|skipped",
+    "acceptanceCriteria": "satisfied/total",
     "quality": "passed|partial|failed",
     "commands": [
       {

package/src/commands/5/implement.md

@@ -1,99 +1,97 @@
 ---
 name: 5:implement
-description: Executes a unified plan by spawning step-orchestrator-agent, per-step executor agents, and verification-agent.
-allowed-tools: Agent, Read, Write, Glob, Grep, Bash, TaskCreate, TaskUpdate, TaskList
+description: Executes a unified plan. Uses the Workflow tool when available (parallel waves, schema-validated agents); otherwise runs an equivalent prose loop. Codex always uses the prose loop.
+allowed-tools: Agent, Read, Write, Glob, Grep, Bash, Workflow, TaskCreate, TaskUpdate, TaskList
 user-invocable: true
 argument-hint: [feature-name]
 ---
 
 <role>
-You are an Implementation Orchestrator. You keep your context lean, delegate all code edits, and use `.5/features/{name}/state.json` as source of truth.
-You do NOT write source code yourself.
+You are an Implementation Orchestrator. Keep your context lean, delegate all code edits, and use `.5/features/{name}/state.json` as the durable source of truth for cross-session resume. You do NOT write source code yourself.
 </role>
 
 # Implement
 
-## Process
+## Step 1: Load Artifacts & Decide Path
 
-### Step 1: Load Artifacts
-
-Read `.5/features/{feature-name}/state.json` first if it exists.
-
-Then read only the artifacts needed for the current path:
+Read `.5/features/{feature-name}/state.json` first if it exists. Then read only what the current path needs:
 
 - Resume existing state: `.5/config.json` if needed for baseline, verification, or auto-commit.
 - New state or restart: `plan.md`, `codebase-scan.md` if it exists, and `.5/config.json` if it exists.
-- Final verification: `plan.md`, `state.json`, `.5/config.json` if present, and `codebase-scan.md` only if verification needs missing context.
 
-If `plan.md` is missing, stop and ask the user to run `/5:plan` first, then rerun `/5:implement {feature-name}` with the created feature folder name.
+If `plan.md` is missing, stop and ask the user to run `/5:plan` first, then rerun `/5:implement {feature-name}`.
 
-If state exists:
+State machine, if state exists:
 
-- `completed`: tell the user it is already implemented and verification already ran.
-- `in-progress`: resume from `currentStep`.
+- `completed`: tell the user it is already implemented and verified; stop.
+- `in-progress`: resume from `currentStep` (only run components not in `completedComponents`).
 - `failed`: ask whether to resume or restart.
 
-### Step 2: Orchestrate Plan Into State
+A plan is **compact** when `plan.md` frontmatter has `planFormat: compact` (1-2 components, no data migration, no security/auth change, no public API change).
 
-If state does not exist or restart was requested, spawn `step-orchestrator-agent`.
+Remove `.5/.planning-active` once you have a valid plan to execute.
 
-In Codex, use `model: gpt-5.4-mini` and `reasoning_effort: low` for this agent unless the plan contains complex cross-module logic, security-sensitive work, or data migrations.
+## Step 2: Establish Baseline
 
-Prompt:
-
-```text
-Read `.claude/agents/step-orchestrator-agent.md` for your role and output contract.
+Run build/test commands from `.5/config.json` (or an explicit baseline block in `state.json`). Skip commands set to `none`. If `state.json.baseline` already records the same commands for this run/resume, reuse it.
 
-Feature: {feature-name}
-Plan: .5/features/{feature-name}/plan.md
-Codebase scan: .5/features/{feature-name}/codebase-scan.md
-Config: .5/config.json if present
+Record compact results in `state.json.baseline` (command, status, one-line summary). Append full history to `state-events.jsonl`. If baseline fails, warn and continue; verification treats those as pre-existing.
 
-Create `.5/features/{feature-name}/state.json`.
-Derive steps, dependencies, model choices, pattern references, verify commands, and executor prompts from the clean plan.
-Keep steps minimal: group independent components in parallel; split only for real data/order dependencies or same-file conflicts.
+```json
+{"type":"command","timestamp":"{ISO}","step":0,"component":null,"status":"passed|failed|skipped","summary":"one line","details":{"command":"{command}","phase":"baseline"}}
 ```
 
-Read back `state.json` and verify:
+## Step 3: Run
+
+**If the `Workflow` tool is available, use the Workflow engine (preferred).** It moves orchestration into deterministic JS, fires parallel components concurrently, and returns schema-validated results — fewer tokens than driving the loop turn-by-turn.
 
-- `status` is `in-progress`
-- `steps` is non-empty
-- each pending component has `step`, `mode`, `model`, `patternRefs` or legacy `patternFiles`, and `verifyCommands`
+1. Build `args` for the workflow:
 
-Remove `.5/.planning-active` after state is valid.
+```json
+{
+  "feature": "{feature-name}",
+  "paths": {"plan": ".5/features/{feature-name}/plan.md", "scan": ".5/features/{feature-name}/codebase-scan.md", "config": ".5/config.json"},
+  "isCompact": true,
+  "components": [{"name": "...", "action": "create|modify|delete|rename", "file": "...", "sourceFile": null, "description": "...", "dependsOn": []}],
+  "baseline": [{"command": "...", "status": "passed|failed|skipped", "summary": "one line"}],
+  "resume": null
+}
+```
 
-### Step 3: Establish Baseline
+- For a **compact** plan, set `isCompact: true` and parse `components` from the plan's Component Checklist (the workflow builds a trivial single step with no orchestrator agent).
+- For a **full** plan, set `isCompact: false` and omit `components` — the workflow's orchestrate phase derives steps itself.
+- `baseline` is the array you recorded in Step 2 (or `[]`); the workflow's verifier treats those failures as pre-existing and reuses passing results instead of rerunning them.
+- `resume` is `null` for a fresh run. To resume, pass `{"completedComponents": [...], "steps": [...], "pendingComponents": [...]}` copied verbatim from the existing `state.json`, so the workflow reuses the original steps rather than re-deriving them (re-derivation is non-deterministic and could rename components, breaking resume matching).
+- The workflow reads the config **file** at `paths.config` itself; do not pass build/test/commit settings inline — baseline (Step 2) and auto-commit (Step 5) are run by this command, not the workflow.
 
-Run build/test commands from `.5/config.json` by default. If `state.json` defines an explicit baseline command block, prefer that block. Skip commands explicitly set to `none`.
+2. Call `Workflow({name: "5-implement", args})`.
+3. When it returns, **persist its result** (Step 4): write the returned `steps`, `components`, and `verification` into `state.json`, and **merge** (never replace) the returned `completedComponents` and per-component `results` into the existing arrays — a resumed run reports only the components it ran this invocation, so earlier-session history must be preserved. Append events to `state-events.jsonl`. The workflow does not touch the filesystem itself.
+4. Auto-commit per step (Step 5), then report (Step 6).
 
-If `state.json.baseline` already records the same commands for the current run or resume, reuse it instead of rerunning baseline.
+> Cross-session resume stays durable via `state.json`, but the Workflow path persists **only after the workflow returns** — if a run is interrupted mid-way, this session's progress is not yet saved. On the next `/5:implement`, resume reconciles against the persisted `completedComponents` (only components recorded there are skipped), so re-running a partially-applied step is possible; the executor's smallest-coherent-change contract makes a re-touch safe but not free. Workflow's own in-session resume is a bonus; you are the one who persists state after it returns.
 
-Record compact command results in `state.json.baseline`: command, status, and a one-line summary only. Append full command history to `state-events.jsonl`. If baseline fails, warn and continue; later verification should treat those failures as pre-existing.
+**Otherwise, run the prose loop (fallback).** It produces the same `state.json` outcome:
 
-Command event shape:
+### 3a. Orchestrate into state
 
-```json
-{"type":"command","timestamp":"{ISO}","step":0,"component":null,"status":"passed|failed|skipped","summary":"one line","details":{"command":"{command}","phase":"baseline"}}
-```
+- **Compact plan:** build `state.json` inline from the Component Checklist — one step, `mode: "parallel"` unless components share a file or have a dependency (then `sequential`), `model: "haiku"`. **Do not spawn `step-orchestrator-agent`.**
+- **Full plan:** spawn `step-orchestrator-agent` with `plan.md`, `codebase-scan.md`, and config; it writes `state.json` with steps, dependencies, model choices, `patternRefs` (line ranges/symbols), and verify commands.
 
-### Step 4: Execute Steps
+Verify `state.json`: `status: in-progress`, non-empty `steps`, each pending component has `step`, `mode`, `model`, `patternRefs` (or legacy `patternFiles`), and `verifyCommands`.
 
-For each step from `currentStep`:
+### 3b. Execute steps in waves
 
-1. Pre-check dependencies: every dependency component must be completed; every file created/modified by previous completed components must still exist.
-2. Create/update progress tasks for the step.
-3. Spawn executor agents:
-   - Use one agent per component when `mode` is `parallel`.
-   - Use one agent at a time when `mode` is `sequential` or when components touch the same file.
-   - Give each executor the inline contract below instead of making it read `.claude/agents/step-executor-agent.md`.
-   - In Codex, map each component model before spawning:
-     - `haiku` -> `model: gpt-5.4-mini`, `reasoning_effort: low`
-     - `sonnet` -> `model: gpt-5.4`, `reasoning_effort: medium`
-     - missing model -> `model: gpt-5.4-mini`, `reasoning_effort: low`
-4. Give each executor only its component block from `state.json`, relevant global notes, required pattern references, verify commands, and this inline contract:
+For each step from `currentStep`, skipping components already in `completedComponents`:
+
+1. Pre-check: every dependency component is completed and its files still exist.
+2. Update progress tasks for the step.
+3. Spawn executors:
+   - **Parallel step: emit all of the step's executor Agent calls in a single message so they run concurrently.**
+   - Sequential step (same-file or dependency): one executor at a time.
+   - Give each executor only its component block, required `patternRefs`, verify commands, and the inline contract below — do not make it read `step-executor-agent.md`. (For legacy `patternFiles`, tell it to read only the smallest relevant sections.)
 
 ```text
-Implement exactly the assigned component. Read only listed patternRefs ranges/symbols and the target file. Make the smallest coherent change, run assigned verify commands, and stop for missing dependencies, unplanned auth/schema/API changes, or unclear product decisions.
+Implement exactly the assigned component. Read only listed patternRefs ranges/symbols and the target file. Make the smallest coherent change, run assigned verify commands, and stop (STATUS: failed) for missing dependencies, unplanned auth/schema/API changes, or unclear product decisions. If verify fails only from pre-existing unrelated issues, report it under DEVIATIONS with the exact evidence and keep STATUS: success — your change is complete. Do not make more than three attempts on the same failing issue.
 
 End with:
 ---RESULT---
@@ -106,97 +104,50 @@ ERROR: none | {error description}
 ---END---
 ```
 
-If a component has legacy `patternFiles`, tell the executor to read only the smallest relevant sections.
-5. Parse only the `---RESULT---` block from each response.
-6. Update `completedComponents`, `recentFailures`, `pendingComponents`, `currentStep`, `latestCommandResults`, and `lastUpdated`.
-   - Append `component_result`, `retry`, and `command` events to `state-events.jsonl`.
-   - Keep only the most recent compact summaries in `state.json`.
-7. Read back state after every write and verify the expected fields changed.
-
-Retry failed components up to two times. Upgrade retries to `sonnet`; in Codex this means `model: gpt-5.4`, `reasoning_effort: medium`. Never fix code in the orchestrator context.
-
-Component and retry event shapes:
+4. Parse only the `---RESULT---` block from each executor.
+5. **Once per wave** (not per component), update `completedComponents`, `recentFailures`, `pendingComponents`, `currentStep`, `latestCommandResults`, `lastUpdated`, and append `component_result` / `retry` / `command` events to `state-events.jsonl`. Trust the executor's report — do not re-read files you did not change to confirm them.
 
 ```json
 {"type":"component_result","timestamp":"{ISO}","step":1,"component":"{name}","status":"success|failed","summary":"one line","details":{"filesCreated":[],"filesModified":[],"verify":"passed|failed|skipped"}}
 {"type":"retry","timestamp":"{ISO}","step":1,"component":"{name}","status":"failed","summary":"retry reason","details":{"attempt":2,"model":"sonnet"}}
 ```
 
-### Step 5: Auto-commit Completed Step
-
-After each step completes successfully, check `.5/config.json` for `git.autoCommit`.
+Retry failed components up to twice, escalating to `sonnet`. Never fix code in the orchestrator context.
 
-If `git.autoCommit` is `true`:
+### 3c. Verify
 
-1. Stage only files owned by components completed in this step:
-   - `file` for create/modify/delete targets.
-   - both `sourceFile` and `file` for rename targets.
-   - files reported in executor `FILES_CREATED` and `FILES_MODIFIED`.
-2. Do not stage unrelated working tree changes.
-3. Build the commit message from `git.commitMessage.pattern`:
-   - Replace `{ticket-id}` with `state.ticket` or an empty string.
-   - Replace `{short-description}` with `step {number}: {step-name}`.
-   - Trim redundant whitespace and punctuation if ticket ID is empty.
-4. Commit the staged files.
-5. Append a detailed entry to `state-events.jsonl` and a compact latest entry to `state.json.latestCommitResults`:
+- **Fast path:** when every component reported `success` with `verify` `passed` or `skipped`, and no component was planned as **or escalated to** `sonnet` (i.e. a mechanical change), verify inline — run the configured build/test once (reuse fresh baseline/component results), set the verification fields directly, and skip `verification-agent`.
+- **Otherwise:** spawn `verification-agent` with `plan.md`, `state.json`, and config (and `codebase-scan.md` only if needed). It reuses fresh `baseline`/component/`latestCommandResults` instead of rerunning identical passing commands, then updates `state.json` verification fields and returns:
 
-```json
-{
-  "type": "commit",
-  "timestamp": "{ISO-timestamp}",
-  "step": 1,
-  "component": null,
-  "status": "committed|skipped|failed",
-  "summary": "{commit-message-or-reason}",
-  "details": {
-    "commit": "{sha-or-null}",
-    "files": ["path/to/file"],
-    "error": null
-  }
-}
+```text
+---VERIFICATION---
+STATUS: passed | partial | failed
+COMPLETENESS: passed | partial | failed
+INFRASTRUCTURE: passed | failed
+ACCEPTANCE_CRITERIA: satisfied/total
+QUALITY: passed | partial | failed
+ERRORS: none | {summary}
+---END_VERIFICATION---
 ```
 
-If there are no changed files for the step, skip the commit and record `status: "skipped"`. If commit fails, record `status: "failed"` and continue to final verification; do not retry by staging broader paths.
-
-If `git.autoCommit` is missing or `false`, do not commit.
+## Step 4: Persist Verification Result
 
-### Step 6: Final Verification
+Set `state.json` `status` to `completed` when verification passed; otherwise `failed`, and tell the user to fix the reported issues and rerun `/5:implement {feature-name}` to resume.
 
-After all steps complete, spawn `verification-agent`.
+## Step 5: Auto-commit
 
-In Codex, use `model: gpt-5.4-mini` and `reasoning_effort: low` when all component verification passed and the change is mechanical. Use `model: gpt-5.4` and `reasoning_effort: medium` when components touched complex logic, security/auth, data migrations, public APIs, or any component verification failed or was skipped.
+If `.5/config.json` `git.autoCommit` is `true`, commit once per completed step:
 
-Prompt:
+1. Stage only files owned by that step's components: `file` for create/modify/delete, both `sourceFile` and `file` for rename, plus the executor's reported `FILES_CREATED`/`FILES_MODIFIED`. Do not stage unrelated changes.
+2. Build the message from `git.commitMessage.pattern`, replacing `{ticket-id}` with `state.ticket` (or empty) and `{short-description}` with `step {number}: {step-name}`; trim redundant whitespace/punctuation when the ticket is empty.
+3. Commit, and record a compact entry in `state.json.latestCommitResults` plus a detailed `commit` event:
 
-```text
-Read `.claude/agents/verification-agent.md` for your role and output contract.
-
-Verify feature `{feature-name}` using:
-- .5/features/{feature-name}/plan.md
-- .5/features/{feature-name}/state.json
-- .5/config.json if present
-- .5/features/{feature-name}/codebase-scan.md only if plan/state are insufficient to judge acceptance criteria, patterns, or risks
-
-Verify that the implementation is complete and correct, the project builds, tests run, everything from the plan is implemented, and tests are written for the implemented feature where appropriate.
-Reuse `state.json.baseline`, component `VERIFY` outcomes, and `latestCommandResults` when they are fresh enough to prove the final status. Do not rerun identical build/test commands unless relevant files changed after the last recorded successful run.
-Update `.5/features/{feature-name}/state.json` verification fields.
-Do not write a verification report.
-Do not implement fixes.
+```json
+{"type":"commit","timestamp":"{ISO}","step":1,"component":null,"status":"committed|skipped|failed","summary":"{message-or-reason}","details":{"commit":"{sha-or-null}","files":["path"],"error":null}}
 ```
 
-Parse only the `---VERIFICATION---` block from the response.
-
-If final verification passes, set state `status` to `completed`. If it fails or is partial, set `status` to `failed` and tell the user to fix the reported issues, then rerun `/5:implement {feature-name}` to resume verification.
-
-### Step 7: Report
-
-Report:
+No changed files → `status: "skipped"`. Commit error → `status: "failed"`, continue; do not retry with broader paths. If `git.autoCommit` is missing/`false`, do not commit.
 
-- Completed component count
-- Failed component count
-- Verification status
-- Path to `state.json`
-- Auto-commit count and any failed commit attempts, if `git.autoCommit` is true
-- Failed commands, missing tests, or unmet acceptance criteria, if any
+## Step 6: Report
 
-Stop.
+Report: completed/failed component counts, verification status, path to `state.json`, auto-commit count and any failures, and any failed commands, missing tests, or unmet acceptance criteria. Then stop.

package/src/commands/5/plan.md

@@ -81,7 +81,7 @@ Do not ask technical follow-ups yet.
 
 If `.5/index/` exists, check the `Generated:` timestamp in `.5/index/README.md`. If the index is more than one day old, run `.5/index/rebuild-index.sh` to refresh it before spawning the Explore agent.
 
-Spawn one Explore agent. In Codex, use `agent_type: explorer`, `model: gpt-5.4-mini`, and `reasoning_effort: low`.
+Spawn one Explore agent.
 
 ```text
 Analyze the codebase for a unified workflow plan.

package/src/workflows/5-implement.js

@@ -0,0 +1,328 @@
+export const meta = {
+  name: '5-implement',
+  description: 'Execute a unified plan: derive steps, run executors in parallel waves, verify. Claude Code only; Codex uses the prose loop.',
+  whenToUse: 'Invoked by the /5:implement command when the Workflow tool is available. Reads args from the command, returns final state for the command to persist to state.json.',
+  phases: [
+    { title: 'Orchestrate', detail: 'derive steps + components (agent for non-trivial plans, inline for compact)' },
+    { title: 'Execute', detail: 'one executor agent per component; parallel components fire together per step' },
+    { title: 'Verify', detail: 'inline when all passed + mechanical, else one verification agent' }
+  ]
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Contract note: the executor / orchestrator / verifier prompts below are the
+// inline, schema-validated form of src/agents/*-agent.md. Those .md files remain
+// the canonical human-readable contract; keep these prompts in sync with them.
+//
+// This script has NO filesystem access. It orchestrates agents and RETURNS the
+// final state object. The /5:implement command (which has Write) persists
+// state.json + state-events.jsonl and runs auto-commit after this returns.
+// ─────────────────────────────────────────────────────────────────────────────
+
+const RESULT_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['status', 'verify'],
+  properties: {
+    status: { enum: ['success', 'failed'] },
+    filesCreated: { type: 'array', items: { type: 'string' } },
+    filesModified: { type: 'array', items: { type: 'string' } },
+    verify: { enum: ['passed', 'failed', 'skipped'] },
+    deviations: { type: 'string', description: 'none or a brief list' },
+    error: { type: 'string', description: 'none or an error description' }
+  }
+}
+
+const VERIFICATION_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['status', 'completeness', 'infrastructure', 'quality'],
+  properties: {
+    status: { enum: ['passed', 'partial', 'failed'] },
+    completeness: { enum: ['passed', 'partial', 'failed'] },
+    infrastructure: { enum: ['passed', 'failed'] },
+    acceptanceCriteria: { type: 'string', description: 'satisfied/total, e.g. "3/3"' },
+    quality: { enum: ['passed', 'partial', 'failed'] },
+    commands: {
+      type: 'array',
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['command', 'status'],
+        properties: {
+          command: { type: 'string' },
+          status: { enum: ['passed', 'failed', 'skipped'] },
+          summary: { type: 'string' }
+        }
+      }
+    },
+    failures: { type: 'array', items: { type: 'string' } }
+  }
+}
+
+const STATE_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['steps', 'pendingComponents'],
+  properties: {
+    steps: {
+      type: 'array',
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['number', 'name', 'mode', 'components'],
+        properties: {
+          number: { type: 'integer' },
+          name: { type: 'string' },
+          mode: { enum: ['parallel', 'sequential'] },
+          model: { enum: ['haiku', 'sonnet'] },
+          components: { type: 'array', items: { type: 'string' } }
+        }
+      }
+    },
+    pendingComponents: {
+      type: 'array',
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['name', 'action', 'step', 'mode', 'model', 'file'],
+        properties: {
+          name: { type: 'string' },
+          action: { enum: ['create', 'modify', 'delete', 'rename'] },
+          step: { type: 'integer' },
+          mode: { enum: ['parallel', 'sequential'] },
+          model: { enum: ['haiku', 'sonnet'] },
+          file: { type: 'string' },
+          sourceFile: { type: ['string', 'null'] },
+          description: { type: 'string' },
+          dependsOn: { type: 'array', items: { type: 'string' } },
+          patternRefs: {
+            type: 'array',
+            items: {
+              type: 'object',
+              additionalProperties: false,
+              required: ['file'],
+              properties: {
+                file: { type: 'string' },
+                read: { type: 'string' },
+                reason: { type: 'string' }
+              }
+            }
+          },
+          verifyCommands: { type: 'array', items: { type: 'string' } },
+          notes: { type: 'array', items: { type: 'string' } }
+        }
+      }
+    }
+  }
+}
+
+// ── Prompt builders ──────────────────────────────────────────────────────────
+
+function orchestratorPrompt(a) {
+  return `You are a Step Orchestrator. Read these files and RETURN execution state as structured output. Do NOT write any file.
+
+Feature: ${a.feature}
+Plan: ${a.paths.plan}
+Codebase scan: ${a.paths.scan} (read only if present)
+Config: ${a.paths.config} (read only if present)
+
+Turn the lean component checklist in the plan into steps + components:
+- Group independent components into one step with mode "parallel"; use "sequential" only when components touch the same file, one imports another, or there is an explicit dependency.
+- Prefer fewer steps. Tests run after the components they validate.
+- model "haiku" by default (mechanical, UI, tests, docs, config, single-file). model "sonnet" only for complex logic, cross-module, security/auth, migrations, or public API.
+- 1-2 high-signal patternRefs per component with line ranges or symbols so executors avoid whole-file reads.
+- verifyCommands: narrowest relevant check first, then project build/test.
+- Exclude [DEFERRED] work. Represent every other component once. dependsOn must reference existing component names.
+
+Return an object matching the schema (steps[] and pendingComponents[]).`
+}
+
+function executorPrompt(c, a, opts) {
+  const refs = (c.patternRefs || []).map(r => `  - ${r.file}${r.read ? ` (${r.read})` : ''}${r.reason ? ` — ${r.reason}` : ''}`).join('\n') || '  - none'
+  const verify = (c.verifyCommands || []).join(' && ') || 'infer the narrowest relevant test/build command'
+  const retry = opts && opts.retry
+    ? '\nThis is a RETRY of a failed attempt — read the error context carefully and correct the root cause.'
+    : ''
+  return `You are a Step Executor. Implement EXACTLY this component and nothing more.${retry}
+
+Component: ${c.name}
+Action: ${c.action}
+Target file: ${c.file}${c.sourceFile ? `\nSource file (rename from): ${c.sourceFile}` : ''}
+Intent: ${c.description || ''}
+
+Read only these pattern references (ranges/symbols), plus the target file for modify/rename:
+${refs}
+
+Rules: smallest coherent change; mirror existing naming/exports/layout/tests; follow any local skill or rule; add no new dependency; no abstraction or error handling beyond what the intent requires. Fix mechanical issues you cause (imports, types, lint). STOP and report failed for missing dependencies, unplanned auth/schema/API/contract changes, or unclear product decisions. If verify fails only from pre-existing unrelated issues, report that as a deviation with the exact evidence — do not mark the component failed. Do not make more than three attempts on the same failing issue.
+
+Then run: ${verify}
+
+Return structured output: status, filesCreated, filesModified, verify, deviations (none or brief), error (none or description). Keep it concise — no logs or diffs unless failed.`
+}
+
+function verifyPrompt(a, results, resumeDone) {
+  const ran = results.flatMap(s => s.items.map(i =>
+    `  step ${s.step} ${i.component.name}: ${i.result ? i.result.status : 'no result'} (verify ${i.result ? i.result.verify : '?'})${i.escalated ? ' [escalated to sonnet]' : ''}`))
+  const prior = [...(resumeDone || [])]
+    .filter(n => !results.some(s => s.items.some(i => i.component.name === n)))
+    .map(n => `  ${n}: completed in a prior session`)
+  const summary = [...ran, ...prior].join('\n') || '  (no components ran this invocation)'
+  const baseline = (a.baseline && a.baseline.length)
+    ? a.baseline.map(b => `  ${b.command || b.details && b.details.command || '?'}: ${b.status}${b.summary ? ` — ${b.summary}` : ''}`).join('\n')
+    : '  (none recorded)'
+  return `You are a Verification Agent. Verify only; do not implement fixes.
+
+Feature: ${a.feature}
+Plan: ${a.paths.plan}
+Config: ${a.paths.config} (read only if present)
+
+Baseline (pre-change) command results — treat any failure listed here as PRE-EXISTING, not caused by this change:
+${baseline}
+
+Component results:
+${summary}
+
+Checks: completeness (every planned component done, acceptance criteria addressed); files exist for create/modify, rename moved correctly, delete removed; build + test pass (reuse the baseline and component results above when they already prove status — rerun only the commands whose inputs changed, not identical passing ones); correctness (inspect changed files, not just existence); quality (logic-bearing changes have tests when a test framework exists). Prefer changed files over broad scanning.
+
+Return structured output: status, completeness, infrastructure, acceptanceCriteria ("satisfied/total"), quality, commands[], failures[].`
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+// Build a single trivial step in JS for compact plans (no orchestrator agent).
+function compactSteps(components) {
+  const norm = components.map((c, i) => ({
+    name: c.name,
+    action: c.action || 'modify',
+    step: 1,
+    mode: 'parallel',
+    model: c.model || 'haiku',
+    file: c.file,
+    sourceFile: c.sourceFile || null,
+    description: c.description || '',
+    dependsOn: c.dependsOn || [],
+    patternRefs: c.patternRefs || [],
+    verifyCommands: c.verifyCommands || [],
+    notes: []
+  }))
+  // If two components write the same file or one depends on another, fall back to sequential.
+  const files = norm.map(c => c.file)
+  const fileConflict = new Set(files).size !== files.length
+  const hasDep = norm.some(c => c.dependsOn && c.dependsOn.length)
+  const mode = (fileConflict || hasDep) ? 'sequential' : 'parallel'
+  norm.forEach(c => { c.mode = mode })
+  const stepModel = norm.some(c => c.model === 'sonnet') ? 'sonnet' : 'haiku'
+  return {
+    steps: [{ number: 1, name: 'implement', mode, model: stepModel, components: norm.map(c => c.name) }],
+    pendingComponents: norm
+  }
+}
+
+async function runStep(step, components, a) {
+  const stepComps = components.filter(c => step.components.includes(c.name))
+  if (!stepComps.length) return { step: step.number, name: step.name, mode: step.mode, items: [] }
+
+  let waveResults
+  if (step.mode === 'parallel' && stepComps.length > 1) {
+    // Fire every parallel component together — true concurrency, one wave.
+    waveResults = await parallel(stepComps.map(c => () =>
+      agent(executorPrompt(c, a), { label: `exec:${c.name}`, phase: 'Execute', model: c.model || 'haiku', schema: RESULT_SCHEMA })
+        .then(result => ({ component: c, result }))
+        .catch(() => ({ component: c, result: null }))))
+  } else {
+    waveResults = []
+    for (const c of stepComps) {
+      const result = await agent(executorPrompt(c, a), { label: `exec:${c.name}`, phase: 'Execute', model: c.model || 'haiku', schema: RESULT_SCHEMA })
+        .catch(() => null)
+      waveResults.push({ component: c, result })
+    }
+  }
+
+  // Retry failed OR crashed (null) components up to twice, escalating to sonnet.
+  // A crashed agent (null result) is retried too — an infra error should not be
+  // treated more harshly than a clean structured failure.
+  for (const wr of waveResults) {
+    let attempt = 1
+    while ((wr.result == null || wr.result.status === 'failed') && attempt <= 2) {
+      log(`retry ${wr.component.name} (attempt ${attempt + 1}) on sonnet`)
+      wr.escalated = true
+      const retried = await agent(executorPrompt(wr.component, a, { retry: true }),
+        { label: `retry:${wr.component.name}`, phase: 'Execute', model: 'sonnet', schema: RESULT_SCHEMA }).catch(() => null)
+      if (retried) wr.result = retried
+      attempt++
+    }
+  }
+
+  return { step: step.number, name: step.name, mode: step.mode, items: waveResults }
+}
+
+// ── Main ─────────────────────────────────────────────────────────────────────
+
+const a = args || {}
+const resume = a.resume || {}
+const resumeDone = new Set(resume.completedComponents || [])
+
+phase('Orchestrate')
+let plan
+if (Array.isArray(resume.steps) && resume.steps.length && Array.isArray(resume.pendingComponents) && resume.pendingComponents.length) {
+  // Resume: reuse the steps/components derived in the original run (stored in state.json).
+  // Re-deriving via the orchestrator agent is non-deterministic and could rename components,
+  // breaking name-based resume matching — so never re-orchestrate on resume.
+  log(`resume: reusing ${resume.steps.length} prior step(s); ${resumeDone.size} component(s) already complete`)
+  plan = { steps: resume.steps, pendingComponents: resume.pendingComponents }
+} else if (a.isCompact && Array.isArray(a.components) && a.components.length) {
+  log(`compact plan: ${a.components.length} component(s), no orchestrator agent`)
+  plan = compactSteps(a.components)
+} else {
+  plan = await agent(orchestratorPrompt(a), { label: 'orchestrate', phase: 'Orchestrate', schema: STATE_SCHEMA })
+}
+const steps = plan.steps
+const components = plan.pendingComponents
+
+phase('Execute')
+const results = []
+for (const step of steps) {
+  const remaining = components.filter(c => step.components.includes(c.name) && !resumeDone.has(c.name))
+  if (!remaining.length) { log(`step ${step.number} already complete (resume), skipping`); continue }
+  const stepResult = await runStep({ ...step, components: remaining.map(c => c.name) }, components, a)
+  results.push(stepResult)
+}
+
+phase('Verify')
+const allItems = results.flatMap(s => s.items)
+const allPassed = allItems.length > 0 && allItems.every(i => i.result && i.result.status === 'success' && i.result.verify !== 'failed')
+// Non-mechanical when a component was planned as sonnet OR needed a sonnet retry to pass —
+// either signals reasoning-level work that warrants the full verification agent.
+const usedSonnet = components.some(c => (c.model || 'haiku') === 'sonnet') || allItems.some(i => i.escalated)
+let verification
+if (allPassed && !usedSonnet) {
+  log('all components passed + mechanical (no sonnet, no escalation) — inline verify, no verification agent')
+  verification = { status: 'passed', completeness: 'passed', infrastructure: 'passed', acceptanceCriteria: 'n/a', quality: 'passed', commands: [], failures: [], inline: true }
+} else {
+  if (!allItems.length) log('no components ran this invocation (resume) — verifying the already-completed feature against the plan')
+  verification = await agent(verifyPrompt(a, results, resumeDone), {
+    label: 'verify', phase: 'Verify', model: usedSonnet ? 'sonnet' : 'haiku', schema: VERIFICATION_SCHEMA
+  })
+}
+
+// Union prior + newly-succeeded so the command can MERGE (not replace) completed history on resume.
+const newlyCompleted = allItems.filter(i => i.result && i.result.status === 'success').map(i => i.component.name)
+const completedComponents = [...new Set([...resumeDone, ...newlyCompleted])]
+
+// Returned to the /5:implement command, which persists state.json + state-events.jsonl and auto-commits.
+// steps + components are returned so a later resume can pass them back (deterministic, no re-orchestration).
+return {
+  feature: a.feature,
+  steps,
+  components,
+  completedComponents,
+  results: results.map(s => ({
+    step: s.step,
+    name: s.name,
+    mode: s.mode,
+    items: s.items.map(i => ({ component: i.component.name, file: i.component.file, sourceFile: i.component.sourceFile, escalated: !!i.escalated, result: i.result }))
+  })),
+  verification,
+  status: verification.status === 'passed' ? 'completed' : 'failed'
+}