5-phase-workflow 3.0.0 → 3.1.0

package/src/commands/5/implement.md

@@ -1,101 +1,95 @@
 ---
 name: 5:implement
-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
+description: Executes a plan from .5/planning/. Compact plans are implemented inline in this session; full plans run through the Workflow tool when available (parallel waves, schema-validated agents), otherwise an equivalent prose loop. Codex always uses the prose loop. Verifies that the plan was built and works, then runs /5:review.
+allowed-tools: Agent, Read, Write, Edit, Glob, Grep, Bash, Workflow, Skill, AskUserQuestion
 user-invocable: true
-argument-hint: [feature-name]
+argument-hint: [feature-name-or-plan-path]
 ---
 
 <role>
-You are an Implementation Orchestrator. Keep your context lean, delegate all code edits, and use `.5/features/{name}/state.json` for cross-session resume. You do NOT write source code yourself.
+You are an Implementation Orchestrator. A compact plan you implement yourself. For a full plan you keep your context lean and delegate every code edit to executor agents.
 </role>
 
 # Implement
 
-## Step 1: Load Artifacts
+## Step 1: Load the Plan
 
-Read `plan.md`, `codebase-scan.md` if it exists, and `.5/config.json` if it exists. If `plan.md` is missing, stop and ask the user to run `/5:plan` first, then rerun `/5:implement {feature-name}`.
+Find the plan:
 
-Then read `.5/features/{feature-name}/state.json` if it exists:
+- If the argument is a path to a plan file, use it.
+- Otherwise look in `.5/planning/` for a file named `{argument}.md`, or whose frontmatter has `feature: {argument}`. If several match, use the most recently modified one.
+- Without an argument, use the most recently modified file in `.5/planning/` and name it to the user.
+- If no plan matches, stop and ask the user to plan the feature first — in plan mode on Claude Code, with `$5-plan` on Codex — then rerun `/5:implement`.
 
-- `completed`: tell the user it is already implemented and verified; stop.
-- `in-progress`: resume — skip every component listed in `completedComponents`.
-- `failed`: ask whether to resume or restart. Restart clears `completedComponents`.
+Plans have no fixed shape. The feature name is the plan's `feature` frontmatter field when it has one, otherwise the file name without `.md`.
 
-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). `/5:plan` implements compact plans inline as soon as the user approves them, so a compact plan usually already has a `completed` or `failed` state here — the common reasons to reach this command are resuming a failed inline run or re-running after the plan changed. Treat that state exactly as above; do not re-run completed components.
+Read the plan and `.5/config.json` if it exists. Nothing is persisted between runs; a rerun starts over, and executors see work that is already done in the files.
 
-The execution graph — steps, component wiring, model choices, pattern references, verify commands — is derived fresh on every run and lives only in this run. `state.json` persists only what resume needs:
+A plan is **compact** when it changes 1-2 files with no data migration, no security/auth change, and no public API change. Every other plan is **full**.
 
-```json
-{
-  "feature": "{feature-name}",
-  "status": "in-progress|completed|failed",
-  "completedComponents": ["component-name"],
-  "verification": {"status": "passed|partial|failed", "summary": "one line"},
-  "startedAt": "{ISO-timestamp}",
-  "lastUpdated": "{ISO-timestamp}"
-}
-```
+Collect the standards once for this run:
 
-Resume matches on component name alone, so component names must always be copied verbatim from the plan's Component Checklist. Write `state.json` with `status: "in-progress"` now if it does not exist.
-
-Create one task per planned component with `TaskCreate` so the user can see progress, and mark already-completed components as completed.
+- **Repository standards:** the files `.claude/skills/review-style/SKILL.md` step 2 lists that exist in this repository.
+- **Style skills:** the absolute paths of the styles listed under `## Styles` in `.claude/skills/review-style/SKILL.md`. Resolve them from that skill's directory.
 
 ## Step 2: Establish Baseline
 
-Run build/test commands from `.5/config.json`. Skip commands set to `none`. Keep the results in context for this run — they are what lets verification tell pre-existing failures apart from new ones. Do not persist them. If baseline fails, warn and continue.
+Record `git rev-parse HEAD` as this run's **fixed point** for the review in Step 4, and the files `git status --porcelain` lists now as **pre-run dirty files**: they hold the user's own uncommitted work.
+
+Run build/test commands from `.5/config.json`. Skip commands set to `none`. Keep the results in context for this run — they are what lets verification tell pre-existing failures apart from new ones. If baseline fails, warn and continue.
 
 ## 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.
+### Compact plan: implement inline
+
+The context is already warm, and an agent for one or two files costs more than it saves. Implement the plan yourself, in this session, with no agents and no Workflow call:
+
+- Follow the repository standards first, then the style skills. Follow the patterns the plan names.
+- Make the smallest coherent change: reuse existing code in this codebase first, then the standard library, native platform features, and installed dependencies. Touch only the planned files and what they strictly need (their tests, an import site). Add no new dependency.
+- Then run the **fast-path check** (3c).
 
-1. Build `args` for the workflow:
+### Full plan, with the `Workflow` tool (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.
+
+1. Call `Workflow({name: "5-implement", args})` with:
 
 ```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"}],
-  "completedComponents": []
+  "paths": {"plan": "{plan-path}", "config": ".5/config.json"},
+  "standards": {"repo": ["CONTRIBUTING.md"], "styles": ["/abs/path/.claude/skills/fowler-code-smells/SKILL.md"]},
+  "baseline": [{"command": "...", "status": "passed|failed|skipped", "summary": "one line"}]
 }
 ```
 
-- 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.
+- `standards` holds the repository standards and style skill paths from Step 1. Executors follow them while writing code.
 - `baseline` is the array from Step 2 (or `[]`); the workflow's verifier treats those failures as pre-existing and reuses passing results instead of rerunning them.
-- `completedComponents` is `[]` for a fresh run, or the array from `state.json` to resume. The workflow re-derives the graph and skips those components by name.
-- 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.
+- The workflow reads the config **file** at `paths.config` itself; do not pass build/test/commit settings inline.
 
-2. Call `Workflow({name: "5-implement", args})`.
-3. When it returns, **merge** (never replace) its `completedComponents` into the existing array and write `state.json` (Step 4). A resumed run reports only the components it ran this invocation. Mark the matching tasks completed with `TaskUpdate`. The workflow does not touch the filesystem itself.
-4. Auto-commit per step (Step 5), then report (Step 6).
+2. If the returned `verification.inline` is `true` (every component was mechanical and passed, so no verification agent ran), run the **fast-path check** (3c) and take its result as the verification.
+3. Continue with Step 4.
 
-> The Workflow path persists only after the workflow returns — if a run is interrupted mid-way, this session's progress is not saved and those components run again on the next `/5:implement`. The executor's smallest-coherent-change contract makes a re-touch safe but not free.
+### Full plan, without the `Workflow` tool (prose loop)
 
-**Otherwise, run the prose loop (fallback).** It produces the same outcome:
+It produces the same outcome.
 
-### 3a. Derive the execution graph
+#### 3a. Derive the execution graph
 
-- **Compact plan:** build the graph 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 returns steps, dependencies, model choices, `patternRefs` (line ranges/symbols), and verify commands.
+Spawn `step-orchestrator-agent` with the plan path and config. It returns steps, dependencies, a model per component, `patternRefs` (line ranges/symbols), and verify commands. Check the graph: non-empty steps, and each component carrying `step`, `mode`, `model`, `patternRefs`, and `verifyCommands`.
 
-Check the returned graph: non-empty steps, every component name copied verbatim from the plan's Component Checklist, and each component carrying `step`, `mode`, `model`, `patternRefs`, and `verifyCommands`.
+#### 3b. Execute steps in waves
 
-### 3b. Execute steps in waves
+For each step:
 
-For each step, skipping components already in `completedComponents`:
-
-1. Pre-check: every dependency component is completed and its files still exist.
-2. Mark the step's tasks in progress with `TaskUpdate`.
-3. Spawn executors:
+1. Pre-check: every dependency component succeeded and its files still exist.
+2. Spawn executors with the component's model. Run `opus` at `effort: "medium"`.
    - **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`.
+   - Give each executor only its component block, required `patternRefs`, verify commands, the standards from Step 1, and the inline contract below — do not make it read `step-executor-agent.md`.
 
 ```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 (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.
+Implement exactly the assigned component. Read only listed patternRefs ranges/symbols and the target file. Nothing is persisted between runs, so your work may already be done: for `create`, read the target first when it exists — if it already fulfils the intent, report success with no change; otherwise complete it, never overwrite it blindly. Read the parts of the repository standards and style skills that apply to your target and follow them; repository standards win over the styles. Make the smallest coherent change — reuse existing codebase code first, then stdlib, native platform features, and installed dependencies; touch only the target file and what it strictly needs (its test, an import site) — 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---
@@ -104,19 +98,19 @@ 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---
 ```
 
-4. Parse only the `---RESULT---` block from each executor.
-5. **Once per wave** (not per component), append the succeeded component names to `state.json.completedComponents`, refresh `lastUpdated`, and mark the matching tasks completed. Trust the executor's report — do not re-read files you did not change to confirm them.
+3. Parse only the `---RESULT---` block from each executor. Trust the executor's report — do not re-read files you did not change to confirm them.
 
-Retry failed components up to twice, escalating to `sonnet`. Never fix code in the orchestrator context.
+Retry failed components up to twice on `opus` at `effort: "medium"`. Never fix code in the orchestrator context.
 
-### 3c. Verify
+#### 3c. Verify
 
-- **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) and set the verification result directly, skipping `verification-agent`.
-- **Otherwise:** spawn `verification-agent` with `plan.md`, the component results, the baseline from Step 2, and config (and `codebase-scan.md` only if needed). It returns:
+- **Fast path:** when every component reported `success` with `verify` `passed` or `skipped`, every component was planned as `haiku`, and none needed a retry, run the **fast-path check** below and skip `verification-agent`.
+- **Otherwise:** spawn `verification-agent` — it checks only that the plan was built and works; quality and correctness come from `/5:review` in Step 4 — on `opus` at `effort: "medium"` when any component was planned as or retried on `opus`, else on `sonnet` — with the plan path, the component results, the baseline from Step 2, the repository standards from Step 1, and config. It returns:
 
 ```text
 ---VERIFICATION---
@@ -124,25 +118,41 @@ 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---
 ```
 
-## Step 4: Persist Result
+**Fast-path check** — used by compact plans and by the fast path of both full-plan routes:
+
+1. Run the configured build and test commands once (skip any set to `none`). A command that passed in the baseline and fails now sets `STATUS: failed`; a failure the baseline already had is pre-existing and only goes into the report.
+2. `git status --short` and `git diff HEAD --stat`: every changed file must be a planned target, its test, an import site it needs, or a file a repository standard requires (such as a changelog entry). Anything else is drift.
+3. Changed dependency manifests or lockfiles: a dependency the plan does not require is drift.
+4. `git diff HEAD` on the changed files plus the full contents of untracked (`??`) files — `git diff HEAD` omits files not yet committed — read against the plan: work the plan rules out or defers, or abstraction/configurability the plan does not ask for, is drift.
 
-Write `state.json` with the merged `completedComponents`, a one-line `verification` summary condensed from the block above, and `lastUpdated`. Set `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.
+Set `SCOPE: passed | drift`. Drift never changes the verification status; it only goes into the report.
+
+## Step 4: Review
+
+Run `/5:review since {fixed-point} files: {run-files} feature: {feature-name} dirty: {dirty-files}` with the fixed point and the pre-run dirty files from Step 2 (`dirty: none` when there are none). `{run-files}` lists the files this run created, modified, or deleted, so changes the user already had stay out of the review. `/5:review` runs every quality check exactly once — the built-in `code-review`, `security-review` for security-sensitive files, and `review-style` against the repository standards and the style skills — saves the findings, fixes the clear ones on its own, and asks the user only about real decisions, one at a time. Run it on every path, and before the auto-commit, so approved fixes land in the same commit.
 
 ## Step 5: Auto-commit
 
-If `.5/config.json` `git.autoCommit` is `true`, commit once per completed step:
+If `.5/config.json` `git.autoCommit` is `true`, verification passed, and Step 4 left the code green — no review fix was applied, or `/5:address-review-findings` reported `Review findings addressed: yes` — commit, including the review fixes from Step 4 for those files, once per step for a full plan, once for a compact plan:
 
-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 the ticket from the plan frontmatter (or empty) and `{short-description}` with `step {number}: {step-name}`; trim redundant whitespace/punctuation when the ticket is empty.
+1. Stage only files that step owns: each component's `file` for create/modify/delete, both `sourceFile` and `file` for rename, plus the executors' reported `FILES_CREATED`/`FILES_MODIFIED`. For a compact plan, stage the files you changed. Do not stage unrelated changes. **Never stage a pre-run dirty file** (Step 2), on any plan: it holds the user's own unfinished work. Leave it uncommitted and list it in the report.
+2. Build the message from `git.commitMessage.pattern`, replacing `{ticket-id}` with the ticket the plan or the branch name gives (or empty) and `{short-description}` with `step {number}: {step-name}` (compact plan: a short summary of the change); trim redundant whitespace/punctuation when the ticket is empty.
 3. Commit.
 
-No changed files → skip. Commit error → report it and continue; do not retry with broader paths. If `git.autoCommit` is missing/`false`, do not commit.
+When a review fix left build, tests, e2e, or lint failing, do not commit; report it. No changed files → skip. Commit error → report it and continue; do not retry with broader paths. If `git.autoCommit` is missing/`false`, do not commit.
 
 ## Step 6: Report
 
-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.
+Report: completed/failed component counts, verification status, auto-commit count and any failures, and any failed commands, missing tests, or unmet acceptance criteria. When verification failed, tell the user to fix the reported issues and rerun `/5:implement {feature-name}`. Also list, one line each:
+
+- **Review:** the findings count from `/5:review` and how many were fixed.
+- **Scope:** drift findings from verification, plus files an executor touched outside its planned target (the workflow returns these as `extraFiles`). Suggest `/5:lean-check {feature-name}` when there are any.
+- **Skipped:** every non-`none` `SKIPPED` entry from the executors, so deliberate omissions stay visible.
+- **Not committed:** pre-run dirty files the run changed — they also hold the user's earlier work, so the user commits them.
+
+Then stop.

package/src/commands/5/lean-check.md

@@ -0,0 +1,75 @@
+---
+name: 5:lean-check
+description: Checks any diff for scope drift and over-engineering — changes that do not trace to the request, new dependencies, reinvented code. Works with or without a workflow plan.
+allowed-tools: Bash, Read, Glob, Grep, Edit, Write, AskUserQuestion
+argument-hint: [base-branch|feature-name] [what was requested]
+user-invocable: true
+model: sonnet
+---
+
+<role>
+You are a Lean Checker. You find what a change added beyond what was asked and what could be smaller.
+You only hunt scope drift and complexity. Correctness, security, and performance belong to `/5:review`.
+</role>
+
+# Lean Check
+
+## Step 1: Collect the Diff
+
+Resolve a base, then diff the working tree against it — `git diff {base} --stat` and `git diff {base}` cover committed and uncommitted changes together; add untracked files from `git status --short`.
+
+A feature name is an argument that has a `.5/features/{argument}/` folder or a plan in `.5/planning/` with `feature: {argument}` in its frontmatter.
+
+- A base branch argument (`git rev-parse --verify {argument}` succeeds and it is not a feature name): `base = git merge-base {argument} HEAD`.
+- A feature name or no argument: `base = git merge-base {default-branch} HEAD`, where `{default-branch}` comes from `git symbolic-ref --short refs/remotes/origin/HEAD` (fall back to `main`, then `master`). This includes commits already made by `/5:implement` with `git.autoCommit`. When `HEAD` is the default branch itself, `base = HEAD` (uncommitted changes only).
+- Any other argument is request text for Step 2.
+
+No changes → say `Nothing to check.` and stop.
+
+## Step 2: Establish the Request
+
+Every finding is judged against what was asked. Take the first that exists:
+
+1. Request text passed as an argument.
+2. The feature's plan — the file in `.5/planning/` with `feature: {feature-name}` in its frontmatter — when a feature name was passed or the current branch matches a feature. Use what it puts in and out of scope, the success criteria it states, the work it defers, and the files it targets.
+3. The request from this conversation.
+
+None of these → ask the user for one sentence describing what the change should do.
+
+## Step 3: Check
+
+Read the diff first; read full files only where a finding needs the surrounding code. Search the codebase before claiming something is reinvented.
+
+Tags, one per finding:
+
+- `drift:` a file or change that does not trace to the request (unrelated refactor, reformatting, a feature nobody asked for, work the plan rules out or defers). Replacement: revert it.
+- `dep:` a new dependency in a manifest or lockfile. Name what already covers it (stdlib, platform, installed dependency), or `needed` if nothing does.
+- `reuse:` re-implements something that already lives in this codebase. Name the existing symbol and path.
+- `stdlib:` / `native:` hand-rolled code the standard library or platform ships. Name the function or feature.
+- `yagni:` abstraction with one implementation, config nobody sets, a layer with one caller, flexibility nobody asked for.
+- `delete:` dead code, unreachable branches, error handling for impossible cases.
+- `shrink:` same logic, fewer lines. Show the shorter form.
+
+Never flag: input validation at trust boundaries, error handling that prevents data loss, security measures, accessibility, one small test for non-trivial logic, or anything the request explicitly asked for.
+
+## Step 4: Report
+
+One line per finding, biggest cut first:
+
+```text
+{file}:L{line}: {tag} {what}. {replacement}.
+```
+
+End with `net: -{N} lines, -{M} dependencies possible.` With no findings, output `Lean already. Ship.` and stop.
+
+## Step 5: Offer to Apply
+
+Ask the user:
+
+- "Apply these cuts?"
+  - Options:
+    1. "Apply all" — apply every finding
+    2. "Only drift and dependencies" — revert unrelated changes and new dependencies, leave the rest
+    3. "No, report only"
+
+When applying: make only the listed changes, revert `drift:` hunks without touching the rest of the file, remove dependencies with the project's package manager (never by editing a lockfile by hand), then run the configured build/test commands from `.5/config.json` (skip any set to `none`) and report the result. Never commit.

package/src/commands/5/reconfigure.md

@@ -1,12 +1,12 @@
 ---
 name: 5:reconfigure
-description: Lightweight refresh of project documentation, codebase index, and skills without full Q&A. Re-detects codebase changes, regenerates .5/*.md docs, rebuilds .5/index/, updates AGENTS.md, and refreshes all skills.
+description: Lightweight refresh of the foifi block in AGENTS.md and the generated rules, without full Q&A. Points plan mode at .5/planning/ and removes the legacy .5/index/. Never touches skills or anything outside the foifi block.
 allowed-tools: Read, Write, Bash, Glob, Grep, Agent, AskUserQuestion
 user-invocable: true
 ---
 
 <role>
-You are a Project Reconfigurer. You refresh documentation and skills using existing config.json preferences.
+You are a Project Reconfigurer. You refresh the foifi block in AGENTS.md and the workflow-generated rules using existing config.json preferences.
 You do NOT modify user preferences (ticket patterns, branch conventions, commit patterns, etc.).
 You detect codebase changes, confirm with the user, invoke the configuration refresh skills, then report.
 After reporting what was updated, you are DONE.
@@ -16,134 +16,67 @@ After reporting what was updated, you are DONE.
 
 ## Overview
 
-Single-command refresh that skips the full Q&A of `/5:configure`. Re-detects codebase state, regenerates documentation and skills based on existing `config.json` preferences.
-
-**When to use which:**
+Single-command refresh that skips the full Q&A of `/5:configure`. It is also the upgrade path after a major workflow update.
 
 | Scenario | Command |
 |----------|---------|
 | First-time setup | `/5:configure` |
 | Change preferences (ticket pattern, commit pattern, etc.) | `/5:configure` |
-| Codebase evolved, refresh docs/skills | **`/5:reconfigure`** |
-| Add new skill patterns | `/5:configure` |
+| Codebase or standards evolved, refresh the AGENTS.md block and rules | **`/5:reconfigure`** |
+| After a major workflow upgrade | **`/5:reconfigure`** |
 
 ## ⚠️ CRITICAL SCOPE CONSTRAINT
 
-**THIS COMMAND REGENERATES DOCS AND SKILLS. IT DOES NOT CHANGE USER PREFERENCES.**
-
 Your job:
 ✅ Validate that config.json exists
-✅ Re-detect codebase patterns and commands (same as configure Steps 1b-1h)
-✅ Compare detected state with config.json skill selections
+✅ Re-detect repository standards and rule-relevant file types
 ✅ Show summary and ask for confirmation
-✅ Invoke `configure-docs-index` and `configure-skills` in refresh mode
-✅ Update version.json with artifacts and timestamps
-✅ Clean up .reconfig-reminder flag
+✅ Point Claude Code plan mode at `.5/planning/` when it is not yet
+✅ Invoke `configure-agents-md` and `configure-rules` in refresh mode
+✅ Remove the legacy `.5/index/` after confirmation
+✅ Update version.json timestamps and clean up the reminder flags
 ✅ Report what was updated
 
 Your job is NOT:
-❌ Ask preference questions (ticket pattern, branch convention, commit pattern, etc.)
-❌ Modify config.json preferences (only the `skills` section may be updated if user confirms new patterns)
+❌ Ask preference questions or modify config.json preferences
 ❌ Skip confirmation — always show what will be regenerated
+❌ Change anything in AGENTS.md or CLAUDE.md outside the foifi block
+❌ Create, refresh, or remove any skill — skills belong to the user or to the installer
+❌ Modify user-created rules
+❌ Rewrite or delete existing `.5/*.md` docs — earlier versions generated them, but a team may maintain them now
 
 ## Process
 
 ### Step 1: Validate Config
 
-Read `.5/config.json`. If it does not exist:
-- Tell the user: "No configuration found. Please run `/5:configure` first to set up your project."
-- **EXIT IMMEDIATELY**
-
-Read `.5/version.json` for current state (configuredAt, configuredAtCommit).
-
-### Step 1b: Check skill-creator plugin
-
-Check if the skill-creator plugin is available (look for skill-creator tools in the current session):
-
-- If available: note for later use during skill generation
-- If NOT available AND config.json has skill selections (i.e., skills exist in `.claude/skills/`):
-  - "The skill-creator plugin is not installed. It can improve skill quality."
-  - Options:
-    1. "Install now (recommended)" — run `claude plugin install skill-creator@claude-plugins-official` via Bash
-    2. "Skip"
-  - If "Install now": execute the install command
-
-### Step 2: Re-detect Codebase State
-
-Perform the same detection as configure Steps 1b-1h:
-
-**2a. Detect project type** — same table as configure Step 1b (package.json deps, build files, etc.)
-
-**2b. Detect build/test commands** — same as configure Step 1c
-
-**2c. Detect codebase patterns** — same as configure Step 1g:
-- Scan for architectural patterns (Controllers, Services, Components, etc.)
-- Use both suffix-based and directory-based globs
-- For each pattern: count files, identify location, sample filename
+Read `.5/config.json`. If it does not exist, tell the user: "No configuration found. Please run `/5:configure` first to set up your project." and **EXIT IMMEDIATELY**.
 
-**2d. Detect runnable commands** — same as configure Step 1h:
-- Scan package.json scripts, Makefile targets, etc.
-- Categorize: Build, Test, Lint, Format, Type Check, etc.
+### Step 2: Re-detect
 
-**2e. Scan existing skills** — list ALL skills in `.claude/skills/`:
-- Read each skill's SKILL.md frontmatter
-- Categorize as workflow-generated (create-*, run-*) or user-created
+- **Repository standards** — same as configure Step 1e2. Note each path for the refresh manifest.
+- **AGENTS.md state** — whether it has a foifi block, is a legacy fully generated file (first line starts with `<!-- Generated from the foifi AGENTS.md template`), or has no block yet. Whether `CLAUDE.md` includes `@AGENTS.md`.
+- **Rules** (if `rules.generate` is `true`) — on Codex, the `###` subsections of the `File-Scoped Rules` section in the foifi block of `AGENTS.md`; all of them are workflow-generated. On Claude Code, list `.claude/rules/*.md`. A rule is workflow-generated when it contains `<!-- foifi:generated -->`, or, from earlier versions, when it is named `code-style.md`, `testing.md`, `api-patterns.md`, or `dependencies.md` and you confirm it with the user in Step 3. Everything else is user-created.
+- For each workflow rule, check that its file types still exist (stale), and whether a missing rule from `configure-rules` step 1 now applies (new).
 
-**2f. Scan existing rules** — list ALL rule files in `.claude/rules/`:
-- Read each `.md` file
-- Note which are workflow-generated (code-style, testing, api-patterns, dependencies) vs user-created
-- User-created rules are never modified or removed
+### Step 3: Confirm with User
 
-### Step 3: Compare and Prepare Summary
+Use `AskUserQuestion` to show a summary and get confirmation:
 
-Use the existing skills in `.claude/skills/` (from Step 2e) as the source of truth — not config.json. Compare what's installed with what's detected in the codebase:
+1. **AGENTS.md** — the foifi block will be replaced, appended, or (legacy file) rebuilt with the user's Custom Documentation kept above it. Nothing else changes. `CLAUDE.md` gets `@AGENTS.md` appended when it lacks it.
+2. **Legacy files that will be removed** — `.5/index/` when it exists.
+3. **Settings** — `plansDirectory` set to `.5/planning` in `.claude/settings.json`, when it is not already (Claude Code only).
+4. **Rules** — which workflow rules will be refreshed, created, or removed (multi-select for new and stale ones). For legacy rules without the marker, ask whether foifi may manage them.
 
-- **Existing `create-*` skills** — extract the pattern name from each (e.g., `create-controller` → `controller`)
-- **Existing `run-*` skills** — extract the command name from each (e.g., `run-tests` → `tests`)
-- **New patterns**: detected in codebase (Step 2c) but no matching `create-*` skill exists → offer to create
-- **Stale patterns**: a `create-*` skill exists but the pattern is no longer detected in the codebase → offer to remove or keep
-- **New commands**: detected (Step 2d) but no matching `run-*` skill exists → offer to create
-- **Stale commands**: a `run-*` skill exists but the command is no longer detected → offer to remove or keep
-- **User-created skills** (not matching `create-*` or `run-*` naming) → always refresh with current conventions, never remove
+Options: "Proceed with refresh" or "Cancel".
 
-**Rules comparison** (if `rules.generate` is `true` in config.json):
-- **Existing workflow rules** (from Step 2f) — code-style, testing, api-patterns, dependencies
-- **Stale rules**: a workflow rule exists but its prerequisite patterns are no longer detected → offer to remove
-- **New rules**: patterns detected that could benefit from a rule but none exists yet → offer to create
-- **User-created rules** → never modify or remove
+### Step 4: Build Refresh Manifest
 
-### Step 4: Confirm with User
-
-Use `AskUserQuestion` to show a summary and get confirmation. Present:
-
-1. **Documentation files that will be rewritten** — list `.5/ARCHITECTURE.md`, `.5/TESTING.md`, `.5/CONCERNS.md` (conditional), `.5/CONVENTIONS.md` (when `conventions.generate` is true), `.5/index/rebuild-index.sh`, `.5/index/*.md`, and `AGENTS.md`
-2. **Skills that will be refreshed** — list ALL skills found in `.claude/skills/` (both workflow-generated and user-created)
-3. **Rules that will be refreshed** (if rules enabled) — list workflow-generated rule files in `.claude/rules/`
-4. **New patterns detected** (if any) — "These patterns were found in your codebase but don't have skills yet: [list]. Create skills for them?"
-5. **Stale patterns** (if any) — "These patterns are in your config but weren't found in the codebase: [list]. Remove them?"
-6. **Stale rules** (if any) — "These rule files no longer have matching patterns in the codebase: [list]. Remove them?"
-
-Options:
-- "Proceed with refresh" — regenerate everything as shown
-- "Cancel" — exit without changes
-
-If there are new or stale patterns, use additional `AskUserQuestion` calls with multiSelect to let the user pick which new patterns to add and which stale patterns to remove.
-
-New skills will be created and stale skills removed based on the user's choices.
-
-### Step 5: Build Refresh Manifest
-
-Write `.5/reconfigure-manifest.json` with the compact decisions needed by refresh skills:
+Write `.5/reconfigure-manifest.json`:
 
 ```json
 {
   "mode": "refresh",
-  "docs": ["ARCHITECTURE.md", "TESTING.md", "CONCERNS.md", "CONVENTIONS.md", "index", "AGENTS.md"],
-  "skills": {
-    "refresh": ["skill names"],
-    "create": ["new skill names"],
-    "remove": ["stale skill names selected by user"]
-  },
+  "repoStandards": ["paths from Step 2"],
   "rules": {
     "refresh": ["rule files"],
     "create": ["new rule files"],
@@ -152,51 +85,37 @@ Write `.5/reconfigure-manifest.json` with the compact decisions needed by refres
 }
 ```
 
-Keep detection details out of the prompt once they are represented in this manifest.
+### Step 5: Regenerate
 
-### Step 6: Regenerate
+First, point plan mode at `.5/planning/` exactly as `/5:configure` Step 2.5 describes (Claude Code only — skip on Codex).
 
-Invoke the refresh skills in **refresh mode** via the Agent tool:
+Then invoke the refresh skills in **refresh mode** via the Agent tool (`subagent_type: "general-purpose"`), one after the other — on Codex both write the foifi block of `AGENTS.md`:
 
 ```
-Task prompt 1: "Run configure-docs-index skill in REFRESH MODE using `.5/reconfigure-manifest.json`. Refresh generated docs, rebuild `.5/index/`, remove legacy docs, and update `AGENTS.md` plus the CLAUDE.md shim while preserving user sections."
+Task prompt 1: "Run configure-agents-md skill in REFRESH MODE using `.5/reconfigure-manifest.json`. Refresh the foifi block in AGENTS.md and the CLAUDE.md include; change nothing outside the block."
 
-Task prompt 2: "Run configure-skills skill in REFRESH MODE using `.5/reconfigure-manifest.json`. Refresh, create, and remove only the skills/rules listed in the manifest."
+Task prompt 2: "Run configure-rules skill in REFRESH MODE using `.5/reconfigure-manifest.json`. Refresh, create, and remove only the rules listed in the manifest."
 ```
 
-Use `subagent_type: "general-purpose"` for the Agent.
-
-### Step 7: Track
+Skip task 2 when `rules.generate` is `false`.
 
-After the skill completes, update `.5/version.json`:
+### Step 6: Track and Clean Up
 
-1. Read current version.json
-2. Set `configuredAt` to current ISO timestamp
-3. Set `configuredAtCommit` to current short commit hash (`git rev-parse --short HEAD`)
-4. Write back version.json preserving all other fields
+Update `.5/version.json`: set `configuredAt` to the current ISO timestamp and `configuredAtCommit` to `git rev-parse --short HEAD`, preserving all other fields. Then:
 
-### Step 8: Clean Up
-
-Remove the `.5/.reconfig-reminder` and `.5/.migration-v2` flag files if they exist:
 ```bash
-rm -f .5/.reconfig-reminder .5/.migration-v2
+rm -f .5/.reconfig-reminder .5/.migration-v*
+rm -rf .5/index   # only when the user confirmed it in Step 3
 ```
 
-### Step 9: Report
-
-Show the user a summary:
-- List of documentation files updated (including `.5/CONVENTIONS.md` when applicable)
-- Mention whether the codebase index script and index files were regenerated
-- List of skills refreshed
-- List of new skills created (if any)
-- List of skills removed (if any)
-- List of rules refreshed (if any)
-- List of new rules created (if any)
-- List of rules removed (if any)
-- Timestamp of reconfiguration
+### Step 7: Report
+
+- How the AGENTS.md block was written, which repository standards it links, and whether `CLAUDE.md` changed
+- Whether `plansDirectory` was set and the legacy `.5/index/` removed
+- Rules refreshed, created, and removed
 - Suggest running `/clear` to reset context
 
 ## Related Documentation
 - [configure command](./configure.md) — full Q&A configuration
-- [configure-docs-index skill](../../skills/configure-docs-index/SKILL.md)
-- [configure-skills skill](../../skills/configure-skills/SKILL.md)
+- [configure-agents-md skill](../../skills/configure-agents-md/SKILL.md)
+- [configure-rules skill](../../skills/configure-rules/SKILL.md)