@jamie-tam/forge 6.0.0

package/skills/plan-task-decompose/SKILL.md

@@ -0,0 +1,454 @@
+---
+name: plan-task-decompose
+description: "Use when architecture artifacts exist and the user asks to 'break this down', 'plan the tasks', 'order the work', 'create a task list', 'decompose into slices'. Outputs ordered, testable tasks with file paths. For prototype-driven /feature and /greenfield, harden produces the slice graph — use this skill only when harden doesn't apply (library, internal tool, refactor)."
+---
+
+# Plan Task Decompose
+
+Break architecture artifacts into bite-sized, implementable tasks. Each task takes 2-5 minutes, references exact file paths, includes complete code examples, and maps dependencies so tasks can be executed in the correct order — by humans or subagents.
+
+**When this skill is the wrong fit:** v6 prototype-driven flow produces the production task graph (slice graph) from the `harden` skill at Phase 5 (codify), with dependencies and acceptance criteria derived from the locked prototype. This skill is the non-prototype fallback that decomposes architecture artifacts upfront; use it only when prototype/wireframe phases were skipped.
+
+**Announce at start:** "I'm using the plan-task-decompose skill to create the implementation plan."
+
+<HARD-GATE>
+When this skill is invoked: do NOT begin implementation until the task plan has been reviewed by the spec-reviewer subagent and approved by the user. Once this skill is on the path, the gate applies. In v6 prototype-driven flow, this skill is not on the path — `harden` produces the slice graph and runs adversarial review on each ADR.
+</HARD-GATE>
+
+---
+
+## I/O Contract
+
+| Field | Value |
+|---|---|
+| **Requires** | Architecture artifacts: `api-contract.md`, `db-schema.md`, `system-diagram.md`. Brainstorm: `brainstorm-approved.md`. Codebase analysis: `codebase-analysis.md` (if existing project). |
+| **Produces** | `.forge/work/{type}/{name}/tasks.md` |
+| **Feeds into** | `build-tdd`, `build-pr-workflow`, subagent dispatch |
+| **Updates manifest** | `artifacts.tasks` |
+
+---
+
+## Checklist
+
+Complete these steps in order:
+
+1. **Read all input artifacts** -- architecture, brainstorm, codebase analysis
+2. **Map file structure** -- which files will be created or modified
+3. **Define tasks** -- 2-5 minute units with exact paths and code
+4. **Map dependencies** -- which tasks block others, which can parallelize
+5. **Flag subagent coordination points** -- tasks that share interfaces
+6. **Write plan header** -- goal, architecture summary, tech stack
+7. **Write complete task plan** -- save to `.forge/work/{type}/{name}/tasks.md`
+8. **Plan review loop** -- dispatch spec-reviewer subagent (max 3 iterations)
+9. **User reviews plan** -- present for approval
+10. **Update feature manifest** -- record artifact path
+11. **Execution handoff** -- offer execution options
+
+---
+
+## Scope Check
+
+Before decomposing, verify the scope is appropriate for a single plan:
+
+- If the architecture covers multiple independent subsystems, it should have been broken into sub-projects during brainstorming
+- If it was not, suggest breaking into separate plans: one per subsystem
+- Each plan should produce working, testable software on its own
+
+> "The architecture covers {N} independent subsystems. I recommend separate task plans for each. Which should we start with?"
+
+---
+
+## Process
+
+### Step 1: Read All Input Artifacts
+
+Read and internalize every input:
+
+**Architecture artifacts:**
+- `api-contract.md` -- every endpoint, type, and error code
+- `db-schema.md` -- every table, column, index, and constraint
+- `system-diagram.md` -- component relationships and data flow
+
+**Design context:**
+- `brainstorm-approved.md` -- the approved approach and rationale
+- `codebase-analysis.md` -- existing patterns, conventions, risks
+
+**Decision log:**
+- `aiwiki/decisions/` -- ADRs that affect implementation choices
+
+Cross-reference: verify that task decomposition will implement everything defined in the API contract and DB schema. Nothing should be lost between architecture and tasks.
+
+### Step 1.5: Codex Mode Check
+
+Now that input artifacts are read, run the Codex consent flow from `protocols/codex.md`. The selected mode applies for the rest of this skill's invocation.
+
+- **Takeover:** Dispatch Codex with the artifacts to decompose into tasks, dependencies, and code examples. Claude reviews ordering and parallelization.
+- **Verify** or **Skip / Codex unavailable:** Proceed with the steps below. Step 7.5 will dispatch Codex to review Claude's task plan (Verify only).
+
+### Step 2: Map File Structure
+
+Before defining tasks, map out every file that will be created or modified. This is where decomposition decisions get locked in.
+
+```markdown
+## File Structure
+
+### New Files
+- `src/api/routes/payments.ts` -- Payment API routes
+- `src/services/payment-service.ts` -- Payment business logic
+- `src/models/payment.ts` -- Payment database model
+- `src/validators/payment-validator.ts` -- Request validation schemas
+- `src/types/payment.ts` -- TypeScript type definitions
+- `tests/unit/services/payment-service.test.ts` -- Unit tests
+- `tests/integration/api/payments.test.ts` -- Integration tests
+- `migrations/YYYYMMDD_create_payments.ts` -- Database migration
+
+### Modified Files
+- `src/api/routes/index.ts:15-20` -- Register payment routes
+- `src/types/index.ts:8-12` -- Export payment types
+- `src/config/database.ts:25-30` -- Add payment table config
+```
+
+Rules for file structure:
+
+- **Design units with clear boundaries.** Each file has one clear responsibility.
+- **Prefer smaller, focused files.** You reason better about code you can hold in context. Your edits are more reliable when files are focused.
+- **Files that change together should live together.** Split by responsibility, not by technical layer.
+- **In existing codebases, follow established patterns.** If the codebase uses large files, do not unilaterally restructure. But if a file you are modifying has grown unwieldy, including a split in the plan is reasonable.
+- **Exact paths required.** No "somewhere in the api directory." Exact file path for every file.
+
+### Step 3: Define Tasks
+
+Each task is a small, self-contained unit of work taking 2-5 minutes. Follow strict TDD task structure.
+
+**Frontend tasks MUST include visual specs.** If a `DESIGN.md` exists at the project root (from the `plan-design-system` skill), every task that creates or modifies a frontend component must include:
+- Layout structure (flexbox/grid, spacing, sizing)
+- Colors and typography referencing the design tokens from `DESIGN.md`
+- Interactive states (hover, focus, active, disabled)
+- Responsive behavior at key breakpoints
+
+Also check for feature-scoped overrides in `.forge/work/{type}/{name}/design-overrides.md` — if present, those tokens take precedence over root `DESIGN.md` for this feature's tasks.
+
+Without visual specs, agents will implement behavior-only components and skip styling entirely (TDD tests verify behavior, not appearance). If no `DESIGN.md` exists (e.g., bugfix command, or user skipped the step), note in the task that visual styling should follow existing patterns in the codebase.
+
+**Task granularity -- each step is ONE action:**
+
+- "Write the failing test" -- one step
+- "Run it to verify it fails" -- one step
+- "Implement minimal code to pass" -- one step
+- "Run tests to verify they pass" -- one step
+- "Commit" -- one step
+
+**Task structure:**
+
+```markdown
+### Task {N}: {Name}
+**Time:** 2-5 min | **Dependencies:** Task {X} | **Parallelizable:** Yes/No
+**Files:** Create: `path/to/file.ts` | Modify: `path/to/existing.ts:L1-L20` | Test: `tests/path/test.ts`
+**API contract ref:** `POST /resource` (if applicable)
+
+- [ ] Write failing test — include complete test code
+- [ ] Run: `{test command} {file}` | Expected: FAIL ("Cannot find module...")
+- [ ] Write minimal implementation — include complete implementation code
+- [ ] Run: `{test command} {file}` | Expected: PASS
+- [ ] `git commit -m "feat(scope): description"`
+```
+
+Rules for task content:
+
+- **Complete code in every step.** Never write "add validation logic here" or "implement the handler." Provide the actual code.
+- **Exact file paths.** Not "the test file" -- the specific path.
+- **Exact commands.** Not "run the tests" -- the specific command with arguments.
+- **Expected output.** What should the developer see after running the command?
+- **One behavior per test.** Each test tests one thing.
+- **Reference API contracts.** When a task implements an API endpoint, reference the exact contract section.
+
+### Step 4: Map Dependencies
+
+Create a dependency map showing task execution order:
+
+```markdown
+## Execution Order
+
+| Phase | Tasks | Parallel? |
+|---|---|---|
+| Phase 1: Foundation | Task 1, Task 2 | Yes |
+| Phase 2: Data Layer | Task 3, Task 4 | Yes (after Phase 1) |
+| Phase 3: Logic | Task 5 (needs 3+4), Task 6 (independent) | Partial |
+| Phase 4: API | Task 7 (needs Phase 3) | No |
+| Phase 5: Verification | Task 8 (needs Phase 4) | No |
+```
+
+Rules for dependency mapping:
+
+- **Explicit blocking relationships.** "Task 5 cannot start until Tasks 3 and 4 are complete because it imports types from both."
+- **Parallel opportunities.** Identify tasks that have no dependency on each other and can run simultaneously by different subagents.
+- **Phase grouping.** Group tasks into phases. All tasks in a phase can run in parallel. Phases execute sequentially.
+- **File-overlap validation.** After grouping tasks into phases, verify: no two tasks in the same phase create or modify the same file. If overlap is found, move one task to a later phase. Parallel tasks must have zero file overlap — merge conflicts are decomposition errors, not expected outcomes.
+- **Critical path.** Identify the longest dependency chain -- this determines minimum total time.
+
+### Step 5: Flag Subagent Coordination Points
+
+When multiple subagents will work on related tasks, flag the coordination requirements:
+
+```markdown
+## Subagent Coordination Points
+
+### Shared Interface: PaymentService <-> PaymentRoutes
+- **Contract:** POST /api/payments from api-contract.md
+- **Tasks affected:** Task 5 (Service), Task 7 (Routes)
+- **Agreement:** PaymentService.createPayment() accepts CreatePaymentInput, returns Payment
+- **Type definition:** Task 1 defines the shared types -- MUST be complete before Tasks 5 and 7 start
+
+### Shared Interface: PaymentModel <-> PaymentService
+- **Contract:** db-schema.md payments table
+- **Tasks affected:** Task 3 (Model), Task 5 (Service)
+- **Agreement:** Model exposes insert(), findById(), update() with types from Task 1
+```
+
+Rules:
+
+- **API contracts are the source of truth.** Subagents implement what the contract specifies, not what they think is best.
+- **Shared types must be defined first.** Flag any task that defines types consumed by other tasks as a hard prerequisite.
+- **Interface mismatches are the #1 cause of subagent bugs.** Make interfaces explicit and unambiguous.
+
+### Step 6: Write Plan Header
+
+Every plan starts with this header:
+
+```markdown
+# {Feature Name} Implementation Plan
+
+> **For agentic workers:** Use build-tdd skill to implement each task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** {One sentence describing what this builds}
+
+**Architecture:** {2-3 sentences about the approach, referencing brainstorm-approved.md}
+
+**Tech Stack:** {Key technologies and libraries}
+
+**Estimated tasks:** {N} tasks in {N} execution waves
+
+**Critical path:** {Tasks on the longest dependency chain}
+
+---
+```
+
+### Step 7: Write Complete Task Plan
+
+Assemble the full plan and save to `.forge/work/{type}/{name}/tasks.md`:
+
+1. Plan header (Step 6)
+2. File structure map (Step 2)
+3. Task dependency graph (Step 4)
+4. Subagent coordination points (Step 5)
+5. All tasks in execution order (Step 3)
+
+The plan must be self-contained. A developer or subagent with ZERO context about the project should be able to pick up the plan and execute it by following the tasks in order.
+
+### Step 7.5: Codex Verify 
+After writing the task plan, check the mode recorded at Step 1.5. If **Verify** was selected, dispatch Codex to review for missing dependencies, oversized tasks, and parallelization opportunities. Merge findings into the task plan before user review. If **Takeover** was selected, skip this step (Codex already decomposed). If **Skip**, do nothing. Do NOT re-run the consent flow. See **Codex Integration** section below for full details.
+
+### Step 8: Plan Review Loop
+
+After writing the complete plan, dispatch a spec-reviewer subagent:
+
+1. **Dispatch spec-reviewer** with precisely crafted review context -- provide the path to the plan document, the path to the architecture artifacts, and the path to the spec document. Never send your session history. This keeps the reviewer focused on the plan.
+2. **If issues found:** Fix the issues, re-dispatch reviewer for the whole plan.
+3. **If approved:** Proceed to user review.
+4. **Max 3 iterations.** If the loop exceeds 3 iterations without convergence, surface remaining issues to the user for guidance.
+
+The reviewer checks for:
+
+- **Completeness** -- does the plan implement everything in the architecture artifacts?
+- **Task granularity** -- is every task 2-5 minutes? Are any too large?
+- **Code quality** -- is the code in examples correct? Does it follow conventions?
+- **Dependencies** -- are all blocking relationships identified? Are parallel opportunities noted?
+- **Testability** -- does every task include tests? Do tests run?
+- **API contract alignment** -- do implementations match the contract exactly?
+
+Reviewer feedback is advisory. If you disagree with feedback, explain your reasoning. But fix legitimate issues.
+
+### Step 9: User Reviews Plan
+
+After the plan review loop passes:
+
+> "Implementation plan written to `.forge/work/{type}/{name}/tasks.md`. Summary:
+>
+> - **{N} tasks** across **{N} phases**
+> - **Critical path:** {tasks on longest chain}
+> - **Parallelizable tasks:** {N} tasks can run concurrently
+> - **Subagent coordination points:** {N}
+>
+> Please review the plan. Let me know if you want changes before we start implementation."
+
+Wait for user approval. If changes are requested, make them and re-run the plan review loop.
+
+### Step 10: Update Feature Manifest
+
+After approval, update `.forge/work/{type}/{name}/manifest.yaml`:
+
+```yaml
+artifacts:
+  tasks:
+    path: tasks.md
+    status: approved
+    approved_at: YYYY-MM-DD
+    task_count: N
+    phase_count: N
+    review_iterations: N
+    critical_path_length: N
+```
+
+### Step 11: Execution Handoff
+
+After saving and approving the plan, offer execution options:
+
+> "Plan complete and approved. Two execution options:
+>
+> **1. Subagent-Driven (recommended for multi-task plans)** -- `build-tdd` dispatches a builder subagent per task, review between tasks, fast iteration. Best when tasks can run in parallel.
+>
+> **2. Inline Execution** -- `build-tdd` executes directly in this session. Best for small plans (< 5 tasks) or when you want close oversight.
+>
+> Which approach?"
+
+**After the user chooses, persist the decision in the manifest immediately:**
+
+```yaml
+execution:
+  mode: subagent  # or: inline
+  decided_at: YYYY-MM-DD
+```
+
+This field is read by `build-tdd` to determine execution mode. It persists across resume so the mode does not change mid-feature.
+
+**Both modes follow the same skill flow:**
+- For each task (respecting dependency order): invoke `build-tdd` skill, then `quality-code-review` skill.
+- `build-tdd` reads `execution.mode` from the manifest and dispatches the builder subagent (subagent mode) or executes inline (inline mode).
+- Review each task output before proceeding.
+- Fix Critical/Important findings before the next task.
+
+---
+
+## Key Rules
+
+1. **2-5 minutes per task.** If a task takes longer, it is too big. Split it.
+2. **Exact file paths.** Every file mentioned has a complete, exact path.
+3. **Complete code examples.** Every step includes the actual code. No placeholders, no "implement here."
+4. **Exact commands with expected output.** "Run: `npm test` Expected: PASS" not "run the tests."
+5. **Reference API contracts.** When a task implements an endpoint, cite the contract section.
+6. **Map file structure first.** Before writing tasks, decide which files exist. This is where decomposition gets locked in.
+7. **Dependencies are explicit.** Every task states what it depends on and what depends on it.
+8. **Subagent coordination is flagged.** Tasks that share interfaces are marked with the shared contract.
+9. **Plan is self-contained.** A developer with zero project context can execute it.
+10. **DRY, YAGNI, TDD.** Do not duplicate logic, do not add features not in the architecture, and every task starts with a failing test.
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It Is Wrong | What To Do Instead |
+|---|---|---|
+| **Tasks larger than 5 minutes** | Large tasks have hidden complexity and fail unpredictably | Split until each task is one clear action |
+| **"Add validation" without code** | Implementor will guess wrong | Provide the exact validation code |
+| **Missing test steps** | TDD requires test-first | Every task starts with a failing test |
+| **No dependency mapping** | Tasks run out of order, imports break | Map every blocking relationship |
+| **Skipping plan review** | Unreviewed plans have gaps and inconsistencies | Always dispatch spec-reviewer |
+| **Monolithic "Phase 1" tasks** | "Set up the database layer" is not a task | Break into: create migration, create model, create types |
+| **Copy-paste from architecture** | Architecture defines WHAT, tasks define HOW step by step | Translate contracts into implementation steps |
+| **Forgetting commit steps** | Work is lost, history is unclear | Every task ends with a commit |
+| **Ignoring parallel opportunities** | Sequential execution of independent tasks wastes time | Identify and document parallelizable tasks |
+
+---
+
+## Task Size Guidelines
+
+| Too Small | Just Right | Too Large |
+|---|---|---|
+| "Add import statement" | "Write failing test for createPayment" | "Implement the payment service" |
+| "Create empty file" | "Implement createPayment to pass test" | "Set up the entire API layer" |
+| "Add comma to config" | "Add payment routes with error handling" | "Write all tests" |
+
+A good task has:
+- One clear objective
+- One test (or a small group of related tests)
+- One commit at the end
+- A verifiable outcome (test passes, command succeeds)
+
+---
+
+## Handling Special Cases
+
+### Refactoring Tasks
+
+When the plan includes refactoring (splitting a large file, renaming, restructuring):
+1. Refactoring tasks come BEFORE feature tasks
+2. Each refactoring task has tests proving behavior is preserved
+3. Commit refactoring separately from feature work
+
+### Database Migration Tasks
+
+Migration tasks have a specific structure:
+1. Write migration file (forward)
+2. Write rollback migration
+3. Test: apply migration on clean DB
+4. Test: apply migration on seeded DB
+5. Test: rollback and re-apply
+6. Commit migration files
+
+### Third-Party Integration Tasks
+
+When a task involves external APIs or services:
+1. Define the integration interface first (types, client shape)
+2. Write tests with the interface mocked
+3. Implement the real client
+4. Write integration tests that hit the real service (flagged as slow/external)
+
+---
+
+## Graphify Context (Static-only)
+
+**Protocol:** `protocols/graphify.md` | **Mode:** Static-only — read `graphify-out/graph.json` if it exists, skip if absent. No guard, no build prompts, no CLI queries.
+
+**How graph data maps to this skill:**
+- **Tasks touching the same community** → likely share files or state, serialize them
+- **Tasks in different communities** → likely independent, candidates for parallel phases
+- **God nodes** → tasks modifying god nodes should be in early phases (downstream tasks depend on them)
+
+---
+
+## Codex Integration
+**Modes:** Verify or Takeover | **Protocol:** `protocols/codex.md`
+
+- **Verify:** Claude decomposes tasks, Codex reviews for gaps.
+- **Takeover:** Codex decomposes tasks, Claude reviews dependencies and ordering.
+
+**When:** After Claude has produced the task decomposition with phases, dependencies, and code examples.
+
+**Context to pass:**
+- Path to `.forge/work/{type}/{name}/tasks.md`
+- Path to `.forge/work/{type}/{name}/architecture/` artifacts
+- Path to `.forge/work/{type}/{name}/codebase-analysis.md` (if available)
+
+**What Codex reviews:**
+- Missing dependencies between tasks (task B needs task A's output but isn't blocked by it)
+- Tasks that are too large (should be split further)
+- Code examples that contradict the architecture artifacts
+- Parallelization opportunities missed
+
+**Prompt focus:** "Review this task decomposition for missing dependencies, oversized tasks, and parallelization opportunities. Check that code examples match the architecture artifacts."
+
+**Presentation:** Merge Codex findings into the task plan. Fix dependency gaps before handoff to execution.
+
+---
+
+## Transition
+
+The terminal state is execution handoff. After execution begins, the plan is consumed by `build-tdd` and `build-pr-workflow` skills. Updates flow back into the manifest as tasks are completed:
+
+```yaml
+tasks:
+  completed: N
+  total: N
+  current_phase: N
+  blocked: []
+```