diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 9103380..cc34e4e 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.29.3", + "version": "0.29.4", "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", @@ -80,7 +80,7 @@ "name": "dev-workflows-frontend", "source": "./dev-workflows-frontend", "strict": true, - "version": "0.29.3", + "version": "0.29.4", "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", @@ -149,7 +149,7 @@ "name": "dev-workflows-fullstack", "source": "./dev-workflows-fullstack", "strict": true, - "version": "0.29.3", + "version": "0.29.4", "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", @@ -235,7 +235,7 @@ "name": "dev-skills", "source": "./dev-skills", "strict": true, - "version": "0.29.3", + "version": "0.29.4", "description": "Lightweight skills for users with existing workflows - coding best practices, testing principles, and design guidelines without recipe workflows or agents", "author": { "name": "Shinsuke Kagawa", diff --git a/agents/prd-creator.md b/agents/prd-creator.md index 0401098..c3cdd48 100644 --- a/agents/prd-creator.md +++ b/agents/prd-creator.md @@ -21,7 +21,7 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow 3. Define success metrics 4. Clarify scope (what's included/excluded) 5. Verify consistency with existing systems -6. **Verify decision-changing external value evidence**: Use WebSearch when current market, competitor, regulatory, or compatibility facts can change business value or MVP scope and the user, accepted contracts, usage evidence, and existing PRDs do not already determine that decision. Record the authoritative source and the decision it affects +6. **Verify decision-changing external value evidence**: Use WebSearch when current market, competitor, or compatibility facts can change business value or MVP scope and the user, accepted contracts, usage evidence, and existing PRDs leave that decision open. Record the authoritative source and the decision it affects ## When PRD is Needed @@ -122,7 +122,6 @@ PRDs focus solely on "what to build." Implementation phases and task decompositi - In reverse-engineer mode, preserve observed measures and distinguish unknown business goals; derive no new target from a template. ### 4. Completeness Check -- Include all stakeholder perspectives - Consider edge cases - Clarify constraints diff --git a/agents/requirement-analyzer.md b/agents/requirement-analyzer.md index e2f325e..cb86bff 100644 --- a/agents/requirement-analyzer.md +++ b/agents/requirement-analyzer.md @@ -28,9 +28,9 @@ Start from the product responsibility the outcome implies, then scan broadly and Inspect a located responsibility further only when leaving it unchanged can affect the outcome, requirement confirmation, relative cost, or the analysis target. Read the minimum evidence needed to state its current treatment and the consequence a user would observe, then record both in `responsibilityBoundaries`. Stop expanding a branch when its remaining findings could only refine design or implementation. -### 2. Form Cost and Question Evidence +### 2. Form Cost Evidence -Summarize relative cost from observed boundaries, reuse, persistence or contract changes, and verification support. Record an unknown or question only when its answer can change the outcome, current requirements, exclusions, Structural Scale, or the analysis target, and the repository cannot resolve it. +Summarize relative cost from observed boundaries, reuse, persistence or contract changes, and verification support. Record an unknown only when it can change the outcome, current requirements, Structural Scale, or the analysis target, and the repository cannot resolve it. Return the evidence for orchestrator judgment. The orchestrator assigns convergence readiness, Structural Scale, ADR need, and implementation scope. @@ -55,11 +55,8 @@ Return exactly one JSON object: "drivers": [ {"kind": "observed|inferred", "fact": "structural cost fact", "source": "request or path"} ], - "unknowns": ["fact that can change relative cost"] - }, - "questions": [ - {"decision": "outcome|requirement|exclusion|scale|analysis_target", "question": "specific unresolved question", "effect": "what changes based on the answer"} - ] + "unknowns": ["fact the repository cannot resolve that can change cost, scope, or scale"] + } } ``` @@ -67,9 +64,8 @@ Return exactly one JSON object: - Scope and cost evidence is shallow, compact, and source-backed. - Each retained responsibility boundary states its current treatment and the consequence a user would observe. -- Every user-facing or operational responsibility a cost driver or question relies on has a source-backed boundary entry, or is recorded as an unknown. +- Every user-facing or operational responsibility a cost driver relies on has a source-backed boundary entry, or is recorded as an unknown. - `executionRoute.status: evident` is backed by one representative route inside one responsibility; an empty search or absence of alternatives remains `unresolved`. -- Every question names the decision its answer can change. - Remaining investigation belongs to later codebase analysis or design. - Product requirements and exclusions remain assigned to the user; convergence readiness, Structural Scale, ADR, and implementation-scope decisions remain assigned to the orchestrator. - The response is one valid JSON object. diff --git a/dev-skills/.claude-plugin/plugin.json b/dev-skills/.claude-plugin/plugin.json index a14d0cb..8c200bc 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.29.3", + "version": "0.29.4", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-skills/skills/documentation-criteria/SKILL.md b/dev-skills/skills/documentation-criteria/SKILL.md index 1e6f67a..2565155 100644 --- a/dev-skills/skills/documentation-criteria/SKILL.md +++ b/dev-skills/skills/documentation-criteria/SKILL.md @@ -11,7 +11,7 @@ This file holds the routing decision: which documents a change requires and wher Each document fixes one class of decision that the repository alone cannot supply. An unfilled section becomes a guess made later by the consumer named below, with no record of what was assumed. -- **PRD** — Fixes the business outcome and the acceptance criteria later work traces to. Its AC IDs are the traceability keys that the Design Doc, UI Spec, and test selection reuse; without them each consumer re-derives requirements from prose and the link between a test and the value it protects is lost. Implementation details belong to the Design Doc, selection rationale to an ADR, phases and task breakdown to the Work Plan. +- **PRD** — Fixes the business outcome and the acceptance criteria later work traces to. Its AC IDs are the traceability keys that the Design Doc, UI Spec, and test selection reuse; without them each consumer re-derives requirements from prose and the link between a test and the value it protects is lost. Implementation details belong to the Design Doc, selection rationale to an ADR, phases and task breakdown to the Work Plan. Later design, review, and test selection treat its content as governing, so a precondition held outside the repository change, such as release execution or organizational approval, appears in it only when the user's wording raises it. - **ADR** — Records one durable technical choice and the options it beat, so later work can tell a deliberate decision from an accident. Without it a future change either re-runs the same comparison or silently reverses it. `Accepted` records the currently selected means, not an obligation to retain it: when later evidence supports a smaller sufficient choice, update or supersede the decision while the confirmed outcome, desired-future requirements, and non-goals remain true. End-to-end implementation design belongs to the Design Doc, schedule and repository tasks to the Work Plan. diff --git a/dev-skills/skills/documentation-criteria/references/prd-template.md b/dev-skills/skills/documentation-criteria/references/prd-template.md index 8d814d7..d0fea27 100644 --- a/dev-skills/skills/documentation-criteria/references/prd-template.md +++ b/dev-skills/skills/documentation-criteria/references/prd-template.md @@ -124,7 +124,7 @@ State observable success for the confirmed outcome. Include only sourced quantit - [Prerequisite requiring validation 2] ### Risks and Mitigation -Include only evidenced product or delivery risks that can change scope, success criteria, sequencing, or acceptance. +Include only evidenced product risks that can change scope, success criteria, or acceptance. | Risk | Impact | Probability | Mitigation | |------|--------|-------------|------------| diff --git a/dev-skills/skills/requirement-convergence/SKILL.md b/dev-skills/skills/requirement-convergence/SKILL.md index defb3cf..bd20961 100644 --- a/dev-skills/skills/requirement-convergence/SKILL.md +++ b/dev-skills/skills/requirement-convergence/SKILL.md @@ -51,7 +51,7 @@ Render this shape at every requirements confirmation stop, whether or not the he |---------|----------| | **Confirmed scope** | The requirements and exclusions the user has already selected, in the user's wording | | **Decision evidence** | Each material observed fact with its source, followed by what that fact can change about scope, outcome, or cost | -| **User decisions** | Each unresolved product, UX, or operational question, followed by the scope, outcome, or cost effects of its materially different answers | +| **User decisions** | One question per convergence field below `ready` (Hearing Protocol Step 1), followed by the scope, outcome, or cost effects of its materially different answers | | **Workflow** | Rough cost band with the unknowns that remain, Structural Scale, and the selected document and workflow route | Keeping the first three sections separate is what makes the decision informable: merged, the reader cannot tell which line is the user's own settled boundary, which is a repository observation, and which is still open. diff --git a/dev-skills/skills/requirement-convergence/references/criteria.md b/dev-skills/skills/requirement-convergence/references/criteria.md index 3e8d072..625980f 100644 --- a/dev-skills/skills/requirement-convergence/references/criteria.md +++ b/dev-skills/skills/requirement-convergence/references/criteria.md @@ -19,6 +19,8 @@ Evaluation requests, speculative ideas, and prescribed mechanisms stay in active Flattening current state, desired future, and candidates into one requirement list makes a bloated plan look coherent because every item then reads as equally required. Label each build-relevant item; ask when its current-state or desired-future role is unclear rather than inferring it. +An item is build-relevant when the repository change can satisfy it. A precondition held outside that change, such as legal or policy review, contract execution, release execution, or organizational approval, enters `requirements[]` and the hearing only when the user's wording raises it. + ## nonGoals[] Capabilities deliberately excluded from this change, authored by the user. diff --git a/dev-workflows-frontend/.claude-plugin/plugin.json b/dev-workflows-frontend/.claude-plugin/plugin.json index 9c92a73..3d20fd3 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.29.3", + "version": "0.29.4", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows-frontend/agents/prd-creator.md b/dev-workflows-frontend/agents/prd-creator.md index 0401098..c3cdd48 100644 --- a/dev-workflows-frontend/agents/prd-creator.md +++ b/dev-workflows-frontend/agents/prd-creator.md @@ -21,7 +21,7 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow 3. Define success metrics 4. Clarify scope (what's included/excluded) 5. Verify consistency with existing systems -6. **Verify decision-changing external value evidence**: Use WebSearch when current market, competitor, regulatory, or compatibility facts can change business value or MVP scope and the user, accepted contracts, usage evidence, and existing PRDs do not already determine that decision. Record the authoritative source and the decision it affects +6. **Verify decision-changing external value evidence**: Use WebSearch when current market, competitor, or compatibility facts can change business value or MVP scope and the user, accepted contracts, usage evidence, and existing PRDs leave that decision open. Record the authoritative source and the decision it affects ## When PRD is Needed @@ -122,7 +122,6 @@ PRDs focus solely on "what to build." Implementation phases and task decompositi - In reverse-engineer mode, preserve observed measures and distinguish unknown business goals; derive no new target from a template. ### 4. Completeness Check -- Include all stakeholder perspectives - Consider edge cases - Clarify constraints diff --git a/dev-workflows-frontend/agents/requirement-analyzer.md b/dev-workflows-frontend/agents/requirement-analyzer.md index e2f325e..cb86bff 100644 --- a/dev-workflows-frontend/agents/requirement-analyzer.md +++ b/dev-workflows-frontend/agents/requirement-analyzer.md @@ -28,9 +28,9 @@ Start from the product responsibility the outcome implies, then scan broadly and Inspect a located responsibility further only when leaving it unchanged can affect the outcome, requirement confirmation, relative cost, or the analysis target. Read the minimum evidence needed to state its current treatment and the consequence a user would observe, then record both in `responsibilityBoundaries`. Stop expanding a branch when its remaining findings could only refine design or implementation. -### 2. Form Cost and Question Evidence +### 2. Form Cost Evidence -Summarize relative cost from observed boundaries, reuse, persistence or contract changes, and verification support. Record an unknown or question only when its answer can change the outcome, current requirements, exclusions, Structural Scale, or the analysis target, and the repository cannot resolve it. +Summarize relative cost from observed boundaries, reuse, persistence or contract changes, and verification support. Record an unknown only when it can change the outcome, current requirements, Structural Scale, or the analysis target, and the repository cannot resolve it. Return the evidence for orchestrator judgment. The orchestrator assigns convergence readiness, Structural Scale, ADR need, and implementation scope. @@ -55,11 +55,8 @@ Return exactly one JSON object: "drivers": [ {"kind": "observed|inferred", "fact": "structural cost fact", "source": "request or path"} ], - "unknowns": ["fact that can change relative cost"] - }, - "questions": [ - {"decision": "outcome|requirement|exclusion|scale|analysis_target", "question": "specific unresolved question", "effect": "what changes based on the answer"} - ] + "unknowns": ["fact the repository cannot resolve that can change cost, scope, or scale"] + } } ``` @@ -67,9 +64,8 @@ Return exactly one JSON object: - Scope and cost evidence is shallow, compact, and source-backed. - Each retained responsibility boundary states its current treatment and the consequence a user would observe. -- Every user-facing or operational responsibility a cost driver or question relies on has a source-backed boundary entry, or is recorded as an unknown. +- Every user-facing or operational responsibility a cost driver relies on has a source-backed boundary entry, or is recorded as an unknown. - `executionRoute.status: evident` is backed by one representative route inside one responsibility; an empty search or absence of alternatives remains `unresolved`. -- Every question names the decision its answer can change. - Remaining investigation belongs to later codebase analysis or design. - Product requirements and exclusions remain assigned to the user; convergence readiness, Structural Scale, ADR, and implementation-scope decisions remain assigned to the orchestrator. - The response is one valid JSON object. diff --git a/dev-workflows-frontend/skills/documentation-criteria/SKILL.md b/dev-workflows-frontend/skills/documentation-criteria/SKILL.md index 1e6f67a..2565155 100644 --- a/dev-workflows-frontend/skills/documentation-criteria/SKILL.md +++ b/dev-workflows-frontend/skills/documentation-criteria/SKILL.md @@ -11,7 +11,7 @@ This file holds the routing decision: which documents a change requires and wher Each document fixes one class of decision that the repository alone cannot supply. An unfilled section becomes a guess made later by the consumer named below, with no record of what was assumed. -- **PRD** — Fixes the business outcome and the acceptance criteria later work traces to. Its AC IDs are the traceability keys that the Design Doc, UI Spec, and test selection reuse; without them each consumer re-derives requirements from prose and the link between a test and the value it protects is lost. Implementation details belong to the Design Doc, selection rationale to an ADR, phases and task breakdown to the Work Plan. +- **PRD** — Fixes the business outcome and the acceptance criteria later work traces to. Its AC IDs are the traceability keys that the Design Doc, UI Spec, and test selection reuse; without them each consumer re-derives requirements from prose and the link between a test and the value it protects is lost. Implementation details belong to the Design Doc, selection rationale to an ADR, phases and task breakdown to the Work Plan. Later design, review, and test selection treat its content as governing, so a precondition held outside the repository change, such as release execution or organizational approval, appears in it only when the user's wording raises it. - **ADR** — Records one durable technical choice and the options it beat, so later work can tell a deliberate decision from an accident. Without it a future change either re-runs the same comparison or silently reverses it. `Accepted` records the currently selected means, not an obligation to retain it: when later evidence supports a smaller sufficient choice, update or supersede the decision while the confirmed outcome, desired-future requirements, and non-goals remain true. End-to-end implementation design belongs to the Design Doc, schedule and repository tasks to the Work Plan. 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 8d814d7..d0fea27 100644 --- a/dev-workflows-frontend/skills/documentation-criteria/references/prd-template.md +++ b/dev-workflows-frontend/skills/documentation-criteria/references/prd-template.md @@ -124,7 +124,7 @@ State observable success for the confirmed outcome. Include only sourced quantit - [Prerequisite requiring validation 2] ### Risks and Mitigation -Include only evidenced product or delivery risks that can change scope, success criteria, sequencing, or acceptance. +Include only evidenced product risks that can change scope, success criteria, or acceptance. | Risk | Impact | Probability | Mitigation | |------|--------|-------------|------------| diff --git a/dev-workflows-frontend/skills/requirement-convergence/SKILL.md b/dev-workflows-frontend/skills/requirement-convergence/SKILL.md index defb3cf..bd20961 100644 --- a/dev-workflows-frontend/skills/requirement-convergence/SKILL.md +++ b/dev-workflows-frontend/skills/requirement-convergence/SKILL.md @@ -51,7 +51,7 @@ Render this shape at every requirements confirmation stop, whether or not the he |---------|----------| | **Confirmed scope** | The requirements and exclusions the user has already selected, in the user's wording | | **Decision evidence** | Each material observed fact with its source, followed by what that fact can change about scope, outcome, or cost | -| **User decisions** | Each unresolved product, UX, or operational question, followed by the scope, outcome, or cost effects of its materially different answers | +| **User decisions** | One question per convergence field below `ready` (Hearing Protocol Step 1), followed by the scope, outcome, or cost effects of its materially different answers | | **Workflow** | Rough cost band with the unknowns that remain, Structural Scale, and the selected document and workflow route | Keeping the first three sections separate is what makes the decision informable: merged, the reader cannot tell which line is the user's own settled boundary, which is a repository observation, and which is still open. diff --git a/dev-workflows-frontend/skills/requirement-convergence/references/criteria.md b/dev-workflows-frontend/skills/requirement-convergence/references/criteria.md index 3e8d072..625980f 100644 --- a/dev-workflows-frontend/skills/requirement-convergence/references/criteria.md +++ b/dev-workflows-frontend/skills/requirement-convergence/references/criteria.md @@ -19,6 +19,8 @@ Evaluation requests, speculative ideas, and prescribed mechanisms stay in active Flattening current state, desired future, and candidates into one requirement list makes a bloated plan look coherent because every item then reads as equally required. Label each build-relevant item; ask when its current-state or desired-future role is unclear rather than inferring it. +An item is build-relevant when the repository change can satisfy it. A precondition held outside that change, such as legal or policy review, contract execution, release execution, or organizational approval, enters `requirements[]` and the hearing only when the user's wording raises it. + ## nonGoals[] Capabilities deliberately excluded from this change, authored by the user. diff --git a/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md index 77c4b77..39b8972 100644 --- a/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md @@ -19,7 +19,7 @@ This section governs the orchestrator's Agent prompt. Each specialist's agent de ### First Action Rule -When receiving a new full-cycle task, retain the user's complete wording in the orchestrator and invoke requirement-analyzer with the Requirement Evidence Handoff below. Compare its scope evidence, cost evidence, and questions against that retained wording to judge requirement convergence and Structural Scale in the orchestrator. Dedicated design recipes use their own codebase-scoped bootstrap. +When receiving a new full-cycle task, retain the user's complete wording in the orchestrator and invoke requirement-analyzer with the Requirement Evidence Handoff below. Compare its scope evidence and cost evidence against that retained wording to judge requirement convergence and Structural Scale in the orchestrator. Dedicated design recipes use their own codebase-scoped bootstrap. **Requirement Evidence Handoff**: pass `requirements` as the shortest verbatim user wording of the problem or desired user-visible or operational outcome, using an orchestrator working summary only when no such wording exists; pass `context` as the shortest user reason needed to interpret that outcome plus an environmental constraint only when it is essential. Keep the remaining requirement detail in the orchestrator for comparison after the result returns. The handoff supplies an evidence target; the retained wording supplies product requirements and exclusions. Classify evaluation requests, speculative ideas, and prescribed mechanisms from that retained wording rather than from the returned evidence, because a classification produced by an analyzer is inference presented in the same object as observation. @@ -27,7 +27,7 @@ Build and judge the `convergence` record in the orchestrator with the requiremen ### Small Evidence Gate -Classify Small when `scopeEvidence.executionRoute.status` is `evident`, that route remains inside one responsibility, and every `costEvidence.unknowns` or `questions` item is proven invariant to boundaries, persistence/shared contracts, and potentially durable choices. Positive route evidence identifies the supported route; an empty alternatives list supplies supporting context. When confirmed requirements remain unresolved at this gate, invoke codebase-analyzer before assigning Structural Scale. Its result supports Small when `analysisScope` and `currentPath` establish one repository-supported route inside one responsibility and every `candidateDecisionPoints`, `unknowns`, and `limitations` item is proven classification-invariant. Other observed boundaries and outcomes route Medium or Large. Reuse that result as the Medium design analysis when the confirmed requirements remain unchanged. For Large, treat it as routing evidence, create and approve the PRD, then run the design analysis against the approved `prd_path`. ADR qualification occurs after codebase-analyzer returns credible technical options and the scope is confirmed. +Classify Small when `scopeEvidence.executionRoute.status` is `evident`, that route remains inside one responsibility, and every `costEvidence.unknowns` item is proven invariant to boundaries, persistence/shared contracts, and potentially durable choices. Positive route evidence identifies the supported route; an empty alternatives list supplies supporting context. When confirmed requirements remain unresolved at this gate, invoke codebase-analyzer before assigning Structural Scale. Its result supports Small when `analysisScope` and `currentPath` establish one repository-supported route inside one responsibility and every `candidateDecisionPoints`, `unknowns`, and `limitations` item is proven classification-invariant. Other observed boundaries and outcomes route Medium or Large. Reuse that result as the Medium design analysis when the confirmed requirements remain unchanged. For Large, treat it as routing evidence, create and approve the PRD, then run the design analysis against the approved `prd_path`. ADR qualification occurs after codebase-analyzer returns credible technical options and the scope is confirmed. ### Requirement Change Detection During Flow @@ -260,7 +260,7 @@ Before post-implementation verifiers, collect retained verification limitations ## Handoff Contracts ### HC-01: requirement-analyzer → orchestrator and codebase-analyzer -- Invoke with the Requirement Evidence Handoff. The orchestrator compares the returned `scopeEvidence`, `costEvidence`, and `questions` against its retained user wording to judge convergence and Structural Scale. Small requires the positive `scopeEvidence.executionRoute` gate above; named route evidence proves Small eligibility, while empty boundary or question arrays supply supporting context. +- Invoke with the Requirement Evidence Handoff. The orchestrator compares the returned `scopeEvidence` and `costEvidence` against its retained user wording to judge convergence and Structural Scale. Small requires the positive `scopeEvidence.executionRoute` gate above; named route evidence proves Small eligibility, while empty boundary or unknown arrays supply supporting context. - Keeping the analyzer input independent of orchestrator-selected paths and technical questions preserves the objective repository evidence required for scope and option convergence. ### HC-01b: convergence record → document owner diff --git a/dev-workflows-fullstack/.claude-plugin/plugin.json b/dev-workflows-fullstack/.claude-plugin/plugin.json index 2b74dd7..fae6618 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.29.3", + "version": "0.29.4", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows-fullstack/agents/prd-creator.md b/dev-workflows-fullstack/agents/prd-creator.md index 0401098..c3cdd48 100644 --- a/dev-workflows-fullstack/agents/prd-creator.md +++ b/dev-workflows-fullstack/agents/prd-creator.md @@ -21,7 +21,7 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow 3. Define success metrics 4. Clarify scope (what's included/excluded) 5. Verify consistency with existing systems -6. **Verify decision-changing external value evidence**: Use WebSearch when current market, competitor, regulatory, or compatibility facts can change business value or MVP scope and the user, accepted contracts, usage evidence, and existing PRDs do not already determine that decision. Record the authoritative source and the decision it affects +6. **Verify decision-changing external value evidence**: Use WebSearch when current market, competitor, or compatibility facts can change business value or MVP scope and the user, accepted contracts, usage evidence, and existing PRDs leave that decision open. Record the authoritative source and the decision it affects ## When PRD is Needed @@ -122,7 +122,6 @@ PRDs focus solely on "what to build." Implementation phases and task decompositi - In reverse-engineer mode, preserve observed measures and distinguish unknown business goals; derive no new target from a template. ### 4. Completeness Check -- Include all stakeholder perspectives - Consider edge cases - Clarify constraints diff --git a/dev-workflows-fullstack/agents/requirement-analyzer.md b/dev-workflows-fullstack/agents/requirement-analyzer.md index e2f325e..cb86bff 100644 --- a/dev-workflows-fullstack/agents/requirement-analyzer.md +++ b/dev-workflows-fullstack/agents/requirement-analyzer.md @@ -28,9 +28,9 @@ Start from the product responsibility the outcome implies, then scan broadly and Inspect a located responsibility further only when leaving it unchanged can affect the outcome, requirement confirmation, relative cost, or the analysis target. Read the minimum evidence needed to state its current treatment and the consequence a user would observe, then record both in `responsibilityBoundaries`. Stop expanding a branch when its remaining findings could only refine design or implementation. -### 2. Form Cost and Question Evidence +### 2. Form Cost Evidence -Summarize relative cost from observed boundaries, reuse, persistence or contract changes, and verification support. Record an unknown or question only when its answer can change the outcome, current requirements, exclusions, Structural Scale, or the analysis target, and the repository cannot resolve it. +Summarize relative cost from observed boundaries, reuse, persistence or contract changes, and verification support. Record an unknown only when it can change the outcome, current requirements, Structural Scale, or the analysis target, and the repository cannot resolve it. Return the evidence for orchestrator judgment. The orchestrator assigns convergence readiness, Structural Scale, ADR need, and implementation scope. @@ -55,11 +55,8 @@ Return exactly one JSON object: "drivers": [ {"kind": "observed|inferred", "fact": "structural cost fact", "source": "request or path"} ], - "unknowns": ["fact that can change relative cost"] - }, - "questions": [ - {"decision": "outcome|requirement|exclusion|scale|analysis_target", "question": "specific unresolved question", "effect": "what changes based on the answer"} - ] + "unknowns": ["fact the repository cannot resolve that can change cost, scope, or scale"] + } } ``` @@ -67,9 +64,8 @@ Return exactly one JSON object: - Scope and cost evidence is shallow, compact, and source-backed. - Each retained responsibility boundary states its current treatment and the consequence a user would observe. -- Every user-facing or operational responsibility a cost driver or question relies on has a source-backed boundary entry, or is recorded as an unknown. +- Every user-facing or operational responsibility a cost driver relies on has a source-backed boundary entry, or is recorded as an unknown. - `executionRoute.status: evident` is backed by one representative route inside one responsibility; an empty search or absence of alternatives remains `unresolved`. -- Every question names the decision its answer can change. - Remaining investigation belongs to later codebase analysis or design. - Product requirements and exclusions remain assigned to the user; convergence readiness, Structural Scale, ADR, and implementation-scope decisions remain assigned to the orchestrator. - The response is one valid JSON object. diff --git a/dev-workflows-fullstack/skills/documentation-criteria/SKILL.md b/dev-workflows-fullstack/skills/documentation-criteria/SKILL.md index 1e6f67a..2565155 100644 --- a/dev-workflows-fullstack/skills/documentation-criteria/SKILL.md +++ b/dev-workflows-fullstack/skills/documentation-criteria/SKILL.md @@ -11,7 +11,7 @@ This file holds the routing decision: which documents a change requires and wher Each document fixes one class of decision that the repository alone cannot supply. An unfilled section becomes a guess made later by the consumer named below, with no record of what was assumed. -- **PRD** — Fixes the business outcome and the acceptance criteria later work traces to. Its AC IDs are the traceability keys that the Design Doc, UI Spec, and test selection reuse; without them each consumer re-derives requirements from prose and the link between a test and the value it protects is lost. Implementation details belong to the Design Doc, selection rationale to an ADR, phases and task breakdown to the Work Plan. +- **PRD** — Fixes the business outcome and the acceptance criteria later work traces to. Its AC IDs are the traceability keys that the Design Doc, UI Spec, and test selection reuse; without them each consumer re-derives requirements from prose and the link between a test and the value it protects is lost. Implementation details belong to the Design Doc, selection rationale to an ADR, phases and task breakdown to the Work Plan. Later design, review, and test selection treat its content as governing, so a precondition held outside the repository change, such as release execution or organizational approval, appears in it only when the user's wording raises it. - **ADR** — Records one durable technical choice and the options it beat, so later work can tell a deliberate decision from an accident. Without it a future change either re-runs the same comparison or silently reverses it. `Accepted` records the currently selected means, not an obligation to retain it: when later evidence supports a smaller sufficient choice, update or supersede the decision while the confirmed outcome, desired-future requirements, and non-goals remain true. End-to-end implementation design belongs to the Design Doc, schedule and repository tasks to the Work Plan. 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 8d814d7..d0fea27 100644 --- a/dev-workflows-fullstack/skills/documentation-criteria/references/prd-template.md +++ b/dev-workflows-fullstack/skills/documentation-criteria/references/prd-template.md @@ -124,7 +124,7 @@ State observable success for the confirmed outcome. Include only sourced quantit - [Prerequisite requiring validation 2] ### Risks and Mitigation -Include only evidenced product or delivery risks that can change scope, success criteria, sequencing, or acceptance. +Include only evidenced product risks that can change scope, success criteria, or acceptance. | Risk | Impact | Probability | Mitigation | |------|--------|-------------|------------| diff --git a/dev-workflows-fullstack/skills/requirement-convergence/SKILL.md b/dev-workflows-fullstack/skills/requirement-convergence/SKILL.md index defb3cf..bd20961 100644 --- a/dev-workflows-fullstack/skills/requirement-convergence/SKILL.md +++ b/dev-workflows-fullstack/skills/requirement-convergence/SKILL.md @@ -51,7 +51,7 @@ Render this shape at every requirements confirmation stop, whether or not the he |---------|----------| | **Confirmed scope** | The requirements and exclusions the user has already selected, in the user's wording | | **Decision evidence** | Each material observed fact with its source, followed by what that fact can change about scope, outcome, or cost | -| **User decisions** | Each unresolved product, UX, or operational question, followed by the scope, outcome, or cost effects of its materially different answers | +| **User decisions** | One question per convergence field below `ready` (Hearing Protocol Step 1), followed by the scope, outcome, or cost effects of its materially different answers | | **Workflow** | Rough cost band with the unknowns that remain, Structural Scale, and the selected document and workflow route | Keeping the first three sections separate is what makes the decision informable: merged, the reader cannot tell which line is the user's own settled boundary, which is a repository observation, and which is still open. diff --git a/dev-workflows-fullstack/skills/requirement-convergence/references/criteria.md b/dev-workflows-fullstack/skills/requirement-convergence/references/criteria.md index 3e8d072..625980f 100644 --- a/dev-workflows-fullstack/skills/requirement-convergence/references/criteria.md +++ b/dev-workflows-fullstack/skills/requirement-convergence/references/criteria.md @@ -19,6 +19,8 @@ Evaluation requests, speculative ideas, and prescribed mechanisms stay in active Flattening current state, desired future, and candidates into one requirement list makes a bloated plan look coherent because every item then reads as equally required. Label each build-relevant item; ask when its current-state or desired-future role is unclear rather than inferring it. +An item is build-relevant when the repository change can satisfy it. A precondition held outside that change, such as legal or policy review, contract execution, release execution, or organizational approval, enters `requirements[]` and the hearing only when the user's wording raises it. + ## nonGoals[] Capabilities deliberately excluded from this change, authored by the user. diff --git a/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md index 77c4b77..39b8972 100644 --- a/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md @@ -19,7 +19,7 @@ This section governs the orchestrator's Agent prompt. Each specialist's agent de ### First Action Rule -When receiving a new full-cycle task, retain the user's complete wording in the orchestrator and invoke requirement-analyzer with the Requirement Evidence Handoff below. Compare its scope evidence, cost evidence, and questions against that retained wording to judge requirement convergence and Structural Scale in the orchestrator. Dedicated design recipes use their own codebase-scoped bootstrap. +When receiving a new full-cycle task, retain the user's complete wording in the orchestrator and invoke requirement-analyzer with the Requirement Evidence Handoff below. Compare its scope evidence and cost evidence against that retained wording to judge requirement convergence and Structural Scale in the orchestrator. Dedicated design recipes use their own codebase-scoped bootstrap. **Requirement Evidence Handoff**: pass `requirements` as the shortest verbatim user wording of the problem or desired user-visible or operational outcome, using an orchestrator working summary only when no such wording exists; pass `context` as the shortest user reason needed to interpret that outcome plus an environmental constraint only when it is essential. Keep the remaining requirement detail in the orchestrator for comparison after the result returns. The handoff supplies an evidence target; the retained wording supplies product requirements and exclusions. Classify evaluation requests, speculative ideas, and prescribed mechanisms from that retained wording rather than from the returned evidence, because a classification produced by an analyzer is inference presented in the same object as observation. @@ -27,7 +27,7 @@ Build and judge the `convergence` record in the orchestrator with the requiremen ### Small Evidence Gate -Classify Small when `scopeEvidence.executionRoute.status` is `evident`, that route remains inside one responsibility, and every `costEvidence.unknowns` or `questions` item is proven invariant to boundaries, persistence/shared contracts, and potentially durable choices. Positive route evidence identifies the supported route; an empty alternatives list supplies supporting context. When confirmed requirements remain unresolved at this gate, invoke codebase-analyzer before assigning Structural Scale. Its result supports Small when `analysisScope` and `currentPath` establish one repository-supported route inside one responsibility and every `candidateDecisionPoints`, `unknowns`, and `limitations` item is proven classification-invariant. Other observed boundaries and outcomes route Medium or Large. Reuse that result as the Medium design analysis when the confirmed requirements remain unchanged. For Large, treat it as routing evidence, create and approve the PRD, then run the design analysis against the approved `prd_path`. ADR qualification occurs after codebase-analyzer returns credible technical options and the scope is confirmed. +Classify Small when `scopeEvidence.executionRoute.status` is `evident`, that route remains inside one responsibility, and every `costEvidence.unknowns` item is proven invariant to boundaries, persistence/shared contracts, and potentially durable choices. Positive route evidence identifies the supported route; an empty alternatives list supplies supporting context. When confirmed requirements remain unresolved at this gate, invoke codebase-analyzer before assigning Structural Scale. Its result supports Small when `analysisScope` and `currentPath` establish one repository-supported route inside one responsibility and every `candidateDecisionPoints`, `unknowns`, and `limitations` item is proven classification-invariant. Other observed boundaries and outcomes route Medium or Large. Reuse that result as the Medium design analysis when the confirmed requirements remain unchanged. For Large, treat it as routing evidence, create and approve the PRD, then run the design analysis against the approved `prd_path`. ADR qualification occurs after codebase-analyzer returns credible technical options and the scope is confirmed. ### Requirement Change Detection During Flow @@ -260,7 +260,7 @@ Before post-implementation verifiers, collect retained verification limitations ## Handoff Contracts ### HC-01: requirement-analyzer → orchestrator and codebase-analyzer -- Invoke with the Requirement Evidence Handoff. The orchestrator compares the returned `scopeEvidence`, `costEvidence`, and `questions` against its retained user wording to judge convergence and Structural Scale. Small requires the positive `scopeEvidence.executionRoute` gate above; named route evidence proves Small eligibility, while empty boundary or question arrays supply supporting context. +- Invoke with the Requirement Evidence Handoff. The orchestrator compares the returned `scopeEvidence` and `costEvidence` against its retained user wording to judge convergence and Structural Scale. Small requires the positive `scopeEvidence.executionRoute` gate above; named route evidence proves Small eligibility, while empty boundary or unknown arrays supply supporting context. - Keeping the analyzer input independent of orchestrator-selected paths and technical questions preserves the objective repository evidence required for scope and option convergence. ### HC-01b: convergence record → document owner diff --git a/dev-workflows/.claude-plugin/plugin.json b/dev-workflows/.claude-plugin/plugin.json index c6de3cd..d97f4d9 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.29.3", + "version": "0.29.4", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows/agents/prd-creator.md b/dev-workflows/agents/prd-creator.md index 0401098..c3cdd48 100644 --- a/dev-workflows/agents/prd-creator.md +++ b/dev-workflows/agents/prd-creator.md @@ -21,7 +21,7 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow 3. Define success metrics 4. Clarify scope (what's included/excluded) 5. Verify consistency with existing systems -6. **Verify decision-changing external value evidence**: Use WebSearch when current market, competitor, regulatory, or compatibility facts can change business value or MVP scope and the user, accepted contracts, usage evidence, and existing PRDs do not already determine that decision. Record the authoritative source and the decision it affects +6. **Verify decision-changing external value evidence**: Use WebSearch when current market, competitor, or compatibility facts can change business value or MVP scope and the user, accepted contracts, usage evidence, and existing PRDs leave that decision open. Record the authoritative source and the decision it affects ## When PRD is Needed @@ -122,7 +122,6 @@ PRDs focus solely on "what to build." Implementation phases and task decompositi - In reverse-engineer mode, preserve observed measures and distinguish unknown business goals; derive no new target from a template. ### 4. Completeness Check -- Include all stakeholder perspectives - Consider edge cases - Clarify constraints diff --git a/dev-workflows/agents/requirement-analyzer.md b/dev-workflows/agents/requirement-analyzer.md index e2f325e..cb86bff 100644 --- a/dev-workflows/agents/requirement-analyzer.md +++ b/dev-workflows/agents/requirement-analyzer.md @@ -28,9 +28,9 @@ Start from the product responsibility the outcome implies, then scan broadly and Inspect a located responsibility further only when leaving it unchanged can affect the outcome, requirement confirmation, relative cost, or the analysis target. Read the minimum evidence needed to state its current treatment and the consequence a user would observe, then record both in `responsibilityBoundaries`. Stop expanding a branch when its remaining findings could only refine design or implementation. -### 2. Form Cost and Question Evidence +### 2. Form Cost Evidence -Summarize relative cost from observed boundaries, reuse, persistence or contract changes, and verification support. Record an unknown or question only when its answer can change the outcome, current requirements, exclusions, Structural Scale, or the analysis target, and the repository cannot resolve it. +Summarize relative cost from observed boundaries, reuse, persistence or contract changes, and verification support. Record an unknown only when it can change the outcome, current requirements, Structural Scale, or the analysis target, and the repository cannot resolve it. Return the evidence for orchestrator judgment. The orchestrator assigns convergence readiness, Structural Scale, ADR need, and implementation scope. @@ -55,11 +55,8 @@ Return exactly one JSON object: "drivers": [ {"kind": "observed|inferred", "fact": "structural cost fact", "source": "request or path"} ], - "unknowns": ["fact that can change relative cost"] - }, - "questions": [ - {"decision": "outcome|requirement|exclusion|scale|analysis_target", "question": "specific unresolved question", "effect": "what changes based on the answer"} - ] + "unknowns": ["fact the repository cannot resolve that can change cost, scope, or scale"] + } } ``` @@ -67,9 +64,8 @@ Return exactly one JSON object: - Scope and cost evidence is shallow, compact, and source-backed. - Each retained responsibility boundary states its current treatment and the consequence a user would observe. -- Every user-facing or operational responsibility a cost driver or question relies on has a source-backed boundary entry, or is recorded as an unknown. +- Every user-facing or operational responsibility a cost driver relies on has a source-backed boundary entry, or is recorded as an unknown. - `executionRoute.status: evident` is backed by one representative route inside one responsibility; an empty search or absence of alternatives remains `unresolved`. -- Every question names the decision its answer can change. - Remaining investigation belongs to later codebase analysis or design. - Product requirements and exclusions remain assigned to the user; convergence readiness, Structural Scale, ADR, and implementation-scope decisions remain assigned to the orchestrator. - The response is one valid JSON object. diff --git a/dev-workflows/skills/documentation-criteria/SKILL.md b/dev-workflows/skills/documentation-criteria/SKILL.md index 1e6f67a..2565155 100644 --- a/dev-workflows/skills/documentation-criteria/SKILL.md +++ b/dev-workflows/skills/documentation-criteria/SKILL.md @@ -11,7 +11,7 @@ This file holds the routing decision: which documents a change requires and wher Each document fixes one class of decision that the repository alone cannot supply. An unfilled section becomes a guess made later by the consumer named below, with no record of what was assumed. -- **PRD** — Fixes the business outcome and the acceptance criteria later work traces to. Its AC IDs are the traceability keys that the Design Doc, UI Spec, and test selection reuse; without them each consumer re-derives requirements from prose and the link between a test and the value it protects is lost. Implementation details belong to the Design Doc, selection rationale to an ADR, phases and task breakdown to the Work Plan. +- **PRD** — Fixes the business outcome and the acceptance criteria later work traces to. Its AC IDs are the traceability keys that the Design Doc, UI Spec, and test selection reuse; without them each consumer re-derives requirements from prose and the link between a test and the value it protects is lost. Implementation details belong to the Design Doc, selection rationale to an ADR, phases and task breakdown to the Work Plan. Later design, review, and test selection treat its content as governing, so a precondition held outside the repository change, such as release execution or organizational approval, appears in it only when the user's wording raises it. - **ADR** — Records one durable technical choice and the options it beat, so later work can tell a deliberate decision from an accident. Without it a future change either re-runs the same comparison or silently reverses it. `Accepted` records the currently selected means, not an obligation to retain it: when later evidence supports a smaller sufficient choice, update or supersede the decision while the confirmed outcome, desired-future requirements, and non-goals remain true. End-to-end implementation design belongs to the Design Doc, schedule and repository tasks to the Work Plan. diff --git a/dev-workflows/skills/documentation-criteria/references/prd-template.md b/dev-workflows/skills/documentation-criteria/references/prd-template.md index 8d814d7..d0fea27 100644 --- a/dev-workflows/skills/documentation-criteria/references/prd-template.md +++ b/dev-workflows/skills/documentation-criteria/references/prd-template.md @@ -124,7 +124,7 @@ State observable success for the confirmed outcome. Include only sourced quantit - [Prerequisite requiring validation 2] ### Risks and Mitigation -Include only evidenced product or delivery risks that can change scope, success criteria, sequencing, or acceptance. +Include only evidenced product risks that can change scope, success criteria, or acceptance. | Risk | Impact | Probability | Mitigation | |------|--------|-------------|------------| diff --git a/dev-workflows/skills/requirement-convergence/SKILL.md b/dev-workflows/skills/requirement-convergence/SKILL.md index defb3cf..bd20961 100644 --- a/dev-workflows/skills/requirement-convergence/SKILL.md +++ b/dev-workflows/skills/requirement-convergence/SKILL.md @@ -51,7 +51,7 @@ Render this shape at every requirements confirmation stop, whether or not the he |---------|----------| | **Confirmed scope** | The requirements and exclusions the user has already selected, in the user's wording | | **Decision evidence** | Each material observed fact with its source, followed by what that fact can change about scope, outcome, or cost | -| **User decisions** | Each unresolved product, UX, or operational question, followed by the scope, outcome, or cost effects of its materially different answers | +| **User decisions** | One question per convergence field below `ready` (Hearing Protocol Step 1), followed by the scope, outcome, or cost effects of its materially different answers | | **Workflow** | Rough cost band with the unknowns that remain, Structural Scale, and the selected document and workflow route | Keeping the first three sections separate is what makes the decision informable: merged, the reader cannot tell which line is the user's own settled boundary, which is a repository observation, and which is still open. diff --git a/dev-workflows/skills/requirement-convergence/references/criteria.md b/dev-workflows/skills/requirement-convergence/references/criteria.md index 3e8d072..625980f 100644 --- a/dev-workflows/skills/requirement-convergence/references/criteria.md +++ b/dev-workflows/skills/requirement-convergence/references/criteria.md @@ -19,6 +19,8 @@ Evaluation requests, speculative ideas, and prescribed mechanisms stay in active Flattening current state, desired future, and candidates into one requirement list makes a bloated plan look coherent because every item then reads as equally required. Label each build-relevant item; ask when its current-state or desired-future role is unclear rather than inferring it. +An item is build-relevant when the repository change can satisfy it. A precondition held outside that change, such as legal or policy review, contract execution, release execution, or organizational approval, enters `requirements[]` and the hearing only when the user's wording raises it. + ## nonGoals[] Capabilities deliberately excluded from this change, authored by the user. diff --git a/dev-workflows/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows/skills/subagents-orchestration-guide/SKILL.md index 77c4b77..39b8972 100644 --- a/dev-workflows/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows/skills/subagents-orchestration-guide/SKILL.md @@ -19,7 +19,7 @@ This section governs the orchestrator's Agent prompt. Each specialist's agent de ### First Action Rule -When receiving a new full-cycle task, retain the user's complete wording in the orchestrator and invoke requirement-analyzer with the Requirement Evidence Handoff below. Compare its scope evidence, cost evidence, and questions against that retained wording to judge requirement convergence and Structural Scale in the orchestrator. Dedicated design recipes use their own codebase-scoped bootstrap. +When receiving a new full-cycle task, retain the user's complete wording in the orchestrator and invoke requirement-analyzer with the Requirement Evidence Handoff below. Compare its scope evidence and cost evidence against that retained wording to judge requirement convergence and Structural Scale in the orchestrator. Dedicated design recipes use their own codebase-scoped bootstrap. **Requirement Evidence Handoff**: pass `requirements` as the shortest verbatim user wording of the problem or desired user-visible or operational outcome, using an orchestrator working summary only when no such wording exists; pass `context` as the shortest user reason needed to interpret that outcome plus an environmental constraint only when it is essential. Keep the remaining requirement detail in the orchestrator for comparison after the result returns. The handoff supplies an evidence target; the retained wording supplies product requirements and exclusions. Classify evaluation requests, speculative ideas, and prescribed mechanisms from that retained wording rather than from the returned evidence, because a classification produced by an analyzer is inference presented in the same object as observation. @@ -27,7 +27,7 @@ Build and judge the `convergence` record in the orchestrator with the requiremen ### Small Evidence Gate -Classify Small when `scopeEvidence.executionRoute.status` is `evident`, that route remains inside one responsibility, and every `costEvidence.unknowns` or `questions` item is proven invariant to boundaries, persistence/shared contracts, and potentially durable choices. Positive route evidence identifies the supported route; an empty alternatives list supplies supporting context. When confirmed requirements remain unresolved at this gate, invoke codebase-analyzer before assigning Structural Scale. Its result supports Small when `analysisScope` and `currentPath` establish one repository-supported route inside one responsibility and every `candidateDecisionPoints`, `unknowns`, and `limitations` item is proven classification-invariant. Other observed boundaries and outcomes route Medium or Large. Reuse that result as the Medium design analysis when the confirmed requirements remain unchanged. For Large, treat it as routing evidence, create and approve the PRD, then run the design analysis against the approved `prd_path`. ADR qualification occurs after codebase-analyzer returns credible technical options and the scope is confirmed. +Classify Small when `scopeEvidence.executionRoute.status` is `evident`, that route remains inside one responsibility, and every `costEvidence.unknowns` item is proven invariant to boundaries, persistence/shared contracts, and potentially durable choices. Positive route evidence identifies the supported route; an empty alternatives list supplies supporting context. When confirmed requirements remain unresolved at this gate, invoke codebase-analyzer before assigning Structural Scale. Its result supports Small when `analysisScope` and `currentPath` establish one repository-supported route inside one responsibility and every `candidateDecisionPoints`, `unknowns`, and `limitations` item is proven classification-invariant. Other observed boundaries and outcomes route Medium or Large. Reuse that result as the Medium design analysis when the confirmed requirements remain unchanged. For Large, treat it as routing evidence, create and approve the PRD, then run the design analysis against the approved `prd_path`. ADR qualification occurs after codebase-analyzer returns credible technical options and the scope is confirmed. ### Requirement Change Detection During Flow @@ -260,7 +260,7 @@ Before post-implementation verifiers, collect retained verification limitations ## Handoff Contracts ### HC-01: requirement-analyzer → orchestrator and codebase-analyzer -- Invoke with the Requirement Evidence Handoff. The orchestrator compares the returned `scopeEvidence`, `costEvidence`, and `questions` against its retained user wording to judge convergence and Structural Scale. Small requires the positive `scopeEvidence.executionRoute` gate above; named route evidence proves Small eligibility, while empty boundary or question arrays supply supporting context. +- Invoke with the Requirement Evidence Handoff. The orchestrator compares the returned `scopeEvidence` and `costEvidence` against its retained user wording to judge convergence and Structural Scale. Small requires the positive `scopeEvidence.executionRoute` gate above; named route evidence proves Small eligibility, while empty boundary or unknown arrays supply supporting context. - Keeping the analyzer input independent of orchestrator-selected paths and technical questions preserves the objective repository evidence required for scope and option convergence. ### HC-01b: convergence record → document owner diff --git a/package.json b/package.json index 4eecb89..febc010 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "claude-code-workflows", - "version": "0.29.3", + "version": "0.29.4", "private": true, "type": "module", "engines": { diff --git a/skills/documentation-criteria/SKILL.md b/skills/documentation-criteria/SKILL.md index 1e6f67a..2565155 100644 --- a/skills/documentation-criteria/SKILL.md +++ b/skills/documentation-criteria/SKILL.md @@ -11,7 +11,7 @@ This file holds the routing decision: which documents a change requires and wher Each document fixes one class of decision that the repository alone cannot supply. An unfilled section becomes a guess made later by the consumer named below, with no record of what was assumed. -- **PRD** — Fixes the business outcome and the acceptance criteria later work traces to. Its AC IDs are the traceability keys that the Design Doc, UI Spec, and test selection reuse; without them each consumer re-derives requirements from prose and the link between a test and the value it protects is lost. Implementation details belong to the Design Doc, selection rationale to an ADR, phases and task breakdown to the Work Plan. +- **PRD** — Fixes the business outcome and the acceptance criteria later work traces to. Its AC IDs are the traceability keys that the Design Doc, UI Spec, and test selection reuse; without them each consumer re-derives requirements from prose and the link between a test and the value it protects is lost. Implementation details belong to the Design Doc, selection rationale to an ADR, phases and task breakdown to the Work Plan. Later design, review, and test selection treat its content as governing, so a precondition held outside the repository change, such as release execution or organizational approval, appears in it only when the user's wording raises it. - **ADR** — Records one durable technical choice and the options it beat, so later work can tell a deliberate decision from an accident. Without it a future change either re-runs the same comparison or silently reverses it. `Accepted` records the currently selected means, not an obligation to retain it: when later evidence supports a smaller sufficient choice, update or supersede the decision while the confirmed outcome, desired-future requirements, and non-goals remain true. End-to-end implementation design belongs to the Design Doc, schedule and repository tasks to the Work Plan. diff --git a/skills/documentation-criteria/references/prd-template.md b/skills/documentation-criteria/references/prd-template.md index 8d814d7..d0fea27 100644 --- a/skills/documentation-criteria/references/prd-template.md +++ b/skills/documentation-criteria/references/prd-template.md @@ -124,7 +124,7 @@ State observable success for the confirmed outcome. Include only sourced quantit - [Prerequisite requiring validation 2] ### Risks and Mitigation -Include only evidenced product or delivery risks that can change scope, success criteria, sequencing, or acceptance. +Include only evidenced product risks that can change scope, success criteria, or acceptance. | Risk | Impact | Probability | Mitigation | |------|--------|-------------|------------| diff --git a/skills/requirement-convergence/SKILL.md b/skills/requirement-convergence/SKILL.md index defb3cf..bd20961 100644 --- a/skills/requirement-convergence/SKILL.md +++ b/skills/requirement-convergence/SKILL.md @@ -51,7 +51,7 @@ Render this shape at every requirements confirmation stop, whether or not the he |---------|----------| | **Confirmed scope** | The requirements and exclusions the user has already selected, in the user's wording | | **Decision evidence** | Each material observed fact with its source, followed by what that fact can change about scope, outcome, or cost | -| **User decisions** | Each unresolved product, UX, or operational question, followed by the scope, outcome, or cost effects of its materially different answers | +| **User decisions** | One question per convergence field below `ready` (Hearing Protocol Step 1), followed by the scope, outcome, or cost effects of its materially different answers | | **Workflow** | Rough cost band with the unknowns that remain, Structural Scale, and the selected document and workflow route | Keeping the first three sections separate is what makes the decision informable: merged, the reader cannot tell which line is the user's own settled boundary, which is a repository observation, and which is still open. diff --git a/skills/requirement-convergence/references/criteria.md b/skills/requirement-convergence/references/criteria.md index 3e8d072..625980f 100644 --- a/skills/requirement-convergence/references/criteria.md +++ b/skills/requirement-convergence/references/criteria.md @@ -19,6 +19,8 @@ Evaluation requests, speculative ideas, and prescribed mechanisms stay in active Flattening current state, desired future, and candidates into one requirement list makes a bloated plan look coherent because every item then reads as equally required. Label each build-relevant item; ask when its current-state or desired-future role is unclear rather than inferring it. +An item is build-relevant when the repository change can satisfy it. A precondition held outside that change, such as legal or policy review, contract execution, release execution, or organizational approval, enters `requirements[]` and the hearing only when the user's wording raises it. + ## nonGoals[] Capabilities deliberately excluded from this change, authored by the user. diff --git a/skills/subagents-orchestration-guide/SKILL.md b/skills/subagents-orchestration-guide/SKILL.md index 77c4b77..39b8972 100644 --- a/skills/subagents-orchestration-guide/SKILL.md +++ b/skills/subagents-orchestration-guide/SKILL.md @@ -19,7 +19,7 @@ This section governs the orchestrator's Agent prompt. Each specialist's agent de ### First Action Rule -When receiving a new full-cycle task, retain the user's complete wording in the orchestrator and invoke requirement-analyzer with the Requirement Evidence Handoff below. Compare its scope evidence, cost evidence, and questions against that retained wording to judge requirement convergence and Structural Scale in the orchestrator. Dedicated design recipes use their own codebase-scoped bootstrap. +When receiving a new full-cycle task, retain the user's complete wording in the orchestrator and invoke requirement-analyzer with the Requirement Evidence Handoff below. Compare its scope evidence and cost evidence against that retained wording to judge requirement convergence and Structural Scale in the orchestrator. Dedicated design recipes use their own codebase-scoped bootstrap. **Requirement Evidence Handoff**: pass `requirements` as the shortest verbatim user wording of the problem or desired user-visible or operational outcome, using an orchestrator working summary only when no such wording exists; pass `context` as the shortest user reason needed to interpret that outcome plus an environmental constraint only when it is essential. Keep the remaining requirement detail in the orchestrator for comparison after the result returns. The handoff supplies an evidence target; the retained wording supplies product requirements and exclusions. Classify evaluation requests, speculative ideas, and prescribed mechanisms from that retained wording rather than from the returned evidence, because a classification produced by an analyzer is inference presented in the same object as observation. @@ -27,7 +27,7 @@ Build and judge the `convergence` record in the orchestrator with the requiremen ### Small Evidence Gate -Classify Small when `scopeEvidence.executionRoute.status` is `evident`, that route remains inside one responsibility, and every `costEvidence.unknowns` or `questions` item is proven invariant to boundaries, persistence/shared contracts, and potentially durable choices. Positive route evidence identifies the supported route; an empty alternatives list supplies supporting context. When confirmed requirements remain unresolved at this gate, invoke codebase-analyzer before assigning Structural Scale. Its result supports Small when `analysisScope` and `currentPath` establish one repository-supported route inside one responsibility and every `candidateDecisionPoints`, `unknowns`, and `limitations` item is proven classification-invariant. Other observed boundaries and outcomes route Medium or Large. Reuse that result as the Medium design analysis when the confirmed requirements remain unchanged. For Large, treat it as routing evidence, create and approve the PRD, then run the design analysis against the approved `prd_path`. ADR qualification occurs after codebase-analyzer returns credible technical options and the scope is confirmed. +Classify Small when `scopeEvidence.executionRoute.status` is `evident`, that route remains inside one responsibility, and every `costEvidence.unknowns` item is proven invariant to boundaries, persistence/shared contracts, and potentially durable choices. Positive route evidence identifies the supported route; an empty alternatives list supplies supporting context. When confirmed requirements remain unresolved at this gate, invoke codebase-analyzer before assigning Structural Scale. Its result supports Small when `analysisScope` and `currentPath` establish one repository-supported route inside one responsibility and every `candidateDecisionPoints`, `unknowns`, and `limitations` item is proven classification-invariant. Other observed boundaries and outcomes route Medium or Large. Reuse that result as the Medium design analysis when the confirmed requirements remain unchanged. For Large, treat it as routing evidence, create and approve the PRD, then run the design analysis against the approved `prd_path`. ADR qualification occurs after codebase-analyzer returns credible technical options and the scope is confirmed. ### Requirement Change Detection During Flow @@ -260,7 +260,7 @@ Before post-implementation verifiers, collect retained verification limitations ## Handoff Contracts ### HC-01: requirement-analyzer → orchestrator and codebase-analyzer -- Invoke with the Requirement Evidence Handoff. The orchestrator compares the returned `scopeEvidence`, `costEvidence`, and `questions` against its retained user wording to judge convergence and Structural Scale. Small requires the positive `scopeEvidence.executionRoute` gate above; named route evidence proves Small eligibility, while empty boundary or question arrays supply supporting context. +- Invoke with the Requirement Evidence Handoff. The orchestrator compares the returned `scopeEvidence` and `costEvidence` against its retained user wording to judge convergence and Structural Scale. Small requires the positive `scopeEvidence.executionRoute` gate above; named route evidence proves Small eligibility, while empty boundary or unknown arrays supply supporting context. - Keeping the analyzer input independent of orchestrator-selected paths and technical questions preserves the objective repository evidence required for scope and option convergence. ### HC-01b: convergence record → document owner