diff --git a/README.md b/README.md index b28312aa..d59ce863 100644 --- a/README.md +++ b/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`, `` ... ``, or `` ... ``): ```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 diff --git a/commands/gen-plan.md b/commands/gen-plan.md index 3b97435e..960c43a5 100644 --- a/commands/gen-plan.md +++ b/commands/gen-plan.md @@ -444,6 +444,15 @@ Example: "The implementation includes core feature X with basic validation" +## 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 | | AC-1, AC-2 | - | Business: ; Design: ; Implementation: | | +| cap2 | | AC-3 | cap1 | Business: ; Design: ; Implementation: | | + ## 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). --- diff --git a/commands/refine-plan.md b/commands/refine-plan.md index 0d97142f..9b196f65 100644 --- a/commands/refine-plan.md +++ b/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 diff --git a/commands/start-rlcr-loop.md b/commands/start-rlcr-loop.md index f24fb156..15b86888 100644 --- a/commands/start-rlcr-loop.md +++ b/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 diff --git a/docs/usage.md b/docs/usage.md index 658733a1..110c8e09 100644 --- a/docs/usage.md +++ b/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 ` before starting or resuming implementation. diff --git a/hooks/loop-codex-stop-hook.sh b/hooks/loop-codex-stop-hook.sh index 0c191d4c..75498431 100755 --- a/hooks/loop-codex-stop-hook.sh +++ b/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. diff --git a/prompt-template/block/round-contract-missing.md b/prompt-template/block/round-contract-missing.md index 35a822b1..7d35a8d3 100644 --- a/prompt-template/block/round-contract-missing.md +++ b/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 diff --git a/prompt-template/claude/drift-replan-prompt.md b/prompt-template/claude/drift-replan-prompt.md index a5970c59..2eb2ab4b 100644 --- a/prompt-template/claude/drift-replan-prompt.md +++ b/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 diff --git a/prompt-template/claude/next-round-prompt.md b/prompt-template/claude/next-round-prompt.md index fd1b1cfe..06aea74d 100644 --- a/prompt-template/claude/next-round-prompt.md +++ b/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 diff --git a/prompt-template/claude/review-phase-prompt.md b/prompt-template/claude/review-phase-prompt.md index e180e418..f67e70a4 100644 --- a/prompt-template/claude/review-phase-prompt.md +++ b/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 diff --git a/prompt-template/codex/full-alignment-review.md b/prompt-template/codex/full-alignment-review.md index 4367810e..0be2d87d 100644 --- a/prompt-template/codex/full-alignment-review.md +++ b/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 diff --git a/prompt-template/codex/regular-review.md b/prompt-template/codex/regular-review.md index 4d4a8680..1b673987 100644 --- a/prompt-template/codex/regular-review.md +++ b/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. diff --git a/prompt-template/plan/gen-plan-template.md b/prompt-template/plan/gen-plan-template.md index ebdd2d98..37c7f8a0 100644 --- a/prompt-template/plan/gen-plan-template.md +++ b/prompt-template/plan/gen-plan-template.md @@ -66,6 +66,15 @@ Example: "The implementation includes core feature X with basic validation" +## 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 | | AC-1, AC-2 | - | Business: ; Design: ; Implementation: | | +| cap2 | | AC-3 | cap1 | Business: ; Design: ; Implementation: | | + ## Task Breakdown Each task must include exactly one routing tag: diff --git a/scripts/setup-rlcr-loop.sh b/scripts/setup-rlcr-loop.sh index 15326bc4..e95618f8 100755 --- a/scripts/setup-rlcr-loop.sh +++ b/scripts/setup-rlcr-loop.sh @@ -977,9 +977,9 @@ $PLAN_AC_CONTENT | 0 | Skip implementation mode initialized around explicit plan anchor | Loop started with \`--skip-impl\` and retained @$PLAN_FILE as scope anchor | Review stays aligned with original plan | #### Active Tasks -| Task | Target AC | Status | Notes | -|------|-----------|--------|-------| -| [mainline] Preserve original plan alignment while resolving blocking review findings | Plan ACs in scope | pending | Review-only mode with explicit plan anchor | +| Task | Target AC | Status | Tag | Owner | Capability | Notes | +|------|-----------|--------|-----|-------|------------|-------| +| [mainline] Preserve original plan alignment while resolving blocking review findings | Plan ACs in scope | pending | coding | claude | plan-anchor | Review-only mode with explicit plan anchor | ### Blocking Side Issues | Issue | Discovered Round | Blocking AC | Resolution Path | @@ -1033,9 +1033,9 @@ Pass code review for the current branch without regressing existing behavior. | 0 | Skip implementation mode initialized | Loop started with `--skip-impl` | Focus on review-only objective | #### Active Tasks -| Task | Target AC | Status | Notes | -|------|-----------|--------|-------| -| [mainline] Pass code review for current branch | AC-1 | pending | Review-only mode | +| Task | Target AC | Status | Tag | Owner | Capability | Notes | +|------|-----------|--------|-----|-------|------------|-------| +| [mainline] Pass code review for current branch | AC-1 | pending | coding | claude | review-only | Review-only mode | ### Blocking Side Issues | Issue | Discovered Round | Blocking AC | Resolution Path | @@ -1126,10 +1126,10 @@ cat >> "$GOAL_TRACKER_FILE" << 'GOAL_TRACKER_EOF' | 0 | Initial plan | - | - | #### Active Tasks - -| Task | Target AC | Status | Tag | Owner | Notes | -|------|-----------|--------|-----|-------|-------| -| [To be populated by Claude based on plan] | - | pending | coding or analyze | claude or codex | mainline task only | + +| Task | Target AC | Status | Tag | Owner | Capability | Notes | +|------|-----------|--------|-----|-------|------------|-------| +| [To be populated by Claude based on plan] | - | pending | coding or analyze | claude or codex | cap ID or map section | mainline task only | ### Blocking Side Issues @@ -1206,6 +1206,7 @@ if [[ "$SKIP_IMPL" == "true" ]]; then - Mainline Objective: Keep the current branch aligned with @$PLAN_FILE while resolving only review findings that block clean acceptance. - Target ACs: The original plan acceptance criteria affected by the current branch changes. +- Capability Anchor: Original plan capability map nodes affected by the current branch, or plan-anchor if the plan has no capability map. - Blocking Side Issues In Scope: Any \`[P0-9]\` findings or regressions that block review acceptance or violate the original plan scope. - Queued Side Issues Out of Scope: Non-blocking cleanup, follow-up refactors, or future improvements that do not block review acceptance or plan alignment. - Success Criteria: Code review passes and the current branch still matches the original plan's intended scope. @@ -1216,6 +1217,7 @@ EOF - Mainline Objective: Run code review for the current branch and resolve only findings that block clean acceptance. - Target ACs: AC-1, AC-2 +- Capability Anchor: review-only - Blocking Side Issues In Scope: Any `[P0-9]` findings from the active review cycle. - Queued Side Issues Out of Scope: Non-blocking cleanup, follow-up refactors, or future improvements that do not block review acceptance. - Success Criteria: Code review passes with no blocking findings, and any remaining non-blocking follow-up is explicitly queued. @@ -1297,7 +1299,7 @@ Before starting implementation, you MUST initialize the Goal Tracker: 1. Read @$GOAL_TRACKER_FILE 2. If the "Ultimate Goal" section says "[To be extracted...]", extract a clear goal statement from the plan 3. If the "Acceptance Criteria" section says "[To be defined...]", define 3-7 specific, testable criteria -4. Populate the "Active Tasks" table with MAINLINE tasks from the plan, mapping each to an AC and filling Tag/Owner +4. Populate the "Active Tasks" table with MAINLINE tasks from the plan, mapping each to an AC and filling Tag/Owner/Capability 5. Record any already-known side issues in either "Blocking Side Issues" or "Queued Side Issues" 6. Write the updated goal-tracker.md @@ -1307,9 +1309,10 @@ Before starting implementation, create @$ROUND_CONTRACT_PATH with: 1. **One mainline objective** for this round 2. **Target ACs** (1-2 ACs only) -3. **Blocking side issues in scope** for this round -4. **Queued side issues out of scope** for this round -5. **Round success criteria** +3. **Capability Anchor**: the `Feature Map / Capability Map` node(s) or map section this round advances +4. **Blocking side issues in scope** for this round +5. **Queued side issues out of scope** for this round +6. **Round success criteria** Use this contract to keep the round focused. Do NOT let non-blocking bugs or cleanup work replace the mainline objective. @@ -1341,6 +1344,14 @@ Each task must have one routing tag from the plan: \`coding\` or \`analyze\`. - Keep Goal Tracker "Active Tasks" columns **Tag** and **Owner** aligned with execution (\`coding -> claude\`, \`analyze -> codex\`). - If a task has no explicit tag, default to \`coding\` (Claude executes directly). +## Capability Anchor (MUST FOLLOW) + +If the plan contains \`## Feature Map / Capability Map\`, every mainline task and round contract MUST stay anchored to it: +- Add the relevant Capability ID(s) or capability/feature name(s) to the round contract's **Capability Anchor** field. +- Fill the Goal Tracker Active Tasks \`Capability\` column for each mainline task. +- Before coding or analysis, restate how the task fits the selected capability's business, design, and implementation context. +- Do not let a task drift into another capability or future-scope node unless you record a Plan Evolution entry. + EOF # Append plan content directly (avoids command substitution size limits for large files) @@ -1402,6 +1413,7 @@ Throughout your work, you MUST maintain the Goal Tracker: 1. **Before starting a round**: Re-anchor on the original plan and current round contract 2. **Before starting a task**: Mark the relevant mainline task as "in_progress" in Active Tasks - Confirm Tag/Owner routing is correct before execution + - Confirm the task's Capability matches the round contract's Capability Anchor 3. **Active Tasks** are MAINLINE tasks only - side issues do not belong there 4. **Blocking Side Issues** are reserved for issues that truly stop mainline progress 5. **Queued Side Issues** are non-blocking and must not take over the round diff --git a/skills/humanize-gen-plan/SKILL.md b/skills/humanize-gen-plan/SKILL.md index 1fd58d25..597ecc9a 100644 --- a/skills/humanize-gen-plan/SKILL.md +++ b/skills/humanize-gen-plan/SKILL.md @@ -33,7 +33,7 @@ flowchart TD HAS_ISSUES -->|No| CHECK_METRICS{Has quantitative
metrics?} CHECK_METRICS -->|Yes| CONFIRM_METRICS[Confirm metrics with user:
Hard requirement or trend?] CONFIRM_METRICS --> GEN_PLAN - CHECK_METRICS -->|No| GEN_PLAN[Generate structured plan:
- Goal Description
- Acceptance Criteria with TDD tests
- Path Boundaries
- Feasibility Hints
- Dependencies & Milestones] + CHECK_METRICS -->|No| GEN_PLAN[Generate structured plan:
- Goal Description
- Acceptance Criteria with TDD tests
- Path Boundaries
- Feasibility Hints
- Dependencies & Milestones
- Feature/Capability Map] GEN_PLAN --> WRITE[Write plan to output file
using Edit tool to preserve draft] WRITE --> REVIEW[Review complete plan
Check for inconsistencies] REVIEW --> INCONSISTENT{Inconsistencies?} @@ -89,6 +89,9 @@ Minimum viable implementation - Phase A: ... - Phase B: ... +## Feature Map / Capability Map +Capability-level dependency and context map that supplements the executable task list. + ## Implementation Notes - Code should NOT contain plan terminology ``` diff --git a/skills/humanize-refine-plan/SKILL.md b/skills/humanize-refine-plan/SKILL.md index b74dae57..b57bd873 100644 --- a/skills/humanize-refine-plan/SKILL.md +++ b/skills/humanize-refine-plan/SKILL.md @@ -80,7 +80,7 @@ The refinement flow must: - `## Claude-Codex Deliberation` - `## Pending User Decisions` - `## Implementation Notes` -- Preserve optional sections when present, including the original design draft appendix +- Preserve optional sections when present, including `## Feature Map / Capability Map` and the original design draft appendix - Keep task routing tags restricted to `coding` or `analyze` - Generate a QA ledger from the shipped QA template - Write the refined plan, QA file, and any language variants atomically diff --git a/skills/humanize-rlcr/SKILL.md b/skills/humanize-rlcr/SKILL.md index 6166e1b7..9a45303d 100644 --- a/skills/humanize-rlcr/SKILL.md +++ b/skills/humanize-rlcr/SKILL.md @@ -55,6 +55,7 @@ The native Stop-hook path enforces: - branch consistency checks - plan-file integrity checks (when applicable) - incomplete Task/Todo blocking +- capability anchor reminders when the plan contains `Feature Map / Capability Map` - git-clean requirement before exit - `--push-every-round` unpushed-commit blocking - summary presence checks diff --git a/skills/humanize/SKILL.md b/skills/humanize/SKILL.md index 558e7e1d..47a0aa62 100644 --- a/skills/humanize/SKILL.md +++ b/skills/humanize/SKILL.md @@ -145,6 +145,9 @@ Minimum viable implementation - Phase A: ... - Phase B: ... +## Feature Map / Capability Map +Capability-level dependency and context map that supplements the executable task list. + ## Implementation Notes - Code should NOT contain plan terminology like "AC-", "Milestone", "Step" ``` @@ -154,14 +157,15 @@ Minimum viable implementation The RLCR loop uses a Goal Tracker to prevent goal drift: - **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 Principles 1. **Acceptance Criteria**: Each task maps to a specific AC -2. **Plan Evolution Log**: Document any plan changes with justification -3. **Explicit Deferrals**: Deferred tasks require strong justification -4. **Full Alignment Checks**: Every N rounds (default: 5), comprehensive goal alignment audit +2. **Capability Anchors**: Each round and mainline task stays mapped to the relevant capability node when the plan includes `Feature Map / Capability Map` +3. **Plan Evolution Log**: Document any plan changes with justification +4. **Explicit Deferrals**: Deferred tasks require strong justification +5. **Full Alignment Checks**: Every N rounds (default: 5), comprehensive goal alignment audit ## Important Rules diff --git a/tests/test-gen-plan.sh b/tests/test-gen-plan.sh index b5bcab07..588e2547 100755 --- a/tests/test-gen-plan.sh +++ b/tests/test-gen-plan.sh @@ -216,6 +216,24 @@ else fail "plan template includes convergence status subsection" "Convergence Status subsection" "missing" fi +if [[ -f "$PLAN_TEMPLATE" ]] && grep -q "## Feature Map / Capability Map" "$PLAN_TEMPLATE"; then + pass "plan template includes feature map / capability map section" +else + fail "plan template includes feature map / capability map section" "Feature Map / Capability Map section" "missing" +fi + +if [[ -f "$PLAN_TEMPLATE" ]] && grep -q "Capability ID" "$PLAN_TEMPLATE" && grep -q "Context Summary" "$PLAN_TEMPLATE"; then + pass "plan template includes capability map context columns" +else + fail "plan template includes capability map context columns" "Capability ID and Context Summary columns" "missing one or both" +fi + +if [[ -f "$GEN_PLAN_CMD" ]] && grep -q "Feature Map Requirement" "$GEN_PLAN_CMD"; then + pass "gen-plan command defines mandatory feature map requirement" +else + fail "gen-plan command defines mandatory feature map requirement" "Feature Map Requirement rule" "missing" +fi + if [[ -f "$GEN_PLAN_CMD" ]] && grep -q "## Task Breakdown" "$GEN_PLAN_CMD"; then pass "gen-plan command requires task breakdown section" else diff --git a/tests/test-refine-plan.sh b/tests/test-refine-plan.sh index c43ba60f..521746e3 100755 --- a/tests/test-refine-plan.sh +++ b/tests/test-refine-plan.sh @@ -762,6 +762,7 @@ assert_file_contains "$REFINE_PLAN_CMD" "- `## Task Breakdown`" "refine-plan.md assert_file_contains "$REFINE_PLAN_CMD" "- `## Claude-Codex Deliberation`" "refine-plan.md preserves Claude-Codex Deliberation section" assert_file_contains "$REFINE_PLAN_CMD" "- `## Pending User Decisions`" "refine-plan.md preserves Pending User Decisions section" assert_file_contains "$REFINE_PLAN_CMD" "- `## Implementation Notes`" "refine-plan.md preserves Implementation Notes section" +assert_file_contains "$REFINE_PLAN_CMD" '- `## Feature Map / Capability Map`' "refine-plan.md preserves Feature Map / Capability Map when present" echo "" echo "PT-8: Alternative language and filename rules" diff --git a/tests/test-task-tag-routing.sh b/tests/test-task-tag-routing.sh index f5a8c0e9..5b6f5af2 100755 --- a/tests/test-task-tag-routing.sh +++ b/tests/test-task-tag-routing.sh @@ -4,8 +4,9 @@ # # Validates: # - round-0 prompt includes coding/analyze routing instructions -# - goal-tracker Active Tasks table includes Tag/Owner columns -# - stop hook keeps task-tag routing reminder in follow-up prompts +# - round-0 prompt includes capability anchor instructions +# - goal-tracker Active Tasks table includes Tag/Owner/Capability columns +# - stop hook keeps task-tag routing and capability anchor reminders in follow-up prompts # set -euo pipefail @@ -82,6 +83,12 @@ Implement and validate feature behavior. - AC-1: Endpoint works - AC-2: Analysis notes captured +## Feature Map / Capability Map +| Capability ID | Capability / Feature | Target ACs | Depends On | Context Summary | Implementation Surface | +|---------------|----------------------|------------|------------|-----------------|------------------------| +| cap1 | Endpoint capability | AC-1 | - | Business: expose feature behavior; Design: endpoint returns expected output; Implementation: route and handler stay aligned | app routes | +| cap2 | Rollout analysis capability | AC-2 | cap1 | Business: understand rollout risk; Design: risk notes reference implemented endpoint; Implementation: analysis depends on cap1 behavior | planning notes | + ## Task Breakdown | Task ID | Description | Target AC | Tag (`coding`/`analyze`) | Depends On | |---------|-------------|-----------|----------------------------|------------| @@ -108,10 +115,16 @@ else fail "round-0 prompt includes ask-codex routing for analyze tasks" "ask-codex instruction" "missing" fi -if [[ -n "$GOAL_TRACKER_FILE" ]] && grep -q "^| Task | Target AC | Status | Tag | Owner | Notes |" "$GOAL_TRACKER_FILE"; then - pass "goal tracker Active Tasks table includes Tag/Owner columns" +if [[ -n "$PROMPT_FILE" ]] && grep -q "## Capability Anchor (MUST FOLLOW)" "$PROMPT_FILE"; then + pass "round-0 prompt includes capability anchor section" +else + fail "round-0 prompt includes capability anchor section" "capability anchor section" "missing" +fi + +if [[ -n "$GOAL_TRACKER_FILE" ]] && grep -q "^| Task | Target AC | Status | Tag | Owner | Capability | Notes |" "$GOAL_TRACKER_FILE"; then + pass "goal tracker Active Tasks table includes Tag/Owner/Capability columns" else - fail "goal tracker Active Tasks table includes Tag/Owner columns" "table header with Tag/Owner" "missing" + fail "goal tracker Active Tasks table includes Tag/Owner/Capability columns" "table header with Tag/Owner/Capability" "missing" fi # ======================================== @@ -132,6 +145,11 @@ Ensure task routing remains consistent. ## Acceptance Criteria - AC-1: Routing reminder is present +## Feature Map / Capability Map +| Capability ID | Capability / Feature | Target ACs | Depends On | Context Summary | Implementation Surface | +|---------------|----------------------|------------|------------|-----------------|------------------------| +| cap1 | Routing capability | AC-1 | - | Business: keep routing stable; Design: prompts preserve route ownership; Implementation: task metadata is carried forward | RLCR prompts | + ## Task Breakdown | Task ID | Description | Target AC | Tag (`coding`/`analyze`) | Depends On | |---------|-------------|-----------|----------------------------|------------| @@ -184,9 +202,9 @@ Keep routing behavior stable. --- ## MUTABLE SECTION #### Active Tasks -| Task | Target AC | Status | Tag | Owner | Notes | -|------|-----------|--------|-----|-------|-------| -| Keep routing note | AC-1 | in_progress | analyze | codex | - +| Task | Target AC | Status | Tag | Owner | Capability | Notes | +|------|-----------|--------|-----|-------|------------|-------| +| Keep routing note | AC-1 | in_progress | analyze | codex | cap1 | - EOF cat > "$loop_dir/round-0-contract.md" << 'EOF' # Round 0 Contract @@ -236,4 +254,17 @@ else fail "stop hook follow-up prompt includes ask-codex instruction for analyze tasks" "ask-codex instruction in round-1 prompt" "missing" fi +if [[ -f "$NEXT_PROMPT" ]] && grep -q "## Capability Anchor Reminder" "$NEXT_PROMPT"; then + pass "stop hook follow-up prompt includes capability anchor reminder" +else + fail "stop hook follow-up prompt includes capability anchor reminder" "capability anchor reminder section" "missing" +fi + +if grep -q "Capability Map Alignment Check" "$PROJECT_ROOT/prompt-template/codex/regular-review.md" && \ + grep -q "Capability Map Alignment Check" "$PROJECT_ROOT/prompt-template/codex/full-alignment-review.md"; then + pass "codex review templates include capability map alignment check" +else + fail "codex review templates include capability map alignment check" "Capability Map Alignment Check in regular and full reviews" "missing" +fi + print_test_summary "Task Tag Routing Tests"