From 312fef95cda2743ece5bc57c5ffba872faf771a0 Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Tue, 28 Jul 2026 14:00:55 +0900 Subject: [PATCH 1/3] Improve workflow execution contracts and context efficiency --- .agents/skills/coding-rules/SKILL.md | 159 +++------- .../coding-rules/references/typescript.md | 164 ++--------- .../skills/documentation-criteria/SKILL.md | 2 +- .../references/plan-template.md | 5 +- .../references/prd-template.md | 14 +- .../references/task-template.md | 8 + .../skills/integration-e2e-testing/SKILL.md | 4 + .agents/skills/llm-friendly-context/SKILL.md | 6 + .../recipe-add-integration-tests/SKILL.md | 14 +- .agents/skills/recipe-build/SKILL.md | 24 +- .agents/skills/recipe-design/SKILL.md | 4 +- .agents/skills/recipe-diagnose/SKILL.md | 4 +- .agents/skills/recipe-front-adjust/SKILL.md | 2 + .agents/skills/recipe-front-build/SKILL.md | 26 +- .agents/skills/recipe-front-design/SKILL.md | 4 +- .agents/skills/recipe-front-plan/SKILL.md | 2 + .agents/skills/recipe-front-review/SKILL.md | 12 +- .../skills/recipe-fullstack-build/SKILL.md | 24 +- .../recipe-fullstack-implement/SKILL.md | 35 ++- .agents/skills/recipe-implement/SKILL.md | 24 +- .agents/skills/recipe-plan/SKILL.md | 2 + .../recipe-prepare-implementation/SKILL.md | 9 +- .../skills/recipe-reverse-engineer/SKILL.md | 8 +- .agents/skills/recipe-review/SKILL.md | 14 +- .agents/skills/recipe-task/SKILL.md | 2 +- .agents/skills/recipe-update-doc/SKILL.md | 4 +- .../subagents-orchestration-guide/SKILL.md | 58 ++-- .../references/monorepo-flow.md | 10 +- .../references/skills-index.yaml | 72 ++--- .agents/skills/testing/SKILL.md | 272 +++--------------- .../skills/testing/references/typescript.md | 2 +- .codex/agents/acceptance-test-generator.toml | 2 +- .codex/agents/code-reviewer.toml | 6 +- .codex/agents/code-verifier.toml | 19 +- .codex/agents/codebase-analyzer.toml | 2 +- .codex/agents/design-sync.toml | 2 +- .codex/agents/document-reviewer.toml | 13 +- .codex/agents/integration-test-reviewer.toml | 56 ++-- .codex/agents/investigator.toml | 2 +- .codex/agents/prd-creator.toml | 4 +- .codex/agents/quality-fixer-frontend.toml | 32 +-- .codex/agents/quality-fixer.toml | 25 +- .codex/agents/requirement-analyzer.toml | 2 + .codex/agents/rule-advisor.toml | 2 + .codex/agents/scope-discoverer.toml | 2 +- .codex/agents/security-reviewer.toml | 55 ++-- .codex/agents/solver.toml | 2 +- .codex/agents/task-decomposer.toml | 11 +- .codex/agents/task-executor-frontend.toml | 26 +- .codex/agents/task-executor.toml | 26 +- .../agents/technical-designer-frontend.toml | 2 +- .codex/agents/technical-designer.toml | 2 +- .codex/agents/ui-analyzer.toml | 2 +- .codex/agents/ui-spec-designer.toml | 2 +- .codex/agents/verifier.toml | 2 +- .codex/agents/work-planner.toml | 5 +- README.md | 2 +- 57 files changed, 492 insertions(+), 804 deletions(-) diff --git a/.agents/skills/coding-rules/SKILL.md b/.agents/skills/coding-rules/SKILL.md index d1ab3c7..91b9bf4 100644 --- a/.agents/skills/coding-rules/SKILL.md +++ b/.agents/skills/coding-rules/SKILL.md @@ -1,143 +1,64 @@ --- name: coding-rules -description: "Language-agnostic coding standards for maintainability, readability, and quality. Use when: implementing features, refactoring code, reviewing code quality, or writing functions." +description: "Repository-aware implementation rules for minimal design surface, contract safety, representative patterns, and verifiable changes. Use when implementing, refactoring, or reviewing code." --- # Coding Rules -## Language-Specific References +## Reference -For language-specific rules, also read: -- **TypeScript/React**: [references/typescript.md](references/typescript.md) +Read [references/typescript.md](references/typescript.md) only for TypeScript used in web frontend work, including React applications. It does not apply to backend or non-web TypeScript. Read [references/security-checks.md](references/security-checks.md) when the change crosses an input, authorization, secret, persistence, or output boundary. -## Core Philosophy [MANDATORY] +## Source Order -1. **Maintainability over Speed**: Prioritize long-term code health -2. **Simplicity First**: YAGNI principle — simplest solution that meets requirements -3. **Design Convergence**: Deliver the current required outcome with the least new design surface. Add surface only to satisfy a current requirement, verified constraint, observed problem, or evidence-backed material risk; among sufficient options, choose the lowest-lifecycle-cost option. -4. **Explicit over Implicit**: Clear intentions through code structure and naming -5. **Delete over Comment**: Remove unused code instead of commenting it out +Follow, in order: -**ENFORCEMENT**: Every code change MUST align with these principles +1. Task, acceptance criteria, Binding Decisions, and Reference Contracts +2. Governing Design Doc, ADR, Work Plan, and repository instructions +3. Representative repository patterns +4. Language/framework defaults -## Design Surface Terms [MANDATORY] +Do not substitute generic best practice for a sourced project contract. -Use these definitions when classifying Design Convergence additions or code-review escalation. +## Minimal Design Surface -- **Maintenance-surface-bearing elements**: persistent state; public-contract or cross-boundary fields/props; behavioral modes, flags, or variants; reusable abstractions; extracted services; shared utilities; component splits. -- **Non-surface elements**: private local variables, internal helper functions with no external observers, test fixtures or mocks, temporary migration scaffolding removed before completion, and private implementation details confined to one function or file. -- **Classification precedence**: When an element matches both surface-bearing and non-surface conditions, classify it as surface-bearing. -- **Selection rule**: Add a surface-bearing element only when it is required by a current requirement, verified constraint, observed problem, or evidence-backed material risk. Prefer fewer new elements only when the remaining candidates are otherwise sufficient and equivalent. -- **Relation to YAGNI**: YAGNI decides present vs. future need over time; Design Convergence minimizes surface area for the current accepted scope. +Deliver the current requirement with the least new persistent surface. Persistent state, public/cross-boundary fields, modes, flags, reusable abstractions, shared utilities, and component/service splits require a current requirement, verified constraint, observed problem, or evidence-backed material risk. -## Code Quality [MANDATORY] +Private local implementation details and test fixtures are not new design surface. If an element matches both categories, treat it as design surface. If several sufficient options remain, prefer the one with lower lifecycle cost. -- Resolve technical debt within confirmed scope or dependencies required for its outcome; report other debt separately -- Use meaningful, descriptive names from the problem domain -- Extract magic numbers and strings into named constants -- Keep code self-documenting +## Contract and Boundary Safety -## Function Design [MANDATORY] +- Preserve required signatures, schemas, serialized values, field order, state transitions, dependency direction, and error behavior. +- Validate untrusted input at the boundary and encode output for its destination. +- Propagate or handle errors with useful context; do not silently suppress them. +- Keep secrets and sensitive values out of source, client bundles, errors, and logs. +- Use parameterized data access and verify authorization at resource access points when applicable. +- For persistent or shared state, verify when partial, stale, committed, and rollback-only states become observable. -- **0-2 parameters** per function (use objects for 3+) -- Single responsibility — each function MUST do one thing well -- Keep functions < 50 lines -- Use pure functions where possible — separate data transformation from side effects -- Use early returns to keep nesting ≤ 3 levels -- **Inject external dependencies explicitly** — pass as parameters for testability +## Repository-Local Choice -## Error Handling [MANDATORY] +Before adopting a pattern, API, or dependency: -- **Always handle errors**: Log with context or propagate explicitly — error suppression is PROHIBITED -- **Fail fast**: Detect and report errors early -- **Protect sensitive data**: Mask passwords, tokens, PII from logs -- Use language-appropriate error handling mechanisms -- Include error context when re-throwing +1. Inspect the changed feature and relevant siblings. +2. Check whether the pattern is representative where alternatives coexist. +3. Follow the dominant compatible pattern or record why another existing pattern is required. +4. Escalate dependency/version or architecture choices when repository evidence cannot resolve them. -**ENFORCEMENT**: Zero silent error suppression — every error MUST have log output and appropriate handling +Nearby code is evidence, not authority by itself. -## Dependency Management +## Change Discipline -- **Inject external dependencies explicitly** — pass as parameters for testability -- Depend on abstractions, not concrete implementations -- Minimize inter-module dependencies +- Keep the change within the task's target files and accepted scope. +- Use names and structure that expose domain intent. +- Remove unused code and obsolete comments in the changed scope. +- Optimize only from measurements or a sourced requirement. +- Refactor in reversible increments and run the focused verification after each behavior-affecting step. +- Report adjacent debt outside scope; do not expand the change silently. -## Reference Representativeness +## Completion Gate -### Verifying References Before Adoption - -When adopting patterns, APIs, or dependencies from existing code: -- If referencing only nearby files, verify the pattern is representative across the repository before adopting it -- If multiple approaches coexist, identify the majority pattern and make a deliberate choice -- If adopting an external dependency, verify repository-wide usage distribution for that dependency and its version -- If repository evidence is insufficient to choose an appropriate dependency version, escalate instead of guessing -- If following an existing pattern when alternatives exist, state the reason for following it - -### Principle - -Nearby code is a starting point for investigation, not a sufficient basis for adoption. Confirm that the reference is representative of repository conventions before using it as the model. - -## Performance - -- **Measure first**: Profile before optimizing — no premature optimization -- Focus on algorithms over micro-optimizations -- Choose data structures based on access patterns - -## Code Organization - -- One primary responsibility per file -- Group related functionality together -- Separate concerns: domain logic, data access, presentation -- Keep files ≤ 500 lines - -## Commenting Principles - -- Prefer names, types, and structure over comments -- Add comments only for why, limitations, edge cases, or public API contracts -- No historical information — use version control -- Remove commented-out code -- Keep comments concise and timeless - -## Refactoring [SAFE CHANGE PROTOCOL] - -**STEP 1**: Understand current state -**STEP 2**: Make one small change -**STEP 3**: Run tests — confirm all pass -**STEP 4**: Repeat from STEP 2 - -**Triggers**: duplication, functions > 50 lines, complex conditionals - -**ENFORCEMENT**: Each step MUST maintain working state - -## Security - -### Secure Defaults -- Store credentials and secrets through environment variables or dedicated secret managers -- Use parameterized queries (prepared statements) for all database access -- Use established cryptographic libraries provided by the language or framework -- Generate security-critical values (tokens, IDs, nonces) with cryptographically secure random generators -- Encrypt sensitive data at rest and in transit using standard protocols - -### Input and Output Boundaries -- Validate all external input at system entry points for expected format, type, and length -- Encode output appropriately for its rendering context (HTML, SQL, shell, URL) -- Return only information necessary for the caller in error responses; log detailed diagnostics server-side - -### Access Control -- Apply authentication to all entry points that handle user data or trigger state changes -- Verify authorization for each resource access, not only at the entry point -- Grant only the permissions required for the operation (files, database connections, API scopes) - -### Knowledge Cutoff Supplement (2026-03) -- OWASP Top 10:2025 shifted from symptoms to root causes; added "Software Supply Chain Failures" (A03) and "Mishandling of Exceptional Conditions" (A10) -- Recent research indicates AI-generated code shows elevated rates of access control gaps — treat authentication and authorization as high-priority review targets -- OpenSSF published "Security-Focused Guide for AI Code Assistant Instructions" — recommends language-specific, actionable constraints over generic advice -- For detailed detection patterns, see `references/security-checks.md` - -## Version Control [MANDATORY] - -- Atomic, focused commits with clear messages -- Commit working code that passes all tests -- Never commit debug code or secrets - -**ENFORCEMENT**: Code MUST pass all quality checks before commit +- [ ] Every addition maps to a governing requirement or verified risk +- [ ] Public and cross-boundary contracts remain exact +- [ ] Repository-local pattern choice is supported by evidence +- [ ] Errors, sensitive data, and persistent state boundaries are handled +- [ ] Focused and repository-required checks pass diff --git a/.agents/skills/coding-rules/references/typescript.md b/.agents/skills/coding-rules/references/typescript.md index c31294b..4e7a2ee 100644 --- a/.agents/skills/coding-rules/references/typescript.md +++ b/.agents/skills/coding-rules/references/typescript.md @@ -1,149 +1,39 @@ -# TypeScript Development Rules (Frontend) +# Web Frontend TypeScript and React -## Basic Principles +Apply only rules relevant to the changed code and prefer repository configuration and local patterns. -- **Aggressive Refactoring** - Prevent technical debt and maintain health -- **No Unused "Just in Case" Code** - Violates YAGNI principle (Kent Beck) +## Type Boundaries -## Comment Writing Rules -- **Code-First Default**: Use names, types, and structure to show what the code does -- **Intent Focus**: Use comments only for why, limitations, edge cases, or public API contracts -- **History in Version Control**: Record development history in commits and PRs instead of code comments -- **Timeless**: Write only content that remains valid whenever read -- **Conciseness**: Keep explanations to necessary minimum +- Treat external, persisted, URL, and browser-storage input as untrusted until validated. +- Prefer `unknown`, generics, unions, and type guards over `any` or suppression. +- Keep public Props, request/response shapes, and serialized values aligned with governing contracts. +- Use assertions only when the invariant is established at the same boundary and cannot be expressed more safely. -## Type Safety +## React Boundaries -**Absolute Rule**: Use `unknown`, generics, unions, intersections, or validated assertions instead of `any`. `any` disables type checking and becomes a source of runtime errors. +- Match the repository's component, state, data-fetching, routing, styling, and test patterns. +- Keep one authoritative owner for state and preserve unidirectional updates. +- Place browser-only behavior behind the repository's client boundary when server/client components coexist. +- Guard asynchronous effects against stale results and post-unmount updates using the repository's established mechanism. +- Use class components only where the repository or framework requires them, such as an existing Error Boundary contract. -**any Type Alternatives (Priority Order)** -1. **unknown Type + Type Guards**: Use for validating external input (API responses, localStorage, URL parameters) -2. **Generics**: When type flexibility is needed -3. **Union Types / Intersection Types**: Combinations of multiple types -4. **Type Assertions (Last Resort)**: Only when type is certain +Do not introduce a state library, server-state library, component hierarchy, alias convention, memoization strategy, or code-splitting pattern merely because it is common elsewhere. -**Type Safety in Frontend Implementation** -- **React Props/State**: TypeScript manages types, unknown unnecessary -- **External API Responses**: Always receive as `unknown`, validate with type guards -- **localStorage/sessionStorage**: Treat as `unknown`, validate -- **URL Parameters**: Treat as `unknown`, validate -- **Form Input (Controlled Components)**: Type-safe with React synthetic events +## Environment and Security -**Type Safety in Data Flow** -- **Frontend to Backend**: Props/State (Type Guaranteed) to API Request (Serialization) -- **Backend to Frontend**: API Response (`unknown`) to Type Guard to State (Type Guaranteed) +- Read client environment values through the configured build-tool interface. +- Only expose variables explicitly intended for the client; never place secrets in frontend configuration or bundles. +- Surface missing required configuration as the governing contract specifies. +- Keep sensitive values out of UI errors and logs. -**Type Complexity Management** -- **Props Design**: - - Props count: 3-7 props ideal (consider component splitting if exceeds 10) - - Optional Props: 50% or less (consider default values or Context if excessive) - - Nesting: Up to 2 levels (flatten deeper structures) -- Type Assertions: Review design if used 3+ times -- **External API Types**: Relax constraints and define according to reality (convert appropriately internally) +## Performance -## Coding Conventions +Apply memoization, lazy loading, and bundle changes only when repository tooling, profiling, or a governing requirement supplies evidence. Verify the named metric or consumer-visible effect after the change. -**Component Design Criteria** -- **Function Components (Mandatory)**: Use function components for new and modified React components -- **Class Component Exception**: Retain or introduce a class component only when an existing or required Error Boundary needs it -- **Custom Hooks**: Standard pattern for logic reuse and dependency injection -- **Component Hierarchy**: Follow the project's existing component architecture. Use Atoms > Molecules > Organisms > Templates > Pages only when the project adopts Atomic Design. -- **Co-location**: Place tests, styles, and related files alongside components +## Completion Checks -**Server/Client Boundary (RSC frameworks only, such as Next.js App Router)** -- Default to server components for data fetching and rendering. Isolate interactivity behind a `"use client"` boundary at the smallest scope that needs it. -- Keep browser-only APIs such as `window`, `localStorage`, and event handlers inside client components. -- Skip this section for client-only SPAs with no server-component runtime. - -**State Management Patterns** -- **Local State**: `useState` for component-specific state -- **Context API**: For sharing state across component tree (theme, auth, etc.) -- **Custom Hooks**: Encapsulate state logic and side effects -- **Server State**: React Query or SWR for API data caching - -**Data Flow Principles** -- **Single Source of Truth**: Each piece of state has one authoritative source -- **Unidirectional Flow**: Data flows top-down via props -- **Immutable Updates**: Use immutable patterns for state updates - -**Function Design** -- **0-2 parameters maximum**: Use object for 3+ parameters - -**Props Design (Props-driven Approach)** -- Props are the interface: Define all necessary information as props -- Declare dependencies explicitly through props, hooks, or injected modules instead of relying on ambient global state -- Type-safe: Always define Props type explicitly - -**Environment Variables** -- **Use the build tool's env accessor**: read client-side env through the bundler's exposed accessor, such as Vite `import.meta.env` or Next.js/CRA prefixed `process.env`. -- **Only prefixed vars reach the client**: build tools expose only vars carrying their public prefix. Match the project's bundler, such as Vite `VITE_`, Next.js `NEXT_PUBLIC_`, or CRA `REACT_APP_`. -- Centrally manage environment variables through a typed configuration layer. -- Treat a missing required variable as a configuration error. Use a default only when requirements or a Design Doc explicitly define that fallback. - -**Security (Client-side Constraints)** -- **CRITICAL**: All frontend code is public and visible in browser -- **Never store secrets client-side**: No API keys, tokens, or secrets in environment variables -- Do not include `.env` files in Git -- Do not include sensitive information in error messages - -**Dependency Injection** -- **Custom Hooks for dependency injection**: Ensure testability and modularity - -**Asynchronous Processing** -- Promise Handling: Always use `async/await` -- Error Handling: Always handle with `try-catch` or Error Boundary -- Type Definition: Explicitly define return value types (e.g., `Promise`) -- Effect race/cleanup: guard `useEffect` data fetches against out-of-order responses and post-unmount state updates with `AbortController`, a mounted/stale flag, or a server-state library such as React Query or SWR. - -**Format Rules** -- Semicolon omission (follow project formatter settings) -- Types in `PascalCase`, variables/functions in `camelCase` -- Imports use absolute paths (`src/`) - -**Clean Code Principles** -- Delete unused code immediately -- Delete debug `console.log()` -- No commented-out code (manage history with version control) -- Comments explain intent, constraints, or contracts that code cannot express directly - -## Error Handling - -**Absolute Rule**: Handle every error explicitly with log output, recovery logic, or escalation appropriate to the failure mode. - -**Fail-Fast Principle**: Fail quickly on errors to prevent continued processing in invalid states - -**Layer-Specific Error Handling (React)** -- Error Boundary: Catch React component errors, display fallback UI -- Custom Hook: Detect business rule violations, propagate AppError as-is -- API Layer: Convert fetch errors to domain errors - -**Structured Logging and Sensitive Information Protection** -Never include sensitive information (password, token, apiKey, secret, creditCard) in logs - -**Asynchronous Error Handling in React** -- Error Boundary setup mandatory: Catch rendering errors -- Use try-catch with all async/await in event handlers -- Always log and re-throw errors or display error state - -## Refactoring Techniques - -**Basic Policy** -- Small Steps: Maintain always-working state through gradual improvements -- Safe Changes: Minimize the scope of changes at once -- Behavior Guarantee: Ensure existing behavior remains unchanged while proceeding - -**Implementation Procedure**: Understand Current State > Gradual Changes > Behavior Verification > Final Validation - -**Priority**: Duplicate Code Removal > Large Function Division > Complex Conditional Branch Simplification > Type Safety Improvement - -## Performance Optimization - -- Automatic memoization: when React Compiler is enabled, rely on it. Use manual `React.memo`, `useMemo`, or `useCallback` only for a profiler-confirmed bottleneck or stable reference identity required by third-party APIs or effect dependencies. -- State Optimization: Minimize re-renders with proper state structure -- Lazy Loading: Use React.lazy and Suspense for code splitting -- Bundle Size: Monitor with the build script against the project's budget - -## Non-functional Requirements - -- **Browser Compatibility**: Chrome/Firefox/Safari/Edge (latest 2 versions) -- **Rendering Time**: Within 5 seconds for major pages +- [ ] Project typecheck/build command passes +- [ ] No new `any`, suppression, or unchecked external input in changed code +- [ ] Props and serialized contracts match their source +- [ ] Async cleanup and race handling follow the repository pattern where applicable +- [ ] Performance changes have measured evidence diff --git a/.agents/skills/documentation-criteria/SKILL.md b/.agents/skills/documentation-criteria/SKILL.md index 7d85635..371bef5 100644 --- a/.agents/skills/documentation-criteria/SKILL.md +++ b/.agents/skills/documentation-criteria/SKILL.md @@ -53,7 +53,7 @@ description: "Documentation creation criteria for PRD, ADR, Design Doc, UI Spec, ### PRD (Product Requirements Document) **Purpose**: Define business requirements and user value -**Scope**: Business requirements, user value, success metrics, user stories, MoSCoW prioritization, MVP/Future phase separation, user journey diagram, scope boundary diagram, and acceptance criteria with sequential IDs (for example `AC-001`, `AC-002`, continuing across all requirements in the document) only. Technical implementation details belong in Design Doc, technical decision rationale in ADR, and implementation phases or task breakdown belong in Work Plan. +**Scope**: Business requirements, user value, success metrics, user stories, converged MVP requirements, Future/Out of Scope capabilities with reasons, user journey diagram, scope boundary diagram, and acceptance criteria with sequential IDs (for example `AC-001`, `AC-002`, continuing across all requirements in the document) only. Technical implementation details belong in Design Doc, technical decision rationale in ADR, and implementation phases or task breakdown belong in Work Plan. ### ADR (Architecture Decision Record) **Purpose**: Record technical decision rationale and background diff --git a/.agents/skills/documentation-criteria/references/plan-template.md b/.agents/skills/documentation-criteria/references/plan-template.md index 8c448c0..9883d11 100644 --- a/.agents/skills/documentation-criteria/references/plan-template.md +++ b/.agents/skills/documentation-criteria/references/plan-template.md @@ -95,7 +95,7 @@ The Traceability table records coverage. This table carries the required value v ## Failure Mode Checklist -Domain-independent failure categories this implementation must guard against. Enumerate all nine categories, mark which apply, and list a covering task for each that applies; keep category names generic and place project-specific detail in task descriptions or notes. +Domain-independent failure categories this implementation must guard against. Enumerate all ten categories, mark which apply, and list a covering task for each that applies; keep category names generic and place project-specific detail in task descriptions or notes. `missing-sort-key ordering` applies when a collection is sorted by a field or key that may be absent, null, derived, or conditionally omitted. Covering tasks must prove a deterministic fallback order for items lacking the sort key. @@ -110,6 +110,9 @@ Domain-independent failure categories this implementation must guard against. En | shared-state dependency | yes/no | | | rollback-only visibility | yes/no | | | missing-sort-key ordering | yes/no | | +| irreversible-operation | yes/no | | + +Set `irreversible-operation` to `yes` when an operation cannot be safely reversed or retried, and assign a covering task. ## UI Spec Component -> Task Mapping diff --git a/.agents/skills/documentation-criteria/references/prd-template.md b/.agents/skills/documentation-criteria/references/prd-template.md index fd257ab..75e2e11 100644 --- a/.agents/skills/documentation-criteria/references/prd-template.md +++ b/.agents/skills/documentation-criteria/references/prd-template.md @@ -27,7 +27,7 @@ So that [expected value/benefit] ## Functional Requirements -### Must Have (MVP) +### MVP Requirements - [ ] Requirement 1: [Detailed description] - AC-001: [Acceptance criteria - Given/When/Then format or measurable standard] - AC-002: [Acceptance criteria] @@ -36,15 +36,11 @@ So that [expected value/benefit] - [ ] Requirement 3: [Detailed description] - AC-004: [Acceptance criteria] -### Nice to Have -- [ ] Requirement 1: [Detailed description] - - AC-005: [Acceptance criteria - continue numbering across all requirements] -- [ ] Requirement 2: [Detailed description] - - AC-006: [Acceptance criteria] +### Future / Out of Scope -### Out of Scope -- Item 1: [Description and reason] -- Item 2: [Description and reason] +| Capability | Disposition | Reason | +|---|---|---| +| [Capability excluded during MVP convergence] | future / out-of-scope | [Why it is not required for the current value or obligations] | ## Non-Functional Requirements diff --git a/.agents/skills/documentation-criteria/references/task-template.md b/.agents/skills/documentation-criteria/references/task-template.md index eefdedc..b8c9340 100644 --- a/.agents/skills/documentation-criteria/references/task-template.md +++ b/.agents/skills/documentation-criteria/references/task-template.md @@ -13,6 +13,14 @@ Metadata: - [ ] [Implementation file path] - [ ] [Test file path] +## Hard Constraints + +| Protected condition | Allowed action | Source | +|---|---|---| +| [Data/state/contract condition that must remain true] | [What the implementation may do while preserving it] | [User request / approved governing document path (§ section) / named task dependency] | + +Include this section only for constraints with a listed source. Before escalation, record and use the smallest in-scope option satisfying the outcome and every constraint; escalate only the unmet item. + ## Investigation Targets Files to read before starting implementation. Use concrete file paths, optionally with a section/function hint: - [e.g., src/orders/checkout.ts (processOrder function)] diff --git a/.agents/skills/integration-e2e-testing/SKILL.md b/.agents/skills/integration-e2e-testing/SKILL.md index 236b64f..b4a2baf 100644 --- a/.agents/skills/integration-e2e-testing/SKILL.md +++ b/.agents/skills/integration-e2e-testing/SKILL.md @@ -176,6 +176,10 @@ The test runner or framework in the project determines the appropriate file exte | Reproducibility | Date/random dependency, varying results | | Readability | Test name doesn't match verification content | +### Route Parity for Shared Mutations + +When multiple routes reach the same mutation, compare validation, classification, resource bounds, and read/parse/mutation/reporting order. Each difference requires an authoritative requirement, design contract, or explicit test claim; otherwise require a test exposing the bypass or inconsistent outcome. + ## Quality Standards [MANDATORY] ### REQUIRED diff --git a/.agents/skills/llm-friendly-context/SKILL.md b/.agents/skills/llm-friendly-context/SKILL.md index c5cccfa..55187be 100644 --- a/.agents/skills/llm-friendly-context/SKILL.md +++ b/.agents/skills/llm-friendly-context/SKILL.md @@ -16,6 +16,7 @@ The goal is stable downstream execution. The next agent should know the target a 1. **Use positive, executable instructions** - State the action the next agent should perform. - Convert quality policies into observable acceptance criteria. + - Keep a prohibition only when it protects an irreversible boundary or shipped contract. Name the protected condition and the allowed action. - Example: `Preserve existing public API behavior across the documented compatibility cases.` 2. **Make vague instructions concrete** @@ -29,10 +30,12 @@ The goal is stable downstream execution. The next agent should know the target a 4. **Provide necessary context** - Include purpose, source artifacts, hard constraints, accepted decisions, and unresolved conditions. - Prefer concrete file paths and section hints over broad module names. + - Follow references only while they can change an in-scope decision, action, or verification result. 5. **Decompose complex work into verifiable steps** - Split work with 3+ objectives or sequential dependencies into ordered steps. - Each step needs a checkpoint stating the evidence that proves completion. + - In Codex workflows, use `update_plan` as the state machine: keep one step `in_progress`, complete it only after its checkpoint evidence exists, then advance. 6. **Permit uncertainty explicitly** - If source material is missing, contradictory, or unverifiable, state the uncertainty and required escalation. @@ -68,6 +71,8 @@ Before sending a prompt or artifact to another agent, verify: - [ ] Output format or expected status fields are specified. - [ ] Success criteria are observable. - [ ] Ambiguous expressions have been rewritten or marked as unresolved. +- [ ] Every retained prohibition names the protected condition and allowed alternative. +- [ ] Sequential work exposes one current state and does not advance without prerequisite evidence. - [ ] The next agent can complete its scope through explicit choices, decision rules, or blocking unresolved items. ## Generated Artifact Checklist @@ -77,5 +82,6 @@ Before writing or finalizing a generated document: - [ ] Each requirement, claim, task, test skeleton, or review finding has enough source context to trace why it exists. - [ ] Every executable instruction names the target, action, and expected result. - [ ] Verification steps say what to run or observe and what result proves success. +- [ ] Every retained prohibition names the protected condition and allowed alternative. - [ ] Derived artifacts preserve copied decisions with the same wording and meaning as their source artifacts. - [ ] Blocking missing information records the missing input and escalation condition. diff --git a/.agents/skills/recipe-add-integration-tests/SKILL.md b/.agents/skills/recipe-add-integration-tests/SKILL.md index 04e74dc..4f8043a 100644 --- a/.agents/skills/recipe-add-integration-tests/SKILL.md +++ b/.agents/skills/recipe-add-integration-tests/SKILL.md @@ -18,7 +18,7 @@ description: "Add integration/E2E tests to existing codebase using Design Docs." **Core Identity**: "I am not a worker. I am an orchestrator." -**First Action**: Register Steps 0-8 before any execution. +**First Action**: Call `update_plan` with first "Map active rules to this task", Steps 0-8, and final "Verify outputs and rule adherence" before execution. While work remains, keep exactly one step `in_progress`; after final verification evidence exists, mark every step `completed`. **Why Spawn**: Orchestrator's context is shared across all steps. Direct implementation consumes context needed for review and quality check phases. Task files create context boundaries. Subagents work in isolated context. @@ -124,6 +124,8 @@ Implement test cases defined in skeleton files. ### Step 4: Test Implementation +Record the current revision as `diffBase` before invoking the executor for each task. + For each task file from Step 3, invoke task-executor routed by filename pattern: - `*-backend-task-*` -> Spawn `task-executor` - `*-frontend-task-*` -> Spawn `task-executor-frontend` @@ -131,13 +133,15 @@ For each task file from Step 3, invoke task-executor routed by filename pattern: Execute one task file at a time through Steps 4 -> 5 -> 6 -> 7 before starting the next. -**Expected output**: `status`, `testsAdded` +**Expected output**: `status`, `filesModified`, `testsAdded` ### Step 5: Test Review -Spawn integration-test-reviewer agent: "Review test quality. Test files: [paths from Step 4 testsAdded]. Skeleton files: [layer-specific paths from Step 2 generatedFiles matching current task's layer]." +Use the executor's `filesModified` as the task write set. +Spawn integration-test-reviewer with `changedTestFiles: [integration/E2E test paths from filesModified]`, `diffBase`, `skeletonFiles: [layer-specific paths from Step 2]`, and `taskFile`. +Keep `testsAdded` as reporting metadata only. -**Expected output**: `status` (approved/needs_revision), `requiredFixes` +**Expected output**: `status` (approved/needs_revision/blocked), `reviewBasis`, `requiredFixes`. Escalate `blocked` or an unrecognized status. ### Step 6: Apply Review Fixes @@ -150,7 +154,7 @@ Check Step 5 result: Spawn quality-fixer routed by task filename pattern: - `*-backend-task-*` -> Spawn `quality-fixer` - `*-frontend-task-*` -> Spawn `quality-fixer-frontend` -- Prompt: "Final quality assurance for test files added in this workflow. Task file: [current task file]. filesModified: [Step 4 testsAdded]. Use these files as the stub-detection scope. Run all tests and verify coverage." +- Inputs: `task_file: [current task file]` and Step 4 `filesModified`. **Expected output**: `status` (`stub_detected`/`approved`/`blocked`) diff --git a/.agents/skills/recipe-build/SKILL.md b/.agents/skills/recipe-build/SKILL.md index 36be348..3261fca 100644 --- a/.agents/skills/recipe-build/SKILL.md +++ b/.agents/skills/recipe-build/SKILL.md @@ -110,16 +110,19 @@ Recompute the Consumed Task Set and verify it is non-empty. **MANDATORY EXECUTION CYCLE**: `task-executor -> escalation check -> quality-fixer -> commit` +Before entering the loop, call `update_plan` once with first "Map active rules to this task", one step per task cycle, and final "Verify outputs and rule adherence". While work remains, keep exactly one step `in_progress`; after final verification evidence exists, mark every step `completed`. Do not recreate the plan inside the loop. + For EACH task, YOU MUST: -1. **Register tasks**: Register work steps. Always include: first "Confirm skill constraints", final "Verify skill fidelity" +1. **Capture diff base**: Record the current revision as `diffBase`. 2. **Spawn task-executor agent**: "Execute the task implementation for [task-file-path]" 3. **CHECK task-executor response**: - `status: "escalation_needed"` or `"blocked"` -> STOP and escalate to user - - `requiresTestReview` is `true` -> Spawn integration-test-reviewer agent: "Review integration tests in [test-files]" + - `requiresTestReview` is `true` -> Spawn integration-test-reviewer agent with `changedTestFiles: [integration/E2E paths from filesModified]`, `diffBase`, and `taskFile: [task-file-path]`; when matching integration/E2E skeleton paths are available from acceptance-test-generator output or task/work-plan references, pass only those paths as `skeletonFiles` - `needs_revision` -> Return to step 2 with `requiredFixes` - `approved` -> Proceed to step 4 + - `blocked` or unrecognized status -> STOP and escalate to user - `readyForQualityCheck: true` -> Proceed to step 4 -4. **Spawn quality-fixer agent**: "Execute all quality checks and fixes. Task file: [task-file-path]. The task file path above is also the `task_file` input. Read its `Quality Assurance Mechanisms` section as supplementary quality-check hints. filesModified: [task-executor response filesModified]. Use these files as the stub-detection scope." +4. **Spawn quality-fixer agent** with `task_file` and executor `filesModified`. 5. **CHECK quality-fixer response**: - `status: "stub_detected"` -> Return to step 2 with `stubFindings` - `status: "blocked"` -> STOP and escalate to user @@ -144,20 +147,21 @@ VERIFY approval status before proceeding. Once confirmed, INITIATE autonomous ex ## Post-Implementation Verification (After All Tasks Complete) -After all task cycles finish, collect all `filesModified` from every task-executor response (deduplicated), then run both verification agents before the completion report: -1. Spawn code-verifier agent: "Verify implementation consistency against the Design Doc. `doc_type: design-doc`. `document_path`: [path]. `code_paths`: [collected filesModified list]. Work Plan Review Scope: [Review Scope value from the active work plan, used only to confirm the collected file set is complete]." -2. Spawn security-reviewer agent: "Design Doc: [path]. Implementation files: [collected filesModified list]. Review security compliance." +After all task cycles finish, collect all `filesModified` from every task-executor response (deduplicated). Resolve `governingDocuments` to the active Design Doc(s), or to the active Work Plan when no Design Doc governs the change, then run both verification agents before the completion report: +1. Spawn code-verifier for each governing document with its matching `doc_type`, `document_path`, and the collected `code_paths`. +2. Spawn security-reviewer with typed `governingDocuments: [{type, path}]` and `implementationFiles: [collected filesModified list]`. 3. Consolidate results: - code-verifier passes when `summary.status` is `consistent` or `mostly_consistent` - code-verifier fails when `summary.status` is `needs_review` or `inconsistent` + - code-verifier `blocked` or unrecognized status -> Escalate to user - security-reviewer passes when `status` is `approved` or `approved_with_notes` - security-reviewer fails when `status` is `needs_revision` - security-reviewer `blocked` -> Escalate to user 4. If either verifier fails: - - Create a single fix task covering verifier discrepancies and security requiredFixes - - Spawn task-executor with that consolidated task - - Spawn quality-fixer - - Re-run only the verifier(s) that failed + - Create one ephemeral fix task per executor route covering verifier discrepancies and security requiredFixes + - Pass each exact task path to task-executor and then quality-fixer + - Re-run both code-verifier and security-reviewer after any fix + - Delete the ephemeral task files only after both verifiers pass - Maximum retry count is 1 verification fix cycle; if any failed verifier still fails after re-run, escalate to the user 5. If both verifiers pass -> Proceed to completion report diff --git a/.agents/skills/recipe-design/SKILL.md b/.agents/skills/recipe-design/SKILL.md index 415b98a..a0e9cce 100644 --- a/.agents/skills/recipe-design/SKILL.md +++ b/.agents/skills/recipe-design/SKILL.md @@ -17,6 +17,8 @@ description: "Execute from codebase-scoped analysis to design document creation. **Core Identity**: "I am not a worker. I am an orchestrator." +**Execution Plan Gate**: Call `update_plan` with first "Map active rules to this task", the applicable design steps, and final "Verify outputs and rule adherence" before scope bootstrap. While work remains, keep exactly one step `in_progress`; after final verification evidence exists, mark every step `completed`. + **Execution Protocol**: 1. **Spawn agents for analysis and document work** -- your role is to invoke sub-agents, pass data between them, and report results. The Step 1 scope bootstrap is an orchestrator-local pass limited to locating seed files. 2. **Run the design flow below in order**: @@ -128,7 +130,7 @@ Skip this step for ADR-only output. ### Step 6: Document Review Review each created document: - ADR: Spawn document-reviewer agent: "Review the ADR for consistency and completeness. doc_type: ADR. target: [ADR path]. codebase_analysis: [output from Step 2]." -- Design Doc: Spawn document-reviewer agent: "Review the Design Doc for consistency, completeness, and adopted design validity. doc_type: DesignDoc. target: [Design Doc path]. requirements_verbatim: [original user requirements]. confirmed_requirement_context: [complete confirmed requirement context from Step 3]. codebase_analysis: [output from Step 2]. code_verification: [output from Step 5]." +- Design Doc: Spawn document-reviewer agent: "Review the Design Doc for consistency, completeness, and adopted design validity. doc_type: DesignDoc. review_context: creation. target: [Design Doc path]. requirements_verbatim: [original user requirements]. confirmed_requirement_context: [complete confirmed requirement context from Step 3]. codebase_analysis: [output from Step 2]. code_verification: [output from Step 5]." ### Step 7: Consistency Verification For Design Docs only, spawn design-sync agent: "Verify consistency of the design document with other existing design documents and project constraints." diff --git a/.agents/skills/recipe-diagnose/SKILL.md b/.agents/skills/recipe-diagnose/SKILL.md index eaf32c5..3b551d5 100644 --- a/.agents/skills/recipe-diagnose/SKILL.md +++ b/.agents/skills/recipe-diagnose/SKILL.md @@ -26,7 +26,7 @@ Target problem: $ARGUMENTS Orchestrator spawns sub-agents and passes structured data between them. -**Task Registration**: Register execution steps and proceed systematically. Track status for each step. +**Execution Plan Gate**: Before substantive work, call `update_plan` with first "Map active rules to this task", then problem structuring, investigation, verification, and solution, and final "Verify outputs and rule adherence". While work remains, keep exactly one step `in_progress`; after final report evidence exists, mark every step `completed`. ## Step 0: Problem Structuring (Before spawning investigator) @@ -82,7 +82,7 @@ coverage sufficient -> Report ## Execution Steps -Register the following and execute: +Execute the registered steps: ### Step 1: Investigation (investigator) diff --git a/.agents/skills/recipe-front-adjust/SKILL.md b/.agents/skills/recipe-front-adjust/SKILL.md index 954006e..78d6119 100644 --- a/.agents/skills/recipe-front-adjust/SKILL.md +++ b/.agents/skills/recipe-front-adjust/SKILL.md @@ -18,6 +18,8 @@ description: "Adjust an implemented UI with external resource context, focused w **Core Identity**: "I am a guided executor. I run the UI adjustment and verification loop in the parent session." +**Execution Plan Gate**: Call `update_plan` with first "Map active rules to this task", the applicable adjustment steps, and final "Verify outputs and rule adherence" before external-resource hearing. While work remains, keep exactly one step `in_progress`; after final verification evidence exists, mark every step `completed`. + **Execution Protocol**: 1. Delegate bounded one-shot work to `ui-analyzer`, `work-planner`, and `quality-fixer-frontend`. 2. Run user dialogue, write-set confirmation, edits, and verification in the parent session. diff --git a/.agents/skills/recipe-front-build/SKILL.md b/.agents/skills/recipe-front-build/SKILL.md index e5b968c..884e01f 100644 --- a/.agents/skills/recipe-front-build/SKILL.md +++ b/.agents/skills/recipe-front-build/SKILL.md @@ -113,21 +113,24 @@ Recompute the Consumed Task Set and verify it is non-empty. ### Structured Response Specification Each sub-agent responds in JSON format: - **task-executor-frontend**: status, filesModified, testsAdded, requiresTestReview, readyForQualityCheck -- **integration-test-reviewer**: status (approved/needs_revision/blocked), requiredFixes +- **integration-test-reviewer**: status (approved/needs_revision/blocked), reviewBasis, requiredFixes - **quality-fixer-frontend**: status, checksPerformed, fixesApplied ### Execution Flow for Each Task +Before entering the loop, call `update_plan` once with first "Map active rules to this task", one step per task cycle, and final "Verify outputs and rule adherence". While work remains, keep exactly one step `in_progress`; after final verification evidence exists, mark every step `completed`. Do not recreate the plan inside the loop. + For EACH task, YOU MUST: -1. **Register tasks**: Register work steps. Always include: first "Confirm skill constraints", final "Verify skill fidelity" +1. **Capture diff base**: Record the current revision as `diffBase`. 2. **Spawn task-executor-frontend agent**: "Task file: docs/plans/tasks/[filename].md Execute frontend implementation" 3. **CHECK task-executor-frontend response**: - `status: "escalation_needed"` or `"blocked"` -> STOP and escalate to user - - `requiresTestReview` is `true` -> Spawn integration-test-reviewer agent: "Review integration tests in [test-files]" + - `requiresTestReview` is `true` -> Spawn integration-test-reviewer with `changedTestFiles: [integration/E2E paths from filesModified]`, `diffBase`, and `taskFile`; when matching integration/E2E skeleton paths are available from acceptance-test-generator output or task/work-plan references, pass only those paths as `skeletonFiles` - `needs_revision` -> Return to step 2 with `requiredFixes` - `approved` -> Proceed to step 4 + - `blocked` or unrecognized status -> STOP and escalate to user - `readyForQualityCheck: true` -> Proceed to step 4 -4. **Spawn quality-fixer-frontend agent**: "Execute all frontend quality checks and fixes. Task file: docs/plans/tasks/[filename].md. The task file path above is also the `task_file` input. Read its `Quality Assurance Mechanisms` section as supplementary quality-check hints. filesModified: [task-executor-frontend response filesModified]. Use these files as the stub-detection scope." +4. **Spawn quality-fixer-frontend agent** with `task_file` and executor `filesModified`. 5. **CHECK quality-fixer-frontend response**: - `status: "stub_detected"` -> Return to step 2 with `stubFindings` - `status: "blocked"` -> STOP and escalate to user @@ -152,20 +155,21 @@ VERIFY approval status before proceeding. Once confirmed, INITIATE autonomous ex ## Post-Implementation Verification (After All Tasks Complete) -After all task cycles finish, collect all `filesModified` from every task-executor-frontend response (deduplicated), then run both verification agents before the completion report: -1. Spawn code-verifier agent: "Verify implementation consistency against the Design Doc. `doc_type: design-doc`. `document_path`: [path]. `code_paths`: [collected filesModified list]. Work Plan Review Scope: [Review Scope value from the active work plan, used only to confirm the collected file set is complete]." -2. Spawn security-reviewer agent: "Design Doc: [path]. Implementation files: [collected filesModified list]. Review security compliance." +After all task cycles finish, collect all `filesModified` from every task-executor-frontend response (deduplicated). Resolve `governingDocuments` to the active Design Doc(s), or to the active Work Plan when no Design Doc governs the change, then run both verification agents before the completion report: +1. Spawn code-verifier for each governing document with its matching `doc_type`, `document_path`, and the collected `code_paths`. +2. Spawn security-reviewer with typed `governingDocuments: [{type, path}]` and `implementationFiles: [collected filesModified list]`. 3. Consolidate results: - code-verifier passes when `summary.status` is `consistent` or `mostly_consistent` - code-verifier fails when `summary.status` is `needs_review` or `inconsistent` + - code-verifier `blocked` or unrecognized status -> Escalate to user - security-reviewer passes when `status` is `approved` or `approved_with_notes` - security-reviewer fails when `status` is `needs_revision` - security-reviewer `blocked` -> Escalate to user 4. If either verifier fails: - - Create a single fix task covering verifier discrepancies and security requiredFixes - - Spawn task-executor-frontend with that consolidated task - - Spawn quality-fixer-frontend - - Re-run only the verifier(s) that failed + - Create one ephemeral frontend fix task covering verifier discrepancies and security requiredFixes + - Pass its exact path to task-executor-frontend and then quality-fixer-frontend + - Re-run both code-verifier and security-reviewer after any fix + - Delete the ephemeral task file only after both verifiers pass - Maximum retry count is 1 verification fix cycle; if any failed verifier still fails after re-run, escalate to the user 5. If both verifiers pass -> Proceed to completion report diff --git a/.agents/skills/recipe-front-design/SKILL.md b/.agents/skills/recipe-front-design/SKILL.md index b25d285..cfc06d6 100644 --- a/.agents/skills/recipe-front-design/SKILL.md +++ b/.agents/skills/recipe-front-design/SKILL.md @@ -18,6 +18,8 @@ description: "Execute from codebase-scoped analysis to frontend design document **Core Identity**: "I am not a worker. I am an orchestrator." +**Execution Plan Gate**: Call `update_plan` with first "Map active rules to this task", the frontend design steps, and final "Verify outputs and rule adherence" before scope bootstrap. While work remains, keep exactly one step `in_progress`; after final verification evidence exists, mark every step `completed`. + **Execution Method**: - Scope bootstrap -> performed by the orchestrator as a file-location pass - Codebase analysis -> performed by codebase-analyzer @@ -151,7 +153,7 @@ Create appropriate design documents according to confirmed scope and scale: - For Design Docs only, spawn code-verifier agent: "Verify Design Doc against code. doc_type: design-doc. document_path: [document path]. verbose: false." - Review each created document: - ADR: Spawn document-reviewer agent: "Review the ADR for consistency and completeness. doc_type: ADR. target: [ADR path]. mode: composite. codebase_analysis: [JSON from codebase-analyzer]. ui_analysis: [JSON from ui-analyzer, when available]." - - Design Doc: Spawn document-reviewer agent: "Review the Design Doc for consistency, completeness, and adopted design validity. doc_type: DesignDoc. target: [Design Doc path]. mode: composite. requirements_verbatim: [original user requirements]. confirmed_requirement_context: [complete confirmed requirement context from Step 3]. codebase_analysis: [JSON from codebase-analyzer]. ui_analysis: [JSON from ui-analyzer]. code_verification: [JSON from code-verifier]." + - Design Doc: Spawn document-reviewer agent: "Review the Design Doc for consistency, completeness, and adopted design validity. doc_type: DesignDoc. review_context: creation. target: [Design Doc path]. mode: composite. requirements_verbatim: [original user requirements]. confirmed_requirement_context: [complete confirmed requirement context from Step 3]. codebase_analysis: [JSON from codebase-analyzer]. ui_analysis: [JSON from ui-analyzer]. code_verification: [JSON from code-verifier]." **[STOP -- BLOCKING]** Present the created design documents and any recorded trade-offs, then obtain user approval. **CANNOT proceed until user explicitly approves the design document.** diff --git a/.agents/skills/recipe-front-plan/SKILL.md b/.agents/skills/recipe-front-plan/SKILL.md index d112c96..9cf1a23 100644 --- a/.agents/skills/recipe-front-plan/SKILL.md +++ b/.agents/skills/recipe-front-plan/SKILL.md @@ -18,6 +18,8 @@ description: "Create frontend work plan from design document with test skeleton **Core Identity**: "I am not a worker. I am an orchestrator." +**Execution Plan Gate**: Call `update_plan` with first "Map active rules to this task", Steps 1-5, and final "Verify outputs and rule adherence" before document selection. While work remains, keep exactly one step `in_progress`; after final verification evidence exists, mark every step `completed`. + **Execution Method**: - Test skeleton generation -> performed by acceptance-test-generator - Work plan creation -> performed by work-planner diff --git a/.agents/skills/recipe-front-review/SKILL.md b/.agents/skills/recipe-front-review/SKILL.md index 2be0c87..f4298eb 100644 --- a/.agents/skills/recipe-front-review/SKILL.md +++ b/.agents/skills/recipe-front-review/SKILL.md @@ -43,7 +43,7 @@ Spawn code-reviewer agent: "Validate Design Doc compliance for [design-doc-path] **Store output as**: `$STEP_2_OUTPUT` ### 3. Execute security-reviewer -Spawn security-reviewer agent: "Design Doc: [path]. Implementation files: [file list from git diff in Step 1]. Review security compliance." +Spawn security-reviewer with `governingDocuments: [{type: "design-doc", path: [path]}]` and `implementationFiles: [file list from git diff in Step 1]`. **Store output as**: `$STEP_3_OUTPUT` and `$STEP_1_FILES` (the initial file list) @@ -111,12 +111,14 @@ If all findings are skipped: Skip fix steps, proceed to Final Report. ## Pre-fix Metacognition 1. **Spawn rule-advisor agent**: "Analyze fixes needed. Code issues: $STEP_2_OUTPUT. Security findings: $STEP_3_OUTPUT. Determine root solutions vs symptomatic treatments." -2. **Design-side update**: If any finding is routed to `d`, spawn technical-designer-frontend in update mode, then document-reviewer, then design-sync when multiple Design Docs exist. If both `d` and `c` routes exist, re-evaluate `c` findings against the updated Design Doc and drop any now satisfied. -3. **Register tasks**: Register work steps. Always include: first "Confirm skill constraints", final "Verify skill fidelity". Create task file -> `docs/plans/tasks/review-fixes-YYYYMMDD.md`. Include only code compliance issues and security requiredFixes routed to `c`. +2. **Design-side update**: If any finding is routed to `d`, spawn technical-designer-frontend in update mode, then document-reviewer with `doc_type: DesignDoc` and `review_context: update`, then design-sync when multiple Design Docs exist. If both `d` and `c` routes exist, re-evaluate `c` findings against the updated Design Doc and drop any now satisfied. +3. **Plan fixes**: Call `update_plan` once for the approved fix flow, with first "Map active rules to this task" and final "Verify outputs and rule adherence". While work remains, keep exactly one step `in_progress`; after final verification evidence exists, mark every step `completed`. Create task file -> `docs/plans/tasks/review-fixes-YYYYMMDD.md`. Include only code compliance issues and security requiredFixes routed to `c`. 4. **Spawn task-executor-frontend agent**: "Execute staged auto-fixes for [task-file-path]. Stop at 5 files." -5. **Spawn quality-fixer-frontend agent**: "Execute all frontend quality checks and confirm quality gate passage" +5. **Spawn quality-fixer-frontend** with `task_file: [task-file-path]` and executor `filesModified`. 6. **Re-validate code-reviewer**: Spawn code-reviewer agent: "Re-validate compliance for [design-doc-path]. Prior issues: $STEP_2_OUTPUT. Measure improvement." -7. **Re-validate security-reviewer** (only if security fixes were applied): Spawn security-reviewer agent: "Re-validate security after fixes. Prior findings: $STEP_3_OUTPUT. Design Doc: [path]. Implementation files: [union of $STEP_1_FILES and task-executor-frontend filesModified from step 4, deduplicated]." +7. **Re-validate security-reviewer**: Spawn security-reviewer with prior findings, `governingDocuments: [{type: "design-doc", path: [path]}]`, and `implementationFiles: [union of $STEP_1_FILES and task-executor-frontend filesModified from step 4, deduplicated]`. + +After any code fix, both review agents must re-run. Delete the task file only after both pass. ENFORCEMENT: Auto-fixes MUST go through quality-fixer-frontend before re-validation. Skipping quality checks invalidates fixes. diff --git a/.agents/skills/recipe-fullstack-build/SKILL.md b/.agents/skills/recipe-fullstack-build/SKILL.md index 01c135e..9a658c1 100644 --- a/.agents/skills/recipe-fullstack-build/SKILL.md +++ b/.agents/skills/recipe-fullstack-build/SKILL.md @@ -128,16 +128,19 @@ Recompute the Consumed Task Set and verify it is non-empty. **MANDATORY EXECUTION CYCLE**: `executor -> escalation check -> quality-fixer -> commit` +Before entering the loop, call `update_plan` once with first "Map active rules to this task", one step per task cycle, and final "Verify outputs and rule adherence". While work remains, keep exactly one step `in_progress`; after final verification evidence exists, mark every step `completed`. Do not recreate the plan inside the loop. + For EACH task, YOU MUST: -1. **Register tasks**: Register work steps. Always include: first "Confirm skill constraints", final "Verify skill fidelity" +1. **Capture diff base**: Record the current revision as `diffBase`. 2. **Spawn task-executor or task-executor-frontend agent** (per routing table): "Execute the task implementation for [task-file-path]" 3. **CHECK executor response**: - `status: "escalation_needed"` or `"blocked"` -> STOP and escalate to user - - `requiresTestReview` is `true` -> Spawn integration-test-reviewer agent: "Review integration tests in [test-files]" + - `requiresTestReview` is `true` -> Spawn integration-test-reviewer with `changedTestFiles: [integration/E2E paths from filesModified]`, `diffBase`, and `taskFile`; when matching integration/E2E skeleton paths are available from acceptance-test-generator output or task/work-plan references, pass only those paths as `skeletonFiles` - `needs_revision` -> Return to step 2 with `requiredFixes` - `approved` -> Proceed to step 4 + - `blocked` or unrecognized status -> STOP and escalate to user - `readyForQualityCheck: true` -> Proceed to step 4 -4. **Spawn quality-fixer agent** (layer-appropriate per routing table): "Execute all quality checks and fixes. Task file: [task-file-path]. The task file path above is also the `task_file` input. Read its `Quality Assurance Mechanisms` section as supplementary quality-check hints. filesModified: [executor response filesModified]. Use these files as the stub-detection scope." +4. **Spawn quality-fixer agent** (layer-appropriate per routing table) with `task_file` and executor `filesModified`. 5. **CHECK quality-fixer response**: - `status: "stub_detected"` -> Return to step 2 with `stubFindings` - `status: "blocked"` -> STOP and escalate to user @@ -162,20 +165,21 @@ VERIFY approval status before proceeding. Once confirmed, INITIATE autonomous ex ## Post-Implementation Verification (After All Tasks Complete) -After all task cycles finish, collect all `filesModified` from every task-executor/task-executor-frontend response (deduplicated), then run both verification agents before the completion report: -1. Spawn code-verifier once per Design Doc: "Verify implementation consistency against the Design Doc. `doc_type: design-doc`. `document_path`: [single design doc path]. `code_paths`: [collected filesModified list]. Work Plan Review Scope: [Review Scope value from the active work plan, used only to confirm the collected file set is complete]." -2. Spawn security-reviewer agent: "Design Doc: [path(s)]. Implementation files: [collected filesModified list]. Review security compliance." +After all task cycles finish, collect all `filesModified` from every task-executor/task-executor-frontend response (deduplicated). Resolve `governingDocuments` to the active Design Docs, or to the active Work Plan when no Design Doc governs the change, then run both verification agents before the completion report: +1. Spawn code-verifier once per governing document with its matching `doc_type`, `document_path`, and the collected `code_paths`. +2. Spawn security-reviewer with typed `governingDocuments: [{type, path}]` and `implementationFiles: [collected filesModified list]`. 3. Consolidate results: - each code-verifier run passes when `summary.status` is `consistent` or `mostly_consistent` - a code-verifier run fails when `summary.status` is `needs_review` or `inconsistent` + - code-verifier `blocked` or unrecognized status -> Escalate to user - security-reviewer passes when `status` is `approved` or `approved_with_notes` - security-reviewer fails when `status` is `needs_revision` - security-reviewer `blocked` -> Escalate to user 4. If any verifier fails: - - Create a single fix task covering verifier discrepancies and security requiredFixes - - Spawn the layer-appropriate task-executor - - Spawn the layer-appropriate quality-fixer - - Re-run only the verifier(s) that failed + - Create one ephemeral fix task per executor route covering verifier discrepancies and security requiredFixes + - Pass each exact task path to the layer-appropriate task-executor and then quality-fixer + - Re-run all code-verifier runs and security-reviewer after any fix + - Delete the ephemeral task files only after all verifiers pass - Maximum retry count is 1 verification fix cycle; if any failed verifier still fails after re-run, escalate to the user 5. If all verifiers pass -> Proceed to completion report diff --git a/.agents/skills/recipe-fullstack-implement/SKILL.md b/.agents/skills/recipe-fullstack-implement/SKILL.md index 1e92002..308a02c 100644 --- a/.agents/skills/recipe-fullstack-implement/SKILL.md +++ b/.agents/skills/recipe-fullstack-implement/SKILL.md @@ -74,11 +74,14 @@ All stop points defined in monorepo-flow.md MUST be respected. ### 5. Register All Flow Steps (MANDATORY) -**After scale determination, register all steps of the monorepo-flow.md**: -- First task: "Confirm skill constraints" -- Register each step as individual task +**After scale determination, call `update_plan` once for all applicable monorepo-flow.md steps**: +- First task: "Map active rules to this task" +- Final task: "Verify outputs and rule adherence" +- Register each applicable flow step once - Mark currently executing step as in_progress -- **Complete task registration before spawning subagents** +- While work remains, keep exactly one step `in_progress`; complete it only after evidence is recorded and prerequisites for the next step are satisfied +- After final verification evidence exists, mark every step `completed` +- **Register the complete plan before spawning subagents** ## After requirement-analyzer [Stop] @@ -133,28 +136,30 @@ Before executing task files, execute the Implementation Readiness Preflight Proc ``` **Rules**: -1. Execute ONE task completely before starting next (each task goes through the full 4-step cycle individually, using the correct executor per filename pattern) +1. Execute ONE task completely before starting next; capture `diffBase` before its executor call 2. Check executor status before quality-fixer (escalation check) -3. Quality-fixer MUST run after each executor (no skipping), MUST receive the executor `filesModified` list as stub-detection scope, and MUST receive the current task file as the `task_file` input so it reads the task file's `Quality Assurance Mechanisms` section as supplementary quality-check hints -4. If quality-fixer returns `status: "stub_detected"`, route the task back to the same executor with `stubFindings` -5. Commit MUST execute only when quality-fixer returns `status: "approved"` (do not defer to end) +3. When `requiresTestReview` is true, integration-test-reviewer receives changed integration/E2E paths from `filesModified`, `diffBase`, and `taskFile`; when matching integration/E2E skeleton paths are available from acceptance-test-generator output or task/work-plan references, pass only those paths as `skeletonFiles`; `blocked` or unrecognized status escalates to the user +4. Quality-fixer MUST run after each executor with `filesModified` and `task_file` +5. If quality-fixer returns `status: "stub_detected"`, route the task back to the same executor with `stubFindings` +6. Commit MUST execute only when quality-fixer returns `status: "approved"` (do not defer to end) ### Post-Implementation Verification (After All Tasks Complete) -After all task cycles finish, collect all `filesModified` from every task-executor/task-executor-frontend response (deduplicated), then run both verification agents before the completion report: -1. Spawn code-verifier once per Design Doc: "Verify implementation consistency against the Design Doc. `doc_type: design-doc`. `document_path`: [single design doc path]. `code_paths`: [collected filesModified list]." -2. Spawn security-reviewer agent: "Design Doc: [path(s)]. Implementation files: [collected filesModified list]. Review security compliance." +After all task cycles finish, collect all `filesModified` from every task-executor/task-executor-frontend response (deduplicated). Resolve governing documents to Design Docs, or the Work Plan when no Design Doc governs the change: +1. Spawn code-verifier once per governing document with matching `doc_type`, `document_path`, and collected `code_paths`. +2. Spawn security-reviewer with typed `governingDocuments: [{type, path}]` and `implementationFiles`. 3. Consolidate results: - each code-verifier run passes when `summary.status` is `consistent` or `mostly_consistent` - a code-verifier run fails when `summary.status` is `needs_review` or `inconsistent` + - code-verifier `blocked` or unrecognized status -> Escalate to user - security-reviewer passes when `status` is `approved` or `approved_with_notes` - security-reviewer fails when `status` is `needs_revision` - security-reviewer `blocked` -> Escalate to user 4. If any verifier fails: - - Create a single fix task covering verifier discrepancies and security requiredFixes - - Spawn the layer-appropriate task-executor - - Spawn the layer-appropriate quality-fixer - - Re-run only the verifier(s) that failed + - Create one ephemeral fix task per executor route covering verifier discrepancies and security requiredFixes + - Pass each exact task path through the layer-appropriate executor and quality-fixer + - Re-run all code-verifier runs and security-reviewer after any fix + - Delete ephemeral task files only after all verifiers pass - Maximum retry count is 1 verification fix cycle; if any failed verifier still fails after re-run, escalate to the user 5. If all verifiers pass -> Proceed to completion report diff --git a/.agents/skills/recipe-implement/SKILL.md b/.agents/skills/recipe-implement/SKILL.md index 5c80263..ec2cac6 100644 --- a/.agents/skills/recipe-implement/SKILL.md +++ b/.agents/skills/recipe-implement/SKILL.md @@ -108,14 +108,17 @@ Before executing task files, read the associated work plan header and apply the ``` **Per-task cycle** (complete each task before starting next): -1. Spawn task-executor (or task-executor-frontend) agent: "Implement task [task-file-path]" +Before the first task, call `update_plan` once with first "Map active rules to this task", one step per task cycle, and final "Verify outputs and rule adherence". While work remains, keep exactly one step `in_progress`; after final verification evidence exists, mark every step `completed`. + +1. Record the current revision as `diffBase`, then spawn task-executor (or task-executor-frontend): "Implement task [task-file-path]" 2. Check task-executor response: - `status: escalation_needed` or `blocked` -> Escalate to user - - `requiresTestReview` is `true` -> Spawn integration-test-reviewer agent + - `requiresTestReview` is `true` -> Spawn integration-test-reviewer with changed integration/E2E paths from `filesModified`, `diffBase`, and `taskFile`; when matching integration/E2E skeleton paths are available from acceptance-test-generator output or task/work-plan references, pass only those paths as `skeletonFiles` - `needs_revision` -> Return to step 1 with `requiredFixes` - `approved` -> Proceed to step 3 + - `blocked` or unrecognized status -> Escalate to user - Otherwise -> Proceed to step 3 -3. Spawn quality-fixer (or quality-fixer-frontend) agent: "Quality check and fixes. Task file: [task-file-path]. The task file path above is also the `task_file` input. Read its `Quality Assurance Mechanisms` section as supplementary quality-check hints. filesModified: [executor response filesModified]. Use these files as the stub-detection scope." +3. Spawn quality-fixer (or quality-fixer-frontend) with `task_file` and executor `filesModified`. 4. Check quality-fixer response: - `status: "stub_detected"` -> Return to step 1 with `stubFindings` - `status: "blocked"` -> Escalate to user @@ -124,20 +127,21 @@ Before executing task files, read the associated work plan header and apply the ### Post-Implementation Verification (After All Tasks Complete) -After all task cycles finish, collect all `filesModified` from every executor response (task-executor and task-executor-frontend, deduplicated), then run both verification agents before the completion report: -1. Spawn code-verifier agent: "Verify implementation consistency against the Design Doc. `doc_type: design-doc`. `document_path`: [path]. `code_paths`: [collected filesModified list]." -2. Spawn security-reviewer agent: "Design Doc: [path]. Implementation files: [collected filesModified list]. Review security compliance." +After all task cycles finish, collect all `filesModified` from every executor response (task-executor and task-executor-frontend, deduplicated). Resolve governing documents to Design Docs, or the Work Plan when no Design Doc governs the change: +1. Spawn code-verifier for every governing document with matching `doc_type`, `document_path`, and collected `code_paths`. +2. Spawn security-reviewer with typed `governingDocuments: [{type, path}]` and `implementationFiles`. 3. Consolidate results: - code-verifier passes when `summary.status` is `consistent` or `mostly_consistent` - code-verifier fails when `summary.status` is `needs_review` or `inconsistent` + - code-verifier `blocked` or unrecognized status -> Escalate to user - security-reviewer passes when `status` is `approved` or `approved_with_notes` - security-reviewer fails when `status` is `needs_revision` - security-reviewer `blocked` -> Escalate to user 4. If either verifier fails: - - Create a single fix task covering verifier discrepancies and security requiredFixes - - Spawn the layer-appropriate executor - - Spawn the layer-appropriate quality-fixer - - Re-run only the verifier(s) that failed + - Create one ephemeral fix task per executor route covering verifier discrepancies and security requiredFixes + - Pass each exact path through the layer-appropriate executor and quality-fixer + - Re-run both verification agents after any fix + - Delete ephemeral task files only after both pass - Maximum retry count is 1 verification fix cycle; if any failed verifier still fails after re-run, escalate to the user 5. If both verifiers pass -> Proceed to completion report diff --git a/.agents/skills/recipe-plan/SKILL.md b/.agents/skills/recipe-plan/SKILL.md index 238cc00..0ffdf14 100644 --- a/.agents/skills/recipe-plan/SKILL.md +++ b/.agents/skills/recipe-plan/SKILL.md @@ -18,6 +18,8 @@ description: "Create work plan from design document with optional test skeleton **Core Identity**: "I am not a worker. I am an orchestrator." (see subagents-orchestration-guide skill) +**Execution Plan Gate**: Call `update_plan` with first "Map active rules to this task", the planning steps, and final "Verify outputs and rule adherence" before document selection. While work remains, keep exactly one step `in_progress`; after final verification evidence exists, mark every step `completed`. + **Execution Protocol**: 1. **Spawn agents for all work** -- your role is to invoke sub-agents, pass data between them, and report results 2. **Follow subagents-orchestration-guide skill planning flow exactly**: diff --git a/.agents/skills/recipe-prepare-implementation/SKILL.md b/.agents/skills/recipe-prepare-implementation/SKILL.md index 3da5cd5..f5d8587 100644 --- a/.agents/skills/recipe-prepare-implementation/SKILL.md +++ b/.agents/skills/recipe-prepare-implementation/SKILL.md @@ -42,6 +42,8 @@ R4 applies only to UI work. R5 applies when the plan uses a local service stack ## Execution Flow +Before Step 1, call `update_plan` with first "Map active rules to this task", Steps 1-6, and final "Verify outputs and rule adherence". While work remains, keep exactly one step `in_progress`; after final verification evidence exists, mark every step `completed`. + ### Step 1: Load Inputs Read the work plan passed in `$ARGUMENTS`; if absent, select the most recent non-template `docs/plans/*.md`. Extract: @@ -99,10 +101,11 @@ Layer selection: ### Step 5: Execute Prep Tasks Run each prep task through the standard 4-step cycle: -1. Spawn the layer-appropriate task executor with the exact prep task path in the prompt: "Execute implementation-readiness prep task. Task file: [exact prep task path]." +1. Capture `diffBase`, then spawn the layer-appropriate task executor with the exact prep task path in the prompt: "Execute implementation-readiness prep task. Task file: [exact prep task path]." 2. Check for `blocked` or `escalation_needed`. -3. Spawn the layer-appropriate quality fixer with the task file as `task_file`. -4. Commit only when the quality fixer returns `approved`. +3. If the executor requires test review, call integration-test-reviewer with changed integration/E2E paths from `filesModified`, `diffBase`, and `taskFile`; when matching integration/E2E skeleton paths are available from task/work-plan references, pass only those paths as `skeletonFiles`; escalate `blocked` or an unrecognized status. +4. Spawn the layer-appropriate quality fixer with `task_file` and executor `filesModified`. +5. Commit only when the quality fixer returns `approved`. Append this scope boundary to every subagent prompt: diff --git a/.agents/skills/recipe-reverse-engineer/SKILL.md b/.agents/skills/recipe-reverse-engineer/SKILL.md index 0eb2334..946ff27 100644 --- a/.agents/skills/recipe-reverse-engineer/SKILL.md +++ b/.agents/skills/recipe-reverse-engineer/SKILL.md @@ -25,7 +25,7 @@ Target: $ARGUMENTS 2. **Process one step at a time**: Execute steps sequentially within each unit (2 -> 3 -> 4 -> 5). Each step's output is the required input for the next step. Complete all steps for one unit before starting the next 3. **Pass `$STEP_N_OUTPUT` as-is** to sub-agents -- the orchestrator bridges data without processing or filtering it, except for steps that explicitly define a deterministic transformation with an input schema, output schema, and mapping rules -**Task Registration**: Register phases first, then steps within each phase as you enter it. Track status for each step. +**Execution Plan Gate**: After scope confirmation, call `update_plan` once with first "Map active rules to this task", all applicable workflow steps across both phases, and final "Verify outputs and rule adherence". While work remains, keep exactly one step `in_progress`; after final verification evidence exists, mark every step `completed`. ## Step 0: Initial Configuration @@ -57,7 +57,7 @@ Phase 2: Design Doc Generation (if requested) ## Phase 1: PRD Generation -**Register tasks**: +**Confirm these steps are present in the plan**: - Step 1: PRD Scope Discovery - Per-unit processing (Steps 2-5 for each unit) @@ -131,7 +131,7 @@ ENFORCEMENT: Exceeding 2 revision cycles without flagging produces unreviewed ou *Execute only if Design Docs were requested in Step 0* -**Register tasks**: +**Confirm these steps are present in the plan**: - Step 6: Design Doc Scope Mapping - Per-unit processing (Steps 7-10 for each unit) @@ -211,7 +211,7 @@ Spawn code-verifier agent: "Verify consistency between Design Doc and code imple **Required Input**: $STEP_8_OUTPUT (verification data from Step 8) -Spawn document-reviewer agent: "Review the following Design Doc considering code verification findings. doc_type: DesignDoc. target: $STEP_7_OUTPUT. mode: composite. code_verification: $STEP_8_OUTPUT. Parent PRD: $APPROVED_PRD_PATH. Additional Review Focus: Technical accuracy of documented interfaces, consistency with parent PRD scope, completeness of unit boundary definitions." +Spawn document-reviewer agent: "Review the following Design Doc considering code verification findings. doc_type: DesignDoc. review_context: as-is. target: $STEP_7_OUTPUT. mode: composite. code_verification: $STEP_8_OUTPUT. Parent PRD: $APPROVED_PRD_PATH. Additional Review Focus: Technical accuracy of documented interfaces, consistency with parent PRD scope, completeness of unit boundary definitions." **Store output as**: `$STEP_9_OUTPUT` diff --git a/.agents/skills/recipe-review/SKILL.md b/.agents/skills/recipe-review/SKILL.md index 044ea43..4440092 100644 --- a/.agents/skills/recipe-review/SKILL.md +++ b/.agents/skills/recipe-review/SKILL.md @@ -18,7 +18,7 @@ description: "Design Doc compliance and security validation with optional auto-f **Core Identity**: "I am not a worker. I am an orchestrator." -**First Action**: Register Steps 1-11 before any execution. +**First Action**: Call `update_plan` with first "Map active rules to this task", Steps 1-11, and final "Verify outputs and rule adherence" before execution. While work remains, keep exactly one step `in_progress`; after final verification evidence exists, mark every step `completed`. ## Execution Method @@ -45,7 +45,7 @@ Spawn code-reviewer agent: "Validate Design Doc compliance for the implementatio **Store output as**: `$STEP_2_OUTPUT` ### Step 3: Execute security-reviewer -Spawn security-reviewer agent: "Design Doc: [path]. Implementation files: [file list from git diff in Step 1]. Review security compliance." +Spawn security-reviewer with `governingDocuments: [{type: "design-doc", path: [path]}]` and `implementationFiles: [file list from git diff in Step 1]`. **Store output as**: `$STEP_3_OUTPUT` and `$STEP_1_FILES` (the initial file list) @@ -119,7 +119,7 @@ Reference documentation-criteria skill for task file template. Run this step only when the user routes at least one finding to `d`. 1. Spawn technical-designer agent in update mode: "Update Design Doc at [path]. The implementation is being accepted as correct for these findings: [d-routed findings with code locations and current Design Doc values]. Update the relevant sections and add change history." -2. Spawn document-reviewer agent: "Review updated Design Doc at [path] for consistency and completeness." +2. Spawn document-reviewer agent: "Review updated Design Doc at [path] for consistency and completeness. doc_type: DesignDoc. review_context: update." 3. If multiple Design Docs exist in `docs/design/`, spawn design-sync agent: "Check cross-Design Doc consistency after updating [path]." 4. If the user selected both `d` and `c` routes, re-evaluate the `c` findings against the updated Design Doc and drop any that are now satisfied. @@ -134,15 +134,17 @@ Spawn task-executor agent: "Execute review fixes. Task file: docs/plans/tasks/re ### Step 8: Quality Check -Spawn quality-fixer agent: "Confirm quality gate passage for fixed files." +Spawn quality-fixer with `task_file: docs/plans/tasks/review-fixes-YYYYMMDD.md` and executor `filesModified`. ### Step 9: Re-validate code-reviewer Spawn code-reviewer agent: "Re-validate Design Doc compliance after fixes. Prior compliance issues: $STEP_2_OUTPUT. Verify each prior issue is resolved." -### Step 10: Re-validate security-reviewer (only if security fixes were applied) +### Step 10: Re-validate security-reviewer -Spawn security-reviewer agent: "Re-validate security after fixes. Prior findings: $STEP_3_OUTPUT. Design Doc: [path]. Implementation files: [union of $STEP_1_FILES and task-executor filesModified from Step 7, deduplicated]." +Spawn security-reviewer with prior findings, `governingDocuments: [{type: "design-doc", path: [path]}]`, and `implementationFiles: [union of $STEP_1_FILES and task-executor filesModified from Step 7, deduplicated]`. + +After any code fix, both Steps 9 and 10 are mandatory even when only one reviewer initially reported a finding. Delete the task file only after both pass. ### Step 11: Final Report diff --git a/.agents/skills/recipe-task/SKILL.md b/.agents/skills/recipe-task/SKILL.md index b277e26..fa7b534 100644 --- a/.agents/skills/recipe-task/SKILL.md +++ b/.agents/skills/recipe-task/SKILL.md @@ -44,7 +44,7 @@ After receiving rule-advisor's response, proceed with: **Step 3: Create Task List** -Register work steps. Always include: first "Confirm skill constraints", final "Verify skill fidelity". +Call `update_plan` once for the work steps. Include first "Map active rules to this task" and final "Verify outputs and rule adherence". While work remains, keep exactly one step `in_progress`; after final verification evidence exists, mark every step `completed`. Break down the task based on rule-advisor's guidance: - Reflect `metaCognitiveGuidance.taskEssence` in task descriptions diff --git a/.agents/skills/recipe-update-doc/SKILL.md b/.agents/skills/recipe-update-doc/SKILL.md index 38873bf..cab1093 100644 --- a/.agents/skills/recipe-update-doc/SKILL.md +++ b/.agents/skills/recipe-update-doc/SKILL.md @@ -17,7 +17,7 @@ description: "Update existing design documents (Design Doc / PRD / ADR) with rev **Core Identity**: "I am not a worker. I am an orchestrator." (see subagents-orchestration-guide skill) -**First Action**: Register Steps 1-6 before any execution. +**First Action**: Call `update_plan` with first "Map active rules to this task", Steps 1-6, and final "Verify outputs and rule adherence" before execution. While work remains, keep exactly one step `in_progress`; after final verification evidence exists, mark every step `completed`. **Execution Protocol**: 1. **Spawn agents for all work** -- your role is to invoke sub-agents, pass data between them, and report results @@ -117,7 +117,7 @@ Spawn code-verifier agent: "Verify the updated Design Doc against current code. **Store output as**: `$CODE_VERIFICATION_OUTPUT` For Design Doc updates: -Spawn document-reviewer agent: "Review the following updated document. doc_type: DesignDoc. target: [path from Step 1]. mode: composite. code_verification: $CODE_VERIFICATION_OUTPUT. Focus on: Consistency of updated sections with rest of document, no contradictions introduced by changes, completeness of change history." +Spawn document-reviewer agent: "Review the following updated document. doc_type: DesignDoc. review_context: update. target: [path from Step 1]. mode: composite. code_verification: $CODE_VERIFICATION_OUTPUT. Focus on: Consistency of updated sections with rest of document, no contradictions introduced by changes, completeness of change history." For PRD or ADR updates: Spawn document-reviewer agent: "Review the following updated document. doc_type: [PRD or ADR]. target: [path from Step 1]. mode: composite. Focus on: Consistency of updated sections with rest of document, no contradictions introduced by changes, completeness of change history." diff --git a/.agents/skills/subagents-orchestration-guide/SKILL.md b/.agents/skills/subagents-orchestration-guide/SKILL.md index d02aab8..74fc8d3 100644 --- a/.agents/skills/subagents-orchestration-guide/SKILL.md +++ b/.agents/skills/subagents-orchestration-guide/SKILL.md @@ -11,6 +11,18 @@ description: "Guides subagent coordination through implementation workflows. Use The orchestrator coordinates subagents. All investigation, analysis, and implementation work flows through specialized subagents. +### Execution Plan Gate + +For workflows with three or more objectives or sequential dependencies, call `update_plan` before the first substantive action. + +- Register the workflow phases once; do not create a fresh plan for each subagent call. +- Use "Map active rules to this task" as the first step and "Verify outputs and rule adherence" as the final step. +- While work remains, keep exactly one step `in_progress`. +- Mark a step `completed` only after its named artifact, status, or verification evidence exists. +- Start the next step only after every prerequisite step is `completed`. +- After final verification evidence exists, mark every step `completed`. +- Update the plan immediately when a result changes the valid next state, including revision, blocked, and escalation branches. + ### Prompt Construction Rule Every subagent prompt must include: 1. Input deliverables with file paths (from previous step or prerequisite check) @@ -52,30 +64,6 @@ Receive New Task -> Analyze requirements with requirement-analyzer **ENFORCEMENT**: If any one applies — MUST restart from requirement-analyzer with integrated requirements -## Available Subagents - -The following subagents are available: - -### Implementation Support Agents -1. **quality-fixer**: Self-contained processing for overall quality assurance and fixes until completion -2. **task-decomposer**: Appropriate task decomposition of work plans -3. **task-executor**: Individual task execution and structured response -4. **integration-test-reviewer**: Review integration/E2E tests for skeleton compliance and quality -5. **security-reviewer**: Security compliance review against Design Doc and coding-rules after all tasks complete - -### Document Creation Agents -6. **requirement-analyzer**: Requirement analysis and work scale determination -7. **codebase-analyzer**: Existing codebase analysis before Design Doc creation -8. **prd-creator**: Product Requirements Document creation -9. **ui-spec-designer**: UI Specification creation from PRD and optional prototype code (frontend/fullstack features) -10. **technical-designer**: ADR/Design Doc creation -11. **work-planner**: Work plan creation from Design Doc and test skeletons -12. **document-reviewer**: Single document quality and rule compliance check -13. **code-verifier**: Document-code consistency verification for review inputs and post-implementation verification -14. **design-sync**: Design Doc consistency verification across multiple documents -15. **acceptance-test-generator**: Generate integration and E2E test skeletons from Design Doc ACs -16. **ui-analyzer**: UI fact gathering from external resources and existing frontend code before UI Spec, Design Doc, or adjustment work - ## Orchestration Principles ### Task Assignment with Responsibility Separation [MANDATORY] @@ -193,11 +181,11 @@ Subagents respond in JSON format. The final response from each JSON-returning su | `codebase-analyzer` | `focusAreas`, `dataModel`, `qualityAssurance`, `dataTransformationPipelines`, `limitations` | | `ui-analyzer` | `externalResources`, `componentStructure`, `propsPatterns`, `cssLayout`, `stateDisplay`, `focusAreas`, `candidateWriteSet`, `limitations` | | `task-executor*` | `status`, `escalation_type` (`design_compliance_violation`, `similar_function_found`, `similar_component_found`, `investigation_target_not_found`, `out_of_scope_file`, `dependency_version_uncertain`, `binding_decision_violation`, `test_environment_not_ready`), `filesModified`, `requiresTestReview` | -| `quality-fixer*` | `status`, `reason`, `stubFindings`, `blockingIssues`, `missingPrerequisites` | +| `quality-fixer*` | Inputs: `task_file`, `filesModified`; outputs: `status`, `reason`, `stubFindings`, `blockingIssues`, `missingPrerequisites` | | `document-reviewer` | `verdict.decision`, `verdict.conditions` | -| `code-verifier` | `summary.status`, `discrepancies`, `reverseCoverage` | +| `code-verifier` | `summary.status`, `blockingReason`, `discrepancies`, `reverseCoverage` | | `design-sync` | `sync_status` | -| `integration-test-reviewer` | `status`, `requiredFixes` | +| `integration-test-reviewer` | Inputs: `changedTestFiles`, `diffBase`, optional review-basis inputs; outputs: `status`, `reviewBasis`, `requiredFixes` | | `security-reviewer` | `status`, `findings`, `notes`, `requiredFixes` | | `acceptance-test-generator` | `status`, `generatedFiles.integration`, `generatedFiles.fixtureE2e`, `generatedFiles.serviceE2e`, `e2eAbsenceReason.fixtureE2e`, `e2eAbsenceReason.serviceE2e` | @@ -293,21 +281,23 @@ After "batch approval for entire implementation phase" with work-planner, autono Batch approval -> Start autonomous execution mode -> task-decomposer: Task decomposition -> Task execution loop: + -> Orchestrator: capture diffBase -> task-executor: Implementation -> Escalation judgment: - escalation_needed/blocked -> Escalate to user - - requiresTestReview: true -> integration-test-reviewer + - requiresTestReview: true -> integration-test-reviewer with changedTestFiles from filesModified, diffBase, taskFile, and matching skeletonFiles when available from acceptance-test-generator output or task/work-plan references - needs_revision -> back to task-executor - approved -> quality-fixer + - blocked/unrecognized -> Escalate to user - No issues -> quality-fixer - -> quality-fixer: Quality check and fixes using the executor `filesModified` set as the stub-detection scope + -> quality-fixer: Quality check and fixes with task_file and filesModified - stub_detected -> task-executor/task-executor-frontend: complete implementation -> re-run quality-fixer -> Orchestrator: Execute git commit -> Check remaining tasks: - Yes -> next task - No -> code-verifier + security-reviewer: Post-implementation verification - all pass -> Completion report - - any fail -> layer-appropriate task-executor: Verification fixes -> quality-fixer -> re-run failed verifiers + - any fail -> exact ephemeral task path -> layer-appropriate task-executor -> quality-fixer -> re-run all verifiers - blocked -> Escalate to user ``` @@ -326,7 +316,7 @@ Continue autonomous execution in the following situations: - The orchestrator has partial context but is still waiting on a required subagent output Use the task loop defined in the autonomous execution diagram above. The canonical per-task cycle is: -1. task-executor implementation +1. capture `diffBase`, then task-executor implementation 2. escalation or integration-test-reviewer decision 3. quality-fixer quality gate 4. git commit on approval @@ -335,10 +325,10 @@ Use the task loop defined in the autonomous execution diagram above. The canonic | Verifier | Pass | Fail | Blocked | |----------|------|------|---------| -| code-verifier | `summary.status` is `consistent` or `mostly_consistent` | `summary.status` is `needs_review` or `inconsistent` | — | +| code-verifier | `summary.status` is `consistent` or `mostly_consistent` | `summary.status` is `needs_review` or `inconsistent` | `summary.status` is `blocked` | | security-reviewer | `status` is `approved` or `approved_with_notes` | `status` is `needs_revision` | `status` is `blocked` | -Re-run only verifiers that failed on the previous verification cycle. +Consolidate failed verifier findings into one ephemeral task per required executor and pass each exact task path through its executor and quality-fixer. Re-run both code-verifier and security-reviewer after any verification fix because the fix can invalidate either result. Delete the ephemeral task files after both verifiers pass. Maximum retry count is 1 verification fix cycle. If any failed verifier still fails after the re-run, escalate to the user. ## Main Orchestrator Roles @@ -361,6 +351,8 @@ Maximum retry count is 1 verification fix cycle. If any failed verifier still fa | `codebase-analyzer` | `technical-designer*` | `Codebase Analysis`, including `focusAreas`, `dataModel`, `qualityAssurance`, `dataTransformationPipelines`, `limitations` | | `technical-designer*` | `code-verifier` | Design Doc path | | `code-verifier` | `document-reviewer` | `code_verification` JSON | +| `task-executor*` | `integration-test-reviewer` | `diffBase`, changed integration/E2E paths from `filesModified`, task file, matching skeleton paths when available, and prompt claims when used | +| `task-executor*` | `quality-fixer*` | exact `task_file` and `filesModified` | | `acceptance-test-generator` | `work-planner` | `generatedFiles.integration`, `generatedFiles.fixtureE2e`, `generatedFiles.serviceE2e`, `e2eAbsenceReason: { fixtureE2e, serviceE2e }` | | Design Doc | `work-planner` | Verification Strategy summary, Output Comparison details, implementation-relevant technical requirements, protected no-change boundaries | diff --git a/.agents/skills/subagents-orchestration-guide/references/monorepo-flow.md b/.agents/skills/subagents-orchestration-guide/references/monorepo-flow.md index ed0c4fd..3bdf5f2 100644 --- a/.agents/skills/subagents-orchestration-guide/references/monorepo-flow.md +++ b/.agents/skills/subagents-orchestration-guide/references/monorepo-flow.md @@ -125,21 +125,21 @@ Layer is determined from the task's **Target files** paths -- this is a factual Each task uses the standard 4-step cycle with layer-appropriate agents: ### backend-task -1. task-executor: Implementation +1. Capture `diffBase`; task-executor: Implementation 2. Escalation check -3. quality-fixer: Quality check and fixes +3. quality-fixer: Quality check and fixes with `task_file` and `filesModified` 4. git commit (on status: "approved") ### frontend-task -1. task-executor-frontend: Implementation +1. Capture `diffBase`; task-executor-frontend: Implementation 2. Escalation check -3. quality-fixer-frontend: Quality check and fixes +3. quality-fixer-frontend: Quality check and fixes with `task_file` and `filesModified` 4. git commit (on status: "approved") ### integration-test-reviewer Placement When `requiresTestReview` is `true`: -- Standard flow (integration-test-reviewer after task-executor, before quality-fixer) +- Standard flow: integration-test-reviewer after executor and before quality-fixer, with changed integration/E2E paths from `filesModified`, `diffBase`, `taskFile`, and only matching `skeletonFiles` when available from acceptance-test-generator output or task/work-plan references ## Agent Routing Summary diff --git a/.agents/skills/task-analyzer/references/skills-index.yaml b/.agents/skills/task-analyzer/references/skills-index.yaml index 48789b7..dcf3ad4 100644 --- a/.agents/skills/task-analyzer/references/skills-index.yaml +++ b/.agents/skills/task-analyzer/references/skills-index.yaml @@ -4,59 +4,40 @@ skills: coding-rules: skill: "coding-rules" - tags: [implementation, code-quality, refactoring, clean-code, maintainability, function-design, error-handling, parameterized-dependencies, reference-representativeness, performance, security] - typical-use: "Language-agnostic code creation, modification, and refactoring principles applicable to all programming languages" - size: medium + tags: [implementation, code-quality, refactoring, design-convergence, contract-safety, boundary-safety, repository-local-choice, performance, security] + typical-use: "Repository-aware implementation, refactoring, contract preservation, and pattern selection" + size: small key-references: - - "YAGNI Principle - Kent Beck" - - "Clean Code - Robert C. Martin" - - "DRY Principle - The Pragmatic Programmer" - - "Refactoring - Martin Fowler" - - "Single Responsibility Principle - SOLID" + - "Governing project contracts" + - "Representative repository patterns" sections: - - "Language-Specific References" - - "Core Philosophy [MANDATORY]" - - "Design Surface Terms [MANDATORY]" - - "Code Quality [MANDATORY]" - - "Function Design [MANDATORY]" - - "Error Handling [MANDATORY]" - - "Dependency Management" - - "Reference Representativeness" - - "Performance" - - "Code Organization" - - "Commenting Principles" - - "Refactoring [SAFE CHANGE PROTOCOL]" - - "Security" - - "Version Control [MANDATORY]" + - "Reference" + - "Source Order" + - "Minimal Design Surface" + - "Contract and Boundary Safety" + - "Repository-Local Choice" + - "Change Discipline" + - "Completion Gate" references: - "references/typescript.md" - "references/security-checks.md" testing: skill: "testing" - tags: [testing, tdd, quality, unit-testing, integration-testing, e2e-testing, data-layer-testing, test-design, coverage, mocking, test-independence, ci-cd, test-quality-criteria] - typical-use: "Universal testing principles, TDD practice, test quality criteria, test creation and quality assurance for all programming languages" - size: large + tags: [testing, tdd, quality, integration-testing, e2e-testing, proof-obligation, capability-probe, boundary-testing, repository-aware] + typical-use: "Repository-aware TDD, observable proof selection, and capability probes" + size: small key-references: - - "Test-Driven Development - Kent Beck" - - "Red-Green-Refactor Cycle - Kent Beck" - - "AAA Pattern - Arrange-Act-Assert" + - "Governing test contracts" + - "Consumer-visible postconditions" sections: - - "Language-Specific References" - - "Core Testing Philosophy" - - "TDD Process [MANDATORY for all code changes]" - - "Quality Requirements [MANDATORY]" - - "Test Level Selection" - - "Test Design Principles" - - "Test Independence" - - "Mocking and Test Doubles" - - "Data Layer Testing" - - "Test Quality Practices [MANDATORY]" - - "What to Test" - - "Test Quality Criteria [MANDATORY]" - - "Verification Requirements [MANDATORY for VERIFY phase]" - - "Common Anti-Patterns" - - "Regression Testing" + - "Reference" + - "Governing Sources" + - "TDD Gate" + - "Proof Selection" + - "Capability Probe Postconditions" + - "Test Integrity" + - "Completion Gate" references: - "references/typescript.md" @@ -150,7 +131,7 @@ skills: subagents-orchestration-guide: skill: "subagents-orchestration-guide" - tags: [orchestration, workflow, subagents, context-isolation, autonomous-execution, guided-autonomous-execution, planning, design-flow, implementation-flow, implementation-readiness, readiness-resolution] + tags: [orchestration, workflow, subagents, update-plan, state-machine, context-isolation, autonomous-execution, guided-autonomous-execution, planning, design-flow, implementation-flow, implementation-readiness, readiness-resolution] typical-use: "Orchestrating subagents through implementation workflows, scale determination, stop points, guided autonomous execution mode" size: large key-references: @@ -159,7 +140,6 @@ skills: sections: - "Role: The Orchestrator" - "Decision Flow When Receiving Tasks" - - "Available Subagents" - "Orchestration Principles" - "Constraints Between Subagents [MANDATORY]" - "How to Spawn Agents" @@ -206,7 +186,7 @@ skills: llm-friendly-context: skill: "llm-friendly-context" - tags: [cross-cutting, llm-facing, prompt-writing, handoff, subagent-prompt, documentation, planning, task-decomposition, test-skeleton, generated-instructions, ambiguity-reduction, output-format, success-criteria] + tags: [cross-cutting, llm-facing, prompt-writing, handoff, subagent-prompt, documentation, planning, update-plan, context-budget, task-decomposition, test-skeleton, generated-instructions, ambiguity-reduction, output-format, success-criteria] typical-use: "Writing or revising LLM-facing prompts, subagent handoffs, design/planning artifacts, review findings, completion reports, generated instructions, and task files so downstream agents can execute without guessing" size: small key-references: diff --git a/.agents/skills/testing/SKILL.md b/.agents/skills/testing/SKILL.md index 1abf63a..3ac46e0 100644 --- a/.agents/skills/testing/SKILL.md +++ b/.agents/skills/testing/SKILL.md @@ -1,255 +1,59 @@ --- name: testing -description: "Testing principles including TDD, test quality, coverage standards, and test design. Use when: writing tests, designing test strategies, reviewing test quality, or following Red-Green-Refactor cycle." +description: "Repository-aware test execution rules for TDD, observable proof, and boundary selection. Use when writing, reviewing, or fixing tests." --- -# Testing Principles +# Testing -## Language-Specific References +## Reference -For language-specific testing patterns, also read: -- **TypeScript (Vitest/RTL/Playwright)**: [references/typescript.md](references/typescript.md) +Read [references/typescript.md](references/typescript.md) only for TypeScript tests in web frontend work, including React, RTL, MSW, and Playwright tests. It does not apply to backend or non-web TypeScript tests. -## Core Testing Philosophy +## Governing Sources -1. **Tests are First-Class Code**: Maintain test quality equal to production code -2. **Fast Feedback**: Tests should run quickly and provide immediate feedback -3. **Reliability**: Tests should be deterministic and reproducible -4. **Independence**: Each test should run in isolation +Use test commands, thresholds, boundaries, fixtures, and conventions from the repository, task, Work Plan, Design Doc, or test skeleton. Do not invent defaults when these sources are silent. -## TDD Process [MANDATORY for all code changes] +## TDD Gate -**Execute this process for every code change:** +For behavior-changing implementation: -### RED Phase -**STEP 1**: Write test that defines expected behavior -**STEP 2**: Run test -**STEP 3**: Confirm the test fails for the targeted missing behavior or regression. If it passes before implementation, verify that it can fail for the targeted defect; then determine whether the behavior is already implemented or the test does not exercise the intended failure mode. +1. **RED**: Add or select a test that observes the required behavior. Run it and confirm it fails for the targeted missing behavior or regression. +2. **GREEN**: Make the smallest implementation change that satisfies the behavior. Run the focused test. +3. **REFACTOR**: Improve the changed code without changing the contract. Re-run the focused test. +4. **VERIFY**: Run the repository's required quality command and every wider check required by the task boundary. -### GREEN Phase -**STEP 1**: Write MINIMAL code to make test pass -**STEP 2**: Run test -**STEP 3**: Confirm test PASSES +Documentation, pure configuration, and disposable exploration do not require a RED phase. A productionized spike must gain tests before completion. -### REFACTOR Phase -**STEP 1**: Improve code quality (eliminate duplication, improve naming) -**STEP 2**: Run test -**STEP 3**: Confirm test STILL PASSES +## Proof Selection -### VERIFY Phase [MANDATORY - 0 ERRORS REQUIRED] -**STEP 1**: Execute ALL quality check commands for your language/project -**STEP 2**: Fix any errors until ALL commands pass with 0 errors -**STEP 3**: Confirm no regressions +- Test through the public or externally observable boundary named by the acceptance criterion or proof obligation. +- Keep a dependency real when that dependency is the boundary under proof; isolate external I/O only when the selected test level permits it. +- Use integration or E2E tests for persistence, process, browser, service, or cross-component claims that unit tests cannot observe. +- A broader test does not replace a required focused check, and a focused test does not prove a wider boundary. -**ENFORCEMENT**: Cannot proceed to next phase with ANY quality check failures +## Capability Probe Postconditions -### TDD Exceptions (no TDD required) -- Pure configuration files -- Documentation only -- Emergency fixes (but add tests immediately after) -- Exploratory spikes (discard or rewrite with tests before merging) -- Build/deployment scripts (unless they contain business logic) +Evidence is substantive only when an executed assertion observes the exact consumer-visible postcondition. -## Quality Requirements [MANDATORY] +- A helper result, mock call, source match, build success, or zero-test run does not prove behavior unless that is the named claim. +- Intentional absence is substantive when absence is the expected postcondition. +- State-changing behavior must assert relevant before → action → after state, including persistence or rollback semantics when applicable. +- For a changed route or alternate input path, exercise that path explicitly; evidence from another route is not interchangeable. -### Coverage +## Test Integrity -- Treat coverage as a diagnostic signal for finding untested areas, not a target. Targets get gamed into trivial tests. -- Concentrate tests on critical paths, business logic, and behavior whose regression would matter. -- Prioritize meaningful assertions over the coverage number. Any required threshold comes from the project's CI, task file, work plan, or Design Doc. +- Keep tests deterministic, isolated, and active. +- Use meaningful assertions on results, state, or observable effects. +- Do not weaken, skip, delete, or replace a test merely to make a run pass. +- Change an existing expectation only when a cited governing source changed the expected behavior. +- Use project-scoped setup and guaranteed cleanup for mutated state or external resources. +- Treat coverage as diagnostic unless a governing source defines a threshold. -### Test Characteristics +## Completion Gate -All tests MUST be: - -- **Independent**: No dependencies between tests -- **Reproducible**: Same input always produces same output -- **Fast**: Complete the full test suite within the project's accepted feedback window and flag suites that materially slow local iteration or CI -- **Self-checking**: Clear pass/fail without manual verification -- **Timely**: Written close to the code they test - -**ENFORCEMENT**: Tests failing ANY characteristic MUST be fixed immediately - -## Test Level Selection - -- **Unit/local**: Exercise one unit or in-process behavior and isolate external I/O -- **Integration**: Exercise the real component, persistence, process, or contract boundary named by the proof obligation -- **End-to-end**: Exercise the complete user, browser, process, or service journey named by the proof obligation -- Select the level that proves the required boundary; a broader test does not replace a required focused check, and a focused test does not prove an integration boundary - -## Test Design Principles - -### AAA Pattern (Arrange-Act-Assert) - -Structure every test in clear Arrange, Act, and Assert phases. - -### One Assertion Per Concept - -- Test one behavior per test case -- Multiple assertions OK if testing single concept -- Split unrelated assertions into separate tests — one test MUST verify one behavior - -### Descriptive Test Names - -Test names should clearly describe: -- What is being tested -- Under what conditions -- What the expected outcome is - -**Recommended format**: `"should [expected behavior] when [condition]"` - -## Test Independence - -### Isolation Requirements - -- Each test creates its own test data -- No dependencies on execution order -- Clean up own state -- Pass when run in isolation - -### Setup and Teardown - -- Use setup hooks to prepare test environment -- Use teardown hooks to clean up resources -- Keep setup scoped to the data, dependencies, and fixtures required for the behavior under test -- Ensure teardown runs even if test fails - -## Mocking and Test Doubles - -### Boundary Selection - -- In unit/local tests, isolate external I/O such as APIs, databases, file systems, network calls, time, and randomness -- In integration and data-layer tests, keep the dependency or boundary named by the proof obligation real or production-like -- Isolate unavailable third-party services unless their contract payload or failure behavior is the boundary under test -- Follow the Design Doc `Test Boundaries` decision when one exists - -### Mocking Principles [MANDATORY] - -- Mock at boundaries, not internally — use real implementations for internal utilities -- Keep each mock limited to the behavior the test needs to control or observe -- Verify mock expectations when relevant -- Use adapters for external libraries/frameworks you do not control - -## Data Layer Testing - -### Mock Limitations for Data Access - -Mocks validate call patterns but do not validate schema correctness, query correctness, or storage constraints. -Examples of issues that mocks can miss: -- schema drift -- column or field mismatches -- incorrect joins, filters, or aggregations -- migration incompatibility - -### When Real Data Layer Verification Adds Value - -Use real or production-like data access verification when testing: -- repository or DAO implementations -- ORM mappings -- query builders or raw SQL -- persistence behavior that depends on constraints or schema shape - -### Environment Options - -Choose the most practical option for the project environment: -- containerized database -- dedicated test database -- in-memory database with documented limitations -- adapter-backed local test harness - -### Design Alignment - -When a Design Doc includes `Test Boundaries`, follow it as the baseline for deciding which dependencies stay real and which boundaries are isolated. - -## Test Quality Practices [MANDATORY] - -### Keep Tests Active - -- **Fix or delete failing tests**: Resolve failures immediately -- **Remove commented-out tests**: Fix them or delete entirely -- **Keep tests running**: Broken tests lose value quickly -- **Maintain test suite**: Refactor tests as needed - -### Test Code Quality - -- Apply same standards as production code -- Use descriptive variable names -- Extract test helpers to reduce duplication -- Keep tests readable and maintainable - -### Test Helpers and Utilities - -- Create reusable test data builders -- Extract common setup into helper functions -- Build test utilities for complex scenarios -- Share helpers across test files appropriately - -## What to Test - -- Test accepted behavior through the public or externally observable boundary -- Cover the happy path and the boundary, error, and regression cases required by the proof obligation -- Do not assert private state or private call order unless that internal contract is itself the named proof target - -## Test Quality Criteria [MANDATORY] - -1. **Literal expectations**: Use hardcoded literal values in assertions — expected value ≠ mock return value (implementation processes data) -2. **Result verification**: Assert return values and state, not call order -3. **Meaningful assertions**: Every test MUST have at least one assertion — a test without assertions provides zero value -4. **Boundary fidelity**: Mock only boundaries intentionally isolated at the selected test level; keep every dependency named as real by the proof obligation or Design Doc boundary decision -5. **Boundary coverage**: Include empty/zero/max/error cases with happy paths - -**ENFORCEMENT**: Tests violating ANY criterion MUST be rewritten - -## Verification Requirements [MANDATORY for VERIFY phase] - -### Before Commit Checklist - -☐ All tests pass -☐ No tests skipped or commented -☐ No debug code left in tests -☐ Coverage threshold passes when the project, task file, work plan, or Design Doc defines one -☐ Tests run in reasonable time - -### Zero Tolerance Policy - -- **Zero failing tests**: Fix immediately -- **Zero skipped tests**: Delete or fix -- **Zero flaky tests**: Make deterministic -- **Zero unreviewed slow tests**: When a test or suite exceeds the project's accepted feedback window, optimize it, split it, move it to the appropriate test level, or record the accepted exception in the governing task or Design Doc - -**ENFORCEMENT**: Cannot proceed with task completion if ANY quality check fails - -## Common Anti-Patterns - -Detect and eliminate these patterns immediately: - -- Tests that test nothing (always pass) -- Tests that depend on execution order -- Tests that depend on external state -- Tests with complex logic (tests that need their own tests) -- Testing implementation details instead of observable behavior -- Excessive mocking (mock boundaries only, use real internals) -- Test code duplication - -### Flaky Tests - -Eliminate tests that fail intermittently: -- Remove timing dependencies -- Use deterministic data instead of random values -- Ensure proper cleanup -- Fix race conditions -- Make all tests deterministic - -## Regression Testing - -- Add test for every bug fix -- Maintain comprehensive test suite -- Run full suite regularly -- Delete a test only when the covered behavior no longer exists or the same behavior is covered by a stronger test at the correct level - -### Legacy Code - -- Add characterization tests before refactoring -- Test existing behavior first -- Gradually improve coverage -- Refactor with confidence +- [ ] Focused tests pass; when the TDD Gate applies, RED failed for the targeted missing behavior or regression; otherwise RED is recorded as not applicable with the reason +- [ ] Required integration/E2E boundary is exercised +- [ ] Every cited behavior has a consumer-visible capability probe +- [ ] Repository-defined quality commands pass +- [ ] No required test is skipped, hollow, or dependent on execution order +- [ ] Mutated state and resources are restored diff --git a/.agents/skills/testing/references/typescript.md b/.agents/skills/testing/references/typescript.md index 1b3a84d..dec283d 100644 --- a/.agents/skills/testing/references/typescript.md +++ b/.agents/skills/testing/references/typescript.md @@ -1,4 +1,4 @@ -# TypeScript Testing Reference (Vitest + RTL + MSW + Playwright) +# Web Frontend Testing Reference (TypeScript + Vitest + RTL + MSW + Playwright) ## Unit and Integration Tests diff --git a/.codex/agents/acceptance-test-generator.toml b/.codex/agents/acceptance-test-generator.toml index e0043dc..769a00d 100644 --- a/.codex/agents/acceptance-test-generator.toml +++ b/.codex/agents/acceptance-test-generator.toml @@ -33,7 +33,7 @@ Skill Status: ## Mandatory Initial Tasks -**Progress Tracking**: Track your work steps. Always include: first "Confirm skill constraints", final "Verify skill fidelity". Update progress upon completion. +**Execution Plan Gate**: Call `update_plan` before substantive work. Include first "Map active rules to this task" and final "Verify outputs and rule adherence". While work remains, keep exactly one step `in_progress`; complete it only after recording its evidence and satisfying the next step's prerequisites. After final verification evidence is recorded, mark every step `completed`. ### Implementation Approach Compliance - **Test Code Generation**: MUST strictly comply with Design Doc implementation patterns (function vs class selection) diff --git a/.codex/agents/code-reviewer.toml b/.codex/agents/code-reviewer.toml index e47c2f0..aaac3da 100644 --- a/.codex/agents/code-reviewer.toml +++ b/.codex/agents/code-reviewer.toml @@ -31,7 +31,7 @@ Skill Status: ## Initial Required Tasks -**Progress Tracking**: Track your work steps. Always include: first "Confirm skill constraints", final "Verify skill fidelity". Update progress upon completion. +**Execution Plan Gate**: Call `update_plan` before substantive work. Include first "Map active rules to this task" and final "Verify outputs and rule adherence". While work remains, keep exactly one step `in_progress`; complete it only after recording its evidence and satisfying the next step's prerequisites. After final verification evidence is recorded, mark every step `completed`. ## Responsibilities @@ -70,6 +70,8 @@ Read the Design Doc in full and extract: ### 2. Map Implementation to Design Doc +Read referenced material only while it can change an in-scope requirement, review decision, or verification method. Stop traversing references once additional material would only add background. + #### 2-1. Acceptance Criteria Verification For each acceptance criterion extracted in Step 1: - Search implementation files for the corresponding code @@ -217,7 +219,7 @@ Recommend higher-level review when any condition below is true: - Design Doc itself has deficiencies - Security concerns discovered - Critical performance issues found -- Implementation introduces a maintenance-surface-bearing element defined by coding-rules that is absent from both the Design Doc's Direct MVP and Adopted Additions +- Implementation introduces an element listed in coding-rules Minimal Design Surface that is absent from both the Design Doc's Direct MVP and Adopted Additions Private single-file refactors, local helper extraction, test fixtures/mocks, and temporary migration scaffolding do not trigger escalation unless they create public, cross-boundary, persistent, or reusable surface. diff --git a/.codex/agents/code-verifier.toml b/.codex/agents/code-verifier.toml index 8bce2cb..7648a1c 100644 --- a/.codex/agents/code-verifier.toml +++ b/.codex/agents/code-verifier.toml @@ -1,5 +1,5 @@ name = "code-verifier" -description = "Validates consistency between PRD/Design Doc and code implementation using multi-source evidence matching." +description = "Validates consistency between PRD, Design Doc, or Work Plan and code implementation using multi-source evidence matching." sandbox_mode = "read-only" developer_instructions = """ @@ -31,13 +31,14 @@ Skill Status: ## Required Initial Tasks -**Progress Tracking**: Track your work steps. Always include "Verify skill constraints" first and "Verify skill adherence" last. Update progress upon each completion. +**Execution Plan Gate**: Call `update_plan` before substantive work. Include first "Map active rules to this task" and final "Verify outputs and rule adherence". While work remains, keep exactly one step `in_progress`; complete it only after recording its evidence and satisfying the next step's prerequisites. After final verification evidence is recorded, mark every step `completed`. ## Input Parameters - **doc_type**: Document type to verify (required) - `prd`: Verify PRD against code - `design-doc`: Verify Design Doc against code + - `work-plan`: Verify Work Plan against code - **document_path**: Path to the document to verify (required) @@ -54,6 +55,10 @@ Document modification and solution proposals are out of scope for this agent. ## Verification Framework +### Input Gate + +Proceed when `doc_type` is documented above and `document_path` identifies a readable authoritative document. Return `summary.status: "blocked"` with `blockingReason` when the type is unsupported, the path is missing or unreadable, or no authoritative document was supplied. + ### Claim Categories | Category | Description | @@ -99,7 +104,9 @@ For each claim, classify as one of: - If a section contains factual statements but yields zero claims, record that explicitly for review 3. Categorize each claim 4. Note ambiguous claims that cannot be verified -5. Minimum claim threshold: if `verifiableClaimCount < 20`, re-read under-covered sections and extract additional claims before continuing. Fewer than 20 claims usually indicates shallow extraction rather than a fully analyzed document. +5. Re-read any authoritative section whose verifiable statements were not converted into claims. Document size does not impose a numeric minimum. + +For `doc_type: work-plan`, treat Binding Contracts, Reference Contracts, task Completion Criteria, Proof Obligations, and scoped implementation claims as the authoritative verification surface. Extract each item separately and retain its task or section origin. ### Step 2: Code Scope Identification @@ -158,7 +165,7 @@ Return the JSON result as the final response. See Output Format for the schema. ### Essential Output (default) ```json -{"summary":{"docType":"prd|design-doc","documentPath":"/path/to/document.md","verifiableClaimCount":24,"matchCount":20,"consistencyScore":85,"status":"consistent|mostly_consistent|needs_review|inconsistent"},"claimCoverage":{"sectionsAnalyzed":8,"sectionsWithClaims":7,"sectionsWithZeroClaims":["Appendix"]},"discrepancies":[{"id":"D001","status":"drift|gap|conflict","severity":"critical|major|minor","claim":"Brief claim description","documentLocation":"PRD.md:45","codeLocation":"src/auth.ts:120","evidence":"Observed implementation or enumeration result","classification":"What was found"}],"reverseCoverage":{"routesInCode":6,"routesDocumented":5,"undocumentedRoutes":["POST /admin/reindex (src/routes/admin.ts:42)"],"testFilesFound":4,"testFilesDocumented":2,"exportsInCode":12,"exportsDocumented":10,"undocumentedExports":["rebuildSearchIndex (src/search/index.ts:18)"],"dataOperationsInCode":3,"dataOperationsDocumented":2,"undocumentedDataOperations":["userRepository.saveUser (src/user/repository.ts:41)"],"testBoundariesSectionPresent":true},"coverage":{"documented":["Feature areas with documentation"],"undocumented":["Code features lacking documentation"],"unimplemented":["Documented specs not yet implemented"]},"limitations":["What could not be verified and why"]} +{"summary":{"docType":"prd|design-doc|work-plan","documentPath":"/path/to/document.md","verifiableClaimCount":24,"matchCount":20,"consistencyScore":85,"status":"consistent|mostly_consistent|needs_review|inconsistent|blocked"},"blockingReason":null,"claimCoverage":{"sectionsAnalyzed":8,"sectionsWithClaims":7,"sectionsWithZeroClaims":["Appendix"]},"discrepancies":[{"id":"D001","status":"drift|gap|conflict","severity":"critical|major|minor","claim":"Brief claim description","documentLocation":"PRD.md:45","codeLocation":"src/auth.ts:120","evidence":"Observed implementation or enumeration result","classification":"What was found"}],"reverseCoverage":{"routesInCode":6,"routesDocumented":5,"undocumentedRoutes":["POST /admin/reindex (src/routes/admin.ts:42)"],"testFilesFound":4,"testFilesDocumented":2,"exportsInCode":12,"exportsDocumented":10,"undocumentedExports":["rebuildSearchIndex (src/search/index.ts:18)"],"dataOperationsInCode":3,"dataOperationsDocumented":2,"undocumentedDataOperations":["userRepository.saveUser (src/user/repository.ts:41)"],"testBoundariesSectionPresent":true},"coverage":{"documented":["Feature areas with documentation"],"undocumented":["Code features lacking documentation"],"unimplemented":["Documented specs not yet implemented"]},"limitations":["What could not be verified and why"]} ``` ### Extended Output (verbose: true) @@ -177,7 +184,7 @@ consistencyScore = (matchCount / verifiableClaimCount) * 100 - (minorDiscrepancies * 2) ``` -If `verifiableClaimCount < 20`, treat the score as unstable and return to Step 1 before finalizing. This threshold exists to prevent shallow extraction from producing an artificially high score. +If an authoritative section still contains unprocessed verifiable statements, treat the score as unstable and return to Step 1 before finalizing. | Score | Status | Interpretation | |-------|--------|----------------| @@ -189,7 +196,7 @@ If `verifiableClaimCount < 20`, treat the score as unstable and return to Step 1 ## Completion Criteria - [ ] Extracted claims section-by-section with per-section counts recorded -- [ ] `verifiableClaimCount >= 20` +- [ ] Every authoritative section was checked for verifiable statements - [ ] Collected evidence from multiple sources for each claim - [ ] Classified each claim (match/drift/gap/conflict) - [ ] Performed reverse coverage with route, test file, public export, and data operation enumeration diff --git a/.codex/agents/codebase-analyzer.toml b/.codex/agents/codebase-analyzer.toml index c5d7bb7..e7cdecf 100644 --- a/.codex/agents/codebase-analyzer.toml +++ b/.codex/agents/codebase-analyzer.toml @@ -21,7 +21,7 @@ You are an AI assistant specializing in objective codebase analysis for design p ## Required Initial Tasks -**Progress Tracking**: Track your work steps. Always include "Confirm skill constraints" first and "Verify skill fidelity" last. Update progress upon each completion. +**Execution Plan Gate**: Call `update_plan` before substantive work. Include first "Map active rules to this task" and final "Verify outputs and rule adherence". While work remains, keep exactly one step `in_progress`; complete it only after recording its evidence and satisfying the next step's prerequisites. After final verification evidence is recorded, mark every step `completed`. ## Responsibilities diff --git a/.codex/agents/design-sync.toml b/.codex/agents/design-sync.toml index bd9c62f..6bd5b09 100644 --- a/.codex/agents/design-sync.toml +++ b/.codex/agents/design-sync.toml @@ -33,7 +33,7 @@ Skill Status: ## Initial Mandatory Tasks -**Progress Tracking**: Track your work steps. Always include: first "Confirm skill constraints", final "Verify skill fidelity". Update progress upon completion. +**Execution Plan Gate**: Call `update_plan` before substantive work. Include first "Map active rules to this task" and final "Verify outputs and rule adherence". While work remains, keep exactly one step `in_progress`; complete it only after recording its evidence and satisfying the next step's prerequisites. After final verification evidence is recorded, mark every step `completed`. ## Detection Criteria (The Only Rule) diff --git a/.codex/agents/document-reviewer.toml b/.codex/agents/document-reviewer.toml index 11177b1..2d9412d 100644 --- a/.codex/agents/document-reviewer.toml +++ b/.codex/agents/document-reviewer.toml @@ -32,7 +32,7 @@ Skill Status: ## Initial Mandatory Tasks -**Progress Tracking**: Track your work steps. Always include: first "Confirm skill constraints", final "Verify skill fidelity". Update progress upon completion. +**Execution Plan Gate**: Call `update_plan` before substantive work. Include first "Map active rules to this task" and final "Verify outputs and rule adherence". While work remains, keep exactly one step `in_progress`; complete it only after recording its evidence and satisfying the next step's prerequisites. After final verification evidence is recorded, mark every step `completed`. ## Responsibilities @@ -52,6 +52,7 @@ Skill Status: - **doc_type**: Document type (`PRD`/`ADR`/`UISpec`/`DesignDoc`/`WorkPlan`) - **target**: Document path to review +- **review_context**: DesignDoc review context (`creation`/`update`/`as-is`); required for DesignDoc - **codebase_analysis**: codebase-analyzer JSON used to create the target document (optional) - **ui_analysis**: ui-analyzer JSON used to create the target document (optional) - **code_verification**: Code-verifier results JSON (optional) @@ -59,7 +60,6 @@ Skill Status: - Use to derive required outcomes and stated constraints; treat only wording framed as a suggestion or option as a candidate - **confirmed_requirement_context**: User-confirmed scope and answers (required for DesignDoc creation review) - Use as authoritative refinements and constraints on `requirements_verbatim` - - A DesignDoc review with both inputs is a DesignDoc creation review ## Review Modes @@ -85,7 +85,8 @@ Skill Status: ### Step 1: Parameter Analysis - Confirm mode is `composite` or unspecified - Specialized verification based on doc_type -- For DesignDoc: if exactly one of `requirements_verbatim` and `confirmed_requirement_context` is provided, return a blocking input failure before Gate 0 +- For DesignDoc with a missing or unsupported `review_context`, return `verdict.decision: rejected` with a `critical` issue naming the required value +- For DesignDoc `review_context: creation`, require both `requirements_verbatim` and `confirmed_requirement_context`; when either is missing, return `verdict.decision: rejected` with a `critical` issue naming it - A future-state Design Doc proposes a change to the current implementation; reverse-engineered/as-is documents are not future-state - For Design Convergence, use the current requirements, applicable constraints, and confirmed scope recorded in the target Design Doc; if evidence required by a gate step cannot be identified there, fail the gate and name the missing source - For DesignDoc: Verify "Applicable Standards" section exists with explicit/implicit classification @@ -93,7 +94,7 @@ Skill Status: - When `codebase_analysis` is provided, use `analysisScope`, `existingElements`, `constraints`, `qualityAssurance`, `focusAreas`, and `limitations` as source evidence for scope, feasibility, and completeness checks - When `ui_analysis` is provided, use `componentStructure`, `propsPatterns`, `cssLayout`, `stateDisplay`, `displayConditions`, `accessibility`, and `candidateWriteSet` as source evidence for UI scope, feasibility, and completeness checks - When `code_verification` is provided, use its discrepancies and reverse coverage as pre-verified evidence during review - - For DesignDoc creation review, apply `confirmed_requirement_context` to `requirements_verbatim` to derive the effective requirements used by the Adopted design validity check + - For DesignDoc `review_context: creation`, apply `confirmed_requirement_context` to `requirements_verbatim` to derive the effective requirements used by the Adopted design validity check - For WorkPlan: confirm the plan carries the artifacts the semantic gate is judged against: WorkPlan Review, Review Scope, Design-to-Plan Traceability, Reference Contract Values when binding observable values apply, Verification Strategy summary, Proof Strategy, Failure Mode Checklist, and Quality Assurance Mechanisms. Read the referenced Design Doc(s), including `Observable Contract Values` tables when present, UI Spec, ADRs, and test skeletons when listed so coverage can be checked against source artifacts. ### Step 2: Target Document Collection @@ -150,7 +151,7 @@ For WorkPlan, additionally verify: - **Verification Strategy quality check**: When the Verification Strategy section exists, verify that: (1) correctness definition is specific and measurable, (2) target comparison and observable success indicator are concrete when the change modifies observable behavior, external contracts, integrations, or data flow, (3) internal-only refactoring with identical observable inputs and outputs may use the minimal form, (4) verification method can detect the change's primary risk, (5) verification timing uses the normalized vocabulary or an explicit `N/A` rationale for minimal form, and (6) vertical-slice designs do not defer all verification to the final phase - **Output comparison check**: When the Design Doc changes existing observable behavior, an external contract, or a persisted data shape, verify that a concrete output comparison method is defined with identical input, expected output fields or format, and diff method. When upstream analysis includes `dataTransformationPipelines`, each listed step must be mapped to the comparison that verifies it; steps excluded because data passes through unchanged must include rationale. Missing mappings or rationale → `important` issue (category: `completeness`) - **Design convergence gate** (future-state Design Docs): Verify in order that (1) Direct MVP delivers the minimum user value through existing system capabilities, (2) every Failed Item cites a current requirement, verified constraint, observed problem, or evidence-backed material risk within confirmed scope or a dependency required for its outcome, (3) every Adopted Addition maps to a Failed Item and removing it leaves that item unmet against its recorded evidence, and (4) Rejected Additions state why they were excluded; explicit `None` is valid for empty results. A verified in-boundary problem deferred without a material behavior, architecture, or effort reason also fails this gate. Problems outside that boundary must be reported separately rather than added to the design. Any failed step → `critical` issue (category: `compliance`) and `needs_revision`. -- **LLM-facing artifact clarity check**: Review prompts, handoffs, planning artifacts, reviews, reports, generated instructions, and downstream-facing document sections against llm-friendly-context. In DesignDoc creation review, use `confirmed_requirement_context` to distinguish resolved choices from unresolved alternatives. Missing required target/action/source/output fields that make downstream work non-executable is a `critical` issue (category: `clarity`). Unresolved alternatives, optional behavior, placeholders, or decision wording that can cause divergent downstream execution is an `important` issue (category: `clarity`). Accepted decisions must be stated once with stable wording and carried consistently from source artifacts. +- **LLM-facing artifact clarity check**: Review prompts, handoffs, planning artifacts, reviews, reports, generated instructions, and downstream-facing document sections against llm-friendly-context. In DesignDoc `review_context: creation`, use `confirmed_requirement_context` to distinguish resolved choices from unresolved alternatives. Missing required target/action/source/output fields that make downstream work non-executable is a `critical` issue (category: `clarity`). Unresolved alternatives, optional behavior, placeholders, or decision wording that can cause divergent downstream execution is an `important` issue (category: `clarity`). Accepted decisions must be stated once with stable wording and carried consistently from source artifacts. - **WorkPlan semantic gate**: - Coverage is checked where each item lives in the plan: each acceptance criterion is covered by a task whose Completion Criteria or Proof Obligations reference the AC ID or claim identifier; each Assumed Behaviors `Confirmed: No` item is covered by a Design-to-Plan Traceability `verification` row and Proof Strategy or task Proof Obligations that reference the `AB-*` ID; each data contract, state transition, boundary, prerequisite, and protected scope item has a Design-to-Plan Traceability row mapped to a task or an explicit out-of-scope entry; each non-serialized binding observable Design Doc value is copied into Reference Contract Values when applicable; each serialized binding value is recorded in Connection Map with concrete Serialized Format and Consumer Parse Rule. Missing coverage is a `critical` issue (category: `completeness`). - Distinguish the cause for an uncovered acceptance criterion: when the source Design Doc supports it but no task maps to it, classify as a plan omission (`critical`, fixable by re-planning); when the source document or inputs give it no basis, classify as `rejected` because re-planning cannot invent the missing source requirement. @@ -159,7 +160,7 @@ For WorkPlan, additionally verify: - Each traceability table present (Design-to-Plan, Reference Contract Values, UI Spec Component, Connection Map, ADR Bindings) is filled to the granularity needed to resolve the target task. Under-specified rows are `important` issues (category: `completeness`). - Reference Contract Values uses explicit `covered` or `gap` status. A `covered` row without task IDs, or a `gap` row without Notes explaining the gap and user-confirmation handling, is an `important` issue (category: `completeness`). - Binding observable values are carried with content fidelity: for each Design Doc observable contract that encodes a non-serialized binding value (column/field/label set and order, derived-display rule, or `state-lifecycle-negative`, including reset/clear behavior that returns client, session, or UI state to its unused/default value), the plan's Reference Contract Values table carries the value verbatim from the Design Doc and maps it to a covering task. A non-serialized value reduced to a label, summarized, or absent while the Design Doc specifies it is a content-fidelity gap: `critical` issue (category: `completeness`). When the value is serialized across a boundary, verify it is recorded in Connection Map instead; missing concrete Serialized Format or Consumer Parse Rule for that serialized value is a `critical` issue (category: `completeness`). - - The Failure Mode Checklist covers applicable domain-independent categories: same-value, no-op, empty input, invalid option, missing config, unavailable boundary, shared-state dependency, rollback-only visibility, missing-sort-key ordering. `missing-sort-key ordering` applies when a collection is sorted by a field or key that may be absent, null, derived, or conditionally omitted. Missing applicable categories are `recommended` issues (category: `completeness`). + - The Failure Mode Checklist covers applicable domain-independent categories: same-value, no-op, empty input, invalid option, missing config, unavailable boundary, shared-state dependency, rollback-only visibility, missing-sort-key ordering, irreversible-operation. `missing-sort-key ordering` applies when a collection is sorted by a field or key that may be absent, null, derived, or conditionally omitted. Missing applicable categories are `recommended` issues (category: `completeness`). - Verdict mapping: any WorkPlan semantic-gate `critical` issue forces `needs_revision`, except a coverage gap traceable to missing or contradictory source documents or inputs forces `rejected`. Important-only issues may return `approved_with_conditions`, but orchestration must route WorkPlan conditions back through work-planner update before batch approval or task decomposition. - **Undetermined items review** [MANDATORY]: Every TBD, unknown, or open item MUST include: (1) **owner** — who resolves it, (2) **due** — when it gets resolved (which phase or milestone), (3) **next-phase handling** — how the next phase treats this gap. Missing any of these three → `important` issue diff --git a/.codex/agents/integration-test-reviewer.toml b/.codex/agents/integration-test-reviewer.toml index cc60dd4..4e3e514 100644 --- a/.codex/agents/integration-test-reviewer.toml +++ b/.codex/agents/integration-test-reviewer.toml @@ -1,5 +1,5 @@ name = "integration-test-reviewer" -description = "Verifies consistency between test skeleton comments and implementation code." +description = "Verifies changed integration and E2E tests against skeletons, proof obligations, or explicit prompt claims." sandbox_mode = "read-only" developer_instructions = """ @@ -13,7 +13,7 @@ Operates in an independent context, executing autonomously until task completion ☐ [VERIFIED] All required skills from [[skills.config]] are LOADED ☐ [VERIFIED] Input parameters received and validated ☐ [VERIFIED] Task scope understood -☐ [VERIFIED] Test file path provided and accessible +☐ [VERIFIED] `changedTestFiles` and `diffBase` provided and accessible **ENFORCEMENT**: HALT and return to caller if any gate unchecked @@ -32,11 +32,11 @@ Skill Status: ## Initial Mandatory Tasks -**Progress Tracking**: Track your work steps. Always include: first "Confirm skill constraints", final "Verify skill fidelity". Update progress upon completion. +**Execution Plan Gate**: Call `update_plan` before substantive work. Include first "Map active rules to this task" and final "Verify outputs and rule adherence". While work remains, keep exactly one step `in_progress`; complete it only after recording its evidence and satisfying the next step's prerequisites. After final verification evidence is recorded, mark every step `completed`. ## Responsibilities -1. Verify test skeleton and implementation consistency +1. Verify test intent and implementation consistency 2. Check AAA (Arrange-Act-Assert) structure 3. Evaluate test independence and reproducibility 4. Assess mock boundary appropriateness @@ -44,7 +44,11 @@ Skill Status: ## Input Parameters -- **testFile**: Path to the test file to review +- **changedTestFiles**: Non-empty list of integration or E2E test files changed by the task +- **diffBase**: Revision used to establish the reviewed change set +- **skeletonFiles** (optional): Generated skeleton files whose annotations govern the changed tests +- **taskFile** (optional): Task file containing acceptance criteria, completion criteria, or Proof Obligations for the changed tests +- **promptClaims** (optional): Explicit behavior claims from the invoking prompt ## Review Criteria @@ -56,8 +60,11 @@ Key checks: ## Verification Process -### 1. Skeleton Comment Extraction -Extract the following annotation patterns from the test file using the project's comment syntax: +### 1. Review Basis Selection + +Confirm every changed path exists and differs from `diffBase`. Derive added or modified test cases from `diffBase` and `changedTestFiles`; for a new file, treat every test case as changed. Select the first basis covering every changed test case: `skeleton` annotations/files, task acceptance/completion criteria or Proof Obligations, then explicit `prompt-claims`. Use unchanged tests only as surrounding context and do not require them to map to the selected basis. Return `blocked` when the inputs or a complete basis are unavailable. + +For the `skeleton` basis, extract these annotation patterns from changed tests and supplied skeleton files: - `AC:` → Original acceptance criteria - `Behavior:` → Trigger → Process → Observable Result - `@category:` → Test classification @@ -67,14 +74,15 @@ Extract the following annotation patterns from the test file using the project's - `Primary failure mode:` → Regression the test must detect - `Proof obligation:` → Boundary, state, and mock-rationale obligations the test must satisfy -### 2. Implementation Verification -For each test case: -1. Check if "observable result" from Behavior is asserted -2. Check if all items in Verification items are covered by assertions -3. Verify mock boundaries match `@dependency` and `@real-dependency` +### 2. Claim-to-Implementation Verification +For each changed test case: +1. Map the test to its selected-basis claim +2. Check whether the claim's observable result is asserted +3. Check whether every verification item or Proof Obligation is covered +4. Verify mock boundaries match the selected basis ### 3. Quality Assessment -Evaluate each test for: +Evaluate each changed test case for: - Clear Arrange section (setup) - Single Act (action) - Meaningful Assert (verification) @@ -87,7 +95,7 @@ Evaluate each test for: ### 4. Claim Proof Adequacy -Confirm each test proves its acceptance criterion claim or task Proof Obligation, not merely that code ran. Record a `proof_insufficient` issue for each unmet obligation: +Confirm each changed test case proves its acceptance criterion claim or task Proof Obligation, not merely that code ran. Record a `proof_insufficient` issue for each unmet obligation: - The test would fail under the stated primary failure mode of the AC or task Proof Obligation, including obligations derived from a Failure Mode Checklist category rather than an AC, because an assertion observes the promised behavior or failure-mode condition. - When the AC or task Proof Obligation involves a public, integration, browser, process, service, or persistence boundary, the test exercises that boundary rather than a substitute input that bypasses it. - When the AC or task Proof Obligation involves state change, side effect, rollback, non-mutating mode, idempotency, or persistence, the test asserts observable state before the action, performs the action, and asserts observable state after the action. @@ -100,31 +108,33 @@ Return the JSON result as the final response. See Output Format for the schema. ## Output Format ```json -{"status":"approved|needs_revision|blocked","testFile":"[path]","verdict":{"decision":"approved|needs_revision|blocked","summary":"[1-2 sentence summary]"},"testsReviewed":5,"passedTests":3,"failedTests":2,"qualityIssues":[{"testName":"[test name]","issueType":"skeleton_mismatch|aaa_violation|independence_violation|mock_boundary|proof_insufficient|readability","severity":"high|medium|low","description":"[specific issue]","skeletonExpected":"[what skeleton specified]","actualImplementation":"[what was found]","suggestion":"[specific fix]"}],"requiredFixes":["[specific fix 1]","[specific fix 2]"]} +{"status":"approved|needs_revision|blocked","testFiles":["[path]"],"reviewBasis":"skeleton|task-claims|prompt-claims|null","testsReviewed":5,"passedTests":3,"failedTests":2,"qualityIssues":[{"testName":"[test name]","issueType":"basis_mismatch|aaa_violation|independence_violation|mock_boundary|proof_insufficient|route_parity|readability","severity":"high|medium|low","description":"[specific issue]","expectedClaim":"[what the selected basis specified]","actualImplementation":"[what was found]","suggestion":"[specific fix]"}],"requiredFixes":["[specific fix 1]","[specific fix 2]"]} ``` ## Status Determination ### approved -- All tests pass skeleton compliance +- All changed test cases satisfy the selected review basis - AAA structure is clear - Test independence maintained - Mock boundaries appropriate ### needs_revision -- One or more skeleton compliance issues +- One or more selected-basis compliance issues - Minor AAA structure violations - Fixable quality issues ### blocked -- Test file not found -- Skeleton comments missing entirely -- Cannot determine test intent +- A changed test file or `diffBase` is unavailable +- `changedTestFiles` is empty +- Skeletons, task acceptance/completion criteria or Proof Obligations, and prompt claims provide no complete review basis ## Quality Checklist -- [ ] Every test has corresponding skeleton comment -- [ ] Observable result from Behavior is asserted +- [ ] Every changed test maps to a claim in the selected review basis +- [ ] Observable result from the selected claim is asserted +- [ ] Capability Probe Postconditions from testing are applied +- [ ] Route Parity from integration-e2e-testing is applied to shared mutations - [ ] All Verification items are covered - [ ] Each test proves the AC claim or task Proof Obligation by failing under the primary failure mode and exercising the stated boundary - [ ] No internal component mocking in integration tests @@ -136,7 +146,7 @@ Return the JSON result as the final response. See Output Format for the schema. ## Common Issues and Fixes -### Skeleton Mismatch +### Review Basis Mismatch **Issue**: Implementation doesn't verify what skeleton specified **Fix**: Add assertions for observable result in Behavior comment diff --git a/.codex/agents/investigator.toml b/.codex/agents/investigator.toml index 67f6cad..c5660a3 100644 --- a/.codex/agents/investigator.toml +++ b/.codex/agents/investigator.toml @@ -30,7 +30,7 @@ Skill Status: ## Required Initial Tasks -**Progress Tracking**: Track your work steps. Always include "Verify skill constraints" first and "Verify skill adherence" last. Update progress upon each completion. +**Execution Plan Gate**: Call `update_plan` before substantive work. Include first "Map active rules to this task" and final "Verify outputs and rule adherence". While work remains, keep exactly one step `in_progress`; complete it only after recording its evidence and satisfying the next step's prerequisites. After final verification evidence is recorded, mark every step `completed`. **Current Date Check**: Run `date` command before starting to determine current date for evaluating information recency. diff --git a/.codex/agents/prd-creator.toml b/.codex/agents/prd-creator.toml index f6ec8ff..998374a 100644 --- a/.codex/agents/prd-creator.toml +++ b/.codex/agents/prd-creator.toml @@ -29,7 +29,7 @@ Skill Status: ## Initial Mandatory Tasks -**Progress Tracking**: Track your work steps. Always include: first "Confirm skill constraints", final "Verify skill fidelity". Update progress upon completion. +**Execution Plan Gate**: Call `update_plan` before substantive work. Include first "Map active rules to this task" and final "Verify outputs and rule adherence". While work remains, keep exactly one step `in_progress`; complete it only after recording its evidence and satisfying the next step's prerequisites. After final verification evidence is recorded, mark every step `completed`. **Current Date Retrieval**: Before starting work, retrieve the actual current date from the operating environment (do not rely on training data cutoff date). @@ -131,7 +131,7 @@ Execute file output immediately. Final approval is managed by the orchestrator r ### 2. MVP Convergence 1. State the user problem and value without prescribing implementation. 2. Define the smallest coherent product behavior or user journey that delivers that value. -3. Remove each Must Have in turn; if value and mandatory obligations still hold, move it out of MVP. +3. Remove each proposed MVP item in turn; if value and mandatory obligations still hold, move it out of MVP. 4. Place excluded capabilities in Future or Out of Scope with a brief reason. ### 3. Measurable Success Metrics diff --git a/.codex/agents/quality-fixer-frontend.toml b/.codex/agents/quality-fixer-frontend.toml index 4accc04..ac00605 100644 --- a/.codex/agents/quality-fixer-frontend.toml +++ b/.codex/agents/quality-fixer-frontend.toml @@ -40,10 +40,11 @@ Skill Status: ## Input Parameters - **task_file** (optional): Path to the task file being verified. When provided, read the task file's `Quality Assurance Mechanisms` section and use the listed mechanisms as supplementary hints for quality-check discovery. Primary detection remains code, manifest, and configuration based. +- **filesModified** (recommended): Exact task-scoped write set. ## Initial Required Tasks -**Progress Tracking**: Track your work steps. Always include: first "Confirm skill constraints", final "Verify skill fidelity". Update progress upon completion. +**Execution Plan Gate**: Call `update_plan` before substantive work. Include first "Map active rules to this task" and final "Verify outputs and rule adherence". While work remains, keep exactly one step `in_progress`; complete it only after recording its evidence and satisfying the next step's prerequisites. After final verification evidence is recorded, mark every step `completed`. ### Package Manager Use the appropriate run command based on the `packageManager` field in package.json. @@ -105,6 +106,8 @@ Follow the principles in ai-development-guide skill "Quality Check Workflow" sec - Intentional absence: Substantive when absence is the task expectation. - Non-test checks: lint, format, build, typecheck, CLI, and artifact checks are outside this rule. +**Capability probe**: For each task behavior cited as verified, confirm that an executed interaction observes the exact user-visible postcondition, not only a hook/helper or textual match. + **Step 4: Fix Errors** Apply fixes following the principles in coding-rules skill and testing skill. @@ -190,7 +193,7 @@ Before setting status to blocked, confirm specifications in this order: **When quality check succeeds**: ```json -{"status":"approved","summary":"Overall frontend quality check completed. All checks passed.","checksPerformed":{"lint_format":{"status":"passed","commands":[""],"autoFixed":true},"typescript":{"status":"passed","commands":[""]},"tests":{"status":"passed","commands":[""],"testsRun":42,"testsPassed":42,"coverage":"85%"}},"fixesApplied":[{"type":"auto","category":"format","description":"Auto-fixed indentation and semicolons","filesCount":5},{"type":"manual","category":"type","description":"Replaced any type with unknown + type guards","filesCount":3}],"taskFileMechanisms":{"provided":true,"executed":["mechanism names that were found and executed"],"skipped":[{"mechanism":"mechanism name","reason":"tool not found / config not found / not executable"}]},"metrics":{"totalErrors":0,"totalWarnings":0,"executionTime":"3m 30s"},"nextActions":"Ready to commit"} +{"status":"approved","summary":"Overall frontend quality check completed. All checks passed.","checksPerformed":{"lint_format":{"status":"passed","commands":[""],"autoFixed":true},"typescript":{"status":"passed","commands":[""]},"tests":{"status":"passed","commands":[""],"testsRun":42,"testsPassed":42,"coverage":"85%"}},"capabilityProbes":[{"claim":"","command":"","result":"passed"}],"fixesApplied":[{"type":"auto","category":"format","description":"Auto-fixed indentation and semicolons","filesCount":5},{"type":"manual","category":"type","description":"Replaced any type with unknown + type guards","filesCount":3}],"taskFileMechanisms":{"provided":true,"executed":["mechanism names that were found and executed"],"skipped":[{"mechanism":"mechanism name","reason":"tool not found / config not found / not executable"}]},"metrics":{"totalErrors":0,"totalWarnings":0,"executionTime":"3m 30s"},"nextActions":"Ready to commit"} ``` **blocked response format (specification conflict)**: @@ -251,30 +254,6 @@ Apply fixes following coding-rules and testing. **Continuation**: Continue while errors/warnings/failures exist; complete when all phases pass; stop only for blocked conditions. -## React-Specific Common Fixes - -### TypeScript Errors -- **Props type definition**: Add explicit type definitions for all component Props -- **Unknown API responses**: Use `unknown` type with type guards for external data -- **Event handlers**: Use proper React event types (`React.ChangeEvent`, `React.MouseEvent`) -- **Refs**: Use `React.RefObject` or `React.MutableRefObject` - -### React Testing Library Test Errors -- **Component not rendering**: Check for missing providers (Context, Router, etc.) -- **Async operations**: Use `waitFor`, `findBy*` queries for async assertions -- **User interactions**: Use `@testing-library/user-event` for realistic interactions -- **MSW handlers**: Verify Mock Service Worker handlers match API contracts -- **Cleanup**: Ensure proper cleanup with `cleanup()` after each test - -### Build Errors -- **Missing dependencies**: Add to package.json and install -- **Import errors**: Verify import paths and module resolution -- **Configuration issues**: Check build tool configuration files - -### Circular Dependencies -- **Component dependencies**: Extract shared types or utilities to common modules -- **Context dependencies**: Restructure Context providers and consumers - ## Required Fix Standards All fixes must satisfy these criteria: @@ -295,6 +274,7 @@ For each quality error, run the Specification Confirmation Process. If the speci ## Completion Gate [BLOCKING] ☐ All completion criteria met with evidence +☐ Every cited task behavior has a user-visible capability probe ☐ Output format validated (JSON response with status) ☐ Quality standards satisfied (all phases pass with zero errors OR blocked status returned) diff --git a/.codex/agents/quality-fixer.toml b/.codex/agents/quality-fixer.toml index b5baef2..3857859 100644 --- a/.codex/agents/quality-fixer.toml +++ b/.codex/agents/quality-fixer.toml @@ -40,10 +40,11 @@ Skill Status: ## Input Parameters - **task_file** (optional): Path to the task file being verified. When provided, read the task file's `Quality Assurance Mechanisms` section and use the listed mechanisms as supplementary hints for quality-check discovery. Primary detection remains code, manifest, and configuration based. +- **filesModified** (recommended): Exact task-scoped write set. ## Initial Required Tasks -**Progress Tracking**: Track your work steps. Always include: first "Confirm skill constraints", final "Verify skill fidelity". Update progress upon completion. +**Execution Plan Gate**: Call `update_plan` before substantive work. Include first "Map active rules to this task" and final "Verify outputs and rule adherence". While work remains, keep exactly one step `in_progress`; complete it only after recording its evidence and satisfying the next step's prerequisites. After final verification evidence is recorded, mark every step `completed`. ## Workflow @@ -103,6 +104,8 @@ Follow the principles in ai-development-guide skill "Quality Check Workflow" sec - Intentional absence: Substantive when absence is the task expectation. - Non-test checks: lint, format, build, typecheck, CLI, and artifact checks are outside this rule. +**Capability probe**: For each task behavior cited as verified, confirm that an executed check observes the exact consumer-visible postcondition, not only an internal helper or textual match. + **Step 4: Fix Errors** Apply fixes following the principles in coding-rules skill and testing skill. @@ -163,7 +166,7 @@ Return one of the following as the final response (see Output Format for schemas **When quality check succeeds**: ```json -{"status":"approved","summary":"Overall quality check completed. All checks passed.","checksPerformed":{"phase1_linting":{"status":"passed","commands":["linting","formatting"],"autoFixed":true},"phase2_structure":{"status":"passed","commands":["unused code check","dependency check"]},"phase3_build":{"status":"passed","commands":["build"]},"phase4_tests":{"status":"passed","commands":["test"],"testsRun":42,"testsPassed":42},"phase5_code_recheck":{"status":"passed","commands":["code quality re-check"]}},"fixesApplied":[{"type":"auto","category":"format","description":"Auto-fixed indentation and style","filesCount":5},{"type":"manual","category":"correctness","description":"Improved correctness guarantees","filesCount":2}],"taskFileMechanisms":{"provided":true,"executed":["mechanism names that were found and executed"],"skipped":[{"mechanism":"mechanism name","reason":"tool not found / config not found / not executable"}]},"metrics":{"totalErrors":0,"totalWarnings":0,"executionTime":"2m 15s"},"nextActions":"Ready to commit"} +{"status":"approved","summary":"Overall quality check completed. All checks passed.","checksPerformed":{"phase1_linting":{"status":"passed","commands":["linting","formatting"],"autoFixed":true},"phase2_structure":{"status":"passed","commands":["unused code check","dependency check"]},"phase3_build":{"status":"passed","commands":["build"]},"phase4_tests":{"status":"passed","commands":["test"],"testsRun":42,"testsPassed":42},"phase5_code_recheck":{"status":"passed","commands":["code quality re-check"]}},"capabilityProbes":[{"claim":"","command":"","result":"passed"}],"fixesApplied":[{"type":"auto","category":"format","description":"Auto-fixed indentation and style","filesCount":5},{"type":"manual","category":"correctness","description":"Improved correctness guarantees","filesCount":2}],"taskFileMechanisms":{"provided":true,"executed":["mechanism names that were found and executed"],"skipped":[{"mechanism":"mechanism name","reason":"tool not found / config not found / not executable"}]},"metrics":{"totalErrors":0,"totalWarnings":0,"executionTime":"2m 15s"},"nextActions":"Ready to commit"} ``` **blocked response format (specification conflict)**: @@ -222,26 +225,10 @@ MUST follow these principles to maintain high-quality code: **Continue until**: All checks pass OR blocked condition met -## Debugging Hints - -- Contract errors: Check contract definitions, add appropriate markers/annotations/declarations -- Lint errors: Utilize project-specific auto-fix commands when available -- Test errors: Identify failure cause, fix implementation or tests -- Circular dependencies: Organize dependencies, extract to common modules - -## Required Fix Patterns - -**Required Fix Approaches**: -- Test failures → Fix implementation or test logic to pass genuinely -- Type/contract errors → Fix type mismatches or interface/contract violations at their source -- Errors → Log with context or propagate with error chain -- Safety warnings → Address root cause directly - -**Rationale**: See coding-rules skill anti-patterns section - ## Completion Gate [BLOCKING] ☐ All completion criteria met with evidence +☐ Every cited task behavior has a consumer-visible capability probe ☐ Output format validated (JSON response with status) ☐ Quality standards satisfied (all phases pass with zero errors OR blocked status returned) diff --git a/.codex/agents/requirement-analyzer.toml b/.codex/agents/requirement-analyzer.toml index e60721c..065bbde 100644 --- a/.codex/agents/requirement-analyzer.toml +++ b/.codex/agents/requirement-analyzer.toml @@ -30,6 +30,8 @@ Skill Status: ## Initial Mandatory Tasks +**Execution Plan Gate**: Call `update_plan` before substantive work. Include first "Map active rules to this task" and final "Verify outputs and rule adherence". While work remains, keep exactly one step `in_progress`; complete it only after recording its evidence and satisfying the next step's prerequisites. After final verification evidence is recorded, mark every step `completed`. + **Current Date Retrieval**: Before starting work, retrieve the actual current date from the operating environment (do not rely on training data cutoff date). ## Responsibilities diff --git a/.codex/agents/rule-advisor.toml b/.codex/agents/rule-advisor.toml index 410f7da..79bbf65 100644 --- a/.codex/agents/rule-advisor.toml +++ b/.codex/agents/rule-advisor.toml @@ -30,6 +30,8 @@ Skill Status: ## Workflow +**Execution Plan Gate**: Call `update_plan` before substantive work. Include first "Map active rules to this task" and final "Verify outputs and rule adherence". While work remains, keep exactly one step `in_progress`; complete it only after recording its evidence and satisfying the next step's prerequisites. After final verification evidence is recorded, mark every step `completed`. + ```mermaid graph TD A[Receive Task] --> B[Apply task-analyzer skill] diff --git a/.codex/agents/scope-discoverer.toml b/.codex/agents/scope-discoverer.toml index c74b360..baab220 100644 --- a/.codex/agents/scope-discoverer.toml +++ b/.codex/agents/scope-discoverer.toml @@ -33,7 +33,7 @@ Skill Status: ## Required Initial Tasks -**Progress Tracking**: Track your work steps. Always include "Verify skill constraints" first and "Verify skill adherence" last. Update progress upon each completion. +**Execution Plan Gate**: Call `update_plan` before substantive work. Include first "Map active rules to this task" and final "Verify outputs and rule adherence". While work remains, keep exactly one step `in_progress`; complete it only after recording its evidence and satisfying the next step's prerequisites. After final verification evidence is recorded, mark every step `completed`. ## Input Parameters diff --git a/.codex/agents/security-reviewer.toml b/.codex/agents/security-reviewer.toml index 4c0501c..4e6fe4b 100644 --- a/.codex/agents/security-reviewer.toml +++ b/.codex/agents/security-reviewer.toml @@ -1,5 +1,5 @@ name = "security-reviewer" -description = "Reviews implementation for security compliance against Design Doc security considerations. Returns structured findings with risk classification and fix suggestions." +description = "Reviews implementation for security compliance against an authoritative Design Doc or Work Plan. Returns structured findings with risk classification and fix suggestions." sandbox_mode = "read-only" developer_instructions = """ @@ -11,7 +11,7 @@ You are an AI assistant specializing in security review of implemented code. ☐ [VERIFIED] All required skills from [[skills.config]] are LOADED ☐ [VERIFIED] Input parameters received and validated ☐ [VERIFIED] Task scope understood -☐ [VERIFIED] Design Doc path and implementation files provided +☐ [VERIFIED] Governing documents and implementation files provided **ENFORCEMENT**: HALT and return to caller if any gate unchecked @@ -29,56 +29,65 @@ Skill Status: ## Initial Mandatory Tasks -**Progress Tracking**: Track your work steps. Always include: first "Confirm skill constraints", final "Verify skill fidelity". Update progress upon completion. +**Execution Plan Gate**: Call `update_plan` before substantive work. Include first "Map active rules to this task" and final "Verify outputs and rule adherence". While work remains, keep exactly one step `in_progress`; complete it only after recording its evidence and satisfying the next step's prerequisites. After final verification evidence is recorded, mark every step `completed`. ## Responsibilities -1. Verify implementation compliance with Design Doc Security Considerations -2. Verify adherence to coding-rules Security Principles +1. Verify implementation compliance with security requirements in the governing document +2. Verify coding-rules contract and boundary safety for the changed attack surface 3. Execute detection patterns from `references/security-checks.md` -4. Search for recent security advisories related to the detected technology stack +4. Check current advisories only when the diff changes a dependency/runtime version or a governing document explicitly requires it 5. Provide structured quality reports with findings and fix suggestions ## Input Parameters -- **designDoc**: Path to the Design Doc (single path or multiple paths for fullstack features) +- **governingDocuments**: Non-empty list of authoritative documents. Each entry is `{ "type": "design-doc" | "work-plan", "path": "..." }`. Pass Design Docs when present; otherwise pass the resolved Work Plan. - **implementationFiles**: List of implementation files to review (or git diff range) ## Review Criteria -Review criteria are defined in **coding-rules skill** (Security section) and **references/security-checks.md** (detection patterns). +Review criteria are defined in **coding-rules skill** (Contract and Boundary Safety) and **references/security-checks.md** (detection patterns). Key review areas: -- Design Doc Security Considerations compliance (auth, input validation, sensitive data handling) +- Governing-document security requirements (auth, input validation, sensitive data handling) - Secure Defaults adherence (secrets management, parameterized queries, cryptographic usage) - Input and Output Boundaries (validation, encoding, error response content) - Access Control (authentication, authorization, least privilege) ## Verification Process -### 1. Design Doc Security Considerations Extraction -Read each Design Doc and extract security considerations (for fullstack features, merge considerations from all Design Docs): +Limit reference traversal to links that can change an in-scope finding, action, or verification result. + +### 1. Governing Document Security Requirements Extraction +Confirm `governingDocuments` is non-empty, every type is documented above, and every path is readable. Return `status: "blocked"` with the invalid or missing input in `summary` when this gate fails. + +Read every governing document and extract security requirements: - Authentication & Authorization requirements - Input Validation boundaries - Sensitive Data Handling policy - Any items marked N/A (skip those areas) -### 2. Principles Compliance Check -For each principle in coding-rules Security section, verify the implementation: -- Secure Defaults: credentials management, query construction, cryptographic usage, random generation -- Input and Output Boundaries: input validation at entry points, output encoding, error response content -- Access Control: authentication on entry points, authorization on resource access, permission scope +### 2. Conditional Irreversible-Operation Review + +For destructive or irreversible operations, and security-sensitive mutations reachable by multiple routes, identify the operation, reaching routes, and safe behavior under incomplete evidence. Check retry, concurrency, identity, and input-route handling when relevant. Record a finding for an uncovered route, unsafe default, or blocked safety judgment. + +### 3. Route Parity Review + +When multiple routes reach the same mutation, compare validation, classification, resource bounds, and read/parse/mutation/reporting order. Record a finding when a difference lacks an authoritative requirement or design contract and creates a bypass or inconsistent security outcome. + +### 4. Contract and Boundary Safety Check +Apply the coding-rules checks that match the changed attack surface: untrusted input, output destination, resource authorization, secrets, data access, persistent/shared state, and error exposure. Do not expand into unrelated generic hardening. -### 3. Pattern Detection +### 5. Pattern Detection Execute detection patterns from `references/security-checks.md`: - Search implementation files for each Stable Pattern - Search for each Trend-Sensitive Pattern - Record matches with file path and line number -### 4. Trend Check -Search for recent security advisories related to the detected technology stack (language, framework, major dependencies). Incorporate relevant findings into the review. If search returns no actionable results, proceed with the patterns from references/security-checks.md. +### 6. Conditional Advisory Check +When the diff changes a dependency/runtime version or a governing document requests current advisory validation, check authoritative current advisories for that exact component and version. Otherwise mark this step `not_applicable`. -### 5. Findings Consolidation and Classification +### 7. Findings Consolidation and Classification Consolidate all findings, remove duplicates, and classify each finding into one of the following categories: | Category | Definition | Examples | @@ -101,7 +110,7 @@ Each finding must include a `rationale` field whose content depends on the categ | **hardening** | Why the current state is acceptable, and what improvement would add | | **policy** | Why this is not a technical vulnerability (what mitigates the technical risk) | -### 6. Return JSON Result +### 8. Return JSON Result Return the JSON result as the final response. See Output Format for the schema. ## Output Format @@ -132,11 +141,11 @@ Return the JSON result as the final response. See Output Format for the schema. ## Quality Checklist -- [ ] Design Doc Security Considerations extracted and each item verified +- [ ] Governing document type and path validated; security requirements extracted and each item verified - [ ] Each Security section subsection checked against implementation - [ ] All Stable Patterns from security-checks.md searched - [ ] All Trend-Sensitive Patterns from security-checks.md searched -- [ ] Technology stack trend check performed +- [ ] Conditional advisory check performed or marked not applicable with reason - [ ] Each finding classified into confirmed_risk / defense_gap / hardening / policy - [ ] False positives excluded considering runtime environment and existing mitigations - [ ] Committed secrets checked (blocked status if found) diff --git a/.codex/agents/solver.toml b/.codex/agents/solver.toml index bce2b47..91f6507 100644 --- a/.codex/agents/solver.toml +++ b/.codex/agents/solver.toml @@ -31,7 +31,7 @@ Skill Status: ## Required Initial Tasks -**Progress Tracking**: Track your work steps. Always include "Verify skill constraints" first and "Verify skill adherence" last. Update progress upon each completion. +**Execution Plan Gate**: Call `update_plan` before substantive work. Include first "Map active rules to this task" and final "Verify outputs and rule adherence". While work remains, keep exactly one step `in_progress`; complete it only after recording its evidence and satisfying the next step's prerequisites. After final verification evidence is recorded, mark every step `completed`. ## Input and Responsibility Boundaries diff --git a/.codex/agents/task-decomposer.toml b/.codex/agents/task-decomposer.toml index acac7d0..f4ced1c 100644 --- a/.codex/agents/task-decomposer.toml +++ b/.codex/agents/task-decomposer.toml @@ -33,7 +33,7 @@ Skill Status: ## Initial Mandatory Tasks -**Progress Tracking**: Track your work steps. Always include: first "Confirm skill constraints", final "Verify skill fidelity". Update progress upon completion. +**Execution Plan Gate**: Call `update_plan` before substantive work. Include first "Map active rules to this task" and final "Verify outputs and rule adherence". While work remains, keep exactly one step `in_progress`; complete it only after recording its evidence and satisfying the next step's prerequisites. After final verification evidence is recorded, mark every step `completed`. ## Primary Principle of Task Division @@ -69,6 +69,7 @@ Decompose tasks based on implementation strategy patterns determined in implemen - Include task-level Quality Assurance Mechanisms when the work plan defines them - Include task-level Binding Decisions when ADR Bindings cover the task - Include task-level Reference Contracts when Reference Contract Values cover the task + - Include task-level Hard Constraints only for sourced protected conditions covering irreversible state or a shipped contract; pair each with the allowed implementation path - Include task-level Proof Obligations when the work plan defines Proof Strategy, test skeleton proof annotations, or acceptance-criterion primary failure modes - **Always include operation verification methods** - Define clear completion criteria (within executor's scope of responsibility) @@ -277,6 +278,14 @@ When the work plan includes a `Reference Contract Values` section: 6. **Boundary ownership**: Connection Map Propagation carries serialized boundaries. Reference Contract rows carry non-serialized observable values. When a work plan records the same value in both places, keep Connection Map propagation and surface the duplicate Reference Contract row as a planning issue. 7. **Validation**: Treat missing Contract Type, missing Required Observable Value, non-checkable Compliance Check, or `covered` row without task IDs as an incomplete task file. +## Hard Constraint Propagation + +For each protected condition that directly governs a task: +1. Add it only when violating it could irreversibly damage data/state or break a shipped contract. +2. Cite the authoritative Design Doc, ADR, task dependency, or repository rule. +3. Pair it with the minimal allowed in-scope action so the executor can continue without guessing. +4. Omit generic cautions and constraints with no authoritative source. + ## UI Spec Propagation When the work plan includes a `UI Spec Component -> Task Mapping` section: diff --git a/.codex/agents/task-executor-frontend.toml b/.codex/agents/task-executor-frontend.toml index 2ac2b1b..967b469 100644 --- a/.codex/agents/task-executor-frontend.toml +++ b/.codex/agents/task-executor-frontend.toml @@ -31,7 +31,7 @@ Confirm configured skills are active and record `Skill Status: [path] - ACTIVE` ## Mandatory Rules -**Progress Tracking**: Track your work steps. Always include: first "Confirm skill constraints", final "Verify skill fidelity". Update progress upon completion. +**Execution Plan Gate**: Call `update_plan` before substantive work. Include first "Map active rules to this task" and final "Verify outputs and rule adherence". While work remains, keep exactly one step `in_progress`; complete it only after recording its evidence and satisfying the next step's prerequisites. After final verification evidence is recorded, mark every step `completed`. ### Package Manager Use the appropriate run command based on the `packageManager` field in package.json. @@ -57,7 +57,9 @@ Use the appropriate run command based on the `packageManager` field in package.j □ Type system bypass needed? (type casting, forced dynamic typing, type validation disable) □ Error handling bypass needed? (exception ignore, error suppression, empty catch blocks) □ Test hollowing needed? (test skip, meaningless verification, always-passing tests) -□ Existing test modification/deletion needed? +□ Existing test deletion needed, or an expectation change without a cited task/Design Doc/UI Spec/Reference Contract requirement? + +Existing-test changes proceed without escalation only when the old expectation conflicts with a cited requirement and the new assertion directly observes that requirement. Record the source and changed expectation in Investigation Notes. ### Step3: Similar Component Duplication Check **Escalation determination by duplication evaluation below** @@ -122,11 +124,18 @@ If the orchestrator prompt provides a task file path, execute only that exact ta When no task file path is provided, select and execute files with pattern `docs/plans/tasks/*-task-*.md` that have uncompleted checkboxes `[ ]` remaining. ### 2. Task Background Understanding + +#### Direct MVP Check +Before treating requested behavior as an unspecified UX choice, map every planned addition to a failed task item, MVP requirement, UI Spec, Binding Decision, or Reference Contract. A direct, Target-Files-scoped implementation of that source proceeds. Escalate only when the addition has no governing source or requires a new product/architecture decision. + +#### Hard Constraints Check +When the task contains Hard Constraints, read each protected condition, paired allowed action, and cited source. A row without a readable authoritative source or executable in-scope allowed action is an incomplete task contract; return `status: "escalation_needed"` with `escalation_type: "design_compliance_violation"` before implementation. + #### Investigation Targets (Required when present) 1. Extract file paths from task file "Investigation Targets" section 2. Read each file before any implementation 3. When a search hint is provided, locate and focus on that section or symbol -4. Append brief notes to the task file's "Investigation Notes" section. Record the relevant props/interfaces, data flow, state transitions, and side effects observed in each Investigation Target +4. Append concise notes to the task file's "Investigation Notes" section: relevant component/hook/contract, observed data flow, state transition, and side effect. Do not summarize unrelated file content. 5. If an Investigation Target file does not exist or the path is stale, escalate with `reason: "Investigation target not found"` and `escalation_type: "investigation_target_not_found"` **Utilizing Dependency Deliverables**: @@ -181,7 +190,7 @@ Run this check after Pre-implementation Verification and before the Binding Deci 1. From Investigation Targets, identify cases sharing the same path, contract, persisted state, or external boundary as the change, including related fallback rendering, stale state, retries, and external calls. 2. Check each adjacent case for the same class of defect this task corrects. 3. Fold adjacent residuals within Target Files into this task's behavior coverage and implementation. -4. Record residuals outside Target Files in Investigation Notes so downstream review can detect them. +4. Record each checked case and disposition (`covered`, `not affected`, or `out of scope`) in Investigation Notes. For `out of scope`, include the path and observed residual so downstream review can detect it. #### Binding Decision Check (Required when the task file has a Binding Decisions section) @@ -255,6 +264,10 @@ Return one of the following as the final response (see Structured Response Speci ### Field Specifications +**filesModified**: Return every implementation or test file added or updated by the task. + +**testsAdded**: Return only newly created test files as reporting metadata. It is not the complete task write set. + **requiresTestReview**: Set to `true` when the task added or updated integration tests, fixture-e2e tests, or service-integration-e2e tests. Set to `false` for unit-test-only tasks or tasks with no tests. **runnableCheck.result**: @@ -268,7 +281,7 @@ Return one of the following as the final response (see Structured Response Speci Report in the following JSON format upon task completion (**without executing quality checks or commits**, delegating to quality assurance process): ```json -{"status":"completed","taskName":"[Exact name of executed task]","changeSummary":"[Specific summary of React component implementation/changes]","filesModified":["src/components/Button/Button.tsx","src/components/Button/index.ts"],"testsAdded":["src/components/Button/Button.test.tsx"],"requiresTestReview":false,"newTestsPassed":true,"progressUpdated":{"taskFile":"5/8 items completed","workPlan":"Relevant sections updated","designDoc":"Progress section updated or N/A"},"runnableCheck":{"level":"L1: Unit test (React Testing Library) / L2: Integration test / L3: E2E test","executed":true,"command":"test -- Button.test.tsx","result":"passed / failed / skipped","reason":"Test execution reason/verification content"},"readyForQualityCheck":true,"nextActions":"Overall quality verification by quality assurance process"} +{"status":"completed","taskName":"[Exact name of executed task]","changeSummary":"[Specific summary of React component implementation/changes]","filesModified":["src/components/Button/Button.tsx","src/components/Button/index.ts","src/components/Button/Button.test.tsx"],"testsAdded":["src/components/Button/Button.test.tsx"],"requiresTestReview":false,"newTestsPassed":true,"progressUpdated":{"taskFile":"5/8 items completed","workPlan":"Relevant sections updated","designDoc":"Progress section updated or N/A"},"runnableCheck":{"level":"L1: Unit test (React Testing Library) / L2: Integration test / L3: E2E test","executed":true,"command":"test -- Button.test.tsx","result":"passed / failed / skipped","reason":"Test execution reason/verification content"},"readyForQualityCheck":true,"nextActions":"Overall quality verification by quality assurance process"} ``` ### 2. Escalation Response @@ -332,6 +345,9 @@ Triggered when the Test Environment Check finds the project-configured test tool ☐ Investigation Targets were processed, or marked N/A when the task file has no Investigation Targets section ☐ Investigation Notes were updated before implementation when Investigation Targets exist ☐ Implementation is consistent with the observations recorded in Investigation Notes +☐ Direct MVP Check maps every addition to a governing source +☐ Every Hard Constraint has a verified source and the implementation follows its allowed action +☐ Adjacent Case Sweep evidence records every checked case and disposition when the task Change Category requires it ☐ Final implementation preserves the required core mechanism from the task, AC, Design Doc, UI Spec, or referenced materials, with evidence recorded in Investigation Notes or runnableCheck.reason ☐ Every Binding Decisions Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes (when the task file has a Binding Decisions section) ☐ Every Reference Contracts row has source fidelity `Y` and Compliance Check `Y` against the final implementation, with evidence recorded in Investigation Notes (when the task file has a Reference Contracts section) diff --git a/.codex/agents/task-executor.toml b/.codex/agents/task-executor.toml index 331e1cc..cafe0f1 100644 --- a/.codex/agents/task-executor.toml +++ b/.codex/agents/task-executor.toml @@ -31,7 +31,7 @@ Confirm configured skills are active and record `Skill Status: [path] - ACTIVE` ## Mandatory Rules -**Progress Tracking**: Track your work steps. Always include: first "Confirm skill constraints", final "Verify skill fidelity". Update progress upon completion. +**Execution Plan Gate**: Call `update_plan` before substantive work. Include first "Map active rules to this task" and final "Verify outputs and rule adherence". While work remains, keep exactly one step `in_progress`; complete it only after recording its evidence and satisfying the next step's prerequisites. After final verification evidence is recorded, mark every step `completed`. ### Applying to Implementation - MUST determine layer structure and dependency direction with architecture rules @@ -53,7 +53,9 @@ Confirm configured skills are active and record `Skill Status: [path] - ACTIVE` - Contract system bypass needed? (unsafe casts, validation disable) - Error handling bypass needed? (exception ignore, error suppression) - Test hollowing needed? (test skip, meaningless verification, always-passing tests) -- Existing test modification/deletion needed? +- Existing test deletion needed, or an expectation change without a cited task/Design Doc/Reference Contract requirement? + +Existing-test changes proceed without escalation only when the old expectation conflicts with a cited requirement and the new assertion directly observes that requirement. Record the source and changed expectation in Investigation Notes. ### Step3: Similar Function Duplication Check **Escalation determination by duplication evaluation below** @@ -122,11 +124,18 @@ If the orchestrator prompt provides a task file path, execute only that exact ta When no task file path is provided, select and execute files with pattern `docs/plans/tasks/*-task-*.md` that have uncompleted checkboxes `[ ]` remaining. ### 2. Task Background Understanding + +#### Direct MVP Check +Before treating requested behavior as an unspecified design choice, map every planned addition to a failed task item, MVP requirement, Binding Decision, or Reference Contract. A direct, Target-Files-scoped implementation of that source proceeds. Escalate only when the addition has no governing source or requires a new product/architecture decision. + +#### Hard Constraints Check +When the task contains Hard Constraints, read each protected condition, paired allowed action, and cited source. A row without a readable authoritative source or executable in-scope allowed action is an incomplete task contract; return `status: "escalation_needed"` with `escalation_type: "design_compliance_violation"` before implementation. + #### Investigation Targets (Required when present) 1. Extract file paths from task file "Investigation Targets" section 2. Read each file before any implementation 3. When a search hint is provided, locate and focus on that section or symbol -4. Append brief notes to the task file's "Investigation Notes" section. Record the relevant interfaces, control/data flow, state transitions, and side effects observed in each Investigation Target +4. Append concise notes to the task file's "Investigation Notes" section: relevant symbol or contract, observed control/data flow, state transition, and side effect. Do not summarize unrelated file content. 5. If an Investigation Target file does not exist or the path is stale, escalate with `reason: "Investigation target not found"` and `escalation_type: "investigation_target_not_found"` **Utilizing Dependency Deliverables**: @@ -181,7 +190,7 @@ Run this check after Pre-implementation Verification and before the Binding Deci 1. From Investigation Targets, identify cases sharing the same path, contract, persisted state, or external boundary as the change. 2. Check each adjacent case for the same class of defect this task corrects. 3. Fold adjacent residuals within Target Files into this task's failing tests and implementation. -4. Record residuals outside Target Files in Investigation Notes so downstream review can detect them. +4. Record each checked case and disposition (`covered`, `not affected`, or `out of scope`) in Investigation Notes. For `out of scope`, include the path and observed residual so downstream review can detect it. #### Binding Decision Check (Required when the task file has a Binding Decisions section) @@ -254,6 +263,10 @@ Return one of the following as the final response (see Structured Response Speci ### Field Specifications +**filesModified**: Return every implementation or test file added or updated by the task. + +**testsAdded**: Return only newly created test files as reporting metadata. It is not the complete task write set. + **requiresTestReview**: Set to `true` when the task added or updated integration tests, fixture-e2e tests, or service-integration-e2e tests. Set to `false` for unit-test-only tasks or tasks with no tests. **runnableCheck.result**: @@ -267,7 +280,7 @@ Return one of the following as the final response (see Structured Response Speci Report in the following JSON format upon task completion (**without executing quality checks or commits**, delegating to quality assurance process): ```json -{"status":"completed","taskName":"[Exact name of executed task]","changeSummary":"[Specific summary of implementation content/changes]","filesModified":["specific/file/path1","specific/file/path2"],"testsAdded":["created/test/file/path"],"requiresTestReview":true,"newTestsPassed":true,"progressUpdated":{"taskFile":"5/8 items completed","workPlan":"Relevant sections updated","designDoc":"Progress section updated or N/A"},"runnableCheck":{"level":"L1: Unit test / L2: Integration test / L3: E2E test","executed":true,"command":"Executed test command","result":"passed / failed / skipped","reason":"Test execution reason/verification content"},"readyForQualityCheck":true,"nextActions":"Overall quality verification by quality assurance process"} +{"status":"completed","taskName":"[Exact name of executed task]","changeSummary":"[Specific summary of implementation content/changes]","filesModified":["specific/file/path1","specific/file/path2","created/test/file/path"],"testsAdded":["created/test/file/path"],"requiresTestReview":true,"newTestsPassed":true,"progressUpdated":{"taskFile":"5/8 items completed","workPlan":"Relevant sections updated","designDoc":"Progress section updated or N/A"},"runnableCheck":{"level":"L1: Unit test / L2: Integration test / L3: E2E test","executed":true,"command":"Executed test command","result":"passed / failed / skipped","reason":"Test execution reason/verification content"},"readyForQualityCheck":true,"nextActions":"Overall quality verification by quality assurance process"} ``` ### 2. Escalation Response @@ -331,6 +344,9 @@ Triggered when the Test Environment Check finds the project-configured test tool ☐ Investigation Targets were processed, or marked N/A when the task file has no Investigation Targets section ☐ Investigation Notes were updated before implementation when Investigation Targets exist ☐ Implementation is consistent with the observations recorded in Investigation Notes +☐ Direct MVP Check maps every addition to a governing source +☐ Every Hard Constraint has a verified source and the implementation follows its allowed action +☐ Adjacent Case Sweep evidence records every checked case and disposition when the task Change Category requires it ☐ Final implementation preserves the required core mechanism from the task, AC, Design Doc, or referenced materials, with evidence recorded in Investigation Notes or runnableCheck.reason ☐ Every Binding Decisions Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes (when the task file has a Binding Decisions section) ☐ Every Reference Contracts row has source fidelity `Y` and Compliance Check `Y` against the final implementation, with evidence recorded in Investigation Notes (when the task file has a Reference Contracts section) diff --git a/.codex/agents/technical-designer-frontend.toml b/.codex/agents/technical-designer-frontend.toml index 8f2d5cf..5275aaa 100644 --- a/.codex/agents/technical-designer-frontend.toml +++ b/.codex/agents/technical-designer-frontend.toml @@ -22,7 +22,7 @@ Verify skills from [[skills.config]] are active. For each inactive skill, execut ## Initial Mandatory Tasks -**Progress Tracking**: Track work steps. Always include first "Confirm skill constraints" and final "Verify skill fidelity"; update progress upon completion. +**Execution Plan Gate**: Call `update_plan` before substantive work. Include first "Map active rules to this task" and final "Verify outputs and rule adherence". While work remains, keep exactly one step `in_progress`; complete it only after recording its evidence and satisfying the next step's prerequisites. After final verification evidence is recorded, mark every step `completed`. **Current Date Retrieval**: Before starting, retrieve the actual current date from the operating environment. ## Document Creation Criteria diff --git a/.codex/agents/technical-designer.toml b/.codex/agents/technical-designer.toml index 1a5222f..c25efdb 100644 --- a/.codex/agents/technical-designer.toml +++ b/.codex/agents/technical-designer.toml @@ -20,7 +20,7 @@ Verify skills from [[skills.config]] are active. For each inactive skill, execut **EVIDENCE REQUIRED:** Record `Skill Status: [path] - ACTIVE` for each loaded skill. ## Initial Mandatory Tasks -**Progress Tracking**: Track work steps. Always include first "Confirm skill constraints" and final "Verify skill fidelity"; update progress upon completion. +**Execution Plan Gate**: Call `update_plan` before substantive work. Include first "Map active rules to this task" and final "Verify outputs and rule adherence". While work remains, keep exactly one step `in_progress`; complete it only after recording its evidence and satisfying the next step's prerequisites. After final verification evidence is recorded, mark every step `completed`. **Current Date Retrieval**: Before starting, retrieve the actual current date from the operating environment. ## Document Creation Criteria diff --git a/.codex/agents/ui-analyzer.toml b/.codex/agents/ui-analyzer.toml index 10f1f7e..49361fc 100644 --- a/.codex/agents/ui-analyzer.toml +++ b/.codex/agents/ui-analyzer.toml @@ -19,7 +19,7 @@ You are a UI fact gathering specialist for frontend design and adjustment prepar ## Initial Mandatory Tasks -Track work steps. Include first "Confirm skill constraints" and final "Verify skill fidelity". Update progress upon completion. +**Execution Plan Gate**: Call `update_plan` before substantive work. Include first "Map active rules to this task" and final "Verify outputs and rule adherence". While work remains, keep exactly one step `in_progress`; complete it only after recording its evidence and satisfying the next step's prerequisites. After final verification evidence is recorded, mark every step `completed`. ## Input Parameters diff --git a/.codex/agents/ui-spec-designer.toml b/.codex/agents/ui-spec-designer.toml index bdb7cea..e45bf3c 100644 --- a/.codex/agents/ui-spec-designer.toml +++ b/.codex/agents/ui-spec-designer.toml @@ -31,7 +31,7 @@ Skill Status: ## Initial Mandatory Tasks -**Progress Tracking**: Track your work steps. Always include: first "Confirm skill constraints", final "Verify skill fidelity". Update progress upon completion. +**Execution Plan Gate**: Call `update_plan` before substantive work. Include first "Map active rules to this task" and final "Verify outputs and rule adherence". While work remains, keep exactly one step `in_progress`; complete it only after recording its evidence and satisfying the next step's prerequisites. After final verification evidence is recorded, mark every step `completed`. **Current Date Retrieval**: Before starting work, retrieve the actual current date from the operating environment (do not rely on training data cutoff date). diff --git a/.codex/agents/verifier.toml b/.codex/agents/verifier.toml index b2e26ae..4009c77 100644 --- a/.codex/agents/verifier.toml +++ b/.codex/agents/verifier.toml @@ -30,7 +30,7 @@ Skill Status: ## Required Initial Tasks -**Progress Tracking**: Track your work steps. Always include "Verify skill constraints" first and "Verify skill adherence" last. Update progress upon each completion. +**Execution Plan Gate**: Call `update_plan` before substantive work. Include first "Map active rules to this task" and final "Verify outputs and rule adherence". While work remains, keep exactly one step `in_progress`; complete it only after recording its evidence and satisfying the next step's prerequisites. After final verification evidence is recorded, mark every step `completed`. **Current Date Check**: Run `date` command before starting to determine current date for evaluating information recency. diff --git a/.codex/agents/work-planner.toml b/.codex/agents/work-planner.toml index 7df71e6..a6fb9a1 100644 --- a/.codex/agents/work-planner.toml +++ b/.codex/agents/work-planner.toml @@ -33,7 +33,7 @@ Skill Status: ## Initial Mandatory Tasks -**Progress Tracking**: Track your work steps. Always include: first "Confirm skill constraints", final "Verify skill fidelity". Update progress upon completion. +**Execution Plan Gate**: Call `update_plan` before substantive work. Include first "Map active rules to this task" and final "Verify outputs and rule adherence". While work remains, keep exactly one step `in_progress`; complete it only after recording its evidence and satisfying the next step's prerequisites. After final verification evidence is recorded, mark every step `completed`. ## Main Responsibilities @@ -195,7 +195,7 @@ Mapping rules: ### 5e. Build Failure Mode Checklist -Populate the plan template's `Failure Mode Checklist` before finalizing tasks. Enumerate all nine domain-independent categories, mark whether each applies, and list the task IDs that cover applicable categories. Keep category names generic and put project-specific details in task descriptions or notes. +Populate the plan template's `Failure Mode Checklist` before finalizing tasks. Enumerate all ten domain-independent categories, mark whether each applies, and list the task IDs that cover applicable categories. Keep category names generic and put project-specific details in task descriptions or notes. Categories: - same-value @@ -207,6 +207,7 @@ Categories: - shared-state dependency - rollback-only visibility - missing-sort-key ordering +- irreversible-operation `missing-sort-key ordering` applies when a collection is sorted by a field or key that may be absent, null, derived, or conditionally omitted. Covering tasks must prove a deterministic fallback order for items lacking the sort key. diff --git a/README.md b/README.md index edd0b0a..6463caa 100644 --- a/README.md +++ b/README.md @@ -254,7 +254,7 @@ These are applied automatically based on context. You rarely need to think about | `task-analyzer` | Task analysis, scale estimation, skill selection | | `subagents-orchestration-guide` | Multi-agent coordination, workflow flows, guided autonomous execution | -Language-specific references are included for TypeScript/React projects (`coding-rules/references/typescript.md`, `testing/references/typescript.md`). +Web-frontend references are included for TypeScript used in web frontend work, including React applications (`coding-rules/references/typescript.md`, `testing/references/typescript.md`). They do not apply to backend TypeScript. --- From 9a1d78ac57820379da6df1e35f7eecf5ff4fa702 Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Tue, 28 Jul 2026 14:03:17 +0900 Subject: [PATCH 2/3] Bump package version to 0.9.3 --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index a6b5662..1e4f0a8 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "codex-workflows", - "version": "0.9.2", + "version": "0.9.3", "description": "Task-oriented agentic coding framework for OpenAI Codex CLI — skills, recipes, and subagents for structured development workflows", "license": "MIT", "author": "Shinsuke Kagawa", From 897165fe593474bc1b803012a1bad8672fe4ddb3 Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Tue, 28 Jul 2026 14:20:40 +0900 Subject: [PATCH 3/3] Rewrite README around workflow outcomes --- README.md | 185 +++++++++++++++++++++++------------------------------- 1 file changed, 77 insertions(+), 108 deletions(-) diff --git a/README.md b/README.md index 6463caa..47e8057 100644 --- a/README.md +++ b/README.md @@ -4,16 +4,31 @@ [![Agent Skills](https://img.shields.io/badge/Agent%20Skills-Spec%20Compliant-blue)](https://developers.openai.com/codex/skills/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) -**Repeatable, reviewable development workflows for [OpenAI Codex CLI](https://developers.openai.com/codex/cli).** +Repeatable software development workflows for [OpenAI Codex CLI](https://developers.openai.com/codex/cli) that keep scope and design decisions traceable through implementation, tests, and review. -Built on the [Agent Skills specification](https://developers.openai.com/codex/skills/) and [Codex subagents](https://developers.openai.com/codex/subagents), codex-workflows turns a request into a predefined delivery process. +Codex can implement a well-scoped task directly. codex-workflows is for changes where the harder problem is keeping analysis, design, implementation, and final verification aligned after the first answer. -Small changes stay lightweight. Larger changes move through requirements, design, task decomposition, TDD implementation, and quality checks. +Each phase delegates to task-specific subagents and hands off through explicit repository artifacts. The workflow inspects the existing codebase, selects the smallest sufficient process, pauses at decision boundaries, implements one task at a time, and checks whether the finished work still matches the agreed requirements. --- ## Quick Start +### Choose a path + +| What do you need? | Start with | +|---|---| +| Deliver a backend, API, CLI, or general change end to end | `$recipe-implement` | +| Complete a focused task without staged design handoffs | `$recipe-task` | +| Design first and implement later | `$recipe-design` → `$recipe-plan` → `$recipe-build` | +| Design and build a React / TypeScript web frontend | `$recipe-front-design` → `$recipe-front-plan` → `$recipe-front-build` | +| Deliver a backend and React frontend change together | `$recipe-fullstack-implement` | +| Review an implementation against its design | `$recipe-review` or `$recipe-front-review` | +| Investigate a problem without changing code | `$recipe-diagnose` | +| Run a throwaway experiment or one-shot script | Use Codex directly | + +### Install and run + ```bash cd your-project npx codex-workflows install @@ -29,84 +44,61 @@ $recipe-implement Add user authentication with JWT --- -## Why codex-workflows? - -Codex can carry large plans to completion. codex-workflows makes the process around that work explicit and repeatable instead of rebuilding it in each prompt. +## Why use a development workflow? -- Analysis, implementation, and review use task-specific context, reducing the chance that the same working assumptions carry from one stage to the next. -- Recipes define which agents run at each stage, what they receive, and what they return. This is slower than open-ended delegation, but keeps agent calls within the defined workflow. -- Design starts with the simplest end-to-end path. A new service, state, flag, or boundary must answer an unmet requirement or verified constraint. -- Requirements and design decisions stay in versioned project documents. Review workflows detect drift, and document updates are checked against the current implementation. +Codex can carry a large plan to completion. The harder problem is keeping a larger change coherent after the first answer. -## Background +Consider a hypothetical authentication change. Analysis finds that the existing authentication path should be extended. During implementation, a second mechanism looks convenient, the response contract changes with it, and the frontend adapts to the new shape. Every local edit may look reasonable and every test may pass, while the result no longer matches the approach the team approved. -The recipes, subagents, and quality checks in this repo were not designed top-down. Each piece was added in response to a concrete failure mode encountered during delivery work. +codex-workflows keeps the existing path as the default, requires evidence for new design surface, and carries the agreed contract into tasks, tests, and final review. If implementation discovers that the contract must change, the workflow returns to the relevant decision instead of silently expanding the change. -That is why the workflow separates requirements, design, verification, implementation, and quality checks instead of treating them as one long session. +This costs more agent calls and tokens than direct execution. Use it when scope drift, lost decisions, or an unreviewed contract change would cost more than the workflow. For a throwaway experiment, one-shot script, or other work where traceability is not valuable, use Codex directly. -## Not Designed For - -- One-shot scripts or exploratory sessions where speed matters more than traceability -- Repositories without tests, lint, builds, or reviewable commits -- Teams that would rather skip design docs and quality checks entirely +Because the workflows are installed into the repository, contributors can use the same recipes, agents, and review boundaries without rebuilding them in each prompt. --- -## What It Does +## How It Works -Instead of forcing a fixed workflow, the framework adjusts how much structure it adds based on scope: +```mermaid +flowchart LR + A[Request] --> B[Scope the change] + B -->|Needs design| C[Inspect and design] + C --> D{Approve} + D -->|Revise| C + D -->|Proceed| E[Write task handoffs] + B -->|Focused task| F[Implement] + E --> F + F --> G[Verify] + G -->|Fix a gap| F + G -->|Decision changed| C + G -->|Passed| H[Complete] +``` -| Scale | File Count | What Happens | +The requirement and affected layers decide the route. The workflow does not create a full document set by default: + +| Scale | Expected file count | What happens | |-------|------------|-------------| | Small | 1-2 | Simplified plan → direct implementation | | Medium | 3-5 | Design Doc → work plan → task execution | -| Large | 6+ | PRD → ADR → Design Doc → test skeletons → work plan → guided autonomous execution | - -For larger work, the path usually looks like this: understand the problem, analyze the codebase, design the change, break it into atomic tasks, implement with tests, and run quality checks before commit. - -Each step isolates one concern, so decisions can be checked before they carry into later stages. Specialized subagents run in their own contexts to reduce carry-over assumptions during changes that would otherwise require long sessions: +| Large | 6+ | PRD when required → ADR when required → Design Doc → test skeletons when required → work plan → task execution | -``` -User Request - ↓ -requirement-analyzer → Scale determination (Small / Medium / Large) - ↓ -prd-creator → Product requirements (Large scale) - ↓ -codebase-analyzer → Existing codebase facts + focus areas - ↓ -technical-designer → ADR + Design Doc with acceptance criteria - ↓ -code-verifier → Design Doc vs existing code verification - ↓ -document-reviewer → Quality gate with verification evidence - ↓ -acceptance-test-gen → Test skeletons from ACs - ↓ -work-planner → Phased execution plan - ↓ -task-decomposer → Atomic tasks (1 task = 1 commit) - ↓ -task-executor → TDD implementation per task - ↓ -quality-fixer → Lint, test, build; no failing checks - ↓ -Ready to commit -``` +After work plan approval, Codex tracks the execution steps, implements each task with focused verification, runs repository quality checks, and creates one commit per task. A design deviation, unresolved contract, or out-of-scope write pauses execution for a decision. -### The Diagnosis Pipeline +Recipes pass explicit inputs and repository artifacts to subagents instead of relying on the accumulated implementation conversation. Generation and review therefore use separate task-specific contexts, while the governing decisions remain inspectable in the repository. -``` -Problem → investigator (path map + failure points) → verifier (path coverage + independent failure-point evaluation) → solver → Actionable solutions -``` +### A handoff you can inspect -### Reverse Engineering +The included [Work Plan template](.agents/skills/documentation-criteria/references/plan-template.md) requires every implementation-relevant Design Doc item to have a covering task or an explicit gap: -``` -Existing code → scope-discoverer (discoveredUnits + prdUnits) → prd-creator → code-verifier → document-reviewer → Design Docs +```markdown +| Source Design Doc | DD Section | DD Item | Category | Covered By Task(s) | Gap Status | Notes | +|---|---|---|---|---|---|---| +| docs/design/example-design.md | API contract | Preserve the error response shape | contract-change | P2-T1 | covered | | +| docs/design/example-design.md | Verification | Exercise cache invalidation | verification | - | gap | Add a covering task before approval | ``` -This works best when repository knowledge is explicit and local. Short `AGENTS.md` files can act as entry points, while design docs, plans, and task files hold the deeper instructions that agents need to execute reliably. +The [Task template](.agents/skills/documentation-criteria/references/task-template.md) then carries protected conditions, allowed actions, binding decisions, observable contract values, proof obligations, and yes-or-no completion checks into implementation. Final review reads the governing documents and completed diff rather than relying on the implementation conversation. --- @@ -166,10 +158,13 @@ npx codex-workflows status --user --- -## Recipe Workflows +## Workflow Recipe Reference Invoke recipes with `$recipe-name` in Codex. Type `$recipe-` and use tab completion to see all available recipes. +
+View all recipe entry points + ### Backend & General | Recipe | What it does | When to use | @@ -203,7 +198,9 @@ Invoke recipes with `$recipe-name` in Codex. Type `$recipe-` and use tab complet | `$recipe-fullstack-implement` | Full lifecycle with separate Design Docs per layer | Cross-layer features | | `$recipe-fullstack-build` | Execute tasks with layer-aware agent routing | Resume cross-layer implementation | -### Working State +
+ +## Working State Recipes use `docs/plans/` as ephemeral working state for work plans, decomposed task files, prep tasks, review-fix tasks, and intermediate analysis files. Add it to your project's `.gitignore` unless your team intentionally wants to review those transient files: @@ -213,33 +210,14 @@ docs/plans/ PRDs, ADRs, UI Specs, and Design Docs are durable project documents and are intended to be committed. -### Examples - -**Full feature development:** -``` -$recipe-implement Add user authentication with JWT and role-based access control -``` - -**Quick fix with proper rule selection:** -``` -$recipe-task Fix validation error message in checkout form -``` - -**Investigate a bug:** -``` -$recipe-diagnose API returns 500 error on user login after deployment -``` - -**Document undocumented legacy code:** -``` -$recipe-reverse-engineer src/auth module -``` - --- -## Foundational Skills +## Included Guidance -These are applied automatically based on context. You rarely need to think about them directly. +Recipes load the repository-aware guidance required for the current task. You rarely need to select these skills directly. + +
+View foundational skills | Skill | What it provides | |-------|-----------------| @@ -256,12 +234,17 @@ These are applied automatically based on context. You rarely need to think about Web-frontend references are included for TypeScript used in web frontend work, including React applications (`coding-rules/references/typescript.md`, `testing/references/typescript.md`). They do not apply to backend TypeScript. +
+ --- -## Subagents +## Specialized Agents Codex spawns these as needed during recipe execution. You do not need to learn them first; recipes route work to the right agents automatically. Each agent runs in its own context with specialized instructions and skill configurations. +
+View all specialized agent roles + ### Document Creation Agents | Agent | Role | @@ -307,26 +290,7 @@ Codex spawns these as needed during recipe execution. You do not need to learn t | `verifier` | Path coverage validation and independent failure-point evaluation | | `solver` | Solution derivation with tradeoff analysis | ---- - -## How It Works - -### Guided Autonomous Execution Mode - -After work plan approval, the framework executes task files with explicit validation points: - -1. **task-executor** implements each task with TDD -2. **quality-fixer** first rejects incomplete task-scoped implementations, then runs lint, tests, and build before every commit -3. Escalation pauses execution when design deviation or ambiguity is detected -4. Each task produces one commit for rollback-friendly granularity - -### Context Separation - -Recipes intentionally avoid passing the accumulated parent conversation to spawned agents. Each agent receives explicit task inputs and repository artifacts instead. This keeps multi-step coding tasks legible and reviewable: -- generation and verification happen in separate contexts, reducing author bias and carry-over assumptions -- **document-reviewer** reviews without the author's bias -- **investigator** collects evidence without confirmation bias -- **code-reviewer** validates compliance without implementation context +
--- @@ -334,6 +298,9 @@ Recipes intentionally avoid passing the accumulated parent conversation to spawn After installation, your project gets: +
+View installed files + ``` your-project/ ├── .agents/skills/ # Codex skills @@ -373,6 +340,8 @@ your-project/ └── tasks/ ``` +
+ --- ## Works With