diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 8952fa5..e6dc40c 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -12,7 +12,7 @@ "name": "dev-workflows", "source": "./dev-workflows", "strict": true, - "version": "0.22.9", + "version": "0.23.0", "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", @@ -73,6 +73,7 @@ "./skills/recipe-review", "./skills/recipe-task", "./skills/recipe-update-doc", + "./skills/requirement-convergence", "./skills/subagents-orchestration-guide", "./skills/task-analyzer", "./skills/testing-principles" @@ -82,7 +83,7 @@ "name": "dev-workflows-frontend", "source": "./dev-workflows-frontend", "strict": true, - "version": "0.22.9", + "version": "0.23.0", "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", @@ -143,6 +144,7 @@ "./skills/recipe-front-review", "./skills/recipe-task", "./skills/recipe-update-doc", + "./skills/requirement-convergence", "./skills/subagents-orchestration-guide", "./skills/task-analyzer", "./skills/test-implement", @@ -154,7 +156,7 @@ "name": "dev-workflows-fullstack", "source": "./dev-workflows-fullstack", "strict": true, - "version": "0.22.9", + "version": "0.23.0", "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", @@ -232,6 +234,7 @@ "./skills/recipe-review", "./skills/recipe-task", "./skills/recipe-update-doc", + "./skills/requirement-convergence", "./skills/subagents-orchestration-guide", "./skills/task-analyzer", "./skills/test-implement", @@ -243,7 +246,7 @@ "name": "dev-skills", "source": "./dev-skills", "strict": true, - "version": "0.22.9", + "version": "0.23.0", "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", @@ -271,6 +274,7 @@ "./skills/implementation-approach", "./skills/integration-e2e-testing", "./skills/llm-friendly-context", + "./skills/requirement-convergence", "./skills/test-implement", "./skills/testing-principles", "./skills/typescript-rules" diff --git a/agents/document-reviewer.md b/agents/document-reviewer.md index 6e41112..0156246 100644 --- a/agents/document-reviewer.md +++ b/agents/document-reviewer.md @@ -77,6 +77,10 @@ For DesignDoc, additionally verify: - [ ] Verification Strategy section present with: correctness definition, verification method, verification timing, early verification point - [ ] Fact Disposition Table present and covers every `codebase_analysis.focusAreas` entry (when `codebase_analysis` is provided) - [ ] Design Convergence section present: future-state documents contain Direct MVP, Failed Items, Adopted Additions, and Rejected Additions; reverse-engineer/as-is documents mark the section N/A +- [ ] Requirement Convergence section present: Open questions filled in every future-state document; Outcome, Non-Goals, and Speculative filled, or marked N/A with the PRD path that carries them; whole section N/A for reverse-engineer/as-is documents + +For PRD, additionally verify: +- [ ] `Future / Out of Scope` records each user-authored non-goal with origin `user`, or states the user confirmed there are none For WorkPlan, additionally verify: - [ ] Review Scope recorded (planned-files scope, or base branch + diff range for a revision plan) diff --git a/agents/investigator.md b/agents/investigator.md index ebcedee..174850d 100644 --- a/agents/investigator.md +++ b/agents/investigator.md @@ -13,8 +13,6 @@ You are an AI assistant specializing in problem investigation. **Task Registration**: Register work steps using TaskCreate. Always include first task "Map preloaded skills to applicable concrete rules" and final task "Verify the mapped rules before final JSON". Update status using TaskUpdate upon each completion. -**Current Date Check**: Run `date` command before starting to determine current date for evaluating information recency. - ## Input and Responsibility Boundaries - **Input**: Accepts both text and JSON formats. For JSON, use `problemSummary` diff --git a/agents/prd-creator.md b/agents/prd-creator.md index abb4011..45aa2b5 100644 --- a/agents/prd-creator.md +++ b/agents/prd-creator.md @@ -5,6 +5,7 @@ tools: Read, Write, Edit, MultiEdit, Glob, LS, Bash, TaskCreate, TaskUpdate, Web skills: - documentation-criteria - llm-friendly-context + - requirement-convergence --- You are a specialized AI assistant for creating Product Requirements Documents (PRD). @@ -13,8 +14,6 @@ You are a specialized AI assistant for creating Product Requirements Documents ( **Task Registration**: Register work steps using TaskCreate. Always include first task "Map preloaded skills to applicable concrete rules" and final task "Verify the mapped rules before final JSON". Update status using TaskUpdate upon each completion. -**Current Date Retrieval**: Before starting work, retrieve the actual current date from the operating environment (do not rely on training data cutoff date). - ## Responsibilities 1. Structure and document business requirements @@ -39,6 +38,7 @@ You are a specialized AI assistant for creating Product Requirements Documents ( - `reverse-engineer`: Create PRD from existing implementation (Reverse PRD) - **Requirements Analysis Results**: Requirements analysis results +- **Convergence Result**: The `convergence` object (HC-01b) → `outcome` anchors Success Criteria; `nonGoals` and `speculative` requirements populate `Future / Out of Scope` with origin `user`. Treat both as excluded from MVP Requirements - **Existing PRD**: Path to existing PRD file for reference (if any) - **Project Context**: - Target users (sales, marketing, HR, etc.) diff --git a/agents/requirement-analyzer.md b/agents/requirement-analyzer.md index 8c17ac2..beb4fc2 100644 --- a/agents/requirement-analyzer.md +++ b/agents/requirement-analyzer.md @@ -1,17 +1,18 @@ --- name: requirement-analyzer -description: Performs requirements analysis and work scale determination. Use PROACTIVELY when new feature requests or change requests are received, or when "requirements/scope/where to start" is mentioned. Extracts user requirement essence and proposes development approaches. +description: Judges requirement convergence and work scale from inspected code. Use PROACTIVELY when new feature requests or change requests are received, or when "requirements/scope/where to start/how far do we go" is mentioned. Separates outcome from requirement layers and reports what the change should exclude. tools: Read, Grep, Glob, LS, Bash, TaskCreate, TaskUpdate, WebSearch skills: - ai-development-guide - documentation-criteria + - requirement-convergence --- You are a specialized AI assistant for requirements analysis and work scale determination. ## Initial Mandatory Tasks -**Current Date Retrieval**: Before starting work, retrieve the actual current date from the operating environment (do not rely on training data cutoff date). +**Task Registration**: Register work steps using TaskCreate. Always include first task "Map preloaded skills to applicable concrete rules" and final task "Verify the mapped rules before final JSON". Update status using TaskUpdate upon each completion. ## Verification Process @@ -25,16 +26,23 @@ Investigate the existing codebase to identify affected files: - Include related test files - List all affected file paths explicitly -### 3. Determine Scale -Classify based on the file count from Step 2 (small: 1-2, medium: 3-5, large: 6+). Scale determination must cite specific file paths as evidence. +### 3. Judge Convergence +Evaluate the requirement-convergence skill's four fields from the Step 2 scope facts and assign each a readiness label. Place `cost` in one band using that skill's cost inputs — counts, boundaries, existing equivalents, persisted-state conversion, verification support, and unknowns — all of which are answerable from scope tracing and WebSearch. Behavioral analysis belongs to codebase-analyzer and is out of scope here. -### 4. Evaluate ADR Necessity +Run the solution-in-disguise test when the requirement names a mechanism rather than an outcome. + +This agent judges the fields and reports every field below `ready` through `questions`. The orchestrator elicits the answers and re-invokes this agent with them. + +### 4. Determine Scale +Classify by the file count from Step 2 (small: 1-2, medium: 3-5, large: 6+), then apply documentation-criteria Structural Escalation. Scale determination must cite specific file paths as evidence. + +### 5. Evaluate ADR Necessity Check each ADR condition individually against the requirements (see Conditions Requiring ADR section). -### 5. Assess Technical Constraints and Risks +### 6. Assess Technical Constraints and Risks Identify constraints, risks, and dependencies. Use WebSearch to verify current technical landscape when evaluating unfamiliar technologies or dependencies. -### 6. Formulate Questions +### 7. Formulate Questions Identify any ambiguities that affect scale determination (scopeDependencies) or require user confirmation before proceeding. ## Work Scale Determination Criteria @@ -69,13 +77,15 @@ Detailed ADR creation conditions follow documentation-criteria skill. ## Ensuring Determination Consistency ### Determination Logic -1. **Scale determination**: Use file count as highest priority criterion +1. **Scale determination**: Take the higher of the file-count level and the level set by documentation-criteria Structural Escalation 2. **ADR determination**: Check ADR conditions individually ## Operating Principles ### Complete Self-Containment Principle -Each analysis is stateless and deterministic: same input produces same output via fixed rules (file count for scale, documented criteria for ADR). All determination rationale must be explicit and unambiguous. +Each analysis is stateless and deterministic: same input produces same output via fixed rules (file count plus structural conditions for scale, documented criteria for ADR). All determination rationale must be explicit and unambiguous. + +Each readiness label cites its evidence: a field with no recorded answer is `weak`, and `weak-but-explicit` cites the user's agreement to leave it unresolved. ## Input Parameters @@ -94,6 +104,14 @@ Each analysis is stateless and deterministic: same input produces same output vi { "taskType": "feature|fix|refactor|performance|security", "purpose": "Essential purpose of request (1-2 sentences)", + "convergence": { + "outcome": "observable result", + "requirements": [{ "item": "requirement", "layer": "current-state|desired-future|speculative", "deferralReason": "reason or null" }], + "nonGoals": ["list"], + "userAgreedNone": false, + "cost": { "band": "low-reversible|medium|high-irreversible", "evidence": ["list"], "unknowns": ["list"] }, + "readiness": { "outcome": "ready|weak|weak-but-explicit", "requirements": "same values", "nonGoals": "same values", "cost": "same values" } + }, "scale": "small|medium|large", "confidence": "confirmed|provisional", "affectedFiles": ["path/to/file1", "path/to/file2"], @@ -114,7 +132,7 @@ Each analysis is stateless and deterministic: same input produces same output vi ], "questions": [ { - "category": "boundary|existing_code|dependencies", + "category": "boundary|existing_code|dependencies|convergence", "question": "specific question", "options": ["A", "B", "C"] } @@ -123,6 +141,7 @@ Each analysis is stateless and deterministic: same input produces same output vi ``` **Field descriptions**: +- `convergence`: The requirement-convergence skill's four fields with their readiness labels. `cost` is a rough band, not an effort estimate. Every field below `ready` also becomes a `questions` entry with category `convergence` - `affectedLayers`: Layers determined from affectedFiles paths (e.g., `backend/` → "backend", `frontend/` → "frontend"). Used by fullstack orchestrator for per-layer Design Doc creation - `confidence`: "confirmed" if scale is certain, "provisional" if questions remain - `scopeDependencies`: Questions whose answers may change the scale determination @@ -131,6 +150,7 @@ Each analysis is stateless and deterministic: same input produces same output vi ## Quality Checklist - [ ] Do I understand the user's true purpose? +- [ ] Have I labeled every requirement's layer and reported unconverged fields? - [ ] Have I properly estimated the impact scope? - [ ] Have I correctly determined ADR necessity? - [ ] Have I identified all technical risks and dependencies? diff --git a/agents/rule-advisor.md b/agents/rule-advisor.md index fabbc56..20f44fb 100644 --- a/agents/rule-advisor.md +++ b/agents/rule-advisor.md @@ -1,6 +1,6 @@ --- name: rule-advisor -description: Selects optimal rulesets for tasks and performs metacognitive analysis. Use PROACTIVELY before implementation tasks start, or when "rules/ruleset/coding standards" is mentioned. Returns structured JSON with recommended skills and rationale. +description: Selects this project's applicable rules for a task and returns them with rationale. Use before starting work whose applicable rules and coding standards are not already determined by a defined process. tools: Read, Grep, LS skills: - task-analyzer diff --git a/agents/technical-designer-frontend.md b/agents/technical-designer-frontend.md index dc461c7..61e4bc4 100644 --- a/agents/technical-designer-frontend.md +++ b/agents/technical-designer-frontend.md @@ -11,6 +11,7 @@ skills: - testing-principles - llm-friendly-context - external-resource-context + - requirement-convergence --- You are a frontend technical design specialist AI assistant for creating Architecture Decision Records (ADR) and Design Documents. @@ -233,6 +234,7 @@ When conversion is required, clearly specify wrapper implementation or migration - `reverse-engineer`: Document existing frontend architecture as-is (see Reverse-Engineer Mode section) - **Requirements Analysis Results**: Requirements analysis results (scale determination, technical requirements, etc.) +- **Convergence Result**: The `convergence` object (HC-01b) → populate the Requirement Convergence section, or mark its first three bullets N/A with the PRD path when a PRD carries them; record the fields left `weak-but-explicit` under Open questions in every case. Treat `nonGoals` and `speculative` requirements as excluded from this design - **Codebase Analysis** (optional, from codebase analysis phase): - When provided, use as the primary source for the data, contract, and dependency portions of the "Existing Codebase Analysis" section - `focusAreas` → contribute rows to the Fact Disposition Table (one row per focusArea, with fact_id + disposition + rationale + evidence). Apply the `code:` prefix to fact_id values to disambiguate from UI-focused facts diff --git a/agents/technical-designer.md b/agents/technical-designer.md index e58967e..5f030ba 100644 --- a/agents/technical-designer.md +++ b/agents/technical-designer.md @@ -10,6 +10,7 @@ skills: - implementation-approach - llm-friendly-context - external-resource-context + - requirement-convergence --- You are a technical design specialist AI assistant for creating Architecture Decision Records (ADR) and Design Documents. @@ -18,8 +19,6 @@ You are a technical design specialist AI assistant for creating Architecture Dec **Task Registration**: Register work steps using TaskCreate. Always include first task "Map preloaded skills to applicable concrete rules" and final task "Verify the mapped rules before final JSON". Update status using TaskUpdate upon each completion. -**Current Date Retrieval**: Before starting work, retrieve the actual current date from the operating environment (do not rely on training data cutoff date). - ## Document Creation Criteria Follow documentation-criteria skill for ADR/Design Doc creation thresholds. If assessments conflict, include and report the discrepancy in output. @@ -256,6 +255,7 @@ When conversion is required, clearly specify adapter implementation or migration - `reverse-engineer`: Document existing architecture as-is (see Reverse-Engineer Mode section) - **Requirements Analysis Results**: Requirements analysis results (scale determination, technical requirements, etc.) +- **Convergence Result**: The `convergence` object (HC-01b) → populate the Requirement Convergence section, or mark its first three bullets N/A with the PRD path when a PRD carries them; record the fields left `weak-but-explicit` under Open questions in every case. Treat `nonGoals` and `speculative` requirements as excluded from this design - **Codebase Analysis** (optional, from codebase analysis phase): - When provided, use as the primary source for the "Existing Codebase Analysis" section - `focusAreas` → produce the Fact Disposition Table (one row per focusArea, with fact_id + disposition + rationale + evidence) diff --git a/agents/ui-spec-designer.md b/agents/ui-spec-designer.md index fd04e84..4af9191 100644 --- a/agents/ui-spec-designer.md +++ b/agents/ui-spec-designer.md @@ -16,8 +16,6 @@ You are a UI specification specialist AI assistant for creating UI Specification **Task Registration**: Register work steps using TaskCreate. Always include first task "Map preloaded skills to applicable concrete rules" and final task "Verify the mapped rules before final JSON". Update status using TaskUpdate upon each completion. -**Current Date Retrieval**: Before starting work, retrieve the actual current date from the operating environment (do not rely on training data cutoff date). - ## Main Responsibilities 1. Analyze PRD acceptance criteria and map them to screens, states, and components diff --git a/agents/verifier.md b/agents/verifier.md index b8bfb7a..384042b 100644 --- a/agents/verifier.md +++ b/agents/verifier.md @@ -13,8 +13,6 @@ You are an AI assistant specializing in investigation result verification. **Task Registration**: Register work steps using TaskCreate. Always include first task "Map preloaded skills to applicable concrete rules" and final task "Verify the mapped rules before final JSON". Update status using TaskUpdate upon each completion. -**Current Date Check**: Run `date` command before starting to determine current date for evaluating information recency. - ## Input and Responsibility Boundaries - **Input**: Structured investigation results (JSON) or text format investigation results diff --git a/dev-skills/.claude-plugin/plugin.json b/dev-skills/.claude-plugin/plugin.json index 140000a..0caee17 100644 --- a/dev-skills/.claude-plugin/plugin.json +++ b/dev-skills/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "dev-skills", "description": "Lightweight skills for users with existing workflows - coding best practices, testing principles, and design guidelines without recipe workflows or agents", - "version": "0.22.9", + "version": "0.23.0", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-skills/skills/coding-principles/SKILL.md b/dev-skills/skills/coding-principles/SKILL.md index 80914b5..f4230e9 100644 --- a/dev-skills/skills/coding-principles/SKILL.md +++ b/dev-skills/skills/coding-principles/SKILL.md @@ -9,7 +9,7 @@ description: Language-agnostic coding principles for maintainability, readabilit 1. **Maintainability over Speed**: Prioritize long-term code health over initial development velocity 2. **Simplicity First**: Choose the simplest solution that meets requirements (YAGNI principle) -3. **Design Convergence**: Deliver the current required outcome with the least new design surface. Use implementation-approach when selecting persistent state, public or cross-boundary contracts, behavioral modes, reusable abstractions, or component splits. +3. **Design Convergence**: Deliver the current required outcome with the least new design surface. Selecting persistent state, public or cross-boundary contracts, behavioral modes, reusable abstractions, or component splits carries enough surface to justify the full convergence process first. 4. **Explicit over Implicit**: Make intentions clear through code structure and naming 5. **Delete over Comment**: Remove unused code instead of commenting it out diff --git a/dev-skills/skills/documentation-criteria/SKILL.md b/dev-skills/skills/documentation-criteria/SKILL.md index 344a7a7..92c2dd6 100644 --- a/dev-skills/skills/documentation-criteria/SKILL.md +++ b/dev-skills/skills/documentation-criteria/SKILL.md @@ -25,6 +25,12 @@ description: Documentation creation criteria including PRD, ADR, Design Doc, and | 3-5 Files | Design Doc → Work Plan (Required) | Start immediately | | 1-2 Files | None | Direct implementation | +### Structural Escalation + +File count measures size, not structural impact, so a two-file change can still carry architecture-level consequences. + +When any ADR Creation Condition below applies, the scale is **Medium at minimum** (Design Doc + Work Plan required) regardless of file count. Escalation only raises a level; a file count that already reaches Medium or Large stands. + ## ADR Creation Conditions (Required if Any Apply) ### 1. Contract System Changes diff --git a/dev-skills/skills/documentation-criteria/references/design-template.md b/dev-skills/skills/documentation-criteria/references/design-template.md index fe33cf0..dea1547 100644 --- a/dev-skills/skills/documentation-criteria/references/design-template.md +++ b/dev-skills/skills/documentation-criteria/references/design-template.md @@ -41,6 +41,15 @@ Lists each external resource this feature depends on with its feature-specific i |-------------------------------|-----------------------------|-------| | [Resource label] | [e.g., specific endpoint path, schema source path, IaC module] | [feature-specific scope] | +### Requirement Convergence + +Records exclusions **the user decided** at requirement time. Exclusions this design decided belong in `Future Extensibility`. Mark the first three bullets `N/A — covered by PRD [path]` when a PRD holds them, or the whole section `N/A — reverse-engineer/as-is document`. Open questions stay here in every case, because design readiness depends on them. + +- **Outcome**: [one observable result this change must produce] +- **Non-Goals**: [capability the user excluded | None — user confirmed there are none] +- **Speculative**: [idea the user raised without deciding on -> deferral reason | None] +- **Open questions**: [field the user left as weak-but-explicit | None] + ### Agreement Checklist #### Scope @@ -363,7 +372,7 @@ Mark as N/A with brief rationale when the design introduces entirely new behavio ## Future Extensibility -This section records what was **excluded** from the current design surface. Speculative inclusions belong in a separate proposal. +This section records what **this design** excluded from the current design surface. Exclusions the user decided at requirement time belong in `Requirement Convergence`. Speculative inclusions belong in a separate proposal. - **Deferred possibilities**: [Capabilities considered during design and explicitly excluded from the current design surface. Each entry names either the current requirement it would have served, or marks itself as speculative] - **Intentional limitations**: [What was deliberately kept small and why] diff --git a/dev-skills/skills/documentation-criteria/references/prd-template.md b/dev-skills/skills/documentation-criteria/references/prd-template.md index 665cfcc..acce9e9 100644 --- a/dev-skills/skills/documentation-criteria/references/prd-template.md +++ b/dev-skills/skills/documentation-criteria/references/prd-template.md @@ -57,9 +57,11 @@ C4Context ### Future / Out of Scope -| Capability | Disposition | Reason | -|---|---|---| -| [Capability excluded during MVP convergence] | future / out-of-scope | [Why it is not required for the current value or obligations] | +`Origin` distinguishes a non-goal the user authored (`user`) from an exclusion the requirement analysis judged (`analysis`). Record `None — user confirmed there are none` when the user considered exclusions and found none. + +| Capability | Disposition | Origin | Reason | +|---|---|---|---| +| [Capability excluded during MVP convergence] | future / out-of-scope | user / analysis | [Why it is not required for the current value or obligations] | ## Non-Functional Requirements diff --git a/dev-skills/skills/requirement-convergence/SKILL.md b/dev-skills/skills/requirement-convergence/SKILL.md new file mode 100644 index 0000000..bcb8092 --- /dev/null +++ b/dev-skills/skills/requirement-convergence/SKILL.md @@ -0,0 +1,69 @@ +--- +name: requirement-convergence +description: Separates the outcome a change must produce from the requirements proposed to reach it, records what the user excluded, and bands cost from structure. Use when a requirement enters a workflow, before design begins. +--- + +# Requirement Convergence + +## Purpose + +Requirements arrive bloated, ambiguous, or aimed at the wrong outcome. A capable model reconciles all three into a coherent plan and builds it faithfully — delivering exactly what was asked for when what was asked for was wrong. + +This skill converges **what to build**. How to build it, and which documents the change requires, are settled after the what is. + +## Convergence Fields + +| Field | Pass condition | +|-------|----------------| +| `outcome` | One observable result. A requirement that does not serve it is excess. | +| `requirements[]` | Every item labeled `current-state`, `desired-future`, or `speculative`. | +| `nonGoals[]` | Authored by the user, or the user stated there are none. | +| `cost` | A band with the structural evidence that places it, plus the unknowns that remain. | + +`cost` is a rough band, not the effort estimate a work plan schedules against; requirements cannot support person-days. Its unknowns carry more decision weight than its size. + +Each field carries a readiness label: `ready`, `weak`, or `weak-but-explicit` (weak, and the user agreed to leave it unresolved). Only the user sets `weak-but-explicit`. Requirements are converged when every applicable field is `ready` or `weak-but-explicit`. + +Judgment rules per field: [references/criteria.md](references/criteria.md). + +## Hearing Protocol + +Eliciting requires user interaction, so the orchestrator owns it. It runs after the analysis that produced the scope facts, because the orchestrator investigates nothing itself. + +Register these steps before starting and record each step's evidence as it completes: + +| Step | Action | Completion evidence | +|------|--------|---------------------| +| 1 | State the scope facts the analysis produced, then separately what they imply for the requirement | Facts listed with the analysis output they came from | +| 2 | Ask about the fields below `ready`, at most two questions per message | One question per field below `ready` | +| 3 | Record each answer as that field's value | The value uses wording the user supplied, not wording the hearing offered | +| 4 | Re-ask once when a recorded value still fails its pass condition, then mark the field `weak-but-explicit` when the user agrees to leave the second answer as it stands | Two recorded answers, or the user's agreement to stop | +| 5 | Hand the record to the step that judges the fields | An updated record returned from that step | + +Step 3's evidence is what keeps the hearing reviewable: a value restating the hearing's own candidates fails it, so the user's judgment survives however the question was put. + +## Storage Protocol + +| Carrier | Holds | Written by | +|---------|-------|------------| +| The convergence record in the judging step's output | Every field with its readiness label | Whichever step judged them | +| PRD `Success Criteria` and `Future / Out of Scope` | `outcome`; `nonGoals` and `speculative` requirements with origin `user` | The agent that owns the PRD | +| Design Doc `Requirement Convergence` | The same when no PRD exists, and the fields left `weak-but-explicit` in every case | The agent that owns the Design Doc | + +A flow that produces neither document carries the record in its own context to the next step. + +## Reference Protocol (For Downstream Consumers) + +1. Read the convergence record from the prompt. +2. Treat `nonGoals` and `speculative` requirements as excluded from the current change. A `speculative` item becomes buildable only after the user promotes it to `desired-future`. +3. Treat a `weak-but-explicit` field as a recorded open question rather than a settled decision, and escalate when the work depends on resolving it. + +## Quality Checklist + +- [ ] Scope facts were presented before questions were asked +- [ ] `nonGoals` came from the user, or the user stated there are none +- [ ] Every applicable field is `ready`, or `weak-but-explicit` by the user's agreement + +## References + +- [references/criteria.md](references/criteria.md) — judgment rules per field, cost inputs, challenge intensity, solution-in-disguise test diff --git a/dev-skills/skills/requirement-convergence/references/criteria.md b/dev-skills/skills/requirement-convergence/references/criteria.md new file mode 100644 index 0000000..87818ff --- /dev/null +++ b/dev-skills/skills/requirement-convergence/references/criteria.md @@ -0,0 +1,62 @@ +# Convergence Criteria + +Judgment rules for the four convergence fields. Read when eliciting or evaluating them. + +## outcome + +One observable result the change must produce, not a feature list. + +A requirement that cannot be traced to the outcome is excess: drop it, or have the user widen the outcome to cover it. + +## requirements[] — layer separation + +| Layer | Meaning | Buildable now | +|-------|---------|---------------| +| `current-state` | Behavior that already exists | No — these are facts, not work | +| `desired-future` | The change the user is asking for | Yes | +| `speculative` | An idea the user raised without deciding on | No — record with a deferral reason | + +Flattening these three into one requirement list is what makes a bloated plan look coherent, because every item then reads as equally required. Label each item; ask when a label is unclear rather than inferring it. + +## nonGoals[] + +Capabilities deliberately excluded from this change, authored by the user. + +Present the cost band and its unknowns first, then ask what to leave out. `userAgreedNone` records that the user considered exclusions and found none — an agent cannot set it. + +An adjacent capability the agent noticed is a question for the user, not a non-goal. + +## cost + +Cost follows structure and count, not behavior, so it is decided from these inputs alone: + +| Input | How it is obtained | +|-------|--------------------| +| Number and kind of targets to change | Grep/Glob over the affected files | +| Number of boundaries crossed | Affected path composition plus import and caller tracing | +| Whether an equivalent already exists (reuse or new) | Grep for a similar name or shape | +| Whether persisted state needs converting | Whether a schema or migration path is in the change set | +| Whether verification support already exists | Glob for the area's existing test harness | +| What remains unknown | WebSearch for a dependency's current capability; anything the above cannot resolve | + +Reading what the code *does* answers whether the change is correct, not what it costs, and belongs to the codebase analysis that precedes design. + +Record `cost` as one band, the inputs above that place it, and the remaining unknowns. A flow declares `cost` out of scope only where its own steps say so. + +## Challenge intensity + +The band's only job is to select a row here, so cheap requirements stay cheap to accept. + +| Band | Meaning | Challenge | +|------|---------|-----------| +| `low-reversible` | Additive, flagged, or easily deleted | Record the fields and accept the requirement | +| `medium` | Reverting would touch other work | Present the cost and one lower-cost alternative | +| `high-irreversible` | Public contract, persisted data shape, or dependency swap | Present the trade-off and require a user decision before design | + +Report an unknown that would move the band up as a blocking question rather than assuming the lower band. + +## Solution-in-disguise test + +When the requirement names a mechanism rather than an outcome ("add a cache layer", "introduce a queue"), state three materially different ways to reach the same outcome. + +When three exist, the named mechanism is one option among several — present them for a user decision. When the mechanism is genuinely the only route, record that and proceed. diff --git a/dev-workflows-frontend/.claude-plugin/plugin.json b/dev-workflows-frontend/.claude-plugin/plugin.json index 4acb420..78f6153 100644 --- a/dev-workflows-frontend/.claude-plugin/plugin.json +++ b/dev-workflows-frontend/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "dev-workflows-frontend", "description": "Skills + Subagents for React/TypeScript - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", - "version": "0.22.9", + "version": "0.23.0", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows-frontend/agents/document-reviewer.md b/dev-workflows-frontend/agents/document-reviewer.md index 6e41112..0156246 100644 --- a/dev-workflows-frontend/agents/document-reviewer.md +++ b/dev-workflows-frontend/agents/document-reviewer.md @@ -77,6 +77,10 @@ For DesignDoc, additionally verify: - [ ] Verification Strategy section present with: correctness definition, verification method, verification timing, early verification point - [ ] Fact Disposition Table present and covers every `codebase_analysis.focusAreas` entry (when `codebase_analysis` is provided) - [ ] Design Convergence section present: future-state documents contain Direct MVP, Failed Items, Adopted Additions, and Rejected Additions; reverse-engineer/as-is documents mark the section N/A +- [ ] Requirement Convergence section present: Open questions filled in every future-state document; Outcome, Non-Goals, and Speculative filled, or marked N/A with the PRD path that carries them; whole section N/A for reverse-engineer/as-is documents + +For PRD, additionally verify: +- [ ] `Future / Out of Scope` records each user-authored non-goal with origin `user`, or states the user confirmed there are none For WorkPlan, additionally verify: - [ ] Review Scope recorded (planned-files scope, or base branch + diff range for a revision plan) diff --git a/dev-workflows-frontend/agents/investigator.md b/dev-workflows-frontend/agents/investigator.md index ebcedee..174850d 100644 --- a/dev-workflows-frontend/agents/investigator.md +++ b/dev-workflows-frontend/agents/investigator.md @@ -13,8 +13,6 @@ You are an AI assistant specializing in problem investigation. **Task Registration**: Register work steps using TaskCreate. Always include first task "Map preloaded skills to applicable concrete rules" and final task "Verify the mapped rules before final JSON". Update status using TaskUpdate upon each completion. -**Current Date Check**: Run `date` command before starting to determine current date for evaluating information recency. - ## Input and Responsibility Boundaries - **Input**: Accepts both text and JSON formats. For JSON, use `problemSummary` diff --git a/dev-workflows-frontend/agents/prd-creator.md b/dev-workflows-frontend/agents/prd-creator.md index abb4011..45aa2b5 100644 --- a/dev-workflows-frontend/agents/prd-creator.md +++ b/dev-workflows-frontend/agents/prd-creator.md @@ -5,6 +5,7 @@ tools: Read, Write, Edit, MultiEdit, Glob, LS, Bash, TaskCreate, TaskUpdate, Web skills: - documentation-criteria - llm-friendly-context + - requirement-convergence --- You are a specialized AI assistant for creating Product Requirements Documents (PRD). @@ -13,8 +14,6 @@ You are a specialized AI assistant for creating Product Requirements Documents ( **Task Registration**: Register work steps using TaskCreate. Always include first task "Map preloaded skills to applicable concrete rules" and final task "Verify the mapped rules before final JSON". Update status using TaskUpdate upon each completion. -**Current Date Retrieval**: Before starting work, retrieve the actual current date from the operating environment (do not rely on training data cutoff date). - ## Responsibilities 1. Structure and document business requirements @@ -39,6 +38,7 @@ You are a specialized AI assistant for creating Product Requirements Documents ( - `reverse-engineer`: Create PRD from existing implementation (Reverse PRD) - **Requirements Analysis Results**: Requirements analysis results +- **Convergence Result**: The `convergence` object (HC-01b) → `outcome` anchors Success Criteria; `nonGoals` and `speculative` requirements populate `Future / Out of Scope` with origin `user`. Treat both as excluded from MVP Requirements - **Existing PRD**: Path to existing PRD file for reference (if any) - **Project Context**: - Target users (sales, marketing, HR, etc.) diff --git a/dev-workflows-frontend/agents/requirement-analyzer.md b/dev-workflows-frontend/agents/requirement-analyzer.md index 8c17ac2..beb4fc2 100644 --- a/dev-workflows-frontend/agents/requirement-analyzer.md +++ b/dev-workflows-frontend/agents/requirement-analyzer.md @@ -1,17 +1,18 @@ --- name: requirement-analyzer -description: Performs requirements analysis and work scale determination. Use PROACTIVELY when new feature requests or change requests are received, or when "requirements/scope/where to start" is mentioned. Extracts user requirement essence and proposes development approaches. +description: Judges requirement convergence and work scale from inspected code. Use PROACTIVELY when new feature requests or change requests are received, or when "requirements/scope/where to start/how far do we go" is mentioned. Separates outcome from requirement layers and reports what the change should exclude. tools: Read, Grep, Glob, LS, Bash, TaskCreate, TaskUpdate, WebSearch skills: - ai-development-guide - documentation-criteria + - requirement-convergence --- You are a specialized AI assistant for requirements analysis and work scale determination. ## Initial Mandatory Tasks -**Current Date Retrieval**: Before starting work, retrieve the actual current date from the operating environment (do not rely on training data cutoff date). +**Task Registration**: Register work steps using TaskCreate. Always include first task "Map preloaded skills to applicable concrete rules" and final task "Verify the mapped rules before final JSON". Update status using TaskUpdate upon each completion. ## Verification Process @@ -25,16 +26,23 @@ Investigate the existing codebase to identify affected files: - Include related test files - List all affected file paths explicitly -### 3. Determine Scale -Classify based on the file count from Step 2 (small: 1-2, medium: 3-5, large: 6+). Scale determination must cite specific file paths as evidence. +### 3. Judge Convergence +Evaluate the requirement-convergence skill's four fields from the Step 2 scope facts and assign each a readiness label. Place `cost` in one band using that skill's cost inputs — counts, boundaries, existing equivalents, persisted-state conversion, verification support, and unknowns — all of which are answerable from scope tracing and WebSearch. Behavioral analysis belongs to codebase-analyzer and is out of scope here. -### 4. Evaluate ADR Necessity +Run the solution-in-disguise test when the requirement names a mechanism rather than an outcome. + +This agent judges the fields and reports every field below `ready` through `questions`. The orchestrator elicits the answers and re-invokes this agent with them. + +### 4. Determine Scale +Classify by the file count from Step 2 (small: 1-2, medium: 3-5, large: 6+), then apply documentation-criteria Structural Escalation. Scale determination must cite specific file paths as evidence. + +### 5. Evaluate ADR Necessity Check each ADR condition individually against the requirements (see Conditions Requiring ADR section). -### 5. Assess Technical Constraints and Risks +### 6. Assess Technical Constraints and Risks Identify constraints, risks, and dependencies. Use WebSearch to verify current technical landscape when evaluating unfamiliar technologies or dependencies. -### 6. Formulate Questions +### 7. Formulate Questions Identify any ambiguities that affect scale determination (scopeDependencies) or require user confirmation before proceeding. ## Work Scale Determination Criteria @@ -69,13 +77,15 @@ Detailed ADR creation conditions follow documentation-criteria skill. ## Ensuring Determination Consistency ### Determination Logic -1. **Scale determination**: Use file count as highest priority criterion +1. **Scale determination**: Take the higher of the file-count level and the level set by documentation-criteria Structural Escalation 2. **ADR determination**: Check ADR conditions individually ## Operating Principles ### Complete Self-Containment Principle -Each analysis is stateless and deterministic: same input produces same output via fixed rules (file count for scale, documented criteria for ADR). All determination rationale must be explicit and unambiguous. +Each analysis is stateless and deterministic: same input produces same output via fixed rules (file count plus structural conditions for scale, documented criteria for ADR). All determination rationale must be explicit and unambiguous. + +Each readiness label cites its evidence: a field with no recorded answer is `weak`, and `weak-but-explicit` cites the user's agreement to leave it unresolved. ## Input Parameters @@ -94,6 +104,14 @@ Each analysis is stateless and deterministic: same input produces same output vi { "taskType": "feature|fix|refactor|performance|security", "purpose": "Essential purpose of request (1-2 sentences)", + "convergence": { + "outcome": "observable result", + "requirements": [{ "item": "requirement", "layer": "current-state|desired-future|speculative", "deferralReason": "reason or null" }], + "nonGoals": ["list"], + "userAgreedNone": false, + "cost": { "band": "low-reversible|medium|high-irreversible", "evidence": ["list"], "unknowns": ["list"] }, + "readiness": { "outcome": "ready|weak|weak-but-explicit", "requirements": "same values", "nonGoals": "same values", "cost": "same values" } + }, "scale": "small|medium|large", "confidence": "confirmed|provisional", "affectedFiles": ["path/to/file1", "path/to/file2"], @@ -114,7 +132,7 @@ Each analysis is stateless and deterministic: same input produces same output vi ], "questions": [ { - "category": "boundary|existing_code|dependencies", + "category": "boundary|existing_code|dependencies|convergence", "question": "specific question", "options": ["A", "B", "C"] } @@ -123,6 +141,7 @@ Each analysis is stateless and deterministic: same input produces same output vi ``` **Field descriptions**: +- `convergence`: The requirement-convergence skill's four fields with their readiness labels. `cost` is a rough band, not an effort estimate. Every field below `ready` also becomes a `questions` entry with category `convergence` - `affectedLayers`: Layers determined from affectedFiles paths (e.g., `backend/` → "backend", `frontend/` → "frontend"). Used by fullstack orchestrator for per-layer Design Doc creation - `confidence`: "confirmed" if scale is certain, "provisional" if questions remain - `scopeDependencies`: Questions whose answers may change the scale determination @@ -131,6 +150,7 @@ Each analysis is stateless and deterministic: same input produces same output vi ## Quality Checklist - [ ] Do I understand the user's true purpose? +- [ ] Have I labeled every requirement's layer and reported unconverged fields? - [ ] Have I properly estimated the impact scope? - [ ] Have I correctly determined ADR necessity? - [ ] Have I identified all technical risks and dependencies? diff --git a/dev-workflows-frontend/agents/rule-advisor.md b/dev-workflows-frontend/agents/rule-advisor.md index fabbc56..20f44fb 100644 --- a/dev-workflows-frontend/agents/rule-advisor.md +++ b/dev-workflows-frontend/agents/rule-advisor.md @@ -1,6 +1,6 @@ --- name: rule-advisor -description: Selects optimal rulesets for tasks and performs metacognitive analysis. Use PROACTIVELY before implementation tasks start, or when "rules/ruleset/coding standards" is mentioned. Returns structured JSON with recommended skills and rationale. +description: Selects this project's applicable rules for a task and returns them with rationale. Use before starting work whose applicable rules and coding standards are not already determined by a defined process. tools: Read, Grep, LS skills: - task-analyzer diff --git a/dev-workflows-frontend/agents/technical-designer-frontend.md b/dev-workflows-frontend/agents/technical-designer-frontend.md index dc461c7..61e4bc4 100644 --- a/dev-workflows-frontend/agents/technical-designer-frontend.md +++ b/dev-workflows-frontend/agents/technical-designer-frontend.md @@ -11,6 +11,7 @@ skills: - testing-principles - llm-friendly-context - external-resource-context + - requirement-convergence --- You are a frontend technical design specialist AI assistant for creating Architecture Decision Records (ADR) and Design Documents. @@ -233,6 +234,7 @@ When conversion is required, clearly specify wrapper implementation or migration - `reverse-engineer`: Document existing frontend architecture as-is (see Reverse-Engineer Mode section) - **Requirements Analysis Results**: Requirements analysis results (scale determination, technical requirements, etc.) +- **Convergence Result**: The `convergence` object (HC-01b) → populate the Requirement Convergence section, or mark its first three bullets N/A with the PRD path when a PRD carries them; record the fields left `weak-but-explicit` under Open questions in every case. Treat `nonGoals` and `speculative` requirements as excluded from this design - **Codebase Analysis** (optional, from codebase analysis phase): - When provided, use as the primary source for the data, contract, and dependency portions of the "Existing Codebase Analysis" section - `focusAreas` → contribute rows to the Fact Disposition Table (one row per focusArea, with fact_id + disposition + rationale + evidence). Apply the `code:` prefix to fact_id values to disambiguate from UI-focused facts diff --git a/dev-workflows-frontend/agents/ui-spec-designer.md b/dev-workflows-frontend/agents/ui-spec-designer.md index fd04e84..4af9191 100644 --- a/dev-workflows-frontend/agents/ui-spec-designer.md +++ b/dev-workflows-frontend/agents/ui-spec-designer.md @@ -16,8 +16,6 @@ You are a UI specification specialist AI assistant for creating UI Specification **Task Registration**: Register work steps using TaskCreate. Always include first task "Map preloaded skills to applicable concrete rules" and final task "Verify the mapped rules before final JSON". Update status using TaskUpdate upon each completion. -**Current Date Retrieval**: Before starting work, retrieve the actual current date from the operating environment (do not rely on training data cutoff date). - ## Main Responsibilities 1. Analyze PRD acceptance criteria and map them to screens, states, and components diff --git a/dev-workflows-frontend/agents/verifier.md b/dev-workflows-frontend/agents/verifier.md index b8bfb7a..384042b 100644 --- a/dev-workflows-frontend/agents/verifier.md +++ b/dev-workflows-frontend/agents/verifier.md @@ -13,8 +13,6 @@ You are an AI assistant specializing in investigation result verification. **Task Registration**: Register work steps using TaskCreate. Always include first task "Map preloaded skills to applicable concrete rules" and final task "Verify the mapped rules before final JSON". Update status using TaskUpdate upon each completion. -**Current Date Check**: Run `date` command before starting to determine current date for evaluating information recency. - ## Input and Responsibility Boundaries - **Input**: Structured investigation results (JSON) or text format investigation results diff --git a/dev-workflows-frontend/skills/coding-principles/SKILL.md b/dev-workflows-frontend/skills/coding-principles/SKILL.md index 80914b5..f4230e9 100644 --- a/dev-workflows-frontend/skills/coding-principles/SKILL.md +++ b/dev-workflows-frontend/skills/coding-principles/SKILL.md @@ -9,7 +9,7 @@ description: Language-agnostic coding principles for maintainability, readabilit 1. **Maintainability over Speed**: Prioritize long-term code health over initial development velocity 2. **Simplicity First**: Choose the simplest solution that meets requirements (YAGNI principle) -3. **Design Convergence**: Deliver the current required outcome with the least new design surface. Use implementation-approach when selecting persistent state, public or cross-boundary contracts, behavioral modes, reusable abstractions, or component splits. +3. **Design Convergence**: Deliver the current required outcome with the least new design surface. Selecting persistent state, public or cross-boundary contracts, behavioral modes, reusable abstractions, or component splits carries enough surface to justify the full convergence process first. 4. **Explicit over Implicit**: Make intentions clear through code structure and naming 5. **Delete over Comment**: Remove unused code instead of commenting it out diff --git a/dev-workflows-frontend/skills/documentation-criteria/SKILL.md b/dev-workflows-frontend/skills/documentation-criteria/SKILL.md index 344a7a7..92c2dd6 100644 --- a/dev-workflows-frontend/skills/documentation-criteria/SKILL.md +++ b/dev-workflows-frontend/skills/documentation-criteria/SKILL.md @@ -25,6 +25,12 @@ description: Documentation creation criteria including PRD, ADR, Design Doc, and | 3-5 Files | Design Doc → Work Plan (Required) | Start immediately | | 1-2 Files | None | Direct implementation | +### Structural Escalation + +File count measures size, not structural impact, so a two-file change can still carry architecture-level consequences. + +When any ADR Creation Condition below applies, the scale is **Medium at minimum** (Design Doc + Work Plan required) regardless of file count. Escalation only raises a level; a file count that already reaches Medium or Large stands. + ## ADR Creation Conditions (Required if Any Apply) ### 1. Contract System Changes 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 fe33cf0..dea1547 100644 --- a/dev-workflows-frontend/skills/documentation-criteria/references/design-template.md +++ b/dev-workflows-frontend/skills/documentation-criteria/references/design-template.md @@ -41,6 +41,15 @@ Lists each external resource this feature depends on with its feature-specific i |-------------------------------|-----------------------------|-------| | [Resource label] | [e.g., specific endpoint path, schema source path, IaC module] | [feature-specific scope] | +### Requirement Convergence + +Records exclusions **the user decided** at requirement time. Exclusions this design decided belong in `Future Extensibility`. Mark the first three bullets `N/A — covered by PRD [path]` when a PRD holds them, or the whole section `N/A — reverse-engineer/as-is document`. Open questions stay here in every case, because design readiness depends on them. + +- **Outcome**: [one observable result this change must produce] +- **Non-Goals**: [capability the user excluded | None — user confirmed there are none] +- **Speculative**: [idea the user raised without deciding on -> deferral reason | None] +- **Open questions**: [field the user left as weak-but-explicit | None] + ### Agreement Checklist #### Scope @@ -363,7 +372,7 @@ Mark as N/A with brief rationale when the design introduces entirely new behavio ## Future Extensibility -This section records what was **excluded** from the current design surface. Speculative inclusions belong in a separate proposal. +This section records what **this design** excluded from the current design surface. Exclusions the user decided at requirement time belong in `Requirement Convergence`. Speculative inclusions belong in a separate proposal. - **Deferred possibilities**: [Capabilities considered during design and explicitly excluded from the current design surface. Each entry names either the current requirement it would have served, or marks itself as speculative] - **Intentional limitations**: [What was deliberately kept small and why] diff --git a/dev-workflows-frontend/skills/documentation-criteria/references/prd-template.md b/dev-workflows-frontend/skills/documentation-criteria/references/prd-template.md index 665cfcc..acce9e9 100644 --- a/dev-workflows-frontend/skills/documentation-criteria/references/prd-template.md +++ b/dev-workflows-frontend/skills/documentation-criteria/references/prd-template.md @@ -57,9 +57,11 @@ C4Context ### Future / Out of Scope -| Capability | Disposition | Reason | -|---|---|---| -| [Capability excluded during MVP convergence] | future / out-of-scope | [Why it is not required for the current value or obligations] | +`Origin` distinguishes a non-goal the user authored (`user`) from an exclusion the requirement analysis judged (`analysis`). Record `None — user confirmed there are none` when the user considered exclusions and found none. + +| Capability | Disposition | Origin | Reason | +|---|---|---|---| +| [Capability excluded during MVP convergence] | future / out-of-scope | user / analysis | [Why it is not required for the current value or obligations] | ## Non-Functional Requirements diff --git a/dev-workflows-frontend/skills/recipe-front-design/SKILL.md b/dev-workflows-frontend/skills/recipe-front-design/SKILL.md index c988b77..b572660 100644 --- a/dev-workflows-frontend/skills/recipe-front-design/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-front-design/SKILL.md @@ -85,9 +85,11 @@ Invoke codebase-analyzer with its existing schema. The orchestrator constructs ` - Expected action: analyze the seed files for frontend design guidance (data, contracts, dependencies, quality assurance mechanisms) ### Step 3: Scope Confirmation -After codebase-analyzer returns, confirm the design scope with the user before any design work. This is a recipe-local confirmation step. Use AskUserQuestion. +After codebase-analyzer returns, confirm the design scope with the user before any design work. This is a recipe-local confirmation step. -Present, sourced from the codebase-analyzer JSON: +First run the requirement-convergence hearing protocol, using the codebase-analyzer findings as the facts it presents. This recipe has no requirement-analyzer, so the orchestrator both elicits and judges the fields, recording the result as the skill's `convergence` object (`outcome`, `requirements[]` with layer labels, `nonGoals[]`, plus a readiness label per field). `cost` does not apply here: the orchestrator cannot search the repository, and entering this recipe already decided to design. Carry that object into Steps 6 and 7 so ui-spec-designer respects the non-goals and technical-designer-frontend persists it to the Design Doc. + +Then present, sourced from the codebase-analyzer JSON, using AskUserQuestion: - **Target files/modules**: `analysisScope.filesAnalyzed` and the modules they belong to - **Affected layers**: layers touched, derived from `analysisScope.categoriesDetected` and `focusAreas` - **Unknowns/assumptions**: `limitations` plus any assumptions codebase-analyzer recorded @@ -131,6 +133,7 @@ Then create the UI Specification: - `description: "UI Spec creation"` - Build the prompt by including: - Source: an existing PRD in `docs/prd/` when one exists for this feature; otherwise the user requirements with the Step 2 codebase-analyzer JSON and the Step 3 confirmed scope + - The Step 3 `convergence` object's `nonGoals` and `speculative` requirements, as capabilities the UI Spec leaves out - `ui_analysis`: ui-analyzer JSON from Step 5 (includes externalResources fetched_summary and componentStructure / propsPatterns / cssLayout / etc.) - Prototype path when provided - Example (existing PRD): `prompt: "Create UI Spec from PRD at [path]. ui_analysis: [JSON from Step 5 ui-analyzer]. Prototype code is at [user-provided path]. Place prototype in docs/ui-spec/assets/{feature-name}/."` @@ -143,7 +146,7 @@ Then create the UI Specification: Pass the Step 2 codebase-analyzer output and the Step 5 ui-analyzer output to technical-designer-frontend. ADRs use alternative comparison; Design Docs use Design Convergence. - Invoke **technical-designer-frontend** using Agent tool - For ADR: `subagent_type: "dev-workflows-frontend:technical-designer-frontend"`, `description: "ADR creation"`, `prompt: "Create ADR for [technical decision]. Requirements: [user requirements verbatim]. Codebase analysis: [codebase-analyzer JSON from Step 2]. UI analysis: [ui-analyzer JSON from Step 5]. Confirmed scope and user answers: [Step 3 confirmed scope and user answers]. Present at least two alternatives with trade-offs."` - - For Design Doc: `subagent_type: "dev-workflows-frontend:technical-designer-frontend"`, `description: "Design Doc creation"`, `prompt: "Create Design Doc based on the requirements. Requirements: [user requirements verbatim]. Codebase analysis: [codebase-analyzer JSON from Step 2]. UI analysis: [ui-analyzer JSON from Step 5]. Confirmed scope and user answers: [Step 3 confirmed scope and user answers]. UI Spec is at [ui-spec path]. Inherit component structure and state design from UI Spec. Apply the code: prefix to codebase-analyzer fact_ids and ui: prefix to ui-analyzer fact_ids when filling the Fact Disposition Table."` + - For Design Doc: `subagent_type: "dev-workflows-frontend:technical-designer-frontend"`, `description: "Design Doc creation"`, `prompt: "Create Design Doc based on the requirements. Requirements: [user requirements verbatim]. Codebase analysis: [codebase-analyzer JSON from Step 2]. UI analysis: [ui-analyzer JSON from Step 5]. Confirmed scope and user answers: [Step 3 confirmed scope and user answers]. Convergence result: [Step 3 `convergence` object]. UI Spec is at [ui-spec path]. Inherit component structure and state design from UI Spec. Apply the code: prefix to codebase-analyzer fact_ids and ui: prefix to ui-analyzer fact_ids when filling the Fact Disposition Table."` - **(Design Doc only)** Invoke **code-verifier** to verify Design Doc against existing code. Skip for ADR. - `subagent_type: "dev-workflows-frontend:code-verifier"`, `description: "Design Doc verification"`, `prompt: "doc_type: design-doc document_path: [Design Doc path] Verify Design Doc against existing code."` - **(Design Doc only)** Invoke **document-reviewer** to verify consistency, completeness, and adopted design validity @@ -160,6 +163,7 @@ Pass the Step 2 codebase-analyzer output and the Step 5 ui-analyzer output to te - [ ] Built the Step 1 scope bootstrap seed (or obtained target files from the user when the search returned none) - [ ] Executed codebase-analyzer with a populated `requirement_analysis` +- [ ] Ran the requirement-convergence hearing and carried its result into design - [ ] Confirmed the design scope with the user and set the scale from the confirmed target files - [ ] Executed external resource hearing per the external-resource-context skill (file written or update explicitly skipped by user) - [ ] Executed ui-analyzer; codebase-analyzer (Step 2) and ui-analyzer (Step 5) outputs reused by ui-spec-designer and technical-designer-frontend diff --git a/dev-workflows-frontend/skills/requirement-convergence/SKILL.md b/dev-workflows-frontend/skills/requirement-convergence/SKILL.md new file mode 100644 index 0000000..bcb8092 --- /dev/null +++ b/dev-workflows-frontend/skills/requirement-convergence/SKILL.md @@ -0,0 +1,69 @@ +--- +name: requirement-convergence +description: Separates the outcome a change must produce from the requirements proposed to reach it, records what the user excluded, and bands cost from structure. Use when a requirement enters a workflow, before design begins. +--- + +# Requirement Convergence + +## Purpose + +Requirements arrive bloated, ambiguous, or aimed at the wrong outcome. A capable model reconciles all three into a coherent plan and builds it faithfully — delivering exactly what was asked for when what was asked for was wrong. + +This skill converges **what to build**. How to build it, and which documents the change requires, are settled after the what is. + +## Convergence Fields + +| Field | Pass condition | +|-------|----------------| +| `outcome` | One observable result. A requirement that does not serve it is excess. | +| `requirements[]` | Every item labeled `current-state`, `desired-future`, or `speculative`. | +| `nonGoals[]` | Authored by the user, or the user stated there are none. | +| `cost` | A band with the structural evidence that places it, plus the unknowns that remain. | + +`cost` is a rough band, not the effort estimate a work plan schedules against; requirements cannot support person-days. Its unknowns carry more decision weight than its size. + +Each field carries a readiness label: `ready`, `weak`, or `weak-but-explicit` (weak, and the user agreed to leave it unresolved). Only the user sets `weak-but-explicit`. Requirements are converged when every applicable field is `ready` or `weak-but-explicit`. + +Judgment rules per field: [references/criteria.md](references/criteria.md). + +## Hearing Protocol + +Eliciting requires user interaction, so the orchestrator owns it. It runs after the analysis that produced the scope facts, because the orchestrator investigates nothing itself. + +Register these steps before starting and record each step's evidence as it completes: + +| Step | Action | Completion evidence | +|------|--------|---------------------| +| 1 | State the scope facts the analysis produced, then separately what they imply for the requirement | Facts listed with the analysis output they came from | +| 2 | Ask about the fields below `ready`, at most two questions per message | One question per field below `ready` | +| 3 | Record each answer as that field's value | The value uses wording the user supplied, not wording the hearing offered | +| 4 | Re-ask once when a recorded value still fails its pass condition, then mark the field `weak-but-explicit` when the user agrees to leave the second answer as it stands | Two recorded answers, or the user's agreement to stop | +| 5 | Hand the record to the step that judges the fields | An updated record returned from that step | + +Step 3's evidence is what keeps the hearing reviewable: a value restating the hearing's own candidates fails it, so the user's judgment survives however the question was put. + +## Storage Protocol + +| Carrier | Holds | Written by | +|---------|-------|------------| +| The convergence record in the judging step's output | Every field with its readiness label | Whichever step judged them | +| PRD `Success Criteria` and `Future / Out of Scope` | `outcome`; `nonGoals` and `speculative` requirements with origin `user` | The agent that owns the PRD | +| Design Doc `Requirement Convergence` | The same when no PRD exists, and the fields left `weak-but-explicit` in every case | The agent that owns the Design Doc | + +A flow that produces neither document carries the record in its own context to the next step. + +## Reference Protocol (For Downstream Consumers) + +1. Read the convergence record from the prompt. +2. Treat `nonGoals` and `speculative` requirements as excluded from the current change. A `speculative` item becomes buildable only after the user promotes it to `desired-future`. +3. Treat a `weak-but-explicit` field as a recorded open question rather than a settled decision, and escalate when the work depends on resolving it. + +## Quality Checklist + +- [ ] Scope facts were presented before questions were asked +- [ ] `nonGoals` came from the user, or the user stated there are none +- [ ] Every applicable field is `ready`, or `weak-but-explicit` by the user's agreement + +## References + +- [references/criteria.md](references/criteria.md) — judgment rules per field, cost inputs, challenge intensity, solution-in-disguise test diff --git a/dev-workflows-frontend/skills/requirement-convergence/references/criteria.md b/dev-workflows-frontend/skills/requirement-convergence/references/criteria.md new file mode 100644 index 0000000..87818ff --- /dev/null +++ b/dev-workflows-frontend/skills/requirement-convergence/references/criteria.md @@ -0,0 +1,62 @@ +# Convergence Criteria + +Judgment rules for the four convergence fields. Read when eliciting or evaluating them. + +## outcome + +One observable result the change must produce, not a feature list. + +A requirement that cannot be traced to the outcome is excess: drop it, or have the user widen the outcome to cover it. + +## requirements[] — layer separation + +| Layer | Meaning | Buildable now | +|-------|---------|---------------| +| `current-state` | Behavior that already exists | No — these are facts, not work | +| `desired-future` | The change the user is asking for | Yes | +| `speculative` | An idea the user raised without deciding on | No — record with a deferral reason | + +Flattening these three into one requirement list is what makes a bloated plan look coherent, because every item then reads as equally required. Label each item; ask when a label is unclear rather than inferring it. + +## nonGoals[] + +Capabilities deliberately excluded from this change, authored by the user. + +Present the cost band and its unknowns first, then ask what to leave out. `userAgreedNone` records that the user considered exclusions and found none — an agent cannot set it. + +An adjacent capability the agent noticed is a question for the user, not a non-goal. + +## cost + +Cost follows structure and count, not behavior, so it is decided from these inputs alone: + +| Input | How it is obtained | +|-------|--------------------| +| Number and kind of targets to change | Grep/Glob over the affected files | +| Number of boundaries crossed | Affected path composition plus import and caller tracing | +| Whether an equivalent already exists (reuse or new) | Grep for a similar name or shape | +| Whether persisted state needs converting | Whether a schema or migration path is in the change set | +| Whether verification support already exists | Glob for the area's existing test harness | +| What remains unknown | WebSearch for a dependency's current capability; anything the above cannot resolve | + +Reading what the code *does* answers whether the change is correct, not what it costs, and belongs to the codebase analysis that precedes design. + +Record `cost` as one band, the inputs above that place it, and the remaining unknowns. A flow declares `cost` out of scope only where its own steps say so. + +## Challenge intensity + +The band's only job is to select a row here, so cheap requirements stay cheap to accept. + +| Band | Meaning | Challenge | +|------|---------|-----------| +| `low-reversible` | Additive, flagged, or easily deleted | Record the fields and accept the requirement | +| `medium` | Reverting would touch other work | Present the cost and one lower-cost alternative | +| `high-irreversible` | Public contract, persisted data shape, or dependency swap | Present the trade-off and require a user decision before design | + +Report an unknown that would move the band up as a blocking question rather than assuming the lower band. + +## Solution-in-disguise test + +When the requirement names a mechanism rather than an outcome ("add a cache layer", "introduce a queue"), state three materially different ways to reach the same outcome. + +When three exist, the named mechanism is one option among several — present them for a user decision. When the mechanism is genuinely the only route, record that and proceed. diff --git a/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md index 7eaf34a..8393731 100644 --- a/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md @@ -13,6 +13,8 @@ All investigation, analysis, and implementation work flows through specialized s When receiving a new task, pass user requirements directly to requirement-analyzer. Determine the workflow based on its scale assessment result. +requirement-analyzer returns a `convergence` object. Run the requirement-convergence hearing protocol at the requirements stop point on that output, recording each step's evidence, then re-invoke requirement-analyzer with the answers so the record is re-judged. The hearing runs in the orchestrator because it requires user interaction, and runs after the analysis because the orchestrator investigates nothing itself. + ### Requirement Change Detection During Flow **During flow execution**, monitor user responses for scope-expanding signals: @@ -79,7 +81,7 @@ Autonomous execution MUST stop and wait for user input at these points. | Phase | Stop Point | User Action Required | |-------|------------|---------------------| -| Requirements | After requirement-analyzer completes | Confirm requirements / Answer questions | +| Requirements | After requirement-analyzer completes | Answer the requirement-convergence hearing, then confirm requirements | | PRD | After document-reviewer completes PRD review | Approve PRD | | UI Spec | After document-reviewer completes UI Spec review (frontend/fullstack) | Approve UI Spec | | ADR | After document-reviewer completes ADR review (if ADR created) | Approve ADR | @@ -95,6 +97,8 @@ Autonomous execution MUST stop and wait for user input at these points. | Medium | 3-5 | Update※1 | Conditional※2 | **Required** | **Required** | | Large | 6+ | **Required**※3 | Conditional※2 | **Required** | **Required** | +File count sets the floor; documentation-criteria Structural Escalation raises it when any ADR Creation Condition applies. + ※1: Update if PRD exists for the relevant feature ※2: When there are architecture changes, new technology introduction, or data flow changes ※3: New creation/update existing/reverse PRD (when no existing PRD) @@ -136,6 +140,7 @@ Two additional rules: - subagent_type: "requirement-analyzer" - description: "Requirement analysis" - prompt: "Requirements: [user requirements]. Context: [any relevant context]. Perform requirement analysis and scale determination." +- On re-invocation after the convergence hearing, append: "Hearing answers: [the user's answers per convergence field]. Re-judge the convergence record with these answers." ### Call Example (codebase-analyzer) - subagent_type: "codebase-analyzer" @@ -157,7 +162,7 @@ When invoked alongside codebase-analyzer for frontend or fullstack-frontend work ## Structured Response Specification Subagents respond in JSON format. Key fields for orchestrator decisions: -- **requirement-analyzer**: scale, confidence, affectedLayers, adrRequired, scopeDependencies, questions +- **requirement-analyzer**: scale, confidence, affectedLayers, adrRequired, scopeDependencies, questions, convergence (fields with readiness labels; a field below `ready` returns as a `convergence` question) - **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**: `summary.status` (consistent/mostly_consistent/needs_review/inconsistent/blocked), `summary.consistencyScore`, discrepancies[], reverseCoverage (including dataOperationsInCode, testBoundariesSectionPresent). Pre-implementation: verifies Design Doc claims against existing codebase. Post-implementation: verifies implementation consistency against the governing Design Doc or Work Plan (pass `code_paths` scoped to changed files) @@ -192,7 +197,7 @@ Criteria for timing when to call each agent: ## Basic Flow: Planning and Implementation -Always start with requirement-analyzer, then select the minimum planning flow required by scale and affected layers. +Always start with requirement-analyzer, hold the requirement-convergence hearing on its output, then select the minimum planning flow required by scale and affected layers. ### Planning flow (per scale) @@ -202,7 +207,7 @@ Always start with requirement-analyzer, then select the minimum planning flow re | Medium | requirement-analyzer → external resource hearing → codebase-analyzer (+ ui-analyzer in parallel for frontend/fullstack) → optional UI Spec → optional ADR → Design Doc → code-verifier → document-reviewer → design-sync → acceptance-test-generator → work-planner → work plan review (document-reviewer, doc_type WorkPlan) → task-decomposer | | Small | requirement-analyzer → work-planner | -External resource hearing runs in the orchestrator (it requires AskUserQuestion). ui-analyzer joins codebase-analyzer in parallel only when the work has a frontend surface; for backend-only work the planning flow uses codebase-analyzer alone. +The requirement-convergence hearing follows requirement-analyzer in every flow. Both it and the external resource hearing run in the orchestrator (they require AskUserQuestion). ui-analyzer joins codebase-analyzer in parallel only when the work has a frontend surface; for backend-only work the planning flow uses codebase-analyzer alone. After the planning flow completes and the user grants batch approval, implementation proceeds. Verifying the plan is implementable end-to-end (verification lanes, fixtures, E2E environment) is an optional preflight the user runs at their discretion via the recipe-prepare-implementation recipe; this guide does not invoke any orchestrator above the agent layer. @@ -345,7 +350,13 @@ Register overall phases using TaskCreate. Update each phase with TaskUpdate as i ### Handoff Contracts #### HC-01: requirement-analyzer → codebase-analyzer - - Pass: `requirement_analysis`, `prd_path` (if exists), original user requirements + - Pass: `requirement_analysis` (including `convergence`), `prd_path` (if exists), original user requirements + + #### HC-01b: convergence record → document owner + - Pass `convergence` from the last requirement-analyzer invocation (or, in flows without one, the orchestrator's own judged record) to whichever agent owns the persisting document + - **prd-creator** (when a PRD is created or updated): persists `outcome` to `Success Criteria`, and `nonGoals` plus `speculative` requirements to `Future / Out of Scope` with origin `user` + - **technical-designer / technical-designer-frontend**: persists the same to the Design Doc's `Requirement Convergence` when no PRD exists, and always records the fields left `weak-but-explicit` there + - Pass the record unchanged; a field's readiness label travels with it #### HC-02: codebase-analyzer → technical-designer - Pass: full codebase-analyzer JSON as additional context diff --git a/dev-workflows-frontend/skills/subagents-orchestration-guide/references/monorepo-flow.md b/dev-workflows-frontend/skills/subagents-orchestration-guide/references/monorepo-flow.md index 74a52d2..ed1889d 100644 --- a/dev-workflows-frontend/skills/subagents-orchestration-guide/references/monorepo-flow.md +++ b/dev-workflows-frontend/skills/subagents-orchestration-guide/references/monorepo-flow.md @@ -14,7 +14,7 @@ This reference defines the orchestration flow for projects spanning multiple lay | Step | Agent | Purpose | Output | |------|-------|---------|--------| -| 1 | requirement-analyzer | Requirement analysis + scale determination **[Stop]** | Requirements + scale | +| 1 | requirement-analyzer → (orchestrator) | Requirement analysis + scale determination, then the requirement-convergence hearing on its `convergence` output, re-invoking the analyzer with the answers **[Stop]** | Converged requirements + scale | | 2 | prd-creator | PRD covering entire feature (all layers) | Single PRD | | 3 | document-reviewer | PRD review **[Stop]** | Approval | | 4 | (orchestrator) | External resource hearing per the external-resource-context skill (frontend domain primary; backend / api / infra domains as applicable for the layer scope). File-existence branching as defined in the skill | `docs/project-context/external-resources.md` written or updated | @@ -36,7 +36,7 @@ This reference defines the orchestration flow for projects spanning multiple lay | Step | Agent | Purpose | Output | |------|-------|---------|--------| -| 1 | requirement-analyzer | Requirement analysis + scale determination **[Stop]** | Requirements + scale | +| 1 | requirement-analyzer → (orchestrator) | Requirement analysis + scale determination, then the requirement-convergence hearing on its `convergence` output, re-invoking the analyzer with the answers **[Stop]** | Converged requirements + scale | | 2 | (orchestrator) | External resource hearing per the external-resource-context skill (frontend / backend / api / infra domains as applicable). File-existence branching as defined in the skill | `docs/project-context/external-resources.md` written or updated | | 3 | codebase-analyzer ×2 + ui-analyzer | Codebase analysis per layer + UI fact gathering (parallel; ui-analyzer reads external-resources.md and fetches external UI sources via inherited MCP/URL access) | Codebase guidance per layer + UI fact JSON | | 4 | (orchestrator) | Ask user for prototype code **[Stop]** | Prototype path or none | diff --git a/dev-workflows-frontend/skills/task-analyzer/references/skills-index.yaml b/dev-workflows-frontend/skills/task-analyzer/references/skills-index.yaml index 7f2b364..d99869d 100644 --- a/dev-workflows-frontend/skills/task-analyzer/references/skills-index.yaml +++ b/dev-workflows-frontend/skills/task-analyzer/references/skills-index.yaml @@ -231,3 +231,19 @@ skills: - "Output Format" - "Quality Checklist" - "References" + + requirement-convergence: + skill: "requirement-convergence" + tags: [cross-cutting, requirements, scope, non-goals, outcome, rough-estimate, trade-off, hearing-protocol, convergence] + typical-use: "Converges what to build before design by separating outcome from requirement layers, recording user-authored non-goals, and banding cost from structure rather than behavior" + size: small + key-references: + - "references/criteria.md" + sections: + - "Purpose" + - "Convergence Fields" + - "Hearing Protocol" + - "Storage Protocol" + - "Reference Protocol (For Downstream Consumers)" + - "Quality Checklist" + - "References" diff --git a/dev-workflows-fullstack/.claude-plugin/plugin.json b/dev-workflows-fullstack/.claude-plugin/plugin.json index 70b6b3f..b271d36 100644 --- a/dev-workflows-fullstack/.claude-plugin/plugin.json +++ b/dev-workflows-fullstack/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "dev-workflows-fullstack", "description": "Skills + Subagents for fullstack development (backend + React/TypeScript) - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", - "version": "0.22.9", + "version": "0.23.0", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows-fullstack/agents/document-reviewer.md b/dev-workflows-fullstack/agents/document-reviewer.md index 6e41112..0156246 100644 --- a/dev-workflows-fullstack/agents/document-reviewer.md +++ b/dev-workflows-fullstack/agents/document-reviewer.md @@ -77,6 +77,10 @@ For DesignDoc, additionally verify: - [ ] Verification Strategy section present with: correctness definition, verification method, verification timing, early verification point - [ ] Fact Disposition Table present and covers every `codebase_analysis.focusAreas` entry (when `codebase_analysis` is provided) - [ ] Design Convergence section present: future-state documents contain Direct MVP, Failed Items, Adopted Additions, and Rejected Additions; reverse-engineer/as-is documents mark the section N/A +- [ ] Requirement Convergence section present: Open questions filled in every future-state document; Outcome, Non-Goals, and Speculative filled, or marked N/A with the PRD path that carries them; whole section N/A for reverse-engineer/as-is documents + +For PRD, additionally verify: +- [ ] `Future / Out of Scope` records each user-authored non-goal with origin `user`, or states the user confirmed there are none For WorkPlan, additionally verify: - [ ] Review Scope recorded (planned-files scope, or base branch + diff range for a revision plan) diff --git a/dev-workflows-fullstack/agents/investigator.md b/dev-workflows-fullstack/agents/investigator.md index ebcedee..174850d 100644 --- a/dev-workflows-fullstack/agents/investigator.md +++ b/dev-workflows-fullstack/agents/investigator.md @@ -13,8 +13,6 @@ You are an AI assistant specializing in problem investigation. **Task Registration**: Register work steps using TaskCreate. Always include first task "Map preloaded skills to applicable concrete rules" and final task "Verify the mapped rules before final JSON". Update status using TaskUpdate upon each completion. -**Current Date Check**: Run `date` command before starting to determine current date for evaluating information recency. - ## Input and Responsibility Boundaries - **Input**: Accepts both text and JSON formats. For JSON, use `problemSummary` diff --git a/dev-workflows-fullstack/agents/prd-creator.md b/dev-workflows-fullstack/agents/prd-creator.md index abb4011..45aa2b5 100644 --- a/dev-workflows-fullstack/agents/prd-creator.md +++ b/dev-workflows-fullstack/agents/prd-creator.md @@ -5,6 +5,7 @@ tools: Read, Write, Edit, MultiEdit, Glob, LS, Bash, TaskCreate, TaskUpdate, Web skills: - documentation-criteria - llm-friendly-context + - requirement-convergence --- You are a specialized AI assistant for creating Product Requirements Documents (PRD). @@ -13,8 +14,6 @@ You are a specialized AI assistant for creating Product Requirements Documents ( **Task Registration**: Register work steps using TaskCreate. Always include first task "Map preloaded skills to applicable concrete rules" and final task "Verify the mapped rules before final JSON". Update status using TaskUpdate upon each completion. -**Current Date Retrieval**: Before starting work, retrieve the actual current date from the operating environment (do not rely on training data cutoff date). - ## Responsibilities 1. Structure and document business requirements @@ -39,6 +38,7 @@ You are a specialized AI assistant for creating Product Requirements Documents ( - `reverse-engineer`: Create PRD from existing implementation (Reverse PRD) - **Requirements Analysis Results**: Requirements analysis results +- **Convergence Result**: The `convergence` object (HC-01b) → `outcome` anchors Success Criteria; `nonGoals` and `speculative` requirements populate `Future / Out of Scope` with origin `user`. Treat both as excluded from MVP Requirements - **Existing PRD**: Path to existing PRD file for reference (if any) - **Project Context**: - Target users (sales, marketing, HR, etc.) diff --git a/dev-workflows-fullstack/agents/requirement-analyzer.md b/dev-workflows-fullstack/agents/requirement-analyzer.md index 8c17ac2..beb4fc2 100644 --- a/dev-workflows-fullstack/agents/requirement-analyzer.md +++ b/dev-workflows-fullstack/agents/requirement-analyzer.md @@ -1,17 +1,18 @@ --- name: requirement-analyzer -description: Performs requirements analysis and work scale determination. Use PROACTIVELY when new feature requests or change requests are received, or when "requirements/scope/where to start" is mentioned. Extracts user requirement essence and proposes development approaches. +description: Judges requirement convergence and work scale from inspected code. Use PROACTIVELY when new feature requests or change requests are received, or when "requirements/scope/where to start/how far do we go" is mentioned. Separates outcome from requirement layers and reports what the change should exclude. tools: Read, Grep, Glob, LS, Bash, TaskCreate, TaskUpdate, WebSearch skills: - ai-development-guide - documentation-criteria + - requirement-convergence --- You are a specialized AI assistant for requirements analysis and work scale determination. ## Initial Mandatory Tasks -**Current Date Retrieval**: Before starting work, retrieve the actual current date from the operating environment (do not rely on training data cutoff date). +**Task Registration**: Register work steps using TaskCreate. Always include first task "Map preloaded skills to applicable concrete rules" and final task "Verify the mapped rules before final JSON". Update status using TaskUpdate upon each completion. ## Verification Process @@ -25,16 +26,23 @@ Investigate the existing codebase to identify affected files: - Include related test files - List all affected file paths explicitly -### 3. Determine Scale -Classify based on the file count from Step 2 (small: 1-2, medium: 3-5, large: 6+). Scale determination must cite specific file paths as evidence. +### 3. Judge Convergence +Evaluate the requirement-convergence skill's four fields from the Step 2 scope facts and assign each a readiness label. Place `cost` in one band using that skill's cost inputs — counts, boundaries, existing equivalents, persisted-state conversion, verification support, and unknowns — all of which are answerable from scope tracing and WebSearch. Behavioral analysis belongs to codebase-analyzer and is out of scope here. -### 4. Evaluate ADR Necessity +Run the solution-in-disguise test when the requirement names a mechanism rather than an outcome. + +This agent judges the fields and reports every field below `ready` through `questions`. The orchestrator elicits the answers and re-invokes this agent with them. + +### 4. Determine Scale +Classify by the file count from Step 2 (small: 1-2, medium: 3-5, large: 6+), then apply documentation-criteria Structural Escalation. Scale determination must cite specific file paths as evidence. + +### 5. Evaluate ADR Necessity Check each ADR condition individually against the requirements (see Conditions Requiring ADR section). -### 5. Assess Technical Constraints and Risks +### 6. Assess Technical Constraints and Risks Identify constraints, risks, and dependencies. Use WebSearch to verify current technical landscape when evaluating unfamiliar technologies or dependencies. -### 6. Formulate Questions +### 7. Formulate Questions Identify any ambiguities that affect scale determination (scopeDependencies) or require user confirmation before proceeding. ## Work Scale Determination Criteria @@ -69,13 +77,15 @@ Detailed ADR creation conditions follow documentation-criteria skill. ## Ensuring Determination Consistency ### Determination Logic -1. **Scale determination**: Use file count as highest priority criterion +1. **Scale determination**: Take the higher of the file-count level and the level set by documentation-criteria Structural Escalation 2. **ADR determination**: Check ADR conditions individually ## Operating Principles ### Complete Self-Containment Principle -Each analysis is stateless and deterministic: same input produces same output via fixed rules (file count for scale, documented criteria for ADR). All determination rationale must be explicit and unambiguous. +Each analysis is stateless and deterministic: same input produces same output via fixed rules (file count plus structural conditions for scale, documented criteria for ADR). All determination rationale must be explicit and unambiguous. + +Each readiness label cites its evidence: a field with no recorded answer is `weak`, and `weak-but-explicit` cites the user's agreement to leave it unresolved. ## Input Parameters @@ -94,6 +104,14 @@ Each analysis is stateless and deterministic: same input produces same output vi { "taskType": "feature|fix|refactor|performance|security", "purpose": "Essential purpose of request (1-2 sentences)", + "convergence": { + "outcome": "observable result", + "requirements": [{ "item": "requirement", "layer": "current-state|desired-future|speculative", "deferralReason": "reason or null" }], + "nonGoals": ["list"], + "userAgreedNone": false, + "cost": { "band": "low-reversible|medium|high-irreversible", "evidence": ["list"], "unknowns": ["list"] }, + "readiness": { "outcome": "ready|weak|weak-but-explicit", "requirements": "same values", "nonGoals": "same values", "cost": "same values" } + }, "scale": "small|medium|large", "confidence": "confirmed|provisional", "affectedFiles": ["path/to/file1", "path/to/file2"], @@ -114,7 +132,7 @@ Each analysis is stateless and deterministic: same input produces same output vi ], "questions": [ { - "category": "boundary|existing_code|dependencies", + "category": "boundary|existing_code|dependencies|convergence", "question": "specific question", "options": ["A", "B", "C"] } @@ -123,6 +141,7 @@ Each analysis is stateless and deterministic: same input produces same output vi ``` **Field descriptions**: +- `convergence`: The requirement-convergence skill's four fields with their readiness labels. `cost` is a rough band, not an effort estimate. Every field below `ready` also becomes a `questions` entry with category `convergence` - `affectedLayers`: Layers determined from affectedFiles paths (e.g., `backend/` → "backend", `frontend/` → "frontend"). Used by fullstack orchestrator for per-layer Design Doc creation - `confidence`: "confirmed" if scale is certain, "provisional" if questions remain - `scopeDependencies`: Questions whose answers may change the scale determination @@ -131,6 +150,7 @@ Each analysis is stateless and deterministic: same input produces same output vi ## Quality Checklist - [ ] Do I understand the user's true purpose? +- [ ] Have I labeled every requirement's layer and reported unconverged fields? - [ ] Have I properly estimated the impact scope? - [ ] Have I correctly determined ADR necessity? - [ ] Have I identified all technical risks and dependencies? diff --git a/dev-workflows-fullstack/agents/rule-advisor.md b/dev-workflows-fullstack/agents/rule-advisor.md index fabbc56..20f44fb 100644 --- a/dev-workflows-fullstack/agents/rule-advisor.md +++ b/dev-workflows-fullstack/agents/rule-advisor.md @@ -1,6 +1,6 @@ --- name: rule-advisor -description: Selects optimal rulesets for tasks and performs metacognitive analysis. Use PROACTIVELY before implementation tasks start, or when "rules/ruleset/coding standards" is mentioned. Returns structured JSON with recommended skills and rationale. +description: Selects this project's applicable rules for a task and returns them with rationale. Use before starting work whose applicable rules and coding standards are not already determined by a defined process. tools: Read, Grep, LS skills: - task-analyzer diff --git a/dev-workflows-fullstack/agents/technical-designer-frontend.md b/dev-workflows-fullstack/agents/technical-designer-frontend.md index dc461c7..61e4bc4 100644 --- a/dev-workflows-fullstack/agents/technical-designer-frontend.md +++ b/dev-workflows-fullstack/agents/technical-designer-frontend.md @@ -11,6 +11,7 @@ skills: - testing-principles - llm-friendly-context - external-resource-context + - requirement-convergence --- You are a frontend technical design specialist AI assistant for creating Architecture Decision Records (ADR) and Design Documents. @@ -233,6 +234,7 @@ When conversion is required, clearly specify wrapper implementation or migration - `reverse-engineer`: Document existing frontend architecture as-is (see Reverse-Engineer Mode section) - **Requirements Analysis Results**: Requirements analysis results (scale determination, technical requirements, etc.) +- **Convergence Result**: The `convergence` object (HC-01b) → populate the Requirement Convergence section, or mark its first three bullets N/A with the PRD path when a PRD carries them; record the fields left `weak-but-explicit` under Open questions in every case. Treat `nonGoals` and `speculative` requirements as excluded from this design - **Codebase Analysis** (optional, from codebase analysis phase): - When provided, use as the primary source for the data, contract, and dependency portions of the "Existing Codebase Analysis" section - `focusAreas` → contribute rows to the Fact Disposition Table (one row per focusArea, with fact_id + disposition + rationale + evidence). Apply the `code:` prefix to fact_id values to disambiguate from UI-focused facts diff --git a/dev-workflows-fullstack/agents/technical-designer.md b/dev-workflows-fullstack/agents/technical-designer.md index e58967e..5f030ba 100644 --- a/dev-workflows-fullstack/agents/technical-designer.md +++ b/dev-workflows-fullstack/agents/technical-designer.md @@ -10,6 +10,7 @@ skills: - implementation-approach - llm-friendly-context - external-resource-context + - requirement-convergence --- You are a technical design specialist AI assistant for creating Architecture Decision Records (ADR) and Design Documents. @@ -18,8 +19,6 @@ You are a technical design specialist AI assistant for creating Architecture Dec **Task Registration**: Register work steps using TaskCreate. Always include first task "Map preloaded skills to applicable concrete rules" and final task "Verify the mapped rules before final JSON". Update status using TaskUpdate upon each completion. -**Current Date Retrieval**: Before starting work, retrieve the actual current date from the operating environment (do not rely on training data cutoff date). - ## Document Creation Criteria Follow documentation-criteria skill for ADR/Design Doc creation thresholds. If assessments conflict, include and report the discrepancy in output. @@ -256,6 +255,7 @@ When conversion is required, clearly specify adapter implementation or migration - `reverse-engineer`: Document existing architecture as-is (see Reverse-Engineer Mode section) - **Requirements Analysis Results**: Requirements analysis results (scale determination, technical requirements, etc.) +- **Convergence Result**: The `convergence` object (HC-01b) → populate the Requirement Convergence section, or mark its first three bullets N/A with the PRD path when a PRD carries them; record the fields left `weak-but-explicit` under Open questions in every case. Treat `nonGoals` and `speculative` requirements as excluded from this design - **Codebase Analysis** (optional, from codebase analysis phase): - When provided, use as the primary source for the "Existing Codebase Analysis" section - `focusAreas` → produce the Fact Disposition Table (one row per focusArea, with fact_id + disposition + rationale + evidence) diff --git a/dev-workflows-fullstack/agents/ui-spec-designer.md b/dev-workflows-fullstack/agents/ui-spec-designer.md index fd04e84..4af9191 100644 --- a/dev-workflows-fullstack/agents/ui-spec-designer.md +++ b/dev-workflows-fullstack/agents/ui-spec-designer.md @@ -16,8 +16,6 @@ You are a UI specification specialist AI assistant for creating UI Specification **Task Registration**: Register work steps using TaskCreate. Always include first task "Map preloaded skills to applicable concrete rules" and final task "Verify the mapped rules before final JSON". Update status using TaskUpdate upon each completion. -**Current Date Retrieval**: Before starting work, retrieve the actual current date from the operating environment (do not rely on training data cutoff date). - ## Main Responsibilities 1. Analyze PRD acceptance criteria and map them to screens, states, and components diff --git a/dev-workflows-fullstack/agents/verifier.md b/dev-workflows-fullstack/agents/verifier.md index b8bfb7a..384042b 100644 --- a/dev-workflows-fullstack/agents/verifier.md +++ b/dev-workflows-fullstack/agents/verifier.md @@ -13,8 +13,6 @@ You are an AI assistant specializing in investigation result verification. **Task Registration**: Register work steps using TaskCreate. Always include first task "Map preloaded skills to applicable concrete rules" and final task "Verify the mapped rules before final JSON". Update status using TaskUpdate upon each completion. -**Current Date Check**: Run `date` command before starting to determine current date for evaluating information recency. - ## Input and Responsibility Boundaries - **Input**: Structured investigation results (JSON) or text format investigation results diff --git a/dev-workflows-fullstack/skills/coding-principles/SKILL.md b/dev-workflows-fullstack/skills/coding-principles/SKILL.md index 80914b5..f4230e9 100644 --- a/dev-workflows-fullstack/skills/coding-principles/SKILL.md +++ b/dev-workflows-fullstack/skills/coding-principles/SKILL.md @@ -9,7 +9,7 @@ description: Language-agnostic coding principles for maintainability, readabilit 1. **Maintainability over Speed**: Prioritize long-term code health over initial development velocity 2. **Simplicity First**: Choose the simplest solution that meets requirements (YAGNI principle) -3. **Design Convergence**: Deliver the current required outcome with the least new design surface. Use implementation-approach when selecting persistent state, public or cross-boundary contracts, behavioral modes, reusable abstractions, or component splits. +3. **Design Convergence**: Deliver the current required outcome with the least new design surface. Selecting persistent state, public or cross-boundary contracts, behavioral modes, reusable abstractions, or component splits carries enough surface to justify the full convergence process first. 4. **Explicit over Implicit**: Make intentions clear through code structure and naming 5. **Delete over Comment**: Remove unused code instead of commenting it out diff --git a/dev-workflows-fullstack/skills/documentation-criteria/SKILL.md b/dev-workflows-fullstack/skills/documentation-criteria/SKILL.md index 344a7a7..92c2dd6 100644 --- a/dev-workflows-fullstack/skills/documentation-criteria/SKILL.md +++ b/dev-workflows-fullstack/skills/documentation-criteria/SKILL.md @@ -25,6 +25,12 @@ description: Documentation creation criteria including PRD, ADR, Design Doc, and | 3-5 Files | Design Doc → Work Plan (Required) | Start immediately | | 1-2 Files | None | Direct implementation | +### Structural Escalation + +File count measures size, not structural impact, so a two-file change can still carry architecture-level consequences. + +When any ADR Creation Condition below applies, the scale is **Medium at minimum** (Design Doc + Work Plan required) regardless of file count. Escalation only raises a level; a file count that already reaches Medium or Large stands. + ## ADR Creation Conditions (Required if Any Apply) ### 1. Contract System Changes 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 fe33cf0..dea1547 100644 --- a/dev-workflows-fullstack/skills/documentation-criteria/references/design-template.md +++ b/dev-workflows-fullstack/skills/documentation-criteria/references/design-template.md @@ -41,6 +41,15 @@ Lists each external resource this feature depends on with its feature-specific i |-------------------------------|-----------------------------|-------| | [Resource label] | [e.g., specific endpoint path, schema source path, IaC module] | [feature-specific scope] | +### Requirement Convergence + +Records exclusions **the user decided** at requirement time. Exclusions this design decided belong in `Future Extensibility`. Mark the first three bullets `N/A — covered by PRD [path]` when a PRD holds them, or the whole section `N/A — reverse-engineer/as-is document`. Open questions stay here in every case, because design readiness depends on them. + +- **Outcome**: [one observable result this change must produce] +- **Non-Goals**: [capability the user excluded | None — user confirmed there are none] +- **Speculative**: [idea the user raised without deciding on -> deferral reason | None] +- **Open questions**: [field the user left as weak-but-explicit | None] + ### Agreement Checklist #### Scope @@ -363,7 +372,7 @@ Mark as N/A with brief rationale when the design introduces entirely new behavio ## Future Extensibility -This section records what was **excluded** from the current design surface. Speculative inclusions belong in a separate proposal. +This section records what **this design** excluded from the current design surface. Exclusions the user decided at requirement time belong in `Requirement Convergence`. Speculative inclusions belong in a separate proposal. - **Deferred possibilities**: [Capabilities considered during design and explicitly excluded from the current design surface. Each entry names either the current requirement it would have served, or marks itself as speculative] - **Intentional limitations**: [What was deliberately kept small and why] diff --git a/dev-workflows-fullstack/skills/documentation-criteria/references/prd-template.md b/dev-workflows-fullstack/skills/documentation-criteria/references/prd-template.md index 665cfcc..acce9e9 100644 --- a/dev-workflows-fullstack/skills/documentation-criteria/references/prd-template.md +++ b/dev-workflows-fullstack/skills/documentation-criteria/references/prd-template.md @@ -57,9 +57,11 @@ C4Context ### Future / Out of Scope -| Capability | Disposition | Reason | -|---|---|---| -| [Capability excluded during MVP convergence] | future / out-of-scope | [Why it is not required for the current value or obligations] | +`Origin` distinguishes a non-goal the user authored (`user`) from an exclusion the requirement analysis judged (`analysis`). Record `None — user confirmed there are none` when the user considered exclusions and found none. + +| Capability | Disposition | Origin | Reason | +|---|---|---|---| +| [Capability excluded during MVP convergence] | future / out-of-scope | user / analysis | [Why it is not required for the current value or obligations] | ## Non-Functional Requirements diff --git a/dev-workflows-fullstack/skills/recipe-design/SKILL.md b/dev-workflows-fullstack/skills/recipe-design/SKILL.md index aa09172..4f44338 100644 --- a/dev-workflows-fullstack/skills/recipe-design/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-design/SKILL.md @@ -76,9 +76,11 @@ Invoke codebase-analyzer with its existing schema. The orchestrator constructs ` - Expected action: analyze the seed files and produce design guidance ### Step 3: Scope Confirmation -After codebase-analyzer returns, confirm the design scope with the user before any design work. This is a recipe-local confirmation step. Use AskUserQuestion. +After codebase-analyzer returns, confirm the design scope with the user before any design work. This is a recipe-local confirmation step. -Present, sourced from the codebase-analyzer JSON: +First run the requirement-convergence hearing protocol, using the codebase-analyzer findings as the facts it presents. This recipe has no requirement-analyzer, so the orchestrator both elicits and judges the fields, recording the result as the skill's `convergence` object (`outcome`, `requirements[]` with layer labels, `nonGoals[]`, plus a readiness label per field). `cost` does not apply here: the orchestrator cannot search the repository, and entering this recipe already decided to design. Carry that object into Step 4 so technical-designer persists it to the Design Doc. + +Then present, sourced from the codebase-analyzer JSON, using AskUserQuestion: - **Target files/modules**: `analysisScope.filesAnalyzed` and the modules they belong to - **Affected layers**: layers touched, derived from `analysisScope.categoriesDetected` and `focusAreas` - **Unknowns/assumptions**: `limitations` plus any assumptions codebase-analyzer recorded @@ -98,7 +100,7 @@ After the user confirms the scope, count the confirmed target files and set the Pass the full codebase-analyzer JSON to technical-designer (handoff contract HC-02). ADRs use alternative comparison; Design Docs use Design Convergence. - Invoke **technical-designer** using Agent tool - - For Design Doc: `subagent_type: "dev-workflows-fullstack:technical-designer"`, `description: "Design Doc creation"`, `prompt: "Create Design Doc based on the requirements. Requirements: [user requirements verbatim]. Codebase analysis: [codebase-analyzer JSON from Step 2]. Confirmed scope and user answers: [Step 3 confirmed scope and user answers]. Apply the code: prefix to codebase-analyzer fact_ids when filling the Fact Disposition Table."` + - For Design Doc: `subagent_type: "dev-workflows-fullstack:technical-designer"`, `description: "Design Doc creation"`, `prompt: "Create Design Doc based on the requirements. Requirements: [user requirements verbatim]. Codebase analysis: [codebase-analyzer JSON from Step 2]. Confirmed scope and user answers: [Step 3 confirmed scope and user answers]. Convergence result: [Step 3 `convergence` object]. Apply the code: prefix to codebase-analyzer fact_ids when filling the Fact Disposition Table."` - For ADR: `subagent_type: "dev-workflows-fullstack:technical-designer"`, `description: "ADR creation"`, `prompt: "Create ADR for [technical decision]. Requirements: [user requirements verbatim]. Codebase analysis: [codebase-analyzer JSON from Step 2]. Confirmed scope and user answers: [Step 3 confirmed scope and user answers]. Present at least two alternatives with trade-offs."` - **(Design Doc only)** Invoke **code-verifier** to verify the Design Doc against existing code. Skip for ADR. - `subagent_type: "dev-workflows-fullstack:code-verifier"`, `description: "Design Doc verification"`, `prompt: "doc_type: design-doc document_path: [Design Doc path] Verify Design Doc against existing code."` @@ -115,6 +117,7 @@ Pass the full codebase-analyzer JSON to technical-designer (handoff contract HC- - [ ] Built the Step 1 scope bootstrap seed (or obtained target files from the user when the search returned none) - [ ] Executed codebase-analyzer with a populated `requirement_analysis` +- [ ] Ran the requirement-convergence hearing and carried its result into design - [ ] Confirmed the design scope with the user and set the scale from the confirmed target files - [ ] Created appropriate design document (ADR or Design Doc) with technical-designer - [ ] Executed code-verifier on Design Doc and passed results to document-reviewer (skip for ADR-only) diff --git a/dev-workflows-fullstack/skills/recipe-front-design/SKILL.md b/dev-workflows-fullstack/skills/recipe-front-design/SKILL.md index 6430e35..c7b6415 100644 --- a/dev-workflows-fullstack/skills/recipe-front-design/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-front-design/SKILL.md @@ -85,9 +85,11 @@ Invoke codebase-analyzer with its existing schema. The orchestrator constructs ` - Expected action: analyze the seed files for frontend design guidance (data, contracts, dependencies, quality assurance mechanisms) ### Step 3: Scope Confirmation -After codebase-analyzer returns, confirm the design scope with the user before any design work. This is a recipe-local confirmation step. Use AskUserQuestion. +After codebase-analyzer returns, confirm the design scope with the user before any design work. This is a recipe-local confirmation step. -Present, sourced from the codebase-analyzer JSON: +First run the requirement-convergence hearing protocol, using the codebase-analyzer findings as the facts it presents. This recipe has no requirement-analyzer, so the orchestrator both elicits and judges the fields, recording the result as the skill's `convergence` object (`outcome`, `requirements[]` with layer labels, `nonGoals[]`, plus a readiness label per field). `cost` does not apply here: the orchestrator cannot search the repository, and entering this recipe already decided to design. Carry that object into Steps 6 and 7 so ui-spec-designer respects the non-goals and technical-designer-frontend persists it to the Design Doc. + +Then present, sourced from the codebase-analyzer JSON, using AskUserQuestion: - **Target files/modules**: `analysisScope.filesAnalyzed` and the modules they belong to - **Affected layers**: layers touched, derived from `analysisScope.categoriesDetected` and `focusAreas` - **Unknowns/assumptions**: `limitations` plus any assumptions codebase-analyzer recorded @@ -131,6 +133,7 @@ Then create the UI Specification: - `description: "UI Spec creation"` - Build the prompt by including: - Source: an existing PRD in `docs/prd/` when one exists for this feature; otherwise the user requirements with the Step 2 codebase-analyzer JSON and the Step 3 confirmed scope + - The Step 3 `convergence` object's `nonGoals` and `speculative` requirements, as capabilities the UI Spec leaves out - `ui_analysis`: ui-analyzer JSON from Step 5 (includes externalResources fetched_summary and componentStructure / propsPatterns / cssLayout / etc.) - Prototype path when provided - Example (existing PRD): `prompt: "Create UI Spec from PRD at [path]. ui_analysis: [JSON from Step 5 ui-analyzer]. Prototype code is at [user-provided path]. Place prototype in docs/ui-spec/assets/{feature-name}/."` @@ -143,7 +146,7 @@ Then create the UI Specification: Pass the Step 2 codebase-analyzer output and the Step 5 ui-analyzer output to technical-designer-frontend. ADRs use alternative comparison; Design Docs use Design Convergence. - Invoke **technical-designer-frontend** using Agent tool - For ADR: `subagent_type: "dev-workflows-fullstack:technical-designer-frontend"`, `description: "ADR creation"`, `prompt: "Create ADR for [technical decision]. Requirements: [user requirements verbatim]. Codebase analysis: [codebase-analyzer JSON from Step 2]. UI analysis: [ui-analyzer JSON from Step 5]. Confirmed scope and user answers: [Step 3 confirmed scope and user answers]. Present at least two alternatives with trade-offs."` - - For Design Doc: `subagent_type: "dev-workflows-fullstack:technical-designer-frontend"`, `description: "Design Doc creation"`, `prompt: "Create Design Doc based on the requirements. Requirements: [user requirements verbatim]. Codebase analysis: [codebase-analyzer JSON from Step 2]. UI analysis: [ui-analyzer JSON from Step 5]. Confirmed scope and user answers: [Step 3 confirmed scope and user answers]. UI Spec is at [ui-spec path]. Inherit component structure and state design from UI Spec. Apply the code: prefix to codebase-analyzer fact_ids and ui: prefix to ui-analyzer fact_ids when filling the Fact Disposition Table."` + - For Design Doc: `subagent_type: "dev-workflows-fullstack:technical-designer-frontend"`, `description: "Design Doc creation"`, `prompt: "Create Design Doc based on the requirements. Requirements: [user requirements verbatim]. Codebase analysis: [codebase-analyzer JSON from Step 2]. UI analysis: [ui-analyzer JSON from Step 5]. Confirmed scope and user answers: [Step 3 confirmed scope and user answers]. Convergence result: [Step 3 `convergence` object]. UI Spec is at [ui-spec path]. Inherit component structure and state design from UI Spec. Apply the code: prefix to codebase-analyzer fact_ids and ui: prefix to ui-analyzer fact_ids when filling the Fact Disposition Table."` - **(Design Doc only)** Invoke **code-verifier** to verify Design Doc against existing code. Skip for ADR. - `subagent_type: "dev-workflows-fullstack:code-verifier"`, `description: "Design Doc verification"`, `prompt: "doc_type: design-doc document_path: [Design Doc path] Verify Design Doc against existing code."` - **(Design Doc only)** Invoke **document-reviewer** to verify consistency, completeness, and adopted design validity @@ -160,6 +163,7 @@ Pass the Step 2 codebase-analyzer output and the Step 5 ui-analyzer output to te - [ ] Built the Step 1 scope bootstrap seed (or obtained target files from the user when the search returned none) - [ ] Executed codebase-analyzer with a populated `requirement_analysis` +- [ ] Ran the requirement-convergence hearing and carried its result into design - [ ] Confirmed the design scope with the user and set the scale from the confirmed target files - [ ] Executed external resource hearing per the external-resource-context skill (file written or update explicitly skipped by user) - [ ] Executed ui-analyzer; codebase-analyzer (Step 2) and ui-analyzer (Step 5) outputs reused by ui-spec-designer and technical-designer-frontend diff --git a/dev-workflows-fullstack/skills/recipe-fullstack-implement/SKILL.md b/dev-workflows-fullstack/skills/recipe-fullstack-implement/SKILL.md index f249813..8c80121 100644 --- a/dev-workflows-fullstack/skills/recipe-fullstack-implement/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-fullstack-implement/SKILL.md @@ -60,11 +60,14 @@ Key points to enforce as the orchestrator runs the flow: ### 4. Register All Flow Steps Using TaskCreate (MANDATORY) -After scale determination, use TaskCreate to register `"Select and map applicable rules"`, each design/planning step, and the implementation, verification, cleanup, and report phases. Complete registration before invoking subagents; mark and advance the active phase with TaskUpdate. +After scale determination, use TaskCreate to register each design/planning step and the implementation, verification, cleanup, and report phases. Complete registration before invoking subagents; mark and advance the active phase with TaskUpdate. ## After requirement-analyzer [Stop] +Run the requirement-convergence hearing protocol on the returned `convergence` object before presenting anything else, using the analyzer's scope facts and cost band as the facts it presents. + When user responds to questions: +- If any `convergence` field is below `ready` → Re-execute requirement-analyzer with the hearing answers so the record is re-judged. Repeat until every field is `ready` or `weak-but-explicit` - If response matches any `scopeDependencies.question` → Check `impact` for scale change - If scale changes → Re-execute requirement-analyzer with updated context - If `confidence: "confirmed"` or no scale change → Proceed to next step diff --git a/dev-workflows-fullstack/skills/recipe-implement/SKILL.md b/dev-workflows-fullstack/skills/recipe-implement/SKILL.md index 3c4504c..aba66ea 100644 --- a/dev-workflows-fullstack/skills/recipe-implement/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-implement/SKILL.md @@ -53,14 +53,17 @@ When continuing existing flow, verify: ### After requirement-analyzer [Stop] +Run the requirement-convergence hearing protocol on the returned `convergence` object before presenting anything else, using the analyzer's scope facts and cost band as the facts it presents. + When user responds to questions: +- If any `convergence` field is below `ready` → Re-execute requirement-analyzer with the hearing answers so the record is re-judged. Repeat until every field is `ready` or `weak-but-explicit` - If response matches any `scopeDependencies.question` → Check `impact` for scale change - If scale changes → Re-execute requirement-analyzer with updated context - If `confidence: "confirmed"` or no scale change → Proceed to next step ### 4. Register All Flow Steps Using TaskCreate (MANDATORY) -After scale determination, use TaskCreate to register `"Select and map applicable rules"`, each design/planning step, and the implementation, verification, cleanup, and report phases. Complete registration before invoking subagents; mark and advance the active phase with TaskUpdate. +After scale determination, use TaskCreate to register each design/planning step and the implementation, verification, cleanup, and report phases. Complete registration before invoking subagents; mark and advance the active phase with TaskUpdate. ## Subagents Orchestration Guide Compliance Execution diff --git a/dev-workflows-fullstack/skills/requirement-convergence/SKILL.md b/dev-workflows-fullstack/skills/requirement-convergence/SKILL.md new file mode 100644 index 0000000..bcb8092 --- /dev/null +++ b/dev-workflows-fullstack/skills/requirement-convergence/SKILL.md @@ -0,0 +1,69 @@ +--- +name: requirement-convergence +description: Separates the outcome a change must produce from the requirements proposed to reach it, records what the user excluded, and bands cost from structure. Use when a requirement enters a workflow, before design begins. +--- + +# Requirement Convergence + +## Purpose + +Requirements arrive bloated, ambiguous, or aimed at the wrong outcome. A capable model reconciles all three into a coherent plan and builds it faithfully — delivering exactly what was asked for when what was asked for was wrong. + +This skill converges **what to build**. How to build it, and which documents the change requires, are settled after the what is. + +## Convergence Fields + +| Field | Pass condition | +|-------|----------------| +| `outcome` | One observable result. A requirement that does not serve it is excess. | +| `requirements[]` | Every item labeled `current-state`, `desired-future`, or `speculative`. | +| `nonGoals[]` | Authored by the user, or the user stated there are none. | +| `cost` | A band with the structural evidence that places it, plus the unknowns that remain. | + +`cost` is a rough band, not the effort estimate a work plan schedules against; requirements cannot support person-days. Its unknowns carry more decision weight than its size. + +Each field carries a readiness label: `ready`, `weak`, or `weak-but-explicit` (weak, and the user agreed to leave it unresolved). Only the user sets `weak-but-explicit`. Requirements are converged when every applicable field is `ready` or `weak-but-explicit`. + +Judgment rules per field: [references/criteria.md](references/criteria.md). + +## Hearing Protocol + +Eliciting requires user interaction, so the orchestrator owns it. It runs after the analysis that produced the scope facts, because the orchestrator investigates nothing itself. + +Register these steps before starting and record each step's evidence as it completes: + +| Step | Action | Completion evidence | +|------|--------|---------------------| +| 1 | State the scope facts the analysis produced, then separately what they imply for the requirement | Facts listed with the analysis output they came from | +| 2 | Ask about the fields below `ready`, at most two questions per message | One question per field below `ready` | +| 3 | Record each answer as that field's value | The value uses wording the user supplied, not wording the hearing offered | +| 4 | Re-ask once when a recorded value still fails its pass condition, then mark the field `weak-but-explicit` when the user agrees to leave the second answer as it stands | Two recorded answers, or the user's agreement to stop | +| 5 | Hand the record to the step that judges the fields | An updated record returned from that step | + +Step 3's evidence is what keeps the hearing reviewable: a value restating the hearing's own candidates fails it, so the user's judgment survives however the question was put. + +## Storage Protocol + +| Carrier | Holds | Written by | +|---------|-------|------------| +| The convergence record in the judging step's output | Every field with its readiness label | Whichever step judged them | +| PRD `Success Criteria` and `Future / Out of Scope` | `outcome`; `nonGoals` and `speculative` requirements with origin `user` | The agent that owns the PRD | +| Design Doc `Requirement Convergence` | The same when no PRD exists, and the fields left `weak-but-explicit` in every case | The agent that owns the Design Doc | + +A flow that produces neither document carries the record in its own context to the next step. + +## Reference Protocol (For Downstream Consumers) + +1. Read the convergence record from the prompt. +2. Treat `nonGoals` and `speculative` requirements as excluded from the current change. A `speculative` item becomes buildable only after the user promotes it to `desired-future`. +3. Treat a `weak-but-explicit` field as a recorded open question rather than a settled decision, and escalate when the work depends on resolving it. + +## Quality Checklist + +- [ ] Scope facts were presented before questions were asked +- [ ] `nonGoals` came from the user, or the user stated there are none +- [ ] Every applicable field is `ready`, or `weak-but-explicit` by the user's agreement + +## References + +- [references/criteria.md](references/criteria.md) — judgment rules per field, cost inputs, challenge intensity, solution-in-disguise test diff --git a/dev-workflows-fullstack/skills/requirement-convergence/references/criteria.md b/dev-workflows-fullstack/skills/requirement-convergence/references/criteria.md new file mode 100644 index 0000000..87818ff --- /dev/null +++ b/dev-workflows-fullstack/skills/requirement-convergence/references/criteria.md @@ -0,0 +1,62 @@ +# Convergence Criteria + +Judgment rules for the four convergence fields. Read when eliciting or evaluating them. + +## outcome + +One observable result the change must produce, not a feature list. + +A requirement that cannot be traced to the outcome is excess: drop it, or have the user widen the outcome to cover it. + +## requirements[] — layer separation + +| Layer | Meaning | Buildable now | +|-------|---------|---------------| +| `current-state` | Behavior that already exists | No — these are facts, not work | +| `desired-future` | The change the user is asking for | Yes | +| `speculative` | An idea the user raised without deciding on | No — record with a deferral reason | + +Flattening these three into one requirement list is what makes a bloated plan look coherent, because every item then reads as equally required. Label each item; ask when a label is unclear rather than inferring it. + +## nonGoals[] + +Capabilities deliberately excluded from this change, authored by the user. + +Present the cost band and its unknowns first, then ask what to leave out. `userAgreedNone` records that the user considered exclusions and found none — an agent cannot set it. + +An adjacent capability the agent noticed is a question for the user, not a non-goal. + +## cost + +Cost follows structure and count, not behavior, so it is decided from these inputs alone: + +| Input | How it is obtained | +|-------|--------------------| +| Number and kind of targets to change | Grep/Glob over the affected files | +| Number of boundaries crossed | Affected path composition plus import and caller tracing | +| Whether an equivalent already exists (reuse or new) | Grep for a similar name or shape | +| Whether persisted state needs converting | Whether a schema or migration path is in the change set | +| Whether verification support already exists | Glob for the area's existing test harness | +| What remains unknown | WebSearch for a dependency's current capability; anything the above cannot resolve | + +Reading what the code *does* answers whether the change is correct, not what it costs, and belongs to the codebase analysis that precedes design. + +Record `cost` as one band, the inputs above that place it, and the remaining unknowns. A flow declares `cost` out of scope only where its own steps say so. + +## Challenge intensity + +The band's only job is to select a row here, so cheap requirements stay cheap to accept. + +| Band | Meaning | Challenge | +|------|---------|-----------| +| `low-reversible` | Additive, flagged, or easily deleted | Record the fields and accept the requirement | +| `medium` | Reverting would touch other work | Present the cost and one lower-cost alternative | +| `high-irreversible` | Public contract, persisted data shape, or dependency swap | Present the trade-off and require a user decision before design | + +Report an unknown that would move the band up as a blocking question rather than assuming the lower band. + +## Solution-in-disguise test + +When the requirement names a mechanism rather than an outcome ("add a cache layer", "introduce a queue"), state three materially different ways to reach the same outcome. + +When three exist, the named mechanism is one option among several — present them for a user decision. When the mechanism is genuinely the only route, record that and proceed. diff --git a/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md index 7eaf34a..8393731 100644 --- a/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md @@ -13,6 +13,8 @@ All investigation, analysis, and implementation work flows through specialized s When receiving a new task, pass user requirements directly to requirement-analyzer. Determine the workflow based on its scale assessment result. +requirement-analyzer returns a `convergence` object. Run the requirement-convergence hearing protocol at the requirements stop point on that output, recording each step's evidence, then re-invoke requirement-analyzer with the answers so the record is re-judged. The hearing runs in the orchestrator because it requires user interaction, and runs after the analysis because the orchestrator investigates nothing itself. + ### Requirement Change Detection During Flow **During flow execution**, monitor user responses for scope-expanding signals: @@ -79,7 +81,7 @@ Autonomous execution MUST stop and wait for user input at these points. | Phase | Stop Point | User Action Required | |-------|------------|---------------------| -| Requirements | After requirement-analyzer completes | Confirm requirements / Answer questions | +| Requirements | After requirement-analyzer completes | Answer the requirement-convergence hearing, then confirm requirements | | PRD | After document-reviewer completes PRD review | Approve PRD | | UI Spec | After document-reviewer completes UI Spec review (frontend/fullstack) | Approve UI Spec | | ADR | After document-reviewer completes ADR review (if ADR created) | Approve ADR | @@ -95,6 +97,8 @@ Autonomous execution MUST stop and wait for user input at these points. | Medium | 3-5 | Update※1 | Conditional※2 | **Required** | **Required** | | Large | 6+ | **Required**※3 | Conditional※2 | **Required** | **Required** | +File count sets the floor; documentation-criteria Structural Escalation raises it when any ADR Creation Condition applies. + ※1: Update if PRD exists for the relevant feature ※2: When there are architecture changes, new technology introduction, or data flow changes ※3: New creation/update existing/reverse PRD (when no existing PRD) @@ -136,6 +140,7 @@ Two additional rules: - subagent_type: "requirement-analyzer" - description: "Requirement analysis" - prompt: "Requirements: [user requirements]. Context: [any relevant context]. Perform requirement analysis and scale determination." +- On re-invocation after the convergence hearing, append: "Hearing answers: [the user's answers per convergence field]. Re-judge the convergence record with these answers." ### Call Example (codebase-analyzer) - subagent_type: "codebase-analyzer" @@ -157,7 +162,7 @@ When invoked alongside codebase-analyzer for frontend or fullstack-frontend work ## Structured Response Specification Subagents respond in JSON format. Key fields for orchestrator decisions: -- **requirement-analyzer**: scale, confidence, affectedLayers, adrRequired, scopeDependencies, questions +- **requirement-analyzer**: scale, confidence, affectedLayers, adrRequired, scopeDependencies, questions, convergence (fields with readiness labels; a field below `ready` returns as a `convergence` question) - **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**: `summary.status` (consistent/mostly_consistent/needs_review/inconsistent/blocked), `summary.consistencyScore`, discrepancies[], reverseCoverage (including dataOperationsInCode, testBoundariesSectionPresent). Pre-implementation: verifies Design Doc claims against existing codebase. Post-implementation: verifies implementation consistency against the governing Design Doc or Work Plan (pass `code_paths` scoped to changed files) @@ -192,7 +197,7 @@ Criteria for timing when to call each agent: ## Basic Flow: Planning and Implementation -Always start with requirement-analyzer, then select the minimum planning flow required by scale and affected layers. +Always start with requirement-analyzer, hold the requirement-convergence hearing on its output, then select the minimum planning flow required by scale and affected layers. ### Planning flow (per scale) @@ -202,7 +207,7 @@ Always start with requirement-analyzer, then select the minimum planning flow re | Medium | requirement-analyzer → external resource hearing → codebase-analyzer (+ ui-analyzer in parallel for frontend/fullstack) → optional UI Spec → optional ADR → Design Doc → code-verifier → document-reviewer → design-sync → acceptance-test-generator → work-planner → work plan review (document-reviewer, doc_type WorkPlan) → task-decomposer | | Small | requirement-analyzer → work-planner | -External resource hearing runs in the orchestrator (it requires AskUserQuestion). ui-analyzer joins codebase-analyzer in parallel only when the work has a frontend surface; for backend-only work the planning flow uses codebase-analyzer alone. +The requirement-convergence hearing follows requirement-analyzer in every flow. Both it and the external resource hearing run in the orchestrator (they require AskUserQuestion). ui-analyzer joins codebase-analyzer in parallel only when the work has a frontend surface; for backend-only work the planning flow uses codebase-analyzer alone. After the planning flow completes and the user grants batch approval, implementation proceeds. Verifying the plan is implementable end-to-end (verification lanes, fixtures, E2E environment) is an optional preflight the user runs at their discretion via the recipe-prepare-implementation recipe; this guide does not invoke any orchestrator above the agent layer. @@ -345,7 +350,13 @@ Register overall phases using TaskCreate. Update each phase with TaskUpdate as i ### Handoff Contracts #### HC-01: requirement-analyzer → codebase-analyzer - - Pass: `requirement_analysis`, `prd_path` (if exists), original user requirements + - Pass: `requirement_analysis` (including `convergence`), `prd_path` (if exists), original user requirements + + #### HC-01b: convergence record → document owner + - Pass `convergence` from the last requirement-analyzer invocation (or, in flows without one, the orchestrator's own judged record) to whichever agent owns the persisting document + - **prd-creator** (when a PRD is created or updated): persists `outcome` to `Success Criteria`, and `nonGoals` plus `speculative` requirements to `Future / Out of Scope` with origin `user` + - **technical-designer / technical-designer-frontend**: persists the same to the Design Doc's `Requirement Convergence` when no PRD exists, and always records the fields left `weak-but-explicit` there + - Pass the record unchanged; a field's readiness label travels with it #### HC-02: codebase-analyzer → technical-designer - Pass: full codebase-analyzer JSON as additional context diff --git a/dev-workflows-fullstack/skills/subagents-orchestration-guide/references/monorepo-flow.md b/dev-workflows-fullstack/skills/subagents-orchestration-guide/references/monorepo-flow.md index 74a52d2..ed1889d 100644 --- a/dev-workflows-fullstack/skills/subagents-orchestration-guide/references/monorepo-flow.md +++ b/dev-workflows-fullstack/skills/subagents-orchestration-guide/references/monorepo-flow.md @@ -14,7 +14,7 @@ This reference defines the orchestration flow for projects spanning multiple lay | Step | Agent | Purpose | Output | |------|-------|---------|--------| -| 1 | requirement-analyzer | Requirement analysis + scale determination **[Stop]** | Requirements + scale | +| 1 | requirement-analyzer → (orchestrator) | Requirement analysis + scale determination, then the requirement-convergence hearing on its `convergence` output, re-invoking the analyzer with the answers **[Stop]** | Converged requirements + scale | | 2 | prd-creator | PRD covering entire feature (all layers) | Single PRD | | 3 | document-reviewer | PRD review **[Stop]** | Approval | | 4 | (orchestrator) | External resource hearing per the external-resource-context skill (frontend domain primary; backend / api / infra domains as applicable for the layer scope). File-existence branching as defined in the skill | `docs/project-context/external-resources.md` written or updated | @@ -36,7 +36,7 @@ This reference defines the orchestration flow for projects spanning multiple lay | Step | Agent | Purpose | Output | |------|-------|---------|--------| -| 1 | requirement-analyzer | Requirement analysis + scale determination **[Stop]** | Requirements + scale | +| 1 | requirement-analyzer → (orchestrator) | Requirement analysis + scale determination, then the requirement-convergence hearing on its `convergence` output, re-invoking the analyzer with the answers **[Stop]** | Converged requirements + scale | | 2 | (orchestrator) | External resource hearing per the external-resource-context skill (frontend / backend / api / infra domains as applicable). File-existence branching as defined in the skill | `docs/project-context/external-resources.md` written or updated | | 3 | codebase-analyzer ×2 + ui-analyzer | Codebase analysis per layer + UI fact gathering (parallel; ui-analyzer reads external-resources.md and fetches external UI sources via inherited MCP/URL access) | Codebase guidance per layer + UI fact JSON | | 4 | (orchestrator) | Ask user for prototype code **[Stop]** | Prototype path or none | diff --git a/dev-workflows-fullstack/skills/task-analyzer/references/skills-index.yaml b/dev-workflows-fullstack/skills/task-analyzer/references/skills-index.yaml index 7f2b364..d99869d 100644 --- a/dev-workflows-fullstack/skills/task-analyzer/references/skills-index.yaml +++ b/dev-workflows-fullstack/skills/task-analyzer/references/skills-index.yaml @@ -231,3 +231,19 @@ skills: - "Output Format" - "Quality Checklist" - "References" + + requirement-convergence: + skill: "requirement-convergence" + tags: [cross-cutting, requirements, scope, non-goals, outcome, rough-estimate, trade-off, hearing-protocol, convergence] + typical-use: "Converges what to build before design by separating outcome from requirement layers, recording user-authored non-goals, and banding cost from structure rather than behavior" + size: small + key-references: + - "references/criteria.md" + sections: + - "Purpose" + - "Convergence Fields" + - "Hearing Protocol" + - "Storage Protocol" + - "Reference Protocol (For Downstream Consumers)" + - "Quality Checklist" + - "References" diff --git a/dev-workflows/.claude-plugin/plugin.json b/dev-workflows/.claude-plugin/plugin.json index 54d25d8..f8a95c2 100644 --- a/dev-workflows/.claude-plugin/plugin.json +++ b/dev-workflows/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "dev-workflows", "description": "Skills + Subagents for backend development - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", - "version": "0.22.9", + "version": "0.23.0", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows/agents/document-reviewer.md b/dev-workflows/agents/document-reviewer.md index 6e41112..0156246 100644 --- a/dev-workflows/agents/document-reviewer.md +++ b/dev-workflows/agents/document-reviewer.md @@ -77,6 +77,10 @@ For DesignDoc, additionally verify: - [ ] Verification Strategy section present with: correctness definition, verification method, verification timing, early verification point - [ ] Fact Disposition Table present and covers every `codebase_analysis.focusAreas` entry (when `codebase_analysis` is provided) - [ ] Design Convergence section present: future-state documents contain Direct MVP, Failed Items, Adopted Additions, and Rejected Additions; reverse-engineer/as-is documents mark the section N/A +- [ ] Requirement Convergence section present: Open questions filled in every future-state document; Outcome, Non-Goals, and Speculative filled, or marked N/A with the PRD path that carries them; whole section N/A for reverse-engineer/as-is documents + +For PRD, additionally verify: +- [ ] `Future / Out of Scope` records each user-authored non-goal with origin `user`, or states the user confirmed there are none For WorkPlan, additionally verify: - [ ] Review Scope recorded (planned-files scope, or base branch + diff range for a revision plan) diff --git a/dev-workflows/agents/investigator.md b/dev-workflows/agents/investigator.md index ebcedee..174850d 100644 --- a/dev-workflows/agents/investigator.md +++ b/dev-workflows/agents/investigator.md @@ -13,8 +13,6 @@ You are an AI assistant specializing in problem investigation. **Task Registration**: Register work steps using TaskCreate. Always include first task "Map preloaded skills to applicable concrete rules" and final task "Verify the mapped rules before final JSON". Update status using TaskUpdate upon each completion. -**Current Date Check**: Run `date` command before starting to determine current date for evaluating information recency. - ## Input and Responsibility Boundaries - **Input**: Accepts both text and JSON formats. For JSON, use `problemSummary` diff --git a/dev-workflows/agents/prd-creator.md b/dev-workflows/agents/prd-creator.md index abb4011..45aa2b5 100644 --- a/dev-workflows/agents/prd-creator.md +++ b/dev-workflows/agents/prd-creator.md @@ -5,6 +5,7 @@ tools: Read, Write, Edit, MultiEdit, Glob, LS, Bash, TaskCreate, TaskUpdate, Web skills: - documentation-criteria - llm-friendly-context + - requirement-convergence --- You are a specialized AI assistant for creating Product Requirements Documents (PRD). @@ -13,8 +14,6 @@ You are a specialized AI assistant for creating Product Requirements Documents ( **Task Registration**: Register work steps using TaskCreate. Always include first task "Map preloaded skills to applicable concrete rules" and final task "Verify the mapped rules before final JSON". Update status using TaskUpdate upon each completion. -**Current Date Retrieval**: Before starting work, retrieve the actual current date from the operating environment (do not rely on training data cutoff date). - ## Responsibilities 1. Structure and document business requirements @@ -39,6 +38,7 @@ You are a specialized AI assistant for creating Product Requirements Documents ( - `reverse-engineer`: Create PRD from existing implementation (Reverse PRD) - **Requirements Analysis Results**: Requirements analysis results +- **Convergence Result**: The `convergence` object (HC-01b) → `outcome` anchors Success Criteria; `nonGoals` and `speculative` requirements populate `Future / Out of Scope` with origin `user`. Treat both as excluded from MVP Requirements - **Existing PRD**: Path to existing PRD file for reference (if any) - **Project Context**: - Target users (sales, marketing, HR, etc.) diff --git a/dev-workflows/agents/requirement-analyzer.md b/dev-workflows/agents/requirement-analyzer.md index 8c17ac2..beb4fc2 100644 --- a/dev-workflows/agents/requirement-analyzer.md +++ b/dev-workflows/agents/requirement-analyzer.md @@ -1,17 +1,18 @@ --- name: requirement-analyzer -description: Performs requirements analysis and work scale determination. Use PROACTIVELY when new feature requests or change requests are received, or when "requirements/scope/where to start" is mentioned. Extracts user requirement essence and proposes development approaches. +description: Judges requirement convergence and work scale from inspected code. Use PROACTIVELY when new feature requests or change requests are received, or when "requirements/scope/where to start/how far do we go" is mentioned. Separates outcome from requirement layers and reports what the change should exclude. tools: Read, Grep, Glob, LS, Bash, TaskCreate, TaskUpdate, WebSearch skills: - ai-development-guide - documentation-criteria + - requirement-convergence --- You are a specialized AI assistant for requirements analysis and work scale determination. ## Initial Mandatory Tasks -**Current Date Retrieval**: Before starting work, retrieve the actual current date from the operating environment (do not rely on training data cutoff date). +**Task Registration**: Register work steps using TaskCreate. Always include first task "Map preloaded skills to applicable concrete rules" and final task "Verify the mapped rules before final JSON". Update status using TaskUpdate upon each completion. ## Verification Process @@ -25,16 +26,23 @@ Investigate the existing codebase to identify affected files: - Include related test files - List all affected file paths explicitly -### 3. Determine Scale -Classify based on the file count from Step 2 (small: 1-2, medium: 3-5, large: 6+). Scale determination must cite specific file paths as evidence. +### 3. Judge Convergence +Evaluate the requirement-convergence skill's four fields from the Step 2 scope facts and assign each a readiness label. Place `cost` in one band using that skill's cost inputs — counts, boundaries, existing equivalents, persisted-state conversion, verification support, and unknowns — all of which are answerable from scope tracing and WebSearch. Behavioral analysis belongs to codebase-analyzer and is out of scope here. -### 4. Evaluate ADR Necessity +Run the solution-in-disguise test when the requirement names a mechanism rather than an outcome. + +This agent judges the fields and reports every field below `ready` through `questions`. The orchestrator elicits the answers and re-invokes this agent with them. + +### 4. Determine Scale +Classify by the file count from Step 2 (small: 1-2, medium: 3-5, large: 6+), then apply documentation-criteria Structural Escalation. Scale determination must cite specific file paths as evidence. + +### 5. Evaluate ADR Necessity Check each ADR condition individually against the requirements (see Conditions Requiring ADR section). -### 5. Assess Technical Constraints and Risks +### 6. Assess Technical Constraints and Risks Identify constraints, risks, and dependencies. Use WebSearch to verify current technical landscape when evaluating unfamiliar technologies or dependencies. -### 6. Formulate Questions +### 7. Formulate Questions Identify any ambiguities that affect scale determination (scopeDependencies) or require user confirmation before proceeding. ## Work Scale Determination Criteria @@ -69,13 +77,15 @@ Detailed ADR creation conditions follow documentation-criteria skill. ## Ensuring Determination Consistency ### Determination Logic -1. **Scale determination**: Use file count as highest priority criterion +1. **Scale determination**: Take the higher of the file-count level and the level set by documentation-criteria Structural Escalation 2. **ADR determination**: Check ADR conditions individually ## Operating Principles ### Complete Self-Containment Principle -Each analysis is stateless and deterministic: same input produces same output via fixed rules (file count for scale, documented criteria for ADR). All determination rationale must be explicit and unambiguous. +Each analysis is stateless and deterministic: same input produces same output via fixed rules (file count plus structural conditions for scale, documented criteria for ADR). All determination rationale must be explicit and unambiguous. + +Each readiness label cites its evidence: a field with no recorded answer is `weak`, and `weak-but-explicit` cites the user's agreement to leave it unresolved. ## Input Parameters @@ -94,6 +104,14 @@ Each analysis is stateless and deterministic: same input produces same output vi { "taskType": "feature|fix|refactor|performance|security", "purpose": "Essential purpose of request (1-2 sentences)", + "convergence": { + "outcome": "observable result", + "requirements": [{ "item": "requirement", "layer": "current-state|desired-future|speculative", "deferralReason": "reason or null" }], + "nonGoals": ["list"], + "userAgreedNone": false, + "cost": { "band": "low-reversible|medium|high-irreversible", "evidence": ["list"], "unknowns": ["list"] }, + "readiness": { "outcome": "ready|weak|weak-but-explicit", "requirements": "same values", "nonGoals": "same values", "cost": "same values" } + }, "scale": "small|medium|large", "confidence": "confirmed|provisional", "affectedFiles": ["path/to/file1", "path/to/file2"], @@ -114,7 +132,7 @@ Each analysis is stateless and deterministic: same input produces same output vi ], "questions": [ { - "category": "boundary|existing_code|dependencies", + "category": "boundary|existing_code|dependencies|convergence", "question": "specific question", "options": ["A", "B", "C"] } @@ -123,6 +141,7 @@ Each analysis is stateless and deterministic: same input produces same output vi ``` **Field descriptions**: +- `convergence`: The requirement-convergence skill's four fields with their readiness labels. `cost` is a rough band, not an effort estimate. Every field below `ready` also becomes a `questions` entry with category `convergence` - `affectedLayers`: Layers determined from affectedFiles paths (e.g., `backend/` → "backend", `frontend/` → "frontend"). Used by fullstack orchestrator for per-layer Design Doc creation - `confidence`: "confirmed" if scale is certain, "provisional" if questions remain - `scopeDependencies`: Questions whose answers may change the scale determination @@ -131,6 +150,7 @@ Each analysis is stateless and deterministic: same input produces same output vi ## Quality Checklist - [ ] Do I understand the user's true purpose? +- [ ] Have I labeled every requirement's layer and reported unconverged fields? - [ ] Have I properly estimated the impact scope? - [ ] Have I correctly determined ADR necessity? - [ ] Have I identified all technical risks and dependencies? diff --git a/dev-workflows/agents/rule-advisor.md b/dev-workflows/agents/rule-advisor.md index fabbc56..20f44fb 100644 --- a/dev-workflows/agents/rule-advisor.md +++ b/dev-workflows/agents/rule-advisor.md @@ -1,6 +1,6 @@ --- name: rule-advisor -description: Selects optimal rulesets for tasks and performs metacognitive analysis. Use PROACTIVELY before implementation tasks start, or when "rules/ruleset/coding standards" is mentioned. Returns structured JSON with recommended skills and rationale. +description: Selects this project's applicable rules for a task and returns them with rationale. Use before starting work whose applicable rules and coding standards are not already determined by a defined process. tools: Read, Grep, LS skills: - task-analyzer diff --git a/dev-workflows/agents/technical-designer.md b/dev-workflows/agents/technical-designer.md index e58967e..5f030ba 100644 --- a/dev-workflows/agents/technical-designer.md +++ b/dev-workflows/agents/technical-designer.md @@ -10,6 +10,7 @@ skills: - implementation-approach - llm-friendly-context - external-resource-context + - requirement-convergence --- You are a technical design specialist AI assistant for creating Architecture Decision Records (ADR) and Design Documents. @@ -18,8 +19,6 @@ You are a technical design specialist AI assistant for creating Architecture Dec **Task Registration**: Register work steps using TaskCreate. Always include first task "Map preloaded skills to applicable concrete rules" and final task "Verify the mapped rules before final JSON". Update status using TaskUpdate upon each completion. -**Current Date Retrieval**: Before starting work, retrieve the actual current date from the operating environment (do not rely on training data cutoff date). - ## Document Creation Criteria Follow documentation-criteria skill for ADR/Design Doc creation thresholds. If assessments conflict, include and report the discrepancy in output. @@ -256,6 +255,7 @@ When conversion is required, clearly specify adapter implementation or migration - `reverse-engineer`: Document existing architecture as-is (see Reverse-Engineer Mode section) - **Requirements Analysis Results**: Requirements analysis results (scale determination, technical requirements, etc.) +- **Convergence Result**: The `convergence` object (HC-01b) → populate the Requirement Convergence section, or mark its first three bullets N/A with the PRD path when a PRD carries them; record the fields left `weak-but-explicit` under Open questions in every case. Treat `nonGoals` and `speculative` requirements as excluded from this design - **Codebase Analysis** (optional, from codebase analysis phase): - When provided, use as the primary source for the "Existing Codebase Analysis" section - `focusAreas` → produce the Fact Disposition Table (one row per focusArea, with fact_id + disposition + rationale + evidence) diff --git a/dev-workflows/agents/verifier.md b/dev-workflows/agents/verifier.md index b8bfb7a..384042b 100644 --- a/dev-workflows/agents/verifier.md +++ b/dev-workflows/agents/verifier.md @@ -13,8 +13,6 @@ You are an AI assistant specializing in investigation result verification. **Task Registration**: Register work steps using TaskCreate. Always include first task "Map preloaded skills to applicable concrete rules" and final task "Verify the mapped rules before final JSON". Update status using TaskUpdate upon each completion. -**Current Date Check**: Run `date` command before starting to determine current date for evaluating information recency. - ## Input and Responsibility Boundaries - **Input**: Structured investigation results (JSON) or text format investigation results diff --git a/dev-workflows/skills/coding-principles/SKILL.md b/dev-workflows/skills/coding-principles/SKILL.md index 80914b5..f4230e9 100644 --- a/dev-workflows/skills/coding-principles/SKILL.md +++ b/dev-workflows/skills/coding-principles/SKILL.md @@ -9,7 +9,7 @@ description: Language-agnostic coding principles for maintainability, readabilit 1. **Maintainability over Speed**: Prioritize long-term code health over initial development velocity 2. **Simplicity First**: Choose the simplest solution that meets requirements (YAGNI principle) -3. **Design Convergence**: Deliver the current required outcome with the least new design surface. Use implementation-approach when selecting persistent state, public or cross-boundary contracts, behavioral modes, reusable abstractions, or component splits. +3. **Design Convergence**: Deliver the current required outcome with the least new design surface. Selecting persistent state, public or cross-boundary contracts, behavioral modes, reusable abstractions, or component splits carries enough surface to justify the full convergence process first. 4. **Explicit over Implicit**: Make intentions clear through code structure and naming 5. **Delete over Comment**: Remove unused code instead of commenting it out diff --git a/dev-workflows/skills/documentation-criteria/SKILL.md b/dev-workflows/skills/documentation-criteria/SKILL.md index 344a7a7..92c2dd6 100644 --- a/dev-workflows/skills/documentation-criteria/SKILL.md +++ b/dev-workflows/skills/documentation-criteria/SKILL.md @@ -25,6 +25,12 @@ description: Documentation creation criteria including PRD, ADR, Design Doc, and | 3-5 Files | Design Doc → Work Plan (Required) | Start immediately | | 1-2 Files | None | Direct implementation | +### Structural Escalation + +File count measures size, not structural impact, so a two-file change can still carry architecture-level consequences. + +When any ADR Creation Condition below applies, the scale is **Medium at minimum** (Design Doc + Work Plan required) regardless of file count. Escalation only raises a level; a file count that already reaches Medium or Large stands. + ## ADR Creation Conditions (Required if Any Apply) ### 1. Contract System Changes diff --git a/dev-workflows/skills/documentation-criteria/references/design-template.md b/dev-workflows/skills/documentation-criteria/references/design-template.md index fe33cf0..dea1547 100644 --- a/dev-workflows/skills/documentation-criteria/references/design-template.md +++ b/dev-workflows/skills/documentation-criteria/references/design-template.md @@ -41,6 +41,15 @@ Lists each external resource this feature depends on with its feature-specific i |-------------------------------|-----------------------------|-------| | [Resource label] | [e.g., specific endpoint path, schema source path, IaC module] | [feature-specific scope] | +### Requirement Convergence + +Records exclusions **the user decided** at requirement time. Exclusions this design decided belong in `Future Extensibility`. Mark the first three bullets `N/A — covered by PRD [path]` when a PRD holds them, or the whole section `N/A — reverse-engineer/as-is document`. Open questions stay here in every case, because design readiness depends on them. + +- **Outcome**: [one observable result this change must produce] +- **Non-Goals**: [capability the user excluded | None — user confirmed there are none] +- **Speculative**: [idea the user raised without deciding on -> deferral reason | None] +- **Open questions**: [field the user left as weak-but-explicit | None] + ### Agreement Checklist #### Scope @@ -363,7 +372,7 @@ Mark as N/A with brief rationale when the design introduces entirely new behavio ## Future Extensibility -This section records what was **excluded** from the current design surface. Speculative inclusions belong in a separate proposal. +This section records what **this design** excluded from the current design surface. Exclusions the user decided at requirement time belong in `Requirement Convergence`. Speculative inclusions belong in a separate proposal. - **Deferred possibilities**: [Capabilities considered during design and explicitly excluded from the current design surface. Each entry names either the current requirement it would have served, or marks itself as speculative] - **Intentional limitations**: [What was deliberately kept small and why] diff --git a/dev-workflows/skills/documentation-criteria/references/prd-template.md b/dev-workflows/skills/documentation-criteria/references/prd-template.md index 665cfcc..acce9e9 100644 --- a/dev-workflows/skills/documentation-criteria/references/prd-template.md +++ b/dev-workflows/skills/documentation-criteria/references/prd-template.md @@ -57,9 +57,11 @@ C4Context ### Future / Out of Scope -| Capability | Disposition | Reason | -|---|---|---| -| [Capability excluded during MVP convergence] | future / out-of-scope | [Why it is not required for the current value or obligations] | +`Origin` distinguishes a non-goal the user authored (`user`) from an exclusion the requirement analysis judged (`analysis`). Record `None — user confirmed there are none` when the user considered exclusions and found none. + +| Capability | Disposition | Origin | Reason | +|---|---|---|---| +| [Capability excluded during MVP convergence] | future / out-of-scope | user / analysis | [Why it is not required for the current value or obligations] | ## Non-Functional Requirements diff --git a/dev-workflows/skills/recipe-design/SKILL.md b/dev-workflows/skills/recipe-design/SKILL.md index 9df5531..15d63d1 100644 --- a/dev-workflows/skills/recipe-design/SKILL.md +++ b/dev-workflows/skills/recipe-design/SKILL.md @@ -76,9 +76,11 @@ Invoke codebase-analyzer with its existing schema. The orchestrator constructs ` - Expected action: analyze the seed files and produce design guidance ### Step 3: Scope Confirmation -After codebase-analyzer returns, confirm the design scope with the user before any design work. This is a recipe-local confirmation step. Use AskUserQuestion. +After codebase-analyzer returns, confirm the design scope with the user before any design work. This is a recipe-local confirmation step. -Present, sourced from the codebase-analyzer JSON: +First run the requirement-convergence hearing protocol, using the codebase-analyzer findings as the facts it presents. This recipe has no requirement-analyzer, so the orchestrator both elicits and judges the fields, recording the result as the skill's `convergence` object (`outcome`, `requirements[]` with layer labels, `nonGoals[]`, plus a readiness label per field). `cost` does not apply here: the orchestrator cannot search the repository, and entering this recipe already decided to design. Carry that object into Step 4 so technical-designer persists it to the Design Doc. + +Then present, sourced from the codebase-analyzer JSON, using AskUserQuestion: - **Target files/modules**: `analysisScope.filesAnalyzed` and the modules they belong to - **Affected layers**: layers touched, derived from `analysisScope.categoriesDetected` and `focusAreas` - **Unknowns/assumptions**: `limitations` plus any assumptions codebase-analyzer recorded @@ -98,7 +100,7 @@ After the user confirms the scope, count the confirmed target files and set the Pass the full codebase-analyzer JSON to technical-designer (handoff contract HC-02). ADRs use alternative comparison; Design Docs use Design Convergence. - Invoke **technical-designer** using Agent tool - - For Design Doc: `subagent_type: "dev-workflows:technical-designer"`, `description: "Design Doc creation"`, `prompt: "Create Design Doc based on the requirements. Requirements: [user requirements verbatim]. Codebase analysis: [codebase-analyzer JSON from Step 2]. Confirmed scope and user answers: [Step 3 confirmed scope and user answers]. Apply the code: prefix to codebase-analyzer fact_ids when filling the Fact Disposition Table."` + - For Design Doc: `subagent_type: "dev-workflows:technical-designer"`, `description: "Design Doc creation"`, `prompt: "Create Design Doc based on the requirements. Requirements: [user requirements verbatim]. Codebase analysis: [codebase-analyzer JSON from Step 2]. Confirmed scope and user answers: [Step 3 confirmed scope and user answers]. Convergence result: [Step 3 `convergence` object]. Apply the code: prefix to codebase-analyzer fact_ids when filling the Fact Disposition Table."` - For ADR: `subagent_type: "dev-workflows:technical-designer"`, `description: "ADR creation"`, `prompt: "Create ADR for [technical decision]. Requirements: [user requirements verbatim]. Codebase analysis: [codebase-analyzer JSON from Step 2]. Confirmed scope and user answers: [Step 3 confirmed scope and user answers]. Present at least two alternatives with trade-offs."` - **(Design Doc only)** Invoke **code-verifier** to verify the Design Doc against existing code. Skip for ADR. - `subagent_type: "dev-workflows:code-verifier"`, `description: "Design Doc verification"`, `prompt: "doc_type: design-doc document_path: [Design Doc path] Verify Design Doc against existing code."` @@ -115,6 +117,7 @@ Pass the full codebase-analyzer JSON to technical-designer (handoff contract HC- - [ ] Built the Step 1 scope bootstrap seed (or obtained target files from the user when the search returned none) - [ ] Executed codebase-analyzer with a populated `requirement_analysis` +- [ ] Ran the requirement-convergence hearing and carried its result into design - [ ] Confirmed the design scope with the user and set the scale from the confirmed target files - [ ] Created appropriate design document (ADR or Design Doc) with technical-designer - [ ] Executed code-verifier on Design Doc and passed results to document-reviewer (skip for ADR-only) diff --git a/dev-workflows/skills/recipe-implement/SKILL.md b/dev-workflows/skills/recipe-implement/SKILL.md index da6d033..57437b7 100644 --- a/dev-workflows/skills/recipe-implement/SKILL.md +++ b/dev-workflows/skills/recipe-implement/SKILL.md @@ -53,14 +53,17 @@ When continuing existing flow, verify: ### After requirement-analyzer [Stop] +Run the requirement-convergence hearing protocol on the returned `convergence` object before presenting anything else, using the analyzer's scope facts and cost band as the facts it presents. + When user responds to questions: +- If any `convergence` field is below `ready` → Re-execute requirement-analyzer with the hearing answers so the record is re-judged. Repeat until every field is `ready` or `weak-but-explicit` - If response matches any `scopeDependencies.question` → Check `impact` for scale change - If scale changes → Re-execute requirement-analyzer with updated context - If `confidence: "confirmed"` or no scale change → Proceed to next step ### 4. Register All Flow Steps Using TaskCreate (MANDATORY) -After scale determination, use TaskCreate to register `"Select and map applicable rules"`, each design/planning step, and the implementation, verification, cleanup, and report phases. Complete registration before invoking subagents; mark and advance the active phase with TaskUpdate. +After scale determination, use TaskCreate to register each design/planning step and the implementation, verification, cleanup, and report phases. Complete registration before invoking subagents; mark and advance the active phase with TaskUpdate. ## Subagents Orchestration Guide Compliance Execution diff --git a/dev-workflows/skills/requirement-convergence/SKILL.md b/dev-workflows/skills/requirement-convergence/SKILL.md new file mode 100644 index 0000000..bcb8092 --- /dev/null +++ b/dev-workflows/skills/requirement-convergence/SKILL.md @@ -0,0 +1,69 @@ +--- +name: requirement-convergence +description: Separates the outcome a change must produce from the requirements proposed to reach it, records what the user excluded, and bands cost from structure. Use when a requirement enters a workflow, before design begins. +--- + +# Requirement Convergence + +## Purpose + +Requirements arrive bloated, ambiguous, or aimed at the wrong outcome. A capable model reconciles all three into a coherent plan and builds it faithfully — delivering exactly what was asked for when what was asked for was wrong. + +This skill converges **what to build**. How to build it, and which documents the change requires, are settled after the what is. + +## Convergence Fields + +| Field | Pass condition | +|-------|----------------| +| `outcome` | One observable result. A requirement that does not serve it is excess. | +| `requirements[]` | Every item labeled `current-state`, `desired-future`, or `speculative`. | +| `nonGoals[]` | Authored by the user, or the user stated there are none. | +| `cost` | A band with the structural evidence that places it, plus the unknowns that remain. | + +`cost` is a rough band, not the effort estimate a work plan schedules against; requirements cannot support person-days. Its unknowns carry more decision weight than its size. + +Each field carries a readiness label: `ready`, `weak`, or `weak-but-explicit` (weak, and the user agreed to leave it unresolved). Only the user sets `weak-but-explicit`. Requirements are converged when every applicable field is `ready` or `weak-but-explicit`. + +Judgment rules per field: [references/criteria.md](references/criteria.md). + +## Hearing Protocol + +Eliciting requires user interaction, so the orchestrator owns it. It runs after the analysis that produced the scope facts, because the orchestrator investigates nothing itself. + +Register these steps before starting and record each step's evidence as it completes: + +| Step | Action | Completion evidence | +|------|--------|---------------------| +| 1 | State the scope facts the analysis produced, then separately what they imply for the requirement | Facts listed with the analysis output they came from | +| 2 | Ask about the fields below `ready`, at most two questions per message | One question per field below `ready` | +| 3 | Record each answer as that field's value | The value uses wording the user supplied, not wording the hearing offered | +| 4 | Re-ask once when a recorded value still fails its pass condition, then mark the field `weak-but-explicit` when the user agrees to leave the second answer as it stands | Two recorded answers, or the user's agreement to stop | +| 5 | Hand the record to the step that judges the fields | An updated record returned from that step | + +Step 3's evidence is what keeps the hearing reviewable: a value restating the hearing's own candidates fails it, so the user's judgment survives however the question was put. + +## Storage Protocol + +| Carrier | Holds | Written by | +|---------|-------|------------| +| The convergence record in the judging step's output | Every field with its readiness label | Whichever step judged them | +| PRD `Success Criteria` and `Future / Out of Scope` | `outcome`; `nonGoals` and `speculative` requirements with origin `user` | The agent that owns the PRD | +| Design Doc `Requirement Convergence` | The same when no PRD exists, and the fields left `weak-but-explicit` in every case | The agent that owns the Design Doc | + +A flow that produces neither document carries the record in its own context to the next step. + +## Reference Protocol (For Downstream Consumers) + +1. Read the convergence record from the prompt. +2. Treat `nonGoals` and `speculative` requirements as excluded from the current change. A `speculative` item becomes buildable only after the user promotes it to `desired-future`. +3. Treat a `weak-but-explicit` field as a recorded open question rather than a settled decision, and escalate when the work depends on resolving it. + +## Quality Checklist + +- [ ] Scope facts were presented before questions were asked +- [ ] `nonGoals` came from the user, or the user stated there are none +- [ ] Every applicable field is `ready`, or `weak-but-explicit` by the user's agreement + +## References + +- [references/criteria.md](references/criteria.md) — judgment rules per field, cost inputs, challenge intensity, solution-in-disguise test diff --git a/dev-workflows/skills/requirement-convergence/references/criteria.md b/dev-workflows/skills/requirement-convergence/references/criteria.md new file mode 100644 index 0000000..87818ff --- /dev/null +++ b/dev-workflows/skills/requirement-convergence/references/criteria.md @@ -0,0 +1,62 @@ +# Convergence Criteria + +Judgment rules for the four convergence fields. Read when eliciting or evaluating them. + +## outcome + +One observable result the change must produce, not a feature list. + +A requirement that cannot be traced to the outcome is excess: drop it, or have the user widen the outcome to cover it. + +## requirements[] — layer separation + +| Layer | Meaning | Buildable now | +|-------|---------|---------------| +| `current-state` | Behavior that already exists | No — these are facts, not work | +| `desired-future` | The change the user is asking for | Yes | +| `speculative` | An idea the user raised without deciding on | No — record with a deferral reason | + +Flattening these three into one requirement list is what makes a bloated plan look coherent, because every item then reads as equally required. Label each item; ask when a label is unclear rather than inferring it. + +## nonGoals[] + +Capabilities deliberately excluded from this change, authored by the user. + +Present the cost band and its unknowns first, then ask what to leave out. `userAgreedNone` records that the user considered exclusions and found none — an agent cannot set it. + +An adjacent capability the agent noticed is a question for the user, not a non-goal. + +## cost + +Cost follows structure and count, not behavior, so it is decided from these inputs alone: + +| Input | How it is obtained | +|-------|--------------------| +| Number and kind of targets to change | Grep/Glob over the affected files | +| Number of boundaries crossed | Affected path composition plus import and caller tracing | +| Whether an equivalent already exists (reuse or new) | Grep for a similar name or shape | +| Whether persisted state needs converting | Whether a schema or migration path is in the change set | +| Whether verification support already exists | Glob for the area's existing test harness | +| What remains unknown | WebSearch for a dependency's current capability; anything the above cannot resolve | + +Reading what the code *does* answers whether the change is correct, not what it costs, and belongs to the codebase analysis that precedes design. + +Record `cost` as one band, the inputs above that place it, and the remaining unknowns. A flow declares `cost` out of scope only where its own steps say so. + +## Challenge intensity + +The band's only job is to select a row here, so cheap requirements stay cheap to accept. + +| Band | Meaning | Challenge | +|------|---------|-----------| +| `low-reversible` | Additive, flagged, or easily deleted | Record the fields and accept the requirement | +| `medium` | Reverting would touch other work | Present the cost and one lower-cost alternative | +| `high-irreversible` | Public contract, persisted data shape, or dependency swap | Present the trade-off and require a user decision before design | + +Report an unknown that would move the band up as a blocking question rather than assuming the lower band. + +## Solution-in-disguise test + +When the requirement names a mechanism rather than an outcome ("add a cache layer", "introduce a queue"), state three materially different ways to reach the same outcome. + +When three exist, the named mechanism is one option among several — present them for a user decision. When the mechanism is genuinely the only route, record that and proceed. diff --git a/dev-workflows/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows/skills/subagents-orchestration-guide/SKILL.md index 7eaf34a..8393731 100644 --- a/dev-workflows/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows/skills/subagents-orchestration-guide/SKILL.md @@ -13,6 +13,8 @@ All investigation, analysis, and implementation work flows through specialized s When receiving a new task, pass user requirements directly to requirement-analyzer. Determine the workflow based on its scale assessment result. +requirement-analyzer returns a `convergence` object. Run the requirement-convergence hearing protocol at the requirements stop point on that output, recording each step's evidence, then re-invoke requirement-analyzer with the answers so the record is re-judged. The hearing runs in the orchestrator because it requires user interaction, and runs after the analysis because the orchestrator investigates nothing itself. + ### Requirement Change Detection During Flow **During flow execution**, monitor user responses for scope-expanding signals: @@ -79,7 +81,7 @@ Autonomous execution MUST stop and wait for user input at these points. | Phase | Stop Point | User Action Required | |-------|------------|---------------------| -| Requirements | After requirement-analyzer completes | Confirm requirements / Answer questions | +| Requirements | After requirement-analyzer completes | Answer the requirement-convergence hearing, then confirm requirements | | PRD | After document-reviewer completes PRD review | Approve PRD | | UI Spec | After document-reviewer completes UI Spec review (frontend/fullstack) | Approve UI Spec | | ADR | After document-reviewer completes ADR review (if ADR created) | Approve ADR | @@ -95,6 +97,8 @@ Autonomous execution MUST stop and wait for user input at these points. | Medium | 3-5 | Update※1 | Conditional※2 | **Required** | **Required** | | Large | 6+ | **Required**※3 | Conditional※2 | **Required** | **Required** | +File count sets the floor; documentation-criteria Structural Escalation raises it when any ADR Creation Condition applies. + ※1: Update if PRD exists for the relevant feature ※2: When there are architecture changes, new technology introduction, or data flow changes ※3: New creation/update existing/reverse PRD (when no existing PRD) @@ -136,6 +140,7 @@ Two additional rules: - subagent_type: "requirement-analyzer" - description: "Requirement analysis" - prompt: "Requirements: [user requirements]. Context: [any relevant context]. Perform requirement analysis and scale determination." +- On re-invocation after the convergence hearing, append: "Hearing answers: [the user's answers per convergence field]. Re-judge the convergence record with these answers." ### Call Example (codebase-analyzer) - subagent_type: "codebase-analyzer" @@ -157,7 +162,7 @@ When invoked alongside codebase-analyzer for frontend or fullstack-frontend work ## Structured Response Specification Subagents respond in JSON format. Key fields for orchestrator decisions: -- **requirement-analyzer**: scale, confidence, affectedLayers, adrRequired, scopeDependencies, questions +- **requirement-analyzer**: scale, confidence, affectedLayers, adrRequired, scopeDependencies, questions, convergence (fields with readiness labels; a field below `ready` returns as a `convergence` question) - **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**: `summary.status` (consistent/mostly_consistent/needs_review/inconsistent/blocked), `summary.consistencyScore`, discrepancies[], reverseCoverage (including dataOperationsInCode, testBoundariesSectionPresent). Pre-implementation: verifies Design Doc claims against existing codebase. Post-implementation: verifies implementation consistency against the governing Design Doc or Work Plan (pass `code_paths` scoped to changed files) @@ -192,7 +197,7 @@ Criteria for timing when to call each agent: ## Basic Flow: Planning and Implementation -Always start with requirement-analyzer, then select the minimum planning flow required by scale and affected layers. +Always start with requirement-analyzer, hold the requirement-convergence hearing on its output, then select the minimum planning flow required by scale and affected layers. ### Planning flow (per scale) @@ -202,7 +207,7 @@ Always start with requirement-analyzer, then select the minimum planning flow re | Medium | requirement-analyzer → external resource hearing → codebase-analyzer (+ ui-analyzer in parallel for frontend/fullstack) → optional UI Spec → optional ADR → Design Doc → code-verifier → document-reviewer → design-sync → acceptance-test-generator → work-planner → work plan review (document-reviewer, doc_type WorkPlan) → task-decomposer | | Small | requirement-analyzer → work-planner | -External resource hearing runs in the orchestrator (it requires AskUserQuestion). ui-analyzer joins codebase-analyzer in parallel only when the work has a frontend surface; for backend-only work the planning flow uses codebase-analyzer alone. +The requirement-convergence hearing follows requirement-analyzer in every flow. Both it and the external resource hearing run in the orchestrator (they require AskUserQuestion). ui-analyzer joins codebase-analyzer in parallel only when the work has a frontend surface; for backend-only work the planning flow uses codebase-analyzer alone. After the planning flow completes and the user grants batch approval, implementation proceeds. Verifying the plan is implementable end-to-end (verification lanes, fixtures, E2E environment) is an optional preflight the user runs at their discretion via the recipe-prepare-implementation recipe; this guide does not invoke any orchestrator above the agent layer. @@ -345,7 +350,13 @@ Register overall phases using TaskCreate. Update each phase with TaskUpdate as i ### Handoff Contracts #### HC-01: requirement-analyzer → codebase-analyzer - - Pass: `requirement_analysis`, `prd_path` (if exists), original user requirements + - Pass: `requirement_analysis` (including `convergence`), `prd_path` (if exists), original user requirements + + #### HC-01b: convergence record → document owner + - Pass `convergence` from the last requirement-analyzer invocation (or, in flows without one, the orchestrator's own judged record) to whichever agent owns the persisting document + - **prd-creator** (when a PRD is created or updated): persists `outcome` to `Success Criteria`, and `nonGoals` plus `speculative` requirements to `Future / Out of Scope` with origin `user` + - **technical-designer / technical-designer-frontend**: persists the same to the Design Doc's `Requirement Convergence` when no PRD exists, and always records the fields left `weak-but-explicit` there + - Pass the record unchanged; a field's readiness label travels with it #### HC-02: codebase-analyzer → technical-designer - Pass: full codebase-analyzer JSON as additional context diff --git a/dev-workflows/skills/subagents-orchestration-guide/references/monorepo-flow.md b/dev-workflows/skills/subagents-orchestration-guide/references/monorepo-flow.md index 74a52d2..ed1889d 100644 --- a/dev-workflows/skills/subagents-orchestration-guide/references/monorepo-flow.md +++ b/dev-workflows/skills/subagents-orchestration-guide/references/monorepo-flow.md @@ -14,7 +14,7 @@ This reference defines the orchestration flow for projects spanning multiple lay | Step | Agent | Purpose | Output | |------|-------|---------|--------| -| 1 | requirement-analyzer | Requirement analysis + scale determination **[Stop]** | Requirements + scale | +| 1 | requirement-analyzer → (orchestrator) | Requirement analysis + scale determination, then the requirement-convergence hearing on its `convergence` output, re-invoking the analyzer with the answers **[Stop]** | Converged requirements + scale | | 2 | prd-creator | PRD covering entire feature (all layers) | Single PRD | | 3 | document-reviewer | PRD review **[Stop]** | Approval | | 4 | (orchestrator) | External resource hearing per the external-resource-context skill (frontend domain primary; backend / api / infra domains as applicable for the layer scope). File-existence branching as defined in the skill | `docs/project-context/external-resources.md` written or updated | @@ -36,7 +36,7 @@ This reference defines the orchestration flow for projects spanning multiple lay | Step | Agent | Purpose | Output | |------|-------|---------|--------| -| 1 | requirement-analyzer | Requirement analysis + scale determination **[Stop]** | Requirements + scale | +| 1 | requirement-analyzer → (orchestrator) | Requirement analysis + scale determination, then the requirement-convergence hearing on its `convergence` output, re-invoking the analyzer with the answers **[Stop]** | Converged requirements + scale | | 2 | (orchestrator) | External resource hearing per the external-resource-context skill (frontend / backend / api / infra domains as applicable). File-existence branching as defined in the skill | `docs/project-context/external-resources.md` written or updated | | 3 | codebase-analyzer ×2 + ui-analyzer | Codebase analysis per layer + UI fact gathering (parallel; ui-analyzer reads external-resources.md and fetches external UI sources via inherited MCP/URL access) | Codebase guidance per layer + UI fact JSON | | 4 | (orchestrator) | Ask user for prototype code **[Stop]** | Prototype path or none | diff --git a/dev-workflows/skills/task-analyzer/references/skills-index.yaml b/dev-workflows/skills/task-analyzer/references/skills-index.yaml index 7f2b364..d99869d 100644 --- a/dev-workflows/skills/task-analyzer/references/skills-index.yaml +++ b/dev-workflows/skills/task-analyzer/references/skills-index.yaml @@ -231,3 +231,19 @@ skills: - "Output Format" - "Quality Checklist" - "References" + + requirement-convergence: + skill: "requirement-convergence" + tags: [cross-cutting, requirements, scope, non-goals, outcome, rough-estimate, trade-off, hearing-protocol, convergence] + typical-use: "Converges what to build before design by separating outcome from requirement layers, recording user-authored non-goals, and banding cost from structure rather than behavior" + size: small + key-references: + - "references/criteria.md" + sections: + - "Purpose" + - "Convergence Fields" + - "Hearing Protocol" + - "Storage Protocol" + - "Reference Protocol (For Downstream Consumers)" + - "Quality Checklist" + - "References" diff --git a/package.json b/package.json index 8b8a050..bf49834 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "claude-code-workflows", - "version": "0.22.9", + "version": "0.23.0", "private": true, "type": "module", "engines": { diff --git a/skills/coding-principles/SKILL.md b/skills/coding-principles/SKILL.md index 80914b5..f4230e9 100644 --- a/skills/coding-principles/SKILL.md +++ b/skills/coding-principles/SKILL.md @@ -9,7 +9,7 @@ description: Language-agnostic coding principles for maintainability, readabilit 1. **Maintainability over Speed**: Prioritize long-term code health over initial development velocity 2. **Simplicity First**: Choose the simplest solution that meets requirements (YAGNI principle) -3. **Design Convergence**: Deliver the current required outcome with the least new design surface. Use implementation-approach when selecting persistent state, public or cross-boundary contracts, behavioral modes, reusable abstractions, or component splits. +3. **Design Convergence**: Deliver the current required outcome with the least new design surface. Selecting persistent state, public or cross-boundary contracts, behavioral modes, reusable abstractions, or component splits carries enough surface to justify the full convergence process first. 4. **Explicit over Implicit**: Make intentions clear through code structure and naming 5. **Delete over Comment**: Remove unused code instead of commenting it out diff --git a/skills/documentation-criteria/SKILL.md b/skills/documentation-criteria/SKILL.md index 344a7a7..92c2dd6 100644 --- a/skills/documentation-criteria/SKILL.md +++ b/skills/documentation-criteria/SKILL.md @@ -25,6 +25,12 @@ description: Documentation creation criteria including PRD, ADR, Design Doc, and | 3-5 Files | Design Doc → Work Plan (Required) | Start immediately | | 1-2 Files | None | Direct implementation | +### Structural Escalation + +File count measures size, not structural impact, so a two-file change can still carry architecture-level consequences. + +When any ADR Creation Condition below applies, the scale is **Medium at minimum** (Design Doc + Work Plan required) regardless of file count. Escalation only raises a level; a file count that already reaches Medium or Large stands. + ## ADR Creation Conditions (Required if Any Apply) ### 1. Contract System Changes diff --git a/skills/documentation-criteria/references/design-template.md b/skills/documentation-criteria/references/design-template.md index fe33cf0..dea1547 100644 --- a/skills/documentation-criteria/references/design-template.md +++ b/skills/documentation-criteria/references/design-template.md @@ -41,6 +41,15 @@ Lists each external resource this feature depends on with its feature-specific i |-------------------------------|-----------------------------|-------| | [Resource label] | [e.g., specific endpoint path, schema source path, IaC module] | [feature-specific scope] | +### Requirement Convergence + +Records exclusions **the user decided** at requirement time. Exclusions this design decided belong in `Future Extensibility`. Mark the first three bullets `N/A — covered by PRD [path]` when a PRD holds them, or the whole section `N/A — reverse-engineer/as-is document`. Open questions stay here in every case, because design readiness depends on them. + +- **Outcome**: [one observable result this change must produce] +- **Non-Goals**: [capability the user excluded | None — user confirmed there are none] +- **Speculative**: [idea the user raised without deciding on -> deferral reason | None] +- **Open questions**: [field the user left as weak-but-explicit | None] + ### Agreement Checklist #### Scope @@ -363,7 +372,7 @@ Mark as N/A with brief rationale when the design introduces entirely new behavio ## Future Extensibility -This section records what was **excluded** from the current design surface. Speculative inclusions belong in a separate proposal. +This section records what **this design** excluded from the current design surface. Exclusions the user decided at requirement time belong in `Requirement Convergence`. Speculative inclusions belong in a separate proposal. - **Deferred possibilities**: [Capabilities considered during design and explicitly excluded from the current design surface. Each entry names either the current requirement it would have served, or marks itself as speculative] - **Intentional limitations**: [What was deliberately kept small and why] diff --git a/skills/documentation-criteria/references/prd-template.md b/skills/documentation-criteria/references/prd-template.md index 665cfcc..acce9e9 100644 --- a/skills/documentation-criteria/references/prd-template.md +++ b/skills/documentation-criteria/references/prd-template.md @@ -57,9 +57,11 @@ C4Context ### Future / Out of Scope -| Capability | Disposition | Reason | -|---|---|---| -| [Capability excluded during MVP convergence] | future / out-of-scope | [Why it is not required for the current value or obligations] | +`Origin` distinguishes a non-goal the user authored (`user`) from an exclusion the requirement analysis judged (`analysis`). Record `None — user confirmed there are none` when the user considered exclusions and found none. + +| Capability | Disposition | Origin | Reason | +|---|---|---|---| +| [Capability excluded during MVP convergence] | future / out-of-scope | user / analysis | [Why it is not required for the current value or obligations] | ## Non-Functional Requirements diff --git a/skills/recipe-design/SKILL.md b/skills/recipe-design/SKILL.md index 9df5531..15d63d1 100644 --- a/skills/recipe-design/SKILL.md +++ b/skills/recipe-design/SKILL.md @@ -76,9 +76,11 @@ Invoke codebase-analyzer with its existing schema. The orchestrator constructs ` - Expected action: analyze the seed files and produce design guidance ### Step 3: Scope Confirmation -After codebase-analyzer returns, confirm the design scope with the user before any design work. This is a recipe-local confirmation step. Use AskUserQuestion. +After codebase-analyzer returns, confirm the design scope with the user before any design work. This is a recipe-local confirmation step. -Present, sourced from the codebase-analyzer JSON: +First run the requirement-convergence hearing protocol, using the codebase-analyzer findings as the facts it presents. This recipe has no requirement-analyzer, so the orchestrator both elicits and judges the fields, recording the result as the skill's `convergence` object (`outcome`, `requirements[]` with layer labels, `nonGoals[]`, plus a readiness label per field). `cost` does not apply here: the orchestrator cannot search the repository, and entering this recipe already decided to design. Carry that object into Step 4 so technical-designer persists it to the Design Doc. + +Then present, sourced from the codebase-analyzer JSON, using AskUserQuestion: - **Target files/modules**: `analysisScope.filesAnalyzed` and the modules they belong to - **Affected layers**: layers touched, derived from `analysisScope.categoriesDetected` and `focusAreas` - **Unknowns/assumptions**: `limitations` plus any assumptions codebase-analyzer recorded @@ -98,7 +100,7 @@ After the user confirms the scope, count the confirmed target files and set the Pass the full codebase-analyzer JSON to technical-designer (handoff contract HC-02). ADRs use alternative comparison; Design Docs use Design Convergence. - Invoke **technical-designer** using Agent tool - - For Design Doc: `subagent_type: "dev-workflows:technical-designer"`, `description: "Design Doc creation"`, `prompt: "Create Design Doc based on the requirements. Requirements: [user requirements verbatim]. Codebase analysis: [codebase-analyzer JSON from Step 2]. Confirmed scope and user answers: [Step 3 confirmed scope and user answers]. Apply the code: prefix to codebase-analyzer fact_ids when filling the Fact Disposition Table."` + - For Design Doc: `subagent_type: "dev-workflows:technical-designer"`, `description: "Design Doc creation"`, `prompt: "Create Design Doc based on the requirements. Requirements: [user requirements verbatim]. Codebase analysis: [codebase-analyzer JSON from Step 2]. Confirmed scope and user answers: [Step 3 confirmed scope and user answers]. Convergence result: [Step 3 `convergence` object]. Apply the code: prefix to codebase-analyzer fact_ids when filling the Fact Disposition Table."` - For ADR: `subagent_type: "dev-workflows:technical-designer"`, `description: "ADR creation"`, `prompt: "Create ADR for [technical decision]. Requirements: [user requirements verbatim]. Codebase analysis: [codebase-analyzer JSON from Step 2]. Confirmed scope and user answers: [Step 3 confirmed scope and user answers]. Present at least two alternatives with trade-offs."` - **(Design Doc only)** Invoke **code-verifier** to verify the Design Doc against existing code. Skip for ADR. - `subagent_type: "dev-workflows:code-verifier"`, `description: "Design Doc verification"`, `prompt: "doc_type: design-doc document_path: [Design Doc path] Verify Design Doc against existing code."` @@ -115,6 +117,7 @@ Pass the full codebase-analyzer JSON to technical-designer (handoff contract HC- - [ ] Built the Step 1 scope bootstrap seed (or obtained target files from the user when the search returned none) - [ ] Executed codebase-analyzer with a populated `requirement_analysis` +- [ ] Ran the requirement-convergence hearing and carried its result into design - [ ] Confirmed the design scope with the user and set the scale from the confirmed target files - [ ] Created appropriate design document (ADR or Design Doc) with technical-designer - [ ] Executed code-verifier on Design Doc and passed results to document-reviewer (skip for ADR-only) diff --git a/skills/recipe-front-design/SKILL.md b/skills/recipe-front-design/SKILL.md index c988b77..b572660 100644 --- a/skills/recipe-front-design/SKILL.md +++ b/skills/recipe-front-design/SKILL.md @@ -85,9 +85,11 @@ Invoke codebase-analyzer with its existing schema. The orchestrator constructs ` - Expected action: analyze the seed files for frontend design guidance (data, contracts, dependencies, quality assurance mechanisms) ### Step 3: Scope Confirmation -After codebase-analyzer returns, confirm the design scope with the user before any design work. This is a recipe-local confirmation step. Use AskUserQuestion. +After codebase-analyzer returns, confirm the design scope with the user before any design work. This is a recipe-local confirmation step. -Present, sourced from the codebase-analyzer JSON: +First run the requirement-convergence hearing protocol, using the codebase-analyzer findings as the facts it presents. This recipe has no requirement-analyzer, so the orchestrator both elicits and judges the fields, recording the result as the skill's `convergence` object (`outcome`, `requirements[]` with layer labels, `nonGoals[]`, plus a readiness label per field). `cost` does not apply here: the orchestrator cannot search the repository, and entering this recipe already decided to design. Carry that object into Steps 6 and 7 so ui-spec-designer respects the non-goals and technical-designer-frontend persists it to the Design Doc. + +Then present, sourced from the codebase-analyzer JSON, using AskUserQuestion: - **Target files/modules**: `analysisScope.filesAnalyzed` and the modules they belong to - **Affected layers**: layers touched, derived from `analysisScope.categoriesDetected` and `focusAreas` - **Unknowns/assumptions**: `limitations` plus any assumptions codebase-analyzer recorded @@ -131,6 +133,7 @@ Then create the UI Specification: - `description: "UI Spec creation"` - Build the prompt by including: - Source: an existing PRD in `docs/prd/` when one exists for this feature; otherwise the user requirements with the Step 2 codebase-analyzer JSON and the Step 3 confirmed scope + - The Step 3 `convergence` object's `nonGoals` and `speculative` requirements, as capabilities the UI Spec leaves out - `ui_analysis`: ui-analyzer JSON from Step 5 (includes externalResources fetched_summary and componentStructure / propsPatterns / cssLayout / etc.) - Prototype path when provided - Example (existing PRD): `prompt: "Create UI Spec from PRD at [path]. ui_analysis: [JSON from Step 5 ui-analyzer]. Prototype code is at [user-provided path]. Place prototype in docs/ui-spec/assets/{feature-name}/."` @@ -143,7 +146,7 @@ Then create the UI Specification: Pass the Step 2 codebase-analyzer output and the Step 5 ui-analyzer output to technical-designer-frontend. ADRs use alternative comparison; Design Docs use Design Convergence. - Invoke **technical-designer-frontend** using Agent tool - For ADR: `subagent_type: "dev-workflows-frontend:technical-designer-frontend"`, `description: "ADR creation"`, `prompt: "Create ADR for [technical decision]. Requirements: [user requirements verbatim]. Codebase analysis: [codebase-analyzer JSON from Step 2]. UI analysis: [ui-analyzer JSON from Step 5]. Confirmed scope and user answers: [Step 3 confirmed scope and user answers]. Present at least two alternatives with trade-offs."` - - For Design Doc: `subagent_type: "dev-workflows-frontend:technical-designer-frontend"`, `description: "Design Doc creation"`, `prompt: "Create Design Doc based on the requirements. Requirements: [user requirements verbatim]. Codebase analysis: [codebase-analyzer JSON from Step 2]. UI analysis: [ui-analyzer JSON from Step 5]. Confirmed scope and user answers: [Step 3 confirmed scope and user answers]. UI Spec is at [ui-spec path]. Inherit component structure and state design from UI Spec. Apply the code: prefix to codebase-analyzer fact_ids and ui: prefix to ui-analyzer fact_ids when filling the Fact Disposition Table."` + - For Design Doc: `subagent_type: "dev-workflows-frontend:technical-designer-frontend"`, `description: "Design Doc creation"`, `prompt: "Create Design Doc based on the requirements. Requirements: [user requirements verbatim]. Codebase analysis: [codebase-analyzer JSON from Step 2]. UI analysis: [ui-analyzer JSON from Step 5]. Confirmed scope and user answers: [Step 3 confirmed scope and user answers]. Convergence result: [Step 3 `convergence` object]. UI Spec is at [ui-spec path]. Inherit component structure and state design from UI Spec. Apply the code: prefix to codebase-analyzer fact_ids and ui: prefix to ui-analyzer fact_ids when filling the Fact Disposition Table."` - **(Design Doc only)** Invoke **code-verifier** to verify Design Doc against existing code. Skip for ADR. - `subagent_type: "dev-workflows-frontend:code-verifier"`, `description: "Design Doc verification"`, `prompt: "doc_type: design-doc document_path: [Design Doc path] Verify Design Doc against existing code."` - **(Design Doc only)** Invoke **document-reviewer** to verify consistency, completeness, and adopted design validity @@ -160,6 +163,7 @@ Pass the Step 2 codebase-analyzer output and the Step 5 ui-analyzer output to te - [ ] Built the Step 1 scope bootstrap seed (or obtained target files from the user when the search returned none) - [ ] Executed codebase-analyzer with a populated `requirement_analysis` +- [ ] Ran the requirement-convergence hearing and carried its result into design - [ ] Confirmed the design scope with the user and set the scale from the confirmed target files - [ ] Executed external resource hearing per the external-resource-context skill (file written or update explicitly skipped by user) - [ ] Executed ui-analyzer; codebase-analyzer (Step 2) and ui-analyzer (Step 5) outputs reused by ui-spec-designer and technical-designer-frontend diff --git a/skills/recipe-fullstack-implement/SKILL.md b/skills/recipe-fullstack-implement/SKILL.md index 314682d..d750e48 100644 --- a/skills/recipe-fullstack-implement/SKILL.md +++ b/skills/recipe-fullstack-implement/SKILL.md @@ -60,11 +60,14 @@ Key points to enforce as the orchestrator runs the flow: ### 4. Register All Flow Steps Using TaskCreate (MANDATORY) -After scale determination, use TaskCreate to register `"Select and map applicable rules"`, each design/planning step, and the implementation, verification, cleanup, and report phases. Complete registration before invoking subagents; mark and advance the active phase with TaskUpdate. +After scale determination, use TaskCreate to register each design/planning step and the implementation, verification, cleanup, and report phases. Complete registration before invoking subagents; mark and advance the active phase with TaskUpdate. ## After requirement-analyzer [Stop] +Run the requirement-convergence hearing protocol on the returned `convergence` object before presenting anything else, using the analyzer's scope facts and cost band as the facts it presents. + When user responds to questions: +- If any `convergence` field is below `ready` → Re-execute requirement-analyzer with the hearing answers so the record is re-judged. Repeat until every field is `ready` or `weak-but-explicit` - If response matches any `scopeDependencies.question` → Check `impact` for scale change - If scale changes → Re-execute requirement-analyzer with updated context - If `confidence: "confirmed"` or no scale change → Proceed to next step diff --git a/skills/recipe-implement/SKILL.md b/skills/recipe-implement/SKILL.md index da6d033..57437b7 100644 --- a/skills/recipe-implement/SKILL.md +++ b/skills/recipe-implement/SKILL.md @@ -53,14 +53,17 @@ When continuing existing flow, verify: ### After requirement-analyzer [Stop] +Run the requirement-convergence hearing protocol on the returned `convergence` object before presenting anything else, using the analyzer's scope facts and cost band as the facts it presents. + When user responds to questions: +- If any `convergence` field is below `ready` → Re-execute requirement-analyzer with the hearing answers so the record is re-judged. Repeat until every field is `ready` or `weak-but-explicit` - If response matches any `scopeDependencies.question` → Check `impact` for scale change - If scale changes → Re-execute requirement-analyzer with updated context - If `confidence: "confirmed"` or no scale change → Proceed to next step ### 4. Register All Flow Steps Using TaskCreate (MANDATORY) -After scale determination, use TaskCreate to register `"Select and map applicable rules"`, each design/planning step, and the implementation, verification, cleanup, and report phases. Complete registration before invoking subagents; mark and advance the active phase with TaskUpdate. +After scale determination, use TaskCreate to register each design/planning step and the implementation, verification, cleanup, and report phases. Complete registration before invoking subagents; mark and advance the active phase with TaskUpdate. ## Subagents Orchestration Guide Compliance Execution diff --git a/skills/requirement-convergence/SKILL.md b/skills/requirement-convergence/SKILL.md new file mode 100644 index 0000000..bcb8092 --- /dev/null +++ b/skills/requirement-convergence/SKILL.md @@ -0,0 +1,69 @@ +--- +name: requirement-convergence +description: Separates the outcome a change must produce from the requirements proposed to reach it, records what the user excluded, and bands cost from structure. Use when a requirement enters a workflow, before design begins. +--- + +# Requirement Convergence + +## Purpose + +Requirements arrive bloated, ambiguous, or aimed at the wrong outcome. A capable model reconciles all three into a coherent plan and builds it faithfully — delivering exactly what was asked for when what was asked for was wrong. + +This skill converges **what to build**. How to build it, and which documents the change requires, are settled after the what is. + +## Convergence Fields + +| Field | Pass condition | +|-------|----------------| +| `outcome` | One observable result. A requirement that does not serve it is excess. | +| `requirements[]` | Every item labeled `current-state`, `desired-future`, or `speculative`. | +| `nonGoals[]` | Authored by the user, or the user stated there are none. | +| `cost` | A band with the structural evidence that places it, plus the unknowns that remain. | + +`cost` is a rough band, not the effort estimate a work plan schedules against; requirements cannot support person-days. Its unknowns carry more decision weight than its size. + +Each field carries a readiness label: `ready`, `weak`, or `weak-but-explicit` (weak, and the user agreed to leave it unresolved). Only the user sets `weak-but-explicit`. Requirements are converged when every applicable field is `ready` or `weak-but-explicit`. + +Judgment rules per field: [references/criteria.md](references/criteria.md). + +## Hearing Protocol + +Eliciting requires user interaction, so the orchestrator owns it. It runs after the analysis that produced the scope facts, because the orchestrator investigates nothing itself. + +Register these steps before starting and record each step's evidence as it completes: + +| Step | Action | Completion evidence | +|------|--------|---------------------| +| 1 | State the scope facts the analysis produced, then separately what they imply for the requirement | Facts listed with the analysis output they came from | +| 2 | Ask about the fields below `ready`, at most two questions per message | One question per field below `ready` | +| 3 | Record each answer as that field's value | The value uses wording the user supplied, not wording the hearing offered | +| 4 | Re-ask once when a recorded value still fails its pass condition, then mark the field `weak-but-explicit` when the user agrees to leave the second answer as it stands | Two recorded answers, or the user's agreement to stop | +| 5 | Hand the record to the step that judges the fields | An updated record returned from that step | + +Step 3's evidence is what keeps the hearing reviewable: a value restating the hearing's own candidates fails it, so the user's judgment survives however the question was put. + +## Storage Protocol + +| Carrier | Holds | Written by | +|---------|-------|------------| +| The convergence record in the judging step's output | Every field with its readiness label | Whichever step judged them | +| PRD `Success Criteria` and `Future / Out of Scope` | `outcome`; `nonGoals` and `speculative` requirements with origin `user` | The agent that owns the PRD | +| Design Doc `Requirement Convergence` | The same when no PRD exists, and the fields left `weak-but-explicit` in every case | The agent that owns the Design Doc | + +A flow that produces neither document carries the record in its own context to the next step. + +## Reference Protocol (For Downstream Consumers) + +1. Read the convergence record from the prompt. +2. Treat `nonGoals` and `speculative` requirements as excluded from the current change. A `speculative` item becomes buildable only after the user promotes it to `desired-future`. +3. Treat a `weak-but-explicit` field as a recorded open question rather than a settled decision, and escalate when the work depends on resolving it. + +## Quality Checklist + +- [ ] Scope facts were presented before questions were asked +- [ ] `nonGoals` came from the user, or the user stated there are none +- [ ] Every applicable field is `ready`, or `weak-but-explicit` by the user's agreement + +## References + +- [references/criteria.md](references/criteria.md) — judgment rules per field, cost inputs, challenge intensity, solution-in-disguise test diff --git a/skills/requirement-convergence/references/criteria.md b/skills/requirement-convergence/references/criteria.md new file mode 100644 index 0000000..87818ff --- /dev/null +++ b/skills/requirement-convergence/references/criteria.md @@ -0,0 +1,62 @@ +# Convergence Criteria + +Judgment rules for the four convergence fields. Read when eliciting or evaluating them. + +## outcome + +One observable result the change must produce, not a feature list. + +A requirement that cannot be traced to the outcome is excess: drop it, or have the user widen the outcome to cover it. + +## requirements[] — layer separation + +| Layer | Meaning | Buildable now | +|-------|---------|---------------| +| `current-state` | Behavior that already exists | No — these are facts, not work | +| `desired-future` | The change the user is asking for | Yes | +| `speculative` | An idea the user raised without deciding on | No — record with a deferral reason | + +Flattening these three into one requirement list is what makes a bloated plan look coherent, because every item then reads as equally required. Label each item; ask when a label is unclear rather than inferring it. + +## nonGoals[] + +Capabilities deliberately excluded from this change, authored by the user. + +Present the cost band and its unknowns first, then ask what to leave out. `userAgreedNone` records that the user considered exclusions and found none — an agent cannot set it. + +An adjacent capability the agent noticed is a question for the user, not a non-goal. + +## cost + +Cost follows structure and count, not behavior, so it is decided from these inputs alone: + +| Input | How it is obtained | +|-------|--------------------| +| Number and kind of targets to change | Grep/Glob over the affected files | +| Number of boundaries crossed | Affected path composition plus import and caller tracing | +| Whether an equivalent already exists (reuse or new) | Grep for a similar name or shape | +| Whether persisted state needs converting | Whether a schema or migration path is in the change set | +| Whether verification support already exists | Glob for the area's existing test harness | +| What remains unknown | WebSearch for a dependency's current capability; anything the above cannot resolve | + +Reading what the code *does* answers whether the change is correct, not what it costs, and belongs to the codebase analysis that precedes design. + +Record `cost` as one band, the inputs above that place it, and the remaining unknowns. A flow declares `cost` out of scope only where its own steps say so. + +## Challenge intensity + +The band's only job is to select a row here, so cheap requirements stay cheap to accept. + +| Band | Meaning | Challenge | +|------|---------|-----------| +| `low-reversible` | Additive, flagged, or easily deleted | Record the fields and accept the requirement | +| `medium` | Reverting would touch other work | Present the cost and one lower-cost alternative | +| `high-irreversible` | Public contract, persisted data shape, or dependency swap | Present the trade-off and require a user decision before design | + +Report an unknown that would move the band up as a blocking question rather than assuming the lower band. + +## Solution-in-disguise test + +When the requirement names a mechanism rather than an outcome ("add a cache layer", "introduce a queue"), state three materially different ways to reach the same outcome. + +When three exist, the named mechanism is one option among several — present them for a user decision. When the mechanism is genuinely the only route, record that and proceed. diff --git a/skills/subagents-orchestration-guide/SKILL.md b/skills/subagents-orchestration-guide/SKILL.md index 7eaf34a..8393731 100644 --- a/skills/subagents-orchestration-guide/SKILL.md +++ b/skills/subagents-orchestration-guide/SKILL.md @@ -13,6 +13,8 @@ All investigation, analysis, and implementation work flows through specialized s When receiving a new task, pass user requirements directly to requirement-analyzer. Determine the workflow based on its scale assessment result. +requirement-analyzer returns a `convergence` object. Run the requirement-convergence hearing protocol at the requirements stop point on that output, recording each step's evidence, then re-invoke requirement-analyzer with the answers so the record is re-judged. The hearing runs in the orchestrator because it requires user interaction, and runs after the analysis because the orchestrator investigates nothing itself. + ### Requirement Change Detection During Flow **During flow execution**, monitor user responses for scope-expanding signals: @@ -79,7 +81,7 @@ Autonomous execution MUST stop and wait for user input at these points. | Phase | Stop Point | User Action Required | |-------|------------|---------------------| -| Requirements | After requirement-analyzer completes | Confirm requirements / Answer questions | +| Requirements | After requirement-analyzer completes | Answer the requirement-convergence hearing, then confirm requirements | | PRD | After document-reviewer completes PRD review | Approve PRD | | UI Spec | After document-reviewer completes UI Spec review (frontend/fullstack) | Approve UI Spec | | ADR | After document-reviewer completes ADR review (if ADR created) | Approve ADR | @@ -95,6 +97,8 @@ Autonomous execution MUST stop and wait for user input at these points. | Medium | 3-5 | Update※1 | Conditional※2 | **Required** | **Required** | | Large | 6+ | **Required**※3 | Conditional※2 | **Required** | **Required** | +File count sets the floor; documentation-criteria Structural Escalation raises it when any ADR Creation Condition applies. + ※1: Update if PRD exists for the relevant feature ※2: When there are architecture changes, new technology introduction, or data flow changes ※3: New creation/update existing/reverse PRD (when no existing PRD) @@ -136,6 +140,7 @@ Two additional rules: - subagent_type: "requirement-analyzer" - description: "Requirement analysis" - prompt: "Requirements: [user requirements]. Context: [any relevant context]. Perform requirement analysis and scale determination." +- On re-invocation after the convergence hearing, append: "Hearing answers: [the user's answers per convergence field]. Re-judge the convergence record with these answers." ### Call Example (codebase-analyzer) - subagent_type: "codebase-analyzer" @@ -157,7 +162,7 @@ When invoked alongside codebase-analyzer for frontend or fullstack-frontend work ## Structured Response Specification Subagents respond in JSON format. Key fields for orchestrator decisions: -- **requirement-analyzer**: scale, confidence, affectedLayers, adrRequired, scopeDependencies, questions +- **requirement-analyzer**: scale, confidence, affectedLayers, adrRequired, scopeDependencies, questions, convergence (fields with readiness labels; a field below `ready` returns as a `convergence` question) - **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**: `summary.status` (consistent/mostly_consistent/needs_review/inconsistent/blocked), `summary.consistencyScore`, discrepancies[], reverseCoverage (including dataOperationsInCode, testBoundariesSectionPresent). Pre-implementation: verifies Design Doc claims against existing codebase. Post-implementation: verifies implementation consistency against the governing Design Doc or Work Plan (pass `code_paths` scoped to changed files) @@ -192,7 +197,7 @@ Criteria for timing when to call each agent: ## Basic Flow: Planning and Implementation -Always start with requirement-analyzer, then select the minimum planning flow required by scale and affected layers. +Always start with requirement-analyzer, hold the requirement-convergence hearing on its output, then select the minimum planning flow required by scale and affected layers. ### Planning flow (per scale) @@ -202,7 +207,7 @@ Always start with requirement-analyzer, then select the minimum planning flow re | Medium | requirement-analyzer → external resource hearing → codebase-analyzer (+ ui-analyzer in parallel for frontend/fullstack) → optional UI Spec → optional ADR → Design Doc → code-verifier → document-reviewer → design-sync → acceptance-test-generator → work-planner → work plan review (document-reviewer, doc_type WorkPlan) → task-decomposer | | Small | requirement-analyzer → work-planner | -External resource hearing runs in the orchestrator (it requires AskUserQuestion). ui-analyzer joins codebase-analyzer in parallel only when the work has a frontend surface; for backend-only work the planning flow uses codebase-analyzer alone. +The requirement-convergence hearing follows requirement-analyzer in every flow. Both it and the external resource hearing run in the orchestrator (they require AskUserQuestion). ui-analyzer joins codebase-analyzer in parallel only when the work has a frontend surface; for backend-only work the planning flow uses codebase-analyzer alone. After the planning flow completes and the user grants batch approval, implementation proceeds. Verifying the plan is implementable end-to-end (verification lanes, fixtures, E2E environment) is an optional preflight the user runs at their discretion via the recipe-prepare-implementation recipe; this guide does not invoke any orchestrator above the agent layer. @@ -345,7 +350,13 @@ Register overall phases using TaskCreate. Update each phase with TaskUpdate as i ### Handoff Contracts #### HC-01: requirement-analyzer → codebase-analyzer - - Pass: `requirement_analysis`, `prd_path` (if exists), original user requirements + - Pass: `requirement_analysis` (including `convergence`), `prd_path` (if exists), original user requirements + + #### HC-01b: convergence record → document owner + - Pass `convergence` from the last requirement-analyzer invocation (or, in flows without one, the orchestrator's own judged record) to whichever agent owns the persisting document + - **prd-creator** (when a PRD is created or updated): persists `outcome` to `Success Criteria`, and `nonGoals` plus `speculative` requirements to `Future / Out of Scope` with origin `user` + - **technical-designer / technical-designer-frontend**: persists the same to the Design Doc's `Requirement Convergence` when no PRD exists, and always records the fields left `weak-but-explicit` there + - Pass the record unchanged; a field's readiness label travels with it #### HC-02: codebase-analyzer → technical-designer - Pass: full codebase-analyzer JSON as additional context diff --git a/skills/subagents-orchestration-guide/references/monorepo-flow.md b/skills/subagents-orchestration-guide/references/monorepo-flow.md index 74a52d2..ed1889d 100644 --- a/skills/subagents-orchestration-guide/references/monorepo-flow.md +++ b/skills/subagents-orchestration-guide/references/monorepo-flow.md @@ -14,7 +14,7 @@ This reference defines the orchestration flow for projects spanning multiple lay | Step | Agent | Purpose | Output | |------|-------|---------|--------| -| 1 | requirement-analyzer | Requirement analysis + scale determination **[Stop]** | Requirements + scale | +| 1 | requirement-analyzer → (orchestrator) | Requirement analysis + scale determination, then the requirement-convergence hearing on its `convergence` output, re-invoking the analyzer with the answers **[Stop]** | Converged requirements + scale | | 2 | prd-creator | PRD covering entire feature (all layers) | Single PRD | | 3 | document-reviewer | PRD review **[Stop]** | Approval | | 4 | (orchestrator) | External resource hearing per the external-resource-context skill (frontend domain primary; backend / api / infra domains as applicable for the layer scope). File-existence branching as defined in the skill | `docs/project-context/external-resources.md` written or updated | @@ -36,7 +36,7 @@ This reference defines the orchestration flow for projects spanning multiple lay | Step | Agent | Purpose | Output | |------|-------|---------|--------| -| 1 | requirement-analyzer | Requirement analysis + scale determination **[Stop]** | Requirements + scale | +| 1 | requirement-analyzer → (orchestrator) | Requirement analysis + scale determination, then the requirement-convergence hearing on its `convergence` output, re-invoking the analyzer with the answers **[Stop]** | Converged requirements + scale | | 2 | (orchestrator) | External resource hearing per the external-resource-context skill (frontend / backend / api / infra domains as applicable). File-existence branching as defined in the skill | `docs/project-context/external-resources.md` written or updated | | 3 | codebase-analyzer ×2 + ui-analyzer | Codebase analysis per layer + UI fact gathering (parallel; ui-analyzer reads external-resources.md and fetches external UI sources via inherited MCP/URL access) | Codebase guidance per layer + UI fact JSON | | 4 | (orchestrator) | Ask user for prototype code **[Stop]** | Prototype path or none | diff --git a/skills/task-analyzer/references/skills-index.yaml b/skills/task-analyzer/references/skills-index.yaml index 7f2b364..d99869d 100644 --- a/skills/task-analyzer/references/skills-index.yaml +++ b/skills/task-analyzer/references/skills-index.yaml @@ -231,3 +231,19 @@ skills: - "Output Format" - "Quality Checklist" - "References" + + requirement-convergence: + skill: "requirement-convergence" + tags: [cross-cutting, requirements, scope, non-goals, outcome, rough-estimate, trade-off, hearing-protocol, convergence] + typical-use: "Converges what to build before design by separating outcome from requirement layers, recording user-authored non-goals, and banding cost from structure rather than behavior" + size: small + key-references: + - "references/criteria.md" + sections: + - "Purpose" + - "Convergence Fields" + - "Hearing Protocol" + - "Storage Protocol" + - "Reference Protocol (For Downstream Consumers)" + - "Quality Checklist" + - "References"