diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 347ff25d..91033802 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.2", + "version": "0.29.3", "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.2", + "version": "0.29.3", "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.2", + "version": "0.29.3", "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.2", + "version": "0.29.3", "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/document-reviewer.md b/agents/document-reviewer.md index 5f39881d..60e1ada0 100644 --- a/agents/document-reviewer.md +++ b/agents/document-reviewer.md @@ -84,7 +84,7 @@ Verify current external facts from authoritative sources only when an ADR select - Applicable standards and repository checks retain source evidence and adoption decisions. - Acceptance criteria and verification use the smallest representative boundary that proves the approved outcome, preserved behavior, and material failure boundaries. The early verification point is executable. - Each AC states observable behavior, and performance, live-external, and exact-visual ACs carry the sourced requirement and reproducible proof required by the Acceptance Criteria section of `references/design-template.md` in the documentation-criteria skill. -- Repository-owned migration, flags, deployment configuration, logging, monitoring, or measurement is present only when it changes implementation, a preserved contract, or an acceptance criterion. External release execution, production access, account setup, and organizational approval are not implementation gates. +- Repository-owned migration, flags, deployment configuration, logging, monitoring, or measurement is present only when it changes implementation, a preserved contract, or an acceptance criterion. External release execution, production access, account setup, and organizational approval are absent from the Design Doc. - Reverse-engineered/as-is documents describe observed code with evidence and are exempt from future-state convergence and design-choice requirements. ### Work Plan @@ -105,7 +105,7 @@ Create an issue only when the artifact otherwise: - leaves a required result non-verifiable; or - commits downstream implementation to added design surface whose total complexity lacks current evidence and whose removal still satisfies the confirmed outcome, boundaries, and required proof. -Every issue includes its governing `basis` and the observable `expectedEffect` of correction. Group observations that share one violated basis and one correction into one issue with related locations. Omit scope additions, optional hardening, external operations, extra Product Context, duplicate proof, stylistic completeness, and template-only omissions from the review result. +Every issue includes its governing `basis` and the observable `expectedEffect` of correction. Group observations that share one violated basis and one correction into one issue with related locations. Omit scope additions, optional hardening, extra Product Context, duplicate proof, stylistic completeness, and template-only omissions from the review result. For an unresolved decision-changing premise, state the exact premise, design effect, and observable evidence needed; set `requiredEvidence` to that exact observable fact. Use `null` for other issues. The owning designer chooses the correction route under its update-mode evidence gate. diff --git a/agents/technical-designer-frontend.md b/agents/technical-designer-frontend.md index b700db96..e4aa15df 100644 --- a/agents/technical-designer-frontend.md +++ b/agents/technical-designer-frontend.md @@ -80,7 +80,7 @@ Follow `references/design-template.md` in the documentation-criteria skill. Pres Sections and rows activate when their boundary exists. An authoritative referenced UI Spec or Design Doc may carry the information; every included state, browser lane, asset, and check is supported by the current scope or preserved behavior. -Use diagrams only when they clarify a material component, state, or interaction relationship. Repository-owned flags, generated assets, deployment configuration, logging, monitoring, or measurement belong only when they change checked-in implementation, a preserved contract, or an acceptance criterion. External release execution, production access, account setup, and organizational approval are context. +Use diagrams only when they clarify a material component, state, or interaction relationship. Repository-owned flags, generated assets, deployment configuration, logging, monitoring, or measurement belong only when they change checked-in implementation, a preserved contract, or an acceptance criterion. External release execution, production access, account setup, and organizational approval stay outside the Design Doc. Acceptance criteria use the smallest representative set that proves the approved user-visible outcome and material failure states. Verification uses the narrowest applicable boundary. diff --git a/agents/technical-designer.md b/agents/technical-designer.md index 4fc6ccba..84b7bd23 100644 --- a/agents/technical-designer.md +++ b/agents/technical-designer.md @@ -86,7 +86,7 @@ Follow `references/design-template.md` in the documentation-criteria skill. Pres Sections and rows activate when their boundary exists. An authoritative referenced artifact may carry the information; every included section contains decision-, implementation-, or verification-relevant content. -Use diagrams only when they make a material relationship easier to judge than prose or a compact table. Repository-owned migration, feature-flag, deployment configuration, logging, monitoring, or measurement belongs in the design only when it changes checked-in implementation, a preserved contract, or an acceptance criterion. External release execution, production access, account setup, and organizational approval are context rather than implementation tasks. +Use diagrams only when they make a material relationship easier to judge than prose or a compact table. Repository-owned migration, feature-flag, deployment configuration, logging, monitoring, or measurement belongs in the design only when it changes checked-in implementation, a preserved contract, or an acceptance criterion. External release execution, production access, account setup, and organizational approval stay outside the Design Doc. Acceptance criteria use the smallest representative set that proves the confirmed outcome and material failure boundaries. Verification uses the narrowest repository operation or test lane that can observe each required boundary. diff --git a/dev-skills/.claude-plugin/plugin.json b/dev-skills/.claude-plugin/plugin.json index 9a920545..a14d0cb7 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.2", + "version": "0.29.3", "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 40ad1f5a..1e6f67ac 100644 --- a/dev-skills/skills/documentation-criteria/SKILL.md +++ b/dev-skills/skills/documentation-criteria/SKILL.md @@ -17,7 +17,7 @@ Each document fixes one class of decision that the repository alone cannot suppl - **UI Spec** — Records screen structure, transitions, component/state contracts, and visual acceptance before components exist, so decomposition is decided before implementation instead of per-component during it. Create one when those decisions remain open; reuse an approved UI Spec or go straight to the Design Doc when one evident repository-supported pattern already determines them. Technical implementation and API contracts belong to the Design Doc. -- **Design Doc** — Records the complete implementation design for the confirmed scope: flows, contracts, change impact, and verification strategy. Task execution treats it as the primary technical baseline, so implementation does not silently invent missing How. When repository evidence invalidates technical How while confirmed outcome, desired-future requirements, and non-goals remain true, correct the implementation and the affected technical artifact through their owning workflow without reopening product requirements. Technology selection rationale belongs to an ADR, schedule and assignments to the Work Plan. +- **Design Doc** — Records the complete implementation design for the confirmed scope: flows, contracts, change impact, and verification strategy. Task execution treats it as the primary technical baseline, so implementation does not silently invent missing How. The same baseline turns anything written in it into planned and implemented work, so release execution, production operation, and other work outside the repository change stay out of it; a confirmed requirement that describes such work is met by designing the capability it uses. When repository evidence invalidates technical How while confirmed outcome, desired-future requirements, and non-goals remain true, correct the implementation and the affected technical artifact through their owning workflow without reopening product requirements. Technology selection rationale belongs to an ADR, schedule and assignments to the Work Plan. - **Work Plan** — Fixes task order, dependencies, executable verification, and the earliest vertical proof point. Without it task order follows file layout rather than dependency, and integration risk moves to the end of the work. Design detail is referenced from the Design Doc rather than restated. diff --git a/dev-skills/skills/documentation-criteria/references/design-template.md b/dev-skills/skills/documentation-criteria/references/design-template.md index 70c8de97..9172e426 100644 --- a/dev-skills/skills/documentation-criteria/references/design-template.md +++ b/dev-skills/skills/documentation-criteria/references/design-template.md @@ -341,8 +341,8 @@ Verification Strategy defines what correctness means and how to prove it at desi ### Correctness Proof Method -- **Correctness definition**: [What "correct" means for this change — e.g., "output matches existing behavior", "all ACs pass in production-equivalent environment", "generated queries execute without error on target DB"] -- **Verification method**: [Specific technique — e.g., "compare new implementation output against existing implementation", "run against staging DB", "contract test with real API"] +- **Correctness definition**: [What "correct" means for this change — e.g., "output matches existing behavior", "generated queries execute without error on target DB"] +- **Verification method**: [Specific technique — e.g., "compare new implementation output against existing implementation", "contract test with real API"] - **Verification timing**: [When verification occurs — e.g., "after first vertical slice", "per repository", "at integration phase"] ### Early Verification Point @@ -371,7 +371,7 @@ Record boundaries needed by a current requirement, downstream implementation, or ## Risks and Mitigation -Include only evidenced residual risks that can change rollout, rollback, contract handling, or verification strategy while leaving the Selected Design valid. +Include only evidenced residual risks that can change rollback, contract handling, or verification strategy while leaving the Selected Design valid. | Risk | Impact | Probability | Mitigation | |------|--------|-------------|------------| diff --git a/dev-workflows-frontend/.claude-plugin/plugin.json b/dev-workflows-frontend/.claude-plugin/plugin.json index 13263539..9c92a738 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.2", + "version": "0.29.3", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows-frontend/agents/document-reviewer.md b/dev-workflows-frontend/agents/document-reviewer.md index 5f39881d..60e1ada0 100644 --- a/dev-workflows-frontend/agents/document-reviewer.md +++ b/dev-workflows-frontend/agents/document-reviewer.md @@ -84,7 +84,7 @@ Verify current external facts from authoritative sources only when an ADR select - Applicable standards and repository checks retain source evidence and adoption decisions. - Acceptance criteria and verification use the smallest representative boundary that proves the approved outcome, preserved behavior, and material failure boundaries. The early verification point is executable. - Each AC states observable behavior, and performance, live-external, and exact-visual ACs carry the sourced requirement and reproducible proof required by the Acceptance Criteria section of `references/design-template.md` in the documentation-criteria skill. -- Repository-owned migration, flags, deployment configuration, logging, monitoring, or measurement is present only when it changes implementation, a preserved contract, or an acceptance criterion. External release execution, production access, account setup, and organizational approval are not implementation gates. +- Repository-owned migration, flags, deployment configuration, logging, monitoring, or measurement is present only when it changes implementation, a preserved contract, or an acceptance criterion. External release execution, production access, account setup, and organizational approval are absent from the Design Doc. - Reverse-engineered/as-is documents describe observed code with evidence and are exempt from future-state convergence and design-choice requirements. ### Work Plan @@ -105,7 +105,7 @@ Create an issue only when the artifact otherwise: - leaves a required result non-verifiable; or - commits downstream implementation to added design surface whose total complexity lacks current evidence and whose removal still satisfies the confirmed outcome, boundaries, and required proof. -Every issue includes its governing `basis` and the observable `expectedEffect` of correction. Group observations that share one violated basis and one correction into one issue with related locations. Omit scope additions, optional hardening, external operations, extra Product Context, duplicate proof, stylistic completeness, and template-only omissions from the review result. +Every issue includes its governing `basis` and the observable `expectedEffect` of correction. Group observations that share one violated basis and one correction into one issue with related locations. Omit scope additions, optional hardening, extra Product Context, duplicate proof, stylistic completeness, and template-only omissions from the review result. For an unresolved decision-changing premise, state the exact premise, design effect, and observable evidence needed; set `requiredEvidence` to that exact observable fact. Use `null` for other issues. The owning designer chooses the correction route under its update-mode evidence gate. diff --git a/dev-workflows-frontend/agents/technical-designer-frontend.md b/dev-workflows-frontend/agents/technical-designer-frontend.md index b700db96..e4aa15df 100644 --- a/dev-workflows-frontend/agents/technical-designer-frontend.md +++ b/dev-workflows-frontend/agents/technical-designer-frontend.md @@ -80,7 +80,7 @@ Follow `references/design-template.md` in the documentation-criteria skill. Pres Sections and rows activate when their boundary exists. An authoritative referenced UI Spec or Design Doc may carry the information; every included state, browser lane, asset, and check is supported by the current scope or preserved behavior. -Use diagrams only when they clarify a material component, state, or interaction relationship. Repository-owned flags, generated assets, deployment configuration, logging, monitoring, or measurement belong only when they change checked-in implementation, a preserved contract, or an acceptance criterion. External release execution, production access, account setup, and organizational approval are context. +Use diagrams only when they clarify a material component, state, or interaction relationship. Repository-owned flags, generated assets, deployment configuration, logging, monitoring, or measurement belong only when they change checked-in implementation, a preserved contract, or an acceptance criterion. External release execution, production access, account setup, and organizational approval stay outside the Design Doc. Acceptance criteria use the smallest representative set that proves the approved user-visible outcome and material failure states. Verification uses the narrowest applicable boundary. diff --git a/dev-workflows-frontend/skills/documentation-criteria/SKILL.md b/dev-workflows-frontend/skills/documentation-criteria/SKILL.md index 40ad1f5a..1e6f67ac 100644 --- a/dev-workflows-frontend/skills/documentation-criteria/SKILL.md +++ b/dev-workflows-frontend/skills/documentation-criteria/SKILL.md @@ -17,7 +17,7 @@ Each document fixes one class of decision that the repository alone cannot suppl - **UI Spec** — Records screen structure, transitions, component/state contracts, and visual acceptance before components exist, so decomposition is decided before implementation instead of per-component during it. Create one when those decisions remain open; reuse an approved UI Spec or go straight to the Design Doc when one evident repository-supported pattern already determines them. Technical implementation and API contracts belong to the Design Doc. -- **Design Doc** — Records the complete implementation design for the confirmed scope: flows, contracts, change impact, and verification strategy. Task execution treats it as the primary technical baseline, so implementation does not silently invent missing How. When repository evidence invalidates technical How while confirmed outcome, desired-future requirements, and non-goals remain true, correct the implementation and the affected technical artifact through their owning workflow without reopening product requirements. Technology selection rationale belongs to an ADR, schedule and assignments to the Work Plan. +- **Design Doc** — Records the complete implementation design for the confirmed scope: flows, contracts, change impact, and verification strategy. Task execution treats it as the primary technical baseline, so implementation does not silently invent missing How. The same baseline turns anything written in it into planned and implemented work, so release execution, production operation, and other work outside the repository change stay out of it; a confirmed requirement that describes such work is met by designing the capability it uses. When repository evidence invalidates technical How while confirmed outcome, desired-future requirements, and non-goals remain true, correct the implementation and the affected technical artifact through their owning workflow without reopening product requirements. Technology selection rationale belongs to an ADR, schedule and assignments to the Work Plan. - **Work Plan** — Fixes task order, dependencies, executable verification, and the earliest vertical proof point. Without it task order follows file layout rather than dependency, and integration risk moves to the end of the work. Design detail is referenced from the Design Doc rather than restated. 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 70c8de97..9172e426 100644 --- a/dev-workflows-frontend/skills/documentation-criteria/references/design-template.md +++ b/dev-workflows-frontend/skills/documentation-criteria/references/design-template.md @@ -341,8 +341,8 @@ Verification Strategy defines what correctness means and how to prove it at desi ### Correctness Proof Method -- **Correctness definition**: [What "correct" means for this change — e.g., "output matches existing behavior", "all ACs pass in production-equivalent environment", "generated queries execute without error on target DB"] -- **Verification method**: [Specific technique — e.g., "compare new implementation output against existing implementation", "run against staging DB", "contract test with real API"] +- **Correctness definition**: [What "correct" means for this change — e.g., "output matches existing behavior", "generated queries execute without error on target DB"] +- **Verification method**: [Specific technique — e.g., "compare new implementation output against existing implementation", "contract test with real API"] - **Verification timing**: [When verification occurs — e.g., "after first vertical slice", "per repository", "at integration phase"] ### Early Verification Point @@ -371,7 +371,7 @@ Record boundaries needed by a current requirement, downstream implementation, or ## Risks and Mitigation -Include only evidenced residual risks that can change rollout, rollback, contract handling, or verification strategy while leaving the Selected Design valid. +Include only evidenced residual risks that can change rollback, contract handling, or verification strategy while leaving the Selected Design valid. | Risk | Impact | Probability | Mitigation | |------|--------|-------------|------------| diff --git a/dev-workflows-frontend/skills/recipe-front-design/SKILL.md b/dev-workflows-frontend/skills/recipe-front-design/SKILL.md index 9cc6eafb..fdab87bf 100644 --- a/dev-workflows-frontend/skills/recipe-front-design/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-front-design/SKILL.md @@ -143,7 +143,7 @@ Invoke `dev-workflows-frontend:code-verifier` with `doc_type: design-doc` and `d Invoke `dev-workflows-frontend:document-reviewer` with exact inputs: `doc_type: DesignDoc`; `target` as the returned Design Doc path unchanged; `review_context: creation`; original user requirements unchanged as `requirements_verbatim`; the Step 1 `confirmed_requirement_context` unchanged; the same unchanged `codebase_analysis` and optional `ui_analysis` supplied to the designer; and Step 8 `verification_evidence` unchanged. The reviewer follows an applicable UI Spec and accepted ADR paths cited by the Design Doc only when they can change an in-scope finding. - `pass`: continue. -- `needs_revision`: apply Review Resolution, update through a fresh technical-designer-frontend invocation using the existing path and complete applied findings, and rerun verification/review for the affected boundary. +- `needs_revision`: apply Review Resolution, update through a fresh technical-designer-frontend invocation using the existing path and complete applied findings, then re-review with `prior_feedback`. - `rejected`: resolve technical governing-source conflicts through Review Resolution; ask the user only when confirmed outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes. Invoke `dev-workflows-frontend:design-sync` with `source_design` as the returned Design Doc path unchanged, apply Review Resolution to actionable conflicts, and report `SKIPPED` distinctly when only one Design Doc exists. diff --git a/dev-workflows-frontend/skills/recipe-update-doc/SKILL.md b/dev-workflows-frontend/skills/recipe-update-doc/SKILL.md index 19d5d244..f3ebc49c 100644 --- a/dev-workflows-frontend/skills/recipe-update-doc/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-update-doc/SKILL.md @@ -148,7 +148,7 @@ For each type, review consistency of the changed sections and their dependent st **On review result**: - Pass → Proceed to Step 6 -- Needs revision → Apply the Review Resolution Gate. Return to Step 4 when `apply` findings exist, using the following prompt: +- Needs revision → Apply the Review Resolution Gate. When `apply` findings exist, invoke the update agent with the following prompt, then re-run document-reviewer: ``` subagent_type: [Update Agent from Step 2] description: "Revise [Type from Step 2]" diff --git a/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md index 3303e4f7..77c4b778 100644 --- a/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md @@ -289,7 +289,7 @@ Before post-implementation verifiers, collect retained verification limitations ### HC-04: code-verifier + codebase-analyzer → document-reviewer - Keep verifier discrepancies unchanged so correction and review remain traceable to observed evidence rather than orchestrator-authored design instructions. -- Apply Review Resolution and rerun verification after every applied correction, passing the previous complete verifier result, dispositions, and correction diff or paths as `prior_feedback`. Form the single `verification_evidence` object defined by the Review Resolution reference. +- Apply Review Resolution and rerun verification after every correction applied from code-verifier findings, passing the previous complete verifier result, dispositions, and correction diff or paths as `prior_feedback`. Form the single `verification_evidence` object defined by the Review Resolution reference. - Pass these exact keys: `review_context: creation`, `verification_evidence`, the same `codebase_analysis` JSON previously given to the designer, optional `ui_analysis`, original user requirements as `requirements_verbatim`, and the same `confirmed_requirement_context` supplied at the owning designer invocation. - Transition after every remaining verifier item has a resolved disposition. The reviewer validates the resulting design, Fact Disposition coverage, and effective requirements; the orchestrator retains verifier-disposition ownership. 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 078058c3..9720d261 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 @@ -70,7 +70,7 @@ The correction assessment covers exactly every received item. The reviewer compl Derive the correction re-review status or verdict only from these reconciliation entries. An independent factual verifier may repeat an observed discrepancy; the orchestrator assigns its disposition from governing evidence. -For a bounded verifier, rerun after at least one correction is applied from its latest result or when the caller's re-run rule identifies a direct change to its declared boundary. Pass the previous complete result, dispositions, and correction diff or paths. The returned result replaces corrected items and carries unaffected evidence forward. Match materially identical findings by their claim or conflict and cited source and target evidence rather than a regenerated positional ID. A new finding enters routing only when its evidence links it causally to the correction or code-verifier’s required full inventory accounting establishes a current omission. +For a bounded verifier, rerun after at least one correction is applied from its latest result. Pass the previous complete result, dispositions, and correction diff or paths. The returned result replaces corrected items and carries unaffected evidence forward. Match materially identical findings by their claim or conflict and cited source and target evidence rather than a regenerated positional ID. A new finding enters routing only when its evidence links it causally to the correction or code-verifier’s required full inventory accounting establishes a current omission. ## 3. Converge or Report diff --git a/dev-workflows-fullstack/.claude-plugin/plugin.json b/dev-workflows-fullstack/.claude-plugin/plugin.json index fb624be1..2b74dd75 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.2", + "version": "0.29.3", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows-fullstack/agents/document-reviewer.md b/dev-workflows-fullstack/agents/document-reviewer.md index 5f39881d..60e1ada0 100644 --- a/dev-workflows-fullstack/agents/document-reviewer.md +++ b/dev-workflows-fullstack/agents/document-reviewer.md @@ -84,7 +84,7 @@ Verify current external facts from authoritative sources only when an ADR select - Applicable standards and repository checks retain source evidence and adoption decisions. - Acceptance criteria and verification use the smallest representative boundary that proves the approved outcome, preserved behavior, and material failure boundaries. The early verification point is executable. - Each AC states observable behavior, and performance, live-external, and exact-visual ACs carry the sourced requirement and reproducible proof required by the Acceptance Criteria section of `references/design-template.md` in the documentation-criteria skill. -- Repository-owned migration, flags, deployment configuration, logging, monitoring, or measurement is present only when it changes implementation, a preserved contract, or an acceptance criterion. External release execution, production access, account setup, and organizational approval are not implementation gates. +- Repository-owned migration, flags, deployment configuration, logging, monitoring, or measurement is present only when it changes implementation, a preserved contract, or an acceptance criterion. External release execution, production access, account setup, and organizational approval are absent from the Design Doc. - Reverse-engineered/as-is documents describe observed code with evidence and are exempt from future-state convergence and design-choice requirements. ### Work Plan @@ -105,7 +105,7 @@ Create an issue only when the artifact otherwise: - leaves a required result non-verifiable; or - commits downstream implementation to added design surface whose total complexity lacks current evidence and whose removal still satisfies the confirmed outcome, boundaries, and required proof. -Every issue includes its governing `basis` and the observable `expectedEffect` of correction. Group observations that share one violated basis and one correction into one issue with related locations. Omit scope additions, optional hardening, external operations, extra Product Context, duplicate proof, stylistic completeness, and template-only omissions from the review result. +Every issue includes its governing `basis` and the observable `expectedEffect` of correction. Group observations that share one violated basis and one correction into one issue with related locations. Omit scope additions, optional hardening, extra Product Context, duplicate proof, stylistic completeness, and template-only omissions from the review result. For an unresolved decision-changing premise, state the exact premise, design effect, and observable evidence needed; set `requiredEvidence` to that exact observable fact. Use `null` for other issues. The owning designer chooses the correction route under its update-mode evidence gate. diff --git a/dev-workflows-fullstack/agents/technical-designer-frontend.md b/dev-workflows-fullstack/agents/technical-designer-frontend.md index b700db96..e4aa15df 100644 --- a/dev-workflows-fullstack/agents/technical-designer-frontend.md +++ b/dev-workflows-fullstack/agents/technical-designer-frontend.md @@ -80,7 +80,7 @@ Follow `references/design-template.md` in the documentation-criteria skill. Pres Sections and rows activate when their boundary exists. An authoritative referenced UI Spec or Design Doc may carry the information; every included state, browser lane, asset, and check is supported by the current scope or preserved behavior. -Use diagrams only when they clarify a material component, state, or interaction relationship. Repository-owned flags, generated assets, deployment configuration, logging, monitoring, or measurement belong only when they change checked-in implementation, a preserved contract, or an acceptance criterion. External release execution, production access, account setup, and organizational approval are context. +Use diagrams only when they clarify a material component, state, or interaction relationship. Repository-owned flags, generated assets, deployment configuration, logging, monitoring, or measurement belong only when they change checked-in implementation, a preserved contract, or an acceptance criterion. External release execution, production access, account setup, and organizational approval stay outside the Design Doc. Acceptance criteria use the smallest representative set that proves the approved user-visible outcome and material failure states. Verification uses the narrowest applicable boundary. diff --git a/dev-workflows-fullstack/agents/technical-designer.md b/dev-workflows-fullstack/agents/technical-designer.md index 4fc6ccba..84b7bd23 100644 --- a/dev-workflows-fullstack/agents/technical-designer.md +++ b/dev-workflows-fullstack/agents/technical-designer.md @@ -86,7 +86,7 @@ Follow `references/design-template.md` in the documentation-criteria skill. Pres Sections and rows activate when their boundary exists. An authoritative referenced artifact may carry the information; every included section contains decision-, implementation-, or verification-relevant content. -Use diagrams only when they make a material relationship easier to judge than prose or a compact table. Repository-owned migration, feature-flag, deployment configuration, logging, monitoring, or measurement belongs in the design only when it changes checked-in implementation, a preserved contract, or an acceptance criterion. External release execution, production access, account setup, and organizational approval are context rather than implementation tasks. +Use diagrams only when they make a material relationship easier to judge than prose or a compact table. Repository-owned migration, feature-flag, deployment configuration, logging, monitoring, or measurement belongs in the design only when it changes checked-in implementation, a preserved contract, or an acceptance criterion. External release execution, production access, account setup, and organizational approval stay outside the Design Doc. Acceptance criteria use the smallest representative set that proves the confirmed outcome and material failure boundaries. Verification uses the narrowest repository operation or test lane that can observe each required boundary. diff --git a/dev-workflows-fullstack/skills/documentation-criteria/SKILL.md b/dev-workflows-fullstack/skills/documentation-criteria/SKILL.md index 40ad1f5a..1e6f67ac 100644 --- a/dev-workflows-fullstack/skills/documentation-criteria/SKILL.md +++ b/dev-workflows-fullstack/skills/documentation-criteria/SKILL.md @@ -17,7 +17,7 @@ Each document fixes one class of decision that the repository alone cannot suppl - **UI Spec** — Records screen structure, transitions, component/state contracts, and visual acceptance before components exist, so decomposition is decided before implementation instead of per-component during it. Create one when those decisions remain open; reuse an approved UI Spec or go straight to the Design Doc when one evident repository-supported pattern already determines them. Technical implementation and API contracts belong to the Design Doc. -- **Design Doc** — Records the complete implementation design for the confirmed scope: flows, contracts, change impact, and verification strategy. Task execution treats it as the primary technical baseline, so implementation does not silently invent missing How. When repository evidence invalidates technical How while confirmed outcome, desired-future requirements, and non-goals remain true, correct the implementation and the affected technical artifact through their owning workflow without reopening product requirements. Technology selection rationale belongs to an ADR, schedule and assignments to the Work Plan. +- **Design Doc** — Records the complete implementation design for the confirmed scope: flows, contracts, change impact, and verification strategy. Task execution treats it as the primary technical baseline, so implementation does not silently invent missing How. The same baseline turns anything written in it into planned and implemented work, so release execution, production operation, and other work outside the repository change stay out of it; a confirmed requirement that describes such work is met by designing the capability it uses. When repository evidence invalidates technical How while confirmed outcome, desired-future requirements, and non-goals remain true, correct the implementation and the affected technical artifact through their owning workflow without reopening product requirements. Technology selection rationale belongs to an ADR, schedule and assignments to the Work Plan. - **Work Plan** — Fixes task order, dependencies, executable verification, and the earliest vertical proof point. Without it task order follows file layout rather than dependency, and integration risk moves to the end of the work. Design detail is referenced from the Design Doc rather than restated. 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 70c8de97..9172e426 100644 --- a/dev-workflows-fullstack/skills/documentation-criteria/references/design-template.md +++ b/dev-workflows-fullstack/skills/documentation-criteria/references/design-template.md @@ -341,8 +341,8 @@ Verification Strategy defines what correctness means and how to prove it at desi ### Correctness Proof Method -- **Correctness definition**: [What "correct" means for this change — e.g., "output matches existing behavior", "all ACs pass in production-equivalent environment", "generated queries execute without error on target DB"] -- **Verification method**: [Specific technique — e.g., "compare new implementation output against existing implementation", "run against staging DB", "contract test with real API"] +- **Correctness definition**: [What "correct" means for this change — e.g., "output matches existing behavior", "generated queries execute without error on target DB"] +- **Verification method**: [Specific technique — e.g., "compare new implementation output against existing implementation", "contract test with real API"] - **Verification timing**: [When verification occurs — e.g., "after first vertical slice", "per repository", "at integration phase"] ### Early Verification Point @@ -371,7 +371,7 @@ Record boundaries needed by a current requirement, downstream implementation, or ## Risks and Mitigation -Include only evidenced residual risks that can change rollout, rollback, contract handling, or verification strategy while leaving the Selected Design valid. +Include only evidenced residual risks that can change rollback, contract handling, or verification strategy while leaving the Selected Design valid. | Risk | Impact | Probability | Mitigation | |------|--------|-------------|------------| diff --git a/dev-workflows-fullstack/skills/recipe-design/SKILL.md b/dev-workflows-fullstack/skills/recipe-design/SKILL.md index e51b2ec8..9a963ef3 100644 --- a/dev-workflows-fullstack/skills/recipe-design/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-design/SKILL.md @@ -115,7 +115,7 @@ Apply Review Resolution to every discrepancy before document review. Send only ` Invoke `dev-workflows-fullstack:document-reviewer` with exact inputs: `doc_type: DesignDoc`, `target`, `review_context: creation`, the original user requirements verbatim as `requirements_verbatim`, `confirmed_requirement_context`, `codebase_analysis`, and `verification_evidence` from Step 6. - `pass`: continue. -- `needs_revision`: apply Review Resolution, update through a fresh technical-designer invocation using the existing path and complete applied findings, then rerun Steps 6-7 for the affected boundary. +- `needs_revision`: apply Review Resolution, update through a fresh technical-designer invocation using the existing path and complete applied findings, then re-review with `prior_feedback`. - `rejected`: resolve technical governing-source conflicts through Review Resolution; ask the user only when confirmed outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes. Invoke `dev-workflows-fullstack:design-sync` for consistency with other Design Docs and apply Review Resolution to actionable conflicts. Report `SKIPPED` distinctly when only one Design Doc exists. diff --git a/dev-workflows-fullstack/skills/recipe-front-design/SKILL.md b/dev-workflows-fullstack/skills/recipe-front-design/SKILL.md index 22f628a4..7b86692e 100644 --- a/dev-workflows-fullstack/skills/recipe-front-design/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-front-design/SKILL.md @@ -143,7 +143,7 @@ Invoke `dev-workflows-fullstack:code-verifier` with `doc_type: design-doc` and ` Invoke `dev-workflows-fullstack:document-reviewer` with exact inputs: `doc_type: DesignDoc`; `target` as the returned Design Doc path unchanged; `review_context: creation`; original user requirements unchanged as `requirements_verbatim`; the Step 1 `confirmed_requirement_context` unchanged; the same unchanged `codebase_analysis` and optional `ui_analysis` supplied to the designer; and Step 8 `verification_evidence` unchanged. The reviewer follows an applicable UI Spec and accepted ADR paths cited by the Design Doc only when they can change an in-scope finding. - `pass`: continue. -- `needs_revision`: apply Review Resolution, update through a fresh technical-designer-frontend invocation using the existing path and complete applied findings, and rerun verification/review for the affected boundary. +- `needs_revision`: apply Review Resolution, update through a fresh technical-designer-frontend invocation using the existing path and complete applied findings, then re-review with `prior_feedback`. - `rejected`: resolve technical governing-source conflicts through Review Resolution; ask the user only when confirmed outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes. Invoke `dev-workflows-fullstack:design-sync` with `source_design` as the returned Design Doc path unchanged, apply Review Resolution to actionable conflicts, and report `SKIPPED` distinctly when only one Design Doc exists. diff --git a/dev-workflows-fullstack/skills/recipe-update-doc/SKILL.md b/dev-workflows-fullstack/skills/recipe-update-doc/SKILL.md index 19d5d244..f3ebc49c 100644 --- a/dev-workflows-fullstack/skills/recipe-update-doc/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-update-doc/SKILL.md @@ -148,7 +148,7 @@ For each type, review consistency of the changed sections and their dependent st **On review result**: - Pass → Proceed to Step 6 -- Needs revision → Apply the Review Resolution Gate. Return to Step 4 when `apply` findings exist, using the following prompt: +- Needs revision → Apply the Review Resolution Gate. When `apply` findings exist, invoke the update agent with the following prompt, then re-run document-reviewer: ``` subagent_type: [Update Agent from Step 2] description: "Revise [Type from Step 2]" diff --git a/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md index 3303e4f7..77c4b778 100644 --- a/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md @@ -289,7 +289,7 @@ Before post-implementation verifiers, collect retained verification limitations ### HC-04: code-verifier + codebase-analyzer → document-reviewer - Keep verifier discrepancies unchanged so correction and review remain traceable to observed evidence rather than orchestrator-authored design instructions. -- Apply Review Resolution and rerun verification after every applied correction, passing the previous complete verifier result, dispositions, and correction diff or paths as `prior_feedback`. Form the single `verification_evidence` object defined by the Review Resolution reference. +- Apply Review Resolution and rerun verification after every correction applied from code-verifier findings, passing the previous complete verifier result, dispositions, and correction diff or paths as `prior_feedback`. Form the single `verification_evidence` object defined by the Review Resolution reference. - Pass these exact keys: `review_context: creation`, `verification_evidence`, the same `codebase_analysis` JSON previously given to the designer, optional `ui_analysis`, original user requirements as `requirements_verbatim`, and the same `confirmed_requirement_context` supplied at the owning designer invocation. - Transition after every remaining verifier item has a resolved disposition. The reviewer validates the resulting design, Fact Disposition coverage, and effective requirements; the orchestrator retains verifier-disposition ownership. 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 078058c3..9720d261 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 @@ -70,7 +70,7 @@ The correction assessment covers exactly every received item. The reviewer compl Derive the correction re-review status or verdict only from these reconciliation entries. An independent factual verifier may repeat an observed discrepancy; the orchestrator assigns its disposition from governing evidence. -For a bounded verifier, rerun after at least one correction is applied from its latest result or when the caller's re-run rule identifies a direct change to its declared boundary. Pass the previous complete result, dispositions, and correction diff or paths. The returned result replaces corrected items and carries unaffected evidence forward. Match materially identical findings by their claim or conflict and cited source and target evidence rather than a regenerated positional ID. A new finding enters routing only when its evidence links it causally to the correction or code-verifier’s required full inventory accounting establishes a current omission. +For a bounded verifier, rerun after at least one correction is applied from its latest result. Pass the previous complete result, dispositions, and correction diff or paths. The returned result replaces corrected items and carries unaffected evidence forward. Match materially identical findings by their claim or conflict and cited source and target evidence rather than a regenerated positional ID. A new finding enters routing only when its evidence links it causally to the correction or code-verifier’s required full inventory accounting establishes a current omission. ## 3. Converge or Report diff --git a/dev-workflows/.claude-plugin/plugin.json b/dev-workflows/.claude-plugin/plugin.json index 97f69de4..c6de3cd8 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.2", + "version": "0.29.3", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows/agents/document-reviewer.md b/dev-workflows/agents/document-reviewer.md index 5f39881d..60e1ada0 100644 --- a/dev-workflows/agents/document-reviewer.md +++ b/dev-workflows/agents/document-reviewer.md @@ -84,7 +84,7 @@ Verify current external facts from authoritative sources only when an ADR select - Applicable standards and repository checks retain source evidence and adoption decisions. - Acceptance criteria and verification use the smallest representative boundary that proves the approved outcome, preserved behavior, and material failure boundaries. The early verification point is executable. - Each AC states observable behavior, and performance, live-external, and exact-visual ACs carry the sourced requirement and reproducible proof required by the Acceptance Criteria section of `references/design-template.md` in the documentation-criteria skill. -- Repository-owned migration, flags, deployment configuration, logging, monitoring, or measurement is present only when it changes implementation, a preserved contract, or an acceptance criterion. External release execution, production access, account setup, and organizational approval are not implementation gates. +- Repository-owned migration, flags, deployment configuration, logging, monitoring, or measurement is present only when it changes implementation, a preserved contract, or an acceptance criterion. External release execution, production access, account setup, and organizational approval are absent from the Design Doc. - Reverse-engineered/as-is documents describe observed code with evidence and are exempt from future-state convergence and design-choice requirements. ### Work Plan @@ -105,7 +105,7 @@ Create an issue only when the artifact otherwise: - leaves a required result non-verifiable; or - commits downstream implementation to added design surface whose total complexity lacks current evidence and whose removal still satisfies the confirmed outcome, boundaries, and required proof. -Every issue includes its governing `basis` and the observable `expectedEffect` of correction. Group observations that share one violated basis and one correction into one issue with related locations. Omit scope additions, optional hardening, external operations, extra Product Context, duplicate proof, stylistic completeness, and template-only omissions from the review result. +Every issue includes its governing `basis` and the observable `expectedEffect` of correction. Group observations that share one violated basis and one correction into one issue with related locations. Omit scope additions, optional hardening, extra Product Context, duplicate proof, stylistic completeness, and template-only omissions from the review result. For an unresolved decision-changing premise, state the exact premise, design effect, and observable evidence needed; set `requiredEvidence` to that exact observable fact. Use `null` for other issues. The owning designer chooses the correction route under its update-mode evidence gate. diff --git a/dev-workflows/agents/technical-designer.md b/dev-workflows/agents/technical-designer.md index 4fc6ccba..84b7bd23 100644 --- a/dev-workflows/agents/technical-designer.md +++ b/dev-workflows/agents/technical-designer.md @@ -86,7 +86,7 @@ Follow `references/design-template.md` in the documentation-criteria skill. Pres Sections and rows activate when their boundary exists. An authoritative referenced artifact may carry the information; every included section contains decision-, implementation-, or verification-relevant content. -Use diagrams only when they make a material relationship easier to judge than prose or a compact table. Repository-owned migration, feature-flag, deployment configuration, logging, monitoring, or measurement belongs in the design only when it changes checked-in implementation, a preserved contract, or an acceptance criterion. External release execution, production access, account setup, and organizational approval are context rather than implementation tasks. +Use diagrams only when they make a material relationship easier to judge than prose or a compact table. Repository-owned migration, feature-flag, deployment configuration, logging, monitoring, or measurement belongs in the design only when it changes checked-in implementation, a preserved contract, or an acceptance criterion. External release execution, production access, account setup, and organizational approval stay outside the Design Doc. Acceptance criteria use the smallest representative set that proves the confirmed outcome and material failure boundaries. Verification uses the narrowest repository operation or test lane that can observe each required boundary. diff --git a/dev-workflows/skills/documentation-criteria/SKILL.md b/dev-workflows/skills/documentation-criteria/SKILL.md index 40ad1f5a..1e6f67ac 100644 --- a/dev-workflows/skills/documentation-criteria/SKILL.md +++ b/dev-workflows/skills/documentation-criteria/SKILL.md @@ -17,7 +17,7 @@ Each document fixes one class of decision that the repository alone cannot suppl - **UI Spec** — Records screen structure, transitions, component/state contracts, and visual acceptance before components exist, so decomposition is decided before implementation instead of per-component during it. Create one when those decisions remain open; reuse an approved UI Spec or go straight to the Design Doc when one evident repository-supported pattern already determines them. Technical implementation and API contracts belong to the Design Doc. -- **Design Doc** — Records the complete implementation design for the confirmed scope: flows, contracts, change impact, and verification strategy. Task execution treats it as the primary technical baseline, so implementation does not silently invent missing How. When repository evidence invalidates technical How while confirmed outcome, desired-future requirements, and non-goals remain true, correct the implementation and the affected technical artifact through their owning workflow without reopening product requirements. Technology selection rationale belongs to an ADR, schedule and assignments to the Work Plan. +- **Design Doc** — Records the complete implementation design for the confirmed scope: flows, contracts, change impact, and verification strategy. Task execution treats it as the primary technical baseline, so implementation does not silently invent missing How. The same baseline turns anything written in it into planned and implemented work, so release execution, production operation, and other work outside the repository change stay out of it; a confirmed requirement that describes such work is met by designing the capability it uses. When repository evidence invalidates technical How while confirmed outcome, desired-future requirements, and non-goals remain true, correct the implementation and the affected technical artifact through their owning workflow without reopening product requirements. Technology selection rationale belongs to an ADR, schedule and assignments to the Work Plan. - **Work Plan** — Fixes task order, dependencies, executable verification, and the earliest vertical proof point. Without it task order follows file layout rather than dependency, and integration risk moves to the end of the work. Design detail is referenced from the Design Doc rather than restated. diff --git a/dev-workflows/skills/documentation-criteria/references/design-template.md b/dev-workflows/skills/documentation-criteria/references/design-template.md index 70c8de97..9172e426 100644 --- a/dev-workflows/skills/documentation-criteria/references/design-template.md +++ b/dev-workflows/skills/documentation-criteria/references/design-template.md @@ -341,8 +341,8 @@ Verification Strategy defines what correctness means and how to prove it at desi ### Correctness Proof Method -- **Correctness definition**: [What "correct" means for this change — e.g., "output matches existing behavior", "all ACs pass in production-equivalent environment", "generated queries execute without error on target DB"] -- **Verification method**: [Specific technique — e.g., "compare new implementation output against existing implementation", "run against staging DB", "contract test with real API"] +- **Correctness definition**: [What "correct" means for this change — e.g., "output matches existing behavior", "generated queries execute without error on target DB"] +- **Verification method**: [Specific technique — e.g., "compare new implementation output against existing implementation", "contract test with real API"] - **Verification timing**: [When verification occurs — e.g., "after first vertical slice", "per repository", "at integration phase"] ### Early Verification Point @@ -371,7 +371,7 @@ Record boundaries needed by a current requirement, downstream implementation, or ## Risks and Mitigation -Include only evidenced residual risks that can change rollout, rollback, contract handling, or verification strategy while leaving the Selected Design valid. +Include only evidenced residual risks that can change rollback, contract handling, or verification strategy while leaving the Selected Design valid. | Risk | Impact | Probability | Mitigation | |------|--------|-------------|------------| diff --git a/dev-workflows/skills/recipe-design/SKILL.md b/dev-workflows/skills/recipe-design/SKILL.md index 9c5d82f2..9deaeb71 100644 --- a/dev-workflows/skills/recipe-design/SKILL.md +++ b/dev-workflows/skills/recipe-design/SKILL.md @@ -115,7 +115,7 @@ Apply Review Resolution to every discrepancy before document review. Send only ` Invoke `dev-workflows:document-reviewer` with exact inputs: `doc_type: DesignDoc`, `target`, `review_context: creation`, the original user requirements verbatim as `requirements_verbatim`, `confirmed_requirement_context`, `codebase_analysis`, and `verification_evidence` from Step 6. - `pass`: continue. -- `needs_revision`: apply Review Resolution, update through a fresh technical-designer invocation using the existing path and complete applied findings, then rerun Steps 6-7 for the affected boundary. +- `needs_revision`: apply Review Resolution, update through a fresh technical-designer invocation using the existing path and complete applied findings, then re-review with `prior_feedback`. - `rejected`: resolve technical governing-source conflicts through Review Resolution; ask the user only when confirmed outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes. Invoke `dev-workflows:design-sync` for consistency with other Design Docs and apply Review Resolution to actionable conflicts. Report `SKIPPED` distinctly when only one Design Doc exists. diff --git a/dev-workflows/skills/recipe-update-doc/SKILL.md b/dev-workflows/skills/recipe-update-doc/SKILL.md index 19d5d244..f3ebc49c 100644 --- a/dev-workflows/skills/recipe-update-doc/SKILL.md +++ b/dev-workflows/skills/recipe-update-doc/SKILL.md @@ -148,7 +148,7 @@ For each type, review consistency of the changed sections and their dependent st **On review result**: - Pass → Proceed to Step 6 -- Needs revision → Apply the Review Resolution Gate. Return to Step 4 when `apply` findings exist, using the following prompt: +- Needs revision → Apply the Review Resolution Gate. When `apply` findings exist, invoke the update agent with the following prompt, then re-run document-reviewer: ``` subagent_type: [Update Agent from Step 2] description: "Revise [Type from Step 2]" diff --git a/dev-workflows/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows/skills/subagents-orchestration-guide/SKILL.md index 3303e4f7..77c4b778 100644 --- a/dev-workflows/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows/skills/subagents-orchestration-guide/SKILL.md @@ -289,7 +289,7 @@ Before post-implementation verifiers, collect retained verification limitations ### HC-04: code-verifier + codebase-analyzer → document-reviewer - Keep verifier discrepancies unchanged so correction and review remain traceable to observed evidence rather than orchestrator-authored design instructions. -- Apply Review Resolution and rerun verification after every applied correction, passing the previous complete verifier result, dispositions, and correction diff or paths as `prior_feedback`. Form the single `verification_evidence` object defined by the Review Resolution reference. +- Apply Review Resolution and rerun verification after every correction applied from code-verifier findings, passing the previous complete verifier result, dispositions, and correction diff or paths as `prior_feedback`. Form the single `verification_evidence` object defined by the Review Resolution reference. - Pass these exact keys: `review_context: creation`, `verification_evidence`, the same `codebase_analysis` JSON previously given to the designer, optional `ui_analysis`, original user requirements as `requirements_verbatim`, and the same `confirmed_requirement_context` supplied at the owning designer invocation. - Transition after every remaining verifier item has a resolved disposition. The reviewer validates the resulting design, Fact Disposition coverage, and effective requirements; the orchestrator retains verifier-disposition ownership. 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 078058c3..9720d261 100644 --- a/dev-workflows/skills/subagents-orchestration-guide/references/review-resolution.md +++ b/dev-workflows/skills/subagents-orchestration-guide/references/review-resolution.md @@ -70,7 +70,7 @@ The correction assessment covers exactly every received item. The reviewer compl Derive the correction re-review status or verdict only from these reconciliation entries. An independent factual verifier may repeat an observed discrepancy; the orchestrator assigns its disposition from governing evidence. -For a bounded verifier, rerun after at least one correction is applied from its latest result or when the caller's re-run rule identifies a direct change to its declared boundary. Pass the previous complete result, dispositions, and correction diff or paths. The returned result replaces corrected items and carries unaffected evidence forward. Match materially identical findings by their claim or conflict and cited source and target evidence rather than a regenerated positional ID. A new finding enters routing only when its evidence links it causally to the correction or code-verifier’s required full inventory accounting establishes a current omission. +For a bounded verifier, rerun after at least one correction is applied from its latest result. Pass the previous complete result, dispositions, and correction diff or paths. The returned result replaces corrected items and carries unaffected evidence forward. Match materially identical findings by their claim or conflict and cited source and target evidence rather than a regenerated positional ID. A new finding enters routing only when its evidence links it causally to the correction or code-verifier’s required full inventory accounting establishes a current omission. ## 3. Converge or Report diff --git a/package.json b/package.json index 332815a0..d4f02a12 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "claude-code-workflows", - "version": "0.29.2", + "version": "0.29.3", "private": true, "type": "module", "engines": { diff --git a/skills/documentation-criteria/SKILL.md b/skills/documentation-criteria/SKILL.md index 40ad1f5a..1e6f67ac 100644 --- a/skills/documentation-criteria/SKILL.md +++ b/skills/documentation-criteria/SKILL.md @@ -17,7 +17,7 @@ Each document fixes one class of decision that the repository alone cannot suppl - **UI Spec** — Records screen structure, transitions, component/state contracts, and visual acceptance before components exist, so decomposition is decided before implementation instead of per-component during it. Create one when those decisions remain open; reuse an approved UI Spec or go straight to the Design Doc when one evident repository-supported pattern already determines them. Technical implementation and API contracts belong to the Design Doc. -- **Design Doc** — Records the complete implementation design for the confirmed scope: flows, contracts, change impact, and verification strategy. Task execution treats it as the primary technical baseline, so implementation does not silently invent missing How. When repository evidence invalidates technical How while confirmed outcome, desired-future requirements, and non-goals remain true, correct the implementation and the affected technical artifact through their owning workflow without reopening product requirements. Technology selection rationale belongs to an ADR, schedule and assignments to the Work Plan. +- **Design Doc** — Records the complete implementation design for the confirmed scope: flows, contracts, change impact, and verification strategy. Task execution treats it as the primary technical baseline, so implementation does not silently invent missing How. The same baseline turns anything written in it into planned and implemented work, so release execution, production operation, and other work outside the repository change stay out of it; a confirmed requirement that describes such work is met by designing the capability it uses. When repository evidence invalidates technical How while confirmed outcome, desired-future requirements, and non-goals remain true, correct the implementation and the affected technical artifact through their owning workflow without reopening product requirements. Technology selection rationale belongs to an ADR, schedule and assignments to the Work Plan. - **Work Plan** — Fixes task order, dependencies, executable verification, and the earliest vertical proof point. Without it task order follows file layout rather than dependency, and integration risk moves to the end of the work. Design detail is referenced from the Design Doc rather than restated. diff --git a/skills/documentation-criteria/references/design-template.md b/skills/documentation-criteria/references/design-template.md index 70c8de97..9172e426 100644 --- a/skills/documentation-criteria/references/design-template.md +++ b/skills/documentation-criteria/references/design-template.md @@ -341,8 +341,8 @@ Verification Strategy defines what correctness means and how to prove it at desi ### Correctness Proof Method -- **Correctness definition**: [What "correct" means for this change — e.g., "output matches existing behavior", "all ACs pass in production-equivalent environment", "generated queries execute without error on target DB"] -- **Verification method**: [Specific technique — e.g., "compare new implementation output against existing implementation", "run against staging DB", "contract test with real API"] +- **Correctness definition**: [What "correct" means for this change — e.g., "output matches existing behavior", "generated queries execute without error on target DB"] +- **Verification method**: [Specific technique — e.g., "compare new implementation output against existing implementation", "contract test with real API"] - **Verification timing**: [When verification occurs — e.g., "after first vertical slice", "per repository", "at integration phase"] ### Early Verification Point @@ -371,7 +371,7 @@ Record boundaries needed by a current requirement, downstream implementation, or ## Risks and Mitigation -Include only evidenced residual risks that can change rollout, rollback, contract handling, or verification strategy while leaving the Selected Design valid. +Include only evidenced residual risks that can change rollback, contract handling, or verification strategy while leaving the Selected Design valid. | Risk | Impact | Probability | Mitigation | |------|--------|-------------|------------| diff --git a/skills/recipe-design/SKILL.md b/skills/recipe-design/SKILL.md index 9c5d82f2..9deaeb71 100644 --- a/skills/recipe-design/SKILL.md +++ b/skills/recipe-design/SKILL.md @@ -115,7 +115,7 @@ Apply Review Resolution to every discrepancy before document review. Send only ` Invoke `dev-workflows:document-reviewer` with exact inputs: `doc_type: DesignDoc`, `target`, `review_context: creation`, the original user requirements verbatim as `requirements_verbatim`, `confirmed_requirement_context`, `codebase_analysis`, and `verification_evidence` from Step 6. - `pass`: continue. -- `needs_revision`: apply Review Resolution, update through a fresh technical-designer invocation using the existing path and complete applied findings, then rerun Steps 6-7 for the affected boundary. +- `needs_revision`: apply Review Resolution, update through a fresh technical-designer invocation using the existing path and complete applied findings, then re-review with `prior_feedback`. - `rejected`: resolve technical governing-source conflicts through Review Resolution; ask the user only when confirmed outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes. Invoke `dev-workflows:design-sync` for consistency with other Design Docs and apply Review Resolution to actionable conflicts. Report `SKIPPED` distinctly when only one Design Doc exists. diff --git a/skills/recipe-front-design/SKILL.md b/skills/recipe-front-design/SKILL.md index 9cc6eafb..fdab87bf 100644 --- a/skills/recipe-front-design/SKILL.md +++ b/skills/recipe-front-design/SKILL.md @@ -143,7 +143,7 @@ Invoke `dev-workflows-frontend:code-verifier` with `doc_type: design-doc` and `d Invoke `dev-workflows-frontend:document-reviewer` with exact inputs: `doc_type: DesignDoc`; `target` as the returned Design Doc path unchanged; `review_context: creation`; original user requirements unchanged as `requirements_verbatim`; the Step 1 `confirmed_requirement_context` unchanged; the same unchanged `codebase_analysis` and optional `ui_analysis` supplied to the designer; and Step 8 `verification_evidence` unchanged. The reviewer follows an applicable UI Spec and accepted ADR paths cited by the Design Doc only when they can change an in-scope finding. - `pass`: continue. -- `needs_revision`: apply Review Resolution, update through a fresh technical-designer-frontend invocation using the existing path and complete applied findings, and rerun verification/review for the affected boundary. +- `needs_revision`: apply Review Resolution, update through a fresh technical-designer-frontend invocation using the existing path and complete applied findings, then re-review with `prior_feedback`. - `rejected`: resolve technical governing-source conflicts through Review Resolution; ask the user only when confirmed outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes. Invoke `dev-workflows-frontend:design-sync` with `source_design` as the returned Design Doc path unchanged, apply Review Resolution to actionable conflicts, and report `SKIPPED` distinctly when only one Design Doc exists. diff --git a/skills/recipe-update-doc/SKILL.md b/skills/recipe-update-doc/SKILL.md index 19d5d244..f3ebc49c 100644 --- a/skills/recipe-update-doc/SKILL.md +++ b/skills/recipe-update-doc/SKILL.md @@ -148,7 +148,7 @@ For each type, review consistency of the changed sections and their dependent st **On review result**: - Pass → Proceed to Step 6 -- Needs revision → Apply the Review Resolution Gate. Return to Step 4 when `apply` findings exist, using the following prompt: +- Needs revision → Apply the Review Resolution Gate. When `apply` findings exist, invoke the update agent with the following prompt, then re-run document-reviewer: ``` subagent_type: [Update Agent from Step 2] description: "Revise [Type from Step 2]" diff --git a/skills/subagents-orchestration-guide/SKILL.md b/skills/subagents-orchestration-guide/SKILL.md index 3303e4f7..77c4b778 100644 --- a/skills/subagents-orchestration-guide/SKILL.md +++ b/skills/subagents-orchestration-guide/SKILL.md @@ -289,7 +289,7 @@ Before post-implementation verifiers, collect retained verification limitations ### HC-04: code-verifier + codebase-analyzer → document-reviewer - Keep verifier discrepancies unchanged so correction and review remain traceable to observed evidence rather than orchestrator-authored design instructions. -- Apply Review Resolution and rerun verification after every applied correction, passing the previous complete verifier result, dispositions, and correction diff or paths as `prior_feedback`. Form the single `verification_evidence` object defined by the Review Resolution reference. +- Apply Review Resolution and rerun verification after every correction applied from code-verifier findings, passing the previous complete verifier result, dispositions, and correction diff or paths as `prior_feedback`. Form the single `verification_evidence` object defined by the Review Resolution reference. - Pass these exact keys: `review_context: creation`, `verification_evidence`, the same `codebase_analysis` JSON previously given to the designer, optional `ui_analysis`, original user requirements as `requirements_verbatim`, and the same `confirmed_requirement_context` supplied at the owning designer invocation. - Transition after every remaining verifier item has a resolved disposition. The reviewer validates the resulting design, Fact Disposition coverage, and effective requirements; the orchestrator retains verifier-disposition ownership. diff --git a/skills/subagents-orchestration-guide/references/review-resolution.md b/skills/subagents-orchestration-guide/references/review-resolution.md index 078058c3..9720d261 100644 --- a/skills/subagents-orchestration-guide/references/review-resolution.md +++ b/skills/subagents-orchestration-guide/references/review-resolution.md @@ -70,7 +70,7 @@ The correction assessment covers exactly every received item. The reviewer compl Derive the correction re-review status or verdict only from these reconciliation entries. An independent factual verifier may repeat an observed discrepancy; the orchestrator assigns its disposition from governing evidence. -For a bounded verifier, rerun after at least one correction is applied from its latest result or when the caller's re-run rule identifies a direct change to its declared boundary. Pass the previous complete result, dispositions, and correction diff or paths. The returned result replaces corrected items and carries unaffected evidence forward. Match materially identical findings by their claim or conflict and cited source and target evidence rather than a regenerated positional ID. A new finding enters routing only when its evidence links it causally to the correction or code-verifier’s required full inventory accounting establishes a current omission. +For a bounded verifier, rerun after at least one correction is applied from its latest result. Pass the previous complete result, dispositions, and correction diff or paths. The returned result replaces corrected items and carries unaffected evidence forward. Match materially identical findings by their claim or conflict and cited source and target evidence rather than a regenerated positional ID. A new finding enters routing only when its evidence links it causally to the correction or code-verifier’s required full inventory accounting establishes a current omission. ## 3. Converge or Report