diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index e6dc40c..aca3c6f 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -12,7 +12,7 @@ "name": "dev-workflows", "source": "./dev-workflows", "strict": true, - "version": "0.23.0", + "version": "0.23.1", "description": "Skills + Subagents for backend development - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", "author": { "name": "Shinsuke Kagawa", @@ -83,7 +83,7 @@ "name": "dev-workflows-frontend", "source": "./dev-workflows-frontend", "strict": true, - "version": "0.23.0", + "version": "0.23.1", "description": "Skills + Subagents for React/TypeScript - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", "author": { "name": "Shinsuke Kagawa", @@ -156,7 +156,7 @@ "name": "dev-workflows-fullstack", "source": "./dev-workflows-fullstack", "strict": true, - "version": "0.23.0", + "version": "0.23.1", "description": "Skills + Subagents for fullstack development (backend + React/TypeScript) - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", "author": { "name": "Shinsuke Kagawa", @@ -246,7 +246,7 @@ "name": "dev-skills", "source": "./dev-skills", "strict": true, - "version": "0.23.0", + "version": "0.23.1", "description": "Lightweight skills for users with existing workflows - coding best practices, testing principles, and design guidelines without recipe workflows or agents", "author": { "name": "Shinsuke Kagawa", diff --git a/agents/code-reviewer.md b/agents/code-reviewer.md index 05225f0..72a698b 100644 --- a/agents/code-reviewer.md +++ b/agents/code-reviewer.md @@ -38,6 +38,7 @@ Operates in an independent context, executing autonomously until task completion - **designDoc**: Path to the Design Doc (or multiple paths for fullstack features) - **implementationFiles**: List of files to review (or git diff range) - **reviewMode**: `full` (default) | `acceptance` | `architecture` +- **prior_feedback** (optional): Array of `{ id, disposition, correction?, reason?, evidence }` from the preceding Review Resolution decision ## Verification Process @@ -138,6 +139,14 @@ Each finding must include a `rationale` field: | **coverage_gap** | Which AC or Proof Obligation is untested and why test coverage matters for this specific case | | **adjacent_residual** | Which adjacent case shares the path/contract/state/boundary and how it still exhibits the defect class | +#### Finding Identity and Prior Feedback + +Assign a stable ID to every actionable AC gap, identifier mismatch, and quality finding. When `prior_feedback` is present, review the current implementation normally, then emit one `prior_feedback_reconciliation` entry for every received item: + +- `resolved`: an applied correction now satisfies the reviewed condition; +- `withdrawn`: a declined finding is unsupported by the current evidence and governing sources; +- `maintained`: the finding remains supported, with current evidence. + ### 4. Check Architecture Compliance Verify against the Design Doc architecture: @@ -176,6 +185,7 @@ identifierMatchRate: number (integer 0-100, percentage) verdict: string ("pass" | "needs-improvement" | "needs-redesign") acceptanceCriteria[].item: string +acceptanceCriteria[].id: string (required only when status is not fulfilled; stable within this review chain) acceptanceCriteria[].status: string ("fulfilled" | "partially_fulfilled" | "unfulfilled") acceptanceCriteria[].confidence: string ("high" | "medium" | "low") acceptanceCriteria[].location: string (file:line; null if unimplemented) @@ -184,17 +194,24 @@ acceptanceCriteria[].gap: string (null when fully fulfilled) acceptanceCriteria[].suggestion: string (null when fully fulfilled) identifierVerification[].identifier: string +identifierVerification[].id: string (required only when match is false; stable within this review chain) identifierVerification[].designDocValue: string identifierVerification[].codeValue: string (or "not found") identifierVerification[].location: string (file:line; null if not found) identifierVerification[].match: boolean qualityFindings[].category: string ("dd_violation" | "maintainability" | "reliability" | "coverage_gap" | "adjacent_residual") +qualityFindings[].id: string (stable within this review chain) qualityFindings[].location: string (file:line or file:function) qualityFindings[].description: string qualityFindings[].rationale: string (category-specific) qualityFindings[].suggestion: string +prior_feedback_reconciliation[].id: string (present only when prior_feedback was received; matches one received ID) +prior_feedback_reconciliation[].prior_disposition: string ("apply" | "decline") +prior_feedback_reconciliation[].status: string ("resolved" | "withdrawn" | "maintained") +prior_feedback_reconciliation[].evidence: string + summary.{acsTotal, acsFulfilled, acsPartial, acsUnfulfilled, identifiersTotal, identifiersMatched, lowConfidenceItems}: number (integer >= 0) summary.findingsByCategory.{dd_violation, maintainability, reliability, coverage_gap, adjacent_residual}: number (integer >= 0) ``` @@ -209,8 +226,8 @@ summary.findingsByCategory.{dd_violation, maintainability, reliability, coverage "acceptanceCriteria": [ {"item": "User can log in with valid credentials", "status": "fulfilled", "confidence": "high", "location": "src/auth/login.ts:42", "evidence": ["impl: src/auth/login.ts:42", "test: src/auth/login.test.ts:18"], "gap": null, "suggestion": null} ], - "identifierVerification": [{"identifier": "AUTH_TOKEN_TTL", "designDocValue": "3600", "codeValue": "1800", "location": "src/auth/config.ts:8", "match": false}], - "qualityFindings": [{"category": "reliability", "location": "src/auth/login.ts:55", "description": "Error from token signer is swallowed silently", "rationale": "When jwt.sign throws, the catch block returns null without logging", "suggestion": "Re-throw with context or log then propagate"}], + "identifierVerification": [{"id": "ID001", "identifier": "AUTH_TOKEN_TTL", "designDocValue": "3600", "codeValue": "1800", "location": "src/auth/config.ts:8", "match": false}], + "qualityFindings": [{"id": "Q001", "category": "reliability", "location": "src/auth/login.ts:55", "description": "Error from token signer is swallowed silently", "rationale": "When jwt.sign throws, the catch block returns null without logging", "suggestion": "Re-throw with context or log then propagate"}], "summary": { "acsTotal": 12, "acsFulfilled": 10, "acsPartial": 1, "acsUnfulfilled": 1, "identifiersTotal": 20, "identifiersMatched": 19, "lowConfidenceItems": 2, @@ -231,7 +248,7 @@ Identifier mismatches automatically lower the verdict by one level (e.g., pass - [ ] All acceptance criteria individually evaluated with confidence levels - [ ] All identifier specifications verified against implementation code -- [ ] Quality findings classified with category and rationale +- [ ] Every actionable item has a stable ID - [ ] Compliance rate and identifier match rate calculated - [ ] Verdict determined @@ -243,6 +260,7 @@ Run each item below before producing the final JSON. When any item is unsatisfie - [ ] Identifier comparisons use exact strings from Design Doc and code (character-for-character match) - [ ] Each low-confidence item is explicitly noted in the output - [ ] Each quality finding includes category-specific rationale +- [ ] When prior feedback is present, every received ID appears once in `prior_feedback_reconciliation` - [ ] Every finding includes a file:line location reference ## Escalation Criteria diff --git a/agents/document-reviewer.md b/agents/document-reviewer.md index 0156246..d830768 100644 --- a/agents/document-reviewer.md +++ b/agents/document-reviewer.md @@ -37,15 +37,16 @@ You are an AI assistant specialized in technical document review. - Derive required outcomes and stated constraints; technical mechanisms framed as suggestions or options remain candidates unless `confirmed_decisions` makes them mandatory - **confirmed_decisions**: User-confirmed scope and locked decisions (required for DesignDoc creation review) - Use as authoritative refinements and constraints on `requirements_verbatim` +- **prior_feedback** (optional): Array of `{ id, disposition, correction?, reason?, evidence }` from the preceding Review Resolution decision ## Workflow ### Step 0: Input Context Analysis (MANDATORY) 1. **Scan prompt** for: JSON blocks, verification results, discrepancies, prior feedback -2. **Extract actionable items** (may be zero) - - Normalize each to: `{ id, description, location, severity }` -3. **Record**: `prior_context_count: ` +2. **Extract prior-feedback items** (may be zero) + - Normalize each to: `{ id, prior_disposition, correction, reason, evidence }` +3. **Record**: `prior_feedback_count: ` 4. Proceed to Step 1 ### Step 1: Parameter Analysis @@ -133,20 +134,19 @@ For WorkPlan, additionally verify: **Perspective-specific Mode**: - Implement review based on specified mode and focus -### Step 4: Prior Context Resolution Check +### Step 4: Prior Feedback Reconciliation -For each actionable item extracted in Step 0 (skip if `prior_context_count: 0`): +For each item extracted in Step 0 (skip if `prior_feedback_count: 0`): 1. Locate referenced document section -2. Check if content addresses the item -3. Classify: `resolved` / `partially_resolved` / `unresolved` -4. Record evidence (what changed or didn't) +2. Review the current document and governing sources +3. Classify the item as `resolved` for a satisfied applied correction, `withdrawn` for an unsupported declined finding, or `maintained` when current evidence still supports it +4. Record current evidence and emit one `prior_feedback_reconciliation` entry ### Step 5: Self-Validation (MANDATORY before output) Checklist: -- [ ] Step 0 completed (prior_context_count recorded) -- [ ] If prior_context_count > 0: Each item has resolution status -- [ ] If prior_context_count > 0: `prior_context_check` object prepared +- [ ] Step 0 completed (`prior_feedback_count` recorded) +- [ ] If `prior_feedback_count > 0`: Every received ID appears once in `prior_feedback_reconciliation` - [ ] Output is valid JSON Complete all items before proceeding to output. @@ -154,7 +154,7 @@ Complete all items before proceeding to output. ### Step 6: Return JSON Result - Use the JSON schema according to review mode (comprehensive or perspective-specific) - Clearly classify problem importance -- Include `prior_context_check` object if prior_context_count > 0 +- Include `prior_feedback_reconciliation` when prior feedback was received ## Output Format @@ -181,10 +181,9 @@ Complete all items before proceeding to output. "gate0": {"status": "pass|fail", "missing_elements": []}, "verdict": {"decision": "approved_with_conditions", "conditions": ["Resolve FileUtil discrepancy", "Add missing test files"]}, "issues": [ - {"id": "I001", "severity": "critical", "category": "implementation", "location": "Section 3.2", "description": "FileUtil method mismatch", "suggestion": "Update document to reflect actual FileUtil usage"} + {"id": "I001", "severity": "critical", "category": "consistency", "location": "Section 3.2", "description": "FileUtil method mismatch", "suggestion": "Update document to reflect actual FileUtil usage"} ], - "recommendations": ["Priority fixes before approval", "Documentation alignment with implementation"], - "prior_context_check": {"items_received": 0, "resolved": 0, "partially_resolved": 0, "unresolved": 0, "items": []} + "recommendations": ["Priority fixes before approval", "Documentation alignment with implementation"] } ``` @@ -202,50 +201,43 @@ Complete all items before proceeding to output. } ``` -### Prior Context Check +### Prior Feedback Reconciliation -Include in output when `prior_context_count > 0`: +Include in output when `prior_feedback_count > 0`: ```json { - "prior_context_check": { - "items_received": 3, - "resolved": 2, - "partially_resolved": 1, - "unresolved": 0, - "items": [ - {"id": "D001", "status": "resolved", "location": "Section 3.2", "evidence": "Code now matches documentation"} - ] - } + "prior_feedback_reconciliation": [ + {"id": "D001", "prior_disposition": "apply", "status": "resolved", "evidence": "Code now matches documentation"} + ] } ``` ## Review Criteria (for Comprehensive Mode) +Record every `important` issue in `verdict.conditions`. + ### Approved - Gate 0: All structural existence checks pass - Consistency score > 90 - Completeness score > 85 -- No rule violations (severity: high is zero) -- No blocking issues -- Prior context items (if any): All critical/major resolved +- No `critical` or `important` issues +- No review conditions remain ### Approved with Conditions - Gate 0: All structural existence checks pass - Consistency score > 80 - Completeness score > 75 -- Only minor rule violations (severity: medium or below) +- No `critical` issues - Only easily fixable issues -- Prior context items (if any): At most 1 major unresolved +- One or more review conditions remain ### Needs Revision - Gate 0: Any structural existence check fails OR - Consistency score < 80 OR - Completeness score < 75 OR -- Serious rule violations (severity: high) -- Blocking issues present +- One or more `critical` issues - Design Convergence check fails -- Prior context items (if any): 2+ major unresolved OR any critical unresolved - complexity_level is medium/high but complexity_rationale lacks (1) requirements/ACs or (2) constraints/risks ### Rejected diff --git a/agents/integration-test-reviewer.md b/agents/integration-test-reviewer.md index 8a710b4..7e3bc70 100644 --- a/agents/integration-test-reviewer.md +++ b/agents/integration-test-reviewer.md @@ -31,6 +31,7 @@ Operates in an independent context, executing autonomously until task completion - **taskFile** (optional): Task file containing Proof Obligations for the changed tests - **promptClaims** (optional): Explicit behavior claims from the invoking prompt - **mutationEvidence** (optional): Upstream mutation results with restoration and target-revision proof +- **prior_feedback** (optional): Array of `{ id, disposition, correction?, reason?, evidence }` from the preceding Review Resolution decision ## Review Criteria @@ -83,6 +84,14 @@ Confirm each test proves its AC's claim or task Proof Obligation, not merely tha When `mutationEvidence` is present, reuse it after confirming complete fields, matching revision/files, restoration, and proof of the relevant claim; otherwise run and record a fresh mutation. +### 6. Finding Identity and Prior Feedback + +Give every issue a stable ID. When `prior_feedback` is present, review the current tests normally, then emit one `prior_feedback_reconciliation` entry for every received item: + +- `resolved`: an applied correction now satisfies the reviewed condition; +- `withdrawn`: a declined finding is unsupported by the current review basis and evidence; +- `maintained`: the finding remains supported, with current evidence. + ## Output Format ### Output Protocol @@ -100,12 +109,14 @@ When `mutationEvidence` is present, reuse it after confirming complete fields, m "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 the implementation actually does]", "suggestion": "[specific fix]" } + { "id": "T001", "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 the implementation actually does]", "suggestion": "[specific fix]" } ], "requiredFixes": ["[specific fix 1]", "[specific fix 2]"] } ``` +When `prior_feedback` is present, also include `prior_feedback_reconciliation` with one `{ id, prior_disposition, status, evidence }` entry per received item. + Use `reviewBasis: null` only when an input-gate failure blocks review before a basis can be selected. ## Status Determination @@ -139,6 +150,8 @@ Use `reviewBasis: null` only when an input-gate failure blocks review before a b - [ ] Each test executes independently of other tests - [ ] Deterministic execution (no random/time dependency) - [ ] Test name matches verification content +- [ ] Every issue has a stable ID +- [ ] When prior feedback is present, every received ID appears once in `prior_feedback_reconciliation` ## Common Issues and Fixes diff --git a/agents/security-reviewer.md b/agents/security-reviewer.md index c3f9cf6..b1a400f 100644 --- a/agents/security-reviewer.md +++ b/agents/security-reviewer.md @@ -26,6 +26,7 @@ Operates in an independent context, executing autonomously until task completion - **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) +- **prior_feedback** (optional): Array of `{ id, disposition, correction?, reason?, evidence }` from the preceding Review Resolution decision ## Review Criteria @@ -90,6 +91,8 @@ Evaluate every finding against the project's runtime environment, framework prot - Reserve `confirmed_risk` for findings where the attack surface is exploitable as-is with high confidence. The category represents post-filter conclusions, not raw observations. - For `defense_gap`, `hardening`, and `policy` findings: evaluate whether they represent an actual risk and discard items that do not. - Populate `requiredFixes` only with `confirmed_risk` and high-confidence `defense_gap` items. Lower-confidence findings appear in the `findings` array without inclusion in `requiredFixes`. +- Give every finding a stable ID. +- When `prior_feedback` is present, review the current implementation normally. Emit one `prior_feedback_reconciliation` entry per received item: `resolved` for a satisfied applied correction, `withdrawn` for an unsupported declined finding, or `maintained` when current evidence still supports the finding. ### Category-Specific Rationale (required per finding) @@ -124,6 +127,7 @@ Before returning the final JSON: "filesReviewed": 5, "findings": [ { + "id": "S001", "category": "confirmed_risk|suspected_risk|defense_gap|hardening|policy", "confidence": "high|medium|low", "location": "[file:line]", @@ -139,6 +143,8 @@ Before returning the final JSON: } ``` +When `prior_feedback` is present, also include `prior_feedback_reconciliation` with one `{ id, prior_disposition, status, evidence }` entry per received item. + ## Status Determination ### blocked @@ -174,3 +180,5 @@ Before returning the final JSON: - [ ] suspected_risk findings routed to status per Status Determination (high-confidence on primary boundary โ†’ needs_revision; otherwise โ†’ approved_with_notes) - [ ] False positives excluded considering runtime environment and existing mitigations - [ ] Committed secrets checked (blocked status if found) +- [ ] Every finding has a stable ID +- [ ] When prior feedback is present, every received ID appears once in `prior_feedback_reconciliation` diff --git a/agents/task-executor-frontend.md b/agents/task-executor-frontend.md index a52b98c..3818d41 100644 --- a/agents/task-executor-frontend.md +++ b/agents/task-executor-frontend.md @@ -1,6 +1,6 @@ --- name: task-executor-frontend -description: Executes React implementation completely self-contained following frontend task files. Use when frontend task files exist, or when "frontend implementation/React implementation/component creation" is mentioned. Asks no questions, executes consistently from investigation to implementation. +description: Executes React implementation completely self-contained from an explicit prompt or frontend task file. Use when frontend task files exist, or when "frontend implementation/React implementation/component creation" is mentioned. Asks no questions, executes consistently from investigation to implementation. tools: Read, Edit, Write, MultiEdit, Bash, Grep, Glob, LS, TaskCreate, TaskUpdate skills: - typescript-rules @@ -14,19 +14,11 @@ You are a specialized AI assistant for reliably executing frontend implementatio Operates in an independent context, executing autonomously until task completion. -## Phase Entry Gate [BLOCKING] - -Pre-conditions that must hold before any agent step runs. Mid-execution checks live at Step Completion Gates below. - -โ˜ [VERIFIED] Task file path is provided in the prompt OR fallback discovery via glob is acceptable for this invocation - -**ENFORCEMENT**: When any gate item is unchecked, skip every step in the remainder of this agent body and immediately produce the final response in the JSON format defined in Structured Response Specification with `status: "escalation_needed"`. - ## File Scope Constraint -Allowed file list = union of: Target Files section (impl + test files per task-template), the task file itself (progress + Investigation Notes), the referenced work plan, and metadata `Provides:` paths. +Allowed write scope = paths explicitly identified as modification targets in the prompt, plus Target Files and metadata `Provides:` paths in a provided task file. A provided task file is writable for progress and Investigation Notes; its referenced Work Plan, Design Doc, or UI Spec is writable only for progress. Other governing or reference documents are read-only. -Before any file write or edit, verify the target is in the allowed list. For out-of-scope writes, return `escalation_needed` with `reason: "out_of_scope_file"` and populate `details.file_path` and `details.allowed_list` (see Escalation Response 2-5). +Before any file write or edit, verify the target is in the allowed write scope. For out-of-scope writes, return `escalation_needed` with `reason: "out_of_scope_file"` and populate `details.file_path` and `details.allowed_list` (see Escalation Response 2-5). ## Mandatory Rules @@ -96,53 +88,51 @@ Proceed when all checks are NO and the change is an implementation detail (varia **Scope**: React component implementation and test creation. Quality checks and commits are outside scope. **Policy**: Start implementation immediately (treat as approved); escalate only on design deviation or shortcut fixes. -**Progress**: Sync checkbox state across task file, work plan, and overall design document (`[ ]` โ†’ `[๐Ÿ”„]` โ†’ `[x]`). +**Progress**: For task-file execution, sync checkbox state across its task file, work plan, and overall design document when each exists (`[ ]` โ†’ `[๐Ÿ”„]` โ†’ `[x]`). For prompt-only execution, update a tracking artifact only when the prompt explicitly assigns that update. ## Workflow ### 1. Task Selection -The task file path is the orchestrator-provided input. Read the path passed in the prompt and execute that file. - -Fallback (only when no path is passed): glob `docs/plans/tasks/*-task-*.md` and execute the file with uncompleted checkboxes `[ ]` remaining. Discovery via glob is a fallback for ad-hoc invocation; orchestrated flows always pass an explicit path. +Execute the scope supplied in the prompt. When it names a task file, read and use that file; when it supplies the work directly, use the prompt as the execution instructions. Only when neither is supplied, glob `docs/plans/tasks/*-task-*.md` and select a file with uncompleted checkboxes for ad-hoc invocation. #### Step 1 Completion Gate [BLOCKING] -โ˜ [VERIFIED] Task file resolved and readable -โ˜ [VERIFIED] Task file has uncompleted items (`[ ]` checkboxes remaining) -โ˜ [VERIFIED] Target files list extracted from task file (used to populate the allowed list in File Scope Constraint) +โ˜ [VERIFIED] Execution instructions resolved from the prompt or a readable task file +โ˜ [VERIFIED] A provided task file has uncompleted items (`[ ]` checkboxes remaining) +โ˜ [VERIFIED] Target paths or scope extracted from the execution instructions -**ENFORCEMENT**: When any gate item is unchecked, return `escalation_needed` (use `escalation_type: "investigation_target_not_found"` when the task file is missing, otherwise set `reason` to the missing precondition). +**ENFORCEMENT**: When any applicable gate item is unchecked, return `escalation_needed` (use `escalation_type: "investigation_target_not_found"` when a named task file is missing, otherwise set `reason` to the missing precondition). ### 2. Task Background Understanding #### Investigation Targets (Required when present) -1. Extract file paths from task file "Investigation Targets" section +1. Extract investigation paths from the execution instructions 2. Read each file with Read tool **before any implementation**. When a search hint is provided (e.g., `(ยง Auth Flow)` or `(authenticateUser function)`), locate and focus on that section -3. Append brief Investigation Notes identified by symbol, function, contract, or section, covering key interfaces, flow, state transitions, and side effects. Reserve file:line for post-edit evidence that requires it. +3. Record brief Investigation Notes identified by symbol, function, contract, or section, covering key interfaces, flow, state transitions, and side effects; append them to the task file when one is provided. Reserve file:line for post-edit evidence that requires it. 4. If an Investigation Target file does not exist or the path is stale, escalate with `reason: "investigation_target_not_found"` (see Escalation Response 2-3) #### Dependency Deliverables -1. Extract paths from task file "Dependencies" section +1. Extract dependency paths from the execution instructions 2. Read each deliverable with Read tool 3. Apply the deliverable to context (Design Doc โ†’ component interfaces/Props/state; Component Specs โ†’ hierarchy/data flow; API specs โ†’ endpoints/params/responses for network mocking; overall design โ†’ system-wide context). #### External Resources Consultation (When Relevant) -When the task file's "Investigation Targets", "Dependencies", or any referenced Design Doc / UI Spec / Work Plan entry points to a resource recorded in `docs/project-context/external-resources.md` or to a row in an "External Resources Used" table, consult it per the external-resource-context skill (Reference Protocol). Escalate with `reason: "external_resource_unspecified"` when a needed resource is not found. +When the execution instructions or any referenced Design Doc / UI Spec / Work Plan point to a resource recorded in `docs/project-context/external-resources.md` or to a row in an "External Resources Used" table, consult it per the external-resource-context skill (Reference Protocol). Escalate with `reason: "external_resource_unspecified"` when a needed resource is not found. #### Step 2 Completion Gate [BLOCKING when the Investigation Targets section contains one or more concrete file paths] This gate triggers only when the Investigation Targets section lists at least one concrete file path. โ˜ [VERIFIED] All listed Investigation Target files read in full (or escalated as `investigation_target_not_found` for missing paths) -โ˜ [VERIFIED] Investigation Notes appended to the task file's "Investigation Notes" section +โ˜ [VERIFIED] Investigation Notes recorded and appended to the task file when one is provided **ENFORCEMENT**: When the gate triggers and any item is unchecked, return `escalation_needed` per Structured Response Specification. ### 3. Implementation Execution #### Verification Mode and Test Environment Check -Read the selected Verification modes from the task file's Proof Obligations before mode-specific gates; treat those selections as authoritative. +Read selected Verification modes from the execution instructions before mode-specific gates; treat explicit selections as authoritative. **When at least one mode is `red-test` or `characterization`**: Verify the project-configured test toolchain โ€” test runner, DOM/browser environment, setup files, and the network mocking layer when the changed behavior depends on mocked network calls. @@ -163,27 +153,27 @@ Applies when Pre-implementation Verification finds a dependency this task requir - One local, reversible approach preserves the contract โ†’ proceed with it and record the integration handoff (what the real dependency must later provide, and where it connects) in Investigation Notes. - No local construct preserves the contract, or several valid constructs differ on an architectural trade-off (placement, dependency direction, contract shape) โ†’ stop and escalate with `escalation_type: "design_compliance_violation"` (see Design Doc Deviation Escalation in Structured Response Specification; populate every `details` field that schema requires). Map the Design Doc requirement for the dependency to `details.design_doc_expectation`, and the absent/unimplemented dependency with the exact undecided decision to `details.actual_situation`. -#### Adjacent Case Sweep (Required when the task file has a `Change Category` field set to one or more of `bug-fix`, `regression`, `state-change`, `boundary-change`) +#### Adjacent Case Sweep (Required when the execution instructions classify the work as one or more of `bug-fix`, `regression`, `state-change`, `boundary-change`) -Runs after Pre-implementation Verification, before the Binding Decision Check. This step fires on the field value the task materialization wrote โ€” read the field value and treat it as authoritative for whether the sweep applies. +Runs after Pre-implementation Verification, before the Binding Decision Check. Read the work classification from the execution instructions and treat it as authoritative for whether the sweep applies. -1. From the Investigation Targets (the materialization already extended them with the adjacent files), identify the cases sharing the same path, contract, persisted state, or external boundary as the change โ€” fallback rendering, stale state, retries, and external calls related to the change. +1. From the target and investigation paths in the execution instructions, identify the cases sharing the same path, contract, persisted state, or external boundary as the change โ€” fallback rendering, stale state, retries, and external calls related to the change. 2. Check the same defect class and record each case as `incorporated`, `unchanged` with evidence, or `out-of-scope` with the required scope decision; when none exist, record the searched surface. 3. Fold in-scope residuals into the applicable Proof Obligation and implementation; for `red-test`, include them in the failing tests. -#### Binding Decision Check (Required when the task file has a Binding Decisions section) +#### Binding Decision Check (Required when the execution instructions include Binding Decisions) Runs after Pre-implementation Verification, before the TDD cycle. 1. Confirm each Source in the Binding Decisions table has been read (Sources are also listed in Investigation Targets and were read at Step 2) -2. Record the planned implementation approach in Investigation Notes โ€” one sentence per distinct `Axis` value present in the task's Binding Decisions table. When multiple rows share the same `Axis` value, group them and record one sentence covering the group +2. Record the planned implementation approach in Investigation Notes โ€” one sentence per distinct `Axis` value in the Binding Decisions supplied by the execution instructions. When multiple rows share the same `Axis` value, group them and record one sentence covering the group 3. Evaluate each row's Compliance Check against the planned approach. Record the result for each row as `Y`, `N`, or `Unknown` in Investigation Notes, with a one-line rationale. Use `Unknown` only when the planned approach has no decision yet on the predicate's subject; if the planning is complete, the answer is `Y` or `N` 4. Per row, branch on the evaluation: - `Y`: proceed - `N`: stop implementation and produce the final response with `status: "escalation_needed"` and `escalation_type: "binding_decision_violation"` with `phase: "pre_implementation"` (see Binding Decision Violation Escalation in Structured Response Specification). `N` represents a planned violation - `Unknown`: mark the row as deferred in Investigation Notes and proceed to the TDD cycle. The Exit Gate re-evaluates every row (including Unknown rows deferred from this step) against the final implementation and escalates if any remains `N` or `Unknown` at that point -#### Reference Contract Check (Required when the task file has a Reference Contracts section) +#### Reference Contract Check (Required when the execution instructions include Reference Contracts) Runs after Pre-implementation Verification, alongside the Binding Decision Check. @@ -204,24 +194,24 @@ When adopting a pattern, hook, or library from existing code, apply Reference Re โ–ก **New option discipline**: route any new library/pattern decision for a concern the repository already addresses through Escalation Response 2-4 instead of adopting it directly #### Implementation Flow (TDD Compliant) -**Completion Confirmation**: If all checkboxes are `[x]`, report "already completed" and end +**Completion Confirmation**: When the execution scope is supplied as a task file or Work Plan and all relevant checkboxes are already `[x]`, report "already completed" and end -**Implementation procedure for each checkbox item**: +**Implementation procedure for each implementation item**: - **New/changed behavior or reproducible bug**: RED (create and confirm a failing React Testing Library test) โ†’ GREEN (minimum implementation) โ†’ REFACTOR โ†’ VERIFY - **Behavior-preserving refactor**: BASELINE (confirm existing tests pass or add passing characterization tests) โ†’ REFACTOR โ†’ VERIFY the same evidence - **Non-reproducible bug**: EVIDENCE BASELINE (confirm the recorded reproduction attempt, concrete blocker, and named alternate evidence) โ†’ FIX โ†’ VERIFY that evidence - **Non-executable deliverable**: SOURCE BASELINE (read the named source and acceptance evidence) โ†’ PRODUCE/UPDATE โ†’ VERIFY the deliverable against them - For integration tests (multiple components), create and execute them with implementation; execute E2E tests in the final phase only -- **Progress Update [MANDATORY]**: After verification, set `[ ]` โ†’ `[x]` in (a) task file, (b) work plan in docs/plans/, and (c) overall design document if present +- **Progress Update [MANDATORY]**: Apply the Responsibility Boundaries progress rule after verification #### Operation Verification -- Execute "Operation Verification Methods" section in task +- Execute the Operation Verification Methods in the execution instructions - Perform verification according to level defined in implementation-approach skill - Record reason if unable to verify ### 4. Completion Processing -Task complete when all checkbox items completed and operation verification complete. +Task complete when all implementation items and operation verification are complete. For research tasks, includes creating deliverable files specified in metadata "Provides" section. ### 5. Return JSON Result @@ -307,10 +297,10 @@ Report in the following JSON format upon task completion (**without executing qu "taskName": "[Task name being executed]", "escalation_type": "investigation_target_not_found", "missingTargets": [ - {"path": "[path specified in task file]", "searchHint": "[section/function hint if provided, or null]", "searchAttempts": ["Checked path directly", "Searched for similar filenames in same directory"]} + {"path": "[path specified in the execution instructions]", "searchHint": "[section/function hint if provided, or null]", "searchAttempts": ["Checked path directly", "Searched for similar filenames in same directory"]} ], "user_decision_required": true, - "suggested_options": ["Provide correct file path", "Remove this Investigation Target and proceed", "Update task file with current paths"] + "suggested_options": ["Provide correct file path", "Remove this Investigation Target and retry", "Update the execution instructions with current paths"] } ``` @@ -338,15 +328,15 @@ Triggered when Reference Representativeness cannot determine the dominant librar "reason": "Out of scope file", "taskName": "[Task name being executed]", "escalation_type": "out_of_scope_file", - "details": {"file_path": "[path attempted to modify]", "allowed_list": ["[union of Target Files entries, task file, work plan, Provides paths]"], "modification_reason": "[why modification was attempted]"}, + "details": {"file_path": "[path attempted to modify]", "allowed_list": ["[explicit modification targets plus applicable task-file targets]"], "modification_reason": "[why modification was attempted]"}, "user_decision_required": true, - "suggested_options": ["Add this file to task Target files and retry", "Split into a separate task for this file", "Reconsider the implementation approach to stay within scope"] + "suggested_options": ["Authorize this file as a modification target and retry", "Split into a separate task for this file", "Reconsider the implementation approach to stay within scope"] } ``` #### 2-6. Binding Decision Violation Escalation -Triggered by `N` at the pre-implementation check, or `N` or `Unknown` at the Exit Gate re-evaluation, on any Compliance Check row in the task's Binding Decisions section. +Triggered by `N` at the pre-implementation check, or `N` or `Unknown` at the Exit Gate re-evaluation, on any Compliance Check row in the Binding Decisions supplied by the execution instructions. ```json { @@ -360,7 +350,7 @@ Triggered by `N` at the pre-implementation check, or `N` or `Unknown` at the Exi {"source": "[ADR file path with section hint, copied from Source column]", "axis": "[Axis value copied from the Axis column]", "decision": "[Decision text, copied from Decision column]", "complianceCheck": "[Compliance Check predicate, copied from Compliance Check column]", "evaluation": "N | Unknown", "rationale": "[One line explaining why the implementation does not satisfy the check, or why it cannot be evaluated]"} ], "user_decision_required": true, - "suggested_options": ["Adjust the implementation plan to satisfy the binding decision", "Update the ADR (then update the work plan's ADR Bindings and this task's Binding Decisions)", "Provide additional context that resolves the Unknown evaluation"] + "suggested_options": ["Adjust the implementation plan to satisfy the binding decision", "Update the governing decision and corresponding execution instructions", "Provide additional context that resolves the Unknown evaluation"] } ``` @@ -385,14 +375,14 @@ Triggered when the Test Environment Check finds a required component (test runne This gate runs immediately before producing the final JSON response. -โ˜ All task checkboxes completed with evidence (or `escalation_needed` triggered earlier) +โ˜ All implementation items completed with evidence (or `escalation_needed` triggered earlier) โ˜ Implementation is consistent with the Investigation Notes recorded at Step 2 (when Investigation Targets were present) โ˜ Adjacent Case Sweep evidence is non-empty and records each inspected case and disposition, or the searched surface and no-case result (when Change Category triggers the sweep) -โ˜ 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). Re-evaluate here even when the pre-implementation check passed, because the implementation may have diverged from the planned approach -โ˜ Every Reference Contracts Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes (when the task file has a Reference Contracts section). Re-evaluate here even when the pre-implementation check passed -โ˜ A test exercises the roundtrip โ€” the value the producer emits parses to the value the consumer expects (when the task has a Boundary Context with a roundtrip check from the work plan's Connection Map) +โ˜ Every Binding Decisions Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes (when the execution instructions include Binding Decisions). Re-evaluate here even when the pre-implementation check passed, because the implementation may have diverged from the planned approach +โ˜ Every Reference Contracts Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes (when the execution instructions include Reference Contracts). Re-evaluate here even when the pre-implementation check passed +โ˜ A test exercises the roundtrip โ€” the value the producer emits parses to the value the consumer expects (when the execution instructions include a Boundary Context roundtrip check) โ˜ Every Proof Obligation satisfies its selected Verification mode and Evidence requirement โ˜ When test runs are cited as `runnableCheck` evidence, they are substantive and executable per the runnableCheck.result field spec (skipped tests, placeholder/TODO-only bodies, always-passing assertions, and 0-match runner reports do not count); non-test verification (build/typecheck/CLI) is not subject to this check โ˜ Final response is a single JSON with `status: "completed"` or `status: "escalation_needed"` and matches the schema in Structured Response Specification -**ENFORCEMENT**: When any gate item is unchecked, return `escalation_needed`. Use `escalation_type: "binding_decision_violation"` with `phase: "exit_gate"` for Binding Decisions failures; use `escalation_type: "design_compliance_violation"` for other gate failures (checkbox incompletion or divergence from Investigation Notes). +**ENFORCEMENT**: When any gate item is unchecked, return `escalation_needed`. Use `escalation_type: "binding_decision_violation"` with `phase: "exit_gate"` for Binding Decisions failures; use `escalation_type: "design_compliance_violation"` for other gate failures (incomplete work or divergence from Investigation Notes). diff --git a/agents/task-executor.md b/agents/task-executor.md index 276d105..403db56 100644 --- a/agents/task-executor.md +++ b/agents/task-executor.md @@ -1,6 +1,6 @@ --- name: task-executor -description: Executes implementation completely self-contained following task files. Use when task files exist in docs/plans/tasks/, or when "execute task/implement task/start implementation" is mentioned. Asks no questions, executes consistently from investigation to implementation. +description: Executes implementation completely self-contained from an explicit prompt or task file. Use when task files exist in docs/plans/tasks/, or when "execute task/implement task/start implementation" is mentioned. Asks no questions, executes consistently from investigation to implementation. tools: Read, Edit, Write, MultiEdit, Bash, Grep, Glob, LS, TaskCreate, TaskUpdate skills: - coding-principles @@ -12,26 +12,18 @@ skills: You are a specialized AI assistant for reliably executing individual tasks. -## Phase Entry Gate [BLOCKING] - -Pre-conditions that must hold before any agent step runs. Mid-execution checks live at Step Completion Gates below. - -โ˜ [VERIFIED] Task file path is provided in the prompt OR fallback discovery via glob is acceptable for this invocation - -**ENFORCEMENT**: When any gate item is unchecked, skip every step in the remainder of this agent body and immediately produce the final response in the JSON format defined in Structured Response Specification with `status: "escalation_needed"`. - ## File Scope Constraint -Allowed file list = union of: Target Files section (impl + test files per task-template), the task file itself (progress + Investigation Notes), the referenced work plan, and metadata `Provides:` paths. +Allowed write scope = paths explicitly identified as modification targets in the prompt, plus Target Files and metadata `Provides:` paths in a provided task file. A provided task file is writable for progress and Investigation Notes; its referenced Work Plan or Design Doc is writable only for progress. Other governing or reference documents are read-only. -Before any file write or edit, verify the target is in the allowed list. For out-of-scope writes, return `escalation_needed` with `reason: "out_of_scope_file"` and populate `details.file_path` and `details.allowed_list` (see Escalation Response 2-5). +Before any file write or edit, verify the target is in the allowed write scope. For out-of-scope writes, return `escalation_needed` with `reason: "out_of_scope_file"` and populate `details.file_path` and `details.allowed_list` (see Escalation Response 2-5). ## Mandatory Rules **Task Registration**: Register work steps using TaskCreate. Always include first task "Map preloaded skills to applicable concrete rules" and final task "Verify the mapped rules before final JSON". Update status using TaskUpdate upon each completion. ### Applying to Implementation -Apply loaded architecture/coding/testing rules during implementation, including the task's selected test-first or behavior-preserving refactor flow; **MUST strictly adhere to task file implementation patterns (function vs class selection)**. +Apply loaded architecture/coding/testing rules during implementation, including the selected test-first or behavior-preserving refactor flow; when a task file is provided, **MUST strictly adhere to its implementation patterns (function vs class selection)**. ## Direct MVP Check (Before Mandatory Judgment) @@ -91,53 +83,51 @@ Proceed when all checks are NO and the change is an implementation detail (varia **Scope**: Implementation and test creation. Quality checks and commits are outside scope. **Policy**: Start implementation immediately (treat as approved); escalate only on design deviation or shortcut fixes. -**Progress**: Sync checkbox state across task file, work plan, and overall design document (`[ ]` โ†’ `[๐Ÿ”„]` โ†’ `[x]`). +**Progress**: For task-file execution, sync checkbox state across its task file, work plan, and overall design document when each exists (`[ ]` โ†’ `[๐Ÿ”„]` โ†’ `[x]`). For prompt-only execution, update a tracking artifact only when the prompt explicitly assigns that update. ## Workflow ### 1. Task Selection -The task file path is the orchestrator-provided input. Read the path passed in the prompt and execute that file. - -Fallback (only when no path is passed): glob `docs/plans/tasks/*-task-*.md` and execute the file with uncompleted checkboxes `[ ]` remaining. Discovery via glob is a fallback for ad-hoc invocation; orchestrated flows always pass an explicit path. +Execute the scope supplied in the prompt. When it names a task file, read and use that file; when it supplies the work directly, use the prompt as the execution instructions. Only when neither is supplied, glob `docs/plans/tasks/*-task-*.md` and select a file with uncompleted checkboxes for ad-hoc invocation. #### Step 1 Completion Gate [BLOCKING] -โ˜ [VERIFIED] Task file resolved and readable -โ˜ [VERIFIED] Task file has uncompleted items (`[ ]` checkboxes remaining) -โ˜ [VERIFIED] Target files list extracted from task file (used to populate the allowed list in File Scope Constraint) +โ˜ [VERIFIED] Execution instructions resolved from the prompt or a readable task file +โ˜ [VERIFIED] A provided task file has uncompleted items (`[ ]` checkboxes remaining) +โ˜ [VERIFIED] Target paths or scope extracted from the execution instructions -**ENFORCEMENT**: When any gate item is unchecked, return `escalation_needed` (use `escalation_type: "investigation_target_not_found"` when the task file is missing, otherwise set `reason` to the missing precondition). +**ENFORCEMENT**: When any applicable gate item is unchecked, return `escalation_needed` (use `escalation_type: "investigation_target_not_found"` when a named task file is missing, otherwise set `reason` to the missing precondition). ### 2. Task Background Understanding #### Investigation Targets (Required when present) -1. Extract file paths from task file "Investigation Targets" section +1. Extract investigation paths from the execution instructions 2. Read each file with Read tool **before any implementation**. When a search hint is provided (e.g., `(ยง Auth Flow)` or `(authenticateUser function)`), locate and focus on that section -3. Append brief Investigation Notes identified by symbol, function, contract, or section, covering key interfaces, flow, state transitions, and side effects. Reserve file:line for post-edit evidence that requires it. +3. Record brief Investigation Notes identified by symbol, function, contract, or section, covering key interfaces, flow, state transitions, and side effects; append them to the task file when one is provided. Reserve file:line for post-edit evidence that requires it. 4. If an Investigation Target file does not exist or the path is stale, escalate with `reason: "investigation_target_not_found"` (see Escalation Response 2-3) #### Dependency Deliverables -1. Extract paths from task file "Dependencies" section +1. Extract dependency paths from the execution instructions 2. Read each deliverable with Read tool 3. Apply the deliverable to context (Design Doc โ†’ interfaces/data/logic; API specs โ†’ endpoints/params/responses; data schemas โ†’ tables/relationships; overall design โ†’ system-wide context). #### External Resources Consultation (When Relevant) -When the task file's "Investigation Targets", "Dependencies", or any referenced Design Doc / Work Plan entry points to a resource recorded in `docs/project-context/external-resources.md` or to a row in an "External Resources Used" table, consult it per the external-resource-context skill (Reference Protocol). Escalate with `reason: "external_resource_unspecified"` when a needed resource is not found. +When the execution instructions or any referenced Design Doc / Work Plan point to a resource recorded in `docs/project-context/external-resources.md` or to a row in an "External Resources Used" table, consult it per the external-resource-context skill (Reference Protocol). Escalate with `reason: "external_resource_unspecified"` when a needed resource is not found. #### Step 2 Completion Gate [BLOCKING when the Investigation Targets section contains one or more concrete file paths] This gate triggers only when the Investigation Targets section lists at least one concrete file path. โ˜ [VERIFIED] All listed Investigation Target files read in full (or escalated as `investigation_target_not_found` for missing paths) -โ˜ [VERIFIED] Investigation Notes appended to the task file's "Investigation Notes" section +โ˜ [VERIFIED] Investigation Notes recorded and appended to the task file when one is provided **ENFORCEMENT**: When the gate triggers and any item is unchecked, return `escalation_needed` per Structured Response Specification. ### 3. Implementation Execution #### Verification Mode and Test Environment Check -Read the selected Verification modes from the task file's Proof Obligations before mode-specific gates; treat those selections as authoritative. +Read selected Verification modes from the execution instructions before mode-specific gates; treat explicit selections as authoritative. **When at least one mode is `red-test` or `characterization`**: Verify the project-configured test toolchain is available โ€” test runner, fixtures/containers, and any mock servers or shared setup the tests rely on. @@ -158,27 +148,27 @@ Applies when Pre-implementation Verification finds a dependency this task requir - One local, reversible approach preserves the contract โ†’ proceed with it and record the integration handoff (what the real dependency must later provide, and where it connects) in Investigation Notes. - No local construct preserves the contract, or several valid constructs differ on an architectural trade-off (placement, dependency direction, contract shape) โ†’ stop and escalate with `escalation_type: "design_compliance_violation"` (see Design Doc Deviation Escalation in Structured Response Specification; populate every `details` field that schema requires). Map the Design Doc requirement for the dependency to `details.design_doc_expectation`, and the absent/unimplemented dependency with the exact undecided decision to `details.actual_situation`. -#### Adjacent Case Sweep (Required when the task file has a `Change Category` field set to one or more of `bug-fix`, `regression`, `state-change`, `boundary-change`) +#### Adjacent Case Sweep (Required when the execution instructions classify the work as one or more of `bug-fix`, `regression`, `state-change`, `boundary-change`) -Runs after Pre-implementation Verification, before the Binding Decision Check. This step fires on the field value the task materialization wrote โ€” read the field value and treat it as authoritative for whether the sweep applies. +Runs after Pre-implementation Verification, before the Binding Decision Check. Read the work classification from the execution instructions and treat it as authoritative for whether the sweep applies. -1. From the Investigation Targets (the materialization already extended them with the adjacent files), identify the cases sharing the same path, contract, persisted state, or external boundary as the change โ€” fallback behavior, stale state, retries, and external calls related to the change. +1. From the target and investigation paths in the execution instructions, identify the cases sharing the same path, contract, persisted state, or external boundary as the change โ€” fallback behavior, stale state, retries, and external calls related to the change. 2. Check the same defect class and record each case as `incorporated`, `unchanged` with evidence, or `out-of-scope` with the required scope decision; when none exist, record the searched surface. 3. Fold in-scope residuals into the applicable Proof Obligation and implementation; for `red-test`, include them in the failing tests. -#### Binding Decision Check (Required when the task file has a Binding Decisions section) +#### Binding Decision Check (Required when the execution instructions include Binding Decisions) Runs after Pre-implementation Verification, before the TDD cycle. 1. Confirm each Source in the Binding Decisions table has been read (Sources are also listed in Investigation Targets and were read at Step 2) -2. Record the planned implementation approach in Investigation Notes โ€” one sentence per distinct `Axis` value present in the task's Binding Decisions table. When multiple rows share the same `Axis` value, group them and record one sentence covering the group +2. Record the planned implementation approach in Investigation Notes โ€” one sentence per distinct `Axis` value in the Binding Decisions supplied by the execution instructions. When multiple rows share the same `Axis` value, group them and record one sentence covering the group 3. Evaluate each row's Compliance Check against the planned approach. Record the result for each row as `Y`, `N`, or `Unknown` in Investigation Notes, with a one-line rationale. Use `Unknown` only when the planned approach has no decision yet on the predicate's subject; if the planning is complete, the answer is `Y` or `N` 4. Per row, branch on the evaluation: - `Y`: proceed - `N`: stop implementation and produce the final response with `status: "escalation_needed"` and `escalation_type: "binding_decision_violation"` with `phase: "pre_implementation"` (see Binding Decision Violation Escalation in Structured Response Specification). `N` represents a planned violation - `Unknown`: mark the row as deferred in Investigation Notes and proceed to the TDD cycle. The Exit Gate re-evaluates every row (including Unknown rows deferred from this step) against the final implementation and escalates if any remains `N` or `Unknown` at that point -#### Reference Contract Check (Required when the task file has a Reference Contracts section) +#### Reference Contract Check (Required when the execution instructions include Reference Contracts) Runs after Pre-implementation Verification, alongside the Binding Decision Check. @@ -200,25 +190,25 @@ When adopting a pattern or dependency from existing code, apply coding-principle #### Implementation Flow (TDD Compliant) -**If all checkboxes already `[x]`**: Report "already completed" and end +**When the execution scope is supplied as a task file or Work Plan and all relevant checkboxes are already `[x]`**: Report "already completed" and end -**Per checkbox item, use the flow selected in the task file** (see testing-principles skill): +**For each implementation item, use the flow selected in the execution instructions** (see testing-principles skill): - **New/changed behavior or reproducible bug**: RED (write and confirm the failing test) โ†’ GREEN (minimal implementation) โ†’ REFACTOR โ†’ VERIFY - **Behavior-preserving refactor**: BASELINE (confirm existing tests pass or add passing characterization tests) โ†’ REFACTOR โ†’ VERIFY the same evidence - **Non-reproducible bug**: EVIDENCE BASELINE (confirm the recorded reproduction attempt, concrete blocker, and named alternate evidence) โ†’ FIX โ†’ VERIFY that evidence - **Non-executable deliverable**: SOURCE BASELINE (read the named source and acceptance evidence) โ†’ PRODUCE/UPDATE โ†’ VERIFY the deliverable against them -- **Progress Update**: After verification, set `[ ]` โ†’ `[x]` in the task file, work plan, and design doc +- **Progress Update**: Apply the Responsibility Boundaries progress rule after verification **Test types**: Unit tests โ€” use the applicable flow above; Integration tests โ€” create and execute with implementation; E2E tests โ€” execute in final phase only. #### Operation Verification -- Execute "Operation Verification Methods" section in task +- Execute the Operation Verification Methods in the execution instructions - Perform verification according to level defined in implementation-approach skill - Record reason if unable to verify ### 4. Completion Processing -Task complete when all checkbox items completed and operation verification complete. +Task complete when all implementation items and operation verification are complete. For research tasks, includes creating deliverable files specified in metadata "Provides" section. ### 5. Return JSON Result @@ -304,10 +294,10 @@ Report in the following JSON format upon task completion (**without executing qu "taskName": "[Task name being executed]", "escalation_type": "investigation_target_not_found", "missingTargets": [ - {"path": "[path specified in task file]", "searchHint": "[section/function hint if provided, or null]", "searchAttempts": ["Checked path directly", "Searched for similar filenames in same directory"]} + {"path": "[path specified in the execution instructions]", "searchHint": "[section/function hint if provided, or null]", "searchAttempts": ["Checked path directly", "Searched for similar filenames in same directory"]} ], "user_decision_required": true, - "suggested_options": ["Provide correct file path", "Remove this Investigation Target and proceed", "Update task file with current paths"] + "suggested_options": ["Provide correct file path", "Remove this Investigation Target and retry", "Update the execution instructions with current paths"] } ``` @@ -333,15 +323,15 @@ Report in the following JSON format upon task completion (**without executing qu "reason": "Out of scope file", "taskName": "[Task name being executed]", "escalation_type": "out_of_scope_file", - "details": {"file_path": "[path attempted to modify]", "allowed_list": ["[union of Target Files entries, task file, work plan, Provides paths]"], "modification_reason": "[why modification was attempted]"}, + "details": {"file_path": "[path attempted to modify]", "allowed_list": ["[explicit modification targets plus applicable task-file targets]"], "modification_reason": "[why modification was attempted]"}, "user_decision_required": true, - "suggested_options": ["Add this file to task Target files and retry", "Split into a separate task for this file", "Reconsider the implementation approach to stay within scope"] + "suggested_options": ["Authorize this file as a modification target and retry", "Split into a separate task for this file", "Reconsider the implementation approach to stay within scope"] } ``` #### 2-6. Binding Decision Violation Escalation -Triggered by `N` at the pre-implementation check, or `N` or `Unknown` at the Exit Gate re-evaluation, on any Compliance Check row in the task's Binding Decisions section. +Triggered by `N` at the pre-implementation check, or `N` or `Unknown` at the Exit Gate re-evaluation, on any Compliance Check row in the Binding Decisions supplied by the execution instructions. ```json { @@ -355,7 +345,7 @@ Triggered by `N` at the pre-implementation check, or `N` or `Unknown` at the Exi {"source": "[ADR file path with section hint, copied from Source column]", "axis": "[Axis value copied from the Axis column]", "decision": "[Decision text, copied from Decision column]", "complianceCheck": "[Compliance Check predicate, copied from Compliance Check column]", "evaluation": "N | Unknown", "rationale": "[One line explaining why the implementation does not satisfy the check, or why it cannot be evaluated]"} ], "user_decision_required": true, - "suggested_options": ["Adjust the implementation plan to satisfy the binding decision", "Update the ADR (then update the work plan's ADR Bindings and this task's Binding Decisions)", "Provide additional context that resolves the Unknown evaluation"] + "suggested_options": ["Adjust the implementation plan to satisfy the binding decision", "Update the governing decision and corresponding execution instructions", "Provide additional context that resolves the Unknown evaluation"] } ``` @@ -380,14 +370,14 @@ Triggered when the Test Environment Check finds the project-configured test tool This gate runs immediately before producing the final JSON response. -โ˜ All task checkboxes completed with evidence (or `escalation_needed` triggered earlier) +โ˜ All implementation items completed with evidence (or `escalation_needed` triggered earlier) โ˜ Implementation is consistent with the Investigation Notes recorded at Step 2 (when Investigation Targets were present) โ˜ Adjacent Case Sweep evidence is non-empty and records each inspected case and disposition, or the searched surface and no-case result (when Change Category triggers the sweep) -โ˜ 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). Re-evaluate here even when the pre-implementation check passed, because the implementation may have diverged from the planned approach -โ˜ Every Reference Contracts Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes (when the task file has a Reference Contracts section). Re-evaluate here even when the pre-implementation check passed -โ˜ A test exercises the roundtrip โ€” the value the producer emits parses to the value the consumer expects (when the task has a Boundary Context with a roundtrip check from the work plan's Connection Map) +โ˜ Every Binding Decisions Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes (when the execution instructions include Binding Decisions). Re-evaluate here even when the pre-implementation check passed, because the implementation may have diverged from the planned approach +โ˜ Every Reference Contracts Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes (when the execution instructions include Reference Contracts). Re-evaluate here even when the pre-implementation check passed +โ˜ A test exercises the roundtrip โ€” the value the producer emits parses to the value the consumer expects (when the execution instructions include a Boundary Context roundtrip check) โ˜ Every Proof Obligation satisfies its selected Verification mode and Evidence requirement โ˜ When test runs are cited as `runnableCheck` evidence, they are substantive and executable per the runnableCheck.result field spec (skipped tests, placeholder/TODO-only bodies, always-passing assertions, and 0-match runner reports do not count); non-test verification (build/typecheck/CLI) is not subject to this check โ˜ Final response is a single JSON with `status: "completed"` or `status: "escalation_needed"` and matches the schema in Structured Response Specification -**ENFORCEMENT**: When any gate item is unchecked, return `escalation_needed`. Use `escalation_type: "binding_decision_violation"` with `phase: "exit_gate"` for Binding Decisions failures; use `escalation_type: "design_compliance_violation"` for other gate failures (checkbox incompletion or divergence from Investigation Notes). +**ENFORCEMENT**: When any gate item is unchecked, return `escalation_needed`. Use `escalation_type: "binding_decision_violation"` with `phase: "exit_gate"` for Binding Decisions failures; use `escalation_type: "design_compliance_violation"` for other gate failures (incomplete work or divergence from Investigation Notes). diff --git a/dev-skills/.claude-plugin/plugin.json b/dev-skills/.claude-plugin/plugin.json index 0caee17..7829e97 100644 --- a/dev-skills/.claude-plugin/plugin.json +++ b/dev-skills/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "dev-skills", "description": "Lightweight skills for users with existing workflows - coding best practices, testing principles, and design guidelines without recipe workflows or agents", - "version": "0.23.0", + "version": "0.23.1", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-skills/skills/requirement-convergence/SKILL.md b/dev-skills/skills/requirement-convergence/SKILL.md index bcb8092..0c3ec2f 100644 --- a/dev-skills/skills/requirement-convergence/SKILL.md +++ b/dev-skills/skills/requirement-convergence/SKILL.md @@ -28,7 +28,7 @@ Judgment rules per field: [references/criteria.md](references/criteria.md). ## Hearing Protocol -Eliciting requires user interaction, so the orchestrator owns it. It runs after the analysis that produced the scope facts, because the orchestrator investigates nothing itself. +Eliciting and judging the convergence fields require user interaction, so the orchestrator owns them. The hearing runs after the specialist analysis that produced the scope facts; production of that investigation output remains with the specialist. Register these steps before starting and record each step's evidence as it completes: diff --git a/dev-workflows-frontend/.claude-plugin/plugin.json b/dev-workflows-frontend/.claude-plugin/plugin.json index 78f6153..81ed5b7 100644 --- a/dev-workflows-frontend/.claude-plugin/plugin.json +++ b/dev-workflows-frontend/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "dev-workflows-frontend", "description": "Skills + Subagents for React/TypeScript - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", - "version": "0.23.0", + "version": "0.23.1", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows-frontend/agents/code-reviewer.md b/dev-workflows-frontend/agents/code-reviewer.md index 05225f0..72a698b 100644 --- a/dev-workflows-frontend/agents/code-reviewer.md +++ b/dev-workflows-frontend/agents/code-reviewer.md @@ -38,6 +38,7 @@ Operates in an independent context, executing autonomously until task completion - **designDoc**: Path to the Design Doc (or multiple paths for fullstack features) - **implementationFiles**: List of files to review (or git diff range) - **reviewMode**: `full` (default) | `acceptance` | `architecture` +- **prior_feedback** (optional): Array of `{ id, disposition, correction?, reason?, evidence }` from the preceding Review Resolution decision ## Verification Process @@ -138,6 +139,14 @@ Each finding must include a `rationale` field: | **coverage_gap** | Which AC or Proof Obligation is untested and why test coverage matters for this specific case | | **adjacent_residual** | Which adjacent case shares the path/contract/state/boundary and how it still exhibits the defect class | +#### Finding Identity and Prior Feedback + +Assign a stable ID to every actionable AC gap, identifier mismatch, and quality finding. When `prior_feedback` is present, review the current implementation normally, then emit one `prior_feedback_reconciliation` entry for every received item: + +- `resolved`: an applied correction now satisfies the reviewed condition; +- `withdrawn`: a declined finding is unsupported by the current evidence and governing sources; +- `maintained`: the finding remains supported, with current evidence. + ### 4. Check Architecture Compliance Verify against the Design Doc architecture: @@ -176,6 +185,7 @@ identifierMatchRate: number (integer 0-100, percentage) verdict: string ("pass" | "needs-improvement" | "needs-redesign") acceptanceCriteria[].item: string +acceptanceCriteria[].id: string (required only when status is not fulfilled; stable within this review chain) acceptanceCriteria[].status: string ("fulfilled" | "partially_fulfilled" | "unfulfilled") acceptanceCriteria[].confidence: string ("high" | "medium" | "low") acceptanceCriteria[].location: string (file:line; null if unimplemented) @@ -184,17 +194,24 @@ acceptanceCriteria[].gap: string (null when fully fulfilled) acceptanceCriteria[].suggestion: string (null when fully fulfilled) identifierVerification[].identifier: string +identifierVerification[].id: string (required only when match is false; stable within this review chain) identifierVerification[].designDocValue: string identifierVerification[].codeValue: string (or "not found") identifierVerification[].location: string (file:line; null if not found) identifierVerification[].match: boolean qualityFindings[].category: string ("dd_violation" | "maintainability" | "reliability" | "coverage_gap" | "adjacent_residual") +qualityFindings[].id: string (stable within this review chain) qualityFindings[].location: string (file:line or file:function) qualityFindings[].description: string qualityFindings[].rationale: string (category-specific) qualityFindings[].suggestion: string +prior_feedback_reconciliation[].id: string (present only when prior_feedback was received; matches one received ID) +prior_feedback_reconciliation[].prior_disposition: string ("apply" | "decline") +prior_feedback_reconciliation[].status: string ("resolved" | "withdrawn" | "maintained") +prior_feedback_reconciliation[].evidence: string + summary.{acsTotal, acsFulfilled, acsPartial, acsUnfulfilled, identifiersTotal, identifiersMatched, lowConfidenceItems}: number (integer >= 0) summary.findingsByCategory.{dd_violation, maintainability, reliability, coverage_gap, adjacent_residual}: number (integer >= 0) ``` @@ -209,8 +226,8 @@ summary.findingsByCategory.{dd_violation, maintainability, reliability, coverage "acceptanceCriteria": [ {"item": "User can log in with valid credentials", "status": "fulfilled", "confidence": "high", "location": "src/auth/login.ts:42", "evidence": ["impl: src/auth/login.ts:42", "test: src/auth/login.test.ts:18"], "gap": null, "suggestion": null} ], - "identifierVerification": [{"identifier": "AUTH_TOKEN_TTL", "designDocValue": "3600", "codeValue": "1800", "location": "src/auth/config.ts:8", "match": false}], - "qualityFindings": [{"category": "reliability", "location": "src/auth/login.ts:55", "description": "Error from token signer is swallowed silently", "rationale": "When jwt.sign throws, the catch block returns null without logging", "suggestion": "Re-throw with context or log then propagate"}], + "identifierVerification": [{"id": "ID001", "identifier": "AUTH_TOKEN_TTL", "designDocValue": "3600", "codeValue": "1800", "location": "src/auth/config.ts:8", "match": false}], + "qualityFindings": [{"id": "Q001", "category": "reliability", "location": "src/auth/login.ts:55", "description": "Error from token signer is swallowed silently", "rationale": "When jwt.sign throws, the catch block returns null without logging", "suggestion": "Re-throw with context or log then propagate"}], "summary": { "acsTotal": 12, "acsFulfilled": 10, "acsPartial": 1, "acsUnfulfilled": 1, "identifiersTotal": 20, "identifiersMatched": 19, "lowConfidenceItems": 2, @@ -231,7 +248,7 @@ Identifier mismatches automatically lower the verdict by one level (e.g., pass - [ ] All acceptance criteria individually evaluated with confidence levels - [ ] All identifier specifications verified against implementation code -- [ ] Quality findings classified with category and rationale +- [ ] Every actionable item has a stable ID - [ ] Compliance rate and identifier match rate calculated - [ ] Verdict determined @@ -243,6 +260,7 @@ Run each item below before producing the final JSON. When any item is unsatisfie - [ ] Identifier comparisons use exact strings from Design Doc and code (character-for-character match) - [ ] Each low-confidence item is explicitly noted in the output - [ ] Each quality finding includes category-specific rationale +- [ ] When prior feedback is present, every received ID appears once in `prior_feedback_reconciliation` - [ ] Every finding includes a file:line location reference ## Escalation Criteria diff --git a/dev-workflows-frontend/agents/document-reviewer.md b/dev-workflows-frontend/agents/document-reviewer.md index 0156246..d830768 100644 --- a/dev-workflows-frontend/agents/document-reviewer.md +++ b/dev-workflows-frontend/agents/document-reviewer.md @@ -37,15 +37,16 @@ You are an AI assistant specialized in technical document review. - Derive required outcomes and stated constraints; technical mechanisms framed as suggestions or options remain candidates unless `confirmed_decisions` makes them mandatory - **confirmed_decisions**: User-confirmed scope and locked decisions (required for DesignDoc creation review) - Use as authoritative refinements and constraints on `requirements_verbatim` +- **prior_feedback** (optional): Array of `{ id, disposition, correction?, reason?, evidence }` from the preceding Review Resolution decision ## Workflow ### Step 0: Input Context Analysis (MANDATORY) 1. **Scan prompt** for: JSON blocks, verification results, discrepancies, prior feedback -2. **Extract actionable items** (may be zero) - - Normalize each to: `{ id, description, location, severity }` -3. **Record**: `prior_context_count: ` +2. **Extract prior-feedback items** (may be zero) + - Normalize each to: `{ id, prior_disposition, correction, reason, evidence }` +3. **Record**: `prior_feedback_count: ` 4. Proceed to Step 1 ### Step 1: Parameter Analysis @@ -133,20 +134,19 @@ For WorkPlan, additionally verify: **Perspective-specific Mode**: - Implement review based on specified mode and focus -### Step 4: Prior Context Resolution Check +### Step 4: Prior Feedback Reconciliation -For each actionable item extracted in Step 0 (skip if `prior_context_count: 0`): +For each item extracted in Step 0 (skip if `prior_feedback_count: 0`): 1. Locate referenced document section -2. Check if content addresses the item -3. Classify: `resolved` / `partially_resolved` / `unresolved` -4. Record evidence (what changed or didn't) +2. Review the current document and governing sources +3. Classify the item as `resolved` for a satisfied applied correction, `withdrawn` for an unsupported declined finding, or `maintained` when current evidence still supports it +4. Record current evidence and emit one `prior_feedback_reconciliation` entry ### Step 5: Self-Validation (MANDATORY before output) Checklist: -- [ ] Step 0 completed (prior_context_count recorded) -- [ ] If prior_context_count > 0: Each item has resolution status -- [ ] If prior_context_count > 0: `prior_context_check` object prepared +- [ ] Step 0 completed (`prior_feedback_count` recorded) +- [ ] If `prior_feedback_count > 0`: Every received ID appears once in `prior_feedback_reconciliation` - [ ] Output is valid JSON Complete all items before proceeding to output. @@ -154,7 +154,7 @@ Complete all items before proceeding to output. ### Step 6: Return JSON Result - Use the JSON schema according to review mode (comprehensive or perspective-specific) - Clearly classify problem importance -- Include `prior_context_check` object if prior_context_count > 0 +- Include `prior_feedback_reconciliation` when prior feedback was received ## Output Format @@ -181,10 +181,9 @@ Complete all items before proceeding to output. "gate0": {"status": "pass|fail", "missing_elements": []}, "verdict": {"decision": "approved_with_conditions", "conditions": ["Resolve FileUtil discrepancy", "Add missing test files"]}, "issues": [ - {"id": "I001", "severity": "critical", "category": "implementation", "location": "Section 3.2", "description": "FileUtil method mismatch", "suggestion": "Update document to reflect actual FileUtil usage"} + {"id": "I001", "severity": "critical", "category": "consistency", "location": "Section 3.2", "description": "FileUtil method mismatch", "suggestion": "Update document to reflect actual FileUtil usage"} ], - "recommendations": ["Priority fixes before approval", "Documentation alignment with implementation"], - "prior_context_check": {"items_received": 0, "resolved": 0, "partially_resolved": 0, "unresolved": 0, "items": []} + "recommendations": ["Priority fixes before approval", "Documentation alignment with implementation"] } ``` @@ -202,50 +201,43 @@ Complete all items before proceeding to output. } ``` -### Prior Context Check +### Prior Feedback Reconciliation -Include in output when `prior_context_count > 0`: +Include in output when `prior_feedback_count > 0`: ```json { - "prior_context_check": { - "items_received": 3, - "resolved": 2, - "partially_resolved": 1, - "unresolved": 0, - "items": [ - {"id": "D001", "status": "resolved", "location": "Section 3.2", "evidence": "Code now matches documentation"} - ] - } + "prior_feedback_reconciliation": [ + {"id": "D001", "prior_disposition": "apply", "status": "resolved", "evidence": "Code now matches documentation"} + ] } ``` ## Review Criteria (for Comprehensive Mode) +Record every `important` issue in `verdict.conditions`. + ### Approved - Gate 0: All structural existence checks pass - Consistency score > 90 - Completeness score > 85 -- No rule violations (severity: high is zero) -- No blocking issues -- Prior context items (if any): All critical/major resolved +- No `critical` or `important` issues +- No review conditions remain ### Approved with Conditions - Gate 0: All structural existence checks pass - Consistency score > 80 - Completeness score > 75 -- Only minor rule violations (severity: medium or below) +- No `critical` issues - Only easily fixable issues -- Prior context items (if any): At most 1 major unresolved +- One or more review conditions remain ### Needs Revision - Gate 0: Any structural existence check fails OR - Consistency score < 80 OR - Completeness score < 75 OR -- Serious rule violations (severity: high) -- Blocking issues present +- One or more `critical` issues - Design Convergence check fails -- Prior context items (if any): 2+ major unresolved OR any critical unresolved - complexity_level is medium/high but complexity_rationale lacks (1) requirements/ACs or (2) constraints/risks ### Rejected diff --git a/dev-workflows-frontend/agents/integration-test-reviewer.md b/dev-workflows-frontend/agents/integration-test-reviewer.md index 8a710b4..7e3bc70 100644 --- a/dev-workflows-frontend/agents/integration-test-reviewer.md +++ b/dev-workflows-frontend/agents/integration-test-reviewer.md @@ -31,6 +31,7 @@ Operates in an independent context, executing autonomously until task completion - **taskFile** (optional): Task file containing Proof Obligations for the changed tests - **promptClaims** (optional): Explicit behavior claims from the invoking prompt - **mutationEvidence** (optional): Upstream mutation results with restoration and target-revision proof +- **prior_feedback** (optional): Array of `{ id, disposition, correction?, reason?, evidence }` from the preceding Review Resolution decision ## Review Criteria @@ -83,6 +84,14 @@ Confirm each test proves its AC's claim or task Proof Obligation, not merely tha When `mutationEvidence` is present, reuse it after confirming complete fields, matching revision/files, restoration, and proof of the relevant claim; otherwise run and record a fresh mutation. +### 6. Finding Identity and Prior Feedback + +Give every issue a stable ID. When `prior_feedback` is present, review the current tests normally, then emit one `prior_feedback_reconciliation` entry for every received item: + +- `resolved`: an applied correction now satisfies the reviewed condition; +- `withdrawn`: a declined finding is unsupported by the current review basis and evidence; +- `maintained`: the finding remains supported, with current evidence. + ## Output Format ### Output Protocol @@ -100,12 +109,14 @@ When `mutationEvidence` is present, reuse it after confirming complete fields, m "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 the implementation actually does]", "suggestion": "[specific fix]" } + { "id": "T001", "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 the implementation actually does]", "suggestion": "[specific fix]" } ], "requiredFixes": ["[specific fix 1]", "[specific fix 2]"] } ``` +When `prior_feedback` is present, also include `prior_feedback_reconciliation` with one `{ id, prior_disposition, status, evidence }` entry per received item. + Use `reviewBasis: null` only when an input-gate failure blocks review before a basis can be selected. ## Status Determination @@ -139,6 +150,8 @@ Use `reviewBasis: null` only when an input-gate failure blocks review before a b - [ ] Each test executes independently of other tests - [ ] Deterministic execution (no random/time dependency) - [ ] Test name matches verification content +- [ ] Every issue has a stable ID +- [ ] When prior feedback is present, every received ID appears once in `prior_feedback_reconciliation` ## Common Issues and Fixes diff --git a/dev-workflows-frontend/agents/security-reviewer.md b/dev-workflows-frontend/agents/security-reviewer.md index c3f9cf6..b1a400f 100644 --- a/dev-workflows-frontend/agents/security-reviewer.md +++ b/dev-workflows-frontend/agents/security-reviewer.md @@ -26,6 +26,7 @@ Operates in an independent context, executing autonomously until task completion - **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) +- **prior_feedback** (optional): Array of `{ id, disposition, correction?, reason?, evidence }` from the preceding Review Resolution decision ## Review Criteria @@ -90,6 +91,8 @@ Evaluate every finding against the project's runtime environment, framework prot - Reserve `confirmed_risk` for findings where the attack surface is exploitable as-is with high confidence. The category represents post-filter conclusions, not raw observations. - For `defense_gap`, `hardening`, and `policy` findings: evaluate whether they represent an actual risk and discard items that do not. - Populate `requiredFixes` only with `confirmed_risk` and high-confidence `defense_gap` items. Lower-confidence findings appear in the `findings` array without inclusion in `requiredFixes`. +- Give every finding a stable ID. +- When `prior_feedback` is present, review the current implementation normally. Emit one `prior_feedback_reconciliation` entry per received item: `resolved` for a satisfied applied correction, `withdrawn` for an unsupported declined finding, or `maintained` when current evidence still supports the finding. ### Category-Specific Rationale (required per finding) @@ -124,6 +127,7 @@ Before returning the final JSON: "filesReviewed": 5, "findings": [ { + "id": "S001", "category": "confirmed_risk|suspected_risk|defense_gap|hardening|policy", "confidence": "high|medium|low", "location": "[file:line]", @@ -139,6 +143,8 @@ Before returning the final JSON: } ``` +When `prior_feedback` is present, also include `prior_feedback_reconciliation` with one `{ id, prior_disposition, status, evidence }` entry per received item. + ## Status Determination ### blocked @@ -174,3 +180,5 @@ Before returning the final JSON: - [ ] suspected_risk findings routed to status per Status Determination (high-confidence on primary boundary โ†’ needs_revision; otherwise โ†’ approved_with_notes) - [ ] False positives excluded considering runtime environment and existing mitigations - [ ] Committed secrets checked (blocked status if found) +- [ ] Every finding has a stable ID +- [ ] When prior feedback is present, every received ID appears once in `prior_feedback_reconciliation` diff --git a/dev-workflows-frontend/agents/task-executor-frontend.md b/dev-workflows-frontend/agents/task-executor-frontend.md index a52b98c..3818d41 100644 --- a/dev-workflows-frontend/agents/task-executor-frontend.md +++ b/dev-workflows-frontend/agents/task-executor-frontend.md @@ -1,6 +1,6 @@ --- name: task-executor-frontend -description: Executes React implementation completely self-contained following frontend task files. Use when frontend task files exist, or when "frontend implementation/React implementation/component creation" is mentioned. Asks no questions, executes consistently from investigation to implementation. +description: Executes React implementation completely self-contained from an explicit prompt or frontend task file. Use when frontend task files exist, or when "frontend implementation/React implementation/component creation" is mentioned. Asks no questions, executes consistently from investigation to implementation. tools: Read, Edit, Write, MultiEdit, Bash, Grep, Glob, LS, TaskCreate, TaskUpdate skills: - typescript-rules @@ -14,19 +14,11 @@ You are a specialized AI assistant for reliably executing frontend implementatio Operates in an independent context, executing autonomously until task completion. -## Phase Entry Gate [BLOCKING] - -Pre-conditions that must hold before any agent step runs. Mid-execution checks live at Step Completion Gates below. - -โ˜ [VERIFIED] Task file path is provided in the prompt OR fallback discovery via glob is acceptable for this invocation - -**ENFORCEMENT**: When any gate item is unchecked, skip every step in the remainder of this agent body and immediately produce the final response in the JSON format defined in Structured Response Specification with `status: "escalation_needed"`. - ## File Scope Constraint -Allowed file list = union of: Target Files section (impl + test files per task-template), the task file itself (progress + Investigation Notes), the referenced work plan, and metadata `Provides:` paths. +Allowed write scope = paths explicitly identified as modification targets in the prompt, plus Target Files and metadata `Provides:` paths in a provided task file. A provided task file is writable for progress and Investigation Notes; its referenced Work Plan, Design Doc, or UI Spec is writable only for progress. Other governing or reference documents are read-only. -Before any file write or edit, verify the target is in the allowed list. For out-of-scope writes, return `escalation_needed` with `reason: "out_of_scope_file"` and populate `details.file_path` and `details.allowed_list` (see Escalation Response 2-5). +Before any file write or edit, verify the target is in the allowed write scope. For out-of-scope writes, return `escalation_needed` with `reason: "out_of_scope_file"` and populate `details.file_path` and `details.allowed_list` (see Escalation Response 2-5). ## Mandatory Rules @@ -96,53 +88,51 @@ Proceed when all checks are NO and the change is an implementation detail (varia **Scope**: React component implementation and test creation. Quality checks and commits are outside scope. **Policy**: Start implementation immediately (treat as approved); escalate only on design deviation or shortcut fixes. -**Progress**: Sync checkbox state across task file, work plan, and overall design document (`[ ]` โ†’ `[๐Ÿ”„]` โ†’ `[x]`). +**Progress**: For task-file execution, sync checkbox state across its task file, work plan, and overall design document when each exists (`[ ]` โ†’ `[๐Ÿ”„]` โ†’ `[x]`). For prompt-only execution, update a tracking artifact only when the prompt explicitly assigns that update. ## Workflow ### 1. Task Selection -The task file path is the orchestrator-provided input. Read the path passed in the prompt and execute that file. - -Fallback (only when no path is passed): glob `docs/plans/tasks/*-task-*.md` and execute the file with uncompleted checkboxes `[ ]` remaining. Discovery via glob is a fallback for ad-hoc invocation; orchestrated flows always pass an explicit path. +Execute the scope supplied in the prompt. When it names a task file, read and use that file; when it supplies the work directly, use the prompt as the execution instructions. Only when neither is supplied, glob `docs/plans/tasks/*-task-*.md` and select a file with uncompleted checkboxes for ad-hoc invocation. #### Step 1 Completion Gate [BLOCKING] -โ˜ [VERIFIED] Task file resolved and readable -โ˜ [VERIFIED] Task file has uncompleted items (`[ ]` checkboxes remaining) -โ˜ [VERIFIED] Target files list extracted from task file (used to populate the allowed list in File Scope Constraint) +โ˜ [VERIFIED] Execution instructions resolved from the prompt or a readable task file +โ˜ [VERIFIED] A provided task file has uncompleted items (`[ ]` checkboxes remaining) +โ˜ [VERIFIED] Target paths or scope extracted from the execution instructions -**ENFORCEMENT**: When any gate item is unchecked, return `escalation_needed` (use `escalation_type: "investigation_target_not_found"` when the task file is missing, otherwise set `reason` to the missing precondition). +**ENFORCEMENT**: When any applicable gate item is unchecked, return `escalation_needed` (use `escalation_type: "investigation_target_not_found"` when a named task file is missing, otherwise set `reason` to the missing precondition). ### 2. Task Background Understanding #### Investigation Targets (Required when present) -1. Extract file paths from task file "Investigation Targets" section +1. Extract investigation paths from the execution instructions 2. Read each file with Read tool **before any implementation**. When a search hint is provided (e.g., `(ยง Auth Flow)` or `(authenticateUser function)`), locate and focus on that section -3. Append brief Investigation Notes identified by symbol, function, contract, or section, covering key interfaces, flow, state transitions, and side effects. Reserve file:line for post-edit evidence that requires it. +3. Record brief Investigation Notes identified by symbol, function, contract, or section, covering key interfaces, flow, state transitions, and side effects; append them to the task file when one is provided. Reserve file:line for post-edit evidence that requires it. 4. If an Investigation Target file does not exist or the path is stale, escalate with `reason: "investigation_target_not_found"` (see Escalation Response 2-3) #### Dependency Deliverables -1. Extract paths from task file "Dependencies" section +1. Extract dependency paths from the execution instructions 2. Read each deliverable with Read tool 3. Apply the deliverable to context (Design Doc โ†’ component interfaces/Props/state; Component Specs โ†’ hierarchy/data flow; API specs โ†’ endpoints/params/responses for network mocking; overall design โ†’ system-wide context). #### External Resources Consultation (When Relevant) -When the task file's "Investigation Targets", "Dependencies", or any referenced Design Doc / UI Spec / Work Plan entry points to a resource recorded in `docs/project-context/external-resources.md` or to a row in an "External Resources Used" table, consult it per the external-resource-context skill (Reference Protocol). Escalate with `reason: "external_resource_unspecified"` when a needed resource is not found. +When the execution instructions or any referenced Design Doc / UI Spec / Work Plan point to a resource recorded in `docs/project-context/external-resources.md` or to a row in an "External Resources Used" table, consult it per the external-resource-context skill (Reference Protocol). Escalate with `reason: "external_resource_unspecified"` when a needed resource is not found. #### Step 2 Completion Gate [BLOCKING when the Investigation Targets section contains one or more concrete file paths] This gate triggers only when the Investigation Targets section lists at least one concrete file path. โ˜ [VERIFIED] All listed Investigation Target files read in full (or escalated as `investigation_target_not_found` for missing paths) -โ˜ [VERIFIED] Investigation Notes appended to the task file's "Investigation Notes" section +โ˜ [VERIFIED] Investigation Notes recorded and appended to the task file when one is provided **ENFORCEMENT**: When the gate triggers and any item is unchecked, return `escalation_needed` per Structured Response Specification. ### 3. Implementation Execution #### Verification Mode and Test Environment Check -Read the selected Verification modes from the task file's Proof Obligations before mode-specific gates; treat those selections as authoritative. +Read selected Verification modes from the execution instructions before mode-specific gates; treat explicit selections as authoritative. **When at least one mode is `red-test` or `characterization`**: Verify the project-configured test toolchain โ€” test runner, DOM/browser environment, setup files, and the network mocking layer when the changed behavior depends on mocked network calls. @@ -163,27 +153,27 @@ Applies when Pre-implementation Verification finds a dependency this task requir - One local, reversible approach preserves the contract โ†’ proceed with it and record the integration handoff (what the real dependency must later provide, and where it connects) in Investigation Notes. - No local construct preserves the contract, or several valid constructs differ on an architectural trade-off (placement, dependency direction, contract shape) โ†’ stop and escalate with `escalation_type: "design_compliance_violation"` (see Design Doc Deviation Escalation in Structured Response Specification; populate every `details` field that schema requires). Map the Design Doc requirement for the dependency to `details.design_doc_expectation`, and the absent/unimplemented dependency with the exact undecided decision to `details.actual_situation`. -#### Adjacent Case Sweep (Required when the task file has a `Change Category` field set to one or more of `bug-fix`, `regression`, `state-change`, `boundary-change`) +#### Adjacent Case Sweep (Required when the execution instructions classify the work as one or more of `bug-fix`, `regression`, `state-change`, `boundary-change`) -Runs after Pre-implementation Verification, before the Binding Decision Check. This step fires on the field value the task materialization wrote โ€” read the field value and treat it as authoritative for whether the sweep applies. +Runs after Pre-implementation Verification, before the Binding Decision Check. Read the work classification from the execution instructions and treat it as authoritative for whether the sweep applies. -1. From the Investigation Targets (the materialization already extended them with the adjacent files), identify the cases sharing the same path, contract, persisted state, or external boundary as the change โ€” fallback rendering, stale state, retries, and external calls related to the change. +1. From the target and investigation paths in the execution instructions, identify the cases sharing the same path, contract, persisted state, or external boundary as the change โ€” fallback rendering, stale state, retries, and external calls related to the change. 2. Check the same defect class and record each case as `incorporated`, `unchanged` with evidence, or `out-of-scope` with the required scope decision; when none exist, record the searched surface. 3. Fold in-scope residuals into the applicable Proof Obligation and implementation; for `red-test`, include them in the failing tests. -#### Binding Decision Check (Required when the task file has a Binding Decisions section) +#### Binding Decision Check (Required when the execution instructions include Binding Decisions) Runs after Pre-implementation Verification, before the TDD cycle. 1. Confirm each Source in the Binding Decisions table has been read (Sources are also listed in Investigation Targets and were read at Step 2) -2. Record the planned implementation approach in Investigation Notes โ€” one sentence per distinct `Axis` value present in the task's Binding Decisions table. When multiple rows share the same `Axis` value, group them and record one sentence covering the group +2. Record the planned implementation approach in Investigation Notes โ€” one sentence per distinct `Axis` value in the Binding Decisions supplied by the execution instructions. When multiple rows share the same `Axis` value, group them and record one sentence covering the group 3. Evaluate each row's Compliance Check against the planned approach. Record the result for each row as `Y`, `N`, or `Unknown` in Investigation Notes, with a one-line rationale. Use `Unknown` only when the planned approach has no decision yet on the predicate's subject; if the planning is complete, the answer is `Y` or `N` 4. Per row, branch on the evaluation: - `Y`: proceed - `N`: stop implementation and produce the final response with `status: "escalation_needed"` and `escalation_type: "binding_decision_violation"` with `phase: "pre_implementation"` (see Binding Decision Violation Escalation in Structured Response Specification). `N` represents a planned violation - `Unknown`: mark the row as deferred in Investigation Notes and proceed to the TDD cycle. The Exit Gate re-evaluates every row (including Unknown rows deferred from this step) against the final implementation and escalates if any remains `N` or `Unknown` at that point -#### Reference Contract Check (Required when the task file has a Reference Contracts section) +#### Reference Contract Check (Required when the execution instructions include Reference Contracts) Runs after Pre-implementation Verification, alongside the Binding Decision Check. @@ -204,24 +194,24 @@ When adopting a pattern, hook, or library from existing code, apply Reference Re โ–ก **New option discipline**: route any new library/pattern decision for a concern the repository already addresses through Escalation Response 2-4 instead of adopting it directly #### Implementation Flow (TDD Compliant) -**Completion Confirmation**: If all checkboxes are `[x]`, report "already completed" and end +**Completion Confirmation**: When the execution scope is supplied as a task file or Work Plan and all relevant checkboxes are already `[x]`, report "already completed" and end -**Implementation procedure for each checkbox item**: +**Implementation procedure for each implementation item**: - **New/changed behavior or reproducible bug**: RED (create and confirm a failing React Testing Library test) โ†’ GREEN (minimum implementation) โ†’ REFACTOR โ†’ VERIFY - **Behavior-preserving refactor**: BASELINE (confirm existing tests pass or add passing characterization tests) โ†’ REFACTOR โ†’ VERIFY the same evidence - **Non-reproducible bug**: EVIDENCE BASELINE (confirm the recorded reproduction attempt, concrete blocker, and named alternate evidence) โ†’ FIX โ†’ VERIFY that evidence - **Non-executable deliverable**: SOURCE BASELINE (read the named source and acceptance evidence) โ†’ PRODUCE/UPDATE โ†’ VERIFY the deliverable against them - For integration tests (multiple components), create and execute them with implementation; execute E2E tests in the final phase only -- **Progress Update [MANDATORY]**: After verification, set `[ ]` โ†’ `[x]` in (a) task file, (b) work plan in docs/plans/, and (c) overall design document if present +- **Progress Update [MANDATORY]**: Apply the Responsibility Boundaries progress rule after verification #### Operation Verification -- Execute "Operation Verification Methods" section in task +- Execute the Operation Verification Methods in the execution instructions - Perform verification according to level defined in implementation-approach skill - Record reason if unable to verify ### 4. Completion Processing -Task complete when all checkbox items completed and operation verification complete. +Task complete when all implementation items and operation verification are complete. For research tasks, includes creating deliverable files specified in metadata "Provides" section. ### 5. Return JSON Result @@ -307,10 +297,10 @@ Report in the following JSON format upon task completion (**without executing qu "taskName": "[Task name being executed]", "escalation_type": "investigation_target_not_found", "missingTargets": [ - {"path": "[path specified in task file]", "searchHint": "[section/function hint if provided, or null]", "searchAttempts": ["Checked path directly", "Searched for similar filenames in same directory"]} + {"path": "[path specified in the execution instructions]", "searchHint": "[section/function hint if provided, or null]", "searchAttempts": ["Checked path directly", "Searched for similar filenames in same directory"]} ], "user_decision_required": true, - "suggested_options": ["Provide correct file path", "Remove this Investigation Target and proceed", "Update task file with current paths"] + "suggested_options": ["Provide correct file path", "Remove this Investigation Target and retry", "Update the execution instructions with current paths"] } ``` @@ -338,15 +328,15 @@ Triggered when Reference Representativeness cannot determine the dominant librar "reason": "Out of scope file", "taskName": "[Task name being executed]", "escalation_type": "out_of_scope_file", - "details": {"file_path": "[path attempted to modify]", "allowed_list": ["[union of Target Files entries, task file, work plan, Provides paths]"], "modification_reason": "[why modification was attempted]"}, + "details": {"file_path": "[path attempted to modify]", "allowed_list": ["[explicit modification targets plus applicable task-file targets]"], "modification_reason": "[why modification was attempted]"}, "user_decision_required": true, - "suggested_options": ["Add this file to task Target files and retry", "Split into a separate task for this file", "Reconsider the implementation approach to stay within scope"] + "suggested_options": ["Authorize this file as a modification target and retry", "Split into a separate task for this file", "Reconsider the implementation approach to stay within scope"] } ``` #### 2-6. Binding Decision Violation Escalation -Triggered by `N` at the pre-implementation check, or `N` or `Unknown` at the Exit Gate re-evaluation, on any Compliance Check row in the task's Binding Decisions section. +Triggered by `N` at the pre-implementation check, or `N` or `Unknown` at the Exit Gate re-evaluation, on any Compliance Check row in the Binding Decisions supplied by the execution instructions. ```json { @@ -360,7 +350,7 @@ Triggered by `N` at the pre-implementation check, or `N` or `Unknown` at the Exi {"source": "[ADR file path with section hint, copied from Source column]", "axis": "[Axis value copied from the Axis column]", "decision": "[Decision text, copied from Decision column]", "complianceCheck": "[Compliance Check predicate, copied from Compliance Check column]", "evaluation": "N | Unknown", "rationale": "[One line explaining why the implementation does not satisfy the check, or why it cannot be evaluated]"} ], "user_decision_required": true, - "suggested_options": ["Adjust the implementation plan to satisfy the binding decision", "Update the ADR (then update the work plan's ADR Bindings and this task's Binding Decisions)", "Provide additional context that resolves the Unknown evaluation"] + "suggested_options": ["Adjust the implementation plan to satisfy the binding decision", "Update the governing decision and corresponding execution instructions", "Provide additional context that resolves the Unknown evaluation"] } ``` @@ -385,14 +375,14 @@ Triggered when the Test Environment Check finds a required component (test runne This gate runs immediately before producing the final JSON response. -โ˜ All task checkboxes completed with evidence (or `escalation_needed` triggered earlier) +โ˜ All implementation items completed with evidence (or `escalation_needed` triggered earlier) โ˜ Implementation is consistent with the Investigation Notes recorded at Step 2 (when Investigation Targets were present) โ˜ Adjacent Case Sweep evidence is non-empty and records each inspected case and disposition, or the searched surface and no-case result (when Change Category triggers the sweep) -โ˜ 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). Re-evaluate here even when the pre-implementation check passed, because the implementation may have diverged from the planned approach -โ˜ Every Reference Contracts Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes (when the task file has a Reference Contracts section). Re-evaluate here even when the pre-implementation check passed -โ˜ A test exercises the roundtrip โ€” the value the producer emits parses to the value the consumer expects (when the task has a Boundary Context with a roundtrip check from the work plan's Connection Map) +โ˜ Every Binding Decisions Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes (when the execution instructions include Binding Decisions). Re-evaluate here even when the pre-implementation check passed, because the implementation may have diverged from the planned approach +โ˜ Every Reference Contracts Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes (when the execution instructions include Reference Contracts). Re-evaluate here even when the pre-implementation check passed +โ˜ A test exercises the roundtrip โ€” the value the producer emits parses to the value the consumer expects (when the execution instructions include a Boundary Context roundtrip check) โ˜ Every Proof Obligation satisfies its selected Verification mode and Evidence requirement โ˜ When test runs are cited as `runnableCheck` evidence, they are substantive and executable per the runnableCheck.result field spec (skipped tests, placeholder/TODO-only bodies, always-passing assertions, and 0-match runner reports do not count); non-test verification (build/typecheck/CLI) is not subject to this check โ˜ Final response is a single JSON with `status: "completed"` or `status: "escalation_needed"` and matches the schema in Structured Response Specification -**ENFORCEMENT**: When any gate item is unchecked, return `escalation_needed`. Use `escalation_type: "binding_decision_violation"` with `phase: "exit_gate"` for Binding Decisions failures; use `escalation_type: "design_compliance_violation"` for other gate failures (checkbox incompletion or divergence from Investigation Notes). +**ENFORCEMENT**: When any gate item is unchecked, return `escalation_needed`. Use `escalation_type: "binding_decision_violation"` with `phase: "exit_gate"` for Binding Decisions failures; use `escalation_type: "design_compliance_violation"` for other gate failures (incomplete work or divergence from Investigation Notes). diff --git a/dev-workflows-frontend/skills/recipe-diagnose/SKILL.md b/dev-workflows-frontend/skills/recipe-diagnose/SKILL.md index fe5cb06..2f34835 100644 --- a/dev-workflows-frontend/skills/recipe-diagnose/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-diagnose/SKILL.md @@ -5,6 +5,7 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. **Context**: Diagnosis flow to identify root cause and present solutions @@ -12,7 +13,9 @@ Target problem: $ARGUMENTS ## Orchestrator Definition -**Core Identity**: "I am not a worker. I am an orchestrator." +**Core Identity**: "I am an orchestrator." + +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. **Execution Method**: - Investigation โ†’ performed by investigator @@ -232,4 +235,3 @@ Rationale: [Selection rationale] - [ ] Executed solver - [ ] Achieved coverageAssessment=sufficient (or obtained user approval after 2 additional iterations) - [ ] Presented final report to user - diff --git a/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md b/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md index 31270db..29d1bbf 100644 --- a/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md @@ -5,6 +5,7 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. **Context**: UI adjustment on already-implemented features. The verification loop (edit โ†’ check against the design source โ†’ refine) runs in the parent session. @@ -63,6 +64,8 @@ Adjustment request: $ARGUMENTS ## Execution Flow ### Step 1: External Resource Hearing +Execute Skill: external-resource-context before running the hearing protocol. + Run the hearing protocol per the external-resource-context skill (frontend domain). ### Step 2: UI Fact Gathering @@ -109,6 +112,11 @@ After work-planner returns: ### Step 5: Adjustment + Verification (parent session) +Execute Skill: frontend-ai-guide before planning or applying adjustment edits. +Execute Skill: typescript-rules before planning or applying adjustment edits. +Execute Skill: implementation-approach before planning or applying adjustment edits. +Execute Skill: test-implement before adding or changing tests. + For each adjustment unit (per file in Branch A; per work plan phase in Branch B): 1. **Plan the edit** based on ui-analyzer focusAreas and the relevant external resource (e.g., design origin's fetched_summary). 2. **Apply the edit** using Edit / Write / MultiEdit on the affected files. diff --git a/dev-workflows-frontend/skills/recipe-front-build/SKILL.md b/dev-workflows-frontend/skills/recipe-front-build/SKILL.md index 5c52651..418ebbd 100644 --- a/dev-workflows-frontend/skills/recipe-front-build/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-front-build/SKILL.md @@ -5,13 +5,19 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. ## Orchestrator Definition **Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. + +**Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression; include declined IDs with governing reasons and evidence in the final user report. +Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. + **Execution Protocol**: -1. **Delegate all work through Agent tool** โ€” invoke sub-agents, pass deliverable paths between them, and report results (permitted tools: see subagents-orchestration-guide "Orchestrator's Permitted Tools") +1. **Invoke named specialists for deliverable production** โ€” pass deliverable paths between them and validate their results (see subagents-orchestration-guide "Orchestrator Execution Boundary") 2. **Follow the 4-step task cycle exactly**: execute โ†’ branch on executor result โ†’ quality-fix โ†’ commit 3. **Enter autonomous mode** when user provides execution instruction with existing task files โ€” this IS the batch approval 4. **Scope**: Complete when all tasks are committed or escalation occurs @@ -26,7 +32,7 @@ Work plan: $ARGUMENTS Before any task processing, locate the work plan. Resolution rule: 1. List task files in `docs/plans/tasks/` matching the single-layer pattern `{plan-name}-task-*.md`. Layer-aware fullstack tasks (`{plan-name}-backend-task-*.md` / `{plan-name}-frontend-task-*.md`) are excluded here so a stale fullstack run does not redirect this recipe to the wrong work plan -2. From the matched files, also exclude every file matching any of these patterns โ€” they originate from other workflow phases and are not implementation tasks for this run's plan: `*-task-prep-*.md` (readiness preflight tasks), `_overview-*.md` (materialization overview file), `*-phase*-completion.md` (per-phase completion files), `review-fixes-*.md` (post-implementation review fixes), `integration-tests-*-task-*.md` (integration-test add-on scaffolding) +2. From the matched files, also exclude `_overview-*.md` (materialization overview files) and `*-phase*-completion.md` (per-phase completion files). 3. For each remaining file, extract the `{plan-name}` prefix as the segment that appears before `-task-` 4. When at least one task file matches, the work plan is `docs/plans/{plan-name}.md` for the prefix that has the most recent task-file mtime; ties broken by the lexicographically last `{plan-name}` 5. When no task file matches the restricted pattern, the work plan is the most-recent-mtime non-template `.md` in `docs/plans/` @@ -36,7 +42,7 @@ Before any task processing, locate the work plan. Resolution rule: Compute the **Consumed Task Set** for this run โ€” the exact files this recipe owns, executes, and later deletes. Use the same restricted pattern as Work Plan Resolution: 1. List task files in `docs/plans/tasks/` matching the single-layer pattern `{plan-name}-task-*.md` for the `{plan-name}` resolved by Work Plan Resolution. Layer-aware fullstack tasks are excluded -2. Exclude every file matching: `*-task-prep-*.md`, `_overview-*.md`, `*-phase*-completion.md`, `review-fixes-*.md`, `integration-tests-*-task-*.md` (these originate from other workflow phases) +2. Exclude every file matching `_overview-*.md` or `*-phase*-completion.md`. Every subsequent reference to "task files" in this recipe โ€” Task Generation Decision Flow, Task Execution Cycle iteration, and Final Cleanup โ€” uses this set, not the unrestricted `docs/plans/tasks/*.md` glob. @@ -48,7 +54,7 @@ Analyze the Consumed Task Set and determine the action required: |-------|----------|-------------| | Tasks exist | Consumed Task Set is non-empty | User's execution instruction serves as batch approval โ†’ Enter autonomous execution immediately | | No tasks + plan exists | Consumed Task Set is empty but the resolved work plan exists | Confirm with user โ†’ run task-decomposer | -| Neither exists + Design Doc exists | No plan, no Consumed Task Set, but `docs/design/*.md` exists | Invoke work-planner to create work plan from Design Doc, then run document-reviewer (`dev-workflows-frontend:document-reviewer`, doc_type: WorkPlan); branch on the reviewer's `verdict.decision` โ€” on `needs_revision`, re-invoke work-planner (update) and re-review until `approved`/`approved_with_conditions`; if the same blocking finding repeats without new evidence or a contract change, stop and escalate it; then present the reviewed plan for batch approval before task materialization; on `rejected`, stop before task materialization and escalate to the user | +| Neither exists + Design Doc exists | No plan, no Consumed Task Set, but `docs/design/*.md` exists | Invoke work-planner to create a work plan, then run document-reviewer (`dev-workflows-frontend:document-reviewer`, doc_type: WorkPlan). Apply the Review Resolution Gate: update for `apply`, re-review with `prior_feedback`, progress when all actionable findings are `decline`, and escalate unresolved `user_decision_required`; then present the resolved plan for batch approval before task materialization | | Neither exists | No plan, no Consumed Task Set, no Design Doc | Report missing prerequisites to user and stop | ## Task Materialization Phase (Conditional) @@ -92,9 +98,12 @@ For EACH task in the Consumed Task Set, YOU MUST: 2. **BRANCH ON EXECUTOR RESULT**: - `status: "escalation_needed"` or `"blocked"` โ†’ STOP and escalate to user - `requiresTestReview` is `true` โ†’ Invoke integration-test-reviewer with `diffBase`, changed integration/E2E paths, `taskFile`, prompt-only claims, and `mutationEvidence` - - `needs_revision` โ†’ Return to step 1 with `requiredFixes` - `approved` โ†’ Proceed to step 3 - `blocked` โ†’ STOP and escalate to user + - `needs_revision` โ†’ Apply the Review Resolution Gate + - one or more `apply` findings โ†’ Return to step 1 with those findings, then re-review with `prior_feedback` + - every actionable finding is `decline` โ†’ Proceed to step 3 + - any unresolved `user_decision_required` finding โ†’ STOP and escalate to user - `readyForQualityCheck: true` โ†’ Proceed to step 3 3. **QUALITY-FIX**: Invoke quality-fixer-frontend with `task_file`, upstream `mutationEvidence`, and `qualityCommand` when available (caller first, otherwise current task) - `stub_detected` โ†’ Return to step 1 with `incompleteImplementations[]` details @@ -146,4 +155,5 @@ Final report must include: - Quality check result - Commit count - Cleanup result +- Declined actionable findings with ID, governing reason, and evidence - Escalation or blocking summary, if any diff --git a/dev-workflows-frontend/skills/recipe-front-design/SKILL.md b/dev-workflows-frontend/skills/recipe-front-design/SKILL.md index b572660..04149c7 100644 --- a/dev-workflows-frontend/skills/recipe-front-design/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-front-design/SKILL.md @@ -5,6 +5,7 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. **Context**: Dedicated to the frontend design phase. @@ -12,15 +13,20 @@ Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or g **Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. The scope bootstrap locates seed files; the named specialists own semantic investigation and artifact authorship. + +**Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression; include declined IDs with governing reasons and evidence in the final user report. +Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. + **Execution Protocol**: -1. **Delegate all work** to sub-agents โ€” your role is to invoke sub-agents, pass data between them, and report results. The one exception is the Step 1 scope bootstrap, a recipe-local orchestrator task limited to locating seed files. +1. **Invoke named specialists for deliverable production** โ€” pass data between them and validate their results. Step 1 is a recipe-local read-only scope bootstrap limited to locating seed files. 2. **Run the frontend design flow below in order** (this recipe covers medium/large frontend): - Execute: scope bootstrap โ†’ codebase-analyzer โ†’ [Stop: Scope confirmation] โ†’ external resource hearing โ†’ ui-analyzer โ†’ ui-spec-designer โ†’ technical-designer-frontend โ†’ code-verifier โ†’ document-reviewer โ†’ design-sync - ui-spec-designer, code-verifier, and design-sync apply when the design output is a Design Doc; all are skipped for ADR-only - **Stop at every `[Stop: ...]` marker** โ†’ Wait for user approval before proceeding 3. **Scope**: Complete when design documents receive approval -**subagents-orchestration-guide usage**: Reference the guide only for orchestration principles (Delegation Boundary, Decision precedence, permitted tools), the Scale Determination table, and handoff contracts HC-02 onward. This recipe defines its own start order and subagent prompts. The guide's requirement-analyzer-origin flow, First Action Rule, HC-01, and Call Examples do not apply to this recipe. +**subagents-orchestration-guide usage**: Use the guide for orchestration principles (Delegation Boundary, Decision precedence, Execution Boundary), the Scale Determination table, and handoff contracts HC-02 onward. This recipe's start order and subagent prompts supersede the guide's requirement-analyzer-origin flow, First Action Rule, HC-01, and Agent-Specific Prompt Content. **CRITICAL**: Execute document-reviewer, design-sync (for Design Docs), and all stopping points โ€” each serves as a quality gate. Skipping any step risks undetected inconsistencies. @@ -87,7 +93,9 @@ Invoke codebase-analyzer with its existing schema. The orchestrator constructs ` ### Step 3: Scope Confirmation After codebase-analyzer returns, confirm the design scope with the user before any design work. This is a recipe-local confirmation step. -First run the requirement-convergence hearing protocol, using the codebase-analyzer findings as the facts it presents. This recipe has no requirement-analyzer, so the orchestrator both elicits and judges the fields, recording the result as the skill's `convergence` object (`outcome`, `requirements[]` with layer labels, `nonGoals[]`, plus a readiness label per field). `cost` does not apply here: the orchestrator cannot search the repository, and entering this recipe already decided to design. Carry that object into Steps 6 and 7 so ui-spec-designer respects the non-goals and technical-designer-frontend persists it to the Design Doc. +Execute Skill: requirement-convergence before running the hearing protocol. + +First run the requirement-convergence hearing protocol, using the codebase-analyzer findings as the facts it presents. In this flow, the orchestrator elicits and judges the fields and records the result as the skill's `convergence` object (`outcome`, `requirements[]` with layer labels, `nonGoals[]`, plus a readiness label per field). Treat `cost` as already resolved because semantic repository investigation is assigned to codebase-analyzer and ui-analyzer and entering this recipe decided to design. Carry that object into Steps 6 and 7 so ui-spec-designer respects the non-goals and technical-designer-frontend persists it to the Design Doc. Then present, sourced from the codebase-analyzer JSON, using AskUserQuestion: - **Target files/modules**: `analysisScope.filesAnalyzed` and the modules they belong to @@ -106,6 +114,8 @@ After the user confirms the scope, count the confirmed target files and set the **[STOP]**: Wait for the user's choice before proceeding. ### Step 4: External Resource Hearing +Execute Skill: external-resource-context before running the hearing protocol. + Run the hearing protocol per the external-resource-context skill (frontend domain). The orchestrator owns this step because it requires AskUserQuestion. The skill defines file-existence branching, two-phase hearing (structured axes + self-declaration), and persistence to `docs/project-context/external-resources.md`. ### Step 5: UI Fact Gathering @@ -140,6 +150,7 @@ Then create the UI Specification: - Example (no PRD): `prompt: "Create UI Spec from these requirements: [user requirements verbatim]. Codebase analysis: [codebase-analyzer JSON from Step 2]. Confirmed scope: [Step 3 confirmed scope]. ui_analysis: [JSON from Step 5 ui-analyzer]. Prototype code is at [user-provided path]. Place prototype in docs/ui-spec/assets/{feature-name}/."` - Invoke **document-reviewer** to verify UI Spec - `subagent_type: "dev-workflows-frontend:document-reviewer"`, `description: "UI Spec review"`, `prompt: "doc_type: UISpec target: [ui-spec path] Review for consistency and completeness"` +- Apply the Review Resolution Gate before presenting the UI Spec. If corrections are applied, re-run document-reviewer with `prior_feedback`. - **[STOP]**: Present UI Spec for user approval ### Step 7: Design Document Creation Phase @@ -150,14 +161,21 @@ Pass the Step 2 codebase-analyzer output and the Step 5 ui-analyzer output to te - **(Design Doc only)** Invoke **code-verifier** to verify Design Doc against existing code. Skip for ADR. - `subagent_type: "dev-workflows-frontend:code-verifier"`, `description: "Design Doc verification"`, `prompt: "doc_type: design-doc document_path: [Design Doc path] Verify Design Doc against existing code."` - **(Design Doc only)** Invoke **document-reviewer** to verify consistency, completeness, and adopted design validity + - Treat the preceding code-verifier result as `code_verification` evidence; the document-reviewer result controls correction routing. - `subagent_type: "dev-workflows-frontend:document-reviewer"`, `description: "Design Doc review"`, `prompt: "Review [Design Doc path] for consistency, completeness, and adopted design validity. doc_type: DesignDoc. review_context: creation. requirements_verbatim: [user requirements verbatim]. confirmed_decisions: [Step 3 confirmed scope and user answers]. codebase_analysis: [codebase-analyzer JSON from Step 2]. ui_analysis: [ui-analyzer JSON from Step 5]. code_verification: [code verification output from this step]"` + - Apply the Review Resolution Gate. When `apply` findings change the Design Doc, invoke technical-designer-frontend in update mode, then re-run code-verifier and document-reviewer with `prior_feedback`. - **(ADR only)** Invoke **document-reviewer** to verify consistency and completeness - `subagent_type: "dev-workflows-frontend:document-reviewer"`, `description: "ADR review"`, `prompt: "Review [ADR path] for consistency and completeness. doc_type: ADR. codebase_analysis: [codebase-analyzer JSON from Step 2]. ui_analysis: [ui-analyzer JSON from Step 5]"` + - Apply the Review Resolution Gate. When `apply` findings change the ADR, invoke technical-designer-frontend in update mode and re-run document-reviewer with `prior_feedback`. ### Step 8: Design Consistency Verification - **(Design Doc only)** Invoke **design-sync** using Agent tool. Skip for ADR-only. - `subagent_type: "dev-workflows-frontend:design-sync"`, `description: "Design consistency check"`, `prompt: "Check consistency across all Design Docs in docs/design/. Report conflicts and overlaps."` -- **[STOP]**: Present the design document, plus design-sync results for a Design Doc, and obtain user approval + - Apply the Review Resolution Gate to every reported conflict. + - One or more `apply` findings โ†’ invoke the named technical designer for each affected Design Doc; re-run code-verifier and document-reviewer for each modified document with the latest verification and `prior_feedback`, then re-run design-sync + - Every actionable conflict is `decline` โ†’ proceed to the approval stop + - Any unresolved `user_decision_required` conflict โ†’ stop for user input +- **[STOP]**: Present the design document, plus design-sync results for a Design Doc, and obtain user approval. For an approved ADR, invoke technical-designer-frontend in update mode to set its status to `Accepted` and verify the update before completion ## Completion Criteria @@ -172,10 +190,10 @@ Pass the Step 2 codebase-analyzer output and the Step 5 ui-analyzer output to te - [ ] Executed code-verifier on Design Doc and passed results to document-reviewer (skip for ADR-only) - [ ] Executed document-reviewer and addressed feedback - [ ] Executed design-sync for consistency verification (skip for ADR-only) -- [ ] Obtained user approval for design document +- [ ] Obtained user approval for the design document and verified an approved ADR has status `Accepted` ## Output Example Frontend design phase completed. -- UI Specification: docs/ui-spec/[feature-name]-ui-spec.md +- UI Specification: docs/ui-spec/[feature-name]-ui-spec.md or N/A โ€” ADR-only - Design document: docs/design/[document-name].md or docs/adr/[document-name].md - Approval status: User approved diff --git a/dev-workflows-frontend/skills/recipe-front-plan/SKILL.md b/dev-workflows-frontend/skills/recipe-front-plan/SKILL.md index 91566bb..4090a1c 100644 --- a/dev-workflows-frontend/skills/recipe-front-plan/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-front-plan/SKILL.md @@ -5,6 +5,7 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. **Context**: Dedicated to the frontend planning phase. @@ -12,8 +13,13 @@ Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or g **Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. + +**Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression; include declined IDs with governing reasons and evidence in the final user report. +Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. + **Execution Protocol**: -1. **Delegate all work** to sub-agents โ€” your role is to invoke sub-agents, pass data between them, and report results +1. **Invoke named specialists for deliverable production** โ€” pass data between them and validate their results 2. **Follow subagents-orchestration-guide skill planning flow**: - Execute steps defined below - **Stop and obtain approval** for plan content before completion @@ -71,7 +77,7 @@ Invoke document-reviewer to review the work plan: - `subagent_type`: "dev-workflows-frontend:document-reviewer" - `description`: "Work plan review" - `prompt`: "doc_type: WorkPlan target: docs/plans/[plan-name].md. Review semantic traceability to the Design Doc, early verification placement, real-boundary verification coverage, Failure Mode Checklist, and Review Scope." -- The work plan is a derivation of the Design Doc, so plan-fidelity findings are resolved without user input while the revision loop makes observable progress. Branch on the reviewer's `verdict.decision`: on `needs_revision`, re-invoke work-planner in update mode with the findings and re-review, repeating until `approved` or `approved_with_conditions`; if the same blocking finding repeats without new evidence or a contract change, stop and escalate it. On `rejected`, escalate to the user. +- Apply the Review Resolution Gate before branching. On `needs_revision`, re-invoke work-planner in update mode with the `apply` findings and re-review with `prior_feedback`. A result whose actionable findings are all `decline` is eligible for approval; escalate unresolved `user_decision_required` or unusable inputs. ### Step 5: Present for Approval - Present the reviewed work plan to the user for batch approval. If the user requests changes, re-invoke work-planner with revised parameters and re-run Step 4. diff --git a/dev-workflows-frontend/skills/recipe-front-review/SKILL.md b/dev-workflows-frontend/skills/recipe-front-review/SKILL.md index d4ab843..338d939 100644 --- a/dev-workflows-frontend/skills/recipe-front-review/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-front-review/SKILL.md @@ -5,6 +5,7 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. **Context**: Post-implementation quality assurance for React/TypeScript frontend @@ -12,7 +13,12 @@ Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or g **Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) -**First Action**: Register Steps 1-11 using TaskCreate before any execution. +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. + +**Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression; include declined IDs with governing reasons and evidence in the final user report. +Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. + +**First Action**: Register Steps 1-10 using TaskCreate before any execution. ## Execution Method @@ -56,17 +62,9 @@ Invoke security-reviewer using Agent tool: **If security-reviewer returned `blocked`**: Stop immediately. Report the blocked finding and escalate to user. Do not proceed to fix steps. -**Code compliance criteria (considering project stage)**: -- Prototype: Pass at 70%+ -- Production: 90%+ recommended - -**Security criteria**: -- `approved` or `approved_with_notes` โ†’ Pass -- `needs_revision` โ†’ Fail +Apply the Review Resolution Gate to both outputs before reporting or routing them. Finding dispositions determine routing; compliance percentages remain diagnostic. -**Report both results independently using subagent output fields only**: - -Before presenting to the user, the orchestrator computes a recommended route per finding using the rule below (this rule is internal โ€” do not include it in the user-facing prompt): +For each `apply` or `user_decision_required` finding, compute a proposed route using the rule below: | Finding pattern | Recommended route | |-----------------|-------------------| @@ -74,7 +72,7 @@ Before presenting to the user, the orchestrator computes a recommended route per | `dd_violation` where the code drifted from a still-correct Design Doc | `c` (Code-side fix) | | `reliability` / `security` / `maintainability` findings | `c` (Code-side fix) | -Then present to the user (label each finding with its recommended route, grouped by route): +Then present the adjudicated result to the user. Group `apply` and `user_decision_required` findings by proposed route, and list declined IDs with their reasons separately: ``` Code Compliance: [complianceRate from code-reviewer] @@ -97,23 +95,19 @@ Security Review: [status from security-reviewer] - [policy] [location]: [description] โ€” [rationale] [recommended: c] Notes: [notes from security-reviewer, if present] -Resolve discrepancies โ€” confirm or override the recommended route per finding: +Approve the proposed changes or decide unresolved items: c) Code-side fix โ€” code violates Design Doc; modify code to match d) Design-side update โ€” code is correct; Design Doc is stale, revise it - s) Skip โ€” accept current state without changes + s) Decline โ€” record the governing reason and accept current state ``` -Use AskUserQuestion. The default offer is **"accept all recommended routes"** โ€” a single confirmation for the typical case where the orchestrator's recommendations are correct. When the user wants to override, collect per-finding c/d/s decisions instead. If the user selects `s` for everything: skip Steps 5-10, proceed to Step 11. +This review command authorizes analysis; use AskUserQuestion to obtain separate implementation authority. The batch option is **"approve all proposed `apply` routes"** and its scope consists exclusively of those routes. Collect an explicit decision for each `user_decision_required` item. When the approved change set is empty, proceed directly to Step 10. Pass approved findings, routes, covered files/sections, and any stated total size budget to update or fix agents. Before re-validation, map every diff hunk to an approved finding or required consistency update; request a scope decision for unmapped or over-budget changes. -### Step 5: Execute Skill - -Execute Skill: documentation-criteria (for task file template) - -### Step 5d: Design-Side Update +### Step 5: Design-Side Update -Run this step only when the user routed at least one finding to `d`. When all routes are `c` or `s`, skip directly to Step 6. +Run this step only when the user routed at least one finding to `d`. When no `d` routes exist, skip it; continue to Step 6 only when approved `c` routes remain. 1. Invoke technical-designer-frontend in update mode using Agent tool: - `subagent_type`: "dev-workflows-frontend:technical-designer-frontend" @@ -124,6 +118,7 @@ Run this step only when the user routed at least one finding to `d`. When all ro - `subagent_type`: "dev-workflows-frontend:document-reviewer" - `description`: "Document review of updated Design Doc" - `prompt`: "Review updated Design Doc at [path] for consistency and completeness. doc_type: DesignDoc. review_context: update." + - Apply the Review Resolution Gate to this result. Route `apply` findings back to technical-designer-frontend and re-run document-reviewer with `prior_feedback`; stop for unresolved `user_decision_required`; proceed when the result is approved or every actionable finding is `decline`. 3. When multiple Design Docs exist (`ls docs/design/*.md | grep -v template | wc -l > 1`), invoke design-sync: - `subagent_type`: "dev-workflows-frontend:design-sync" @@ -131,53 +126,44 @@ Run this step only when the user routed at least one finding to `d`. When all ro - `prompt`: "source_design: [updated DD path]. Detect conflicts across all Design Docs after the update." - When `sync_status: conflicts_found`: present conflicts to the user; resolution requires re-invoking technical-designer-frontend for affected DDs. -4. After Step 5d completes: - - If the user selected `d` for all findings (no `c` routes) โ†’ skip Steps 6-8, proceed to Step 9 for re-validation +4. After Step 5 completes: + - If the user selected `d` for all findings (no `c` routes) โ†’ skip Steps 6-7, proceed to Step 8 for re-validation - If the user selected both `d` and `c` โ†’ re-evaluate the `c`-routed findings against the updated DD and drop any that are now satisfied by the DD revision; then proceed to Step 6 with the remaining `c` findings -### Step 6: Create Task File - -Create task file at `docs/plans/tasks/review-fixes-YYYYMMDD.md` -Include both code compliance issues and security requiredFixes. - -### Step 7: Execute Fixes +### Step 6: Execute Fixes Invoke task-executor-frontend using Agent tool: - `subagent_type`: "dev-workflows-frontend:task-executor-frontend" - `description`: "Execute review fixes" -- `prompt`: "Task file: docs/plans/tasks/review-fixes-YYYYMMDD.md. Apply staged fixes (stops at 5 files)." +- `prompt`: "Apply these approved code-side findings directly: [findings with IDs, governing sources, smallest correction, affected paths, and observable verification condition]. Keep the change within the approved routes and stated total size budget." -### Step 8: Quality Check +### Step 7: Quality Check Invoke quality-fixer-frontend using Agent tool: - `subagent_type`: "dev-workflows-frontend:quality-fixer-frontend" - `description`: "Quality gate check" -- Pass Step 7 `mutationEvidence` and `qualityCommand` when available (caller first, otherwise current task). +- Pass Step 6 `filesModified` and `mutationEvidence`. - `prompt`: "Confirm quality gate passage for fixed files." -### Step 9: Re-validate code-reviewer +### Step 8: Re-validate code-reviewer Invoke code-reviewer using Agent tool: - `subagent_type`: "dev-workflows-frontend:code-reviewer" - `description`: "Re-validate compliance" -- `prompt`: "Re-validate Design Doc compliance after fixes. Design Doc: [path]. Implementation files: [file list]. Prior compliance issues: $STEP_2_OUTPUT. Verify each prior issue is resolved (whether resolved code-side or design-side)." +- `prompt`: "Re-validate Design Doc compliance after fixes. Design Doc: [path]. Implementation files: [file list]. prior_feedback: [{id, disposition, correction?, reason?, evidence}]. Review the current state normally, then reconcile every prior item." -### Step 10: Re-validate security-reviewer +### Step 9: Re-validate security-reviewer Invoke security-reviewer using Agent tool (only if security fixes were applied): - `subagent_type`: "dev-workflows-frontend:security-reviewer" - `description`: "Re-validate security" -- `prompt`: "Re-validate security after fixes. governingDocuments: [{\"type\":\"design-doc\",\"path\":\"[path]\"}]. implementationFiles: [file list]. Prior findings: $STEP_3_OUTPUT." - -### Step 11: Final Cleanup and Report +- `prompt`: "Re-validate security after fixes. governingDocuments: [{\"type\":\"design-doc\",\"path\":\"[path]\"}]. implementationFiles: [file list]. prior_feedback: [{id, disposition, correction?, reason?, evidence}]. Review the current state normally, then reconcile every prior item." -Delete the review-fix task file this recipe created (if any). Its work is committed; `docs/plans/` is ephemeral working state and is not retained between recipe runs: +Apply the Review Resolution Gate to every Step 8 and Step 9 result before Step 10. Route new `apply` findings through their approved design-side or code-side path and repeat the affected verification; stop for unresolved `user_decision_required`; proceed when each result is approved or every actionable finding is `decline`. -- Delete `docs/plans/tasks/review-fixes-YYYYMMDD.md` if it exists +### Step 10: Final Report -If the file cannot be deleted (filesystem error), report the failure but do not block the final report. - -Then present the final report: +Present the final report: ``` Code Compliance: @@ -191,8 +177,6 @@ Security Review: Remaining issues: - [items requiring manual intervention] - -Cleanup: review-fixes task file removed ``` ## Auto-fixable Items (code-side path) diff --git a/dev-workflows-frontend/skills/recipe-task/SKILL.md b/dev-workflows-frontend/skills/recipe-task/SKILL.md index 9c2f55e..ad48e0f 100644 --- a/dev-workflows-frontend/skills/recipe-task/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-task/SKILL.md @@ -5,6 +5,7 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. # Task Execution with Metacognitive Analysis diff --git a/dev-workflows-frontend/skills/recipe-update-doc/SKILL.md b/dev-workflows-frontend/skills/recipe-update-doc/SKILL.md index 6bdeb54..73c3256 100644 --- a/dev-workflows-frontend/skills/recipe-update-doc/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-update-doc/SKILL.md @@ -5,6 +5,7 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. **Context**: Dedicated to updating existing design documents. @@ -12,10 +13,15 @@ Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or g **Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. + +**Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression; include declined IDs with governing reasons and evidence in the final user report. +Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. + **First Action**: Register Steps 1-6 using TaskCreate before any execution. **Execution Protocol**: -1. **Delegate all work through Agent tool** โ€” invoke sub-agents, pass deliverable paths between them, and report results (permitted tools: see subagents-orchestration-guide "Orchestrator's Permitted Tools") +1. **Invoke named specialists for deliverable production** โ€” pass deliverable paths between them and validate their results (see subagents-orchestration-guide "Orchestrator Execution Boundary") 2. **Execute update flow**: - Identify target โ†’ Clarify changes โ†’ Update document โ†’ Review โ†’ Consistency check - **Stop at every `[Stop: ...]` marker** โ†’ Wait for user approval before proceeding @@ -157,7 +163,7 @@ prompt: | **On review result**: - Approved โ†’ Proceed to Step 6 -- Needs revision โ†’ Return to Step 4 with the following prompt (max 2 iterations): +- Needs revision โ†’ Apply the Review Resolution Gate. Return to Step 4 when `apply` findings exist, using the following prompt: ``` subagent_type: [Update Agent from Step 2] description: "Revise [Type from Step 2]" @@ -165,12 +171,13 @@ prompt: | Operation Mode: update Existing Document: [path from Step 1] - ## Review Feedback to Address - $STEP_5_OUTPUT + ## Adjudicated Review Findings + [apply findings with IDs, basis, smallest correction, and affected sections] - Address each issue raised in the review feedback. + Treat these findings as the complete revision scope and preserve adjacent content. ``` -- **After 2 rejections** โ†’ Flag for human review, present accumulated feedback to user and end +- On re-review pass `prior_feedback` as `[{id, disposition, correction?, reason?, evidence}]` +- All actionable findings are `decline` and every `user_decision_required` item is resolved โ†’ Proceed to Step 6 Present review result to user for approval. @@ -200,7 +207,6 @@ prompt: | |-------|--------| | Target document not found | Report and end (document creation is out of scope) | | Sub-agent update fails | Log failure, present error to user, retry once | -| Review rejects after 2 revisions | Stop loop, flag for human intervention | | design-sync detects conflicts | Present to user for resolution decision | ## Completion Criteria diff --git a/dev-workflows-frontend/skills/requirement-convergence/SKILL.md b/dev-workflows-frontend/skills/requirement-convergence/SKILL.md index bcb8092..0c3ec2f 100644 --- a/dev-workflows-frontend/skills/requirement-convergence/SKILL.md +++ b/dev-workflows-frontend/skills/requirement-convergence/SKILL.md @@ -28,7 +28,7 @@ Judgment rules per field: [references/criteria.md](references/criteria.md). ## Hearing Protocol -Eliciting requires user interaction, so the orchestrator owns it. It runs after the analysis that produced the scope facts, because the orchestrator investigates nothing itself. +Eliciting and judging the convergence fields require user interaction, so the orchestrator owns them. The hearing runs after the specialist analysis that produced the scope facts; production of that investigation output remains with the specialist. Register these steps before starting and record each step's evidence as it completes: diff --git a/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md index 8393731..4aef64f 100644 --- a/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md @@ -7,27 +7,28 @@ description: Guides subagent coordination through implementation workflows. Use ## Role: The Orchestrator -All investigation, analysis, and implementation work flows through specialized subagents. +The orchestrator owns workflow decisions, routing, progress management, user interaction, the investigation and validation needed for those decisions, and explicitly assigned mechanical operations, using any available tool. Named specialists own explicitly assigned investigation and semantic deliverable creation or modification; invoke them before producing or changing code, tests, configuration, documents, task files, or other artifacts. ### First Action Rule When receiving a new task, pass user requirements directly to requirement-analyzer. Determine the workflow based on its scale assessment result. -requirement-analyzer returns a `convergence` object. Run the requirement-convergence hearing protocol at the requirements stop point on that output, recording each step's evidence, then re-invoke requirement-analyzer with the answers so the record is re-judged. The hearing runs in the orchestrator because it requires user interaction, and runs after the analysis because the orchestrator investigates nothing itself. +requirement-analyzer returns a `convergence` object. Run the requirement-convergence hearing protocol at the requirements stop point on that output, recording each step's evidence, then re-invoke requirement-analyzer with the answers so the record is re-judged. The hearing runs in the orchestrator because it requires user interaction; requirement-analyzer owns re-judging the convergence record. ### Requirement Change Detection During Flow -**During flow execution**, monitor user responses for scope-expanding signals: -- Mentions of new features/behaviors (additional operation methods, display on different screens, etc.) -- Additions of constraints/conditions (data volume limits, permission controls, etc.) -- Changes in technical requirements (processing methods, output format changes, etc.) - -**When any signal is detected โ†’ Re-run requirement-analyzer with integrated requirements, identify which approved artifacts or task boundaries the change invalidates, and resume from the earliest invalidated gate. Preserve earlier outputs that remain valid.** +Treat new or changed behaviors, constraints, or technical requirements as requirement changes. Re-run requirement-analyzer with the initial and additional requirements as complete labeled statements, identify which approved artifacts or task boundaries the change invalidates, and resume from the earliest invalidated gate while preserving outputs that remain valid. ## Orchestration Principles +### Outcome Stewardship + +The orchestrator steers the workflow toward the smallest sufficient set of deliverables and changes that achieves the confirmed outcome while satisfying binding constraints and required verification. Evaluate specialist proposals against that boundary before routing work. + ### Delegation Boundary: What vs How +Before assigning repository work, inspect the current state needed to identify **what to accomplish** and **where to work**; pass unresolved questions as explicit investigation scope. + The orchestrator passes **what to accomplish** and **where to work**. Each specialist determines **how to execute** autonomously. **Pass to specialists** (what/where/constraints): @@ -40,35 +41,28 @@ The orchestrator passes **what to accomplish** and **where to work**. Each speci - Execution order and tool flags - Which files to inspect or modify within the given scope -| | Bad (orchestrator prescribes how) | Good (orchestrator passes what) | -|---|---|---| -| quality-fixer | "Run these checks: 1. lint 2. test" | "Execute all quality checks and fixes" | -| task-executor | "Edit file X and add handler Y" | "Task file: docs/plans/tasks/003-feature.md" | - -**Decision precedence when outputs conflict**: +**Decision precedence for routing**: 1. User instructions (explicit requests or constraints) 2. Task files and design artifacts (Design Doc, PRD, work plan) 3. Objective repo state (git status, file system, project configuration) 4. Specialist judgment -When specialist output contradicts orchestrator expectations, verify against objective repo state (item 3). If repo state confirms the specialist, follow the specialist. Override specialist output only when it conflicts with items 1 or 2. +Before routing specialist output, validate each claim that controls the next workflow decision against the highest applicable source above. Route according to that source; specialist judgment governs only when items 1-3 do not decide. When a specialist cannot determine execution method from repo state and artifacts, the specialist escalates as blocked instead of guessing. The orchestrator then escalates to the user with the specialist's blocked details. -### Task Assignment with Responsibility Separation +### Review Resolution + +Apply `references/review-resolution.md` to actionable deliverable-review findings. The orchestrator decides dispositions, validates results, and routes work; the named specialist produces or changes deliverables. -Assign work based on each subagent's responsibilities: +### Task Assignment with Responsibility Separation -**What to delegate to task-executor**: -- Implementation work and test addition -- Confirmation of added tests passing (existing tests are not covered) -- Delegate quality assurance exclusively to quality-fixer (or quality-fixer-frontend for frontend tasks) +| Specialist | Responsibility | +|---|---| +| task-executor | Implement scoped work and tests, and confirm added tests pass; leave whole-repository quality assurance to the quality-fixer. | +| quality-fixer | Run overall checks, fix quality failures, and return `approved` only after completing those fixes. | -**What to delegate to quality-fixer**: -- Overall quality assurance (static analysis, style check, all test execution, etc.) -- Complete execution of quality error fixes -- Self-contained processing until fix completion -- Final approved judgment (only after fixes are complete) +For frontend work, substitute task-executor-frontend and quality-fixer-frontend; in fullstack work, select them by task layer. ## Constraints Between Subagents @@ -79,6 +73,8 @@ Assign work based on each subagent's responsibilities: Autonomous execution MUST stop and wait for user input at these points. **Use AskUserQuestion to present confirmations and questions.** +Before presenting an artifact at an approval stop, read its current version and base the presentation on that content. + | Phase | Stop Point | User Action Required | |-------|------------|---------------------| | Requirements | After requirement-analyzer completes | Answer the requirement-convergence hearing, then confirm requirements | @@ -111,19 +107,9 @@ Each subagent invocation is a **fresh Agent tool** call, isolating each phase's - `description`: Concise task description (3-5 words) - `prompt`: Specific instructions including deliverable paths -### Orchestrator's Permitted Tools - -The orchestrator coordinates work using only the following tools: +### Orchestrator Execution Boundary -| Tool | Purpose | -|------|---------| -| Agent | Invoke subagents | -| AskUserQuestion | User confirmations and questions | -| TaskCreate / TaskUpdate | Progress tracking | -| Bash | Shell operations (git commit, ls, verification commands) | -| Read | Deliverable documents for information bridging between subagents | - -All implementation work (Edit, Write, MultiEdit) is performed by subagents, not the orchestrator. +Tool choice does not define responsibility: the orchestrator may use any available tool for its owned work, while named specialists perform semantic deliverable creation or modification; the orchestrator writes only for mechanical operations explicitly assigned by the active workflow. ### Prompt Construction Rule Every subagent prompt must include: @@ -134,40 +120,26 @@ Construct the prompt from the agent's Input Parameters section and the deliverab Two additional rules: - Subagents see only the Agent prompt and files they read. Include required paths, prior JSON, parameters, and scope constraints explicitly. -- Replace every `[placeholder]` in examples below with concrete values before invoking the Agent tool. - -### Call Example (requirement-analyzer) -- subagent_type: "requirement-analyzer" -- description: "Requirement analysis" -- prompt: "Requirements: [user requirements]. Context: [any relevant context]. Perform requirement analysis and scale determination." -- On re-invocation after the convergence hearing, append: "Hearing answers: [the user's answers per convergence field]. Re-judge the convergence record with these answers." - -### Call Example (codebase-analyzer) -- subagent_type: "codebase-analyzer" -- description: "Codebase analysis" -- prompt: "requirement_analysis: [JSON from requirement-analyzer]. prd_path: [path if exists]. requirements: [original user requirements]. Analyze the existing codebase and produce design guidance." +- Resolve every placeholder in workflow prompt templates before invoking the Agent tool. -### Call Example (ui-analyzer) -- subagent_type: "ui-analyzer" -- description: "UI fact gathering" -- prompt: "requirement_analysis: [JSON from requirement-analyzer]. requirements: [original user requirements]. ui_spec_path: [path if exists]. target_components: [list if focused]. Read docs/project-context/external-resources.md, fetch external UI sources via the declared access methods (MCP / URL / file), and analyze the existing UI codebase. Output the consolidated UI fact JSON." +### Agent-Specific Prompt Content -When invoked alongside codebase-analyzer for frontend or fullstack-frontend work, run both agents in parallel and pass both JSON outputs to consumers (ui-spec-designer for the design phase; technical-designer-frontend for the Design Doc phase). - -### Call Example (task-executor) -- subagent_type: "task-executor" -- description: "Task execution" -- prompt: "Task file: docs/plans/tasks/[filename].md Please complete the implementation" +| Specialist | Required prompt content | +|---|---| +| requirement-analyzer | User requirements and relevant context; on re-invocation, add the hearing answers per `convergence` field and request re-judgment. | +| codebase-analyzer | `requirement_analysis`, optional `prd_path`, and original requirements. | +| ui-analyzer | `requirement_analysis`, original requirements, optional UI Spec and target components, plus the external-resource context path and declared access methods. Run it in parallel with codebase-analyzer for frontend work; pass both outputs to ui-spec-designer for the UI Spec phase and technical-designer-frontend for the Design Doc phase. | +| task-executor | The task file path when one exists; otherwise the direct scope, governing sources, target paths, and observable verification condition. | ## Structured Response Specification Subagents respond in JSON format. Key fields for orchestrator decisions: - **requirement-analyzer**: scale, confidence, affectedLayers, adrRequired, scopeDependencies, questions, convergence (fields with readiness labels; a field below `ready` returns as a `convergence` question) -- **codebase-analyzer**: analysisScope.categoriesDetected, dataModel.detected, qualityAssurance (mechanisms[], domainConstraints[]), focusAreas[], existingElements count, limitations -- **ui-analyzer**: analysisScope.uiConventions, externalResources (designOrigin/designSystem/guidelines/visualVerification with fetch_status), componentStructure[], propsPatterns[], cssLayout[], stateDisplay[], displayConditions[], i18n, accessibility[], generatedArtifacts[], focusAreas[] (raw fact_id; consumers apply `ui:` prefix when merging with codebase analysis facts), candidateWriteSet[] (with confidence labels), limitations +- **codebase-analyzer**: pass its full JSON unchanged; HC-02 defines the fields consumed downstream +- **ui-analyzer**: pass its full JSON unchanged with raw `fact_id` values; the consumer applies the `ui:` prefix when merging with codebase facts - **code-verifier**: `summary.status` (consistent/mostly_consistent/needs_review/inconsistent/blocked), `summary.consistencyScore`, discrepancies[], reverseCoverage (including dataOperationsInCode, testBoundariesSectionPresent). Pre-implementation: verifies Design Doc claims against existing codebase. Post-implementation: verifies implementation consistency against the governing Design Doc or Work Plan (pass `code_paths` scoped to changed files) -- **task-executor**: status (escalation_needed/completed), escalation_type (design_compliance_violation/similar_function_found/investigation_target_not_found/out_of_scope_file/dependency_version_uncertain/binding_decision_violation/test_environment_not_ready), testsAdded, requiresTestReview -- **quality-fixer**: Input: `task_file` (path to current task file โ€” always pass this in orchestrated flows). Status: approved/stub_detected/blocked. `stub_detected` โ†’ route back to task-executor with `incompleteImplementations[]` details for completion, then re-run quality-fixer. `blocked` โ†’ discriminate by `reason` field: `"Cannot determine due to unclear specification"` โ†’ read `blockingIssues[]` for specification details; `"Execution prerequisites not met"` โ†’ read `missingPrerequisites[]` with `resolutionSteps` โ€” present these to the user as actionable next steps +- **task-executor**: status (escalation_needed/completed), escalation_type (design_compliance_violation/similar_function_found/investigation_target_not_found/out_of_scope_file/dependency_version_uncertain/binding_decision_violation/test_environment_not_ready), changeSummary, testsAdded, requiresTestReview +- **quality-fixer**: Input: optional `task_file`, plus the executor's `filesModified` and `mutationEvidence`; pass `qualityCommand` only when the caller or task supplies one. Status: approved/stub_detected/blocked. `stub_detected` โ†’ route back to task-executor with `incompleteImplementations[]` details for completion, then re-run quality-fixer. `blocked` โ†’ discriminate by `reason` field: `"Cannot determine due to unclear specification"` โ†’ read `blockingIssues[]` for specification details; `"Execution prerequisites not met"` โ†’ read `missingPrerequisites[]` with `resolutionSteps` โ€” present these to the user as actionable next steps - **document-reviewer**: `verdict.decision` (approved/approved_with_conditions/needs_revision/rejected) - **design-sync**: sync_status (synced/conflicts_found) - **integration-test-reviewer**: Input: `changedTestFiles[]`, `diffBase`, optional review-basis inputs, and `mutationEvidence`. Output: status (`approved`/`needs_revision`/`blocked`), `reviewBasis`, requiredFixes @@ -176,114 +148,57 @@ Subagents respond in JSON format. Key fields for orchestrator decisions: ## Handling Requirement Changes -### Handling Requirement Changes in requirement-analyzer -requirement-analyzer follows the "completely self-contained" principle and processes requirement changes as new input. - -#### How to Integrate Requirements +Use create mode for initial documents. For requirement-driven revisions, invoke the owning document specialist in `update` mode and add history: -**Important**: To maximize accuracy, integrate requirements as complete sentences, including all contextual information communicated by the user. Result format: raw concatenation of all requirements, followed by a labeled summary (`Initial requirement: โ€ฆ` / `Additional requirement: โ€ฆ`). - -### Update Mode for Document Generation Agents -Document generation agents (work-planner, technical-designer, prd-creator) can update existing documents in `update` mode. - -- **Initial creation**: Create new document in create (default) mode -- **On requirement change**: Edit existing document and add history in update mode - -Criteria for timing when to call each agent: -- **work-planner**: Request updates only before execution -- **technical-designer**: Request updates according to design changes โ†’ Execute document-reviewer for consistency check -- **prd-creator**: Request updates according to requirement changes โ†’ Execute document-reviewer for consistency check -- **document-reviewer**: Always execute before user approval after PRD/ADR/Design Doc creation/update, and after Work Plan creation/update at Medium/Large scale (Small uses a simplified plan with no semantic review โ€” no Design Doc to trace against) +- **work-planner**: update only before execution +- **technical-designer / prd-creator**: update affected documents, then invoke document-reviewer +- **document-reviewer**: run before user approval after PRD/ADR/Design Doc changes and after Medium/Large Work Plan changes; Small plans require no semantic review ## Basic Flow: Planning and Implementation -Always start with requirement-analyzer, hold the requirement-convergence hearing on its output, then select the minimum planning flow required by scale and affected layers. - ### Planning flow (per scale) | Scale | Planning flow (ends at task-decomposer for Medium/Large; ends at work-planner for Small) | |-------|---------------| -| Large | requirement-analyzer โ†’ PRD โ†’ PRD review โ†’ external resource hearing โ†’ optional ADR โ†’ codebase-analyzer (+ ui-analyzer in parallel for frontend/fullstack) โ†’ optional UI Spec โ†’ Design Doc โ†’ code-verifier โ†’ document-reviewer โ†’ design-sync โ†’ acceptance-test-generator โ†’ work-planner โ†’ work plan review (document-reviewer, doc_type WorkPlan) โ†’ task-decomposer | +| Large | requirement-analyzer โ†’ PRD โ†’ PRD review โ†’ external resource hearing โ†’ codebase-analyzer (+ ui-analyzer in parallel for frontend/fullstack) โ†’ optional UI Spec โ†’ optional ADR โ†’ Design Doc โ†’ code-verifier โ†’ document-reviewer โ†’ design-sync โ†’ acceptance-test-generator โ†’ work-planner โ†’ work plan review (document-reviewer, doc_type WorkPlan) โ†’ task-decomposer | | Medium | requirement-analyzer โ†’ external resource hearing โ†’ codebase-analyzer (+ ui-analyzer in parallel for frontend/fullstack) โ†’ optional UI Spec โ†’ optional ADR โ†’ Design Doc โ†’ code-verifier โ†’ document-reviewer โ†’ design-sync โ†’ acceptance-test-generator โ†’ work-planner โ†’ work plan review (document-reviewer, doc_type WorkPlan) โ†’ task-decomposer | | Small | requirement-analyzer โ†’ work-planner | -The requirement-convergence hearing follows requirement-analyzer in every flow. Both it and the external resource hearing run in the orchestrator (they require AskUserQuestion). ui-analyzer joins codebase-analyzer in parallel only when the work has a frontend surface; for backend-only work the planning flow uses codebase-analyzer alone. +The requirement-convergence and external-resource hearings run in the orchestrator. Run ui-analyzer and codebase-analyzer in parallel only for frontend surfaces. -After the planning flow completes and the user grants batch approval, implementation proceeds. Verifying the plan is implementable end-to-end (verification lanes, fixtures, E2E environment) is an optional preflight the user runs at their discretion via the recipe-prepare-implementation recipe; this guide does not invoke any orchestrator above the agent layer. - -Then execute the task execution cycle: `task-executor โ†’ quality-fixer โ†’ commit` for each task. See "Autonomous Execution Mode" below for full per-task details. At Small scale this cycle still applies โ€” implementation runs through `task-executor`, not orchestrator-direct edits. - -Each agent name in the chain is invoked via the Agent tool (per "Orchestrator's Permitted Tools" above). +After batch approval, enter the autonomous cycle below. Small-scale implementation also runs through task-executor. Rules: -- Large scale requires PRD before Design Doc creation -- Frontend/fullstack flows add UI Spec before Design Doc creation +- Frontend/fullstack flows that produce a Design Doc complete the UI Spec first; ADR-only flows skip the UI Spec - Fullstack layer sequencing is defined only in `references/monorepo-flow.md` - `design-sync` is required whenever multiple Design Docs exist - `task-decomposer` begins only after work plan review (document-reviewer, doc_type WorkPlan; Medium/Large) and batch approval -- Work plan review self-heals: on `verdict.decision` `needs_revision`, route back to work-planner (update) and re-review until `approved`/`approved_with_conditions`; `rejected` escalates to the user. If re-review returns the same blocking finding and the update adds no new evidence or contract change, stop the loop and escalate that finding. The work plan is a derivation of the Design Doc, so plan-fidelity findings need no user adjudication while the loop is making observable progress +- Work plan review applies Review Resolution: revise and re-review with `prior_feedback` for `apply`; proceed when all actionable findings are `decline`; escalate unresolved `user_decision_required` or unusable inputs ## Autonomous Execution Mode -### Pre-Execution Environment Check - -**Principle**: Verify subagents can complete their responsibilities - -**Required environments**: -- Commit capability (for per-task commit cycle) -- Quality check tools (quality-fixer will detect and escalate if missing) -- Test runner (task-executor will detect and escalate if missing) - -**If critical environment unavailable**: Escalate with specific missing component before entering autonomous mode -**If detectable by subagent**: Proceed (subagent will escalate with detailed context) +### Pre-Execution Gate -### Authority Delegation +Verify commit capability before autonomous mode. Let task-executor and quality-fixer detect and escalate unavailable test or quality tooling; escalate a known critical missing prerequisite before entry. -**After environment check passes**: -- Batch approval for entire implementation phase delegates authority to subagents -- task-executor: Implementation authority (can use Edit/Write) -- quality-fixer: Fix authority (automatic quality error fixes) +Batch approval authorizes task-executor implementation and quality-fixer corrections until completion or escalation. -### Definition of Autonomous Execution Mode +### Autonomous Execution Summary After "batch approval for entire implementation phase" with work-planner, autonomously execute the following processes without human approval: ```mermaid graph TD - START[Batch approval for entire implementation phase] --> AUTO[Start autonomous execution mode] - AUTO --> TD[task-decomposer: Task materialization] - TD --> LOOP[Task execution loop] - LOOP --> TE[task-executor: Implementation] - TE --> ESCJUDGE{Escalation judgment} - ESCJUDGE -->|escalation_needed/blocked| USERESC[Escalate to user] - ESCJUDGE -->|requiresTestReview: true| ITR[integration-test-reviewer] - ESCJUDGE -->|No issues| QF - ITR -->|needs_revision| TE - ITR -->|approved| QF - ITR -->|blocked| USERESC - QF[quality-fixer: Quality check and fixes] --> QFJUDGE{quality-fixer result} - QFJUDGE -->|stub_detected| TE - QFJUDGE -->|approved| COMMIT[Orchestrator: Execute git commit] - QFJUDGE -->|blocked| USERESC - COMMIT --> CHECK{Any remaining tasks?} - CHECK -->|Yes| LOOP - CHECK -->|No| VERIFY[Post-implementation verification] - VERIFY --> CV[code-verifier: Governing document consistency check] - VERIFY --> SEC[security-reviewer: Security review] - CV --> VRESULT{Verification results} - SEC --> VRESULT - VRESULT -->|All passed| REPORT[Completion report] - VRESULT -->|Any failed| VFIX[task-executor: Verification fixes] - VFIX --> QF2[quality-fixer: Quality check] - QF2 --> REVERIFY[Re-run both verifiers] - REVERIFY --> VRESULT - VRESULT -->|blocked| USERESC - - LOOP --> INTERRUPT{User input?} - INTERRUPT -->|None| TE - INTERRUPT -->|Yes| REQCHECK{Requirement change check} - REQCHECK -->|No change| TE - REQCHECK -->|Change| STOP[Stop autonomous execution] - STOP --> RA[Re-analyze with requirement-analyzer] + START[Batch approval] --> TD[task-decomposer] + TD --> CYCLE[Per-task 4-step cycle, including commit] + CYCLE -->|remaining tasks| CYCLE + CYCLE -->|all tasks complete| VERIFY[code-verifier + security-reviewer] + CYCLE -->|blocked, escalation, or requirement change| USER[Escalate or re-analyze] + VERIFY -->|passed| REPORT[Completion report] + VERIFY -->|actionable findings| RR[Review Resolution] + RR -->|apply| FIX[task-executor + quality-fixer] + FIX --> VERIFY + RR -->|all decline| REPORT + RR -->|user decision required| USER ``` ### Post-Implementation Verification Pass/Fail Criteria @@ -293,118 +208,83 @@ graph TD | code-verifier | `summary.status` is `consistent` or `mostly_consistent` | `summary.status` is `needs_review` or `inconsistent` | `summary.status` is `blocked` โ†’ Escalate to user | | security-reviewer | `status` is `approved` or `approved_with_notes` | `status` is `needs_revision` | `status` is `blocked` โ†’ Escalate to user | -**Fix-cycle handoff**: Consolidate failed verifier findings into one ephemeral task per required executor and pass each exact path as `task_file` through its executor and quality-fixer. Use `review-fixes-{plan-name}-task-*` for single-layer work and `review-fixes-{plan-name}-{backend|frontend}-task-*` for fullstack routing; delete the files after all verifiers pass. +**Fix-cycle handoff**: Apply Review Resolution, then pass each required executor the `apply` findings, affected paths, governing evidence, and verification condition directly. Carry `prior_feedback` to reviewer inputs that support reconciliation. **Re-run rule**: After any post-implementation verification fix cycle, re-run both code-verifier and security-reviewer before accepting the result. ### Conditions for Stopping Autonomous Execution -Stop autonomous execution and escalate to user in the following cases: -1. **Escalation from subagent** - - When receiving response with `status: "escalation_needed"` - - When receiving response with `status: "blocked"` - -2. **When requirement change detected** - - Any match in requirement change detection checklist - - Stop autonomous execution and re-analyze with integrated requirements in requirement-analyzer - - Mark affected PRD/UI Spec/ADR/Design Doc/Work Plan/task outputs invalid and resume from the earliest invalidated approval gate; preserve outputs outside the changed requirement's impact - -3. **When work-planner update restriction is violated** - - Requirement changes after task-decomposer starts require requirement re-analysis and task invalidation - - Restart document design only when the re-analysis shows that an approved requirement, contract, data flow, verification strategy, or task boundary changed - -4. **When user explicitly stops** - - Direct stop instruction or interruption +| Trigger | Action | +|---|---| +| A subagent returns `escalation_needed` or `blocked` | Escalate its concrete details to the user. | +| Review Resolution returns `user_decision_required` | Stop at the current gate and request that decision. | +| A requirement changes | Apply Requirement Change Detection above. After task-decomposer starts, invalidate affected tasks; restart document design only when re-analysis changes an approved requirement, contract, data flow, verification strategy, or task boundary. | +| The user stops or interrupts | Stop autonomous execution. | ### Task Management: 4-Step Cycle **Per-task cycle**: -1. **Execute**: invoke Agent tool (subagent_type: "task-executor") โ†’ Record the current HEAD as `diffBase`, pass the task file path in the prompt, and receive the structured response +1. **Execute**: record the current HEAD as `diffBase`, then invoke task-executor with the task file path when one exists or with the direct scope contract above 2. **Branch on executor result**: - `status: escalation_needed` or `blocked` โ†’ Escalate to user - - `requiresTestReview` is `true` โ†’ Invoke integration-test-reviewer with `diffBase`, changed integration/E2E paths, `taskFile`, prompt-only claims, and `mutationEvidence` - - `needs_revision` โ†’ Return to step 1 with `requiredFixes` + - `requiresTestReview` is `true` โ†’ Invoke integration-test-reviewer with `diffBase`, changed integration/E2E paths, optional `taskFile`, prompt-only claims, and `mutationEvidence` - `approved` โ†’ Proceed to step 3 - `blocked` โ†’ Escalate to user + - `needs_revision` โ†’ Apply Review Resolution + - one or more `apply` findings โ†’ Return to step 1 with those findings, then re-review with `prior_feedback` + - every actionable finding is `decline` โ†’ Proceed to step 3 + - any unresolved `user_decision_required` finding โ†’ Escalate to user - Otherwise โ†’ Proceed to step 3 -3. **Quality-fix**: invoke quality-fixer with `task_file`, upstream `mutationEvidence`, and `qualityCommand` when available (caller first, otherwise current task) +3. **Quality-fix**: invoke quality-fixer with upstream `filesModified` and `mutationEvidence`, plus `task_file` when available and `qualityCommand` from the caller first or task otherwise - `stub_detected` โ†’ Return to step 1 with `incompleteImplementations[]` details - `blocked` โ†’ Escalate to user - `approved` โ†’ Proceed to step 4 -4. **Commit**: execute git commit with Bash after quality-fixer returns `approved` - -### Progress Tracking - -Register overall phases using TaskCreate. Update each phase with TaskUpdate as it completes. - -## Main Orchestrator Roles - -1. **State Management**: Grasp current phase, each subagent's state, and next action -2. **Information Bridging**: Data conversion and transmission between subagents - - Convert each subagent's output to next subagent's input format - - **Always pass deliverables from previous process to next agent** - - Extract necessary information from structured responses - - Compose commit messages from changeSummary - - Explicitly integrate initial and additional requirements when requirements change - - ### Handoff Contracts - - #### HC-01: requirement-analyzer โ†’ codebase-analyzer - - Pass: `requirement_analysis` (including `convergence`), `prd_path` (if exists), original user requirements - - #### HC-01b: convergence record โ†’ document owner - - Pass `convergence` from the last requirement-analyzer invocation (or, in flows without one, the orchestrator's own judged record) to whichever agent owns the persisting document - - **prd-creator** (when a PRD is created or updated): persists `outcome` to `Success Criteria`, and `nonGoals` plus `speculative` requirements to `Future / Out of Scope` with origin `user` - - **technical-designer / technical-designer-frontend**: persists the same to the Design Doc's `Requirement Convergence` when no PRD exists, and always records the fields left `weak-but-explicit` there - - Pass the record unchanged; a field's readiness label travels with it - - #### HC-02: codebase-analyzer โ†’ technical-designer - - Pass: full codebase-analyzer JSON as additional context - - Required downstream uses: - - `focusAreas` โ†’ canonical disposition-target list for the Fact Disposition Table - - `dataModel`, `dataTransformationPipelines`, `qualityAssurance` โ†’ Existing Codebase Analysis / Verification Strategy / Quality Assurance sections - - #### HC-03: technical-designer โ†’ code-verifier - - Pass: Design Doc path (`doc_type: design-doc`) - - Do not pass `code_paths`; code-verifier discovers scope from the document - - #### HC-04: code-verifier + codebase-analyzer โ†’ document-reviewer - - Pass: `review_context: creation`, `code_verification` JSON, the same `codebase_analysis` JSON previously given to the designer, original user requirements as `requirements_verbatim`, and confirmed scope and user decisions as `confirmed_decisions` - - Purpose: reviewer validates discrepancy integration, Fact Disposition coverage against `focusAreas`, and Design Convergence against the effective requirements +4. **Commit**: after quality-fixer returns `approved`, compose the message from `changeSummary` and execute git commit with Bash - #### HC-05: code-verifier โ†’ next-layer technical-designer (fullstack only) - - Defined only for multi-layer fullstack flow in `references/monorepo-flow.md` - - Pass: prior-layer Design Doc path plus `prior_layer_verification` - - Use only `discrepancies[]` as known issues to address or escalate. Do not infer verified claims that are not explicitly present in the verifier output. +Register overall phases using TaskCreate and update each phase with TaskUpdate as it completes. - #### technical-designer โ†’ work-planner +## Handoff Contracts - **Pass to work-planner**: Design Doc path. Work-planner reads the DD template from documentation-criteria skill, scans all DD sections, and extracts technical requirements in these categories: - - **Verification Strategy**: Extracted to work plan header (Correctness Proof Method + Early Verification Point) - - **Implementation targets**: Components, functions, or data structures to create or modify - - **Connection/switching/registration**: Integration points, dependency wiring, switching methods - - **Contract changes and propagation**: Interface changes, data contracts, field propagation across boundaries - - **Verification requirements**: Verification methods, test boundaries, integration verification points - - **Prerequisite work**: Migration steps, security measures, environment setup +### HC-01: requirement-analyzer โ†’ codebase-analyzer +- Pass: `requirement_analysis` (including `convergence`), `prd_path` (if exists), original user requirements - Work-planner produces a Design-to-Plan Traceability table mapping each extracted item to covering task(s). Items without a covering task must be marked as `gap` with justification. Unjustified gaps are errors. Justified gaps require user confirmation before plan approval. +### HC-01b: convergence record โ†’ document owner +- Pass `convergence` from the last requirement-analyzer invocation (or, in flows without one, the orchestrator's own judged record) to whichever agent owns the persisting document +- **prd-creator** (when a PRD is created or updated): persists `outcome` to `Success Criteria`, and `nonGoals` plus `speculative` requirements to `Future / Out of Scope` with origin `user` +- **technical-designer / technical-designer-frontend**: persists the same to the Design Doc's `Requirement Convergence` when no PRD exists, and always records the fields left `weak-but-explicit` there +- Pass the record unchanged; a field's readiness label travels with it - #### HC-06: acceptance-test-generator โ†’ work-planner +### HC-02: codebase-analyzer โ†’ technical-designer +- Pass: full codebase-analyzer JSON as additional context +- Required downstream uses: + - `focusAreas` โ†’ canonical disposition-target list for the Fact Disposition Table + - `dataModel`, `dataTransformationPipelines`, `qualityAssurance` โ†’ Existing Codebase Analysis / Verification Strategy / Quality Assurance sections - **Pass to acceptance-test-generator**: Design Doc path; UI Spec path (if exists). +### HC-03: technical-designer โ†’ code-verifier +- Pass: Design Doc path (`doc_type: design-doc`) +- Leave `code_paths` unspecified so code-verifier discovers scope from the document - **Orchestrator verification**: Every non-null `generatedFiles.` path exists on disk. For each null lane, `e2eAbsenceReason.` is present (intentional absence, not an error). +### HC-04: code-verifier + codebase-analyzer โ†’ document-reviewer +- Pass: `review_context: creation`, `code_verification` JSON, the same `codebase_analysis` JSON previously given to the designer, original user requirements as `requirements_verbatim`, and confirmed scope and user decisions as `confirmed_decisions` +- Purpose: reviewer validates discrepancy integration, Fact Disposition coverage against `focusAreas`, and Design Convergence against the effective requirements - **Pass to work-planner**: integration / fixture-e2e / service-integration-e2e file paths (or null per lane), per-lane absence reasons, plus timing guidance โ€” integration tests are created alongside each phase implementation, fixture-e2e tests are created alongside the UI feature phase, service-integration-e2e tests are executed only in the final phase. +### HC-05: code-verifier โ†’ next-layer technical-designer (fullstack only) +- Defined only for multi-layer fullstack flow in `references/monorepo-flow.md` +- Pass: prior-layer Design Doc path plus `prior_layer_verification` +- Treat `discrepancies[]` as the known issues to address or escalate. Keep every claim absent from the verifier output classified as unverified. - **On error**: Escalate to user when status != completed and integration file generation failed unexpectedly. A null E2E lane with a valid absence reason is not an error. +### technical-designer โ†’ work-planner -3. **ADR Status Management**: Update ADR status after user decision (Accepted/Rejected) +Pass the Design Doc path. Work-planner owns the documentation-criteria template scan and Design-to-Plan Traceability; unjustified coverage gaps are errors, and justified gaps require user confirmation before plan approval. -## Important Constraints +### HC-06: acceptance-test-generator โ†’ work-planner -Recap (defined above): quality-fixer approval before commit; inter-agent communication is JSON; document-reviewer + user approval before proceeding; check next step against work planning flow after approval; resolve conflicts via Decision precedence. +- Pass the Design Doc and optional UI Spec paths to acceptance-test-generator. +- Verify each non-null `generatedFiles.` path exists and each null lane has `e2eAbsenceReason.`. +- Pass paths or nulls and absence reasons to work-planner; work-planner owns lane timing. +- Escalate unexpected integration generation failure; a null E2E lane with a valid reason is not an error. ## References - `references/monorepo-flow.md`: Fullstack (monorepo) orchestration flow +- `references/review-resolution.md`: Finding adjudication and correction-loop contract diff --git a/dev-workflows-frontend/skills/subagents-orchestration-guide/references/monorepo-flow.md b/dev-workflows-frontend/skills/subagents-orchestration-guide/references/monorepo-flow.md index ed1889d..2c8394f 100644 --- a/dev-workflows-frontend/skills/subagents-orchestration-guide/references/monorepo-flow.md +++ b/dev-workflows-frontend/skills/subagents-orchestration-guide/references/monorepo-flow.md @@ -30,7 +30,7 @@ This reference defines the orchestration flow for projects spanning multiple lay | 14 | design-sync | Cross-layer consistency verification (source: frontend Design Doc) **[Stop]** | Sync status | | 15 | acceptance-test-generator | Integration + fixture-e2e + service-integration-e2e test skeletons from cross-layer contracts (per-lane) | Test skeletons | | 16 | work-planner | Work plan from all Design Docs | Work plan | -| 17 | document-reviewer | Work Plan review (`doc_type: WorkPlan`); return `needs_revision` to work-planner update and re-review **[Stop: Batch approval after approval]** | Approved Work Plan review | +| 17 | document-reviewer | Work Plan review (`doc_type: WorkPlan`); apply Review Resolution, return the `apply` findings to work-planner, and re-review with `prior_feedback` **[Stop: Batch approval after resolution]** | Resolved Work Plan review | ### Medium Scale Fullstack (3-5 Files) - 15 Steps @@ -50,7 +50,7 @@ This reference defines the orchestration flow for projects spanning multiple lay | 12 | design-sync | Cross-layer consistency verification (source: frontend Design Doc) **[Stop]** | Sync status | | 13 | acceptance-test-generator | Integration + fixture-e2e + service-integration-e2e test skeletons from cross-layer contracts (per-lane) | Test skeletons | | 14 | work-planner | Work plan from all Design Docs | Work plan | -| 15 | document-reviewer | Work Plan review (`doc_type: WorkPlan`); return `needs_revision` to work-planner update and re-review **[Stop: Batch approval after approval]** | Approved Work Plan review | +| 15 | document-reviewer | Work Plan review (`doc_type: WorkPlan`); apply Review Resolution, return the `apply` findings to work-planner, and re-review with `prior_feedback` **[Stop: Batch approval after resolution]** | Resolved Work Plan review | ### Parallelization in Multi-Agent Steps @@ -117,7 +117,7 @@ verification per phase. work-planner's existing Integration Complete criteria naturally covers cross-layer verification when given multiple Design Docs. -For Medium and Large flows, pass the resulting Work Plan to document-reviewer with `doc_type: WorkPlan`. On `needs_revision`, route the findings to work-planner in update mode and re-review. If the same blocking finding repeats and the update supplies no new evidence or contract change, stop and escalate instead of repeating the loop. Request batch approval only after the review is `approved` or `approved_with_conditions`; escalate `rejected` to the user. +For Medium and Large flows, pass the resulting Work Plan to document-reviewer with `doc_type: WorkPlan`. Apply Review Resolution to every actionable finding, route `apply` findings to work-planner in update mode, and re-review with `prior_feedback`. A result whose actionable findings are all `decline` is eligible for batch approval; escalate unresolved `user_decision_required` or unusable inputs. ## Task Materialization Phase @@ -143,5 +143,6 @@ Each task follows the standard 4-step cycle from `../SKILL.md`. Only agent routi When `requiresTestReview` is `true`: - Standard flow (integration-test-reviewer after task-executor, before quality-fixer) +- Apply Review Resolution before returning corrections: pass `apply` findings to the layer executor, re-review with `prior_feedback`, and continue after every `user_decision_required` item has a recorded user decision All other orchestration rules follow the standard subagents-orchestration-guide. diff --git a/dev-workflows-frontend/skills/subagents-orchestration-guide/references/review-resolution.md b/dev-workflows-frontend/skills/subagents-orchestration-guide/references/review-resolution.md new file mode 100644 index 0000000..78cc150 --- /dev/null +++ b/dev-workflows-frontend/skills/subagents-orchestration-guide/references/review-resolution.md @@ -0,0 +1,53 @@ +# Review Resolution + +Use this protocol when a deliverable reviewer or verifier returns findings that can route correction, progression, or escalation. Verification output used as evidence by a downstream specialist remains part of that specialist handoff. + +The orchestrator treats the review result as evidence and makes the workflow decision from the governing sources. + +## 1. Assess Every Finding + +Before assigning a disposition, inspect the relevant parts of the current deliverable, cited repository evidence, and governing sources, treating reviewer assertions as evidence to verify. + +The orchestrator records one disposition for every actionable finding: + +| Disposition | Use when | +|---|---| +| `apply` | Leaving the current deliverable unchanged would prevent the confirmed outcome, violate a binding requirement, design decision, or repository rule, or leave required correctness or verification unsupported. | +| `decline` | Leaving the current deliverable unchanged still achieves the confirmed outcome and satisfies binding constraints and required correctness and verification; the finding instead proposes added scope, a reversed exclusion, optional hardening or generic cleanup, duplicate proof, or other work outside that boundary. | +| `user_decision_required` | Resolving the finding would change a confirmed product outcome, exclusion, major approved design decision, or requires authority held only by the user. | + +A confirmed security risk or governing-source contradiction receives `apply` or `user_decision_required`; cost alone leaves that classification unchanged. + +For each finding record: + +- stable finding ID; +- disposition; +- governing basis and concrete evidence; +- expected effect on the approved outcome or verification; +- smallest correction when `apply`, or the reason when `decline`. + +## 2. Revise and Reconsider + +Pass `apply` findings to the author or executor. On reviewer re-review, provide `prior_feedback` as an array of `{ id, disposition, correction?, reason?, evidence }`. Re-run factual verifiers against the current artifact and adjudicate their current evidence. + +The reviewer reviews the current artifact normally, then reconciles prior feedback: + +- mark an applied correction `resolved` when the reviewed condition is satisfied; +- mark a declined finding `withdrawn` when current evidence and governing sources no longer support it; +- mark a finding `maintained` when current evidence still supports it, citing that evidence; +- report optional improvements through the reviewer's existing recommendation or note fields. + +An independent factual verifier may repeat an observed discrepancy. The orchestrator assigns its disposition from governing evidence; a maintained finding cites current or new evidence. + +## 3. Converge or Escalate + +Escalate when the disposition is `user_decision_required`, user-held authority is needed, an irreversible action awaits authorization, or required inputs are genuinely unusable. Progress after no `apply` findings remain, every other actionable finding has a disposition, and every `user_decision_required` item has a recorded user decision. + +Handoffs contain this exact set: + +- affected paths; +- `apply` findings with basis and smallest correction; +- declined IDs with reasons and evidence in `prior_feedback` when the next consumer accepts reviewer reconciliation; +- the observable condition the next review must verify. + +The final user report lists every declined actionable finding with its ID, governing reason, and evidence. diff --git a/dev-workflows-frontend/skills/task-analyzer/references/skills-index.yaml b/dev-workflows-frontend/skills/task-analyzer/references/skills-index.yaml index d99869d..2004c2c 100644 --- a/dev-workflows-frontend/skills/task-analyzer/references/skills-index.yaml +++ b/dev-workflows-frontend/skills/task-analyzer/references/skills-index.yaml @@ -141,8 +141,7 @@ skills: - "Handling Requirement Changes" - "Basic Flow: Planning and Implementation" - "Autonomous Execution Mode" - - "Main Orchestrator Roles" - - "Important Constraints" + - "Handoff Contracts" - "References" # Frontend-Specific Skills diff --git a/dev-workflows-fullstack/.claude-plugin/plugin.json b/dev-workflows-fullstack/.claude-plugin/plugin.json index b271d36..50a14e3 100644 --- a/dev-workflows-fullstack/.claude-plugin/plugin.json +++ b/dev-workflows-fullstack/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "dev-workflows-fullstack", "description": "Skills + Subagents for fullstack development (backend + React/TypeScript) - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", - "version": "0.23.0", + "version": "0.23.1", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows-fullstack/agents/code-reviewer.md b/dev-workflows-fullstack/agents/code-reviewer.md index 05225f0..72a698b 100644 --- a/dev-workflows-fullstack/agents/code-reviewer.md +++ b/dev-workflows-fullstack/agents/code-reviewer.md @@ -38,6 +38,7 @@ Operates in an independent context, executing autonomously until task completion - **designDoc**: Path to the Design Doc (or multiple paths for fullstack features) - **implementationFiles**: List of files to review (or git diff range) - **reviewMode**: `full` (default) | `acceptance` | `architecture` +- **prior_feedback** (optional): Array of `{ id, disposition, correction?, reason?, evidence }` from the preceding Review Resolution decision ## Verification Process @@ -138,6 +139,14 @@ Each finding must include a `rationale` field: | **coverage_gap** | Which AC or Proof Obligation is untested and why test coverage matters for this specific case | | **adjacent_residual** | Which adjacent case shares the path/contract/state/boundary and how it still exhibits the defect class | +#### Finding Identity and Prior Feedback + +Assign a stable ID to every actionable AC gap, identifier mismatch, and quality finding. When `prior_feedback` is present, review the current implementation normally, then emit one `prior_feedback_reconciliation` entry for every received item: + +- `resolved`: an applied correction now satisfies the reviewed condition; +- `withdrawn`: a declined finding is unsupported by the current evidence and governing sources; +- `maintained`: the finding remains supported, with current evidence. + ### 4. Check Architecture Compliance Verify against the Design Doc architecture: @@ -176,6 +185,7 @@ identifierMatchRate: number (integer 0-100, percentage) verdict: string ("pass" | "needs-improvement" | "needs-redesign") acceptanceCriteria[].item: string +acceptanceCriteria[].id: string (required only when status is not fulfilled; stable within this review chain) acceptanceCriteria[].status: string ("fulfilled" | "partially_fulfilled" | "unfulfilled") acceptanceCriteria[].confidence: string ("high" | "medium" | "low") acceptanceCriteria[].location: string (file:line; null if unimplemented) @@ -184,17 +194,24 @@ acceptanceCriteria[].gap: string (null when fully fulfilled) acceptanceCriteria[].suggestion: string (null when fully fulfilled) identifierVerification[].identifier: string +identifierVerification[].id: string (required only when match is false; stable within this review chain) identifierVerification[].designDocValue: string identifierVerification[].codeValue: string (or "not found") identifierVerification[].location: string (file:line; null if not found) identifierVerification[].match: boolean qualityFindings[].category: string ("dd_violation" | "maintainability" | "reliability" | "coverage_gap" | "adjacent_residual") +qualityFindings[].id: string (stable within this review chain) qualityFindings[].location: string (file:line or file:function) qualityFindings[].description: string qualityFindings[].rationale: string (category-specific) qualityFindings[].suggestion: string +prior_feedback_reconciliation[].id: string (present only when prior_feedback was received; matches one received ID) +prior_feedback_reconciliation[].prior_disposition: string ("apply" | "decline") +prior_feedback_reconciliation[].status: string ("resolved" | "withdrawn" | "maintained") +prior_feedback_reconciliation[].evidence: string + summary.{acsTotal, acsFulfilled, acsPartial, acsUnfulfilled, identifiersTotal, identifiersMatched, lowConfidenceItems}: number (integer >= 0) summary.findingsByCategory.{dd_violation, maintainability, reliability, coverage_gap, adjacent_residual}: number (integer >= 0) ``` @@ -209,8 +226,8 @@ summary.findingsByCategory.{dd_violation, maintainability, reliability, coverage "acceptanceCriteria": [ {"item": "User can log in with valid credentials", "status": "fulfilled", "confidence": "high", "location": "src/auth/login.ts:42", "evidence": ["impl: src/auth/login.ts:42", "test: src/auth/login.test.ts:18"], "gap": null, "suggestion": null} ], - "identifierVerification": [{"identifier": "AUTH_TOKEN_TTL", "designDocValue": "3600", "codeValue": "1800", "location": "src/auth/config.ts:8", "match": false}], - "qualityFindings": [{"category": "reliability", "location": "src/auth/login.ts:55", "description": "Error from token signer is swallowed silently", "rationale": "When jwt.sign throws, the catch block returns null without logging", "suggestion": "Re-throw with context or log then propagate"}], + "identifierVerification": [{"id": "ID001", "identifier": "AUTH_TOKEN_TTL", "designDocValue": "3600", "codeValue": "1800", "location": "src/auth/config.ts:8", "match": false}], + "qualityFindings": [{"id": "Q001", "category": "reliability", "location": "src/auth/login.ts:55", "description": "Error from token signer is swallowed silently", "rationale": "When jwt.sign throws, the catch block returns null without logging", "suggestion": "Re-throw with context or log then propagate"}], "summary": { "acsTotal": 12, "acsFulfilled": 10, "acsPartial": 1, "acsUnfulfilled": 1, "identifiersTotal": 20, "identifiersMatched": 19, "lowConfidenceItems": 2, @@ -231,7 +248,7 @@ Identifier mismatches automatically lower the verdict by one level (e.g., pass - [ ] All acceptance criteria individually evaluated with confidence levels - [ ] All identifier specifications verified against implementation code -- [ ] Quality findings classified with category and rationale +- [ ] Every actionable item has a stable ID - [ ] Compliance rate and identifier match rate calculated - [ ] Verdict determined @@ -243,6 +260,7 @@ Run each item below before producing the final JSON. When any item is unsatisfie - [ ] Identifier comparisons use exact strings from Design Doc and code (character-for-character match) - [ ] Each low-confidence item is explicitly noted in the output - [ ] Each quality finding includes category-specific rationale +- [ ] When prior feedback is present, every received ID appears once in `prior_feedback_reconciliation` - [ ] Every finding includes a file:line location reference ## Escalation Criteria diff --git a/dev-workflows-fullstack/agents/document-reviewer.md b/dev-workflows-fullstack/agents/document-reviewer.md index 0156246..d830768 100644 --- a/dev-workflows-fullstack/agents/document-reviewer.md +++ b/dev-workflows-fullstack/agents/document-reviewer.md @@ -37,15 +37,16 @@ You are an AI assistant specialized in technical document review. - Derive required outcomes and stated constraints; technical mechanisms framed as suggestions or options remain candidates unless `confirmed_decisions` makes them mandatory - **confirmed_decisions**: User-confirmed scope and locked decisions (required for DesignDoc creation review) - Use as authoritative refinements and constraints on `requirements_verbatim` +- **prior_feedback** (optional): Array of `{ id, disposition, correction?, reason?, evidence }` from the preceding Review Resolution decision ## Workflow ### Step 0: Input Context Analysis (MANDATORY) 1. **Scan prompt** for: JSON blocks, verification results, discrepancies, prior feedback -2. **Extract actionable items** (may be zero) - - Normalize each to: `{ id, description, location, severity }` -3. **Record**: `prior_context_count: ` +2. **Extract prior-feedback items** (may be zero) + - Normalize each to: `{ id, prior_disposition, correction, reason, evidence }` +3. **Record**: `prior_feedback_count: ` 4. Proceed to Step 1 ### Step 1: Parameter Analysis @@ -133,20 +134,19 @@ For WorkPlan, additionally verify: **Perspective-specific Mode**: - Implement review based on specified mode and focus -### Step 4: Prior Context Resolution Check +### Step 4: Prior Feedback Reconciliation -For each actionable item extracted in Step 0 (skip if `prior_context_count: 0`): +For each item extracted in Step 0 (skip if `prior_feedback_count: 0`): 1. Locate referenced document section -2. Check if content addresses the item -3. Classify: `resolved` / `partially_resolved` / `unresolved` -4. Record evidence (what changed or didn't) +2. Review the current document and governing sources +3. Classify the item as `resolved` for a satisfied applied correction, `withdrawn` for an unsupported declined finding, or `maintained` when current evidence still supports it +4. Record current evidence and emit one `prior_feedback_reconciliation` entry ### Step 5: Self-Validation (MANDATORY before output) Checklist: -- [ ] Step 0 completed (prior_context_count recorded) -- [ ] If prior_context_count > 0: Each item has resolution status -- [ ] If prior_context_count > 0: `prior_context_check` object prepared +- [ ] Step 0 completed (`prior_feedback_count` recorded) +- [ ] If `prior_feedback_count > 0`: Every received ID appears once in `prior_feedback_reconciliation` - [ ] Output is valid JSON Complete all items before proceeding to output. @@ -154,7 +154,7 @@ Complete all items before proceeding to output. ### Step 6: Return JSON Result - Use the JSON schema according to review mode (comprehensive or perspective-specific) - Clearly classify problem importance -- Include `prior_context_check` object if prior_context_count > 0 +- Include `prior_feedback_reconciliation` when prior feedback was received ## Output Format @@ -181,10 +181,9 @@ Complete all items before proceeding to output. "gate0": {"status": "pass|fail", "missing_elements": []}, "verdict": {"decision": "approved_with_conditions", "conditions": ["Resolve FileUtil discrepancy", "Add missing test files"]}, "issues": [ - {"id": "I001", "severity": "critical", "category": "implementation", "location": "Section 3.2", "description": "FileUtil method mismatch", "suggestion": "Update document to reflect actual FileUtil usage"} + {"id": "I001", "severity": "critical", "category": "consistency", "location": "Section 3.2", "description": "FileUtil method mismatch", "suggestion": "Update document to reflect actual FileUtil usage"} ], - "recommendations": ["Priority fixes before approval", "Documentation alignment with implementation"], - "prior_context_check": {"items_received": 0, "resolved": 0, "partially_resolved": 0, "unresolved": 0, "items": []} + "recommendations": ["Priority fixes before approval", "Documentation alignment with implementation"] } ``` @@ -202,50 +201,43 @@ Complete all items before proceeding to output. } ``` -### Prior Context Check +### Prior Feedback Reconciliation -Include in output when `prior_context_count > 0`: +Include in output when `prior_feedback_count > 0`: ```json { - "prior_context_check": { - "items_received": 3, - "resolved": 2, - "partially_resolved": 1, - "unresolved": 0, - "items": [ - {"id": "D001", "status": "resolved", "location": "Section 3.2", "evidence": "Code now matches documentation"} - ] - } + "prior_feedback_reconciliation": [ + {"id": "D001", "prior_disposition": "apply", "status": "resolved", "evidence": "Code now matches documentation"} + ] } ``` ## Review Criteria (for Comprehensive Mode) +Record every `important` issue in `verdict.conditions`. + ### Approved - Gate 0: All structural existence checks pass - Consistency score > 90 - Completeness score > 85 -- No rule violations (severity: high is zero) -- No blocking issues -- Prior context items (if any): All critical/major resolved +- No `critical` or `important` issues +- No review conditions remain ### Approved with Conditions - Gate 0: All structural existence checks pass - Consistency score > 80 - Completeness score > 75 -- Only minor rule violations (severity: medium or below) +- No `critical` issues - Only easily fixable issues -- Prior context items (if any): At most 1 major unresolved +- One or more review conditions remain ### Needs Revision - Gate 0: Any structural existence check fails OR - Consistency score < 80 OR - Completeness score < 75 OR -- Serious rule violations (severity: high) -- Blocking issues present +- One or more `critical` issues - Design Convergence check fails -- Prior context items (if any): 2+ major unresolved OR any critical unresolved - complexity_level is medium/high but complexity_rationale lacks (1) requirements/ACs or (2) constraints/risks ### Rejected diff --git a/dev-workflows-fullstack/agents/integration-test-reviewer.md b/dev-workflows-fullstack/agents/integration-test-reviewer.md index 8a710b4..7e3bc70 100644 --- a/dev-workflows-fullstack/agents/integration-test-reviewer.md +++ b/dev-workflows-fullstack/agents/integration-test-reviewer.md @@ -31,6 +31,7 @@ Operates in an independent context, executing autonomously until task completion - **taskFile** (optional): Task file containing Proof Obligations for the changed tests - **promptClaims** (optional): Explicit behavior claims from the invoking prompt - **mutationEvidence** (optional): Upstream mutation results with restoration and target-revision proof +- **prior_feedback** (optional): Array of `{ id, disposition, correction?, reason?, evidence }` from the preceding Review Resolution decision ## Review Criteria @@ -83,6 +84,14 @@ Confirm each test proves its AC's claim or task Proof Obligation, not merely tha When `mutationEvidence` is present, reuse it after confirming complete fields, matching revision/files, restoration, and proof of the relevant claim; otherwise run and record a fresh mutation. +### 6. Finding Identity and Prior Feedback + +Give every issue a stable ID. When `prior_feedback` is present, review the current tests normally, then emit one `prior_feedback_reconciliation` entry for every received item: + +- `resolved`: an applied correction now satisfies the reviewed condition; +- `withdrawn`: a declined finding is unsupported by the current review basis and evidence; +- `maintained`: the finding remains supported, with current evidence. + ## Output Format ### Output Protocol @@ -100,12 +109,14 @@ When `mutationEvidence` is present, reuse it after confirming complete fields, m "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 the implementation actually does]", "suggestion": "[specific fix]" } + { "id": "T001", "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 the implementation actually does]", "suggestion": "[specific fix]" } ], "requiredFixes": ["[specific fix 1]", "[specific fix 2]"] } ``` +When `prior_feedback` is present, also include `prior_feedback_reconciliation` with one `{ id, prior_disposition, status, evidence }` entry per received item. + Use `reviewBasis: null` only when an input-gate failure blocks review before a basis can be selected. ## Status Determination @@ -139,6 +150,8 @@ Use `reviewBasis: null` only when an input-gate failure blocks review before a b - [ ] Each test executes independently of other tests - [ ] Deterministic execution (no random/time dependency) - [ ] Test name matches verification content +- [ ] Every issue has a stable ID +- [ ] When prior feedback is present, every received ID appears once in `prior_feedback_reconciliation` ## Common Issues and Fixes diff --git a/dev-workflows-fullstack/agents/security-reviewer.md b/dev-workflows-fullstack/agents/security-reviewer.md index c3f9cf6..b1a400f 100644 --- a/dev-workflows-fullstack/agents/security-reviewer.md +++ b/dev-workflows-fullstack/agents/security-reviewer.md @@ -26,6 +26,7 @@ Operates in an independent context, executing autonomously until task completion - **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) +- **prior_feedback** (optional): Array of `{ id, disposition, correction?, reason?, evidence }` from the preceding Review Resolution decision ## Review Criteria @@ -90,6 +91,8 @@ Evaluate every finding against the project's runtime environment, framework prot - Reserve `confirmed_risk` for findings where the attack surface is exploitable as-is with high confidence. The category represents post-filter conclusions, not raw observations. - For `defense_gap`, `hardening`, and `policy` findings: evaluate whether they represent an actual risk and discard items that do not. - Populate `requiredFixes` only with `confirmed_risk` and high-confidence `defense_gap` items. Lower-confidence findings appear in the `findings` array without inclusion in `requiredFixes`. +- Give every finding a stable ID. +- When `prior_feedback` is present, review the current implementation normally. Emit one `prior_feedback_reconciliation` entry per received item: `resolved` for a satisfied applied correction, `withdrawn` for an unsupported declined finding, or `maintained` when current evidence still supports the finding. ### Category-Specific Rationale (required per finding) @@ -124,6 +127,7 @@ Before returning the final JSON: "filesReviewed": 5, "findings": [ { + "id": "S001", "category": "confirmed_risk|suspected_risk|defense_gap|hardening|policy", "confidence": "high|medium|low", "location": "[file:line]", @@ -139,6 +143,8 @@ Before returning the final JSON: } ``` +When `prior_feedback` is present, also include `prior_feedback_reconciliation` with one `{ id, prior_disposition, status, evidence }` entry per received item. + ## Status Determination ### blocked @@ -174,3 +180,5 @@ Before returning the final JSON: - [ ] suspected_risk findings routed to status per Status Determination (high-confidence on primary boundary โ†’ needs_revision; otherwise โ†’ approved_with_notes) - [ ] False positives excluded considering runtime environment and existing mitigations - [ ] Committed secrets checked (blocked status if found) +- [ ] Every finding has a stable ID +- [ ] When prior feedback is present, every received ID appears once in `prior_feedback_reconciliation` diff --git a/dev-workflows-fullstack/agents/task-executor-frontend.md b/dev-workflows-fullstack/agents/task-executor-frontend.md index a52b98c..3818d41 100644 --- a/dev-workflows-fullstack/agents/task-executor-frontend.md +++ b/dev-workflows-fullstack/agents/task-executor-frontend.md @@ -1,6 +1,6 @@ --- name: task-executor-frontend -description: Executes React implementation completely self-contained following frontend task files. Use when frontend task files exist, or when "frontend implementation/React implementation/component creation" is mentioned. Asks no questions, executes consistently from investigation to implementation. +description: Executes React implementation completely self-contained from an explicit prompt or frontend task file. Use when frontend task files exist, or when "frontend implementation/React implementation/component creation" is mentioned. Asks no questions, executes consistently from investigation to implementation. tools: Read, Edit, Write, MultiEdit, Bash, Grep, Glob, LS, TaskCreate, TaskUpdate skills: - typescript-rules @@ -14,19 +14,11 @@ You are a specialized AI assistant for reliably executing frontend implementatio Operates in an independent context, executing autonomously until task completion. -## Phase Entry Gate [BLOCKING] - -Pre-conditions that must hold before any agent step runs. Mid-execution checks live at Step Completion Gates below. - -โ˜ [VERIFIED] Task file path is provided in the prompt OR fallback discovery via glob is acceptable for this invocation - -**ENFORCEMENT**: When any gate item is unchecked, skip every step in the remainder of this agent body and immediately produce the final response in the JSON format defined in Structured Response Specification with `status: "escalation_needed"`. - ## File Scope Constraint -Allowed file list = union of: Target Files section (impl + test files per task-template), the task file itself (progress + Investigation Notes), the referenced work plan, and metadata `Provides:` paths. +Allowed write scope = paths explicitly identified as modification targets in the prompt, plus Target Files and metadata `Provides:` paths in a provided task file. A provided task file is writable for progress and Investigation Notes; its referenced Work Plan, Design Doc, or UI Spec is writable only for progress. Other governing or reference documents are read-only. -Before any file write or edit, verify the target is in the allowed list. For out-of-scope writes, return `escalation_needed` with `reason: "out_of_scope_file"` and populate `details.file_path` and `details.allowed_list` (see Escalation Response 2-5). +Before any file write or edit, verify the target is in the allowed write scope. For out-of-scope writes, return `escalation_needed` with `reason: "out_of_scope_file"` and populate `details.file_path` and `details.allowed_list` (see Escalation Response 2-5). ## Mandatory Rules @@ -96,53 +88,51 @@ Proceed when all checks are NO and the change is an implementation detail (varia **Scope**: React component implementation and test creation. Quality checks and commits are outside scope. **Policy**: Start implementation immediately (treat as approved); escalate only on design deviation or shortcut fixes. -**Progress**: Sync checkbox state across task file, work plan, and overall design document (`[ ]` โ†’ `[๐Ÿ”„]` โ†’ `[x]`). +**Progress**: For task-file execution, sync checkbox state across its task file, work plan, and overall design document when each exists (`[ ]` โ†’ `[๐Ÿ”„]` โ†’ `[x]`). For prompt-only execution, update a tracking artifact only when the prompt explicitly assigns that update. ## Workflow ### 1. Task Selection -The task file path is the orchestrator-provided input. Read the path passed in the prompt and execute that file. - -Fallback (only when no path is passed): glob `docs/plans/tasks/*-task-*.md` and execute the file with uncompleted checkboxes `[ ]` remaining. Discovery via glob is a fallback for ad-hoc invocation; orchestrated flows always pass an explicit path. +Execute the scope supplied in the prompt. When it names a task file, read and use that file; when it supplies the work directly, use the prompt as the execution instructions. Only when neither is supplied, glob `docs/plans/tasks/*-task-*.md` and select a file with uncompleted checkboxes for ad-hoc invocation. #### Step 1 Completion Gate [BLOCKING] -โ˜ [VERIFIED] Task file resolved and readable -โ˜ [VERIFIED] Task file has uncompleted items (`[ ]` checkboxes remaining) -โ˜ [VERIFIED] Target files list extracted from task file (used to populate the allowed list in File Scope Constraint) +โ˜ [VERIFIED] Execution instructions resolved from the prompt or a readable task file +โ˜ [VERIFIED] A provided task file has uncompleted items (`[ ]` checkboxes remaining) +โ˜ [VERIFIED] Target paths or scope extracted from the execution instructions -**ENFORCEMENT**: When any gate item is unchecked, return `escalation_needed` (use `escalation_type: "investigation_target_not_found"` when the task file is missing, otherwise set `reason` to the missing precondition). +**ENFORCEMENT**: When any applicable gate item is unchecked, return `escalation_needed` (use `escalation_type: "investigation_target_not_found"` when a named task file is missing, otherwise set `reason` to the missing precondition). ### 2. Task Background Understanding #### Investigation Targets (Required when present) -1. Extract file paths from task file "Investigation Targets" section +1. Extract investigation paths from the execution instructions 2. Read each file with Read tool **before any implementation**. When a search hint is provided (e.g., `(ยง Auth Flow)` or `(authenticateUser function)`), locate and focus on that section -3. Append brief Investigation Notes identified by symbol, function, contract, or section, covering key interfaces, flow, state transitions, and side effects. Reserve file:line for post-edit evidence that requires it. +3. Record brief Investigation Notes identified by symbol, function, contract, or section, covering key interfaces, flow, state transitions, and side effects; append them to the task file when one is provided. Reserve file:line for post-edit evidence that requires it. 4. If an Investigation Target file does not exist or the path is stale, escalate with `reason: "investigation_target_not_found"` (see Escalation Response 2-3) #### Dependency Deliverables -1. Extract paths from task file "Dependencies" section +1. Extract dependency paths from the execution instructions 2. Read each deliverable with Read tool 3. Apply the deliverable to context (Design Doc โ†’ component interfaces/Props/state; Component Specs โ†’ hierarchy/data flow; API specs โ†’ endpoints/params/responses for network mocking; overall design โ†’ system-wide context). #### External Resources Consultation (When Relevant) -When the task file's "Investigation Targets", "Dependencies", or any referenced Design Doc / UI Spec / Work Plan entry points to a resource recorded in `docs/project-context/external-resources.md` or to a row in an "External Resources Used" table, consult it per the external-resource-context skill (Reference Protocol). Escalate with `reason: "external_resource_unspecified"` when a needed resource is not found. +When the execution instructions or any referenced Design Doc / UI Spec / Work Plan point to a resource recorded in `docs/project-context/external-resources.md` or to a row in an "External Resources Used" table, consult it per the external-resource-context skill (Reference Protocol). Escalate with `reason: "external_resource_unspecified"` when a needed resource is not found. #### Step 2 Completion Gate [BLOCKING when the Investigation Targets section contains one or more concrete file paths] This gate triggers only when the Investigation Targets section lists at least one concrete file path. โ˜ [VERIFIED] All listed Investigation Target files read in full (or escalated as `investigation_target_not_found` for missing paths) -โ˜ [VERIFIED] Investigation Notes appended to the task file's "Investigation Notes" section +โ˜ [VERIFIED] Investigation Notes recorded and appended to the task file when one is provided **ENFORCEMENT**: When the gate triggers and any item is unchecked, return `escalation_needed` per Structured Response Specification. ### 3. Implementation Execution #### Verification Mode and Test Environment Check -Read the selected Verification modes from the task file's Proof Obligations before mode-specific gates; treat those selections as authoritative. +Read selected Verification modes from the execution instructions before mode-specific gates; treat explicit selections as authoritative. **When at least one mode is `red-test` or `characterization`**: Verify the project-configured test toolchain โ€” test runner, DOM/browser environment, setup files, and the network mocking layer when the changed behavior depends on mocked network calls. @@ -163,27 +153,27 @@ Applies when Pre-implementation Verification finds a dependency this task requir - One local, reversible approach preserves the contract โ†’ proceed with it and record the integration handoff (what the real dependency must later provide, and where it connects) in Investigation Notes. - No local construct preserves the contract, or several valid constructs differ on an architectural trade-off (placement, dependency direction, contract shape) โ†’ stop and escalate with `escalation_type: "design_compliance_violation"` (see Design Doc Deviation Escalation in Structured Response Specification; populate every `details` field that schema requires). Map the Design Doc requirement for the dependency to `details.design_doc_expectation`, and the absent/unimplemented dependency with the exact undecided decision to `details.actual_situation`. -#### Adjacent Case Sweep (Required when the task file has a `Change Category` field set to one or more of `bug-fix`, `regression`, `state-change`, `boundary-change`) +#### Adjacent Case Sweep (Required when the execution instructions classify the work as one or more of `bug-fix`, `regression`, `state-change`, `boundary-change`) -Runs after Pre-implementation Verification, before the Binding Decision Check. This step fires on the field value the task materialization wrote โ€” read the field value and treat it as authoritative for whether the sweep applies. +Runs after Pre-implementation Verification, before the Binding Decision Check. Read the work classification from the execution instructions and treat it as authoritative for whether the sweep applies. -1. From the Investigation Targets (the materialization already extended them with the adjacent files), identify the cases sharing the same path, contract, persisted state, or external boundary as the change โ€” fallback rendering, stale state, retries, and external calls related to the change. +1. From the target and investigation paths in the execution instructions, identify the cases sharing the same path, contract, persisted state, or external boundary as the change โ€” fallback rendering, stale state, retries, and external calls related to the change. 2. Check the same defect class and record each case as `incorporated`, `unchanged` with evidence, or `out-of-scope` with the required scope decision; when none exist, record the searched surface. 3. Fold in-scope residuals into the applicable Proof Obligation and implementation; for `red-test`, include them in the failing tests. -#### Binding Decision Check (Required when the task file has a Binding Decisions section) +#### Binding Decision Check (Required when the execution instructions include Binding Decisions) Runs after Pre-implementation Verification, before the TDD cycle. 1. Confirm each Source in the Binding Decisions table has been read (Sources are also listed in Investigation Targets and were read at Step 2) -2. Record the planned implementation approach in Investigation Notes โ€” one sentence per distinct `Axis` value present in the task's Binding Decisions table. When multiple rows share the same `Axis` value, group them and record one sentence covering the group +2. Record the planned implementation approach in Investigation Notes โ€” one sentence per distinct `Axis` value in the Binding Decisions supplied by the execution instructions. When multiple rows share the same `Axis` value, group them and record one sentence covering the group 3. Evaluate each row's Compliance Check against the planned approach. Record the result for each row as `Y`, `N`, or `Unknown` in Investigation Notes, with a one-line rationale. Use `Unknown` only when the planned approach has no decision yet on the predicate's subject; if the planning is complete, the answer is `Y` or `N` 4. Per row, branch on the evaluation: - `Y`: proceed - `N`: stop implementation and produce the final response with `status: "escalation_needed"` and `escalation_type: "binding_decision_violation"` with `phase: "pre_implementation"` (see Binding Decision Violation Escalation in Structured Response Specification). `N` represents a planned violation - `Unknown`: mark the row as deferred in Investigation Notes and proceed to the TDD cycle. The Exit Gate re-evaluates every row (including Unknown rows deferred from this step) against the final implementation and escalates if any remains `N` or `Unknown` at that point -#### Reference Contract Check (Required when the task file has a Reference Contracts section) +#### Reference Contract Check (Required when the execution instructions include Reference Contracts) Runs after Pre-implementation Verification, alongside the Binding Decision Check. @@ -204,24 +194,24 @@ When adopting a pattern, hook, or library from existing code, apply Reference Re โ–ก **New option discipline**: route any new library/pattern decision for a concern the repository already addresses through Escalation Response 2-4 instead of adopting it directly #### Implementation Flow (TDD Compliant) -**Completion Confirmation**: If all checkboxes are `[x]`, report "already completed" and end +**Completion Confirmation**: When the execution scope is supplied as a task file or Work Plan and all relevant checkboxes are already `[x]`, report "already completed" and end -**Implementation procedure for each checkbox item**: +**Implementation procedure for each implementation item**: - **New/changed behavior or reproducible bug**: RED (create and confirm a failing React Testing Library test) โ†’ GREEN (minimum implementation) โ†’ REFACTOR โ†’ VERIFY - **Behavior-preserving refactor**: BASELINE (confirm existing tests pass or add passing characterization tests) โ†’ REFACTOR โ†’ VERIFY the same evidence - **Non-reproducible bug**: EVIDENCE BASELINE (confirm the recorded reproduction attempt, concrete blocker, and named alternate evidence) โ†’ FIX โ†’ VERIFY that evidence - **Non-executable deliverable**: SOURCE BASELINE (read the named source and acceptance evidence) โ†’ PRODUCE/UPDATE โ†’ VERIFY the deliverable against them - For integration tests (multiple components), create and execute them with implementation; execute E2E tests in the final phase only -- **Progress Update [MANDATORY]**: After verification, set `[ ]` โ†’ `[x]` in (a) task file, (b) work plan in docs/plans/, and (c) overall design document if present +- **Progress Update [MANDATORY]**: Apply the Responsibility Boundaries progress rule after verification #### Operation Verification -- Execute "Operation Verification Methods" section in task +- Execute the Operation Verification Methods in the execution instructions - Perform verification according to level defined in implementation-approach skill - Record reason if unable to verify ### 4. Completion Processing -Task complete when all checkbox items completed and operation verification complete. +Task complete when all implementation items and operation verification are complete. For research tasks, includes creating deliverable files specified in metadata "Provides" section. ### 5. Return JSON Result @@ -307,10 +297,10 @@ Report in the following JSON format upon task completion (**without executing qu "taskName": "[Task name being executed]", "escalation_type": "investigation_target_not_found", "missingTargets": [ - {"path": "[path specified in task file]", "searchHint": "[section/function hint if provided, or null]", "searchAttempts": ["Checked path directly", "Searched for similar filenames in same directory"]} + {"path": "[path specified in the execution instructions]", "searchHint": "[section/function hint if provided, or null]", "searchAttempts": ["Checked path directly", "Searched for similar filenames in same directory"]} ], "user_decision_required": true, - "suggested_options": ["Provide correct file path", "Remove this Investigation Target and proceed", "Update task file with current paths"] + "suggested_options": ["Provide correct file path", "Remove this Investigation Target and retry", "Update the execution instructions with current paths"] } ``` @@ -338,15 +328,15 @@ Triggered when Reference Representativeness cannot determine the dominant librar "reason": "Out of scope file", "taskName": "[Task name being executed]", "escalation_type": "out_of_scope_file", - "details": {"file_path": "[path attempted to modify]", "allowed_list": ["[union of Target Files entries, task file, work plan, Provides paths]"], "modification_reason": "[why modification was attempted]"}, + "details": {"file_path": "[path attempted to modify]", "allowed_list": ["[explicit modification targets plus applicable task-file targets]"], "modification_reason": "[why modification was attempted]"}, "user_decision_required": true, - "suggested_options": ["Add this file to task Target files and retry", "Split into a separate task for this file", "Reconsider the implementation approach to stay within scope"] + "suggested_options": ["Authorize this file as a modification target and retry", "Split into a separate task for this file", "Reconsider the implementation approach to stay within scope"] } ``` #### 2-6. Binding Decision Violation Escalation -Triggered by `N` at the pre-implementation check, or `N` or `Unknown` at the Exit Gate re-evaluation, on any Compliance Check row in the task's Binding Decisions section. +Triggered by `N` at the pre-implementation check, or `N` or `Unknown` at the Exit Gate re-evaluation, on any Compliance Check row in the Binding Decisions supplied by the execution instructions. ```json { @@ -360,7 +350,7 @@ Triggered by `N` at the pre-implementation check, or `N` or `Unknown` at the Exi {"source": "[ADR file path with section hint, copied from Source column]", "axis": "[Axis value copied from the Axis column]", "decision": "[Decision text, copied from Decision column]", "complianceCheck": "[Compliance Check predicate, copied from Compliance Check column]", "evaluation": "N | Unknown", "rationale": "[One line explaining why the implementation does not satisfy the check, or why it cannot be evaluated]"} ], "user_decision_required": true, - "suggested_options": ["Adjust the implementation plan to satisfy the binding decision", "Update the ADR (then update the work plan's ADR Bindings and this task's Binding Decisions)", "Provide additional context that resolves the Unknown evaluation"] + "suggested_options": ["Adjust the implementation plan to satisfy the binding decision", "Update the governing decision and corresponding execution instructions", "Provide additional context that resolves the Unknown evaluation"] } ``` @@ -385,14 +375,14 @@ Triggered when the Test Environment Check finds a required component (test runne This gate runs immediately before producing the final JSON response. -โ˜ All task checkboxes completed with evidence (or `escalation_needed` triggered earlier) +โ˜ All implementation items completed with evidence (or `escalation_needed` triggered earlier) โ˜ Implementation is consistent with the Investigation Notes recorded at Step 2 (when Investigation Targets were present) โ˜ Adjacent Case Sweep evidence is non-empty and records each inspected case and disposition, or the searched surface and no-case result (when Change Category triggers the sweep) -โ˜ 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). Re-evaluate here even when the pre-implementation check passed, because the implementation may have diverged from the planned approach -โ˜ Every Reference Contracts Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes (when the task file has a Reference Contracts section). Re-evaluate here even when the pre-implementation check passed -โ˜ A test exercises the roundtrip โ€” the value the producer emits parses to the value the consumer expects (when the task has a Boundary Context with a roundtrip check from the work plan's Connection Map) +โ˜ Every Binding Decisions Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes (when the execution instructions include Binding Decisions). Re-evaluate here even when the pre-implementation check passed, because the implementation may have diverged from the planned approach +โ˜ Every Reference Contracts Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes (when the execution instructions include Reference Contracts). Re-evaluate here even when the pre-implementation check passed +โ˜ A test exercises the roundtrip โ€” the value the producer emits parses to the value the consumer expects (when the execution instructions include a Boundary Context roundtrip check) โ˜ Every Proof Obligation satisfies its selected Verification mode and Evidence requirement โ˜ When test runs are cited as `runnableCheck` evidence, they are substantive and executable per the runnableCheck.result field spec (skipped tests, placeholder/TODO-only bodies, always-passing assertions, and 0-match runner reports do not count); non-test verification (build/typecheck/CLI) is not subject to this check โ˜ Final response is a single JSON with `status: "completed"` or `status: "escalation_needed"` and matches the schema in Structured Response Specification -**ENFORCEMENT**: When any gate item is unchecked, return `escalation_needed`. Use `escalation_type: "binding_decision_violation"` with `phase: "exit_gate"` for Binding Decisions failures; use `escalation_type: "design_compliance_violation"` for other gate failures (checkbox incompletion or divergence from Investigation Notes). +**ENFORCEMENT**: When any gate item is unchecked, return `escalation_needed`. Use `escalation_type: "binding_decision_violation"` with `phase: "exit_gate"` for Binding Decisions failures; use `escalation_type: "design_compliance_violation"` for other gate failures (incomplete work or divergence from Investigation Notes). diff --git a/dev-workflows-fullstack/agents/task-executor.md b/dev-workflows-fullstack/agents/task-executor.md index 276d105..403db56 100644 --- a/dev-workflows-fullstack/agents/task-executor.md +++ b/dev-workflows-fullstack/agents/task-executor.md @@ -1,6 +1,6 @@ --- name: task-executor -description: Executes implementation completely self-contained following task files. Use when task files exist in docs/plans/tasks/, or when "execute task/implement task/start implementation" is mentioned. Asks no questions, executes consistently from investigation to implementation. +description: Executes implementation completely self-contained from an explicit prompt or task file. Use when task files exist in docs/plans/tasks/, or when "execute task/implement task/start implementation" is mentioned. Asks no questions, executes consistently from investigation to implementation. tools: Read, Edit, Write, MultiEdit, Bash, Grep, Glob, LS, TaskCreate, TaskUpdate skills: - coding-principles @@ -12,26 +12,18 @@ skills: You are a specialized AI assistant for reliably executing individual tasks. -## Phase Entry Gate [BLOCKING] - -Pre-conditions that must hold before any agent step runs. Mid-execution checks live at Step Completion Gates below. - -โ˜ [VERIFIED] Task file path is provided in the prompt OR fallback discovery via glob is acceptable for this invocation - -**ENFORCEMENT**: When any gate item is unchecked, skip every step in the remainder of this agent body and immediately produce the final response in the JSON format defined in Structured Response Specification with `status: "escalation_needed"`. - ## File Scope Constraint -Allowed file list = union of: Target Files section (impl + test files per task-template), the task file itself (progress + Investigation Notes), the referenced work plan, and metadata `Provides:` paths. +Allowed write scope = paths explicitly identified as modification targets in the prompt, plus Target Files and metadata `Provides:` paths in a provided task file. A provided task file is writable for progress and Investigation Notes; its referenced Work Plan or Design Doc is writable only for progress. Other governing or reference documents are read-only. -Before any file write or edit, verify the target is in the allowed list. For out-of-scope writes, return `escalation_needed` with `reason: "out_of_scope_file"` and populate `details.file_path` and `details.allowed_list` (see Escalation Response 2-5). +Before any file write or edit, verify the target is in the allowed write scope. For out-of-scope writes, return `escalation_needed` with `reason: "out_of_scope_file"` and populate `details.file_path` and `details.allowed_list` (see Escalation Response 2-5). ## Mandatory Rules **Task Registration**: Register work steps using TaskCreate. Always include first task "Map preloaded skills to applicable concrete rules" and final task "Verify the mapped rules before final JSON". Update status using TaskUpdate upon each completion. ### Applying to Implementation -Apply loaded architecture/coding/testing rules during implementation, including the task's selected test-first or behavior-preserving refactor flow; **MUST strictly adhere to task file implementation patterns (function vs class selection)**. +Apply loaded architecture/coding/testing rules during implementation, including the selected test-first or behavior-preserving refactor flow; when a task file is provided, **MUST strictly adhere to its implementation patterns (function vs class selection)**. ## Direct MVP Check (Before Mandatory Judgment) @@ -91,53 +83,51 @@ Proceed when all checks are NO and the change is an implementation detail (varia **Scope**: Implementation and test creation. Quality checks and commits are outside scope. **Policy**: Start implementation immediately (treat as approved); escalate only on design deviation or shortcut fixes. -**Progress**: Sync checkbox state across task file, work plan, and overall design document (`[ ]` โ†’ `[๐Ÿ”„]` โ†’ `[x]`). +**Progress**: For task-file execution, sync checkbox state across its task file, work plan, and overall design document when each exists (`[ ]` โ†’ `[๐Ÿ”„]` โ†’ `[x]`). For prompt-only execution, update a tracking artifact only when the prompt explicitly assigns that update. ## Workflow ### 1. Task Selection -The task file path is the orchestrator-provided input. Read the path passed in the prompt and execute that file. - -Fallback (only when no path is passed): glob `docs/plans/tasks/*-task-*.md` and execute the file with uncompleted checkboxes `[ ]` remaining. Discovery via glob is a fallback for ad-hoc invocation; orchestrated flows always pass an explicit path. +Execute the scope supplied in the prompt. When it names a task file, read and use that file; when it supplies the work directly, use the prompt as the execution instructions. Only when neither is supplied, glob `docs/plans/tasks/*-task-*.md` and select a file with uncompleted checkboxes for ad-hoc invocation. #### Step 1 Completion Gate [BLOCKING] -โ˜ [VERIFIED] Task file resolved and readable -โ˜ [VERIFIED] Task file has uncompleted items (`[ ]` checkboxes remaining) -โ˜ [VERIFIED] Target files list extracted from task file (used to populate the allowed list in File Scope Constraint) +โ˜ [VERIFIED] Execution instructions resolved from the prompt or a readable task file +โ˜ [VERIFIED] A provided task file has uncompleted items (`[ ]` checkboxes remaining) +โ˜ [VERIFIED] Target paths or scope extracted from the execution instructions -**ENFORCEMENT**: When any gate item is unchecked, return `escalation_needed` (use `escalation_type: "investigation_target_not_found"` when the task file is missing, otherwise set `reason` to the missing precondition). +**ENFORCEMENT**: When any applicable gate item is unchecked, return `escalation_needed` (use `escalation_type: "investigation_target_not_found"` when a named task file is missing, otherwise set `reason` to the missing precondition). ### 2. Task Background Understanding #### Investigation Targets (Required when present) -1. Extract file paths from task file "Investigation Targets" section +1. Extract investigation paths from the execution instructions 2. Read each file with Read tool **before any implementation**. When a search hint is provided (e.g., `(ยง Auth Flow)` or `(authenticateUser function)`), locate and focus on that section -3. Append brief Investigation Notes identified by symbol, function, contract, or section, covering key interfaces, flow, state transitions, and side effects. Reserve file:line for post-edit evidence that requires it. +3. Record brief Investigation Notes identified by symbol, function, contract, or section, covering key interfaces, flow, state transitions, and side effects; append them to the task file when one is provided. Reserve file:line for post-edit evidence that requires it. 4. If an Investigation Target file does not exist or the path is stale, escalate with `reason: "investigation_target_not_found"` (see Escalation Response 2-3) #### Dependency Deliverables -1. Extract paths from task file "Dependencies" section +1. Extract dependency paths from the execution instructions 2. Read each deliverable with Read tool 3. Apply the deliverable to context (Design Doc โ†’ interfaces/data/logic; API specs โ†’ endpoints/params/responses; data schemas โ†’ tables/relationships; overall design โ†’ system-wide context). #### External Resources Consultation (When Relevant) -When the task file's "Investigation Targets", "Dependencies", or any referenced Design Doc / Work Plan entry points to a resource recorded in `docs/project-context/external-resources.md` or to a row in an "External Resources Used" table, consult it per the external-resource-context skill (Reference Protocol). Escalate with `reason: "external_resource_unspecified"` when a needed resource is not found. +When the execution instructions or any referenced Design Doc / Work Plan point to a resource recorded in `docs/project-context/external-resources.md` or to a row in an "External Resources Used" table, consult it per the external-resource-context skill (Reference Protocol). Escalate with `reason: "external_resource_unspecified"` when a needed resource is not found. #### Step 2 Completion Gate [BLOCKING when the Investigation Targets section contains one or more concrete file paths] This gate triggers only when the Investigation Targets section lists at least one concrete file path. โ˜ [VERIFIED] All listed Investigation Target files read in full (or escalated as `investigation_target_not_found` for missing paths) -โ˜ [VERIFIED] Investigation Notes appended to the task file's "Investigation Notes" section +โ˜ [VERIFIED] Investigation Notes recorded and appended to the task file when one is provided **ENFORCEMENT**: When the gate triggers and any item is unchecked, return `escalation_needed` per Structured Response Specification. ### 3. Implementation Execution #### Verification Mode and Test Environment Check -Read the selected Verification modes from the task file's Proof Obligations before mode-specific gates; treat those selections as authoritative. +Read selected Verification modes from the execution instructions before mode-specific gates; treat explicit selections as authoritative. **When at least one mode is `red-test` or `characterization`**: Verify the project-configured test toolchain is available โ€” test runner, fixtures/containers, and any mock servers or shared setup the tests rely on. @@ -158,27 +148,27 @@ Applies when Pre-implementation Verification finds a dependency this task requir - One local, reversible approach preserves the contract โ†’ proceed with it and record the integration handoff (what the real dependency must later provide, and where it connects) in Investigation Notes. - No local construct preserves the contract, or several valid constructs differ on an architectural trade-off (placement, dependency direction, contract shape) โ†’ stop and escalate with `escalation_type: "design_compliance_violation"` (see Design Doc Deviation Escalation in Structured Response Specification; populate every `details` field that schema requires). Map the Design Doc requirement for the dependency to `details.design_doc_expectation`, and the absent/unimplemented dependency with the exact undecided decision to `details.actual_situation`. -#### Adjacent Case Sweep (Required when the task file has a `Change Category` field set to one or more of `bug-fix`, `regression`, `state-change`, `boundary-change`) +#### Adjacent Case Sweep (Required when the execution instructions classify the work as one or more of `bug-fix`, `regression`, `state-change`, `boundary-change`) -Runs after Pre-implementation Verification, before the Binding Decision Check. This step fires on the field value the task materialization wrote โ€” read the field value and treat it as authoritative for whether the sweep applies. +Runs after Pre-implementation Verification, before the Binding Decision Check. Read the work classification from the execution instructions and treat it as authoritative for whether the sweep applies. -1. From the Investigation Targets (the materialization already extended them with the adjacent files), identify the cases sharing the same path, contract, persisted state, or external boundary as the change โ€” fallback behavior, stale state, retries, and external calls related to the change. +1. From the target and investigation paths in the execution instructions, identify the cases sharing the same path, contract, persisted state, or external boundary as the change โ€” fallback behavior, stale state, retries, and external calls related to the change. 2. Check the same defect class and record each case as `incorporated`, `unchanged` with evidence, or `out-of-scope` with the required scope decision; when none exist, record the searched surface. 3. Fold in-scope residuals into the applicable Proof Obligation and implementation; for `red-test`, include them in the failing tests. -#### Binding Decision Check (Required when the task file has a Binding Decisions section) +#### Binding Decision Check (Required when the execution instructions include Binding Decisions) Runs after Pre-implementation Verification, before the TDD cycle. 1. Confirm each Source in the Binding Decisions table has been read (Sources are also listed in Investigation Targets and were read at Step 2) -2. Record the planned implementation approach in Investigation Notes โ€” one sentence per distinct `Axis` value present in the task's Binding Decisions table. When multiple rows share the same `Axis` value, group them and record one sentence covering the group +2. Record the planned implementation approach in Investigation Notes โ€” one sentence per distinct `Axis` value in the Binding Decisions supplied by the execution instructions. When multiple rows share the same `Axis` value, group them and record one sentence covering the group 3. Evaluate each row's Compliance Check against the planned approach. Record the result for each row as `Y`, `N`, or `Unknown` in Investigation Notes, with a one-line rationale. Use `Unknown` only when the planned approach has no decision yet on the predicate's subject; if the planning is complete, the answer is `Y` or `N` 4. Per row, branch on the evaluation: - `Y`: proceed - `N`: stop implementation and produce the final response with `status: "escalation_needed"` and `escalation_type: "binding_decision_violation"` with `phase: "pre_implementation"` (see Binding Decision Violation Escalation in Structured Response Specification). `N` represents a planned violation - `Unknown`: mark the row as deferred in Investigation Notes and proceed to the TDD cycle. The Exit Gate re-evaluates every row (including Unknown rows deferred from this step) against the final implementation and escalates if any remains `N` or `Unknown` at that point -#### Reference Contract Check (Required when the task file has a Reference Contracts section) +#### Reference Contract Check (Required when the execution instructions include Reference Contracts) Runs after Pre-implementation Verification, alongside the Binding Decision Check. @@ -200,25 +190,25 @@ When adopting a pattern or dependency from existing code, apply coding-principle #### Implementation Flow (TDD Compliant) -**If all checkboxes already `[x]`**: Report "already completed" and end +**When the execution scope is supplied as a task file or Work Plan and all relevant checkboxes are already `[x]`**: Report "already completed" and end -**Per checkbox item, use the flow selected in the task file** (see testing-principles skill): +**For each implementation item, use the flow selected in the execution instructions** (see testing-principles skill): - **New/changed behavior or reproducible bug**: RED (write and confirm the failing test) โ†’ GREEN (minimal implementation) โ†’ REFACTOR โ†’ VERIFY - **Behavior-preserving refactor**: BASELINE (confirm existing tests pass or add passing characterization tests) โ†’ REFACTOR โ†’ VERIFY the same evidence - **Non-reproducible bug**: EVIDENCE BASELINE (confirm the recorded reproduction attempt, concrete blocker, and named alternate evidence) โ†’ FIX โ†’ VERIFY that evidence - **Non-executable deliverable**: SOURCE BASELINE (read the named source and acceptance evidence) โ†’ PRODUCE/UPDATE โ†’ VERIFY the deliverable against them -- **Progress Update**: After verification, set `[ ]` โ†’ `[x]` in the task file, work plan, and design doc +- **Progress Update**: Apply the Responsibility Boundaries progress rule after verification **Test types**: Unit tests โ€” use the applicable flow above; Integration tests โ€” create and execute with implementation; E2E tests โ€” execute in final phase only. #### Operation Verification -- Execute "Operation Verification Methods" section in task +- Execute the Operation Verification Methods in the execution instructions - Perform verification according to level defined in implementation-approach skill - Record reason if unable to verify ### 4. Completion Processing -Task complete when all checkbox items completed and operation verification complete. +Task complete when all implementation items and operation verification are complete. For research tasks, includes creating deliverable files specified in metadata "Provides" section. ### 5. Return JSON Result @@ -304,10 +294,10 @@ Report in the following JSON format upon task completion (**without executing qu "taskName": "[Task name being executed]", "escalation_type": "investigation_target_not_found", "missingTargets": [ - {"path": "[path specified in task file]", "searchHint": "[section/function hint if provided, or null]", "searchAttempts": ["Checked path directly", "Searched for similar filenames in same directory"]} + {"path": "[path specified in the execution instructions]", "searchHint": "[section/function hint if provided, or null]", "searchAttempts": ["Checked path directly", "Searched for similar filenames in same directory"]} ], "user_decision_required": true, - "suggested_options": ["Provide correct file path", "Remove this Investigation Target and proceed", "Update task file with current paths"] + "suggested_options": ["Provide correct file path", "Remove this Investigation Target and retry", "Update the execution instructions with current paths"] } ``` @@ -333,15 +323,15 @@ Report in the following JSON format upon task completion (**without executing qu "reason": "Out of scope file", "taskName": "[Task name being executed]", "escalation_type": "out_of_scope_file", - "details": {"file_path": "[path attempted to modify]", "allowed_list": ["[union of Target Files entries, task file, work plan, Provides paths]"], "modification_reason": "[why modification was attempted]"}, + "details": {"file_path": "[path attempted to modify]", "allowed_list": ["[explicit modification targets plus applicable task-file targets]"], "modification_reason": "[why modification was attempted]"}, "user_decision_required": true, - "suggested_options": ["Add this file to task Target files and retry", "Split into a separate task for this file", "Reconsider the implementation approach to stay within scope"] + "suggested_options": ["Authorize this file as a modification target and retry", "Split into a separate task for this file", "Reconsider the implementation approach to stay within scope"] } ``` #### 2-6. Binding Decision Violation Escalation -Triggered by `N` at the pre-implementation check, or `N` or `Unknown` at the Exit Gate re-evaluation, on any Compliance Check row in the task's Binding Decisions section. +Triggered by `N` at the pre-implementation check, or `N` or `Unknown` at the Exit Gate re-evaluation, on any Compliance Check row in the Binding Decisions supplied by the execution instructions. ```json { @@ -355,7 +345,7 @@ Triggered by `N` at the pre-implementation check, or `N` or `Unknown` at the Exi {"source": "[ADR file path with section hint, copied from Source column]", "axis": "[Axis value copied from the Axis column]", "decision": "[Decision text, copied from Decision column]", "complianceCheck": "[Compliance Check predicate, copied from Compliance Check column]", "evaluation": "N | Unknown", "rationale": "[One line explaining why the implementation does not satisfy the check, or why it cannot be evaluated]"} ], "user_decision_required": true, - "suggested_options": ["Adjust the implementation plan to satisfy the binding decision", "Update the ADR (then update the work plan's ADR Bindings and this task's Binding Decisions)", "Provide additional context that resolves the Unknown evaluation"] + "suggested_options": ["Adjust the implementation plan to satisfy the binding decision", "Update the governing decision and corresponding execution instructions", "Provide additional context that resolves the Unknown evaluation"] } ``` @@ -380,14 +370,14 @@ Triggered when the Test Environment Check finds the project-configured test tool This gate runs immediately before producing the final JSON response. -โ˜ All task checkboxes completed with evidence (or `escalation_needed` triggered earlier) +โ˜ All implementation items completed with evidence (or `escalation_needed` triggered earlier) โ˜ Implementation is consistent with the Investigation Notes recorded at Step 2 (when Investigation Targets were present) โ˜ Adjacent Case Sweep evidence is non-empty and records each inspected case and disposition, or the searched surface and no-case result (when Change Category triggers the sweep) -โ˜ 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). Re-evaluate here even when the pre-implementation check passed, because the implementation may have diverged from the planned approach -โ˜ Every Reference Contracts Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes (when the task file has a Reference Contracts section). Re-evaluate here even when the pre-implementation check passed -โ˜ A test exercises the roundtrip โ€” the value the producer emits parses to the value the consumer expects (when the task has a Boundary Context with a roundtrip check from the work plan's Connection Map) +โ˜ Every Binding Decisions Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes (when the execution instructions include Binding Decisions). Re-evaluate here even when the pre-implementation check passed, because the implementation may have diverged from the planned approach +โ˜ Every Reference Contracts Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes (when the execution instructions include Reference Contracts). Re-evaluate here even when the pre-implementation check passed +โ˜ A test exercises the roundtrip โ€” the value the producer emits parses to the value the consumer expects (when the execution instructions include a Boundary Context roundtrip check) โ˜ Every Proof Obligation satisfies its selected Verification mode and Evidence requirement โ˜ When test runs are cited as `runnableCheck` evidence, they are substantive and executable per the runnableCheck.result field spec (skipped tests, placeholder/TODO-only bodies, always-passing assertions, and 0-match runner reports do not count); non-test verification (build/typecheck/CLI) is not subject to this check โ˜ Final response is a single JSON with `status: "completed"` or `status: "escalation_needed"` and matches the schema in Structured Response Specification -**ENFORCEMENT**: When any gate item is unchecked, return `escalation_needed`. Use `escalation_type: "binding_decision_violation"` with `phase: "exit_gate"` for Binding Decisions failures; use `escalation_type: "design_compliance_violation"` for other gate failures (checkbox incompletion or divergence from Investigation Notes). +**ENFORCEMENT**: When any gate item is unchecked, return `escalation_needed`. Use `escalation_type: "binding_decision_violation"` with `phase: "exit_gate"` for Binding Decisions failures; use `escalation_type: "design_compliance_violation"` for other gate failures (incomplete work or divergence from Investigation Notes). diff --git a/dev-workflows-fullstack/skills/recipe-add-integration-tests/SKILL.md b/dev-workflows-fullstack/skills/recipe-add-integration-tests/SKILL.md index 69b0b65..c09d014 100644 --- a/dev-workflows-fullstack/skills/recipe-add-integration-tests/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-add-integration-tests/SKILL.md @@ -5,6 +5,7 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. **Context**: Test addition workflow for existing implementations (backend, frontend, or fullstack) @@ -12,13 +13,17 @@ Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or g **Core Identity**: "I am an orchestrator." -**First Action**: Register Steps 0-8 using TaskCreate before any execution. +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. -**Why Delegate**: 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. +**Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression; include declined IDs with governing reasons and evidence in the final user report. +Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. + +**First Action**: Register Steps 1-7 using TaskCreate before any execution. + +**Why Delegate**: Orchestrator's context is shared across all steps. Direct implementation consumes context needed for review and quality check phases. Subagents work in isolated context. **Execution Method**: - Skeleton generation โ†’ delegate to acceptance-test-generator -- Task file creation โ†’ orchestrator creates directly (minimal context usage) - Test implementation โ†’ delegate to task-executor - Test review โ†’ delegate to integration-test-reviewer - Quality checks โ†’ delegate to quality-fixer @@ -32,10 +37,6 @@ Document paths: $ARGUMENTS ## Execution Flow -### Step 0: Execute Skill - -Execute Skill: documentation-criteria (for task file template in Step 3) - ### Step 1: Discover and Validate Documents ```bash @@ -71,107 +72,67 @@ Invoke acceptance-test-generator using Agent tool: **Expected output**: `generatedFiles` containing integration and e2e paths -### Step 3: Create Task Files [GATE] - -Create one task file per layer, using the monorepo-flow.md naming convention for deterministic agent routing: -- Backend skeletons exist โ†’ `docs/plans/tasks/integration-tests-backend-task-YYYYMMDD.md` -- Frontend skeletons exist โ†’ `docs/plans/tasks/integration-tests-frontend-task-YYYYMMDD.md` -- Single-layer (no backend/frontend distinction) โ†’ `docs/plans/tasks/integration-tests-backend-task-YYYYMMDD.md` - -**Template** (per task file): -```markdown ---- -name: Implement [layer] integration tests for [feature name] -type: test-implementation ---- - -## Objective - -Implement test cases defined in skeleton files. - -## Target Files - -- Skeleton: [layer-specific paths from Step 2 generatedFiles] -- Design Doc: [layer-specific Design Doc from Step 1] +### Step 3: Test Implementation -## Tasks - -- [ ] Implement each test case in skeleton -- [ ] Verify all tests pass -- [ ] Ensure coverage meets requirements - -## Acceptance Criteria - -- All skeleton test cases implemented -- All tests passing -- quality-fixer reports approved -``` - -**Output**: "Task file(s) created at [path(s)]. Ready for Step 4." - -### Step 4: Test Implementation - -For each task file from Step 3, record the current HEAD as `diffBase`, then invoke task-executor routed by filename pattern (per monorepo-flow.md): -- `*-backend-task-*` โ†’ `subagent_type`: "dev-workflows-fullstack:task-executor" -- `*-frontend-task-*` โ†’ `subagent_type`: "dev-workflows-fullstack:task-executor-frontend" +For each layer with generated skeletons, record the current HEAD as `diffBase`, then invoke the layer's task-executor: +- Backend or single-layer โ†’ `subagent_type`: "dev-workflows-fullstack:task-executor" +- Frontend โ†’ `subagent_type`: "dev-workflows-fullstack:task-executor-frontend" - `description`: "Implement integration tests" -- `prompt`: "Task file: [task file path from Step 3]. Implement tests following the task file." +- `prompt`: "Implement every test defined by these generated skeletons: [layer-specific Step 2 paths]. Governing documents: [layer-specific Design Doc and UI Spec when present]. Keep changes within the generated tests and the setup or fixture files they require. Verify the implemented tests against the skeleton claims." + +Execute one layer at a time through Steps 3โ†’4โ†’5โ†’6โ†’7 before starting the next. -Execute one task file at a time through Steps 4โ†’5โ†’6โ†’7 before starting the next. +**Expected output**: `status`, `filesModified`, `testsAdded`, `mutationEvidence` -**Expected output**: `status`, `testsAdded` +Apply this response gate after every task-executor invocation in Steps 3 and 5: +- `status: completed`, `filesModified` and `testsAdded` are present, and at least one changed integration/E2E path can be identified from the cumulative response paths against `diffBase` โ†’ Proceed to Step 4 +- `status: escalation_needed` โ†’ Escalate to the user +- Any other status, or a response missing the required fields above โ†’ Stop and report the invalid or missing fields -### Step 5: Test Review +### Step 4: Test Review Invoke integration-test-reviewer using Agent tool: - `subagent_type`: "dev-workflows-fullstack:integration-test-reviewer" - `description`: "Review test quality" -- `prompt`: "Review test quality. changedTestFiles: [integration/E2E paths in Step 4 filesModified or testsAdded that differ from diffBase]. diffBase: [revision recorded before Step 4]. skeletonFiles: [layer-specific paths from Step 2 generatedFiles matching current task's layer]. taskFile: [current task file]. mutationEvidence: [Step 4 mutationEvidence]." +- `prompt`: "Review test quality. changedTestFiles: [integration/E2E paths in Step 3 filesModified or testsAdded that differ from diffBase]. diffBase: [revision recorded before Step 3]. skeletonFiles: [layer-specific paths from Step 2 generatedFiles]. mutationEvidence: [Step 3 mutationEvidence]." -**Expected output**: `status` (approved/needs_revision/blocked), `testFiles`, `reviewBasis`, `requiredFixes` +**Expected output**: `status` (approved/needs_revision/blocked), `testFiles`, `reviewBasis`, `qualityIssues`, `requiredFixes` -### Step 6: Apply Review Fixes +### Step 5: Apply Review Fixes -Check Step 5 result: -- `status: approved` โ†’ Mark complete, proceed to Step 7 -- `status: needs_revision` โ†’ Invoke task-executor with requiredFixes, then return to Step 5 +Check Step 4 result: +- `status: approved` โ†’ Mark complete, proceed to Step 6 - `status: blocked` โ†’ Escalate to user +- `status: needs_revision` โ†’ Apply the Review Resolution Gate + - one or more `apply` findings โ†’ Invoke task-executor with those findings, apply the executor response gate above, then return to Step 4 with `prior_feedback` + - every actionable finding is `decline` โ†’ Mark review complete and proceed to Step 6 + - any unresolved `user_decision_required` finding โ†’ Escalate to user -Invoke task-executor routed by task filename pattern: -- `*-backend-task-*` โ†’ `subagent_type`: "dev-workflows-fullstack:task-executor" -- `*-frontend-task-*` โ†’ `subagent_type`: "dev-workflows-fullstack:task-executor-frontend" +Invoke the same layer's task-executor: - `description`: "Fix review findings" -- `prompt`: "Fix the following issues in test files: [requiredFixes from Step 5]" +- `prompt`: "Fix these adjudicated test-review findings directly: [apply findings with IDs, governing basis, smallest correction, affected paths, and observable verification condition]." -### Step 7: Quality Check +### Step 6: Quality Check -Invoke quality-fixer routed by task filename pattern: -- `*-backend-task-*` โ†’ `subagent_type`: "dev-workflows-fullstack:quality-fixer" -- `*-frontend-task-*` โ†’ `subagent_type`: "dev-workflows-fullstack:quality-fixer-frontend" +Invoke quality-fixer for the current layer: +- Backend or single-layer โ†’ `subagent_type`: "dev-workflows-fullstack:quality-fixer" +- Frontend โ†’ `subagent_type`: "dev-workflows-fullstack:quality-fixer-frontend" - `description`: "Final quality assurance" -- Pass Step 4 `mutationEvidence` and `qualityCommand` when available (caller first, otherwise current task). +- Pass the latest executor's `filesModified` and `mutationEvidence`. - `prompt`: "Final quality assurance for test files added in this workflow. Run all tests and verify coverage." **Expected output**: `status` (approved/stub_detected/blocked) Check quality-fixer response: -- `stub_detected` โ†’ Return to Step 4 with `incompleteImplementations[]` details, then re-execute Steps 4โ†’5โ†’6โ†’7 +- `stub_detected` โ†’ Return to Step 3 with `incompleteImplementations[]` details, then re-execute Steps 3โ†’4โ†’5โ†’6 - `blocked` โ†’ Escalate to user -- `approved` โ†’ Proceed to Step 8 +- `approved` โ†’ Proceed to Step 7 -### Step 8: Commit +### Step 7: Commit On `approved` from quality-fixer: - Commit test files using Bash with message format: "test: add [layer] integration tests for [feature name]" -### Step 9: Final Cleanup - -After all task files have been processed and committed, delete the task files this recipe created. Their work is committed; `docs/plans/` is ephemeral working state and is not retained between recipe runs: - -- Delete every file matching `docs/plans/tasks/integration-tests-backend-task-*.md` and `docs/plans/tasks/integration-tests-frontend-task-*.md` created during this run - -If task files cannot be deleted (filesystem error), report the failure but do not block completion. - ## Scope Boundary for Subagents Append the following block to every subagent prompt invoked from this recipe: diff --git a/dev-workflows-fullstack/skills/recipe-build/SKILL.md b/dev-workflows-fullstack/skills/recipe-build/SKILL.md index 0ebe4c5..81fd1b5 100644 --- a/dev-workflows-fullstack/skills/recipe-build/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-build/SKILL.md @@ -5,13 +5,19 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. ## Orchestrator Definition **Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. + +**Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression; include declined IDs with governing reasons and evidence in the final user report. +Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. + **Execution Protocol**: -1. **Delegate all work through Agent tool** โ€” invoke sub-agents, pass deliverable paths between them, and report results (permitted tools: see subagents-orchestration-guide "Orchestrator's Permitted Tools") +1. **Invoke named specialists for deliverable production** โ€” pass deliverable paths between them and validate their results (see subagents-orchestration-guide "Orchestrator Execution Boundary") 2. **Follow the 4-step task cycle exactly**: execute โ†’ branch on executor result โ†’ quality-fix โ†’ commit 3. **Enter autonomous mode** when user provides execution instruction with existing task files โ€” this IS the batch approval 4. **Scope**: Complete when all tasks are committed or escalation occurs @@ -26,7 +32,7 @@ Work plan: $ARGUMENTS Before any task processing, locate the work plan. Resolution rule: 1. List task files in `docs/plans/tasks/` matching the single-layer pattern `{plan-name}-task-*.md`. Layer-aware fullstack tasks (`{plan-name}-backend-task-*.md` / `{plan-name}-frontend-task-*.md`) are excluded here so a stale fullstack run does not redirect this recipe to the wrong work plan -2. From the matched files, also exclude every file matching any of these patterns โ€” they originate from other workflow phases and are not implementation tasks for this run's plan: `*-task-prep-*.md` (readiness preflight tasks), `_overview-*.md` (materialization overview file), `*-phase*-completion.md` (per-phase completion files), `review-fixes-*.md` (post-implementation review fixes), `integration-tests-*-task-*.md` (integration-test add-on scaffolding) +2. From the matched files, also exclude `_overview-*.md` (materialization overview files) and `*-phase*-completion.md` (per-phase completion files). 3. For each remaining file, extract the `{plan-name}` prefix as the segment that appears before `-task-` 4. When at least one task file matches, the work plan is `docs/plans/{plan-name}.md` for the prefix that has the most recent task-file mtime; ties broken by the lexicographically last `{plan-name}` 5. When no task file matches the restricted pattern, the work plan is the most-recent-mtime non-template `.md` in `docs/plans/` @@ -36,7 +42,7 @@ Before any task processing, locate the work plan. Resolution rule: Compute the **Consumed Task Set** for this run โ€” the exact files this recipe owns, executes, and later deletes. Use the same restricted pattern as Work Plan Resolution: 1. List task files in `docs/plans/tasks/` matching the single-layer pattern `{plan-name}-task-*.md` for the `{plan-name}` resolved by Work Plan Resolution. Layer-aware fullstack tasks are excluded -2. Exclude every file matching: `*-task-prep-*.md`, `_overview-*.md`, `*-phase*-completion.md`, `review-fixes-*.md`, `integration-tests-*-task-*.md` (these originate from other workflow phases) +2. Exclude every file matching `_overview-*.md` or `*-phase*-completion.md`. Every subsequent reference to "task files" in this recipe โ€” Task Generation Decision Flow, Task Execution Cycle iteration, and Final Cleanup โ€” uses this set, not the unrestricted `docs/plans/tasks/*.md` glob. @@ -48,7 +54,7 @@ Analyze the Consumed Task Set and determine the action required: |-------|----------|-------------| | Tasks exist | Consumed Task Set is non-empty | User's execution instruction serves as batch approval โ†’ Enter autonomous execution immediately | | No tasks + plan exists | Consumed Task Set is empty but the resolved work plan exists | Confirm with user โ†’ run task-decomposer | -| Neither exists + Design Doc exists | No plan, no Consumed Task Set, but `docs/design/*.md` exists | Invoke work-planner to create work plan from Design Doc, then run document-reviewer (`dev-workflows-fullstack:document-reviewer`, doc_type: WorkPlan); branch on the reviewer's `verdict.decision` โ€” on `needs_revision`, re-invoke work-planner (update) and re-review until `approved`/`approved_with_conditions`; if the same blocking finding repeats without new evidence or a contract change, stop and escalate it; then present the reviewed plan for batch approval before task materialization; on `rejected`, stop before task materialization and escalate to the user | +| Neither exists + Design Doc exists | No plan, no Consumed Task Set, but `docs/design/*.md` exists | Invoke work-planner to create a work plan, then run document-reviewer (`dev-workflows-fullstack:document-reviewer`, doc_type: WorkPlan). Apply the Review Resolution Gate: update for `apply`, re-review with `prior_feedback`, progress when all actionable findings are `decline`, and escalate unresolved `user_decision_required`; then present the resolved plan for batch approval before task materialization | | Neither exists | No plan, no Consumed Task Set, no Design Doc | Report missing prerequisites to user and stop | ## Task Materialization Phase (Conditional) @@ -92,9 +98,12 @@ For EACH task in the Consumed Task Set, YOU MUST: 2. **BRANCH ON EXECUTOR RESULT**: - `status: "escalation_needed"` or `"blocked"` โ†’ STOP and escalate to user - `requiresTestReview` is `true` โ†’ Invoke integration-test-reviewer with `diffBase`, changed integration/E2E paths, `taskFile`, prompt-only claims, and `mutationEvidence` - - `needs_revision` โ†’ Return to step 1 with `requiredFixes` - `approved` โ†’ Proceed to step 3 - `blocked` โ†’ STOP and escalate to user + - `needs_revision` โ†’ Apply the Review Resolution Gate + - one or more `apply` findings โ†’ Return to step 1 with those findings, then re-review with `prior_feedback` + - every actionable finding is `decline` โ†’ Proceed to step 3 + - any unresolved `user_decision_required` finding โ†’ STOP and escalate to user - `readyForQualityCheck: true` โ†’ Proceed to step 3 3. **QUALITY-FIX**: Invoke quality-fixer with `task_file`, upstream `mutationEvidence`, and `qualityCommand` when available (caller first, otherwise current task) - `stub_detected` โ†’ Return to step 1 with `incompleteImplementations[]` details @@ -146,4 +155,5 @@ Final report must include: - Quality check result - Commit count - Cleanup result +- Declined actionable findings with ID, governing reason, and evidence - Escalation or blocking summary, if any diff --git a/dev-workflows-fullstack/skills/recipe-design/SKILL.md b/dev-workflows-fullstack/skills/recipe-design/SKILL.md index 4f44338..f414a41 100644 --- a/dev-workflows-fullstack/skills/recipe-design/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-design/SKILL.md @@ -5,6 +5,7 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. **Context**: Dedicated to the design phase. @@ -12,15 +13,20 @@ Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or g **Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. The scope bootstrap locates seed files; the named specialists own semantic investigation and artifact authorship. + +**Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression; include declined IDs with governing reasons and evidence in the final user report. +Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. + **Execution Protocol**: -1. **Delegate all work** to sub-agents โ€” your role is to invoke sub-agents, pass data between them, and report results. The one exception is the Step 1 scope bootstrap, a recipe-local orchestrator task limited to locating seed files. +1. **Invoke named specialists for deliverable production** โ€” pass data between them and validate their results. Step 1 is a recipe-local read-only scope bootstrap limited to locating seed files. 2. **Run the design flow below in order**: - Execute: scope bootstrap โ†’ codebase-analyzer โ†’ [Stop: Scope confirmation] โ†’ technical-designer โ†’ code-verifier โ†’ document-reviewer โ†’ design-sync - code-verifier and design-sync apply when the design output is a Design Doc; both are skipped for ADR-only - **Stop at every `[Stop: ...]` marker** โ†’ Wait for user approval before proceeding 3. **Scope**: Complete when design documents receive approval -**subagents-orchestration-guide usage**: Reference the guide only for orchestration principles (Delegation Boundary, Decision precedence, permitted tools), the Scale Determination table, and handoff contracts HC-02 onward. This recipe defines its own start order and subagent prompts. The guide's requirement-analyzer-origin flow, First Action Rule, HC-01, and Call Examples do not apply to this recipe. +**subagents-orchestration-guide usage**: Use the guide for orchestration principles (Delegation Boundary, Decision precedence, Execution Boundary), the Scale Determination table, and handoff contracts HC-02 onward. This recipe's start order and subagent prompts supersede the guide's requirement-analyzer-origin flow, First Action Rule, HC-01, and Agent-Specific Prompt Content. **CRITICAL**: Execute document-reviewer, design-sync (for Design Docs), and all stopping points โ€” each serves as a quality gate. Skipping any step risks undetected inconsistencies. @@ -78,7 +84,9 @@ Invoke codebase-analyzer with its existing schema. The orchestrator constructs ` ### Step 3: Scope Confirmation After codebase-analyzer returns, confirm the design scope with the user before any design work. This is a recipe-local confirmation step. -First run the requirement-convergence hearing protocol, using the codebase-analyzer findings as the facts it presents. This recipe has no requirement-analyzer, so the orchestrator both elicits and judges the fields, recording the result as the skill's `convergence` object (`outcome`, `requirements[]` with layer labels, `nonGoals[]`, plus a readiness label per field). `cost` does not apply here: the orchestrator cannot search the repository, and entering this recipe already decided to design. Carry that object into Step 4 so technical-designer persists it to the Design Doc. +Execute Skill: requirement-convergence before running the hearing protocol. + +First run the requirement-convergence hearing protocol, using the codebase-analyzer findings as the facts it presents. In this flow, the orchestrator elicits and judges the fields and records the result as the skill's `convergence` object (`outcome`, `requirements[]` with layer labels, `nonGoals[]`, plus a readiness label per field). Treat `cost` as already resolved because semantic repository investigation is assigned to codebase-analyzer and entering this recipe decided to design. Carry that object into Step 4 so technical-designer persists it to the Design Doc. Then present, sourced from the codebase-analyzer JSON, using AskUserQuestion: - **Target files/modules**: `analysisScope.filesAnalyzed` and the modules they belong to @@ -105,13 +113,20 @@ Pass the full codebase-analyzer JSON to technical-designer (handoff contract HC- - **(Design Doc only)** Invoke **code-verifier** to verify the Design Doc against existing code. Skip for ADR. - `subagent_type: "dev-workflows-fullstack:code-verifier"`, `description: "Design Doc verification"`, `prompt: "doc_type: design-doc document_path: [Design Doc path] Verify Design Doc against existing code."` - **(Design Doc only)** Invoke **document-reviewer** to verify consistency, completeness, and adopted design validity + - Treat the preceding code-verifier result as `code_verification` evidence; the document-reviewer result controls correction routing. - `subagent_type: "dev-workflows-fullstack:document-reviewer"`, `description: "Design Doc review"`, `prompt: "Review [Design Doc path] for consistency, completeness, and adopted design validity. doc_type: DesignDoc. review_context: creation. requirements_verbatim: [user requirements verbatim]. confirmed_decisions: [Step 3 confirmed scope and user answers]. codebase_analysis: [codebase-analyzer JSON from Step 2]. code_verification: [code-verifier output from this step]"` + - Apply the Review Resolution Gate. When `apply` findings change the Design Doc, invoke technical-designer in update mode, then re-run code-verifier and document-reviewer with `prior_feedback`. - **(ADR only)** Invoke **document-reviewer** to verify consistency and completeness - `subagent_type: "dev-workflows-fullstack:document-reviewer"`, `description: "ADR review"`, `prompt: "Review [ADR path] for consistency and completeness. doc_type: ADR. codebase_analysis: [codebase-analyzer JSON from Step 2]"` + - Apply the Review Resolution Gate. When `apply` findings change the ADR, invoke technical-designer in update mode and re-run document-reviewer with `prior_feedback`. - **(Design Doc only)** Invoke **design-sync** to verify consistency across design documents. Skip for ADR-only. - `subagent_type: "dev-workflows-fullstack:design-sync"`, `description: "Design consistency check"`, `prompt: "Check consistency across all Design Docs in docs/design/. Report conflicts and overlaps."` + - Apply the Review Resolution Gate to every reported conflict. + - One or more `apply` findings โ†’ invoke the named technical designer for each affected Design Doc; re-run code-verifier and document-reviewer for each modified document with the latest verification and `prior_feedback`, then re-run design-sync + - Every actionable conflict is `decline` โ†’ proceed to the approval stop + - Any unresolved `user_decision_required` conflict โ†’ stop for user input -**[STOP]**: Present the design document, plus design-sync results for a Design Doc, and obtain user approval. +**[STOP]**: Present the design document, plus design-sync results for a Design Doc, and obtain user approval. For an approved ADR, invoke technical-designer in update mode to set its status to `Accepted` and verify the update before completion. ## Completion Criteria @@ -123,7 +138,7 @@ Pass the full codebase-analyzer JSON to technical-designer (handoff contract HC- - [ ] Executed code-verifier on Design Doc and passed results to document-reviewer (skip for ADR-only) - [ ] Executed document-reviewer and addressed feedback - [ ] Executed design-sync for consistency verification (skip for ADR-only) -- [ ] Obtained user approval for design document +- [ ] Obtained user approval for the design document and verified an approved ADR has status `Accepted` ## Output Example Design phase completed. diff --git a/dev-workflows-fullstack/skills/recipe-diagnose/SKILL.md b/dev-workflows-fullstack/skills/recipe-diagnose/SKILL.md index fe5cb06..2f34835 100644 --- a/dev-workflows-fullstack/skills/recipe-diagnose/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-diagnose/SKILL.md @@ -5,6 +5,7 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. **Context**: Diagnosis flow to identify root cause and present solutions @@ -12,7 +13,9 @@ Target problem: $ARGUMENTS ## Orchestrator Definition -**Core Identity**: "I am not a worker. I am an orchestrator." +**Core Identity**: "I am an orchestrator." + +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. **Execution Method**: - Investigation โ†’ performed by investigator @@ -232,4 +235,3 @@ Rationale: [Selection rationale] - [ ] Executed solver - [ ] Achieved coverageAssessment=sufficient (or obtained user approval after 2 additional iterations) - [ ] Presented final report to user - diff --git a/dev-workflows-fullstack/skills/recipe-front-adjust/SKILL.md b/dev-workflows-fullstack/skills/recipe-front-adjust/SKILL.md index d8a25db..f4c6d84 100644 --- a/dev-workflows-fullstack/skills/recipe-front-adjust/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-front-adjust/SKILL.md @@ -5,6 +5,7 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. **Context**: UI adjustment on already-implemented features. The verification loop (edit โ†’ check against the design source โ†’ refine) runs in the parent session. @@ -63,6 +64,8 @@ Adjustment request: $ARGUMENTS ## Execution Flow ### Step 1: External Resource Hearing +Execute Skill: external-resource-context before running the hearing protocol. + Run the hearing protocol per the external-resource-context skill (frontend domain). ### Step 2: UI Fact Gathering @@ -109,6 +112,11 @@ After work-planner returns: ### Step 5: Adjustment + Verification (parent session) +Execute Skill: frontend-ai-guide before planning or applying adjustment edits. +Execute Skill: typescript-rules before planning or applying adjustment edits. +Execute Skill: implementation-approach before planning or applying adjustment edits. +Execute Skill: test-implement before adding or changing tests. + For each adjustment unit (per file in Branch A; per work plan phase in Branch B): 1. **Plan the edit** based on ui-analyzer focusAreas and the relevant external resource (e.g., design origin's fetched_summary). 2. **Apply the edit** using Edit / Write / MultiEdit on the affected files. diff --git a/dev-workflows-fullstack/skills/recipe-front-build/SKILL.md b/dev-workflows-fullstack/skills/recipe-front-build/SKILL.md index dd01258..a8a49d8 100644 --- a/dev-workflows-fullstack/skills/recipe-front-build/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-front-build/SKILL.md @@ -5,13 +5,19 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. ## Orchestrator Definition **Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. + +**Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression; include declined IDs with governing reasons and evidence in the final user report. +Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. + **Execution Protocol**: -1. **Delegate all work through Agent tool** โ€” invoke sub-agents, pass deliverable paths between them, and report results (permitted tools: see subagents-orchestration-guide "Orchestrator's Permitted Tools") +1. **Invoke named specialists for deliverable production** โ€” pass deliverable paths between them and validate their results (see subagents-orchestration-guide "Orchestrator Execution Boundary") 2. **Follow the 4-step task cycle exactly**: execute โ†’ branch on executor result โ†’ quality-fix โ†’ commit 3. **Enter autonomous mode** when user provides execution instruction with existing task files โ€” this IS the batch approval 4. **Scope**: Complete when all tasks are committed or escalation occurs @@ -26,7 +32,7 @@ Work plan: $ARGUMENTS Before any task processing, locate the work plan. Resolution rule: 1. List task files in `docs/plans/tasks/` matching the single-layer pattern `{plan-name}-task-*.md`. Layer-aware fullstack tasks (`{plan-name}-backend-task-*.md` / `{plan-name}-frontend-task-*.md`) are excluded here so a stale fullstack run does not redirect this recipe to the wrong work plan -2. From the matched files, also exclude every file matching any of these patterns โ€” they originate from other workflow phases and are not implementation tasks for this run's plan: `*-task-prep-*.md` (readiness preflight tasks), `_overview-*.md` (materialization overview file), `*-phase*-completion.md` (per-phase completion files), `review-fixes-*.md` (post-implementation review fixes), `integration-tests-*-task-*.md` (integration-test add-on scaffolding) +2. From the matched files, also exclude `_overview-*.md` (materialization overview files) and `*-phase*-completion.md` (per-phase completion files). 3. For each remaining file, extract the `{plan-name}` prefix as the segment that appears before `-task-` 4. When at least one task file matches, the work plan is `docs/plans/{plan-name}.md` for the prefix that has the most recent task-file mtime; ties broken by the lexicographically last `{plan-name}` 5. When no task file matches the restricted pattern, the work plan is the most-recent-mtime non-template `.md` in `docs/plans/` @@ -36,7 +42,7 @@ Before any task processing, locate the work plan. Resolution rule: Compute the **Consumed Task Set** for this run โ€” the exact files this recipe owns, executes, and later deletes. Use the same restricted pattern as Work Plan Resolution: 1. List task files in `docs/plans/tasks/` matching the single-layer pattern `{plan-name}-task-*.md` for the `{plan-name}` resolved by Work Plan Resolution. Layer-aware fullstack tasks are excluded -2. Exclude every file matching: `*-task-prep-*.md`, `_overview-*.md`, `*-phase*-completion.md`, `review-fixes-*.md`, `integration-tests-*-task-*.md` (these originate from other workflow phases) +2. Exclude every file matching `_overview-*.md` or `*-phase*-completion.md`. Every subsequent reference to "task files" in this recipe โ€” Task Generation Decision Flow, Task Execution Cycle iteration, and Final Cleanup โ€” uses this set, not the unrestricted `docs/plans/tasks/*.md` glob. @@ -48,7 +54,7 @@ Analyze the Consumed Task Set and determine the action required: |-------|----------|-------------| | Tasks exist | Consumed Task Set is non-empty | User's execution instruction serves as batch approval โ†’ Enter autonomous execution immediately | | No tasks + plan exists | Consumed Task Set is empty but the resolved work plan exists | Confirm with user โ†’ run task-decomposer | -| Neither exists + Design Doc exists | No plan, no Consumed Task Set, but `docs/design/*.md` exists | Invoke work-planner to create work plan from Design Doc, then run document-reviewer (`dev-workflows-fullstack:document-reviewer`, doc_type: WorkPlan); branch on the reviewer's `verdict.decision` โ€” on `needs_revision`, re-invoke work-planner (update) and re-review until `approved`/`approved_with_conditions`; if the same blocking finding repeats without new evidence or a contract change, stop and escalate it; then present the reviewed plan for batch approval before task materialization; on `rejected`, stop before task materialization and escalate to the user | +| Neither exists + Design Doc exists | No plan, no Consumed Task Set, but `docs/design/*.md` exists | Invoke work-planner to create a work plan, then run document-reviewer (`dev-workflows-fullstack:document-reviewer`, doc_type: WorkPlan). Apply the Review Resolution Gate: update for `apply`, re-review with `prior_feedback`, progress when all actionable findings are `decline`, and escalate unresolved `user_decision_required`; then present the resolved plan for batch approval before task materialization | | Neither exists | No plan, no Consumed Task Set, no Design Doc | Report missing prerequisites to user and stop | ## Task Materialization Phase (Conditional) @@ -92,9 +98,12 @@ For EACH task in the Consumed Task Set, YOU MUST: 2. **BRANCH ON EXECUTOR RESULT**: - `status: "escalation_needed"` or `"blocked"` โ†’ STOP and escalate to user - `requiresTestReview` is `true` โ†’ Invoke integration-test-reviewer with `diffBase`, changed integration/E2E paths, `taskFile`, prompt-only claims, and `mutationEvidence` - - `needs_revision` โ†’ Return to step 1 with `requiredFixes` - `approved` โ†’ Proceed to step 3 - `blocked` โ†’ STOP and escalate to user + - `needs_revision` โ†’ Apply the Review Resolution Gate + - one or more `apply` findings โ†’ Return to step 1 with those findings, then re-review with `prior_feedback` + - every actionable finding is `decline` โ†’ Proceed to step 3 + - any unresolved `user_decision_required` finding โ†’ STOP and escalate to user - `readyForQualityCheck: true` โ†’ Proceed to step 3 3. **QUALITY-FIX**: Invoke quality-fixer-frontend with `task_file`, upstream `mutationEvidence`, and `qualityCommand` when available (caller first, otherwise current task) - `stub_detected` โ†’ Return to step 1 with `incompleteImplementations[]` details @@ -146,4 +155,5 @@ Final report must include: - Quality check result - Commit count - Cleanup result +- Declined actionable findings with ID, governing reason, and evidence - Escalation or blocking summary, if any diff --git a/dev-workflows-fullstack/skills/recipe-front-design/SKILL.md b/dev-workflows-fullstack/skills/recipe-front-design/SKILL.md index c7b6415..e04555f 100644 --- a/dev-workflows-fullstack/skills/recipe-front-design/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-front-design/SKILL.md @@ -5,6 +5,7 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. **Context**: Dedicated to the frontend design phase. @@ -12,15 +13,20 @@ Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or g **Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. The scope bootstrap locates seed files; the named specialists own semantic investigation and artifact authorship. + +**Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression; include declined IDs with governing reasons and evidence in the final user report. +Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. + **Execution Protocol**: -1. **Delegate all work** to sub-agents โ€” your role is to invoke sub-agents, pass data between them, and report results. The one exception is the Step 1 scope bootstrap, a recipe-local orchestrator task limited to locating seed files. +1. **Invoke named specialists for deliverable production** โ€” pass data between them and validate their results. Step 1 is a recipe-local read-only scope bootstrap limited to locating seed files. 2. **Run the frontend design flow below in order** (this recipe covers medium/large frontend): - Execute: scope bootstrap โ†’ codebase-analyzer โ†’ [Stop: Scope confirmation] โ†’ external resource hearing โ†’ ui-analyzer โ†’ ui-spec-designer โ†’ technical-designer-frontend โ†’ code-verifier โ†’ document-reviewer โ†’ design-sync - ui-spec-designer, code-verifier, and design-sync apply when the design output is a Design Doc; all are skipped for ADR-only - **Stop at every `[Stop: ...]` marker** โ†’ Wait for user approval before proceeding 3. **Scope**: Complete when design documents receive approval -**subagents-orchestration-guide usage**: Reference the guide only for orchestration principles (Delegation Boundary, Decision precedence, permitted tools), the Scale Determination table, and handoff contracts HC-02 onward. This recipe defines its own start order and subagent prompts. The guide's requirement-analyzer-origin flow, First Action Rule, HC-01, and Call Examples do not apply to this recipe. +**subagents-orchestration-guide usage**: Use the guide for orchestration principles (Delegation Boundary, Decision precedence, Execution Boundary), the Scale Determination table, and handoff contracts HC-02 onward. This recipe's start order and subagent prompts supersede the guide's requirement-analyzer-origin flow, First Action Rule, HC-01, and Agent-Specific Prompt Content. **CRITICAL**: Execute document-reviewer, design-sync (for Design Docs), and all stopping points โ€” each serves as a quality gate. Skipping any step risks undetected inconsistencies. @@ -87,7 +93,9 @@ Invoke codebase-analyzer with its existing schema. The orchestrator constructs ` ### Step 3: Scope Confirmation After codebase-analyzer returns, confirm the design scope with the user before any design work. This is a recipe-local confirmation step. -First run the requirement-convergence hearing protocol, using the codebase-analyzer findings as the facts it presents. This recipe has no requirement-analyzer, so the orchestrator both elicits and judges the fields, recording the result as the skill's `convergence` object (`outcome`, `requirements[]` with layer labels, `nonGoals[]`, plus a readiness label per field). `cost` does not apply here: the orchestrator cannot search the repository, and entering this recipe already decided to design. Carry that object into Steps 6 and 7 so ui-spec-designer respects the non-goals and technical-designer-frontend persists it to the Design Doc. +Execute Skill: requirement-convergence before running the hearing protocol. + +First run the requirement-convergence hearing protocol, using the codebase-analyzer findings as the facts it presents. In this flow, the orchestrator elicits and judges the fields and records the result as the skill's `convergence` object (`outcome`, `requirements[]` with layer labels, `nonGoals[]`, plus a readiness label per field). Treat `cost` as already resolved because semantic repository investigation is assigned to codebase-analyzer and ui-analyzer and entering this recipe decided to design. Carry that object into Steps 6 and 7 so ui-spec-designer respects the non-goals and technical-designer-frontend persists it to the Design Doc. Then present, sourced from the codebase-analyzer JSON, using AskUserQuestion: - **Target files/modules**: `analysisScope.filesAnalyzed` and the modules they belong to @@ -106,6 +114,8 @@ After the user confirms the scope, count the confirmed target files and set the **[STOP]**: Wait for the user's choice before proceeding. ### Step 4: External Resource Hearing +Execute Skill: external-resource-context before running the hearing protocol. + Run the hearing protocol per the external-resource-context skill (frontend domain). The orchestrator owns this step because it requires AskUserQuestion. The skill defines file-existence branching, two-phase hearing (structured axes + self-declaration), and persistence to `docs/project-context/external-resources.md`. ### Step 5: UI Fact Gathering @@ -140,6 +150,7 @@ Then create the UI Specification: - Example (no PRD): `prompt: "Create UI Spec from these requirements: [user requirements verbatim]. Codebase analysis: [codebase-analyzer JSON from Step 2]. Confirmed scope: [Step 3 confirmed scope]. ui_analysis: [JSON from Step 5 ui-analyzer]. Prototype code is at [user-provided path]. Place prototype in docs/ui-spec/assets/{feature-name}/."` - Invoke **document-reviewer** to verify UI Spec - `subagent_type: "dev-workflows-fullstack:document-reviewer"`, `description: "UI Spec review"`, `prompt: "doc_type: UISpec target: [ui-spec path] Review for consistency and completeness"` +- Apply the Review Resolution Gate before presenting the UI Spec. If corrections are applied, re-run document-reviewer with `prior_feedback`. - **[STOP]**: Present UI Spec for user approval ### Step 7: Design Document Creation Phase @@ -150,14 +161,21 @@ Pass the Step 2 codebase-analyzer output and the Step 5 ui-analyzer output to te - **(Design Doc only)** Invoke **code-verifier** to verify Design Doc against existing code. Skip for ADR. - `subagent_type: "dev-workflows-fullstack:code-verifier"`, `description: "Design Doc verification"`, `prompt: "doc_type: design-doc document_path: [Design Doc path] Verify Design Doc against existing code."` - **(Design Doc only)** Invoke **document-reviewer** to verify consistency, completeness, and adopted design validity + - Treat the preceding code-verifier result as `code_verification` evidence; the document-reviewer result controls correction routing. - `subagent_type: "dev-workflows-fullstack:document-reviewer"`, `description: "Design Doc review"`, `prompt: "Review [Design Doc path] for consistency, completeness, and adopted design validity. doc_type: DesignDoc. review_context: creation. requirements_verbatim: [user requirements verbatim]. confirmed_decisions: [Step 3 confirmed scope and user answers]. codebase_analysis: [codebase-analyzer JSON from Step 2]. ui_analysis: [ui-analyzer JSON from Step 5]. code_verification: [code verification output from this step]"` + - Apply the Review Resolution Gate. When `apply` findings change the Design Doc, invoke technical-designer-frontend in update mode, then re-run code-verifier and document-reviewer with `prior_feedback`. - **(ADR only)** Invoke **document-reviewer** to verify consistency and completeness - `subagent_type: "dev-workflows-fullstack:document-reviewer"`, `description: "ADR review"`, `prompt: "Review [ADR path] for consistency and completeness. doc_type: ADR. codebase_analysis: [codebase-analyzer JSON from Step 2]. ui_analysis: [ui-analyzer JSON from Step 5]"` + - Apply the Review Resolution Gate. When `apply` findings change the ADR, invoke technical-designer-frontend in update mode and re-run document-reviewer with `prior_feedback`. ### Step 8: Design Consistency Verification - **(Design Doc only)** Invoke **design-sync** using Agent tool. Skip for ADR-only. - `subagent_type: "dev-workflows-fullstack:design-sync"`, `description: "Design consistency check"`, `prompt: "Check consistency across all Design Docs in docs/design/. Report conflicts and overlaps."` -- **[STOP]**: Present the design document, plus design-sync results for a Design Doc, and obtain user approval + - Apply the Review Resolution Gate to every reported conflict. + - One or more `apply` findings โ†’ invoke the named technical designer for each affected Design Doc; re-run code-verifier and document-reviewer for each modified document with the latest verification and `prior_feedback`, then re-run design-sync + - Every actionable conflict is `decline` โ†’ proceed to the approval stop + - Any unresolved `user_decision_required` conflict โ†’ stop for user input +- **[STOP]**: Present the design document, plus design-sync results for a Design Doc, and obtain user approval. For an approved ADR, invoke technical-designer-frontend in update mode to set its status to `Accepted` and verify the update before completion ## Completion Criteria @@ -172,10 +190,10 @@ Pass the Step 2 codebase-analyzer output and the Step 5 ui-analyzer output to te - [ ] Executed code-verifier on Design Doc and passed results to document-reviewer (skip for ADR-only) - [ ] Executed document-reviewer and addressed feedback - [ ] Executed design-sync for consistency verification (skip for ADR-only) -- [ ] Obtained user approval for design document +- [ ] Obtained user approval for the design document and verified an approved ADR has status `Accepted` ## Output Example Frontend design phase completed. -- UI Specification: docs/ui-spec/[feature-name]-ui-spec.md +- UI Specification: docs/ui-spec/[feature-name]-ui-spec.md or N/A โ€” ADR-only - Design document: docs/design/[document-name].md or docs/adr/[document-name].md - Approval status: User approved diff --git a/dev-workflows-fullstack/skills/recipe-front-plan/SKILL.md b/dev-workflows-fullstack/skills/recipe-front-plan/SKILL.md index b274aeb..12e46ca 100644 --- a/dev-workflows-fullstack/skills/recipe-front-plan/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-front-plan/SKILL.md @@ -5,6 +5,7 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. **Context**: Dedicated to the frontend planning phase. @@ -12,8 +13,13 @@ Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or g **Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. + +**Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression; include declined IDs with governing reasons and evidence in the final user report. +Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. + **Execution Protocol**: -1. **Delegate all work** to sub-agents โ€” your role is to invoke sub-agents, pass data between them, and report results +1. **Invoke named specialists for deliverable production** โ€” pass data between them and validate their results 2. **Follow subagents-orchestration-guide skill planning flow**: - Execute steps defined below - **Stop and obtain approval** for plan content before completion @@ -71,7 +77,7 @@ Invoke document-reviewer to review the work plan: - `subagent_type`: "dev-workflows-fullstack:document-reviewer" - `description`: "Work plan review" - `prompt`: "doc_type: WorkPlan target: docs/plans/[plan-name].md. Review semantic traceability to the Design Doc, early verification placement, real-boundary verification coverage, Failure Mode Checklist, and Review Scope." -- The work plan is a derivation of the Design Doc, so plan-fidelity findings are resolved without user input while the revision loop makes observable progress. Branch on the reviewer's `verdict.decision`: on `needs_revision`, re-invoke work-planner in update mode with the findings and re-review, repeating until `approved` or `approved_with_conditions`; if the same blocking finding repeats without new evidence or a contract change, stop and escalate it. On `rejected`, escalate to the user. +- Apply the Review Resolution Gate before branching. On `needs_revision`, re-invoke work-planner in update mode with the `apply` findings and re-review with `prior_feedback`. A result whose actionable findings are all `decline` is eligible for approval; escalate unresolved `user_decision_required` or unusable inputs. ### Step 5: Present for Approval - Present the reviewed work plan to the user for batch approval. If the user requests changes, re-invoke work-planner with revised parameters and re-run Step 4. diff --git a/dev-workflows-fullstack/skills/recipe-front-review/SKILL.md b/dev-workflows-fullstack/skills/recipe-front-review/SKILL.md index 2c29c4b..f5429a6 100644 --- a/dev-workflows-fullstack/skills/recipe-front-review/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-front-review/SKILL.md @@ -5,6 +5,7 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. **Context**: Post-implementation quality assurance for React/TypeScript frontend @@ -12,7 +13,12 @@ Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or g **Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) -**First Action**: Register Steps 1-11 using TaskCreate before any execution. +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. + +**Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression; include declined IDs with governing reasons and evidence in the final user report. +Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. + +**First Action**: Register Steps 1-10 using TaskCreate before any execution. ## Execution Method @@ -56,17 +62,9 @@ Invoke security-reviewer using Agent tool: **If security-reviewer returned `blocked`**: Stop immediately. Report the blocked finding and escalate to user. Do not proceed to fix steps. -**Code compliance criteria (considering project stage)**: -- Prototype: Pass at 70%+ -- Production: 90%+ recommended - -**Security criteria**: -- `approved` or `approved_with_notes` โ†’ Pass -- `needs_revision` โ†’ Fail +Apply the Review Resolution Gate to both outputs before reporting or routing them. Finding dispositions determine routing; compliance percentages remain diagnostic. -**Report both results independently using subagent output fields only**: - -Before presenting to the user, the orchestrator computes a recommended route per finding using the rule below (this rule is internal โ€” do not include it in the user-facing prompt): +For each `apply` or `user_decision_required` finding, compute a proposed route using the rule below: | Finding pattern | Recommended route | |-----------------|-------------------| @@ -74,7 +72,7 @@ Before presenting to the user, the orchestrator computes a recommended route per | `dd_violation` where the code drifted from a still-correct Design Doc | `c` (Code-side fix) | | `reliability` / `security` / `maintainability` findings | `c` (Code-side fix) | -Then present to the user (label each finding with its recommended route, grouped by route): +Then present the adjudicated result to the user. Group `apply` and `user_decision_required` findings by proposed route, and list declined IDs with their reasons separately: ``` Code Compliance: [complianceRate from code-reviewer] @@ -97,23 +95,19 @@ Security Review: [status from security-reviewer] - [policy] [location]: [description] โ€” [rationale] [recommended: c] Notes: [notes from security-reviewer, if present] -Resolve discrepancies โ€” confirm or override the recommended route per finding: +Approve the proposed changes or decide unresolved items: c) Code-side fix โ€” code violates Design Doc; modify code to match d) Design-side update โ€” code is correct; Design Doc is stale, revise it - s) Skip โ€” accept current state without changes + s) Decline โ€” record the governing reason and accept current state ``` -Use AskUserQuestion. The default offer is **"accept all recommended routes"** โ€” a single confirmation for the typical case where the orchestrator's recommendations are correct. When the user wants to override, collect per-finding c/d/s decisions instead. If the user selects `s` for everything: skip Steps 5-10, proceed to Step 11. +This review command authorizes analysis; use AskUserQuestion to obtain separate implementation authority. The batch option is **"approve all proposed `apply` routes"** and its scope consists exclusively of those routes. Collect an explicit decision for each `user_decision_required` item. When the approved change set is empty, proceed directly to Step 10. Pass approved findings, routes, covered files/sections, and any stated total size budget to update or fix agents. Before re-validation, map every diff hunk to an approved finding or required consistency update; request a scope decision for unmapped or over-budget changes. -### Step 5: Execute Skill - -Execute Skill: documentation-criteria (for task file template) - -### Step 5d: Design-Side Update +### Step 5: Design-Side Update -Run this step only when the user routed at least one finding to `d`. When all routes are `c` or `s`, skip directly to Step 6. +Run this step only when the user routed at least one finding to `d`. When no `d` routes exist, skip it; continue to Step 6 only when approved `c` routes remain. 1. Invoke technical-designer-frontend in update mode using Agent tool: - `subagent_type`: "dev-workflows-fullstack:technical-designer-frontend" @@ -124,6 +118,7 @@ Run this step only when the user routed at least one finding to `d`. When all ro - `subagent_type`: "dev-workflows-fullstack:document-reviewer" - `description`: "Document review of updated Design Doc" - `prompt`: "Review updated Design Doc at [path] for consistency and completeness. doc_type: DesignDoc. review_context: update." + - Apply the Review Resolution Gate to this result. Route `apply` findings back to technical-designer-frontend and re-run document-reviewer with `prior_feedback`; stop for unresolved `user_decision_required`; proceed when the result is approved or every actionable finding is `decline`. 3. When multiple Design Docs exist (`ls docs/design/*.md | grep -v template | wc -l > 1`), invoke design-sync: - `subagent_type`: "dev-workflows-fullstack:design-sync" @@ -131,53 +126,44 @@ Run this step only when the user routed at least one finding to `d`. When all ro - `prompt`: "source_design: [updated DD path]. Detect conflicts across all Design Docs after the update." - When `sync_status: conflicts_found`: present conflicts to the user; resolution requires re-invoking technical-designer-frontend for affected DDs. -4. After Step 5d completes: - - If the user selected `d` for all findings (no `c` routes) โ†’ skip Steps 6-8, proceed to Step 9 for re-validation +4. After Step 5 completes: + - If the user selected `d` for all findings (no `c` routes) โ†’ skip Steps 6-7, proceed to Step 8 for re-validation - If the user selected both `d` and `c` โ†’ re-evaluate the `c`-routed findings against the updated DD and drop any that are now satisfied by the DD revision; then proceed to Step 6 with the remaining `c` findings -### Step 6: Create Task File - -Create task file at `docs/plans/tasks/review-fixes-YYYYMMDD.md` -Include both code compliance issues and security requiredFixes. - -### Step 7: Execute Fixes +### Step 6: Execute Fixes Invoke task-executor-frontend using Agent tool: - `subagent_type`: "dev-workflows-fullstack:task-executor-frontend" - `description`: "Execute review fixes" -- `prompt`: "Task file: docs/plans/tasks/review-fixes-YYYYMMDD.md. Apply staged fixes (stops at 5 files)." +- `prompt`: "Apply these approved code-side findings directly: [findings with IDs, governing sources, smallest correction, affected paths, and observable verification condition]. Keep the change within the approved routes and stated total size budget." -### Step 8: Quality Check +### Step 7: Quality Check Invoke quality-fixer-frontend using Agent tool: - `subagent_type`: "dev-workflows-fullstack:quality-fixer-frontend" - `description`: "Quality gate check" -- Pass Step 7 `mutationEvidence` and `qualityCommand` when available (caller first, otherwise current task). +- Pass Step 6 `filesModified` and `mutationEvidence`. - `prompt`: "Confirm quality gate passage for fixed files." -### Step 9: Re-validate code-reviewer +### Step 8: Re-validate code-reviewer Invoke code-reviewer using Agent tool: - `subagent_type`: "dev-workflows-fullstack:code-reviewer" - `description`: "Re-validate compliance" -- `prompt`: "Re-validate Design Doc compliance after fixes. Design Doc: [path]. Implementation files: [file list]. Prior compliance issues: $STEP_2_OUTPUT. Verify each prior issue is resolved (whether resolved code-side or design-side)." +- `prompt`: "Re-validate Design Doc compliance after fixes. Design Doc: [path]. Implementation files: [file list]. prior_feedback: [{id, disposition, correction?, reason?, evidence}]. Review the current state normally, then reconcile every prior item." -### Step 10: Re-validate security-reviewer +### Step 9: Re-validate security-reviewer Invoke security-reviewer using Agent tool (only if security fixes were applied): - `subagent_type`: "dev-workflows-fullstack:security-reviewer" - `description`: "Re-validate security" -- `prompt`: "Re-validate security after fixes. governingDocuments: [{\"type\":\"design-doc\",\"path\":\"[path]\"}]. implementationFiles: [file list]. Prior findings: $STEP_3_OUTPUT." - -### Step 11: Final Cleanup and Report +- `prompt`: "Re-validate security after fixes. governingDocuments: [{\"type\":\"design-doc\",\"path\":\"[path]\"}]. implementationFiles: [file list]. prior_feedback: [{id, disposition, correction?, reason?, evidence}]. Review the current state normally, then reconcile every prior item." -Delete the review-fix task file this recipe created (if any). Its work is committed; `docs/plans/` is ephemeral working state and is not retained between recipe runs: +Apply the Review Resolution Gate to every Step 8 and Step 9 result before Step 10. Route new `apply` findings through their approved design-side or code-side path and repeat the affected verification; stop for unresolved `user_decision_required`; proceed when each result is approved or every actionable finding is `decline`. -- Delete `docs/plans/tasks/review-fixes-YYYYMMDD.md` if it exists +### Step 10: Final Report -If the file cannot be deleted (filesystem error), report the failure but do not block the final report. - -Then present the final report: +Present the final report: ``` Code Compliance: @@ -191,8 +177,6 @@ Security Review: Remaining issues: - [items requiring manual intervention] - -Cleanup: review-fixes task file removed ``` ## Auto-fixable Items (code-side path) diff --git a/dev-workflows-fullstack/skills/recipe-fullstack-build/SKILL.md b/dev-workflows-fullstack/skills/recipe-fullstack-build/SKILL.md index acdca14..7794171 100644 --- a/dev-workflows-fullstack/skills/recipe-fullstack-build/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-fullstack-build/SKILL.md @@ -5,18 +5,24 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. ## Orchestrator Definition **Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. + +**Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression; include declined IDs with governing reasons and evidence in the final user report. +Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. + ## Required Reference **MANDATORY**: Read `references/monorepo-flow.md` from subagents-orchestration-guide skill BEFORE proceeding. Follow the Extended Task Cycle and Agent Routing defined there. ## Execution Protocol -1. **Delegate all work through Agent tool** โ€” invoke sub-agents, pass deliverable paths between them, and report results (permitted tools: see subagents-orchestration-guide "Orchestrator's Permitted Tools") +1. **Invoke named specialists for deliverable production** โ€” pass deliverable paths between them and validate their results (see subagents-orchestration-guide "Orchestrator Execution Boundary") 2. **Route agents by task filename pattern** (see monorepo-flow.md reference): - `*-backend-task-*` โ†’ task-executor + quality-fixer - `*-frontend-task-*` โ†’ task-executor-frontend + quality-fixer-frontend @@ -34,7 +40,7 @@ Work plan: $ARGUMENTS Before any task processing, locate the work plan. Resolution rule: 1. List task files in `docs/plans/tasks/` matching the layer-aware patterns `{plan-name}-backend-task-*.md` and `{plan-name}-frontend-task-*.md` only. Single-layer tasks (`{plan-name}-task-*.md`) are excluded here so a stale single-layer run does not redirect this recipe to the wrong work plan -2. From the matched files, also exclude every file matching any of these patterns โ€” they originate from other workflow phases and are not implementation tasks for this run's plan: `*-task-prep-*.md` (readiness preflight tasks), `_overview-*.md` (materialization overview file), `*-phase*-completion.md` (per-phase completion files), `review-fixes-*.md` (post-implementation review fixes), `integration-tests-*-task-*.md` (integration-test add-on scaffolding) +2. From the matched files, also exclude `_overview-*.md` (materialization overview files) and `*-phase*-completion.md` (per-phase completion files). 3. For each remaining file, extract the `{plan-name}` prefix as the segment that appears before `-backend-task-` or `-frontend-task-` 4. When at least one task file matches, the work plan is `docs/plans/{plan-name}.md` for the prefix that has the most recent task-file mtime; ties broken by the lexicographically last `{plan-name}` 5. When no task file matches the restricted pattern, the work plan is the most-recent-mtime non-template `.md` in `docs/plans/` @@ -44,7 +50,7 @@ Before any task processing, locate the work plan. Resolution rule: Compute the **Consumed Task Set** for this run โ€” the exact files this recipe owns, executes, and later deletes. Use the same restricted pattern as Work Plan Resolution: 1. List task files in `docs/plans/tasks/` matching the layer-aware patterns `{plan-name}-backend-task-*.md` and `{plan-name}-frontend-task-*.md` for the `{plan-name}` resolved by Work Plan Resolution. Single-layer tasks are excluded -2. Exclude every file matching: `*-task-prep-*.md`, `_overview-*.md`, `*-phase*-completion.md`, `review-fixes-*.md`, `integration-tests-*-task-*.md` (these originate from other workflow phases) +2. Exclude every file matching `_overview-*.md` or `*-phase*-completion.md`. Every subsequent reference to "task files" in this recipe โ€” Task Generation Decision Flow, Task Execution Cycle iteration, and Final Cleanup โ€” uses this set, not the unrestricted `docs/plans/tasks/*.md` glob. @@ -56,7 +62,7 @@ Analyze the Consumed Task Set and determine the action required: |-------|----------|-------------| | Tasks exist | Consumed Task Set is non-empty | User's execution instruction serves as batch approval โ†’ Enter autonomous execution immediately | | No tasks + plan exists | Consumed Task Set is empty but the resolved work plan exists | Confirm with user โ†’ run task-decomposer | -| Neither exists + Design Doc exists | No plan, no Consumed Task Set, but `docs/design/*.md` exists | Invoke work-planner to create work plan from Design Doc(s), then run document-reviewer (`dev-workflows-fullstack:document-reviewer`, doc_type: WorkPlan); branch on the reviewer's `verdict.decision` โ€” on `needs_revision`, re-invoke work-planner (update) and re-review until `approved`/`approved_with_conditions`; if the same blocking finding repeats without new evidence or a contract change, stop and escalate it; then present the reviewed plan for batch approval before task materialization; on `rejected`, stop before task materialization and escalate to the user | +| Neither exists + Design Doc exists | No plan, no Consumed Task Set, but `docs/design/*.md` exists | Invoke work-planner to create a work plan, then run document-reviewer (`dev-workflows-fullstack:document-reviewer`, doc_type: WorkPlan). Apply the Review Resolution Gate: update for `apply`, re-review with `prior_feedback`, progress when all actionable findings are `decline`, and escalate unresolved `user_decision_required`; then present the resolved plan for batch approval before task materialization | | Neither exists | No plan, no Consumed Task Set, no Design Doc | Report missing prerequisites to user and stop | ## Task Materialization Phase (Conditional) @@ -110,9 +116,12 @@ For EACH task, YOU MUST: 2. **BRANCH ON EXECUTOR RESULT**: - `status: "escalation_needed"` or `"blocked"` โ†’ STOP and escalate to user - `requiresTestReview` is `true` โ†’ Invoke integration-test-reviewer with `diffBase`, changed integration/E2E paths, `taskFile`, prompt-only claims, and `mutationEvidence` - - `needs_revision` โ†’ Return to step 1 with `requiredFixes` - `approved` โ†’ Proceed to step 3 - `blocked` โ†’ STOP and escalate to user + - `needs_revision` โ†’ Apply the Review Resolution Gate + - one or more `apply` findings โ†’ Return to step 1 with those findings, then re-review with `prior_feedback` + - every actionable finding is `decline` โ†’ Proceed to step 3 + - any unresolved `user_decision_required` finding โ†’ STOP and escalate to user - `readyForQualityCheck: true` โ†’ Proceed to step 3 3. **QUALITY-FIX**: Invoke the layer-appropriate quality-fixer with `task_file`, upstream `mutationEvidence`, and `qualityCommand` when available (caller first, otherwise current task) - `stub_detected` โ†’ Return to step 1 with `incompleteImplementations[]` details @@ -164,4 +173,5 @@ Final report must include: - Quality check result - Commit count - Cleanup result +- Declined actionable findings with ID, governing reason, and evidence - Escalation or blocking summary, if any diff --git a/dev-workflows-fullstack/skills/recipe-fullstack-implement/SKILL.md b/dev-workflows-fullstack/skills/recipe-fullstack-implement/SKILL.md index 8c80121..0b32140 100644 --- a/dev-workflows-fullstack/skills/recipe-fullstack-implement/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-fullstack-implement/SKILL.md @@ -5,6 +5,7 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. **Context**: Full-cycle fullstack implementation management (Requirements Analysis โ†’ Design (backend + frontend) โ†’ Planning โ†’ Implementation โ†’ Quality Assurance) @@ -12,13 +13,18 @@ Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or g **Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. + +**Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression; include declined IDs with governing reasons and evidence in the final user report. +Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. + ## Required Reference **MANDATORY**: Read `references/monorepo-flow.md` from subagents-orchestration-guide skill BEFORE proceeding. Follow the Fullstack Flow defined there instead of the standard single-layer flow. ## Execution Protocol -1. **Delegate all work through Agent tool** โ€” invoke sub-agents, pass deliverable paths between them, and report results (permitted tools: see subagents-orchestration-guide "Orchestrator's Permitted Tools") +1. **Invoke named specialists for deliverable production** โ€” pass deliverable paths between them and validate their results (see subagents-orchestration-guide "Orchestrator Execution Boundary") 2. **Follow monorepo-flow.md** for the design phase (multiple Design Docs, design-sync, vertical slicing) 3. **Follow subagents-orchestration-guide skill** for all other orchestration rules (stop points, structured responses, escalation) 4. **Enter autonomous mode** only after "batch approval for entire implementation phase" @@ -48,6 +54,8 @@ When continuing existing flow, verify: ### 3. Design through Planning Phase +Execute Skill: external-resource-context before running the external resource hearing in monorepo-flow.md. + **Follow monorepo-flow.md** for the complete design-through-planning flow (Steps 1-17 for Large scale, Steps 1-15 for Medium scale). The flow table in that reference defines every step, agent invocation, parallelization rule, and stop point. Key points to enforce as the orchestrator runs the flow: @@ -64,6 +72,8 @@ After scale determination, use TaskCreate to register each design/planning step ## After requirement-analyzer [Stop] +Execute Skill: requirement-convergence before running the hearing protocol. + Run the requirement-convergence hearing protocol on the returned `convergence` object before presenting anything else, using the analyzer's scope facts and cost band as the facts it presents. When user responds to questions: @@ -113,8 +123,14 @@ Escalate when the required fix or investigation falls outside that scope. **Rules**: 1. Execute ONE task completely before starting next (each task goes through the full 4-step cycle via Agent tool, using the correct executor per filename pattern) -2. Check executor status before quality-fixer (escalation check) -3. Run quality-fixer after each executor with `task_file`, upstream `mutationEvidence`, and `qualityCommand` when available (caller first, otherwise current task) +2. Check executor status before quality-fixer (escalation check). When `requiresTestReview` is `true`, invoke integration-test-reviewer with `diffBase`, changed integration/E2E paths, `taskFile`, prompt claims, and `mutationEvidence`, then branch on its status: + - `approved` โ†’ Continue to rule 3 + - `blocked` โ†’ Escalate to user + - `needs_revision` โ†’ Apply the Review Resolution Gate + - one or more `apply` findings โ†’ Return them to the layer executor, then re-review with `prior_feedback` + - every actionable finding is `decline` โ†’ Continue to rule 3 + - any unresolved `user_decision_required` finding โ†’ Escalate to user +3. Run the layer quality-fixer after the executor and any required test-review loop completes, passing `task_file`, upstream `mutationEvidence`, and `qualityCommand` when available (caller first, otherwise current task) 4. Check quality-fixer response: - `stub_detected` โ†’ Return to executor with `incompleteImplementations[]` details - `blocked` โ†’ Escalate to user @@ -147,9 +163,7 @@ After acceptance-test-generator execution, when invoking work-planner (subagent_ - Generated fixture-e2e test file path or null (from `generatedFiles.fixtureE2e`) - Generated service-integration-e2e test file path or null (from `generatedFiles.serviceE2e`) - Per-lane E2E absence reason (from `e2eAbsenceReason.fixtureE2e` and `e2eAbsenceReason.serviceE2e`, when each lane is null) -- Explicit note: integration tests are created simultaneously with implementation, fixture-e2e tests are created alongside the UI feature phase, service-integration-e2e tests are executed only in the final phase ## Execution Method -All work is executed through sub-agents. -Sub-agent selection follows monorepo-flow.md reference and subagents-orchestration-guide skill. +Deliverable production is executed through the specialist selected by monorepo-flow.md and subagents-orchestration-guide; workflow decisions and returned-result validation remain with the orchestrator. diff --git a/dev-workflows-fullstack/skills/recipe-implement/SKILL.md b/dev-workflows-fullstack/skills/recipe-implement/SKILL.md index aba66ea..0e0cd84 100644 --- a/dev-workflows-fullstack/skills/recipe-implement/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-implement/SKILL.md @@ -5,6 +5,7 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. **Context**: Full-cycle implementation management (Requirements Analysis โ†’ Design โ†’ Planning โ†’ Implementation โ†’ Quality Assurance) @@ -12,8 +13,13 @@ Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or g **Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. + +**Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression; include declined IDs with governing reasons and evidence in the final user report. +Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. + **Execution Protocol**: -1. **Delegate all work through Agent tool** โ€” invoke sub-agents, pass deliverable paths between them, and report results (permitted tools: see subagents-orchestration-guide "Orchestrator's Permitted Tools") +1. **Invoke named specialists for deliverable production** โ€” pass deliverable paths between them and validate their results (see subagents-orchestration-guide "Orchestrator Execution Boundary") 2. **Follow subagents-orchestration-guide skill flows exactly**: - Execute one step at a time in the defined flow (Large/Medium/Small scale) - When flow specifies "Execute document-reviewer" โ†’ Execute it immediately @@ -53,6 +59,8 @@ When continuing existing flow, verify: ### After requirement-analyzer [Stop] +Execute Skill: requirement-convergence before running the hearing protocol. + Run the requirement-convergence hearing protocol on the returned `convergence` object before presenting anything else, using the analyzer's scope facts and cost band as the facts it presents. When user responds to questions: @@ -102,9 +110,12 @@ Escalate when the required fix or investigation falls outside that scope. 2. Check task-executor response: - `status: escalation_needed` or `blocked` โ†’ Escalate to user - `requiresTestReview` is `true` โ†’ Invoke integration-test-reviewer with `diffBase`, changed integration/E2E paths, `taskFile`, prompt-only claims, and `mutationEvidence` - - `needs_revision` โ†’ Return to step 1 with `requiredFixes` - `approved` โ†’ Proceed to step 3 - `blocked` โ†’ Escalate to user + - `needs_revision` โ†’ Apply the Review Resolution Gate + - one or more `apply` findings โ†’ Return to step 1 with those findings, then re-review with `prior_feedback` + - every actionable finding is `decline` โ†’ Proceed to step 3 + - any unresolved `user_decision_required` finding โ†’ Escalate to user - Otherwise โ†’ Proceed to step 3 3. quality-fixer โ†’ Pass `task_file`, upstream `mutationEvidence`, and `qualityCommand` when available (caller first, otherwise current task); run quality checks and fixes - `stub_detected` โ†’ Return to step 1 with `incompleteImplementations[]` details @@ -139,9 +150,7 @@ After acceptance-test-generator execution, when invoking work-planner (subagent_ - Generated fixture-e2e test file path or null (from `generatedFiles.fixtureE2e`) - Generated service-integration-e2e test file path or null (from `generatedFiles.serviceE2e`) - Per-lane E2E absence reason (from `e2eAbsenceReason.fixtureE2e` and `e2eAbsenceReason.serviceE2e`, when each lane is null) -- Explicit note: integration tests are created simultaneously with implementation, fixture-e2e tests are created alongside the UI feature phase, service-integration-e2e tests are executed only in the final phase ## Execution Method -All work is executed through sub-agents. -Sub-agent selection follows subagents-orchestration-guide skill. +Deliverable production is executed through the specialist selected by subagents-orchestration-guide; workflow decisions and returned-result validation remain with the orchestrator. diff --git a/dev-workflows-fullstack/skills/recipe-plan/SKILL.md b/dev-workflows-fullstack/skills/recipe-plan/SKILL.md index cd37087..84409e8 100644 --- a/dev-workflows-fullstack/skills/recipe-plan/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-plan/SKILL.md @@ -5,6 +5,7 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. **Context**: Dedicated to the planning phase. @@ -12,8 +13,13 @@ Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or g **Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. + +**Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression; include declined IDs with governing reasons and evidence in the final user report. +Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. + **Execution Protocol**: -1. **Delegate all work** to sub-agents โ€” your role is to invoke sub-agents, pass data between them, and report results +1. **Invoke named specialists for deliverable production** โ€” pass data between them and validate their results 2. **Follow subagents-orchestration-guide skill planning flow exactly**: - Execute steps defined below - **Stop and obtain approval** for plan content before completion @@ -66,7 +72,7 @@ Invoke document-reviewer to review the work plan: - `subagent_type`: "dev-workflows-fullstack:document-reviewer" - `description`: "Work plan review" - `prompt`: "doc_type: WorkPlan target: docs/plans/[plan-name].md. Review semantic traceability to the Design Doc, early verification placement, real-boundary verification coverage, Failure Mode Checklist, and Review Scope." -- The work plan is a derivation of the Design Doc, so plan-fidelity findings are resolved without user input while the revision loop makes observable progress. Branch on the reviewer's `verdict.decision`: on `needs_revision`, re-invoke work-planner in update mode with the findings and re-review, repeating until `approved` or `approved_with_conditions`; if the same blocking finding repeats without new evidence or a contract change, stop and escalate it. On `rejected`, escalate to the user. +- Apply the Review Resolution Gate before branching. On `needs_revision`, re-invoke work-planner in update mode with the `apply` findings and re-review with `prior_feedback`. A result whose actionable findings are all `decline` is eligible for approval; escalate unresolved `user_decision_required` or unusable inputs. ### Step 5: Present for Approval - Present the reviewed work plan to the user for batch approval. If the user requests changes, re-invoke work-planner with revised parameters and re-run Step 4. diff --git a/dev-workflows-fullstack/skills/recipe-prepare-implementation/SKILL.md b/dev-workflows-fullstack/skills/recipe-prepare-implementation/SKILL.md index 1117e6f..046dbea 100644 --- a/dev-workflows-fullstack/skills/recipe-prepare-implementation/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-prepare-implementation/SKILL.md @@ -5,17 +5,20 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. -**Context**: Optional readiness phase between work-plan approval and recipe-*-build. Confirms the implementation will be observable from Phase 1 onward and resolves any gaps via Phase 0 tasks. Exits no-op when the readiness criteria already pass, so the recipe is safe to invoke unconditionally. +**Context**: Optional readiness phase between work-plan approval and recipe-*-build. Confirms the implementation will be observable from Phase 1 onward and resolves any gaps before build execution. Exits no-op when the readiness criteria already pass, so the recipe is safe to invoke unconditionally. ## Orchestrator Definition **Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. + **Execution Protocol**: -1. **Delegate all work through Agent tool** โ€” invoke sub-agents, pass deliverable paths between them, and report results (permitted tools: see subagents-orchestration-guide "Orchestrator's Permitted Tools") -2. **Self-contained scope**: When gaps are found, this recipe BOTH generates resolution tasks AND executes them through the standard 4-step cycle. Recipe completes only when readiness criteria pass or remaining gaps are escalated. -3. **No-op exit**: When the readiness scan finds no failing criteria, generate no resolution tasks and exit immediately, presenting the Readiness Report to the user. No files are modified in this branch. +1. **Invoke named specialists for deliverable production** โ€” pass deliverable paths between them and validate their results (see subagents-orchestration-guide "Orchestrator Execution Boundary") +2. **Self-contained scope**: When gaps are found, this recipe defines resolution items and executes them through the standard 4-step cycle. Recipe completes only when readiness criteria pass or remaining gaps are escalated. +3. **No-op exit**: When the readiness scan finds no failing criteria, generate no resolution items and exit immediately, presenting the Readiness Report to the user. No files are modified in this branch. Work plan: $ARGUMENTS @@ -84,48 +87,44 @@ When every applicable criterion is `pass` (zero `fail`): When one or more criteria are `fail` โ†’ proceed to Step 4. -### Step 4: Plan Resolution Tasks +### Step 4: Plan Resolution Items For each `fail` criterion: -1. Determine the smallest concrete task that closes the gap (examples: "Add fixture entry for ComponentX covering loading/empty/error states", "Add seed script for E2E user fixtures", "Document local startup commands in docs/run/local.md") -2. Decide the task's **layer** by matching every target file path against the markers below: +1. Determine the smallest concrete correction that closes the gap (examples: "Add fixture entry for ComponentX covering loading/empty/error states", "Add seed script for E2E user fixtures", "Document local startup commands in docs/run/local.md") +2. Decide the resolution item's **layer** by matching every target file path against the markers below: - **backend** when every target file path matches one of: `**/api/**`, `**/server/**`, `**/services/**`, `**/backend/**`, `**/handlers/**`, `**/repositories/**` - **frontend** when every target file path matches one of: `**/components/**`, `**/pages/**`, `**/web/**`, `**/frontend/**`, `**/*.tsx`, `**/*.jsx` - - **mixed** (target files span both backend and frontend markers) โ†’ escalate to user; ask the user to split the gap into per-layer tasks - - **unrecognized** (any target file matches neither backend nor frontend markers โ€” e.g., `docs/**`, `scripts/**`, root-level configs, fixture data files outside the markers above) โ†’ escalate to user; ask the user to either (a) decide which layer's executor / quality-fixer should run the task, or (b) update the markers if the project uses different paths + - **mixed** (target files span both backend and frontend markers) โ†’ escalate to user; ask the user to split the gap into per-layer items + - **unrecognized** (any target file matches neither backend nor frontend markers โ€” e.g., `docs/**`, `scripts/**`, root-level configs, fixture data files outside the markers above) โ†’ escalate to user; ask the user to either (a) decide which layer's executor / quality-fixer should run the item, or (b) update the markers if the project uses different paths Apply the rules in the order above. The first matching rule wins; "unrecognized" is the final fallback rather than a catch-all that defaults to backend. -3. Create a Phase 0 task file at `docs/plans/tasks/{plan-name}-backend-task-prep-{NN}.md` (backend) or `docs/plans/tasks/{plan-name}-frontend-task-prep-{NN}.md` (frontend) using the task template from documentation-criteria skill. The `-task-prep-` segment lets recipe-prepare-implementation distinguish prep tasks from implementation tasks while keeping the existing `{plan-name}-{layer}-task-*` matcher used by other recipes -4. Update the work plan to insert these tasks as Phase 0 (before Phase 1) -Present the proposed resolution task list to the user with AskUserQuestion. Proceed only after explicit approval โ€” this is the single human gate inside this recipe. +Present the proposed resolution item list to the user with AskUserQuestion. Proceed only after explicit approval โ€” this is the single human gate inside this recipe. -### Step 5: Execute Resolution Tasks +### Step 5: Execute Resolution Items -For each resolution task, run the standard 4-step cycle (see subagents-orchestration-guide "Task Management: 4-Step Cycle"): +For each approved resolution item, run execute โ†’ branch โ†’ quality-fix โ†’ commit: -1. **Agent tool** โ€” route by filename layer segment: - - `*-backend-task-prep-*` โ†’ `subagent_type: "dev-workflows-fullstack:task-executor"` - - `*-frontend-task-prep-*` โ†’ `subagent_type: "dev-workflows-fullstack:task-executor-frontend"` - - Filename without a recognized layer segment โ†’ escalate (the file should not exist; Step 4 prevents this) +1. **Agent tool** โ€” route by the item's layer: + - `backend` โ†’ `subagent_type: "dev-workflows-fullstack:task-executor"` + - `frontend` โ†’ `subagent_type: "dev-workflows-fullstack:task-executor-frontend"` + - Pass the exact resolution item, governing documents, target paths, and verification condition directly 2. Check escalation per orchestration-guide -3. **quality-fixer** โ€” route by the same filename layer segment: - - `*-backend-task-prep-*` โ†’ `"dev-workflows-fullstack:quality-fixer"` - - `*-frontend-task-prep-*` โ†’ `"dev-workflows-fullstack:quality-fixer-frontend"` - - Pass upstream `mutationEvidence` and `qualityCommand` when available (caller first, otherwise current task). +3. **quality-fixer** โ€” route by the same Executor lane: + - `backend` โ†’ `"dev-workflows-fullstack:quality-fixer"` + - `frontend` โ†’ `"dev-workflows-fullstack:quality-fixer-frontend"` + - Pass upstream `filesModified` and `mutationEvidence`. 4. **Commit** when quality-fixer returns `approved` Append the Scope Boundary block (below) to every subagent prompt. -### Step 6: Re-scan, Present Readiness Report, Cleanup, Exit - -1. **Re-scan**: Re-run the Step 2 readiness scan after all resolution tasks are committed. +### Step 6: Re-scan, Present Readiness Report, Exit -2. **Present Readiness Report**: Present the Readiness Report (see Output Format below) to the user. The report is shown in-session and is not written into the work plan โ€” the durable output of this recipe is the committed Phase 0 resolution tasks, not a persisted report. +1. **Re-scan**: Re-run the Step 2 readiness scan after all resolution items are committed. -3. **Final Cleanup**: Delete every prep task file this recipe created for the current `{plan-name}` (`docs/plans/tasks/{plan-name}-backend-task-prep-*.md` and `docs/plans/tasks/{plan-name}-frontend-task-prep-*.md`) AND the phase-completion file generated for prep phases (`docs/plans/tasks/{plan-name}-phase0-completion.md` when present, since prep tasks live in Phase 0). Prep task files for other plans are out of scope โ€” this recipe deletes only what it created for the current run. Their work is committed; `docs/plans/` is ephemeral working state and is not retained between recipe runs. The work plan itself is preserved for the downstream recipe-*-build / recipe-*-implement. +2. **Present Readiness Report**: Present the Readiness Report (see Output Format below) to the user. The report is shown in-session and is not written into the work plan โ€” the durable output is the committed readiness fixes. -4. **Exit**: +3. **Exit**: | Re-scan result | Action | |----------------|--------| @@ -164,8 +163,8 @@ Gaps resolved: [N] | R4 | ... | ... | | R5 | ... | ... | -### Resolution Tasks Executed (when gaps_resolved > 0) -- [task file path] โ€” [one-line summary] โ€” committed +### Resolution Items Executed (when gaps_resolved > 0) +- [criterion ID] โ€” [one-line summary] โ€” committed - ... ### Remaining Gaps (when outcome is escalated) @@ -176,7 +175,6 @@ Gaps resolved: [N] - [ ] Work plan loaded and Verification Strategy / E2E references / Phase structure extracted - [ ] Readiness scan run with per-criterion result and evidence recorded -- [ ] No-op exit when all `pass`, OR resolution tasks generated, approved, and executed via the 4-step cycle -- [ ] Re-scan run after the last resolution task commits -- [ ] Prep task files (and Phase 0 phase-completion file when generated) deleted from `docs/plans/tasks/` +- [ ] No-op exit when all `pass`, OR resolution items planned, approved, and executed via the 4-step cycle +- [ ] Re-scan run after the last resolution item commits - [ ] Final report presented to the user diff --git a/dev-workflows-fullstack/skills/recipe-reverse-engineer/SKILL.md b/dev-workflows-fullstack/skills/recipe-reverse-engineer/SKILL.md index 03b39a3..8f631e0 100644 --- a/dev-workflows-fullstack/skills/recipe-reverse-engineer/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-reverse-engineer/SKILL.md @@ -5,6 +5,7 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. **Context**: Reverse engineering workflow to create documentation from existing code @@ -14,10 +15,15 @@ Target: $ARGUMENTS **Core Identity**: "I am an orchestrator." +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. + +**Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression; include declined IDs with governing reasons and evidence in the final user report. +Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. + **Execution Protocol**: -1. **Delegate all work through Agent tool** โ€” invoke sub-agents, pass deliverable paths between them, and report results (permitted tools: see subagents-orchestration-guide "Orchestrator's Permitted Tools") +1. **Invoke named specialists for deliverable production** โ€” pass deliverable paths between them and validate their results (see subagents-orchestration-guide "Orchestrator Execution Boundary") 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 +3. **Preserve evidence while bridging outputs** โ€” extract and transform the fields required by the next specialist without changing supported meaning; apply Review Resolution before routing any correction **Task Registration**: Register phases first using TaskCreate, then steps within each phase as you enter it. Update status using TaskUpdate. @@ -163,10 +169,7 @@ prompt: | #### Step 5: Revision (conditional) -**Trigger Conditions** (any one of the following): -- Review status is "Needs Revision" or "Rejected" -- Critical discrepancies exist in `$STEP_3_OUTPUT` -- consistencyScore < 70 +Pass `$STEP_3_OUTPUT` to document-reviewer as verification evidence, then apply the Review Resolution Gate to `$STEP_4_OUTPUT`. Run revision only when at least one finding is `apply`; a decline-only result completes the review, and unresolved `user_decision_required` stops for user input. **Agent tool invocation**: ``` @@ -178,21 +181,17 @@ prompt: | Operation Mode: update Existing PRD: $STEP_2_OUTPUT - ## Review Feedback - $STEP_4_OUTPUT + ## Adjudicated Findings + [apply findings with IDs, governing basis, smallest correction, and affected sections] - ## Code Verification Results - $STEP_3_OUTPUT - - Address discrepancies by severity. Critical and major items require correction. - Minor items: correct if straightforward, otherwise leave as-is with rationale. + Treat these findings as the complete revision scope and preserve adjacent content. ``` -**Loop Control**: Maximum 2 revision cycles. After 2 cycles, flag for human review regardless of status. +**Re-validation**: After each revision, re-run code-verifier on the revised document, then re-run document-reviewer with the latest `code_verification` and `prior_feedback`. #### Unit Completion -- [ ] Review status is "Approved" or "Approved with Conditions" +- [ ] No `apply` findings remain; every other review finding has a disposition and every `user_decision_required` item has a recorded user decision - [ ] Human review passed (if enabled in Step 0) **Next**: Proceed to next unit. After all units โ†’ Phase 2. @@ -361,10 +360,7 @@ prompt: | #### Step 10: Revision (conditional) -**Trigger Conditions** (same as Step 5): -- Review status is "Needs Revision" or "Rejected" -- Critical discrepancies exist in `$STEP_8_OUTPUT` -- consistencyScore < 70 +Pass `$STEP_8_OUTPUT` to document-reviewer as verification evidence, then apply the Review Resolution Gate to `$STEP_9_OUTPUT`. Run revision only when at least one finding is `apply`; a decline-only result completes the review, and unresolved `user_decision_required` stops for user input. **Agent tool invocation (per Design Doc)**: ``` @@ -376,21 +372,17 @@ prompt: | Operation Mode: update Existing Design Doc: $STEP_7_OUTPUT (or $STEP_7a_OUTPUT / $STEP_7b_OUTPUT) - ## Review Feedback - $STEP_9_OUTPUT - - ## Code Verification Results - $STEP_8_OUTPUT + ## Adjudicated Findings + [apply findings with IDs, governing basis, smallest correction, and affected sections] - Address discrepancies by severity. Critical and major items require correction. - Minor items: correct if straightforward, otherwise leave as-is with rationale. + Treat these findings as the complete revision scope and preserve adjacent content. ``` -**Loop Control**: Maximum 2 revision cycles. After 2 cycles, flag for human review regardless of status. +**Re-validation**: After each revision, re-run code-verifier on the revised document, then re-run document-reviewer with the latest `code_verification` and `prior_feedback`. #### Unit Completion -- [ ] Review status is "Approved" or "Approved with Conditions" +- [ ] No `apply` findings remain; every other review finding has a disposition and every `user_decision_required` item has a recorded user decision - [ ] Human review passed (if enabled in Step 0) **Next**: Proceed to next unit. After all units โ†’ Final Report. @@ -409,4 +401,3 @@ Output summary including: | Discovery finds nothing | Ask user for project structure hints | | Generation fails | Log failure, continue with other units, report in summary | | consistencyScore < 50 | Flag for mandatory human review โ€” require explicit human approval | -| Review rejects after 2 revisions | Stop loop, flag for human intervention | diff --git a/dev-workflows-fullstack/skills/recipe-review/SKILL.md b/dev-workflows-fullstack/skills/recipe-review/SKILL.md index c724e75..f1afe83 100644 --- a/dev-workflows-fullstack/skills/recipe-review/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-review/SKILL.md @@ -5,6 +5,7 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. **Context**: Post-implementation quality assurance @@ -12,7 +13,12 @@ Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or g **Core Identity**: "I am an orchestrator." -**First Action**: Register Steps 1-11 using TaskCreate before any execution. +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. + +**Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression; include declined IDs with governing reasons and evidence in the final user report. +Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. + +**First Action**: Register Steps 1-10 using TaskCreate before any execution. ## Execution Method @@ -56,17 +62,9 @@ Invoke security-reviewer using Agent tool: **If security-reviewer returned `blocked`**: Stop immediately. Report the blocked finding and escalate to user. Do not proceed to fix steps. -**Code compliance criteria (considering project stage)**: -- Prototype: Pass at 70%+ -- Production: 90%+ recommended - -**Security criteria**: -- `approved` or `approved_with_notes` โ†’ Pass -- `needs_revision` โ†’ Fail +Apply the Review Resolution Gate to both outputs before reporting or routing them. Finding dispositions determine routing; compliance percentages remain diagnostic. -**Report both results independently using subagent output fields only**: - -Before presenting to the user, the orchestrator computes a recommended route per finding using the rule below (this rule is internal โ€” do not include it in the user-facing prompt): +For each `apply` or `user_decision_required` finding, compute a proposed route using the rule below: | Finding pattern | Recommended route | |-----------------|-------------------| @@ -74,7 +72,7 @@ Before presenting to the user, the orchestrator computes a recommended route per | `dd_violation` where the code drifted from a still-correct Design Doc | `c` (Code-side fix) | | `reliability` / `security` / `maintainability` findings | `c` (Code-side fix) | -Then present to the user (label each finding with its recommended route, grouped by route): +Then present the adjudicated result to the user. Group `apply` and `user_decision_required` findings by proposed route, and list declined IDs with their reasons separately: ``` Code Compliance: [complianceRate from code-reviewer] @@ -97,23 +95,19 @@ Security Review: [status from security-reviewer] - [policy] [location]: [description] โ€” [rationale] [recommended: c] Notes: [notes from security-reviewer, if present] -Resolve discrepancies โ€” confirm or override the recommended route per finding: +Approve the proposed changes or decide unresolved items: c) Code-side fix โ€” code violates Design Doc; modify code to match d) Design-side update โ€” code is correct; Design Doc is stale, revise it - s) Skip โ€” accept current state without changes + s) Decline โ€” record the governing reason and accept current state ``` -Use AskUserQuestion. The default offer is **"accept all recommended routes"** โ€” a single confirmation for the typical case where the orchestrator's recommendations are correct. When the user wants to override, collect per-finding c/d/s decisions instead. If the user selects `s` for everything: skip Steps 5-10, proceed to Step 11. +This review command authorizes analysis; use AskUserQuestion to obtain separate implementation authority. The batch option is **"approve all proposed `apply` routes"** and its scope consists exclusively of those routes. Collect an explicit decision for each `user_decision_required` item. When the approved change set is empty, proceed directly to Step 10. Pass approved findings, routes, covered files/sections, and any stated total size budget to update or fix agents. Before re-validation, map every diff hunk to an approved finding or required consistency update; request a scope decision for unmapped or over-budget changes. -### Step 5: Execute Skill - -Execute Skill: documentation-criteria (for task file template) - -### Step 5d: Design-Side Update +### Step 5: Design-Side Update -Run this step only when the user routed at least one finding to `d`. When all routes are `c` or `s`, skip directly to Step 6. +Run this step only when the user routed at least one finding to `d`. When no `d` routes exist, skip it; continue to Step 6 only when approved `c` routes remain. 1. Invoke technical-designer in update mode using Agent tool: - `subagent_type`: "dev-workflows-fullstack:technical-designer" @@ -124,6 +118,7 @@ Run this step only when the user routed at least one finding to `d`. When all ro - `subagent_type`: "dev-workflows-fullstack:document-reviewer" - `description`: "Document review of updated Design Doc" - `prompt`: "Review updated Design Doc at [path] for consistency and completeness. doc_type: DesignDoc. review_context: update." + - Apply the Review Resolution Gate to this result. Route `apply` findings back to technical-designer and re-run document-reviewer with `prior_feedback`; stop for unresolved `user_decision_required`; proceed when the result is approved or every actionable finding is `decline`. 3. When multiple Design Docs exist (`ls docs/design/*.md | grep -v template | wc -l > 1`), invoke design-sync: - `subagent_type`: "dev-workflows-fullstack:design-sync" @@ -131,53 +126,44 @@ Run this step only when the user routed at least one finding to `d`. When all ro - `prompt`: "source_design: [updated DD path]. Detect conflicts across all Design Docs after the update." - When `sync_status: conflicts_found`: present conflicts to the user; resolution requires re-invoking technical-designer for affected DDs. -4. After Step 5d completes: - - If the user selected `d` for all findings (no `c` routes) โ†’ skip Steps 6-8, proceed to Step 9 for re-validation +4. After Step 5 completes: + - If the user selected `d` for all findings (no `c` routes) โ†’ skip Steps 6-7, proceed to Step 8 for re-validation - If the user selected both `d` and `c` โ†’ re-evaluate the `c`-routed findings against the updated DD and drop any that are now satisfied by the DD revision; then proceed to Step 6 with the remaining `c` findings -### Step 6: Create Task File - -Create task file at `docs/plans/tasks/review-fixes-YYYYMMDD.md` -Include both code compliance issues and security requiredFixes. - -### Step 7: Execute Fixes +### Step 6: Execute Fixes Invoke task-executor using Agent tool: - `subagent_type`: "dev-workflows-fullstack:task-executor" - `description`: "Execute review fixes" -- `prompt`: "Task file: docs/plans/tasks/review-fixes-YYYYMMDD.md. Apply staged fixes (stops at 5 files)." +- `prompt`: "Apply these approved code-side findings directly: [findings with IDs, governing sources, smallest correction, affected paths, and observable verification condition]. Keep the change within the approved routes and stated total size budget." -### Step 8: Quality Check +### Step 7: Quality Check Invoke quality-fixer using Agent tool: - `subagent_type`: "dev-workflows-fullstack:quality-fixer" - `description`: "Quality gate check" -- Pass Step 7 `mutationEvidence` and `qualityCommand` when available (caller first, otherwise current task). +- Pass Step 6 `filesModified` and `mutationEvidence`. - `prompt`: "Confirm quality gate passage for fixed files." -### Step 9: Re-validate code-reviewer +### Step 8: Re-validate code-reviewer Invoke code-reviewer using Agent tool: - `subagent_type`: "dev-workflows-fullstack:code-reviewer" - `description`: "Re-validate compliance" -- `prompt`: "Re-validate Design Doc compliance after fixes. Prior compliance issues: $STEP_2_OUTPUT. Verify each prior issue is resolved (whether resolved code-side or design-side)." +- `prompt`: "Re-validate Design Doc compliance after fixes. Design Doc: [path]. Implementation files: [file list]. prior_feedback: [{id, disposition, correction?, reason?, evidence}]. Review the current state normally, then reconcile every prior item." -### Step 10: Re-validate security-reviewer +### Step 9: Re-validate security-reviewer Invoke security-reviewer using Agent tool (only if security fixes were applied): - `subagent_type`: "dev-workflows-fullstack:security-reviewer" - `description`: "Re-validate security" -- `prompt`: "Re-validate security after fixes. governingDocuments: [{\"type\":\"design-doc\",\"path\":\"[path]\"}]. implementationFiles: [file list]. Prior findings: $STEP_3_OUTPUT." - -### Step 11: Final Cleanup and Report +- `prompt`: "Re-validate security after fixes. governingDocuments: [{\"type\":\"design-doc\",\"path\":\"[path]\"}]. implementationFiles: [file list]. prior_feedback: [{id, disposition, correction?, reason?, evidence}]. Review the current state normally, then reconcile every prior item." -Delete the review-fix task file this recipe created (if any). Its work is committed; `docs/plans/` is ephemeral working state and is not retained between recipe runs: +Apply the Review Resolution Gate to every Step 8 and Step 9 result before Step 10. Route new `apply` findings through their approved design-side or code-side path and repeat the affected verification; stop for unresolved `user_decision_required`; proceed when each result is approved or every actionable finding is `decline`. -- Delete `docs/plans/tasks/review-fixes-YYYYMMDD.md` if it exists +### Step 10: Final Report -If the file cannot be deleted (filesystem error), report the failure but do not block the final report. - -Then present the final report: +Present the final report: ``` Code Compliance: @@ -191,8 +177,6 @@ Security Review: Remaining issues: - [items requiring manual intervention] - -Cleanup: review-fixes task file removed ``` ## Auto-fixable Items (code-side path) diff --git a/dev-workflows-fullstack/skills/recipe-task/SKILL.md b/dev-workflows-fullstack/skills/recipe-task/SKILL.md index 2f89f7e..86c7198 100644 --- a/dev-workflows-fullstack/skills/recipe-task/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-task/SKILL.md @@ -5,6 +5,7 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. # Task Execution with Metacognitive Analysis diff --git a/dev-workflows-fullstack/skills/recipe-update-doc/SKILL.md b/dev-workflows-fullstack/skills/recipe-update-doc/SKILL.md index 6bdeb54..73c3256 100644 --- a/dev-workflows-fullstack/skills/recipe-update-doc/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-update-doc/SKILL.md @@ -5,6 +5,7 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. **Context**: Dedicated to updating existing design documents. @@ -12,10 +13,15 @@ Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or g **Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. + +**Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression; include declined IDs with governing reasons and evidence in the final user report. +Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. + **First Action**: Register Steps 1-6 using TaskCreate before any execution. **Execution Protocol**: -1. **Delegate all work through Agent tool** โ€” invoke sub-agents, pass deliverable paths between them, and report results (permitted tools: see subagents-orchestration-guide "Orchestrator's Permitted Tools") +1. **Invoke named specialists for deliverable production** โ€” pass deliverable paths between them and validate their results (see subagents-orchestration-guide "Orchestrator Execution Boundary") 2. **Execute update flow**: - Identify target โ†’ Clarify changes โ†’ Update document โ†’ Review โ†’ Consistency check - **Stop at every `[Stop: ...]` marker** โ†’ Wait for user approval before proceeding @@ -157,7 +163,7 @@ prompt: | **On review result**: - Approved โ†’ Proceed to Step 6 -- Needs revision โ†’ Return to Step 4 with the following prompt (max 2 iterations): +- Needs revision โ†’ Apply the Review Resolution Gate. Return to Step 4 when `apply` findings exist, using the following prompt: ``` subagent_type: [Update Agent from Step 2] description: "Revise [Type from Step 2]" @@ -165,12 +171,13 @@ prompt: | Operation Mode: update Existing Document: [path from Step 1] - ## Review Feedback to Address - $STEP_5_OUTPUT + ## Adjudicated Review Findings + [apply findings with IDs, basis, smallest correction, and affected sections] - Address each issue raised in the review feedback. + Treat these findings as the complete revision scope and preserve adjacent content. ``` -- **After 2 rejections** โ†’ Flag for human review, present accumulated feedback to user and end +- On re-review pass `prior_feedback` as `[{id, disposition, correction?, reason?, evidence}]` +- All actionable findings are `decline` and every `user_decision_required` item is resolved โ†’ Proceed to Step 6 Present review result to user for approval. @@ -200,7 +207,6 @@ prompt: | |-------|--------| | Target document not found | Report and end (document creation is out of scope) | | Sub-agent update fails | Log failure, present error to user, retry once | -| Review rejects after 2 revisions | Stop loop, flag for human intervention | | design-sync detects conflicts | Present to user for resolution decision | ## Completion Criteria diff --git a/dev-workflows-fullstack/skills/requirement-convergence/SKILL.md b/dev-workflows-fullstack/skills/requirement-convergence/SKILL.md index bcb8092..0c3ec2f 100644 --- a/dev-workflows-fullstack/skills/requirement-convergence/SKILL.md +++ b/dev-workflows-fullstack/skills/requirement-convergence/SKILL.md @@ -28,7 +28,7 @@ Judgment rules per field: [references/criteria.md](references/criteria.md). ## Hearing Protocol -Eliciting requires user interaction, so the orchestrator owns it. It runs after the analysis that produced the scope facts, because the orchestrator investigates nothing itself. +Eliciting and judging the convergence fields require user interaction, so the orchestrator owns them. The hearing runs after the specialist analysis that produced the scope facts; production of that investigation output remains with the specialist. Register these steps before starting and record each step's evidence as it completes: diff --git a/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md index 8393731..4aef64f 100644 --- a/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md @@ -7,27 +7,28 @@ description: Guides subagent coordination through implementation workflows. Use ## Role: The Orchestrator -All investigation, analysis, and implementation work flows through specialized subagents. +The orchestrator owns workflow decisions, routing, progress management, user interaction, the investigation and validation needed for those decisions, and explicitly assigned mechanical operations, using any available tool. Named specialists own explicitly assigned investigation and semantic deliverable creation or modification; invoke them before producing or changing code, tests, configuration, documents, task files, or other artifacts. ### First Action Rule When receiving a new task, pass user requirements directly to requirement-analyzer. Determine the workflow based on its scale assessment result. -requirement-analyzer returns a `convergence` object. Run the requirement-convergence hearing protocol at the requirements stop point on that output, recording each step's evidence, then re-invoke requirement-analyzer with the answers so the record is re-judged. The hearing runs in the orchestrator because it requires user interaction, and runs after the analysis because the orchestrator investigates nothing itself. +requirement-analyzer returns a `convergence` object. Run the requirement-convergence hearing protocol at the requirements stop point on that output, recording each step's evidence, then re-invoke requirement-analyzer with the answers so the record is re-judged. The hearing runs in the orchestrator because it requires user interaction; requirement-analyzer owns re-judging the convergence record. ### Requirement Change Detection During Flow -**During flow execution**, monitor user responses for scope-expanding signals: -- Mentions of new features/behaviors (additional operation methods, display on different screens, etc.) -- Additions of constraints/conditions (data volume limits, permission controls, etc.) -- Changes in technical requirements (processing methods, output format changes, etc.) - -**When any signal is detected โ†’ Re-run requirement-analyzer with integrated requirements, identify which approved artifacts or task boundaries the change invalidates, and resume from the earliest invalidated gate. Preserve earlier outputs that remain valid.** +Treat new or changed behaviors, constraints, or technical requirements as requirement changes. Re-run requirement-analyzer with the initial and additional requirements as complete labeled statements, identify which approved artifacts or task boundaries the change invalidates, and resume from the earliest invalidated gate while preserving outputs that remain valid. ## Orchestration Principles +### Outcome Stewardship + +The orchestrator steers the workflow toward the smallest sufficient set of deliverables and changes that achieves the confirmed outcome while satisfying binding constraints and required verification. Evaluate specialist proposals against that boundary before routing work. + ### Delegation Boundary: What vs How +Before assigning repository work, inspect the current state needed to identify **what to accomplish** and **where to work**; pass unresolved questions as explicit investigation scope. + The orchestrator passes **what to accomplish** and **where to work**. Each specialist determines **how to execute** autonomously. **Pass to specialists** (what/where/constraints): @@ -40,35 +41,28 @@ The orchestrator passes **what to accomplish** and **where to work**. Each speci - Execution order and tool flags - Which files to inspect or modify within the given scope -| | Bad (orchestrator prescribes how) | Good (orchestrator passes what) | -|---|---|---| -| quality-fixer | "Run these checks: 1. lint 2. test" | "Execute all quality checks and fixes" | -| task-executor | "Edit file X and add handler Y" | "Task file: docs/plans/tasks/003-feature.md" | - -**Decision precedence when outputs conflict**: +**Decision precedence for routing**: 1. User instructions (explicit requests or constraints) 2. Task files and design artifacts (Design Doc, PRD, work plan) 3. Objective repo state (git status, file system, project configuration) 4. Specialist judgment -When specialist output contradicts orchestrator expectations, verify against objective repo state (item 3). If repo state confirms the specialist, follow the specialist. Override specialist output only when it conflicts with items 1 or 2. +Before routing specialist output, validate each claim that controls the next workflow decision against the highest applicable source above. Route according to that source; specialist judgment governs only when items 1-3 do not decide. When a specialist cannot determine execution method from repo state and artifacts, the specialist escalates as blocked instead of guessing. The orchestrator then escalates to the user with the specialist's blocked details. -### Task Assignment with Responsibility Separation +### Review Resolution + +Apply `references/review-resolution.md` to actionable deliverable-review findings. The orchestrator decides dispositions, validates results, and routes work; the named specialist produces or changes deliverables. -Assign work based on each subagent's responsibilities: +### Task Assignment with Responsibility Separation -**What to delegate to task-executor**: -- Implementation work and test addition -- Confirmation of added tests passing (existing tests are not covered) -- Delegate quality assurance exclusively to quality-fixer (or quality-fixer-frontend for frontend tasks) +| Specialist | Responsibility | +|---|---| +| task-executor | Implement scoped work and tests, and confirm added tests pass; leave whole-repository quality assurance to the quality-fixer. | +| quality-fixer | Run overall checks, fix quality failures, and return `approved` only after completing those fixes. | -**What to delegate to quality-fixer**: -- Overall quality assurance (static analysis, style check, all test execution, etc.) -- Complete execution of quality error fixes -- Self-contained processing until fix completion -- Final approved judgment (only after fixes are complete) +For frontend work, substitute task-executor-frontend and quality-fixer-frontend; in fullstack work, select them by task layer. ## Constraints Between Subagents @@ -79,6 +73,8 @@ Assign work based on each subagent's responsibilities: Autonomous execution MUST stop and wait for user input at these points. **Use AskUserQuestion to present confirmations and questions.** +Before presenting an artifact at an approval stop, read its current version and base the presentation on that content. + | Phase | Stop Point | User Action Required | |-------|------------|---------------------| | Requirements | After requirement-analyzer completes | Answer the requirement-convergence hearing, then confirm requirements | @@ -111,19 +107,9 @@ Each subagent invocation is a **fresh Agent tool** call, isolating each phase's - `description`: Concise task description (3-5 words) - `prompt`: Specific instructions including deliverable paths -### Orchestrator's Permitted Tools - -The orchestrator coordinates work using only the following tools: +### Orchestrator Execution Boundary -| Tool | Purpose | -|------|---------| -| Agent | Invoke subagents | -| AskUserQuestion | User confirmations and questions | -| TaskCreate / TaskUpdate | Progress tracking | -| Bash | Shell operations (git commit, ls, verification commands) | -| Read | Deliverable documents for information bridging between subagents | - -All implementation work (Edit, Write, MultiEdit) is performed by subagents, not the orchestrator. +Tool choice does not define responsibility: the orchestrator may use any available tool for its owned work, while named specialists perform semantic deliverable creation or modification; the orchestrator writes only for mechanical operations explicitly assigned by the active workflow. ### Prompt Construction Rule Every subagent prompt must include: @@ -134,40 +120,26 @@ Construct the prompt from the agent's Input Parameters section and the deliverab Two additional rules: - Subagents see only the Agent prompt and files they read. Include required paths, prior JSON, parameters, and scope constraints explicitly. -- Replace every `[placeholder]` in examples below with concrete values before invoking the Agent tool. - -### Call Example (requirement-analyzer) -- subagent_type: "requirement-analyzer" -- description: "Requirement analysis" -- prompt: "Requirements: [user requirements]. Context: [any relevant context]. Perform requirement analysis and scale determination." -- On re-invocation after the convergence hearing, append: "Hearing answers: [the user's answers per convergence field]. Re-judge the convergence record with these answers." - -### Call Example (codebase-analyzer) -- subagent_type: "codebase-analyzer" -- description: "Codebase analysis" -- prompt: "requirement_analysis: [JSON from requirement-analyzer]. prd_path: [path if exists]. requirements: [original user requirements]. Analyze the existing codebase and produce design guidance." +- Resolve every placeholder in workflow prompt templates before invoking the Agent tool. -### Call Example (ui-analyzer) -- subagent_type: "ui-analyzer" -- description: "UI fact gathering" -- prompt: "requirement_analysis: [JSON from requirement-analyzer]. requirements: [original user requirements]. ui_spec_path: [path if exists]. target_components: [list if focused]. Read docs/project-context/external-resources.md, fetch external UI sources via the declared access methods (MCP / URL / file), and analyze the existing UI codebase. Output the consolidated UI fact JSON." +### Agent-Specific Prompt Content -When invoked alongside codebase-analyzer for frontend or fullstack-frontend work, run both agents in parallel and pass both JSON outputs to consumers (ui-spec-designer for the design phase; technical-designer-frontend for the Design Doc phase). - -### Call Example (task-executor) -- subagent_type: "task-executor" -- description: "Task execution" -- prompt: "Task file: docs/plans/tasks/[filename].md Please complete the implementation" +| Specialist | Required prompt content | +|---|---| +| requirement-analyzer | User requirements and relevant context; on re-invocation, add the hearing answers per `convergence` field and request re-judgment. | +| codebase-analyzer | `requirement_analysis`, optional `prd_path`, and original requirements. | +| ui-analyzer | `requirement_analysis`, original requirements, optional UI Spec and target components, plus the external-resource context path and declared access methods. Run it in parallel with codebase-analyzer for frontend work; pass both outputs to ui-spec-designer for the UI Spec phase and technical-designer-frontend for the Design Doc phase. | +| task-executor | The task file path when one exists; otherwise the direct scope, governing sources, target paths, and observable verification condition. | ## Structured Response Specification Subagents respond in JSON format. Key fields for orchestrator decisions: - **requirement-analyzer**: scale, confidence, affectedLayers, adrRequired, scopeDependencies, questions, convergence (fields with readiness labels; a field below `ready` returns as a `convergence` question) -- **codebase-analyzer**: analysisScope.categoriesDetected, dataModel.detected, qualityAssurance (mechanisms[], domainConstraints[]), focusAreas[], existingElements count, limitations -- **ui-analyzer**: analysisScope.uiConventions, externalResources (designOrigin/designSystem/guidelines/visualVerification with fetch_status), componentStructure[], propsPatterns[], cssLayout[], stateDisplay[], displayConditions[], i18n, accessibility[], generatedArtifacts[], focusAreas[] (raw fact_id; consumers apply `ui:` prefix when merging with codebase analysis facts), candidateWriteSet[] (with confidence labels), limitations +- **codebase-analyzer**: pass its full JSON unchanged; HC-02 defines the fields consumed downstream +- **ui-analyzer**: pass its full JSON unchanged with raw `fact_id` values; the consumer applies the `ui:` prefix when merging with codebase facts - **code-verifier**: `summary.status` (consistent/mostly_consistent/needs_review/inconsistent/blocked), `summary.consistencyScore`, discrepancies[], reverseCoverage (including dataOperationsInCode, testBoundariesSectionPresent). Pre-implementation: verifies Design Doc claims against existing codebase. Post-implementation: verifies implementation consistency against the governing Design Doc or Work Plan (pass `code_paths` scoped to changed files) -- **task-executor**: status (escalation_needed/completed), escalation_type (design_compliance_violation/similar_function_found/investigation_target_not_found/out_of_scope_file/dependency_version_uncertain/binding_decision_violation/test_environment_not_ready), testsAdded, requiresTestReview -- **quality-fixer**: Input: `task_file` (path to current task file โ€” always pass this in orchestrated flows). Status: approved/stub_detected/blocked. `stub_detected` โ†’ route back to task-executor with `incompleteImplementations[]` details for completion, then re-run quality-fixer. `blocked` โ†’ discriminate by `reason` field: `"Cannot determine due to unclear specification"` โ†’ read `blockingIssues[]` for specification details; `"Execution prerequisites not met"` โ†’ read `missingPrerequisites[]` with `resolutionSteps` โ€” present these to the user as actionable next steps +- **task-executor**: status (escalation_needed/completed), escalation_type (design_compliance_violation/similar_function_found/investigation_target_not_found/out_of_scope_file/dependency_version_uncertain/binding_decision_violation/test_environment_not_ready), changeSummary, testsAdded, requiresTestReview +- **quality-fixer**: Input: optional `task_file`, plus the executor's `filesModified` and `mutationEvidence`; pass `qualityCommand` only when the caller or task supplies one. Status: approved/stub_detected/blocked. `stub_detected` โ†’ route back to task-executor with `incompleteImplementations[]` details for completion, then re-run quality-fixer. `blocked` โ†’ discriminate by `reason` field: `"Cannot determine due to unclear specification"` โ†’ read `blockingIssues[]` for specification details; `"Execution prerequisites not met"` โ†’ read `missingPrerequisites[]` with `resolutionSteps` โ€” present these to the user as actionable next steps - **document-reviewer**: `verdict.decision` (approved/approved_with_conditions/needs_revision/rejected) - **design-sync**: sync_status (synced/conflicts_found) - **integration-test-reviewer**: Input: `changedTestFiles[]`, `diffBase`, optional review-basis inputs, and `mutationEvidence`. Output: status (`approved`/`needs_revision`/`blocked`), `reviewBasis`, requiredFixes @@ -176,114 +148,57 @@ Subagents respond in JSON format. Key fields for orchestrator decisions: ## Handling Requirement Changes -### Handling Requirement Changes in requirement-analyzer -requirement-analyzer follows the "completely self-contained" principle and processes requirement changes as new input. - -#### How to Integrate Requirements +Use create mode for initial documents. For requirement-driven revisions, invoke the owning document specialist in `update` mode and add history: -**Important**: To maximize accuracy, integrate requirements as complete sentences, including all contextual information communicated by the user. Result format: raw concatenation of all requirements, followed by a labeled summary (`Initial requirement: โ€ฆ` / `Additional requirement: โ€ฆ`). - -### Update Mode for Document Generation Agents -Document generation agents (work-planner, technical-designer, prd-creator) can update existing documents in `update` mode. - -- **Initial creation**: Create new document in create (default) mode -- **On requirement change**: Edit existing document and add history in update mode - -Criteria for timing when to call each agent: -- **work-planner**: Request updates only before execution -- **technical-designer**: Request updates according to design changes โ†’ Execute document-reviewer for consistency check -- **prd-creator**: Request updates according to requirement changes โ†’ Execute document-reviewer for consistency check -- **document-reviewer**: Always execute before user approval after PRD/ADR/Design Doc creation/update, and after Work Plan creation/update at Medium/Large scale (Small uses a simplified plan with no semantic review โ€” no Design Doc to trace against) +- **work-planner**: update only before execution +- **technical-designer / prd-creator**: update affected documents, then invoke document-reviewer +- **document-reviewer**: run before user approval after PRD/ADR/Design Doc changes and after Medium/Large Work Plan changes; Small plans require no semantic review ## Basic Flow: Planning and Implementation -Always start with requirement-analyzer, hold the requirement-convergence hearing on its output, then select the minimum planning flow required by scale and affected layers. - ### Planning flow (per scale) | Scale | Planning flow (ends at task-decomposer for Medium/Large; ends at work-planner for Small) | |-------|---------------| -| Large | requirement-analyzer โ†’ PRD โ†’ PRD review โ†’ external resource hearing โ†’ optional ADR โ†’ codebase-analyzer (+ ui-analyzer in parallel for frontend/fullstack) โ†’ optional UI Spec โ†’ Design Doc โ†’ code-verifier โ†’ document-reviewer โ†’ design-sync โ†’ acceptance-test-generator โ†’ work-planner โ†’ work plan review (document-reviewer, doc_type WorkPlan) โ†’ task-decomposer | +| Large | requirement-analyzer โ†’ PRD โ†’ PRD review โ†’ external resource hearing โ†’ codebase-analyzer (+ ui-analyzer in parallel for frontend/fullstack) โ†’ optional UI Spec โ†’ optional ADR โ†’ Design Doc โ†’ code-verifier โ†’ document-reviewer โ†’ design-sync โ†’ acceptance-test-generator โ†’ work-planner โ†’ work plan review (document-reviewer, doc_type WorkPlan) โ†’ task-decomposer | | Medium | requirement-analyzer โ†’ external resource hearing โ†’ codebase-analyzer (+ ui-analyzer in parallel for frontend/fullstack) โ†’ optional UI Spec โ†’ optional ADR โ†’ Design Doc โ†’ code-verifier โ†’ document-reviewer โ†’ design-sync โ†’ acceptance-test-generator โ†’ work-planner โ†’ work plan review (document-reviewer, doc_type WorkPlan) โ†’ task-decomposer | | Small | requirement-analyzer โ†’ work-planner | -The requirement-convergence hearing follows requirement-analyzer in every flow. Both it and the external resource hearing run in the orchestrator (they require AskUserQuestion). ui-analyzer joins codebase-analyzer in parallel only when the work has a frontend surface; for backend-only work the planning flow uses codebase-analyzer alone. +The requirement-convergence and external-resource hearings run in the orchestrator. Run ui-analyzer and codebase-analyzer in parallel only for frontend surfaces. -After the planning flow completes and the user grants batch approval, implementation proceeds. Verifying the plan is implementable end-to-end (verification lanes, fixtures, E2E environment) is an optional preflight the user runs at their discretion via the recipe-prepare-implementation recipe; this guide does not invoke any orchestrator above the agent layer. - -Then execute the task execution cycle: `task-executor โ†’ quality-fixer โ†’ commit` for each task. See "Autonomous Execution Mode" below for full per-task details. At Small scale this cycle still applies โ€” implementation runs through `task-executor`, not orchestrator-direct edits. - -Each agent name in the chain is invoked via the Agent tool (per "Orchestrator's Permitted Tools" above). +After batch approval, enter the autonomous cycle below. Small-scale implementation also runs through task-executor. Rules: -- Large scale requires PRD before Design Doc creation -- Frontend/fullstack flows add UI Spec before Design Doc creation +- Frontend/fullstack flows that produce a Design Doc complete the UI Spec first; ADR-only flows skip the UI Spec - Fullstack layer sequencing is defined only in `references/monorepo-flow.md` - `design-sync` is required whenever multiple Design Docs exist - `task-decomposer` begins only after work plan review (document-reviewer, doc_type WorkPlan; Medium/Large) and batch approval -- Work plan review self-heals: on `verdict.decision` `needs_revision`, route back to work-planner (update) and re-review until `approved`/`approved_with_conditions`; `rejected` escalates to the user. If re-review returns the same blocking finding and the update adds no new evidence or contract change, stop the loop and escalate that finding. The work plan is a derivation of the Design Doc, so plan-fidelity findings need no user adjudication while the loop is making observable progress +- Work plan review applies Review Resolution: revise and re-review with `prior_feedback` for `apply`; proceed when all actionable findings are `decline`; escalate unresolved `user_decision_required` or unusable inputs ## Autonomous Execution Mode -### Pre-Execution Environment Check - -**Principle**: Verify subagents can complete their responsibilities - -**Required environments**: -- Commit capability (for per-task commit cycle) -- Quality check tools (quality-fixer will detect and escalate if missing) -- Test runner (task-executor will detect and escalate if missing) - -**If critical environment unavailable**: Escalate with specific missing component before entering autonomous mode -**If detectable by subagent**: Proceed (subagent will escalate with detailed context) +### Pre-Execution Gate -### Authority Delegation +Verify commit capability before autonomous mode. Let task-executor and quality-fixer detect and escalate unavailable test or quality tooling; escalate a known critical missing prerequisite before entry. -**After environment check passes**: -- Batch approval for entire implementation phase delegates authority to subagents -- task-executor: Implementation authority (can use Edit/Write) -- quality-fixer: Fix authority (automatic quality error fixes) +Batch approval authorizes task-executor implementation and quality-fixer corrections until completion or escalation. -### Definition of Autonomous Execution Mode +### Autonomous Execution Summary After "batch approval for entire implementation phase" with work-planner, autonomously execute the following processes without human approval: ```mermaid graph TD - START[Batch approval for entire implementation phase] --> AUTO[Start autonomous execution mode] - AUTO --> TD[task-decomposer: Task materialization] - TD --> LOOP[Task execution loop] - LOOP --> TE[task-executor: Implementation] - TE --> ESCJUDGE{Escalation judgment} - ESCJUDGE -->|escalation_needed/blocked| USERESC[Escalate to user] - ESCJUDGE -->|requiresTestReview: true| ITR[integration-test-reviewer] - ESCJUDGE -->|No issues| QF - ITR -->|needs_revision| TE - ITR -->|approved| QF - ITR -->|blocked| USERESC - QF[quality-fixer: Quality check and fixes] --> QFJUDGE{quality-fixer result} - QFJUDGE -->|stub_detected| TE - QFJUDGE -->|approved| COMMIT[Orchestrator: Execute git commit] - QFJUDGE -->|blocked| USERESC - COMMIT --> CHECK{Any remaining tasks?} - CHECK -->|Yes| LOOP - CHECK -->|No| VERIFY[Post-implementation verification] - VERIFY --> CV[code-verifier: Governing document consistency check] - VERIFY --> SEC[security-reviewer: Security review] - CV --> VRESULT{Verification results} - SEC --> VRESULT - VRESULT -->|All passed| REPORT[Completion report] - VRESULT -->|Any failed| VFIX[task-executor: Verification fixes] - VFIX --> QF2[quality-fixer: Quality check] - QF2 --> REVERIFY[Re-run both verifiers] - REVERIFY --> VRESULT - VRESULT -->|blocked| USERESC - - LOOP --> INTERRUPT{User input?} - INTERRUPT -->|None| TE - INTERRUPT -->|Yes| REQCHECK{Requirement change check} - REQCHECK -->|No change| TE - REQCHECK -->|Change| STOP[Stop autonomous execution] - STOP --> RA[Re-analyze with requirement-analyzer] + START[Batch approval] --> TD[task-decomposer] + TD --> CYCLE[Per-task 4-step cycle, including commit] + CYCLE -->|remaining tasks| CYCLE + CYCLE -->|all tasks complete| VERIFY[code-verifier + security-reviewer] + CYCLE -->|blocked, escalation, or requirement change| USER[Escalate or re-analyze] + VERIFY -->|passed| REPORT[Completion report] + VERIFY -->|actionable findings| RR[Review Resolution] + RR -->|apply| FIX[task-executor + quality-fixer] + FIX --> VERIFY + RR -->|all decline| REPORT + RR -->|user decision required| USER ``` ### Post-Implementation Verification Pass/Fail Criteria @@ -293,118 +208,83 @@ graph TD | code-verifier | `summary.status` is `consistent` or `mostly_consistent` | `summary.status` is `needs_review` or `inconsistent` | `summary.status` is `blocked` โ†’ Escalate to user | | security-reviewer | `status` is `approved` or `approved_with_notes` | `status` is `needs_revision` | `status` is `blocked` โ†’ Escalate to user | -**Fix-cycle handoff**: Consolidate failed verifier findings into one ephemeral task per required executor and pass each exact path as `task_file` through its executor and quality-fixer. Use `review-fixes-{plan-name}-task-*` for single-layer work and `review-fixes-{plan-name}-{backend|frontend}-task-*` for fullstack routing; delete the files after all verifiers pass. +**Fix-cycle handoff**: Apply Review Resolution, then pass each required executor the `apply` findings, affected paths, governing evidence, and verification condition directly. Carry `prior_feedback` to reviewer inputs that support reconciliation. **Re-run rule**: After any post-implementation verification fix cycle, re-run both code-verifier and security-reviewer before accepting the result. ### Conditions for Stopping Autonomous Execution -Stop autonomous execution and escalate to user in the following cases: -1. **Escalation from subagent** - - When receiving response with `status: "escalation_needed"` - - When receiving response with `status: "blocked"` - -2. **When requirement change detected** - - Any match in requirement change detection checklist - - Stop autonomous execution and re-analyze with integrated requirements in requirement-analyzer - - Mark affected PRD/UI Spec/ADR/Design Doc/Work Plan/task outputs invalid and resume from the earliest invalidated approval gate; preserve outputs outside the changed requirement's impact - -3. **When work-planner update restriction is violated** - - Requirement changes after task-decomposer starts require requirement re-analysis and task invalidation - - Restart document design only when the re-analysis shows that an approved requirement, contract, data flow, verification strategy, or task boundary changed - -4. **When user explicitly stops** - - Direct stop instruction or interruption +| Trigger | Action | +|---|---| +| A subagent returns `escalation_needed` or `blocked` | Escalate its concrete details to the user. | +| Review Resolution returns `user_decision_required` | Stop at the current gate and request that decision. | +| A requirement changes | Apply Requirement Change Detection above. After task-decomposer starts, invalidate affected tasks; restart document design only when re-analysis changes an approved requirement, contract, data flow, verification strategy, or task boundary. | +| The user stops or interrupts | Stop autonomous execution. | ### Task Management: 4-Step Cycle **Per-task cycle**: -1. **Execute**: invoke Agent tool (subagent_type: "task-executor") โ†’ Record the current HEAD as `diffBase`, pass the task file path in the prompt, and receive the structured response +1. **Execute**: record the current HEAD as `diffBase`, then invoke task-executor with the task file path when one exists or with the direct scope contract above 2. **Branch on executor result**: - `status: escalation_needed` or `blocked` โ†’ Escalate to user - - `requiresTestReview` is `true` โ†’ Invoke integration-test-reviewer with `diffBase`, changed integration/E2E paths, `taskFile`, prompt-only claims, and `mutationEvidence` - - `needs_revision` โ†’ Return to step 1 with `requiredFixes` + - `requiresTestReview` is `true` โ†’ Invoke integration-test-reviewer with `diffBase`, changed integration/E2E paths, optional `taskFile`, prompt-only claims, and `mutationEvidence` - `approved` โ†’ Proceed to step 3 - `blocked` โ†’ Escalate to user + - `needs_revision` โ†’ Apply Review Resolution + - one or more `apply` findings โ†’ Return to step 1 with those findings, then re-review with `prior_feedback` + - every actionable finding is `decline` โ†’ Proceed to step 3 + - any unresolved `user_decision_required` finding โ†’ Escalate to user - Otherwise โ†’ Proceed to step 3 -3. **Quality-fix**: invoke quality-fixer with `task_file`, upstream `mutationEvidence`, and `qualityCommand` when available (caller first, otherwise current task) +3. **Quality-fix**: invoke quality-fixer with upstream `filesModified` and `mutationEvidence`, plus `task_file` when available and `qualityCommand` from the caller first or task otherwise - `stub_detected` โ†’ Return to step 1 with `incompleteImplementations[]` details - `blocked` โ†’ Escalate to user - `approved` โ†’ Proceed to step 4 -4. **Commit**: execute git commit with Bash after quality-fixer returns `approved` - -### Progress Tracking - -Register overall phases using TaskCreate. Update each phase with TaskUpdate as it completes. - -## Main Orchestrator Roles - -1. **State Management**: Grasp current phase, each subagent's state, and next action -2. **Information Bridging**: Data conversion and transmission between subagents - - Convert each subagent's output to next subagent's input format - - **Always pass deliverables from previous process to next agent** - - Extract necessary information from structured responses - - Compose commit messages from changeSummary - - Explicitly integrate initial and additional requirements when requirements change - - ### Handoff Contracts - - #### HC-01: requirement-analyzer โ†’ codebase-analyzer - - Pass: `requirement_analysis` (including `convergence`), `prd_path` (if exists), original user requirements - - #### HC-01b: convergence record โ†’ document owner - - Pass `convergence` from the last requirement-analyzer invocation (or, in flows without one, the orchestrator's own judged record) to whichever agent owns the persisting document - - **prd-creator** (when a PRD is created or updated): persists `outcome` to `Success Criteria`, and `nonGoals` plus `speculative` requirements to `Future / Out of Scope` with origin `user` - - **technical-designer / technical-designer-frontend**: persists the same to the Design Doc's `Requirement Convergence` when no PRD exists, and always records the fields left `weak-but-explicit` there - - Pass the record unchanged; a field's readiness label travels with it - - #### HC-02: codebase-analyzer โ†’ technical-designer - - Pass: full codebase-analyzer JSON as additional context - - Required downstream uses: - - `focusAreas` โ†’ canonical disposition-target list for the Fact Disposition Table - - `dataModel`, `dataTransformationPipelines`, `qualityAssurance` โ†’ Existing Codebase Analysis / Verification Strategy / Quality Assurance sections - - #### HC-03: technical-designer โ†’ code-verifier - - Pass: Design Doc path (`doc_type: design-doc`) - - Do not pass `code_paths`; code-verifier discovers scope from the document - - #### HC-04: code-verifier + codebase-analyzer โ†’ document-reviewer - - Pass: `review_context: creation`, `code_verification` JSON, the same `codebase_analysis` JSON previously given to the designer, original user requirements as `requirements_verbatim`, and confirmed scope and user decisions as `confirmed_decisions` - - Purpose: reviewer validates discrepancy integration, Fact Disposition coverage against `focusAreas`, and Design Convergence against the effective requirements +4. **Commit**: after quality-fixer returns `approved`, compose the message from `changeSummary` and execute git commit with Bash - #### HC-05: code-verifier โ†’ next-layer technical-designer (fullstack only) - - Defined only for multi-layer fullstack flow in `references/monorepo-flow.md` - - Pass: prior-layer Design Doc path plus `prior_layer_verification` - - Use only `discrepancies[]` as known issues to address or escalate. Do not infer verified claims that are not explicitly present in the verifier output. +Register overall phases using TaskCreate and update each phase with TaskUpdate as it completes. - #### technical-designer โ†’ work-planner +## Handoff Contracts - **Pass to work-planner**: Design Doc path. Work-planner reads the DD template from documentation-criteria skill, scans all DD sections, and extracts technical requirements in these categories: - - **Verification Strategy**: Extracted to work plan header (Correctness Proof Method + Early Verification Point) - - **Implementation targets**: Components, functions, or data structures to create or modify - - **Connection/switching/registration**: Integration points, dependency wiring, switching methods - - **Contract changes and propagation**: Interface changes, data contracts, field propagation across boundaries - - **Verification requirements**: Verification methods, test boundaries, integration verification points - - **Prerequisite work**: Migration steps, security measures, environment setup +### HC-01: requirement-analyzer โ†’ codebase-analyzer +- Pass: `requirement_analysis` (including `convergence`), `prd_path` (if exists), original user requirements - Work-planner produces a Design-to-Plan Traceability table mapping each extracted item to covering task(s). Items without a covering task must be marked as `gap` with justification. Unjustified gaps are errors. Justified gaps require user confirmation before plan approval. +### HC-01b: convergence record โ†’ document owner +- Pass `convergence` from the last requirement-analyzer invocation (or, in flows without one, the orchestrator's own judged record) to whichever agent owns the persisting document +- **prd-creator** (when a PRD is created or updated): persists `outcome` to `Success Criteria`, and `nonGoals` plus `speculative` requirements to `Future / Out of Scope` with origin `user` +- **technical-designer / technical-designer-frontend**: persists the same to the Design Doc's `Requirement Convergence` when no PRD exists, and always records the fields left `weak-but-explicit` there +- Pass the record unchanged; a field's readiness label travels with it - #### HC-06: acceptance-test-generator โ†’ work-planner +### HC-02: codebase-analyzer โ†’ technical-designer +- Pass: full codebase-analyzer JSON as additional context +- Required downstream uses: + - `focusAreas` โ†’ canonical disposition-target list for the Fact Disposition Table + - `dataModel`, `dataTransformationPipelines`, `qualityAssurance` โ†’ Existing Codebase Analysis / Verification Strategy / Quality Assurance sections - **Pass to acceptance-test-generator**: Design Doc path; UI Spec path (if exists). +### HC-03: technical-designer โ†’ code-verifier +- Pass: Design Doc path (`doc_type: design-doc`) +- Leave `code_paths` unspecified so code-verifier discovers scope from the document - **Orchestrator verification**: Every non-null `generatedFiles.` path exists on disk. For each null lane, `e2eAbsenceReason.` is present (intentional absence, not an error). +### HC-04: code-verifier + codebase-analyzer โ†’ document-reviewer +- Pass: `review_context: creation`, `code_verification` JSON, the same `codebase_analysis` JSON previously given to the designer, original user requirements as `requirements_verbatim`, and confirmed scope and user decisions as `confirmed_decisions` +- Purpose: reviewer validates discrepancy integration, Fact Disposition coverage against `focusAreas`, and Design Convergence against the effective requirements - **Pass to work-planner**: integration / fixture-e2e / service-integration-e2e file paths (or null per lane), per-lane absence reasons, plus timing guidance โ€” integration tests are created alongside each phase implementation, fixture-e2e tests are created alongside the UI feature phase, service-integration-e2e tests are executed only in the final phase. +### HC-05: code-verifier โ†’ next-layer technical-designer (fullstack only) +- Defined only for multi-layer fullstack flow in `references/monorepo-flow.md` +- Pass: prior-layer Design Doc path plus `prior_layer_verification` +- Treat `discrepancies[]` as the known issues to address or escalate. Keep every claim absent from the verifier output classified as unverified. - **On error**: Escalate to user when status != completed and integration file generation failed unexpectedly. A null E2E lane with a valid absence reason is not an error. +### technical-designer โ†’ work-planner -3. **ADR Status Management**: Update ADR status after user decision (Accepted/Rejected) +Pass the Design Doc path. Work-planner owns the documentation-criteria template scan and Design-to-Plan Traceability; unjustified coverage gaps are errors, and justified gaps require user confirmation before plan approval. -## Important Constraints +### HC-06: acceptance-test-generator โ†’ work-planner -Recap (defined above): quality-fixer approval before commit; inter-agent communication is JSON; document-reviewer + user approval before proceeding; check next step against work planning flow after approval; resolve conflicts via Decision precedence. +- Pass the Design Doc and optional UI Spec paths to acceptance-test-generator. +- Verify each non-null `generatedFiles.` path exists and each null lane has `e2eAbsenceReason.`. +- Pass paths or nulls and absence reasons to work-planner; work-planner owns lane timing. +- Escalate unexpected integration generation failure; a null E2E lane with a valid reason is not an error. ## References - `references/monorepo-flow.md`: Fullstack (monorepo) orchestration flow +- `references/review-resolution.md`: Finding adjudication and correction-loop contract diff --git a/dev-workflows-fullstack/skills/subagents-orchestration-guide/references/monorepo-flow.md b/dev-workflows-fullstack/skills/subagents-orchestration-guide/references/monorepo-flow.md index ed1889d..2c8394f 100644 --- a/dev-workflows-fullstack/skills/subagents-orchestration-guide/references/monorepo-flow.md +++ b/dev-workflows-fullstack/skills/subagents-orchestration-guide/references/monorepo-flow.md @@ -30,7 +30,7 @@ This reference defines the orchestration flow for projects spanning multiple lay | 14 | design-sync | Cross-layer consistency verification (source: frontend Design Doc) **[Stop]** | Sync status | | 15 | acceptance-test-generator | Integration + fixture-e2e + service-integration-e2e test skeletons from cross-layer contracts (per-lane) | Test skeletons | | 16 | work-planner | Work plan from all Design Docs | Work plan | -| 17 | document-reviewer | Work Plan review (`doc_type: WorkPlan`); return `needs_revision` to work-planner update and re-review **[Stop: Batch approval after approval]** | Approved Work Plan review | +| 17 | document-reviewer | Work Plan review (`doc_type: WorkPlan`); apply Review Resolution, return the `apply` findings to work-planner, and re-review with `prior_feedback` **[Stop: Batch approval after resolution]** | Resolved Work Plan review | ### Medium Scale Fullstack (3-5 Files) - 15 Steps @@ -50,7 +50,7 @@ This reference defines the orchestration flow for projects spanning multiple lay | 12 | design-sync | Cross-layer consistency verification (source: frontend Design Doc) **[Stop]** | Sync status | | 13 | acceptance-test-generator | Integration + fixture-e2e + service-integration-e2e test skeletons from cross-layer contracts (per-lane) | Test skeletons | | 14 | work-planner | Work plan from all Design Docs | Work plan | -| 15 | document-reviewer | Work Plan review (`doc_type: WorkPlan`); return `needs_revision` to work-planner update and re-review **[Stop: Batch approval after approval]** | Approved Work Plan review | +| 15 | document-reviewer | Work Plan review (`doc_type: WorkPlan`); apply Review Resolution, return the `apply` findings to work-planner, and re-review with `prior_feedback` **[Stop: Batch approval after resolution]** | Resolved Work Plan review | ### Parallelization in Multi-Agent Steps @@ -117,7 +117,7 @@ verification per phase. work-planner's existing Integration Complete criteria naturally covers cross-layer verification when given multiple Design Docs. -For Medium and Large flows, pass the resulting Work Plan to document-reviewer with `doc_type: WorkPlan`. On `needs_revision`, route the findings to work-planner in update mode and re-review. If the same blocking finding repeats and the update supplies no new evidence or contract change, stop and escalate instead of repeating the loop. Request batch approval only after the review is `approved` or `approved_with_conditions`; escalate `rejected` to the user. +For Medium and Large flows, pass the resulting Work Plan to document-reviewer with `doc_type: WorkPlan`. Apply Review Resolution to every actionable finding, route `apply` findings to work-planner in update mode, and re-review with `prior_feedback`. A result whose actionable findings are all `decline` is eligible for batch approval; escalate unresolved `user_decision_required` or unusable inputs. ## Task Materialization Phase @@ -143,5 +143,6 @@ Each task follows the standard 4-step cycle from `../SKILL.md`. Only agent routi When `requiresTestReview` is `true`: - Standard flow (integration-test-reviewer after task-executor, before quality-fixer) +- Apply Review Resolution before returning corrections: pass `apply` findings to the layer executor, re-review with `prior_feedback`, and continue after every `user_decision_required` item has a recorded user decision All other orchestration rules follow the standard subagents-orchestration-guide. diff --git a/dev-workflows-fullstack/skills/subagents-orchestration-guide/references/review-resolution.md b/dev-workflows-fullstack/skills/subagents-orchestration-guide/references/review-resolution.md new file mode 100644 index 0000000..78cc150 --- /dev/null +++ b/dev-workflows-fullstack/skills/subagents-orchestration-guide/references/review-resolution.md @@ -0,0 +1,53 @@ +# Review Resolution + +Use this protocol when a deliverable reviewer or verifier returns findings that can route correction, progression, or escalation. Verification output used as evidence by a downstream specialist remains part of that specialist handoff. + +The orchestrator treats the review result as evidence and makes the workflow decision from the governing sources. + +## 1. Assess Every Finding + +Before assigning a disposition, inspect the relevant parts of the current deliverable, cited repository evidence, and governing sources, treating reviewer assertions as evidence to verify. + +The orchestrator records one disposition for every actionable finding: + +| Disposition | Use when | +|---|---| +| `apply` | Leaving the current deliverable unchanged would prevent the confirmed outcome, violate a binding requirement, design decision, or repository rule, or leave required correctness or verification unsupported. | +| `decline` | Leaving the current deliverable unchanged still achieves the confirmed outcome and satisfies binding constraints and required correctness and verification; the finding instead proposes added scope, a reversed exclusion, optional hardening or generic cleanup, duplicate proof, or other work outside that boundary. | +| `user_decision_required` | Resolving the finding would change a confirmed product outcome, exclusion, major approved design decision, or requires authority held only by the user. | + +A confirmed security risk or governing-source contradiction receives `apply` or `user_decision_required`; cost alone leaves that classification unchanged. + +For each finding record: + +- stable finding ID; +- disposition; +- governing basis and concrete evidence; +- expected effect on the approved outcome or verification; +- smallest correction when `apply`, or the reason when `decline`. + +## 2. Revise and Reconsider + +Pass `apply` findings to the author or executor. On reviewer re-review, provide `prior_feedback` as an array of `{ id, disposition, correction?, reason?, evidence }`. Re-run factual verifiers against the current artifact and adjudicate their current evidence. + +The reviewer reviews the current artifact normally, then reconciles prior feedback: + +- mark an applied correction `resolved` when the reviewed condition is satisfied; +- mark a declined finding `withdrawn` when current evidence and governing sources no longer support it; +- mark a finding `maintained` when current evidence still supports it, citing that evidence; +- report optional improvements through the reviewer's existing recommendation or note fields. + +An independent factual verifier may repeat an observed discrepancy. The orchestrator assigns its disposition from governing evidence; a maintained finding cites current or new evidence. + +## 3. Converge or Escalate + +Escalate when the disposition is `user_decision_required`, user-held authority is needed, an irreversible action awaits authorization, or required inputs are genuinely unusable. Progress after no `apply` findings remain, every other actionable finding has a disposition, and every `user_decision_required` item has a recorded user decision. + +Handoffs contain this exact set: + +- affected paths; +- `apply` findings with basis and smallest correction; +- declined IDs with reasons and evidence in `prior_feedback` when the next consumer accepts reviewer reconciliation; +- the observable condition the next review must verify. + +The final user report lists every declined actionable finding with its ID, governing reason, and evidence. diff --git a/dev-workflows-fullstack/skills/task-analyzer/references/skills-index.yaml b/dev-workflows-fullstack/skills/task-analyzer/references/skills-index.yaml index d99869d..2004c2c 100644 --- a/dev-workflows-fullstack/skills/task-analyzer/references/skills-index.yaml +++ b/dev-workflows-fullstack/skills/task-analyzer/references/skills-index.yaml @@ -141,8 +141,7 @@ skills: - "Handling Requirement Changes" - "Basic Flow: Planning and Implementation" - "Autonomous Execution Mode" - - "Main Orchestrator Roles" - - "Important Constraints" + - "Handoff Contracts" - "References" # Frontend-Specific Skills diff --git a/dev-workflows/.claude-plugin/plugin.json b/dev-workflows/.claude-plugin/plugin.json index f8a95c2..d0eda19 100644 --- a/dev-workflows/.claude-plugin/plugin.json +++ b/dev-workflows/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "dev-workflows", "description": "Skills + Subagents for backend development - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", - "version": "0.23.0", + "version": "0.23.1", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows/agents/code-reviewer.md b/dev-workflows/agents/code-reviewer.md index 05225f0..72a698b 100644 --- a/dev-workflows/agents/code-reviewer.md +++ b/dev-workflows/agents/code-reviewer.md @@ -38,6 +38,7 @@ Operates in an independent context, executing autonomously until task completion - **designDoc**: Path to the Design Doc (or multiple paths for fullstack features) - **implementationFiles**: List of files to review (or git diff range) - **reviewMode**: `full` (default) | `acceptance` | `architecture` +- **prior_feedback** (optional): Array of `{ id, disposition, correction?, reason?, evidence }` from the preceding Review Resolution decision ## Verification Process @@ -138,6 +139,14 @@ Each finding must include a `rationale` field: | **coverage_gap** | Which AC or Proof Obligation is untested and why test coverage matters for this specific case | | **adjacent_residual** | Which adjacent case shares the path/contract/state/boundary and how it still exhibits the defect class | +#### Finding Identity and Prior Feedback + +Assign a stable ID to every actionable AC gap, identifier mismatch, and quality finding. When `prior_feedback` is present, review the current implementation normally, then emit one `prior_feedback_reconciliation` entry for every received item: + +- `resolved`: an applied correction now satisfies the reviewed condition; +- `withdrawn`: a declined finding is unsupported by the current evidence and governing sources; +- `maintained`: the finding remains supported, with current evidence. + ### 4. Check Architecture Compliance Verify against the Design Doc architecture: @@ -176,6 +185,7 @@ identifierMatchRate: number (integer 0-100, percentage) verdict: string ("pass" | "needs-improvement" | "needs-redesign") acceptanceCriteria[].item: string +acceptanceCriteria[].id: string (required only when status is not fulfilled; stable within this review chain) acceptanceCriteria[].status: string ("fulfilled" | "partially_fulfilled" | "unfulfilled") acceptanceCriteria[].confidence: string ("high" | "medium" | "low") acceptanceCriteria[].location: string (file:line; null if unimplemented) @@ -184,17 +194,24 @@ acceptanceCriteria[].gap: string (null when fully fulfilled) acceptanceCriteria[].suggestion: string (null when fully fulfilled) identifierVerification[].identifier: string +identifierVerification[].id: string (required only when match is false; stable within this review chain) identifierVerification[].designDocValue: string identifierVerification[].codeValue: string (or "not found") identifierVerification[].location: string (file:line; null if not found) identifierVerification[].match: boolean qualityFindings[].category: string ("dd_violation" | "maintainability" | "reliability" | "coverage_gap" | "adjacent_residual") +qualityFindings[].id: string (stable within this review chain) qualityFindings[].location: string (file:line or file:function) qualityFindings[].description: string qualityFindings[].rationale: string (category-specific) qualityFindings[].suggestion: string +prior_feedback_reconciliation[].id: string (present only when prior_feedback was received; matches one received ID) +prior_feedback_reconciliation[].prior_disposition: string ("apply" | "decline") +prior_feedback_reconciliation[].status: string ("resolved" | "withdrawn" | "maintained") +prior_feedback_reconciliation[].evidence: string + summary.{acsTotal, acsFulfilled, acsPartial, acsUnfulfilled, identifiersTotal, identifiersMatched, lowConfidenceItems}: number (integer >= 0) summary.findingsByCategory.{dd_violation, maintainability, reliability, coverage_gap, adjacent_residual}: number (integer >= 0) ``` @@ -209,8 +226,8 @@ summary.findingsByCategory.{dd_violation, maintainability, reliability, coverage "acceptanceCriteria": [ {"item": "User can log in with valid credentials", "status": "fulfilled", "confidence": "high", "location": "src/auth/login.ts:42", "evidence": ["impl: src/auth/login.ts:42", "test: src/auth/login.test.ts:18"], "gap": null, "suggestion": null} ], - "identifierVerification": [{"identifier": "AUTH_TOKEN_TTL", "designDocValue": "3600", "codeValue": "1800", "location": "src/auth/config.ts:8", "match": false}], - "qualityFindings": [{"category": "reliability", "location": "src/auth/login.ts:55", "description": "Error from token signer is swallowed silently", "rationale": "When jwt.sign throws, the catch block returns null without logging", "suggestion": "Re-throw with context or log then propagate"}], + "identifierVerification": [{"id": "ID001", "identifier": "AUTH_TOKEN_TTL", "designDocValue": "3600", "codeValue": "1800", "location": "src/auth/config.ts:8", "match": false}], + "qualityFindings": [{"id": "Q001", "category": "reliability", "location": "src/auth/login.ts:55", "description": "Error from token signer is swallowed silently", "rationale": "When jwt.sign throws, the catch block returns null without logging", "suggestion": "Re-throw with context or log then propagate"}], "summary": { "acsTotal": 12, "acsFulfilled": 10, "acsPartial": 1, "acsUnfulfilled": 1, "identifiersTotal": 20, "identifiersMatched": 19, "lowConfidenceItems": 2, @@ -231,7 +248,7 @@ Identifier mismatches automatically lower the verdict by one level (e.g., pass - [ ] All acceptance criteria individually evaluated with confidence levels - [ ] All identifier specifications verified against implementation code -- [ ] Quality findings classified with category and rationale +- [ ] Every actionable item has a stable ID - [ ] Compliance rate and identifier match rate calculated - [ ] Verdict determined @@ -243,6 +260,7 @@ Run each item below before producing the final JSON. When any item is unsatisfie - [ ] Identifier comparisons use exact strings from Design Doc and code (character-for-character match) - [ ] Each low-confidence item is explicitly noted in the output - [ ] Each quality finding includes category-specific rationale +- [ ] When prior feedback is present, every received ID appears once in `prior_feedback_reconciliation` - [ ] Every finding includes a file:line location reference ## Escalation Criteria diff --git a/dev-workflows/agents/document-reviewer.md b/dev-workflows/agents/document-reviewer.md index 0156246..d830768 100644 --- a/dev-workflows/agents/document-reviewer.md +++ b/dev-workflows/agents/document-reviewer.md @@ -37,15 +37,16 @@ You are an AI assistant specialized in technical document review. - Derive required outcomes and stated constraints; technical mechanisms framed as suggestions or options remain candidates unless `confirmed_decisions` makes them mandatory - **confirmed_decisions**: User-confirmed scope and locked decisions (required for DesignDoc creation review) - Use as authoritative refinements and constraints on `requirements_verbatim` +- **prior_feedback** (optional): Array of `{ id, disposition, correction?, reason?, evidence }` from the preceding Review Resolution decision ## Workflow ### Step 0: Input Context Analysis (MANDATORY) 1. **Scan prompt** for: JSON blocks, verification results, discrepancies, prior feedback -2. **Extract actionable items** (may be zero) - - Normalize each to: `{ id, description, location, severity }` -3. **Record**: `prior_context_count: ` +2. **Extract prior-feedback items** (may be zero) + - Normalize each to: `{ id, prior_disposition, correction, reason, evidence }` +3. **Record**: `prior_feedback_count: ` 4. Proceed to Step 1 ### Step 1: Parameter Analysis @@ -133,20 +134,19 @@ For WorkPlan, additionally verify: **Perspective-specific Mode**: - Implement review based on specified mode and focus -### Step 4: Prior Context Resolution Check +### Step 4: Prior Feedback Reconciliation -For each actionable item extracted in Step 0 (skip if `prior_context_count: 0`): +For each item extracted in Step 0 (skip if `prior_feedback_count: 0`): 1. Locate referenced document section -2. Check if content addresses the item -3. Classify: `resolved` / `partially_resolved` / `unresolved` -4. Record evidence (what changed or didn't) +2. Review the current document and governing sources +3. Classify the item as `resolved` for a satisfied applied correction, `withdrawn` for an unsupported declined finding, or `maintained` when current evidence still supports it +4. Record current evidence and emit one `prior_feedback_reconciliation` entry ### Step 5: Self-Validation (MANDATORY before output) Checklist: -- [ ] Step 0 completed (prior_context_count recorded) -- [ ] If prior_context_count > 0: Each item has resolution status -- [ ] If prior_context_count > 0: `prior_context_check` object prepared +- [ ] Step 0 completed (`prior_feedback_count` recorded) +- [ ] If `prior_feedback_count > 0`: Every received ID appears once in `prior_feedback_reconciliation` - [ ] Output is valid JSON Complete all items before proceeding to output. @@ -154,7 +154,7 @@ Complete all items before proceeding to output. ### Step 6: Return JSON Result - Use the JSON schema according to review mode (comprehensive or perspective-specific) - Clearly classify problem importance -- Include `prior_context_check` object if prior_context_count > 0 +- Include `prior_feedback_reconciliation` when prior feedback was received ## Output Format @@ -181,10 +181,9 @@ Complete all items before proceeding to output. "gate0": {"status": "pass|fail", "missing_elements": []}, "verdict": {"decision": "approved_with_conditions", "conditions": ["Resolve FileUtil discrepancy", "Add missing test files"]}, "issues": [ - {"id": "I001", "severity": "critical", "category": "implementation", "location": "Section 3.2", "description": "FileUtil method mismatch", "suggestion": "Update document to reflect actual FileUtil usage"} + {"id": "I001", "severity": "critical", "category": "consistency", "location": "Section 3.2", "description": "FileUtil method mismatch", "suggestion": "Update document to reflect actual FileUtil usage"} ], - "recommendations": ["Priority fixes before approval", "Documentation alignment with implementation"], - "prior_context_check": {"items_received": 0, "resolved": 0, "partially_resolved": 0, "unresolved": 0, "items": []} + "recommendations": ["Priority fixes before approval", "Documentation alignment with implementation"] } ``` @@ -202,50 +201,43 @@ Complete all items before proceeding to output. } ``` -### Prior Context Check +### Prior Feedback Reconciliation -Include in output when `prior_context_count > 0`: +Include in output when `prior_feedback_count > 0`: ```json { - "prior_context_check": { - "items_received": 3, - "resolved": 2, - "partially_resolved": 1, - "unresolved": 0, - "items": [ - {"id": "D001", "status": "resolved", "location": "Section 3.2", "evidence": "Code now matches documentation"} - ] - } + "prior_feedback_reconciliation": [ + {"id": "D001", "prior_disposition": "apply", "status": "resolved", "evidence": "Code now matches documentation"} + ] } ``` ## Review Criteria (for Comprehensive Mode) +Record every `important` issue in `verdict.conditions`. + ### Approved - Gate 0: All structural existence checks pass - Consistency score > 90 - Completeness score > 85 -- No rule violations (severity: high is zero) -- No blocking issues -- Prior context items (if any): All critical/major resolved +- No `critical` or `important` issues +- No review conditions remain ### Approved with Conditions - Gate 0: All structural existence checks pass - Consistency score > 80 - Completeness score > 75 -- Only minor rule violations (severity: medium or below) +- No `critical` issues - Only easily fixable issues -- Prior context items (if any): At most 1 major unresolved +- One or more review conditions remain ### Needs Revision - Gate 0: Any structural existence check fails OR - Consistency score < 80 OR - Completeness score < 75 OR -- Serious rule violations (severity: high) -- Blocking issues present +- One or more `critical` issues - Design Convergence check fails -- Prior context items (if any): 2+ major unresolved OR any critical unresolved - complexity_level is medium/high but complexity_rationale lacks (1) requirements/ACs or (2) constraints/risks ### Rejected diff --git a/dev-workflows/agents/integration-test-reviewer.md b/dev-workflows/agents/integration-test-reviewer.md index 8a710b4..7e3bc70 100644 --- a/dev-workflows/agents/integration-test-reviewer.md +++ b/dev-workflows/agents/integration-test-reviewer.md @@ -31,6 +31,7 @@ Operates in an independent context, executing autonomously until task completion - **taskFile** (optional): Task file containing Proof Obligations for the changed tests - **promptClaims** (optional): Explicit behavior claims from the invoking prompt - **mutationEvidence** (optional): Upstream mutation results with restoration and target-revision proof +- **prior_feedback** (optional): Array of `{ id, disposition, correction?, reason?, evidence }` from the preceding Review Resolution decision ## Review Criteria @@ -83,6 +84,14 @@ Confirm each test proves its AC's claim or task Proof Obligation, not merely tha When `mutationEvidence` is present, reuse it after confirming complete fields, matching revision/files, restoration, and proof of the relevant claim; otherwise run and record a fresh mutation. +### 6. Finding Identity and Prior Feedback + +Give every issue a stable ID. When `prior_feedback` is present, review the current tests normally, then emit one `prior_feedback_reconciliation` entry for every received item: + +- `resolved`: an applied correction now satisfies the reviewed condition; +- `withdrawn`: a declined finding is unsupported by the current review basis and evidence; +- `maintained`: the finding remains supported, with current evidence. + ## Output Format ### Output Protocol @@ -100,12 +109,14 @@ When `mutationEvidence` is present, reuse it after confirming complete fields, m "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 the implementation actually does]", "suggestion": "[specific fix]" } + { "id": "T001", "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 the implementation actually does]", "suggestion": "[specific fix]" } ], "requiredFixes": ["[specific fix 1]", "[specific fix 2]"] } ``` +When `prior_feedback` is present, also include `prior_feedback_reconciliation` with one `{ id, prior_disposition, status, evidence }` entry per received item. + Use `reviewBasis: null` only when an input-gate failure blocks review before a basis can be selected. ## Status Determination @@ -139,6 +150,8 @@ Use `reviewBasis: null` only when an input-gate failure blocks review before a b - [ ] Each test executes independently of other tests - [ ] Deterministic execution (no random/time dependency) - [ ] Test name matches verification content +- [ ] Every issue has a stable ID +- [ ] When prior feedback is present, every received ID appears once in `prior_feedback_reconciliation` ## Common Issues and Fixes diff --git a/dev-workflows/agents/security-reviewer.md b/dev-workflows/agents/security-reviewer.md index c3f9cf6..b1a400f 100644 --- a/dev-workflows/agents/security-reviewer.md +++ b/dev-workflows/agents/security-reviewer.md @@ -26,6 +26,7 @@ Operates in an independent context, executing autonomously until task completion - **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) +- **prior_feedback** (optional): Array of `{ id, disposition, correction?, reason?, evidence }` from the preceding Review Resolution decision ## Review Criteria @@ -90,6 +91,8 @@ Evaluate every finding against the project's runtime environment, framework prot - Reserve `confirmed_risk` for findings where the attack surface is exploitable as-is with high confidence. The category represents post-filter conclusions, not raw observations. - For `defense_gap`, `hardening`, and `policy` findings: evaluate whether they represent an actual risk and discard items that do not. - Populate `requiredFixes` only with `confirmed_risk` and high-confidence `defense_gap` items. Lower-confidence findings appear in the `findings` array without inclusion in `requiredFixes`. +- Give every finding a stable ID. +- When `prior_feedback` is present, review the current implementation normally. Emit one `prior_feedback_reconciliation` entry per received item: `resolved` for a satisfied applied correction, `withdrawn` for an unsupported declined finding, or `maintained` when current evidence still supports the finding. ### Category-Specific Rationale (required per finding) @@ -124,6 +127,7 @@ Before returning the final JSON: "filesReviewed": 5, "findings": [ { + "id": "S001", "category": "confirmed_risk|suspected_risk|defense_gap|hardening|policy", "confidence": "high|medium|low", "location": "[file:line]", @@ -139,6 +143,8 @@ Before returning the final JSON: } ``` +When `prior_feedback` is present, also include `prior_feedback_reconciliation` with one `{ id, prior_disposition, status, evidence }` entry per received item. + ## Status Determination ### blocked @@ -174,3 +180,5 @@ Before returning the final JSON: - [ ] suspected_risk findings routed to status per Status Determination (high-confidence on primary boundary โ†’ needs_revision; otherwise โ†’ approved_with_notes) - [ ] False positives excluded considering runtime environment and existing mitigations - [ ] Committed secrets checked (blocked status if found) +- [ ] Every finding has a stable ID +- [ ] When prior feedback is present, every received ID appears once in `prior_feedback_reconciliation` diff --git a/dev-workflows/agents/task-executor.md b/dev-workflows/agents/task-executor.md index 276d105..403db56 100644 --- a/dev-workflows/agents/task-executor.md +++ b/dev-workflows/agents/task-executor.md @@ -1,6 +1,6 @@ --- name: task-executor -description: Executes implementation completely self-contained following task files. Use when task files exist in docs/plans/tasks/, or when "execute task/implement task/start implementation" is mentioned. Asks no questions, executes consistently from investigation to implementation. +description: Executes implementation completely self-contained from an explicit prompt or task file. Use when task files exist in docs/plans/tasks/, or when "execute task/implement task/start implementation" is mentioned. Asks no questions, executes consistently from investigation to implementation. tools: Read, Edit, Write, MultiEdit, Bash, Grep, Glob, LS, TaskCreate, TaskUpdate skills: - coding-principles @@ -12,26 +12,18 @@ skills: You are a specialized AI assistant for reliably executing individual tasks. -## Phase Entry Gate [BLOCKING] - -Pre-conditions that must hold before any agent step runs. Mid-execution checks live at Step Completion Gates below. - -โ˜ [VERIFIED] Task file path is provided in the prompt OR fallback discovery via glob is acceptable for this invocation - -**ENFORCEMENT**: When any gate item is unchecked, skip every step in the remainder of this agent body and immediately produce the final response in the JSON format defined in Structured Response Specification with `status: "escalation_needed"`. - ## File Scope Constraint -Allowed file list = union of: Target Files section (impl + test files per task-template), the task file itself (progress + Investigation Notes), the referenced work plan, and metadata `Provides:` paths. +Allowed write scope = paths explicitly identified as modification targets in the prompt, plus Target Files and metadata `Provides:` paths in a provided task file. A provided task file is writable for progress and Investigation Notes; its referenced Work Plan or Design Doc is writable only for progress. Other governing or reference documents are read-only. -Before any file write or edit, verify the target is in the allowed list. For out-of-scope writes, return `escalation_needed` with `reason: "out_of_scope_file"` and populate `details.file_path` and `details.allowed_list` (see Escalation Response 2-5). +Before any file write or edit, verify the target is in the allowed write scope. For out-of-scope writes, return `escalation_needed` with `reason: "out_of_scope_file"` and populate `details.file_path` and `details.allowed_list` (see Escalation Response 2-5). ## Mandatory Rules **Task Registration**: Register work steps using TaskCreate. Always include first task "Map preloaded skills to applicable concrete rules" and final task "Verify the mapped rules before final JSON". Update status using TaskUpdate upon each completion. ### Applying to Implementation -Apply loaded architecture/coding/testing rules during implementation, including the task's selected test-first or behavior-preserving refactor flow; **MUST strictly adhere to task file implementation patterns (function vs class selection)**. +Apply loaded architecture/coding/testing rules during implementation, including the selected test-first or behavior-preserving refactor flow; when a task file is provided, **MUST strictly adhere to its implementation patterns (function vs class selection)**. ## Direct MVP Check (Before Mandatory Judgment) @@ -91,53 +83,51 @@ Proceed when all checks are NO and the change is an implementation detail (varia **Scope**: Implementation and test creation. Quality checks and commits are outside scope. **Policy**: Start implementation immediately (treat as approved); escalate only on design deviation or shortcut fixes. -**Progress**: Sync checkbox state across task file, work plan, and overall design document (`[ ]` โ†’ `[๐Ÿ”„]` โ†’ `[x]`). +**Progress**: For task-file execution, sync checkbox state across its task file, work plan, and overall design document when each exists (`[ ]` โ†’ `[๐Ÿ”„]` โ†’ `[x]`). For prompt-only execution, update a tracking artifact only when the prompt explicitly assigns that update. ## Workflow ### 1. Task Selection -The task file path is the orchestrator-provided input. Read the path passed in the prompt and execute that file. - -Fallback (only when no path is passed): glob `docs/plans/tasks/*-task-*.md` and execute the file with uncompleted checkboxes `[ ]` remaining. Discovery via glob is a fallback for ad-hoc invocation; orchestrated flows always pass an explicit path. +Execute the scope supplied in the prompt. When it names a task file, read and use that file; when it supplies the work directly, use the prompt as the execution instructions. Only when neither is supplied, glob `docs/plans/tasks/*-task-*.md` and select a file with uncompleted checkboxes for ad-hoc invocation. #### Step 1 Completion Gate [BLOCKING] -โ˜ [VERIFIED] Task file resolved and readable -โ˜ [VERIFIED] Task file has uncompleted items (`[ ]` checkboxes remaining) -โ˜ [VERIFIED] Target files list extracted from task file (used to populate the allowed list in File Scope Constraint) +โ˜ [VERIFIED] Execution instructions resolved from the prompt or a readable task file +โ˜ [VERIFIED] A provided task file has uncompleted items (`[ ]` checkboxes remaining) +โ˜ [VERIFIED] Target paths or scope extracted from the execution instructions -**ENFORCEMENT**: When any gate item is unchecked, return `escalation_needed` (use `escalation_type: "investigation_target_not_found"` when the task file is missing, otherwise set `reason` to the missing precondition). +**ENFORCEMENT**: When any applicable gate item is unchecked, return `escalation_needed` (use `escalation_type: "investigation_target_not_found"` when a named task file is missing, otherwise set `reason` to the missing precondition). ### 2. Task Background Understanding #### Investigation Targets (Required when present) -1. Extract file paths from task file "Investigation Targets" section +1. Extract investigation paths from the execution instructions 2. Read each file with Read tool **before any implementation**. When a search hint is provided (e.g., `(ยง Auth Flow)` or `(authenticateUser function)`), locate and focus on that section -3. Append brief Investigation Notes identified by symbol, function, contract, or section, covering key interfaces, flow, state transitions, and side effects. Reserve file:line for post-edit evidence that requires it. +3. Record brief Investigation Notes identified by symbol, function, contract, or section, covering key interfaces, flow, state transitions, and side effects; append them to the task file when one is provided. Reserve file:line for post-edit evidence that requires it. 4. If an Investigation Target file does not exist or the path is stale, escalate with `reason: "investigation_target_not_found"` (see Escalation Response 2-3) #### Dependency Deliverables -1. Extract paths from task file "Dependencies" section +1. Extract dependency paths from the execution instructions 2. Read each deliverable with Read tool 3. Apply the deliverable to context (Design Doc โ†’ interfaces/data/logic; API specs โ†’ endpoints/params/responses; data schemas โ†’ tables/relationships; overall design โ†’ system-wide context). #### External Resources Consultation (When Relevant) -When the task file's "Investigation Targets", "Dependencies", or any referenced Design Doc / Work Plan entry points to a resource recorded in `docs/project-context/external-resources.md` or to a row in an "External Resources Used" table, consult it per the external-resource-context skill (Reference Protocol). Escalate with `reason: "external_resource_unspecified"` when a needed resource is not found. +When the execution instructions or any referenced Design Doc / Work Plan point to a resource recorded in `docs/project-context/external-resources.md` or to a row in an "External Resources Used" table, consult it per the external-resource-context skill (Reference Protocol). Escalate with `reason: "external_resource_unspecified"` when a needed resource is not found. #### Step 2 Completion Gate [BLOCKING when the Investigation Targets section contains one or more concrete file paths] This gate triggers only when the Investigation Targets section lists at least one concrete file path. โ˜ [VERIFIED] All listed Investigation Target files read in full (or escalated as `investigation_target_not_found` for missing paths) -โ˜ [VERIFIED] Investigation Notes appended to the task file's "Investigation Notes" section +โ˜ [VERIFIED] Investigation Notes recorded and appended to the task file when one is provided **ENFORCEMENT**: When the gate triggers and any item is unchecked, return `escalation_needed` per Structured Response Specification. ### 3. Implementation Execution #### Verification Mode and Test Environment Check -Read the selected Verification modes from the task file's Proof Obligations before mode-specific gates; treat those selections as authoritative. +Read selected Verification modes from the execution instructions before mode-specific gates; treat explicit selections as authoritative. **When at least one mode is `red-test` or `characterization`**: Verify the project-configured test toolchain is available โ€” test runner, fixtures/containers, and any mock servers or shared setup the tests rely on. @@ -158,27 +148,27 @@ Applies when Pre-implementation Verification finds a dependency this task requir - One local, reversible approach preserves the contract โ†’ proceed with it and record the integration handoff (what the real dependency must later provide, and where it connects) in Investigation Notes. - No local construct preserves the contract, or several valid constructs differ on an architectural trade-off (placement, dependency direction, contract shape) โ†’ stop and escalate with `escalation_type: "design_compliance_violation"` (see Design Doc Deviation Escalation in Structured Response Specification; populate every `details` field that schema requires). Map the Design Doc requirement for the dependency to `details.design_doc_expectation`, and the absent/unimplemented dependency with the exact undecided decision to `details.actual_situation`. -#### Adjacent Case Sweep (Required when the task file has a `Change Category` field set to one or more of `bug-fix`, `regression`, `state-change`, `boundary-change`) +#### Adjacent Case Sweep (Required when the execution instructions classify the work as one or more of `bug-fix`, `regression`, `state-change`, `boundary-change`) -Runs after Pre-implementation Verification, before the Binding Decision Check. This step fires on the field value the task materialization wrote โ€” read the field value and treat it as authoritative for whether the sweep applies. +Runs after Pre-implementation Verification, before the Binding Decision Check. Read the work classification from the execution instructions and treat it as authoritative for whether the sweep applies. -1. From the Investigation Targets (the materialization already extended them with the adjacent files), identify the cases sharing the same path, contract, persisted state, or external boundary as the change โ€” fallback behavior, stale state, retries, and external calls related to the change. +1. From the target and investigation paths in the execution instructions, identify the cases sharing the same path, contract, persisted state, or external boundary as the change โ€” fallback behavior, stale state, retries, and external calls related to the change. 2. Check the same defect class and record each case as `incorporated`, `unchanged` with evidence, or `out-of-scope` with the required scope decision; when none exist, record the searched surface. 3. Fold in-scope residuals into the applicable Proof Obligation and implementation; for `red-test`, include them in the failing tests. -#### Binding Decision Check (Required when the task file has a Binding Decisions section) +#### Binding Decision Check (Required when the execution instructions include Binding Decisions) Runs after Pre-implementation Verification, before the TDD cycle. 1. Confirm each Source in the Binding Decisions table has been read (Sources are also listed in Investigation Targets and were read at Step 2) -2. Record the planned implementation approach in Investigation Notes โ€” one sentence per distinct `Axis` value present in the task's Binding Decisions table. When multiple rows share the same `Axis` value, group them and record one sentence covering the group +2. Record the planned implementation approach in Investigation Notes โ€” one sentence per distinct `Axis` value in the Binding Decisions supplied by the execution instructions. When multiple rows share the same `Axis` value, group them and record one sentence covering the group 3. Evaluate each row's Compliance Check against the planned approach. Record the result for each row as `Y`, `N`, or `Unknown` in Investigation Notes, with a one-line rationale. Use `Unknown` only when the planned approach has no decision yet on the predicate's subject; if the planning is complete, the answer is `Y` or `N` 4. Per row, branch on the evaluation: - `Y`: proceed - `N`: stop implementation and produce the final response with `status: "escalation_needed"` and `escalation_type: "binding_decision_violation"` with `phase: "pre_implementation"` (see Binding Decision Violation Escalation in Structured Response Specification). `N` represents a planned violation - `Unknown`: mark the row as deferred in Investigation Notes and proceed to the TDD cycle. The Exit Gate re-evaluates every row (including Unknown rows deferred from this step) against the final implementation and escalates if any remains `N` or `Unknown` at that point -#### Reference Contract Check (Required when the task file has a Reference Contracts section) +#### Reference Contract Check (Required when the execution instructions include Reference Contracts) Runs after Pre-implementation Verification, alongside the Binding Decision Check. @@ -200,25 +190,25 @@ When adopting a pattern or dependency from existing code, apply coding-principle #### Implementation Flow (TDD Compliant) -**If all checkboxes already `[x]`**: Report "already completed" and end +**When the execution scope is supplied as a task file or Work Plan and all relevant checkboxes are already `[x]`**: Report "already completed" and end -**Per checkbox item, use the flow selected in the task file** (see testing-principles skill): +**For each implementation item, use the flow selected in the execution instructions** (see testing-principles skill): - **New/changed behavior or reproducible bug**: RED (write and confirm the failing test) โ†’ GREEN (minimal implementation) โ†’ REFACTOR โ†’ VERIFY - **Behavior-preserving refactor**: BASELINE (confirm existing tests pass or add passing characterization tests) โ†’ REFACTOR โ†’ VERIFY the same evidence - **Non-reproducible bug**: EVIDENCE BASELINE (confirm the recorded reproduction attempt, concrete blocker, and named alternate evidence) โ†’ FIX โ†’ VERIFY that evidence - **Non-executable deliverable**: SOURCE BASELINE (read the named source and acceptance evidence) โ†’ PRODUCE/UPDATE โ†’ VERIFY the deliverable against them -- **Progress Update**: After verification, set `[ ]` โ†’ `[x]` in the task file, work plan, and design doc +- **Progress Update**: Apply the Responsibility Boundaries progress rule after verification **Test types**: Unit tests โ€” use the applicable flow above; Integration tests โ€” create and execute with implementation; E2E tests โ€” execute in final phase only. #### Operation Verification -- Execute "Operation Verification Methods" section in task +- Execute the Operation Verification Methods in the execution instructions - Perform verification according to level defined in implementation-approach skill - Record reason if unable to verify ### 4. Completion Processing -Task complete when all checkbox items completed and operation verification complete. +Task complete when all implementation items and operation verification are complete. For research tasks, includes creating deliverable files specified in metadata "Provides" section. ### 5. Return JSON Result @@ -304,10 +294,10 @@ Report in the following JSON format upon task completion (**without executing qu "taskName": "[Task name being executed]", "escalation_type": "investigation_target_not_found", "missingTargets": [ - {"path": "[path specified in task file]", "searchHint": "[section/function hint if provided, or null]", "searchAttempts": ["Checked path directly", "Searched for similar filenames in same directory"]} + {"path": "[path specified in the execution instructions]", "searchHint": "[section/function hint if provided, or null]", "searchAttempts": ["Checked path directly", "Searched for similar filenames in same directory"]} ], "user_decision_required": true, - "suggested_options": ["Provide correct file path", "Remove this Investigation Target and proceed", "Update task file with current paths"] + "suggested_options": ["Provide correct file path", "Remove this Investigation Target and retry", "Update the execution instructions with current paths"] } ``` @@ -333,15 +323,15 @@ Report in the following JSON format upon task completion (**without executing qu "reason": "Out of scope file", "taskName": "[Task name being executed]", "escalation_type": "out_of_scope_file", - "details": {"file_path": "[path attempted to modify]", "allowed_list": ["[union of Target Files entries, task file, work plan, Provides paths]"], "modification_reason": "[why modification was attempted]"}, + "details": {"file_path": "[path attempted to modify]", "allowed_list": ["[explicit modification targets plus applicable task-file targets]"], "modification_reason": "[why modification was attempted]"}, "user_decision_required": true, - "suggested_options": ["Add this file to task Target files and retry", "Split into a separate task for this file", "Reconsider the implementation approach to stay within scope"] + "suggested_options": ["Authorize this file as a modification target and retry", "Split into a separate task for this file", "Reconsider the implementation approach to stay within scope"] } ``` #### 2-6. Binding Decision Violation Escalation -Triggered by `N` at the pre-implementation check, or `N` or `Unknown` at the Exit Gate re-evaluation, on any Compliance Check row in the task's Binding Decisions section. +Triggered by `N` at the pre-implementation check, or `N` or `Unknown` at the Exit Gate re-evaluation, on any Compliance Check row in the Binding Decisions supplied by the execution instructions. ```json { @@ -355,7 +345,7 @@ Triggered by `N` at the pre-implementation check, or `N` or `Unknown` at the Exi {"source": "[ADR file path with section hint, copied from Source column]", "axis": "[Axis value copied from the Axis column]", "decision": "[Decision text, copied from Decision column]", "complianceCheck": "[Compliance Check predicate, copied from Compliance Check column]", "evaluation": "N | Unknown", "rationale": "[One line explaining why the implementation does not satisfy the check, or why it cannot be evaluated]"} ], "user_decision_required": true, - "suggested_options": ["Adjust the implementation plan to satisfy the binding decision", "Update the ADR (then update the work plan's ADR Bindings and this task's Binding Decisions)", "Provide additional context that resolves the Unknown evaluation"] + "suggested_options": ["Adjust the implementation plan to satisfy the binding decision", "Update the governing decision and corresponding execution instructions", "Provide additional context that resolves the Unknown evaluation"] } ``` @@ -380,14 +370,14 @@ Triggered when the Test Environment Check finds the project-configured test tool This gate runs immediately before producing the final JSON response. -โ˜ All task checkboxes completed with evidence (or `escalation_needed` triggered earlier) +โ˜ All implementation items completed with evidence (or `escalation_needed` triggered earlier) โ˜ Implementation is consistent with the Investigation Notes recorded at Step 2 (when Investigation Targets were present) โ˜ Adjacent Case Sweep evidence is non-empty and records each inspected case and disposition, or the searched surface and no-case result (when Change Category triggers the sweep) -โ˜ 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). Re-evaluate here even when the pre-implementation check passed, because the implementation may have diverged from the planned approach -โ˜ Every Reference Contracts Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes (when the task file has a Reference Contracts section). Re-evaluate here even when the pre-implementation check passed -โ˜ A test exercises the roundtrip โ€” the value the producer emits parses to the value the consumer expects (when the task has a Boundary Context with a roundtrip check from the work plan's Connection Map) +โ˜ Every Binding Decisions Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes (when the execution instructions include Binding Decisions). Re-evaluate here even when the pre-implementation check passed, because the implementation may have diverged from the planned approach +โ˜ Every Reference Contracts Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes (when the execution instructions include Reference Contracts). Re-evaluate here even when the pre-implementation check passed +โ˜ A test exercises the roundtrip โ€” the value the producer emits parses to the value the consumer expects (when the execution instructions include a Boundary Context roundtrip check) โ˜ Every Proof Obligation satisfies its selected Verification mode and Evidence requirement โ˜ When test runs are cited as `runnableCheck` evidence, they are substantive and executable per the runnableCheck.result field spec (skipped tests, placeholder/TODO-only bodies, always-passing assertions, and 0-match runner reports do not count); non-test verification (build/typecheck/CLI) is not subject to this check โ˜ Final response is a single JSON with `status: "completed"` or `status: "escalation_needed"` and matches the schema in Structured Response Specification -**ENFORCEMENT**: When any gate item is unchecked, return `escalation_needed`. Use `escalation_type: "binding_decision_violation"` with `phase: "exit_gate"` for Binding Decisions failures; use `escalation_type: "design_compliance_violation"` for other gate failures (checkbox incompletion or divergence from Investigation Notes). +**ENFORCEMENT**: When any gate item is unchecked, return `escalation_needed`. Use `escalation_type: "binding_decision_violation"` with `phase: "exit_gate"` for Binding Decisions failures; use `escalation_type: "design_compliance_violation"` for other gate failures (incomplete work or divergence from Investigation Notes). diff --git a/dev-workflows/skills/recipe-add-integration-tests/SKILL.md b/dev-workflows/skills/recipe-add-integration-tests/SKILL.md index 40be943..ad5bfa3 100644 --- a/dev-workflows/skills/recipe-add-integration-tests/SKILL.md +++ b/dev-workflows/skills/recipe-add-integration-tests/SKILL.md @@ -5,6 +5,7 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. **Context**: Test addition workflow for existing implementations (backend, frontend, or fullstack) @@ -12,13 +13,17 @@ Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or g **Core Identity**: "I am an orchestrator." -**First Action**: Register Steps 0-8 using TaskCreate before any execution. +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. -**Why Delegate**: 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. +**Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression; include declined IDs with governing reasons and evidence in the final user report. +Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. + +**First Action**: Register Steps 1-7 using TaskCreate before any execution. + +**Why Delegate**: Orchestrator's context is shared across all steps. Direct implementation consumes context needed for review and quality check phases. Subagents work in isolated context. **Execution Method**: - Skeleton generation โ†’ delegate to acceptance-test-generator -- Task file creation โ†’ orchestrator creates directly (minimal context usage) - Test implementation โ†’ delegate to task-executor - Test review โ†’ delegate to integration-test-reviewer - Quality checks โ†’ delegate to quality-fixer @@ -32,10 +37,6 @@ Document paths: $ARGUMENTS ## Execution Flow -### Step 0: Execute Skill - -Execute Skill: documentation-criteria (for task file template in Step 3) - ### Step 1: Discover and Validate Documents ```bash @@ -71,107 +72,67 @@ Invoke acceptance-test-generator using Agent tool: **Expected output**: `generatedFiles` containing integration and e2e paths -### Step 3: Create Task Files [GATE] - -Create one task file per layer, using the monorepo-flow.md naming convention for deterministic agent routing: -- Backend skeletons exist โ†’ `docs/plans/tasks/integration-tests-backend-task-YYYYMMDD.md` -- Frontend skeletons exist โ†’ `docs/plans/tasks/integration-tests-frontend-task-YYYYMMDD.md` -- Single-layer (no backend/frontend distinction) โ†’ `docs/plans/tasks/integration-tests-backend-task-YYYYMMDD.md` - -**Template** (per task file): -```markdown ---- -name: Implement [layer] integration tests for [feature name] -type: test-implementation ---- - -## Objective - -Implement test cases defined in skeleton files. - -## Target Files - -- Skeleton: [layer-specific paths from Step 2 generatedFiles] -- Design Doc: [layer-specific Design Doc from Step 1] +### Step 3: Test Implementation -## Tasks - -- [ ] Implement each test case in skeleton -- [ ] Verify all tests pass -- [ ] Ensure coverage meets requirements - -## Acceptance Criteria - -- All skeleton test cases implemented -- All tests passing -- quality-fixer reports approved -``` - -**Output**: "Task file(s) created at [path(s)]. Ready for Step 4." - -### Step 4: Test Implementation - -For each task file from Step 3, record the current HEAD as `diffBase`, then invoke task-executor routed by filename pattern (per monorepo-flow.md): -- `*-backend-task-*` โ†’ `subagent_type`: "dev-workflows:task-executor" -- `*-frontend-task-*` โ†’ `subagent_type`: "dev-workflows-frontend:task-executor-frontend" +For each layer with generated skeletons, record the current HEAD as `diffBase`, then invoke the layer's task-executor: +- Backend or single-layer โ†’ `subagent_type`: "dev-workflows:task-executor" +- Frontend โ†’ `subagent_type`: "dev-workflows-frontend:task-executor-frontend" - `description`: "Implement integration tests" -- `prompt`: "Task file: [task file path from Step 3]. Implement tests following the task file." +- `prompt`: "Implement every test defined by these generated skeletons: [layer-specific Step 2 paths]. Governing documents: [layer-specific Design Doc and UI Spec when present]. Keep changes within the generated tests and the setup or fixture files they require. Verify the implemented tests against the skeleton claims." + +Execute one layer at a time through Steps 3โ†’4โ†’5โ†’6โ†’7 before starting the next. -Execute one task file at a time through Steps 4โ†’5โ†’6โ†’7 before starting the next. +**Expected output**: `status`, `filesModified`, `testsAdded`, `mutationEvidence` -**Expected output**: `status`, `testsAdded` +Apply this response gate after every task-executor invocation in Steps 3 and 5: +- `status: completed`, `filesModified` and `testsAdded` are present, and at least one changed integration/E2E path can be identified from the cumulative response paths against `diffBase` โ†’ Proceed to Step 4 +- `status: escalation_needed` โ†’ Escalate to the user +- Any other status, or a response missing the required fields above โ†’ Stop and report the invalid or missing fields -### Step 5: Test Review +### Step 4: Test Review Invoke integration-test-reviewer using Agent tool: - `subagent_type`: "dev-workflows:integration-test-reviewer" - `description`: "Review test quality" -- `prompt`: "Review test quality. changedTestFiles: [integration/E2E paths in Step 4 filesModified or testsAdded that differ from diffBase]. diffBase: [revision recorded before Step 4]. skeletonFiles: [layer-specific paths from Step 2 generatedFiles matching current task's layer]. taskFile: [current task file]. mutationEvidence: [Step 4 mutationEvidence]." +- `prompt`: "Review test quality. changedTestFiles: [integration/E2E paths in Step 3 filesModified or testsAdded that differ from diffBase]. diffBase: [revision recorded before Step 3]. skeletonFiles: [layer-specific paths from Step 2 generatedFiles]. mutationEvidence: [Step 3 mutationEvidence]." -**Expected output**: `status` (approved/needs_revision/blocked), `testFiles`, `reviewBasis`, `requiredFixes` +**Expected output**: `status` (approved/needs_revision/blocked), `testFiles`, `reviewBasis`, `qualityIssues`, `requiredFixes` -### Step 6: Apply Review Fixes +### Step 5: Apply Review Fixes -Check Step 5 result: -- `status: approved` โ†’ Mark complete, proceed to Step 7 -- `status: needs_revision` โ†’ Invoke task-executor with requiredFixes, then return to Step 5 +Check Step 4 result: +- `status: approved` โ†’ Mark complete, proceed to Step 6 - `status: blocked` โ†’ Escalate to user +- `status: needs_revision` โ†’ Apply the Review Resolution Gate + - one or more `apply` findings โ†’ Invoke task-executor with those findings, apply the executor response gate above, then return to Step 4 with `prior_feedback` + - every actionable finding is `decline` โ†’ Mark review complete and proceed to Step 6 + - any unresolved `user_decision_required` finding โ†’ Escalate to user -Invoke task-executor routed by task filename pattern: -- `*-backend-task-*` โ†’ `subagent_type`: "dev-workflows:task-executor" -- `*-frontend-task-*` โ†’ `subagent_type`: "dev-workflows-frontend:task-executor-frontend" +Invoke the same layer's task-executor: - `description`: "Fix review findings" -- `prompt`: "Fix the following issues in test files: [requiredFixes from Step 5]" +- `prompt`: "Fix these adjudicated test-review findings directly: [apply findings with IDs, governing basis, smallest correction, affected paths, and observable verification condition]." -### Step 7: Quality Check +### Step 6: Quality Check -Invoke quality-fixer routed by task filename pattern: -- `*-backend-task-*` โ†’ `subagent_type`: "dev-workflows:quality-fixer" -- `*-frontend-task-*` โ†’ `subagent_type`: "dev-workflows-frontend:quality-fixer-frontend" +Invoke quality-fixer for the current layer: +- Backend or single-layer โ†’ `subagent_type`: "dev-workflows:quality-fixer" +- Frontend โ†’ `subagent_type`: "dev-workflows-frontend:quality-fixer-frontend" - `description`: "Final quality assurance" -- Pass Step 4 `mutationEvidence` and `qualityCommand` when available (caller first, otherwise current task). +- Pass the latest executor's `filesModified` and `mutationEvidence`. - `prompt`: "Final quality assurance for test files added in this workflow. Run all tests and verify coverage." **Expected output**: `status` (approved/stub_detected/blocked) Check quality-fixer response: -- `stub_detected` โ†’ Return to Step 4 with `incompleteImplementations[]` details, then re-execute Steps 4โ†’5โ†’6โ†’7 +- `stub_detected` โ†’ Return to Step 3 with `incompleteImplementations[]` details, then re-execute Steps 3โ†’4โ†’5โ†’6 - `blocked` โ†’ Escalate to user -- `approved` โ†’ Proceed to Step 8 +- `approved` โ†’ Proceed to Step 7 -### Step 8: Commit +### Step 7: Commit On `approved` from quality-fixer: - Commit test files using Bash with message format: "test: add [layer] integration tests for [feature name]" -### Step 9: Final Cleanup - -After all task files have been processed and committed, delete the task files this recipe created. Their work is committed; `docs/plans/` is ephemeral working state and is not retained between recipe runs: - -- Delete every file matching `docs/plans/tasks/integration-tests-backend-task-*.md` and `docs/plans/tasks/integration-tests-frontend-task-*.md` created during this run - -If task files cannot be deleted (filesystem error), report the failure but do not block completion. - ## Scope Boundary for Subagents Append the following block to every subagent prompt invoked from this recipe: diff --git a/dev-workflows/skills/recipe-build/SKILL.md b/dev-workflows/skills/recipe-build/SKILL.md index d52365a..8c5ea38 100644 --- a/dev-workflows/skills/recipe-build/SKILL.md +++ b/dev-workflows/skills/recipe-build/SKILL.md @@ -5,13 +5,19 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. ## Orchestrator Definition **Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. + +**Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression; include declined IDs with governing reasons and evidence in the final user report. +Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. + **Execution Protocol**: -1. **Delegate all work through Agent tool** โ€” invoke sub-agents, pass deliverable paths between them, and report results (permitted tools: see subagents-orchestration-guide "Orchestrator's Permitted Tools") +1. **Invoke named specialists for deliverable production** โ€” pass deliverable paths between them and validate their results (see subagents-orchestration-guide "Orchestrator Execution Boundary") 2. **Follow the 4-step task cycle exactly**: execute โ†’ branch on executor result โ†’ quality-fix โ†’ commit 3. **Enter autonomous mode** when user provides execution instruction with existing task files โ€” this IS the batch approval 4. **Scope**: Complete when all tasks are committed or escalation occurs @@ -26,7 +32,7 @@ Work plan: $ARGUMENTS Before any task processing, locate the work plan. Resolution rule: 1. List task files in `docs/plans/tasks/` matching the single-layer pattern `{plan-name}-task-*.md`. Layer-aware fullstack tasks (`{plan-name}-backend-task-*.md` / `{plan-name}-frontend-task-*.md`) are excluded here so a stale fullstack run does not redirect this recipe to the wrong work plan -2. From the matched files, also exclude every file matching any of these patterns โ€” they originate from other workflow phases and are not implementation tasks for this run's plan: `*-task-prep-*.md` (readiness preflight tasks), `_overview-*.md` (materialization overview file), `*-phase*-completion.md` (per-phase completion files), `review-fixes-*.md` (post-implementation review fixes), `integration-tests-*-task-*.md` (integration-test add-on scaffolding) +2. From the matched files, also exclude `_overview-*.md` (materialization overview files) and `*-phase*-completion.md` (per-phase completion files). 3. For each remaining file, extract the `{plan-name}` prefix as the segment that appears before `-task-` 4. When at least one task file matches, the work plan is `docs/plans/{plan-name}.md` for the prefix that has the most recent task-file mtime; ties broken by the lexicographically last `{plan-name}` 5. When no task file matches the restricted pattern, the work plan is the most-recent-mtime non-template `.md` in `docs/plans/` @@ -36,7 +42,7 @@ Before any task processing, locate the work plan. Resolution rule: Compute the **Consumed Task Set** for this run โ€” the exact files this recipe owns, executes, and later deletes. Use the same restricted pattern as Work Plan Resolution: 1. List task files in `docs/plans/tasks/` matching the single-layer pattern `{plan-name}-task-*.md` for the `{plan-name}` resolved by Work Plan Resolution. Layer-aware fullstack tasks are excluded -2. Exclude every file matching: `*-task-prep-*.md`, `_overview-*.md`, `*-phase*-completion.md`, `review-fixes-*.md`, `integration-tests-*-task-*.md` (these originate from other workflow phases) +2. Exclude every file matching `_overview-*.md` or `*-phase*-completion.md`. Every subsequent reference to "task files" in this recipe โ€” Task Generation Decision Flow, Task Execution Cycle iteration, and Final Cleanup โ€” uses this set, not the unrestricted `docs/plans/tasks/*.md` glob. @@ -48,7 +54,7 @@ Analyze the Consumed Task Set and determine the action required: |-------|----------|-------------| | Tasks exist | Consumed Task Set is non-empty | User's execution instruction serves as batch approval โ†’ Enter autonomous execution immediately | | No tasks + plan exists | Consumed Task Set is empty but the resolved work plan exists | Confirm with user โ†’ run task-decomposer | -| Neither exists + Design Doc exists | No plan, no Consumed Task Set, but `docs/design/*.md` exists | Invoke work-planner to create work plan from Design Doc, then run document-reviewer (`dev-workflows:document-reviewer`, doc_type: WorkPlan); branch on the reviewer's `verdict.decision` โ€” on `needs_revision`, re-invoke work-planner (update) and re-review until `approved`/`approved_with_conditions`; if the same blocking finding repeats without new evidence or a contract change, stop and escalate it; then present the reviewed plan for batch approval before task materialization; on `rejected`, stop before task materialization and escalate to the user | +| Neither exists + Design Doc exists | No plan, no Consumed Task Set, but `docs/design/*.md` exists | Invoke work-planner to create a work plan, then run document-reviewer (`dev-workflows:document-reviewer`, doc_type: WorkPlan). Apply the Review Resolution Gate: update for `apply`, re-review with `prior_feedback`, progress when all actionable findings are `decline`, and escalate unresolved `user_decision_required`; then present the resolved plan for batch approval before task materialization | | Neither exists | No plan, no Consumed Task Set, no Design Doc | Report missing prerequisites to user and stop | ## Task Materialization Phase (Conditional) @@ -92,9 +98,12 @@ For EACH task in the Consumed Task Set, YOU MUST: 2. **BRANCH ON EXECUTOR RESULT**: - `status: "escalation_needed"` or `"blocked"` โ†’ STOP and escalate to user - `requiresTestReview` is `true` โ†’ Invoke integration-test-reviewer with `diffBase`, changed integration/E2E paths, `taskFile`, prompt-only claims, and `mutationEvidence` - - `needs_revision` โ†’ Return to step 1 with `requiredFixes` - `approved` โ†’ Proceed to step 3 - `blocked` โ†’ STOP and escalate to user + - `needs_revision` โ†’ Apply the Review Resolution Gate + - one or more `apply` findings โ†’ Return to step 1 with those findings, then re-review with `prior_feedback` + - every actionable finding is `decline` โ†’ Proceed to step 3 + - any unresolved `user_decision_required` finding โ†’ STOP and escalate to user - `readyForQualityCheck: true` โ†’ Proceed to step 3 3. **QUALITY-FIX**: Invoke quality-fixer with `task_file`, upstream `mutationEvidence`, and `qualityCommand` when available (caller first, otherwise current task) - `stub_detected` โ†’ Return to step 1 with `incompleteImplementations[]` details @@ -146,4 +155,5 @@ Final report must include: - Quality check result - Commit count - Cleanup result +- Declined actionable findings with ID, governing reason, and evidence - Escalation or blocking summary, if any diff --git a/dev-workflows/skills/recipe-design/SKILL.md b/dev-workflows/skills/recipe-design/SKILL.md index 15d63d1..0c27452 100644 --- a/dev-workflows/skills/recipe-design/SKILL.md +++ b/dev-workflows/skills/recipe-design/SKILL.md @@ -5,6 +5,7 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. **Context**: Dedicated to the design phase. @@ -12,15 +13,20 @@ Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or g **Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. The scope bootstrap locates seed files; the named specialists own semantic investigation and artifact authorship. + +**Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression; include declined IDs with governing reasons and evidence in the final user report. +Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. + **Execution Protocol**: -1. **Delegate all work** to sub-agents โ€” your role is to invoke sub-agents, pass data between them, and report results. The one exception is the Step 1 scope bootstrap, a recipe-local orchestrator task limited to locating seed files. +1. **Invoke named specialists for deliverable production** โ€” pass data between them and validate their results. Step 1 is a recipe-local read-only scope bootstrap limited to locating seed files. 2. **Run the design flow below in order**: - Execute: scope bootstrap โ†’ codebase-analyzer โ†’ [Stop: Scope confirmation] โ†’ technical-designer โ†’ code-verifier โ†’ document-reviewer โ†’ design-sync - code-verifier and design-sync apply when the design output is a Design Doc; both are skipped for ADR-only - **Stop at every `[Stop: ...]` marker** โ†’ Wait for user approval before proceeding 3. **Scope**: Complete when design documents receive approval -**subagents-orchestration-guide usage**: Reference the guide only for orchestration principles (Delegation Boundary, Decision precedence, permitted tools), the Scale Determination table, and handoff contracts HC-02 onward. This recipe defines its own start order and subagent prompts. The guide's requirement-analyzer-origin flow, First Action Rule, HC-01, and Call Examples do not apply to this recipe. +**subagents-orchestration-guide usage**: Use the guide for orchestration principles (Delegation Boundary, Decision precedence, Execution Boundary), the Scale Determination table, and handoff contracts HC-02 onward. This recipe's start order and subagent prompts supersede the guide's requirement-analyzer-origin flow, First Action Rule, HC-01, and Agent-Specific Prompt Content. **CRITICAL**: Execute document-reviewer, design-sync (for Design Docs), and all stopping points โ€” each serves as a quality gate. Skipping any step risks undetected inconsistencies. @@ -78,7 +84,9 @@ Invoke codebase-analyzer with its existing schema. The orchestrator constructs ` ### Step 3: Scope Confirmation After codebase-analyzer returns, confirm the design scope with the user before any design work. This is a recipe-local confirmation step. -First run the requirement-convergence hearing protocol, using the codebase-analyzer findings as the facts it presents. This recipe has no requirement-analyzer, so the orchestrator both elicits and judges the fields, recording the result as the skill's `convergence` object (`outcome`, `requirements[]` with layer labels, `nonGoals[]`, plus a readiness label per field). `cost` does not apply here: the orchestrator cannot search the repository, and entering this recipe already decided to design. Carry that object into Step 4 so technical-designer persists it to the Design Doc. +Execute Skill: requirement-convergence before running the hearing protocol. + +First run the requirement-convergence hearing protocol, using the codebase-analyzer findings as the facts it presents. In this flow, the orchestrator elicits and judges the fields and records the result as the skill's `convergence` object (`outcome`, `requirements[]` with layer labels, `nonGoals[]`, plus a readiness label per field). Treat `cost` as already resolved because semantic repository investigation is assigned to codebase-analyzer and entering this recipe decided to design. Carry that object into Step 4 so technical-designer persists it to the Design Doc. Then present, sourced from the codebase-analyzer JSON, using AskUserQuestion: - **Target files/modules**: `analysisScope.filesAnalyzed` and the modules they belong to @@ -105,13 +113,20 @@ Pass the full codebase-analyzer JSON to technical-designer (handoff contract HC- - **(Design Doc only)** Invoke **code-verifier** to verify the Design Doc against existing code. Skip for ADR. - `subagent_type: "dev-workflows:code-verifier"`, `description: "Design Doc verification"`, `prompt: "doc_type: design-doc document_path: [Design Doc path] Verify Design Doc against existing code."` - **(Design Doc only)** Invoke **document-reviewer** to verify consistency, completeness, and adopted design validity + - Treat the preceding code-verifier result as `code_verification` evidence; the document-reviewer result controls correction routing. - `subagent_type: "dev-workflows:document-reviewer"`, `description: "Design Doc review"`, `prompt: "Review [Design Doc path] for consistency, completeness, and adopted design validity. doc_type: DesignDoc. review_context: creation. requirements_verbatim: [user requirements verbatim]. confirmed_decisions: [Step 3 confirmed scope and user answers]. codebase_analysis: [codebase-analyzer JSON from Step 2]. code_verification: [code-verifier output from this step]"` + - Apply the Review Resolution Gate. When `apply` findings change the Design Doc, invoke technical-designer in update mode, then re-run code-verifier and document-reviewer with `prior_feedback`. - **(ADR only)** Invoke **document-reviewer** to verify consistency and completeness - `subagent_type: "dev-workflows:document-reviewer"`, `description: "ADR review"`, `prompt: "Review [ADR path] for consistency and completeness. doc_type: ADR. codebase_analysis: [codebase-analyzer JSON from Step 2]"` + - Apply the Review Resolution Gate. When `apply` findings change the ADR, invoke technical-designer in update mode and re-run document-reviewer with `prior_feedback`. - **(Design Doc only)** Invoke **design-sync** to verify consistency across design documents. Skip for ADR-only. - `subagent_type: "dev-workflows:design-sync"`, `description: "Design consistency check"`, `prompt: "Check consistency across all Design Docs in docs/design/. Report conflicts and overlaps."` + - Apply the Review Resolution Gate to every reported conflict. + - One or more `apply` findings โ†’ invoke the named technical designer for each affected Design Doc; re-run code-verifier and document-reviewer for each modified document with the latest verification and `prior_feedback`, then re-run design-sync + - Every actionable conflict is `decline` โ†’ proceed to the approval stop + - Any unresolved `user_decision_required` conflict โ†’ stop for user input -**[STOP]**: Present the design document, plus design-sync results for a Design Doc, and obtain user approval. +**[STOP]**: Present the design document, plus design-sync results for a Design Doc, and obtain user approval. For an approved ADR, invoke technical-designer in update mode to set its status to `Accepted` and verify the update before completion. ## Completion Criteria @@ -123,7 +138,7 @@ Pass the full codebase-analyzer JSON to technical-designer (handoff contract HC- - [ ] Executed code-verifier on Design Doc and passed results to document-reviewer (skip for ADR-only) - [ ] Executed document-reviewer and addressed feedback - [ ] Executed design-sync for consistency verification (skip for ADR-only) -- [ ] Obtained user approval for design document +- [ ] Obtained user approval for the design document and verified an approved ADR has status `Accepted` ## Output Example Design phase completed. diff --git a/dev-workflows/skills/recipe-diagnose/SKILL.md b/dev-workflows/skills/recipe-diagnose/SKILL.md index fe5cb06..2f34835 100644 --- a/dev-workflows/skills/recipe-diagnose/SKILL.md +++ b/dev-workflows/skills/recipe-diagnose/SKILL.md @@ -5,6 +5,7 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. **Context**: Diagnosis flow to identify root cause and present solutions @@ -12,7 +13,9 @@ Target problem: $ARGUMENTS ## Orchestrator Definition -**Core Identity**: "I am not a worker. I am an orchestrator." +**Core Identity**: "I am an orchestrator." + +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. **Execution Method**: - Investigation โ†’ performed by investigator @@ -232,4 +235,3 @@ Rationale: [Selection rationale] - [ ] Executed solver - [ ] Achieved coverageAssessment=sufficient (or obtained user approval after 2 additional iterations) - [ ] Presented final report to user - diff --git a/dev-workflows/skills/recipe-implement/SKILL.md b/dev-workflows/skills/recipe-implement/SKILL.md index 57437b7..f0c44fa 100644 --- a/dev-workflows/skills/recipe-implement/SKILL.md +++ b/dev-workflows/skills/recipe-implement/SKILL.md @@ -5,6 +5,7 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. **Context**: Full-cycle implementation management (Requirements Analysis โ†’ Design โ†’ Planning โ†’ Implementation โ†’ Quality Assurance) @@ -12,8 +13,13 @@ Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or g **Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. + +**Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression; include declined IDs with governing reasons and evidence in the final user report. +Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. + **Execution Protocol**: -1. **Delegate all work through Agent tool** โ€” invoke sub-agents, pass deliverable paths between them, and report results (permitted tools: see subagents-orchestration-guide "Orchestrator's Permitted Tools") +1. **Invoke named specialists for deliverable production** โ€” pass deliverable paths between them and validate their results (see subagents-orchestration-guide "Orchestrator Execution Boundary") 2. **Follow subagents-orchestration-guide skill flows exactly**: - Execute one step at a time in the defined flow (Large/Medium/Small scale) - When flow specifies "Execute document-reviewer" โ†’ Execute it immediately @@ -53,6 +59,8 @@ When continuing existing flow, verify: ### After requirement-analyzer [Stop] +Execute Skill: requirement-convergence before running the hearing protocol. + Run the requirement-convergence hearing protocol on the returned `convergence` object before presenting anything else, using the analyzer's scope facts and cost band as the facts it presents. When user responds to questions: @@ -102,9 +110,12 @@ Escalate when the required fix or investigation falls outside that scope. 2. Check task-executor response: - `status: escalation_needed` or `blocked` โ†’ Escalate to user - `requiresTestReview` is `true` โ†’ Invoke integration-test-reviewer with `diffBase`, changed integration/E2E paths, `taskFile`, prompt-only claims, and `mutationEvidence` - - `needs_revision` โ†’ Return to step 1 with `requiredFixes` - `approved` โ†’ Proceed to step 3 - `blocked` โ†’ Escalate to user + - `needs_revision` โ†’ Apply the Review Resolution Gate + - one or more `apply` findings โ†’ Return to step 1 with those findings, then re-review with `prior_feedback` + - every actionable finding is `decline` โ†’ Proceed to step 3 + - any unresolved `user_decision_required` finding โ†’ Escalate to user - Otherwise โ†’ Proceed to step 3 3. quality-fixer โ†’ Pass `task_file`, upstream `mutationEvidence`, and `qualityCommand` when available (caller first, otherwise current task); run quality checks and fixes - `stub_detected` โ†’ Return to step 1 with `incompleteImplementations[]` details @@ -139,9 +150,7 @@ After acceptance-test-generator execution, when invoking work-planner (subagent_ - Generated fixture-e2e test file path or null (from `generatedFiles.fixtureE2e`) - Generated service-integration-e2e test file path or null (from `generatedFiles.serviceE2e`) - Per-lane E2E absence reason (from `e2eAbsenceReason.fixtureE2e` and `e2eAbsenceReason.serviceE2e`, when each lane is null) -- Explicit note: integration tests are created simultaneously with implementation, fixture-e2e tests are created alongside the UI feature phase, service-integration-e2e tests are executed only in the final phase ## Execution Method -All work is executed through sub-agents. -Sub-agent selection follows subagents-orchestration-guide skill. +Deliverable production is executed through the specialist selected by subagents-orchestration-guide; workflow decisions and returned-result validation remain with the orchestrator. diff --git a/dev-workflows/skills/recipe-plan/SKILL.md b/dev-workflows/skills/recipe-plan/SKILL.md index d0acefd..e2cd10a 100644 --- a/dev-workflows/skills/recipe-plan/SKILL.md +++ b/dev-workflows/skills/recipe-plan/SKILL.md @@ -5,6 +5,7 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. **Context**: Dedicated to the planning phase. @@ -12,8 +13,13 @@ Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or g **Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. + +**Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression; include declined IDs with governing reasons and evidence in the final user report. +Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. + **Execution Protocol**: -1. **Delegate all work** to sub-agents โ€” your role is to invoke sub-agents, pass data between them, and report results +1. **Invoke named specialists for deliverable production** โ€” pass data between them and validate their results 2. **Follow subagents-orchestration-guide skill planning flow exactly**: - Execute steps defined below - **Stop and obtain approval** for plan content before completion @@ -66,7 +72,7 @@ Invoke document-reviewer to review the work plan: - `subagent_type`: "dev-workflows:document-reviewer" - `description`: "Work plan review" - `prompt`: "doc_type: WorkPlan target: docs/plans/[plan-name].md. Review semantic traceability to the Design Doc, early verification placement, real-boundary verification coverage, Failure Mode Checklist, and Review Scope." -- The work plan is a derivation of the Design Doc, so plan-fidelity findings are resolved without user input while the revision loop makes observable progress. Branch on the reviewer's `verdict.decision`: on `needs_revision`, re-invoke work-planner in update mode with the findings and re-review, repeating until `approved` or `approved_with_conditions`; if the same blocking finding repeats without new evidence or a contract change, stop and escalate it. On `rejected`, escalate to the user. +- Apply the Review Resolution Gate before branching. On `needs_revision`, re-invoke work-planner in update mode with the `apply` findings and re-review with `prior_feedback`. A result whose actionable findings are all `decline` is eligible for approval; escalate unresolved `user_decision_required` or unusable inputs. ### Step 5: Present for Approval - Present the reviewed work plan to the user for batch approval. If the user requests changes, re-invoke work-planner with revised parameters and re-run Step 4. diff --git a/dev-workflows/skills/recipe-prepare-implementation/SKILL.md b/dev-workflows/skills/recipe-prepare-implementation/SKILL.md index acac374..9c70371 100644 --- a/dev-workflows/skills/recipe-prepare-implementation/SKILL.md +++ b/dev-workflows/skills/recipe-prepare-implementation/SKILL.md @@ -5,17 +5,20 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. -**Context**: Optional readiness phase between work-plan approval and recipe-*-build. Confirms the implementation will be observable from Phase 1 onward and resolves any gaps via Phase 0 tasks. Exits no-op when the readiness criteria already pass, so the recipe is safe to invoke unconditionally. +**Context**: Optional readiness phase between work-plan approval and recipe-*-build. Confirms the implementation will be observable from Phase 1 onward and resolves any gaps before build execution. Exits no-op when the readiness criteria already pass, so the recipe is safe to invoke unconditionally. ## Orchestrator Definition **Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. + **Execution Protocol**: -1. **Delegate all work through Agent tool** โ€” invoke sub-agents, pass deliverable paths between them, and report results (permitted tools: see subagents-orchestration-guide "Orchestrator's Permitted Tools") -2. **Self-contained scope**: When gaps are found, this recipe BOTH generates resolution tasks AND executes them through the standard 4-step cycle. Recipe completes only when readiness criteria pass or remaining gaps are escalated. -3. **No-op exit**: When the readiness scan finds no failing criteria, generate no resolution tasks and exit immediately, presenting the Readiness Report to the user. No files are modified in this branch. +1. **Invoke named specialists for deliverable production** โ€” pass deliverable paths between them and validate their results (see subagents-orchestration-guide "Orchestrator Execution Boundary") +2. **Self-contained scope**: When gaps are found, this recipe defines resolution items and executes them through the standard 4-step cycle. Recipe completes only when readiness criteria pass or remaining gaps are escalated. +3. **No-op exit**: When the readiness scan finds no failing criteria, generate no resolution items and exit immediately, presenting the Readiness Report to the user. No files are modified in this branch. Work plan: $ARGUMENTS @@ -84,48 +87,44 @@ When every applicable criterion is `pass` (zero `fail`): When one or more criteria are `fail` โ†’ proceed to Step 4. -### Step 4: Plan Resolution Tasks +### Step 4: Plan Resolution Items For each `fail` criterion: -1. Determine the smallest concrete task that closes the gap (examples: "Add fixture entry for ComponentX covering loading/empty/error states", "Add seed script for E2E user fixtures", "Document local startup commands in docs/run/local.md") -2. Decide the task's **layer** by matching every target file path against the markers below: +1. Determine the smallest concrete correction that closes the gap (examples: "Add fixture entry for ComponentX covering loading/empty/error states", "Add seed script for E2E user fixtures", "Document local startup commands in docs/run/local.md") +2. Decide the resolution item's **layer** by matching every target file path against the markers below: - **backend** when every target file path matches one of: `**/api/**`, `**/server/**`, `**/services/**`, `**/backend/**`, `**/handlers/**`, `**/repositories/**` - **frontend** when every target file path matches one of: `**/components/**`, `**/pages/**`, `**/web/**`, `**/frontend/**`, `**/*.tsx`, `**/*.jsx` - - **mixed** (target files span both backend and frontend markers) โ†’ escalate to user; ask the user to split the gap into per-layer tasks - - **unrecognized** (any target file matches neither backend nor frontend markers โ€” e.g., `docs/**`, `scripts/**`, root-level configs, fixture data files outside the markers above) โ†’ escalate to user; ask the user to either (a) decide which layer's executor / quality-fixer should run the task, or (b) update the markers if the project uses different paths + - **mixed** (target files span both backend and frontend markers) โ†’ escalate to user; ask the user to split the gap into per-layer items + - **unrecognized** (any target file matches neither backend nor frontend markers โ€” e.g., `docs/**`, `scripts/**`, root-level configs, fixture data files outside the markers above) โ†’ escalate to user; ask the user to either (a) decide which layer's executor / quality-fixer should run the item, or (b) update the markers if the project uses different paths Apply the rules in the order above. The first matching rule wins; "unrecognized" is the final fallback rather than a catch-all that defaults to backend. -3. Create a Phase 0 task file at `docs/plans/tasks/{plan-name}-backend-task-prep-{NN}.md` (backend) or `docs/plans/tasks/{plan-name}-frontend-task-prep-{NN}.md` (frontend) using the task template from documentation-criteria skill. The `-task-prep-` segment lets recipe-prepare-implementation distinguish prep tasks from implementation tasks while keeping the existing `{plan-name}-{layer}-task-*` matcher used by other recipes -4. Update the work plan to insert these tasks as Phase 0 (before Phase 1) -Present the proposed resolution task list to the user with AskUserQuestion. Proceed only after explicit approval โ€” this is the single human gate inside this recipe. +Present the proposed resolution item list to the user with AskUserQuestion. Proceed only after explicit approval โ€” this is the single human gate inside this recipe. -### Step 5: Execute Resolution Tasks +### Step 5: Execute Resolution Items -For each resolution task, run the standard 4-step cycle (see subagents-orchestration-guide "Task Management: 4-Step Cycle"): +For each approved resolution item, run execute โ†’ branch โ†’ quality-fix โ†’ commit: -1. **Agent tool** โ€” route by filename layer segment: - - `*-backend-task-prep-*` โ†’ `subagent_type: "dev-workflows:task-executor"` - - `*-frontend-task-prep-*` โ†’ `subagent_type: "dev-workflows-frontend:task-executor-frontend"` - - Filename without a recognized layer segment โ†’ escalate (the file should not exist; Step 4 prevents this) +1. **Agent tool** โ€” route by the item's layer: + - `backend` โ†’ `subagent_type: "dev-workflows:task-executor"` + - `frontend` โ†’ `subagent_type: "dev-workflows-frontend:task-executor-frontend"` + - Pass the exact resolution item, governing documents, target paths, and verification condition directly 2. Check escalation per orchestration-guide -3. **quality-fixer** โ€” route by the same filename layer segment: - - `*-backend-task-prep-*` โ†’ `"dev-workflows:quality-fixer"` - - `*-frontend-task-prep-*` โ†’ `"dev-workflows-frontend:quality-fixer-frontend"` - - Pass upstream `mutationEvidence` and `qualityCommand` when available (caller first, otherwise current task). +3. **quality-fixer** โ€” route by the same Executor lane: + - `backend` โ†’ `"dev-workflows:quality-fixer"` + - `frontend` โ†’ `"dev-workflows-frontend:quality-fixer-frontend"` + - Pass upstream `filesModified` and `mutationEvidence`. 4. **Commit** when quality-fixer returns `approved` Append the Scope Boundary block (below) to every subagent prompt. -### Step 6: Re-scan, Present Readiness Report, Cleanup, Exit - -1. **Re-scan**: Re-run the Step 2 readiness scan after all resolution tasks are committed. +### Step 6: Re-scan, Present Readiness Report, Exit -2. **Present Readiness Report**: Present the Readiness Report (see Output Format below) to the user. The report is shown in-session and is not written into the work plan โ€” the durable output of this recipe is the committed Phase 0 resolution tasks, not a persisted report. +1. **Re-scan**: Re-run the Step 2 readiness scan after all resolution items are committed. -3. **Final Cleanup**: Delete every prep task file this recipe created for the current `{plan-name}` (`docs/plans/tasks/{plan-name}-backend-task-prep-*.md` and `docs/plans/tasks/{plan-name}-frontend-task-prep-*.md`) AND the phase-completion file generated for prep phases (`docs/plans/tasks/{plan-name}-phase0-completion.md` when present, since prep tasks live in Phase 0). Prep task files for other plans are out of scope โ€” this recipe deletes only what it created for the current run. Their work is committed; `docs/plans/` is ephemeral working state and is not retained between recipe runs. The work plan itself is preserved for the downstream recipe-*-build / recipe-*-implement. +2. **Present Readiness Report**: Present the Readiness Report (see Output Format below) to the user. The report is shown in-session and is not written into the work plan โ€” the durable output is the committed readiness fixes. -4. **Exit**: +3. **Exit**: | Re-scan result | Action | |----------------|--------| @@ -164,8 +163,8 @@ Gaps resolved: [N] | R4 | ... | ... | | R5 | ... | ... | -### Resolution Tasks Executed (when gaps_resolved > 0) -- [task file path] โ€” [one-line summary] โ€” committed +### Resolution Items Executed (when gaps_resolved > 0) +- [criterion ID] โ€” [one-line summary] โ€” committed - ... ### Remaining Gaps (when outcome is escalated) @@ -176,7 +175,6 @@ Gaps resolved: [N] - [ ] Work plan loaded and Verification Strategy / E2E references / Phase structure extracted - [ ] Readiness scan run with per-criterion result and evidence recorded -- [ ] No-op exit when all `pass`, OR resolution tasks generated, approved, and executed via the 4-step cycle -- [ ] Re-scan run after the last resolution task commits -- [ ] Prep task files (and Phase 0 phase-completion file when generated) deleted from `docs/plans/tasks/` +- [ ] No-op exit when all `pass`, OR resolution items planned, approved, and executed via the 4-step cycle +- [ ] Re-scan run after the last resolution item commits - [ ] Final report presented to the user diff --git a/dev-workflows/skills/recipe-reverse-engineer/SKILL.md b/dev-workflows/skills/recipe-reverse-engineer/SKILL.md index de1ddcc..1980ca7 100644 --- a/dev-workflows/skills/recipe-reverse-engineer/SKILL.md +++ b/dev-workflows/skills/recipe-reverse-engineer/SKILL.md @@ -5,6 +5,7 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. **Context**: Reverse engineering workflow to create documentation from existing code @@ -14,10 +15,15 @@ Target: $ARGUMENTS **Core Identity**: "I am an orchestrator." +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. + +**Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression; include declined IDs with governing reasons and evidence in the final user report. +Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. + **Execution Protocol**: -1. **Delegate all work through Agent tool** โ€” invoke sub-agents, pass deliverable paths between them, and report results (permitted tools: see subagents-orchestration-guide "Orchestrator's Permitted Tools") +1. **Invoke named specialists for deliverable production** โ€” pass deliverable paths between them and validate their results (see subagents-orchestration-guide "Orchestrator Execution Boundary") 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 +3. **Preserve evidence while bridging outputs** โ€” extract and transform the fields required by the next specialist without changing supported meaning; apply Review Resolution before routing any correction **Task Registration**: Register phases first using TaskCreate, then steps within each phase as you enter it. Update status using TaskUpdate. @@ -163,10 +169,7 @@ prompt: | #### Step 5: Revision (conditional) -**Trigger Conditions** (any one of the following): -- Review status is "Needs Revision" or "Rejected" -- Critical discrepancies exist in `$STEP_3_OUTPUT` -- consistencyScore < 70 +Pass `$STEP_3_OUTPUT` to document-reviewer as verification evidence, then apply the Review Resolution Gate to `$STEP_4_OUTPUT`. Run revision only when at least one finding is `apply`; a decline-only result completes the review, and unresolved `user_decision_required` stops for user input. **Agent tool invocation**: ``` @@ -178,21 +181,17 @@ prompt: | Operation Mode: update Existing PRD: $STEP_2_OUTPUT - ## Review Feedback - $STEP_4_OUTPUT + ## Adjudicated Findings + [apply findings with IDs, governing basis, smallest correction, and affected sections] - ## Code Verification Results - $STEP_3_OUTPUT - - Address discrepancies by severity. Critical and major items require correction. - Minor items: correct if straightforward, otherwise leave as-is with rationale. + Treat these findings as the complete revision scope and preserve adjacent content. ``` -**Loop Control**: Maximum 2 revision cycles. After 2 cycles, flag for human review regardless of status. +**Re-validation**: After each revision, re-run code-verifier on the revised document, then re-run document-reviewer with the latest `code_verification` and `prior_feedback`. #### Unit Completion -- [ ] Review status is "Approved" or "Approved with Conditions" +- [ ] No `apply` findings remain; every other review finding has a disposition and every `user_decision_required` item has a recorded user decision - [ ] Human review passed (if enabled in Step 0) **Next**: Proceed to next unit. After all units โ†’ Phase 2. @@ -361,10 +360,7 @@ prompt: | #### Step 10: Revision (conditional) -**Trigger Conditions** (same as Step 5): -- Review status is "Needs Revision" or "Rejected" -- Critical discrepancies exist in `$STEP_8_OUTPUT` -- consistencyScore < 70 +Pass `$STEP_8_OUTPUT` to document-reviewer as verification evidence, then apply the Review Resolution Gate to `$STEP_9_OUTPUT`. Run revision only when at least one finding is `apply`; a decline-only result completes the review, and unresolved `user_decision_required` stops for user input. **Agent tool invocation (per Design Doc)**: ``` @@ -376,21 +372,17 @@ prompt: | Operation Mode: update Existing Design Doc: $STEP_7_OUTPUT (or $STEP_7a_OUTPUT / $STEP_7b_OUTPUT) - ## Review Feedback - $STEP_9_OUTPUT - - ## Code Verification Results - $STEP_8_OUTPUT + ## Adjudicated Findings + [apply findings with IDs, governing basis, smallest correction, and affected sections] - Address discrepancies by severity. Critical and major items require correction. - Minor items: correct if straightforward, otherwise leave as-is with rationale. + Treat these findings as the complete revision scope and preserve adjacent content. ``` -**Loop Control**: Maximum 2 revision cycles. After 2 cycles, flag for human review regardless of status. +**Re-validation**: After each revision, re-run code-verifier on the revised document, then re-run document-reviewer with the latest `code_verification` and `prior_feedback`. #### Unit Completion -- [ ] Review status is "Approved" or "Approved with Conditions" +- [ ] No `apply` findings remain; every other review finding has a disposition and every `user_decision_required` item has a recorded user decision - [ ] Human review passed (if enabled in Step 0) **Next**: Proceed to next unit. After all units โ†’ Final Report. @@ -409,4 +401,3 @@ Output summary including: | Discovery finds nothing | Ask user for project structure hints | | Generation fails | Log failure, continue with other units, report in summary | | consistencyScore < 50 | Flag for mandatory human review โ€” require explicit human approval | -| Review rejects after 2 revisions | Stop loop, flag for human intervention | diff --git a/dev-workflows/skills/recipe-review/SKILL.md b/dev-workflows/skills/recipe-review/SKILL.md index 939d39d..8fff7da 100644 --- a/dev-workflows/skills/recipe-review/SKILL.md +++ b/dev-workflows/skills/recipe-review/SKILL.md @@ -5,6 +5,7 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. **Context**: Post-implementation quality assurance @@ -12,7 +13,12 @@ Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or g **Core Identity**: "I am an orchestrator." -**First Action**: Register Steps 1-11 using TaskCreate before any execution. +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. + +**Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression; include declined IDs with governing reasons and evidence in the final user report. +Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. + +**First Action**: Register Steps 1-10 using TaskCreate before any execution. ## Execution Method @@ -56,17 +62,9 @@ Invoke security-reviewer using Agent tool: **If security-reviewer returned `blocked`**: Stop immediately. Report the blocked finding and escalate to user. Do not proceed to fix steps. -**Code compliance criteria (considering project stage)**: -- Prototype: Pass at 70%+ -- Production: 90%+ recommended - -**Security criteria**: -- `approved` or `approved_with_notes` โ†’ Pass -- `needs_revision` โ†’ Fail +Apply the Review Resolution Gate to both outputs before reporting or routing them. Finding dispositions determine routing; compliance percentages remain diagnostic. -**Report both results independently using subagent output fields only**: - -Before presenting to the user, the orchestrator computes a recommended route per finding using the rule below (this rule is internal โ€” do not include it in the user-facing prompt): +For each `apply` or `user_decision_required` finding, compute a proposed route using the rule below: | Finding pattern | Recommended route | |-----------------|-------------------| @@ -74,7 +72,7 @@ Before presenting to the user, the orchestrator computes a recommended route per | `dd_violation` where the code drifted from a still-correct Design Doc | `c` (Code-side fix) | | `reliability` / `security` / `maintainability` findings | `c` (Code-side fix) | -Then present to the user (label each finding with its recommended route, grouped by route): +Then present the adjudicated result to the user. Group `apply` and `user_decision_required` findings by proposed route, and list declined IDs with their reasons separately: ``` Code Compliance: [complianceRate from code-reviewer] @@ -97,23 +95,19 @@ Security Review: [status from security-reviewer] - [policy] [location]: [description] โ€” [rationale] [recommended: c] Notes: [notes from security-reviewer, if present] -Resolve discrepancies โ€” confirm or override the recommended route per finding: +Approve the proposed changes or decide unresolved items: c) Code-side fix โ€” code violates Design Doc; modify code to match d) Design-side update โ€” code is correct; Design Doc is stale, revise it - s) Skip โ€” accept current state without changes + s) Decline โ€” record the governing reason and accept current state ``` -Use AskUserQuestion. The default offer is **"accept all recommended routes"** โ€” a single confirmation for the typical case where the orchestrator's recommendations are correct. When the user wants to override, collect per-finding c/d/s decisions instead. If the user selects `s` for everything: skip Steps 5-10, proceed to Step 11. +This review command authorizes analysis; use AskUserQuestion to obtain separate implementation authority. The batch option is **"approve all proposed `apply` routes"** and its scope consists exclusively of those routes. Collect an explicit decision for each `user_decision_required` item. When the approved change set is empty, proceed directly to Step 10. Pass approved findings, routes, covered files/sections, and any stated total size budget to update or fix agents. Before re-validation, map every diff hunk to an approved finding or required consistency update; request a scope decision for unmapped or over-budget changes. -### Step 5: Execute Skill - -Execute Skill: documentation-criteria (for task file template) - -### Step 5d: Design-Side Update +### Step 5: Design-Side Update -Run this step only when the user routed at least one finding to `d`. When all routes are `c` or `s`, skip directly to Step 6. +Run this step only when the user routed at least one finding to `d`. When no `d` routes exist, skip it; continue to Step 6 only when approved `c` routes remain. 1. Invoke technical-designer in update mode using Agent tool: - `subagent_type`: "dev-workflows:technical-designer" @@ -124,6 +118,7 @@ Run this step only when the user routed at least one finding to `d`. When all ro - `subagent_type`: "dev-workflows:document-reviewer" - `description`: "Document review of updated Design Doc" - `prompt`: "Review updated Design Doc at [path] for consistency and completeness. doc_type: DesignDoc. review_context: update." + - Apply the Review Resolution Gate to this result. Route `apply` findings back to technical-designer and re-run document-reviewer with `prior_feedback`; stop for unresolved `user_decision_required`; proceed when the result is approved or every actionable finding is `decline`. 3. When multiple Design Docs exist (`ls docs/design/*.md | grep -v template | wc -l > 1`), invoke design-sync: - `subagent_type`: "dev-workflows:design-sync" @@ -131,53 +126,44 @@ Run this step only when the user routed at least one finding to `d`. When all ro - `prompt`: "source_design: [updated DD path]. Detect conflicts across all Design Docs after the update." - When `sync_status: conflicts_found`: present conflicts to the user; resolution requires re-invoking technical-designer for affected DDs. -4. After Step 5d completes: - - If the user selected `d` for all findings (no `c` routes) โ†’ skip Steps 6-8, proceed to Step 9 for re-validation +4. After Step 5 completes: + - If the user selected `d` for all findings (no `c` routes) โ†’ skip Steps 6-7, proceed to Step 8 for re-validation - If the user selected both `d` and `c` โ†’ re-evaluate the `c`-routed findings against the updated DD and drop any that are now satisfied by the DD revision; then proceed to Step 6 with the remaining `c` findings -### Step 6: Create Task File - -Create task file at `docs/plans/tasks/review-fixes-YYYYMMDD.md` -Include both code compliance issues and security requiredFixes. - -### Step 7: Execute Fixes +### Step 6: Execute Fixes Invoke task-executor using Agent tool: - `subagent_type`: "dev-workflows:task-executor" - `description`: "Execute review fixes" -- `prompt`: "Task file: docs/plans/tasks/review-fixes-YYYYMMDD.md. Apply staged fixes (stops at 5 files)." +- `prompt`: "Apply these approved code-side findings directly: [findings with IDs, governing sources, smallest correction, affected paths, and observable verification condition]. Keep the change within the approved routes and stated total size budget." -### Step 8: Quality Check +### Step 7: Quality Check Invoke quality-fixer using Agent tool: - `subagent_type`: "dev-workflows:quality-fixer" - `description`: "Quality gate check" -- Pass Step 7 `mutationEvidence` and `qualityCommand` when available (caller first, otherwise current task). +- Pass Step 6 `filesModified` and `mutationEvidence`. - `prompt`: "Confirm quality gate passage for fixed files." -### Step 9: Re-validate code-reviewer +### Step 8: Re-validate code-reviewer Invoke code-reviewer using Agent tool: - `subagent_type`: "dev-workflows:code-reviewer" - `description`: "Re-validate compliance" -- `prompt`: "Re-validate Design Doc compliance after fixes. Prior compliance issues: $STEP_2_OUTPUT. Verify each prior issue is resolved (whether resolved code-side or design-side)." +- `prompt`: "Re-validate Design Doc compliance after fixes. Design Doc: [path]. Implementation files: [file list]. prior_feedback: [{id, disposition, correction?, reason?, evidence}]. Review the current state normally, then reconcile every prior item." -### Step 10: Re-validate security-reviewer +### Step 9: Re-validate security-reviewer Invoke security-reviewer using Agent tool (only if security fixes were applied): - `subagent_type`: "dev-workflows:security-reviewer" - `description`: "Re-validate security" -- `prompt`: "Re-validate security after fixes. governingDocuments: [{\"type\":\"design-doc\",\"path\":\"[path]\"}]. implementationFiles: [file list]. Prior findings: $STEP_3_OUTPUT." - -### Step 11: Final Cleanup and Report +- `prompt`: "Re-validate security after fixes. governingDocuments: [{\"type\":\"design-doc\",\"path\":\"[path]\"}]. implementationFiles: [file list]. prior_feedback: [{id, disposition, correction?, reason?, evidence}]. Review the current state normally, then reconcile every prior item." -Delete the review-fix task file this recipe created (if any). Its work is committed; `docs/plans/` is ephemeral working state and is not retained between recipe runs: +Apply the Review Resolution Gate to every Step 8 and Step 9 result before Step 10. Route new `apply` findings through their approved design-side or code-side path and repeat the affected verification; stop for unresolved `user_decision_required`; proceed when each result is approved or every actionable finding is `decline`. -- Delete `docs/plans/tasks/review-fixes-YYYYMMDD.md` if it exists +### Step 10: Final Report -If the file cannot be deleted (filesystem error), report the failure but do not block the final report. - -Then present the final report: +Present the final report: ``` Code Compliance: @@ -191,8 +177,6 @@ Security Review: Remaining issues: - [items requiring manual intervention] - -Cleanup: review-fixes task file removed ``` ## Auto-fixable Items (code-side path) diff --git a/dev-workflows/skills/recipe-task/SKILL.md b/dev-workflows/skills/recipe-task/SKILL.md index 322e3a3..24d0e49 100644 --- a/dev-workflows/skills/recipe-task/SKILL.md +++ b/dev-workflows/skills/recipe-task/SKILL.md @@ -5,6 +5,7 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. # Task Execution with Metacognitive Analysis diff --git a/dev-workflows/skills/recipe-update-doc/SKILL.md b/dev-workflows/skills/recipe-update-doc/SKILL.md index 6bdeb54..73c3256 100644 --- a/dev-workflows/skills/recipe-update-doc/SKILL.md +++ b/dev-workflows/skills/recipe-update-doc/SKILL.md @@ -5,6 +5,7 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. **Context**: Dedicated to updating existing design documents. @@ -12,10 +13,15 @@ Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or g **Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. + +**Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression; include declined IDs with governing reasons and evidence in the final user report. +Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. + **First Action**: Register Steps 1-6 using TaskCreate before any execution. **Execution Protocol**: -1. **Delegate all work through Agent tool** โ€” invoke sub-agents, pass deliverable paths between them, and report results (permitted tools: see subagents-orchestration-guide "Orchestrator's Permitted Tools") +1. **Invoke named specialists for deliverable production** โ€” pass deliverable paths between them and validate their results (see subagents-orchestration-guide "Orchestrator Execution Boundary") 2. **Execute update flow**: - Identify target โ†’ Clarify changes โ†’ Update document โ†’ Review โ†’ Consistency check - **Stop at every `[Stop: ...]` marker** โ†’ Wait for user approval before proceeding @@ -157,7 +163,7 @@ prompt: | **On review result**: - Approved โ†’ Proceed to Step 6 -- Needs revision โ†’ Return to Step 4 with the following prompt (max 2 iterations): +- Needs revision โ†’ Apply the Review Resolution Gate. Return to Step 4 when `apply` findings exist, using the following prompt: ``` subagent_type: [Update Agent from Step 2] description: "Revise [Type from Step 2]" @@ -165,12 +171,13 @@ prompt: | Operation Mode: update Existing Document: [path from Step 1] - ## Review Feedback to Address - $STEP_5_OUTPUT + ## Adjudicated Review Findings + [apply findings with IDs, basis, smallest correction, and affected sections] - Address each issue raised in the review feedback. + Treat these findings as the complete revision scope and preserve adjacent content. ``` -- **After 2 rejections** โ†’ Flag for human review, present accumulated feedback to user and end +- On re-review pass `prior_feedback` as `[{id, disposition, correction?, reason?, evidence}]` +- All actionable findings are `decline` and every `user_decision_required` item is resolved โ†’ Proceed to Step 6 Present review result to user for approval. @@ -200,7 +207,6 @@ prompt: | |-------|--------| | Target document not found | Report and end (document creation is out of scope) | | Sub-agent update fails | Log failure, present error to user, retry once | -| Review rejects after 2 revisions | Stop loop, flag for human intervention | | design-sync detects conflicts | Present to user for resolution decision | ## Completion Criteria diff --git a/dev-workflows/skills/requirement-convergence/SKILL.md b/dev-workflows/skills/requirement-convergence/SKILL.md index bcb8092..0c3ec2f 100644 --- a/dev-workflows/skills/requirement-convergence/SKILL.md +++ b/dev-workflows/skills/requirement-convergence/SKILL.md @@ -28,7 +28,7 @@ Judgment rules per field: [references/criteria.md](references/criteria.md). ## Hearing Protocol -Eliciting requires user interaction, so the orchestrator owns it. It runs after the analysis that produced the scope facts, because the orchestrator investigates nothing itself. +Eliciting and judging the convergence fields require user interaction, so the orchestrator owns them. The hearing runs after the specialist analysis that produced the scope facts; production of that investigation output remains with the specialist. Register these steps before starting and record each step's evidence as it completes: diff --git a/dev-workflows/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows/skills/subagents-orchestration-guide/SKILL.md index 8393731..4aef64f 100644 --- a/dev-workflows/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows/skills/subagents-orchestration-guide/SKILL.md @@ -7,27 +7,28 @@ description: Guides subagent coordination through implementation workflows. Use ## Role: The Orchestrator -All investigation, analysis, and implementation work flows through specialized subagents. +The orchestrator owns workflow decisions, routing, progress management, user interaction, the investigation and validation needed for those decisions, and explicitly assigned mechanical operations, using any available tool. Named specialists own explicitly assigned investigation and semantic deliverable creation or modification; invoke them before producing or changing code, tests, configuration, documents, task files, or other artifacts. ### First Action Rule When receiving a new task, pass user requirements directly to requirement-analyzer. Determine the workflow based on its scale assessment result. -requirement-analyzer returns a `convergence` object. Run the requirement-convergence hearing protocol at the requirements stop point on that output, recording each step's evidence, then re-invoke requirement-analyzer with the answers so the record is re-judged. The hearing runs in the orchestrator because it requires user interaction, and runs after the analysis because the orchestrator investigates nothing itself. +requirement-analyzer returns a `convergence` object. Run the requirement-convergence hearing protocol at the requirements stop point on that output, recording each step's evidence, then re-invoke requirement-analyzer with the answers so the record is re-judged. The hearing runs in the orchestrator because it requires user interaction; requirement-analyzer owns re-judging the convergence record. ### Requirement Change Detection During Flow -**During flow execution**, monitor user responses for scope-expanding signals: -- Mentions of new features/behaviors (additional operation methods, display on different screens, etc.) -- Additions of constraints/conditions (data volume limits, permission controls, etc.) -- Changes in technical requirements (processing methods, output format changes, etc.) - -**When any signal is detected โ†’ Re-run requirement-analyzer with integrated requirements, identify which approved artifacts or task boundaries the change invalidates, and resume from the earliest invalidated gate. Preserve earlier outputs that remain valid.** +Treat new or changed behaviors, constraints, or technical requirements as requirement changes. Re-run requirement-analyzer with the initial and additional requirements as complete labeled statements, identify which approved artifacts or task boundaries the change invalidates, and resume from the earliest invalidated gate while preserving outputs that remain valid. ## Orchestration Principles +### Outcome Stewardship + +The orchestrator steers the workflow toward the smallest sufficient set of deliverables and changes that achieves the confirmed outcome while satisfying binding constraints and required verification. Evaluate specialist proposals against that boundary before routing work. + ### Delegation Boundary: What vs How +Before assigning repository work, inspect the current state needed to identify **what to accomplish** and **where to work**; pass unresolved questions as explicit investigation scope. + The orchestrator passes **what to accomplish** and **where to work**. Each specialist determines **how to execute** autonomously. **Pass to specialists** (what/where/constraints): @@ -40,35 +41,28 @@ The orchestrator passes **what to accomplish** and **where to work**. Each speci - Execution order and tool flags - Which files to inspect or modify within the given scope -| | Bad (orchestrator prescribes how) | Good (orchestrator passes what) | -|---|---|---| -| quality-fixer | "Run these checks: 1. lint 2. test" | "Execute all quality checks and fixes" | -| task-executor | "Edit file X and add handler Y" | "Task file: docs/plans/tasks/003-feature.md" | - -**Decision precedence when outputs conflict**: +**Decision precedence for routing**: 1. User instructions (explicit requests or constraints) 2. Task files and design artifacts (Design Doc, PRD, work plan) 3. Objective repo state (git status, file system, project configuration) 4. Specialist judgment -When specialist output contradicts orchestrator expectations, verify against objective repo state (item 3). If repo state confirms the specialist, follow the specialist. Override specialist output only when it conflicts with items 1 or 2. +Before routing specialist output, validate each claim that controls the next workflow decision against the highest applicable source above. Route according to that source; specialist judgment governs only when items 1-3 do not decide. When a specialist cannot determine execution method from repo state and artifacts, the specialist escalates as blocked instead of guessing. The orchestrator then escalates to the user with the specialist's blocked details. -### Task Assignment with Responsibility Separation +### Review Resolution + +Apply `references/review-resolution.md` to actionable deliverable-review findings. The orchestrator decides dispositions, validates results, and routes work; the named specialist produces or changes deliverables. -Assign work based on each subagent's responsibilities: +### Task Assignment with Responsibility Separation -**What to delegate to task-executor**: -- Implementation work and test addition -- Confirmation of added tests passing (existing tests are not covered) -- Delegate quality assurance exclusively to quality-fixer (or quality-fixer-frontend for frontend tasks) +| Specialist | Responsibility | +|---|---| +| task-executor | Implement scoped work and tests, and confirm added tests pass; leave whole-repository quality assurance to the quality-fixer. | +| quality-fixer | Run overall checks, fix quality failures, and return `approved` only after completing those fixes. | -**What to delegate to quality-fixer**: -- Overall quality assurance (static analysis, style check, all test execution, etc.) -- Complete execution of quality error fixes -- Self-contained processing until fix completion -- Final approved judgment (only after fixes are complete) +For frontend work, substitute task-executor-frontend and quality-fixer-frontend; in fullstack work, select them by task layer. ## Constraints Between Subagents @@ -79,6 +73,8 @@ Assign work based on each subagent's responsibilities: Autonomous execution MUST stop and wait for user input at these points. **Use AskUserQuestion to present confirmations and questions.** +Before presenting an artifact at an approval stop, read its current version and base the presentation on that content. + | Phase | Stop Point | User Action Required | |-------|------------|---------------------| | Requirements | After requirement-analyzer completes | Answer the requirement-convergence hearing, then confirm requirements | @@ -111,19 +107,9 @@ Each subagent invocation is a **fresh Agent tool** call, isolating each phase's - `description`: Concise task description (3-5 words) - `prompt`: Specific instructions including deliverable paths -### Orchestrator's Permitted Tools - -The orchestrator coordinates work using only the following tools: +### Orchestrator Execution Boundary -| Tool | Purpose | -|------|---------| -| Agent | Invoke subagents | -| AskUserQuestion | User confirmations and questions | -| TaskCreate / TaskUpdate | Progress tracking | -| Bash | Shell operations (git commit, ls, verification commands) | -| Read | Deliverable documents for information bridging between subagents | - -All implementation work (Edit, Write, MultiEdit) is performed by subagents, not the orchestrator. +Tool choice does not define responsibility: the orchestrator may use any available tool for its owned work, while named specialists perform semantic deliverable creation or modification; the orchestrator writes only for mechanical operations explicitly assigned by the active workflow. ### Prompt Construction Rule Every subagent prompt must include: @@ -134,40 +120,26 @@ Construct the prompt from the agent's Input Parameters section and the deliverab Two additional rules: - Subagents see only the Agent prompt and files they read. Include required paths, prior JSON, parameters, and scope constraints explicitly. -- Replace every `[placeholder]` in examples below with concrete values before invoking the Agent tool. - -### Call Example (requirement-analyzer) -- subagent_type: "requirement-analyzer" -- description: "Requirement analysis" -- prompt: "Requirements: [user requirements]. Context: [any relevant context]. Perform requirement analysis and scale determination." -- On re-invocation after the convergence hearing, append: "Hearing answers: [the user's answers per convergence field]. Re-judge the convergence record with these answers." - -### Call Example (codebase-analyzer) -- subagent_type: "codebase-analyzer" -- description: "Codebase analysis" -- prompt: "requirement_analysis: [JSON from requirement-analyzer]. prd_path: [path if exists]. requirements: [original user requirements]. Analyze the existing codebase and produce design guidance." +- Resolve every placeholder in workflow prompt templates before invoking the Agent tool. -### Call Example (ui-analyzer) -- subagent_type: "ui-analyzer" -- description: "UI fact gathering" -- prompt: "requirement_analysis: [JSON from requirement-analyzer]. requirements: [original user requirements]. ui_spec_path: [path if exists]. target_components: [list if focused]. Read docs/project-context/external-resources.md, fetch external UI sources via the declared access methods (MCP / URL / file), and analyze the existing UI codebase. Output the consolidated UI fact JSON." +### Agent-Specific Prompt Content -When invoked alongside codebase-analyzer for frontend or fullstack-frontend work, run both agents in parallel and pass both JSON outputs to consumers (ui-spec-designer for the design phase; technical-designer-frontend for the Design Doc phase). - -### Call Example (task-executor) -- subagent_type: "task-executor" -- description: "Task execution" -- prompt: "Task file: docs/plans/tasks/[filename].md Please complete the implementation" +| Specialist | Required prompt content | +|---|---| +| requirement-analyzer | User requirements and relevant context; on re-invocation, add the hearing answers per `convergence` field and request re-judgment. | +| codebase-analyzer | `requirement_analysis`, optional `prd_path`, and original requirements. | +| ui-analyzer | `requirement_analysis`, original requirements, optional UI Spec and target components, plus the external-resource context path and declared access methods. Run it in parallel with codebase-analyzer for frontend work; pass both outputs to ui-spec-designer for the UI Spec phase and technical-designer-frontend for the Design Doc phase. | +| task-executor | The task file path when one exists; otherwise the direct scope, governing sources, target paths, and observable verification condition. | ## Structured Response Specification Subagents respond in JSON format. Key fields for orchestrator decisions: - **requirement-analyzer**: scale, confidence, affectedLayers, adrRequired, scopeDependencies, questions, convergence (fields with readiness labels; a field below `ready` returns as a `convergence` question) -- **codebase-analyzer**: analysisScope.categoriesDetected, dataModel.detected, qualityAssurance (mechanisms[], domainConstraints[]), focusAreas[], existingElements count, limitations -- **ui-analyzer**: analysisScope.uiConventions, externalResources (designOrigin/designSystem/guidelines/visualVerification with fetch_status), componentStructure[], propsPatterns[], cssLayout[], stateDisplay[], displayConditions[], i18n, accessibility[], generatedArtifacts[], focusAreas[] (raw fact_id; consumers apply `ui:` prefix when merging with codebase analysis facts), candidateWriteSet[] (with confidence labels), limitations +- **codebase-analyzer**: pass its full JSON unchanged; HC-02 defines the fields consumed downstream +- **ui-analyzer**: pass its full JSON unchanged with raw `fact_id` values; the consumer applies the `ui:` prefix when merging with codebase facts - **code-verifier**: `summary.status` (consistent/mostly_consistent/needs_review/inconsistent/blocked), `summary.consistencyScore`, discrepancies[], reverseCoverage (including dataOperationsInCode, testBoundariesSectionPresent). Pre-implementation: verifies Design Doc claims against existing codebase. Post-implementation: verifies implementation consistency against the governing Design Doc or Work Plan (pass `code_paths` scoped to changed files) -- **task-executor**: status (escalation_needed/completed), escalation_type (design_compliance_violation/similar_function_found/investigation_target_not_found/out_of_scope_file/dependency_version_uncertain/binding_decision_violation/test_environment_not_ready), testsAdded, requiresTestReview -- **quality-fixer**: Input: `task_file` (path to current task file โ€” always pass this in orchestrated flows). Status: approved/stub_detected/blocked. `stub_detected` โ†’ route back to task-executor with `incompleteImplementations[]` details for completion, then re-run quality-fixer. `blocked` โ†’ discriminate by `reason` field: `"Cannot determine due to unclear specification"` โ†’ read `blockingIssues[]` for specification details; `"Execution prerequisites not met"` โ†’ read `missingPrerequisites[]` with `resolutionSteps` โ€” present these to the user as actionable next steps +- **task-executor**: status (escalation_needed/completed), escalation_type (design_compliance_violation/similar_function_found/investigation_target_not_found/out_of_scope_file/dependency_version_uncertain/binding_decision_violation/test_environment_not_ready), changeSummary, testsAdded, requiresTestReview +- **quality-fixer**: Input: optional `task_file`, plus the executor's `filesModified` and `mutationEvidence`; pass `qualityCommand` only when the caller or task supplies one. Status: approved/stub_detected/blocked. `stub_detected` โ†’ route back to task-executor with `incompleteImplementations[]` details for completion, then re-run quality-fixer. `blocked` โ†’ discriminate by `reason` field: `"Cannot determine due to unclear specification"` โ†’ read `blockingIssues[]` for specification details; `"Execution prerequisites not met"` โ†’ read `missingPrerequisites[]` with `resolutionSteps` โ€” present these to the user as actionable next steps - **document-reviewer**: `verdict.decision` (approved/approved_with_conditions/needs_revision/rejected) - **design-sync**: sync_status (synced/conflicts_found) - **integration-test-reviewer**: Input: `changedTestFiles[]`, `diffBase`, optional review-basis inputs, and `mutationEvidence`. Output: status (`approved`/`needs_revision`/`blocked`), `reviewBasis`, requiredFixes @@ -176,114 +148,57 @@ Subagents respond in JSON format. Key fields for orchestrator decisions: ## Handling Requirement Changes -### Handling Requirement Changes in requirement-analyzer -requirement-analyzer follows the "completely self-contained" principle and processes requirement changes as new input. - -#### How to Integrate Requirements +Use create mode for initial documents. For requirement-driven revisions, invoke the owning document specialist in `update` mode and add history: -**Important**: To maximize accuracy, integrate requirements as complete sentences, including all contextual information communicated by the user. Result format: raw concatenation of all requirements, followed by a labeled summary (`Initial requirement: โ€ฆ` / `Additional requirement: โ€ฆ`). - -### Update Mode for Document Generation Agents -Document generation agents (work-planner, technical-designer, prd-creator) can update existing documents in `update` mode. - -- **Initial creation**: Create new document in create (default) mode -- **On requirement change**: Edit existing document and add history in update mode - -Criteria for timing when to call each agent: -- **work-planner**: Request updates only before execution -- **technical-designer**: Request updates according to design changes โ†’ Execute document-reviewer for consistency check -- **prd-creator**: Request updates according to requirement changes โ†’ Execute document-reviewer for consistency check -- **document-reviewer**: Always execute before user approval after PRD/ADR/Design Doc creation/update, and after Work Plan creation/update at Medium/Large scale (Small uses a simplified plan with no semantic review โ€” no Design Doc to trace against) +- **work-planner**: update only before execution +- **technical-designer / prd-creator**: update affected documents, then invoke document-reviewer +- **document-reviewer**: run before user approval after PRD/ADR/Design Doc changes and after Medium/Large Work Plan changes; Small plans require no semantic review ## Basic Flow: Planning and Implementation -Always start with requirement-analyzer, hold the requirement-convergence hearing on its output, then select the minimum planning flow required by scale and affected layers. - ### Planning flow (per scale) | Scale | Planning flow (ends at task-decomposer for Medium/Large; ends at work-planner for Small) | |-------|---------------| -| Large | requirement-analyzer โ†’ PRD โ†’ PRD review โ†’ external resource hearing โ†’ optional ADR โ†’ codebase-analyzer (+ ui-analyzer in parallel for frontend/fullstack) โ†’ optional UI Spec โ†’ Design Doc โ†’ code-verifier โ†’ document-reviewer โ†’ design-sync โ†’ acceptance-test-generator โ†’ work-planner โ†’ work plan review (document-reviewer, doc_type WorkPlan) โ†’ task-decomposer | +| Large | requirement-analyzer โ†’ PRD โ†’ PRD review โ†’ external resource hearing โ†’ codebase-analyzer (+ ui-analyzer in parallel for frontend/fullstack) โ†’ optional UI Spec โ†’ optional ADR โ†’ Design Doc โ†’ code-verifier โ†’ document-reviewer โ†’ design-sync โ†’ acceptance-test-generator โ†’ work-planner โ†’ work plan review (document-reviewer, doc_type WorkPlan) โ†’ task-decomposer | | Medium | requirement-analyzer โ†’ external resource hearing โ†’ codebase-analyzer (+ ui-analyzer in parallel for frontend/fullstack) โ†’ optional UI Spec โ†’ optional ADR โ†’ Design Doc โ†’ code-verifier โ†’ document-reviewer โ†’ design-sync โ†’ acceptance-test-generator โ†’ work-planner โ†’ work plan review (document-reviewer, doc_type WorkPlan) โ†’ task-decomposer | | Small | requirement-analyzer โ†’ work-planner | -The requirement-convergence hearing follows requirement-analyzer in every flow. Both it and the external resource hearing run in the orchestrator (they require AskUserQuestion). ui-analyzer joins codebase-analyzer in parallel only when the work has a frontend surface; for backend-only work the planning flow uses codebase-analyzer alone. +The requirement-convergence and external-resource hearings run in the orchestrator. Run ui-analyzer and codebase-analyzer in parallel only for frontend surfaces. -After the planning flow completes and the user grants batch approval, implementation proceeds. Verifying the plan is implementable end-to-end (verification lanes, fixtures, E2E environment) is an optional preflight the user runs at their discretion via the recipe-prepare-implementation recipe; this guide does not invoke any orchestrator above the agent layer. - -Then execute the task execution cycle: `task-executor โ†’ quality-fixer โ†’ commit` for each task. See "Autonomous Execution Mode" below for full per-task details. At Small scale this cycle still applies โ€” implementation runs through `task-executor`, not orchestrator-direct edits. - -Each agent name in the chain is invoked via the Agent tool (per "Orchestrator's Permitted Tools" above). +After batch approval, enter the autonomous cycle below. Small-scale implementation also runs through task-executor. Rules: -- Large scale requires PRD before Design Doc creation -- Frontend/fullstack flows add UI Spec before Design Doc creation +- Frontend/fullstack flows that produce a Design Doc complete the UI Spec first; ADR-only flows skip the UI Spec - Fullstack layer sequencing is defined only in `references/monorepo-flow.md` - `design-sync` is required whenever multiple Design Docs exist - `task-decomposer` begins only after work plan review (document-reviewer, doc_type WorkPlan; Medium/Large) and batch approval -- Work plan review self-heals: on `verdict.decision` `needs_revision`, route back to work-planner (update) and re-review until `approved`/`approved_with_conditions`; `rejected` escalates to the user. If re-review returns the same blocking finding and the update adds no new evidence or contract change, stop the loop and escalate that finding. The work plan is a derivation of the Design Doc, so plan-fidelity findings need no user adjudication while the loop is making observable progress +- Work plan review applies Review Resolution: revise and re-review with `prior_feedback` for `apply`; proceed when all actionable findings are `decline`; escalate unresolved `user_decision_required` or unusable inputs ## Autonomous Execution Mode -### Pre-Execution Environment Check - -**Principle**: Verify subagents can complete their responsibilities - -**Required environments**: -- Commit capability (for per-task commit cycle) -- Quality check tools (quality-fixer will detect and escalate if missing) -- Test runner (task-executor will detect and escalate if missing) - -**If critical environment unavailable**: Escalate with specific missing component before entering autonomous mode -**If detectable by subagent**: Proceed (subagent will escalate with detailed context) +### Pre-Execution Gate -### Authority Delegation +Verify commit capability before autonomous mode. Let task-executor and quality-fixer detect and escalate unavailable test or quality tooling; escalate a known critical missing prerequisite before entry. -**After environment check passes**: -- Batch approval for entire implementation phase delegates authority to subagents -- task-executor: Implementation authority (can use Edit/Write) -- quality-fixer: Fix authority (automatic quality error fixes) +Batch approval authorizes task-executor implementation and quality-fixer corrections until completion or escalation. -### Definition of Autonomous Execution Mode +### Autonomous Execution Summary After "batch approval for entire implementation phase" with work-planner, autonomously execute the following processes without human approval: ```mermaid graph TD - START[Batch approval for entire implementation phase] --> AUTO[Start autonomous execution mode] - AUTO --> TD[task-decomposer: Task materialization] - TD --> LOOP[Task execution loop] - LOOP --> TE[task-executor: Implementation] - TE --> ESCJUDGE{Escalation judgment} - ESCJUDGE -->|escalation_needed/blocked| USERESC[Escalate to user] - ESCJUDGE -->|requiresTestReview: true| ITR[integration-test-reviewer] - ESCJUDGE -->|No issues| QF - ITR -->|needs_revision| TE - ITR -->|approved| QF - ITR -->|blocked| USERESC - QF[quality-fixer: Quality check and fixes] --> QFJUDGE{quality-fixer result} - QFJUDGE -->|stub_detected| TE - QFJUDGE -->|approved| COMMIT[Orchestrator: Execute git commit] - QFJUDGE -->|blocked| USERESC - COMMIT --> CHECK{Any remaining tasks?} - CHECK -->|Yes| LOOP - CHECK -->|No| VERIFY[Post-implementation verification] - VERIFY --> CV[code-verifier: Governing document consistency check] - VERIFY --> SEC[security-reviewer: Security review] - CV --> VRESULT{Verification results} - SEC --> VRESULT - VRESULT -->|All passed| REPORT[Completion report] - VRESULT -->|Any failed| VFIX[task-executor: Verification fixes] - VFIX --> QF2[quality-fixer: Quality check] - QF2 --> REVERIFY[Re-run both verifiers] - REVERIFY --> VRESULT - VRESULT -->|blocked| USERESC - - LOOP --> INTERRUPT{User input?} - INTERRUPT -->|None| TE - INTERRUPT -->|Yes| REQCHECK{Requirement change check} - REQCHECK -->|No change| TE - REQCHECK -->|Change| STOP[Stop autonomous execution] - STOP --> RA[Re-analyze with requirement-analyzer] + START[Batch approval] --> TD[task-decomposer] + TD --> CYCLE[Per-task 4-step cycle, including commit] + CYCLE -->|remaining tasks| CYCLE + CYCLE -->|all tasks complete| VERIFY[code-verifier + security-reviewer] + CYCLE -->|blocked, escalation, or requirement change| USER[Escalate or re-analyze] + VERIFY -->|passed| REPORT[Completion report] + VERIFY -->|actionable findings| RR[Review Resolution] + RR -->|apply| FIX[task-executor + quality-fixer] + FIX --> VERIFY + RR -->|all decline| REPORT + RR -->|user decision required| USER ``` ### Post-Implementation Verification Pass/Fail Criteria @@ -293,118 +208,83 @@ graph TD | code-verifier | `summary.status` is `consistent` or `mostly_consistent` | `summary.status` is `needs_review` or `inconsistent` | `summary.status` is `blocked` โ†’ Escalate to user | | security-reviewer | `status` is `approved` or `approved_with_notes` | `status` is `needs_revision` | `status` is `blocked` โ†’ Escalate to user | -**Fix-cycle handoff**: Consolidate failed verifier findings into one ephemeral task per required executor and pass each exact path as `task_file` through its executor and quality-fixer. Use `review-fixes-{plan-name}-task-*` for single-layer work and `review-fixes-{plan-name}-{backend|frontend}-task-*` for fullstack routing; delete the files after all verifiers pass. +**Fix-cycle handoff**: Apply Review Resolution, then pass each required executor the `apply` findings, affected paths, governing evidence, and verification condition directly. Carry `prior_feedback` to reviewer inputs that support reconciliation. **Re-run rule**: After any post-implementation verification fix cycle, re-run both code-verifier and security-reviewer before accepting the result. ### Conditions for Stopping Autonomous Execution -Stop autonomous execution and escalate to user in the following cases: -1. **Escalation from subagent** - - When receiving response with `status: "escalation_needed"` - - When receiving response with `status: "blocked"` - -2. **When requirement change detected** - - Any match in requirement change detection checklist - - Stop autonomous execution and re-analyze with integrated requirements in requirement-analyzer - - Mark affected PRD/UI Spec/ADR/Design Doc/Work Plan/task outputs invalid and resume from the earliest invalidated approval gate; preserve outputs outside the changed requirement's impact - -3. **When work-planner update restriction is violated** - - Requirement changes after task-decomposer starts require requirement re-analysis and task invalidation - - Restart document design only when the re-analysis shows that an approved requirement, contract, data flow, verification strategy, or task boundary changed - -4. **When user explicitly stops** - - Direct stop instruction or interruption +| Trigger | Action | +|---|---| +| A subagent returns `escalation_needed` or `blocked` | Escalate its concrete details to the user. | +| Review Resolution returns `user_decision_required` | Stop at the current gate and request that decision. | +| A requirement changes | Apply Requirement Change Detection above. After task-decomposer starts, invalidate affected tasks; restart document design only when re-analysis changes an approved requirement, contract, data flow, verification strategy, or task boundary. | +| The user stops or interrupts | Stop autonomous execution. | ### Task Management: 4-Step Cycle **Per-task cycle**: -1. **Execute**: invoke Agent tool (subagent_type: "task-executor") โ†’ Record the current HEAD as `diffBase`, pass the task file path in the prompt, and receive the structured response +1. **Execute**: record the current HEAD as `diffBase`, then invoke task-executor with the task file path when one exists or with the direct scope contract above 2. **Branch on executor result**: - `status: escalation_needed` or `blocked` โ†’ Escalate to user - - `requiresTestReview` is `true` โ†’ Invoke integration-test-reviewer with `diffBase`, changed integration/E2E paths, `taskFile`, prompt-only claims, and `mutationEvidence` - - `needs_revision` โ†’ Return to step 1 with `requiredFixes` + - `requiresTestReview` is `true` โ†’ Invoke integration-test-reviewer with `diffBase`, changed integration/E2E paths, optional `taskFile`, prompt-only claims, and `mutationEvidence` - `approved` โ†’ Proceed to step 3 - `blocked` โ†’ Escalate to user + - `needs_revision` โ†’ Apply Review Resolution + - one or more `apply` findings โ†’ Return to step 1 with those findings, then re-review with `prior_feedback` + - every actionable finding is `decline` โ†’ Proceed to step 3 + - any unresolved `user_decision_required` finding โ†’ Escalate to user - Otherwise โ†’ Proceed to step 3 -3. **Quality-fix**: invoke quality-fixer with `task_file`, upstream `mutationEvidence`, and `qualityCommand` when available (caller first, otherwise current task) +3. **Quality-fix**: invoke quality-fixer with upstream `filesModified` and `mutationEvidence`, plus `task_file` when available and `qualityCommand` from the caller first or task otherwise - `stub_detected` โ†’ Return to step 1 with `incompleteImplementations[]` details - `blocked` โ†’ Escalate to user - `approved` โ†’ Proceed to step 4 -4. **Commit**: execute git commit with Bash after quality-fixer returns `approved` - -### Progress Tracking - -Register overall phases using TaskCreate. Update each phase with TaskUpdate as it completes. - -## Main Orchestrator Roles - -1. **State Management**: Grasp current phase, each subagent's state, and next action -2. **Information Bridging**: Data conversion and transmission between subagents - - Convert each subagent's output to next subagent's input format - - **Always pass deliverables from previous process to next agent** - - Extract necessary information from structured responses - - Compose commit messages from changeSummary - - Explicitly integrate initial and additional requirements when requirements change - - ### Handoff Contracts - - #### HC-01: requirement-analyzer โ†’ codebase-analyzer - - Pass: `requirement_analysis` (including `convergence`), `prd_path` (if exists), original user requirements - - #### HC-01b: convergence record โ†’ document owner - - Pass `convergence` from the last requirement-analyzer invocation (or, in flows without one, the orchestrator's own judged record) to whichever agent owns the persisting document - - **prd-creator** (when a PRD is created or updated): persists `outcome` to `Success Criteria`, and `nonGoals` plus `speculative` requirements to `Future / Out of Scope` with origin `user` - - **technical-designer / technical-designer-frontend**: persists the same to the Design Doc's `Requirement Convergence` when no PRD exists, and always records the fields left `weak-but-explicit` there - - Pass the record unchanged; a field's readiness label travels with it - - #### HC-02: codebase-analyzer โ†’ technical-designer - - Pass: full codebase-analyzer JSON as additional context - - Required downstream uses: - - `focusAreas` โ†’ canonical disposition-target list for the Fact Disposition Table - - `dataModel`, `dataTransformationPipelines`, `qualityAssurance` โ†’ Existing Codebase Analysis / Verification Strategy / Quality Assurance sections - - #### HC-03: technical-designer โ†’ code-verifier - - Pass: Design Doc path (`doc_type: design-doc`) - - Do not pass `code_paths`; code-verifier discovers scope from the document - - #### HC-04: code-verifier + codebase-analyzer โ†’ document-reviewer - - Pass: `review_context: creation`, `code_verification` JSON, the same `codebase_analysis` JSON previously given to the designer, original user requirements as `requirements_verbatim`, and confirmed scope and user decisions as `confirmed_decisions` - - Purpose: reviewer validates discrepancy integration, Fact Disposition coverage against `focusAreas`, and Design Convergence against the effective requirements +4. **Commit**: after quality-fixer returns `approved`, compose the message from `changeSummary` and execute git commit with Bash - #### HC-05: code-verifier โ†’ next-layer technical-designer (fullstack only) - - Defined only for multi-layer fullstack flow in `references/monorepo-flow.md` - - Pass: prior-layer Design Doc path plus `prior_layer_verification` - - Use only `discrepancies[]` as known issues to address or escalate. Do not infer verified claims that are not explicitly present in the verifier output. +Register overall phases using TaskCreate and update each phase with TaskUpdate as it completes. - #### technical-designer โ†’ work-planner +## Handoff Contracts - **Pass to work-planner**: Design Doc path. Work-planner reads the DD template from documentation-criteria skill, scans all DD sections, and extracts technical requirements in these categories: - - **Verification Strategy**: Extracted to work plan header (Correctness Proof Method + Early Verification Point) - - **Implementation targets**: Components, functions, or data structures to create or modify - - **Connection/switching/registration**: Integration points, dependency wiring, switching methods - - **Contract changes and propagation**: Interface changes, data contracts, field propagation across boundaries - - **Verification requirements**: Verification methods, test boundaries, integration verification points - - **Prerequisite work**: Migration steps, security measures, environment setup +### HC-01: requirement-analyzer โ†’ codebase-analyzer +- Pass: `requirement_analysis` (including `convergence`), `prd_path` (if exists), original user requirements - Work-planner produces a Design-to-Plan Traceability table mapping each extracted item to covering task(s). Items without a covering task must be marked as `gap` with justification. Unjustified gaps are errors. Justified gaps require user confirmation before plan approval. +### HC-01b: convergence record โ†’ document owner +- Pass `convergence` from the last requirement-analyzer invocation (or, in flows without one, the orchestrator's own judged record) to whichever agent owns the persisting document +- **prd-creator** (when a PRD is created or updated): persists `outcome` to `Success Criteria`, and `nonGoals` plus `speculative` requirements to `Future / Out of Scope` with origin `user` +- **technical-designer / technical-designer-frontend**: persists the same to the Design Doc's `Requirement Convergence` when no PRD exists, and always records the fields left `weak-but-explicit` there +- Pass the record unchanged; a field's readiness label travels with it - #### HC-06: acceptance-test-generator โ†’ work-planner +### HC-02: codebase-analyzer โ†’ technical-designer +- Pass: full codebase-analyzer JSON as additional context +- Required downstream uses: + - `focusAreas` โ†’ canonical disposition-target list for the Fact Disposition Table + - `dataModel`, `dataTransformationPipelines`, `qualityAssurance` โ†’ Existing Codebase Analysis / Verification Strategy / Quality Assurance sections - **Pass to acceptance-test-generator**: Design Doc path; UI Spec path (if exists). +### HC-03: technical-designer โ†’ code-verifier +- Pass: Design Doc path (`doc_type: design-doc`) +- Leave `code_paths` unspecified so code-verifier discovers scope from the document - **Orchestrator verification**: Every non-null `generatedFiles.` path exists on disk. For each null lane, `e2eAbsenceReason.` is present (intentional absence, not an error). +### HC-04: code-verifier + codebase-analyzer โ†’ document-reviewer +- Pass: `review_context: creation`, `code_verification` JSON, the same `codebase_analysis` JSON previously given to the designer, original user requirements as `requirements_verbatim`, and confirmed scope and user decisions as `confirmed_decisions` +- Purpose: reviewer validates discrepancy integration, Fact Disposition coverage against `focusAreas`, and Design Convergence against the effective requirements - **Pass to work-planner**: integration / fixture-e2e / service-integration-e2e file paths (or null per lane), per-lane absence reasons, plus timing guidance โ€” integration tests are created alongside each phase implementation, fixture-e2e tests are created alongside the UI feature phase, service-integration-e2e tests are executed only in the final phase. +### HC-05: code-verifier โ†’ next-layer technical-designer (fullstack only) +- Defined only for multi-layer fullstack flow in `references/monorepo-flow.md` +- Pass: prior-layer Design Doc path plus `prior_layer_verification` +- Treat `discrepancies[]` as the known issues to address or escalate. Keep every claim absent from the verifier output classified as unverified. - **On error**: Escalate to user when status != completed and integration file generation failed unexpectedly. A null E2E lane with a valid absence reason is not an error. +### technical-designer โ†’ work-planner -3. **ADR Status Management**: Update ADR status after user decision (Accepted/Rejected) +Pass the Design Doc path. Work-planner owns the documentation-criteria template scan and Design-to-Plan Traceability; unjustified coverage gaps are errors, and justified gaps require user confirmation before plan approval. -## Important Constraints +### HC-06: acceptance-test-generator โ†’ work-planner -Recap (defined above): quality-fixer approval before commit; inter-agent communication is JSON; document-reviewer + user approval before proceeding; check next step against work planning flow after approval; resolve conflicts via Decision precedence. +- Pass the Design Doc and optional UI Spec paths to acceptance-test-generator. +- Verify each non-null `generatedFiles.` path exists and each null lane has `e2eAbsenceReason.`. +- Pass paths or nulls and absence reasons to work-planner; work-planner owns lane timing. +- Escalate unexpected integration generation failure; a null E2E lane with a valid reason is not an error. ## References - `references/monorepo-flow.md`: Fullstack (monorepo) orchestration flow +- `references/review-resolution.md`: Finding adjudication and correction-loop contract diff --git a/dev-workflows/skills/subagents-orchestration-guide/references/monorepo-flow.md b/dev-workflows/skills/subagents-orchestration-guide/references/monorepo-flow.md index ed1889d..2c8394f 100644 --- a/dev-workflows/skills/subagents-orchestration-guide/references/monorepo-flow.md +++ b/dev-workflows/skills/subagents-orchestration-guide/references/monorepo-flow.md @@ -30,7 +30,7 @@ This reference defines the orchestration flow for projects spanning multiple lay | 14 | design-sync | Cross-layer consistency verification (source: frontend Design Doc) **[Stop]** | Sync status | | 15 | acceptance-test-generator | Integration + fixture-e2e + service-integration-e2e test skeletons from cross-layer contracts (per-lane) | Test skeletons | | 16 | work-planner | Work plan from all Design Docs | Work plan | -| 17 | document-reviewer | Work Plan review (`doc_type: WorkPlan`); return `needs_revision` to work-planner update and re-review **[Stop: Batch approval after approval]** | Approved Work Plan review | +| 17 | document-reviewer | Work Plan review (`doc_type: WorkPlan`); apply Review Resolution, return the `apply` findings to work-planner, and re-review with `prior_feedback` **[Stop: Batch approval after resolution]** | Resolved Work Plan review | ### Medium Scale Fullstack (3-5 Files) - 15 Steps @@ -50,7 +50,7 @@ This reference defines the orchestration flow for projects spanning multiple lay | 12 | design-sync | Cross-layer consistency verification (source: frontend Design Doc) **[Stop]** | Sync status | | 13 | acceptance-test-generator | Integration + fixture-e2e + service-integration-e2e test skeletons from cross-layer contracts (per-lane) | Test skeletons | | 14 | work-planner | Work plan from all Design Docs | Work plan | -| 15 | document-reviewer | Work Plan review (`doc_type: WorkPlan`); return `needs_revision` to work-planner update and re-review **[Stop: Batch approval after approval]** | Approved Work Plan review | +| 15 | document-reviewer | Work Plan review (`doc_type: WorkPlan`); apply Review Resolution, return the `apply` findings to work-planner, and re-review with `prior_feedback` **[Stop: Batch approval after resolution]** | Resolved Work Plan review | ### Parallelization in Multi-Agent Steps @@ -117,7 +117,7 @@ verification per phase. work-planner's existing Integration Complete criteria naturally covers cross-layer verification when given multiple Design Docs. -For Medium and Large flows, pass the resulting Work Plan to document-reviewer with `doc_type: WorkPlan`. On `needs_revision`, route the findings to work-planner in update mode and re-review. If the same blocking finding repeats and the update supplies no new evidence or contract change, stop and escalate instead of repeating the loop. Request batch approval only after the review is `approved` or `approved_with_conditions`; escalate `rejected` to the user. +For Medium and Large flows, pass the resulting Work Plan to document-reviewer with `doc_type: WorkPlan`. Apply Review Resolution to every actionable finding, route `apply` findings to work-planner in update mode, and re-review with `prior_feedback`. A result whose actionable findings are all `decline` is eligible for batch approval; escalate unresolved `user_decision_required` or unusable inputs. ## Task Materialization Phase @@ -143,5 +143,6 @@ Each task follows the standard 4-step cycle from `../SKILL.md`. Only agent routi When `requiresTestReview` is `true`: - Standard flow (integration-test-reviewer after task-executor, before quality-fixer) +- Apply Review Resolution before returning corrections: pass `apply` findings to the layer executor, re-review with `prior_feedback`, and continue after every `user_decision_required` item has a recorded user decision All other orchestration rules follow the standard subagents-orchestration-guide. diff --git a/dev-workflows/skills/subagents-orchestration-guide/references/review-resolution.md b/dev-workflows/skills/subagents-orchestration-guide/references/review-resolution.md new file mode 100644 index 0000000..78cc150 --- /dev/null +++ b/dev-workflows/skills/subagents-orchestration-guide/references/review-resolution.md @@ -0,0 +1,53 @@ +# Review Resolution + +Use this protocol when a deliverable reviewer or verifier returns findings that can route correction, progression, or escalation. Verification output used as evidence by a downstream specialist remains part of that specialist handoff. + +The orchestrator treats the review result as evidence and makes the workflow decision from the governing sources. + +## 1. Assess Every Finding + +Before assigning a disposition, inspect the relevant parts of the current deliverable, cited repository evidence, and governing sources, treating reviewer assertions as evidence to verify. + +The orchestrator records one disposition for every actionable finding: + +| Disposition | Use when | +|---|---| +| `apply` | Leaving the current deliverable unchanged would prevent the confirmed outcome, violate a binding requirement, design decision, or repository rule, or leave required correctness or verification unsupported. | +| `decline` | Leaving the current deliverable unchanged still achieves the confirmed outcome and satisfies binding constraints and required correctness and verification; the finding instead proposes added scope, a reversed exclusion, optional hardening or generic cleanup, duplicate proof, or other work outside that boundary. | +| `user_decision_required` | Resolving the finding would change a confirmed product outcome, exclusion, major approved design decision, or requires authority held only by the user. | + +A confirmed security risk or governing-source contradiction receives `apply` or `user_decision_required`; cost alone leaves that classification unchanged. + +For each finding record: + +- stable finding ID; +- disposition; +- governing basis and concrete evidence; +- expected effect on the approved outcome or verification; +- smallest correction when `apply`, or the reason when `decline`. + +## 2. Revise and Reconsider + +Pass `apply` findings to the author or executor. On reviewer re-review, provide `prior_feedback` as an array of `{ id, disposition, correction?, reason?, evidence }`. Re-run factual verifiers against the current artifact and adjudicate their current evidence. + +The reviewer reviews the current artifact normally, then reconciles prior feedback: + +- mark an applied correction `resolved` when the reviewed condition is satisfied; +- mark a declined finding `withdrawn` when current evidence and governing sources no longer support it; +- mark a finding `maintained` when current evidence still supports it, citing that evidence; +- report optional improvements through the reviewer's existing recommendation or note fields. + +An independent factual verifier may repeat an observed discrepancy. The orchestrator assigns its disposition from governing evidence; a maintained finding cites current or new evidence. + +## 3. Converge or Escalate + +Escalate when the disposition is `user_decision_required`, user-held authority is needed, an irreversible action awaits authorization, or required inputs are genuinely unusable. Progress after no `apply` findings remain, every other actionable finding has a disposition, and every `user_decision_required` item has a recorded user decision. + +Handoffs contain this exact set: + +- affected paths; +- `apply` findings with basis and smallest correction; +- declined IDs with reasons and evidence in `prior_feedback` when the next consumer accepts reviewer reconciliation; +- the observable condition the next review must verify. + +The final user report lists every declined actionable finding with its ID, governing reason, and evidence. diff --git a/dev-workflows/skills/task-analyzer/references/skills-index.yaml b/dev-workflows/skills/task-analyzer/references/skills-index.yaml index d99869d..2004c2c 100644 --- a/dev-workflows/skills/task-analyzer/references/skills-index.yaml +++ b/dev-workflows/skills/task-analyzer/references/skills-index.yaml @@ -141,8 +141,7 @@ skills: - "Handling Requirement Changes" - "Basic Flow: Planning and Implementation" - "Autonomous Execution Mode" - - "Main Orchestrator Roles" - - "Important Constraints" + - "Handoff Contracts" - "References" # Frontend-Specific Skills diff --git a/package.json b/package.json index bf49834..88ceade 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "claude-code-workflows", - "version": "0.23.0", + "version": "0.23.1", "private": true, "type": "module", "engines": { diff --git a/skills/recipe-add-integration-tests/SKILL.md b/skills/recipe-add-integration-tests/SKILL.md index 40be943..ad5bfa3 100644 --- a/skills/recipe-add-integration-tests/SKILL.md +++ b/skills/recipe-add-integration-tests/SKILL.md @@ -5,6 +5,7 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. **Context**: Test addition workflow for existing implementations (backend, frontend, or fullstack) @@ -12,13 +13,17 @@ Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or g **Core Identity**: "I am an orchestrator." -**First Action**: Register Steps 0-8 using TaskCreate before any execution. +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. -**Why Delegate**: 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. +**Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression; include declined IDs with governing reasons and evidence in the final user report. +Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. + +**First Action**: Register Steps 1-7 using TaskCreate before any execution. + +**Why Delegate**: Orchestrator's context is shared across all steps. Direct implementation consumes context needed for review and quality check phases. Subagents work in isolated context. **Execution Method**: - Skeleton generation โ†’ delegate to acceptance-test-generator -- Task file creation โ†’ orchestrator creates directly (minimal context usage) - Test implementation โ†’ delegate to task-executor - Test review โ†’ delegate to integration-test-reviewer - Quality checks โ†’ delegate to quality-fixer @@ -32,10 +37,6 @@ Document paths: $ARGUMENTS ## Execution Flow -### Step 0: Execute Skill - -Execute Skill: documentation-criteria (for task file template in Step 3) - ### Step 1: Discover and Validate Documents ```bash @@ -71,107 +72,67 @@ Invoke acceptance-test-generator using Agent tool: **Expected output**: `generatedFiles` containing integration and e2e paths -### Step 3: Create Task Files [GATE] - -Create one task file per layer, using the monorepo-flow.md naming convention for deterministic agent routing: -- Backend skeletons exist โ†’ `docs/plans/tasks/integration-tests-backend-task-YYYYMMDD.md` -- Frontend skeletons exist โ†’ `docs/plans/tasks/integration-tests-frontend-task-YYYYMMDD.md` -- Single-layer (no backend/frontend distinction) โ†’ `docs/plans/tasks/integration-tests-backend-task-YYYYMMDD.md` - -**Template** (per task file): -```markdown ---- -name: Implement [layer] integration tests for [feature name] -type: test-implementation ---- - -## Objective - -Implement test cases defined in skeleton files. - -## Target Files - -- Skeleton: [layer-specific paths from Step 2 generatedFiles] -- Design Doc: [layer-specific Design Doc from Step 1] +### Step 3: Test Implementation -## Tasks - -- [ ] Implement each test case in skeleton -- [ ] Verify all tests pass -- [ ] Ensure coverage meets requirements - -## Acceptance Criteria - -- All skeleton test cases implemented -- All tests passing -- quality-fixer reports approved -``` - -**Output**: "Task file(s) created at [path(s)]. Ready for Step 4." - -### Step 4: Test Implementation - -For each task file from Step 3, record the current HEAD as `diffBase`, then invoke task-executor routed by filename pattern (per monorepo-flow.md): -- `*-backend-task-*` โ†’ `subagent_type`: "dev-workflows:task-executor" -- `*-frontend-task-*` โ†’ `subagent_type`: "dev-workflows-frontend:task-executor-frontend" +For each layer with generated skeletons, record the current HEAD as `diffBase`, then invoke the layer's task-executor: +- Backend or single-layer โ†’ `subagent_type`: "dev-workflows:task-executor" +- Frontend โ†’ `subagent_type`: "dev-workflows-frontend:task-executor-frontend" - `description`: "Implement integration tests" -- `prompt`: "Task file: [task file path from Step 3]. Implement tests following the task file." +- `prompt`: "Implement every test defined by these generated skeletons: [layer-specific Step 2 paths]. Governing documents: [layer-specific Design Doc and UI Spec when present]. Keep changes within the generated tests and the setup or fixture files they require. Verify the implemented tests against the skeleton claims." + +Execute one layer at a time through Steps 3โ†’4โ†’5โ†’6โ†’7 before starting the next. -Execute one task file at a time through Steps 4โ†’5โ†’6โ†’7 before starting the next. +**Expected output**: `status`, `filesModified`, `testsAdded`, `mutationEvidence` -**Expected output**: `status`, `testsAdded` +Apply this response gate after every task-executor invocation in Steps 3 and 5: +- `status: completed`, `filesModified` and `testsAdded` are present, and at least one changed integration/E2E path can be identified from the cumulative response paths against `diffBase` โ†’ Proceed to Step 4 +- `status: escalation_needed` โ†’ Escalate to the user +- Any other status, or a response missing the required fields above โ†’ Stop and report the invalid or missing fields -### Step 5: Test Review +### Step 4: Test Review Invoke integration-test-reviewer using Agent tool: - `subagent_type`: "dev-workflows:integration-test-reviewer" - `description`: "Review test quality" -- `prompt`: "Review test quality. changedTestFiles: [integration/E2E paths in Step 4 filesModified or testsAdded that differ from diffBase]. diffBase: [revision recorded before Step 4]. skeletonFiles: [layer-specific paths from Step 2 generatedFiles matching current task's layer]. taskFile: [current task file]. mutationEvidence: [Step 4 mutationEvidence]." +- `prompt`: "Review test quality. changedTestFiles: [integration/E2E paths in Step 3 filesModified or testsAdded that differ from diffBase]. diffBase: [revision recorded before Step 3]. skeletonFiles: [layer-specific paths from Step 2 generatedFiles]. mutationEvidence: [Step 3 mutationEvidence]." -**Expected output**: `status` (approved/needs_revision/blocked), `testFiles`, `reviewBasis`, `requiredFixes` +**Expected output**: `status` (approved/needs_revision/blocked), `testFiles`, `reviewBasis`, `qualityIssues`, `requiredFixes` -### Step 6: Apply Review Fixes +### Step 5: Apply Review Fixes -Check Step 5 result: -- `status: approved` โ†’ Mark complete, proceed to Step 7 -- `status: needs_revision` โ†’ Invoke task-executor with requiredFixes, then return to Step 5 +Check Step 4 result: +- `status: approved` โ†’ Mark complete, proceed to Step 6 - `status: blocked` โ†’ Escalate to user +- `status: needs_revision` โ†’ Apply the Review Resolution Gate + - one or more `apply` findings โ†’ Invoke task-executor with those findings, apply the executor response gate above, then return to Step 4 with `prior_feedback` + - every actionable finding is `decline` โ†’ Mark review complete and proceed to Step 6 + - any unresolved `user_decision_required` finding โ†’ Escalate to user -Invoke task-executor routed by task filename pattern: -- `*-backend-task-*` โ†’ `subagent_type`: "dev-workflows:task-executor" -- `*-frontend-task-*` โ†’ `subagent_type`: "dev-workflows-frontend:task-executor-frontend" +Invoke the same layer's task-executor: - `description`: "Fix review findings" -- `prompt`: "Fix the following issues in test files: [requiredFixes from Step 5]" +- `prompt`: "Fix these adjudicated test-review findings directly: [apply findings with IDs, governing basis, smallest correction, affected paths, and observable verification condition]." -### Step 7: Quality Check +### Step 6: Quality Check -Invoke quality-fixer routed by task filename pattern: -- `*-backend-task-*` โ†’ `subagent_type`: "dev-workflows:quality-fixer" -- `*-frontend-task-*` โ†’ `subagent_type`: "dev-workflows-frontend:quality-fixer-frontend" +Invoke quality-fixer for the current layer: +- Backend or single-layer โ†’ `subagent_type`: "dev-workflows:quality-fixer" +- Frontend โ†’ `subagent_type`: "dev-workflows-frontend:quality-fixer-frontend" - `description`: "Final quality assurance" -- Pass Step 4 `mutationEvidence` and `qualityCommand` when available (caller first, otherwise current task). +- Pass the latest executor's `filesModified` and `mutationEvidence`. - `prompt`: "Final quality assurance for test files added in this workflow. Run all tests and verify coverage." **Expected output**: `status` (approved/stub_detected/blocked) Check quality-fixer response: -- `stub_detected` โ†’ Return to Step 4 with `incompleteImplementations[]` details, then re-execute Steps 4โ†’5โ†’6โ†’7 +- `stub_detected` โ†’ Return to Step 3 with `incompleteImplementations[]` details, then re-execute Steps 3โ†’4โ†’5โ†’6 - `blocked` โ†’ Escalate to user -- `approved` โ†’ Proceed to Step 8 +- `approved` โ†’ Proceed to Step 7 -### Step 8: Commit +### Step 7: Commit On `approved` from quality-fixer: - Commit test files using Bash with message format: "test: add [layer] integration tests for [feature name]" -### Step 9: Final Cleanup - -After all task files have been processed and committed, delete the task files this recipe created. Their work is committed; `docs/plans/` is ephemeral working state and is not retained between recipe runs: - -- Delete every file matching `docs/plans/tasks/integration-tests-backend-task-*.md` and `docs/plans/tasks/integration-tests-frontend-task-*.md` created during this run - -If task files cannot be deleted (filesystem error), report the failure but do not block completion. - ## Scope Boundary for Subagents Append the following block to every subagent prompt invoked from this recipe: diff --git a/skills/recipe-build/SKILL.md b/skills/recipe-build/SKILL.md index d52365a..8c5ea38 100644 --- a/skills/recipe-build/SKILL.md +++ b/skills/recipe-build/SKILL.md @@ -5,13 +5,19 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. ## Orchestrator Definition **Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. + +**Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression; include declined IDs with governing reasons and evidence in the final user report. +Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. + **Execution Protocol**: -1. **Delegate all work through Agent tool** โ€” invoke sub-agents, pass deliverable paths between them, and report results (permitted tools: see subagents-orchestration-guide "Orchestrator's Permitted Tools") +1. **Invoke named specialists for deliverable production** โ€” pass deliverable paths between them and validate their results (see subagents-orchestration-guide "Orchestrator Execution Boundary") 2. **Follow the 4-step task cycle exactly**: execute โ†’ branch on executor result โ†’ quality-fix โ†’ commit 3. **Enter autonomous mode** when user provides execution instruction with existing task files โ€” this IS the batch approval 4. **Scope**: Complete when all tasks are committed or escalation occurs @@ -26,7 +32,7 @@ Work plan: $ARGUMENTS Before any task processing, locate the work plan. Resolution rule: 1. List task files in `docs/plans/tasks/` matching the single-layer pattern `{plan-name}-task-*.md`. Layer-aware fullstack tasks (`{plan-name}-backend-task-*.md` / `{plan-name}-frontend-task-*.md`) are excluded here so a stale fullstack run does not redirect this recipe to the wrong work plan -2. From the matched files, also exclude every file matching any of these patterns โ€” they originate from other workflow phases and are not implementation tasks for this run's plan: `*-task-prep-*.md` (readiness preflight tasks), `_overview-*.md` (materialization overview file), `*-phase*-completion.md` (per-phase completion files), `review-fixes-*.md` (post-implementation review fixes), `integration-tests-*-task-*.md` (integration-test add-on scaffolding) +2. From the matched files, also exclude `_overview-*.md` (materialization overview files) and `*-phase*-completion.md` (per-phase completion files). 3. For each remaining file, extract the `{plan-name}` prefix as the segment that appears before `-task-` 4. When at least one task file matches, the work plan is `docs/plans/{plan-name}.md` for the prefix that has the most recent task-file mtime; ties broken by the lexicographically last `{plan-name}` 5. When no task file matches the restricted pattern, the work plan is the most-recent-mtime non-template `.md` in `docs/plans/` @@ -36,7 +42,7 @@ Before any task processing, locate the work plan. Resolution rule: Compute the **Consumed Task Set** for this run โ€” the exact files this recipe owns, executes, and later deletes. Use the same restricted pattern as Work Plan Resolution: 1. List task files in `docs/plans/tasks/` matching the single-layer pattern `{plan-name}-task-*.md` for the `{plan-name}` resolved by Work Plan Resolution. Layer-aware fullstack tasks are excluded -2. Exclude every file matching: `*-task-prep-*.md`, `_overview-*.md`, `*-phase*-completion.md`, `review-fixes-*.md`, `integration-tests-*-task-*.md` (these originate from other workflow phases) +2. Exclude every file matching `_overview-*.md` or `*-phase*-completion.md`. Every subsequent reference to "task files" in this recipe โ€” Task Generation Decision Flow, Task Execution Cycle iteration, and Final Cleanup โ€” uses this set, not the unrestricted `docs/plans/tasks/*.md` glob. @@ -48,7 +54,7 @@ Analyze the Consumed Task Set and determine the action required: |-------|----------|-------------| | Tasks exist | Consumed Task Set is non-empty | User's execution instruction serves as batch approval โ†’ Enter autonomous execution immediately | | No tasks + plan exists | Consumed Task Set is empty but the resolved work plan exists | Confirm with user โ†’ run task-decomposer | -| Neither exists + Design Doc exists | No plan, no Consumed Task Set, but `docs/design/*.md` exists | Invoke work-planner to create work plan from Design Doc, then run document-reviewer (`dev-workflows:document-reviewer`, doc_type: WorkPlan); branch on the reviewer's `verdict.decision` โ€” on `needs_revision`, re-invoke work-planner (update) and re-review until `approved`/`approved_with_conditions`; if the same blocking finding repeats without new evidence or a contract change, stop and escalate it; then present the reviewed plan for batch approval before task materialization; on `rejected`, stop before task materialization and escalate to the user | +| Neither exists + Design Doc exists | No plan, no Consumed Task Set, but `docs/design/*.md` exists | Invoke work-planner to create a work plan, then run document-reviewer (`dev-workflows:document-reviewer`, doc_type: WorkPlan). Apply the Review Resolution Gate: update for `apply`, re-review with `prior_feedback`, progress when all actionable findings are `decline`, and escalate unresolved `user_decision_required`; then present the resolved plan for batch approval before task materialization | | Neither exists | No plan, no Consumed Task Set, no Design Doc | Report missing prerequisites to user and stop | ## Task Materialization Phase (Conditional) @@ -92,9 +98,12 @@ For EACH task in the Consumed Task Set, YOU MUST: 2. **BRANCH ON EXECUTOR RESULT**: - `status: "escalation_needed"` or `"blocked"` โ†’ STOP and escalate to user - `requiresTestReview` is `true` โ†’ Invoke integration-test-reviewer with `diffBase`, changed integration/E2E paths, `taskFile`, prompt-only claims, and `mutationEvidence` - - `needs_revision` โ†’ Return to step 1 with `requiredFixes` - `approved` โ†’ Proceed to step 3 - `blocked` โ†’ STOP and escalate to user + - `needs_revision` โ†’ Apply the Review Resolution Gate + - one or more `apply` findings โ†’ Return to step 1 with those findings, then re-review with `prior_feedback` + - every actionable finding is `decline` โ†’ Proceed to step 3 + - any unresolved `user_decision_required` finding โ†’ STOP and escalate to user - `readyForQualityCheck: true` โ†’ Proceed to step 3 3. **QUALITY-FIX**: Invoke quality-fixer with `task_file`, upstream `mutationEvidence`, and `qualityCommand` when available (caller first, otherwise current task) - `stub_detected` โ†’ Return to step 1 with `incompleteImplementations[]` details @@ -146,4 +155,5 @@ Final report must include: - Quality check result - Commit count - Cleanup result +- Declined actionable findings with ID, governing reason, and evidence - Escalation or blocking summary, if any diff --git a/skills/recipe-design/SKILL.md b/skills/recipe-design/SKILL.md index 15d63d1..0c27452 100644 --- a/skills/recipe-design/SKILL.md +++ b/skills/recipe-design/SKILL.md @@ -5,6 +5,7 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. **Context**: Dedicated to the design phase. @@ -12,15 +13,20 @@ Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or g **Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. The scope bootstrap locates seed files; the named specialists own semantic investigation and artifact authorship. + +**Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression; include declined IDs with governing reasons and evidence in the final user report. +Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. + **Execution Protocol**: -1. **Delegate all work** to sub-agents โ€” your role is to invoke sub-agents, pass data between them, and report results. The one exception is the Step 1 scope bootstrap, a recipe-local orchestrator task limited to locating seed files. +1. **Invoke named specialists for deliverable production** โ€” pass data between them and validate their results. Step 1 is a recipe-local read-only scope bootstrap limited to locating seed files. 2. **Run the design flow below in order**: - Execute: scope bootstrap โ†’ codebase-analyzer โ†’ [Stop: Scope confirmation] โ†’ technical-designer โ†’ code-verifier โ†’ document-reviewer โ†’ design-sync - code-verifier and design-sync apply when the design output is a Design Doc; both are skipped for ADR-only - **Stop at every `[Stop: ...]` marker** โ†’ Wait for user approval before proceeding 3. **Scope**: Complete when design documents receive approval -**subagents-orchestration-guide usage**: Reference the guide only for orchestration principles (Delegation Boundary, Decision precedence, permitted tools), the Scale Determination table, and handoff contracts HC-02 onward. This recipe defines its own start order and subagent prompts. The guide's requirement-analyzer-origin flow, First Action Rule, HC-01, and Call Examples do not apply to this recipe. +**subagents-orchestration-guide usage**: Use the guide for orchestration principles (Delegation Boundary, Decision precedence, Execution Boundary), the Scale Determination table, and handoff contracts HC-02 onward. This recipe's start order and subagent prompts supersede the guide's requirement-analyzer-origin flow, First Action Rule, HC-01, and Agent-Specific Prompt Content. **CRITICAL**: Execute document-reviewer, design-sync (for Design Docs), and all stopping points โ€” each serves as a quality gate. Skipping any step risks undetected inconsistencies. @@ -78,7 +84,9 @@ Invoke codebase-analyzer with its existing schema. The orchestrator constructs ` ### Step 3: Scope Confirmation After codebase-analyzer returns, confirm the design scope with the user before any design work. This is a recipe-local confirmation step. -First run the requirement-convergence hearing protocol, using the codebase-analyzer findings as the facts it presents. This recipe has no requirement-analyzer, so the orchestrator both elicits and judges the fields, recording the result as the skill's `convergence` object (`outcome`, `requirements[]` with layer labels, `nonGoals[]`, plus a readiness label per field). `cost` does not apply here: the orchestrator cannot search the repository, and entering this recipe already decided to design. Carry that object into Step 4 so technical-designer persists it to the Design Doc. +Execute Skill: requirement-convergence before running the hearing protocol. + +First run the requirement-convergence hearing protocol, using the codebase-analyzer findings as the facts it presents. In this flow, the orchestrator elicits and judges the fields and records the result as the skill's `convergence` object (`outcome`, `requirements[]` with layer labels, `nonGoals[]`, plus a readiness label per field). Treat `cost` as already resolved because semantic repository investigation is assigned to codebase-analyzer and entering this recipe decided to design. Carry that object into Step 4 so technical-designer persists it to the Design Doc. Then present, sourced from the codebase-analyzer JSON, using AskUserQuestion: - **Target files/modules**: `analysisScope.filesAnalyzed` and the modules they belong to @@ -105,13 +113,20 @@ Pass the full codebase-analyzer JSON to technical-designer (handoff contract HC- - **(Design Doc only)** Invoke **code-verifier** to verify the Design Doc against existing code. Skip for ADR. - `subagent_type: "dev-workflows:code-verifier"`, `description: "Design Doc verification"`, `prompt: "doc_type: design-doc document_path: [Design Doc path] Verify Design Doc against existing code."` - **(Design Doc only)** Invoke **document-reviewer** to verify consistency, completeness, and adopted design validity + - Treat the preceding code-verifier result as `code_verification` evidence; the document-reviewer result controls correction routing. - `subagent_type: "dev-workflows:document-reviewer"`, `description: "Design Doc review"`, `prompt: "Review [Design Doc path] for consistency, completeness, and adopted design validity. doc_type: DesignDoc. review_context: creation. requirements_verbatim: [user requirements verbatim]. confirmed_decisions: [Step 3 confirmed scope and user answers]. codebase_analysis: [codebase-analyzer JSON from Step 2]. code_verification: [code-verifier output from this step]"` + - Apply the Review Resolution Gate. When `apply` findings change the Design Doc, invoke technical-designer in update mode, then re-run code-verifier and document-reviewer with `prior_feedback`. - **(ADR only)** Invoke **document-reviewer** to verify consistency and completeness - `subagent_type: "dev-workflows:document-reviewer"`, `description: "ADR review"`, `prompt: "Review [ADR path] for consistency and completeness. doc_type: ADR. codebase_analysis: [codebase-analyzer JSON from Step 2]"` + - Apply the Review Resolution Gate. When `apply` findings change the ADR, invoke technical-designer in update mode and re-run document-reviewer with `prior_feedback`. - **(Design Doc only)** Invoke **design-sync** to verify consistency across design documents. Skip for ADR-only. - `subagent_type: "dev-workflows:design-sync"`, `description: "Design consistency check"`, `prompt: "Check consistency across all Design Docs in docs/design/. Report conflicts and overlaps."` + - Apply the Review Resolution Gate to every reported conflict. + - One or more `apply` findings โ†’ invoke the named technical designer for each affected Design Doc; re-run code-verifier and document-reviewer for each modified document with the latest verification and `prior_feedback`, then re-run design-sync + - Every actionable conflict is `decline` โ†’ proceed to the approval stop + - Any unresolved `user_decision_required` conflict โ†’ stop for user input -**[STOP]**: Present the design document, plus design-sync results for a Design Doc, and obtain user approval. +**[STOP]**: Present the design document, plus design-sync results for a Design Doc, and obtain user approval. For an approved ADR, invoke technical-designer in update mode to set its status to `Accepted` and verify the update before completion. ## Completion Criteria @@ -123,7 +138,7 @@ Pass the full codebase-analyzer JSON to technical-designer (handoff contract HC- - [ ] Executed code-verifier on Design Doc and passed results to document-reviewer (skip for ADR-only) - [ ] Executed document-reviewer and addressed feedback - [ ] Executed design-sync for consistency verification (skip for ADR-only) -- [ ] Obtained user approval for design document +- [ ] Obtained user approval for the design document and verified an approved ADR has status `Accepted` ## Output Example Design phase completed. diff --git a/skills/recipe-diagnose/SKILL.md b/skills/recipe-diagnose/SKILL.md index fe5cb06..2f34835 100644 --- a/skills/recipe-diagnose/SKILL.md +++ b/skills/recipe-diagnose/SKILL.md @@ -5,6 +5,7 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. **Context**: Diagnosis flow to identify root cause and present solutions @@ -12,7 +13,9 @@ Target problem: $ARGUMENTS ## Orchestrator Definition -**Core Identity**: "I am not a worker. I am an orchestrator." +**Core Identity**: "I am an orchestrator." + +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. **Execution Method**: - Investigation โ†’ performed by investigator @@ -232,4 +235,3 @@ Rationale: [Selection rationale] - [ ] Executed solver - [ ] Achieved coverageAssessment=sufficient (or obtained user approval after 2 additional iterations) - [ ] Presented final report to user - diff --git a/skills/recipe-front-adjust/SKILL.md b/skills/recipe-front-adjust/SKILL.md index 31270db..29d1bbf 100644 --- a/skills/recipe-front-adjust/SKILL.md +++ b/skills/recipe-front-adjust/SKILL.md @@ -5,6 +5,7 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. **Context**: UI adjustment on already-implemented features. The verification loop (edit โ†’ check against the design source โ†’ refine) runs in the parent session. @@ -63,6 +64,8 @@ Adjustment request: $ARGUMENTS ## Execution Flow ### Step 1: External Resource Hearing +Execute Skill: external-resource-context before running the hearing protocol. + Run the hearing protocol per the external-resource-context skill (frontend domain). ### Step 2: UI Fact Gathering @@ -109,6 +112,11 @@ After work-planner returns: ### Step 5: Adjustment + Verification (parent session) +Execute Skill: frontend-ai-guide before planning or applying adjustment edits. +Execute Skill: typescript-rules before planning or applying adjustment edits. +Execute Skill: implementation-approach before planning or applying adjustment edits. +Execute Skill: test-implement before adding or changing tests. + For each adjustment unit (per file in Branch A; per work plan phase in Branch B): 1. **Plan the edit** based on ui-analyzer focusAreas and the relevant external resource (e.g., design origin's fetched_summary). 2. **Apply the edit** using Edit / Write / MultiEdit on the affected files. diff --git a/skills/recipe-front-build/SKILL.md b/skills/recipe-front-build/SKILL.md index 5c52651..418ebbd 100644 --- a/skills/recipe-front-build/SKILL.md +++ b/skills/recipe-front-build/SKILL.md @@ -5,13 +5,19 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. ## Orchestrator Definition **Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. + +**Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression; include declined IDs with governing reasons and evidence in the final user report. +Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. + **Execution Protocol**: -1. **Delegate all work through Agent tool** โ€” invoke sub-agents, pass deliverable paths between them, and report results (permitted tools: see subagents-orchestration-guide "Orchestrator's Permitted Tools") +1. **Invoke named specialists for deliverable production** โ€” pass deliverable paths between them and validate their results (see subagents-orchestration-guide "Orchestrator Execution Boundary") 2. **Follow the 4-step task cycle exactly**: execute โ†’ branch on executor result โ†’ quality-fix โ†’ commit 3. **Enter autonomous mode** when user provides execution instruction with existing task files โ€” this IS the batch approval 4. **Scope**: Complete when all tasks are committed or escalation occurs @@ -26,7 +32,7 @@ Work plan: $ARGUMENTS Before any task processing, locate the work plan. Resolution rule: 1. List task files in `docs/plans/tasks/` matching the single-layer pattern `{plan-name}-task-*.md`. Layer-aware fullstack tasks (`{plan-name}-backend-task-*.md` / `{plan-name}-frontend-task-*.md`) are excluded here so a stale fullstack run does not redirect this recipe to the wrong work plan -2. From the matched files, also exclude every file matching any of these patterns โ€” they originate from other workflow phases and are not implementation tasks for this run's plan: `*-task-prep-*.md` (readiness preflight tasks), `_overview-*.md` (materialization overview file), `*-phase*-completion.md` (per-phase completion files), `review-fixes-*.md` (post-implementation review fixes), `integration-tests-*-task-*.md` (integration-test add-on scaffolding) +2. From the matched files, also exclude `_overview-*.md` (materialization overview files) and `*-phase*-completion.md` (per-phase completion files). 3. For each remaining file, extract the `{plan-name}` prefix as the segment that appears before `-task-` 4. When at least one task file matches, the work plan is `docs/plans/{plan-name}.md` for the prefix that has the most recent task-file mtime; ties broken by the lexicographically last `{plan-name}` 5. When no task file matches the restricted pattern, the work plan is the most-recent-mtime non-template `.md` in `docs/plans/` @@ -36,7 +42,7 @@ Before any task processing, locate the work plan. Resolution rule: Compute the **Consumed Task Set** for this run โ€” the exact files this recipe owns, executes, and later deletes. Use the same restricted pattern as Work Plan Resolution: 1. List task files in `docs/plans/tasks/` matching the single-layer pattern `{plan-name}-task-*.md` for the `{plan-name}` resolved by Work Plan Resolution. Layer-aware fullstack tasks are excluded -2. Exclude every file matching: `*-task-prep-*.md`, `_overview-*.md`, `*-phase*-completion.md`, `review-fixes-*.md`, `integration-tests-*-task-*.md` (these originate from other workflow phases) +2. Exclude every file matching `_overview-*.md` or `*-phase*-completion.md`. Every subsequent reference to "task files" in this recipe โ€” Task Generation Decision Flow, Task Execution Cycle iteration, and Final Cleanup โ€” uses this set, not the unrestricted `docs/plans/tasks/*.md` glob. @@ -48,7 +54,7 @@ Analyze the Consumed Task Set and determine the action required: |-------|----------|-------------| | Tasks exist | Consumed Task Set is non-empty | User's execution instruction serves as batch approval โ†’ Enter autonomous execution immediately | | No tasks + plan exists | Consumed Task Set is empty but the resolved work plan exists | Confirm with user โ†’ run task-decomposer | -| Neither exists + Design Doc exists | No plan, no Consumed Task Set, but `docs/design/*.md` exists | Invoke work-planner to create work plan from Design Doc, then run document-reviewer (`dev-workflows-frontend:document-reviewer`, doc_type: WorkPlan); branch on the reviewer's `verdict.decision` โ€” on `needs_revision`, re-invoke work-planner (update) and re-review until `approved`/`approved_with_conditions`; if the same blocking finding repeats without new evidence or a contract change, stop and escalate it; then present the reviewed plan for batch approval before task materialization; on `rejected`, stop before task materialization and escalate to the user | +| Neither exists + Design Doc exists | No plan, no Consumed Task Set, but `docs/design/*.md` exists | Invoke work-planner to create a work plan, then run document-reviewer (`dev-workflows-frontend:document-reviewer`, doc_type: WorkPlan). Apply the Review Resolution Gate: update for `apply`, re-review with `prior_feedback`, progress when all actionable findings are `decline`, and escalate unresolved `user_decision_required`; then present the resolved plan for batch approval before task materialization | | Neither exists | No plan, no Consumed Task Set, no Design Doc | Report missing prerequisites to user and stop | ## Task Materialization Phase (Conditional) @@ -92,9 +98,12 @@ For EACH task in the Consumed Task Set, YOU MUST: 2. **BRANCH ON EXECUTOR RESULT**: - `status: "escalation_needed"` or `"blocked"` โ†’ STOP and escalate to user - `requiresTestReview` is `true` โ†’ Invoke integration-test-reviewer with `diffBase`, changed integration/E2E paths, `taskFile`, prompt-only claims, and `mutationEvidence` - - `needs_revision` โ†’ Return to step 1 with `requiredFixes` - `approved` โ†’ Proceed to step 3 - `blocked` โ†’ STOP and escalate to user + - `needs_revision` โ†’ Apply the Review Resolution Gate + - one or more `apply` findings โ†’ Return to step 1 with those findings, then re-review with `prior_feedback` + - every actionable finding is `decline` โ†’ Proceed to step 3 + - any unresolved `user_decision_required` finding โ†’ STOP and escalate to user - `readyForQualityCheck: true` โ†’ Proceed to step 3 3. **QUALITY-FIX**: Invoke quality-fixer-frontend with `task_file`, upstream `mutationEvidence`, and `qualityCommand` when available (caller first, otherwise current task) - `stub_detected` โ†’ Return to step 1 with `incompleteImplementations[]` details @@ -146,4 +155,5 @@ Final report must include: - Quality check result - Commit count - Cleanup result +- Declined actionable findings with ID, governing reason, and evidence - Escalation or blocking summary, if any diff --git a/skills/recipe-front-design/SKILL.md b/skills/recipe-front-design/SKILL.md index b572660..04149c7 100644 --- a/skills/recipe-front-design/SKILL.md +++ b/skills/recipe-front-design/SKILL.md @@ -5,6 +5,7 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. **Context**: Dedicated to the frontend design phase. @@ -12,15 +13,20 @@ Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or g **Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. The scope bootstrap locates seed files; the named specialists own semantic investigation and artifact authorship. + +**Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression; include declined IDs with governing reasons and evidence in the final user report. +Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. + **Execution Protocol**: -1. **Delegate all work** to sub-agents โ€” your role is to invoke sub-agents, pass data between them, and report results. The one exception is the Step 1 scope bootstrap, a recipe-local orchestrator task limited to locating seed files. +1. **Invoke named specialists for deliverable production** โ€” pass data between them and validate their results. Step 1 is a recipe-local read-only scope bootstrap limited to locating seed files. 2. **Run the frontend design flow below in order** (this recipe covers medium/large frontend): - Execute: scope bootstrap โ†’ codebase-analyzer โ†’ [Stop: Scope confirmation] โ†’ external resource hearing โ†’ ui-analyzer โ†’ ui-spec-designer โ†’ technical-designer-frontend โ†’ code-verifier โ†’ document-reviewer โ†’ design-sync - ui-spec-designer, code-verifier, and design-sync apply when the design output is a Design Doc; all are skipped for ADR-only - **Stop at every `[Stop: ...]` marker** โ†’ Wait for user approval before proceeding 3. **Scope**: Complete when design documents receive approval -**subagents-orchestration-guide usage**: Reference the guide only for orchestration principles (Delegation Boundary, Decision precedence, permitted tools), the Scale Determination table, and handoff contracts HC-02 onward. This recipe defines its own start order and subagent prompts. The guide's requirement-analyzer-origin flow, First Action Rule, HC-01, and Call Examples do not apply to this recipe. +**subagents-orchestration-guide usage**: Use the guide for orchestration principles (Delegation Boundary, Decision precedence, Execution Boundary), the Scale Determination table, and handoff contracts HC-02 onward. This recipe's start order and subagent prompts supersede the guide's requirement-analyzer-origin flow, First Action Rule, HC-01, and Agent-Specific Prompt Content. **CRITICAL**: Execute document-reviewer, design-sync (for Design Docs), and all stopping points โ€” each serves as a quality gate. Skipping any step risks undetected inconsistencies. @@ -87,7 +93,9 @@ Invoke codebase-analyzer with its existing schema. The orchestrator constructs ` ### Step 3: Scope Confirmation After codebase-analyzer returns, confirm the design scope with the user before any design work. This is a recipe-local confirmation step. -First run the requirement-convergence hearing protocol, using the codebase-analyzer findings as the facts it presents. This recipe has no requirement-analyzer, so the orchestrator both elicits and judges the fields, recording the result as the skill's `convergence` object (`outcome`, `requirements[]` with layer labels, `nonGoals[]`, plus a readiness label per field). `cost` does not apply here: the orchestrator cannot search the repository, and entering this recipe already decided to design. Carry that object into Steps 6 and 7 so ui-spec-designer respects the non-goals and technical-designer-frontend persists it to the Design Doc. +Execute Skill: requirement-convergence before running the hearing protocol. + +First run the requirement-convergence hearing protocol, using the codebase-analyzer findings as the facts it presents. In this flow, the orchestrator elicits and judges the fields and records the result as the skill's `convergence` object (`outcome`, `requirements[]` with layer labels, `nonGoals[]`, plus a readiness label per field). Treat `cost` as already resolved because semantic repository investigation is assigned to codebase-analyzer and ui-analyzer and entering this recipe decided to design. Carry that object into Steps 6 and 7 so ui-spec-designer respects the non-goals and technical-designer-frontend persists it to the Design Doc. Then present, sourced from the codebase-analyzer JSON, using AskUserQuestion: - **Target files/modules**: `analysisScope.filesAnalyzed` and the modules they belong to @@ -106,6 +114,8 @@ After the user confirms the scope, count the confirmed target files and set the **[STOP]**: Wait for the user's choice before proceeding. ### Step 4: External Resource Hearing +Execute Skill: external-resource-context before running the hearing protocol. + Run the hearing protocol per the external-resource-context skill (frontend domain). The orchestrator owns this step because it requires AskUserQuestion. The skill defines file-existence branching, two-phase hearing (structured axes + self-declaration), and persistence to `docs/project-context/external-resources.md`. ### Step 5: UI Fact Gathering @@ -140,6 +150,7 @@ Then create the UI Specification: - Example (no PRD): `prompt: "Create UI Spec from these requirements: [user requirements verbatim]. Codebase analysis: [codebase-analyzer JSON from Step 2]. Confirmed scope: [Step 3 confirmed scope]. ui_analysis: [JSON from Step 5 ui-analyzer]. Prototype code is at [user-provided path]. Place prototype in docs/ui-spec/assets/{feature-name}/."` - Invoke **document-reviewer** to verify UI Spec - `subagent_type: "dev-workflows-frontend:document-reviewer"`, `description: "UI Spec review"`, `prompt: "doc_type: UISpec target: [ui-spec path] Review for consistency and completeness"` +- Apply the Review Resolution Gate before presenting the UI Spec. If corrections are applied, re-run document-reviewer with `prior_feedback`. - **[STOP]**: Present UI Spec for user approval ### Step 7: Design Document Creation Phase @@ -150,14 +161,21 @@ Pass the Step 2 codebase-analyzer output and the Step 5 ui-analyzer output to te - **(Design Doc only)** Invoke **code-verifier** to verify Design Doc against existing code. Skip for ADR. - `subagent_type: "dev-workflows-frontend:code-verifier"`, `description: "Design Doc verification"`, `prompt: "doc_type: design-doc document_path: [Design Doc path] Verify Design Doc against existing code."` - **(Design Doc only)** Invoke **document-reviewer** to verify consistency, completeness, and adopted design validity + - Treat the preceding code-verifier result as `code_verification` evidence; the document-reviewer result controls correction routing. - `subagent_type: "dev-workflows-frontend:document-reviewer"`, `description: "Design Doc review"`, `prompt: "Review [Design Doc path] for consistency, completeness, and adopted design validity. doc_type: DesignDoc. review_context: creation. requirements_verbatim: [user requirements verbatim]. confirmed_decisions: [Step 3 confirmed scope and user answers]. codebase_analysis: [codebase-analyzer JSON from Step 2]. ui_analysis: [ui-analyzer JSON from Step 5]. code_verification: [code verification output from this step]"` + - Apply the Review Resolution Gate. When `apply` findings change the Design Doc, invoke technical-designer-frontend in update mode, then re-run code-verifier and document-reviewer with `prior_feedback`. - **(ADR only)** Invoke **document-reviewer** to verify consistency and completeness - `subagent_type: "dev-workflows-frontend:document-reviewer"`, `description: "ADR review"`, `prompt: "Review [ADR path] for consistency and completeness. doc_type: ADR. codebase_analysis: [codebase-analyzer JSON from Step 2]. ui_analysis: [ui-analyzer JSON from Step 5]"` + - Apply the Review Resolution Gate. When `apply` findings change the ADR, invoke technical-designer-frontend in update mode and re-run document-reviewer with `prior_feedback`. ### Step 8: Design Consistency Verification - **(Design Doc only)** Invoke **design-sync** using Agent tool. Skip for ADR-only. - `subagent_type: "dev-workflows-frontend:design-sync"`, `description: "Design consistency check"`, `prompt: "Check consistency across all Design Docs in docs/design/. Report conflicts and overlaps."` -- **[STOP]**: Present the design document, plus design-sync results for a Design Doc, and obtain user approval + - Apply the Review Resolution Gate to every reported conflict. + - One or more `apply` findings โ†’ invoke the named technical designer for each affected Design Doc; re-run code-verifier and document-reviewer for each modified document with the latest verification and `prior_feedback`, then re-run design-sync + - Every actionable conflict is `decline` โ†’ proceed to the approval stop + - Any unresolved `user_decision_required` conflict โ†’ stop for user input +- **[STOP]**: Present the design document, plus design-sync results for a Design Doc, and obtain user approval. For an approved ADR, invoke technical-designer-frontend in update mode to set its status to `Accepted` and verify the update before completion ## Completion Criteria @@ -172,10 +190,10 @@ Pass the Step 2 codebase-analyzer output and the Step 5 ui-analyzer output to te - [ ] Executed code-verifier on Design Doc and passed results to document-reviewer (skip for ADR-only) - [ ] Executed document-reviewer and addressed feedback - [ ] Executed design-sync for consistency verification (skip for ADR-only) -- [ ] Obtained user approval for design document +- [ ] Obtained user approval for the design document and verified an approved ADR has status `Accepted` ## Output Example Frontend design phase completed. -- UI Specification: docs/ui-spec/[feature-name]-ui-spec.md +- UI Specification: docs/ui-spec/[feature-name]-ui-spec.md or N/A โ€” ADR-only - Design document: docs/design/[document-name].md or docs/adr/[document-name].md - Approval status: User approved diff --git a/skills/recipe-front-plan/SKILL.md b/skills/recipe-front-plan/SKILL.md index 91566bb..4090a1c 100644 --- a/skills/recipe-front-plan/SKILL.md +++ b/skills/recipe-front-plan/SKILL.md @@ -5,6 +5,7 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. **Context**: Dedicated to the frontend planning phase. @@ -12,8 +13,13 @@ Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or g **Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. + +**Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression; include declined IDs with governing reasons and evidence in the final user report. +Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. + **Execution Protocol**: -1. **Delegate all work** to sub-agents โ€” your role is to invoke sub-agents, pass data between them, and report results +1. **Invoke named specialists for deliverable production** โ€” pass data between them and validate their results 2. **Follow subagents-orchestration-guide skill planning flow**: - Execute steps defined below - **Stop and obtain approval** for plan content before completion @@ -71,7 +77,7 @@ Invoke document-reviewer to review the work plan: - `subagent_type`: "dev-workflows-frontend:document-reviewer" - `description`: "Work plan review" - `prompt`: "doc_type: WorkPlan target: docs/plans/[plan-name].md. Review semantic traceability to the Design Doc, early verification placement, real-boundary verification coverage, Failure Mode Checklist, and Review Scope." -- The work plan is a derivation of the Design Doc, so plan-fidelity findings are resolved without user input while the revision loop makes observable progress. Branch on the reviewer's `verdict.decision`: on `needs_revision`, re-invoke work-planner in update mode with the findings and re-review, repeating until `approved` or `approved_with_conditions`; if the same blocking finding repeats without new evidence or a contract change, stop and escalate it. On `rejected`, escalate to the user. +- Apply the Review Resolution Gate before branching. On `needs_revision`, re-invoke work-planner in update mode with the `apply` findings and re-review with `prior_feedback`. A result whose actionable findings are all `decline` is eligible for approval; escalate unresolved `user_decision_required` or unusable inputs. ### Step 5: Present for Approval - Present the reviewed work plan to the user for batch approval. If the user requests changes, re-invoke work-planner with revised parameters and re-run Step 4. diff --git a/skills/recipe-front-review/SKILL.md b/skills/recipe-front-review/SKILL.md index d4ab843..338d939 100644 --- a/skills/recipe-front-review/SKILL.md +++ b/skills/recipe-front-review/SKILL.md @@ -5,6 +5,7 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. **Context**: Post-implementation quality assurance for React/TypeScript frontend @@ -12,7 +13,12 @@ Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or g **Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) -**First Action**: Register Steps 1-11 using TaskCreate before any execution. +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. + +**Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression; include declined IDs with governing reasons and evidence in the final user report. +Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. + +**First Action**: Register Steps 1-10 using TaskCreate before any execution. ## Execution Method @@ -56,17 +62,9 @@ Invoke security-reviewer using Agent tool: **If security-reviewer returned `blocked`**: Stop immediately. Report the blocked finding and escalate to user. Do not proceed to fix steps. -**Code compliance criteria (considering project stage)**: -- Prototype: Pass at 70%+ -- Production: 90%+ recommended - -**Security criteria**: -- `approved` or `approved_with_notes` โ†’ Pass -- `needs_revision` โ†’ Fail +Apply the Review Resolution Gate to both outputs before reporting or routing them. Finding dispositions determine routing; compliance percentages remain diagnostic. -**Report both results independently using subagent output fields only**: - -Before presenting to the user, the orchestrator computes a recommended route per finding using the rule below (this rule is internal โ€” do not include it in the user-facing prompt): +For each `apply` or `user_decision_required` finding, compute a proposed route using the rule below: | Finding pattern | Recommended route | |-----------------|-------------------| @@ -74,7 +72,7 @@ Before presenting to the user, the orchestrator computes a recommended route per | `dd_violation` where the code drifted from a still-correct Design Doc | `c` (Code-side fix) | | `reliability` / `security` / `maintainability` findings | `c` (Code-side fix) | -Then present to the user (label each finding with its recommended route, grouped by route): +Then present the adjudicated result to the user. Group `apply` and `user_decision_required` findings by proposed route, and list declined IDs with their reasons separately: ``` Code Compliance: [complianceRate from code-reviewer] @@ -97,23 +95,19 @@ Security Review: [status from security-reviewer] - [policy] [location]: [description] โ€” [rationale] [recommended: c] Notes: [notes from security-reviewer, if present] -Resolve discrepancies โ€” confirm or override the recommended route per finding: +Approve the proposed changes or decide unresolved items: c) Code-side fix โ€” code violates Design Doc; modify code to match d) Design-side update โ€” code is correct; Design Doc is stale, revise it - s) Skip โ€” accept current state without changes + s) Decline โ€” record the governing reason and accept current state ``` -Use AskUserQuestion. The default offer is **"accept all recommended routes"** โ€” a single confirmation for the typical case where the orchestrator's recommendations are correct. When the user wants to override, collect per-finding c/d/s decisions instead. If the user selects `s` for everything: skip Steps 5-10, proceed to Step 11. +This review command authorizes analysis; use AskUserQuestion to obtain separate implementation authority. The batch option is **"approve all proposed `apply` routes"** and its scope consists exclusively of those routes. Collect an explicit decision for each `user_decision_required` item. When the approved change set is empty, proceed directly to Step 10. Pass approved findings, routes, covered files/sections, and any stated total size budget to update or fix agents. Before re-validation, map every diff hunk to an approved finding or required consistency update; request a scope decision for unmapped or over-budget changes. -### Step 5: Execute Skill - -Execute Skill: documentation-criteria (for task file template) - -### Step 5d: Design-Side Update +### Step 5: Design-Side Update -Run this step only when the user routed at least one finding to `d`. When all routes are `c` or `s`, skip directly to Step 6. +Run this step only when the user routed at least one finding to `d`. When no `d` routes exist, skip it; continue to Step 6 only when approved `c` routes remain. 1. Invoke technical-designer-frontend in update mode using Agent tool: - `subagent_type`: "dev-workflows-frontend:technical-designer-frontend" @@ -124,6 +118,7 @@ Run this step only when the user routed at least one finding to `d`. When all ro - `subagent_type`: "dev-workflows-frontend:document-reviewer" - `description`: "Document review of updated Design Doc" - `prompt`: "Review updated Design Doc at [path] for consistency and completeness. doc_type: DesignDoc. review_context: update." + - Apply the Review Resolution Gate to this result. Route `apply` findings back to technical-designer-frontend and re-run document-reviewer with `prior_feedback`; stop for unresolved `user_decision_required`; proceed when the result is approved or every actionable finding is `decline`. 3. When multiple Design Docs exist (`ls docs/design/*.md | grep -v template | wc -l > 1`), invoke design-sync: - `subagent_type`: "dev-workflows-frontend:design-sync" @@ -131,53 +126,44 @@ Run this step only when the user routed at least one finding to `d`. When all ro - `prompt`: "source_design: [updated DD path]. Detect conflicts across all Design Docs after the update." - When `sync_status: conflicts_found`: present conflicts to the user; resolution requires re-invoking technical-designer-frontend for affected DDs. -4. After Step 5d completes: - - If the user selected `d` for all findings (no `c` routes) โ†’ skip Steps 6-8, proceed to Step 9 for re-validation +4. After Step 5 completes: + - If the user selected `d` for all findings (no `c` routes) โ†’ skip Steps 6-7, proceed to Step 8 for re-validation - If the user selected both `d` and `c` โ†’ re-evaluate the `c`-routed findings against the updated DD and drop any that are now satisfied by the DD revision; then proceed to Step 6 with the remaining `c` findings -### Step 6: Create Task File - -Create task file at `docs/plans/tasks/review-fixes-YYYYMMDD.md` -Include both code compliance issues and security requiredFixes. - -### Step 7: Execute Fixes +### Step 6: Execute Fixes Invoke task-executor-frontend using Agent tool: - `subagent_type`: "dev-workflows-frontend:task-executor-frontend" - `description`: "Execute review fixes" -- `prompt`: "Task file: docs/plans/tasks/review-fixes-YYYYMMDD.md. Apply staged fixes (stops at 5 files)." +- `prompt`: "Apply these approved code-side findings directly: [findings with IDs, governing sources, smallest correction, affected paths, and observable verification condition]. Keep the change within the approved routes and stated total size budget." -### Step 8: Quality Check +### Step 7: Quality Check Invoke quality-fixer-frontend using Agent tool: - `subagent_type`: "dev-workflows-frontend:quality-fixer-frontend" - `description`: "Quality gate check" -- Pass Step 7 `mutationEvidence` and `qualityCommand` when available (caller first, otherwise current task). +- Pass Step 6 `filesModified` and `mutationEvidence`. - `prompt`: "Confirm quality gate passage for fixed files." -### Step 9: Re-validate code-reviewer +### Step 8: Re-validate code-reviewer Invoke code-reviewer using Agent tool: - `subagent_type`: "dev-workflows-frontend:code-reviewer" - `description`: "Re-validate compliance" -- `prompt`: "Re-validate Design Doc compliance after fixes. Design Doc: [path]. Implementation files: [file list]. Prior compliance issues: $STEP_2_OUTPUT. Verify each prior issue is resolved (whether resolved code-side or design-side)." +- `prompt`: "Re-validate Design Doc compliance after fixes. Design Doc: [path]. Implementation files: [file list]. prior_feedback: [{id, disposition, correction?, reason?, evidence}]. Review the current state normally, then reconcile every prior item." -### Step 10: Re-validate security-reviewer +### Step 9: Re-validate security-reviewer Invoke security-reviewer using Agent tool (only if security fixes were applied): - `subagent_type`: "dev-workflows-frontend:security-reviewer" - `description`: "Re-validate security" -- `prompt`: "Re-validate security after fixes. governingDocuments: [{\"type\":\"design-doc\",\"path\":\"[path]\"}]. implementationFiles: [file list]. Prior findings: $STEP_3_OUTPUT." - -### Step 11: Final Cleanup and Report +- `prompt`: "Re-validate security after fixes. governingDocuments: [{\"type\":\"design-doc\",\"path\":\"[path]\"}]. implementationFiles: [file list]. prior_feedback: [{id, disposition, correction?, reason?, evidence}]. Review the current state normally, then reconcile every prior item." -Delete the review-fix task file this recipe created (if any). Its work is committed; `docs/plans/` is ephemeral working state and is not retained between recipe runs: +Apply the Review Resolution Gate to every Step 8 and Step 9 result before Step 10. Route new `apply` findings through their approved design-side or code-side path and repeat the affected verification; stop for unresolved `user_decision_required`; proceed when each result is approved or every actionable finding is `decline`. -- Delete `docs/plans/tasks/review-fixes-YYYYMMDD.md` if it exists +### Step 10: Final Report -If the file cannot be deleted (filesystem error), report the failure but do not block the final report. - -Then present the final report: +Present the final report: ``` Code Compliance: @@ -191,8 +177,6 @@ Security Review: Remaining issues: - [items requiring manual intervention] - -Cleanup: review-fixes task file removed ``` ## Auto-fixable Items (code-side path) diff --git a/skills/recipe-fullstack-build/SKILL.md b/skills/recipe-fullstack-build/SKILL.md index 84a64aa..9531bbd 100644 --- a/skills/recipe-fullstack-build/SKILL.md +++ b/skills/recipe-fullstack-build/SKILL.md @@ -5,18 +5,24 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. ## Orchestrator Definition **Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. + +**Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression; include declined IDs with governing reasons and evidence in the final user report. +Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. + ## Required Reference **MANDATORY**: Read `references/monorepo-flow.md` from subagents-orchestration-guide skill BEFORE proceeding. Follow the Extended Task Cycle and Agent Routing defined there. ## Execution Protocol -1. **Delegate all work through Agent tool** โ€” invoke sub-agents, pass deliverable paths between them, and report results (permitted tools: see subagents-orchestration-guide "Orchestrator's Permitted Tools") +1. **Invoke named specialists for deliverable production** โ€” pass deliverable paths between them and validate their results (see subagents-orchestration-guide "Orchestrator Execution Boundary") 2. **Route agents by task filename pattern** (see monorepo-flow.md reference): - `*-backend-task-*` โ†’ task-executor + quality-fixer - `*-frontend-task-*` โ†’ task-executor-frontend + quality-fixer-frontend @@ -34,7 +40,7 @@ Work plan: $ARGUMENTS Before any task processing, locate the work plan. Resolution rule: 1. List task files in `docs/plans/tasks/` matching the layer-aware patterns `{plan-name}-backend-task-*.md` and `{plan-name}-frontend-task-*.md` only. Single-layer tasks (`{plan-name}-task-*.md`) are excluded here so a stale single-layer run does not redirect this recipe to the wrong work plan -2. From the matched files, also exclude every file matching any of these patterns โ€” they originate from other workflow phases and are not implementation tasks for this run's plan: `*-task-prep-*.md` (readiness preflight tasks), `_overview-*.md` (materialization overview file), `*-phase*-completion.md` (per-phase completion files), `review-fixes-*.md` (post-implementation review fixes), `integration-tests-*-task-*.md` (integration-test add-on scaffolding) +2. From the matched files, also exclude `_overview-*.md` (materialization overview files) and `*-phase*-completion.md` (per-phase completion files). 3. For each remaining file, extract the `{plan-name}` prefix as the segment that appears before `-backend-task-` or `-frontend-task-` 4. When at least one task file matches, the work plan is `docs/plans/{plan-name}.md` for the prefix that has the most recent task-file mtime; ties broken by the lexicographically last `{plan-name}` 5. When no task file matches the restricted pattern, the work plan is the most-recent-mtime non-template `.md` in `docs/plans/` @@ -44,7 +50,7 @@ Before any task processing, locate the work plan. Resolution rule: Compute the **Consumed Task Set** for this run โ€” the exact files this recipe owns, executes, and later deletes. Use the same restricted pattern as Work Plan Resolution: 1. List task files in `docs/plans/tasks/` matching the layer-aware patterns `{plan-name}-backend-task-*.md` and `{plan-name}-frontend-task-*.md` for the `{plan-name}` resolved by Work Plan Resolution. Single-layer tasks are excluded -2. Exclude every file matching: `*-task-prep-*.md`, `_overview-*.md`, `*-phase*-completion.md`, `review-fixes-*.md`, `integration-tests-*-task-*.md` (these originate from other workflow phases) +2. Exclude every file matching `_overview-*.md` or `*-phase*-completion.md`. Every subsequent reference to "task files" in this recipe โ€” Task Generation Decision Flow, Task Execution Cycle iteration, and Final Cleanup โ€” uses this set, not the unrestricted `docs/plans/tasks/*.md` glob. @@ -56,7 +62,7 @@ Analyze the Consumed Task Set and determine the action required: |-------|----------|-------------| | Tasks exist | Consumed Task Set is non-empty | User's execution instruction serves as batch approval โ†’ Enter autonomous execution immediately | | No tasks + plan exists | Consumed Task Set is empty but the resolved work plan exists | Confirm with user โ†’ run task-decomposer | -| Neither exists + Design Doc exists | No plan, no Consumed Task Set, but `docs/design/*.md` exists | Invoke work-planner to create work plan from Design Doc(s), then run document-reviewer (`dev-workflows:document-reviewer`, doc_type: WorkPlan); branch on the reviewer's `verdict.decision` โ€” on `needs_revision`, re-invoke work-planner (update) and re-review until `approved`/`approved_with_conditions`; if the same blocking finding repeats without new evidence or a contract change, stop and escalate it; then present the reviewed plan for batch approval before task materialization; on `rejected`, stop before task materialization and escalate to the user | +| Neither exists + Design Doc exists | No plan, no Consumed Task Set, but `docs/design/*.md` exists | Invoke work-planner to create a work plan, then run document-reviewer (`dev-workflows:document-reviewer`, doc_type: WorkPlan). Apply the Review Resolution Gate: update for `apply`, re-review with `prior_feedback`, progress when all actionable findings are `decline`, and escalate unresolved `user_decision_required`; then present the resolved plan for batch approval before task materialization | | Neither exists | No plan, no Consumed Task Set, no Design Doc | Report missing prerequisites to user and stop | ## Task Materialization Phase (Conditional) @@ -110,9 +116,12 @@ For EACH task, YOU MUST: 2. **BRANCH ON EXECUTOR RESULT**: - `status: "escalation_needed"` or `"blocked"` โ†’ STOP and escalate to user - `requiresTestReview` is `true` โ†’ Invoke integration-test-reviewer with `diffBase`, changed integration/E2E paths, `taskFile`, prompt-only claims, and `mutationEvidence` - - `needs_revision` โ†’ Return to step 1 with `requiredFixes` - `approved` โ†’ Proceed to step 3 - `blocked` โ†’ STOP and escalate to user + - `needs_revision` โ†’ Apply the Review Resolution Gate + - one or more `apply` findings โ†’ Return to step 1 with those findings, then re-review with `prior_feedback` + - every actionable finding is `decline` โ†’ Proceed to step 3 + - any unresolved `user_decision_required` finding โ†’ STOP and escalate to user - `readyForQualityCheck: true` โ†’ Proceed to step 3 3. **QUALITY-FIX**: Invoke the layer-appropriate quality-fixer with `task_file`, upstream `mutationEvidence`, and `qualityCommand` when available (caller first, otherwise current task) - `stub_detected` โ†’ Return to step 1 with `incompleteImplementations[]` details @@ -164,4 +173,5 @@ Final report must include: - Quality check result - Commit count - Cleanup result +- Declined actionable findings with ID, governing reason, and evidence - Escalation or blocking summary, if any diff --git a/skills/recipe-fullstack-implement/SKILL.md b/skills/recipe-fullstack-implement/SKILL.md index d750e48..a98f74c 100644 --- a/skills/recipe-fullstack-implement/SKILL.md +++ b/skills/recipe-fullstack-implement/SKILL.md @@ -5,6 +5,7 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. **Context**: Full-cycle fullstack implementation management (Requirements Analysis โ†’ Design (backend + frontend) โ†’ Planning โ†’ Implementation โ†’ Quality Assurance) @@ -12,13 +13,18 @@ Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or g **Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. + +**Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression; include declined IDs with governing reasons and evidence in the final user report. +Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. + ## Required Reference **MANDATORY**: Read `references/monorepo-flow.md` from subagents-orchestration-guide skill BEFORE proceeding. Follow the Fullstack Flow defined there instead of the standard single-layer flow. ## Execution Protocol -1. **Delegate all work through Agent tool** โ€” invoke sub-agents, pass deliverable paths between them, and report results (permitted tools: see subagents-orchestration-guide "Orchestrator's Permitted Tools") +1. **Invoke named specialists for deliverable production** โ€” pass deliverable paths between them and validate their results (see subagents-orchestration-guide "Orchestrator Execution Boundary") 2. **Follow monorepo-flow.md** for the design phase (multiple Design Docs, design-sync, vertical slicing) 3. **Follow subagents-orchestration-guide skill** for all other orchestration rules (stop points, structured responses, escalation) 4. **Enter autonomous mode** only after "batch approval for entire implementation phase" @@ -48,6 +54,8 @@ When continuing existing flow, verify: ### 3. Design through Planning Phase +Execute Skill: external-resource-context before running the external resource hearing in monorepo-flow.md. + **Follow monorepo-flow.md** for the complete design-through-planning flow (Steps 1-17 for Large scale, Steps 1-15 for Medium scale). The flow table in that reference defines every step, agent invocation, parallelization rule, and stop point. Key points to enforce as the orchestrator runs the flow: @@ -64,6 +72,8 @@ After scale determination, use TaskCreate to register each design/planning step ## After requirement-analyzer [Stop] +Execute Skill: requirement-convergence before running the hearing protocol. + Run the requirement-convergence hearing protocol on the returned `convergence` object before presenting anything else, using the analyzer's scope facts and cost band as the facts it presents. When user responds to questions: @@ -113,8 +123,14 @@ Escalate when the required fix or investigation falls outside that scope. **Rules**: 1. Execute ONE task completely before starting next (each task goes through the full 4-step cycle via Agent tool, using the correct executor per filename pattern) -2. Check executor status before quality-fixer (escalation check) -3. Run quality-fixer after each executor with `task_file`, upstream `mutationEvidence`, and `qualityCommand` when available (caller first, otherwise current task) +2. Check executor status before quality-fixer (escalation check). When `requiresTestReview` is `true`, invoke integration-test-reviewer with `diffBase`, changed integration/E2E paths, `taskFile`, prompt claims, and `mutationEvidence`, then branch on its status: + - `approved` โ†’ Continue to rule 3 + - `blocked` โ†’ Escalate to user + - `needs_revision` โ†’ Apply the Review Resolution Gate + - one or more `apply` findings โ†’ Return them to the layer executor, then re-review with `prior_feedback` + - every actionable finding is `decline` โ†’ Continue to rule 3 + - any unresolved `user_decision_required` finding โ†’ Escalate to user +3. Run the layer quality-fixer after the executor and any required test-review loop completes, passing `task_file`, upstream `mutationEvidence`, and `qualityCommand` when available (caller first, otherwise current task) 4. Check quality-fixer response: - `stub_detected` โ†’ Return to executor with `incompleteImplementations[]` details - `blocked` โ†’ Escalate to user @@ -147,9 +163,7 @@ After acceptance-test-generator execution, when invoking work-planner (subagent_ - Generated fixture-e2e test file path or null (from `generatedFiles.fixtureE2e`) - Generated service-integration-e2e test file path or null (from `generatedFiles.serviceE2e`) - Per-lane E2E absence reason (from `e2eAbsenceReason.fixtureE2e` and `e2eAbsenceReason.serviceE2e`, when each lane is null) -- Explicit note: integration tests are created simultaneously with implementation, fixture-e2e tests are created alongside the UI feature phase, service-integration-e2e tests are executed only in the final phase ## Execution Method -All work is executed through sub-agents. -Sub-agent selection follows monorepo-flow.md reference and subagents-orchestration-guide skill. +Deliverable production is executed through the specialist selected by monorepo-flow.md and subagents-orchestration-guide; workflow decisions and returned-result validation remain with the orchestrator. diff --git a/skills/recipe-implement/SKILL.md b/skills/recipe-implement/SKILL.md index 57437b7..f0c44fa 100644 --- a/skills/recipe-implement/SKILL.md +++ b/skills/recipe-implement/SKILL.md @@ -5,6 +5,7 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. **Context**: Full-cycle implementation management (Requirements Analysis โ†’ Design โ†’ Planning โ†’ Implementation โ†’ Quality Assurance) @@ -12,8 +13,13 @@ Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or g **Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. + +**Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression; include declined IDs with governing reasons and evidence in the final user report. +Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. + **Execution Protocol**: -1. **Delegate all work through Agent tool** โ€” invoke sub-agents, pass deliverable paths between them, and report results (permitted tools: see subagents-orchestration-guide "Orchestrator's Permitted Tools") +1. **Invoke named specialists for deliverable production** โ€” pass deliverable paths between them and validate their results (see subagents-orchestration-guide "Orchestrator Execution Boundary") 2. **Follow subagents-orchestration-guide skill flows exactly**: - Execute one step at a time in the defined flow (Large/Medium/Small scale) - When flow specifies "Execute document-reviewer" โ†’ Execute it immediately @@ -53,6 +59,8 @@ When continuing existing flow, verify: ### After requirement-analyzer [Stop] +Execute Skill: requirement-convergence before running the hearing protocol. + Run the requirement-convergence hearing protocol on the returned `convergence` object before presenting anything else, using the analyzer's scope facts and cost band as the facts it presents. When user responds to questions: @@ -102,9 +110,12 @@ Escalate when the required fix or investigation falls outside that scope. 2. Check task-executor response: - `status: escalation_needed` or `blocked` โ†’ Escalate to user - `requiresTestReview` is `true` โ†’ Invoke integration-test-reviewer with `diffBase`, changed integration/E2E paths, `taskFile`, prompt-only claims, and `mutationEvidence` - - `needs_revision` โ†’ Return to step 1 with `requiredFixes` - `approved` โ†’ Proceed to step 3 - `blocked` โ†’ Escalate to user + - `needs_revision` โ†’ Apply the Review Resolution Gate + - one or more `apply` findings โ†’ Return to step 1 with those findings, then re-review with `prior_feedback` + - every actionable finding is `decline` โ†’ Proceed to step 3 + - any unresolved `user_decision_required` finding โ†’ Escalate to user - Otherwise โ†’ Proceed to step 3 3. quality-fixer โ†’ Pass `task_file`, upstream `mutationEvidence`, and `qualityCommand` when available (caller first, otherwise current task); run quality checks and fixes - `stub_detected` โ†’ Return to step 1 with `incompleteImplementations[]` details @@ -139,9 +150,7 @@ After acceptance-test-generator execution, when invoking work-planner (subagent_ - Generated fixture-e2e test file path or null (from `generatedFiles.fixtureE2e`) - Generated service-integration-e2e test file path or null (from `generatedFiles.serviceE2e`) - Per-lane E2E absence reason (from `e2eAbsenceReason.fixtureE2e` and `e2eAbsenceReason.serviceE2e`, when each lane is null) -- Explicit note: integration tests are created simultaneously with implementation, fixture-e2e tests are created alongside the UI feature phase, service-integration-e2e tests are executed only in the final phase ## Execution Method -All work is executed through sub-agents. -Sub-agent selection follows subagents-orchestration-guide skill. +Deliverable production is executed through the specialist selected by subagents-orchestration-guide; workflow decisions and returned-result validation remain with the orchestrator. diff --git a/skills/recipe-plan/SKILL.md b/skills/recipe-plan/SKILL.md index d0acefd..e2cd10a 100644 --- a/skills/recipe-plan/SKILL.md +++ b/skills/recipe-plan/SKILL.md @@ -5,6 +5,7 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. **Context**: Dedicated to the planning phase. @@ -12,8 +13,13 @@ Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or g **Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. + +**Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression; include declined IDs with governing reasons and evidence in the final user report. +Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. + **Execution Protocol**: -1. **Delegate all work** to sub-agents โ€” your role is to invoke sub-agents, pass data between them, and report results +1. **Invoke named specialists for deliverable production** โ€” pass data between them and validate their results 2. **Follow subagents-orchestration-guide skill planning flow exactly**: - Execute steps defined below - **Stop and obtain approval** for plan content before completion @@ -66,7 +72,7 @@ Invoke document-reviewer to review the work plan: - `subagent_type`: "dev-workflows:document-reviewer" - `description`: "Work plan review" - `prompt`: "doc_type: WorkPlan target: docs/plans/[plan-name].md. Review semantic traceability to the Design Doc, early verification placement, real-boundary verification coverage, Failure Mode Checklist, and Review Scope." -- The work plan is a derivation of the Design Doc, so plan-fidelity findings are resolved without user input while the revision loop makes observable progress. Branch on the reviewer's `verdict.decision`: on `needs_revision`, re-invoke work-planner in update mode with the findings and re-review, repeating until `approved` or `approved_with_conditions`; if the same blocking finding repeats without new evidence or a contract change, stop and escalate it. On `rejected`, escalate to the user. +- Apply the Review Resolution Gate before branching. On `needs_revision`, re-invoke work-planner in update mode with the `apply` findings and re-review with `prior_feedback`. A result whose actionable findings are all `decline` is eligible for approval; escalate unresolved `user_decision_required` or unusable inputs. ### Step 5: Present for Approval - Present the reviewed work plan to the user for batch approval. If the user requests changes, re-invoke work-planner with revised parameters and re-run Step 4. diff --git a/skills/recipe-prepare-implementation/SKILL.md b/skills/recipe-prepare-implementation/SKILL.md index acac374..9c70371 100644 --- a/skills/recipe-prepare-implementation/SKILL.md +++ b/skills/recipe-prepare-implementation/SKILL.md @@ -5,17 +5,20 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. -**Context**: Optional readiness phase between work-plan approval and recipe-*-build. Confirms the implementation will be observable from Phase 1 onward and resolves any gaps via Phase 0 tasks. Exits no-op when the readiness criteria already pass, so the recipe is safe to invoke unconditionally. +**Context**: Optional readiness phase between work-plan approval and recipe-*-build. Confirms the implementation will be observable from Phase 1 onward and resolves any gaps before build execution. Exits no-op when the readiness criteria already pass, so the recipe is safe to invoke unconditionally. ## Orchestrator Definition **Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. + **Execution Protocol**: -1. **Delegate all work through Agent tool** โ€” invoke sub-agents, pass deliverable paths between them, and report results (permitted tools: see subagents-orchestration-guide "Orchestrator's Permitted Tools") -2. **Self-contained scope**: When gaps are found, this recipe BOTH generates resolution tasks AND executes them through the standard 4-step cycle. Recipe completes only when readiness criteria pass or remaining gaps are escalated. -3. **No-op exit**: When the readiness scan finds no failing criteria, generate no resolution tasks and exit immediately, presenting the Readiness Report to the user. No files are modified in this branch. +1. **Invoke named specialists for deliverable production** โ€” pass deliverable paths between them and validate their results (see subagents-orchestration-guide "Orchestrator Execution Boundary") +2. **Self-contained scope**: When gaps are found, this recipe defines resolution items and executes them through the standard 4-step cycle. Recipe completes only when readiness criteria pass or remaining gaps are escalated. +3. **No-op exit**: When the readiness scan finds no failing criteria, generate no resolution items and exit immediately, presenting the Readiness Report to the user. No files are modified in this branch. Work plan: $ARGUMENTS @@ -84,48 +87,44 @@ When every applicable criterion is `pass` (zero `fail`): When one or more criteria are `fail` โ†’ proceed to Step 4. -### Step 4: Plan Resolution Tasks +### Step 4: Plan Resolution Items For each `fail` criterion: -1. Determine the smallest concrete task that closes the gap (examples: "Add fixture entry for ComponentX covering loading/empty/error states", "Add seed script for E2E user fixtures", "Document local startup commands in docs/run/local.md") -2. Decide the task's **layer** by matching every target file path against the markers below: +1. Determine the smallest concrete correction that closes the gap (examples: "Add fixture entry for ComponentX covering loading/empty/error states", "Add seed script for E2E user fixtures", "Document local startup commands in docs/run/local.md") +2. Decide the resolution item's **layer** by matching every target file path against the markers below: - **backend** when every target file path matches one of: `**/api/**`, `**/server/**`, `**/services/**`, `**/backend/**`, `**/handlers/**`, `**/repositories/**` - **frontend** when every target file path matches one of: `**/components/**`, `**/pages/**`, `**/web/**`, `**/frontend/**`, `**/*.tsx`, `**/*.jsx` - - **mixed** (target files span both backend and frontend markers) โ†’ escalate to user; ask the user to split the gap into per-layer tasks - - **unrecognized** (any target file matches neither backend nor frontend markers โ€” e.g., `docs/**`, `scripts/**`, root-level configs, fixture data files outside the markers above) โ†’ escalate to user; ask the user to either (a) decide which layer's executor / quality-fixer should run the task, or (b) update the markers if the project uses different paths + - **mixed** (target files span both backend and frontend markers) โ†’ escalate to user; ask the user to split the gap into per-layer items + - **unrecognized** (any target file matches neither backend nor frontend markers โ€” e.g., `docs/**`, `scripts/**`, root-level configs, fixture data files outside the markers above) โ†’ escalate to user; ask the user to either (a) decide which layer's executor / quality-fixer should run the item, or (b) update the markers if the project uses different paths Apply the rules in the order above. The first matching rule wins; "unrecognized" is the final fallback rather than a catch-all that defaults to backend. -3. Create a Phase 0 task file at `docs/plans/tasks/{plan-name}-backend-task-prep-{NN}.md` (backend) or `docs/plans/tasks/{plan-name}-frontend-task-prep-{NN}.md` (frontend) using the task template from documentation-criteria skill. The `-task-prep-` segment lets recipe-prepare-implementation distinguish prep tasks from implementation tasks while keeping the existing `{plan-name}-{layer}-task-*` matcher used by other recipes -4. Update the work plan to insert these tasks as Phase 0 (before Phase 1) -Present the proposed resolution task list to the user with AskUserQuestion. Proceed only after explicit approval โ€” this is the single human gate inside this recipe. +Present the proposed resolution item list to the user with AskUserQuestion. Proceed only after explicit approval โ€” this is the single human gate inside this recipe. -### Step 5: Execute Resolution Tasks +### Step 5: Execute Resolution Items -For each resolution task, run the standard 4-step cycle (see subagents-orchestration-guide "Task Management: 4-Step Cycle"): +For each approved resolution item, run execute โ†’ branch โ†’ quality-fix โ†’ commit: -1. **Agent tool** โ€” route by filename layer segment: - - `*-backend-task-prep-*` โ†’ `subagent_type: "dev-workflows:task-executor"` - - `*-frontend-task-prep-*` โ†’ `subagent_type: "dev-workflows-frontend:task-executor-frontend"` - - Filename without a recognized layer segment โ†’ escalate (the file should not exist; Step 4 prevents this) +1. **Agent tool** โ€” route by the item's layer: + - `backend` โ†’ `subagent_type: "dev-workflows:task-executor"` + - `frontend` โ†’ `subagent_type: "dev-workflows-frontend:task-executor-frontend"` + - Pass the exact resolution item, governing documents, target paths, and verification condition directly 2. Check escalation per orchestration-guide -3. **quality-fixer** โ€” route by the same filename layer segment: - - `*-backend-task-prep-*` โ†’ `"dev-workflows:quality-fixer"` - - `*-frontend-task-prep-*` โ†’ `"dev-workflows-frontend:quality-fixer-frontend"` - - Pass upstream `mutationEvidence` and `qualityCommand` when available (caller first, otherwise current task). +3. **quality-fixer** โ€” route by the same Executor lane: + - `backend` โ†’ `"dev-workflows:quality-fixer"` + - `frontend` โ†’ `"dev-workflows-frontend:quality-fixer-frontend"` + - Pass upstream `filesModified` and `mutationEvidence`. 4. **Commit** when quality-fixer returns `approved` Append the Scope Boundary block (below) to every subagent prompt. -### Step 6: Re-scan, Present Readiness Report, Cleanup, Exit - -1. **Re-scan**: Re-run the Step 2 readiness scan after all resolution tasks are committed. +### Step 6: Re-scan, Present Readiness Report, Exit -2. **Present Readiness Report**: Present the Readiness Report (see Output Format below) to the user. The report is shown in-session and is not written into the work plan โ€” the durable output of this recipe is the committed Phase 0 resolution tasks, not a persisted report. +1. **Re-scan**: Re-run the Step 2 readiness scan after all resolution items are committed. -3. **Final Cleanup**: Delete every prep task file this recipe created for the current `{plan-name}` (`docs/plans/tasks/{plan-name}-backend-task-prep-*.md` and `docs/plans/tasks/{plan-name}-frontend-task-prep-*.md`) AND the phase-completion file generated for prep phases (`docs/plans/tasks/{plan-name}-phase0-completion.md` when present, since prep tasks live in Phase 0). Prep task files for other plans are out of scope โ€” this recipe deletes only what it created for the current run. Their work is committed; `docs/plans/` is ephemeral working state and is not retained between recipe runs. The work plan itself is preserved for the downstream recipe-*-build / recipe-*-implement. +2. **Present Readiness Report**: Present the Readiness Report (see Output Format below) to the user. The report is shown in-session and is not written into the work plan โ€” the durable output is the committed readiness fixes. -4. **Exit**: +3. **Exit**: | Re-scan result | Action | |----------------|--------| @@ -164,8 +163,8 @@ Gaps resolved: [N] | R4 | ... | ... | | R5 | ... | ... | -### Resolution Tasks Executed (when gaps_resolved > 0) -- [task file path] โ€” [one-line summary] โ€” committed +### Resolution Items Executed (when gaps_resolved > 0) +- [criterion ID] โ€” [one-line summary] โ€” committed - ... ### Remaining Gaps (when outcome is escalated) @@ -176,7 +175,6 @@ Gaps resolved: [N] - [ ] Work plan loaded and Verification Strategy / E2E references / Phase structure extracted - [ ] Readiness scan run with per-criterion result and evidence recorded -- [ ] No-op exit when all `pass`, OR resolution tasks generated, approved, and executed via the 4-step cycle -- [ ] Re-scan run after the last resolution task commits -- [ ] Prep task files (and Phase 0 phase-completion file when generated) deleted from `docs/plans/tasks/` +- [ ] No-op exit when all `pass`, OR resolution items planned, approved, and executed via the 4-step cycle +- [ ] Re-scan run after the last resolution item commits - [ ] Final report presented to the user diff --git a/skills/recipe-reverse-engineer/SKILL.md b/skills/recipe-reverse-engineer/SKILL.md index de1ddcc..1980ca7 100644 --- a/skills/recipe-reverse-engineer/SKILL.md +++ b/skills/recipe-reverse-engineer/SKILL.md @@ -5,6 +5,7 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. **Context**: Reverse engineering workflow to create documentation from existing code @@ -14,10 +15,15 @@ Target: $ARGUMENTS **Core Identity**: "I am an orchestrator." +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. + +**Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression; include declined IDs with governing reasons and evidence in the final user report. +Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. + **Execution Protocol**: -1. **Delegate all work through Agent tool** โ€” invoke sub-agents, pass deliverable paths between them, and report results (permitted tools: see subagents-orchestration-guide "Orchestrator's Permitted Tools") +1. **Invoke named specialists for deliverable production** โ€” pass deliverable paths between them and validate their results (see subagents-orchestration-guide "Orchestrator Execution Boundary") 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 +3. **Preserve evidence while bridging outputs** โ€” extract and transform the fields required by the next specialist without changing supported meaning; apply Review Resolution before routing any correction **Task Registration**: Register phases first using TaskCreate, then steps within each phase as you enter it. Update status using TaskUpdate. @@ -163,10 +169,7 @@ prompt: | #### Step 5: Revision (conditional) -**Trigger Conditions** (any one of the following): -- Review status is "Needs Revision" or "Rejected" -- Critical discrepancies exist in `$STEP_3_OUTPUT` -- consistencyScore < 70 +Pass `$STEP_3_OUTPUT` to document-reviewer as verification evidence, then apply the Review Resolution Gate to `$STEP_4_OUTPUT`. Run revision only when at least one finding is `apply`; a decline-only result completes the review, and unresolved `user_decision_required` stops for user input. **Agent tool invocation**: ``` @@ -178,21 +181,17 @@ prompt: | Operation Mode: update Existing PRD: $STEP_2_OUTPUT - ## Review Feedback - $STEP_4_OUTPUT + ## Adjudicated Findings + [apply findings with IDs, governing basis, smallest correction, and affected sections] - ## Code Verification Results - $STEP_3_OUTPUT - - Address discrepancies by severity. Critical and major items require correction. - Minor items: correct if straightforward, otherwise leave as-is with rationale. + Treat these findings as the complete revision scope and preserve adjacent content. ``` -**Loop Control**: Maximum 2 revision cycles. After 2 cycles, flag for human review regardless of status. +**Re-validation**: After each revision, re-run code-verifier on the revised document, then re-run document-reviewer with the latest `code_verification` and `prior_feedback`. #### Unit Completion -- [ ] Review status is "Approved" or "Approved with Conditions" +- [ ] No `apply` findings remain; every other review finding has a disposition and every `user_decision_required` item has a recorded user decision - [ ] Human review passed (if enabled in Step 0) **Next**: Proceed to next unit. After all units โ†’ Phase 2. @@ -361,10 +360,7 @@ prompt: | #### Step 10: Revision (conditional) -**Trigger Conditions** (same as Step 5): -- Review status is "Needs Revision" or "Rejected" -- Critical discrepancies exist in `$STEP_8_OUTPUT` -- consistencyScore < 70 +Pass `$STEP_8_OUTPUT` to document-reviewer as verification evidence, then apply the Review Resolution Gate to `$STEP_9_OUTPUT`. Run revision only when at least one finding is `apply`; a decline-only result completes the review, and unresolved `user_decision_required` stops for user input. **Agent tool invocation (per Design Doc)**: ``` @@ -376,21 +372,17 @@ prompt: | Operation Mode: update Existing Design Doc: $STEP_7_OUTPUT (or $STEP_7a_OUTPUT / $STEP_7b_OUTPUT) - ## Review Feedback - $STEP_9_OUTPUT - - ## Code Verification Results - $STEP_8_OUTPUT + ## Adjudicated Findings + [apply findings with IDs, governing basis, smallest correction, and affected sections] - Address discrepancies by severity. Critical and major items require correction. - Minor items: correct if straightforward, otherwise leave as-is with rationale. + Treat these findings as the complete revision scope and preserve adjacent content. ``` -**Loop Control**: Maximum 2 revision cycles. After 2 cycles, flag for human review regardless of status. +**Re-validation**: After each revision, re-run code-verifier on the revised document, then re-run document-reviewer with the latest `code_verification` and `prior_feedback`. #### Unit Completion -- [ ] Review status is "Approved" or "Approved with Conditions" +- [ ] No `apply` findings remain; every other review finding has a disposition and every `user_decision_required` item has a recorded user decision - [ ] Human review passed (if enabled in Step 0) **Next**: Proceed to next unit. After all units โ†’ Final Report. @@ -409,4 +401,3 @@ Output summary including: | Discovery finds nothing | Ask user for project structure hints | | Generation fails | Log failure, continue with other units, report in summary | | consistencyScore < 50 | Flag for mandatory human review โ€” require explicit human approval | -| Review rejects after 2 revisions | Stop loop, flag for human intervention | diff --git a/skills/recipe-review/SKILL.md b/skills/recipe-review/SKILL.md index 939d39d..8fff7da 100644 --- a/skills/recipe-review/SKILL.md +++ b/skills/recipe-review/SKILL.md @@ -5,6 +5,7 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. **Context**: Post-implementation quality assurance @@ -12,7 +13,12 @@ Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or g **Core Identity**: "I am an orchestrator." -**First Action**: Register Steps 1-11 using TaskCreate before any execution. +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. + +**Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression; include declined IDs with governing reasons and evidence in the final user report. +Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. + +**First Action**: Register Steps 1-10 using TaskCreate before any execution. ## Execution Method @@ -56,17 +62,9 @@ Invoke security-reviewer using Agent tool: **If security-reviewer returned `blocked`**: Stop immediately. Report the blocked finding and escalate to user. Do not proceed to fix steps. -**Code compliance criteria (considering project stage)**: -- Prototype: Pass at 70%+ -- Production: 90%+ recommended - -**Security criteria**: -- `approved` or `approved_with_notes` โ†’ Pass -- `needs_revision` โ†’ Fail +Apply the Review Resolution Gate to both outputs before reporting or routing them. Finding dispositions determine routing; compliance percentages remain diagnostic. -**Report both results independently using subagent output fields only**: - -Before presenting to the user, the orchestrator computes a recommended route per finding using the rule below (this rule is internal โ€” do not include it in the user-facing prompt): +For each `apply` or `user_decision_required` finding, compute a proposed route using the rule below: | Finding pattern | Recommended route | |-----------------|-------------------| @@ -74,7 +72,7 @@ Before presenting to the user, the orchestrator computes a recommended route per | `dd_violation` where the code drifted from a still-correct Design Doc | `c` (Code-side fix) | | `reliability` / `security` / `maintainability` findings | `c` (Code-side fix) | -Then present to the user (label each finding with its recommended route, grouped by route): +Then present the adjudicated result to the user. Group `apply` and `user_decision_required` findings by proposed route, and list declined IDs with their reasons separately: ``` Code Compliance: [complianceRate from code-reviewer] @@ -97,23 +95,19 @@ Security Review: [status from security-reviewer] - [policy] [location]: [description] โ€” [rationale] [recommended: c] Notes: [notes from security-reviewer, if present] -Resolve discrepancies โ€” confirm or override the recommended route per finding: +Approve the proposed changes or decide unresolved items: c) Code-side fix โ€” code violates Design Doc; modify code to match d) Design-side update โ€” code is correct; Design Doc is stale, revise it - s) Skip โ€” accept current state without changes + s) Decline โ€” record the governing reason and accept current state ``` -Use AskUserQuestion. The default offer is **"accept all recommended routes"** โ€” a single confirmation for the typical case where the orchestrator's recommendations are correct. When the user wants to override, collect per-finding c/d/s decisions instead. If the user selects `s` for everything: skip Steps 5-10, proceed to Step 11. +This review command authorizes analysis; use AskUserQuestion to obtain separate implementation authority. The batch option is **"approve all proposed `apply` routes"** and its scope consists exclusively of those routes. Collect an explicit decision for each `user_decision_required` item. When the approved change set is empty, proceed directly to Step 10. Pass approved findings, routes, covered files/sections, and any stated total size budget to update or fix agents. Before re-validation, map every diff hunk to an approved finding or required consistency update; request a scope decision for unmapped or over-budget changes. -### Step 5: Execute Skill - -Execute Skill: documentation-criteria (for task file template) - -### Step 5d: Design-Side Update +### Step 5: Design-Side Update -Run this step only when the user routed at least one finding to `d`. When all routes are `c` or `s`, skip directly to Step 6. +Run this step only when the user routed at least one finding to `d`. When no `d` routes exist, skip it; continue to Step 6 only when approved `c` routes remain. 1. Invoke technical-designer in update mode using Agent tool: - `subagent_type`: "dev-workflows:technical-designer" @@ -124,6 +118,7 @@ Run this step only when the user routed at least one finding to `d`. When all ro - `subagent_type`: "dev-workflows:document-reviewer" - `description`: "Document review of updated Design Doc" - `prompt`: "Review updated Design Doc at [path] for consistency and completeness. doc_type: DesignDoc. review_context: update." + - Apply the Review Resolution Gate to this result. Route `apply` findings back to technical-designer and re-run document-reviewer with `prior_feedback`; stop for unresolved `user_decision_required`; proceed when the result is approved or every actionable finding is `decline`. 3. When multiple Design Docs exist (`ls docs/design/*.md | grep -v template | wc -l > 1`), invoke design-sync: - `subagent_type`: "dev-workflows:design-sync" @@ -131,53 +126,44 @@ Run this step only when the user routed at least one finding to `d`. When all ro - `prompt`: "source_design: [updated DD path]. Detect conflicts across all Design Docs after the update." - When `sync_status: conflicts_found`: present conflicts to the user; resolution requires re-invoking technical-designer for affected DDs. -4. After Step 5d completes: - - If the user selected `d` for all findings (no `c` routes) โ†’ skip Steps 6-8, proceed to Step 9 for re-validation +4. After Step 5 completes: + - If the user selected `d` for all findings (no `c` routes) โ†’ skip Steps 6-7, proceed to Step 8 for re-validation - If the user selected both `d` and `c` โ†’ re-evaluate the `c`-routed findings against the updated DD and drop any that are now satisfied by the DD revision; then proceed to Step 6 with the remaining `c` findings -### Step 6: Create Task File - -Create task file at `docs/plans/tasks/review-fixes-YYYYMMDD.md` -Include both code compliance issues and security requiredFixes. - -### Step 7: Execute Fixes +### Step 6: Execute Fixes Invoke task-executor using Agent tool: - `subagent_type`: "dev-workflows:task-executor" - `description`: "Execute review fixes" -- `prompt`: "Task file: docs/plans/tasks/review-fixes-YYYYMMDD.md. Apply staged fixes (stops at 5 files)." +- `prompt`: "Apply these approved code-side findings directly: [findings with IDs, governing sources, smallest correction, affected paths, and observable verification condition]. Keep the change within the approved routes and stated total size budget." -### Step 8: Quality Check +### Step 7: Quality Check Invoke quality-fixer using Agent tool: - `subagent_type`: "dev-workflows:quality-fixer" - `description`: "Quality gate check" -- Pass Step 7 `mutationEvidence` and `qualityCommand` when available (caller first, otherwise current task). +- Pass Step 6 `filesModified` and `mutationEvidence`. - `prompt`: "Confirm quality gate passage for fixed files." -### Step 9: Re-validate code-reviewer +### Step 8: Re-validate code-reviewer Invoke code-reviewer using Agent tool: - `subagent_type`: "dev-workflows:code-reviewer" - `description`: "Re-validate compliance" -- `prompt`: "Re-validate Design Doc compliance after fixes. Prior compliance issues: $STEP_2_OUTPUT. Verify each prior issue is resolved (whether resolved code-side or design-side)." +- `prompt`: "Re-validate Design Doc compliance after fixes. Design Doc: [path]. Implementation files: [file list]. prior_feedback: [{id, disposition, correction?, reason?, evidence}]. Review the current state normally, then reconcile every prior item." -### Step 10: Re-validate security-reviewer +### Step 9: Re-validate security-reviewer Invoke security-reviewer using Agent tool (only if security fixes were applied): - `subagent_type`: "dev-workflows:security-reviewer" - `description`: "Re-validate security" -- `prompt`: "Re-validate security after fixes. governingDocuments: [{\"type\":\"design-doc\",\"path\":\"[path]\"}]. implementationFiles: [file list]. Prior findings: $STEP_3_OUTPUT." - -### Step 11: Final Cleanup and Report +- `prompt`: "Re-validate security after fixes. governingDocuments: [{\"type\":\"design-doc\",\"path\":\"[path]\"}]. implementationFiles: [file list]. prior_feedback: [{id, disposition, correction?, reason?, evidence}]. Review the current state normally, then reconcile every prior item." -Delete the review-fix task file this recipe created (if any). Its work is committed; `docs/plans/` is ephemeral working state and is not retained between recipe runs: +Apply the Review Resolution Gate to every Step 8 and Step 9 result before Step 10. Route new `apply` findings through their approved design-side or code-side path and repeat the affected verification; stop for unresolved `user_decision_required`; proceed when each result is approved or every actionable finding is `decline`. -- Delete `docs/plans/tasks/review-fixes-YYYYMMDD.md` if it exists +### Step 10: Final Report -If the file cannot be deleted (filesystem error), report the failure but do not block the final report. - -Then present the final report: +Present the final report: ``` Code Compliance: @@ -191,8 +177,6 @@ Security Review: Remaining issues: - [items requiring manual intervention] - -Cleanup: review-fixes task file removed ``` ## Auto-fixable Items (code-side path) diff --git a/skills/recipe-task/SKILL.md b/skills/recipe-task/SKILL.md index 322e3a3..24d0e49 100644 --- a/skills/recipe-task/SKILL.md +++ b/skills/recipe-task/SKILL.md @@ -5,6 +5,7 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. # Task Execution with Metacognitive Analysis diff --git a/skills/recipe-update-doc/SKILL.md b/skills/recipe-update-doc/SKILL.md index 6bdeb54..73c3256 100644 --- a/skills/recipe-update-doc/SKILL.md +++ b/skills/recipe-update-doc/SKILL.md @@ -5,6 +5,7 @@ disable-model-invocation: true --- Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. +Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. **Context**: Dedicated to updating existing design documents. @@ -12,10 +13,15 @@ Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or g **Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) +**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. + +**Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression; include declined IDs with governing reasons and evidence in the final user report. +Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. + **First Action**: Register Steps 1-6 using TaskCreate before any execution. **Execution Protocol**: -1. **Delegate all work through Agent tool** โ€” invoke sub-agents, pass deliverable paths between them, and report results (permitted tools: see subagents-orchestration-guide "Orchestrator's Permitted Tools") +1. **Invoke named specialists for deliverable production** โ€” pass deliverable paths between them and validate their results (see subagents-orchestration-guide "Orchestrator Execution Boundary") 2. **Execute update flow**: - Identify target โ†’ Clarify changes โ†’ Update document โ†’ Review โ†’ Consistency check - **Stop at every `[Stop: ...]` marker** โ†’ Wait for user approval before proceeding @@ -157,7 +163,7 @@ prompt: | **On review result**: - Approved โ†’ Proceed to Step 6 -- Needs revision โ†’ Return to Step 4 with the following prompt (max 2 iterations): +- Needs revision โ†’ Apply the Review Resolution Gate. Return to Step 4 when `apply` findings exist, using the following prompt: ``` subagent_type: [Update Agent from Step 2] description: "Revise [Type from Step 2]" @@ -165,12 +171,13 @@ prompt: | Operation Mode: update Existing Document: [path from Step 1] - ## Review Feedback to Address - $STEP_5_OUTPUT + ## Adjudicated Review Findings + [apply findings with IDs, basis, smallest correction, and affected sections] - Address each issue raised in the review feedback. + Treat these findings as the complete revision scope and preserve adjacent content. ``` -- **After 2 rejections** โ†’ Flag for human review, present accumulated feedback to user and end +- On re-review pass `prior_feedback` as `[{id, disposition, correction?, reason?, evidence}]` +- All actionable findings are `decline` and every `user_decision_required` item is resolved โ†’ Proceed to Step 6 Present review result to user for approval. @@ -200,7 +207,6 @@ prompt: | |-------|--------| | Target document not found | Report and end (document creation is out of scope) | | Sub-agent update fails | Log failure, present error to user, retry once | -| Review rejects after 2 revisions | Stop loop, flag for human intervention | | design-sync detects conflicts | Present to user for resolution decision | ## Completion Criteria diff --git a/skills/requirement-convergence/SKILL.md b/skills/requirement-convergence/SKILL.md index bcb8092..0c3ec2f 100644 --- a/skills/requirement-convergence/SKILL.md +++ b/skills/requirement-convergence/SKILL.md @@ -28,7 +28,7 @@ Judgment rules per field: [references/criteria.md](references/criteria.md). ## Hearing Protocol -Eliciting requires user interaction, so the orchestrator owns it. It runs after the analysis that produced the scope facts, because the orchestrator investigates nothing itself. +Eliciting and judging the convergence fields require user interaction, so the orchestrator owns them. The hearing runs after the specialist analysis that produced the scope facts; production of that investigation output remains with the specialist. Register these steps before starting and record each step's evidence as it completes: diff --git a/skills/subagents-orchestration-guide/SKILL.md b/skills/subagents-orchestration-guide/SKILL.md index 8393731..4aef64f 100644 --- a/skills/subagents-orchestration-guide/SKILL.md +++ b/skills/subagents-orchestration-guide/SKILL.md @@ -7,27 +7,28 @@ description: Guides subagent coordination through implementation workflows. Use ## Role: The Orchestrator -All investigation, analysis, and implementation work flows through specialized subagents. +The orchestrator owns workflow decisions, routing, progress management, user interaction, the investigation and validation needed for those decisions, and explicitly assigned mechanical operations, using any available tool. Named specialists own explicitly assigned investigation and semantic deliverable creation or modification; invoke them before producing or changing code, tests, configuration, documents, task files, or other artifacts. ### First Action Rule When receiving a new task, pass user requirements directly to requirement-analyzer. Determine the workflow based on its scale assessment result. -requirement-analyzer returns a `convergence` object. Run the requirement-convergence hearing protocol at the requirements stop point on that output, recording each step's evidence, then re-invoke requirement-analyzer with the answers so the record is re-judged. The hearing runs in the orchestrator because it requires user interaction, and runs after the analysis because the orchestrator investigates nothing itself. +requirement-analyzer returns a `convergence` object. Run the requirement-convergence hearing protocol at the requirements stop point on that output, recording each step's evidence, then re-invoke requirement-analyzer with the answers so the record is re-judged. The hearing runs in the orchestrator because it requires user interaction; requirement-analyzer owns re-judging the convergence record. ### Requirement Change Detection During Flow -**During flow execution**, monitor user responses for scope-expanding signals: -- Mentions of new features/behaviors (additional operation methods, display on different screens, etc.) -- Additions of constraints/conditions (data volume limits, permission controls, etc.) -- Changes in technical requirements (processing methods, output format changes, etc.) - -**When any signal is detected โ†’ Re-run requirement-analyzer with integrated requirements, identify which approved artifacts or task boundaries the change invalidates, and resume from the earliest invalidated gate. Preserve earlier outputs that remain valid.** +Treat new or changed behaviors, constraints, or technical requirements as requirement changes. Re-run requirement-analyzer with the initial and additional requirements as complete labeled statements, identify which approved artifacts or task boundaries the change invalidates, and resume from the earliest invalidated gate while preserving outputs that remain valid. ## Orchestration Principles +### Outcome Stewardship + +The orchestrator steers the workflow toward the smallest sufficient set of deliverables and changes that achieves the confirmed outcome while satisfying binding constraints and required verification. Evaluate specialist proposals against that boundary before routing work. + ### Delegation Boundary: What vs How +Before assigning repository work, inspect the current state needed to identify **what to accomplish** and **where to work**; pass unresolved questions as explicit investigation scope. + The orchestrator passes **what to accomplish** and **where to work**. Each specialist determines **how to execute** autonomously. **Pass to specialists** (what/where/constraints): @@ -40,35 +41,28 @@ The orchestrator passes **what to accomplish** and **where to work**. Each speci - Execution order and tool flags - Which files to inspect or modify within the given scope -| | Bad (orchestrator prescribes how) | Good (orchestrator passes what) | -|---|---|---| -| quality-fixer | "Run these checks: 1. lint 2. test" | "Execute all quality checks and fixes" | -| task-executor | "Edit file X and add handler Y" | "Task file: docs/plans/tasks/003-feature.md" | - -**Decision precedence when outputs conflict**: +**Decision precedence for routing**: 1. User instructions (explicit requests or constraints) 2. Task files and design artifacts (Design Doc, PRD, work plan) 3. Objective repo state (git status, file system, project configuration) 4. Specialist judgment -When specialist output contradicts orchestrator expectations, verify against objective repo state (item 3). If repo state confirms the specialist, follow the specialist. Override specialist output only when it conflicts with items 1 or 2. +Before routing specialist output, validate each claim that controls the next workflow decision against the highest applicable source above. Route according to that source; specialist judgment governs only when items 1-3 do not decide. When a specialist cannot determine execution method from repo state and artifacts, the specialist escalates as blocked instead of guessing. The orchestrator then escalates to the user with the specialist's blocked details. -### Task Assignment with Responsibility Separation +### Review Resolution + +Apply `references/review-resolution.md` to actionable deliverable-review findings. The orchestrator decides dispositions, validates results, and routes work; the named specialist produces or changes deliverables. -Assign work based on each subagent's responsibilities: +### Task Assignment with Responsibility Separation -**What to delegate to task-executor**: -- Implementation work and test addition -- Confirmation of added tests passing (existing tests are not covered) -- Delegate quality assurance exclusively to quality-fixer (or quality-fixer-frontend for frontend tasks) +| Specialist | Responsibility | +|---|---| +| task-executor | Implement scoped work and tests, and confirm added tests pass; leave whole-repository quality assurance to the quality-fixer. | +| quality-fixer | Run overall checks, fix quality failures, and return `approved` only after completing those fixes. | -**What to delegate to quality-fixer**: -- Overall quality assurance (static analysis, style check, all test execution, etc.) -- Complete execution of quality error fixes -- Self-contained processing until fix completion -- Final approved judgment (only after fixes are complete) +For frontend work, substitute task-executor-frontend and quality-fixer-frontend; in fullstack work, select them by task layer. ## Constraints Between Subagents @@ -79,6 +73,8 @@ Assign work based on each subagent's responsibilities: Autonomous execution MUST stop and wait for user input at these points. **Use AskUserQuestion to present confirmations and questions.** +Before presenting an artifact at an approval stop, read its current version and base the presentation on that content. + | Phase | Stop Point | User Action Required | |-------|------------|---------------------| | Requirements | After requirement-analyzer completes | Answer the requirement-convergence hearing, then confirm requirements | @@ -111,19 +107,9 @@ Each subagent invocation is a **fresh Agent tool** call, isolating each phase's - `description`: Concise task description (3-5 words) - `prompt`: Specific instructions including deliverable paths -### Orchestrator's Permitted Tools - -The orchestrator coordinates work using only the following tools: +### Orchestrator Execution Boundary -| Tool | Purpose | -|------|---------| -| Agent | Invoke subagents | -| AskUserQuestion | User confirmations and questions | -| TaskCreate / TaskUpdate | Progress tracking | -| Bash | Shell operations (git commit, ls, verification commands) | -| Read | Deliverable documents for information bridging between subagents | - -All implementation work (Edit, Write, MultiEdit) is performed by subagents, not the orchestrator. +Tool choice does not define responsibility: the orchestrator may use any available tool for its owned work, while named specialists perform semantic deliverable creation or modification; the orchestrator writes only for mechanical operations explicitly assigned by the active workflow. ### Prompt Construction Rule Every subagent prompt must include: @@ -134,40 +120,26 @@ Construct the prompt from the agent's Input Parameters section and the deliverab Two additional rules: - Subagents see only the Agent prompt and files they read. Include required paths, prior JSON, parameters, and scope constraints explicitly. -- Replace every `[placeholder]` in examples below with concrete values before invoking the Agent tool. - -### Call Example (requirement-analyzer) -- subagent_type: "requirement-analyzer" -- description: "Requirement analysis" -- prompt: "Requirements: [user requirements]. Context: [any relevant context]. Perform requirement analysis and scale determination." -- On re-invocation after the convergence hearing, append: "Hearing answers: [the user's answers per convergence field]. Re-judge the convergence record with these answers." - -### Call Example (codebase-analyzer) -- subagent_type: "codebase-analyzer" -- description: "Codebase analysis" -- prompt: "requirement_analysis: [JSON from requirement-analyzer]. prd_path: [path if exists]. requirements: [original user requirements]. Analyze the existing codebase and produce design guidance." +- Resolve every placeholder in workflow prompt templates before invoking the Agent tool. -### Call Example (ui-analyzer) -- subagent_type: "ui-analyzer" -- description: "UI fact gathering" -- prompt: "requirement_analysis: [JSON from requirement-analyzer]. requirements: [original user requirements]. ui_spec_path: [path if exists]. target_components: [list if focused]. Read docs/project-context/external-resources.md, fetch external UI sources via the declared access methods (MCP / URL / file), and analyze the existing UI codebase. Output the consolidated UI fact JSON." +### Agent-Specific Prompt Content -When invoked alongside codebase-analyzer for frontend or fullstack-frontend work, run both agents in parallel and pass both JSON outputs to consumers (ui-spec-designer for the design phase; technical-designer-frontend for the Design Doc phase). - -### Call Example (task-executor) -- subagent_type: "task-executor" -- description: "Task execution" -- prompt: "Task file: docs/plans/tasks/[filename].md Please complete the implementation" +| Specialist | Required prompt content | +|---|---| +| requirement-analyzer | User requirements and relevant context; on re-invocation, add the hearing answers per `convergence` field and request re-judgment. | +| codebase-analyzer | `requirement_analysis`, optional `prd_path`, and original requirements. | +| ui-analyzer | `requirement_analysis`, original requirements, optional UI Spec and target components, plus the external-resource context path and declared access methods. Run it in parallel with codebase-analyzer for frontend work; pass both outputs to ui-spec-designer for the UI Spec phase and technical-designer-frontend for the Design Doc phase. | +| task-executor | The task file path when one exists; otherwise the direct scope, governing sources, target paths, and observable verification condition. | ## Structured Response Specification Subagents respond in JSON format. Key fields for orchestrator decisions: - **requirement-analyzer**: scale, confidence, affectedLayers, adrRequired, scopeDependencies, questions, convergence (fields with readiness labels; a field below `ready` returns as a `convergence` question) -- **codebase-analyzer**: analysisScope.categoriesDetected, dataModel.detected, qualityAssurance (mechanisms[], domainConstraints[]), focusAreas[], existingElements count, limitations -- **ui-analyzer**: analysisScope.uiConventions, externalResources (designOrigin/designSystem/guidelines/visualVerification with fetch_status), componentStructure[], propsPatterns[], cssLayout[], stateDisplay[], displayConditions[], i18n, accessibility[], generatedArtifacts[], focusAreas[] (raw fact_id; consumers apply `ui:` prefix when merging with codebase analysis facts), candidateWriteSet[] (with confidence labels), limitations +- **codebase-analyzer**: pass its full JSON unchanged; HC-02 defines the fields consumed downstream +- **ui-analyzer**: pass its full JSON unchanged with raw `fact_id` values; the consumer applies the `ui:` prefix when merging with codebase facts - **code-verifier**: `summary.status` (consistent/mostly_consistent/needs_review/inconsistent/blocked), `summary.consistencyScore`, discrepancies[], reverseCoverage (including dataOperationsInCode, testBoundariesSectionPresent). Pre-implementation: verifies Design Doc claims against existing codebase. Post-implementation: verifies implementation consistency against the governing Design Doc or Work Plan (pass `code_paths` scoped to changed files) -- **task-executor**: status (escalation_needed/completed), escalation_type (design_compliance_violation/similar_function_found/investigation_target_not_found/out_of_scope_file/dependency_version_uncertain/binding_decision_violation/test_environment_not_ready), testsAdded, requiresTestReview -- **quality-fixer**: Input: `task_file` (path to current task file โ€” always pass this in orchestrated flows). Status: approved/stub_detected/blocked. `stub_detected` โ†’ route back to task-executor with `incompleteImplementations[]` details for completion, then re-run quality-fixer. `blocked` โ†’ discriminate by `reason` field: `"Cannot determine due to unclear specification"` โ†’ read `blockingIssues[]` for specification details; `"Execution prerequisites not met"` โ†’ read `missingPrerequisites[]` with `resolutionSteps` โ€” present these to the user as actionable next steps +- **task-executor**: status (escalation_needed/completed), escalation_type (design_compliance_violation/similar_function_found/investigation_target_not_found/out_of_scope_file/dependency_version_uncertain/binding_decision_violation/test_environment_not_ready), changeSummary, testsAdded, requiresTestReview +- **quality-fixer**: Input: optional `task_file`, plus the executor's `filesModified` and `mutationEvidence`; pass `qualityCommand` only when the caller or task supplies one. Status: approved/stub_detected/blocked. `stub_detected` โ†’ route back to task-executor with `incompleteImplementations[]` details for completion, then re-run quality-fixer. `blocked` โ†’ discriminate by `reason` field: `"Cannot determine due to unclear specification"` โ†’ read `blockingIssues[]` for specification details; `"Execution prerequisites not met"` โ†’ read `missingPrerequisites[]` with `resolutionSteps` โ€” present these to the user as actionable next steps - **document-reviewer**: `verdict.decision` (approved/approved_with_conditions/needs_revision/rejected) - **design-sync**: sync_status (synced/conflicts_found) - **integration-test-reviewer**: Input: `changedTestFiles[]`, `diffBase`, optional review-basis inputs, and `mutationEvidence`. Output: status (`approved`/`needs_revision`/`blocked`), `reviewBasis`, requiredFixes @@ -176,114 +148,57 @@ Subagents respond in JSON format. Key fields for orchestrator decisions: ## Handling Requirement Changes -### Handling Requirement Changes in requirement-analyzer -requirement-analyzer follows the "completely self-contained" principle and processes requirement changes as new input. - -#### How to Integrate Requirements +Use create mode for initial documents. For requirement-driven revisions, invoke the owning document specialist in `update` mode and add history: -**Important**: To maximize accuracy, integrate requirements as complete sentences, including all contextual information communicated by the user. Result format: raw concatenation of all requirements, followed by a labeled summary (`Initial requirement: โ€ฆ` / `Additional requirement: โ€ฆ`). - -### Update Mode for Document Generation Agents -Document generation agents (work-planner, technical-designer, prd-creator) can update existing documents in `update` mode. - -- **Initial creation**: Create new document in create (default) mode -- **On requirement change**: Edit existing document and add history in update mode - -Criteria for timing when to call each agent: -- **work-planner**: Request updates only before execution -- **technical-designer**: Request updates according to design changes โ†’ Execute document-reviewer for consistency check -- **prd-creator**: Request updates according to requirement changes โ†’ Execute document-reviewer for consistency check -- **document-reviewer**: Always execute before user approval after PRD/ADR/Design Doc creation/update, and after Work Plan creation/update at Medium/Large scale (Small uses a simplified plan with no semantic review โ€” no Design Doc to trace against) +- **work-planner**: update only before execution +- **technical-designer / prd-creator**: update affected documents, then invoke document-reviewer +- **document-reviewer**: run before user approval after PRD/ADR/Design Doc changes and after Medium/Large Work Plan changes; Small plans require no semantic review ## Basic Flow: Planning and Implementation -Always start with requirement-analyzer, hold the requirement-convergence hearing on its output, then select the minimum planning flow required by scale and affected layers. - ### Planning flow (per scale) | Scale | Planning flow (ends at task-decomposer for Medium/Large; ends at work-planner for Small) | |-------|---------------| -| Large | requirement-analyzer โ†’ PRD โ†’ PRD review โ†’ external resource hearing โ†’ optional ADR โ†’ codebase-analyzer (+ ui-analyzer in parallel for frontend/fullstack) โ†’ optional UI Spec โ†’ Design Doc โ†’ code-verifier โ†’ document-reviewer โ†’ design-sync โ†’ acceptance-test-generator โ†’ work-planner โ†’ work plan review (document-reviewer, doc_type WorkPlan) โ†’ task-decomposer | +| Large | requirement-analyzer โ†’ PRD โ†’ PRD review โ†’ external resource hearing โ†’ codebase-analyzer (+ ui-analyzer in parallel for frontend/fullstack) โ†’ optional UI Spec โ†’ optional ADR โ†’ Design Doc โ†’ code-verifier โ†’ document-reviewer โ†’ design-sync โ†’ acceptance-test-generator โ†’ work-planner โ†’ work plan review (document-reviewer, doc_type WorkPlan) โ†’ task-decomposer | | Medium | requirement-analyzer โ†’ external resource hearing โ†’ codebase-analyzer (+ ui-analyzer in parallel for frontend/fullstack) โ†’ optional UI Spec โ†’ optional ADR โ†’ Design Doc โ†’ code-verifier โ†’ document-reviewer โ†’ design-sync โ†’ acceptance-test-generator โ†’ work-planner โ†’ work plan review (document-reviewer, doc_type WorkPlan) โ†’ task-decomposer | | Small | requirement-analyzer โ†’ work-planner | -The requirement-convergence hearing follows requirement-analyzer in every flow. Both it and the external resource hearing run in the orchestrator (they require AskUserQuestion). ui-analyzer joins codebase-analyzer in parallel only when the work has a frontend surface; for backend-only work the planning flow uses codebase-analyzer alone. +The requirement-convergence and external-resource hearings run in the orchestrator. Run ui-analyzer and codebase-analyzer in parallel only for frontend surfaces. -After the planning flow completes and the user grants batch approval, implementation proceeds. Verifying the plan is implementable end-to-end (verification lanes, fixtures, E2E environment) is an optional preflight the user runs at their discretion via the recipe-prepare-implementation recipe; this guide does not invoke any orchestrator above the agent layer. - -Then execute the task execution cycle: `task-executor โ†’ quality-fixer โ†’ commit` for each task. See "Autonomous Execution Mode" below for full per-task details. At Small scale this cycle still applies โ€” implementation runs through `task-executor`, not orchestrator-direct edits. - -Each agent name in the chain is invoked via the Agent tool (per "Orchestrator's Permitted Tools" above). +After batch approval, enter the autonomous cycle below. Small-scale implementation also runs through task-executor. Rules: -- Large scale requires PRD before Design Doc creation -- Frontend/fullstack flows add UI Spec before Design Doc creation +- Frontend/fullstack flows that produce a Design Doc complete the UI Spec first; ADR-only flows skip the UI Spec - Fullstack layer sequencing is defined only in `references/monorepo-flow.md` - `design-sync` is required whenever multiple Design Docs exist - `task-decomposer` begins only after work plan review (document-reviewer, doc_type WorkPlan; Medium/Large) and batch approval -- Work plan review self-heals: on `verdict.decision` `needs_revision`, route back to work-planner (update) and re-review until `approved`/`approved_with_conditions`; `rejected` escalates to the user. If re-review returns the same blocking finding and the update adds no new evidence or contract change, stop the loop and escalate that finding. The work plan is a derivation of the Design Doc, so plan-fidelity findings need no user adjudication while the loop is making observable progress +- Work plan review applies Review Resolution: revise and re-review with `prior_feedback` for `apply`; proceed when all actionable findings are `decline`; escalate unresolved `user_decision_required` or unusable inputs ## Autonomous Execution Mode -### Pre-Execution Environment Check - -**Principle**: Verify subagents can complete their responsibilities - -**Required environments**: -- Commit capability (for per-task commit cycle) -- Quality check tools (quality-fixer will detect and escalate if missing) -- Test runner (task-executor will detect and escalate if missing) - -**If critical environment unavailable**: Escalate with specific missing component before entering autonomous mode -**If detectable by subagent**: Proceed (subagent will escalate with detailed context) +### Pre-Execution Gate -### Authority Delegation +Verify commit capability before autonomous mode. Let task-executor and quality-fixer detect and escalate unavailable test or quality tooling; escalate a known critical missing prerequisite before entry. -**After environment check passes**: -- Batch approval for entire implementation phase delegates authority to subagents -- task-executor: Implementation authority (can use Edit/Write) -- quality-fixer: Fix authority (automatic quality error fixes) +Batch approval authorizes task-executor implementation and quality-fixer corrections until completion or escalation. -### Definition of Autonomous Execution Mode +### Autonomous Execution Summary After "batch approval for entire implementation phase" with work-planner, autonomously execute the following processes without human approval: ```mermaid graph TD - START[Batch approval for entire implementation phase] --> AUTO[Start autonomous execution mode] - AUTO --> TD[task-decomposer: Task materialization] - TD --> LOOP[Task execution loop] - LOOP --> TE[task-executor: Implementation] - TE --> ESCJUDGE{Escalation judgment} - ESCJUDGE -->|escalation_needed/blocked| USERESC[Escalate to user] - ESCJUDGE -->|requiresTestReview: true| ITR[integration-test-reviewer] - ESCJUDGE -->|No issues| QF - ITR -->|needs_revision| TE - ITR -->|approved| QF - ITR -->|blocked| USERESC - QF[quality-fixer: Quality check and fixes] --> QFJUDGE{quality-fixer result} - QFJUDGE -->|stub_detected| TE - QFJUDGE -->|approved| COMMIT[Orchestrator: Execute git commit] - QFJUDGE -->|blocked| USERESC - COMMIT --> CHECK{Any remaining tasks?} - CHECK -->|Yes| LOOP - CHECK -->|No| VERIFY[Post-implementation verification] - VERIFY --> CV[code-verifier: Governing document consistency check] - VERIFY --> SEC[security-reviewer: Security review] - CV --> VRESULT{Verification results} - SEC --> VRESULT - VRESULT -->|All passed| REPORT[Completion report] - VRESULT -->|Any failed| VFIX[task-executor: Verification fixes] - VFIX --> QF2[quality-fixer: Quality check] - QF2 --> REVERIFY[Re-run both verifiers] - REVERIFY --> VRESULT - VRESULT -->|blocked| USERESC - - LOOP --> INTERRUPT{User input?} - INTERRUPT -->|None| TE - INTERRUPT -->|Yes| REQCHECK{Requirement change check} - REQCHECK -->|No change| TE - REQCHECK -->|Change| STOP[Stop autonomous execution] - STOP --> RA[Re-analyze with requirement-analyzer] + START[Batch approval] --> TD[task-decomposer] + TD --> CYCLE[Per-task 4-step cycle, including commit] + CYCLE -->|remaining tasks| CYCLE + CYCLE -->|all tasks complete| VERIFY[code-verifier + security-reviewer] + CYCLE -->|blocked, escalation, or requirement change| USER[Escalate or re-analyze] + VERIFY -->|passed| REPORT[Completion report] + VERIFY -->|actionable findings| RR[Review Resolution] + RR -->|apply| FIX[task-executor + quality-fixer] + FIX --> VERIFY + RR -->|all decline| REPORT + RR -->|user decision required| USER ``` ### Post-Implementation Verification Pass/Fail Criteria @@ -293,118 +208,83 @@ graph TD | code-verifier | `summary.status` is `consistent` or `mostly_consistent` | `summary.status` is `needs_review` or `inconsistent` | `summary.status` is `blocked` โ†’ Escalate to user | | security-reviewer | `status` is `approved` or `approved_with_notes` | `status` is `needs_revision` | `status` is `blocked` โ†’ Escalate to user | -**Fix-cycle handoff**: Consolidate failed verifier findings into one ephemeral task per required executor and pass each exact path as `task_file` through its executor and quality-fixer. Use `review-fixes-{plan-name}-task-*` for single-layer work and `review-fixes-{plan-name}-{backend|frontend}-task-*` for fullstack routing; delete the files after all verifiers pass. +**Fix-cycle handoff**: Apply Review Resolution, then pass each required executor the `apply` findings, affected paths, governing evidence, and verification condition directly. Carry `prior_feedback` to reviewer inputs that support reconciliation. **Re-run rule**: After any post-implementation verification fix cycle, re-run both code-verifier and security-reviewer before accepting the result. ### Conditions for Stopping Autonomous Execution -Stop autonomous execution and escalate to user in the following cases: -1. **Escalation from subagent** - - When receiving response with `status: "escalation_needed"` - - When receiving response with `status: "blocked"` - -2. **When requirement change detected** - - Any match in requirement change detection checklist - - Stop autonomous execution and re-analyze with integrated requirements in requirement-analyzer - - Mark affected PRD/UI Spec/ADR/Design Doc/Work Plan/task outputs invalid and resume from the earliest invalidated approval gate; preserve outputs outside the changed requirement's impact - -3. **When work-planner update restriction is violated** - - Requirement changes after task-decomposer starts require requirement re-analysis and task invalidation - - Restart document design only when the re-analysis shows that an approved requirement, contract, data flow, verification strategy, or task boundary changed - -4. **When user explicitly stops** - - Direct stop instruction or interruption +| Trigger | Action | +|---|---| +| A subagent returns `escalation_needed` or `blocked` | Escalate its concrete details to the user. | +| Review Resolution returns `user_decision_required` | Stop at the current gate and request that decision. | +| A requirement changes | Apply Requirement Change Detection above. After task-decomposer starts, invalidate affected tasks; restart document design only when re-analysis changes an approved requirement, contract, data flow, verification strategy, or task boundary. | +| The user stops or interrupts | Stop autonomous execution. | ### Task Management: 4-Step Cycle **Per-task cycle**: -1. **Execute**: invoke Agent tool (subagent_type: "task-executor") โ†’ Record the current HEAD as `diffBase`, pass the task file path in the prompt, and receive the structured response +1. **Execute**: record the current HEAD as `diffBase`, then invoke task-executor with the task file path when one exists or with the direct scope contract above 2. **Branch on executor result**: - `status: escalation_needed` or `blocked` โ†’ Escalate to user - - `requiresTestReview` is `true` โ†’ Invoke integration-test-reviewer with `diffBase`, changed integration/E2E paths, `taskFile`, prompt-only claims, and `mutationEvidence` - - `needs_revision` โ†’ Return to step 1 with `requiredFixes` + - `requiresTestReview` is `true` โ†’ Invoke integration-test-reviewer with `diffBase`, changed integration/E2E paths, optional `taskFile`, prompt-only claims, and `mutationEvidence` - `approved` โ†’ Proceed to step 3 - `blocked` โ†’ Escalate to user + - `needs_revision` โ†’ Apply Review Resolution + - one or more `apply` findings โ†’ Return to step 1 with those findings, then re-review with `prior_feedback` + - every actionable finding is `decline` โ†’ Proceed to step 3 + - any unresolved `user_decision_required` finding โ†’ Escalate to user - Otherwise โ†’ Proceed to step 3 -3. **Quality-fix**: invoke quality-fixer with `task_file`, upstream `mutationEvidence`, and `qualityCommand` when available (caller first, otherwise current task) +3. **Quality-fix**: invoke quality-fixer with upstream `filesModified` and `mutationEvidence`, plus `task_file` when available and `qualityCommand` from the caller first or task otherwise - `stub_detected` โ†’ Return to step 1 with `incompleteImplementations[]` details - `blocked` โ†’ Escalate to user - `approved` โ†’ Proceed to step 4 -4. **Commit**: execute git commit with Bash after quality-fixer returns `approved` - -### Progress Tracking - -Register overall phases using TaskCreate. Update each phase with TaskUpdate as it completes. - -## Main Orchestrator Roles - -1. **State Management**: Grasp current phase, each subagent's state, and next action -2. **Information Bridging**: Data conversion and transmission between subagents - - Convert each subagent's output to next subagent's input format - - **Always pass deliverables from previous process to next agent** - - Extract necessary information from structured responses - - Compose commit messages from changeSummary - - Explicitly integrate initial and additional requirements when requirements change - - ### Handoff Contracts - - #### HC-01: requirement-analyzer โ†’ codebase-analyzer - - Pass: `requirement_analysis` (including `convergence`), `prd_path` (if exists), original user requirements - - #### HC-01b: convergence record โ†’ document owner - - Pass `convergence` from the last requirement-analyzer invocation (or, in flows without one, the orchestrator's own judged record) to whichever agent owns the persisting document - - **prd-creator** (when a PRD is created or updated): persists `outcome` to `Success Criteria`, and `nonGoals` plus `speculative` requirements to `Future / Out of Scope` with origin `user` - - **technical-designer / technical-designer-frontend**: persists the same to the Design Doc's `Requirement Convergence` when no PRD exists, and always records the fields left `weak-but-explicit` there - - Pass the record unchanged; a field's readiness label travels with it - - #### HC-02: codebase-analyzer โ†’ technical-designer - - Pass: full codebase-analyzer JSON as additional context - - Required downstream uses: - - `focusAreas` โ†’ canonical disposition-target list for the Fact Disposition Table - - `dataModel`, `dataTransformationPipelines`, `qualityAssurance` โ†’ Existing Codebase Analysis / Verification Strategy / Quality Assurance sections - - #### HC-03: technical-designer โ†’ code-verifier - - Pass: Design Doc path (`doc_type: design-doc`) - - Do not pass `code_paths`; code-verifier discovers scope from the document - - #### HC-04: code-verifier + codebase-analyzer โ†’ document-reviewer - - Pass: `review_context: creation`, `code_verification` JSON, the same `codebase_analysis` JSON previously given to the designer, original user requirements as `requirements_verbatim`, and confirmed scope and user decisions as `confirmed_decisions` - - Purpose: reviewer validates discrepancy integration, Fact Disposition coverage against `focusAreas`, and Design Convergence against the effective requirements +4. **Commit**: after quality-fixer returns `approved`, compose the message from `changeSummary` and execute git commit with Bash - #### HC-05: code-verifier โ†’ next-layer technical-designer (fullstack only) - - Defined only for multi-layer fullstack flow in `references/monorepo-flow.md` - - Pass: prior-layer Design Doc path plus `prior_layer_verification` - - Use only `discrepancies[]` as known issues to address or escalate. Do not infer verified claims that are not explicitly present in the verifier output. +Register overall phases using TaskCreate and update each phase with TaskUpdate as it completes. - #### technical-designer โ†’ work-planner +## Handoff Contracts - **Pass to work-planner**: Design Doc path. Work-planner reads the DD template from documentation-criteria skill, scans all DD sections, and extracts technical requirements in these categories: - - **Verification Strategy**: Extracted to work plan header (Correctness Proof Method + Early Verification Point) - - **Implementation targets**: Components, functions, or data structures to create or modify - - **Connection/switching/registration**: Integration points, dependency wiring, switching methods - - **Contract changes and propagation**: Interface changes, data contracts, field propagation across boundaries - - **Verification requirements**: Verification methods, test boundaries, integration verification points - - **Prerequisite work**: Migration steps, security measures, environment setup +### HC-01: requirement-analyzer โ†’ codebase-analyzer +- Pass: `requirement_analysis` (including `convergence`), `prd_path` (if exists), original user requirements - Work-planner produces a Design-to-Plan Traceability table mapping each extracted item to covering task(s). Items without a covering task must be marked as `gap` with justification. Unjustified gaps are errors. Justified gaps require user confirmation before plan approval. +### HC-01b: convergence record โ†’ document owner +- Pass `convergence` from the last requirement-analyzer invocation (or, in flows without one, the orchestrator's own judged record) to whichever agent owns the persisting document +- **prd-creator** (when a PRD is created or updated): persists `outcome` to `Success Criteria`, and `nonGoals` plus `speculative` requirements to `Future / Out of Scope` with origin `user` +- **technical-designer / technical-designer-frontend**: persists the same to the Design Doc's `Requirement Convergence` when no PRD exists, and always records the fields left `weak-but-explicit` there +- Pass the record unchanged; a field's readiness label travels with it - #### HC-06: acceptance-test-generator โ†’ work-planner +### HC-02: codebase-analyzer โ†’ technical-designer +- Pass: full codebase-analyzer JSON as additional context +- Required downstream uses: + - `focusAreas` โ†’ canonical disposition-target list for the Fact Disposition Table + - `dataModel`, `dataTransformationPipelines`, `qualityAssurance` โ†’ Existing Codebase Analysis / Verification Strategy / Quality Assurance sections - **Pass to acceptance-test-generator**: Design Doc path; UI Spec path (if exists). +### HC-03: technical-designer โ†’ code-verifier +- Pass: Design Doc path (`doc_type: design-doc`) +- Leave `code_paths` unspecified so code-verifier discovers scope from the document - **Orchestrator verification**: Every non-null `generatedFiles.` path exists on disk. For each null lane, `e2eAbsenceReason.` is present (intentional absence, not an error). +### HC-04: code-verifier + codebase-analyzer โ†’ document-reviewer +- Pass: `review_context: creation`, `code_verification` JSON, the same `codebase_analysis` JSON previously given to the designer, original user requirements as `requirements_verbatim`, and confirmed scope and user decisions as `confirmed_decisions` +- Purpose: reviewer validates discrepancy integration, Fact Disposition coverage against `focusAreas`, and Design Convergence against the effective requirements - **Pass to work-planner**: integration / fixture-e2e / service-integration-e2e file paths (or null per lane), per-lane absence reasons, plus timing guidance โ€” integration tests are created alongside each phase implementation, fixture-e2e tests are created alongside the UI feature phase, service-integration-e2e tests are executed only in the final phase. +### HC-05: code-verifier โ†’ next-layer technical-designer (fullstack only) +- Defined only for multi-layer fullstack flow in `references/monorepo-flow.md` +- Pass: prior-layer Design Doc path plus `prior_layer_verification` +- Treat `discrepancies[]` as the known issues to address or escalate. Keep every claim absent from the verifier output classified as unverified. - **On error**: Escalate to user when status != completed and integration file generation failed unexpectedly. A null E2E lane with a valid absence reason is not an error. +### technical-designer โ†’ work-planner -3. **ADR Status Management**: Update ADR status after user decision (Accepted/Rejected) +Pass the Design Doc path. Work-planner owns the documentation-criteria template scan and Design-to-Plan Traceability; unjustified coverage gaps are errors, and justified gaps require user confirmation before plan approval. -## Important Constraints +### HC-06: acceptance-test-generator โ†’ work-planner -Recap (defined above): quality-fixer approval before commit; inter-agent communication is JSON; document-reviewer + user approval before proceeding; check next step against work planning flow after approval; resolve conflicts via Decision precedence. +- Pass the Design Doc and optional UI Spec paths to acceptance-test-generator. +- Verify each non-null `generatedFiles.` path exists and each null lane has `e2eAbsenceReason.`. +- Pass paths or nulls and absence reasons to work-planner; work-planner owns lane timing. +- Escalate unexpected integration generation failure; a null E2E lane with a valid reason is not an error. ## References - `references/monorepo-flow.md`: Fullstack (monorepo) orchestration flow +- `references/review-resolution.md`: Finding adjudication and correction-loop contract diff --git a/skills/subagents-orchestration-guide/references/monorepo-flow.md b/skills/subagents-orchestration-guide/references/monorepo-flow.md index ed1889d..2c8394f 100644 --- a/skills/subagents-orchestration-guide/references/monorepo-flow.md +++ b/skills/subagents-orchestration-guide/references/monorepo-flow.md @@ -30,7 +30,7 @@ This reference defines the orchestration flow for projects spanning multiple lay | 14 | design-sync | Cross-layer consistency verification (source: frontend Design Doc) **[Stop]** | Sync status | | 15 | acceptance-test-generator | Integration + fixture-e2e + service-integration-e2e test skeletons from cross-layer contracts (per-lane) | Test skeletons | | 16 | work-planner | Work plan from all Design Docs | Work plan | -| 17 | document-reviewer | Work Plan review (`doc_type: WorkPlan`); return `needs_revision` to work-planner update and re-review **[Stop: Batch approval after approval]** | Approved Work Plan review | +| 17 | document-reviewer | Work Plan review (`doc_type: WorkPlan`); apply Review Resolution, return the `apply` findings to work-planner, and re-review with `prior_feedback` **[Stop: Batch approval after resolution]** | Resolved Work Plan review | ### Medium Scale Fullstack (3-5 Files) - 15 Steps @@ -50,7 +50,7 @@ This reference defines the orchestration flow for projects spanning multiple lay | 12 | design-sync | Cross-layer consistency verification (source: frontend Design Doc) **[Stop]** | Sync status | | 13 | acceptance-test-generator | Integration + fixture-e2e + service-integration-e2e test skeletons from cross-layer contracts (per-lane) | Test skeletons | | 14 | work-planner | Work plan from all Design Docs | Work plan | -| 15 | document-reviewer | Work Plan review (`doc_type: WorkPlan`); return `needs_revision` to work-planner update and re-review **[Stop: Batch approval after approval]** | Approved Work Plan review | +| 15 | document-reviewer | Work Plan review (`doc_type: WorkPlan`); apply Review Resolution, return the `apply` findings to work-planner, and re-review with `prior_feedback` **[Stop: Batch approval after resolution]** | Resolved Work Plan review | ### Parallelization in Multi-Agent Steps @@ -117,7 +117,7 @@ verification per phase. work-planner's existing Integration Complete criteria naturally covers cross-layer verification when given multiple Design Docs. -For Medium and Large flows, pass the resulting Work Plan to document-reviewer with `doc_type: WorkPlan`. On `needs_revision`, route the findings to work-planner in update mode and re-review. If the same blocking finding repeats and the update supplies no new evidence or contract change, stop and escalate instead of repeating the loop. Request batch approval only after the review is `approved` or `approved_with_conditions`; escalate `rejected` to the user. +For Medium and Large flows, pass the resulting Work Plan to document-reviewer with `doc_type: WorkPlan`. Apply Review Resolution to every actionable finding, route `apply` findings to work-planner in update mode, and re-review with `prior_feedback`. A result whose actionable findings are all `decline` is eligible for batch approval; escalate unresolved `user_decision_required` or unusable inputs. ## Task Materialization Phase @@ -143,5 +143,6 @@ Each task follows the standard 4-step cycle from `../SKILL.md`. Only agent routi When `requiresTestReview` is `true`: - Standard flow (integration-test-reviewer after task-executor, before quality-fixer) +- Apply Review Resolution before returning corrections: pass `apply` findings to the layer executor, re-review with `prior_feedback`, and continue after every `user_decision_required` item has a recorded user decision All other orchestration rules follow the standard subagents-orchestration-guide. diff --git a/skills/subagents-orchestration-guide/references/review-resolution.md b/skills/subagents-orchestration-guide/references/review-resolution.md new file mode 100644 index 0000000..78cc150 --- /dev/null +++ b/skills/subagents-orchestration-guide/references/review-resolution.md @@ -0,0 +1,53 @@ +# Review Resolution + +Use this protocol when a deliverable reviewer or verifier returns findings that can route correction, progression, or escalation. Verification output used as evidence by a downstream specialist remains part of that specialist handoff. + +The orchestrator treats the review result as evidence and makes the workflow decision from the governing sources. + +## 1. Assess Every Finding + +Before assigning a disposition, inspect the relevant parts of the current deliverable, cited repository evidence, and governing sources, treating reviewer assertions as evidence to verify. + +The orchestrator records one disposition for every actionable finding: + +| Disposition | Use when | +|---|---| +| `apply` | Leaving the current deliverable unchanged would prevent the confirmed outcome, violate a binding requirement, design decision, or repository rule, or leave required correctness or verification unsupported. | +| `decline` | Leaving the current deliverable unchanged still achieves the confirmed outcome and satisfies binding constraints and required correctness and verification; the finding instead proposes added scope, a reversed exclusion, optional hardening or generic cleanup, duplicate proof, or other work outside that boundary. | +| `user_decision_required` | Resolving the finding would change a confirmed product outcome, exclusion, major approved design decision, or requires authority held only by the user. | + +A confirmed security risk or governing-source contradiction receives `apply` or `user_decision_required`; cost alone leaves that classification unchanged. + +For each finding record: + +- stable finding ID; +- disposition; +- governing basis and concrete evidence; +- expected effect on the approved outcome or verification; +- smallest correction when `apply`, or the reason when `decline`. + +## 2. Revise and Reconsider + +Pass `apply` findings to the author or executor. On reviewer re-review, provide `prior_feedback` as an array of `{ id, disposition, correction?, reason?, evidence }`. Re-run factual verifiers against the current artifact and adjudicate their current evidence. + +The reviewer reviews the current artifact normally, then reconciles prior feedback: + +- mark an applied correction `resolved` when the reviewed condition is satisfied; +- mark a declined finding `withdrawn` when current evidence and governing sources no longer support it; +- mark a finding `maintained` when current evidence still supports it, citing that evidence; +- report optional improvements through the reviewer's existing recommendation or note fields. + +An independent factual verifier may repeat an observed discrepancy. The orchestrator assigns its disposition from governing evidence; a maintained finding cites current or new evidence. + +## 3. Converge or Escalate + +Escalate when the disposition is `user_decision_required`, user-held authority is needed, an irreversible action awaits authorization, or required inputs are genuinely unusable. Progress after no `apply` findings remain, every other actionable finding has a disposition, and every `user_decision_required` item has a recorded user decision. + +Handoffs contain this exact set: + +- affected paths; +- `apply` findings with basis and smallest correction; +- declined IDs with reasons and evidence in `prior_feedback` when the next consumer accepts reviewer reconciliation; +- the observable condition the next review must verify. + +The final user report lists every declined actionable finding with its ID, governing reason, and evidence. diff --git a/skills/task-analyzer/references/skills-index.yaml b/skills/task-analyzer/references/skills-index.yaml index d99869d..2004c2c 100644 --- a/skills/task-analyzer/references/skills-index.yaml +++ b/skills/task-analyzer/references/skills-index.yaml @@ -141,8 +141,7 @@ skills: - "Handling Requirement Changes" - "Basic Flow: Planning and Implementation" - "Autonomous Execution Mode" - - "Main Orchestrator Roles" - - "Important Constraints" + - "Handoff Contracts" - "References" # Frontend-Specific Skills