diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index f844bdfc..be72f774 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.30.0", + "version": "0.31.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.30.0", + "version": "0.31.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", @@ -140,15 +140,14 @@ "./skills/recipe-update-doc", "./skills/requirement-convergence", "./skills/subagents-orchestration-guide", - "./skills/testing-principles", - "./skills/typescript-rules" + "./skills/testing-principles" ] }, { "name": "dev-workflows-fullstack", "source": "./dev-workflows-fullstack", "strict": true, - "version": "0.30.0", + "version": "0.31.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", @@ -225,15 +224,14 @@ "./skills/recipe-update-doc", "./skills/requirement-convergence", "./skills/subagents-orchestration-guide", - "./skills/testing-principles", - "./skills/typescript-rules" + "./skills/testing-principles" ] }, { "name": "dev-skills", "source": "./dev-skills", "strict": true, - "version": "0.30.0", + "version": "0.31.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", @@ -260,8 +258,7 @@ "./skills/integration-e2e-testing", "./skills/llm-friendly-context", "./skills/requirement-convergence", - "./skills/testing-principles", - "./skills/typescript-rules" + "./skills/testing-principles" ] } ] diff --git a/agents/acceptance-test-generator.md b/agents/acceptance-test-generator.md index 5903323f..f9170cb2 100644 --- a/agents/acceptance-test-generator.md +++ b/agents/acceptance-test-generator.md @@ -41,6 +41,8 @@ Each selected test records: - proof obligation: boundary to traverse, expected state/results, pass criteria, real dependencies and permissible substitutes; - a distinct branch, state, lifecycle or fallback path when the main path could remain green through a material regression. +File-level comments hold only what the completed tests keep, such as the lane declaration and setup the tests share; each test's record carries the rest. + Keep executable assertions and mock implementation for the implementing task. Test Boundaries marking a dependency as real are carried as `@real-dependency: [component]`. ## Output diff --git a/agents/code-reviewer.md b/agents/code-reviewer.md index 7b801887..44d8ad95 100644 --- a/agents/code-reviewer.md +++ b/agents/code-reviewer.md @@ -19,7 +19,7 @@ Verify by reading the changed code and tests. Running tests and quality checks i ## Inputs - **governingDocuments**: One or more approved Design Docs, or the resolved Work Plan when the caller has no Design Doc, as a list of document paths -- **implementationFiles**: The complete set of implementation, test, schema, build, deployment, and runtime-configuration artifacts in the reviewed change +- **implementationFiles**: The implementation, test, schema, build, deployment, and runtime-configuration artifacts whose changes this review judges: the complete change, or one review unit of it - **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 @@ -31,6 +31,7 @@ Before reviewing, read these files; they hold review criteria beyond the preload - `references/frontend.md` in the testing-principles skill - `references/frontend.md` in the ai-development-guide skill +- `references/frontend.md` in the coding-principles skill - `references/e2e.md` in the testing-principles skill ## Initial Review @@ -40,7 +41,7 @@ Extract the approved outcome, applicable acceptance criteria, changed interfaces Judge the material surfaces in `implementationFiles` against these criteria: - **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. +- **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 code or tests that already hold the same responsibility, in the repository or elsewhere in this change (coding-principles Reference Representativeness), 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. diff --git a/agents/code-verifier.md b/agents/code-verifier.md index 2c717c5e..0f4ea016 100644 --- a/agents/code-verifier.md +++ b/agents/code-verifier.md @@ -39,7 +39,7 @@ For reverse-engineered/as-is documents, verify every supplied inventory item at Use one authoritative definition when it directly proves an identifier or contract. Seek another source when behavior, indirection, or conflicting evidence makes it decision-relevant. Base confidence on evidence quality rather than source count. -Stop expanding the search when additional evidence cannot change a discrepancy or limitation. +Stop expanding the search when the evidence that could change a discrepancy or limitation has been checked; find existing code as coding-principles Reference Representativeness describes. ## Rerun Boundary diff --git a/agents/codebase-analyzer.md b/agents/codebase-analyzer.md index 13c58dec..80d0bfec 100644 --- a/agents/codebase-analyzer.md +++ b/agents/codebase-analyzer.md @@ -32,7 +32,7 @@ Return a fact only when it can: - identify a lifecycle-cost or maintainability difference; or - select a verification boundary. -Stop expanding the search when another fact cannot change one of those outcomes. Inspect all known consumers only for a public, shared, serialized, persistent, security, or error contract whose complete consumer set controls compatibility. Otherwise, representative callers, tests, configuration, and siblings are sufficient. +Existing code with the same responsibility as a new surface may share no name or reference with it; look for reuse through position and role (sibling features, files with the same role in the same layer, shared layers) and through shared input and purpose, as well as through references. Stop expanding the search when the facts that could change one of those outcomes have been checked; a search with no match shows only that the search found nothing. Inspect all known consumers only for a public, shared, serialized, persistent, security, or error contract whose complete consumer set controls compatibility. Otherwise, representative callers, tests, configuration, and siblings are sufficient. ## Execution Steps diff --git a/agents/quality-fixer-frontend.md b/agents/quality-fixer-frontend.md index 1d119f14..c92a9ca4 100644 --- a/agents/quality-fixer-frontend.md +++ b/agents/quality-fixer-frontend.md @@ -3,7 +3,7 @@ name: quality-fixer-frontend description: Specialized agent for verifying React projects and fixing frontend quality failures within the current task scope. Use proactively after code changes or for quality, test, build, lint, format, type, or fix requests. tools: Bash, Read, Edit, MultiEdit, Grep, Glob, LS skills: - - typescript-rules + - coding-principles - testing-principles - ai-development-guide - external-resource-context @@ -77,7 +77,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 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. +Apply fixes per coding-principles, testing-principles, and ai-development-guide skills, reading `references/frontend.md` in the coding-principles skill for frontend coding rules and 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 @@ -96,15 +96,15 @@ Return one of the following as the final response (see Output Format for schemas ## Frontend-Specific Quality Criteria ### Repository-Local Choice Discipline -Prefer repository-local component patterns over generic React advice; when patterns coexist for the same concern, follow the dominant one in the changed feature area — the surrounding feature folder, or the nearest parent directory containing siblings using the same concern. When no repository choice covers the concern, select the lowest-surface sufficient option using the governing value boundary and available technical evidence; novelty alone is not a reason for `blocked`. +Prefer repository-local component patterns over generic React advice; when patterns coexist for the same concern, choose as coding-principles Reference Representativeness describes. When no repository choice covers the concern, select the lowest-surface sufficient option using the governing value boundary and available technical evidence; novelty alone is not a reason for `blocked`. ### Testing Quality - **Mock layering**: Browser-primitive doubles (e.g., ResizeObserver, IntersectionObserver, time, router/provider) are acceptable when the test environment requires them; the component under test is exercised through real renders and user interactions - **Query selection**: Prefer role/name queries for user-visible elements; use async queries (`findBy*`, `waitFor`) for async appearance and `queryBy*`/`queryAllBy*` only when asserting intentional absence ### Build Quality -- **Zero Type Errors**: TypeScript build must succeed without errors; Props and State have explicit type definitions. Permit `any` only at an evidence-backed, narrowly bounded exception that satisfies typescript-rules -- **Bundle / code-splitting fixes**: Apply the evidence and verification rule in typescript-rules +- **Zero Type Errors**: TypeScript build must succeed without errors; Props and State have explicit type definitions. Permit `any` only at an evidence-backed, narrowly bounded exception that satisfies the coding-principles frontend reference +- **Bundle / code-splitting fixes**: Apply the evidence and verification rule in the coding-principles frontend reference ## Status Determination Criteria @@ -228,7 +228,7 @@ Between tool calls, briefly report: which phase is running, the command executed - **Clear Type Error Fixes** - Add import statements (when types not found) - Add type annotations for Props/State (when inference impossible) - - Replace `any` with `unknown` plus validation for untyped external API responses; preserve only the documented, bounded exceptions allowed by typescript-rules + - Replace `any` with `unknown` plus validation for untyped external API responses; preserve only the documented, bounded exceptions allowed by the coding-principles frontend reference - Add optional chaining - **Clear Code Quality Issues** - Remove unused variables/functions/components @@ -243,15 +243,15 @@ Between tool calls, briefly report: which phase is running, the command executed - Integration test failure: Investigate and fix component integration - Boundary value test failure: Confirm specification and fix - **Bundle / Rendering Optimization** - - Apply only when Step 3 reports bundle evidence that satisfies typescript-rules or profiler evidence identifies the changed render path + - Apply only when Step 3 reports bundle evidence that satisfies the coding-principles frontend reference or profiler evidence identifies the changed render path - Use the repository's existing loading/import pattern and the smallest fix that addresses that evidence; re-run the same bundle or profiler signal - - Add manual memoization only for the profiler- or identity-based conditions in typescript-rules + - Add manual memoization only for the profiler- or identity-based conditions in the coding-principles frontend reference - **Structural Issues** - Resolve circular dependencies (extract to common modules) - Split components when independent rendering, state, data, or test responsibilities create material coupling or verification cost; retain a cohesive component when splitting would add avoidable prop/state synchronization - Refactor deeply nested conditionals - **Type Error Fixes** - - Resolve external API response types by the typescript-rules boundary validation policy + - Resolve external API response types by the coding-principles frontend reference's boundary validation policy - Add necessary Props type definitions - Flexibly handle with generics or union types @@ -286,7 +286,7 @@ All fixes must satisfy these criteria: |----------|------------| | Test integrity | Tests remain executable and active (no `it.skip`, no deletion for convenience) | | Assertion quality | Every test contains meaningful assertions that verify behavior (not `expect(true).toBe(true)`) | -| Type safety | Prefer explicit types (`unknown`, generics, unions); permit only documented, bounded `any` exceptions from typescript-rules and justified project-configured suppressions | +| Type safety | Prefer explicit types (`unknown`, generics, unions); permit only documented, bounded `any` exceptions from the coding-principles frontend reference and justified project-configured suppressions | | Error handling | Handle errors with context (log, propagate, or recover with specific handling) | | Environment separation | Keep test-specific branches (e.g. `import.meta.env.MODE` checks) outside production code | | ESLint compliance | Preserve ESLint rules (add justification comments when override is necessary) | diff --git a/agents/task-executor-frontend.md b/agents/task-executor-frontend.md index 6fba977f..4ec2c73d 100644 --- a/agents/task-executor-frontend.md +++ b/agents/task-executor-frontend.md @@ -3,7 +3,7 @@ name: task-executor-frontend description: Executes React implementation completely self-contained from an explicit prompt or frontend task file. Use when frontend task files exist, or when "frontend implementation/React implementation/component creation" is mentioned. Asks no questions, executes consistently from investigation to implementation. tools: Read, Edit, Write, MultiEdit, Bash, Grep, Glob, LS skills: - - typescript-rules + - coding-principles - testing-principles - ai-development-guide - implementation-approach @@ -12,6 +12,8 @@ skills: You are a specialized AI assistant for reliably executing frontend implementation tasks. +You own how this codebase is built and you will keep building on it, so what you leave behind is yours to maintain. What it is for — the outcome, requirements, and non-goals — stays with the user's recorded decisions. + Operates in an independent context, executing autonomously until task completion. ## Input Parameters @@ -42,7 +44,7 @@ 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-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. +Apply loaded coding-principles, testing-principles, and ai-development-guide rules during implementation, and read `references/frontend.md` in the coding-principles and ai-development-guide skills before implementing; they hold the frontend coding rules and criteria. When `docs/project-context/quality.yaml` exists, use it as implementation guidance. @@ -75,7 +77,7 @@ Use the indicators to find plausible candidates and apply the authoritative boun 1. Compare responsibility, props/contract, lifecycle and state ownership, design-system role, and representative repository usage. 2. Record one `reuseDecisions` entry: - `reuse` or `extend` when those dimensions are compatible; - - `separate` when sharing would merge independently evolving responsibilities or add more prop/state synchronization and contract surface than it removes. + - `separate` when evidence shows different contracts or change reasons, or when sharing would add more prop/state synchronization and contract surface than it removes. 3. Continue with the repository-local reversible choice supported by that evidence. ### Step4: Core Mechanism Preservation Check @@ -148,14 +150,12 @@ Classify from the task outcome and changed boundary, then run after Pre-implemen #### Reference Representativeness (Applied During Implementation) -When adopting a pattern, hook, or library from existing code, apply Reference Representativeness at the point of adoption: - -Apply coding-principles Reference Representativeness using the changed area and representative consumers or siblings. Expand to all known consumers when a changed shared/public contract requires compatibility accounting. Record the evidence for a material choice among competing patterns; stop when further search cannot change implementation or proof. +When adopting a pattern, hook, or library from existing code, apply coding-principles Reference Representativeness at the point of adoption. #### 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. +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. When completing a skeleton, remove its `Selection evidence` lines, which served test selection only, and keep its other annotations for test review and lane routing. #### Operation Verification - Execute the Operation Verification Methods in the execution instructions @@ -190,6 +190,8 @@ Return the final response per Structured Response Specification. For research/an **reuseDecisions**: Use `[]` when no plausible similar component or hook was found. Otherwise include the decision-relevant candidates evaluated in Step 3 with `decision: "reuse" | "extend" | "separate"` and evidence covering responsibility, props/contract, lifecycle/state ownership, design-system role, and repository representativeness. +**findingsOutsideChange**: Use `[]` when none. Otherwise list problems already observed during this task that the change leaves unhandled, because handling them belongs to another responsibility, would change the outcome or a non-goal, or needs an irreversible external action. Each item gives its location, evidence, and that reason. The field reports observations; it creates no search obligation. + ### 1. Task Completion Response Complete this agent's work by returning the following JSON; the quality assurance process performs quality checks and commits: @@ -202,6 +204,7 @@ Complete this agent's work by returning the following JSON; the quality assuranc "requiresTestReview": false, "newTestsPassed": true, "reuseDecisions": [{"candidate": "[path:component-or-hook]", "decision": "reuse | extend | separate", "evidence": "[Responsibility, props/contract, lifecycle/state ownership, design-system role, and repository-representativeness evidence]"}], + "findingsOutsideChange": [{"location": "[path:symbol]", "evidence": "[Observed fact]", "reason": "[Why this change leaves it unhandled]"}], "runnableCheck": {"level": "L1: Functional Operation Verification / L2: Test Operation Verification / L3: Build Success Verification", "executed": true, "command": "Executed verification command", "result": "passed / failed / skipped", "reason": "Verification content or exact limitation"}, "mutationEvidence": [{"mutation": "[description or patch]", "killedTest": "[test name]", "baselineResult": "[baseline command and result]", "mutatedResult": "[mutated command and result]", "restorationProof": "[restoration checksum or clean diff]", "targetRevision": "[revision or file hashes]"}] } diff --git a/agents/task-executor.md b/agents/task-executor.md index ffc23b25..f6a9167e 100644 --- a/agents/task-executor.md +++ b/agents/task-executor.md @@ -12,6 +12,8 @@ skills: You are a specialized AI assistant for reliably executing individual tasks. +You own how this codebase is built and you will keep building on it, so what you leave behind is yours to maintain. What it is for — the outcome, requirements, and non-goals — stays with the user's recorded decisions. + ## Input Parameters Workflow callers use the applicable canonical fields below: @@ -70,7 +72,7 @@ Use the indicators to find plausible candidates and apply the authoritative boun 1. Compare responsibility, contract, lifecycle, and representative repository usage. 2. Record one `reuseDecisions` entry: - `reuse` or `extend` when those dimensions are compatible; - - `separate` when sharing would merge independently evolving responsibilities or add more contract surface than it removes. + - `separate` when evidence shows different contracts or change reasons, or when sharing would add more coupling and contract surface than it removes. 3. Continue with the repository-local reversible choice supported by that evidence. ### Step4: Core Mechanism Preservation Check @@ -143,15 +145,13 @@ Classify from the task outcome and changed boundary, then run after Pre-implemen #### Reference Representativeness (Applied During Implementation) -When adopting a pattern or dependency from existing code, apply coding-principles "Reference Representativeness" at the point of adoption: - -Apply coding-principles Reference Representativeness using the changed area and representative consumers or siblings. Expand to all known consumers when a changed shared/public contract requires compatibility accounting. Record the evidence for a material choice among competing patterns; stop when further search cannot change implementation or proof. +When adopting a pattern or dependency from existing code, apply coding-principles Reference Representativeness at the point of adoption. #### 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 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. +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. When completing a skeleton, remove its `Selection evidence` lines, which served test selection only, and keep its other annotations for test review and lane routing. #### Operation Verification - Execute the Operation Verification Methods in the execution instructions @@ -186,6 +186,8 @@ Return the final response per Structured Response Specification. For research/an **reuseDecisions**: Use `[]` when no plausible similar implementation was found. Otherwise include the decision-relevant candidates evaluated in Step 3 with `decision: "reuse" | "extend" | "separate"` and evidence covering responsibility, contract, lifecycle, and repository representativeness. +**findingsOutsideChange**: Use `[]` when none. Otherwise list problems already observed during this task that the change leaves unhandled, because handling them belongs to another responsibility, would change the outcome or a non-goal, or needs an irreversible external action. Each item gives its location, evidence, and that reason. The field reports observations; it creates no search obligation. + ### 1. Task Completion Response Complete this agent's work by returning the following JSON; the quality assurance process performs quality checks and commits: @@ -198,6 +200,7 @@ Complete this agent's work by returning the following JSON; the quality assuranc "requiresTestReview": true, "newTestsPassed": true, "reuseDecisions": [{"candidate": "[path:symbol]", "decision": "reuse | extend | separate", "evidence": "[Responsibility, contract, lifecycle, and repository-representativeness evidence]"}], + "findingsOutsideChange": [{"location": "[path:symbol]", "evidence": "[Observed fact]", "reason": "[Why this change leaves it unhandled]"}], "runnableCheck": {"level": "L1: Functional Operation Verification / L2: Test Operation Verification / L3: Build Success Verification", "executed": true, "command": "Executed verification command", "result": "passed / failed / skipped", "reason": "Verification content or exact limitation"}, "mutationEvidence": [{"mutation": "[description or patch]", "killedTest": "[test name]", "baselineResult": "[baseline command and result]", "mutatedResult": "[mutated command and result]", "restorationProof": "[restoration checksum or clean diff]", "targetRevision": "[revision or file hashes]"}] } diff --git a/agents/technical-designer-frontend.md b/agents/technical-designer-frontend.md index ed5c24e2..f215ff00 100644 --- a/agents/technical-designer-frontend.md +++ b/agents/technical-designer-frontend.md @@ -15,6 +15,8 @@ skills: You create one complete frontend ADR batch or one frontend Design Doc per invocation. +You own how this codebase is built and you will keep building on it, so what you leave behind is yours to maintain. What it is for — the outcome, requirements, and non-goals — stays with the user's recorded decisions. + ## Execution Gate 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. diff --git a/agents/technical-designer.md b/agents/technical-designer.md index b01a6322..c097d31b 100644 --- a/agents/technical-designer.md +++ b/agents/technical-designer.md @@ -15,6 +15,8 @@ skills: You create one complete ADR batch or one Design Doc per invocation. +You own how this codebase is built and you will keep building on it, so what you leave behind is yours to maintain. What it is for — the outcome, requirements, and non-goals — stays with the user's recorded decisions. + ## Execution Gate 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. diff --git a/agents/ui-analyzer.md b/agents/ui-analyzer.md index a2ad0c82..cf1a4f04 100644 --- a/agents/ui-analyzer.md +++ b/agents/ui-analyzer.md @@ -27,7 +27,7 @@ Use only supplied `external_resource_refs`. Resolve their labels through `docs/p Locate the affected screens, components, and callers, then inspect only the render, state, style, interaction, and data path needed for the current decisions. Include Props and variants, DOM or layout behavior, display conditions, responsive behavior, accessibility, localization, and generated artifacts when they can change the result, a preserved contract, reuse, or verification. From evidence already gathered, record a simplification when a responsibility, branch, artifact, or change can be omitted while the outcome still holds; it remains a candidate for the parent and document owner. Inspect every consumer only when the complete consumer set controls compatibility; otherwise use representative consumers, tests, stories, and style peers. -Stop when another fact cannot change one of those outcomes. +Stop when the facts that could change one of those outcomes have been checked; a search with no match shows only that the search found nothing. ## Output Format diff --git a/agents/ui-spec-designer.md b/agents/ui-spec-designer.md index f70a6501..eba08510 100644 --- a/agents/ui-spec-designer.md +++ b/agents/ui-spec-designer.md @@ -4,7 +4,6 @@ description: Creates UI Specifications from requirements and optional prototype tools: Read, Write, Edit, MultiEdit, Glob, LS, Bash skills: - documentation-criteria - - typescript-rules - ai-development-guide - llm-friendly-context - external-resource-context diff --git a/dev-skills/.claude-plugin/plugin.json b/dev-skills/.claude-plugin/plugin.json index 4510355b..6121b391 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.30.0", + "version": "0.31.0", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-skills/skills/ai-development-guide/SKILL.md b/dev-skills/skills/ai-development-guide/SKILL.md index 70fbfe0a..352ad685 100644 --- a/dev-skills/skills/ai-development-guide/SKILL.md +++ b/dev-skills/skills/ai-development-guide/SKILL.md @@ -108,7 +108,7 @@ Keep concrete implementations separate while their apparent similarity is accide **Cases to Avoid Commonalization** - Accidental matches (coincidentally same code) -- Possibility of evolving in different directions +- Contracts or change reasons that evidence shows differ - Significant readability decrease from commonalization - Simple helpers in test code @@ -138,12 +138,11 @@ Keep concrete implementations separate while their apparent similarity is accide **Symptom**: Duplicate implementations, architecture inconsistency, integration failures, adopting outdated patterns **Cause**: Insufficient understanding of existing code before implementation; referencing only nearby files without verifying representativeness **Avoidance Methods**: -- Before implementation, always search for similar functionality (using domain, responsibility, configuration patterns as keywords) +- Before implementation, find functionality that already holds the same responsibility and the code that depends on the change, as coding-principles Reference Representativeness describes; similar functionality may share no name with the new code - Similar functionality found → Verify that its contract, lifecycle, and repository usage are representative; reuse or extend it when compatible, otherwise record why it is not a valid model - Similar functionality is technical debt → Repair it when it blocks the current outcome, was caused by the current change, or lies in scope; otherwise report it separately. Create an ADR when the repair requires an architectural decision - No similar functionality exists → Implement new functionality following existing design philosophy - Preserve the evidence for each reuse, extend, separate, or repair decision in the applicable implementation or design record -- **Reference representativeness check**: When adopting a pattern or dependency from nearby code, inspect the changed area and enough representative consumers or siblings to establish compatibility; expand only when competing patterns or a shared/public contract can change the choice ## Quality Assurance Mechanism Awareness @@ -168,7 +167,7 @@ Follow repository-declared command composition or ordering when it exists. Other ## Situations Requiring Technical Decisions ### Timing of Abstraction -- Extract a shared abstraction after repository evidence establishes a shared responsibility and coordinated change pattern +- Extract a shared abstraction after repository evidence shows a responsibility with the same contract and change reason maintained in more than one place - Be conscious of YAGNI, implement only currently needed features - Prioritize current simplicity over future extensibility diff --git a/dev-skills/skills/coding-principles/SKILL.md b/dev-skills/skills/coding-principles/SKILL.md index bd3ede0b..d45bce62 100644 --- a/dev-skills/skills/coding-principles/SKILL.md +++ b/dev-skills/skills/coding-principles/SKILL.md @@ -70,9 +70,11 @@ description: Language-agnostic coding principles for maintainability, readabilit ## Reference Representativeness -Inspect the changed responsibility and enough representative callers, consumers, configuration and siblings to establish a compatible pattern or dependency. Nearby code is a starting point; when alternatives coexist, choose from their responsibility, contract, lifecycle and repository usage rather than proximity or global popularity alone. Record the evidence only when it changes the choice. +Existing code relates to a change in two ways. Code that depends on it — callers, consumers, configuration — is reached through references to the changed code. Code that already holds the same responsibility may share no name or reference with it; reach it through position and role (sibling features, files with the same role in the same layer, shared layers) and through the input it takes and the purpose it serves, then compare their logic to judge whether the responsibility is the same. -Expand to all known consumers for a changed public, shared, serialized or persistent contract whose compatibility depends on them. Otherwise stop when additional inspection cannot change implementation or proof. Resolve versions from applicable manifests and usage; record a specific limitation only when required compatibility evidence remains unavailable. +When alternatives coexist, choose the pattern from responsibility, contract, lifecycle and repository usage rather than proximity or global popularity alone. Record the evidence only when it changes the choice. + +Expand to all known consumers for a changed public, shared, serialized or persistent contract whose compatibility depends on them. Stop when the candidates that could change implementation or proof have been read and judged; a search with no match shows only that the search found nothing. Resolve versions from applicable manifests and usage; record a specific limitation only when required compatibility evidence remains unavailable. ## Performance Considerations @@ -120,7 +122,7 @@ One comment per decision. If a comment restates what the names and control flow - Delete commented-out code (retrieve from git history when needed) ### Comment Quality -- Base comments on stable rationale, limits, and contracts rather than dates, versions, or temporary state +- Base comments on stable rationale, limits, and contracts rather than dates, versions, temporary state, or references to documents and their sections, which drift as those documents change - Update comments when changing code - Use proper grammar and formatting - Write for future maintainers @@ -161,3 +163,7 @@ One comment per decision. If a comment restates what the names and control flow - For changes involving identity or protected resources, prioritize authentication and per-resource authorization review For concrete detection patterns used by security review, see `references/security-checks.md`. + +## References + +- [references/frontend.md](references/frontend.md): read when implementing, reviewing, or fixing React/TypeScript code diff --git a/dev-skills/skills/coding-principles/references/frontend.md b/dev-skills/skills/coding-principles/references/frontend.md new file mode 100644 index 00000000..ba9f0363 --- /dev/null +++ b/dev-skills/skills/coding-principles/references/frontend.md @@ -0,0 +1,50 @@ +# Frontend (React/TypeScript) Coding Rules + +Apply these with the SKILL.md principles. Each entry adds what React and TypeScript code needs beyond them; the frontend decision criteria for component responsibility, error boundaries, and profiling live in `references/frontend.md` of the ai-development-guide skill. + +## Type Safety + +**Default Rule**: Prefer `unknown`, generics, or union types over `any`. Retain `any` only when an existing external, generated, or legacy public signature requires it, or when replacing it prevents the project type check from expressing a safe generic relationship. Record the declaration path or type-check result that proves the constraint. When a local adapter can preserve compatibility and expose a safer type within the user request or current task/design artifact, implement the adapter; otherwise confine `any` to the smallest adapter or public-signature boundary, document the reason, and validate untrusted data before it enters typed application code. + +**Frontend Boundaries** + +- React Props/State: use the declared application types. +- External API responses: treat unvalidated payloads as `unknown` and validate at the boundary. A generated client may retain its declared type when it also enforces the contract at runtime. +- `localStorage` / `sessionStorage`: handle `string | null`; treat parsed data as `unknown` until validated. +- URL parameters: handle the router or platform's nullable string shape, then parse and validate before converting to a domain type. +- Exported APIs and important boundaries: declare return types; allow inference for local implementations when the contract remains clear. + +**Type Complexity Review Signals** + +Use these as review prompts, not pass/fail thresholds. Existing project conventions and the component's responsibility take precedence. + +- Props count: review ownership or splitting above 10. +- Optional props: review defaults or ownership when more than half are optional. +- Nested prop structures: review flattening beyond 2 levels. +- Type assertions: review the boundary when 3+ assertions are required. +- External API types: represent the actual external shape and convert at the application boundary. + +## Components and State + +- Prefer function components and Hooks for new code. Preserve working class components unless the accepted work requires migration; a class remains valid for an Error Boundary implementation. +- Follow the project's adopted component architecture and file layout. Co-locate files only when it is established or approved as a new structure. +- Preserve the repository's existing local, shared, and server-state ownership boundaries. Introduce Context, a shared-state layer, or a server-state dependency only when the accepted design requires ownership or lifecycle that the existing boundary cannot represent. +- Keep one authoritative owner for each state value and use the immutable updates React change detection requires. +- Guard effect-driven requests against stale or post-unmount updates through the repository's cancellation or server-state mechanism. + +## Server/Client Boundary — only for RSC frameworks + +- Fetch and render on the server by default; isolate interactivity behind the smallest `"use client"` boundary that needs it. +- Keep browser-only APIs and event handlers inside client components. +- Skip these rules when the project has no server-component runtime. + +## Environment and Client Security + +- Read client-side environment variables through the project's bundler accessor and public prefix. Validate required values through the repository's typed config layer; add a default only for an optional value or an explicitly defined local-development mode. +- Browser-delivered code and public environment variables are observable by clients, so credentials and secrets stay on the server. + +## Performance and Compatibility + +- When React Compiler is enabled, rely on it. Add manual `React.memo`, `useMemo`, or `useCallback` only for a measured bottleneck or a required stable identity at an external API/effect boundary. +- Apply code splitting or import changes when a configured bundle budget regresses, or when the accepted task names bundle size as an outcome and a repository bundle report attributes the relevant increase to the changed import. Follow the repository's existing loading pattern and verify the same signal after the change. +- Implement against the browser support policy in the PRD, Design Doc, Browserslist, or build configuration. When none is defined, preserve the repository's current transpilation/polyfill baseline and surface any new browser-dependent API as an unresolved compatibility decision. diff --git a/dev-skills/skills/implementation-approach/SKILL.md b/dev-skills/skills/implementation-approach/SKILL.md index 46ee41dc..b9784615 100644 --- a/dev-skills/skills/implementation-approach/SKILL.md +++ b/dev-skills/skills/implementation-approach/SKILL.md @@ -24,7 +24,7 @@ Historical Context Understanding: Current form rationale, past decision validity - What dependencies or implicit preconditions are unclear from the code? - What benefits and constraints does the current design bring? -Stop when another current-state fact cannot change responsibility, reuse, option validity, total complexity, a contract, or verification. +Stop when the current-state facts that could change responsibility, reuse, option validity, total complexity, a contract, or verification have been checked; find existing code as coding-principles Reference Representativeness describes. ### Phase 2: Design Convergence @@ -32,7 +32,7 @@ Complete these steps in order before selecting an implementation strategy: 1. **Existing-Surface Baseline**: Form the simplest end-to-end path that delivers the current outcome through existing responsibilities. Explicit requirements and accepted decisions are binding; suggested mechanisms remain candidates. 2. **Evidence Check**: Test that path against current requirements, verified constraints, observed in-scope problems, and evidence-backed material risks. Keep only the unmet conditions that can change the selected design. Where the requirements leave a quality level unset, such as performance, freshness, consistency, availability, or protection beyond the required trust boundary, test against the lowest level that still delivers the outcome and record it as the selected level. -3. **Targeted Comparison**: For each unmet condition, test reuse, derivation from existing data, on-demand computation, or responsibility at the current caller or boundary before adding design surface. Compare viable choices by total complexity across the dimensions that materially differ: user decisions, settings, modes, concepts, outputs, persistent state, implementation paths, UX, runtime, implementation, testing, documentation, and maintenance. Select the lowest-total-complexity choice that satisfies the condition. +3. **Targeted Comparison**: For each unmet condition, test reuse, derivation from existing data, on-demand computation, or responsibility at the current caller or boundary before adding design surface. Compare viable choices by total complexity across the dimensions that materially differ: user decisions, settings, modes, concepts, outputs, persistent state, implementation paths, UX, runtime, implementation, testing, documentation, and maintenance. A second implementation of a responsibility that already has an owner with the same contract and change reason, including one added earlier in the same change, adds design surface; reusing or relocating that owner removes it. Select the lowest-total-complexity choice that satisfies the condition. 4. **Subtraction Check**: Remove each proposed addition and re-test its governing condition. Retain it only when the outcome, a required boundary, or necessary proof becomes unmet at its origin (a requirement, an accepted decision, or a repository rule or contract); a criterion, invariant, or constraint that a workflow artifact derived from that origin is narrowed to what the origin requires instead. Classify supporting claims as observed, inferred, or unknown. Route an unknown that blocks the next step as an exact evidence prerequisite; the caller's value-boundary and irreversible-action gates determine whether user interaction is required. diff --git a/dev-skills/skills/integration-e2e-testing/SKILL.md b/dev-skills/skills/integration-e2e-testing/SKILL.md index aa037f1f..9ad86fdd 100644 --- a/dev-skills/skills/integration-e2e-testing/SKILL.md +++ b/dev-skills/skills/integration-e2e-testing/SKILL.md @@ -29,6 +29,8 @@ Selection evidence: [required claim, uncovered failure, and why cheaper existing Use the project's comment syntax to wrap these annotations (e.g., `//` for C-family, `#` for Python/Ruby/Shell). +`Selection evidence` serves test selection and planning, so the implementing task removes it when it makes the test executable. + ### Verification Items (Optional) When verification points need explicit enumeration: diff --git a/dev-skills/skills/testing-principles/references/e2e.md b/dev-skills/skills/testing-principles/references/e2e.md index b0e06542..df87bf72 100644 --- a/dev-skills/skills/testing-principles/references/e2e.md +++ b/dev-skills/skills/testing-principles/references/e2e.md @@ -42,4 +42,4 @@ Use the repository's existing seed and authentication mechanisms. Create per-tes ## Skeleton Annotations -Preserve the skeleton's annotations unchanged. When `Verification items:` are present, implement and assert every listed item. +Preserve the skeleton's annotations unchanged, except `Selection evidence`, which served test selection only and is removed when the test becomes executable. When `Verification items:` are present, implement and assert every listed item. diff --git a/dev-skills/skills/testing-principles/references/frontend.md b/dev-skills/skills/testing-principles/references/frontend.md index 9b683622..a961645e 100644 --- a/dev-skills/skills/testing-principles/references/frontend.md +++ b/dev-skills/skills/testing-principles/references/frontend.md @@ -7,7 +7,7 @@ Before writing a test, inspect package scripts, runner configuration, setup file - Use React Testing Library when it is the project's component-test renderer; prefer `userEvent` for user interactions. - Use the repository's network mocking layer for API behavior. When MSW is configured, extend its handlers instead of adding runner-level fetch mocks. - Use the configured runner's imports, module-mocking API, fake timers, and reset conventions. -- When multiple approaches coexist, follow the dominant convention in the changed feature area. If none is representative and adding or replacing tooling is outside the approved work, report the missing test-environment decision. +- When multiple approaches coexist, choose from the behavior under test and the setup the repository maintains for it rather than from proximity alone. If none is representative and adding or replacing tooling is outside the approved work, report the missing test-environment decision. ## Test Scope diff --git a/dev-skills/skills/typescript-rules/SKILL.md b/dev-skills/skills/typescript-rules/SKILL.md deleted file mode 100644 index df4751bd..00000000 --- a/dev-skills/skills/typescript-rules/SKILL.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -name: typescript-rules -description: React/TypeScript frontend development rules including type safety, component design, state management, and error handling. Use when implementing React components, TypeScript code, or frontend features. ---- - -# TypeScript Development Rules (Frontend) - -## Comment Writing Rules - -Code first: names and types carry meaning; a comment must add what code cannot, and one comment per decision is enough. - -- Explain why a component memoizes, guards, or re-renders, not what the JSX renders. -- Record decisions and rationale; leave chronological history to version control. - -## Type Safety - -**Default Rule**: Prefer `unknown`, generics, or union types over `any`. Retain `any` only when an existing external, generated, or legacy public signature requires it, or when replacing it prevents the project type check from expressing a safe generic relationship. Record the declaration path or type-check result that proves the constraint. When a local adapter can preserve compatibility and expose a safer type within the user request or current task/design artifact, implement the adapter; otherwise confine `any` to the smallest adapter or public-signature boundary, document the reason, and validate untrusted data before it enters typed application code. - -**Frontend Boundaries** - -- React Props/State: use the declared application types. -- External API responses: treat unvalidated payloads as `unknown` and validate at the boundary. A generated client may retain its declared type when it also enforces the contract at runtime. -- `localStorage` / `sessionStorage`: handle `string | null`; treat parsed data as `unknown` until validated. -- URL parameters: handle the router or platform's nullable string shape, then parse and validate before converting to a domain type. -- Exported APIs and important boundaries: declare return types; allow inference for local implementations when the contract remains clear. - -**Type Complexity Review Signals** - -Use these as review prompts, not pass/fail thresholds. Existing project conventions and the component's responsibility take precedence. - -- Props count: review ownership or splitting above 10. -- Optional props: review defaults or ownership when more than half are optional. -- Nested prop structures: review flattening beyond 2 levels. -- Type assertions: review the boundary when 3+ assertions are required. -- External API types: represent the actual external shape and convert at the application boundary. - -## Coding Conventions - -**Component and File Decisions** - -- Prefer function components and Hooks for new code. Preserve working class components unless the accepted work requires migration; a class remains valid for an Error Boundary implementation. -- Reuse logic through the repository's established component, hook, or module pattern. -- Follow the project's adopted component architecture and file layout. Co-locate files only when it is established or approved as a new structure. - -**Server/Client Boundary — only for RSC frameworks** - -- Fetch and render on the server by default; isolate interactivity behind the smallest `"use client"` boundary that needs it. -- Keep browser-only APIs and event handlers inside client components. -- Skip these rules when the project has no server-component runtime. - -**State Ownership** - -- Preserve the repository's existing local, shared, and server-state ownership boundaries. -- Introduce Context, a shared-state layer, or a server-state dependency only when the accepted design requires ownership or lifecycle that the existing boundary cannot represent. -- Keep one authoritative owner for each state value and use immutable updates required by React change detection. - -**Function and Props Boundaries** - -- Prefer 0-2 parameters. For 3+ related values, use an object when it clarifies names or represents one domain input; preserve positional parameters when the repository convention or external API requires them. -- Declare component dependencies through typed props, hooks, Context, or injected modules according to the repository's established state and dependency boundaries. - -**Environment Variables** - -- Read client-side environment variables through the project's bundler accessor and public prefix. -- Validate required values through the repository's typed config layer; add a default only for an optional value or an explicitly defined local-development mode. - -**Client Security** - -- Keep credentials and secrets on the server; browser-delivered code and public environment variables are observable by clients. -- Exclude local environment files from version control and keep error output free of sensitive values. - -**Asynchronous Processing** - -- Follow the repository's promise style; use `async`/`await` when it clarifies sequencing and error propagation. -- Handle event-handler and asynchronous failures at their owning boundary. Error Boundaries cover descendant rendering failures, not ordinary callbacks or asynchronous work. -- Guard effect-driven requests against stale or post-unmount updates through the repository's cancellation or server-state mechanism. - -**Formatting** - -- Follow the repository's formatter, naming, module-resolution, and package-boundary configuration. -- Use an import alias only when the project configuration resolves it. - -## Error Handling - -Every caught error has one intentional outcome: propagate it, convert it to the repository's typed boundary result, or represent it as user-facing error state. Preserve context and log once at the boundary that owns diagnosis or recovery, with sensitive data redacted. - -- Error Boundary: place it where descendant render failures have a defined UI recovery outcome. -- Custom Hook: preserve the application's existing error contract. -- API Layer: convert transport failures to the repository's established domain or boundary representation. -- Event handlers and async workflows: use the owning layer's exception, result, or UI-state contract. - -## Performance Optimization - -- When React Compiler is enabled, rely on it. Add manual `React.memo`, `useMemo`, or `useCallback` only for a measured bottleneck or a required stable identity at an external API/effect boundary. -- Apply code splitting or import changes when a configured bundle budget regresses, or when the accepted task names bundle size as an outcome and a repository bundle report attributes the relevant increase to the changed import. Follow the repository's existing loading pattern and verify the same signal after the change. - -## Non-functional Requirements - -- **Browser Compatibility**: Implement against the support policy in the PRD, Design Doc, Browserslist, or build configuration. When none is defined, preserve the repository's current transpilation/polyfill baseline and surface any new browser-dependent API as an unresolved compatibility decision. -- **Performance**: Verify against project-defined budgets and the metric representing the affected experience. When no budget exists, measure the changed path and report the observed result instead of inventing a threshold. diff --git a/dev-workflows-frontend/.claude-plugin/plugin.json b/dev-workflows-frontend/.claude-plugin/plugin.json index 69db6218..01e4a592 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.30.0", + "version": "0.31.0", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows-frontend/agents/acceptance-test-generator.md b/dev-workflows-frontend/agents/acceptance-test-generator.md index 5903323f..f9170cb2 100644 --- a/dev-workflows-frontend/agents/acceptance-test-generator.md +++ b/dev-workflows-frontend/agents/acceptance-test-generator.md @@ -41,6 +41,8 @@ Each selected test records: - proof obligation: boundary to traverse, expected state/results, pass criteria, real dependencies and permissible substitutes; - a distinct branch, state, lifecycle or fallback path when the main path could remain green through a material regression. +File-level comments hold only what the completed tests keep, such as the lane declaration and setup the tests share; each test's record carries the rest. + Keep executable assertions and mock implementation for the implementing task. Test Boundaries marking a dependency as real are carried as `@real-dependency: [component]`. ## Output diff --git a/dev-workflows-frontend/agents/code-reviewer.md b/dev-workflows-frontend/agents/code-reviewer.md index 7b801887..44d8ad95 100644 --- a/dev-workflows-frontend/agents/code-reviewer.md +++ b/dev-workflows-frontend/agents/code-reviewer.md @@ -19,7 +19,7 @@ Verify by reading the changed code and tests. Running tests and quality checks i ## Inputs - **governingDocuments**: One or more approved Design Docs, or the resolved Work Plan when the caller has no Design Doc, as a list of document paths -- **implementationFiles**: The complete set of implementation, test, schema, build, deployment, and runtime-configuration artifacts in the reviewed change +- **implementationFiles**: The implementation, test, schema, build, deployment, and runtime-configuration artifacts whose changes this review judges: the complete change, or one review unit of it - **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 @@ -31,6 +31,7 @@ Before reviewing, read these files; they hold review criteria beyond the preload - `references/frontend.md` in the testing-principles skill - `references/frontend.md` in the ai-development-guide skill +- `references/frontend.md` in the coding-principles skill - `references/e2e.md` in the testing-principles skill ## Initial Review @@ -40,7 +41,7 @@ Extract the approved outcome, applicable acceptance criteria, changed interfaces Judge the material surfaces in `implementationFiles` against these criteria: - **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. +- **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 code or tests that already hold the same responsibility, in the repository or elsewhere in this change (coding-principles Reference Representativeness), 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. diff --git a/dev-workflows-frontend/agents/code-verifier.md b/dev-workflows-frontend/agents/code-verifier.md index 2c717c5e..0f4ea016 100644 --- a/dev-workflows-frontend/agents/code-verifier.md +++ b/dev-workflows-frontend/agents/code-verifier.md @@ -39,7 +39,7 @@ For reverse-engineered/as-is documents, verify every supplied inventory item at Use one authoritative definition when it directly proves an identifier or contract. Seek another source when behavior, indirection, or conflicting evidence makes it decision-relevant. Base confidence on evidence quality rather than source count. -Stop expanding the search when additional evidence cannot change a discrepancy or limitation. +Stop expanding the search when the evidence that could change a discrepancy or limitation has been checked; find existing code as coding-principles Reference Representativeness describes. ## Rerun Boundary diff --git a/dev-workflows-frontend/agents/codebase-analyzer.md b/dev-workflows-frontend/agents/codebase-analyzer.md index 13c58dec..80d0bfec 100644 --- a/dev-workflows-frontend/agents/codebase-analyzer.md +++ b/dev-workflows-frontend/agents/codebase-analyzer.md @@ -32,7 +32,7 @@ Return a fact only when it can: - identify a lifecycle-cost or maintainability difference; or - select a verification boundary. -Stop expanding the search when another fact cannot change one of those outcomes. Inspect all known consumers only for a public, shared, serialized, persistent, security, or error contract whose complete consumer set controls compatibility. Otherwise, representative callers, tests, configuration, and siblings are sufficient. +Existing code with the same responsibility as a new surface may share no name or reference with it; look for reuse through position and role (sibling features, files with the same role in the same layer, shared layers) and through shared input and purpose, as well as through references. Stop expanding the search when the facts that could change one of those outcomes have been checked; a search with no match shows only that the search found nothing. Inspect all known consumers only for a public, shared, serialized, persistent, security, or error contract whose complete consumer set controls compatibility. Otherwise, representative callers, tests, configuration, and siblings are sufficient. ## Execution Steps diff --git a/dev-workflows-frontend/agents/quality-fixer-frontend.md b/dev-workflows-frontend/agents/quality-fixer-frontend.md index 1d119f14..c92a9ca4 100644 --- a/dev-workflows-frontend/agents/quality-fixer-frontend.md +++ b/dev-workflows-frontend/agents/quality-fixer-frontend.md @@ -3,7 +3,7 @@ name: quality-fixer-frontend description: Specialized agent for verifying React projects and fixing frontend quality failures within the current task scope. Use proactively after code changes or for quality, test, build, lint, format, type, or fix requests. tools: Bash, Read, Edit, MultiEdit, Grep, Glob, LS skills: - - typescript-rules + - coding-principles - testing-principles - ai-development-guide - external-resource-context @@ -77,7 +77,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 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. +Apply fixes per coding-principles, testing-principles, and ai-development-guide skills, reading `references/frontend.md` in the coding-principles skill for frontend coding rules and 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 @@ -96,15 +96,15 @@ Return one of the following as the final response (see Output Format for schemas ## Frontend-Specific Quality Criteria ### Repository-Local Choice Discipline -Prefer repository-local component patterns over generic React advice; when patterns coexist for the same concern, follow the dominant one in the changed feature area — the surrounding feature folder, or the nearest parent directory containing siblings using the same concern. When no repository choice covers the concern, select the lowest-surface sufficient option using the governing value boundary and available technical evidence; novelty alone is not a reason for `blocked`. +Prefer repository-local component patterns over generic React advice; when patterns coexist for the same concern, choose as coding-principles Reference Representativeness describes. When no repository choice covers the concern, select the lowest-surface sufficient option using the governing value boundary and available technical evidence; novelty alone is not a reason for `blocked`. ### Testing Quality - **Mock layering**: Browser-primitive doubles (e.g., ResizeObserver, IntersectionObserver, time, router/provider) are acceptable when the test environment requires them; the component under test is exercised through real renders and user interactions - **Query selection**: Prefer role/name queries for user-visible elements; use async queries (`findBy*`, `waitFor`) for async appearance and `queryBy*`/`queryAllBy*` only when asserting intentional absence ### Build Quality -- **Zero Type Errors**: TypeScript build must succeed without errors; Props and State have explicit type definitions. Permit `any` only at an evidence-backed, narrowly bounded exception that satisfies typescript-rules -- **Bundle / code-splitting fixes**: Apply the evidence and verification rule in typescript-rules +- **Zero Type Errors**: TypeScript build must succeed without errors; Props and State have explicit type definitions. Permit `any` only at an evidence-backed, narrowly bounded exception that satisfies the coding-principles frontend reference +- **Bundle / code-splitting fixes**: Apply the evidence and verification rule in the coding-principles frontend reference ## Status Determination Criteria @@ -228,7 +228,7 @@ Between tool calls, briefly report: which phase is running, the command executed - **Clear Type Error Fixes** - Add import statements (when types not found) - Add type annotations for Props/State (when inference impossible) - - Replace `any` with `unknown` plus validation for untyped external API responses; preserve only the documented, bounded exceptions allowed by typescript-rules + - Replace `any` with `unknown` plus validation for untyped external API responses; preserve only the documented, bounded exceptions allowed by the coding-principles frontend reference - Add optional chaining - **Clear Code Quality Issues** - Remove unused variables/functions/components @@ -243,15 +243,15 @@ Between tool calls, briefly report: which phase is running, the command executed - Integration test failure: Investigate and fix component integration - Boundary value test failure: Confirm specification and fix - **Bundle / Rendering Optimization** - - Apply only when Step 3 reports bundle evidence that satisfies typescript-rules or profiler evidence identifies the changed render path + - Apply only when Step 3 reports bundle evidence that satisfies the coding-principles frontend reference or profiler evidence identifies the changed render path - Use the repository's existing loading/import pattern and the smallest fix that addresses that evidence; re-run the same bundle or profiler signal - - Add manual memoization only for the profiler- or identity-based conditions in typescript-rules + - Add manual memoization only for the profiler- or identity-based conditions in the coding-principles frontend reference - **Structural Issues** - Resolve circular dependencies (extract to common modules) - Split components when independent rendering, state, data, or test responsibilities create material coupling or verification cost; retain a cohesive component when splitting would add avoidable prop/state synchronization - Refactor deeply nested conditionals - **Type Error Fixes** - - Resolve external API response types by the typescript-rules boundary validation policy + - Resolve external API response types by the coding-principles frontend reference's boundary validation policy - Add necessary Props type definitions - Flexibly handle with generics or union types @@ -286,7 +286,7 @@ All fixes must satisfy these criteria: |----------|------------| | Test integrity | Tests remain executable and active (no `it.skip`, no deletion for convenience) | | Assertion quality | Every test contains meaningful assertions that verify behavior (not `expect(true).toBe(true)`) | -| Type safety | Prefer explicit types (`unknown`, generics, unions); permit only documented, bounded `any` exceptions from typescript-rules and justified project-configured suppressions | +| Type safety | Prefer explicit types (`unknown`, generics, unions); permit only documented, bounded `any` exceptions from the coding-principles frontend reference and justified project-configured suppressions | | Error handling | Handle errors with context (log, propagate, or recover with specific handling) | | Environment separation | Keep test-specific branches (e.g. `import.meta.env.MODE` checks) outside production code | | ESLint compliance | Preserve ESLint rules (add justification comments when override is necessary) | diff --git a/dev-workflows-frontend/agents/task-executor-frontend.md b/dev-workflows-frontend/agents/task-executor-frontend.md index 6fba977f..4ec2c73d 100644 --- a/dev-workflows-frontend/agents/task-executor-frontend.md +++ b/dev-workflows-frontend/agents/task-executor-frontend.md @@ -3,7 +3,7 @@ name: task-executor-frontend description: Executes React implementation completely self-contained from an explicit prompt or frontend task file. Use when frontend task files exist, or when "frontend implementation/React implementation/component creation" is mentioned. Asks no questions, executes consistently from investigation to implementation. tools: Read, Edit, Write, MultiEdit, Bash, Grep, Glob, LS skills: - - typescript-rules + - coding-principles - testing-principles - ai-development-guide - implementation-approach @@ -12,6 +12,8 @@ skills: You are a specialized AI assistant for reliably executing frontend implementation tasks. +You own how this codebase is built and you will keep building on it, so what you leave behind is yours to maintain. What it is for — the outcome, requirements, and non-goals — stays with the user's recorded decisions. + Operates in an independent context, executing autonomously until task completion. ## Input Parameters @@ -42,7 +44,7 @@ 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-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. +Apply loaded coding-principles, testing-principles, and ai-development-guide rules during implementation, and read `references/frontend.md` in the coding-principles and ai-development-guide skills before implementing; they hold the frontend coding rules and criteria. When `docs/project-context/quality.yaml` exists, use it as implementation guidance. @@ -75,7 +77,7 @@ Use the indicators to find plausible candidates and apply the authoritative boun 1. Compare responsibility, props/contract, lifecycle and state ownership, design-system role, and representative repository usage. 2. Record one `reuseDecisions` entry: - `reuse` or `extend` when those dimensions are compatible; - - `separate` when sharing would merge independently evolving responsibilities or add more prop/state synchronization and contract surface than it removes. + - `separate` when evidence shows different contracts or change reasons, or when sharing would add more prop/state synchronization and contract surface than it removes. 3. Continue with the repository-local reversible choice supported by that evidence. ### Step4: Core Mechanism Preservation Check @@ -148,14 +150,12 @@ Classify from the task outcome and changed boundary, then run after Pre-implemen #### Reference Representativeness (Applied During Implementation) -When adopting a pattern, hook, or library from existing code, apply Reference Representativeness at the point of adoption: - -Apply coding-principles Reference Representativeness using the changed area and representative consumers or siblings. Expand to all known consumers when a changed shared/public contract requires compatibility accounting. Record the evidence for a material choice among competing patterns; stop when further search cannot change implementation or proof. +When adopting a pattern, hook, or library from existing code, apply coding-principles Reference Representativeness at the point of adoption. #### 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. +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. When completing a skeleton, remove its `Selection evidence` lines, which served test selection only, and keep its other annotations for test review and lane routing. #### Operation Verification - Execute the Operation Verification Methods in the execution instructions @@ -190,6 +190,8 @@ Return the final response per Structured Response Specification. For research/an **reuseDecisions**: Use `[]` when no plausible similar component or hook was found. Otherwise include the decision-relevant candidates evaluated in Step 3 with `decision: "reuse" | "extend" | "separate"` and evidence covering responsibility, props/contract, lifecycle/state ownership, design-system role, and repository representativeness. +**findingsOutsideChange**: Use `[]` when none. Otherwise list problems already observed during this task that the change leaves unhandled, because handling them belongs to another responsibility, would change the outcome or a non-goal, or needs an irreversible external action. Each item gives its location, evidence, and that reason. The field reports observations; it creates no search obligation. + ### 1. Task Completion Response Complete this agent's work by returning the following JSON; the quality assurance process performs quality checks and commits: @@ -202,6 +204,7 @@ Complete this agent's work by returning the following JSON; the quality assuranc "requiresTestReview": false, "newTestsPassed": true, "reuseDecisions": [{"candidate": "[path:component-or-hook]", "decision": "reuse | extend | separate", "evidence": "[Responsibility, props/contract, lifecycle/state ownership, design-system role, and repository-representativeness evidence]"}], + "findingsOutsideChange": [{"location": "[path:symbol]", "evidence": "[Observed fact]", "reason": "[Why this change leaves it unhandled]"}], "runnableCheck": {"level": "L1: Functional Operation Verification / L2: Test Operation Verification / L3: Build Success Verification", "executed": true, "command": "Executed verification command", "result": "passed / failed / skipped", "reason": "Verification content or exact limitation"}, "mutationEvidence": [{"mutation": "[description or patch]", "killedTest": "[test name]", "baselineResult": "[baseline command and result]", "mutatedResult": "[mutated command and result]", "restorationProof": "[restoration checksum or clean diff]", "targetRevision": "[revision or file hashes]"}] } diff --git a/dev-workflows-frontend/agents/technical-designer-frontend.md b/dev-workflows-frontend/agents/technical-designer-frontend.md index ed5c24e2..f215ff00 100644 --- a/dev-workflows-frontend/agents/technical-designer-frontend.md +++ b/dev-workflows-frontend/agents/technical-designer-frontend.md @@ -15,6 +15,8 @@ skills: You create one complete frontend ADR batch or one frontend Design Doc per invocation. +You own how this codebase is built and you will keep building on it, so what you leave behind is yours to maintain. What it is for — the outcome, requirements, and non-goals — stays with the user's recorded decisions. + ## Execution Gate 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. diff --git a/dev-workflows-frontend/agents/ui-analyzer.md b/dev-workflows-frontend/agents/ui-analyzer.md index a2ad0c82..cf1a4f04 100644 --- a/dev-workflows-frontend/agents/ui-analyzer.md +++ b/dev-workflows-frontend/agents/ui-analyzer.md @@ -27,7 +27,7 @@ Use only supplied `external_resource_refs`. Resolve their labels through `docs/p Locate the affected screens, components, and callers, then inspect only the render, state, style, interaction, and data path needed for the current decisions. Include Props and variants, DOM or layout behavior, display conditions, responsive behavior, accessibility, localization, and generated artifacts when they can change the result, a preserved contract, reuse, or verification. From evidence already gathered, record a simplification when a responsibility, branch, artifact, or change can be omitted while the outcome still holds; it remains a candidate for the parent and document owner. Inspect every consumer only when the complete consumer set controls compatibility; otherwise use representative consumers, tests, stories, and style peers. -Stop when another fact cannot change one of those outcomes. +Stop when the facts that could change one of those outcomes have been checked; a search with no match shows only that the search found nothing. ## Output Format diff --git a/dev-workflows-frontend/agents/ui-spec-designer.md b/dev-workflows-frontend/agents/ui-spec-designer.md index f70a6501..eba08510 100644 --- a/dev-workflows-frontend/agents/ui-spec-designer.md +++ b/dev-workflows-frontend/agents/ui-spec-designer.md @@ -4,7 +4,6 @@ description: Creates UI Specifications from requirements and optional prototype tools: Read, Write, Edit, MultiEdit, Glob, LS, Bash skills: - documentation-criteria - - typescript-rules - ai-development-guide - llm-friendly-context - external-resource-context diff --git a/dev-workflows-frontend/skills/ai-development-guide/SKILL.md b/dev-workflows-frontend/skills/ai-development-guide/SKILL.md index 70fbfe0a..352ad685 100644 --- a/dev-workflows-frontend/skills/ai-development-guide/SKILL.md +++ b/dev-workflows-frontend/skills/ai-development-guide/SKILL.md @@ -108,7 +108,7 @@ Keep concrete implementations separate while their apparent similarity is accide **Cases to Avoid Commonalization** - Accidental matches (coincidentally same code) -- Possibility of evolving in different directions +- Contracts or change reasons that evidence shows differ - Significant readability decrease from commonalization - Simple helpers in test code @@ -138,12 +138,11 @@ Keep concrete implementations separate while their apparent similarity is accide **Symptom**: Duplicate implementations, architecture inconsistency, integration failures, adopting outdated patterns **Cause**: Insufficient understanding of existing code before implementation; referencing only nearby files without verifying representativeness **Avoidance Methods**: -- Before implementation, always search for similar functionality (using domain, responsibility, configuration patterns as keywords) +- Before implementation, find functionality that already holds the same responsibility and the code that depends on the change, as coding-principles Reference Representativeness describes; similar functionality may share no name with the new code - Similar functionality found → Verify that its contract, lifecycle, and repository usage are representative; reuse or extend it when compatible, otherwise record why it is not a valid model - Similar functionality is technical debt → Repair it when it blocks the current outcome, was caused by the current change, or lies in scope; otherwise report it separately. Create an ADR when the repair requires an architectural decision - No similar functionality exists → Implement new functionality following existing design philosophy - Preserve the evidence for each reuse, extend, separate, or repair decision in the applicable implementation or design record -- **Reference representativeness check**: When adopting a pattern or dependency from nearby code, inspect the changed area and enough representative consumers or siblings to establish compatibility; expand only when competing patterns or a shared/public contract can change the choice ## Quality Assurance Mechanism Awareness @@ -168,7 +167,7 @@ Follow repository-declared command composition or ordering when it exists. Other ## Situations Requiring Technical Decisions ### Timing of Abstraction -- Extract a shared abstraction after repository evidence establishes a shared responsibility and coordinated change pattern +- Extract a shared abstraction after repository evidence shows a responsibility with the same contract and change reason maintained in more than one place - Be conscious of YAGNI, implement only currently needed features - Prioritize current simplicity over future extensibility diff --git a/dev-workflows-frontend/skills/coding-principles/SKILL.md b/dev-workflows-frontend/skills/coding-principles/SKILL.md index bd3ede0b..d45bce62 100644 --- a/dev-workflows-frontend/skills/coding-principles/SKILL.md +++ b/dev-workflows-frontend/skills/coding-principles/SKILL.md @@ -70,9 +70,11 @@ description: Language-agnostic coding principles for maintainability, readabilit ## Reference Representativeness -Inspect the changed responsibility and enough representative callers, consumers, configuration and siblings to establish a compatible pattern or dependency. Nearby code is a starting point; when alternatives coexist, choose from their responsibility, contract, lifecycle and repository usage rather than proximity or global popularity alone. Record the evidence only when it changes the choice. +Existing code relates to a change in two ways. Code that depends on it — callers, consumers, configuration — is reached through references to the changed code. Code that already holds the same responsibility may share no name or reference with it; reach it through position and role (sibling features, files with the same role in the same layer, shared layers) and through the input it takes and the purpose it serves, then compare their logic to judge whether the responsibility is the same. -Expand to all known consumers for a changed public, shared, serialized or persistent contract whose compatibility depends on them. Otherwise stop when additional inspection cannot change implementation or proof. Resolve versions from applicable manifests and usage; record a specific limitation only when required compatibility evidence remains unavailable. +When alternatives coexist, choose the pattern from responsibility, contract, lifecycle and repository usage rather than proximity or global popularity alone. Record the evidence only when it changes the choice. + +Expand to all known consumers for a changed public, shared, serialized or persistent contract whose compatibility depends on them. Stop when the candidates that could change implementation or proof have been read and judged; a search with no match shows only that the search found nothing. Resolve versions from applicable manifests and usage; record a specific limitation only when required compatibility evidence remains unavailable. ## Performance Considerations @@ -120,7 +122,7 @@ One comment per decision. If a comment restates what the names and control flow - Delete commented-out code (retrieve from git history when needed) ### Comment Quality -- Base comments on stable rationale, limits, and contracts rather than dates, versions, or temporary state +- Base comments on stable rationale, limits, and contracts rather than dates, versions, temporary state, or references to documents and their sections, which drift as those documents change - Update comments when changing code - Use proper grammar and formatting - Write for future maintainers @@ -161,3 +163,7 @@ One comment per decision. If a comment restates what the names and control flow - For changes involving identity or protected resources, prioritize authentication and per-resource authorization review For concrete detection patterns used by security review, see `references/security-checks.md`. + +## References + +- [references/frontend.md](references/frontend.md): read when implementing, reviewing, or fixing React/TypeScript code diff --git a/dev-workflows-frontend/skills/coding-principles/references/frontend.md b/dev-workflows-frontend/skills/coding-principles/references/frontend.md new file mode 100644 index 00000000..ba9f0363 --- /dev/null +++ b/dev-workflows-frontend/skills/coding-principles/references/frontend.md @@ -0,0 +1,50 @@ +# Frontend (React/TypeScript) Coding Rules + +Apply these with the SKILL.md principles. Each entry adds what React and TypeScript code needs beyond them; the frontend decision criteria for component responsibility, error boundaries, and profiling live in `references/frontend.md` of the ai-development-guide skill. + +## Type Safety + +**Default Rule**: Prefer `unknown`, generics, or union types over `any`. Retain `any` only when an existing external, generated, or legacy public signature requires it, or when replacing it prevents the project type check from expressing a safe generic relationship. Record the declaration path or type-check result that proves the constraint. When a local adapter can preserve compatibility and expose a safer type within the user request or current task/design artifact, implement the adapter; otherwise confine `any` to the smallest adapter or public-signature boundary, document the reason, and validate untrusted data before it enters typed application code. + +**Frontend Boundaries** + +- React Props/State: use the declared application types. +- External API responses: treat unvalidated payloads as `unknown` and validate at the boundary. A generated client may retain its declared type when it also enforces the contract at runtime. +- `localStorage` / `sessionStorage`: handle `string | null`; treat parsed data as `unknown` until validated. +- URL parameters: handle the router or platform's nullable string shape, then parse and validate before converting to a domain type. +- Exported APIs and important boundaries: declare return types; allow inference for local implementations when the contract remains clear. + +**Type Complexity Review Signals** + +Use these as review prompts, not pass/fail thresholds. Existing project conventions and the component's responsibility take precedence. + +- Props count: review ownership or splitting above 10. +- Optional props: review defaults or ownership when more than half are optional. +- Nested prop structures: review flattening beyond 2 levels. +- Type assertions: review the boundary when 3+ assertions are required. +- External API types: represent the actual external shape and convert at the application boundary. + +## Components and State + +- Prefer function components and Hooks for new code. Preserve working class components unless the accepted work requires migration; a class remains valid for an Error Boundary implementation. +- Follow the project's adopted component architecture and file layout. Co-locate files only when it is established or approved as a new structure. +- Preserve the repository's existing local, shared, and server-state ownership boundaries. Introduce Context, a shared-state layer, or a server-state dependency only when the accepted design requires ownership or lifecycle that the existing boundary cannot represent. +- Keep one authoritative owner for each state value and use the immutable updates React change detection requires. +- Guard effect-driven requests against stale or post-unmount updates through the repository's cancellation or server-state mechanism. + +## Server/Client Boundary — only for RSC frameworks + +- Fetch and render on the server by default; isolate interactivity behind the smallest `"use client"` boundary that needs it. +- Keep browser-only APIs and event handlers inside client components. +- Skip these rules when the project has no server-component runtime. + +## Environment and Client Security + +- Read client-side environment variables through the project's bundler accessor and public prefix. Validate required values through the repository's typed config layer; add a default only for an optional value or an explicitly defined local-development mode. +- Browser-delivered code and public environment variables are observable by clients, so credentials and secrets stay on the server. + +## Performance and Compatibility + +- When React Compiler is enabled, rely on it. Add manual `React.memo`, `useMemo`, or `useCallback` only for a measured bottleneck or a required stable identity at an external API/effect boundary. +- Apply code splitting or import changes when a configured bundle budget regresses, or when the accepted task names bundle size as an outcome and a repository bundle report attributes the relevant increase to the changed import. Follow the repository's existing loading pattern and verify the same signal after the change. +- Implement against the browser support policy in the PRD, Design Doc, Browserslist, or build configuration. When none is defined, preserve the repository's current transpilation/polyfill baseline and surface any new browser-dependent API as an unresolved compatibility decision. diff --git a/dev-workflows-frontend/skills/implementation-approach/SKILL.md b/dev-workflows-frontend/skills/implementation-approach/SKILL.md index 46ee41dc..b9784615 100644 --- a/dev-workflows-frontend/skills/implementation-approach/SKILL.md +++ b/dev-workflows-frontend/skills/implementation-approach/SKILL.md @@ -24,7 +24,7 @@ Historical Context Understanding: Current form rationale, past decision validity - What dependencies or implicit preconditions are unclear from the code? - What benefits and constraints does the current design bring? -Stop when another current-state fact cannot change responsibility, reuse, option validity, total complexity, a contract, or verification. +Stop when the current-state facts that could change responsibility, reuse, option validity, total complexity, a contract, or verification have been checked; find existing code as coding-principles Reference Representativeness describes. ### Phase 2: Design Convergence @@ -32,7 +32,7 @@ Complete these steps in order before selecting an implementation strategy: 1. **Existing-Surface Baseline**: Form the simplest end-to-end path that delivers the current outcome through existing responsibilities. Explicit requirements and accepted decisions are binding; suggested mechanisms remain candidates. 2. **Evidence Check**: Test that path against current requirements, verified constraints, observed in-scope problems, and evidence-backed material risks. Keep only the unmet conditions that can change the selected design. Where the requirements leave a quality level unset, such as performance, freshness, consistency, availability, or protection beyond the required trust boundary, test against the lowest level that still delivers the outcome and record it as the selected level. -3. **Targeted Comparison**: For each unmet condition, test reuse, derivation from existing data, on-demand computation, or responsibility at the current caller or boundary before adding design surface. Compare viable choices by total complexity across the dimensions that materially differ: user decisions, settings, modes, concepts, outputs, persistent state, implementation paths, UX, runtime, implementation, testing, documentation, and maintenance. Select the lowest-total-complexity choice that satisfies the condition. +3. **Targeted Comparison**: For each unmet condition, test reuse, derivation from existing data, on-demand computation, or responsibility at the current caller or boundary before adding design surface. Compare viable choices by total complexity across the dimensions that materially differ: user decisions, settings, modes, concepts, outputs, persistent state, implementation paths, UX, runtime, implementation, testing, documentation, and maintenance. A second implementation of a responsibility that already has an owner with the same contract and change reason, including one added earlier in the same change, adds design surface; reusing or relocating that owner removes it. Select the lowest-total-complexity choice that satisfies the condition. 4. **Subtraction Check**: Remove each proposed addition and re-test its governing condition. Retain it only when the outcome, a required boundary, or necessary proof becomes unmet at its origin (a requirement, an accepted decision, or a repository rule or contract); a criterion, invariant, or constraint that a workflow artifact derived from that origin is narrowed to what the origin requires instead. Classify supporting claims as observed, inferred, or unknown. Route an unknown that blocks the next step as an exact evidence prerequisite; the caller's value-boundary and irreversible-action gates determine whether user interaction is required. diff --git a/dev-workflows-frontend/skills/integration-e2e-testing/SKILL.md b/dev-workflows-frontend/skills/integration-e2e-testing/SKILL.md index aa037f1f..9ad86fdd 100644 --- a/dev-workflows-frontend/skills/integration-e2e-testing/SKILL.md +++ b/dev-workflows-frontend/skills/integration-e2e-testing/SKILL.md @@ -29,6 +29,8 @@ Selection evidence: [required claim, uncovered failure, and why cheaper existing Use the project's comment syntax to wrap these annotations (e.g., `//` for C-family, `#` for Python/Ruby/Shell). +`Selection evidence` serves test selection and planning, so the implementing task removes it when it makes the test executable. + ### Verification Items (Optional) When verification points need explicit enumeration: diff --git a/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md b/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md index f44aa004..53569f2e 100644 --- a/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md @@ -92,7 +92,7 @@ Present the adjustment context to the user for review. ### Step 5: Adjustment + Verification (parent session) 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: coding-principles and read its `references/frontend.md` 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 628b61f3..8bd9cf29 100644 --- a/dev-workflows-frontend/skills/recipe-front-build/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-front-build/SKILL.md @@ -134,4 +134,5 @@ Final report must include: - Commit count - Cleanup result - Declined actionable findings with ID, governing reason, and evidence, when any occurred +- Findings outside the change that remain unhandled, with location and evidence, when any remain - Escalation or blocking summary, if any diff --git a/dev-workflows-frontend/skills/recipe-front-review/SKILL.md b/dev-workflows-frontend/skills/recipe-front-review/SKILL.md index e363bab3..a339b44b 100644 --- a/dev-workflows-frontend/skills/recipe-front-review/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-front-review/SKILL.md @@ -153,7 +153,7 @@ Use the shared **Re-run rule** to select the owners of the findings corrected in Apply Review Resolution to each returned reconciliation. Return maintained applied findings to their correction owner; proceed to Step 9 at convergence. -Before Step 9, retry each retained quality-fixer-frontend limitation once with the same Step 7 inputs and affected check. Remove a limitation when the retry passes, route newly discovered incomplete implementation through Steps 6-8, and report a repeated `verification_incomplete` result. Apply the shared Re-run rule, including its changed-boundary check for mutations outside received findings, before reporting. +Before Step 9, retry each retained quality-fixer-frontend limitation once with the same Step 7 inputs and affected check. Remove a limitation when the retry passes, route newly discovered incomplete implementation through Steps 6-8, and report a repeated `verification_incomplete` result. Apply the shared Re-run rule, including its check of whether the corrections invalidated evidence a passed review relied on, before reporting. ### Step 9: Final Report diff --git a/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md index 887356c6..34ce9448 100644 --- a/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md @@ -211,9 +211,9 @@ Reviewer findings are candidates. Create correction work only from the Review Re **Fix-cycle handoff**: Apply Review Resolution and invoke each correction owner it selects. For an author-owned technical-artifact correction, invoke the layer-appropriate technical designer in update mode, run the artifact's existing document-reviewer and applicable design-sync gates, then re-run the originating reviewer. For an executor-owned correction, invoke the layer-appropriate executor with its original `task_file` or direct-scope fields plus `correction_findings` as the complete `apply` finding objects verbatim with only their dispositions added, then branch on the executor result through the per-task cycle's step 2, including its conditional integration-test-reviewer path, and run the applicable quality gate. When both owners are required, Review Resolution's author-first re-evaluation controls the order. Carry `prior_feedback` only to a reviewer or verifier being rechecked. Post-implementation corrections stay uncommitted through this cycle: the reviewers read the current working tree, so run the applicable quality gate and re-run the originating reviewer on the uncommitted changes, and commit the applied corrections once through Commit Boundary Check after the complete review set reaches Review Resolution convergence. -**Re-run rule**: After an applied post-implementation correction, re-run only the reviewer that owns a corrected finding from its latest result. For these finding-owned corrections, retain every passed reviewer result, including after another reviewer's correction. Pass the previous complete result, dispositions, and correction diff or paths to the rerun. After Specialist Result Acceptance recovers a blocked review prerequisite, re-run that reviewer. Review Resolution convergence governs acceptance and preserves resolved declines. +**Re-run rule**: After an applied post-implementation correction, re-run only the reviewer that owns a corrected finding from its latest result. Retain every other passed reviewer result, including after another reviewer's correction, unless the check below finds that the correction invalidated the evidence that review relied on. Pass the previous complete result, dispositions, and correction diff or paths to the rerun. After Specialist Result Acceptance recovers a blocked review prerequisite, re-run that reviewer. Review Resolution convergence governs acceptance and preserves resolved declines. -When a quality-fixer retry changes behavior outside the received findings, compare its actual diff against the already reviewed boundaries. Reconcile changes covered by an existing finding through its owner. For other behavior changes that invalidate review evidence, invoke only the applicable code-reviewer or security-reviewer with the original governing documents and the affected `implementationFiles`, scoped to that diff and its directly affected boundary; omit `prior_feedback` because this is new changed code, not finding reconciliation. Apply Review Resolution to its findings. Retain unaffected passed results; unchanged output and behavior-neutral formatting require no review. This check does not reopen a passed reviewer merely because another reviewer’s correction touched the same file. +After a correction or quality-fixer retry, compare its actual diff against the contracts, behavior, and verification evidence that the passed reviews relied on, whether or not the change stays inside the received findings: a shared contract corrected for one unit's finding can invalidate another unit's pass. Reconcile changes covered by an existing finding through its owner. For other changes that invalidate review evidence, invoke only the applicable code-reviewer or security-reviewer with the original governing documents and the affected `implementationFiles`, scoped to that diff and its directly affected boundary; omit `prior_feedback` because this is new changed code, not finding reconciliation. Apply Review Resolution to its findings. Retain unaffected passed results; unchanged output and behavior-neutral formatting require no review. This check does not reopen a passed reviewer merely because another reviewer’s correction touched the same file. ### Conditions for Stopping Autonomous Execution @@ -262,6 +262,8 @@ Derive the values from the quality-fixer result. Keep the complete result in orc - `pass` → Proceed to step 4 4. **Commit**: apply Commit Boundary Check, then compose the message from `changeSummary` and execute git commit with Bash after `pass` or `verification_incomplete`; append the verification trailers for the latter +**Findings outside the change**: Retain each executor `findingsOutsideChange` item; one the outcome needs is incomplete implementation under Specialist Result Acceptance. When the workflow runs post-implementation review, an item in work this workflow produced enters Review Resolution with the review findings, and the code-reviewer whose `implementationFiles` contain its location owns an applied one. List the items left unhandled with their location and evidence in the completion report. + Before post-implementation verifiers, collect retained verification limitations from orchestration state and the verification trailers on task-boundary commits created by the workflow, then re-invoke the applicable quality-fixer once for each limitation using the same task inputs and its affected check or command. When the retry returns `pass`, remove that limitation from retained state. Route newly discovered incomplete implementation through the normal cycle, and retain a repeated `verification_incomplete` result for the final report. Commit any fixes produced by this retry through the same task cycle, then continue post-implementation verification. ## Handoff Contracts diff --git a/dev-workflows-frontend/skills/testing-principles/references/e2e.md b/dev-workflows-frontend/skills/testing-principles/references/e2e.md index b0e06542..df87bf72 100644 --- a/dev-workflows-frontend/skills/testing-principles/references/e2e.md +++ b/dev-workflows-frontend/skills/testing-principles/references/e2e.md @@ -42,4 +42,4 @@ Use the repository's existing seed and authentication mechanisms. Create per-tes ## Skeleton Annotations -Preserve the skeleton's annotations unchanged. When `Verification items:` are present, implement and assert every listed item. +Preserve the skeleton's annotations unchanged, except `Selection evidence`, which served test selection only and is removed when the test becomes executable. When `Verification items:` are present, implement and assert every listed item. diff --git a/dev-workflows-frontend/skills/testing-principles/references/frontend.md b/dev-workflows-frontend/skills/testing-principles/references/frontend.md index 9b683622..a961645e 100644 --- a/dev-workflows-frontend/skills/testing-principles/references/frontend.md +++ b/dev-workflows-frontend/skills/testing-principles/references/frontend.md @@ -7,7 +7,7 @@ Before writing a test, inspect package scripts, runner configuration, setup file - Use React Testing Library when it is the project's component-test renderer; prefer `userEvent` for user interactions. - Use the repository's network mocking layer for API behavior. When MSW is configured, extend its handlers instead of adding runner-level fetch mocks. - Use the configured runner's imports, module-mocking API, fake timers, and reset conventions. -- When multiple approaches coexist, follow the dominant convention in the changed feature area. If none is representative and adding or replacing tooling is outside the approved work, report the missing test-environment decision. +- When multiple approaches coexist, choose from the behavior under test and the setup the repository maintains for it rather than from proximity alone. If none is representative and adding or replacing tooling is outside the approved work, report the missing test-environment decision. ## Test Scope diff --git a/dev-workflows-frontend/skills/typescript-rules/SKILL.md b/dev-workflows-frontend/skills/typescript-rules/SKILL.md deleted file mode 100644 index df4751bd..00000000 --- a/dev-workflows-frontend/skills/typescript-rules/SKILL.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -name: typescript-rules -description: React/TypeScript frontend development rules including type safety, component design, state management, and error handling. Use when implementing React components, TypeScript code, or frontend features. ---- - -# TypeScript Development Rules (Frontend) - -## Comment Writing Rules - -Code first: names and types carry meaning; a comment must add what code cannot, and one comment per decision is enough. - -- Explain why a component memoizes, guards, or re-renders, not what the JSX renders. -- Record decisions and rationale; leave chronological history to version control. - -## Type Safety - -**Default Rule**: Prefer `unknown`, generics, or union types over `any`. Retain `any` only when an existing external, generated, or legacy public signature requires it, or when replacing it prevents the project type check from expressing a safe generic relationship. Record the declaration path or type-check result that proves the constraint. When a local adapter can preserve compatibility and expose a safer type within the user request or current task/design artifact, implement the adapter; otherwise confine `any` to the smallest adapter or public-signature boundary, document the reason, and validate untrusted data before it enters typed application code. - -**Frontend Boundaries** - -- React Props/State: use the declared application types. -- External API responses: treat unvalidated payloads as `unknown` and validate at the boundary. A generated client may retain its declared type when it also enforces the contract at runtime. -- `localStorage` / `sessionStorage`: handle `string | null`; treat parsed data as `unknown` until validated. -- URL parameters: handle the router or platform's nullable string shape, then parse and validate before converting to a domain type. -- Exported APIs and important boundaries: declare return types; allow inference for local implementations when the contract remains clear. - -**Type Complexity Review Signals** - -Use these as review prompts, not pass/fail thresholds. Existing project conventions and the component's responsibility take precedence. - -- Props count: review ownership or splitting above 10. -- Optional props: review defaults or ownership when more than half are optional. -- Nested prop structures: review flattening beyond 2 levels. -- Type assertions: review the boundary when 3+ assertions are required. -- External API types: represent the actual external shape and convert at the application boundary. - -## Coding Conventions - -**Component and File Decisions** - -- Prefer function components and Hooks for new code. Preserve working class components unless the accepted work requires migration; a class remains valid for an Error Boundary implementation. -- Reuse logic through the repository's established component, hook, or module pattern. -- Follow the project's adopted component architecture and file layout. Co-locate files only when it is established or approved as a new structure. - -**Server/Client Boundary — only for RSC frameworks** - -- Fetch and render on the server by default; isolate interactivity behind the smallest `"use client"` boundary that needs it. -- Keep browser-only APIs and event handlers inside client components. -- Skip these rules when the project has no server-component runtime. - -**State Ownership** - -- Preserve the repository's existing local, shared, and server-state ownership boundaries. -- Introduce Context, a shared-state layer, or a server-state dependency only when the accepted design requires ownership or lifecycle that the existing boundary cannot represent. -- Keep one authoritative owner for each state value and use immutable updates required by React change detection. - -**Function and Props Boundaries** - -- Prefer 0-2 parameters. For 3+ related values, use an object when it clarifies names or represents one domain input; preserve positional parameters when the repository convention or external API requires them. -- Declare component dependencies through typed props, hooks, Context, or injected modules according to the repository's established state and dependency boundaries. - -**Environment Variables** - -- Read client-side environment variables through the project's bundler accessor and public prefix. -- Validate required values through the repository's typed config layer; add a default only for an optional value or an explicitly defined local-development mode. - -**Client Security** - -- Keep credentials and secrets on the server; browser-delivered code and public environment variables are observable by clients. -- Exclude local environment files from version control and keep error output free of sensitive values. - -**Asynchronous Processing** - -- Follow the repository's promise style; use `async`/`await` when it clarifies sequencing and error propagation. -- Handle event-handler and asynchronous failures at their owning boundary. Error Boundaries cover descendant rendering failures, not ordinary callbacks or asynchronous work. -- Guard effect-driven requests against stale or post-unmount updates through the repository's cancellation or server-state mechanism. - -**Formatting** - -- Follow the repository's formatter, naming, module-resolution, and package-boundary configuration. -- Use an import alias only when the project configuration resolves it. - -## Error Handling - -Every caught error has one intentional outcome: propagate it, convert it to the repository's typed boundary result, or represent it as user-facing error state. Preserve context and log once at the boundary that owns diagnosis or recovery, with sensitive data redacted. - -- Error Boundary: place it where descendant render failures have a defined UI recovery outcome. -- Custom Hook: preserve the application's existing error contract. -- API Layer: convert transport failures to the repository's established domain or boundary representation. -- Event handlers and async workflows: use the owning layer's exception, result, or UI-state contract. - -## Performance Optimization - -- When React Compiler is enabled, rely on it. Add manual `React.memo`, `useMemo`, or `useCallback` only for a measured bottleneck or a required stable identity at an external API/effect boundary. -- Apply code splitting or import changes when a configured bundle budget regresses, or when the accepted task names bundle size as an outcome and a repository bundle report attributes the relevant increase to the changed import. Follow the repository's existing loading pattern and verify the same signal after the change. - -## Non-functional Requirements - -- **Browser Compatibility**: Implement against the support policy in the PRD, Design Doc, Browserslist, or build configuration. When none is defined, preserve the repository's current transpilation/polyfill baseline and surface any new browser-dependent API as an unresolved compatibility decision. -- **Performance**: Verify against project-defined budgets and the metric representing the affected experience. When no budget exists, measure the changed path and report the observed result instead of inventing a threshold. diff --git a/dev-workflows-fullstack/.claude-plugin/plugin.json b/dev-workflows-fullstack/.claude-plugin/plugin.json index a9b7acb5..a0faf89a 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.30.0", + "version": "0.31.0", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows-fullstack/agents/acceptance-test-generator.md b/dev-workflows-fullstack/agents/acceptance-test-generator.md index 5903323f..f9170cb2 100644 --- a/dev-workflows-fullstack/agents/acceptance-test-generator.md +++ b/dev-workflows-fullstack/agents/acceptance-test-generator.md @@ -41,6 +41,8 @@ Each selected test records: - proof obligation: boundary to traverse, expected state/results, pass criteria, real dependencies and permissible substitutes; - a distinct branch, state, lifecycle or fallback path when the main path could remain green through a material regression. +File-level comments hold only what the completed tests keep, such as the lane declaration and setup the tests share; each test's record carries the rest. + Keep executable assertions and mock implementation for the implementing task. Test Boundaries marking a dependency as real are carried as `@real-dependency: [component]`. ## Output diff --git a/dev-workflows-fullstack/agents/code-reviewer.md b/dev-workflows-fullstack/agents/code-reviewer.md index 7b801887..44d8ad95 100644 --- a/dev-workflows-fullstack/agents/code-reviewer.md +++ b/dev-workflows-fullstack/agents/code-reviewer.md @@ -19,7 +19,7 @@ Verify by reading the changed code and tests. Running tests and quality checks i ## Inputs - **governingDocuments**: One or more approved Design Docs, or the resolved Work Plan when the caller has no Design Doc, as a list of document paths -- **implementationFiles**: The complete set of implementation, test, schema, build, deployment, and runtime-configuration artifacts in the reviewed change +- **implementationFiles**: The implementation, test, schema, build, deployment, and runtime-configuration artifacts whose changes this review judges: the complete change, or one review unit of it - **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 @@ -31,6 +31,7 @@ Before reviewing, read these files; they hold review criteria beyond the preload - `references/frontend.md` in the testing-principles skill - `references/frontend.md` in the ai-development-guide skill +- `references/frontend.md` in the coding-principles skill - `references/e2e.md` in the testing-principles skill ## Initial Review @@ -40,7 +41,7 @@ Extract the approved outcome, applicable acceptance criteria, changed interfaces Judge the material surfaces in `implementationFiles` against these criteria: - **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. +- **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 code or tests that already hold the same responsibility, in the repository or elsewhere in this change (coding-principles Reference Representativeness), 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. diff --git a/dev-workflows-fullstack/agents/code-verifier.md b/dev-workflows-fullstack/agents/code-verifier.md index 2c717c5e..0f4ea016 100644 --- a/dev-workflows-fullstack/agents/code-verifier.md +++ b/dev-workflows-fullstack/agents/code-verifier.md @@ -39,7 +39,7 @@ For reverse-engineered/as-is documents, verify every supplied inventory item at Use one authoritative definition when it directly proves an identifier or contract. Seek another source when behavior, indirection, or conflicting evidence makes it decision-relevant. Base confidence on evidence quality rather than source count. -Stop expanding the search when additional evidence cannot change a discrepancy or limitation. +Stop expanding the search when the evidence that could change a discrepancy or limitation has been checked; find existing code as coding-principles Reference Representativeness describes. ## Rerun Boundary diff --git a/dev-workflows-fullstack/agents/codebase-analyzer.md b/dev-workflows-fullstack/agents/codebase-analyzer.md index 13c58dec..80d0bfec 100644 --- a/dev-workflows-fullstack/agents/codebase-analyzer.md +++ b/dev-workflows-fullstack/agents/codebase-analyzer.md @@ -32,7 +32,7 @@ Return a fact only when it can: - identify a lifecycle-cost or maintainability difference; or - select a verification boundary. -Stop expanding the search when another fact cannot change one of those outcomes. Inspect all known consumers only for a public, shared, serialized, persistent, security, or error contract whose complete consumer set controls compatibility. Otherwise, representative callers, tests, configuration, and siblings are sufficient. +Existing code with the same responsibility as a new surface may share no name or reference with it; look for reuse through position and role (sibling features, files with the same role in the same layer, shared layers) and through shared input and purpose, as well as through references. Stop expanding the search when the facts that could change one of those outcomes have been checked; a search with no match shows only that the search found nothing. Inspect all known consumers only for a public, shared, serialized, persistent, security, or error contract whose complete consumer set controls compatibility. Otherwise, representative callers, tests, configuration, and siblings are sufficient. ## Execution Steps diff --git a/dev-workflows-fullstack/agents/quality-fixer-frontend.md b/dev-workflows-fullstack/agents/quality-fixer-frontend.md index 1d119f14..c92a9ca4 100644 --- a/dev-workflows-fullstack/agents/quality-fixer-frontend.md +++ b/dev-workflows-fullstack/agents/quality-fixer-frontend.md @@ -3,7 +3,7 @@ name: quality-fixer-frontend description: Specialized agent for verifying React projects and fixing frontend quality failures within the current task scope. Use proactively after code changes or for quality, test, build, lint, format, type, or fix requests. tools: Bash, Read, Edit, MultiEdit, Grep, Glob, LS skills: - - typescript-rules + - coding-principles - testing-principles - ai-development-guide - external-resource-context @@ -77,7 +77,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 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. +Apply fixes per coding-principles, testing-principles, and ai-development-guide skills, reading `references/frontend.md` in the coding-principles skill for frontend coding rules and 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 @@ -96,15 +96,15 @@ Return one of the following as the final response (see Output Format for schemas ## Frontend-Specific Quality Criteria ### Repository-Local Choice Discipline -Prefer repository-local component patterns over generic React advice; when patterns coexist for the same concern, follow the dominant one in the changed feature area — the surrounding feature folder, or the nearest parent directory containing siblings using the same concern. When no repository choice covers the concern, select the lowest-surface sufficient option using the governing value boundary and available technical evidence; novelty alone is not a reason for `blocked`. +Prefer repository-local component patterns over generic React advice; when patterns coexist for the same concern, choose as coding-principles Reference Representativeness describes. When no repository choice covers the concern, select the lowest-surface sufficient option using the governing value boundary and available technical evidence; novelty alone is not a reason for `blocked`. ### Testing Quality - **Mock layering**: Browser-primitive doubles (e.g., ResizeObserver, IntersectionObserver, time, router/provider) are acceptable when the test environment requires them; the component under test is exercised through real renders and user interactions - **Query selection**: Prefer role/name queries for user-visible elements; use async queries (`findBy*`, `waitFor`) for async appearance and `queryBy*`/`queryAllBy*` only when asserting intentional absence ### Build Quality -- **Zero Type Errors**: TypeScript build must succeed without errors; Props and State have explicit type definitions. Permit `any` only at an evidence-backed, narrowly bounded exception that satisfies typescript-rules -- **Bundle / code-splitting fixes**: Apply the evidence and verification rule in typescript-rules +- **Zero Type Errors**: TypeScript build must succeed without errors; Props and State have explicit type definitions. Permit `any` only at an evidence-backed, narrowly bounded exception that satisfies the coding-principles frontend reference +- **Bundle / code-splitting fixes**: Apply the evidence and verification rule in the coding-principles frontend reference ## Status Determination Criteria @@ -228,7 +228,7 @@ Between tool calls, briefly report: which phase is running, the command executed - **Clear Type Error Fixes** - Add import statements (when types not found) - Add type annotations for Props/State (when inference impossible) - - Replace `any` with `unknown` plus validation for untyped external API responses; preserve only the documented, bounded exceptions allowed by typescript-rules + - Replace `any` with `unknown` plus validation for untyped external API responses; preserve only the documented, bounded exceptions allowed by the coding-principles frontend reference - Add optional chaining - **Clear Code Quality Issues** - Remove unused variables/functions/components @@ -243,15 +243,15 @@ Between tool calls, briefly report: which phase is running, the command executed - Integration test failure: Investigate and fix component integration - Boundary value test failure: Confirm specification and fix - **Bundle / Rendering Optimization** - - Apply only when Step 3 reports bundle evidence that satisfies typescript-rules or profiler evidence identifies the changed render path + - Apply only when Step 3 reports bundle evidence that satisfies the coding-principles frontend reference or profiler evidence identifies the changed render path - Use the repository's existing loading/import pattern and the smallest fix that addresses that evidence; re-run the same bundle or profiler signal - - Add manual memoization only for the profiler- or identity-based conditions in typescript-rules + - Add manual memoization only for the profiler- or identity-based conditions in the coding-principles frontend reference - **Structural Issues** - Resolve circular dependencies (extract to common modules) - Split components when independent rendering, state, data, or test responsibilities create material coupling or verification cost; retain a cohesive component when splitting would add avoidable prop/state synchronization - Refactor deeply nested conditionals - **Type Error Fixes** - - Resolve external API response types by the typescript-rules boundary validation policy + - Resolve external API response types by the coding-principles frontend reference's boundary validation policy - Add necessary Props type definitions - Flexibly handle with generics or union types @@ -286,7 +286,7 @@ All fixes must satisfy these criteria: |----------|------------| | Test integrity | Tests remain executable and active (no `it.skip`, no deletion for convenience) | | Assertion quality | Every test contains meaningful assertions that verify behavior (not `expect(true).toBe(true)`) | -| Type safety | Prefer explicit types (`unknown`, generics, unions); permit only documented, bounded `any` exceptions from typescript-rules and justified project-configured suppressions | +| Type safety | Prefer explicit types (`unknown`, generics, unions); permit only documented, bounded `any` exceptions from the coding-principles frontend reference and justified project-configured suppressions | | Error handling | Handle errors with context (log, propagate, or recover with specific handling) | | Environment separation | Keep test-specific branches (e.g. `import.meta.env.MODE` checks) outside production code | | ESLint compliance | Preserve ESLint rules (add justification comments when override is necessary) | diff --git a/dev-workflows-fullstack/agents/task-executor-frontend.md b/dev-workflows-fullstack/agents/task-executor-frontend.md index 6fba977f..4ec2c73d 100644 --- a/dev-workflows-fullstack/agents/task-executor-frontend.md +++ b/dev-workflows-fullstack/agents/task-executor-frontend.md @@ -3,7 +3,7 @@ name: task-executor-frontend description: Executes React implementation completely self-contained from an explicit prompt or frontend task file. Use when frontend task files exist, or when "frontend implementation/React implementation/component creation" is mentioned. Asks no questions, executes consistently from investigation to implementation. tools: Read, Edit, Write, MultiEdit, Bash, Grep, Glob, LS skills: - - typescript-rules + - coding-principles - testing-principles - ai-development-guide - implementation-approach @@ -12,6 +12,8 @@ skills: You are a specialized AI assistant for reliably executing frontend implementation tasks. +You own how this codebase is built and you will keep building on it, so what you leave behind is yours to maintain. What it is for — the outcome, requirements, and non-goals — stays with the user's recorded decisions. + Operates in an independent context, executing autonomously until task completion. ## Input Parameters @@ -42,7 +44,7 @@ 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-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. +Apply loaded coding-principles, testing-principles, and ai-development-guide rules during implementation, and read `references/frontend.md` in the coding-principles and ai-development-guide skills before implementing; they hold the frontend coding rules and criteria. When `docs/project-context/quality.yaml` exists, use it as implementation guidance. @@ -75,7 +77,7 @@ Use the indicators to find plausible candidates and apply the authoritative boun 1. Compare responsibility, props/contract, lifecycle and state ownership, design-system role, and representative repository usage. 2. Record one `reuseDecisions` entry: - `reuse` or `extend` when those dimensions are compatible; - - `separate` when sharing would merge independently evolving responsibilities or add more prop/state synchronization and contract surface than it removes. + - `separate` when evidence shows different contracts or change reasons, or when sharing would add more prop/state synchronization and contract surface than it removes. 3. Continue with the repository-local reversible choice supported by that evidence. ### Step4: Core Mechanism Preservation Check @@ -148,14 +150,12 @@ Classify from the task outcome and changed boundary, then run after Pre-implemen #### Reference Representativeness (Applied During Implementation) -When adopting a pattern, hook, or library from existing code, apply Reference Representativeness at the point of adoption: - -Apply coding-principles Reference Representativeness using the changed area and representative consumers or siblings. Expand to all known consumers when a changed shared/public contract requires compatibility accounting. Record the evidence for a material choice among competing patterns; stop when further search cannot change implementation or proof. +When adopting a pattern, hook, or library from existing code, apply coding-principles Reference Representativeness at the point of adoption. #### 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. +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. When completing a skeleton, remove its `Selection evidence` lines, which served test selection only, and keep its other annotations for test review and lane routing. #### Operation Verification - Execute the Operation Verification Methods in the execution instructions @@ -190,6 +190,8 @@ Return the final response per Structured Response Specification. For research/an **reuseDecisions**: Use `[]` when no plausible similar component or hook was found. Otherwise include the decision-relevant candidates evaluated in Step 3 with `decision: "reuse" | "extend" | "separate"` and evidence covering responsibility, props/contract, lifecycle/state ownership, design-system role, and repository representativeness. +**findingsOutsideChange**: Use `[]` when none. Otherwise list problems already observed during this task that the change leaves unhandled, because handling them belongs to another responsibility, would change the outcome or a non-goal, or needs an irreversible external action. Each item gives its location, evidence, and that reason. The field reports observations; it creates no search obligation. + ### 1. Task Completion Response Complete this agent's work by returning the following JSON; the quality assurance process performs quality checks and commits: @@ -202,6 +204,7 @@ Complete this agent's work by returning the following JSON; the quality assuranc "requiresTestReview": false, "newTestsPassed": true, "reuseDecisions": [{"candidate": "[path:component-or-hook]", "decision": "reuse | extend | separate", "evidence": "[Responsibility, props/contract, lifecycle/state ownership, design-system role, and repository-representativeness evidence]"}], + "findingsOutsideChange": [{"location": "[path:symbol]", "evidence": "[Observed fact]", "reason": "[Why this change leaves it unhandled]"}], "runnableCheck": {"level": "L1: Functional Operation Verification / L2: Test Operation Verification / L3: Build Success Verification", "executed": true, "command": "Executed verification command", "result": "passed / failed / skipped", "reason": "Verification content or exact limitation"}, "mutationEvidence": [{"mutation": "[description or patch]", "killedTest": "[test name]", "baselineResult": "[baseline command and result]", "mutatedResult": "[mutated command and result]", "restorationProof": "[restoration checksum or clean diff]", "targetRevision": "[revision or file hashes]"}] } diff --git a/dev-workflows-fullstack/agents/task-executor.md b/dev-workflows-fullstack/agents/task-executor.md index ffc23b25..f6a9167e 100644 --- a/dev-workflows-fullstack/agents/task-executor.md +++ b/dev-workflows-fullstack/agents/task-executor.md @@ -12,6 +12,8 @@ skills: You are a specialized AI assistant for reliably executing individual tasks. +You own how this codebase is built and you will keep building on it, so what you leave behind is yours to maintain. What it is for — the outcome, requirements, and non-goals — stays with the user's recorded decisions. + ## Input Parameters Workflow callers use the applicable canonical fields below: @@ -70,7 +72,7 @@ Use the indicators to find plausible candidates and apply the authoritative boun 1. Compare responsibility, contract, lifecycle, and representative repository usage. 2. Record one `reuseDecisions` entry: - `reuse` or `extend` when those dimensions are compatible; - - `separate` when sharing would merge independently evolving responsibilities or add more contract surface than it removes. + - `separate` when evidence shows different contracts or change reasons, or when sharing would add more coupling and contract surface than it removes. 3. Continue with the repository-local reversible choice supported by that evidence. ### Step4: Core Mechanism Preservation Check @@ -143,15 +145,13 @@ Classify from the task outcome and changed boundary, then run after Pre-implemen #### Reference Representativeness (Applied During Implementation) -When adopting a pattern or dependency from existing code, apply coding-principles "Reference Representativeness" at the point of adoption: - -Apply coding-principles Reference Representativeness using the changed area and representative consumers or siblings. Expand to all known consumers when a changed shared/public contract requires compatibility accounting. Record the evidence for a material choice among competing patterns; stop when further search cannot change implementation or proof. +When adopting a pattern or dependency from existing code, apply coding-principles Reference Representativeness at the point of adoption. #### 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 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. +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. When completing a skeleton, remove its `Selection evidence` lines, which served test selection only, and keep its other annotations for test review and lane routing. #### Operation Verification - Execute the Operation Verification Methods in the execution instructions @@ -186,6 +186,8 @@ Return the final response per Structured Response Specification. For research/an **reuseDecisions**: Use `[]` when no plausible similar implementation was found. Otherwise include the decision-relevant candidates evaluated in Step 3 with `decision: "reuse" | "extend" | "separate"` and evidence covering responsibility, contract, lifecycle, and repository representativeness. +**findingsOutsideChange**: Use `[]` when none. Otherwise list problems already observed during this task that the change leaves unhandled, because handling them belongs to another responsibility, would change the outcome or a non-goal, or needs an irreversible external action. Each item gives its location, evidence, and that reason. The field reports observations; it creates no search obligation. + ### 1. Task Completion Response Complete this agent's work by returning the following JSON; the quality assurance process performs quality checks and commits: @@ -198,6 +200,7 @@ Complete this agent's work by returning the following JSON; the quality assuranc "requiresTestReview": true, "newTestsPassed": true, "reuseDecisions": [{"candidate": "[path:symbol]", "decision": "reuse | extend | separate", "evidence": "[Responsibility, contract, lifecycle, and repository-representativeness evidence]"}], + "findingsOutsideChange": [{"location": "[path:symbol]", "evidence": "[Observed fact]", "reason": "[Why this change leaves it unhandled]"}], "runnableCheck": {"level": "L1: Functional Operation Verification / L2: Test Operation Verification / L3: Build Success Verification", "executed": true, "command": "Executed verification command", "result": "passed / failed / skipped", "reason": "Verification content or exact limitation"}, "mutationEvidence": [{"mutation": "[description or patch]", "killedTest": "[test name]", "baselineResult": "[baseline command and result]", "mutatedResult": "[mutated command and result]", "restorationProof": "[restoration checksum or clean diff]", "targetRevision": "[revision or file hashes]"}] } diff --git a/dev-workflows-fullstack/agents/technical-designer-frontend.md b/dev-workflows-fullstack/agents/technical-designer-frontend.md index ed5c24e2..f215ff00 100644 --- a/dev-workflows-fullstack/agents/technical-designer-frontend.md +++ b/dev-workflows-fullstack/agents/technical-designer-frontend.md @@ -15,6 +15,8 @@ skills: You create one complete frontend ADR batch or one frontend Design Doc per invocation. +You own how this codebase is built and you will keep building on it, so what you leave behind is yours to maintain. What it is for — the outcome, requirements, and non-goals — stays with the user's recorded decisions. + ## Execution Gate 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. diff --git a/dev-workflows-fullstack/agents/technical-designer.md b/dev-workflows-fullstack/agents/technical-designer.md index b01a6322..c097d31b 100644 --- a/dev-workflows-fullstack/agents/technical-designer.md +++ b/dev-workflows-fullstack/agents/technical-designer.md @@ -15,6 +15,8 @@ skills: You create one complete ADR batch or one Design Doc per invocation. +You own how this codebase is built and you will keep building on it, so what you leave behind is yours to maintain. What it is for — the outcome, requirements, and non-goals — stays with the user's recorded decisions. + ## Execution Gate 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. diff --git a/dev-workflows-fullstack/agents/ui-analyzer.md b/dev-workflows-fullstack/agents/ui-analyzer.md index a2ad0c82..cf1a4f04 100644 --- a/dev-workflows-fullstack/agents/ui-analyzer.md +++ b/dev-workflows-fullstack/agents/ui-analyzer.md @@ -27,7 +27,7 @@ Use only supplied `external_resource_refs`. Resolve their labels through `docs/p Locate the affected screens, components, and callers, then inspect only the render, state, style, interaction, and data path needed for the current decisions. Include Props and variants, DOM or layout behavior, display conditions, responsive behavior, accessibility, localization, and generated artifacts when they can change the result, a preserved contract, reuse, or verification. From evidence already gathered, record a simplification when a responsibility, branch, artifact, or change can be omitted while the outcome still holds; it remains a candidate for the parent and document owner. Inspect every consumer only when the complete consumer set controls compatibility; otherwise use representative consumers, tests, stories, and style peers. -Stop when another fact cannot change one of those outcomes. +Stop when the facts that could change one of those outcomes have been checked; a search with no match shows only that the search found nothing. ## Output Format diff --git a/dev-workflows-fullstack/agents/ui-spec-designer.md b/dev-workflows-fullstack/agents/ui-spec-designer.md index f70a6501..eba08510 100644 --- a/dev-workflows-fullstack/agents/ui-spec-designer.md +++ b/dev-workflows-fullstack/agents/ui-spec-designer.md @@ -4,7 +4,6 @@ description: Creates UI Specifications from requirements and optional prototype tools: Read, Write, Edit, MultiEdit, Glob, LS, Bash skills: - documentation-criteria - - typescript-rules - ai-development-guide - llm-friendly-context - external-resource-context diff --git a/dev-workflows-fullstack/skills/ai-development-guide/SKILL.md b/dev-workflows-fullstack/skills/ai-development-guide/SKILL.md index 70fbfe0a..352ad685 100644 --- a/dev-workflows-fullstack/skills/ai-development-guide/SKILL.md +++ b/dev-workflows-fullstack/skills/ai-development-guide/SKILL.md @@ -108,7 +108,7 @@ Keep concrete implementations separate while their apparent similarity is accide **Cases to Avoid Commonalization** - Accidental matches (coincidentally same code) -- Possibility of evolving in different directions +- Contracts or change reasons that evidence shows differ - Significant readability decrease from commonalization - Simple helpers in test code @@ -138,12 +138,11 @@ Keep concrete implementations separate while their apparent similarity is accide **Symptom**: Duplicate implementations, architecture inconsistency, integration failures, adopting outdated patterns **Cause**: Insufficient understanding of existing code before implementation; referencing only nearby files without verifying representativeness **Avoidance Methods**: -- Before implementation, always search for similar functionality (using domain, responsibility, configuration patterns as keywords) +- Before implementation, find functionality that already holds the same responsibility and the code that depends on the change, as coding-principles Reference Representativeness describes; similar functionality may share no name with the new code - Similar functionality found → Verify that its contract, lifecycle, and repository usage are representative; reuse or extend it when compatible, otherwise record why it is not a valid model - Similar functionality is technical debt → Repair it when it blocks the current outcome, was caused by the current change, or lies in scope; otherwise report it separately. Create an ADR when the repair requires an architectural decision - No similar functionality exists → Implement new functionality following existing design philosophy - Preserve the evidence for each reuse, extend, separate, or repair decision in the applicable implementation or design record -- **Reference representativeness check**: When adopting a pattern or dependency from nearby code, inspect the changed area and enough representative consumers or siblings to establish compatibility; expand only when competing patterns or a shared/public contract can change the choice ## Quality Assurance Mechanism Awareness @@ -168,7 +167,7 @@ Follow repository-declared command composition or ordering when it exists. Other ## Situations Requiring Technical Decisions ### Timing of Abstraction -- Extract a shared abstraction after repository evidence establishes a shared responsibility and coordinated change pattern +- Extract a shared abstraction after repository evidence shows a responsibility with the same contract and change reason maintained in more than one place - Be conscious of YAGNI, implement only currently needed features - Prioritize current simplicity over future extensibility diff --git a/dev-workflows-fullstack/skills/coding-principles/SKILL.md b/dev-workflows-fullstack/skills/coding-principles/SKILL.md index bd3ede0b..d45bce62 100644 --- a/dev-workflows-fullstack/skills/coding-principles/SKILL.md +++ b/dev-workflows-fullstack/skills/coding-principles/SKILL.md @@ -70,9 +70,11 @@ description: Language-agnostic coding principles for maintainability, readabilit ## Reference Representativeness -Inspect the changed responsibility and enough representative callers, consumers, configuration and siblings to establish a compatible pattern or dependency. Nearby code is a starting point; when alternatives coexist, choose from their responsibility, contract, lifecycle and repository usage rather than proximity or global popularity alone. Record the evidence only when it changes the choice. +Existing code relates to a change in two ways. Code that depends on it — callers, consumers, configuration — is reached through references to the changed code. Code that already holds the same responsibility may share no name or reference with it; reach it through position and role (sibling features, files with the same role in the same layer, shared layers) and through the input it takes and the purpose it serves, then compare their logic to judge whether the responsibility is the same. -Expand to all known consumers for a changed public, shared, serialized or persistent contract whose compatibility depends on them. Otherwise stop when additional inspection cannot change implementation or proof. Resolve versions from applicable manifests and usage; record a specific limitation only when required compatibility evidence remains unavailable. +When alternatives coexist, choose the pattern from responsibility, contract, lifecycle and repository usage rather than proximity or global popularity alone. Record the evidence only when it changes the choice. + +Expand to all known consumers for a changed public, shared, serialized or persistent contract whose compatibility depends on them. Stop when the candidates that could change implementation or proof have been read and judged; a search with no match shows only that the search found nothing. Resolve versions from applicable manifests and usage; record a specific limitation only when required compatibility evidence remains unavailable. ## Performance Considerations @@ -120,7 +122,7 @@ One comment per decision. If a comment restates what the names and control flow - Delete commented-out code (retrieve from git history when needed) ### Comment Quality -- Base comments on stable rationale, limits, and contracts rather than dates, versions, or temporary state +- Base comments on stable rationale, limits, and contracts rather than dates, versions, temporary state, or references to documents and their sections, which drift as those documents change - Update comments when changing code - Use proper grammar and formatting - Write for future maintainers @@ -161,3 +163,7 @@ One comment per decision. If a comment restates what the names and control flow - For changes involving identity or protected resources, prioritize authentication and per-resource authorization review For concrete detection patterns used by security review, see `references/security-checks.md`. + +## References + +- [references/frontend.md](references/frontend.md): read when implementing, reviewing, or fixing React/TypeScript code diff --git a/dev-workflows-fullstack/skills/coding-principles/references/frontend.md b/dev-workflows-fullstack/skills/coding-principles/references/frontend.md new file mode 100644 index 00000000..ba9f0363 --- /dev/null +++ b/dev-workflows-fullstack/skills/coding-principles/references/frontend.md @@ -0,0 +1,50 @@ +# Frontend (React/TypeScript) Coding Rules + +Apply these with the SKILL.md principles. Each entry adds what React and TypeScript code needs beyond them; the frontend decision criteria for component responsibility, error boundaries, and profiling live in `references/frontend.md` of the ai-development-guide skill. + +## Type Safety + +**Default Rule**: Prefer `unknown`, generics, or union types over `any`. Retain `any` only when an existing external, generated, or legacy public signature requires it, or when replacing it prevents the project type check from expressing a safe generic relationship. Record the declaration path or type-check result that proves the constraint. When a local adapter can preserve compatibility and expose a safer type within the user request or current task/design artifact, implement the adapter; otherwise confine `any` to the smallest adapter or public-signature boundary, document the reason, and validate untrusted data before it enters typed application code. + +**Frontend Boundaries** + +- React Props/State: use the declared application types. +- External API responses: treat unvalidated payloads as `unknown` and validate at the boundary. A generated client may retain its declared type when it also enforces the contract at runtime. +- `localStorage` / `sessionStorage`: handle `string | null`; treat parsed data as `unknown` until validated. +- URL parameters: handle the router or platform's nullable string shape, then parse and validate before converting to a domain type. +- Exported APIs and important boundaries: declare return types; allow inference for local implementations when the contract remains clear. + +**Type Complexity Review Signals** + +Use these as review prompts, not pass/fail thresholds. Existing project conventions and the component's responsibility take precedence. + +- Props count: review ownership or splitting above 10. +- Optional props: review defaults or ownership when more than half are optional. +- Nested prop structures: review flattening beyond 2 levels. +- Type assertions: review the boundary when 3+ assertions are required. +- External API types: represent the actual external shape and convert at the application boundary. + +## Components and State + +- Prefer function components and Hooks for new code. Preserve working class components unless the accepted work requires migration; a class remains valid for an Error Boundary implementation. +- Follow the project's adopted component architecture and file layout. Co-locate files only when it is established or approved as a new structure. +- Preserve the repository's existing local, shared, and server-state ownership boundaries. Introduce Context, a shared-state layer, or a server-state dependency only when the accepted design requires ownership or lifecycle that the existing boundary cannot represent. +- Keep one authoritative owner for each state value and use the immutable updates React change detection requires. +- Guard effect-driven requests against stale or post-unmount updates through the repository's cancellation or server-state mechanism. + +## Server/Client Boundary — only for RSC frameworks + +- Fetch and render on the server by default; isolate interactivity behind the smallest `"use client"` boundary that needs it. +- Keep browser-only APIs and event handlers inside client components. +- Skip these rules when the project has no server-component runtime. + +## Environment and Client Security + +- Read client-side environment variables through the project's bundler accessor and public prefix. Validate required values through the repository's typed config layer; add a default only for an optional value or an explicitly defined local-development mode. +- Browser-delivered code and public environment variables are observable by clients, so credentials and secrets stay on the server. + +## Performance and Compatibility + +- When React Compiler is enabled, rely on it. Add manual `React.memo`, `useMemo`, or `useCallback` only for a measured bottleneck or a required stable identity at an external API/effect boundary. +- Apply code splitting or import changes when a configured bundle budget regresses, or when the accepted task names bundle size as an outcome and a repository bundle report attributes the relevant increase to the changed import. Follow the repository's existing loading pattern and verify the same signal after the change. +- Implement against the browser support policy in the PRD, Design Doc, Browserslist, or build configuration. When none is defined, preserve the repository's current transpilation/polyfill baseline and surface any new browser-dependent API as an unresolved compatibility decision. diff --git a/dev-workflows-fullstack/skills/implementation-approach/SKILL.md b/dev-workflows-fullstack/skills/implementation-approach/SKILL.md index 46ee41dc..b9784615 100644 --- a/dev-workflows-fullstack/skills/implementation-approach/SKILL.md +++ b/dev-workflows-fullstack/skills/implementation-approach/SKILL.md @@ -24,7 +24,7 @@ Historical Context Understanding: Current form rationale, past decision validity - What dependencies or implicit preconditions are unclear from the code? - What benefits and constraints does the current design bring? -Stop when another current-state fact cannot change responsibility, reuse, option validity, total complexity, a contract, or verification. +Stop when the current-state facts that could change responsibility, reuse, option validity, total complexity, a contract, or verification have been checked; find existing code as coding-principles Reference Representativeness describes. ### Phase 2: Design Convergence @@ -32,7 +32,7 @@ Complete these steps in order before selecting an implementation strategy: 1. **Existing-Surface Baseline**: Form the simplest end-to-end path that delivers the current outcome through existing responsibilities. Explicit requirements and accepted decisions are binding; suggested mechanisms remain candidates. 2. **Evidence Check**: Test that path against current requirements, verified constraints, observed in-scope problems, and evidence-backed material risks. Keep only the unmet conditions that can change the selected design. Where the requirements leave a quality level unset, such as performance, freshness, consistency, availability, or protection beyond the required trust boundary, test against the lowest level that still delivers the outcome and record it as the selected level. -3. **Targeted Comparison**: For each unmet condition, test reuse, derivation from existing data, on-demand computation, or responsibility at the current caller or boundary before adding design surface. Compare viable choices by total complexity across the dimensions that materially differ: user decisions, settings, modes, concepts, outputs, persistent state, implementation paths, UX, runtime, implementation, testing, documentation, and maintenance. Select the lowest-total-complexity choice that satisfies the condition. +3. **Targeted Comparison**: For each unmet condition, test reuse, derivation from existing data, on-demand computation, or responsibility at the current caller or boundary before adding design surface. Compare viable choices by total complexity across the dimensions that materially differ: user decisions, settings, modes, concepts, outputs, persistent state, implementation paths, UX, runtime, implementation, testing, documentation, and maintenance. A second implementation of a responsibility that already has an owner with the same contract and change reason, including one added earlier in the same change, adds design surface; reusing or relocating that owner removes it. Select the lowest-total-complexity choice that satisfies the condition. 4. **Subtraction Check**: Remove each proposed addition and re-test its governing condition. Retain it only when the outcome, a required boundary, or necessary proof becomes unmet at its origin (a requirement, an accepted decision, or a repository rule or contract); a criterion, invariant, or constraint that a workflow artifact derived from that origin is narrowed to what the origin requires instead. Classify supporting claims as observed, inferred, or unknown. Route an unknown that blocks the next step as an exact evidence prerequisite; the caller's value-boundary and irreversible-action gates determine whether user interaction is required. diff --git a/dev-workflows-fullstack/skills/integration-e2e-testing/SKILL.md b/dev-workflows-fullstack/skills/integration-e2e-testing/SKILL.md index aa037f1f..9ad86fdd 100644 --- a/dev-workflows-fullstack/skills/integration-e2e-testing/SKILL.md +++ b/dev-workflows-fullstack/skills/integration-e2e-testing/SKILL.md @@ -29,6 +29,8 @@ Selection evidence: [required claim, uncovered failure, and why cheaper existing Use the project's comment syntax to wrap these annotations (e.g., `//` for C-family, `#` for Python/Ruby/Shell). +`Selection evidence` serves test selection and planning, so the implementing task removes it when it makes the test executable. + ### Verification Items (Optional) When verification points need explicit enumeration: diff --git a/dev-workflows-fullstack/skills/recipe-build/SKILL.md b/dev-workflows-fullstack/skills/recipe-build/SKILL.md index 7e8b3cb5..6f7d3379 100644 --- a/dev-workflows-fullstack/skills/recipe-build/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-build/SKILL.md @@ -134,4 +134,5 @@ Final report must include: - Commit count - Cleanup result - Declined actionable findings with ID, governing reason, and evidence, when any occurred +- Findings outside the change that remain unhandled, with location and evidence, when any remain - Escalation or blocking summary, if any diff --git a/dev-workflows-fullstack/skills/recipe-front-adjust/SKILL.md b/dev-workflows-fullstack/skills/recipe-front-adjust/SKILL.md index 1ba04995..73499592 100644 --- a/dev-workflows-fullstack/skills/recipe-front-adjust/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-front-adjust/SKILL.md @@ -92,7 +92,7 @@ Present the adjustment context to the user for review. ### Step 5: Adjustment + Verification (parent session) 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: coding-principles and read its `references/frontend.md` 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 93e3620f..0a81ec3d 100644 --- a/dev-workflows-fullstack/skills/recipe-front-build/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-front-build/SKILL.md @@ -134,4 +134,5 @@ Final report must include: - Commit count - Cleanup result - Declined actionable findings with ID, governing reason, and evidence, when any occurred +- Findings outside the change that remain unhandled, with location and evidence, when any remain - Escalation or blocking summary, if any diff --git a/dev-workflows-fullstack/skills/recipe-front-review/SKILL.md b/dev-workflows-fullstack/skills/recipe-front-review/SKILL.md index 73483f80..d8dcb2c8 100644 --- a/dev-workflows-fullstack/skills/recipe-front-review/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-front-review/SKILL.md @@ -153,7 +153,7 @@ Use the shared **Re-run rule** to select the owners of the findings corrected in Apply Review Resolution to each returned reconciliation. Return maintained applied findings to their correction owner; proceed to Step 9 at convergence. -Before Step 9, retry each retained quality-fixer-frontend limitation once with the same Step 7 inputs and affected check. Remove a limitation when the retry passes, route newly discovered incomplete implementation through Steps 6-8, and report a repeated `verification_incomplete` result. Apply the shared Re-run rule, including its changed-boundary check for mutations outside received findings, before reporting. +Before Step 9, retry each retained quality-fixer-frontend limitation once with the same Step 7 inputs and affected check. Remove a limitation when the retry passes, route newly discovered incomplete implementation through Steps 6-8, and report a repeated `verification_incomplete` result. Apply the shared Re-run rule, including its check of whether the corrections invalidated evidence a passed review relied on, before reporting. ### Step 9: Final Report diff --git a/dev-workflows-fullstack/skills/recipe-fullstack-build/SKILL.md b/dev-workflows-fullstack/skills/recipe-fullstack-build/SKILL.md index 57f83835..34f74515 100644 --- a/dev-workflows-fullstack/skills/recipe-fullstack-build/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-fullstack-build/SKILL.md @@ -152,4 +152,5 @@ Final report must include: - Commit count - Cleanup result - Declined actionable findings with ID, governing reason, and evidence, when any occurred +- Findings outside the change that remain unhandled, with location and evidence, when any remain - Escalation or blocking summary, if any diff --git a/dev-workflows-fullstack/skills/recipe-review/SKILL.md b/dev-workflows-fullstack/skills/recipe-review/SKILL.md index 479ab76b..3b883851 100644 --- a/dev-workflows-fullstack/skills/recipe-review/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-review/SKILL.md @@ -153,7 +153,7 @@ Use the shared **Re-run rule** to select the owners of the findings corrected in Apply Review Resolution to each returned reconciliation. Return maintained applied findings to their correction owner; proceed to Step 9 at convergence. -Before Step 9, retry each retained quality-fixer limitation once with the same Step 7 inputs and affected check. Remove a limitation when the retry passes, route newly discovered incomplete implementation through Steps 6-8, and report a repeated `verification_incomplete` result. Apply the shared Re-run rule, including its changed-boundary check for mutations outside received findings, before reporting. +Before Step 9, retry each retained quality-fixer limitation once with the same Step 7 inputs and affected check. Remove a limitation when the retry passes, route newly discovered incomplete implementation through Steps 6-8, and report a repeated `verification_incomplete` result. Apply the shared Re-run rule, including its check of whether the corrections invalidated evidence a passed review relied on, before reporting. ### Step 9: Final Report diff --git a/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md index 887356c6..34ce9448 100644 --- a/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md @@ -211,9 +211,9 @@ Reviewer findings are candidates. Create correction work only from the Review Re **Fix-cycle handoff**: Apply Review Resolution and invoke each correction owner it selects. For an author-owned technical-artifact correction, invoke the layer-appropriate technical designer in update mode, run the artifact's existing document-reviewer and applicable design-sync gates, then re-run the originating reviewer. For an executor-owned correction, invoke the layer-appropriate executor with its original `task_file` or direct-scope fields plus `correction_findings` as the complete `apply` finding objects verbatim with only their dispositions added, then branch on the executor result through the per-task cycle's step 2, including its conditional integration-test-reviewer path, and run the applicable quality gate. When both owners are required, Review Resolution's author-first re-evaluation controls the order. Carry `prior_feedback` only to a reviewer or verifier being rechecked. Post-implementation corrections stay uncommitted through this cycle: the reviewers read the current working tree, so run the applicable quality gate and re-run the originating reviewer on the uncommitted changes, and commit the applied corrections once through Commit Boundary Check after the complete review set reaches Review Resolution convergence. -**Re-run rule**: After an applied post-implementation correction, re-run only the reviewer that owns a corrected finding from its latest result. For these finding-owned corrections, retain every passed reviewer result, including after another reviewer's correction. Pass the previous complete result, dispositions, and correction diff or paths to the rerun. After Specialist Result Acceptance recovers a blocked review prerequisite, re-run that reviewer. Review Resolution convergence governs acceptance and preserves resolved declines. +**Re-run rule**: After an applied post-implementation correction, re-run only the reviewer that owns a corrected finding from its latest result. Retain every other passed reviewer result, including after another reviewer's correction, unless the check below finds that the correction invalidated the evidence that review relied on. Pass the previous complete result, dispositions, and correction diff or paths to the rerun. After Specialist Result Acceptance recovers a blocked review prerequisite, re-run that reviewer. Review Resolution convergence governs acceptance and preserves resolved declines. -When a quality-fixer retry changes behavior outside the received findings, compare its actual diff against the already reviewed boundaries. Reconcile changes covered by an existing finding through its owner. For other behavior changes that invalidate review evidence, invoke only the applicable code-reviewer or security-reviewer with the original governing documents and the affected `implementationFiles`, scoped to that diff and its directly affected boundary; omit `prior_feedback` because this is new changed code, not finding reconciliation. Apply Review Resolution to its findings. Retain unaffected passed results; unchanged output and behavior-neutral formatting require no review. This check does not reopen a passed reviewer merely because another reviewer’s correction touched the same file. +After a correction or quality-fixer retry, compare its actual diff against the contracts, behavior, and verification evidence that the passed reviews relied on, whether or not the change stays inside the received findings: a shared contract corrected for one unit's finding can invalidate another unit's pass. Reconcile changes covered by an existing finding through its owner. For other changes that invalidate review evidence, invoke only the applicable code-reviewer or security-reviewer with the original governing documents and the affected `implementationFiles`, scoped to that diff and its directly affected boundary; omit `prior_feedback` because this is new changed code, not finding reconciliation. Apply Review Resolution to its findings. Retain unaffected passed results; unchanged output and behavior-neutral formatting require no review. This check does not reopen a passed reviewer merely because another reviewer’s correction touched the same file. ### Conditions for Stopping Autonomous Execution @@ -262,6 +262,8 @@ Derive the values from the quality-fixer result. Keep the complete result in orc - `pass` → Proceed to step 4 4. **Commit**: apply Commit Boundary Check, then compose the message from `changeSummary` and execute git commit with Bash after `pass` or `verification_incomplete`; append the verification trailers for the latter +**Findings outside the change**: Retain each executor `findingsOutsideChange` item; one the outcome needs is incomplete implementation under Specialist Result Acceptance. When the workflow runs post-implementation review, an item in work this workflow produced enters Review Resolution with the review findings, and the code-reviewer whose `implementationFiles` contain its location owns an applied one. List the items left unhandled with their location and evidence in the completion report. + Before post-implementation verifiers, collect retained verification limitations from orchestration state and the verification trailers on task-boundary commits created by the workflow, then re-invoke the applicable quality-fixer once for each limitation using the same task inputs and its affected check or command. When the retry returns `pass`, remove that limitation from retained state. Route newly discovered incomplete implementation through the normal cycle, and retain a repeated `verification_incomplete` result for the final report. Commit any fixes produced by this retry through the same task cycle, then continue post-implementation verification. ## Handoff Contracts diff --git a/dev-workflows-fullstack/skills/testing-principles/references/e2e.md b/dev-workflows-fullstack/skills/testing-principles/references/e2e.md index b0e06542..df87bf72 100644 --- a/dev-workflows-fullstack/skills/testing-principles/references/e2e.md +++ b/dev-workflows-fullstack/skills/testing-principles/references/e2e.md @@ -42,4 +42,4 @@ Use the repository's existing seed and authentication mechanisms. Create per-tes ## Skeleton Annotations -Preserve the skeleton's annotations unchanged. When `Verification items:` are present, implement and assert every listed item. +Preserve the skeleton's annotations unchanged, except `Selection evidence`, which served test selection only and is removed when the test becomes executable. When `Verification items:` are present, implement and assert every listed item. diff --git a/dev-workflows-fullstack/skills/testing-principles/references/frontend.md b/dev-workflows-fullstack/skills/testing-principles/references/frontend.md index 9b683622..a961645e 100644 --- a/dev-workflows-fullstack/skills/testing-principles/references/frontend.md +++ b/dev-workflows-fullstack/skills/testing-principles/references/frontend.md @@ -7,7 +7,7 @@ Before writing a test, inspect package scripts, runner configuration, setup file - Use React Testing Library when it is the project's component-test renderer; prefer `userEvent` for user interactions. - Use the repository's network mocking layer for API behavior. When MSW is configured, extend its handlers instead of adding runner-level fetch mocks. - Use the configured runner's imports, module-mocking API, fake timers, and reset conventions. -- When multiple approaches coexist, follow the dominant convention in the changed feature area. If none is representative and adding or replacing tooling is outside the approved work, report the missing test-environment decision. +- When multiple approaches coexist, choose from the behavior under test and the setup the repository maintains for it rather than from proximity alone. If none is representative and adding or replacing tooling is outside the approved work, report the missing test-environment decision. ## Test Scope diff --git a/dev-workflows-fullstack/skills/typescript-rules/SKILL.md b/dev-workflows-fullstack/skills/typescript-rules/SKILL.md deleted file mode 100644 index df4751bd..00000000 --- a/dev-workflows-fullstack/skills/typescript-rules/SKILL.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -name: typescript-rules -description: React/TypeScript frontend development rules including type safety, component design, state management, and error handling. Use when implementing React components, TypeScript code, or frontend features. ---- - -# TypeScript Development Rules (Frontend) - -## Comment Writing Rules - -Code first: names and types carry meaning; a comment must add what code cannot, and one comment per decision is enough. - -- Explain why a component memoizes, guards, or re-renders, not what the JSX renders. -- Record decisions and rationale; leave chronological history to version control. - -## Type Safety - -**Default Rule**: Prefer `unknown`, generics, or union types over `any`. Retain `any` only when an existing external, generated, or legacy public signature requires it, or when replacing it prevents the project type check from expressing a safe generic relationship. Record the declaration path or type-check result that proves the constraint. When a local adapter can preserve compatibility and expose a safer type within the user request or current task/design artifact, implement the adapter; otherwise confine `any` to the smallest adapter or public-signature boundary, document the reason, and validate untrusted data before it enters typed application code. - -**Frontend Boundaries** - -- React Props/State: use the declared application types. -- External API responses: treat unvalidated payloads as `unknown` and validate at the boundary. A generated client may retain its declared type when it also enforces the contract at runtime. -- `localStorage` / `sessionStorage`: handle `string | null`; treat parsed data as `unknown` until validated. -- URL parameters: handle the router or platform's nullable string shape, then parse and validate before converting to a domain type. -- Exported APIs and important boundaries: declare return types; allow inference for local implementations when the contract remains clear. - -**Type Complexity Review Signals** - -Use these as review prompts, not pass/fail thresholds. Existing project conventions and the component's responsibility take precedence. - -- Props count: review ownership or splitting above 10. -- Optional props: review defaults or ownership when more than half are optional. -- Nested prop structures: review flattening beyond 2 levels. -- Type assertions: review the boundary when 3+ assertions are required. -- External API types: represent the actual external shape and convert at the application boundary. - -## Coding Conventions - -**Component and File Decisions** - -- Prefer function components and Hooks for new code. Preserve working class components unless the accepted work requires migration; a class remains valid for an Error Boundary implementation. -- Reuse logic through the repository's established component, hook, or module pattern. -- Follow the project's adopted component architecture and file layout. Co-locate files only when it is established or approved as a new structure. - -**Server/Client Boundary — only for RSC frameworks** - -- Fetch and render on the server by default; isolate interactivity behind the smallest `"use client"` boundary that needs it. -- Keep browser-only APIs and event handlers inside client components. -- Skip these rules when the project has no server-component runtime. - -**State Ownership** - -- Preserve the repository's existing local, shared, and server-state ownership boundaries. -- Introduce Context, a shared-state layer, or a server-state dependency only when the accepted design requires ownership or lifecycle that the existing boundary cannot represent. -- Keep one authoritative owner for each state value and use immutable updates required by React change detection. - -**Function and Props Boundaries** - -- Prefer 0-2 parameters. For 3+ related values, use an object when it clarifies names or represents one domain input; preserve positional parameters when the repository convention or external API requires them. -- Declare component dependencies through typed props, hooks, Context, or injected modules according to the repository's established state and dependency boundaries. - -**Environment Variables** - -- Read client-side environment variables through the project's bundler accessor and public prefix. -- Validate required values through the repository's typed config layer; add a default only for an optional value or an explicitly defined local-development mode. - -**Client Security** - -- Keep credentials and secrets on the server; browser-delivered code and public environment variables are observable by clients. -- Exclude local environment files from version control and keep error output free of sensitive values. - -**Asynchronous Processing** - -- Follow the repository's promise style; use `async`/`await` when it clarifies sequencing and error propagation. -- Handle event-handler and asynchronous failures at their owning boundary. Error Boundaries cover descendant rendering failures, not ordinary callbacks or asynchronous work. -- Guard effect-driven requests against stale or post-unmount updates through the repository's cancellation or server-state mechanism. - -**Formatting** - -- Follow the repository's formatter, naming, module-resolution, and package-boundary configuration. -- Use an import alias only when the project configuration resolves it. - -## Error Handling - -Every caught error has one intentional outcome: propagate it, convert it to the repository's typed boundary result, or represent it as user-facing error state. Preserve context and log once at the boundary that owns diagnosis or recovery, with sensitive data redacted. - -- Error Boundary: place it where descendant render failures have a defined UI recovery outcome. -- Custom Hook: preserve the application's existing error contract. -- API Layer: convert transport failures to the repository's established domain or boundary representation. -- Event handlers and async workflows: use the owning layer's exception, result, or UI-state contract. - -## Performance Optimization - -- When React Compiler is enabled, rely on it. Add manual `React.memo`, `useMemo`, or `useCallback` only for a measured bottleneck or a required stable identity at an external API/effect boundary. -- Apply code splitting or import changes when a configured bundle budget regresses, or when the accepted task names bundle size as an outcome and a repository bundle report attributes the relevant increase to the changed import. Follow the repository's existing loading pattern and verify the same signal after the change. - -## Non-functional Requirements - -- **Browser Compatibility**: Implement against the support policy in the PRD, Design Doc, Browserslist, or build configuration. When none is defined, preserve the repository's current transpilation/polyfill baseline and surface any new browser-dependent API as an unresolved compatibility decision. -- **Performance**: Verify against project-defined budgets and the metric representing the affected experience. When no budget exists, measure the changed path and report the observed result instead of inventing a threshold. diff --git a/dev-workflows/.claude-plugin/plugin.json b/dev-workflows/.claude-plugin/plugin.json index 68036dae..6655317b 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.30.0", + "version": "0.31.0", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows/agents/acceptance-test-generator.md b/dev-workflows/agents/acceptance-test-generator.md index 5903323f..f9170cb2 100644 --- a/dev-workflows/agents/acceptance-test-generator.md +++ b/dev-workflows/agents/acceptance-test-generator.md @@ -41,6 +41,8 @@ Each selected test records: - proof obligation: boundary to traverse, expected state/results, pass criteria, real dependencies and permissible substitutes; - a distinct branch, state, lifecycle or fallback path when the main path could remain green through a material regression. +File-level comments hold only what the completed tests keep, such as the lane declaration and setup the tests share; each test's record carries the rest. + Keep executable assertions and mock implementation for the implementing task. Test Boundaries marking a dependency as real are carried as `@real-dependency: [component]`. ## Output diff --git a/dev-workflows/agents/code-reviewer.md b/dev-workflows/agents/code-reviewer.md index 7b801887..44d8ad95 100644 --- a/dev-workflows/agents/code-reviewer.md +++ b/dev-workflows/agents/code-reviewer.md @@ -19,7 +19,7 @@ Verify by reading the changed code and tests. Running tests and quality checks i ## Inputs - **governingDocuments**: One or more approved Design Docs, or the resolved Work Plan when the caller has no Design Doc, as a list of document paths -- **implementationFiles**: The complete set of implementation, test, schema, build, deployment, and runtime-configuration artifacts in the reviewed change +- **implementationFiles**: The implementation, test, schema, build, deployment, and runtime-configuration artifacts whose changes this review judges: the complete change, or one review unit of it - **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 @@ -31,6 +31,7 @@ Before reviewing, read these files; they hold review criteria beyond the preload - `references/frontend.md` in the testing-principles skill - `references/frontend.md` in the ai-development-guide skill +- `references/frontend.md` in the coding-principles skill - `references/e2e.md` in the testing-principles skill ## Initial Review @@ -40,7 +41,7 @@ Extract the approved outcome, applicable acceptance criteria, changed interfaces Judge the material surfaces in `implementationFiles` against these criteria: - **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. +- **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 code or tests that already hold the same responsibility, in the repository or elsewhere in this change (coding-principles Reference Representativeness), 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. diff --git a/dev-workflows/agents/code-verifier.md b/dev-workflows/agents/code-verifier.md index 2c717c5e..0f4ea016 100644 --- a/dev-workflows/agents/code-verifier.md +++ b/dev-workflows/agents/code-verifier.md @@ -39,7 +39,7 @@ For reverse-engineered/as-is documents, verify every supplied inventory item at Use one authoritative definition when it directly proves an identifier or contract. Seek another source when behavior, indirection, or conflicting evidence makes it decision-relevant. Base confidence on evidence quality rather than source count. -Stop expanding the search when additional evidence cannot change a discrepancy or limitation. +Stop expanding the search when the evidence that could change a discrepancy or limitation has been checked; find existing code as coding-principles Reference Representativeness describes. ## Rerun Boundary diff --git a/dev-workflows/agents/codebase-analyzer.md b/dev-workflows/agents/codebase-analyzer.md index 13c58dec..80d0bfec 100644 --- a/dev-workflows/agents/codebase-analyzer.md +++ b/dev-workflows/agents/codebase-analyzer.md @@ -32,7 +32,7 @@ Return a fact only when it can: - identify a lifecycle-cost or maintainability difference; or - select a verification boundary. -Stop expanding the search when another fact cannot change one of those outcomes. Inspect all known consumers only for a public, shared, serialized, persistent, security, or error contract whose complete consumer set controls compatibility. Otherwise, representative callers, tests, configuration, and siblings are sufficient. +Existing code with the same responsibility as a new surface may share no name or reference with it; look for reuse through position and role (sibling features, files with the same role in the same layer, shared layers) and through shared input and purpose, as well as through references. Stop expanding the search when the facts that could change one of those outcomes have been checked; a search with no match shows only that the search found nothing. Inspect all known consumers only for a public, shared, serialized, persistent, security, or error contract whose complete consumer set controls compatibility. Otherwise, representative callers, tests, configuration, and siblings are sufficient. ## Execution Steps diff --git a/dev-workflows/agents/task-executor.md b/dev-workflows/agents/task-executor.md index ffc23b25..f6a9167e 100644 --- a/dev-workflows/agents/task-executor.md +++ b/dev-workflows/agents/task-executor.md @@ -12,6 +12,8 @@ skills: You are a specialized AI assistant for reliably executing individual tasks. +You own how this codebase is built and you will keep building on it, so what you leave behind is yours to maintain. What it is for — the outcome, requirements, and non-goals — stays with the user's recorded decisions. + ## Input Parameters Workflow callers use the applicable canonical fields below: @@ -70,7 +72,7 @@ Use the indicators to find plausible candidates and apply the authoritative boun 1. Compare responsibility, contract, lifecycle, and representative repository usage. 2. Record one `reuseDecisions` entry: - `reuse` or `extend` when those dimensions are compatible; - - `separate` when sharing would merge independently evolving responsibilities or add more contract surface than it removes. + - `separate` when evidence shows different contracts or change reasons, or when sharing would add more coupling and contract surface than it removes. 3. Continue with the repository-local reversible choice supported by that evidence. ### Step4: Core Mechanism Preservation Check @@ -143,15 +145,13 @@ Classify from the task outcome and changed boundary, then run after Pre-implemen #### Reference Representativeness (Applied During Implementation) -When adopting a pattern or dependency from existing code, apply coding-principles "Reference Representativeness" at the point of adoption: - -Apply coding-principles Reference Representativeness using the changed area and representative consumers or siblings. Expand to all known consumers when a changed shared/public contract requires compatibility accounting. Record the evidence for a material choice among competing patterns; stop when further search cannot change implementation or proof. +When adopting a pattern or dependency from existing code, apply coding-principles Reference Representativeness at the point of adoption. #### 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 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. +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. When completing a skeleton, remove its `Selection evidence` lines, which served test selection only, and keep its other annotations for test review and lane routing. #### Operation Verification - Execute the Operation Verification Methods in the execution instructions @@ -186,6 +186,8 @@ Return the final response per Structured Response Specification. For research/an **reuseDecisions**: Use `[]` when no plausible similar implementation was found. Otherwise include the decision-relevant candidates evaluated in Step 3 with `decision: "reuse" | "extend" | "separate"` and evidence covering responsibility, contract, lifecycle, and repository representativeness. +**findingsOutsideChange**: Use `[]` when none. Otherwise list problems already observed during this task that the change leaves unhandled, because handling them belongs to another responsibility, would change the outcome or a non-goal, or needs an irreversible external action. Each item gives its location, evidence, and that reason. The field reports observations; it creates no search obligation. + ### 1. Task Completion Response Complete this agent's work by returning the following JSON; the quality assurance process performs quality checks and commits: @@ -198,6 +200,7 @@ Complete this agent's work by returning the following JSON; the quality assuranc "requiresTestReview": true, "newTestsPassed": true, "reuseDecisions": [{"candidate": "[path:symbol]", "decision": "reuse | extend | separate", "evidence": "[Responsibility, contract, lifecycle, and repository-representativeness evidence]"}], + "findingsOutsideChange": [{"location": "[path:symbol]", "evidence": "[Observed fact]", "reason": "[Why this change leaves it unhandled]"}], "runnableCheck": {"level": "L1: Functional Operation Verification / L2: Test Operation Verification / L3: Build Success Verification", "executed": true, "command": "Executed verification command", "result": "passed / failed / skipped", "reason": "Verification content or exact limitation"}, "mutationEvidence": [{"mutation": "[description or patch]", "killedTest": "[test name]", "baselineResult": "[baseline command and result]", "mutatedResult": "[mutated command and result]", "restorationProof": "[restoration checksum or clean diff]", "targetRevision": "[revision or file hashes]"}] } diff --git a/dev-workflows/agents/technical-designer.md b/dev-workflows/agents/technical-designer.md index b01a6322..c097d31b 100644 --- a/dev-workflows/agents/technical-designer.md +++ b/dev-workflows/agents/technical-designer.md @@ -15,6 +15,8 @@ skills: You create one complete ADR batch or one Design Doc per invocation. +You own how this codebase is built and you will keep building on it, so what you leave behind is yours to maintain. What it is for — the outcome, requirements, and non-goals — stays with the user's recorded decisions. + ## Execution Gate 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. diff --git a/dev-workflows/skills/ai-development-guide/SKILL.md b/dev-workflows/skills/ai-development-guide/SKILL.md index 70fbfe0a..352ad685 100644 --- a/dev-workflows/skills/ai-development-guide/SKILL.md +++ b/dev-workflows/skills/ai-development-guide/SKILL.md @@ -108,7 +108,7 @@ Keep concrete implementations separate while their apparent similarity is accide **Cases to Avoid Commonalization** - Accidental matches (coincidentally same code) -- Possibility of evolving in different directions +- Contracts or change reasons that evidence shows differ - Significant readability decrease from commonalization - Simple helpers in test code @@ -138,12 +138,11 @@ Keep concrete implementations separate while their apparent similarity is accide **Symptom**: Duplicate implementations, architecture inconsistency, integration failures, adopting outdated patterns **Cause**: Insufficient understanding of existing code before implementation; referencing only nearby files without verifying representativeness **Avoidance Methods**: -- Before implementation, always search for similar functionality (using domain, responsibility, configuration patterns as keywords) +- Before implementation, find functionality that already holds the same responsibility and the code that depends on the change, as coding-principles Reference Representativeness describes; similar functionality may share no name with the new code - Similar functionality found → Verify that its contract, lifecycle, and repository usage are representative; reuse or extend it when compatible, otherwise record why it is not a valid model - Similar functionality is technical debt → Repair it when it blocks the current outcome, was caused by the current change, or lies in scope; otherwise report it separately. Create an ADR when the repair requires an architectural decision - No similar functionality exists → Implement new functionality following existing design philosophy - Preserve the evidence for each reuse, extend, separate, or repair decision in the applicable implementation or design record -- **Reference representativeness check**: When adopting a pattern or dependency from nearby code, inspect the changed area and enough representative consumers or siblings to establish compatibility; expand only when competing patterns or a shared/public contract can change the choice ## Quality Assurance Mechanism Awareness @@ -168,7 +167,7 @@ Follow repository-declared command composition or ordering when it exists. Other ## Situations Requiring Technical Decisions ### Timing of Abstraction -- Extract a shared abstraction after repository evidence establishes a shared responsibility and coordinated change pattern +- Extract a shared abstraction after repository evidence shows a responsibility with the same contract and change reason maintained in more than one place - Be conscious of YAGNI, implement only currently needed features - Prioritize current simplicity over future extensibility diff --git a/dev-workflows/skills/coding-principles/SKILL.md b/dev-workflows/skills/coding-principles/SKILL.md index bd3ede0b..d45bce62 100644 --- a/dev-workflows/skills/coding-principles/SKILL.md +++ b/dev-workflows/skills/coding-principles/SKILL.md @@ -70,9 +70,11 @@ description: Language-agnostic coding principles for maintainability, readabilit ## Reference Representativeness -Inspect the changed responsibility and enough representative callers, consumers, configuration and siblings to establish a compatible pattern or dependency. Nearby code is a starting point; when alternatives coexist, choose from their responsibility, contract, lifecycle and repository usage rather than proximity or global popularity alone. Record the evidence only when it changes the choice. +Existing code relates to a change in two ways. Code that depends on it — callers, consumers, configuration — is reached through references to the changed code. Code that already holds the same responsibility may share no name or reference with it; reach it through position and role (sibling features, files with the same role in the same layer, shared layers) and through the input it takes and the purpose it serves, then compare their logic to judge whether the responsibility is the same. -Expand to all known consumers for a changed public, shared, serialized or persistent contract whose compatibility depends on them. Otherwise stop when additional inspection cannot change implementation or proof. Resolve versions from applicable manifests and usage; record a specific limitation only when required compatibility evidence remains unavailable. +When alternatives coexist, choose the pattern from responsibility, contract, lifecycle and repository usage rather than proximity or global popularity alone. Record the evidence only when it changes the choice. + +Expand to all known consumers for a changed public, shared, serialized or persistent contract whose compatibility depends on them. Stop when the candidates that could change implementation or proof have been read and judged; a search with no match shows only that the search found nothing. Resolve versions from applicable manifests and usage; record a specific limitation only when required compatibility evidence remains unavailable. ## Performance Considerations @@ -120,7 +122,7 @@ One comment per decision. If a comment restates what the names and control flow - Delete commented-out code (retrieve from git history when needed) ### Comment Quality -- Base comments on stable rationale, limits, and contracts rather than dates, versions, or temporary state +- Base comments on stable rationale, limits, and contracts rather than dates, versions, temporary state, or references to documents and their sections, which drift as those documents change - Update comments when changing code - Use proper grammar and formatting - Write for future maintainers @@ -161,3 +163,7 @@ One comment per decision. If a comment restates what the names and control flow - For changes involving identity or protected resources, prioritize authentication and per-resource authorization review For concrete detection patterns used by security review, see `references/security-checks.md`. + +## References + +- [references/frontend.md](references/frontend.md): read when implementing, reviewing, or fixing React/TypeScript code diff --git a/dev-workflows/skills/coding-principles/references/frontend.md b/dev-workflows/skills/coding-principles/references/frontend.md new file mode 100644 index 00000000..ba9f0363 --- /dev/null +++ b/dev-workflows/skills/coding-principles/references/frontend.md @@ -0,0 +1,50 @@ +# Frontend (React/TypeScript) Coding Rules + +Apply these with the SKILL.md principles. Each entry adds what React and TypeScript code needs beyond them; the frontend decision criteria for component responsibility, error boundaries, and profiling live in `references/frontend.md` of the ai-development-guide skill. + +## Type Safety + +**Default Rule**: Prefer `unknown`, generics, or union types over `any`. Retain `any` only when an existing external, generated, or legacy public signature requires it, or when replacing it prevents the project type check from expressing a safe generic relationship. Record the declaration path or type-check result that proves the constraint. When a local adapter can preserve compatibility and expose a safer type within the user request or current task/design artifact, implement the adapter; otherwise confine `any` to the smallest adapter or public-signature boundary, document the reason, and validate untrusted data before it enters typed application code. + +**Frontend Boundaries** + +- React Props/State: use the declared application types. +- External API responses: treat unvalidated payloads as `unknown` and validate at the boundary. A generated client may retain its declared type when it also enforces the contract at runtime. +- `localStorage` / `sessionStorage`: handle `string | null`; treat parsed data as `unknown` until validated. +- URL parameters: handle the router or platform's nullable string shape, then parse and validate before converting to a domain type. +- Exported APIs and important boundaries: declare return types; allow inference for local implementations when the contract remains clear. + +**Type Complexity Review Signals** + +Use these as review prompts, not pass/fail thresholds. Existing project conventions and the component's responsibility take precedence. + +- Props count: review ownership or splitting above 10. +- Optional props: review defaults or ownership when more than half are optional. +- Nested prop structures: review flattening beyond 2 levels. +- Type assertions: review the boundary when 3+ assertions are required. +- External API types: represent the actual external shape and convert at the application boundary. + +## Components and State + +- Prefer function components and Hooks for new code. Preserve working class components unless the accepted work requires migration; a class remains valid for an Error Boundary implementation. +- Follow the project's adopted component architecture and file layout. Co-locate files only when it is established or approved as a new structure. +- Preserve the repository's existing local, shared, and server-state ownership boundaries. Introduce Context, a shared-state layer, or a server-state dependency only when the accepted design requires ownership or lifecycle that the existing boundary cannot represent. +- Keep one authoritative owner for each state value and use the immutable updates React change detection requires. +- Guard effect-driven requests against stale or post-unmount updates through the repository's cancellation or server-state mechanism. + +## Server/Client Boundary — only for RSC frameworks + +- Fetch and render on the server by default; isolate interactivity behind the smallest `"use client"` boundary that needs it. +- Keep browser-only APIs and event handlers inside client components. +- Skip these rules when the project has no server-component runtime. + +## Environment and Client Security + +- Read client-side environment variables through the project's bundler accessor and public prefix. Validate required values through the repository's typed config layer; add a default only for an optional value or an explicitly defined local-development mode. +- Browser-delivered code and public environment variables are observable by clients, so credentials and secrets stay on the server. + +## Performance and Compatibility + +- When React Compiler is enabled, rely on it. Add manual `React.memo`, `useMemo`, or `useCallback` only for a measured bottleneck or a required stable identity at an external API/effect boundary. +- Apply code splitting or import changes when a configured bundle budget regresses, or when the accepted task names bundle size as an outcome and a repository bundle report attributes the relevant increase to the changed import. Follow the repository's existing loading pattern and verify the same signal after the change. +- Implement against the browser support policy in the PRD, Design Doc, Browserslist, or build configuration. When none is defined, preserve the repository's current transpilation/polyfill baseline and surface any new browser-dependent API as an unresolved compatibility decision. diff --git a/dev-workflows/skills/implementation-approach/SKILL.md b/dev-workflows/skills/implementation-approach/SKILL.md index 46ee41dc..b9784615 100644 --- a/dev-workflows/skills/implementation-approach/SKILL.md +++ b/dev-workflows/skills/implementation-approach/SKILL.md @@ -24,7 +24,7 @@ Historical Context Understanding: Current form rationale, past decision validity - What dependencies or implicit preconditions are unclear from the code? - What benefits and constraints does the current design bring? -Stop when another current-state fact cannot change responsibility, reuse, option validity, total complexity, a contract, or verification. +Stop when the current-state facts that could change responsibility, reuse, option validity, total complexity, a contract, or verification have been checked; find existing code as coding-principles Reference Representativeness describes. ### Phase 2: Design Convergence @@ -32,7 +32,7 @@ Complete these steps in order before selecting an implementation strategy: 1. **Existing-Surface Baseline**: Form the simplest end-to-end path that delivers the current outcome through existing responsibilities. Explicit requirements and accepted decisions are binding; suggested mechanisms remain candidates. 2. **Evidence Check**: Test that path against current requirements, verified constraints, observed in-scope problems, and evidence-backed material risks. Keep only the unmet conditions that can change the selected design. Where the requirements leave a quality level unset, such as performance, freshness, consistency, availability, or protection beyond the required trust boundary, test against the lowest level that still delivers the outcome and record it as the selected level. -3. **Targeted Comparison**: For each unmet condition, test reuse, derivation from existing data, on-demand computation, or responsibility at the current caller or boundary before adding design surface. Compare viable choices by total complexity across the dimensions that materially differ: user decisions, settings, modes, concepts, outputs, persistent state, implementation paths, UX, runtime, implementation, testing, documentation, and maintenance. Select the lowest-total-complexity choice that satisfies the condition. +3. **Targeted Comparison**: For each unmet condition, test reuse, derivation from existing data, on-demand computation, or responsibility at the current caller or boundary before adding design surface. Compare viable choices by total complexity across the dimensions that materially differ: user decisions, settings, modes, concepts, outputs, persistent state, implementation paths, UX, runtime, implementation, testing, documentation, and maintenance. A second implementation of a responsibility that already has an owner with the same contract and change reason, including one added earlier in the same change, adds design surface; reusing or relocating that owner removes it. Select the lowest-total-complexity choice that satisfies the condition. 4. **Subtraction Check**: Remove each proposed addition and re-test its governing condition. Retain it only when the outcome, a required boundary, or necessary proof becomes unmet at its origin (a requirement, an accepted decision, or a repository rule or contract); a criterion, invariant, or constraint that a workflow artifact derived from that origin is narrowed to what the origin requires instead. Classify supporting claims as observed, inferred, or unknown. Route an unknown that blocks the next step as an exact evidence prerequisite; the caller's value-boundary and irreversible-action gates determine whether user interaction is required. diff --git a/dev-workflows/skills/integration-e2e-testing/SKILL.md b/dev-workflows/skills/integration-e2e-testing/SKILL.md index aa037f1f..9ad86fdd 100644 --- a/dev-workflows/skills/integration-e2e-testing/SKILL.md +++ b/dev-workflows/skills/integration-e2e-testing/SKILL.md @@ -29,6 +29,8 @@ Selection evidence: [required claim, uncovered failure, and why cheaper existing Use the project's comment syntax to wrap these annotations (e.g., `//` for C-family, `#` for Python/Ruby/Shell). +`Selection evidence` serves test selection and planning, so the implementing task removes it when it makes the test executable. + ### Verification Items (Optional) When verification points need explicit enumeration: diff --git a/dev-workflows/skills/recipe-build/SKILL.md b/dev-workflows/skills/recipe-build/SKILL.md index 14d4ca35..2056e556 100644 --- a/dev-workflows/skills/recipe-build/SKILL.md +++ b/dev-workflows/skills/recipe-build/SKILL.md @@ -134,4 +134,5 @@ Final report must include: - Commit count - Cleanup result - Declined actionable findings with ID, governing reason, and evidence, when any occurred +- Findings outside the change that remain unhandled, with location and evidence, when any remain - Escalation or blocking summary, if any diff --git a/dev-workflows/skills/recipe-review/SKILL.md b/dev-workflows/skills/recipe-review/SKILL.md index b95c562b..32dafcb9 100644 --- a/dev-workflows/skills/recipe-review/SKILL.md +++ b/dev-workflows/skills/recipe-review/SKILL.md @@ -153,7 +153,7 @@ Use the shared **Re-run rule** to select the owners of the findings corrected in Apply Review Resolution to each returned reconciliation. Return maintained applied findings to their correction owner; proceed to Step 9 at convergence. -Before Step 9, retry each retained quality-fixer limitation once with the same Step 7 inputs and affected check. Remove a limitation when the retry passes, route newly discovered incomplete implementation through Steps 6-8, and report a repeated `verification_incomplete` result. Apply the shared Re-run rule, including its changed-boundary check for mutations outside received findings, before reporting. +Before Step 9, retry each retained quality-fixer limitation once with the same Step 7 inputs and affected check. Remove a limitation when the retry passes, route newly discovered incomplete implementation through Steps 6-8, and report a repeated `verification_incomplete` result. Apply the shared Re-run rule, including its check of whether the corrections invalidated evidence a passed review relied on, before reporting. ### Step 9: Final Report diff --git a/dev-workflows/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows/skills/subagents-orchestration-guide/SKILL.md index 887356c6..34ce9448 100644 --- a/dev-workflows/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows/skills/subagents-orchestration-guide/SKILL.md @@ -211,9 +211,9 @@ Reviewer findings are candidates. Create correction work only from the Review Re **Fix-cycle handoff**: Apply Review Resolution and invoke each correction owner it selects. For an author-owned technical-artifact correction, invoke the layer-appropriate technical designer in update mode, run the artifact's existing document-reviewer and applicable design-sync gates, then re-run the originating reviewer. For an executor-owned correction, invoke the layer-appropriate executor with its original `task_file` or direct-scope fields plus `correction_findings` as the complete `apply` finding objects verbatim with only their dispositions added, then branch on the executor result through the per-task cycle's step 2, including its conditional integration-test-reviewer path, and run the applicable quality gate. When both owners are required, Review Resolution's author-first re-evaluation controls the order. Carry `prior_feedback` only to a reviewer or verifier being rechecked. Post-implementation corrections stay uncommitted through this cycle: the reviewers read the current working tree, so run the applicable quality gate and re-run the originating reviewer on the uncommitted changes, and commit the applied corrections once through Commit Boundary Check after the complete review set reaches Review Resolution convergence. -**Re-run rule**: After an applied post-implementation correction, re-run only the reviewer that owns a corrected finding from its latest result. For these finding-owned corrections, retain every passed reviewer result, including after another reviewer's correction. Pass the previous complete result, dispositions, and correction diff or paths to the rerun. After Specialist Result Acceptance recovers a blocked review prerequisite, re-run that reviewer. Review Resolution convergence governs acceptance and preserves resolved declines. +**Re-run rule**: After an applied post-implementation correction, re-run only the reviewer that owns a corrected finding from its latest result. Retain every other passed reviewer result, including after another reviewer's correction, unless the check below finds that the correction invalidated the evidence that review relied on. Pass the previous complete result, dispositions, and correction diff or paths to the rerun. After Specialist Result Acceptance recovers a blocked review prerequisite, re-run that reviewer. Review Resolution convergence governs acceptance and preserves resolved declines. -When a quality-fixer retry changes behavior outside the received findings, compare its actual diff against the already reviewed boundaries. Reconcile changes covered by an existing finding through its owner. For other behavior changes that invalidate review evidence, invoke only the applicable code-reviewer or security-reviewer with the original governing documents and the affected `implementationFiles`, scoped to that diff and its directly affected boundary; omit `prior_feedback` because this is new changed code, not finding reconciliation. Apply Review Resolution to its findings. Retain unaffected passed results; unchanged output and behavior-neutral formatting require no review. This check does not reopen a passed reviewer merely because another reviewer’s correction touched the same file. +After a correction or quality-fixer retry, compare its actual diff against the contracts, behavior, and verification evidence that the passed reviews relied on, whether or not the change stays inside the received findings: a shared contract corrected for one unit's finding can invalidate another unit's pass. Reconcile changes covered by an existing finding through its owner. For other changes that invalidate review evidence, invoke only the applicable code-reviewer or security-reviewer with the original governing documents and the affected `implementationFiles`, scoped to that diff and its directly affected boundary; omit `prior_feedback` because this is new changed code, not finding reconciliation. Apply Review Resolution to its findings. Retain unaffected passed results; unchanged output and behavior-neutral formatting require no review. This check does not reopen a passed reviewer merely because another reviewer’s correction touched the same file. ### Conditions for Stopping Autonomous Execution @@ -262,6 +262,8 @@ Derive the values from the quality-fixer result. Keep the complete result in orc - `pass` → Proceed to step 4 4. **Commit**: apply Commit Boundary Check, then compose the message from `changeSummary` and execute git commit with Bash after `pass` or `verification_incomplete`; append the verification trailers for the latter +**Findings outside the change**: Retain each executor `findingsOutsideChange` item; one the outcome needs is incomplete implementation under Specialist Result Acceptance. When the workflow runs post-implementation review, an item in work this workflow produced enters Review Resolution with the review findings, and the code-reviewer whose `implementationFiles` contain its location owns an applied one. List the items left unhandled with their location and evidence in the completion report. + Before post-implementation verifiers, collect retained verification limitations from orchestration state and the verification trailers on task-boundary commits created by the workflow, then re-invoke the applicable quality-fixer once for each limitation using the same task inputs and its affected check or command. When the retry returns `pass`, remove that limitation from retained state. Route newly discovered incomplete implementation through the normal cycle, and retain a repeated `verification_incomplete` result for the final report. Commit any fixes produced by this retry through the same task cycle, then continue post-implementation verification. ## Handoff Contracts diff --git a/dev-workflows/skills/testing-principles/references/e2e.md b/dev-workflows/skills/testing-principles/references/e2e.md index b0e06542..df87bf72 100644 --- a/dev-workflows/skills/testing-principles/references/e2e.md +++ b/dev-workflows/skills/testing-principles/references/e2e.md @@ -42,4 +42,4 @@ Use the repository's existing seed and authentication mechanisms. Create per-tes ## Skeleton Annotations -Preserve the skeleton's annotations unchanged. When `Verification items:` are present, implement and assert every listed item. +Preserve the skeleton's annotations unchanged, except `Selection evidence`, which served test selection only and is removed when the test becomes executable. When `Verification items:` are present, implement and assert every listed item. diff --git a/dev-workflows/skills/testing-principles/references/frontend.md b/dev-workflows/skills/testing-principles/references/frontend.md index 9b683622..a961645e 100644 --- a/dev-workflows/skills/testing-principles/references/frontend.md +++ b/dev-workflows/skills/testing-principles/references/frontend.md @@ -7,7 +7,7 @@ Before writing a test, inspect package scripts, runner configuration, setup file - Use React Testing Library when it is the project's component-test renderer; prefer `userEvent` for user interactions. - Use the repository's network mocking layer for API behavior. When MSW is configured, extend its handlers instead of adding runner-level fetch mocks. - Use the configured runner's imports, module-mocking API, fake timers, and reset conventions. -- When multiple approaches coexist, follow the dominant convention in the changed feature area. If none is representative and adding or replacing tooling is outside the approved work, report the missing test-environment decision. +- When multiple approaches coexist, choose from the behavior under test and the setup the repository maintains for it rather than from proximity alone. If none is representative and adding or replacing tooling is outside the approved work, report the missing test-environment decision. ## Test Scope diff --git a/package.json b/package.json index b0076034..215b939b 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "claude-code-workflows", - "version": "0.30.0", + "version": "0.31.0", "private": true, "type": "module", "engines": { diff --git a/skills/ai-development-guide/SKILL.md b/skills/ai-development-guide/SKILL.md index 70fbfe0a..352ad685 100644 --- a/skills/ai-development-guide/SKILL.md +++ b/skills/ai-development-guide/SKILL.md @@ -108,7 +108,7 @@ Keep concrete implementations separate while their apparent similarity is accide **Cases to Avoid Commonalization** - Accidental matches (coincidentally same code) -- Possibility of evolving in different directions +- Contracts or change reasons that evidence shows differ - Significant readability decrease from commonalization - Simple helpers in test code @@ -138,12 +138,11 @@ Keep concrete implementations separate while their apparent similarity is accide **Symptom**: Duplicate implementations, architecture inconsistency, integration failures, adopting outdated patterns **Cause**: Insufficient understanding of existing code before implementation; referencing only nearby files without verifying representativeness **Avoidance Methods**: -- Before implementation, always search for similar functionality (using domain, responsibility, configuration patterns as keywords) +- Before implementation, find functionality that already holds the same responsibility and the code that depends on the change, as coding-principles Reference Representativeness describes; similar functionality may share no name with the new code - Similar functionality found → Verify that its contract, lifecycle, and repository usage are representative; reuse or extend it when compatible, otherwise record why it is not a valid model - Similar functionality is technical debt → Repair it when it blocks the current outcome, was caused by the current change, or lies in scope; otherwise report it separately. Create an ADR when the repair requires an architectural decision - No similar functionality exists → Implement new functionality following existing design philosophy - Preserve the evidence for each reuse, extend, separate, or repair decision in the applicable implementation or design record -- **Reference representativeness check**: When adopting a pattern or dependency from nearby code, inspect the changed area and enough representative consumers or siblings to establish compatibility; expand only when competing patterns or a shared/public contract can change the choice ## Quality Assurance Mechanism Awareness @@ -168,7 +167,7 @@ Follow repository-declared command composition or ordering when it exists. Other ## Situations Requiring Technical Decisions ### Timing of Abstraction -- Extract a shared abstraction after repository evidence establishes a shared responsibility and coordinated change pattern +- Extract a shared abstraction after repository evidence shows a responsibility with the same contract and change reason maintained in more than one place - Be conscious of YAGNI, implement only currently needed features - Prioritize current simplicity over future extensibility diff --git a/skills/coding-principles/SKILL.md b/skills/coding-principles/SKILL.md index bd3ede0b..d45bce62 100644 --- a/skills/coding-principles/SKILL.md +++ b/skills/coding-principles/SKILL.md @@ -70,9 +70,11 @@ description: Language-agnostic coding principles for maintainability, readabilit ## Reference Representativeness -Inspect the changed responsibility and enough representative callers, consumers, configuration and siblings to establish a compatible pattern or dependency. Nearby code is a starting point; when alternatives coexist, choose from their responsibility, contract, lifecycle and repository usage rather than proximity or global popularity alone. Record the evidence only when it changes the choice. +Existing code relates to a change in two ways. Code that depends on it — callers, consumers, configuration — is reached through references to the changed code. Code that already holds the same responsibility may share no name or reference with it; reach it through position and role (sibling features, files with the same role in the same layer, shared layers) and through the input it takes and the purpose it serves, then compare their logic to judge whether the responsibility is the same. -Expand to all known consumers for a changed public, shared, serialized or persistent contract whose compatibility depends on them. Otherwise stop when additional inspection cannot change implementation or proof. Resolve versions from applicable manifests and usage; record a specific limitation only when required compatibility evidence remains unavailable. +When alternatives coexist, choose the pattern from responsibility, contract, lifecycle and repository usage rather than proximity or global popularity alone. Record the evidence only when it changes the choice. + +Expand to all known consumers for a changed public, shared, serialized or persistent contract whose compatibility depends on them. Stop when the candidates that could change implementation or proof have been read and judged; a search with no match shows only that the search found nothing. Resolve versions from applicable manifests and usage; record a specific limitation only when required compatibility evidence remains unavailable. ## Performance Considerations @@ -120,7 +122,7 @@ One comment per decision. If a comment restates what the names and control flow - Delete commented-out code (retrieve from git history when needed) ### Comment Quality -- Base comments on stable rationale, limits, and contracts rather than dates, versions, or temporary state +- Base comments on stable rationale, limits, and contracts rather than dates, versions, temporary state, or references to documents and their sections, which drift as those documents change - Update comments when changing code - Use proper grammar and formatting - Write for future maintainers @@ -161,3 +163,7 @@ One comment per decision. If a comment restates what the names and control flow - For changes involving identity or protected resources, prioritize authentication and per-resource authorization review For concrete detection patterns used by security review, see `references/security-checks.md`. + +## References + +- [references/frontend.md](references/frontend.md): read when implementing, reviewing, or fixing React/TypeScript code diff --git a/skills/coding-principles/references/frontend.md b/skills/coding-principles/references/frontend.md new file mode 100644 index 00000000..ba9f0363 --- /dev/null +++ b/skills/coding-principles/references/frontend.md @@ -0,0 +1,50 @@ +# Frontend (React/TypeScript) Coding Rules + +Apply these with the SKILL.md principles. Each entry adds what React and TypeScript code needs beyond them; the frontend decision criteria for component responsibility, error boundaries, and profiling live in `references/frontend.md` of the ai-development-guide skill. + +## Type Safety + +**Default Rule**: Prefer `unknown`, generics, or union types over `any`. Retain `any` only when an existing external, generated, or legacy public signature requires it, or when replacing it prevents the project type check from expressing a safe generic relationship. Record the declaration path or type-check result that proves the constraint. When a local adapter can preserve compatibility and expose a safer type within the user request or current task/design artifact, implement the adapter; otherwise confine `any` to the smallest adapter or public-signature boundary, document the reason, and validate untrusted data before it enters typed application code. + +**Frontend Boundaries** + +- React Props/State: use the declared application types. +- External API responses: treat unvalidated payloads as `unknown` and validate at the boundary. A generated client may retain its declared type when it also enforces the contract at runtime. +- `localStorage` / `sessionStorage`: handle `string | null`; treat parsed data as `unknown` until validated. +- URL parameters: handle the router or platform's nullable string shape, then parse and validate before converting to a domain type. +- Exported APIs and important boundaries: declare return types; allow inference for local implementations when the contract remains clear. + +**Type Complexity Review Signals** + +Use these as review prompts, not pass/fail thresholds. Existing project conventions and the component's responsibility take precedence. + +- Props count: review ownership or splitting above 10. +- Optional props: review defaults or ownership when more than half are optional. +- Nested prop structures: review flattening beyond 2 levels. +- Type assertions: review the boundary when 3+ assertions are required. +- External API types: represent the actual external shape and convert at the application boundary. + +## Components and State + +- Prefer function components and Hooks for new code. Preserve working class components unless the accepted work requires migration; a class remains valid for an Error Boundary implementation. +- Follow the project's adopted component architecture and file layout. Co-locate files only when it is established or approved as a new structure. +- Preserve the repository's existing local, shared, and server-state ownership boundaries. Introduce Context, a shared-state layer, or a server-state dependency only when the accepted design requires ownership or lifecycle that the existing boundary cannot represent. +- Keep one authoritative owner for each state value and use the immutable updates React change detection requires. +- Guard effect-driven requests against stale or post-unmount updates through the repository's cancellation or server-state mechanism. + +## Server/Client Boundary — only for RSC frameworks + +- Fetch and render on the server by default; isolate interactivity behind the smallest `"use client"` boundary that needs it. +- Keep browser-only APIs and event handlers inside client components. +- Skip these rules when the project has no server-component runtime. + +## Environment and Client Security + +- Read client-side environment variables through the project's bundler accessor and public prefix. Validate required values through the repository's typed config layer; add a default only for an optional value or an explicitly defined local-development mode. +- Browser-delivered code and public environment variables are observable by clients, so credentials and secrets stay on the server. + +## Performance and Compatibility + +- When React Compiler is enabled, rely on it. Add manual `React.memo`, `useMemo`, or `useCallback` only for a measured bottleneck or a required stable identity at an external API/effect boundary. +- Apply code splitting or import changes when a configured bundle budget regresses, or when the accepted task names bundle size as an outcome and a repository bundle report attributes the relevant increase to the changed import. Follow the repository's existing loading pattern and verify the same signal after the change. +- Implement against the browser support policy in the PRD, Design Doc, Browserslist, or build configuration. When none is defined, preserve the repository's current transpilation/polyfill baseline and surface any new browser-dependent API as an unresolved compatibility decision. diff --git a/skills/implementation-approach/SKILL.md b/skills/implementation-approach/SKILL.md index 46ee41dc..b9784615 100644 --- a/skills/implementation-approach/SKILL.md +++ b/skills/implementation-approach/SKILL.md @@ -24,7 +24,7 @@ Historical Context Understanding: Current form rationale, past decision validity - What dependencies or implicit preconditions are unclear from the code? - What benefits and constraints does the current design bring? -Stop when another current-state fact cannot change responsibility, reuse, option validity, total complexity, a contract, or verification. +Stop when the current-state facts that could change responsibility, reuse, option validity, total complexity, a contract, or verification have been checked; find existing code as coding-principles Reference Representativeness describes. ### Phase 2: Design Convergence @@ -32,7 +32,7 @@ Complete these steps in order before selecting an implementation strategy: 1. **Existing-Surface Baseline**: Form the simplest end-to-end path that delivers the current outcome through existing responsibilities. Explicit requirements and accepted decisions are binding; suggested mechanisms remain candidates. 2. **Evidence Check**: Test that path against current requirements, verified constraints, observed in-scope problems, and evidence-backed material risks. Keep only the unmet conditions that can change the selected design. Where the requirements leave a quality level unset, such as performance, freshness, consistency, availability, or protection beyond the required trust boundary, test against the lowest level that still delivers the outcome and record it as the selected level. -3. **Targeted Comparison**: For each unmet condition, test reuse, derivation from existing data, on-demand computation, or responsibility at the current caller or boundary before adding design surface. Compare viable choices by total complexity across the dimensions that materially differ: user decisions, settings, modes, concepts, outputs, persistent state, implementation paths, UX, runtime, implementation, testing, documentation, and maintenance. Select the lowest-total-complexity choice that satisfies the condition. +3. **Targeted Comparison**: For each unmet condition, test reuse, derivation from existing data, on-demand computation, or responsibility at the current caller or boundary before adding design surface. Compare viable choices by total complexity across the dimensions that materially differ: user decisions, settings, modes, concepts, outputs, persistent state, implementation paths, UX, runtime, implementation, testing, documentation, and maintenance. A second implementation of a responsibility that already has an owner with the same contract and change reason, including one added earlier in the same change, adds design surface; reusing or relocating that owner removes it. Select the lowest-total-complexity choice that satisfies the condition. 4. **Subtraction Check**: Remove each proposed addition and re-test its governing condition. Retain it only when the outcome, a required boundary, or necessary proof becomes unmet at its origin (a requirement, an accepted decision, or a repository rule or contract); a criterion, invariant, or constraint that a workflow artifact derived from that origin is narrowed to what the origin requires instead. Classify supporting claims as observed, inferred, or unknown. Route an unknown that blocks the next step as an exact evidence prerequisite; the caller's value-boundary and irreversible-action gates determine whether user interaction is required. diff --git a/skills/integration-e2e-testing/SKILL.md b/skills/integration-e2e-testing/SKILL.md index aa037f1f..9ad86fdd 100644 --- a/skills/integration-e2e-testing/SKILL.md +++ b/skills/integration-e2e-testing/SKILL.md @@ -29,6 +29,8 @@ Selection evidence: [required claim, uncovered failure, and why cheaper existing Use the project's comment syntax to wrap these annotations (e.g., `//` for C-family, `#` for Python/Ruby/Shell). +`Selection evidence` serves test selection and planning, so the implementing task removes it when it makes the test executable. + ### Verification Items (Optional) When verification points need explicit enumeration: diff --git a/skills/recipe-build/SKILL.md b/skills/recipe-build/SKILL.md index 14d4ca35..2056e556 100644 --- a/skills/recipe-build/SKILL.md +++ b/skills/recipe-build/SKILL.md @@ -134,4 +134,5 @@ Final report must include: - Commit count - Cleanup result - Declined actionable findings with ID, governing reason, and evidence, when any occurred +- Findings outside the change that remain unhandled, with location and evidence, when any remain - Escalation or blocking summary, if any diff --git a/skills/recipe-front-adjust/SKILL.md b/skills/recipe-front-adjust/SKILL.md index f44aa004..53569f2e 100644 --- a/skills/recipe-front-adjust/SKILL.md +++ b/skills/recipe-front-adjust/SKILL.md @@ -92,7 +92,7 @@ Present the adjustment context to the user for review. ### Step 5: Adjustment + Verification (parent session) 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: coding-principles and read its `references/frontend.md` 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 628b61f3..8bd9cf29 100644 --- a/skills/recipe-front-build/SKILL.md +++ b/skills/recipe-front-build/SKILL.md @@ -134,4 +134,5 @@ Final report must include: - Commit count - Cleanup result - Declined actionable findings with ID, governing reason, and evidence, when any occurred +- Findings outside the change that remain unhandled, with location and evidence, when any remain - Escalation or blocking summary, if any diff --git a/skills/recipe-front-review/SKILL.md b/skills/recipe-front-review/SKILL.md index e363bab3..a339b44b 100644 --- a/skills/recipe-front-review/SKILL.md +++ b/skills/recipe-front-review/SKILL.md @@ -153,7 +153,7 @@ Use the shared **Re-run rule** to select the owners of the findings corrected in Apply Review Resolution to each returned reconciliation. Return maintained applied findings to their correction owner; proceed to Step 9 at convergence. -Before Step 9, retry each retained quality-fixer-frontend limitation once with the same Step 7 inputs and affected check. Remove a limitation when the retry passes, route newly discovered incomplete implementation through Steps 6-8, and report a repeated `verification_incomplete` result. Apply the shared Re-run rule, including its changed-boundary check for mutations outside received findings, before reporting. +Before Step 9, retry each retained quality-fixer-frontend limitation once with the same Step 7 inputs and affected check. Remove a limitation when the retry passes, route newly discovered incomplete implementation through Steps 6-8, and report a repeated `verification_incomplete` result. Apply the shared Re-run rule, including its check of whether the corrections invalidated evidence a passed review relied on, before reporting. ### Step 9: Final Report diff --git a/skills/recipe-fullstack-build/SKILL.md b/skills/recipe-fullstack-build/SKILL.md index b84d1905..17872b4b 100644 --- a/skills/recipe-fullstack-build/SKILL.md +++ b/skills/recipe-fullstack-build/SKILL.md @@ -152,4 +152,5 @@ Final report must include: - Commit count - Cleanup result - Declined actionable findings with ID, governing reason, and evidence, when any occurred +- Findings outside the change that remain unhandled, with location and evidence, when any remain - Escalation or blocking summary, if any diff --git a/skills/recipe-review/SKILL.md b/skills/recipe-review/SKILL.md index b95c562b..32dafcb9 100644 --- a/skills/recipe-review/SKILL.md +++ b/skills/recipe-review/SKILL.md @@ -153,7 +153,7 @@ Use the shared **Re-run rule** to select the owners of the findings corrected in Apply Review Resolution to each returned reconciliation. Return maintained applied findings to their correction owner; proceed to Step 9 at convergence. -Before Step 9, retry each retained quality-fixer limitation once with the same Step 7 inputs and affected check. Remove a limitation when the retry passes, route newly discovered incomplete implementation through Steps 6-8, and report a repeated `verification_incomplete` result. Apply the shared Re-run rule, including its changed-boundary check for mutations outside received findings, before reporting. +Before Step 9, retry each retained quality-fixer limitation once with the same Step 7 inputs and affected check. Remove a limitation when the retry passes, route newly discovered incomplete implementation through Steps 6-8, and report a repeated `verification_incomplete` result. Apply the shared Re-run rule, including its check of whether the corrections invalidated evidence a passed review relied on, before reporting. ### Step 9: Final Report diff --git a/skills/subagents-orchestration-guide/SKILL.md b/skills/subagents-orchestration-guide/SKILL.md index 887356c6..34ce9448 100644 --- a/skills/subagents-orchestration-guide/SKILL.md +++ b/skills/subagents-orchestration-guide/SKILL.md @@ -211,9 +211,9 @@ Reviewer findings are candidates. Create correction work only from the Review Re **Fix-cycle handoff**: Apply Review Resolution and invoke each correction owner it selects. For an author-owned technical-artifact correction, invoke the layer-appropriate technical designer in update mode, run the artifact's existing document-reviewer and applicable design-sync gates, then re-run the originating reviewer. For an executor-owned correction, invoke the layer-appropriate executor with its original `task_file` or direct-scope fields plus `correction_findings` as the complete `apply` finding objects verbatim with only their dispositions added, then branch on the executor result through the per-task cycle's step 2, including its conditional integration-test-reviewer path, and run the applicable quality gate. When both owners are required, Review Resolution's author-first re-evaluation controls the order. Carry `prior_feedback` only to a reviewer or verifier being rechecked. Post-implementation corrections stay uncommitted through this cycle: the reviewers read the current working tree, so run the applicable quality gate and re-run the originating reviewer on the uncommitted changes, and commit the applied corrections once through Commit Boundary Check after the complete review set reaches Review Resolution convergence. -**Re-run rule**: After an applied post-implementation correction, re-run only the reviewer that owns a corrected finding from its latest result. For these finding-owned corrections, retain every passed reviewer result, including after another reviewer's correction. Pass the previous complete result, dispositions, and correction diff or paths to the rerun. After Specialist Result Acceptance recovers a blocked review prerequisite, re-run that reviewer. Review Resolution convergence governs acceptance and preserves resolved declines. +**Re-run rule**: After an applied post-implementation correction, re-run only the reviewer that owns a corrected finding from its latest result. Retain every other passed reviewer result, including after another reviewer's correction, unless the check below finds that the correction invalidated the evidence that review relied on. Pass the previous complete result, dispositions, and correction diff or paths to the rerun. After Specialist Result Acceptance recovers a blocked review prerequisite, re-run that reviewer. Review Resolution convergence governs acceptance and preserves resolved declines. -When a quality-fixer retry changes behavior outside the received findings, compare its actual diff against the already reviewed boundaries. Reconcile changes covered by an existing finding through its owner. For other behavior changes that invalidate review evidence, invoke only the applicable code-reviewer or security-reviewer with the original governing documents and the affected `implementationFiles`, scoped to that diff and its directly affected boundary; omit `prior_feedback` because this is new changed code, not finding reconciliation. Apply Review Resolution to its findings. Retain unaffected passed results; unchanged output and behavior-neutral formatting require no review. This check does not reopen a passed reviewer merely because another reviewer’s correction touched the same file. +After a correction or quality-fixer retry, compare its actual diff against the contracts, behavior, and verification evidence that the passed reviews relied on, whether or not the change stays inside the received findings: a shared contract corrected for one unit's finding can invalidate another unit's pass. Reconcile changes covered by an existing finding through its owner. For other changes that invalidate review evidence, invoke only the applicable code-reviewer or security-reviewer with the original governing documents and the affected `implementationFiles`, scoped to that diff and its directly affected boundary; omit `prior_feedback` because this is new changed code, not finding reconciliation. Apply Review Resolution to its findings. Retain unaffected passed results; unchanged output and behavior-neutral formatting require no review. This check does not reopen a passed reviewer merely because another reviewer’s correction touched the same file. ### Conditions for Stopping Autonomous Execution @@ -262,6 +262,8 @@ Derive the values from the quality-fixer result. Keep the complete result in orc - `pass` → Proceed to step 4 4. **Commit**: apply Commit Boundary Check, then compose the message from `changeSummary` and execute git commit with Bash after `pass` or `verification_incomplete`; append the verification trailers for the latter +**Findings outside the change**: Retain each executor `findingsOutsideChange` item; one the outcome needs is incomplete implementation under Specialist Result Acceptance. When the workflow runs post-implementation review, an item in work this workflow produced enters Review Resolution with the review findings, and the code-reviewer whose `implementationFiles` contain its location owns an applied one. List the items left unhandled with their location and evidence in the completion report. + Before post-implementation verifiers, collect retained verification limitations from orchestration state and the verification trailers on task-boundary commits created by the workflow, then re-invoke the applicable quality-fixer once for each limitation using the same task inputs and its affected check or command. When the retry returns `pass`, remove that limitation from retained state. Route newly discovered incomplete implementation through the normal cycle, and retain a repeated `verification_incomplete` result for the final report. Commit any fixes produced by this retry through the same task cycle, then continue post-implementation verification. ## Handoff Contracts diff --git a/skills/testing-principles/references/e2e.md b/skills/testing-principles/references/e2e.md index b0e06542..df87bf72 100644 --- a/skills/testing-principles/references/e2e.md +++ b/skills/testing-principles/references/e2e.md @@ -42,4 +42,4 @@ Use the repository's existing seed and authentication mechanisms. Create per-tes ## Skeleton Annotations -Preserve the skeleton's annotations unchanged. When `Verification items:` are present, implement and assert every listed item. +Preserve the skeleton's annotations unchanged, except `Selection evidence`, which served test selection only and is removed when the test becomes executable. When `Verification items:` are present, implement and assert every listed item. diff --git a/skills/testing-principles/references/frontend.md b/skills/testing-principles/references/frontend.md index 9b683622..a961645e 100644 --- a/skills/testing-principles/references/frontend.md +++ b/skills/testing-principles/references/frontend.md @@ -7,7 +7,7 @@ Before writing a test, inspect package scripts, runner configuration, setup file - Use React Testing Library when it is the project's component-test renderer; prefer `userEvent` for user interactions. - Use the repository's network mocking layer for API behavior. When MSW is configured, extend its handlers instead of adding runner-level fetch mocks. - Use the configured runner's imports, module-mocking API, fake timers, and reset conventions. -- When multiple approaches coexist, follow the dominant convention in the changed feature area. If none is representative and adding or replacing tooling is outside the approved work, report the missing test-environment decision. +- When multiple approaches coexist, choose from the behavior under test and the setup the repository maintains for it rather than from proximity alone. If none is representative and adding or replacing tooling is outside the approved work, report the missing test-environment decision. ## Test Scope diff --git a/skills/typescript-rules/SKILL.md b/skills/typescript-rules/SKILL.md deleted file mode 100644 index df4751bd..00000000 --- a/skills/typescript-rules/SKILL.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -name: typescript-rules -description: React/TypeScript frontend development rules including type safety, component design, state management, and error handling. Use when implementing React components, TypeScript code, or frontend features. ---- - -# TypeScript Development Rules (Frontend) - -## Comment Writing Rules - -Code first: names and types carry meaning; a comment must add what code cannot, and one comment per decision is enough. - -- Explain why a component memoizes, guards, or re-renders, not what the JSX renders. -- Record decisions and rationale; leave chronological history to version control. - -## Type Safety - -**Default Rule**: Prefer `unknown`, generics, or union types over `any`. Retain `any` only when an existing external, generated, or legacy public signature requires it, or when replacing it prevents the project type check from expressing a safe generic relationship. Record the declaration path or type-check result that proves the constraint. When a local adapter can preserve compatibility and expose a safer type within the user request or current task/design artifact, implement the adapter; otherwise confine `any` to the smallest adapter or public-signature boundary, document the reason, and validate untrusted data before it enters typed application code. - -**Frontend Boundaries** - -- React Props/State: use the declared application types. -- External API responses: treat unvalidated payloads as `unknown` and validate at the boundary. A generated client may retain its declared type when it also enforces the contract at runtime. -- `localStorage` / `sessionStorage`: handle `string | null`; treat parsed data as `unknown` until validated. -- URL parameters: handle the router or platform's nullable string shape, then parse and validate before converting to a domain type. -- Exported APIs and important boundaries: declare return types; allow inference for local implementations when the contract remains clear. - -**Type Complexity Review Signals** - -Use these as review prompts, not pass/fail thresholds. Existing project conventions and the component's responsibility take precedence. - -- Props count: review ownership or splitting above 10. -- Optional props: review defaults or ownership when more than half are optional. -- Nested prop structures: review flattening beyond 2 levels. -- Type assertions: review the boundary when 3+ assertions are required. -- External API types: represent the actual external shape and convert at the application boundary. - -## Coding Conventions - -**Component and File Decisions** - -- Prefer function components and Hooks for new code. Preserve working class components unless the accepted work requires migration; a class remains valid for an Error Boundary implementation. -- Reuse logic through the repository's established component, hook, or module pattern. -- Follow the project's adopted component architecture and file layout. Co-locate files only when it is established or approved as a new structure. - -**Server/Client Boundary — only for RSC frameworks** - -- Fetch and render on the server by default; isolate interactivity behind the smallest `"use client"` boundary that needs it. -- Keep browser-only APIs and event handlers inside client components. -- Skip these rules when the project has no server-component runtime. - -**State Ownership** - -- Preserve the repository's existing local, shared, and server-state ownership boundaries. -- Introduce Context, a shared-state layer, or a server-state dependency only when the accepted design requires ownership or lifecycle that the existing boundary cannot represent. -- Keep one authoritative owner for each state value and use immutable updates required by React change detection. - -**Function and Props Boundaries** - -- Prefer 0-2 parameters. For 3+ related values, use an object when it clarifies names or represents one domain input; preserve positional parameters when the repository convention or external API requires them. -- Declare component dependencies through typed props, hooks, Context, or injected modules according to the repository's established state and dependency boundaries. - -**Environment Variables** - -- Read client-side environment variables through the project's bundler accessor and public prefix. -- Validate required values through the repository's typed config layer; add a default only for an optional value or an explicitly defined local-development mode. - -**Client Security** - -- Keep credentials and secrets on the server; browser-delivered code and public environment variables are observable by clients. -- Exclude local environment files from version control and keep error output free of sensitive values. - -**Asynchronous Processing** - -- Follow the repository's promise style; use `async`/`await` when it clarifies sequencing and error propagation. -- Handle event-handler and asynchronous failures at their owning boundary. Error Boundaries cover descendant rendering failures, not ordinary callbacks or asynchronous work. -- Guard effect-driven requests against stale or post-unmount updates through the repository's cancellation or server-state mechanism. - -**Formatting** - -- Follow the repository's formatter, naming, module-resolution, and package-boundary configuration. -- Use an import alias only when the project configuration resolves it. - -## Error Handling - -Every caught error has one intentional outcome: propagate it, convert it to the repository's typed boundary result, or represent it as user-facing error state. Preserve context and log once at the boundary that owns diagnosis or recovery, with sensitive data redacted. - -- Error Boundary: place it where descendant render failures have a defined UI recovery outcome. -- Custom Hook: preserve the application's existing error contract. -- API Layer: convert transport failures to the repository's established domain or boundary representation. -- Event handlers and async workflows: use the owning layer's exception, result, or UI-state contract. - -## Performance Optimization - -- When React Compiler is enabled, rely on it. Add manual `React.memo`, `useMemo`, or `useCallback` only for a measured bottleneck or a required stable identity at an external API/effect boundary. -- Apply code splitting or import changes when a configured bundle budget regresses, or when the accepted task names bundle size as an outcome and a repository bundle report attributes the relevant increase to the changed import. Follow the repository's existing loading pattern and verify the same signal after the change. - -## Non-functional Requirements - -- **Browser Compatibility**: Implement against the support policy in the PRD, Design Doc, Browserslist, or build configuration. When none is defined, preserve the repository's current transpilation/polyfill baseline and surface any new browser-dependent API as an unresolved compatibility decision. -- **Performance**: Verify against project-defined budgets and the metric representing the affected experience. When no budget exists, measure the changed path and report the observed result instead of inventing a threshold.