[codex] Add capability map to gen-plan

README.md

@@ -15,6 +15,7 @@ A Claude Code plugin that provides iterative development with independent AI rev
 - **Iteration over Perfection** -- Instead of expecting perfect output in one shot, Humanize leverages continuous feedback loops where issues are caught early and refined incrementally.
 - **One Build + One Review** -- Claude implements, Codex independently reviews. No blind spots.
 - **Ralph Loop with Swarm Mode** -- Iterative refinement continues until all acceptance criteria are met. Optionally parallelize with Agent Teams.
+- **Capability Anchors** -- Generated plans include a feature/capability map, and RLCR rounds keep Claude and Codex anchored to the relevant capability node.
 - **Begin with the End in Mind** -- Before the loop starts, Humanize verifies that *you* understand the plan you are about to execute. The human must remain the architect. ([Details](docs/usage.md#begin-with-the-end-in-mind))
 
 ## How It Works
@@ -51,6 +52,7 @@ Requires [codex CLI](https://github.com/openai/codex) for review. See the full [
    ```bash
    /humanize:gen-plan --input draft.md --output docs/plan.md
    ```
+   Generated plans include a `Feature Map / Capability Map` before the task breakdown so each task carries its global capability context.
 
 3. **Refine an annotated plan** before implementation when reviewers add comments (`CMT:` ... `ENDCMT`, `<cmt>` ... `</cmt>`, or `<comment>` ... `</comment>`):
    ```bash
@@ -61,6 +63,7 @@ Requires [codex CLI](https://github.com/openai/codex) for review. See the full [
    ```bash
    /humanize:start-rlcr-loop docs/plan.md
    ```
+   When the plan has a capability map, RLCR records a `Capability Anchor` in each round contract and Goal Tracker active task so Claude coding and Codex review stay aligned with the map.
 
 5. **Consult Gemini** for deep web research (requires Gemini CLI):
    ```bash

commands/gen-plan.md

@@ -444,6 +444,15 @@ Example: "The implementation includes core feature X with basic validation"
 
 <Describe relative dependencies between components, not time estimates>
 
+## Feature Map / Capability Map
+
+Use this section to map feature- or capability-level dependencies and context. It supplements `## Task Breakdown` by showing how related tasks carry business, design, and implementation context across the plan; it is not a replacement for executable tasks.
+
+| Capability ID | Capability / Feature | Target ACs | Depends On | Context Summary | Implementation Surface |
+|---------------|----------------------|------------|------------|-----------------|------------------------|
+| cap1 | <User-facing or internal capability> | AC-1, AC-2 | - | Business: <why this matters>; Design: <expected behavior/UX/API>; Implementation: <state, data, or integration context to preserve> | <files/modules/components likely involved> |
+| cap2 | <Dependent capability> | AC-3 | cap1 | Business: <dependency rationale>; Design: <constraints inherited from cap1>; Implementation: <interfaces or decisions reused from cap1> | <files/modules/components likely involved> |
+
 ## Task Breakdown
 
 Each task must include exactly one routing tag:
@@ -526,7 +535,9 @@ When `alternative_plan_language` is empty, absent, set to `"English"`, or set to
 
 13. **Convergence Requirement**: The plan MUST record Claude/Codex agreements, resolved disagreements, and final convergence status in `## Claude-Codex Deliberation`. Stop only when convergence conditions are met or max rounds reached with explicit carry-over decisions.
 
-14. **Task Tag Requirement**: The plan MUST include `## Task Breakdown`, and every task MUST be tagged as either `coding` or `analyze` (no untagged tasks, no other tag values).
+14. **Feature Map Requirement**: The plan MUST include `## Feature Map / Capability Map` before `## Task Breakdown`. Use it to group tasks into feature/capability nodes, record capability dependencies, and preserve business/design/implementation context that later implementation rounds should carry forward. Capability IDs must be stable and dependency references must point to existing capability IDs or `-`.
+
+15. **Task Tag Requirement**: The plan MUST include `## Task Breakdown`, and every task MUST be tagged as either `coding` or `analyze` (no untagged tasks, no other tag values).
 
 ---
 

commands/refine-plan.md

@@ -412,6 +412,7 @@ The refined plan MUST retain these required sections:
 
 Optional sections that MUST be preserved when present in the input:
 
+- `## Feature Map / Capability Map`
 - `## Codex Team Workflow`
 - `## Convergence Log`
 - `--- Original Design Draft Start ---` appendix and its matching end marker

commands/start-rlcr-loop.md

@@ -142,19 +142,20 @@ This loop uses a **Goal Tracker** to prevent goal drift across iterations:
 
 ### Structure
 - **IMMUTABLE SECTION**: Ultimate Goal and Acceptance Criteria (set in Round 0, never changed)
-- **MUTABLE SECTION**: Active Tasks, Completed Items, Deferred Items, Plan Evolution Log
+- **MUTABLE SECTION**: Active Tasks, Capability anchors, Completed Items, Deferred Items, Plan Evolution Log
 
 ### Key Features
 1. **Acceptance Criteria**: Each task maps to a specific AC - nothing can be "forgotten"
-2. **Task Tag Routing**: Every task should carry `coding` or `analyze` tag from plan generation
+2. **Capability Anchors**: When the plan has `Feature Map / Capability Map`, each mainline task and round contract records the relevant capability node
+3. **Task Tag Routing**: Every task should carry `coding` or `analyze` tag from plan generation
    - `coding -> Claude`, `analyze -> Codex`
-3. **Plan Evolution Log**: If you discover the plan needs changes, document the change with justification
-4. **Explicit Deferrals**: Deferred tasks require strong justification and impact analysis
-5. **Full Alignment Checks**: At configurable intervals (default every 5 rounds: rounds 4, 9, 14, etc.), Codex conducts a comprehensive goal alignment audit. Use `--full-review-round N` to customize (min: 2)
+4. **Plan Evolution Log**: If you discover the plan needs changes, document the change with justification
+5. **Explicit Deferrals**: Deferred tasks require strong justification and impact analysis
+6. **Full Alignment Checks**: At configurable intervals (default every 5 rounds: rounds 4, 9, 14, etc.), Codex conducts a comprehensive goal alignment audit. Use `--full-review-round N` to customize (min: 2)
 
 ### How to Use
 1. **Round 0**: Initialize the Goal Tracker with Ultimate Goal and Acceptance Criteria
-2. **Each Round**: Update task status, log plan changes, note discovered issues
+2. **Each Round**: Update task status, capability anchors, log plan changes, note discovered issues
 3. **Before Exit**: Ensure goal-tracker.md reflects current state accurately
 
 ## Important Rules

docs/usage.md

@@ -11,6 +11,11 @@ Humanize creates an iterative feedback loop with two phases:
 
 The loop continues until all acceptance criteria are met or no issues remain.
 
+When a plan includes `Feature Map / Capability Map`, RLCR also tracks a per-round
+`Capability Anchor`. Claude uses it to keep implementation tied to the relevant
+business, design, and implementation context, while Codex reviews capability-map
+alignment alongside normal acceptance criteria.
+
 ## Begin with the End in Mind
 
 Before the RLCR loop starts any work, Humanize runs a **Plan Understanding Quiz** -- a brief pre-flight check that verifies you genuinely understand the plan you are about to execute.
@@ -46,6 +51,9 @@ The quiz is advisory, not a gate. You always have the option to proceed. But tha
    ```bash
    /humanize:gen-plan --input draft.md --output docs/plan.md
    ```
+   The generated plan includes a `Feature Map / Capability Map` that records
+   capability dependencies and context before tasks are split into executable
+   `coding` and `analyze` work.
 2. If the plan is reviewed with comment annotations, refine it and generate a QA ledger:
    ```bash
    /humanize:refine-plan --input docs/plan.md
@@ -122,9 +130,13 @@ Workflow:
 2. Checks if draft is relevant to the repository
 3. Analyzes draft for clarity, consistency, completeness, and functionality
 4. Engages user to resolve any issues found
-5. Generates a structured plan.md with acceptance criteria
+5. Generates a structured plan.md with acceptance criteria, capability map, and task routing tags
 6. Optionally starts `/humanize:start-rlcr-loop` if `--auto-start-rlcr-if-converged` conditions are met
 
+The capability map supplements the task breakdown: it tells Claude and Codex
+which global feature or capability each task belongs to, what it depends on, and
+which business/design/implementation context must be preserved during RLCR.
+
 If reviewers later annotate the generated plan with comment blocks, run
 `/humanize:refine-plan --input <plan.md>` before starting or resuming implementation.
 

hooks/loop-codex-stop-hook.sh

@@ -1415,6 +1415,14 @@ Follow the plan's per-task routing tags strictly:
 - `coding` task -> Claude executes directly
 - `analyze` task -> execute via `/humanize:ask-codex`, then integrate the result
 - Keep Goal Tracker Active Tasks columns `Tag` and `Owner` aligned with execution
+
+## Capability Anchor Reminder
+
+If the plan contains `## Feature Map / Capability Map`:
+- The round contract must name the relevant Capability ID(s) or capability/feature name(s)
+- Goal Tracker Active Tasks must keep their `Capability` column aligned with the round contract
+- Mainline work must preserve the selected capability's business, design, and implementation context
+- Do not let queued or future-scope capability work take over the current round
 ROUTING_EOF
 }
 
@@ -1542,11 +1550,12 @@ You are in the **Review Phase** of the RLCR loop. Codex has performed a code rev
 ## Instructions
 
 1. Re-anchor on the original plan and current goal tracker before changing code
-2. Refresh the round contract at {{ROUND_CONTRACT_FILE}}
+2. Refresh the round contract at {{ROUND_CONTRACT_FILE}}, including its Capability Anchor when the plan has a capability map
 3. Address only the issues that are truly blocking the current mainline objective or code-review acceptance
-4. Record non-blocking follow-up items as queued, not as the main goal
-5. Commit your changes after fixing the issues
-6. Write your summary to: {{SUMMARY_FILE}}"
+4. Keep fixes inside the current Capability Anchor unless review proves it was wrong
+5. Record non-blocking follow-up items as queued, not as the main goal
+6. Commit your changes after fixing the issues
+7. Write your summary to: {{SUMMARY_FILE}}"
 
     load_and_render_safe "$TEMPLATE_DIR" "claude/review-phase-prompt.md" "$fallback" \
         "REVIEW_CONTENT=$review_content" \
@@ -2030,6 +2039,7 @@ Before executing tasks in this round:
 1. Read @{{BITLESSON_FILE}}
 2. Run \`bitlesson-selector\` for each task/sub-task
 3. Follow selected lesson IDs (or \`NONE\`)
+4. Preserve the Capability Anchor from @{{ROUND_CONTRACT_FILE}} when the plan has a capability map
 
 ## Codex Review
 {{REVIEW_CONTENT}}
@@ -2045,7 +2055,7 @@ Before writing code:
 - Re-read @{{PLAN_FILE}}
 - Re-read @{{GOAL_TRACKER_FILE}}
 - Re-read the recent round summaries and review results
-- Rewrite @{{ROUND_CONTRACT_FILE}} with a recovery-focused mainline objective
+- Rewrite @{{ROUND_CONTRACT_FILE}} with a recovery-focused mainline objective and Capability Anchor
 
 Do not spend this round clearing queued work. Recover mainline progress first.
 

prompt-template/block/round-contract-missing.md

@@ -6,6 +6,7 @@ Before you try to exit this round, write the current round contract to:
 The round contract must restate:
 - The single **mainline objective** for this round
 - The target ACs
+- The Capability Anchor for this round, or `N/A` when the plan has no `Feature Map / Capability Map`
 - Which issues are truly **blocking**
 - Which issues are **queued** and out of scope
 - The concrete success criteria for this round

prompt-template/claude/drift-replan-prompt.md

@@ -25,6 +25,7 @@ Before changing code:
 Your recovery contract must contain:
 - Exactly one recovered **mainline objective**
 - The 1-2 target ACs that prove mainline progress this round
+- The recovered **Capability Anchor**: relevant `Feature Map / Capability Map` node(s), or `N/A` if the plan has no capability map
 - The root cause of recent drift or stagnation
 - Which issues are truly **blocking** the recovered mainline objective
 - Which issues remain **queued** and explicitly out of scope
@@ -56,6 +57,7 @@ Below is Codex's review result:
 
 Before starting work, **read and update** @{{GOAL_TRACKER_FILE}} as needed:
 - Keep the immutable section unchanged
+- Re-anchor Active Tasks on the recovered Capability Anchor when the plan has a `Feature Map / Capability Map`
 - Record the drift/stagnation cause in the mutable section if it changed planning
 - Keep blocking vs queued issue classification accurate
 - Ensure the tracker and contract now describe the same recovered mainline objective
@@ -64,5 +66,6 @@ Before starting work, **read and update** @{{GOAL_TRACKER_FILE}} as needed:
 
 - Do not spend this round mostly on queued cleanup
 - Do not broaden scope to compensate for previous stalls
+- Do not jump to unrelated or future-scope capability nodes to compensate for previous stalls
 - If the original approach was flawed, log the plan evolution explicitly instead of silently changing direction
 - If you cannot produce a credible recovered mainline objective, say so in the summary with concrete blockers

prompt-template/claude/next-round-prompt.md

@@ -20,6 +20,7 @@ Before writing code:
 Your round contract must contain:
 - Exactly one **mainline objective**
 - The 1-2 target ACs for this round
+- The **Capability Anchor**: relevant `Feature Map / Capability Map` node(s), or `N/A` if the plan has no capability map
 - Which issues are truly **blocking** that mainline objective
 - Which issues are **queued** and explicitly out of scope
 - Concrete success criteria for this round
@@ -55,6 +56,7 @@ Below is Codex's review result:
 
 Before starting work, **read** @{{GOAL_TRACKER_FILE}} to understand:
 - The Ultimate Goal and Acceptance Criteria you're working toward
+- Which Capability each Active Task belongs to, when the plan has a `Feature Map / Capability Map`
 - Which tasks are Active, Completed, or Deferred
 - Which side issues are blocking vs queued
 - Any Plan Evolution that has occurred
@@ -67,6 +69,8 @@ If you cannot safely reconcile the tracker yourself, include an optional "Goal T
 ## Mainline Guardrails
 
 - Keep the mainline objective from @{{ROUND_CONTRACT_FILE}} stable for this round
+- Keep the Capability Anchor from @{{ROUND_CONTRACT_FILE}} stable for this round
+- Before implementing each mainline task, restate how it fits the anchored capability's business, design, and implementation context
 - Do not let queued issues take over the round
 - If Codex reported several findings, classify them into:
   - mainline gaps

prompt-template/claude/review-phase-prompt.md

@@ -10,6 +10,7 @@ Before touching code:
 - Refresh the current round contract at @{{ROUND_CONTRACT_FILE}}
 
 The round contract must preserve a single mainline objective. Code review findings do NOT automatically become the new round objective.
+If the original plan contains `## Feature Map / Capability Map`, the refreshed contract must also preserve or update the current Capability Anchor intentionally.
 
 ## Review Results
 
@@ -35,9 +36,10 @@ Do not create new `[mainline]` tasks in review phase unless the review proves th
 
 1. **Refresh the round contract** at `{{ROUND_CONTRACT_FILE}}`
 2. **Address blocking issues first** and keep the mainline objective stable
-3. **Focus on fixes only** - do not add new features or make unrelated changes
-4. **Commit your changes** after fixing the issues
-5. **Write your summary** to: `{{SUMMARY_FILE}}`
+3. **Keep fixes inside the Capability Anchor** unless the review proves the anchor was wrong
+4. **Focus on fixes only** - do not add new features or make unrelated changes
+5. **Commit your changes** after fixing the issues
+6. **Write your summary** to: `{{SUMMARY_FILE}}`
 
 ## Summary Template
 

prompt-template/codex/full-alignment-review.md

@@ -65,16 +65,32 @@ Queued Side Issues: N
 
 The `Mainline Progress Verdict` line is mandatory. If you omit it, the Humanize stop hook will block the round and require the review to be rerun.
 
-## Part 3: Implementation Review
+## Part 3: Capability Map Alignment Check (MANDATORY when present)
+
+If the original plan contains `## Feature Map / Capability Map`, verify:
+
+1. **Capability Anchor**: Do the recent round contracts and Active Tasks identify the capability node(s) they are advancing?
+2. **Context Preservation**: Has implementation preserved each anchored capability's business, design, and implementation context?
+3. **Dependency Respect**: Were prerequisite capability nodes completed or consciously carried forward before dependent work?
+4. **Scope Control**: Are queued or future-scope capability nodes taking over recent rounds?
+
+Include a short capability summary:
+```
+Capability anchors reviewed: ...
+Dependency gaps: N
+Capability scope drift: yes/no
+```
+
+## Part 4: Implementation Review
 
 - Conduct a deep critical review of the implementation
 - Verify Claude's claims match reality
 - Identify any gaps, bugs, or incomplete work
 - Reference @{{DOCS_PATH}} for design documents
 
-## Part 4: {{GOAL_TRACKER_UPDATE_SECTION}}
+## Part 5: {{GOAL_TRACKER_UPDATE_SECTION}}
 
-## Part 5: Progress Stagnation Check (MANDATORY for Full Alignment Rounds)
+## Part 6: Progress Stagnation Check (MANDATORY for Full Alignment Rounds)
 
 To implement the original plan at @{{PLAN_FILE}}, we have completed **{{COMPLETED_ITERATIONS}} iterations** (Round 0 to Round {{CURRENT_ROUND}}).
 
@@ -101,14 +117,14 @@ The project's `.humanize/rlcr/{{LOOP_TIMESTAMP}}/` directory contains the histor
 
 **If development is stagnating**, write **STOP** (as a single word on its own line) as the last line of your review output @{{REVIEW_RESULT_FILE}} instead of COMPLETE.
 
-## Part 6: Output Requirements
+## Part 7: Output Requirements
 
 - If issues found OR any AC is NOT MET (including deferred ACs), write your findings to @{{REVIEW_RESULT_FILE}}
 - Include specific action items for Claude to address, classified into:
   - Mainline Gaps
   - Blocking Side Issues
   - Queued Side Issues
-- **If development is stagnating** (see Part 4), write "STOP" as the last line
+- **If development is stagnating** (see Part 6), write "STOP" as the last line
 - **CRITICAL**: Only write "COMPLETE" as the last line if ALL ACs from the original plan are FULLY MET with no deferrals
   - DEFERRED items are considered INCOMPLETE - do NOT output COMPLETE if any AC is deferred
   - The ONLY condition for COMPLETE is: all original plan tasks are done, all ACs are met, no deferrals allowed

prompt-template/codex/regular-review.md

@@ -46,7 +46,21 @@ Include a brief Goal Alignment Summary in your review:
 ACs: X/Y addressed | Forgotten items: N | Unjustified deferrals: N
 ```
 
-## Part 3: Required Finding Classification
+## Part 3: Capability Map Alignment Check (MANDATORY when present)
+
+If the original plan contains `## Feature Map / Capability Map`, verify:
+
+1. **Capability Anchor**: Did Claude's round contract and Active Tasks identify the relevant capability node(s)?
+2. **Context Preservation**: Did the implementation preserve the anchored capability's business, design, and implementation context?
+3. **Dependency Respect**: Did Claude respect capability dependencies instead of skipping prerequisite nodes?
+4. **Scope Control**: Did Claude avoid drifting into unrelated or future-scope capability nodes?
+
+Include a brief Capability Alignment Summary:
+```
+Capability anchor: cap-id/name or N/A | Dependency gaps: N | Scope drift: yes/no
+```
+
+## Part 4: Required Finding Classification
 
 You MUST classify your findings into these lanes:
 - **Mainline Gaps**: plan-derived work or AC progress that is missing, incomplete, or regressing
@@ -62,9 +76,9 @@ This verdict line is mandatory. If you omit it, the Humanize stop hook will bloc
 
 If Claude mostly worked on queued side issues and failed to advance the mainline, say so explicitly.
 
-## Part 4: {{GOAL_TRACKER_UPDATE_SECTION}}
+## Part 5: {{GOAL_TRACKER_UPDATE_SECTION}}
 
-## Part 5: Output Requirements
+## Part 6: Output Requirements
 
 - In short, your review comments can include: problems/findings/blockers; claims that don't match reality; implementation plans for deferred work (to be implemented now); implementation plans for unfinished work; goal alignment issues.
 - Your output should be structured so Claude can tell which items are mainline gaps, blocking side issues, and queued side issues.