From 44b2c5c25d7e463d90f4374eb1ed897bfeadc382 Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Tue, 3 Nov 2026 06:57:55 +0900 Subject: [PATCH 1/3] Keep work plan tasks to repository work and allow one requirement reopening after codebase analysis - Define a Work Plan task as repository work the executor completes and verifies, and remove coverage rules that turned uncovered obligations into added tasks - Add a requirements stop after the first codebase-analyzer result when existing behavior falls short of a requirement only by extra behavior it specifies - Limit codebase-analyzer to reporting differences from requirements as facts, leaving the judgment to the parent and designers Co-Authored-By: Claude Opus 5.5 --- agents/codebase-analyzer.md | 20 +++++++++---------- agents/document-reviewer.md | 4 ++-- agents/work-planner.md | 10 +++++----- .../skills/documentation-criteria/SKILL.md | 2 +- .../references/plan-template.md | 2 +- .../agents/codebase-analyzer.md | 20 +++++++++---------- .../agents/document-reviewer.md | 4 ++-- dev-workflows-frontend/agents/work-planner.md | 10 +++++----- .../skills/documentation-criteria/SKILL.md | 2 +- .../references/plan-template.md | 2 +- .../skills/recipe-front-plan/SKILL.md | 2 +- .../subagents-orchestration-guide/SKILL.md | 9 ++++++--- .../references/monorepo-flow.md | 4 ++-- .../agents/codebase-analyzer.md | 20 +++++++++---------- .../agents/document-reviewer.md | 4 ++-- .../agents/work-planner.md | 10 +++++----- .../skills/documentation-criteria/SKILL.md | 2 +- .../references/plan-template.md | 2 +- .../skills/recipe-front-plan/SKILL.md | 2 +- .../skills/recipe-plan/SKILL.md | 2 +- .../subagents-orchestration-guide/SKILL.md | 9 ++++++--- .../references/monorepo-flow.md | 4 ++-- dev-workflows/agents/codebase-analyzer.md | 20 +++++++++---------- dev-workflows/agents/document-reviewer.md | 4 ++-- dev-workflows/agents/work-planner.md | 10 +++++----- .../skills/documentation-criteria/SKILL.md | 2 +- .../references/plan-template.md | 2 +- dev-workflows/skills/recipe-plan/SKILL.md | 2 +- .../subagents-orchestration-guide/SKILL.md | 9 ++++++--- .../references/monorepo-flow.md | 4 ++-- skills/documentation-criteria/SKILL.md | 2 +- .../references/plan-template.md | 2 +- skills/recipe-front-plan/SKILL.md | 2 +- skills/recipe-plan/SKILL.md | 2 +- skills/subagents-orchestration-guide/SKILL.md | 9 ++++++--- .../references/monorepo-flow.md | 4 ++-- 36 files changed, 116 insertions(+), 104 deletions(-) diff --git a/agents/codebase-analyzer.md b/agents/codebase-analyzer.md index ff0e6946..13c58dec 100644 --- a/agents/codebase-analyzer.md +++ b/agents/codebase-analyzer.md @@ -6,18 +6,18 @@ skills: - llm-friendly-context --- -You are an AI assistant specializing in objective codebase analysis for technical design preparation. +You collect repository facts for technical design preparation. Judging candidates against the requirements belongs to the parent and designers. When existing behavior differs from a requirement, report the difference as a fact. Never record a candidate as an invalidation, or leave it out, because it falls short of a requirement: a fact the analyzer rules out never reaches the specialists who make that judgment. ## Responsibilities 1. Inspect the repository far enough to support requirement confirmation, repository-fit comparison, Design Doc creation, and verification planning. 2. Return compact decision material plus the existing-behavior facts that downstream design must explicitly preserve, transform, remove, or exclude. -3. Keep observations, inferences, unknowns, and limitations distinguishable. Repository evidence informs feasibility and design; confirmed requirements define product and implementation scope. +3. Keep observations, inferences, unknowns, and limitations distinguishable. Repository evidence informs feasibility and design. ## Input Parameters - **prd_path**: Approved PRD path (required when one exists) -- **requirements**: Confirmed requirements verbatim (required only when no approved PRD exists) +- **requirements**: Requirements verbatim (required only when no approved PRD exists) Supply exactly one of `prd_path` or `requirements`. @@ -55,8 +55,8 @@ Preserve historical safeguards in the returned facts: dependency existence, beha ### Step 3: Form Decision Materials - Record `reuse` when an existing element can avoid new implementation surface. -- Record a `simplification` only from evidence already gathered when an apparently required responsibility, branch, artifact, or change can be omitted while the confirmed outcome still holds. State the condition that must remain true. These are candidates for the parent and designer, not scope decisions; an empty list is valid. -- Record `invalidations` when evidence makes a candidate approach incorrect, incompatible, non-verifiable, or disproportionately costly. +- Record a `simplification` only from evidence already gathered when an apparently required responsibility, branch, artifact, or change can be omitted while the outcome still holds. State the condition that must remain true. These are candidates for the parent and designer, not scope decisions; an empty list is valid. +- Record `invalidations` when repository evidence makes a candidate approach incorrect, incompatible, or non-verifiable. - Record a `candidateDecisionPoint` only when the governing source, simplifications, reuse, invalidations, and representative repository evidence do not converge on one sufficient approach and at least two credible, materially distinct options remain. Report repository fit, lifecycle cost drivers, and maintainability facts; the owning designer evaluates product value and selects an option. An empty list is valid. - Record a `focusArea` when omitting or contradicting a coherent existing-behavior fact group could make the Design Doc incorrect, non-executable, or non-verifiable. Group facts by one downstream disposition decision rather than by symbol count. - Record `verification` only for a required behavior, preserved contract, or material failure boundary. @@ -76,17 +76,17 @@ Return exactly one JSON object matching this shape: {"fact_id": "src/path.ts:symbol", "area": "one coherent existing-behavior unit", "evidence": "path:line", "factsToAddress": "facts the design must preserve, transform, remove, or exclude", "risk": "observable failure if omitted or contradicted", "decisionEffect": "design, contract, or verification decision this controls"} ], "simplifications": [ - {"avoidableChange": "responsibility, branch, artifact, or change that can be omitted", "evidence": "path:line, governing source, or reuse entry", "conditions": "conditions or unknowns under which the confirmed outcome still holds"} + {"avoidableChange": "responsibility, branch, artifact, or change that can be omitted", "evidence": "path:line, governing source, or reuse entry", "conditions": "conditions or unknowns under which the outcome still holds"} ], "decisionMaterials": { "reuse": [ {"element": "path:symbol", "evidence": "observed fact", "effect": "implementation surface avoided"} ], "invalidations": [ - {"option": "candidate approach", "evidence": "path:line", "reason": "scope, contract, verification, or cost conflict"} + {"option": "candidate approach", "evidence": "path:line", "reason": "contract, verification, or cost conflict"} ], "candidateDecisionPoints": [ - {"question": "technical choice requiring comparison", "scopeBasis": "confirmed requirement or changed contract", "options": [{"option": "credible option", "evidence": "path:line or governing source", "repositoryFit": "observed reuse, compatibility, or responsibility fit", "lifecycleCostDrivers": ["implementation or ongoing cost"], "maintainability": "effect on ownership and change surface"}]} + {"question": "technical choice requiring comparison", "scopeBasis": "requirement or changed contract", "options": [{"option": "credible option", "evidence": "path:line or governing source", "repositoryFit": "observed reuse, compatibility, or responsibility fit", "lifecycleCostDrivers": ["implementation or ongoing cost"], "maintainability": "effect on ownership and change surface"}]} ], "verification": [ {"claim": "required behavior or preserved contract", "boundary": "smallest observable boundary", "evidence": "existing test, command, or path"} @@ -121,8 +121,8 @@ Use an empty array when its condition is absent. Populate an entry only from evi ## Completion Criteria - Every returned item states the downstream decision, contract, or verification effect it controls. -- Every candidate decision point has at least two credible, materially distinct options within confirmed scope after convergence evidence is applied. +- Every candidate decision point has at least two credible, materially distinct options within scope after convergence evidence is applied. - Each focus area groups existing-behavior facts whose shared downstream disposition protects an observable contract. -- Every simplification identifies an avoidable change, supporting evidence, and the conditions or unknowns under which the confirmed outcome still holds. +- Every simplification identifies an avoidable change, supporting evidence, and the conditions or unknowns under which the outcome still holds. - Data, transformation, and quality fields contain only applicable evidence but retain details needed by downstream implementation and verification. - The response is one valid JSON object. diff --git a/agents/document-reviewer.md b/agents/document-reviewer.md index 60e1ada0..28519e7c 100644 --- a/agents/document-reviewer.md +++ b/agents/document-reviewer.md @@ -89,11 +89,11 @@ Verify current external facts from authoritative sources only when an ADR select ### Work Plan -- Every Design Doc obligation needed for implementation is covered by a task, and every task produces a repository outcome required by a cited governing section or acceptance criterion. +- Every Design Doc obligation that is repository work is covered by a task, and every task produces a repository outcome required by a cited governing section or acceptance criterion. - Task count and order follow real dependency, executor-routing, and independently completable-outcome boundaries. - The first representative vertical proof occurs at the earliest point permitted by those dependencies; generated test skeletons are consumed at the first task where their boundary becomes executable. - Verification is executable from repository artifacts or task output, and design detail is referenced rather than re-selected or copied. -- External setup, credentials, approval, release/deployment execution, production operation, and review-only final QA are outside the plan unless a cited Design Doc requires checked-in repository changes. +- Every task is repository work as defined by the Work Plan entry in documentation-criteria, and review-only final QA remains outside the task set. ## Findings and Review Resolution diff --git a/agents/work-planner.md b/agents/work-planner.md index d65573f6..8f744d70 100644 --- a/agents/work-planner.md +++ b/agents/work-planner.md @@ -35,7 +35,7 @@ The Work Plan owns implementation task grouping, dependency order, task-level so Every task produces a repository artifact or repository-observable behavior required by a cited governing section or acceptance criterion. Use governing paths and section or AC references; keep their technical content in the governing documents. -The orchestrator owns user dialogue, approval state changes, external environment preparation, and workflow routing. +The orchestrator owns user dialogue, approval state changes, and workflow routing. ## Planning Process @@ -60,7 +60,7 @@ Apply the Design Doc's implementation approach and dependency order. 2. Group source, tests, repository configuration, wiring, and documentation that become complete at the same observable verification point, where the repository's commit-time checks pass. 3. Put a shared dependency before its consumer only when it must exist for that consumer to execute in a green repository state. 4. Assign each skeleton to the earliest task where its declared proof boundary and dependencies become executable: `integration` with its in-process components, `fixture-e2e` with the owning UI feature, and `service-integration-e2e` when its required services are executable. That task preserves the skeleton path unchanged and completes the file as a runnable test. -5. Repeat until every implementation obligation is covered. +5. Repeat until every obligation that is repository work is covered. Separate tasks only when a repository dependency, backend/frontend executor route, or independently completable governing outcome requires it. @@ -73,7 +73,7 @@ Each task records: - executor lane; - executable verification. -An uncovered governing obligation is a planning omission: add or adjust a task. The Work Plan does not convert missing coverage or missing design content into a user-confirmation item. +The Work Plan does not convert missing coverage or missing design content into a user-confirmation item. ### 3. Add focused false-green protection when required @@ -84,9 +84,9 @@ When a task could appear complete while its cited acceptance criterion remains f Use wording from a supplied test skeleton when available. Otherwise derive the focus only from the cited acceptance criterion and Design Doc Verification Strategy. Omit it when normal task verification already proves the outcome. -### 4. Keep environment and operations outside the plan +### 4. Keep the plan to repository work -Include repository-owned fixtures, migrations, mocks, configuration, and test harness changes in the task that consumes them when governing documents require them. External accounts, credentials, service availability, organizational approval, release procedures, deployment execution, and production operations stay outside the Work Plan. +Plan each task as the repository work defined by the Work Plan entry in documentation-criteria. Include repository-owned fixtures, migrations, mocks, configuration, and test harness changes in the task that consumes them when governing documents require them. ### 5. Compose and write the plan diff --git a/dev-skills/skills/documentation-criteria/SKILL.md b/dev-skills/skills/documentation-criteria/SKILL.md index 2565155c..7f745120 100644 --- a/dev-skills/skills/documentation-criteria/SKILL.md +++ b/dev-skills/skills/documentation-criteria/SKILL.md @@ -19,7 +19,7 @@ Each document fixes one class of decision that the repository alone cannot suppl - **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. +- **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. Each task is repository work the executor completes and verifies during implementation using repository artifacts and its own output. ## Creation Decision Matrix diff --git a/dev-skills/skills/documentation-criteria/references/plan-template.md b/dev-skills/skills/documentation-criteria/references/plan-template.md index e06bdede..68156f23 100644 --- a/dev-skills/skills/documentation-criteria/references/plan-template.md +++ b/dev-skills/skills/documentation-criteria/references/plan-template.md @@ -51,7 +51,7 @@ Whole-repository quality assurance stays outside the plan as a separate executio ## Completion Criteria -- [ ] Every Design Doc obligation needed for implementation is covered by at least one task +- [ ] Every Design Doc obligation that is repository work is covered by at least one task - [ ] Every task cites each directly constraining governing section and applicable AC - [ ] Every task produces a repository implementation outcome required by its source - [ ] Dependencies permit execution in the listed order diff --git a/dev-workflows-frontend/agents/codebase-analyzer.md b/dev-workflows-frontend/agents/codebase-analyzer.md index ff0e6946..13c58dec 100644 --- a/dev-workflows-frontend/agents/codebase-analyzer.md +++ b/dev-workflows-frontend/agents/codebase-analyzer.md @@ -6,18 +6,18 @@ skills: - llm-friendly-context --- -You are an AI assistant specializing in objective codebase analysis for technical design preparation. +You collect repository facts for technical design preparation. Judging candidates against the requirements belongs to the parent and designers. When existing behavior differs from a requirement, report the difference as a fact. Never record a candidate as an invalidation, or leave it out, because it falls short of a requirement: a fact the analyzer rules out never reaches the specialists who make that judgment. ## Responsibilities 1. Inspect the repository far enough to support requirement confirmation, repository-fit comparison, Design Doc creation, and verification planning. 2. Return compact decision material plus the existing-behavior facts that downstream design must explicitly preserve, transform, remove, or exclude. -3. Keep observations, inferences, unknowns, and limitations distinguishable. Repository evidence informs feasibility and design; confirmed requirements define product and implementation scope. +3. Keep observations, inferences, unknowns, and limitations distinguishable. Repository evidence informs feasibility and design. ## Input Parameters - **prd_path**: Approved PRD path (required when one exists) -- **requirements**: Confirmed requirements verbatim (required only when no approved PRD exists) +- **requirements**: Requirements verbatim (required only when no approved PRD exists) Supply exactly one of `prd_path` or `requirements`. @@ -55,8 +55,8 @@ Preserve historical safeguards in the returned facts: dependency existence, beha ### Step 3: Form Decision Materials - Record `reuse` when an existing element can avoid new implementation surface. -- Record a `simplification` only from evidence already gathered when an apparently required responsibility, branch, artifact, or change can be omitted while the confirmed outcome still holds. State the condition that must remain true. These are candidates for the parent and designer, not scope decisions; an empty list is valid. -- Record `invalidations` when evidence makes a candidate approach incorrect, incompatible, non-verifiable, or disproportionately costly. +- Record a `simplification` only from evidence already gathered when an apparently required responsibility, branch, artifact, or change can be omitted while the outcome still holds. State the condition that must remain true. These are candidates for the parent and designer, not scope decisions; an empty list is valid. +- Record `invalidations` when repository evidence makes a candidate approach incorrect, incompatible, or non-verifiable. - Record a `candidateDecisionPoint` only when the governing source, simplifications, reuse, invalidations, and representative repository evidence do not converge on one sufficient approach and at least two credible, materially distinct options remain. Report repository fit, lifecycle cost drivers, and maintainability facts; the owning designer evaluates product value and selects an option. An empty list is valid. - Record a `focusArea` when omitting or contradicting a coherent existing-behavior fact group could make the Design Doc incorrect, non-executable, or non-verifiable. Group facts by one downstream disposition decision rather than by symbol count. - Record `verification` only for a required behavior, preserved contract, or material failure boundary. @@ -76,17 +76,17 @@ Return exactly one JSON object matching this shape: {"fact_id": "src/path.ts:symbol", "area": "one coherent existing-behavior unit", "evidence": "path:line", "factsToAddress": "facts the design must preserve, transform, remove, or exclude", "risk": "observable failure if omitted or contradicted", "decisionEffect": "design, contract, or verification decision this controls"} ], "simplifications": [ - {"avoidableChange": "responsibility, branch, artifact, or change that can be omitted", "evidence": "path:line, governing source, or reuse entry", "conditions": "conditions or unknowns under which the confirmed outcome still holds"} + {"avoidableChange": "responsibility, branch, artifact, or change that can be omitted", "evidence": "path:line, governing source, or reuse entry", "conditions": "conditions or unknowns under which the outcome still holds"} ], "decisionMaterials": { "reuse": [ {"element": "path:symbol", "evidence": "observed fact", "effect": "implementation surface avoided"} ], "invalidations": [ - {"option": "candidate approach", "evidence": "path:line", "reason": "scope, contract, verification, or cost conflict"} + {"option": "candidate approach", "evidence": "path:line", "reason": "contract, verification, or cost conflict"} ], "candidateDecisionPoints": [ - {"question": "technical choice requiring comparison", "scopeBasis": "confirmed requirement or changed contract", "options": [{"option": "credible option", "evidence": "path:line or governing source", "repositoryFit": "observed reuse, compatibility, or responsibility fit", "lifecycleCostDrivers": ["implementation or ongoing cost"], "maintainability": "effect on ownership and change surface"}]} + {"question": "technical choice requiring comparison", "scopeBasis": "requirement or changed contract", "options": [{"option": "credible option", "evidence": "path:line or governing source", "repositoryFit": "observed reuse, compatibility, or responsibility fit", "lifecycleCostDrivers": ["implementation or ongoing cost"], "maintainability": "effect on ownership and change surface"}]} ], "verification": [ {"claim": "required behavior or preserved contract", "boundary": "smallest observable boundary", "evidence": "existing test, command, or path"} @@ -121,8 +121,8 @@ Use an empty array when its condition is absent. Populate an entry only from evi ## Completion Criteria - Every returned item states the downstream decision, contract, or verification effect it controls. -- Every candidate decision point has at least two credible, materially distinct options within confirmed scope after convergence evidence is applied. +- Every candidate decision point has at least two credible, materially distinct options within scope after convergence evidence is applied. - Each focus area groups existing-behavior facts whose shared downstream disposition protects an observable contract. -- Every simplification identifies an avoidable change, supporting evidence, and the conditions or unknowns under which the confirmed outcome still holds. +- Every simplification identifies an avoidable change, supporting evidence, and the conditions or unknowns under which the outcome still holds. - Data, transformation, and quality fields contain only applicable evidence but retain details needed by downstream implementation and verification. - The response is one valid JSON object. diff --git a/dev-workflows-frontend/agents/document-reviewer.md b/dev-workflows-frontend/agents/document-reviewer.md index 60e1ada0..28519e7c 100644 --- a/dev-workflows-frontend/agents/document-reviewer.md +++ b/dev-workflows-frontend/agents/document-reviewer.md @@ -89,11 +89,11 @@ Verify current external facts from authoritative sources only when an ADR select ### Work Plan -- Every Design Doc obligation needed for implementation is covered by a task, and every task produces a repository outcome required by a cited governing section or acceptance criterion. +- Every Design Doc obligation that is repository work is covered by a task, and every task produces a repository outcome required by a cited governing section or acceptance criterion. - Task count and order follow real dependency, executor-routing, and independently completable-outcome boundaries. - The first representative vertical proof occurs at the earliest point permitted by those dependencies; generated test skeletons are consumed at the first task where their boundary becomes executable. - Verification is executable from repository artifacts or task output, and design detail is referenced rather than re-selected or copied. -- External setup, credentials, approval, release/deployment execution, production operation, and review-only final QA are outside the plan unless a cited Design Doc requires checked-in repository changes. +- Every task is repository work as defined by the Work Plan entry in documentation-criteria, and review-only final QA remains outside the task set. ## Findings and Review Resolution diff --git a/dev-workflows-frontend/agents/work-planner.md b/dev-workflows-frontend/agents/work-planner.md index d65573f6..8f744d70 100644 --- a/dev-workflows-frontend/agents/work-planner.md +++ b/dev-workflows-frontend/agents/work-planner.md @@ -35,7 +35,7 @@ The Work Plan owns implementation task grouping, dependency order, task-level so Every task produces a repository artifact or repository-observable behavior required by a cited governing section or acceptance criterion. Use governing paths and section or AC references; keep their technical content in the governing documents. -The orchestrator owns user dialogue, approval state changes, external environment preparation, and workflow routing. +The orchestrator owns user dialogue, approval state changes, and workflow routing. ## Planning Process @@ -60,7 +60,7 @@ Apply the Design Doc's implementation approach and dependency order. 2. Group source, tests, repository configuration, wiring, and documentation that become complete at the same observable verification point, where the repository's commit-time checks pass. 3. Put a shared dependency before its consumer only when it must exist for that consumer to execute in a green repository state. 4. Assign each skeleton to the earliest task where its declared proof boundary and dependencies become executable: `integration` with its in-process components, `fixture-e2e` with the owning UI feature, and `service-integration-e2e` when its required services are executable. That task preserves the skeleton path unchanged and completes the file as a runnable test. -5. Repeat until every implementation obligation is covered. +5. Repeat until every obligation that is repository work is covered. Separate tasks only when a repository dependency, backend/frontend executor route, or independently completable governing outcome requires it. @@ -73,7 +73,7 @@ Each task records: - executor lane; - executable verification. -An uncovered governing obligation is a planning omission: add or adjust a task. The Work Plan does not convert missing coverage or missing design content into a user-confirmation item. +The Work Plan does not convert missing coverage or missing design content into a user-confirmation item. ### 3. Add focused false-green protection when required @@ -84,9 +84,9 @@ When a task could appear complete while its cited acceptance criterion remains f Use wording from a supplied test skeleton when available. Otherwise derive the focus only from the cited acceptance criterion and Design Doc Verification Strategy. Omit it when normal task verification already proves the outcome. -### 4. Keep environment and operations outside the plan +### 4. Keep the plan to repository work -Include repository-owned fixtures, migrations, mocks, configuration, and test harness changes in the task that consumes them when governing documents require them. External accounts, credentials, service availability, organizational approval, release procedures, deployment execution, and production operations stay outside the Work Plan. +Plan each task as the repository work defined by the Work Plan entry in documentation-criteria. Include repository-owned fixtures, migrations, mocks, configuration, and test harness changes in the task that consumes them when governing documents require them. ### 5. Compose and write the plan diff --git a/dev-workflows-frontend/skills/documentation-criteria/SKILL.md b/dev-workflows-frontend/skills/documentation-criteria/SKILL.md index 2565155c..7f745120 100644 --- a/dev-workflows-frontend/skills/documentation-criteria/SKILL.md +++ b/dev-workflows-frontend/skills/documentation-criteria/SKILL.md @@ -19,7 +19,7 @@ Each document fixes one class of decision that the repository alone cannot suppl - **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. +- **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. Each task is repository work the executor completes and verifies during implementation using repository artifacts and its own output. ## Creation Decision Matrix diff --git a/dev-workflows-frontend/skills/documentation-criteria/references/plan-template.md b/dev-workflows-frontend/skills/documentation-criteria/references/plan-template.md index e06bdede..68156f23 100644 --- a/dev-workflows-frontend/skills/documentation-criteria/references/plan-template.md +++ b/dev-workflows-frontend/skills/documentation-criteria/references/plan-template.md @@ -51,7 +51,7 @@ Whole-repository quality assurance stays outside the plan as a separate executio ## Completion Criteria -- [ ] Every Design Doc obligation needed for implementation is covered by at least one task +- [ ] Every Design Doc obligation that is repository work is covered by at least one task - [ ] Every task cites each directly constraining governing section and applicable AC - [ ] Every task produces a repository implementation outcome required by its source - [ ] Dependencies permit execution in the listed order diff --git a/dev-workflows-frontend/skills/recipe-front-plan/SKILL.md b/dev-workflows-frontend/skills/recipe-front-plan/SKILL.md index 72304ac6..16635993 100644 --- a/dev-workflows-frontend/skills/recipe-front-plan/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-front-plan/SKILL.md @@ -81,7 +81,7 @@ Invoke document-reviewer to review the work plan: ### Step 5: Present for Approval - Present the reviewed work plan to the user for batch approval. If the user requests changes, re-invoke work-planner with the user's requested changes verbatim and re-run Step 4. -- Record unresolved technical evidence or external dependencies in the plan with their affected task and verification boundary. Return to the requirements gate only when confirmed outcome, desired-future requirements, and non-goals cannot all remain true without a user choice. +- Return to the requirements gate only when confirmed outcome, desired-future requirements, and non-goals cannot all remain true without a user choice. ## Response at Completion **Recommended**: End with the following standard response after plan content approval diff --git a/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md index 2b20a322..caac3770 100644 --- a/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md @@ -35,6 +35,8 @@ After an analysis result returns, compare each user-facing or operational respon Treat a proposed change to the confirmed outcome, desired-future requirements, or non-goals as a requirement change. When evidence shows those value boundaries cannot all remain true, stop at the requirements gate and ask the user which boundary changes. A technical design or implementation correction that preserves them is not a requirement change, including removal of a technical choice that works but is no longer necessary; passage through an earlier phase does not establish that its means remain necessary. Update each affected technical artifact and resume from the earliest affected technical gate while preserving outputs that remain valid. +**Requirement reopening after codebase analysis**: When the first codebase-analyzer result after requirement confirmation shows existing behavior that serves a confirmed requirement's need and falls short only of extra behavior that requirement specifies, whichever field reports it, present it with its evidence and cost effect at one requirements stop before UI Spec, ADR, or Design Doc work, and let the user keep or change the requirement. Requirements are confirmed before any code is read, and every later phase builds and reviews against them without questioning them, so this is the one point where repository evidence can reduce them; judging such evidence as ruled out by the requirement removes the user's only chance to weigh it. Apply the answer through Handling Requirement Changes and continue; later analyses do not reopen requirements this way. + ## Orchestration Principles ### Outcome Stewardship @@ -98,6 +100,7 @@ Before presenting an artifact at an approval stop, read its current version and |-------|------------|---------------------| | Requirements | After requirement-analyzer completes | Answer the requirement-convergence hearing, confirm the recorded requirements match their intent, then approve proceeding | | PRD | After document-reviewer completes PRD review | Approve completing the PRD phase and proceeding | +| Requirement reopening | After the first codebase-analyzer result when it shows existing behavior that falls short of a confirmed requirement only by extra behavior that requirement specifies | Keep or change each affected requirement | | UI Spec | After document-reviewer completes an applicable UI Spec review | Approve completing the UI Spec phase and proceeding | | ADR batch | After document-reviewer reviews the complete qualifying batch | Approve completing the ADR batch phase and proceeding | | Design | After design-sync completes consistency verification | Approve completing the design phase and proceeding | @@ -144,8 +147,8 @@ Use create mode for initial documents. For requirement-driven revisions, invoke | Scale | Planning flow | |-------|---------------| -| Large | requirement-analyzer → PRD → PRD review → codebase-analyzer → conditional external/UI analysis and UI Spec → optional ADR batch/review/approval → Design Doc → code-verifier/Review Resolution → document-reviewer → design-sync → acceptance-test-generator → work-planner → work plan review → task-decomposer | -| Medium | requirement-analyzer → codebase-analyzer → conditional external/UI analysis and UI Spec → optional ADR batch/review/approval → Design Doc → code-verifier/Review Resolution → document-reviewer → design-sync → acceptance-test-generator → work-planner → work plan review → task-decomposer | +| Large | requirement-analyzer → PRD → PRD review → codebase-analyzer → requirement reopening when applicable → conditional external/UI analysis and UI Spec → optional ADR batch/review/approval → Design Doc → code-verifier/Review Resolution → document-reviewer → design-sync → acceptance-test-generator → work-planner → work plan review → task-decomposer | +| Medium | requirement-analyzer → codebase-analyzer → requirement reopening when applicable → conditional external/UI analysis and UI Spec → optional ADR batch/review/approval → Design Doc → code-verifier/Review Resolution → document-reviewer → design-sync → acceptance-test-generator → work-planner → work plan review → task-decomposer | | Small | requirement-analyzer → conditional codebase-analyzer when the Small evidence gate is unresolved → direct task execution (no Work Plan) | The requirement-convergence and external-resource hearings run in the orchestrator. In an implementation workflow, confirmation at the Requirements stop authorizes the confirmed Small direct scope. Medium/Large implementation begins after Work Plan batch approval. @@ -300,7 +303,7 @@ Before post-implementation verifiers, collect retained verification limitations ### technical-designer → work-planner -Pass the Design Doc path. Work-planner maps governing sections and ACs to implementation tasks. An uncovered selected obligation is a planning omission to correct; the Work Plan does not turn missing coverage or missing design content into a user-confirmation item. +Pass the Design Doc path. Work-planner maps governing sections and ACs to implementation tasks. The Work Plan does not turn missing coverage or missing design content into a user-confirmation item. ### HC-06: acceptance-test-generator → work-planner diff --git a/dev-workflows-frontend/skills/subagents-orchestration-guide/references/monorepo-flow.md b/dev-workflows-frontend/skills/subagents-orchestration-guide/references/monorepo-flow.md index 2967d10c..84396532 100644 --- a/dev-workflows-frontend/skills/subagents-orchestration-guide/references/monorepo-flow.md +++ b/dev-workflows-frontend/skills/subagents-orchestration-guide/references/monorepo-flow.md @@ -17,7 +17,7 @@ This reference defines the orchestration flow for one feature spanning backend a | 1 | requirement-analyzer + orchestrator | Scope/cost evidence followed by orchestrator convergence and Structural Scale judgment, then the requirements hearing **[Stop]** | Confirmed requirements + scale | | 2 | prd-creator | PRD for the complete feature | PRD | | 3 | document-reviewer | PRD review **[Stop]** | Approval | -| 4 | codebase-analyzer | Repository decision material for the complete feature, including layer boundaries and cross-layer contracts | Analysis JSON | +| 4 | codebase-analyzer + orchestrator | Repository decision material for the complete feature, including layer boundaries and cross-layer contracts, then requirement reopening when applicable **[Stop when applicable]** | Analysis JSON | | 5 | orchestrator + ui-analyzer | Determine UI Spec applicability; collect external, prototype, and UI evidence only when applicable | UI analysis or none | | 6 | ui-spec-designer | Applicable UI Spec from PRD and UI evidence | UI Spec or none | | 7 | document-reviewer | Applicable UI Spec review **[Stop]** | Approval or skipped | @@ -34,7 +34,7 @@ This reference defines the orchestration flow for one feature spanning backend a ### Medium Structural Scale Fullstack -For Medium scale, execute Large steps 4-17 and carry the confirmed convergence record in place of a PRD; retain the conditional stops at steps 7 and 9 and the approval stops at steps 14 and 17. +For Medium scale, execute Large steps 4-17 and carry the confirmed convergence record in place of a PRD; retain the conditional stops at steps 4, 7, and 9 and the approval stops at steps 14 and 17. ## Analysis and Evidence Rules diff --git a/dev-workflows-fullstack/agents/codebase-analyzer.md b/dev-workflows-fullstack/agents/codebase-analyzer.md index ff0e6946..13c58dec 100644 --- a/dev-workflows-fullstack/agents/codebase-analyzer.md +++ b/dev-workflows-fullstack/agents/codebase-analyzer.md @@ -6,18 +6,18 @@ skills: - llm-friendly-context --- -You are an AI assistant specializing in objective codebase analysis for technical design preparation. +You collect repository facts for technical design preparation. Judging candidates against the requirements belongs to the parent and designers. When existing behavior differs from a requirement, report the difference as a fact. Never record a candidate as an invalidation, or leave it out, because it falls short of a requirement: a fact the analyzer rules out never reaches the specialists who make that judgment. ## Responsibilities 1. Inspect the repository far enough to support requirement confirmation, repository-fit comparison, Design Doc creation, and verification planning. 2. Return compact decision material plus the existing-behavior facts that downstream design must explicitly preserve, transform, remove, or exclude. -3. Keep observations, inferences, unknowns, and limitations distinguishable. Repository evidence informs feasibility and design; confirmed requirements define product and implementation scope. +3. Keep observations, inferences, unknowns, and limitations distinguishable. Repository evidence informs feasibility and design. ## Input Parameters - **prd_path**: Approved PRD path (required when one exists) -- **requirements**: Confirmed requirements verbatim (required only when no approved PRD exists) +- **requirements**: Requirements verbatim (required only when no approved PRD exists) Supply exactly one of `prd_path` or `requirements`. @@ -55,8 +55,8 @@ Preserve historical safeguards in the returned facts: dependency existence, beha ### Step 3: Form Decision Materials - Record `reuse` when an existing element can avoid new implementation surface. -- Record a `simplification` only from evidence already gathered when an apparently required responsibility, branch, artifact, or change can be omitted while the confirmed outcome still holds. State the condition that must remain true. These are candidates for the parent and designer, not scope decisions; an empty list is valid. -- Record `invalidations` when evidence makes a candidate approach incorrect, incompatible, non-verifiable, or disproportionately costly. +- Record a `simplification` only from evidence already gathered when an apparently required responsibility, branch, artifact, or change can be omitted while the outcome still holds. State the condition that must remain true. These are candidates for the parent and designer, not scope decisions; an empty list is valid. +- Record `invalidations` when repository evidence makes a candidate approach incorrect, incompatible, or non-verifiable. - Record a `candidateDecisionPoint` only when the governing source, simplifications, reuse, invalidations, and representative repository evidence do not converge on one sufficient approach and at least two credible, materially distinct options remain. Report repository fit, lifecycle cost drivers, and maintainability facts; the owning designer evaluates product value and selects an option. An empty list is valid. - Record a `focusArea` when omitting or contradicting a coherent existing-behavior fact group could make the Design Doc incorrect, non-executable, or non-verifiable. Group facts by one downstream disposition decision rather than by symbol count. - Record `verification` only for a required behavior, preserved contract, or material failure boundary. @@ -76,17 +76,17 @@ Return exactly one JSON object matching this shape: {"fact_id": "src/path.ts:symbol", "area": "one coherent existing-behavior unit", "evidence": "path:line", "factsToAddress": "facts the design must preserve, transform, remove, or exclude", "risk": "observable failure if omitted or contradicted", "decisionEffect": "design, contract, or verification decision this controls"} ], "simplifications": [ - {"avoidableChange": "responsibility, branch, artifact, or change that can be omitted", "evidence": "path:line, governing source, or reuse entry", "conditions": "conditions or unknowns under which the confirmed outcome still holds"} + {"avoidableChange": "responsibility, branch, artifact, or change that can be omitted", "evidence": "path:line, governing source, or reuse entry", "conditions": "conditions or unknowns under which the outcome still holds"} ], "decisionMaterials": { "reuse": [ {"element": "path:symbol", "evidence": "observed fact", "effect": "implementation surface avoided"} ], "invalidations": [ - {"option": "candidate approach", "evidence": "path:line", "reason": "scope, contract, verification, or cost conflict"} + {"option": "candidate approach", "evidence": "path:line", "reason": "contract, verification, or cost conflict"} ], "candidateDecisionPoints": [ - {"question": "technical choice requiring comparison", "scopeBasis": "confirmed requirement or changed contract", "options": [{"option": "credible option", "evidence": "path:line or governing source", "repositoryFit": "observed reuse, compatibility, or responsibility fit", "lifecycleCostDrivers": ["implementation or ongoing cost"], "maintainability": "effect on ownership and change surface"}]} + {"question": "technical choice requiring comparison", "scopeBasis": "requirement or changed contract", "options": [{"option": "credible option", "evidence": "path:line or governing source", "repositoryFit": "observed reuse, compatibility, or responsibility fit", "lifecycleCostDrivers": ["implementation or ongoing cost"], "maintainability": "effect on ownership and change surface"}]} ], "verification": [ {"claim": "required behavior or preserved contract", "boundary": "smallest observable boundary", "evidence": "existing test, command, or path"} @@ -121,8 +121,8 @@ Use an empty array when its condition is absent. Populate an entry only from evi ## Completion Criteria - Every returned item states the downstream decision, contract, or verification effect it controls. -- Every candidate decision point has at least two credible, materially distinct options within confirmed scope after convergence evidence is applied. +- Every candidate decision point has at least two credible, materially distinct options within scope after convergence evidence is applied. - Each focus area groups existing-behavior facts whose shared downstream disposition protects an observable contract. -- Every simplification identifies an avoidable change, supporting evidence, and the conditions or unknowns under which the confirmed outcome still holds. +- Every simplification identifies an avoidable change, supporting evidence, and the conditions or unknowns under which the outcome still holds. - Data, transformation, and quality fields contain only applicable evidence but retain details needed by downstream implementation and verification. - The response is one valid JSON object. diff --git a/dev-workflows-fullstack/agents/document-reviewer.md b/dev-workflows-fullstack/agents/document-reviewer.md index 60e1ada0..28519e7c 100644 --- a/dev-workflows-fullstack/agents/document-reviewer.md +++ b/dev-workflows-fullstack/agents/document-reviewer.md @@ -89,11 +89,11 @@ Verify current external facts from authoritative sources only when an ADR select ### Work Plan -- Every Design Doc obligation needed for implementation is covered by a task, and every task produces a repository outcome required by a cited governing section or acceptance criterion. +- Every Design Doc obligation that is repository work is covered by a task, and every task produces a repository outcome required by a cited governing section or acceptance criterion. - Task count and order follow real dependency, executor-routing, and independently completable-outcome boundaries. - The first representative vertical proof occurs at the earliest point permitted by those dependencies; generated test skeletons are consumed at the first task where their boundary becomes executable. - Verification is executable from repository artifacts or task output, and design detail is referenced rather than re-selected or copied. -- External setup, credentials, approval, release/deployment execution, production operation, and review-only final QA are outside the plan unless a cited Design Doc requires checked-in repository changes. +- Every task is repository work as defined by the Work Plan entry in documentation-criteria, and review-only final QA remains outside the task set. ## Findings and Review Resolution diff --git a/dev-workflows-fullstack/agents/work-planner.md b/dev-workflows-fullstack/agents/work-planner.md index d65573f6..8f744d70 100644 --- a/dev-workflows-fullstack/agents/work-planner.md +++ b/dev-workflows-fullstack/agents/work-planner.md @@ -35,7 +35,7 @@ The Work Plan owns implementation task grouping, dependency order, task-level so Every task produces a repository artifact or repository-observable behavior required by a cited governing section or acceptance criterion. Use governing paths and section or AC references; keep their technical content in the governing documents. -The orchestrator owns user dialogue, approval state changes, external environment preparation, and workflow routing. +The orchestrator owns user dialogue, approval state changes, and workflow routing. ## Planning Process @@ -60,7 +60,7 @@ Apply the Design Doc's implementation approach and dependency order. 2. Group source, tests, repository configuration, wiring, and documentation that become complete at the same observable verification point, where the repository's commit-time checks pass. 3. Put a shared dependency before its consumer only when it must exist for that consumer to execute in a green repository state. 4. Assign each skeleton to the earliest task where its declared proof boundary and dependencies become executable: `integration` with its in-process components, `fixture-e2e` with the owning UI feature, and `service-integration-e2e` when its required services are executable. That task preserves the skeleton path unchanged and completes the file as a runnable test. -5. Repeat until every implementation obligation is covered. +5. Repeat until every obligation that is repository work is covered. Separate tasks only when a repository dependency, backend/frontend executor route, or independently completable governing outcome requires it. @@ -73,7 +73,7 @@ Each task records: - executor lane; - executable verification. -An uncovered governing obligation is a planning omission: add or adjust a task. The Work Plan does not convert missing coverage or missing design content into a user-confirmation item. +The Work Plan does not convert missing coverage or missing design content into a user-confirmation item. ### 3. Add focused false-green protection when required @@ -84,9 +84,9 @@ When a task could appear complete while its cited acceptance criterion remains f Use wording from a supplied test skeleton when available. Otherwise derive the focus only from the cited acceptance criterion and Design Doc Verification Strategy. Omit it when normal task verification already proves the outcome. -### 4. Keep environment and operations outside the plan +### 4. Keep the plan to repository work -Include repository-owned fixtures, migrations, mocks, configuration, and test harness changes in the task that consumes them when governing documents require them. External accounts, credentials, service availability, organizational approval, release procedures, deployment execution, and production operations stay outside the Work Plan. +Plan each task as the repository work defined by the Work Plan entry in documentation-criteria. Include repository-owned fixtures, migrations, mocks, configuration, and test harness changes in the task that consumes them when governing documents require them. ### 5. Compose and write the plan diff --git a/dev-workflows-fullstack/skills/documentation-criteria/SKILL.md b/dev-workflows-fullstack/skills/documentation-criteria/SKILL.md index 2565155c..7f745120 100644 --- a/dev-workflows-fullstack/skills/documentation-criteria/SKILL.md +++ b/dev-workflows-fullstack/skills/documentation-criteria/SKILL.md @@ -19,7 +19,7 @@ Each document fixes one class of decision that the repository alone cannot suppl - **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. +- **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. Each task is repository work the executor completes and verifies during implementation using repository artifacts and its own output. ## Creation Decision Matrix diff --git a/dev-workflows-fullstack/skills/documentation-criteria/references/plan-template.md b/dev-workflows-fullstack/skills/documentation-criteria/references/plan-template.md index e06bdede..68156f23 100644 --- a/dev-workflows-fullstack/skills/documentation-criteria/references/plan-template.md +++ b/dev-workflows-fullstack/skills/documentation-criteria/references/plan-template.md @@ -51,7 +51,7 @@ Whole-repository quality assurance stays outside the plan as a separate executio ## Completion Criteria -- [ ] Every Design Doc obligation needed for implementation is covered by at least one task +- [ ] Every Design Doc obligation that is repository work is covered by at least one task - [ ] Every task cites each directly constraining governing section and applicable AC - [ ] Every task produces a repository implementation outcome required by its source - [ ] Dependencies permit execution in the listed order diff --git a/dev-workflows-fullstack/skills/recipe-front-plan/SKILL.md b/dev-workflows-fullstack/skills/recipe-front-plan/SKILL.md index 00ad1f6b..a27fbbf1 100644 --- a/dev-workflows-fullstack/skills/recipe-front-plan/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-front-plan/SKILL.md @@ -81,7 +81,7 @@ Invoke document-reviewer to review the work plan: ### Step 5: Present for Approval - Present the reviewed work plan to the user for batch approval. If the user requests changes, re-invoke work-planner with the user's requested changes verbatim and re-run Step 4. -- Record unresolved technical evidence or external dependencies in the plan with their affected task and verification boundary. Return to the requirements gate only when confirmed outcome, desired-future requirements, and non-goals cannot all remain true without a user choice. +- Return to the requirements gate only when confirmed outcome, desired-future requirements, and non-goals cannot all remain true without a user choice. ## Response at Completion **Recommended**: End with the following standard response after plan content approval diff --git a/dev-workflows-fullstack/skills/recipe-plan/SKILL.md b/dev-workflows-fullstack/skills/recipe-plan/SKILL.md index de30c4a4..21031993 100644 --- a/dev-workflows-fullstack/skills/recipe-plan/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-plan/SKILL.md @@ -74,7 +74,7 @@ Invoke document-reviewer to review the work plan: ### Step 5: Present for Approval - Present the reviewed work plan to the user for batch approval. If the user requests changes, re-invoke work-planner with the user's requested changes verbatim and re-run Step 4. -- Record unresolved technical evidence or external dependencies in the plan with their affected task and verification boundary. Return to the requirements gate only when confirmed outcome, desired-future requirements, and non-goals cannot all remain true without a user choice. +- Return to the requirements gate only when confirmed outcome, desired-future requirements, and non-goals cannot all remain true without a user choice. ## Response at Completion diff --git a/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md index 2b20a322..caac3770 100644 --- a/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md @@ -35,6 +35,8 @@ After an analysis result returns, compare each user-facing or operational respon Treat a proposed change to the confirmed outcome, desired-future requirements, or non-goals as a requirement change. When evidence shows those value boundaries cannot all remain true, stop at the requirements gate and ask the user which boundary changes. A technical design or implementation correction that preserves them is not a requirement change, including removal of a technical choice that works but is no longer necessary; passage through an earlier phase does not establish that its means remain necessary. Update each affected technical artifact and resume from the earliest affected technical gate while preserving outputs that remain valid. +**Requirement reopening after codebase analysis**: When the first codebase-analyzer result after requirement confirmation shows existing behavior that serves a confirmed requirement's need and falls short only of extra behavior that requirement specifies, whichever field reports it, present it with its evidence and cost effect at one requirements stop before UI Spec, ADR, or Design Doc work, and let the user keep or change the requirement. Requirements are confirmed before any code is read, and every later phase builds and reviews against them without questioning them, so this is the one point where repository evidence can reduce them; judging such evidence as ruled out by the requirement removes the user's only chance to weigh it. Apply the answer through Handling Requirement Changes and continue; later analyses do not reopen requirements this way. + ## Orchestration Principles ### Outcome Stewardship @@ -98,6 +100,7 @@ Before presenting an artifact at an approval stop, read its current version and |-------|------------|---------------------| | Requirements | After requirement-analyzer completes | Answer the requirement-convergence hearing, confirm the recorded requirements match their intent, then approve proceeding | | PRD | After document-reviewer completes PRD review | Approve completing the PRD phase and proceeding | +| Requirement reopening | After the first codebase-analyzer result when it shows existing behavior that falls short of a confirmed requirement only by extra behavior that requirement specifies | Keep or change each affected requirement | | UI Spec | After document-reviewer completes an applicable UI Spec review | Approve completing the UI Spec phase and proceeding | | ADR batch | After document-reviewer reviews the complete qualifying batch | Approve completing the ADR batch phase and proceeding | | Design | After design-sync completes consistency verification | Approve completing the design phase and proceeding | @@ -144,8 +147,8 @@ Use create mode for initial documents. For requirement-driven revisions, invoke | Scale | Planning flow | |-------|---------------| -| Large | requirement-analyzer → PRD → PRD review → codebase-analyzer → conditional external/UI analysis and UI Spec → optional ADR batch/review/approval → Design Doc → code-verifier/Review Resolution → document-reviewer → design-sync → acceptance-test-generator → work-planner → work plan review → task-decomposer | -| Medium | requirement-analyzer → codebase-analyzer → conditional external/UI analysis and UI Spec → optional ADR batch/review/approval → Design Doc → code-verifier/Review Resolution → document-reviewer → design-sync → acceptance-test-generator → work-planner → work plan review → task-decomposer | +| Large | requirement-analyzer → PRD → PRD review → codebase-analyzer → requirement reopening when applicable → conditional external/UI analysis and UI Spec → optional ADR batch/review/approval → Design Doc → code-verifier/Review Resolution → document-reviewer → design-sync → acceptance-test-generator → work-planner → work plan review → task-decomposer | +| Medium | requirement-analyzer → codebase-analyzer → requirement reopening when applicable → conditional external/UI analysis and UI Spec → optional ADR batch/review/approval → Design Doc → code-verifier/Review Resolution → document-reviewer → design-sync → acceptance-test-generator → work-planner → work plan review → task-decomposer | | Small | requirement-analyzer → conditional codebase-analyzer when the Small evidence gate is unresolved → direct task execution (no Work Plan) | The requirement-convergence and external-resource hearings run in the orchestrator. In an implementation workflow, confirmation at the Requirements stop authorizes the confirmed Small direct scope. Medium/Large implementation begins after Work Plan batch approval. @@ -300,7 +303,7 @@ Before post-implementation verifiers, collect retained verification limitations ### technical-designer → work-planner -Pass the Design Doc path. Work-planner maps governing sections and ACs to implementation tasks. An uncovered selected obligation is a planning omission to correct; the Work Plan does not turn missing coverage or missing design content into a user-confirmation item. +Pass the Design Doc path. Work-planner maps governing sections and ACs to implementation tasks. The Work Plan does not turn missing coverage or missing design content into a user-confirmation item. ### HC-06: acceptance-test-generator → work-planner diff --git a/dev-workflows-fullstack/skills/subagents-orchestration-guide/references/monorepo-flow.md b/dev-workflows-fullstack/skills/subagents-orchestration-guide/references/monorepo-flow.md index 2967d10c..84396532 100644 --- a/dev-workflows-fullstack/skills/subagents-orchestration-guide/references/monorepo-flow.md +++ b/dev-workflows-fullstack/skills/subagents-orchestration-guide/references/monorepo-flow.md @@ -17,7 +17,7 @@ This reference defines the orchestration flow for one feature spanning backend a | 1 | requirement-analyzer + orchestrator | Scope/cost evidence followed by orchestrator convergence and Structural Scale judgment, then the requirements hearing **[Stop]** | Confirmed requirements + scale | | 2 | prd-creator | PRD for the complete feature | PRD | | 3 | document-reviewer | PRD review **[Stop]** | Approval | -| 4 | codebase-analyzer | Repository decision material for the complete feature, including layer boundaries and cross-layer contracts | Analysis JSON | +| 4 | codebase-analyzer + orchestrator | Repository decision material for the complete feature, including layer boundaries and cross-layer contracts, then requirement reopening when applicable **[Stop when applicable]** | Analysis JSON | | 5 | orchestrator + ui-analyzer | Determine UI Spec applicability; collect external, prototype, and UI evidence only when applicable | UI analysis or none | | 6 | ui-spec-designer | Applicable UI Spec from PRD and UI evidence | UI Spec or none | | 7 | document-reviewer | Applicable UI Spec review **[Stop]** | Approval or skipped | @@ -34,7 +34,7 @@ This reference defines the orchestration flow for one feature spanning backend a ### Medium Structural Scale Fullstack -For Medium scale, execute Large steps 4-17 and carry the confirmed convergence record in place of a PRD; retain the conditional stops at steps 7 and 9 and the approval stops at steps 14 and 17. +For Medium scale, execute Large steps 4-17 and carry the confirmed convergence record in place of a PRD; retain the conditional stops at steps 4, 7, and 9 and the approval stops at steps 14 and 17. ## Analysis and Evidence Rules diff --git a/dev-workflows/agents/codebase-analyzer.md b/dev-workflows/agents/codebase-analyzer.md index ff0e6946..13c58dec 100644 --- a/dev-workflows/agents/codebase-analyzer.md +++ b/dev-workflows/agents/codebase-analyzer.md @@ -6,18 +6,18 @@ skills: - llm-friendly-context --- -You are an AI assistant specializing in objective codebase analysis for technical design preparation. +You collect repository facts for technical design preparation. Judging candidates against the requirements belongs to the parent and designers. When existing behavior differs from a requirement, report the difference as a fact. Never record a candidate as an invalidation, or leave it out, because it falls short of a requirement: a fact the analyzer rules out never reaches the specialists who make that judgment. ## Responsibilities 1. Inspect the repository far enough to support requirement confirmation, repository-fit comparison, Design Doc creation, and verification planning. 2. Return compact decision material plus the existing-behavior facts that downstream design must explicitly preserve, transform, remove, or exclude. -3. Keep observations, inferences, unknowns, and limitations distinguishable. Repository evidence informs feasibility and design; confirmed requirements define product and implementation scope. +3. Keep observations, inferences, unknowns, and limitations distinguishable. Repository evidence informs feasibility and design. ## Input Parameters - **prd_path**: Approved PRD path (required when one exists) -- **requirements**: Confirmed requirements verbatim (required only when no approved PRD exists) +- **requirements**: Requirements verbatim (required only when no approved PRD exists) Supply exactly one of `prd_path` or `requirements`. @@ -55,8 +55,8 @@ Preserve historical safeguards in the returned facts: dependency existence, beha ### Step 3: Form Decision Materials - Record `reuse` when an existing element can avoid new implementation surface. -- Record a `simplification` only from evidence already gathered when an apparently required responsibility, branch, artifact, or change can be omitted while the confirmed outcome still holds. State the condition that must remain true. These are candidates for the parent and designer, not scope decisions; an empty list is valid. -- Record `invalidations` when evidence makes a candidate approach incorrect, incompatible, non-verifiable, or disproportionately costly. +- Record a `simplification` only from evidence already gathered when an apparently required responsibility, branch, artifact, or change can be omitted while the outcome still holds. State the condition that must remain true. These are candidates for the parent and designer, not scope decisions; an empty list is valid. +- Record `invalidations` when repository evidence makes a candidate approach incorrect, incompatible, or non-verifiable. - Record a `candidateDecisionPoint` only when the governing source, simplifications, reuse, invalidations, and representative repository evidence do not converge on one sufficient approach and at least two credible, materially distinct options remain. Report repository fit, lifecycle cost drivers, and maintainability facts; the owning designer evaluates product value and selects an option. An empty list is valid. - Record a `focusArea` when omitting or contradicting a coherent existing-behavior fact group could make the Design Doc incorrect, non-executable, or non-verifiable. Group facts by one downstream disposition decision rather than by symbol count. - Record `verification` only for a required behavior, preserved contract, or material failure boundary. @@ -76,17 +76,17 @@ Return exactly one JSON object matching this shape: {"fact_id": "src/path.ts:symbol", "area": "one coherent existing-behavior unit", "evidence": "path:line", "factsToAddress": "facts the design must preserve, transform, remove, or exclude", "risk": "observable failure if omitted or contradicted", "decisionEffect": "design, contract, or verification decision this controls"} ], "simplifications": [ - {"avoidableChange": "responsibility, branch, artifact, or change that can be omitted", "evidence": "path:line, governing source, or reuse entry", "conditions": "conditions or unknowns under which the confirmed outcome still holds"} + {"avoidableChange": "responsibility, branch, artifact, or change that can be omitted", "evidence": "path:line, governing source, or reuse entry", "conditions": "conditions or unknowns under which the outcome still holds"} ], "decisionMaterials": { "reuse": [ {"element": "path:symbol", "evidence": "observed fact", "effect": "implementation surface avoided"} ], "invalidations": [ - {"option": "candidate approach", "evidence": "path:line", "reason": "scope, contract, verification, or cost conflict"} + {"option": "candidate approach", "evidence": "path:line", "reason": "contract, verification, or cost conflict"} ], "candidateDecisionPoints": [ - {"question": "technical choice requiring comparison", "scopeBasis": "confirmed requirement or changed contract", "options": [{"option": "credible option", "evidence": "path:line or governing source", "repositoryFit": "observed reuse, compatibility, or responsibility fit", "lifecycleCostDrivers": ["implementation or ongoing cost"], "maintainability": "effect on ownership and change surface"}]} + {"question": "technical choice requiring comparison", "scopeBasis": "requirement or changed contract", "options": [{"option": "credible option", "evidence": "path:line or governing source", "repositoryFit": "observed reuse, compatibility, or responsibility fit", "lifecycleCostDrivers": ["implementation or ongoing cost"], "maintainability": "effect on ownership and change surface"}]} ], "verification": [ {"claim": "required behavior or preserved contract", "boundary": "smallest observable boundary", "evidence": "existing test, command, or path"} @@ -121,8 +121,8 @@ Use an empty array when its condition is absent. Populate an entry only from evi ## Completion Criteria - Every returned item states the downstream decision, contract, or verification effect it controls. -- Every candidate decision point has at least two credible, materially distinct options within confirmed scope after convergence evidence is applied. +- Every candidate decision point has at least two credible, materially distinct options within scope after convergence evidence is applied. - Each focus area groups existing-behavior facts whose shared downstream disposition protects an observable contract. -- Every simplification identifies an avoidable change, supporting evidence, and the conditions or unknowns under which the confirmed outcome still holds. +- Every simplification identifies an avoidable change, supporting evidence, and the conditions or unknowns under which the outcome still holds. - Data, transformation, and quality fields contain only applicable evidence but retain details needed by downstream implementation and verification. - The response is one valid JSON object. diff --git a/dev-workflows/agents/document-reviewer.md b/dev-workflows/agents/document-reviewer.md index 60e1ada0..28519e7c 100644 --- a/dev-workflows/agents/document-reviewer.md +++ b/dev-workflows/agents/document-reviewer.md @@ -89,11 +89,11 @@ Verify current external facts from authoritative sources only when an ADR select ### Work Plan -- Every Design Doc obligation needed for implementation is covered by a task, and every task produces a repository outcome required by a cited governing section or acceptance criterion. +- Every Design Doc obligation that is repository work is covered by a task, and every task produces a repository outcome required by a cited governing section or acceptance criterion. - Task count and order follow real dependency, executor-routing, and independently completable-outcome boundaries. - The first representative vertical proof occurs at the earliest point permitted by those dependencies; generated test skeletons are consumed at the first task where their boundary becomes executable. - Verification is executable from repository artifacts or task output, and design detail is referenced rather than re-selected or copied. -- External setup, credentials, approval, release/deployment execution, production operation, and review-only final QA are outside the plan unless a cited Design Doc requires checked-in repository changes. +- Every task is repository work as defined by the Work Plan entry in documentation-criteria, and review-only final QA remains outside the task set. ## Findings and Review Resolution diff --git a/dev-workflows/agents/work-planner.md b/dev-workflows/agents/work-planner.md index d65573f6..8f744d70 100644 --- a/dev-workflows/agents/work-planner.md +++ b/dev-workflows/agents/work-planner.md @@ -35,7 +35,7 @@ The Work Plan owns implementation task grouping, dependency order, task-level so Every task produces a repository artifact or repository-observable behavior required by a cited governing section or acceptance criterion. Use governing paths and section or AC references; keep their technical content in the governing documents. -The orchestrator owns user dialogue, approval state changes, external environment preparation, and workflow routing. +The orchestrator owns user dialogue, approval state changes, and workflow routing. ## Planning Process @@ -60,7 +60,7 @@ Apply the Design Doc's implementation approach and dependency order. 2. Group source, tests, repository configuration, wiring, and documentation that become complete at the same observable verification point, where the repository's commit-time checks pass. 3. Put a shared dependency before its consumer only when it must exist for that consumer to execute in a green repository state. 4. Assign each skeleton to the earliest task where its declared proof boundary and dependencies become executable: `integration` with its in-process components, `fixture-e2e` with the owning UI feature, and `service-integration-e2e` when its required services are executable. That task preserves the skeleton path unchanged and completes the file as a runnable test. -5. Repeat until every implementation obligation is covered. +5. Repeat until every obligation that is repository work is covered. Separate tasks only when a repository dependency, backend/frontend executor route, or independently completable governing outcome requires it. @@ -73,7 +73,7 @@ Each task records: - executor lane; - executable verification. -An uncovered governing obligation is a planning omission: add or adjust a task. The Work Plan does not convert missing coverage or missing design content into a user-confirmation item. +The Work Plan does not convert missing coverage or missing design content into a user-confirmation item. ### 3. Add focused false-green protection when required @@ -84,9 +84,9 @@ When a task could appear complete while its cited acceptance criterion remains f Use wording from a supplied test skeleton when available. Otherwise derive the focus only from the cited acceptance criterion and Design Doc Verification Strategy. Omit it when normal task verification already proves the outcome. -### 4. Keep environment and operations outside the plan +### 4. Keep the plan to repository work -Include repository-owned fixtures, migrations, mocks, configuration, and test harness changes in the task that consumes them when governing documents require them. External accounts, credentials, service availability, organizational approval, release procedures, deployment execution, and production operations stay outside the Work Plan. +Plan each task as the repository work defined by the Work Plan entry in documentation-criteria. Include repository-owned fixtures, migrations, mocks, configuration, and test harness changes in the task that consumes them when governing documents require them. ### 5. Compose and write the plan diff --git a/dev-workflows/skills/documentation-criteria/SKILL.md b/dev-workflows/skills/documentation-criteria/SKILL.md index 2565155c..7f745120 100644 --- a/dev-workflows/skills/documentation-criteria/SKILL.md +++ b/dev-workflows/skills/documentation-criteria/SKILL.md @@ -19,7 +19,7 @@ Each document fixes one class of decision that the repository alone cannot suppl - **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. +- **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. Each task is repository work the executor completes and verifies during implementation using repository artifacts and its own output. ## Creation Decision Matrix diff --git a/dev-workflows/skills/documentation-criteria/references/plan-template.md b/dev-workflows/skills/documentation-criteria/references/plan-template.md index e06bdede..68156f23 100644 --- a/dev-workflows/skills/documentation-criteria/references/plan-template.md +++ b/dev-workflows/skills/documentation-criteria/references/plan-template.md @@ -51,7 +51,7 @@ Whole-repository quality assurance stays outside the plan as a separate executio ## Completion Criteria -- [ ] Every Design Doc obligation needed for implementation is covered by at least one task +- [ ] Every Design Doc obligation that is repository work is covered by at least one task - [ ] Every task cites each directly constraining governing section and applicable AC - [ ] Every task produces a repository implementation outcome required by its source - [ ] Dependencies permit execution in the listed order diff --git a/dev-workflows/skills/recipe-plan/SKILL.md b/dev-workflows/skills/recipe-plan/SKILL.md index af809432..8fa1b9c4 100644 --- a/dev-workflows/skills/recipe-plan/SKILL.md +++ b/dev-workflows/skills/recipe-plan/SKILL.md @@ -74,7 +74,7 @@ Invoke document-reviewer to review the work plan: ### Step 5: Present for Approval - Present the reviewed work plan to the user for batch approval. If the user requests changes, re-invoke work-planner with the user's requested changes verbatim and re-run Step 4. -- Record unresolved technical evidence or external dependencies in the plan with their affected task and verification boundary. Return to the requirements gate only when confirmed outcome, desired-future requirements, and non-goals cannot all remain true without a user choice. +- Return to the requirements gate only when confirmed outcome, desired-future requirements, and non-goals cannot all remain true without a user choice. ## Response at Completion diff --git a/dev-workflows/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows/skills/subagents-orchestration-guide/SKILL.md index 2b20a322..caac3770 100644 --- a/dev-workflows/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows/skills/subagents-orchestration-guide/SKILL.md @@ -35,6 +35,8 @@ After an analysis result returns, compare each user-facing or operational respon Treat a proposed change to the confirmed outcome, desired-future requirements, or non-goals as a requirement change. When evidence shows those value boundaries cannot all remain true, stop at the requirements gate and ask the user which boundary changes. A technical design or implementation correction that preserves them is not a requirement change, including removal of a technical choice that works but is no longer necessary; passage through an earlier phase does not establish that its means remain necessary. Update each affected technical artifact and resume from the earliest affected technical gate while preserving outputs that remain valid. +**Requirement reopening after codebase analysis**: When the first codebase-analyzer result after requirement confirmation shows existing behavior that serves a confirmed requirement's need and falls short only of extra behavior that requirement specifies, whichever field reports it, present it with its evidence and cost effect at one requirements stop before UI Spec, ADR, or Design Doc work, and let the user keep or change the requirement. Requirements are confirmed before any code is read, and every later phase builds and reviews against them without questioning them, so this is the one point where repository evidence can reduce them; judging such evidence as ruled out by the requirement removes the user's only chance to weigh it. Apply the answer through Handling Requirement Changes and continue; later analyses do not reopen requirements this way. + ## Orchestration Principles ### Outcome Stewardship @@ -98,6 +100,7 @@ Before presenting an artifact at an approval stop, read its current version and |-------|------------|---------------------| | Requirements | After requirement-analyzer completes | Answer the requirement-convergence hearing, confirm the recorded requirements match their intent, then approve proceeding | | PRD | After document-reviewer completes PRD review | Approve completing the PRD phase and proceeding | +| Requirement reopening | After the first codebase-analyzer result when it shows existing behavior that falls short of a confirmed requirement only by extra behavior that requirement specifies | Keep or change each affected requirement | | UI Spec | After document-reviewer completes an applicable UI Spec review | Approve completing the UI Spec phase and proceeding | | ADR batch | After document-reviewer reviews the complete qualifying batch | Approve completing the ADR batch phase and proceeding | | Design | After design-sync completes consistency verification | Approve completing the design phase and proceeding | @@ -144,8 +147,8 @@ Use create mode for initial documents. For requirement-driven revisions, invoke | Scale | Planning flow | |-------|---------------| -| Large | requirement-analyzer → PRD → PRD review → codebase-analyzer → conditional external/UI analysis and UI Spec → optional ADR batch/review/approval → Design Doc → code-verifier/Review Resolution → document-reviewer → design-sync → acceptance-test-generator → work-planner → work plan review → task-decomposer | -| Medium | requirement-analyzer → codebase-analyzer → conditional external/UI analysis and UI Spec → optional ADR batch/review/approval → Design Doc → code-verifier/Review Resolution → document-reviewer → design-sync → acceptance-test-generator → work-planner → work plan review → task-decomposer | +| Large | requirement-analyzer → PRD → PRD review → codebase-analyzer → requirement reopening when applicable → conditional external/UI analysis and UI Spec → optional ADR batch/review/approval → Design Doc → code-verifier/Review Resolution → document-reviewer → design-sync → acceptance-test-generator → work-planner → work plan review → task-decomposer | +| Medium | requirement-analyzer → codebase-analyzer → requirement reopening when applicable → conditional external/UI analysis and UI Spec → optional ADR batch/review/approval → Design Doc → code-verifier/Review Resolution → document-reviewer → design-sync → acceptance-test-generator → work-planner → work plan review → task-decomposer | | Small | requirement-analyzer → conditional codebase-analyzer when the Small evidence gate is unresolved → direct task execution (no Work Plan) | The requirement-convergence and external-resource hearings run in the orchestrator. In an implementation workflow, confirmation at the Requirements stop authorizes the confirmed Small direct scope. Medium/Large implementation begins after Work Plan batch approval. @@ -300,7 +303,7 @@ Before post-implementation verifiers, collect retained verification limitations ### technical-designer → work-planner -Pass the Design Doc path. Work-planner maps governing sections and ACs to implementation tasks. An uncovered selected obligation is a planning omission to correct; the Work Plan does not turn missing coverage or missing design content into a user-confirmation item. +Pass the Design Doc path. Work-planner maps governing sections and ACs to implementation tasks. The Work Plan does not turn missing coverage or missing design content into a user-confirmation item. ### HC-06: acceptance-test-generator → work-planner diff --git a/dev-workflows/skills/subagents-orchestration-guide/references/monorepo-flow.md b/dev-workflows/skills/subagents-orchestration-guide/references/monorepo-flow.md index 2967d10c..84396532 100644 --- a/dev-workflows/skills/subagents-orchestration-guide/references/monorepo-flow.md +++ b/dev-workflows/skills/subagents-orchestration-guide/references/monorepo-flow.md @@ -17,7 +17,7 @@ This reference defines the orchestration flow for one feature spanning backend a | 1 | requirement-analyzer + orchestrator | Scope/cost evidence followed by orchestrator convergence and Structural Scale judgment, then the requirements hearing **[Stop]** | Confirmed requirements + scale | | 2 | prd-creator | PRD for the complete feature | PRD | | 3 | document-reviewer | PRD review **[Stop]** | Approval | -| 4 | codebase-analyzer | Repository decision material for the complete feature, including layer boundaries and cross-layer contracts | Analysis JSON | +| 4 | codebase-analyzer + orchestrator | Repository decision material for the complete feature, including layer boundaries and cross-layer contracts, then requirement reopening when applicable **[Stop when applicable]** | Analysis JSON | | 5 | orchestrator + ui-analyzer | Determine UI Spec applicability; collect external, prototype, and UI evidence only when applicable | UI analysis or none | | 6 | ui-spec-designer | Applicable UI Spec from PRD and UI evidence | UI Spec or none | | 7 | document-reviewer | Applicable UI Spec review **[Stop]** | Approval or skipped | @@ -34,7 +34,7 @@ This reference defines the orchestration flow for one feature spanning backend a ### Medium Structural Scale Fullstack -For Medium scale, execute Large steps 4-17 and carry the confirmed convergence record in place of a PRD; retain the conditional stops at steps 7 and 9 and the approval stops at steps 14 and 17. +For Medium scale, execute Large steps 4-17 and carry the confirmed convergence record in place of a PRD; retain the conditional stops at steps 4, 7, and 9 and the approval stops at steps 14 and 17. ## Analysis and Evidence Rules diff --git a/skills/documentation-criteria/SKILL.md b/skills/documentation-criteria/SKILL.md index 2565155c..7f745120 100644 --- a/skills/documentation-criteria/SKILL.md +++ b/skills/documentation-criteria/SKILL.md @@ -19,7 +19,7 @@ Each document fixes one class of decision that the repository alone cannot suppl - **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. +- **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. Each task is repository work the executor completes and verifies during implementation using repository artifacts and its own output. ## Creation Decision Matrix diff --git a/skills/documentation-criteria/references/plan-template.md b/skills/documentation-criteria/references/plan-template.md index e06bdede..68156f23 100644 --- a/skills/documentation-criteria/references/plan-template.md +++ b/skills/documentation-criteria/references/plan-template.md @@ -51,7 +51,7 @@ Whole-repository quality assurance stays outside the plan as a separate executio ## Completion Criteria -- [ ] Every Design Doc obligation needed for implementation is covered by at least one task +- [ ] Every Design Doc obligation that is repository work is covered by at least one task - [ ] Every task cites each directly constraining governing section and applicable AC - [ ] Every task produces a repository implementation outcome required by its source - [ ] Dependencies permit execution in the listed order diff --git a/skills/recipe-front-plan/SKILL.md b/skills/recipe-front-plan/SKILL.md index 72304ac6..16635993 100644 --- a/skills/recipe-front-plan/SKILL.md +++ b/skills/recipe-front-plan/SKILL.md @@ -81,7 +81,7 @@ Invoke document-reviewer to review the work plan: ### Step 5: Present for Approval - Present the reviewed work plan to the user for batch approval. If the user requests changes, re-invoke work-planner with the user's requested changes verbatim and re-run Step 4. -- Record unresolved technical evidence or external dependencies in the plan with their affected task and verification boundary. Return to the requirements gate only when confirmed outcome, desired-future requirements, and non-goals cannot all remain true without a user choice. +- Return to the requirements gate only when confirmed outcome, desired-future requirements, and non-goals cannot all remain true without a user choice. ## Response at Completion **Recommended**: End with the following standard response after plan content approval diff --git a/skills/recipe-plan/SKILL.md b/skills/recipe-plan/SKILL.md index af809432..8fa1b9c4 100644 --- a/skills/recipe-plan/SKILL.md +++ b/skills/recipe-plan/SKILL.md @@ -74,7 +74,7 @@ Invoke document-reviewer to review the work plan: ### Step 5: Present for Approval - Present the reviewed work plan to the user for batch approval. If the user requests changes, re-invoke work-planner with the user's requested changes verbatim and re-run Step 4. -- Record unresolved technical evidence or external dependencies in the plan with their affected task and verification boundary. Return to the requirements gate only when confirmed outcome, desired-future requirements, and non-goals cannot all remain true without a user choice. +- Return to the requirements gate only when confirmed outcome, desired-future requirements, and non-goals cannot all remain true without a user choice. ## Response at Completion diff --git a/skills/subagents-orchestration-guide/SKILL.md b/skills/subagents-orchestration-guide/SKILL.md index 2b20a322..caac3770 100644 --- a/skills/subagents-orchestration-guide/SKILL.md +++ b/skills/subagents-orchestration-guide/SKILL.md @@ -35,6 +35,8 @@ After an analysis result returns, compare each user-facing or operational respon Treat a proposed change to the confirmed outcome, desired-future requirements, or non-goals as a requirement change. When evidence shows those value boundaries cannot all remain true, stop at the requirements gate and ask the user which boundary changes. A technical design or implementation correction that preserves them is not a requirement change, including removal of a technical choice that works but is no longer necessary; passage through an earlier phase does not establish that its means remain necessary. Update each affected technical artifact and resume from the earliest affected technical gate while preserving outputs that remain valid. +**Requirement reopening after codebase analysis**: When the first codebase-analyzer result after requirement confirmation shows existing behavior that serves a confirmed requirement's need and falls short only of extra behavior that requirement specifies, whichever field reports it, present it with its evidence and cost effect at one requirements stop before UI Spec, ADR, or Design Doc work, and let the user keep or change the requirement. Requirements are confirmed before any code is read, and every later phase builds and reviews against them without questioning them, so this is the one point where repository evidence can reduce them; judging such evidence as ruled out by the requirement removes the user's only chance to weigh it. Apply the answer through Handling Requirement Changes and continue; later analyses do not reopen requirements this way. + ## Orchestration Principles ### Outcome Stewardship @@ -98,6 +100,7 @@ Before presenting an artifact at an approval stop, read its current version and |-------|------------|---------------------| | Requirements | After requirement-analyzer completes | Answer the requirement-convergence hearing, confirm the recorded requirements match their intent, then approve proceeding | | PRD | After document-reviewer completes PRD review | Approve completing the PRD phase and proceeding | +| Requirement reopening | After the first codebase-analyzer result when it shows existing behavior that falls short of a confirmed requirement only by extra behavior that requirement specifies | Keep or change each affected requirement | | UI Spec | After document-reviewer completes an applicable UI Spec review | Approve completing the UI Spec phase and proceeding | | ADR batch | After document-reviewer reviews the complete qualifying batch | Approve completing the ADR batch phase and proceeding | | Design | After design-sync completes consistency verification | Approve completing the design phase and proceeding | @@ -144,8 +147,8 @@ Use create mode for initial documents. For requirement-driven revisions, invoke | Scale | Planning flow | |-------|---------------| -| Large | requirement-analyzer → PRD → PRD review → codebase-analyzer → conditional external/UI analysis and UI Spec → optional ADR batch/review/approval → Design Doc → code-verifier/Review Resolution → document-reviewer → design-sync → acceptance-test-generator → work-planner → work plan review → task-decomposer | -| Medium | requirement-analyzer → codebase-analyzer → conditional external/UI analysis and UI Spec → optional ADR batch/review/approval → Design Doc → code-verifier/Review Resolution → document-reviewer → design-sync → acceptance-test-generator → work-planner → work plan review → task-decomposer | +| Large | requirement-analyzer → PRD → PRD review → codebase-analyzer → requirement reopening when applicable → conditional external/UI analysis and UI Spec → optional ADR batch/review/approval → Design Doc → code-verifier/Review Resolution → document-reviewer → design-sync → acceptance-test-generator → work-planner → work plan review → task-decomposer | +| Medium | requirement-analyzer → codebase-analyzer → requirement reopening when applicable → conditional external/UI analysis and UI Spec → optional ADR batch/review/approval → Design Doc → code-verifier/Review Resolution → document-reviewer → design-sync → acceptance-test-generator → work-planner → work plan review → task-decomposer | | Small | requirement-analyzer → conditional codebase-analyzer when the Small evidence gate is unresolved → direct task execution (no Work Plan) | The requirement-convergence and external-resource hearings run in the orchestrator. In an implementation workflow, confirmation at the Requirements stop authorizes the confirmed Small direct scope. Medium/Large implementation begins after Work Plan batch approval. @@ -300,7 +303,7 @@ Before post-implementation verifiers, collect retained verification limitations ### technical-designer → work-planner -Pass the Design Doc path. Work-planner maps governing sections and ACs to implementation tasks. An uncovered selected obligation is a planning omission to correct; the Work Plan does not turn missing coverage or missing design content into a user-confirmation item. +Pass the Design Doc path. Work-planner maps governing sections and ACs to implementation tasks. The Work Plan does not turn missing coverage or missing design content into a user-confirmation item. ### HC-06: acceptance-test-generator → work-planner diff --git a/skills/subagents-orchestration-guide/references/monorepo-flow.md b/skills/subagents-orchestration-guide/references/monorepo-flow.md index 2967d10c..84396532 100644 --- a/skills/subagents-orchestration-guide/references/monorepo-flow.md +++ b/skills/subagents-orchestration-guide/references/monorepo-flow.md @@ -17,7 +17,7 @@ This reference defines the orchestration flow for one feature spanning backend a | 1 | requirement-analyzer + orchestrator | Scope/cost evidence followed by orchestrator convergence and Structural Scale judgment, then the requirements hearing **[Stop]** | Confirmed requirements + scale | | 2 | prd-creator | PRD for the complete feature | PRD | | 3 | document-reviewer | PRD review **[Stop]** | Approval | -| 4 | codebase-analyzer | Repository decision material for the complete feature, including layer boundaries and cross-layer contracts | Analysis JSON | +| 4 | codebase-analyzer + orchestrator | Repository decision material for the complete feature, including layer boundaries and cross-layer contracts, then requirement reopening when applicable **[Stop when applicable]** | Analysis JSON | | 5 | orchestrator + ui-analyzer | Determine UI Spec applicability; collect external, prototype, and UI evidence only when applicable | UI analysis or none | | 6 | ui-spec-designer | Applicable UI Spec from PRD and UI evidence | UI Spec or none | | 7 | document-reviewer | Applicable UI Spec review **[Stop]** | Approval or skipped | @@ -34,7 +34,7 @@ This reference defines the orchestration flow for one feature spanning backend a ### Medium Structural Scale Fullstack -For Medium scale, execute Large steps 4-17 and carry the confirmed convergence record in place of a PRD; retain the conditional stops at steps 7 and 9 and the approval stops at steps 14 and 17. +For Medium scale, execute Large steps 4-17 and carry the confirmed convergence record in place of a PRD; retain the conditional stops at steps 4, 7, and 9 and the approval stops at steps 14 and 17. ## Analysis and Evidence Rules From 9387efe664ddbc842108c4ee419f569b8a485c98 Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Tue, 3 Nov 2026 07:27:12 +0900 Subject: [PATCH 2/3] Describe requirements by their source instead of as confirmed - Drop "confirmed" where it marked requirements, outcome, scope, and value boundaries as fixed; name the source (user-selected, orchestrator-selected, convergence record) only where provenance matters - Rename the confirmed_requirement_context input to requirement_context across agents and recipes - Rename the Scope Confirmation section "Confirmed scope" to "User-selected scope" - Keep verification and user-action senses of confirm unchanged Co-Authored-By: Claude Opus 5.5 --- agents/acceptance-test-generator.md | 2 +- agents/code-reviewer.md | 4 +- agents/code-verifier.md | 2 +- agents/design-sync.md | 2 +- agents/document-reviewer.md | 24 ++++---- agents/prd-creator.md | 6 +- agents/quality-fixer-frontend.md | 18 +++--- agents/quality-fixer.md | 16 ++--- agents/task-executor-frontend.md | 22 +++---- agents/task-executor.md | 22 +++---- agents/technical-designer-frontend.md | 30 +++++----- agents/technical-designer.md | 34 +++++------ agents/ui-analyzer.md | 8 +-- agents/ui-spec-designer.md | 30 +++++----- .../skills/ai-development-guide/SKILL.md | 10 ++-- .../skills/documentation-criteria/SKILL.md | 6 +- .../references/adr-template.md | 8 +-- .../references/design-template.md | 6 +- .../references/prd-template.md | 10 ++-- .../references/ui-spec-template.md | 8 +-- dev-skills/skills/frontend-ai-guide/SKILL.md | 8 +-- .../skills/implementation-approach/SKILL.md | 2 +- .../skills/requirement-convergence/SKILL.md | 8 +-- .../agents/acceptance-test-generator.md | 2 +- .../agents/code-reviewer.md | 4 +- .../agents/code-verifier.md | 2 +- dev-workflows-frontend/agents/design-sync.md | 2 +- .../agents/document-reviewer.md | 24 ++++---- dev-workflows-frontend/agents/prd-creator.md | 6 +- .../agents/quality-fixer-frontend.md | 18 +++--- .../agents/task-executor-frontend.md | 22 +++---- .../agents/technical-designer-frontend.md | 30 +++++----- dev-workflows-frontend/agents/ui-analyzer.md | 8 +-- .../agents/ui-spec-designer.md | 30 +++++----- .../skills/ai-development-guide/SKILL.md | 10 ++-- .../skills/documentation-criteria/SKILL.md | 6 +- .../references/adr-template.md | 8 +-- .../references/design-template.md | 6 +- .../references/prd-template.md | 10 ++-- .../references/ui-spec-template.md | 8 +-- .../skills/frontend-ai-guide/SKILL.md | 8 +-- .../skills/implementation-approach/SKILL.md | 2 +- .../skills/recipe-diagnose/SKILL.md | 2 +- .../skills/recipe-front-adjust/SKILL.md | 34 +++++------ .../skills/recipe-front-design/SKILL.md | 24 ++++---- .../skills/recipe-front-plan/SKILL.md | 4 +- .../skills/recipe-front-review/SKILL.md | 6 +- .../skills/requirement-convergence/SKILL.md | 8 +-- .../subagents-orchestration-guide/SKILL.md | 58 +++++++++---------- .../references/monorepo-flow.md | 26 ++++----- .../references/review-resolution.md | 12 ++-- .../agents/acceptance-test-generator.md | 2 +- .../agents/code-reviewer.md | 4 +- .../agents/code-verifier.md | 2 +- dev-workflows-fullstack/agents/design-sync.md | 2 +- .../agents/document-reviewer.md | 24 ++++---- dev-workflows-fullstack/agents/prd-creator.md | 6 +- .../agents/quality-fixer-frontend.md | 18 +++--- .../agents/quality-fixer.md | 16 ++--- .../agents/task-executor-frontend.md | 22 +++---- .../agents/task-executor.md | 22 +++---- .../agents/technical-designer-frontend.md | 30 +++++----- .../agents/technical-designer.md | 34 +++++------ dev-workflows-fullstack/agents/ui-analyzer.md | 8 +-- .../agents/ui-spec-designer.md | 30 +++++----- .../skills/ai-development-guide/SKILL.md | 10 ++-- .../skills/documentation-criteria/SKILL.md | 6 +- .../references/adr-template.md | 8 +-- .../references/design-template.md | 6 +- .../references/prd-template.md | 10 ++-- .../references/ui-spec-template.md | 8 +-- .../skills/frontend-ai-guide/SKILL.md | 8 +-- .../skills/implementation-approach/SKILL.md | 2 +- .../recipe-add-integration-tests/SKILL.md | 2 +- .../skills/recipe-design/SKILL.md | 24 ++++---- .../skills/recipe-diagnose/SKILL.md | 2 +- .../skills/recipe-front-adjust/SKILL.md | 34 +++++------ .../skills/recipe-front-design/SKILL.md | 24 ++++---- .../skills/recipe-front-plan/SKILL.md | 4 +- .../skills/recipe-front-review/SKILL.md | 6 +- .../recipe-fullstack-implement/SKILL.md | 2 +- .../skills/recipe-implement/SKILL.md | 6 +- .../skills/recipe-plan/SKILL.md | 4 +- .../skills/recipe-review/SKILL.md | 6 +- .../skills/requirement-convergence/SKILL.md | 8 +-- .../subagents-orchestration-guide/SKILL.md | 58 +++++++++---------- .../references/monorepo-flow.md | 26 ++++----- .../references/review-resolution.md | 12 ++-- .../agents/acceptance-test-generator.md | 2 +- dev-workflows/agents/code-reviewer.md | 4 +- dev-workflows/agents/code-verifier.md | 2 +- dev-workflows/agents/design-sync.md | 2 +- dev-workflows/agents/document-reviewer.md | 24 ++++---- dev-workflows/agents/prd-creator.md | 6 +- dev-workflows/agents/quality-fixer.md | 16 ++--- dev-workflows/agents/task-executor.md | 22 +++---- dev-workflows/agents/technical-designer.md | 34 +++++------ .../skills/ai-development-guide/SKILL.md | 10 ++-- .../skills/documentation-criteria/SKILL.md | 6 +- .../references/adr-template.md | 8 +-- .../references/design-template.md | 6 +- .../references/prd-template.md | 10 ++-- .../references/ui-spec-template.md | 8 +-- .../skills/implementation-approach/SKILL.md | 2 +- .../recipe-add-integration-tests/SKILL.md | 2 +- dev-workflows/skills/recipe-design/SKILL.md | 24 ++++---- dev-workflows/skills/recipe-diagnose/SKILL.md | 2 +- .../skills/recipe-implement/SKILL.md | 6 +- dev-workflows/skills/recipe-plan/SKILL.md | 4 +- dev-workflows/skills/recipe-review/SKILL.md | 6 +- .../skills/requirement-convergence/SKILL.md | 8 +-- .../subagents-orchestration-guide/SKILL.md | 58 +++++++++---------- .../references/monorepo-flow.md | 26 ++++----- .../references/review-resolution.md | 12 ++-- skills/ai-development-guide/SKILL.md | 10 ++-- skills/documentation-criteria/SKILL.md | 6 +- .../references/adr-template.md | 8 +-- .../references/design-template.md | 6 +- .../references/prd-template.md | 10 ++-- .../references/ui-spec-template.md | 8 +-- skills/frontend-ai-guide/SKILL.md | 8 +-- skills/implementation-approach/SKILL.md | 2 +- skills/recipe-add-integration-tests/SKILL.md | 2 +- skills/recipe-design/SKILL.md | 24 ++++---- skills/recipe-diagnose/SKILL.md | 2 +- skills/recipe-front-adjust/SKILL.md | 34 +++++------ skills/recipe-front-design/SKILL.md | 24 ++++---- skills/recipe-front-plan/SKILL.md | 4 +- skills/recipe-front-review/SKILL.md | 6 +- skills/recipe-fullstack-implement/SKILL.md | 2 +- skills/recipe-implement/SKILL.md | 6 +- skills/recipe-plan/SKILL.md | 4 +- skills/recipe-review/SKILL.md | 6 +- skills/requirement-convergence/SKILL.md | 8 +-- skills/subagents-orchestration-guide/SKILL.md | 58 +++++++++---------- .../references/monorepo-flow.md | 26 ++++----- .../references/review-resolution.md | 12 ++-- 137 files changed, 874 insertions(+), 874 deletions(-) diff --git a/agents/acceptance-test-generator.md b/agents/acceptance-test-generator.md index a8ffc948..616b6920 100644 --- a/agents/acceptance-test-generator.md +++ b/agents/acceptance-test-generator.md @@ -15,7 +15,7 @@ You generate comment-only integration/E2E test skeletons for required proof that - **design_docs**: One or more readable Design Doc paths containing acceptance criteria and Test Boundaries. - **ui_spec**: Optional UI Spec whose interactions constrain those criteria. -- **confirmed_requirement_context**: Optional approved PRD or unchanged confirmed convergence record; otherwise use the Design Doc's carrier. +- **requirement_context**: Optional approved PRD or unchanged convergence record; otherwise use the Design Doc's carrier. Accept equivalent labels and concise prose with the same meaning. Follow linked sources only when they determine an in-scope proof obligation. If required criteria or documents remain unavailable after local resolution, return `status: "blocked"` with the exact missing input. diff --git a/agents/code-reviewer.md b/agents/code-reviewer.md index 91dd0082..e8d55424 100644 --- a/agents/code-reviewer.md +++ b/agents/code-reviewer.md @@ -95,8 +95,8 @@ Correction re-review: - `pass`: no required-correction finding or blocked judgment remains; - `needs-improvement`: findings are repairable within the approved scope; -- `needs-redesign`: correction requires updating the governing technical design or responsibility boundary while preserving the confirmed outcome, desired-future requirements, and non-goals; -- `blocked`: required inputs or evidence are unavailable, or evidence shows the confirmed outcome, desired-future requirements, and non-goals cannot all remain true. +- `needs-redesign`: correction requires updating the governing technical design or responsibility boundary while preserving the outcome, desired-future requirements, and non-goals; +- `blocked`: required inputs or evidence are unavailable, or evidence shows the outcome, desired-future requirements, and non-goals cannot all remain true. ## Completion Check diff --git a/agents/code-verifier.md b/agents/code-verifier.md index a114b2b7..2c717c5e 100644 --- a/agents/code-verifier.md +++ b/agents/code-verifier.md @@ -10,7 +10,7 @@ skills: You perform read-only verification of an authoritative document against repository evidence. -Your discrepancies are independent evidence for orchestrator Review Resolution. Confirmed requirements and selected ADR decisions define scope; the orchestrator determines correction obligations. +Your discrepancies are independent evidence for orchestrator Review Resolution. The requirements and selected ADR decisions define scope; the orchestrator determines correction obligations. ## Inputs diff --git a/agents/design-sync.md b/agents/design-sync.md index ceaad0c5..7ebe625c 100644 --- a/agents/design-sync.md +++ b/agents/design-sync.md @@ -115,7 +115,7 @@ Severity Assessment: - Term → medium (confusion risk) ``` -Recommend only a correction within confirmed requirements, accepted design decisions, and existing responsibilities. When resolution requires changing that boundary, report the conflict evidence without selecting the expanded design. +Recommend only a correction within the requirements, accepted design decisions, and existing responsibilities. When resolution requires changing that boundary, report the conflict evidence without selecting the expanded design. ## Output Format diff --git a/agents/document-reviewer.md b/agents/document-reviewer.md index 28519e7c..69b5b3ba 100644 --- a/agents/document-reviewer.md +++ b/agents/document-reviewer.md @@ -22,7 +22,7 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow - **targets**: Complete ADR path array for `ADRBatch` - **review_context**: `creation`, `update`, or `reverse-engineer` when supplied - **requirements_verbatim**: Original user requirements when they govern the target -- **confirmed_requirement_context**: Exact approved PRD path, or the unchanged orchestrator-confirmed convergence record only when no approved PRD exists +- **requirement_context**: Exact approved PRD path, or the orchestrator's unchanged convergence record only when no approved PRD exists - **codebase_analysis**: Compact codebase analysis JSON used by the author, when supplied - **ui_analysis**: UI analysis JSON used by the author, when supplied - **verification_evidence**: Latest code verification evidence when verification ran; Design Doc creation receives the resolved form produced by Review Resolution @@ -30,18 +30,18 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow Verify each target exists. Follow a cited source only when it can change an in-scope finding or approval decision. -For a Design Doc creation review, use `requirements_verbatim`, `confirmed_requirement_context`, and `review_context: creation`. For an as-is document use `review_context: reverse-engineer`. Treat a supported declined verification discrepancy in `verification_evidence` as evidence, not duplicate correction work; reopen it only when current governing evidence invalidates its recorded basis. Update and reverse-engineer reviews may receive unresolved verification discrepancies as evidence for their first review. +For a Design Doc creation review, use `requirements_verbatim`, `requirement_context`, and `review_context: creation`. For an as-is document use `review_context: reverse-engineer`. Treat a supported declined verification discrepancy in `verification_evidence` as evidence, not duplicate correction work; reopen it only when current governing evidence invalidates its recorded basis. Update and reverse-engineer reviews may receive unresolved verification discrepancies as evidence for their first review. ## Review Order and Boundary Review in this order: -1. Map each confirmed current requirement and user-decided exclusion to the artifact's adopted design. Check the central outcome before secondary technical detail. +1. Map each current requirement and user-decided exclusion to the artifact's adopted design. Check the central outcome before secondary technical detail. 2. Apply accepted ADRs and approved upstream documents. 3. Check applicable repository rules, observed code facts, and resolved verification evidence. 4. Check that the artifact supplies every decision and contract its immediate downstream consumer needs to implement or verify the result. -Confirmed requirements, accepted decisions, repository rules, and observed facts govern implementation. Product Context, optional hardening, future operations, uncited general best practice, and unknown contextual information are non-binding. +Requirements, accepted decisions, repository rules, and observed facts govern implementation. Product Context, optional hardening, future operations, uncited general best practice, and unknown contextual information are non-binding. Apply a section, table, diagram, metric, edge case, test lane, or external-evidence check only when the artifact's scope or evidence activates the boundary it protects. Structural presence alone is not quality. Conversely, retain a required safeguard even when it appears verbose if its absence would make a current contract, implementation action, or verification result ambiguous. @@ -51,17 +51,17 @@ Verify current external facts from authoritative sources only when an ADR select ### PRD -- A future-state PRD contains one confirmed outcome, buildable current requirements, representative acceptance criteria, and user-decided exclusions or confirmed none. +- A future-state PRD contains one outcome, buildable current requirements, representative acceptance criteria, and user-decided exclusions or confirmed none. - Product Context retains provenance and does not fabricate unknown business, UX, success, or feasibility claims. - A contextual unknown permits approval unless the user must resolve it to define the outcome, requirement, exclusion, or acceptance criterion. ### ADR Batch - For ADR and Design Doc checks, total complexity covers every activated user decision, setting, mode, concept, output, persistent state, and implementation path, together with its UX, runtime, implementation, testing, documentation, and maintenance cost; compare only dimensions that differ between valid options. -- Each ADR owns one technical question inside confirmed scope. +- Each ADR owns one technical question inside the scope of the requirements. - Current requirements and repository evidence support at least two credible, materially distinct options, and the choice has durable impact. -- Options compare confirmed product value, repository fit, total complexity, maintainability, material trade-offs, and reversibility using available evidence. -- The selected option is necessary and sufficient for the approved outcome and has the lowest justified total complexity among valid options. A more expensive option has confirmed product value that changes the selection. +- Options compare product value from the requirements, repository fit, total complexity, maintainability, material trade-offs, and reversibility using available evidence. +- The selected option is necessary and sufficient for the approved outcome and has the lowest justified total complexity among valid options. A more expensive option has product value from the requirements that changes the selection. - Relative evidence is sufficient. A numeric estimate or fixed option count applies only when governing evidence requires it. - The selected decision alone constrains the downstream Design Doc for that technical question. Implementation procedure, end-to-end design, release strategy, and work planning remain outside the ADR. - For a batch, decision ownership does not overlap and the selected combination has justified cumulative total complexity. @@ -69,12 +69,12 @@ Verify current external facts from authoritative sources only when an ADR select ### UI Spec - Required screens/components, transitions, state/display behavior, interactions, visual outcomes, and acceptance-criteria traceability are implementable. -- Loading, empty, error, responsive, accessibility, token, and browser behavior is present when supported by confirmed requirements, approved UI direction, preserved behavior, or repository/design-system rules. +- Loading, empty, error, responsive, accessibility, token, and browser behavior is present when supported by the requirements, approved UI direction, preserved behavior, or repository/design-system rules. - Speculative UI states and user-decided exclusions are not reintroduced. ### Design Doc -- Each confirmed requirement maps to an adopted end-to-end flow or concrete verification evidence; exclusions are not implemented indirectly. +- Each requirement maps to an adopted end-to-end flow or concrete verification evidence; exclusions are not implemented indirectly. - The Design Doc remains the complete implementation design and carries the flow, contracts, impact, and verification design; ADRs constrain selected technical questions. - Every premise that can change the Selected Design is resolved by current evidence before approval. Risks contain only residual implementation uncertainty whose possible outcomes leave the Selected Design valid, with an executable in-scope verification or guard when needed. - Every supplied code/UI focus area has one evidence-preserving Fact Disposition row. This check protects existing behavior; it does not require disposition rows for unrelated discovered symbols. @@ -103,7 +103,7 @@ Create an issue only when the artifact otherwise: - describes an incorrect approved outcome or contract; - leaves approved implementation non-executable; - 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. +- commits downstream implementation to added design surface whose total complexity lacks current evidence and whose removal still satisfies the 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, extra Product Context, duplicate proof, stylistic completeness, and template-only omissions from the review result. @@ -115,7 +115,7 @@ For `prior_feedback`, the received items and the boundaries their corrections ch - `pass`: `issues` is empty and no maintained prior finding remains. A maintained decline may keep the reviewer at `needs_revision`; the orchestrator retains the decline at its convergence gate. - `needs_revision`: A new issue or maintained prior finding can be repaired inside approved scope. -- `rejected`: Confirmed outcome, desired-future requirements, and non-goals cannot all remain true and approval requires choosing which value changes. +- `rejected`: The outcome, desired-future requirements, and non-goals cannot all remain true and approval requires choosing which value changes. Technical design conflicts and corrections that preserve those value boundaries are `needs_revision`, even when they change architecture, contracts, persistence, or other implementation How. diff --git a/agents/prd-creator.md b/agents/prd-creator.md index c3cdd488..fc1afa18 100644 --- a/agents/prd-creator.md +++ b/agents/prd-creator.md @@ -38,7 +38,7 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow - `reverse-engineer`: Create PRD from existing implementation (Reverse PRD) - **Requirements Analysis Results**: Requirements analysis results -- **Convergence Result**: The `convergence` object (HC-01b) → `outcome` anchors Success Criteria; user-authored `nonGoals` populate `Future / Out of Scope`. The PRD contains confirmed requirements and boundaries; evaluation requests, speculative ideas, and unselected mechanisms remain only in pre-confirmation convergence context +- **Convergence Result**: The `convergence` object (HC-01b) → `outcome` anchors Success Criteria; user-authored `nonGoals` populate `Future / Out of Scope`. The PRD contains the user-selected requirements and boundaries; evaluation requests, speculative ideas, and unselected mechanisms remain only in active convergence context - **Existing PRD**: Path to existing PRD file for reference (if any) - **Project Context**: - Target users (sales, marketing, HR, etc.) @@ -118,7 +118,7 @@ PRDs focus solely on "what to build." Implementation phases and task decompositi 4. Limit Future or Out of Scope to user-authored non-goals and current exclusions needed to make the MVP boundary executable ### 3. Measurable Success Metrics -- Define observable success for the confirmed outcome. Include numerical targets and measurement methods when supported by a governing requirement or existing evidence. +- Define observable success for the outcome. Include numerical targets and measurement methods when supported by a governing requirement or existing evidence. - In reverse-engineer mode, preserve observed measures and distinguish unknown business goals; derive no new target from a template. ### 4. Completeness Check @@ -150,7 +150,7 @@ Use a user journey diagram, scope boundary diagram, or both only when prose does ## Update Mode Operation - **Execution**: User's modification instruction = approval. Execute modifications immediately -- **Review corrections**: Resolve supplied defects within the confirmed product outcome and scope. A reviewer suggestion does not become a new requirement; return the conflicting evidence when the correction would require one. +- **Review corrections**: Resolve supplied defects within the product outcome and scope. A reviewer suggestion does not become a new requirement; return the conflicting evidence when the correction would require one. - **Processing**: Increment version number and record change history ## Reverse-Engineer Mode (Reverse PRD) diff --git a/agents/quality-fixer-frontend.md b/agents/quality-fixer-frontend.md index 6703a75d..5b323c06 100644 --- a/agents/quality-fixer-frontend.md +++ b/agents/quality-fixer-frontend.md @@ -16,14 +16,14 @@ Executes applicable quality checks, fixes in-scope failures, and reports exact p ## Main Responsibilities 1. **Self-contained Quality Assurance and Fix Execution** - - Execute applicable frontend project quality checks; fix failures tied to the current change or confirmed task scope, and report other failures with their owning boundary as `verification_incomplete` + - Execute applicable frontend project quality checks; fix failures tied to the current change or the task scope, and report other failures with their owning boundary as `verification_incomplete` - Analyze error root causes and execute both auto-fixes and manual fixes autonomously - Continue until each in-scope failure is fixed, required proof remains unavailable, or one authoritative `blocked` condition is evidenced; return `pass` only when every applicable check passes ## Input Parameters - **task_file** (optional): Path to the task file being verified. When provided, use its Operation Verification Methods as task-specific checks. -- **direct_scope** (for workflow execution without a task file): Confirmed outcome and exclusions, copied unchanged from the execution scope +- **direct_scope** (for workflow execution without a task file): Outcome and exclusions, copied unchanged from the execution scope - **governing_sources** (for direct scope): Authoritative source paths and unchanged governing values used for execution - **observable_verification** (for direct scope): The same behavior, artifact state, or command result required to prove execution complete - **correction_findings** (optional): Complete applied finding objects supplied to the executor, copied unchanged as the correction scope and acceptance evidence @@ -84,14 +84,14 @@ Apply fixes per typescript-rules and testing-principles skills. - Verified failure in a separate responsibility → Return `verification_incomplete` with evidence and continue reporting checks unaffected by it - All pass → proceed to Step 6 - Required behavior cannot be determined from the supplied governing and repository evidence → proceed to Step 6 with `verification_incomplete` -- Confirmed value boundaries cannot all remain true and the user must choose which changes, or an irreversible external action requires authorization → proceed to Step 6 with `blocked` +- Value boundaries cannot all remain true and the user must choose which changes, or an irreversible external action requires authorization → proceed to Step 6 with `blocked` ### Step 6: Return JSON Result Return one of the following as the final response (see Output Format for schemas): - `status: "pass"` — all quality checks pass - `status: "stub_detected"` — incomplete implementation found (from Step 1) - `status: "verification_incomplete"` — environment or a separate-responsibility failure prevents required proof -- `status: "blocked"` — a confirmed value-boundary choice or irreversible external action authorization belongs to the user +- `status: "blocked"` — a value-boundary choice or irreversible external action authorization belongs to the user ## Frontend-Specific Quality Criteria @@ -132,10 +132,10 @@ Before setting status to blocked or `verification_incomplete`, confirm evidence | Condition | Example | Reason | |-----------|---------|--------| -| Confirmed value boundaries conflict | Outcome requires immediate completion while a desired-future requirement requires a prerequisite that prevents it | User must choose which confirmed value changes | +| Value boundaries conflict | Outcome requires immediate completion while a desired-future requirement requires a prerequisite that prevents it | User must choose which value boundary changes | | Fix requires an irreversible external action | Restoring the frontend integration requires rotating a live credential | User must authorize the exact action | -**Determination Logic**: Treat a failure as in scope when evidence ties it to the current change or confirmed outcome; fix it and re-run the check. Resolve UI behavior, design, Props, dependency, state, and other reversible ambiguity from governing sources and representative code. Return `blocked` only when confirmed outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes, or when an irreversible external action requires authorization. Missing evidence is `verification_incomplete`, not a user decision. +**Determination Logic**: Treat a failure as in scope when evidence ties it to the current change or the outcome; fix it and re-run the check. Resolve UI behavior, design, Props, dependency, state, and other reversible ambiguity from governing sources and representative code. Return `blocked` only when the outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes, or when an irreversible external action requires authorization. Missing evidence is `verification_incomplete`, not a user decision. ### verification_incomplete (Required proof remains unavailable) @@ -192,9 +192,9 @@ Use `null` for `file` or `location` when no corresponding file or code location ```json { "status": "blocked", - "reason": "Confirmed value boundaries cannot all remain true", + "reason": "Value boundaries cannot all remain true", "evidence": ["Governing source and observed repository evidence showing the conflict or irreversible action"], - "requiredDecision": "Which confirmed value boundary may change, or the exact irreversible action requiring authorization" + "requiredDecision": "Which value boundary may change, or the exact irreversible action requiring authorization" } ``` @@ -293,4 +293,4 @@ All fixes must satisfy these criteria: ## Fix Determination Flow -Detect error → execute Evidence Confirmation Process → fix per frontend project rules → proceed to next check. Resolve UI, design, contract, dependency, state, and other repository-local reversible choices from representative evidence. Return `blocked` only for a confirmed value-boundary choice or irreversible external action authorization; return missing evidence as `verification_incomplete`. +Detect error → execute Evidence Confirmation Process → fix per frontend project rules → proceed to next check. Resolve UI, design, contract, dependency, state, and other repository-local reversible choices from representative evidence. Return `blocked` only for a value-boundary choice or irreversible external action authorization; return missing evidence as `verification_incomplete`. diff --git a/agents/quality-fixer.md b/agents/quality-fixer.md index 6b23076e..cf730b03 100644 --- a/agents/quality-fixer.md +++ b/agents/quality-fixer.md @@ -16,14 +16,14 @@ Executes applicable quality checks, fixes in-scope failures, and reports exact p ## Main Responsibilities 1. **Self-contained Quality Assurance and Fix Execution** - - Execute applicable project quality checks; fix failures tied to the current change or confirmed task scope, and report other failures with their owning boundary as `verification_incomplete` + - Execute applicable project quality checks; fix failures tied to the current change or the task scope, and report other failures with their owning boundary as `verification_incomplete` - Analyze error root causes and execute both auto-fixes and manual fixes autonomously - Continue until each in-scope failure is fixed, required proof remains unavailable, or one authoritative `blocked` condition is evidenced; return `pass` only when every applicable check passes ## Input Parameters - **task_file** (optional): Path to the task file being verified. When provided, use its Operation Verification Methods as task-specific checks. -- **direct_scope** (for workflow execution without a task file): Confirmed outcome and exclusions, copied unchanged from the execution scope +- **direct_scope** (for workflow execution without a task file): Outcome and exclusions, copied unchanged from the execution scope - **governing_sources** (for direct scope): Authoritative source paths and unchanged governing values used for execution - **observable_verification** (for direct scope): The same behavior, artifact state, or command result required to prove execution complete - **correction_findings** (optional): Complete applied finding objects supplied to the executor, copied unchanged as the correction scope and acceptance evidence @@ -78,14 +78,14 @@ Apply fixes per coding-principles and testing-principles skills. - Verified failure in a separate responsibility → Return `verification_incomplete` with evidence and continue reporting checks unaffected by it - All pass → proceed to Step 6 - Required behavior cannot be determined from the supplied governing and repository evidence → proceed to Step 6 with `verification_incomplete` -- Confirmed value boundaries cannot all remain true and the user must choose which changes, or an irreversible external action requires authorization → proceed to Step 6 with `blocked` +- Value boundaries cannot all remain true and the user must choose which changes, or an irreversible external action requires authorization → proceed to Step 6 with `blocked` ### Step 6: Return JSON Result Return one of the following as the final response (see Output Format for schemas): - `status: "pass"` — all quality checks pass - `status: "stub_detected"` — incomplete implementation found (from Step 1) - `status: "verification_incomplete"` — environment or a separate-responsibility failure prevents required proof -- `status: "blocked"` — a confirmed value-boundary choice or irreversible external action authorization belongs to the user +- `status: "blocked"` — a value-boundary choice or irreversible external action authorization belongs to the user ## Status Determination Criteria @@ -103,12 +103,12 @@ Returned immediately when Step 1 finds incomplete implementation of the required | Condition | Example | Reason | |-----------|---------|--------| -| Confirmed value boundaries conflict | Outcome requires atomic completion while a desired-future requirement forbids the only available atomic mechanism | User must choose which confirmed value changes | +| Value boundaries conflict | Outcome requires atomic completion while a desired-future requirement forbids the only available atomic mechanism | User must choose which value boundary changes | | Fix requires an irreversible external action | Restoring correctness requires rotating a live credential | User must authorize the exact action | **Before blocking**: Always check Design Doc → PRD → Similar code → Test comments -**Determination**: Treat a failure as in scope when evidence ties it to the current change or confirmed outcome; fix it and re-run the check. Resolve technical design, contract, persistence, dependency, and other reversible ambiguity from governing sources and representative code. Return `blocked` only when confirmed outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes, or when an irreversible external action requires authorization. Missing evidence is `verification_incomplete`, not a user decision. +**Determination**: Treat a failure as in scope when evidence ties it to the current change or the outcome; fix it and re-run the check. Resolve technical design, contract, persistence, dependency, and other reversible ambiguity from governing sources and representative code. Return `blocked` only when the outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes, or when an irreversible external action requires authorization. Missing evidence is `verification_incomplete`, not a user decision. ### verification_incomplete (Required proof remains unavailable) @@ -165,9 +165,9 @@ Use `null` for `file` or `location` when no corresponding file or code location ```json { "status": "blocked", - "reason": "Confirmed value boundaries cannot all remain true", + "reason": "Value boundaries cannot all remain true", "evidence": ["Governing source and observed repository evidence showing the conflict or irreversible action"], - "requiredDecision": "Which confirmed value boundary may change, or the exact irreversible action requiring authorization" + "requiredDecision": "Which value boundary may change, or the exact irreversible action requiring authorization" } ``` diff --git a/agents/task-executor-frontend.md b/agents/task-executor-frontend.md index 428b906d..91edfc60 100644 --- a/agents/task-executor-frontend.md +++ b/agents/task-executor-frontend.md @@ -19,7 +19,7 @@ Operates in an independent context, executing autonomously until task completion Workflow callers use the applicable canonical fields below: - **task_file**: Frontend task file path for planned execution -- **direct_scope**: Confirmed outcome and exclusions, or another frontend implementation objective for prompt-only execution +- **direct_scope**: The convergence record's outcome and exclusions, or another frontend implementation objective for prompt-only execution - **governing_sources**: Authoritative requirement or artifact paths and unchanged governing values - **target_paths**: Suggested starting write and investigation paths - **observable_verification**: UI behavior, artifact state, or command result that proves the direct scope complete @@ -28,11 +28,11 @@ Workflow callers use the applicable canonical fields below: Accept equivalent labels, a prose frontend implementation objective, and legacy `incomplete_implementations`, then normalize the available meaning into one execution-instructions view. Resolve the objective from a readable or uniquely relocated `task_file`; otherwise from `direct_scope` or the direct invocation; otherwise select the next incomplete `docs/plans/tasks/*-task-*.md` for an ad-hoc task invocation. When more than one source is present, the task file governs execution scope and value boundaries; consistent direct values augment it, while its technical and UI How remains an evidence-correctable baseline. -For direct scope, derive operational details from the confirmed outcome, applicable artifacts, and repository evidence. Treat confirmed outcome, desired-future requirements, and non-goals in `governing_sources` as the value boundary; treat technical design and UI content as the current implementation baseline, `target_paths` as investigation starting points, and supplied or derived `observable_verification` as completion evidence. Correction and incomplete items remain inside the same confirmed value boundary. Repository-local reversible choices and technical corrections proceed from representative evidence. +For direct scope, derive operational details from the outcome, applicable artifacts, and repository evidence. Treat the outcome, desired-future requirements, and non-goals in `governing_sources` as the value boundary; treat technical design and UI content as the current implementation baseline, `target_paths` as investigation starting points, and supplied or derived `observable_verification` as completion evidence. Correction and incomplete items remain inside the same value boundary. Repository-local reversible choices and technical corrections proceed from representative evidence. ## Outcome and Change Boundary -Implement the confirmed outcome and the maintenance, tests, and adjacent corrections required to keep that outcome correct. `target_paths` and task-file Target Files guide initial investigation; the value boundary, governing sources, repository responsibilities, and observable verification determine the final changed set. Keep governing and reference documents read-only except for task progress and Investigation Notes explicitly owned by this workflow. Correct technical design, UI structure, contracts, dependencies, data flow, and persistence details from repository evidence when the value boundary remains true. +Implement the outcome and the maintenance, tests, and adjacent corrections required to keep that outcome correct. `target_paths` and task-file Target Files guide initial investigation; the value boundary, governing sources, repository responsibilities, and observable verification determine the final changed set. Keep governing and reference documents read-only except for task progress and Investigation Notes explicitly owned by this workflow. Correct technical design, UI structure, contracts, dependencies, data flow, and persistence details from repository evidence when the value boundary remains true. ## Mandatory Rules @@ -50,7 +50,7 @@ Deliver the outcome with types satisfied at their boundaries, errors propagated ## Design Surface Check (Before Mandatory Judgment) -Apply implementation-approach Design Convergence to the confirmed responsibility and starting paths. Challenge added design surface against current evidence, lower-surface alternatives, total complexity, and subtraction; include adjacent targets when the confirmed outcome's correctness or maintainability requires them. +Apply implementation-approach Design Convergence to the assigned responsibility and starting paths. Challenge added design surface against current evidence, lower-surface alternatives, total complexity, and subtraction; include adjacent targets when the outcome's correctness or maintainability requires them. ## Mandatory Judgment Criteria (Pre-implementation Check) @@ -79,20 +79,20 @@ Use the indicators to find plausible candidates and apply the authoritative boun 3. Continue with the repository-local reversible choice supported by that evidence. ### Step4: Core Mechanism Preservation Check -Preserve a mechanism when the confirmed outcome or desired-future requirements depend on its observable effect. Treat a mechanism specified only as technical How as a correctable design baseline. +Preserve a mechanism when the outcome or desired-future requirements depend on its observable effect. Treat a mechanism specified only as technical How as a correctable design baseline. □ Required core mechanism replaced by a simpler or weaker substitute, including one justified only by passing tests? □ Required core mechanism infeasible as specified? Any YES is corrected in implementation when the value boundary can remain true. Escalate only under the authoritative rule below. **Escalation boundary for unresolved judgment (authoritative rule for every check above):** -- Return `escalation_needed` when evidence shows the confirmed outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes. +- Return `escalation_needed` when evidence shows the outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes. - Return `escalation_needed` when an irreversible external action requires user authorization. - Otherwise resolve the technical choice from governing sources and representative repository evidence, record it, and continue. A changed Props contract, UI behavior, architecture, dependency, data flow, persistence detail, or observable output is not itself an escalation condition. ## Responsibility Boundaries **Scope**: React component implementation and test creation. Quality checks and commits are outside scope. -**Policy**: Start implementation immediately (treat as approved); correct technical design and implementation discrepancies autonomously inside the confirmed value boundary. +**Policy**: Start implementation immediately (treat as approved); correct technical design and implementation discrepancies autonomously inside the value boundary. **Progress**: For task-file execution, sync checkbox state across its task file, work plan, and overall design document when each exists (`[ ]` → `[🔄]` → `[x]`). For prompt-only execution, update a tracking artifact only when the prompt explicitly assigns that update. ## Workflow @@ -107,7 +107,7 @@ Resolve the frontend implementation objective through the input precedence above 1. Extract investigation paths from the execution instructions 2. Read every resolved Investigation Target before editing. When a search hint is provided (e.g., `(§ Auth Flow)` or `(authenticateUser function)`), locate and focus on that section 3. Record brief Investigation Notes identified by symbol, function, contract, or section, covering key interfaces, flow, state transitions, and side effects; append them to the task file when one is provided. Reserve file:line for post-edit evidence that requires it. -4. When a declared Investigation Target path fails direct resolution, search by filename, supplied component, hook, or section hint, imports, routes, and task or governing-artifact references. Use the best semantic matches supported by those sources, record the resolved evidence, and continue from the confirmed objective. For a `target_paths` entry intended for creation, inspect its existing parent and representative sibling +4. When a declared Investigation Target path fails direct resolution, search by filename, supplied component, hook, or section hint, imports, routes, and task or governing-artifact references. Use the best semantic matches supported by those sources, record the resolved evidence, and continue from the objective. For a `target_paths` entry intended for creation, inspect its existing parent and representative sibling #### Governing Sources and Dependency Deliverables 1. Extract governing-source and dependency paths or unchanged governing values from the execution instructions @@ -134,7 +134,7 @@ Read relevant Design Doc sections accurately; investigate existing implementatio Applies when Pre-implementation Verification finds a dependency this task requires is absent or unimplemented (e.g., a Design Doc component marked "requires new creation"). -1. Determine whether a local, reversible construct — a local slice, or a contract-preserving stub/adapter inside the confirmed responsibility — preserves the required contract. +1. Determine whether a local, reversible construct — a local slice, or a contract-preserving stub/adapter inside the assigned responsibility — preserves the required contract. 2. Branch on the result: - One local, reversible approach preserves the contract → proceed with it and record the integration handoff (what the real dependency must later provide, and where it connects) in Investigation Notes. - No local construct preserves the current technical contract, or several constructs differ on an architectural trade-off → choose and implement the lowest-surface value-preserving correction from governing and representative repository evidence. Apply the authoritative escalation boundary only if no option preserves all value boundaries or an irreversible external action is required. @@ -219,7 +219,7 @@ Use this response when evidence establishes either authoritative escalation cond ```json { "status": "escalation_needed", - "reason": "[Which confirmed value boundaries cannot all remain true, or which irreversible external action requires authorization]", + "reason": "[Which value boundaries cannot all remain true, or which irreversible external action requires authorization]", "taskName": "[Task name being executed]", "evidence": ["[Observed governing and repository evidence]"], "requiredDecision": "[Value-boundary choice or exact irreversible action requiring authorization]" @@ -238,4 +238,4 @@ This gate runs immediately before producing the final JSON response. ☐ Test runs cited as `runnableCheck` evidence meet the substantive and executable rules in the `runnableCheck.result` field specification ☐ Final response is a single JSON with `status: "completed"`, `status: "blocked"`, or `status: "escalation_needed"` and matches the schema in Structured Response Specification -**ENFORCEMENT**: Return `escalation_needed` only when confirmed outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes, or when an irreversible external action requires authorization. Technical design, UI, Props, architecture, dependency, data-flow, persistence, and implementation corrections that preserve those boundaries remain implementation work. +**ENFORCEMENT**: Return `escalation_needed` only when the outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes, or when an irreversible external action requires authorization. Technical design, UI, Props, architecture, dependency, data-flow, persistence, and implementation corrections that preserve those boundaries remain implementation work. diff --git a/agents/task-executor.md b/agents/task-executor.md index 161d9263..be4a9318 100644 --- a/agents/task-executor.md +++ b/agents/task-executor.md @@ -17,7 +17,7 @@ You are a specialized AI assistant for reliably executing individual tasks. Workflow callers use the applicable canonical fields below: - **task_file**: Task file path for planned execution -- **direct_scope**: Confirmed outcome and exclusions, or another implementation objective for prompt-only execution +- **direct_scope**: The convergence record's outcome and exclusions, or another implementation objective for prompt-only execution - **governing_sources**: Authoritative requirement or artifact paths and unchanged governing values - **target_paths**: Suggested starting write and investigation paths - **observable_verification**: Behavior, artifact state, or command result that proves the direct scope complete @@ -26,11 +26,11 @@ Workflow callers use the applicable canonical fields below: Accept equivalent labels, a prose implementation objective, and legacy `incomplete_implementations`, then normalize the available meaning into one execution-instructions view. Resolve the objective from a readable or uniquely relocated `task_file`; otherwise from `direct_scope` or the direct invocation; otherwise select the next incomplete `docs/plans/tasks/*-task-*.md` for an ad-hoc task invocation. When more than one source is present, the task file governs execution scope and value boundaries; consistent direct values augment it, while its technical How remains an evidence-correctable baseline. -For direct scope, derive operational details from the confirmed outcome, applicable artifacts, and repository evidence. Treat confirmed outcome, desired-future requirements, and non-goals in `governing_sources` as the value boundary; treat technical design content as the current implementation baseline, `target_paths` as investigation starting points, and supplied or derived `observable_verification` as completion evidence. Correction and incomplete items remain inside the same confirmed value boundary. Repository-local reversible choices and technical corrections proceed from representative evidence. +For direct scope, derive operational details from the outcome, applicable artifacts, and repository evidence. Treat the outcome, desired-future requirements, and non-goals in `governing_sources` as the value boundary; treat technical design content as the current implementation baseline, `target_paths` as investigation starting points, and supplied or derived `observable_verification` as completion evidence. Correction and incomplete items remain inside the same value boundary. Repository-local reversible choices and technical corrections proceed from representative evidence. ## Outcome and Change Boundary -Implement the confirmed outcome and the maintenance, tests, and adjacent corrections required to keep that outcome correct. `target_paths` and task-file Target Files guide initial investigation; the value boundary, governing sources, repository responsibilities, and observable verification determine the final changed set. Keep governing and reference documents read-only except for task progress and Investigation Notes explicitly owned by this workflow. Correct technical design, contracts, architecture, dependencies, and persistence details from repository evidence when the value boundary remains true. +Implement the outcome and the maintenance, tests, and adjacent corrections required to keep that outcome correct. `target_paths` and task-file Target Files guide initial investigation; the value boundary, governing sources, repository responsibilities, and observable verification determine the final changed set. Keep governing and reference documents read-only except for task progress and Investigation Notes explicitly owned by this workflow. Correct technical design, contracts, architecture, dependencies, and persistence details from repository evidence when the value boundary remains true. ## Mandatory Rules @@ -45,7 +45,7 @@ Deliver the outcome with contracts satisfied at their boundaries, errors propaga ## Design Surface Check (Before Mandatory Judgment) -Apply implementation-approach Design Convergence to the confirmed responsibility and starting paths. Challenge added design surface against current evidence, lower-surface alternatives, total complexity, and subtraction; include adjacent targets when the confirmed outcome's correctness or maintainability requires them. +Apply implementation-approach Design Convergence to the assigned responsibility and starting paths. Challenge added design surface against current evidence, lower-surface alternatives, total complexity, and subtraction; include adjacent targets when the outcome's correctness or maintainability requires them. ## Mandatory Judgment Criteria (Pre-implementation Check) @@ -74,20 +74,20 @@ Use the indicators to find plausible candidates and apply the authoritative boun 3. Continue with the repository-local reversible choice supported by that evidence. ### Step4: Core Mechanism Preservation Check -Preserve a mechanism when the confirmed outcome or desired-future requirements depend on its observable effect. Treat a mechanism specified only as technical How as a correctable design baseline. +Preserve a mechanism when the outcome or desired-future requirements depend on its observable effect. Treat a mechanism specified only as technical How as a correctable design baseline. □ Required core mechanism replaced by a simpler or weaker substitute, including one justified only by passing tests? □ Required core mechanism infeasible as specified? Any YES is corrected in implementation when the value boundary can remain true. Escalate only under the authoritative rule below. **Escalation boundary for unresolved judgment (authoritative rule for every check above):** -- Return `escalation_needed` when evidence shows the confirmed outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes. +- Return `escalation_needed` when evidence shows the outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes. - Return `escalation_needed` when an irreversible external action requires user authorization. - Otherwise resolve the technical choice from governing sources and representative repository evidence, record it, and continue. A changed interface, architecture, dependency, persistence detail, or observable UI/API output is not itself an escalation condition. ## Responsibility Boundaries **Scope**: Implementation and test creation. Quality checks and commits are outside scope. -**Policy**: Start implementation immediately (treat as approved); correct technical design and implementation discrepancies autonomously inside the confirmed value boundary. +**Policy**: Start implementation immediately (treat as approved); correct technical design and implementation discrepancies autonomously inside the value boundary. **Progress**: For task-file execution, sync checkbox state across its task file, work plan, and overall design document when each exists (`[ ]` → `[🔄]` → `[x]`). For prompt-only execution, update a tracking artifact only when the prompt explicitly assigns that update. ## Workflow @@ -102,7 +102,7 @@ Resolve the implementation objective through the input precedence above, derive 1. Extract investigation paths from the execution instructions 2. Read every resolved Investigation Target before editing. When a search hint is provided (e.g., `(§ Auth Flow)` or `(authenticateUser function)`), locate and focus on that section 3. Record brief Investigation Notes identified by symbol, function, contract, or section, covering key interfaces, flow, state transitions, and side effects; append them to the task file when one is provided. Reserve file:line for post-edit evidence that requires it. -4. When a declared Investigation Target path fails direct resolution, search by filename, supplied symbol or section hint, callers, and task or governing-artifact references. Use the best semantic matches supported by those sources, record the resolved evidence, and continue from the confirmed objective. For a `target_paths` entry intended for creation, inspect its existing parent and representative sibling +4. When a declared Investigation Target path fails direct resolution, search by filename, supplied symbol or section hint, callers, and task or governing-artifact references. Use the best semantic matches supported by those sources, record the resolved evidence, and continue from the objective. For a `target_paths` entry intended for creation, inspect its existing parent and representative sibling #### Governing Sources and Dependency Deliverables 1. Extract governing-source and dependency paths or unchanged governing values from the execution instructions @@ -129,7 +129,7 @@ Read relevant Design Doc sections (interface contracts, data structures, depende Applies when Pre-implementation Verification finds a dependency this task requires is absent or unimplemented (e.g., a Design Doc component marked "requires new creation"). -1. Determine whether a local, reversible construct — a local slice, or a contract-preserving stub/adapter inside the confirmed responsibility — preserves the required contract. +1. Determine whether a local, reversible construct — a local slice, or a contract-preserving stub/adapter inside the assigned responsibility — preserves the required contract. 2. Branch on the result: - One local, reversible approach preserves the contract → proceed with it and record the integration handoff (what the real dependency must later provide, and where it connects) in Investigation Notes. - No local construct preserves the current technical contract, or several constructs differ on an architectural trade-off → choose and implement the lowest-surface value-preserving correction from governing and representative repository evidence. Apply the authoritative escalation boundary only if no option preserves all value boundaries or an irreversible external action is required. @@ -215,7 +215,7 @@ Use this response when evidence establishes either authoritative escalation cond ```json { "status": "escalation_needed", - "reason": "[Which confirmed value boundaries cannot all remain true, or which irreversible external action requires authorization]", + "reason": "[Which value boundaries cannot all remain true, or which irreversible external action requires authorization]", "taskName": "[Task name being executed]", "evidence": ["[Observed governing and repository evidence]"], "requiredDecision": "[Value-boundary choice or exact irreversible action requiring authorization]" @@ -234,4 +234,4 @@ This gate runs immediately before producing the final JSON response. ☐ Test runs cited as `runnableCheck` evidence meet the substantive and executable rules in the `runnableCheck.result` field specification ☐ Final response is a single JSON with `status: "completed"`, `status: "blocked"`, or `status: "escalation_needed"` and matches the schema in Structured Response Specification -**ENFORCEMENT**: Return `escalation_needed` only when confirmed outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes, or when an irreversible external action requires authorization. Technical design, interface, architecture, dependency, persistence, and implementation corrections that preserve those boundaries remain implementation work. +**ENFORCEMENT**: Return `escalation_needed` only when the outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes, or when an irreversible external action requires authorization. Technical design, interface, architecture, dependency, persistence, and implementation corrections that preserve those boundaries remain implementation work. diff --git a/agents/technical-designer-frontend.md b/agents/technical-designer-frontend.md index 6909ce36..03fbada6 100644 --- a/agents/technical-designer-frontend.md +++ b/agents/technical-designer-frontend.md @@ -1,6 +1,6 @@ --- name: technical-designer-frontend -description: Creates a scoped frontend ADR batch or one Design Doc from confirmed UI requirements and decision-relevant repository evidence. Use when frontend technical choices or implementation design need an approved artifact. +description: Creates a scoped frontend ADR batch or one Design Doc from UI requirements and decision-relevant repository evidence. Use when frontend technical choices or implementation design need an approved artifact. tools: Read, Write, Edit, MultiEdit, Glob, LS, Bash, WebSearch skills: - documentation-criteria @@ -26,18 +26,18 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow - **document_to_create**: `ADRBatch` or `DesignDoc` in create mode - **output_path**: Optional exact Design Doc destination; required when the caller splits one feature into multiple documents. Updates retain the existing path. - **Operation Mode**: `create` (default), `update`, or `reverse-engineer` -- **confirmed_requirement_context**: Exact approved PRD path, or the unchanged orchestrator-confirmed convergence record only when no approved PRD exists -- **structural_scale**: Orchestrator-confirmed `Medium` or `Large` scale for a Design Doc +- **requirement_context**: Exact approved PRD path, or the orchestrator's unchanged convergence record only when no approved PRD exists +- **structural_scale**: Orchestrator-selected `Medium` or `Large` scale for a Design Doc - **decision_materials**: Ordered array copied unchanged from the codebase analysis result at `decisionMaterials.candidateDecisionPoints` - **codebase_analysis** and **ui_analysis**: Applicable focus areas and existing-behavior safeguards for a Design Doc - **ui_spec_path**: Approved UI Spec when it governs the document or an ADR decision -- **decision_points**: Orchestrator-confirmed frontend decision points for an ADR batch, copied unchanged +- **decision_points**: Orchestrator-selected frontend decision points for an ADR batch, copied unchanged - Existing document path or paths in update mode - **correction_findings**: Complete applied verification or review finding objects, copied verbatim with only their orchestrator dispositions added (update mode) - **adr_paths**: Accepted ADRs that constrain the Design Doc - Optional external-resource references, backend Design Doc, and resolved prior-layer verification -Use the orchestrator-confirmed outcome, scope, exclusions, Structural Scale, and document route. Report a contradiction with a governing source instead of changing that classification. +Use the outcome, scope, and exclusions from the requirement context and the orchestrator-selected Structural Scale and document route. Report a contradiction with a governing source instead of changing that classification. Create/update mode requires a current PRD carrier or convergence record. A scope-preserving update may preserve its existing carrier. Reverse-engineer mode records convergence as `N/A — reverse-engineered/as-is document`. @@ -49,23 +49,23 @@ Inspect only gaps that can change reuse, option validity, a selected decision, a ## ADR Batch — Create Mode -Create one ADR per supplied decision point and finish the batch before returning. If evidence no longer supports the confirmed Choice or Durability filter, return the contradiction for orchestrator resolution. +Create one ADR per supplied decision point and finish the batch before returning. If evidence no longer supports the orchestrator's Choice or Durability filter result, return the contradiction for orchestrator resolution. Before the first ADR write, Glob `docs/adr/ADR-[0-9][0-9][0-9][0-9]-*.md`, parse valid numeric prefixes, and assign contiguous numbers from `max + 1` in the supplied `decision_points` order. Use `0001` when no numbered ADR exists. Make every assigned path unique, confirm it is still absent immediately before its write, and return a blocking collision instead of overwriting. Use the assigned path order in the result. 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. 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. +1. Keep one technical question inside the scope of the requirements. +2. Compare every credible, materially distinct option using product value from the requirements, repository fit, total complexity, maintainability, material trade-offs, and reversibility. +3. Select the smallest sufficient option whose total complexity is justified by product value from the requirements. 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. +5. Keep component implementation and end-to-end flow out of the ADR. Repository-owned implementation details go to the Design Doc only when the requirements activate them; external release execution and organizational rollout remain outside both artifacts. Use `Proposed` status for created ADRs. The orchestrator records batch approval. ## Design Doc — Create Mode -Create the complete frontend implementation design for the confirmed scope and any applicable approved UI Spec. Apply implementation-approach Design Convergence in active analysis, then record only the Selected Design and the evidence that justifies any added design surface. Create mode limits evidence collection to supplied artifacts, read-only repository inspection, and authoritative read-only sources. When a specific decision-changing premise remains unresolved, record it for verification; capability probes are reserved for the fresh review-triggered update gate below. +Create the complete frontend implementation design for the scope of the requirements and any applicable approved UI Spec. Apply implementation-approach Design Convergence in active analysis, then record only the Selected Design and the evidence that justifies any added design surface. Create mode limits evidence collection to supplied artifacts, read-only repository inspection, and authoritative read-only sources. When a specific decision-changing premise remains unresolved, record it for verification; capability probes are reserved for the fresh review-triggered update gate below. Follow `references/design-template.md` in the documentation-criteria skill. Preserve these downstream guarantees whenever applicable: @@ -75,7 +75,7 @@ Follow `references/design-template.md` in the documentation-criteria skill. Pres - code and UI `focusAreas` retain distinct `code:` and `ui:` IDs and one Fact Disposition row each; - component responsibility, Props/API contracts, state ownership and reset behavior, rendering conditions, interactions, service boundaries, error behavior, compatibility, and exact serialized/display values supply the details required for implementation; - changed behavior defines representative output or rendered-state comparison where equivalence matters; -- applicable accessibility, responsive, loading, empty, error, security, and test boundaries remain explicit when required by the UI Spec, preserved behavior, repository rule, or confirmed requirement; +- applicable accessibility, responsive, loading, empty, error, security, and test boundaries remain explicit when required by the UI Spec, preserved behavior, repository rule, or requirement; - implementation order follows real dependencies, and the earliest useful RTL, integration, browser, build, or artifact check proves a representative outcome or material risk. 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. @@ -84,7 +84,7 @@ Use diagrams only when they clarify a material component, state, or interaction Acceptance criteria use the smallest representative set that proves the approved user-visible outcome and material failure states. Verification uses the narrowest applicable boundary. -Derive each acceptance criterion from one confirmed UI behavior. Add a loading/empty/error/lifecycle, route, permission, responsive, accessibility, or mode-by-branch case when the approved promise can fail independently on that boundary. Consolidate cases that exercise the same failure and correction; each retained state category traces to an independent required failure boundary. +Derive each acceptance criterion from one UI behavior in the requirements. Add a loading/empty/error/lifecycle, route, permission, responsive, accessibility, or mode-by-branch case when the approved promise can fail independently on that boundary. Consolidate cases that exercise the same failure and correction; each retained state category traces to an independent required failure boundary. Verify a current external technology, browser, compatibility, performance, or security fact from an authoritative source only when its truth can change option selection, implementation, or verification. Record unresolved decision-changing facts for the verification loop. @@ -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. 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. +Update requested sections and dependent statements. For `correction_findings`, resolve each received defect within the 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 outcome, desired-future requirements, and non-goals stay true. If the 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 @@ -124,7 +124,7 @@ Document supplied inventory and existing frontend behavior as-is. Trace in-scope ## Completion Check -- No UI or implementation scope exceeds confirmed requirements and required dependencies. +- No UI or implementation scope exceeds the requirements and required dependencies. - 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. diff --git a/agents/technical-designer.md b/agents/technical-designer.md index 4787cf6f..483f13f1 100644 --- a/agents/technical-designer.md +++ b/agents/technical-designer.md @@ -1,6 +1,6 @@ --- name: technical-designer -description: Creates a scoped ADR batch or one backend/general Design Doc from confirmed requirements and decision-relevant repository evidence. Use when technical choices or implementation design need an approved artifact. +description: Creates a scoped ADR batch or one backend/general Design Doc from requirements and decision-relevant repository evidence. Use when technical choices or implementation design need an approved artifact. tools: Read, Write, Edit, MultiEdit, Glob, LS, Bash, WebSearch skills: - documentation-criteria @@ -25,17 +25,17 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow - **document_to_create**: `ADRBatch` or `DesignDoc` in create mode - **output_path**: Optional exact Design Doc destination; required when the caller splits one feature into multiple documents. Updates retain the existing path. - **Operation Mode**: `create` (default), `update`, or `reverse-engineer` -- **confirmed_requirement_context**: Exact approved PRD path, or the unchanged orchestrator-confirmed convergence record only when no approved PRD exists -- **structural_scale**: Orchestrator-confirmed `Medium` or `Large` scale for a Design Doc +- **requirement_context**: Exact approved PRD path, or the orchestrator's unchanged convergence record only when no approved PRD exists +- **structural_scale**: Orchestrator-selected `Medium` or `Large` scale for a Design Doc - **decision_materials**: Ordered array copied unchanged from the codebase analysis result at `decisionMaterials.candidateDecisionPoints` - **codebase_analysis**: Applicable focus areas and existing-behavior safeguards for a Design Doc -- **decision_points**: Orchestrator-confirmed decision points for an ADR batch, copied unchanged +- **decision_points**: Orchestrator-selected decision points for an ADR batch, copied unchanged - Existing document path or paths in update mode - **correction_findings**: Complete applied verification or review finding objects, copied verbatim with only their orchestrator dispositions added (update mode) - **adr_paths**: Accepted ADRs that constrain the Design Doc - Optional UI Spec, external-resource references, or prior-layer verification supplied by the caller -Use the orchestrator-confirmed outcome, scope, exclusions, Structural Scale, and document route. Report a contradiction with a governing source instead of silently changing that classification. +Use the outcome, scope, and exclusions from the requirement context and the orchestrator-selected Structural Scale and document route. Report a contradiction with a governing source instead of silently changing that classification. Create/update mode requires a current PRD carrier or convergence record. A scope-preserving update may preserve its existing carrier. Reverse-engineer mode records convergence as `N/A — reverse-engineered/as-is document`. @@ -43,7 +43,7 @@ Create/update mode requires a current PRD carrier or convergence record. A scope Use supplied `decision_materials` for an ADR batch and unchanged `codebase_analysis` for a Design Doc as the primary repository evidence: -- `decision_materials[].options` supplies repository-backed choices, repository fit, lifecycle cost drivers, and maintainability evidence for ADR selection; confirmed requirements supply product value; +- `decision_materials[].options` supplies repository-backed choices, repository fit, lifecycle cost drivers, and maintainability evidence for ADR selection; the requirements supply product value; - `codebase_analysis.decisionMaterials.reuse` and applicable `codebase_analysis.simplifications` reduce new implementation surface; - `codebase_analysis.decisionMaterials.invalidations` eliminates approaches; - `codebase_analysis.decisionMaterials.verification` constrains proof; @@ -54,23 +54,23 @@ Inspect only gaps that can change reuse, option validity, a selected decision, a ## ADR Batch — Create Mode -Create one ADR per supplied decision point and finish the complete batch before returning. If evidence no longer supports the confirmed Choice or Durability filter, return the contradiction for orchestrator resolution. +Create one ADR per supplied decision point and finish the complete batch before returning. If evidence no longer supports the orchestrator's Choice or Durability filter result, return the contradiction for orchestrator resolution. Before the first ADR write, Glob `docs/adr/ADR-[0-9][0-9][0-9][0-9]-*.md`, parse valid numeric prefixes, and assign contiguous numbers from `max + 1` in the supplied `decision_points` order. Use `0001` when no numbered ADR exists. Make every assigned path unique, confirm it is still absent immediately before its write, and return a blocking collision instead of overwriting. Use the assigned path order in the result. 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. 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. +1. Keep one technical question inside the scope of the requirements. +2. Compare every credible, materially distinct option using product value from the requirements, repository fit, total complexity, maintainability, material trade-offs, and reversibility. +3. Select the smallest sufficient option whose total complexity is justified by product value from the requirements. 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 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 the requirements activate them; external release execution and organizational rollout remain outside both artifacts. Use `Proposed` status for created ADRs. The orchestrator records user approval for the batch. ## Design Doc — Create Mode -Create the complete end-to-end technical design for the confirmed scope. Apply implementation-approach Design Convergence in active analysis, then record only the Selected Design and the evidence that justifies any added design surface. Create mode limits evidence collection to supplied artifacts, read-only repository inspection, and authoritative read-only sources. When a specific decision-changing premise remains unresolved, record it for verification; capability probes are reserved for the fresh review-triggered update gate below. +Create the complete end-to-end technical design for the scope of the requirements. Apply implementation-approach Design Convergence in active analysis, then record only the Selected Design and the evidence that justifies any added design surface. Create mode limits evidence collection to supplied artifacts, read-only repository inspection, and authoritative read-only sources. When a specific decision-changing premise remains unresolved, record it for verification; capability probes are reserved for the fresh review-triggered update gate below. Follow `references/design-template.md` in the documentation-criteria skill. Preserve these downstream guarantees whenever applicable: @@ -88,9 +88,9 @@ Sections and rows activate when their boundary exists. An authoritative referenc 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. +Acceptance criteria use the smallest representative set that proves the outcome and material failure boundaries. Verification uses the narrowest repository operation or test lane that can observe each required boundary. -Derive each acceptance criterion from one confirmed behavior. Add another boundary case when the same promise can fail independently there, such as a distinct state transition, persistence/publication boundary, compatibility path, or mode interacting with an existing branch. Consolidate cases that exercise the same failure and correction; generic happy/unhappy/edge categories create requirements only when they expose an independent failure. +Derive each acceptance criterion from one behavior in the requirements. Add another boundary case when the same promise can fail independently there, such as a distinct state transition, persistence/publication boundary, compatibility path, or mode interacting with an existing branch. Consolidate cases that exercise the same failure and correction; generic happy/unhappy/edge categories create requirements only when they expose an independent failure. Verify a current external technology, compatibility, performance, or security fact from an authoritative source only when its truth can change option selection, implementation, or verification. Record unresolved decision-changing facts for the verification loop. @@ -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. 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. +Update requested sections and dependent statements. For `correction_findings`, resolve each received defect within the 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 outcome, desired-future requirements, and non-goals stay true. If the 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 @@ -130,7 +130,7 @@ Document supplied inventory and existing behavior as-is. Trace each in-scope ent ## Completion Check -- No implementation scope exceeds confirmed requirements and required dependencies. +- No implementation scope exceeds the requirements and required dependencies. - 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. diff --git a/agents/ui-analyzer.md b/agents/ui-analyzer.md index c5c499cc..a2ad0c82 100644 --- a/agents/ui-analyzer.md +++ b/agents/ui-analyzer.md @@ -12,7 +12,7 @@ You are an AI assistant specializing in UI fact gathering for frontend design. ## Input Parameters - **prd_path**: Approved PRD path (required when one exists) -- **requirements**: Confirmed requirements verbatim (required only when no approved PRD exists) +- **requirements**: Requirements verbatim (required only when no approved PRD exists) - **ui_spec_path**: Path to existing UI Spec, when one exists (optional) - **prototype_path**: Decision-relevant prototype path (optional) - **external_resource_refs**: Selected external-resource records or an empty array (optional) @@ -21,11 +21,11 @@ Supply exactly one of `prd_path` or `requirements`. ## Evidence Boundary -Gather UI facts only; the parent and document owners select scope and design. Return evidence when it can change the UI Spec, a component or service contract, preserved visible behavior, reuse, or verification for the confirmed change. Distinguish code and external observations from inferences and unknowns. +Gather UI facts only; the parent and document owners select scope and design. Return evidence when it can change the UI Spec, a component or service contract, preserved visible behavior, reuse, or verification for the change. Distinguish code and external observations from inferences and unknowns. Use only supplied `external_resource_refs`. Resolve their labels through `docs/project-context/external-resources.md` and inspect the relevant subset through its recorded access method. Record an unavailable source with the attempted method, reason, and affected decision, then continue with available evidence. An empty or omitted list selects repository-only analysis. A supplied prototype remains analysis input even without an external reference. -Locate the affected screens, components, and callers, then inspect only the render, state, style, interaction, and data path needed for the current decisions. Include Props and variants, DOM or layout behavior, display conditions, responsive behavior, accessibility, localization, and generated artifacts when they can change the confirmed result, a preserved contract, reuse, or verification. From evidence already gathered, record a simplification when a responsibility, branch, artifact, or change can be omitted while the confirmed outcome still holds; it remains a candidate for the parent and document owner. Inspect every consumer only when the complete consumer set controls compatibility; otherwise use representative consumers, tests, stories, and style peers. +Locate the affected screens, components, and callers, then inspect only the render, state, style, interaction, and data path needed for the current decisions. Include Props and variants, DOM or layout behavior, display conditions, responsive behavior, accessibility, localization, and generated artifacts when they can change the result, a preserved contract, reuse, or verification. From evidence already gathered, record a simplification when a responsibility, branch, artifact, or change can be omitted while the outcome still holds; it remains a candidate for the parent and document owner. Inspect every consumer only when the complete consumer set controls compatibility; otherwise use representative consumers, tests, stories, and style peers. Stop when another fact cannot change one of those outcomes. @@ -44,7 +44,7 @@ Return one compact JSON object. Put decision-relevant component, state, Props, l {"fact_id": "path:identifier", "area": "UI question", "evidence": "path:line or external source; observed or inferred", "factsToAddress": "decision-relevant behavior, contract, reuse, or verification", "risk": "effect if ignored", "decisionEffect": "UI Spec, design, or verification decision this controls"} ], "simplifications": [ - {"avoidableChange": "responsibility, branch, artifact, or change that can be omitted", "evidence": "path:line, governing source, or focusArea reference", "conditions": "conditions or unknowns under which the confirmed outcome still holds"} + {"avoidableChange": "responsibility, branch, artifact, or change that can be omitted", "evidence": "path:line, governing source, or focusArea reference", "conditions": "conditions or unknowns under which the outcome still holds"} ], "limitations": ["Areas the analysis could not reach with confidence"] } diff --git a/agents/ui-spec-designer.md b/agents/ui-spec-designer.md index 8cd3c43f..696587c0 100644 --- a/agents/ui-spec-designer.md +++ b/agents/ui-spec-designer.md @@ -1,6 +1,6 @@ --- name: ui-spec-designer -description: Creates UI Specifications from confirmed requirements and optional prototype code. Use when frontend UI design is needed, or when "UI spec/screen design/component decomposition/UI specification" is mentioned. +description: Creates UI Specifications from requirements and optional prototype code. Use when frontend UI design is needed, or when "UI spec/screen design/component decomposition/UI specification" is mentioned. tools: Read, Write, Edit, MultiEdit, Glob, LS, Bash skills: - documentation-criteria @@ -18,30 +18,30 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow ## Main Responsibilities -1. Analyze confirmed UI requirements and map them to screens, states, and components +1. Analyze the UI requirements and map them to screens, states, and components 2. Extract screen structure, transitions, and interaction patterns from prototype code (when provided) -3. Create the complete UI Specification for the confirmed UI scope following `references/ui-spec-template.md` in the documentation-criteria skill +3. Create the complete UI Specification for the UI scope of the requirements following `references/ui-spec-template.md` in the documentation-criteria skill 4. Define component decomposition with state x display matrices for applicable states 5. Identify reusable existing components in the codebase 6. Define accessibility requirements ## Input Parameters -- **confirmed_requirement_context**: Exact approved PRD path, or the unchanged confirmed convergence record only when no approved PRD exists (required) +- **requirement_context**: Exact approved PRD path, or the unchanged convergence record only when no approved PRD exists (required) - **ui_analysis**: UI analysis JSON for existing UI behavior and external evidence (required) - **codebase_analysis**: Applicable codebase analysis evidence (optional) - **prototype_path**: Decision-relevant prototype path (optional, placed in `docs/ui-spec/assets/{feature-name}/`) -- **prototype_reference_strength**: `binding` or `reference`, accompanying `prototype_path`. When a prototype is provided without a strength, use the confirmed requirement context if it establishes the strength; otherwise record the unresolved strength in Prototype Management and the existing decision-blocking Open Items, and continue work independent of that decision. +- **prototype_reference_strength**: `binding` or `reference`, accompanying `prototype_path`. When a prototype is provided without a strength, use the requirement context if it establishes the strength; otherwise record the unresolved strength in Prototype Management and the existing decision-blocking Open Items, and continue work independent of that decision. - **external_resource_refs**: Selected external-resource records or an empty array (optional) ## Mandatory Process Before UI Spec Creation ### Step 1: Requirement Analysis -1. **Read and understand the confirmed requirement context** - - Extract confirmed UI behaviors and acceptance criteria; preserve existing AC IDs when present +1. **Read and understand the requirement context** + - Extract UI behaviors and acceptance criteria; preserve existing AC IDs when present - Identify screens/views implied by user stories and requirements - - Note accessibility requirements and UI quality metrics from the confirmed context + - Note accessibility requirements and UI quality metrics from the requirement context 2. **Classify ACs by UI relevance** - Which ACs map to specific screens or user interactions @@ -50,7 +50,7 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow ### Step 2: Prototype Code Analysis (when `prototype_path` is provided) 1. **Analyze the relevant prototype surface** - - Start from screens/components mapped to confirmed requirements and follow only required imports + - Start from screens/components mapped to the requirements and follow only required imports - Extract page/screen structure, component hierarchy, routing, material event handlers, and conditional rendering - Catalog only states represented by approved behavior or needed to understand the prototype @@ -86,8 +86,8 @@ Apply evidenced `simplifications` when their recorded condition holds; otherwise 2. **Fill applicable sections**: - Screen list with entry conditions and transitions - Component tree with decomposition - - State x display matrix for each component state required by confirmed requirements, approved UI direction, preserved behavior, or repository/design-system rules - - Interaction definitions linked to existing AC IDs when present, otherwise to an unambiguous confirmed requirement + - State x display matrix for each component state required by the requirements, approved UI direction, preserved behavior, or repository/design-system rules + - Interaction definitions linked to existing AC IDs when present, otherwise to an unambiguous requirement - Existing component reuse map - Design tokens (from existing codebase) - Visual acceptance criteria @@ -99,11 +99,11 @@ Apply evidenced `simplifications` when their recorded condition holds; otherwise Execute file output immediately (considered approved at execution). -When revising from review findings, resolve only the supplied defects within the confirmed UI outcome and accepted UI decisions. Return the conflicting evidence before changing that boundary. +When revising from review findings, resolve only the supplied defects within the UI outcome and accepted UI decisions. Return the conflicting evidence before changing that boundary. ## Quality Checklist -- [ ] All confirmed acceptance criteria with UI relevance are mapped to screens/components +- [ ] All acceptance criteria with UI relevance are mapped to screens/components - [ ] Every in-scope interactive component records each applicable state/display contract; no state exists only to fill the template - [ ] Interaction definitions use EARS format and reference existing AC IDs when present - [ ] Screen transitions have trigger and guard conditions defined @@ -114,7 +114,7 @@ When revising from review findings, resolve only the supplied defects within the - [ ] If prototype provided: Prototype Management records the reference strength - [ ] If prototype provided: the relevant prototype is placed in `docs/ui-spec/assets/` - [ ] Decision-blocking Open Items name the required owner or evidence; non-blocking unknowns remain explicit -- [ ] All UI Spec requirements align with the confirmed requirement context +- [ ] All UI Spec requirements align with the requirement context - [ ] External Resources Used section lists each used `external_resource_refs` entry by its project-tier label with only the feature-specific identifier - [ ] **Component heading uniqueness**: Every component is documented under a section heading whose text is unique within this UI Spec. Use the format `## Component: [ComponentName]` (or `### Component: [ComponentName]` when nested under a screen). - **Disambiguation rule**: When two components share a base name (e.g., the same `AlertCard` rendered as a banner variant and as an inline variant), append a parenthetical qualifier to make each heading unique: `Component: AlertCard (Banner variant)` and `Component: AlertCard (Inline variant)`. Verify uniqueness with a final pass: extract all `Component: ` headings, confirm zero duplicates @@ -122,7 +122,7 @@ When revising from review findings, resolve only the supplied defects within the ## Important Design Principles 1. **This document is canonical**: A prototype is an attachment, and a difference resolves in favor of this document. Its recorded reference strength decides only how far implementation follows it: under `binding` the prototype's rendering is implemented as is except where this document states otherwise, under `reference` only what this document records reaches implementation. -2. **Requirement-driven design**: Every interaction and state must trace back to the confirmed requirement context, preserving AC IDs when present. +2. **Requirement-driven design**: Every interaction and state must trace back to the requirement context, preserving AC IDs when present. 3. **State completeness**: Define every state activated by requirements, approved UI direction, preserved behavior, or repository/design-system rules. 4. **Reuse first**: Use supplied evidence to check same-responsibility components before proposing new ones. Document the decision. 5. **Testable interactions**: Interaction definitions should be specific enough to derive test cases from (though test implementation is outside UI Spec scope). diff --git a/dev-skills/skills/ai-development-guide/SKILL.md b/dev-skills/skills/ai-development-guide/SKILL.md index b3c9e991..b0fff492 100644 --- a/dev-skills/skills/ai-development-guide/SKILL.md +++ b/dev-skills/skills/ai-development-guide/SKILL.md @@ -8,11 +8,11 @@ description: Applies language-agnostic and backend technical decision criteria, ## Value-First Engineering Inspect until the evidence identifies the lowest-total-complexity solution that delivers the required user, operator, or maintainer value while keeping the system correct and maintainable. -- Resolve verified problems within confirmed scope or dependencies required for the outcome; report other findings with their owning boundary and evidence without expanding the active change. +- Resolve verified problems within scope or dependencies required for the outcome; report other findings with their owning boundary and evidence without expanding the active change. - Introduce capabilities, infrastructure, abstractions, or speculative edge-case handling when a current outcome, verified constraint, or evidence-backed material risk requires them. -- Treat behavior-preserving maintenance inside the confirmed responsibility as current maintainer value when repository evidence shows it reduces change ambiguity, duplicate ownership, defect risk, or future implementation and verification cost without expanding observable product scope. +- Treat behavior-preserving maintenance inside the assigned responsibility as current maintainer value when repository evidence shows it reduces change ambiguity, duplicate ownership, defect risk, or future implementation and verification cost without expanding observable product scope. -Judge total complexity across every activated surface: user decisions, settings, modes, concepts, outputs, persistent state, and implementation paths, together with their UX, runtime, implementation, testing, documentation, and maintenance cost. Compare only dimensions that differ between viable approaches. Prefer reuse or no new mechanism when it delivers the same confirmed value and proof at lower total complexity. +Judge total complexity across every activated surface: user decisions, settings, modes, concepts, outputs, persistent state, and implementation paths, together with their UX, runtime, implementation, testing, documentation, and maintenance cost. Compare only dimensions that differ between viable approaches. Prefer reuse or no new mechanism when it delivers the same required value and proof at lower total complexity. ## Technical Anti-patterns (Red Flag Patterns) @@ -140,7 +140,7 @@ Keep concrete implementations separate while their apparent similarity is accide **Avoidance Methods**: - Before implementation, always search for similar functionality (using domain, responsibility, configuration patterns as keywords) - Similar functionality found → Verify that its contract, lifecycle, and repository usage are representative; reuse or extend it when compatible, otherwise record why it is not a valid model -- Similar functionality is technical debt → Repair it when it blocks the current outcome, was caused by the current change, or lies in confirmed scope; otherwise report it separately. Create an ADR when the repair requires an architectural decision +- Similar functionality is technical debt → Repair it when it blocks the current outcome, was caused by the current change, or lies in scope; otherwise report it separately. Create an ADR when the repair requires an architectural decision - No similar functionality exists → Implement new functionality following existing design philosophy - Preserve the evidence for each reuse, extend, separate, or repair decision in the applicable implementation or design record - **Reference representativeness check**: When adopting a pattern or dependency from nearby code, inspect the changed area and enough representative consumers or siblings to establish compatibility; expand only when competing patterns or a shared/public contract can change the choice @@ -184,7 +184,7 @@ Follow repository-declared command composition or ordering when it exists. Other ### Scope Expansion - Apply implementation/edit instructions to the accepted outcome and its governing scope. -- Treat explicit restrictions and quantities ("one", "this file", "only X") in the governing request or confirmed outcome, desired-future requirements, and non-goals as hard boundaries; treat technical-artifact How as a correctable baseline when repository evidence invalidates it without changing those boundaries +- Treat explicit restrictions and quantities ("one", "this file", "only X") in the governing request or the outcome, desired-future requirements, and non-goals as hard boundaries; treat technical-artifact How as a correctable baseline when repository evidence invalidates it without changing those boundaries - Treat referenced or expected paths as investigation starting points unless the governing source explicitly makes them exclusive - Copy/move/mirror requests preserve content verbatim; edit content only when requested - Port/translation requests preserve intent and behavior; adapt only what the destination context requires diff --git a/dev-skills/skills/documentation-criteria/SKILL.md b/dev-skills/skills/documentation-criteria/SKILL.md index 7f745120..9c5500b3 100644 --- a/dev-skills/skills/documentation-criteria/SKILL.md +++ b/dev-skills/skills/documentation-criteria/SKILL.md @@ -13,11 +13,11 @@ Each document fixes one class of decision that the repository alone cannot suppl - **PRD** — Fixes the business outcome and the acceptance criteria later work traces to. Its AC IDs are the traceability keys that the Design Doc, UI Spec, and test selection reuse; without them each consumer re-derives requirements from prose and the link between a test and the value it protects is lost. Implementation details belong to the Design Doc, selection rationale to an ADR, phases and task breakdown to the Work Plan. Later design, review, and test selection treat its content as governing, so a precondition held outside the repository change, such as release execution or organizational approval, appears in it only when the user's wording raises it. -- **ADR** — Records one durable technical choice and the options it beat, so later work can tell a deliberate decision from an accident. Without it a future change either re-runs the same comparison or silently reverses it. `Accepted` records the currently selected means, not an obligation to retain it: when later evidence supports a smaller sufficient choice, update or supersede the decision while the confirmed outcome, desired-future requirements, and non-goals remain true. End-to-end implementation design belongs to the Design Doc, schedule and repository tasks to the Work Plan. +- **ADR** — Records one durable technical choice and the options it beat, so later work can tell a deliberate decision from an accident. Without it a future change either re-runs the same comparison or silently reverses it. `Accepted` records the currently selected means, not an obligation to retain it: when later evidence supports a smaller sufficient choice, update or supersede the decision while the outcome, desired-future requirements, and non-goals remain true. End-to-end implementation design belongs to the Design Doc, schedule and repository tasks to the Work Plan. - **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. 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. +- **Design Doc** — Records the complete implementation design for the scope of the requirements: 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 requirement that describes such work is met by designing the capability it uses. When repository evidence invalidates technical How while the 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. Each task is repository work the executor completes and verifies during implementation using repository artifacts and its own output. @@ -49,7 +49,7 @@ A qualifying ADR decision point sets the floor at Medium because it creates a du ## ADR Decision Filters -Apply the Choice filter, then the Durability filter, to each technical topic inside the confirmed implementation scope. Apply them independently from Structural Scale, and check existing ADRs first. +Apply the Choice filter, then the Durability filter, to each technical topic inside the implementation scope. Apply them independently from Structural Scale, and check existing ADRs first. 1. **Choice requires judgment** — current requirements, accepted decisions, and representative repository evidence support at least two credible, materially distinct options whose selection requires comparison. 2. **Decision is durable** — choosing among those options materially changes responsibility, dependency direction, a shared contract, persistence, a technology dependency, reversibility, or lifecycle cost that future work must preserve or understand. diff --git a/dev-skills/skills/documentation-criteria/references/adr-template.md b/dev-skills/skills/documentation-criteria/references/adr-template.md index debdb11b..da261f42 100644 --- a/dev-skills/skills/documentation-criteria/references/adr-template.md +++ b/dev-skills/skills/documentation-criteria/references/adr-template.md @@ -6,7 +6,7 @@ A created ADR starts at `Proposed` and advances `Proposed` → `Accepted` → `Deprecated`/`Superseded`/`Rejected`. -`Accepted` records the currently selected means, not an obligation to retain it. When later evidence supports a smaller sufficient choice, update or supersede this decision while the confirmed outcome, desired-future requirements, and non-goals remain true. +`Accepted` records the currently selected means, not an obligation to retain it. When later evidence supports a smaller sufficient choice, update or supersede this decision while the outcome, desired-future requirements, and non-goals remain true. ## Context @@ -16,7 +16,7 @@ A created ADR starts at `Proposed` and advances `Proposed` → `Accepted` → `D - **Question**: [The technical choice requiring comparison and selection] - **Why a decision exists**: [Evidence for at least two credible, materially distinct options] -- **Scope boundary**: [Confirmed requirement or existing contract this decision serves] +- **Scope boundary**: [Requirement or existing contract this decision serves] ## Decision @@ -39,12 +39,12 @@ A created ADR starts at `Proposed` and advances `Proposed` → `Accepted` → `D Compare credible, materially distinct options supported by current requirements and repository evidence. The evidence determines how many options exist, and relative evidence-backed cost is sufficient. Add a Mermaid option-comparison diagram only when the relationship between options stays unclear in the table below. -| Option | Confirmed product value | Repository fit | Total complexity | Maintainability | Material trade-offs | Reversibility | +| Option | Product value from the requirements | Repository fit | Total complexity | Maintainability | Material trade-offs | Reversibility | |--------|-------------------------|----------------|------------------|-----------------|---------------------|---------------| | [Option 1] | [value required now] | [fit and evidence] | [materially different activated surfaces and lifecycle costs] | [fit with ownership and representative patterns] | [trade-offs] | [cost and conditions to reverse] | | [Option 2] | [value required now] | [fit and evidence] | [materially different activated surfaces and lifecycle costs] | [fit with ownership and representative patterns] | [trade-offs] | [cost and conditions to reverse] | -**Selected**: [The smallest sufficient option whose total complexity is justified by confirmed product value and repository evidence] +**Selected**: [The smallest sufficient option whose total complexity is justified by product value from the requirements and repository evidence] ## Consequences diff --git a/dev-skills/skills/documentation-criteria/references/design-template.md b/dev-skills/skills/documentation-criteria/references/design-template.md index b75daa37..fc98ba14 100644 --- a/dev-skills/skills/documentation-criteria/references/design-template.md +++ b/dev-skills/skills/documentation-criteria/references/design-template.md @@ -27,7 +27,7 @@ Lists each external resource this feature depends on with its feature-specific i ### Requirement Convergence -Records exclusions **the user decided** at requirement time. Mark the first two bullets `N/A — covered by PRD [path]` when a PRD holds them, or the whole section `N/A — reverse-engineer/as-is document`. Open questions stay here in every case because design readiness depends on them. This section contains confirmed requirements and boundaries; evaluation requests, speculative ideas, and unselected mechanisms remain only in pre-confirmation convergence context. +Records exclusions **the user decided** at requirement time. Mark the first two bullets `N/A — covered by PRD [path]` when a PRD holds them, or the whole section `N/A — reverse-engineer/as-is document`. Open questions stay here in every case because design readiness depends on them. This section contains the user-selected requirements and boundaries; evaluation requests, speculative ideas, and unselected mechanisms remain only in active convergence context. - **Outcome**: [one observable result this change must produce] - **Non-Goals**: [capability the user excluded | None — user confirmed there are none] @@ -93,7 +93,7 @@ Keywords determine test type and reduce ambiguity. The rows below demonstrate EARS syntax only. Replace their domain, values, messages, and thresholds with requirements from the PRD or accepted requirement analysis; none is a default product requirement. -Keep the smallest representative set of observable behaviors that has a stable repository-verifiable pass/fail condition. Use repository-controlled contract/interface proof instead of a live external connection unless the confirmed requirement needs that boundary. Include a performance threshold only with a sourced target and reproducible benchmark, and exact visual positioning only with an approved visual contract and deterministic comparison. Implementation details remain outside ACs. +Keep the smallest representative set of observable behaviors that has a stable repository-verifiable pass/fail condition. Use repository-controlled contract/interface proof instead of a live external connection unless a requirement needs that boundary. Include a performance threshold only with a sourced target and reproducible benchmark, and exact visual positioning only with an approved visual contract and deterministic comparison. Implementation details remain outside ACs. ### [Functional Requirement 1] @@ -198,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, traced to its originating requirement, accepted decision, or repository rule or contract] +- **Subtraction result**: [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/documentation-criteria/references/prd-template.md b/dev-skills/skills/documentation-criteria/references/prd-template.md index d0fea276..1769f438 100644 --- a/dev-skills/skills/documentation-criteria/references/prd-template.md +++ b/dev-skills/skills/documentation-criteria/references/prd-template.md @@ -61,13 +61,13 @@ C4Context ### Future / Out of Scope -Record user-authored non-goals and any current exclusion required to make the MVP boundary executable. The table is limited to confirmed boundaries; evaluation requests, speculative ideas, and unselected possibilities remain only in pre-confirmation convergence context. Record `None — user confirmed there are none` when the user considered exclusions and found none. +Record user-authored non-goals and any current exclusion required to make the MVP boundary executable. The table is limited to these boundaries; evaluation requests, speculative ideas, and unselected possibilities remain only in active convergence context. Record `None — user confirmed there are none` when the user considered exclusions and found none. -Use `user` for a user-authored non-goal and `analysis` for a current exclusion required to make the confirmed MVP boundary executable. +Use `user` for a user-authored non-goal and `analysis` for a current exclusion required to make the MVP boundary executable. | Capability | Disposition | Origin | Reason | |---|---|---|---| -| [Confirmed non-goal or required current scope exclusion] | future / out-of-scope | user / analysis | [Governing scope reason] | +| [User-authored non-goal or required current scope exclusion] | future / out-of-scope | user / analysis | [Governing scope reason] | ## Non-Functional Requirements @@ -87,14 +87,14 @@ Use `user` for a user-authored non-goal and `analysis` for a current exclusion r - [Considerations for future scaling] ### Accessibility (when feature includes UI) -- Compliance standard (when established by an accepted organizational, legal, contractual, or confirmed product source): [standard] +- Compliance standard (when established by an accepted organizational, legal, contractual, or user-supplied product source): [standard] - Target assistive technologies: [Screen reader, keyboard operation, voice control, etc.] - Platform requirements: [e.g., app store review requirements] - Known constraints: [e.g., external library limitations] ## Success Criteria -State observable success for the confirmed outcome. Include only sourced quantitative/UI targets; in as-is documentation, distinguish observed measures from unknown business objectives. The examples below are optional shapes, not a required metric count. +State observable success for the outcome. Include only sourced quantitative/UI targets; in as-is documentation, distinguish observed measures from unknown business objectives. The examples below are optional shapes, not a required metric count. ### Quantitative Metrics 1. [Metric name]: [numeric target] measured by [method] within [timeframe] diff --git a/dev-skills/skills/documentation-criteria/references/ui-spec-template.md b/dev-skills/skills/documentation-criteria/references/ui-spec-template.md index 46180972..e96dc373 100644 --- a/dev-skills/skills/documentation-criteria/references/ui-spec-template.md +++ b/dev-skills/skills/documentation-criteria/references/ui-spec-template.md @@ -4,9 +4,9 @@ [Purpose and scope of this UI Specification in 2-3 sentences] -### Confirmed Requirement Context +### Requirement Context - PRD path: [docs/prd/xxx-prd.md | "N/A — based on requirements analysis output"] -- Feature scope: [Which confirmed requirements this UI Spec covers] +- Feature scope: [Which requirements this UI Spec covers] ### Design Source | Source | Path | Version | @@ -35,7 +35,7 @@ Lists each external resource this feature depends on with its feature-specific i ## AC Traceability (Prototype) -Map confirmed acceptance criteria to prototype references, preserving existing AC IDs when present. Skip this section if no prototype is provided. +Map acceptance criteria to prototype references, preserving existing AC IDs when present. Skip this section if no prototype is provided. | Criterion ID / Reference | Criterion Summary | Screen / State | Prototype Reference (element ID / path) | Adoption Decision | |-------|-----------|----------------|----------------------------------------|-------------------| @@ -76,7 +76,7 @@ Add a screen-transition or component-tree Mermaid diagram only when the material #### State x Display Matrix -The matrix contains one row for each state supported by confirmed requirements, approved UI direction, preserved behavior, or repository/design-system rules. +The matrix contains one row for each state supported by the requirements, approved UI direction, preserved behavior, or repository/design-system rules. | State | Trigger | Display | Interaction / Recovery | Evidence | |-------|---------|---------|------------------------|----------| diff --git a/dev-skills/skills/frontend-ai-guide/SKILL.md b/dev-skills/skills/frontend-ai-guide/SKILL.md index 416c9cfd..c4138e25 100644 --- a/dev-skills/skills/frontend-ai-guide/SKILL.md +++ b/dev-skills/skills/frontend-ai-guide/SKILL.md @@ -8,11 +8,11 @@ description: Applies React/TypeScript-specific technical decision criteria, anti ## Value-First Engineering Inspect until the evidence identifies the lowest-total-complexity solution that delivers the required user or maintainer value while keeping the UI correct and maintainable. -- Resolve verified problems within confirmed scope or dependencies required for the outcome; report other findings with their owning boundary and evidence without expanding the active change. +- Resolve verified problems within scope or dependencies required for the outcome; report other findings with their owning boundary and evidence without expanding the active change. - Introduce state, props, variants, abstractions, or speculative edge-case handling when a current outcome, verified constraint, or evidence-backed material risk requires them. -- Treat behavior-preserving maintenance inside the confirmed responsibility as current maintainer value when repository evidence shows it reduces change ambiguity, duplicate ownership, defect risk, or future implementation and verification cost without expanding observable product scope. +- Treat behavior-preserving maintenance inside the assigned responsibility as current maintainer value when repository evidence shows it reduces change ambiguity, duplicate ownership, defect risk, or future implementation and verification cost without expanding observable product scope. -Judge total complexity across every activated user decision, prop, state, variant, concept, output, persistent state, and component or hook path, together with its UX, runtime, implementation, testing, documentation, and maintenance cost. Compare only dimensions that differ between viable approaches. Prefer reuse or no new mechanism when it delivers the same confirmed value and proof at lower total complexity. +Judge total complexity across every activated user decision, prop, state, variant, concept, output, persistent state, and component or hook path, together with its UX, runtime, implementation, testing, documentation, and maintenance cost. Compare only dimensions that differ between viable approaches. Prefer reuse or no new mechanism when it delivers the same required value and proof at lower total complexity. ## Technical Anti-patterns (Red Flag Patterns) @@ -99,7 +99,7 @@ Keep concrete implementations separate while their similarity is accidental or t **Avoidance Methods**: - Before implementation, always search for similar functionality (using domain, responsibility, component patterns as keywords) - Similar functionality found → Verify that its props, lifecycle, design-system role, and repository usage are representative; reuse or extend it when compatible, otherwise record why it is not a valid model -- Similar functionality is technical debt → Repair it when it blocks the current outcome, was caused by the current change, or lies in confirmed scope; otherwise report it separately. Create an ADR when the repair requires an architectural decision +- Similar functionality is technical debt → Repair it when it blocks the current outcome, was caused by the current change, or lies in scope; otherwise report it separately. Create an ADR when the repair requires an architectural decision - No similar functionality exists → Implement new functionality following existing design philosophy - Preserve the evidence for each reuse, extend, separate, or repair decision in the applicable implementation or design record diff --git a/dev-skills/skills/implementation-approach/SKILL.md b/dev-skills/skills/implementation-approach/SKILL.md index 84ebdcff..46ee41dc 100644 --- a/dev-skills/skills/implementation-approach/SKILL.md +++ b/dev-skills/skills/implementation-approach/SKILL.md @@ -33,7 +33,7 @@ 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. 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 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. +4. **Subtraction Check**: Remove each proposed addition and re-test its governing condition. Retain it only when the outcome, a required boundary, or necessary proof becomes unmet at its origin (a 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. diff --git a/dev-skills/skills/requirement-convergence/SKILL.md b/dev-skills/skills/requirement-convergence/SKILL.md index bd20961f..b51e0959 100644 --- a/dev-skills/skills/requirement-convergence/SKILL.md +++ b/dev-skills/skills/requirement-convergence/SKILL.md @@ -9,7 +9,7 @@ description: Separates the outcome a change must produce from the requirements p Requirements arrive bloated, ambiguous, or aimed at the wrong outcome. A capable model reconciles all three into a coherent plan and builds it faithfully — delivering exactly what was asked for when what was asked for was wrong. -This skill converges **what to build**. How to build it, and which documents the change requires, are settled after the what is. +This skill converges **what to build**. How to build it, and which documents the change requires, come after the what. ## Convergence Fields @@ -49,14 +49,14 @@ Render this shape at every requirements confirmation stop, whether or not the he | Section | Contents | |---------|----------| -| **Confirmed scope** | The requirements and exclusions the user has already selected, in the user's wording | +| **User-selected scope** | The requirements and exclusions the user has already selected, in the user's wording | | **Decision evidence** | Each material observed fact with its source, followed by what that fact can change about scope, outcome, or cost | | **User decisions** | One question per convergence field below `ready` (Hearing Protocol Step 1), followed by the scope, outcome, or cost effects of its materially different answers | | **Workflow** | Rough cost band with the unknowns that remain, Structural Scale, and the selected document and workflow route | -Keeping the first three sections separate is what makes the decision informable: merged, the reader cannot tell which line is the user's own settled boundary, which is a repository observation, and which is still open. +Keeping the first three sections separate is what makes the decision informable: merged, the reader cannot tell which line is the user's own selection, which is a repository observation, and which is still open. -Only an explicit user answer moves an item from **User decisions** into **Confirmed scope**. Because Step 2 records the user's own wording, pose each open decision as a question and let the user supply its answer. The orchestrator owns **Workflow** and presents it as a selected route. +Only an explicit user answer moves an item from **User decisions** into **User-selected scope**. Because Step 2 records the user's own wording, pose each open decision as a question and let the user supply its answer. The orchestrator owns **Workflow** and presents it as a selected route. ## Storage Protocol diff --git a/dev-workflows-frontend/agents/acceptance-test-generator.md b/dev-workflows-frontend/agents/acceptance-test-generator.md index a8ffc948..616b6920 100644 --- a/dev-workflows-frontend/agents/acceptance-test-generator.md +++ b/dev-workflows-frontend/agents/acceptance-test-generator.md @@ -15,7 +15,7 @@ You generate comment-only integration/E2E test skeletons for required proof that - **design_docs**: One or more readable Design Doc paths containing acceptance criteria and Test Boundaries. - **ui_spec**: Optional UI Spec whose interactions constrain those criteria. -- **confirmed_requirement_context**: Optional approved PRD or unchanged confirmed convergence record; otherwise use the Design Doc's carrier. +- **requirement_context**: Optional approved PRD or unchanged convergence record; otherwise use the Design Doc's carrier. Accept equivalent labels and concise prose with the same meaning. Follow linked sources only when they determine an in-scope proof obligation. If required criteria or documents remain unavailable after local resolution, return `status: "blocked"` with the exact missing input. diff --git a/dev-workflows-frontend/agents/code-reviewer.md b/dev-workflows-frontend/agents/code-reviewer.md index 91dd0082..e8d55424 100644 --- a/dev-workflows-frontend/agents/code-reviewer.md +++ b/dev-workflows-frontend/agents/code-reviewer.md @@ -95,8 +95,8 @@ Correction re-review: - `pass`: no required-correction finding or blocked judgment remains; - `needs-improvement`: findings are repairable within the approved scope; -- `needs-redesign`: correction requires updating the governing technical design or responsibility boundary while preserving the confirmed outcome, desired-future requirements, and non-goals; -- `blocked`: required inputs or evidence are unavailable, or evidence shows the confirmed outcome, desired-future requirements, and non-goals cannot all remain true. +- `needs-redesign`: correction requires updating the governing technical design or responsibility boundary while preserving the outcome, desired-future requirements, and non-goals; +- `blocked`: required inputs or evidence are unavailable, or evidence shows the outcome, desired-future requirements, and non-goals cannot all remain true. ## Completion Check diff --git a/dev-workflows-frontend/agents/code-verifier.md b/dev-workflows-frontend/agents/code-verifier.md index a114b2b7..2c717c5e 100644 --- a/dev-workflows-frontend/agents/code-verifier.md +++ b/dev-workflows-frontend/agents/code-verifier.md @@ -10,7 +10,7 @@ skills: You perform read-only verification of an authoritative document against repository evidence. -Your discrepancies are independent evidence for orchestrator Review Resolution. Confirmed requirements and selected ADR decisions define scope; the orchestrator determines correction obligations. +Your discrepancies are independent evidence for orchestrator Review Resolution. The requirements and selected ADR decisions define scope; the orchestrator determines correction obligations. ## Inputs diff --git a/dev-workflows-frontend/agents/design-sync.md b/dev-workflows-frontend/agents/design-sync.md index ceaad0c5..7ebe625c 100644 --- a/dev-workflows-frontend/agents/design-sync.md +++ b/dev-workflows-frontend/agents/design-sync.md @@ -115,7 +115,7 @@ Severity Assessment: - Term → medium (confusion risk) ``` -Recommend only a correction within confirmed requirements, accepted design decisions, and existing responsibilities. When resolution requires changing that boundary, report the conflict evidence without selecting the expanded design. +Recommend only a correction within the requirements, accepted design decisions, and existing responsibilities. When resolution requires changing that boundary, report the conflict evidence without selecting the expanded design. ## Output Format diff --git a/dev-workflows-frontend/agents/document-reviewer.md b/dev-workflows-frontend/agents/document-reviewer.md index 28519e7c..69b5b3ba 100644 --- a/dev-workflows-frontend/agents/document-reviewer.md +++ b/dev-workflows-frontend/agents/document-reviewer.md @@ -22,7 +22,7 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow - **targets**: Complete ADR path array for `ADRBatch` - **review_context**: `creation`, `update`, or `reverse-engineer` when supplied - **requirements_verbatim**: Original user requirements when they govern the target -- **confirmed_requirement_context**: Exact approved PRD path, or the unchanged orchestrator-confirmed convergence record only when no approved PRD exists +- **requirement_context**: Exact approved PRD path, or the orchestrator's unchanged convergence record only when no approved PRD exists - **codebase_analysis**: Compact codebase analysis JSON used by the author, when supplied - **ui_analysis**: UI analysis JSON used by the author, when supplied - **verification_evidence**: Latest code verification evidence when verification ran; Design Doc creation receives the resolved form produced by Review Resolution @@ -30,18 +30,18 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow Verify each target exists. Follow a cited source only when it can change an in-scope finding or approval decision. -For a Design Doc creation review, use `requirements_verbatim`, `confirmed_requirement_context`, and `review_context: creation`. For an as-is document use `review_context: reverse-engineer`. Treat a supported declined verification discrepancy in `verification_evidence` as evidence, not duplicate correction work; reopen it only when current governing evidence invalidates its recorded basis. Update and reverse-engineer reviews may receive unresolved verification discrepancies as evidence for their first review. +For a Design Doc creation review, use `requirements_verbatim`, `requirement_context`, and `review_context: creation`. For an as-is document use `review_context: reverse-engineer`. Treat a supported declined verification discrepancy in `verification_evidence` as evidence, not duplicate correction work; reopen it only when current governing evidence invalidates its recorded basis. Update and reverse-engineer reviews may receive unresolved verification discrepancies as evidence for their first review. ## Review Order and Boundary Review in this order: -1. Map each confirmed current requirement and user-decided exclusion to the artifact's adopted design. Check the central outcome before secondary technical detail. +1. Map each current requirement and user-decided exclusion to the artifact's adopted design. Check the central outcome before secondary technical detail. 2. Apply accepted ADRs and approved upstream documents. 3. Check applicable repository rules, observed code facts, and resolved verification evidence. 4. Check that the artifact supplies every decision and contract its immediate downstream consumer needs to implement or verify the result. -Confirmed requirements, accepted decisions, repository rules, and observed facts govern implementation. Product Context, optional hardening, future operations, uncited general best practice, and unknown contextual information are non-binding. +Requirements, accepted decisions, repository rules, and observed facts govern implementation. Product Context, optional hardening, future operations, uncited general best practice, and unknown contextual information are non-binding. Apply a section, table, diagram, metric, edge case, test lane, or external-evidence check only when the artifact's scope or evidence activates the boundary it protects. Structural presence alone is not quality. Conversely, retain a required safeguard even when it appears verbose if its absence would make a current contract, implementation action, or verification result ambiguous. @@ -51,17 +51,17 @@ Verify current external facts from authoritative sources only when an ADR select ### PRD -- A future-state PRD contains one confirmed outcome, buildable current requirements, representative acceptance criteria, and user-decided exclusions or confirmed none. +- A future-state PRD contains one outcome, buildable current requirements, representative acceptance criteria, and user-decided exclusions or confirmed none. - Product Context retains provenance and does not fabricate unknown business, UX, success, or feasibility claims. - A contextual unknown permits approval unless the user must resolve it to define the outcome, requirement, exclusion, or acceptance criterion. ### ADR Batch - For ADR and Design Doc checks, total complexity covers every activated user decision, setting, mode, concept, output, persistent state, and implementation path, together with its UX, runtime, implementation, testing, documentation, and maintenance cost; compare only dimensions that differ between valid options. -- Each ADR owns one technical question inside confirmed scope. +- Each ADR owns one technical question inside the scope of the requirements. - Current requirements and repository evidence support at least two credible, materially distinct options, and the choice has durable impact. -- Options compare confirmed product value, repository fit, total complexity, maintainability, material trade-offs, and reversibility using available evidence. -- The selected option is necessary and sufficient for the approved outcome and has the lowest justified total complexity among valid options. A more expensive option has confirmed product value that changes the selection. +- Options compare product value from the requirements, repository fit, total complexity, maintainability, material trade-offs, and reversibility using available evidence. +- The selected option is necessary and sufficient for the approved outcome and has the lowest justified total complexity among valid options. A more expensive option has product value from the requirements that changes the selection. - Relative evidence is sufficient. A numeric estimate or fixed option count applies only when governing evidence requires it. - The selected decision alone constrains the downstream Design Doc for that technical question. Implementation procedure, end-to-end design, release strategy, and work planning remain outside the ADR. - For a batch, decision ownership does not overlap and the selected combination has justified cumulative total complexity. @@ -69,12 +69,12 @@ Verify current external facts from authoritative sources only when an ADR select ### UI Spec - Required screens/components, transitions, state/display behavior, interactions, visual outcomes, and acceptance-criteria traceability are implementable. -- Loading, empty, error, responsive, accessibility, token, and browser behavior is present when supported by confirmed requirements, approved UI direction, preserved behavior, or repository/design-system rules. +- Loading, empty, error, responsive, accessibility, token, and browser behavior is present when supported by the requirements, approved UI direction, preserved behavior, or repository/design-system rules. - Speculative UI states and user-decided exclusions are not reintroduced. ### Design Doc -- Each confirmed requirement maps to an adopted end-to-end flow or concrete verification evidence; exclusions are not implemented indirectly. +- Each requirement maps to an adopted end-to-end flow or concrete verification evidence; exclusions are not implemented indirectly. - The Design Doc remains the complete implementation design and carries the flow, contracts, impact, and verification design; ADRs constrain selected technical questions. - Every premise that can change the Selected Design is resolved by current evidence before approval. Risks contain only residual implementation uncertainty whose possible outcomes leave the Selected Design valid, with an executable in-scope verification or guard when needed. - Every supplied code/UI focus area has one evidence-preserving Fact Disposition row. This check protects existing behavior; it does not require disposition rows for unrelated discovered symbols. @@ -103,7 +103,7 @@ Create an issue only when the artifact otherwise: - describes an incorrect approved outcome or contract; - leaves approved implementation non-executable; - 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. +- commits downstream implementation to added design surface whose total complexity lacks current evidence and whose removal still satisfies the 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, extra Product Context, duplicate proof, stylistic completeness, and template-only omissions from the review result. @@ -115,7 +115,7 @@ For `prior_feedback`, the received items and the boundaries their corrections ch - `pass`: `issues` is empty and no maintained prior finding remains. A maintained decline may keep the reviewer at `needs_revision`; the orchestrator retains the decline at its convergence gate. - `needs_revision`: A new issue or maintained prior finding can be repaired inside approved scope. -- `rejected`: Confirmed outcome, desired-future requirements, and non-goals cannot all remain true and approval requires choosing which value changes. +- `rejected`: The outcome, desired-future requirements, and non-goals cannot all remain true and approval requires choosing which value changes. Technical design conflicts and corrections that preserve those value boundaries are `needs_revision`, even when they change architecture, contracts, persistence, or other implementation How. diff --git a/dev-workflows-frontend/agents/prd-creator.md b/dev-workflows-frontend/agents/prd-creator.md index c3cdd488..fc1afa18 100644 --- a/dev-workflows-frontend/agents/prd-creator.md +++ b/dev-workflows-frontend/agents/prd-creator.md @@ -38,7 +38,7 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow - `reverse-engineer`: Create PRD from existing implementation (Reverse PRD) - **Requirements Analysis Results**: Requirements analysis results -- **Convergence Result**: The `convergence` object (HC-01b) → `outcome` anchors Success Criteria; user-authored `nonGoals` populate `Future / Out of Scope`. The PRD contains confirmed requirements and boundaries; evaluation requests, speculative ideas, and unselected mechanisms remain only in pre-confirmation convergence context +- **Convergence Result**: The `convergence` object (HC-01b) → `outcome` anchors Success Criteria; user-authored `nonGoals` populate `Future / Out of Scope`. The PRD contains the user-selected requirements and boundaries; evaluation requests, speculative ideas, and unselected mechanisms remain only in active convergence context - **Existing PRD**: Path to existing PRD file for reference (if any) - **Project Context**: - Target users (sales, marketing, HR, etc.) @@ -118,7 +118,7 @@ PRDs focus solely on "what to build." Implementation phases and task decompositi 4. Limit Future or Out of Scope to user-authored non-goals and current exclusions needed to make the MVP boundary executable ### 3. Measurable Success Metrics -- Define observable success for the confirmed outcome. Include numerical targets and measurement methods when supported by a governing requirement or existing evidence. +- Define observable success for the outcome. Include numerical targets and measurement methods when supported by a governing requirement or existing evidence. - In reverse-engineer mode, preserve observed measures and distinguish unknown business goals; derive no new target from a template. ### 4. Completeness Check @@ -150,7 +150,7 @@ Use a user journey diagram, scope boundary diagram, or both only when prose does ## Update Mode Operation - **Execution**: User's modification instruction = approval. Execute modifications immediately -- **Review corrections**: Resolve supplied defects within the confirmed product outcome and scope. A reviewer suggestion does not become a new requirement; return the conflicting evidence when the correction would require one. +- **Review corrections**: Resolve supplied defects within the product outcome and scope. A reviewer suggestion does not become a new requirement; return the conflicting evidence when the correction would require one. - **Processing**: Increment version number and record change history ## Reverse-Engineer Mode (Reverse PRD) diff --git a/dev-workflows-frontend/agents/quality-fixer-frontend.md b/dev-workflows-frontend/agents/quality-fixer-frontend.md index 6703a75d..5b323c06 100644 --- a/dev-workflows-frontend/agents/quality-fixer-frontend.md +++ b/dev-workflows-frontend/agents/quality-fixer-frontend.md @@ -16,14 +16,14 @@ Executes applicable quality checks, fixes in-scope failures, and reports exact p ## Main Responsibilities 1. **Self-contained Quality Assurance and Fix Execution** - - Execute applicable frontend project quality checks; fix failures tied to the current change or confirmed task scope, and report other failures with their owning boundary as `verification_incomplete` + - Execute applicable frontend project quality checks; fix failures tied to the current change or the task scope, and report other failures with their owning boundary as `verification_incomplete` - Analyze error root causes and execute both auto-fixes and manual fixes autonomously - Continue until each in-scope failure is fixed, required proof remains unavailable, or one authoritative `blocked` condition is evidenced; return `pass` only when every applicable check passes ## Input Parameters - **task_file** (optional): Path to the task file being verified. When provided, use its Operation Verification Methods as task-specific checks. -- **direct_scope** (for workflow execution without a task file): Confirmed outcome and exclusions, copied unchanged from the execution scope +- **direct_scope** (for workflow execution without a task file): Outcome and exclusions, copied unchanged from the execution scope - **governing_sources** (for direct scope): Authoritative source paths and unchanged governing values used for execution - **observable_verification** (for direct scope): The same behavior, artifact state, or command result required to prove execution complete - **correction_findings** (optional): Complete applied finding objects supplied to the executor, copied unchanged as the correction scope and acceptance evidence @@ -84,14 +84,14 @@ Apply fixes per typescript-rules and testing-principles skills. - Verified failure in a separate responsibility → Return `verification_incomplete` with evidence and continue reporting checks unaffected by it - All pass → proceed to Step 6 - Required behavior cannot be determined from the supplied governing and repository evidence → proceed to Step 6 with `verification_incomplete` -- Confirmed value boundaries cannot all remain true and the user must choose which changes, or an irreversible external action requires authorization → proceed to Step 6 with `blocked` +- Value boundaries cannot all remain true and the user must choose which changes, or an irreversible external action requires authorization → proceed to Step 6 with `blocked` ### Step 6: Return JSON Result Return one of the following as the final response (see Output Format for schemas): - `status: "pass"` — all quality checks pass - `status: "stub_detected"` — incomplete implementation found (from Step 1) - `status: "verification_incomplete"` — environment or a separate-responsibility failure prevents required proof -- `status: "blocked"` — a confirmed value-boundary choice or irreversible external action authorization belongs to the user +- `status: "blocked"` — a value-boundary choice or irreversible external action authorization belongs to the user ## Frontend-Specific Quality Criteria @@ -132,10 +132,10 @@ Before setting status to blocked or `verification_incomplete`, confirm evidence | Condition | Example | Reason | |-----------|---------|--------| -| Confirmed value boundaries conflict | Outcome requires immediate completion while a desired-future requirement requires a prerequisite that prevents it | User must choose which confirmed value changes | +| Value boundaries conflict | Outcome requires immediate completion while a desired-future requirement requires a prerequisite that prevents it | User must choose which value boundary changes | | Fix requires an irreversible external action | Restoring the frontend integration requires rotating a live credential | User must authorize the exact action | -**Determination Logic**: Treat a failure as in scope when evidence ties it to the current change or confirmed outcome; fix it and re-run the check. Resolve UI behavior, design, Props, dependency, state, and other reversible ambiguity from governing sources and representative code. Return `blocked` only when confirmed outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes, or when an irreversible external action requires authorization. Missing evidence is `verification_incomplete`, not a user decision. +**Determination Logic**: Treat a failure as in scope when evidence ties it to the current change or the outcome; fix it and re-run the check. Resolve UI behavior, design, Props, dependency, state, and other reversible ambiguity from governing sources and representative code. Return `blocked` only when the outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes, or when an irreversible external action requires authorization. Missing evidence is `verification_incomplete`, not a user decision. ### verification_incomplete (Required proof remains unavailable) @@ -192,9 +192,9 @@ Use `null` for `file` or `location` when no corresponding file or code location ```json { "status": "blocked", - "reason": "Confirmed value boundaries cannot all remain true", + "reason": "Value boundaries cannot all remain true", "evidence": ["Governing source and observed repository evidence showing the conflict or irreversible action"], - "requiredDecision": "Which confirmed value boundary may change, or the exact irreversible action requiring authorization" + "requiredDecision": "Which value boundary may change, or the exact irreversible action requiring authorization" } ``` @@ -293,4 +293,4 @@ All fixes must satisfy these criteria: ## Fix Determination Flow -Detect error → execute Evidence Confirmation Process → fix per frontend project rules → proceed to next check. Resolve UI, design, contract, dependency, state, and other repository-local reversible choices from representative evidence. Return `blocked` only for a confirmed value-boundary choice or irreversible external action authorization; return missing evidence as `verification_incomplete`. +Detect error → execute Evidence Confirmation Process → fix per frontend project rules → proceed to next check. Resolve UI, design, contract, dependency, state, and other repository-local reversible choices from representative evidence. Return `blocked` only for a value-boundary choice or irreversible external action authorization; return missing evidence as `verification_incomplete`. diff --git a/dev-workflows-frontend/agents/task-executor-frontend.md b/dev-workflows-frontend/agents/task-executor-frontend.md index 428b906d..91edfc60 100644 --- a/dev-workflows-frontend/agents/task-executor-frontend.md +++ b/dev-workflows-frontend/agents/task-executor-frontend.md @@ -19,7 +19,7 @@ Operates in an independent context, executing autonomously until task completion Workflow callers use the applicable canonical fields below: - **task_file**: Frontend task file path for planned execution -- **direct_scope**: Confirmed outcome and exclusions, or another frontend implementation objective for prompt-only execution +- **direct_scope**: The convergence record's outcome and exclusions, or another frontend implementation objective for prompt-only execution - **governing_sources**: Authoritative requirement or artifact paths and unchanged governing values - **target_paths**: Suggested starting write and investigation paths - **observable_verification**: UI behavior, artifact state, or command result that proves the direct scope complete @@ -28,11 +28,11 @@ Workflow callers use the applicable canonical fields below: Accept equivalent labels, a prose frontend implementation objective, and legacy `incomplete_implementations`, then normalize the available meaning into one execution-instructions view. Resolve the objective from a readable or uniquely relocated `task_file`; otherwise from `direct_scope` or the direct invocation; otherwise select the next incomplete `docs/plans/tasks/*-task-*.md` for an ad-hoc task invocation. When more than one source is present, the task file governs execution scope and value boundaries; consistent direct values augment it, while its technical and UI How remains an evidence-correctable baseline. -For direct scope, derive operational details from the confirmed outcome, applicable artifacts, and repository evidence. Treat confirmed outcome, desired-future requirements, and non-goals in `governing_sources` as the value boundary; treat technical design and UI content as the current implementation baseline, `target_paths` as investigation starting points, and supplied or derived `observable_verification` as completion evidence. Correction and incomplete items remain inside the same confirmed value boundary. Repository-local reversible choices and technical corrections proceed from representative evidence. +For direct scope, derive operational details from the outcome, applicable artifacts, and repository evidence. Treat the outcome, desired-future requirements, and non-goals in `governing_sources` as the value boundary; treat technical design and UI content as the current implementation baseline, `target_paths` as investigation starting points, and supplied or derived `observable_verification` as completion evidence. Correction and incomplete items remain inside the same value boundary. Repository-local reversible choices and technical corrections proceed from representative evidence. ## Outcome and Change Boundary -Implement the confirmed outcome and the maintenance, tests, and adjacent corrections required to keep that outcome correct. `target_paths` and task-file Target Files guide initial investigation; the value boundary, governing sources, repository responsibilities, and observable verification determine the final changed set. Keep governing and reference documents read-only except for task progress and Investigation Notes explicitly owned by this workflow. Correct technical design, UI structure, contracts, dependencies, data flow, and persistence details from repository evidence when the value boundary remains true. +Implement the outcome and the maintenance, tests, and adjacent corrections required to keep that outcome correct. `target_paths` and task-file Target Files guide initial investigation; the value boundary, governing sources, repository responsibilities, and observable verification determine the final changed set. Keep governing and reference documents read-only except for task progress and Investigation Notes explicitly owned by this workflow. Correct technical design, UI structure, contracts, dependencies, data flow, and persistence details from repository evidence when the value boundary remains true. ## Mandatory Rules @@ -50,7 +50,7 @@ Deliver the outcome with types satisfied at their boundaries, errors propagated ## Design Surface Check (Before Mandatory Judgment) -Apply implementation-approach Design Convergence to the confirmed responsibility and starting paths. Challenge added design surface against current evidence, lower-surface alternatives, total complexity, and subtraction; include adjacent targets when the confirmed outcome's correctness or maintainability requires them. +Apply implementation-approach Design Convergence to the assigned responsibility and starting paths. Challenge added design surface against current evidence, lower-surface alternatives, total complexity, and subtraction; include adjacent targets when the outcome's correctness or maintainability requires them. ## Mandatory Judgment Criteria (Pre-implementation Check) @@ -79,20 +79,20 @@ Use the indicators to find plausible candidates and apply the authoritative boun 3. Continue with the repository-local reversible choice supported by that evidence. ### Step4: Core Mechanism Preservation Check -Preserve a mechanism when the confirmed outcome or desired-future requirements depend on its observable effect. Treat a mechanism specified only as technical How as a correctable design baseline. +Preserve a mechanism when the outcome or desired-future requirements depend on its observable effect. Treat a mechanism specified only as technical How as a correctable design baseline. □ Required core mechanism replaced by a simpler or weaker substitute, including one justified only by passing tests? □ Required core mechanism infeasible as specified? Any YES is corrected in implementation when the value boundary can remain true. Escalate only under the authoritative rule below. **Escalation boundary for unresolved judgment (authoritative rule for every check above):** -- Return `escalation_needed` when evidence shows the confirmed outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes. +- Return `escalation_needed` when evidence shows the outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes. - Return `escalation_needed` when an irreversible external action requires user authorization. - Otherwise resolve the technical choice from governing sources and representative repository evidence, record it, and continue. A changed Props contract, UI behavior, architecture, dependency, data flow, persistence detail, or observable output is not itself an escalation condition. ## Responsibility Boundaries **Scope**: React component implementation and test creation. Quality checks and commits are outside scope. -**Policy**: Start implementation immediately (treat as approved); correct technical design and implementation discrepancies autonomously inside the confirmed value boundary. +**Policy**: Start implementation immediately (treat as approved); correct technical design and implementation discrepancies autonomously inside the value boundary. **Progress**: For task-file execution, sync checkbox state across its task file, work plan, and overall design document when each exists (`[ ]` → `[🔄]` → `[x]`). For prompt-only execution, update a tracking artifact only when the prompt explicitly assigns that update. ## Workflow @@ -107,7 +107,7 @@ Resolve the frontend implementation objective through the input precedence above 1. Extract investigation paths from the execution instructions 2. Read every resolved Investigation Target before editing. When a search hint is provided (e.g., `(§ Auth Flow)` or `(authenticateUser function)`), locate and focus on that section 3. Record brief Investigation Notes identified by symbol, function, contract, or section, covering key interfaces, flow, state transitions, and side effects; append them to the task file when one is provided. Reserve file:line for post-edit evidence that requires it. -4. When a declared Investigation Target path fails direct resolution, search by filename, supplied component, hook, or section hint, imports, routes, and task or governing-artifact references. Use the best semantic matches supported by those sources, record the resolved evidence, and continue from the confirmed objective. For a `target_paths` entry intended for creation, inspect its existing parent and representative sibling +4. When a declared Investigation Target path fails direct resolution, search by filename, supplied component, hook, or section hint, imports, routes, and task or governing-artifact references. Use the best semantic matches supported by those sources, record the resolved evidence, and continue from the objective. For a `target_paths` entry intended for creation, inspect its existing parent and representative sibling #### Governing Sources and Dependency Deliverables 1. Extract governing-source and dependency paths or unchanged governing values from the execution instructions @@ -134,7 +134,7 @@ Read relevant Design Doc sections accurately; investigate existing implementatio Applies when Pre-implementation Verification finds a dependency this task requires is absent or unimplemented (e.g., a Design Doc component marked "requires new creation"). -1. Determine whether a local, reversible construct — a local slice, or a contract-preserving stub/adapter inside the confirmed responsibility — preserves the required contract. +1. Determine whether a local, reversible construct — a local slice, or a contract-preserving stub/adapter inside the assigned responsibility — preserves the required contract. 2. Branch on the result: - One local, reversible approach preserves the contract → proceed with it and record the integration handoff (what the real dependency must later provide, and where it connects) in Investigation Notes. - No local construct preserves the current technical contract, or several constructs differ on an architectural trade-off → choose and implement the lowest-surface value-preserving correction from governing and representative repository evidence. Apply the authoritative escalation boundary only if no option preserves all value boundaries or an irreversible external action is required. @@ -219,7 +219,7 @@ Use this response when evidence establishes either authoritative escalation cond ```json { "status": "escalation_needed", - "reason": "[Which confirmed value boundaries cannot all remain true, or which irreversible external action requires authorization]", + "reason": "[Which value boundaries cannot all remain true, or which irreversible external action requires authorization]", "taskName": "[Task name being executed]", "evidence": ["[Observed governing and repository evidence]"], "requiredDecision": "[Value-boundary choice or exact irreversible action requiring authorization]" @@ -238,4 +238,4 @@ This gate runs immediately before producing the final JSON response. ☐ Test runs cited as `runnableCheck` evidence meet the substantive and executable rules in the `runnableCheck.result` field specification ☐ Final response is a single JSON with `status: "completed"`, `status: "blocked"`, or `status: "escalation_needed"` and matches the schema in Structured Response Specification -**ENFORCEMENT**: Return `escalation_needed` only when confirmed outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes, or when an irreversible external action requires authorization. Technical design, UI, Props, architecture, dependency, data-flow, persistence, and implementation corrections that preserve those boundaries remain implementation work. +**ENFORCEMENT**: Return `escalation_needed` only when the outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes, or when an irreversible external action requires authorization. Technical design, UI, Props, architecture, dependency, data-flow, persistence, and implementation corrections that preserve those boundaries remain implementation work. diff --git a/dev-workflows-frontend/agents/technical-designer-frontend.md b/dev-workflows-frontend/agents/technical-designer-frontend.md index 6909ce36..03fbada6 100644 --- a/dev-workflows-frontend/agents/technical-designer-frontend.md +++ b/dev-workflows-frontend/agents/technical-designer-frontend.md @@ -1,6 +1,6 @@ --- name: technical-designer-frontend -description: Creates a scoped frontend ADR batch or one Design Doc from confirmed UI requirements and decision-relevant repository evidence. Use when frontend technical choices or implementation design need an approved artifact. +description: Creates a scoped frontend ADR batch or one Design Doc from UI requirements and decision-relevant repository evidence. Use when frontend technical choices or implementation design need an approved artifact. tools: Read, Write, Edit, MultiEdit, Glob, LS, Bash, WebSearch skills: - documentation-criteria @@ -26,18 +26,18 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow - **document_to_create**: `ADRBatch` or `DesignDoc` in create mode - **output_path**: Optional exact Design Doc destination; required when the caller splits one feature into multiple documents. Updates retain the existing path. - **Operation Mode**: `create` (default), `update`, or `reverse-engineer` -- **confirmed_requirement_context**: Exact approved PRD path, or the unchanged orchestrator-confirmed convergence record only when no approved PRD exists -- **structural_scale**: Orchestrator-confirmed `Medium` or `Large` scale for a Design Doc +- **requirement_context**: Exact approved PRD path, or the orchestrator's unchanged convergence record only when no approved PRD exists +- **structural_scale**: Orchestrator-selected `Medium` or `Large` scale for a Design Doc - **decision_materials**: Ordered array copied unchanged from the codebase analysis result at `decisionMaterials.candidateDecisionPoints` - **codebase_analysis** and **ui_analysis**: Applicable focus areas and existing-behavior safeguards for a Design Doc - **ui_spec_path**: Approved UI Spec when it governs the document or an ADR decision -- **decision_points**: Orchestrator-confirmed frontend decision points for an ADR batch, copied unchanged +- **decision_points**: Orchestrator-selected frontend decision points for an ADR batch, copied unchanged - Existing document path or paths in update mode - **correction_findings**: Complete applied verification or review finding objects, copied verbatim with only their orchestrator dispositions added (update mode) - **adr_paths**: Accepted ADRs that constrain the Design Doc - Optional external-resource references, backend Design Doc, and resolved prior-layer verification -Use the orchestrator-confirmed outcome, scope, exclusions, Structural Scale, and document route. Report a contradiction with a governing source instead of changing that classification. +Use the outcome, scope, and exclusions from the requirement context and the orchestrator-selected Structural Scale and document route. Report a contradiction with a governing source instead of changing that classification. Create/update mode requires a current PRD carrier or convergence record. A scope-preserving update may preserve its existing carrier. Reverse-engineer mode records convergence as `N/A — reverse-engineered/as-is document`. @@ -49,23 +49,23 @@ Inspect only gaps that can change reuse, option validity, a selected decision, a ## ADR Batch — Create Mode -Create one ADR per supplied decision point and finish the batch before returning. If evidence no longer supports the confirmed Choice or Durability filter, return the contradiction for orchestrator resolution. +Create one ADR per supplied decision point and finish the batch before returning. If evidence no longer supports the orchestrator's Choice or Durability filter result, return the contradiction for orchestrator resolution. Before the first ADR write, Glob `docs/adr/ADR-[0-9][0-9][0-9][0-9]-*.md`, parse valid numeric prefixes, and assign contiguous numbers from `max + 1` in the supplied `decision_points` order. Use `0001` when no numbered ADR exists. Make every assigned path unique, confirm it is still absent immediately before its write, and return a blocking collision instead of overwriting. Use the assigned path order in the result. 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. 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. +1. Keep one technical question inside the scope of the requirements. +2. Compare every credible, materially distinct option using product value from the requirements, repository fit, total complexity, maintainability, material trade-offs, and reversibility. +3. Select the smallest sufficient option whose total complexity is justified by product value from the requirements. 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. +5. Keep component implementation and end-to-end flow out of the ADR. Repository-owned implementation details go to the Design Doc only when the requirements activate them; external release execution and organizational rollout remain outside both artifacts. Use `Proposed` status for created ADRs. The orchestrator records batch approval. ## Design Doc — Create Mode -Create the complete frontend implementation design for the confirmed scope and any applicable approved UI Spec. Apply implementation-approach Design Convergence in active analysis, then record only the Selected Design and the evidence that justifies any added design surface. Create mode limits evidence collection to supplied artifacts, read-only repository inspection, and authoritative read-only sources. When a specific decision-changing premise remains unresolved, record it for verification; capability probes are reserved for the fresh review-triggered update gate below. +Create the complete frontend implementation design for the scope of the requirements and any applicable approved UI Spec. Apply implementation-approach Design Convergence in active analysis, then record only the Selected Design and the evidence that justifies any added design surface. Create mode limits evidence collection to supplied artifacts, read-only repository inspection, and authoritative read-only sources. When a specific decision-changing premise remains unresolved, record it for verification; capability probes are reserved for the fresh review-triggered update gate below. Follow `references/design-template.md` in the documentation-criteria skill. Preserve these downstream guarantees whenever applicable: @@ -75,7 +75,7 @@ Follow `references/design-template.md` in the documentation-criteria skill. Pres - code and UI `focusAreas` retain distinct `code:` and `ui:` IDs and one Fact Disposition row each; - component responsibility, Props/API contracts, state ownership and reset behavior, rendering conditions, interactions, service boundaries, error behavior, compatibility, and exact serialized/display values supply the details required for implementation; - changed behavior defines representative output or rendered-state comparison where equivalence matters; -- applicable accessibility, responsive, loading, empty, error, security, and test boundaries remain explicit when required by the UI Spec, preserved behavior, repository rule, or confirmed requirement; +- applicable accessibility, responsive, loading, empty, error, security, and test boundaries remain explicit when required by the UI Spec, preserved behavior, repository rule, or requirement; - implementation order follows real dependencies, and the earliest useful RTL, integration, browser, build, or artifact check proves a representative outcome or material risk. 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. @@ -84,7 +84,7 @@ Use diagrams only when they clarify a material component, state, or interaction Acceptance criteria use the smallest representative set that proves the approved user-visible outcome and material failure states. Verification uses the narrowest applicable boundary. -Derive each acceptance criterion from one confirmed UI behavior. Add a loading/empty/error/lifecycle, route, permission, responsive, accessibility, or mode-by-branch case when the approved promise can fail independently on that boundary. Consolidate cases that exercise the same failure and correction; each retained state category traces to an independent required failure boundary. +Derive each acceptance criterion from one UI behavior in the requirements. Add a loading/empty/error/lifecycle, route, permission, responsive, accessibility, or mode-by-branch case when the approved promise can fail independently on that boundary. Consolidate cases that exercise the same failure and correction; each retained state category traces to an independent required failure boundary. Verify a current external technology, browser, compatibility, performance, or security fact from an authoritative source only when its truth can change option selection, implementation, or verification. Record unresolved decision-changing facts for the verification loop. @@ -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. 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. +Update requested sections and dependent statements. For `correction_findings`, resolve each received defect within the 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 outcome, desired-future requirements, and non-goals stay true. If the 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 @@ -124,7 +124,7 @@ Document supplied inventory and existing frontend behavior as-is. Trace in-scope ## Completion Check -- No UI or implementation scope exceeds confirmed requirements and required dependencies. +- No UI or implementation scope exceeds the requirements and required dependencies. - 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. diff --git a/dev-workflows-frontend/agents/ui-analyzer.md b/dev-workflows-frontend/agents/ui-analyzer.md index c5c499cc..a2ad0c82 100644 --- a/dev-workflows-frontend/agents/ui-analyzer.md +++ b/dev-workflows-frontend/agents/ui-analyzer.md @@ -12,7 +12,7 @@ You are an AI assistant specializing in UI fact gathering for frontend design. ## Input Parameters - **prd_path**: Approved PRD path (required when one exists) -- **requirements**: Confirmed requirements verbatim (required only when no approved PRD exists) +- **requirements**: Requirements verbatim (required only when no approved PRD exists) - **ui_spec_path**: Path to existing UI Spec, when one exists (optional) - **prototype_path**: Decision-relevant prototype path (optional) - **external_resource_refs**: Selected external-resource records or an empty array (optional) @@ -21,11 +21,11 @@ Supply exactly one of `prd_path` or `requirements`. ## Evidence Boundary -Gather UI facts only; the parent and document owners select scope and design. Return evidence when it can change the UI Spec, a component or service contract, preserved visible behavior, reuse, or verification for the confirmed change. Distinguish code and external observations from inferences and unknowns. +Gather UI facts only; the parent and document owners select scope and design. Return evidence when it can change the UI Spec, a component or service contract, preserved visible behavior, reuse, or verification for the change. Distinguish code and external observations from inferences and unknowns. Use only supplied `external_resource_refs`. Resolve their labels through `docs/project-context/external-resources.md` and inspect the relevant subset through its recorded access method. Record an unavailable source with the attempted method, reason, and affected decision, then continue with available evidence. An empty or omitted list selects repository-only analysis. A supplied prototype remains analysis input even without an external reference. -Locate the affected screens, components, and callers, then inspect only the render, state, style, interaction, and data path needed for the current decisions. Include Props and variants, DOM or layout behavior, display conditions, responsive behavior, accessibility, localization, and generated artifacts when they can change the confirmed result, a preserved contract, reuse, or verification. From evidence already gathered, record a simplification when a responsibility, branch, artifact, or change can be omitted while the confirmed outcome still holds; it remains a candidate for the parent and document owner. Inspect every consumer only when the complete consumer set controls compatibility; otherwise use representative consumers, tests, stories, and style peers. +Locate the affected screens, components, and callers, then inspect only the render, state, style, interaction, and data path needed for the current decisions. Include Props and variants, DOM or layout behavior, display conditions, responsive behavior, accessibility, localization, and generated artifacts when they can change the result, a preserved contract, reuse, or verification. From evidence already gathered, record a simplification when a responsibility, branch, artifact, or change can be omitted while the outcome still holds; it remains a candidate for the parent and document owner. Inspect every consumer only when the complete consumer set controls compatibility; otherwise use representative consumers, tests, stories, and style peers. Stop when another fact cannot change one of those outcomes. @@ -44,7 +44,7 @@ Return one compact JSON object. Put decision-relevant component, state, Props, l {"fact_id": "path:identifier", "area": "UI question", "evidence": "path:line or external source; observed or inferred", "factsToAddress": "decision-relevant behavior, contract, reuse, or verification", "risk": "effect if ignored", "decisionEffect": "UI Spec, design, or verification decision this controls"} ], "simplifications": [ - {"avoidableChange": "responsibility, branch, artifact, or change that can be omitted", "evidence": "path:line, governing source, or focusArea reference", "conditions": "conditions or unknowns under which the confirmed outcome still holds"} + {"avoidableChange": "responsibility, branch, artifact, or change that can be omitted", "evidence": "path:line, governing source, or focusArea reference", "conditions": "conditions or unknowns under which the outcome still holds"} ], "limitations": ["Areas the analysis could not reach with confidence"] } diff --git a/dev-workflows-frontend/agents/ui-spec-designer.md b/dev-workflows-frontend/agents/ui-spec-designer.md index 8cd3c43f..696587c0 100644 --- a/dev-workflows-frontend/agents/ui-spec-designer.md +++ b/dev-workflows-frontend/agents/ui-spec-designer.md @@ -1,6 +1,6 @@ --- name: ui-spec-designer -description: Creates UI Specifications from confirmed requirements and optional prototype code. Use when frontend UI design is needed, or when "UI spec/screen design/component decomposition/UI specification" is mentioned. +description: Creates UI Specifications from requirements and optional prototype code. Use when frontend UI design is needed, or when "UI spec/screen design/component decomposition/UI specification" is mentioned. tools: Read, Write, Edit, MultiEdit, Glob, LS, Bash skills: - documentation-criteria @@ -18,30 +18,30 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow ## Main Responsibilities -1. Analyze confirmed UI requirements and map them to screens, states, and components +1. Analyze the UI requirements and map them to screens, states, and components 2. Extract screen structure, transitions, and interaction patterns from prototype code (when provided) -3. Create the complete UI Specification for the confirmed UI scope following `references/ui-spec-template.md` in the documentation-criteria skill +3. Create the complete UI Specification for the UI scope of the requirements following `references/ui-spec-template.md` in the documentation-criteria skill 4. Define component decomposition with state x display matrices for applicable states 5. Identify reusable existing components in the codebase 6. Define accessibility requirements ## Input Parameters -- **confirmed_requirement_context**: Exact approved PRD path, or the unchanged confirmed convergence record only when no approved PRD exists (required) +- **requirement_context**: Exact approved PRD path, or the unchanged convergence record only when no approved PRD exists (required) - **ui_analysis**: UI analysis JSON for existing UI behavior and external evidence (required) - **codebase_analysis**: Applicable codebase analysis evidence (optional) - **prototype_path**: Decision-relevant prototype path (optional, placed in `docs/ui-spec/assets/{feature-name}/`) -- **prototype_reference_strength**: `binding` or `reference`, accompanying `prototype_path`. When a prototype is provided without a strength, use the confirmed requirement context if it establishes the strength; otherwise record the unresolved strength in Prototype Management and the existing decision-blocking Open Items, and continue work independent of that decision. +- **prototype_reference_strength**: `binding` or `reference`, accompanying `prototype_path`. When a prototype is provided without a strength, use the requirement context if it establishes the strength; otherwise record the unresolved strength in Prototype Management and the existing decision-blocking Open Items, and continue work independent of that decision. - **external_resource_refs**: Selected external-resource records or an empty array (optional) ## Mandatory Process Before UI Spec Creation ### Step 1: Requirement Analysis -1. **Read and understand the confirmed requirement context** - - Extract confirmed UI behaviors and acceptance criteria; preserve existing AC IDs when present +1. **Read and understand the requirement context** + - Extract UI behaviors and acceptance criteria; preserve existing AC IDs when present - Identify screens/views implied by user stories and requirements - - Note accessibility requirements and UI quality metrics from the confirmed context + - Note accessibility requirements and UI quality metrics from the requirement context 2. **Classify ACs by UI relevance** - Which ACs map to specific screens or user interactions @@ -50,7 +50,7 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow ### Step 2: Prototype Code Analysis (when `prototype_path` is provided) 1. **Analyze the relevant prototype surface** - - Start from screens/components mapped to confirmed requirements and follow only required imports + - Start from screens/components mapped to the requirements and follow only required imports - Extract page/screen structure, component hierarchy, routing, material event handlers, and conditional rendering - Catalog only states represented by approved behavior or needed to understand the prototype @@ -86,8 +86,8 @@ Apply evidenced `simplifications` when their recorded condition holds; otherwise 2. **Fill applicable sections**: - Screen list with entry conditions and transitions - Component tree with decomposition - - State x display matrix for each component state required by confirmed requirements, approved UI direction, preserved behavior, or repository/design-system rules - - Interaction definitions linked to existing AC IDs when present, otherwise to an unambiguous confirmed requirement + - State x display matrix for each component state required by the requirements, approved UI direction, preserved behavior, or repository/design-system rules + - Interaction definitions linked to existing AC IDs when present, otherwise to an unambiguous requirement - Existing component reuse map - Design tokens (from existing codebase) - Visual acceptance criteria @@ -99,11 +99,11 @@ Apply evidenced `simplifications` when their recorded condition holds; otherwise Execute file output immediately (considered approved at execution). -When revising from review findings, resolve only the supplied defects within the confirmed UI outcome and accepted UI decisions. Return the conflicting evidence before changing that boundary. +When revising from review findings, resolve only the supplied defects within the UI outcome and accepted UI decisions. Return the conflicting evidence before changing that boundary. ## Quality Checklist -- [ ] All confirmed acceptance criteria with UI relevance are mapped to screens/components +- [ ] All acceptance criteria with UI relevance are mapped to screens/components - [ ] Every in-scope interactive component records each applicable state/display contract; no state exists only to fill the template - [ ] Interaction definitions use EARS format and reference existing AC IDs when present - [ ] Screen transitions have trigger and guard conditions defined @@ -114,7 +114,7 @@ When revising from review findings, resolve only the supplied defects within the - [ ] If prototype provided: Prototype Management records the reference strength - [ ] If prototype provided: the relevant prototype is placed in `docs/ui-spec/assets/` - [ ] Decision-blocking Open Items name the required owner or evidence; non-blocking unknowns remain explicit -- [ ] All UI Spec requirements align with the confirmed requirement context +- [ ] All UI Spec requirements align with the requirement context - [ ] External Resources Used section lists each used `external_resource_refs` entry by its project-tier label with only the feature-specific identifier - [ ] **Component heading uniqueness**: Every component is documented under a section heading whose text is unique within this UI Spec. Use the format `## Component: [ComponentName]` (or `### Component: [ComponentName]` when nested under a screen). - **Disambiguation rule**: When two components share a base name (e.g., the same `AlertCard` rendered as a banner variant and as an inline variant), append a parenthetical qualifier to make each heading unique: `Component: AlertCard (Banner variant)` and `Component: AlertCard (Inline variant)`. Verify uniqueness with a final pass: extract all `Component: ` headings, confirm zero duplicates @@ -122,7 +122,7 @@ When revising from review findings, resolve only the supplied defects within the ## Important Design Principles 1. **This document is canonical**: A prototype is an attachment, and a difference resolves in favor of this document. Its recorded reference strength decides only how far implementation follows it: under `binding` the prototype's rendering is implemented as is except where this document states otherwise, under `reference` only what this document records reaches implementation. -2. **Requirement-driven design**: Every interaction and state must trace back to the confirmed requirement context, preserving AC IDs when present. +2. **Requirement-driven design**: Every interaction and state must trace back to the requirement context, preserving AC IDs when present. 3. **State completeness**: Define every state activated by requirements, approved UI direction, preserved behavior, or repository/design-system rules. 4. **Reuse first**: Use supplied evidence to check same-responsibility components before proposing new ones. Document the decision. 5. **Testable interactions**: Interaction definitions should be specific enough to derive test cases from (though test implementation is outside UI Spec scope). diff --git a/dev-workflows-frontend/skills/ai-development-guide/SKILL.md b/dev-workflows-frontend/skills/ai-development-guide/SKILL.md index b3c9e991..b0fff492 100644 --- a/dev-workflows-frontend/skills/ai-development-guide/SKILL.md +++ b/dev-workflows-frontend/skills/ai-development-guide/SKILL.md @@ -8,11 +8,11 @@ description: Applies language-agnostic and backend technical decision criteria, ## Value-First Engineering Inspect until the evidence identifies the lowest-total-complexity solution that delivers the required user, operator, or maintainer value while keeping the system correct and maintainable. -- Resolve verified problems within confirmed scope or dependencies required for the outcome; report other findings with their owning boundary and evidence without expanding the active change. +- Resolve verified problems within scope or dependencies required for the outcome; report other findings with their owning boundary and evidence without expanding the active change. - Introduce capabilities, infrastructure, abstractions, or speculative edge-case handling when a current outcome, verified constraint, or evidence-backed material risk requires them. -- Treat behavior-preserving maintenance inside the confirmed responsibility as current maintainer value when repository evidence shows it reduces change ambiguity, duplicate ownership, defect risk, or future implementation and verification cost without expanding observable product scope. +- Treat behavior-preserving maintenance inside the assigned responsibility as current maintainer value when repository evidence shows it reduces change ambiguity, duplicate ownership, defect risk, or future implementation and verification cost without expanding observable product scope. -Judge total complexity across every activated surface: user decisions, settings, modes, concepts, outputs, persistent state, and implementation paths, together with their UX, runtime, implementation, testing, documentation, and maintenance cost. Compare only dimensions that differ between viable approaches. Prefer reuse or no new mechanism when it delivers the same confirmed value and proof at lower total complexity. +Judge total complexity across every activated surface: user decisions, settings, modes, concepts, outputs, persistent state, and implementation paths, together with their UX, runtime, implementation, testing, documentation, and maintenance cost. Compare only dimensions that differ between viable approaches. Prefer reuse or no new mechanism when it delivers the same required value and proof at lower total complexity. ## Technical Anti-patterns (Red Flag Patterns) @@ -140,7 +140,7 @@ Keep concrete implementations separate while their apparent similarity is accide **Avoidance Methods**: - Before implementation, always search for similar functionality (using domain, responsibility, configuration patterns as keywords) - Similar functionality found → Verify that its contract, lifecycle, and repository usage are representative; reuse or extend it when compatible, otherwise record why it is not a valid model -- Similar functionality is technical debt → Repair it when it blocks the current outcome, was caused by the current change, or lies in confirmed scope; otherwise report it separately. Create an ADR when the repair requires an architectural decision +- Similar functionality is technical debt → Repair it when it blocks the current outcome, was caused by the current change, or lies in scope; otherwise report it separately. Create an ADR when the repair requires an architectural decision - No similar functionality exists → Implement new functionality following existing design philosophy - Preserve the evidence for each reuse, extend, separate, or repair decision in the applicable implementation or design record - **Reference representativeness check**: When adopting a pattern or dependency from nearby code, inspect the changed area and enough representative consumers or siblings to establish compatibility; expand only when competing patterns or a shared/public contract can change the choice @@ -184,7 +184,7 @@ Follow repository-declared command composition or ordering when it exists. Other ### Scope Expansion - Apply implementation/edit instructions to the accepted outcome and its governing scope. -- Treat explicit restrictions and quantities ("one", "this file", "only X") in the governing request or confirmed outcome, desired-future requirements, and non-goals as hard boundaries; treat technical-artifact How as a correctable baseline when repository evidence invalidates it without changing those boundaries +- Treat explicit restrictions and quantities ("one", "this file", "only X") in the governing request or the outcome, desired-future requirements, and non-goals as hard boundaries; treat technical-artifact How as a correctable baseline when repository evidence invalidates it without changing those boundaries - Treat referenced or expected paths as investigation starting points unless the governing source explicitly makes them exclusive - Copy/move/mirror requests preserve content verbatim; edit content only when requested - Port/translation requests preserve intent and behavior; adapt only what the destination context requires diff --git a/dev-workflows-frontend/skills/documentation-criteria/SKILL.md b/dev-workflows-frontend/skills/documentation-criteria/SKILL.md index 7f745120..9c5500b3 100644 --- a/dev-workflows-frontend/skills/documentation-criteria/SKILL.md +++ b/dev-workflows-frontend/skills/documentation-criteria/SKILL.md @@ -13,11 +13,11 @@ Each document fixes one class of decision that the repository alone cannot suppl - **PRD** — Fixes the business outcome and the acceptance criteria later work traces to. Its AC IDs are the traceability keys that the Design Doc, UI Spec, and test selection reuse; without them each consumer re-derives requirements from prose and the link between a test and the value it protects is lost. Implementation details belong to the Design Doc, selection rationale to an ADR, phases and task breakdown to the Work Plan. Later design, review, and test selection treat its content as governing, so a precondition held outside the repository change, such as release execution or organizational approval, appears in it only when the user's wording raises it. -- **ADR** — Records one durable technical choice and the options it beat, so later work can tell a deliberate decision from an accident. Without it a future change either re-runs the same comparison or silently reverses it. `Accepted` records the currently selected means, not an obligation to retain it: when later evidence supports a smaller sufficient choice, update or supersede the decision while the confirmed outcome, desired-future requirements, and non-goals remain true. End-to-end implementation design belongs to the Design Doc, schedule and repository tasks to the Work Plan. +- **ADR** — Records one durable technical choice and the options it beat, so later work can tell a deliberate decision from an accident. Without it a future change either re-runs the same comparison or silently reverses it. `Accepted` records the currently selected means, not an obligation to retain it: when later evidence supports a smaller sufficient choice, update or supersede the decision while the outcome, desired-future requirements, and non-goals remain true. End-to-end implementation design belongs to the Design Doc, schedule and repository tasks to the Work Plan. - **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. 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. +- **Design Doc** — Records the complete implementation design for the scope of the requirements: 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 requirement that describes such work is met by designing the capability it uses. When repository evidence invalidates technical How while the 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. Each task is repository work the executor completes and verifies during implementation using repository artifacts and its own output. @@ -49,7 +49,7 @@ A qualifying ADR decision point sets the floor at Medium because it creates a du ## ADR Decision Filters -Apply the Choice filter, then the Durability filter, to each technical topic inside the confirmed implementation scope. Apply them independently from Structural Scale, and check existing ADRs first. +Apply the Choice filter, then the Durability filter, to each technical topic inside the implementation scope. Apply them independently from Structural Scale, and check existing ADRs first. 1. **Choice requires judgment** — current requirements, accepted decisions, and representative repository evidence support at least two credible, materially distinct options whose selection requires comparison. 2. **Decision is durable** — choosing among those options materially changes responsibility, dependency direction, a shared contract, persistence, a technology dependency, reversibility, or lifecycle cost that future work must preserve or understand. diff --git a/dev-workflows-frontend/skills/documentation-criteria/references/adr-template.md b/dev-workflows-frontend/skills/documentation-criteria/references/adr-template.md index debdb11b..da261f42 100644 --- a/dev-workflows-frontend/skills/documentation-criteria/references/adr-template.md +++ b/dev-workflows-frontend/skills/documentation-criteria/references/adr-template.md @@ -6,7 +6,7 @@ A created ADR starts at `Proposed` and advances `Proposed` → `Accepted` → `Deprecated`/`Superseded`/`Rejected`. -`Accepted` records the currently selected means, not an obligation to retain it. When later evidence supports a smaller sufficient choice, update or supersede this decision while the confirmed outcome, desired-future requirements, and non-goals remain true. +`Accepted` records the currently selected means, not an obligation to retain it. When later evidence supports a smaller sufficient choice, update or supersede this decision while the outcome, desired-future requirements, and non-goals remain true. ## Context @@ -16,7 +16,7 @@ A created ADR starts at `Proposed` and advances `Proposed` → `Accepted` → `D - **Question**: [The technical choice requiring comparison and selection] - **Why a decision exists**: [Evidence for at least two credible, materially distinct options] -- **Scope boundary**: [Confirmed requirement or existing contract this decision serves] +- **Scope boundary**: [Requirement or existing contract this decision serves] ## Decision @@ -39,12 +39,12 @@ A created ADR starts at `Proposed` and advances `Proposed` → `Accepted` → `D Compare credible, materially distinct options supported by current requirements and repository evidence. The evidence determines how many options exist, and relative evidence-backed cost is sufficient. Add a Mermaid option-comparison diagram only when the relationship between options stays unclear in the table below. -| Option | Confirmed product value | Repository fit | Total complexity | Maintainability | Material trade-offs | Reversibility | +| Option | Product value from the requirements | Repository fit | Total complexity | Maintainability | Material trade-offs | Reversibility | |--------|-------------------------|----------------|------------------|-----------------|---------------------|---------------| | [Option 1] | [value required now] | [fit and evidence] | [materially different activated surfaces and lifecycle costs] | [fit with ownership and representative patterns] | [trade-offs] | [cost and conditions to reverse] | | [Option 2] | [value required now] | [fit and evidence] | [materially different activated surfaces and lifecycle costs] | [fit with ownership and representative patterns] | [trade-offs] | [cost and conditions to reverse] | -**Selected**: [The smallest sufficient option whose total complexity is justified by confirmed product value and repository evidence] +**Selected**: [The smallest sufficient option whose total complexity is justified by product value from the requirements and repository evidence] ## Consequences 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 b75daa37..fc98ba14 100644 --- a/dev-workflows-frontend/skills/documentation-criteria/references/design-template.md +++ b/dev-workflows-frontend/skills/documentation-criteria/references/design-template.md @@ -27,7 +27,7 @@ Lists each external resource this feature depends on with its feature-specific i ### Requirement Convergence -Records exclusions **the user decided** at requirement time. Mark the first two bullets `N/A — covered by PRD [path]` when a PRD holds them, or the whole section `N/A — reverse-engineer/as-is document`. Open questions stay here in every case because design readiness depends on them. This section contains confirmed requirements and boundaries; evaluation requests, speculative ideas, and unselected mechanisms remain only in pre-confirmation convergence context. +Records exclusions **the user decided** at requirement time. Mark the first two bullets `N/A — covered by PRD [path]` when a PRD holds them, or the whole section `N/A — reverse-engineer/as-is document`. Open questions stay here in every case because design readiness depends on them. This section contains the user-selected requirements and boundaries; evaluation requests, speculative ideas, and unselected mechanisms remain only in active convergence context. - **Outcome**: [one observable result this change must produce] - **Non-Goals**: [capability the user excluded | None — user confirmed there are none] @@ -93,7 +93,7 @@ Keywords determine test type and reduce ambiguity. The rows below demonstrate EARS syntax only. Replace their domain, values, messages, and thresholds with requirements from the PRD or accepted requirement analysis; none is a default product requirement. -Keep the smallest representative set of observable behaviors that has a stable repository-verifiable pass/fail condition. Use repository-controlled contract/interface proof instead of a live external connection unless the confirmed requirement needs that boundary. Include a performance threshold only with a sourced target and reproducible benchmark, and exact visual positioning only with an approved visual contract and deterministic comparison. Implementation details remain outside ACs. +Keep the smallest representative set of observable behaviors that has a stable repository-verifiable pass/fail condition. Use repository-controlled contract/interface proof instead of a live external connection unless a requirement needs that boundary. Include a performance threshold only with a sourced target and reproducible benchmark, and exact visual positioning only with an approved visual contract and deterministic comparison. Implementation details remain outside ACs. ### [Functional Requirement 1] @@ -198,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, traced to its originating requirement, accepted decision, or repository rule or contract] +- **Subtraction result**: [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/documentation-criteria/references/prd-template.md b/dev-workflows-frontend/skills/documentation-criteria/references/prd-template.md index d0fea276..1769f438 100644 --- a/dev-workflows-frontend/skills/documentation-criteria/references/prd-template.md +++ b/dev-workflows-frontend/skills/documentation-criteria/references/prd-template.md @@ -61,13 +61,13 @@ C4Context ### Future / Out of Scope -Record user-authored non-goals and any current exclusion required to make the MVP boundary executable. The table is limited to confirmed boundaries; evaluation requests, speculative ideas, and unselected possibilities remain only in pre-confirmation convergence context. Record `None — user confirmed there are none` when the user considered exclusions and found none. +Record user-authored non-goals and any current exclusion required to make the MVP boundary executable. The table is limited to these boundaries; evaluation requests, speculative ideas, and unselected possibilities remain only in active convergence context. Record `None — user confirmed there are none` when the user considered exclusions and found none. -Use `user` for a user-authored non-goal and `analysis` for a current exclusion required to make the confirmed MVP boundary executable. +Use `user` for a user-authored non-goal and `analysis` for a current exclusion required to make the MVP boundary executable. | Capability | Disposition | Origin | Reason | |---|---|---|---| -| [Confirmed non-goal or required current scope exclusion] | future / out-of-scope | user / analysis | [Governing scope reason] | +| [User-authored non-goal or required current scope exclusion] | future / out-of-scope | user / analysis | [Governing scope reason] | ## Non-Functional Requirements @@ -87,14 +87,14 @@ Use `user` for a user-authored non-goal and `analysis` for a current exclusion r - [Considerations for future scaling] ### Accessibility (when feature includes UI) -- Compliance standard (when established by an accepted organizational, legal, contractual, or confirmed product source): [standard] +- Compliance standard (when established by an accepted organizational, legal, contractual, or user-supplied product source): [standard] - Target assistive technologies: [Screen reader, keyboard operation, voice control, etc.] - Platform requirements: [e.g., app store review requirements] - Known constraints: [e.g., external library limitations] ## Success Criteria -State observable success for the confirmed outcome. Include only sourced quantitative/UI targets; in as-is documentation, distinguish observed measures from unknown business objectives. The examples below are optional shapes, not a required metric count. +State observable success for the outcome. Include only sourced quantitative/UI targets; in as-is documentation, distinguish observed measures from unknown business objectives. The examples below are optional shapes, not a required metric count. ### Quantitative Metrics 1. [Metric name]: [numeric target] measured by [method] within [timeframe] diff --git a/dev-workflows-frontend/skills/documentation-criteria/references/ui-spec-template.md b/dev-workflows-frontend/skills/documentation-criteria/references/ui-spec-template.md index 46180972..e96dc373 100644 --- a/dev-workflows-frontend/skills/documentation-criteria/references/ui-spec-template.md +++ b/dev-workflows-frontend/skills/documentation-criteria/references/ui-spec-template.md @@ -4,9 +4,9 @@ [Purpose and scope of this UI Specification in 2-3 sentences] -### Confirmed Requirement Context +### Requirement Context - PRD path: [docs/prd/xxx-prd.md | "N/A — based on requirements analysis output"] -- Feature scope: [Which confirmed requirements this UI Spec covers] +- Feature scope: [Which requirements this UI Spec covers] ### Design Source | Source | Path | Version | @@ -35,7 +35,7 @@ Lists each external resource this feature depends on with its feature-specific i ## AC Traceability (Prototype) -Map confirmed acceptance criteria to prototype references, preserving existing AC IDs when present. Skip this section if no prototype is provided. +Map acceptance criteria to prototype references, preserving existing AC IDs when present. Skip this section if no prototype is provided. | Criterion ID / Reference | Criterion Summary | Screen / State | Prototype Reference (element ID / path) | Adoption Decision | |-------|-----------|----------------|----------------------------------------|-------------------| @@ -76,7 +76,7 @@ Add a screen-transition or component-tree Mermaid diagram only when the material #### State x Display Matrix -The matrix contains one row for each state supported by confirmed requirements, approved UI direction, preserved behavior, or repository/design-system rules. +The matrix contains one row for each state supported by the requirements, approved UI direction, preserved behavior, or repository/design-system rules. | State | Trigger | Display | Interaction / Recovery | Evidence | |-------|---------|---------|------------------------|----------| diff --git a/dev-workflows-frontend/skills/frontend-ai-guide/SKILL.md b/dev-workflows-frontend/skills/frontend-ai-guide/SKILL.md index 416c9cfd..c4138e25 100644 --- a/dev-workflows-frontend/skills/frontend-ai-guide/SKILL.md +++ b/dev-workflows-frontend/skills/frontend-ai-guide/SKILL.md @@ -8,11 +8,11 @@ description: Applies React/TypeScript-specific technical decision criteria, anti ## Value-First Engineering Inspect until the evidence identifies the lowest-total-complexity solution that delivers the required user or maintainer value while keeping the UI correct and maintainable. -- Resolve verified problems within confirmed scope or dependencies required for the outcome; report other findings with their owning boundary and evidence without expanding the active change. +- Resolve verified problems within scope or dependencies required for the outcome; report other findings with their owning boundary and evidence without expanding the active change. - Introduce state, props, variants, abstractions, or speculative edge-case handling when a current outcome, verified constraint, or evidence-backed material risk requires them. -- Treat behavior-preserving maintenance inside the confirmed responsibility as current maintainer value when repository evidence shows it reduces change ambiguity, duplicate ownership, defect risk, or future implementation and verification cost without expanding observable product scope. +- Treat behavior-preserving maintenance inside the assigned responsibility as current maintainer value when repository evidence shows it reduces change ambiguity, duplicate ownership, defect risk, or future implementation and verification cost without expanding observable product scope. -Judge total complexity across every activated user decision, prop, state, variant, concept, output, persistent state, and component or hook path, together with its UX, runtime, implementation, testing, documentation, and maintenance cost. Compare only dimensions that differ between viable approaches. Prefer reuse or no new mechanism when it delivers the same confirmed value and proof at lower total complexity. +Judge total complexity across every activated user decision, prop, state, variant, concept, output, persistent state, and component or hook path, together with its UX, runtime, implementation, testing, documentation, and maintenance cost. Compare only dimensions that differ between viable approaches. Prefer reuse or no new mechanism when it delivers the same required value and proof at lower total complexity. ## Technical Anti-patterns (Red Flag Patterns) @@ -99,7 +99,7 @@ Keep concrete implementations separate while their similarity is accidental or t **Avoidance Methods**: - Before implementation, always search for similar functionality (using domain, responsibility, component patterns as keywords) - Similar functionality found → Verify that its props, lifecycle, design-system role, and repository usage are representative; reuse or extend it when compatible, otherwise record why it is not a valid model -- Similar functionality is technical debt → Repair it when it blocks the current outcome, was caused by the current change, or lies in confirmed scope; otherwise report it separately. Create an ADR when the repair requires an architectural decision +- Similar functionality is technical debt → Repair it when it blocks the current outcome, was caused by the current change, or lies in scope; otherwise report it separately. Create an ADR when the repair requires an architectural decision - No similar functionality exists → Implement new functionality following existing design philosophy - Preserve the evidence for each reuse, extend, separate, or repair decision in the applicable implementation or design record diff --git a/dev-workflows-frontend/skills/implementation-approach/SKILL.md b/dev-workflows-frontend/skills/implementation-approach/SKILL.md index 84ebdcff..46ee41dc 100644 --- a/dev-workflows-frontend/skills/implementation-approach/SKILL.md +++ b/dev-workflows-frontend/skills/implementation-approach/SKILL.md @@ -33,7 +33,7 @@ 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. 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 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. +4. **Subtraction Check**: Remove each proposed addition and re-test its governing condition. Retain it only when the outcome, a required boundary, or necessary proof becomes unmet at its origin (a 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. diff --git a/dev-workflows-frontend/skills/recipe-diagnose/SKILL.md b/dev-workflows-frontend/skills/recipe-diagnose/SKILL.md index 687bd7f1..eb3e1ae6 100644 --- a/dev-workflows-frontend/skills/recipe-diagnose/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-diagnose/SKILL.md @@ -135,7 +135,7 @@ Continue investigation while an available action can advance a material gap. Com ### Step 5: Solution Boundary -After coverage is closed, pass the complete verified cause set to solver. Ownership, contract, and technical design corrections are ordinary solution candidates when they preserve the confirmed outcome, desired-future requirements, and non-goals; detecting a design gap does not create a user decision. If evidence shows those value boundaries cannot all remain true, or a proposed remedy requires authorization for an irreversible external action, report that exact boundary with the solution evidence instead of inventing a choice. +After coverage is closed, pass the complete verified cause set to solver. Ownership, contract, and technical design corrections are ordinary solution candidates when they preserve the outcome, desired-future requirements, and non-goals; detecting a design gap does not create a user decision. If evidence shows those value boundaries cannot all remain true, or a proposed remedy requires authorization for an irreversible external action, report that exact boundary with the solution evidence instead of inventing a choice. ### Step 6: Solution Derivation (solver) diff --git a/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md b/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md index d7bddcd1..c6e4651d 100644 --- a/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md @@ -21,7 +21,7 @@ Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or g ## Execution Gate -Complete Steps 1-7 in order for the confirmed adjustment outcome. Advance only through the current step's stated evidence, quality result, or user stop; skip work only when its stated condition is false. Report completion after every applicable Completion Criterion and retained-limitation retry is satisfied. +Complete Steps 1-7 in order for the adjustment outcome. Advance only through the current step's stated evidence, quality result, or user stop; skip work only when its stated condition is false. Report completion after every applicable Completion Criterion and retained-limitation retry is satisfied. ## Workflow Overview @@ -49,9 +49,9 @@ Adjustment request → conditional external resource evidence - Structural boundary judgment via documentation-criteria - Adjustment edits and verification against the design source (run in this session) - Quality verification via quality-fixer-frontend -- Commit the confirmed adjustment outcome +- Commit the adjustment outcome -**Responsibility Boundary**: This skill completes when the confirmed adjustment is committed after its quality cycle and any retained proof limitation receives its final retry. Adjustment work is end-to-end within this recipe; parent session owns edits, verification loops, quality-result routing, and commits. +**Responsibility Boundary**: This skill completes when the adjustment is committed after its quality cycle and any retained proof limitation receives its final retry. Adjustment work is end-to-end within this recipe; parent session owns edits, verification loops, quality-result routing, and commits. **Escalation Boundary**: Escalate to the full frontend design phase when the request crosses a responsibility or approved UI boundary, requires a complete Design Doc, or contains a technical choice that passes documentation-criteria's Choice and Durability filters. @@ -73,7 +73,7 @@ Inspect the named or current UI and the smallest sufficient repository evidence ### Step 3: Scale Judgment 1. Read the candidate write set from Step 2. -2. Apply Structural Scale to the confirmed outcome and responsibility boundary. Use write-set count as supporting evidence only: +2. Apply Structural Scale to the adjustment outcome and responsibility boundary. Use write-set count as supporting evidence only: - **0 files**: The adjustment request did not map to any existing file. Escalate to the user with the message "No write target identified from the adjustment request. Please clarify which component(s) should change, or run the full frontend design phase if this is a new feature." Stop this recipe. - **Direct adjustment**: One coherent UI outcome follows existing component, state, interaction, and verification patterns inside one responsibility boundary. Continue directly to adjustment context even when generated or tightly coupled files increase the count. - **Design required**: The change crosses a responsibility or approved UI contract, coordinates independently valuable outcomes, or needs a durable technical choice between credible alternatives. Escalate to the full frontend design phase. @@ -96,12 +96,12 @@ Execute Skill: typescript-rules before planning or applying adjustment edits. Execute Skill: implementation-approach before planning or applying adjustment edits. Execute Skill: testing-principles before adding or changing tests. -Implement the confirmed adjustment outcome across its affected files: -1. **Plan the edit** from the confirmed adjustment context and relevant external resource (e.g., design origin's fetched_summary). +Implement the adjustment outcome across its affected files: +1. **Plan the edit** from the Step 4 adjustment context and relevant external resource (e.g., design origin's fetched_summary). 2. **Apply the edit** using Edit / Write / MultiEdit on the affected files. -3. **Verify the confirmed target** using applicable repository/UI Spec evidence and any external source selected in Step 1. Reuse its available access or verification method; compare rendering, interaction or tokens only where they determine the requested adjustment. +3. **Verify the adjustment target** using applicable repository/UI Spec evidence and any external source selected in Step 1. Reuse its available access or verification method; compare rendering, interaction or tokens only where they determine the requested adjustment. 4. **Refine and re-verify** until the adjustment matches the design source, or matches the user-confirmed adjustment target when no separate design source exists. -5. When the complete adjustment matches the confirmed target, proceed to Step 6. +5. When the complete adjustment matches the adjustment target, proceed to Step 6. When required proof is unavailable, use sufficient file-based or other available evidence; retain an exact proof limitation otherwise. Ask for manual confirmation only when a user-owned interpretation is needed to determine the adjustment target. @@ -109,21 +109,21 @@ When required proof is unavailable, use sufficient file-based or other available - Invoke **quality-fixer-frontend** using Agent tool - `subagent_type: "dev-workflows-frontend:quality-fixer-frontend"` - - `description: "Quality verification for confirmed adjustment"` - - `direct_scope`: Copy the confirmed adjustment request and preserved visible behavior from Step 4 unchanged. + - `description: "Quality verification for adjustment"` + - `direct_scope`: Copy the adjustment request and preserved visible behavior from Step 4 unchanged. - `governing_sources`: Pass the existing UI and design source references used for the adjustment unchanged. - - `observable_verification`: Pass the confirmed adjustment request from Step 4 and applicable acceptance criteria from the governing sources unchanged. + - `observable_verification`: Pass the adjustment request from Step 4 and applicable acceptance criteria from the governing sources unchanged. - Pass `qualityCommand` when available (caller first, otherwise current task). - Route the quality-fixer-frontend response by `status`: - `pass` → proceed to Step 7 - - `stub_detected` → return to Step 5 to complete the confirmed adjustment, then re-invoke quality-fixer-frontend + - `stub_detected` → return to Step 5 to complete the adjustment, then re-invoke quality-fixer-frontend - `verification_incomplete` → retain the complete result for final retry and proceed to Step 7 - `blocked` → Apply subagents-orchestration-guide Specialist Result Acceptance using the result's semantic evidence, changed files, and repository state ### Step 7: Commit -Before committing, use repository state at the commit boundary as the primary evidence and account for every actual change by mapping it to the confirmed adjustment, preserved pattern, or a necessary dependency, test, or generated artifact. Every required change is ready for the adjustment commit, accidental changes introduced during the adjustment are removed, and existing worktree changes unrelated to the confirmed adjustment remain intact. +Before committing, use repository state at the commit boundary as the primary evidence and account for every actual change by mapping it to the adjustment, preserved pattern, or a necessary dependency, test, or generated artifact. Every required change is ready for the adjustment commit, accidental changes introduced during the adjustment are removed, and existing worktree changes unrelated to the adjustment remain intact. -Commit the confirmed adjustment after `pass` or `verification_incomplete`. For the latter, derive and append one `Verification-Limitation: ` and `Verification-Affected: ` trailer pair per retained limitation. +Commit the adjustment after `pass` or `verification_incomplete`. For the latter, derive and append one `Verification-Limitation: ` and `Verification-Affected: ` trailer pair per retained limitation. On continuation, reconstruct retained limitations from the verification trailers on commits already completed for this request. After the adjustment is committed, retry each retained verification limitation once with quality-fixer-frontend. When the retry returns `pass`, remove that limitation from retained state. Commit any resulting fixes through Steps 6→7, and include only a repeated limitation in the completion report. @@ -133,9 +133,9 @@ On continuation, reconstruct retained limitations from the verification trailers - [ ] UI Spec applicability and the candidate write set were determined from the requested UI and sufficient repository evidence - [ ] Structural boundary judgment applied; changes requiring complete design or a qualifying durable decision escalated - [ ] Adjustment context, including the affected files, was presented and confirmed once -- [ ] The confirmed adjustment outcome is implemented; each declared verification mechanism ran, received manual confirmation where required, or retained its exact proof limitation after final retry -- [ ] The confirmed adjustment completed quality-fixer-frontend before commit; retained proof limitations were retried and reported -- [ ] The confirmed adjustment is committed +- [ ] The adjustment outcome is implemented; each declared verification mechanism ran, received manual confirmation where required, or retained its exact proof limitation after final retry +- [ ] The adjustment completed quality-fixer-frontend before commit; retained proof limitations were retried and reported +- [ ] The adjustment is committed ## Output Example diff --git a/dev-workflows-frontend/skills/recipe-front-design/SKILL.md b/dev-workflows-frontend/skills/recipe-front-design/SKILL.md index fdab87bf..24205264 100644 --- a/dev-workflows-frontend/skills/recipe-front-design/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-front-design/SKILL.md @@ -39,13 +39,13 @@ At each Agent invocation below, build the prompt as a mechanical extraction: cop ## Step 1: Select the Governing Requirement Source -Use the approved PRD path when one exists. Otherwise use the confirmed requirements verbatim. +Use the approved PRD path when one exists. Otherwise use the requirements verbatim. -Set `confirmed_requirement_context` to the approved PRD path exactly. Only when no approved PRD exists, use the orchestrator-confirmed convergence record unchanged. +Set `requirement_context` to the approved PRD path exactly. Only when no approved PRD exists, use the orchestrator's convergence record unchanged. ## Step 2: Collect Repository Decision Material -Invoke `dev-workflows-frontend:codebase-analyzer` once for the complete confirmed scope with exactly `prd_path: [approved PRD path]`, or `requirements: [confirmed requirements verbatim]` when no approved PRD exists. +Invoke `dev-workflows-frontend:codebase-analyzer` once for the complete scope with exactly `prd_path: [approved PRD path]`, or `requirements: [requirements verbatim]` when no approved PRD exists. Require one valid JSON result and let the analyzer discover affected paths, responsibility boundaries, and cross-layer contracts. Treat `focusAreas` as existing-behavior safeguards rather than requirements. @@ -68,7 +68,7 @@ prd_path: [approved PRD path] or, when no approved PRD exists: ```text -requirements: [confirmed requirements verbatim] +requirements: [requirements verbatim] ``` Add only an existing `ui_spec_path`, a decision-relevant `prototype_path`, and selected `external_resource_refs` or `[]`. @@ -87,7 +87,7 @@ Judge all four convergence fields. Assign `cost` from Step 2 structural evidence Determine Structural Scale from outcomes and responsibility boundaries; file count is supporting evidence only. Resolve candidate decision points against the governing source, applicable code/UI `simplifications`, `reuse`, and `invalidations`; applicable UI facts may support or contradict the remaining options. Apply documentation-criteria Choice and Durability filters only after this convergence and record passing points as `adrDecisionPoints`; an empty list is valid. -Present the requirement-convergence Scope Confirmation. Place affected responsibilities, applicable simplifications with their conditions, and qualifying ADR points or `none` under **Decision evidence**; place Structural Scale, UI Spec applicability, and the recommended document route under **Workflow**. Offer proceed, or correct and re-run. Ask a question only when its answer can change a convergence field, the confirmed outcome, or scope. Continue only when every convergence field is `ready` or `weak-but-explicit`. `[Stop: Scope confirmation]`. +Present the requirement-convergence Scope Confirmation. Place affected responsibilities, applicable simplifications with their conditions, and qualifying ADR points or `none` under **Decision evidence**; place Structural Scale, UI Spec applicability, and the recommended document route under **Workflow**. Offer proceed, or correct and re-run. Ask a question only when its answer can change a convergence field, the outcome, or scope. Continue only when every convergence field is `ready` or `weak-but-explicit`. `[Stop: Scope confirmation]`. ## Step 5: Create and Approve the UI Spec @@ -96,7 +96,7 @@ Run this step only when Step 3 determined that a UI Spec applies. Invoke `dev-workflows-frontend:ui-spec-designer` with exact inputs: ```text -confirmed_requirement_context: [the value fixed in Step 1] +requirement_context: [the value set in Step 1] ui_analysis: [complete Step 3 UI analyzer JSON unchanged] codebase_analysis: [complete Step 2 codebase-analyzer JSON unchanged] prototype_path: [decision-relevant path from Step 3 exactly, or absent] @@ -110,8 +110,8 @@ Invoke `dev-workflows-frontend:document-reviewer` with exact inputs: `doc_type: When `adrDecisionPoints` is non-empty: -1. Route shared/backend-owned points to technical-designer first, then frontend-owned points to technical-designer-frontend. Invoke each owner with exact inputs: `document_to_create: ADRBatch`; `confirmed_requirement_context`; its ordered `decision_points` confirmed in Step 4, unchanged; `decision_materials` as the corresponding Step 2 `decisionMaterials.candidateDecisionPoints` objects copied unchanged in that order; and `ui_spec_path` only when the approved UI Spec constrains that owner's decision. Run owner batches serially so each batch allocates ADR numbers after the preceding batch exists. -2. Collect all returned paths and invoke `dev-workflows-frontend:document-reviewer` once with exact inputs: `doc_type: ADRBatch`, `targets: [all paths]`, and `confirmed_requirement_context`. The reviewer follows the approved UI Spec cited by the ADRs when it can change the decision review. +1. Route shared/backend-owned points to technical-designer first, then frontend-owned points to technical-designer-frontend. Invoke each owner with exact inputs: `document_to_create: ADRBatch`; `requirement_context`; its ordered `decision_points` from Step 4, unchanged; `decision_materials` as the corresponding Step 2 `decisionMaterials.candidateDecisionPoints` objects copied unchanged in that order; and `ui_spec_path` only when the approved UI Spec constrains that owner's decision. Run owner batches serially so each batch allocates ADR numbers after the preceding batch exists. +2. Collect all returned paths and invoke `dev-workflows-frontend:document-reviewer` once with exact inputs: `doc_type: ADRBatch`, `targets: [all paths]`, and `requirement_context`. The reviewer follows the approved UI Spec cited by the ADRs when it can change the decision review. 3. Route the reviewer verdict first: `pass` proceeds with `issues: []`; `needs_revision` applies Review Resolution, updates one ADR per path serially, and re-reviews the complete batch; `rejected` resolves the governing-source conflict before another review. 4. Present one batch decision after Review Resolution converges, including a decline-only result; unresolved governing-source conflicts still block approval. `[Stop: ADR batch approval]`. 5. After user approval, set every ADR status to `Accepted` and verify the status update. @@ -123,7 +123,7 @@ Create the complete frontend MVP implementation design from reviewed artifacts a Invoke `dev-workflows-frontend:technical-designer-frontend` with exactly: - `document_to_create: DesignDoc`; -- `confirmed_requirement_context`; +- `requirement_context`; - `structural_scale`; - applicable approved `ui_spec_path` exactly and selected external-resource reference records unchanged; - `adr_paths: [accepted paths or []]`; @@ -140,11 +140,11 @@ Keep verifier observations unchanged so corrections remain traceable to observed Invoke `dev-workflows-frontend:code-verifier` with `doc_type: design-doc` and `document_path` as the Design Doc path returned by technical-designer-frontend, unchanged, to verify current premises and feasibility while treating planned behavior as intent. Apply Review Resolution before document review; send applied findings to a fresh technical-designer-frontend update invocation with `Operation Mode: update`, `Existing Document: [Design Doc path]`, and `correction_findings: [complete findings unchanged except for their dispositions]`. The designer applies its review-triggered bounded self-verification gate for an unverified decision-changing premise; this fresh designer is the sole correction specialist and selects the evidence route. Rerun verification after an applied correction with the previous complete result, dispositions, and correction diff or paths as `prior_feedback`, then build one `verification_evidence` object from the latest result. Continue at the Review Resolution convergence condition. -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. +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 `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, 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. +- `rejected`: resolve technical governing-source conflicts through Review Resolution; ask the user only when the 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. @@ -153,7 +153,7 @@ Present the applicable UI Spec, Design Doc, accepted ADR paths, resolved limitat ## Completion Criteria - External and prototype evidence was requested only when it controlled a current decision. -- Scope and Structural Scale were confirmed from outcomes and responsibility boundaries. +- Scope and Structural Scale were determined from outcomes and responsibility boundaries. - ADRs exist only for points passing both filters, and the batch received one review and approval. - An applicable UI Spec and a complete frontend Design Doc exist regardless of ADR need. - Applicable existing UI behavior, contracts, assumptions, states, equivalence, and verification safeguards reached the Design Doc. diff --git a/dev-workflows-frontend/skills/recipe-front-plan/SKILL.md b/dev-workflows-frontend/skills/recipe-front-plan/SKILL.md index 16635993..c0489a19 100644 --- a/dev-workflows-frontend/skills/recipe-front-plan/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-front-plan/SKILL.md @@ -58,7 +58,7 @@ Follow the planning process below: - `description`: "Test skeleton generation" - `design_docs: [Design Doc path]` - `ui_spec: [UI Spec path]` when one exists - - `confirmed_requirement_context`: approved PRD path named by the Design Doc, or its unchanged Requirement Convergence record when no PRD exists + - `requirement_context`: approved PRD path named by the Design Doc, or its unchanged Requirement Convergence record when no PRD exists - Follow subagents-orchestration-guide HC-06 for generated-path and empty-lane coverage checks - Pass every non-null generated skeleton path to work-planner; treat an evidence-backed empty lane as complete for that lane and continue to work-planner @@ -81,7 +81,7 @@ Invoke document-reviewer to review the work plan: ### Step 5: Present for Approval - Present the reviewed work plan to the user for batch approval. If the user requests changes, re-invoke work-planner with the user's requested changes verbatim and re-run Step 4. -- Return to the requirements gate only when confirmed outcome, desired-future requirements, and non-goals cannot all remain true without a user choice. +- Return to the requirements gate only when the outcome, desired-future requirements, and non-goals cannot all remain true without a user choice. ## Response at Completion **Recommended**: End with the following standard response after plan content approval diff --git a/dev-workflows-frontend/skills/recipe-front-review/SKILL.md b/dev-workflows-frontend/skills/recipe-front-review/SKILL.md index c6f0aa6c..6fc502c2 100644 --- a/dev-workflows-frontend/skills/recipe-front-review/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-front-review/SKILL.md @@ -98,7 +98,7 @@ Approve the proposed changes: This review command authorizes analysis; use AskUserQuestion to obtain separate implementation authority. The batch option is **"approve all proposed `apply` routes"** and its scope consists exclusively of those routes. When the approved change set is empty, proceed directly to Step 9. -Pass approved findings, routes, covered files/sections, and any stated total size budget to update or fix agents. Before re-validation, map every diff hunk to an approved finding or required consistency update. Remove accidental unmapped changes; when a necessary change would alter a confirmed value boundary or explicit size constraint, return to Requirement Change Detection. +Pass approved findings, routes, covered files/sections, and any stated total size budget to update or fix agents. Before re-validation, map every diff hunk to an approved finding or required consistency update. Remove accidental unmapped changes; when a necessary change would alter a value boundary or explicit size constraint, return to Requirement Change Detection. ### Step 5: Design-Side Update @@ -130,9 +130,9 @@ Run this step only when the user routed at least one finding to `d`. When no `d` Invoke task-executor-frontend using Agent tool: - `subagent_type`: "dev-workflows-frontend:task-executor-frontend" - `description`: "Execute review fixes" -- `direct_scope`: Apply the approved frontend corrections within the confirmed review scope and stated total size budget +- `direct_scope`: Apply the approved frontend corrections within the review scope and stated total size budget - `governing_sources`: The reviewed Design Doc, applicable UI Spec, and accepted requirement or ADR paths -- `target_paths`: The implementation and test paths confirmed for the approved code-side routes +- `target_paths`: The implementation and test paths identified for the approved code-side routes - `observable_verification`: The focused UI behavior tests or observable contract checks named by the findings and governing sources pass - `correction_findings`: Complete reviewer finding objects verbatim, with only their orchestrator dispositions added diff --git a/dev-workflows-frontend/skills/requirement-convergence/SKILL.md b/dev-workflows-frontend/skills/requirement-convergence/SKILL.md index bd20961f..b51e0959 100644 --- a/dev-workflows-frontend/skills/requirement-convergence/SKILL.md +++ b/dev-workflows-frontend/skills/requirement-convergence/SKILL.md @@ -9,7 +9,7 @@ description: Separates the outcome a change must produce from the requirements p Requirements arrive bloated, ambiguous, or aimed at the wrong outcome. A capable model reconciles all three into a coherent plan and builds it faithfully — delivering exactly what was asked for when what was asked for was wrong. -This skill converges **what to build**. How to build it, and which documents the change requires, are settled after the what is. +This skill converges **what to build**. How to build it, and which documents the change requires, come after the what. ## Convergence Fields @@ -49,14 +49,14 @@ Render this shape at every requirements confirmation stop, whether or not the he | Section | Contents | |---------|----------| -| **Confirmed scope** | The requirements and exclusions the user has already selected, in the user's wording | +| **User-selected scope** | The requirements and exclusions the user has already selected, in the user's wording | | **Decision evidence** | Each material observed fact with its source, followed by what that fact can change about scope, outcome, or cost | | **User decisions** | One question per convergence field below `ready` (Hearing Protocol Step 1), followed by the scope, outcome, or cost effects of its materially different answers | | **Workflow** | Rough cost band with the unknowns that remain, Structural Scale, and the selected document and workflow route | -Keeping the first three sections separate is what makes the decision informable: merged, the reader cannot tell which line is the user's own settled boundary, which is a repository observation, and which is still open. +Keeping the first three sections separate is what makes the decision informable: merged, the reader cannot tell which line is the user's own selection, which is a repository observation, and which is still open. -Only an explicit user answer moves an item from **User decisions** into **Confirmed scope**. Because Step 2 records the user's own wording, pose each open decision as a question and let the user supply its answer. The orchestrator owns **Workflow** and presents it as a selected route. +Only an explicit user answer moves an item from **User decisions** into **User-selected scope**. Because Step 2 records the user's own wording, pose each open decision as a question and let the user supply its answer. The orchestrator owns **Workflow** and presents it as a selected route. ## Storage Protocol diff --git a/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md index caac3770..38f28531 100644 --- a/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md @@ -27,27 +27,27 @@ Build and judge the `convergence` record in the orchestrator with the requiremen ### Small Evidence Gate -Classify Small when `scopeEvidence.executionRoute.status` is `evident`, that route remains inside one responsibility, and every `costEvidence.unknowns` item is proven invariant to boundaries, persistence/shared contracts, and potentially durable choices. Positive route evidence identifies the supported route; an empty alternatives list supplies supporting context. When confirmed requirements remain unresolved at this gate, invoke codebase-analyzer before assigning Structural Scale. Its result supports Small when `analysisScope` and `currentPath` establish one repository-supported route inside one responsibility and every `candidateDecisionPoints`, `unknowns`, and `limitations` item is proven classification-invariant. Other observed boundaries and outcomes route Medium or Large. Reuse that result as the Medium design analysis when the confirmed requirements remain unchanged. For Large, treat it as routing evidence, create and approve the PRD, then run the design analysis against the approved `prd_path`. ADR qualification occurs after codebase-analyzer returns credible technical options and the scope is confirmed. +Classify Small when `scopeEvidence.executionRoute.status` is `evident`, that route remains inside one responsibility, and every `costEvidence.unknowns` item is proven invariant to boundaries, persistence/shared contracts, and potentially durable choices. Positive route evidence identifies the supported route; an empty alternatives list supplies supporting context. When the requirements remain unresolved at this gate, invoke codebase-analyzer before assigning Structural Scale. Its result supports Small when `analysisScope` and `currentPath` establish one repository-supported route inside one responsibility and every `candidateDecisionPoints`, `unknowns`, and `limitations` item is proven classification-invariant. Other observed boundaries and outcomes route Medium or Large. Reuse that result as the Medium design analysis when the requirements remain unchanged. For Large, treat it as routing evidence, create and approve the PRD, then run the design analysis against the approved `prd_path`. ADR qualification occurs after codebase-analyzer returns credible technical options and the scope has passed the requirements stop. ### Requirement Change Detection During Flow -After an analysis result returns, compare each user-facing or operational responsibility it exposes against the confirmed scope. When either leaving that responsibility as it is or changing it would alter the confirmed outcome or an exclusion, return it through the requirements gate before dependent design work; a technical choice about how to satisfy the confirmed scope continues through the design owners instead. +After an analysis result returns, compare each user-facing or operational responsibility it exposes against the scope in the convergence record. When either leaving that responsibility as it is or changing it would alter the outcome or an exclusion, return it through the requirements gate before dependent design work; a technical choice about how to satisfy that scope continues through the design owners instead. -Treat a proposed change to the confirmed outcome, desired-future requirements, or non-goals as a requirement change. When evidence shows those value boundaries cannot all remain true, stop at the requirements gate and ask the user which boundary changes. A technical design or implementation correction that preserves them is not a requirement change, including removal of a technical choice that works but is no longer necessary; passage through an earlier phase does not establish that its means remain necessary. Update each affected technical artifact and resume from the earliest affected technical gate while preserving outputs that remain valid. +Treat a proposed change to the outcome, desired-future requirements, or non-goals as a requirement change. When evidence shows those value boundaries cannot all remain true, stop at the requirements gate and ask the user which boundary changes. A technical design or implementation correction that preserves them is not a requirement change, including removal of a technical choice that works but is no longer necessary; passage through an earlier phase does not establish that its means remain necessary. Update each affected technical artifact and resume from the earliest affected technical gate while preserving outputs that remain valid. -**Requirement reopening after codebase analysis**: When the first codebase-analyzer result after requirement confirmation shows existing behavior that serves a confirmed requirement's need and falls short only of extra behavior that requirement specifies, whichever field reports it, present it with its evidence and cost effect at one requirements stop before UI Spec, ADR, or Design Doc work, and let the user keep or change the requirement. Requirements are confirmed before any code is read, and every later phase builds and reviews against them without questioning them, so this is the one point where repository evidence can reduce them; judging such evidence as ruled out by the requirement removes the user's only chance to weigh it. Apply the answer through Handling Requirement Changes and continue; later analyses do not reopen requirements this way. +**Requirement reopening after codebase analysis**: When the first codebase-analyzer result after requirement confirmation shows existing behavior that serves a requirement's need and falls short only of extra behavior that requirement specifies, whichever field reports it, present it with its evidence and cost effect at one requirements stop before UI Spec, ADR, or Design Doc work, and let the user keep or change the requirement. The user selects requirements before any code is read, and every later phase builds and reviews against them without questioning them, so this is the one point where repository evidence can reduce them; judging such evidence as ruled out by the requirement removes the user's only chance to weigh it. Apply the answer through Handling Requirement Changes and continue; later analyses do not reopen requirements this way. ## Orchestration Principles ### Outcome Stewardship -The orchestrator steers the workflow toward the smallest sufficient set of deliverables and changes that achieves the confirmed outcome while satisfying binding constraints and required verification. Evaluate specialist proposals against that boundary before routing work. +The orchestrator steers the workflow toward the smallest sufficient set of deliverables and changes that achieves the outcome while satisfying binding constraints and required verification. Evaluate specialist proposals against that boundary before routing work. -Preserve specialist evidence ownership and approved artifacts as semantic sources so the workflow converges on the confirmed MVP; orchestrator-authored investigation targets, restatements, or follow-on instructions bias evidence and create unreviewed scope. +Preserve specialist evidence ownership and approved artifacts as semantic sources so the workflow converges on the MVP; orchestrator-authored investigation targets, restatements, or follow-on instructions bias evidence and create unreviewed scope. ### Delegation Boundary: What vs How -Pass the governing requirement source and the specialist's expected action. Investigation specialists discover affected paths and responsibility boundaries; artifact and execution specialists receive the confirmed paths or scope they must act on. Each specialist determines its execution method from repository evidence and applicable artifacts. +Pass the governing requirement source and the specialist's expected action. Investigation specialists discover affected paths and responsibility boundaries; artifact and execution specialists receive the paths or scope they must act on. Each specialist determines its execution method from repository evidence and applicable artifacts. **Decision precedence for routing**: 1. User instructions (explicit requests or constraints) @@ -56,10 +56,10 @@ Pass the governing requirement source and the specialist's expected action. Inve 4. Specialist judgment **Scope source classification**: -- An explicit restriction in the user instruction or confirmed outcome, desired-future requirements, or non-goals is a hard boundary. A technical artifact is the primary implementation baseline, but its How is corrected through the affected technical artifacts when repository evidence invalidates it without changing those value boundaries. +- An explicit restriction in the user instruction or the outcome, desired-future requirements, or non-goals is a hard boundary. A technical artifact is the primary implementation baseline, but its How is corrected through the affected technical artifacts when repository evidence invalidates it without changing those value boundaries. - Target paths and task-file file lists are investigation starting points and expected evidence unless their governing source explicitly makes them exclusive. -- Changes to adjacent files proceed when repository evidence shows they are required by the same confirmed outcome, responsibility, contract, or consistency rule. -- Unrelated improvements remain outside the active change. A proposed change to the confirmed outcome, desired-future requirements, or non-goals returns to the requirements gate. Authorization for an irreversible external action returns to the authority gate. Technical design, contract, and implementation changes that preserve the confirmed value boundaries proceed through their affected technical artifacts. +- Changes to adjacent files proceed when repository evidence shows they are required by the same outcome, responsibility, contract, or consistency rule. +- Unrelated improvements remain outside the active change. A proposed change to the outcome, desired-future requirements, or non-goals returns to the requirements gate. Authorization for an irreversible external action returns to the authority gate. Technical design, contract, and implementation changes that preserve those value boundaries proceed through their affected technical artifacts. Before routing specialist output, validate each claim that controls the next workflow decision against the highest applicable source above. Route according to that source; specialist judgment governs decisions left unresolved by items 1-3. @@ -67,7 +67,7 @@ Before routing specialist output, validate each claim that controls the next wor Each specialist's agent definition owns its canonical result shape. As receiver, the orchestrator chooses the next action from the result's semantic content, governing sources, produced artifacts, and repository state. Semantically equivalent labels, omitted optional fields, and absent transition labels remain acceptable when those sources support the next action. Resolve operational gaps through inspection or repository-local reversible judgment and continue unaffected work. -Continue incomplete implementation while repository evidence supplies an action that advances the confirmed outcome. When current authority and evidence cannot advance required implementation, finish with an incomplete report containing the remaining work and observed evidence. Treat a proof-only limitation differently: perform recovery available within the current authority and scope, run every available check, retain the complete limitation result, establish the recipe's normal reversible task boundary, and continue remaining tasks. Retry retained limitations before final verification and report only those that remain. Claim only the proof actually observed. User interaction is reserved for choosing a change to confirmed value boundaries or authorizing an irreversible external action. +Continue incomplete implementation while repository evidence supplies an action that advances the outcome. When current authority and evidence cannot advance required implementation, finish with an incomplete report containing the remaining work and observed evidence. Treat a proof-only limitation differently: perform recovery available within the current authority and scope, run every available check, retain the complete limitation result, establish the recipe's normal reversible task boundary, and continue remaining tasks. Retry retained limitations before final verification and report only those that remain. Claim only the proof actually observed. User interaction is reserved for choosing a change to value boundaries or authorizing an irreversible external action. ### Review Resolution @@ -94,19 +94,19 @@ 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 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. +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 user-visible outcome from it or the requirement context alongside major internal responsibility, contract, or refactoring changes, so the user can judge whether to proceed. | Phase | Stop Point | User Action Required | |-------|------------|---------------------| | Requirements | After requirement-analyzer completes | Answer the requirement-convergence hearing, confirm the recorded requirements match their intent, then approve proceeding | | PRD | After document-reviewer completes PRD review | Approve completing the PRD phase and proceeding | -| Requirement reopening | After the first codebase-analyzer result when it shows existing behavior that falls short of a confirmed requirement only by extra behavior that requirement specifies | Keep or change each affected requirement | +| Requirement reopening | After the first codebase-analyzer result when it shows existing behavior that falls short of a requirement only by extra behavior that requirement specifies | Keep or change each affected requirement | | UI Spec | After document-reviewer completes an applicable UI Spec review | Approve completing the UI Spec phase and proceeding | | ADR batch | After document-reviewer reviews the complete qualifying batch | Approve completing the ADR batch phase and proceeding | | Design | After design-sync completes consistency verification | Approve completing the design phase and proceeding | | Work Plan | After work plan review (document-reviewer, doc_type WorkPlan; Medium/Large) completes | Batch approval: authorize implementation within this outcome | -**After applicable implementation authorization**: Confirmed Small requirements or Medium/Large batch approval start autonomous execution, which continues until completion or an escalation condition is reached. +**After applicable implementation authorization**: User confirmation at the Requirements stop for Small, or Medium/Large batch approval, starts autonomous execution, which continues until completion or an escalation condition is reached. ## Scale Determination and Document Requirements @@ -151,15 +151,15 @@ Use create mode for initial documents. For requirement-driven revisions, invoke | Medium | requirement-analyzer → codebase-analyzer → requirement reopening when applicable → conditional external/UI analysis and UI Spec → optional ADR batch/review/approval → Design Doc → code-verifier/Review Resolution → document-reviewer → design-sync → acceptance-test-generator → work-planner → work plan review → task-decomposer | | Small | requirement-analyzer → conditional codebase-analyzer when the Small evidence gate is unresolved → direct task execution (no Work Plan) | -The requirement-convergence and external-resource hearings run in the orchestrator. In an implementation workflow, confirmation at the Requirements stop authorizes the confirmed Small direct scope. Medium/Large implementation begins after Work Plan batch approval. +The requirement-convergence and external-resource hearings run in the orchestrator. In an implementation workflow, confirmation at the Requirements stop authorizes the Small direct scope. Medium/Large implementation begins after Work Plan batch approval. Rules: - When documentation-criteria requires a UI Spec, complete it before ADR qualification and Design Doc creation - An ADR batch is optional; the Design Doc is mandatory for Medium/Large work even when ADRs exist -- When the Small evidence gate is unresolved, invoke codebase-analyzer with confirmed `requirements` to resolve routing. Reuse that result for unchanged Medium scope. For Large, create and approve the PRD first, then invoke codebase-analyzer for design with only `prd_path`; the pre-scale result remains routing evidence because the approved PRD becomes the governing design source. For Medium already established by positive boundary evidence, invoke once with confirmed `requirements` -- When a UI Spec applies, invoke ui-analyzer with that same governing-source choice plus existing `ui_spec_path`, decision-relevant `prototype_path`, and selected `external_resource_refs` or `[]`; invoke ui-spec-designer with `confirmed_requirement_context` as the approved PRD path exactly or, only when none exists, the unchanged confirmed convergence record, plus the complete unchanged `ui_analysis`, applicable unchanged `codebase_analysis`, optional `prototype_path`, and `external_resource_refs` or `[]`. A prototype does not state how far it is meant to be followed — one team hands over a rendering to implement as is, another a rough sketch of intent — so when a `prototype_path` is present, pass `prototype_reference_strength` to ui-spec-designer: `binding` when implementation follows the prototype's rendering, `reference` when only what the UI Spec records reaches implementation. Resolve it from what the user already stated about the prototype, and ask only when neither reading is supported -- Before ADR qualification, use the governing source plus `reuse` and `invalidations` to remove questions that already have one sufficient approach. Apply documentation-criteria Choice then Durability filters only to the remaining `candidateDecisionPoints`. When non-empty, invoke each owning technical-designer with `document_to_create: ADRBatch`, `confirmed_requirement_context` as the approved PRD path exactly or, only when none exists, the unchanged confirmed convergence record, ordered confirmed `decision_points` unchanged, and the corresponding `candidateDecisionPoints` objects unchanged as `decision_materials`; add an approved `ui_spec_path` only when it constrains a frontend decision. Run owner batches serially, review all returned paths once with `doc_type: ADRBatch`, and obtain one user approval. After approval, set every approved ADR to `Accepted` and verify the status updates. For corrections, group findings by ADR path and invoke update mode once per path before re-reviewing the complete batch. An empty result proceeds directly to the Design Doc -- Invoke the Design Doc owner with `document_to_create: DesignDoc`, `confirmed_requirement_context` as the approved PRD path exactly or, only when none exists, the unchanged confirmed convergence record, `structural_scale`, unchanged `codebase_analysis`, optional unchanged `ui_analysis`, and accepted `adr_paths`; frontend/fullstack invocations add their named UI or layer artifact paths and distinct `output_path` destinations when splitting a feature across documents +- When the Small evidence gate is unresolved, invoke codebase-analyzer with the convergence record's `requirements` to resolve routing. Reuse that result for unchanged Medium scope. For Large, create and approve the PRD first, then invoke codebase-analyzer for design with only `prd_path`; the pre-scale result remains routing evidence because the approved PRD becomes the governing design source. For Medium already established by positive boundary evidence, invoke once with the convergence record's `requirements` +- When a UI Spec applies, invoke ui-analyzer with that same governing-source choice plus existing `ui_spec_path`, decision-relevant `prototype_path`, and selected `external_resource_refs` or `[]`; invoke ui-spec-designer with `requirement_context` as the approved PRD path exactly or, only when none exists, the unchanged convergence record, plus the complete unchanged `ui_analysis`, applicable unchanged `codebase_analysis`, optional `prototype_path`, and `external_resource_refs` or `[]`. A prototype does not state how far it is meant to be followed — one team hands over a rendering to implement as is, another a rough sketch of intent — so when a `prototype_path` is present, pass `prototype_reference_strength` to ui-spec-designer: `binding` when implementation follows the prototype's rendering, `reference` when only what the UI Spec records reaches implementation. Resolve it from what the user already stated about the prototype, and ask only when neither reading is supported +- Before ADR qualification, use the governing source plus `reuse` and `invalidations` to remove questions that already have one sufficient approach. Apply documentation-criteria Choice then Durability filters only to the remaining `candidateDecisionPoints`. When non-empty, invoke each owning technical-designer with `document_to_create: ADRBatch`, `requirement_context` as the approved PRD path exactly or, only when none exists, the unchanged convergence record, the ordered `decision_points` that pass both filters unchanged, and the corresponding `candidateDecisionPoints` objects unchanged as `decision_materials`; add an approved `ui_spec_path` only when it constrains a frontend decision. Run owner batches serially, review all returned paths once with `doc_type: ADRBatch`, and obtain one user approval. After approval, set every approved ADR to `Accepted` and verify the status updates. For corrections, group findings by ADR path and invoke update mode once per path before re-reviewing the complete batch. An empty result proceeds directly to the Design Doc +- Invoke the Design Doc owner with `document_to_create: DesignDoc`, `requirement_context` as the approved PRD path exactly or, only when none exists, the unchanged convergence record, `structural_scale`, unchanged `codebase_analysis`, optional unchanged `ui_analysis`, and accepted `adr_paths`; frontend/fullstack invocations add their named UI or layer artifact paths and distinct `output_path` destinations when splitting a feature across documents - Resolve code-verifier discrepancies through Review Resolution before invoking document-reviewer; pass the exact HC-04 inputs rather than a narrative evidence bundle - An applied `unverified` discrepancy returns through a fresh owning technical-designer update invocation. Capability probing is reserved for the designer's review-triggered gate, with that fresh designer as the sole correction specialist - Fullstack layer sequencing is defined only in `references/monorepo-flow.md` @@ -174,7 +174,7 @@ Start the applicable Structural Scale flow at the user-requested phase. Before r Verify commit capability before autonomous mode. Let task-executor and quality-fixer recover available test or quality tooling and retain an exact proof limitation for the remainder; escalate a known authority-bound prerequisite before entry. -Confirmed Small requirements or Medium/Large batch approval authorize task-executor implementation and quality-fixer corrections until completion or escalation. +User confirmation at the Requirements stop for Small, or Medium/Large batch approval, authorizes task-executor implementation and quality-fixer corrections until completion or escalation. ### Autonomous Execution Summary For Medium/Large, after batch approval, including an existing-plan build instruction, autonomously execute the following processes through completion or an escalation condition: @@ -215,7 +215,7 @@ When a quality-fixer retry changes behavior outside the received findings, compa | Trigger | Action | |---|---| -| Evidence shows the confirmed outcome, desired-future requirements, and non-goals cannot all remain true without a user choice | Apply Requirement Change Detection and ask which value boundary changes. | +| Evidence shows the outcome, desired-future requirements, and non-goals cannot all remain true without a user choice | Apply Requirement Change Detection and ask which value boundary changes. | | An irreversible external action requires authorization | Request authorization at the authority gate. | | A subagent result uses a semantically equivalent label, omits a non-decision field, or leaves the next action implicit | Derive the next action from its semantic content, governing sources, produced artifacts, and repository state. | | Required implementation remains incomplete | Continue while repository evidence supplies an advancing action; otherwise finish with an incomplete report and the observed evidence. | @@ -228,9 +228,9 @@ When a quality-fixer retry changes behavior outside the received findings, compa #### Commit Boundary Check Immediately before a workflow commit: -1. Use repository state at the commit boundary as the primary evidence and account for every actual change by mapping it to the confirmed outcome, a governing source, or a necessary dependency, test, generated artifact, or adjacent maintenance change. `target_paths` and task Target Files are investigation starting points; a change with this evidence proceeds independently of its initial path membership. -2. Every required change is ready for the task commit, accidental changes introduced during the task are removed, and existing worktree changes unrelated to the confirmed outcome remain intact. -3. Commit the resulting change set. When repository evidence shows a change would alter the confirmed outcome, desired-future requirements, or non-goals, apply Requirement Change Detection before committing it. +1. Use repository state at the commit boundary as the primary evidence and account for every actual change by mapping it to the outcome, a governing source, or a necessary dependency, test, generated artifact, or adjacent maintenance change. `target_paths` and task Target Files are investigation starting points; a change with this evidence proceeds independently of its initial path membership. +2. Every required change is ready for the task commit, accidental changes introduced during the task are removed, and existing worktree changes unrelated to the outcome remain intact. +3. Commit the resulting change set. When repository evidence shows a change would alter the outcome, desired-future requirements, or non-goals, apply Requirement Change Detection before committing it. For a `verification_incomplete` commit, append one trailer pair per retained limitation: @@ -242,7 +242,7 @@ Verification-Affected: Derive the values from the quality-fixer result. Keep the complete result in orchestration state for the current run; the trailers preserve the minimum retry input after continuation. **Per-task cycle**: -1. **Execute**: record the current HEAD as `diffBase`, then invoke task-executor with `task_file: [path]` when one exists; for Small, invoke it with `direct_scope` as the confirmed outcome and exclusions, `governing_sources`, `target_paths`, and `observable_verification` +1. **Execute**: record the current HEAD as `diffBase`, then invoke task-executor with `task_file: [path]` when one exists; for Small, invoke it with `direct_scope` as the convergence record's outcome and exclusions, `governing_sources`, `target_paths`, and `observable_verification` 2. **Branch on executor result**: - `status: escalation_needed` or `blocked` → Apply Specialist Result Acceptance - `requiresTestReview` is `true` → Identify the changed integration/E2E test files in the current changes and invoke integration-test-reviewer with them as `changedTestFiles`, plus `diffBase`, optional `taskFile`, prompt-only claims, and `mutationEvidence` @@ -268,12 +268,12 @@ Before post-implementation verifiers, collect retained verification limitations ### HC-01b: convergence record → document owner - Pass the orchestrator-judged `convergence` record to whichever agent owns the persisting document. -- **prd-creator** (when a PRD is created or updated): persists `outcome` to `Success Criteria` and user-authored `nonGoals` to `Future / Out of Scope`; the PRD contains confirmed requirements and boundaries while evaluation requests, speculative ideas, and unselected mechanisms remain only in pre-confirmation convergence context +- **prd-creator** (when a PRD is created or updated): persists `outcome` to `Success Criteria` and user-authored `nonGoals` to `Future / Out of Scope`; the PRD contains the user-selected requirements and boundaries while evaluation requests, speculative ideas, and unselected mechanisms remain only in active convergence context - **technical-designer / technical-designer-frontend**: persists the same to the Design Doc's `Requirement Convergence` when no PRD exists, and always records the fields left `weak-but-explicit` there - Pass the record unchanged; a field's readiness label travels with it ### HC-02: codebase-analyzer → technical-designer -- For an ADR batch, pass the confirmed `decision_points` unchanged and copy their corresponding `decisionMaterials.candidateDecisionPoints` objects unchanged as `decision_materials`. +- For an ADR batch, pass the `decision_points` that pass both filters unchanged and copy their corresponding `decisionMaterials.candidateDecisionPoints` objects unchanged as `decision_materials`. - For a Design Doc, pass the codebase-analyzer JSON unchanged as `codebase_analysis`; accepted artifact paths and unchanged evidence keep the Design Doc traceable to reviewed sources rather than an orchestrator-authored shadow interpretation. Use these fields as follows: - Required downstream uses: - `focusAreas` → canonical disposition-target list for the Fact Disposition Table @@ -293,7 +293,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 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. +- 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 `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. ### HC-05: code-verifier → next-layer technical-designer (fullstack only) @@ -307,7 +307,7 @@ Pass the Design Doc path. Work-planner maps governing sections and ACs to implem ### HC-06: acceptance-test-generator → work-planner -- Invoke acceptance-test-generator with `design_docs` as the applicable Design Doc path list, optional `ui_spec`, and the same `confirmed_requirement_context` used for design. +- Invoke acceptance-test-generator with `design_docs` as the applicable Design Doc path list, optional `ui_spec`, and the same `requirement_context` used for design. - Resolve a blocked generator result through Specialist Result Acceptance before consuming `generatedFiles`. - Verify each non-null `generatedFiles.` path exists. When a lane is `null`, check the generator’s explanation against the accepted criteria, applicable UI Spec, actual existing test assertions and generated skeletons. Confirm that the explanation accounts for the required observable boundary. A proposed test is not existing coverage; return any missing integration/E2E obligation to the generator. - Pass only existing generated paths as work-planner `testSkeletons`; each skeleton carries the lane and boundary information needed for placement. diff --git a/dev-workflows-frontend/skills/subagents-orchestration-guide/references/monorepo-flow.md b/dev-workflows-frontend/skills/subagents-orchestration-guide/references/monorepo-flow.md index 84396532..52bbc86e 100644 --- a/dev-workflows-frontend/skills/subagents-orchestration-guide/references/monorepo-flow.md +++ b/dev-workflows-frontend/skills/subagents-orchestration-guide/references/monorepo-flow.md @@ -4,7 +4,7 @@ This reference defines the orchestration flow for one feature spanning backend a ## When This Flow Applies -- The confirmed outcome requires backend and frontend implementation. +- The outcome requires backend and frontend implementation. - Separate Design Docs are needed for layer ownership and cross-layer verification. - The orchestrator is invoked through a fullstack implementation or build recipe. @@ -14,7 +14,7 @@ This reference defines the orchestration flow for one feature spanning backend a | Step | Owner | Purpose | Output | |------|-------|---------|--------| -| 1 | requirement-analyzer + orchestrator | Scope/cost evidence followed by orchestrator convergence and Structural Scale judgment, then the requirements hearing **[Stop]** | Confirmed requirements + scale | +| 1 | requirement-analyzer + orchestrator | Scope/cost evidence followed by orchestrator convergence and Structural Scale judgment, then the requirements hearing **[Stop]** | Convergence record + scale | | 2 | prd-creator | PRD for the complete feature | PRD | | 3 | document-reviewer | PRD review **[Stop]** | Approval | | 4 | codebase-analyzer + orchestrator | Repository decision material for the complete feature, including layer boundaries and cross-layer contracts, then requirement reopening when applicable **[Stop when applicable]** | Analysis JSON | @@ -34,13 +34,13 @@ This reference defines the orchestration flow for one feature spanning backend a ### Medium Structural Scale Fullstack -For Medium scale, execute Large steps 4-17 and carry the confirmed convergence record in place of a PRD; retain the conditional stops at steps 4, 7, and 9 and the approval stops at steps 14 and 17. +For Medium scale, execute Large steps 4-17 and carry the convergence record in place of a PRD; retain the conditional stops at steps 4, 7, and 9 and the approval stops at steps 14 and 17. ## Analysis and Evidence Rules At each Agent invocation in this flow, build the prompt as a mechanical extraction: copy the named source values into the exact fields, apply only the declared serialization, then invoke immediately. -Invoke codebase-analyzer once for the complete confirmed feature. It discovers backend/frontend responsibility boundaries and their cross-layer contracts; independent discovery keeps convergence grounded in repository evidence rather than the orchestrator's unverified implementation hypothesis. +Invoke codebase-analyzer once for the complete feature. It discovers backend/frontend responsibility boundaries and their cross-layer contracts; independent discovery keeps convergence grounded in repository evidence rather than the orchestrator's unverified implementation hypothesis. Apply the documentation-criteria UI Spec creation condition. Invoke ui-analyzer only when a UI Spec applies. External-resource and prototype inputs are then conditional: load external-resource-context when external evidence can change the current UI or verification decision, and ask for a prototype only when it resolves an approved UI decision or target ambiguity. @@ -50,7 +50,7 @@ Use these prompt shapes: For either analyzer, pass exactly one governing source: prd_path: [approved PRD path] or -requirements: [confirmed requirements verbatim] +requirements: [convergence record requirements verbatim] For UI analysis only, add an existing UI Spec, a decision-relevant prototype, and selected external references: ui_spec_path: [existing UI Spec path] @@ -58,7 +58,7 @@ prototype_path: [decision-relevant path] external_resource_refs: [selected references or []] UI Spec: -confirmed_requirement_context: [approved PRD path exactly; otherwise unchanged convergence record] +requirement_context: [approved PRD path exactly; otherwise unchanged convergence record] ui_analysis: [UI analyzer JSON] codebase_analysis: [applicable frontend codebase evidence] prototype_path: [decision-relevant path or absent] @@ -72,7 +72,7 @@ After scope and any applicable UI Spec approval, resolve candidate decision poin - Route layer-owned decision points to the matching technical designer. - Route cross-layer points to technical-designer. -- Invoke each owner with `document_to_create: ADRBatch`, `confirmed_requirement_context`, its ordered confirmed `decision_points` unchanged, and the corresponding codebase-analysis `candidateDecisionPoints` objects unchanged as `decision_materials`; include an approved `ui_spec_path` only when it constrains a frontend decision. +- Invoke each owner with `document_to_create: ADRBatch`, `requirement_context`, its ordered `decision_points` that pass both filters unchanged, and the corresponding codebase-analysis `candidateDecisionPoints` objects unchanged as `decision_materials`; include an approved `ui_spec_path` only when it constrains a frontend decision. - Invoke technical-designer batches serially: cross-layer/backend first, frontend second. Each owner allocates numbers only after the preceding batch exists. - Collect every returned ADR path. - Invoke document-reviewer once with `doc_type: ADRBatch` and the complete `targets` array. @@ -89,8 +89,8 @@ Create each complete layer design from reviewed artifacts and unchanged evidence ```text document_to_create: DesignDoc output_path: docs/design/[feature-name]-backend-design.md -confirmed_requirement_context: [approved PRD path exactly; otherwise unchanged convergence record] -structural_scale: [confirmed scale] +requirement_context: [approved PRD path exactly; otherwise unchanged convergence record] +structural_scale: [orchestrator-selected scale] adr_paths: [accepted paths or []] codebase_analysis: [complete analysis JSON unchanged] ``` @@ -100,8 +100,8 @@ codebase_analysis: [complete analysis JSON unchanged] ```text document_to_create: DesignDoc output_path: docs/design/[feature-name]-frontend-design.md -confirmed_requirement_context: [approved PRD path exactly; otherwise unchanged convergence record] -structural_scale: [confirmed scale] +requirement_context: [approved PRD path exactly; otherwise unchanged convergence record] +structural_scale: [orchestrator-selected scale] adr_paths: [accepted paths or []] ui_spec_path: [approved UI Spec; omit when absent] backend_design_doc: [path] @@ -113,13 +113,13 @@ Apply `code:` and `ui:` prefixes to respective Fact Disposition IDs. The fronten ## Verification Resolution -Keep verifier observations unchanged so corrections remain traceable to observed evidence rather than orchestrator-authored design instructions. Invoke code-verifier once per Design Doc with `doc_type: design-doc`; apply Review Resolution independently, forward each `apply` discrepancy verbatim with only its disposition, and rerun the affected verifier with its previous complete result, dispositions, and correction diff or paths as `prior_feedback`. Build one `verification_evidence` object per Design Doc from the latest result. Invoke document-reviewer with `review_context: creation`, `verification_evidence`, the same unchanged `codebase_analysis` and optional unchanged `ui_analysis`, original requirements as `requirements_verbatim`, and `confirmed_requirement_context` in the exact form fixed by the orchestration guide. +Keep verifier observations unchanged so corrections remain traceable to observed evidence rather than orchestrator-authored design instructions. Invoke code-verifier once per Design Doc with `doc_type: design-doc`; apply Review Resolution independently, forward each `apply` discrepancy verbatim with only its disposition, and rerun the affected verifier with its previous complete result, dispositions, and correction diff or paths as `prior_feedback`. Build one `verification_evidence` object per Design Doc from the latest result. Invoke document-reviewer with `review_context: creation`, `verification_evidence`, the same unchanged `codebase_analysis` and optional unchanged `ui_analysis`, original requirements as `requirements_verbatim`, and `requirement_context` in the exact form fixed by the orchestration guide. After both document reviews permit approval, invoke design-sync with `source_design` as the frontend Design Doc path because it consumes backend integration contracts. Apply Review Resolution to actionable conflicts before the design approval stop. ## Test Skeleton and Work Planning -Pass both Design Doc paths as `design_docs`, the applicable `ui_spec`, and the same `confirmed_requirement_context` used for design to acceptance-test-generator. Follow parent HC-06 for generated-path and empty-lane coverage checks before planning. Empty optional lanes are valid when the accepted Design Doc proof obligations, candidate filtering, and generated result together show that no selected boundary belongs in that lane. +Pass both Design Doc paths as `design_docs`, the applicable `ui_spec`, and the same `requirement_context` used for design to acceptance-test-generator. Follow parent HC-06 for generated-path and empty-lane coverage checks before planning. Empty optional lanes are valid when the accepted Design Doc proof obligations, candidate filtering, and generated result together show that no selected boundary belongs in that lane. Pass both Design Docs, the applicable UI Spec, applicable PRD, and generated skeleton paths to work-planner. Compose phases around shared backend/frontend verification points. The generated skeleton file is consumed by the earliest task where its declared boundary becomes executable. 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 09f6bae1..512b2c26 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 @@ -1,6 +1,6 @@ # Review Resolution -Use this protocol when a deliverable reviewer or verifier returns findings that can route correction or progression. Correct evidenced defects while preserving confirmed requirements, exclusions, and compatibility obligations, using existing responsibilities. Accepted design decisions are the currently selected means: a correction may remove or narrow one while those boundaries remain true. Verification output used as evidence by a downstream specialist remains part of that specialist handoff. +Use this protocol when a deliverable reviewer or verifier returns findings that can route correction or progression. Correct evidenced defects while preserving the requirements, exclusions, and compatibility obligations, using existing responsibilities. Accepted design decisions are the currently selected means: a correction may remove or narrow one while those boundaries remain true. Verification output used as evidence by a downstream specialist remains part of that specialist handoff. Preserve reviewer/verifier evidence ownership so each gate converges on the governing sources; orchestrator reinterpretation would create unreviewed requirements and make approval or reconciliation non-terminal. @@ -23,20 +23,20 @@ Use the result producer's declared verification mode: ## 1. Assess Every Finding -Before assigning a disposition, inspect the relevant parts of the current deliverable, cited repository evidence, and governing sources. Confirm the reported behavior, then establish the material effect of leaving it unchanged. A material effect changes the confirmed outcome, a binding constraint, downstream behavior, decisions, or required verification, or is an evidenced lifecycle cost whose frequency or magnitude is observable. For a discretionary response, compare that effect with the full cost of implementing, verifying, and retaining the response, including review attention. +Before assigning a disposition, inspect the relevant parts of the current deliverable, cited repository evidence, and governing sources. Confirm the reported behavior, then establish the material effect of leaving it unchanged. A material effect changes the outcome, a binding constraint, downstream behavior, decisions, or required verification, or is an evidenced lifecycle cost whose frequency or magnitude is observable. For a discretionary response, compare that effect with the full cost of implementing, verifying, and retaining the response, including review attention. Order the candidate responses before recording a disposition: no change, then removal or narrowing, then reuse of existing behavior, then a repair that retains or adds a mechanism. A retaining or additive response names the required result the earlier candidates cannot deliver. This is a selection condition, not an obligation to enumerate alternatives for every finding. -When a proposed correction remains within the agreed boundary above, select it from current evidence without expanding scope. When evidence shows the confirmed outcome cannot be achieved within existing responsibilities, leave Review Resolution and apply the parent workflow's existing design or requirement gate before changing them. When the confirmed outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which value boundary changes, apply the parent workflow's Requirement Change Detection. When correction requires authorization for an irreversible external action, apply the parent workflow's authority gate. These workflow exits are not finding dispositions; an optional expansion receives `decline`. +When a proposed correction remains within the agreed boundary above, select it from current evidence without expanding scope. When evidence shows the outcome cannot be achieved within existing responsibilities, leave Review Resolution and apply the parent workflow's existing design or requirement gate before changing them. When the outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which value boundary changes, apply the parent workflow's Requirement Change Detection. When correction requires authorization for an irreversible external action, apply the parent workflow's authority gate. These workflow exits are not finding dispositions; an optional expansion receives `decline`. The orchestrator records one disposition for every actionable finding: | Disposition | Use when | |---|---| -| `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. | +| `apply` | Leaving the current deliverable unchanged would prevent the 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 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. +A confirmed exploitable gap in a relied-upon trust boundary, implementation divergence, or governing-source contradiction receives `apply` when correction preserves the 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: @@ -53,7 +53,7 @@ Only findings with `apply`, and maintained `apply` findings under section 3, ent Select the existing correction owner from the accepted state each finding requires: -- use the owning document author when the implementation already satisfies the confirmed value boundaries and the technical artifact must change; +- use the owning document author when the implementation already satisfies the value boundaries and the technical artifact must change; - use the executor when the implementation must change to reach the accepted state. For a mixed set, complete author-owned corrections first and re-evaluate executor-owned findings against the corrected governing artifact. Pass complete `apply` finding objects verbatim with their dispositions to the selected owner. Invoke a document author as a fresh update call with the original target and those findings; the artifact supplies unaffected context. When an executor is used, preserve its original `task_file` or four direct-scope fields and add the findings as `correction_findings`; correction remains inside the original execution scope. diff --git a/dev-workflows-fullstack/agents/acceptance-test-generator.md b/dev-workflows-fullstack/agents/acceptance-test-generator.md index a8ffc948..616b6920 100644 --- a/dev-workflows-fullstack/agents/acceptance-test-generator.md +++ b/dev-workflows-fullstack/agents/acceptance-test-generator.md @@ -15,7 +15,7 @@ You generate comment-only integration/E2E test skeletons for required proof that - **design_docs**: One or more readable Design Doc paths containing acceptance criteria and Test Boundaries. - **ui_spec**: Optional UI Spec whose interactions constrain those criteria. -- **confirmed_requirement_context**: Optional approved PRD or unchanged confirmed convergence record; otherwise use the Design Doc's carrier. +- **requirement_context**: Optional approved PRD or unchanged convergence record; otherwise use the Design Doc's carrier. Accept equivalent labels and concise prose with the same meaning. Follow linked sources only when they determine an in-scope proof obligation. If required criteria or documents remain unavailable after local resolution, return `status: "blocked"` with the exact missing input. diff --git a/dev-workflows-fullstack/agents/code-reviewer.md b/dev-workflows-fullstack/agents/code-reviewer.md index 91dd0082..e8d55424 100644 --- a/dev-workflows-fullstack/agents/code-reviewer.md +++ b/dev-workflows-fullstack/agents/code-reviewer.md @@ -95,8 +95,8 @@ Correction re-review: - `pass`: no required-correction finding or blocked judgment remains; - `needs-improvement`: findings are repairable within the approved scope; -- `needs-redesign`: correction requires updating the governing technical design or responsibility boundary while preserving the confirmed outcome, desired-future requirements, and non-goals; -- `blocked`: required inputs or evidence are unavailable, or evidence shows the confirmed outcome, desired-future requirements, and non-goals cannot all remain true. +- `needs-redesign`: correction requires updating the governing technical design or responsibility boundary while preserving the outcome, desired-future requirements, and non-goals; +- `blocked`: required inputs or evidence are unavailable, or evidence shows the outcome, desired-future requirements, and non-goals cannot all remain true. ## Completion Check diff --git a/dev-workflows-fullstack/agents/code-verifier.md b/dev-workflows-fullstack/agents/code-verifier.md index a114b2b7..2c717c5e 100644 --- a/dev-workflows-fullstack/agents/code-verifier.md +++ b/dev-workflows-fullstack/agents/code-verifier.md @@ -10,7 +10,7 @@ skills: You perform read-only verification of an authoritative document against repository evidence. -Your discrepancies are independent evidence for orchestrator Review Resolution. Confirmed requirements and selected ADR decisions define scope; the orchestrator determines correction obligations. +Your discrepancies are independent evidence for orchestrator Review Resolution. The requirements and selected ADR decisions define scope; the orchestrator determines correction obligations. ## Inputs diff --git a/dev-workflows-fullstack/agents/design-sync.md b/dev-workflows-fullstack/agents/design-sync.md index ceaad0c5..7ebe625c 100644 --- a/dev-workflows-fullstack/agents/design-sync.md +++ b/dev-workflows-fullstack/agents/design-sync.md @@ -115,7 +115,7 @@ Severity Assessment: - Term → medium (confusion risk) ``` -Recommend only a correction within confirmed requirements, accepted design decisions, and existing responsibilities. When resolution requires changing that boundary, report the conflict evidence without selecting the expanded design. +Recommend only a correction within the requirements, accepted design decisions, and existing responsibilities. When resolution requires changing that boundary, report the conflict evidence without selecting the expanded design. ## Output Format diff --git a/dev-workflows-fullstack/agents/document-reviewer.md b/dev-workflows-fullstack/agents/document-reviewer.md index 28519e7c..69b5b3ba 100644 --- a/dev-workflows-fullstack/agents/document-reviewer.md +++ b/dev-workflows-fullstack/agents/document-reviewer.md @@ -22,7 +22,7 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow - **targets**: Complete ADR path array for `ADRBatch` - **review_context**: `creation`, `update`, or `reverse-engineer` when supplied - **requirements_verbatim**: Original user requirements when they govern the target -- **confirmed_requirement_context**: Exact approved PRD path, or the unchanged orchestrator-confirmed convergence record only when no approved PRD exists +- **requirement_context**: Exact approved PRD path, or the orchestrator's unchanged convergence record only when no approved PRD exists - **codebase_analysis**: Compact codebase analysis JSON used by the author, when supplied - **ui_analysis**: UI analysis JSON used by the author, when supplied - **verification_evidence**: Latest code verification evidence when verification ran; Design Doc creation receives the resolved form produced by Review Resolution @@ -30,18 +30,18 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow Verify each target exists. Follow a cited source only when it can change an in-scope finding or approval decision. -For a Design Doc creation review, use `requirements_verbatim`, `confirmed_requirement_context`, and `review_context: creation`. For an as-is document use `review_context: reverse-engineer`. Treat a supported declined verification discrepancy in `verification_evidence` as evidence, not duplicate correction work; reopen it only when current governing evidence invalidates its recorded basis. Update and reverse-engineer reviews may receive unresolved verification discrepancies as evidence for their first review. +For a Design Doc creation review, use `requirements_verbatim`, `requirement_context`, and `review_context: creation`. For an as-is document use `review_context: reverse-engineer`. Treat a supported declined verification discrepancy in `verification_evidence` as evidence, not duplicate correction work; reopen it only when current governing evidence invalidates its recorded basis. Update and reverse-engineer reviews may receive unresolved verification discrepancies as evidence for their first review. ## Review Order and Boundary Review in this order: -1. Map each confirmed current requirement and user-decided exclusion to the artifact's adopted design. Check the central outcome before secondary technical detail. +1. Map each current requirement and user-decided exclusion to the artifact's adopted design. Check the central outcome before secondary technical detail. 2. Apply accepted ADRs and approved upstream documents. 3. Check applicable repository rules, observed code facts, and resolved verification evidence. 4. Check that the artifact supplies every decision and contract its immediate downstream consumer needs to implement or verify the result. -Confirmed requirements, accepted decisions, repository rules, and observed facts govern implementation. Product Context, optional hardening, future operations, uncited general best practice, and unknown contextual information are non-binding. +Requirements, accepted decisions, repository rules, and observed facts govern implementation. Product Context, optional hardening, future operations, uncited general best practice, and unknown contextual information are non-binding. Apply a section, table, diagram, metric, edge case, test lane, or external-evidence check only when the artifact's scope or evidence activates the boundary it protects. Structural presence alone is not quality. Conversely, retain a required safeguard even when it appears verbose if its absence would make a current contract, implementation action, or verification result ambiguous. @@ -51,17 +51,17 @@ Verify current external facts from authoritative sources only when an ADR select ### PRD -- A future-state PRD contains one confirmed outcome, buildable current requirements, representative acceptance criteria, and user-decided exclusions or confirmed none. +- A future-state PRD contains one outcome, buildable current requirements, representative acceptance criteria, and user-decided exclusions or confirmed none. - Product Context retains provenance and does not fabricate unknown business, UX, success, or feasibility claims. - A contextual unknown permits approval unless the user must resolve it to define the outcome, requirement, exclusion, or acceptance criterion. ### ADR Batch - For ADR and Design Doc checks, total complexity covers every activated user decision, setting, mode, concept, output, persistent state, and implementation path, together with its UX, runtime, implementation, testing, documentation, and maintenance cost; compare only dimensions that differ between valid options. -- Each ADR owns one technical question inside confirmed scope. +- Each ADR owns one technical question inside the scope of the requirements. - Current requirements and repository evidence support at least two credible, materially distinct options, and the choice has durable impact. -- Options compare confirmed product value, repository fit, total complexity, maintainability, material trade-offs, and reversibility using available evidence. -- The selected option is necessary and sufficient for the approved outcome and has the lowest justified total complexity among valid options. A more expensive option has confirmed product value that changes the selection. +- Options compare product value from the requirements, repository fit, total complexity, maintainability, material trade-offs, and reversibility using available evidence. +- The selected option is necessary and sufficient for the approved outcome and has the lowest justified total complexity among valid options. A more expensive option has product value from the requirements that changes the selection. - Relative evidence is sufficient. A numeric estimate or fixed option count applies only when governing evidence requires it. - The selected decision alone constrains the downstream Design Doc for that technical question. Implementation procedure, end-to-end design, release strategy, and work planning remain outside the ADR. - For a batch, decision ownership does not overlap and the selected combination has justified cumulative total complexity. @@ -69,12 +69,12 @@ Verify current external facts from authoritative sources only when an ADR select ### UI Spec - Required screens/components, transitions, state/display behavior, interactions, visual outcomes, and acceptance-criteria traceability are implementable. -- Loading, empty, error, responsive, accessibility, token, and browser behavior is present when supported by confirmed requirements, approved UI direction, preserved behavior, or repository/design-system rules. +- Loading, empty, error, responsive, accessibility, token, and browser behavior is present when supported by the requirements, approved UI direction, preserved behavior, or repository/design-system rules. - Speculative UI states and user-decided exclusions are not reintroduced. ### Design Doc -- Each confirmed requirement maps to an adopted end-to-end flow or concrete verification evidence; exclusions are not implemented indirectly. +- Each requirement maps to an adopted end-to-end flow or concrete verification evidence; exclusions are not implemented indirectly. - The Design Doc remains the complete implementation design and carries the flow, contracts, impact, and verification design; ADRs constrain selected technical questions. - Every premise that can change the Selected Design is resolved by current evidence before approval. Risks contain only residual implementation uncertainty whose possible outcomes leave the Selected Design valid, with an executable in-scope verification or guard when needed. - Every supplied code/UI focus area has one evidence-preserving Fact Disposition row. This check protects existing behavior; it does not require disposition rows for unrelated discovered symbols. @@ -103,7 +103,7 @@ Create an issue only when the artifact otherwise: - describes an incorrect approved outcome or contract; - leaves approved implementation non-executable; - 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. +- commits downstream implementation to added design surface whose total complexity lacks current evidence and whose removal still satisfies the 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, extra Product Context, duplicate proof, stylistic completeness, and template-only omissions from the review result. @@ -115,7 +115,7 @@ For `prior_feedback`, the received items and the boundaries their corrections ch - `pass`: `issues` is empty and no maintained prior finding remains. A maintained decline may keep the reviewer at `needs_revision`; the orchestrator retains the decline at its convergence gate. - `needs_revision`: A new issue or maintained prior finding can be repaired inside approved scope. -- `rejected`: Confirmed outcome, desired-future requirements, and non-goals cannot all remain true and approval requires choosing which value changes. +- `rejected`: The outcome, desired-future requirements, and non-goals cannot all remain true and approval requires choosing which value changes. Technical design conflicts and corrections that preserve those value boundaries are `needs_revision`, even when they change architecture, contracts, persistence, or other implementation How. diff --git a/dev-workflows-fullstack/agents/prd-creator.md b/dev-workflows-fullstack/agents/prd-creator.md index c3cdd488..fc1afa18 100644 --- a/dev-workflows-fullstack/agents/prd-creator.md +++ b/dev-workflows-fullstack/agents/prd-creator.md @@ -38,7 +38,7 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow - `reverse-engineer`: Create PRD from existing implementation (Reverse PRD) - **Requirements Analysis Results**: Requirements analysis results -- **Convergence Result**: The `convergence` object (HC-01b) → `outcome` anchors Success Criteria; user-authored `nonGoals` populate `Future / Out of Scope`. The PRD contains confirmed requirements and boundaries; evaluation requests, speculative ideas, and unselected mechanisms remain only in pre-confirmation convergence context +- **Convergence Result**: The `convergence` object (HC-01b) → `outcome` anchors Success Criteria; user-authored `nonGoals` populate `Future / Out of Scope`. The PRD contains the user-selected requirements and boundaries; evaluation requests, speculative ideas, and unselected mechanisms remain only in active convergence context - **Existing PRD**: Path to existing PRD file for reference (if any) - **Project Context**: - Target users (sales, marketing, HR, etc.) @@ -118,7 +118,7 @@ PRDs focus solely on "what to build." Implementation phases and task decompositi 4. Limit Future or Out of Scope to user-authored non-goals and current exclusions needed to make the MVP boundary executable ### 3. Measurable Success Metrics -- Define observable success for the confirmed outcome. Include numerical targets and measurement methods when supported by a governing requirement or existing evidence. +- Define observable success for the outcome. Include numerical targets and measurement methods when supported by a governing requirement or existing evidence. - In reverse-engineer mode, preserve observed measures and distinguish unknown business goals; derive no new target from a template. ### 4. Completeness Check @@ -150,7 +150,7 @@ Use a user journey diagram, scope boundary diagram, or both only when prose does ## Update Mode Operation - **Execution**: User's modification instruction = approval. Execute modifications immediately -- **Review corrections**: Resolve supplied defects within the confirmed product outcome and scope. A reviewer suggestion does not become a new requirement; return the conflicting evidence when the correction would require one. +- **Review corrections**: Resolve supplied defects within the product outcome and scope. A reviewer suggestion does not become a new requirement; return the conflicting evidence when the correction would require one. - **Processing**: Increment version number and record change history ## Reverse-Engineer Mode (Reverse PRD) diff --git a/dev-workflows-fullstack/agents/quality-fixer-frontend.md b/dev-workflows-fullstack/agents/quality-fixer-frontend.md index 6703a75d..5b323c06 100644 --- a/dev-workflows-fullstack/agents/quality-fixer-frontend.md +++ b/dev-workflows-fullstack/agents/quality-fixer-frontend.md @@ -16,14 +16,14 @@ Executes applicable quality checks, fixes in-scope failures, and reports exact p ## Main Responsibilities 1. **Self-contained Quality Assurance and Fix Execution** - - Execute applicable frontend project quality checks; fix failures tied to the current change or confirmed task scope, and report other failures with their owning boundary as `verification_incomplete` + - Execute applicable frontend project quality checks; fix failures tied to the current change or the task scope, and report other failures with their owning boundary as `verification_incomplete` - Analyze error root causes and execute both auto-fixes and manual fixes autonomously - Continue until each in-scope failure is fixed, required proof remains unavailable, or one authoritative `blocked` condition is evidenced; return `pass` only when every applicable check passes ## Input Parameters - **task_file** (optional): Path to the task file being verified. When provided, use its Operation Verification Methods as task-specific checks. -- **direct_scope** (for workflow execution without a task file): Confirmed outcome and exclusions, copied unchanged from the execution scope +- **direct_scope** (for workflow execution without a task file): Outcome and exclusions, copied unchanged from the execution scope - **governing_sources** (for direct scope): Authoritative source paths and unchanged governing values used for execution - **observable_verification** (for direct scope): The same behavior, artifact state, or command result required to prove execution complete - **correction_findings** (optional): Complete applied finding objects supplied to the executor, copied unchanged as the correction scope and acceptance evidence @@ -84,14 +84,14 @@ Apply fixes per typescript-rules and testing-principles skills. - Verified failure in a separate responsibility → Return `verification_incomplete` with evidence and continue reporting checks unaffected by it - All pass → proceed to Step 6 - Required behavior cannot be determined from the supplied governing and repository evidence → proceed to Step 6 with `verification_incomplete` -- Confirmed value boundaries cannot all remain true and the user must choose which changes, or an irreversible external action requires authorization → proceed to Step 6 with `blocked` +- Value boundaries cannot all remain true and the user must choose which changes, or an irreversible external action requires authorization → proceed to Step 6 with `blocked` ### Step 6: Return JSON Result Return one of the following as the final response (see Output Format for schemas): - `status: "pass"` — all quality checks pass - `status: "stub_detected"` — incomplete implementation found (from Step 1) - `status: "verification_incomplete"` — environment or a separate-responsibility failure prevents required proof -- `status: "blocked"` — a confirmed value-boundary choice or irreversible external action authorization belongs to the user +- `status: "blocked"` — a value-boundary choice or irreversible external action authorization belongs to the user ## Frontend-Specific Quality Criteria @@ -132,10 +132,10 @@ Before setting status to blocked or `verification_incomplete`, confirm evidence | Condition | Example | Reason | |-----------|---------|--------| -| Confirmed value boundaries conflict | Outcome requires immediate completion while a desired-future requirement requires a prerequisite that prevents it | User must choose which confirmed value changes | +| Value boundaries conflict | Outcome requires immediate completion while a desired-future requirement requires a prerequisite that prevents it | User must choose which value boundary changes | | Fix requires an irreversible external action | Restoring the frontend integration requires rotating a live credential | User must authorize the exact action | -**Determination Logic**: Treat a failure as in scope when evidence ties it to the current change or confirmed outcome; fix it and re-run the check. Resolve UI behavior, design, Props, dependency, state, and other reversible ambiguity from governing sources and representative code. Return `blocked` only when confirmed outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes, or when an irreversible external action requires authorization. Missing evidence is `verification_incomplete`, not a user decision. +**Determination Logic**: Treat a failure as in scope when evidence ties it to the current change or the outcome; fix it and re-run the check. Resolve UI behavior, design, Props, dependency, state, and other reversible ambiguity from governing sources and representative code. Return `blocked` only when the outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes, or when an irreversible external action requires authorization. Missing evidence is `verification_incomplete`, not a user decision. ### verification_incomplete (Required proof remains unavailable) @@ -192,9 +192,9 @@ Use `null` for `file` or `location` when no corresponding file or code location ```json { "status": "blocked", - "reason": "Confirmed value boundaries cannot all remain true", + "reason": "Value boundaries cannot all remain true", "evidence": ["Governing source and observed repository evidence showing the conflict or irreversible action"], - "requiredDecision": "Which confirmed value boundary may change, or the exact irreversible action requiring authorization" + "requiredDecision": "Which value boundary may change, or the exact irreversible action requiring authorization" } ``` @@ -293,4 +293,4 @@ All fixes must satisfy these criteria: ## Fix Determination Flow -Detect error → execute Evidence Confirmation Process → fix per frontend project rules → proceed to next check. Resolve UI, design, contract, dependency, state, and other repository-local reversible choices from representative evidence. Return `blocked` only for a confirmed value-boundary choice or irreversible external action authorization; return missing evidence as `verification_incomplete`. +Detect error → execute Evidence Confirmation Process → fix per frontend project rules → proceed to next check. Resolve UI, design, contract, dependency, state, and other repository-local reversible choices from representative evidence. Return `blocked` only for a value-boundary choice or irreversible external action authorization; return missing evidence as `verification_incomplete`. diff --git a/dev-workflows-fullstack/agents/quality-fixer.md b/dev-workflows-fullstack/agents/quality-fixer.md index 6b23076e..cf730b03 100644 --- a/dev-workflows-fullstack/agents/quality-fixer.md +++ b/dev-workflows-fullstack/agents/quality-fixer.md @@ -16,14 +16,14 @@ Executes applicable quality checks, fixes in-scope failures, and reports exact p ## Main Responsibilities 1. **Self-contained Quality Assurance and Fix Execution** - - Execute applicable project quality checks; fix failures tied to the current change or confirmed task scope, and report other failures with their owning boundary as `verification_incomplete` + - Execute applicable project quality checks; fix failures tied to the current change or the task scope, and report other failures with their owning boundary as `verification_incomplete` - Analyze error root causes and execute both auto-fixes and manual fixes autonomously - Continue until each in-scope failure is fixed, required proof remains unavailable, or one authoritative `blocked` condition is evidenced; return `pass` only when every applicable check passes ## Input Parameters - **task_file** (optional): Path to the task file being verified. When provided, use its Operation Verification Methods as task-specific checks. -- **direct_scope** (for workflow execution without a task file): Confirmed outcome and exclusions, copied unchanged from the execution scope +- **direct_scope** (for workflow execution without a task file): Outcome and exclusions, copied unchanged from the execution scope - **governing_sources** (for direct scope): Authoritative source paths and unchanged governing values used for execution - **observable_verification** (for direct scope): The same behavior, artifact state, or command result required to prove execution complete - **correction_findings** (optional): Complete applied finding objects supplied to the executor, copied unchanged as the correction scope and acceptance evidence @@ -78,14 +78,14 @@ Apply fixes per coding-principles and testing-principles skills. - Verified failure in a separate responsibility → Return `verification_incomplete` with evidence and continue reporting checks unaffected by it - All pass → proceed to Step 6 - Required behavior cannot be determined from the supplied governing and repository evidence → proceed to Step 6 with `verification_incomplete` -- Confirmed value boundaries cannot all remain true and the user must choose which changes, or an irreversible external action requires authorization → proceed to Step 6 with `blocked` +- Value boundaries cannot all remain true and the user must choose which changes, or an irreversible external action requires authorization → proceed to Step 6 with `blocked` ### Step 6: Return JSON Result Return one of the following as the final response (see Output Format for schemas): - `status: "pass"` — all quality checks pass - `status: "stub_detected"` — incomplete implementation found (from Step 1) - `status: "verification_incomplete"` — environment or a separate-responsibility failure prevents required proof -- `status: "blocked"` — a confirmed value-boundary choice or irreversible external action authorization belongs to the user +- `status: "blocked"` — a value-boundary choice or irreversible external action authorization belongs to the user ## Status Determination Criteria @@ -103,12 +103,12 @@ Returned immediately when Step 1 finds incomplete implementation of the required | Condition | Example | Reason | |-----------|---------|--------| -| Confirmed value boundaries conflict | Outcome requires atomic completion while a desired-future requirement forbids the only available atomic mechanism | User must choose which confirmed value changes | +| Value boundaries conflict | Outcome requires atomic completion while a desired-future requirement forbids the only available atomic mechanism | User must choose which value boundary changes | | Fix requires an irreversible external action | Restoring correctness requires rotating a live credential | User must authorize the exact action | **Before blocking**: Always check Design Doc → PRD → Similar code → Test comments -**Determination**: Treat a failure as in scope when evidence ties it to the current change or confirmed outcome; fix it and re-run the check. Resolve technical design, contract, persistence, dependency, and other reversible ambiguity from governing sources and representative code. Return `blocked` only when confirmed outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes, or when an irreversible external action requires authorization. Missing evidence is `verification_incomplete`, not a user decision. +**Determination**: Treat a failure as in scope when evidence ties it to the current change or the outcome; fix it and re-run the check. Resolve technical design, contract, persistence, dependency, and other reversible ambiguity from governing sources and representative code. Return `blocked` only when the outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes, or when an irreversible external action requires authorization. Missing evidence is `verification_incomplete`, not a user decision. ### verification_incomplete (Required proof remains unavailable) @@ -165,9 +165,9 @@ Use `null` for `file` or `location` when no corresponding file or code location ```json { "status": "blocked", - "reason": "Confirmed value boundaries cannot all remain true", + "reason": "Value boundaries cannot all remain true", "evidence": ["Governing source and observed repository evidence showing the conflict or irreversible action"], - "requiredDecision": "Which confirmed value boundary may change, or the exact irreversible action requiring authorization" + "requiredDecision": "Which value boundary may change, or the exact irreversible action requiring authorization" } ``` diff --git a/dev-workflows-fullstack/agents/task-executor-frontend.md b/dev-workflows-fullstack/agents/task-executor-frontend.md index 428b906d..91edfc60 100644 --- a/dev-workflows-fullstack/agents/task-executor-frontend.md +++ b/dev-workflows-fullstack/agents/task-executor-frontend.md @@ -19,7 +19,7 @@ Operates in an independent context, executing autonomously until task completion Workflow callers use the applicable canonical fields below: - **task_file**: Frontend task file path for planned execution -- **direct_scope**: Confirmed outcome and exclusions, or another frontend implementation objective for prompt-only execution +- **direct_scope**: The convergence record's outcome and exclusions, or another frontend implementation objective for prompt-only execution - **governing_sources**: Authoritative requirement or artifact paths and unchanged governing values - **target_paths**: Suggested starting write and investigation paths - **observable_verification**: UI behavior, artifact state, or command result that proves the direct scope complete @@ -28,11 +28,11 @@ Workflow callers use the applicable canonical fields below: Accept equivalent labels, a prose frontend implementation objective, and legacy `incomplete_implementations`, then normalize the available meaning into one execution-instructions view. Resolve the objective from a readable or uniquely relocated `task_file`; otherwise from `direct_scope` or the direct invocation; otherwise select the next incomplete `docs/plans/tasks/*-task-*.md` for an ad-hoc task invocation. When more than one source is present, the task file governs execution scope and value boundaries; consistent direct values augment it, while its technical and UI How remains an evidence-correctable baseline. -For direct scope, derive operational details from the confirmed outcome, applicable artifacts, and repository evidence. Treat confirmed outcome, desired-future requirements, and non-goals in `governing_sources` as the value boundary; treat technical design and UI content as the current implementation baseline, `target_paths` as investigation starting points, and supplied or derived `observable_verification` as completion evidence. Correction and incomplete items remain inside the same confirmed value boundary. Repository-local reversible choices and technical corrections proceed from representative evidence. +For direct scope, derive operational details from the outcome, applicable artifacts, and repository evidence. Treat the outcome, desired-future requirements, and non-goals in `governing_sources` as the value boundary; treat technical design and UI content as the current implementation baseline, `target_paths` as investigation starting points, and supplied or derived `observable_verification` as completion evidence. Correction and incomplete items remain inside the same value boundary. Repository-local reversible choices and technical corrections proceed from representative evidence. ## Outcome and Change Boundary -Implement the confirmed outcome and the maintenance, tests, and adjacent corrections required to keep that outcome correct. `target_paths` and task-file Target Files guide initial investigation; the value boundary, governing sources, repository responsibilities, and observable verification determine the final changed set. Keep governing and reference documents read-only except for task progress and Investigation Notes explicitly owned by this workflow. Correct technical design, UI structure, contracts, dependencies, data flow, and persistence details from repository evidence when the value boundary remains true. +Implement the outcome and the maintenance, tests, and adjacent corrections required to keep that outcome correct. `target_paths` and task-file Target Files guide initial investigation; the value boundary, governing sources, repository responsibilities, and observable verification determine the final changed set. Keep governing and reference documents read-only except for task progress and Investigation Notes explicitly owned by this workflow. Correct technical design, UI structure, contracts, dependencies, data flow, and persistence details from repository evidence when the value boundary remains true. ## Mandatory Rules @@ -50,7 +50,7 @@ Deliver the outcome with types satisfied at their boundaries, errors propagated ## Design Surface Check (Before Mandatory Judgment) -Apply implementation-approach Design Convergence to the confirmed responsibility and starting paths. Challenge added design surface against current evidence, lower-surface alternatives, total complexity, and subtraction; include adjacent targets when the confirmed outcome's correctness or maintainability requires them. +Apply implementation-approach Design Convergence to the assigned responsibility and starting paths. Challenge added design surface against current evidence, lower-surface alternatives, total complexity, and subtraction; include adjacent targets when the outcome's correctness or maintainability requires them. ## Mandatory Judgment Criteria (Pre-implementation Check) @@ -79,20 +79,20 @@ Use the indicators to find plausible candidates and apply the authoritative boun 3. Continue with the repository-local reversible choice supported by that evidence. ### Step4: Core Mechanism Preservation Check -Preserve a mechanism when the confirmed outcome or desired-future requirements depend on its observable effect. Treat a mechanism specified only as technical How as a correctable design baseline. +Preserve a mechanism when the outcome or desired-future requirements depend on its observable effect. Treat a mechanism specified only as technical How as a correctable design baseline. □ Required core mechanism replaced by a simpler or weaker substitute, including one justified only by passing tests? □ Required core mechanism infeasible as specified? Any YES is corrected in implementation when the value boundary can remain true. Escalate only under the authoritative rule below. **Escalation boundary for unresolved judgment (authoritative rule for every check above):** -- Return `escalation_needed` when evidence shows the confirmed outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes. +- Return `escalation_needed` when evidence shows the outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes. - Return `escalation_needed` when an irreversible external action requires user authorization. - Otherwise resolve the technical choice from governing sources and representative repository evidence, record it, and continue. A changed Props contract, UI behavior, architecture, dependency, data flow, persistence detail, or observable output is not itself an escalation condition. ## Responsibility Boundaries **Scope**: React component implementation and test creation. Quality checks and commits are outside scope. -**Policy**: Start implementation immediately (treat as approved); correct technical design and implementation discrepancies autonomously inside the confirmed value boundary. +**Policy**: Start implementation immediately (treat as approved); correct technical design and implementation discrepancies autonomously inside the value boundary. **Progress**: For task-file execution, sync checkbox state across its task file, work plan, and overall design document when each exists (`[ ]` → `[🔄]` → `[x]`). For prompt-only execution, update a tracking artifact only when the prompt explicitly assigns that update. ## Workflow @@ -107,7 +107,7 @@ Resolve the frontend implementation objective through the input precedence above 1. Extract investigation paths from the execution instructions 2. Read every resolved Investigation Target before editing. When a search hint is provided (e.g., `(§ Auth Flow)` or `(authenticateUser function)`), locate and focus on that section 3. Record brief Investigation Notes identified by symbol, function, contract, or section, covering key interfaces, flow, state transitions, and side effects; append them to the task file when one is provided. Reserve file:line for post-edit evidence that requires it. -4. When a declared Investigation Target path fails direct resolution, search by filename, supplied component, hook, or section hint, imports, routes, and task or governing-artifact references. Use the best semantic matches supported by those sources, record the resolved evidence, and continue from the confirmed objective. For a `target_paths` entry intended for creation, inspect its existing parent and representative sibling +4. When a declared Investigation Target path fails direct resolution, search by filename, supplied component, hook, or section hint, imports, routes, and task or governing-artifact references. Use the best semantic matches supported by those sources, record the resolved evidence, and continue from the objective. For a `target_paths` entry intended for creation, inspect its existing parent and representative sibling #### Governing Sources and Dependency Deliverables 1. Extract governing-source and dependency paths or unchanged governing values from the execution instructions @@ -134,7 +134,7 @@ Read relevant Design Doc sections accurately; investigate existing implementatio Applies when Pre-implementation Verification finds a dependency this task requires is absent or unimplemented (e.g., a Design Doc component marked "requires new creation"). -1. Determine whether a local, reversible construct — a local slice, or a contract-preserving stub/adapter inside the confirmed responsibility — preserves the required contract. +1. Determine whether a local, reversible construct — a local slice, or a contract-preserving stub/adapter inside the assigned responsibility — preserves the required contract. 2. Branch on the result: - One local, reversible approach preserves the contract → proceed with it and record the integration handoff (what the real dependency must later provide, and where it connects) in Investigation Notes. - No local construct preserves the current technical contract, or several constructs differ on an architectural trade-off → choose and implement the lowest-surface value-preserving correction from governing and representative repository evidence. Apply the authoritative escalation boundary only if no option preserves all value boundaries or an irreversible external action is required. @@ -219,7 +219,7 @@ Use this response when evidence establishes either authoritative escalation cond ```json { "status": "escalation_needed", - "reason": "[Which confirmed value boundaries cannot all remain true, or which irreversible external action requires authorization]", + "reason": "[Which value boundaries cannot all remain true, or which irreversible external action requires authorization]", "taskName": "[Task name being executed]", "evidence": ["[Observed governing and repository evidence]"], "requiredDecision": "[Value-boundary choice or exact irreversible action requiring authorization]" @@ -238,4 +238,4 @@ This gate runs immediately before producing the final JSON response. ☐ Test runs cited as `runnableCheck` evidence meet the substantive and executable rules in the `runnableCheck.result` field specification ☐ Final response is a single JSON with `status: "completed"`, `status: "blocked"`, or `status: "escalation_needed"` and matches the schema in Structured Response Specification -**ENFORCEMENT**: Return `escalation_needed` only when confirmed outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes, or when an irreversible external action requires authorization. Technical design, UI, Props, architecture, dependency, data-flow, persistence, and implementation corrections that preserve those boundaries remain implementation work. +**ENFORCEMENT**: Return `escalation_needed` only when the outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes, or when an irreversible external action requires authorization. Technical design, UI, Props, architecture, dependency, data-flow, persistence, and implementation corrections that preserve those boundaries remain implementation work. diff --git a/dev-workflows-fullstack/agents/task-executor.md b/dev-workflows-fullstack/agents/task-executor.md index 161d9263..be4a9318 100644 --- a/dev-workflows-fullstack/agents/task-executor.md +++ b/dev-workflows-fullstack/agents/task-executor.md @@ -17,7 +17,7 @@ You are a specialized AI assistant for reliably executing individual tasks. Workflow callers use the applicable canonical fields below: - **task_file**: Task file path for planned execution -- **direct_scope**: Confirmed outcome and exclusions, or another implementation objective for prompt-only execution +- **direct_scope**: The convergence record's outcome and exclusions, or another implementation objective for prompt-only execution - **governing_sources**: Authoritative requirement or artifact paths and unchanged governing values - **target_paths**: Suggested starting write and investigation paths - **observable_verification**: Behavior, artifact state, or command result that proves the direct scope complete @@ -26,11 +26,11 @@ Workflow callers use the applicable canonical fields below: Accept equivalent labels, a prose implementation objective, and legacy `incomplete_implementations`, then normalize the available meaning into one execution-instructions view. Resolve the objective from a readable or uniquely relocated `task_file`; otherwise from `direct_scope` or the direct invocation; otherwise select the next incomplete `docs/plans/tasks/*-task-*.md` for an ad-hoc task invocation. When more than one source is present, the task file governs execution scope and value boundaries; consistent direct values augment it, while its technical How remains an evidence-correctable baseline. -For direct scope, derive operational details from the confirmed outcome, applicable artifacts, and repository evidence. Treat confirmed outcome, desired-future requirements, and non-goals in `governing_sources` as the value boundary; treat technical design content as the current implementation baseline, `target_paths` as investigation starting points, and supplied or derived `observable_verification` as completion evidence. Correction and incomplete items remain inside the same confirmed value boundary. Repository-local reversible choices and technical corrections proceed from representative evidence. +For direct scope, derive operational details from the outcome, applicable artifacts, and repository evidence. Treat the outcome, desired-future requirements, and non-goals in `governing_sources` as the value boundary; treat technical design content as the current implementation baseline, `target_paths` as investigation starting points, and supplied or derived `observable_verification` as completion evidence. Correction and incomplete items remain inside the same value boundary. Repository-local reversible choices and technical corrections proceed from representative evidence. ## Outcome and Change Boundary -Implement the confirmed outcome and the maintenance, tests, and adjacent corrections required to keep that outcome correct. `target_paths` and task-file Target Files guide initial investigation; the value boundary, governing sources, repository responsibilities, and observable verification determine the final changed set. Keep governing and reference documents read-only except for task progress and Investigation Notes explicitly owned by this workflow. Correct technical design, contracts, architecture, dependencies, and persistence details from repository evidence when the value boundary remains true. +Implement the outcome and the maintenance, tests, and adjacent corrections required to keep that outcome correct. `target_paths` and task-file Target Files guide initial investigation; the value boundary, governing sources, repository responsibilities, and observable verification determine the final changed set. Keep governing and reference documents read-only except for task progress and Investigation Notes explicitly owned by this workflow. Correct technical design, contracts, architecture, dependencies, and persistence details from repository evidence when the value boundary remains true. ## Mandatory Rules @@ -45,7 +45,7 @@ Deliver the outcome with contracts satisfied at their boundaries, errors propaga ## Design Surface Check (Before Mandatory Judgment) -Apply implementation-approach Design Convergence to the confirmed responsibility and starting paths. Challenge added design surface against current evidence, lower-surface alternatives, total complexity, and subtraction; include adjacent targets when the confirmed outcome's correctness or maintainability requires them. +Apply implementation-approach Design Convergence to the assigned responsibility and starting paths. Challenge added design surface against current evidence, lower-surface alternatives, total complexity, and subtraction; include adjacent targets when the outcome's correctness or maintainability requires them. ## Mandatory Judgment Criteria (Pre-implementation Check) @@ -74,20 +74,20 @@ Use the indicators to find plausible candidates and apply the authoritative boun 3. Continue with the repository-local reversible choice supported by that evidence. ### Step4: Core Mechanism Preservation Check -Preserve a mechanism when the confirmed outcome or desired-future requirements depend on its observable effect. Treat a mechanism specified only as technical How as a correctable design baseline. +Preserve a mechanism when the outcome or desired-future requirements depend on its observable effect. Treat a mechanism specified only as technical How as a correctable design baseline. □ Required core mechanism replaced by a simpler or weaker substitute, including one justified only by passing tests? □ Required core mechanism infeasible as specified? Any YES is corrected in implementation when the value boundary can remain true. Escalate only under the authoritative rule below. **Escalation boundary for unresolved judgment (authoritative rule for every check above):** -- Return `escalation_needed` when evidence shows the confirmed outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes. +- Return `escalation_needed` when evidence shows the outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes. - Return `escalation_needed` when an irreversible external action requires user authorization. - Otherwise resolve the technical choice from governing sources and representative repository evidence, record it, and continue. A changed interface, architecture, dependency, persistence detail, or observable UI/API output is not itself an escalation condition. ## Responsibility Boundaries **Scope**: Implementation and test creation. Quality checks and commits are outside scope. -**Policy**: Start implementation immediately (treat as approved); correct technical design and implementation discrepancies autonomously inside the confirmed value boundary. +**Policy**: Start implementation immediately (treat as approved); correct technical design and implementation discrepancies autonomously inside the value boundary. **Progress**: For task-file execution, sync checkbox state across its task file, work plan, and overall design document when each exists (`[ ]` → `[🔄]` → `[x]`). For prompt-only execution, update a tracking artifact only when the prompt explicitly assigns that update. ## Workflow @@ -102,7 +102,7 @@ Resolve the implementation objective through the input precedence above, derive 1. Extract investigation paths from the execution instructions 2. Read every resolved Investigation Target before editing. When a search hint is provided (e.g., `(§ Auth Flow)` or `(authenticateUser function)`), locate and focus on that section 3. Record brief Investigation Notes identified by symbol, function, contract, or section, covering key interfaces, flow, state transitions, and side effects; append them to the task file when one is provided. Reserve file:line for post-edit evidence that requires it. -4. When a declared Investigation Target path fails direct resolution, search by filename, supplied symbol or section hint, callers, and task or governing-artifact references. Use the best semantic matches supported by those sources, record the resolved evidence, and continue from the confirmed objective. For a `target_paths` entry intended for creation, inspect its existing parent and representative sibling +4. When a declared Investigation Target path fails direct resolution, search by filename, supplied symbol or section hint, callers, and task or governing-artifact references. Use the best semantic matches supported by those sources, record the resolved evidence, and continue from the objective. For a `target_paths` entry intended for creation, inspect its existing parent and representative sibling #### Governing Sources and Dependency Deliverables 1. Extract governing-source and dependency paths or unchanged governing values from the execution instructions @@ -129,7 +129,7 @@ Read relevant Design Doc sections (interface contracts, data structures, depende Applies when Pre-implementation Verification finds a dependency this task requires is absent or unimplemented (e.g., a Design Doc component marked "requires new creation"). -1. Determine whether a local, reversible construct — a local slice, or a contract-preserving stub/adapter inside the confirmed responsibility — preserves the required contract. +1. Determine whether a local, reversible construct — a local slice, or a contract-preserving stub/adapter inside the assigned responsibility — preserves the required contract. 2. Branch on the result: - One local, reversible approach preserves the contract → proceed with it and record the integration handoff (what the real dependency must later provide, and where it connects) in Investigation Notes. - No local construct preserves the current technical contract, or several constructs differ on an architectural trade-off → choose and implement the lowest-surface value-preserving correction from governing and representative repository evidence. Apply the authoritative escalation boundary only if no option preserves all value boundaries or an irreversible external action is required. @@ -215,7 +215,7 @@ Use this response when evidence establishes either authoritative escalation cond ```json { "status": "escalation_needed", - "reason": "[Which confirmed value boundaries cannot all remain true, or which irreversible external action requires authorization]", + "reason": "[Which value boundaries cannot all remain true, or which irreversible external action requires authorization]", "taskName": "[Task name being executed]", "evidence": ["[Observed governing and repository evidence]"], "requiredDecision": "[Value-boundary choice or exact irreversible action requiring authorization]" @@ -234,4 +234,4 @@ This gate runs immediately before producing the final JSON response. ☐ Test runs cited as `runnableCheck` evidence meet the substantive and executable rules in the `runnableCheck.result` field specification ☐ Final response is a single JSON with `status: "completed"`, `status: "blocked"`, or `status: "escalation_needed"` and matches the schema in Structured Response Specification -**ENFORCEMENT**: Return `escalation_needed` only when confirmed outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes, or when an irreversible external action requires authorization. Technical design, interface, architecture, dependency, persistence, and implementation corrections that preserve those boundaries remain implementation work. +**ENFORCEMENT**: Return `escalation_needed` only when the outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes, or when an irreversible external action requires authorization. Technical design, interface, architecture, dependency, persistence, and implementation corrections that preserve those boundaries remain implementation work. diff --git a/dev-workflows-fullstack/agents/technical-designer-frontend.md b/dev-workflows-fullstack/agents/technical-designer-frontend.md index 6909ce36..03fbada6 100644 --- a/dev-workflows-fullstack/agents/technical-designer-frontend.md +++ b/dev-workflows-fullstack/agents/technical-designer-frontend.md @@ -1,6 +1,6 @@ --- name: technical-designer-frontend -description: Creates a scoped frontend ADR batch or one Design Doc from confirmed UI requirements and decision-relevant repository evidence. Use when frontend technical choices or implementation design need an approved artifact. +description: Creates a scoped frontend ADR batch or one Design Doc from UI requirements and decision-relevant repository evidence. Use when frontend technical choices or implementation design need an approved artifact. tools: Read, Write, Edit, MultiEdit, Glob, LS, Bash, WebSearch skills: - documentation-criteria @@ -26,18 +26,18 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow - **document_to_create**: `ADRBatch` or `DesignDoc` in create mode - **output_path**: Optional exact Design Doc destination; required when the caller splits one feature into multiple documents. Updates retain the existing path. - **Operation Mode**: `create` (default), `update`, or `reverse-engineer` -- **confirmed_requirement_context**: Exact approved PRD path, or the unchanged orchestrator-confirmed convergence record only when no approved PRD exists -- **structural_scale**: Orchestrator-confirmed `Medium` or `Large` scale for a Design Doc +- **requirement_context**: Exact approved PRD path, or the orchestrator's unchanged convergence record only when no approved PRD exists +- **structural_scale**: Orchestrator-selected `Medium` or `Large` scale for a Design Doc - **decision_materials**: Ordered array copied unchanged from the codebase analysis result at `decisionMaterials.candidateDecisionPoints` - **codebase_analysis** and **ui_analysis**: Applicable focus areas and existing-behavior safeguards for a Design Doc - **ui_spec_path**: Approved UI Spec when it governs the document or an ADR decision -- **decision_points**: Orchestrator-confirmed frontend decision points for an ADR batch, copied unchanged +- **decision_points**: Orchestrator-selected frontend decision points for an ADR batch, copied unchanged - Existing document path or paths in update mode - **correction_findings**: Complete applied verification or review finding objects, copied verbatim with only their orchestrator dispositions added (update mode) - **adr_paths**: Accepted ADRs that constrain the Design Doc - Optional external-resource references, backend Design Doc, and resolved prior-layer verification -Use the orchestrator-confirmed outcome, scope, exclusions, Structural Scale, and document route. Report a contradiction with a governing source instead of changing that classification. +Use the outcome, scope, and exclusions from the requirement context and the orchestrator-selected Structural Scale and document route. Report a contradiction with a governing source instead of changing that classification. Create/update mode requires a current PRD carrier or convergence record. A scope-preserving update may preserve its existing carrier. Reverse-engineer mode records convergence as `N/A — reverse-engineered/as-is document`. @@ -49,23 +49,23 @@ Inspect only gaps that can change reuse, option validity, a selected decision, a ## ADR Batch — Create Mode -Create one ADR per supplied decision point and finish the batch before returning. If evidence no longer supports the confirmed Choice or Durability filter, return the contradiction for orchestrator resolution. +Create one ADR per supplied decision point and finish the batch before returning. If evidence no longer supports the orchestrator's Choice or Durability filter result, return the contradiction for orchestrator resolution. Before the first ADR write, Glob `docs/adr/ADR-[0-9][0-9][0-9][0-9]-*.md`, parse valid numeric prefixes, and assign contiguous numbers from `max + 1` in the supplied `decision_points` order. Use `0001` when no numbered ADR exists. Make every assigned path unique, confirm it is still absent immediately before its write, and return a blocking collision instead of overwriting. Use the assigned path order in the result. 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. 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. +1. Keep one technical question inside the scope of the requirements. +2. Compare every credible, materially distinct option using product value from the requirements, repository fit, total complexity, maintainability, material trade-offs, and reversibility. +3. Select the smallest sufficient option whose total complexity is justified by product value from the requirements. 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. +5. Keep component implementation and end-to-end flow out of the ADR. Repository-owned implementation details go to the Design Doc only when the requirements activate them; external release execution and organizational rollout remain outside both artifacts. Use `Proposed` status for created ADRs. The orchestrator records batch approval. ## Design Doc — Create Mode -Create the complete frontend implementation design for the confirmed scope and any applicable approved UI Spec. Apply implementation-approach Design Convergence in active analysis, then record only the Selected Design and the evidence that justifies any added design surface. Create mode limits evidence collection to supplied artifacts, read-only repository inspection, and authoritative read-only sources. When a specific decision-changing premise remains unresolved, record it for verification; capability probes are reserved for the fresh review-triggered update gate below. +Create the complete frontend implementation design for the scope of the requirements and any applicable approved UI Spec. Apply implementation-approach Design Convergence in active analysis, then record only the Selected Design and the evidence that justifies any added design surface. Create mode limits evidence collection to supplied artifacts, read-only repository inspection, and authoritative read-only sources. When a specific decision-changing premise remains unresolved, record it for verification; capability probes are reserved for the fresh review-triggered update gate below. Follow `references/design-template.md` in the documentation-criteria skill. Preserve these downstream guarantees whenever applicable: @@ -75,7 +75,7 @@ Follow `references/design-template.md` in the documentation-criteria skill. Pres - code and UI `focusAreas` retain distinct `code:` and `ui:` IDs and one Fact Disposition row each; - component responsibility, Props/API contracts, state ownership and reset behavior, rendering conditions, interactions, service boundaries, error behavior, compatibility, and exact serialized/display values supply the details required for implementation; - changed behavior defines representative output or rendered-state comparison where equivalence matters; -- applicable accessibility, responsive, loading, empty, error, security, and test boundaries remain explicit when required by the UI Spec, preserved behavior, repository rule, or confirmed requirement; +- applicable accessibility, responsive, loading, empty, error, security, and test boundaries remain explicit when required by the UI Spec, preserved behavior, repository rule, or requirement; - implementation order follows real dependencies, and the earliest useful RTL, integration, browser, build, or artifact check proves a representative outcome or material risk. 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. @@ -84,7 +84,7 @@ Use diagrams only when they clarify a material component, state, or interaction Acceptance criteria use the smallest representative set that proves the approved user-visible outcome and material failure states. Verification uses the narrowest applicable boundary. -Derive each acceptance criterion from one confirmed UI behavior. Add a loading/empty/error/lifecycle, route, permission, responsive, accessibility, or mode-by-branch case when the approved promise can fail independently on that boundary. Consolidate cases that exercise the same failure and correction; each retained state category traces to an independent required failure boundary. +Derive each acceptance criterion from one UI behavior in the requirements. Add a loading/empty/error/lifecycle, route, permission, responsive, accessibility, or mode-by-branch case when the approved promise can fail independently on that boundary. Consolidate cases that exercise the same failure and correction; each retained state category traces to an independent required failure boundary. Verify a current external technology, browser, compatibility, performance, or security fact from an authoritative source only when its truth can change option selection, implementation, or verification. Record unresolved decision-changing facts for the verification loop. @@ -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. 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. +Update requested sections and dependent statements. For `correction_findings`, resolve each received defect within the 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 outcome, desired-future requirements, and non-goals stay true. If the 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 @@ -124,7 +124,7 @@ Document supplied inventory and existing frontend behavior as-is. Trace in-scope ## Completion Check -- No UI or implementation scope exceeds confirmed requirements and required dependencies. +- No UI or implementation scope exceeds the requirements and required dependencies. - 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. diff --git a/dev-workflows-fullstack/agents/technical-designer.md b/dev-workflows-fullstack/agents/technical-designer.md index 4787cf6f..483f13f1 100644 --- a/dev-workflows-fullstack/agents/technical-designer.md +++ b/dev-workflows-fullstack/agents/technical-designer.md @@ -1,6 +1,6 @@ --- name: technical-designer -description: Creates a scoped ADR batch or one backend/general Design Doc from confirmed requirements and decision-relevant repository evidence. Use when technical choices or implementation design need an approved artifact. +description: Creates a scoped ADR batch or one backend/general Design Doc from requirements and decision-relevant repository evidence. Use when technical choices or implementation design need an approved artifact. tools: Read, Write, Edit, MultiEdit, Glob, LS, Bash, WebSearch skills: - documentation-criteria @@ -25,17 +25,17 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow - **document_to_create**: `ADRBatch` or `DesignDoc` in create mode - **output_path**: Optional exact Design Doc destination; required when the caller splits one feature into multiple documents. Updates retain the existing path. - **Operation Mode**: `create` (default), `update`, or `reverse-engineer` -- **confirmed_requirement_context**: Exact approved PRD path, or the unchanged orchestrator-confirmed convergence record only when no approved PRD exists -- **structural_scale**: Orchestrator-confirmed `Medium` or `Large` scale for a Design Doc +- **requirement_context**: Exact approved PRD path, or the orchestrator's unchanged convergence record only when no approved PRD exists +- **structural_scale**: Orchestrator-selected `Medium` or `Large` scale for a Design Doc - **decision_materials**: Ordered array copied unchanged from the codebase analysis result at `decisionMaterials.candidateDecisionPoints` - **codebase_analysis**: Applicable focus areas and existing-behavior safeguards for a Design Doc -- **decision_points**: Orchestrator-confirmed decision points for an ADR batch, copied unchanged +- **decision_points**: Orchestrator-selected decision points for an ADR batch, copied unchanged - Existing document path or paths in update mode - **correction_findings**: Complete applied verification or review finding objects, copied verbatim with only their orchestrator dispositions added (update mode) - **adr_paths**: Accepted ADRs that constrain the Design Doc - Optional UI Spec, external-resource references, or prior-layer verification supplied by the caller -Use the orchestrator-confirmed outcome, scope, exclusions, Structural Scale, and document route. Report a contradiction with a governing source instead of silently changing that classification. +Use the outcome, scope, and exclusions from the requirement context and the orchestrator-selected Structural Scale and document route. Report a contradiction with a governing source instead of silently changing that classification. Create/update mode requires a current PRD carrier or convergence record. A scope-preserving update may preserve its existing carrier. Reverse-engineer mode records convergence as `N/A — reverse-engineered/as-is document`. @@ -43,7 +43,7 @@ Create/update mode requires a current PRD carrier or convergence record. A scope Use supplied `decision_materials` for an ADR batch and unchanged `codebase_analysis` for a Design Doc as the primary repository evidence: -- `decision_materials[].options` supplies repository-backed choices, repository fit, lifecycle cost drivers, and maintainability evidence for ADR selection; confirmed requirements supply product value; +- `decision_materials[].options` supplies repository-backed choices, repository fit, lifecycle cost drivers, and maintainability evidence for ADR selection; the requirements supply product value; - `codebase_analysis.decisionMaterials.reuse` and applicable `codebase_analysis.simplifications` reduce new implementation surface; - `codebase_analysis.decisionMaterials.invalidations` eliminates approaches; - `codebase_analysis.decisionMaterials.verification` constrains proof; @@ -54,23 +54,23 @@ Inspect only gaps that can change reuse, option validity, a selected decision, a ## ADR Batch — Create Mode -Create one ADR per supplied decision point and finish the complete batch before returning. If evidence no longer supports the confirmed Choice or Durability filter, return the contradiction for orchestrator resolution. +Create one ADR per supplied decision point and finish the complete batch before returning. If evidence no longer supports the orchestrator's Choice or Durability filter result, return the contradiction for orchestrator resolution. Before the first ADR write, Glob `docs/adr/ADR-[0-9][0-9][0-9][0-9]-*.md`, parse valid numeric prefixes, and assign contiguous numbers from `max + 1` in the supplied `decision_points` order. Use `0001` when no numbered ADR exists. Make every assigned path unique, confirm it is still absent immediately before its write, and return a blocking collision instead of overwriting. Use the assigned path order in the result. 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. 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. +1. Keep one technical question inside the scope of the requirements. +2. Compare every credible, materially distinct option using product value from the requirements, repository fit, total complexity, maintainability, material trade-offs, and reversibility. +3. Select the smallest sufficient option whose total complexity is justified by product value from the requirements. 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 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 the requirements activate them; external release execution and organizational rollout remain outside both artifacts. Use `Proposed` status for created ADRs. The orchestrator records user approval for the batch. ## Design Doc — Create Mode -Create the complete end-to-end technical design for the confirmed scope. Apply implementation-approach Design Convergence in active analysis, then record only the Selected Design and the evidence that justifies any added design surface. Create mode limits evidence collection to supplied artifacts, read-only repository inspection, and authoritative read-only sources. When a specific decision-changing premise remains unresolved, record it for verification; capability probes are reserved for the fresh review-triggered update gate below. +Create the complete end-to-end technical design for the scope of the requirements. Apply implementation-approach Design Convergence in active analysis, then record only the Selected Design and the evidence that justifies any added design surface. Create mode limits evidence collection to supplied artifacts, read-only repository inspection, and authoritative read-only sources. When a specific decision-changing premise remains unresolved, record it for verification; capability probes are reserved for the fresh review-triggered update gate below. Follow `references/design-template.md` in the documentation-criteria skill. Preserve these downstream guarantees whenever applicable: @@ -88,9 +88,9 @@ Sections and rows activate when their boundary exists. An authoritative referenc 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. +Acceptance criteria use the smallest representative set that proves the outcome and material failure boundaries. Verification uses the narrowest repository operation or test lane that can observe each required boundary. -Derive each acceptance criterion from one confirmed behavior. Add another boundary case when the same promise can fail independently there, such as a distinct state transition, persistence/publication boundary, compatibility path, or mode interacting with an existing branch. Consolidate cases that exercise the same failure and correction; generic happy/unhappy/edge categories create requirements only when they expose an independent failure. +Derive each acceptance criterion from one behavior in the requirements. Add another boundary case when the same promise can fail independently there, such as a distinct state transition, persistence/publication boundary, compatibility path, or mode interacting with an existing branch. Consolidate cases that exercise the same failure and correction; generic happy/unhappy/edge categories create requirements only when they expose an independent failure. Verify a current external technology, compatibility, performance, or security fact from an authoritative source only when its truth can change option selection, implementation, or verification. Record unresolved decision-changing facts for the verification loop. @@ -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. 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. +Update requested sections and dependent statements. For `correction_findings`, resolve each received defect within the 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 outcome, desired-future requirements, and non-goals stay true. If the 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 @@ -130,7 +130,7 @@ Document supplied inventory and existing behavior as-is. Trace each in-scope ent ## Completion Check -- No implementation scope exceeds confirmed requirements and required dependencies. +- No implementation scope exceeds the requirements and required dependencies. - 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. diff --git a/dev-workflows-fullstack/agents/ui-analyzer.md b/dev-workflows-fullstack/agents/ui-analyzer.md index c5c499cc..a2ad0c82 100644 --- a/dev-workflows-fullstack/agents/ui-analyzer.md +++ b/dev-workflows-fullstack/agents/ui-analyzer.md @@ -12,7 +12,7 @@ You are an AI assistant specializing in UI fact gathering for frontend design. ## Input Parameters - **prd_path**: Approved PRD path (required when one exists) -- **requirements**: Confirmed requirements verbatim (required only when no approved PRD exists) +- **requirements**: Requirements verbatim (required only when no approved PRD exists) - **ui_spec_path**: Path to existing UI Spec, when one exists (optional) - **prototype_path**: Decision-relevant prototype path (optional) - **external_resource_refs**: Selected external-resource records or an empty array (optional) @@ -21,11 +21,11 @@ Supply exactly one of `prd_path` or `requirements`. ## Evidence Boundary -Gather UI facts only; the parent and document owners select scope and design. Return evidence when it can change the UI Spec, a component or service contract, preserved visible behavior, reuse, or verification for the confirmed change. Distinguish code and external observations from inferences and unknowns. +Gather UI facts only; the parent and document owners select scope and design. Return evidence when it can change the UI Spec, a component or service contract, preserved visible behavior, reuse, or verification for the change. Distinguish code and external observations from inferences and unknowns. Use only supplied `external_resource_refs`. Resolve their labels through `docs/project-context/external-resources.md` and inspect the relevant subset through its recorded access method. Record an unavailable source with the attempted method, reason, and affected decision, then continue with available evidence. An empty or omitted list selects repository-only analysis. A supplied prototype remains analysis input even without an external reference. -Locate the affected screens, components, and callers, then inspect only the render, state, style, interaction, and data path needed for the current decisions. Include Props and variants, DOM or layout behavior, display conditions, responsive behavior, accessibility, localization, and generated artifacts when they can change the confirmed result, a preserved contract, reuse, or verification. From evidence already gathered, record a simplification when a responsibility, branch, artifact, or change can be omitted while the confirmed outcome still holds; it remains a candidate for the parent and document owner. Inspect every consumer only when the complete consumer set controls compatibility; otherwise use representative consumers, tests, stories, and style peers. +Locate the affected screens, components, and callers, then inspect only the render, state, style, interaction, and data path needed for the current decisions. Include Props and variants, DOM or layout behavior, display conditions, responsive behavior, accessibility, localization, and generated artifacts when they can change the result, a preserved contract, reuse, or verification. From evidence already gathered, record a simplification when a responsibility, branch, artifact, or change can be omitted while the outcome still holds; it remains a candidate for the parent and document owner. Inspect every consumer only when the complete consumer set controls compatibility; otherwise use representative consumers, tests, stories, and style peers. Stop when another fact cannot change one of those outcomes. @@ -44,7 +44,7 @@ Return one compact JSON object. Put decision-relevant component, state, Props, l {"fact_id": "path:identifier", "area": "UI question", "evidence": "path:line or external source; observed or inferred", "factsToAddress": "decision-relevant behavior, contract, reuse, or verification", "risk": "effect if ignored", "decisionEffect": "UI Spec, design, or verification decision this controls"} ], "simplifications": [ - {"avoidableChange": "responsibility, branch, artifact, or change that can be omitted", "evidence": "path:line, governing source, or focusArea reference", "conditions": "conditions or unknowns under which the confirmed outcome still holds"} + {"avoidableChange": "responsibility, branch, artifact, or change that can be omitted", "evidence": "path:line, governing source, or focusArea reference", "conditions": "conditions or unknowns under which the outcome still holds"} ], "limitations": ["Areas the analysis could not reach with confidence"] } diff --git a/dev-workflows-fullstack/agents/ui-spec-designer.md b/dev-workflows-fullstack/agents/ui-spec-designer.md index 8cd3c43f..696587c0 100644 --- a/dev-workflows-fullstack/agents/ui-spec-designer.md +++ b/dev-workflows-fullstack/agents/ui-spec-designer.md @@ -1,6 +1,6 @@ --- name: ui-spec-designer -description: Creates UI Specifications from confirmed requirements and optional prototype code. Use when frontend UI design is needed, or when "UI spec/screen design/component decomposition/UI specification" is mentioned. +description: Creates UI Specifications from requirements and optional prototype code. Use when frontend UI design is needed, or when "UI spec/screen design/component decomposition/UI specification" is mentioned. tools: Read, Write, Edit, MultiEdit, Glob, LS, Bash skills: - documentation-criteria @@ -18,30 +18,30 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow ## Main Responsibilities -1. Analyze confirmed UI requirements and map them to screens, states, and components +1. Analyze the UI requirements and map them to screens, states, and components 2. Extract screen structure, transitions, and interaction patterns from prototype code (when provided) -3. Create the complete UI Specification for the confirmed UI scope following `references/ui-spec-template.md` in the documentation-criteria skill +3. Create the complete UI Specification for the UI scope of the requirements following `references/ui-spec-template.md` in the documentation-criteria skill 4. Define component decomposition with state x display matrices for applicable states 5. Identify reusable existing components in the codebase 6. Define accessibility requirements ## Input Parameters -- **confirmed_requirement_context**: Exact approved PRD path, or the unchanged confirmed convergence record only when no approved PRD exists (required) +- **requirement_context**: Exact approved PRD path, or the unchanged convergence record only when no approved PRD exists (required) - **ui_analysis**: UI analysis JSON for existing UI behavior and external evidence (required) - **codebase_analysis**: Applicable codebase analysis evidence (optional) - **prototype_path**: Decision-relevant prototype path (optional, placed in `docs/ui-spec/assets/{feature-name}/`) -- **prototype_reference_strength**: `binding` or `reference`, accompanying `prototype_path`. When a prototype is provided without a strength, use the confirmed requirement context if it establishes the strength; otherwise record the unresolved strength in Prototype Management and the existing decision-blocking Open Items, and continue work independent of that decision. +- **prototype_reference_strength**: `binding` or `reference`, accompanying `prototype_path`. When a prototype is provided without a strength, use the requirement context if it establishes the strength; otherwise record the unresolved strength in Prototype Management and the existing decision-blocking Open Items, and continue work independent of that decision. - **external_resource_refs**: Selected external-resource records or an empty array (optional) ## Mandatory Process Before UI Spec Creation ### Step 1: Requirement Analysis -1. **Read and understand the confirmed requirement context** - - Extract confirmed UI behaviors and acceptance criteria; preserve existing AC IDs when present +1. **Read and understand the requirement context** + - Extract UI behaviors and acceptance criteria; preserve existing AC IDs when present - Identify screens/views implied by user stories and requirements - - Note accessibility requirements and UI quality metrics from the confirmed context + - Note accessibility requirements and UI quality metrics from the requirement context 2. **Classify ACs by UI relevance** - Which ACs map to specific screens or user interactions @@ -50,7 +50,7 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow ### Step 2: Prototype Code Analysis (when `prototype_path` is provided) 1. **Analyze the relevant prototype surface** - - Start from screens/components mapped to confirmed requirements and follow only required imports + - Start from screens/components mapped to the requirements and follow only required imports - Extract page/screen structure, component hierarchy, routing, material event handlers, and conditional rendering - Catalog only states represented by approved behavior or needed to understand the prototype @@ -86,8 +86,8 @@ Apply evidenced `simplifications` when their recorded condition holds; otherwise 2. **Fill applicable sections**: - Screen list with entry conditions and transitions - Component tree with decomposition - - State x display matrix for each component state required by confirmed requirements, approved UI direction, preserved behavior, or repository/design-system rules - - Interaction definitions linked to existing AC IDs when present, otherwise to an unambiguous confirmed requirement + - State x display matrix for each component state required by the requirements, approved UI direction, preserved behavior, or repository/design-system rules + - Interaction definitions linked to existing AC IDs when present, otherwise to an unambiguous requirement - Existing component reuse map - Design tokens (from existing codebase) - Visual acceptance criteria @@ -99,11 +99,11 @@ Apply evidenced `simplifications` when their recorded condition holds; otherwise Execute file output immediately (considered approved at execution). -When revising from review findings, resolve only the supplied defects within the confirmed UI outcome and accepted UI decisions. Return the conflicting evidence before changing that boundary. +When revising from review findings, resolve only the supplied defects within the UI outcome and accepted UI decisions. Return the conflicting evidence before changing that boundary. ## Quality Checklist -- [ ] All confirmed acceptance criteria with UI relevance are mapped to screens/components +- [ ] All acceptance criteria with UI relevance are mapped to screens/components - [ ] Every in-scope interactive component records each applicable state/display contract; no state exists only to fill the template - [ ] Interaction definitions use EARS format and reference existing AC IDs when present - [ ] Screen transitions have trigger and guard conditions defined @@ -114,7 +114,7 @@ When revising from review findings, resolve only the supplied defects within the - [ ] If prototype provided: Prototype Management records the reference strength - [ ] If prototype provided: the relevant prototype is placed in `docs/ui-spec/assets/` - [ ] Decision-blocking Open Items name the required owner or evidence; non-blocking unknowns remain explicit -- [ ] All UI Spec requirements align with the confirmed requirement context +- [ ] All UI Spec requirements align with the requirement context - [ ] External Resources Used section lists each used `external_resource_refs` entry by its project-tier label with only the feature-specific identifier - [ ] **Component heading uniqueness**: Every component is documented under a section heading whose text is unique within this UI Spec. Use the format `## Component: [ComponentName]` (or `### Component: [ComponentName]` when nested under a screen). - **Disambiguation rule**: When two components share a base name (e.g., the same `AlertCard` rendered as a banner variant and as an inline variant), append a parenthetical qualifier to make each heading unique: `Component: AlertCard (Banner variant)` and `Component: AlertCard (Inline variant)`. Verify uniqueness with a final pass: extract all `Component: ` headings, confirm zero duplicates @@ -122,7 +122,7 @@ When revising from review findings, resolve only the supplied defects within the ## Important Design Principles 1. **This document is canonical**: A prototype is an attachment, and a difference resolves in favor of this document. Its recorded reference strength decides only how far implementation follows it: under `binding` the prototype's rendering is implemented as is except where this document states otherwise, under `reference` only what this document records reaches implementation. -2. **Requirement-driven design**: Every interaction and state must trace back to the confirmed requirement context, preserving AC IDs when present. +2. **Requirement-driven design**: Every interaction and state must trace back to the requirement context, preserving AC IDs when present. 3. **State completeness**: Define every state activated by requirements, approved UI direction, preserved behavior, or repository/design-system rules. 4. **Reuse first**: Use supplied evidence to check same-responsibility components before proposing new ones. Document the decision. 5. **Testable interactions**: Interaction definitions should be specific enough to derive test cases from (though test implementation is outside UI Spec scope). diff --git a/dev-workflows-fullstack/skills/ai-development-guide/SKILL.md b/dev-workflows-fullstack/skills/ai-development-guide/SKILL.md index b3c9e991..b0fff492 100644 --- a/dev-workflows-fullstack/skills/ai-development-guide/SKILL.md +++ b/dev-workflows-fullstack/skills/ai-development-guide/SKILL.md @@ -8,11 +8,11 @@ description: Applies language-agnostic and backend technical decision criteria, ## Value-First Engineering Inspect until the evidence identifies the lowest-total-complexity solution that delivers the required user, operator, or maintainer value while keeping the system correct and maintainable. -- Resolve verified problems within confirmed scope or dependencies required for the outcome; report other findings with their owning boundary and evidence without expanding the active change. +- Resolve verified problems within scope or dependencies required for the outcome; report other findings with their owning boundary and evidence without expanding the active change. - Introduce capabilities, infrastructure, abstractions, or speculative edge-case handling when a current outcome, verified constraint, or evidence-backed material risk requires them. -- Treat behavior-preserving maintenance inside the confirmed responsibility as current maintainer value when repository evidence shows it reduces change ambiguity, duplicate ownership, defect risk, or future implementation and verification cost without expanding observable product scope. +- Treat behavior-preserving maintenance inside the assigned responsibility as current maintainer value when repository evidence shows it reduces change ambiguity, duplicate ownership, defect risk, or future implementation and verification cost without expanding observable product scope. -Judge total complexity across every activated surface: user decisions, settings, modes, concepts, outputs, persistent state, and implementation paths, together with their UX, runtime, implementation, testing, documentation, and maintenance cost. Compare only dimensions that differ between viable approaches. Prefer reuse or no new mechanism when it delivers the same confirmed value and proof at lower total complexity. +Judge total complexity across every activated surface: user decisions, settings, modes, concepts, outputs, persistent state, and implementation paths, together with their UX, runtime, implementation, testing, documentation, and maintenance cost. Compare only dimensions that differ between viable approaches. Prefer reuse or no new mechanism when it delivers the same required value and proof at lower total complexity. ## Technical Anti-patterns (Red Flag Patterns) @@ -140,7 +140,7 @@ Keep concrete implementations separate while their apparent similarity is accide **Avoidance Methods**: - Before implementation, always search for similar functionality (using domain, responsibility, configuration patterns as keywords) - Similar functionality found → Verify that its contract, lifecycle, and repository usage are representative; reuse or extend it when compatible, otherwise record why it is not a valid model -- Similar functionality is technical debt → Repair it when it blocks the current outcome, was caused by the current change, or lies in confirmed scope; otherwise report it separately. Create an ADR when the repair requires an architectural decision +- Similar functionality is technical debt → Repair it when it blocks the current outcome, was caused by the current change, or lies in scope; otherwise report it separately. Create an ADR when the repair requires an architectural decision - No similar functionality exists → Implement new functionality following existing design philosophy - Preserve the evidence for each reuse, extend, separate, or repair decision in the applicable implementation or design record - **Reference representativeness check**: When adopting a pattern or dependency from nearby code, inspect the changed area and enough representative consumers or siblings to establish compatibility; expand only when competing patterns or a shared/public contract can change the choice @@ -184,7 +184,7 @@ Follow repository-declared command composition or ordering when it exists. Other ### Scope Expansion - Apply implementation/edit instructions to the accepted outcome and its governing scope. -- Treat explicit restrictions and quantities ("one", "this file", "only X") in the governing request or confirmed outcome, desired-future requirements, and non-goals as hard boundaries; treat technical-artifact How as a correctable baseline when repository evidence invalidates it without changing those boundaries +- Treat explicit restrictions and quantities ("one", "this file", "only X") in the governing request or the outcome, desired-future requirements, and non-goals as hard boundaries; treat technical-artifact How as a correctable baseline when repository evidence invalidates it without changing those boundaries - Treat referenced or expected paths as investigation starting points unless the governing source explicitly makes them exclusive - Copy/move/mirror requests preserve content verbatim; edit content only when requested - Port/translation requests preserve intent and behavior; adapt only what the destination context requires diff --git a/dev-workflows-fullstack/skills/documentation-criteria/SKILL.md b/dev-workflows-fullstack/skills/documentation-criteria/SKILL.md index 7f745120..9c5500b3 100644 --- a/dev-workflows-fullstack/skills/documentation-criteria/SKILL.md +++ b/dev-workflows-fullstack/skills/documentation-criteria/SKILL.md @@ -13,11 +13,11 @@ Each document fixes one class of decision that the repository alone cannot suppl - **PRD** — Fixes the business outcome and the acceptance criteria later work traces to. Its AC IDs are the traceability keys that the Design Doc, UI Spec, and test selection reuse; without them each consumer re-derives requirements from prose and the link between a test and the value it protects is lost. Implementation details belong to the Design Doc, selection rationale to an ADR, phases and task breakdown to the Work Plan. Later design, review, and test selection treat its content as governing, so a precondition held outside the repository change, such as release execution or organizational approval, appears in it only when the user's wording raises it. -- **ADR** — Records one durable technical choice and the options it beat, so later work can tell a deliberate decision from an accident. Without it a future change either re-runs the same comparison or silently reverses it. `Accepted` records the currently selected means, not an obligation to retain it: when later evidence supports a smaller sufficient choice, update or supersede the decision while the confirmed outcome, desired-future requirements, and non-goals remain true. End-to-end implementation design belongs to the Design Doc, schedule and repository tasks to the Work Plan. +- **ADR** — Records one durable technical choice and the options it beat, so later work can tell a deliberate decision from an accident. Without it a future change either re-runs the same comparison or silently reverses it. `Accepted` records the currently selected means, not an obligation to retain it: when later evidence supports a smaller sufficient choice, update or supersede the decision while the outcome, desired-future requirements, and non-goals remain true. End-to-end implementation design belongs to the Design Doc, schedule and repository tasks to the Work Plan. - **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. 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. +- **Design Doc** — Records the complete implementation design for the scope of the requirements: 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 requirement that describes such work is met by designing the capability it uses. When repository evidence invalidates technical How while the 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. Each task is repository work the executor completes and verifies during implementation using repository artifacts and its own output. @@ -49,7 +49,7 @@ A qualifying ADR decision point sets the floor at Medium because it creates a du ## ADR Decision Filters -Apply the Choice filter, then the Durability filter, to each technical topic inside the confirmed implementation scope. Apply them independently from Structural Scale, and check existing ADRs first. +Apply the Choice filter, then the Durability filter, to each technical topic inside the implementation scope. Apply them independently from Structural Scale, and check existing ADRs first. 1. **Choice requires judgment** — current requirements, accepted decisions, and representative repository evidence support at least two credible, materially distinct options whose selection requires comparison. 2. **Decision is durable** — choosing among those options materially changes responsibility, dependency direction, a shared contract, persistence, a technology dependency, reversibility, or lifecycle cost that future work must preserve or understand. diff --git a/dev-workflows-fullstack/skills/documentation-criteria/references/adr-template.md b/dev-workflows-fullstack/skills/documentation-criteria/references/adr-template.md index debdb11b..da261f42 100644 --- a/dev-workflows-fullstack/skills/documentation-criteria/references/adr-template.md +++ b/dev-workflows-fullstack/skills/documentation-criteria/references/adr-template.md @@ -6,7 +6,7 @@ A created ADR starts at `Proposed` and advances `Proposed` → `Accepted` → `Deprecated`/`Superseded`/`Rejected`. -`Accepted` records the currently selected means, not an obligation to retain it. When later evidence supports a smaller sufficient choice, update or supersede this decision while the confirmed outcome, desired-future requirements, and non-goals remain true. +`Accepted` records the currently selected means, not an obligation to retain it. When later evidence supports a smaller sufficient choice, update or supersede this decision while the outcome, desired-future requirements, and non-goals remain true. ## Context @@ -16,7 +16,7 @@ A created ADR starts at `Proposed` and advances `Proposed` → `Accepted` → `D - **Question**: [The technical choice requiring comparison and selection] - **Why a decision exists**: [Evidence for at least two credible, materially distinct options] -- **Scope boundary**: [Confirmed requirement or existing contract this decision serves] +- **Scope boundary**: [Requirement or existing contract this decision serves] ## Decision @@ -39,12 +39,12 @@ A created ADR starts at `Proposed` and advances `Proposed` → `Accepted` → `D Compare credible, materially distinct options supported by current requirements and repository evidence. The evidence determines how many options exist, and relative evidence-backed cost is sufficient. Add a Mermaid option-comparison diagram only when the relationship between options stays unclear in the table below. -| Option | Confirmed product value | Repository fit | Total complexity | Maintainability | Material trade-offs | Reversibility | +| Option | Product value from the requirements | Repository fit | Total complexity | Maintainability | Material trade-offs | Reversibility | |--------|-------------------------|----------------|------------------|-----------------|---------------------|---------------| | [Option 1] | [value required now] | [fit and evidence] | [materially different activated surfaces and lifecycle costs] | [fit with ownership and representative patterns] | [trade-offs] | [cost and conditions to reverse] | | [Option 2] | [value required now] | [fit and evidence] | [materially different activated surfaces and lifecycle costs] | [fit with ownership and representative patterns] | [trade-offs] | [cost and conditions to reverse] | -**Selected**: [The smallest sufficient option whose total complexity is justified by confirmed product value and repository evidence] +**Selected**: [The smallest sufficient option whose total complexity is justified by product value from the requirements and repository evidence] ## Consequences 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 b75daa37..fc98ba14 100644 --- a/dev-workflows-fullstack/skills/documentation-criteria/references/design-template.md +++ b/dev-workflows-fullstack/skills/documentation-criteria/references/design-template.md @@ -27,7 +27,7 @@ Lists each external resource this feature depends on with its feature-specific i ### Requirement Convergence -Records exclusions **the user decided** at requirement time. Mark the first two bullets `N/A — covered by PRD [path]` when a PRD holds them, or the whole section `N/A — reverse-engineer/as-is document`. Open questions stay here in every case because design readiness depends on them. This section contains confirmed requirements and boundaries; evaluation requests, speculative ideas, and unselected mechanisms remain only in pre-confirmation convergence context. +Records exclusions **the user decided** at requirement time. Mark the first two bullets `N/A — covered by PRD [path]` when a PRD holds them, or the whole section `N/A — reverse-engineer/as-is document`. Open questions stay here in every case because design readiness depends on them. This section contains the user-selected requirements and boundaries; evaluation requests, speculative ideas, and unselected mechanisms remain only in active convergence context. - **Outcome**: [one observable result this change must produce] - **Non-Goals**: [capability the user excluded | None — user confirmed there are none] @@ -93,7 +93,7 @@ Keywords determine test type and reduce ambiguity. The rows below demonstrate EARS syntax only. Replace their domain, values, messages, and thresholds with requirements from the PRD or accepted requirement analysis; none is a default product requirement. -Keep the smallest representative set of observable behaviors that has a stable repository-verifiable pass/fail condition. Use repository-controlled contract/interface proof instead of a live external connection unless the confirmed requirement needs that boundary. Include a performance threshold only with a sourced target and reproducible benchmark, and exact visual positioning only with an approved visual contract and deterministic comparison. Implementation details remain outside ACs. +Keep the smallest representative set of observable behaviors that has a stable repository-verifiable pass/fail condition. Use repository-controlled contract/interface proof instead of a live external connection unless a requirement needs that boundary. Include a performance threshold only with a sourced target and reproducible benchmark, and exact visual positioning only with an approved visual contract and deterministic comparison. Implementation details remain outside ACs. ### [Functional Requirement 1] @@ -198,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, traced to its originating requirement, accepted decision, or repository rule or contract] +- **Subtraction result**: [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/documentation-criteria/references/prd-template.md b/dev-workflows-fullstack/skills/documentation-criteria/references/prd-template.md index d0fea276..1769f438 100644 --- a/dev-workflows-fullstack/skills/documentation-criteria/references/prd-template.md +++ b/dev-workflows-fullstack/skills/documentation-criteria/references/prd-template.md @@ -61,13 +61,13 @@ C4Context ### Future / Out of Scope -Record user-authored non-goals and any current exclusion required to make the MVP boundary executable. The table is limited to confirmed boundaries; evaluation requests, speculative ideas, and unselected possibilities remain only in pre-confirmation convergence context. Record `None — user confirmed there are none` when the user considered exclusions and found none. +Record user-authored non-goals and any current exclusion required to make the MVP boundary executable. The table is limited to these boundaries; evaluation requests, speculative ideas, and unselected possibilities remain only in active convergence context. Record `None — user confirmed there are none` when the user considered exclusions and found none. -Use `user` for a user-authored non-goal and `analysis` for a current exclusion required to make the confirmed MVP boundary executable. +Use `user` for a user-authored non-goal and `analysis` for a current exclusion required to make the MVP boundary executable. | Capability | Disposition | Origin | Reason | |---|---|---|---| -| [Confirmed non-goal or required current scope exclusion] | future / out-of-scope | user / analysis | [Governing scope reason] | +| [User-authored non-goal or required current scope exclusion] | future / out-of-scope | user / analysis | [Governing scope reason] | ## Non-Functional Requirements @@ -87,14 +87,14 @@ Use `user` for a user-authored non-goal and `analysis` for a current exclusion r - [Considerations for future scaling] ### Accessibility (when feature includes UI) -- Compliance standard (when established by an accepted organizational, legal, contractual, or confirmed product source): [standard] +- Compliance standard (when established by an accepted organizational, legal, contractual, or user-supplied product source): [standard] - Target assistive technologies: [Screen reader, keyboard operation, voice control, etc.] - Platform requirements: [e.g., app store review requirements] - Known constraints: [e.g., external library limitations] ## Success Criteria -State observable success for the confirmed outcome. Include only sourced quantitative/UI targets; in as-is documentation, distinguish observed measures from unknown business objectives. The examples below are optional shapes, not a required metric count. +State observable success for the outcome. Include only sourced quantitative/UI targets; in as-is documentation, distinguish observed measures from unknown business objectives. The examples below are optional shapes, not a required metric count. ### Quantitative Metrics 1. [Metric name]: [numeric target] measured by [method] within [timeframe] diff --git a/dev-workflows-fullstack/skills/documentation-criteria/references/ui-spec-template.md b/dev-workflows-fullstack/skills/documentation-criteria/references/ui-spec-template.md index 46180972..e96dc373 100644 --- a/dev-workflows-fullstack/skills/documentation-criteria/references/ui-spec-template.md +++ b/dev-workflows-fullstack/skills/documentation-criteria/references/ui-spec-template.md @@ -4,9 +4,9 @@ [Purpose and scope of this UI Specification in 2-3 sentences] -### Confirmed Requirement Context +### Requirement Context - PRD path: [docs/prd/xxx-prd.md | "N/A — based on requirements analysis output"] -- Feature scope: [Which confirmed requirements this UI Spec covers] +- Feature scope: [Which requirements this UI Spec covers] ### Design Source | Source | Path | Version | @@ -35,7 +35,7 @@ Lists each external resource this feature depends on with its feature-specific i ## AC Traceability (Prototype) -Map confirmed acceptance criteria to prototype references, preserving existing AC IDs when present. Skip this section if no prototype is provided. +Map acceptance criteria to prototype references, preserving existing AC IDs when present. Skip this section if no prototype is provided. | Criterion ID / Reference | Criterion Summary | Screen / State | Prototype Reference (element ID / path) | Adoption Decision | |-------|-----------|----------------|----------------------------------------|-------------------| @@ -76,7 +76,7 @@ Add a screen-transition or component-tree Mermaid diagram only when the material #### State x Display Matrix -The matrix contains one row for each state supported by confirmed requirements, approved UI direction, preserved behavior, or repository/design-system rules. +The matrix contains one row for each state supported by the requirements, approved UI direction, preserved behavior, or repository/design-system rules. | State | Trigger | Display | Interaction / Recovery | Evidence | |-------|---------|---------|------------------------|----------| diff --git a/dev-workflows-fullstack/skills/frontend-ai-guide/SKILL.md b/dev-workflows-fullstack/skills/frontend-ai-guide/SKILL.md index 416c9cfd..c4138e25 100644 --- a/dev-workflows-fullstack/skills/frontend-ai-guide/SKILL.md +++ b/dev-workflows-fullstack/skills/frontend-ai-guide/SKILL.md @@ -8,11 +8,11 @@ description: Applies React/TypeScript-specific technical decision criteria, anti ## Value-First Engineering Inspect until the evidence identifies the lowest-total-complexity solution that delivers the required user or maintainer value while keeping the UI correct and maintainable. -- Resolve verified problems within confirmed scope or dependencies required for the outcome; report other findings with their owning boundary and evidence without expanding the active change. +- Resolve verified problems within scope or dependencies required for the outcome; report other findings with their owning boundary and evidence without expanding the active change. - Introduce state, props, variants, abstractions, or speculative edge-case handling when a current outcome, verified constraint, or evidence-backed material risk requires them. -- Treat behavior-preserving maintenance inside the confirmed responsibility as current maintainer value when repository evidence shows it reduces change ambiguity, duplicate ownership, defect risk, or future implementation and verification cost without expanding observable product scope. +- Treat behavior-preserving maintenance inside the assigned responsibility as current maintainer value when repository evidence shows it reduces change ambiguity, duplicate ownership, defect risk, or future implementation and verification cost without expanding observable product scope. -Judge total complexity across every activated user decision, prop, state, variant, concept, output, persistent state, and component or hook path, together with its UX, runtime, implementation, testing, documentation, and maintenance cost. Compare only dimensions that differ between viable approaches. Prefer reuse or no new mechanism when it delivers the same confirmed value and proof at lower total complexity. +Judge total complexity across every activated user decision, prop, state, variant, concept, output, persistent state, and component or hook path, together with its UX, runtime, implementation, testing, documentation, and maintenance cost. Compare only dimensions that differ between viable approaches. Prefer reuse or no new mechanism when it delivers the same required value and proof at lower total complexity. ## Technical Anti-patterns (Red Flag Patterns) @@ -99,7 +99,7 @@ Keep concrete implementations separate while their similarity is accidental or t **Avoidance Methods**: - Before implementation, always search for similar functionality (using domain, responsibility, component patterns as keywords) - Similar functionality found → Verify that its props, lifecycle, design-system role, and repository usage are representative; reuse or extend it when compatible, otherwise record why it is not a valid model -- Similar functionality is technical debt → Repair it when it blocks the current outcome, was caused by the current change, or lies in confirmed scope; otherwise report it separately. Create an ADR when the repair requires an architectural decision +- Similar functionality is technical debt → Repair it when it blocks the current outcome, was caused by the current change, or lies in scope; otherwise report it separately. Create an ADR when the repair requires an architectural decision - No similar functionality exists → Implement new functionality following existing design philosophy - Preserve the evidence for each reuse, extend, separate, or repair decision in the applicable implementation or design record diff --git a/dev-workflows-fullstack/skills/implementation-approach/SKILL.md b/dev-workflows-fullstack/skills/implementation-approach/SKILL.md index 84ebdcff..46ee41dc 100644 --- a/dev-workflows-fullstack/skills/implementation-approach/SKILL.md +++ b/dev-workflows-fullstack/skills/implementation-approach/SKILL.md @@ -33,7 +33,7 @@ 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. 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 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. +4. **Subtraction Check**: Remove each proposed addition and re-test its governing condition. Retain it only when the outcome, a required boundary, or necessary proof becomes unmet at its origin (a 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. diff --git a/dev-workflows-fullstack/skills/recipe-add-integration-tests/SKILL.md b/dev-workflows-fullstack/skills/recipe-add-integration-tests/SKILL.md index 12b0542a..63b1d0cd 100644 --- a/dev-workflows-fullstack/skills/recipe-add-integration-tests/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-add-integration-tests/SKILL.md @@ -52,7 +52,7 @@ Invoke acceptance-test-generator using Agent tool: - `description`: "Generate test skeletons" - `design_docs`: Existing backend, frontend, or single-layer Design Doc paths from Step 1 - `ui_spec`: Existing UI Spec path when present -- `confirmed_requirement_context`: Approved PRD path or unchanged Design Doc Requirement Convergence record +- `requirement_context`: Approved PRD path or unchanged Design Doc Requirement Convergence record Follow subagents-orchestration-guide HC-06 to verify generated paths and coverage of empty lanes before Step 3. diff --git a/dev-workflows-fullstack/skills/recipe-design/SKILL.md b/dev-workflows-fullstack/skills/recipe-design/SKILL.md index 9a963ef3..8f698021 100644 --- a/dev-workflows-fullstack/skills/recipe-design/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-design/SKILL.md @@ -37,9 +37,9 @@ At each `Invoke` below, build the Agent prompt as a mechanical extraction: copy ## Step 1: Select the Governing Requirement Source -Use the approved PRD path when one exists. Otherwise use the confirmed requirements verbatim. +Use the approved PRD path when one exists. Otherwise use the requirements verbatim. -Set `confirmed_requirement_context` to the approved PRD path exactly. Only when no approved PRD exists, use the orchestrator-confirmed convergence record unchanged. +Set `requirement_context` to the approved PRD path exactly. Only when no approved PRD exists, use the orchestrator's convergence record unchanged. ## Step 2: Collect Decision Material @@ -52,10 +52,10 @@ prd_path: [approved PRD path] or, when no approved PRD exists: ```text -requirements: [confirmed requirements verbatim] +requirements: [requirements verbatim] ``` -Invoke once for the complete confirmed scope. Require one valid JSON result and let the analyzer discover affected paths, responsibility boundaries, and cross-layer contracts. Treat its focus areas as existing-behavior safeguards, not as new requirements. +Invoke once for the complete scope. Require one valid JSON result and let the analyzer discover affected paths, responsibility boundaries, and cross-layer contracts. Treat its focus areas as existing-behavior safeguards, not as new requirements. This independent discovery keeps scope and option convergence grounded in repository evidence rather than the orchestrator's unverified implementation hypothesis. @@ -69,21 +69,21 @@ Determine Structural Scale from outcomes and responsibility boundaries. File cou Resolve `decisionMaterials.candidateDecisionPoints` against the governing requirement source, applicable `simplifications`, `reuse`, and `invalidations`. Remove a point when that evidence already converges on one sufficient approach. For each remaining item, apply documentation-criteria filters in order: -1. Choice requires judgment between at least two credible, materially distinct options inside confirmed scope. +1. Choice requires judgment between at least two credible, materially distinct options inside the scope of the requirements. 2. The selection has durable material impact. Record every passing item as `adrDecisionPoints`; an empty list routes directly to the Design Doc. ADR creation is limited to items that pass both filters. Present the requirement-convergence Scope Confirmation. Place target responsibilities with their strongest file evidence, applicable simplifications with their conditions, and each qualifying ADR decision point with its filter evidence or `none` under **Decision evidence**; place Structural Scale with its boundary rationale and the recommended document route under **Workflow**. -Offer proceed, or correct scope and re-run analysis. Ask a question only when its answer can change a convergence field, the confirmed outcome, or scope. Continue only when every convergence field is `ready` or `weak-but-explicit`. `[Stop: Scope confirmation]`. +Offer proceed, or correct scope and re-run analysis. Ask a question only when its answer can change a convergence field, the outcome, or scope. Continue only when every convergence field is `ready` or `weak-but-explicit`. `[Stop: Scope confirmation]`. ## Step 4: Create and Approve an ADR Batch When Needed When `adrDecisionPoints` is non-empty: -1. Invoke `dev-workflows-fullstack:technical-designer` once with exact inputs: `document_to_create: ADRBatch`; `confirmed_requirement_context`; `decision_points` as the ordered `adrDecisionPoints` confirmed in Step 3, unchanged; and `decision_materials` as the corresponding objects from Step 2 `decisionMaterials.candidateDecisionPoints`, copied unchanged in that order. -2. Invoke `dev-workflows-fullstack:document-reviewer` once with exact inputs: `doc_type: ADRBatch`, `targets: [all returned paths]`, and `confirmed_requirement_context`. +1. Invoke `dev-workflows-fullstack:technical-designer` once with exact inputs: `document_to_create: ADRBatch`; `requirement_context`; `decision_points` as the ordered `adrDecisionPoints` from Step 3, unchanged; and `decision_materials` as the corresponding objects from Step 2 `decisionMaterials.candidateDecisionPoints`, copied unchanged in that order. +2. Invoke `dev-workflows-fullstack:document-reviewer` once with exact inputs: `doc_type: ADRBatch`, `targets: [all returned paths]`, and `requirement_context`. 3. Route the reviewer verdict first: `pass` proceeds with `issues: []`; `needs_revision` applies Review Resolution, updates one ADR per path serially, and re-reviews the complete batch; `rejected` resolves the governing-source conflict before another review. 4. Present one batch decision after Review Resolution converges, including a decline-only result; unresolved governing-source conflicts still block approval. `[Stop: ADR batch approval]`. 5. After user approval, update each ADR status to `Accepted` and verify the changed status. @@ -95,7 +95,7 @@ Create the complete MVP implementation design from reviewed artifacts and unchan Invoke `dev-workflows-fullstack:technical-designer` with exactly: - `document_to_create: DesignDoc`; -- `confirmed_requirement_context`; +- `requirement_context`; - `structural_scale`; - `adr_paths: [accepted paths or []]`; - `codebase_analysis: [complete Step 2 JSON unchanged]`. @@ -112,11 +112,11 @@ Apply Review Resolution to every discrepancy before document review. Send only ` ## Step 7: Review and Approve -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. +Invoke `dev-workflows-fullstack:document-reviewer` with exact inputs: `doc_type: DesignDoc`, `target`, `review_context: creation`, the original user requirements verbatim as `requirements_verbatim`, `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 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. +- `rejected`: resolve technical governing-source conflicts through Review Resolution; ask the user only when the 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. @@ -124,7 +124,7 @@ Present the Design Doc, accepted ADR paths, resolved limitations/declines, and d ## Completion Criteria -- Scope and Structural Scale were confirmed from outcomes and responsibility boundaries. +- Scope and Structural Scale were determined from outcomes and responsibility boundaries. - ADRs exist only for decision points passing both filters, and the complete batch received one review and approval. - A Design Doc exists regardless of whether ADRs were needed. - Applicable existing-behavior, contract, assumption, equivalence, and verification safeguards reached the Design Doc. diff --git a/dev-workflows-fullstack/skills/recipe-diagnose/SKILL.md b/dev-workflows-fullstack/skills/recipe-diagnose/SKILL.md index 687bd7f1..eb3e1ae6 100644 --- a/dev-workflows-fullstack/skills/recipe-diagnose/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-diagnose/SKILL.md @@ -135,7 +135,7 @@ Continue investigation while an available action can advance a material gap. Com ### Step 5: Solution Boundary -After coverage is closed, pass the complete verified cause set to solver. Ownership, contract, and technical design corrections are ordinary solution candidates when they preserve the confirmed outcome, desired-future requirements, and non-goals; detecting a design gap does not create a user decision. If evidence shows those value boundaries cannot all remain true, or a proposed remedy requires authorization for an irreversible external action, report that exact boundary with the solution evidence instead of inventing a choice. +After coverage is closed, pass the complete verified cause set to solver. Ownership, contract, and technical design corrections are ordinary solution candidates when they preserve the outcome, desired-future requirements, and non-goals; detecting a design gap does not create a user decision. If evidence shows those value boundaries cannot all remain true, or a proposed remedy requires authorization for an irreversible external action, report that exact boundary with the solution evidence instead of inventing a choice. ### Step 6: Solution Derivation (solver) diff --git a/dev-workflows-fullstack/skills/recipe-front-adjust/SKILL.md b/dev-workflows-fullstack/skills/recipe-front-adjust/SKILL.md index ec9437c8..59748bcf 100644 --- a/dev-workflows-fullstack/skills/recipe-front-adjust/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-front-adjust/SKILL.md @@ -21,7 +21,7 @@ Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or g ## Execution Gate -Complete Steps 1-7 in order for the confirmed adjustment outcome. Advance only through the current step's stated evidence, quality result, or user stop; skip work only when its stated condition is false. Report completion after every applicable Completion Criterion and retained-limitation retry is satisfied. +Complete Steps 1-7 in order for the adjustment outcome. Advance only through the current step's stated evidence, quality result, or user stop; skip work only when its stated condition is false. Report completion after every applicable Completion Criterion and retained-limitation retry is satisfied. ## Workflow Overview @@ -49,9 +49,9 @@ Adjustment request → conditional external resource evidence - Structural boundary judgment via documentation-criteria - Adjustment edits and verification against the design source (run in this session) - Quality verification via quality-fixer-frontend -- Commit the confirmed adjustment outcome +- Commit the adjustment outcome -**Responsibility Boundary**: This skill completes when the confirmed adjustment is committed after its quality cycle and any retained proof limitation receives its final retry. Adjustment work is end-to-end within this recipe; parent session owns edits, verification loops, quality-result routing, and commits. +**Responsibility Boundary**: This skill completes when the adjustment is committed after its quality cycle and any retained proof limitation receives its final retry. Adjustment work is end-to-end within this recipe; parent session owns edits, verification loops, quality-result routing, and commits. **Escalation Boundary**: Escalate to the full frontend design phase when the request crosses a responsibility or approved UI boundary, requires a complete Design Doc, or contains a technical choice that passes documentation-criteria's Choice and Durability filters. @@ -73,7 +73,7 @@ Inspect the named or current UI and the smallest sufficient repository evidence ### Step 3: Scale Judgment 1. Read the candidate write set from Step 2. -2. Apply Structural Scale to the confirmed outcome and responsibility boundary. Use write-set count as supporting evidence only: +2. Apply Structural Scale to the adjustment outcome and responsibility boundary. Use write-set count as supporting evidence only: - **0 files**: The adjustment request did not map to any existing file. Escalate to the user with the message "No write target identified from the adjustment request. Please clarify which component(s) should change, or run the full frontend design phase if this is a new feature." Stop this recipe. - **Direct adjustment**: One coherent UI outcome follows existing component, state, interaction, and verification patterns inside one responsibility boundary. Continue directly to adjustment context even when generated or tightly coupled files increase the count. - **Design required**: The change crosses a responsibility or approved UI contract, coordinates independently valuable outcomes, or needs a durable technical choice between credible alternatives. Escalate to the full frontend design phase. @@ -96,12 +96,12 @@ Execute Skill: typescript-rules before planning or applying adjustment edits. Execute Skill: implementation-approach before planning or applying adjustment edits. Execute Skill: testing-principles before adding or changing tests. -Implement the confirmed adjustment outcome across its affected files: -1. **Plan the edit** from the confirmed adjustment context and relevant external resource (e.g., design origin's fetched_summary). +Implement the adjustment outcome across its affected files: +1. **Plan the edit** from the Step 4 adjustment context and relevant external resource (e.g., design origin's fetched_summary). 2. **Apply the edit** using Edit / Write / MultiEdit on the affected files. -3. **Verify the confirmed target** using applicable repository/UI Spec evidence and any external source selected in Step 1. Reuse its available access or verification method; compare rendering, interaction or tokens only where they determine the requested adjustment. +3. **Verify the adjustment target** using applicable repository/UI Spec evidence and any external source selected in Step 1. Reuse its available access or verification method; compare rendering, interaction or tokens only where they determine the requested adjustment. 4. **Refine and re-verify** until the adjustment matches the design source, or matches the user-confirmed adjustment target when no separate design source exists. -5. When the complete adjustment matches the confirmed target, proceed to Step 6. +5. When the complete adjustment matches the adjustment target, proceed to Step 6. When required proof is unavailable, use sufficient file-based or other available evidence; retain an exact proof limitation otherwise. Ask for manual confirmation only when a user-owned interpretation is needed to determine the adjustment target. @@ -109,21 +109,21 @@ When required proof is unavailable, use sufficient file-based or other available - Invoke **quality-fixer-frontend** using Agent tool - `subagent_type: "dev-workflows-fullstack:quality-fixer-frontend"` - - `description: "Quality verification for confirmed adjustment"` - - `direct_scope`: Copy the confirmed adjustment request and preserved visible behavior from Step 4 unchanged. + - `description: "Quality verification for adjustment"` + - `direct_scope`: Copy the adjustment request and preserved visible behavior from Step 4 unchanged. - `governing_sources`: Pass the existing UI and design source references used for the adjustment unchanged. - - `observable_verification`: Pass the confirmed adjustment request from Step 4 and applicable acceptance criteria from the governing sources unchanged. + - `observable_verification`: Pass the adjustment request from Step 4 and applicable acceptance criteria from the governing sources unchanged. - Pass `qualityCommand` when available (caller first, otherwise current task). - Route the quality-fixer-frontend response by `status`: - `pass` → proceed to Step 7 - - `stub_detected` → return to Step 5 to complete the confirmed adjustment, then re-invoke quality-fixer-frontend + - `stub_detected` → return to Step 5 to complete the adjustment, then re-invoke quality-fixer-frontend - `verification_incomplete` → retain the complete result for final retry and proceed to Step 7 - `blocked` → Apply subagents-orchestration-guide Specialist Result Acceptance using the result's semantic evidence, changed files, and repository state ### Step 7: Commit -Before committing, use repository state at the commit boundary as the primary evidence and account for every actual change by mapping it to the confirmed adjustment, preserved pattern, or a necessary dependency, test, or generated artifact. Every required change is ready for the adjustment commit, accidental changes introduced during the adjustment are removed, and existing worktree changes unrelated to the confirmed adjustment remain intact. +Before committing, use repository state at the commit boundary as the primary evidence and account for every actual change by mapping it to the adjustment, preserved pattern, or a necessary dependency, test, or generated artifact. Every required change is ready for the adjustment commit, accidental changes introduced during the adjustment are removed, and existing worktree changes unrelated to the adjustment remain intact. -Commit the confirmed adjustment after `pass` or `verification_incomplete`. For the latter, derive and append one `Verification-Limitation: ` and `Verification-Affected: ` trailer pair per retained limitation. +Commit the adjustment after `pass` or `verification_incomplete`. For the latter, derive and append one `Verification-Limitation: ` and `Verification-Affected: ` trailer pair per retained limitation. On continuation, reconstruct retained limitations from the verification trailers on commits already completed for this request. After the adjustment is committed, retry each retained verification limitation once with quality-fixer-frontend. When the retry returns `pass`, remove that limitation from retained state. Commit any resulting fixes through Steps 6→7, and include only a repeated limitation in the completion report. @@ -133,9 +133,9 @@ On continuation, reconstruct retained limitations from the verification trailers - [ ] UI Spec applicability and the candidate write set were determined from the requested UI and sufficient repository evidence - [ ] Structural boundary judgment applied; changes requiring complete design or a qualifying durable decision escalated - [ ] Adjustment context, including the affected files, was presented and confirmed once -- [ ] The confirmed adjustment outcome is implemented; each declared verification mechanism ran, received manual confirmation where required, or retained its exact proof limitation after final retry -- [ ] The confirmed adjustment completed quality-fixer-frontend before commit; retained proof limitations were retried and reported -- [ ] The confirmed adjustment is committed +- [ ] The adjustment outcome is implemented; each declared verification mechanism ran, received manual confirmation where required, or retained its exact proof limitation after final retry +- [ ] The adjustment completed quality-fixer-frontend before commit; retained proof limitations were retried and reported +- [ ] The adjustment is committed ## Output Example diff --git a/dev-workflows-fullstack/skills/recipe-front-design/SKILL.md b/dev-workflows-fullstack/skills/recipe-front-design/SKILL.md index 7b86692e..11753534 100644 --- a/dev-workflows-fullstack/skills/recipe-front-design/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-front-design/SKILL.md @@ -39,13 +39,13 @@ At each Agent invocation below, build the prompt as a mechanical extraction: cop ## Step 1: Select the Governing Requirement Source -Use the approved PRD path when one exists. Otherwise use the confirmed requirements verbatim. +Use the approved PRD path when one exists. Otherwise use the requirements verbatim. -Set `confirmed_requirement_context` to the approved PRD path exactly. Only when no approved PRD exists, use the orchestrator-confirmed convergence record unchanged. +Set `requirement_context` to the approved PRD path exactly. Only when no approved PRD exists, use the orchestrator's convergence record unchanged. ## Step 2: Collect Repository Decision Material -Invoke `dev-workflows-fullstack:codebase-analyzer` once for the complete confirmed scope with exactly `prd_path: [approved PRD path]`, or `requirements: [confirmed requirements verbatim]` when no approved PRD exists. +Invoke `dev-workflows-fullstack:codebase-analyzer` once for the complete scope with exactly `prd_path: [approved PRD path]`, or `requirements: [requirements verbatim]` when no approved PRD exists. Require one valid JSON result and let the analyzer discover affected paths, responsibility boundaries, and cross-layer contracts. Treat `focusAreas` as existing-behavior safeguards rather than requirements. @@ -68,7 +68,7 @@ prd_path: [approved PRD path] or, when no approved PRD exists: ```text -requirements: [confirmed requirements verbatim] +requirements: [requirements verbatim] ``` Add only an existing `ui_spec_path`, a decision-relevant `prototype_path`, and selected `external_resource_refs` or `[]`. @@ -87,7 +87,7 @@ Judge all four convergence fields. Assign `cost` from Step 2 structural evidence Determine Structural Scale from outcomes and responsibility boundaries; file count is supporting evidence only. Resolve candidate decision points against the governing source, applicable code/UI `simplifications`, `reuse`, and `invalidations`; applicable UI facts may support or contradict the remaining options. Apply documentation-criteria Choice and Durability filters only after this convergence and record passing points as `adrDecisionPoints`; an empty list is valid. -Present the requirement-convergence Scope Confirmation. Place affected responsibilities, applicable simplifications with their conditions, and qualifying ADR points or `none` under **Decision evidence**; place Structural Scale, UI Spec applicability, and the recommended document route under **Workflow**. Offer proceed, or correct and re-run. Ask a question only when its answer can change a convergence field, the confirmed outcome, or scope. Continue only when every convergence field is `ready` or `weak-but-explicit`. `[Stop: Scope confirmation]`. +Present the requirement-convergence Scope Confirmation. Place affected responsibilities, applicable simplifications with their conditions, and qualifying ADR points or `none` under **Decision evidence**; place Structural Scale, UI Spec applicability, and the recommended document route under **Workflow**. Offer proceed, or correct and re-run. Ask a question only when its answer can change a convergence field, the outcome, or scope. Continue only when every convergence field is `ready` or `weak-but-explicit`. `[Stop: Scope confirmation]`. ## Step 5: Create and Approve the UI Spec @@ -96,7 +96,7 @@ Run this step only when Step 3 determined that a UI Spec applies. Invoke `dev-workflows-fullstack:ui-spec-designer` with exact inputs: ```text -confirmed_requirement_context: [the value fixed in Step 1] +requirement_context: [the value set in Step 1] ui_analysis: [complete Step 3 UI analyzer JSON unchanged] codebase_analysis: [complete Step 2 codebase-analyzer JSON unchanged] prototype_path: [decision-relevant path from Step 3 exactly, or absent] @@ -110,8 +110,8 @@ Invoke `dev-workflows-fullstack:document-reviewer` with exact inputs: `doc_type: When `adrDecisionPoints` is non-empty: -1. Route shared/backend-owned points to technical-designer first, then frontend-owned points to technical-designer-frontend. Invoke each owner with exact inputs: `document_to_create: ADRBatch`; `confirmed_requirement_context`; its ordered `decision_points` confirmed in Step 4, unchanged; `decision_materials` as the corresponding Step 2 `decisionMaterials.candidateDecisionPoints` objects copied unchanged in that order; and `ui_spec_path` only when the approved UI Spec constrains that owner's decision. Run owner batches serially so each batch allocates ADR numbers after the preceding batch exists. -2. Collect all returned paths and invoke `dev-workflows-fullstack:document-reviewer` once with exact inputs: `doc_type: ADRBatch`, `targets: [all paths]`, and `confirmed_requirement_context`. The reviewer follows the approved UI Spec cited by the ADRs when it can change the decision review. +1. Route shared/backend-owned points to technical-designer first, then frontend-owned points to technical-designer-frontend. Invoke each owner with exact inputs: `document_to_create: ADRBatch`; `requirement_context`; its ordered `decision_points` from Step 4, unchanged; `decision_materials` as the corresponding Step 2 `decisionMaterials.candidateDecisionPoints` objects copied unchanged in that order; and `ui_spec_path` only when the approved UI Spec constrains that owner's decision. Run owner batches serially so each batch allocates ADR numbers after the preceding batch exists. +2. Collect all returned paths and invoke `dev-workflows-fullstack:document-reviewer` once with exact inputs: `doc_type: ADRBatch`, `targets: [all paths]`, and `requirement_context`. The reviewer follows the approved UI Spec cited by the ADRs when it can change the decision review. 3. Route the reviewer verdict first: `pass` proceeds with `issues: []`; `needs_revision` applies Review Resolution, updates one ADR per path serially, and re-reviews the complete batch; `rejected` resolves the governing-source conflict before another review. 4. Present one batch decision after Review Resolution converges, including a decline-only result; unresolved governing-source conflicts still block approval. `[Stop: ADR batch approval]`. 5. After user approval, set every ADR status to `Accepted` and verify the status update. @@ -123,7 +123,7 @@ Create the complete frontend MVP implementation design from reviewed artifacts a Invoke `dev-workflows-fullstack:technical-designer-frontend` with exactly: - `document_to_create: DesignDoc`; -- `confirmed_requirement_context`; +- `requirement_context`; - `structural_scale`; - applicable approved `ui_spec_path` exactly and selected external-resource reference records unchanged; - `adr_paths: [accepted paths or []]`; @@ -140,11 +140,11 @@ Keep verifier observations unchanged so corrections remain traceable to observed Invoke `dev-workflows-fullstack:code-verifier` with `doc_type: design-doc` and `document_path` as the Design Doc path returned by technical-designer-frontend, unchanged, to verify current premises and feasibility while treating planned behavior as intent. Apply Review Resolution before document review; send applied findings to a fresh technical-designer-frontend update invocation with `Operation Mode: update`, `Existing Document: [Design Doc path]`, and `correction_findings: [complete findings unchanged except for their dispositions]`. The designer applies its review-triggered bounded self-verification gate for an unverified decision-changing premise; this fresh designer is the sole correction specialist and selects the evidence route. Rerun verification after an applied correction with the previous complete result, dispositions, and correction diff or paths as `prior_feedback`, then build one `verification_evidence` object from the latest result. Continue at the Review Resolution convergence condition. -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. +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 `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, 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. +- `rejected`: resolve technical governing-source conflicts through Review Resolution; ask the user only when the 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. @@ -153,7 +153,7 @@ Present the applicable UI Spec, Design Doc, accepted ADR paths, resolved limitat ## Completion Criteria - External and prototype evidence was requested only when it controlled a current decision. -- Scope and Structural Scale were confirmed from outcomes and responsibility boundaries. +- Scope and Structural Scale were determined from outcomes and responsibility boundaries. - ADRs exist only for points passing both filters, and the batch received one review and approval. - An applicable UI Spec and a complete frontend Design Doc exist regardless of ADR need. - Applicable existing UI behavior, contracts, assumptions, states, equivalence, and verification safeguards reached the Design Doc. diff --git a/dev-workflows-fullstack/skills/recipe-front-plan/SKILL.md b/dev-workflows-fullstack/skills/recipe-front-plan/SKILL.md index a27fbbf1..7646e8fe 100644 --- a/dev-workflows-fullstack/skills/recipe-front-plan/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-front-plan/SKILL.md @@ -58,7 +58,7 @@ Follow the planning process below: - `description`: "Test skeleton generation" - `design_docs: [Design Doc path]` - `ui_spec: [UI Spec path]` when one exists - - `confirmed_requirement_context`: approved PRD path named by the Design Doc, or its unchanged Requirement Convergence record when no PRD exists + - `requirement_context`: approved PRD path named by the Design Doc, or its unchanged Requirement Convergence record when no PRD exists - Follow subagents-orchestration-guide HC-06 for generated-path and empty-lane coverage checks - Pass every non-null generated skeleton path to work-planner; treat an evidence-backed empty lane as complete for that lane and continue to work-planner @@ -81,7 +81,7 @@ Invoke document-reviewer to review the work plan: ### Step 5: Present for Approval - Present the reviewed work plan to the user for batch approval. If the user requests changes, re-invoke work-planner with the user's requested changes verbatim and re-run Step 4. -- Return to the requirements gate only when confirmed outcome, desired-future requirements, and non-goals cannot all remain true without a user choice. +- Return to the requirements gate only when the outcome, desired-future requirements, and non-goals cannot all remain true without a user choice. ## Response at Completion **Recommended**: End with the following standard response after plan content approval diff --git a/dev-workflows-fullstack/skills/recipe-front-review/SKILL.md b/dev-workflows-fullstack/skills/recipe-front-review/SKILL.md index e95801f8..4cc8f23e 100644 --- a/dev-workflows-fullstack/skills/recipe-front-review/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-front-review/SKILL.md @@ -98,7 +98,7 @@ Approve the proposed changes: This review command authorizes analysis; use AskUserQuestion to obtain separate implementation authority. The batch option is **"approve all proposed `apply` routes"** and its scope consists exclusively of those routes. When the approved change set is empty, proceed directly to Step 9. -Pass approved findings, routes, covered files/sections, and any stated total size budget to update or fix agents. Before re-validation, map every diff hunk to an approved finding or required consistency update. Remove accidental unmapped changes; when a necessary change would alter a confirmed value boundary or explicit size constraint, return to Requirement Change Detection. +Pass approved findings, routes, covered files/sections, and any stated total size budget to update or fix agents. Before re-validation, map every diff hunk to an approved finding or required consistency update. Remove accidental unmapped changes; when a necessary change would alter a value boundary or explicit size constraint, return to Requirement Change Detection. ### Step 5: Design-Side Update @@ -130,9 +130,9 @@ Run this step only when the user routed at least one finding to `d`. When no `d` Invoke task-executor-frontend using Agent tool: - `subagent_type`: "dev-workflows-fullstack:task-executor-frontend" - `description`: "Execute review fixes" -- `direct_scope`: Apply the approved frontend corrections within the confirmed review scope and stated total size budget +- `direct_scope`: Apply the approved frontend corrections within the review scope and stated total size budget - `governing_sources`: The reviewed Design Doc, applicable UI Spec, and accepted requirement or ADR paths -- `target_paths`: The implementation and test paths confirmed for the approved code-side routes +- `target_paths`: The implementation and test paths identified for the approved code-side routes - `observable_verification`: The focused UI behavior tests or observable contract checks named by the findings and governing sources pass - `correction_findings`: Complete reviewer finding objects verbatim, with only their orchestrator dispositions added diff --git a/dev-workflows-fullstack/skills/recipe-fullstack-implement/SKILL.md b/dev-workflows-fullstack/skills/recipe-fullstack-implement/SKILL.md index 16ee3111..fc0b46a6 100644 --- a/dev-workflows-fullstack/skills/recipe-fullstack-implement/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-fullstack-implement/SKILL.md @@ -76,7 +76,7 @@ After Structural Scale is determined, follow only that scale's applicable path. Execute Skill: requirement-convergence before running the hearing protocol. -Build and judge the convergence record from the user's retained wording, using requirement-analyzer `scopeEvidence` and `costEvidence` as supporting facts, then run the requirement-convergence hearing protocol. After the requirements are confirmed, apply the subagents-orchestration-guide Small evidence gate before assigning the final Structural Scale; when the gate is unresolved, invoke codebase-analyzer before routing. +Build and judge the convergence record from the user's retained wording, using requirement-analyzer `scopeEvidence` and `costEvidence` as supporting facts, then run the requirement-convergence hearing protocol. After the user answers the requirements stop, apply the subagents-orchestration-guide Small evidence gate before assigning the final Structural Scale; when the gate is unresolved, invoke codebase-analyzer before routing. When user responds to questions: - Update the orchestrator-owned convergence record from the answer, then update the Structural Scale judgment through the Small evidence gate. diff --git a/dev-workflows-fullstack/skills/recipe-implement/SKILL.md b/dev-workflows-fullstack/skills/recipe-implement/SKILL.md index 30c48668..591b4773 100644 --- a/dev-workflows-fullstack/skills/recipe-implement/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-implement/SKILL.md @@ -26,7 +26,7 @@ Before the first finding disposition, read `references/review-resolution.md` fro - Execute one step at a time in the defined flow (Large/Medium/Small scale) - When flow specifies "Execute document-reviewer" → Execute it immediately - **Stop at every `[Stop: ...]` marker** → Wait for explicit user confirmation before proceeding -3. **Enter autonomous mode** after confirmed Small requirements or Medium/Large batch approval +3. **Enter autonomous mode** after user confirmation at the Requirements stop for Small, or Medium/Large batch approval At each Agent invocation below, build the prompt as a mechanical extraction: copy the named source values into the exact fields, apply only the declared serialization, then invoke immediately. @@ -63,7 +63,7 @@ When continuing existing flow, verify: Execute Skill: requirement-convergence before running the hearing protocol. -Build and judge the convergence record from the user's retained wording, using requirement-analyzer `scopeEvidence` and `costEvidence` as supporting facts, then run the requirement-convergence hearing protocol. After the requirements are confirmed, apply the subagents-orchestration-guide Small evidence gate before assigning the final Structural Scale; when the gate is unresolved, invoke codebase-analyzer before routing. +Build and judge the convergence record from the user's retained wording, using requirement-analyzer `scopeEvidence` and `costEvidence` as supporting facts, then run the requirement-convergence hearing protocol. After the user answers the requirements stop, apply the subagents-orchestration-guide Small evidence gate before assigning the final Structural Scale; when the gate is unresolved, invoke codebase-analyzer before routing. When user responds to questions: - Update the orchestrator-owned convergence record from the answer, then update the Structural Scale judgment through the Small evidence gate. @@ -97,7 +97,7 @@ After Structural Scale is determined, follow only that scale's applicable path. ### Task Execution Quality Cycle (4-Step Cycle per Task) **Per-task cycle** (complete each task before starting next): -1. **Agent tool** (subagent_type: "dev-workflows-fullstack:task-executor") → Record the current HEAD as `diffBase`; pass `task_file: [path]` when one exists, otherwise pass `direct_scope` as the confirmed outcome and exclusions, `governing_sources`, `target_paths`, and `observable_verification` +1. **Agent tool** (subagent_type: "dev-workflows-fullstack:task-executor") → Record the current HEAD as `diffBase`; pass `task_file: [path]` when one exists, otherwise pass `direct_scope` as the convergence record's outcome and exclusions, `governing_sources`, `target_paths`, and `observable_verification` 2. Check task-executor response: - `status: escalation_needed` or `blocked` → Apply subagents-orchestration-guide Specialist Result Acceptance - `requiresTestReview` is `true` → Identify the changed integration/E2E test files in the current changes and invoke integration-test-reviewer with them as `changedTestFiles`, plus `diffBase`, optional `taskFile`, prompt-only claims, and `mutationEvidence` diff --git a/dev-workflows-fullstack/skills/recipe-plan/SKILL.md b/dev-workflows-fullstack/skills/recipe-plan/SKILL.md index 21031993..9379a959 100644 --- a/dev-workflows-fullstack/skills/recipe-plan/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-plan/SKILL.md @@ -52,7 +52,7 @@ Follow the planning process below: - Report when none exist; when multiple exist, present them for selection ### Step 2: Test Skeleton Generation - - Invoke acceptance-test-generator with `design_docs: [selected Design Doc path]` and `confirmed_requirement_context` as the approved PRD path named by its Requirement Convergence section, or that section's unchanged convergence record when no PRD exists + - Invoke acceptance-test-generator with `design_docs: [selected Design Doc path]` and `requirement_context` as the approved PRD path named by its Requirement Convergence section, or that section's unchanged convergence record when no PRD exists - Follow subagents-orchestration-guide HC-06 for generated-path and empty-lane coverage checks - Pass every non-null generated skeleton path to the next process; treat an evidence-backed empty lane as complete for that lane and continue to the next process @@ -74,7 +74,7 @@ Invoke document-reviewer to review the work plan: ### Step 5: Present for Approval - Present the reviewed work plan to the user for batch approval. If the user requests changes, re-invoke work-planner with the user's requested changes verbatim and re-run Step 4. -- Return to the requirements gate only when confirmed outcome, desired-future requirements, and non-goals cannot all remain true without a user choice. +- Return to the requirements gate only when the outcome, desired-future requirements, and non-goals cannot all remain true without a user choice. ## Response at Completion diff --git a/dev-workflows-fullstack/skills/recipe-review/SKILL.md b/dev-workflows-fullstack/skills/recipe-review/SKILL.md index 21b8410a..f7b09f04 100644 --- a/dev-workflows-fullstack/skills/recipe-review/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-review/SKILL.md @@ -98,7 +98,7 @@ Approve the proposed changes: This review command authorizes analysis; use AskUserQuestion to obtain separate implementation authority. The batch option is **"approve all proposed `apply` routes"** and its scope consists exclusively of those routes. When the approved change set is empty, proceed directly to Step 9. -Pass approved findings, routes, covered files/sections, and any stated total size budget to update or fix agents. Before re-validation, map every diff hunk to an approved finding or required consistency update. Remove accidental unmapped changes; when a necessary change would alter a confirmed value boundary or explicit size constraint, return to Requirement Change Detection. +Pass approved findings, routes, covered files/sections, and any stated total size budget to update or fix agents. Before re-validation, map every diff hunk to an approved finding or required consistency update. Remove accidental unmapped changes; when a necessary change would alter a value boundary or explicit size constraint, return to Requirement Change Detection. ### Step 5: Design-Side Update @@ -130,9 +130,9 @@ Run this step only when the user routed at least one finding to `d`. When no `d` Invoke task-executor using Agent tool: - `subagent_type`: "dev-workflows-fullstack:task-executor" - `description`: "Execute review fixes" -- `direct_scope`: Apply the approved code-side corrections within the confirmed review scope and stated total size budget +- `direct_scope`: Apply the approved code-side corrections within the review scope and stated total size budget - `governing_sources`: The reviewed Design Doc and accepted requirement or ADR paths -- `target_paths`: The implementation and test paths confirmed for the approved code-side routes +- `target_paths`: The implementation and test paths identified for the approved code-side routes - `observable_verification`: The focused tests or observable contract checks named by the findings and governing sources pass - `correction_findings`: Complete reviewer finding objects verbatim, with only their orchestrator dispositions added diff --git a/dev-workflows-fullstack/skills/requirement-convergence/SKILL.md b/dev-workflows-fullstack/skills/requirement-convergence/SKILL.md index bd20961f..b51e0959 100644 --- a/dev-workflows-fullstack/skills/requirement-convergence/SKILL.md +++ b/dev-workflows-fullstack/skills/requirement-convergence/SKILL.md @@ -9,7 +9,7 @@ description: Separates the outcome a change must produce from the requirements p Requirements arrive bloated, ambiguous, or aimed at the wrong outcome. A capable model reconciles all three into a coherent plan and builds it faithfully — delivering exactly what was asked for when what was asked for was wrong. -This skill converges **what to build**. How to build it, and which documents the change requires, are settled after the what is. +This skill converges **what to build**. How to build it, and which documents the change requires, come after the what. ## Convergence Fields @@ -49,14 +49,14 @@ Render this shape at every requirements confirmation stop, whether or not the he | Section | Contents | |---------|----------| -| **Confirmed scope** | The requirements and exclusions the user has already selected, in the user's wording | +| **User-selected scope** | The requirements and exclusions the user has already selected, in the user's wording | | **Decision evidence** | Each material observed fact with its source, followed by what that fact can change about scope, outcome, or cost | | **User decisions** | One question per convergence field below `ready` (Hearing Protocol Step 1), followed by the scope, outcome, or cost effects of its materially different answers | | **Workflow** | Rough cost band with the unknowns that remain, Structural Scale, and the selected document and workflow route | -Keeping the first three sections separate is what makes the decision informable: merged, the reader cannot tell which line is the user's own settled boundary, which is a repository observation, and which is still open. +Keeping the first three sections separate is what makes the decision informable: merged, the reader cannot tell which line is the user's own selection, which is a repository observation, and which is still open. -Only an explicit user answer moves an item from **User decisions** into **Confirmed scope**. Because Step 2 records the user's own wording, pose each open decision as a question and let the user supply its answer. The orchestrator owns **Workflow** and presents it as a selected route. +Only an explicit user answer moves an item from **User decisions** into **User-selected scope**. Because Step 2 records the user's own wording, pose each open decision as a question and let the user supply its answer. The orchestrator owns **Workflow** and presents it as a selected route. ## Storage Protocol diff --git a/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md index caac3770..38f28531 100644 --- a/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md @@ -27,27 +27,27 @@ Build and judge the `convergence` record in the orchestrator with the requiremen ### Small Evidence Gate -Classify Small when `scopeEvidence.executionRoute.status` is `evident`, that route remains inside one responsibility, and every `costEvidence.unknowns` item is proven invariant to boundaries, persistence/shared contracts, and potentially durable choices. Positive route evidence identifies the supported route; an empty alternatives list supplies supporting context. When confirmed requirements remain unresolved at this gate, invoke codebase-analyzer before assigning Structural Scale. Its result supports Small when `analysisScope` and `currentPath` establish one repository-supported route inside one responsibility and every `candidateDecisionPoints`, `unknowns`, and `limitations` item is proven classification-invariant. Other observed boundaries and outcomes route Medium or Large. Reuse that result as the Medium design analysis when the confirmed requirements remain unchanged. For Large, treat it as routing evidence, create and approve the PRD, then run the design analysis against the approved `prd_path`. ADR qualification occurs after codebase-analyzer returns credible technical options and the scope is confirmed. +Classify Small when `scopeEvidence.executionRoute.status` is `evident`, that route remains inside one responsibility, and every `costEvidence.unknowns` item is proven invariant to boundaries, persistence/shared contracts, and potentially durable choices. Positive route evidence identifies the supported route; an empty alternatives list supplies supporting context. When the requirements remain unresolved at this gate, invoke codebase-analyzer before assigning Structural Scale. Its result supports Small when `analysisScope` and `currentPath` establish one repository-supported route inside one responsibility and every `candidateDecisionPoints`, `unknowns`, and `limitations` item is proven classification-invariant. Other observed boundaries and outcomes route Medium or Large. Reuse that result as the Medium design analysis when the requirements remain unchanged. For Large, treat it as routing evidence, create and approve the PRD, then run the design analysis against the approved `prd_path`. ADR qualification occurs after codebase-analyzer returns credible technical options and the scope has passed the requirements stop. ### Requirement Change Detection During Flow -After an analysis result returns, compare each user-facing or operational responsibility it exposes against the confirmed scope. When either leaving that responsibility as it is or changing it would alter the confirmed outcome or an exclusion, return it through the requirements gate before dependent design work; a technical choice about how to satisfy the confirmed scope continues through the design owners instead. +After an analysis result returns, compare each user-facing or operational responsibility it exposes against the scope in the convergence record. When either leaving that responsibility as it is or changing it would alter the outcome or an exclusion, return it through the requirements gate before dependent design work; a technical choice about how to satisfy that scope continues through the design owners instead. -Treat a proposed change to the confirmed outcome, desired-future requirements, or non-goals as a requirement change. When evidence shows those value boundaries cannot all remain true, stop at the requirements gate and ask the user which boundary changes. A technical design or implementation correction that preserves them is not a requirement change, including removal of a technical choice that works but is no longer necessary; passage through an earlier phase does not establish that its means remain necessary. Update each affected technical artifact and resume from the earliest affected technical gate while preserving outputs that remain valid. +Treat a proposed change to the outcome, desired-future requirements, or non-goals as a requirement change. When evidence shows those value boundaries cannot all remain true, stop at the requirements gate and ask the user which boundary changes. A technical design or implementation correction that preserves them is not a requirement change, including removal of a technical choice that works but is no longer necessary; passage through an earlier phase does not establish that its means remain necessary. Update each affected technical artifact and resume from the earliest affected technical gate while preserving outputs that remain valid. -**Requirement reopening after codebase analysis**: When the first codebase-analyzer result after requirement confirmation shows existing behavior that serves a confirmed requirement's need and falls short only of extra behavior that requirement specifies, whichever field reports it, present it with its evidence and cost effect at one requirements stop before UI Spec, ADR, or Design Doc work, and let the user keep or change the requirement. Requirements are confirmed before any code is read, and every later phase builds and reviews against them without questioning them, so this is the one point where repository evidence can reduce them; judging such evidence as ruled out by the requirement removes the user's only chance to weigh it. Apply the answer through Handling Requirement Changes and continue; later analyses do not reopen requirements this way. +**Requirement reopening after codebase analysis**: When the first codebase-analyzer result after requirement confirmation shows existing behavior that serves a requirement's need and falls short only of extra behavior that requirement specifies, whichever field reports it, present it with its evidence and cost effect at one requirements stop before UI Spec, ADR, or Design Doc work, and let the user keep or change the requirement. The user selects requirements before any code is read, and every later phase builds and reviews against them without questioning them, so this is the one point where repository evidence can reduce them; judging such evidence as ruled out by the requirement removes the user's only chance to weigh it. Apply the answer through Handling Requirement Changes and continue; later analyses do not reopen requirements this way. ## Orchestration Principles ### Outcome Stewardship -The orchestrator steers the workflow toward the smallest sufficient set of deliverables and changes that achieves the confirmed outcome while satisfying binding constraints and required verification. Evaluate specialist proposals against that boundary before routing work. +The orchestrator steers the workflow toward the smallest sufficient set of deliverables and changes that achieves the outcome while satisfying binding constraints and required verification. Evaluate specialist proposals against that boundary before routing work. -Preserve specialist evidence ownership and approved artifacts as semantic sources so the workflow converges on the confirmed MVP; orchestrator-authored investigation targets, restatements, or follow-on instructions bias evidence and create unreviewed scope. +Preserve specialist evidence ownership and approved artifacts as semantic sources so the workflow converges on the MVP; orchestrator-authored investigation targets, restatements, or follow-on instructions bias evidence and create unreviewed scope. ### Delegation Boundary: What vs How -Pass the governing requirement source and the specialist's expected action. Investigation specialists discover affected paths and responsibility boundaries; artifact and execution specialists receive the confirmed paths or scope they must act on. Each specialist determines its execution method from repository evidence and applicable artifacts. +Pass the governing requirement source and the specialist's expected action. Investigation specialists discover affected paths and responsibility boundaries; artifact and execution specialists receive the paths or scope they must act on. Each specialist determines its execution method from repository evidence and applicable artifacts. **Decision precedence for routing**: 1. User instructions (explicit requests or constraints) @@ -56,10 +56,10 @@ Pass the governing requirement source and the specialist's expected action. Inve 4. Specialist judgment **Scope source classification**: -- An explicit restriction in the user instruction or confirmed outcome, desired-future requirements, or non-goals is a hard boundary. A technical artifact is the primary implementation baseline, but its How is corrected through the affected technical artifacts when repository evidence invalidates it without changing those value boundaries. +- An explicit restriction in the user instruction or the outcome, desired-future requirements, or non-goals is a hard boundary. A technical artifact is the primary implementation baseline, but its How is corrected through the affected technical artifacts when repository evidence invalidates it without changing those value boundaries. - Target paths and task-file file lists are investigation starting points and expected evidence unless their governing source explicitly makes them exclusive. -- Changes to adjacent files proceed when repository evidence shows they are required by the same confirmed outcome, responsibility, contract, or consistency rule. -- Unrelated improvements remain outside the active change. A proposed change to the confirmed outcome, desired-future requirements, or non-goals returns to the requirements gate. Authorization for an irreversible external action returns to the authority gate. Technical design, contract, and implementation changes that preserve the confirmed value boundaries proceed through their affected technical artifacts. +- Changes to adjacent files proceed when repository evidence shows they are required by the same outcome, responsibility, contract, or consistency rule. +- Unrelated improvements remain outside the active change. A proposed change to the outcome, desired-future requirements, or non-goals returns to the requirements gate. Authorization for an irreversible external action returns to the authority gate. Technical design, contract, and implementation changes that preserve those value boundaries proceed through their affected technical artifacts. Before routing specialist output, validate each claim that controls the next workflow decision against the highest applicable source above. Route according to that source; specialist judgment governs decisions left unresolved by items 1-3. @@ -67,7 +67,7 @@ Before routing specialist output, validate each claim that controls the next wor Each specialist's agent definition owns its canonical result shape. As receiver, the orchestrator chooses the next action from the result's semantic content, governing sources, produced artifacts, and repository state. Semantically equivalent labels, omitted optional fields, and absent transition labels remain acceptable when those sources support the next action. Resolve operational gaps through inspection or repository-local reversible judgment and continue unaffected work. -Continue incomplete implementation while repository evidence supplies an action that advances the confirmed outcome. When current authority and evidence cannot advance required implementation, finish with an incomplete report containing the remaining work and observed evidence. Treat a proof-only limitation differently: perform recovery available within the current authority and scope, run every available check, retain the complete limitation result, establish the recipe's normal reversible task boundary, and continue remaining tasks. Retry retained limitations before final verification and report only those that remain. Claim only the proof actually observed. User interaction is reserved for choosing a change to confirmed value boundaries or authorizing an irreversible external action. +Continue incomplete implementation while repository evidence supplies an action that advances the outcome. When current authority and evidence cannot advance required implementation, finish with an incomplete report containing the remaining work and observed evidence. Treat a proof-only limitation differently: perform recovery available within the current authority and scope, run every available check, retain the complete limitation result, establish the recipe's normal reversible task boundary, and continue remaining tasks. Retry retained limitations before final verification and report only those that remain. Claim only the proof actually observed. User interaction is reserved for choosing a change to value boundaries or authorizing an irreversible external action. ### Review Resolution @@ -94,19 +94,19 @@ 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 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. +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 user-visible outcome from it or the requirement context alongside major internal responsibility, contract, or refactoring changes, so the user can judge whether to proceed. | Phase | Stop Point | User Action Required | |-------|------------|---------------------| | Requirements | After requirement-analyzer completes | Answer the requirement-convergence hearing, confirm the recorded requirements match their intent, then approve proceeding | | PRD | After document-reviewer completes PRD review | Approve completing the PRD phase and proceeding | -| Requirement reopening | After the first codebase-analyzer result when it shows existing behavior that falls short of a confirmed requirement only by extra behavior that requirement specifies | Keep or change each affected requirement | +| Requirement reopening | After the first codebase-analyzer result when it shows existing behavior that falls short of a requirement only by extra behavior that requirement specifies | Keep or change each affected requirement | | UI Spec | After document-reviewer completes an applicable UI Spec review | Approve completing the UI Spec phase and proceeding | | ADR batch | After document-reviewer reviews the complete qualifying batch | Approve completing the ADR batch phase and proceeding | | Design | After design-sync completes consistency verification | Approve completing the design phase and proceeding | | Work Plan | After work plan review (document-reviewer, doc_type WorkPlan; Medium/Large) completes | Batch approval: authorize implementation within this outcome | -**After applicable implementation authorization**: Confirmed Small requirements or Medium/Large batch approval start autonomous execution, which continues until completion or an escalation condition is reached. +**After applicable implementation authorization**: User confirmation at the Requirements stop for Small, or Medium/Large batch approval, starts autonomous execution, which continues until completion or an escalation condition is reached. ## Scale Determination and Document Requirements @@ -151,15 +151,15 @@ Use create mode for initial documents. For requirement-driven revisions, invoke | Medium | requirement-analyzer → codebase-analyzer → requirement reopening when applicable → conditional external/UI analysis and UI Spec → optional ADR batch/review/approval → Design Doc → code-verifier/Review Resolution → document-reviewer → design-sync → acceptance-test-generator → work-planner → work plan review → task-decomposer | | Small | requirement-analyzer → conditional codebase-analyzer when the Small evidence gate is unresolved → direct task execution (no Work Plan) | -The requirement-convergence and external-resource hearings run in the orchestrator. In an implementation workflow, confirmation at the Requirements stop authorizes the confirmed Small direct scope. Medium/Large implementation begins after Work Plan batch approval. +The requirement-convergence and external-resource hearings run in the orchestrator. In an implementation workflow, confirmation at the Requirements stop authorizes the Small direct scope. Medium/Large implementation begins after Work Plan batch approval. Rules: - When documentation-criteria requires a UI Spec, complete it before ADR qualification and Design Doc creation - An ADR batch is optional; the Design Doc is mandatory for Medium/Large work even when ADRs exist -- When the Small evidence gate is unresolved, invoke codebase-analyzer with confirmed `requirements` to resolve routing. Reuse that result for unchanged Medium scope. For Large, create and approve the PRD first, then invoke codebase-analyzer for design with only `prd_path`; the pre-scale result remains routing evidence because the approved PRD becomes the governing design source. For Medium already established by positive boundary evidence, invoke once with confirmed `requirements` -- When a UI Spec applies, invoke ui-analyzer with that same governing-source choice plus existing `ui_spec_path`, decision-relevant `prototype_path`, and selected `external_resource_refs` or `[]`; invoke ui-spec-designer with `confirmed_requirement_context` as the approved PRD path exactly or, only when none exists, the unchanged confirmed convergence record, plus the complete unchanged `ui_analysis`, applicable unchanged `codebase_analysis`, optional `prototype_path`, and `external_resource_refs` or `[]`. A prototype does not state how far it is meant to be followed — one team hands over a rendering to implement as is, another a rough sketch of intent — so when a `prototype_path` is present, pass `prototype_reference_strength` to ui-spec-designer: `binding` when implementation follows the prototype's rendering, `reference` when only what the UI Spec records reaches implementation. Resolve it from what the user already stated about the prototype, and ask only when neither reading is supported -- Before ADR qualification, use the governing source plus `reuse` and `invalidations` to remove questions that already have one sufficient approach. Apply documentation-criteria Choice then Durability filters only to the remaining `candidateDecisionPoints`. When non-empty, invoke each owning technical-designer with `document_to_create: ADRBatch`, `confirmed_requirement_context` as the approved PRD path exactly or, only when none exists, the unchanged confirmed convergence record, ordered confirmed `decision_points` unchanged, and the corresponding `candidateDecisionPoints` objects unchanged as `decision_materials`; add an approved `ui_spec_path` only when it constrains a frontend decision. Run owner batches serially, review all returned paths once with `doc_type: ADRBatch`, and obtain one user approval. After approval, set every approved ADR to `Accepted` and verify the status updates. For corrections, group findings by ADR path and invoke update mode once per path before re-reviewing the complete batch. An empty result proceeds directly to the Design Doc -- Invoke the Design Doc owner with `document_to_create: DesignDoc`, `confirmed_requirement_context` as the approved PRD path exactly or, only when none exists, the unchanged confirmed convergence record, `structural_scale`, unchanged `codebase_analysis`, optional unchanged `ui_analysis`, and accepted `adr_paths`; frontend/fullstack invocations add their named UI or layer artifact paths and distinct `output_path` destinations when splitting a feature across documents +- When the Small evidence gate is unresolved, invoke codebase-analyzer with the convergence record's `requirements` to resolve routing. Reuse that result for unchanged Medium scope. For Large, create and approve the PRD first, then invoke codebase-analyzer for design with only `prd_path`; the pre-scale result remains routing evidence because the approved PRD becomes the governing design source. For Medium already established by positive boundary evidence, invoke once with the convergence record's `requirements` +- When a UI Spec applies, invoke ui-analyzer with that same governing-source choice plus existing `ui_spec_path`, decision-relevant `prototype_path`, and selected `external_resource_refs` or `[]`; invoke ui-spec-designer with `requirement_context` as the approved PRD path exactly or, only when none exists, the unchanged convergence record, plus the complete unchanged `ui_analysis`, applicable unchanged `codebase_analysis`, optional `prototype_path`, and `external_resource_refs` or `[]`. A prototype does not state how far it is meant to be followed — one team hands over a rendering to implement as is, another a rough sketch of intent — so when a `prototype_path` is present, pass `prototype_reference_strength` to ui-spec-designer: `binding` when implementation follows the prototype's rendering, `reference` when only what the UI Spec records reaches implementation. Resolve it from what the user already stated about the prototype, and ask only when neither reading is supported +- Before ADR qualification, use the governing source plus `reuse` and `invalidations` to remove questions that already have one sufficient approach. Apply documentation-criteria Choice then Durability filters only to the remaining `candidateDecisionPoints`. When non-empty, invoke each owning technical-designer with `document_to_create: ADRBatch`, `requirement_context` as the approved PRD path exactly or, only when none exists, the unchanged convergence record, the ordered `decision_points` that pass both filters unchanged, and the corresponding `candidateDecisionPoints` objects unchanged as `decision_materials`; add an approved `ui_spec_path` only when it constrains a frontend decision. Run owner batches serially, review all returned paths once with `doc_type: ADRBatch`, and obtain one user approval. After approval, set every approved ADR to `Accepted` and verify the status updates. For corrections, group findings by ADR path and invoke update mode once per path before re-reviewing the complete batch. An empty result proceeds directly to the Design Doc +- Invoke the Design Doc owner with `document_to_create: DesignDoc`, `requirement_context` as the approved PRD path exactly or, only when none exists, the unchanged convergence record, `structural_scale`, unchanged `codebase_analysis`, optional unchanged `ui_analysis`, and accepted `adr_paths`; frontend/fullstack invocations add their named UI or layer artifact paths and distinct `output_path` destinations when splitting a feature across documents - Resolve code-verifier discrepancies through Review Resolution before invoking document-reviewer; pass the exact HC-04 inputs rather than a narrative evidence bundle - An applied `unverified` discrepancy returns through a fresh owning technical-designer update invocation. Capability probing is reserved for the designer's review-triggered gate, with that fresh designer as the sole correction specialist - Fullstack layer sequencing is defined only in `references/monorepo-flow.md` @@ -174,7 +174,7 @@ Start the applicable Structural Scale flow at the user-requested phase. Before r Verify commit capability before autonomous mode. Let task-executor and quality-fixer recover available test or quality tooling and retain an exact proof limitation for the remainder; escalate a known authority-bound prerequisite before entry. -Confirmed Small requirements or Medium/Large batch approval authorize task-executor implementation and quality-fixer corrections until completion or escalation. +User confirmation at the Requirements stop for Small, or Medium/Large batch approval, authorizes task-executor implementation and quality-fixer corrections until completion or escalation. ### Autonomous Execution Summary For Medium/Large, after batch approval, including an existing-plan build instruction, autonomously execute the following processes through completion or an escalation condition: @@ -215,7 +215,7 @@ When a quality-fixer retry changes behavior outside the received findings, compa | Trigger | Action | |---|---| -| Evidence shows the confirmed outcome, desired-future requirements, and non-goals cannot all remain true without a user choice | Apply Requirement Change Detection and ask which value boundary changes. | +| Evidence shows the outcome, desired-future requirements, and non-goals cannot all remain true without a user choice | Apply Requirement Change Detection and ask which value boundary changes. | | An irreversible external action requires authorization | Request authorization at the authority gate. | | A subagent result uses a semantically equivalent label, omits a non-decision field, or leaves the next action implicit | Derive the next action from its semantic content, governing sources, produced artifacts, and repository state. | | Required implementation remains incomplete | Continue while repository evidence supplies an advancing action; otherwise finish with an incomplete report and the observed evidence. | @@ -228,9 +228,9 @@ When a quality-fixer retry changes behavior outside the received findings, compa #### Commit Boundary Check Immediately before a workflow commit: -1. Use repository state at the commit boundary as the primary evidence and account for every actual change by mapping it to the confirmed outcome, a governing source, or a necessary dependency, test, generated artifact, or adjacent maintenance change. `target_paths` and task Target Files are investigation starting points; a change with this evidence proceeds independently of its initial path membership. -2. Every required change is ready for the task commit, accidental changes introduced during the task are removed, and existing worktree changes unrelated to the confirmed outcome remain intact. -3. Commit the resulting change set. When repository evidence shows a change would alter the confirmed outcome, desired-future requirements, or non-goals, apply Requirement Change Detection before committing it. +1. Use repository state at the commit boundary as the primary evidence and account for every actual change by mapping it to the outcome, a governing source, or a necessary dependency, test, generated artifact, or adjacent maintenance change. `target_paths` and task Target Files are investigation starting points; a change with this evidence proceeds independently of its initial path membership. +2. Every required change is ready for the task commit, accidental changes introduced during the task are removed, and existing worktree changes unrelated to the outcome remain intact. +3. Commit the resulting change set. When repository evidence shows a change would alter the outcome, desired-future requirements, or non-goals, apply Requirement Change Detection before committing it. For a `verification_incomplete` commit, append one trailer pair per retained limitation: @@ -242,7 +242,7 @@ Verification-Affected: Derive the values from the quality-fixer result. Keep the complete result in orchestration state for the current run; the trailers preserve the minimum retry input after continuation. **Per-task cycle**: -1. **Execute**: record the current HEAD as `diffBase`, then invoke task-executor with `task_file: [path]` when one exists; for Small, invoke it with `direct_scope` as the confirmed outcome and exclusions, `governing_sources`, `target_paths`, and `observable_verification` +1. **Execute**: record the current HEAD as `diffBase`, then invoke task-executor with `task_file: [path]` when one exists; for Small, invoke it with `direct_scope` as the convergence record's outcome and exclusions, `governing_sources`, `target_paths`, and `observable_verification` 2. **Branch on executor result**: - `status: escalation_needed` or `blocked` → Apply Specialist Result Acceptance - `requiresTestReview` is `true` → Identify the changed integration/E2E test files in the current changes and invoke integration-test-reviewer with them as `changedTestFiles`, plus `diffBase`, optional `taskFile`, prompt-only claims, and `mutationEvidence` @@ -268,12 +268,12 @@ Before post-implementation verifiers, collect retained verification limitations ### HC-01b: convergence record → document owner - Pass the orchestrator-judged `convergence` record to whichever agent owns the persisting document. -- **prd-creator** (when a PRD is created or updated): persists `outcome` to `Success Criteria` and user-authored `nonGoals` to `Future / Out of Scope`; the PRD contains confirmed requirements and boundaries while evaluation requests, speculative ideas, and unselected mechanisms remain only in pre-confirmation convergence context +- **prd-creator** (when a PRD is created or updated): persists `outcome` to `Success Criteria` and user-authored `nonGoals` to `Future / Out of Scope`; the PRD contains the user-selected requirements and boundaries while evaluation requests, speculative ideas, and unselected mechanisms remain only in active convergence context - **technical-designer / technical-designer-frontend**: persists the same to the Design Doc's `Requirement Convergence` when no PRD exists, and always records the fields left `weak-but-explicit` there - Pass the record unchanged; a field's readiness label travels with it ### HC-02: codebase-analyzer → technical-designer -- For an ADR batch, pass the confirmed `decision_points` unchanged and copy their corresponding `decisionMaterials.candidateDecisionPoints` objects unchanged as `decision_materials`. +- For an ADR batch, pass the `decision_points` that pass both filters unchanged and copy their corresponding `decisionMaterials.candidateDecisionPoints` objects unchanged as `decision_materials`. - For a Design Doc, pass the codebase-analyzer JSON unchanged as `codebase_analysis`; accepted artifact paths and unchanged evidence keep the Design Doc traceable to reviewed sources rather than an orchestrator-authored shadow interpretation. Use these fields as follows: - Required downstream uses: - `focusAreas` → canonical disposition-target list for the Fact Disposition Table @@ -293,7 +293,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 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. +- 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 `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. ### HC-05: code-verifier → next-layer technical-designer (fullstack only) @@ -307,7 +307,7 @@ Pass the Design Doc path. Work-planner maps governing sections and ACs to implem ### HC-06: acceptance-test-generator → work-planner -- Invoke acceptance-test-generator with `design_docs` as the applicable Design Doc path list, optional `ui_spec`, and the same `confirmed_requirement_context` used for design. +- Invoke acceptance-test-generator with `design_docs` as the applicable Design Doc path list, optional `ui_spec`, and the same `requirement_context` used for design. - Resolve a blocked generator result through Specialist Result Acceptance before consuming `generatedFiles`. - Verify each non-null `generatedFiles.` path exists. When a lane is `null`, check the generator’s explanation against the accepted criteria, applicable UI Spec, actual existing test assertions and generated skeletons. Confirm that the explanation accounts for the required observable boundary. A proposed test is not existing coverage; return any missing integration/E2E obligation to the generator. - Pass only existing generated paths as work-planner `testSkeletons`; each skeleton carries the lane and boundary information needed for placement. diff --git a/dev-workflows-fullstack/skills/subagents-orchestration-guide/references/monorepo-flow.md b/dev-workflows-fullstack/skills/subagents-orchestration-guide/references/monorepo-flow.md index 84396532..52bbc86e 100644 --- a/dev-workflows-fullstack/skills/subagents-orchestration-guide/references/monorepo-flow.md +++ b/dev-workflows-fullstack/skills/subagents-orchestration-guide/references/monorepo-flow.md @@ -4,7 +4,7 @@ This reference defines the orchestration flow for one feature spanning backend a ## When This Flow Applies -- The confirmed outcome requires backend and frontend implementation. +- The outcome requires backend and frontend implementation. - Separate Design Docs are needed for layer ownership and cross-layer verification. - The orchestrator is invoked through a fullstack implementation or build recipe. @@ -14,7 +14,7 @@ This reference defines the orchestration flow for one feature spanning backend a | Step | Owner | Purpose | Output | |------|-------|---------|--------| -| 1 | requirement-analyzer + orchestrator | Scope/cost evidence followed by orchestrator convergence and Structural Scale judgment, then the requirements hearing **[Stop]** | Confirmed requirements + scale | +| 1 | requirement-analyzer + orchestrator | Scope/cost evidence followed by orchestrator convergence and Structural Scale judgment, then the requirements hearing **[Stop]** | Convergence record + scale | | 2 | prd-creator | PRD for the complete feature | PRD | | 3 | document-reviewer | PRD review **[Stop]** | Approval | | 4 | codebase-analyzer + orchestrator | Repository decision material for the complete feature, including layer boundaries and cross-layer contracts, then requirement reopening when applicable **[Stop when applicable]** | Analysis JSON | @@ -34,13 +34,13 @@ This reference defines the orchestration flow for one feature spanning backend a ### Medium Structural Scale Fullstack -For Medium scale, execute Large steps 4-17 and carry the confirmed convergence record in place of a PRD; retain the conditional stops at steps 4, 7, and 9 and the approval stops at steps 14 and 17. +For Medium scale, execute Large steps 4-17 and carry the convergence record in place of a PRD; retain the conditional stops at steps 4, 7, and 9 and the approval stops at steps 14 and 17. ## Analysis and Evidence Rules At each Agent invocation in this flow, build the prompt as a mechanical extraction: copy the named source values into the exact fields, apply only the declared serialization, then invoke immediately. -Invoke codebase-analyzer once for the complete confirmed feature. It discovers backend/frontend responsibility boundaries and their cross-layer contracts; independent discovery keeps convergence grounded in repository evidence rather than the orchestrator's unverified implementation hypothesis. +Invoke codebase-analyzer once for the complete feature. It discovers backend/frontend responsibility boundaries and their cross-layer contracts; independent discovery keeps convergence grounded in repository evidence rather than the orchestrator's unverified implementation hypothesis. Apply the documentation-criteria UI Spec creation condition. Invoke ui-analyzer only when a UI Spec applies. External-resource and prototype inputs are then conditional: load external-resource-context when external evidence can change the current UI or verification decision, and ask for a prototype only when it resolves an approved UI decision or target ambiguity. @@ -50,7 +50,7 @@ Use these prompt shapes: For either analyzer, pass exactly one governing source: prd_path: [approved PRD path] or -requirements: [confirmed requirements verbatim] +requirements: [convergence record requirements verbatim] For UI analysis only, add an existing UI Spec, a decision-relevant prototype, and selected external references: ui_spec_path: [existing UI Spec path] @@ -58,7 +58,7 @@ prototype_path: [decision-relevant path] external_resource_refs: [selected references or []] UI Spec: -confirmed_requirement_context: [approved PRD path exactly; otherwise unchanged convergence record] +requirement_context: [approved PRD path exactly; otherwise unchanged convergence record] ui_analysis: [UI analyzer JSON] codebase_analysis: [applicable frontend codebase evidence] prototype_path: [decision-relevant path or absent] @@ -72,7 +72,7 @@ After scope and any applicable UI Spec approval, resolve candidate decision poin - Route layer-owned decision points to the matching technical designer. - Route cross-layer points to technical-designer. -- Invoke each owner with `document_to_create: ADRBatch`, `confirmed_requirement_context`, its ordered confirmed `decision_points` unchanged, and the corresponding codebase-analysis `candidateDecisionPoints` objects unchanged as `decision_materials`; include an approved `ui_spec_path` only when it constrains a frontend decision. +- Invoke each owner with `document_to_create: ADRBatch`, `requirement_context`, its ordered `decision_points` that pass both filters unchanged, and the corresponding codebase-analysis `candidateDecisionPoints` objects unchanged as `decision_materials`; include an approved `ui_spec_path` only when it constrains a frontend decision. - Invoke technical-designer batches serially: cross-layer/backend first, frontend second. Each owner allocates numbers only after the preceding batch exists. - Collect every returned ADR path. - Invoke document-reviewer once with `doc_type: ADRBatch` and the complete `targets` array. @@ -89,8 +89,8 @@ Create each complete layer design from reviewed artifacts and unchanged evidence ```text document_to_create: DesignDoc output_path: docs/design/[feature-name]-backend-design.md -confirmed_requirement_context: [approved PRD path exactly; otherwise unchanged convergence record] -structural_scale: [confirmed scale] +requirement_context: [approved PRD path exactly; otherwise unchanged convergence record] +structural_scale: [orchestrator-selected scale] adr_paths: [accepted paths or []] codebase_analysis: [complete analysis JSON unchanged] ``` @@ -100,8 +100,8 @@ codebase_analysis: [complete analysis JSON unchanged] ```text document_to_create: DesignDoc output_path: docs/design/[feature-name]-frontend-design.md -confirmed_requirement_context: [approved PRD path exactly; otherwise unchanged convergence record] -structural_scale: [confirmed scale] +requirement_context: [approved PRD path exactly; otherwise unchanged convergence record] +structural_scale: [orchestrator-selected scale] adr_paths: [accepted paths or []] ui_spec_path: [approved UI Spec; omit when absent] backend_design_doc: [path] @@ -113,13 +113,13 @@ Apply `code:` and `ui:` prefixes to respective Fact Disposition IDs. The fronten ## Verification Resolution -Keep verifier observations unchanged so corrections remain traceable to observed evidence rather than orchestrator-authored design instructions. Invoke code-verifier once per Design Doc with `doc_type: design-doc`; apply Review Resolution independently, forward each `apply` discrepancy verbatim with only its disposition, and rerun the affected verifier with its previous complete result, dispositions, and correction diff or paths as `prior_feedback`. Build one `verification_evidence` object per Design Doc from the latest result. Invoke document-reviewer with `review_context: creation`, `verification_evidence`, the same unchanged `codebase_analysis` and optional unchanged `ui_analysis`, original requirements as `requirements_verbatim`, and `confirmed_requirement_context` in the exact form fixed by the orchestration guide. +Keep verifier observations unchanged so corrections remain traceable to observed evidence rather than orchestrator-authored design instructions. Invoke code-verifier once per Design Doc with `doc_type: design-doc`; apply Review Resolution independently, forward each `apply` discrepancy verbatim with only its disposition, and rerun the affected verifier with its previous complete result, dispositions, and correction diff or paths as `prior_feedback`. Build one `verification_evidence` object per Design Doc from the latest result. Invoke document-reviewer with `review_context: creation`, `verification_evidence`, the same unchanged `codebase_analysis` and optional unchanged `ui_analysis`, original requirements as `requirements_verbatim`, and `requirement_context` in the exact form fixed by the orchestration guide. After both document reviews permit approval, invoke design-sync with `source_design` as the frontend Design Doc path because it consumes backend integration contracts. Apply Review Resolution to actionable conflicts before the design approval stop. ## Test Skeleton and Work Planning -Pass both Design Doc paths as `design_docs`, the applicable `ui_spec`, and the same `confirmed_requirement_context` used for design to acceptance-test-generator. Follow parent HC-06 for generated-path and empty-lane coverage checks before planning. Empty optional lanes are valid when the accepted Design Doc proof obligations, candidate filtering, and generated result together show that no selected boundary belongs in that lane. +Pass both Design Doc paths as `design_docs`, the applicable `ui_spec`, and the same `requirement_context` used for design to acceptance-test-generator. Follow parent HC-06 for generated-path and empty-lane coverage checks before planning. Empty optional lanes are valid when the accepted Design Doc proof obligations, candidate filtering, and generated result together show that no selected boundary belongs in that lane. Pass both Design Docs, the applicable UI Spec, applicable PRD, and generated skeleton paths to work-planner. Compose phases around shared backend/frontend verification points. The generated skeleton file is consumed by the earliest task where its declared boundary becomes executable. 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 09f6bae1..512b2c26 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 @@ -1,6 +1,6 @@ # Review Resolution -Use this protocol when a deliverable reviewer or verifier returns findings that can route correction or progression. Correct evidenced defects while preserving confirmed requirements, exclusions, and compatibility obligations, using existing responsibilities. Accepted design decisions are the currently selected means: a correction may remove or narrow one while those boundaries remain true. Verification output used as evidence by a downstream specialist remains part of that specialist handoff. +Use this protocol when a deliverable reviewer or verifier returns findings that can route correction or progression. Correct evidenced defects while preserving the requirements, exclusions, and compatibility obligations, using existing responsibilities. Accepted design decisions are the currently selected means: a correction may remove or narrow one while those boundaries remain true. Verification output used as evidence by a downstream specialist remains part of that specialist handoff. Preserve reviewer/verifier evidence ownership so each gate converges on the governing sources; orchestrator reinterpretation would create unreviewed requirements and make approval or reconciliation non-terminal. @@ -23,20 +23,20 @@ Use the result producer's declared verification mode: ## 1. Assess Every Finding -Before assigning a disposition, inspect the relevant parts of the current deliverable, cited repository evidence, and governing sources. Confirm the reported behavior, then establish the material effect of leaving it unchanged. A material effect changes the confirmed outcome, a binding constraint, downstream behavior, decisions, or required verification, or is an evidenced lifecycle cost whose frequency or magnitude is observable. For a discretionary response, compare that effect with the full cost of implementing, verifying, and retaining the response, including review attention. +Before assigning a disposition, inspect the relevant parts of the current deliverable, cited repository evidence, and governing sources. Confirm the reported behavior, then establish the material effect of leaving it unchanged. A material effect changes the outcome, a binding constraint, downstream behavior, decisions, or required verification, or is an evidenced lifecycle cost whose frequency or magnitude is observable. For a discretionary response, compare that effect with the full cost of implementing, verifying, and retaining the response, including review attention. Order the candidate responses before recording a disposition: no change, then removal or narrowing, then reuse of existing behavior, then a repair that retains or adds a mechanism. A retaining or additive response names the required result the earlier candidates cannot deliver. This is a selection condition, not an obligation to enumerate alternatives for every finding. -When a proposed correction remains within the agreed boundary above, select it from current evidence without expanding scope. When evidence shows the confirmed outcome cannot be achieved within existing responsibilities, leave Review Resolution and apply the parent workflow's existing design or requirement gate before changing them. When the confirmed outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which value boundary changes, apply the parent workflow's Requirement Change Detection. When correction requires authorization for an irreversible external action, apply the parent workflow's authority gate. These workflow exits are not finding dispositions; an optional expansion receives `decline`. +When a proposed correction remains within the agreed boundary above, select it from current evidence without expanding scope. When evidence shows the outcome cannot be achieved within existing responsibilities, leave Review Resolution and apply the parent workflow's existing design or requirement gate before changing them. When the outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which value boundary changes, apply the parent workflow's Requirement Change Detection. When correction requires authorization for an irreversible external action, apply the parent workflow's authority gate. These workflow exits are not finding dispositions; an optional expansion receives `decline`. The orchestrator records one disposition for every actionable finding: | Disposition | Use when | |---|---| -| `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. | +| `apply` | Leaving the current deliverable unchanged would prevent the 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 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. +A confirmed exploitable gap in a relied-upon trust boundary, implementation divergence, or governing-source contradiction receives `apply` when correction preserves the 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: @@ -53,7 +53,7 @@ Only findings with `apply`, and maintained `apply` findings under section 3, ent Select the existing correction owner from the accepted state each finding requires: -- use the owning document author when the implementation already satisfies the confirmed value boundaries and the technical artifact must change; +- use the owning document author when the implementation already satisfies the value boundaries and the technical artifact must change; - use the executor when the implementation must change to reach the accepted state. For a mixed set, complete author-owned corrections first and re-evaluate executor-owned findings against the corrected governing artifact. Pass complete `apply` finding objects verbatim with their dispositions to the selected owner. Invoke a document author as a fresh update call with the original target and those findings; the artifact supplies unaffected context. When an executor is used, preserve its original `task_file` or four direct-scope fields and add the findings as `correction_findings`; correction remains inside the original execution scope. diff --git a/dev-workflows/agents/acceptance-test-generator.md b/dev-workflows/agents/acceptance-test-generator.md index a8ffc948..616b6920 100644 --- a/dev-workflows/agents/acceptance-test-generator.md +++ b/dev-workflows/agents/acceptance-test-generator.md @@ -15,7 +15,7 @@ You generate comment-only integration/E2E test skeletons for required proof that - **design_docs**: One or more readable Design Doc paths containing acceptance criteria and Test Boundaries. - **ui_spec**: Optional UI Spec whose interactions constrain those criteria. -- **confirmed_requirement_context**: Optional approved PRD or unchanged confirmed convergence record; otherwise use the Design Doc's carrier. +- **requirement_context**: Optional approved PRD or unchanged convergence record; otherwise use the Design Doc's carrier. Accept equivalent labels and concise prose with the same meaning. Follow linked sources only when they determine an in-scope proof obligation. If required criteria or documents remain unavailable after local resolution, return `status: "blocked"` with the exact missing input. diff --git a/dev-workflows/agents/code-reviewer.md b/dev-workflows/agents/code-reviewer.md index 91dd0082..e8d55424 100644 --- a/dev-workflows/agents/code-reviewer.md +++ b/dev-workflows/agents/code-reviewer.md @@ -95,8 +95,8 @@ Correction re-review: - `pass`: no required-correction finding or blocked judgment remains; - `needs-improvement`: findings are repairable within the approved scope; -- `needs-redesign`: correction requires updating the governing technical design or responsibility boundary while preserving the confirmed outcome, desired-future requirements, and non-goals; -- `blocked`: required inputs or evidence are unavailable, or evidence shows the confirmed outcome, desired-future requirements, and non-goals cannot all remain true. +- `needs-redesign`: correction requires updating the governing technical design or responsibility boundary while preserving the outcome, desired-future requirements, and non-goals; +- `blocked`: required inputs or evidence are unavailable, or evidence shows the outcome, desired-future requirements, and non-goals cannot all remain true. ## Completion Check diff --git a/dev-workflows/agents/code-verifier.md b/dev-workflows/agents/code-verifier.md index a114b2b7..2c717c5e 100644 --- a/dev-workflows/agents/code-verifier.md +++ b/dev-workflows/agents/code-verifier.md @@ -10,7 +10,7 @@ skills: You perform read-only verification of an authoritative document against repository evidence. -Your discrepancies are independent evidence for orchestrator Review Resolution. Confirmed requirements and selected ADR decisions define scope; the orchestrator determines correction obligations. +Your discrepancies are independent evidence for orchestrator Review Resolution. The requirements and selected ADR decisions define scope; the orchestrator determines correction obligations. ## Inputs diff --git a/dev-workflows/agents/design-sync.md b/dev-workflows/agents/design-sync.md index ceaad0c5..7ebe625c 100644 --- a/dev-workflows/agents/design-sync.md +++ b/dev-workflows/agents/design-sync.md @@ -115,7 +115,7 @@ Severity Assessment: - Term → medium (confusion risk) ``` -Recommend only a correction within confirmed requirements, accepted design decisions, and existing responsibilities. When resolution requires changing that boundary, report the conflict evidence without selecting the expanded design. +Recommend only a correction within the requirements, accepted design decisions, and existing responsibilities. When resolution requires changing that boundary, report the conflict evidence without selecting the expanded design. ## Output Format diff --git a/dev-workflows/agents/document-reviewer.md b/dev-workflows/agents/document-reviewer.md index 28519e7c..69b5b3ba 100644 --- a/dev-workflows/agents/document-reviewer.md +++ b/dev-workflows/agents/document-reviewer.md @@ -22,7 +22,7 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow - **targets**: Complete ADR path array for `ADRBatch` - **review_context**: `creation`, `update`, or `reverse-engineer` when supplied - **requirements_verbatim**: Original user requirements when they govern the target -- **confirmed_requirement_context**: Exact approved PRD path, or the unchanged orchestrator-confirmed convergence record only when no approved PRD exists +- **requirement_context**: Exact approved PRD path, or the orchestrator's unchanged convergence record only when no approved PRD exists - **codebase_analysis**: Compact codebase analysis JSON used by the author, when supplied - **ui_analysis**: UI analysis JSON used by the author, when supplied - **verification_evidence**: Latest code verification evidence when verification ran; Design Doc creation receives the resolved form produced by Review Resolution @@ -30,18 +30,18 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow Verify each target exists. Follow a cited source only when it can change an in-scope finding or approval decision. -For a Design Doc creation review, use `requirements_verbatim`, `confirmed_requirement_context`, and `review_context: creation`. For an as-is document use `review_context: reverse-engineer`. Treat a supported declined verification discrepancy in `verification_evidence` as evidence, not duplicate correction work; reopen it only when current governing evidence invalidates its recorded basis. Update and reverse-engineer reviews may receive unresolved verification discrepancies as evidence for their first review. +For a Design Doc creation review, use `requirements_verbatim`, `requirement_context`, and `review_context: creation`. For an as-is document use `review_context: reverse-engineer`. Treat a supported declined verification discrepancy in `verification_evidence` as evidence, not duplicate correction work; reopen it only when current governing evidence invalidates its recorded basis. Update and reverse-engineer reviews may receive unresolved verification discrepancies as evidence for their first review. ## Review Order and Boundary Review in this order: -1. Map each confirmed current requirement and user-decided exclusion to the artifact's adopted design. Check the central outcome before secondary technical detail. +1. Map each current requirement and user-decided exclusion to the artifact's adopted design. Check the central outcome before secondary technical detail. 2. Apply accepted ADRs and approved upstream documents. 3. Check applicable repository rules, observed code facts, and resolved verification evidence. 4. Check that the artifact supplies every decision and contract its immediate downstream consumer needs to implement or verify the result. -Confirmed requirements, accepted decisions, repository rules, and observed facts govern implementation. Product Context, optional hardening, future operations, uncited general best practice, and unknown contextual information are non-binding. +Requirements, accepted decisions, repository rules, and observed facts govern implementation. Product Context, optional hardening, future operations, uncited general best practice, and unknown contextual information are non-binding. Apply a section, table, diagram, metric, edge case, test lane, or external-evidence check only when the artifact's scope or evidence activates the boundary it protects. Structural presence alone is not quality. Conversely, retain a required safeguard even when it appears verbose if its absence would make a current contract, implementation action, or verification result ambiguous. @@ -51,17 +51,17 @@ Verify current external facts from authoritative sources only when an ADR select ### PRD -- A future-state PRD contains one confirmed outcome, buildable current requirements, representative acceptance criteria, and user-decided exclusions or confirmed none. +- A future-state PRD contains one outcome, buildable current requirements, representative acceptance criteria, and user-decided exclusions or confirmed none. - Product Context retains provenance and does not fabricate unknown business, UX, success, or feasibility claims. - A contextual unknown permits approval unless the user must resolve it to define the outcome, requirement, exclusion, or acceptance criterion. ### ADR Batch - For ADR and Design Doc checks, total complexity covers every activated user decision, setting, mode, concept, output, persistent state, and implementation path, together with its UX, runtime, implementation, testing, documentation, and maintenance cost; compare only dimensions that differ between valid options. -- Each ADR owns one technical question inside confirmed scope. +- Each ADR owns one technical question inside the scope of the requirements. - Current requirements and repository evidence support at least two credible, materially distinct options, and the choice has durable impact. -- Options compare confirmed product value, repository fit, total complexity, maintainability, material trade-offs, and reversibility using available evidence. -- The selected option is necessary and sufficient for the approved outcome and has the lowest justified total complexity among valid options. A more expensive option has confirmed product value that changes the selection. +- Options compare product value from the requirements, repository fit, total complexity, maintainability, material trade-offs, and reversibility using available evidence. +- The selected option is necessary and sufficient for the approved outcome and has the lowest justified total complexity among valid options. A more expensive option has product value from the requirements that changes the selection. - Relative evidence is sufficient. A numeric estimate or fixed option count applies only when governing evidence requires it. - The selected decision alone constrains the downstream Design Doc for that technical question. Implementation procedure, end-to-end design, release strategy, and work planning remain outside the ADR. - For a batch, decision ownership does not overlap and the selected combination has justified cumulative total complexity. @@ -69,12 +69,12 @@ Verify current external facts from authoritative sources only when an ADR select ### UI Spec - Required screens/components, transitions, state/display behavior, interactions, visual outcomes, and acceptance-criteria traceability are implementable. -- Loading, empty, error, responsive, accessibility, token, and browser behavior is present when supported by confirmed requirements, approved UI direction, preserved behavior, or repository/design-system rules. +- Loading, empty, error, responsive, accessibility, token, and browser behavior is present when supported by the requirements, approved UI direction, preserved behavior, or repository/design-system rules. - Speculative UI states and user-decided exclusions are not reintroduced. ### Design Doc -- Each confirmed requirement maps to an adopted end-to-end flow or concrete verification evidence; exclusions are not implemented indirectly. +- Each requirement maps to an adopted end-to-end flow or concrete verification evidence; exclusions are not implemented indirectly. - The Design Doc remains the complete implementation design and carries the flow, contracts, impact, and verification design; ADRs constrain selected technical questions. - Every premise that can change the Selected Design is resolved by current evidence before approval. Risks contain only residual implementation uncertainty whose possible outcomes leave the Selected Design valid, with an executable in-scope verification or guard when needed. - Every supplied code/UI focus area has one evidence-preserving Fact Disposition row. This check protects existing behavior; it does not require disposition rows for unrelated discovered symbols. @@ -103,7 +103,7 @@ Create an issue only when the artifact otherwise: - describes an incorrect approved outcome or contract; - leaves approved implementation non-executable; - 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. +- commits downstream implementation to added design surface whose total complexity lacks current evidence and whose removal still satisfies the 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, extra Product Context, duplicate proof, stylistic completeness, and template-only omissions from the review result. @@ -115,7 +115,7 @@ For `prior_feedback`, the received items and the boundaries their corrections ch - `pass`: `issues` is empty and no maintained prior finding remains. A maintained decline may keep the reviewer at `needs_revision`; the orchestrator retains the decline at its convergence gate. - `needs_revision`: A new issue or maintained prior finding can be repaired inside approved scope. -- `rejected`: Confirmed outcome, desired-future requirements, and non-goals cannot all remain true and approval requires choosing which value changes. +- `rejected`: The outcome, desired-future requirements, and non-goals cannot all remain true and approval requires choosing which value changes. Technical design conflicts and corrections that preserve those value boundaries are `needs_revision`, even when they change architecture, contracts, persistence, or other implementation How. diff --git a/dev-workflows/agents/prd-creator.md b/dev-workflows/agents/prd-creator.md index c3cdd488..fc1afa18 100644 --- a/dev-workflows/agents/prd-creator.md +++ b/dev-workflows/agents/prd-creator.md @@ -38,7 +38,7 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow - `reverse-engineer`: Create PRD from existing implementation (Reverse PRD) - **Requirements Analysis Results**: Requirements analysis results -- **Convergence Result**: The `convergence` object (HC-01b) → `outcome` anchors Success Criteria; user-authored `nonGoals` populate `Future / Out of Scope`. The PRD contains confirmed requirements and boundaries; evaluation requests, speculative ideas, and unselected mechanisms remain only in pre-confirmation convergence context +- **Convergence Result**: The `convergence` object (HC-01b) → `outcome` anchors Success Criteria; user-authored `nonGoals` populate `Future / Out of Scope`. The PRD contains the user-selected requirements and boundaries; evaluation requests, speculative ideas, and unselected mechanisms remain only in active convergence context - **Existing PRD**: Path to existing PRD file for reference (if any) - **Project Context**: - Target users (sales, marketing, HR, etc.) @@ -118,7 +118,7 @@ PRDs focus solely on "what to build." Implementation phases and task decompositi 4. Limit Future or Out of Scope to user-authored non-goals and current exclusions needed to make the MVP boundary executable ### 3. Measurable Success Metrics -- Define observable success for the confirmed outcome. Include numerical targets and measurement methods when supported by a governing requirement or existing evidence. +- Define observable success for the outcome. Include numerical targets and measurement methods when supported by a governing requirement or existing evidence. - In reverse-engineer mode, preserve observed measures and distinguish unknown business goals; derive no new target from a template. ### 4. Completeness Check @@ -150,7 +150,7 @@ Use a user journey diagram, scope boundary diagram, or both only when prose does ## Update Mode Operation - **Execution**: User's modification instruction = approval. Execute modifications immediately -- **Review corrections**: Resolve supplied defects within the confirmed product outcome and scope. A reviewer suggestion does not become a new requirement; return the conflicting evidence when the correction would require one. +- **Review corrections**: Resolve supplied defects within the product outcome and scope. A reviewer suggestion does not become a new requirement; return the conflicting evidence when the correction would require one. - **Processing**: Increment version number and record change history ## Reverse-Engineer Mode (Reverse PRD) diff --git a/dev-workflows/agents/quality-fixer.md b/dev-workflows/agents/quality-fixer.md index 6b23076e..cf730b03 100644 --- a/dev-workflows/agents/quality-fixer.md +++ b/dev-workflows/agents/quality-fixer.md @@ -16,14 +16,14 @@ Executes applicable quality checks, fixes in-scope failures, and reports exact p ## Main Responsibilities 1. **Self-contained Quality Assurance and Fix Execution** - - Execute applicable project quality checks; fix failures tied to the current change or confirmed task scope, and report other failures with their owning boundary as `verification_incomplete` + - Execute applicable project quality checks; fix failures tied to the current change or the task scope, and report other failures with their owning boundary as `verification_incomplete` - Analyze error root causes and execute both auto-fixes and manual fixes autonomously - Continue until each in-scope failure is fixed, required proof remains unavailable, or one authoritative `blocked` condition is evidenced; return `pass` only when every applicable check passes ## Input Parameters - **task_file** (optional): Path to the task file being verified. When provided, use its Operation Verification Methods as task-specific checks. -- **direct_scope** (for workflow execution without a task file): Confirmed outcome and exclusions, copied unchanged from the execution scope +- **direct_scope** (for workflow execution without a task file): Outcome and exclusions, copied unchanged from the execution scope - **governing_sources** (for direct scope): Authoritative source paths and unchanged governing values used for execution - **observable_verification** (for direct scope): The same behavior, artifact state, or command result required to prove execution complete - **correction_findings** (optional): Complete applied finding objects supplied to the executor, copied unchanged as the correction scope and acceptance evidence @@ -78,14 +78,14 @@ Apply fixes per coding-principles and testing-principles skills. - Verified failure in a separate responsibility → Return `verification_incomplete` with evidence and continue reporting checks unaffected by it - All pass → proceed to Step 6 - Required behavior cannot be determined from the supplied governing and repository evidence → proceed to Step 6 with `verification_incomplete` -- Confirmed value boundaries cannot all remain true and the user must choose which changes, or an irreversible external action requires authorization → proceed to Step 6 with `blocked` +- Value boundaries cannot all remain true and the user must choose which changes, or an irreversible external action requires authorization → proceed to Step 6 with `blocked` ### Step 6: Return JSON Result Return one of the following as the final response (see Output Format for schemas): - `status: "pass"` — all quality checks pass - `status: "stub_detected"` — incomplete implementation found (from Step 1) - `status: "verification_incomplete"` — environment or a separate-responsibility failure prevents required proof -- `status: "blocked"` — a confirmed value-boundary choice or irreversible external action authorization belongs to the user +- `status: "blocked"` — a value-boundary choice or irreversible external action authorization belongs to the user ## Status Determination Criteria @@ -103,12 +103,12 @@ Returned immediately when Step 1 finds incomplete implementation of the required | Condition | Example | Reason | |-----------|---------|--------| -| Confirmed value boundaries conflict | Outcome requires atomic completion while a desired-future requirement forbids the only available atomic mechanism | User must choose which confirmed value changes | +| Value boundaries conflict | Outcome requires atomic completion while a desired-future requirement forbids the only available atomic mechanism | User must choose which value boundary changes | | Fix requires an irreversible external action | Restoring correctness requires rotating a live credential | User must authorize the exact action | **Before blocking**: Always check Design Doc → PRD → Similar code → Test comments -**Determination**: Treat a failure as in scope when evidence ties it to the current change or confirmed outcome; fix it and re-run the check. Resolve technical design, contract, persistence, dependency, and other reversible ambiguity from governing sources and representative code. Return `blocked` only when confirmed outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes, or when an irreversible external action requires authorization. Missing evidence is `verification_incomplete`, not a user decision. +**Determination**: Treat a failure as in scope when evidence ties it to the current change or the outcome; fix it and re-run the check. Resolve technical design, contract, persistence, dependency, and other reversible ambiguity from governing sources and representative code. Return `blocked` only when the outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes, or when an irreversible external action requires authorization. Missing evidence is `verification_incomplete`, not a user decision. ### verification_incomplete (Required proof remains unavailable) @@ -165,9 +165,9 @@ Use `null` for `file` or `location` when no corresponding file or code location ```json { "status": "blocked", - "reason": "Confirmed value boundaries cannot all remain true", + "reason": "Value boundaries cannot all remain true", "evidence": ["Governing source and observed repository evidence showing the conflict or irreversible action"], - "requiredDecision": "Which confirmed value boundary may change, or the exact irreversible action requiring authorization" + "requiredDecision": "Which value boundary may change, or the exact irreversible action requiring authorization" } ``` diff --git a/dev-workflows/agents/task-executor.md b/dev-workflows/agents/task-executor.md index 161d9263..be4a9318 100644 --- a/dev-workflows/agents/task-executor.md +++ b/dev-workflows/agents/task-executor.md @@ -17,7 +17,7 @@ You are a specialized AI assistant for reliably executing individual tasks. Workflow callers use the applicable canonical fields below: - **task_file**: Task file path for planned execution -- **direct_scope**: Confirmed outcome and exclusions, or another implementation objective for prompt-only execution +- **direct_scope**: The convergence record's outcome and exclusions, or another implementation objective for prompt-only execution - **governing_sources**: Authoritative requirement or artifact paths and unchanged governing values - **target_paths**: Suggested starting write and investigation paths - **observable_verification**: Behavior, artifact state, or command result that proves the direct scope complete @@ -26,11 +26,11 @@ Workflow callers use the applicable canonical fields below: Accept equivalent labels, a prose implementation objective, and legacy `incomplete_implementations`, then normalize the available meaning into one execution-instructions view. Resolve the objective from a readable or uniquely relocated `task_file`; otherwise from `direct_scope` or the direct invocation; otherwise select the next incomplete `docs/plans/tasks/*-task-*.md` for an ad-hoc task invocation. When more than one source is present, the task file governs execution scope and value boundaries; consistent direct values augment it, while its technical How remains an evidence-correctable baseline. -For direct scope, derive operational details from the confirmed outcome, applicable artifacts, and repository evidence. Treat confirmed outcome, desired-future requirements, and non-goals in `governing_sources` as the value boundary; treat technical design content as the current implementation baseline, `target_paths` as investigation starting points, and supplied or derived `observable_verification` as completion evidence. Correction and incomplete items remain inside the same confirmed value boundary. Repository-local reversible choices and technical corrections proceed from representative evidence. +For direct scope, derive operational details from the outcome, applicable artifacts, and repository evidence. Treat the outcome, desired-future requirements, and non-goals in `governing_sources` as the value boundary; treat technical design content as the current implementation baseline, `target_paths` as investigation starting points, and supplied or derived `observable_verification` as completion evidence. Correction and incomplete items remain inside the same value boundary. Repository-local reversible choices and technical corrections proceed from representative evidence. ## Outcome and Change Boundary -Implement the confirmed outcome and the maintenance, tests, and adjacent corrections required to keep that outcome correct. `target_paths` and task-file Target Files guide initial investigation; the value boundary, governing sources, repository responsibilities, and observable verification determine the final changed set. Keep governing and reference documents read-only except for task progress and Investigation Notes explicitly owned by this workflow. Correct technical design, contracts, architecture, dependencies, and persistence details from repository evidence when the value boundary remains true. +Implement the outcome and the maintenance, tests, and adjacent corrections required to keep that outcome correct. `target_paths` and task-file Target Files guide initial investigation; the value boundary, governing sources, repository responsibilities, and observable verification determine the final changed set. Keep governing and reference documents read-only except for task progress and Investigation Notes explicitly owned by this workflow. Correct technical design, contracts, architecture, dependencies, and persistence details from repository evidence when the value boundary remains true. ## Mandatory Rules @@ -45,7 +45,7 @@ Deliver the outcome with contracts satisfied at their boundaries, errors propaga ## Design Surface Check (Before Mandatory Judgment) -Apply implementation-approach Design Convergence to the confirmed responsibility and starting paths. Challenge added design surface against current evidence, lower-surface alternatives, total complexity, and subtraction; include adjacent targets when the confirmed outcome's correctness or maintainability requires them. +Apply implementation-approach Design Convergence to the assigned responsibility and starting paths. Challenge added design surface against current evidence, lower-surface alternatives, total complexity, and subtraction; include adjacent targets when the outcome's correctness or maintainability requires them. ## Mandatory Judgment Criteria (Pre-implementation Check) @@ -74,20 +74,20 @@ Use the indicators to find plausible candidates and apply the authoritative boun 3. Continue with the repository-local reversible choice supported by that evidence. ### Step4: Core Mechanism Preservation Check -Preserve a mechanism when the confirmed outcome or desired-future requirements depend on its observable effect. Treat a mechanism specified only as technical How as a correctable design baseline. +Preserve a mechanism when the outcome or desired-future requirements depend on its observable effect. Treat a mechanism specified only as technical How as a correctable design baseline. □ Required core mechanism replaced by a simpler or weaker substitute, including one justified only by passing tests? □ Required core mechanism infeasible as specified? Any YES is corrected in implementation when the value boundary can remain true. Escalate only under the authoritative rule below. **Escalation boundary for unresolved judgment (authoritative rule for every check above):** -- Return `escalation_needed` when evidence shows the confirmed outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes. +- Return `escalation_needed` when evidence shows the outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes. - Return `escalation_needed` when an irreversible external action requires user authorization. - Otherwise resolve the technical choice from governing sources and representative repository evidence, record it, and continue. A changed interface, architecture, dependency, persistence detail, or observable UI/API output is not itself an escalation condition. ## Responsibility Boundaries **Scope**: Implementation and test creation. Quality checks and commits are outside scope. -**Policy**: Start implementation immediately (treat as approved); correct technical design and implementation discrepancies autonomously inside the confirmed value boundary. +**Policy**: Start implementation immediately (treat as approved); correct technical design and implementation discrepancies autonomously inside the value boundary. **Progress**: For task-file execution, sync checkbox state across its task file, work plan, and overall design document when each exists (`[ ]` → `[🔄]` → `[x]`). For prompt-only execution, update a tracking artifact only when the prompt explicitly assigns that update. ## Workflow @@ -102,7 +102,7 @@ Resolve the implementation objective through the input precedence above, derive 1. Extract investigation paths from the execution instructions 2. Read every resolved Investigation Target before editing. When a search hint is provided (e.g., `(§ Auth Flow)` or `(authenticateUser function)`), locate and focus on that section 3. Record brief Investigation Notes identified by symbol, function, contract, or section, covering key interfaces, flow, state transitions, and side effects; append them to the task file when one is provided. Reserve file:line for post-edit evidence that requires it. -4. When a declared Investigation Target path fails direct resolution, search by filename, supplied symbol or section hint, callers, and task or governing-artifact references. Use the best semantic matches supported by those sources, record the resolved evidence, and continue from the confirmed objective. For a `target_paths` entry intended for creation, inspect its existing parent and representative sibling +4. When a declared Investigation Target path fails direct resolution, search by filename, supplied symbol or section hint, callers, and task or governing-artifact references. Use the best semantic matches supported by those sources, record the resolved evidence, and continue from the objective. For a `target_paths` entry intended for creation, inspect its existing parent and representative sibling #### Governing Sources and Dependency Deliverables 1. Extract governing-source and dependency paths or unchanged governing values from the execution instructions @@ -129,7 +129,7 @@ Read relevant Design Doc sections (interface contracts, data structures, depende Applies when Pre-implementation Verification finds a dependency this task requires is absent or unimplemented (e.g., a Design Doc component marked "requires new creation"). -1. Determine whether a local, reversible construct — a local slice, or a contract-preserving stub/adapter inside the confirmed responsibility — preserves the required contract. +1. Determine whether a local, reversible construct — a local slice, or a contract-preserving stub/adapter inside the assigned responsibility — preserves the required contract. 2. Branch on the result: - One local, reversible approach preserves the contract → proceed with it and record the integration handoff (what the real dependency must later provide, and where it connects) in Investigation Notes. - No local construct preserves the current technical contract, or several constructs differ on an architectural trade-off → choose and implement the lowest-surface value-preserving correction from governing and representative repository evidence. Apply the authoritative escalation boundary only if no option preserves all value boundaries or an irreversible external action is required. @@ -215,7 +215,7 @@ Use this response when evidence establishes either authoritative escalation cond ```json { "status": "escalation_needed", - "reason": "[Which confirmed value boundaries cannot all remain true, or which irreversible external action requires authorization]", + "reason": "[Which value boundaries cannot all remain true, or which irreversible external action requires authorization]", "taskName": "[Task name being executed]", "evidence": ["[Observed governing and repository evidence]"], "requiredDecision": "[Value-boundary choice or exact irreversible action requiring authorization]" @@ -234,4 +234,4 @@ This gate runs immediately before producing the final JSON response. ☐ Test runs cited as `runnableCheck` evidence meet the substantive and executable rules in the `runnableCheck.result` field specification ☐ Final response is a single JSON with `status: "completed"`, `status: "blocked"`, or `status: "escalation_needed"` and matches the schema in Structured Response Specification -**ENFORCEMENT**: Return `escalation_needed` only when confirmed outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes, or when an irreversible external action requires authorization. Technical design, interface, architecture, dependency, persistence, and implementation corrections that preserve those boundaries remain implementation work. +**ENFORCEMENT**: Return `escalation_needed` only when the outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which changes, or when an irreversible external action requires authorization. Technical design, interface, architecture, dependency, persistence, and implementation corrections that preserve those boundaries remain implementation work. diff --git a/dev-workflows/agents/technical-designer.md b/dev-workflows/agents/technical-designer.md index 4787cf6f..483f13f1 100644 --- a/dev-workflows/agents/technical-designer.md +++ b/dev-workflows/agents/technical-designer.md @@ -1,6 +1,6 @@ --- name: technical-designer -description: Creates a scoped ADR batch or one backend/general Design Doc from confirmed requirements and decision-relevant repository evidence. Use when technical choices or implementation design need an approved artifact. +description: Creates a scoped ADR batch or one backend/general Design Doc from requirements and decision-relevant repository evidence. Use when technical choices or implementation design need an approved artifact. tools: Read, Write, Edit, MultiEdit, Glob, LS, Bash, WebSearch skills: - documentation-criteria @@ -25,17 +25,17 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow - **document_to_create**: `ADRBatch` or `DesignDoc` in create mode - **output_path**: Optional exact Design Doc destination; required when the caller splits one feature into multiple documents. Updates retain the existing path. - **Operation Mode**: `create` (default), `update`, or `reverse-engineer` -- **confirmed_requirement_context**: Exact approved PRD path, or the unchanged orchestrator-confirmed convergence record only when no approved PRD exists -- **structural_scale**: Orchestrator-confirmed `Medium` or `Large` scale for a Design Doc +- **requirement_context**: Exact approved PRD path, or the orchestrator's unchanged convergence record only when no approved PRD exists +- **structural_scale**: Orchestrator-selected `Medium` or `Large` scale for a Design Doc - **decision_materials**: Ordered array copied unchanged from the codebase analysis result at `decisionMaterials.candidateDecisionPoints` - **codebase_analysis**: Applicable focus areas and existing-behavior safeguards for a Design Doc -- **decision_points**: Orchestrator-confirmed decision points for an ADR batch, copied unchanged +- **decision_points**: Orchestrator-selected decision points for an ADR batch, copied unchanged - Existing document path or paths in update mode - **correction_findings**: Complete applied verification or review finding objects, copied verbatim with only their orchestrator dispositions added (update mode) - **adr_paths**: Accepted ADRs that constrain the Design Doc - Optional UI Spec, external-resource references, or prior-layer verification supplied by the caller -Use the orchestrator-confirmed outcome, scope, exclusions, Structural Scale, and document route. Report a contradiction with a governing source instead of silently changing that classification. +Use the outcome, scope, and exclusions from the requirement context and the orchestrator-selected Structural Scale and document route. Report a contradiction with a governing source instead of silently changing that classification. Create/update mode requires a current PRD carrier or convergence record. A scope-preserving update may preserve its existing carrier. Reverse-engineer mode records convergence as `N/A — reverse-engineered/as-is document`. @@ -43,7 +43,7 @@ Create/update mode requires a current PRD carrier or convergence record. A scope Use supplied `decision_materials` for an ADR batch and unchanged `codebase_analysis` for a Design Doc as the primary repository evidence: -- `decision_materials[].options` supplies repository-backed choices, repository fit, lifecycle cost drivers, and maintainability evidence for ADR selection; confirmed requirements supply product value; +- `decision_materials[].options` supplies repository-backed choices, repository fit, lifecycle cost drivers, and maintainability evidence for ADR selection; the requirements supply product value; - `codebase_analysis.decisionMaterials.reuse` and applicable `codebase_analysis.simplifications` reduce new implementation surface; - `codebase_analysis.decisionMaterials.invalidations` eliminates approaches; - `codebase_analysis.decisionMaterials.verification` constrains proof; @@ -54,23 +54,23 @@ Inspect only gaps that can change reuse, option validity, a selected decision, a ## ADR Batch — Create Mode -Create one ADR per supplied decision point and finish the complete batch before returning. If evidence no longer supports the confirmed Choice or Durability filter, return the contradiction for orchestrator resolution. +Create one ADR per supplied decision point and finish the complete batch before returning. If evidence no longer supports the orchestrator's Choice or Durability filter result, return the contradiction for orchestrator resolution. Before the first ADR write, Glob `docs/adr/ADR-[0-9][0-9][0-9][0-9]-*.md`, parse valid numeric prefixes, and assign contiguous numbers from `max + 1` in the supplied `decision_points` order. Use `0001` when no numbered ADR exists. Make every assigned path unique, confirm it is still absent immediately before its write, and return a blocking collision instead of overwriting. Use the assigned path order in the result. 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. 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. +1. Keep one technical question inside the scope of the requirements. +2. Compare every credible, materially distinct option using product value from the requirements, repository fit, total complexity, maintainability, material trade-offs, and reversibility. +3. Select the smallest sufficient option whose total complexity is justified by product value from the requirements. 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 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 the requirements activate them; external release execution and organizational rollout remain outside both artifacts. Use `Proposed` status for created ADRs. The orchestrator records user approval for the batch. ## Design Doc — Create Mode -Create the complete end-to-end technical design for the confirmed scope. Apply implementation-approach Design Convergence in active analysis, then record only the Selected Design and the evidence that justifies any added design surface. Create mode limits evidence collection to supplied artifacts, read-only repository inspection, and authoritative read-only sources. When a specific decision-changing premise remains unresolved, record it for verification; capability probes are reserved for the fresh review-triggered update gate below. +Create the complete end-to-end technical design for the scope of the requirements. Apply implementation-approach Design Convergence in active analysis, then record only the Selected Design and the evidence that justifies any added design surface. Create mode limits evidence collection to supplied artifacts, read-only repository inspection, and authoritative read-only sources. When a specific decision-changing premise remains unresolved, record it for verification; capability probes are reserved for the fresh review-triggered update gate below. Follow `references/design-template.md` in the documentation-criteria skill. Preserve these downstream guarantees whenever applicable: @@ -88,9 +88,9 @@ Sections and rows activate when their boundary exists. An authoritative referenc 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. +Acceptance criteria use the smallest representative set that proves the outcome and material failure boundaries. Verification uses the narrowest repository operation or test lane that can observe each required boundary. -Derive each acceptance criterion from one confirmed behavior. Add another boundary case when the same promise can fail independently there, such as a distinct state transition, persistence/publication boundary, compatibility path, or mode interacting with an existing branch. Consolidate cases that exercise the same failure and correction; generic happy/unhappy/edge categories create requirements only when they expose an independent failure. +Derive each acceptance criterion from one behavior in the requirements. Add another boundary case when the same promise can fail independently there, such as a distinct state transition, persistence/publication boundary, compatibility path, or mode interacting with an existing branch. Consolidate cases that exercise the same failure and correction; generic happy/unhappy/edge categories create requirements only when they expose an independent failure. Verify a current external technology, compatibility, performance, or security fact from an authoritative source only when its truth can change option selection, implementation, or verification. Record unresolved decision-changing facts for the verification loop. @@ -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. 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. +Update requested sections and dependent statements. For `correction_findings`, resolve each received defect within the 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 outcome, desired-future requirements, and non-goals stay true. If the 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 @@ -130,7 +130,7 @@ Document supplied inventory and existing behavior as-is. Trace each in-scope ent ## Completion Check -- No implementation scope exceeds confirmed requirements and required dependencies. +- No implementation scope exceeds the requirements and required dependencies. - 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. diff --git a/dev-workflows/skills/ai-development-guide/SKILL.md b/dev-workflows/skills/ai-development-guide/SKILL.md index b3c9e991..b0fff492 100644 --- a/dev-workflows/skills/ai-development-guide/SKILL.md +++ b/dev-workflows/skills/ai-development-guide/SKILL.md @@ -8,11 +8,11 @@ description: Applies language-agnostic and backend technical decision criteria, ## Value-First Engineering Inspect until the evidence identifies the lowest-total-complexity solution that delivers the required user, operator, or maintainer value while keeping the system correct and maintainable. -- Resolve verified problems within confirmed scope or dependencies required for the outcome; report other findings with their owning boundary and evidence without expanding the active change. +- Resolve verified problems within scope or dependencies required for the outcome; report other findings with their owning boundary and evidence without expanding the active change. - Introduce capabilities, infrastructure, abstractions, or speculative edge-case handling when a current outcome, verified constraint, or evidence-backed material risk requires them. -- Treat behavior-preserving maintenance inside the confirmed responsibility as current maintainer value when repository evidence shows it reduces change ambiguity, duplicate ownership, defect risk, or future implementation and verification cost without expanding observable product scope. +- Treat behavior-preserving maintenance inside the assigned responsibility as current maintainer value when repository evidence shows it reduces change ambiguity, duplicate ownership, defect risk, or future implementation and verification cost without expanding observable product scope. -Judge total complexity across every activated surface: user decisions, settings, modes, concepts, outputs, persistent state, and implementation paths, together with their UX, runtime, implementation, testing, documentation, and maintenance cost. Compare only dimensions that differ between viable approaches. Prefer reuse or no new mechanism when it delivers the same confirmed value and proof at lower total complexity. +Judge total complexity across every activated surface: user decisions, settings, modes, concepts, outputs, persistent state, and implementation paths, together with their UX, runtime, implementation, testing, documentation, and maintenance cost. Compare only dimensions that differ between viable approaches. Prefer reuse or no new mechanism when it delivers the same required value and proof at lower total complexity. ## Technical Anti-patterns (Red Flag Patterns) @@ -140,7 +140,7 @@ Keep concrete implementations separate while their apparent similarity is accide **Avoidance Methods**: - Before implementation, always search for similar functionality (using domain, responsibility, configuration patterns as keywords) - Similar functionality found → Verify that its contract, lifecycle, and repository usage are representative; reuse or extend it when compatible, otherwise record why it is not a valid model -- Similar functionality is technical debt → Repair it when it blocks the current outcome, was caused by the current change, or lies in confirmed scope; otherwise report it separately. Create an ADR when the repair requires an architectural decision +- Similar functionality is technical debt → Repair it when it blocks the current outcome, was caused by the current change, or lies in scope; otherwise report it separately. Create an ADR when the repair requires an architectural decision - No similar functionality exists → Implement new functionality following existing design philosophy - Preserve the evidence for each reuse, extend, separate, or repair decision in the applicable implementation or design record - **Reference representativeness check**: When adopting a pattern or dependency from nearby code, inspect the changed area and enough representative consumers or siblings to establish compatibility; expand only when competing patterns or a shared/public contract can change the choice @@ -184,7 +184,7 @@ Follow repository-declared command composition or ordering when it exists. Other ### Scope Expansion - Apply implementation/edit instructions to the accepted outcome and its governing scope. -- Treat explicit restrictions and quantities ("one", "this file", "only X") in the governing request or confirmed outcome, desired-future requirements, and non-goals as hard boundaries; treat technical-artifact How as a correctable baseline when repository evidence invalidates it without changing those boundaries +- Treat explicit restrictions and quantities ("one", "this file", "only X") in the governing request or the outcome, desired-future requirements, and non-goals as hard boundaries; treat technical-artifact How as a correctable baseline when repository evidence invalidates it without changing those boundaries - Treat referenced or expected paths as investigation starting points unless the governing source explicitly makes them exclusive - Copy/move/mirror requests preserve content verbatim; edit content only when requested - Port/translation requests preserve intent and behavior; adapt only what the destination context requires diff --git a/dev-workflows/skills/documentation-criteria/SKILL.md b/dev-workflows/skills/documentation-criteria/SKILL.md index 7f745120..9c5500b3 100644 --- a/dev-workflows/skills/documentation-criteria/SKILL.md +++ b/dev-workflows/skills/documentation-criteria/SKILL.md @@ -13,11 +13,11 @@ Each document fixes one class of decision that the repository alone cannot suppl - **PRD** — Fixes the business outcome and the acceptance criteria later work traces to. Its AC IDs are the traceability keys that the Design Doc, UI Spec, and test selection reuse; without them each consumer re-derives requirements from prose and the link between a test and the value it protects is lost. Implementation details belong to the Design Doc, selection rationale to an ADR, phases and task breakdown to the Work Plan. Later design, review, and test selection treat its content as governing, so a precondition held outside the repository change, such as release execution or organizational approval, appears in it only when the user's wording raises it. -- **ADR** — Records one durable technical choice and the options it beat, so later work can tell a deliberate decision from an accident. Without it a future change either re-runs the same comparison or silently reverses it. `Accepted` records the currently selected means, not an obligation to retain it: when later evidence supports a smaller sufficient choice, update or supersede the decision while the confirmed outcome, desired-future requirements, and non-goals remain true. End-to-end implementation design belongs to the Design Doc, schedule and repository tasks to the Work Plan. +- **ADR** — Records one durable technical choice and the options it beat, so later work can tell a deliberate decision from an accident. Without it a future change either re-runs the same comparison or silently reverses it. `Accepted` records the currently selected means, not an obligation to retain it: when later evidence supports a smaller sufficient choice, update or supersede the decision while the outcome, desired-future requirements, and non-goals remain true. End-to-end implementation design belongs to the Design Doc, schedule and repository tasks to the Work Plan. - **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. 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. +- **Design Doc** — Records the complete implementation design for the scope of the requirements: 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 requirement that describes such work is met by designing the capability it uses. When repository evidence invalidates technical How while the 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. Each task is repository work the executor completes and verifies during implementation using repository artifacts and its own output. @@ -49,7 +49,7 @@ A qualifying ADR decision point sets the floor at Medium because it creates a du ## ADR Decision Filters -Apply the Choice filter, then the Durability filter, to each technical topic inside the confirmed implementation scope. Apply them independently from Structural Scale, and check existing ADRs first. +Apply the Choice filter, then the Durability filter, to each technical topic inside the implementation scope. Apply them independently from Structural Scale, and check existing ADRs first. 1. **Choice requires judgment** — current requirements, accepted decisions, and representative repository evidence support at least two credible, materially distinct options whose selection requires comparison. 2. **Decision is durable** — choosing among those options materially changes responsibility, dependency direction, a shared contract, persistence, a technology dependency, reversibility, or lifecycle cost that future work must preserve or understand. diff --git a/dev-workflows/skills/documentation-criteria/references/adr-template.md b/dev-workflows/skills/documentation-criteria/references/adr-template.md index debdb11b..da261f42 100644 --- a/dev-workflows/skills/documentation-criteria/references/adr-template.md +++ b/dev-workflows/skills/documentation-criteria/references/adr-template.md @@ -6,7 +6,7 @@ A created ADR starts at `Proposed` and advances `Proposed` → `Accepted` → `Deprecated`/`Superseded`/`Rejected`. -`Accepted` records the currently selected means, not an obligation to retain it. When later evidence supports a smaller sufficient choice, update or supersede this decision while the confirmed outcome, desired-future requirements, and non-goals remain true. +`Accepted` records the currently selected means, not an obligation to retain it. When later evidence supports a smaller sufficient choice, update or supersede this decision while the outcome, desired-future requirements, and non-goals remain true. ## Context @@ -16,7 +16,7 @@ A created ADR starts at `Proposed` and advances `Proposed` → `Accepted` → `D - **Question**: [The technical choice requiring comparison and selection] - **Why a decision exists**: [Evidence for at least two credible, materially distinct options] -- **Scope boundary**: [Confirmed requirement or existing contract this decision serves] +- **Scope boundary**: [Requirement or existing contract this decision serves] ## Decision @@ -39,12 +39,12 @@ A created ADR starts at `Proposed` and advances `Proposed` → `Accepted` → `D Compare credible, materially distinct options supported by current requirements and repository evidence. The evidence determines how many options exist, and relative evidence-backed cost is sufficient. Add a Mermaid option-comparison diagram only when the relationship between options stays unclear in the table below. -| Option | Confirmed product value | Repository fit | Total complexity | Maintainability | Material trade-offs | Reversibility | +| Option | Product value from the requirements | Repository fit | Total complexity | Maintainability | Material trade-offs | Reversibility | |--------|-------------------------|----------------|------------------|-----------------|---------------------|---------------| | [Option 1] | [value required now] | [fit and evidence] | [materially different activated surfaces and lifecycle costs] | [fit with ownership and representative patterns] | [trade-offs] | [cost and conditions to reverse] | | [Option 2] | [value required now] | [fit and evidence] | [materially different activated surfaces and lifecycle costs] | [fit with ownership and representative patterns] | [trade-offs] | [cost and conditions to reverse] | -**Selected**: [The smallest sufficient option whose total complexity is justified by confirmed product value and repository evidence] +**Selected**: [The smallest sufficient option whose total complexity is justified by product value from the requirements and repository evidence] ## Consequences diff --git a/dev-workflows/skills/documentation-criteria/references/design-template.md b/dev-workflows/skills/documentation-criteria/references/design-template.md index b75daa37..fc98ba14 100644 --- a/dev-workflows/skills/documentation-criteria/references/design-template.md +++ b/dev-workflows/skills/documentation-criteria/references/design-template.md @@ -27,7 +27,7 @@ Lists each external resource this feature depends on with its feature-specific i ### Requirement Convergence -Records exclusions **the user decided** at requirement time. Mark the first two bullets `N/A — covered by PRD [path]` when a PRD holds them, or the whole section `N/A — reverse-engineer/as-is document`. Open questions stay here in every case because design readiness depends on them. This section contains confirmed requirements and boundaries; evaluation requests, speculative ideas, and unselected mechanisms remain only in pre-confirmation convergence context. +Records exclusions **the user decided** at requirement time. Mark the first two bullets `N/A — covered by PRD [path]` when a PRD holds them, or the whole section `N/A — reverse-engineer/as-is document`. Open questions stay here in every case because design readiness depends on them. This section contains the user-selected requirements and boundaries; evaluation requests, speculative ideas, and unselected mechanisms remain only in active convergence context. - **Outcome**: [one observable result this change must produce] - **Non-Goals**: [capability the user excluded | None — user confirmed there are none] @@ -93,7 +93,7 @@ Keywords determine test type and reduce ambiguity. The rows below demonstrate EARS syntax only. Replace their domain, values, messages, and thresholds with requirements from the PRD or accepted requirement analysis; none is a default product requirement. -Keep the smallest representative set of observable behaviors that has a stable repository-verifiable pass/fail condition. Use repository-controlled contract/interface proof instead of a live external connection unless the confirmed requirement needs that boundary. Include a performance threshold only with a sourced target and reproducible benchmark, and exact visual positioning only with an approved visual contract and deterministic comparison. Implementation details remain outside ACs. +Keep the smallest representative set of observable behaviors that has a stable repository-verifiable pass/fail condition. Use repository-controlled contract/interface proof instead of a live external connection unless a requirement needs that boundary. Include a performance threshold only with a sourced target and reproducible benchmark, and exact visual positioning only with an approved visual contract and deterministic comparison. Implementation details remain outside ACs. ### [Functional Requirement 1] @@ -198,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, traced to its originating requirement, accepted decision, or repository rule or contract] +- **Subtraction result**: [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/documentation-criteria/references/prd-template.md b/dev-workflows/skills/documentation-criteria/references/prd-template.md index d0fea276..1769f438 100644 --- a/dev-workflows/skills/documentation-criteria/references/prd-template.md +++ b/dev-workflows/skills/documentation-criteria/references/prd-template.md @@ -61,13 +61,13 @@ C4Context ### Future / Out of Scope -Record user-authored non-goals and any current exclusion required to make the MVP boundary executable. The table is limited to confirmed boundaries; evaluation requests, speculative ideas, and unselected possibilities remain only in pre-confirmation convergence context. Record `None — user confirmed there are none` when the user considered exclusions and found none. +Record user-authored non-goals and any current exclusion required to make the MVP boundary executable. The table is limited to these boundaries; evaluation requests, speculative ideas, and unselected possibilities remain only in active convergence context. Record `None — user confirmed there are none` when the user considered exclusions and found none. -Use `user` for a user-authored non-goal and `analysis` for a current exclusion required to make the confirmed MVP boundary executable. +Use `user` for a user-authored non-goal and `analysis` for a current exclusion required to make the MVP boundary executable. | Capability | Disposition | Origin | Reason | |---|---|---|---| -| [Confirmed non-goal or required current scope exclusion] | future / out-of-scope | user / analysis | [Governing scope reason] | +| [User-authored non-goal or required current scope exclusion] | future / out-of-scope | user / analysis | [Governing scope reason] | ## Non-Functional Requirements @@ -87,14 +87,14 @@ Use `user` for a user-authored non-goal and `analysis` for a current exclusion r - [Considerations for future scaling] ### Accessibility (when feature includes UI) -- Compliance standard (when established by an accepted organizational, legal, contractual, or confirmed product source): [standard] +- Compliance standard (when established by an accepted organizational, legal, contractual, or user-supplied product source): [standard] - Target assistive technologies: [Screen reader, keyboard operation, voice control, etc.] - Platform requirements: [e.g., app store review requirements] - Known constraints: [e.g., external library limitations] ## Success Criteria -State observable success for the confirmed outcome. Include only sourced quantitative/UI targets; in as-is documentation, distinguish observed measures from unknown business objectives. The examples below are optional shapes, not a required metric count. +State observable success for the outcome. Include only sourced quantitative/UI targets; in as-is documentation, distinguish observed measures from unknown business objectives. The examples below are optional shapes, not a required metric count. ### Quantitative Metrics 1. [Metric name]: [numeric target] measured by [method] within [timeframe] diff --git a/dev-workflows/skills/documentation-criteria/references/ui-spec-template.md b/dev-workflows/skills/documentation-criteria/references/ui-spec-template.md index 46180972..e96dc373 100644 --- a/dev-workflows/skills/documentation-criteria/references/ui-spec-template.md +++ b/dev-workflows/skills/documentation-criteria/references/ui-spec-template.md @@ -4,9 +4,9 @@ [Purpose and scope of this UI Specification in 2-3 sentences] -### Confirmed Requirement Context +### Requirement Context - PRD path: [docs/prd/xxx-prd.md | "N/A — based on requirements analysis output"] -- Feature scope: [Which confirmed requirements this UI Spec covers] +- Feature scope: [Which requirements this UI Spec covers] ### Design Source | Source | Path | Version | @@ -35,7 +35,7 @@ Lists each external resource this feature depends on with its feature-specific i ## AC Traceability (Prototype) -Map confirmed acceptance criteria to prototype references, preserving existing AC IDs when present. Skip this section if no prototype is provided. +Map acceptance criteria to prototype references, preserving existing AC IDs when present. Skip this section if no prototype is provided. | Criterion ID / Reference | Criterion Summary | Screen / State | Prototype Reference (element ID / path) | Adoption Decision | |-------|-----------|----------------|----------------------------------------|-------------------| @@ -76,7 +76,7 @@ Add a screen-transition or component-tree Mermaid diagram only when the material #### State x Display Matrix -The matrix contains one row for each state supported by confirmed requirements, approved UI direction, preserved behavior, or repository/design-system rules. +The matrix contains one row for each state supported by the requirements, approved UI direction, preserved behavior, or repository/design-system rules. | State | Trigger | Display | Interaction / Recovery | Evidence | |-------|---------|---------|------------------------|----------| diff --git a/dev-workflows/skills/implementation-approach/SKILL.md b/dev-workflows/skills/implementation-approach/SKILL.md index 84ebdcff..46ee41dc 100644 --- a/dev-workflows/skills/implementation-approach/SKILL.md +++ b/dev-workflows/skills/implementation-approach/SKILL.md @@ -33,7 +33,7 @@ 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. 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 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. +4. **Subtraction Check**: Remove each proposed addition and re-test its governing condition. Retain it only when the outcome, a required boundary, or necessary proof becomes unmet at its origin (a 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. diff --git a/dev-workflows/skills/recipe-add-integration-tests/SKILL.md b/dev-workflows/skills/recipe-add-integration-tests/SKILL.md index 479d208a..f6b93679 100644 --- a/dev-workflows/skills/recipe-add-integration-tests/SKILL.md +++ b/dev-workflows/skills/recipe-add-integration-tests/SKILL.md @@ -52,7 +52,7 @@ Invoke acceptance-test-generator using Agent tool: - `description`: "Generate test skeletons" - `design_docs`: Existing backend, frontend, or single-layer Design Doc paths from Step 1 - `ui_spec`: Existing UI Spec path when present -- `confirmed_requirement_context`: Approved PRD path or unchanged Design Doc Requirement Convergence record +- `requirement_context`: Approved PRD path or unchanged Design Doc Requirement Convergence record Follow subagents-orchestration-guide HC-06 to verify generated paths and coverage of empty lanes before Step 3. diff --git a/dev-workflows/skills/recipe-design/SKILL.md b/dev-workflows/skills/recipe-design/SKILL.md index 9deaeb71..bd4032ab 100644 --- a/dev-workflows/skills/recipe-design/SKILL.md +++ b/dev-workflows/skills/recipe-design/SKILL.md @@ -37,9 +37,9 @@ At each `Invoke` below, build the Agent prompt as a mechanical extraction: copy ## Step 1: Select the Governing Requirement Source -Use the approved PRD path when one exists. Otherwise use the confirmed requirements verbatim. +Use the approved PRD path when one exists. Otherwise use the requirements verbatim. -Set `confirmed_requirement_context` to the approved PRD path exactly. Only when no approved PRD exists, use the orchestrator-confirmed convergence record unchanged. +Set `requirement_context` to the approved PRD path exactly. Only when no approved PRD exists, use the orchestrator's convergence record unchanged. ## Step 2: Collect Decision Material @@ -52,10 +52,10 @@ prd_path: [approved PRD path] or, when no approved PRD exists: ```text -requirements: [confirmed requirements verbatim] +requirements: [requirements verbatim] ``` -Invoke once for the complete confirmed scope. Require one valid JSON result and let the analyzer discover affected paths, responsibility boundaries, and cross-layer contracts. Treat its focus areas as existing-behavior safeguards, not as new requirements. +Invoke once for the complete scope. Require one valid JSON result and let the analyzer discover affected paths, responsibility boundaries, and cross-layer contracts. Treat its focus areas as existing-behavior safeguards, not as new requirements. This independent discovery keeps scope and option convergence grounded in repository evidence rather than the orchestrator's unverified implementation hypothesis. @@ -69,21 +69,21 @@ Determine Structural Scale from outcomes and responsibility boundaries. File cou Resolve `decisionMaterials.candidateDecisionPoints` against the governing requirement source, applicable `simplifications`, `reuse`, and `invalidations`. Remove a point when that evidence already converges on one sufficient approach. For each remaining item, apply documentation-criteria filters in order: -1. Choice requires judgment between at least two credible, materially distinct options inside confirmed scope. +1. Choice requires judgment between at least two credible, materially distinct options inside the scope of the requirements. 2. The selection has durable material impact. Record every passing item as `adrDecisionPoints`; an empty list routes directly to the Design Doc. ADR creation is limited to items that pass both filters. Present the requirement-convergence Scope Confirmation. Place target responsibilities with their strongest file evidence, applicable simplifications with their conditions, and each qualifying ADR decision point with its filter evidence or `none` under **Decision evidence**; place Structural Scale with its boundary rationale and the recommended document route under **Workflow**. -Offer proceed, or correct scope and re-run analysis. Ask a question only when its answer can change a convergence field, the confirmed outcome, or scope. Continue only when every convergence field is `ready` or `weak-but-explicit`. `[Stop: Scope confirmation]`. +Offer proceed, or correct scope and re-run analysis. Ask a question only when its answer can change a convergence field, the outcome, or scope. Continue only when every convergence field is `ready` or `weak-but-explicit`. `[Stop: Scope confirmation]`. ## Step 4: Create and Approve an ADR Batch When Needed When `adrDecisionPoints` is non-empty: -1. Invoke `dev-workflows:technical-designer` once with exact inputs: `document_to_create: ADRBatch`; `confirmed_requirement_context`; `decision_points` as the ordered `adrDecisionPoints` confirmed in Step 3, unchanged; and `decision_materials` as the corresponding objects from Step 2 `decisionMaterials.candidateDecisionPoints`, copied unchanged in that order. -2. Invoke `dev-workflows:document-reviewer` once with exact inputs: `doc_type: ADRBatch`, `targets: [all returned paths]`, and `confirmed_requirement_context`. +1. Invoke `dev-workflows:technical-designer` once with exact inputs: `document_to_create: ADRBatch`; `requirement_context`; `decision_points` as the ordered `adrDecisionPoints` from Step 3, unchanged; and `decision_materials` as the corresponding objects from Step 2 `decisionMaterials.candidateDecisionPoints`, copied unchanged in that order. +2. Invoke `dev-workflows:document-reviewer` once with exact inputs: `doc_type: ADRBatch`, `targets: [all returned paths]`, and `requirement_context`. 3. Route the reviewer verdict first: `pass` proceeds with `issues: []`; `needs_revision` applies Review Resolution, updates one ADR per path serially, and re-reviews the complete batch; `rejected` resolves the governing-source conflict before another review. 4. Present one batch decision after Review Resolution converges, including a decline-only result; unresolved governing-source conflicts still block approval. `[Stop: ADR batch approval]`. 5. After user approval, update each ADR status to `Accepted` and verify the changed status. @@ -95,7 +95,7 @@ Create the complete MVP implementation design from reviewed artifacts and unchan Invoke `dev-workflows:technical-designer` with exactly: - `document_to_create: DesignDoc`; -- `confirmed_requirement_context`; +- `requirement_context`; - `structural_scale`; - `adr_paths: [accepted paths or []]`; - `codebase_analysis: [complete Step 2 JSON unchanged]`. @@ -112,11 +112,11 @@ Apply Review Resolution to every discrepancy before document review. Send only ` ## Step 7: Review and Approve -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. +Invoke `dev-workflows:document-reviewer` with exact inputs: `doc_type: DesignDoc`, `target`, `review_context: creation`, the original user requirements verbatim as `requirements_verbatim`, `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 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. +- `rejected`: resolve technical governing-source conflicts through Review Resolution; ask the user only when the 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. @@ -124,7 +124,7 @@ Present the Design Doc, accepted ADR paths, resolved limitations/declines, and d ## Completion Criteria -- Scope and Structural Scale were confirmed from outcomes and responsibility boundaries. +- Scope and Structural Scale were determined from outcomes and responsibility boundaries. - ADRs exist only for decision points passing both filters, and the complete batch received one review and approval. - A Design Doc exists regardless of whether ADRs were needed. - Applicable existing-behavior, contract, assumption, equivalence, and verification safeguards reached the Design Doc. diff --git a/dev-workflows/skills/recipe-diagnose/SKILL.md b/dev-workflows/skills/recipe-diagnose/SKILL.md index 687bd7f1..eb3e1ae6 100644 --- a/dev-workflows/skills/recipe-diagnose/SKILL.md +++ b/dev-workflows/skills/recipe-diagnose/SKILL.md @@ -135,7 +135,7 @@ Continue investigation while an available action can advance a material gap. Com ### Step 5: Solution Boundary -After coverage is closed, pass the complete verified cause set to solver. Ownership, contract, and technical design corrections are ordinary solution candidates when they preserve the confirmed outcome, desired-future requirements, and non-goals; detecting a design gap does not create a user decision. If evidence shows those value boundaries cannot all remain true, or a proposed remedy requires authorization for an irreversible external action, report that exact boundary with the solution evidence instead of inventing a choice. +After coverage is closed, pass the complete verified cause set to solver. Ownership, contract, and technical design corrections are ordinary solution candidates when they preserve the outcome, desired-future requirements, and non-goals; detecting a design gap does not create a user decision. If evidence shows those value boundaries cannot all remain true, or a proposed remedy requires authorization for an irreversible external action, report that exact boundary with the solution evidence instead of inventing a choice. ### Step 6: Solution Derivation (solver) diff --git a/dev-workflows/skills/recipe-implement/SKILL.md b/dev-workflows/skills/recipe-implement/SKILL.md index acf22580..d1fcf62c 100644 --- a/dev-workflows/skills/recipe-implement/SKILL.md +++ b/dev-workflows/skills/recipe-implement/SKILL.md @@ -26,7 +26,7 @@ Before the first finding disposition, read `references/review-resolution.md` fro - Execute one step at a time in the defined flow (Large/Medium/Small scale) - When flow specifies "Execute document-reviewer" → Execute it immediately - **Stop at every `[Stop: ...]` marker** → Wait for explicit user confirmation before proceeding -3. **Enter autonomous mode** after confirmed Small requirements or Medium/Large batch approval +3. **Enter autonomous mode** after user confirmation at the Requirements stop for Small, or Medium/Large batch approval At each Agent invocation below, build the prompt as a mechanical extraction: copy the named source values into the exact fields, apply only the declared serialization, then invoke immediately. @@ -63,7 +63,7 @@ When continuing existing flow, verify: Execute Skill: requirement-convergence before running the hearing protocol. -Build and judge the convergence record from the user's retained wording, using requirement-analyzer `scopeEvidence` and `costEvidence` as supporting facts, then run the requirement-convergence hearing protocol. After the requirements are confirmed, apply the subagents-orchestration-guide Small evidence gate before assigning the final Structural Scale; when the gate is unresolved, invoke codebase-analyzer before routing. +Build and judge the convergence record from the user's retained wording, using requirement-analyzer `scopeEvidence` and `costEvidence` as supporting facts, then run the requirement-convergence hearing protocol. After the user answers the requirements stop, apply the subagents-orchestration-guide Small evidence gate before assigning the final Structural Scale; when the gate is unresolved, invoke codebase-analyzer before routing. When user responds to questions: - Update the orchestrator-owned convergence record from the answer, then update the Structural Scale judgment through the Small evidence gate. @@ -97,7 +97,7 @@ After Structural Scale is determined, follow only that scale's applicable path. ### Task Execution Quality Cycle (4-Step Cycle per Task) **Per-task cycle** (complete each task before starting next): -1. **Agent tool** (subagent_type: "dev-workflows:task-executor") → Record the current HEAD as `diffBase`; pass `task_file: [path]` when one exists, otherwise pass `direct_scope` as the confirmed outcome and exclusions, `governing_sources`, `target_paths`, and `observable_verification` +1. **Agent tool** (subagent_type: "dev-workflows:task-executor") → Record the current HEAD as `diffBase`; pass `task_file: [path]` when one exists, otherwise pass `direct_scope` as the convergence record's outcome and exclusions, `governing_sources`, `target_paths`, and `observable_verification` 2. Check task-executor response: - `status: escalation_needed` or `blocked` → Apply subagents-orchestration-guide Specialist Result Acceptance - `requiresTestReview` is `true` → Identify the changed integration/E2E test files in the current changes and invoke integration-test-reviewer with them as `changedTestFiles`, plus `diffBase`, optional `taskFile`, prompt-only claims, and `mutationEvidence` diff --git a/dev-workflows/skills/recipe-plan/SKILL.md b/dev-workflows/skills/recipe-plan/SKILL.md index 8fa1b9c4..9068c095 100644 --- a/dev-workflows/skills/recipe-plan/SKILL.md +++ b/dev-workflows/skills/recipe-plan/SKILL.md @@ -52,7 +52,7 @@ Follow the planning process below: - Report when none exist; when multiple exist, present them for selection ### Step 2: Test Skeleton Generation - - Invoke acceptance-test-generator with `design_docs: [selected Design Doc path]` and `confirmed_requirement_context` as the approved PRD path named by its Requirement Convergence section, or that section's unchanged convergence record when no PRD exists + - Invoke acceptance-test-generator with `design_docs: [selected Design Doc path]` and `requirement_context` as the approved PRD path named by its Requirement Convergence section, or that section's unchanged convergence record when no PRD exists - Follow subagents-orchestration-guide HC-06 for generated-path and empty-lane coverage checks - Pass every non-null generated skeleton path to the next process; treat an evidence-backed empty lane as complete for that lane and continue to the next process @@ -74,7 +74,7 @@ Invoke document-reviewer to review the work plan: ### Step 5: Present for Approval - Present the reviewed work plan to the user for batch approval. If the user requests changes, re-invoke work-planner with the user's requested changes verbatim and re-run Step 4. -- Return to the requirements gate only when confirmed outcome, desired-future requirements, and non-goals cannot all remain true without a user choice. +- Return to the requirements gate only when the outcome, desired-future requirements, and non-goals cannot all remain true without a user choice. ## Response at Completion diff --git a/dev-workflows/skills/recipe-review/SKILL.md b/dev-workflows/skills/recipe-review/SKILL.md index 8d8b4390..eec33915 100644 --- a/dev-workflows/skills/recipe-review/SKILL.md +++ b/dev-workflows/skills/recipe-review/SKILL.md @@ -98,7 +98,7 @@ Approve the proposed changes: This review command authorizes analysis; use AskUserQuestion to obtain separate implementation authority. The batch option is **"approve all proposed `apply` routes"** and its scope consists exclusively of those routes. When the approved change set is empty, proceed directly to Step 9. -Pass approved findings, routes, covered files/sections, and any stated total size budget to update or fix agents. Before re-validation, map every diff hunk to an approved finding or required consistency update. Remove accidental unmapped changes; when a necessary change would alter a confirmed value boundary or explicit size constraint, return to Requirement Change Detection. +Pass approved findings, routes, covered files/sections, and any stated total size budget to update or fix agents. Before re-validation, map every diff hunk to an approved finding or required consistency update. Remove accidental unmapped changes; when a necessary change would alter a value boundary or explicit size constraint, return to Requirement Change Detection. ### Step 5: Design-Side Update @@ -130,9 +130,9 @@ Run this step only when the user routed at least one finding to `d`. When no `d` Invoke task-executor using Agent tool: - `subagent_type`: "dev-workflows:task-executor" - `description`: "Execute review fixes" -- `direct_scope`: Apply the approved code-side corrections within the confirmed review scope and stated total size budget +- `direct_scope`: Apply the approved code-side corrections within the review scope and stated total size budget - `governing_sources`: The reviewed Design Doc and accepted requirement or ADR paths -- `target_paths`: The implementation and test paths confirmed for the approved code-side routes +- `target_paths`: The implementation and test paths identified for the approved code-side routes - `observable_verification`: The focused tests or observable contract checks named by the findings and governing sources pass - `correction_findings`: Complete reviewer finding objects verbatim, with only their orchestrator dispositions added diff --git a/dev-workflows/skills/requirement-convergence/SKILL.md b/dev-workflows/skills/requirement-convergence/SKILL.md index bd20961f..b51e0959 100644 --- a/dev-workflows/skills/requirement-convergence/SKILL.md +++ b/dev-workflows/skills/requirement-convergence/SKILL.md @@ -9,7 +9,7 @@ description: Separates the outcome a change must produce from the requirements p Requirements arrive bloated, ambiguous, or aimed at the wrong outcome. A capable model reconciles all three into a coherent plan and builds it faithfully — delivering exactly what was asked for when what was asked for was wrong. -This skill converges **what to build**. How to build it, and which documents the change requires, are settled after the what is. +This skill converges **what to build**. How to build it, and which documents the change requires, come after the what. ## Convergence Fields @@ -49,14 +49,14 @@ Render this shape at every requirements confirmation stop, whether or not the he | Section | Contents | |---------|----------| -| **Confirmed scope** | The requirements and exclusions the user has already selected, in the user's wording | +| **User-selected scope** | The requirements and exclusions the user has already selected, in the user's wording | | **Decision evidence** | Each material observed fact with its source, followed by what that fact can change about scope, outcome, or cost | | **User decisions** | One question per convergence field below `ready` (Hearing Protocol Step 1), followed by the scope, outcome, or cost effects of its materially different answers | | **Workflow** | Rough cost band with the unknowns that remain, Structural Scale, and the selected document and workflow route | -Keeping the first three sections separate is what makes the decision informable: merged, the reader cannot tell which line is the user's own settled boundary, which is a repository observation, and which is still open. +Keeping the first three sections separate is what makes the decision informable: merged, the reader cannot tell which line is the user's own selection, which is a repository observation, and which is still open. -Only an explicit user answer moves an item from **User decisions** into **Confirmed scope**. Because Step 2 records the user's own wording, pose each open decision as a question and let the user supply its answer. The orchestrator owns **Workflow** and presents it as a selected route. +Only an explicit user answer moves an item from **User decisions** into **User-selected scope**. Because Step 2 records the user's own wording, pose each open decision as a question and let the user supply its answer. The orchestrator owns **Workflow** and presents it as a selected route. ## Storage Protocol diff --git a/dev-workflows/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows/skills/subagents-orchestration-guide/SKILL.md index caac3770..38f28531 100644 --- a/dev-workflows/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows/skills/subagents-orchestration-guide/SKILL.md @@ -27,27 +27,27 @@ Build and judge the `convergence` record in the orchestrator with the requiremen ### Small Evidence Gate -Classify Small when `scopeEvidence.executionRoute.status` is `evident`, that route remains inside one responsibility, and every `costEvidence.unknowns` item is proven invariant to boundaries, persistence/shared contracts, and potentially durable choices. Positive route evidence identifies the supported route; an empty alternatives list supplies supporting context. When confirmed requirements remain unresolved at this gate, invoke codebase-analyzer before assigning Structural Scale. Its result supports Small when `analysisScope` and `currentPath` establish one repository-supported route inside one responsibility and every `candidateDecisionPoints`, `unknowns`, and `limitations` item is proven classification-invariant. Other observed boundaries and outcomes route Medium or Large. Reuse that result as the Medium design analysis when the confirmed requirements remain unchanged. For Large, treat it as routing evidence, create and approve the PRD, then run the design analysis against the approved `prd_path`. ADR qualification occurs after codebase-analyzer returns credible technical options and the scope is confirmed. +Classify Small when `scopeEvidence.executionRoute.status` is `evident`, that route remains inside one responsibility, and every `costEvidence.unknowns` item is proven invariant to boundaries, persistence/shared contracts, and potentially durable choices. Positive route evidence identifies the supported route; an empty alternatives list supplies supporting context. When the requirements remain unresolved at this gate, invoke codebase-analyzer before assigning Structural Scale. Its result supports Small when `analysisScope` and `currentPath` establish one repository-supported route inside one responsibility and every `candidateDecisionPoints`, `unknowns`, and `limitations` item is proven classification-invariant. Other observed boundaries and outcomes route Medium or Large. Reuse that result as the Medium design analysis when the requirements remain unchanged. For Large, treat it as routing evidence, create and approve the PRD, then run the design analysis against the approved `prd_path`. ADR qualification occurs after codebase-analyzer returns credible technical options and the scope has passed the requirements stop. ### Requirement Change Detection During Flow -After an analysis result returns, compare each user-facing or operational responsibility it exposes against the confirmed scope. When either leaving that responsibility as it is or changing it would alter the confirmed outcome or an exclusion, return it through the requirements gate before dependent design work; a technical choice about how to satisfy the confirmed scope continues through the design owners instead. +After an analysis result returns, compare each user-facing or operational responsibility it exposes against the scope in the convergence record. When either leaving that responsibility as it is or changing it would alter the outcome or an exclusion, return it through the requirements gate before dependent design work; a technical choice about how to satisfy that scope continues through the design owners instead. -Treat a proposed change to the confirmed outcome, desired-future requirements, or non-goals as a requirement change. When evidence shows those value boundaries cannot all remain true, stop at the requirements gate and ask the user which boundary changes. A technical design or implementation correction that preserves them is not a requirement change, including removal of a technical choice that works but is no longer necessary; passage through an earlier phase does not establish that its means remain necessary. Update each affected technical artifact and resume from the earliest affected technical gate while preserving outputs that remain valid. +Treat a proposed change to the outcome, desired-future requirements, or non-goals as a requirement change. When evidence shows those value boundaries cannot all remain true, stop at the requirements gate and ask the user which boundary changes. A technical design or implementation correction that preserves them is not a requirement change, including removal of a technical choice that works but is no longer necessary; passage through an earlier phase does not establish that its means remain necessary. Update each affected technical artifact and resume from the earliest affected technical gate while preserving outputs that remain valid. -**Requirement reopening after codebase analysis**: When the first codebase-analyzer result after requirement confirmation shows existing behavior that serves a confirmed requirement's need and falls short only of extra behavior that requirement specifies, whichever field reports it, present it with its evidence and cost effect at one requirements stop before UI Spec, ADR, or Design Doc work, and let the user keep or change the requirement. Requirements are confirmed before any code is read, and every later phase builds and reviews against them without questioning them, so this is the one point where repository evidence can reduce them; judging such evidence as ruled out by the requirement removes the user's only chance to weigh it. Apply the answer through Handling Requirement Changes and continue; later analyses do not reopen requirements this way. +**Requirement reopening after codebase analysis**: When the first codebase-analyzer result after requirement confirmation shows existing behavior that serves a requirement's need and falls short only of extra behavior that requirement specifies, whichever field reports it, present it with its evidence and cost effect at one requirements stop before UI Spec, ADR, or Design Doc work, and let the user keep or change the requirement. The user selects requirements before any code is read, and every later phase builds and reviews against them without questioning them, so this is the one point where repository evidence can reduce them; judging such evidence as ruled out by the requirement removes the user's only chance to weigh it. Apply the answer through Handling Requirement Changes and continue; later analyses do not reopen requirements this way. ## Orchestration Principles ### Outcome Stewardship -The orchestrator steers the workflow toward the smallest sufficient set of deliverables and changes that achieves the confirmed outcome while satisfying binding constraints and required verification. Evaluate specialist proposals against that boundary before routing work. +The orchestrator steers the workflow toward the smallest sufficient set of deliverables and changes that achieves the outcome while satisfying binding constraints and required verification. Evaluate specialist proposals against that boundary before routing work. -Preserve specialist evidence ownership and approved artifacts as semantic sources so the workflow converges on the confirmed MVP; orchestrator-authored investigation targets, restatements, or follow-on instructions bias evidence and create unreviewed scope. +Preserve specialist evidence ownership and approved artifacts as semantic sources so the workflow converges on the MVP; orchestrator-authored investigation targets, restatements, or follow-on instructions bias evidence and create unreviewed scope. ### Delegation Boundary: What vs How -Pass the governing requirement source and the specialist's expected action. Investigation specialists discover affected paths and responsibility boundaries; artifact and execution specialists receive the confirmed paths or scope they must act on. Each specialist determines its execution method from repository evidence and applicable artifacts. +Pass the governing requirement source and the specialist's expected action. Investigation specialists discover affected paths and responsibility boundaries; artifact and execution specialists receive the paths or scope they must act on. Each specialist determines its execution method from repository evidence and applicable artifacts. **Decision precedence for routing**: 1. User instructions (explicit requests or constraints) @@ -56,10 +56,10 @@ Pass the governing requirement source and the specialist's expected action. Inve 4. Specialist judgment **Scope source classification**: -- An explicit restriction in the user instruction or confirmed outcome, desired-future requirements, or non-goals is a hard boundary. A technical artifact is the primary implementation baseline, but its How is corrected through the affected technical artifacts when repository evidence invalidates it without changing those value boundaries. +- An explicit restriction in the user instruction or the outcome, desired-future requirements, or non-goals is a hard boundary. A technical artifact is the primary implementation baseline, but its How is corrected through the affected technical artifacts when repository evidence invalidates it without changing those value boundaries. - Target paths and task-file file lists are investigation starting points and expected evidence unless their governing source explicitly makes them exclusive. -- Changes to adjacent files proceed when repository evidence shows they are required by the same confirmed outcome, responsibility, contract, or consistency rule. -- Unrelated improvements remain outside the active change. A proposed change to the confirmed outcome, desired-future requirements, or non-goals returns to the requirements gate. Authorization for an irreversible external action returns to the authority gate. Technical design, contract, and implementation changes that preserve the confirmed value boundaries proceed through their affected technical artifacts. +- Changes to adjacent files proceed when repository evidence shows they are required by the same outcome, responsibility, contract, or consistency rule. +- Unrelated improvements remain outside the active change. A proposed change to the outcome, desired-future requirements, or non-goals returns to the requirements gate. Authorization for an irreversible external action returns to the authority gate. Technical design, contract, and implementation changes that preserve those value boundaries proceed through their affected technical artifacts. Before routing specialist output, validate each claim that controls the next workflow decision against the highest applicable source above. Route according to that source; specialist judgment governs decisions left unresolved by items 1-3. @@ -67,7 +67,7 @@ Before routing specialist output, validate each claim that controls the next wor Each specialist's agent definition owns its canonical result shape. As receiver, the orchestrator chooses the next action from the result's semantic content, governing sources, produced artifacts, and repository state. Semantically equivalent labels, omitted optional fields, and absent transition labels remain acceptable when those sources support the next action. Resolve operational gaps through inspection or repository-local reversible judgment and continue unaffected work. -Continue incomplete implementation while repository evidence supplies an action that advances the confirmed outcome. When current authority and evidence cannot advance required implementation, finish with an incomplete report containing the remaining work and observed evidence. Treat a proof-only limitation differently: perform recovery available within the current authority and scope, run every available check, retain the complete limitation result, establish the recipe's normal reversible task boundary, and continue remaining tasks. Retry retained limitations before final verification and report only those that remain. Claim only the proof actually observed. User interaction is reserved for choosing a change to confirmed value boundaries or authorizing an irreversible external action. +Continue incomplete implementation while repository evidence supplies an action that advances the outcome. When current authority and evidence cannot advance required implementation, finish with an incomplete report containing the remaining work and observed evidence. Treat a proof-only limitation differently: perform recovery available within the current authority and scope, run every available check, retain the complete limitation result, establish the recipe's normal reversible task boundary, and continue remaining tasks. Retry retained limitations before final verification and report only those that remain. Claim only the proof actually observed. User interaction is reserved for choosing a change to value boundaries or authorizing an irreversible external action. ### Review Resolution @@ -94,19 +94,19 @@ 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 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. +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 user-visible outcome from it or the requirement context alongside major internal responsibility, contract, or refactoring changes, so the user can judge whether to proceed. | Phase | Stop Point | User Action Required | |-------|------------|---------------------| | Requirements | After requirement-analyzer completes | Answer the requirement-convergence hearing, confirm the recorded requirements match their intent, then approve proceeding | | PRD | After document-reviewer completes PRD review | Approve completing the PRD phase and proceeding | -| Requirement reopening | After the first codebase-analyzer result when it shows existing behavior that falls short of a confirmed requirement only by extra behavior that requirement specifies | Keep or change each affected requirement | +| Requirement reopening | After the first codebase-analyzer result when it shows existing behavior that falls short of a requirement only by extra behavior that requirement specifies | Keep or change each affected requirement | | UI Spec | After document-reviewer completes an applicable UI Spec review | Approve completing the UI Spec phase and proceeding | | ADR batch | After document-reviewer reviews the complete qualifying batch | Approve completing the ADR batch phase and proceeding | | Design | After design-sync completes consistency verification | Approve completing the design phase and proceeding | | Work Plan | After work plan review (document-reviewer, doc_type WorkPlan; Medium/Large) completes | Batch approval: authorize implementation within this outcome | -**After applicable implementation authorization**: Confirmed Small requirements or Medium/Large batch approval start autonomous execution, which continues until completion or an escalation condition is reached. +**After applicable implementation authorization**: User confirmation at the Requirements stop for Small, or Medium/Large batch approval, starts autonomous execution, which continues until completion or an escalation condition is reached. ## Scale Determination and Document Requirements @@ -151,15 +151,15 @@ Use create mode for initial documents. For requirement-driven revisions, invoke | Medium | requirement-analyzer → codebase-analyzer → requirement reopening when applicable → conditional external/UI analysis and UI Spec → optional ADR batch/review/approval → Design Doc → code-verifier/Review Resolution → document-reviewer → design-sync → acceptance-test-generator → work-planner → work plan review → task-decomposer | | Small | requirement-analyzer → conditional codebase-analyzer when the Small evidence gate is unresolved → direct task execution (no Work Plan) | -The requirement-convergence and external-resource hearings run in the orchestrator. In an implementation workflow, confirmation at the Requirements stop authorizes the confirmed Small direct scope. Medium/Large implementation begins after Work Plan batch approval. +The requirement-convergence and external-resource hearings run in the orchestrator. In an implementation workflow, confirmation at the Requirements stop authorizes the Small direct scope. Medium/Large implementation begins after Work Plan batch approval. Rules: - When documentation-criteria requires a UI Spec, complete it before ADR qualification and Design Doc creation - An ADR batch is optional; the Design Doc is mandatory for Medium/Large work even when ADRs exist -- When the Small evidence gate is unresolved, invoke codebase-analyzer with confirmed `requirements` to resolve routing. Reuse that result for unchanged Medium scope. For Large, create and approve the PRD first, then invoke codebase-analyzer for design with only `prd_path`; the pre-scale result remains routing evidence because the approved PRD becomes the governing design source. For Medium already established by positive boundary evidence, invoke once with confirmed `requirements` -- When a UI Spec applies, invoke ui-analyzer with that same governing-source choice plus existing `ui_spec_path`, decision-relevant `prototype_path`, and selected `external_resource_refs` or `[]`; invoke ui-spec-designer with `confirmed_requirement_context` as the approved PRD path exactly or, only when none exists, the unchanged confirmed convergence record, plus the complete unchanged `ui_analysis`, applicable unchanged `codebase_analysis`, optional `prototype_path`, and `external_resource_refs` or `[]`. A prototype does not state how far it is meant to be followed — one team hands over a rendering to implement as is, another a rough sketch of intent — so when a `prototype_path` is present, pass `prototype_reference_strength` to ui-spec-designer: `binding` when implementation follows the prototype's rendering, `reference` when only what the UI Spec records reaches implementation. Resolve it from what the user already stated about the prototype, and ask only when neither reading is supported -- Before ADR qualification, use the governing source plus `reuse` and `invalidations` to remove questions that already have one sufficient approach. Apply documentation-criteria Choice then Durability filters only to the remaining `candidateDecisionPoints`. When non-empty, invoke each owning technical-designer with `document_to_create: ADRBatch`, `confirmed_requirement_context` as the approved PRD path exactly or, only when none exists, the unchanged confirmed convergence record, ordered confirmed `decision_points` unchanged, and the corresponding `candidateDecisionPoints` objects unchanged as `decision_materials`; add an approved `ui_spec_path` only when it constrains a frontend decision. Run owner batches serially, review all returned paths once with `doc_type: ADRBatch`, and obtain one user approval. After approval, set every approved ADR to `Accepted` and verify the status updates. For corrections, group findings by ADR path and invoke update mode once per path before re-reviewing the complete batch. An empty result proceeds directly to the Design Doc -- Invoke the Design Doc owner with `document_to_create: DesignDoc`, `confirmed_requirement_context` as the approved PRD path exactly or, only when none exists, the unchanged confirmed convergence record, `structural_scale`, unchanged `codebase_analysis`, optional unchanged `ui_analysis`, and accepted `adr_paths`; frontend/fullstack invocations add their named UI or layer artifact paths and distinct `output_path` destinations when splitting a feature across documents +- When the Small evidence gate is unresolved, invoke codebase-analyzer with the convergence record's `requirements` to resolve routing. Reuse that result for unchanged Medium scope. For Large, create and approve the PRD first, then invoke codebase-analyzer for design with only `prd_path`; the pre-scale result remains routing evidence because the approved PRD becomes the governing design source. For Medium already established by positive boundary evidence, invoke once with the convergence record's `requirements` +- When a UI Spec applies, invoke ui-analyzer with that same governing-source choice plus existing `ui_spec_path`, decision-relevant `prototype_path`, and selected `external_resource_refs` or `[]`; invoke ui-spec-designer with `requirement_context` as the approved PRD path exactly or, only when none exists, the unchanged convergence record, plus the complete unchanged `ui_analysis`, applicable unchanged `codebase_analysis`, optional `prototype_path`, and `external_resource_refs` or `[]`. A prototype does not state how far it is meant to be followed — one team hands over a rendering to implement as is, another a rough sketch of intent — so when a `prototype_path` is present, pass `prototype_reference_strength` to ui-spec-designer: `binding` when implementation follows the prototype's rendering, `reference` when only what the UI Spec records reaches implementation. Resolve it from what the user already stated about the prototype, and ask only when neither reading is supported +- Before ADR qualification, use the governing source plus `reuse` and `invalidations` to remove questions that already have one sufficient approach. Apply documentation-criteria Choice then Durability filters only to the remaining `candidateDecisionPoints`. When non-empty, invoke each owning technical-designer with `document_to_create: ADRBatch`, `requirement_context` as the approved PRD path exactly or, only when none exists, the unchanged convergence record, the ordered `decision_points` that pass both filters unchanged, and the corresponding `candidateDecisionPoints` objects unchanged as `decision_materials`; add an approved `ui_spec_path` only when it constrains a frontend decision. Run owner batches serially, review all returned paths once with `doc_type: ADRBatch`, and obtain one user approval. After approval, set every approved ADR to `Accepted` and verify the status updates. For corrections, group findings by ADR path and invoke update mode once per path before re-reviewing the complete batch. An empty result proceeds directly to the Design Doc +- Invoke the Design Doc owner with `document_to_create: DesignDoc`, `requirement_context` as the approved PRD path exactly or, only when none exists, the unchanged convergence record, `structural_scale`, unchanged `codebase_analysis`, optional unchanged `ui_analysis`, and accepted `adr_paths`; frontend/fullstack invocations add their named UI or layer artifact paths and distinct `output_path` destinations when splitting a feature across documents - Resolve code-verifier discrepancies through Review Resolution before invoking document-reviewer; pass the exact HC-04 inputs rather than a narrative evidence bundle - An applied `unverified` discrepancy returns through a fresh owning technical-designer update invocation. Capability probing is reserved for the designer's review-triggered gate, with that fresh designer as the sole correction specialist - Fullstack layer sequencing is defined only in `references/monorepo-flow.md` @@ -174,7 +174,7 @@ Start the applicable Structural Scale flow at the user-requested phase. Before r Verify commit capability before autonomous mode. Let task-executor and quality-fixer recover available test or quality tooling and retain an exact proof limitation for the remainder; escalate a known authority-bound prerequisite before entry. -Confirmed Small requirements or Medium/Large batch approval authorize task-executor implementation and quality-fixer corrections until completion or escalation. +User confirmation at the Requirements stop for Small, or Medium/Large batch approval, authorizes task-executor implementation and quality-fixer corrections until completion or escalation. ### Autonomous Execution Summary For Medium/Large, after batch approval, including an existing-plan build instruction, autonomously execute the following processes through completion or an escalation condition: @@ -215,7 +215,7 @@ When a quality-fixer retry changes behavior outside the received findings, compa | Trigger | Action | |---|---| -| Evidence shows the confirmed outcome, desired-future requirements, and non-goals cannot all remain true without a user choice | Apply Requirement Change Detection and ask which value boundary changes. | +| Evidence shows the outcome, desired-future requirements, and non-goals cannot all remain true without a user choice | Apply Requirement Change Detection and ask which value boundary changes. | | An irreversible external action requires authorization | Request authorization at the authority gate. | | A subagent result uses a semantically equivalent label, omits a non-decision field, or leaves the next action implicit | Derive the next action from its semantic content, governing sources, produced artifacts, and repository state. | | Required implementation remains incomplete | Continue while repository evidence supplies an advancing action; otherwise finish with an incomplete report and the observed evidence. | @@ -228,9 +228,9 @@ When a quality-fixer retry changes behavior outside the received findings, compa #### Commit Boundary Check Immediately before a workflow commit: -1. Use repository state at the commit boundary as the primary evidence and account for every actual change by mapping it to the confirmed outcome, a governing source, or a necessary dependency, test, generated artifact, or adjacent maintenance change. `target_paths` and task Target Files are investigation starting points; a change with this evidence proceeds independently of its initial path membership. -2. Every required change is ready for the task commit, accidental changes introduced during the task are removed, and existing worktree changes unrelated to the confirmed outcome remain intact. -3. Commit the resulting change set. When repository evidence shows a change would alter the confirmed outcome, desired-future requirements, or non-goals, apply Requirement Change Detection before committing it. +1. Use repository state at the commit boundary as the primary evidence and account for every actual change by mapping it to the outcome, a governing source, or a necessary dependency, test, generated artifact, or adjacent maintenance change. `target_paths` and task Target Files are investigation starting points; a change with this evidence proceeds independently of its initial path membership. +2. Every required change is ready for the task commit, accidental changes introduced during the task are removed, and existing worktree changes unrelated to the outcome remain intact. +3. Commit the resulting change set. When repository evidence shows a change would alter the outcome, desired-future requirements, or non-goals, apply Requirement Change Detection before committing it. For a `verification_incomplete` commit, append one trailer pair per retained limitation: @@ -242,7 +242,7 @@ Verification-Affected: Derive the values from the quality-fixer result. Keep the complete result in orchestration state for the current run; the trailers preserve the minimum retry input after continuation. **Per-task cycle**: -1. **Execute**: record the current HEAD as `diffBase`, then invoke task-executor with `task_file: [path]` when one exists; for Small, invoke it with `direct_scope` as the confirmed outcome and exclusions, `governing_sources`, `target_paths`, and `observable_verification` +1. **Execute**: record the current HEAD as `diffBase`, then invoke task-executor with `task_file: [path]` when one exists; for Small, invoke it with `direct_scope` as the convergence record's outcome and exclusions, `governing_sources`, `target_paths`, and `observable_verification` 2. **Branch on executor result**: - `status: escalation_needed` or `blocked` → Apply Specialist Result Acceptance - `requiresTestReview` is `true` → Identify the changed integration/E2E test files in the current changes and invoke integration-test-reviewer with them as `changedTestFiles`, plus `diffBase`, optional `taskFile`, prompt-only claims, and `mutationEvidence` @@ -268,12 +268,12 @@ Before post-implementation verifiers, collect retained verification limitations ### HC-01b: convergence record → document owner - Pass the orchestrator-judged `convergence` record to whichever agent owns the persisting document. -- **prd-creator** (when a PRD is created or updated): persists `outcome` to `Success Criteria` and user-authored `nonGoals` to `Future / Out of Scope`; the PRD contains confirmed requirements and boundaries while evaluation requests, speculative ideas, and unselected mechanisms remain only in pre-confirmation convergence context +- **prd-creator** (when a PRD is created or updated): persists `outcome` to `Success Criteria` and user-authored `nonGoals` to `Future / Out of Scope`; the PRD contains the user-selected requirements and boundaries while evaluation requests, speculative ideas, and unselected mechanisms remain only in active convergence context - **technical-designer / technical-designer-frontend**: persists the same to the Design Doc's `Requirement Convergence` when no PRD exists, and always records the fields left `weak-but-explicit` there - Pass the record unchanged; a field's readiness label travels with it ### HC-02: codebase-analyzer → technical-designer -- For an ADR batch, pass the confirmed `decision_points` unchanged and copy their corresponding `decisionMaterials.candidateDecisionPoints` objects unchanged as `decision_materials`. +- For an ADR batch, pass the `decision_points` that pass both filters unchanged and copy their corresponding `decisionMaterials.candidateDecisionPoints` objects unchanged as `decision_materials`. - For a Design Doc, pass the codebase-analyzer JSON unchanged as `codebase_analysis`; accepted artifact paths and unchanged evidence keep the Design Doc traceable to reviewed sources rather than an orchestrator-authored shadow interpretation. Use these fields as follows: - Required downstream uses: - `focusAreas` → canonical disposition-target list for the Fact Disposition Table @@ -293,7 +293,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 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. +- 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 `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. ### HC-05: code-verifier → next-layer technical-designer (fullstack only) @@ -307,7 +307,7 @@ Pass the Design Doc path. Work-planner maps governing sections and ACs to implem ### HC-06: acceptance-test-generator → work-planner -- Invoke acceptance-test-generator with `design_docs` as the applicable Design Doc path list, optional `ui_spec`, and the same `confirmed_requirement_context` used for design. +- Invoke acceptance-test-generator with `design_docs` as the applicable Design Doc path list, optional `ui_spec`, and the same `requirement_context` used for design. - Resolve a blocked generator result through Specialist Result Acceptance before consuming `generatedFiles`. - Verify each non-null `generatedFiles.` path exists. When a lane is `null`, check the generator’s explanation against the accepted criteria, applicable UI Spec, actual existing test assertions and generated skeletons. Confirm that the explanation accounts for the required observable boundary. A proposed test is not existing coverage; return any missing integration/E2E obligation to the generator. - Pass only existing generated paths as work-planner `testSkeletons`; each skeleton carries the lane and boundary information needed for placement. diff --git a/dev-workflows/skills/subagents-orchestration-guide/references/monorepo-flow.md b/dev-workflows/skills/subagents-orchestration-guide/references/monorepo-flow.md index 84396532..52bbc86e 100644 --- a/dev-workflows/skills/subagents-orchestration-guide/references/monorepo-flow.md +++ b/dev-workflows/skills/subagents-orchestration-guide/references/monorepo-flow.md @@ -4,7 +4,7 @@ This reference defines the orchestration flow for one feature spanning backend a ## When This Flow Applies -- The confirmed outcome requires backend and frontend implementation. +- The outcome requires backend and frontend implementation. - Separate Design Docs are needed for layer ownership and cross-layer verification. - The orchestrator is invoked through a fullstack implementation or build recipe. @@ -14,7 +14,7 @@ This reference defines the orchestration flow for one feature spanning backend a | Step | Owner | Purpose | Output | |------|-------|---------|--------| -| 1 | requirement-analyzer + orchestrator | Scope/cost evidence followed by orchestrator convergence and Structural Scale judgment, then the requirements hearing **[Stop]** | Confirmed requirements + scale | +| 1 | requirement-analyzer + orchestrator | Scope/cost evidence followed by orchestrator convergence and Structural Scale judgment, then the requirements hearing **[Stop]** | Convergence record + scale | | 2 | prd-creator | PRD for the complete feature | PRD | | 3 | document-reviewer | PRD review **[Stop]** | Approval | | 4 | codebase-analyzer + orchestrator | Repository decision material for the complete feature, including layer boundaries and cross-layer contracts, then requirement reopening when applicable **[Stop when applicable]** | Analysis JSON | @@ -34,13 +34,13 @@ This reference defines the orchestration flow for one feature spanning backend a ### Medium Structural Scale Fullstack -For Medium scale, execute Large steps 4-17 and carry the confirmed convergence record in place of a PRD; retain the conditional stops at steps 4, 7, and 9 and the approval stops at steps 14 and 17. +For Medium scale, execute Large steps 4-17 and carry the convergence record in place of a PRD; retain the conditional stops at steps 4, 7, and 9 and the approval stops at steps 14 and 17. ## Analysis and Evidence Rules At each Agent invocation in this flow, build the prompt as a mechanical extraction: copy the named source values into the exact fields, apply only the declared serialization, then invoke immediately. -Invoke codebase-analyzer once for the complete confirmed feature. It discovers backend/frontend responsibility boundaries and their cross-layer contracts; independent discovery keeps convergence grounded in repository evidence rather than the orchestrator's unverified implementation hypothesis. +Invoke codebase-analyzer once for the complete feature. It discovers backend/frontend responsibility boundaries and their cross-layer contracts; independent discovery keeps convergence grounded in repository evidence rather than the orchestrator's unverified implementation hypothesis. Apply the documentation-criteria UI Spec creation condition. Invoke ui-analyzer only when a UI Spec applies. External-resource and prototype inputs are then conditional: load external-resource-context when external evidence can change the current UI or verification decision, and ask for a prototype only when it resolves an approved UI decision or target ambiguity. @@ -50,7 +50,7 @@ Use these prompt shapes: For either analyzer, pass exactly one governing source: prd_path: [approved PRD path] or -requirements: [confirmed requirements verbatim] +requirements: [convergence record requirements verbatim] For UI analysis only, add an existing UI Spec, a decision-relevant prototype, and selected external references: ui_spec_path: [existing UI Spec path] @@ -58,7 +58,7 @@ prototype_path: [decision-relevant path] external_resource_refs: [selected references or []] UI Spec: -confirmed_requirement_context: [approved PRD path exactly; otherwise unchanged convergence record] +requirement_context: [approved PRD path exactly; otherwise unchanged convergence record] ui_analysis: [UI analyzer JSON] codebase_analysis: [applicable frontend codebase evidence] prototype_path: [decision-relevant path or absent] @@ -72,7 +72,7 @@ After scope and any applicable UI Spec approval, resolve candidate decision poin - Route layer-owned decision points to the matching technical designer. - Route cross-layer points to technical-designer. -- Invoke each owner with `document_to_create: ADRBatch`, `confirmed_requirement_context`, its ordered confirmed `decision_points` unchanged, and the corresponding codebase-analysis `candidateDecisionPoints` objects unchanged as `decision_materials`; include an approved `ui_spec_path` only when it constrains a frontend decision. +- Invoke each owner with `document_to_create: ADRBatch`, `requirement_context`, its ordered `decision_points` that pass both filters unchanged, and the corresponding codebase-analysis `candidateDecisionPoints` objects unchanged as `decision_materials`; include an approved `ui_spec_path` only when it constrains a frontend decision. - Invoke technical-designer batches serially: cross-layer/backend first, frontend second. Each owner allocates numbers only after the preceding batch exists. - Collect every returned ADR path. - Invoke document-reviewer once with `doc_type: ADRBatch` and the complete `targets` array. @@ -89,8 +89,8 @@ Create each complete layer design from reviewed artifacts and unchanged evidence ```text document_to_create: DesignDoc output_path: docs/design/[feature-name]-backend-design.md -confirmed_requirement_context: [approved PRD path exactly; otherwise unchanged convergence record] -structural_scale: [confirmed scale] +requirement_context: [approved PRD path exactly; otherwise unchanged convergence record] +structural_scale: [orchestrator-selected scale] adr_paths: [accepted paths or []] codebase_analysis: [complete analysis JSON unchanged] ``` @@ -100,8 +100,8 @@ codebase_analysis: [complete analysis JSON unchanged] ```text document_to_create: DesignDoc output_path: docs/design/[feature-name]-frontend-design.md -confirmed_requirement_context: [approved PRD path exactly; otherwise unchanged convergence record] -structural_scale: [confirmed scale] +requirement_context: [approved PRD path exactly; otherwise unchanged convergence record] +structural_scale: [orchestrator-selected scale] adr_paths: [accepted paths or []] ui_spec_path: [approved UI Spec; omit when absent] backend_design_doc: [path] @@ -113,13 +113,13 @@ Apply `code:` and `ui:` prefixes to respective Fact Disposition IDs. The fronten ## Verification Resolution -Keep verifier observations unchanged so corrections remain traceable to observed evidence rather than orchestrator-authored design instructions. Invoke code-verifier once per Design Doc with `doc_type: design-doc`; apply Review Resolution independently, forward each `apply` discrepancy verbatim with only its disposition, and rerun the affected verifier with its previous complete result, dispositions, and correction diff or paths as `prior_feedback`. Build one `verification_evidence` object per Design Doc from the latest result. Invoke document-reviewer with `review_context: creation`, `verification_evidence`, the same unchanged `codebase_analysis` and optional unchanged `ui_analysis`, original requirements as `requirements_verbatim`, and `confirmed_requirement_context` in the exact form fixed by the orchestration guide. +Keep verifier observations unchanged so corrections remain traceable to observed evidence rather than orchestrator-authored design instructions. Invoke code-verifier once per Design Doc with `doc_type: design-doc`; apply Review Resolution independently, forward each `apply` discrepancy verbatim with only its disposition, and rerun the affected verifier with its previous complete result, dispositions, and correction diff or paths as `prior_feedback`. Build one `verification_evidence` object per Design Doc from the latest result. Invoke document-reviewer with `review_context: creation`, `verification_evidence`, the same unchanged `codebase_analysis` and optional unchanged `ui_analysis`, original requirements as `requirements_verbatim`, and `requirement_context` in the exact form fixed by the orchestration guide. After both document reviews permit approval, invoke design-sync with `source_design` as the frontend Design Doc path because it consumes backend integration contracts. Apply Review Resolution to actionable conflicts before the design approval stop. ## Test Skeleton and Work Planning -Pass both Design Doc paths as `design_docs`, the applicable `ui_spec`, and the same `confirmed_requirement_context` used for design to acceptance-test-generator. Follow parent HC-06 for generated-path and empty-lane coverage checks before planning. Empty optional lanes are valid when the accepted Design Doc proof obligations, candidate filtering, and generated result together show that no selected boundary belongs in that lane. +Pass both Design Doc paths as `design_docs`, the applicable `ui_spec`, and the same `requirement_context` used for design to acceptance-test-generator. Follow parent HC-06 for generated-path and empty-lane coverage checks before planning. Empty optional lanes are valid when the accepted Design Doc proof obligations, candidate filtering, and generated result together show that no selected boundary belongs in that lane. Pass both Design Docs, the applicable UI Spec, applicable PRD, and generated skeleton paths to work-planner. Compose phases around shared backend/frontend verification points. The generated skeleton file is consumed by the earliest task where its declared boundary becomes executable. 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 09f6bae1..512b2c26 100644 --- a/dev-workflows/skills/subagents-orchestration-guide/references/review-resolution.md +++ b/dev-workflows/skills/subagents-orchestration-guide/references/review-resolution.md @@ -1,6 +1,6 @@ # Review Resolution -Use this protocol when a deliverable reviewer or verifier returns findings that can route correction or progression. Correct evidenced defects while preserving confirmed requirements, exclusions, and compatibility obligations, using existing responsibilities. Accepted design decisions are the currently selected means: a correction may remove or narrow one while those boundaries remain true. Verification output used as evidence by a downstream specialist remains part of that specialist handoff. +Use this protocol when a deliverable reviewer or verifier returns findings that can route correction or progression. Correct evidenced defects while preserving the requirements, exclusions, and compatibility obligations, using existing responsibilities. Accepted design decisions are the currently selected means: a correction may remove or narrow one while those boundaries remain true. Verification output used as evidence by a downstream specialist remains part of that specialist handoff. Preserve reviewer/verifier evidence ownership so each gate converges on the governing sources; orchestrator reinterpretation would create unreviewed requirements and make approval or reconciliation non-terminal. @@ -23,20 +23,20 @@ Use the result producer's declared verification mode: ## 1. Assess Every Finding -Before assigning a disposition, inspect the relevant parts of the current deliverable, cited repository evidence, and governing sources. Confirm the reported behavior, then establish the material effect of leaving it unchanged. A material effect changes the confirmed outcome, a binding constraint, downstream behavior, decisions, or required verification, or is an evidenced lifecycle cost whose frequency or magnitude is observable. For a discretionary response, compare that effect with the full cost of implementing, verifying, and retaining the response, including review attention. +Before assigning a disposition, inspect the relevant parts of the current deliverable, cited repository evidence, and governing sources. Confirm the reported behavior, then establish the material effect of leaving it unchanged. A material effect changes the outcome, a binding constraint, downstream behavior, decisions, or required verification, or is an evidenced lifecycle cost whose frequency or magnitude is observable. For a discretionary response, compare that effect with the full cost of implementing, verifying, and retaining the response, including review attention. Order the candidate responses before recording a disposition: no change, then removal or narrowing, then reuse of existing behavior, then a repair that retains or adds a mechanism. A retaining or additive response names the required result the earlier candidates cannot deliver. This is a selection condition, not an obligation to enumerate alternatives for every finding. -When a proposed correction remains within the agreed boundary above, select it from current evidence without expanding scope. When evidence shows the confirmed outcome cannot be achieved within existing responsibilities, leave Review Resolution and apply the parent workflow's existing design or requirement gate before changing them. When the confirmed outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which value boundary changes, apply the parent workflow's Requirement Change Detection. When correction requires authorization for an irreversible external action, apply the parent workflow's authority gate. These workflow exits are not finding dispositions; an optional expansion receives `decline`. +When a proposed correction remains within the agreed boundary above, select it from current evidence without expanding scope. When evidence shows the outcome cannot be achieved within existing responsibilities, leave Review Resolution and apply the parent workflow's existing design or requirement gate before changing them. When the outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which value boundary changes, apply the parent workflow's Requirement Change Detection. When correction requires authorization for an irreversible external action, apply the parent workflow's authority gate. These workflow exits are not finding dispositions; an optional expansion receives `decline`. The orchestrator records one disposition for every actionable finding: | Disposition | Use when | |---|---| -| `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. | +| `apply` | Leaving the current deliverable unchanged would prevent the 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 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. +A confirmed exploitable gap in a relied-upon trust boundary, implementation divergence, or governing-source contradiction receives `apply` when correction preserves the 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: @@ -53,7 +53,7 @@ Only findings with `apply`, and maintained `apply` findings under section 3, ent Select the existing correction owner from the accepted state each finding requires: -- use the owning document author when the implementation already satisfies the confirmed value boundaries and the technical artifact must change; +- use the owning document author when the implementation already satisfies the value boundaries and the technical artifact must change; - use the executor when the implementation must change to reach the accepted state. For a mixed set, complete author-owned corrections first and re-evaluate executor-owned findings against the corrected governing artifact. Pass complete `apply` finding objects verbatim with their dispositions to the selected owner. Invoke a document author as a fresh update call with the original target and those findings; the artifact supplies unaffected context. When an executor is used, preserve its original `task_file` or four direct-scope fields and add the findings as `correction_findings`; correction remains inside the original execution scope. diff --git a/skills/ai-development-guide/SKILL.md b/skills/ai-development-guide/SKILL.md index b3c9e991..b0fff492 100644 --- a/skills/ai-development-guide/SKILL.md +++ b/skills/ai-development-guide/SKILL.md @@ -8,11 +8,11 @@ description: Applies language-agnostic and backend technical decision criteria, ## Value-First Engineering Inspect until the evidence identifies the lowest-total-complexity solution that delivers the required user, operator, or maintainer value while keeping the system correct and maintainable. -- Resolve verified problems within confirmed scope or dependencies required for the outcome; report other findings with their owning boundary and evidence without expanding the active change. +- Resolve verified problems within scope or dependencies required for the outcome; report other findings with their owning boundary and evidence without expanding the active change. - Introduce capabilities, infrastructure, abstractions, or speculative edge-case handling when a current outcome, verified constraint, or evidence-backed material risk requires them. -- Treat behavior-preserving maintenance inside the confirmed responsibility as current maintainer value when repository evidence shows it reduces change ambiguity, duplicate ownership, defect risk, or future implementation and verification cost without expanding observable product scope. +- Treat behavior-preserving maintenance inside the assigned responsibility as current maintainer value when repository evidence shows it reduces change ambiguity, duplicate ownership, defect risk, or future implementation and verification cost without expanding observable product scope. -Judge total complexity across every activated surface: user decisions, settings, modes, concepts, outputs, persistent state, and implementation paths, together with their UX, runtime, implementation, testing, documentation, and maintenance cost. Compare only dimensions that differ between viable approaches. Prefer reuse or no new mechanism when it delivers the same confirmed value and proof at lower total complexity. +Judge total complexity across every activated surface: user decisions, settings, modes, concepts, outputs, persistent state, and implementation paths, together with their UX, runtime, implementation, testing, documentation, and maintenance cost. Compare only dimensions that differ between viable approaches. Prefer reuse or no new mechanism when it delivers the same required value and proof at lower total complexity. ## Technical Anti-patterns (Red Flag Patterns) @@ -140,7 +140,7 @@ Keep concrete implementations separate while their apparent similarity is accide **Avoidance Methods**: - Before implementation, always search for similar functionality (using domain, responsibility, configuration patterns as keywords) - Similar functionality found → Verify that its contract, lifecycle, and repository usage are representative; reuse or extend it when compatible, otherwise record why it is not a valid model -- Similar functionality is technical debt → Repair it when it blocks the current outcome, was caused by the current change, or lies in confirmed scope; otherwise report it separately. Create an ADR when the repair requires an architectural decision +- Similar functionality is technical debt → Repair it when it blocks the current outcome, was caused by the current change, or lies in scope; otherwise report it separately. Create an ADR when the repair requires an architectural decision - No similar functionality exists → Implement new functionality following existing design philosophy - Preserve the evidence for each reuse, extend, separate, or repair decision in the applicable implementation or design record - **Reference representativeness check**: When adopting a pattern or dependency from nearby code, inspect the changed area and enough representative consumers or siblings to establish compatibility; expand only when competing patterns or a shared/public contract can change the choice @@ -184,7 +184,7 @@ Follow repository-declared command composition or ordering when it exists. Other ### Scope Expansion - Apply implementation/edit instructions to the accepted outcome and its governing scope. -- Treat explicit restrictions and quantities ("one", "this file", "only X") in the governing request or confirmed outcome, desired-future requirements, and non-goals as hard boundaries; treat technical-artifact How as a correctable baseline when repository evidence invalidates it without changing those boundaries +- Treat explicit restrictions and quantities ("one", "this file", "only X") in the governing request or the outcome, desired-future requirements, and non-goals as hard boundaries; treat technical-artifact How as a correctable baseline when repository evidence invalidates it without changing those boundaries - Treat referenced or expected paths as investigation starting points unless the governing source explicitly makes them exclusive - Copy/move/mirror requests preserve content verbatim; edit content only when requested - Port/translation requests preserve intent and behavior; adapt only what the destination context requires diff --git a/skills/documentation-criteria/SKILL.md b/skills/documentation-criteria/SKILL.md index 7f745120..9c5500b3 100644 --- a/skills/documentation-criteria/SKILL.md +++ b/skills/documentation-criteria/SKILL.md @@ -13,11 +13,11 @@ Each document fixes one class of decision that the repository alone cannot suppl - **PRD** — Fixes the business outcome and the acceptance criteria later work traces to. Its AC IDs are the traceability keys that the Design Doc, UI Spec, and test selection reuse; without them each consumer re-derives requirements from prose and the link between a test and the value it protects is lost. Implementation details belong to the Design Doc, selection rationale to an ADR, phases and task breakdown to the Work Plan. Later design, review, and test selection treat its content as governing, so a precondition held outside the repository change, such as release execution or organizational approval, appears in it only when the user's wording raises it. -- **ADR** — Records one durable technical choice and the options it beat, so later work can tell a deliberate decision from an accident. Without it a future change either re-runs the same comparison or silently reverses it. `Accepted` records the currently selected means, not an obligation to retain it: when later evidence supports a smaller sufficient choice, update or supersede the decision while the confirmed outcome, desired-future requirements, and non-goals remain true. End-to-end implementation design belongs to the Design Doc, schedule and repository tasks to the Work Plan. +- **ADR** — Records one durable technical choice and the options it beat, so later work can tell a deliberate decision from an accident. Without it a future change either re-runs the same comparison or silently reverses it. `Accepted` records the currently selected means, not an obligation to retain it: when later evidence supports a smaller sufficient choice, update or supersede the decision while the outcome, desired-future requirements, and non-goals remain true. End-to-end implementation design belongs to the Design Doc, schedule and repository tasks to the Work Plan. - **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. 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. +- **Design Doc** — Records the complete implementation design for the scope of the requirements: 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 requirement that describes such work is met by designing the capability it uses. When repository evidence invalidates technical How while the 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. Each task is repository work the executor completes and verifies during implementation using repository artifacts and its own output. @@ -49,7 +49,7 @@ A qualifying ADR decision point sets the floor at Medium because it creates a du ## ADR Decision Filters -Apply the Choice filter, then the Durability filter, to each technical topic inside the confirmed implementation scope. Apply them independently from Structural Scale, and check existing ADRs first. +Apply the Choice filter, then the Durability filter, to each technical topic inside the implementation scope. Apply them independently from Structural Scale, and check existing ADRs first. 1. **Choice requires judgment** — current requirements, accepted decisions, and representative repository evidence support at least two credible, materially distinct options whose selection requires comparison. 2. **Decision is durable** — choosing among those options materially changes responsibility, dependency direction, a shared contract, persistence, a technology dependency, reversibility, or lifecycle cost that future work must preserve or understand. diff --git a/skills/documentation-criteria/references/adr-template.md b/skills/documentation-criteria/references/adr-template.md index debdb11b..da261f42 100644 --- a/skills/documentation-criteria/references/adr-template.md +++ b/skills/documentation-criteria/references/adr-template.md @@ -6,7 +6,7 @@ A created ADR starts at `Proposed` and advances `Proposed` → `Accepted` → `Deprecated`/`Superseded`/`Rejected`. -`Accepted` records the currently selected means, not an obligation to retain it. When later evidence supports a smaller sufficient choice, update or supersede this decision while the confirmed outcome, desired-future requirements, and non-goals remain true. +`Accepted` records the currently selected means, not an obligation to retain it. When later evidence supports a smaller sufficient choice, update or supersede this decision while the outcome, desired-future requirements, and non-goals remain true. ## Context @@ -16,7 +16,7 @@ A created ADR starts at `Proposed` and advances `Proposed` → `Accepted` → `D - **Question**: [The technical choice requiring comparison and selection] - **Why a decision exists**: [Evidence for at least two credible, materially distinct options] -- **Scope boundary**: [Confirmed requirement or existing contract this decision serves] +- **Scope boundary**: [Requirement or existing contract this decision serves] ## Decision @@ -39,12 +39,12 @@ A created ADR starts at `Proposed` and advances `Proposed` → `Accepted` → `D Compare credible, materially distinct options supported by current requirements and repository evidence. The evidence determines how many options exist, and relative evidence-backed cost is sufficient. Add a Mermaid option-comparison diagram only when the relationship between options stays unclear in the table below. -| Option | Confirmed product value | Repository fit | Total complexity | Maintainability | Material trade-offs | Reversibility | +| Option | Product value from the requirements | Repository fit | Total complexity | Maintainability | Material trade-offs | Reversibility | |--------|-------------------------|----------------|------------------|-----------------|---------------------|---------------| | [Option 1] | [value required now] | [fit and evidence] | [materially different activated surfaces and lifecycle costs] | [fit with ownership and representative patterns] | [trade-offs] | [cost and conditions to reverse] | | [Option 2] | [value required now] | [fit and evidence] | [materially different activated surfaces and lifecycle costs] | [fit with ownership and representative patterns] | [trade-offs] | [cost and conditions to reverse] | -**Selected**: [The smallest sufficient option whose total complexity is justified by confirmed product value and repository evidence] +**Selected**: [The smallest sufficient option whose total complexity is justified by product value from the requirements and repository evidence] ## Consequences diff --git a/skills/documentation-criteria/references/design-template.md b/skills/documentation-criteria/references/design-template.md index b75daa37..fc98ba14 100644 --- a/skills/documentation-criteria/references/design-template.md +++ b/skills/documentation-criteria/references/design-template.md @@ -27,7 +27,7 @@ Lists each external resource this feature depends on with its feature-specific i ### Requirement Convergence -Records exclusions **the user decided** at requirement time. Mark the first two bullets `N/A — covered by PRD [path]` when a PRD holds them, or the whole section `N/A — reverse-engineer/as-is document`. Open questions stay here in every case because design readiness depends on them. This section contains confirmed requirements and boundaries; evaluation requests, speculative ideas, and unselected mechanisms remain only in pre-confirmation convergence context. +Records exclusions **the user decided** at requirement time. Mark the first two bullets `N/A — covered by PRD [path]` when a PRD holds them, or the whole section `N/A — reverse-engineer/as-is document`. Open questions stay here in every case because design readiness depends on them. This section contains the user-selected requirements and boundaries; evaluation requests, speculative ideas, and unselected mechanisms remain only in active convergence context. - **Outcome**: [one observable result this change must produce] - **Non-Goals**: [capability the user excluded | None — user confirmed there are none] @@ -93,7 +93,7 @@ Keywords determine test type and reduce ambiguity. The rows below demonstrate EARS syntax only. Replace their domain, values, messages, and thresholds with requirements from the PRD or accepted requirement analysis; none is a default product requirement. -Keep the smallest representative set of observable behaviors that has a stable repository-verifiable pass/fail condition. Use repository-controlled contract/interface proof instead of a live external connection unless the confirmed requirement needs that boundary. Include a performance threshold only with a sourced target and reproducible benchmark, and exact visual positioning only with an approved visual contract and deterministic comparison. Implementation details remain outside ACs. +Keep the smallest representative set of observable behaviors that has a stable repository-verifiable pass/fail condition. Use repository-controlled contract/interface proof instead of a live external connection unless a requirement needs that boundary. Include a performance threshold only with a sourced target and reproducible benchmark, and exact visual positioning only with an approved visual contract and deterministic comparison. Implementation details remain outside ACs. ### [Functional Requirement 1] @@ -198,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, traced to its originating requirement, accepted decision, or repository rule or contract] +- **Subtraction result**: [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/documentation-criteria/references/prd-template.md b/skills/documentation-criteria/references/prd-template.md index d0fea276..1769f438 100644 --- a/skills/documentation-criteria/references/prd-template.md +++ b/skills/documentation-criteria/references/prd-template.md @@ -61,13 +61,13 @@ C4Context ### Future / Out of Scope -Record user-authored non-goals and any current exclusion required to make the MVP boundary executable. The table is limited to confirmed boundaries; evaluation requests, speculative ideas, and unselected possibilities remain only in pre-confirmation convergence context. Record `None — user confirmed there are none` when the user considered exclusions and found none. +Record user-authored non-goals and any current exclusion required to make the MVP boundary executable. The table is limited to these boundaries; evaluation requests, speculative ideas, and unselected possibilities remain only in active convergence context. Record `None — user confirmed there are none` when the user considered exclusions and found none. -Use `user` for a user-authored non-goal and `analysis` for a current exclusion required to make the confirmed MVP boundary executable. +Use `user` for a user-authored non-goal and `analysis` for a current exclusion required to make the MVP boundary executable. | Capability | Disposition | Origin | Reason | |---|---|---|---| -| [Confirmed non-goal or required current scope exclusion] | future / out-of-scope | user / analysis | [Governing scope reason] | +| [User-authored non-goal or required current scope exclusion] | future / out-of-scope | user / analysis | [Governing scope reason] | ## Non-Functional Requirements @@ -87,14 +87,14 @@ Use `user` for a user-authored non-goal and `analysis` for a current exclusion r - [Considerations for future scaling] ### Accessibility (when feature includes UI) -- Compliance standard (when established by an accepted organizational, legal, contractual, or confirmed product source): [standard] +- Compliance standard (when established by an accepted organizational, legal, contractual, or user-supplied product source): [standard] - Target assistive technologies: [Screen reader, keyboard operation, voice control, etc.] - Platform requirements: [e.g., app store review requirements] - Known constraints: [e.g., external library limitations] ## Success Criteria -State observable success for the confirmed outcome. Include only sourced quantitative/UI targets; in as-is documentation, distinguish observed measures from unknown business objectives. The examples below are optional shapes, not a required metric count. +State observable success for the outcome. Include only sourced quantitative/UI targets; in as-is documentation, distinguish observed measures from unknown business objectives. The examples below are optional shapes, not a required metric count. ### Quantitative Metrics 1. [Metric name]: [numeric target] measured by [method] within [timeframe] diff --git a/skills/documentation-criteria/references/ui-spec-template.md b/skills/documentation-criteria/references/ui-spec-template.md index 46180972..e96dc373 100644 --- a/skills/documentation-criteria/references/ui-spec-template.md +++ b/skills/documentation-criteria/references/ui-spec-template.md @@ -4,9 +4,9 @@ [Purpose and scope of this UI Specification in 2-3 sentences] -### Confirmed Requirement Context +### Requirement Context - PRD path: [docs/prd/xxx-prd.md | "N/A — based on requirements analysis output"] -- Feature scope: [Which confirmed requirements this UI Spec covers] +- Feature scope: [Which requirements this UI Spec covers] ### Design Source | Source | Path | Version | @@ -35,7 +35,7 @@ Lists each external resource this feature depends on with its feature-specific i ## AC Traceability (Prototype) -Map confirmed acceptance criteria to prototype references, preserving existing AC IDs when present. Skip this section if no prototype is provided. +Map acceptance criteria to prototype references, preserving existing AC IDs when present. Skip this section if no prototype is provided. | Criterion ID / Reference | Criterion Summary | Screen / State | Prototype Reference (element ID / path) | Adoption Decision | |-------|-----------|----------------|----------------------------------------|-------------------| @@ -76,7 +76,7 @@ Add a screen-transition or component-tree Mermaid diagram only when the material #### State x Display Matrix -The matrix contains one row for each state supported by confirmed requirements, approved UI direction, preserved behavior, or repository/design-system rules. +The matrix contains one row for each state supported by the requirements, approved UI direction, preserved behavior, or repository/design-system rules. | State | Trigger | Display | Interaction / Recovery | Evidence | |-------|---------|---------|------------------------|----------| diff --git a/skills/frontend-ai-guide/SKILL.md b/skills/frontend-ai-guide/SKILL.md index 416c9cfd..c4138e25 100644 --- a/skills/frontend-ai-guide/SKILL.md +++ b/skills/frontend-ai-guide/SKILL.md @@ -8,11 +8,11 @@ description: Applies React/TypeScript-specific technical decision criteria, anti ## Value-First Engineering Inspect until the evidence identifies the lowest-total-complexity solution that delivers the required user or maintainer value while keeping the UI correct and maintainable. -- Resolve verified problems within confirmed scope or dependencies required for the outcome; report other findings with their owning boundary and evidence without expanding the active change. +- Resolve verified problems within scope or dependencies required for the outcome; report other findings with their owning boundary and evidence without expanding the active change. - Introduce state, props, variants, abstractions, or speculative edge-case handling when a current outcome, verified constraint, or evidence-backed material risk requires them. -- Treat behavior-preserving maintenance inside the confirmed responsibility as current maintainer value when repository evidence shows it reduces change ambiguity, duplicate ownership, defect risk, or future implementation and verification cost without expanding observable product scope. +- Treat behavior-preserving maintenance inside the assigned responsibility as current maintainer value when repository evidence shows it reduces change ambiguity, duplicate ownership, defect risk, or future implementation and verification cost without expanding observable product scope. -Judge total complexity across every activated user decision, prop, state, variant, concept, output, persistent state, and component or hook path, together with its UX, runtime, implementation, testing, documentation, and maintenance cost. Compare only dimensions that differ between viable approaches. Prefer reuse or no new mechanism when it delivers the same confirmed value and proof at lower total complexity. +Judge total complexity across every activated user decision, prop, state, variant, concept, output, persistent state, and component or hook path, together with its UX, runtime, implementation, testing, documentation, and maintenance cost. Compare only dimensions that differ between viable approaches. Prefer reuse or no new mechanism when it delivers the same required value and proof at lower total complexity. ## Technical Anti-patterns (Red Flag Patterns) @@ -99,7 +99,7 @@ Keep concrete implementations separate while their similarity is accidental or t **Avoidance Methods**: - Before implementation, always search for similar functionality (using domain, responsibility, component patterns as keywords) - Similar functionality found → Verify that its props, lifecycle, design-system role, and repository usage are representative; reuse or extend it when compatible, otherwise record why it is not a valid model -- Similar functionality is technical debt → Repair it when it blocks the current outcome, was caused by the current change, or lies in confirmed scope; otherwise report it separately. Create an ADR when the repair requires an architectural decision +- Similar functionality is technical debt → Repair it when it blocks the current outcome, was caused by the current change, or lies in scope; otherwise report it separately. Create an ADR when the repair requires an architectural decision - No similar functionality exists → Implement new functionality following existing design philosophy - Preserve the evidence for each reuse, extend, separate, or repair decision in the applicable implementation or design record diff --git a/skills/implementation-approach/SKILL.md b/skills/implementation-approach/SKILL.md index 84ebdcff..46ee41dc 100644 --- a/skills/implementation-approach/SKILL.md +++ b/skills/implementation-approach/SKILL.md @@ -33,7 +33,7 @@ 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. 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 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. +4. **Subtraction Check**: Remove each proposed addition and re-test its governing condition. Retain it only when the outcome, a required boundary, or necessary proof becomes unmet at its origin (a 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. diff --git a/skills/recipe-add-integration-tests/SKILL.md b/skills/recipe-add-integration-tests/SKILL.md index 479d208a..f6b93679 100644 --- a/skills/recipe-add-integration-tests/SKILL.md +++ b/skills/recipe-add-integration-tests/SKILL.md @@ -52,7 +52,7 @@ Invoke acceptance-test-generator using Agent tool: - `description`: "Generate test skeletons" - `design_docs`: Existing backend, frontend, or single-layer Design Doc paths from Step 1 - `ui_spec`: Existing UI Spec path when present -- `confirmed_requirement_context`: Approved PRD path or unchanged Design Doc Requirement Convergence record +- `requirement_context`: Approved PRD path or unchanged Design Doc Requirement Convergence record Follow subagents-orchestration-guide HC-06 to verify generated paths and coverage of empty lanes before Step 3. diff --git a/skills/recipe-design/SKILL.md b/skills/recipe-design/SKILL.md index 9deaeb71..bd4032ab 100644 --- a/skills/recipe-design/SKILL.md +++ b/skills/recipe-design/SKILL.md @@ -37,9 +37,9 @@ At each `Invoke` below, build the Agent prompt as a mechanical extraction: copy ## Step 1: Select the Governing Requirement Source -Use the approved PRD path when one exists. Otherwise use the confirmed requirements verbatim. +Use the approved PRD path when one exists. Otherwise use the requirements verbatim. -Set `confirmed_requirement_context` to the approved PRD path exactly. Only when no approved PRD exists, use the orchestrator-confirmed convergence record unchanged. +Set `requirement_context` to the approved PRD path exactly. Only when no approved PRD exists, use the orchestrator's convergence record unchanged. ## Step 2: Collect Decision Material @@ -52,10 +52,10 @@ prd_path: [approved PRD path] or, when no approved PRD exists: ```text -requirements: [confirmed requirements verbatim] +requirements: [requirements verbatim] ``` -Invoke once for the complete confirmed scope. Require one valid JSON result and let the analyzer discover affected paths, responsibility boundaries, and cross-layer contracts. Treat its focus areas as existing-behavior safeguards, not as new requirements. +Invoke once for the complete scope. Require one valid JSON result and let the analyzer discover affected paths, responsibility boundaries, and cross-layer contracts. Treat its focus areas as existing-behavior safeguards, not as new requirements. This independent discovery keeps scope and option convergence grounded in repository evidence rather than the orchestrator's unverified implementation hypothesis. @@ -69,21 +69,21 @@ Determine Structural Scale from outcomes and responsibility boundaries. File cou Resolve `decisionMaterials.candidateDecisionPoints` against the governing requirement source, applicable `simplifications`, `reuse`, and `invalidations`. Remove a point when that evidence already converges on one sufficient approach. For each remaining item, apply documentation-criteria filters in order: -1. Choice requires judgment between at least two credible, materially distinct options inside confirmed scope. +1. Choice requires judgment between at least two credible, materially distinct options inside the scope of the requirements. 2. The selection has durable material impact. Record every passing item as `adrDecisionPoints`; an empty list routes directly to the Design Doc. ADR creation is limited to items that pass both filters. Present the requirement-convergence Scope Confirmation. Place target responsibilities with their strongest file evidence, applicable simplifications with their conditions, and each qualifying ADR decision point with its filter evidence or `none` under **Decision evidence**; place Structural Scale with its boundary rationale and the recommended document route under **Workflow**. -Offer proceed, or correct scope and re-run analysis. Ask a question only when its answer can change a convergence field, the confirmed outcome, or scope. Continue only when every convergence field is `ready` or `weak-but-explicit`. `[Stop: Scope confirmation]`. +Offer proceed, or correct scope and re-run analysis. Ask a question only when its answer can change a convergence field, the outcome, or scope. Continue only when every convergence field is `ready` or `weak-but-explicit`. `[Stop: Scope confirmation]`. ## Step 4: Create and Approve an ADR Batch When Needed When `adrDecisionPoints` is non-empty: -1. Invoke `dev-workflows:technical-designer` once with exact inputs: `document_to_create: ADRBatch`; `confirmed_requirement_context`; `decision_points` as the ordered `adrDecisionPoints` confirmed in Step 3, unchanged; and `decision_materials` as the corresponding objects from Step 2 `decisionMaterials.candidateDecisionPoints`, copied unchanged in that order. -2. Invoke `dev-workflows:document-reviewer` once with exact inputs: `doc_type: ADRBatch`, `targets: [all returned paths]`, and `confirmed_requirement_context`. +1. Invoke `dev-workflows:technical-designer` once with exact inputs: `document_to_create: ADRBatch`; `requirement_context`; `decision_points` as the ordered `adrDecisionPoints` from Step 3, unchanged; and `decision_materials` as the corresponding objects from Step 2 `decisionMaterials.candidateDecisionPoints`, copied unchanged in that order. +2. Invoke `dev-workflows:document-reviewer` once with exact inputs: `doc_type: ADRBatch`, `targets: [all returned paths]`, and `requirement_context`. 3. Route the reviewer verdict first: `pass` proceeds with `issues: []`; `needs_revision` applies Review Resolution, updates one ADR per path serially, and re-reviews the complete batch; `rejected` resolves the governing-source conflict before another review. 4. Present one batch decision after Review Resolution converges, including a decline-only result; unresolved governing-source conflicts still block approval. `[Stop: ADR batch approval]`. 5. After user approval, update each ADR status to `Accepted` and verify the changed status. @@ -95,7 +95,7 @@ Create the complete MVP implementation design from reviewed artifacts and unchan Invoke `dev-workflows:technical-designer` with exactly: - `document_to_create: DesignDoc`; -- `confirmed_requirement_context`; +- `requirement_context`; - `structural_scale`; - `adr_paths: [accepted paths or []]`; - `codebase_analysis: [complete Step 2 JSON unchanged]`. @@ -112,11 +112,11 @@ Apply Review Resolution to every discrepancy before document review. Send only ` ## Step 7: Review and Approve -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. +Invoke `dev-workflows:document-reviewer` with exact inputs: `doc_type: DesignDoc`, `target`, `review_context: creation`, the original user requirements verbatim as `requirements_verbatim`, `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 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. +- `rejected`: resolve technical governing-source conflicts through Review Resolution; ask the user only when the 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. @@ -124,7 +124,7 @@ Present the Design Doc, accepted ADR paths, resolved limitations/declines, and d ## Completion Criteria -- Scope and Structural Scale were confirmed from outcomes and responsibility boundaries. +- Scope and Structural Scale were determined from outcomes and responsibility boundaries. - ADRs exist only for decision points passing both filters, and the complete batch received one review and approval. - A Design Doc exists regardless of whether ADRs were needed. - Applicable existing-behavior, contract, assumption, equivalence, and verification safeguards reached the Design Doc. diff --git a/skills/recipe-diagnose/SKILL.md b/skills/recipe-diagnose/SKILL.md index 687bd7f1..eb3e1ae6 100644 --- a/skills/recipe-diagnose/SKILL.md +++ b/skills/recipe-diagnose/SKILL.md @@ -135,7 +135,7 @@ Continue investigation while an available action can advance a material gap. Com ### Step 5: Solution Boundary -After coverage is closed, pass the complete verified cause set to solver. Ownership, contract, and technical design corrections are ordinary solution candidates when they preserve the confirmed outcome, desired-future requirements, and non-goals; detecting a design gap does not create a user decision. If evidence shows those value boundaries cannot all remain true, or a proposed remedy requires authorization for an irreversible external action, report that exact boundary with the solution evidence instead of inventing a choice. +After coverage is closed, pass the complete verified cause set to solver. Ownership, contract, and technical design corrections are ordinary solution candidates when they preserve the outcome, desired-future requirements, and non-goals; detecting a design gap does not create a user decision. If evidence shows those value boundaries cannot all remain true, or a proposed remedy requires authorization for an irreversible external action, report that exact boundary with the solution evidence instead of inventing a choice. ### Step 6: Solution Derivation (solver) diff --git a/skills/recipe-front-adjust/SKILL.md b/skills/recipe-front-adjust/SKILL.md index d7bddcd1..c6e4651d 100644 --- a/skills/recipe-front-adjust/SKILL.md +++ b/skills/recipe-front-adjust/SKILL.md @@ -21,7 +21,7 @@ Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or g ## Execution Gate -Complete Steps 1-7 in order for the confirmed adjustment outcome. Advance only through the current step's stated evidence, quality result, or user stop; skip work only when its stated condition is false. Report completion after every applicable Completion Criterion and retained-limitation retry is satisfied. +Complete Steps 1-7 in order for the adjustment outcome. Advance only through the current step's stated evidence, quality result, or user stop; skip work only when its stated condition is false. Report completion after every applicable Completion Criterion and retained-limitation retry is satisfied. ## Workflow Overview @@ -49,9 +49,9 @@ Adjustment request → conditional external resource evidence - Structural boundary judgment via documentation-criteria - Adjustment edits and verification against the design source (run in this session) - Quality verification via quality-fixer-frontend -- Commit the confirmed adjustment outcome +- Commit the adjustment outcome -**Responsibility Boundary**: This skill completes when the confirmed adjustment is committed after its quality cycle and any retained proof limitation receives its final retry. Adjustment work is end-to-end within this recipe; parent session owns edits, verification loops, quality-result routing, and commits. +**Responsibility Boundary**: This skill completes when the adjustment is committed after its quality cycle and any retained proof limitation receives its final retry. Adjustment work is end-to-end within this recipe; parent session owns edits, verification loops, quality-result routing, and commits. **Escalation Boundary**: Escalate to the full frontend design phase when the request crosses a responsibility or approved UI boundary, requires a complete Design Doc, or contains a technical choice that passes documentation-criteria's Choice and Durability filters. @@ -73,7 +73,7 @@ Inspect the named or current UI and the smallest sufficient repository evidence ### Step 3: Scale Judgment 1. Read the candidate write set from Step 2. -2. Apply Structural Scale to the confirmed outcome and responsibility boundary. Use write-set count as supporting evidence only: +2. Apply Structural Scale to the adjustment outcome and responsibility boundary. Use write-set count as supporting evidence only: - **0 files**: The adjustment request did not map to any existing file. Escalate to the user with the message "No write target identified from the adjustment request. Please clarify which component(s) should change, or run the full frontend design phase if this is a new feature." Stop this recipe. - **Direct adjustment**: One coherent UI outcome follows existing component, state, interaction, and verification patterns inside one responsibility boundary. Continue directly to adjustment context even when generated or tightly coupled files increase the count. - **Design required**: The change crosses a responsibility or approved UI contract, coordinates independently valuable outcomes, or needs a durable technical choice between credible alternatives. Escalate to the full frontend design phase. @@ -96,12 +96,12 @@ Execute Skill: typescript-rules before planning or applying adjustment edits. Execute Skill: implementation-approach before planning or applying adjustment edits. Execute Skill: testing-principles before adding or changing tests. -Implement the confirmed adjustment outcome across its affected files: -1. **Plan the edit** from the confirmed adjustment context and relevant external resource (e.g., design origin's fetched_summary). +Implement the adjustment outcome across its affected files: +1. **Plan the edit** from the Step 4 adjustment context and relevant external resource (e.g., design origin's fetched_summary). 2. **Apply the edit** using Edit / Write / MultiEdit on the affected files. -3. **Verify the confirmed target** using applicable repository/UI Spec evidence and any external source selected in Step 1. Reuse its available access or verification method; compare rendering, interaction or tokens only where they determine the requested adjustment. +3. **Verify the adjustment target** using applicable repository/UI Spec evidence and any external source selected in Step 1. Reuse its available access or verification method; compare rendering, interaction or tokens only where they determine the requested adjustment. 4. **Refine and re-verify** until the adjustment matches the design source, or matches the user-confirmed adjustment target when no separate design source exists. -5. When the complete adjustment matches the confirmed target, proceed to Step 6. +5. When the complete adjustment matches the adjustment target, proceed to Step 6. When required proof is unavailable, use sufficient file-based or other available evidence; retain an exact proof limitation otherwise. Ask for manual confirmation only when a user-owned interpretation is needed to determine the adjustment target. @@ -109,21 +109,21 @@ When required proof is unavailable, use sufficient file-based or other available - Invoke **quality-fixer-frontend** using Agent tool - `subagent_type: "dev-workflows-frontend:quality-fixer-frontend"` - - `description: "Quality verification for confirmed adjustment"` - - `direct_scope`: Copy the confirmed adjustment request and preserved visible behavior from Step 4 unchanged. + - `description: "Quality verification for adjustment"` + - `direct_scope`: Copy the adjustment request and preserved visible behavior from Step 4 unchanged. - `governing_sources`: Pass the existing UI and design source references used for the adjustment unchanged. - - `observable_verification`: Pass the confirmed adjustment request from Step 4 and applicable acceptance criteria from the governing sources unchanged. + - `observable_verification`: Pass the adjustment request from Step 4 and applicable acceptance criteria from the governing sources unchanged. - Pass `qualityCommand` when available (caller first, otherwise current task). - Route the quality-fixer-frontend response by `status`: - `pass` → proceed to Step 7 - - `stub_detected` → return to Step 5 to complete the confirmed adjustment, then re-invoke quality-fixer-frontend + - `stub_detected` → return to Step 5 to complete the adjustment, then re-invoke quality-fixer-frontend - `verification_incomplete` → retain the complete result for final retry and proceed to Step 7 - `blocked` → Apply subagents-orchestration-guide Specialist Result Acceptance using the result's semantic evidence, changed files, and repository state ### Step 7: Commit -Before committing, use repository state at the commit boundary as the primary evidence and account for every actual change by mapping it to the confirmed adjustment, preserved pattern, or a necessary dependency, test, or generated artifact. Every required change is ready for the adjustment commit, accidental changes introduced during the adjustment are removed, and existing worktree changes unrelated to the confirmed adjustment remain intact. +Before committing, use repository state at the commit boundary as the primary evidence and account for every actual change by mapping it to the adjustment, preserved pattern, or a necessary dependency, test, or generated artifact. Every required change is ready for the adjustment commit, accidental changes introduced during the adjustment are removed, and existing worktree changes unrelated to the adjustment remain intact. -Commit the confirmed adjustment after `pass` or `verification_incomplete`. For the latter, derive and append one `Verification-Limitation: ` and `Verification-Affected: ` trailer pair per retained limitation. +Commit the adjustment after `pass` or `verification_incomplete`. For the latter, derive and append one `Verification-Limitation: ` and `Verification-Affected: ` trailer pair per retained limitation. On continuation, reconstruct retained limitations from the verification trailers on commits already completed for this request. After the adjustment is committed, retry each retained verification limitation once with quality-fixer-frontend. When the retry returns `pass`, remove that limitation from retained state. Commit any resulting fixes through Steps 6→7, and include only a repeated limitation in the completion report. @@ -133,9 +133,9 @@ On continuation, reconstruct retained limitations from the verification trailers - [ ] UI Spec applicability and the candidate write set were determined from the requested UI and sufficient repository evidence - [ ] Structural boundary judgment applied; changes requiring complete design or a qualifying durable decision escalated - [ ] Adjustment context, including the affected files, was presented and confirmed once -- [ ] The confirmed adjustment outcome is implemented; each declared verification mechanism ran, received manual confirmation where required, or retained its exact proof limitation after final retry -- [ ] The confirmed adjustment completed quality-fixer-frontend before commit; retained proof limitations were retried and reported -- [ ] The confirmed adjustment is committed +- [ ] The adjustment outcome is implemented; each declared verification mechanism ran, received manual confirmation where required, or retained its exact proof limitation after final retry +- [ ] The adjustment completed quality-fixer-frontend before commit; retained proof limitations were retried and reported +- [ ] The adjustment is committed ## Output Example diff --git a/skills/recipe-front-design/SKILL.md b/skills/recipe-front-design/SKILL.md index fdab87bf..24205264 100644 --- a/skills/recipe-front-design/SKILL.md +++ b/skills/recipe-front-design/SKILL.md @@ -39,13 +39,13 @@ At each Agent invocation below, build the prompt as a mechanical extraction: cop ## Step 1: Select the Governing Requirement Source -Use the approved PRD path when one exists. Otherwise use the confirmed requirements verbatim. +Use the approved PRD path when one exists. Otherwise use the requirements verbatim. -Set `confirmed_requirement_context` to the approved PRD path exactly. Only when no approved PRD exists, use the orchestrator-confirmed convergence record unchanged. +Set `requirement_context` to the approved PRD path exactly. Only when no approved PRD exists, use the orchestrator's convergence record unchanged. ## Step 2: Collect Repository Decision Material -Invoke `dev-workflows-frontend:codebase-analyzer` once for the complete confirmed scope with exactly `prd_path: [approved PRD path]`, or `requirements: [confirmed requirements verbatim]` when no approved PRD exists. +Invoke `dev-workflows-frontend:codebase-analyzer` once for the complete scope with exactly `prd_path: [approved PRD path]`, or `requirements: [requirements verbatim]` when no approved PRD exists. Require one valid JSON result and let the analyzer discover affected paths, responsibility boundaries, and cross-layer contracts. Treat `focusAreas` as existing-behavior safeguards rather than requirements. @@ -68,7 +68,7 @@ prd_path: [approved PRD path] or, when no approved PRD exists: ```text -requirements: [confirmed requirements verbatim] +requirements: [requirements verbatim] ``` Add only an existing `ui_spec_path`, a decision-relevant `prototype_path`, and selected `external_resource_refs` or `[]`. @@ -87,7 +87,7 @@ Judge all four convergence fields. Assign `cost` from Step 2 structural evidence Determine Structural Scale from outcomes and responsibility boundaries; file count is supporting evidence only. Resolve candidate decision points against the governing source, applicable code/UI `simplifications`, `reuse`, and `invalidations`; applicable UI facts may support or contradict the remaining options. Apply documentation-criteria Choice and Durability filters only after this convergence and record passing points as `adrDecisionPoints`; an empty list is valid. -Present the requirement-convergence Scope Confirmation. Place affected responsibilities, applicable simplifications with their conditions, and qualifying ADR points or `none` under **Decision evidence**; place Structural Scale, UI Spec applicability, and the recommended document route under **Workflow**. Offer proceed, or correct and re-run. Ask a question only when its answer can change a convergence field, the confirmed outcome, or scope. Continue only when every convergence field is `ready` or `weak-but-explicit`. `[Stop: Scope confirmation]`. +Present the requirement-convergence Scope Confirmation. Place affected responsibilities, applicable simplifications with their conditions, and qualifying ADR points or `none` under **Decision evidence**; place Structural Scale, UI Spec applicability, and the recommended document route under **Workflow**. Offer proceed, or correct and re-run. Ask a question only when its answer can change a convergence field, the outcome, or scope. Continue only when every convergence field is `ready` or `weak-but-explicit`. `[Stop: Scope confirmation]`. ## Step 5: Create and Approve the UI Spec @@ -96,7 +96,7 @@ Run this step only when Step 3 determined that a UI Spec applies. Invoke `dev-workflows-frontend:ui-spec-designer` with exact inputs: ```text -confirmed_requirement_context: [the value fixed in Step 1] +requirement_context: [the value set in Step 1] ui_analysis: [complete Step 3 UI analyzer JSON unchanged] codebase_analysis: [complete Step 2 codebase-analyzer JSON unchanged] prototype_path: [decision-relevant path from Step 3 exactly, or absent] @@ -110,8 +110,8 @@ Invoke `dev-workflows-frontend:document-reviewer` with exact inputs: `doc_type: When `adrDecisionPoints` is non-empty: -1. Route shared/backend-owned points to technical-designer first, then frontend-owned points to technical-designer-frontend. Invoke each owner with exact inputs: `document_to_create: ADRBatch`; `confirmed_requirement_context`; its ordered `decision_points` confirmed in Step 4, unchanged; `decision_materials` as the corresponding Step 2 `decisionMaterials.candidateDecisionPoints` objects copied unchanged in that order; and `ui_spec_path` only when the approved UI Spec constrains that owner's decision. Run owner batches serially so each batch allocates ADR numbers after the preceding batch exists. -2. Collect all returned paths and invoke `dev-workflows-frontend:document-reviewer` once with exact inputs: `doc_type: ADRBatch`, `targets: [all paths]`, and `confirmed_requirement_context`. The reviewer follows the approved UI Spec cited by the ADRs when it can change the decision review. +1. Route shared/backend-owned points to technical-designer first, then frontend-owned points to technical-designer-frontend. Invoke each owner with exact inputs: `document_to_create: ADRBatch`; `requirement_context`; its ordered `decision_points` from Step 4, unchanged; `decision_materials` as the corresponding Step 2 `decisionMaterials.candidateDecisionPoints` objects copied unchanged in that order; and `ui_spec_path` only when the approved UI Spec constrains that owner's decision. Run owner batches serially so each batch allocates ADR numbers after the preceding batch exists. +2. Collect all returned paths and invoke `dev-workflows-frontend:document-reviewer` once with exact inputs: `doc_type: ADRBatch`, `targets: [all paths]`, and `requirement_context`. The reviewer follows the approved UI Spec cited by the ADRs when it can change the decision review. 3. Route the reviewer verdict first: `pass` proceeds with `issues: []`; `needs_revision` applies Review Resolution, updates one ADR per path serially, and re-reviews the complete batch; `rejected` resolves the governing-source conflict before another review. 4. Present one batch decision after Review Resolution converges, including a decline-only result; unresolved governing-source conflicts still block approval. `[Stop: ADR batch approval]`. 5. After user approval, set every ADR status to `Accepted` and verify the status update. @@ -123,7 +123,7 @@ Create the complete frontend MVP implementation design from reviewed artifacts a Invoke `dev-workflows-frontend:technical-designer-frontend` with exactly: - `document_to_create: DesignDoc`; -- `confirmed_requirement_context`; +- `requirement_context`; - `structural_scale`; - applicable approved `ui_spec_path` exactly and selected external-resource reference records unchanged; - `adr_paths: [accepted paths or []]`; @@ -140,11 +140,11 @@ Keep verifier observations unchanged so corrections remain traceable to observed Invoke `dev-workflows-frontend:code-verifier` with `doc_type: design-doc` and `document_path` as the Design Doc path returned by technical-designer-frontend, unchanged, to verify current premises and feasibility while treating planned behavior as intent. Apply Review Resolution before document review; send applied findings to a fresh technical-designer-frontend update invocation with `Operation Mode: update`, `Existing Document: [Design Doc path]`, and `correction_findings: [complete findings unchanged except for their dispositions]`. The designer applies its review-triggered bounded self-verification gate for an unverified decision-changing premise; this fresh designer is the sole correction specialist and selects the evidence route. Rerun verification after an applied correction with the previous complete result, dispositions, and correction diff or paths as `prior_feedback`, then build one `verification_evidence` object from the latest result. Continue at the Review Resolution convergence condition. -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. +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 `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, 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. +- `rejected`: resolve technical governing-source conflicts through Review Resolution; ask the user only when the 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. @@ -153,7 +153,7 @@ Present the applicable UI Spec, Design Doc, accepted ADR paths, resolved limitat ## Completion Criteria - External and prototype evidence was requested only when it controlled a current decision. -- Scope and Structural Scale were confirmed from outcomes and responsibility boundaries. +- Scope and Structural Scale were determined from outcomes and responsibility boundaries. - ADRs exist only for points passing both filters, and the batch received one review and approval. - An applicable UI Spec and a complete frontend Design Doc exist regardless of ADR need. - Applicable existing UI behavior, contracts, assumptions, states, equivalence, and verification safeguards reached the Design Doc. diff --git a/skills/recipe-front-plan/SKILL.md b/skills/recipe-front-plan/SKILL.md index 16635993..c0489a19 100644 --- a/skills/recipe-front-plan/SKILL.md +++ b/skills/recipe-front-plan/SKILL.md @@ -58,7 +58,7 @@ Follow the planning process below: - `description`: "Test skeleton generation" - `design_docs: [Design Doc path]` - `ui_spec: [UI Spec path]` when one exists - - `confirmed_requirement_context`: approved PRD path named by the Design Doc, or its unchanged Requirement Convergence record when no PRD exists + - `requirement_context`: approved PRD path named by the Design Doc, or its unchanged Requirement Convergence record when no PRD exists - Follow subagents-orchestration-guide HC-06 for generated-path and empty-lane coverage checks - Pass every non-null generated skeleton path to work-planner; treat an evidence-backed empty lane as complete for that lane and continue to work-planner @@ -81,7 +81,7 @@ Invoke document-reviewer to review the work plan: ### Step 5: Present for Approval - Present the reviewed work plan to the user for batch approval. If the user requests changes, re-invoke work-planner with the user's requested changes verbatim and re-run Step 4. -- Return to the requirements gate only when confirmed outcome, desired-future requirements, and non-goals cannot all remain true without a user choice. +- Return to the requirements gate only when the outcome, desired-future requirements, and non-goals cannot all remain true without a user choice. ## Response at Completion **Recommended**: End with the following standard response after plan content approval diff --git a/skills/recipe-front-review/SKILL.md b/skills/recipe-front-review/SKILL.md index c6f0aa6c..6fc502c2 100644 --- a/skills/recipe-front-review/SKILL.md +++ b/skills/recipe-front-review/SKILL.md @@ -98,7 +98,7 @@ Approve the proposed changes: This review command authorizes analysis; use AskUserQuestion to obtain separate implementation authority. The batch option is **"approve all proposed `apply` routes"** and its scope consists exclusively of those routes. When the approved change set is empty, proceed directly to Step 9. -Pass approved findings, routes, covered files/sections, and any stated total size budget to update or fix agents. Before re-validation, map every diff hunk to an approved finding or required consistency update. Remove accidental unmapped changes; when a necessary change would alter a confirmed value boundary or explicit size constraint, return to Requirement Change Detection. +Pass approved findings, routes, covered files/sections, and any stated total size budget to update or fix agents. Before re-validation, map every diff hunk to an approved finding or required consistency update. Remove accidental unmapped changes; when a necessary change would alter a value boundary or explicit size constraint, return to Requirement Change Detection. ### Step 5: Design-Side Update @@ -130,9 +130,9 @@ Run this step only when the user routed at least one finding to `d`. When no `d` Invoke task-executor-frontend using Agent tool: - `subagent_type`: "dev-workflows-frontend:task-executor-frontend" - `description`: "Execute review fixes" -- `direct_scope`: Apply the approved frontend corrections within the confirmed review scope and stated total size budget +- `direct_scope`: Apply the approved frontend corrections within the review scope and stated total size budget - `governing_sources`: The reviewed Design Doc, applicable UI Spec, and accepted requirement or ADR paths -- `target_paths`: The implementation and test paths confirmed for the approved code-side routes +- `target_paths`: The implementation and test paths identified for the approved code-side routes - `observable_verification`: The focused UI behavior tests or observable contract checks named by the findings and governing sources pass - `correction_findings`: Complete reviewer finding objects verbatim, with only their orchestrator dispositions added diff --git a/skills/recipe-fullstack-implement/SKILL.md b/skills/recipe-fullstack-implement/SKILL.md index dc9056c6..7338352a 100644 --- a/skills/recipe-fullstack-implement/SKILL.md +++ b/skills/recipe-fullstack-implement/SKILL.md @@ -76,7 +76,7 @@ After Structural Scale is determined, follow only that scale's applicable path. Execute Skill: requirement-convergence before running the hearing protocol. -Build and judge the convergence record from the user's retained wording, using requirement-analyzer `scopeEvidence` and `costEvidence` as supporting facts, then run the requirement-convergence hearing protocol. After the requirements are confirmed, apply the subagents-orchestration-guide Small evidence gate before assigning the final Structural Scale; when the gate is unresolved, invoke codebase-analyzer before routing. +Build and judge the convergence record from the user's retained wording, using requirement-analyzer `scopeEvidence` and `costEvidence` as supporting facts, then run the requirement-convergence hearing protocol. After the user answers the requirements stop, apply the subagents-orchestration-guide Small evidence gate before assigning the final Structural Scale; when the gate is unresolved, invoke codebase-analyzer before routing. When user responds to questions: - Update the orchestrator-owned convergence record from the answer, then update the Structural Scale judgment through the Small evidence gate. diff --git a/skills/recipe-implement/SKILL.md b/skills/recipe-implement/SKILL.md index acf22580..d1fcf62c 100644 --- a/skills/recipe-implement/SKILL.md +++ b/skills/recipe-implement/SKILL.md @@ -26,7 +26,7 @@ Before the first finding disposition, read `references/review-resolution.md` fro - Execute one step at a time in the defined flow (Large/Medium/Small scale) - When flow specifies "Execute document-reviewer" → Execute it immediately - **Stop at every `[Stop: ...]` marker** → Wait for explicit user confirmation before proceeding -3. **Enter autonomous mode** after confirmed Small requirements or Medium/Large batch approval +3. **Enter autonomous mode** after user confirmation at the Requirements stop for Small, or Medium/Large batch approval At each Agent invocation below, build the prompt as a mechanical extraction: copy the named source values into the exact fields, apply only the declared serialization, then invoke immediately. @@ -63,7 +63,7 @@ When continuing existing flow, verify: Execute Skill: requirement-convergence before running the hearing protocol. -Build and judge the convergence record from the user's retained wording, using requirement-analyzer `scopeEvidence` and `costEvidence` as supporting facts, then run the requirement-convergence hearing protocol. After the requirements are confirmed, apply the subagents-orchestration-guide Small evidence gate before assigning the final Structural Scale; when the gate is unresolved, invoke codebase-analyzer before routing. +Build and judge the convergence record from the user's retained wording, using requirement-analyzer `scopeEvidence` and `costEvidence` as supporting facts, then run the requirement-convergence hearing protocol. After the user answers the requirements stop, apply the subagents-orchestration-guide Small evidence gate before assigning the final Structural Scale; when the gate is unresolved, invoke codebase-analyzer before routing. When user responds to questions: - Update the orchestrator-owned convergence record from the answer, then update the Structural Scale judgment through the Small evidence gate. @@ -97,7 +97,7 @@ After Structural Scale is determined, follow only that scale's applicable path. ### Task Execution Quality Cycle (4-Step Cycle per Task) **Per-task cycle** (complete each task before starting next): -1. **Agent tool** (subagent_type: "dev-workflows:task-executor") → Record the current HEAD as `diffBase`; pass `task_file: [path]` when one exists, otherwise pass `direct_scope` as the confirmed outcome and exclusions, `governing_sources`, `target_paths`, and `observable_verification` +1. **Agent tool** (subagent_type: "dev-workflows:task-executor") → Record the current HEAD as `diffBase`; pass `task_file: [path]` when one exists, otherwise pass `direct_scope` as the convergence record's outcome and exclusions, `governing_sources`, `target_paths`, and `observable_verification` 2. Check task-executor response: - `status: escalation_needed` or `blocked` → Apply subagents-orchestration-guide Specialist Result Acceptance - `requiresTestReview` is `true` → Identify the changed integration/E2E test files in the current changes and invoke integration-test-reviewer with them as `changedTestFiles`, plus `diffBase`, optional `taskFile`, prompt-only claims, and `mutationEvidence` diff --git a/skills/recipe-plan/SKILL.md b/skills/recipe-plan/SKILL.md index 8fa1b9c4..9068c095 100644 --- a/skills/recipe-plan/SKILL.md +++ b/skills/recipe-plan/SKILL.md @@ -52,7 +52,7 @@ Follow the planning process below: - Report when none exist; when multiple exist, present them for selection ### Step 2: Test Skeleton Generation - - Invoke acceptance-test-generator with `design_docs: [selected Design Doc path]` and `confirmed_requirement_context` as the approved PRD path named by its Requirement Convergence section, or that section's unchanged convergence record when no PRD exists + - Invoke acceptance-test-generator with `design_docs: [selected Design Doc path]` and `requirement_context` as the approved PRD path named by its Requirement Convergence section, or that section's unchanged convergence record when no PRD exists - Follow subagents-orchestration-guide HC-06 for generated-path and empty-lane coverage checks - Pass every non-null generated skeleton path to the next process; treat an evidence-backed empty lane as complete for that lane and continue to the next process @@ -74,7 +74,7 @@ Invoke document-reviewer to review the work plan: ### Step 5: Present for Approval - Present the reviewed work plan to the user for batch approval. If the user requests changes, re-invoke work-planner with the user's requested changes verbatim and re-run Step 4. -- Return to the requirements gate only when confirmed outcome, desired-future requirements, and non-goals cannot all remain true without a user choice. +- Return to the requirements gate only when the outcome, desired-future requirements, and non-goals cannot all remain true without a user choice. ## Response at Completion diff --git a/skills/recipe-review/SKILL.md b/skills/recipe-review/SKILL.md index 8d8b4390..eec33915 100644 --- a/skills/recipe-review/SKILL.md +++ b/skills/recipe-review/SKILL.md @@ -98,7 +98,7 @@ Approve the proposed changes: This review command authorizes analysis; use AskUserQuestion to obtain separate implementation authority. The batch option is **"approve all proposed `apply` routes"** and its scope consists exclusively of those routes. When the approved change set is empty, proceed directly to Step 9. -Pass approved findings, routes, covered files/sections, and any stated total size budget to update or fix agents. Before re-validation, map every diff hunk to an approved finding or required consistency update. Remove accidental unmapped changes; when a necessary change would alter a confirmed value boundary or explicit size constraint, return to Requirement Change Detection. +Pass approved findings, routes, covered files/sections, and any stated total size budget to update or fix agents. Before re-validation, map every diff hunk to an approved finding or required consistency update. Remove accidental unmapped changes; when a necessary change would alter a value boundary or explicit size constraint, return to Requirement Change Detection. ### Step 5: Design-Side Update @@ -130,9 +130,9 @@ Run this step only when the user routed at least one finding to `d`. When no `d` Invoke task-executor using Agent tool: - `subagent_type`: "dev-workflows:task-executor" - `description`: "Execute review fixes" -- `direct_scope`: Apply the approved code-side corrections within the confirmed review scope and stated total size budget +- `direct_scope`: Apply the approved code-side corrections within the review scope and stated total size budget - `governing_sources`: The reviewed Design Doc and accepted requirement or ADR paths -- `target_paths`: The implementation and test paths confirmed for the approved code-side routes +- `target_paths`: The implementation and test paths identified for the approved code-side routes - `observable_verification`: The focused tests or observable contract checks named by the findings and governing sources pass - `correction_findings`: Complete reviewer finding objects verbatim, with only their orchestrator dispositions added diff --git a/skills/requirement-convergence/SKILL.md b/skills/requirement-convergence/SKILL.md index bd20961f..b51e0959 100644 --- a/skills/requirement-convergence/SKILL.md +++ b/skills/requirement-convergence/SKILL.md @@ -9,7 +9,7 @@ description: Separates the outcome a change must produce from the requirements p Requirements arrive bloated, ambiguous, or aimed at the wrong outcome. A capable model reconciles all three into a coherent plan and builds it faithfully — delivering exactly what was asked for when what was asked for was wrong. -This skill converges **what to build**. How to build it, and which documents the change requires, are settled after the what is. +This skill converges **what to build**. How to build it, and which documents the change requires, come after the what. ## Convergence Fields @@ -49,14 +49,14 @@ Render this shape at every requirements confirmation stop, whether or not the he | Section | Contents | |---------|----------| -| **Confirmed scope** | The requirements and exclusions the user has already selected, in the user's wording | +| **User-selected scope** | The requirements and exclusions the user has already selected, in the user's wording | | **Decision evidence** | Each material observed fact with its source, followed by what that fact can change about scope, outcome, or cost | | **User decisions** | One question per convergence field below `ready` (Hearing Protocol Step 1), followed by the scope, outcome, or cost effects of its materially different answers | | **Workflow** | Rough cost band with the unknowns that remain, Structural Scale, and the selected document and workflow route | -Keeping the first three sections separate is what makes the decision informable: merged, the reader cannot tell which line is the user's own settled boundary, which is a repository observation, and which is still open. +Keeping the first three sections separate is what makes the decision informable: merged, the reader cannot tell which line is the user's own selection, which is a repository observation, and which is still open. -Only an explicit user answer moves an item from **User decisions** into **Confirmed scope**. Because Step 2 records the user's own wording, pose each open decision as a question and let the user supply its answer. The orchestrator owns **Workflow** and presents it as a selected route. +Only an explicit user answer moves an item from **User decisions** into **User-selected scope**. Because Step 2 records the user's own wording, pose each open decision as a question and let the user supply its answer. The orchestrator owns **Workflow** and presents it as a selected route. ## Storage Protocol diff --git a/skills/subagents-orchestration-guide/SKILL.md b/skills/subagents-orchestration-guide/SKILL.md index caac3770..38f28531 100644 --- a/skills/subagents-orchestration-guide/SKILL.md +++ b/skills/subagents-orchestration-guide/SKILL.md @@ -27,27 +27,27 @@ Build and judge the `convergence` record in the orchestrator with the requiremen ### Small Evidence Gate -Classify Small when `scopeEvidence.executionRoute.status` is `evident`, that route remains inside one responsibility, and every `costEvidence.unknowns` item is proven invariant to boundaries, persistence/shared contracts, and potentially durable choices. Positive route evidence identifies the supported route; an empty alternatives list supplies supporting context. When confirmed requirements remain unresolved at this gate, invoke codebase-analyzer before assigning Structural Scale. Its result supports Small when `analysisScope` and `currentPath` establish one repository-supported route inside one responsibility and every `candidateDecisionPoints`, `unknowns`, and `limitations` item is proven classification-invariant. Other observed boundaries and outcomes route Medium or Large. Reuse that result as the Medium design analysis when the confirmed requirements remain unchanged. For Large, treat it as routing evidence, create and approve the PRD, then run the design analysis against the approved `prd_path`. ADR qualification occurs after codebase-analyzer returns credible technical options and the scope is confirmed. +Classify Small when `scopeEvidence.executionRoute.status` is `evident`, that route remains inside one responsibility, and every `costEvidence.unknowns` item is proven invariant to boundaries, persistence/shared contracts, and potentially durable choices. Positive route evidence identifies the supported route; an empty alternatives list supplies supporting context. When the requirements remain unresolved at this gate, invoke codebase-analyzer before assigning Structural Scale. Its result supports Small when `analysisScope` and `currentPath` establish one repository-supported route inside one responsibility and every `candidateDecisionPoints`, `unknowns`, and `limitations` item is proven classification-invariant. Other observed boundaries and outcomes route Medium or Large. Reuse that result as the Medium design analysis when the requirements remain unchanged. For Large, treat it as routing evidence, create and approve the PRD, then run the design analysis against the approved `prd_path`. ADR qualification occurs after codebase-analyzer returns credible technical options and the scope has passed the requirements stop. ### Requirement Change Detection During Flow -After an analysis result returns, compare each user-facing or operational responsibility it exposes against the confirmed scope. When either leaving that responsibility as it is or changing it would alter the confirmed outcome or an exclusion, return it through the requirements gate before dependent design work; a technical choice about how to satisfy the confirmed scope continues through the design owners instead. +After an analysis result returns, compare each user-facing or operational responsibility it exposes against the scope in the convergence record. When either leaving that responsibility as it is or changing it would alter the outcome or an exclusion, return it through the requirements gate before dependent design work; a technical choice about how to satisfy that scope continues through the design owners instead. -Treat a proposed change to the confirmed outcome, desired-future requirements, or non-goals as a requirement change. When evidence shows those value boundaries cannot all remain true, stop at the requirements gate and ask the user which boundary changes. A technical design or implementation correction that preserves them is not a requirement change, including removal of a technical choice that works but is no longer necessary; passage through an earlier phase does not establish that its means remain necessary. Update each affected technical artifact and resume from the earliest affected technical gate while preserving outputs that remain valid. +Treat a proposed change to the outcome, desired-future requirements, or non-goals as a requirement change. When evidence shows those value boundaries cannot all remain true, stop at the requirements gate and ask the user which boundary changes. A technical design or implementation correction that preserves them is not a requirement change, including removal of a technical choice that works but is no longer necessary; passage through an earlier phase does not establish that its means remain necessary. Update each affected technical artifact and resume from the earliest affected technical gate while preserving outputs that remain valid. -**Requirement reopening after codebase analysis**: When the first codebase-analyzer result after requirement confirmation shows existing behavior that serves a confirmed requirement's need and falls short only of extra behavior that requirement specifies, whichever field reports it, present it with its evidence and cost effect at one requirements stop before UI Spec, ADR, or Design Doc work, and let the user keep or change the requirement. Requirements are confirmed before any code is read, and every later phase builds and reviews against them without questioning them, so this is the one point where repository evidence can reduce them; judging such evidence as ruled out by the requirement removes the user's only chance to weigh it. Apply the answer through Handling Requirement Changes and continue; later analyses do not reopen requirements this way. +**Requirement reopening after codebase analysis**: When the first codebase-analyzer result after requirement confirmation shows existing behavior that serves a requirement's need and falls short only of extra behavior that requirement specifies, whichever field reports it, present it with its evidence and cost effect at one requirements stop before UI Spec, ADR, or Design Doc work, and let the user keep or change the requirement. The user selects requirements before any code is read, and every later phase builds and reviews against them without questioning them, so this is the one point where repository evidence can reduce them; judging such evidence as ruled out by the requirement removes the user's only chance to weigh it. Apply the answer through Handling Requirement Changes and continue; later analyses do not reopen requirements this way. ## Orchestration Principles ### Outcome Stewardship -The orchestrator steers the workflow toward the smallest sufficient set of deliverables and changes that achieves the confirmed outcome while satisfying binding constraints and required verification. Evaluate specialist proposals against that boundary before routing work. +The orchestrator steers the workflow toward the smallest sufficient set of deliverables and changes that achieves the outcome while satisfying binding constraints and required verification. Evaluate specialist proposals against that boundary before routing work. -Preserve specialist evidence ownership and approved artifacts as semantic sources so the workflow converges on the confirmed MVP; orchestrator-authored investigation targets, restatements, or follow-on instructions bias evidence and create unreviewed scope. +Preserve specialist evidence ownership and approved artifacts as semantic sources so the workflow converges on the MVP; orchestrator-authored investigation targets, restatements, or follow-on instructions bias evidence and create unreviewed scope. ### Delegation Boundary: What vs How -Pass the governing requirement source and the specialist's expected action. Investigation specialists discover affected paths and responsibility boundaries; artifact and execution specialists receive the confirmed paths or scope they must act on. Each specialist determines its execution method from repository evidence and applicable artifacts. +Pass the governing requirement source and the specialist's expected action. Investigation specialists discover affected paths and responsibility boundaries; artifact and execution specialists receive the paths or scope they must act on. Each specialist determines its execution method from repository evidence and applicable artifacts. **Decision precedence for routing**: 1. User instructions (explicit requests or constraints) @@ -56,10 +56,10 @@ Pass the governing requirement source and the specialist's expected action. Inve 4. Specialist judgment **Scope source classification**: -- An explicit restriction in the user instruction or confirmed outcome, desired-future requirements, or non-goals is a hard boundary. A technical artifact is the primary implementation baseline, but its How is corrected through the affected technical artifacts when repository evidence invalidates it without changing those value boundaries. +- An explicit restriction in the user instruction or the outcome, desired-future requirements, or non-goals is a hard boundary. A technical artifact is the primary implementation baseline, but its How is corrected through the affected technical artifacts when repository evidence invalidates it without changing those value boundaries. - Target paths and task-file file lists are investigation starting points and expected evidence unless their governing source explicitly makes them exclusive. -- Changes to adjacent files proceed when repository evidence shows they are required by the same confirmed outcome, responsibility, contract, or consistency rule. -- Unrelated improvements remain outside the active change. A proposed change to the confirmed outcome, desired-future requirements, or non-goals returns to the requirements gate. Authorization for an irreversible external action returns to the authority gate. Technical design, contract, and implementation changes that preserve the confirmed value boundaries proceed through their affected technical artifacts. +- Changes to adjacent files proceed when repository evidence shows they are required by the same outcome, responsibility, contract, or consistency rule. +- Unrelated improvements remain outside the active change. A proposed change to the outcome, desired-future requirements, or non-goals returns to the requirements gate. Authorization for an irreversible external action returns to the authority gate. Technical design, contract, and implementation changes that preserve those value boundaries proceed through their affected technical artifacts. Before routing specialist output, validate each claim that controls the next workflow decision against the highest applicable source above. Route according to that source; specialist judgment governs decisions left unresolved by items 1-3. @@ -67,7 +67,7 @@ Before routing specialist output, validate each claim that controls the next wor Each specialist's agent definition owns its canonical result shape. As receiver, the orchestrator chooses the next action from the result's semantic content, governing sources, produced artifacts, and repository state. Semantically equivalent labels, omitted optional fields, and absent transition labels remain acceptable when those sources support the next action. Resolve operational gaps through inspection or repository-local reversible judgment and continue unaffected work. -Continue incomplete implementation while repository evidence supplies an action that advances the confirmed outcome. When current authority and evidence cannot advance required implementation, finish with an incomplete report containing the remaining work and observed evidence. Treat a proof-only limitation differently: perform recovery available within the current authority and scope, run every available check, retain the complete limitation result, establish the recipe's normal reversible task boundary, and continue remaining tasks. Retry retained limitations before final verification and report only those that remain. Claim only the proof actually observed. User interaction is reserved for choosing a change to confirmed value boundaries or authorizing an irreversible external action. +Continue incomplete implementation while repository evidence supplies an action that advances the outcome. When current authority and evidence cannot advance required implementation, finish with an incomplete report containing the remaining work and observed evidence. Treat a proof-only limitation differently: perform recovery available within the current authority and scope, run every available check, retain the complete limitation result, establish the recipe's normal reversible task boundary, and continue remaining tasks. Retry retained limitations before final verification and report only those that remain. Claim only the proof actually observed. User interaction is reserved for choosing a change to value boundaries or authorizing an irreversible external action. ### Review Resolution @@ -94,19 +94,19 @@ 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 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. +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 user-visible outcome from it or the requirement context alongside major internal responsibility, contract, or refactoring changes, so the user can judge whether to proceed. | Phase | Stop Point | User Action Required | |-------|------------|---------------------| | Requirements | After requirement-analyzer completes | Answer the requirement-convergence hearing, confirm the recorded requirements match their intent, then approve proceeding | | PRD | After document-reviewer completes PRD review | Approve completing the PRD phase and proceeding | -| Requirement reopening | After the first codebase-analyzer result when it shows existing behavior that falls short of a confirmed requirement only by extra behavior that requirement specifies | Keep or change each affected requirement | +| Requirement reopening | After the first codebase-analyzer result when it shows existing behavior that falls short of a requirement only by extra behavior that requirement specifies | Keep or change each affected requirement | | UI Spec | After document-reviewer completes an applicable UI Spec review | Approve completing the UI Spec phase and proceeding | | ADR batch | After document-reviewer reviews the complete qualifying batch | Approve completing the ADR batch phase and proceeding | | Design | After design-sync completes consistency verification | Approve completing the design phase and proceeding | | Work Plan | After work plan review (document-reviewer, doc_type WorkPlan; Medium/Large) completes | Batch approval: authorize implementation within this outcome | -**After applicable implementation authorization**: Confirmed Small requirements or Medium/Large batch approval start autonomous execution, which continues until completion or an escalation condition is reached. +**After applicable implementation authorization**: User confirmation at the Requirements stop for Small, or Medium/Large batch approval, starts autonomous execution, which continues until completion or an escalation condition is reached. ## Scale Determination and Document Requirements @@ -151,15 +151,15 @@ Use create mode for initial documents. For requirement-driven revisions, invoke | Medium | requirement-analyzer → codebase-analyzer → requirement reopening when applicable → conditional external/UI analysis and UI Spec → optional ADR batch/review/approval → Design Doc → code-verifier/Review Resolution → document-reviewer → design-sync → acceptance-test-generator → work-planner → work plan review → task-decomposer | | Small | requirement-analyzer → conditional codebase-analyzer when the Small evidence gate is unresolved → direct task execution (no Work Plan) | -The requirement-convergence and external-resource hearings run in the orchestrator. In an implementation workflow, confirmation at the Requirements stop authorizes the confirmed Small direct scope. Medium/Large implementation begins after Work Plan batch approval. +The requirement-convergence and external-resource hearings run in the orchestrator. In an implementation workflow, confirmation at the Requirements stop authorizes the Small direct scope. Medium/Large implementation begins after Work Plan batch approval. Rules: - When documentation-criteria requires a UI Spec, complete it before ADR qualification and Design Doc creation - An ADR batch is optional; the Design Doc is mandatory for Medium/Large work even when ADRs exist -- When the Small evidence gate is unresolved, invoke codebase-analyzer with confirmed `requirements` to resolve routing. Reuse that result for unchanged Medium scope. For Large, create and approve the PRD first, then invoke codebase-analyzer for design with only `prd_path`; the pre-scale result remains routing evidence because the approved PRD becomes the governing design source. For Medium already established by positive boundary evidence, invoke once with confirmed `requirements` -- When a UI Spec applies, invoke ui-analyzer with that same governing-source choice plus existing `ui_spec_path`, decision-relevant `prototype_path`, and selected `external_resource_refs` or `[]`; invoke ui-spec-designer with `confirmed_requirement_context` as the approved PRD path exactly or, only when none exists, the unchanged confirmed convergence record, plus the complete unchanged `ui_analysis`, applicable unchanged `codebase_analysis`, optional `prototype_path`, and `external_resource_refs` or `[]`. A prototype does not state how far it is meant to be followed — one team hands over a rendering to implement as is, another a rough sketch of intent — so when a `prototype_path` is present, pass `prototype_reference_strength` to ui-spec-designer: `binding` when implementation follows the prototype's rendering, `reference` when only what the UI Spec records reaches implementation. Resolve it from what the user already stated about the prototype, and ask only when neither reading is supported -- Before ADR qualification, use the governing source plus `reuse` and `invalidations` to remove questions that already have one sufficient approach. Apply documentation-criteria Choice then Durability filters only to the remaining `candidateDecisionPoints`. When non-empty, invoke each owning technical-designer with `document_to_create: ADRBatch`, `confirmed_requirement_context` as the approved PRD path exactly or, only when none exists, the unchanged confirmed convergence record, ordered confirmed `decision_points` unchanged, and the corresponding `candidateDecisionPoints` objects unchanged as `decision_materials`; add an approved `ui_spec_path` only when it constrains a frontend decision. Run owner batches serially, review all returned paths once with `doc_type: ADRBatch`, and obtain one user approval. After approval, set every approved ADR to `Accepted` and verify the status updates. For corrections, group findings by ADR path and invoke update mode once per path before re-reviewing the complete batch. An empty result proceeds directly to the Design Doc -- Invoke the Design Doc owner with `document_to_create: DesignDoc`, `confirmed_requirement_context` as the approved PRD path exactly or, only when none exists, the unchanged confirmed convergence record, `structural_scale`, unchanged `codebase_analysis`, optional unchanged `ui_analysis`, and accepted `adr_paths`; frontend/fullstack invocations add their named UI or layer artifact paths and distinct `output_path` destinations when splitting a feature across documents +- When the Small evidence gate is unresolved, invoke codebase-analyzer with the convergence record's `requirements` to resolve routing. Reuse that result for unchanged Medium scope. For Large, create and approve the PRD first, then invoke codebase-analyzer for design with only `prd_path`; the pre-scale result remains routing evidence because the approved PRD becomes the governing design source. For Medium already established by positive boundary evidence, invoke once with the convergence record's `requirements` +- When a UI Spec applies, invoke ui-analyzer with that same governing-source choice plus existing `ui_spec_path`, decision-relevant `prototype_path`, and selected `external_resource_refs` or `[]`; invoke ui-spec-designer with `requirement_context` as the approved PRD path exactly or, only when none exists, the unchanged convergence record, plus the complete unchanged `ui_analysis`, applicable unchanged `codebase_analysis`, optional `prototype_path`, and `external_resource_refs` or `[]`. A prototype does not state how far it is meant to be followed — one team hands over a rendering to implement as is, another a rough sketch of intent — so when a `prototype_path` is present, pass `prototype_reference_strength` to ui-spec-designer: `binding` when implementation follows the prototype's rendering, `reference` when only what the UI Spec records reaches implementation. Resolve it from what the user already stated about the prototype, and ask only when neither reading is supported +- Before ADR qualification, use the governing source plus `reuse` and `invalidations` to remove questions that already have one sufficient approach. Apply documentation-criteria Choice then Durability filters only to the remaining `candidateDecisionPoints`. When non-empty, invoke each owning technical-designer with `document_to_create: ADRBatch`, `requirement_context` as the approved PRD path exactly or, only when none exists, the unchanged convergence record, the ordered `decision_points` that pass both filters unchanged, and the corresponding `candidateDecisionPoints` objects unchanged as `decision_materials`; add an approved `ui_spec_path` only when it constrains a frontend decision. Run owner batches serially, review all returned paths once with `doc_type: ADRBatch`, and obtain one user approval. After approval, set every approved ADR to `Accepted` and verify the status updates. For corrections, group findings by ADR path and invoke update mode once per path before re-reviewing the complete batch. An empty result proceeds directly to the Design Doc +- Invoke the Design Doc owner with `document_to_create: DesignDoc`, `requirement_context` as the approved PRD path exactly or, only when none exists, the unchanged convergence record, `structural_scale`, unchanged `codebase_analysis`, optional unchanged `ui_analysis`, and accepted `adr_paths`; frontend/fullstack invocations add their named UI or layer artifact paths and distinct `output_path` destinations when splitting a feature across documents - Resolve code-verifier discrepancies through Review Resolution before invoking document-reviewer; pass the exact HC-04 inputs rather than a narrative evidence bundle - An applied `unverified` discrepancy returns through a fresh owning technical-designer update invocation. Capability probing is reserved for the designer's review-triggered gate, with that fresh designer as the sole correction specialist - Fullstack layer sequencing is defined only in `references/monorepo-flow.md` @@ -174,7 +174,7 @@ Start the applicable Structural Scale flow at the user-requested phase. Before r Verify commit capability before autonomous mode. Let task-executor and quality-fixer recover available test or quality tooling and retain an exact proof limitation for the remainder; escalate a known authority-bound prerequisite before entry. -Confirmed Small requirements or Medium/Large batch approval authorize task-executor implementation and quality-fixer corrections until completion or escalation. +User confirmation at the Requirements stop for Small, or Medium/Large batch approval, authorizes task-executor implementation and quality-fixer corrections until completion or escalation. ### Autonomous Execution Summary For Medium/Large, after batch approval, including an existing-plan build instruction, autonomously execute the following processes through completion or an escalation condition: @@ -215,7 +215,7 @@ When a quality-fixer retry changes behavior outside the received findings, compa | Trigger | Action | |---|---| -| Evidence shows the confirmed outcome, desired-future requirements, and non-goals cannot all remain true without a user choice | Apply Requirement Change Detection and ask which value boundary changes. | +| Evidence shows the outcome, desired-future requirements, and non-goals cannot all remain true without a user choice | Apply Requirement Change Detection and ask which value boundary changes. | | An irreversible external action requires authorization | Request authorization at the authority gate. | | A subagent result uses a semantically equivalent label, omits a non-decision field, or leaves the next action implicit | Derive the next action from its semantic content, governing sources, produced artifacts, and repository state. | | Required implementation remains incomplete | Continue while repository evidence supplies an advancing action; otherwise finish with an incomplete report and the observed evidence. | @@ -228,9 +228,9 @@ When a quality-fixer retry changes behavior outside the received findings, compa #### Commit Boundary Check Immediately before a workflow commit: -1. Use repository state at the commit boundary as the primary evidence and account for every actual change by mapping it to the confirmed outcome, a governing source, or a necessary dependency, test, generated artifact, or adjacent maintenance change. `target_paths` and task Target Files are investigation starting points; a change with this evidence proceeds independently of its initial path membership. -2. Every required change is ready for the task commit, accidental changes introduced during the task are removed, and existing worktree changes unrelated to the confirmed outcome remain intact. -3. Commit the resulting change set. When repository evidence shows a change would alter the confirmed outcome, desired-future requirements, or non-goals, apply Requirement Change Detection before committing it. +1. Use repository state at the commit boundary as the primary evidence and account for every actual change by mapping it to the outcome, a governing source, or a necessary dependency, test, generated artifact, or adjacent maintenance change. `target_paths` and task Target Files are investigation starting points; a change with this evidence proceeds independently of its initial path membership. +2. Every required change is ready for the task commit, accidental changes introduced during the task are removed, and existing worktree changes unrelated to the outcome remain intact. +3. Commit the resulting change set. When repository evidence shows a change would alter the outcome, desired-future requirements, or non-goals, apply Requirement Change Detection before committing it. For a `verification_incomplete` commit, append one trailer pair per retained limitation: @@ -242,7 +242,7 @@ Verification-Affected: Derive the values from the quality-fixer result. Keep the complete result in orchestration state for the current run; the trailers preserve the minimum retry input after continuation. **Per-task cycle**: -1. **Execute**: record the current HEAD as `diffBase`, then invoke task-executor with `task_file: [path]` when one exists; for Small, invoke it with `direct_scope` as the confirmed outcome and exclusions, `governing_sources`, `target_paths`, and `observable_verification` +1. **Execute**: record the current HEAD as `diffBase`, then invoke task-executor with `task_file: [path]` when one exists; for Small, invoke it with `direct_scope` as the convergence record's outcome and exclusions, `governing_sources`, `target_paths`, and `observable_verification` 2. **Branch on executor result**: - `status: escalation_needed` or `blocked` → Apply Specialist Result Acceptance - `requiresTestReview` is `true` → Identify the changed integration/E2E test files in the current changes and invoke integration-test-reviewer with them as `changedTestFiles`, plus `diffBase`, optional `taskFile`, prompt-only claims, and `mutationEvidence` @@ -268,12 +268,12 @@ Before post-implementation verifiers, collect retained verification limitations ### HC-01b: convergence record → document owner - Pass the orchestrator-judged `convergence` record to whichever agent owns the persisting document. -- **prd-creator** (when a PRD is created or updated): persists `outcome` to `Success Criteria` and user-authored `nonGoals` to `Future / Out of Scope`; the PRD contains confirmed requirements and boundaries while evaluation requests, speculative ideas, and unselected mechanisms remain only in pre-confirmation convergence context +- **prd-creator** (when a PRD is created or updated): persists `outcome` to `Success Criteria` and user-authored `nonGoals` to `Future / Out of Scope`; the PRD contains the user-selected requirements and boundaries while evaluation requests, speculative ideas, and unselected mechanisms remain only in active convergence context - **technical-designer / technical-designer-frontend**: persists the same to the Design Doc's `Requirement Convergence` when no PRD exists, and always records the fields left `weak-but-explicit` there - Pass the record unchanged; a field's readiness label travels with it ### HC-02: codebase-analyzer → technical-designer -- For an ADR batch, pass the confirmed `decision_points` unchanged and copy their corresponding `decisionMaterials.candidateDecisionPoints` objects unchanged as `decision_materials`. +- For an ADR batch, pass the `decision_points` that pass both filters unchanged and copy their corresponding `decisionMaterials.candidateDecisionPoints` objects unchanged as `decision_materials`. - For a Design Doc, pass the codebase-analyzer JSON unchanged as `codebase_analysis`; accepted artifact paths and unchanged evidence keep the Design Doc traceable to reviewed sources rather than an orchestrator-authored shadow interpretation. Use these fields as follows: - Required downstream uses: - `focusAreas` → canonical disposition-target list for the Fact Disposition Table @@ -293,7 +293,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 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. +- 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 `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. ### HC-05: code-verifier → next-layer technical-designer (fullstack only) @@ -307,7 +307,7 @@ Pass the Design Doc path. Work-planner maps governing sections and ACs to implem ### HC-06: acceptance-test-generator → work-planner -- Invoke acceptance-test-generator with `design_docs` as the applicable Design Doc path list, optional `ui_spec`, and the same `confirmed_requirement_context` used for design. +- Invoke acceptance-test-generator with `design_docs` as the applicable Design Doc path list, optional `ui_spec`, and the same `requirement_context` used for design. - Resolve a blocked generator result through Specialist Result Acceptance before consuming `generatedFiles`. - Verify each non-null `generatedFiles.` path exists. When a lane is `null`, check the generator’s explanation against the accepted criteria, applicable UI Spec, actual existing test assertions and generated skeletons. Confirm that the explanation accounts for the required observable boundary. A proposed test is not existing coverage; return any missing integration/E2E obligation to the generator. - Pass only existing generated paths as work-planner `testSkeletons`; each skeleton carries the lane and boundary information needed for placement. diff --git a/skills/subagents-orchestration-guide/references/monorepo-flow.md b/skills/subagents-orchestration-guide/references/monorepo-flow.md index 84396532..52bbc86e 100644 --- a/skills/subagents-orchestration-guide/references/monorepo-flow.md +++ b/skills/subagents-orchestration-guide/references/monorepo-flow.md @@ -4,7 +4,7 @@ This reference defines the orchestration flow for one feature spanning backend a ## When This Flow Applies -- The confirmed outcome requires backend and frontend implementation. +- The outcome requires backend and frontend implementation. - Separate Design Docs are needed for layer ownership and cross-layer verification. - The orchestrator is invoked through a fullstack implementation or build recipe. @@ -14,7 +14,7 @@ This reference defines the orchestration flow for one feature spanning backend a | Step | Owner | Purpose | Output | |------|-------|---------|--------| -| 1 | requirement-analyzer + orchestrator | Scope/cost evidence followed by orchestrator convergence and Structural Scale judgment, then the requirements hearing **[Stop]** | Confirmed requirements + scale | +| 1 | requirement-analyzer + orchestrator | Scope/cost evidence followed by orchestrator convergence and Structural Scale judgment, then the requirements hearing **[Stop]** | Convergence record + scale | | 2 | prd-creator | PRD for the complete feature | PRD | | 3 | document-reviewer | PRD review **[Stop]** | Approval | | 4 | codebase-analyzer + orchestrator | Repository decision material for the complete feature, including layer boundaries and cross-layer contracts, then requirement reopening when applicable **[Stop when applicable]** | Analysis JSON | @@ -34,13 +34,13 @@ This reference defines the orchestration flow for one feature spanning backend a ### Medium Structural Scale Fullstack -For Medium scale, execute Large steps 4-17 and carry the confirmed convergence record in place of a PRD; retain the conditional stops at steps 4, 7, and 9 and the approval stops at steps 14 and 17. +For Medium scale, execute Large steps 4-17 and carry the convergence record in place of a PRD; retain the conditional stops at steps 4, 7, and 9 and the approval stops at steps 14 and 17. ## Analysis and Evidence Rules At each Agent invocation in this flow, build the prompt as a mechanical extraction: copy the named source values into the exact fields, apply only the declared serialization, then invoke immediately. -Invoke codebase-analyzer once for the complete confirmed feature. It discovers backend/frontend responsibility boundaries and their cross-layer contracts; independent discovery keeps convergence grounded in repository evidence rather than the orchestrator's unverified implementation hypothesis. +Invoke codebase-analyzer once for the complete feature. It discovers backend/frontend responsibility boundaries and their cross-layer contracts; independent discovery keeps convergence grounded in repository evidence rather than the orchestrator's unverified implementation hypothesis. Apply the documentation-criteria UI Spec creation condition. Invoke ui-analyzer only when a UI Spec applies. External-resource and prototype inputs are then conditional: load external-resource-context when external evidence can change the current UI or verification decision, and ask for a prototype only when it resolves an approved UI decision or target ambiguity. @@ -50,7 +50,7 @@ Use these prompt shapes: For either analyzer, pass exactly one governing source: prd_path: [approved PRD path] or -requirements: [confirmed requirements verbatim] +requirements: [convergence record requirements verbatim] For UI analysis only, add an existing UI Spec, a decision-relevant prototype, and selected external references: ui_spec_path: [existing UI Spec path] @@ -58,7 +58,7 @@ prototype_path: [decision-relevant path] external_resource_refs: [selected references or []] UI Spec: -confirmed_requirement_context: [approved PRD path exactly; otherwise unchanged convergence record] +requirement_context: [approved PRD path exactly; otherwise unchanged convergence record] ui_analysis: [UI analyzer JSON] codebase_analysis: [applicable frontend codebase evidence] prototype_path: [decision-relevant path or absent] @@ -72,7 +72,7 @@ After scope and any applicable UI Spec approval, resolve candidate decision poin - Route layer-owned decision points to the matching technical designer. - Route cross-layer points to technical-designer. -- Invoke each owner with `document_to_create: ADRBatch`, `confirmed_requirement_context`, its ordered confirmed `decision_points` unchanged, and the corresponding codebase-analysis `candidateDecisionPoints` objects unchanged as `decision_materials`; include an approved `ui_spec_path` only when it constrains a frontend decision. +- Invoke each owner with `document_to_create: ADRBatch`, `requirement_context`, its ordered `decision_points` that pass both filters unchanged, and the corresponding codebase-analysis `candidateDecisionPoints` objects unchanged as `decision_materials`; include an approved `ui_spec_path` only when it constrains a frontend decision. - Invoke technical-designer batches serially: cross-layer/backend first, frontend second. Each owner allocates numbers only after the preceding batch exists. - Collect every returned ADR path. - Invoke document-reviewer once with `doc_type: ADRBatch` and the complete `targets` array. @@ -89,8 +89,8 @@ Create each complete layer design from reviewed artifacts and unchanged evidence ```text document_to_create: DesignDoc output_path: docs/design/[feature-name]-backend-design.md -confirmed_requirement_context: [approved PRD path exactly; otherwise unchanged convergence record] -structural_scale: [confirmed scale] +requirement_context: [approved PRD path exactly; otherwise unchanged convergence record] +structural_scale: [orchestrator-selected scale] adr_paths: [accepted paths or []] codebase_analysis: [complete analysis JSON unchanged] ``` @@ -100,8 +100,8 @@ codebase_analysis: [complete analysis JSON unchanged] ```text document_to_create: DesignDoc output_path: docs/design/[feature-name]-frontend-design.md -confirmed_requirement_context: [approved PRD path exactly; otherwise unchanged convergence record] -structural_scale: [confirmed scale] +requirement_context: [approved PRD path exactly; otherwise unchanged convergence record] +structural_scale: [orchestrator-selected scale] adr_paths: [accepted paths or []] ui_spec_path: [approved UI Spec; omit when absent] backend_design_doc: [path] @@ -113,13 +113,13 @@ Apply `code:` and `ui:` prefixes to respective Fact Disposition IDs. The fronten ## Verification Resolution -Keep verifier observations unchanged so corrections remain traceable to observed evidence rather than orchestrator-authored design instructions. Invoke code-verifier once per Design Doc with `doc_type: design-doc`; apply Review Resolution independently, forward each `apply` discrepancy verbatim with only its disposition, and rerun the affected verifier with its previous complete result, dispositions, and correction diff or paths as `prior_feedback`. Build one `verification_evidence` object per Design Doc from the latest result. Invoke document-reviewer with `review_context: creation`, `verification_evidence`, the same unchanged `codebase_analysis` and optional unchanged `ui_analysis`, original requirements as `requirements_verbatim`, and `confirmed_requirement_context` in the exact form fixed by the orchestration guide. +Keep verifier observations unchanged so corrections remain traceable to observed evidence rather than orchestrator-authored design instructions. Invoke code-verifier once per Design Doc with `doc_type: design-doc`; apply Review Resolution independently, forward each `apply` discrepancy verbatim with only its disposition, and rerun the affected verifier with its previous complete result, dispositions, and correction diff or paths as `prior_feedback`. Build one `verification_evidence` object per Design Doc from the latest result. Invoke document-reviewer with `review_context: creation`, `verification_evidence`, the same unchanged `codebase_analysis` and optional unchanged `ui_analysis`, original requirements as `requirements_verbatim`, and `requirement_context` in the exact form fixed by the orchestration guide. After both document reviews permit approval, invoke design-sync with `source_design` as the frontend Design Doc path because it consumes backend integration contracts. Apply Review Resolution to actionable conflicts before the design approval stop. ## Test Skeleton and Work Planning -Pass both Design Doc paths as `design_docs`, the applicable `ui_spec`, and the same `confirmed_requirement_context` used for design to acceptance-test-generator. Follow parent HC-06 for generated-path and empty-lane coverage checks before planning. Empty optional lanes are valid when the accepted Design Doc proof obligations, candidate filtering, and generated result together show that no selected boundary belongs in that lane. +Pass both Design Doc paths as `design_docs`, the applicable `ui_spec`, and the same `requirement_context` used for design to acceptance-test-generator. Follow parent HC-06 for generated-path and empty-lane coverage checks before planning. Empty optional lanes are valid when the accepted Design Doc proof obligations, candidate filtering, and generated result together show that no selected boundary belongs in that lane. Pass both Design Docs, the applicable UI Spec, applicable PRD, and generated skeleton paths to work-planner. Compose phases around shared backend/frontend verification points. The generated skeleton file is consumed by the earliest task where its declared boundary becomes executable. diff --git a/skills/subagents-orchestration-guide/references/review-resolution.md b/skills/subagents-orchestration-guide/references/review-resolution.md index 09f6bae1..512b2c26 100644 --- a/skills/subagents-orchestration-guide/references/review-resolution.md +++ b/skills/subagents-orchestration-guide/references/review-resolution.md @@ -1,6 +1,6 @@ # Review Resolution -Use this protocol when a deliverable reviewer or verifier returns findings that can route correction or progression. Correct evidenced defects while preserving confirmed requirements, exclusions, and compatibility obligations, using existing responsibilities. Accepted design decisions are the currently selected means: a correction may remove or narrow one while those boundaries remain true. Verification output used as evidence by a downstream specialist remains part of that specialist handoff. +Use this protocol when a deliverable reviewer or verifier returns findings that can route correction or progression. Correct evidenced defects while preserving the requirements, exclusions, and compatibility obligations, using existing responsibilities. Accepted design decisions are the currently selected means: a correction may remove or narrow one while those boundaries remain true. Verification output used as evidence by a downstream specialist remains part of that specialist handoff. Preserve reviewer/verifier evidence ownership so each gate converges on the governing sources; orchestrator reinterpretation would create unreviewed requirements and make approval or reconciliation non-terminal. @@ -23,20 +23,20 @@ Use the result producer's declared verification mode: ## 1. Assess Every Finding -Before assigning a disposition, inspect the relevant parts of the current deliverable, cited repository evidence, and governing sources. Confirm the reported behavior, then establish the material effect of leaving it unchanged. A material effect changes the confirmed outcome, a binding constraint, downstream behavior, decisions, or required verification, or is an evidenced lifecycle cost whose frequency or magnitude is observable. For a discretionary response, compare that effect with the full cost of implementing, verifying, and retaining the response, including review attention. +Before assigning a disposition, inspect the relevant parts of the current deliverable, cited repository evidence, and governing sources. Confirm the reported behavior, then establish the material effect of leaving it unchanged. A material effect changes the outcome, a binding constraint, downstream behavior, decisions, or required verification, or is an evidenced lifecycle cost whose frequency or magnitude is observable. For a discretionary response, compare that effect with the full cost of implementing, verifying, and retaining the response, including review attention. Order the candidate responses before recording a disposition: no change, then removal or narrowing, then reuse of existing behavior, then a repair that retains or adds a mechanism. A retaining or additive response names the required result the earlier candidates cannot deliver. This is a selection condition, not an obligation to enumerate alternatives for every finding. -When a proposed correction remains within the agreed boundary above, select it from current evidence without expanding scope. When evidence shows the confirmed outcome cannot be achieved within existing responsibilities, leave Review Resolution and apply the parent workflow's existing design or requirement gate before changing them. When the confirmed outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which value boundary changes, apply the parent workflow's Requirement Change Detection. When correction requires authorization for an irreversible external action, apply the parent workflow's authority gate. These workflow exits are not finding dispositions; an optional expansion receives `decline`. +When a proposed correction remains within the agreed boundary above, select it from current evidence without expanding scope. When evidence shows the outcome cannot be achieved within existing responsibilities, leave Review Resolution and apply the parent workflow's existing design or requirement gate before changing them. When the outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which value boundary changes, apply the parent workflow's Requirement Change Detection. When correction requires authorization for an irreversible external action, apply the parent workflow's authority gate. These workflow exits are not finding dispositions; an optional expansion receives `decline`. The orchestrator records one disposition for every actionable finding: | Disposition | Use when | |---|---| -| `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. | +| `apply` | Leaving the current deliverable unchanged would prevent the 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 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. +A confirmed exploitable gap in a relied-upon trust boundary, implementation divergence, or governing-source contradiction receives `apply` when correction preserves the 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: @@ -53,7 +53,7 @@ Only findings with `apply`, and maintained `apply` findings under section 3, ent Select the existing correction owner from the accepted state each finding requires: -- use the owning document author when the implementation already satisfies the confirmed value boundaries and the technical artifact must change; +- use the owning document author when the implementation already satisfies the value boundaries and the technical artifact must change; - use the executor when the implementation must change to reach the accepted state. For a mixed set, complete author-owned corrections first and re-evaluate executor-owned findings against the corrected governing artifact. Pass complete `apply` finding objects verbatim with their dispositions to the selected owner. Invoke a document author as a fresh update call with the original target and those findings; the artifact supplies unaffected context. When an executor is used, preserve its original `task_file` or four direct-scope fields and add the findings as `correction_findings`; correction remains inside the original execution scope. From 106b43ddb8f9a3820c979eb64a9c776f83faa168 Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Tue, 3 Nov 2026 07:51:47 +0900 Subject: [PATCH 3/3] Bump version to 0.29.6 Co-Authored-By: Claude Opus 5.5 --- .claude-plugin/marketplace.json | 8 ++++---- dev-skills/.claude-plugin/plugin.json | 2 +- dev-workflows-frontend/.claude-plugin/plugin.json | 2 +- dev-workflows-fullstack/.claude-plugin/plugin.json | 2 +- dev-workflows/.claude-plugin/plugin.json | 2 +- package.json | 2 +- 6 files changed, 9 insertions(+), 9 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 836c161a..76e758ab 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.5", + "version": "0.29.6", "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.5", + "version": "0.29.6", "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.5", + "version": "0.29.6", "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.5", + "version": "0.29.6", "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/dev-skills/.claude-plugin/plugin.json b/dev-skills/.claude-plugin/plugin.json index 499633df..8c68fa51 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.5", + "version": "0.29.6", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows-frontend/.claude-plugin/plugin.json b/dev-workflows-frontend/.claude-plugin/plugin.json index ac0af0f4..bf75a940 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.5", + "version": "0.29.6", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows-fullstack/.claude-plugin/plugin.json b/dev-workflows-fullstack/.claude-plugin/plugin.json index 0e8cd557..b78012ff 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.5", + "version": "0.29.6", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows/.claude-plugin/plugin.json b/dev-workflows/.claude-plugin/plugin.json index 2275880a..086a9075 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.5", + "version": "0.29.6", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/package.json b/package.json index 2f12fcc1..29e26b7f 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "claude-code-workflows", - "version": "0.29.5", + "version": "0.29.6", "private": true, "type": "module", "engines": {