Merge pull request #151 from zevorn/codex/feature-capability-map

Add capability map to gen-plan

Author: zevorn

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
@@ -58,6 +59,7 @@ Requires [codex CLI](https://github.com/openai/codex) for review. See the full [
    /humanize:gen-plan --input .humanize/explore/<run-id>/final-idea.md --output docs/plan.md
    ```
    Add `--coach` to run mandatory short-answer stage quizzes after each planning stage. Normal plan decision questions stay separate; quiz mismatches are treated as design drift, AI design correction, or background gaps before the agent expands the next planning layer.
+   Generated plans include a `Feature Map / Capability Map` before the task breakdown so each task carries its global capability context.
 
 4. **Refine an annotated plan** before implementation when reviewers add comments (`CMT:` ... `ENDCMT`, `<cmt>` ... `</cmt>`, or `<comment>` ... `</comment>`):
    ```bash
@@ -68,6 +70,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.
 
 6. **Consult Gemini** for deep web research (requires Gemini CLI):
    ```bash

commands/gen-plan.md

@@ -533,6 +533,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:
@@ -636,7 +645,9 @@ When `alternative_plan_language` is empty, absent, set to `"English"`, or set to
 
 18. **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.
 
-19. **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).
+19. **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 `-`.
+
+20. **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
@@ -173,9 +181,13 @@ Workflow:
 3. Analyzes draft for clarity, consistency, completeness, and functionality
 4. Engages user to resolve any issues found
 5. When `--coach` is enabled, runs mandatory stage quizzes after each planning stage; normal plan decision questions stay separate, and quiz mismatches become design drift, AI design corrections, or background gaps before overall acceptance
-6. Generates a structured plan.md with acceptance criteria
+6. Generates a structured plan.md with acceptance criteria, capability map, and task routing tags
 7. 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

@@ -1439,6 +1439,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
 }
 
@@ -1566,11 +1574,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" \
@@ -2054,6 +2063,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}}
@@ -2069,7 +2079,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