5-phase-workflow 3.0.1 → 3.1.0

package/src/commands/5/address-review-findings.md

@@ -1,68 +1,58 @@
 ---
 name: 5:address-review-findings
-description: Coordinates interactive review finding decisions and optionally handles GitHub PR review comments.
-allowed-tools: Bash, Read, Write, Glob, AskUserQuestion
+description: Fixes clear review findings on its own, asks the user one question at a time only for real decisions, then verifies the result. --interactive asks about every finding.
+allowed-tools: Bash, Read, Edit, Write, Glob, AskUserQuestion, Agent
+argument-hint: [feature-name] [--interactive] [dirty: {paths}]
 user-invocable: true
-model: haiku
+model: sonnet
 context: inherit
 ---
 
 <role>
-You are a Review Fix Coordinator. You keep context lean, collect user decisions one finding at a time, route work to narrower helper commands, and do not review code or implement unrelated changes.
+You are a Review Fix Coordinator. You fix what is clear, ask the user only what they must decide, and do not review code or implement unrelated changes.
 </role>
 
 # Address Review Findings
 
-This is the stable entrypoint after `/5:review`.
+`/5:review` runs this after every review. For comments on a GitHub PR, ask Claude directly; this command handles the findings file only.
 
 ## Options
 
-- `--github` - skip local findings and process PR comments only.
+- `--interactive` — ask about every finding, one at a time, instead of deciding the clear ones yourself.
+- `dirty: {paths}` — files that held the user's own uncommitted work before the run (`/5:implement` passes this). A finding in one of them may sit in that earlier work, so it is always **ask**, never fixed on your own.
 
 ## Process
 
 1. Determine feature context:
-   - Find `.5/features/*/state.json`.
-   - Select the most recent `startedAt` or `lastUpdated`.
-   - If none exists, ask for the feature name.
-   - Read `.5/config.json` only if needed for git/review settings.
-2. Normal mode:
-   - Find the latest `.5/features/{feature}/review-findings-*.md`.
-   - If missing, ask whether to stop or continue with GitHub PR comments only.
+   - Use the feature name argument when given.
+   - Otherwise use the feature of the most recently modified plan in `.5/planning/`: its `feature` frontmatter field, or its file name without `.md`.
+   - If there is none, ask for the feature name.
+2. Decide:
+   - Find the latest `.5/features/{feature}/review-findings-*.md`. If missing, tell the user to run `/5:review` and stop.
    - Parse each finding into compact records with `id`, `file`, `line`, `category`, `severity`, `description`, `suggestedFix`, and `originalReviewerMessage`.
-   - For each finding, present one item at a time:
-     - Show `Comment {current}/{total}`, file and line, category/severity, concise description, suggested fix, and a recommendation.
-     - Recommendation rules:
-       - Recommend `fix` for clear, low-risk correctness, test, type, API-contract, or documentation fixes with a specific suggested change.
-       - Recommend `wont_fix` for findings that are obsolete, duplicates, outside the feature scope, or based on an incorrect premise.
-       - Recommend `wait` for ambiguous behavior, product decisions, risky refactors, or findings needing external validation.
-     - Ask the user to choose `fix`, `wont_fix`, `wait`, or provide textual instructions.
-     - Treat textual instructions as `fix` with `customInstructions` unless the text clearly says to defer or reject the finding.
+   - Sort each finding into one group:
+     - **fix** — a confirmed bug, security issue, breach of a repository standard, or style finding with a clear, local fix that changes no behavior beyond the finding.
+     - **wont_fix** — obsolete, a duplicate, outside the feature scope, or based on an incorrect premise.
+     - **ask** — uncertain (`Question` category), spanning several files, or needing a design, product, or API decision; also any fix whose suggested change you cannot apply with confidence.
+   - Record `fix` and `wont_fix` yourself, each with a one-line reason.
+   - For each **ask** finding, ask the user — **one finding per question, one question at a time**. Show `Decision {current}/{total}`, file and line, a concise description, the suggested fix, and your recommendation. Options: `fix`, `wont_fix`, `wait`, or textual instructions. Treat textual instructions as `fix` with `customInstructions` unless the text clearly says to defer or reject the finding.
+   - With `--interactive`, ask about every finding this way instead.
    - Write decisions to `.5/features/{feature}/review-decisions-{YYYYMMDD-HHmmss}.json`.
-   - Invoke `/5:apply-review-findings {feature} --decisions .5/features/{feature}/review-decisions-{timestamp}.json` to apply approved local fixes.
-3. GitHub mode or user-approved PR handling:
-   - Invoke `/5:triage-pr-comments {feature}` to fetch and classify compact PR comments.
-   - Parse the `---PR-TRIAGE---` block. If triage succeeded, continue even when there are zero actionable comments because duplicate, declined, or deferred comments may still need replies.
-   - Ask the user for decisions on actionable/manual comments.
-   - Invoke `/5:apply-review-findings {feature} --pr-approved` for approved PR fixes.
-   - Invoke `/5:reply-pr-comments {feature}` to post PR replies.
-   - Parse the `---PR-REPLIES---` block and include `POSTED`, `FAILED`, and `ERRORS` in the review summary.
-   - Do not proceed to final output in GitHub mode until `/5:reply-pr-comments` has either posted replies or returned an explicit `---PR-REPLIES---` failure/partial result. Reply failures are non-fatal, but silent omission of the reply step is not allowed.
-4. Run post-fix verification. This is mandatory after any approved fix is applied.
-   - Read `.5/config.json`, project run skills, and common project manifests such as `package.json`, `Makefile`, `pyproject.toml`, `Cargo.toml`, and Gradle files only as needed to identify configured commands.
-   - Run every available configured command in these categories: `build`, `test`, `e2e`/`test:e2e`, and `lint`.
-   - Prefer generated run skills when present (`run-build`, `run-tests`, `run-lint`, and any e2e/test-e2e variant). Otherwise run the exact configured command from `.5/config.json` or the project manifest.
-   - Do not skip a category because another category passed. Skip only when no command exists or the command is explicitly configured as `none`; record the reason.
-   - If any command fails, continue running remaining independent categories so the user gets a complete verification picture.
-   - Do not claim the review findings are fully addressed unless every discovered post-fix verification command passes or is explicitly skipped because no command exists.
-   - Store compact results for each category in the summary: command, status (`passed`, `failed`, or `skipped`), and a one-line reason.
-5. Write `.5/features/{feature}/review-summary-{YYYYMMDD-HHmmss}.md` using `.claude/templates/workflow/REVIEW-SUMMARY.md`.
-
-Keep all intermediate summaries compact. Do not paste raw diffs, raw PR JSON, or command logs unless a failure needs exact evidence.
-
-## Local Decision Format
-
-Write JSON with this shape:
+3. Apply the fixes:
+   - Take every decision with `fix`. Use `customInstructions` when present; otherwise `suggestedFix`.
+   - Group fixes by file. Read each file before editing it.
+   - 1-3 simple fixes in a file: edit directly, highest line number first.
+   - 4+ fixes or complex logic in a file: spawn one focused agent with only the file path and its numbered fix list. It reads the file first, applies the fixes from highest line to lowest, introduces no unrelated changes, and reports each item as `APPLIED` or `FAILED`.
+   - Track each finding as `APPLIED`, `FAILED`, or `SKIPPED` (`wont_fix` and `wait`).
+4. Run post-fix verification. This is mandatory after any fix is applied.
+   - Identify the commands from `.5/config.json` and, only as needed, the project manifests (`package.json`, `Makefile`, `pyproject.toml`, `Cargo.toml`, Gradle files).
+   - Run every available command in these categories: `build`, `test`, `e2e`/`test:e2e`, and `lint`. Skip a category only when no command exists or it is configured as `none`; record the reason.
+   - If a command fails, still run the remaining independent categories.
+   - Do not claim the findings are addressed unless every discovered command passes or is skipped because no command exists.
+
+Keep all intermediate summaries compact. Do not paste raw diffs or command logs unless a failure needs exact evidence.
+
+## Decision Format
 
 ```json
 {
@@ -74,7 +64,8 @@ Write JSON with this shape:
       "file": "path/to/file.ts",
       "line": 123,
       "decision": "fix",
-      "recommendation": "fix",
+      "decidedBy": "claude",
+      "reason": "Confirmed off-by-one; local fix",
       "description": "Concise issue summary",
       "suggestedFix": "Concrete fix to apply",
       "customInstructions": ""
@@ -83,7 +74,7 @@ Write JSON with this shape:
 }
 ```
 
-Allowed `decision` values are `fix`, `wont_fix`, and `wait`.
+Allowed `decision` values are `fix`, `wont_fix`, and `wait`. `decidedBy` is `claude` or `user`.
 
 ## Completion
 
@@ -92,13 +83,13 @@ Output:
 ```text
 Review findings addressed: {yes/no}
 
-Local findings: {summary}
-PR comments: {summary}
-PR replies: {posted/failed/skipped with reason}
-Post-fix verification: {passed/failed}
+Fixed on my own: {N} — {one line per finding: id, file, what changed}
+Decided by you: {N} ({fixed} fixed, {deferred} deferred)
+Skipped: {N} — {one line per finding: id, reason}
+Failed: {N}
 Build: {passed/failed/skipped}
 Tests: {passed/failed/skipped}
 E2E: {passed/failed/skipped}
 Lint: {passed/failed/skipped}
-Summary saved at .5/features/{feature}/review-summary-{timestamp}.md
+Decisions saved at .5/features/{feature}/review-decisions-{timestamp}.json
 ```

package/src/commands/5/analyze-feature.md

@@ -30,7 +30,7 @@ Do NOT proceed until you have a clear understanding of what to analyze.
 
 1. Derive a short kebab-case name from the analysis subject (e.g., `user-auth`, `order-processing`, `payment-integration`). This becomes the filename: `{name}-analysis.md`.
 
-2. Identify the relevant modules and layers to analyze. Invoke the `use-index` skill for a quick structural overview. The skill will rebuild the index if stale; fall back to Glob only if the index is missing.
+2. Identify the relevant modules and layers to analyze.
 
 3. Use Glob and Grep to locate the relevant source files. Search for key classes, interfaces, functions, and types related to the analysis subject.
 

package/src/commands/5/configure.md

@@ -1,14 +1,14 @@
 ---
 name: 5:configure
-description: Configures the project. Analyzes project, gathers preferences, writes config.json, and creates .5/features/CONFIGURE/plan.md. Follow up with /5:implement CONFIGURE.
+description: Configures the project. Analyzes project, gathers preferences, writes config.json, points Claude Code plan mode at .5/planning/, and creates .5/planning/CONFIGURE.md. Follow up with /5:implement CONFIGURE.
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
 user-invocable: true
 ---
 
 <role>
 You are a Project Configurator. You analyze a project, gather preferences, and write config.json plus a unified plan.
-You do NOT generate AGENTS.md, CLAUDE.md, documentation files, or skills directly — those are /5:implement's job.
-You write ONLY to: .5/config.json, .5/version.json, .5/features/CONFIGURE/plan.md, and .gitignore.
+You do NOT write AGENTS.md, CLAUDE.md, or rules directly — those are /5:implement's job.
+You write ONLY to: .5/config.json, .5/version.json, .5/planning/CONFIGURE.md, .gitignore, and the `plansDirectory` key of .claude/settings.json (Claude Code only).
 After writing config.json and the unified plan, you are DONE. Exit immediately.
 </role>
 
@@ -18,11 +18,11 @@ Current commit: !`git rev-parse --short HEAD 2>/dev/null || echo "none"`
 
 ## Overview
 
-This command prepares project configuration. It analyzes the project, asks preference questions, writes `.5/config.json`, and writes a unified plan at `.5/features/CONFIGURE/plan.md`.
+This command prepares project configuration. It analyzes the project, asks preference questions, writes `.5/config.json`, points Claude Code plan mode at `.5/planning/`, and writes a plan at `.5/planning/CONFIGURE.md`.
 
 After running this command, proceed through the standard phases:
 1. **`/5:configure`** (this command) - Create config and CONFIGURE plan
-2. `/5:implement CONFIGURE` - Execute configuration (uses `configure-docs-index` and `configure-skills`)
+2. `/5:implement CONFIGURE` - Execute configuration (uses `configure-agents-md` and `configure-rules`)
 3. `/5:review` - Review generated files if desired
 
 ## ⚠️ CRITICAL SCOPE CONSTRAINT
@@ -33,19 +33,19 @@ Your job in this command:
 ✅ Analyze project (detect type, build commands, etc.)
 ✅ Gather user preferences via questions
 ✅ Write `.5/config.json` directly
-✅ Create unified plan at `.5/features/CONFIGURE/plan.md` for remaining work
+✅ Set `plansDirectory` in `.claude/settings.json` (Claude Code only)
+✅ Create the plan at `.5/planning/CONFIGURE.md` for remaining work
 ✅ Tell user to run /5:implement CONFIGURE
 
 Your job is NOT:
-❌ Create AGENTS.md or CLAUDE.md directly (/5:implement does this)
-❌ Generate documentation files directly (/5:implement does this)
-❌ Generate skills directly (/5:implement does this)
+❌ Write AGENTS.md or CLAUDE.md directly (/5:implement does this)
+❌ Generate rules directly (/5:implement does this)
 ❌ Skip user interaction
 ❌ Assume project structure
 
 **After writing config.json, creating the unified plan, and informing the user, YOUR JOB IS COMPLETE. EXIT IMMEDIATELY.**
 
-**If you find yourself creating AGENTS.md, CLAUDE.md, documentation files, or skills, STOP IMMEDIATELY. You should only be writing config.json and the unified plan.**
+**If you find yourself writing AGENTS.md, CLAUDE.md, or rules, STOP IMMEDIATELY. You should only be writing config.json, the settings key, and the plan.**
 
 ## Configuration Process
 
@@ -75,23 +75,16 @@ fi
 
 # Context7 - up-to-date documentation MCP server
 # Check if context7 tools are available (resolve-library-id, query-docs)
-
-# skill-creator plugin — helps create better project-specific skills
-# Check if skill-creator tools are available by looking for known tool names
-# in the current session (e.g., create-skill, scaffold-skill).
-# Set skill_creator_available=true if any skill-creator tool is found.
 ```
 
 **1e. Check AGENTS.md / CLAUDE.md:**
-- If `AGENTS.md` exists, read its content
-- If `AGENTS.md` does not exist but `CLAUDE.md` exists with real content (not just `@AGENTS.md`), read it — this is a legacy setup that will be migrated to AGENTS.md during planning
-
-**1f. Scan existing skills:**
-- Check `.claude/skills/` for existing project-specific skills
-
-**1g. Detect codebase patterns** — Read `.claude/references/configure-tables.md` section "Codebase Pattern Categories to Scan" for the full list and scanning approach.
+- Read `AGENTS.md` and `CLAUDE.md` if they exist. Their content belongs to the repository and stays exactly as it is; the workflow only adds its own marked block to `AGENTS.md` and an `@AGENTS.md` line to `CLAUDE.md`.
+- Note the build/test commands and the commit convention they already document, so the questions below can skip them.
 
-**1h. Detect runnable commands** — Read `.claude/references/configure-tables.md` section "Runnable Command Categories" for categories and scanning approach.
+**1e2. Find repository standards:**
+- Find the files `.claude/skills/review-style/SKILL.md` step 2 counts as repository standards, such as `CONTRIBUTING.md` or `CODESTYLE.md`. Note each path.
+- These always win over the workflow's own rules. AGENTS.md links them, and generated rules must not contradict them.
+- Note whether one of them documents a commit message convention.
 
 ### Step 2: Gather User Preferences (interactive via AskUserQuestion)
 
@@ -149,7 +142,9 @@ If "Cancel": Exit immediately with message "Configuration unchanged."
     1. "No (recommended)" → `git.autoCommit: false`
     2. "Yes - commit after each implementation step" → `git.autoCommit: true`
 
-**2g. Commit message pattern (only if auto-commit = Yes):**
+**2g. Commit message pattern:**
+
+When the repository already documents a commit convention (step 1e or 1e2), that convention wins and AGENTS.md links it. Skip the question, and derive the closest pattern from the convention with the `{ticket-id}` and `{short-description}` placeholders — for example `feat({ticket-id}): {short-description}` for Conventional Commits — and store it as `git.commitMessage.pattern`, so auto-commits follow the convention too. Otherwise ask:
 - "What commit message format would you like?"
   - Options:
     1. "Default: `{ticket-id} {short-description}` (Recommended)"
@@ -170,23 +165,8 @@ Context7 provides up-to-date, version-specific documentation and code examples d
     2. "Skip"
   - If user selects "Install now": execute the install command
 
-**2i. skill-creator plugin:**
-
-The skill-creator plugin from the official Claude store helps generate higher-quality project-specific skills with structured authoring guidance.
-
-- If skill-creator was detected in Step 1d:
-  - "skill-creator plugin is already installed. ✓"
-  - Set `tools.skillCreator.available = true` in the config
-- If skill-creator was NOT detected:
-  - "Would you like to install the skill-creator plugin? It helps generate higher-quality project-specific skills."
-  - Options:
-    1. "Install now (recommended)" — run `claude plugin install skill-creator@claude-plugins-official` via Bash
-    2. "Skip"
-  - If user selects "Install now": execute the install command, then set `tools.skillCreator.available = true` in the config
-  - If user selects "Skip": `tools.skillCreator.available` remains `false`
-
 **2j. Confirm AGENTS.md generation:**
-- "Generate/update AGENTS.md? This will analyze your codebase to document structure and conventions. (A CLAUDE.md shim will also be created for Claude Code compatibility.)"
+- "Add the workflow rules to AGENTS.md? They go into one marked block that links your repository's own standards; nothing else in AGENTS.md or CLAUDE.md changes. CLAUDE.md gets an `@AGENTS.md` line if it lacks one."
   - Options: "Yes (recommended)", "Skip"
 
 **2j2. Confirm rules generation:**
@@ -194,58 +174,12 @@ The skill-creator plugin from the official Claude store helps generate higher-qu
   - Options: "Yes (recommended)", "Skip"
 - Note: Rules complement AGENTS.md — they provide focused, file-type-scoped directives derived from your project's actual conventions.
 
-**2k. Review detected patterns for skill generation:**
-
-Present ONLY patterns that were actually detected in steps 1g and 1h.
-
-**Part 1: Architectural patterns (create-* skills)**
-
-"I analyzed your codebase and found these architectural patterns:
-
-| Pattern | Files Found | Location | Example |
-|---------|-------------|----------|---------|
-| Controller | 12 files | src/controllers/ | UserController.ts |
-| Service | 8 files | src/services/ | AuthService.ts |
-| Component | 25 files | src/components/ | Button.tsx |
-
-Which patterns would you like `create-*` skills generated for?"
-
-- Options: Multi-select checkboxes for each detected pattern (use AskUserQuestion with multiSelect: true)
-- Include descriptions like: "Controller (12 files) - Generate `create-controller` skill"
-- Plus "Other" option for patterns not detected but desired
-
-**Part 2: Command skills (run-* skills)**
-
-"I also found these runnable commands:
-
-| Command | Source | Full Command | Variants |
-|---------|--------|--------------|----------|
-| build | package.json | npm run build | build:prod, build:dev |
-| test | package.json | npm test | test:unit, test:e2e |
-| lint | package.json | npm run lint | lint:fix |
-| format | Makefile | make format | - |
-
-Which commands would you like `run-*` skills generated for?"
-
-- Options: Multi-select checkboxes for each detected command
-- Include descriptions like: "test - Generate `run-tests` skill"
-- Plus "Other" option for commands not detected
-
-If no patterns/commands detected:
-- Inform user: "No common patterns detected. Would you like to specify patterns manually?"
-- Allow manual entry of pattern names/locations or command names
-
-**2l. Git-ignore `.5/features/` folder:**
-- "The `.5/features/` folder will contain unified plans, state files, and review findings. Would you like to add it to `.gitignore`?"
+**2l. Git-ignore workflow folders:**
+- "`.5/planning/` will hold your plans. `.5/features/` will hold implementation state and review findings. Which should git ignore?"
   - Options:
-    1. "Yes, add to .gitignore (recommended)" — workflow artifacts stay local, not tracked in version control
-    2. "No, track in git" — useful if you want to share specs and plans with your team
-
-**2m. Code Conventions:**
-- "Generate `.5/CONVENTIONS.md` with coding conventions for this project? It will include a default set of strict rules (typing, code structure, naming, error handling, testing, and documentation standards) plus project-specific conventions derived from your codebase."
-  - Options:
-    1. "Yes (recommended)" → `conventions.generate: true`
-    2. "Skip" → `conventions.generate: false`
+    1. "Both (recommended)" — workflow artifacts stay local
+    2. "Only `.5/features/`" — share plans with your team, keep state local
+    3. "Neither" — track plans, state, and findings in git
 
 ### Step 2.5: Write config.json
 
@@ -259,7 +193,7 @@ Using the values gathered from Steps 1 and 2, write `.5/config.json` directly.
 mkdir -p .5
 ```
 
-**Schema:** Read `.claude/references/configure-tables.md` section "Config Schema" for the full JSON structure. Fill all values from user responses (including `rules.generate` from step 2j2 and `conventions.generate` from step 2m). Write with pretty-printed JSON. Read back to verify correctness.
+**Schema:** Read `.claude/references/configure-tables.md` section "Config Schema" for the full JSON structure. Fill all values from user responses (including `rules.generate` from step 2j2). Write with pretty-printed JSON. Read back to verify correctness.
 
 **Update `.5/version.json` with configure timestamp:**
 
@@ -269,13 +203,20 @@ After writing config.json, update `.5/version.json` so the reconfigure reminder
 3. Set `configuredAtCommit` to the current short commit hash injected at the top of this command
 4. Write back `.5/version.json` preserving all other fields
 
+**Point plan mode at `.5/planning/` (Claude Code only — skip on Codex):**
+
+Native plan mode must save its plans in `.5/planning/`, where `/5:implement` finds them.
+1. Read `.claude/settings.json` if it exists.
+2. If `plansDirectory` is missing, set it to `".5/planning"` and keep every other key unchanged. Create the file if it does not exist.
+3. If `plansDirectory` already holds a different value, ask whether to switch it to `.5/planning`. Explain that `/5:implement` finds plans only there, unless it gets a plan path.
+4. Inform the user: "Plan mode now saves plans in `.5/planning/`"
+
 **Apply `.gitignore` if selected:**
 
-If the user chose to gitignore the `.5/features/` folder:
-1. Check if `.gitignore` exists in the project root
-2. If it exists, check if `.5/features/` is already listed — if not, append `.5/features/` on a new line
-3. If `.gitignore` does not exist, create it with `.5/features/` as the first entry
-4. Inform the user: "Added `.5/features/` to `.gitignore`"
+For each folder the user chose to ignore in step 2l (`.5/planning/`, `.5/features/`):
+1. Check if `.gitignore` exists in the project root — create it if not
+2. Check if the folder is already listed — if not, append it on a new line
+3. Inform the user which folders were added to `.gitignore`
 
 **Always gitignore `.5/.reconfig-reminder`:**
 
@@ -285,7 +226,7 @@ Ensure `.5/.reconfig-reminder` is gitignored (it's a transient runtime flag that
 
 ### Step 3: Create Configuration Plan
 
-Write `.5/features/CONFIGURE/plan.md` containing all gathered data:
+Write `.5/planning/CONFIGURE.md` containing all gathered data:
 
 ```markdown
 ---
@@ -297,131 +238,86 @@ created: {ISO-timestamp}
 # Plan: CONFIGURE - Project Configuration
 
 ## Overview
-Generates AGENTS.md, CLAUDE.md shim, a rebuildable codebase index, and project-specific skills. (config.json already written.)
+Adds the workflow block to AGENTS.md, includes AGENTS.md from CLAUDE.md, and generates scoped rules. (config.json and the plans directory setting are already written.)
 
 ## What Changes
 
-- Generate focused documentation and a rebuildable codebase index.
-- Generate selected project-specific skills and scoped rules.
-- Preserve existing user-authored AGENTS.md/CLAUDE.md content.
+- Write the workflow block into AGENTS.md, linking the repository's own standards.
+- Generate scoped rules from detected conventions, when selected.
+- Leave all existing AGENTS.md/CLAUDE.md content unchanged.
 
 ## Existing Patterns to Follow
 
-- `.claude/skills/configure-docs-index/SKILL.md` - documentation and index generation behavior.
-- `.claude/skills/configure-skills/SKILL.md` - skill and rule generation behavior.
+- `.claude/skills/configure-agents-md/SKILL.md` - the AGENTS.md block and the CLAUDE.md include.
+- `.claude/skills/configure-rules/SKILL.md` - rule generation behavior.
 
 ## Constraints
 
 - config.json is already written by `/5:configure`.
-- Do not generate empty placeholder documentation or index files.
-- Preserve user-authored sections in AGENTS.md.
+- Repository standards win over the workflow's own rules. Generated rules must not restate or contradict them.
+- Change nothing outside the foifi block in AGENTS.md, and only append `@AGENTS.md` to CLAUDE.md.
+- Never rewrite or delete existing `.5/*.md` docs. Teams may maintain them.
 
 ## Scope
 
 ### In
 
-- Documentation files under `.5/`.
-- `.5/index/` and rebuild script.
-- AGENTS.md plus CLAUDE.md shim.
-- Selected create/run skills.
+- The foifi block in AGENTS.md plus the CLAUDE.md include.
 - Selected scoped rules.
 
 ### Out
 
 - Changing preferences already saved in `.5/config.json`.
+- Generated architecture, testing, concerns, or conventions docs, codebase indexes, and project-specific skills.
 
 ## Acceptance Criteria
 
-- [ ] `.5/ARCHITECTURE.md` exists when architecture knowledge was found.
-- [ ] `.5/TESTING.md` exists when test knowledge was found.
-- [ ] `.5/CONCERNS.md` exists only if concerns were found.
-- [ ] `.5/CONVENTIONS.md` exists when `conventions.generate` is true.
-- [ ] `.5/index/rebuild-index.sh` exists and rebuilds the index.
-- [ ] `.5/index/README.md` documents generated index files.
-- [ ] `AGENTS.md` references created `.5/` files and the index rebuild rule.
-- [ ] `CLAUDE.md` contains only `@AGENTS.md`.
-- [ ] Selected project-specific skills are generated in `.claude/skills/`.
-- [ ] Selected scoped rules are generated in `.claude/rules/`.
-- [ ] User-written AGENTS.md/CLAUDE.md content is preserved.
+- [ ] The foifi block in `AGENTS.md` links every repository standard listed below.
+- [ ] `CLAUDE.md` includes `@AGENTS.md`.
+- [ ] Selected scoped rules are generated in `.claude/rules/` — on Codex, as the `File-Scoped Rules` section in the foifi block of `AGENTS.md` instead.
+- [ ] Content outside the foifi block in AGENTS.md and CLAUDE.md is byte-for-byte unchanged.
 
 ## Decisions
 
-- [DECIDED] Use the detected project type, build command, test command, ticket settings, review tool, and selected patterns from this configure session.
-- [FLEXIBLE] Omit optional generated files when no useful project knowledge exists.
+- [DECIDED] Use the detected project type, build command, test command, ticket settings, and commit convention from this configure session.
+- [FLEXIBLE] Omit optional rules when no useful project knowledge exists.
 - [DEFERRED] Further preference changes; rerun `/5:configure` for those.
 
 ## Module Impact
 
 | Module/Area | Impact |
 |-------------|--------|
-| `.5/` | Create/update documentation and index artifacts. |
-| `AGENTS.md` / `CLAUDE.md` | Create or update provider instructions. |
-| `.claude/skills/` | Create selected project-specific skills. |
-| `.claude/rules/` | Create selected scoped rules. |
+| `AGENTS.md` / `CLAUDE.md` | Add or refresh the foifi block; include AGENTS.md from CLAUDE.md. |
+| `.claude/rules/` (Codex: `AGENTS.md`) | Create selected scoped rules. |
 
 ## Component Checklist
 
 | Component | Action | Target Path | Intent |
 |-----------|--------|-------------|--------|
-| configure docs and index | create | `.5/` | Generate project documentation, codebase index, AGENTS.md, and CLAUDE.md shim. |
-| configure skills and rules | create | `.claude/skills/` | Generate selected create/run skills and scoped rules from detected conventions. |
+| configure agents md | modify | `AGENTS.md` | Write the foifi block into AGENTS.md and include it from CLAUDE.md, linking the repository standards. |
+| configure rules | create | `.claude/rules/` (Codex: `AGENTS.md`) | After configure agents md: generate scoped rules from detected conventions — on Codex, as the `File-Scoped Rules` section in the foifi block of `AGENTS.md`. |
 
 ## Technical Notes
 
-Analyze the codebase and generate focused documentation capturing only non-derivable knowledge (skip version numbers, dependency lists, directory layouts, linter configs — Claude Code can look these up directly):
-
-**Create documentation files in `.5/` folder:**
-- `.5/ARCHITECTURE.md` - Architecture pattern, layers & data flow, key abstractions, non-obvious conventions, where to add new code
-- `.5/TESTING.md` - Test organization, patterns, mocking approach, gotchas
-- `.5/CONCERNS.md` - Tech debt, known issues, security/integration/performance notes (**only if concerns found — skip file entirely if nothing detected**)
-- `.5/CONVENTIONS.md` - Default strict coding conventions plus project-specific conventions derived from codebase analysis (**only when `conventions.generate` is true**)
-
-**Create a rebuildable codebase index in `.5/index/`:**
-- Generate a repository-local script at `.5/index/rebuild-index.sh`
-- Generate multiple focused Markdown index files in `.5/index/` plus `.5/index/README.md`
-- Keep the index generic and adapted to the actual project
-- Skip empty categories; do not create placeholder index files
-- Re-running the script should fully refresh the index in place
-
-**Create AGENTS.md** (provider-agnostic instructions file):
-- Use `.claude/templates/AGENTS.md` as the source template
-- Fill `{PROJECT_OVERVIEW}` with 1-2 sentences from README/package.json
-- Fill `{BUILD_RUN_COMMANDS}` with build, test, and other detected commands
-- Fill `{PROJECT_DOCUMENTATION_LINKS}` with whichever `.5/` documentation files were created
-- Fill `{CODEBASE_INDEX_LINKS}` with `.5/index/README.md`, generated index files, and `.5/index/rebuild-index.sh`
-- Fill `{CUSTOM_DOCUMENTATION}` with preserved user-authored sections under `## Custom Documentation`; remove the placeholder if there is no custom content
-- Preserve static template sections exactly as written, including skill usage, commit messages, workflow rules, coding guidelines, simplicity, testing, surgical changes, goal-driven execution, and index freshness
-
-**Create CLAUDE.md shim:**
-- Contains only `@AGENTS.md` (Claude Code include syntax)
-
-**Migrate and preserve existing content:**
-- If AGENTS.md already exists, preserve user-written custom sections
-- If CLAUDE.md exists with real content (not just `@AGENTS.md`), migrate content to AGENTS.md and replace CLAUDE.md with the shim
-
-### Requirement 2: Generate Project-Specific Skills
-Handled by: `configure-skills`
-
-**Create-* skills** for each user-selected architectural pattern:
-- Skill name: `create-{pattern}` (e.g., `create-controller`, `create-service`)
-- Analyze 2-3 existing files, extract conventions, generate SKILL.md with project-specific template
-- Set `user-invocable: true`, `model: haiku`
+### Requirement 1: Write AGENTS.md
+Handled by: `configure-agents-md`
 
-**Run-* skills** for each user-selected command:
-- Skill name: `run-{category}` (e.g., `run-tests`, `run-lint`)
-- Document exact command syntax, variants, flags
-- Set `user-invocable: true`, `model: haiku`
+**Repository standards found:**
+- {one bullet per path from step 1e2, or "none found"}
 
-Include only patterns/commands where user selected "Generate".
+**Write the foifi block into AGENTS.md** as `configure-agents-md` describes:
+- Fill the template from `.claude/templates/AGENTS.md`: build/run commands, the commit message rule, the repository standards above, and links to existing `.5/*.md` docs
+- Never change content outside the block; append `@AGENTS.md` to CLAUDE.md only when it lacks that line
 
-### Requirement 3: Generate Scoped Rules (if selected)
-Handled by: `configure-skills`
+### Requirement 2: Generate Scoped Rules (if selected)
+Handled by: `configure-rules`. Runs after Requirement 1: on Codex, Codex reads only `AGENTS.md`, so the rules go into its foifi block instead of rule files.
 
 Generate `.claude/rules/` files with project-specific conventions scoped to relevant file types.
 Rules are concise directives (15-40 lines, NOT documentation) derived from codebase analysis.
+They must not restate or contradict the repository standards above.
 Only generate rules for patterns that were actually detected:
 - `code-style.md` — naming, formatting, import conventions (scoped to source files)
-- `testing.md` — test patterns, mocking, fixtures (scoped to test files)
+- `testing.md` — test patterns, mocking, fixtures, gotchas (scoped to test files)
 - `api-patterns.md` — API conventions, error handling (scoped to API/route/controller files)
 - `dependencies.md` — dependency usage patterns, env var conventions (unconditional)
 
@@ -430,19 +326,19 @@ Only generate rules for patterns that were actually detected:
 1. Run `/5:implement CONFIGURE`.
 ```
 
-**Important:** Use `mkdir -p .5/features/CONFIGURE` before writing the unified plan.
+**Important:** Use `mkdir -p .5/planning` before writing the plan.
 
 ### Step 4: Guide User to Next Phase
 
 Tell the user:
 
 1. "Configuration saved to `.5/config.json`"
-2. "Configuration plan written to `.5/features/CONFIGURE/plan.md`"
+2. "Configuration plan written to `.5/planning/CONFIGURE.md`"
 3. "Next steps:"
    - "Run `/clear` to reset context"
    - "Then run `/5:implement CONFIGURE`"
 4. "After that: Run `/5:review` if you want a review of generated files"
 
 ## Related Documentation
-- [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)

package/src/commands/5/eject.md

@@ -54,7 +54,6 @@ Tell the user what ejecting means:
 > For Codex installs:
 > - `.codex/skills/5-update/` (update skill)
 > - `.codex/skills/5-eject/` (this skill)
-> - `.codex/instructions.md` is removed only if it is workflow-managed and no longer needed for remaining installed workflow files
 >
 > All other workflow files remain untouched. To restore updates later, reinstall with `npx foifi`.