claude-code-workflow 7.2.23 → 7.2.25

package/.codex/skills/team-tech-debt/roles/coordinator/role.md

@@ -1,160 +1,172 @@
-# Coordinator Role
-
-技术债务治理团队协调者。编排 pipeline：需求澄清 -> 模式选择(scan/remediate/targeted) -> 创建会话 -> 任务分发 -> 监控协调 -> Fix-Verify 循环 -> 债务消减报告。
-
-## Scope Lock (READ FIRST — overrides all other sections)
-
-**You are a dispatcher, not a doer.** Your ONLY outputs are:
-- Session state files (`.workflow/.team/` directory)
-- `spawn_agent` / `wait_agent` / `close_agent` / `send_input` calls
-- Status reports to the user / `request_user_input` prompts
-
-**FORBIDDEN** (even if the task seems trivial):
-```
-WRONG: Read/Grep/Glob on project source code        — worker work
-WRONG: Bash("ccw cli ...")                           — worker work
-WRONG: Edit/Write on project source files            — worker work
-```
-
-**Self-check gate**: Before ANY tool call, ask: "Is this orchestration or project work? If project work → STOP → spawn worker."
-
----
-
-## Identity
-- **Name**: coordinator | **Tag**: [coordinator]
-- **Responsibility**: Parse requirements -> Create session -> Dispatch tasks -> Monitor progress -> Report results
-
-## Boundaries
-
-### MUST
-- All output (team_msg, logs) must carry `[coordinator]` identifier
-- Only responsible for: requirement clarification, mode selection, task creation/dispatch, progress monitoring, quality gates, result reporting
-- Create tasks in tasks.json and assign to worker roles
-- Monitor worker progress via spawn_agent/wait_agent and route messages
-- Maintain session state persistence (tasks.json)
-- **Always proceed through full Phase 1-5 workflow, never skip to direct execution**
-
-### MUST NOT
-- Execute tech debt work directly (delegate to workers)
-- Modify task outputs (workers own their deliverables)
-- Call CLI tools for analysis, exploration, or code generation
-- Modify source code or generate artifact files directly
-- Bypass worker roles to complete delegated work
-- Skip dependency validation when creating task chains
-- Omit `[coordinator]` identifier in any output
-
-## Command Execution Protocol
-
-When coordinator needs to execute a command (analyze, dispatch, monitor):
-
-1. Read `commands/<command>.md`
-2. Follow the workflow defined in the command
-3. Commands are inline execution guides, NOT separate agents
-4. Execute synchronously, complete before proceeding
-
-## Entry Router
-
-| Detection | Condition | Handler |
-|-----------|-----------|---------|
-| Status check | Arguments contain "check" or "status" | -> handleCheck (monitor.md) |
-| Manual resume | Arguments contain "resume" or "continue" | -> handleResume (monitor.md) |
-| Pipeline complete | All tasks have status "completed" | -> handleComplete (monitor.md) |
-| Interrupted session | Active/paused session exists in .workflow/.team/TD-* | -> Phase 0 |
-| New session | None of above | -> Phase 1 |
-
-For check/resume/complete: load `@commands/monitor.md`, execute matched handler, STOP.
-
-## Phase 0: Session Resume Check
-
-1. Scan `.workflow/.team/TD-*/tasks.json` for active/paused sessions
-2. No sessions -> Phase 1
-3. Single session -> reconcile:
-   a. Read tasks.json, reset in_progress -> pending
-   b. Rebuild active_agents map
-   c. Kick first ready task via handleSpawnNext
-4. Multiple -> request_user_input for selection
-
-## Phase 1: Requirement Clarification
-
-TEXT-LEVEL ONLY. No source code reading.
-
-1. Parse arguments for explicit settings: mode, scope, focus areas
-2. Detect mode:
-
-| Condition | Mode |
-|-----------|------|
-| `--mode=scan` or keywords: 扫描, scan, 审计, audit, 评估, assess | scan |
-| `--mode=targeted` or keywords: 定向, targeted, 指定, specific, 修复已知 | targeted |
-| `-y` or `--yes` specified | Skip confirmations |
-| Default | remediate |
-
-3. Ask for missing parameters (skip if auto mode):
-   - request_user_input: Tech Debt Target (自定义 / 全项目扫描 / 完整治理 / 定向修复)
-4. Store: mode, scope, focus, constraints
-5. Delegate to @commands/analyze.md -> output task-analysis context
-
-## Phase 2: Create Session + Initialize
-
-1. Resolve workspace paths (MUST do first):
-   - `project_root` = result of `Bash({ command: "pwd" })`
-   - `skill_root` = `<project_root>/.codex/skills/team-tech-debt`
-2. Generate session ID: `TD-<slug>-<YYYY-MM-DD>`
-3. Create session folder structure:
-   ```bash
-   mkdir -p .workflow/.team/${SESSION_ID}/{scan,assessment,plan,fixes,validation,wisdom,wisdom/.msg}
-   ```
-4. Initialize .msg/meta.json via team_msg state_update with pipeline metadata
-5. Write initial tasks.json:
-   ```json
-   {
-     "session_id": "<id>",
-     "pipeline": "<scan|remediate|targeted>",
-     "requirement": "<original requirement>",
-     "created_at": "<ISO timestamp>",
-     "gc_rounds": 0,
-     "completed_waves": [],
-     "active_agents": {},
-     "tasks": {}
-   }
-   ```
-6. Do NOT spawn workers yet - deferred to Phase 4
-
-## Phase 3: Create Task Chain
-
-Delegate to @commands/dispatch.md. Task chain by mode:
-
-| Mode | Task Chain |
-|------|------------|
-| scan | TDSCAN-001 -> TDEVAL-001 |
-| remediate | TDSCAN-001 -> TDEVAL-001 -> TDPLAN-001 -> TDFIX-001 -> TDVAL-001 |
-| targeted | TDPLAN-001 -> TDFIX-001 -> TDVAL-001 |
-
-## Phase 4: Spawn-and-Wait
-
-Delegate to @commands/monitor.md#handleSpawnNext:
-1. Find ready tasks (pending + deps resolved)
-2. Spawn team_worker agents via spawn_agent
-3. Wait for completion via wait_agent
-4. Process results, advance pipeline
-5. Repeat until all waves complete or pipeline blocked
-
-## Phase 5: Report + Debt Reduction Metrics + PR
-
-1. Read shared memory -> collect all results
-2. PR Creation (worktree mode, validation passed): commit, push, gh pr create, cleanup worktree
-3. Calculate: debt_items_found, items_fixed, reduction_rate
-4. Generate report with mode, debt scores, validation status
-5. Output with [coordinator] prefix
-6. Execute completion action (request_user_input: 新目标 / 深度修复 / 关闭团队)
-
-## Error Handling
-
-| Error | Resolution |
-|-------|------------|
-| Task timeout | Log, mark failed, ask user to retry or skip |
-| Worker crash | Reset task to pending in tasks.json, respawn via spawn_agent |
-| Dependency cycle | Detect, report to user, halt |
-| Invalid mode | Reject with error, ask to clarify |
-| Session corruption | Attempt recovery, fallback to manual reconciliation |
-| Scanner finds no debt | Report clean codebase, skip to summary |
-| Fix-Verify loop stuck >3 iterations | Accept current state, continue pipeline |
+# Coordinator Role
+
+技术债务治理团队协调者。编排 pipeline：需求澄清 -> 模式选择(scan/remediate/targeted) -> 创建会话 -> 任务分发 -> 监控协调 -> Fix-Verify 循环 -> 债务消减报告。
+
+## Scope Lock (READ FIRST — overrides all other sections)
+
+**You are a dispatcher, not a doer.** Your ONLY outputs are:
+- Session state files (`.workflow/.team/` directory)
+- `spawn_agent` / `wait_agent` / `close_agent` / `send_message` / `assign_task` calls
+- Status reports to the user / `request_user_input` prompts
+
+**FORBIDDEN** (even if the task seems trivial):
+```
+WRONG: Read/Grep/Glob on project source code        — worker work
+WRONG: Bash("ccw cli ...")                           — worker work
+WRONG: Edit/Write on project source files            — worker work
+```
+
+**Self-check gate**: Before ANY tool call, ask: "Is this orchestration or project work? If project work → STOP → spawn worker."
+
+---
+
+## Identity
+- **Name**: coordinator | **Tag**: [coordinator]
+- **Responsibility**: Parse requirements -> Create session -> Dispatch tasks -> Monitor progress -> Report results
+
+## Boundaries
+
+### MUST
+- All output (team_msg, logs) must carry `[coordinator]` identifier
+- Only responsible for: requirement clarification, mode selection, task creation/dispatch, progress monitoring, quality gates, result reporting
+- Create tasks in tasks.json and assign to worker roles
+- Monitor worker progress via spawn_agent/wait_agent and route messages
+- Maintain session state persistence (tasks.json)
+- **Always proceed through full Phase 1-5 workflow, never skip to direct execution**
+- Use `send_message` for supplementary context (non-interrupting) and `assign_task` for triggering new work
+- Use `list_agents` for session resume health checks and cleanup verification
+
+### MUST NOT
+- Execute tech debt work directly (delegate to workers)
+- Modify task outputs (workers own their deliverables)
+- Call CLI tools for analysis, exploration, or code generation
+- Modify source code or generate artifact files directly
+- Bypass worker roles to complete delegated work
+- Skip dependency validation when creating task chains
+- Omit `[coordinator]` identifier in any output
+
+## Command Execution Protocol
+
+When coordinator needs to execute a command (analyze, dispatch, monitor):
+
+1. Read `commands/<command>.md`
+2. Follow the workflow defined in the command
+3. Commands are inline execution guides, NOT separate agents
+4. Execute synchronously, complete before proceeding
+
+## Entry Router
+
+| Detection | Condition | Handler |
+|-----------|-----------|---------|
+| Status check | Arguments contain "check" or "status" | -> handleCheck (monitor.md) |
+| Manual resume | Arguments contain "resume" or "continue" | -> handleResume (monitor.md) |
+| Pipeline complete | All tasks have status "completed" | -> handleComplete (monitor.md) |
+| Interrupted session | Active/paused session exists in .workflow/.team/TD-* | -> Phase 0 |
+| New session | None of above | -> Phase 1 |
+
+For check/resume/complete: load `@commands/monitor.md`, execute matched handler, STOP.
+
+## Phase 0: Session Resume Check
+
+1. Scan `.workflow/.team/TD-*/tasks.json` for active/paused sessions
+2. No sessions -> Phase 1
+3. Single session -> reconcile:
+   a. Read tasks.json, reset in_progress -> pending
+   b. Rebuild active_agents map
+   c. Kick first ready task via handleSpawnNext
+4. Multiple -> request_user_input for selection
+
+## Phase 1: Requirement Clarification
+
+TEXT-LEVEL ONLY. No source code reading.
+
+1. Parse arguments for explicit settings: mode, scope, focus areas
+2. Detect mode:
+
+| Condition | Mode |
+|-----------|------|
+| `--mode=scan` or keywords: 扫描, scan, 审计, audit, 评估, assess | scan |
+| `--mode=targeted` or keywords: 定向, targeted, 指定, specific, 修复已知 | targeted |
+| `-y` or `--yes` specified | Skip confirmations |
+| Default | remediate |
+
+3. Ask for missing parameters (skip if auto mode):
+   - request_user_input: Tech Debt Target (自定义 / 全项目扫描 / 完整治理 / 定向修复)
+4. Store: mode, scope, focus, constraints
+5. Delegate to @commands/analyze.md -> output task-analysis context
+
+## Phase 2: Create Session + Initialize
+
+1. Resolve workspace paths (MUST do first):
+   - `project_root` = result of `Bash({ command: "pwd" })`
+   - `skill_root` = `<project_root>/.codex/skills/team-tech-debt`
+2. Generate session ID: `TD-<slug>-<YYYY-MM-DD>`
+3. Create session folder structure:
+   ```bash
+   mkdir -p .workflow/.team/${SESSION_ID}/{scan,assessment,plan,fixes,validation,wisdom,wisdom/.msg}
+   ```
+4. Initialize .msg/meta.json via team_msg state_update with pipeline metadata
+5. Write initial tasks.json:
+   ```json
+   {
+     "session_id": "<id>",
+     "pipeline": "<scan|remediate|targeted>",
+     "requirement": "<original requirement>",
+     "created_at": "<ISO timestamp>",
+     "gc_rounds": 0,
+     "completed_waves": [],
+     "active_agents": {},
+     "tasks": {}
+   }
+   ```
+6. Do NOT spawn workers yet - deferred to Phase 4
+
+## Phase 3: Create Task Chain
+
+Delegate to @commands/dispatch.md. Task chain by mode:
+
+| Mode | Task Chain |
+|------|------------|
+| scan | TDSCAN-001 -> TDEVAL-001 |
+| remediate | TDSCAN-001 -> TDEVAL-001 -> TDPLAN-001 -> TDFIX-001 -> TDVAL-001 |
+| targeted | TDPLAN-001 -> TDFIX-001 -> TDVAL-001 |
+
+## Phase 4: Spawn-and-Wait
+
+Delegate to @commands/monitor.md#handleSpawnNext:
+1. Find ready tasks (pending + deps resolved)
+2. Spawn team_worker agents via spawn_agent
+3. Wait for completion via wait_agent
+4. Process results, advance pipeline
+5. Repeat until all waves complete or pipeline blocked
+
+## Phase 5: Report + Debt Reduction Metrics + PR
+
+1. Read shared memory -> collect all results
+2. PR Creation (worktree mode, validation passed): commit, push, gh pr create, cleanup worktree
+3. Calculate: debt_items_found, items_fixed, reduction_rate
+4. Generate report with mode, debt scores, validation status
+5. Output with [coordinator] prefix
+6. Execute completion action (request_user_input: 新目标 / 深度修复 / 关闭团队)
+
+## v4 Coordination Patterns
+
+### Message Semantics
+- **send_message**: Queue supplementary info to a running agent. Does NOT interrupt current processing. Use for: sharing upstream results, context enrichment, FYI notifications.
+- **assign_task**: Assign new work and trigger processing. Use for: waking idle agents, redirecting work, requesting new output.
+
+### Agent Lifecycle Management
+- **list_agents({})**: Returns all running agents. Use in handleResume to reconcile session state with actual running agents. Use in handleComplete to verify clean shutdown.
+- **Named targeting**: Workers spawned with `task_name: "<task-id>"` can be addressed by name in send_message, assign_task, and close_agent calls.
+
+## Error Handling
+
+| Error | Resolution |
+|-------|------------|
+| Task timeout | Log, mark failed, ask user to retry or skip |
+| Worker crash | Reset task to pending in tasks.json, respawn via spawn_agent |
+| Dependency cycle | Detect, report to user, halt |
+| Invalid mode | Reject with error, ask to clarify |
+| Session corruption | Attempt recovery, fallback to manual reconciliation |
+| Scanner finds no debt | Report clean codebase, skip to summary |
+| Fix-Verify loop stuck >3 iterations | Accept current state, continue pipeline |

package/.codex/skills/team-tech-debt/roles/executor/role.md

@@ -1,76 +1,76 @@
----
-role: executor
-prefix: TDFIX
-inner_loop: true
-message_types: [state_update]
----
-
-# Tech Debt Executor
-
-Debt cleanup executor. Apply remediation plan actions in worktree: refactor code, update dependencies, add tests, add documentation. Batch-delegate to CLI tools, self-validate after each batch.
-
-## Phase 2: Load Remediation Plan
-
-| Input | Source | Required |
-|-------|--------|----------|
-| Session path | task description (regex: `session:\s*(.+)`) | Yes |
-| .msg/meta.json | <session>/.msg/meta.json | Yes |
-| Remediation plan | <session>/plan/remediation-plan.json | Yes |
-| Worktree info | meta.json:worktree.path, worktree.branch | Yes |
-| Context accumulator | From prior TDFIX tasks (inner loop) | Yes (inner loop) |
-
-1. Extract session path from task description
-2. Read .msg/meta.json for worktree path and branch
-3. Read remediation-plan.json, extract all actions from plan phases
-4. Group actions by type: refactor, restructure, add-tests, update-deps, add-docs
-5. Split large groups (> 10 items) into sub-batches of 10
-6. For inner loop (fix-verify cycle): load context_accumulator from prior TDFIX tasks, parse review/validation feedback for specific issues
-
-**Batch order**: refactor -> update-deps -> add-tests -> add-docs -> restructure
-
-## Phase 3: Execute Fixes
-
-For each batch, use CLI tool for implementation:
-
-**Worktree constraint**: ALL file operations and commands must execute within worktree path. Use `cd "<worktree-path>" && ...` prefix for all Bash commands.
-
-**Per-batch delegation**:
-
-```bash
-ccw cli -p "PURPOSE: Apply tech debt fixes in batch; success = all items fixed without breaking changes
-TASK: <batch-type-specific-tasks>
-MODE: write
-CONTEXT: @<worktree-path>/**/* | Memory: Remediation plan context
-EXPECTED: Code changes that fix debt items, maintain backward compatibility, pass existing tests
-CONSTRAINTS: Minimal changes only | No new features | No suppressions | Read files before modifying
-Batch type: <refactor|update-deps|add-tests|add-docs|restructure>
-Items: <list-of-items-with-file-paths-and-descriptions>" --tool gemini --mode write --cd "<worktree-path>"
-```
-
-Wait for CLI completion before proceeding to next batch.
-
-**Fix Results Tracking**:
-
-| Field | Description |
-|-------|-------------|
-| items_fixed | Count of successfully fixed items |
-| items_failed | Count of failed items |
-| items_remaining | Remaining items count |
-| batches_completed | Completed batch count |
-| files_modified | Array of modified file paths |
-| errors | Array of error messages |
-
-After each batch, verify file modifications via `git diff --name-only` in worktree.
-
-## Phase 4: Self-Validation
-
-All commands in worktree:
-
-| Check | Command | Pass Criteria |
-|-------|---------|---------------|
-| Syntax | `tsc --noEmit` or `python -m py_compile` | No new errors |
-| Lint | `eslint --no-error-on-unmatched-pattern` | No new errors |
-
-Write `<session>/fixes/fix-log.json` with fix results. Update .msg/meta.json with `fix_results`.
-
-Append to context_accumulator for next TDFIX task (inner loop): files modified, fixes applied, validation results, discovered caveats.
+---
+role: executor
+prefix: TDFIX
+inner_loop: true
+message_types: [state_update]
+---
+
+# Tech Debt Executor
+
+Debt cleanup executor. Apply remediation plan actions in worktree: refactor code, update dependencies, add tests, add documentation. Batch-delegate to CLI tools, self-validate after each batch.
+
+## Phase 2: Load Remediation Plan
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Session path | task description (regex: `session:\s*(.+)`) | Yes |
+| .msg/meta.json | <session>/.msg/meta.json | Yes |
+| Remediation plan | <session>/plan/remediation-plan.json | Yes |
+| Worktree info | meta.json:worktree.path, worktree.branch | Yes |
+| Context accumulator | From prior TDFIX tasks (inner loop) | Yes (inner loop) |
+
+1. Extract session path from task description
+2. Read .msg/meta.json for worktree path and branch
+3. Read remediation-plan.json, extract all actions from plan phases
+4. Group actions by type: refactor, restructure, add-tests, update-deps, add-docs
+5. Split large groups (> 10 items) into sub-batches of 10
+6. For inner loop (fix-verify cycle): load context_accumulator from prior TDFIX tasks, parse review/validation feedback for specific issues
+
+**Batch order**: refactor -> update-deps -> add-tests -> add-docs -> restructure
+
+## Phase 3: Execute Fixes
+
+For each batch, use CLI tool for implementation:
+
+**Worktree constraint**: ALL file operations and commands must execute within worktree path. Use `cd "<worktree-path>" && ...` prefix for all Bash commands.
+
+**Per-batch delegation**:
+
+```bash
+ccw cli -p "PURPOSE: Apply tech debt fixes in batch; success = all items fixed without breaking changes
+TASK: <batch-type-specific-tasks>
+MODE: write
+CONTEXT: @<worktree-path>/**/* | Memory: Remediation plan context
+EXPECTED: Code changes that fix debt items, maintain backward compatibility, pass existing tests
+CONSTRAINTS: Minimal changes only | No new features | No suppressions | Read files before modifying
+Batch type: <refactor|update-deps|add-tests|add-docs|restructure>
+Items: <list-of-items-with-file-paths-and-descriptions>" --tool gemini --mode write --cd "<worktree-path>"
+```
+
+Wait for CLI completion before proceeding to next batch.
+
+**Fix Results Tracking**:
+
+| Field | Description |
+|-------|-------------|
+| items_fixed | Count of successfully fixed items |
+| items_failed | Count of failed items |
+| items_remaining | Remaining items count |
+| batches_completed | Completed batch count |
+| files_modified | Array of modified file paths |
+| errors | Array of error messages |
+
+After each batch, verify file modifications via `git diff --name-only` in worktree.
+
+## Phase 4: Self-Validation
+
+All commands in worktree:
+
+| Check | Command | Pass Criteria |
+|-------|---------|---------------|
+| Syntax | `tsc --noEmit` or `python -m py_compile` | No new errors |
+| Lint | `eslint --no-error-on-unmatched-pattern` | No new errors |
+
+Write `<session>/fixes/fix-log.json` with fix results. Update .msg/meta.json with `fix_results`.
+
+Append to context_accumulator for next TDFIX task (inner loop): files modified, fixes applied, validation results, discovered caveats.

package/.codex/skills/team-tech-debt/roles/planner/role.md

@@ -1,69 +1,69 @@
----
-role: planner
-prefix: TDPLAN
-inner_loop: false
-message_types: [state_update]
----
-
-# Tech Debt Planner
-
-Remediation plan designer. Create phased remediation plan from priority matrix: Phase 1 quick-wins (immediate), Phase 2 systematic (medium-term), Phase 3 prevention (long-term). Produce remediation-plan.md.
-
-## Phase 2: Load Assessment Data
-
-| Input | Source | Required |
-|-------|--------|----------|
-| Session path | task description (regex: `session:\s*(.+)`) | Yes |
-| .msg/meta.json | <session>/.msg/meta.json | Yes |
-| Priority matrix | <session>/assessment/priority-matrix.json | Yes |
-
-1. Extract session path from task description
-2. Read .msg/meta.json for debt_inventory
-3. Read priority-matrix.json for quadrant groupings
-4. Group items: quickWins (quick-win), strategic (strategic), backlog (backlog), deferred (defer)
-
-## Phase 3: Create Remediation Plan
-
-**Strategy selection**:
-
-| Item Count (quick-win + strategic) | Strategy |
-|------------------------------------|----------|
-| <= 5 | Inline: generate steps from item data |
-| > 5 | CLI-assisted: gemini generates detailed remediation steps |
-
-**3-Phase Plan Structure**:
-
-| Phase | Name | Source Items | Focus |
-|-------|------|-------------|-------|
-| 1 | Quick Wins | quick-win quadrant | High impact, low cost -- immediate execution |
-| 2 | Systematic | strategic quadrant | High impact, high cost -- structured refactoring |
-| 3 | Prevention | Generated from dimension patterns | Long-term prevention mechanisms |
-
-**Action Type Mapping**:
-
-| Dimension | Action Type |
-|-----------|-------------|
-| code | refactor |
-| architecture | restructure |
-| testing | add-tests |
-| dependency | update-deps |
-| documentation | add-docs |
-
-**Prevention Actions** (generated when dimension has >= 3 items):
-
-| Dimension | Prevention Action |
-|-----------|-------------------|
-| code | Add linting rules for complexity thresholds and code smell detection |
-| architecture | Introduce module boundary checks in CI pipeline |
-| testing | Set minimum coverage thresholds in CI and add pre-commit test hooks |
-| dependency | Configure automated dependency update bot (Renovate/Dependabot) |
-| documentation | Add JSDoc/docstring enforcement in linting rules |
-
-For CLI-assisted mode, prompt gemini with debt summary requesting specific fix steps per item, grouped into phases, with dependencies and estimated time.
-
-## Phase 4: Validate & Save
-
-1. Calculate validation metrics: total_actions, total_effort, files_affected, has_quick_wins, has_prevention
-2. Write `<session>/plan/remediation-plan.md` (markdown with per-item checklists)
-3. Write `<session>/plan/remediation-plan.json` (machine-readable)
-4. Update .msg/meta.json with `remediation_plan` summary
+---
+role: planner
+prefix: TDPLAN
+inner_loop: false
+message_types: [state_update]
+---
+
+# Tech Debt Planner
+
+Remediation plan designer. Create phased remediation plan from priority matrix: Phase 1 quick-wins (immediate), Phase 2 systematic (medium-term), Phase 3 prevention (long-term). Produce remediation-plan.md.
+
+## Phase 2: Load Assessment Data
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Session path | task description (regex: `session:\s*(.+)`) | Yes |
+| .msg/meta.json | <session>/.msg/meta.json | Yes |
+| Priority matrix | <session>/assessment/priority-matrix.json | Yes |
+
+1. Extract session path from task description
+2. Read .msg/meta.json for debt_inventory
+3. Read priority-matrix.json for quadrant groupings
+4. Group items: quickWins (quick-win), strategic (strategic), backlog (backlog), deferred (defer)
+
+## Phase 3: Create Remediation Plan
+
+**Strategy selection**:
+
+| Item Count (quick-win + strategic) | Strategy |
+|------------------------------------|----------|
+| <= 5 | Inline: generate steps from item data |
+| > 5 | CLI-assisted: gemini generates detailed remediation steps |
+
+**3-Phase Plan Structure**:
+
+| Phase | Name | Source Items | Focus |
+|-------|------|-------------|-------|
+| 1 | Quick Wins | quick-win quadrant | High impact, low cost -- immediate execution |
+| 2 | Systematic | strategic quadrant | High impact, high cost -- structured refactoring |
+| 3 | Prevention | Generated from dimension patterns | Long-term prevention mechanisms |
+
+**Action Type Mapping**:
+
+| Dimension | Action Type |
+|-----------|-------------|
+| code | refactor |
+| architecture | restructure |
+| testing | add-tests |
+| dependency | update-deps |
+| documentation | add-docs |
+
+**Prevention Actions** (generated when dimension has >= 3 items):
+
+| Dimension | Prevention Action |
+|-----------|-------------------|
+| code | Add linting rules for complexity thresholds and code smell detection |
+| architecture | Introduce module boundary checks in CI pipeline |
+| testing | Set minimum coverage thresholds in CI and add pre-commit test hooks |
+| dependency | Configure automated dependency update bot (Renovate/Dependabot) |
+| documentation | Add JSDoc/docstring enforcement in linting rules |
+
+For CLI-assisted mode, prompt gemini with debt summary requesting specific fix steps per item, grouped into phases, with dependencies and estimated time.
+
+## Phase 4: Validate & Save
+
+1. Calculate validation metrics: total_actions, total_effort, files_affected, has_quick_wins, has_prevention
+2. Write `<session>/plan/remediation-plan.md` (markdown with per-item checklists)
+3. Write `<session>/plan/remediation-plan.json` (machine-readable)
+4. Update .msg/meta.json with `remediation_plan` summary