5-phase-workflow 2.0.6 → 3.0.0-beta-2

package/README.md

@@ -6,18 +6,18 @@
 
 **Project setup** — The `/5:configure` command detects your stack, generates a `CLAUDE.md` / `AGENTS.md` tailored to your project, writes a `.5/index/` knowledge base, and installs project-specific skills and rules. This gives every AI session the right context from the start rather than letting the model guess.
 
-**Status line** — foifi installs an informative Claude Code status line that surfaces the active feature, current workflow phase, and relevant state directly in the terminal footer. No more digging through files to remember where you left off.
+**Status line** — foifi installs a Claude Code status line that surfaces the installed version, available updates, and pending reconfigure/migration reminders directly in the terminal footer.
 
 **Structured implementation workflow** — Instead of asking Claude or Codex to "just implement this," foifi enforces a three-phase loop:
-1. **Plan** (`/5:plan`) — writes a single human-reviewed `plan.md` with scope, acceptance criteria, component checklist, and decisions.
-2. **Implement** (`/5:implement`) — an orchestrator agent turns the plan into a typed execution graph (`state.json`), then delegates each component to a focused executor agent. A verification agent checks completeness, correctness, and test coverage at the end of every run.
-3. **Review** (`/5:review`) — triages changed files, produces structured findings, and feeds them into `/5:address-review-findings` for interactive fix decisions and PR replies.
+1. **Plan** (`/5:plan`) — wraps Claude Code's native plan mode and persists the approved result as a single human-reviewed `plan.md` with scope, acceptance criteria, component checklist, and decisions. Run it again on the same feature to refine that plan. Small plans are implemented right there on approval; larger ones hand off to step 2.
+2. **Implement** (`/5:implement`) — an orchestrator agent turns the plan into a typed execution graph, then delegates each component to a focused executor agent, firing independent components in parallel waves. A verification agent checks completeness, correctness, and test coverage at the end of every run.
+3. **Review** (`/5:review`) — wraps Claude Code's built-in `code-review` skill, produces structured findings, and feeds them into `/5:address-review-findings` for interactive fix decisions and PR replies.
 
-This separation keeps planning readable, implementation mechanical, and review structured.
+This separation keeps planning readable, implementation mechanical, and review structured. Where Claude Code ships a native capability, foifi wraps it rather than reimplementing it — what foifi adds is the durable repo-local artifact and the ticket/config conventions around it.
 
 **Code review and findings** — `/5:review` triages changed files and produces structured `review-findings-*.md`. `/5:address-review-findings` presents each finding interactively, records `fix`/`wont_fix`/`wait` decisions, applies approved local fixes, handles PR comment replies, and keeps a decision log — all without losing context between sessions.
 
-**Plan management helpers** — `/5:discuss-feature` refines an existing plan in conversation. `/5:split` breaks a large plan into smaller linked child plans. `/5:unlock` clears a stale planning lock. `/5:reconfigure` refreshes docs and skills when the project evolves.
+**Plan management helpers** — `/5:split` breaks a large plan into smaller linked child plans. `/5:reconfigure` refreshes docs and skills when the project evolves.
 
 **Codex support** — Every command has a `$5-*` Codex equivalent. Codex runs are token-budgeted: simple steps use a lighter model and low reasoning, complex or security-sensitive steps escalate automatically.
 
@@ -81,24 +81,22 @@ $5-review
 $5-address-review-findings {feature-name}
 ```
 
-Verification runs at the end of `/5:implement` and records concise results in `state.json`.
+Verification runs at the end of `/5:implement` and records a concise result in `state.json`.
 
 ## Commands
 
 | Command | Purpose |
 |---------|---------|
 | `/5:configure` / `$5-configure` | Detect project settings and write the CONFIGURE plan |
-| `/5:plan` / `$5-plan` | Create one unified `plan.md` from requirements, codebase exploration, and user decisions |
-| `/5:discuss-feature` / `$5-discuss-feature` | Refine an existing `plan.md` |
+| `/5:plan` / `$5-plan` | Create one unified `plan.md` from requirements, codebase exploration, and user decisions — or refine an existing one |
 | `/5:split` / `$5-split` | Split an existing plan into smaller linked plans for separate implementation |
-| `/5:implement` / `$5-implement` | Derive `state.json`, execute steps with agents, and verify inline |
+| `/5:implement` / `$5-implement` | Derive the execution graph, execute steps with agents, and verify inline |
 | `/5:review` / `$5-review` | Review code changes and save findings |
 | `/5:commit` / `$5-commit` | Create a git commit using the configured commit message template |
 | `/5:address-review-findings` / `$5-address-review-findings` | Decide on review findings interactively, then apply approved fixes and PR comments |
 | `/5:reconfigure` / `$5-reconfigure` | Refresh docs, index, skills, and rules |
 | `/5:update` / `$5-update` | Upgrade installed workflow files |
 | `/5:eject` / `$5-eject` | Stop workflow-managed updates |
-| `/5:unlock` / `$5-unlock` | Remove a stale planning guard lock |
 | `/5:synchronize-agents` / `$5-synchronize-agents` | Sync user content between Claude Code and Codex |
 
 ## Artifacts
@@ -107,8 +105,7 @@ Each feature lives under `.5/features/{feature-name}/`:
 
 - `plan.md` - single human-reviewed planning artifact
 - `codebase-scan.md` - cached discovery used to reduce repeated scanning
-- `state.json` - enriched execution state derived by `step-orchestrator-agent`
-- `state-events.jsonl` - detailed execution history for retries, commands, commits, and verification
+- `state.json` - small resume record: status, completed components, verification result
 - `split-manifest-*.json` - parent feature record for child plans created by `/5:split`
 - `review-findings-*.md` - review output for `/5:address-review-findings`
 - `review-decisions-*.json` - interactive fix/wont-fix/wait decisions for local findings
@@ -116,13 +113,15 @@ Each feature lives under `.5/features/{feature-name}/`:
 
 ## Design
 
-Planning stays human-readable. `plan.md` contains scope, acceptance criteria, decisions, module impact, and a clean component checklist. Small low-risk changes can use the compact plan template. Plans intentionally do not ask the planner to fill model choices, verify commands, step grouping, or pattern-file wiring.
+Planning stays human-readable. Claude Code's native plan mode does the exploring, the asking, and the approval gate; `/5:plan` contributes the ticket lookup, the feature folder convention, and the artifact schema, then persists the approved plan. `plan.md` contains scope, acceptance criteria, decisions, module impact, and a clean component checklist. Small low-risk changes can use the compact plan template. Plans intentionally do not ask the planner to fill model choices, verify commands, step grouping, or pattern-file wiring.
 
-Implementation is mechanical. `step-orchestrator-agent` reads `plan.md` and `codebase-scan.md`, derives the execution graph into compact `state.json`, then `/5:implement` delegates each component to `step-executor-agent` with an inline executor contract. Pattern context is passed as targeted references instead of broad file lists so executors can read only the relevant ranges. Detailed history is appended to `state-events.jsonl`. This reduces planning token cost and avoids brittle prompt-table metadata.
+Delegation is matched to the size of the job. Approving a plan means you want it built, so `/5:plan` finishes compact plans itself — for one or two files, the already-warm session beats anything an orchestrator can set up. Full plans go to `/5:implement`, where the cost is repaid: `step-orchestrator-agent` reads `plan.md` and `codebase-scan.md` and returns an execution graph, then each component goes to a `step-executor-agent` with an inline executor contract, independent components firing in parallel. Pattern context is passed as targeted references instead of broad file lists so executors read only the relevant ranges, and mechanical components run on a cheaper model than the ones that need reasoning.
 
-Verification uses a dedicated agent. `/5:implement` runs `verification-agent` at the end and records a concise final status in `state.json` without generating an extra report.
+State is kept to what is actually read. The execution graph is derived fresh on every run and never written to disk; `state.json` persists only the status, the completed component names, and the verification result, which is all a resume needs. Component names are copied verbatim from the plan's checklist, so a re-derived graph still matches what already ran. Live progress comes from the task list, not from a file.
 
-Review is risk-based. Native review triages changed files first and reads full files only for risky changes or when diff context is insufficient. `/5:address-review-findings` presents each finding one by one with a recommendation, records `fix`/`wont_fix`/`wait` decisions, then coordinates narrower helpers for approved local fixes, PR comment triage, and PR replies so the common path stays compact.
+Verification uses a dedicated agent. `/5:implement` runs `verification-agent` at the end, passing it the pre-change baseline so pre-existing failures are not blamed on the change, and records a concise final status without generating an extra report.
+
+Review delegates to Claude Code's built-in `code-review` skill (default effort `high`, override with `/5:review {low|medium|high|max}`) and maps its findings into the workflow's findings file. Where that skill is unavailable — Codex, for example — a built-in review agent takes over and triages changed files by risk instead. `/5:address-review-findings` presents each finding one by one with a recommendation, records `fix`/`wont_fix`/`wait` decisions, then coordinates narrower helpers for approved local fixes, PR comment triage, and PR replies so the common path stays compact.
 
 Reconfiguration uses a compact `.5/reconfigure-manifest.json` to pass refresh decisions to documentation and skill generation helpers without duplicating long detection summaries in prompts.
 

package/bin/install.js

@@ -372,7 +372,14 @@ const LEGACY_REMOVED_FILES = [
   'skills/5-verify-implementation',
   'skills/5-review-code',
   'skills/5-quick-implement',
-  'skills/configure-project'
+  'skills/configure-project',
+  // v2.2: native plan mode replaces the plan guard; /5:plan absorbed discuss-feature
+  'hooks/plan-guard.js',
+  'commands/5/unlock.md',
+  'commands/5/discuss-feature.md',
+  'templates/workflow/STATE.json',
+  'skills/5-unlock',
+  'skills/5-discuss-feature'
 ];
 
 // Get list of workflow-owned files/directories (not user-created)
@@ -388,6 +395,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',
@@ -401,7 +413,6 @@ function getWorkflowManagedFiles() {
       'statusline.js',
       'check-updates.js',
       'check-reconfig.js',
-      'plan-guard.js',
       'config-guard.js'
     ],
 
@@ -426,7 +437,6 @@ function getWorkflowManagedFiles() {
       // Workflow output templates
       'workflow/PLAN.md',
       'workflow/PLAN-COMPACT.md',
-      'workflow/STATE.json',
       'workflow/REVIEW-FINDINGS.md',
       'workflow/REVIEW-SUMMARY.md',
       'workflow/FIX-PLAN.md'
@@ -451,6 +461,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,7 +574,20 @@ This skill was authored for Claude Code. Map these tool references:
 | \`Glob\` | \`glob\` / \`list_directory\` |
 | \`Grep\` | \`grep\` / \`search\` |
 | \`TaskCreate/TaskUpdate\` | Track progress internally |
-| \`EnterPlanMode\` | Not available — use structured output instead |
+| \`Workflow\` | Not available — run the command's prose fallback loop instead |
+| \`Skill(skill="code-review")\` | Not available — run the command's prose fallback loop instead |
+| \`EnterPlanMode\` | Not available — run the command's prose fallback loop instead |
+
+## Model Mapping (single source of truth)
+When a skill, plan, or execution-graph 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.
@@ -565,12 +595,14 @@ This skill was authored for Claude Code. Map these tool references:
 - Use stronger models only when a previous cheaper attempt failed for reasoning reasons.
 - Keep the parent skill context lean: delegate read-heavy exploration to explorer agents and pass only compact findings, target paths, pattern references, and command summaries between agents.
 
-## Guard Rules (replaces plan-guard hook)
-During the planning phase ($5-plan):
+## Guard Rules (Codex has no plan mode)
+Claude Code enforces these at the harness level via native plan mode. Codex has no equivalent, so honour them yourself while running \`$5-plan\`, **until the user approves the plan**:
 - Do NOT write to any file outside \`.5/\`
 - Do NOT write source code — only the unified plan and scan cache
 - Do NOT spawn implementation agents — only Explore/research agents
 
+After approval, \`$5-plan\` implements compact plans inline and hands larger ones to \`$5-implement\`.
+
 ## Update & Migration Notices (replaces statusline hooks)
 At the very start of this skill, before doing anything else, read these two files if they exist:
 - \`.5/.update-cache.json\` — if \`latestAvailableVersion\` is set, compare it to \`packageVersion\` in \`.5/version.json\`. If a newer version is available, tell the user: "foifi update available: <version> — run \`npx foifi --codex --upgrade\` to update."
@@ -696,6 +728,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');
@@ -1022,7 +1073,7 @@ function checkExistingInstallation(targetPath) {
 function showCommandsHelp(isGlobal) {
   if (activeRuntime === 'codex') {
     log.info('Available skills (invoke with $ prefix in Codex):');
-    log.info('  $5-plan                      - Create unified plan');
+    log.info('  $5-plan                      - Create or refine a unified plan');
     log.info('  $5-split                     - Split plan into smaller plans');
     log.info('  $5-implement                 - Execute implementation + verification');
     log.info('  $5-review                    - Code review');
@@ -1031,11 +1082,10 @@ function showCommandsHelp(isGlobal) {
     log.info('  $5-configure                 - Interactive project setup');
     log.info('  $5-reconfigure               - Refresh docs/skills (no Q&A)');
     log.info('  $5-eject                     - Eject from update mechanism');
-    log.info('  $5-unlock                    - Remove planning guard lock');
     log.info('  $5-synchronize-agents        - Sync user content between runtimes');
   } else {
     log.info('Available commands:');
-    log.info('  /5:plan                      - Create unified plan');
+    log.info('  /5:plan                      - Create or refine a unified plan');
     log.info('  /5:split                     - Split plan into smaller plans');
     log.info('  /5:implement                 - Execute implementation + verification');
     log.info('  /5:review                    - Code review');
@@ -1044,7 +1094,6 @@ function showCommandsHelp(isGlobal) {
     log.info('  /5:configure                 - Interactive project setup');
     log.info('  /5:reconfigure               - Refresh docs/skills (no Q&A)');
     log.info('  /5:eject                     - Eject from update mechanism');
-    log.info('  /5:unlock                    - Remove planning guard lock');
     log.info('  /5:synchronize-agents        - Sync user content between runtimes');
   }
   log.info('');
@@ -1059,8 +1108,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);
@@ -1143,6 +1192,38 @@ function removeContextForkFromSkills(targetPath) {
   } catch (e) {}
 }
 
+// Remove the plan-guard PreToolUse hook entry from an existing settings.json.
+// Native plan mode enforces read-only planning at the harness level, so the hook
+// is gone. Claude Code only — Codex never had a settings.json.
+function removePlanGuardHook(targetPath) {
+  const settingsFile = path.join(targetPath, 'settings.json');
+  if (!fs.existsSync(settingsFile)) return;
+  try {
+    const settings = JSON.parse(fs.readFileSync(settingsFile, 'utf8'));
+    const pre = settings.hooks && settings.hooks.PreToolUse;
+    if (!Array.isArray(pre)) return;
+    const kept = pre.filter(entry =>
+      !(entry.hooks || []).some(h => typeof h.command === 'string' && h.command.includes('plan-guard.js')));
+    if (kept.length === pre.length) return;
+    if (kept.length) settings.hooks.PreToolUse = kept;
+    else delete settings.hooks.PreToolUse;
+    if (settings.hooks && !Object.keys(settings.hooks).length) delete settings.hooks;
+    fs.writeFileSync(settingsFile, JSON.stringify(settings, null, 2));
+    log.info('Removed plan-guard hook from settings.json (native plan mode replaces it)');
+  } catch (e) {}
+}
+
+// Delete the stale .5/.planning-active marker. It only existed to drive plan-guard.
+function removePlanningActiveMarker(dataDir) {
+  try {
+    const marker = path.join(dataDir, '.planning-active');
+    if (fs.existsSync(marker)) {
+      fs.unlinkSync(marker);
+      log.info('Removed stale .5/.planning-active marker');
+    }
+  } catch (e) {}
+}
+
 // Perform update (preserves user-created files, updates .5/ data directory)
 function performUpdate(targetPath, sourcePath, isGlobal, versionInfo) {
   log.header(`Updating from ${versionInfo.installed || 'legacy'} to ${versionInfo.available}`);
@@ -1164,6 +1245,10 @@ function performUpdate(targetPath, sourcePath, isGlobal, versionInfo) {
   // Strip `context: fork` from generated skills — caused infinite loops
   removeContextForkFromSkills(targetPath);
 
+  // Native plan mode replaces the plan-guard hook and its marker file
+  removePlanGuardHook(targetPath);
+  removePlanningActiveMarker(dataDir);
+
   // Flag v1 → v2 major upgrade so statusline can prompt for reconfigure
   const prevMajor = versionInfo.installed ? parseInt(versionInfo.installed.split('.')[0], 10) : 0;
   const newMajor = versionInfo.available ? parseInt(versionInfo.available.split('.')[0], 10) : 0;
@@ -1213,14 +1298,13 @@ The workflow provides structured feature development:
 All workflow state lives in \`.5/\` at the project root:
 - \`.5/config.json\` — Project configuration
 - \`.5/features/{name}/plan.md\` — Unified plan
-- \`.5/features/{name}/state.json\` — Implementation state
+- \`.5/features/{name}/state.json\` — Implementation resume state
 
 ## Guard Rules
 
-During the planning phase ($5-plan):
+During the planning phase ($5-plan), until the user approves the plan:
 - Do NOT write files outside \`.5/\`
 - Do NOT write source code — only the unified plan and scan cache
-- The \`.5/.planning-active\` marker indicates planning is in progress
 
 ## Configuration
 
@@ -1417,6 +1501,9 @@ function performCodexUpdate(targetPath, sourcePath, isGlobal, versionInfo) {
   // Rename create-* skill dirs to bare pattern names (create-dto → dto)
   renameCreateSkills(targetPath);
 
+  // The plan-guard marker is shared .5/ state; Codex has no settings.json hook to remove
+  removePlanningActiveMarker(dataDir);
+
   // Flag v1 → v2 major upgrade so skills can prompt for reconfigure
   const prevMajor = versionInfo.installed ? parseInt(versionInfo.installed.split('.')[0], 10) : 0;
   const newMajor = versionInfo.available ? parseInt(versionInfo.available.split('.')[0], 10) : 0;
@@ -1668,6 +1755,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/docs/workflow-guide.md

@@ -14,9 +14,10 @@ The workflow separates human decisions from mechanical execution.
 
 - `plan.md` is the only planning artifact.
 - `codebase-scan.md` caches discovery so later phases avoid repeated scanning.
-- `state.json` is generated by `step-orchestrator-agent` and drives implementation.
-- `state-events.jsonl` stores detailed execution history so `state.json` stays compact.
-- `verification-agent` records final verification status in `state.json`.
+- The execution graph is derived by `step-orchestrator-agent` on every run and is never written to disk.
+- `state.json` persists only what a resume needs: status, completed component names, and the verification result.
+
+Where Claude Code ships a native capability, the workflow wraps it: `/5:plan` runs inside native plan mode and `/5:review` calls the built-in `code-review` skill. Codex has neither, so both commands keep a prose fallback.
 
 This keeps planning short and reviewable while still giving implementation agents enough structured data to work reliably.
 
@@ -56,41 +57,46 @@ The planner gathers requirements, explores the codebase, asks targeted questions
 
 The component checklist has only four columns: component, action, target path, intent. It does not contain step grouping, model selection, verify commands, or pattern-reference wiring.
 
+Which template gets chosen also decides what happens on approval: a compact plan is implemented immediately in the same session, while a full plan stops after writing the artifacts and points you at `/5:implement`.
+
 ## Refining A Plan
 
 Run:
 
 ```text
-/5:discuss-feature {feature-name}
+/5:plan {feature-name}
 ```
 
-Use this when the reviewed plan needs changed scope, additional acceptance criteria, or a corrected component checklist.
+With an existing `plan.md`, `/5:plan` enters refine mode: it seeds plan mode with the current plan, discusses the changes, then overwrites the file and appends a `## Discussion History` entry. Use this when the reviewed plan needs changed scope, additional acceptance criteria, or a corrected component checklist.
 
 ## Implement
 
+Compact plans never reach this command. Approving a plan means you want it built, so `/5:plan` implements a 1-2 component plan inline in the session that planned it and writes the same `state.json` — orchestration would cost more than it saves at that size. What follows applies to full plans.
+
 Run:
 
 ```text
 /5:implement {feature-name}
 ```
 
+Prefer a fresh context first — `/clear` in Claude Code, a new conversation in Codex. This command needs only `plan.md` and `codebase-scan.md`, and dropping the planning conversation is the point of the handoff. It is a recommendation, not a requirement.
+
 Implementation does three things:
 
-1. Spawns `step-orchestrator-agent` to derive compact `state.json` from `plan.md` and `codebase-scan.md`.
+1. Spawns `step-orchestrator-agent` to derive the execution graph from `plan.md` and `codebase-scan.md` — steps, execution mode, dependency edges, model choice, targeted pattern references, and verify commands.
 2. Spawns executor agents for each component using an inline executor contract, parallelizing independent work.
-3. Spawns `verification-agent` to verify completeness, correctness, build/tests, acceptance criteria, and test coverage, then records the result in `state.json`.
+3. Spawns `verification-agent` to verify completeness, correctness, build/tests, acceptance criteria, and test coverage.
+
+The graph is transient. `state.json` records only:
 
-`state.json` tracks:
+- `status` — `in-progress`, `completed`, or `failed`
+- `completedComponents` — the names of components that finished
+- `verification` — final status plus a one-line summary
+- `startedAt` / `lastUpdated`
 
-- steps and execution mode
-- pending/completed/failed components
-- dependency edges
-- targeted pattern references
-- verify commands
-- baseline and verification results
-- compact latest command/commit summaries, with detailed history in `state-events.jsonl`
+Live progress during a run comes from the task list rather than the file.
 
-If implementation is interrupted, rerun `/5:implement {feature-name}` to resume from the recorded step.
+If implementation is interrupted, rerun `/5:implement {feature-name}` to resume. The graph is re-derived and components already in `completedComponents` are skipped — which works because component names are copied verbatim from the plan's checklist. Note that the Workflow path writes `state.json` only when the run returns, so a run killed mid-way repeats the components it had finished.
 
 Verification runs inline during `/5:implement`. It checks planned files, final build/test commands, acceptance criteria, and recorded component verification outcomes.
 
@@ -102,13 +108,13 @@ Run:
 /5:review
 ```
 
-Review can use native agent review or CodeRabbit if configured. Native review triages changed files by risk and reads full files only for high-risk changes or when diff context is insufficient. It saves findings to:
+On Claude Code, review delegates to the built-in `code-review` skill. Effort defaults to `high`; pass `/5:review low|medium|high|max` to override. Where that skill is unavailable (Codex), a built-in review agent triages changed files by risk and reads full files only for high-risk changes or when diff context is insufficient. Either way it saves findings to:
 
 ```text
 .5/features/{feature-name}/review-findings-{timestamp}.md
 ```
 
-Then apply approved findings:
+When findings exist, `/5:review` asks whether to address them right away and hands off automatically if you say yes. To pick it up later instead:
 
 ```text
 /5:address-review-findings {feature-name}
@@ -143,12 +149,6 @@ Refresh generated docs/index/skills later with:
 
 ## Troubleshooting
 
-If planning is blocked by a stale guard:
-
-```text
-/5:unlock
-```
-
 If an implementation failed:
 
 1. Read `.5/features/{feature-name}/state.json`.
@@ -174,8 +174,7 @@ v2.0.0 removes old commands during upgrade:
 
 | Command | Purpose |
 |---------|---------|
-| `/5:plan` | Create unified plan |
-| `/5:discuss-feature` | Refine existing plan |
+| `/5:plan` | Create a unified plan, or refine an existing one |
 | `/5:implement` | Implement and verify |
 | `/5:review` | Review changes |
 | `/5:commit` | Create a templated git commit |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "5-phase-workflow",
-  "version": "2.0.6",
+  "version": "3.0.0-beta-2",
   "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

@@ -1,41 +1,36 @@
 ---
 name: step-orchestrator-agent
-description: Converts a clean human plan into enriched state.json steps, component wiring, model choices, pattern references, and verify commands.
-tools: Read, Write, Glob, Grep
+description: Converts a clean human plan into an execution graph — steps, component wiring, model choices, pattern references, and verify commands.
+tools: Read, Glob, Grep
 ---
 
 <role>
-You are a Step Orchestrator. You do not implement code. You read `plan.md`, `codebase-scan.md`, and config, then write `.5/features/{name}/state.json`.
+You are a Step Orchestrator. You do not implement code and you do not write files. You read `plan.md`, `codebase-scan.md`, and config, then return an execution graph.
 </role>
 
 ## Goal
 
-Turn the human-readable component checklist in `plan.md` into execution state that `/5:implement` can run without rethinking the plan.
+Turn the human-readable component checklist in `plan.md` into execution state that `/5:implement` can run without rethinking the plan. The graph is transient — it is derived fresh on every run, including resumes.
 
 ## Derivation Rules
 
+- **Copy every component name verbatim from the plan's Component Checklist.** Resume matches components by name across runs; renaming or reformatting a name makes completed work run twice.
 - Group independent components into the same step with `mode: "parallel"`.
 - Use `mode: "sequential"` when components touch the same file, one imports another, or an explicit dependency exists.
 - Prefer fewer steps when dependencies allow.
 - 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.
 
-## State Schema
+## Output
 
-Write valid JSON:
+Return this shape:
 
 ```json
 {
-  "ticket": "{ticket-id}",
-  "feature": "{feature-name}",
-  "status": "in-progress",
-  "currentStep": 1,
-  "totalSteps": 1,
   "steps": [
     {
       "number": 1,
@@ -66,46 +61,17 @@ Write valid JSON:
       "verifyCommands": ["command"],
       "notes": []
     }
-  ],
-  "completedComponents": [],
-  "recentFailures": [],
-  "baseline": {},
-  "latestCommandResults": [],
-  "verificationResults": {},
-  "latestCommitResults": [],
-  "eventLog": ".5/features/{feature-name}/state-events.jsonl",
-  "startedAt": "{ISO-timestamp}",
-  "lastUpdated": "{ISO-timestamp}"
+  ]
 }
 ```
 
 ## Quality Bar
 
-Before writing state:
+Before returning:
 
+- Every component name matches the plan's Component Checklist character for character.
 - Every component from `plan.md` is represented once unless it is explicitly deferred.
 - Every non-first-step dependency refers to an existing component name.
 - Every component has 1-2 high-signal `patternRefs`, or a note explaining why no pattern exists.
 - Every component has at least one verify command or a note explaining why verification is manual.
 - Rename components must set `sourceFile` to the original path and `file` to the destination path.
-- `totalSteps` equals `steps.length`.
-
-## Event Log
-
-Keep `state.json` small. Append historical details to `.5/features/{name}/state-events.jsonl` as one JSON object per line. Keep only the latest compact summaries in `state.json`.
-
-Each event must include:
-
-```json
-{
-  "type": "command|component_result|retry|commit|verification|state_change",
-  "timestamp": "{ISO-timestamp}",
-  "step": 1,
-  "component": "{component-name-or-null}",
-  "status": "passed|failed|skipped|success|partial",
-  "summary": "one line",
-  "details": {}
-}
-```
-
-Use `details` for command text, files, commit SHA, errors, or verification evidence. Do not duplicate large logs or diffs.