diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 1ab4fd0..3ab977b 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.19.0", + "version": "0.19.1", "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", @@ -83,7 +83,7 @@ "name": "dev-workflows-frontend", "source": "./dev-workflows-frontend", "strict": true, - "version": "0.19.0", + "version": "0.19.1", "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", @@ -154,7 +154,7 @@ "name": "dev-workflows-fullstack", "source": "./dev-workflows-fullstack", "strict": true, - "version": "0.19.0", + "version": "0.19.1", "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", @@ -242,7 +242,7 @@ "name": "dev-skills", "source": "./dev-skills", "strict": true, - "version": "0.19.0", + "version": "0.19.1", "description": "Lightweight skills for users with existing workflows - coding best practices, testing principles, and design guidelines without recipe workflows or agents", "author": { "name": "Shinsuke Kagawa", diff --git a/agents/code-reviewer.md b/agents/code-reviewer.md index 684fdf4..423619c 100644 --- a/agents/code-reviewer.md +++ b/agents/code-reviewer.md @@ -293,6 +293,7 @@ Recommend higher-level review when: - Implementation significantly exceeds Design Doc quality - Security concerns discovered - Critical performance issues found +- Implementation introduces in-scope elements (persistent state; public-contract or cross-boundary fields/props; behavioral modes/flags/variants; reusable abstractions or component splits) that are absent from the Design Doc's Minimal Surface Alternatives section ## Special Considerations diff --git a/agents/document-reviewer.md b/agents/document-reviewer.md index c544a36..7e582c1 100644 --- a/agents/document-reviewer.md +++ b/agents/document-reviewer.md @@ -83,6 +83,7 @@ For DesignDoc, additionally verify: - [ ] Field propagation map present (when fields cross boundaries) - [ ] Verification Strategy section present with: correctness definition, verification method, verification timing, early verification point - [ ] Fact Disposition Table present and covers every `codebase_analysis.focusAreas` entry (when `codebase_analysis` is provided) +- [ ] Minimal Surface Alternatives section present with one entry per new in-scope element (persistent state / public-contract or cross-boundary field or prop / behavioral mode/flag/variant / reusable abstraction or component split) (when the design introduces any). Each entry contains the 5-step output (fixed requirements with AC IDs or accepted technical constraint IDs, alternatives table including at least one subtractive option, selected alternative with rationale, rejected alternatives log) #### Gate 1: Quality Assessment (only after Gate 0 passes) @@ -103,6 +104,14 @@ For DesignDoc, additionally verify: - **Verification Strategy quality check**: When Verification Strategy section exists, verify: (1) Correctness definition is specific and measurable — "tests pass" without specifying which tests or what they verify → `important` issue (category: `completeness`). (2) Verification method is sufficient for the change's risk and dependency type — method that cannot detect the primary risk category (e.g., schema correctness, behavioral equivalence, integration compatibility) → `important` issue (category: `consistency`). (3) Early verification point identifies a concrete first target — "TBD" or "final phase" → `important` issue (category: `completeness`). (4) When vertical slice is selected, verification timing deferred entirely to final phase → `important` issue (category: `consistency`) - **Output comparison check**: When the Design Doc describes replacing or modifying existing behavior, verify that a concrete output comparison method is defined (identical input, expected output fields/format, diff method). Missing output comparison for behavior-replacing changes → `critical` issue (category: `completeness`). When codebase analysis `dataTransformationPipelines` are referenced, verify each pipeline step's output is covered by the comparison — uncovered steps → `important` issue (category: `completeness`) - **Fact disposition completeness check**: When `codebase_analysis` is provided, every entry in `focusAreas` requires a corresponding row in the Fact Disposition Table. Missing rows → `critical` issue (category: `completeness`). `fact_id` missing or not carrying through the focusArea's `fact_id` value → `critical` issue (category: `consistency`). Disposition value other than `preserve` / `transform` / `remove` / `out-of-scope` → `important` issue (category: `consistency`). Rationale missing for `transform` / `remove` / `out-of-scope` → `important` issue (category: `completeness`). Evidence column not carrying through the focusArea's evidence value → `important` issue (category: `consistency`) +- **Minimal Surface Alternatives check**: + - *Scope trigger*: applies when the Design Doc introduces in-scope elements (persistent state; public-contract or cross-boundary fields or props; behavioral modes, flags, or variants; reusable abstractions or component splits). + - *Section existence*: when the trigger fires but the "Minimal Surface Alternatives" section is absent or empty → `critical` issue (category: `completeness`). + - *Per Element entry*: + - (1) Step 1 lists at least one AC ID or accepted technical constraint from the Design Doc → missing linkage or only speculative requirements ("future", "might want") → `critical` issue (category: `compliance`). + - (2) Steps 2–3 include at least one subtractive alternative (derive / compute on demand / keep at caller / reuse existing / do not introduce new state) → missing subtractive alternative → `critical` issue (category: `compliance`). + - (3) Step 4 rationale either selects the smallest alternative or names a current requirement smaller alternatives fail to satisfy → "useful" / "future-ready" / "convenient" / "users might want" used as primary rationale → `critical` issue (category: `compliance`). + - (4) Step 5 records the rejected alternatives with brief rationale → missing rejected alternatives log → `important` issue (category: `completeness`). **Perspective-specific Mode**: - Implement review based on specified mode and focus @@ -264,6 +273,7 @@ Include in output when `prior_context_count > 0`: - [ ] Verification Strategy aligns with design_type and implementation approach - [ ] Output comparison defined when design replaces/modifies existing behavior (covers all transformation pipeline steps) - [ ] Fact Disposition Table covers every `codebase_analysis.focusAreas` entry (when `codebase_analysis` is provided) +- [ ] Minimal Surface Alternatives section covers every new in-scope element (persistent state / public-contract or cross-boundary field or prop / behavioral mode/flag/variant / reusable abstraction or component split) with the 5-step output (when the design introduces any); selection rationale cites a named current requirement that smaller alternatives fail to satisfy, or names the smallest alternative as selected ## Review Criteria (for Comprehensive Mode) diff --git a/agents/technical-designer-frontend.md b/agents/technical-designer-frontend.md index 74bcebb..70ff261 100644 --- a/agents/technical-designer-frontend.md +++ b/agents/technical-designer-frontend.md @@ -39,6 +39,7 @@ The subsections below are not parallel mandates; they form four serial gates. Co **Gate 1 — Existing State Analysis** (depends on Gate 0): - Existing Code Investigation - Fact Disposition (when Codebase Analysis input is provided) +- Minimal Surface Alternatives (when introducing persistent client/server state, props or fields crossing component boundaries, behavioral modes/variants, or reusable component splits) **Gate 2 — Design Decisions** (depends on Gate 1): - Implementation Approach Decision @@ -117,6 +118,41 @@ For every entry in `Codebase Analysis.focusAreas`, produce one row in the Design The Fact Disposition Table is the single mechanism that binds existing-behavior facts to the design. Other Design Doc sections that describe existing behavior reference the corresponding Disposition Table row by Focus Area name. +### Minimal Surface Alternatives [Gate 1 — Required when introducing persistent client/server state, props or fields crossing component boundaries, behavioral modes/variants, or reusable component splits] + +Applies to each maintenance-surface-bearing element the design introduces. The goal is to select the smallest design surface that satisfies the same current requirements. Reference: coding-principles skill, "Minimum Surface for Required Coverage". + +**In scope**: persistent state (localStorage/sessionStorage/IndexedDB/cookies/server-saved fields — i.e., state that survives reload, navigation, or session, or is saved outside component memory); props or fields crossing component boundaries (props passed between components, Context values, lifted state); behavioral modes/variants (component variants, mode props, conditional rendering modes); reusable component splits (extracted sub-components, custom hooks, or utilities intended for reuse by multiple parents). + +**Out of scope**: local `useState` / `useReducer` confined to a single component's internal logic (does not survive reload); private hooks used by one component; test fixture or mock props; transient render-only state; internal helper functions without external observers. + +**Precedence**: when an element matches both an in-scope and an out-of-scope condition (e.g., a prop that is both "passed to one child component" and "lifted to Context"), the in-scope classification wins and the gate applies. + +Execute the 5 steps below for each in-scope element, and record the result in the Design Doc's "Minimal Surface Alternatives" section. + +1. **Fix Requirements** + - List the current user-visible requirements / ACs / accepted technical constraints (audit, accessibility, performance, security, compatibility) this element would serve, citing AC IDs or constraint IDs from the Design Doc or referenced UI Spec. + - Eligibility rule: only requirements / constraints that are part of the current Design Doc's adopted scope qualify. Future-only, speculative, or "users might want" requirements are out of scope for this list. + +2. **Diverge** (generate alternatives) + - Produce at least 2 alternative realizations that cover the same fixed requirements. + - At least one alternative must be subtractive. Subtractive alternatives are drawn from: derive from existing props/state, lift state to existing parent, reuse existing component or variant, keep at caller / URL / server response, do not introduce a new mode. + +3. **Compare** (record alternatives in a table) + + | Alternative | Current requirements covered (AC or constraint IDs) | New persistent state (client or server, count) | New props / modes / variants (count) | Crosses component boundary (yes/no) | Breaking change or migration required (yes/no) | Subjective cost notes | + |---|---|---|---|---|---|---| + + Resolution priority (later columns are tiebreakers when earlier are equal): (1) new persistent state (lower=smaller); (2) crosses component boundary (no=smaller); (3) new props/modes/variants (lower=smaller); (4) breaking change or migration (no=smaller); (5) subjective cost notes. + +4. **Converge** (select) + - Select the alternative with the smallest surface that covers all fixed requirements, applying the resolution priority above. + - When the selected alternative is not the smallest, name the current requirement (from step 1) that smaller alternatives fail to satisfy. + - "Reusable" / "future-ready" / "convenient for implementation" / "users might want" belong in the Subjective cost notes column (tiebreakers only). + +5. **Record Rejected Alternatives** + - For each rejected alternative, record 1-2 lines: what it was, why rejected. Include in the Design Doc to prevent re-proposal in subsequent iterations or by future agents. + ### Implementation Approach Decision [Gate 2 — Required] Must be performed when creating Design Doc: @@ -262,27 +298,11 @@ Execute file output immediately (considered approved at execution). ## Important Design Principles -1. **Consistency First Priority**: Follow existing React component patterns, document clear reasons when introducing new patterns -2. **Appropriate Abstraction**: Design optimal for current requirements, thoroughly apply YAGNI principle (follow project rules) -3. **Testability**: Props-driven design and mockable custom hooks -4. **Test Derivation from Feature Acceptance Criteria**: Clear React Testing Library test cases that satisfy each feature acceptance criterion -5. **Explicit Trade-offs**: Quantitatively evaluate benefits and drawbacks of each option (performance, accessibility) -6. **Active Use of Latest Information**: - - Always research latest React best practices, libraries, and approaches with WebSearch before design - - Cite information sources in "References" section with URLs - - Especially confirm multiple reliable sources when introducing new technologies +Apply principles from loaded skills (`typescript-rules`, `frontend-ai-guide`, `testing-principles`). Trade-off evaluation (Gate 2 + ADR Checklist), existing-pattern consistency (Gate 1 Existing Code Investigation + Fact Disposition), and Verification Strategy from AC (Gate 2) are enforced above; test derivation itself is a downstream agent responsibility. Latest-information research is governed by the "Latest Information Research" section below. ## Implementation Sample Standards Compliance -Implementation samples in ADR and Design Docs follow the standards loaded from the `typescript-rules` and `frontend-ai-guide` skills: - -- Function components with explicit Props type definitions -- Custom hooks for logic reuse and testability -- Type safety: `unknown` + type guards for external responses -- Error handling: error boundaries and error state management -- Secrets remain server-side - -When sample code is needed, keep it minimal and follow concrete patterns from those skills. +All implementation samples in ADR and Design Docs MUST follow the loaded `typescript-rules` and `frontend-ai-guide` skills. Omit samples unless they clarify contracts or edge cases that prose cannot convey. ## Diagram Creation (using mermaid notation) @@ -311,7 +331,6 @@ These items test the final document output. Process gates (Gate 0-3) are enforce - [ ] Props type contracts are explicit for every integration point - [ ] Component hierarchy and data flow appear as diagrams - [ ] External Resources Used subsection lists feature-tier identifiers (when external resources apply) -- [ ] Fact Disposition Table covers every Codebase Analysis focusArea, each row with fact_id + disposition + rationale + evidence (when Codebase Analysis input was provided) **Create/update mode only**: - [ ] Prerequisite common ADRs are referenced @@ -359,13 +378,7 @@ These items test the final document output. Process gates (Gate 0-3) are enforce **When** (create/update mode): New library/framework introduction, performance optimization, accessibility design, major version upgrades. -Check current year with `date +%Y` and include in search queries: -- `[library] best practices {current_year}` -- `[lib A] vs [lib B] comparison {current_year}` -- `[framework] breaking changes migration guide` -- `[framework] accessibility best practices` - -Cite sources in "## References" section at end of ADR/Design Doc with URLs. +Check current year with `date +%Y` and include in search queries (e.g., `[library | framework] [best practices | vs comparison | breaking changes | accessibility] {current_year}`). Cite sources in "## References" section at end of ADR/Design Doc with URLs. **Reverse-engineer mode**: Skip. Research is for forward design decisions. @@ -391,22 +404,17 @@ Before modifying the document, inventory the external definitions that the chang **On conflict**: Log conflicting identifiers in the output. The orchestrator is responsible for presenting conflicts to the user -## Reverse-Engineer Mode (As-Is Frontend Documentation) - -Mode for documenting existing frontend architecture as-is. Used when creating Design Docs from existing implementation. +## Reverse-Engineer Mode -### What to Skip in Reverse-Engineer Mode -- ADR creation, option comparison, change impact analysis, latest information research, implementation approach decision +When `operation_mode: reverse-engineer`: -### Reverse-Engineer Mode Execution Steps +**Skip**: ADR creation, option comparison, change impact analysis, Latest Information Research, Implementation Approach Decision, Minimal Surface Alternatives. -1. **Read & Inventory**: Read every Primary File. Record component hierarchy, exported components, hooks, utilities. If Unit Inventory is provided, use it as a completeness baseline — all listed routes, exports, and test files should be accounted for in the Design Doc -2. **Trace Component Tree**: For each page/screen, read implementation and child components. Record: props, state management, data fetching, conditional rendering — as implemented -3. **Document Data Flow**: For each data fetching call: record endpoint, params, response shape. For state management: record state shape, update mechanisms, consumers -4. **Record Contracts**: For each component's interface, record prop names, types, required/optional — as written in code. Use exact identifiers from source -5. **Identify Test Coverage**: Glob for test files. Record which components have tests. Confirm test existence with Glob before reporting +**Execute**: +1. Read every Primary File; record component hierarchy, exported components, hooks, utilities. If Unit Inventory is provided, treat it as completeness baseline (every listed route, export, test file accounted for). +2. For each page/screen, read implementation and child components; record props, state management, data fetching, conditional rendering as implemented. +3. For each data-fetching call: record endpoint, params, response shape. For state management: record state shape, update mechanisms, consumers. +4. For each component's interface, record prop names, types, required/optional verbatim from code, using exact identifiers. +5. Glob for test files; record which components have tests. Confirm test existence by Glob. -### Reverse-Engineer Mode Quality Standard -- Every claim cites file:line as evidence -- Identifiers transcribed exactly from code -- Test existence confirmed by Glob, not assumed +**Quality**: every claim cites `file:line`; identifiers transcribed exactly; test existence confirmed by Glob. diff --git a/agents/technical-designer.md b/agents/technical-designer.md index 395f567..67c3ab2 100644 --- a/agents/technical-designer.md +++ b/agents/technical-designer.md @@ -41,6 +41,7 @@ The subsections below are not parallel mandates; they form four serial gates. Co - Existing Code Investigation - Fact Disposition (when Codebase Analysis input is provided) - Data Representation Decision (when new or modified data structures are introduced) +- Minimal Surface Alternatives (when introducing persistent state, public-contract or cross-boundary fields, behavioral modes/flags, or reusable abstractions) **Gate 2 — Design Decisions** (depends on Gate 1): - Implementation Approach Decision @@ -159,6 +160,41 @@ When the design introduces or significantly modifies data structures: - 3+ criteria fail → New structure justified - Record decision and rationale in Design Doc +### Minimal Surface Alternatives [Gate 1 — Required when introducing persistent state, public-contract or cross-boundary fields, behavioral modes/flags, or reusable abstractions] + +Applies to each maintenance-surface-bearing element the design introduces. The goal is to select the smallest design surface that satisfies the same current requirements. Reference: coding-principles skill, "Minimum Surface for Required Coverage". + +**In scope**: persistent state (DB columns/tables, file fields, cache entries, queue payloads, session/cookie data, any state outliving a single operation); public-contract elements (exported types, API request/response fields, exported function signatures, schema definitions); cross-boundary fields (passed between modules/services/components); behavioral modes/flags (state-machine states, feature flags, config options); reusable abstractions (new types/classes/modules/interfaces intended for reuse). + +**Out of scope**: local variables within a single function; internal struct fields used only within one module/package; test fixture or mock fields; transient state confined to a single operation; private state without external observers. + +**Precedence**: when an element matches both an in-scope and an out-of-scope condition (e.g., a struct field that is both "internal to one module" and "persisted to a DB column"), the in-scope classification wins and the gate applies. + +Execute the 5 steps below for each in-scope element, and record the result in the Design Doc's "Minimal Surface Alternatives" section. + +1. **Fix Requirements** + - List the current user-visible requirements / ACs / accepted technical constraints (audit, data integrity, compatibility, security, performance) this element would serve, citing AC IDs or constraint IDs from the Design Doc. + - Eligibility rule: only requirements / constraints that are part of the current Design Doc's adopted scope qualify. Future-only, speculative, or "users might want" requirements are out of scope for this list. + +2. **Diverge** (generate alternatives) + - Produce at least 2 alternative realizations that cover the same fixed requirements. + - At least one alternative must be subtractive. Subtractive alternatives are drawn from: derive from existing data, compute on demand, keep at caller / invocation boundary, reuse existing structure, do not introduce new state. + +3. **Compare** (record alternatives in a table) + + | Alternative | Current requirements covered (AC or constraint IDs) | New persistent state (count) | New concept / mode / flag (count) | Crosses component boundary (yes/no) | Breaking change or migration required (yes/no) | Subjective cost notes | + |---|---|---|---|---|---|---| + + Resolution priority (later columns are tiebreakers when earlier are equal): (1) new persistent state (lower=smaller); (2) crosses component boundary (no=smaller); (3) new concept/mode/flag (lower=smaller); (4) breaking change or migration (no=smaller); (5) subjective cost notes. + +4. **Converge** (select) + - Select the alternative with the smallest surface that covers all fixed requirements, applying the resolution priority above. + - When the selected alternative is not the smallest, name the current requirement (from step 1) that smaller alternatives fail to satisfy. + - "Useful" / "future-ready" / "convenient for implementation" / "users might want" belong in the Subjective cost notes column (tiebreakers only). + +5. **Record Rejected Alternatives** + - For each rejected alternative, record 1-2 lines: what it was, why rejected. Include in the Design Doc to prevent re-proposal in subsequent iterations or by future agents. + ### Implementation Approach Decision [Gate 2 — Required] Must be performed when creating Design Doc: @@ -299,24 +335,11 @@ Execute file output immediately (considered approved at execution). ## Important Design Principles -1. **Consistency First Priority**: Follow existing patterns, document clear reasons when introducing new patterns -2. **Appropriate Abstraction**: Design optimal for current requirements, thoroughly apply YAGNI principle (follow project rules) -3. **Testability**: Parameterized dependencies (dependency injection, function parameters) and mockable design -4. **Test Derivation from Feature Acceptance Criteria**: Clear test cases that satisfy each feature acceptance criterion -5. **Explicit Trade-offs**: Quantitatively evaluate benefits and drawbacks of each option -6. **Active Use of Latest Information**: - - Always research latest best practices, libraries, and approaches with WebSearch before design - - Cite information sources in "References" section with URLs - - Especially confirm multiple reliable sources when introducing new technologies +Apply principles from loaded skills (`coding-principles`, `testing-principles`, `ai-development-guide`). Trade-off evaluation (Gate 2 + ADR Checklist), existing-pattern consistency (Gate 1 Existing Code Investigation + Fact Disposition), and Verification Strategy from AC (Gate 2) are enforced above; test derivation itself is a downstream agent responsibility. Latest-information research is governed by the "Latest Information Research" section below. ## Implementation Sample Standards Compliance -**MANDATORY**: All implementation samples in ADR and Design Docs MUST strictly comply with project coding standards. - -Implementation sample creation checklist: -- Follow language-appropriate correctness guarantee patterns -- Apply appropriate design patterns for the language -- Implement robust error handling strategies +All implementation samples in ADR and Design Docs MUST follow the loaded `coding-principles` and `testing-principles` skills. Omit samples unless they clarify contracts or edge cases that prose cannot convey. ## Diagram Creation (using mermaid notation) @@ -340,7 +363,6 @@ These items test the final document output. Process gates (Gate 0-3) are enforce - [ ] Architecture and data flow appear as diagrams - [ ] External Resources Used subsection lists feature-tier identifiers (when external resources apply) - [ ] Quality Assurance Mechanisms list adopted/noted status for checks covering this change -- [ ] Fact Disposition Table covers every Codebase Analysis focusArea, each row with fact_id + disposition + rationale + evidence (when Codebase Analysis input was provided) **Create/update mode only**: - [ ] Prerequisite common ADRs are referenced @@ -350,10 +372,7 @@ These items test the final document output. Process gates (Gate 0-3) are enforce - [ ] Interface change matrix is complete - [ ] Implementation approach selection (vertical/horizontal/hybrid) carries rationale - [ ] `complexity_level` is set; when medium/high, `complexity_rationale` covers (1) requirements/ACs, (2) constraints/risks -- [ ] Data representation decision is documented when new structures are introduced -- [ ] Field propagation map is included when fields cross boundaries - [ ] Verification Strategy defines correctness, method, timing, and early verification point -- [ ] Output comparison defines input, expected output fields, and diff method when behavior is replaced or modified (covers every transformation pipeline step from codebase analysis) **Reverse-engineer mode only**: - [ ] Every architectural claim cites file:line @@ -363,13 +382,7 @@ These items test the final document output. Process gates (Gate 0-3) are enforce ## Acceptance Criteria Creation Guidelines -1. **Principle**: Set specific, verifiable conditions. Avoid ambiguous expressions, document in format convertible to test cases. -2. **Example**: "Login works" → "After authentication with correct credentials, navigates to dashboard screen" -3. **Comprehensiveness**: Cover happy path, unhappy path, and edge cases. Define non-functional requirements in separate section. - - Expected behavior (happy path) - - Error handling (unhappy path) - - Edge cases -4. **Priority**: Place important acceptance criteria at the top +Each AC must be specific, verifiable, and convertible to a test case — avoid ambiguous expressions (e.g., "Login works" → "After authentication with correct credentials, navigates to dashboard screen"). Cover happy path, unhappy path, and edge cases; non-functional requirements belong in a separate section. Highest-priority AC first. Concrete scoping rules below. ### AC Scoping for Autonomous Implementation @@ -397,12 +410,7 @@ These items test the final document output. Process gates (Gate 0-3) are enforce **When** (create/update mode): New technology/library introduction, performance optimization, security design, major version upgrades. -Check current year with `date +%Y` and include in search queries: -- `[technology] [feature] best practices {current_year}` -- `[tech A] vs [tech B] comparison {current_year}` -- `[framework] breaking changes migration guide` - -Cite sources in "## References" section at end of ADR/Design Doc with URLs. +Check current year with `date +%Y` and include in search queries (e.g., `[technology] [feature | vs comparison | breaking changes] {current_year}`). Cite sources in "## References" section at end of ADR/Design Doc with URLs. **Reverse-engineer mode**: Skip. Research is for forward design decisions. @@ -412,11 +420,7 @@ Cite sources in "## References" section at end of ADR/Design Doc with URLs. ### Update Mode: Dependency Inventory for Changed Sections [Required] -Before modifying the document, inventory the external definitions that the changed sections depend on: - -1. **Extract literal identifiers from update scope**: Collect all concrete identifiers (paths, endpoints, type names, config keys, component names) in the sections being updated -2. **Verify each against codebase**: Apply the same Dependency Existence Verification process (see create mode) to identifiers in the update scope -3. **Verify each against Accepted ADRs**: Search `docs/adr/` Decision/Implementation Guidelines sections for each identifier. Flag if the same identifier has a different value or definition. (Cross-document checks are handled in a subsequent pipeline step.) +For each literal identifier in the updated sections (paths, endpoints, type names, config keys, component names): (1) verify against codebase per Dependency Existence Verification; (2) search `docs/adr/` Decision / Implementation Guidelines for the identifier and flag identifier-value mismatches. **Output format** (per identifier): ```yaml @@ -426,29 +430,19 @@ Before modifying the document, inventory the external definitions that the chang action: "[none | address in update | flag for user]" ``` -**On conflict**: Log conflicting identifiers in the output. The orchestrator is responsible for presenting conflicts to the user - -## Reverse-Engineer Mode (As-Is Documentation) +Log conflicts in the output; the orchestrator presents conflicts to the user. -Mode for documenting existing architecture as-is. Used when creating Design Docs from existing implementation (e.g., in reverse-engineering workflows). +## Reverse-Engineer Mode -### What to Skip in Reverse-Engineer Mode -- ADR creation (no decisions to record — decisions were already made) -- Option comparison (no alternatives to evaluate) -- Change Impact Map (no changes being proposed) -- Field Propagation Map (no new fields being introduced) -- Implementation Approach Decision (no implementation strategy to select) -- Latest Information Research (documenting what exists, not designing something new) +When `operation_mode: reverse-engineer`: -### Reverse-Engineer Mode Execution Steps +**Skip**: ADR creation, Option comparison, Change Impact Map, Field Propagation Map, Implementation Approach Decision, Latest Information Research, Minimal Surface Alternatives. -1. **Read & Inventory**: Read every Primary File. Record public interfaces per file. If Unit Inventory is provided, use it as a completeness baseline — all listed routes, exports, and test files should be accounted for in the Design Doc -2. **Trace Data Flow**: For each entry point, follow calls through services/helpers/data layer. Read each. Record actual flow and error handling as implemented -3. **Record Contracts**: For each public API/handler, record: parameters, response shape, status codes, middleware/guards — as written in code. For external dependencies: record what is called and returned. Use exact identifiers from source -4. **Document Data Model**: Read schema/type definitions. Record: field names, types, nullable markers, defaults. For enums: list ALL values -5. **Identify Test Coverage**: Glob for test files. Record which interfaces have tests. Confirm test existence with Glob before reporting +**Execute**: +1. Read every Primary File; record public interfaces per file. If Unit Inventory is provided, treat it as completeness baseline (every listed route, export, test file accounted for). +2. For each entry point, trace calls through services/helpers/data layer; record actual flow and error handling as implemented. +3. For each public API/handler, record parameters, response shape, status codes, middleware/guards verbatim from code. For external dependencies: record what is called and returned, using exact identifiers. +4. Read schema/type definitions; record field names, types, nullable markers, defaults. For enums: list ALL values. +5. Glob for test files; record which interfaces have tests. Confirm test existence by Glob. -### Reverse-Engineer Mode Quality Standard -- Every claim cites file:line as evidence -- Identifiers transcribed exactly from code -- Test existence confirmed by Glob, not assumed +**Quality**: every claim cites `file:line`; identifiers transcribed exactly; test existence confirmed by Glob. diff --git a/dev-skills/.claude-plugin/plugin.json b/dev-skills/.claude-plugin/plugin.json index 0f76632..09b58bf 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.19.0", + "version": "0.19.1", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-skills/skills/coding-principles/SKILL.md b/dev-skills/skills/coding-principles/SKILL.md index 001ccdb..a1e95a9 100644 --- a/dev-skills/skills/coding-principles/SKILL.md +++ b/dev-skills/skills/coding-principles/SKILL.md @@ -9,8 +9,9 @@ description: Language-agnostic coding principles for maintainability, readabilit 1. **Maintainability over Speed**: Prioritize long-term code health over initial development velocity 2. **Simplicity First**: Choose the simplest solution that meets requirements (YAGNI principle) -3. **Explicit over Implicit**: Make intentions clear through code structure and naming -4. **Delete over Comment**: Remove unused code instead of commenting it out +3. **Minimum Surface for Required Coverage**: When introducing maintenance-surface-bearing elements (persistent state, public-contract or cross-boundary fields/props, behavioral modes/flags/variants, reusable abstractions, or component splits), select the smallest design surface that covers the current user-visible requirements and accepted technical constraints (audit, data integrity, compatibility, security, performance, accessibility). Adoption is justified by naming a current requirement or constraint that smaller alternatives fail to cover; value-based arguments serve as tiebreakers. Distinct from YAGNI (time-axis judgment of present vs. future need), this principle governs surface-area minimization at a fixed coverage point. +4. **Explicit over Implicit**: Make intentions clear through code structure and naming +5. **Delete over Comment**: Remove unused code instead of commenting it out ## Code Quality diff --git a/dev-skills/skills/documentation-criteria/references/design-template.md b/dev-skills/skills/documentation-criteria/references/design-template.md index a09c206..9bfeba4 100644 --- a/dev-skills/skills/documentation-criteria/references/design-template.md +++ b/dev-skills/skills/documentation-criteria/references/design-template.md @@ -111,7 +111,6 @@ Keywords determine test type and reduce ambiguity. ### [Functional Requirement 2] - [ ] The system shall display data list with pagination of 10 items per page -- [ ] **When** input is entered in search field, the system shall apply real-time filtering ## Existing Codebase Analysis @@ -180,13 +179,9 @@ No Ripple Effect: ### Main Components -#### Component 1 - -- **Responsibility**: [Scope of responsibility for this component] -- **Interface**: [APIs and contract definitions provided] -- **Dependencies**: [Relationships with other components] +Repeat the block below for each component. -#### Component 2 +#### Component 1 - **Responsibility**: [Scope of responsibility for this component] - **Interface**: [APIs and contract definitions provided] @@ -203,6 +198,38 @@ No Ripple Effect: **Decision**: [reuse / extend / new] — [rationale in 1-2 sentences] +### Minimal Surface Alternatives (When Introducing Maintenance-Surface Elements) + +One entry per new in-scope element. This section records the 5-step output produced by the invoking agent. + +#### Element 1: [name of the new element — e.g., persistent state field, public-contract field, cross-boundary prop, behavioral mode/variant, reusable abstraction or component split] + +**Step 1 — Fixed Requirements** +- [AC ID or constraint ID]: [requirement / constraint text] +- [AC ID or constraint ID]: [requirement / constraint text] + +**Steps 2–3 — Alternatives Compared** + +| Alternative | Current requirements covered (AC or constraint IDs) | New state introduced (count) | New concept / mode / flag (count) | Crosses component boundary (yes/no) | Breaking change or migration required (yes/no) | Subjective cost notes | +|---|---|---|---|---|---|---| +| [The added element as proposed] | | | | | | | +| [Subtractive alternative — derive / compute on demand / keep at caller / reuse existing / do not introduce new state] | | | | | | | +| [Optional third alternative] | | | | | | | + +**Step 4 — Selected Alternative and Rationale** +- **Selected**: [alternative name] +- **Rationale**: + - If selected = smallest alternative considered: state "smallest alternative considered; no further reduction available" + - If selected > smallest: name the current requirement(s) from step 1 that smaller alternatives fail to satisfy + +**Step 5 — Rejected Alternatives Log** +- [Alternative name]: [1-2 lines on what it was and why rejected] +- [Alternative name]: [1-2 lines on what it was and why rejected] + +(Repeat the Element block above for each additional in-scope element.) + +Mark the whole section as N/A with brief rationale when the design introduces no in-scope elements. + ### Contract Definitions ``` @@ -291,13 +318,12 @@ System Invariants: ### Technical Dependencies and Implementation Order #### Required Implementation Order -1. **[Component/Feature A]** - - Technical Reason: [Why this needs to be implemented first] - - Dependent Elements: [Other components that depend on this] -2. **[Component/Feature B]** - - Technical Reason: [Technical necessity to implement after A] - - Prerequisites: [Required pre-implementations] +Repeat the entry below for each component/feature, in dependency order. + +1. **[Component/Feature]** + - Technical Reason: [Why this needs to be implemented at this position] + - Prerequisites / Dependent Elements: [Components depended on or that depend on this] ### Migration Strategy @@ -366,9 +392,11 @@ Mark as N/A with brief rationale when the design introduces entirely new behavio ## Future Extensibility -- **Extension points**: [Interfaces, hooks, or plugin mechanisms designed for future use] -- **Known future requirements**: [Planned features that influenced current design decisions] -- **Intentional limitations**: [What was deliberately kept simple and why] +This section records what was **excluded** from the current design surface. Speculative inclusions belong in a separate proposal. + +- **Deferred possibilities**: [Capabilities considered during design and explicitly excluded from the current design surface. Each entry names either the current requirement it would have served, or marks itself as speculative] +- **Intentional limitations**: [What was deliberately kept small and why] +- **Extension points (existing, with current consumers)**: [Interfaces or hooks already in use by named current consumers. Each entry names a current consumer] ## Alternative Solutions diff --git a/dev-workflows-frontend/.claude-plugin/plugin.json b/dev-workflows-frontend/.claude-plugin/plugin.json index bbc6cf4..9c5842a 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.19.0", + "version": "0.19.1", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows-frontend/agents/code-reviewer.md b/dev-workflows-frontend/agents/code-reviewer.md index 684fdf4..423619c 100644 --- a/dev-workflows-frontend/agents/code-reviewer.md +++ b/dev-workflows-frontend/agents/code-reviewer.md @@ -293,6 +293,7 @@ Recommend higher-level review when: - Implementation significantly exceeds Design Doc quality - Security concerns discovered - Critical performance issues found +- Implementation introduces in-scope elements (persistent state; public-contract or cross-boundary fields/props; behavioral modes/flags/variants; reusable abstractions or component splits) that are absent from the Design Doc's Minimal Surface Alternatives section ## Special Considerations diff --git a/dev-workflows-frontend/agents/document-reviewer.md b/dev-workflows-frontend/agents/document-reviewer.md index c544a36..7e582c1 100644 --- a/dev-workflows-frontend/agents/document-reviewer.md +++ b/dev-workflows-frontend/agents/document-reviewer.md @@ -83,6 +83,7 @@ For DesignDoc, additionally verify: - [ ] Field propagation map present (when fields cross boundaries) - [ ] Verification Strategy section present with: correctness definition, verification method, verification timing, early verification point - [ ] Fact Disposition Table present and covers every `codebase_analysis.focusAreas` entry (when `codebase_analysis` is provided) +- [ ] Minimal Surface Alternatives section present with one entry per new in-scope element (persistent state / public-contract or cross-boundary field or prop / behavioral mode/flag/variant / reusable abstraction or component split) (when the design introduces any). Each entry contains the 5-step output (fixed requirements with AC IDs or accepted technical constraint IDs, alternatives table including at least one subtractive option, selected alternative with rationale, rejected alternatives log) #### Gate 1: Quality Assessment (only after Gate 0 passes) @@ -103,6 +104,14 @@ For DesignDoc, additionally verify: - **Verification Strategy quality check**: When Verification Strategy section exists, verify: (1) Correctness definition is specific and measurable — "tests pass" without specifying which tests or what they verify → `important` issue (category: `completeness`). (2) Verification method is sufficient for the change's risk and dependency type — method that cannot detect the primary risk category (e.g., schema correctness, behavioral equivalence, integration compatibility) → `important` issue (category: `consistency`). (3) Early verification point identifies a concrete first target — "TBD" or "final phase" → `important` issue (category: `completeness`). (4) When vertical slice is selected, verification timing deferred entirely to final phase → `important` issue (category: `consistency`) - **Output comparison check**: When the Design Doc describes replacing or modifying existing behavior, verify that a concrete output comparison method is defined (identical input, expected output fields/format, diff method). Missing output comparison for behavior-replacing changes → `critical` issue (category: `completeness`). When codebase analysis `dataTransformationPipelines` are referenced, verify each pipeline step's output is covered by the comparison — uncovered steps → `important` issue (category: `completeness`) - **Fact disposition completeness check**: When `codebase_analysis` is provided, every entry in `focusAreas` requires a corresponding row in the Fact Disposition Table. Missing rows → `critical` issue (category: `completeness`). `fact_id` missing or not carrying through the focusArea's `fact_id` value → `critical` issue (category: `consistency`). Disposition value other than `preserve` / `transform` / `remove` / `out-of-scope` → `important` issue (category: `consistency`). Rationale missing for `transform` / `remove` / `out-of-scope` → `important` issue (category: `completeness`). Evidence column not carrying through the focusArea's evidence value → `important` issue (category: `consistency`) +- **Minimal Surface Alternatives check**: + - *Scope trigger*: applies when the Design Doc introduces in-scope elements (persistent state; public-contract or cross-boundary fields or props; behavioral modes, flags, or variants; reusable abstractions or component splits). + - *Section existence*: when the trigger fires but the "Minimal Surface Alternatives" section is absent or empty → `critical` issue (category: `completeness`). + - *Per Element entry*: + - (1) Step 1 lists at least one AC ID or accepted technical constraint from the Design Doc → missing linkage or only speculative requirements ("future", "might want") → `critical` issue (category: `compliance`). + - (2) Steps 2–3 include at least one subtractive alternative (derive / compute on demand / keep at caller / reuse existing / do not introduce new state) → missing subtractive alternative → `critical` issue (category: `compliance`). + - (3) Step 4 rationale either selects the smallest alternative or names a current requirement smaller alternatives fail to satisfy → "useful" / "future-ready" / "convenient" / "users might want" used as primary rationale → `critical` issue (category: `compliance`). + - (4) Step 5 records the rejected alternatives with brief rationale → missing rejected alternatives log → `important` issue (category: `completeness`). **Perspective-specific Mode**: - Implement review based on specified mode and focus @@ -264,6 +273,7 @@ Include in output when `prior_context_count > 0`: - [ ] Verification Strategy aligns with design_type and implementation approach - [ ] Output comparison defined when design replaces/modifies existing behavior (covers all transformation pipeline steps) - [ ] Fact Disposition Table covers every `codebase_analysis.focusAreas` entry (when `codebase_analysis` is provided) +- [ ] Minimal Surface Alternatives section covers every new in-scope element (persistent state / public-contract or cross-boundary field or prop / behavioral mode/flag/variant / reusable abstraction or component split) with the 5-step output (when the design introduces any); selection rationale cites a named current requirement that smaller alternatives fail to satisfy, or names the smallest alternative as selected ## Review Criteria (for Comprehensive Mode) diff --git a/dev-workflows-frontend/agents/technical-designer-frontend.md b/dev-workflows-frontend/agents/technical-designer-frontend.md index 74bcebb..70ff261 100644 --- a/dev-workflows-frontend/agents/technical-designer-frontend.md +++ b/dev-workflows-frontend/agents/technical-designer-frontend.md @@ -39,6 +39,7 @@ The subsections below are not parallel mandates; they form four serial gates. Co **Gate 1 — Existing State Analysis** (depends on Gate 0): - Existing Code Investigation - Fact Disposition (when Codebase Analysis input is provided) +- Minimal Surface Alternatives (when introducing persistent client/server state, props or fields crossing component boundaries, behavioral modes/variants, or reusable component splits) **Gate 2 — Design Decisions** (depends on Gate 1): - Implementation Approach Decision @@ -117,6 +118,41 @@ For every entry in `Codebase Analysis.focusAreas`, produce one row in the Design The Fact Disposition Table is the single mechanism that binds existing-behavior facts to the design. Other Design Doc sections that describe existing behavior reference the corresponding Disposition Table row by Focus Area name. +### Minimal Surface Alternatives [Gate 1 — Required when introducing persistent client/server state, props or fields crossing component boundaries, behavioral modes/variants, or reusable component splits] + +Applies to each maintenance-surface-bearing element the design introduces. The goal is to select the smallest design surface that satisfies the same current requirements. Reference: coding-principles skill, "Minimum Surface for Required Coverage". + +**In scope**: persistent state (localStorage/sessionStorage/IndexedDB/cookies/server-saved fields — i.e., state that survives reload, navigation, or session, or is saved outside component memory); props or fields crossing component boundaries (props passed between components, Context values, lifted state); behavioral modes/variants (component variants, mode props, conditional rendering modes); reusable component splits (extracted sub-components, custom hooks, or utilities intended for reuse by multiple parents). + +**Out of scope**: local `useState` / `useReducer` confined to a single component's internal logic (does not survive reload); private hooks used by one component; test fixture or mock props; transient render-only state; internal helper functions without external observers. + +**Precedence**: when an element matches both an in-scope and an out-of-scope condition (e.g., a prop that is both "passed to one child component" and "lifted to Context"), the in-scope classification wins and the gate applies. + +Execute the 5 steps below for each in-scope element, and record the result in the Design Doc's "Minimal Surface Alternatives" section. + +1. **Fix Requirements** + - List the current user-visible requirements / ACs / accepted technical constraints (audit, accessibility, performance, security, compatibility) this element would serve, citing AC IDs or constraint IDs from the Design Doc or referenced UI Spec. + - Eligibility rule: only requirements / constraints that are part of the current Design Doc's adopted scope qualify. Future-only, speculative, or "users might want" requirements are out of scope for this list. + +2. **Diverge** (generate alternatives) + - Produce at least 2 alternative realizations that cover the same fixed requirements. + - At least one alternative must be subtractive. Subtractive alternatives are drawn from: derive from existing props/state, lift state to existing parent, reuse existing component or variant, keep at caller / URL / server response, do not introduce a new mode. + +3. **Compare** (record alternatives in a table) + + | Alternative | Current requirements covered (AC or constraint IDs) | New persistent state (client or server, count) | New props / modes / variants (count) | Crosses component boundary (yes/no) | Breaking change or migration required (yes/no) | Subjective cost notes | + |---|---|---|---|---|---|---| + + Resolution priority (later columns are tiebreakers when earlier are equal): (1) new persistent state (lower=smaller); (2) crosses component boundary (no=smaller); (3) new props/modes/variants (lower=smaller); (4) breaking change or migration (no=smaller); (5) subjective cost notes. + +4. **Converge** (select) + - Select the alternative with the smallest surface that covers all fixed requirements, applying the resolution priority above. + - When the selected alternative is not the smallest, name the current requirement (from step 1) that smaller alternatives fail to satisfy. + - "Reusable" / "future-ready" / "convenient for implementation" / "users might want" belong in the Subjective cost notes column (tiebreakers only). + +5. **Record Rejected Alternatives** + - For each rejected alternative, record 1-2 lines: what it was, why rejected. Include in the Design Doc to prevent re-proposal in subsequent iterations or by future agents. + ### Implementation Approach Decision [Gate 2 — Required] Must be performed when creating Design Doc: @@ -262,27 +298,11 @@ Execute file output immediately (considered approved at execution). ## Important Design Principles -1. **Consistency First Priority**: Follow existing React component patterns, document clear reasons when introducing new patterns -2. **Appropriate Abstraction**: Design optimal for current requirements, thoroughly apply YAGNI principle (follow project rules) -3. **Testability**: Props-driven design and mockable custom hooks -4. **Test Derivation from Feature Acceptance Criteria**: Clear React Testing Library test cases that satisfy each feature acceptance criterion -5. **Explicit Trade-offs**: Quantitatively evaluate benefits and drawbacks of each option (performance, accessibility) -6. **Active Use of Latest Information**: - - Always research latest React best practices, libraries, and approaches with WebSearch before design - - Cite information sources in "References" section with URLs - - Especially confirm multiple reliable sources when introducing new technologies +Apply principles from loaded skills (`typescript-rules`, `frontend-ai-guide`, `testing-principles`). Trade-off evaluation (Gate 2 + ADR Checklist), existing-pattern consistency (Gate 1 Existing Code Investigation + Fact Disposition), and Verification Strategy from AC (Gate 2) are enforced above; test derivation itself is a downstream agent responsibility. Latest-information research is governed by the "Latest Information Research" section below. ## Implementation Sample Standards Compliance -Implementation samples in ADR and Design Docs follow the standards loaded from the `typescript-rules` and `frontend-ai-guide` skills: - -- Function components with explicit Props type definitions -- Custom hooks for logic reuse and testability -- Type safety: `unknown` + type guards for external responses -- Error handling: error boundaries and error state management -- Secrets remain server-side - -When sample code is needed, keep it minimal and follow concrete patterns from those skills. +All implementation samples in ADR and Design Docs MUST follow the loaded `typescript-rules` and `frontend-ai-guide` skills. Omit samples unless they clarify contracts or edge cases that prose cannot convey. ## Diagram Creation (using mermaid notation) @@ -311,7 +331,6 @@ These items test the final document output. Process gates (Gate 0-3) are enforce - [ ] Props type contracts are explicit for every integration point - [ ] Component hierarchy and data flow appear as diagrams - [ ] External Resources Used subsection lists feature-tier identifiers (when external resources apply) -- [ ] Fact Disposition Table covers every Codebase Analysis focusArea, each row with fact_id + disposition + rationale + evidence (when Codebase Analysis input was provided) **Create/update mode only**: - [ ] Prerequisite common ADRs are referenced @@ -359,13 +378,7 @@ These items test the final document output. Process gates (Gate 0-3) are enforce **When** (create/update mode): New library/framework introduction, performance optimization, accessibility design, major version upgrades. -Check current year with `date +%Y` and include in search queries: -- `[library] best practices {current_year}` -- `[lib A] vs [lib B] comparison {current_year}` -- `[framework] breaking changes migration guide` -- `[framework] accessibility best practices` - -Cite sources in "## References" section at end of ADR/Design Doc with URLs. +Check current year with `date +%Y` and include in search queries (e.g., `[library | framework] [best practices | vs comparison | breaking changes | accessibility] {current_year}`). Cite sources in "## References" section at end of ADR/Design Doc with URLs. **Reverse-engineer mode**: Skip. Research is for forward design decisions. @@ -391,22 +404,17 @@ Before modifying the document, inventory the external definitions that the chang **On conflict**: Log conflicting identifiers in the output. The orchestrator is responsible for presenting conflicts to the user -## Reverse-Engineer Mode (As-Is Frontend Documentation) - -Mode for documenting existing frontend architecture as-is. Used when creating Design Docs from existing implementation. +## Reverse-Engineer Mode -### What to Skip in Reverse-Engineer Mode -- ADR creation, option comparison, change impact analysis, latest information research, implementation approach decision +When `operation_mode: reverse-engineer`: -### Reverse-Engineer Mode Execution Steps +**Skip**: ADR creation, option comparison, change impact analysis, Latest Information Research, Implementation Approach Decision, Minimal Surface Alternatives. -1. **Read & Inventory**: Read every Primary File. Record component hierarchy, exported components, hooks, utilities. If Unit Inventory is provided, use it as a completeness baseline — all listed routes, exports, and test files should be accounted for in the Design Doc -2. **Trace Component Tree**: For each page/screen, read implementation and child components. Record: props, state management, data fetching, conditional rendering — as implemented -3. **Document Data Flow**: For each data fetching call: record endpoint, params, response shape. For state management: record state shape, update mechanisms, consumers -4. **Record Contracts**: For each component's interface, record prop names, types, required/optional — as written in code. Use exact identifiers from source -5. **Identify Test Coverage**: Glob for test files. Record which components have tests. Confirm test existence with Glob before reporting +**Execute**: +1. Read every Primary File; record component hierarchy, exported components, hooks, utilities. If Unit Inventory is provided, treat it as completeness baseline (every listed route, export, test file accounted for). +2. For each page/screen, read implementation and child components; record props, state management, data fetching, conditional rendering as implemented. +3. For each data-fetching call: record endpoint, params, response shape. For state management: record state shape, update mechanisms, consumers. +4. For each component's interface, record prop names, types, required/optional verbatim from code, using exact identifiers. +5. Glob for test files; record which components have tests. Confirm test existence by Glob. -### Reverse-Engineer Mode Quality Standard -- Every claim cites file:line as evidence -- Identifiers transcribed exactly from code -- Test existence confirmed by Glob, not assumed +**Quality**: every claim cites `file:line`; identifiers transcribed exactly; test existence confirmed by Glob. diff --git a/dev-workflows-frontend/skills/coding-principles/SKILL.md b/dev-workflows-frontend/skills/coding-principles/SKILL.md index 001ccdb..a1e95a9 100644 --- a/dev-workflows-frontend/skills/coding-principles/SKILL.md +++ b/dev-workflows-frontend/skills/coding-principles/SKILL.md @@ -9,8 +9,9 @@ description: Language-agnostic coding principles for maintainability, readabilit 1. **Maintainability over Speed**: Prioritize long-term code health over initial development velocity 2. **Simplicity First**: Choose the simplest solution that meets requirements (YAGNI principle) -3. **Explicit over Implicit**: Make intentions clear through code structure and naming -4. **Delete over Comment**: Remove unused code instead of commenting it out +3. **Minimum Surface for Required Coverage**: When introducing maintenance-surface-bearing elements (persistent state, public-contract or cross-boundary fields/props, behavioral modes/flags/variants, reusable abstractions, or component splits), select the smallest design surface that covers the current user-visible requirements and accepted technical constraints (audit, data integrity, compatibility, security, performance, accessibility). Adoption is justified by naming a current requirement or constraint that smaller alternatives fail to cover; value-based arguments serve as tiebreakers. Distinct from YAGNI (time-axis judgment of present vs. future need), this principle governs surface-area minimization at a fixed coverage point. +4. **Explicit over Implicit**: Make intentions clear through code structure and naming +5. **Delete over Comment**: Remove unused code instead of commenting it out ## Code Quality diff --git a/dev-workflows-frontend/skills/documentation-criteria/references/design-template.md b/dev-workflows-frontend/skills/documentation-criteria/references/design-template.md index a09c206..9bfeba4 100644 --- a/dev-workflows-frontend/skills/documentation-criteria/references/design-template.md +++ b/dev-workflows-frontend/skills/documentation-criteria/references/design-template.md @@ -111,7 +111,6 @@ Keywords determine test type and reduce ambiguity. ### [Functional Requirement 2] - [ ] The system shall display data list with pagination of 10 items per page -- [ ] **When** input is entered in search field, the system shall apply real-time filtering ## Existing Codebase Analysis @@ -180,13 +179,9 @@ No Ripple Effect: ### Main Components -#### Component 1 - -- **Responsibility**: [Scope of responsibility for this component] -- **Interface**: [APIs and contract definitions provided] -- **Dependencies**: [Relationships with other components] +Repeat the block below for each component. -#### Component 2 +#### Component 1 - **Responsibility**: [Scope of responsibility for this component] - **Interface**: [APIs and contract definitions provided] @@ -203,6 +198,38 @@ No Ripple Effect: **Decision**: [reuse / extend / new] — [rationale in 1-2 sentences] +### Minimal Surface Alternatives (When Introducing Maintenance-Surface Elements) + +One entry per new in-scope element. This section records the 5-step output produced by the invoking agent. + +#### Element 1: [name of the new element — e.g., persistent state field, public-contract field, cross-boundary prop, behavioral mode/variant, reusable abstraction or component split] + +**Step 1 — Fixed Requirements** +- [AC ID or constraint ID]: [requirement / constraint text] +- [AC ID or constraint ID]: [requirement / constraint text] + +**Steps 2–3 — Alternatives Compared** + +| Alternative | Current requirements covered (AC or constraint IDs) | New state introduced (count) | New concept / mode / flag (count) | Crosses component boundary (yes/no) | Breaking change or migration required (yes/no) | Subjective cost notes | +|---|---|---|---|---|---|---| +| [The added element as proposed] | | | | | | | +| [Subtractive alternative — derive / compute on demand / keep at caller / reuse existing / do not introduce new state] | | | | | | | +| [Optional third alternative] | | | | | | | + +**Step 4 — Selected Alternative and Rationale** +- **Selected**: [alternative name] +- **Rationale**: + - If selected = smallest alternative considered: state "smallest alternative considered; no further reduction available" + - If selected > smallest: name the current requirement(s) from step 1 that smaller alternatives fail to satisfy + +**Step 5 — Rejected Alternatives Log** +- [Alternative name]: [1-2 lines on what it was and why rejected] +- [Alternative name]: [1-2 lines on what it was and why rejected] + +(Repeat the Element block above for each additional in-scope element.) + +Mark the whole section as N/A with brief rationale when the design introduces no in-scope elements. + ### Contract Definitions ``` @@ -291,13 +318,12 @@ System Invariants: ### Technical Dependencies and Implementation Order #### Required Implementation Order -1. **[Component/Feature A]** - - Technical Reason: [Why this needs to be implemented first] - - Dependent Elements: [Other components that depend on this] -2. **[Component/Feature B]** - - Technical Reason: [Technical necessity to implement after A] - - Prerequisites: [Required pre-implementations] +Repeat the entry below for each component/feature, in dependency order. + +1. **[Component/Feature]** + - Technical Reason: [Why this needs to be implemented at this position] + - Prerequisites / Dependent Elements: [Components depended on or that depend on this] ### Migration Strategy @@ -366,9 +392,11 @@ Mark as N/A with brief rationale when the design introduces entirely new behavio ## Future Extensibility -- **Extension points**: [Interfaces, hooks, or plugin mechanisms designed for future use] -- **Known future requirements**: [Planned features that influenced current design decisions] -- **Intentional limitations**: [What was deliberately kept simple and why] +This section records what was **excluded** from the current design surface. Speculative inclusions belong in a separate proposal. + +- **Deferred possibilities**: [Capabilities considered during design and explicitly excluded from the current design surface. Each entry names either the current requirement it would have served, or marks itself as speculative] +- **Intentional limitations**: [What was deliberately kept small and why] +- **Extension points (existing, with current consumers)**: [Interfaces or hooks already in use by named current consumers. Each entry names a current consumer] ## Alternative Solutions diff --git a/dev-workflows-fullstack/.claude-plugin/plugin.json b/dev-workflows-fullstack/.claude-plugin/plugin.json index 8487841..8c36322 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.19.0", + "version": "0.19.1", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows-fullstack/agents/code-reviewer.md b/dev-workflows-fullstack/agents/code-reviewer.md index 684fdf4..423619c 100644 --- a/dev-workflows-fullstack/agents/code-reviewer.md +++ b/dev-workflows-fullstack/agents/code-reviewer.md @@ -293,6 +293,7 @@ Recommend higher-level review when: - Implementation significantly exceeds Design Doc quality - Security concerns discovered - Critical performance issues found +- Implementation introduces in-scope elements (persistent state; public-contract or cross-boundary fields/props; behavioral modes/flags/variants; reusable abstractions or component splits) that are absent from the Design Doc's Minimal Surface Alternatives section ## Special Considerations diff --git a/dev-workflows-fullstack/agents/document-reviewer.md b/dev-workflows-fullstack/agents/document-reviewer.md index c544a36..7e582c1 100644 --- a/dev-workflows-fullstack/agents/document-reviewer.md +++ b/dev-workflows-fullstack/agents/document-reviewer.md @@ -83,6 +83,7 @@ For DesignDoc, additionally verify: - [ ] Field propagation map present (when fields cross boundaries) - [ ] Verification Strategy section present with: correctness definition, verification method, verification timing, early verification point - [ ] Fact Disposition Table present and covers every `codebase_analysis.focusAreas` entry (when `codebase_analysis` is provided) +- [ ] Minimal Surface Alternatives section present with one entry per new in-scope element (persistent state / public-contract or cross-boundary field or prop / behavioral mode/flag/variant / reusable abstraction or component split) (when the design introduces any). Each entry contains the 5-step output (fixed requirements with AC IDs or accepted technical constraint IDs, alternatives table including at least one subtractive option, selected alternative with rationale, rejected alternatives log) #### Gate 1: Quality Assessment (only after Gate 0 passes) @@ -103,6 +104,14 @@ For DesignDoc, additionally verify: - **Verification Strategy quality check**: When Verification Strategy section exists, verify: (1) Correctness definition is specific and measurable — "tests pass" without specifying which tests or what they verify → `important` issue (category: `completeness`). (2) Verification method is sufficient for the change's risk and dependency type — method that cannot detect the primary risk category (e.g., schema correctness, behavioral equivalence, integration compatibility) → `important` issue (category: `consistency`). (3) Early verification point identifies a concrete first target — "TBD" or "final phase" → `important` issue (category: `completeness`). (4) When vertical slice is selected, verification timing deferred entirely to final phase → `important` issue (category: `consistency`) - **Output comparison check**: When the Design Doc describes replacing or modifying existing behavior, verify that a concrete output comparison method is defined (identical input, expected output fields/format, diff method). Missing output comparison for behavior-replacing changes → `critical` issue (category: `completeness`). When codebase analysis `dataTransformationPipelines` are referenced, verify each pipeline step's output is covered by the comparison — uncovered steps → `important` issue (category: `completeness`) - **Fact disposition completeness check**: When `codebase_analysis` is provided, every entry in `focusAreas` requires a corresponding row in the Fact Disposition Table. Missing rows → `critical` issue (category: `completeness`). `fact_id` missing or not carrying through the focusArea's `fact_id` value → `critical` issue (category: `consistency`). Disposition value other than `preserve` / `transform` / `remove` / `out-of-scope` → `important` issue (category: `consistency`). Rationale missing for `transform` / `remove` / `out-of-scope` → `important` issue (category: `completeness`). Evidence column not carrying through the focusArea's evidence value → `important` issue (category: `consistency`) +- **Minimal Surface Alternatives check**: + - *Scope trigger*: applies when the Design Doc introduces in-scope elements (persistent state; public-contract or cross-boundary fields or props; behavioral modes, flags, or variants; reusable abstractions or component splits). + - *Section existence*: when the trigger fires but the "Minimal Surface Alternatives" section is absent or empty → `critical` issue (category: `completeness`). + - *Per Element entry*: + - (1) Step 1 lists at least one AC ID or accepted technical constraint from the Design Doc → missing linkage or only speculative requirements ("future", "might want") → `critical` issue (category: `compliance`). + - (2) Steps 2–3 include at least one subtractive alternative (derive / compute on demand / keep at caller / reuse existing / do not introduce new state) → missing subtractive alternative → `critical` issue (category: `compliance`). + - (3) Step 4 rationale either selects the smallest alternative or names a current requirement smaller alternatives fail to satisfy → "useful" / "future-ready" / "convenient" / "users might want" used as primary rationale → `critical` issue (category: `compliance`). + - (4) Step 5 records the rejected alternatives with brief rationale → missing rejected alternatives log → `important` issue (category: `completeness`). **Perspective-specific Mode**: - Implement review based on specified mode and focus @@ -264,6 +273,7 @@ Include in output when `prior_context_count > 0`: - [ ] Verification Strategy aligns with design_type and implementation approach - [ ] Output comparison defined when design replaces/modifies existing behavior (covers all transformation pipeline steps) - [ ] Fact Disposition Table covers every `codebase_analysis.focusAreas` entry (when `codebase_analysis` is provided) +- [ ] Minimal Surface Alternatives section covers every new in-scope element (persistent state / public-contract or cross-boundary field or prop / behavioral mode/flag/variant / reusable abstraction or component split) with the 5-step output (when the design introduces any); selection rationale cites a named current requirement that smaller alternatives fail to satisfy, or names the smallest alternative as selected ## Review Criteria (for Comprehensive Mode) diff --git a/dev-workflows-fullstack/agents/technical-designer-frontend.md b/dev-workflows-fullstack/agents/technical-designer-frontend.md index 74bcebb..70ff261 100644 --- a/dev-workflows-fullstack/agents/technical-designer-frontend.md +++ b/dev-workflows-fullstack/agents/technical-designer-frontend.md @@ -39,6 +39,7 @@ The subsections below are not parallel mandates; they form four serial gates. Co **Gate 1 — Existing State Analysis** (depends on Gate 0): - Existing Code Investigation - Fact Disposition (when Codebase Analysis input is provided) +- Minimal Surface Alternatives (when introducing persistent client/server state, props or fields crossing component boundaries, behavioral modes/variants, or reusable component splits) **Gate 2 — Design Decisions** (depends on Gate 1): - Implementation Approach Decision @@ -117,6 +118,41 @@ For every entry in `Codebase Analysis.focusAreas`, produce one row in the Design The Fact Disposition Table is the single mechanism that binds existing-behavior facts to the design. Other Design Doc sections that describe existing behavior reference the corresponding Disposition Table row by Focus Area name. +### Minimal Surface Alternatives [Gate 1 — Required when introducing persistent client/server state, props or fields crossing component boundaries, behavioral modes/variants, or reusable component splits] + +Applies to each maintenance-surface-bearing element the design introduces. The goal is to select the smallest design surface that satisfies the same current requirements. Reference: coding-principles skill, "Minimum Surface for Required Coverage". + +**In scope**: persistent state (localStorage/sessionStorage/IndexedDB/cookies/server-saved fields — i.e., state that survives reload, navigation, or session, or is saved outside component memory); props or fields crossing component boundaries (props passed between components, Context values, lifted state); behavioral modes/variants (component variants, mode props, conditional rendering modes); reusable component splits (extracted sub-components, custom hooks, or utilities intended for reuse by multiple parents). + +**Out of scope**: local `useState` / `useReducer` confined to a single component's internal logic (does not survive reload); private hooks used by one component; test fixture or mock props; transient render-only state; internal helper functions without external observers. + +**Precedence**: when an element matches both an in-scope and an out-of-scope condition (e.g., a prop that is both "passed to one child component" and "lifted to Context"), the in-scope classification wins and the gate applies. + +Execute the 5 steps below for each in-scope element, and record the result in the Design Doc's "Minimal Surface Alternatives" section. + +1. **Fix Requirements** + - List the current user-visible requirements / ACs / accepted technical constraints (audit, accessibility, performance, security, compatibility) this element would serve, citing AC IDs or constraint IDs from the Design Doc or referenced UI Spec. + - Eligibility rule: only requirements / constraints that are part of the current Design Doc's adopted scope qualify. Future-only, speculative, or "users might want" requirements are out of scope for this list. + +2. **Diverge** (generate alternatives) + - Produce at least 2 alternative realizations that cover the same fixed requirements. + - At least one alternative must be subtractive. Subtractive alternatives are drawn from: derive from existing props/state, lift state to existing parent, reuse existing component or variant, keep at caller / URL / server response, do not introduce a new mode. + +3. **Compare** (record alternatives in a table) + + | Alternative | Current requirements covered (AC or constraint IDs) | New persistent state (client or server, count) | New props / modes / variants (count) | Crosses component boundary (yes/no) | Breaking change or migration required (yes/no) | Subjective cost notes | + |---|---|---|---|---|---|---| + + Resolution priority (later columns are tiebreakers when earlier are equal): (1) new persistent state (lower=smaller); (2) crosses component boundary (no=smaller); (3) new props/modes/variants (lower=smaller); (4) breaking change or migration (no=smaller); (5) subjective cost notes. + +4. **Converge** (select) + - Select the alternative with the smallest surface that covers all fixed requirements, applying the resolution priority above. + - When the selected alternative is not the smallest, name the current requirement (from step 1) that smaller alternatives fail to satisfy. + - "Reusable" / "future-ready" / "convenient for implementation" / "users might want" belong in the Subjective cost notes column (tiebreakers only). + +5. **Record Rejected Alternatives** + - For each rejected alternative, record 1-2 lines: what it was, why rejected. Include in the Design Doc to prevent re-proposal in subsequent iterations or by future agents. + ### Implementation Approach Decision [Gate 2 — Required] Must be performed when creating Design Doc: @@ -262,27 +298,11 @@ Execute file output immediately (considered approved at execution). ## Important Design Principles -1. **Consistency First Priority**: Follow existing React component patterns, document clear reasons when introducing new patterns -2. **Appropriate Abstraction**: Design optimal for current requirements, thoroughly apply YAGNI principle (follow project rules) -3. **Testability**: Props-driven design and mockable custom hooks -4. **Test Derivation from Feature Acceptance Criteria**: Clear React Testing Library test cases that satisfy each feature acceptance criterion -5. **Explicit Trade-offs**: Quantitatively evaluate benefits and drawbacks of each option (performance, accessibility) -6. **Active Use of Latest Information**: - - Always research latest React best practices, libraries, and approaches with WebSearch before design - - Cite information sources in "References" section with URLs - - Especially confirm multiple reliable sources when introducing new technologies +Apply principles from loaded skills (`typescript-rules`, `frontend-ai-guide`, `testing-principles`). Trade-off evaluation (Gate 2 + ADR Checklist), existing-pattern consistency (Gate 1 Existing Code Investigation + Fact Disposition), and Verification Strategy from AC (Gate 2) are enforced above; test derivation itself is a downstream agent responsibility. Latest-information research is governed by the "Latest Information Research" section below. ## Implementation Sample Standards Compliance -Implementation samples in ADR and Design Docs follow the standards loaded from the `typescript-rules` and `frontend-ai-guide` skills: - -- Function components with explicit Props type definitions -- Custom hooks for logic reuse and testability -- Type safety: `unknown` + type guards for external responses -- Error handling: error boundaries and error state management -- Secrets remain server-side - -When sample code is needed, keep it minimal and follow concrete patterns from those skills. +All implementation samples in ADR and Design Docs MUST follow the loaded `typescript-rules` and `frontend-ai-guide` skills. Omit samples unless they clarify contracts or edge cases that prose cannot convey. ## Diagram Creation (using mermaid notation) @@ -311,7 +331,6 @@ These items test the final document output. Process gates (Gate 0-3) are enforce - [ ] Props type contracts are explicit for every integration point - [ ] Component hierarchy and data flow appear as diagrams - [ ] External Resources Used subsection lists feature-tier identifiers (when external resources apply) -- [ ] Fact Disposition Table covers every Codebase Analysis focusArea, each row with fact_id + disposition + rationale + evidence (when Codebase Analysis input was provided) **Create/update mode only**: - [ ] Prerequisite common ADRs are referenced @@ -359,13 +378,7 @@ These items test the final document output. Process gates (Gate 0-3) are enforce **When** (create/update mode): New library/framework introduction, performance optimization, accessibility design, major version upgrades. -Check current year with `date +%Y` and include in search queries: -- `[library] best practices {current_year}` -- `[lib A] vs [lib B] comparison {current_year}` -- `[framework] breaking changes migration guide` -- `[framework] accessibility best practices` - -Cite sources in "## References" section at end of ADR/Design Doc with URLs. +Check current year with `date +%Y` and include in search queries (e.g., `[library | framework] [best practices | vs comparison | breaking changes | accessibility] {current_year}`). Cite sources in "## References" section at end of ADR/Design Doc with URLs. **Reverse-engineer mode**: Skip. Research is for forward design decisions. @@ -391,22 +404,17 @@ Before modifying the document, inventory the external definitions that the chang **On conflict**: Log conflicting identifiers in the output. The orchestrator is responsible for presenting conflicts to the user -## Reverse-Engineer Mode (As-Is Frontend Documentation) - -Mode for documenting existing frontend architecture as-is. Used when creating Design Docs from existing implementation. +## Reverse-Engineer Mode -### What to Skip in Reverse-Engineer Mode -- ADR creation, option comparison, change impact analysis, latest information research, implementation approach decision +When `operation_mode: reverse-engineer`: -### Reverse-Engineer Mode Execution Steps +**Skip**: ADR creation, option comparison, change impact analysis, Latest Information Research, Implementation Approach Decision, Minimal Surface Alternatives. -1. **Read & Inventory**: Read every Primary File. Record component hierarchy, exported components, hooks, utilities. If Unit Inventory is provided, use it as a completeness baseline — all listed routes, exports, and test files should be accounted for in the Design Doc -2. **Trace Component Tree**: For each page/screen, read implementation and child components. Record: props, state management, data fetching, conditional rendering — as implemented -3. **Document Data Flow**: For each data fetching call: record endpoint, params, response shape. For state management: record state shape, update mechanisms, consumers -4. **Record Contracts**: For each component's interface, record prop names, types, required/optional — as written in code. Use exact identifiers from source -5. **Identify Test Coverage**: Glob for test files. Record which components have tests. Confirm test existence with Glob before reporting +**Execute**: +1. Read every Primary File; record component hierarchy, exported components, hooks, utilities. If Unit Inventory is provided, treat it as completeness baseline (every listed route, export, test file accounted for). +2. For each page/screen, read implementation and child components; record props, state management, data fetching, conditional rendering as implemented. +3. For each data-fetching call: record endpoint, params, response shape. For state management: record state shape, update mechanisms, consumers. +4. For each component's interface, record prop names, types, required/optional verbatim from code, using exact identifiers. +5. Glob for test files; record which components have tests. Confirm test existence by Glob. -### Reverse-Engineer Mode Quality Standard -- Every claim cites file:line as evidence -- Identifiers transcribed exactly from code -- Test existence confirmed by Glob, not assumed +**Quality**: every claim cites `file:line`; identifiers transcribed exactly; test existence confirmed by Glob. diff --git a/dev-workflows-fullstack/agents/technical-designer.md b/dev-workflows-fullstack/agents/technical-designer.md index 395f567..67c3ab2 100644 --- a/dev-workflows-fullstack/agents/technical-designer.md +++ b/dev-workflows-fullstack/agents/technical-designer.md @@ -41,6 +41,7 @@ The subsections below are not parallel mandates; they form four serial gates. Co - Existing Code Investigation - Fact Disposition (when Codebase Analysis input is provided) - Data Representation Decision (when new or modified data structures are introduced) +- Minimal Surface Alternatives (when introducing persistent state, public-contract or cross-boundary fields, behavioral modes/flags, or reusable abstractions) **Gate 2 — Design Decisions** (depends on Gate 1): - Implementation Approach Decision @@ -159,6 +160,41 @@ When the design introduces or significantly modifies data structures: - 3+ criteria fail → New structure justified - Record decision and rationale in Design Doc +### Minimal Surface Alternatives [Gate 1 — Required when introducing persistent state, public-contract or cross-boundary fields, behavioral modes/flags, or reusable abstractions] + +Applies to each maintenance-surface-bearing element the design introduces. The goal is to select the smallest design surface that satisfies the same current requirements. Reference: coding-principles skill, "Minimum Surface for Required Coverage". + +**In scope**: persistent state (DB columns/tables, file fields, cache entries, queue payloads, session/cookie data, any state outliving a single operation); public-contract elements (exported types, API request/response fields, exported function signatures, schema definitions); cross-boundary fields (passed between modules/services/components); behavioral modes/flags (state-machine states, feature flags, config options); reusable abstractions (new types/classes/modules/interfaces intended for reuse). + +**Out of scope**: local variables within a single function; internal struct fields used only within one module/package; test fixture or mock fields; transient state confined to a single operation; private state without external observers. + +**Precedence**: when an element matches both an in-scope and an out-of-scope condition (e.g., a struct field that is both "internal to one module" and "persisted to a DB column"), the in-scope classification wins and the gate applies. + +Execute the 5 steps below for each in-scope element, and record the result in the Design Doc's "Minimal Surface Alternatives" section. + +1. **Fix Requirements** + - List the current user-visible requirements / ACs / accepted technical constraints (audit, data integrity, compatibility, security, performance) this element would serve, citing AC IDs or constraint IDs from the Design Doc. + - Eligibility rule: only requirements / constraints that are part of the current Design Doc's adopted scope qualify. Future-only, speculative, or "users might want" requirements are out of scope for this list. + +2. **Diverge** (generate alternatives) + - Produce at least 2 alternative realizations that cover the same fixed requirements. + - At least one alternative must be subtractive. Subtractive alternatives are drawn from: derive from existing data, compute on demand, keep at caller / invocation boundary, reuse existing structure, do not introduce new state. + +3. **Compare** (record alternatives in a table) + + | Alternative | Current requirements covered (AC or constraint IDs) | New persistent state (count) | New concept / mode / flag (count) | Crosses component boundary (yes/no) | Breaking change or migration required (yes/no) | Subjective cost notes | + |---|---|---|---|---|---|---| + + Resolution priority (later columns are tiebreakers when earlier are equal): (1) new persistent state (lower=smaller); (2) crosses component boundary (no=smaller); (3) new concept/mode/flag (lower=smaller); (4) breaking change or migration (no=smaller); (5) subjective cost notes. + +4. **Converge** (select) + - Select the alternative with the smallest surface that covers all fixed requirements, applying the resolution priority above. + - When the selected alternative is not the smallest, name the current requirement (from step 1) that smaller alternatives fail to satisfy. + - "Useful" / "future-ready" / "convenient for implementation" / "users might want" belong in the Subjective cost notes column (tiebreakers only). + +5. **Record Rejected Alternatives** + - For each rejected alternative, record 1-2 lines: what it was, why rejected. Include in the Design Doc to prevent re-proposal in subsequent iterations or by future agents. + ### Implementation Approach Decision [Gate 2 — Required] Must be performed when creating Design Doc: @@ -299,24 +335,11 @@ Execute file output immediately (considered approved at execution). ## Important Design Principles -1. **Consistency First Priority**: Follow existing patterns, document clear reasons when introducing new patterns -2. **Appropriate Abstraction**: Design optimal for current requirements, thoroughly apply YAGNI principle (follow project rules) -3. **Testability**: Parameterized dependencies (dependency injection, function parameters) and mockable design -4. **Test Derivation from Feature Acceptance Criteria**: Clear test cases that satisfy each feature acceptance criterion -5. **Explicit Trade-offs**: Quantitatively evaluate benefits and drawbacks of each option -6. **Active Use of Latest Information**: - - Always research latest best practices, libraries, and approaches with WebSearch before design - - Cite information sources in "References" section with URLs - - Especially confirm multiple reliable sources when introducing new technologies +Apply principles from loaded skills (`coding-principles`, `testing-principles`, `ai-development-guide`). Trade-off evaluation (Gate 2 + ADR Checklist), existing-pattern consistency (Gate 1 Existing Code Investigation + Fact Disposition), and Verification Strategy from AC (Gate 2) are enforced above; test derivation itself is a downstream agent responsibility. Latest-information research is governed by the "Latest Information Research" section below. ## Implementation Sample Standards Compliance -**MANDATORY**: All implementation samples in ADR and Design Docs MUST strictly comply with project coding standards. - -Implementation sample creation checklist: -- Follow language-appropriate correctness guarantee patterns -- Apply appropriate design patterns for the language -- Implement robust error handling strategies +All implementation samples in ADR and Design Docs MUST follow the loaded `coding-principles` and `testing-principles` skills. Omit samples unless they clarify contracts or edge cases that prose cannot convey. ## Diagram Creation (using mermaid notation) @@ -340,7 +363,6 @@ These items test the final document output. Process gates (Gate 0-3) are enforce - [ ] Architecture and data flow appear as diagrams - [ ] External Resources Used subsection lists feature-tier identifiers (when external resources apply) - [ ] Quality Assurance Mechanisms list adopted/noted status for checks covering this change -- [ ] Fact Disposition Table covers every Codebase Analysis focusArea, each row with fact_id + disposition + rationale + evidence (when Codebase Analysis input was provided) **Create/update mode only**: - [ ] Prerequisite common ADRs are referenced @@ -350,10 +372,7 @@ These items test the final document output. Process gates (Gate 0-3) are enforce - [ ] Interface change matrix is complete - [ ] Implementation approach selection (vertical/horizontal/hybrid) carries rationale - [ ] `complexity_level` is set; when medium/high, `complexity_rationale` covers (1) requirements/ACs, (2) constraints/risks -- [ ] Data representation decision is documented when new structures are introduced -- [ ] Field propagation map is included when fields cross boundaries - [ ] Verification Strategy defines correctness, method, timing, and early verification point -- [ ] Output comparison defines input, expected output fields, and diff method when behavior is replaced or modified (covers every transformation pipeline step from codebase analysis) **Reverse-engineer mode only**: - [ ] Every architectural claim cites file:line @@ -363,13 +382,7 @@ These items test the final document output. Process gates (Gate 0-3) are enforce ## Acceptance Criteria Creation Guidelines -1. **Principle**: Set specific, verifiable conditions. Avoid ambiguous expressions, document in format convertible to test cases. -2. **Example**: "Login works" → "After authentication with correct credentials, navigates to dashboard screen" -3. **Comprehensiveness**: Cover happy path, unhappy path, and edge cases. Define non-functional requirements in separate section. - - Expected behavior (happy path) - - Error handling (unhappy path) - - Edge cases -4. **Priority**: Place important acceptance criteria at the top +Each AC must be specific, verifiable, and convertible to a test case — avoid ambiguous expressions (e.g., "Login works" → "After authentication with correct credentials, navigates to dashboard screen"). Cover happy path, unhappy path, and edge cases; non-functional requirements belong in a separate section. Highest-priority AC first. Concrete scoping rules below. ### AC Scoping for Autonomous Implementation @@ -397,12 +410,7 @@ These items test the final document output. Process gates (Gate 0-3) are enforce **When** (create/update mode): New technology/library introduction, performance optimization, security design, major version upgrades. -Check current year with `date +%Y` and include in search queries: -- `[technology] [feature] best practices {current_year}` -- `[tech A] vs [tech B] comparison {current_year}` -- `[framework] breaking changes migration guide` - -Cite sources in "## References" section at end of ADR/Design Doc with URLs. +Check current year with `date +%Y` and include in search queries (e.g., `[technology] [feature | vs comparison | breaking changes] {current_year}`). Cite sources in "## References" section at end of ADR/Design Doc with URLs. **Reverse-engineer mode**: Skip. Research is for forward design decisions. @@ -412,11 +420,7 @@ Cite sources in "## References" section at end of ADR/Design Doc with URLs. ### Update Mode: Dependency Inventory for Changed Sections [Required] -Before modifying the document, inventory the external definitions that the changed sections depend on: - -1. **Extract literal identifiers from update scope**: Collect all concrete identifiers (paths, endpoints, type names, config keys, component names) in the sections being updated -2. **Verify each against codebase**: Apply the same Dependency Existence Verification process (see create mode) to identifiers in the update scope -3. **Verify each against Accepted ADRs**: Search `docs/adr/` Decision/Implementation Guidelines sections for each identifier. Flag if the same identifier has a different value or definition. (Cross-document checks are handled in a subsequent pipeline step.) +For each literal identifier in the updated sections (paths, endpoints, type names, config keys, component names): (1) verify against codebase per Dependency Existence Verification; (2) search `docs/adr/` Decision / Implementation Guidelines for the identifier and flag identifier-value mismatches. **Output format** (per identifier): ```yaml @@ -426,29 +430,19 @@ Before modifying the document, inventory the external definitions that the chang action: "[none | address in update | flag for user]" ``` -**On conflict**: Log conflicting identifiers in the output. The orchestrator is responsible for presenting conflicts to the user - -## Reverse-Engineer Mode (As-Is Documentation) +Log conflicts in the output; the orchestrator presents conflicts to the user. -Mode for documenting existing architecture as-is. Used when creating Design Docs from existing implementation (e.g., in reverse-engineering workflows). +## Reverse-Engineer Mode -### What to Skip in Reverse-Engineer Mode -- ADR creation (no decisions to record — decisions were already made) -- Option comparison (no alternatives to evaluate) -- Change Impact Map (no changes being proposed) -- Field Propagation Map (no new fields being introduced) -- Implementation Approach Decision (no implementation strategy to select) -- Latest Information Research (documenting what exists, not designing something new) +When `operation_mode: reverse-engineer`: -### Reverse-Engineer Mode Execution Steps +**Skip**: ADR creation, Option comparison, Change Impact Map, Field Propagation Map, Implementation Approach Decision, Latest Information Research, Minimal Surface Alternatives. -1. **Read & Inventory**: Read every Primary File. Record public interfaces per file. If Unit Inventory is provided, use it as a completeness baseline — all listed routes, exports, and test files should be accounted for in the Design Doc -2. **Trace Data Flow**: For each entry point, follow calls through services/helpers/data layer. Read each. Record actual flow and error handling as implemented -3. **Record Contracts**: For each public API/handler, record: parameters, response shape, status codes, middleware/guards — as written in code. For external dependencies: record what is called and returned. Use exact identifiers from source -4. **Document Data Model**: Read schema/type definitions. Record: field names, types, nullable markers, defaults. For enums: list ALL values -5. **Identify Test Coverage**: Glob for test files. Record which interfaces have tests. Confirm test existence with Glob before reporting +**Execute**: +1. Read every Primary File; record public interfaces per file. If Unit Inventory is provided, treat it as completeness baseline (every listed route, export, test file accounted for). +2. For each entry point, trace calls through services/helpers/data layer; record actual flow and error handling as implemented. +3. For each public API/handler, record parameters, response shape, status codes, middleware/guards verbatim from code. For external dependencies: record what is called and returned, using exact identifiers. +4. Read schema/type definitions; record field names, types, nullable markers, defaults. For enums: list ALL values. +5. Glob for test files; record which interfaces have tests. Confirm test existence by Glob. -### Reverse-Engineer Mode Quality Standard -- Every claim cites file:line as evidence -- Identifiers transcribed exactly from code -- Test existence confirmed by Glob, not assumed +**Quality**: every claim cites `file:line`; identifiers transcribed exactly; test existence confirmed by Glob. diff --git a/dev-workflows-fullstack/skills/coding-principles/SKILL.md b/dev-workflows-fullstack/skills/coding-principles/SKILL.md index 001ccdb..a1e95a9 100644 --- a/dev-workflows-fullstack/skills/coding-principles/SKILL.md +++ b/dev-workflows-fullstack/skills/coding-principles/SKILL.md @@ -9,8 +9,9 @@ description: Language-agnostic coding principles for maintainability, readabilit 1. **Maintainability over Speed**: Prioritize long-term code health over initial development velocity 2. **Simplicity First**: Choose the simplest solution that meets requirements (YAGNI principle) -3. **Explicit over Implicit**: Make intentions clear through code structure and naming -4. **Delete over Comment**: Remove unused code instead of commenting it out +3. **Minimum Surface for Required Coverage**: When introducing maintenance-surface-bearing elements (persistent state, public-contract or cross-boundary fields/props, behavioral modes/flags/variants, reusable abstractions, or component splits), select the smallest design surface that covers the current user-visible requirements and accepted technical constraints (audit, data integrity, compatibility, security, performance, accessibility). Adoption is justified by naming a current requirement or constraint that smaller alternatives fail to cover; value-based arguments serve as tiebreakers. Distinct from YAGNI (time-axis judgment of present vs. future need), this principle governs surface-area minimization at a fixed coverage point. +4. **Explicit over Implicit**: Make intentions clear through code structure and naming +5. **Delete over Comment**: Remove unused code instead of commenting it out ## Code Quality diff --git a/dev-workflows-fullstack/skills/documentation-criteria/references/design-template.md b/dev-workflows-fullstack/skills/documentation-criteria/references/design-template.md index a09c206..9bfeba4 100644 --- a/dev-workflows-fullstack/skills/documentation-criteria/references/design-template.md +++ b/dev-workflows-fullstack/skills/documentation-criteria/references/design-template.md @@ -111,7 +111,6 @@ Keywords determine test type and reduce ambiguity. ### [Functional Requirement 2] - [ ] The system shall display data list with pagination of 10 items per page -- [ ] **When** input is entered in search field, the system shall apply real-time filtering ## Existing Codebase Analysis @@ -180,13 +179,9 @@ No Ripple Effect: ### Main Components -#### Component 1 - -- **Responsibility**: [Scope of responsibility for this component] -- **Interface**: [APIs and contract definitions provided] -- **Dependencies**: [Relationships with other components] +Repeat the block below for each component. -#### Component 2 +#### Component 1 - **Responsibility**: [Scope of responsibility for this component] - **Interface**: [APIs and contract definitions provided] @@ -203,6 +198,38 @@ No Ripple Effect: **Decision**: [reuse / extend / new] — [rationale in 1-2 sentences] +### Minimal Surface Alternatives (When Introducing Maintenance-Surface Elements) + +One entry per new in-scope element. This section records the 5-step output produced by the invoking agent. + +#### Element 1: [name of the new element — e.g., persistent state field, public-contract field, cross-boundary prop, behavioral mode/variant, reusable abstraction or component split] + +**Step 1 — Fixed Requirements** +- [AC ID or constraint ID]: [requirement / constraint text] +- [AC ID or constraint ID]: [requirement / constraint text] + +**Steps 2–3 — Alternatives Compared** + +| Alternative | Current requirements covered (AC or constraint IDs) | New state introduced (count) | New concept / mode / flag (count) | Crosses component boundary (yes/no) | Breaking change or migration required (yes/no) | Subjective cost notes | +|---|---|---|---|---|---|---| +| [The added element as proposed] | | | | | | | +| [Subtractive alternative — derive / compute on demand / keep at caller / reuse existing / do not introduce new state] | | | | | | | +| [Optional third alternative] | | | | | | | + +**Step 4 — Selected Alternative and Rationale** +- **Selected**: [alternative name] +- **Rationale**: + - If selected = smallest alternative considered: state "smallest alternative considered; no further reduction available" + - If selected > smallest: name the current requirement(s) from step 1 that smaller alternatives fail to satisfy + +**Step 5 — Rejected Alternatives Log** +- [Alternative name]: [1-2 lines on what it was and why rejected] +- [Alternative name]: [1-2 lines on what it was and why rejected] + +(Repeat the Element block above for each additional in-scope element.) + +Mark the whole section as N/A with brief rationale when the design introduces no in-scope elements. + ### Contract Definitions ``` @@ -291,13 +318,12 @@ System Invariants: ### Technical Dependencies and Implementation Order #### Required Implementation Order -1. **[Component/Feature A]** - - Technical Reason: [Why this needs to be implemented first] - - Dependent Elements: [Other components that depend on this] -2. **[Component/Feature B]** - - Technical Reason: [Technical necessity to implement after A] - - Prerequisites: [Required pre-implementations] +Repeat the entry below for each component/feature, in dependency order. + +1. **[Component/Feature]** + - Technical Reason: [Why this needs to be implemented at this position] + - Prerequisites / Dependent Elements: [Components depended on or that depend on this] ### Migration Strategy @@ -366,9 +392,11 @@ Mark as N/A with brief rationale when the design introduces entirely new behavio ## Future Extensibility -- **Extension points**: [Interfaces, hooks, or plugin mechanisms designed for future use] -- **Known future requirements**: [Planned features that influenced current design decisions] -- **Intentional limitations**: [What was deliberately kept simple and why] +This section records what was **excluded** from the current design surface. Speculative inclusions belong in a separate proposal. + +- **Deferred possibilities**: [Capabilities considered during design and explicitly excluded from the current design surface. Each entry names either the current requirement it would have served, or marks itself as speculative] +- **Intentional limitations**: [What was deliberately kept small and why] +- **Extension points (existing, with current consumers)**: [Interfaces or hooks already in use by named current consumers. Each entry names a current consumer] ## Alternative Solutions diff --git a/dev-workflows/.claude-plugin/plugin.json b/dev-workflows/.claude-plugin/plugin.json index baae7ef..45a67d5 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.19.0", + "version": "0.19.1", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows/agents/code-reviewer.md b/dev-workflows/agents/code-reviewer.md index 684fdf4..423619c 100644 --- a/dev-workflows/agents/code-reviewer.md +++ b/dev-workflows/agents/code-reviewer.md @@ -293,6 +293,7 @@ Recommend higher-level review when: - Implementation significantly exceeds Design Doc quality - Security concerns discovered - Critical performance issues found +- Implementation introduces in-scope elements (persistent state; public-contract or cross-boundary fields/props; behavioral modes/flags/variants; reusable abstractions or component splits) that are absent from the Design Doc's Minimal Surface Alternatives section ## Special Considerations diff --git a/dev-workflows/agents/document-reviewer.md b/dev-workflows/agents/document-reviewer.md index c544a36..7e582c1 100644 --- a/dev-workflows/agents/document-reviewer.md +++ b/dev-workflows/agents/document-reviewer.md @@ -83,6 +83,7 @@ For DesignDoc, additionally verify: - [ ] Field propagation map present (when fields cross boundaries) - [ ] Verification Strategy section present with: correctness definition, verification method, verification timing, early verification point - [ ] Fact Disposition Table present and covers every `codebase_analysis.focusAreas` entry (when `codebase_analysis` is provided) +- [ ] Minimal Surface Alternatives section present with one entry per new in-scope element (persistent state / public-contract or cross-boundary field or prop / behavioral mode/flag/variant / reusable abstraction or component split) (when the design introduces any). Each entry contains the 5-step output (fixed requirements with AC IDs or accepted technical constraint IDs, alternatives table including at least one subtractive option, selected alternative with rationale, rejected alternatives log) #### Gate 1: Quality Assessment (only after Gate 0 passes) @@ -103,6 +104,14 @@ For DesignDoc, additionally verify: - **Verification Strategy quality check**: When Verification Strategy section exists, verify: (1) Correctness definition is specific and measurable — "tests pass" without specifying which tests or what they verify → `important` issue (category: `completeness`). (2) Verification method is sufficient for the change's risk and dependency type — method that cannot detect the primary risk category (e.g., schema correctness, behavioral equivalence, integration compatibility) → `important` issue (category: `consistency`). (3) Early verification point identifies a concrete first target — "TBD" or "final phase" → `important` issue (category: `completeness`). (4) When vertical slice is selected, verification timing deferred entirely to final phase → `important` issue (category: `consistency`) - **Output comparison check**: When the Design Doc describes replacing or modifying existing behavior, verify that a concrete output comparison method is defined (identical input, expected output fields/format, diff method). Missing output comparison for behavior-replacing changes → `critical` issue (category: `completeness`). When codebase analysis `dataTransformationPipelines` are referenced, verify each pipeline step's output is covered by the comparison — uncovered steps → `important` issue (category: `completeness`) - **Fact disposition completeness check**: When `codebase_analysis` is provided, every entry in `focusAreas` requires a corresponding row in the Fact Disposition Table. Missing rows → `critical` issue (category: `completeness`). `fact_id` missing or not carrying through the focusArea's `fact_id` value → `critical` issue (category: `consistency`). Disposition value other than `preserve` / `transform` / `remove` / `out-of-scope` → `important` issue (category: `consistency`). Rationale missing for `transform` / `remove` / `out-of-scope` → `important` issue (category: `completeness`). Evidence column not carrying through the focusArea's evidence value → `important` issue (category: `consistency`) +- **Minimal Surface Alternatives check**: + - *Scope trigger*: applies when the Design Doc introduces in-scope elements (persistent state; public-contract or cross-boundary fields or props; behavioral modes, flags, or variants; reusable abstractions or component splits). + - *Section existence*: when the trigger fires but the "Minimal Surface Alternatives" section is absent or empty → `critical` issue (category: `completeness`). + - *Per Element entry*: + - (1) Step 1 lists at least one AC ID or accepted technical constraint from the Design Doc → missing linkage or only speculative requirements ("future", "might want") → `critical` issue (category: `compliance`). + - (2) Steps 2–3 include at least one subtractive alternative (derive / compute on demand / keep at caller / reuse existing / do not introduce new state) → missing subtractive alternative → `critical` issue (category: `compliance`). + - (3) Step 4 rationale either selects the smallest alternative or names a current requirement smaller alternatives fail to satisfy → "useful" / "future-ready" / "convenient" / "users might want" used as primary rationale → `critical` issue (category: `compliance`). + - (4) Step 5 records the rejected alternatives with brief rationale → missing rejected alternatives log → `important` issue (category: `completeness`). **Perspective-specific Mode**: - Implement review based on specified mode and focus @@ -264,6 +273,7 @@ Include in output when `prior_context_count > 0`: - [ ] Verification Strategy aligns with design_type and implementation approach - [ ] Output comparison defined when design replaces/modifies existing behavior (covers all transformation pipeline steps) - [ ] Fact Disposition Table covers every `codebase_analysis.focusAreas` entry (when `codebase_analysis` is provided) +- [ ] Minimal Surface Alternatives section covers every new in-scope element (persistent state / public-contract or cross-boundary field or prop / behavioral mode/flag/variant / reusable abstraction or component split) with the 5-step output (when the design introduces any); selection rationale cites a named current requirement that smaller alternatives fail to satisfy, or names the smallest alternative as selected ## Review Criteria (for Comprehensive Mode) diff --git a/dev-workflows/agents/technical-designer.md b/dev-workflows/agents/technical-designer.md index 395f567..67c3ab2 100644 --- a/dev-workflows/agents/technical-designer.md +++ b/dev-workflows/agents/technical-designer.md @@ -41,6 +41,7 @@ The subsections below are not parallel mandates; they form four serial gates. Co - Existing Code Investigation - Fact Disposition (when Codebase Analysis input is provided) - Data Representation Decision (when new or modified data structures are introduced) +- Minimal Surface Alternatives (when introducing persistent state, public-contract or cross-boundary fields, behavioral modes/flags, or reusable abstractions) **Gate 2 — Design Decisions** (depends on Gate 1): - Implementation Approach Decision @@ -159,6 +160,41 @@ When the design introduces or significantly modifies data structures: - 3+ criteria fail → New structure justified - Record decision and rationale in Design Doc +### Minimal Surface Alternatives [Gate 1 — Required when introducing persistent state, public-contract or cross-boundary fields, behavioral modes/flags, or reusable abstractions] + +Applies to each maintenance-surface-bearing element the design introduces. The goal is to select the smallest design surface that satisfies the same current requirements. Reference: coding-principles skill, "Minimum Surface for Required Coverage". + +**In scope**: persistent state (DB columns/tables, file fields, cache entries, queue payloads, session/cookie data, any state outliving a single operation); public-contract elements (exported types, API request/response fields, exported function signatures, schema definitions); cross-boundary fields (passed between modules/services/components); behavioral modes/flags (state-machine states, feature flags, config options); reusable abstractions (new types/classes/modules/interfaces intended for reuse). + +**Out of scope**: local variables within a single function; internal struct fields used only within one module/package; test fixture or mock fields; transient state confined to a single operation; private state without external observers. + +**Precedence**: when an element matches both an in-scope and an out-of-scope condition (e.g., a struct field that is both "internal to one module" and "persisted to a DB column"), the in-scope classification wins and the gate applies. + +Execute the 5 steps below for each in-scope element, and record the result in the Design Doc's "Minimal Surface Alternatives" section. + +1. **Fix Requirements** + - List the current user-visible requirements / ACs / accepted technical constraints (audit, data integrity, compatibility, security, performance) this element would serve, citing AC IDs or constraint IDs from the Design Doc. + - Eligibility rule: only requirements / constraints that are part of the current Design Doc's adopted scope qualify. Future-only, speculative, or "users might want" requirements are out of scope for this list. + +2. **Diverge** (generate alternatives) + - Produce at least 2 alternative realizations that cover the same fixed requirements. + - At least one alternative must be subtractive. Subtractive alternatives are drawn from: derive from existing data, compute on demand, keep at caller / invocation boundary, reuse existing structure, do not introduce new state. + +3. **Compare** (record alternatives in a table) + + | Alternative | Current requirements covered (AC or constraint IDs) | New persistent state (count) | New concept / mode / flag (count) | Crosses component boundary (yes/no) | Breaking change or migration required (yes/no) | Subjective cost notes | + |---|---|---|---|---|---|---| + + Resolution priority (later columns are tiebreakers when earlier are equal): (1) new persistent state (lower=smaller); (2) crosses component boundary (no=smaller); (3) new concept/mode/flag (lower=smaller); (4) breaking change or migration (no=smaller); (5) subjective cost notes. + +4. **Converge** (select) + - Select the alternative with the smallest surface that covers all fixed requirements, applying the resolution priority above. + - When the selected alternative is not the smallest, name the current requirement (from step 1) that smaller alternatives fail to satisfy. + - "Useful" / "future-ready" / "convenient for implementation" / "users might want" belong in the Subjective cost notes column (tiebreakers only). + +5. **Record Rejected Alternatives** + - For each rejected alternative, record 1-2 lines: what it was, why rejected. Include in the Design Doc to prevent re-proposal in subsequent iterations or by future agents. + ### Implementation Approach Decision [Gate 2 — Required] Must be performed when creating Design Doc: @@ -299,24 +335,11 @@ Execute file output immediately (considered approved at execution). ## Important Design Principles -1. **Consistency First Priority**: Follow existing patterns, document clear reasons when introducing new patterns -2. **Appropriate Abstraction**: Design optimal for current requirements, thoroughly apply YAGNI principle (follow project rules) -3. **Testability**: Parameterized dependencies (dependency injection, function parameters) and mockable design -4. **Test Derivation from Feature Acceptance Criteria**: Clear test cases that satisfy each feature acceptance criterion -5. **Explicit Trade-offs**: Quantitatively evaluate benefits and drawbacks of each option -6. **Active Use of Latest Information**: - - Always research latest best practices, libraries, and approaches with WebSearch before design - - Cite information sources in "References" section with URLs - - Especially confirm multiple reliable sources when introducing new technologies +Apply principles from loaded skills (`coding-principles`, `testing-principles`, `ai-development-guide`). Trade-off evaluation (Gate 2 + ADR Checklist), existing-pattern consistency (Gate 1 Existing Code Investigation + Fact Disposition), and Verification Strategy from AC (Gate 2) are enforced above; test derivation itself is a downstream agent responsibility. Latest-information research is governed by the "Latest Information Research" section below. ## Implementation Sample Standards Compliance -**MANDATORY**: All implementation samples in ADR and Design Docs MUST strictly comply with project coding standards. - -Implementation sample creation checklist: -- Follow language-appropriate correctness guarantee patterns -- Apply appropriate design patterns for the language -- Implement robust error handling strategies +All implementation samples in ADR and Design Docs MUST follow the loaded `coding-principles` and `testing-principles` skills. Omit samples unless they clarify contracts or edge cases that prose cannot convey. ## Diagram Creation (using mermaid notation) @@ -340,7 +363,6 @@ These items test the final document output. Process gates (Gate 0-3) are enforce - [ ] Architecture and data flow appear as diagrams - [ ] External Resources Used subsection lists feature-tier identifiers (when external resources apply) - [ ] Quality Assurance Mechanisms list adopted/noted status for checks covering this change -- [ ] Fact Disposition Table covers every Codebase Analysis focusArea, each row with fact_id + disposition + rationale + evidence (when Codebase Analysis input was provided) **Create/update mode only**: - [ ] Prerequisite common ADRs are referenced @@ -350,10 +372,7 @@ These items test the final document output. Process gates (Gate 0-3) are enforce - [ ] Interface change matrix is complete - [ ] Implementation approach selection (vertical/horizontal/hybrid) carries rationale - [ ] `complexity_level` is set; when medium/high, `complexity_rationale` covers (1) requirements/ACs, (2) constraints/risks -- [ ] Data representation decision is documented when new structures are introduced -- [ ] Field propagation map is included when fields cross boundaries - [ ] Verification Strategy defines correctness, method, timing, and early verification point -- [ ] Output comparison defines input, expected output fields, and diff method when behavior is replaced or modified (covers every transformation pipeline step from codebase analysis) **Reverse-engineer mode only**: - [ ] Every architectural claim cites file:line @@ -363,13 +382,7 @@ These items test the final document output. Process gates (Gate 0-3) are enforce ## Acceptance Criteria Creation Guidelines -1. **Principle**: Set specific, verifiable conditions. Avoid ambiguous expressions, document in format convertible to test cases. -2. **Example**: "Login works" → "After authentication with correct credentials, navigates to dashboard screen" -3. **Comprehensiveness**: Cover happy path, unhappy path, and edge cases. Define non-functional requirements in separate section. - - Expected behavior (happy path) - - Error handling (unhappy path) - - Edge cases -4. **Priority**: Place important acceptance criteria at the top +Each AC must be specific, verifiable, and convertible to a test case — avoid ambiguous expressions (e.g., "Login works" → "After authentication with correct credentials, navigates to dashboard screen"). Cover happy path, unhappy path, and edge cases; non-functional requirements belong in a separate section. Highest-priority AC first. Concrete scoping rules below. ### AC Scoping for Autonomous Implementation @@ -397,12 +410,7 @@ These items test the final document output. Process gates (Gate 0-3) are enforce **When** (create/update mode): New technology/library introduction, performance optimization, security design, major version upgrades. -Check current year with `date +%Y` and include in search queries: -- `[technology] [feature] best practices {current_year}` -- `[tech A] vs [tech B] comparison {current_year}` -- `[framework] breaking changes migration guide` - -Cite sources in "## References" section at end of ADR/Design Doc with URLs. +Check current year with `date +%Y` and include in search queries (e.g., `[technology] [feature | vs comparison | breaking changes] {current_year}`). Cite sources in "## References" section at end of ADR/Design Doc with URLs. **Reverse-engineer mode**: Skip. Research is for forward design decisions. @@ -412,11 +420,7 @@ Cite sources in "## References" section at end of ADR/Design Doc with URLs. ### Update Mode: Dependency Inventory for Changed Sections [Required] -Before modifying the document, inventory the external definitions that the changed sections depend on: - -1. **Extract literal identifiers from update scope**: Collect all concrete identifiers (paths, endpoints, type names, config keys, component names) in the sections being updated -2. **Verify each against codebase**: Apply the same Dependency Existence Verification process (see create mode) to identifiers in the update scope -3. **Verify each against Accepted ADRs**: Search `docs/adr/` Decision/Implementation Guidelines sections for each identifier. Flag if the same identifier has a different value or definition. (Cross-document checks are handled in a subsequent pipeline step.) +For each literal identifier in the updated sections (paths, endpoints, type names, config keys, component names): (1) verify against codebase per Dependency Existence Verification; (2) search `docs/adr/` Decision / Implementation Guidelines for the identifier and flag identifier-value mismatches. **Output format** (per identifier): ```yaml @@ -426,29 +430,19 @@ Before modifying the document, inventory the external definitions that the chang action: "[none | address in update | flag for user]" ``` -**On conflict**: Log conflicting identifiers in the output. The orchestrator is responsible for presenting conflicts to the user - -## Reverse-Engineer Mode (As-Is Documentation) +Log conflicts in the output; the orchestrator presents conflicts to the user. -Mode for documenting existing architecture as-is. Used when creating Design Docs from existing implementation (e.g., in reverse-engineering workflows). +## Reverse-Engineer Mode -### What to Skip in Reverse-Engineer Mode -- ADR creation (no decisions to record — decisions were already made) -- Option comparison (no alternatives to evaluate) -- Change Impact Map (no changes being proposed) -- Field Propagation Map (no new fields being introduced) -- Implementation Approach Decision (no implementation strategy to select) -- Latest Information Research (documenting what exists, not designing something new) +When `operation_mode: reverse-engineer`: -### Reverse-Engineer Mode Execution Steps +**Skip**: ADR creation, Option comparison, Change Impact Map, Field Propagation Map, Implementation Approach Decision, Latest Information Research, Minimal Surface Alternatives. -1. **Read & Inventory**: Read every Primary File. Record public interfaces per file. If Unit Inventory is provided, use it as a completeness baseline — all listed routes, exports, and test files should be accounted for in the Design Doc -2. **Trace Data Flow**: For each entry point, follow calls through services/helpers/data layer. Read each. Record actual flow and error handling as implemented -3. **Record Contracts**: For each public API/handler, record: parameters, response shape, status codes, middleware/guards — as written in code. For external dependencies: record what is called and returned. Use exact identifiers from source -4. **Document Data Model**: Read schema/type definitions. Record: field names, types, nullable markers, defaults. For enums: list ALL values -5. **Identify Test Coverage**: Glob for test files. Record which interfaces have tests. Confirm test existence with Glob before reporting +**Execute**: +1. Read every Primary File; record public interfaces per file. If Unit Inventory is provided, treat it as completeness baseline (every listed route, export, test file accounted for). +2. For each entry point, trace calls through services/helpers/data layer; record actual flow and error handling as implemented. +3. For each public API/handler, record parameters, response shape, status codes, middleware/guards verbatim from code. For external dependencies: record what is called and returned, using exact identifiers. +4. Read schema/type definitions; record field names, types, nullable markers, defaults. For enums: list ALL values. +5. Glob for test files; record which interfaces have tests. Confirm test existence by Glob. -### Reverse-Engineer Mode Quality Standard -- Every claim cites file:line as evidence -- Identifiers transcribed exactly from code -- Test existence confirmed by Glob, not assumed +**Quality**: every claim cites `file:line`; identifiers transcribed exactly; test existence confirmed by Glob. diff --git a/dev-workflows/skills/coding-principles/SKILL.md b/dev-workflows/skills/coding-principles/SKILL.md index 001ccdb..a1e95a9 100644 --- a/dev-workflows/skills/coding-principles/SKILL.md +++ b/dev-workflows/skills/coding-principles/SKILL.md @@ -9,8 +9,9 @@ description: Language-agnostic coding principles for maintainability, readabilit 1. **Maintainability over Speed**: Prioritize long-term code health over initial development velocity 2. **Simplicity First**: Choose the simplest solution that meets requirements (YAGNI principle) -3. **Explicit over Implicit**: Make intentions clear through code structure and naming -4. **Delete over Comment**: Remove unused code instead of commenting it out +3. **Minimum Surface for Required Coverage**: When introducing maintenance-surface-bearing elements (persistent state, public-contract or cross-boundary fields/props, behavioral modes/flags/variants, reusable abstractions, or component splits), select the smallest design surface that covers the current user-visible requirements and accepted technical constraints (audit, data integrity, compatibility, security, performance, accessibility). Adoption is justified by naming a current requirement or constraint that smaller alternatives fail to cover; value-based arguments serve as tiebreakers. Distinct from YAGNI (time-axis judgment of present vs. future need), this principle governs surface-area minimization at a fixed coverage point. +4. **Explicit over Implicit**: Make intentions clear through code structure and naming +5. **Delete over Comment**: Remove unused code instead of commenting it out ## Code Quality diff --git a/dev-workflows/skills/documentation-criteria/references/design-template.md b/dev-workflows/skills/documentation-criteria/references/design-template.md index a09c206..9bfeba4 100644 --- a/dev-workflows/skills/documentation-criteria/references/design-template.md +++ b/dev-workflows/skills/documentation-criteria/references/design-template.md @@ -111,7 +111,6 @@ Keywords determine test type and reduce ambiguity. ### [Functional Requirement 2] - [ ] The system shall display data list with pagination of 10 items per page -- [ ] **When** input is entered in search field, the system shall apply real-time filtering ## Existing Codebase Analysis @@ -180,13 +179,9 @@ No Ripple Effect: ### Main Components -#### Component 1 - -- **Responsibility**: [Scope of responsibility for this component] -- **Interface**: [APIs and contract definitions provided] -- **Dependencies**: [Relationships with other components] +Repeat the block below for each component. -#### Component 2 +#### Component 1 - **Responsibility**: [Scope of responsibility for this component] - **Interface**: [APIs and contract definitions provided] @@ -203,6 +198,38 @@ No Ripple Effect: **Decision**: [reuse / extend / new] — [rationale in 1-2 sentences] +### Minimal Surface Alternatives (When Introducing Maintenance-Surface Elements) + +One entry per new in-scope element. This section records the 5-step output produced by the invoking agent. + +#### Element 1: [name of the new element — e.g., persistent state field, public-contract field, cross-boundary prop, behavioral mode/variant, reusable abstraction or component split] + +**Step 1 — Fixed Requirements** +- [AC ID or constraint ID]: [requirement / constraint text] +- [AC ID or constraint ID]: [requirement / constraint text] + +**Steps 2–3 — Alternatives Compared** + +| Alternative | Current requirements covered (AC or constraint IDs) | New state introduced (count) | New concept / mode / flag (count) | Crosses component boundary (yes/no) | Breaking change or migration required (yes/no) | Subjective cost notes | +|---|---|---|---|---|---|---| +| [The added element as proposed] | | | | | | | +| [Subtractive alternative — derive / compute on demand / keep at caller / reuse existing / do not introduce new state] | | | | | | | +| [Optional third alternative] | | | | | | | + +**Step 4 — Selected Alternative and Rationale** +- **Selected**: [alternative name] +- **Rationale**: + - If selected = smallest alternative considered: state "smallest alternative considered; no further reduction available" + - If selected > smallest: name the current requirement(s) from step 1 that smaller alternatives fail to satisfy + +**Step 5 — Rejected Alternatives Log** +- [Alternative name]: [1-2 lines on what it was and why rejected] +- [Alternative name]: [1-2 lines on what it was and why rejected] + +(Repeat the Element block above for each additional in-scope element.) + +Mark the whole section as N/A with brief rationale when the design introduces no in-scope elements. + ### Contract Definitions ``` @@ -291,13 +318,12 @@ System Invariants: ### Technical Dependencies and Implementation Order #### Required Implementation Order -1. **[Component/Feature A]** - - Technical Reason: [Why this needs to be implemented first] - - Dependent Elements: [Other components that depend on this] -2. **[Component/Feature B]** - - Technical Reason: [Technical necessity to implement after A] - - Prerequisites: [Required pre-implementations] +Repeat the entry below for each component/feature, in dependency order. + +1. **[Component/Feature]** + - Technical Reason: [Why this needs to be implemented at this position] + - Prerequisites / Dependent Elements: [Components depended on or that depend on this] ### Migration Strategy @@ -366,9 +392,11 @@ Mark as N/A with brief rationale when the design introduces entirely new behavio ## Future Extensibility -- **Extension points**: [Interfaces, hooks, or plugin mechanisms designed for future use] -- **Known future requirements**: [Planned features that influenced current design decisions] -- **Intentional limitations**: [What was deliberately kept simple and why] +This section records what was **excluded** from the current design surface. Speculative inclusions belong in a separate proposal. + +- **Deferred possibilities**: [Capabilities considered during design and explicitly excluded from the current design surface. Each entry names either the current requirement it would have served, or marks itself as speculative] +- **Intentional limitations**: [What was deliberately kept small and why] +- **Extension points (existing, with current consumers)**: [Interfaces or hooks already in use by named current consumers. Each entry names a current consumer] ## Alternative Solutions diff --git a/package.json b/package.json index 9a179fe..dc56919 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "claude-code-workflows", - "version": "0.19.0", + "version": "0.19.1", "private": true, "type": "module", "engines": { diff --git a/skills/coding-principles/SKILL.md b/skills/coding-principles/SKILL.md index 001ccdb..a1e95a9 100644 --- a/skills/coding-principles/SKILL.md +++ b/skills/coding-principles/SKILL.md @@ -9,8 +9,9 @@ description: Language-agnostic coding principles for maintainability, readabilit 1. **Maintainability over Speed**: Prioritize long-term code health over initial development velocity 2. **Simplicity First**: Choose the simplest solution that meets requirements (YAGNI principle) -3. **Explicit over Implicit**: Make intentions clear through code structure and naming -4. **Delete over Comment**: Remove unused code instead of commenting it out +3. **Minimum Surface for Required Coverage**: When introducing maintenance-surface-bearing elements (persistent state, public-contract or cross-boundary fields/props, behavioral modes/flags/variants, reusable abstractions, or component splits), select the smallest design surface that covers the current user-visible requirements and accepted technical constraints (audit, data integrity, compatibility, security, performance, accessibility). Adoption is justified by naming a current requirement or constraint that smaller alternatives fail to cover; value-based arguments serve as tiebreakers. Distinct from YAGNI (time-axis judgment of present vs. future need), this principle governs surface-area minimization at a fixed coverage point. +4. **Explicit over Implicit**: Make intentions clear through code structure and naming +5. **Delete over Comment**: Remove unused code instead of commenting it out ## Code Quality diff --git a/skills/documentation-criteria/references/design-template.md b/skills/documentation-criteria/references/design-template.md index a09c206..9bfeba4 100644 --- a/skills/documentation-criteria/references/design-template.md +++ b/skills/documentation-criteria/references/design-template.md @@ -111,7 +111,6 @@ Keywords determine test type and reduce ambiguity. ### [Functional Requirement 2] - [ ] The system shall display data list with pagination of 10 items per page -- [ ] **When** input is entered in search field, the system shall apply real-time filtering ## Existing Codebase Analysis @@ -180,13 +179,9 @@ No Ripple Effect: ### Main Components -#### Component 1 - -- **Responsibility**: [Scope of responsibility for this component] -- **Interface**: [APIs and contract definitions provided] -- **Dependencies**: [Relationships with other components] +Repeat the block below for each component. -#### Component 2 +#### Component 1 - **Responsibility**: [Scope of responsibility for this component] - **Interface**: [APIs and contract definitions provided] @@ -203,6 +198,38 @@ No Ripple Effect: **Decision**: [reuse / extend / new] — [rationale in 1-2 sentences] +### Minimal Surface Alternatives (When Introducing Maintenance-Surface Elements) + +One entry per new in-scope element. This section records the 5-step output produced by the invoking agent. + +#### Element 1: [name of the new element — e.g., persistent state field, public-contract field, cross-boundary prop, behavioral mode/variant, reusable abstraction or component split] + +**Step 1 — Fixed Requirements** +- [AC ID or constraint ID]: [requirement / constraint text] +- [AC ID or constraint ID]: [requirement / constraint text] + +**Steps 2–3 — Alternatives Compared** + +| Alternative | Current requirements covered (AC or constraint IDs) | New state introduced (count) | New concept / mode / flag (count) | Crosses component boundary (yes/no) | Breaking change or migration required (yes/no) | Subjective cost notes | +|---|---|---|---|---|---|---| +| [The added element as proposed] | | | | | | | +| [Subtractive alternative — derive / compute on demand / keep at caller / reuse existing / do not introduce new state] | | | | | | | +| [Optional third alternative] | | | | | | | + +**Step 4 — Selected Alternative and Rationale** +- **Selected**: [alternative name] +- **Rationale**: + - If selected = smallest alternative considered: state "smallest alternative considered; no further reduction available" + - If selected > smallest: name the current requirement(s) from step 1 that smaller alternatives fail to satisfy + +**Step 5 — Rejected Alternatives Log** +- [Alternative name]: [1-2 lines on what it was and why rejected] +- [Alternative name]: [1-2 lines on what it was and why rejected] + +(Repeat the Element block above for each additional in-scope element.) + +Mark the whole section as N/A with brief rationale when the design introduces no in-scope elements. + ### Contract Definitions ``` @@ -291,13 +318,12 @@ System Invariants: ### Technical Dependencies and Implementation Order #### Required Implementation Order -1. **[Component/Feature A]** - - Technical Reason: [Why this needs to be implemented first] - - Dependent Elements: [Other components that depend on this] -2. **[Component/Feature B]** - - Technical Reason: [Technical necessity to implement after A] - - Prerequisites: [Required pre-implementations] +Repeat the entry below for each component/feature, in dependency order. + +1. **[Component/Feature]** + - Technical Reason: [Why this needs to be implemented at this position] + - Prerequisites / Dependent Elements: [Components depended on or that depend on this] ### Migration Strategy @@ -366,9 +392,11 @@ Mark as N/A with brief rationale when the design introduces entirely new behavio ## Future Extensibility -- **Extension points**: [Interfaces, hooks, or plugin mechanisms designed for future use] -- **Known future requirements**: [Planned features that influenced current design decisions] -- **Intentional limitations**: [What was deliberately kept simple and why] +This section records what was **excluded** from the current design surface. Speculative inclusions belong in a separate proposal. + +- **Deferred possibilities**: [Capabilities considered during design and explicitly excluded from the current design surface. Each entry names either the current requirement it would have served, or marks itself as speculative] +- **Intentional limitations**: [What was deliberately kept small and why] +- **Extension points (existing, with current consumers)**: [Interfaces or hooks already in use by named current consumers. Each entry names a current consumer] ## Alternative Solutions