From 6a82a919edea7bf465e8649070b0c34488b678bf Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Mon, 2 Nov 2026 15:48:53 +0900 Subject: [PATCH] Judge design additions against their origin and select unset quality levels Co-Authored-By: Claude Opus 5.5 --- .claude-plugin/marketplace.json | 8 ++++---- agents/technical-designer-frontend.md | 6 +++--- agents/technical-designer.md | 6 +++--- dev-skills/.claude-plugin/plugin.json | 2 +- .../references/design-template.md | 7 ++----- dev-skills/skills/implementation-approach/SKILL.md | 13 ++----------- dev-workflows-frontend/.claude-plugin/plugin.json | 2 +- .../agents/technical-designer-frontend.md | 6 +++--- .../references/design-template.md | 7 ++----- .../skills/implementation-approach/SKILL.md | 13 ++----------- .../skills/subagents-orchestration-guide/SKILL.md | 2 +- .../references/review-resolution.md | 2 +- dev-workflows-fullstack/.claude-plugin/plugin.json | 2 +- .../agents/technical-designer-frontend.md | 6 +++--- .../agents/technical-designer.md | 6 +++--- .../references/design-template.md | 7 ++----- .../skills/implementation-approach/SKILL.md | 13 ++----------- .../skills/subagents-orchestration-guide/SKILL.md | 2 +- .../references/review-resolution.md | 2 +- dev-workflows/.claude-plugin/plugin.json | 2 +- dev-workflows/agents/technical-designer.md | 6 +++--- .../references/design-template.md | 7 ++----- .../skills/implementation-approach/SKILL.md | 13 ++----------- .../skills/subagents-orchestration-guide/SKILL.md | 2 +- .../references/review-resolution.md | 2 +- package.json | 2 +- .../references/design-template.md | 7 ++----- skills/implementation-approach/SKILL.md | 13 ++----------- skills/subagents-orchestration-guide/SKILL.md | 2 +- .../references/review-resolution.md | 2 +- 30 files changed, 55 insertions(+), 115 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index cc34e4e..836c161 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.4", + "version": "0.29.5", "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.4", + "version": "0.29.5", "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.4", + "version": "0.29.5", "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.4", + "version": "0.29.5", "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/technical-designer-frontend.md b/agents/technical-designer-frontend.md index e4aa15d..6909ce3 100644 --- a/agents/technical-designer-frontend.md +++ b/agents/technical-designer-frontend.md @@ -57,7 +57,7 @@ For each ADR: 1. Keep one technical question inside confirmed scope. 2. Compare every credible, materially distinct option using confirmed product value, repository fit, total complexity, maintainability, material trade-offs, and reversibility. -3. Select the smallest sufficient option whose total complexity is justified by confirmed product value. +3. Select the smallest sufficient option whose total complexity is justified by confirmed product value. Compare options at the stated quality levels, or at the implementation-approach selected level where the requirements leave one unset, and record that level in the decision. 4. Record only the selected decision as a downstream constraint. Requirements and any applicable approved UI Spec remain UI scope. 5. Keep component implementation and end-to-end flow out of the ADR. Repository-owned implementation details go to the Design Doc only when confirmed scope activates them; external release execution and organizational rollout remain outside both artifacts. @@ -106,7 +106,7 @@ When existing evidence resolves the premise, update from that evidence without a ## Update Mode -Update requested sections and dependent statements. For `correction_findings`, resolve each received defect within confirmed requirements, using existing responsibilities. Accepted design decisions record the current means: remove or narrow one when the confirmed outcome, desired-future requirements, and non-goals stay true. If the confirmed outcome cannot otherwise be achieved, return the failing condition and evidence before changing that design. Preserve unaffected decisions, historical safeguards, and update history. Re-check only identifiers, Props, state, or contracts whose meaning changes. An ADR update operates on one existing ADR. +Update requested sections and dependent statements. For `correction_findings`, resolve each received defect within confirmed requirements, using existing responsibilities. Treat a finding's proposed correction as one candidate and choose in this order: remove or narrow the addition, claim, or accepted design decision it concerns, reuse existing behavior, then add or extend a mechanism only when the earlier options leave the requirement, accepted decision, or repository contract behind the finding unmet. Accepted design decisions record the current means, so removing or narrowing one is valid when the confirmed outcome, desired-future requirements, and non-goals stay true. If the confirmed outcome cannot otherwise be achieved, return the failing condition and evidence before changing that design. Preserve unaffected decisions, historical safeguards, and update history. Re-check only identifiers, Props, state, or contracts whose meaning changes. An ADR update operates on one existing ADR. ## Reverse-Engineer Mode @@ -128,5 +128,5 @@ Document supplied inventory and existing frontend behavior as-is. Trace in-scope - Every created ADR passes both filters and selects the lowest-total-complexity sufficient option. - The Design Doc remains the complete frontend implementation design even when ADRs exist. - Existing UI behavior, contracts, assumptions, states, equivalence, and verification safeguards applicable to the change remain available downstream. -- The Selected Design delivers the outcome, and every added design surface becomes necessary again when removed from its recorded evidence. +- The Selected Design delivers the outcome, and removing any added design surface leaves the origin named in its Subtraction result unmet. - The final response is one valid JSON object. diff --git a/agents/technical-designer.md b/agents/technical-designer.md index 84b7bd2..4787cf6 100644 --- a/agents/technical-designer.md +++ b/agents/technical-designer.md @@ -62,7 +62,7 @@ For each ADR: 1. Keep one technical question inside confirmed scope. 2. Compare every credible, materially distinct option using confirmed product value, repository fit, total complexity, maintainability, material trade-offs, and reversibility. -3. Select the smallest sufficient option whose total complexity is justified by confirmed product value. Use relative evidence rather than fabricated estimates. +3. Select the smallest sufficient option whose total complexity is justified by confirmed product value. Use relative evidence rather than fabricated estimates. Compare options at the stated quality levels, or at the implementation-approach selected level where the requirements leave one unset, and record that level in the decision. 4. Record only the selected decision as a downstream technical constraint. The confirmed requirements remain implementation scope. 5. Keep end-to-end implementation design out of the ADR. Repository-owned implementation details go to the Design Doc only when confirmed scope activates them; external release execution and organizational rollout remain outside both artifacts. @@ -112,7 +112,7 @@ When existing evidence resolves the premise, update from that evidence without a ## Update Mode -Update requested sections and dependent statements. For `correction_findings`, resolve each received defect within confirmed requirements, using existing responsibilities. Accepted design decisions record the current means: remove or narrow one when the confirmed outcome, desired-future requirements, and non-goals stay true. If the confirmed outcome cannot otherwise be achieved, return the failing condition and evidence before changing that design. Preserve unaffected decisions, historical safeguards, and update history. Re-check only identifiers or contracts whose meaning the update changes. An ADR update operates on one existing ADR; batch creation is a create-mode operation. +Update requested sections and dependent statements. For `correction_findings`, resolve each received defect within confirmed requirements, using existing responsibilities. Treat a finding's proposed correction as one candidate and choose in this order: remove or narrow the addition, claim, or accepted design decision it concerns, reuse existing behavior, then add or extend a mechanism only when the earlier options leave the requirement, accepted decision, or repository contract behind the finding unmet. Accepted design decisions record the current means, so removing or narrowing one is valid when the confirmed outcome, desired-future requirements, and non-goals stay true. If the confirmed outcome cannot otherwise be achieved, return the failing condition and evidence before changing that design. Preserve unaffected decisions, historical safeguards, and update history. Re-check only identifiers or contracts whose meaning the update changes. An ADR update operates on one existing ADR; batch creation is a create-mode operation. ## Reverse-Engineer Mode @@ -134,5 +134,5 @@ Document supplied inventory and existing behavior as-is. Trace each in-scope ent - Every created ADR passes both filters and selects the lowest-total-complexity sufficient option. - The Design Doc remains the complete implementation design even when ADRs exist. - Existing-behavior, contract, assumption, equivalence, and verification safeguards applicable to the change remain available to downstream consumers. -- The Selected Design delivers the outcome, and every added design surface becomes necessary again when removed from its recorded evidence. +- The Selected Design delivers the outcome, and removing any added design surface leaves the origin named in its Subtraction result unmet. - The final response is one valid JSON object. diff --git a/dev-skills/.claude-plugin/plugin.json b/dev-skills/.claude-plugin/plugin.json index 8c200bc..499633d 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.4", + "version": "0.29.5", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-skills/skills/documentation-criteria/references/design-template.md b/dev-skills/skills/documentation-criteria/references/design-template.md index 9172e42..b75daa3 100644 --- a/dev-skills/skills/documentation-criteria/references/design-template.md +++ b/dev-skills/skills/documentation-criteria/references/design-template.md @@ -74,10 +74,7 @@ How quality is enforced in the change area. Each item is either adopted (will be #### Non-Functional Requirements -- **Performance**: [Response time, throughput requirements] -- **Scalability**: [Requirements for handling increased load] -- **Reliability**: [Error rate, availability requirements] -- **Maintainability**: [Code readability and changeability] +- **[Quality attribute]**: [level] - Source: [requirement that states it | selected in Design Convergence because the requirements leave it unset] ## Acceptance Criteria (AC) - EARS Format @@ -201,7 +198,7 @@ For each added design surface—user decision, setting, mode, concept, output, p - **Addition**: [selected design surface] - **Current evidence**: [requirement, accepted decision, verified constraint, observed problem, or evidence-backed material risk] - **Lower-surface insufficiency**: [why reuse, derivation, on-demand computation, or current-boundary ownership does not satisfy the same condition] -- **Subtraction result**: [confirmed outcome, required boundary, or proof that becomes unmet when removed] +- **Subtraction result**: [confirmed outcome, required boundary, or proof that becomes unmet when removed, traced to its originating requirement, accepted decision, or repository rule or contract] Use `None — existing design surface is sufficient` when the selected design adds none of these surfaces. diff --git a/dev-skills/skills/implementation-approach/SKILL.md b/dev-skills/skills/implementation-approach/SKILL.md index 6692145..84ebdcf 100644 --- a/dev-skills/skills/implementation-approach/SKILL.md +++ b/dev-skills/skills/implementation-approach/SKILL.md @@ -31,9 +31,9 @@ Stop when another current-state fact cannot change responsibility, reuse, option Complete these steps in order before selecting an implementation strategy: 1. **Existing-Surface Baseline**: Form the simplest end-to-end path that delivers the current outcome through existing responsibilities. Explicit requirements and accepted decisions are binding; suggested mechanisms remain candidates. -2. **Evidence Check**: Test that path against current requirements, verified constraints, observed in-scope problems, and evidence-backed material risks. Keep only the unmet conditions that can change the selected design. +2. **Evidence Check**: Test that path against current requirements, verified constraints, observed in-scope problems, and evidence-backed material risks. Keep only the unmet conditions that can change the selected design. Where the requirements leave a quality level unset, such as performance, freshness, consistency, availability, or protection beyond the required trust boundary, test against the lowest level that still delivers the outcome and record it as the selected level. 3. **Targeted Comparison**: For each unmet condition, test reuse, derivation from existing data, on-demand computation, or responsibility at the current caller or boundary before adding design surface. Compare viable choices by total complexity across the dimensions that materially differ: user decisions, settings, modes, concepts, outputs, persistent state, implementation paths, UX, runtime, implementation, testing, documentation, and maintenance. Select the lowest-total-complexity choice that satisfies the condition. -4. **Subtraction Check**: Remove each proposed addition and re-test its governing condition. Retain it only when the confirmed outcome, a required boundary, or necessary proof becomes unmet. +4. **Subtraction Check**: Remove each proposed addition and re-test its governing condition. Retain it only when the confirmed outcome, a required boundary, or necessary proof becomes unmet at its origin (a confirmed requirement, an accepted decision, or a repository rule or contract); a criterion, invariant, or constraint that a workflow artifact derived from that origin is narrowed to what the origin requires instead. Classify supporting claims as observed, inferred, or unknown. Route an unknown that blocks the next step as an exact evidence prerequisite; the caller's value-boundary and irreversible-action gates determine whether user interaction is required. @@ -79,13 +79,6 @@ Evaluate only risk categories for which current evidence can change the strategy ```yaml Technical Risks: System impact, data consistency, performance degradation, integration complexity Operational Risks: Service availability, deployment downtime, process changes, rollback procedures -Project Risks: Schedule delays, learning costs, quality achievement, team coordination -``` - -#### Risk Control Strategies -```yaml -Preventive Measures: Phased migration, parallel operation verification, integration/regression tests, monitoring setup -Incident Response: Rollback procedures, log/metrics preparation, communication system, service continuation procedures ``` ### Phase 5: Decision-Relevant Constraint Compatibility @@ -98,8 +91,6 @@ Check only constraints evidenced by the governing requirements, repository, exte ```yaml Technical Constraints: Library compatibility, resource capacity, mandatory requirements, numerical targets Temporal Constraints: Deadlines/priorities, dependencies, milestones, learning periods -Resource Constraints: Team/skills, work hours/systems, budget, external contracts -Business Constraints: Market launch timing, customer impact, regulatory compliance ``` ### Phase 6: Implementation Approach Decision diff --git a/dev-workflows-frontend/.claude-plugin/plugin.json b/dev-workflows-frontend/.claude-plugin/plugin.json index 3d20fd3..ac0af0f 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.4", + "version": "0.29.5", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows-frontend/agents/technical-designer-frontend.md b/dev-workflows-frontend/agents/technical-designer-frontend.md index e4aa15d..6909ce3 100644 --- a/dev-workflows-frontend/agents/technical-designer-frontend.md +++ b/dev-workflows-frontend/agents/technical-designer-frontend.md @@ -57,7 +57,7 @@ For each ADR: 1. Keep one technical question inside confirmed scope. 2. Compare every credible, materially distinct option using confirmed product value, repository fit, total complexity, maintainability, material trade-offs, and reversibility. -3. Select the smallest sufficient option whose total complexity is justified by confirmed product value. +3. Select the smallest sufficient option whose total complexity is justified by confirmed product value. Compare options at the stated quality levels, or at the implementation-approach selected level where the requirements leave one unset, and record that level in the decision. 4. Record only the selected decision as a downstream constraint. Requirements and any applicable approved UI Spec remain UI scope. 5. Keep component implementation and end-to-end flow out of the ADR. Repository-owned implementation details go to the Design Doc only when confirmed scope activates them; external release execution and organizational rollout remain outside both artifacts. @@ -106,7 +106,7 @@ When existing evidence resolves the premise, update from that evidence without a ## Update Mode -Update requested sections and dependent statements. For `correction_findings`, resolve each received defect within confirmed requirements, using existing responsibilities. Accepted design decisions record the current means: remove or narrow one when the confirmed outcome, desired-future requirements, and non-goals stay true. If the confirmed outcome cannot otherwise be achieved, return the failing condition and evidence before changing that design. Preserve unaffected decisions, historical safeguards, and update history. Re-check only identifiers, Props, state, or contracts whose meaning changes. An ADR update operates on one existing ADR. +Update requested sections and dependent statements. For `correction_findings`, resolve each received defect within confirmed requirements, using existing responsibilities. Treat a finding's proposed correction as one candidate and choose in this order: remove or narrow the addition, claim, or accepted design decision it concerns, reuse existing behavior, then add or extend a mechanism only when the earlier options leave the requirement, accepted decision, or repository contract behind the finding unmet. Accepted design decisions record the current means, so removing or narrowing one is valid when the confirmed outcome, desired-future requirements, and non-goals stay true. If the confirmed outcome cannot otherwise be achieved, return the failing condition and evidence before changing that design. Preserve unaffected decisions, historical safeguards, and update history. Re-check only identifiers, Props, state, or contracts whose meaning changes. An ADR update operates on one existing ADR. ## Reverse-Engineer Mode @@ -128,5 +128,5 @@ Document supplied inventory and existing frontend behavior as-is. Trace in-scope - Every created ADR passes both filters and selects the lowest-total-complexity sufficient option. - The Design Doc remains the complete frontend implementation design even when ADRs exist. - Existing UI behavior, contracts, assumptions, states, equivalence, and verification safeguards applicable to the change remain available downstream. -- The Selected Design delivers the outcome, and every added design surface becomes necessary again when removed from its recorded evidence. +- The Selected Design delivers the outcome, and removing any added design surface leaves the origin named in its Subtraction result unmet. - The final response is one valid JSON object. diff --git a/dev-workflows-frontend/skills/documentation-criteria/references/design-template.md b/dev-workflows-frontend/skills/documentation-criteria/references/design-template.md index 9172e42..b75daa3 100644 --- a/dev-workflows-frontend/skills/documentation-criteria/references/design-template.md +++ b/dev-workflows-frontend/skills/documentation-criteria/references/design-template.md @@ -74,10 +74,7 @@ How quality is enforced in the change area. Each item is either adopted (will be #### Non-Functional Requirements -- **Performance**: [Response time, throughput requirements] -- **Scalability**: [Requirements for handling increased load] -- **Reliability**: [Error rate, availability requirements] -- **Maintainability**: [Code readability and changeability] +- **[Quality attribute]**: [level] - Source: [requirement that states it | selected in Design Convergence because the requirements leave it unset] ## Acceptance Criteria (AC) - EARS Format @@ -201,7 +198,7 @@ For each added design surface—user decision, setting, mode, concept, output, p - **Addition**: [selected design surface] - **Current evidence**: [requirement, accepted decision, verified constraint, observed problem, or evidence-backed material risk] - **Lower-surface insufficiency**: [why reuse, derivation, on-demand computation, or current-boundary ownership does not satisfy the same condition] -- **Subtraction result**: [confirmed outcome, required boundary, or proof that becomes unmet when removed] +- **Subtraction result**: [confirmed outcome, required boundary, or proof that becomes unmet when removed, traced to its originating requirement, accepted decision, or repository rule or contract] Use `None — existing design surface is sufficient` when the selected design adds none of these surfaces. diff --git a/dev-workflows-frontend/skills/implementation-approach/SKILL.md b/dev-workflows-frontend/skills/implementation-approach/SKILL.md index 6692145..84ebdcf 100644 --- a/dev-workflows-frontend/skills/implementation-approach/SKILL.md +++ b/dev-workflows-frontend/skills/implementation-approach/SKILL.md @@ -31,9 +31,9 @@ Stop when another current-state fact cannot change responsibility, reuse, option Complete these steps in order before selecting an implementation strategy: 1. **Existing-Surface Baseline**: Form the simplest end-to-end path that delivers the current outcome through existing responsibilities. Explicit requirements and accepted decisions are binding; suggested mechanisms remain candidates. -2. **Evidence Check**: Test that path against current requirements, verified constraints, observed in-scope problems, and evidence-backed material risks. Keep only the unmet conditions that can change the selected design. +2. **Evidence Check**: Test that path against current requirements, verified constraints, observed in-scope problems, and evidence-backed material risks. Keep only the unmet conditions that can change the selected design. Where the requirements leave a quality level unset, such as performance, freshness, consistency, availability, or protection beyond the required trust boundary, test against the lowest level that still delivers the outcome and record it as the selected level. 3. **Targeted Comparison**: For each unmet condition, test reuse, derivation from existing data, on-demand computation, or responsibility at the current caller or boundary before adding design surface. Compare viable choices by total complexity across the dimensions that materially differ: user decisions, settings, modes, concepts, outputs, persistent state, implementation paths, UX, runtime, implementation, testing, documentation, and maintenance. Select the lowest-total-complexity choice that satisfies the condition. -4. **Subtraction Check**: Remove each proposed addition and re-test its governing condition. Retain it only when the confirmed outcome, a required boundary, or necessary proof becomes unmet. +4. **Subtraction Check**: Remove each proposed addition and re-test its governing condition. Retain it only when the confirmed outcome, a required boundary, or necessary proof becomes unmet at its origin (a confirmed requirement, an accepted decision, or a repository rule or contract); a criterion, invariant, or constraint that a workflow artifact derived from that origin is narrowed to what the origin requires instead. Classify supporting claims as observed, inferred, or unknown. Route an unknown that blocks the next step as an exact evidence prerequisite; the caller's value-boundary and irreversible-action gates determine whether user interaction is required. @@ -79,13 +79,6 @@ Evaluate only risk categories for which current evidence can change the strategy ```yaml Technical Risks: System impact, data consistency, performance degradation, integration complexity Operational Risks: Service availability, deployment downtime, process changes, rollback procedures -Project Risks: Schedule delays, learning costs, quality achievement, team coordination -``` - -#### Risk Control Strategies -```yaml -Preventive Measures: Phased migration, parallel operation verification, integration/regression tests, monitoring setup -Incident Response: Rollback procedures, log/metrics preparation, communication system, service continuation procedures ``` ### Phase 5: Decision-Relevant Constraint Compatibility @@ -98,8 +91,6 @@ Check only constraints evidenced by the governing requirements, repository, exte ```yaml Technical Constraints: Library compatibility, resource capacity, mandatory requirements, numerical targets Temporal Constraints: Deadlines/priorities, dependencies, milestones, learning periods -Resource Constraints: Team/skills, work hours/systems, budget, external contracts -Business Constraints: Market launch timing, customer impact, regulatory compliance ``` ### Phase 6: Implementation Approach Decision diff --git a/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md index 39b8972..2b20a32 100644 --- a/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md @@ -92,7 +92,7 @@ Workflow coordination is flat: the orchestrator issues every specialist call and Apply these approval stops when producing or materially revising an artifact in the current workflow. At each stop the user approves an action — completing the current phase, or authorizing implementation — rather than ratifying the artifact's technical content. Authority over required outcomes and explicit constraints comes from the user's own wording in the convergence record, not from passing a stop. A user instruction to proceed to a later phase accepts the preceding phases and authorizes entry into that phase; continue from that entry point rather than rechecking earlier review or approval records. In particular, a build instruction with an existing Work Plan grants batch approval for task materialization and implementation. -Before presenting an artifact at an approval stop, read its current version and base the presentation on that content. At the Design stop, also read the current PRD when present and state the confirmed user-visible outcome from it or the confirmed requirement context alongside major internal responsibility, contract, or refactoring changes, so the user can judge whether to proceed. +Before presenting an artifact at an approval stop, read its current version and base the presentation on that content. At the ADR batch and Design stops, state each quality level the artifacts selected where the requirements left it unset, so the user can raise one before dependent work. At the Design stop, also read the current PRD when present and state the confirmed user-visible outcome from it or the confirmed requirement context alongside major internal responsibility, contract, or refactoring changes, so the user can judge whether to proceed. | Phase | Stop Point | User Action Required | |-------|------------|---------------------| diff --git a/dev-workflows-frontend/skills/subagents-orchestration-guide/references/review-resolution.md b/dev-workflows-frontend/skills/subagents-orchestration-guide/references/review-resolution.md index 9720d26..09f6bae 100644 --- a/dev-workflows-frontend/skills/subagents-orchestration-guide/references/review-resolution.md +++ b/dev-workflows-frontend/skills/subagents-orchestration-guide/references/review-resolution.md @@ -36,7 +36,7 @@ The orchestrator records one disposition for every actionable finding: | `apply` | Leaving the current deliverable unchanged would prevent the confirmed outcome, violate a binding requirement, design decision, or repository rule, leave required correctness or verification unsupported, or commit downstream work to added design surface whose total complexity lacks current evidence. Otherwise, apply only when the material effect exceeds the response cost. | | `decline` | No material effect is established; the finding is outside the agreed boundary above or the reviewer's declared artifact boundary, or reverses an exclusion; or the response cost equals or exceeds the material effect. | -A confirmed security risk, implementation divergence, or governing-source contradiction receives `apply` when correction preserves the confirmed value boundaries; cost alone leaves that classification unchanged. Technical design, contract, or implementation changes are correction work rather than user decisions when those boundaries remain true. +A confirmed exploitable gap in a relied-upon trust boundary, implementation divergence, or governing-source contradiction receives `apply` when correction preserves the confirmed value boundaries; cost alone leaves that classification unchanged. Technical design, contract, or implementation changes are correction work rather than user decisions when those boundaries remain true. For each finding record: diff --git a/dev-workflows-fullstack/.claude-plugin/plugin.json b/dev-workflows-fullstack/.claude-plugin/plugin.json index fae6618..0e8cd55 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.4", + "version": "0.29.5", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows-fullstack/agents/technical-designer-frontend.md b/dev-workflows-fullstack/agents/technical-designer-frontend.md index e4aa15d..6909ce3 100644 --- a/dev-workflows-fullstack/agents/technical-designer-frontend.md +++ b/dev-workflows-fullstack/agents/technical-designer-frontend.md @@ -57,7 +57,7 @@ For each ADR: 1. Keep one technical question inside confirmed scope. 2. Compare every credible, materially distinct option using confirmed product value, repository fit, total complexity, maintainability, material trade-offs, and reversibility. -3. Select the smallest sufficient option whose total complexity is justified by confirmed product value. +3. Select the smallest sufficient option whose total complexity is justified by confirmed product value. Compare options at the stated quality levels, or at the implementation-approach selected level where the requirements leave one unset, and record that level in the decision. 4. Record only the selected decision as a downstream constraint. Requirements and any applicable approved UI Spec remain UI scope. 5. Keep component implementation and end-to-end flow out of the ADR. Repository-owned implementation details go to the Design Doc only when confirmed scope activates them; external release execution and organizational rollout remain outside both artifacts. @@ -106,7 +106,7 @@ When existing evidence resolves the premise, update from that evidence without a ## Update Mode -Update requested sections and dependent statements. For `correction_findings`, resolve each received defect within confirmed requirements, using existing responsibilities. Accepted design decisions record the current means: remove or narrow one when the confirmed outcome, desired-future requirements, and non-goals stay true. If the confirmed outcome cannot otherwise be achieved, return the failing condition and evidence before changing that design. Preserve unaffected decisions, historical safeguards, and update history. Re-check only identifiers, Props, state, or contracts whose meaning changes. An ADR update operates on one existing ADR. +Update requested sections and dependent statements. For `correction_findings`, resolve each received defect within confirmed requirements, using existing responsibilities. Treat a finding's proposed correction as one candidate and choose in this order: remove or narrow the addition, claim, or accepted design decision it concerns, reuse existing behavior, then add or extend a mechanism only when the earlier options leave the requirement, accepted decision, or repository contract behind the finding unmet. Accepted design decisions record the current means, so removing or narrowing one is valid when the confirmed outcome, desired-future requirements, and non-goals stay true. If the confirmed outcome cannot otherwise be achieved, return the failing condition and evidence before changing that design. Preserve unaffected decisions, historical safeguards, and update history. Re-check only identifiers, Props, state, or contracts whose meaning changes. An ADR update operates on one existing ADR. ## Reverse-Engineer Mode @@ -128,5 +128,5 @@ Document supplied inventory and existing frontend behavior as-is. Trace in-scope - Every created ADR passes both filters and selects the lowest-total-complexity sufficient option. - The Design Doc remains the complete frontend implementation design even when ADRs exist. - Existing UI behavior, contracts, assumptions, states, equivalence, and verification safeguards applicable to the change remain available downstream. -- The Selected Design delivers the outcome, and every added design surface becomes necessary again when removed from its recorded evidence. +- The Selected Design delivers the outcome, and removing any added design surface leaves the origin named in its Subtraction result unmet. - The final response is one valid JSON object. diff --git a/dev-workflows-fullstack/agents/technical-designer.md b/dev-workflows-fullstack/agents/technical-designer.md index 84b7bd2..4787cf6 100644 --- a/dev-workflows-fullstack/agents/technical-designer.md +++ b/dev-workflows-fullstack/agents/technical-designer.md @@ -62,7 +62,7 @@ For each ADR: 1. Keep one technical question inside confirmed scope. 2. Compare every credible, materially distinct option using confirmed product value, repository fit, total complexity, maintainability, material trade-offs, and reversibility. -3. Select the smallest sufficient option whose total complexity is justified by confirmed product value. Use relative evidence rather than fabricated estimates. +3. Select the smallest sufficient option whose total complexity is justified by confirmed product value. Use relative evidence rather than fabricated estimates. Compare options at the stated quality levels, or at the implementation-approach selected level where the requirements leave one unset, and record that level in the decision. 4. Record only the selected decision as a downstream technical constraint. The confirmed requirements remain implementation scope. 5. Keep end-to-end implementation design out of the ADR. Repository-owned implementation details go to the Design Doc only when confirmed scope activates them; external release execution and organizational rollout remain outside both artifacts. @@ -112,7 +112,7 @@ When existing evidence resolves the premise, update from that evidence without a ## Update Mode -Update requested sections and dependent statements. For `correction_findings`, resolve each received defect within confirmed requirements, using existing responsibilities. Accepted design decisions record the current means: remove or narrow one when the confirmed outcome, desired-future requirements, and non-goals stay true. If the confirmed outcome cannot otherwise be achieved, return the failing condition and evidence before changing that design. Preserve unaffected decisions, historical safeguards, and update history. Re-check only identifiers or contracts whose meaning the update changes. An ADR update operates on one existing ADR; batch creation is a create-mode operation. +Update requested sections and dependent statements. For `correction_findings`, resolve each received defect within confirmed requirements, using existing responsibilities. Treat a finding's proposed correction as one candidate and choose in this order: remove or narrow the addition, claim, or accepted design decision it concerns, reuse existing behavior, then add or extend a mechanism only when the earlier options leave the requirement, accepted decision, or repository contract behind the finding unmet. Accepted design decisions record the current means, so removing or narrowing one is valid when the confirmed outcome, desired-future requirements, and non-goals stay true. If the confirmed outcome cannot otherwise be achieved, return the failing condition and evidence before changing that design. Preserve unaffected decisions, historical safeguards, and update history. Re-check only identifiers or contracts whose meaning the update changes. An ADR update operates on one existing ADR; batch creation is a create-mode operation. ## Reverse-Engineer Mode @@ -134,5 +134,5 @@ Document supplied inventory and existing behavior as-is. Trace each in-scope ent - Every created ADR passes both filters and selects the lowest-total-complexity sufficient option. - The Design Doc remains the complete implementation design even when ADRs exist. - Existing-behavior, contract, assumption, equivalence, and verification safeguards applicable to the change remain available to downstream consumers. -- The Selected Design delivers the outcome, and every added design surface becomes necessary again when removed from its recorded evidence. +- The Selected Design delivers the outcome, and removing any added design surface leaves the origin named in its Subtraction result unmet. - The final response is one valid JSON object. diff --git a/dev-workflows-fullstack/skills/documentation-criteria/references/design-template.md b/dev-workflows-fullstack/skills/documentation-criteria/references/design-template.md index 9172e42..b75daa3 100644 --- a/dev-workflows-fullstack/skills/documentation-criteria/references/design-template.md +++ b/dev-workflows-fullstack/skills/documentation-criteria/references/design-template.md @@ -74,10 +74,7 @@ How quality is enforced in the change area. Each item is either adopted (will be #### Non-Functional Requirements -- **Performance**: [Response time, throughput requirements] -- **Scalability**: [Requirements for handling increased load] -- **Reliability**: [Error rate, availability requirements] -- **Maintainability**: [Code readability and changeability] +- **[Quality attribute]**: [level] - Source: [requirement that states it | selected in Design Convergence because the requirements leave it unset] ## Acceptance Criteria (AC) - EARS Format @@ -201,7 +198,7 @@ For each added design surface—user decision, setting, mode, concept, output, p - **Addition**: [selected design surface] - **Current evidence**: [requirement, accepted decision, verified constraint, observed problem, or evidence-backed material risk] - **Lower-surface insufficiency**: [why reuse, derivation, on-demand computation, or current-boundary ownership does not satisfy the same condition] -- **Subtraction result**: [confirmed outcome, required boundary, or proof that becomes unmet when removed] +- **Subtraction result**: [confirmed outcome, required boundary, or proof that becomes unmet when removed, traced to its originating requirement, accepted decision, or repository rule or contract] Use `None — existing design surface is sufficient` when the selected design adds none of these surfaces. diff --git a/dev-workflows-fullstack/skills/implementation-approach/SKILL.md b/dev-workflows-fullstack/skills/implementation-approach/SKILL.md index 6692145..84ebdcf 100644 --- a/dev-workflows-fullstack/skills/implementation-approach/SKILL.md +++ b/dev-workflows-fullstack/skills/implementation-approach/SKILL.md @@ -31,9 +31,9 @@ Stop when another current-state fact cannot change responsibility, reuse, option Complete these steps in order before selecting an implementation strategy: 1. **Existing-Surface Baseline**: Form the simplest end-to-end path that delivers the current outcome through existing responsibilities. Explicit requirements and accepted decisions are binding; suggested mechanisms remain candidates. -2. **Evidence Check**: Test that path against current requirements, verified constraints, observed in-scope problems, and evidence-backed material risks. Keep only the unmet conditions that can change the selected design. +2. **Evidence Check**: Test that path against current requirements, verified constraints, observed in-scope problems, and evidence-backed material risks. Keep only the unmet conditions that can change the selected design. Where the requirements leave a quality level unset, such as performance, freshness, consistency, availability, or protection beyond the required trust boundary, test against the lowest level that still delivers the outcome and record it as the selected level. 3. **Targeted Comparison**: For each unmet condition, test reuse, derivation from existing data, on-demand computation, or responsibility at the current caller or boundary before adding design surface. Compare viable choices by total complexity across the dimensions that materially differ: user decisions, settings, modes, concepts, outputs, persistent state, implementation paths, UX, runtime, implementation, testing, documentation, and maintenance. Select the lowest-total-complexity choice that satisfies the condition. -4. **Subtraction Check**: Remove each proposed addition and re-test its governing condition. Retain it only when the confirmed outcome, a required boundary, or necessary proof becomes unmet. +4. **Subtraction Check**: Remove each proposed addition and re-test its governing condition. Retain it only when the confirmed outcome, a required boundary, or necessary proof becomes unmet at its origin (a confirmed requirement, an accepted decision, or a repository rule or contract); a criterion, invariant, or constraint that a workflow artifact derived from that origin is narrowed to what the origin requires instead. Classify supporting claims as observed, inferred, or unknown. Route an unknown that blocks the next step as an exact evidence prerequisite; the caller's value-boundary and irreversible-action gates determine whether user interaction is required. @@ -79,13 +79,6 @@ Evaluate only risk categories for which current evidence can change the strategy ```yaml Technical Risks: System impact, data consistency, performance degradation, integration complexity Operational Risks: Service availability, deployment downtime, process changes, rollback procedures -Project Risks: Schedule delays, learning costs, quality achievement, team coordination -``` - -#### Risk Control Strategies -```yaml -Preventive Measures: Phased migration, parallel operation verification, integration/regression tests, monitoring setup -Incident Response: Rollback procedures, log/metrics preparation, communication system, service continuation procedures ``` ### Phase 5: Decision-Relevant Constraint Compatibility @@ -98,8 +91,6 @@ Check only constraints evidenced by the governing requirements, repository, exte ```yaml Technical Constraints: Library compatibility, resource capacity, mandatory requirements, numerical targets Temporal Constraints: Deadlines/priorities, dependencies, milestones, learning periods -Resource Constraints: Team/skills, work hours/systems, budget, external contracts -Business Constraints: Market launch timing, customer impact, regulatory compliance ``` ### Phase 6: Implementation Approach Decision diff --git a/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md index 39b8972..2b20a32 100644 --- a/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md @@ -92,7 +92,7 @@ Workflow coordination is flat: the orchestrator issues every specialist call and Apply these approval stops when producing or materially revising an artifact in the current workflow. At each stop the user approves an action — completing the current phase, or authorizing implementation — rather than ratifying the artifact's technical content. Authority over required outcomes and explicit constraints comes from the user's own wording in the convergence record, not from passing a stop. A user instruction to proceed to a later phase accepts the preceding phases and authorizes entry into that phase; continue from that entry point rather than rechecking earlier review or approval records. In particular, a build instruction with an existing Work Plan grants batch approval for task materialization and implementation. -Before presenting an artifact at an approval stop, read its current version and base the presentation on that content. At the Design stop, also read the current PRD when present and state the confirmed user-visible outcome from it or the confirmed requirement context alongside major internal responsibility, contract, or refactoring changes, so the user can judge whether to proceed. +Before presenting an artifact at an approval stop, read its current version and base the presentation on that content. At the ADR batch and Design stops, state each quality level the artifacts selected where the requirements left it unset, so the user can raise one before dependent work. At the Design stop, also read the current PRD when present and state the confirmed user-visible outcome from it or the confirmed requirement context alongside major internal responsibility, contract, or refactoring changes, so the user can judge whether to proceed. | Phase | Stop Point | User Action Required | |-------|------------|---------------------| diff --git a/dev-workflows-fullstack/skills/subagents-orchestration-guide/references/review-resolution.md b/dev-workflows-fullstack/skills/subagents-orchestration-guide/references/review-resolution.md index 9720d26..09f6bae 100644 --- a/dev-workflows-fullstack/skills/subagents-orchestration-guide/references/review-resolution.md +++ b/dev-workflows-fullstack/skills/subagents-orchestration-guide/references/review-resolution.md @@ -36,7 +36,7 @@ The orchestrator records one disposition for every actionable finding: | `apply` | Leaving the current deliverable unchanged would prevent the confirmed outcome, violate a binding requirement, design decision, or repository rule, leave required correctness or verification unsupported, or commit downstream work to added design surface whose total complexity lacks current evidence. Otherwise, apply only when the material effect exceeds the response cost. | | `decline` | No material effect is established; the finding is outside the agreed boundary above or the reviewer's declared artifact boundary, or reverses an exclusion; or the response cost equals or exceeds the material effect. | -A confirmed security risk, implementation divergence, or governing-source contradiction receives `apply` when correction preserves the confirmed value boundaries; cost alone leaves that classification unchanged. Technical design, contract, or implementation changes are correction work rather than user decisions when those boundaries remain true. +A confirmed exploitable gap in a relied-upon trust boundary, implementation divergence, or governing-source contradiction receives `apply` when correction preserves the confirmed value boundaries; cost alone leaves that classification unchanged. Technical design, contract, or implementation changes are correction work rather than user decisions when those boundaries remain true. For each finding record: diff --git a/dev-workflows/.claude-plugin/plugin.json b/dev-workflows/.claude-plugin/plugin.json index d97f4d9..2275880 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.4", + "version": "0.29.5", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows/agents/technical-designer.md b/dev-workflows/agents/technical-designer.md index 84b7bd2..4787cf6 100644 --- a/dev-workflows/agents/technical-designer.md +++ b/dev-workflows/agents/technical-designer.md @@ -62,7 +62,7 @@ For each ADR: 1. Keep one technical question inside confirmed scope. 2. Compare every credible, materially distinct option using confirmed product value, repository fit, total complexity, maintainability, material trade-offs, and reversibility. -3. Select the smallest sufficient option whose total complexity is justified by confirmed product value. Use relative evidence rather than fabricated estimates. +3. Select the smallest sufficient option whose total complexity is justified by confirmed product value. Use relative evidence rather than fabricated estimates. Compare options at the stated quality levels, or at the implementation-approach selected level where the requirements leave one unset, and record that level in the decision. 4. Record only the selected decision as a downstream technical constraint. The confirmed requirements remain implementation scope. 5. Keep end-to-end implementation design out of the ADR. Repository-owned implementation details go to the Design Doc only when confirmed scope activates them; external release execution and organizational rollout remain outside both artifacts. @@ -112,7 +112,7 @@ When existing evidence resolves the premise, update from that evidence without a ## Update Mode -Update requested sections and dependent statements. For `correction_findings`, resolve each received defect within confirmed requirements, using existing responsibilities. Accepted design decisions record the current means: remove or narrow one when the confirmed outcome, desired-future requirements, and non-goals stay true. If the confirmed outcome cannot otherwise be achieved, return the failing condition and evidence before changing that design. Preserve unaffected decisions, historical safeguards, and update history. Re-check only identifiers or contracts whose meaning the update changes. An ADR update operates on one existing ADR; batch creation is a create-mode operation. +Update requested sections and dependent statements. For `correction_findings`, resolve each received defect within confirmed requirements, using existing responsibilities. Treat a finding's proposed correction as one candidate and choose in this order: remove or narrow the addition, claim, or accepted design decision it concerns, reuse existing behavior, then add or extend a mechanism only when the earlier options leave the requirement, accepted decision, or repository contract behind the finding unmet. Accepted design decisions record the current means, so removing or narrowing one is valid when the confirmed outcome, desired-future requirements, and non-goals stay true. If the confirmed outcome cannot otherwise be achieved, return the failing condition and evidence before changing that design. Preserve unaffected decisions, historical safeguards, and update history. Re-check only identifiers or contracts whose meaning the update changes. An ADR update operates on one existing ADR; batch creation is a create-mode operation. ## Reverse-Engineer Mode @@ -134,5 +134,5 @@ Document supplied inventory and existing behavior as-is. Trace each in-scope ent - Every created ADR passes both filters and selects the lowest-total-complexity sufficient option. - The Design Doc remains the complete implementation design even when ADRs exist. - Existing-behavior, contract, assumption, equivalence, and verification safeguards applicable to the change remain available to downstream consumers. -- The Selected Design delivers the outcome, and every added design surface becomes necessary again when removed from its recorded evidence. +- The Selected Design delivers the outcome, and removing any added design surface leaves the origin named in its Subtraction result unmet. - The final response is one valid JSON object. diff --git a/dev-workflows/skills/documentation-criteria/references/design-template.md b/dev-workflows/skills/documentation-criteria/references/design-template.md index 9172e42..b75daa3 100644 --- a/dev-workflows/skills/documentation-criteria/references/design-template.md +++ b/dev-workflows/skills/documentation-criteria/references/design-template.md @@ -74,10 +74,7 @@ How quality is enforced in the change area. Each item is either adopted (will be #### Non-Functional Requirements -- **Performance**: [Response time, throughput requirements] -- **Scalability**: [Requirements for handling increased load] -- **Reliability**: [Error rate, availability requirements] -- **Maintainability**: [Code readability and changeability] +- **[Quality attribute]**: [level] - Source: [requirement that states it | selected in Design Convergence because the requirements leave it unset] ## Acceptance Criteria (AC) - EARS Format @@ -201,7 +198,7 @@ For each added design surface—user decision, setting, mode, concept, output, p - **Addition**: [selected design surface] - **Current evidence**: [requirement, accepted decision, verified constraint, observed problem, or evidence-backed material risk] - **Lower-surface insufficiency**: [why reuse, derivation, on-demand computation, or current-boundary ownership does not satisfy the same condition] -- **Subtraction result**: [confirmed outcome, required boundary, or proof that becomes unmet when removed] +- **Subtraction result**: [confirmed outcome, required boundary, or proof that becomes unmet when removed, traced to its originating requirement, accepted decision, or repository rule or contract] Use `None — existing design surface is sufficient` when the selected design adds none of these surfaces. diff --git a/dev-workflows/skills/implementation-approach/SKILL.md b/dev-workflows/skills/implementation-approach/SKILL.md index 6692145..84ebdcf 100644 --- a/dev-workflows/skills/implementation-approach/SKILL.md +++ b/dev-workflows/skills/implementation-approach/SKILL.md @@ -31,9 +31,9 @@ Stop when another current-state fact cannot change responsibility, reuse, option Complete these steps in order before selecting an implementation strategy: 1. **Existing-Surface Baseline**: Form the simplest end-to-end path that delivers the current outcome through existing responsibilities. Explicit requirements and accepted decisions are binding; suggested mechanisms remain candidates. -2. **Evidence Check**: Test that path against current requirements, verified constraints, observed in-scope problems, and evidence-backed material risks. Keep only the unmet conditions that can change the selected design. +2. **Evidence Check**: Test that path against current requirements, verified constraints, observed in-scope problems, and evidence-backed material risks. Keep only the unmet conditions that can change the selected design. Where the requirements leave a quality level unset, such as performance, freshness, consistency, availability, or protection beyond the required trust boundary, test against the lowest level that still delivers the outcome and record it as the selected level. 3. **Targeted Comparison**: For each unmet condition, test reuse, derivation from existing data, on-demand computation, or responsibility at the current caller or boundary before adding design surface. Compare viable choices by total complexity across the dimensions that materially differ: user decisions, settings, modes, concepts, outputs, persistent state, implementation paths, UX, runtime, implementation, testing, documentation, and maintenance. Select the lowest-total-complexity choice that satisfies the condition. -4. **Subtraction Check**: Remove each proposed addition and re-test its governing condition. Retain it only when the confirmed outcome, a required boundary, or necessary proof becomes unmet. +4. **Subtraction Check**: Remove each proposed addition and re-test its governing condition. Retain it only when the confirmed outcome, a required boundary, or necessary proof becomes unmet at its origin (a confirmed requirement, an accepted decision, or a repository rule or contract); a criterion, invariant, or constraint that a workflow artifact derived from that origin is narrowed to what the origin requires instead. Classify supporting claims as observed, inferred, or unknown. Route an unknown that blocks the next step as an exact evidence prerequisite; the caller's value-boundary and irreversible-action gates determine whether user interaction is required. @@ -79,13 +79,6 @@ Evaluate only risk categories for which current evidence can change the strategy ```yaml Technical Risks: System impact, data consistency, performance degradation, integration complexity Operational Risks: Service availability, deployment downtime, process changes, rollback procedures -Project Risks: Schedule delays, learning costs, quality achievement, team coordination -``` - -#### Risk Control Strategies -```yaml -Preventive Measures: Phased migration, parallel operation verification, integration/regression tests, monitoring setup -Incident Response: Rollback procedures, log/metrics preparation, communication system, service continuation procedures ``` ### Phase 5: Decision-Relevant Constraint Compatibility @@ -98,8 +91,6 @@ Check only constraints evidenced by the governing requirements, repository, exte ```yaml Technical Constraints: Library compatibility, resource capacity, mandatory requirements, numerical targets Temporal Constraints: Deadlines/priorities, dependencies, milestones, learning periods -Resource Constraints: Team/skills, work hours/systems, budget, external contracts -Business Constraints: Market launch timing, customer impact, regulatory compliance ``` ### Phase 6: Implementation Approach Decision diff --git a/dev-workflows/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows/skills/subagents-orchestration-guide/SKILL.md index 39b8972..2b20a32 100644 --- a/dev-workflows/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows/skills/subagents-orchestration-guide/SKILL.md @@ -92,7 +92,7 @@ Workflow coordination is flat: the orchestrator issues every specialist call and Apply these approval stops when producing or materially revising an artifact in the current workflow. At each stop the user approves an action — completing the current phase, or authorizing implementation — rather than ratifying the artifact's technical content. Authority over required outcomes and explicit constraints comes from the user's own wording in the convergence record, not from passing a stop. A user instruction to proceed to a later phase accepts the preceding phases and authorizes entry into that phase; continue from that entry point rather than rechecking earlier review or approval records. In particular, a build instruction with an existing Work Plan grants batch approval for task materialization and implementation. -Before presenting an artifact at an approval stop, read its current version and base the presentation on that content. At the Design stop, also read the current PRD when present and state the confirmed user-visible outcome from it or the confirmed requirement context alongside major internal responsibility, contract, or refactoring changes, so the user can judge whether to proceed. +Before presenting an artifact at an approval stop, read its current version and base the presentation on that content. At the ADR batch and Design stops, state each quality level the artifacts selected where the requirements left it unset, so the user can raise one before dependent work. At the Design stop, also read the current PRD when present and state the confirmed user-visible outcome from it or the confirmed requirement context alongside major internal responsibility, contract, or refactoring changes, so the user can judge whether to proceed. | Phase | Stop Point | User Action Required | |-------|------------|---------------------| diff --git a/dev-workflows/skills/subagents-orchestration-guide/references/review-resolution.md b/dev-workflows/skills/subagents-orchestration-guide/references/review-resolution.md index 9720d26..09f6bae 100644 --- a/dev-workflows/skills/subagents-orchestration-guide/references/review-resolution.md +++ b/dev-workflows/skills/subagents-orchestration-guide/references/review-resolution.md @@ -36,7 +36,7 @@ The orchestrator records one disposition for every actionable finding: | `apply` | Leaving the current deliverable unchanged would prevent the confirmed outcome, violate a binding requirement, design decision, or repository rule, leave required correctness or verification unsupported, or commit downstream work to added design surface whose total complexity lacks current evidence. Otherwise, apply only when the material effect exceeds the response cost. | | `decline` | No material effect is established; the finding is outside the agreed boundary above or the reviewer's declared artifact boundary, or reverses an exclusion; or the response cost equals or exceeds the material effect. | -A confirmed security risk, implementation divergence, or governing-source contradiction receives `apply` when correction preserves the confirmed value boundaries; cost alone leaves that classification unchanged. Technical design, contract, or implementation changes are correction work rather than user decisions when those boundaries remain true. +A confirmed exploitable gap in a relied-upon trust boundary, implementation divergence, or governing-source contradiction receives `apply` when correction preserves the confirmed value boundaries; cost alone leaves that classification unchanged. Technical design, contract, or implementation changes are correction work rather than user decisions when those boundaries remain true. For each finding record: diff --git a/package.json b/package.json index febc010..2f12fcc 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "claude-code-workflows", - "version": "0.29.4", + "version": "0.29.5", "private": true, "type": "module", "engines": { diff --git a/skills/documentation-criteria/references/design-template.md b/skills/documentation-criteria/references/design-template.md index 9172e42..b75daa3 100644 --- a/skills/documentation-criteria/references/design-template.md +++ b/skills/documentation-criteria/references/design-template.md @@ -74,10 +74,7 @@ How quality is enforced in the change area. Each item is either adopted (will be #### Non-Functional Requirements -- **Performance**: [Response time, throughput requirements] -- **Scalability**: [Requirements for handling increased load] -- **Reliability**: [Error rate, availability requirements] -- **Maintainability**: [Code readability and changeability] +- **[Quality attribute]**: [level] - Source: [requirement that states it | selected in Design Convergence because the requirements leave it unset] ## Acceptance Criteria (AC) - EARS Format @@ -201,7 +198,7 @@ For each added design surface—user decision, setting, mode, concept, output, p - **Addition**: [selected design surface] - **Current evidence**: [requirement, accepted decision, verified constraint, observed problem, or evidence-backed material risk] - **Lower-surface insufficiency**: [why reuse, derivation, on-demand computation, or current-boundary ownership does not satisfy the same condition] -- **Subtraction result**: [confirmed outcome, required boundary, or proof that becomes unmet when removed] +- **Subtraction result**: [confirmed outcome, required boundary, or proof that becomes unmet when removed, traced to its originating requirement, accepted decision, or repository rule or contract] Use `None — existing design surface is sufficient` when the selected design adds none of these surfaces. diff --git a/skills/implementation-approach/SKILL.md b/skills/implementation-approach/SKILL.md index 6692145..84ebdcf 100644 --- a/skills/implementation-approach/SKILL.md +++ b/skills/implementation-approach/SKILL.md @@ -31,9 +31,9 @@ Stop when another current-state fact cannot change responsibility, reuse, option Complete these steps in order before selecting an implementation strategy: 1. **Existing-Surface Baseline**: Form the simplest end-to-end path that delivers the current outcome through existing responsibilities. Explicit requirements and accepted decisions are binding; suggested mechanisms remain candidates. -2. **Evidence Check**: Test that path against current requirements, verified constraints, observed in-scope problems, and evidence-backed material risks. Keep only the unmet conditions that can change the selected design. +2. **Evidence Check**: Test that path against current requirements, verified constraints, observed in-scope problems, and evidence-backed material risks. Keep only the unmet conditions that can change the selected design. Where the requirements leave a quality level unset, such as performance, freshness, consistency, availability, or protection beyond the required trust boundary, test against the lowest level that still delivers the outcome and record it as the selected level. 3. **Targeted Comparison**: For each unmet condition, test reuse, derivation from existing data, on-demand computation, or responsibility at the current caller or boundary before adding design surface. Compare viable choices by total complexity across the dimensions that materially differ: user decisions, settings, modes, concepts, outputs, persistent state, implementation paths, UX, runtime, implementation, testing, documentation, and maintenance. Select the lowest-total-complexity choice that satisfies the condition. -4. **Subtraction Check**: Remove each proposed addition and re-test its governing condition. Retain it only when the confirmed outcome, a required boundary, or necessary proof becomes unmet. +4. **Subtraction Check**: Remove each proposed addition and re-test its governing condition. Retain it only when the confirmed outcome, a required boundary, or necessary proof becomes unmet at its origin (a confirmed requirement, an accepted decision, or a repository rule or contract); a criterion, invariant, or constraint that a workflow artifact derived from that origin is narrowed to what the origin requires instead. Classify supporting claims as observed, inferred, or unknown. Route an unknown that blocks the next step as an exact evidence prerequisite; the caller's value-boundary and irreversible-action gates determine whether user interaction is required. @@ -79,13 +79,6 @@ Evaluate only risk categories for which current evidence can change the strategy ```yaml Technical Risks: System impact, data consistency, performance degradation, integration complexity Operational Risks: Service availability, deployment downtime, process changes, rollback procedures -Project Risks: Schedule delays, learning costs, quality achievement, team coordination -``` - -#### Risk Control Strategies -```yaml -Preventive Measures: Phased migration, parallel operation verification, integration/regression tests, monitoring setup -Incident Response: Rollback procedures, log/metrics preparation, communication system, service continuation procedures ``` ### Phase 5: Decision-Relevant Constraint Compatibility @@ -98,8 +91,6 @@ Check only constraints evidenced by the governing requirements, repository, exte ```yaml Technical Constraints: Library compatibility, resource capacity, mandatory requirements, numerical targets Temporal Constraints: Deadlines/priorities, dependencies, milestones, learning periods -Resource Constraints: Team/skills, work hours/systems, budget, external contracts -Business Constraints: Market launch timing, customer impact, regulatory compliance ``` ### Phase 6: Implementation Approach Decision diff --git a/skills/subagents-orchestration-guide/SKILL.md b/skills/subagents-orchestration-guide/SKILL.md index 39b8972..2b20a32 100644 --- a/skills/subagents-orchestration-guide/SKILL.md +++ b/skills/subagents-orchestration-guide/SKILL.md @@ -92,7 +92,7 @@ Workflow coordination is flat: the orchestrator issues every specialist call and Apply these approval stops when producing or materially revising an artifact in the current workflow. At each stop the user approves an action — completing the current phase, or authorizing implementation — rather than ratifying the artifact's technical content. Authority over required outcomes and explicit constraints comes from the user's own wording in the convergence record, not from passing a stop. A user instruction to proceed to a later phase accepts the preceding phases and authorizes entry into that phase; continue from that entry point rather than rechecking earlier review or approval records. In particular, a build instruction with an existing Work Plan grants batch approval for task materialization and implementation. -Before presenting an artifact at an approval stop, read its current version and base the presentation on that content. At the Design stop, also read the current PRD when present and state the confirmed user-visible outcome from it or the confirmed requirement context alongside major internal responsibility, contract, or refactoring changes, so the user can judge whether to proceed. +Before presenting an artifact at an approval stop, read its current version and base the presentation on that content. At the ADR batch and Design stops, state each quality level the artifacts selected where the requirements left it unset, so the user can raise one before dependent work. At the Design stop, also read the current PRD when present and state the confirmed user-visible outcome from it or the confirmed requirement context alongside major internal responsibility, contract, or refactoring changes, so the user can judge whether to proceed. | Phase | Stop Point | User Action Required | |-------|------------|---------------------| diff --git a/skills/subagents-orchestration-guide/references/review-resolution.md b/skills/subagents-orchestration-guide/references/review-resolution.md index 9720d26..09f6bae 100644 --- a/skills/subagents-orchestration-guide/references/review-resolution.md +++ b/skills/subagents-orchestration-guide/references/review-resolution.md @@ -36,7 +36,7 @@ The orchestrator records one disposition for every actionable finding: | `apply` | Leaving the current deliverable unchanged would prevent the confirmed outcome, violate a binding requirement, design decision, or repository rule, leave required correctness or verification unsupported, or commit downstream work to added design surface whose total complexity lacks current evidence. Otherwise, apply only when the material effect exceeds the response cost. | | `decline` | No material effect is established; the finding is outside the agreed boundary above or the reviewer's declared artifact boundary, or reverses an exclusion; or the response cost equals or exceeds the material effect. | -A confirmed security risk, implementation divergence, or governing-source contradiction receives `apply` when correction preserves the confirmed value boundaries; cost alone leaves that classification unchanged. Technical design, contract, or implementation changes are correction work rather than user decisions when those boundaries remain true. +A confirmed exploitable gap in a relied-upon trust boundary, implementation divergence, or governing-source contradiction receives `apply` when correction preserves the confirmed value boundaries; cost alone leaves that classification unchanged. Technical design, contract, or implementation changes are correction work rather than user decisions when those boundaries remain true. For each finding record: