5-phase-workflow 3.0.0 → 3.1.0

package/bin/sync-agents.js

@@ -26,9 +26,13 @@ const log = {
 // ── Workflow-managed file lists (must match install.js) ────────────────────
 
 const WORKFLOW_MANAGED_SKILLS = new Set([
-  'configure-docs-index',
-  'configure-skills',
-  'generate-readme'
+  'configure-agents-md',
+  'configure-rules',
+  'review-style',
+  'fowler-code-smells',
+  'cognitive-load',
+  'documentation-style',
+  'baseline-conventions'
 ]);
 
 const WORKFLOW_MANAGED_AGENTS = new Set([
@@ -42,6 +46,8 @@ const RULES_SYNC_START = '<!-- 5-sync:rules-start -->';
 const RULES_SYNC_END = '<!-- 5-sync:rules-end -->';
 const AGENTS_SYNC_START = '<!-- 5-sync:agents-start -->';
 const AGENTS_SYNC_END = '<!-- 5-sync:agents-end -->';
+// Codex reads only AGENTS.md, so synced rules and agents live in its foifi block.
+const FOIFI_BLOCK_END = '<!-- foifi:end -->';
 
 // ── Conversion functions (mirrors install.js logic) ────────────────────────
 
@@ -73,14 +79,6 @@ function convertClaudeSetupCommandsToCodexNotes(content) {
     .replace(
       /- If user selects "Install now": execute the install command/g,
       '- If user selects "Install now": explain that Codex cannot run the Claude Code installer command; leave `tools.context7.available = false` unless Context7 is already detected'
-    )
-    .replace(
-      /1\. "Install now \(recommended\)" — run `claude plugin install skill-creator@claude-plugins-official` via Bash/g,
-      '1. "Install now" — not supported automatically in Codex; install an equivalent skill authoring workflow outside this command, then rerun configuration'
-    )
-    .replace(
-      /- If user selects "Install now": execute the install command, then set `tools\.skillCreator\.available = true` in the config/g,
-      '- If user selects "Install now": explain that Codex cannot run the Claude Code plugin installer; leave `tools.skillCreator.available = false` unless an equivalent tool is already detected'
     );
 }
 
@@ -107,6 +105,7 @@ This skill was authored for Claude Code. Map these tool references:
 | \`Agent(subagent_type="Explore")\` | \`spawn_agent(agent_type="explorer", model="gpt-5.4-mini", reasoning_effort="low", message="...")\` |
 | \`Agent(prompt="...", model="haiku")\` | \`spawn_agent(model="gpt-5.4-mini", reasoning_effort="low", message="...")\` |
 | \`Agent(prompt="...", model="sonnet")\` | \`spawn_agent(model="gpt-5.4", reasoning_effort="medium", message="...")\` |
+| \`Agent(prompt="...", model="opus", effort="medium")\` | \`spawn_agent(model="gpt-5.4", reasoning_effort="high", message="...")\` |
 | \`Agent(prompt="...")\` | \`spawn_agent(model="gpt-5.4-mini", reasoning_effort="low", message="...")\` unless the prompt explicitly requires complex reasoning |
 | \`Read\` | \`read_file\` |
 | \`Write\` | \`write_file\` |
@@ -230,8 +229,8 @@ function findProjectRoot() {
 }
 
 function isClaudeInstalled(root) {
-  return fs.existsSync(path.join(root, '.claude', 'commands', '5', 'plan.md')) ||
-    fs.existsSync(path.join(root, '.claude', 'commands', '5', 'plan-feature.md'));
+  return ['implement.md', 'plan.md', 'plan-feature.md']
+    .some(file => fs.existsSync(path.join(root, '.claude', 'commands', '5', file)));
 }
 
 function isCodexInstalled(root) {
@@ -352,22 +351,22 @@ function classifyRulesActions(root) {
   const rules = getClaudeRules(root);
   if (rules.length === 0) return [];
 
-  const instructionsPath = path.join(root, '.codex', 'instructions.md');
-  if (!fs.existsSync(instructionsPath)) {
+  const agentsPath = path.join(root, 'AGENTS.md');
+  if (!fs.existsSync(agentsPath)) {
     return [{ type: 'new', direction: 'claude-to-codex', category: 'rules', name: `${rules.length} rule file(s)` }];
   }
 
-  const instructions = fs.readFileSync(instructionsPath, 'utf8');
+  const agentsMd = fs.readFileSync(agentsPath, 'utf8');
   const newSection = buildRulesSection(root, rules);
 
   // Extract existing section
-  const startIdx = instructions.indexOf(RULES_SYNC_START);
-  const endIdx = instructions.indexOf(RULES_SYNC_END);
+  const startIdx = agentsMd.indexOf(RULES_SYNC_START);
+  const endIdx = agentsMd.indexOf(RULES_SYNC_END);
   if (startIdx === -1 || endIdx === -1) {
     return [{ type: 'new', direction: 'claude-to-codex', category: 'rules', name: `${rules.length} rule file(s)` }];
   }
 
-  const existing = instructions.substring(startIdx, endIdx + RULES_SYNC_END.length);
+  const existing = agentsMd.substring(startIdx, endIdx + RULES_SYNC_END.length);
   if (existing === newSection) {
     return [{ type: 'in-sync', direction: 'both', category: 'rules', name: `${rules.length} rule file(s)` }];
   }
@@ -378,21 +377,21 @@ function classifyAgentActions(root) {
   const agents = getClaudeCustomAgents(root);
   if (agents.length === 0) return [];
 
-  const instructionsPath = path.join(root, '.codex', 'instructions.md');
-  if (!fs.existsSync(instructionsPath)) {
+  const agentsPath = path.join(root, 'AGENTS.md');
+  if (!fs.existsSync(agentsPath)) {
     return [{ type: 'new', direction: 'claude-to-codex', category: 'agents', name: `${agents.length} agent(s)` }];
   }
 
-  const instructions = fs.readFileSync(instructionsPath, 'utf8');
+  const agentsMd = fs.readFileSync(agentsPath, 'utf8');
   const newSection = buildAgentsSection(root, agents);
 
-  const startIdx = instructions.indexOf(AGENTS_SYNC_START);
-  const endIdx = instructions.indexOf(AGENTS_SYNC_END);
+  const startIdx = agentsMd.indexOf(AGENTS_SYNC_START);
+  const endIdx = agentsMd.indexOf(AGENTS_SYNC_END);
   if (startIdx === -1 || endIdx === -1) {
     return [{ type: 'new', direction: 'claude-to-codex', category: 'agents', name: `${agents.length} agent(s)` }];
   }
 
-  const existing = instructions.substring(startIdx, endIdx + AGENTS_SYNC_END.length);
+  const existing = agentsMd.substring(startIdx, endIdx + AGENTS_SYNC_END.length);
   if (existing === newSection) {
     return [{ type: 'in-sync', direction: 'both', category: 'agents', name: `${agents.length} agent(s)` }];
   }
@@ -403,15 +402,17 @@ function classifyAgentActions(root) {
 
 function buildRulesSection(root, ruleFiles) {
   const rulesDir = path.join(root, '.claude', 'rules');
-  let section = `${RULES_SYNC_START}\n## Project Rules\n\n`;
+  let section = `${RULES_SYNC_START}\n## File-Scoped Rules\n\n`;
   section += '> Synced from .claude/rules/ — do not edit this section manually.\n';
   section += '> Re-run /5:synchronize-agents (or $5-synchronize-agents) to update.\n\n';
 
   for (const file of ruleFiles) {
     const content = fs.readFileSync(path.join(rulesDir, file), 'utf8');
-    const { body } = extractFrontmatterAndBody(content);
+    const { frontmatter, body } = extractFrontmatterAndBody(content);
+    const globs = frontmatter ? [...frontmatter.matchAll(/^\s*-\s*["']?([^"'\n]+?)["']?\s*$/gm)].map(m => `\`${m[1]}\``) : [];
     const name = file.replace('.md', '');
-    section += `### ${name}\n\n${body.trim()}\n\n`;
+    const directives = body.replace('<!-- foifi:generated -->', '').trim();
+    section += `### ${name}\nApplies to: ${globs.length ? globs.join(', ') : 'all files'}\n\n${directives}\n\n`;
   }
 
   section += RULES_SYNC_END;
@@ -435,18 +436,32 @@ function buildAgentsSection(root, agentFiles) {
   return section;
 }
 
-function updateInstructionsSection(instructionsContent, startMarker, endMarker, newSection) {
-  const startIdx = instructionsContent.indexOf(startMarker);
-  const endIdx = instructionsContent.indexOf(endMarker);
+// Replace the marked section inside the foifi block of AGENTS.md, or insert it just before the
+// block's end. Returns null when there is no foifi block: content outside it belongs to the user.
+function updateFoifiBlockSection(content, startMarker, endMarker, newSection) {
+  const startIdx = content.indexOf(startMarker);
+  const endIdx = content.indexOf(endMarker);
 
   if (startIdx !== -1 && endIdx !== -1) {
-    // Replace existing section
-    return instructionsContent.substring(0, startIdx) +
+    return content.substring(0, startIdx) +
       newSection +
-      instructionsContent.substring(endIdx + endMarker.length);
+      content.substring(endIdx + endMarker.length);
+  }
+  const blockEnd = content.indexOf(FOIFI_BLOCK_END);
+  if (blockEnd === -1) return null;
+  return content.substring(0, blockEnd) + newSection + '\n\n' + content.substring(blockEnd);
+}
+
+function writeFoifiBlockSection(root, startMarker, endMarker, section, label) {
+  const agentsPath = path.join(root, 'AGENTS.md');
+  const content = fs.existsSync(agentsPath) ? fs.readFileSync(agentsPath, 'utf8') : '';
+  const updated = updateFoifiBlockSection(content, startMarker, endMarker, section);
+  if (updated === null) {
+    log.warn(`${label}: AGENTS.md has no foifi block — run /5:configure first`);
+    return;
   }
-  // Append
-  return instructionsContent.trimEnd() + '\n\n' + newSection + '\n';
+  fs.writeFileSync(agentsPath, updated);
+  log.dim(`${label} → AGENTS.md (foifi block)`);
 }
 
 // ── Execute sync ───────────────────────────────────────────────────────────
@@ -474,17 +489,17 @@ function executeSync(root, actions) {
     // rules and agents are handled separately in batch
   }
 
-  // Sync rules to instructions.md
+  // Sync rules into the AGENTS.md foifi block
   const ruleActions = actions.filter(a => a.category === 'rules' && a.type !== 'in-sync');
   if (ruleActions.length > 0) {
-    syncRulesToInstructions(root);
+    syncRulesToAgentsMd(root);
     for (const a of ruleActions) counts['claude-to-codex'][a.type]++;
   }
 
-  // Sync agents to instructions.md
+  // Sync agents into the AGENTS.md foifi block
   const agentActions = actions.filter(a => a.category === 'agents' && a.type !== 'in-sync');
   if (agentActions.length > 0) {
-    syncAgentsToInstructions(root);
+    syncAgentsToAgentsMd(root);
     for (const a of agentActions) counts['claude-to-codex'][a.type]++;
   }
 
@@ -519,24 +534,14 @@ function syncCommandClaudeToCodex(root, action) {
   log.dim(`command: ${action.name} → .codex/skills/${action.skillName}/`);
 }
 
-function syncRulesToInstructions(root) {
+function syncRulesToAgentsMd(root) {
   const rules = getClaudeRules(root);
-  const section = buildRulesSection(root, rules);
-  const instructionsPath = path.join(root, '.codex', 'instructions.md');
-  let content = fs.existsSync(instructionsPath) ? fs.readFileSync(instructionsPath, 'utf8') : '';
-  content = updateInstructionsSection(content, RULES_SYNC_START, RULES_SYNC_END, section);
-  fs.writeFileSync(instructionsPath, content);
-  log.dim(`rules: ${rules.length} file(s) → .codex/instructions.md`);
+  writeFoifiBlockSection(root, RULES_SYNC_START, RULES_SYNC_END, buildRulesSection(root, rules), `rules: ${rules.length} file(s)`);
 }
 
-function syncAgentsToInstructions(root) {
+function syncAgentsToAgentsMd(root) {
   const agents = getClaudeCustomAgents(root);
-  const section = buildAgentsSection(root, agents);
-  const instructionsPath = path.join(root, '.codex', 'instructions.md');
-  let content = fs.existsSync(instructionsPath) ? fs.readFileSync(instructionsPath, 'utf8') : '';
-  content = updateInstructionsSection(content, AGENTS_SYNC_START, AGENTS_SYNC_END, section);
-  fs.writeFileSync(instructionsPath, content);
-  log.dim(`agents: ${agents.length} file(s) → .codex/instructions.md`);
+  writeFoifiBlockSection(root, AGENTS_SYNC_START, AGENTS_SYNC_END, buildAgentsSection(root, agents), `agents: ${agents.length} file(s)`);
 }
 
 // ── Display ────────────────────────────────────────────────────────────────

package/docs/workflow-guide.md

@@ -3,7 +3,7 @@
 v2.0.0 collapses the old five command path into the dev-workflow command path:
 
 ```text
-/5:plan -> /5:implement -> /5:review
+plan mode -> /5:implement -> /5:review
 ```
 
 The package is named `foifi`.
@@ -12,93 +12,55 @@ The package is named `foifi`.
 
 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.
+- The plan in `.5/planning/` is the only planning artifact. Claude Code's plan mode saves it there because `/5:configure` sets `plansDirectory`.
+- There is no codebase index or scan cache. What implementation needs, such as the patterns to follow, goes into the plan.
 - 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.
+- Nothing about a run is persisted; a rerun of `/5:implement` starts over.
 
-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.
+Where Claude Code ships a native capability, the workflow uses it: planning happens in native plan mode, shaped by the `AGENTS.md` rules, and `/5:review` calls the built-in `code-review` skill. Codex has neither, so it gets `$5-plan` and a prose review fallback.
+
+Code quality follows a fixed order. The repository's own standards, such as `CONTRIBUTING.md` or `CODESTYLE.md`, always win. The style skills `fowler-code-smells`, `cognitive-load`, `documentation-style`, and `baseline-conventions` set the baseline wherever the repository says nothing. The `review-style` skill checks a change against both.
 
 This keeps planning short and reviewable while still giving implementation agents enough structured data to work reliably.
 
 ## Plan
 
-Run:
-
-```text
-/5:plan
-```
-
-or:
+On Claude Code there is no plan command. Plan in native plan mode (shift+tab, or ask Claude to plan). The "Planning" section of the generated `AGENTS.md` shapes every plan, and plan mode saves it as:
 
 ```text
-$5-plan
+.5/planning/{generated-name}.md
 ```
 
-The planner gathers requirements, explores the codebase, asks targeted questions, and writes:
-
-```text
-.5/features/{feature-name}/plan.md
-.5/features/{feature-name}/codebase-scan.md
-```
-
-`plan.md` uses either the normal template or `PLAN-COMPACT.md` for small, low-risk changes with 1-2 components and no migration, security/auth, or public API contract change. It contains:
-
-- overview
-- what changes
-- existing patterns to follow
-- constraints
-- scope in/out
-- acceptance criteria
-- decisions
-- module impact
-- component checklist
-- technical notes
+On Codex, which has no plan mode, run `$5-plan`; it writes `.5/planning/{feature-name}.md`.
 
-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.
+The plan has no prescribed structure; Claude shapes it as the change needs, with a mermaid diagram where a flow, state machine, or component relationships explain the change better than text. When the request names a ticket, Claude fetches it and confirms the content with you first.
 
-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`.
+Approving a plan means you want it built: Claude runs `/5:implement {plan-path}` right away. A small plan (1-2 files, no migration, security/auth, or public API change) skips the orchestrator there.
 
 ## Refining A Plan
 
-Run:
-
-```text
-/5:plan {feature-name}
-```
-
-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.
+Ask Claude in plan mode to refine an existing plan, by feature name or path. It starts from the plan's content. On Codex, run `$5-plan {feature-name}` or `$5-plan {path-to-plan}`.
 
 ## 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.
+Claude runs it right after you approve a plan; run it yourself to run a plan again.
 
-Implementation does three things:
+A compact plan (1-2 files, no migration, security/auth, or public API change) is implemented inline in that session — no agents. Then build and tests run once, and a scope check compares the diff with the plan. `/5:review` follows, as for a full plan.
 
-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.
+A full plan goes through four steps:
 
-The graph is transient. `state.json` records only:
+1. `step-orchestrator-agent` derives the execution graph — steps, execution mode, dependency edges, model choice, targeted pattern references, and verify commands.
+2. Executor agents implement the components using an inline executor contract, independent ones in parallel. Each follows the repository standards and style skills that apply to its target. Mechanical work runs on `haiku`, ordinary logic on `sonnet`, complex work and every retry on `opus` at medium effort.
+3. When every component was mechanical and passed, build and tests run once plus the scope check. Otherwise `verification-agent` checks completeness, build/tests, the plan's acceptance criteria when it states any, and scope.
+4. `/5:review` runs once on the files the run changed — `code-review`, `security-review` for security-sensitive files, and `review-style` — and `/5:address-review-findings` then fixes the clear findings on its own and asks you only about real decisions, one question at a time. Auto-commit comes after, so approved fixes land in the same commit.
 
-- `status` — `in-progress`, `completed`, or `failed`
-- `completedComponents` — the names of components that finished
-- `verification` — final status plus a one-line summary
-- `startedAt` / `lastUpdated`
-
-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. 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.
+Nothing is persisted. If a run fails or is interrupted, fix the cause and rerun `/5:implement`; executors see work already in the files.
 
 ## Review
 
@@ -108,25 +70,19 @@ Run:
 /5:review
 ```
 
-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:
+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. When the diff touches authentication, user input, secrets, cryptography, or SQL/shell/path construction, the built-in `security-review` skill runs as well. Then `review-style` checks the same changes against the repository's standards and the style skills, in report-only mode. Either way it saves findings to:
 
 ```text
 .5/features/{feature-name}/review-findings-{timestamp}.md
 ```
 
-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:
+When findings exist after `/5:implement`, `/5:review` hands them straight to `/5:address-review-findings`. When you start `/5:review` yourself — possibly on someone else's branch — it asks once before fixing anything and running build and tests. It fixes clear findings on its own — confirmed bugs, security issues, breaches of a repository standard, and style findings with a clear local fix — skips obsolete or out-of-scope ones, and asks you only about real decisions, one question at a time. Then it runs build, tests, and lint, and reports what it fixed, what it skipped, and what you decided. To go through saved findings again, or to decide on every finding yourself:
 
 ```text
-/5:address-review-findings {feature-name}
+/5:address-review-findings {feature-name} [--interactive]
 ```
 
-`/5:address-review-findings` is a compact coordinator. It routes local fixes, PR comment triage, and PR replies through focused helper commands:
-
-- `/5:apply-review-findings`
-- `/5:triage-pr-comments`
-- `/5:reply-pr-comments`
-
-PR comment decisions are recorded in `.5/features/{feature-name}/pr-comment-decisions.json` when PR handling is used.
+For comments on a GitHub PR, ask Claude directly.
 
 ## Configuration
 
@@ -137,23 +93,23 @@ First-time setup:
 /5:implement CONFIGURE
 ```
 
-`/5:configure` writes `.5/config.json` and a CONFIGURE plan. `/5:implement CONFIGURE` generates documentation, the codebase index, AGENTS.md, CLAUDE.md shim, selected skills, and scoped rules.
+`/5:configure` writes `.5/config.json`, sets `plansDirectory` to `.5/planning` in `.claude/settings.json`, and writes the CONFIGURE plan. `/5:implement CONFIGURE` adds the workflow rules to AGENTS.md as one marked block that links the repository's own standards, appends `@AGENTS.md` to CLAUDE.md when it lacks that line, and generates scoped rules. Nothing outside the block changes.
 
-Refresh generated docs/index/skills later with:
+Refresh the AGENTS.md block and the rules later with:
 
 ```text
 /5:reconfigure
 ```
 
-`/5:reconfigure` writes `.5/reconfigure-manifest.json` and passes that compact manifest to documentation and skill refresh helpers instead of duplicating long detection summaries in prompts.
+`/5:reconfigure` writes `.5/reconfigure-manifest.json` and passes that compact manifest to the AGENTS.md and rule refresh helpers instead of duplicating long detection summaries in prompts. It is also the upgrade path after a major update: it sets `plansDirectory` and removes the legacy `.5/index/`. Existing `.5/*.md` docs stay untouched.
 
 ## Troubleshooting
 
 If an implementation failed:
 
-1. Read `.5/features/{feature-name}/state.json`.
+1. Read the verification result in the `/5:implement` report.
 2. Fix external blockers if needed.
-3. Re-run `/5:implement {feature-name}` to resume.
+3. Re-run `/5:implement {feature-name}`.
 
 If an upgrade left old command files installed, run:
 
@@ -174,10 +130,10 @@ v2.0.0 removes old commands during upgrade:
 
 | Command | Purpose |
 |---------|---------|
-| `/5:plan` | Create a unified plan, or refine an existing one |
+| plan mode / `$5-plan` | Create a plan, or refine an existing one |
 | `/5:implement` | Implement and verify |
-| `/5:review` | Review changes |
-| `/5:commit` | Create a templated git commit |
-| `/5:address-review-findings` | Apply approved findings |
+| `/5:review` | Review changes for correctness and standards |
+| `/5:address-review-findings` | Fix clear findings, ask about real decisions |
+| `/5:analyze-feature` | Document a feature with mermaid diagrams |
 | `/5:configure` | Create project config and CONFIGURE plan |
-| `/5:reconfigure` | Refresh generated project context |
+| `/5:reconfigure` | Refresh the AGENTS.md block and rules |

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "5-phase-workflow",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "A dev-workflow for Claude Code and Codex",
   "bin": {
     "foifi": "bin/install.js"
   },
   "scripts": {
-    "test": "bash test/verify-install-js.sh && bash test/test-version-compare.sh && bash test/test-check-updates-hook.sh && bash test/test-update-system.sh",
+    "test": "bash test/verify-install-js.sh && bash test/test-version-compare.sh && bash test/test-check-updates-hook.sh && bash test/test-dependency-guard.sh && bash test/test-update-system.sh",
     "test:install": "bash test/verify-install-js.sh",
     "test:hook": "bash test/test-check-updates-hook.sh",
     "test:update": "bash test/test-update-system.sh",

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

@@ -6,7 +6,7 @@ tools: Read, Write, Edit, Glob, Grep, Bash, context7
 
 <role>
 You are a Step Executor. You implement exactly the assigned component or tightly grouped components.
-You follow the plan, state entry, and existing codebase patterns. You do not widen scope.
+You follow the plan, your component, and existing codebase patterns. You do not widen scope.
 </role>
 
 ## Process
@@ -14,14 +14,14 @@ You follow the plan, state entry, and existing codebase patterns. You do not wid
 1. Read only the listed `patternRefs` ranges or symbols before editing. If a component only has legacy `patternFiles`, read the smallest relevant sections of those files instead of the whole file whenever possible.
 2. For `modify`, read the target file first and make the smallest coherent change.
 3. For `rename`, read both `sourceFile` and `file` first, then move content with the smallest coherent change.
-4. For `create`, mirror naming, exports, layout, and test style from the pattern files.
-5. If the target area has a local skill or rule, follow it.
+4. For `create`, mirror naming, exports, layout, and test style from the pattern files. Nothing is persisted between runs, so the target may exist from an earlier run: read it first; if it already fulfils the intent, report success with no change, otherwise complete it — never overwrite it blindly.
+5. Follow the standards `/5:implement` assigns: read the parts of the repository standards and style skills that apply to your target. Repository standards win over the style skills. If the target area has a local skill or rule, follow it too.
 6. Run every verify command assigned to your component. If none is assigned, verify touched files exist and run the narrowest relevant test/build command you can infer.
 7. Fix local mechanical issues you caused. Stop for architectural changes, auth gates, missing external services, or unclear product decisions.
 
 ## Simplicity
 
-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`.
+Write the minimum that satisfies the component (the "smallest coherent change"): reuse what already exists in this codebase first, then 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. Touch only the target file and what it strictly needs (its test, an import site). Follow `Simplicity First` in the project `AGENTS.md`.
 
 End with exactly:
 
@@ -32,6 +32,7 @@ FILES_CREATED: [comma-separated paths]
 FILES_MODIFIED: [comma-separated paths]
 VERIFY: passed | failed | skipped
 DEVIATIONS: none | {brief list}
+SKIPPED: none | {what you deliberately did not build — add when ...}
 ERROR: none | {error description}
 ---END---
 ```

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

@@ -1,29 +1,30 @@
 ---
 name: step-orchestrator-agent
-description: Converts a clean human plan into an execution graph — steps, component wiring, model choices, pattern references, and verify commands.
+description: Converts a human plan of any shape 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 and you do not write files. You read `plan.md`, `codebase-scan.md`, and config, then return an execution graph.
+You are a Step Orchestrator. You do not implement code and you do not write files. You read the plan 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. The graph is transient — it is derived fresh on every run, including resumes.
+Turn the plan into execution state that `/5:implement` can run without rethinking the plan. The plan has no fixed shape; derive the components from whatever it describes, one per target file or tightly coupled file group. The graph is transient — it is derived fresh on every run.
 
 ## 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.
+- Name each component in short kebab-case.
 - 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.
-- 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.
+- Choose `model: "haiku"` for mechanical work: localized UI changes, tests, docs, config edits, and simple single-file changes.
+- Choose `model: "sonnet"` for ordinary logic.
+- Choose `model: "opus"` only for complex logic, cross-module behavior, security/auth, data migrations, or public API contracts. `/5:implement` runs it at medium effort.
+- Pick `patternRefs` from patterns the plan names, or from 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 plan, package scripts, and target-specific checks. Prefer narrow checks first, then project-level build/test.
+- Preserve user decisions exactly. Exclude work the plan defers or rules out.
 
 ## Output
 
@@ -46,7 +47,7 @@ Return this shape:
       "action": "create|modify|delete|rename",
       "step": 1,
       "mode": "parallel|sequential",
-      "model": "haiku|sonnet",
+      "model": "haiku|sonnet|opus",
       "file": "path/to/file",
       "sourceFile": null,
       "description": "one sentence",
@@ -69,8 +70,7 @@ Return this shape:
 
 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 piece of planned work is represented once unless the plan defers it.
 - 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.

package/src/agents/verification-agent.md

@@ -1,6 +1,6 @@
 ---
 name: verification-agent
-description: Verifies a workflow implementation across completeness, correctness, infrastructure, acceptance criteria, and quality. Used by /5:implement.
+description: Verifies that a workflow implementation was built as planned and works — completeness, infrastructure, acceptance criteria, and scope. Code quality and correctness belong to /5:review. Used by /5:implement.
 tools: Read, Glob, Grep, Bash
 ---
 
@@ -10,18 +10,17 @@ You are a Verification Agent. You verify only. You do not implement fixes and yo
 
 ## Inputs
 
-Read `.5/features/{feature-name}/plan.md` and `.5/config.json` if present. Read `.5/features/{feature-name}/codebase-scan.md` only if the plan does not contain enough information to judge acceptance criteria, relevant patterns, or known risks.
+Read the plan `/5:implement` names and `.5/config.json` if present.
 
-`/5:implement` passes you the component results and the baseline command results from before the change. Treat any command that already failed in the baseline as **pre-existing**, not caused by this change.
+`/5:implement` passes you the component results, the repository standards, and the baseline command results from before the change. Treat any command that already failed in the baseline as **pre-existing**, not caused by this change.
 
 ## Checks
 
-1. Completeness: every planned component is completed, none remain pending, and all planned acceptance criteria are addressed.
+1. Completeness: every planned component is completed, none remain pending, and any acceptance criteria the plan states are addressed.
 2. Files: every planned create/modify target exists unless action is `delete`; `rename` actions verify both that `sourceFile` is removed and `file` exists at the destination path.
 3. Build: run the configured build command unless it is `none` or the baseline and component results already prove its status.
 4. Tests: run the configured test command unless it is `none` or the baseline and component results already prove its status.
-5. Correctness: inspect changed files and executor results to confirm the implementation matches the plan and does not only satisfy file existence. Prefer changed files and targeted imports over broad codebase scanning.
-6. Quality: logic-bearing created or modified components have tests when the project has a test framework.
+5. Scope: run `git status --short` and `git diff HEAD --stat`, and read untracked (`??`) files directly — `git diff HEAD` omits them. Every changed file traces to a planned component (its target, its test, or an import site it needs) or is a file a repository standard requires, such as a changelog entry. Flag files outside the plan, work the plan rules out or defers, new dependencies no component requires, and abstractions or configurability no acceptance criterion asks for. Report drift only in `SCOPE`; it does not change `STATUS` — the user decides what to revert.
 
 Rerun only the commands whose inputs changed. Do not rerun an identical passing command just to see it pass again.
 
@@ -35,9 +34,9 @@ STATUS: passed | partial | failed
 COMPLETENESS: passed | partial | failed
 INFRASTRUCTURE: passed | failed
 ACCEPTANCE_CRITERIA: satisfied/total
-QUALITY: passed | partial | failed
+SCOPE: passed | drift
 ERRORS: none | {summary}
 ---END_VERIFICATION---
 ```
 
-Keep `ERRORS` to a compact summary. Do not paste command logs or diffs.
+Keep `ERRORS` to a compact summary; list each drift finding there as `drift: {path} — {why}`. Do not paste command logs or diffs.