diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 3ab977b..58c7738 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.19.1", + "version": "0.19.2", "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", @@ -83,7 +83,7 @@ "name": "dev-workflows-frontend", "source": "./dev-workflows-frontend", "strict": true, - "version": "0.19.1", + "version": "0.19.2", "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.19.1", + "version": "0.19.2", "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", @@ -242,7 +242,7 @@ "name": "dev-skills", "source": "./dev-skills", "strict": true, - "version": "0.19.1", + "version": "0.19.2", "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 aeff0d1..a385d3a 100644 --- a/agents/task-decomposer.md +++ b/agents/task-decomposer.md @@ -112,6 +112,7 @@ Decompose tasks based on implementation strategy patterns determined in implemen | Cross-package boundary implementation | Both sides of the boundary as listed in the work plan's Connection Map (owner modules and expected signal), the contract definition between them | | Bug fix / refactor | The affected code paths, related test coverage, error reproduction context | | Behavior replacement / rewrite | The existing implementation being replaced, its observable outputs, Design Doc Verification Strategy section | + | Task constrained by an ADR (work plan's ADR Bindings table covers this task) | The ADR file with section hint matching the row's `Source Section` value (e.g., `(§ Decision)` or `(§ Implementation Guidance)`) for each binding row covering this task | **Principles**: - Every task must have at least one Investigation Target (even if just the Design Doc) @@ -121,6 +122,8 @@ Decompose tasks based on implementation strategy patterns determined in implemen - When test skeletons exist for the task, always include them as Investigation Targets - When the work plan contains a UI Spec Component → Task Mapping table, propagate the matching component section to every task in that row (see UI Spec Propagation below) - When the work plan contains a Connection Map, propagate the boundary rows touching this task's target files (see Connection Map Propagation below) + - When the work plan contains an ADR Bindings table covering this task, propagate the matching rows (see ADR Binding Propagation below) + - When the work plan contains a Design-to-Plan Traceability table, propagate the matching DD section rows (see Design Traceability Propagation below) 7. **Implementation Pattern Consistency** When including implementation samples, MUST ensure strict compliance with the Design Doc implementation approach that forms the basis of the work plan @@ -173,6 +176,34 @@ When the work plan contains a Connection Map table, propagate boundary context t 3. **Add a "Boundary Context" note in the task body**: Record the boundary identifier and expected signal verbatim from the Connection Map row, so the executor knows what observable evidence the implementation must produce 4. **Skip when not provided**: If the work plan has no Connection Map, skip this propagation step +## ADR Binding Propagation + +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 +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 + - **Axis**: Copy the row's `Axis` value verbatim from the work plan row + - **Decision**: Copy the binding decision sentence verbatim from the work plan row + - **Compliance Check**: Write a Y/N-answerable positive predicate stating that the implementation satisfies the decision. One example per binding axis: + - `placement`: "Auth entrypoint is in `src/middleware/**`" + - `dependency_direction`: "The domain layer imports only from `src/domain/**` and `src/shared/**`" + - `contract_schema`: "API responses match the `ResponseEnvelope` schema" + - `data_flow`: "Session tokens are written exclusively through the Redis client" + - `persistence`: "User records are persisted only via the `UsersRepository` interface" + + When the decision cannot be verified by file:line or command alone, the predicate may rely on reasoned judgment, but it must remain Y/N-answerable +4. **Apply only when provided**: Run this propagation only when the work plan contains an ADR Bindings table + +## Design Traceability Propagation + +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])` +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 + ## Task File Template See task template in documentation-criteria skill for details. @@ -274,6 +305,11 @@ Please execute decomposed tasks according to the order. - [ ] Quality Assurance Mechanisms from work plan header propagated to relevant tasks - [ ] UI Spec Component → Task Mapping rows propagated to matching tasks (when work plan has the table) - [ ] Connection Map boundary rows propagated to matching tasks (when work plan has the table) +- [ ] Design-to-Plan Traceability rows propagated to matching tasks as Investigation Targets (when work plan has the table) +- [ ] ADR Bindings rows propagated to matching tasks as Binding Decisions (when work plan has the table) + - [ ] Source includes ADR path with section hint + - [ ] Axis copied verbatim from the work plan row to the task's Binding Decisions table + - [ ] 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) diff --git a/agents/task-executor-frontend.md b/agents/task-executor-frontend.md index 2c47ae3..4aae2d1 100644 --- a/agents/task-executor-frontend.md +++ b/agents/task-executor-frontend.md @@ -104,22 +104,11 @@ Use the appropriate run command based on the `packageManager` field in package.j - Type guard usage from unknown→concrete type (for external API responses) - Minor UI adjustments, message text changes -## Implementation Authority and Responsibility Boundaries +## Responsibility Boundaries -**Responsibility Scope**: React component implementation and test creation (quality checks and commits out of scope) -**Basic Policy**: Start implementation immediately (assuming approved), escalate only for design deviation or shortcut fixes - -## Main Responsibilities - -1. **Task Execution** - - Read and execute task files from `docs/plans/tasks/` - - Review dependency deliverables listed in task "Metadata" - - Meet all completion criteria - -2. **Progress Management (3-location synchronized updates)** - - Checkboxes within task files - - Checkboxes and progress records in work plan documents - - States: `[ ]` not started → `[🔄]` in progress → `[x]` completed +**Scope**: React component implementation and test creation. Quality checks and commits are handled by other agents. +**Policy**: Start implementation immediately (treat as approved); escalate only on design deviation or shortcut fixes. +**Progress**: Sync checkbox state across task file, work plan, and overall design document (`[ ]` → `[🔄]` → `[x]`). ## Workflow @@ -172,6 +161,18 @@ This gate runs only when the task file's "Investigation Targets" section lists a 2. **Investigate existing implementations**: Search for similar components/hooks in same domain/responsibility 3. **Execute determination**: Determine continue/escalation per "Mandatory Judgment Criteria" above +#### Binding Decision Check (Required when the task file has a Binding Decisions section) + +This check runs after Pre-implementation Verification and before the TDD cycle. It applies only when the task file contains a Binding Decisions section with one or more rows. + +1. Confirm each Source in the Binding Decisions table has been read (Sources are also listed in Investigation Targets and were read at Step 2) +2. Record the planned implementation approach in Investigation Notes — one sentence per distinct `Axis` value present in the task's Binding Decisions table. When multiple rows share the same `Axis` value, group them and record one sentence covering the group +3. Evaluate each row's Compliance Check against the planned approach. Record the result for each row as `Y`, `N`, or `Unknown` in Investigation Notes, with a one-line rationale. Use `Unknown` only when the planned approach has no decision yet on the predicate's subject; if the planning is complete, the answer is `Y` or `N` +4. Per row, branch on the evaluation: + - `Y`: proceed + - `N`: stop implementation and produce the final response with `status: "escalation_needed"` and `escalation_type: "binding_decision_violation"` with `phase: "pre_implementation"` (see Binding Decision Violation Escalation in Structured Response Specification). `N` represents a planned violation + - `Unknown`: mark the row as deferred in Investigation Notes and proceed to the TDD cycle. The Exit Gate re-evaluates every row (including Unknown rows deferred from this step) against the final implementation and escalates if any remains `N` or `Unknown` at that point + #### Implementation Flow (TDD Compliant) **Completion Confirmation**: If all checkboxes are `[x]`, report "already completed" and end @@ -180,11 +181,7 @@ This gate runs only when the task file's "Investigation Targets" section lists a ※For integration tests (multiple components), create and execute simultaneously with implementation; E2E tests are executed in final phase only 2. **Green**: Implement minimum code to pass test (React function component) 3. **Refactor**: Improve code quality (readability, maintainability, React best practices) -4. **Progress Update [MANDATORY]**: Execute the following in sequence (cannot be omitted) - 4-1. **Task file**: Change completed item from `[ ]` → `[x]` - 4-2. **Work plan**: Change same item from `[ ]` → `[x]` in corresponding plan in docs/plans/ - 4-3. **Overall design document**: Update corresponding item in progress section if exists - ※After each Edit tool execution, proceed to next step +4. **Progress Update [MANDATORY]**: After each checkbox completes, set `[ ]` → `[x]` in (a) task file, (b) work plan in docs/plans/, (c) overall design document if present 5. **Test Execution**: Run only created tests and confirm they pass #### Operation Verification @@ -199,14 +196,7 @@ Task complete when all checkbox items completed and operation verification compl For research tasks, includes creating deliverable files specified in metadata "Provides" section. ### 5. Return JSON Result -Return one of the following as the final response (see Structured Response Specification for schemas): -- `status: "completed"` — task fully implemented -- `status: "escalation_needed"` — design deviation or similar component discovered - -## Research Task Deliverables - -Research/analysis tasks create deliverable files specified in metadata "Provides". -Examples: `docs/plans/analysis/component-research.md`, `docs/plans/analysis/api-integration.md` +Return the final response per Structured Response Specification. For research/analysis tasks, also create the deliverable files declared in task metadata `Provides`. ## Structured Response Specification @@ -358,15 +348,46 @@ When a file outside the allowed list (see "File Scope Constraint" section) needs } ``` +#### 2-6. Binding Decision Violation Escalation +When one or more Compliance Checks in the task's Binding Decisions section trigger escalation — `N` at the pre-implementation check, or `N` or `Unknown` at the Exit Gate re-evaluation — escalate in following JSON format: + +```json +{ + "status": "escalation_needed", + "reason": "Binding decision violation", + "taskName": "[Task name being executed]", + "escalation_type": "binding_decision_violation", + "phase": "pre_implementation | exit_gate", + "plannedApproach": "[1–2 sentence summary of the planned or actual implementation approach]", + "failures": [ + { + "source": "[ADR file path with section hint, copied from Source column]", + "axis": "[Axis value copied from the Axis column]", + "decision": "[Decision text, copied from Decision column]", + "complianceCheck": "[Compliance Check predicate, copied from Compliance Check column]", + "evaluation": "N | Unknown", + "rationale": "[One line explaining why the implementation does not satisfy the check, or why it cannot be evaluated]" + } + ], + "user_decision_required": true, + "suggested_options": [ + "Adjust the implementation plan to satisfy the binding decision", + "Update the ADR (then update the work plan's ADR Bindings and this task's Binding Decisions)", + "Provide additional context that resolves the Unknown evaluation" + ] +} +``` + ## Exit Gate [BLOCKING] This gate runs immediately before producing the final JSON response. ☐ All task checkboxes completed with evidence (or `escalation_needed` triggered earlier) ☐ Implementation is consistent with the Investigation Notes recorded at Step 2 (when Investigation Targets were present) +☐ Every Binding Decisions Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes (when the task file has a Binding Decisions section). Re-evaluate here even when the pre-implementation check passed, because the implementation may have diverged from the planned approach ☐ Final response is a single JSON with `status: "completed"` or `status: "escalation_needed"` and matches the schema in Structured Response Specification -**ENFORCEMENT**: When any gate item is unchecked, produce the final response in the JSON format defined in Structured Response Specification with `status: "escalation_needed"`. +**ENFORCEMENT**: When any gate item is unchecked, produce the final response in the JSON format defined in Structured Response Specification with `status: "escalation_needed"`. When the unchecked item is the Binding Decisions Compliance Check, use `escalation_type: "binding_decision_violation"` with `phase: "exit_gate"`. For other gate failures (checkbox incompletion, divergence from Investigation Notes), use `escalation_type: "design_compliance_violation"` because the implementation has diverged from the planned approach. ## Scope Boundary (delegate to orchestrator) - Overall quality checks → handled by dedicated quality check agent diff --git a/agents/task-executor.md b/agents/task-executor.md index d614046..d4106a8 100644 --- a/agents/task-executor.md +++ b/agents/task-executor.md @@ -102,22 +102,11 @@ The task file plus its declared metadata sections form the source of truth for s - Safety guard usage from dynamic/untyped→concrete contract - Minor UI adjustments, message text changes -## Implementation Authority and Responsibility Boundaries +## Responsibility Boundaries -**Responsibility Scope**: Implementation and test creation (quality checks and commits out of scope) -**Basic Policy**: Start implementation immediately (assuming approved), escalate only for design deviation or shortcut fixes - -## Main Responsibilities - -1. **Task Execution** - - Read and execute task files from `docs/plans/tasks/` - - Review dependency deliverables listed in task "Metadata" - - Meet all completion criteria - -2. **Progress Management (3-location synchronized updates)** - - Checkboxes within task files - - Checkboxes and progress records in work plan documents - - States: `[ ]` not started → `[🔄]` in progress → `[x]` completed +**Scope**: Implementation and test creation. Quality checks and commits are handled by other agents. +**Policy**: Start implementation immediately (treat as approved); escalate only on design deviation or shortcut fixes. +**Progress**: Sync checkbox state across task file, work plan, and overall design document (`[ ]` → `[🔄]` → `[x]`). ## Workflow @@ -178,6 +167,18 @@ This gate runs only when the task file's "Investigation Targets" section lists a 2. **Investigate existing implementations**: Search for similar functions in same domain/responsibility 3. **Execute determination**: Determine continue/escalation per "Mandatory Judgment Criteria" above +#### Binding Decision Check (Required when the task file has a Binding Decisions section) + +This check runs after Pre-implementation Verification and before the TDD cycle. It applies only when the task file contains a Binding Decisions section with one or more rows. + +1. Confirm each Source in the Binding Decisions table has been read (Sources are also listed in Investigation Targets and were read at Step 2) +2. Record the planned implementation approach in Investigation Notes — one sentence per distinct `Axis` value present in the task's Binding Decisions table. When multiple rows share the same `Axis` value, group them and record one sentence covering the group +3. Evaluate each row's Compliance Check against the planned approach. Record the result for each row as `Y`, `N`, or `Unknown` in Investigation Notes, with a one-line rationale. Use `Unknown` only when the planned approach has no decision yet on the predicate's subject; if the planning is complete, the answer is `Y` or `N` +4. Per row, branch on the evaluation: + - `Y`: proceed + - `N`: stop implementation and produce the final response with `status: "escalation_needed"` and `escalation_type: "binding_decision_violation"` with `phase: "pre_implementation"` (see Binding Decision Violation Escalation in Structured Response Specification). `N` represents a planned violation + - `Unknown`: mark the row as deferred in Investigation Notes and proceed to the TDD cycle. The Exit Gate re-evaluates every row (including Unknown rows deferred from this step) against the final implementation and escalates if any remains `N` or `Unknown` at that point + #### Reference Representativeness (Applied During Implementation) When adopting a pattern or dependency from existing code, apply coding-principles "Reference Representativeness" at the point of adoption: @@ -219,14 +220,7 @@ Task complete when all checkbox items completed and operation verification compl For research tasks, includes creating deliverable files specified in metadata "Provides" section. ### 5. Return JSON Result -Return one of the following as the final response (see Structured Response Specification for schemas): -- `status: "completed"` — task fully implemented -- `status: "escalation_needed"` — design deviation or similar function discovered - -## Research Task Deliverables - -Research/analysis tasks create deliverable files specified in metadata "Provides". -Examples: `docs/plans/analysis/research-results.md`, `docs/plans/analysis/api-spec.md` +Return the final response per Structured Response Specification. For research/analysis tasks, also create the deliverable files declared in task metadata `Provides`. ## Structured Response Specification @@ -402,19 +396,50 @@ When a file outside the allowed list (see "File Scope Constraint" section) needs } ``` +#### 2-6. Binding Decision Violation Escalation +When one or more Compliance Checks in the task's Binding Decisions section trigger escalation — `N` at the pre-implementation check, or `N` or `Unknown` at the Exit Gate re-evaluation — escalate in following JSON format: + +```json +{ + "status": "escalation_needed", + "reason": "Binding decision violation", + "taskName": "[Task name being executed]", + "escalation_type": "binding_decision_violation", + "phase": "pre_implementation | exit_gate", + "plannedApproach": "[1–2 sentence summary of the planned or actual implementation approach]", + "failures": [ + { + "source": "[ADR file path with section hint, copied from Source column]", + "axis": "[Axis value copied from the Axis column]", + "decision": "[Decision text, copied from Decision column]", + "complianceCheck": "[Compliance Check predicate, copied from Compliance Check column]", + "evaluation": "N | Unknown", + "rationale": "[One line explaining why the implementation does not satisfy the check, or why it cannot be evaluated]" + } + ], + "user_decision_required": true, + "suggested_options": [ + "Adjust the implementation plan to satisfy the binding decision", + "Update the ADR (then update the work plan's ADR Bindings and this task's Binding Decisions)", + "Provide additional context that resolves the Unknown evaluation" + ] +} +``` + ## Exit Gate [BLOCKING] This gate runs immediately before producing the final JSON response. ☐ All task checkboxes completed with evidence (or `escalation_needed` triggered earlier) ☐ Implementation is consistent with the Investigation Notes recorded at Step 2 (when Investigation Targets were present) +☐ Every Binding Decisions Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes (when the task file has a Binding Decisions section). Re-evaluate here even when the pre-implementation check passed, because the implementation may have diverged from the planned approach ☐ Final response is a single JSON with `status: "completed"` or `status: "escalation_needed"` and matches the schema in Structured Response Specification -**ENFORCEMENT**: When any gate item is unchecked, produce the final response in the JSON format defined in Structured Response Specification with `status: "escalation_needed"`. +**ENFORCEMENT**: When any gate item is unchecked, produce the final response in the JSON format defined in Structured Response Specification with `status: "escalation_needed"`. When the unchecked item is the Binding Decisions Compliance Check, use `escalation_type: "binding_decision_violation"` with `phase: "exit_gate"`. For other gate failures (checkbox incompletion, divergence from Investigation Notes), use `escalation_type: "design_compliance_violation"` because the implementation has diverged from the planned approach. ## Execution Principles - Follow RED-GREEN-REFACTOR (see testing-principles skill) - Update progress checkboxes per step -- Escalate when: design deviation, similar functions found, test environment missing +- Escalate when: design deviation, similar functions found, test environment missing, binding decision violation - Stop after implementation and test creation — quality checks and commits are handled separately \ No newline at end of file diff --git a/agents/work-planner.md b/agents/work-planner.md index e3cf06f..98e915d 100644 --- a/agents/work-planner.md +++ b/agents/work-planner.md @@ -87,7 +87,9 @@ Read the Design Doc template from documentation-criteria skill to identify all s | Verification requirement | Verification methods, test boundaries, integration verification points | Verification/test task | | Prerequisite work | Migration steps, security measures, environment setup | Prerequisite task | -Map each extracted item to a covering task. Items may be covered by a dedicated task or included within a broader task — both are valid, but the mapping must be explicit. +Additionally, when these design-attention sections are non-N/A in the DD, always create Traceability rows for their content: Minimal Surface Alternatives (selected alternative), 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`). + +Map each extracted item to a covering task. Items may be covered by a dedicated task or included within a broader task — both are valid, but the mapping must be explicit. Each row must record the source DD path (matching one of the Related Documents entries) in the `Design Doc` column so downstream task generation can resolve the file unambiguously. Record the mapping in the Design-to-Plan Traceability table (see plan template). If an item has no covering task, set Gap Status to `gap` with justification in Notes. Gaps with justification require user confirmation before plan approval. @@ -124,6 +126,26 @@ For each qualifying boundary: Record the mapping in the **Connection Map** table (see plan template). Omit this section entirely when no qualifying boundary exists. +### 5c. Map ADR Decisions to Tasks (when ADR provided or referenced from Design Doc) + +When an ADR is among the inputs, or when the Design Doc lists ADRs under "Prerequisite ADRs", build the ADR Bindings table. This table is required so binding decisions propagate to each affected task in the downstream task generation phase. + +For each referenced ADR: +1. Resolve the ADR path (file convention: `docs/adr/ADR-[4-digit]-[title].md`): + - Full path (e.g., `docs/adr/ADR-0042-foo.md`) — use as-is + - ID only (e.g., `ADR-0042`) — glob `docs/adr/ADR-0042-*.md`; require exactly one match + - Filename without directory (e.g., `ADR-0042-foo.md`) — prepend `docs/adr/` + - Escalate when the glob returns 0 or 2+ matches, or when the resolved path does not exist + + Then read the ADR's Decision and Implementation Guidance sections +2. Extract decisions that are **implementation-binding** — i.e., they constrain one of five binding axes: placement, dependency direction, contract/schema shape, data flow, or persistence. Acceptance criteria and required behaviors are recorded in the Design Doc; this table covers only structural constraints from ADRs +3. For each binding decision, classify it under exactly one axis (`placement` | `dependency_direction` | `contract_schema` | `data_flow` | `persistence`) — this becomes the row's `Axis` value +4. For each binding decision, note which section it came from (`Decision` or `Implementation Guidance`) — this becomes the row's `Source Section` value +5. For each binding decision, identify the planned task(s) where the decision applies. Use Target files, layer, or component scope to determine relevance — layer/component-level mapping is sufficient at this stage +6. Record one row per binding decision in the **ADR Bindings** table (see plan template) + +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). @@ -302,6 +324,11 @@ When creating work plans, **Phase Structure Diagrams** and **Task Dependency Dia - [ ] Connection Map table complete (when implementation crosses packages/services) - [ ] Every boundary lists owner modules and expected signal - [ ] Every boundary maps to at least one covering task on each side +- [ ] ADR Bindings table complete (when ADR provided or referenced from Design Doc) + - [ ] Each row represents one implementation-binding decision (placement, dependency, contract, data flow, or persistence) + - [ ] Each row's `Axis` value is exactly one of `placement` | `dependency_direction` | `contract_schema` | `data_flow` | `persistence` + - [ ] Each row's `Source Section` is set to `Decision` or `Implementation Guidance` matching the actual location of the decision in the ADR + - [ ] Every row maps to at least one covering task - [ ] Verification Strategy extracted from Design Doc and included in plan header - [ ] Adopted Quality Assurance Mechanisms extracted from Design Doc and included in plan header - [ ] Phase structure matches implementation approach (vertical → value unit phases, horizontal → layer phases) diff --git a/dev-skills/.claude-plugin/plugin.json b/dev-skills/.claude-plugin/plugin.json index 09b58bf..4614eba 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.19.1", + "version": "0.19.2", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-skills/skills/documentation-criteria/references/design-template.md b/dev-skills/skills/documentation-criteria/references/design-template.md index 9bfeba4..4344e12 100644 --- a/dev-skills/skills/documentation-criteria/references/design-template.md +++ b/dev-skills/skills/documentation-criteria/references/design-template.md @@ -30,7 +30,7 @@ unknowns: ### Prerequisite ADRs -- [ADR File Name]: [Related decision items] +- [docs/adr/ADR-XXXX.md]: [Related decision items] - Reference common technical ADRs when applicable ### External Resources Used diff --git a/dev-skills/skills/documentation-criteria/references/plan-template.md b/dev-skills/skills/documentation-criteria/references/plan-template.md index dc7a178..e78a4c1 100644 --- a/dev-skills/skills/documentation-criteria/references/plan-template.md +++ b/dev-skills/skills/documentation-criteria/references/plan-template.md @@ -39,9 +39,9 @@ Adopted quality gates for the change area. Each task in this plan must satisfy t Maps each Design Doc technical requirement to the covering task(s). One row per extracted item. Every row must have at least one covering task, or an explicit gap justification. -| DD Section | DD Item | Category | Covered By Task(s) | Gap Status | Notes | -|---|---|---|---|---|---| -| [Section name from DD] | [Specific item] | impl-target / connection-switching / contract-change / verification / prerequisite | [Phase X Task Y] | covered | | +| Design Doc | DD Section | DD Item | Category | Covered By Task(s) | Gap Status | Notes | +|---|---|---|---|---|---|---| +| [docs/design/XXX.md — one of the Related Documents above] | [Section name from DD] | [Specific item] | impl-target / connection-switching / contract-change / verification / prerequisite | [Phase X Task Y] | covered | | **Category values**: `impl-target` (implementation target), `connection-switching` (connection/switching/registration), `contract-change` (contract change and propagation), `verification` (verification requirement), `prerequisite` (prerequisite work) @@ -59,6 +59,18 @@ Include this section when a UI Spec is among the inputs. Maps each component doc **Gap Status values**: `covered` (task exists), `gap` (no task — requires justification in Notes, user confirmation required before plan approval) +## ADR Bindings + +Include this section when ADRs are provided as input or listed in the Design Doc's "Prerequisite ADRs" section. Maps each implementation-binding ADR decision to the task(s) it constrains. Omit the section when no ADR applies. + +A decision is **implementation-binding** when it constrains code placement, dependency direction, contract/schema shape, data flow, or persistence. Acceptance criteria and required behaviors are recorded in the Design Doc; this table covers only structural constraints from ADRs. + +| ADR | Source Section | Axis | Binding Decision | Covered By Task(s) | +|---|---|---|---|---| +| [docs/adr/ADR-XXXX.md] | Decision / Implementation Guidance | placement \| dependency_direction \| contract_schema \| data_flow \| persistence | [One implementation-binding decision sentence, copied or condensed from the named section] | [Phase X Task Y] | + +One row per binding decision. A single ADR can contribute multiple rows. A single task can appear in multiple rows. + ## Connection Map Include this section when the implementation crosses more than one package, service, or process boundary. Document each boundary. Omit the section when the implementation stays within a single package. diff --git a/dev-skills/skills/documentation-criteria/references/task-template.md b/dev-skills/skills/documentation-criteria/references/task-template.md index fac8370..8a29a9a 100644 --- a/dev-skills/skills/documentation-criteria/references/task-template.md +++ b/dev-skills/skills/documentation-criteria/references/task-template.md @@ -17,8 +17,17 @@ Metadata: 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] +## Binding Decisions +(Include this section when the work plan's ADR Bindings table covers this task. Omit otherwise.) + +Each row is an ADR decision the implementation in this task must comply with. + +| Source | Axis | Decision | Compliance Check | +|---|---|---|---| +| [docs/adr/ADR-XXXX.md (§ ) — substitute the section name (`Decision` or `Implementation Guidance`) from the matching work plan row] | [Axis value copied verbatim from the work plan's ADR Bindings row] | [Binding decision copied from the work plan's ADR Bindings row] | [Y/N-answerable positive predicate that evaluates whether the planned/final implementation satisfies the decision] | + ## Investigation Notes -(Implementation observations are appended here before implementation begins.) +(Implementation observations are appended here before implementation begins. When Binding Decisions exist, record the planned implementation approach and each Compliance Check result here.) ## Implementation Steps (TDD: Red-Green-Refactor) ### 1. Red Phase @@ -51,6 +60,7 @@ Files to read before starting implementation (file path, with optional search hi - [ ] All added tests pass - [ ] Operation verified per Operation Verification Methods above - [ ] Deliverables created (for research/design tasks) +- [ ] (When Binding Decisions exist) Every Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes (file:line, test result, or command output) ## Notes - Impact scope: [Areas where changes may propagate] diff --git a/dev-workflows-frontend/.claude-plugin/plugin.json b/dev-workflows-frontend/.claude-plugin/plugin.json index 9c5842a..0e7900d 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.19.1", + "version": "0.19.2", "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 aeff0d1..a385d3a 100644 --- a/dev-workflows-frontend/agents/task-decomposer.md +++ b/dev-workflows-frontend/agents/task-decomposer.md @@ -112,6 +112,7 @@ Decompose tasks based on implementation strategy patterns determined in implemen | Cross-package boundary implementation | Both sides of the boundary as listed in the work plan's Connection Map (owner modules and expected signal), the contract definition between them | | Bug fix / refactor | The affected code paths, related test coverage, error reproduction context | | Behavior replacement / rewrite | The existing implementation being replaced, its observable outputs, Design Doc Verification Strategy section | + | Task constrained by an ADR (work plan's ADR Bindings table covers this task) | The ADR file with section hint matching the row's `Source Section` value (e.g., `(§ Decision)` or `(§ Implementation Guidance)`) for each binding row covering this task | **Principles**: - Every task must have at least one Investigation Target (even if just the Design Doc) @@ -121,6 +122,8 @@ Decompose tasks based on implementation strategy patterns determined in implemen - When test skeletons exist for the task, always include them as Investigation Targets - When the work plan contains a UI Spec Component → Task Mapping table, propagate the matching component section to every task in that row (see UI Spec Propagation below) - When the work plan contains a Connection Map, propagate the boundary rows touching this task's target files (see Connection Map Propagation below) + - When the work plan contains an ADR Bindings table covering this task, propagate the matching rows (see ADR Binding Propagation below) + - When the work plan contains a Design-to-Plan Traceability table, propagate the matching DD section rows (see Design Traceability Propagation below) 7. **Implementation Pattern Consistency** When including implementation samples, MUST ensure strict compliance with the Design Doc implementation approach that forms the basis of the work plan @@ -173,6 +176,34 @@ When the work plan contains a Connection Map table, propagate boundary context t 3. **Add a "Boundary Context" note in the task body**: Record the boundary identifier and expected signal verbatim from the Connection Map row, so the executor knows what observable evidence the implementation must produce 4. **Skip when not provided**: If the work plan has no Connection Map, skip this propagation step +## ADR Binding Propagation + +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 +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 + - **Axis**: Copy the row's `Axis` value verbatim from the work plan row + - **Decision**: Copy the binding decision sentence verbatim from the work plan row + - **Compliance Check**: Write a Y/N-answerable positive predicate stating that the implementation satisfies the decision. One example per binding axis: + - `placement`: "Auth entrypoint is in `src/middleware/**`" + - `dependency_direction`: "The domain layer imports only from `src/domain/**` and `src/shared/**`" + - `contract_schema`: "API responses match the `ResponseEnvelope` schema" + - `data_flow`: "Session tokens are written exclusively through the Redis client" + - `persistence`: "User records are persisted only via the `UsersRepository` interface" + + When the decision cannot be verified by file:line or command alone, the predicate may rely on reasoned judgment, but it must remain Y/N-answerable +4. **Apply only when provided**: Run this propagation only when the work plan contains an ADR Bindings table + +## Design Traceability Propagation + +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])` +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 + ## Task File Template See task template in documentation-criteria skill for details. @@ -274,6 +305,11 @@ Please execute decomposed tasks according to the order. - [ ] Quality Assurance Mechanisms from work plan header propagated to relevant tasks - [ ] UI Spec Component → Task Mapping rows propagated to matching tasks (when work plan has the table) - [ ] Connection Map boundary rows propagated to matching tasks (when work plan has the table) +- [ ] Design-to-Plan Traceability rows propagated to matching tasks as Investigation Targets (when work plan has the table) +- [ ] ADR Bindings rows propagated to matching tasks as Binding Decisions (when work plan has the table) + - [ ] Source includes ADR path with section hint + - [ ] Axis copied verbatim from the work plan row to the task's Binding Decisions table + - [ ] 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) diff --git a/dev-workflows-frontend/agents/task-executor-frontend.md b/dev-workflows-frontend/agents/task-executor-frontend.md index 2c47ae3..4aae2d1 100644 --- a/dev-workflows-frontend/agents/task-executor-frontend.md +++ b/dev-workflows-frontend/agents/task-executor-frontend.md @@ -104,22 +104,11 @@ Use the appropriate run command based on the `packageManager` field in package.j - Type guard usage from unknown→concrete type (for external API responses) - Minor UI adjustments, message text changes -## Implementation Authority and Responsibility Boundaries +## Responsibility Boundaries -**Responsibility Scope**: React component implementation and test creation (quality checks and commits out of scope) -**Basic Policy**: Start implementation immediately (assuming approved), escalate only for design deviation or shortcut fixes - -## Main Responsibilities - -1. **Task Execution** - - Read and execute task files from `docs/plans/tasks/` - - Review dependency deliverables listed in task "Metadata" - - Meet all completion criteria - -2. **Progress Management (3-location synchronized updates)** - - Checkboxes within task files - - Checkboxes and progress records in work plan documents - - States: `[ ]` not started → `[🔄]` in progress → `[x]` completed +**Scope**: React component implementation and test creation. Quality checks and commits are handled by other agents. +**Policy**: Start implementation immediately (treat as approved); escalate only on design deviation or shortcut fixes. +**Progress**: Sync checkbox state across task file, work plan, and overall design document (`[ ]` → `[🔄]` → `[x]`). ## Workflow @@ -172,6 +161,18 @@ This gate runs only when the task file's "Investigation Targets" section lists a 2. **Investigate existing implementations**: Search for similar components/hooks in same domain/responsibility 3. **Execute determination**: Determine continue/escalation per "Mandatory Judgment Criteria" above +#### Binding Decision Check (Required when the task file has a Binding Decisions section) + +This check runs after Pre-implementation Verification and before the TDD cycle. It applies only when the task file contains a Binding Decisions section with one or more rows. + +1. Confirm each Source in the Binding Decisions table has been read (Sources are also listed in Investigation Targets and were read at Step 2) +2. Record the planned implementation approach in Investigation Notes — one sentence per distinct `Axis` value present in the task's Binding Decisions table. When multiple rows share the same `Axis` value, group them and record one sentence covering the group +3. Evaluate each row's Compliance Check against the planned approach. Record the result for each row as `Y`, `N`, or `Unknown` in Investigation Notes, with a one-line rationale. Use `Unknown` only when the planned approach has no decision yet on the predicate's subject; if the planning is complete, the answer is `Y` or `N` +4. Per row, branch on the evaluation: + - `Y`: proceed + - `N`: stop implementation and produce the final response with `status: "escalation_needed"` and `escalation_type: "binding_decision_violation"` with `phase: "pre_implementation"` (see Binding Decision Violation Escalation in Structured Response Specification). `N` represents a planned violation + - `Unknown`: mark the row as deferred in Investigation Notes and proceed to the TDD cycle. The Exit Gate re-evaluates every row (including Unknown rows deferred from this step) against the final implementation and escalates if any remains `N` or `Unknown` at that point + #### Implementation Flow (TDD Compliant) **Completion Confirmation**: If all checkboxes are `[x]`, report "already completed" and end @@ -180,11 +181,7 @@ This gate runs only when the task file's "Investigation Targets" section lists a ※For integration tests (multiple components), create and execute simultaneously with implementation; E2E tests are executed in final phase only 2. **Green**: Implement minimum code to pass test (React function component) 3. **Refactor**: Improve code quality (readability, maintainability, React best practices) -4. **Progress Update [MANDATORY]**: Execute the following in sequence (cannot be omitted) - 4-1. **Task file**: Change completed item from `[ ]` → `[x]` - 4-2. **Work plan**: Change same item from `[ ]` → `[x]` in corresponding plan in docs/plans/ - 4-3. **Overall design document**: Update corresponding item in progress section if exists - ※After each Edit tool execution, proceed to next step +4. **Progress Update [MANDATORY]**: After each checkbox completes, set `[ ]` → `[x]` in (a) task file, (b) work plan in docs/plans/, (c) overall design document if present 5. **Test Execution**: Run only created tests and confirm they pass #### Operation Verification @@ -199,14 +196,7 @@ Task complete when all checkbox items completed and operation verification compl For research tasks, includes creating deliverable files specified in metadata "Provides" section. ### 5. Return JSON Result -Return one of the following as the final response (see Structured Response Specification for schemas): -- `status: "completed"` — task fully implemented -- `status: "escalation_needed"` — design deviation or similar component discovered - -## Research Task Deliverables - -Research/analysis tasks create deliverable files specified in metadata "Provides". -Examples: `docs/plans/analysis/component-research.md`, `docs/plans/analysis/api-integration.md` +Return the final response per Structured Response Specification. For research/analysis tasks, also create the deliverable files declared in task metadata `Provides`. ## Structured Response Specification @@ -358,15 +348,46 @@ When a file outside the allowed list (see "File Scope Constraint" section) needs } ``` +#### 2-6. Binding Decision Violation Escalation +When one or more Compliance Checks in the task's Binding Decisions section trigger escalation — `N` at the pre-implementation check, or `N` or `Unknown` at the Exit Gate re-evaluation — escalate in following JSON format: + +```json +{ + "status": "escalation_needed", + "reason": "Binding decision violation", + "taskName": "[Task name being executed]", + "escalation_type": "binding_decision_violation", + "phase": "pre_implementation | exit_gate", + "plannedApproach": "[1–2 sentence summary of the planned or actual implementation approach]", + "failures": [ + { + "source": "[ADR file path with section hint, copied from Source column]", + "axis": "[Axis value copied from the Axis column]", + "decision": "[Decision text, copied from Decision column]", + "complianceCheck": "[Compliance Check predicate, copied from Compliance Check column]", + "evaluation": "N | Unknown", + "rationale": "[One line explaining why the implementation does not satisfy the check, or why it cannot be evaluated]" + } + ], + "user_decision_required": true, + "suggested_options": [ + "Adjust the implementation plan to satisfy the binding decision", + "Update the ADR (then update the work plan's ADR Bindings and this task's Binding Decisions)", + "Provide additional context that resolves the Unknown evaluation" + ] +} +``` + ## Exit Gate [BLOCKING] This gate runs immediately before producing the final JSON response. ☐ All task checkboxes completed with evidence (or `escalation_needed` triggered earlier) ☐ Implementation is consistent with the Investigation Notes recorded at Step 2 (when Investigation Targets were present) +☐ Every Binding Decisions Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes (when the task file has a Binding Decisions section). Re-evaluate here even when the pre-implementation check passed, because the implementation may have diverged from the planned approach ☐ Final response is a single JSON with `status: "completed"` or `status: "escalation_needed"` and matches the schema in Structured Response Specification -**ENFORCEMENT**: When any gate item is unchecked, produce the final response in the JSON format defined in Structured Response Specification with `status: "escalation_needed"`. +**ENFORCEMENT**: When any gate item is unchecked, produce the final response in the JSON format defined in Structured Response Specification with `status: "escalation_needed"`. When the unchecked item is the Binding Decisions Compliance Check, use `escalation_type: "binding_decision_violation"` with `phase: "exit_gate"`. For other gate failures (checkbox incompletion, divergence from Investigation Notes), use `escalation_type: "design_compliance_violation"` because the implementation has diverged from the planned approach. ## Scope Boundary (delegate to orchestrator) - Overall quality checks → handled by dedicated quality check agent diff --git a/dev-workflows-frontend/agents/work-planner.md b/dev-workflows-frontend/agents/work-planner.md index e3cf06f..98e915d 100644 --- a/dev-workflows-frontend/agents/work-planner.md +++ b/dev-workflows-frontend/agents/work-planner.md @@ -87,7 +87,9 @@ Read the Design Doc template from documentation-criteria skill to identify all s | Verification requirement | Verification methods, test boundaries, integration verification points | Verification/test task | | Prerequisite work | Migration steps, security measures, environment setup | Prerequisite task | -Map each extracted item to a covering task. Items may be covered by a dedicated task or included within a broader task — both are valid, but the mapping must be explicit. +Additionally, when these design-attention sections are non-N/A in the DD, always create Traceability rows for their content: Minimal Surface Alternatives (selected alternative), 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`). + +Map each extracted item to a covering task. Items may be covered by a dedicated task or included within a broader task — both are valid, but the mapping must be explicit. Each row must record the source DD path (matching one of the Related Documents entries) in the `Design Doc` column so downstream task generation can resolve the file unambiguously. Record the mapping in the Design-to-Plan Traceability table (see plan template). If an item has no covering task, set Gap Status to `gap` with justification in Notes. Gaps with justification require user confirmation before plan approval. @@ -124,6 +126,26 @@ For each qualifying boundary: Record the mapping in the **Connection Map** table (see plan template). Omit this section entirely when no qualifying boundary exists. +### 5c. Map ADR Decisions to Tasks (when ADR provided or referenced from Design Doc) + +When an ADR is among the inputs, or when the Design Doc lists ADRs under "Prerequisite ADRs", build the ADR Bindings table. This table is required so binding decisions propagate to each affected task in the downstream task generation phase. + +For each referenced ADR: +1. Resolve the ADR path (file convention: `docs/adr/ADR-[4-digit]-[title].md`): + - Full path (e.g., `docs/adr/ADR-0042-foo.md`) — use as-is + - ID only (e.g., `ADR-0042`) — glob `docs/adr/ADR-0042-*.md`; require exactly one match + - Filename without directory (e.g., `ADR-0042-foo.md`) — prepend `docs/adr/` + - Escalate when the glob returns 0 or 2+ matches, or when the resolved path does not exist + + Then read the ADR's Decision and Implementation Guidance sections +2. Extract decisions that are **implementation-binding** — i.e., they constrain one of five binding axes: placement, dependency direction, contract/schema shape, data flow, or persistence. Acceptance criteria and required behaviors are recorded in the Design Doc; this table covers only structural constraints from ADRs +3. For each binding decision, classify it under exactly one axis (`placement` | `dependency_direction` | `contract_schema` | `data_flow` | `persistence`) — this becomes the row's `Axis` value +4. For each binding decision, note which section it came from (`Decision` or `Implementation Guidance`) — this becomes the row's `Source Section` value +5. For each binding decision, identify the planned task(s) where the decision applies. Use Target files, layer, or component scope to determine relevance — layer/component-level mapping is sufficient at this stage +6. Record one row per binding decision in the **ADR Bindings** table (see plan template) + +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). @@ -302,6 +324,11 @@ When creating work plans, **Phase Structure Diagrams** and **Task Dependency Dia - [ ] Connection Map table complete (when implementation crosses packages/services) - [ ] Every boundary lists owner modules and expected signal - [ ] Every boundary maps to at least one covering task on each side +- [ ] ADR Bindings table complete (when ADR provided or referenced from Design Doc) + - [ ] Each row represents one implementation-binding decision (placement, dependency, contract, data flow, or persistence) + - [ ] Each row's `Axis` value is exactly one of `placement` | `dependency_direction` | `contract_schema` | `data_flow` | `persistence` + - [ ] Each row's `Source Section` is set to `Decision` or `Implementation Guidance` matching the actual location of the decision in the ADR + - [ ] Every row maps to at least one covering task - [ ] Verification Strategy extracted from Design Doc and included in plan header - [ ] Adopted Quality Assurance Mechanisms extracted from Design Doc and included in plan header - [ ] Phase structure matches implementation approach (vertical → value unit phases, horizontal → layer phases) diff --git a/dev-workflows-frontend/skills/documentation-criteria/references/design-template.md b/dev-workflows-frontend/skills/documentation-criteria/references/design-template.md index 9bfeba4..4344e12 100644 --- a/dev-workflows-frontend/skills/documentation-criteria/references/design-template.md +++ b/dev-workflows-frontend/skills/documentation-criteria/references/design-template.md @@ -30,7 +30,7 @@ unknowns: ### Prerequisite ADRs -- [ADR File Name]: [Related decision items] +- [docs/adr/ADR-XXXX.md]: [Related decision items] - Reference common technical ADRs when applicable ### External Resources Used 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 dc7a178..e78a4c1 100644 --- a/dev-workflows-frontend/skills/documentation-criteria/references/plan-template.md +++ b/dev-workflows-frontend/skills/documentation-criteria/references/plan-template.md @@ -39,9 +39,9 @@ Adopted quality gates for the change area. Each task in this plan must satisfy t Maps each Design Doc technical requirement to the covering task(s). One row per extracted item. Every row must have at least one covering task, or an explicit gap justification. -| DD Section | DD Item | Category | Covered By Task(s) | Gap Status | Notes | -|---|---|---|---|---|---| -| [Section name from DD] | [Specific item] | impl-target / connection-switching / contract-change / verification / prerequisite | [Phase X Task Y] | covered | | +| Design Doc | DD Section | DD Item | Category | Covered By Task(s) | Gap Status | Notes | +|---|---|---|---|---|---|---| +| [docs/design/XXX.md — one of the Related Documents above] | [Section name from DD] | [Specific item] | impl-target / connection-switching / contract-change / verification / prerequisite | [Phase X Task Y] | covered | | **Category values**: `impl-target` (implementation target), `connection-switching` (connection/switching/registration), `contract-change` (contract change and propagation), `verification` (verification requirement), `prerequisite` (prerequisite work) @@ -59,6 +59,18 @@ Include this section when a UI Spec is among the inputs. Maps each component doc **Gap Status values**: `covered` (task exists), `gap` (no task — requires justification in Notes, user confirmation required before plan approval) +## ADR Bindings + +Include this section when ADRs are provided as input or listed in the Design Doc's "Prerequisite ADRs" section. Maps each implementation-binding ADR decision to the task(s) it constrains. Omit the section when no ADR applies. + +A decision is **implementation-binding** when it constrains code placement, dependency direction, contract/schema shape, data flow, or persistence. Acceptance criteria and required behaviors are recorded in the Design Doc; this table covers only structural constraints from ADRs. + +| ADR | Source Section | Axis | Binding Decision | Covered By Task(s) | +|---|---|---|---|---| +| [docs/adr/ADR-XXXX.md] | Decision / Implementation Guidance | placement \| dependency_direction \| contract_schema \| data_flow \| persistence | [One implementation-binding decision sentence, copied or condensed from the named section] | [Phase X Task Y] | + +One row per binding decision. A single ADR can contribute multiple rows. A single task can appear in multiple rows. + ## Connection Map Include this section when the implementation crosses more than one package, service, or process boundary. Document each boundary. Omit the section when the implementation stays within a single package. 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 fac8370..8a29a9a 100644 --- a/dev-workflows-frontend/skills/documentation-criteria/references/task-template.md +++ b/dev-workflows-frontend/skills/documentation-criteria/references/task-template.md @@ -17,8 +17,17 @@ Metadata: 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] +## Binding Decisions +(Include this section when the work plan's ADR Bindings table covers this task. Omit otherwise.) + +Each row is an ADR decision the implementation in this task must comply with. + +| Source | Axis | Decision | Compliance Check | +|---|---|---|---| +| [docs/adr/ADR-XXXX.md (§ ) — substitute the section name (`Decision` or `Implementation Guidance`) from the matching work plan row] | [Axis value copied verbatim from the work plan's ADR Bindings row] | [Binding decision copied from the work plan's ADR Bindings row] | [Y/N-answerable positive predicate that evaluates whether the planned/final implementation satisfies the decision] | + ## Investigation Notes -(Implementation observations are appended here before implementation begins.) +(Implementation observations are appended here before implementation begins. When Binding Decisions exist, record the planned implementation approach and each Compliance Check result here.) ## Implementation Steps (TDD: Red-Green-Refactor) ### 1. Red Phase @@ -51,6 +60,7 @@ Files to read before starting implementation (file path, with optional search hi - [ ] All added tests pass - [ ] Operation verified per Operation Verification Methods above - [ ] Deliverables created (for research/design tasks) +- [ ] (When Binding Decisions exist) Every Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes (file:line, test result, or command output) ## Notes - Impact scope: [Areas where changes may propagate] diff --git a/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md index 89d7997..b84e79d 100644 --- a/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md @@ -7,8 +7,6 @@ description: Guides subagent coordination through implementation workflows. Use ## Role: The Orchestrator -**The orchestrator coordinates subagents like a conductor—directing the musicians without playing the instruments.** - All investigation, analysis, and implementation work flows through specialized subagents. ### First Action Rule @@ -26,19 +24,17 @@ When receiving a new task, pass user requirements directly to requirement-analyz ## Available Subagents -The following subagents are available: - -### Implementation Support Agents +Implementation support: 1. **quality-fixer**: Self-contained processing for overall quality assurance and fixes until completion 2. **task-decomposer**: Appropriate task decomposition of work plans 3. **task-executor**: Individual task execution and structured response 4. **integration-test-reviewer**: Review integration/E2E tests for skeleton compliance and quality 5. **security-reviewer**: Security compliance review against Design Doc and coding-principles after all tasks complete -### Document Creation Agents +Document creation: 6. **requirement-analyzer**: Requirement analysis and work scale determination 7. **codebase-analyzer**: Analyze existing codebase to produce focused guidance for technical design (data, contracts, dependencies, quality assurance mechanisms) -8. **ui-analyzer**: Read the project's external-resources file, fetch external UI sources (design origin, design system, guidelines) via MCP/URL/file, and analyze existing UI code (visual structure, layout state, props patterns, state matrices, display conditions, i18n format, accessibility, generated UI artifacts). Frontend/fullstack features; runs in parallel with codebase-analyzer. Uses `disallowedTools` to inherit MCP access +8. **ui-analyzer**: Read the project's external-resources file, fetch external UI sources (design origin, design system, guidelines) via MCP/URL/file, and analyze existing UI code. Frontend/fullstack features; runs in parallel with codebase-analyzer. Uses `disallowedTools` to inherit MCP access 9. **prd-creator**: Product Requirements Document creation 10. **ui-spec-designer**: UI Specification creation from PRD and optional prototype code (frontend/fullstack features) 11. **technical-designer**: ADR/Design Doc creation @@ -187,7 +183,7 @@ Subagents respond in JSON format. Key fields for orchestrator decisions: - **codebase-analyzer**: analysisScope.categoriesDetected, dataModel.detected, qualityAssurance (mechanisms[], domainConstraints[]), focusAreas[], existingElements count, limitations - **ui-analyzer**: analysisScope.uiConventions, externalResources (designOrigin/designSystem/guidelines/visualVerification with fetch_status), componentStructure[], propsPatterns[], cssLayout[], stateDisplay[], displayConditions[], i18n, accessibility[], generatedArtifacts[], focusAreas[] (raw fact_id; consumers apply `ui:` prefix when merging with codebase analysis facts), candidateWriteSet[] (with confidence labels), limitations - **code-verifier**: status (consistent/mostly_consistent/needs_review/inconsistent), consistencyScore, discrepancies[], reverseCoverage (including dataOperationsInCode, testBoundariesSectionPresent). Pre-implementation: verifies Design Doc claims against existing codebase. Post-implementation: verifies implementation consistency against Design Doc (pass `code_paths` scoped to changed files) -- **task-executor**: status (escalation_needed/completed), escalation_type (design_compliance_violation/similar_function_found/investigation_target_not_found/out_of_scope_file/dependency_version_uncertain), testsAdded, requiresTestReview +- **task-executor**: status (escalation_needed/completed), escalation_type (design_compliance_violation/similar_function_found/investigation_target_not_found/out_of_scope_file/dependency_version_uncertain/binding_decision_violation), testsAdded, requiresTestReview - **quality-fixer**: Input: `task_file` (path to current task file — always pass this in orchestrated flows). Status: approved/stub_detected/blocked. `stub_detected` → route back to task-executor with `incompleteImplementations[]` details for completion, then re-run quality-fixer. `blocked` → discriminate by `reason` field: `"Cannot determine due to unclear specification"` → read `blockingIssues[]` for specification details; `"Execution prerequisites not met"` → read `missingPrerequisites[]` with `resolutionSteps` — present these to the user as actionable next steps - **document-reviewer**: approvalReady (true/false) - **design-sync**: sync_status (synced/conflicts_found) @@ -202,17 +198,7 @@ requirement-analyzer follows the "completely self-contained" principle and proce #### How to Integrate Requirements -**Important**: To maximize accuracy, integrate requirements as complete sentences, including all contextual information communicated by the user. - -```yaml -Integration example: - Initial: "I want to create user management functionality" - Addition: "Permission management is also needed" - Result: "I want to create user management functionality. Permission management is also needed. - - Initial requirement: I want to create user management functionality - Additional requirement: Permission management is also needed" -``` +**Important**: To maximize accuracy, integrate requirements as complete sentences, including all contextual information communicated by the user. Result format: raw concatenation of all requirements, followed by a labeled summary (`Initial requirement: …` / `Additional requirement: …`). ### Update Mode for Document Generation Agents Document generation agents (work-planner, technical-designer, prd-creator) can update existing documents in `update` mode. @@ -422,11 +408,7 @@ Register overall phases using TaskCreate. Update each phase with TaskUpdate as i ## Important Constraints -- **Quality check is mandatory**: quality-fixer approval needed before commit -- **Structured response mandatory**: Information transmission between subagents in JSON format -- **Approval management**: Document creation → Execute document-reviewer → Get user approval before proceeding -- **Flow confirmation**: After getting approval, always check next step with work planning flow (large/medium/small scale) -- **Consistency verification**: Resolve subagent conflicts per Decision precedence (see Delegation Boundary section) +Recap (defined above): quality-fixer approval before commit; inter-agent communication is JSON; document-reviewer + user approval before proceeding; check next step against work planning flow after approval; resolve conflicts via Decision precedence. ## References diff --git a/dev-workflows-fullstack/.claude-plugin/plugin.json b/dev-workflows-fullstack/.claude-plugin/plugin.json index 8c36322..f512410 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.19.1", + "version": "0.19.2", "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 aeff0d1..a385d3a 100644 --- a/dev-workflows-fullstack/agents/task-decomposer.md +++ b/dev-workflows-fullstack/agents/task-decomposer.md @@ -112,6 +112,7 @@ Decompose tasks based on implementation strategy patterns determined in implemen | Cross-package boundary implementation | Both sides of the boundary as listed in the work plan's Connection Map (owner modules and expected signal), the contract definition between them | | Bug fix / refactor | The affected code paths, related test coverage, error reproduction context | | Behavior replacement / rewrite | The existing implementation being replaced, its observable outputs, Design Doc Verification Strategy section | + | Task constrained by an ADR (work plan's ADR Bindings table covers this task) | The ADR file with section hint matching the row's `Source Section` value (e.g., `(§ Decision)` or `(§ Implementation Guidance)`) for each binding row covering this task | **Principles**: - Every task must have at least one Investigation Target (even if just the Design Doc) @@ -121,6 +122,8 @@ Decompose tasks based on implementation strategy patterns determined in implemen - When test skeletons exist for the task, always include them as Investigation Targets - When the work plan contains a UI Spec Component → Task Mapping table, propagate the matching component section to every task in that row (see UI Spec Propagation below) - When the work plan contains a Connection Map, propagate the boundary rows touching this task's target files (see Connection Map Propagation below) + - When the work plan contains an ADR Bindings table covering this task, propagate the matching rows (see ADR Binding Propagation below) + - When the work plan contains a Design-to-Plan Traceability table, propagate the matching DD section rows (see Design Traceability Propagation below) 7. **Implementation Pattern Consistency** When including implementation samples, MUST ensure strict compliance with the Design Doc implementation approach that forms the basis of the work plan @@ -173,6 +176,34 @@ When the work plan contains a Connection Map table, propagate boundary context t 3. **Add a "Boundary Context" note in the task body**: Record the boundary identifier and expected signal verbatim from the Connection Map row, so the executor knows what observable evidence the implementation must produce 4. **Skip when not provided**: If the work plan has no Connection Map, skip this propagation step +## ADR Binding Propagation + +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 +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 + - **Axis**: Copy the row's `Axis` value verbatim from the work plan row + - **Decision**: Copy the binding decision sentence verbatim from the work plan row + - **Compliance Check**: Write a Y/N-answerable positive predicate stating that the implementation satisfies the decision. One example per binding axis: + - `placement`: "Auth entrypoint is in `src/middleware/**`" + - `dependency_direction`: "The domain layer imports only from `src/domain/**` and `src/shared/**`" + - `contract_schema`: "API responses match the `ResponseEnvelope` schema" + - `data_flow`: "Session tokens are written exclusively through the Redis client" + - `persistence`: "User records are persisted only via the `UsersRepository` interface" + + When the decision cannot be verified by file:line or command alone, the predicate may rely on reasoned judgment, but it must remain Y/N-answerable +4. **Apply only when provided**: Run this propagation only when the work plan contains an ADR Bindings table + +## Design Traceability Propagation + +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])` +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 + ## Task File Template See task template in documentation-criteria skill for details. @@ -274,6 +305,11 @@ Please execute decomposed tasks according to the order. - [ ] Quality Assurance Mechanisms from work plan header propagated to relevant tasks - [ ] UI Spec Component → Task Mapping rows propagated to matching tasks (when work plan has the table) - [ ] Connection Map boundary rows propagated to matching tasks (when work plan has the table) +- [ ] Design-to-Plan Traceability rows propagated to matching tasks as Investigation Targets (when work plan has the table) +- [ ] ADR Bindings rows propagated to matching tasks as Binding Decisions (when work plan has the table) + - [ ] Source includes ADR path with section hint + - [ ] Axis copied verbatim from the work plan row to the task's Binding Decisions table + - [ ] 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) diff --git a/dev-workflows-fullstack/agents/task-executor-frontend.md b/dev-workflows-fullstack/agents/task-executor-frontend.md index 2c47ae3..4aae2d1 100644 --- a/dev-workflows-fullstack/agents/task-executor-frontend.md +++ b/dev-workflows-fullstack/agents/task-executor-frontend.md @@ -104,22 +104,11 @@ Use the appropriate run command based on the `packageManager` field in package.j - Type guard usage from unknown→concrete type (for external API responses) - Minor UI adjustments, message text changes -## Implementation Authority and Responsibility Boundaries +## Responsibility Boundaries -**Responsibility Scope**: React component implementation and test creation (quality checks and commits out of scope) -**Basic Policy**: Start implementation immediately (assuming approved), escalate only for design deviation or shortcut fixes - -## Main Responsibilities - -1. **Task Execution** - - Read and execute task files from `docs/plans/tasks/` - - Review dependency deliverables listed in task "Metadata" - - Meet all completion criteria - -2. **Progress Management (3-location synchronized updates)** - - Checkboxes within task files - - Checkboxes and progress records in work plan documents - - States: `[ ]` not started → `[🔄]` in progress → `[x]` completed +**Scope**: React component implementation and test creation. Quality checks and commits are handled by other agents. +**Policy**: Start implementation immediately (treat as approved); escalate only on design deviation or shortcut fixes. +**Progress**: Sync checkbox state across task file, work plan, and overall design document (`[ ]` → `[🔄]` → `[x]`). ## Workflow @@ -172,6 +161,18 @@ This gate runs only when the task file's "Investigation Targets" section lists a 2. **Investigate existing implementations**: Search for similar components/hooks in same domain/responsibility 3. **Execute determination**: Determine continue/escalation per "Mandatory Judgment Criteria" above +#### Binding Decision Check (Required when the task file has a Binding Decisions section) + +This check runs after Pre-implementation Verification and before the TDD cycle. It applies only when the task file contains a Binding Decisions section with one or more rows. + +1. Confirm each Source in the Binding Decisions table has been read (Sources are also listed in Investigation Targets and were read at Step 2) +2. Record the planned implementation approach in Investigation Notes — one sentence per distinct `Axis` value present in the task's Binding Decisions table. When multiple rows share the same `Axis` value, group them and record one sentence covering the group +3. Evaluate each row's Compliance Check against the planned approach. Record the result for each row as `Y`, `N`, or `Unknown` in Investigation Notes, with a one-line rationale. Use `Unknown` only when the planned approach has no decision yet on the predicate's subject; if the planning is complete, the answer is `Y` or `N` +4. Per row, branch on the evaluation: + - `Y`: proceed + - `N`: stop implementation and produce the final response with `status: "escalation_needed"` and `escalation_type: "binding_decision_violation"` with `phase: "pre_implementation"` (see Binding Decision Violation Escalation in Structured Response Specification). `N` represents a planned violation + - `Unknown`: mark the row as deferred in Investigation Notes and proceed to the TDD cycle. The Exit Gate re-evaluates every row (including Unknown rows deferred from this step) against the final implementation and escalates if any remains `N` or `Unknown` at that point + #### Implementation Flow (TDD Compliant) **Completion Confirmation**: If all checkboxes are `[x]`, report "already completed" and end @@ -180,11 +181,7 @@ This gate runs only when the task file's "Investigation Targets" section lists a ※For integration tests (multiple components), create and execute simultaneously with implementation; E2E tests are executed in final phase only 2. **Green**: Implement minimum code to pass test (React function component) 3. **Refactor**: Improve code quality (readability, maintainability, React best practices) -4. **Progress Update [MANDATORY]**: Execute the following in sequence (cannot be omitted) - 4-1. **Task file**: Change completed item from `[ ]` → `[x]` - 4-2. **Work plan**: Change same item from `[ ]` → `[x]` in corresponding plan in docs/plans/ - 4-3. **Overall design document**: Update corresponding item in progress section if exists - ※After each Edit tool execution, proceed to next step +4. **Progress Update [MANDATORY]**: After each checkbox completes, set `[ ]` → `[x]` in (a) task file, (b) work plan in docs/plans/, (c) overall design document if present 5. **Test Execution**: Run only created tests and confirm they pass #### Operation Verification @@ -199,14 +196,7 @@ Task complete when all checkbox items completed and operation verification compl For research tasks, includes creating deliverable files specified in metadata "Provides" section. ### 5. Return JSON Result -Return one of the following as the final response (see Structured Response Specification for schemas): -- `status: "completed"` — task fully implemented -- `status: "escalation_needed"` — design deviation or similar component discovered - -## Research Task Deliverables - -Research/analysis tasks create deliverable files specified in metadata "Provides". -Examples: `docs/plans/analysis/component-research.md`, `docs/plans/analysis/api-integration.md` +Return the final response per Structured Response Specification. For research/analysis tasks, also create the deliverable files declared in task metadata `Provides`. ## Structured Response Specification @@ -358,15 +348,46 @@ When a file outside the allowed list (see "File Scope Constraint" section) needs } ``` +#### 2-6. Binding Decision Violation Escalation +When one or more Compliance Checks in the task's Binding Decisions section trigger escalation — `N` at the pre-implementation check, or `N` or `Unknown` at the Exit Gate re-evaluation — escalate in following JSON format: + +```json +{ + "status": "escalation_needed", + "reason": "Binding decision violation", + "taskName": "[Task name being executed]", + "escalation_type": "binding_decision_violation", + "phase": "pre_implementation | exit_gate", + "plannedApproach": "[1–2 sentence summary of the planned or actual implementation approach]", + "failures": [ + { + "source": "[ADR file path with section hint, copied from Source column]", + "axis": "[Axis value copied from the Axis column]", + "decision": "[Decision text, copied from Decision column]", + "complianceCheck": "[Compliance Check predicate, copied from Compliance Check column]", + "evaluation": "N | Unknown", + "rationale": "[One line explaining why the implementation does not satisfy the check, or why it cannot be evaluated]" + } + ], + "user_decision_required": true, + "suggested_options": [ + "Adjust the implementation plan to satisfy the binding decision", + "Update the ADR (then update the work plan's ADR Bindings and this task's Binding Decisions)", + "Provide additional context that resolves the Unknown evaluation" + ] +} +``` + ## Exit Gate [BLOCKING] This gate runs immediately before producing the final JSON response. ☐ All task checkboxes completed with evidence (or `escalation_needed` triggered earlier) ☐ Implementation is consistent with the Investigation Notes recorded at Step 2 (when Investigation Targets were present) +☐ Every Binding Decisions Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes (when the task file has a Binding Decisions section). Re-evaluate here even when the pre-implementation check passed, because the implementation may have diverged from the planned approach ☐ Final response is a single JSON with `status: "completed"` or `status: "escalation_needed"` and matches the schema in Structured Response Specification -**ENFORCEMENT**: When any gate item is unchecked, produce the final response in the JSON format defined in Structured Response Specification with `status: "escalation_needed"`. +**ENFORCEMENT**: When any gate item is unchecked, produce the final response in the JSON format defined in Structured Response Specification with `status: "escalation_needed"`. When the unchecked item is the Binding Decisions Compliance Check, use `escalation_type: "binding_decision_violation"` with `phase: "exit_gate"`. For other gate failures (checkbox incompletion, divergence from Investigation Notes), use `escalation_type: "design_compliance_violation"` because the implementation has diverged from the planned approach. ## Scope Boundary (delegate to orchestrator) - Overall quality checks → handled by dedicated quality check agent diff --git a/dev-workflows-fullstack/agents/task-executor.md b/dev-workflows-fullstack/agents/task-executor.md index d614046..d4106a8 100644 --- a/dev-workflows-fullstack/agents/task-executor.md +++ b/dev-workflows-fullstack/agents/task-executor.md @@ -102,22 +102,11 @@ The task file plus its declared metadata sections form the source of truth for s - Safety guard usage from dynamic/untyped→concrete contract - Minor UI adjustments, message text changes -## Implementation Authority and Responsibility Boundaries +## Responsibility Boundaries -**Responsibility Scope**: Implementation and test creation (quality checks and commits out of scope) -**Basic Policy**: Start implementation immediately (assuming approved), escalate only for design deviation or shortcut fixes - -## Main Responsibilities - -1. **Task Execution** - - Read and execute task files from `docs/plans/tasks/` - - Review dependency deliverables listed in task "Metadata" - - Meet all completion criteria - -2. **Progress Management (3-location synchronized updates)** - - Checkboxes within task files - - Checkboxes and progress records in work plan documents - - States: `[ ]` not started → `[🔄]` in progress → `[x]` completed +**Scope**: Implementation and test creation. Quality checks and commits are handled by other agents. +**Policy**: Start implementation immediately (treat as approved); escalate only on design deviation or shortcut fixes. +**Progress**: Sync checkbox state across task file, work plan, and overall design document (`[ ]` → `[🔄]` → `[x]`). ## Workflow @@ -178,6 +167,18 @@ This gate runs only when the task file's "Investigation Targets" section lists a 2. **Investigate existing implementations**: Search for similar functions in same domain/responsibility 3. **Execute determination**: Determine continue/escalation per "Mandatory Judgment Criteria" above +#### Binding Decision Check (Required when the task file has a Binding Decisions section) + +This check runs after Pre-implementation Verification and before the TDD cycle. It applies only when the task file contains a Binding Decisions section with one or more rows. + +1. Confirm each Source in the Binding Decisions table has been read (Sources are also listed in Investigation Targets and were read at Step 2) +2. Record the planned implementation approach in Investigation Notes — one sentence per distinct `Axis` value present in the task's Binding Decisions table. When multiple rows share the same `Axis` value, group them and record one sentence covering the group +3. Evaluate each row's Compliance Check against the planned approach. Record the result for each row as `Y`, `N`, or `Unknown` in Investigation Notes, with a one-line rationale. Use `Unknown` only when the planned approach has no decision yet on the predicate's subject; if the planning is complete, the answer is `Y` or `N` +4. Per row, branch on the evaluation: + - `Y`: proceed + - `N`: stop implementation and produce the final response with `status: "escalation_needed"` and `escalation_type: "binding_decision_violation"` with `phase: "pre_implementation"` (see Binding Decision Violation Escalation in Structured Response Specification). `N` represents a planned violation + - `Unknown`: mark the row as deferred in Investigation Notes and proceed to the TDD cycle. The Exit Gate re-evaluates every row (including Unknown rows deferred from this step) against the final implementation and escalates if any remains `N` or `Unknown` at that point + #### Reference Representativeness (Applied During Implementation) When adopting a pattern or dependency from existing code, apply coding-principles "Reference Representativeness" at the point of adoption: @@ -219,14 +220,7 @@ Task complete when all checkbox items completed and operation verification compl For research tasks, includes creating deliverable files specified in metadata "Provides" section. ### 5. Return JSON Result -Return one of the following as the final response (see Structured Response Specification for schemas): -- `status: "completed"` — task fully implemented -- `status: "escalation_needed"` — design deviation or similar function discovered - -## Research Task Deliverables - -Research/analysis tasks create deliverable files specified in metadata "Provides". -Examples: `docs/plans/analysis/research-results.md`, `docs/plans/analysis/api-spec.md` +Return the final response per Structured Response Specification. For research/analysis tasks, also create the deliverable files declared in task metadata `Provides`. ## Structured Response Specification @@ -402,19 +396,50 @@ When a file outside the allowed list (see "File Scope Constraint" section) needs } ``` +#### 2-6. Binding Decision Violation Escalation +When one or more Compliance Checks in the task's Binding Decisions section trigger escalation — `N` at the pre-implementation check, or `N` or `Unknown` at the Exit Gate re-evaluation — escalate in following JSON format: + +```json +{ + "status": "escalation_needed", + "reason": "Binding decision violation", + "taskName": "[Task name being executed]", + "escalation_type": "binding_decision_violation", + "phase": "pre_implementation | exit_gate", + "plannedApproach": "[1–2 sentence summary of the planned or actual implementation approach]", + "failures": [ + { + "source": "[ADR file path with section hint, copied from Source column]", + "axis": "[Axis value copied from the Axis column]", + "decision": "[Decision text, copied from Decision column]", + "complianceCheck": "[Compliance Check predicate, copied from Compliance Check column]", + "evaluation": "N | Unknown", + "rationale": "[One line explaining why the implementation does not satisfy the check, or why it cannot be evaluated]" + } + ], + "user_decision_required": true, + "suggested_options": [ + "Adjust the implementation plan to satisfy the binding decision", + "Update the ADR (then update the work plan's ADR Bindings and this task's Binding Decisions)", + "Provide additional context that resolves the Unknown evaluation" + ] +} +``` + ## Exit Gate [BLOCKING] This gate runs immediately before producing the final JSON response. ☐ All task checkboxes completed with evidence (or `escalation_needed` triggered earlier) ☐ Implementation is consistent with the Investigation Notes recorded at Step 2 (when Investigation Targets were present) +☐ Every Binding Decisions Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes (when the task file has a Binding Decisions section). Re-evaluate here even when the pre-implementation check passed, because the implementation may have diverged from the planned approach ☐ Final response is a single JSON with `status: "completed"` or `status: "escalation_needed"` and matches the schema in Structured Response Specification -**ENFORCEMENT**: When any gate item is unchecked, produce the final response in the JSON format defined in Structured Response Specification with `status: "escalation_needed"`. +**ENFORCEMENT**: When any gate item is unchecked, produce the final response in the JSON format defined in Structured Response Specification with `status: "escalation_needed"`. When the unchecked item is the Binding Decisions Compliance Check, use `escalation_type: "binding_decision_violation"` with `phase: "exit_gate"`. For other gate failures (checkbox incompletion, divergence from Investigation Notes), use `escalation_type: "design_compliance_violation"` because the implementation has diverged from the planned approach. ## Execution Principles - Follow RED-GREEN-REFACTOR (see testing-principles skill) - Update progress checkboxes per step -- Escalate when: design deviation, similar functions found, test environment missing +- Escalate when: design deviation, similar functions found, test environment missing, binding decision violation - Stop after implementation and test creation — quality checks and commits are handled separately \ No newline at end of file diff --git a/dev-workflows-fullstack/agents/work-planner.md b/dev-workflows-fullstack/agents/work-planner.md index e3cf06f..98e915d 100644 --- a/dev-workflows-fullstack/agents/work-planner.md +++ b/dev-workflows-fullstack/agents/work-planner.md @@ -87,7 +87,9 @@ Read the Design Doc template from documentation-criteria skill to identify all s | Verification requirement | Verification methods, test boundaries, integration verification points | Verification/test task | | Prerequisite work | Migration steps, security measures, environment setup | Prerequisite task | -Map each extracted item to a covering task. Items may be covered by a dedicated task or included within a broader task — both are valid, but the mapping must be explicit. +Additionally, when these design-attention sections are non-N/A in the DD, always create Traceability rows for their content: Minimal Surface Alternatives (selected alternative), 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`). + +Map each extracted item to a covering task. Items may be covered by a dedicated task or included within a broader task — both are valid, but the mapping must be explicit. Each row must record the source DD path (matching one of the Related Documents entries) in the `Design Doc` column so downstream task generation can resolve the file unambiguously. Record the mapping in the Design-to-Plan Traceability table (see plan template). If an item has no covering task, set Gap Status to `gap` with justification in Notes. Gaps with justification require user confirmation before plan approval. @@ -124,6 +126,26 @@ For each qualifying boundary: Record the mapping in the **Connection Map** table (see plan template). Omit this section entirely when no qualifying boundary exists. +### 5c. Map ADR Decisions to Tasks (when ADR provided or referenced from Design Doc) + +When an ADR is among the inputs, or when the Design Doc lists ADRs under "Prerequisite ADRs", build the ADR Bindings table. This table is required so binding decisions propagate to each affected task in the downstream task generation phase. + +For each referenced ADR: +1. Resolve the ADR path (file convention: `docs/adr/ADR-[4-digit]-[title].md`): + - Full path (e.g., `docs/adr/ADR-0042-foo.md`) — use as-is + - ID only (e.g., `ADR-0042`) — glob `docs/adr/ADR-0042-*.md`; require exactly one match + - Filename without directory (e.g., `ADR-0042-foo.md`) — prepend `docs/adr/` + - Escalate when the glob returns 0 or 2+ matches, or when the resolved path does not exist + + Then read the ADR's Decision and Implementation Guidance sections +2. Extract decisions that are **implementation-binding** — i.e., they constrain one of five binding axes: placement, dependency direction, contract/schema shape, data flow, or persistence. Acceptance criteria and required behaviors are recorded in the Design Doc; this table covers only structural constraints from ADRs +3. For each binding decision, classify it under exactly one axis (`placement` | `dependency_direction` | `contract_schema` | `data_flow` | `persistence`) — this becomes the row's `Axis` value +4. For each binding decision, note which section it came from (`Decision` or `Implementation Guidance`) — this becomes the row's `Source Section` value +5. For each binding decision, identify the planned task(s) where the decision applies. Use Target files, layer, or component scope to determine relevance — layer/component-level mapping is sufficient at this stage +6. Record one row per binding decision in the **ADR Bindings** table (see plan template) + +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). @@ -302,6 +324,11 @@ When creating work plans, **Phase Structure Diagrams** and **Task Dependency Dia - [ ] Connection Map table complete (when implementation crosses packages/services) - [ ] Every boundary lists owner modules and expected signal - [ ] Every boundary maps to at least one covering task on each side +- [ ] ADR Bindings table complete (when ADR provided or referenced from Design Doc) + - [ ] Each row represents one implementation-binding decision (placement, dependency, contract, data flow, or persistence) + - [ ] Each row's `Axis` value is exactly one of `placement` | `dependency_direction` | `contract_schema` | `data_flow` | `persistence` + - [ ] Each row's `Source Section` is set to `Decision` or `Implementation Guidance` matching the actual location of the decision in the ADR + - [ ] Every row maps to at least one covering task - [ ] Verification Strategy extracted from Design Doc and included in plan header - [ ] Adopted Quality Assurance Mechanisms extracted from Design Doc and included in plan header - [ ] Phase structure matches implementation approach (vertical → value unit phases, horizontal → layer phases) diff --git a/dev-workflows-fullstack/skills/documentation-criteria/references/design-template.md b/dev-workflows-fullstack/skills/documentation-criteria/references/design-template.md index 9bfeba4..4344e12 100644 --- a/dev-workflows-fullstack/skills/documentation-criteria/references/design-template.md +++ b/dev-workflows-fullstack/skills/documentation-criteria/references/design-template.md @@ -30,7 +30,7 @@ unknowns: ### Prerequisite ADRs -- [ADR File Name]: [Related decision items] +- [docs/adr/ADR-XXXX.md]: [Related decision items] - Reference common technical ADRs when applicable ### External Resources Used 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 dc7a178..e78a4c1 100644 --- a/dev-workflows-fullstack/skills/documentation-criteria/references/plan-template.md +++ b/dev-workflows-fullstack/skills/documentation-criteria/references/plan-template.md @@ -39,9 +39,9 @@ Adopted quality gates for the change area. Each task in this plan must satisfy t Maps each Design Doc technical requirement to the covering task(s). One row per extracted item. Every row must have at least one covering task, or an explicit gap justification. -| DD Section | DD Item | Category | Covered By Task(s) | Gap Status | Notes | -|---|---|---|---|---|---| -| [Section name from DD] | [Specific item] | impl-target / connection-switching / contract-change / verification / prerequisite | [Phase X Task Y] | covered | | +| Design Doc | DD Section | DD Item | Category | Covered By Task(s) | Gap Status | Notes | +|---|---|---|---|---|---|---| +| [docs/design/XXX.md — one of the Related Documents above] | [Section name from DD] | [Specific item] | impl-target / connection-switching / contract-change / verification / prerequisite | [Phase X Task Y] | covered | | **Category values**: `impl-target` (implementation target), `connection-switching` (connection/switching/registration), `contract-change` (contract change and propagation), `verification` (verification requirement), `prerequisite` (prerequisite work) @@ -59,6 +59,18 @@ Include this section when a UI Spec is among the inputs. Maps each component doc **Gap Status values**: `covered` (task exists), `gap` (no task — requires justification in Notes, user confirmation required before plan approval) +## ADR Bindings + +Include this section when ADRs are provided as input or listed in the Design Doc's "Prerequisite ADRs" section. Maps each implementation-binding ADR decision to the task(s) it constrains. Omit the section when no ADR applies. + +A decision is **implementation-binding** when it constrains code placement, dependency direction, contract/schema shape, data flow, or persistence. Acceptance criteria and required behaviors are recorded in the Design Doc; this table covers only structural constraints from ADRs. + +| ADR | Source Section | Axis | Binding Decision | Covered By Task(s) | +|---|---|---|---|---| +| [docs/adr/ADR-XXXX.md] | Decision / Implementation Guidance | placement \| dependency_direction \| contract_schema \| data_flow \| persistence | [One implementation-binding decision sentence, copied or condensed from the named section] | [Phase X Task Y] | + +One row per binding decision. A single ADR can contribute multiple rows. A single task can appear in multiple rows. + ## Connection Map Include this section when the implementation crosses more than one package, service, or process boundary. Document each boundary. Omit the section when the implementation stays within a single package. 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 fac8370..8a29a9a 100644 --- a/dev-workflows-fullstack/skills/documentation-criteria/references/task-template.md +++ b/dev-workflows-fullstack/skills/documentation-criteria/references/task-template.md @@ -17,8 +17,17 @@ Metadata: 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] +## Binding Decisions +(Include this section when the work plan's ADR Bindings table covers this task. Omit otherwise.) + +Each row is an ADR decision the implementation in this task must comply with. + +| Source | Axis | Decision | Compliance Check | +|---|---|---|---| +| [docs/adr/ADR-XXXX.md (§ ) — substitute the section name (`Decision` or `Implementation Guidance`) from the matching work plan row] | [Axis value copied verbatim from the work plan's ADR Bindings row] | [Binding decision copied from the work plan's ADR Bindings row] | [Y/N-answerable positive predicate that evaluates whether the planned/final implementation satisfies the decision] | + ## Investigation Notes -(Implementation observations are appended here before implementation begins.) +(Implementation observations are appended here before implementation begins. When Binding Decisions exist, record the planned implementation approach and each Compliance Check result here.) ## Implementation Steps (TDD: Red-Green-Refactor) ### 1. Red Phase @@ -51,6 +60,7 @@ Files to read before starting implementation (file path, with optional search hi - [ ] All added tests pass - [ ] Operation verified per Operation Verification Methods above - [ ] Deliverables created (for research/design tasks) +- [ ] (When Binding Decisions exist) Every Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes (file:line, test result, or command output) ## Notes - Impact scope: [Areas where changes may propagate] diff --git a/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md index 89d7997..b84e79d 100644 --- a/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md @@ -7,8 +7,6 @@ description: Guides subagent coordination through implementation workflows. Use ## Role: The Orchestrator -**The orchestrator coordinates subagents like a conductor—directing the musicians without playing the instruments.** - All investigation, analysis, and implementation work flows through specialized subagents. ### First Action Rule @@ -26,19 +24,17 @@ When receiving a new task, pass user requirements directly to requirement-analyz ## Available Subagents -The following subagents are available: - -### Implementation Support Agents +Implementation support: 1. **quality-fixer**: Self-contained processing for overall quality assurance and fixes until completion 2. **task-decomposer**: Appropriate task decomposition of work plans 3. **task-executor**: Individual task execution and structured response 4. **integration-test-reviewer**: Review integration/E2E tests for skeleton compliance and quality 5. **security-reviewer**: Security compliance review against Design Doc and coding-principles after all tasks complete -### Document Creation Agents +Document creation: 6. **requirement-analyzer**: Requirement analysis and work scale determination 7. **codebase-analyzer**: Analyze existing codebase to produce focused guidance for technical design (data, contracts, dependencies, quality assurance mechanisms) -8. **ui-analyzer**: Read the project's external-resources file, fetch external UI sources (design origin, design system, guidelines) via MCP/URL/file, and analyze existing UI code (visual structure, layout state, props patterns, state matrices, display conditions, i18n format, accessibility, generated UI artifacts). Frontend/fullstack features; runs in parallel with codebase-analyzer. Uses `disallowedTools` to inherit MCP access +8. **ui-analyzer**: Read the project's external-resources file, fetch external UI sources (design origin, design system, guidelines) via MCP/URL/file, and analyze existing UI code. Frontend/fullstack features; runs in parallel with codebase-analyzer. Uses `disallowedTools` to inherit MCP access 9. **prd-creator**: Product Requirements Document creation 10. **ui-spec-designer**: UI Specification creation from PRD and optional prototype code (frontend/fullstack features) 11. **technical-designer**: ADR/Design Doc creation @@ -187,7 +183,7 @@ Subagents respond in JSON format. Key fields for orchestrator decisions: - **codebase-analyzer**: analysisScope.categoriesDetected, dataModel.detected, qualityAssurance (mechanisms[], domainConstraints[]), focusAreas[], existingElements count, limitations - **ui-analyzer**: analysisScope.uiConventions, externalResources (designOrigin/designSystem/guidelines/visualVerification with fetch_status), componentStructure[], propsPatterns[], cssLayout[], stateDisplay[], displayConditions[], i18n, accessibility[], generatedArtifacts[], focusAreas[] (raw fact_id; consumers apply `ui:` prefix when merging with codebase analysis facts), candidateWriteSet[] (with confidence labels), limitations - **code-verifier**: status (consistent/mostly_consistent/needs_review/inconsistent), consistencyScore, discrepancies[], reverseCoverage (including dataOperationsInCode, testBoundariesSectionPresent). Pre-implementation: verifies Design Doc claims against existing codebase. Post-implementation: verifies implementation consistency against Design Doc (pass `code_paths` scoped to changed files) -- **task-executor**: status (escalation_needed/completed), escalation_type (design_compliance_violation/similar_function_found/investigation_target_not_found/out_of_scope_file/dependency_version_uncertain), testsAdded, requiresTestReview +- **task-executor**: status (escalation_needed/completed), escalation_type (design_compliance_violation/similar_function_found/investigation_target_not_found/out_of_scope_file/dependency_version_uncertain/binding_decision_violation), testsAdded, requiresTestReview - **quality-fixer**: Input: `task_file` (path to current task file — always pass this in orchestrated flows). Status: approved/stub_detected/blocked. `stub_detected` → route back to task-executor with `incompleteImplementations[]` details for completion, then re-run quality-fixer. `blocked` → discriminate by `reason` field: `"Cannot determine due to unclear specification"` → read `blockingIssues[]` for specification details; `"Execution prerequisites not met"` → read `missingPrerequisites[]` with `resolutionSteps` — present these to the user as actionable next steps - **document-reviewer**: approvalReady (true/false) - **design-sync**: sync_status (synced/conflicts_found) @@ -202,17 +198,7 @@ requirement-analyzer follows the "completely self-contained" principle and proce #### How to Integrate Requirements -**Important**: To maximize accuracy, integrate requirements as complete sentences, including all contextual information communicated by the user. - -```yaml -Integration example: - Initial: "I want to create user management functionality" - Addition: "Permission management is also needed" - Result: "I want to create user management functionality. Permission management is also needed. - - Initial requirement: I want to create user management functionality - Additional requirement: Permission management is also needed" -``` +**Important**: To maximize accuracy, integrate requirements as complete sentences, including all contextual information communicated by the user. Result format: raw concatenation of all requirements, followed by a labeled summary (`Initial requirement: …` / `Additional requirement: …`). ### Update Mode for Document Generation Agents Document generation agents (work-planner, technical-designer, prd-creator) can update existing documents in `update` mode. @@ -422,11 +408,7 @@ Register overall phases using TaskCreate. Update each phase with TaskUpdate as i ## Important Constraints -- **Quality check is mandatory**: quality-fixer approval needed before commit -- **Structured response mandatory**: Information transmission between subagents in JSON format -- **Approval management**: Document creation → Execute document-reviewer → Get user approval before proceeding -- **Flow confirmation**: After getting approval, always check next step with work planning flow (large/medium/small scale) -- **Consistency verification**: Resolve subagent conflicts per Decision precedence (see Delegation Boundary section) +Recap (defined above): quality-fixer approval before commit; inter-agent communication is JSON; document-reviewer + user approval before proceeding; check next step against work planning flow after approval; resolve conflicts via Decision precedence. ## References diff --git a/dev-workflows/.claude-plugin/plugin.json b/dev-workflows/.claude-plugin/plugin.json index 45a67d5..d58e63d 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.19.1", + "version": "0.19.2", "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 aeff0d1..a385d3a 100644 --- a/dev-workflows/agents/task-decomposer.md +++ b/dev-workflows/agents/task-decomposer.md @@ -112,6 +112,7 @@ Decompose tasks based on implementation strategy patterns determined in implemen | Cross-package boundary implementation | Both sides of the boundary as listed in the work plan's Connection Map (owner modules and expected signal), the contract definition between them | | Bug fix / refactor | The affected code paths, related test coverage, error reproduction context | | Behavior replacement / rewrite | The existing implementation being replaced, its observable outputs, Design Doc Verification Strategy section | + | Task constrained by an ADR (work plan's ADR Bindings table covers this task) | The ADR file with section hint matching the row's `Source Section` value (e.g., `(§ Decision)` or `(§ Implementation Guidance)`) for each binding row covering this task | **Principles**: - Every task must have at least one Investigation Target (even if just the Design Doc) @@ -121,6 +122,8 @@ Decompose tasks based on implementation strategy patterns determined in implemen - When test skeletons exist for the task, always include them as Investigation Targets - When the work plan contains a UI Spec Component → Task Mapping table, propagate the matching component section to every task in that row (see UI Spec Propagation below) - When the work plan contains a Connection Map, propagate the boundary rows touching this task's target files (see Connection Map Propagation below) + - When the work plan contains an ADR Bindings table covering this task, propagate the matching rows (see ADR Binding Propagation below) + - When the work plan contains a Design-to-Plan Traceability table, propagate the matching DD section rows (see Design Traceability Propagation below) 7. **Implementation Pattern Consistency** When including implementation samples, MUST ensure strict compliance with the Design Doc implementation approach that forms the basis of the work plan @@ -173,6 +176,34 @@ When the work plan contains a Connection Map table, propagate boundary context t 3. **Add a "Boundary Context" note in the task body**: Record the boundary identifier and expected signal verbatim from the Connection Map row, so the executor knows what observable evidence the implementation must produce 4. **Skip when not provided**: If the work plan has no Connection Map, skip this propagation step +## ADR Binding Propagation + +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 +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 + - **Axis**: Copy the row's `Axis` value verbatim from the work plan row + - **Decision**: Copy the binding decision sentence verbatim from the work plan row + - **Compliance Check**: Write a Y/N-answerable positive predicate stating that the implementation satisfies the decision. One example per binding axis: + - `placement`: "Auth entrypoint is in `src/middleware/**`" + - `dependency_direction`: "The domain layer imports only from `src/domain/**` and `src/shared/**`" + - `contract_schema`: "API responses match the `ResponseEnvelope` schema" + - `data_flow`: "Session tokens are written exclusively through the Redis client" + - `persistence`: "User records are persisted only via the `UsersRepository` interface" + + When the decision cannot be verified by file:line or command alone, the predicate may rely on reasoned judgment, but it must remain Y/N-answerable +4. **Apply only when provided**: Run this propagation only when the work plan contains an ADR Bindings table + +## Design Traceability Propagation + +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])` +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 + ## Task File Template See task template in documentation-criteria skill for details. @@ -274,6 +305,11 @@ Please execute decomposed tasks according to the order. - [ ] Quality Assurance Mechanisms from work plan header propagated to relevant tasks - [ ] UI Spec Component → Task Mapping rows propagated to matching tasks (when work plan has the table) - [ ] Connection Map boundary rows propagated to matching tasks (when work plan has the table) +- [ ] Design-to-Plan Traceability rows propagated to matching tasks as Investigation Targets (when work plan has the table) +- [ ] ADR Bindings rows propagated to matching tasks as Binding Decisions (when work plan has the table) + - [ ] Source includes ADR path with section hint + - [ ] Axis copied verbatim from the work plan row to the task's Binding Decisions table + - [ ] 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) diff --git a/dev-workflows/agents/task-executor.md b/dev-workflows/agents/task-executor.md index d614046..d4106a8 100644 --- a/dev-workflows/agents/task-executor.md +++ b/dev-workflows/agents/task-executor.md @@ -102,22 +102,11 @@ The task file plus its declared metadata sections form the source of truth for s - Safety guard usage from dynamic/untyped→concrete contract - Minor UI adjustments, message text changes -## Implementation Authority and Responsibility Boundaries +## Responsibility Boundaries -**Responsibility Scope**: Implementation and test creation (quality checks and commits out of scope) -**Basic Policy**: Start implementation immediately (assuming approved), escalate only for design deviation or shortcut fixes - -## Main Responsibilities - -1. **Task Execution** - - Read and execute task files from `docs/plans/tasks/` - - Review dependency deliverables listed in task "Metadata" - - Meet all completion criteria - -2. **Progress Management (3-location synchronized updates)** - - Checkboxes within task files - - Checkboxes and progress records in work plan documents - - States: `[ ]` not started → `[🔄]` in progress → `[x]` completed +**Scope**: Implementation and test creation. Quality checks and commits are handled by other agents. +**Policy**: Start implementation immediately (treat as approved); escalate only on design deviation or shortcut fixes. +**Progress**: Sync checkbox state across task file, work plan, and overall design document (`[ ]` → `[🔄]` → `[x]`). ## Workflow @@ -178,6 +167,18 @@ This gate runs only when the task file's "Investigation Targets" section lists a 2. **Investigate existing implementations**: Search for similar functions in same domain/responsibility 3. **Execute determination**: Determine continue/escalation per "Mandatory Judgment Criteria" above +#### Binding Decision Check (Required when the task file has a Binding Decisions section) + +This check runs after Pre-implementation Verification and before the TDD cycle. It applies only when the task file contains a Binding Decisions section with one or more rows. + +1. Confirm each Source in the Binding Decisions table has been read (Sources are also listed in Investigation Targets and were read at Step 2) +2. Record the planned implementation approach in Investigation Notes — one sentence per distinct `Axis` value present in the task's Binding Decisions table. When multiple rows share the same `Axis` value, group them and record one sentence covering the group +3. Evaluate each row's Compliance Check against the planned approach. Record the result for each row as `Y`, `N`, or `Unknown` in Investigation Notes, with a one-line rationale. Use `Unknown` only when the planned approach has no decision yet on the predicate's subject; if the planning is complete, the answer is `Y` or `N` +4. Per row, branch on the evaluation: + - `Y`: proceed + - `N`: stop implementation and produce the final response with `status: "escalation_needed"` and `escalation_type: "binding_decision_violation"` with `phase: "pre_implementation"` (see Binding Decision Violation Escalation in Structured Response Specification). `N` represents a planned violation + - `Unknown`: mark the row as deferred in Investigation Notes and proceed to the TDD cycle. The Exit Gate re-evaluates every row (including Unknown rows deferred from this step) against the final implementation and escalates if any remains `N` or `Unknown` at that point + #### Reference Representativeness (Applied During Implementation) When adopting a pattern or dependency from existing code, apply coding-principles "Reference Representativeness" at the point of adoption: @@ -219,14 +220,7 @@ Task complete when all checkbox items completed and operation verification compl For research tasks, includes creating deliverable files specified in metadata "Provides" section. ### 5. Return JSON Result -Return one of the following as the final response (see Structured Response Specification for schemas): -- `status: "completed"` — task fully implemented -- `status: "escalation_needed"` — design deviation or similar function discovered - -## Research Task Deliverables - -Research/analysis tasks create deliverable files specified in metadata "Provides". -Examples: `docs/plans/analysis/research-results.md`, `docs/plans/analysis/api-spec.md` +Return the final response per Structured Response Specification. For research/analysis tasks, also create the deliverable files declared in task metadata `Provides`. ## Structured Response Specification @@ -402,19 +396,50 @@ When a file outside the allowed list (see "File Scope Constraint" section) needs } ``` +#### 2-6. Binding Decision Violation Escalation +When one or more Compliance Checks in the task's Binding Decisions section trigger escalation — `N` at the pre-implementation check, or `N` or `Unknown` at the Exit Gate re-evaluation — escalate in following JSON format: + +```json +{ + "status": "escalation_needed", + "reason": "Binding decision violation", + "taskName": "[Task name being executed]", + "escalation_type": "binding_decision_violation", + "phase": "pre_implementation | exit_gate", + "plannedApproach": "[1–2 sentence summary of the planned or actual implementation approach]", + "failures": [ + { + "source": "[ADR file path with section hint, copied from Source column]", + "axis": "[Axis value copied from the Axis column]", + "decision": "[Decision text, copied from Decision column]", + "complianceCheck": "[Compliance Check predicate, copied from Compliance Check column]", + "evaluation": "N | Unknown", + "rationale": "[One line explaining why the implementation does not satisfy the check, or why it cannot be evaluated]" + } + ], + "user_decision_required": true, + "suggested_options": [ + "Adjust the implementation plan to satisfy the binding decision", + "Update the ADR (then update the work plan's ADR Bindings and this task's Binding Decisions)", + "Provide additional context that resolves the Unknown evaluation" + ] +} +``` + ## Exit Gate [BLOCKING] This gate runs immediately before producing the final JSON response. ☐ All task checkboxes completed with evidence (or `escalation_needed` triggered earlier) ☐ Implementation is consistent with the Investigation Notes recorded at Step 2 (when Investigation Targets were present) +☐ Every Binding Decisions Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes (when the task file has a Binding Decisions section). Re-evaluate here even when the pre-implementation check passed, because the implementation may have diverged from the planned approach ☐ Final response is a single JSON with `status: "completed"` or `status: "escalation_needed"` and matches the schema in Structured Response Specification -**ENFORCEMENT**: When any gate item is unchecked, produce the final response in the JSON format defined in Structured Response Specification with `status: "escalation_needed"`. +**ENFORCEMENT**: When any gate item is unchecked, produce the final response in the JSON format defined in Structured Response Specification with `status: "escalation_needed"`. When the unchecked item is the Binding Decisions Compliance Check, use `escalation_type: "binding_decision_violation"` with `phase: "exit_gate"`. For other gate failures (checkbox incompletion, divergence from Investigation Notes), use `escalation_type: "design_compliance_violation"` because the implementation has diverged from the planned approach. ## Execution Principles - Follow RED-GREEN-REFACTOR (see testing-principles skill) - Update progress checkboxes per step -- Escalate when: design deviation, similar functions found, test environment missing +- Escalate when: design deviation, similar functions found, test environment missing, binding decision violation - Stop after implementation and test creation — quality checks and commits are handled separately \ No newline at end of file diff --git a/dev-workflows/agents/work-planner.md b/dev-workflows/agents/work-planner.md index e3cf06f..98e915d 100644 --- a/dev-workflows/agents/work-planner.md +++ b/dev-workflows/agents/work-planner.md @@ -87,7 +87,9 @@ Read the Design Doc template from documentation-criteria skill to identify all s | Verification requirement | Verification methods, test boundaries, integration verification points | Verification/test task | | Prerequisite work | Migration steps, security measures, environment setup | Prerequisite task | -Map each extracted item to a covering task. Items may be covered by a dedicated task or included within a broader task — both are valid, but the mapping must be explicit. +Additionally, when these design-attention sections are non-N/A in the DD, always create Traceability rows for their content: Minimal Surface Alternatives (selected alternative), 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`). + +Map each extracted item to a covering task. Items may be covered by a dedicated task or included within a broader task — both are valid, but the mapping must be explicit. Each row must record the source DD path (matching one of the Related Documents entries) in the `Design Doc` column so downstream task generation can resolve the file unambiguously. Record the mapping in the Design-to-Plan Traceability table (see plan template). If an item has no covering task, set Gap Status to `gap` with justification in Notes. Gaps with justification require user confirmation before plan approval. @@ -124,6 +126,26 @@ For each qualifying boundary: Record the mapping in the **Connection Map** table (see plan template). Omit this section entirely when no qualifying boundary exists. +### 5c. Map ADR Decisions to Tasks (when ADR provided or referenced from Design Doc) + +When an ADR is among the inputs, or when the Design Doc lists ADRs under "Prerequisite ADRs", build the ADR Bindings table. This table is required so binding decisions propagate to each affected task in the downstream task generation phase. + +For each referenced ADR: +1. Resolve the ADR path (file convention: `docs/adr/ADR-[4-digit]-[title].md`): + - Full path (e.g., `docs/adr/ADR-0042-foo.md`) — use as-is + - ID only (e.g., `ADR-0042`) — glob `docs/adr/ADR-0042-*.md`; require exactly one match + - Filename without directory (e.g., `ADR-0042-foo.md`) — prepend `docs/adr/` + - Escalate when the glob returns 0 or 2+ matches, or when the resolved path does not exist + + Then read the ADR's Decision and Implementation Guidance sections +2. Extract decisions that are **implementation-binding** — i.e., they constrain one of five binding axes: placement, dependency direction, contract/schema shape, data flow, or persistence. Acceptance criteria and required behaviors are recorded in the Design Doc; this table covers only structural constraints from ADRs +3. For each binding decision, classify it under exactly one axis (`placement` | `dependency_direction` | `contract_schema` | `data_flow` | `persistence`) — this becomes the row's `Axis` value +4. For each binding decision, note which section it came from (`Decision` or `Implementation Guidance`) — this becomes the row's `Source Section` value +5. For each binding decision, identify the planned task(s) where the decision applies. Use Target files, layer, or component scope to determine relevance — layer/component-level mapping is sufficient at this stage +6. Record one row per binding decision in the **ADR Bindings** table (see plan template) + +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). @@ -302,6 +324,11 @@ When creating work plans, **Phase Structure Diagrams** and **Task Dependency Dia - [ ] Connection Map table complete (when implementation crosses packages/services) - [ ] Every boundary lists owner modules and expected signal - [ ] Every boundary maps to at least one covering task on each side +- [ ] ADR Bindings table complete (when ADR provided or referenced from Design Doc) + - [ ] Each row represents one implementation-binding decision (placement, dependency, contract, data flow, or persistence) + - [ ] Each row's `Axis` value is exactly one of `placement` | `dependency_direction` | `contract_schema` | `data_flow` | `persistence` + - [ ] Each row's `Source Section` is set to `Decision` or `Implementation Guidance` matching the actual location of the decision in the ADR + - [ ] Every row maps to at least one covering task - [ ] Verification Strategy extracted from Design Doc and included in plan header - [ ] Adopted Quality Assurance Mechanisms extracted from Design Doc and included in plan header - [ ] Phase structure matches implementation approach (vertical → value unit phases, horizontal → layer phases) diff --git a/dev-workflows/skills/documentation-criteria/references/design-template.md b/dev-workflows/skills/documentation-criteria/references/design-template.md index 9bfeba4..4344e12 100644 --- a/dev-workflows/skills/documentation-criteria/references/design-template.md +++ b/dev-workflows/skills/documentation-criteria/references/design-template.md @@ -30,7 +30,7 @@ unknowns: ### Prerequisite ADRs -- [ADR File Name]: [Related decision items] +- [docs/adr/ADR-XXXX.md]: [Related decision items] - Reference common technical ADRs when applicable ### External Resources Used diff --git a/dev-workflows/skills/documentation-criteria/references/plan-template.md b/dev-workflows/skills/documentation-criteria/references/plan-template.md index dc7a178..e78a4c1 100644 --- a/dev-workflows/skills/documentation-criteria/references/plan-template.md +++ b/dev-workflows/skills/documentation-criteria/references/plan-template.md @@ -39,9 +39,9 @@ Adopted quality gates for the change area. Each task in this plan must satisfy t Maps each Design Doc technical requirement to the covering task(s). One row per extracted item. Every row must have at least one covering task, or an explicit gap justification. -| DD Section | DD Item | Category | Covered By Task(s) | Gap Status | Notes | -|---|---|---|---|---|---| -| [Section name from DD] | [Specific item] | impl-target / connection-switching / contract-change / verification / prerequisite | [Phase X Task Y] | covered | | +| Design Doc | DD Section | DD Item | Category | Covered By Task(s) | Gap Status | Notes | +|---|---|---|---|---|---|---| +| [docs/design/XXX.md — one of the Related Documents above] | [Section name from DD] | [Specific item] | impl-target / connection-switching / contract-change / verification / prerequisite | [Phase X Task Y] | covered | | **Category values**: `impl-target` (implementation target), `connection-switching` (connection/switching/registration), `contract-change` (contract change and propagation), `verification` (verification requirement), `prerequisite` (prerequisite work) @@ -59,6 +59,18 @@ Include this section when a UI Spec is among the inputs. Maps each component doc **Gap Status values**: `covered` (task exists), `gap` (no task — requires justification in Notes, user confirmation required before plan approval) +## ADR Bindings + +Include this section when ADRs are provided as input or listed in the Design Doc's "Prerequisite ADRs" section. Maps each implementation-binding ADR decision to the task(s) it constrains. Omit the section when no ADR applies. + +A decision is **implementation-binding** when it constrains code placement, dependency direction, contract/schema shape, data flow, or persistence. Acceptance criteria and required behaviors are recorded in the Design Doc; this table covers only structural constraints from ADRs. + +| ADR | Source Section | Axis | Binding Decision | Covered By Task(s) | +|---|---|---|---|---| +| [docs/adr/ADR-XXXX.md] | Decision / Implementation Guidance | placement \| dependency_direction \| contract_schema \| data_flow \| persistence | [One implementation-binding decision sentence, copied or condensed from the named section] | [Phase X Task Y] | + +One row per binding decision. A single ADR can contribute multiple rows. A single task can appear in multiple rows. + ## Connection Map Include this section when the implementation crosses more than one package, service, or process boundary. Document each boundary. Omit the section when the implementation stays within a single package. diff --git a/dev-workflows/skills/documentation-criteria/references/task-template.md b/dev-workflows/skills/documentation-criteria/references/task-template.md index fac8370..8a29a9a 100644 --- a/dev-workflows/skills/documentation-criteria/references/task-template.md +++ b/dev-workflows/skills/documentation-criteria/references/task-template.md @@ -17,8 +17,17 @@ Metadata: 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] +## Binding Decisions +(Include this section when the work plan's ADR Bindings table covers this task. Omit otherwise.) + +Each row is an ADR decision the implementation in this task must comply with. + +| Source | Axis | Decision | Compliance Check | +|---|---|---|---| +| [docs/adr/ADR-XXXX.md (§ ) — substitute the section name (`Decision` or `Implementation Guidance`) from the matching work plan row] | [Axis value copied verbatim from the work plan's ADR Bindings row] | [Binding decision copied from the work plan's ADR Bindings row] | [Y/N-answerable positive predicate that evaluates whether the planned/final implementation satisfies the decision] | + ## Investigation Notes -(Implementation observations are appended here before implementation begins.) +(Implementation observations are appended here before implementation begins. When Binding Decisions exist, record the planned implementation approach and each Compliance Check result here.) ## Implementation Steps (TDD: Red-Green-Refactor) ### 1. Red Phase @@ -51,6 +60,7 @@ Files to read before starting implementation (file path, with optional search hi - [ ] All added tests pass - [ ] Operation verified per Operation Verification Methods above - [ ] Deliverables created (for research/design tasks) +- [ ] (When Binding Decisions exist) Every Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes (file:line, test result, or command output) ## Notes - Impact scope: [Areas where changes may propagate] diff --git a/dev-workflows/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows/skills/subagents-orchestration-guide/SKILL.md index 89d7997..b84e79d 100644 --- a/dev-workflows/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows/skills/subagents-orchestration-guide/SKILL.md @@ -7,8 +7,6 @@ description: Guides subagent coordination through implementation workflows. Use ## Role: The Orchestrator -**The orchestrator coordinates subagents like a conductor—directing the musicians without playing the instruments.** - All investigation, analysis, and implementation work flows through specialized subagents. ### First Action Rule @@ -26,19 +24,17 @@ When receiving a new task, pass user requirements directly to requirement-analyz ## Available Subagents -The following subagents are available: - -### Implementation Support Agents +Implementation support: 1. **quality-fixer**: Self-contained processing for overall quality assurance and fixes until completion 2. **task-decomposer**: Appropriate task decomposition of work plans 3. **task-executor**: Individual task execution and structured response 4. **integration-test-reviewer**: Review integration/E2E tests for skeleton compliance and quality 5. **security-reviewer**: Security compliance review against Design Doc and coding-principles after all tasks complete -### Document Creation Agents +Document creation: 6. **requirement-analyzer**: Requirement analysis and work scale determination 7. **codebase-analyzer**: Analyze existing codebase to produce focused guidance for technical design (data, contracts, dependencies, quality assurance mechanisms) -8. **ui-analyzer**: Read the project's external-resources file, fetch external UI sources (design origin, design system, guidelines) via MCP/URL/file, and analyze existing UI code (visual structure, layout state, props patterns, state matrices, display conditions, i18n format, accessibility, generated UI artifacts). Frontend/fullstack features; runs in parallel with codebase-analyzer. Uses `disallowedTools` to inherit MCP access +8. **ui-analyzer**: Read the project's external-resources file, fetch external UI sources (design origin, design system, guidelines) via MCP/URL/file, and analyze existing UI code. Frontend/fullstack features; runs in parallel with codebase-analyzer. Uses `disallowedTools` to inherit MCP access 9. **prd-creator**: Product Requirements Document creation 10. **ui-spec-designer**: UI Specification creation from PRD and optional prototype code (frontend/fullstack features) 11. **technical-designer**: ADR/Design Doc creation @@ -187,7 +183,7 @@ Subagents respond in JSON format. Key fields for orchestrator decisions: - **codebase-analyzer**: analysisScope.categoriesDetected, dataModel.detected, qualityAssurance (mechanisms[], domainConstraints[]), focusAreas[], existingElements count, limitations - **ui-analyzer**: analysisScope.uiConventions, externalResources (designOrigin/designSystem/guidelines/visualVerification with fetch_status), componentStructure[], propsPatterns[], cssLayout[], stateDisplay[], displayConditions[], i18n, accessibility[], generatedArtifacts[], focusAreas[] (raw fact_id; consumers apply `ui:` prefix when merging with codebase analysis facts), candidateWriteSet[] (with confidence labels), limitations - **code-verifier**: status (consistent/mostly_consistent/needs_review/inconsistent), consistencyScore, discrepancies[], reverseCoverage (including dataOperationsInCode, testBoundariesSectionPresent). Pre-implementation: verifies Design Doc claims against existing codebase. Post-implementation: verifies implementation consistency against Design Doc (pass `code_paths` scoped to changed files) -- **task-executor**: status (escalation_needed/completed), escalation_type (design_compliance_violation/similar_function_found/investigation_target_not_found/out_of_scope_file/dependency_version_uncertain), testsAdded, requiresTestReview +- **task-executor**: status (escalation_needed/completed), escalation_type (design_compliance_violation/similar_function_found/investigation_target_not_found/out_of_scope_file/dependency_version_uncertain/binding_decision_violation), testsAdded, requiresTestReview - **quality-fixer**: Input: `task_file` (path to current task file — always pass this in orchestrated flows). Status: approved/stub_detected/blocked. `stub_detected` → route back to task-executor with `incompleteImplementations[]` details for completion, then re-run quality-fixer. `blocked` → discriminate by `reason` field: `"Cannot determine due to unclear specification"` → read `blockingIssues[]` for specification details; `"Execution prerequisites not met"` → read `missingPrerequisites[]` with `resolutionSteps` — present these to the user as actionable next steps - **document-reviewer**: approvalReady (true/false) - **design-sync**: sync_status (synced/conflicts_found) @@ -202,17 +198,7 @@ requirement-analyzer follows the "completely self-contained" principle and proce #### How to Integrate Requirements -**Important**: To maximize accuracy, integrate requirements as complete sentences, including all contextual information communicated by the user. - -```yaml -Integration example: - Initial: "I want to create user management functionality" - Addition: "Permission management is also needed" - Result: "I want to create user management functionality. Permission management is also needed. - - Initial requirement: I want to create user management functionality - Additional requirement: Permission management is also needed" -``` +**Important**: To maximize accuracy, integrate requirements as complete sentences, including all contextual information communicated by the user. Result format: raw concatenation of all requirements, followed by a labeled summary (`Initial requirement: …` / `Additional requirement: …`). ### Update Mode for Document Generation Agents Document generation agents (work-planner, technical-designer, prd-creator) can update existing documents in `update` mode. @@ -422,11 +408,7 @@ Register overall phases using TaskCreate. Update each phase with TaskUpdate as i ## Important Constraints -- **Quality check is mandatory**: quality-fixer approval needed before commit -- **Structured response mandatory**: Information transmission between subagents in JSON format -- **Approval management**: Document creation → Execute document-reviewer → Get user approval before proceeding -- **Flow confirmation**: After getting approval, always check next step with work planning flow (large/medium/small scale) -- **Consistency verification**: Resolve subagent conflicts per Decision precedence (see Delegation Boundary section) +Recap (defined above): quality-fixer approval before commit; inter-agent communication is JSON; document-reviewer + user approval before proceeding; check next step against work planning flow after approval; resolve conflicts via Decision precedence. ## References diff --git a/package.json b/package.json index dc56919..7757933 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "claude-code-workflows", - "version": "0.19.1", + "version": "0.19.2", "private": true, "type": "module", "engines": { diff --git a/skills/documentation-criteria/references/design-template.md b/skills/documentation-criteria/references/design-template.md index 9bfeba4..4344e12 100644 --- a/skills/documentation-criteria/references/design-template.md +++ b/skills/documentation-criteria/references/design-template.md @@ -30,7 +30,7 @@ unknowns: ### Prerequisite ADRs -- [ADR File Name]: [Related decision items] +- [docs/adr/ADR-XXXX.md]: [Related decision items] - Reference common technical ADRs when applicable ### External Resources Used diff --git a/skills/documentation-criteria/references/plan-template.md b/skills/documentation-criteria/references/plan-template.md index dc7a178..e78a4c1 100644 --- a/skills/documentation-criteria/references/plan-template.md +++ b/skills/documentation-criteria/references/plan-template.md @@ -39,9 +39,9 @@ Adopted quality gates for the change area. Each task in this plan must satisfy t Maps each Design Doc technical requirement to the covering task(s). One row per extracted item. Every row must have at least one covering task, or an explicit gap justification. -| DD Section | DD Item | Category | Covered By Task(s) | Gap Status | Notes | -|---|---|---|---|---|---| -| [Section name from DD] | [Specific item] | impl-target / connection-switching / contract-change / verification / prerequisite | [Phase X Task Y] | covered | | +| Design Doc | DD Section | DD Item | Category | Covered By Task(s) | Gap Status | Notes | +|---|---|---|---|---|---|---| +| [docs/design/XXX.md — one of the Related Documents above] | [Section name from DD] | [Specific item] | impl-target / connection-switching / contract-change / verification / prerequisite | [Phase X Task Y] | covered | | **Category values**: `impl-target` (implementation target), `connection-switching` (connection/switching/registration), `contract-change` (contract change and propagation), `verification` (verification requirement), `prerequisite` (prerequisite work) @@ -59,6 +59,18 @@ Include this section when a UI Spec is among the inputs. Maps each component doc **Gap Status values**: `covered` (task exists), `gap` (no task — requires justification in Notes, user confirmation required before plan approval) +## ADR Bindings + +Include this section when ADRs are provided as input or listed in the Design Doc's "Prerequisite ADRs" section. Maps each implementation-binding ADR decision to the task(s) it constrains. Omit the section when no ADR applies. + +A decision is **implementation-binding** when it constrains code placement, dependency direction, contract/schema shape, data flow, or persistence. Acceptance criteria and required behaviors are recorded in the Design Doc; this table covers only structural constraints from ADRs. + +| ADR | Source Section | Axis | Binding Decision | Covered By Task(s) | +|---|---|---|---|---| +| [docs/adr/ADR-XXXX.md] | Decision / Implementation Guidance | placement \| dependency_direction \| contract_schema \| data_flow \| persistence | [One implementation-binding decision sentence, copied or condensed from the named section] | [Phase X Task Y] | + +One row per binding decision. A single ADR can contribute multiple rows. A single task can appear in multiple rows. + ## Connection Map Include this section when the implementation crosses more than one package, service, or process boundary. Document each boundary. Omit the section when the implementation stays within a single package. diff --git a/skills/documentation-criteria/references/task-template.md b/skills/documentation-criteria/references/task-template.md index fac8370..8a29a9a 100644 --- a/skills/documentation-criteria/references/task-template.md +++ b/skills/documentation-criteria/references/task-template.md @@ -17,8 +17,17 @@ Metadata: 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] +## Binding Decisions +(Include this section when the work plan's ADR Bindings table covers this task. Omit otherwise.) + +Each row is an ADR decision the implementation in this task must comply with. + +| Source | Axis | Decision | Compliance Check | +|---|---|---|---| +| [docs/adr/ADR-XXXX.md (§ ) — substitute the section name (`Decision` or `Implementation Guidance`) from the matching work plan row] | [Axis value copied verbatim from the work plan's ADR Bindings row] | [Binding decision copied from the work plan's ADR Bindings row] | [Y/N-answerable positive predicate that evaluates whether the planned/final implementation satisfies the decision] | + ## Investigation Notes -(Implementation observations are appended here before implementation begins.) +(Implementation observations are appended here before implementation begins. When Binding Decisions exist, record the planned implementation approach and each Compliance Check result here.) ## Implementation Steps (TDD: Red-Green-Refactor) ### 1. Red Phase @@ -51,6 +60,7 @@ Files to read before starting implementation (file path, with optional search hi - [ ] All added tests pass - [ ] Operation verified per Operation Verification Methods above - [ ] Deliverables created (for research/design tasks) +- [ ] (When Binding Decisions exist) Every Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes (file:line, test result, or command output) ## Notes - Impact scope: [Areas where changes may propagate] diff --git a/skills/subagents-orchestration-guide/SKILL.md b/skills/subagents-orchestration-guide/SKILL.md index 89d7997..b84e79d 100644 --- a/skills/subagents-orchestration-guide/SKILL.md +++ b/skills/subagents-orchestration-guide/SKILL.md @@ -7,8 +7,6 @@ description: Guides subagent coordination through implementation workflows. Use ## Role: The Orchestrator -**The orchestrator coordinates subagents like a conductor—directing the musicians without playing the instruments.** - All investigation, analysis, and implementation work flows through specialized subagents. ### First Action Rule @@ -26,19 +24,17 @@ When receiving a new task, pass user requirements directly to requirement-analyz ## Available Subagents -The following subagents are available: - -### Implementation Support Agents +Implementation support: 1. **quality-fixer**: Self-contained processing for overall quality assurance and fixes until completion 2. **task-decomposer**: Appropriate task decomposition of work plans 3. **task-executor**: Individual task execution and structured response 4. **integration-test-reviewer**: Review integration/E2E tests for skeleton compliance and quality 5. **security-reviewer**: Security compliance review against Design Doc and coding-principles after all tasks complete -### Document Creation Agents +Document creation: 6. **requirement-analyzer**: Requirement analysis and work scale determination 7. **codebase-analyzer**: Analyze existing codebase to produce focused guidance for technical design (data, contracts, dependencies, quality assurance mechanisms) -8. **ui-analyzer**: Read the project's external-resources file, fetch external UI sources (design origin, design system, guidelines) via MCP/URL/file, and analyze existing UI code (visual structure, layout state, props patterns, state matrices, display conditions, i18n format, accessibility, generated UI artifacts). Frontend/fullstack features; runs in parallel with codebase-analyzer. Uses `disallowedTools` to inherit MCP access +8. **ui-analyzer**: Read the project's external-resources file, fetch external UI sources (design origin, design system, guidelines) via MCP/URL/file, and analyze existing UI code. Frontend/fullstack features; runs in parallel with codebase-analyzer. Uses `disallowedTools` to inherit MCP access 9. **prd-creator**: Product Requirements Document creation 10. **ui-spec-designer**: UI Specification creation from PRD and optional prototype code (frontend/fullstack features) 11. **technical-designer**: ADR/Design Doc creation @@ -187,7 +183,7 @@ Subagents respond in JSON format. Key fields for orchestrator decisions: - **codebase-analyzer**: analysisScope.categoriesDetected, dataModel.detected, qualityAssurance (mechanisms[], domainConstraints[]), focusAreas[], existingElements count, limitations - **ui-analyzer**: analysisScope.uiConventions, externalResources (designOrigin/designSystem/guidelines/visualVerification with fetch_status), componentStructure[], propsPatterns[], cssLayout[], stateDisplay[], displayConditions[], i18n, accessibility[], generatedArtifacts[], focusAreas[] (raw fact_id; consumers apply `ui:` prefix when merging with codebase analysis facts), candidateWriteSet[] (with confidence labels), limitations - **code-verifier**: status (consistent/mostly_consistent/needs_review/inconsistent), consistencyScore, discrepancies[], reverseCoverage (including dataOperationsInCode, testBoundariesSectionPresent). Pre-implementation: verifies Design Doc claims against existing codebase. Post-implementation: verifies implementation consistency against Design Doc (pass `code_paths` scoped to changed files) -- **task-executor**: status (escalation_needed/completed), escalation_type (design_compliance_violation/similar_function_found/investigation_target_not_found/out_of_scope_file/dependency_version_uncertain), testsAdded, requiresTestReview +- **task-executor**: status (escalation_needed/completed), escalation_type (design_compliance_violation/similar_function_found/investigation_target_not_found/out_of_scope_file/dependency_version_uncertain/binding_decision_violation), testsAdded, requiresTestReview - **quality-fixer**: Input: `task_file` (path to current task file — always pass this in orchestrated flows). Status: approved/stub_detected/blocked. `stub_detected` → route back to task-executor with `incompleteImplementations[]` details for completion, then re-run quality-fixer. `blocked` → discriminate by `reason` field: `"Cannot determine due to unclear specification"` → read `blockingIssues[]` for specification details; `"Execution prerequisites not met"` → read `missingPrerequisites[]` with `resolutionSteps` — present these to the user as actionable next steps - **document-reviewer**: approvalReady (true/false) - **design-sync**: sync_status (synced/conflicts_found) @@ -202,17 +198,7 @@ requirement-analyzer follows the "completely self-contained" principle and proce #### How to Integrate Requirements -**Important**: To maximize accuracy, integrate requirements as complete sentences, including all contextual information communicated by the user. - -```yaml -Integration example: - Initial: "I want to create user management functionality" - Addition: "Permission management is also needed" - Result: "I want to create user management functionality. Permission management is also needed. - - Initial requirement: I want to create user management functionality - Additional requirement: Permission management is also needed" -``` +**Important**: To maximize accuracy, integrate requirements as complete sentences, including all contextual information communicated by the user. Result format: raw concatenation of all requirements, followed by a labeled summary (`Initial requirement: …` / `Additional requirement: …`). ### Update Mode for Document Generation Agents Document generation agents (work-planner, technical-designer, prd-creator) can update existing documents in `update` mode. @@ -422,11 +408,7 @@ Register overall phases using TaskCreate. Update each phase with TaskUpdate as i ## Important Constraints -- **Quality check is mandatory**: quality-fixer approval needed before commit -- **Structured response mandatory**: Information transmission between subagents in JSON format -- **Approval management**: Document creation → Execute document-reviewer → Get user approval before proceeding -- **Flow confirmation**: After getting approval, always check next step with work planning flow (large/medium/small scale) -- **Consistency verification**: Resolve subagent conflicts per Decision precedence (see Delegation Boundary section) +Recap (defined above): quality-fixer approval before commit; inter-agent communication is JSON; document-reviewer + user approval before proceeding; check next step against work planning flow after approval; resolve conflicts via Decision precedence. ## References