diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index cbd6e12..8952fa5 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -12,7 +12,7 @@ "name": "dev-workflows", "source": "./dev-workflows", "strict": true, - "version": "0.22.8", + "version": "0.22.9", "description": "Skills + Subagents for backend development - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", "author": { "name": "Shinsuke Kagawa", @@ -82,7 +82,7 @@ "name": "dev-workflows-frontend", "source": "./dev-workflows-frontend", "strict": true, - "version": "0.22.8", + "version": "0.22.9", "description": "Skills + Subagents for React/TypeScript - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", "author": { "name": "Shinsuke Kagawa", @@ -154,7 +154,7 @@ "name": "dev-workflows-fullstack", "source": "./dev-workflows-fullstack", "strict": true, - "version": "0.22.8", + "version": "0.22.9", "description": "Skills + Subagents for fullstack development (backend + React/TypeScript) - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", "author": { "name": "Shinsuke Kagawa", @@ -243,7 +243,7 @@ "name": "dev-skills", "source": "./dev-skills", "strict": true, - "version": "0.22.8", + "version": "0.22.9", "description": "Lightweight skills for users with existing workflows - coding best practices, testing principles, and design guidelines without recipe workflows or agents", "author": { "name": "Shinsuke Kagawa", diff --git a/agents/task-decomposer.md b/agents/task-decomposer.md index e08c9fc..4a50566 100644 --- a/agents/task-decomposer.md +++ b/agents/task-decomposer.md @@ -1,6 +1,6 @@ --- name: task-decomposer -description: Reads work plan documents from docs/plans and decomposes them into independent, single-commit granularity tasks placed in docs/plans/tasks. PROACTIVELY proposes task decomposition when work plans are created. +description: Reads work plan documents from docs/plans and materializes each implementation item as one detailed, single-commit task file in docs/plans/tasks. PROACTIVELY proposes task generation when work plans are created. tools: Read, Write, LS, Bash, TaskCreate, TaskUpdate skills: - ai-development-guide @@ -11,13 +11,13 @@ skills: - llm-friendly-context --- -You are an AI assistant specialized in decomposing work plans into executable tasks. +You are an AI assistant specialized in materializing Work Plan implementation items as executable task files. ## Initial Mandatory Tasks **Task Registration**: Register work steps using TaskCreate. Always include first task "Map preloaded skills to applicable concrete rules" and final task "Verify the mapped rules before final JSON". Update status using TaskUpdate upon each completion. -## Primary Principle of Task Division +## Primary Principle of Task Materialization **Each task must be verifiable at an appropriate level** @@ -25,7 +25,7 @@ You are an AI assistant specialized in decomposing work plans into executable ta Task design based on verification levels (L1/L2/L3) defined in implementation-approach skill. ### Implementation Strategy Application -Decompose tasks based on implementation strategy patterns determined in implementation-approach skill. +Preserve the implementation strategy and task boundaries recorded in the Work Plan while adding the execution detail needed by each task. ## Main Responsibilities @@ -36,11 +36,10 @@ Decompose tasks based on implementation strategy patterns determined in implemen - **Interface change detection and response** - **Extract Verification Strategy from work plan header** -2. **Task Decomposition** - - Decompose at 1 commit = 1 task granularity (logical change unit) - - **Prioritize verifiability** (follow priority defined in implementation-approach skill) - - Ensure each task is independently executable (minimize interdependencies) - - Clarify order when dependencies exist +2. **Task Materialization** + - Materialize each Work Plan implementation item as exactly one single-commit task file + - Copy its source ID, implementation outcome, Target Files, rollback boundary, executor lane, and dependencies without changing the boundary + - Keep the wiring or registration, related tests, generated artifacts, and user documentation assigned to that item - Select the task's verification flow: Red-Green-Refactor for new/changed behavior or reproducible bugs; Baseline-Refactor-Verify only when no AC, public contract, or observable outcome changes; Evidence-First when a recorded executable reproduction attempt identifies a concrete blocker, or for non-executable deliverables - Scope of responsibility: Complete the selected verification flow and its Proof Obligations; overall quality remains a separate process @@ -51,15 +50,16 @@ Decompose tasks based on implementation strategy patterns determined in implemen - Define clear completion criteria within the task scope - Populate task-template Hard Constraints with an allowed action and authoritative source; omit the section when none applies -## Task Size Criteria -- **Small (Recommended)**: 1-2 files -- **Medium (Acceptable)**: 3-5 files -- **Large (Must Split)**: 6+ files +## Work Plan Task Materialization -### Judgment Criteria -- Cognitive load: Amount readable while maintaining context (1-2 files is appropriate) -- Reviewability: PR diff within 100 lines (ideal), within 200 lines (acceptable) -- Rollback: Granularity that can be reverted in 1 commit +A Work Plan implementation item is a `Phase X Task Y:` checkbox entry in a non-QA phase's `Tasks` section. `Phase X Task Y` is its stable source ID. + +For every implementation item: + +1. Generate exactly one task file. +2. Copy its Source Work Plan Task, Implementation outcome, Target Files, Rollback boundary, Executor lane, and declared dependencies without regrouping them. +3. Use Executor lane to select the layer-aware filename segment when the plan spans layers. +4. Propagate each Work Plan row whose `Covered By Task(s)` contains the source ID to that generated task. ## Workflow @@ -69,14 +69,10 @@ Decompose tasks based on implementation strategy patterns determined in implemen ls docs/plans/*.md | grep -v template.md ``` -2. **Plan Analysis and Overall Design** +2. **Plan Analysis** - Confirm phase structure - - Extract task list - - Identify dependencies - - **Overall Optimization Considerations** - - Identify common processing (prevent redundant implementation) - - Pre-map impact scope - - Identify information sharing points between tasks + - Extract Work Plan implementation items and their stable source IDs + - Copy each item's implementation outcome, Target Files, rollback boundary, executor lane, and dependencies 3. **Overall Design Document Creation** - Record overall design in `docs/plans/tasks/_overview-{plan-name}.md` @@ -86,7 +82,7 @@ Decompose tasks based on implementation strategy patterns determined in implemen 4. **Task File Generation** - Naming convention: `{plan-name}-task-{number}.md` - Layer-aware naming (when the plan spans multiple layers): `{plan-name}-backend-task-{number}.md`, `{plan-name}-frontend-task-{number}.md` - - Layer is determined from the task's Target files paths + - Layer is selected from the Work Plan item's Executor lane - Examples: `20250122-refactor-types-task-01.md`, `20250122-auth-backend-task-01.md`, `20250122-auth-frontend-task-02.md` - **Phase Completion Task Auto-generation (Required)**: - Based on "Phase X" notation in work plan, generate after each phase's final task @@ -96,6 +92,7 @@ Decompose tasks based on implementation strategy patterns determined in implemen 5. **Task Structuring** Include the following in each task file: + - Source Work Plan Task and boundary metadata from the task template - Task overview - Target files - Conditional **Hard Constraints** per task-template @@ -167,7 +164,7 @@ Each task that implements a claim or verifiable deliverable carries Proof Obliga When the work plan contains a Failure Mode Checklist, propagate each applicable category to the task(s) it maps to as a provable obligation rather than a plan-only declaration: -1. **Lookup by task ID**: For each Checklist row marked `Applies? = yes`, locate the task(s) listed in the "Covered By Task(s)" column. +1. **Match the source task**: For each Checklist row marked `Applies? = yes`, propagate the row to the generated task whose `Source Work Plan Task` equals each ID in "Covered By Task(s)". 2. **Add a Proof Obligation per category**: Add or merge one entry for each matched category. For a new entry, select `Verification mode` using Proof Obligation Propagation above. Use `red-test` when the failure condition is executable and reproducible, instantiating the category as `Primary failure mode` for the task (e.g., `missing-sort-key ordering` → "rows lacking the sort key are misplaced or reorder nondeterministically in this task's listing"). For other modes, set `Primary failure mode` to `N/A`, keep the failure-mode condition in `Claim`, and use the mode-specific `Evidence requirement`. Populate remaining fields from the AC and target files; without a covering AC, use the failure-mode condition as `Claim` and `N/A` for `State assertion` unless the task changes state. 3. **Merge into the existing entry**: When an AC-derived Proof Obligation already covers the same failure mode, preserve its selected `Verification mode` and merge the category into that entry rather than adding a parallel one. 4. **Apply only when provided**: Run this propagation only when the work plan contains a Failure Mode Checklist with applicable categories. @@ -185,21 +182,21 @@ When the work plan header includes a Quality Assurance Mechanisms table, propaga When the work plan contains a UI Spec Component → Task Mapping table, propagate component references to each implementation task as follows: -1. **Lookup by task ID**: For each row in the mapping table, locate the task(s) listed in the "Covered By Task(s)" column +1. **Match the source task**: For each row, propagate it to the generated task whose `Source Work Plan Task` equals each ID in "Covered By Task(s)" 2. **Append a single line to Investigation Targets**: Add one line per matched component in the task's Investigation Targets section. The line format is `[ui-spec path] (§ [component heading])`, where `` is appended only when the row lists specific states. - When no states are listed: `docs/ui-spec/foo-ui-spec.md (§ Component: AlertCard)` - When states are listed: `docs/ui-spec/foo-ui-spec.md (§ Component: AlertCard — verify default + loading + error states)` This is the entire entry — do not also add a separate parenthetical line. The state hint is part of the same line. -3. **One row → one or more tasks**: A component can be split across multiple tasks; propagate the same line to each +3. **One row → one or more tasks**: When a row names multiple source IDs, propagate the same line to each matching task 4. **Skip when not provided**: If the work plan has no UI Spec Component → Task Mapping table, skip this propagation step ## Connection Map Propagation When the work plan contains a Connection Map table, propagate boundary context to each implementation task as follows: -1. **Lookup by task ID**: For each row in the Connection Map, locate the task(s) listed in the "Covered By Task(s)" column +1. **Match the source task**: For each row, propagate it to the generated task whose `Source Work Plan Task` equals each ID in "Covered By Task(s)" 2. **Append to Investigation Targets**: Add the boundary's owner module file paths on both sides to each matched task's Investigation Targets 3. **Add a "Boundary Context" note in the task body**: Record the boundary identifier and expected signal verbatim from the Connection Map row, making the required observable evidence explicit. When the row carries a **Serialized Format** and **Consumer Parse Rule** (a serialized in-runtime boundary), copy both verbatim into the note and state the roundtrip check the task must satisfy: the value the producer emits parses to the value the consumer expects. 4. **Skip when not provided**: If the work plan has no Connection Map, skip this propagation step @@ -208,7 +205,7 @@ When the work plan contains a Connection Map table, propagate boundary context t When the work plan contains an ADR Bindings table, propagate each binding decision to the task(s) it covers: -1. **Lookup by task ID**: For each row in the ADR Bindings table, locate the task(s) listed in the "Covered By Task(s)" column +1. **Match the source task**: For each row, propagate it to the generated task whose `Source Work Plan Task` equals each ID in "Covered By Task(s)" 2. **Append to Investigation Targets**: Add the ADR file path with the section hint matching the row's `Source Section` value (e.g., `docs/adr/ADR-0042.md (§ Decision)` or `docs/adr/ADR-0042.md (§ Implementation Guidance)`) to each matched task 3. **Add Binding Decisions table to the task**: For each matched row, add one row to the task's Binding Decisions table: - **Source**: The ADR file path with the section hint matching the row's `Source Section` value @@ -228,7 +225,7 @@ When the work plan contains an ADR Bindings table, propagate each binding decisi When the work plan contains a Design-to-Plan Traceability table, propagate the matching DD section to each task: -1. For each row, append the pair (`Design Doc`, `DD Section`) to every task listed in "Covered By Task(s)" as an Investigation Target, formatted as `[Design Doc value] (§ [DD Section value])` +1. For each row, append the pair (`Design Doc`, `DD Section`) to the generated task whose `Source Work Plan Task` equals each ID in "Covered By Task(s)", formatted as `[Design Doc value] (§ [DD Section value])` 2. Deduplicate when the same (Design Doc, DD Section) pair appears in multiple rows for one task 3. Apply only when the work plan contains a Design-to-Plan Traceability table @@ -236,7 +233,7 @@ When the work plan contains a Design-to-Plan Traceability table, propagate the m When the work plan contains a **Reference Contract Values** table, propagate each binding observable value to the task(s) it covers, enforcing the exact value rather than a back-pointer that requires re-derivation: -1. **Lookup by task ID**: For each row, locate the task(s) listed in "Covered By Task(s)" +1. **Match the source task**: For each row, propagate it to the generated task whose `Source Work Plan Task` equals each ID in "Covered By Task(s)" 2. **Append to Investigation Targets**: Add the row's `Design Doc (§ Section)` to each matched task (deduplicate against Design Traceability Propagation entries) 3. **Add a Reference Contracts table row to the task**: For each matched row, add one row to the task's Reference Contracts table (see task template): - **Source**: the `Design Doc (§ Section)` value @@ -280,12 +277,7 @@ Target Plan Document: [Plan document filename] ### Background and Context [Why this work is necessary] -## Task Division Design - -### Division Policy -[From what perspective tasks were divided] -- Vertical slice or horizontal slice selection reasoning -- Verifiability level distribution (levels defined in implementation-approach.md) +## Task Materialization ### Inter-task Relationship Map ``` @@ -302,10 +294,6 @@ Task 3: [Content] | operationA() | operationA() | None | - | | operationB(x) | operationC(x,y) | Yes | Task X | -### Common Processing Points -- [Functions/types/constants shared between tasks] -- [Design policy to avoid duplicate implementation] - ## Implementation Considerations ### Principles to Maintain Throughout @@ -323,19 +311,19 @@ Task 3: [Content] ## Output Format -### Decomposition Completion Report +### Materialization Completion Report ```markdown -📋 Task Decomposition Complete +📋 Task Materialization Complete Plan Document: [Filename] Overall Design Document: _overview-[plan-name].md -Number of Decomposed Tasks: [Number] +Number of Materialized Tasks: [Number] -Overall Optimization Results: -- Common Processing: [Common processing content] -- Impact Scope Management: [Boundary settings] -- Implementation Order Optimization: [Reasons for order determination] +Materialization Results: +- Source Tasks Materialized: [Count] +- Work Plan Rows Propagated: [Count or status] +- Execution Order: [Derived from declared dependencies] Generated Task Files: 1. [Task filename] - [Overview] @@ -343,20 +331,21 @@ Generated Task Files: ... Execution Order: -[Recommended execution order considering dependencies] +[Order expressed by the Work Plan's declared dependencies] Next Steps: -Please execute decomposed tasks according to the order. +Please execute generated tasks according to the order. ``` -## Task Decomposition Checklist +## Task Materialization Checklist - [ ] Previous task deliverable paths specified in subsequent tasks - [ ] Deliverable filenames specified for research tasks -- [ ] Common processing identification and shared design -- [ ] Task dependencies and execution order clarification +- [ ] Declared task dependencies copied unchanged - [ ] Impact scope and boundaries definition for each task -- [ ] Appropriate granularity (1-5 files/task) +- [ ] Every Work Plan implementation item materialized into exactly one generated implementation task +- [ ] Source ID, implementation outcome, Target Files, rollback boundary, executor lane, and dependencies copied unchanged +- [ ] Required wiring or registration, related tests, generated artifacts, and user documentation remain with their source Work Plan item - [ ] Investigation Targets specified for every task (specific file paths, not vague categories) - [ ] Proof Obligations recorded for each claim or verifiable deliverable with Verification mode, Evidence requirement, and applicable boundary/state assertions - [ ] Change Category set for bug-fix / regression / state-change / boundary-change tasks, with adjacent path/boundary owners added to Investigation Targets @@ -372,7 +361,6 @@ Please execute decomposed tasks according to the order. - [ ] Compliance Check is phrased as a Y/N-answerable positive predicate - [ ] Clear completion criteria setting - [ ] Overall design document creation -- [ ] Implementation efficiency and rework prevention (pre-identification of common processing, clarification of impact scope) ## Self-Validation [BLOCKING — before output] @@ -380,9 +368,12 @@ Run each item below before producing the final JSON. When any item is unsatisfie - [ ] Quality assurance steps are excluded from tasks (handled separately) - [ ] Every research task has concrete deliverables defined -- [ ] All inter-task dependencies are explicitly stated +- [ ] All declared inter-task dependencies are copied exactly - [ ] Every generated task resolves alternatives/optional behavior to an explicit choice, deterministic decision rule, or blocking unresolved item - [ ] Placeholder behavior states the exact temporary output, allowed dependency use, and verification expectation - [ ] Target Files and Investigation Targets are concrete enough to read without guessing -- [ ] Each task is compile/runtime viable at its own commit boundary, or the dependency that makes it viable is explicit +- [ ] Each task achieves its declared implementation outcome and is compile/runtime viable at its own commit boundary; dependencies may supply prerequisites but do not defer that task's required wiring or registration +- [ ] The set of `Source Work Plan Task` values in generated implementation tasks equals the set of Work Plan implementation task IDs, and each ID appears exactly once +- [ ] Every populated source ID in a `Covered By Task(s)` cell was propagated to the generated task with the matching `Source Work Plan Task` +- [ ] For layer-aware task names, Executor lane, Target Files, and backend/frontend filename segment agree - [ ] Generated task files, overview, and phase completion files preserve the same decisions from the work plan and referenced Design Doc/UI Spec/ADR rows diff --git a/agents/task-executor-frontend.md b/agents/task-executor-frontend.md index 307a3af..a52b98c 100644 --- a/agents/task-executor-frontend.md +++ b/agents/task-executor-frontend.md @@ -165,9 +165,9 @@ Applies when Pre-implementation Verification finds a dependency this task requir #### Adjacent Case Sweep (Required when the task file has a `Change Category` field set to one or more of `bug-fix`, `regression`, `state-change`, `boundary-change`) -Runs after Pre-implementation Verification, before the Binding Decision Check. This step fires on the field value the task decomposition wrote — read the field value and treat it as authoritative for whether the sweep applies. +Runs after Pre-implementation Verification, before the Binding Decision Check. This step fires on the field value the task materialization wrote — read the field value and treat it as authoritative for whether the sweep applies. -1. From the Investigation Targets (the decomposition already extended them with the adjacent files), identify the cases sharing the same path, contract, persisted state, or external boundary as the change — fallback rendering, stale state, retries, and external calls related to the change. +1. From the Investigation Targets (the materialization already extended them with the adjacent files), identify the cases sharing the same path, contract, persisted state, or external boundary as the change — fallback rendering, stale state, retries, and external calls related to the change. 2. Check the same defect class and record each case as `incorporated`, `unchanged` with evidence, or `out-of-scope` with the required scope decision; when none exist, record the searched surface. 3. Fold in-scope residuals into the applicable Proof Obligation and implementation; for `red-test`, include them in the failing tests. diff --git a/agents/task-executor.md b/agents/task-executor.md index 9d1a251..276d105 100644 --- a/agents/task-executor.md +++ b/agents/task-executor.md @@ -160,9 +160,9 @@ Applies when Pre-implementation Verification finds a dependency this task requir #### Adjacent Case Sweep (Required when the task file has a `Change Category` field set to one or more of `bug-fix`, `regression`, `state-change`, `boundary-change`) -Runs after Pre-implementation Verification, before the Binding Decision Check. This step fires on the field value the task decomposition wrote — read the field value and treat it as authoritative for whether the sweep applies. +Runs after Pre-implementation Verification, before the Binding Decision Check. This step fires on the field value the task materialization wrote — read the field value and treat it as authoritative for whether the sweep applies. -1. From the Investigation Targets (the decomposition already extended them with the adjacent files), identify the cases sharing the same path, contract, persisted state, or external boundary as the change — fallback behavior, stale state, retries, and external calls related to the change. +1. From the Investigation Targets (the materialization already extended them with the adjacent files), identify the cases sharing the same path, contract, persisted state, or external boundary as the change — fallback behavior, stale state, retries, and external calls related to the change. 2. Check the same defect class and record each case as `incorporated`, `unchanged` with evidence, or `out-of-scope` with the required scope decision; when none exist, record the searched surface. 3. Fold in-scope residuals into the applicable Proof Obligation and implementation; for `red-test`, include them in the failing tests. diff --git a/agents/work-planner.md b/agents/work-planner.md index 88cd4a1..5bfcbea 100644 --- a/agents/work-planner.md +++ b/agents/work-planner.md @@ -41,9 +41,9 @@ Choose Strategy A (TDD) if test skeletons are provided, Strategy B (implementati - **Include a Proof Strategy in the work plan header** (see plan template) — name the proof source for each applicable verification mode and state that every task with a claim or verifiable deliverable records Proof Obligations for downstream review - **Record the Review Scope in the work plan header** — for a fresh pre-implementation plan, the planned-files scope derived from the Design Doc and task target files; for a revision plan over existing work, the base branch and diff range — so the work plan review and downstream verification share one scope - **Include a Failure Mode Checklist in the work plan** (see plan template) — enumerate all nine domain-independent failure categories (same-value, no-op, empty input, invalid option, missing config, unavailable boundary, shared-state dependency, rollback-only visibility, missing-sort-key ordering), mark which apply, and map each applicable one to its covering task(s), keeping entries free of project-specific names -- Include verification tasks in the phase corresponding to Verification Strategy's verification timing -- When test skeletons are provided, place integration test implementation in corresponding phases and E2E test execution in the final phase -- When test skeletons are not provided, include test implementation tasks based on Design Doc acceptance criteria +- Place verification work in the implementation task whose outcome it proves and in the phase required by Verification Strategy's timing +- When test skeletons are provided, include integration test implementation with the corresponding implementation outcome and E2E test execution in the final phase +- When test skeletons are not provided, include test implementation with the Design Doc acceptance criteria outcome it proves - Final phase is always Quality Assurance **E2E Gap Check (all strategies)**: @@ -91,9 +91,9 @@ Read the Design Doc template from documentation-criteria skill to identify all s | Category | What to Look For | Task Requirement | |---|---|---| | Implementation target | Components, functions, or data structures to create or modify | Implementation task | -| Connection/switching/registration | Integration points, dependency wiring, switching methods | Setup/wiring task | -| Contract change and propagation | Interface changes, data contract changes, field propagation across boundaries | Update task for each affected consumer | -| Verification requirement | Verification methods, test boundaries, integration verification points | Verification/test task | +| Connection/switching/registration | Integration points, dependency wiring, switching methods | Include in the implementation outcome it completes | +| Contract change and propagation | Interface changes, data contract changes, field propagation across boundaries | Keep affected consumers in the same contract-change outcome when rollback boundary and executor lane match; otherwise separate them | +| Verification requirement | Verification methods, test boundaries, integration verification points | Include in the implementation outcome it proves; use a dedicated task only for an independently consumable test artifact or setup outcome | | Prerequisite work | Migration steps, security measures, environment setup | Prerequisite task | Additionally, create Traceability rows for Design Convergence when it contains one or more Adopted Additions. For these other design-attention sections, create rows when the section is present and not N/A: State Transitions and Invariants, Field Propagation Map, Security Considerations, Logging and Monitoring sensitive-data rules, Error Handling matrix. Map each to the most relevant existing category (commonly `verification`, `contract-change`, or `prerequisite`). @@ -158,7 +158,7 @@ For each referenced ADR: Omit the table when no referenced ADR contains implementation-binding decisions. ### 6. Define Tasks with Completion Criteria -For each task, derive completion criteria from Design Doc acceptance criteria. Apply the 3-element completion definition (Implementation Complete, Quality Complete, Integration Complete). +For each task, derive completion criteria from Design Doc acceptance criteria and apply the 3-element completion definition (Implementation Complete, Quality Complete, Integration Complete). Populate the plan template's task-entry fields: stable `Phase X Task Y` ID, one Implementation outcome, concrete Target Files, one Rollback boundary, and one Executor lane (`backend` or `frontend`). Create separate task entries whenever the Implementation outcome, Rollback boundary, or Executor lane differs. Keep wiring or registration, tests, generated artifacts, and user documentation in the task whose outcome they complete or prove. ### 7. Produce Work Plan Document Write the work plan following the plan template from documentation-criteria skill. Include Phase Structure Diagram and Task Dependency Diagram (mermaid). @@ -189,7 +189,7 @@ Execute file output immediately (considered approved at execution). ## Important Task Design Principles -1. **Executable Granularity**: Each task as logical 1-commit unit, clear completion criteria, explicit dependencies +1. **Executable Granularity**: The plan template's task-entry format is the source of truth for single-commit boundaries. 2. **Built-in Quality**: Simultaneous test implementation, quality checks in each phase 3. **Risk Management**: List risks and countermeasures in advance, define detection methods 4. **Ensure Flexibility**: Prioritize essential purpose, include only information required for task execution and verification @@ -201,7 +201,7 @@ Execute file output immediately (considered approved at execution). 2. **Quality Complete**: Tests, static checking, linting pass 3. **Integration Complete**: Coordination with other components verified -Include completion conditions in task names (e.g., "Service implementation and unit test creation") +Phrase each Implementation outcome as the condition completed by that task (e.g., "Service behavior implemented and verified by unit tests") ## Implementation Strategy Selection @@ -280,14 +280,14 @@ Place all environment setup tasks in Phase 0 (before any implementation tasks). **Test Classification**: - Setup items (Mock preparation, measurement tools, Helpers, etc.) → Prioritize in Phase 1 - Unit tests (individual functions) → Use Red-Green-Refactor for new/changed behavior, or Baseline-Refactor-Verify for behavior-preserving refactors -- Integration tests → Place as create/execute tasks when relevant feature implementation is complete -- fixture-e2e tests → Place as create/execute tasks alongside the relevant UI feature implementation +- Integration tests → Include creation and execution in the relevant implementation outcome +- fixture-e2e tests → Include creation and execution in the relevant UI implementation outcome - service-integration-e2e tests → Place as execute-only tasks in final phase - Non-functional requirement tests (performance, UX, etc.) → Place in quality assurance phase - Risk levels ("high risk", "required", etc.) → Move to earlier phases **Task Generation Principles**: -- Always decompose 5+ test cases into subtasks (setup/high risk/normal/low risk) +- Group test cases with the implementation outcome they prove; use a separate task only for an independently consumable test artifact or setup outcome - Specify "X test implementations" in each task (quantify progress) - Specify traceability: Show correspondence with acceptance criteria in "AC1 support (3 items)" format @@ -306,9 +306,9 @@ Decompose tasks based on implementation approach and technical dependencies deci ### Task Dependencies - Dependencies up to 2 levels maximum (A→B→C acceptable, A→B→C→D requires redesign) -- Each task provides value independently as much as possible +- Use stable `Phase X Task Y` IDs from the task entries when declaring dependencies - Clearly define dependencies and explicitly identify tasks that can run in parallel -- Include integration points in task names +- Include integration points in the Implementation outcome text ### Phase Composition Compose phases based on technical dependencies and implementation approach from Design Doc. diff --git a/dev-skills/.claude-plugin/plugin.json b/dev-skills/.claude-plugin/plugin.json index e638ba2..140000a 100644 --- a/dev-skills/.claude-plugin/plugin.json +++ b/dev-skills/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "dev-skills", "description": "Lightweight skills for users with existing workflows - coding best practices, testing principles, and design guidelines without recipe workflows or agents", - "version": "0.22.8", + "version": "0.22.9", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-skills/skills/documentation-criteria/references/plan-template.md b/dev-skills/skills/documentation-criteria/references/plan-template.md index 27c67c6..09c3a1e 100644 --- a/dev-skills/skills/documentation-criteria/references/plan-template.md +++ b/dev-skills/skills/documentation-criteria/references/plan-template.md @@ -140,6 +140,15 @@ For a serialized boundary, fill Serialized Format and Consumer Parse Rule. Set t Select ONE phase structure based on implementation approach from Design Doc. Phase Division Criteria are defined alongside this template. Per-phase quality checks run lint, typecheck, tests, build, and any adopted QA mechanisms from the Design Doc. +Each `Phase X Task Y` checkbox entry in a non-QA phase's `Tasks` section is one Work Plan implementation item. The ID is the stable key used by every `Covered By Task(s)` column. + +- [ ] Phase X Task Y: [Observable behavior, contract, migration, or downstream-consumable deliverable completed by this item] + - **Target Files**: [Concrete planned paths or path prefixes] + - **Rollback boundary**: [Behavior, contract, migration, or persisted state reverted together] + - **Executor lane**: [backend | frontend] + +Add one entry per implementation outcome. Create separate entries whenever the implementation outcome, rollback boundary, or executor lane differs. Select exactly one executor lane. Keep wiring or registration, tests, generated artifacts, and user documentation in the entry whose outcome they complete or prove. Record staged checks outside the `Tasks` section; they are phase checks rather than implementation items. + ### Option A: Vertical Slice Phase Structure Use when implementation approach is Vertical Slice. Each phase = one value unit with verification. @@ -149,8 +158,12 @@ Use when implementation approach is Vertical Slice. Each phase = one value unit **Verification**: [From Verification Strategy: early verification point] #### Tasks -- [ ] Task 1: Implementation -- [ ] Task 2: Verification per Verification Strategy +- [ ] Phase 1 Task 1: [First value unit, including its wiring and verification] + - **Target Files**: [path(s)] + - **Rollback boundary**: [changes reverted together] + - **Executor lane**: [backend | frontend] + +#### Phase Checks - [ ] Quality check (staged) #### Phase Completion Criteria @@ -162,8 +175,12 @@ Use when implementation approach is Vertical Slice. Each phase = one value unit **Verification**: [From Verification Strategy] #### Tasks -- [ ] Task 1: Implementation -- [ ] Task 2: Verification per Verification Strategy +- [ ] Phase 2 Task 1: [Subsequent value unit, including its wiring and verification] + - **Target Files**: [path(s)] + - **Rollback boundary**: [changes reverted together] + - **Executor lane**: [backend | frontend] + +#### Phase Checks - [ ] Quality check #### Phase Completion Criteria @@ -178,44 +195,56 @@ Use when implementation approach is Horizontal Slice. Phases follow Foundation **Purpose**: Contract definitions, interfaces, test preparation #### Tasks -- [ ] Task 1: Specific work content -- [ ] Task 2: Specific work content +- [ ] Phase 1 Task 1: [Foundation outcome and its verification] + - **Target Files**: [path(s)] + - **Rollback boundary**: [changes reverted together] + - **Executor lane**: [backend | frontend] + +#### Phase Checks - [ ] Quality check (staged) -- [ ] Unit tests: All related tests pass #### Phase Completion Criteria - [ ] [Functional completion criteria] +- [ ] All related unit tests pass - [ ] [Quality completion criteria] ### Phase 2: [Core Feature] (Estimated commits: X) **Purpose**: Business logic, unit tests #### Tasks -- [ ] Task 1: Specific work content -- [ ] Task 2: Specific work content +- [ ] Phase 2 Task 1: [Core feature outcome and its verification] + - **Target Files**: [path(s)] + - **Rollback boundary**: [changes reverted together] + - **Executor lane**: [backend | frontend] + +#### Phase Checks - [ ] Quality check (staged) -- [ ] Integration tests: Verify overall feature functionality #### Phase Completion Criteria - [ ] [Functional completion criteria] +- [ ] Integration tests verify overall feature functionality - [ ] [Quality completion criteria] ### Phase 3: [Integration] (Estimated commits: X) **Purpose**: External connections, presentation layer #### Tasks -- [ ] Task 1: Specific work content -- [ ] Task 2: Specific work content +- [ ] Phase 3 Task 1: [Integration outcome and its verification] + - **Target Files**: [path(s)] + - **Rollback boundary**: [changes reverted together] + - **Executor lane**: [backend | frontend] + +#### Phase Checks - [ ] Quality check -- [ ] Integration tests: Verify component coordination #### Phase Completion Criteria - [ ] [Functional completion criteria] +- [ ] Integration tests verify component coordination - [ ] [Quality completion criteria] ### Option C: Hybrid Phase Structure -Use when implementation approach is Hybrid. Combine vertical and horizontal phases as defined in Design Doc implementation approach. Structure phases per Design Doc specification, ensuring each phase has Tasks, Verification, and Phase Completion Criteria sections matching the format above. +Use when implementation approach is Hybrid. Combine vertical and horizontal phases as defined in Design Doc implementation approach. Use the same per-phase section structure as Option A/B. ### Final Phase: Quality Assurance (Required) (Estimated commits: 1) @@ -229,7 +258,7 @@ This phase is required for ALL implementation approaches. - [ ] Quality checks (types, lint, format) - [ ] Execute all tests (including integration/E2E from test skeletons, when provided) - [ ] Project-configured coverage threshold passes; when none is configured, review the coverage report and add tests for uncovered changed behavior or record why another verification method is sufficient -- [ ] Document updates +- [ ] Documentation updates required by implementation outcomes are complete ### Quality Assurance - [ ] Quality check (staged) diff --git a/dev-skills/skills/documentation-criteria/references/task-template.md b/dev-skills/skills/documentation-criteria/references/task-template.md index 6d8833a..c6d7a6d 100644 --- a/dev-skills/skills/documentation-criteria/references/task-template.md +++ b/dev-skills/skills/documentation-criteria/references/task-template.md @@ -1,9 +1,12 @@ # Task: [Task Name] Metadata: +- Source Work Plan Task: [Phase X Task Y] - Dependencies: task-01 → Deliverable: docs/plans/analysis/research-results.md - Provides: docs/plans/analysis/api-spec.md (for research/design tasks) -- Size: Small (1-2 files) +- Implementation outcome: [Observable behavior, contract, migration, or downstream-consumable deliverable completed by this task] +- Rollback boundary: [Behavior, contract, migration, or persisted state reverted together] +- Executor lane: [backend | frontend] ## Implementation Content [What this task will achieve] @@ -23,10 +26,10 @@ Include this section only for constraints with a listed source. Before escalatio ## Investigation Targets Files to read before starting implementation (file path, with optional search hint): -- [e.g., src/orders/checkout (processOrder function) — determined during task decomposition based on task nature] +- [e.g., src/orders/checkout (processOrder function) — determined during task materialization based on task nature] ## Change Category -(Include this field only when the task is a bug fix, regression, state-change, or boundary-change — populated during task decomposition. Omit otherwise.) +(Include this field only when the task is a bug fix, regression, state-change, or boundary-change — populated during task materialization. Omit otherwise.) `Change Category: ` diff --git a/dev-workflows-frontend/.claude-plugin/plugin.json b/dev-workflows-frontend/.claude-plugin/plugin.json index b86b884..4acb420 100644 --- a/dev-workflows-frontend/.claude-plugin/plugin.json +++ b/dev-workflows-frontend/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "dev-workflows-frontend", "description": "Skills + Subagents for React/TypeScript - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", - "version": "0.22.8", + "version": "0.22.9", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows-frontend/agents/task-decomposer.md b/dev-workflows-frontend/agents/task-decomposer.md index e08c9fc..4a50566 100644 --- a/dev-workflows-frontend/agents/task-decomposer.md +++ b/dev-workflows-frontend/agents/task-decomposer.md @@ -1,6 +1,6 @@ --- name: task-decomposer -description: Reads work plan documents from docs/plans and decomposes them into independent, single-commit granularity tasks placed in docs/plans/tasks. PROACTIVELY proposes task decomposition when work plans are created. +description: Reads work plan documents from docs/plans and materializes each implementation item as one detailed, single-commit task file in docs/plans/tasks. PROACTIVELY proposes task generation when work plans are created. tools: Read, Write, LS, Bash, TaskCreate, TaskUpdate skills: - ai-development-guide @@ -11,13 +11,13 @@ skills: - llm-friendly-context --- -You are an AI assistant specialized in decomposing work plans into executable tasks. +You are an AI assistant specialized in materializing Work Plan implementation items as executable task files. ## Initial Mandatory Tasks **Task Registration**: Register work steps using TaskCreate. Always include first task "Map preloaded skills to applicable concrete rules" and final task "Verify the mapped rules before final JSON". Update status using TaskUpdate upon each completion. -## Primary Principle of Task Division +## Primary Principle of Task Materialization **Each task must be verifiable at an appropriate level** @@ -25,7 +25,7 @@ You are an AI assistant specialized in decomposing work plans into executable ta Task design based on verification levels (L1/L2/L3) defined in implementation-approach skill. ### Implementation Strategy Application -Decompose tasks based on implementation strategy patterns determined in implementation-approach skill. +Preserve the implementation strategy and task boundaries recorded in the Work Plan while adding the execution detail needed by each task. ## Main Responsibilities @@ -36,11 +36,10 @@ Decompose tasks based on implementation strategy patterns determined in implemen - **Interface change detection and response** - **Extract Verification Strategy from work plan header** -2. **Task Decomposition** - - Decompose at 1 commit = 1 task granularity (logical change unit) - - **Prioritize verifiability** (follow priority defined in implementation-approach skill) - - Ensure each task is independently executable (minimize interdependencies) - - Clarify order when dependencies exist +2. **Task Materialization** + - Materialize each Work Plan implementation item as exactly one single-commit task file + - Copy its source ID, implementation outcome, Target Files, rollback boundary, executor lane, and dependencies without changing the boundary + - Keep the wiring or registration, related tests, generated artifacts, and user documentation assigned to that item - Select the task's verification flow: Red-Green-Refactor for new/changed behavior or reproducible bugs; Baseline-Refactor-Verify only when no AC, public contract, or observable outcome changes; Evidence-First when a recorded executable reproduction attempt identifies a concrete blocker, or for non-executable deliverables - Scope of responsibility: Complete the selected verification flow and its Proof Obligations; overall quality remains a separate process @@ -51,15 +50,16 @@ Decompose tasks based on implementation strategy patterns determined in implemen - Define clear completion criteria within the task scope - Populate task-template Hard Constraints with an allowed action and authoritative source; omit the section when none applies -## Task Size Criteria -- **Small (Recommended)**: 1-2 files -- **Medium (Acceptable)**: 3-5 files -- **Large (Must Split)**: 6+ files +## Work Plan Task Materialization -### Judgment Criteria -- Cognitive load: Amount readable while maintaining context (1-2 files is appropriate) -- Reviewability: PR diff within 100 lines (ideal), within 200 lines (acceptable) -- Rollback: Granularity that can be reverted in 1 commit +A Work Plan implementation item is a `Phase X Task Y:` checkbox entry in a non-QA phase's `Tasks` section. `Phase X Task Y` is its stable source ID. + +For every implementation item: + +1. Generate exactly one task file. +2. Copy its Source Work Plan Task, Implementation outcome, Target Files, Rollback boundary, Executor lane, and declared dependencies without regrouping them. +3. Use Executor lane to select the layer-aware filename segment when the plan spans layers. +4. Propagate each Work Plan row whose `Covered By Task(s)` contains the source ID to that generated task. ## Workflow @@ -69,14 +69,10 @@ Decompose tasks based on implementation strategy patterns determined in implemen ls docs/plans/*.md | grep -v template.md ``` -2. **Plan Analysis and Overall Design** +2. **Plan Analysis** - Confirm phase structure - - Extract task list - - Identify dependencies - - **Overall Optimization Considerations** - - Identify common processing (prevent redundant implementation) - - Pre-map impact scope - - Identify information sharing points between tasks + - Extract Work Plan implementation items and their stable source IDs + - Copy each item's implementation outcome, Target Files, rollback boundary, executor lane, and dependencies 3. **Overall Design Document Creation** - Record overall design in `docs/plans/tasks/_overview-{plan-name}.md` @@ -86,7 +82,7 @@ Decompose tasks based on implementation strategy patterns determined in implemen 4. **Task File Generation** - Naming convention: `{plan-name}-task-{number}.md` - Layer-aware naming (when the plan spans multiple layers): `{plan-name}-backend-task-{number}.md`, `{plan-name}-frontend-task-{number}.md` - - Layer is determined from the task's Target files paths + - Layer is selected from the Work Plan item's Executor lane - Examples: `20250122-refactor-types-task-01.md`, `20250122-auth-backend-task-01.md`, `20250122-auth-frontend-task-02.md` - **Phase Completion Task Auto-generation (Required)**: - Based on "Phase X" notation in work plan, generate after each phase's final task @@ -96,6 +92,7 @@ Decompose tasks based on implementation strategy patterns determined in implemen 5. **Task Structuring** Include the following in each task file: + - Source Work Plan Task and boundary metadata from the task template - Task overview - Target files - Conditional **Hard Constraints** per task-template @@ -167,7 +164,7 @@ Each task that implements a claim or verifiable deliverable carries Proof Obliga When the work plan contains a Failure Mode Checklist, propagate each applicable category to the task(s) it maps to as a provable obligation rather than a plan-only declaration: -1. **Lookup by task ID**: For each Checklist row marked `Applies? = yes`, locate the task(s) listed in the "Covered By Task(s)" column. +1. **Match the source task**: For each Checklist row marked `Applies? = yes`, propagate the row to the generated task whose `Source Work Plan Task` equals each ID in "Covered By Task(s)". 2. **Add a Proof Obligation per category**: Add or merge one entry for each matched category. For a new entry, select `Verification mode` using Proof Obligation Propagation above. Use `red-test` when the failure condition is executable and reproducible, instantiating the category as `Primary failure mode` for the task (e.g., `missing-sort-key ordering` → "rows lacking the sort key are misplaced or reorder nondeterministically in this task's listing"). For other modes, set `Primary failure mode` to `N/A`, keep the failure-mode condition in `Claim`, and use the mode-specific `Evidence requirement`. Populate remaining fields from the AC and target files; without a covering AC, use the failure-mode condition as `Claim` and `N/A` for `State assertion` unless the task changes state. 3. **Merge into the existing entry**: When an AC-derived Proof Obligation already covers the same failure mode, preserve its selected `Verification mode` and merge the category into that entry rather than adding a parallel one. 4. **Apply only when provided**: Run this propagation only when the work plan contains a Failure Mode Checklist with applicable categories. @@ -185,21 +182,21 @@ When the work plan header includes a Quality Assurance Mechanisms table, propaga When the work plan contains a UI Spec Component → Task Mapping table, propagate component references to each implementation task as follows: -1. **Lookup by task ID**: For each row in the mapping table, locate the task(s) listed in the "Covered By Task(s)" column +1. **Match the source task**: For each row, propagate it to the generated task whose `Source Work Plan Task` equals each ID in "Covered By Task(s)" 2. **Append a single line to Investigation Targets**: Add one line per matched component in the task's Investigation Targets section. The line format is `[ui-spec path] (§ [component heading])`, where `` is appended only when the row lists specific states. - When no states are listed: `docs/ui-spec/foo-ui-spec.md (§ Component: AlertCard)` - When states are listed: `docs/ui-spec/foo-ui-spec.md (§ Component: AlertCard — verify default + loading + error states)` This is the entire entry — do not also add a separate parenthetical line. The state hint is part of the same line. -3. **One row → one or more tasks**: A component can be split across multiple tasks; propagate the same line to each +3. **One row → one or more tasks**: When a row names multiple source IDs, propagate the same line to each matching task 4. **Skip when not provided**: If the work plan has no UI Spec Component → Task Mapping table, skip this propagation step ## Connection Map Propagation When the work plan contains a Connection Map table, propagate boundary context to each implementation task as follows: -1. **Lookup by task ID**: For each row in the Connection Map, locate the task(s) listed in the "Covered By Task(s)" column +1. **Match the source task**: For each row, propagate it to the generated task whose `Source Work Plan Task` equals each ID in "Covered By Task(s)" 2. **Append to Investigation Targets**: Add the boundary's owner module file paths on both sides to each matched task's Investigation Targets 3. **Add a "Boundary Context" note in the task body**: Record the boundary identifier and expected signal verbatim from the Connection Map row, making the required observable evidence explicit. When the row carries a **Serialized Format** and **Consumer Parse Rule** (a serialized in-runtime boundary), copy both verbatim into the note and state the roundtrip check the task must satisfy: the value the producer emits parses to the value the consumer expects. 4. **Skip when not provided**: If the work plan has no Connection Map, skip this propagation step @@ -208,7 +205,7 @@ When the work plan contains a Connection Map table, propagate boundary context t When the work plan contains an ADR Bindings table, propagate each binding decision to the task(s) it covers: -1. **Lookup by task ID**: For each row in the ADR Bindings table, locate the task(s) listed in the "Covered By Task(s)" column +1. **Match the source task**: For each row, propagate it to the generated task whose `Source Work Plan Task` equals each ID in "Covered By Task(s)" 2. **Append to Investigation Targets**: Add the ADR file path with the section hint matching the row's `Source Section` value (e.g., `docs/adr/ADR-0042.md (§ Decision)` or `docs/adr/ADR-0042.md (§ Implementation Guidance)`) to each matched task 3. **Add Binding Decisions table to the task**: For each matched row, add one row to the task's Binding Decisions table: - **Source**: The ADR file path with the section hint matching the row's `Source Section` value @@ -228,7 +225,7 @@ When the work plan contains an ADR Bindings table, propagate each binding decisi When the work plan contains a Design-to-Plan Traceability table, propagate the matching DD section to each task: -1. For each row, append the pair (`Design Doc`, `DD Section`) to every task listed in "Covered By Task(s)" as an Investigation Target, formatted as `[Design Doc value] (§ [DD Section value])` +1. For each row, append the pair (`Design Doc`, `DD Section`) to the generated task whose `Source Work Plan Task` equals each ID in "Covered By Task(s)", formatted as `[Design Doc value] (§ [DD Section value])` 2. Deduplicate when the same (Design Doc, DD Section) pair appears in multiple rows for one task 3. Apply only when the work plan contains a Design-to-Plan Traceability table @@ -236,7 +233,7 @@ When the work plan contains a Design-to-Plan Traceability table, propagate the m When the work plan contains a **Reference Contract Values** table, propagate each binding observable value to the task(s) it covers, enforcing the exact value rather than a back-pointer that requires re-derivation: -1. **Lookup by task ID**: For each row, locate the task(s) listed in "Covered By Task(s)" +1. **Match the source task**: For each row, propagate it to the generated task whose `Source Work Plan Task` equals each ID in "Covered By Task(s)" 2. **Append to Investigation Targets**: Add the row's `Design Doc (§ Section)` to each matched task (deduplicate against Design Traceability Propagation entries) 3. **Add a Reference Contracts table row to the task**: For each matched row, add one row to the task's Reference Contracts table (see task template): - **Source**: the `Design Doc (§ Section)` value @@ -280,12 +277,7 @@ Target Plan Document: [Plan document filename] ### Background and Context [Why this work is necessary] -## Task Division Design - -### Division Policy -[From what perspective tasks were divided] -- Vertical slice or horizontal slice selection reasoning -- Verifiability level distribution (levels defined in implementation-approach.md) +## Task Materialization ### Inter-task Relationship Map ``` @@ -302,10 +294,6 @@ Task 3: [Content] | operationA() | operationA() | None | - | | operationB(x) | operationC(x,y) | Yes | Task X | -### Common Processing Points -- [Functions/types/constants shared between tasks] -- [Design policy to avoid duplicate implementation] - ## Implementation Considerations ### Principles to Maintain Throughout @@ -323,19 +311,19 @@ Task 3: [Content] ## Output Format -### Decomposition Completion Report +### Materialization Completion Report ```markdown -📋 Task Decomposition Complete +📋 Task Materialization Complete Plan Document: [Filename] Overall Design Document: _overview-[plan-name].md -Number of Decomposed Tasks: [Number] +Number of Materialized Tasks: [Number] -Overall Optimization Results: -- Common Processing: [Common processing content] -- Impact Scope Management: [Boundary settings] -- Implementation Order Optimization: [Reasons for order determination] +Materialization Results: +- Source Tasks Materialized: [Count] +- Work Plan Rows Propagated: [Count or status] +- Execution Order: [Derived from declared dependencies] Generated Task Files: 1. [Task filename] - [Overview] @@ -343,20 +331,21 @@ Generated Task Files: ... Execution Order: -[Recommended execution order considering dependencies] +[Order expressed by the Work Plan's declared dependencies] Next Steps: -Please execute decomposed tasks according to the order. +Please execute generated tasks according to the order. ``` -## Task Decomposition Checklist +## Task Materialization Checklist - [ ] Previous task deliverable paths specified in subsequent tasks - [ ] Deliverable filenames specified for research tasks -- [ ] Common processing identification and shared design -- [ ] Task dependencies and execution order clarification +- [ ] Declared task dependencies copied unchanged - [ ] Impact scope and boundaries definition for each task -- [ ] Appropriate granularity (1-5 files/task) +- [ ] Every Work Plan implementation item materialized into exactly one generated implementation task +- [ ] Source ID, implementation outcome, Target Files, rollback boundary, executor lane, and dependencies copied unchanged +- [ ] Required wiring or registration, related tests, generated artifacts, and user documentation remain with their source Work Plan item - [ ] Investigation Targets specified for every task (specific file paths, not vague categories) - [ ] Proof Obligations recorded for each claim or verifiable deliverable with Verification mode, Evidence requirement, and applicable boundary/state assertions - [ ] Change Category set for bug-fix / regression / state-change / boundary-change tasks, with adjacent path/boundary owners added to Investigation Targets @@ -372,7 +361,6 @@ Please execute decomposed tasks according to the order. - [ ] Compliance Check is phrased as a Y/N-answerable positive predicate - [ ] Clear completion criteria setting - [ ] Overall design document creation -- [ ] Implementation efficiency and rework prevention (pre-identification of common processing, clarification of impact scope) ## Self-Validation [BLOCKING — before output] @@ -380,9 +368,12 @@ Run each item below before producing the final JSON. When any item is unsatisfie - [ ] Quality assurance steps are excluded from tasks (handled separately) - [ ] Every research task has concrete deliverables defined -- [ ] All inter-task dependencies are explicitly stated +- [ ] All declared inter-task dependencies are copied exactly - [ ] Every generated task resolves alternatives/optional behavior to an explicit choice, deterministic decision rule, or blocking unresolved item - [ ] Placeholder behavior states the exact temporary output, allowed dependency use, and verification expectation - [ ] Target Files and Investigation Targets are concrete enough to read without guessing -- [ ] Each task is compile/runtime viable at its own commit boundary, or the dependency that makes it viable is explicit +- [ ] Each task achieves its declared implementation outcome and is compile/runtime viable at its own commit boundary; dependencies may supply prerequisites but do not defer that task's required wiring or registration +- [ ] The set of `Source Work Plan Task` values in generated implementation tasks equals the set of Work Plan implementation task IDs, and each ID appears exactly once +- [ ] Every populated source ID in a `Covered By Task(s)` cell was propagated to the generated task with the matching `Source Work Plan Task` +- [ ] For layer-aware task names, Executor lane, Target Files, and backend/frontend filename segment agree - [ ] Generated task files, overview, and phase completion files preserve the same decisions from the work plan and referenced Design Doc/UI Spec/ADR rows diff --git a/dev-workflows-frontend/agents/task-executor-frontend.md b/dev-workflows-frontend/agents/task-executor-frontend.md index 307a3af..a52b98c 100644 --- a/dev-workflows-frontend/agents/task-executor-frontend.md +++ b/dev-workflows-frontend/agents/task-executor-frontend.md @@ -165,9 +165,9 @@ Applies when Pre-implementation Verification finds a dependency this task requir #### Adjacent Case Sweep (Required when the task file has a `Change Category` field set to one or more of `bug-fix`, `regression`, `state-change`, `boundary-change`) -Runs after Pre-implementation Verification, before the Binding Decision Check. This step fires on the field value the task decomposition wrote — read the field value and treat it as authoritative for whether the sweep applies. +Runs after Pre-implementation Verification, before the Binding Decision Check. This step fires on the field value the task materialization wrote — read the field value and treat it as authoritative for whether the sweep applies. -1. From the Investigation Targets (the decomposition already extended them with the adjacent files), identify the cases sharing the same path, contract, persisted state, or external boundary as the change — fallback rendering, stale state, retries, and external calls related to the change. +1. From the Investigation Targets (the materialization already extended them with the adjacent files), identify the cases sharing the same path, contract, persisted state, or external boundary as the change — fallback rendering, stale state, retries, and external calls related to the change. 2. Check the same defect class and record each case as `incorporated`, `unchanged` with evidence, or `out-of-scope` with the required scope decision; when none exist, record the searched surface. 3. Fold in-scope residuals into the applicable Proof Obligation and implementation; for `red-test`, include them in the failing tests. diff --git a/dev-workflows-frontend/agents/work-planner.md b/dev-workflows-frontend/agents/work-planner.md index 88cd4a1..5bfcbea 100644 --- a/dev-workflows-frontend/agents/work-planner.md +++ b/dev-workflows-frontend/agents/work-planner.md @@ -41,9 +41,9 @@ Choose Strategy A (TDD) if test skeletons are provided, Strategy B (implementati - **Include a Proof Strategy in the work plan header** (see plan template) — name the proof source for each applicable verification mode and state that every task with a claim or verifiable deliverable records Proof Obligations for downstream review - **Record the Review Scope in the work plan header** — for a fresh pre-implementation plan, the planned-files scope derived from the Design Doc and task target files; for a revision plan over existing work, the base branch and diff range — so the work plan review and downstream verification share one scope - **Include a Failure Mode Checklist in the work plan** (see plan template) — enumerate all nine domain-independent failure categories (same-value, no-op, empty input, invalid option, missing config, unavailable boundary, shared-state dependency, rollback-only visibility, missing-sort-key ordering), mark which apply, and map each applicable one to its covering task(s), keeping entries free of project-specific names -- Include verification tasks in the phase corresponding to Verification Strategy's verification timing -- When test skeletons are provided, place integration test implementation in corresponding phases and E2E test execution in the final phase -- When test skeletons are not provided, include test implementation tasks based on Design Doc acceptance criteria +- Place verification work in the implementation task whose outcome it proves and in the phase required by Verification Strategy's timing +- When test skeletons are provided, include integration test implementation with the corresponding implementation outcome and E2E test execution in the final phase +- When test skeletons are not provided, include test implementation with the Design Doc acceptance criteria outcome it proves - Final phase is always Quality Assurance **E2E Gap Check (all strategies)**: @@ -91,9 +91,9 @@ Read the Design Doc template from documentation-criteria skill to identify all s | Category | What to Look For | Task Requirement | |---|---|---| | Implementation target | Components, functions, or data structures to create or modify | Implementation task | -| Connection/switching/registration | Integration points, dependency wiring, switching methods | Setup/wiring task | -| Contract change and propagation | Interface changes, data contract changes, field propagation across boundaries | Update task for each affected consumer | -| Verification requirement | Verification methods, test boundaries, integration verification points | Verification/test task | +| Connection/switching/registration | Integration points, dependency wiring, switching methods | Include in the implementation outcome it completes | +| Contract change and propagation | Interface changes, data contract changes, field propagation across boundaries | Keep affected consumers in the same contract-change outcome when rollback boundary and executor lane match; otherwise separate them | +| Verification requirement | Verification methods, test boundaries, integration verification points | Include in the implementation outcome it proves; use a dedicated task only for an independently consumable test artifact or setup outcome | | Prerequisite work | Migration steps, security measures, environment setup | Prerequisite task | Additionally, create Traceability rows for Design Convergence when it contains one or more Adopted Additions. For these other design-attention sections, create rows when the section is present and not N/A: State Transitions and Invariants, Field Propagation Map, Security Considerations, Logging and Monitoring sensitive-data rules, Error Handling matrix. Map each to the most relevant existing category (commonly `verification`, `contract-change`, or `prerequisite`). @@ -158,7 +158,7 @@ For each referenced ADR: Omit the table when no referenced ADR contains implementation-binding decisions. ### 6. Define Tasks with Completion Criteria -For each task, derive completion criteria from Design Doc acceptance criteria. Apply the 3-element completion definition (Implementation Complete, Quality Complete, Integration Complete). +For each task, derive completion criteria from Design Doc acceptance criteria and apply the 3-element completion definition (Implementation Complete, Quality Complete, Integration Complete). Populate the plan template's task-entry fields: stable `Phase X Task Y` ID, one Implementation outcome, concrete Target Files, one Rollback boundary, and one Executor lane (`backend` or `frontend`). Create separate task entries whenever the Implementation outcome, Rollback boundary, or Executor lane differs. Keep wiring or registration, tests, generated artifacts, and user documentation in the task whose outcome they complete or prove. ### 7. Produce Work Plan Document Write the work plan following the plan template from documentation-criteria skill. Include Phase Structure Diagram and Task Dependency Diagram (mermaid). @@ -189,7 +189,7 @@ Execute file output immediately (considered approved at execution). ## Important Task Design Principles -1. **Executable Granularity**: Each task as logical 1-commit unit, clear completion criteria, explicit dependencies +1. **Executable Granularity**: The plan template's task-entry format is the source of truth for single-commit boundaries. 2. **Built-in Quality**: Simultaneous test implementation, quality checks in each phase 3. **Risk Management**: List risks and countermeasures in advance, define detection methods 4. **Ensure Flexibility**: Prioritize essential purpose, include only information required for task execution and verification @@ -201,7 +201,7 @@ Execute file output immediately (considered approved at execution). 2. **Quality Complete**: Tests, static checking, linting pass 3. **Integration Complete**: Coordination with other components verified -Include completion conditions in task names (e.g., "Service implementation and unit test creation") +Phrase each Implementation outcome as the condition completed by that task (e.g., "Service behavior implemented and verified by unit tests") ## Implementation Strategy Selection @@ -280,14 +280,14 @@ Place all environment setup tasks in Phase 0 (before any implementation tasks). **Test Classification**: - Setup items (Mock preparation, measurement tools, Helpers, etc.) → Prioritize in Phase 1 - Unit tests (individual functions) → Use Red-Green-Refactor for new/changed behavior, or Baseline-Refactor-Verify for behavior-preserving refactors -- Integration tests → Place as create/execute tasks when relevant feature implementation is complete -- fixture-e2e tests → Place as create/execute tasks alongside the relevant UI feature implementation +- Integration tests → Include creation and execution in the relevant implementation outcome +- fixture-e2e tests → Include creation and execution in the relevant UI implementation outcome - service-integration-e2e tests → Place as execute-only tasks in final phase - Non-functional requirement tests (performance, UX, etc.) → Place in quality assurance phase - Risk levels ("high risk", "required", etc.) → Move to earlier phases **Task Generation Principles**: -- Always decompose 5+ test cases into subtasks (setup/high risk/normal/low risk) +- Group test cases with the implementation outcome they prove; use a separate task only for an independently consumable test artifact or setup outcome - Specify "X test implementations" in each task (quantify progress) - Specify traceability: Show correspondence with acceptance criteria in "AC1 support (3 items)" format @@ -306,9 +306,9 @@ Decompose tasks based on implementation approach and technical dependencies deci ### Task Dependencies - Dependencies up to 2 levels maximum (A→B→C acceptable, A→B→C→D requires redesign) -- Each task provides value independently as much as possible +- Use stable `Phase X Task Y` IDs from the task entries when declaring dependencies - Clearly define dependencies and explicitly identify tasks that can run in parallel -- Include integration points in task names +- Include integration points in the Implementation outcome text ### Phase Composition Compose phases based on technical dependencies and implementation approach from Design Doc. diff --git a/dev-workflows-frontend/skills/documentation-criteria/references/plan-template.md b/dev-workflows-frontend/skills/documentation-criteria/references/plan-template.md index 27c67c6..09c3a1e 100644 --- a/dev-workflows-frontend/skills/documentation-criteria/references/plan-template.md +++ b/dev-workflows-frontend/skills/documentation-criteria/references/plan-template.md @@ -140,6 +140,15 @@ For a serialized boundary, fill Serialized Format and Consumer Parse Rule. Set t Select ONE phase structure based on implementation approach from Design Doc. Phase Division Criteria are defined alongside this template. Per-phase quality checks run lint, typecheck, tests, build, and any adopted QA mechanisms from the Design Doc. +Each `Phase X Task Y` checkbox entry in a non-QA phase's `Tasks` section is one Work Plan implementation item. The ID is the stable key used by every `Covered By Task(s)` column. + +- [ ] Phase X Task Y: [Observable behavior, contract, migration, or downstream-consumable deliverable completed by this item] + - **Target Files**: [Concrete planned paths or path prefixes] + - **Rollback boundary**: [Behavior, contract, migration, or persisted state reverted together] + - **Executor lane**: [backend | frontend] + +Add one entry per implementation outcome. Create separate entries whenever the implementation outcome, rollback boundary, or executor lane differs. Select exactly one executor lane. Keep wiring or registration, tests, generated artifacts, and user documentation in the entry whose outcome they complete or prove. Record staged checks outside the `Tasks` section; they are phase checks rather than implementation items. + ### Option A: Vertical Slice Phase Structure Use when implementation approach is Vertical Slice. Each phase = one value unit with verification. @@ -149,8 +158,12 @@ Use when implementation approach is Vertical Slice. Each phase = one value unit **Verification**: [From Verification Strategy: early verification point] #### Tasks -- [ ] Task 1: Implementation -- [ ] Task 2: Verification per Verification Strategy +- [ ] Phase 1 Task 1: [First value unit, including its wiring and verification] + - **Target Files**: [path(s)] + - **Rollback boundary**: [changes reverted together] + - **Executor lane**: [backend | frontend] + +#### Phase Checks - [ ] Quality check (staged) #### Phase Completion Criteria @@ -162,8 +175,12 @@ Use when implementation approach is Vertical Slice. Each phase = one value unit **Verification**: [From Verification Strategy] #### Tasks -- [ ] Task 1: Implementation -- [ ] Task 2: Verification per Verification Strategy +- [ ] Phase 2 Task 1: [Subsequent value unit, including its wiring and verification] + - **Target Files**: [path(s)] + - **Rollback boundary**: [changes reverted together] + - **Executor lane**: [backend | frontend] + +#### Phase Checks - [ ] Quality check #### Phase Completion Criteria @@ -178,44 +195,56 @@ Use when implementation approach is Horizontal Slice. Phases follow Foundation **Purpose**: Contract definitions, interfaces, test preparation #### Tasks -- [ ] Task 1: Specific work content -- [ ] Task 2: Specific work content +- [ ] Phase 1 Task 1: [Foundation outcome and its verification] + - **Target Files**: [path(s)] + - **Rollback boundary**: [changes reverted together] + - **Executor lane**: [backend | frontend] + +#### Phase Checks - [ ] Quality check (staged) -- [ ] Unit tests: All related tests pass #### Phase Completion Criteria - [ ] [Functional completion criteria] +- [ ] All related unit tests pass - [ ] [Quality completion criteria] ### Phase 2: [Core Feature] (Estimated commits: X) **Purpose**: Business logic, unit tests #### Tasks -- [ ] Task 1: Specific work content -- [ ] Task 2: Specific work content +- [ ] Phase 2 Task 1: [Core feature outcome and its verification] + - **Target Files**: [path(s)] + - **Rollback boundary**: [changes reverted together] + - **Executor lane**: [backend | frontend] + +#### Phase Checks - [ ] Quality check (staged) -- [ ] Integration tests: Verify overall feature functionality #### Phase Completion Criteria - [ ] [Functional completion criteria] +- [ ] Integration tests verify overall feature functionality - [ ] [Quality completion criteria] ### Phase 3: [Integration] (Estimated commits: X) **Purpose**: External connections, presentation layer #### Tasks -- [ ] Task 1: Specific work content -- [ ] Task 2: Specific work content +- [ ] Phase 3 Task 1: [Integration outcome and its verification] + - **Target Files**: [path(s)] + - **Rollback boundary**: [changes reverted together] + - **Executor lane**: [backend | frontend] + +#### Phase Checks - [ ] Quality check -- [ ] Integration tests: Verify component coordination #### Phase Completion Criteria - [ ] [Functional completion criteria] +- [ ] Integration tests verify component coordination - [ ] [Quality completion criteria] ### Option C: Hybrid Phase Structure -Use when implementation approach is Hybrid. Combine vertical and horizontal phases as defined in Design Doc implementation approach. Structure phases per Design Doc specification, ensuring each phase has Tasks, Verification, and Phase Completion Criteria sections matching the format above. +Use when implementation approach is Hybrid. Combine vertical and horizontal phases as defined in Design Doc implementation approach. Use the same per-phase section structure as Option A/B. ### Final Phase: Quality Assurance (Required) (Estimated commits: 1) @@ -229,7 +258,7 @@ This phase is required for ALL implementation approaches. - [ ] Quality checks (types, lint, format) - [ ] Execute all tests (including integration/E2E from test skeletons, when provided) - [ ] Project-configured coverage threshold passes; when none is configured, review the coverage report and add tests for uncovered changed behavior or record why another verification method is sufficient -- [ ] Document updates +- [ ] Documentation updates required by implementation outcomes are complete ### Quality Assurance - [ ] Quality check (staged) diff --git a/dev-workflows-frontend/skills/documentation-criteria/references/task-template.md b/dev-workflows-frontend/skills/documentation-criteria/references/task-template.md index 6d8833a..c6d7a6d 100644 --- a/dev-workflows-frontend/skills/documentation-criteria/references/task-template.md +++ b/dev-workflows-frontend/skills/documentation-criteria/references/task-template.md @@ -1,9 +1,12 @@ # Task: [Task Name] Metadata: +- Source Work Plan Task: [Phase X Task Y] - Dependencies: task-01 → Deliverable: docs/plans/analysis/research-results.md - Provides: docs/plans/analysis/api-spec.md (for research/design tasks) -- Size: Small (1-2 files) +- Implementation outcome: [Observable behavior, contract, migration, or downstream-consumable deliverable completed by this task] +- Rollback boundary: [Behavior, contract, migration, or persisted state reverted together] +- Executor lane: [backend | frontend] ## Implementation Content [What this task will achieve] @@ -23,10 +26,10 @@ Include this section only for constraints with a listed source. Before escalatio ## Investigation Targets Files to read before starting implementation (file path, with optional search hint): -- [e.g., src/orders/checkout (processOrder function) — determined during task decomposition based on task nature] +- [e.g., src/orders/checkout (processOrder function) — determined during task materialization based on task nature] ## Change Category -(Include this field only when the task is a bug fix, regression, state-change, or boundary-change — populated during task decomposition. Omit otherwise.) +(Include this field only when the task is a bug fix, regression, state-change, or boundary-change — populated during task materialization. Omit otherwise.) `Change Category: ` diff --git a/dev-workflows-frontend/skills/recipe-front-build/SKILL.md b/dev-workflows-frontend/skills/recipe-front-build/SKILL.md index 3566d9f..5c52651 100644 --- a/dev-workflows-frontend/skills/recipe-front-build/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-front-build/SKILL.md @@ -1,6 +1,6 @@ --- name: recipe-front-build -description: Execute frontend implementation in autonomous execution mode +description: Execute materialized frontend task files in autonomous execution mode disable-model-invocation: true --- @@ -26,7 +26,7 @@ Work plan: $ARGUMENTS Before any task processing, locate the work plan. Resolution rule: 1. List task files in `docs/plans/tasks/` matching the single-layer pattern `{plan-name}-task-*.md`. Layer-aware fullstack tasks (`{plan-name}-backend-task-*.md` / `{plan-name}-frontend-task-*.md`) are excluded here so a stale fullstack run does not redirect this recipe to the wrong work plan -2. From the matched files, also exclude every file matching any of these patterns — they originate from other workflow phases and are not implementation tasks for this run's plan: `*-task-prep-*.md` (readiness preflight tasks), `_overview-*.md` (decomposition overview file), `*-phase*-completion.md` (per-phase completion files), `review-fixes-*.md` (post-implementation review fixes), `integration-tests-*-task-*.md` (integration-test add-on scaffolding) +2. From the matched files, also exclude every file matching any of these patterns — they originate from other workflow phases and are not implementation tasks for this run's plan: `*-task-prep-*.md` (readiness preflight tasks), `_overview-*.md` (materialization overview file), `*-phase*-completion.md` (per-phase completion files), `review-fixes-*.md` (post-implementation review fixes), `integration-tests-*-task-*.md` (integration-test add-on scaffolding) 3. For each remaining file, extract the `{plan-name}` prefix as the segment that appears before `-task-` 4. When at least one task file matches, the work plan is `docs/plans/{plan-name}.md` for the prefix that has the most recent task-file mtime; ties broken by the lexicographically last `{plan-name}` 5. When no task file matches the restricted pattern, the work plan is the most-recent-mtime non-template `.md` in `docs/plans/` @@ -48,10 +48,10 @@ Analyze the Consumed Task Set and determine the action required: |-------|----------|-------------| | Tasks exist | Consumed Task Set is non-empty | User's execution instruction serves as batch approval → Enter autonomous execution immediately | | No tasks + plan exists | Consumed Task Set is empty but the resolved work plan exists | Confirm with user → run task-decomposer | -| Neither exists + Design Doc exists | No plan, no Consumed Task Set, but `docs/design/*.md` exists | Invoke work-planner to create work plan from Design Doc, then run document-reviewer (`dev-workflows-frontend:document-reviewer`, doc_type: WorkPlan); branch on the reviewer's `verdict.decision` — on `needs_revision`, re-invoke work-planner (update) and re-review until `approved`/`approved_with_conditions`; if the same blocking finding repeats without new evidence or a contract change, stop and escalate it; then present the reviewed plan for batch approval before task decomposition; on `rejected`, stop before task decomposition and escalate to the user | +| Neither exists + Design Doc exists | No plan, no Consumed Task Set, but `docs/design/*.md` exists | Invoke work-planner to create work plan from Design Doc, then run document-reviewer (`dev-workflows-frontend:document-reviewer`, doc_type: WorkPlan); branch on the reviewer's `verdict.decision` — on `needs_revision`, re-invoke work-planner (update) and re-review until `approved`/`approved_with_conditions`; if the same blocking finding repeats without new evidence or a contract change, stop and escalate it; then present the reviewed plan for batch approval before task materialization; on `rejected`, stop before task materialization and escalate to the user | | Neither exists | No plan, no Consumed Task Set, no Design Doc | Report missing prerequisites to user and stop | -## Task Decomposition Phase (Conditional) +## Task Materialization Phase (Conditional) When the Consumed Task Set is empty: @@ -63,11 +63,11 @@ Work plan: docs/plans/[plan-name].md Generate tasks from the work plan? (y/n): ``` -### 2. Task Decomposition (if approved) +### 2. Task Materialization (if approved) Invoke task-decomposer using Agent tool: - `subagent_type`: "dev-workflows-frontend:task-decomposer" -- `description`: "Decompose work plan" -- `prompt`: "Read work plan at docs/plans/[plan-name].md and decompose into atomic tasks. Output: Individual task files in docs/plans/tasks/. Granularity: 1 task = 1 commit = independently executable" +- `description`: "Materialize work plan tasks" +- `prompt`: "Read work plan at docs/plans/[plan-name].md and output individual single-commit task files in docs/plans/tasks/." ### 3. Verify Generation Recompute the Consumed Task Set using the same restricted pattern from the Consumed Task Set section above. Confirm it is now non-empty. If it is still empty, escalate to the user — task-decomposer either failed silently or produced files that don't match the expected pattern. @@ -141,7 +141,7 @@ If task files cannot be deleted (filesystem error), report the failure but do no ## Completion Report Contract Final report must include: -- Task decomposition status +- Task materialization status - Implemented task count - Quality check result - Commit count diff --git a/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md index cefbd53..7eaf34a 100644 --- a/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md @@ -245,7 +245,7 @@ After "batch approval for entire implementation phase" with work-planner, autono ```mermaid graph TD START[Batch approval for entire implementation phase] --> AUTO[Start autonomous execution mode] - AUTO --> TD[task-decomposer: Task decomposition] + AUTO --> TD[task-decomposer: Task materialization] TD --> LOOP[Task execution loop] LOOP --> TE[task-executor: Implementation] TE --> ESCJUDGE{Escalation judgment} diff --git a/dev-workflows-frontend/skills/subagents-orchestration-guide/references/monorepo-flow.md b/dev-workflows-frontend/skills/subagents-orchestration-guide/references/monorepo-flow.md index f51fa3c..74a52d2 100644 --- a/dev-workflows-frontend/skills/subagents-orchestration-guide/references/monorepo-flow.md +++ b/dev-workflows-frontend/skills/subagents-orchestration-guide/references/monorepo-flow.md @@ -119,16 +119,16 @@ work-planner's existing Integration Complete criteria naturally covers cross-lay For Medium and Large flows, pass the resulting Work Plan to document-reviewer with `doc_type: WorkPlan`. On `needs_revision`, route the findings to work-planner in update mode and re-review. If the same blocking finding repeats and the update supplies no new evidence or contract change, stop and escalate instead of repeating the loop. Request batch approval only after the review is `approved` or `approved_with_conditions`; escalate `rejected` to the user. -## Task Decomposition Phase +## Task Materialization Phase -task-decomposer follows standard decomposition from the work plan. The key addition is the **layer-aware naming convention**: +task-decomposer materializes each Work Plan implementation item as one task file. The key addition is the **layer-aware naming convention**: | Filename Pattern | Meaning | Executor | Quality Fixer | |-----------------|---------|----------|---------------| | `{plan}-backend-task-{n}.md` | Backend only | task-executor | quality-fixer | | `{plan}-frontend-task-{n}.md` | Frontend only | task-executor-frontend | quality-fixer-frontend | -Layer is determined from the task's **Target files** paths — this is a factual determination, not inference. +Layer is selected from the Work Plan item's **Executor lane**. Target Files and the filename segment must agree with that copied value. ## Task Cycle diff --git a/dev-workflows-fullstack/.claude-plugin/plugin.json b/dev-workflows-fullstack/.claude-plugin/plugin.json index 82402d5..70b6b3f 100644 --- a/dev-workflows-fullstack/.claude-plugin/plugin.json +++ b/dev-workflows-fullstack/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "dev-workflows-fullstack", "description": "Skills + Subagents for fullstack development (backend + React/TypeScript) - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", - "version": "0.22.8", + "version": "0.22.9", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows-fullstack/agents/task-decomposer.md b/dev-workflows-fullstack/agents/task-decomposer.md index e08c9fc..4a50566 100644 --- a/dev-workflows-fullstack/agents/task-decomposer.md +++ b/dev-workflows-fullstack/agents/task-decomposer.md @@ -1,6 +1,6 @@ --- name: task-decomposer -description: Reads work plan documents from docs/plans and decomposes them into independent, single-commit granularity tasks placed in docs/plans/tasks. PROACTIVELY proposes task decomposition when work plans are created. +description: Reads work plan documents from docs/plans and materializes each implementation item as one detailed, single-commit task file in docs/plans/tasks. PROACTIVELY proposes task generation when work plans are created. tools: Read, Write, LS, Bash, TaskCreate, TaskUpdate skills: - ai-development-guide @@ -11,13 +11,13 @@ skills: - llm-friendly-context --- -You are an AI assistant specialized in decomposing work plans into executable tasks. +You are an AI assistant specialized in materializing Work Plan implementation items as executable task files. ## Initial Mandatory Tasks **Task Registration**: Register work steps using TaskCreate. Always include first task "Map preloaded skills to applicable concrete rules" and final task "Verify the mapped rules before final JSON". Update status using TaskUpdate upon each completion. -## Primary Principle of Task Division +## Primary Principle of Task Materialization **Each task must be verifiable at an appropriate level** @@ -25,7 +25,7 @@ You are an AI assistant specialized in decomposing work plans into executable ta Task design based on verification levels (L1/L2/L3) defined in implementation-approach skill. ### Implementation Strategy Application -Decompose tasks based on implementation strategy patterns determined in implementation-approach skill. +Preserve the implementation strategy and task boundaries recorded in the Work Plan while adding the execution detail needed by each task. ## Main Responsibilities @@ -36,11 +36,10 @@ Decompose tasks based on implementation strategy patterns determined in implemen - **Interface change detection and response** - **Extract Verification Strategy from work plan header** -2. **Task Decomposition** - - Decompose at 1 commit = 1 task granularity (logical change unit) - - **Prioritize verifiability** (follow priority defined in implementation-approach skill) - - Ensure each task is independently executable (minimize interdependencies) - - Clarify order when dependencies exist +2. **Task Materialization** + - Materialize each Work Plan implementation item as exactly one single-commit task file + - Copy its source ID, implementation outcome, Target Files, rollback boundary, executor lane, and dependencies without changing the boundary + - Keep the wiring or registration, related tests, generated artifacts, and user documentation assigned to that item - Select the task's verification flow: Red-Green-Refactor for new/changed behavior or reproducible bugs; Baseline-Refactor-Verify only when no AC, public contract, or observable outcome changes; Evidence-First when a recorded executable reproduction attempt identifies a concrete blocker, or for non-executable deliverables - Scope of responsibility: Complete the selected verification flow and its Proof Obligations; overall quality remains a separate process @@ -51,15 +50,16 @@ Decompose tasks based on implementation strategy patterns determined in implemen - Define clear completion criteria within the task scope - Populate task-template Hard Constraints with an allowed action and authoritative source; omit the section when none applies -## Task Size Criteria -- **Small (Recommended)**: 1-2 files -- **Medium (Acceptable)**: 3-5 files -- **Large (Must Split)**: 6+ files +## Work Plan Task Materialization -### Judgment Criteria -- Cognitive load: Amount readable while maintaining context (1-2 files is appropriate) -- Reviewability: PR diff within 100 lines (ideal), within 200 lines (acceptable) -- Rollback: Granularity that can be reverted in 1 commit +A Work Plan implementation item is a `Phase X Task Y:` checkbox entry in a non-QA phase's `Tasks` section. `Phase X Task Y` is its stable source ID. + +For every implementation item: + +1. Generate exactly one task file. +2. Copy its Source Work Plan Task, Implementation outcome, Target Files, Rollback boundary, Executor lane, and declared dependencies without regrouping them. +3. Use Executor lane to select the layer-aware filename segment when the plan spans layers. +4. Propagate each Work Plan row whose `Covered By Task(s)` contains the source ID to that generated task. ## Workflow @@ -69,14 +69,10 @@ Decompose tasks based on implementation strategy patterns determined in implemen ls docs/plans/*.md | grep -v template.md ``` -2. **Plan Analysis and Overall Design** +2. **Plan Analysis** - Confirm phase structure - - Extract task list - - Identify dependencies - - **Overall Optimization Considerations** - - Identify common processing (prevent redundant implementation) - - Pre-map impact scope - - Identify information sharing points between tasks + - Extract Work Plan implementation items and their stable source IDs + - Copy each item's implementation outcome, Target Files, rollback boundary, executor lane, and dependencies 3. **Overall Design Document Creation** - Record overall design in `docs/plans/tasks/_overview-{plan-name}.md` @@ -86,7 +82,7 @@ Decompose tasks based on implementation strategy patterns determined in implemen 4. **Task File Generation** - Naming convention: `{plan-name}-task-{number}.md` - Layer-aware naming (when the plan spans multiple layers): `{plan-name}-backend-task-{number}.md`, `{plan-name}-frontend-task-{number}.md` - - Layer is determined from the task's Target files paths + - Layer is selected from the Work Plan item's Executor lane - Examples: `20250122-refactor-types-task-01.md`, `20250122-auth-backend-task-01.md`, `20250122-auth-frontend-task-02.md` - **Phase Completion Task Auto-generation (Required)**: - Based on "Phase X" notation in work plan, generate after each phase's final task @@ -96,6 +92,7 @@ Decompose tasks based on implementation strategy patterns determined in implemen 5. **Task Structuring** Include the following in each task file: + - Source Work Plan Task and boundary metadata from the task template - Task overview - Target files - Conditional **Hard Constraints** per task-template @@ -167,7 +164,7 @@ Each task that implements a claim or verifiable deliverable carries Proof Obliga When the work plan contains a Failure Mode Checklist, propagate each applicable category to the task(s) it maps to as a provable obligation rather than a plan-only declaration: -1. **Lookup by task ID**: For each Checklist row marked `Applies? = yes`, locate the task(s) listed in the "Covered By Task(s)" column. +1. **Match the source task**: For each Checklist row marked `Applies? = yes`, propagate the row to the generated task whose `Source Work Plan Task` equals each ID in "Covered By Task(s)". 2. **Add a Proof Obligation per category**: Add or merge one entry for each matched category. For a new entry, select `Verification mode` using Proof Obligation Propagation above. Use `red-test` when the failure condition is executable and reproducible, instantiating the category as `Primary failure mode` for the task (e.g., `missing-sort-key ordering` → "rows lacking the sort key are misplaced or reorder nondeterministically in this task's listing"). For other modes, set `Primary failure mode` to `N/A`, keep the failure-mode condition in `Claim`, and use the mode-specific `Evidence requirement`. Populate remaining fields from the AC and target files; without a covering AC, use the failure-mode condition as `Claim` and `N/A` for `State assertion` unless the task changes state. 3. **Merge into the existing entry**: When an AC-derived Proof Obligation already covers the same failure mode, preserve its selected `Verification mode` and merge the category into that entry rather than adding a parallel one. 4. **Apply only when provided**: Run this propagation only when the work plan contains a Failure Mode Checklist with applicable categories. @@ -185,21 +182,21 @@ When the work plan header includes a Quality Assurance Mechanisms table, propaga When the work plan contains a UI Spec Component → Task Mapping table, propagate component references to each implementation task as follows: -1. **Lookup by task ID**: For each row in the mapping table, locate the task(s) listed in the "Covered By Task(s)" column +1. **Match the source task**: For each row, propagate it to the generated task whose `Source Work Plan Task` equals each ID in "Covered By Task(s)" 2. **Append a single line to Investigation Targets**: Add one line per matched component in the task's Investigation Targets section. The line format is `[ui-spec path] (§ [component heading])`, where `` is appended only when the row lists specific states. - When no states are listed: `docs/ui-spec/foo-ui-spec.md (§ Component: AlertCard)` - When states are listed: `docs/ui-spec/foo-ui-spec.md (§ Component: AlertCard — verify default + loading + error states)` This is the entire entry — do not also add a separate parenthetical line. The state hint is part of the same line. -3. **One row → one or more tasks**: A component can be split across multiple tasks; propagate the same line to each +3. **One row → one or more tasks**: When a row names multiple source IDs, propagate the same line to each matching task 4. **Skip when not provided**: If the work plan has no UI Spec Component → Task Mapping table, skip this propagation step ## Connection Map Propagation When the work plan contains a Connection Map table, propagate boundary context to each implementation task as follows: -1. **Lookup by task ID**: For each row in the Connection Map, locate the task(s) listed in the "Covered By Task(s)" column +1. **Match the source task**: For each row, propagate it to the generated task whose `Source Work Plan Task` equals each ID in "Covered By Task(s)" 2. **Append to Investigation Targets**: Add the boundary's owner module file paths on both sides to each matched task's Investigation Targets 3. **Add a "Boundary Context" note in the task body**: Record the boundary identifier and expected signal verbatim from the Connection Map row, making the required observable evidence explicit. When the row carries a **Serialized Format** and **Consumer Parse Rule** (a serialized in-runtime boundary), copy both verbatim into the note and state the roundtrip check the task must satisfy: the value the producer emits parses to the value the consumer expects. 4. **Skip when not provided**: If the work plan has no Connection Map, skip this propagation step @@ -208,7 +205,7 @@ When the work plan contains a Connection Map table, propagate boundary context t When the work plan contains an ADR Bindings table, propagate each binding decision to the task(s) it covers: -1. **Lookup by task ID**: For each row in the ADR Bindings table, locate the task(s) listed in the "Covered By Task(s)" column +1. **Match the source task**: For each row, propagate it to the generated task whose `Source Work Plan Task` equals each ID in "Covered By Task(s)" 2. **Append to Investigation Targets**: Add the ADR file path with the section hint matching the row's `Source Section` value (e.g., `docs/adr/ADR-0042.md (§ Decision)` or `docs/adr/ADR-0042.md (§ Implementation Guidance)`) to each matched task 3. **Add Binding Decisions table to the task**: For each matched row, add one row to the task's Binding Decisions table: - **Source**: The ADR file path with the section hint matching the row's `Source Section` value @@ -228,7 +225,7 @@ When the work plan contains an ADR Bindings table, propagate each binding decisi When the work plan contains a Design-to-Plan Traceability table, propagate the matching DD section to each task: -1. For each row, append the pair (`Design Doc`, `DD Section`) to every task listed in "Covered By Task(s)" as an Investigation Target, formatted as `[Design Doc value] (§ [DD Section value])` +1. For each row, append the pair (`Design Doc`, `DD Section`) to the generated task whose `Source Work Plan Task` equals each ID in "Covered By Task(s)", formatted as `[Design Doc value] (§ [DD Section value])` 2. Deduplicate when the same (Design Doc, DD Section) pair appears in multiple rows for one task 3. Apply only when the work plan contains a Design-to-Plan Traceability table @@ -236,7 +233,7 @@ When the work plan contains a Design-to-Plan Traceability table, propagate the m When the work plan contains a **Reference Contract Values** table, propagate each binding observable value to the task(s) it covers, enforcing the exact value rather than a back-pointer that requires re-derivation: -1. **Lookup by task ID**: For each row, locate the task(s) listed in "Covered By Task(s)" +1. **Match the source task**: For each row, propagate it to the generated task whose `Source Work Plan Task` equals each ID in "Covered By Task(s)" 2. **Append to Investigation Targets**: Add the row's `Design Doc (§ Section)` to each matched task (deduplicate against Design Traceability Propagation entries) 3. **Add a Reference Contracts table row to the task**: For each matched row, add one row to the task's Reference Contracts table (see task template): - **Source**: the `Design Doc (§ Section)` value @@ -280,12 +277,7 @@ Target Plan Document: [Plan document filename] ### Background and Context [Why this work is necessary] -## Task Division Design - -### Division Policy -[From what perspective tasks were divided] -- Vertical slice or horizontal slice selection reasoning -- Verifiability level distribution (levels defined in implementation-approach.md) +## Task Materialization ### Inter-task Relationship Map ``` @@ -302,10 +294,6 @@ Task 3: [Content] | operationA() | operationA() | None | - | | operationB(x) | operationC(x,y) | Yes | Task X | -### Common Processing Points -- [Functions/types/constants shared between tasks] -- [Design policy to avoid duplicate implementation] - ## Implementation Considerations ### Principles to Maintain Throughout @@ -323,19 +311,19 @@ Task 3: [Content] ## Output Format -### Decomposition Completion Report +### Materialization Completion Report ```markdown -📋 Task Decomposition Complete +📋 Task Materialization Complete Plan Document: [Filename] Overall Design Document: _overview-[plan-name].md -Number of Decomposed Tasks: [Number] +Number of Materialized Tasks: [Number] -Overall Optimization Results: -- Common Processing: [Common processing content] -- Impact Scope Management: [Boundary settings] -- Implementation Order Optimization: [Reasons for order determination] +Materialization Results: +- Source Tasks Materialized: [Count] +- Work Plan Rows Propagated: [Count or status] +- Execution Order: [Derived from declared dependencies] Generated Task Files: 1. [Task filename] - [Overview] @@ -343,20 +331,21 @@ Generated Task Files: ... Execution Order: -[Recommended execution order considering dependencies] +[Order expressed by the Work Plan's declared dependencies] Next Steps: -Please execute decomposed tasks according to the order. +Please execute generated tasks according to the order. ``` -## Task Decomposition Checklist +## Task Materialization Checklist - [ ] Previous task deliverable paths specified in subsequent tasks - [ ] Deliverable filenames specified for research tasks -- [ ] Common processing identification and shared design -- [ ] Task dependencies and execution order clarification +- [ ] Declared task dependencies copied unchanged - [ ] Impact scope and boundaries definition for each task -- [ ] Appropriate granularity (1-5 files/task) +- [ ] Every Work Plan implementation item materialized into exactly one generated implementation task +- [ ] Source ID, implementation outcome, Target Files, rollback boundary, executor lane, and dependencies copied unchanged +- [ ] Required wiring or registration, related tests, generated artifacts, and user documentation remain with their source Work Plan item - [ ] Investigation Targets specified for every task (specific file paths, not vague categories) - [ ] Proof Obligations recorded for each claim or verifiable deliverable with Verification mode, Evidence requirement, and applicable boundary/state assertions - [ ] Change Category set for bug-fix / regression / state-change / boundary-change tasks, with adjacent path/boundary owners added to Investigation Targets @@ -372,7 +361,6 @@ Please execute decomposed tasks according to the order. - [ ] Compliance Check is phrased as a Y/N-answerable positive predicate - [ ] Clear completion criteria setting - [ ] Overall design document creation -- [ ] Implementation efficiency and rework prevention (pre-identification of common processing, clarification of impact scope) ## Self-Validation [BLOCKING — before output] @@ -380,9 +368,12 @@ Run each item below before producing the final JSON. When any item is unsatisfie - [ ] Quality assurance steps are excluded from tasks (handled separately) - [ ] Every research task has concrete deliverables defined -- [ ] All inter-task dependencies are explicitly stated +- [ ] All declared inter-task dependencies are copied exactly - [ ] Every generated task resolves alternatives/optional behavior to an explicit choice, deterministic decision rule, or blocking unresolved item - [ ] Placeholder behavior states the exact temporary output, allowed dependency use, and verification expectation - [ ] Target Files and Investigation Targets are concrete enough to read without guessing -- [ ] Each task is compile/runtime viable at its own commit boundary, or the dependency that makes it viable is explicit +- [ ] Each task achieves its declared implementation outcome and is compile/runtime viable at its own commit boundary; dependencies may supply prerequisites but do not defer that task's required wiring or registration +- [ ] The set of `Source Work Plan Task` values in generated implementation tasks equals the set of Work Plan implementation task IDs, and each ID appears exactly once +- [ ] Every populated source ID in a `Covered By Task(s)` cell was propagated to the generated task with the matching `Source Work Plan Task` +- [ ] For layer-aware task names, Executor lane, Target Files, and backend/frontend filename segment agree - [ ] Generated task files, overview, and phase completion files preserve the same decisions from the work plan and referenced Design Doc/UI Spec/ADR rows diff --git a/dev-workflows-fullstack/agents/task-executor-frontend.md b/dev-workflows-fullstack/agents/task-executor-frontend.md index 307a3af..a52b98c 100644 --- a/dev-workflows-fullstack/agents/task-executor-frontend.md +++ b/dev-workflows-fullstack/agents/task-executor-frontend.md @@ -165,9 +165,9 @@ Applies when Pre-implementation Verification finds a dependency this task requir #### Adjacent Case Sweep (Required when the task file has a `Change Category` field set to one or more of `bug-fix`, `regression`, `state-change`, `boundary-change`) -Runs after Pre-implementation Verification, before the Binding Decision Check. This step fires on the field value the task decomposition wrote — read the field value and treat it as authoritative for whether the sweep applies. +Runs after Pre-implementation Verification, before the Binding Decision Check. This step fires on the field value the task materialization wrote — read the field value and treat it as authoritative for whether the sweep applies. -1. From the Investigation Targets (the decomposition already extended them with the adjacent files), identify the cases sharing the same path, contract, persisted state, or external boundary as the change — fallback rendering, stale state, retries, and external calls related to the change. +1. From the Investigation Targets (the materialization already extended them with the adjacent files), identify the cases sharing the same path, contract, persisted state, or external boundary as the change — fallback rendering, stale state, retries, and external calls related to the change. 2. Check the same defect class and record each case as `incorporated`, `unchanged` with evidence, or `out-of-scope` with the required scope decision; when none exist, record the searched surface. 3. Fold in-scope residuals into the applicable Proof Obligation and implementation; for `red-test`, include them in the failing tests. diff --git a/dev-workflows-fullstack/agents/task-executor.md b/dev-workflows-fullstack/agents/task-executor.md index 9d1a251..276d105 100644 --- a/dev-workflows-fullstack/agents/task-executor.md +++ b/dev-workflows-fullstack/agents/task-executor.md @@ -160,9 +160,9 @@ Applies when Pre-implementation Verification finds a dependency this task requir #### Adjacent Case Sweep (Required when the task file has a `Change Category` field set to one or more of `bug-fix`, `regression`, `state-change`, `boundary-change`) -Runs after Pre-implementation Verification, before the Binding Decision Check. This step fires on the field value the task decomposition wrote — read the field value and treat it as authoritative for whether the sweep applies. +Runs after Pre-implementation Verification, before the Binding Decision Check. This step fires on the field value the task materialization wrote — read the field value and treat it as authoritative for whether the sweep applies. -1. From the Investigation Targets (the decomposition already extended them with the adjacent files), identify the cases sharing the same path, contract, persisted state, or external boundary as the change — fallback behavior, stale state, retries, and external calls related to the change. +1. From the Investigation Targets (the materialization already extended them with the adjacent files), identify the cases sharing the same path, contract, persisted state, or external boundary as the change — fallback behavior, stale state, retries, and external calls related to the change. 2. Check the same defect class and record each case as `incorporated`, `unchanged` with evidence, or `out-of-scope` with the required scope decision; when none exist, record the searched surface. 3. Fold in-scope residuals into the applicable Proof Obligation and implementation; for `red-test`, include them in the failing tests. diff --git a/dev-workflows-fullstack/agents/work-planner.md b/dev-workflows-fullstack/agents/work-planner.md index 88cd4a1..5bfcbea 100644 --- a/dev-workflows-fullstack/agents/work-planner.md +++ b/dev-workflows-fullstack/agents/work-planner.md @@ -41,9 +41,9 @@ Choose Strategy A (TDD) if test skeletons are provided, Strategy B (implementati - **Include a Proof Strategy in the work plan header** (see plan template) — name the proof source for each applicable verification mode and state that every task with a claim or verifiable deliverable records Proof Obligations for downstream review - **Record the Review Scope in the work plan header** — for a fresh pre-implementation plan, the planned-files scope derived from the Design Doc and task target files; for a revision plan over existing work, the base branch and diff range — so the work plan review and downstream verification share one scope - **Include a Failure Mode Checklist in the work plan** (see plan template) — enumerate all nine domain-independent failure categories (same-value, no-op, empty input, invalid option, missing config, unavailable boundary, shared-state dependency, rollback-only visibility, missing-sort-key ordering), mark which apply, and map each applicable one to its covering task(s), keeping entries free of project-specific names -- Include verification tasks in the phase corresponding to Verification Strategy's verification timing -- When test skeletons are provided, place integration test implementation in corresponding phases and E2E test execution in the final phase -- When test skeletons are not provided, include test implementation tasks based on Design Doc acceptance criteria +- Place verification work in the implementation task whose outcome it proves and in the phase required by Verification Strategy's timing +- When test skeletons are provided, include integration test implementation with the corresponding implementation outcome and E2E test execution in the final phase +- When test skeletons are not provided, include test implementation with the Design Doc acceptance criteria outcome it proves - Final phase is always Quality Assurance **E2E Gap Check (all strategies)**: @@ -91,9 +91,9 @@ Read the Design Doc template from documentation-criteria skill to identify all s | Category | What to Look For | Task Requirement | |---|---|---| | Implementation target | Components, functions, or data structures to create or modify | Implementation task | -| Connection/switching/registration | Integration points, dependency wiring, switching methods | Setup/wiring task | -| Contract change and propagation | Interface changes, data contract changes, field propagation across boundaries | Update task for each affected consumer | -| Verification requirement | Verification methods, test boundaries, integration verification points | Verification/test task | +| Connection/switching/registration | Integration points, dependency wiring, switching methods | Include in the implementation outcome it completes | +| Contract change and propagation | Interface changes, data contract changes, field propagation across boundaries | Keep affected consumers in the same contract-change outcome when rollback boundary and executor lane match; otherwise separate them | +| Verification requirement | Verification methods, test boundaries, integration verification points | Include in the implementation outcome it proves; use a dedicated task only for an independently consumable test artifact or setup outcome | | Prerequisite work | Migration steps, security measures, environment setup | Prerequisite task | Additionally, create Traceability rows for Design Convergence when it contains one or more Adopted Additions. For these other design-attention sections, create rows when the section is present and not N/A: State Transitions and Invariants, Field Propagation Map, Security Considerations, Logging and Monitoring sensitive-data rules, Error Handling matrix. Map each to the most relevant existing category (commonly `verification`, `contract-change`, or `prerequisite`). @@ -158,7 +158,7 @@ For each referenced ADR: Omit the table when no referenced ADR contains implementation-binding decisions. ### 6. Define Tasks with Completion Criteria -For each task, derive completion criteria from Design Doc acceptance criteria. Apply the 3-element completion definition (Implementation Complete, Quality Complete, Integration Complete). +For each task, derive completion criteria from Design Doc acceptance criteria and apply the 3-element completion definition (Implementation Complete, Quality Complete, Integration Complete). Populate the plan template's task-entry fields: stable `Phase X Task Y` ID, one Implementation outcome, concrete Target Files, one Rollback boundary, and one Executor lane (`backend` or `frontend`). Create separate task entries whenever the Implementation outcome, Rollback boundary, or Executor lane differs. Keep wiring or registration, tests, generated artifacts, and user documentation in the task whose outcome they complete or prove. ### 7. Produce Work Plan Document Write the work plan following the plan template from documentation-criteria skill. Include Phase Structure Diagram and Task Dependency Diagram (mermaid). @@ -189,7 +189,7 @@ Execute file output immediately (considered approved at execution). ## Important Task Design Principles -1. **Executable Granularity**: Each task as logical 1-commit unit, clear completion criteria, explicit dependencies +1. **Executable Granularity**: The plan template's task-entry format is the source of truth for single-commit boundaries. 2. **Built-in Quality**: Simultaneous test implementation, quality checks in each phase 3. **Risk Management**: List risks and countermeasures in advance, define detection methods 4. **Ensure Flexibility**: Prioritize essential purpose, include only information required for task execution and verification @@ -201,7 +201,7 @@ Execute file output immediately (considered approved at execution). 2. **Quality Complete**: Tests, static checking, linting pass 3. **Integration Complete**: Coordination with other components verified -Include completion conditions in task names (e.g., "Service implementation and unit test creation") +Phrase each Implementation outcome as the condition completed by that task (e.g., "Service behavior implemented and verified by unit tests") ## Implementation Strategy Selection @@ -280,14 +280,14 @@ Place all environment setup tasks in Phase 0 (before any implementation tasks). **Test Classification**: - Setup items (Mock preparation, measurement tools, Helpers, etc.) → Prioritize in Phase 1 - Unit tests (individual functions) → Use Red-Green-Refactor for new/changed behavior, or Baseline-Refactor-Verify for behavior-preserving refactors -- Integration tests → Place as create/execute tasks when relevant feature implementation is complete -- fixture-e2e tests → Place as create/execute tasks alongside the relevant UI feature implementation +- Integration tests → Include creation and execution in the relevant implementation outcome +- fixture-e2e tests → Include creation and execution in the relevant UI implementation outcome - service-integration-e2e tests → Place as execute-only tasks in final phase - Non-functional requirement tests (performance, UX, etc.) → Place in quality assurance phase - Risk levels ("high risk", "required", etc.) → Move to earlier phases **Task Generation Principles**: -- Always decompose 5+ test cases into subtasks (setup/high risk/normal/low risk) +- Group test cases with the implementation outcome they prove; use a separate task only for an independently consumable test artifact or setup outcome - Specify "X test implementations" in each task (quantify progress) - Specify traceability: Show correspondence with acceptance criteria in "AC1 support (3 items)" format @@ -306,9 +306,9 @@ Decompose tasks based on implementation approach and technical dependencies deci ### Task Dependencies - Dependencies up to 2 levels maximum (A→B→C acceptable, A→B→C→D requires redesign) -- Each task provides value independently as much as possible +- Use stable `Phase X Task Y` IDs from the task entries when declaring dependencies - Clearly define dependencies and explicitly identify tasks that can run in parallel -- Include integration points in task names +- Include integration points in the Implementation outcome text ### Phase Composition Compose phases based on technical dependencies and implementation approach from Design Doc. diff --git a/dev-workflows-fullstack/skills/documentation-criteria/references/plan-template.md b/dev-workflows-fullstack/skills/documentation-criteria/references/plan-template.md index 27c67c6..09c3a1e 100644 --- a/dev-workflows-fullstack/skills/documentation-criteria/references/plan-template.md +++ b/dev-workflows-fullstack/skills/documentation-criteria/references/plan-template.md @@ -140,6 +140,15 @@ For a serialized boundary, fill Serialized Format and Consumer Parse Rule. Set t Select ONE phase structure based on implementation approach from Design Doc. Phase Division Criteria are defined alongside this template. Per-phase quality checks run lint, typecheck, tests, build, and any adopted QA mechanisms from the Design Doc. +Each `Phase X Task Y` checkbox entry in a non-QA phase's `Tasks` section is one Work Plan implementation item. The ID is the stable key used by every `Covered By Task(s)` column. + +- [ ] Phase X Task Y: [Observable behavior, contract, migration, or downstream-consumable deliverable completed by this item] + - **Target Files**: [Concrete planned paths or path prefixes] + - **Rollback boundary**: [Behavior, contract, migration, or persisted state reverted together] + - **Executor lane**: [backend | frontend] + +Add one entry per implementation outcome. Create separate entries whenever the implementation outcome, rollback boundary, or executor lane differs. Select exactly one executor lane. Keep wiring or registration, tests, generated artifacts, and user documentation in the entry whose outcome they complete or prove. Record staged checks outside the `Tasks` section; they are phase checks rather than implementation items. + ### Option A: Vertical Slice Phase Structure Use when implementation approach is Vertical Slice. Each phase = one value unit with verification. @@ -149,8 +158,12 @@ Use when implementation approach is Vertical Slice. Each phase = one value unit **Verification**: [From Verification Strategy: early verification point] #### Tasks -- [ ] Task 1: Implementation -- [ ] Task 2: Verification per Verification Strategy +- [ ] Phase 1 Task 1: [First value unit, including its wiring and verification] + - **Target Files**: [path(s)] + - **Rollback boundary**: [changes reverted together] + - **Executor lane**: [backend | frontend] + +#### Phase Checks - [ ] Quality check (staged) #### Phase Completion Criteria @@ -162,8 +175,12 @@ Use when implementation approach is Vertical Slice. Each phase = one value unit **Verification**: [From Verification Strategy] #### Tasks -- [ ] Task 1: Implementation -- [ ] Task 2: Verification per Verification Strategy +- [ ] Phase 2 Task 1: [Subsequent value unit, including its wiring and verification] + - **Target Files**: [path(s)] + - **Rollback boundary**: [changes reverted together] + - **Executor lane**: [backend | frontend] + +#### Phase Checks - [ ] Quality check #### Phase Completion Criteria @@ -178,44 +195,56 @@ Use when implementation approach is Horizontal Slice. Phases follow Foundation **Purpose**: Contract definitions, interfaces, test preparation #### Tasks -- [ ] Task 1: Specific work content -- [ ] Task 2: Specific work content +- [ ] Phase 1 Task 1: [Foundation outcome and its verification] + - **Target Files**: [path(s)] + - **Rollback boundary**: [changes reverted together] + - **Executor lane**: [backend | frontend] + +#### Phase Checks - [ ] Quality check (staged) -- [ ] Unit tests: All related tests pass #### Phase Completion Criteria - [ ] [Functional completion criteria] +- [ ] All related unit tests pass - [ ] [Quality completion criteria] ### Phase 2: [Core Feature] (Estimated commits: X) **Purpose**: Business logic, unit tests #### Tasks -- [ ] Task 1: Specific work content -- [ ] Task 2: Specific work content +- [ ] Phase 2 Task 1: [Core feature outcome and its verification] + - **Target Files**: [path(s)] + - **Rollback boundary**: [changes reverted together] + - **Executor lane**: [backend | frontend] + +#### Phase Checks - [ ] Quality check (staged) -- [ ] Integration tests: Verify overall feature functionality #### Phase Completion Criteria - [ ] [Functional completion criteria] +- [ ] Integration tests verify overall feature functionality - [ ] [Quality completion criteria] ### Phase 3: [Integration] (Estimated commits: X) **Purpose**: External connections, presentation layer #### Tasks -- [ ] Task 1: Specific work content -- [ ] Task 2: Specific work content +- [ ] Phase 3 Task 1: [Integration outcome and its verification] + - **Target Files**: [path(s)] + - **Rollback boundary**: [changes reverted together] + - **Executor lane**: [backend | frontend] + +#### Phase Checks - [ ] Quality check -- [ ] Integration tests: Verify component coordination #### Phase Completion Criteria - [ ] [Functional completion criteria] +- [ ] Integration tests verify component coordination - [ ] [Quality completion criteria] ### Option C: Hybrid Phase Structure -Use when implementation approach is Hybrid. Combine vertical and horizontal phases as defined in Design Doc implementation approach. Structure phases per Design Doc specification, ensuring each phase has Tasks, Verification, and Phase Completion Criteria sections matching the format above. +Use when implementation approach is Hybrid. Combine vertical and horizontal phases as defined in Design Doc implementation approach. Use the same per-phase section structure as Option A/B. ### Final Phase: Quality Assurance (Required) (Estimated commits: 1) @@ -229,7 +258,7 @@ This phase is required for ALL implementation approaches. - [ ] Quality checks (types, lint, format) - [ ] Execute all tests (including integration/E2E from test skeletons, when provided) - [ ] Project-configured coverage threshold passes; when none is configured, review the coverage report and add tests for uncovered changed behavior or record why another verification method is sufficient -- [ ] Document updates +- [ ] Documentation updates required by implementation outcomes are complete ### Quality Assurance - [ ] Quality check (staged) diff --git a/dev-workflows-fullstack/skills/documentation-criteria/references/task-template.md b/dev-workflows-fullstack/skills/documentation-criteria/references/task-template.md index 6d8833a..c6d7a6d 100644 --- a/dev-workflows-fullstack/skills/documentation-criteria/references/task-template.md +++ b/dev-workflows-fullstack/skills/documentation-criteria/references/task-template.md @@ -1,9 +1,12 @@ # Task: [Task Name] Metadata: +- Source Work Plan Task: [Phase X Task Y] - Dependencies: task-01 → Deliverable: docs/plans/analysis/research-results.md - Provides: docs/plans/analysis/api-spec.md (for research/design tasks) -- Size: Small (1-2 files) +- Implementation outcome: [Observable behavior, contract, migration, or downstream-consumable deliverable completed by this task] +- Rollback boundary: [Behavior, contract, migration, or persisted state reverted together] +- Executor lane: [backend | frontend] ## Implementation Content [What this task will achieve] @@ -23,10 +26,10 @@ Include this section only for constraints with a listed source. Before escalatio ## Investigation Targets Files to read before starting implementation (file path, with optional search hint): -- [e.g., src/orders/checkout (processOrder function) — determined during task decomposition based on task nature] +- [e.g., src/orders/checkout (processOrder function) — determined during task materialization based on task nature] ## Change Category -(Include this field only when the task is a bug fix, regression, state-change, or boundary-change — populated during task decomposition. Omit otherwise.) +(Include this field only when the task is a bug fix, regression, state-change, or boundary-change — populated during task materialization. Omit otherwise.) `Change Category: ` diff --git a/dev-workflows-fullstack/skills/recipe-build/SKILL.md b/dev-workflows-fullstack/skills/recipe-build/SKILL.md index 8a375ed..0ebe4c5 100644 --- a/dev-workflows-fullstack/skills/recipe-build/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-build/SKILL.md @@ -1,6 +1,6 @@ --- name: recipe-build -description: Execute decomposed tasks in autonomous execution mode +description: Execute materialized task files in autonomous execution mode disable-model-invocation: true --- @@ -26,7 +26,7 @@ Work plan: $ARGUMENTS Before any task processing, locate the work plan. Resolution rule: 1. List task files in `docs/plans/tasks/` matching the single-layer pattern `{plan-name}-task-*.md`. Layer-aware fullstack tasks (`{plan-name}-backend-task-*.md` / `{plan-name}-frontend-task-*.md`) are excluded here so a stale fullstack run does not redirect this recipe to the wrong work plan -2. From the matched files, also exclude every file matching any of these patterns — they originate from other workflow phases and are not implementation tasks for this run's plan: `*-task-prep-*.md` (readiness preflight tasks), `_overview-*.md` (decomposition overview file), `*-phase*-completion.md` (per-phase completion files), `review-fixes-*.md` (post-implementation review fixes), `integration-tests-*-task-*.md` (integration-test add-on scaffolding) +2. From the matched files, also exclude every file matching any of these patterns — they originate from other workflow phases and are not implementation tasks for this run's plan: `*-task-prep-*.md` (readiness preflight tasks), `_overview-*.md` (materialization overview file), `*-phase*-completion.md` (per-phase completion files), `review-fixes-*.md` (post-implementation review fixes), `integration-tests-*-task-*.md` (integration-test add-on scaffolding) 3. For each remaining file, extract the `{plan-name}` prefix as the segment that appears before `-task-` 4. When at least one task file matches, the work plan is `docs/plans/{plan-name}.md` for the prefix that has the most recent task-file mtime; ties broken by the lexicographically last `{plan-name}` 5. When no task file matches the restricted pattern, the work plan is the most-recent-mtime non-template `.md` in `docs/plans/` @@ -48,10 +48,10 @@ Analyze the Consumed Task Set and determine the action required: |-------|----------|-------------| | Tasks exist | Consumed Task Set is non-empty | User's execution instruction serves as batch approval → Enter autonomous execution immediately | | No tasks + plan exists | Consumed Task Set is empty but the resolved work plan exists | Confirm with user → run task-decomposer | -| Neither exists + Design Doc exists | No plan, no Consumed Task Set, but `docs/design/*.md` exists | Invoke work-planner to create work plan from Design Doc, then run document-reviewer (`dev-workflows-fullstack:document-reviewer`, doc_type: WorkPlan); branch on the reviewer's `verdict.decision` — on `needs_revision`, re-invoke work-planner (update) and re-review until `approved`/`approved_with_conditions`; if the same blocking finding repeats without new evidence or a contract change, stop and escalate it; then present the reviewed plan for batch approval before task decomposition; on `rejected`, stop before task decomposition and escalate to the user | +| Neither exists + Design Doc exists | No plan, no Consumed Task Set, but `docs/design/*.md` exists | Invoke work-planner to create work plan from Design Doc, then run document-reviewer (`dev-workflows-fullstack:document-reviewer`, doc_type: WorkPlan); branch on the reviewer's `verdict.decision` — on `needs_revision`, re-invoke work-planner (update) and re-review until `approved`/`approved_with_conditions`; if the same blocking finding repeats without new evidence or a contract change, stop and escalate it; then present the reviewed plan for batch approval before task materialization; on `rejected`, stop before task materialization and escalate to the user | | Neither exists | No plan, no Consumed Task Set, no Design Doc | Report missing prerequisites to user and stop | -## Task Decomposition Phase (Conditional) +## Task Materialization Phase (Conditional) When the Consumed Task Set is empty: @@ -63,11 +63,11 @@ Work plan: docs/plans/[plan-name].md Generate tasks from the work plan? (y/n): ``` -### 2. Task Decomposition (if approved) +### 2. Task Materialization (if approved) Invoke task-decomposer using Agent tool: - `subagent_type`: "dev-workflows-fullstack:task-decomposer" -- `description`: "Decompose work plan" -- `prompt`: "Read work plan at docs/plans/[plan-name].md and decompose into atomic tasks. Output: Individual task files in docs/plans/tasks/. Granularity: 1 task = 1 commit = independently executable" +- `description`: "Materialize work plan tasks" +- `prompt`: "Read work plan at docs/plans/[plan-name].md and output individual single-commit task files in docs/plans/tasks/." ### 3. Verify Generation Recompute the Consumed Task Set using the same restricted pattern from the Consumed Task Set section above. Confirm it is now non-empty. If it is still empty, escalate to the user — task-decomposer either failed silently or produced files that don't match the expected pattern. @@ -141,7 +141,7 @@ If task files cannot be deleted (filesystem error), report the failure but do no ## Completion Report Contract Final report must include: -- Task decomposition status +- Task materialization status - Implemented task count - Quality check result - Commit count diff --git a/dev-workflows-fullstack/skills/recipe-front-build/SKILL.md b/dev-workflows-fullstack/skills/recipe-front-build/SKILL.md index 157245a..dd01258 100644 --- a/dev-workflows-fullstack/skills/recipe-front-build/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-front-build/SKILL.md @@ -1,6 +1,6 @@ --- name: recipe-front-build -description: Execute frontend implementation in autonomous execution mode +description: Execute materialized frontend task files in autonomous execution mode disable-model-invocation: true --- @@ -26,7 +26,7 @@ Work plan: $ARGUMENTS Before any task processing, locate the work plan. Resolution rule: 1. List task files in `docs/plans/tasks/` matching the single-layer pattern `{plan-name}-task-*.md`. Layer-aware fullstack tasks (`{plan-name}-backend-task-*.md` / `{plan-name}-frontend-task-*.md`) are excluded here so a stale fullstack run does not redirect this recipe to the wrong work plan -2. From the matched files, also exclude every file matching any of these patterns — they originate from other workflow phases and are not implementation tasks for this run's plan: `*-task-prep-*.md` (readiness preflight tasks), `_overview-*.md` (decomposition overview file), `*-phase*-completion.md` (per-phase completion files), `review-fixes-*.md` (post-implementation review fixes), `integration-tests-*-task-*.md` (integration-test add-on scaffolding) +2. From the matched files, also exclude every file matching any of these patterns — they originate from other workflow phases and are not implementation tasks for this run's plan: `*-task-prep-*.md` (readiness preflight tasks), `_overview-*.md` (materialization overview file), `*-phase*-completion.md` (per-phase completion files), `review-fixes-*.md` (post-implementation review fixes), `integration-tests-*-task-*.md` (integration-test add-on scaffolding) 3. For each remaining file, extract the `{plan-name}` prefix as the segment that appears before `-task-` 4. When at least one task file matches, the work plan is `docs/plans/{plan-name}.md` for the prefix that has the most recent task-file mtime; ties broken by the lexicographically last `{plan-name}` 5. When no task file matches the restricted pattern, the work plan is the most-recent-mtime non-template `.md` in `docs/plans/` @@ -48,10 +48,10 @@ Analyze the Consumed Task Set and determine the action required: |-------|----------|-------------| | Tasks exist | Consumed Task Set is non-empty | User's execution instruction serves as batch approval → Enter autonomous execution immediately | | No tasks + plan exists | Consumed Task Set is empty but the resolved work plan exists | Confirm with user → run task-decomposer | -| Neither exists + Design Doc exists | No plan, no Consumed Task Set, but `docs/design/*.md` exists | Invoke work-planner to create work plan from Design Doc, then run document-reviewer (`dev-workflows-fullstack:document-reviewer`, doc_type: WorkPlan); branch on the reviewer's `verdict.decision` — on `needs_revision`, re-invoke work-planner (update) and re-review until `approved`/`approved_with_conditions`; if the same blocking finding repeats without new evidence or a contract change, stop and escalate it; then present the reviewed plan for batch approval before task decomposition; on `rejected`, stop before task decomposition and escalate to the user | +| Neither exists + Design Doc exists | No plan, no Consumed Task Set, but `docs/design/*.md` exists | Invoke work-planner to create work plan from Design Doc, then run document-reviewer (`dev-workflows-fullstack:document-reviewer`, doc_type: WorkPlan); branch on the reviewer's `verdict.decision` — on `needs_revision`, re-invoke work-planner (update) and re-review until `approved`/`approved_with_conditions`; if the same blocking finding repeats without new evidence or a contract change, stop and escalate it; then present the reviewed plan for batch approval before task materialization; on `rejected`, stop before task materialization and escalate to the user | | Neither exists | No plan, no Consumed Task Set, no Design Doc | Report missing prerequisites to user and stop | -## Task Decomposition Phase (Conditional) +## Task Materialization Phase (Conditional) When the Consumed Task Set is empty: @@ -63,11 +63,11 @@ Work plan: docs/plans/[plan-name].md Generate tasks from the work plan? (y/n): ``` -### 2. Task Decomposition (if approved) +### 2. Task Materialization (if approved) Invoke task-decomposer using Agent tool: - `subagent_type`: "dev-workflows-fullstack:task-decomposer" -- `description`: "Decompose work plan" -- `prompt`: "Read work plan at docs/plans/[plan-name].md and decompose into atomic tasks. Output: Individual task files in docs/plans/tasks/. Granularity: 1 task = 1 commit = independently executable" +- `description`: "Materialize work plan tasks" +- `prompt`: "Read work plan at docs/plans/[plan-name].md and output individual single-commit task files in docs/plans/tasks/." ### 3. Verify Generation Recompute the Consumed Task Set using the same restricted pattern from the Consumed Task Set section above. Confirm it is now non-empty. If it is still empty, escalate to the user — task-decomposer either failed silently or produced files that don't match the expected pattern. @@ -141,7 +141,7 @@ If task files cannot be deleted (filesystem error), report the failure but do no ## Completion Report Contract Final report must include: -- Task decomposition status +- Task materialization status - Implemented task count - Quality check result - Commit count diff --git a/dev-workflows-fullstack/skills/recipe-fullstack-build/SKILL.md b/dev-workflows-fullstack/skills/recipe-fullstack-build/SKILL.md index d58db1d..acdca14 100644 --- a/dev-workflows-fullstack/skills/recipe-fullstack-build/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-fullstack-build/SKILL.md @@ -1,6 +1,6 @@ --- name: recipe-fullstack-build -description: Execute decomposed fullstack tasks with layer-aware agent routing +description: Execute materialized fullstack task files with layer-aware agent routing disable-model-invocation: true --- @@ -34,7 +34,7 @@ Work plan: $ARGUMENTS Before any task processing, locate the work plan. Resolution rule: 1. List task files in `docs/plans/tasks/` matching the layer-aware patterns `{plan-name}-backend-task-*.md` and `{plan-name}-frontend-task-*.md` only. Single-layer tasks (`{plan-name}-task-*.md`) are excluded here so a stale single-layer run does not redirect this recipe to the wrong work plan -2. From the matched files, also exclude every file matching any of these patterns — they originate from other workflow phases and are not implementation tasks for this run's plan: `*-task-prep-*.md` (readiness preflight tasks), `_overview-*.md` (decomposition overview file), `*-phase*-completion.md` (per-phase completion files), `review-fixes-*.md` (post-implementation review fixes), `integration-tests-*-task-*.md` (integration-test add-on scaffolding) +2. From the matched files, also exclude every file matching any of these patterns — they originate from other workflow phases and are not implementation tasks for this run's plan: `*-task-prep-*.md` (readiness preflight tasks), `_overview-*.md` (materialization overview file), `*-phase*-completion.md` (per-phase completion files), `review-fixes-*.md` (post-implementation review fixes), `integration-tests-*-task-*.md` (integration-test add-on scaffolding) 3. For each remaining file, extract the `{plan-name}` prefix as the segment that appears before `-backend-task-` or `-frontend-task-` 4. When at least one task file matches, the work plan is `docs/plans/{plan-name}.md` for the prefix that has the most recent task-file mtime; ties broken by the lexicographically last `{plan-name}` 5. When no task file matches the restricted pattern, the work plan is the most-recent-mtime non-template `.md` in `docs/plans/` @@ -56,10 +56,10 @@ Analyze the Consumed Task Set and determine the action required: |-------|----------|-------------| | Tasks exist | Consumed Task Set is non-empty | User's execution instruction serves as batch approval → Enter autonomous execution immediately | | No tasks + plan exists | Consumed Task Set is empty but the resolved work plan exists | Confirm with user → run task-decomposer | -| Neither exists + Design Doc exists | No plan, no Consumed Task Set, but `docs/design/*.md` exists | Invoke work-planner to create work plan from Design Doc(s), then run document-reviewer (`dev-workflows-fullstack:document-reviewer`, doc_type: WorkPlan); branch on the reviewer's `verdict.decision` — on `needs_revision`, re-invoke work-planner (update) and re-review until `approved`/`approved_with_conditions`; if the same blocking finding repeats without new evidence or a contract change, stop and escalate it; then present the reviewed plan for batch approval before task decomposition; on `rejected`, stop before task decomposition and escalate to the user | +| Neither exists + Design Doc exists | No plan, no Consumed Task Set, but `docs/design/*.md` exists | Invoke work-planner to create work plan from Design Doc(s), then run document-reviewer (`dev-workflows-fullstack:document-reviewer`, doc_type: WorkPlan); branch on the reviewer's `verdict.decision` — on `needs_revision`, re-invoke work-planner (update) and re-review until `approved`/`approved_with_conditions`; if the same blocking finding repeats without new evidence or a contract change, stop and escalate it; then present the reviewed plan for batch approval before task materialization; on `rejected`, stop before task materialization and escalate to the user | | Neither exists | No plan, no Consumed Task Set, no Design Doc | Report missing prerequisites to user and stop | -## Task Decomposition Phase (Conditional) +## Task Materialization Phase (Conditional) When the Consumed Task Set is empty: @@ -71,11 +71,11 @@ Work plan: docs/plans/[plan-name].md Generate tasks from the work plan? (y/n): ``` -### 2. Task Decomposition (if approved) +### 2. Task Materialization (if approved) Invoke task-decomposer using Agent tool: - `subagent_type`: "dev-workflows-fullstack:task-decomposer" -- `description`: "Decompose work plan" -- `prompt`: "Read work plan at docs/plans/[plan-name].md and decompose into atomic tasks. Output: Individual task files in docs/plans/tasks/. Granularity: 1 task = 1 commit = independently executable. Use layer-aware naming: {plan}-backend-task-{n}.md, {plan}-frontend-task-{n}.md based on Target files paths." +- `description`: "Materialize work plan tasks" +- `prompt`: "Read work plan at docs/plans/[plan-name].md and output individual single-commit task files in docs/plans/tasks/. Use layer-aware naming: {plan}-backend-task-{n}.md, {plan}-frontend-task-{n}.md from each Work Plan task's Executor lane." ### 3. Verify Generation Recompute the Consumed Task Set using the same restricted pattern from the Consumed Task Set section above. Confirm it is now non-empty. If it is still empty, escalate to the user — task-decomposer either failed silently or produced files that don't match the expected pattern. @@ -159,7 +159,7 @@ If task files cannot be deleted (filesystem error), report the failure but do no ## Completion Report Contract Final report must include: -- Task decomposition status +- Task materialization status - Implemented task count, including backend/frontend counts - Quality check result - Commit count diff --git a/dev-workflows-fullstack/skills/recipe-prepare-implementation/SKILL.md b/dev-workflows-fullstack/skills/recipe-prepare-implementation/SKILL.md index 5ffdb5e..1117e6f 100644 --- a/dev-workflows-fullstack/skills/recipe-prepare-implementation/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-prepare-implementation/SKILL.md @@ -52,7 +52,7 @@ R4 and R5 are evaluated only when their triggering signals appear in the work pl **State check**: - Work plan exists → Proceed to Step 1 -- No work plan → Stop and report: "An approved work plan is required. Complete the upstream planning phase first, then re-invoke this recipe." +- No work plan → Stop and report: "A work plan is required. Complete the upstream planning phase first, then re-invoke this recipe." ## Execution Flow diff --git a/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md index cefbd53..7eaf34a 100644 --- a/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md @@ -245,7 +245,7 @@ After "batch approval for entire implementation phase" with work-planner, autono ```mermaid graph TD START[Batch approval for entire implementation phase] --> AUTO[Start autonomous execution mode] - AUTO --> TD[task-decomposer: Task decomposition] + AUTO --> TD[task-decomposer: Task materialization] TD --> LOOP[Task execution loop] LOOP --> TE[task-executor: Implementation] TE --> ESCJUDGE{Escalation judgment} diff --git a/dev-workflows-fullstack/skills/subagents-orchestration-guide/references/monorepo-flow.md b/dev-workflows-fullstack/skills/subagents-orchestration-guide/references/monorepo-flow.md index f51fa3c..74a52d2 100644 --- a/dev-workflows-fullstack/skills/subagents-orchestration-guide/references/monorepo-flow.md +++ b/dev-workflows-fullstack/skills/subagents-orchestration-guide/references/monorepo-flow.md @@ -119,16 +119,16 @@ work-planner's existing Integration Complete criteria naturally covers cross-lay For Medium and Large flows, pass the resulting Work Plan to document-reviewer with `doc_type: WorkPlan`. On `needs_revision`, route the findings to work-planner in update mode and re-review. If the same blocking finding repeats and the update supplies no new evidence or contract change, stop and escalate instead of repeating the loop. Request batch approval only after the review is `approved` or `approved_with_conditions`; escalate `rejected` to the user. -## Task Decomposition Phase +## Task Materialization Phase -task-decomposer follows standard decomposition from the work plan. The key addition is the **layer-aware naming convention**: +task-decomposer materializes each Work Plan implementation item as one task file. The key addition is the **layer-aware naming convention**: | Filename Pattern | Meaning | Executor | Quality Fixer | |-----------------|---------|----------|---------------| | `{plan}-backend-task-{n}.md` | Backend only | task-executor | quality-fixer | | `{plan}-frontend-task-{n}.md` | Frontend only | task-executor-frontend | quality-fixer-frontend | -Layer is determined from the task's **Target files** paths — this is a factual determination, not inference. +Layer is selected from the Work Plan item's **Executor lane**. Target Files and the filename segment must agree with that copied value. ## Task Cycle diff --git a/dev-workflows/.claude-plugin/plugin.json b/dev-workflows/.claude-plugin/plugin.json index 442fc2f..54d25d8 100644 --- a/dev-workflows/.claude-plugin/plugin.json +++ b/dev-workflows/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "dev-workflows", "description": "Skills + Subagents for backend development - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", - "version": "0.22.8", + "version": "0.22.9", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows/agents/task-decomposer.md b/dev-workflows/agents/task-decomposer.md index e08c9fc..4a50566 100644 --- a/dev-workflows/agents/task-decomposer.md +++ b/dev-workflows/agents/task-decomposer.md @@ -1,6 +1,6 @@ --- name: task-decomposer -description: Reads work plan documents from docs/plans and decomposes them into independent, single-commit granularity tasks placed in docs/plans/tasks. PROACTIVELY proposes task decomposition when work plans are created. +description: Reads work plan documents from docs/plans and materializes each implementation item as one detailed, single-commit task file in docs/plans/tasks. PROACTIVELY proposes task generation when work plans are created. tools: Read, Write, LS, Bash, TaskCreate, TaskUpdate skills: - ai-development-guide @@ -11,13 +11,13 @@ skills: - llm-friendly-context --- -You are an AI assistant specialized in decomposing work plans into executable tasks. +You are an AI assistant specialized in materializing Work Plan implementation items as executable task files. ## Initial Mandatory Tasks **Task Registration**: Register work steps using TaskCreate. Always include first task "Map preloaded skills to applicable concrete rules" and final task "Verify the mapped rules before final JSON". Update status using TaskUpdate upon each completion. -## Primary Principle of Task Division +## Primary Principle of Task Materialization **Each task must be verifiable at an appropriate level** @@ -25,7 +25,7 @@ You are an AI assistant specialized in decomposing work plans into executable ta Task design based on verification levels (L1/L2/L3) defined in implementation-approach skill. ### Implementation Strategy Application -Decompose tasks based on implementation strategy patterns determined in implementation-approach skill. +Preserve the implementation strategy and task boundaries recorded in the Work Plan while adding the execution detail needed by each task. ## Main Responsibilities @@ -36,11 +36,10 @@ Decompose tasks based on implementation strategy patterns determined in implemen - **Interface change detection and response** - **Extract Verification Strategy from work plan header** -2. **Task Decomposition** - - Decompose at 1 commit = 1 task granularity (logical change unit) - - **Prioritize verifiability** (follow priority defined in implementation-approach skill) - - Ensure each task is independently executable (minimize interdependencies) - - Clarify order when dependencies exist +2. **Task Materialization** + - Materialize each Work Plan implementation item as exactly one single-commit task file + - Copy its source ID, implementation outcome, Target Files, rollback boundary, executor lane, and dependencies without changing the boundary + - Keep the wiring or registration, related tests, generated artifacts, and user documentation assigned to that item - Select the task's verification flow: Red-Green-Refactor for new/changed behavior or reproducible bugs; Baseline-Refactor-Verify only when no AC, public contract, or observable outcome changes; Evidence-First when a recorded executable reproduction attempt identifies a concrete blocker, or for non-executable deliverables - Scope of responsibility: Complete the selected verification flow and its Proof Obligations; overall quality remains a separate process @@ -51,15 +50,16 @@ Decompose tasks based on implementation strategy patterns determined in implemen - Define clear completion criteria within the task scope - Populate task-template Hard Constraints with an allowed action and authoritative source; omit the section when none applies -## Task Size Criteria -- **Small (Recommended)**: 1-2 files -- **Medium (Acceptable)**: 3-5 files -- **Large (Must Split)**: 6+ files +## Work Plan Task Materialization -### Judgment Criteria -- Cognitive load: Amount readable while maintaining context (1-2 files is appropriate) -- Reviewability: PR diff within 100 lines (ideal), within 200 lines (acceptable) -- Rollback: Granularity that can be reverted in 1 commit +A Work Plan implementation item is a `Phase X Task Y:` checkbox entry in a non-QA phase's `Tasks` section. `Phase X Task Y` is its stable source ID. + +For every implementation item: + +1. Generate exactly one task file. +2. Copy its Source Work Plan Task, Implementation outcome, Target Files, Rollback boundary, Executor lane, and declared dependencies without regrouping them. +3. Use Executor lane to select the layer-aware filename segment when the plan spans layers. +4. Propagate each Work Plan row whose `Covered By Task(s)` contains the source ID to that generated task. ## Workflow @@ -69,14 +69,10 @@ Decompose tasks based on implementation strategy patterns determined in implemen ls docs/plans/*.md | grep -v template.md ``` -2. **Plan Analysis and Overall Design** +2. **Plan Analysis** - Confirm phase structure - - Extract task list - - Identify dependencies - - **Overall Optimization Considerations** - - Identify common processing (prevent redundant implementation) - - Pre-map impact scope - - Identify information sharing points between tasks + - Extract Work Plan implementation items and their stable source IDs + - Copy each item's implementation outcome, Target Files, rollback boundary, executor lane, and dependencies 3. **Overall Design Document Creation** - Record overall design in `docs/plans/tasks/_overview-{plan-name}.md` @@ -86,7 +82,7 @@ Decompose tasks based on implementation strategy patterns determined in implemen 4. **Task File Generation** - Naming convention: `{plan-name}-task-{number}.md` - Layer-aware naming (when the plan spans multiple layers): `{plan-name}-backend-task-{number}.md`, `{plan-name}-frontend-task-{number}.md` - - Layer is determined from the task's Target files paths + - Layer is selected from the Work Plan item's Executor lane - Examples: `20250122-refactor-types-task-01.md`, `20250122-auth-backend-task-01.md`, `20250122-auth-frontend-task-02.md` - **Phase Completion Task Auto-generation (Required)**: - Based on "Phase X" notation in work plan, generate after each phase's final task @@ -96,6 +92,7 @@ Decompose tasks based on implementation strategy patterns determined in implemen 5. **Task Structuring** Include the following in each task file: + - Source Work Plan Task and boundary metadata from the task template - Task overview - Target files - Conditional **Hard Constraints** per task-template @@ -167,7 +164,7 @@ Each task that implements a claim or verifiable deliverable carries Proof Obliga When the work plan contains a Failure Mode Checklist, propagate each applicable category to the task(s) it maps to as a provable obligation rather than a plan-only declaration: -1. **Lookup by task ID**: For each Checklist row marked `Applies? = yes`, locate the task(s) listed in the "Covered By Task(s)" column. +1. **Match the source task**: For each Checklist row marked `Applies? = yes`, propagate the row to the generated task whose `Source Work Plan Task` equals each ID in "Covered By Task(s)". 2. **Add a Proof Obligation per category**: Add or merge one entry for each matched category. For a new entry, select `Verification mode` using Proof Obligation Propagation above. Use `red-test` when the failure condition is executable and reproducible, instantiating the category as `Primary failure mode` for the task (e.g., `missing-sort-key ordering` → "rows lacking the sort key are misplaced or reorder nondeterministically in this task's listing"). For other modes, set `Primary failure mode` to `N/A`, keep the failure-mode condition in `Claim`, and use the mode-specific `Evidence requirement`. Populate remaining fields from the AC and target files; without a covering AC, use the failure-mode condition as `Claim` and `N/A` for `State assertion` unless the task changes state. 3. **Merge into the existing entry**: When an AC-derived Proof Obligation already covers the same failure mode, preserve its selected `Verification mode` and merge the category into that entry rather than adding a parallel one. 4. **Apply only when provided**: Run this propagation only when the work plan contains a Failure Mode Checklist with applicable categories. @@ -185,21 +182,21 @@ When the work plan header includes a Quality Assurance Mechanisms table, propaga When the work plan contains a UI Spec Component → Task Mapping table, propagate component references to each implementation task as follows: -1. **Lookup by task ID**: For each row in the mapping table, locate the task(s) listed in the "Covered By Task(s)" column +1. **Match the source task**: For each row, propagate it to the generated task whose `Source Work Plan Task` equals each ID in "Covered By Task(s)" 2. **Append a single line to Investigation Targets**: Add one line per matched component in the task's Investigation Targets section. The line format is `[ui-spec path] (§ [component heading])`, where `` is appended only when the row lists specific states. - When no states are listed: `docs/ui-spec/foo-ui-spec.md (§ Component: AlertCard)` - When states are listed: `docs/ui-spec/foo-ui-spec.md (§ Component: AlertCard — verify default + loading + error states)` This is the entire entry — do not also add a separate parenthetical line. The state hint is part of the same line. -3. **One row → one or more tasks**: A component can be split across multiple tasks; propagate the same line to each +3. **One row → one or more tasks**: When a row names multiple source IDs, propagate the same line to each matching task 4. **Skip when not provided**: If the work plan has no UI Spec Component → Task Mapping table, skip this propagation step ## Connection Map Propagation When the work plan contains a Connection Map table, propagate boundary context to each implementation task as follows: -1. **Lookup by task ID**: For each row in the Connection Map, locate the task(s) listed in the "Covered By Task(s)" column +1. **Match the source task**: For each row, propagate it to the generated task whose `Source Work Plan Task` equals each ID in "Covered By Task(s)" 2. **Append to Investigation Targets**: Add the boundary's owner module file paths on both sides to each matched task's Investigation Targets 3. **Add a "Boundary Context" note in the task body**: Record the boundary identifier and expected signal verbatim from the Connection Map row, making the required observable evidence explicit. When the row carries a **Serialized Format** and **Consumer Parse Rule** (a serialized in-runtime boundary), copy both verbatim into the note and state the roundtrip check the task must satisfy: the value the producer emits parses to the value the consumer expects. 4. **Skip when not provided**: If the work plan has no Connection Map, skip this propagation step @@ -208,7 +205,7 @@ When the work plan contains a Connection Map table, propagate boundary context t When the work plan contains an ADR Bindings table, propagate each binding decision to the task(s) it covers: -1. **Lookup by task ID**: For each row in the ADR Bindings table, locate the task(s) listed in the "Covered By Task(s)" column +1. **Match the source task**: For each row, propagate it to the generated task whose `Source Work Plan Task` equals each ID in "Covered By Task(s)" 2. **Append to Investigation Targets**: Add the ADR file path with the section hint matching the row's `Source Section` value (e.g., `docs/adr/ADR-0042.md (§ Decision)` or `docs/adr/ADR-0042.md (§ Implementation Guidance)`) to each matched task 3. **Add Binding Decisions table to the task**: For each matched row, add one row to the task's Binding Decisions table: - **Source**: The ADR file path with the section hint matching the row's `Source Section` value @@ -228,7 +225,7 @@ When the work plan contains an ADR Bindings table, propagate each binding decisi When the work plan contains a Design-to-Plan Traceability table, propagate the matching DD section to each task: -1. For each row, append the pair (`Design Doc`, `DD Section`) to every task listed in "Covered By Task(s)" as an Investigation Target, formatted as `[Design Doc value] (§ [DD Section value])` +1. For each row, append the pair (`Design Doc`, `DD Section`) to the generated task whose `Source Work Plan Task` equals each ID in "Covered By Task(s)", formatted as `[Design Doc value] (§ [DD Section value])` 2. Deduplicate when the same (Design Doc, DD Section) pair appears in multiple rows for one task 3. Apply only when the work plan contains a Design-to-Plan Traceability table @@ -236,7 +233,7 @@ When the work plan contains a Design-to-Plan Traceability table, propagate the m When the work plan contains a **Reference Contract Values** table, propagate each binding observable value to the task(s) it covers, enforcing the exact value rather than a back-pointer that requires re-derivation: -1. **Lookup by task ID**: For each row, locate the task(s) listed in "Covered By Task(s)" +1. **Match the source task**: For each row, propagate it to the generated task whose `Source Work Plan Task` equals each ID in "Covered By Task(s)" 2. **Append to Investigation Targets**: Add the row's `Design Doc (§ Section)` to each matched task (deduplicate against Design Traceability Propagation entries) 3. **Add a Reference Contracts table row to the task**: For each matched row, add one row to the task's Reference Contracts table (see task template): - **Source**: the `Design Doc (§ Section)` value @@ -280,12 +277,7 @@ Target Plan Document: [Plan document filename] ### Background and Context [Why this work is necessary] -## Task Division Design - -### Division Policy -[From what perspective tasks were divided] -- Vertical slice or horizontal slice selection reasoning -- Verifiability level distribution (levels defined in implementation-approach.md) +## Task Materialization ### Inter-task Relationship Map ``` @@ -302,10 +294,6 @@ Task 3: [Content] | operationA() | operationA() | None | - | | operationB(x) | operationC(x,y) | Yes | Task X | -### Common Processing Points -- [Functions/types/constants shared between tasks] -- [Design policy to avoid duplicate implementation] - ## Implementation Considerations ### Principles to Maintain Throughout @@ -323,19 +311,19 @@ Task 3: [Content] ## Output Format -### Decomposition Completion Report +### Materialization Completion Report ```markdown -📋 Task Decomposition Complete +📋 Task Materialization Complete Plan Document: [Filename] Overall Design Document: _overview-[plan-name].md -Number of Decomposed Tasks: [Number] +Number of Materialized Tasks: [Number] -Overall Optimization Results: -- Common Processing: [Common processing content] -- Impact Scope Management: [Boundary settings] -- Implementation Order Optimization: [Reasons for order determination] +Materialization Results: +- Source Tasks Materialized: [Count] +- Work Plan Rows Propagated: [Count or status] +- Execution Order: [Derived from declared dependencies] Generated Task Files: 1. [Task filename] - [Overview] @@ -343,20 +331,21 @@ Generated Task Files: ... Execution Order: -[Recommended execution order considering dependencies] +[Order expressed by the Work Plan's declared dependencies] Next Steps: -Please execute decomposed tasks according to the order. +Please execute generated tasks according to the order. ``` -## Task Decomposition Checklist +## Task Materialization Checklist - [ ] Previous task deliverable paths specified in subsequent tasks - [ ] Deliverable filenames specified for research tasks -- [ ] Common processing identification and shared design -- [ ] Task dependencies and execution order clarification +- [ ] Declared task dependencies copied unchanged - [ ] Impact scope and boundaries definition for each task -- [ ] Appropriate granularity (1-5 files/task) +- [ ] Every Work Plan implementation item materialized into exactly one generated implementation task +- [ ] Source ID, implementation outcome, Target Files, rollback boundary, executor lane, and dependencies copied unchanged +- [ ] Required wiring or registration, related tests, generated artifacts, and user documentation remain with their source Work Plan item - [ ] Investigation Targets specified for every task (specific file paths, not vague categories) - [ ] Proof Obligations recorded for each claim or verifiable deliverable with Verification mode, Evidence requirement, and applicable boundary/state assertions - [ ] Change Category set for bug-fix / regression / state-change / boundary-change tasks, with adjacent path/boundary owners added to Investigation Targets @@ -372,7 +361,6 @@ Please execute decomposed tasks according to the order. - [ ] Compliance Check is phrased as a Y/N-answerable positive predicate - [ ] Clear completion criteria setting - [ ] Overall design document creation -- [ ] Implementation efficiency and rework prevention (pre-identification of common processing, clarification of impact scope) ## Self-Validation [BLOCKING — before output] @@ -380,9 +368,12 @@ Run each item below before producing the final JSON. When any item is unsatisfie - [ ] Quality assurance steps are excluded from tasks (handled separately) - [ ] Every research task has concrete deliverables defined -- [ ] All inter-task dependencies are explicitly stated +- [ ] All declared inter-task dependencies are copied exactly - [ ] Every generated task resolves alternatives/optional behavior to an explicit choice, deterministic decision rule, or blocking unresolved item - [ ] Placeholder behavior states the exact temporary output, allowed dependency use, and verification expectation - [ ] Target Files and Investigation Targets are concrete enough to read without guessing -- [ ] Each task is compile/runtime viable at its own commit boundary, or the dependency that makes it viable is explicit +- [ ] Each task achieves its declared implementation outcome and is compile/runtime viable at its own commit boundary; dependencies may supply prerequisites but do not defer that task's required wiring or registration +- [ ] The set of `Source Work Plan Task` values in generated implementation tasks equals the set of Work Plan implementation task IDs, and each ID appears exactly once +- [ ] Every populated source ID in a `Covered By Task(s)` cell was propagated to the generated task with the matching `Source Work Plan Task` +- [ ] For layer-aware task names, Executor lane, Target Files, and backend/frontend filename segment agree - [ ] Generated task files, overview, and phase completion files preserve the same decisions from the work plan and referenced Design Doc/UI Spec/ADR rows diff --git a/dev-workflows/agents/task-executor.md b/dev-workflows/agents/task-executor.md index 9d1a251..276d105 100644 --- a/dev-workflows/agents/task-executor.md +++ b/dev-workflows/agents/task-executor.md @@ -160,9 +160,9 @@ Applies when Pre-implementation Verification finds a dependency this task requir #### Adjacent Case Sweep (Required when the task file has a `Change Category` field set to one or more of `bug-fix`, `regression`, `state-change`, `boundary-change`) -Runs after Pre-implementation Verification, before the Binding Decision Check. This step fires on the field value the task decomposition wrote — read the field value and treat it as authoritative for whether the sweep applies. +Runs after Pre-implementation Verification, before the Binding Decision Check. This step fires on the field value the task materialization wrote — read the field value and treat it as authoritative for whether the sweep applies. -1. From the Investigation Targets (the decomposition already extended them with the adjacent files), identify the cases sharing the same path, contract, persisted state, or external boundary as the change — fallback behavior, stale state, retries, and external calls related to the change. +1. From the Investigation Targets (the materialization already extended them with the adjacent files), identify the cases sharing the same path, contract, persisted state, or external boundary as the change — fallback behavior, stale state, retries, and external calls related to the change. 2. Check the same defect class and record each case as `incorporated`, `unchanged` with evidence, or `out-of-scope` with the required scope decision; when none exist, record the searched surface. 3. Fold in-scope residuals into the applicable Proof Obligation and implementation; for `red-test`, include them in the failing tests. diff --git a/dev-workflows/agents/work-planner.md b/dev-workflows/agents/work-planner.md index 88cd4a1..5bfcbea 100644 --- a/dev-workflows/agents/work-planner.md +++ b/dev-workflows/agents/work-planner.md @@ -41,9 +41,9 @@ Choose Strategy A (TDD) if test skeletons are provided, Strategy B (implementati - **Include a Proof Strategy in the work plan header** (see plan template) — name the proof source for each applicable verification mode and state that every task with a claim or verifiable deliverable records Proof Obligations for downstream review - **Record the Review Scope in the work plan header** — for a fresh pre-implementation plan, the planned-files scope derived from the Design Doc and task target files; for a revision plan over existing work, the base branch and diff range — so the work plan review and downstream verification share one scope - **Include a Failure Mode Checklist in the work plan** (see plan template) — enumerate all nine domain-independent failure categories (same-value, no-op, empty input, invalid option, missing config, unavailable boundary, shared-state dependency, rollback-only visibility, missing-sort-key ordering), mark which apply, and map each applicable one to its covering task(s), keeping entries free of project-specific names -- Include verification tasks in the phase corresponding to Verification Strategy's verification timing -- When test skeletons are provided, place integration test implementation in corresponding phases and E2E test execution in the final phase -- When test skeletons are not provided, include test implementation tasks based on Design Doc acceptance criteria +- Place verification work in the implementation task whose outcome it proves and in the phase required by Verification Strategy's timing +- When test skeletons are provided, include integration test implementation with the corresponding implementation outcome and E2E test execution in the final phase +- When test skeletons are not provided, include test implementation with the Design Doc acceptance criteria outcome it proves - Final phase is always Quality Assurance **E2E Gap Check (all strategies)**: @@ -91,9 +91,9 @@ Read the Design Doc template from documentation-criteria skill to identify all s | Category | What to Look For | Task Requirement | |---|---|---| | Implementation target | Components, functions, or data structures to create or modify | Implementation task | -| Connection/switching/registration | Integration points, dependency wiring, switching methods | Setup/wiring task | -| Contract change and propagation | Interface changes, data contract changes, field propagation across boundaries | Update task for each affected consumer | -| Verification requirement | Verification methods, test boundaries, integration verification points | Verification/test task | +| Connection/switching/registration | Integration points, dependency wiring, switching methods | Include in the implementation outcome it completes | +| Contract change and propagation | Interface changes, data contract changes, field propagation across boundaries | Keep affected consumers in the same contract-change outcome when rollback boundary and executor lane match; otherwise separate them | +| Verification requirement | Verification methods, test boundaries, integration verification points | Include in the implementation outcome it proves; use a dedicated task only for an independently consumable test artifact or setup outcome | | Prerequisite work | Migration steps, security measures, environment setup | Prerequisite task | Additionally, create Traceability rows for Design Convergence when it contains one or more Adopted Additions. For these other design-attention sections, create rows when the section is present and not N/A: State Transitions and Invariants, Field Propagation Map, Security Considerations, Logging and Monitoring sensitive-data rules, Error Handling matrix. Map each to the most relevant existing category (commonly `verification`, `contract-change`, or `prerequisite`). @@ -158,7 +158,7 @@ For each referenced ADR: Omit the table when no referenced ADR contains implementation-binding decisions. ### 6. Define Tasks with Completion Criteria -For each task, derive completion criteria from Design Doc acceptance criteria. Apply the 3-element completion definition (Implementation Complete, Quality Complete, Integration Complete). +For each task, derive completion criteria from Design Doc acceptance criteria and apply the 3-element completion definition (Implementation Complete, Quality Complete, Integration Complete). Populate the plan template's task-entry fields: stable `Phase X Task Y` ID, one Implementation outcome, concrete Target Files, one Rollback boundary, and one Executor lane (`backend` or `frontend`). Create separate task entries whenever the Implementation outcome, Rollback boundary, or Executor lane differs. Keep wiring or registration, tests, generated artifacts, and user documentation in the task whose outcome they complete or prove. ### 7. Produce Work Plan Document Write the work plan following the plan template from documentation-criteria skill. Include Phase Structure Diagram and Task Dependency Diagram (mermaid). @@ -189,7 +189,7 @@ Execute file output immediately (considered approved at execution). ## Important Task Design Principles -1. **Executable Granularity**: Each task as logical 1-commit unit, clear completion criteria, explicit dependencies +1. **Executable Granularity**: The plan template's task-entry format is the source of truth for single-commit boundaries. 2. **Built-in Quality**: Simultaneous test implementation, quality checks in each phase 3. **Risk Management**: List risks and countermeasures in advance, define detection methods 4. **Ensure Flexibility**: Prioritize essential purpose, include only information required for task execution and verification @@ -201,7 +201,7 @@ Execute file output immediately (considered approved at execution). 2. **Quality Complete**: Tests, static checking, linting pass 3. **Integration Complete**: Coordination with other components verified -Include completion conditions in task names (e.g., "Service implementation and unit test creation") +Phrase each Implementation outcome as the condition completed by that task (e.g., "Service behavior implemented and verified by unit tests") ## Implementation Strategy Selection @@ -280,14 +280,14 @@ Place all environment setup tasks in Phase 0 (before any implementation tasks). **Test Classification**: - Setup items (Mock preparation, measurement tools, Helpers, etc.) → Prioritize in Phase 1 - Unit tests (individual functions) → Use Red-Green-Refactor for new/changed behavior, or Baseline-Refactor-Verify for behavior-preserving refactors -- Integration tests → Place as create/execute tasks when relevant feature implementation is complete -- fixture-e2e tests → Place as create/execute tasks alongside the relevant UI feature implementation +- Integration tests → Include creation and execution in the relevant implementation outcome +- fixture-e2e tests → Include creation and execution in the relevant UI implementation outcome - service-integration-e2e tests → Place as execute-only tasks in final phase - Non-functional requirement tests (performance, UX, etc.) → Place in quality assurance phase - Risk levels ("high risk", "required", etc.) → Move to earlier phases **Task Generation Principles**: -- Always decompose 5+ test cases into subtasks (setup/high risk/normal/low risk) +- Group test cases with the implementation outcome they prove; use a separate task only for an independently consumable test artifact or setup outcome - Specify "X test implementations" in each task (quantify progress) - Specify traceability: Show correspondence with acceptance criteria in "AC1 support (3 items)" format @@ -306,9 +306,9 @@ Decompose tasks based on implementation approach and technical dependencies deci ### Task Dependencies - Dependencies up to 2 levels maximum (A→B→C acceptable, A→B→C→D requires redesign) -- Each task provides value independently as much as possible +- Use stable `Phase X Task Y` IDs from the task entries when declaring dependencies - Clearly define dependencies and explicitly identify tasks that can run in parallel -- Include integration points in task names +- Include integration points in the Implementation outcome text ### Phase Composition Compose phases based on technical dependencies and implementation approach from Design Doc. diff --git a/dev-workflows/skills/documentation-criteria/references/plan-template.md b/dev-workflows/skills/documentation-criteria/references/plan-template.md index 27c67c6..09c3a1e 100644 --- a/dev-workflows/skills/documentation-criteria/references/plan-template.md +++ b/dev-workflows/skills/documentation-criteria/references/plan-template.md @@ -140,6 +140,15 @@ For a serialized boundary, fill Serialized Format and Consumer Parse Rule. Set t Select ONE phase structure based on implementation approach from Design Doc. Phase Division Criteria are defined alongside this template. Per-phase quality checks run lint, typecheck, tests, build, and any adopted QA mechanisms from the Design Doc. +Each `Phase X Task Y` checkbox entry in a non-QA phase's `Tasks` section is one Work Plan implementation item. The ID is the stable key used by every `Covered By Task(s)` column. + +- [ ] Phase X Task Y: [Observable behavior, contract, migration, or downstream-consumable deliverable completed by this item] + - **Target Files**: [Concrete planned paths or path prefixes] + - **Rollback boundary**: [Behavior, contract, migration, or persisted state reverted together] + - **Executor lane**: [backend | frontend] + +Add one entry per implementation outcome. Create separate entries whenever the implementation outcome, rollback boundary, or executor lane differs. Select exactly one executor lane. Keep wiring or registration, tests, generated artifacts, and user documentation in the entry whose outcome they complete or prove. Record staged checks outside the `Tasks` section; they are phase checks rather than implementation items. + ### Option A: Vertical Slice Phase Structure Use when implementation approach is Vertical Slice. Each phase = one value unit with verification. @@ -149,8 +158,12 @@ Use when implementation approach is Vertical Slice. Each phase = one value unit **Verification**: [From Verification Strategy: early verification point] #### Tasks -- [ ] Task 1: Implementation -- [ ] Task 2: Verification per Verification Strategy +- [ ] Phase 1 Task 1: [First value unit, including its wiring and verification] + - **Target Files**: [path(s)] + - **Rollback boundary**: [changes reverted together] + - **Executor lane**: [backend | frontend] + +#### Phase Checks - [ ] Quality check (staged) #### Phase Completion Criteria @@ -162,8 +175,12 @@ Use when implementation approach is Vertical Slice. Each phase = one value unit **Verification**: [From Verification Strategy] #### Tasks -- [ ] Task 1: Implementation -- [ ] Task 2: Verification per Verification Strategy +- [ ] Phase 2 Task 1: [Subsequent value unit, including its wiring and verification] + - **Target Files**: [path(s)] + - **Rollback boundary**: [changes reverted together] + - **Executor lane**: [backend | frontend] + +#### Phase Checks - [ ] Quality check #### Phase Completion Criteria @@ -178,44 +195,56 @@ Use when implementation approach is Horizontal Slice. Phases follow Foundation **Purpose**: Contract definitions, interfaces, test preparation #### Tasks -- [ ] Task 1: Specific work content -- [ ] Task 2: Specific work content +- [ ] Phase 1 Task 1: [Foundation outcome and its verification] + - **Target Files**: [path(s)] + - **Rollback boundary**: [changes reverted together] + - **Executor lane**: [backend | frontend] + +#### Phase Checks - [ ] Quality check (staged) -- [ ] Unit tests: All related tests pass #### Phase Completion Criteria - [ ] [Functional completion criteria] +- [ ] All related unit tests pass - [ ] [Quality completion criteria] ### Phase 2: [Core Feature] (Estimated commits: X) **Purpose**: Business logic, unit tests #### Tasks -- [ ] Task 1: Specific work content -- [ ] Task 2: Specific work content +- [ ] Phase 2 Task 1: [Core feature outcome and its verification] + - **Target Files**: [path(s)] + - **Rollback boundary**: [changes reverted together] + - **Executor lane**: [backend | frontend] + +#### Phase Checks - [ ] Quality check (staged) -- [ ] Integration tests: Verify overall feature functionality #### Phase Completion Criteria - [ ] [Functional completion criteria] +- [ ] Integration tests verify overall feature functionality - [ ] [Quality completion criteria] ### Phase 3: [Integration] (Estimated commits: X) **Purpose**: External connections, presentation layer #### Tasks -- [ ] Task 1: Specific work content -- [ ] Task 2: Specific work content +- [ ] Phase 3 Task 1: [Integration outcome and its verification] + - **Target Files**: [path(s)] + - **Rollback boundary**: [changes reverted together] + - **Executor lane**: [backend | frontend] + +#### Phase Checks - [ ] Quality check -- [ ] Integration tests: Verify component coordination #### Phase Completion Criteria - [ ] [Functional completion criteria] +- [ ] Integration tests verify component coordination - [ ] [Quality completion criteria] ### Option C: Hybrid Phase Structure -Use when implementation approach is Hybrid. Combine vertical and horizontal phases as defined in Design Doc implementation approach. Structure phases per Design Doc specification, ensuring each phase has Tasks, Verification, and Phase Completion Criteria sections matching the format above. +Use when implementation approach is Hybrid. Combine vertical and horizontal phases as defined in Design Doc implementation approach. Use the same per-phase section structure as Option A/B. ### Final Phase: Quality Assurance (Required) (Estimated commits: 1) @@ -229,7 +258,7 @@ This phase is required for ALL implementation approaches. - [ ] Quality checks (types, lint, format) - [ ] Execute all tests (including integration/E2E from test skeletons, when provided) - [ ] Project-configured coverage threshold passes; when none is configured, review the coverage report and add tests for uncovered changed behavior or record why another verification method is sufficient -- [ ] Document updates +- [ ] Documentation updates required by implementation outcomes are complete ### Quality Assurance - [ ] Quality check (staged) diff --git a/dev-workflows/skills/documentation-criteria/references/task-template.md b/dev-workflows/skills/documentation-criteria/references/task-template.md index 6d8833a..c6d7a6d 100644 --- a/dev-workflows/skills/documentation-criteria/references/task-template.md +++ b/dev-workflows/skills/documentation-criteria/references/task-template.md @@ -1,9 +1,12 @@ # Task: [Task Name] Metadata: +- Source Work Plan Task: [Phase X Task Y] - Dependencies: task-01 → Deliverable: docs/plans/analysis/research-results.md - Provides: docs/plans/analysis/api-spec.md (for research/design tasks) -- Size: Small (1-2 files) +- Implementation outcome: [Observable behavior, contract, migration, or downstream-consumable deliverable completed by this task] +- Rollback boundary: [Behavior, contract, migration, or persisted state reverted together] +- Executor lane: [backend | frontend] ## Implementation Content [What this task will achieve] @@ -23,10 +26,10 @@ Include this section only for constraints with a listed source. Before escalatio ## Investigation Targets Files to read before starting implementation (file path, with optional search hint): -- [e.g., src/orders/checkout (processOrder function) — determined during task decomposition based on task nature] +- [e.g., src/orders/checkout (processOrder function) — determined during task materialization based on task nature] ## Change Category -(Include this field only when the task is a bug fix, regression, state-change, or boundary-change — populated during task decomposition. Omit otherwise.) +(Include this field only when the task is a bug fix, regression, state-change, or boundary-change — populated during task materialization. Omit otherwise.) `Change Category: ` diff --git a/dev-workflows/skills/recipe-build/SKILL.md b/dev-workflows/skills/recipe-build/SKILL.md index e60a558..d52365a 100644 --- a/dev-workflows/skills/recipe-build/SKILL.md +++ b/dev-workflows/skills/recipe-build/SKILL.md @@ -1,6 +1,6 @@ --- name: recipe-build -description: Execute decomposed tasks in autonomous execution mode +description: Execute materialized task files in autonomous execution mode disable-model-invocation: true --- @@ -26,7 +26,7 @@ Work plan: $ARGUMENTS Before any task processing, locate the work plan. Resolution rule: 1. List task files in `docs/plans/tasks/` matching the single-layer pattern `{plan-name}-task-*.md`. Layer-aware fullstack tasks (`{plan-name}-backend-task-*.md` / `{plan-name}-frontend-task-*.md`) are excluded here so a stale fullstack run does not redirect this recipe to the wrong work plan -2. From the matched files, also exclude every file matching any of these patterns — they originate from other workflow phases and are not implementation tasks for this run's plan: `*-task-prep-*.md` (readiness preflight tasks), `_overview-*.md` (decomposition overview file), `*-phase*-completion.md` (per-phase completion files), `review-fixes-*.md` (post-implementation review fixes), `integration-tests-*-task-*.md` (integration-test add-on scaffolding) +2. From the matched files, also exclude every file matching any of these patterns — they originate from other workflow phases and are not implementation tasks for this run's plan: `*-task-prep-*.md` (readiness preflight tasks), `_overview-*.md` (materialization overview file), `*-phase*-completion.md` (per-phase completion files), `review-fixes-*.md` (post-implementation review fixes), `integration-tests-*-task-*.md` (integration-test add-on scaffolding) 3. For each remaining file, extract the `{plan-name}` prefix as the segment that appears before `-task-` 4. When at least one task file matches, the work plan is `docs/plans/{plan-name}.md` for the prefix that has the most recent task-file mtime; ties broken by the lexicographically last `{plan-name}` 5. When no task file matches the restricted pattern, the work plan is the most-recent-mtime non-template `.md` in `docs/plans/` @@ -48,10 +48,10 @@ Analyze the Consumed Task Set and determine the action required: |-------|----------|-------------| | Tasks exist | Consumed Task Set is non-empty | User's execution instruction serves as batch approval → Enter autonomous execution immediately | | No tasks + plan exists | Consumed Task Set is empty but the resolved work plan exists | Confirm with user → run task-decomposer | -| Neither exists + Design Doc exists | No plan, no Consumed Task Set, but `docs/design/*.md` exists | Invoke work-planner to create work plan from Design Doc, then run document-reviewer (`dev-workflows:document-reviewer`, doc_type: WorkPlan); branch on the reviewer's `verdict.decision` — on `needs_revision`, re-invoke work-planner (update) and re-review until `approved`/`approved_with_conditions`; if the same blocking finding repeats without new evidence or a contract change, stop and escalate it; then present the reviewed plan for batch approval before task decomposition; on `rejected`, stop before task decomposition and escalate to the user | +| Neither exists + Design Doc exists | No plan, no Consumed Task Set, but `docs/design/*.md` exists | Invoke work-planner to create work plan from Design Doc, then run document-reviewer (`dev-workflows:document-reviewer`, doc_type: WorkPlan); branch on the reviewer's `verdict.decision` — on `needs_revision`, re-invoke work-planner (update) and re-review until `approved`/`approved_with_conditions`; if the same blocking finding repeats without new evidence or a contract change, stop and escalate it; then present the reviewed plan for batch approval before task materialization; on `rejected`, stop before task materialization and escalate to the user | | Neither exists | No plan, no Consumed Task Set, no Design Doc | Report missing prerequisites to user and stop | -## Task Decomposition Phase (Conditional) +## Task Materialization Phase (Conditional) When the Consumed Task Set is empty: @@ -63,11 +63,11 @@ Work plan: docs/plans/[plan-name].md Generate tasks from the work plan? (y/n): ``` -### 2. Task Decomposition (if approved) +### 2. Task Materialization (if approved) Invoke task-decomposer using Agent tool: - `subagent_type`: "dev-workflows:task-decomposer" -- `description`: "Decompose work plan" -- `prompt`: "Read work plan at docs/plans/[plan-name].md and decompose into atomic tasks. Output: Individual task files in docs/plans/tasks/. Granularity: 1 task = 1 commit = independently executable" +- `description`: "Materialize work plan tasks" +- `prompt`: "Read work plan at docs/plans/[plan-name].md and output individual single-commit task files in docs/plans/tasks/." ### 3. Verify Generation Recompute the Consumed Task Set using the same restricted pattern from the Consumed Task Set section above. Confirm it is now non-empty. If it is still empty, escalate to the user — task-decomposer either failed silently or produced files that don't match the expected pattern. @@ -141,7 +141,7 @@ If task files cannot be deleted (filesystem error), report the failure but do no ## Completion Report Contract Final report must include: -- Task decomposition status +- Task materialization status - Implemented task count - Quality check result - Commit count diff --git a/dev-workflows/skills/recipe-prepare-implementation/SKILL.md b/dev-workflows/skills/recipe-prepare-implementation/SKILL.md index 0e0d55a..acac374 100644 --- a/dev-workflows/skills/recipe-prepare-implementation/SKILL.md +++ b/dev-workflows/skills/recipe-prepare-implementation/SKILL.md @@ -52,7 +52,7 @@ R4 and R5 are evaluated only when their triggering signals appear in the work pl **State check**: - Work plan exists → Proceed to Step 1 -- No work plan → Stop and report: "An approved work plan is required. Complete the upstream planning phase first, then re-invoke this recipe." +- No work plan → Stop and report: "A work plan is required. Complete the upstream planning phase first, then re-invoke this recipe." ## Execution Flow diff --git a/dev-workflows/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows/skills/subagents-orchestration-guide/SKILL.md index cefbd53..7eaf34a 100644 --- a/dev-workflows/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows/skills/subagents-orchestration-guide/SKILL.md @@ -245,7 +245,7 @@ After "batch approval for entire implementation phase" with work-planner, autono ```mermaid graph TD START[Batch approval for entire implementation phase] --> AUTO[Start autonomous execution mode] - AUTO --> TD[task-decomposer: Task decomposition] + AUTO --> TD[task-decomposer: Task materialization] TD --> LOOP[Task execution loop] LOOP --> TE[task-executor: Implementation] TE --> ESCJUDGE{Escalation judgment} diff --git a/dev-workflows/skills/subagents-orchestration-guide/references/monorepo-flow.md b/dev-workflows/skills/subagents-orchestration-guide/references/monorepo-flow.md index f51fa3c..74a52d2 100644 --- a/dev-workflows/skills/subagents-orchestration-guide/references/monorepo-flow.md +++ b/dev-workflows/skills/subagents-orchestration-guide/references/monorepo-flow.md @@ -119,16 +119,16 @@ work-planner's existing Integration Complete criteria naturally covers cross-lay For Medium and Large flows, pass the resulting Work Plan to document-reviewer with `doc_type: WorkPlan`. On `needs_revision`, route the findings to work-planner in update mode and re-review. If the same blocking finding repeats and the update supplies no new evidence or contract change, stop and escalate instead of repeating the loop. Request batch approval only after the review is `approved` or `approved_with_conditions`; escalate `rejected` to the user. -## Task Decomposition Phase +## Task Materialization Phase -task-decomposer follows standard decomposition from the work plan. The key addition is the **layer-aware naming convention**: +task-decomposer materializes each Work Plan implementation item as one task file. The key addition is the **layer-aware naming convention**: | Filename Pattern | Meaning | Executor | Quality Fixer | |-----------------|---------|----------|---------------| | `{plan}-backend-task-{n}.md` | Backend only | task-executor | quality-fixer | | `{plan}-frontend-task-{n}.md` | Frontend only | task-executor-frontend | quality-fixer-frontend | -Layer is determined from the task's **Target files** paths — this is a factual determination, not inference. +Layer is selected from the Work Plan item's **Executor lane**. Target Files and the filename segment must agree with that copied value. ## Task Cycle diff --git a/package.json b/package.json index 3a2660b..8b8a050 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "claude-code-workflows", - "version": "0.22.8", + "version": "0.22.9", "private": true, "type": "module", "engines": { diff --git a/skills/documentation-criteria/references/plan-template.md b/skills/documentation-criteria/references/plan-template.md index 27c67c6..09c3a1e 100644 --- a/skills/documentation-criteria/references/plan-template.md +++ b/skills/documentation-criteria/references/plan-template.md @@ -140,6 +140,15 @@ For a serialized boundary, fill Serialized Format and Consumer Parse Rule. Set t Select ONE phase structure based on implementation approach from Design Doc. Phase Division Criteria are defined alongside this template. Per-phase quality checks run lint, typecheck, tests, build, and any adopted QA mechanisms from the Design Doc. +Each `Phase X Task Y` checkbox entry in a non-QA phase's `Tasks` section is one Work Plan implementation item. The ID is the stable key used by every `Covered By Task(s)` column. + +- [ ] Phase X Task Y: [Observable behavior, contract, migration, or downstream-consumable deliverable completed by this item] + - **Target Files**: [Concrete planned paths or path prefixes] + - **Rollback boundary**: [Behavior, contract, migration, or persisted state reverted together] + - **Executor lane**: [backend | frontend] + +Add one entry per implementation outcome. Create separate entries whenever the implementation outcome, rollback boundary, or executor lane differs. Select exactly one executor lane. Keep wiring or registration, tests, generated artifacts, and user documentation in the entry whose outcome they complete or prove. Record staged checks outside the `Tasks` section; they are phase checks rather than implementation items. + ### Option A: Vertical Slice Phase Structure Use when implementation approach is Vertical Slice. Each phase = one value unit with verification. @@ -149,8 +158,12 @@ Use when implementation approach is Vertical Slice. Each phase = one value unit **Verification**: [From Verification Strategy: early verification point] #### Tasks -- [ ] Task 1: Implementation -- [ ] Task 2: Verification per Verification Strategy +- [ ] Phase 1 Task 1: [First value unit, including its wiring and verification] + - **Target Files**: [path(s)] + - **Rollback boundary**: [changes reverted together] + - **Executor lane**: [backend | frontend] + +#### Phase Checks - [ ] Quality check (staged) #### Phase Completion Criteria @@ -162,8 +175,12 @@ Use when implementation approach is Vertical Slice. Each phase = one value unit **Verification**: [From Verification Strategy] #### Tasks -- [ ] Task 1: Implementation -- [ ] Task 2: Verification per Verification Strategy +- [ ] Phase 2 Task 1: [Subsequent value unit, including its wiring and verification] + - **Target Files**: [path(s)] + - **Rollback boundary**: [changes reverted together] + - **Executor lane**: [backend | frontend] + +#### Phase Checks - [ ] Quality check #### Phase Completion Criteria @@ -178,44 +195,56 @@ Use when implementation approach is Horizontal Slice. Phases follow Foundation **Purpose**: Contract definitions, interfaces, test preparation #### Tasks -- [ ] Task 1: Specific work content -- [ ] Task 2: Specific work content +- [ ] Phase 1 Task 1: [Foundation outcome and its verification] + - **Target Files**: [path(s)] + - **Rollback boundary**: [changes reverted together] + - **Executor lane**: [backend | frontend] + +#### Phase Checks - [ ] Quality check (staged) -- [ ] Unit tests: All related tests pass #### Phase Completion Criteria - [ ] [Functional completion criteria] +- [ ] All related unit tests pass - [ ] [Quality completion criteria] ### Phase 2: [Core Feature] (Estimated commits: X) **Purpose**: Business logic, unit tests #### Tasks -- [ ] Task 1: Specific work content -- [ ] Task 2: Specific work content +- [ ] Phase 2 Task 1: [Core feature outcome and its verification] + - **Target Files**: [path(s)] + - **Rollback boundary**: [changes reverted together] + - **Executor lane**: [backend | frontend] + +#### Phase Checks - [ ] Quality check (staged) -- [ ] Integration tests: Verify overall feature functionality #### Phase Completion Criteria - [ ] [Functional completion criteria] +- [ ] Integration tests verify overall feature functionality - [ ] [Quality completion criteria] ### Phase 3: [Integration] (Estimated commits: X) **Purpose**: External connections, presentation layer #### Tasks -- [ ] Task 1: Specific work content -- [ ] Task 2: Specific work content +- [ ] Phase 3 Task 1: [Integration outcome and its verification] + - **Target Files**: [path(s)] + - **Rollback boundary**: [changes reverted together] + - **Executor lane**: [backend | frontend] + +#### Phase Checks - [ ] Quality check -- [ ] Integration tests: Verify component coordination #### Phase Completion Criteria - [ ] [Functional completion criteria] +- [ ] Integration tests verify component coordination - [ ] [Quality completion criteria] ### Option C: Hybrid Phase Structure -Use when implementation approach is Hybrid. Combine vertical and horizontal phases as defined in Design Doc implementation approach. Structure phases per Design Doc specification, ensuring each phase has Tasks, Verification, and Phase Completion Criteria sections matching the format above. +Use when implementation approach is Hybrid. Combine vertical and horizontal phases as defined in Design Doc implementation approach. Use the same per-phase section structure as Option A/B. ### Final Phase: Quality Assurance (Required) (Estimated commits: 1) @@ -229,7 +258,7 @@ This phase is required for ALL implementation approaches. - [ ] Quality checks (types, lint, format) - [ ] Execute all tests (including integration/E2E from test skeletons, when provided) - [ ] Project-configured coverage threshold passes; when none is configured, review the coverage report and add tests for uncovered changed behavior or record why another verification method is sufficient -- [ ] Document updates +- [ ] Documentation updates required by implementation outcomes are complete ### Quality Assurance - [ ] Quality check (staged) diff --git a/skills/documentation-criteria/references/task-template.md b/skills/documentation-criteria/references/task-template.md index 6d8833a..c6d7a6d 100644 --- a/skills/documentation-criteria/references/task-template.md +++ b/skills/documentation-criteria/references/task-template.md @@ -1,9 +1,12 @@ # Task: [Task Name] Metadata: +- Source Work Plan Task: [Phase X Task Y] - Dependencies: task-01 → Deliverable: docs/plans/analysis/research-results.md - Provides: docs/plans/analysis/api-spec.md (for research/design tasks) -- Size: Small (1-2 files) +- Implementation outcome: [Observable behavior, contract, migration, or downstream-consumable deliverable completed by this task] +- Rollback boundary: [Behavior, contract, migration, or persisted state reverted together] +- Executor lane: [backend | frontend] ## Implementation Content [What this task will achieve] @@ -23,10 +26,10 @@ Include this section only for constraints with a listed source. Before escalatio ## Investigation Targets Files to read before starting implementation (file path, with optional search hint): -- [e.g., src/orders/checkout (processOrder function) — determined during task decomposition based on task nature] +- [e.g., src/orders/checkout (processOrder function) — determined during task materialization based on task nature] ## Change Category -(Include this field only when the task is a bug fix, regression, state-change, or boundary-change — populated during task decomposition. Omit otherwise.) +(Include this field only when the task is a bug fix, regression, state-change, or boundary-change — populated during task materialization. Omit otherwise.) `Change Category: ` diff --git a/skills/recipe-build/SKILL.md b/skills/recipe-build/SKILL.md index e60a558..d52365a 100644 --- a/skills/recipe-build/SKILL.md +++ b/skills/recipe-build/SKILL.md @@ -1,6 +1,6 @@ --- name: recipe-build -description: Execute decomposed tasks in autonomous execution mode +description: Execute materialized task files in autonomous execution mode disable-model-invocation: true --- @@ -26,7 +26,7 @@ Work plan: $ARGUMENTS Before any task processing, locate the work plan. Resolution rule: 1. List task files in `docs/plans/tasks/` matching the single-layer pattern `{plan-name}-task-*.md`. Layer-aware fullstack tasks (`{plan-name}-backend-task-*.md` / `{plan-name}-frontend-task-*.md`) are excluded here so a stale fullstack run does not redirect this recipe to the wrong work plan -2. From the matched files, also exclude every file matching any of these patterns — they originate from other workflow phases and are not implementation tasks for this run's plan: `*-task-prep-*.md` (readiness preflight tasks), `_overview-*.md` (decomposition overview file), `*-phase*-completion.md` (per-phase completion files), `review-fixes-*.md` (post-implementation review fixes), `integration-tests-*-task-*.md` (integration-test add-on scaffolding) +2. From the matched files, also exclude every file matching any of these patterns — they originate from other workflow phases and are not implementation tasks for this run's plan: `*-task-prep-*.md` (readiness preflight tasks), `_overview-*.md` (materialization overview file), `*-phase*-completion.md` (per-phase completion files), `review-fixes-*.md` (post-implementation review fixes), `integration-tests-*-task-*.md` (integration-test add-on scaffolding) 3. For each remaining file, extract the `{plan-name}` prefix as the segment that appears before `-task-` 4. When at least one task file matches, the work plan is `docs/plans/{plan-name}.md` for the prefix that has the most recent task-file mtime; ties broken by the lexicographically last `{plan-name}` 5. When no task file matches the restricted pattern, the work plan is the most-recent-mtime non-template `.md` in `docs/plans/` @@ -48,10 +48,10 @@ Analyze the Consumed Task Set and determine the action required: |-------|----------|-------------| | Tasks exist | Consumed Task Set is non-empty | User's execution instruction serves as batch approval → Enter autonomous execution immediately | | No tasks + plan exists | Consumed Task Set is empty but the resolved work plan exists | Confirm with user → run task-decomposer | -| Neither exists + Design Doc exists | No plan, no Consumed Task Set, but `docs/design/*.md` exists | Invoke work-planner to create work plan from Design Doc, then run document-reviewer (`dev-workflows:document-reviewer`, doc_type: WorkPlan); branch on the reviewer's `verdict.decision` — on `needs_revision`, re-invoke work-planner (update) and re-review until `approved`/`approved_with_conditions`; if the same blocking finding repeats without new evidence or a contract change, stop and escalate it; then present the reviewed plan for batch approval before task decomposition; on `rejected`, stop before task decomposition and escalate to the user | +| Neither exists + Design Doc exists | No plan, no Consumed Task Set, but `docs/design/*.md` exists | Invoke work-planner to create work plan from Design Doc, then run document-reviewer (`dev-workflows:document-reviewer`, doc_type: WorkPlan); branch on the reviewer's `verdict.decision` — on `needs_revision`, re-invoke work-planner (update) and re-review until `approved`/`approved_with_conditions`; if the same blocking finding repeats without new evidence or a contract change, stop and escalate it; then present the reviewed plan for batch approval before task materialization; on `rejected`, stop before task materialization and escalate to the user | | Neither exists | No plan, no Consumed Task Set, no Design Doc | Report missing prerequisites to user and stop | -## Task Decomposition Phase (Conditional) +## Task Materialization Phase (Conditional) When the Consumed Task Set is empty: @@ -63,11 +63,11 @@ Work plan: docs/plans/[plan-name].md Generate tasks from the work plan? (y/n): ``` -### 2. Task Decomposition (if approved) +### 2. Task Materialization (if approved) Invoke task-decomposer using Agent tool: - `subagent_type`: "dev-workflows:task-decomposer" -- `description`: "Decompose work plan" -- `prompt`: "Read work plan at docs/plans/[plan-name].md and decompose into atomic tasks. Output: Individual task files in docs/plans/tasks/. Granularity: 1 task = 1 commit = independently executable" +- `description`: "Materialize work plan tasks" +- `prompt`: "Read work plan at docs/plans/[plan-name].md and output individual single-commit task files in docs/plans/tasks/." ### 3. Verify Generation Recompute the Consumed Task Set using the same restricted pattern from the Consumed Task Set section above. Confirm it is now non-empty. If it is still empty, escalate to the user — task-decomposer either failed silently or produced files that don't match the expected pattern. @@ -141,7 +141,7 @@ If task files cannot be deleted (filesystem error), report the failure but do no ## Completion Report Contract Final report must include: -- Task decomposition status +- Task materialization status - Implemented task count - Quality check result - Commit count diff --git a/skills/recipe-front-build/SKILL.md b/skills/recipe-front-build/SKILL.md index 3566d9f..5c52651 100644 --- a/skills/recipe-front-build/SKILL.md +++ b/skills/recipe-front-build/SKILL.md @@ -1,6 +1,6 @@ --- name: recipe-front-build -description: Execute frontend implementation in autonomous execution mode +description: Execute materialized frontend task files in autonomous execution mode disable-model-invocation: true --- @@ -26,7 +26,7 @@ Work plan: $ARGUMENTS Before any task processing, locate the work plan. Resolution rule: 1. List task files in `docs/plans/tasks/` matching the single-layer pattern `{plan-name}-task-*.md`. Layer-aware fullstack tasks (`{plan-name}-backend-task-*.md` / `{plan-name}-frontend-task-*.md`) are excluded here so a stale fullstack run does not redirect this recipe to the wrong work plan -2. From the matched files, also exclude every file matching any of these patterns — they originate from other workflow phases and are not implementation tasks for this run's plan: `*-task-prep-*.md` (readiness preflight tasks), `_overview-*.md` (decomposition overview file), `*-phase*-completion.md` (per-phase completion files), `review-fixes-*.md` (post-implementation review fixes), `integration-tests-*-task-*.md` (integration-test add-on scaffolding) +2. From the matched files, also exclude every file matching any of these patterns — they originate from other workflow phases and are not implementation tasks for this run's plan: `*-task-prep-*.md` (readiness preflight tasks), `_overview-*.md` (materialization overview file), `*-phase*-completion.md` (per-phase completion files), `review-fixes-*.md` (post-implementation review fixes), `integration-tests-*-task-*.md` (integration-test add-on scaffolding) 3. For each remaining file, extract the `{plan-name}` prefix as the segment that appears before `-task-` 4. When at least one task file matches, the work plan is `docs/plans/{plan-name}.md` for the prefix that has the most recent task-file mtime; ties broken by the lexicographically last `{plan-name}` 5. When no task file matches the restricted pattern, the work plan is the most-recent-mtime non-template `.md` in `docs/plans/` @@ -48,10 +48,10 @@ Analyze the Consumed Task Set and determine the action required: |-------|----------|-------------| | Tasks exist | Consumed Task Set is non-empty | User's execution instruction serves as batch approval → Enter autonomous execution immediately | | No tasks + plan exists | Consumed Task Set is empty but the resolved work plan exists | Confirm with user → run task-decomposer | -| Neither exists + Design Doc exists | No plan, no Consumed Task Set, but `docs/design/*.md` exists | Invoke work-planner to create work plan from Design Doc, then run document-reviewer (`dev-workflows-frontend:document-reviewer`, doc_type: WorkPlan); branch on the reviewer's `verdict.decision` — on `needs_revision`, re-invoke work-planner (update) and re-review until `approved`/`approved_with_conditions`; if the same blocking finding repeats without new evidence or a contract change, stop and escalate it; then present the reviewed plan for batch approval before task decomposition; on `rejected`, stop before task decomposition and escalate to the user | +| Neither exists + Design Doc exists | No plan, no Consumed Task Set, but `docs/design/*.md` exists | Invoke work-planner to create work plan from Design Doc, then run document-reviewer (`dev-workflows-frontend:document-reviewer`, doc_type: WorkPlan); branch on the reviewer's `verdict.decision` — on `needs_revision`, re-invoke work-planner (update) and re-review until `approved`/`approved_with_conditions`; if the same blocking finding repeats without new evidence or a contract change, stop and escalate it; then present the reviewed plan for batch approval before task materialization; on `rejected`, stop before task materialization and escalate to the user | | Neither exists | No plan, no Consumed Task Set, no Design Doc | Report missing prerequisites to user and stop | -## Task Decomposition Phase (Conditional) +## Task Materialization Phase (Conditional) When the Consumed Task Set is empty: @@ -63,11 +63,11 @@ Work plan: docs/plans/[plan-name].md Generate tasks from the work plan? (y/n): ``` -### 2. Task Decomposition (if approved) +### 2. Task Materialization (if approved) Invoke task-decomposer using Agent tool: - `subagent_type`: "dev-workflows-frontend:task-decomposer" -- `description`: "Decompose work plan" -- `prompt`: "Read work plan at docs/plans/[plan-name].md and decompose into atomic tasks. Output: Individual task files in docs/plans/tasks/. Granularity: 1 task = 1 commit = independently executable" +- `description`: "Materialize work plan tasks" +- `prompt`: "Read work plan at docs/plans/[plan-name].md and output individual single-commit task files in docs/plans/tasks/." ### 3. Verify Generation Recompute the Consumed Task Set using the same restricted pattern from the Consumed Task Set section above. Confirm it is now non-empty. If it is still empty, escalate to the user — task-decomposer either failed silently or produced files that don't match the expected pattern. @@ -141,7 +141,7 @@ If task files cannot be deleted (filesystem error), report the failure but do no ## Completion Report Contract Final report must include: -- Task decomposition status +- Task materialization status - Implemented task count - Quality check result - Commit count diff --git a/skills/recipe-fullstack-build/SKILL.md b/skills/recipe-fullstack-build/SKILL.md index 69d402b..84a64aa 100644 --- a/skills/recipe-fullstack-build/SKILL.md +++ b/skills/recipe-fullstack-build/SKILL.md @@ -1,6 +1,6 @@ --- name: recipe-fullstack-build -description: Execute decomposed fullstack tasks with layer-aware agent routing +description: Execute materialized fullstack task files with layer-aware agent routing disable-model-invocation: true --- @@ -34,7 +34,7 @@ Work plan: $ARGUMENTS Before any task processing, locate the work plan. Resolution rule: 1. List task files in `docs/plans/tasks/` matching the layer-aware patterns `{plan-name}-backend-task-*.md` and `{plan-name}-frontend-task-*.md` only. Single-layer tasks (`{plan-name}-task-*.md`) are excluded here so a stale single-layer run does not redirect this recipe to the wrong work plan -2. From the matched files, also exclude every file matching any of these patterns — they originate from other workflow phases and are not implementation tasks for this run's plan: `*-task-prep-*.md` (readiness preflight tasks), `_overview-*.md` (decomposition overview file), `*-phase*-completion.md` (per-phase completion files), `review-fixes-*.md` (post-implementation review fixes), `integration-tests-*-task-*.md` (integration-test add-on scaffolding) +2. From the matched files, also exclude every file matching any of these patterns — they originate from other workflow phases and are not implementation tasks for this run's plan: `*-task-prep-*.md` (readiness preflight tasks), `_overview-*.md` (materialization overview file), `*-phase*-completion.md` (per-phase completion files), `review-fixes-*.md` (post-implementation review fixes), `integration-tests-*-task-*.md` (integration-test add-on scaffolding) 3. For each remaining file, extract the `{plan-name}` prefix as the segment that appears before `-backend-task-` or `-frontend-task-` 4. When at least one task file matches, the work plan is `docs/plans/{plan-name}.md` for the prefix that has the most recent task-file mtime; ties broken by the lexicographically last `{plan-name}` 5. When no task file matches the restricted pattern, the work plan is the most-recent-mtime non-template `.md` in `docs/plans/` @@ -56,10 +56,10 @@ Analyze the Consumed Task Set and determine the action required: |-------|----------|-------------| | Tasks exist | Consumed Task Set is non-empty | User's execution instruction serves as batch approval → Enter autonomous execution immediately | | No tasks + plan exists | Consumed Task Set is empty but the resolved work plan exists | Confirm with user → run task-decomposer | -| Neither exists + Design Doc exists | No plan, no Consumed Task Set, but `docs/design/*.md` exists | Invoke work-planner to create work plan from Design Doc(s), then run document-reviewer (`dev-workflows:document-reviewer`, doc_type: WorkPlan); branch on the reviewer's `verdict.decision` — on `needs_revision`, re-invoke work-planner (update) and re-review until `approved`/`approved_with_conditions`; if the same blocking finding repeats without new evidence or a contract change, stop and escalate it; then present the reviewed plan for batch approval before task decomposition; on `rejected`, stop before task decomposition and escalate to the user | +| Neither exists + Design Doc exists | No plan, no Consumed Task Set, but `docs/design/*.md` exists | Invoke work-planner to create work plan from Design Doc(s), then run document-reviewer (`dev-workflows:document-reviewer`, doc_type: WorkPlan); branch on the reviewer's `verdict.decision` — on `needs_revision`, re-invoke work-planner (update) and re-review until `approved`/`approved_with_conditions`; if the same blocking finding repeats without new evidence or a contract change, stop and escalate it; then present the reviewed plan for batch approval before task materialization; on `rejected`, stop before task materialization and escalate to the user | | Neither exists | No plan, no Consumed Task Set, no Design Doc | Report missing prerequisites to user and stop | -## Task Decomposition Phase (Conditional) +## Task Materialization Phase (Conditional) When the Consumed Task Set is empty: @@ -71,11 +71,11 @@ Work plan: docs/plans/[plan-name].md Generate tasks from the work plan? (y/n): ``` -### 2. Task Decomposition (if approved) +### 2. Task Materialization (if approved) Invoke task-decomposer using Agent tool: - `subagent_type`: "dev-workflows:task-decomposer" -- `description`: "Decompose work plan" -- `prompt`: "Read work plan at docs/plans/[plan-name].md and decompose into atomic tasks. Output: Individual task files in docs/plans/tasks/. Granularity: 1 task = 1 commit = independently executable. Use layer-aware naming: {plan}-backend-task-{n}.md, {plan}-frontend-task-{n}.md based on Target files paths." +- `description`: "Materialize work plan tasks" +- `prompt`: "Read work plan at docs/plans/[plan-name].md and output individual single-commit task files in docs/plans/tasks/. Use layer-aware naming: {plan}-backend-task-{n}.md, {plan}-frontend-task-{n}.md from each Work Plan task's Executor lane." ### 3. Verify Generation Recompute the Consumed Task Set using the same restricted pattern from the Consumed Task Set section above. Confirm it is now non-empty. If it is still empty, escalate to the user — task-decomposer either failed silently or produced files that don't match the expected pattern. @@ -159,7 +159,7 @@ If task files cannot be deleted (filesystem error), report the failure but do no ## Completion Report Contract Final report must include: -- Task decomposition status +- Task materialization status - Implemented task count, including backend/frontend counts - Quality check result - Commit count diff --git a/skills/recipe-prepare-implementation/SKILL.md b/skills/recipe-prepare-implementation/SKILL.md index 0e0d55a..acac374 100644 --- a/skills/recipe-prepare-implementation/SKILL.md +++ b/skills/recipe-prepare-implementation/SKILL.md @@ -52,7 +52,7 @@ R4 and R5 are evaluated only when their triggering signals appear in the work pl **State check**: - Work plan exists → Proceed to Step 1 -- No work plan → Stop and report: "An approved work plan is required. Complete the upstream planning phase first, then re-invoke this recipe." +- No work plan → Stop and report: "A work plan is required. Complete the upstream planning phase first, then re-invoke this recipe." ## Execution Flow diff --git a/skills/subagents-orchestration-guide/SKILL.md b/skills/subagents-orchestration-guide/SKILL.md index cefbd53..7eaf34a 100644 --- a/skills/subagents-orchestration-guide/SKILL.md +++ b/skills/subagents-orchestration-guide/SKILL.md @@ -245,7 +245,7 @@ After "batch approval for entire implementation phase" with work-planner, autono ```mermaid graph TD START[Batch approval for entire implementation phase] --> AUTO[Start autonomous execution mode] - AUTO --> TD[task-decomposer: Task decomposition] + AUTO --> TD[task-decomposer: Task materialization] TD --> LOOP[Task execution loop] LOOP --> TE[task-executor: Implementation] TE --> ESCJUDGE{Escalation judgment} diff --git a/skills/subagents-orchestration-guide/references/monorepo-flow.md b/skills/subagents-orchestration-guide/references/monorepo-flow.md index f51fa3c..74a52d2 100644 --- a/skills/subagents-orchestration-guide/references/monorepo-flow.md +++ b/skills/subagents-orchestration-guide/references/monorepo-flow.md @@ -119,16 +119,16 @@ work-planner's existing Integration Complete criteria naturally covers cross-lay For Medium and Large flows, pass the resulting Work Plan to document-reviewer with `doc_type: WorkPlan`. On `needs_revision`, route the findings to work-planner in update mode and re-review. If the same blocking finding repeats and the update supplies no new evidence or contract change, stop and escalate instead of repeating the loop. Request batch approval only after the review is `approved` or `approved_with_conditions`; escalate `rejected` to the user. -## Task Decomposition Phase +## Task Materialization Phase -task-decomposer follows standard decomposition from the work plan. The key addition is the **layer-aware naming convention**: +task-decomposer materializes each Work Plan implementation item as one task file. The key addition is the **layer-aware naming convention**: | Filename Pattern | Meaning | Executor | Quality Fixer | |-----------------|---------|----------|---------------| | `{plan}-backend-task-{n}.md` | Backend only | task-executor | quality-fixer | | `{plan}-frontend-task-{n}.md` | Frontend only | task-executor-frontend | quality-fixer-frontend | -Layer is determined from the task's **Target files** paths — this is a factual determination, not inference. +Layer is selected from the Work Plan item's **Executor lane**. Target Files and the filename segment must agree with that copied value. ## Task Cycle