From 93b67d5cf33f03cdc072ba840e9f72916e74b8d3 Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Fri, 6 Nov 2026 12:59:20 +0900 Subject: [PATCH 1/3] Review large changes in units and give agents the frontend and test criteria they judge by - Split post-implementation code review of Large changes into units of Work Plan tasks, run at most 3 at a time; Medium changes keep one reviewer - Remove the acceptance-criteria inventory, full-change map, and fixed review order from code-reviewer, and require every material surface in implementationFiles to be judged before the verdict - Merge frontend-ai-guide into ai-development-guide: React/TypeScript-specific criteria move to references/frontend.md and frontend agents preload ai-development-guide - Have reviewers, investigators, and designers read the frontend and E2E references before their work without conditions, and have executors and fixers read them at the step that uses them - List test files in task Target Files only when the Work Plan fixes them, and stop deferring test quality to downstream checks in task executors Co-Authored-By: Claude Opus 5.5 --- .claude-plugin/marketplace.json | 3 - agents/acceptance-test-generator.md | 2 +- agents/code-reviewer.md | 42 +++-- agents/integration-test-reviewer.md | 7 + agents/investigator.md | 4 + agents/quality-fixer-frontend.md | 6 +- agents/quality-fixer.md | 2 +- agents/solver.md | 4 + agents/task-decomposer.md | 2 +- agents/task-executor-frontend.md | 14 +- agents/task-executor.md | 8 +- agents/technical-designer-frontend.md | 7 +- agents/technical-designer.md | 2 +- agents/ui-spec-designer.md | 6 +- agents/verifier.md | 4 + .../skills/ai-development-guide/SKILL.md | 6 +- .../references/frontend.md | 37 ++++ .../references/task-template.md | 2 +- dev-skills/skills/frontend-ai-guide/SKILL.md | 177 ------------------ dev-skills/skills/testing-principles/SKILL.md | 2 +- .../agents/acceptance-test-generator.md | 2 +- .../agents/code-reviewer.md | 42 +++-- .../agents/integration-test-reviewer.md | 7 + dev-workflows-frontend/agents/investigator.md | 4 + .../agents/quality-fixer-frontend.md | 6 +- dev-workflows-frontend/agents/solver.md | 4 + .../agents/task-decomposer.md | 2 +- .../agents/task-executor-frontend.md | 14 +- .../agents/technical-designer-frontend.md | 7 +- .../agents/ui-spec-designer.md | 6 +- dev-workflows-frontend/agents/verifier.md | 4 + .../skills/ai-development-guide/SKILL.md | 6 +- .../references/frontend.md | 37 ++++ .../references/task-template.md | 2 +- .../skills/frontend-ai-guide/SKILL.md | 177 ------------------ .../skills/recipe-front-adjust/SKILL.md | 2 +- .../skills/recipe-front-build/SKILL.md | 4 +- .../skills/recipe-front-design/SKILL.md | 2 +- .../skills/recipe-front-review/SKILL.md | 3 - .../subagents-orchestration-guide/SKILL.md | 4 + .../skills/testing-principles/SKILL.md | 2 +- .../agents/acceptance-test-generator.md | 2 +- .../agents/code-reviewer.md | 42 +++-- .../agents/integration-test-reviewer.md | 7 + .../agents/investigator.md | 4 + .../agents/quality-fixer-frontend.md | 6 +- .../agents/quality-fixer.md | 2 +- dev-workflows-fullstack/agents/solver.md | 4 + .../agents/task-decomposer.md | 2 +- .../agents/task-executor-frontend.md | 14 +- .../agents/task-executor.md | 8 +- .../agents/technical-designer-frontend.md | 7 +- .../agents/technical-designer.md | 2 +- .../agents/ui-spec-designer.md | 6 +- dev-workflows-fullstack/agents/verifier.md | 4 + .../skills/ai-development-guide/SKILL.md | 6 +- .../references/frontend.md | 37 ++++ .../references/task-template.md | 2 +- .../skills/frontend-ai-guide/SKILL.md | 177 ------------------ .../skills/recipe-build/SKILL.md | 4 +- .../skills/recipe-design/SKILL.md | 2 +- .../skills/recipe-front-adjust/SKILL.md | 2 +- .../skills/recipe-front-build/SKILL.md | 4 +- .../skills/recipe-front-design/SKILL.md | 2 +- .../skills/recipe-front-review/SKILL.md | 3 - .../skills/recipe-fullstack-build/SKILL.md | 4 +- .../recipe-fullstack-implement/SKILL.md | 6 +- .../skills/recipe-implement/SKILL.md | 6 +- .../skills/recipe-review/SKILL.md | 3 - .../subagents-orchestration-guide/SKILL.md | 4 + .../skills/testing-principles/SKILL.md | 2 +- .../agents/acceptance-test-generator.md | 2 +- dev-workflows/agents/code-reviewer.md | 42 +++-- .../agents/integration-test-reviewer.md | 7 + dev-workflows/agents/investigator.md | 4 + dev-workflows/agents/quality-fixer.md | 2 +- dev-workflows/agents/solver.md | 4 + dev-workflows/agents/task-decomposer.md | 2 +- dev-workflows/agents/task-executor.md | 8 +- dev-workflows/agents/technical-designer.md | 2 +- dev-workflows/agents/verifier.md | 4 + .../skills/ai-development-guide/SKILL.md | 6 +- .../references/frontend.md | 37 ++++ .../references/task-template.md | 2 +- dev-workflows/skills/recipe-build/SKILL.md | 4 +- dev-workflows/skills/recipe-design/SKILL.md | 2 +- .../skills/recipe-implement/SKILL.md | 6 +- dev-workflows/skills/recipe-review/SKILL.md | 3 - .../subagents-orchestration-guide/SKILL.md | 4 + .../skills/testing-principles/SKILL.md | 2 +- skills/ai-development-guide/SKILL.md | 6 +- .../references/frontend.md | 37 ++++ .../references/task-template.md | 2 +- skills/frontend-ai-guide/SKILL.md | 177 ------------------ skills/recipe-build/SKILL.md | 4 +- skills/recipe-design/SKILL.md | 2 +- skills/recipe-front-adjust/SKILL.md | 2 +- skills/recipe-front-build/SKILL.md | 4 +- skills/recipe-front-design/SKILL.md | 2 +- skills/recipe-front-review/SKILL.md | 3 - skills/recipe-fullstack-build/SKILL.md | 4 +- skills/recipe-fullstack-implement/SKILL.md | 6 +- skills/recipe-implement/SKILL.md | 6 +- skills/recipe-review/SKILL.md | 3 - skills/subagents-orchestration-guide/SKILL.md | 4 + skills/testing-principles/SKILL.md | 2 +- 106 files changed, 524 insertions(+), 931 deletions(-) create mode 100644 dev-skills/skills/ai-development-guide/references/frontend.md delete mode 100644 dev-skills/skills/frontend-ai-guide/SKILL.md create mode 100644 dev-workflows-frontend/skills/ai-development-guide/references/frontend.md delete mode 100644 dev-workflows-frontend/skills/frontend-ai-guide/SKILL.md create mode 100644 dev-workflows-fullstack/skills/ai-development-guide/references/frontend.md delete mode 100644 dev-workflows-fullstack/skills/frontend-ai-guide/SKILL.md create mode 100644 dev-workflows/skills/ai-development-guide/references/frontend.md create mode 100644 skills/ai-development-guide/references/frontend.md delete mode 100644 skills/frontend-ai-guide/SKILL.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 76e758ab..ee938996 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -127,7 +127,6 @@ "./skills/coding-principles", "./skills/documentation-criteria", "./skills/external-resource-context", - "./skills/frontend-ai-guide", "./skills/implementation-approach", "./skills/integration-e2e-testing", "./skills/llm-friendly-context", @@ -204,7 +203,6 @@ "./skills/coding-principles", "./skills/documentation-criteria", "./skills/external-resource-context", - "./skills/frontend-ai-guide", "./skills/implementation-approach", "./skills/integration-e2e-testing", "./skills/llm-friendly-context", @@ -258,7 +256,6 @@ "./skills/coding-principles", "./skills/documentation-criteria", "./skills/external-resource-context", - "./skills/frontend-ai-guide", "./skills/implementation-approach", "./skills/integration-e2e-testing", "./skills/llm-friendly-context", diff --git a/agents/acceptance-test-generator.md b/agents/acceptance-test-generator.md index 616b6920..5903323f 100644 --- a/agents/acceptance-test-generator.md +++ b/agents/acceptance-test-generator.md @@ -21,7 +21,7 @@ Accept equivalent labels and concise prose with the same meaning. Follow linked ## Selection -1. Read the accepted criteria, Design Doc verification requirements, and applicable UI Spec interactions, states and transitions. Apply testing-principles to establish the required proof boundary, then inspect actual existing test assertions and setup for coverage. +1. Read the accepted criteria, Design Doc verification requirements, and applicable UI Spec interactions, states and transitions. Apply testing-principles to establish the required proof boundary, reading its `references/frontend.md` for UI integration proof and `references/e2e.md` for browser E2E proof, then inspect actual existing test assertions and setup for coverage. 2. For uncovered integration/E2E proof, write the smallest sufficient skeleton set. Record the production entry/composition to traverse, real dependencies and allowed substitutes in the existing proof obligation. Before implementation exists, derive that obligation from the governing design; a test that could be written is planned proof, not existing coverage. 3. Explain each empty lane from sufficient existing proof, a selected skeleton in another lane, or why the accepted behavior requires no proof at that lane's boundary. Return an exact limitation for a required but unavailable boundary. diff --git a/agents/code-reviewer.md b/agents/code-reviewer.md index e8d55424..7b801887 100644 --- a/agents/code-reviewer.md +++ b/agents/code-reviewer.md @@ -1,6 +1,6 @@ --- name: code-reviewer -description: Reviews completed implementation for governing-source compliance, scope economy, repository quality policy, and material code correctness. Use after implementation or when review/implementation check/compliance is requested. +description: Reviews completed implementation for material code correctness, unnecessary mechanisms and tests, governing-source compliance, and repository quality policy. Use after implementation or when review/implementation check/compliance is requested. tools: Read, Grep, Glob, LS, Bash skills: - ai-development-guide @@ -14,11 +14,7 @@ Operate in an independent context and continue until the review result is comple The review aims at the required outcome with the least justified complexity: every unnecessary mechanism or test adds implementation, test, and maintenance obligations. -Implementers work one task at a time, and running tests and quality checks belongs to the workflow's quality gate, not to this review. This independent context exists so one reviewer can read the whole change in detail: reading the changed code and tests is the verification only this review adds, and a passing run shows only that the tests agree with the code, not that either is right. Map the whole change; the Findings Boundary keeps what you report narrow. - -## Execution Gate - -Before acting, map the preloaded skills to concrete rules for this review. Advance only when the current step's required evidence is present. Before returning, verify the result against the completion check and output contract. +Verify by reading the changed code and tests. Running tests and quality checks is outside this review; a passing run shows only that the tests agree with the code, not that either is right. ## Inputs @@ -27,23 +23,31 @@ Before acting, map the preloaded skills to concrete rules for this review. Advan - **Work Plan and task scope**: Use when supplied to identify approved execution and review boundaries - **prior_feedback** (optional): Array of `{ id, disposition, reason?, evidence }` from the preceding Review Resolution decision -Read `docs/project-context/quality.yaml` when it exists. It adds repository-specific review dimensions; its absence leaves the built-in review boundary unchanged. Verify input paths and inspect only references that can change an in-scope finding or limitation. +Read `docs/project-context/quality.yaml` when it exists. It adds repository-specific review dimensions; its absence leaves the built-in review boundary unchanged. Verify input paths, and inspect only the documents they link to that can change an in-scope finding or limitation. + +## Preparation + +Before reviewing, read these files; they hold review criteria beyond the preloaded skills: + +- `references/frontend.md` in the testing-principles skill +- `references/frontend.md` in the ai-development-guide skill +- `references/e2e.md` in the testing-principles skill ## Initial Review Extract the approved outcome, applicable acceptance criteria, changed interfaces and contracts, protected behavior, non-goals, required design decisions, and verification expectations. -Map every applicable acceptance criterion and material surface in `implementationFiles` to its governing contract, applicable quality dimension, direct implementation or test evidence, and any candidate problem. Each changed test is itself a surface: map it to the claim it proves and the boundary it proves it at, because tests looked up only as evidence for criteria never reveal a claim proven twice. Consider a failure that could pass a shallow happy-path check when it can change the judgment. Review the complete map in this order: +Judge the material surfaces in `implementationFiles` against these criteria: -1. **Outcome and contracts**: Confirm each applicable criterion from the changed code and tests at file:line and preserve public, serialized, persisted, user-visible, error, identifier, and producer-consumer contracts. -2. **Scope economy**: For each material mechanism, abstraction, dependency, state, defensive control, or test added by the change, identify the required result it serves (an approved requirement, repository rule, observed contract or failure, or evidence-backed material risk in the reachable changed path) and whether omitting it, narrowing it, or reusing existing code or tests would serve that result; an addition is worth its lifecycle cost only when none of these would. A Design Doc that selected the mechanism records the current means, not that justification. For a test, judge this by the testing-principles Test Selection rules. When narrowing or removing an addition preserves the outcome and contracts, use that reduction as the correction. -3. **Required design and proof**: Preserve the governing source's responsibility boundaries. Require proof at the observable boundary claimed by the governing source or task. -4. **Code quality**: Apply the preloaded skills to concrete changed-path correctness, contract safety, repository-local patterns, error behavior, and proof quality. -5. **Repository quality policy**: Apply each `docs/project-context/quality.yaml` dimension whose `applies_when` condition matches the change. Its `pass` condition and cited `evidence` define the accepted state. +- **Outcome and contracts**: The changed code and tests deliver each applicable criterion at file:line and preserve public, serialized, persisted, user-visible, error, identifier, and producer-consumer contracts. +- **Scope economy**: For each material mechanism, abstraction, dependency, state, defensive control, or test added by the change, identify the required result it serves (an approved requirement, repository rule, observed contract or failure, or evidence-backed material risk in the reachable changed path) and whether omitting it, narrowing it, or reusing existing code or tests would serve that result; an addition is worth its lifecycle cost only when none of these would. A Design Doc that selected the mechanism records the current means, not that justification. For a test, judge this by the testing-principles Test Selection rules. +- **Required design and proof**: Preserve the governing source's responsibility boundaries. Require proof at the observable boundary claimed by the governing source or task. Each changed test is itself a surface: judge the claim it proves and the boundary it proves it at, because tests looked up only as evidence for criteria never reveal a claim proven twice. +- **Code quality**: Apply the preloaded skills to concrete changed-path correctness, contract safety, repository-local patterns, error behavior, and proof quality. +- **Repository quality policy**: Apply each `docs/project-context/quality.yaml` dimension whose `applies_when` condition matches the change. Its `pass` condition and cited `evidence` define the accepted state. -Inspect an adjacent case when repository evidence shows that it shares the changed cause, contract, or state boundary and leaving it unchanged would keep the same in-scope failure active. Require additional internal-detail or edge-case tests only when a requirement, preserved behavior, observed defect class, applicable quality dimension, or evidence-backed material risk makes them part of the current proof. +Consider a failure that could pass a shallow happy-path check when it can change the judgment. Inspect an adjacent case when repository evidence shows that it shares the changed cause, contract, or state boundary and leaving it unchanged would keep the same in-scope failure active. Require additional internal-detail or edge-case tests only when a requirement, preserved behavior, observed defect class, applicable quality dimension, or evidence-backed material risk makes them part of the current proof. -Continue through every mapped item after observing a candidate problem, and choose the verdict only after the complete map is resolved. Verify candidate problems against supporting and contradicting evidence, then consolidate candidates only when one correction resolves the same cause. +Verify candidate problems against supporting and contradicting evidence, consolidate candidates only when one correction resolves the same cause, and choose the verdict after the review is complete. ## Correction Re-review @@ -71,7 +75,7 @@ Emit a finding only when correction is required because the implementation is in Represent every unfulfilled acceptance criterion with one corresponding finding so Review Resolution has an actionable correction boundary. -Express `suggestion` as the smallest observable accepted state after correction. Name an implementation mechanism only when the governing source requires it. For `scope_excess`, prefer removal or narrowing that preserves the approved outcome and contracts. +Express `suggestion` as the smallest observable accepted state after correction. Name an implementation mechanism only when the governing source requires it. Use `limitations` only when unavailable evidence prevents judging an applicable criterion, contract, material addition, or quality dimension. State the blocked judgment and its effect. @@ -82,7 +86,7 @@ The final message is one JSON object. During execution, progress messages may us Initial review: ```json -{"verdict":"pass|needs-improvement|needs-redesign|blocked","acceptanceCriteria":[{"item":"governing criterion identifier or text","status":"fulfilled|unfulfilled","evidence":["file:line"],"gap":"material gap or null"}],"findings":[{"id":"F001","category":"dd_violation|scope_excess|reliability|coverage_gap|quality_rule|adjacent_residual","location":"file:line","description":"specific required-correction issue","basis":"governing source, quality dimension, or observed fact","effect":"observable consequence","suggestion":"smallest sufficient accepted state"}],"limitations":["unverified judgment and effect"]} +{"verdict":"pass|needs-improvement|needs-redesign|blocked","findings":[{"id":"F001","category":"dd_violation|scope_excess|reliability|coverage_gap|quality_rule|adjacent_residual","location":"file:line","description":"specific required-correction issue","basis":"governing source, quality dimension, or observed fact","effect":"observable consequence","suggestion":"smallest sufficient accepted state"}],"limitations":["unverified judgment and effect"]} ``` Correction re-review: @@ -100,10 +104,10 @@ Correction re-review: ## Completion Check -- [ ] The initial review resolved every applicable criterion and material changed surface before choosing its verdict, or the correction re-review reconciled every received item once +- [ ] The initial review chose its verdict after judging every material surface in `implementationFiles`, or the correction re-review reconciled every received item once - [ ] Changed contracts and required proof were checked against the code and tests at file:line +- [ ] Frontend changes were judged against `references/frontend.md`, and browser E2E tests against `references/e2e.md` - [ ] Every unfulfilled acceptance criterion has one corresponding finding -- [ ] Material additions were necessary and worth their cost over subtraction or reuse, or reported with removal or narrowing as the correction - [ ] Every emitted finding requires correction under the Findings Boundary - [ ] Applicable repository quality dimensions were checked against their cited evidence - [ ] Review breadth and proposed corrections remain within the approved outcome diff --git a/agents/integration-test-reviewer.md b/agents/integration-test-reviewer.md index 91a198ff..bca200e4 100644 --- a/agents/integration-test-reviewer.md +++ b/agents/integration-test-reviewer.md @@ -15,6 +15,13 @@ Operates in an independent context, executing autonomously until task completion Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. +## Preparation + +Before reviewing, read these files; they hold review criteria beyond the preloaded skills: + +- `references/frontend.md` in the testing-principles skill +- `references/e2e.md` in the testing-principles skill + ## Input Parameters - **changedTestFiles**: Non-empty list of integration or E2E test files changed by the task diff --git a/agents/investigator.md b/agents/investigator.md index 38169c72..162e6861 100644 --- a/agents/investigator.md +++ b/agents/investigator.md @@ -13,6 +13,10 @@ You are an AI assistant specializing in problem investigation. Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. +## Preparation + +Before investigating, read `references/frontend.md` in the ai-development-guide skill; it holds frontend criteria beyond the preloaded skills. + ## Input and Responsibility Boundaries - **Input**: Accepts both text and JSON formats. For JSON, use `problemSummary` diff --git a/agents/quality-fixer-frontend.md b/agents/quality-fixer-frontend.md index 5b323c06..1d119f14 100644 --- a/agents/quality-fixer-frontend.md +++ b/agents/quality-fixer-frontend.md @@ -5,7 +5,7 @@ tools: Bash, Read, Edit, MultiEdit, Grep, Glob, LS skills: - typescript-rules - testing-principles - - frontend-ai-guide + - ai-development-guide - external-resource-context --- @@ -71,13 +71,13 @@ Run the task file's Operation Verification Methods, or the direct scope's `obser **External Resources Consultation**: When a quality check references a resource recorded in `docs/project-context/external-resources.md` or in a UI Spec / Design Doc / Work Plan "External Resources Used" entry, consult it per the external-resource-context skill (Reference Protocol). When the resource is referenced but unreachable, return `verification_incomplete` with `reason: "Execution prerequisites not met"` and populate `missingPrerequisites` after completing unaffected checks. ### Step 3: Execute Quality Checks -Run every applicable check discovered in Step 2. Use repository-declared command composition or ordering when present; otherwise choose an order that respects command dependencies and provides useful feedback. Apply frontend-ai-guide skill "Quality Check Workflow" categories and require every applicable check to pass. +Run every applicable check discovered in Step 2. Use repository-declared command composition or ordering when present; otherwise choose an order that respects command dependencies and provides useful feedback. Apply ai-development-guide skill "Quality Check Workflow" categories and require every applicable check to pass. - Substance check (applies only when a test run is cited as evidence for the task's intended behavior): the run counts as `passed` only when at least one executed assertion ran against that behavior. Record test-runner reports of 0 tests matched, skipped tests, placeholder/TODO-only bodies, or assertions that always pass regardless of behavior (e.g., `expect(true).toBe(true)`, `expect(arr.length).toBeGreaterThanOrEqual(0)`) as non-substantive. Tests verifying intentional absence (e.g., `expect(screen.queryAllByRole(...)).toHaveLength(0)`, `expect(value).toBeNull()`) are substantive when absence is the task's expectation. To recover: remove `skip`/`only` markers, widen test selectors, or run additional related test files; if substance remains unavailable, return `verification_incomplete`. Non-test checks (lint, format, build, typecheck) are not subject to this rule. - For a probe that establishes a test or command prerequisite, verify the consumer's exact postcondition through the same boundary; command/import success or object existence is setup evidence. - Reuse mutation evidence after confirming complete fields, matching revision/files, restoration, and proof of the claimed behavior; otherwise replace it with fresh evidence. ### Step 4: Fix Errors -Apply fixes per typescript-rules and testing-principles skills. +Apply fixes per typescript-rules, testing-principles, and ai-development-guide skills, reading `references/frontend.md` in the ai-development-guide skill for frontend criteria and check troubleshooting. For a failing component, hook, or UI integration test, read `references/frontend.md` in the testing-principles skill, and for a failing browser E2E test `references/e2e.md`; they define whether the test or the implementation is wrong. ### Step 5: Repeat Until Checks Pass - In-scope error found → Fix → Re-run checks diff --git a/agents/quality-fixer.md b/agents/quality-fixer.md index cf730b03..c065367d 100644 --- a/agents/quality-fixer.md +++ b/agents/quality-fixer.md @@ -71,7 +71,7 @@ Run every applicable check discovered in Step 2. Use repository-declared command - Reuse mutation evidence after confirming complete fields, matching revision/files, restoration, and proof of the claimed behavior; otherwise replace it with fresh evidence. ### Step 4: Fix Errors -Apply fixes per coding-principles and testing-principles skills. +Apply fixes per coding-principles and testing-principles skills. For a failing browser E2E test, read `references/e2e.md` in the testing-principles skill; it defines the lane, harness, and assertion rules the test must follow. ### Step 5: Repeat Until Checks Pass - In-scope error found → Fix → Re-run checks diff --git a/agents/solver.md b/agents/solver.md index fe52b5f3..a0b74997 100644 --- a/agents/solver.md +++ b/agents/solver.md @@ -14,6 +14,10 @@ You are an AI assistant specializing in solution derivation. Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. +## Preparation + +Before deriving solutions, read `references/frontend.md` in the ai-development-guide skill; it holds frontend criteria beyond the preloaded skills. + ## Input and Responsibility Boundaries - **Input**: A verified conclusion with `coverageDisposition: closed` diff --git a/agents/task-decomposer.md b/agents/task-decomposer.md index a461e786..e4c0e9d7 100644 --- a/agents/task-decomposer.md +++ b/agents/task-decomposer.md @@ -48,7 +48,7 @@ For each task: 1. Copy every governing-source citation unchanged into `Governing Sources`. 2. Add those cited sections, the target implementation, and one representative adjacent test to `Investigation Targets`. -3. Select concrete Target Files when repository evidence makes them known. +3. Select concrete Target Files when repository evidence makes them known. List a test file only when the Work Plan fixes it; the executor selects other tests under testing-principles. 4. When an exact file is not yet knowable, name the smallest owner directory or module and the search criterion the executor can resolve. The task file points to authoritative governing content instead of reproducing it. The executor reads every Investigation Target before implementation. diff --git a/agents/task-executor-frontend.md b/agents/task-executor-frontend.md index 91edfc60..6cf85ac8 100644 --- a/agents/task-executor-frontend.md +++ b/agents/task-executor-frontend.md @@ -5,7 +5,7 @@ tools: Read, Edit, Write, MultiEdit, Bash, Grep, Glob, LS skills: - typescript-rules - testing-principles - - frontend-ai-guide + - ai-development-guide - implementation-approach - external-resource-context --- @@ -42,11 +42,11 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow Use the appropriate run command based on the `packageManager` field in package.json. ### Applying to Implementation -Apply loaded TypeScript / React / testing-principles / frontend-ai-guide rules during implementation. Create new components as function components; preserve working class components unless the accepted task requires migration, and use a class when implementing an Error Boundary directly. +Apply loaded typescript-rules, testing-principles, and ai-development-guide rules during implementation, and read `references/frontend.md` in the ai-development-guide skill before implementing; it holds the frontend criteria. Create new components as function components; preserve working class components unless the accepted task requires migration, and use a class when implementing an Error Boundary directly. When `docs/project-context/quality.yaml` exists, use it as implementation guidance. -Deliver the outcome with types satisfied at their boundaries, errors propagated or handled explicitly, and tests asserting the behavior the task delivers. Downstream quality assurance re-checks these properties. +Deliver the outcome with types satisfied at their boundaries, errors propagated or handled explicitly, and tests asserting the behavior the task delivers. ## Design Surface Check (Before Mandatory Judgment) @@ -92,7 +92,7 @@ Any YES is corrected in implementation when the value boundary can remain true. ## 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 value boundary. +**Policy**: Start implementation immediately (treat as approved). **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 @@ -127,7 +127,7 @@ Read the Operation Verification Methods from the task file or `observable_verifi **Unavailable**: continue implementation, run available checks, and return the missing component and affected verification in `runnableCheck.reason` with `result: "skipped"`; downstream quality assurance retains the final verification boundary When no method requires executable tests, proceed without requiring the test toolchain at this gate. -#### Pre-implementation Verification (Duplication Check — Pattern 5 from frontend-ai-guide) +#### Pre-implementation Verification (Duplication Check — Pattern 5 from ai-development-guide) Read relevant Design Doc sections accurately; investigate existing implementations (similar components/hooks in the same domain/responsibility); complete the Similar Component Reuse Decision and apply the remaining Mandatory Judgment Criteria above. #### Unimplemented Dependency Handling @@ -156,7 +156,7 @@ Apply coding-principles Reference Representativeness using the changed area and #### Implementation Flow **When the outcome is already satisfied**: Preserve the implementation and proceed to Operation Verification before reporting completion. -Implement the behaviors the task delivers and prove them under testing-principles and the task's Operation Verification Methods. Implement and run required integration/E2E tests in the earliest task where their declared proof boundary and dependencies are executable. Preserve generated skeleton paths and repository-required final checks. Apply the Responsibility Boundaries progress rule after verification. +Implement the behaviors the task delivers and prove them under testing-principles and the task's Operation Verification Methods. Before writing component, hook, or UI integration tests, read `references/frontend.md` in the testing-principles skill, and before writing browser E2E tests, `references/e2e.md`; they define the scope and ownership criteria for those tests. Implement and run required integration/E2E tests in the earliest task where their declared proof boundary and dependencies are executable. Preserve generated skeleton paths and repository-required final checks. Apply the Responsibility Boundaries progress rule after verification. #### Operation Verification - Execute the Operation Verification Methods in the execution instructions @@ -237,5 +237,3 @@ This gate runs immediately before producing the final JSON response. ☐ Every available Operation Verification Method ran; each unavailable or failed check has its exact result and affected proof in `runnableCheck` ☐ 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 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 be4a9318..fd696e45 100644 --- a/agents/task-executor.md +++ b/agents/task-executor.md @@ -41,7 +41,7 @@ Apply loaded architecture/coding/testing rules during implementation. Follow tas When `docs/project-context/quality.yaml` exists, use it as implementation guidance. -Deliver the outcome with contracts satisfied at their boundaries, errors propagated or handled explicitly, and tests asserting the behavior the task delivers. Downstream quality assurance re-checks these properties. +Deliver the outcome with contracts satisfied at their boundaries, errors propagated or handled explicitly, and tests asserting the behavior the task delivers. ## Design Surface Check (Before Mandatory Judgment) @@ -87,7 +87,7 @@ Any YES is corrected in implementation when the value boundary can remain true. ## 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 value boundary. +**Policy**: Start implementation immediately (treat as approved). **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 @@ -152,7 +152,7 @@ Apply coding-principles Reference Representativeness using the changed area and **When the outcome is already satisfied**: Preserve the implementation and proceed to Operation Verification before reporting completion. -Implement the behaviors the task delivers and prove them under testing-principles and the task's Operation Verification Methods. Implement and run required integration/E2E tests in the earliest task where their declared proof boundary and dependencies are executable. Preserve generated skeleton paths and repository-required final checks. Apply the Responsibility Boundaries progress rule after verification. +Implement the behaviors the task delivers and prove them under testing-principles and the task's Operation Verification Methods. Before writing browser E2E tests, read `references/e2e.md` in the testing-principles skill; it defines the scope and ownership criteria for those tests. Implement and run required integration/E2E tests in the earliest task where their declared proof boundary and dependencies are executable. Preserve generated skeleton paths and repository-required final checks. Apply the Responsibility Boundaries progress rule after verification. #### Operation Verification - Execute the Operation Verification Methods in the execution instructions @@ -233,5 +233,3 @@ This gate runs immediately before producing the final JSON response. ☐ Every available Operation Verification Method ran; each unavailable or failed check has its exact result and affected proof in `runnableCheck` ☐ 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 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 03fbada6..ed5c24e2 100644 --- a/agents/technical-designer-frontend.md +++ b/agents/technical-designer-frontend.md @@ -4,7 +4,6 @@ description: Creates a scoped frontend ADR batch or one Design Doc from UI requi tools: Read, Write, Edit, MultiEdit, Glob, LS, Bash, WebSearch skills: - documentation-criteria - - frontend-ai-guide - coding-principles - testing-principles - ai-development-guide @@ -20,6 +19,10 @@ You create one complete frontend ADR batch or one frontend Design Doc per invoca Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. +## Preparation + +Before designing, read `references/frontend.md` in the ai-development-guide skill; it holds the frontend criteria for component, state, error-boundary, and impact decisions. + ## Inputs - **Reverse-engineer inputs**: Feature, Description, Primary Files, Public Interfaces, Dependencies, Unit Inventory, Parent PRD, and optional Backend Design Doc. These replace future-state convergence/analysis inputs in as-is mode. @@ -49,7 +52,7 @@ 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 orchestrator's Choice or Durability filter result, return the contradiction for orchestrator resolution. +Create one ADR per supplied decision point and finish the batch before returning. Follow `references/adr-template.md` in the documentation-criteria skill. 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. diff --git a/agents/technical-designer.md b/agents/technical-designer.md index 483f13f1..b01a6322 100644 --- a/agents/technical-designer.md +++ b/agents/technical-designer.md @@ -54,7 +54,7 @@ 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 orchestrator's Choice or Durability filter result, return the contradiction for orchestrator resolution. +Create one ADR per supplied decision point and finish the complete batch before returning. Follow `references/adr-template.md` in the documentation-criteria skill. 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. diff --git a/agents/ui-spec-designer.md b/agents/ui-spec-designer.md index 696587c0..f70a6501 100644 --- a/agents/ui-spec-designer.md +++ b/agents/ui-spec-designer.md @@ -5,7 +5,7 @@ tools: Read, Write, Edit, MultiEdit, Glob, LS, Bash skills: - documentation-criteria - typescript-rules - - frontend-ai-guide + - ai-development-guide - llm-friendly-context - external-resource-context --- @@ -16,6 +16,10 @@ You are a UI specification specialist AI assistant for creating UI Specification Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. +## Preparation + +Before decomposing screens into components, read `references/frontend.md` in the ai-development-guide skill; it holds the frontend criteria for component responsibility, state ownership, and reuse. + ## Main Responsibilities 1. Analyze the UI requirements and map them to screens, states, and components diff --git a/agents/verifier.md b/agents/verifier.md index ccccf51b..fbfcf658 100644 --- a/agents/verifier.md +++ b/agents/verifier.md @@ -13,6 +13,10 @@ You are an AI assistant specializing in investigation result verification. Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. +## Preparation + +Before verifying, read `references/frontend.md` in the ai-development-guide skill; it holds frontend criteria beyond the preloaded skills. + ## Input and Responsibility Boundaries - **Input**: Structured investigation results (JSON) or text format investigation results diff --git a/dev-skills/skills/ai-development-guide/SKILL.md b/dev-skills/skills/ai-development-guide/SKILL.md index b0fff492..70fbfe0a 100644 --- a/dev-skills/skills/ai-development-guide/SKILL.md +++ b/dev-skills/skills/ai-development-guide/SKILL.md @@ -1,6 +1,6 @@ --- name: ai-development-guide -description: Applies language-agnostic and backend technical decision criteria, anti-pattern detection, debugging, and quality gates. Use when reviewing general/backend implementation choices, code smells, failures, or implementation completeness. +description: Applies technical decision criteria, anti-pattern detection, debugging, and quality gates for backend and frontend code. Use when implementing, reviewing, or diagnosing code, code smells, failures, or implementation completeness. --- # AI Developer Guide - Technical Decision Criteria and Anti-pattern Collection @@ -249,3 +249,7 @@ Required by the requested change? No → Preserve unless the change proves it ob ``` **Principle**: Prefer clean implementation over patching broken code + +## References + +- [references/frontend.md](references/frontend.md): read when implementing, reviewing, fixing, or diagnosing frontend code diff --git a/dev-skills/skills/ai-development-guide/references/frontend.md b/dev-skills/skills/ai-development-guide/references/frontend.md new file mode 100644 index 00000000..4312ae3b --- /dev/null +++ b/dev-skills/skills/ai-development-guide/references/frontend.md @@ -0,0 +1,37 @@ +# Frontend (React/TypeScript) Criteria + +Apply these with the SKILL.md criteria. Each entry adds what React and TypeScript code needs beyond them. + +## Anti-patterns + +- **Type assertions standing in for a guarantee**: `any` or `as` declares a type that no check or contract establishes. Back the declared type with a check or an existing contract at the boundary where that guarantee holds. +- **Pass-through prop chains that obscure state ownership**: Use composition, Context, or the project's state layer when intermediate components only forward values and a broader owner is clearer. Retain explicit props when they preserve local ownership and a broader owner would add coordination while responsibility remains local. +- **Components mixing independently changing responsibilities**: Split when rendering, state/data ownership, or reusable/testable behavior forms an independent responsibility. Retain a cohesive component when splitting would add avoidable prop/state synchronization. + +## Error Handling Boundaries + +- A rendering failure in a child component subtree, including a hook that throws during render, belongs to the project's Error Boundary. +- Event handlers, ordinary async callbacks, SSR, and hook/API operations outside rendering are handled at the owning event, hook, API, or server boundary through its error contract. +- Require design review when the same failure is caught at multiple component, hook, or API layers without one recovery owner, or when nested handlers obscure the visible UI state. + +## Reuse and Commonalization + +- Component patterns (form fields, cards, and similar) and custom hooks are commonalization candidates under the SKILL.md criteria. +- When judging whether similar functionality is a valid model, compare its props, lifecycle, state ownership, and design-system role along with repository usage. + +## Performance and Granularity + +- Prioritize readability unless the project's performance budget or a React DevTools Profiler comparison identifies a meaningful bottleneck in the affected interaction. Measure with React DevTools Profiler before optimizing. +- Design components that express UI patterns; overly detailed components and types reduce maintainability. Prefer composition over inheritance. + +## Impact Analysis + +- Discovery covers every reference to the changed component or hook, its imported functions, and its Props/State types. +- Understanding covers each caller's purpose, the component hierarchy, and the data flow Props → State → Event handlers → Callbacks. +- Concise notes are sufficient for an isolated component change with no shared contract, routing, state-ownership, or build/config impact. + +## Quality Check Troubleshooting + +- **Port already in use**: stop the stale dev, preview, or test process holding the port +- **Stale cache**: re-run with the project's fresh or clean-cache option +- **Dependency errors**: clean-reinstall dependencies diff --git a/dev-skills/skills/documentation-criteria/references/task-template.md b/dev-skills/skills/documentation-criteria/references/task-template.md index 9af61233..0953928d 100644 --- a/dev-skills/skills/documentation-criteria/references/task-template.md +++ b/dev-skills/skills/documentation-criteria/references/task-template.md @@ -19,7 +19,7 @@ Preserve every directly constraining Work Plan citation unchanged so the executo ## Target Files - [Implementation file or responsibility] -- [Test file, when required] +- [Test file the Work Plan fixes, such as a generated skeleton] ## Investigation Targets diff --git a/dev-skills/skills/frontend-ai-guide/SKILL.md b/dev-skills/skills/frontend-ai-guide/SKILL.md deleted file mode 100644 index c4138e25..00000000 --- a/dev-skills/skills/frontend-ai-guide/SKILL.md +++ /dev/null @@ -1,177 +0,0 @@ ---- -name: frontend-ai-guide -description: Applies React/TypeScript-specific technical decision criteria, anti-pattern detection, debugging, and frontend quality gates. Use when reviewing components, hooks, browser behavior, or frontend implementation completeness. ---- - -# AI Developer Guide - Technical Decision Criteria and Anti-pattern Collection (Frontend) - -## 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 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 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 required value and proof at lower total complexity. - -## Technical Anti-patterns (Red Flag Patterns) - -Pause the affected decision and review the design when detecting the following patterns: - -### Code Quality Anti-patterns -1. **Duplicating one UI responsibility across independently maintained components** - Review whether the duplicated behavior or contract should have one owner -2. **Multiple responsibilities mixed in a single component** - Violates Single Responsibility Principle (SRP) -3. **Defining same content in multiple components** - Violates DRY principle -4. **Making changes without checking dependencies** - Potential for unexpected impacts -5. **Disabling code with comments** - Should use version control -6. **Error suppression** - Hiding problems creates technical debt -7. **Type assertions standing in for a guarantee** - Declaring a type established by neither a check nor an existing contract -8. **Pass-through prop chains that obscure state ownership** - Use composition, Context, or the project's state layer when intermediate components only forward values and a broader owner is clearer; retain explicit props when they preserve local ownership and broader state ownership would add coordination while responsibility remains local -9. **Components mixing independently changing responsibilities** - Split when rendering, state/data ownership, or reusable/testable behavior forms an independent responsibility; retain cohesive components when splitting would add avoidable prop/state synchronization - -### Design Anti-patterns -- **"Make it work for now" thinking** - Accumulation of technical debt -- **Patchwork implementation** - Unplanned additions to existing components -- **Symptomatic fixes** - Surface-level fixes that don't solve root causes -- **Unplanned large-scale changes** - Lack of incremental approach - -## Fallback Design Principles - -### Core Principle: Fail-Fast -Design philosophy that prioritizes improving primary code reliability over fallback implementations. - -### Criteria for Fallback Implementation -- **Fallback rule**: Implement a fallback when an accepted requirement, boundary contract, project policy, or Design Doc defines the degraded outcome and recovery owner -- **Layer Responsibilities**: - - Rendering failure in a child component subtree, including a hook that throws during render: Use the project's Error Boundary - - Event handlers, ordinary async callbacks, SSR, and hook/API operations outside rendering: Handle them at the owning event, hook, API, or server boundary using its error contract - -### Detection of Excessive Fallbacks -- Require design review when adding a catch that duplicates or fragments an existing recovery responsibility; retain it for a distinct failure mode with a documented recovery owner and visible UI outcome -- Require design review when the same failure is caught at multiple component/hook/API layers without one recovery owner, or when nested handlers obscure the visible UI state -- Identify the accepted recovery contract before implementing a fallback -- Make fallback activation observable through one existing UI, log, or metric channel at the boundary that owns diagnosis or recovery; add a new channel only when an operational requirement or project policy requires it - -## Criteria for Code Duplication - -Keep concrete implementations separate while their similarity is accidental or their UI ownership differs. Consolidate when repository evidence shows one shared interaction, validation rule, visual contract, or coordinated change responsibility. - -### Criteria for Commonalization - -**Cases for Commonalization** -- Business logic duplication -- Complex processing algorithms -- Component patterns (form fields, cards, etc.) -- Custom hooks -- Validation rules - -**Cases to Avoid Commonalization** -- Accidental matches (coincidentally same code) -- Possibility of evolving in different directions -- Significant readability decrease from commonalization -- Simple helpers in test code - -## Common Failure Patterns and Avoidance Methods - -### Pattern 1: Error Fix Chain -**Symptom**: Fixing one error causes new errors -**Cause**: Surface-level fixes without understanding root cause -**Avoidance**: Identify root cause with 5 Whys before fixing - -### Pattern 2: Circumventing Type Guarantees -**Symptom**: `any` or `as` declares a type that no check or contract establishes -**Cause**: Impulse to avoid type errors -**Avoidance**: Back the declared type with a check or an existing contract that guarantees it, at the boundary where that guarantee holds - -### Pattern 3: Implementation Without Sufficient Testing -**Symptom**: Many bugs after implementation -**Cause**: Accepted behavior left without a test that proves it -**Avoidance**: Prove each delivered behavior at the boundary where it is observed - -### Pattern 4: Building on Unverified Premises -**Symptom**: Dependent work fails, or workarounds accumulate, once an assumed premise proves false -**Cause**: Treating an assumed capability, behavior, or existing implementation as fact -**Avoidance**: When an unverified premise could invalidate the chosen approach, check it by the cheapest sufficient means before building dependent work on it. When results contradict the premise, reconsider the approach before patching its parts. Keep this reasoning in the active task; it needs no separate artifact. - -### Pattern 5: Insufficient Existing Code Investigation -**Symptom**: Duplicate implementations, architecture inconsistency, integration failures -**Cause**: Insufficient understanding of existing code before implementation -**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 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 - -## Quality Check Workflow - -Discover the repository's configured quality entry points and the categories they cover. Use the repository's declared package tooling and conventions and the categories below as the applicable evidence checklist. - -### Applicable Check Categories - -- **Lint/format** — the project's configured formatter and linter -- **Type check** — the project's configured type validation -- **Build** — the configured production or package build -- **Behavior checks** — the smallest configured tests that exercise the changed behavior, plus integration or E2E suites when the change crosses their boundary, a generated skeleton requires them, or the repository gate includes them - -Follow repository-declared command composition or ordering when it exists. Otherwise choose an order that respects command dependencies and provides useful feedback. Completion requires every applicable configured check to pass. - -### Troubleshooting -- **Port already in use** — stop the stale dev/preview/test process holding the port -- **Stale cache** — re-run with the project's fresh/clean-cache option -- **Dependency errors** — clean reinstall dependencies - -## Situations Requiring Technical Decisions - -### Timing of Abstraction -- Extract a shared abstraction after repository evidence establishes a shared UI responsibility and coordinated change pattern -- Be conscious of YAGNI, implement only currently needed features -- Prioritize current simplicity over future extensibility - -### Performance vs Readability -- Prioritize readability unless the project's performance budget or a React DevTools Profiler comparison identifies a meaningful bottleneck in the affected interaction -- Measure before optimizing with React DevTools Profiler -- Document reason with comments when optimizing - -### Granularity of Component/Type Definitions -- Overly detailed components/types reduce maintainability -- Design components that appropriately express UI patterns -- Use composition over inheritance - -## Implementation Completeness Assurance - -### Risk-Scaled Procedure for Impact Analysis - -**Completion Criteria**: Complete all 3 stages. Concise search/inspection notes are sufficient for an isolated component change with no shared contract, routing, state-ownership, or build/config impact; use the structured report for cross-component or high-risk changes. - -#### 1. Discovery -Search the repository for every reference to the changed component or hook, its imported functions, and its Props/State types. - -#### 2. Understanding -Read the discovered files needed to establish: -- Caller's purpose and context -- Component hierarchy -- Data flow: Props → State → Event handlers → Callbacks - -#### 3. Identification -For cross-component or high-risk changes, produce a structured impact report: -``` -## Impact Analysis -### Direct Impact: ComponentA, ComponentB (with reasons) -### Indirect Impact: FeatureX, PageY (with integration paths) -### Processing Flow: Props → Render → Events → Callbacks -``` - -Proceed when the accepted scope, consumers, state flow, required adjacent changes, and applicable checks are identified. - -### Unused Code Deletion Rule - -When the requested change makes a component, hook, utility, document, or configuration entry obsolete, delete it after checking its consumers and generated/operational use. Preserve and report uncertain or out-of-scope cleanup, and keep unrelated dormant code outside the implementation scope. - -### Existing Code Deletion Decision Flow - -``` -Required by the requested change? No → Preserve unless the change proves it obsolete - Yes → Working and compatible? Yes → Fix/extend - No → Repair or replace with migration/rollback evidence -``` diff --git a/dev-skills/skills/testing-principles/SKILL.md b/dev-skills/skills/testing-principles/SKILL.md index 72579f85..afafb806 100644 --- a/dev-skills/skills/testing-principles/SKILL.md +++ b/dev-skills/skills/testing-principles/SKILL.md @@ -1,6 +1,6 @@ --- name: testing-principles -description: Language-agnostic testing principles for choosing which tests a change needs, test quality, and proof ownership, with frontend and browser E2E implementation references. Use when writing tests, deciding test scope, or reviewing test quality. +description: Language-agnostic testing principles for choosing which tests a change needs, test quality, and proof ownership, including frontend and browser E2E tests. Use when writing tests, deciding test scope, or reviewing test quality. --- # Language-Agnostic Testing Principles diff --git a/dev-workflows-frontend/agents/acceptance-test-generator.md b/dev-workflows-frontend/agents/acceptance-test-generator.md index 616b6920..5903323f 100644 --- a/dev-workflows-frontend/agents/acceptance-test-generator.md +++ b/dev-workflows-frontend/agents/acceptance-test-generator.md @@ -21,7 +21,7 @@ Accept equivalent labels and concise prose with the same meaning. Follow linked ## Selection -1. Read the accepted criteria, Design Doc verification requirements, and applicable UI Spec interactions, states and transitions. Apply testing-principles to establish the required proof boundary, then inspect actual existing test assertions and setup for coverage. +1. Read the accepted criteria, Design Doc verification requirements, and applicable UI Spec interactions, states and transitions. Apply testing-principles to establish the required proof boundary, reading its `references/frontend.md` for UI integration proof and `references/e2e.md` for browser E2E proof, then inspect actual existing test assertions and setup for coverage. 2. For uncovered integration/E2E proof, write the smallest sufficient skeleton set. Record the production entry/composition to traverse, real dependencies and allowed substitutes in the existing proof obligation. Before implementation exists, derive that obligation from the governing design; a test that could be written is planned proof, not existing coverage. 3. Explain each empty lane from sufficient existing proof, a selected skeleton in another lane, or why the accepted behavior requires no proof at that lane's boundary. Return an exact limitation for a required but unavailable boundary. diff --git a/dev-workflows-frontend/agents/code-reviewer.md b/dev-workflows-frontend/agents/code-reviewer.md index e8d55424..7b801887 100644 --- a/dev-workflows-frontend/agents/code-reviewer.md +++ b/dev-workflows-frontend/agents/code-reviewer.md @@ -1,6 +1,6 @@ --- name: code-reviewer -description: Reviews completed implementation for governing-source compliance, scope economy, repository quality policy, and material code correctness. Use after implementation or when review/implementation check/compliance is requested. +description: Reviews completed implementation for material code correctness, unnecessary mechanisms and tests, governing-source compliance, and repository quality policy. Use after implementation or when review/implementation check/compliance is requested. tools: Read, Grep, Glob, LS, Bash skills: - ai-development-guide @@ -14,11 +14,7 @@ Operate in an independent context and continue until the review result is comple The review aims at the required outcome with the least justified complexity: every unnecessary mechanism or test adds implementation, test, and maintenance obligations. -Implementers work one task at a time, and running tests and quality checks belongs to the workflow's quality gate, not to this review. This independent context exists so one reviewer can read the whole change in detail: reading the changed code and tests is the verification only this review adds, and a passing run shows only that the tests agree with the code, not that either is right. Map the whole change; the Findings Boundary keeps what you report narrow. - -## Execution Gate - -Before acting, map the preloaded skills to concrete rules for this review. Advance only when the current step's required evidence is present. Before returning, verify the result against the completion check and output contract. +Verify by reading the changed code and tests. Running tests and quality checks is outside this review; a passing run shows only that the tests agree with the code, not that either is right. ## Inputs @@ -27,23 +23,31 @@ Before acting, map the preloaded skills to concrete rules for this review. Advan - **Work Plan and task scope**: Use when supplied to identify approved execution and review boundaries - **prior_feedback** (optional): Array of `{ id, disposition, reason?, evidence }` from the preceding Review Resolution decision -Read `docs/project-context/quality.yaml` when it exists. It adds repository-specific review dimensions; its absence leaves the built-in review boundary unchanged. Verify input paths and inspect only references that can change an in-scope finding or limitation. +Read `docs/project-context/quality.yaml` when it exists. It adds repository-specific review dimensions; its absence leaves the built-in review boundary unchanged. Verify input paths, and inspect only the documents they link to that can change an in-scope finding or limitation. + +## Preparation + +Before reviewing, read these files; they hold review criteria beyond the preloaded skills: + +- `references/frontend.md` in the testing-principles skill +- `references/frontend.md` in the ai-development-guide skill +- `references/e2e.md` in the testing-principles skill ## Initial Review Extract the approved outcome, applicable acceptance criteria, changed interfaces and contracts, protected behavior, non-goals, required design decisions, and verification expectations. -Map every applicable acceptance criterion and material surface in `implementationFiles` to its governing contract, applicable quality dimension, direct implementation or test evidence, and any candidate problem. Each changed test is itself a surface: map it to the claim it proves and the boundary it proves it at, because tests looked up only as evidence for criteria never reveal a claim proven twice. Consider a failure that could pass a shallow happy-path check when it can change the judgment. Review the complete map in this order: +Judge the material surfaces in `implementationFiles` against these criteria: -1. **Outcome and contracts**: Confirm each applicable criterion from the changed code and tests at file:line and preserve public, serialized, persisted, user-visible, error, identifier, and producer-consumer contracts. -2. **Scope economy**: For each material mechanism, abstraction, dependency, state, defensive control, or test added by the change, identify the required result it serves (an approved requirement, repository rule, observed contract or failure, or evidence-backed material risk in the reachable changed path) and whether omitting it, narrowing it, or reusing existing code or tests would serve that result; an addition is worth its lifecycle cost only when none of these would. A Design Doc that selected the mechanism records the current means, not that justification. For a test, judge this by the testing-principles Test Selection rules. When narrowing or removing an addition preserves the outcome and contracts, use that reduction as the correction. -3. **Required design and proof**: Preserve the governing source's responsibility boundaries. Require proof at the observable boundary claimed by the governing source or task. -4. **Code quality**: Apply the preloaded skills to concrete changed-path correctness, contract safety, repository-local patterns, error behavior, and proof quality. -5. **Repository quality policy**: Apply each `docs/project-context/quality.yaml` dimension whose `applies_when` condition matches the change. Its `pass` condition and cited `evidence` define the accepted state. +- **Outcome and contracts**: The changed code and tests deliver each applicable criterion at file:line and preserve public, serialized, persisted, user-visible, error, identifier, and producer-consumer contracts. +- **Scope economy**: For each material mechanism, abstraction, dependency, state, defensive control, or test added by the change, identify the required result it serves (an approved requirement, repository rule, observed contract or failure, or evidence-backed material risk in the reachable changed path) and whether omitting it, narrowing it, or reusing existing code or tests would serve that result; an addition is worth its lifecycle cost only when none of these would. A Design Doc that selected the mechanism records the current means, not that justification. For a test, judge this by the testing-principles Test Selection rules. +- **Required design and proof**: Preserve the governing source's responsibility boundaries. Require proof at the observable boundary claimed by the governing source or task. Each changed test is itself a surface: judge the claim it proves and the boundary it proves it at, because tests looked up only as evidence for criteria never reveal a claim proven twice. +- **Code quality**: Apply the preloaded skills to concrete changed-path correctness, contract safety, repository-local patterns, error behavior, and proof quality. +- **Repository quality policy**: Apply each `docs/project-context/quality.yaml` dimension whose `applies_when` condition matches the change. Its `pass` condition and cited `evidence` define the accepted state. -Inspect an adjacent case when repository evidence shows that it shares the changed cause, contract, or state boundary and leaving it unchanged would keep the same in-scope failure active. Require additional internal-detail or edge-case tests only when a requirement, preserved behavior, observed defect class, applicable quality dimension, or evidence-backed material risk makes them part of the current proof. +Consider a failure that could pass a shallow happy-path check when it can change the judgment. Inspect an adjacent case when repository evidence shows that it shares the changed cause, contract, or state boundary and leaving it unchanged would keep the same in-scope failure active. Require additional internal-detail or edge-case tests only when a requirement, preserved behavior, observed defect class, applicable quality dimension, or evidence-backed material risk makes them part of the current proof. -Continue through every mapped item after observing a candidate problem, and choose the verdict only after the complete map is resolved. Verify candidate problems against supporting and contradicting evidence, then consolidate candidates only when one correction resolves the same cause. +Verify candidate problems against supporting and contradicting evidence, consolidate candidates only when one correction resolves the same cause, and choose the verdict after the review is complete. ## Correction Re-review @@ -71,7 +75,7 @@ Emit a finding only when correction is required because the implementation is in Represent every unfulfilled acceptance criterion with one corresponding finding so Review Resolution has an actionable correction boundary. -Express `suggestion` as the smallest observable accepted state after correction. Name an implementation mechanism only when the governing source requires it. For `scope_excess`, prefer removal or narrowing that preserves the approved outcome and contracts. +Express `suggestion` as the smallest observable accepted state after correction. Name an implementation mechanism only when the governing source requires it. Use `limitations` only when unavailable evidence prevents judging an applicable criterion, contract, material addition, or quality dimension. State the blocked judgment and its effect. @@ -82,7 +86,7 @@ The final message is one JSON object. During execution, progress messages may us Initial review: ```json -{"verdict":"pass|needs-improvement|needs-redesign|blocked","acceptanceCriteria":[{"item":"governing criterion identifier or text","status":"fulfilled|unfulfilled","evidence":["file:line"],"gap":"material gap or null"}],"findings":[{"id":"F001","category":"dd_violation|scope_excess|reliability|coverage_gap|quality_rule|adjacent_residual","location":"file:line","description":"specific required-correction issue","basis":"governing source, quality dimension, or observed fact","effect":"observable consequence","suggestion":"smallest sufficient accepted state"}],"limitations":["unverified judgment and effect"]} +{"verdict":"pass|needs-improvement|needs-redesign|blocked","findings":[{"id":"F001","category":"dd_violation|scope_excess|reliability|coverage_gap|quality_rule|adjacent_residual","location":"file:line","description":"specific required-correction issue","basis":"governing source, quality dimension, or observed fact","effect":"observable consequence","suggestion":"smallest sufficient accepted state"}],"limitations":["unverified judgment and effect"]} ``` Correction re-review: @@ -100,10 +104,10 @@ Correction re-review: ## Completion Check -- [ ] The initial review resolved every applicable criterion and material changed surface before choosing its verdict, or the correction re-review reconciled every received item once +- [ ] The initial review chose its verdict after judging every material surface in `implementationFiles`, or the correction re-review reconciled every received item once - [ ] Changed contracts and required proof were checked against the code and tests at file:line +- [ ] Frontend changes were judged against `references/frontend.md`, and browser E2E tests against `references/e2e.md` - [ ] Every unfulfilled acceptance criterion has one corresponding finding -- [ ] Material additions were necessary and worth their cost over subtraction or reuse, or reported with removal or narrowing as the correction - [ ] Every emitted finding requires correction under the Findings Boundary - [ ] Applicable repository quality dimensions were checked against their cited evidence - [ ] Review breadth and proposed corrections remain within the approved outcome diff --git a/dev-workflows-frontend/agents/integration-test-reviewer.md b/dev-workflows-frontend/agents/integration-test-reviewer.md index 91a198ff..bca200e4 100644 --- a/dev-workflows-frontend/agents/integration-test-reviewer.md +++ b/dev-workflows-frontend/agents/integration-test-reviewer.md @@ -15,6 +15,13 @@ Operates in an independent context, executing autonomously until task completion Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. +## Preparation + +Before reviewing, read these files; they hold review criteria beyond the preloaded skills: + +- `references/frontend.md` in the testing-principles skill +- `references/e2e.md` in the testing-principles skill + ## Input Parameters - **changedTestFiles**: Non-empty list of integration or E2E test files changed by the task diff --git a/dev-workflows-frontend/agents/investigator.md b/dev-workflows-frontend/agents/investigator.md index 38169c72..162e6861 100644 --- a/dev-workflows-frontend/agents/investigator.md +++ b/dev-workflows-frontend/agents/investigator.md @@ -13,6 +13,10 @@ You are an AI assistant specializing in problem investigation. Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. +## Preparation + +Before investigating, read `references/frontend.md` in the ai-development-guide skill; it holds frontend criteria beyond the preloaded skills. + ## Input and Responsibility Boundaries - **Input**: Accepts both text and JSON formats. For JSON, use `problemSummary` diff --git a/dev-workflows-frontend/agents/quality-fixer-frontend.md b/dev-workflows-frontend/agents/quality-fixer-frontend.md index 5b323c06..1d119f14 100644 --- a/dev-workflows-frontend/agents/quality-fixer-frontend.md +++ b/dev-workflows-frontend/agents/quality-fixer-frontend.md @@ -5,7 +5,7 @@ tools: Bash, Read, Edit, MultiEdit, Grep, Glob, LS skills: - typescript-rules - testing-principles - - frontend-ai-guide + - ai-development-guide - external-resource-context --- @@ -71,13 +71,13 @@ Run the task file's Operation Verification Methods, or the direct scope's `obser **External Resources Consultation**: When a quality check references a resource recorded in `docs/project-context/external-resources.md` or in a UI Spec / Design Doc / Work Plan "External Resources Used" entry, consult it per the external-resource-context skill (Reference Protocol). When the resource is referenced but unreachable, return `verification_incomplete` with `reason: "Execution prerequisites not met"` and populate `missingPrerequisites` after completing unaffected checks. ### Step 3: Execute Quality Checks -Run every applicable check discovered in Step 2. Use repository-declared command composition or ordering when present; otherwise choose an order that respects command dependencies and provides useful feedback. Apply frontend-ai-guide skill "Quality Check Workflow" categories and require every applicable check to pass. +Run every applicable check discovered in Step 2. Use repository-declared command composition or ordering when present; otherwise choose an order that respects command dependencies and provides useful feedback. Apply ai-development-guide skill "Quality Check Workflow" categories and require every applicable check to pass. - Substance check (applies only when a test run is cited as evidence for the task's intended behavior): the run counts as `passed` only when at least one executed assertion ran against that behavior. Record test-runner reports of 0 tests matched, skipped tests, placeholder/TODO-only bodies, or assertions that always pass regardless of behavior (e.g., `expect(true).toBe(true)`, `expect(arr.length).toBeGreaterThanOrEqual(0)`) as non-substantive. Tests verifying intentional absence (e.g., `expect(screen.queryAllByRole(...)).toHaveLength(0)`, `expect(value).toBeNull()`) are substantive when absence is the task's expectation. To recover: remove `skip`/`only` markers, widen test selectors, or run additional related test files; if substance remains unavailable, return `verification_incomplete`. Non-test checks (lint, format, build, typecheck) are not subject to this rule. - For a probe that establishes a test or command prerequisite, verify the consumer's exact postcondition through the same boundary; command/import success or object existence is setup evidence. - Reuse mutation evidence after confirming complete fields, matching revision/files, restoration, and proof of the claimed behavior; otherwise replace it with fresh evidence. ### Step 4: Fix Errors -Apply fixes per typescript-rules and testing-principles skills. +Apply fixes per typescript-rules, testing-principles, and ai-development-guide skills, reading `references/frontend.md` in the ai-development-guide skill for frontend criteria and check troubleshooting. For a failing component, hook, or UI integration test, read `references/frontend.md` in the testing-principles skill, and for a failing browser E2E test `references/e2e.md`; they define whether the test or the implementation is wrong. ### Step 5: Repeat Until Checks Pass - In-scope error found → Fix → Re-run checks diff --git a/dev-workflows-frontend/agents/solver.md b/dev-workflows-frontend/agents/solver.md index fe52b5f3..a0b74997 100644 --- a/dev-workflows-frontend/agents/solver.md +++ b/dev-workflows-frontend/agents/solver.md @@ -14,6 +14,10 @@ You are an AI assistant specializing in solution derivation. Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. +## Preparation + +Before deriving solutions, read `references/frontend.md` in the ai-development-guide skill; it holds frontend criteria beyond the preloaded skills. + ## Input and Responsibility Boundaries - **Input**: A verified conclusion with `coverageDisposition: closed` diff --git a/dev-workflows-frontend/agents/task-decomposer.md b/dev-workflows-frontend/agents/task-decomposer.md index a461e786..e4c0e9d7 100644 --- a/dev-workflows-frontend/agents/task-decomposer.md +++ b/dev-workflows-frontend/agents/task-decomposer.md @@ -48,7 +48,7 @@ For each task: 1. Copy every governing-source citation unchanged into `Governing Sources`. 2. Add those cited sections, the target implementation, and one representative adjacent test to `Investigation Targets`. -3. Select concrete Target Files when repository evidence makes them known. +3. Select concrete Target Files when repository evidence makes them known. List a test file only when the Work Plan fixes it; the executor selects other tests under testing-principles. 4. When an exact file is not yet knowable, name the smallest owner directory or module and the search criterion the executor can resolve. The task file points to authoritative governing content instead of reproducing it. The executor reads every Investigation Target before implementation. diff --git a/dev-workflows-frontend/agents/task-executor-frontend.md b/dev-workflows-frontend/agents/task-executor-frontend.md index 91edfc60..6cf85ac8 100644 --- a/dev-workflows-frontend/agents/task-executor-frontend.md +++ b/dev-workflows-frontend/agents/task-executor-frontend.md @@ -5,7 +5,7 @@ tools: Read, Edit, Write, MultiEdit, Bash, Grep, Glob, LS skills: - typescript-rules - testing-principles - - frontend-ai-guide + - ai-development-guide - implementation-approach - external-resource-context --- @@ -42,11 +42,11 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow Use the appropriate run command based on the `packageManager` field in package.json. ### Applying to Implementation -Apply loaded TypeScript / React / testing-principles / frontend-ai-guide rules during implementation. Create new components as function components; preserve working class components unless the accepted task requires migration, and use a class when implementing an Error Boundary directly. +Apply loaded typescript-rules, testing-principles, and ai-development-guide rules during implementation, and read `references/frontend.md` in the ai-development-guide skill before implementing; it holds the frontend criteria. Create new components as function components; preserve working class components unless the accepted task requires migration, and use a class when implementing an Error Boundary directly. When `docs/project-context/quality.yaml` exists, use it as implementation guidance. -Deliver the outcome with types satisfied at their boundaries, errors propagated or handled explicitly, and tests asserting the behavior the task delivers. Downstream quality assurance re-checks these properties. +Deliver the outcome with types satisfied at their boundaries, errors propagated or handled explicitly, and tests asserting the behavior the task delivers. ## Design Surface Check (Before Mandatory Judgment) @@ -92,7 +92,7 @@ Any YES is corrected in implementation when the value boundary can remain true. ## 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 value boundary. +**Policy**: Start implementation immediately (treat as approved). **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 @@ -127,7 +127,7 @@ Read the Operation Verification Methods from the task file or `observable_verifi **Unavailable**: continue implementation, run available checks, and return the missing component and affected verification in `runnableCheck.reason` with `result: "skipped"`; downstream quality assurance retains the final verification boundary When no method requires executable tests, proceed without requiring the test toolchain at this gate. -#### Pre-implementation Verification (Duplication Check — Pattern 5 from frontend-ai-guide) +#### Pre-implementation Verification (Duplication Check — Pattern 5 from ai-development-guide) Read relevant Design Doc sections accurately; investigate existing implementations (similar components/hooks in the same domain/responsibility); complete the Similar Component Reuse Decision and apply the remaining Mandatory Judgment Criteria above. #### Unimplemented Dependency Handling @@ -156,7 +156,7 @@ Apply coding-principles Reference Representativeness using the changed area and #### Implementation Flow **When the outcome is already satisfied**: Preserve the implementation and proceed to Operation Verification before reporting completion. -Implement the behaviors the task delivers and prove them under testing-principles and the task's Operation Verification Methods. Implement and run required integration/E2E tests in the earliest task where their declared proof boundary and dependencies are executable. Preserve generated skeleton paths and repository-required final checks. Apply the Responsibility Boundaries progress rule after verification. +Implement the behaviors the task delivers and prove them under testing-principles and the task's Operation Verification Methods. Before writing component, hook, or UI integration tests, read `references/frontend.md` in the testing-principles skill, and before writing browser E2E tests, `references/e2e.md`; they define the scope and ownership criteria for those tests. Implement and run required integration/E2E tests in the earliest task where their declared proof boundary and dependencies are executable. Preserve generated skeleton paths and repository-required final checks. Apply the Responsibility Boundaries progress rule after verification. #### Operation Verification - Execute the Operation Verification Methods in the execution instructions @@ -237,5 +237,3 @@ This gate runs immediately before producing the final JSON response. ☐ Every available Operation Verification Method ran; each unavailable or failed check has its exact result and affected proof in `runnableCheck` ☐ 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 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 03fbada6..ed5c24e2 100644 --- a/dev-workflows-frontend/agents/technical-designer-frontend.md +++ b/dev-workflows-frontend/agents/technical-designer-frontend.md @@ -4,7 +4,6 @@ description: Creates a scoped frontend ADR batch or one Design Doc from UI requi tools: Read, Write, Edit, MultiEdit, Glob, LS, Bash, WebSearch skills: - documentation-criteria - - frontend-ai-guide - coding-principles - testing-principles - ai-development-guide @@ -20,6 +19,10 @@ You create one complete frontend ADR batch or one frontend Design Doc per invoca Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. +## Preparation + +Before designing, read `references/frontend.md` in the ai-development-guide skill; it holds the frontend criteria for component, state, error-boundary, and impact decisions. + ## Inputs - **Reverse-engineer inputs**: Feature, Description, Primary Files, Public Interfaces, Dependencies, Unit Inventory, Parent PRD, and optional Backend Design Doc. These replace future-state convergence/analysis inputs in as-is mode. @@ -49,7 +52,7 @@ 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 orchestrator's Choice or Durability filter result, return the contradiction for orchestrator resolution. +Create one ADR per supplied decision point and finish the batch before returning. Follow `references/adr-template.md` in the documentation-criteria skill. 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. diff --git a/dev-workflows-frontend/agents/ui-spec-designer.md b/dev-workflows-frontend/agents/ui-spec-designer.md index 696587c0..f70a6501 100644 --- a/dev-workflows-frontend/agents/ui-spec-designer.md +++ b/dev-workflows-frontend/agents/ui-spec-designer.md @@ -5,7 +5,7 @@ tools: Read, Write, Edit, MultiEdit, Glob, LS, Bash skills: - documentation-criteria - typescript-rules - - frontend-ai-guide + - ai-development-guide - llm-friendly-context - external-resource-context --- @@ -16,6 +16,10 @@ You are a UI specification specialist AI assistant for creating UI Specification Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. +## Preparation + +Before decomposing screens into components, read `references/frontend.md` in the ai-development-guide skill; it holds the frontend criteria for component responsibility, state ownership, and reuse. + ## Main Responsibilities 1. Analyze the UI requirements and map them to screens, states, and components diff --git a/dev-workflows-frontend/agents/verifier.md b/dev-workflows-frontend/agents/verifier.md index ccccf51b..fbfcf658 100644 --- a/dev-workflows-frontend/agents/verifier.md +++ b/dev-workflows-frontend/agents/verifier.md @@ -13,6 +13,10 @@ You are an AI assistant specializing in investigation result verification. Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. +## Preparation + +Before verifying, read `references/frontend.md` in the ai-development-guide skill; it holds frontend criteria beyond the preloaded skills. + ## Input and Responsibility Boundaries - **Input**: Structured investigation results (JSON) or text format investigation results diff --git a/dev-workflows-frontend/skills/ai-development-guide/SKILL.md b/dev-workflows-frontend/skills/ai-development-guide/SKILL.md index b0fff492..70fbfe0a 100644 --- a/dev-workflows-frontend/skills/ai-development-guide/SKILL.md +++ b/dev-workflows-frontend/skills/ai-development-guide/SKILL.md @@ -1,6 +1,6 @@ --- name: ai-development-guide -description: Applies language-agnostic and backend technical decision criteria, anti-pattern detection, debugging, and quality gates. Use when reviewing general/backend implementation choices, code smells, failures, or implementation completeness. +description: Applies technical decision criteria, anti-pattern detection, debugging, and quality gates for backend and frontend code. Use when implementing, reviewing, or diagnosing code, code smells, failures, or implementation completeness. --- # AI Developer Guide - Technical Decision Criteria and Anti-pattern Collection @@ -249,3 +249,7 @@ Required by the requested change? No → Preserve unless the change proves it ob ``` **Principle**: Prefer clean implementation over patching broken code + +## References + +- [references/frontend.md](references/frontend.md): read when implementing, reviewing, fixing, or diagnosing frontend code diff --git a/dev-workflows-frontend/skills/ai-development-guide/references/frontend.md b/dev-workflows-frontend/skills/ai-development-guide/references/frontend.md new file mode 100644 index 00000000..4312ae3b --- /dev/null +++ b/dev-workflows-frontend/skills/ai-development-guide/references/frontend.md @@ -0,0 +1,37 @@ +# Frontend (React/TypeScript) Criteria + +Apply these with the SKILL.md criteria. Each entry adds what React and TypeScript code needs beyond them. + +## Anti-patterns + +- **Type assertions standing in for a guarantee**: `any` or `as` declares a type that no check or contract establishes. Back the declared type with a check or an existing contract at the boundary where that guarantee holds. +- **Pass-through prop chains that obscure state ownership**: Use composition, Context, or the project's state layer when intermediate components only forward values and a broader owner is clearer. Retain explicit props when they preserve local ownership and a broader owner would add coordination while responsibility remains local. +- **Components mixing independently changing responsibilities**: Split when rendering, state/data ownership, or reusable/testable behavior forms an independent responsibility. Retain a cohesive component when splitting would add avoidable prop/state synchronization. + +## Error Handling Boundaries + +- A rendering failure in a child component subtree, including a hook that throws during render, belongs to the project's Error Boundary. +- Event handlers, ordinary async callbacks, SSR, and hook/API operations outside rendering are handled at the owning event, hook, API, or server boundary through its error contract. +- Require design review when the same failure is caught at multiple component, hook, or API layers without one recovery owner, or when nested handlers obscure the visible UI state. + +## Reuse and Commonalization + +- Component patterns (form fields, cards, and similar) and custom hooks are commonalization candidates under the SKILL.md criteria. +- When judging whether similar functionality is a valid model, compare its props, lifecycle, state ownership, and design-system role along with repository usage. + +## Performance and Granularity + +- Prioritize readability unless the project's performance budget or a React DevTools Profiler comparison identifies a meaningful bottleneck in the affected interaction. Measure with React DevTools Profiler before optimizing. +- Design components that express UI patterns; overly detailed components and types reduce maintainability. Prefer composition over inheritance. + +## Impact Analysis + +- Discovery covers every reference to the changed component or hook, its imported functions, and its Props/State types. +- Understanding covers each caller's purpose, the component hierarchy, and the data flow Props → State → Event handlers → Callbacks. +- Concise notes are sufficient for an isolated component change with no shared contract, routing, state-ownership, or build/config impact. + +## Quality Check Troubleshooting + +- **Port already in use**: stop the stale dev, preview, or test process holding the port +- **Stale cache**: re-run with the project's fresh or clean-cache option +- **Dependency errors**: clean-reinstall dependencies diff --git a/dev-workflows-frontend/skills/documentation-criteria/references/task-template.md b/dev-workflows-frontend/skills/documentation-criteria/references/task-template.md index 9af61233..0953928d 100644 --- a/dev-workflows-frontend/skills/documentation-criteria/references/task-template.md +++ b/dev-workflows-frontend/skills/documentation-criteria/references/task-template.md @@ -19,7 +19,7 @@ Preserve every directly constraining Work Plan citation unchanged so the executo ## Target Files - [Implementation file or responsibility] -- [Test file, when required] +- [Test file the Work Plan fixes, such as a generated skeleton] ## Investigation Targets diff --git a/dev-workflows-frontend/skills/frontend-ai-guide/SKILL.md b/dev-workflows-frontend/skills/frontend-ai-guide/SKILL.md deleted file mode 100644 index c4138e25..00000000 --- a/dev-workflows-frontend/skills/frontend-ai-guide/SKILL.md +++ /dev/null @@ -1,177 +0,0 @@ ---- -name: frontend-ai-guide -description: Applies React/TypeScript-specific technical decision criteria, anti-pattern detection, debugging, and frontend quality gates. Use when reviewing components, hooks, browser behavior, or frontend implementation completeness. ---- - -# AI Developer Guide - Technical Decision Criteria and Anti-pattern Collection (Frontend) - -## 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 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 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 required value and proof at lower total complexity. - -## Technical Anti-patterns (Red Flag Patterns) - -Pause the affected decision and review the design when detecting the following patterns: - -### Code Quality Anti-patterns -1. **Duplicating one UI responsibility across independently maintained components** - Review whether the duplicated behavior or contract should have one owner -2. **Multiple responsibilities mixed in a single component** - Violates Single Responsibility Principle (SRP) -3. **Defining same content in multiple components** - Violates DRY principle -4. **Making changes without checking dependencies** - Potential for unexpected impacts -5. **Disabling code with comments** - Should use version control -6. **Error suppression** - Hiding problems creates technical debt -7. **Type assertions standing in for a guarantee** - Declaring a type established by neither a check nor an existing contract -8. **Pass-through prop chains that obscure state ownership** - Use composition, Context, or the project's state layer when intermediate components only forward values and a broader owner is clearer; retain explicit props when they preserve local ownership and broader state ownership would add coordination while responsibility remains local -9. **Components mixing independently changing responsibilities** - Split when rendering, state/data ownership, or reusable/testable behavior forms an independent responsibility; retain cohesive components when splitting would add avoidable prop/state synchronization - -### Design Anti-patterns -- **"Make it work for now" thinking** - Accumulation of technical debt -- **Patchwork implementation** - Unplanned additions to existing components -- **Symptomatic fixes** - Surface-level fixes that don't solve root causes -- **Unplanned large-scale changes** - Lack of incremental approach - -## Fallback Design Principles - -### Core Principle: Fail-Fast -Design philosophy that prioritizes improving primary code reliability over fallback implementations. - -### Criteria for Fallback Implementation -- **Fallback rule**: Implement a fallback when an accepted requirement, boundary contract, project policy, or Design Doc defines the degraded outcome and recovery owner -- **Layer Responsibilities**: - - Rendering failure in a child component subtree, including a hook that throws during render: Use the project's Error Boundary - - Event handlers, ordinary async callbacks, SSR, and hook/API operations outside rendering: Handle them at the owning event, hook, API, or server boundary using its error contract - -### Detection of Excessive Fallbacks -- Require design review when adding a catch that duplicates or fragments an existing recovery responsibility; retain it for a distinct failure mode with a documented recovery owner and visible UI outcome -- Require design review when the same failure is caught at multiple component/hook/API layers without one recovery owner, or when nested handlers obscure the visible UI state -- Identify the accepted recovery contract before implementing a fallback -- Make fallback activation observable through one existing UI, log, or metric channel at the boundary that owns diagnosis or recovery; add a new channel only when an operational requirement or project policy requires it - -## Criteria for Code Duplication - -Keep concrete implementations separate while their similarity is accidental or their UI ownership differs. Consolidate when repository evidence shows one shared interaction, validation rule, visual contract, or coordinated change responsibility. - -### Criteria for Commonalization - -**Cases for Commonalization** -- Business logic duplication -- Complex processing algorithms -- Component patterns (form fields, cards, etc.) -- Custom hooks -- Validation rules - -**Cases to Avoid Commonalization** -- Accidental matches (coincidentally same code) -- Possibility of evolving in different directions -- Significant readability decrease from commonalization -- Simple helpers in test code - -## Common Failure Patterns and Avoidance Methods - -### Pattern 1: Error Fix Chain -**Symptom**: Fixing one error causes new errors -**Cause**: Surface-level fixes without understanding root cause -**Avoidance**: Identify root cause with 5 Whys before fixing - -### Pattern 2: Circumventing Type Guarantees -**Symptom**: `any` or `as` declares a type that no check or contract establishes -**Cause**: Impulse to avoid type errors -**Avoidance**: Back the declared type with a check or an existing contract that guarantees it, at the boundary where that guarantee holds - -### Pattern 3: Implementation Without Sufficient Testing -**Symptom**: Many bugs after implementation -**Cause**: Accepted behavior left without a test that proves it -**Avoidance**: Prove each delivered behavior at the boundary where it is observed - -### Pattern 4: Building on Unverified Premises -**Symptom**: Dependent work fails, or workarounds accumulate, once an assumed premise proves false -**Cause**: Treating an assumed capability, behavior, or existing implementation as fact -**Avoidance**: When an unverified premise could invalidate the chosen approach, check it by the cheapest sufficient means before building dependent work on it. When results contradict the premise, reconsider the approach before patching its parts. Keep this reasoning in the active task; it needs no separate artifact. - -### Pattern 5: Insufficient Existing Code Investigation -**Symptom**: Duplicate implementations, architecture inconsistency, integration failures -**Cause**: Insufficient understanding of existing code before implementation -**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 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 - -## Quality Check Workflow - -Discover the repository's configured quality entry points and the categories they cover. Use the repository's declared package tooling and conventions and the categories below as the applicable evidence checklist. - -### Applicable Check Categories - -- **Lint/format** — the project's configured formatter and linter -- **Type check** — the project's configured type validation -- **Build** — the configured production or package build -- **Behavior checks** — the smallest configured tests that exercise the changed behavior, plus integration or E2E suites when the change crosses their boundary, a generated skeleton requires them, or the repository gate includes them - -Follow repository-declared command composition or ordering when it exists. Otherwise choose an order that respects command dependencies and provides useful feedback. Completion requires every applicable configured check to pass. - -### Troubleshooting -- **Port already in use** — stop the stale dev/preview/test process holding the port -- **Stale cache** — re-run with the project's fresh/clean-cache option -- **Dependency errors** — clean reinstall dependencies - -## Situations Requiring Technical Decisions - -### Timing of Abstraction -- Extract a shared abstraction after repository evidence establishes a shared UI responsibility and coordinated change pattern -- Be conscious of YAGNI, implement only currently needed features -- Prioritize current simplicity over future extensibility - -### Performance vs Readability -- Prioritize readability unless the project's performance budget or a React DevTools Profiler comparison identifies a meaningful bottleneck in the affected interaction -- Measure before optimizing with React DevTools Profiler -- Document reason with comments when optimizing - -### Granularity of Component/Type Definitions -- Overly detailed components/types reduce maintainability -- Design components that appropriately express UI patterns -- Use composition over inheritance - -## Implementation Completeness Assurance - -### Risk-Scaled Procedure for Impact Analysis - -**Completion Criteria**: Complete all 3 stages. Concise search/inspection notes are sufficient for an isolated component change with no shared contract, routing, state-ownership, or build/config impact; use the structured report for cross-component or high-risk changes. - -#### 1. Discovery -Search the repository for every reference to the changed component or hook, its imported functions, and its Props/State types. - -#### 2. Understanding -Read the discovered files needed to establish: -- Caller's purpose and context -- Component hierarchy -- Data flow: Props → State → Event handlers → Callbacks - -#### 3. Identification -For cross-component or high-risk changes, produce a structured impact report: -``` -## Impact Analysis -### Direct Impact: ComponentA, ComponentB (with reasons) -### Indirect Impact: FeatureX, PageY (with integration paths) -### Processing Flow: Props → Render → Events → Callbacks -``` - -Proceed when the accepted scope, consumers, state flow, required adjacent changes, and applicable checks are identified. - -### Unused Code Deletion Rule - -When the requested change makes a component, hook, utility, document, or configuration entry obsolete, delete it after checking its consumers and generated/operational use. Preserve and report uncertain or out-of-scope cleanup, and keep unrelated dormant code outside the implementation scope. - -### Existing Code Deletion Decision Flow - -``` -Required by the requested change? No → Preserve unless the change proves it obsolete - Yes → Working and compatible? Yes → Fix/extend - No → Repair or replace with migration/rollback evidence -``` diff --git a/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md b/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md index c6e4651d..f44aa004 100644 --- a/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md @@ -91,7 +91,7 @@ Present the adjustment context to the user for review. ### Step 5: Adjustment + Verification (parent session) -Execute Skill: frontend-ai-guide before planning or applying adjustment edits. +Execute Skill: ai-development-guide and read its `references/frontend.md` before planning or applying adjustment edits. 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. diff --git a/dev-workflows-frontend/skills/recipe-front-build/SKILL.md b/dev-workflows-frontend/skills/recipe-front-build/SKILL.md index 3eb5ad9f..628b61f3 100644 --- a/dev-workflows-frontend/skills/recipe-front-build/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-front-build/SKILL.md @@ -109,8 +109,8 @@ Before invoking post-implementation reviewers, apply subagents-orchestration-gui Resolve the Work Plan's readable Design Doc; missing input blocks review. -Emit these Agent calls in one assistant message, then await both: -- code-reviewer (subagent_type: "dev-workflows-frontend:code-reviewer") → review the completed implementation with the resolved `governingDocuments`, the actual files changed by completed tasks as `implementationFiles`, and the Work Plan path +Invoke the code-reviewer calls for the subagents-orchestration-guide Post-Implementation Review Units and one security-reviewer call, then await all: +- code-reviewer (subagent_type: "dev-workflows-frontend:code-reviewer") → one call per review unit with the resolved `governingDocuments`, the unit's changed files as `implementationFiles`, the unit's tasks as task scope, and the Work Plan path - security-reviewer (subagent_type: "dev-workflows-frontend:security-reviewer") → review the completed implementation against the same `governingDocuments` Apply subagents-orchestration-guide's Post-Implementation Review status-routing and fix/re-run rules. Present the unified report; proceed to Final Cleanup after the complete review set reaches Review Resolution convergence. diff --git a/dev-workflows-frontend/skills/recipe-front-design/SKILL.md b/dev-workflows-frontend/skills/recipe-front-design/SKILL.md index 24205264..87632225 100644 --- a/dev-workflows-frontend/skills/recipe-front-design/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-front-design/SKILL.md @@ -83,7 +83,7 @@ external_resource_refs: [selected references or []] Execute Skill: requirement-convergence. Build and judge the convergence record from the governing requirement source, repository analysis, and applicable UI analysis. -Judge all four convergence fields. Assign `cost` from Step 2 structural evidence and record its unknowns; run the hearing only for fields below `ready`. +Judge all four convergence fields by the rules in `references/criteria.md` of the requirement-convergence skill. Assign `cost` from Step 2 structural evidence and record its unknowns; run the hearing only for fields below `ready`. 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. diff --git a/dev-workflows-frontend/skills/recipe-front-review/SKILL.md b/dev-workflows-frontend/skills/recipe-front-review/SKILL.md index 6fc502c2..e363bab3 100644 --- a/dev-workflows-frontend/skills/recipe-front-review/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-front-review/SKILL.md @@ -76,9 +76,6 @@ Then present the adjudicated result to the user. Group `apply` findings by propo ``` Implementation Review: [verdict from code-reviewer] - Acceptance Criteria: - - [fulfilled] [item]: [evidence] - - [unfulfilled] [item] -> [corresponding finding ID under Required Corrections] Required Corrections: - [id] [category] [location]: [description] — [basis and effect] [recommended: c | d | d and c] Limitations: diff --git a/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md index 38f28531..887356c6 100644 --- a/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md @@ -196,6 +196,10 @@ graph TD For Small, execute one direct-scope 4-step cycle. Complete after `pass`, or retry a retained `verification_incomplete` result once and complete with its exact repeated limitation. Small has no task decomposition, document-dependent post-implementation review, or task-file cleanup. +### Post-Implementation Review Units (Medium/Large) + +Review a Medium change with one code-reviewer. A Large change is more than one code-reviewer can read in full; partition it into units of Work Plan tasks. A unit holds a consuming task (one delivering a screen, route, command, or job) together with the tasks it depends on through `Depends on`, so a contract's producer, its consumer, and every test proving their behavior are reviewed together; tasks that several units depend on form one shared unit. Each completed task belongs to one unit, whose `implementationFiles` are the files changed by its tasks' commits. Run at most 3 reviewer calls concurrently. security-reviewer reviews the complete change once. The unit reviewer that reported a finding owns it under the fix-cycle and re-run rules. + ### Post-Implementation Review Status Routing (Medium/Large) | Reviewer | Complete: empty finding set | Enter Review Resolution | Blocked | diff --git a/dev-workflows-frontend/skills/testing-principles/SKILL.md b/dev-workflows-frontend/skills/testing-principles/SKILL.md index 72579f85..afafb806 100644 --- a/dev-workflows-frontend/skills/testing-principles/SKILL.md +++ b/dev-workflows-frontend/skills/testing-principles/SKILL.md @@ -1,6 +1,6 @@ --- name: testing-principles -description: Language-agnostic testing principles for choosing which tests a change needs, test quality, and proof ownership, with frontend and browser E2E implementation references. Use when writing tests, deciding test scope, or reviewing test quality. +description: Language-agnostic testing principles for choosing which tests a change needs, test quality, and proof ownership, including frontend and browser E2E tests. Use when writing tests, deciding test scope, or reviewing test quality. --- # Language-Agnostic Testing Principles diff --git a/dev-workflows-fullstack/agents/acceptance-test-generator.md b/dev-workflows-fullstack/agents/acceptance-test-generator.md index 616b6920..5903323f 100644 --- a/dev-workflows-fullstack/agents/acceptance-test-generator.md +++ b/dev-workflows-fullstack/agents/acceptance-test-generator.md @@ -21,7 +21,7 @@ Accept equivalent labels and concise prose with the same meaning. Follow linked ## Selection -1. Read the accepted criteria, Design Doc verification requirements, and applicable UI Spec interactions, states and transitions. Apply testing-principles to establish the required proof boundary, then inspect actual existing test assertions and setup for coverage. +1. Read the accepted criteria, Design Doc verification requirements, and applicable UI Spec interactions, states and transitions. Apply testing-principles to establish the required proof boundary, reading its `references/frontend.md` for UI integration proof and `references/e2e.md` for browser E2E proof, then inspect actual existing test assertions and setup for coverage. 2. For uncovered integration/E2E proof, write the smallest sufficient skeleton set. Record the production entry/composition to traverse, real dependencies and allowed substitutes in the existing proof obligation. Before implementation exists, derive that obligation from the governing design; a test that could be written is planned proof, not existing coverage. 3. Explain each empty lane from sufficient existing proof, a selected skeleton in another lane, or why the accepted behavior requires no proof at that lane's boundary. Return an exact limitation for a required but unavailable boundary. diff --git a/dev-workflows-fullstack/agents/code-reviewer.md b/dev-workflows-fullstack/agents/code-reviewer.md index e8d55424..7b801887 100644 --- a/dev-workflows-fullstack/agents/code-reviewer.md +++ b/dev-workflows-fullstack/agents/code-reviewer.md @@ -1,6 +1,6 @@ --- name: code-reviewer -description: Reviews completed implementation for governing-source compliance, scope economy, repository quality policy, and material code correctness. Use after implementation or when review/implementation check/compliance is requested. +description: Reviews completed implementation for material code correctness, unnecessary mechanisms and tests, governing-source compliance, and repository quality policy. Use after implementation or when review/implementation check/compliance is requested. tools: Read, Grep, Glob, LS, Bash skills: - ai-development-guide @@ -14,11 +14,7 @@ Operate in an independent context and continue until the review result is comple The review aims at the required outcome with the least justified complexity: every unnecessary mechanism or test adds implementation, test, and maintenance obligations. -Implementers work one task at a time, and running tests and quality checks belongs to the workflow's quality gate, not to this review. This independent context exists so one reviewer can read the whole change in detail: reading the changed code and tests is the verification only this review adds, and a passing run shows only that the tests agree with the code, not that either is right. Map the whole change; the Findings Boundary keeps what you report narrow. - -## Execution Gate - -Before acting, map the preloaded skills to concrete rules for this review. Advance only when the current step's required evidence is present. Before returning, verify the result against the completion check and output contract. +Verify by reading the changed code and tests. Running tests and quality checks is outside this review; a passing run shows only that the tests agree with the code, not that either is right. ## Inputs @@ -27,23 +23,31 @@ Before acting, map the preloaded skills to concrete rules for this review. Advan - **Work Plan and task scope**: Use when supplied to identify approved execution and review boundaries - **prior_feedback** (optional): Array of `{ id, disposition, reason?, evidence }` from the preceding Review Resolution decision -Read `docs/project-context/quality.yaml` when it exists. It adds repository-specific review dimensions; its absence leaves the built-in review boundary unchanged. Verify input paths and inspect only references that can change an in-scope finding or limitation. +Read `docs/project-context/quality.yaml` when it exists. It adds repository-specific review dimensions; its absence leaves the built-in review boundary unchanged. Verify input paths, and inspect only the documents they link to that can change an in-scope finding or limitation. + +## Preparation + +Before reviewing, read these files; they hold review criteria beyond the preloaded skills: + +- `references/frontend.md` in the testing-principles skill +- `references/frontend.md` in the ai-development-guide skill +- `references/e2e.md` in the testing-principles skill ## Initial Review Extract the approved outcome, applicable acceptance criteria, changed interfaces and contracts, protected behavior, non-goals, required design decisions, and verification expectations. -Map every applicable acceptance criterion and material surface in `implementationFiles` to its governing contract, applicable quality dimension, direct implementation or test evidence, and any candidate problem. Each changed test is itself a surface: map it to the claim it proves and the boundary it proves it at, because tests looked up only as evidence for criteria never reveal a claim proven twice. Consider a failure that could pass a shallow happy-path check when it can change the judgment. Review the complete map in this order: +Judge the material surfaces in `implementationFiles` against these criteria: -1. **Outcome and contracts**: Confirm each applicable criterion from the changed code and tests at file:line and preserve public, serialized, persisted, user-visible, error, identifier, and producer-consumer contracts. -2. **Scope economy**: For each material mechanism, abstraction, dependency, state, defensive control, or test added by the change, identify the required result it serves (an approved requirement, repository rule, observed contract or failure, or evidence-backed material risk in the reachable changed path) and whether omitting it, narrowing it, or reusing existing code or tests would serve that result; an addition is worth its lifecycle cost only when none of these would. A Design Doc that selected the mechanism records the current means, not that justification. For a test, judge this by the testing-principles Test Selection rules. When narrowing or removing an addition preserves the outcome and contracts, use that reduction as the correction. -3. **Required design and proof**: Preserve the governing source's responsibility boundaries. Require proof at the observable boundary claimed by the governing source or task. -4. **Code quality**: Apply the preloaded skills to concrete changed-path correctness, contract safety, repository-local patterns, error behavior, and proof quality. -5. **Repository quality policy**: Apply each `docs/project-context/quality.yaml` dimension whose `applies_when` condition matches the change. Its `pass` condition and cited `evidence` define the accepted state. +- **Outcome and contracts**: The changed code and tests deliver each applicable criterion at file:line and preserve public, serialized, persisted, user-visible, error, identifier, and producer-consumer contracts. +- **Scope economy**: For each material mechanism, abstraction, dependency, state, defensive control, or test added by the change, identify the required result it serves (an approved requirement, repository rule, observed contract or failure, or evidence-backed material risk in the reachable changed path) and whether omitting it, narrowing it, or reusing existing code or tests would serve that result; an addition is worth its lifecycle cost only when none of these would. A Design Doc that selected the mechanism records the current means, not that justification. For a test, judge this by the testing-principles Test Selection rules. +- **Required design and proof**: Preserve the governing source's responsibility boundaries. Require proof at the observable boundary claimed by the governing source or task. Each changed test is itself a surface: judge the claim it proves and the boundary it proves it at, because tests looked up only as evidence for criteria never reveal a claim proven twice. +- **Code quality**: Apply the preloaded skills to concrete changed-path correctness, contract safety, repository-local patterns, error behavior, and proof quality. +- **Repository quality policy**: Apply each `docs/project-context/quality.yaml` dimension whose `applies_when` condition matches the change. Its `pass` condition and cited `evidence` define the accepted state. -Inspect an adjacent case when repository evidence shows that it shares the changed cause, contract, or state boundary and leaving it unchanged would keep the same in-scope failure active. Require additional internal-detail or edge-case tests only when a requirement, preserved behavior, observed defect class, applicable quality dimension, or evidence-backed material risk makes them part of the current proof. +Consider a failure that could pass a shallow happy-path check when it can change the judgment. Inspect an adjacent case when repository evidence shows that it shares the changed cause, contract, or state boundary and leaving it unchanged would keep the same in-scope failure active. Require additional internal-detail or edge-case tests only when a requirement, preserved behavior, observed defect class, applicable quality dimension, or evidence-backed material risk makes them part of the current proof. -Continue through every mapped item after observing a candidate problem, and choose the verdict only after the complete map is resolved. Verify candidate problems against supporting and contradicting evidence, then consolidate candidates only when one correction resolves the same cause. +Verify candidate problems against supporting and contradicting evidence, consolidate candidates only when one correction resolves the same cause, and choose the verdict after the review is complete. ## Correction Re-review @@ -71,7 +75,7 @@ Emit a finding only when correction is required because the implementation is in Represent every unfulfilled acceptance criterion with one corresponding finding so Review Resolution has an actionable correction boundary. -Express `suggestion` as the smallest observable accepted state after correction. Name an implementation mechanism only when the governing source requires it. For `scope_excess`, prefer removal or narrowing that preserves the approved outcome and contracts. +Express `suggestion` as the smallest observable accepted state after correction. Name an implementation mechanism only when the governing source requires it. Use `limitations` only when unavailable evidence prevents judging an applicable criterion, contract, material addition, or quality dimension. State the blocked judgment and its effect. @@ -82,7 +86,7 @@ The final message is one JSON object. During execution, progress messages may us Initial review: ```json -{"verdict":"pass|needs-improvement|needs-redesign|blocked","acceptanceCriteria":[{"item":"governing criterion identifier or text","status":"fulfilled|unfulfilled","evidence":["file:line"],"gap":"material gap or null"}],"findings":[{"id":"F001","category":"dd_violation|scope_excess|reliability|coverage_gap|quality_rule|adjacent_residual","location":"file:line","description":"specific required-correction issue","basis":"governing source, quality dimension, or observed fact","effect":"observable consequence","suggestion":"smallest sufficient accepted state"}],"limitations":["unverified judgment and effect"]} +{"verdict":"pass|needs-improvement|needs-redesign|blocked","findings":[{"id":"F001","category":"dd_violation|scope_excess|reliability|coverage_gap|quality_rule|adjacent_residual","location":"file:line","description":"specific required-correction issue","basis":"governing source, quality dimension, or observed fact","effect":"observable consequence","suggestion":"smallest sufficient accepted state"}],"limitations":["unverified judgment and effect"]} ``` Correction re-review: @@ -100,10 +104,10 @@ Correction re-review: ## Completion Check -- [ ] The initial review resolved every applicable criterion and material changed surface before choosing its verdict, or the correction re-review reconciled every received item once +- [ ] The initial review chose its verdict after judging every material surface in `implementationFiles`, or the correction re-review reconciled every received item once - [ ] Changed contracts and required proof were checked against the code and tests at file:line +- [ ] Frontend changes were judged against `references/frontend.md`, and browser E2E tests against `references/e2e.md` - [ ] Every unfulfilled acceptance criterion has one corresponding finding -- [ ] Material additions were necessary and worth their cost over subtraction or reuse, or reported with removal or narrowing as the correction - [ ] Every emitted finding requires correction under the Findings Boundary - [ ] Applicable repository quality dimensions were checked against their cited evidence - [ ] Review breadth and proposed corrections remain within the approved outcome diff --git a/dev-workflows-fullstack/agents/integration-test-reviewer.md b/dev-workflows-fullstack/agents/integration-test-reviewer.md index 91a198ff..bca200e4 100644 --- a/dev-workflows-fullstack/agents/integration-test-reviewer.md +++ b/dev-workflows-fullstack/agents/integration-test-reviewer.md @@ -15,6 +15,13 @@ Operates in an independent context, executing autonomously until task completion Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. +## Preparation + +Before reviewing, read these files; they hold review criteria beyond the preloaded skills: + +- `references/frontend.md` in the testing-principles skill +- `references/e2e.md` in the testing-principles skill + ## Input Parameters - **changedTestFiles**: Non-empty list of integration or E2E test files changed by the task diff --git a/dev-workflows-fullstack/agents/investigator.md b/dev-workflows-fullstack/agents/investigator.md index 38169c72..162e6861 100644 --- a/dev-workflows-fullstack/agents/investigator.md +++ b/dev-workflows-fullstack/agents/investigator.md @@ -13,6 +13,10 @@ You are an AI assistant specializing in problem investigation. Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. +## Preparation + +Before investigating, read `references/frontend.md` in the ai-development-guide skill; it holds frontend criteria beyond the preloaded skills. + ## Input and Responsibility Boundaries - **Input**: Accepts both text and JSON formats. For JSON, use `problemSummary` diff --git a/dev-workflows-fullstack/agents/quality-fixer-frontend.md b/dev-workflows-fullstack/agents/quality-fixer-frontend.md index 5b323c06..1d119f14 100644 --- a/dev-workflows-fullstack/agents/quality-fixer-frontend.md +++ b/dev-workflows-fullstack/agents/quality-fixer-frontend.md @@ -5,7 +5,7 @@ tools: Bash, Read, Edit, MultiEdit, Grep, Glob, LS skills: - typescript-rules - testing-principles - - frontend-ai-guide + - ai-development-guide - external-resource-context --- @@ -71,13 +71,13 @@ Run the task file's Operation Verification Methods, or the direct scope's `obser **External Resources Consultation**: When a quality check references a resource recorded in `docs/project-context/external-resources.md` or in a UI Spec / Design Doc / Work Plan "External Resources Used" entry, consult it per the external-resource-context skill (Reference Protocol). When the resource is referenced but unreachable, return `verification_incomplete` with `reason: "Execution prerequisites not met"` and populate `missingPrerequisites` after completing unaffected checks. ### Step 3: Execute Quality Checks -Run every applicable check discovered in Step 2. Use repository-declared command composition or ordering when present; otherwise choose an order that respects command dependencies and provides useful feedback. Apply frontend-ai-guide skill "Quality Check Workflow" categories and require every applicable check to pass. +Run every applicable check discovered in Step 2. Use repository-declared command composition or ordering when present; otherwise choose an order that respects command dependencies and provides useful feedback. Apply ai-development-guide skill "Quality Check Workflow" categories and require every applicable check to pass. - Substance check (applies only when a test run is cited as evidence for the task's intended behavior): the run counts as `passed` only when at least one executed assertion ran against that behavior. Record test-runner reports of 0 tests matched, skipped tests, placeholder/TODO-only bodies, or assertions that always pass regardless of behavior (e.g., `expect(true).toBe(true)`, `expect(arr.length).toBeGreaterThanOrEqual(0)`) as non-substantive. Tests verifying intentional absence (e.g., `expect(screen.queryAllByRole(...)).toHaveLength(0)`, `expect(value).toBeNull()`) are substantive when absence is the task's expectation. To recover: remove `skip`/`only` markers, widen test selectors, or run additional related test files; if substance remains unavailable, return `verification_incomplete`. Non-test checks (lint, format, build, typecheck) are not subject to this rule. - For a probe that establishes a test or command prerequisite, verify the consumer's exact postcondition through the same boundary; command/import success or object existence is setup evidence. - Reuse mutation evidence after confirming complete fields, matching revision/files, restoration, and proof of the claimed behavior; otherwise replace it with fresh evidence. ### Step 4: Fix Errors -Apply fixes per typescript-rules and testing-principles skills. +Apply fixes per typescript-rules, testing-principles, and ai-development-guide skills, reading `references/frontend.md` in the ai-development-guide skill for frontend criteria and check troubleshooting. For a failing component, hook, or UI integration test, read `references/frontend.md` in the testing-principles skill, and for a failing browser E2E test `references/e2e.md`; they define whether the test or the implementation is wrong. ### Step 5: Repeat Until Checks Pass - In-scope error found → Fix → Re-run checks diff --git a/dev-workflows-fullstack/agents/quality-fixer.md b/dev-workflows-fullstack/agents/quality-fixer.md index cf730b03..c065367d 100644 --- a/dev-workflows-fullstack/agents/quality-fixer.md +++ b/dev-workflows-fullstack/agents/quality-fixer.md @@ -71,7 +71,7 @@ Run every applicable check discovered in Step 2. Use repository-declared command - Reuse mutation evidence after confirming complete fields, matching revision/files, restoration, and proof of the claimed behavior; otherwise replace it with fresh evidence. ### Step 4: Fix Errors -Apply fixes per coding-principles and testing-principles skills. +Apply fixes per coding-principles and testing-principles skills. For a failing browser E2E test, read `references/e2e.md` in the testing-principles skill; it defines the lane, harness, and assertion rules the test must follow. ### Step 5: Repeat Until Checks Pass - In-scope error found → Fix → Re-run checks diff --git a/dev-workflows-fullstack/agents/solver.md b/dev-workflows-fullstack/agents/solver.md index fe52b5f3..a0b74997 100644 --- a/dev-workflows-fullstack/agents/solver.md +++ b/dev-workflows-fullstack/agents/solver.md @@ -14,6 +14,10 @@ You are an AI assistant specializing in solution derivation. Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. +## Preparation + +Before deriving solutions, read `references/frontend.md` in the ai-development-guide skill; it holds frontend criteria beyond the preloaded skills. + ## Input and Responsibility Boundaries - **Input**: A verified conclusion with `coverageDisposition: closed` diff --git a/dev-workflows-fullstack/agents/task-decomposer.md b/dev-workflows-fullstack/agents/task-decomposer.md index a461e786..e4c0e9d7 100644 --- a/dev-workflows-fullstack/agents/task-decomposer.md +++ b/dev-workflows-fullstack/agents/task-decomposer.md @@ -48,7 +48,7 @@ For each task: 1. Copy every governing-source citation unchanged into `Governing Sources`. 2. Add those cited sections, the target implementation, and one representative adjacent test to `Investigation Targets`. -3. Select concrete Target Files when repository evidence makes them known. +3. Select concrete Target Files when repository evidence makes them known. List a test file only when the Work Plan fixes it; the executor selects other tests under testing-principles. 4. When an exact file is not yet knowable, name the smallest owner directory or module and the search criterion the executor can resolve. The task file points to authoritative governing content instead of reproducing it. The executor reads every Investigation Target before implementation. diff --git a/dev-workflows-fullstack/agents/task-executor-frontend.md b/dev-workflows-fullstack/agents/task-executor-frontend.md index 91edfc60..6cf85ac8 100644 --- a/dev-workflows-fullstack/agents/task-executor-frontend.md +++ b/dev-workflows-fullstack/agents/task-executor-frontend.md @@ -5,7 +5,7 @@ tools: Read, Edit, Write, MultiEdit, Bash, Grep, Glob, LS skills: - typescript-rules - testing-principles - - frontend-ai-guide + - ai-development-guide - implementation-approach - external-resource-context --- @@ -42,11 +42,11 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow Use the appropriate run command based on the `packageManager` field in package.json. ### Applying to Implementation -Apply loaded TypeScript / React / testing-principles / frontend-ai-guide rules during implementation. Create new components as function components; preserve working class components unless the accepted task requires migration, and use a class when implementing an Error Boundary directly. +Apply loaded typescript-rules, testing-principles, and ai-development-guide rules during implementation, and read `references/frontend.md` in the ai-development-guide skill before implementing; it holds the frontend criteria. Create new components as function components; preserve working class components unless the accepted task requires migration, and use a class when implementing an Error Boundary directly. When `docs/project-context/quality.yaml` exists, use it as implementation guidance. -Deliver the outcome with types satisfied at their boundaries, errors propagated or handled explicitly, and tests asserting the behavior the task delivers. Downstream quality assurance re-checks these properties. +Deliver the outcome with types satisfied at their boundaries, errors propagated or handled explicitly, and tests asserting the behavior the task delivers. ## Design Surface Check (Before Mandatory Judgment) @@ -92,7 +92,7 @@ Any YES is corrected in implementation when the value boundary can remain true. ## 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 value boundary. +**Policy**: Start implementation immediately (treat as approved). **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 @@ -127,7 +127,7 @@ Read the Operation Verification Methods from the task file or `observable_verifi **Unavailable**: continue implementation, run available checks, and return the missing component and affected verification in `runnableCheck.reason` with `result: "skipped"`; downstream quality assurance retains the final verification boundary When no method requires executable tests, proceed without requiring the test toolchain at this gate. -#### Pre-implementation Verification (Duplication Check — Pattern 5 from frontend-ai-guide) +#### Pre-implementation Verification (Duplication Check — Pattern 5 from ai-development-guide) Read relevant Design Doc sections accurately; investigate existing implementations (similar components/hooks in the same domain/responsibility); complete the Similar Component Reuse Decision and apply the remaining Mandatory Judgment Criteria above. #### Unimplemented Dependency Handling @@ -156,7 +156,7 @@ Apply coding-principles Reference Representativeness using the changed area and #### Implementation Flow **When the outcome is already satisfied**: Preserve the implementation and proceed to Operation Verification before reporting completion. -Implement the behaviors the task delivers and prove them under testing-principles and the task's Operation Verification Methods. Implement and run required integration/E2E tests in the earliest task where their declared proof boundary and dependencies are executable. Preserve generated skeleton paths and repository-required final checks. Apply the Responsibility Boundaries progress rule after verification. +Implement the behaviors the task delivers and prove them under testing-principles and the task's Operation Verification Methods. Before writing component, hook, or UI integration tests, read `references/frontend.md` in the testing-principles skill, and before writing browser E2E tests, `references/e2e.md`; they define the scope and ownership criteria for those tests. Implement and run required integration/E2E tests in the earliest task where their declared proof boundary and dependencies are executable. Preserve generated skeleton paths and repository-required final checks. Apply the Responsibility Boundaries progress rule after verification. #### Operation Verification - Execute the Operation Verification Methods in the execution instructions @@ -237,5 +237,3 @@ This gate runs immediately before producing the final JSON response. ☐ Every available Operation Verification Method ran; each unavailable or failed check has its exact result and affected proof in `runnableCheck` ☐ 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 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 be4a9318..fd696e45 100644 --- a/dev-workflows-fullstack/agents/task-executor.md +++ b/dev-workflows-fullstack/agents/task-executor.md @@ -41,7 +41,7 @@ Apply loaded architecture/coding/testing rules during implementation. Follow tas When `docs/project-context/quality.yaml` exists, use it as implementation guidance. -Deliver the outcome with contracts satisfied at their boundaries, errors propagated or handled explicitly, and tests asserting the behavior the task delivers. Downstream quality assurance re-checks these properties. +Deliver the outcome with contracts satisfied at their boundaries, errors propagated or handled explicitly, and tests asserting the behavior the task delivers. ## Design Surface Check (Before Mandatory Judgment) @@ -87,7 +87,7 @@ Any YES is corrected in implementation when the value boundary can remain true. ## 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 value boundary. +**Policy**: Start implementation immediately (treat as approved). **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 @@ -152,7 +152,7 @@ Apply coding-principles Reference Representativeness using the changed area and **When the outcome is already satisfied**: Preserve the implementation and proceed to Operation Verification before reporting completion. -Implement the behaviors the task delivers and prove them under testing-principles and the task's Operation Verification Methods. Implement and run required integration/E2E tests in the earliest task where their declared proof boundary and dependencies are executable. Preserve generated skeleton paths and repository-required final checks. Apply the Responsibility Boundaries progress rule after verification. +Implement the behaviors the task delivers and prove them under testing-principles and the task's Operation Verification Methods. Before writing browser E2E tests, read `references/e2e.md` in the testing-principles skill; it defines the scope and ownership criteria for those tests. Implement and run required integration/E2E tests in the earliest task where their declared proof boundary and dependencies are executable. Preserve generated skeleton paths and repository-required final checks. Apply the Responsibility Boundaries progress rule after verification. #### Operation Verification - Execute the Operation Verification Methods in the execution instructions @@ -233,5 +233,3 @@ This gate runs immediately before producing the final JSON response. ☐ Every available Operation Verification Method ran; each unavailable or failed check has its exact result and affected proof in `runnableCheck` ☐ 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 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 03fbada6..ed5c24e2 100644 --- a/dev-workflows-fullstack/agents/technical-designer-frontend.md +++ b/dev-workflows-fullstack/agents/technical-designer-frontend.md @@ -4,7 +4,6 @@ description: Creates a scoped frontend ADR batch or one Design Doc from UI requi tools: Read, Write, Edit, MultiEdit, Glob, LS, Bash, WebSearch skills: - documentation-criteria - - frontend-ai-guide - coding-principles - testing-principles - ai-development-guide @@ -20,6 +19,10 @@ You create one complete frontend ADR batch or one frontend Design Doc per invoca Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. +## Preparation + +Before designing, read `references/frontend.md` in the ai-development-guide skill; it holds the frontend criteria for component, state, error-boundary, and impact decisions. + ## Inputs - **Reverse-engineer inputs**: Feature, Description, Primary Files, Public Interfaces, Dependencies, Unit Inventory, Parent PRD, and optional Backend Design Doc. These replace future-state convergence/analysis inputs in as-is mode. @@ -49,7 +52,7 @@ 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 orchestrator's Choice or Durability filter result, return the contradiction for orchestrator resolution. +Create one ADR per supplied decision point and finish the batch before returning. Follow `references/adr-template.md` in the documentation-criteria skill. 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. diff --git a/dev-workflows-fullstack/agents/technical-designer.md b/dev-workflows-fullstack/agents/technical-designer.md index 483f13f1..b01a6322 100644 --- a/dev-workflows-fullstack/agents/technical-designer.md +++ b/dev-workflows-fullstack/agents/technical-designer.md @@ -54,7 +54,7 @@ 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 orchestrator's Choice or Durability filter result, return the contradiction for orchestrator resolution. +Create one ADR per supplied decision point and finish the complete batch before returning. Follow `references/adr-template.md` in the documentation-criteria skill. 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. diff --git a/dev-workflows-fullstack/agents/ui-spec-designer.md b/dev-workflows-fullstack/agents/ui-spec-designer.md index 696587c0..f70a6501 100644 --- a/dev-workflows-fullstack/agents/ui-spec-designer.md +++ b/dev-workflows-fullstack/agents/ui-spec-designer.md @@ -5,7 +5,7 @@ tools: Read, Write, Edit, MultiEdit, Glob, LS, Bash skills: - documentation-criteria - typescript-rules - - frontend-ai-guide + - ai-development-guide - llm-friendly-context - external-resource-context --- @@ -16,6 +16,10 @@ You are a UI specification specialist AI assistant for creating UI Specification Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. +## Preparation + +Before decomposing screens into components, read `references/frontend.md` in the ai-development-guide skill; it holds the frontend criteria for component responsibility, state ownership, and reuse. + ## Main Responsibilities 1. Analyze the UI requirements and map them to screens, states, and components diff --git a/dev-workflows-fullstack/agents/verifier.md b/dev-workflows-fullstack/agents/verifier.md index ccccf51b..fbfcf658 100644 --- a/dev-workflows-fullstack/agents/verifier.md +++ b/dev-workflows-fullstack/agents/verifier.md @@ -13,6 +13,10 @@ You are an AI assistant specializing in investigation result verification. Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. +## Preparation + +Before verifying, read `references/frontend.md` in the ai-development-guide skill; it holds frontend criteria beyond the preloaded skills. + ## Input and Responsibility Boundaries - **Input**: Structured investigation results (JSON) or text format investigation results diff --git a/dev-workflows-fullstack/skills/ai-development-guide/SKILL.md b/dev-workflows-fullstack/skills/ai-development-guide/SKILL.md index b0fff492..70fbfe0a 100644 --- a/dev-workflows-fullstack/skills/ai-development-guide/SKILL.md +++ b/dev-workflows-fullstack/skills/ai-development-guide/SKILL.md @@ -1,6 +1,6 @@ --- name: ai-development-guide -description: Applies language-agnostic and backend technical decision criteria, anti-pattern detection, debugging, and quality gates. Use when reviewing general/backend implementation choices, code smells, failures, or implementation completeness. +description: Applies technical decision criteria, anti-pattern detection, debugging, and quality gates for backend and frontend code. Use when implementing, reviewing, or diagnosing code, code smells, failures, or implementation completeness. --- # AI Developer Guide - Technical Decision Criteria and Anti-pattern Collection @@ -249,3 +249,7 @@ Required by the requested change? No → Preserve unless the change proves it ob ``` **Principle**: Prefer clean implementation over patching broken code + +## References + +- [references/frontend.md](references/frontend.md): read when implementing, reviewing, fixing, or diagnosing frontend code diff --git a/dev-workflows-fullstack/skills/ai-development-guide/references/frontend.md b/dev-workflows-fullstack/skills/ai-development-guide/references/frontend.md new file mode 100644 index 00000000..4312ae3b --- /dev/null +++ b/dev-workflows-fullstack/skills/ai-development-guide/references/frontend.md @@ -0,0 +1,37 @@ +# Frontend (React/TypeScript) Criteria + +Apply these with the SKILL.md criteria. Each entry adds what React and TypeScript code needs beyond them. + +## Anti-patterns + +- **Type assertions standing in for a guarantee**: `any` or `as` declares a type that no check or contract establishes. Back the declared type with a check or an existing contract at the boundary where that guarantee holds. +- **Pass-through prop chains that obscure state ownership**: Use composition, Context, or the project's state layer when intermediate components only forward values and a broader owner is clearer. Retain explicit props when they preserve local ownership and a broader owner would add coordination while responsibility remains local. +- **Components mixing independently changing responsibilities**: Split when rendering, state/data ownership, or reusable/testable behavior forms an independent responsibility. Retain a cohesive component when splitting would add avoidable prop/state synchronization. + +## Error Handling Boundaries + +- A rendering failure in a child component subtree, including a hook that throws during render, belongs to the project's Error Boundary. +- Event handlers, ordinary async callbacks, SSR, and hook/API operations outside rendering are handled at the owning event, hook, API, or server boundary through its error contract. +- Require design review when the same failure is caught at multiple component, hook, or API layers without one recovery owner, or when nested handlers obscure the visible UI state. + +## Reuse and Commonalization + +- Component patterns (form fields, cards, and similar) and custom hooks are commonalization candidates under the SKILL.md criteria. +- When judging whether similar functionality is a valid model, compare its props, lifecycle, state ownership, and design-system role along with repository usage. + +## Performance and Granularity + +- Prioritize readability unless the project's performance budget or a React DevTools Profiler comparison identifies a meaningful bottleneck in the affected interaction. Measure with React DevTools Profiler before optimizing. +- Design components that express UI patterns; overly detailed components and types reduce maintainability. Prefer composition over inheritance. + +## Impact Analysis + +- Discovery covers every reference to the changed component or hook, its imported functions, and its Props/State types. +- Understanding covers each caller's purpose, the component hierarchy, and the data flow Props → State → Event handlers → Callbacks. +- Concise notes are sufficient for an isolated component change with no shared contract, routing, state-ownership, or build/config impact. + +## Quality Check Troubleshooting + +- **Port already in use**: stop the stale dev, preview, or test process holding the port +- **Stale cache**: re-run with the project's fresh or clean-cache option +- **Dependency errors**: clean-reinstall dependencies diff --git a/dev-workflows-fullstack/skills/documentation-criteria/references/task-template.md b/dev-workflows-fullstack/skills/documentation-criteria/references/task-template.md index 9af61233..0953928d 100644 --- a/dev-workflows-fullstack/skills/documentation-criteria/references/task-template.md +++ b/dev-workflows-fullstack/skills/documentation-criteria/references/task-template.md @@ -19,7 +19,7 @@ Preserve every directly constraining Work Plan citation unchanged so the executo ## Target Files - [Implementation file or responsibility] -- [Test file, when required] +- [Test file the Work Plan fixes, such as a generated skeleton] ## Investigation Targets diff --git a/dev-workflows-fullstack/skills/frontend-ai-guide/SKILL.md b/dev-workflows-fullstack/skills/frontend-ai-guide/SKILL.md deleted file mode 100644 index c4138e25..00000000 --- a/dev-workflows-fullstack/skills/frontend-ai-guide/SKILL.md +++ /dev/null @@ -1,177 +0,0 @@ ---- -name: frontend-ai-guide -description: Applies React/TypeScript-specific technical decision criteria, anti-pattern detection, debugging, and frontend quality gates. Use when reviewing components, hooks, browser behavior, or frontend implementation completeness. ---- - -# AI Developer Guide - Technical Decision Criteria and Anti-pattern Collection (Frontend) - -## 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 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 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 required value and proof at lower total complexity. - -## Technical Anti-patterns (Red Flag Patterns) - -Pause the affected decision and review the design when detecting the following patterns: - -### Code Quality Anti-patterns -1. **Duplicating one UI responsibility across independently maintained components** - Review whether the duplicated behavior or contract should have one owner -2. **Multiple responsibilities mixed in a single component** - Violates Single Responsibility Principle (SRP) -3. **Defining same content in multiple components** - Violates DRY principle -4. **Making changes without checking dependencies** - Potential for unexpected impacts -5. **Disabling code with comments** - Should use version control -6. **Error suppression** - Hiding problems creates technical debt -7. **Type assertions standing in for a guarantee** - Declaring a type established by neither a check nor an existing contract -8. **Pass-through prop chains that obscure state ownership** - Use composition, Context, or the project's state layer when intermediate components only forward values and a broader owner is clearer; retain explicit props when they preserve local ownership and broader state ownership would add coordination while responsibility remains local -9. **Components mixing independently changing responsibilities** - Split when rendering, state/data ownership, or reusable/testable behavior forms an independent responsibility; retain cohesive components when splitting would add avoidable prop/state synchronization - -### Design Anti-patterns -- **"Make it work for now" thinking** - Accumulation of technical debt -- **Patchwork implementation** - Unplanned additions to existing components -- **Symptomatic fixes** - Surface-level fixes that don't solve root causes -- **Unplanned large-scale changes** - Lack of incremental approach - -## Fallback Design Principles - -### Core Principle: Fail-Fast -Design philosophy that prioritizes improving primary code reliability over fallback implementations. - -### Criteria for Fallback Implementation -- **Fallback rule**: Implement a fallback when an accepted requirement, boundary contract, project policy, or Design Doc defines the degraded outcome and recovery owner -- **Layer Responsibilities**: - - Rendering failure in a child component subtree, including a hook that throws during render: Use the project's Error Boundary - - Event handlers, ordinary async callbacks, SSR, and hook/API operations outside rendering: Handle them at the owning event, hook, API, or server boundary using its error contract - -### Detection of Excessive Fallbacks -- Require design review when adding a catch that duplicates or fragments an existing recovery responsibility; retain it for a distinct failure mode with a documented recovery owner and visible UI outcome -- Require design review when the same failure is caught at multiple component/hook/API layers without one recovery owner, or when nested handlers obscure the visible UI state -- Identify the accepted recovery contract before implementing a fallback -- Make fallback activation observable through one existing UI, log, or metric channel at the boundary that owns diagnosis or recovery; add a new channel only when an operational requirement or project policy requires it - -## Criteria for Code Duplication - -Keep concrete implementations separate while their similarity is accidental or their UI ownership differs. Consolidate when repository evidence shows one shared interaction, validation rule, visual contract, or coordinated change responsibility. - -### Criteria for Commonalization - -**Cases for Commonalization** -- Business logic duplication -- Complex processing algorithms -- Component patterns (form fields, cards, etc.) -- Custom hooks -- Validation rules - -**Cases to Avoid Commonalization** -- Accidental matches (coincidentally same code) -- Possibility of evolving in different directions -- Significant readability decrease from commonalization -- Simple helpers in test code - -## Common Failure Patterns and Avoidance Methods - -### Pattern 1: Error Fix Chain -**Symptom**: Fixing one error causes new errors -**Cause**: Surface-level fixes without understanding root cause -**Avoidance**: Identify root cause with 5 Whys before fixing - -### Pattern 2: Circumventing Type Guarantees -**Symptom**: `any` or `as` declares a type that no check or contract establishes -**Cause**: Impulse to avoid type errors -**Avoidance**: Back the declared type with a check or an existing contract that guarantees it, at the boundary where that guarantee holds - -### Pattern 3: Implementation Without Sufficient Testing -**Symptom**: Many bugs after implementation -**Cause**: Accepted behavior left without a test that proves it -**Avoidance**: Prove each delivered behavior at the boundary where it is observed - -### Pattern 4: Building on Unverified Premises -**Symptom**: Dependent work fails, or workarounds accumulate, once an assumed premise proves false -**Cause**: Treating an assumed capability, behavior, or existing implementation as fact -**Avoidance**: When an unverified premise could invalidate the chosen approach, check it by the cheapest sufficient means before building dependent work on it. When results contradict the premise, reconsider the approach before patching its parts. Keep this reasoning in the active task; it needs no separate artifact. - -### Pattern 5: Insufficient Existing Code Investigation -**Symptom**: Duplicate implementations, architecture inconsistency, integration failures -**Cause**: Insufficient understanding of existing code before implementation -**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 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 - -## Quality Check Workflow - -Discover the repository's configured quality entry points and the categories they cover. Use the repository's declared package tooling and conventions and the categories below as the applicable evidence checklist. - -### Applicable Check Categories - -- **Lint/format** — the project's configured formatter and linter -- **Type check** — the project's configured type validation -- **Build** — the configured production or package build -- **Behavior checks** — the smallest configured tests that exercise the changed behavior, plus integration or E2E suites when the change crosses their boundary, a generated skeleton requires them, or the repository gate includes them - -Follow repository-declared command composition or ordering when it exists. Otherwise choose an order that respects command dependencies and provides useful feedback. Completion requires every applicable configured check to pass. - -### Troubleshooting -- **Port already in use** — stop the stale dev/preview/test process holding the port -- **Stale cache** — re-run with the project's fresh/clean-cache option -- **Dependency errors** — clean reinstall dependencies - -## Situations Requiring Technical Decisions - -### Timing of Abstraction -- Extract a shared abstraction after repository evidence establishes a shared UI responsibility and coordinated change pattern -- Be conscious of YAGNI, implement only currently needed features -- Prioritize current simplicity over future extensibility - -### Performance vs Readability -- Prioritize readability unless the project's performance budget or a React DevTools Profiler comparison identifies a meaningful bottleneck in the affected interaction -- Measure before optimizing with React DevTools Profiler -- Document reason with comments when optimizing - -### Granularity of Component/Type Definitions -- Overly detailed components/types reduce maintainability -- Design components that appropriately express UI patterns -- Use composition over inheritance - -## Implementation Completeness Assurance - -### Risk-Scaled Procedure for Impact Analysis - -**Completion Criteria**: Complete all 3 stages. Concise search/inspection notes are sufficient for an isolated component change with no shared contract, routing, state-ownership, or build/config impact; use the structured report for cross-component or high-risk changes. - -#### 1. Discovery -Search the repository for every reference to the changed component or hook, its imported functions, and its Props/State types. - -#### 2. Understanding -Read the discovered files needed to establish: -- Caller's purpose and context -- Component hierarchy -- Data flow: Props → State → Event handlers → Callbacks - -#### 3. Identification -For cross-component or high-risk changes, produce a structured impact report: -``` -## Impact Analysis -### Direct Impact: ComponentA, ComponentB (with reasons) -### Indirect Impact: FeatureX, PageY (with integration paths) -### Processing Flow: Props → Render → Events → Callbacks -``` - -Proceed when the accepted scope, consumers, state flow, required adjacent changes, and applicable checks are identified. - -### Unused Code Deletion Rule - -When the requested change makes a component, hook, utility, document, or configuration entry obsolete, delete it after checking its consumers and generated/operational use. Preserve and report uncertain or out-of-scope cleanup, and keep unrelated dormant code outside the implementation scope. - -### Existing Code Deletion Decision Flow - -``` -Required by the requested change? No → Preserve unless the change proves it obsolete - Yes → Working and compatible? Yes → Fix/extend - No → Repair or replace with migration/rollback evidence -``` diff --git a/dev-workflows-fullstack/skills/recipe-build/SKILL.md b/dev-workflows-fullstack/skills/recipe-build/SKILL.md index 7487ac37..7e8b3cb5 100644 --- a/dev-workflows-fullstack/skills/recipe-build/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-build/SKILL.md @@ -109,8 +109,8 @@ Before invoking post-implementation reviewers, apply subagents-orchestration-gui Resolve the Work Plan's readable Design Doc; missing input blocks review. -Emit these Agent calls in one assistant message, then await both: -- code-reviewer (subagent_type: "dev-workflows-fullstack:code-reviewer") → review the completed implementation with the resolved `governingDocuments`, the actual files changed by completed tasks as `implementationFiles`, and the Work Plan path +Invoke the code-reviewer calls for the subagents-orchestration-guide Post-Implementation Review Units and one security-reviewer call, then await all: +- code-reviewer (subagent_type: "dev-workflows-fullstack:code-reviewer") → one call per review unit with the resolved `governingDocuments`, the unit's changed files as `implementationFiles`, the unit's tasks as task scope, and the Work Plan path - security-reviewer (subagent_type: "dev-workflows-fullstack:security-reviewer") → review the completed implementation against the same `governingDocuments` Apply subagents-orchestration-guide's Post-Implementation Review status-routing and fix/re-run rules. Present the unified report; proceed to Final Cleanup after the complete review set reaches Review Resolution convergence. diff --git a/dev-workflows-fullstack/skills/recipe-design/SKILL.md b/dev-workflows-fullstack/skills/recipe-design/SKILL.md index 8f698021..ea44da06 100644 --- a/dev-workflows-fullstack/skills/recipe-design/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-design/SKILL.md @@ -63,7 +63,7 @@ This independent discovery keeps scope and option convergence grounded in reposi Execute Skill: requirement-convergence. The orchestrator builds and judges the convergence record from the user request and Step 2 evidence. -Judge all four convergence fields. Assign `cost` from Step 2 structural evidence and record its unknowns; run the hearing only for fields below `ready`. +Judge all four convergence fields by the rules in `references/criteria.md` of the requirement-convergence skill. Assign `cost` from Step 2 structural evidence and record its unknowns; run the hearing only for fields below `ready`. Determine Structural Scale from outcomes and responsibility boundaries. File count is supporting evidence only. diff --git a/dev-workflows-fullstack/skills/recipe-front-adjust/SKILL.md b/dev-workflows-fullstack/skills/recipe-front-adjust/SKILL.md index 59748bcf..1ba04995 100644 --- a/dev-workflows-fullstack/skills/recipe-front-adjust/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-front-adjust/SKILL.md @@ -91,7 +91,7 @@ Present the adjustment context to the user for review. ### Step 5: Adjustment + Verification (parent session) -Execute Skill: frontend-ai-guide before planning or applying adjustment edits. +Execute Skill: ai-development-guide and read its `references/frontend.md` before planning or applying adjustment edits. 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. diff --git a/dev-workflows-fullstack/skills/recipe-front-build/SKILL.md b/dev-workflows-fullstack/skills/recipe-front-build/SKILL.md index 3b37ce56..93e3620f 100644 --- a/dev-workflows-fullstack/skills/recipe-front-build/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-front-build/SKILL.md @@ -109,8 +109,8 @@ Before invoking post-implementation reviewers, apply subagents-orchestration-gui Resolve the Work Plan's readable Design Doc; missing input blocks review. -Emit these Agent calls in one assistant message, then await both: -- code-reviewer (subagent_type: "dev-workflows-fullstack:code-reviewer") → review the completed implementation with the resolved `governingDocuments`, the actual files changed by completed tasks as `implementationFiles`, and the Work Plan path +Invoke the code-reviewer calls for the subagents-orchestration-guide Post-Implementation Review Units and one security-reviewer call, then await all: +- code-reviewer (subagent_type: "dev-workflows-fullstack:code-reviewer") → one call per review unit with the resolved `governingDocuments`, the unit's changed files as `implementationFiles`, the unit's tasks as task scope, and the Work Plan path - security-reviewer (subagent_type: "dev-workflows-fullstack:security-reviewer") → review the completed implementation against the same `governingDocuments` Apply subagents-orchestration-guide's Post-Implementation Review status-routing and fix/re-run rules. Present the unified report; proceed to Final Cleanup after the complete review set reaches Review Resolution convergence. diff --git a/dev-workflows-fullstack/skills/recipe-front-design/SKILL.md b/dev-workflows-fullstack/skills/recipe-front-design/SKILL.md index 11753534..8b34a051 100644 --- a/dev-workflows-fullstack/skills/recipe-front-design/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-front-design/SKILL.md @@ -83,7 +83,7 @@ external_resource_refs: [selected references or []] Execute Skill: requirement-convergence. Build and judge the convergence record from the governing requirement source, repository analysis, and applicable UI analysis. -Judge all four convergence fields. Assign `cost` from Step 2 structural evidence and record its unknowns; run the hearing only for fields below `ready`. +Judge all four convergence fields by the rules in `references/criteria.md` of the requirement-convergence skill. Assign `cost` from Step 2 structural evidence and record its unknowns; run the hearing only for fields below `ready`. 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. diff --git a/dev-workflows-fullstack/skills/recipe-front-review/SKILL.md b/dev-workflows-fullstack/skills/recipe-front-review/SKILL.md index 4cc8f23e..73483f80 100644 --- a/dev-workflows-fullstack/skills/recipe-front-review/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-front-review/SKILL.md @@ -76,9 +76,6 @@ Then present the adjudicated result to the user. Group `apply` findings by propo ``` Implementation Review: [verdict from code-reviewer] - Acceptance Criteria: - - [fulfilled] [item]: [evidence] - - [unfulfilled] [item] -> [corresponding finding ID under Required Corrections] Required Corrections: - [id] [category] [location]: [description] — [basis and effect] [recommended: c | d | d and c] Limitations: diff --git a/dev-workflows-fullstack/skills/recipe-fullstack-build/SKILL.md b/dev-workflows-fullstack/skills/recipe-fullstack-build/SKILL.md index 1314eeca..57f83835 100644 --- a/dev-workflows-fullstack/skills/recipe-fullstack-build/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-fullstack-build/SKILL.md @@ -127,8 +127,8 @@ Before invoking post-implementation reviewers, apply subagents-orchestration-gui Resolve all readable Design Docs from the Work Plan, or the Work Plan itself when none exist; missing input blocks review. -Emit one code-reviewer call plus one security-reviewer call in one assistant message, then await both: -- code-reviewer (subagent_type: "dev-workflows-fullstack:code-reviewer") → review the completed implementation with the resolved `governingDocuments` list, the actual files changed by completed tasks as `implementationFiles`, and the Work Plan path +Invoke the code-reviewer calls for the subagents-orchestration-guide Post-Implementation Review Units and one security-reviewer call, then await all: +- code-reviewer (subagent_type: "dev-workflows-fullstack:code-reviewer") → one call per review unit with the resolved `governingDocuments` list, the unit's changed files as `implementationFiles`, the unit's tasks as task scope, and the Work Plan path - security-reviewer (subagent_type: "dev-workflows-fullstack:security-reviewer") → review the completed implementation against the same `governingDocuments` list Apply subagents-orchestration-guide's Post-Implementation Review status-routing and fix/re-run rules. Present the unified report; proceed to Final Cleanup after the complete review set reaches Review Resolution convergence. diff --git a/dev-workflows-fullstack/skills/recipe-fullstack-implement/SKILL.md b/dev-workflows-fullstack/skills/recipe-fullstack-implement/SKILL.md index fc0b46a6..4174c5b4 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 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. +Build and judge the convergence record by the rules in `references/criteria.md` of the requirement-convergence skill, 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. @@ -131,8 +131,8 @@ Apply subagents-orchestration-guide's retained verification limitation retry wit Resolve all readable Design Docs from the Work Plan, or the Work Plan itself when none exist; missing input blocks review. -Emit one code-reviewer call plus one security-reviewer call in one assistant message, then await both: -- code-reviewer (subagent_type: "dev-workflows-fullstack:code-reviewer") → review the completed implementation with the resolved `governingDocuments` list, the actual files changed by completed tasks as `implementationFiles`, and the Work Plan path +Invoke the code-reviewer calls for the subagents-orchestration-guide Post-Implementation Review Units and one security-reviewer call, then await all: +- code-reviewer (subagent_type: "dev-workflows-fullstack:code-reviewer") → one call per review unit with the resolved `governingDocuments` list, the unit's changed files as `implementationFiles`, the unit's tasks as task scope, and the Work Plan path - security-reviewer (subagent_type: "dev-workflows-fullstack:security-reviewer") → review the completed implementation against the same `governingDocuments` list Apply subagents-orchestration-guide's Post-Implementation Review status-routing and fix/re-run rules. Present the unified report; proceed to Final Cleanup after the complete review set reaches Review Resolution convergence. diff --git a/dev-workflows-fullstack/skills/recipe-implement/SKILL.md b/dev-workflows-fullstack/skills/recipe-implement/SKILL.md index 591b4773..e9503c81 100644 --- a/dev-workflows-fullstack/skills/recipe-implement/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-implement/SKILL.md @@ -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 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. +Build and judge the convergence record by the rules in `references/criteria.md` of the requirement-convergence skill, 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. @@ -119,8 +119,8 @@ Apply subagents-orchestration-guide's retained verification limitation retry bef Resolve the Work Plan's readable Design Doc; missing input blocks review. -Emit these Agent calls in one assistant message, then await both: -- code-reviewer (subagent_type: "dev-workflows-fullstack:code-reviewer") → review the completed implementation with the resolved `governingDocuments`, the actual files changed by completed tasks as `implementationFiles`, and the Work Plan path +Invoke the code-reviewer calls for the subagents-orchestration-guide Post-Implementation Review Units and one security-reviewer call, then await all: +- code-reviewer (subagent_type: "dev-workflows-fullstack:code-reviewer") → one call per review unit with the resolved `governingDocuments`, the unit's changed files as `implementationFiles`, the unit's tasks as task scope, and the Work Plan path - security-reviewer (subagent_type: "dev-workflows-fullstack:security-reviewer") → review the completed implementation against the same `governingDocuments` Apply subagents-orchestration-guide's Post-Implementation Review status-routing and fix/re-run rules. Present the unified report; proceed to Final Cleanup after the complete review set reaches Review Resolution convergence. diff --git a/dev-workflows-fullstack/skills/recipe-review/SKILL.md b/dev-workflows-fullstack/skills/recipe-review/SKILL.md index f7b09f04..479ab76b 100644 --- a/dev-workflows-fullstack/skills/recipe-review/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-review/SKILL.md @@ -76,9 +76,6 @@ Then present the adjudicated result to the user. Group `apply` findings by propo ``` Implementation Review: [verdict from code-reviewer] - Acceptance Criteria: - - [fulfilled] [item]: [evidence] - - [unfulfilled] [item] -> [corresponding finding ID under Required Corrections] Required Corrections: - [id] [category] [location]: [description] — [basis and effect] [recommended: c | d | d and c] Limitations: diff --git a/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md index 38f28531..887356c6 100644 --- a/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md @@ -196,6 +196,10 @@ graph TD For Small, execute one direct-scope 4-step cycle. Complete after `pass`, or retry a retained `verification_incomplete` result once and complete with its exact repeated limitation. Small has no task decomposition, document-dependent post-implementation review, or task-file cleanup. +### Post-Implementation Review Units (Medium/Large) + +Review a Medium change with one code-reviewer. A Large change is more than one code-reviewer can read in full; partition it into units of Work Plan tasks. A unit holds a consuming task (one delivering a screen, route, command, or job) together with the tasks it depends on through `Depends on`, so a contract's producer, its consumer, and every test proving their behavior are reviewed together; tasks that several units depend on form one shared unit. Each completed task belongs to one unit, whose `implementationFiles` are the files changed by its tasks' commits. Run at most 3 reviewer calls concurrently. security-reviewer reviews the complete change once. The unit reviewer that reported a finding owns it under the fix-cycle and re-run rules. + ### Post-Implementation Review Status Routing (Medium/Large) | Reviewer | Complete: empty finding set | Enter Review Resolution | Blocked | diff --git a/dev-workflows-fullstack/skills/testing-principles/SKILL.md b/dev-workflows-fullstack/skills/testing-principles/SKILL.md index 72579f85..afafb806 100644 --- a/dev-workflows-fullstack/skills/testing-principles/SKILL.md +++ b/dev-workflows-fullstack/skills/testing-principles/SKILL.md @@ -1,6 +1,6 @@ --- name: testing-principles -description: Language-agnostic testing principles for choosing which tests a change needs, test quality, and proof ownership, with frontend and browser E2E implementation references. Use when writing tests, deciding test scope, or reviewing test quality. +description: Language-agnostic testing principles for choosing which tests a change needs, test quality, and proof ownership, including frontend and browser E2E tests. Use when writing tests, deciding test scope, or reviewing test quality. --- # Language-Agnostic Testing Principles diff --git a/dev-workflows/agents/acceptance-test-generator.md b/dev-workflows/agents/acceptance-test-generator.md index 616b6920..5903323f 100644 --- a/dev-workflows/agents/acceptance-test-generator.md +++ b/dev-workflows/agents/acceptance-test-generator.md @@ -21,7 +21,7 @@ Accept equivalent labels and concise prose with the same meaning. Follow linked ## Selection -1. Read the accepted criteria, Design Doc verification requirements, and applicable UI Spec interactions, states and transitions. Apply testing-principles to establish the required proof boundary, then inspect actual existing test assertions and setup for coverage. +1. Read the accepted criteria, Design Doc verification requirements, and applicable UI Spec interactions, states and transitions. Apply testing-principles to establish the required proof boundary, reading its `references/frontend.md` for UI integration proof and `references/e2e.md` for browser E2E proof, then inspect actual existing test assertions and setup for coverage. 2. For uncovered integration/E2E proof, write the smallest sufficient skeleton set. Record the production entry/composition to traverse, real dependencies and allowed substitutes in the existing proof obligation. Before implementation exists, derive that obligation from the governing design; a test that could be written is planned proof, not existing coverage. 3. Explain each empty lane from sufficient existing proof, a selected skeleton in another lane, or why the accepted behavior requires no proof at that lane's boundary. Return an exact limitation for a required but unavailable boundary. diff --git a/dev-workflows/agents/code-reviewer.md b/dev-workflows/agents/code-reviewer.md index e8d55424..7b801887 100644 --- a/dev-workflows/agents/code-reviewer.md +++ b/dev-workflows/agents/code-reviewer.md @@ -1,6 +1,6 @@ --- name: code-reviewer -description: Reviews completed implementation for governing-source compliance, scope economy, repository quality policy, and material code correctness. Use after implementation or when review/implementation check/compliance is requested. +description: Reviews completed implementation for material code correctness, unnecessary mechanisms and tests, governing-source compliance, and repository quality policy. Use after implementation or when review/implementation check/compliance is requested. tools: Read, Grep, Glob, LS, Bash skills: - ai-development-guide @@ -14,11 +14,7 @@ Operate in an independent context and continue until the review result is comple The review aims at the required outcome with the least justified complexity: every unnecessary mechanism or test adds implementation, test, and maintenance obligations. -Implementers work one task at a time, and running tests and quality checks belongs to the workflow's quality gate, not to this review. This independent context exists so one reviewer can read the whole change in detail: reading the changed code and tests is the verification only this review adds, and a passing run shows only that the tests agree with the code, not that either is right. Map the whole change; the Findings Boundary keeps what you report narrow. - -## Execution Gate - -Before acting, map the preloaded skills to concrete rules for this review. Advance only when the current step's required evidence is present. Before returning, verify the result against the completion check and output contract. +Verify by reading the changed code and tests. Running tests and quality checks is outside this review; a passing run shows only that the tests agree with the code, not that either is right. ## Inputs @@ -27,23 +23,31 @@ Before acting, map the preloaded skills to concrete rules for this review. Advan - **Work Plan and task scope**: Use when supplied to identify approved execution and review boundaries - **prior_feedback** (optional): Array of `{ id, disposition, reason?, evidence }` from the preceding Review Resolution decision -Read `docs/project-context/quality.yaml` when it exists. It adds repository-specific review dimensions; its absence leaves the built-in review boundary unchanged. Verify input paths and inspect only references that can change an in-scope finding or limitation. +Read `docs/project-context/quality.yaml` when it exists. It adds repository-specific review dimensions; its absence leaves the built-in review boundary unchanged. Verify input paths, and inspect only the documents they link to that can change an in-scope finding or limitation. + +## Preparation + +Before reviewing, read these files; they hold review criteria beyond the preloaded skills: + +- `references/frontend.md` in the testing-principles skill +- `references/frontend.md` in the ai-development-guide skill +- `references/e2e.md` in the testing-principles skill ## Initial Review Extract the approved outcome, applicable acceptance criteria, changed interfaces and contracts, protected behavior, non-goals, required design decisions, and verification expectations. -Map every applicable acceptance criterion and material surface in `implementationFiles` to its governing contract, applicable quality dimension, direct implementation or test evidence, and any candidate problem. Each changed test is itself a surface: map it to the claim it proves and the boundary it proves it at, because tests looked up only as evidence for criteria never reveal a claim proven twice. Consider a failure that could pass a shallow happy-path check when it can change the judgment. Review the complete map in this order: +Judge the material surfaces in `implementationFiles` against these criteria: -1. **Outcome and contracts**: Confirm each applicable criterion from the changed code and tests at file:line and preserve public, serialized, persisted, user-visible, error, identifier, and producer-consumer contracts. -2. **Scope economy**: For each material mechanism, abstraction, dependency, state, defensive control, or test added by the change, identify the required result it serves (an approved requirement, repository rule, observed contract or failure, or evidence-backed material risk in the reachable changed path) and whether omitting it, narrowing it, or reusing existing code or tests would serve that result; an addition is worth its lifecycle cost only when none of these would. A Design Doc that selected the mechanism records the current means, not that justification. For a test, judge this by the testing-principles Test Selection rules. When narrowing or removing an addition preserves the outcome and contracts, use that reduction as the correction. -3. **Required design and proof**: Preserve the governing source's responsibility boundaries. Require proof at the observable boundary claimed by the governing source or task. -4. **Code quality**: Apply the preloaded skills to concrete changed-path correctness, contract safety, repository-local patterns, error behavior, and proof quality. -5. **Repository quality policy**: Apply each `docs/project-context/quality.yaml` dimension whose `applies_when` condition matches the change. Its `pass` condition and cited `evidence` define the accepted state. +- **Outcome and contracts**: The changed code and tests deliver each applicable criterion at file:line and preserve public, serialized, persisted, user-visible, error, identifier, and producer-consumer contracts. +- **Scope economy**: For each material mechanism, abstraction, dependency, state, defensive control, or test added by the change, identify the required result it serves (an approved requirement, repository rule, observed contract or failure, or evidence-backed material risk in the reachable changed path) and whether omitting it, narrowing it, or reusing existing code or tests would serve that result; an addition is worth its lifecycle cost only when none of these would. A Design Doc that selected the mechanism records the current means, not that justification. For a test, judge this by the testing-principles Test Selection rules. +- **Required design and proof**: Preserve the governing source's responsibility boundaries. Require proof at the observable boundary claimed by the governing source or task. Each changed test is itself a surface: judge the claim it proves and the boundary it proves it at, because tests looked up only as evidence for criteria never reveal a claim proven twice. +- **Code quality**: Apply the preloaded skills to concrete changed-path correctness, contract safety, repository-local patterns, error behavior, and proof quality. +- **Repository quality policy**: Apply each `docs/project-context/quality.yaml` dimension whose `applies_when` condition matches the change. Its `pass` condition and cited `evidence` define the accepted state. -Inspect an adjacent case when repository evidence shows that it shares the changed cause, contract, or state boundary and leaving it unchanged would keep the same in-scope failure active. Require additional internal-detail or edge-case tests only when a requirement, preserved behavior, observed defect class, applicable quality dimension, or evidence-backed material risk makes them part of the current proof. +Consider a failure that could pass a shallow happy-path check when it can change the judgment. Inspect an adjacent case when repository evidence shows that it shares the changed cause, contract, or state boundary and leaving it unchanged would keep the same in-scope failure active. Require additional internal-detail or edge-case tests only when a requirement, preserved behavior, observed defect class, applicable quality dimension, or evidence-backed material risk makes them part of the current proof. -Continue through every mapped item after observing a candidate problem, and choose the verdict only after the complete map is resolved. Verify candidate problems against supporting and contradicting evidence, then consolidate candidates only when one correction resolves the same cause. +Verify candidate problems against supporting and contradicting evidence, consolidate candidates only when one correction resolves the same cause, and choose the verdict after the review is complete. ## Correction Re-review @@ -71,7 +75,7 @@ Emit a finding only when correction is required because the implementation is in Represent every unfulfilled acceptance criterion with one corresponding finding so Review Resolution has an actionable correction boundary. -Express `suggestion` as the smallest observable accepted state after correction. Name an implementation mechanism only when the governing source requires it. For `scope_excess`, prefer removal or narrowing that preserves the approved outcome and contracts. +Express `suggestion` as the smallest observable accepted state after correction. Name an implementation mechanism only when the governing source requires it. Use `limitations` only when unavailable evidence prevents judging an applicable criterion, contract, material addition, or quality dimension. State the blocked judgment and its effect. @@ -82,7 +86,7 @@ The final message is one JSON object. During execution, progress messages may us Initial review: ```json -{"verdict":"pass|needs-improvement|needs-redesign|blocked","acceptanceCriteria":[{"item":"governing criterion identifier or text","status":"fulfilled|unfulfilled","evidence":["file:line"],"gap":"material gap or null"}],"findings":[{"id":"F001","category":"dd_violation|scope_excess|reliability|coverage_gap|quality_rule|adjacent_residual","location":"file:line","description":"specific required-correction issue","basis":"governing source, quality dimension, or observed fact","effect":"observable consequence","suggestion":"smallest sufficient accepted state"}],"limitations":["unverified judgment and effect"]} +{"verdict":"pass|needs-improvement|needs-redesign|blocked","findings":[{"id":"F001","category":"dd_violation|scope_excess|reliability|coverage_gap|quality_rule|adjacent_residual","location":"file:line","description":"specific required-correction issue","basis":"governing source, quality dimension, or observed fact","effect":"observable consequence","suggestion":"smallest sufficient accepted state"}],"limitations":["unverified judgment and effect"]} ``` Correction re-review: @@ -100,10 +104,10 @@ Correction re-review: ## Completion Check -- [ ] The initial review resolved every applicable criterion and material changed surface before choosing its verdict, or the correction re-review reconciled every received item once +- [ ] The initial review chose its verdict after judging every material surface in `implementationFiles`, or the correction re-review reconciled every received item once - [ ] Changed contracts and required proof were checked against the code and tests at file:line +- [ ] Frontend changes were judged against `references/frontend.md`, and browser E2E tests against `references/e2e.md` - [ ] Every unfulfilled acceptance criterion has one corresponding finding -- [ ] Material additions were necessary and worth their cost over subtraction or reuse, or reported with removal or narrowing as the correction - [ ] Every emitted finding requires correction under the Findings Boundary - [ ] Applicable repository quality dimensions were checked against their cited evidence - [ ] Review breadth and proposed corrections remain within the approved outcome diff --git a/dev-workflows/agents/integration-test-reviewer.md b/dev-workflows/agents/integration-test-reviewer.md index 91a198ff..bca200e4 100644 --- a/dev-workflows/agents/integration-test-reviewer.md +++ b/dev-workflows/agents/integration-test-reviewer.md @@ -15,6 +15,13 @@ Operates in an independent context, executing autonomously until task completion Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. +## Preparation + +Before reviewing, read these files; they hold review criteria beyond the preloaded skills: + +- `references/frontend.md` in the testing-principles skill +- `references/e2e.md` in the testing-principles skill + ## Input Parameters - **changedTestFiles**: Non-empty list of integration or E2E test files changed by the task diff --git a/dev-workflows/agents/investigator.md b/dev-workflows/agents/investigator.md index 38169c72..162e6861 100644 --- a/dev-workflows/agents/investigator.md +++ b/dev-workflows/agents/investigator.md @@ -13,6 +13,10 @@ You are an AI assistant specializing in problem investigation. Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. +## Preparation + +Before investigating, read `references/frontend.md` in the ai-development-guide skill; it holds frontend criteria beyond the preloaded skills. + ## Input and Responsibility Boundaries - **Input**: Accepts both text and JSON formats. For JSON, use `problemSummary` diff --git a/dev-workflows/agents/quality-fixer.md b/dev-workflows/agents/quality-fixer.md index cf730b03..c065367d 100644 --- a/dev-workflows/agents/quality-fixer.md +++ b/dev-workflows/agents/quality-fixer.md @@ -71,7 +71,7 @@ Run every applicable check discovered in Step 2. Use repository-declared command - Reuse mutation evidence after confirming complete fields, matching revision/files, restoration, and proof of the claimed behavior; otherwise replace it with fresh evidence. ### Step 4: Fix Errors -Apply fixes per coding-principles and testing-principles skills. +Apply fixes per coding-principles and testing-principles skills. For a failing browser E2E test, read `references/e2e.md` in the testing-principles skill; it defines the lane, harness, and assertion rules the test must follow. ### Step 5: Repeat Until Checks Pass - In-scope error found → Fix → Re-run checks diff --git a/dev-workflows/agents/solver.md b/dev-workflows/agents/solver.md index fe52b5f3..a0b74997 100644 --- a/dev-workflows/agents/solver.md +++ b/dev-workflows/agents/solver.md @@ -14,6 +14,10 @@ You are an AI assistant specializing in solution derivation. Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. +## Preparation + +Before deriving solutions, read `references/frontend.md` in the ai-development-guide skill; it holds frontend criteria beyond the preloaded skills. + ## Input and Responsibility Boundaries - **Input**: A verified conclusion with `coverageDisposition: closed` diff --git a/dev-workflows/agents/task-decomposer.md b/dev-workflows/agents/task-decomposer.md index a461e786..e4c0e9d7 100644 --- a/dev-workflows/agents/task-decomposer.md +++ b/dev-workflows/agents/task-decomposer.md @@ -48,7 +48,7 @@ For each task: 1. Copy every governing-source citation unchanged into `Governing Sources`. 2. Add those cited sections, the target implementation, and one representative adjacent test to `Investigation Targets`. -3. Select concrete Target Files when repository evidence makes them known. +3. Select concrete Target Files when repository evidence makes them known. List a test file only when the Work Plan fixes it; the executor selects other tests under testing-principles. 4. When an exact file is not yet knowable, name the smallest owner directory or module and the search criterion the executor can resolve. The task file points to authoritative governing content instead of reproducing it. The executor reads every Investigation Target before implementation. diff --git a/dev-workflows/agents/task-executor.md b/dev-workflows/agents/task-executor.md index be4a9318..fd696e45 100644 --- a/dev-workflows/agents/task-executor.md +++ b/dev-workflows/agents/task-executor.md @@ -41,7 +41,7 @@ Apply loaded architecture/coding/testing rules during implementation. Follow tas When `docs/project-context/quality.yaml` exists, use it as implementation guidance. -Deliver the outcome with contracts satisfied at their boundaries, errors propagated or handled explicitly, and tests asserting the behavior the task delivers. Downstream quality assurance re-checks these properties. +Deliver the outcome with contracts satisfied at their boundaries, errors propagated or handled explicitly, and tests asserting the behavior the task delivers. ## Design Surface Check (Before Mandatory Judgment) @@ -87,7 +87,7 @@ Any YES is corrected in implementation when the value boundary can remain true. ## 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 value boundary. +**Policy**: Start implementation immediately (treat as approved). **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 @@ -152,7 +152,7 @@ Apply coding-principles Reference Representativeness using the changed area and **When the outcome is already satisfied**: Preserve the implementation and proceed to Operation Verification before reporting completion. -Implement the behaviors the task delivers and prove them under testing-principles and the task's Operation Verification Methods. Implement and run required integration/E2E tests in the earliest task where their declared proof boundary and dependencies are executable. Preserve generated skeleton paths and repository-required final checks. Apply the Responsibility Boundaries progress rule after verification. +Implement the behaviors the task delivers and prove them under testing-principles and the task's Operation Verification Methods. Before writing browser E2E tests, read `references/e2e.md` in the testing-principles skill; it defines the scope and ownership criteria for those tests. Implement and run required integration/E2E tests in the earliest task where their declared proof boundary and dependencies are executable. Preserve generated skeleton paths and repository-required final checks. Apply the Responsibility Boundaries progress rule after verification. #### Operation Verification - Execute the Operation Verification Methods in the execution instructions @@ -233,5 +233,3 @@ This gate runs immediately before producing the final JSON response. ☐ Every available Operation Verification Method ran; each unavailable or failed check has its exact result and affected proof in `runnableCheck` ☐ 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 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 483f13f1..b01a6322 100644 --- a/dev-workflows/agents/technical-designer.md +++ b/dev-workflows/agents/technical-designer.md @@ -54,7 +54,7 @@ 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 orchestrator's Choice or Durability filter result, return the contradiction for orchestrator resolution. +Create one ADR per supplied decision point and finish the complete batch before returning. Follow `references/adr-template.md` in the documentation-criteria skill. 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. diff --git a/dev-workflows/agents/verifier.md b/dev-workflows/agents/verifier.md index ccccf51b..fbfcf658 100644 --- a/dev-workflows/agents/verifier.md +++ b/dev-workflows/agents/verifier.md @@ -13,6 +13,10 @@ You are an AI assistant specializing in investigation result verification. Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. +## Preparation + +Before verifying, read `references/frontend.md` in the ai-development-guide skill; it holds frontend criteria beyond the preloaded skills. + ## Input and Responsibility Boundaries - **Input**: Structured investigation results (JSON) or text format investigation results diff --git a/dev-workflows/skills/ai-development-guide/SKILL.md b/dev-workflows/skills/ai-development-guide/SKILL.md index b0fff492..70fbfe0a 100644 --- a/dev-workflows/skills/ai-development-guide/SKILL.md +++ b/dev-workflows/skills/ai-development-guide/SKILL.md @@ -1,6 +1,6 @@ --- name: ai-development-guide -description: Applies language-agnostic and backend technical decision criteria, anti-pattern detection, debugging, and quality gates. Use when reviewing general/backend implementation choices, code smells, failures, or implementation completeness. +description: Applies technical decision criteria, anti-pattern detection, debugging, and quality gates for backend and frontend code. Use when implementing, reviewing, or diagnosing code, code smells, failures, or implementation completeness. --- # AI Developer Guide - Technical Decision Criteria and Anti-pattern Collection @@ -249,3 +249,7 @@ Required by the requested change? No → Preserve unless the change proves it ob ``` **Principle**: Prefer clean implementation over patching broken code + +## References + +- [references/frontend.md](references/frontend.md): read when implementing, reviewing, fixing, or diagnosing frontend code diff --git a/dev-workflows/skills/ai-development-guide/references/frontend.md b/dev-workflows/skills/ai-development-guide/references/frontend.md new file mode 100644 index 00000000..4312ae3b --- /dev/null +++ b/dev-workflows/skills/ai-development-guide/references/frontend.md @@ -0,0 +1,37 @@ +# Frontend (React/TypeScript) Criteria + +Apply these with the SKILL.md criteria. Each entry adds what React and TypeScript code needs beyond them. + +## Anti-patterns + +- **Type assertions standing in for a guarantee**: `any` or `as` declares a type that no check or contract establishes. Back the declared type with a check or an existing contract at the boundary where that guarantee holds. +- **Pass-through prop chains that obscure state ownership**: Use composition, Context, or the project's state layer when intermediate components only forward values and a broader owner is clearer. Retain explicit props when they preserve local ownership and a broader owner would add coordination while responsibility remains local. +- **Components mixing independently changing responsibilities**: Split when rendering, state/data ownership, or reusable/testable behavior forms an independent responsibility. Retain a cohesive component when splitting would add avoidable prop/state synchronization. + +## Error Handling Boundaries + +- A rendering failure in a child component subtree, including a hook that throws during render, belongs to the project's Error Boundary. +- Event handlers, ordinary async callbacks, SSR, and hook/API operations outside rendering are handled at the owning event, hook, API, or server boundary through its error contract. +- Require design review when the same failure is caught at multiple component, hook, or API layers without one recovery owner, or when nested handlers obscure the visible UI state. + +## Reuse and Commonalization + +- Component patterns (form fields, cards, and similar) and custom hooks are commonalization candidates under the SKILL.md criteria. +- When judging whether similar functionality is a valid model, compare its props, lifecycle, state ownership, and design-system role along with repository usage. + +## Performance and Granularity + +- Prioritize readability unless the project's performance budget or a React DevTools Profiler comparison identifies a meaningful bottleneck in the affected interaction. Measure with React DevTools Profiler before optimizing. +- Design components that express UI patterns; overly detailed components and types reduce maintainability. Prefer composition over inheritance. + +## Impact Analysis + +- Discovery covers every reference to the changed component or hook, its imported functions, and its Props/State types. +- Understanding covers each caller's purpose, the component hierarchy, and the data flow Props → State → Event handlers → Callbacks. +- Concise notes are sufficient for an isolated component change with no shared contract, routing, state-ownership, or build/config impact. + +## Quality Check Troubleshooting + +- **Port already in use**: stop the stale dev, preview, or test process holding the port +- **Stale cache**: re-run with the project's fresh or clean-cache option +- **Dependency errors**: clean-reinstall dependencies diff --git a/dev-workflows/skills/documentation-criteria/references/task-template.md b/dev-workflows/skills/documentation-criteria/references/task-template.md index 9af61233..0953928d 100644 --- a/dev-workflows/skills/documentation-criteria/references/task-template.md +++ b/dev-workflows/skills/documentation-criteria/references/task-template.md @@ -19,7 +19,7 @@ Preserve every directly constraining Work Plan citation unchanged so the executo ## Target Files - [Implementation file or responsibility] -- [Test file, when required] +- [Test file the Work Plan fixes, such as a generated skeleton] ## Investigation Targets diff --git a/dev-workflows/skills/recipe-build/SKILL.md b/dev-workflows/skills/recipe-build/SKILL.md index b0aadebb..14d4ca35 100644 --- a/dev-workflows/skills/recipe-build/SKILL.md +++ b/dev-workflows/skills/recipe-build/SKILL.md @@ -109,8 +109,8 @@ Before invoking post-implementation reviewers, apply subagents-orchestration-gui Resolve the Work Plan's readable Design Doc; missing input blocks review. -Emit these Agent calls in one assistant message, then await both: -- code-reviewer (subagent_type: "dev-workflows:code-reviewer") → review the completed implementation with the resolved `governingDocuments`, the actual files changed by completed tasks as `implementationFiles`, and the Work Plan path +Invoke the code-reviewer calls for the subagents-orchestration-guide Post-Implementation Review Units and one security-reviewer call, then await all: +- code-reviewer (subagent_type: "dev-workflows:code-reviewer") → one call per review unit with the resolved `governingDocuments`, the unit's changed files as `implementationFiles`, the unit's tasks as task scope, and the Work Plan path - security-reviewer (subagent_type: "dev-workflows:security-reviewer") → review the completed implementation against the same `governingDocuments` Apply subagents-orchestration-guide's Post-Implementation Review status-routing and fix/re-run rules. Present the unified report; proceed to Final Cleanup after the complete review set reaches Review Resolution convergence. diff --git a/dev-workflows/skills/recipe-design/SKILL.md b/dev-workflows/skills/recipe-design/SKILL.md index bd4032ab..9200baf2 100644 --- a/dev-workflows/skills/recipe-design/SKILL.md +++ b/dev-workflows/skills/recipe-design/SKILL.md @@ -63,7 +63,7 @@ This independent discovery keeps scope and option convergence grounded in reposi Execute Skill: requirement-convergence. The orchestrator builds and judges the convergence record from the user request and Step 2 evidence. -Judge all four convergence fields. Assign `cost` from Step 2 structural evidence and record its unknowns; run the hearing only for fields below `ready`. +Judge all four convergence fields by the rules in `references/criteria.md` of the requirement-convergence skill. Assign `cost` from Step 2 structural evidence and record its unknowns; run the hearing only for fields below `ready`. Determine Structural Scale from outcomes and responsibility boundaries. File count is supporting evidence only. diff --git a/dev-workflows/skills/recipe-implement/SKILL.md b/dev-workflows/skills/recipe-implement/SKILL.md index d1fcf62c..bfd829fd 100644 --- a/dev-workflows/skills/recipe-implement/SKILL.md +++ b/dev-workflows/skills/recipe-implement/SKILL.md @@ -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 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. +Build and judge the convergence record by the rules in `references/criteria.md` of the requirement-convergence skill, 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. @@ -119,8 +119,8 @@ Apply subagents-orchestration-guide's retained verification limitation retry bef Resolve the Work Plan's readable Design Doc; missing input blocks review. -Emit these Agent calls in one assistant message, then await both: -- code-reviewer (subagent_type: "dev-workflows:code-reviewer") → review the completed implementation with the resolved `governingDocuments`, the actual files changed by completed tasks as `implementationFiles`, and the Work Plan path +Invoke the code-reviewer calls for the subagents-orchestration-guide Post-Implementation Review Units and one security-reviewer call, then await all: +- code-reviewer (subagent_type: "dev-workflows:code-reviewer") → one call per review unit with the resolved `governingDocuments`, the unit's changed files as `implementationFiles`, the unit's tasks as task scope, and the Work Plan path - security-reviewer (subagent_type: "dev-workflows:security-reviewer") → review the completed implementation against the same `governingDocuments` Apply subagents-orchestration-guide's Post-Implementation Review status-routing and fix/re-run rules. Present the unified report; proceed to Final Cleanup after the complete review set reaches Review Resolution convergence. diff --git a/dev-workflows/skills/recipe-review/SKILL.md b/dev-workflows/skills/recipe-review/SKILL.md index eec33915..b95c562b 100644 --- a/dev-workflows/skills/recipe-review/SKILL.md +++ b/dev-workflows/skills/recipe-review/SKILL.md @@ -76,9 +76,6 @@ Then present the adjudicated result to the user. Group `apply` findings by propo ``` Implementation Review: [verdict from code-reviewer] - Acceptance Criteria: - - [fulfilled] [item]: [evidence] - - [unfulfilled] [item] -> [corresponding finding ID under Required Corrections] Required Corrections: - [id] [category] [location]: [description] — [basis and effect] [recommended: c | d | d and c] Limitations: diff --git a/dev-workflows/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows/skills/subagents-orchestration-guide/SKILL.md index 38f28531..887356c6 100644 --- a/dev-workflows/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows/skills/subagents-orchestration-guide/SKILL.md @@ -196,6 +196,10 @@ graph TD For Small, execute one direct-scope 4-step cycle. Complete after `pass`, or retry a retained `verification_incomplete` result once and complete with its exact repeated limitation. Small has no task decomposition, document-dependent post-implementation review, or task-file cleanup. +### Post-Implementation Review Units (Medium/Large) + +Review a Medium change with one code-reviewer. A Large change is more than one code-reviewer can read in full; partition it into units of Work Plan tasks. A unit holds a consuming task (one delivering a screen, route, command, or job) together with the tasks it depends on through `Depends on`, so a contract's producer, its consumer, and every test proving their behavior are reviewed together; tasks that several units depend on form one shared unit. Each completed task belongs to one unit, whose `implementationFiles` are the files changed by its tasks' commits. Run at most 3 reviewer calls concurrently. security-reviewer reviews the complete change once. The unit reviewer that reported a finding owns it under the fix-cycle and re-run rules. + ### Post-Implementation Review Status Routing (Medium/Large) | Reviewer | Complete: empty finding set | Enter Review Resolution | Blocked | diff --git a/dev-workflows/skills/testing-principles/SKILL.md b/dev-workflows/skills/testing-principles/SKILL.md index 72579f85..afafb806 100644 --- a/dev-workflows/skills/testing-principles/SKILL.md +++ b/dev-workflows/skills/testing-principles/SKILL.md @@ -1,6 +1,6 @@ --- name: testing-principles -description: Language-agnostic testing principles for choosing which tests a change needs, test quality, and proof ownership, with frontend and browser E2E implementation references. Use when writing tests, deciding test scope, or reviewing test quality. +description: Language-agnostic testing principles for choosing which tests a change needs, test quality, and proof ownership, including frontend and browser E2E tests. Use when writing tests, deciding test scope, or reviewing test quality. --- # Language-Agnostic Testing Principles diff --git a/skills/ai-development-guide/SKILL.md b/skills/ai-development-guide/SKILL.md index b0fff492..70fbfe0a 100644 --- a/skills/ai-development-guide/SKILL.md +++ b/skills/ai-development-guide/SKILL.md @@ -1,6 +1,6 @@ --- name: ai-development-guide -description: Applies language-agnostic and backend technical decision criteria, anti-pattern detection, debugging, and quality gates. Use when reviewing general/backend implementation choices, code smells, failures, or implementation completeness. +description: Applies technical decision criteria, anti-pattern detection, debugging, and quality gates for backend and frontend code. Use when implementing, reviewing, or diagnosing code, code smells, failures, or implementation completeness. --- # AI Developer Guide - Technical Decision Criteria and Anti-pattern Collection @@ -249,3 +249,7 @@ Required by the requested change? No → Preserve unless the change proves it ob ``` **Principle**: Prefer clean implementation over patching broken code + +## References + +- [references/frontend.md](references/frontend.md): read when implementing, reviewing, fixing, or diagnosing frontend code diff --git a/skills/ai-development-guide/references/frontend.md b/skills/ai-development-guide/references/frontend.md new file mode 100644 index 00000000..4312ae3b --- /dev/null +++ b/skills/ai-development-guide/references/frontend.md @@ -0,0 +1,37 @@ +# Frontend (React/TypeScript) Criteria + +Apply these with the SKILL.md criteria. Each entry adds what React and TypeScript code needs beyond them. + +## Anti-patterns + +- **Type assertions standing in for a guarantee**: `any` or `as` declares a type that no check or contract establishes. Back the declared type with a check or an existing contract at the boundary where that guarantee holds. +- **Pass-through prop chains that obscure state ownership**: Use composition, Context, or the project's state layer when intermediate components only forward values and a broader owner is clearer. Retain explicit props when they preserve local ownership and a broader owner would add coordination while responsibility remains local. +- **Components mixing independently changing responsibilities**: Split when rendering, state/data ownership, or reusable/testable behavior forms an independent responsibility. Retain a cohesive component when splitting would add avoidable prop/state synchronization. + +## Error Handling Boundaries + +- A rendering failure in a child component subtree, including a hook that throws during render, belongs to the project's Error Boundary. +- Event handlers, ordinary async callbacks, SSR, and hook/API operations outside rendering are handled at the owning event, hook, API, or server boundary through its error contract. +- Require design review when the same failure is caught at multiple component, hook, or API layers without one recovery owner, or when nested handlers obscure the visible UI state. + +## Reuse and Commonalization + +- Component patterns (form fields, cards, and similar) and custom hooks are commonalization candidates under the SKILL.md criteria. +- When judging whether similar functionality is a valid model, compare its props, lifecycle, state ownership, and design-system role along with repository usage. + +## Performance and Granularity + +- Prioritize readability unless the project's performance budget or a React DevTools Profiler comparison identifies a meaningful bottleneck in the affected interaction. Measure with React DevTools Profiler before optimizing. +- Design components that express UI patterns; overly detailed components and types reduce maintainability. Prefer composition over inheritance. + +## Impact Analysis + +- Discovery covers every reference to the changed component or hook, its imported functions, and its Props/State types. +- Understanding covers each caller's purpose, the component hierarchy, and the data flow Props → State → Event handlers → Callbacks. +- Concise notes are sufficient for an isolated component change with no shared contract, routing, state-ownership, or build/config impact. + +## Quality Check Troubleshooting + +- **Port already in use**: stop the stale dev, preview, or test process holding the port +- **Stale cache**: re-run with the project's fresh or clean-cache option +- **Dependency errors**: clean-reinstall dependencies diff --git a/skills/documentation-criteria/references/task-template.md b/skills/documentation-criteria/references/task-template.md index 9af61233..0953928d 100644 --- a/skills/documentation-criteria/references/task-template.md +++ b/skills/documentation-criteria/references/task-template.md @@ -19,7 +19,7 @@ Preserve every directly constraining Work Plan citation unchanged so the executo ## Target Files - [Implementation file or responsibility] -- [Test file, when required] +- [Test file the Work Plan fixes, such as a generated skeleton] ## Investigation Targets diff --git a/skills/frontend-ai-guide/SKILL.md b/skills/frontend-ai-guide/SKILL.md deleted file mode 100644 index c4138e25..00000000 --- a/skills/frontend-ai-guide/SKILL.md +++ /dev/null @@ -1,177 +0,0 @@ ---- -name: frontend-ai-guide -description: Applies React/TypeScript-specific technical decision criteria, anti-pattern detection, debugging, and frontend quality gates. Use when reviewing components, hooks, browser behavior, or frontend implementation completeness. ---- - -# AI Developer Guide - Technical Decision Criteria and Anti-pattern Collection (Frontend) - -## 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 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 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 required value and proof at lower total complexity. - -## Technical Anti-patterns (Red Flag Patterns) - -Pause the affected decision and review the design when detecting the following patterns: - -### Code Quality Anti-patterns -1. **Duplicating one UI responsibility across independently maintained components** - Review whether the duplicated behavior or contract should have one owner -2. **Multiple responsibilities mixed in a single component** - Violates Single Responsibility Principle (SRP) -3. **Defining same content in multiple components** - Violates DRY principle -4. **Making changes without checking dependencies** - Potential for unexpected impacts -5. **Disabling code with comments** - Should use version control -6. **Error suppression** - Hiding problems creates technical debt -7. **Type assertions standing in for a guarantee** - Declaring a type established by neither a check nor an existing contract -8. **Pass-through prop chains that obscure state ownership** - Use composition, Context, or the project's state layer when intermediate components only forward values and a broader owner is clearer; retain explicit props when they preserve local ownership and broader state ownership would add coordination while responsibility remains local -9. **Components mixing independently changing responsibilities** - Split when rendering, state/data ownership, or reusable/testable behavior forms an independent responsibility; retain cohesive components when splitting would add avoidable prop/state synchronization - -### Design Anti-patterns -- **"Make it work for now" thinking** - Accumulation of technical debt -- **Patchwork implementation** - Unplanned additions to existing components -- **Symptomatic fixes** - Surface-level fixes that don't solve root causes -- **Unplanned large-scale changes** - Lack of incremental approach - -## Fallback Design Principles - -### Core Principle: Fail-Fast -Design philosophy that prioritizes improving primary code reliability over fallback implementations. - -### Criteria for Fallback Implementation -- **Fallback rule**: Implement a fallback when an accepted requirement, boundary contract, project policy, or Design Doc defines the degraded outcome and recovery owner -- **Layer Responsibilities**: - - Rendering failure in a child component subtree, including a hook that throws during render: Use the project's Error Boundary - - Event handlers, ordinary async callbacks, SSR, and hook/API operations outside rendering: Handle them at the owning event, hook, API, or server boundary using its error contract - -### Detection of Excessive Fallbacks -- Require design review when adding a catch that duplicates or fragments an existing recovery responsibility; retain it for a distinct failure mode with a documented recovery owner and visible UI outcome -- Require design review when the same failure is caught at multiple component/hook/API layers without one recovery owner, or when nested handlers obscure the visible UI state -- Identify the accepted recovery contract before implementing a fallback -- Make fallback activation observable through one existing UI, log, or metric channel at the boundary that owns diagnosis or recovery; add a new channel only when an operational requirement or project policy requires it - -## Criteria for Code Duplication - -Keep concrete implementations separate while their similarity is accidental or their UI ownership differs. Consolidate when repository evidence shows one shared interaction, validation rule, visual contract, or coordinated change responsibility. - -### Criteria for Commonalization - -**Cases for Commonalization** -- Business logic duplication -- Complex processing algorithms -- Component patterns (form fields, cards, etc.) -- Custom hooks -- Validation rules - -**Cases to Avoid Commonalization** -- Accidental matches (coincidentally same code) -- Possibility of evolving in different directions -- Significant readability decrease from commonalization -- Simple helpers in test code - -## Common Failure Patterns and Avoidance Methods - -### Pattern 1: Error Fix Chain -**Symptom**: Fixing one error causes new errors -**Cause**: Surface-level fixes without understanding root cause -**Avoidance**: Identify root cause with 5 Whys before fixing - -### Pattern 2: Circumventing Type Guarantees -**Symptom**: `any` or `as` declares a type that no check or contract establishes -**Cause**: Impulse to avoid type errors -**Avoidance**: Back the declared type with a check or an existing contract that guarantees it, at the boundary where that guarantee holds - -### Pattern 3: Implementation Without Sufficient Testing -**Symptom**: Many bugs after implementation -**Cause**: Accepted behavior left without a test that proves it -**Avoidance**: Prove each delivered behavior at the boundary where it is observed - -### Pattern 4: Building on Unverified Premises -**Symptom**: Dependent work fails, or workarounds accumulate, once an assumed premise proves false -**Cause**: Treating an assumed capability, behavior, or existing implementation as fact -**Avoidance**: When an unverified premise could invalidate the chosen approach, check it by the cheapest sufficient means before building dependent work on it. When results contradict the premise, reconsider the approach before patching its parts. Keep this reasoning in the active task; it needs no separate artifact. - -### Pattern 5: Insufficient Existing Code Investigation -**Symptom**: Duplicate implementations, architecture inconsistency, integration failures -**Cause**: Insufficient understanding of existing code before implementation -**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 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 - -## Quality Check Workflow - -Discover the repository's configured quality entry points and the categories they cover. Use the repository's declared package tooling and conventions and the categories below as the applicable evidence checklist. - -### Applicable Check Categories - -- **Lint/format** — the project's configured formatter and linter -- **Type check** — the project's configured type validation -- **Build** — the configured production or package build -- **Behavior checks** — the smallest configured tests that exercise the changed behavior, plus integration or E2E suites when the change crosses their boundary, a generated skeleton requires them, or the repository gate includes them - -Follow repository-declared command composition or ordering when it exists. Otherwise choose an order that respects command dependencies and provides useful feedback. Completion requires every applicable configured check to pass. - -### Troubleshooting -- **Port already in use** — stop the stale dev/preview/test process holding the port -- **Stale cache** — re-run with the project's fresh/clean-cache option -- **Dependency errors** — clean reinstall dependencies - -## Situations Requiring Technical Decisions - -### Timing of Abstraction -- Extract a shared abstraction after repository evidence establishes a shared UI responsibility and coordinated change pattern -- Be conscious of YAGNI, implement only currently needed features -- Prioritize current simplicity over future extensibility - -### Performance vs Readability -- Prioritize readability unless the project's performance budget or a React DevTools Profiler comparison identifies a meaningful bottleneck in the affected interaction -- Measure before optimizing with React DevTools Profiler -- Document reason with comments when optimizing - -### Granularity of Component/Type Definitions -- Overly detailed components/types reduce maintainability -- Design components that appropriately express UI patterns -- Use composition over inheritance - -## Implementation Completeness Assurance - -### Risk-Scaled Procedure for Impact Analysis - -**Completion Criteria**: Complete all 3 stages. Concise search/inspection notes are sufficient for an isolated component change with no shared contract, routing, state-ownership, or build/config impact; use the structured report for cross-component or high-risk changes. - -#### 1. Discovery -Search the repository for every reference to the changed component or hook, its imported functions, and its Props/State types. - -#### 2. Understanding -Read the discovered files needed to establish: -- Caller's purpose and context -- Component hierarchy -- Data flow: Props → State → Event handlers → Callbacks - -#### 3. Identification -For cross-component or high-risk changes, produce a structured impact report: -``` -## Impact Analysis -### Direct Impact: ComponentA, ComponentB (with reasons) -### Indirect Impact: FeatureX, PageY (with integration paths) -### Processing Flow: Props → Render → Events → Callbacks -``` - -Proceed when the accepted scope, consumers, state flow, required adjacent changes, and applicable checks are identified. - -### Unused Code Deletion Rule - -When the requested change makes a component, hook, utility, document, or configuration entry obsolete, delete it after checking its consumers and generated/operational use. Preserve and report uncertain or out-of-scope cleanup, and keep unrelated dormant code outside the implementation scope. - -### Existing Code Deletion Decision Flow - -``` -Required by the requested change? No → Preserve unless the change proves it obsolete - Yes → Working and compatible? Yes → Fix/extend - No → Repair or replace with migration/rollback evidence -``` diff --git a/skills/recipe-build/SKILL.md b/skills/recipe-build/SKILL.md index b0aadebb..14d4ca35 100644 --- a/skills/recipe-build/SKILL.md +++ b/skills/recipe-build/SKILL.md @@ -109,8 +109,8 @@ Before invoking post-implementation reviewers, apply subagents-orchestration-gui Resolve the Work Plan's readable Design Doc; missing input blocks review. -Emit these Agent calls in one assistant message, then await both: -- code-reviewer (subagent_type: "dev-workflows:code-reviewer") → review the completed implementation with the resolved `governingDocuments`, the actual files changed by completed tasks as `implementationFiles`, and the Work Plan path +Invoke the code-reviewer calls for the subagents-orchestration-guide Post-Implementation Review Units and one security-reviewer call, then await all: +- code-reviewer (subagent_type: "dev-workflows:code-reviewer") → one call per review unit with the resolved `governingDocuments`, the unit's changed files as `implementationFiles`, the unit's tasks as task scope, and the Work Plan path - security-reviewer (subagent_type: "dev-workflows:security-reviewer") → review the completed implementation against the same `governingDocuments` Apply subagents-orchestration-guide's Post-Implementation Review status-routing and fix/re-run rules. Present the unified report; proceed to Final Cleanup after the complete review set reaches Review Resolution convergence. diff --git a/skills/recipe-design/SKILL.md b/skills/recipe-design/SKILL.md index bd4032ab..9200baf2 100644 --- a/skills/recipe-design/SKILL.md +++ b/skills/recipe-design/SKILL.md @@ -63,7 +63,7 @@ This independent discovery keeps scope and option convergence grounded in reposi Execute Skill: requirement-convergence. The orchestrator builds and judges the convergence record from the user request and Step 2 evidence. -Judge all four convergence fields. Assign `cost` from Step 2 structural evidence and record its unknowns; run the hearing only for fields below `ready`. +Judge all four convergence fields by the rules in `references/criteria.md` of the requirement-convergence skill. Assign `cost` from Step 2 structural evidence and record its unknowns; run the hearing only for fields below `ready`. Determine Structural Scale from outcomes and responsibility boundaries. File count is supporting evidence only. diff --git a/skills/recipe-front-adjust/SKILL.md b/skills/recipe-front-adjust/SKILL.md index c6e4651d..f44aa004 100644 --- a/skills/recipe-front-adjust/SKILL.md +++ b/skills/recipe-front-adjust/SKILL.md @@ -91,7 +91,7 @@ Present the adjustment context to the user for review. ### Step 5: Adjustment + Verification (parent session) -Execute Skill: frontend-ai-guide before planning or applying adjustment edits. +Execute Skill: ai-development-guide and read its `references/frontend.md` before planning or applying adjustment edits. 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. diff --git a/skills/recipe-front-build/SKILL.md b/skills/recipe-front-build/SKILL.md index 3eb5ad9f..628b61f3 100644 --- a/skills/recipe-front-build/SKILL.md +++ b/skills/recipe-front-build/SKILL.md @@ -109,8 +109,8 @@ Before invoking post-implementation reviewers, apply subagents-orchestration-gui Resolve the Work Plan's readable Design Doc; missing input blocks review. -Emit these Agent calls in one assistant message, then await both: -- code-reviewer (subagent_type: "dev-workflows-frontend:code-reviewer") → review the completed implementation with the resolved `governingDocuments`, the actual files changed by completed tasks as `implementationFiles`, and the Work Plan path +Invoke the code-reviewer calls for the subagents-orchestration-guide Post-Implementation Review Units and one security-reviewer call, then await all: +- code-reviewer (subagent_type: "dev-workflows-frontend:code-reviewer") → one call per review unit with the resolved `governingDocuments`, the unit's changed files as `implementationFiles`, the unit's tasks as task scope, and the Work Plan path - security-reviewer (subagent_type: "dev-workflows-frontend:security-reviewer") → review the completed implementation against the same `governingDocuments` Apply subagents-orchestration-guide's Post-Implementation Review status-routing and fix/re-run rules. Present the unified report; proceed to Final Cleanup after the complete review set reaches Review Resolution convergence. diff --git a/skills/recipe-front-design/SKILL.md b/skills/recipe-front-design/SKILL.md index 24205264..87632225 100644 --- a/skills/recipe-front-design/SKILL.md +++ b/skills/recipe-front-design/SKILL.md @@ -83,7 +83,7 @@ external_resource_refs: [selected references or []] Execute Skill: requirement-convergence. Build and judge the convergence record from the governing requirement source, repository analysis, and applicable UI analysis. -Judge all four convergence fields. Assign `cost` from Step 2 structural evidence and record its unknowns; run the hearing only for fields below `ready`. +Judge all four convergence fields by the rules in `references/criteria.md` of the requirement-convergence skill. Assign `cost` from Step 2 structural evidence and record its unknowns; run the hearing only for fields below `ready`. 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. diff --git a/skills/recipe-front-review/SKILL.md b/skills/recipe-front-review/SKILL.md index 6fc502c2..e363bab3 100644 --- a/skills/recipe-front-review/SKILL.md +++ b/skills/recipe-front-review/SKILL.md @@ -76,9 +76,6 @@ Then present the adjudicated result to the user. Group `apply` findings by propo ``` Implementation Review: [verdict from code-reviewer] - Acceptance Criteria: - - [fulfilled] [item]: [evidence] - - [unfulfilled] [item] -> [corresponding finding ID under Required Corrections] Required Corrections: - [id] [category] [location]: [description] — [basis and effect] [recommended: c | d | d and c] Limitations: diff --git a/skills/recipe-fullstack-build/SKILL.md b/skills/recipe-fullstack-build/SKILL.md index fade5f3d..b84d1905 100644 --- a/skills/recipe-fullstack-build/SKILL.md +++ b/skills/recipe-fullstack-build/SKILL.md @@ -127,8 +127,8 @@ Before invoking post-implementation reviewers, apply subagents-orchestration-gui Resolve all readable Design Docs from the Work Plan, or the Work Plan itself when none exist; missing input blocks review. -Emit one code-reviewer call plus one security-reviewer call in one assistant message, then await both: -- code-reviewer (subagent_type: "dev-workflows:code-reviewer") → review the completed implementation with the resolved `governingDocuments` list, the actual files changed by completed tasks as `implementationFiles`, and the Work Plan path +Invoke the code-reviewer calls for the subagents-orchestration-guide Post-Implementation Review Units and one security-reviewer call, then await all: +- code-reviewer (subagent_type: "dev-workflows:code-reviewer") → one call per review unit with the resolved `governingDocuments` list, the unit's changed files as `implementationFiles`, the unit's tasks as task scope, and the Work Plan path - security-reviewer (subagent_type: "dev-workflows:security-reviewer") → review the completed implementation against the same `governingDocuments` list Apply subagents-orchestration-guide's Post-Implementation Review status-routing and fix/re-run rules. Present the unified report; proceed to Final Cleanup after the complete review set reaches Review Resolution convergence. diff --git a/skills/recipe-fullstack-implement/SKILL.md b/skills/recipe-fullstack-implement/SKILL.md index 7338352a..67f9ac6c 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 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. +Build and judge the convergence record by the rules in `references/criteria.md` of the requirement-convergence skill, 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. @@ -131,8 +131,8 @@ Apply subagents-orchestration-guide's retained verification limitation retry wit Resolve all readable Design Docs from the Work Plan, or the Work Plan itself when none exist; missing input blocks review. -Emit one code-reviewer call plus one security-reviewer call in one assistant message, then await both: -- code-reviewer (subagent_type: "dev-workflows:code-reviewer") → review the completed implementation with the resolved `governingDocuments` list, the actual files changed by completed tasks as `implementationFiles`, and the Work Plan path +Invoke the code-reviewer calls for the subagents-orchestration-guide Post-Implementation Review Units and one security-reviewer call, then await all: +- code-reviewer (subagent_type: "dev-workflows:code-reviewer") → one call per review unit with the resolved `governingDocuments` list, the unit's changed files as `implementationFiles`, the unit's tasks as task scope, and the Work Plan path - security-reviewer (subagent_type: "dev-workflows:security-reviewer") → review the completed implementation against the same `governingDocuments` list Apply subagents-orchestration-guide's Post-Implementation Review status-routing and fix/re-run rules. Present the unified report; proceed to Final Cleanup after the complete review set reaches Review Resolution convergence. diff --git a/skills/recipe-implement/SKILL.md b/skills/recipe-implement/SKILL.md index d1fcf62c..bfd829fd 100644 --- a/skills/recipe-implement/SKILL.md +++ b/skills/recipe-implement/SKILL.md @@ -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 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. +Build and judge the convergence record by the rules in `references/criteria.md` of the requirement-convergence skill, 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. @@ -119,8 +119,8 @@ Apply subagents-orchestration-guide's retained verification limitation retry bef Resolve the Work Plan's readable Design Doc; missing input blocks review. -Emit these Agent calls in one assistant message, then await both: -- code-reviewer (subagent_type: "dev-workflows:code-reviewer") → review the completed implementation with the resolved `governingDocuments`, the actual files changed by completed tasks as `implementationFiles`, and the Work Plan path +Invoke the code-reviewer calls for the subagents-orchestration-guide Post-Implementation Review Units and one security-reviewer call, then await all: +- code-reviewer (subagent_type: "dev-workflows:code-reviewer") → one call per review unit with the resolved `governingDocuments`, the unit's changed files as `implementationFiles`, the unit's tasks as task scope, and the Work Plan path - security-reviewer (subagent_type: "dev-workflows:security-reviewer") → review the completed implementation against the same `governingDocuments` Apply subagents-orchestration-guide's Post-Implementation Review status-routing and fix/re-run rules. Present the unified report; proceed to Final Cleanup after the complete review set reaches Review Resolution convergence. diff --git a/skills/recipe-review/SKILL.md b/skills/recipe-review/SKILL.md index eec33915..b95c562b 100644 --- a/skills/recipe-review/SKILL.md +++ b/skills/recipe-review/SKILL.md @@ -76,9 +76,6 @@ Then present the adjudicated result to the user. Group `apply` findings by propo ``` Implementation Review: [verdict from code-reviewer] - Acceptance Criteria: - - [fulfilled] [item]: [evidence] - - [unfulfilled] [item] -> [corresponding finding ID under Required Corrections] Required Corrections: - [id] [category] [location]: [description] — [basis and effect] [recommended: c | d | d and c] Limitations: diff --git a/skills/subagents-orchestration-guide/SKILL.md b/skills/subagents-orchestration-guide/SKILL.md index 38f28531..887356c6 100644 --- a/skills/subagents-orchestration-guide/SKILL.md +++ b/skills/subagents-orchestration-guide/SKILL.md @@ -196,6 +196,10 @@ graph TD For Small, execute one direct-scope 4-step cycle. Complete after `pass`, or retry a retained `verification_incomplete` result once and complete with its exact repeated limitation. Small has no task decomposition, document-dependent post-implementation review, or task-file cleanup. +### Post-Implementation Review Units (Medium/Large) + +Review a Medium change with one code-reviewer. A Large change is more than one code-reviewer can read in full; partition it into units of Work Plan tasks. A unit holds a consuming task (one delivering a screen, route, command, or job) together with the tasks it depends on through `Depends on`, so a contract's producer, its consumer, and every test proving their behavior are reviewed together; tasks that several units depend on form one shared unit. Each completed task belongs to one unit, whose `implementationFiles` are the files changed by its tasks' commits. Run at most 3 reviewer calls concurrently. security-reviewer reviews the complete change once. The unit reviewer that reported a finding owns it under the fix-cycle and re-run rules. + ### Post-Implementation Review Status Routing (Medium/Large) | Reviewer | Complete: empty finding set | Enter Review Resolution | Blocked | diff --git a/skills/testing-principles/SKILL.md b/skills/testing-principles/SKILL.md index 72579f85..afafb806 100644 --- a/skills/testing-principles/SKILL.md +++ b/skills/testing-principles/SKILL.md @@ -1,6 +1,6 @@ --- name: testing-principles -description: Language-agnostic testing principles for choosing which tests a change needs, test quality, and proof ownership, with frontend and browser E2E implementation references. Use when writing tests, deciding test scope, or reviewing test quality. +description: Language-agnostic testing principles for choosing which tests a change needs, test quality, and proof ownership, including frontend and browser E2E tests. Use when writing tests, deciding test scope, or reviewing test quality. --- # Language-Agnostic Testing Principles From d3a35547e3aaa06d7266375df4444d92ed68bd8f Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Fri, 6 Nov 2026 12:59:24 +0900 Subject: [PATCH 2/3] Bump version to 0.30.0 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 ee938996..f844bdfc 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.6", + "version": "0.30.0", "description": "Skills + Subagents for backend development - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", "author": { "name": "Shinsuke Kagawa", @@ -80,7 +80,7 @@ "name": "dev-workflows-frontend", "source": "./dev-workflows-frontend", "strict": true, - "version": "0.29.6", + "version": "0.30.0", "description": "Skills + Subagents for React/TypeScript - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", "author": { "name": "Shinsuke Kagawa", @@ -148,7 +148,7 @@ "name": "dev-workflows-fullstack", "source": "./dev-workflows-fullstack", "strict": true, - "version": "0.29.6", + "version": "0.30.0", "description": "Skills + Subagents for fullstack development (backend + React/TypeScript) - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", "author": { "name": "Shinsuke Kagawa", @@ -233,7 +233,7 @@ "name": "dev-skills", "source": "./dev-skills", "strict": true, - "version": "0.29.6", + "version": "0.30.0", "description": "Lightweight skills for users with existing workflows - coding best practices, testing principles, and design guidelines without recipe workflows or agents", "author": { "name": "Shinsuke Kagawa", diff --git a/dev-skills/.claude-plugin/plugin.json b/dev-skills/.claude-plugin/plugin.json index 8c68fa51..4510355b 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.6", + "version": "0.30.0", "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 bf75a940..69db6218 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.6", + "version": "0.30.0", "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 b78012ff..a9b7acb5 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.6", + "version": "0.30.0", "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 086a9075..68036dae 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.6", + "version": "0.30.0", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/package.json b/package.json index 29e26b7f..b0076034 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "claude-code-workflows", - "version": "0.29.6", + "version": "0.30.0", "private": true, "type": "module", "engines": { From 0612439dd795264e04a9ec75700c0f0a3f18c33e Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Fri, 6 Nov 2026 13:15:40 +0900 Subject: [PATCH 3/3] Check task completion criteria instead of syncing progress checkboxes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Remove the task executors' rule that synced [ ], [🔄], and [x] across the task file, Work Plan, and Design Doc - Add a final gate item: for task-file execution, each Completion Criteria item in the task file is satisfied with evidence in the response Co-Authored-By: Claude Opus 5.5 --- agents/task-executor-frontend.md | 6 +++--- agents/task-executor.md | 6 +++--- dev-workflows-frontend/agents/task-executor-frontend.md | 6 +++--- dev-workflows-fullstack/agents/task-executor-frontend.md | 6 +++--- dev-workflows-fullstack/agents/task-executor.md | 6 +++--- dev-workflows/agents/task-executor.md | 6 +++--- 6 files changed, 18 insertions(+), 18 deletions(-) diff --git a/agents/task-executor-frontend.md b/agents/task-executor-frontend.md index 6cf85ac8..6fba977f 100644 --- a/agents/task-executor-frontend.md +++ b/agents/task-executor-frontend.md @@ -93,13 +93,12 @@ Any YES is corrected in implementation when the value boundary can remain true. **Scope**: React component implementation and test creation. Quality checks and commits are outside scope. **Policy**: Start implementation immediately (treat as approved). -**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 ### 1. Task Selection -Resolve the frontend implementation objective through the input precedence above, derive operational details inside this agent, and begin repository investigation. Completed task checkboxes guide continuation; confirm the outcome against the current repository state and applicable verification evidence before returning an existing completed result. +Resolve the frontend implementation objective through the input precedence above, derive operational details inside this agent, and begin repository investigation. Confirm the outcome against the current repository state and applicable verification evidence before returning an existing completed result. ### 2. Task Background Understanding @@ -156,7 +155,7 @@ Apply coding-principles Reference Representativeness using the changed area and #### Implementation Flow **When the outcome is already satisfied**: Preserve the implementation and proceed to Operation Verification before reporting completion. -Implement the behaviors the task delivers and prove them under testing-principles and the task's Operation Verification Methods. Before writing component, hook, or UI integration tests, read `references/frontend.md` in the testing-principles skill, and before writing browser E2E tests, `references/e2e.md`; they define the scope and ownership criteria for those tests. Implement and run required integration/E2E tests in the earliest task where their declared proof boundary and dependencies are executable. Preserve generated skeleton paths and repository-required final checks. Apply the Responsibility Boundaries progress rule after verification. +Implement the behaviors the task delivers and prove them under testing-principles and the task's Operation Verification Methods. Before writing component, hook, or UI integration tests, read `references/frontend.md` in the testing-principles skill, and before writing browser E2E tests, `references/e2e.md`; they define the scope and ownership criteria for those tests. Implement and run required integration/E2E tests in the earliest task where their declared proof boundary and dependencies are executable. Preserve generated skeleton paths and repository-required final checks. #### Operation Verification - Execute the Operation Verification Methods in the execution instructions @@ -231,6 +230,7 @@ Use this response when evidence establishes either authoritative escalation cond This gate runs immediately before producing the final JSON response. ☐ All implementation items completed with evidence, or the response reports exact incomplete work or proves one authoritative escalation condition +☐ For task-file execution, each Completion Criteria item in the task file is satisfied, with its evidence in the response ☐ Implementation is consistent with the governing sources and investigation evidence ☐ Adjacent Case Sweep evidence records each inspected case and disposition, or the searched surface and no-case result, when the current task triggers the sweep ☐ `reuseDecisions` records decision-relevant similar components or hooks and its evidence-backed reuse, extend, or separate disposition diff --git a/agents/task-executor.md b/agents/task-executor.md index fd696e45..ffc23b25 100644 --- a/agents/task-executor.md +++ b/agents/task-executor.md @@ -88,13 +88,12 @@ Any YES is corrected in implementation when the value boundary can remain true. **Scope**: Implementation and test creation. Quality checks and commits are outside scope. **Policy**: Start implementation immediately (treat as approved). -**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 ### 1. Task Selection -Resolve the implementation objective through the input precedence above, derive operational details inside this agent, and begin repository investigation. Completed task checkboxes guide continuation; confirm the outcome against the current repository state and applicable verification evidence before returning an existing completed result. +Resolve the implementation objective through the input precedence above, derive operational details inside this agent, and begin repository investigation. Confirm the outcome against the current repository state and applicable verification evidence before returning an existing completed result. ### 2. Task Background Understanding @@ -152,7 +151,7 @@ Apply coding-principles Reference Representativeness using the changed area and **When the outcome is already satisfied**: Preserve the implementation and proceed to Operation Verification before reporting completion. -Implement the behaviors the task delivers and prove them under testing-principles and the task's Operation Verification Methods. Before writing browser E2E tests, read `references/e2e.md` in the testing-principles skill; it defines the scope and ownership criteria for those tests. Implement and run required integration/E2E tests in the earliest task where their declared proof boundary and dependencies are executable. Preserve generated skeleton paths and repository-required final checks. Apply the Responsibility Boundaries progress rule after verification. +Implement the behaviors the task delivers and prove them under testing-principles and the task's Operation Verification Methods. Before writing browser E2E tests, read `references/e2e.md` in the testing-principles skill; it defines the scope and ownership criteria for those tests. Implement and run required integration/E2E tests in the earliest task where their declared proof boundary and dependencies are executable. Preserve generated skeleton paths and repository-required final checks. #### Operation Verification - Execute the Operation Verification Methods in the execution instructions @@ -227,6 +226,7 @@ Use this response when evidence establishes either authoritative escalation cond This gate runs immediately before producing the final JSON response. ☐ All implementation items completed with evidence, or the response reports exact incomplete work or proves one authoritative escalation condition +☐ For task-file execution, each Completion Criteria item in the task file is satisfied, with its evidence in the response ☐ Implementation is consistent with the governing sources and investigation evidence ☐ Adjacent Case Sweep evidence records each inspected case and disposition, or the searched surface and no-case result, when the current task triggers the sweep ☐ `reuseDecisions` records decision-relevant similar implementations and its evidence-backed reuse, extend, or separate disposition diff --git a/dev-workflows-frontend/agents/task-executor-frontend.md b/dev-workflows-frontend/agents/task-executor-frontend.md index 6cf85ac8..6fba977f 100644 --- a/dev-workflows-frontend/agents/task-executor-frontend.md +++ b/dev-workflows-frontend/agents/task-executor-frontend.md @@ -93,13 +93,12 @@ Any YES is corrected in implementation when the value boundary can remain true. **Scope**: React component implementation and test creation. Quality checks and commits are outside scope. **Policy**: Start implementation immediately (treat as approved). -**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 ### 1. Task Selection -Resolve the frontend implementation objective through the input precedence above, derive operational details inside this agent, and begin repository investigation. Completed task checkboxes guide continuation; confirm the outcome against the current repository state and applicable verification evidence before returning an existing completed result. +Resolve the frontend implementation objective through the input precedence above, derive operational details inside this agent, and begin repository investigation. Confirm the outcome against the current repository state and applicable verification evidence before returning an existing completed result. ### 2. Task Background Understanding @@ -156,7 +155,7 @@ Apply coding-principles Reference Representativeness using the changed area and #### Implementation Flow **When the outcome is already satisfied**: Preserve the implementation and proceed to Operation Verification before reporting completion. -Implement the behaviors the task delivers and prove them under testing-principles and the task's Operation Verification Methods. Before writing component, hook, or UI integration tests, read `references/frontend.md` in the testing-principles skill, and before writing browser E2E tests, `references/e2e.md`; they define the scope and ownership criteria for those tests. Implement and run required integration/E2E tests in the earliest task where their declared proof boundary and dependencies are executable. Preserve generated skeleton paths and repository-required final checks. Apply the Responsibility Boundaries progress rule after verification. +Implement the behaviors the task delivers and prove them under testing-principles and the task's Operation Verification Methods. Before writing component, hook, or UI integration tests, read `references/frontend.md` in the testing-principles skill, and before writing browser E2E tests, `references/e2e.md`; they define the scope and ownership criteria for those tests. Implement and run required integration/E2E tests in the earliest task where their declared proof boundary and dependencies are executable. Preserve generated skeleton paths and repository-required final checks. #### Operation Verification - Execute the Operation Verification Methods in the execution instructions @@ -231,6 +230,7 @@ Use this response when evidence establishes either authoritative escalation cond This gate runs immediately before producing the final JSON response. ☐ All implementation items completed with evidence, or the response reports exact incomplete work or proves one authoritative escalation condition +☐ For task-file execution, each Completion Criteria item in the task file is satisfied, with its evidence in the response ☐ Implementation is consistent with the governing sources and investigation evidence ☐ Adjacent Case Sweep evidence records each inspected case and disposition, or the searched surface and no-case result, when the current task triggers the sweep ☐ `reuseDecisions` records decision-relevant similar components or hooks and its evidence-backed reuse, extend, or separate disposition diff --git a/dev-workflows-fullstack/agents/task-executor-frontend.md b/dev-workflows-fullstack/agents/task-executor-frontend.md index 6cf85ac8..6fba977f 100644 --- a/dev-workflows-fullstack/agents/task-executor-frontend.md +++ b/dev-workflows-fullstack/agents/task-executor-frontend.md @@ -93,13 +93,12 @@ Any YES is corrected in implementation when the value boundary can remain true. **Scope**: React component implementation and test creation. Quality checks and commits are outside scope. **Policy**: Start implementation immediately (treat as approved). -**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 ### 1. Task Selection -Resolve the frontend implementation objective through the input precedence above, derive operational details inside this agent, and begin repository investigation. Completed task checkboxes guide continuation; confirm the outcome against the current repository state and applicable verification evidence before returning an existing completed result. +Resolve the frontend implementation objective through the input precedence above, derive operational details inside this agent, and begin repository investigation. Confirm the outcome against the current repository state and applicable verification evidence before returning an existing completed result. ### 2. Task Background Understanding @@ -156,7 +155,7 @@ Apply coding-principles Reference Representativeness using the changed area and #### Implementation Flow **When the outcome is already satisfied**: Preserve the implementation and proceed to Operation Verification before reporting completion. -Implement the behaviors the task delivers and prove them under testing-principles and the task's Operation Verification Methods. Before writing component, hook, or UI integration tests, read `references/frontend.md` in the testing-principles skill, and before writing browser E2E tests, `references/e2e.md`; they define the scope and ownership criteria for those tests. Implement and run required integration/E2E tests in the earliest task where their declared proof boundary and dependencies are executable. Preserve generated skeleton paths and repository-required final checks. Apply the Responsibility Boundaries progress rule after verification. +Implement the behaviors the task delivers and prove them under testing-principles and the task's Operation Verification Methods. Before writing component, hook, or UI integration tests, read `references/frontend.md` in the testing-principles skill, and before writing browser E2E tests, `references/e2e.md`; they define the scope and ownership criteria for those tests. Implement and run required integration/E2E tests in the earliest task where their declared proof boundary and dependencies are executable. Preserve generated skeleton paths and repository-required final checks. #### Operation Verification - Execute the Operation Verification Methods in the execution instructions @@ -231,6 +230,7 @@ Use this response when evidence establishes either authoritative escalation cond This gate runs immediately before producing the final JSON response. ☐ All implementation items completed with evidence, or the response reports exact incomplete work or proves one authoritative escalation condition +☐ For task-file execution, each Completion Criteria item in the task file is satisfied, with its evidence in the response ☐ Implementation is consistent with the governing sources and investigation evidence ☐ Adjacent Case Sweep evidence records each inspected case and disposition, or the searched surface and no-case result, when the current task triggers the sweep ☐ `reuseDecisions` records decision-relevant similar components or hooks and its evidence-backed reuse, extend, or separate disposition diff --git a/dev-workflows-fullstack/agents/task-executor.md b/dev-workflows-fullstack/agents/task-executor.md index fd696e45..ffc23b25 100644 --- a/dev-workflows-fullstack/agents/task-executor.md +++ b/dev-workflows-fullstack/agents/task-executor.md @@ -88,13 +88,12 @@ Any YES is corrected in implementation when the value boundary can remain true. **Scope**: Implementation and test creation. Quality checks and commits are outside scope. **Policy**: Start implementation immediately (treat as approved). -**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 ### 1. Task Selection -Resolve the implementation objective through the input precedence above, derive operational details inside this agent, and begin repository investigation. Completed task checkboxes guide continuation; confirm the outcome against the current repository state and applicable verification evidence before returning an existing completed result. +Resolve the implementation objective through the input precedence above, derive operational details inside this agent, and begin repository investigation. Confirm the outcome against the current repository state and applicable verification evidence before returning an existing completed result. ### 2. Task Background Understanding @@ -152,7 +151,7 @@ Apply coding-principles Reference Representativeness using the changed area and **When the outcome is already satisfied**: Preserve the implementation and proceed to Operation Verification before reporting completion. -Implement the behaviors the task delivers and prove them under testing-principles and the task's Operation Verification Methods. Before writing browser E2E tests, read `references/e2e.md` in the testing-principles skill; it defines the scope and ownership criteria for those tests. Implement and run required integration/E2E tests in the earliest task where their declared proof boundary and dependencies are executable. Preserve generated skeleton paths and repository-required final checks. Apply the Responsibility Boundaries progress rule after verification. +Implement the behaviors the task delivers and prove them under testing-principles and the task's Operation Verification Methods. Before writing browser E2E tests, read `references/e2e.md` in the testing-principles skill; it defines the scope and ownership criteria for those tests. Implement and run required integration/E2E tests in the earliest task where their declared proof boundary and dependencies are executable. Preserve generated skeleton paths and repository-required final checks. #### Operation Verification - Execute the Operation Verification Methods in the execution instructions @@ -227,6 +226,7 @@ Use this response when evidence establishes either authoritative escalation cond This gate runs immediately before producing the final JSON response. ☐ All implementation items completed with evidence, or the response reports exact incomplete work or proves one authoritative escalation condition +☐ For task-file execution, each Completion Criteria item in the task file is satisfied, with its evidence in the response ☐ Implementation is consistent with the governing sources and investigation evidence ☐ Adjacent Case Sweep evidence records each inspected case and disposition, or the searched surface and no-case result, when the current task triggers the sweep ☐ `reuseDecisions` records decision-relevant similar implementations and its evidence-backed reuse, extend, or separate disposition diff --git a/dev-workflows/agents/task-executor.md b/dev-workflows/agents/task-executor.md index fd696e45..ffc23b25 100644 --- a/dev-workflows/agents/task-executor.md +++ b/dev-workflows/agents/task-executor.md @@ -88,13 +88,12 @@ Any YES is corrected in implementation when the value boundary can remain true. **Scope**: Implementation and test creation. Quality checks and commits are outside scope. **Policy**: Start implementation immediately (treat as approved). -**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 ### 1. Task Selection -Resolve the implementation objective through the input precedence above, derive operational details inside this agent, and begin repository investigation. Completed task checkboxes guide continuation; confirm the outcome against the current repository state and applicable verification evidence before returning an existing completed result. +Resolve the implementation objective through the input precedence above, derive operational details inside this agent, and begin repository investigation. Confirm the outcome against the current repository state and applicable verification evidence before returning an existing completed result. ### 2. Task Background Understanding @@ -152,7 +151,7 @@ Apply coding-principles Reference Representativeness using the changed area and **When the outcome is already satisfied**: Preserve the implementation and proceed to Operation Verification before reporting completion. -Implement the behaviors the task delivers and prove them under testing-principles and the task's Operation Verification Methods. Before writing browser E2E tests, read `references/e2e.md` in the testing-principles skill; it defines the scope and ownership criteria for those tests. Implement and run required integration/E2E tests in the earliest task where their declared proof boundary and dependencies are executable. Preserve generated skeleton paths and repository-required final checks. Apply the Responsibility Boundaries progress rule after verification. +Implement the behaviors the task delivers and prove them under testing-principles and the task's Operation Verification Methods. Before writing browser E2E tests, read `references/e2e.md` in the testing-principles skill; it defines the scope and ownership criteria for those tests. Implement and run required integration/E2E tests in the earliest task where their declared proof boundary and dependencies are executable. Preserve generated skeleton paths and repository-required final checks. #### Operation Verification - Execute the Operation Verification Methods in the execution instructions @@ -227,6 +226,7 @@ Use this response when evidence establishes either authoritative escalation cond This gate runs immediately before producing the final JSON response. ☐ All implementation items completed with evidence, or the response reports exact incomplete work or proves one authoritative escalation condition +☐ For task-file execution, each Completion Criteria item in the task file is satisfied, with its evidence in the response ☐ Implementation is consistent with the governing sources and investigation evidence ☐ Adjacent Case Sweep evidence records each inspected case and disposition, or the searched surface and no-case result, when the current task triggers the sweep ☐ `reuseDecisions` records decision-relevant similar implementations and its evidence-backed reuse, extend, or separate disposition