diff --git a/.agents/skills/recipe-build/SKILL.md b/.agents/skills/recipe-build/SKILL.md index 428d09d..4ef689e 100644 --- a/.agents/skills/recipe-build/SKILL.md +++ b/.agents/skills/recipe-build/SKILL.md @@ -59,7 +59,9 @@ Apply subagents-orchestration-guide `Requirement Change Detection During Flow` a ## 8. Final Verification -Apply `subagents-orchestration-guide` Post-Implementation Verification to the actual files changed by completed tasks and their governing documents. Route required fixes through the same task cycle and apply its Post-Verification Rerun Rule. +Apply `subagents-orchestration-guide` Post-Implementation Review to the actual files changed by completed tasks and their governing documents. Route required fixes through the same task cycle. + +Apply a security-reviewer finding only when leaving it unresolved would violate an explicit governing requirement or repository rule, or leave a concrete material security failure in the actual reachable trust model. The violated requirement, rule, or failure defines implementation scope: route the smallest correction that resolves it, treating the reviewer's suggestion as one candidate implementation. ## 9. Cleanup and Report diff --git a/.agents/skills/recipe-front-build/SKILL.md b/.agents/skills/recipe-front-build/SKILL.md index a3384e2..7a6ae14 100644 --- a/.agents/skills/recipe-front-build/SKILL.md +++ b/.agents/skills/recipe-front-build/SKILL.md @@ -51,7 +51,9 @@ Apply subagents-orchestration-guide `Requirement Change Detection During Flow` a ## 7. Final Verification -Apply `subagents-orchestration-guide` Post-Implementation Verification to the actual files changed by completed tasks and their governing documents. Route required fixes through the frontend task cycle and apply its Post-Verification Rerun Rule. +Apply `subagents-orchestration-guide` Post-Implementation Review to the actual files changed by completed tasks and their governing documents. Route required fixes through the frontend task cycle. + +Apply a security-reviewer finding only when leaving it unresolved would violate an explicit governing requirement or repository rule, or leave a concrete material security failure in the actual reachable trust model. The violated requirement, rule, or failure defines implementation scope: route the smallest correction that resolves it, treating the reviewer's suggestion as one candidate implementation. ## 8. Cleanup and Report diff --git a/.agents/skills/recipe-front-review/SKILL.md b/.agents/skills/recipe-front-review/SKILL.md index 7ec7aef..2ccc92b 100644 --- a/.agents/skills/recipe-front-review/SKILL.md +++ b/.agents/skills/recipe-front-review/SKILL.md @@ -1,6 +1,6 @@ --- name: recipe-front-review -description: "Frontend Design Doc compliance and security validation with optional auto-fixes using React-specific quality checks." +description: "Reviews completed frontend implementation for governing-source compliance, scope economy, repository quality, and security, and applies user-approved React corrections." --- **Context**: Post-implementation quality assurance for React/TypeScript frontend @@ -17,7 +17,7 @@ description: "Frontend Design Doc compliance and security validation with option ## Execution Method -- Compliance validation -> performed by code-reviewer +- Implementation review -> performed by code-reviewer - Security validation -> performed by security-reviewer - Code-side fix path -> performed by task-executor-frontend - Design-side update path -> performed by technical-designer-frontend in update mode, then document-reviewer, then design-sync when multiple Design Docs exist @@ -38,7 +38,7 @@ If a single active work plan is explicitly provided or unambiguously resolved fo **CANNOT proceed without both a Design Doc and implementation files.** ### 2. Execute code-reviewer -Spawn code-reviewer agent: "Validate Design Doc compliance for [design-doc-path]. Work Plan: [resolved work plan path or none]. Review Scope: [literal Review Scope value or none]. Implementation files: [$STEP_1_FILES]. Review mode: full. Return structured JSON report per your Output Format specification." +Spawn code-reviewer agent: "Review the completed frontend implementation. governingDocuments: [{type: design-doc, path: [design-doc-path]}]. Work Plan: [resolved work plan path or none]. Review Scope: [literal Review Scope value or none]. implementationFiles: [$STEP_1_FILES]. Return the initial review JSON." **Store output as**: `$STEP_2_OUTPUT` @@ -51,20 +51,21 @@ Spawn security-reviewer with `governingDocuments: [{type: "design-doc", path: [p If either reviewer returns a blocked or otherwise unusable result, apply Orchestrator Escalation Resolution before continuing. +Apply a security-reviewer finding only when leaving it unresolved would violate an explicit governing requirement or repository rule, or leave a concrete material security failure in the actual reachable trust model. The violated requirement, rule, or failure defines implementation scope: route the smallest correction that resolves it, treating the reviewer's suggestion as one candidate implementation. + **Code compliance criteria (considering project stage)**: - `code-reviewer` verdict is `pass` **Security criteria**: - `approved` -> Pass -- `needs_revision` -> Fail +- `needs_revision` -> Requires disposition -Report both results from their evidence, then apply Review Resolution before proposing corrections: +Report required corrections from both results, then apply Review Resolution before proposing corrections: ``` -Code Compliance: [verdict] +Implementation Review: [verdict] Acceptance Criteria: [fulfilled/unfulfilled items with evidence] - Findings: [blocking findings with basis and effect] - Recommendations: [non-blocking items] + Findings: [required-correction findings with basis and effect] Security Review: [status from security-reviewer] Findings by category: @@ -74,15 +75,13 @@ Security Review: [status from security-reviewer] Proposed corrections: c) Code-side fix d) Design-side update -Declined recommendations: - - [finding and evidence-backed reason] ``` Apply Review Resolution before presenting results. Recommend a correction route only for findings classified `apply` or `user_decision_required`: - Use `d` when implementation intent matches the requirement but the Design Doc is stale or too narrow. -- Use `c` when code drifted from a still-correct Design Doc, or when the finding is reliability, security, or maintainability related. +- Use `c` when the required correction changes implementation. -Present the review and internally declined recommendations. When no correction remains, proceed to Final Report. Because this recipe is a review request rather than prior implementation authority, ask once before applying the proposed code or document corrections. +Present the review. When no correction remains, proceed to Final Report. Because this recipe is a review request rather than prior implementation authority, ask once before applying the proposed code or document corrections. If the user declines corrections, skip fix steps and proceed to Final Report. @@ -92,9 +91,11 @@ If the user declines corrections, skip fix steps and proceed to Final Report. 2. **Plan fixes**: Use the active execution plan when one exists. When none exists, create one for the accepted fix flow. Create `docs/plans/tasks/review-fixes-YYYYMMDD.md` with only accepted code compliance issues and security required fixes routed to `c`. 3. **Execute fixes**: Start the Per-Task Change Set, invoke task-executor-frontend with the task file, inspect its result and repository diff, and accumulate its paths. 4. **Quality check**: Invoke quality-fixer-frontend with `task_file`, `filesModified: taskWriteSet`, and executor operation-verification evidence. On approval, add its paths and commit the reconciled set; repair stubs through task-executor-frontend, accumulate their paths, and resolve blocked results through Orchestrator Escalation Resolution. -5. **Re-validate**: Run code-reviewer and security-reviewer against the updated Design Doc and actual implementation and fix files. Pass both `prior_feedback: [applied corrections and declined finding IDs with reasons and evidence]` and review the current result normally. +5. **Re-validate**: Run code-reviewer and security-reviewer against the updated Design Doc and actual implementation and fix files. For code-reviewer, pass `prior_feedback: [the complete initial result, applied corrections, declined finding IDs with reasons and evidence, and the correction paths or diff]` and apply its Rerun Boundary. Pass the applicable corrections and dispositions to security-reviewer. + +After any code fix, both review agents must re-run. -After any code fix, both review agents must re-run. Delete the task file only after both pass. +Apply Review Resolution to rerun findings. Its convergence rule governs any further correction and rerun; code-reviewer receives the latest complete result and the next correction paths or diff. ENFORCEMENT: Auto-fixes MUST go through quality-fixer-frontend before re-validation. Skipping quality checks invalidates fixes. @@ -102,7 +103,7 @@ ENFORCEMENT: Auto-fixes MUST go through quality-fixer-frontend before re-validat Delete the review-fix task file this recipe created, if present. Its work is committed; `docs/plans/` is ephemeral working state. ``` -Code Compliance: +Implementation Review: Initial: [verdict] Final: [verdict] (if fixes executed) @@ -114,18 +115,6 @@ Remaining issues: - [items requiring manual intervention] ``` -## Auto-fixable Items -- Simple unimplemented acceptance criteria -- Error handling additions -- Contract definition fixes -- Function splitting (length/complexity improvements) -- Security confirmed_risk and defense_gap fixes (input validation, auth checks, output encoding) - -## Non-fixable Items -- Fundamental business logic changes -- Architecture-level modifications -- Design Doc deficiencies -- Committed secrets (blocked -> human intervention) ## Completion Criteria diff --git a/.agents/skills/recipe-front-review/agents/openai.yaml b/.agents/skills/recipe-front-review/agents/openai.yaml index 96361ac..a08cef6 100644 --- a/.agents/skills/recipe-front-review/agents/openai.yaml +++ b/.agents/skills/recipe-front-review/agents/openai.yaml @@ -1,7 +1,7 @@ interface: display_name: "recipe-front-review" - short_description: "Frontend Design Doc compliance and security validation with React-specific checks" - default_prompt: "Use $recipe-front-review to validate frontend: " + short_description: "Review frontend scope, quality, and security" + default_prompt: "Use $recipe-front-review to review frontend: " policy: allow_implicit_invocation: false diff --git a/.agents/skills/recipe-fullstack-build/SKILL.md b/.agents/skills/recipe-fullstack-build/SKILL.md index 3d882b2..d6dceb3 100644 --- a/.agents/skills/recipe-fullstack-build/SKILL.md +++ b/.agents/skills/recipe-fullstack-build/SKILL.md @@ -69,7 +69,9 @@ Apply subagents-orchestration-guide `Requirement Change Detection During Flow` a ## 9. Final Verification -Apply `subagents-orchestration-guide` Post-Implementation Verification to the actual files changed by completed tasks and their governing documents. Route required fixes through the layer-selected task cycle and apply its Post-Verification Rerun Rule. +Apply `subagents-orchestration-guide` Post-Implementation Review to the actual files changed by completed tasks and their governing documents. Route required fixes through the layer-selected task cycle. + +Apply a security-reviewer finding only when leaving it unresolved would violate an explicit governing requirement or repository rule, or leave a concrete material security failure in the actual reachable trust model. The violated requirement, rule, or failure defines implementation scope: route the smallest correction that resolves it, treating the reviewer's suggestion as one candidate implementation. ## 10. Cleanup and Report diff --git a/.agents/skills/recipe-fullstack-implement/SKILL.md b/.agents/skills/recipe-fullstack-implement/SKILL.md index f8ef5e2..dfedc3b 100644 --- a/.agents/skills/recipe-fullstack-implement/SKILL.md +++ b/.agents/skills/recipe-fullstack-implement/SKILL.md @@ -26,7 +26,9 @@ Resolve the entry from supplied artifacts and repository state. Ask only when di Apply the Fullstack Flow exposed by `subagents-orchestration-guide` with backend, frontend, and shared routing. The orchestrator directly owns artifact/path resolution, execution-plan updates, approval recording, task-set computation, commits, and lightweight checks; invoke the named specialists for analysis, authoring, implementation, review, and quality judgment. -Reuse the active execution plan or register the material remaining phases once. Follow the Fullstack Flow's document approvals. After implementation-scope approval, execute tasks autonomously through its filename routing, Per-Task Change Set, quality gate, commit, and Post-Implementation Verification. +Reuse the active execution plan or register the material remaining phases once. Follow the Fullstack Flow's document approvals. After implementation-scope approval, execute tasks autonomously through its filename routing, Per-Task Change Set, quality gate, commit, and Post-Implementation Review. + +Apply a security-reviewer finding only when leaving it unresolved would violate an explicit governing requirement or repository rule, or leave a concrete material security failure in the actual reachable trust model. The violated requirement, rule, or failure defines implementation scope: route the smallest correction that resolves it, treating the reviewer's suggestion as one candidate implementation. External evidence, prototypes, and repository environment preparation remain conditional under the canonical flow. A missing optional input does not create a stop. diff --git a/.agents/skills/recipe-implement/SKILL.md b/.agents/skills/recipe-implement/SKILL.md index 9e6b16e..b3ea852 100644 --- a/.agents/skills/recipe-implement/SKILL.md +++ b/.agents/skills/recipe-implement/SKILL.md @@ -50,9 +50,11 @@ Enter autonomous execution when the subagents-orchestration-guide `Authority Gra For a fullstack task set, apply the Fullstack Flow filename routing exposed by `subagents-orchestration-guide`. For a single-layer task set, use the executor and quality fixer selected by `affectedLayers`. Execute each task through the canonical autonomous task cycle. -### Post-Implementation Verification (After All Tasks Complete) +### Post-Implementation Review (After All Tasks Complete) -Apply subagents-orchestration-guide `Post-Implementation Verification Pass/Fail Criteria` to the actual repository changes and governing documents. Use the active Small task file as the security source when no durable document exists. Resolve required fixes through the normal task cycle and `Post-Verification Rerun Rule`. +Apply subagents-orchestration-guide `Post-Implementation Review` to the actual repository changes and governing documents. Use the active Small task file as the governing source when no durable document exists. Resolve required fixes through the normal task cycle. + +Apply a security-reviewer finding only when leaving it unresolved would violate an explicit governing requirement or repository rule, or leave a concrete material security failure in the actual reachable trust model. The violated requirement, rule, or failure defines implementation scope: route the smallest correction that resolves it, treating the reviewer's suggestion as one candidate implementation. ### Test Information Communication Verify acceptance-test-generator artifact paths and pass them to work-planner. diff --git a/.agents/skills/recipe-quality-profile/SKILL.md b/.agents/skills/recipe-quality-profile/SKILL.md new file mode 100644 index 0000000..3276184 --- /dev/null +++ b/.agents/skills/recipe-quality-profile/SKILL.md @@ -0,0 +1,72 @@ +--- +name: recipe-quality-profile +description: "Proposes and, after user confirmation, creates or maintains docs/project-context/quality.yaml from repository-specific review requirements. Use when asked to generate or update a repository quality profile." +--- + +## Required Skills [LOAD BEFORE EXECUTION] + +1. `llm-friendly-context` — make each generated condition unambiguous, executable, and observable +2. `coding-rules` — distinguish repository-specific policy from general code quality knowledge + +## Purpose + +Establish repository-specific code-quality acceptance conditions with the user, then create or update `docs/project-context/quality.yaml`. Create `docs/project-context/` when the directory is absent. + +Target repository and, when a profile already exists, requested policy change: $ARGUMENTS + +## Profile Contract + +Use this shape: + +```yaml +version: 1 +review_dimensions: + - id: stable-kebab-case-id + applies_when: Observable condition that makes this repository rule relevant to a change. + pass: Observable accepted state to verify. + evidence: + - "repository/path: section, identifier, or contract" +``` + +Each dimension represents one repository-specific decision. `id` identifies it across reviews, `applies_when` limits its review surface, `pass` defines acceptance, and `evidence` records why the repository owns the rule. + +## Authoring Flow + +1. Resolve the target repository and read its existing `docs/project-context/quality.yaml` when present. When a profile exists without a requested policy change, ask for the intended change and keep the profile unchanged. +2. Establish candidate dimensions before deciding profile content: + - For initial creation, derive candidates from acceptance conditions that repository instructions, contributor documentation, CI, manifests and scripts, schemas and public contracts, tests, or established implementation patterns express or enforce. + - For an update, translate the requested policy change into candidate additions, changes, or removals. Match it to the current dimension that owns the same policy when one exists and preserve other dimensions as the proposed unchanged set. +3. State a candidate `applies_when` and `pass`, then identify the repository claims that must hold for that criterion to mean what it says. Inspect supporting and contradicting evidence, following declarations, workflows, contracts, tests, and usages wherever their difference could change the candidate's applicability, accepted state, or ownership. +4. Compare the candidate with the current profile and repository evidence. Record duplicated policy ownership, contradictory accepted states under overlapping `applies_when` conditions, conflicting evidence, and current accepted behavior that the candidate would newly reject. Separate repository facts from policy choices that only the user can make. +5. Retain a candidate for the proposal only when its failure would change implementation acceptance and every repository fact it depends on is supported by cited evidence. Present remaining policy choices for user confirmation. When a required repository fact cannot be established, report the exact evidence needed and omit that candidate from the proposal. A general language or framework concern qualifies when repository evidence adds a distinct local rule. Express each retained dimension as one positive observable `pass` condition with the narrowest useful `applies_when` boundary, and consolidate dimensions that would produce the same finding and correction. +6. Before writing, present the proposed additions, changes, and removals; confirm that other dimensions remain unchanged; show the supporting and contradicting evidence for each proposed modification; and state every unresolved policy choice with its effect on review acceptance. **[STOP — BLOCKING]** Keep the repository unchanged until the user explicitly confirms a proposal with no unresolved choices. +7. When the user's response changes a proposed criterion or resolves a policy choice, repeat its repository comparison and present the revised proposal for confirmation. After confirmation, write only the confirmed profile content. +8. Read the resulting YAML and verify version `1`, unique IDs, all four dimension fields, positive observable pass conditions, readable evidence references, and consistency with the confirmed proposal. + +When no repository-specific dimension survives this process and no profile exists, report that no profile content is supported and leave the repository unchanged. + +## Result + +Before confirmation, report: + +- proposed additions, changes, and removals, plus confirmation that other dimensions remain unchanged; +- supporting and contradicting repository evidence for each proposed modification, plus exact evidence needed for any candidate that cannot yet be proposed; +- policy choices requiring the user's decision and how each choice changes review acceptance. + +After confirmation, report: + +- profile path and whether it was created, updated, or left unchanged; +- dimensions added, changed, or removed; +- evidence used for each changed dimension; +- an exact validation limitation when the profile could not be verified. + +## Completion Check + +- [ ] `llm-friendly-context` was read before authoring criteria +- [ ] Every dimension changes a review decision and cites repository or user-policy evidence +- [ ] Conditions are positive, observable, and limited by `applies_when` +- [ ] The profile contains only repository-specific acceptance conditions +- [ ] Candidate criteria were compared with supporting and contradicting repository evidence +- [ ] The user confirmed the proposed profile content before any repository write +- [ ] Dimensions outside the requested update remain unchanged and the resulting set is internally consistent +- [ ] The written profile satisfies the Profile Contract diff --git a/.agents/skills/recipe-quality-profile/agents/openai.yaml b/.agents/skills/recipe-quality-profile/agents/openai.yaml new file mode 100644 index 0000000..5673423 --- /dev/null +++ b/.agents/skills/recipe-quality-profile/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "recipe-quality-profile" + short_description: "Create or maintain repository review policy" + default_prompt: "Use $recipe-quality-profile to generate or update the quality profile for: " + +policy: + allow_implicit_invocation: false diff --git a/.agents/skills/recipe-review/SKILL.md b/.agents/skills/recipe-review/SKILL.md index bf41e91..f2d7576 100644 --- a/.agents/skills/recipe-review/SKILL.md +++ b/.agents/skills/recipe-review/SKILL.md @@ -1,6 +1,6 @@ --- name: recipe-review -description: "Design Doc compliance and security validation with optional auto-fixes." +description: "Reviews completed implementation for governing-source compliance, scope economy, repository quality, and security, and applies user-approved corrections." --- ## Required Skills [LOAD BEFORE EXECUTION] @@ -23,7 +23,7 @@ description: "Design Doc compliance and security validation with optional auto-f ## Execution Method -- Compliance validation -> Spawn code-reviewer agent +- Implementation review -> Spawn code-reviewer agent - Security validation -> Spawn security-reviewer agent - Code-side fix path -> Spawn task-executor agent - Design-side update path -> Spawn technical-designer in update mode, then document-reviewer, then design-sync when multiple Design Docs exist @@ -41,7 +41,7 @@ Identify the Design Doc in `docs/design/`. Derive `$STEP_1_FILES` as the complet If a single active work plan is explicitly provided or unambiguously resolved for that Design Doc, read its `Review Scope` line. Otherwise set `Work Plan: none` and `Review Scope: none`; do not infer. ### Step 2: Execute code-reviewer -Spawn code-reviewer agent: "Validate Design Doc compliance for the implementation. Design Doc path: [path]. Work Plan: [resolved work plan path or none]. Review Scope: [literal Review Scope value or none]. Implementation files: [$STEP_1_FILES]. Review mode: full. Return structured JSON report per your Output Format specification." +Spawn code-reviewer agent: "Review the completed implementation. governingDocuments: [{type: design-doc, path: [path]}]. Work Plan: [resolved work plan path or none]. Review Scope: [literal Review Scope value or none]. implementationFiles: [$STEP_1_FILES]. Return the initial review JSON." **Store output as**: `$STEP_2_OUTPUT` @@ -54,20 +54,21 @@ Spawn security-reviewer with `governingDocuments: [{type: "design-doc", path: [p If either reviewer returns a blocked or otherwise unusable result, apply Orchestrator Escalation Resolution before continuing. +Apply a security-reviewer finding only when leaving it unresolved would violate an explicit governing requirement or repository rule, or leave a concrete material security failure in the actual reachable trust model. The violated requirement, rule, or failure defines implementation scope: route the smallest correction that resolves it, treating the reviewer's suggestion as one candidate implementation. + **Code compliance criteria (considering project stage)**: - `code-reviewer` verdict is `pass` **Security criteria**: - `approved` -> Pass -- `needs_revision` -> Fail +- `needs_revision` -> Requires disposition -Report both results from their evidence, then apply Review Resolution before proposing corrections: +Report required corrections from both results, then apply Review Resolution before proposing corrections: ``` -Code Compliance: [verdict] +Implementation Review: [verdict] Acceptance Criteria: [fulfilled/unfulfilled items with evidence] - Findings: [blocking findings with basis and effect] - Recommendations: [non-blocking items] + Findings: [required-correction findings with basis and effect] Security Review: [status from security-reviewer] Findings by category: @@ -77,15 +78,13 @@ Security Review: [status from security-reviewer] Proposed corrections: c) Code-side fix d) Design-side update -Declined recommendations: - - [finding and evidence-backed reason] ``` Apply Review Resolution before presenting results. Recommend a correction route only for findings classified `apply` or `user_decision_required`: - Use `d` when implementation intent matches the requirement but the Design Doc is stale or too narrow. -- Use `c` when code drifted from a still-correct Design Doc, or when the finding is reliability, security, or maintainability related. +- Use `c` when the required correction changes implementation. -Present the review and internally declined recommendations. When no correction remains, proceed to Step 11. Because this recipe is a review request rather than prior implementation authority, ask once before applying the proposed code or document corrections. +Present the review. When no correction remains, proceed to Step 11. Because this recipe is a review request rather than prior implementation authority, ask once before applying the proposed code or document corrections. If the user declines corrections, skip Steps 5-10 and proceed to Step 11. @@ -119,20 +118,22 @@ Spawn quality-fixer with `task_file`, `filesModified: taskWriteSet`, and executo ### Step 9: Re-validate code-reviewer -Spawn code-reviewer with the Design Doc, actual implementation and fix files, and `prior_feedback: [applied corrections and declined finding IDs with reasons and evidence from Step 4]`. Review the current implementation normally and verify the applied corrections. +Spawn code-reviewer with the original governing documents and implementation change set, plus `prior_feedback: [the complete Step 2 result, applied corrections, declined finding IDs with reasons and evidence, and the correction paths or diff]`. Apply its Rerun Boundary. ### Step 10: Re-validate security-reviewer Spawn security-reviewer with `governingDocuments: [{type: "design-doc", path: [path]}]`, the actual implementation and fix files, and `prior_feedback: [applied corrections and declined finding IDs with reasons and evidence from Step 4]`. -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. +After any code fix, both Steps 9 and 10 are mandatory even when only one reviewer initially reported a finding. + +Apply Review Resolution to rerun findings. Its convergence rule governs any further correction and rerun; code-reviewer receives the latest complete result and the next correction paths or diff. ### Step 11: Final Report Delete the review-fix task file this recipe created, if present. Its work is committed; `docs/plans/` is ephemeral working state. ``` -Code Compliance: +Implementation Review: Initial: [verdict] Final: [verdict] (if fixes executed) @@ -144,19 +145,6 @@ Remaining issues: - [items requiring manual intervention] ``` -## Auto-fixable Items -- Simple unimplemented acceptance criteria -- Error handling additions -- Contract definition fixes -- Function splitting (length/complexity improvements) -- Security confirmed_risk and defense_gap fixes (input validation, auth checks, output encoding) - -## Non-fixable Items -- Fundamental business logic changes -- Architecture-level modifications -- Design Doc deficiencies -- Committed secrets (blocked -> human intervention) - ## Completion Criteria - [ ] Design Doc identified and implementation files checked @@ -167,4 +155,4 @@ Remaining issues: - [ ] Re-validation completed after fixes (both code and security) - [ ] Final report presented to user -**Scope**: Design Doc compliance validation, security review, and auto-fixes. +**Scope**: Completed implementation review, security review, and approved corrections. diff --git a/.agents/skills/recipe-review/agents/openai.yaml b/.agents/skills/recipe-review/agents/openai.yaml index 74f12d0..b0a25a1 100644 --- a/.agents/skills/recipe-review/agents/openai.yaml +++ b/.agents/skills/recipe-review/agents/openai.yaml @@ -1,7 +1,7 @@ interface: display_name: "recipe-review" - short_description: "Design Doc compliance and security validation with auto-fixes" - default_prompt: "Use $recipe-review to validate: " + short_description: "Review implementation scope, quality, and security" + default_prompt: "Use $recipe-review to review: " policy: allow_implicit_invocation: false diff --git a/.agents/skills/subagents-orchestration-guide/SKILL.md b/.agents/skills/subagents-orchestration-guide/SKILL.md index 12eaf0a..5c79c8e 100644 --- a/.agents/skills/subagents-orchestration-guide/SKILL.md +++ b/.agents/skills/subagents-orchestration-guide/SKILL.md @@ -210,7 +210,7 @@ Flow rules: - Frontend and fullstack flows create the UI Spec from completed layer analysis before ADR or Design Doc creation. - After analysis, apply the Choice filter to each `candidateDecisionPoint`, then apply the Durability filter to the retained set. Create one ADR per qualifying point, then review and approve the complete ADR batch once. These filters are the exclusive ADR creation basis and Structural Scale is supporting context. - Pass requirement-analyzer's compact scope evidence and original requirements to `codebase-analyzer`; the orchestrator separately owns and carries the confirmed convergence record until a PRD or Design Doc persists it. -- For Small flows whose confirmed scope is carried by the execution task, use the llm-friendly-context Task File Contract to create `docs/plans/tasks/small-{name}.md`. Build its outcome, targets, steps, and verification from the confirmed requirement and repository scope; embed `outcome`, `requirements`, `nonGoals`, and readiness in `Governing Sources`. Pass the exact file to the layer-appropriate executor. Requirement confirmation authorizes this cycle; work-planner, WorkPlan review, and task-decomposer are outside the path. Remove the task file after security-reviewer passes. +- For Small flows whose confirmed scope is carried by the execution task, use the llm-friendly-context Task File Contract to create `docs/plans/tasks/small-{name}.md`. Build its outcome, targets, steps, and verification from the confirmed requirement and repository scope; embed `outcome`, `requirements`, `nonGoals`, and readiness in `Governing Sources`. Pass the exact file to the layer-appropriate executor. Requirement confirmation authorizes this cycle; work-planner, WorkPlan review, and task-decomposer are outside the path. Remove the task file after Post-Implementation Review passes. - Pass only codebase-analyzer material that changes reuse, option validity or selection, lifecycle cost, a preserved contract, design, or verification to the relevant ADR/Design Doc owner. - Pass a Design Doc path to `code-verifier`, apply Review Resolution to its discrepancies, and pass only resolved verification evidence to `document-reviewer`. - Fullstack layer sequencing is defined in `references/monorepo-flow.md` @@ -236,9 +236,11 @@ After implementation-scope approval, autonomously execute the following processe ``` Approved scope -> task decomposition when needed -> each task: implementation -> optional integration-test review -> quality-fixer -> commit --> final code/security verification -> completion report +-> final code/security review -> completion report ``` +Reviewer findings in this mode are candidates, not work orders; create repair work only from the Review Resolution `apply` set. + For each task, record `diffBase`, run the routed executor, and inspect the resulting repository change. Add each execution or repair result to the Per-Task Change Set. Run integration-test-reviewer when `requiresTestReview` is true and changed integration/E2E paths exist, then resolve findings through Review Resolution. Run the routed quality-fixer with the accumulated `taskWriteSet` and the executor's operation-verification evidence. The quality fixer reruns task-specific verification when evidence is missing or its fixes can invalidate that evidence. On quality approval, add its changed paths to the set and commit the implementation files. After the commit succeeds, mark the Task File's satisfied Completion Criteria and the corresponding Work Plan task and phase complete, then update the active execution plan. Repair `stub_detected` through the same implementation owner. Resolve blocked or unusable results through Orchestrator Escalation Resolution. ### Conditions for Stopping Autonomous Execution @@ -262,18 +264,16 @@ Use the task loop defined in the autonomous execution diagram above. The canonic 3. run the quality fixer on the accumulated change set and repair until approved 4. commit implementation files, then record Task File, Work Plan task/phase, and execution-plan completion locally -### Post-Implementation Verification Pass/Fail Criteria +### Post-Implementation Review -| Verifier | Pass | Fail | Blocked | +| Reviewer | Pass | Requires disposition | Blocked | |----------|------|------|---------| -| code-verifier | `summary.status` is `consistent` | `summary.status` is `needs_review` or `inconsistent` | `summary.status` is `blocked` | +| code-reviewer | `verdict` is `pass` | `verdict` is `needs-improvement` or `needs-redesign` | `verdict` is `blocked` | | security-reviewer | `status` is `approved` | `status` is `needs_revision` | `status` is `blocked` | -Code-verifier runs correspond to durable governing documents. The Small path passes its active task file to security-reviewer as `type: task-file`. Repository quality checks are owned by the quality-fixer run in each implementation and verifier-fix task cycle. - -#### Post-Verification Rerun Rule +Run code-reviewer against the complete implementation change set and its governing Design Docs, or the active task file for a Small flow. When an applied correction changes code, rerun it with `prior_feedback` containing the previous complete result, finding dispositions, and the correction paths or diff; its Rerun Boundary preserves unaffected evidence. The Small path also passes its active task file to security-reviewer as `type: task-file`. Mechanical repository checks remain owned by the quality-fixer in each implementation or review-fix task cycle. -Apply Review Resolution to verifier findings. Consolidate the `apply` set into the fewest executor-routed ephemeral tasks, execute them through the normal task cycle, then re-run only verifiers classified as Fail by the table above. A Pass result completes that verifier's work for this build. Delete the ephemeral task files after final verification. A remaining unusable result enters Orchestrator Escalation Resolution. +Apply Review Resolution to reviewer findings. Apply a security-reviewer finding only when leaving it unresolved would violate an explicit governing requirement or repository rule, or leave a concrete material security failure in the actual reachable trust model. The violated requirement, rule, or failure defines implementation scope: route the smallest correction that resolves it, treating the reviewer's suggestion as one candidate implementation. ## Main Orchestrator Roles diff --git a/.agents/skills/subagents-orchestration-guide/references/review-resolution.md b/.agents/skills/subagents-orchestration-guide/references/review-resolution.md index e18ac54..9ca1e57 100644 --- a/.agents/skills/subagents-orchestration-guide/references/review-resolution.md +++ b/.agents/skills/subagents-orchestration-guide/references/review-resolution.md @@ -16,13 +16,13 @@ For `apply`, pass the complete finding or discrepancy unchanged with its disposi ## 2. Revise and Reconsider -Invoke the responsible author when at least one `apply` finding or discrepancy exists, and pass only the `apply` findings or discrepancies. Then rerun the same reviewer or verifier with its original inputs and the changed artifact or implementation. When that agent accepts `prior_feedback`, include the applied corrections and declined reasons; otherwise keep the dispositions in the active workflow context for orchestrator reassessment. An empty `apply` set proceeds directly to the next workflow step. +Invoke the responsible author when at least one `apply` finding or discrepancy exists, and pass only the `apply` findings or discrepancies. Then rerun the same reviewer or verifier with its original governing inputs, the changed artifact or implementation, and the rerun evidence required by that agent. When that agent accepts `prior_feedback`, include applied corrections and declined reasons; add the previous result and correction paths or diff only when its rerun boundary consumes them. Otherwise keep the dispositions in the active workflow context for orchestrator reassessment. An empty `apply` set proceeds directly to the next workflow step. The reviewer withdraws a declined finding when the reason is consistent with governing evidence. It may maintain the finding when existing or newly observed governing evidence still shows the result is incorrect, non-executable, or non-verifiable. A maintained non-blocking recommendation does not prevent progression. ## 3. Converge Internally -Each rerun checks the current artifact or implementation normally and may report newly observed evidence-backed findings. The orchestrator reassesses the current findings through Section 1. +Each rerun applies the reviewer's or verifier's stated rerun boundary to the current artifact or implementation and may report newly observed evidence-backed findings within that boundary. The orchestrator reassesses the current findings through Section 1. Continue revision and reconsideration while an applied correction or new evidence materially changes the artifact, implementation, evidence, or finding disposition. When a rerun repeats a blocking claim without new evidence or no longer changes the result, the orchestrator decides its disposition from the governing sources. Route a remaining unusable artifact or implementation through Orchestrator Escalation Resolution instead of starting the same Review Resolution again. @@ -35,4 +35,5 @@ Pass only: - artifact or implementation path or ADR batch paths; - complete `apply` findings or discrepancies unchanged with their dispositions; - declined finding IDs with reasons and evidence; +- the previous complete result when the rerun contract uses it to preserve unaffected evidence; - the observable condition the rerun must judge. diff --git a/.codex/agents/code-reviewer.toml b/.codex/agents/code-reviewer.toml index cec940c..3044715 100644 --- a/.codex/agents/code-reviewer.toml +++ b/.codex/agents/code-reviewer.toml @@ -1,9 +1,9 @@ name = "code-reviewer" -description = "Reviews implemented changes for compliance with approved Design Docs and material code correctness." +description = "Reviews completed implementation for governing-source compliance, scope economy, repository quality policy, and material code correctness." sandbox_mode = "read-only" developer_instructions = """ -You review implemented repository changes against approved governing documents. +You review completed repository changes against their approved governing sources. ## Required Skills [LOAD BEFORE EXECUTION] @@ -13,46 +13,62 @@ Load and read each skill completely before taking task actions: `ai-development- ## Inputs -- `designDoc`: one or more governing Design Doc paths -- `implementationFiles`: actual changed implementation and test files, or a diff range -- `reviewMode`: `full` (default), `acceptance`, or `architecture` -- optional Work Plan/task scope -- `prior_feedback`: optional applied corrections and orchestrator-declined finding IDs with reasons and evidence +- `governingDocuments`: one or more approved Design Docs, or the active task file for a Small flow +- `implementationFiles`: the complete implementation change set or its diff range; on a rerun, include the correction paths or diff +- Work Plan and task scope when supplied +- `prior_feedback`: on a rerun, the previous complete review result, finding dispositions, and the correction paths or diff -Verify paths and inspect only references that can change an in-scope finding. +Read `docs/project-context/quality.yaml` when it exists. It adds repository-specific review dimensions; its absence leaves the built-in review boundary unchanged. Verify paths and inspect only references that can change an in-scope finding. ## Review Boundary -Extract the approved outcome, applicable ACs, changed interfaces/contracts, protected behavior, and verification expectations. Review the supplied implementation for: +Extract the approved outcome, applicable ACs or confirmed Small-flow requirements, changed interfaces and contracts, protected behavior, non-goals, required design decisions, and verification expectations. -1. representative evidence that each applicable AC is fulfilled; -2. exact agreement with changed public, serialized, persisted, or user-visible contracts; -3. preservation of the Design Doc's required core mechanism and responsibility boundaries; -4. meaningful verification at the boundary claimed by the task or Design Doc; -5. concrete reliability or maintainability problems introduced by, exposed by, or required to complete the changed path. +The initial review covers every applicable AC or confirmed requirement and each material surface in `implementationFiles`. Before recording findings, build a working review map from those items to their governing contracts and applicable quality dimensions, implementation evidence, the primary failure mode that could pass a shallow happy-path check, and any candidate problem. -Limit required tests for internal details and edge cases to those made part of the current proof by a requirement, preserved behavior, observed defect class, or evidence-backed material risk. Inspect an adjacent case when repository evidence shows it shares the changed cause, contract, or state boundary and leaving it unchanged would keep the same in-scope failure active. +Apply these review boundaries across the complete map in this priority order: -Classify optional hardening, generic refactoring preferences, extra telemetry, external operations, and future product work as non-blocking recommendations. +1. **Outcome and contracts**: confirm each applicable AC or confirmed requirement with direct implementation or test evidence and preserve changed public, serialized, persisted, user-visible, and error contracts. +2. **Scope economy**: for each material mechanism, abstraction, dependency, state, defensive control, or test added by the change, identify its governing requirement, selected design decision, repository rule, observed contract or failure, or evidence-backed material risk in the actual reachable changed path. When removing or narrowing an unsupported addition preserves the approved outcome and contracts, report that reduction as the correction. +3. **Required design and proof**: preserve the governing source's required mechanism and responsibility boundaries, and require proof only at the boundary claimed by the task or governing source. +4. **Code quality**: apply `ai-development-guide`, `coding-rules`, and `testing` to concrete changed-path correctness, contract safety, repository-local patterns, error behavior, and proof quality. +5. **Repository quality policy**: apply each `docs/project-context/quality.yaml` dimension whose `applies_when` condition matches the change. Its `pass` condition and cited `evidence` define the repository-specific accepted state. + +Inspect an adjacent case when repository evidence shows it shares the changed cause, contract, or state boundary and leaving it unchanged would keep the same in-scope failure active. Limit required tests for internal details and edge cases to those made part of the current proof by a requirement, preserved behavior, observed defect class, applicable quality dimension, or evidence-backed material risk. + +Continue through every mapped item after observing a candidate problem. Choose the verdict only after each item has direct evidence of fulfillment, a candidate problem, or a limitation that prevents its judgment. Then verify candidates against supporting and contradicting evidence, consolidate candidates only when one correction resolves the same cause, and apply the Findings boundary. + +## Rerun Boundary + +When `prior_feedback` contains the previous complete result, use that result as the accepted review baseline. Recheck: + +- each applied finding against the current implementation; +- the correction paths or diff for new material problems; +- previously fulfilled ACs or requirements, contracts, or quality dimensions only when the correction can invalidate their cited evidence. + +Carry forward other fulfilled items and their evidence. Limit new findings to the correction or a directly affected contract, responsibility, proof boundary, or applicable quality dimension. This rerun boundary replaces the initial full review. ## Findings Use these categories: - `dd_violation`: implementation contradicts an approved requirement or design contract; +- `scope_excess`: a material addition lacks an approved or evidence-backed need and can be removed or narrowed while preserving the outcome; - `reliability`: a concrete changed-path failure remains possible under stated conditions; - `coverage_gap`: required observable behavior or Verification Focus is not substantively proven; -- `maintainability`: changed code materially obscures or mixes the responsibility required for this outcome; +- `quality_rule`: an applicable `docs/project-context/quality.yaml` pass condition is false; - `adjacent_residual`: the same verified cause remains in an adjacent in-scope path. -Every finding includes file:line evidence, governing basis, the observable effect, and the smallest sufficient correction. Set `blocking: true` only when the implementation would otherwise be incorrect, non-executable, non-verifiable, or contradictory to a governing source. +Output a finding only when correction is required because the implementation is incorrect, non-executable, non-verifiable, contradictory to a governing source, or carries a material unsupported addition or quality-policy violation. Every finding includes file:line evidence, its governing basis, the observable effect, and the smallest sufficient correction. Express `suggestion` as the smallest observable post-fix state; name an implementation mechanism when the governing source requires that mechanism. For `scope_excess`, prefer removal or narrowing over a replacement mechanism. + +Withdraw a declined finding when its reason remains consistent with governing evidence. Maintain it only when current or newly observed evidence still proves a required-correction condition. -When `prior_feedback` is present, review the current implementation normally. Withdraw a declined finding when its reason remains consistent with governing evidence. Maintain it only when current or newly observed evidence still proves a blocking condition; newly observed findings require current evidence. +Use `limitations` only for unavailable evidence that prevents judging an applicable AC or requirement, contract, material addition, or quality dimension, and state the blocked judgment's effect. ## Verdict -- `pass`: no blocking finding remains; non-blocking recommendations may be reported. -- `needs-improvement`: blocking findings are repairable within approved scope. +- `pass`: no required-correction finding remains. +- `needs-improvement`: findings are repairable within approved scope. - `needs-redesign`: resolution requires changing the approved outcome, public contract, or major design decision. - `blocked`: required inputs or repository evidence are unavailable. @@ -61,13 +77,16 @@ When `prior_feedback` is present, review the current implementation normally. Wi Return one JSON object: ```json -{"verdict":"pass|needs-improvement|needs-redesign|blocked","acceptanceCriteria":[{"item":"AC-001","status":"fulfilled|unfulfilled","evidence":["file:line or command result"],"gap":"material gap or null"}],"findings":[{"id":"F001","category":"dd_violation|reliability|coverage_gap|maintainability|adjacent_residual","location":"file:line","description":"specific issue","basis":"governing source or observed fact","effect":"observable consequence","blocking":true,"suggestion":"smallest sufficient correction"}],"recommendations":["non-blocking item"],"limitations":["unverified item and effect"]} +{"verdict":"pass|needs-improvement|needs-redesign|blocked","acceptanceCriteria":[{"item":"governing criterion identifier or text","status":"fulfilled|unfulfilled","evidence":["file:line or command result"],"gap":"material gap or null"}],"findings":[{"id":"F001","category":"dd_violation|scope_excess|reliability|coverage_gap|quality_rule|adjacent_residual","location":"file:line","description":"specific required-correction issue","basis":"governing source, quality dimension, or observed fact","effect":"observable consequence","suggestion":"smallest sufficient correction"}],"limitations":["unverified item and effect"]} ``` ## Completion Check -- Applicable ACs and changed contracts were checked with direct evidence. +- The initial review resolved every mapped AC or confirmed requirement and material changed surface before choosing its verdict; a rerun preserved unaffected evidence and checked only correction-affected review boundaries. +- Applicable ACs or requirements and changed contracts were checked with direct evidence. +- Material additions were traced to approved or evidence-backed needs, or reported with removal or narrowing as the correction. - Required test evidence observes the claimed behavior rather than a placeholder or substitute boundary. -- Every blocking finding is tied to approved scope or a material changed-path failure. +- Every emitted finding requires correction under the Findings boundary. +- Applicable `docs/project-context/quality.yaml` dimensions were checked against their cited repository evidence. - Review breadth and proposed corrections stay within the approved outcome. """ diff --git a/.codex/agents/integration-test-reviewer.toml b/.codex/agents/integration-test-reviewer.toml index 806ddfc..764ea4a 100644 --- a/.codex/agents/integration-test-reviewer.toml +++ b/.codex/agents/integration-test-reviewer.toml @@ -31,16 +31,16 @@ For each changed test, verify: 5. state-changing claims assert the relevant before/action/after result when needed; 6. fixtures and isolation are sufficient for the repository's normal execution model. -Limit required AAA comments, additional edge cases, separate assertions, and stylistic cleanup to changes needed to make the selected proof clear and valid. Classify recommendations that leave the proof valid as non-blocking. +Treat the test as acceptable when the selected proof is clear and valid. Output only material proof gaps; keep optional AAA comments, additional edge cases, separate assertions, and stylistic cleanup out of the response. -When `prior_feedback` is present, withdraw declined findings whose reasons remain consistent with governing evidence and maintenance value. Maintain a finding only when the proof remains materially invalid; a non-blocking recommendation permits approval. +When `prior_feedback` is present, withdraw declined findings whose reasons remain consistent with governing evidence and maintenance value. Maintain a finding only when the proof remains materially invalid. ## Output Return one JSON object: ```json -{"status":"approved|needs_revision|blocked","testFiles":["path"],"reviewBasis":"skeleton|task|prompt","findings":[{"id":"T001","location":"file:test","description":"material proof gap","basis":"governing claim or proof obligation","effect":"behavior left unproven","blocking":true,"suggestion":"smallest sufficient correction"}],"recommendations":["non-blocking item"]} +{"status":"approved|needs_revision|blocked","testFiles":["path"],"reviewBasis":"skeleton|task|prompt","findings":[{"id":"T001","location":"file:test","description":"material proof gap","basis":"governing claim or proof obligation","effect":"behavior left unproven","blocking":true,"suggestion":"smallest sufficient correction"}]} ``` Use `approved` when no blocking proof gap remains, `needs_revision` when a gap is repairable within the selected claim and lane, and `blocked` only for unusable inputs or contradictory governing proof. @@ -49,5 +49,5 @@ Use `approved` when no blocking proof gap remains, `needs_revision` when a gap i - Only changed tests and their governing proof were reviewed. - Every blocking finding identifies a material invalid or missing proof. -- Review suggestions expand the test set or lane only after passing the Selection Gate. +- Every suggested correction is the smallest change that restores the selected proof and expands the test set or lane only after passing the Selection Gate. """ diff --git a/.codex/agents/security-reviewer.toml b/.codex/agents/security-reviewer.toml index e17f8f6..1c15efa 100644 --- a/.codex/agents/security-reviewer.toml +++ b/.codex/agents/security-reviewer.toml @@ -1,5 +1,5 @@ name = "security-reviewer" -description = "Reviews implementation security against authoritative Design Docs, Work Plans, or Small-flow task files. Returns structured findings with risk classification and fix suggestions." +description = "Reviews implementation security against authoritative Design Docs, Work Plans, or Small-flow task files. Returns only must-fix findings with the smallest sufficient corrections." sandbox_mode = "read-only" developer_instructions = """ @@ -11,6 +11,12 @@ Load and read each skill completely before taking task actions: `coding-rules`. **Execution Plan**: For work with multiple dependent actions, use `update_plan` to track them through final verification and reuse an active plan. A single-action task proceeds directly. Complete a plan step after verifying its result; start a dependent step after its prerequisites are satisfied. +## Output Boundary + +The response is a release-blocking exception list. Emit a finding only when current evidence shows that the approved scope cannot be accepted without correction because the implementation violates an explicit governing requirement or repository rule, or because a concrete material security failure exists in the actual reachable trust model. Evaluate that decision against actor reachability, deployed exposure, the project's runtime environment, framework protections, existing mitigations, and observable impact. + +Each finding contains exactly one must-fix problem and its smallest sufficient correction. Keep optional hardening and defense-in-depth out of the response; when only those candidates exist, return `approved`. A candidate that would only make an already-acceptable trust boundary more resilient is optional hardening. + ## Responsibilities 1. Verify implementation compliance with security requirements in the governing artifacts @@ -76,9 +82,7 @@ Consolidate all findings, remove duplicates, and classify each finding into one | Category | Definition | Examples | |----------|-----------|----------| | **confirmed_risk** | An attack surface is exploitable in the implementation as-is | Missing authentication on endpoint, arbitrary file access, SQL injection via string concatenation | -| **defense_gap** | A governing security requirement or in-scope security boundary lacks a required defensive control | Runtime type validation missing at an input boundary, unnecessary capability enabled | - -Emit a finding only when current evidence shows a correction is required to satisfy a governing security requirement or protect an in-scope security boundary. Evaluate it against the project's runtime environment, framework protections, and existing mitigations. +| **defense_gap** | A governing security requirement or in-scope security boundary lacks a required defensive control | Required runtime type validation missing at an input boundary | When `prior_feedback` is present, review the current implementation normally. Withdraw a declined finding when its reason remains consistent with governing evidence. Maintain it only when current or newly observed evidence still supports `needs_revision`; newly observed findings require current evidence. @@ -116,7 +120,7 @@ Otherwise return `needs_revision` when `findings` is non-empty and `approved` wh - [ ] Applicable stable and trend-sensitive patterns exposed by coding-rules searched - [ ] Conditional advisory check performed or marked not applicable with reason - [ ] Each finding classified into confirmed_risk / defense_gap -- [ ] Every finding requires correction after considering the runtime environment and existing mitigations +- [ ] Every finding is one must-fix problem grounded in a governing requirement, repository rule, or concrete material failure in the actual reachable trust model, and its suggestion is the smallest sufficient correction; optional hardening and defense-in-depth are absent - [ ] Committed secrets checked (blocked status if found) - [ ] Final response is the JSON output diff --git a/README.md b/README.md index c39bdba..b30cb86 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,7 @@ codex-workflows controls that expansion throughout the run: | Scope | The workflow compares the request with the desired outcome, explicit exclusions, the existing code, and rough implementation cost. Work that does not earn its cost is removed before it becomes architecture. | | Phase gates | Requirements, design, and planning outputs are checked before they can authorize the next phase. Fresh agents read the approved decisions and evidence they need instead of reconstructing intent from a long conversation. | | Execution | After implementation approval, Codex executes the task set autonomously. Each task passes its focused verification and applicable repository checks before its implementation commit. | -| Completion | Independent code and security verification inspect the whole change. Required corrections return through the same implementation and quality cycle; optional hardening can be declined with evidence. | +| Completion | Independent code and security review inspects the completed change for approved scope and material failures. Required corrections return through the same implementation and quality cycle. | This workflow uses more agent calls and tokens than direct execution. Use it when protecting the approved outcome is worth that cost. @@ -71,6 +71,7 @@ $recipe-implement Add user authentication with JWT | 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` | +| Create or maintain repository-specific review policy | `$recipe-quality-profile` | | Investigate a problem without changing code | `$recipe-diagnose` | | Run a throwaway experiment or one-shot script | Use Codex directly | @@ -88,7 +89,7 @@ flowchart LR D --> E[Plan dependent work] E --> F[Approve implementation scope] F --> H[Per task: implement, verify, quality-check, commit] - H --> K[Independent code and security verification] + H --> K[Independent code and security review] K -->|Correction| H K -->|Requirement or major design changed| B K -->|Passed| L[Complete] @@ -123,7 +124,7 @@ Fresh contexts keep exploration, design, implementation, and review from silentl - **Verification**: Run the contract test and observe the documented response shape ``` -The [Task File Contract](.agents/skills/llm-friendly-context/references/task-template.md) carries the source, intended result, target files, and executable verification into implementation. It adds a `Verification Focus` only when a test could pass without proving one important behavior. After execution, the applicable repository checks run against the complete task change before commit. Final reviewers compare the approved documents with the completed code and rerun after accepted corrections. +The [Task File Contract](.agents/skills/llm-friendly-context/references/task-template.md) carries the source, intended result, target files, and executable verification into implementation. It adds a `Verification Focus` only when a test could pass without proving one important behavior. After execution, the applicable repository checks run against the complete task change before commit. Final reviewers compare the approved documents with the completed code, check for unsupported implementation scope and material code-quality failures, and rerun only the correction-affected review boundary after accepted corrections. `docs/project-context/quality.yaml`, generated or updated with `$recipe-quality-profile`, can add evidence-backed repository policy to that review. --- @@ -200,7 +201,8 @@ Invoke recipes with `$recipe-name` in Codex. Type `$recipe-` and use tab complet | `$recipe-plan` | Design Doc → selective integration/E2E skeletons → work plan | Planning phase from an approved Design Doc | | `$recipe-prepare-implementation` | Prepare existing repository-local tools needed by an approved Work Plan | Explicit setup request or a concrete task capability is unavailable | | `$recipe-build` | Execute backend tasks with validation between steps | Resume backend implementation | -| `$recipe-review` | Design Doc compliance and security validation with optional approved corrections | Post-implementation check | +| `$recipe-review` | Implementation scope, Design Doc compliance, code quality, and security review with user-approved corrections | Post-implementation check | +| `$recipe-quality-profile` | Generate or update `docs/project-context/quality.yaml` from repository evidence | Repository review-policy setup and maintenance | | `$recipe-diagnose` | Problem investigation → failure-point verification → solution | Bug investigation | | `$recipe-reverse-engineer` | Generate PRD + Design Docs from existing code | Legacy system documentation | | `$recipe-add-integration-tests` | Add integration/E2E tests from Design Doc | Test coverage for existing code | @@ -214,7 +216,7 @@ Invoke recipes with `$recipe-name` in Codex. Type `$recipe-` and use tab complet | `$recipe-front-adjust` | Focused UI adjustment using repository, supplied, or required external evidence | Focused UI changes after implementation | | `$recipe-front-plan` | Frontend Design Doc → selective integration/E2E skeletons → work plan | Frontend planning phase | | `$recipe-front-build` | Execute frontend tasks with focused verification and quality checks | Resume frontend implementation | -| `$recipe-front-review` | Frontend compliance and security validation with optional approved React corrections | Frontend post-implementation check | +| `$recipe-front-review` | Frontend scope, compliance, code quality, and security review with user-approved React corrections | Frontend post-implementation check | ### Fullstack (Cross-Layer) @@ -303,7 +305,7 @@ Codex spawns these as needed during recipe execution. You do not need to learn t | Agent | Role | |-------|------| -| `code-reviewer` | Design Doc compliance validation | +| `code-reviewer` | Completed implementation scope, governing-source compliance, and material code-quality review | | `code-verifier` | Document-code consistency verification | | `security-reviewer` | Security compliance review after implementation | | `rule-advisor` | Skill selection for standalone work not already governed by a recipe | diff --git a/package.json b/package.json index 61b75a1..e513dd2 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "codex-workflows", - "version": "1.2.2", + "version": "1.3.0", "description": "Codex CLI workflows that keep larger software changes within the approved scope, from planning through review", "license": "MIT", "author": "Shinsuke Kagawa",