Converge what to build before design starts

.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"

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)

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`

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.)

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?

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

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

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)

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

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

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"

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
 

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