From 67d254427a9143d4808e20bad3a0920d5680d4eb Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Fri, 2 Oct 2026 15:00:27 +0900 Subject: [PATCH] Reuse named agents within recipe flows --- .../recipe-add-integration-tests/SKILL.md | 16 ++++----- .agents/skills/recipe-build/SKILL.md | 2 +- .agents/skills/recipe-design/SKILL.md | 26 +++++++------- .agents/skills/recipe-diagnose/SKILL.md | 24 ++++++------- .agents/skills/recipe-front-adjust/SKILL.md | 6 ++-- .agents/skills/recipe-front-build/SKILL.md | 2 +- .agents/skills/recipe-front-design/SKILL.md | 22 ++++++------ .agents/skills/recipe-front-plan/SKILL.md | 8 ++--- .agents/skills/recipe-front-review/SKILL.md | 8 ++--- .../skills/recipe-fullstack-build/SKILL.md | 2 +- .../recipe-fullstack-implement/SKILL.md | 2 +- .agents/skills/recipe-implement/SKILL.md | 6 ++-- .agents/skills/recipe-plan/SKILL.md | 8 ++--- .../skills/recipe-reverse-engineer/SKILL.md | 16 ++++----- .agents/skills/recipe-review/SKILL.md | 36 +++++++++---------- .agents/skills/recipe-update-doc/SKILL.md | 18 +++++----- .../subagents-orchestration-guide/SKILL.md | 12 +++---- .../references/lite-mode.md | 2 +- .../references/monorepo-flow.md | 22 ++++++------ .../agents/technical-designer-frontend.toml | 6 ++-- .codex/agents/technical-designer.toml | 6 ++-- package.json | 2 +- 22 files changed, 128 insertions(+), 124 deletions(-) diff --git a/.agents/skills/recipe-add-integration-tests/SKILL.md b/.agents/skills/recipe-add-integration-tests/SKILL.md index 6b220a1..bf8456f 100644 --- a/.agents/skills/recipe-add-integration-tests/SKILL.md +++ b/.agents/skills/recipe-add-integration-tests/SKILL.md @@ -10,7 +10,7 @@ description: "Add integration/E2E tests to existing codebase using Design Docs." 3. [LOAD IF NOT ACTIVE] `subagents-orchestration-guide` — review resolution and agent coordination 4. [LOAD IF NOT ACTIVE] `llm-friendly-context` — task file contract -**Spawn rule**: every `spawn_agent` call uses `fork_turns="none"` so the subagent receives only the task message and explicitly provided context. +**Invocation rule**: Start each named agent with `spawn_agent` and `fork_turns="none"`. When invoking the same named agent again within this flow, use `followup_task` on its existing instance with the inputs specified for the current invocation. **Context**: Test addition workflow for existing implementations @@ -21,11 +21,11 @@ description: "Add integration/E2E tests to existing codebase using Design Docs." **Execution Plan**: Reuse the active execution plan. When the workflow has multiple dependent actions and no plan exists, create one that tracks them through final verification. **Execution Method**: -- Skeleton generation -> Spawn acceptance-test-generator agent +- Skeleton generation -> Invoke acceptance-test-generator agent - Task file creation -> Orchestrator creates directly (minimal context usage) -- Test implementation -> Spawn task-executor agent -- Test review -> Spawn integration-test-reviewer agent -- Quality checks -> Spawn quality-fixer agent +- Test implementation -> Invoke task-executor agent +- Test review -> Invoke integration-test-reviewer agent +- Quality checks -> Invoke quality-fixer agent Document paths: $ARGUMENTS @@ -48,7 +48,7 @@ Treat paths under `docs/ui-spec/` as UI Specs and the supplied `docs/design/` pa ### Step 2: Skeleton Generation -Spawn acceptance-test-generator with the validated document paths from Step 1. Include UI Specs as optional UI evidence. +Invoke acceptance-test-generator with the validated document paths from Step 1. Include UI Specs as optional UI evidence. ```text Generate test skeletons from the following documents: - Design Docs: [paths] @@ -103,7 +103,7 @@ Execute one task file at a time through Steps 4 -> 5 -> 6 -> 7 before starting t ### Step 5: Test Review Use integration/E2E paths from `taskWriteSet` as the test-review input set. -Spawn integration-test-reviewer with `changedTestFiles`, `diffBase`, `skeletonFiles: [artifact paths in the current task]`, and `taskFile`. +Invoke integration-test-reviewer with `changedTestFiles`, `diffBase`, `skeletonFiles: [artifact paths in the current task]`, and `taskFile`. Keep `testsAdded` as reporting metadata only. Consume the reviewer decision, actionable findings, and governing basis. Apply Orchestrator Escalation Resolution when the result is blocked or cannot support the next action. @@ -116,7 +116,7 @@ Proceed when the review passes. When it contains actionable revision findings, a ### Step 7: Quality Check -Spawn the quality fixer from the current task's Step 3 table row with `task_file`, `filesModified: taskWriteSet`, and the executor's operation-verification evidence. +Invoke the quality fixer from the current task's Step 3 table row with `task_file`, `filesModified: taskWriteSet`, and the executor's operation-verification evidence. **Expected output**: `status` (`stub_detected`/`pass`/`blocked`) diff --git a/.agents/skills/recipe-build/SKILL.md b/.agents/skills/recipe-build/SKILL.md index 5718d49..9b3a5c3 100644 --- a/.agents/skills/recipe-build/SKILL.md +++ b/.agents/skills/recipe-build/SKILL.md @@ -11,7 +11,7 @@ description: "Execute an approved backend Work Plan autonomously through task ex 4. `subagents-orchestration-guide` 5. `llm-friendly-context` -Every `spawn_agent` call uses `fork_turns="none"` and supplies the exact artifact paths needed by that specialist. +**Invocation rule**: Start each named agent with `spawn_agent` and `fork_turns="none"`. When invoking the same named agent again within this flow, use `followup_task` on its existing instance with the inputs specified for the current invocation. Supply the exact artifact paths needed by that specialist. ## Orchestrator Role diff --git a/.agents/skills/recipe-design/SKILL.md b/.agents/skills/recipe-design/SKILL.md index 68f26e5..022514c 100644 --- a/.agents/skills/recipe-design/SKILL.md +++ b/.agents/skills/recipe-design/SKILL.md @@ -10,7 +10,7 @@ description: "Execute from codebase-scoped analysis to design document creation. 3. [LOAD IF NOT ACTIVE] `requirement-convergence` — requirements hearing and scope-confirmation output 4. [LOAD IF NOT ACTIVE] `llm-friendly-context` — document and review handoffs -**Spawn rule**: every `spawn_agent` call uses `fork_turns="none"` so the subagent receives only the task message and explicitly provided context. +**Invocation rule**: Start each named agent with `spawn_agent` and `fork_turns="none"`. When invoking the same named agent again within this flow, use `followup_task` on its existing instance with the inputs specified for the current invocation. **Context**: Dedicated to the design phase. @@ -21,7 +21,7 @@ description: "Execute from codebase-scoped analysis to design document creation. **Execution Plan**: Reuse the active execution plan. When the workflow has multiple dependent actions and no plan exists, create one that tracks them through final verification. **Execution Protocol**: -1. **Spawn agents for analysis and document work** -- your role is to invoke sub-agents, select from their compact evidence against governing requirements, pass the selected material onward, and report results. +1. **Invoke agents for analysis and document work** -- your role is to invoke sub-agents, select from their compact evidence against governing requirements, pass the selected material onward, and report results. 2. **Run the design flow below in order**: - Execute: scope evidence -> [Stop: Scope confirmation] -> optional PRD update/review/[Stop: PRD confirmation] -> codebase-analyzer -> optional ADR batch/batch review/[Stop: ADR-batch confirmation] -> Design Doc -> code-verifier/Review Resolution -> document-reviewer -> design-sync -> [Stop: Design confirmation] - **[STOP — BLOCKING]** At every `[Stop: ...]` marker -> Present status to user for confirmation and proceed after explicit confirmation. @@ -66,7 +66,7 @@ Execute the process below within design scope. ### Step 1: Scope and Cost Evidence -Apply the subagents-orchestration-guide Requirement Evidence Handoff, then spawn requirement-analyzer with that minimum contract. +Apply the subagents-orchestration-guide Requirement Evidence Handoff, then invoke requirement-analyzer with that minimum contract. Step 1 completes when the requirement-analyzer result is received. While it runs, apply the subagent-delegation independence boundary; Step 2 depends on the completed scope and cost evidence. @@ -89,31 +89,31 @@ If `prdRequired` is true and the user neither provides a PRD path nor explicitly After confirmation, record the final scale. When the user's answer changes the analysis target or scope/cost evidence, re-run requirement-analyzer; otherwise update the convergence record directly. Use the current PRD path as carrier when available; otherwise use the compact `convergence` object. ### Step 3: Upstream Confirmation and Codebase Analysis -When Step 2 marked an existing PRD for update, spawn prd-creator in update mode with that PRD path and the confirmed `convergence` object. Review the updated PRD with document-reviewer using its path as `target`, then resolve findings through Review Resolution. After the review permits approval, present the updated PRD for user confirmation. Continue with its path as the carrier after approval. +When Step 2 marked an existing PRD for update, invoke prd-creator in update mode with that PRD path and the confirmed `convergence` object. Review the updated PRD with document-reviewer using its path as `target`, then resolve findings through Review Resolution. After the review permits approval, present the updated PRD for user confirmation. Continue with its path as the carrier after approval. **[STOP — BLOCKING when a PRD was updated]** Wait for user confirmation of the updated PRD. -When analysis is required under the subagents-orchestration-guide reuse rule, use the Fullstack Codebase Analysis assignment in `subagents-orchestration-guide`'s `references/monorepo-flow.md` for a fullstack scope; otherwise spawn codebase-analyzer: "exploration_mode: [mode from Analysis Assignment]. Analyze the existing codebase to provide compact decision materials for ADR selection, minimal Design Doc creation, and verification. requirement_analysis: [confirmed Step 1 scopeEvidence]. requirements: [confirmed requirements]. prd_path: [current PRD path when present]. target_paths: [confirmed scopeEvidence.affectedFiles]." +When analysis is required under the subagents-orchestration-guide reuse rule, use the Fullstack Codebase Analysis assignment in `subagents-orchestration-guide`'s `references/monorepo-flow.md` for a fullstack scope; otherwise invoke codebase-analyzer: "exploration_mode: [mode from Analysis Assignment]. Analyze the existing codebase to provide compact decision materials for ADR selection, minimal Design Doc creation, and verification. requirement_analysis: [confirmed Step 1 scopeEvidence]. requirements: [confirmed requirements]. prd_path: [current PRD path when present]. target_paths: [confirmed scopeEvidence.affectedFiles]." Apply the documentation-criteria Choice filter, then the Durability filter, to `decisionMaterials.candidateDecisionPoints`. `adrDecisionPoints` contains every current-scope point that passes both filters; an empty array routes directly to Design Doc. Record `documentTypeRationale` from the retained points. ### Step 4: Design Document Creation Create documents according to `documentTypeRationale`: -- When `adrDecisionPoints` is non-empty, spawn technical-designer once with `document_to_create: ADRBatch`, `decision_points: [adrDecisionPoints]`, confirmed requirements, and `decision_materials: [only the Step 3 simplification, reuse, invalidation, option/cost, contract, and decision-changing unknown material relevant to those points]`. Review all returned `paths[]` in one document-reviewer invocation using `doc_type: ADRBatch` and `targets: [all paths]`. Apply Review Resolution to the batch, rerun the batch review when an accepted correction changes a file, then present one ADR-batch confirmation request. +- When `adrDecisionPoints` is non-empty, invoke technical-designer once with `document_to_create: ADRBatch`, `decision_points: [adrDecisionPoints]`, confirmed requirements, and `decision_materials: [only the Step 3 simplification, reuse, invalidation, option/cost, contract, and decision-changing unknown material relevant to those points]`. Review all returned `paths[]` in one document-reviewer invocation using `doc_type: ADRBatch` and `targets: [all paths]`. Apply Review Resolution to the batch, rerun the batch review when an accepted correction changes a file, then present one ADR-batch confirmation request. **[STOP — BLOCKING when ADRs were created]** Wait for one user confirmation of the reviewed ADR batch before creating the Design Doc. -Record every approved ADR file as `Accepted` when ADRs were created. Spawn technical-designer with `document_to_create: DesignDoc`, `adr_paths: [accepted ADR paths or []]`, the confirmed requirement carrier, and `decision_materials: [only Step 3 material that changes reuse, simplification, implementation validity, a selected ADR decision, a preserved contract, or verification]`. The confirmed requirements define scope, and selected ADR decisions supply the current technical choices, revisable when a smaller sufficient design is supported. +Record every approved ADR file as `Accepted` when ADRs were created. Invoke technical-designer with `document_to_create: DesignDoc`, `adr_paths: [accepted ADR paths or []]`, the confirmed requirement carrier, and `decision_materials: [only Step 3 material that changes reuse, simplification, implementation validity, a selected ADR decision, a preserved contract, or verification]`. The confirmed requirements define scope, and selected ADR decisions supply the current technical choices, revisable when a smaller sufficient design is supported. ### Step 5: Code Verification **Review reception:** Unnecessary repairs create lasting work. Before assigning a fix, use Review Resolution to judge no change, removal or narrowing, and reuse first; record why any retained or added mechanism is necessary. -Spawn code-verifier agent: "Verify the Design Doc against the current codebase. document_path: [Design Doc path from Step 4]. doc_type: design-doc." +Invoke code-verifier agent: "Verify the Design Doc against the current codebase. document_path: [Design Doc path from Step 4]. doc_type: design-doc." Apply Review Resolution to every discrepancy before document review, using technical-designer in update mode for selected corrections and its bounded rerun rule. When the `apply` set is empty, carry the resolved verification summary, declines with reasons, and material limitations to Step 6. ### Step 6: Document Review -Spawn document-reviewer agent: "Review the Design Doc for consistency, completeness, and adopted design validity. doc_type: DesignDoc. review_context: creation. target: [Design Doc path]. requirements_verbatim: [original user requirements]. confirmed_requirement_context: [complete confirmed requirement context from Step 2]. decision_materials: [only Step 3 material that constrains this design]. verification_resolution: [resolved Step 5 evidence]." +Invoke document-reviewer agent: "Review the Design Doc for consistency, completeness, and adopted design validity. doc_type: DesignDoc. review_context: creation. target: [Design Doc path]. requirements_verbatim: [original user requirements]. confirmed_requirement_context: [complete confirmed requirement context from Step 2]. decision_materials: [only Step 3 material that constrains this design]. verification_resolution: [resolved Step 5 evidence]." Route the result before consistency verification: - `pass`: continue @@ -121,7 +121,7 @@ Route the result before consistency verification: - `rejected`: apply Orchestrator Escalation Resolution. Continue after an evidence-based self-resolution; ask the user only when that procedure reaches a user-decision condition ### Step 7: Consistency Verification -Spawn design-sync agent: "Verify consistency of the design document with other existing design documents and project constraints." +Invoke design-sync agent: "Verify consistency of the design document with other existing design documents and project constraints." **Note**: design-sync returns `sync_status: "SKIPPED"` when only 1 Design Doc exists. This is distinct from `NO_CONFLICTS` and MUST be reported as such to the user. @@ -130,13 +130,13 @@ Request user confirmation using the shared Design Confirmation alignment. ## Completion Criteria - [ ] Obtained compact scope and cost evidence while the user retained product requirements and exclusions and the orchestrator handled comparison, readiness, scale, and routing -- [ ] Spawned codebase-analyzer and passed only decision-relevant material into ADR/Design Doc creation +- [ ] Invoked codebase-analyzer and passed only decision-relevant material into ADR/Design Doc creation - [ ] Converged the requirement and persisted the record - [ ] Confirmed the design scope before codebase analysis and document creation - [ ] Created one ADR per qualifying decision point and reviewed the complete batch once, or routed an empty decision-point set directly to Design Doc - [ ] Applied Review Resolution to code-verifier discrepancies before document review -- [ ] Spawned document-reviewer and addressed feedback -- [ ] Spawned design-sync for consistency verification for Design Docs +- [ ] Invoked document-reviewer and addressed feedback +- [ ] Invoked design-sync for consistency verification for Design Docs - [ ] Obtained user confirmation for design document - [ ] All `[Stop: ...]` markers honored with user confirmation diff --git a/.agents/skills/recipe-diagnose/SKILL.md b/.agents/skills/recipe-diagnose/SKILL.md index 7f398a8..ff51589 100644 --- a/.agents/skills/recipe-diagnose/SKILL.md +++ b/.agents/skills/recipe-diagnose/SKILL.md @@ -9,7 +9,7 @@ description: "Investigate problem, verify findings, and derive solutions through 2. [LOAD IF NOT ACTIVE] `coding-rules` — coding standards 3. [LOAD IF NOT ACTIVE] `llm-friendly-context` — clear prompts, handoffs, and generated artifacts -**Spawn rule**: every `spawn_agent` call uses `fork_turns="none"` so the subagent receives only the task message and explicitly provided context. +**Invocation rule**: Start each named agent with `spawn_agent` and `fork_turns="none"`. When invoking the same named agent again within this flow, use `followup_task` on its existing instance with the inputs specified for the current invocation. **Context**: Diagnosis flow to identify concrete failure points and present solutions @@ -18,15 +18,15 @@ Target problem: $ARGUMENTS ## Orchestrator Definition **Execution Method**: -- Investigation -> Spawn investigator agent -- Verification -> Spawn verifier agent -- Solution derivation -> Spawn solver agent +- Investigation -> Invoke investigator agent +- Verification -> Invoke verifier agent +- Solution derivation -> Invoke solver agent The orchestrator structures the reported problem, coordinates the three specialist stages, evaluates their results, and passes only the context needed by the next stage. **Execution Plan**: Reuse the active execution plan. When the workflow has multiple dependent actions and no plan exists, create one that tracks them through final verification. Complete a plan step after verifying its result; start a dependent step after its prerequisites are satisfied. -## Step 0: Problem Structuring (Before spawning investigator) +## Step 0: Problem Structuring (Before invoking investigator) ### 0.1 Problem Type Determination @@ -57,7 +57,7 @@ solver null recommendation -> investigator while new evidence can change the res evidence saturated before recommendation -> unresolved Report ``` -**Context Separation**: Pass only structured output to each step. Each step starts fresh with the data only. +**Context Separation**: Pass only structured output to each step. Each agent's first invocation starts fresh with the supplied data only. ## Execution Steps @@ -65,7 +65,7 @@ Execute the registered steps: ### Step 1: Investigation (investigator) -Spawn investigator agent with the following prompt: +Invoke investigator agent with the following prompt: ```text Collect decision-relevant information about the following phenomenon. @@ -98,7 +98,7 @@ Proceed to verifier once quality is satisfied. ### Step 3: Verification (verifier) -Spawn verifier agent: "Verify the following investigation results. Investigation results: [Investigation output]" +Invoke verifier agent: "Verify the following investigation results. Investigation results: [Investigation output]" **Expected output**: Path coverage findings, independent failure-point evaluation, final conclusion, coverageAssessment/finalStatus @@ -106,7 +106,7 @@ Use the verifier's `coverageAssessment` and its Coverage Determination Criteria ### Step 4: Solution Derivation (solver) -When `finalStatus=ready_for_solution`, spawn solver agent: "Derive solutions based on the following verified conclusion. Verified conclusion: [verifier's conclusion]. Failure-point evaluations: [verifier's failurePointsEvaluation]. Verification limitations: [verifier's verificationLimitations]. Impact analysis: [investigator output impactAnalysis]." +When `finalStatus=ready_for_solution`, invoke solver agent: "Derive solutions based on the following verified conclusion. Verified conclusion: [verifier's conclusion]. Failure-point evaluations: [verifier's failurePointsEvaluation]. Verification limitations: [verifier's verificationLimitations]. Impact analysis: [investigator output impactAnalysis]." **Expected output**: Credible materially distinct solutions, relevant tradeoffs, and either a supported recommendation with implementation steps or a null recommendation with exact missing evidence. One solution is sufficient when evidence rules out a meaningful alternative. @@ -155,9 +155,9 @@ Rationale: [Selection rationale] ## Completion Criteria -- [ ] Spawned investigator and obtained evidence matrix, comparison analysis, and causal tracking +- [ ] Invoked investigator and obtained evidence matrix, comparison analysis, and causal tracking - [ ] Performed investigation quality check and re-ran if insufficient -- [ ] Spawned verifier and obtained coverage assessment -- [ ] Spawned solver when `finalStatus=ready_for_solution` +- [ ] Invoked verifier and obtained coverage assessment +- [ ] Invoked solver when `finalStatus=ready_for_solution` - [ ] Reached `ready_for_solution` with a supported recommendation, or reported the exact unresolved input after available evidence stopped changing coverage - [ ] Presented final report to user diff --git a/.agents/skills/recipe-front-adjust/SKILL.md b/.agents/skills/recipe-front-adjust/SKILL.md index e1b54ef..fd9546b 100644 --- a/.agents/skills/recipe-front-adjust/SKILL.md +++ b/.agents/skills/recipe-front-adjust/SKILL.md @@ -12,7 +12,7 @@ description: "Adjust an implemented UI with focused evidence, verification, and Load `external-resource-context` in Step 1 only when a named external source is required for the requested adjustment. -**Spawn rule**: every `spawn_agent` call uses `fork_turns="none"` so the subagent receives only the task message and explicitly provided context. +**Invocation rule**: Start each named agent with `spawn_agent` and `fork_turns="none"`. When invoking the same named agent again within this flow, use `followup_task` on its existing instance with the inputs specified for the current invocation. ## Execution Pattern @@ -34,7 +34,7 @@ Identify whether the requested adjustment depends on an external design or verif ### Step 2: UI Fact Gathering -Spawn `ui-analyzer`: +Invoke `ui-analyzer`: `exploration_mode: [mode from Analysis Assignment]. requirement_analysis: { affectedFiles: [files inferred from request], purpose: "UI adjustment", technicalConsiderations: [] }. requirements: [adjustment request]. target_paths: [paths named or inferred from request]. target_components: [components named in request]. ui_spec_path: [path if available]. externalResourceRefs: [{label, featureIdentifier} selected in Step 1, or []]. Analyze existing UI code and populate candidateWriteSet[].` @@ -67,7 +67,7 @@ For each adjustment unit: **Review reception:** Unnecessary repairs create lasting work. Before assigning a fix, use Review Resolution to judge no change, removal or narrowing, and reuse first; record why any retained or added mechanism is necessary. -For each unit, spawn `quality-fixer-frontend` with `filesModified: taskWriteSet` and the Step 4 verification evidence. Repair reported stubs in the parent session, accumulate every repair and quality-fixer path, and rerun quality-fixer. On pass, reconcile and commit the Per-Task Change Set; resolve blocked results through Orchestrator Escalation Resolution. +For each unit, invoke `quality-fixer-frontend` with `filesModified: taskWriteSet` and the Step 4 verification evidence. Repair reported stubs in the parent session, accumulate every repair and quality-fixer path, and rerun quality-fixer. On pass, reconcile and commit the Per-Task Change Set; resolve blocked results through Orchestrator Escalation Resolution. ## Completion Criteria diff --git a/.agents/skills/recipe-front-build/SKILL.md b/.agents/skills/recipe-front-build/SKILL.md index 40142ee..89edc39 100644 --- a/.agents/skills/recipe-front-build/SKILL.md +++ b/.agents/skills/recipe-front-build/SKILL.md @@ -11,7 +11,7 @@ description: "Execute an approved frontend Work Plan autonomously through fronte 4. `subagents-orchestration-guide` 5. `llm-friendly-context` -Every `spawn_agent` call uses `fork_turns="none"` and supplies exact artifact paths. +**Invocation rule**: Start each named agent with `spawn_agent` and `fork_turns="none"`. When invoking the same named agent again within this flow, use `followup_task` on its existing instance with the inputs specified for the current invocation. Supply exact artifact paths. ## Orchestrator Role diff --git a/.agents/skills/recipe-front-design/SKILL.md b/.agents/skills/recipe-front-design/SKILL.md index 9ae9d7c..f234d5a 100644 --- a/.agents/skills/recipe-front-design/SKILL.md +++ b/.agents/skills/recipe-front-design/SKILL.md @@ -14,7 +14,7 @@ description: "Execute from codebase-scoped analysis to frontend design document Load `external-resource-context` in Step 4 only when a named external source is required for the current design or verification decision. -**Spawn rule**: every `spawn_agent` call uses `fork_turns="none"` so the subagent receives only the task message and explicitly provided context. +**Invocation rule**: Start each named agent with `spawn_agent` and `fork_turns="none"`. When invoking the same named agent again within this flow, use `followup_task` on its existing instance with the inputs specified for the current invocation. ## Orchestrator Definition @@ -55,7 +55,7 @@ Requirements: $ARGUMENTS ### Step 1: Scope and Cost Evidence -Apply the subagents-orchestration-guide Requirement Evidence Handoff, then spawn requirement-analyzer with that minimum contract. Step 1 completes when the evidence result returns. +Apply the subagents-orchestration-guide Requirement Evidence Handoff, then invoke requirement-analyzer with that minimum contract. Step 1 completes when the evidence result returns. ### Step 2: Scope Confirmation Confirm requirements and determine Structural Scale from the user's wording and Step 1 scope and cost evidence: @@ -76,11 +76,11 @@ If `prdRequired` is true and the user neither provides a PRD path nor explicitly After confirmation, record the final scale. When the user's answer changes the analysis target or scope/cost evidence, re-run requirement-analyzer; otherwise update the convergence record directly. The Choice and Durability filters supply ADR decision points independently of scale. Use the current PRD path as carrier when available; otherwise use the compact `convergence` object. ### Step 3: Upstream Confirmation and Codebase Analysis -When Step 2 marked an existing PRD for update, spawn prd-creator in update mode with that PRD path and the confirmed `convergence` object. Review the updated PRD with document-reviewer using its path as `target`, then resolve findings through Review Resolution. After the review permits approval, present the updated PRD for user confirmation. Continue with its path as the carrier after approval. +When Step 2 marked an existing PRD for update, invoke prd-creator in update mode with that PRD path and the confirmed `convergence` object. Review the updated PRD with document-reviewer using its path as `target`, then resolve findings through Review Resolution. After the review permits approval, present the updated PRD for user confirmation. Continue with its path as the carrier after approval. **[STOP -- BLOCKING when a PRD was updated]** Wait for user confirmation of the updated PRD. -When analysis is required under the subagents-orchestration-guide reuse rule, spawn codebase-analyzer for the confirmed frontend scope: "exploration_mode: [mode from Analysis Assignment]. Analyze the existing codebase to provide compact decision materials for ADR selection, minimal Design Doc creation, and verification. requirement_analysis: [confirmed Step 1 scopeEvidence]. requirements: [confirmed requirements]. prd_path: [current PRD path when present]. layer: frontend. target_paths: [confirmed scopeEvidence.affectedFiles]. focus_areas: responsibility ownership, state/data paths, contracts, and reuse." +When analysis is required under the subagents-orchestration-guide reuse rule, invoke codebase-analyzer for the confirmed frontend scope: "exploration_mode: [mode from Analysis Assignment]. Analyze the existing codebase to provide compact decision materials for ADR selection, minimal Design Doc creation, and verification. requirement_analysis: [confirmed Step 1 scopeEvidence]. requirements: [confirmed requirements]. prd_path: [current PRD path when present]. layer: frontend. target_paths: [confirmed scopeEvidence.affectedFiles]. focus_areas: responsibility ownership, state/data paths, contracts, and reuse." ### Step 4: External Resource Hearing After scope confirmation, identify whether a current UI or verification decision requires evidence unavailable from the repository, supplied artifacts, or a recorded resource. When it does, run the focused hearing from `external-resource-context` for that exact axis and persist its access method. Ask the user only when the missing access method controls the design decision. Otherwise record no external-resource dependency and continue. @@ -93,14 +93,14 @@ When `prototype_path` is available, apply the subagents-orchestration-guide UI S ### Step 6: UI Fact Gathering Phase Use the prototype path as an input when one was provided; otherwise set `prototype_path` to unavailable. -Spawn ui-analyzer agent: "exploration_mode: [mode from Analysis Assignment]. prior_evidence: [relevant Step 3 findings]. Gather UI facts for frontend design. requirement_analysis: { affectedFiles: [confirmed frontend affected files] }. requirements: [Step 2 confirmed current requirements]. target_paths: [confirmed frontend affected files and directories]. target_components: [frontend target components when known]. ui_spec_path: [path if an existing UI Spec covers this feature]. prototype_path: [path if provided]. externalResourceRefs: [{label, featureIdentifier} selected in Step 4, or []]. focus_areas: [remaining rendering, interaction, and visual questions]." +Invoke ui-analyzer agent: "exploration_mode: [mode from Analysis Assignment]. prior_evidence: [relevant Step 3 findings]. Gather UI facts for frontend design. requirement_analysis: { affectedFiles: [confirmed frontend affected files] }. requirements: [Step 2 confirmed current requirements]. target_paths: [confirmed frontend affected files and directories]. target_components: [frontend target components when known]. ui_spec_path: [path if an existing UI Spec covers this feature]. prototype_path: [path if provided]. externalResourceRefs: [{label, featureIdentifier} selected in Step 4, or []]. focus_areas: [remaining rendering, interaction, and visual questions]." ### Step 7: UI Specification Phase **Review reception:** Unnecessary repairs create lasting work. Before assigning a fix, use Review Resolution to judge no change, removal or narrowing, and reuse first; record why any retained or added mechanism is necessary. After UI fact gathering completes, create the UI Specification: -- Spawn ui-spec-designer agent: "Create UI Spec [from PRD at [path] if PRD exists; read its binding requirements and only Product Context entries they explicitly cite]. Confirmed requirements and exclusions: [Step 2 current requirements and nonGoals]. Codebase analysis: [JSON from codebase-analyzer]. UI analysis: [JSON from ui-analyzer]. [Prototype code is at [user-provided path]. Prototype reference strength: [binding | reference]. Place prototype in docs/ui-spec/assets/{feature-name}/ | Prototype path unavailable; proceed from PRD/requirements and UI analysis.] External resource refs: [ui_analysis.externalResources.selectedRefs]." -- Spawn document-reviewer agent: "doc_type: UISpec target: [ui-spec path] Review for consistency and completeness" +- Invoke ui-spec-designer agent: "Create UI Spec [from PRD at [path] if PRD exists; read its binding requirements and only Product Context entries they explicitly cite]. Confirmed requirements and exclusions: [Step 2 current requirements and nonGoals]. Codebase analysis: [JSON from codebase-analyzer]. UI analysis: [JSON from ui-analyzer]. [Prototype code is at [user-provided path]. Prototype reference strength: [binding | reference]. Place prototype in docs/ui-spec/assets/{feature-name}/ | Prototype path unavailable; proceed from PRD/requirements and UI analysis.] External resource refs: [ui_analysis.externalResources.selectedRefs]." +- Invoke document-reviewer agent: "doc_type: UISpec target: [ui-spec path] Review for consistency and completeness" - Resolve `needs_revision` through Review Resolution with ui-spec-designer, then review the updated UI Spec. Route governing-source contradictions through Orchestrator Escalation Resolution before the user confirmation stop. **[STOP -- BLOCKING]** Present UI Spec for user confirmation. @@ -109,14 +109,14 @@ Proceed after the user explicitly confirms the UI Spec. ### Step 8: Design Document Creation Phase Create appropriate design documents from confirmed scope and decision materials: - Start with codebase analysis `candidateDecisionPoints`, then add a technical choice from UI analysis or the approved UI Spec when its evidence establishes at least two credible materially distinct options. Apply the Choice filter, then the Durability filter, to the complete candidate set. -- When the retained array is non-empty, spawn technical-designer-frontend once with `document_to_create: ADRBatch`, `decision_points: [retained array]`, confirmed requirements, and `decision_materials: [only analysis material that changes the options, lifecycle cost, maintainability, or validity of those points]`. Review all returned `paths[]` in one document-reviewer invocation using `doc_type: ADRBatch` and `targets: [all paths]`. Apply Review Resolution to the batch, rerun the batch review when an accepted correction changes a file, then present one ADR-batch confirmation request. +- When the retained array is non-empty, invoke technical-designer-frontend once with `document_to_create: ADRBatch`, `decision_points: [retained array]`, confirmed requirements, and `decision_materials: [only analysis material that changes the options, lifecycle cost, maintainability, or validity of those points]`. Review all returned `paths[]` in one document-reviewer invocation using `doc_type: ADRBatch` and `targets: [all paths]`. Apply Review Resolution to the batch, rerun the batch review when an accepted correction changes a file, then present one ADR-batch confirmation request. **[STOP -- BLOCKING when ADRs were created]** Wait for one user confirmation of the reviewed ADR batch before creating the Design Doc. -- Record every approved ADR file as `Accepted` when ADRs were created. For Design Doc, spawn technical-designer-frontend with `document_to_create: DesignDoc`, `adr_paths: [accepted ADR paths or []]`, confirmed requirements, approved UI Spec, and `decision_materials: [only analysis material that changes reuse, simplification, implementation validity, a selected ADR decision, a preserved contract, or verification]`. The confirmed requirements define scope, and selected ADR decisions supply the current technical choices, revisable when a smaller sufficient design is supported. -- Spawn code-verifier agent: "Verify Design Doc against code. doc_type: design-doc. document_path: [document path]." +- Record every approved ADR file as `Accepted` when ADRs were created. For Design Doc, invoke technical-designer-frontend with `document_to_create: DesignDoc`, `adr_paths: [accepted ADR paths or []]`, confirmed requirements, approved UI Spec, and `decision_materials: [only analysis material that changes reuse, simplification, implementation validity, a selected ADR decision, a preserved contract, or verification]`. The confirmed requirements define scope, and selected ADR decisions supply the current technical choices, revisable when a smaller sufficient design is supported. +- Invoke code-verifier agent: "Verify Design Doc against code. doc_type: design-doc. document_path: [document path]." - Apply Review Resolution to every code-verifier discrepancy, using technical-designer-frontend in update mode for selected corrections and its bounded rerun rule. Carry the resolved verification summary, declines with reasons, and material limitations after the `apply` set becomes empty. -- Review the Design Doc: Spawn document-reviewer agent: "Review the Design Doc for consistency, completeness, and adopted design validity. doc_type: DesignDoc. review_context: creation. target: [Design Doc path]. requirements_verbatim: [original user requirements]. confirmed_requirement_context: [complete confirmed requirement context from Step 2]. decision_materials: [only analysis material that constrains this design]. verification_resolution: [resolved code-verifier evidence]." +- Review the Design Doc: Invoke document-reviewer agent: "Review the Design Doc for consistency, completeness, and adopted design validity. doc_type: DesignDoc. review_context: creation. target: [Design Doc path]. requirements_verbatim: [original user requirements]. confirmed_requirement_context: [complete confirmed requirement context from Step 2]. decision_materials: [only analysis material that constrains this design]. verification_resolution: [resolved code-verifier evidence]." - Resolve `needs_revision` through Review Resolution with technical-designer-frontend, then review the updated Design Doc. Route governing-source contradictions through Orchestrator Escalation Resolution. Reach the user confirmation stop after review succeeds. **[STOP -- BLOCKING]** Obtain user confirmation using the shared Design Confirmation alignment. diff --git a/.agents/skills/recipe-front-plan/SKILL.md b/.agents/skills/recipe-front-plan/SKILL.md index 57a7dc3..2a2b562 100644 --- a/.agents/skills/recipe-front-plan/SKILL.md +++ b/.agents/skills/recipe-front-plan/SKILL.md @@ -12,7 +12,7 @@ description: "Create frontend work plan from design document with test skeleton 3. [LOAD IF NOT ACTIVE] `subagents-orchestration-guide` -- agent coordination and workflow flow 4. [LOAD IF NOT ACTIVE] `llm-friendly-context` -- planning handoffs and artifact contract -**Spawn rule**: every `spawn_agent` call uses `fork_turns="none"` so the subagent receives only the task message and explicitly provided context. +**Invocation rule**: Start each named agent with `spawn_agent` and `fork_turns="none"`. When invoking the same named agent again within this flow, use `followup_task` on its existing instance with the inputs specified for the current invocation. ## Orchestrator Definition @@ -50,17 +50,17 @@ Check for existence of design documents in docs/design/. Proceed when a design document is available. ### Step 2: Test Skeleton Generation -Spawn acceptance-test-generator agent: "Generate test skeletons from Design Doc at [path]. [UI Spec at [ui-spec path] if exists.]" +Invoke acceptance-test-generator agent: "Generate test skeletons from Design Doc at [path]. [UI Spec at [ui-spec path] if exists.]" Verify generated artifact paths and pass them to Step 3; an empty selection is valid. ### Step 3: Work Plan Creation -Spawn work-planner agent: "Create an implementation-focused work plan from Design Doc at [path]. Include generated test skeleton artifact paths from Step 2 when present. Plan only repository implementation outcomes required by the Design Doc and UI Spec." +Invoke work-planner agent: "Create an implementation-focused work plan from Design Doc at [path]. Include generated test skeleton artifact paths from Step 2 when present. Plan only repository implementation outcomes required by the Design Doc and UI Spec." Verify the returned Work Plan path and use it as the Step 4 review target. ### Step 4: Work Plan Review **Review reception:** Unnecessary repairs create lasting work. Before assigning a fix, use Review Resolution to judge no change, removal or narrowing, and reuse first; record why any retained or added mechanism is necessary. -Spawn document-reviewer agent: "Review the frontend work plan. doc_type: WorkPlan. target: [work-planner completed path]. Verify Design Doc and UI Spec implementation coverage, absence of added operational scope, dependency order, executable verification, optional Verification Focus, and Review Scope." +Invoke document-reviewer agent: "Review the frontend work plan. doc_type: WorkPlan. target: [work-planner completed path]. Verify Design Doc and UI Spec implementation coverage, absence of added operational scope, dependency order, executable verification, optional Verification Focus, and Review Scope." Branch on `verdict.decision`: - `pass` -> proceed to Step 5 diff --git a/.agents/skills/recipe-front-review/SKILL.md b/.agents/skills/recipe-front-review/SKILL.md index 5cfbdee..ad09d95 100644 --- a/.agents/skills/recipe-front-review/SKILL.md +++ b/.agents/skills/recipe-front-review/SKILL.md @@ -13,7 +13,7 @@ description: "Reviews completed frontend implementation for governing-source com 4. [LOAD IF NOT ACTIVE] `llm-friendly-context` -- task file contract 5. [LOAD IF NOT ACTIVE] `subagents-orchestration-guide` -- agent coordination and result handling -**Spawn rule**: every `spawn_agent` call uses `fork_turns="none"` so the subagent receives only the task message and explicitly provided context. +**Invocation rule**: Start each named agent with `spawn_agent` and `fork_turns="none"`. When invoking the same named agent again within this flow, use `followup_task` on its existing instance with the inputs specified for the current invocation. ## Execution Method @@ -38,12 +38,12 @@ If a single active work plan is explicitly provided or unambiguously resolved fo Proceed when both a Design Doc and implementation files are available. ### 2. Execute code-reviewer -Spawn code-reviewer agent: "Review the completed frontend implementation. governingDocuments: [{type: design-doc, path: [design-doc-path]}]. Work Plan: [resolved work plan path or none]. Review Scope: [literal Review Scope value or none]. implementationFiles: [$STEP_1_FILES]. Return the initial review JSON." +Invoke code-reviewer agent: "Review the completed frontend implementation. governingDocuments: [{type: design-doc, path: [design-doc-path]}]. Work Plan: [resolved work plan path or none]. Review Scope: [literal Review Scope value or none]. implementationFiles: [$STEP_1_FILES]. Return the initial review JSON." **Store output as**: `$STEP_2_OUTPUT` ### 3. Execute security-reviewer -Spawn security-reviewer with `governingDocuments: [{type: "design-doc", path: [path]}]` and `implementationFiles: $STEP_1_FILES`. +Invoke security-reviewer with `governingDocuments: [{type: "design-doc", path: [path]}]` and `implementationFiles: $STEP_1_FILES`. **Store output as**: `$STEP_3_OUTPUT` @@ -89,7 +89,7 @@ If the user declines corrections, skip fix steps and proceed to Final Report. ## Correction Flow -1. **Design-side update**: If any accepted finding uses the design-side route, spawn technical-designer-frontend in update mode, then document-reviewer with `doc_type: DesignDoc` and `review_context: update`, then design-sync when multiple Design Docs exist. If both routes apply, re-evaluate the code-side findings against the updated Design Doc and drop any now satisfied. +1. **Design-side update**: If any accepted finding uses the design-side route, invoke technical-designer-frontend in update mode, then document-reviewer with `doc_type: DesignDoc` and `review_context: update`, then design-sync when multiple Design Docs exist. If both routes apply, re-evaluate the code-side findings against the updated Design Doc and drop any now satisfied. 2. **Plan fixes**: Use the active execution plan when one exists. When none exists, create one for the accepted fix flow. Create `docs/plans/tasks/review-fixes-frontend-task-01.md` with only findings selected for code-side correction. 3. **Execute fixes**: Start the Per-Task Change Set, invoke task-executor-frontend with the task file, inspect its result and repository diff, and accumulate its paths. 4. **Quality check**: Invoke quality-fixer-frontend with `task_file`, `filesModified: taskWriteSet`, and executor operation-verification evidence. On pass, add its paths and commit the reconciled set; repair stubs through task-executor-frontend, accumulate their paths, and resolve blocked results through Orchestrator Escalation Resolution. diff --git a/.agents/skills/recipe-fullstack-build/SKILL.md b/.agents/skills/recipe-fullstack-build/SKILL.md index 29870b0..14dfde1 100644 --- a/.agents/skills/recipe-fullstack-build/SKILL.md +++ b/.agents/skills/recipe-fullstack-build/SKILL.md @@ -11,7 +11,7 @@ description: "Execute an approved fullstack Work Plan autonomously with layer-aw 4. `subagents-orchestration-guide` 5. `llm-friendly-context` -Every `spawn_agent` call uses `fork_turns="none"` and supplies exact artifact paths. +**Invocation rule**: Start each named agent with `spawn_agent` and `fork_turns="none"`. When invoking the same named agent again within this flow, use `followup_task` on its existing instance with the inputs specified for the current invocation. Supply exact artifact paths. ## Orchestrator Role diff --git a/.agents/skills/recipe-fullstack-implement/SKILL.md b/.agents/skills/recipe-fullstack-implement/SKILL.md index 699562e..2db5b98 100644 --- a/.agents/skills/recipe-fullstack-implement/SKILL.md +++ b/.agents/skills/recipe-fullstack-implement/SKILL.md @@ -10,7 +10,7 @@ description: "Run the full-cycle implementation workflow for one outcome spannin 3. [LOAD IF NOT ACTIVE] `requirement-convergence` — outcome, exclusions, and rough-cost challenge 4. [LOAD IF NOT ACTIVE] `llm-friendly-context` — cross-agent handoffs and Small task carrier -Every `spawn_agent` call uses `fork_turns="none"` and supplies only the exact artifacts needed by that specialist. +**Invocation rule**: Start each named agent with `spawn_agent` and `fork_turns="none"`. When invoking the same named agent again within this flow, use `followup_task` on its existing instance with the inputs specified for the current invocation. Supply only the exact artifacts needed by that specialist. Requirements or continuation instruction: $ARGUMENTS diff --git a/.agents/skills/recipe-implement/SKILL.md b/.agents/skills/recipe-implement/SKILL.md index 4dd04d9..55417d9 100644 --- a/.agents/skills/recipe-implement/SKILL.md +++ b/.agents/skills/recipe-implement/SKILL.md @@ -10,7 +10,7 @@ description: "Orchestrate the complete implementation lifecycle from requirement 3. [LOAD IF NOT ACTIVE] `requirement-convergence` — outcome, exclusion, and rough-cost convergence before design 4. [LOAD IF NOT ACTIVE] `llm-friendly-context` — cross-agent handoffs and task carrier -**Spawn rule**: every `spawn_agent` call uses `fork_turns="none"` so the subagent receives only the task message and explicitly provided context. +**Invocation rule**: Start each named agent with `spawn_agent` and `fork_turns="none"`. When invoking the same named agent again within this flow, use `followup_task` on its existing instance with the inputs specified for the current invocation. # Full-Cycle Implementation @@ -24,7 +24,7 @@ Follow the scale-selected flow and its user approval points from subagents-orche ## Step 1: Requirement Analysis -Apply the subagents-orchestration-guide Requirement Evidence Handoff, then spawn requirement-analyzer for compact scope evidence, cost evidence, affected-layer evidence, and decision-changing questions. +Apply the subagents-orchestration-guide Requirement Evidence Handoff, then invoke requirement-analyzer for compact scope evidence, cost evidence, affected-layer evidence, and decision-changing questions. At the requirements stop, the orchestrator compares the evidence with its retained user record and applies subagents-orchestration-guide `Requirement Convergence`. User selections establish requirements and exclusions; the orchestrator judges readiness, determines Structural Scale and affected layers, and selects the canonical route. @@ -69,5 +69,5 @@ Verify acceptance-test-generator artifact paths and pass them to work-planner. - [ ] codebase-analyzer included before Design Doc creation for Medium/Large flows - [ ] code-verifier discrepancies passed through Review Resolution before Design Doc review - [ ] All stopping points honored with user confirmation obtained -- [ ] Quality-fixer spawned before every commit +- [ ] Quality-fixer invoked before every commit - [ ] All tasks committed or user input requested diff --git a/.agents/skills/recipe-plan/SKILL.md b/.agents/skills/recipe-plan/SKILL.md index 8ba9141..598bacd 100644 --- a/.agents/skills/recipe-plan/SKILL.md +++ b/.agents/skills/recipe-plan/SKILL.md @@ -10,7 +10,7 @@ description: "Creates a reviewed Work Plan with value-filtered integration/E2E t 3. [LOAD IF NOT ACTIVE] `subagents-orchestration-guide` — agent coordination and workflow flow 4. [LOAD IF NOT ACTIVE] `llm-friendly-context` — planning handoffs and artifact contract -**Spawn rule**: every `spawn_agent` call uses `fork_turns="none"` so the subagent receives only the task message and explicitly provided context. +**Invocation rule**: Start each named agent with `spawn_agent` and `fork_turns="none"`. When invoking the same named agent again within this flow, use `followup_task` on its existing instance with the inputs specified for the current invocation. **Context**: Dedicated to the planning phase. @@ -47,17 +47,17 @@ Check for existence of design documents in docs/design/, notify user if none exi Present options if multiple exist (can be specified with $ARGUMENTS). ### Step 2: Integration/E2E Test Skeleton Selection -- Spawn acceptance-test-generator agent: "Generate the value-selected integration/E2E test skeletons from Design Doc at [design-doc-path]." +- Invoke acceptance-test-generator agent: "Generate the value-selected integration/E2E test skeletons from Design Doc at [design-doc-path]." - Verify generated artifact paths and pass them to Step 3; an empty selection is valid ### Step 3: Work Plan Creation -- Spawn work-planner agent: "Create an implementation-focused work plan from design document at [design-doc-path]. Include generated test skeleton artifact paths from the previous step when present. Plan only repository implementation outcomes required by the Design Doc." +- Invoke work-planner agent: "Create an implementation-focused work plan from design document at [design-doc-path]. Include generated test skeleton artifact paths from the previous step when present. Plan only repository implementation outcomes required by the Design Doc." - Verify the returned Work Plan path and use it as the Step 4 review target ### Step 4: Work Plan Review **Review reception:** Unnecessary repairs create lasting work. Before assigning a fix, use Review Resolution to judge no change, removal or narrowing, and reuse first; record why any retained or added mechanism is necessary. -Spawn document-reviewer agent: "Review the work plan. doc_type: WorkPlan. target: [work-planner completed path]. Verify Design Doc implementation coverage, absence of added operational scope, dependency order, executable verification, optional Verification Focus, and Review Scope." +Invoke document-reviewer agent: "Review the work plan. doc_type: WorkPlan. target: [work-planner completed path]. Verify Design Doc implementation coverage, absence of added operational scope, dependency order, executable verification, optional Verification Focus, and Review Scope." Branch on `verdict.decision`: - `pass` -> proceed to Step 5 diff --git a/.agents/skills/recipe-reverse-engineer/SKILL.md b/.agents/skills/recipe-reverse-engineer/SKILL.md index 85fd8dd..8c5f455 100644 --- a/.agents/skills/recipe-reverse-engineer/SKILL.md +++ b/.agents/skills/recipe-reverse-engineer/SKILL.md @@ -10,7 +10,7 @@ description: "Generate PRD and Design Docs from existing codebase through discov 3. [LOAD IF NOT ACTIVE] `subagents-orchestration-guide` — agent coordination and review resolution 4. [LOAD IF NOT ACTIVE] `llm-friendly-context` — generated document handoffs -**Spawn rule**: every `spawn_agent` call uses `fork_turns="none"` so the subagent receives only the task message and explicitly provided context. +**Invocation rule**: Start each named agent with `spawn_agent` and `fork_turns="none"`. When invoking the same named agent again within this flow, use `followup_task` on its existing instance with the inputs specified for the current invocation. **Context**: Reverse engineering workflow to create documentation from existing code @@ -59,7 +59,7 @@ Phase 2: Design Doc Generation (if requested) ### Step 1: PRD Scope Discovery -Spawn scope-discoverer agent: "Discover functional scope targets in the codebase. target_path: $USER_TARGET_PATH. reference_architecture: $USER_RA_CHOICE. focus_area: $USER_FOCUS_AREA (if specified)." +Invoke scope-discoverer agent: "Discover functional scope targets in the codebase. target_path: $USER_TARGET_PATH. reference_architecture: $USER_RA_CHOICE. focus_area: $USER_FOCUS_AREA (if specified)." **Store output as**: `$STEP_1_OUTPUT` @@ -80,7 +80,7 @@ Spawn scope-discoverer agent: "Discover functional scope targets in the codebase Set `$PRD_UNIT_INVENTORY` to the category-wise deduplicated union of `unitInventory` from the `$STEP_1_OUTPUT.discoveredUnits` named by `$PRD_UNIT_SOURCE_UNITS`, preserving its `routes`, `testFiles`, and `publicExports` arrays. -Spawn prd-creator agent: "Create reverse-engineered PRD for the following feature. Operation Mode: reverse-engineer. External Scope Provided: true. Feature: $PRD_UNIT_NAME. Description: $PRD_UNIT_DESCRIPTION. Related Files: $PRD_UNIT_COMBINED_RELATED_FILES. Entry Points: $PRD_UNIT_COMBINED_ENTRY_POINTS. Source Units: $PRD_UNIT_SOURCE_UNITS. Unit Inventory: $PRD_UNIT_INVENTORY. Use provided scope as an investigation starting point. If tracing entry points reveals directly connected files outside this scope, include them. Create final version PRD based on thorough code investigation." +Invoke prd-creator agent: "Create reverse-engineered PRD for the following feature. Operation Mode: reverse-engineer. External Scope Provided: true. Feature: $PRD_UNIT_NAME. Description: $PRD_UNIT_DESCRIPTION. Related Files: $PRD_UNIT_COMBINED_RELATED_FILES. Entry Points: $PRD_UNIT_COMBINED_ENTRY_POINTS. Source Units: $PRD_UNIT_SOURCE_UNITS. Unit Inventory: $PRD_UNIT_INVENTORY. Use provided scope as an investigation starting point. If tracing entry points reveals directly connected files outside this scope, include them. Create final version PRD based on thorough code investigation." **Store output as**: `$STEP_2_OUTPUT` (PRD path) @@ -90,7 +90,7 @@ Spawn prd-creator agent: "Create reverse-engineered PRD for the following featur **Prerequisite**: $STEP_2_OUTPUT (PRD path from Step 2) -Spawn code-verifier agent: "Verify consistency between PRD and code implementation. doc_type: prd. document_path: $STEP_2_OUTPUT. code_paths: $PRD_UNIT_COMBINED_RELATED_FILES. unit_inventory: $PRD_UNIT_INVENTORY." +Invoke code-verifier agent: "Verify consistency between PRD and code implementation. doc_type: prd. document_path: $STEP_2_OUTPUT. code_paths: $PRD_UNIT_COMBINED_RELATED_FILES. unit_inventory: $PRD_UNIT_INVENTORY." Apply Review Resolution to every discrepancy. Pass the `apply` discrepancies to prd-creator in update mode, rerun code-verifier, and store the resolved summary, declines with reasons, and material limitations as `$STEP_3_RESOLUTION` after the `apply` set becomes empty. A blocked or unusable result enters Orchestrator Escalation Resolution. @@ -98,7 +98,7 @@ Apply Review Resolution to every discrepancy. Pass the `apply` discrepancies to **Required Input**: $STEP_3_RESOLUTION (resolved verification evidence from Step 3) -Spawn document-reviewer agent: "Review the following PRD. doc_type: PRD. target: $STEP_2_OUTPUT. verification_resolution: $STEP_3_RESOLUTION. Review alignment between PRD claims, resolved verification evidence, and in-scope inventory coverage." +Invoke document-reviewer agent: "Review the following PRD. doc_type: PRD. target: $STEP_2_OUTPUT. verification_resolution: $STEP_3_RESOLUTION. Review alignment between PRD claims, resolved verification evidence, and in-scope inventory coverage." **Store output as**: `$STEP_4_OUTPUT` @@ -180,13 +180,13 @@ Map PRD units to Design Doc generation targets by resolving each PRD unit's `sou **Scope**: Document current architecture as-is. This is a documentation task, not a design improvement task. -Spawn technical-designer agent: "Create Design Doc for the following feature based on existing code. Operation Mode: reverse-engineer. Feature: $UNIT_NAME. Description: $UNIT_DESCRIPTION. Primary Files: $UNIT_PRIMARY_MODULES. Public Interfaces: $UNIT_PUBLIC_INTERFACES. Dependencies: $UNIT_DEPENDENCIES. Unit Inventory: $UNIT_INVENTORY. Parent PRD: $APPROVED_PRD_PATH. Document current architecture as-is. Use Unit Inventory as the completeness baseline." +Invoke technical-designer agent: "Create Design Doc for the following feature based on existing code. Operation Mode: reverse-engineer. Feature: $UNIT_NAME. Description: $UNIT_DESCRIPTION. Primary Files: $UNIT_PRIMARY_MODULES. Public Interfaces: $UNIT_PUBLIC_INTERFACES. Dependencies: $UNIT_DEPENDENCIES. Unit Inventory: $UNIT_INVENTORY. Parent PRD: $APPROVED_PRD_PATH. Document current architecture as-is. Use Unit Inventory as the completeness baseline." **Store output as**: `$STEP_7_OUTPUT` #### Step 8: Code Verification -Spawn code-verifier agent: "Verify consistency between Design Doc and code implementation. doc_type: design-doc. document_path: $STEP_7_OUTPUT. code_paths: $UNIT_SCOPE_BOUNDARY. unit_inventory: $UNIT_INVENTORY." +Invoke code-verifier agent: "Verify consistency between Design Doc and code implementation. doc_type: design-doc. document_path: $STEP_7_OUTPUT. code_paths: $UNIT_SCOPE_BOUNDARY. unit_inventory: $UNIT_INVENTORY." Apply Review Resolution to every discrepancy. Pass the `apply` discrepancies to technical-designer in update mode, rerun code-verifier, and store the resolved summary, declines with reasons, and material limitations as `$STEP_8_RESOLUTION` after the `apply` set becomes empty. A blocked or unusable result enters Orchestrator Escalation Resolution. @@ -194,7 +194,7 @@ Apply Review Resolution to every discrepancy. Pass the `apply` discrepancies to **Required Input**: $STEP_8_RESOLUTION (resolved verification evidence from Step 8) -Spawn document-reviewer agent: "Review the following Design Doc. doc_type: DesignDoc. review_context: as-is. target: $STEP_7_OUTPUT. verification_resolution: $STEP_8_RESOLUTION. Parent PRD: $APPROVED_PRD_PATH. Review technical accuracy, parent PRD scope, and in-scope unit boundary coverage." +Invoke document-reviewer agent: "Review the following Design Doc. doc_type: DesignDoc. review_context: as-is. target: $STEP_7_OUTPUT. verification_resolution: $STEP_8_RESOLUTION. Parent PRD: $APPROVED_PRD_PATH. Review technical accuracy, parent PRD scope, and in-scope unit boundary coverage." **Store output as**: `$STEP_9_OUTPUT` diff --git a/.agents/skills/recipe-review/SKILL.md b/.agents/skills/recipe-review/SKILL.md index b205edc..115196d 100644 --- a/.agents/skills/recipe-review/SKILL.md +++ b/.agents/skills/recipe-review/SKILL.md @@ -11,7 +11,7 @@ description: "Reviews completed implementation for governing-source compliance, 4. [LOAD IF NOT ACTIVE] `llm-friendly-context` — task file contract 5. [LOAD IF NOT ACTIVE] `subagents-orchestration-guide` — agent coordination and result handling -**Spawn rule**: every `spawn_agent` call uses `fork_turns="none"` so the subagent receives only the task message and explicitly provided context. +**Invocation rule**: Start each named agent with `spawn_agent` and `fork_turns="none"`. When invoking the same named agent again within this flow, use `followup_task` on its existing instance with the inputs specified for the current invocation. **Context**: Post-implementation quality assurance @@ -23,12 +23,12 @@ description: "Reviews completed implementation for governing-source compliance, ## Execution Method -- Implementation review -> Spawn code-reviewer agent -- Security validation -> Spawn security-reviewer agent -- Code-side fix path -> Spawn task-executor agent -- Design-side update path -> Spawn technical-designer in update mode, then document-reviewer, then design-sync when multiple Design Docs exist -- Quality checks -> Spawn quality-fixer agent -- Re-validation -> Spawn code-reviewer / security-reviewer agents +- Implementation review -> Invoke code-reviewer agent +- Security validation -> Invoke security-reviewer agent +- Code-side fix path -> Invoke task-executor agent +- Design-side update path -> Invoke technical-designer in update mode, then document-reviewer, then design-sync when multiple Design Docs exist +- Quality checks -> Invoke quality-fixer agent +- Re-validation -> Invoke code-reviewer / security-reviewer agents Orchestrator spawns sub-agents and passes structured data between them. @@ -41,12 +41,12 @@ Identify the Design Doc in `docs/design/`. Derive `$STEP_1_FILES` as the complet If a single active work plan is explicitly provided or unambiguously resolved for that Design Doc, read its `Review Scope` line. Otherwise set `Work Plan: none` and `Review Scope: none`; do not infer. ### Step 2: Execute code-reviewer -Spawn code-reviewer agent: "Review the completed implementation. governingDocuments: [{type: design-doc, path: [path]}]. Work Plan: [resolved work plan path or none]. Review Scope: [literal Review Scope value or none]. implementationFiles: [$STEP_1_FILES]. Return the initial review JSON." +Invoke code-reviewer agent: "Review the completed implementation. governingDocuments: [{type: design-doc, path: [path]}]. Work Plan: [resolved work plan path or none]. Review Scope: [literal Review Scope value or none]. implementationFiles: [$STEP_1_FILES]. Return the initial review JSON." **Store output as**: `$STEP_2_OUTPUT` ### Step 3: Execute security-reviewer -Spawn security-reviewer with `governingDocuments: [{type: "design-doc", path: [path]}]` and `implementationFiles: $STEP_1_FILES`. +Invoke security-reviewer with `governingDocuments: [{type: "design-doc", path: [path]}]` and `implementationFiles: $STEP_1_FILES`. **Store output as**: `$STEP_3_OUTPUT` @@ -98,9 +98,9 @@ Use the llm-friendly-context Task File Contract. Run this step only when the user selects a design-side correction. -1. Spawn technical-designer agent in update mode: "Update Design Doc at [path]. Apply the selected Review Resolution disposition to these findings; neither existing implementation nor the prior design is automatically correct: [d-routed findings with code locations and current Design Doc values]. Update the relevant sections and add change history." -2. Spawn document-reviewer agent: "Review updated Design Doc at [path] for consistency and completeness. doc_type: DesignDoc. review_context: update." -3. If multiple Design Docs exist in `docs/design/`, spawn design-sync agent: "Check cross-Design Doc consistency after updating [path]." +1. Invoke technical-designer agent in update mode: "Update Design Doc at [path]. Apply the selected Review Resolution disposition to these findings; neither existing implementation nor the prior design is automatically correct: [d-routed findings with code locations and current Design Doc values]. Update the relevant sections and add change history." +2. Invoke document-reviewer agent: "Review updated Design Doc at [path] for consistency and completeness. doc_type: DesignDoc. review_context: update." +3. If multiple Design Docs exist in `docs/design/`, invoke design-sync agent: "Check cross-Design Doc consistency after updating [path]." 4. If the user selected both routes, re-evaluate the code-side findings against the updated Design Doc and drop any that are now satisfied. ### Step 6: Create Task File @@ -110,21 +110,21 @@ Include only findings selected for code-side correction. ### Step 7: Execute Fixes -Spawn task-executor agent: "Execute the accepted review fixes. Task file: docs/plans/tasks/review-fixes-task-01.md." +Invoke task-executor agent: "Execute the accepted review fixes. Task file: docs/plans/tasks/review-fixes-task-01.md." Start the Per-Task Change Set before execution. Inspect the executor result and repository diff, add its paths, and continue when the requested fixes are present; resolve an incomplete or unusable result through Orchestrator Escalation Resolution. ### Step 8: Quality Check -Spawn quality-fixer with `task_file`, `filesModified: taskWriteSet`, and executor operation-verification evidence. On pass, add its paths and commit the reconciled Per-Task Change Set; repair stubs through task-executor, accumulate their paths, and resolve blocked results through Orchestrator Escalation Resolution. +Invoke quality-fixer with `task_file`, `filesModified: taskWriteSet`, and executor operation-verification evidence. On pass, add its paths and commit the reconciled Per-Task Change Set; repair stubs through task-executor, accumulate their paths, and resolve blocked results through Orchestrator Escalation Resolution. ### Step 9: Re-validate code-reviewer -Spawn code-reviewer with the original governing documents and implementation change set, plus `prior_feedback: [the complete Step 2 result, applied corrections, declined finding IDs with reasons and evidence, and the correction paths or diff]`. Apply its Rerun Boundary. +Invoke code-reviewer with the original governing documents and implementation change set, plus `prior_feedback: [the complete Step 2 result, applied corrections, declined finding IDs with reasons and evidence, and the correction paths or diff]`. Apply its Rerun Boundary. ### Step 10: Re-validate security-reviewer -Spawn security-reviewer with `governingDocuments: [{type: "design-doc", path: [path]}]`, the actual implementation and fix files, and `prior_feedback: [applied corrections and declined finding IDs with reasons and evidence from Step 4]`. +Invoke security-reviewer with `governingDocuments: [{type: "design-doc", path: [path]}]`, the actual implementation and fix files, and `prior_feedback: [applied corrections and declined finding IDs with reasons and evidence from Step 4]`. After any code fix, both Steps 9 and 10 are mandatory even when only one reviewer initially reported a finding. @@ -150,8 +150,8 @@ Remaining issues: ## Completion Criteria - [ ] Design Doc identified and implementation files checked -- [ ] code-reviewer spawned and compliance validated -- [ ] security-reviewer spawned and security reviewed +- [ ] code-reviewer invoked and compliance validated +- [ ] security-reviewer invoked and security reviewed - [ ] Results presented to user - [ ] Fixes executed if user approved (with quality-fixer gate) - [ ] Re-validation completed after fixes (both code and security) diff --git a/.agents/skills/recipe-update-doc/SKILL.md b/.agents/skills/recipe-update-doc/SKILL.md index e206f0f..0709dea 100644 --- a/.agents/skills/recipe-update-doc/SKILL.md +++ b/.agents/skills/recipe-update-doc/SKILL.md @@ -9,7 +9,7 @@ description: "Update existing design documents (Design Doc / PRD / ADR) with rev 2. [LOAD IF NOT ACTIVE] `subagents-orchestration-guide` — agent coordination and workflow flows 3. [LOAD IF NOT ACTIVE] `llm-friendly-context` — document update and review handoffs -**Spawn rule**: every `spawn_agent` call uses `fork_turns="none"` so the subagent receives only the task message and explicitly provided context. +**Invocation rule**: Start each named agent with `spawn_agent` and `fork_turns="none"`. When invoking the same named agent again within this flow, use `followup_task` on its existing instance with the inputs specified for the current invocation. **Context**: Dedicated to updating existing design documents. @@ -97,9 +97,9 @@ For PRD or Design Doc updates, apply the confirmed changes to the target documen ### Step 4: Document Update -For PRD or Design Doc, spawn [Update Agent from Step 2]: "Operation Mode: update. Existing Document: [path from Step 1]. Changes Required: [Changes clarified in Step 3]. confirmed_requirement_context: [Step 3 current context]. Update the document to reflect the specified changes. Add change history entry." +For PRD or Design Doc, invoke [Update Agent from Step 2]: "Operation Mode: update. Existing Document: [path from Step 1]. Changes Required: [Changes clarified in Step 3]. confirmed_requirement_context: [Step 3 current context]. Update the document to reflect the specified changes. Add change history entry." -For a minor ADR change, spawn the update agent with `Operation Mode: update`, the existing path, confirmed changes, and `confirmed_requirement_context: N/A — ADR update`. For a major ADR change, apply documentation-criteria's choice and durability filters. Update or retire an unnecessary choice in the existing record; create a superseding ADR only for a qualifying new decision. Existing execution authority remains valid for outcome-preserving technical reductions. +For a minor ADR change, invoke the update agent with `Operation Mode: update`, the existing path, confirmed changes, and `confirmed_requirement_context: N/A — ADR update`. For a major ADR change, apply documentation-criteria's choice and durability filters. Update or retire an unnecessary choice in the existing record; create a superseding ADR only for a qualifying new decision. Existing execution authority remains valid for outcome-preserving technical reductions. ### Step 5: Document Review @@ -107,14 +107,14 @@ For a minor ADR change, spawn the update agent with `Operation Mode: update`, th For Design Doc updates, first verify the updated document against code: -Spawn code-verifier agent: "Verify the updated Design Doc against current code. doc_type: design-doc. document_path: [path from Step 1]. Focus especially on literal identifier referential integrity for concrete paths, endpoints, type names, config keys, and other exact identifiers changed in this update." +Invoke code-verifier agent: "Verify the updated Design Doc against current code. doc_type: design-doc. document_path: [path from Step 1]. Focus especially on literal identifier referential integrity for concrete paths, endpoints, type names, config keys, and other exact identifiers changed in this update." Apply Review Resolution to every discrepancy. Pass the `apply` discrepancies to the update agent, rerun code-verifier, and store the resolved summary, declines with reasons, and material limitations as `$VERIFICATION_RESOLUTION` after the `apply` set becomes empty. For Design Doc updates: -Spawn document-reviewer agent: "Review the following updated document. doc_type: DesignDoc. review_context: update. target: [path from Step 1]. confirmed_requirement_context: [Step 3 current context]. verification_resolution: $VERIFICATION_RESOLUTION. Focus on consistency of the updated sections, governing requirements, and change history." +Invoke document-reviewer agent: "Review the following updated document. doc_type: DesignDoc. review_context: update. target: [path from Step 1]. confirmed_requirement_context: [Step 3 current context]. verification_resolution: $VERIFICATION_RESOLUTION. Focus on consistency of the updated sections, governing requirements, and change history." -For PRD updates, spawn document-reviewer with the target and `confirmed_requirement_context` from Step 3. For minor ADR updates, use `doc_type: ADRBatch`, `targets: [updated ADR path]`, and `review_context: update`; review the requested changes and their dependent consistency while carrying the accepted, unchanged decision content as governing context. +For PRD updates, invoke document-reviewer with the target and `confirmed_requirement_context` from Step 3. For minor ADR updates, use `doc_type: ADRBatch`, `targets: [updated ADR path]`, and `review_context: update`; review the requested changes and their dependent consistency while carrying the accepted, unchanged decision content as governing context. **Store output as**: `$STEP_5_OUTPUT` @@ -127,7 +127,7 @@ For PRD updates, spawn document-reviewer with the target and `confirmed_requirem For PRD or ADR, proceed directly to finalization below. -For Design Doc, spawn design-sync agent: "Verify consistency of the updated Design Doc with other design documents. Updated document: [path from Step 1]" +For Design Doc, invoke design-sync agent: "Verify consistency of the updated Design Doc with other design documents. Updated document: [path from Step 1]" **On consistency result**: - No conflicts -> Finalize the update below @@ -151,8 +151,8 @@ For Design Doc, spawn design-sync agent: "Verify consistency of the updated Desi - [ ] Built the current `confirmed_requirement_context` from the target document and confirmed changes - [ ] Updated document via appropriate agent (update mode) - [ ] Applied Review Resolution to code-verifier discrepancies before document-reviewer for Design Doc updates -- [ ] Spawned document-reviewer and addressed feedback -- [ ] Spawned design-sync for consistency verification (Design Doc only) +- [ ] Invoked document-reviewer and addressed feedback +- [ ] Invoked design-sync for consistency verification (Design Doc only) - [ ] Finalized the update under Step 6 ## Output Example diff --git a/.agents/skills/subagents-orchestration-guide/SKILL.md b/.agents/skills/subagents-orchestration-guide/SKILL.md index 7281b54..e31020d 100644 --- a/.agents/skills/subagents-orchestration-guide/SKILL.md +++ b/.agents/skills/subagents-orchestration-guide/SKILL.md @@ -7,7 +7,7 @@ description: "Coordinates custom specialists through workflow phases, artifact h Load `subagent-delegation` for assignment, waiting, and intervention rules. This guide owns workflow-specific coordination. -**Spawn rule**: every `spawn_agent` call uses `fork_turns="none"` so the subagent receives only the task message and explicitly provided context. +**Invocation rule**: Start each named agent with `spawn_agent` and `fork_turns="none"`. When invoking the same named agent again within this flow, use `followup_task` on its existing instance with the inputs specified for the current invocation. ## Role: The Orchestrator @@ -69,21 +69,21 @@ Assign work based on each subagent's responsibilities: - Applying explicit user answers and governing-source resolutions - Deterministic commands and lightweight evidence collection needed to route the next step -**What to spawn task-executor for**: +**What to invoke task-executor for**: - Implementation work and test addition - Confirmation of added tests passing (existing tests are not covered) -**What to spawn quality-fixer for**: +**What to invoke quality-fixer for**: - Applicable repository checks discovered from the task, changed files, manifests, configuration, and CI - Complete execution of quality error fixes - Self-contained processing until fix completion - Final approved judgment (only after fixes are complete) -## How to Spawn Agents +## How to Invoke Agents -Apply the Spawn rule above. Resolve missing workflow inputs that affect the next action or its verification from repository and governing evidence; route remaining blockers through Orchestrator Escalation Resolution. +Apply the Invocation rule above. Resolve missing workflow inputs that affect the next action or its verification from repository and governing evidence; route remaining blockers through Orchestrator Escalation Resolution. -### Spawn Prompt Requirements +### Invocation Prompt Requirements - For requirement, design, or scope judgment, supply relevant user wording and explicit constraints through the existing requirement carrier or task message, separately from agent-selected means. A target document alone suffices only when it retains that provenance; otherwise include the source excerpt needed for the decision. diff --git a/.agents/skills/subagents-orchestration-guide/references/lite-mode.md b/.agents/skills/subagents-orchestration-guide/references/lite-mode.md index 08d9808..0c364be 100644 --- a/.agents/skills/subagents-orchestration-guide/references/lite-mode.md +++ b/.agents/skills/subagents-orchestration-guide/references/lite-mode.md @@ -15,6 +15,6 @@ A single-cycle flow without a Work Plan task set, such as Small, keeps its quali ## Final Quality Run -After the last task commit and before Post-Implementation Review, spawn the routed quality fixer once per layer with completed tasks. Pass its usual inputs with values for that layer's whole task set: the Work Plan as `task_file`, the union of the tasks' `taskWriteSet` as `filesModified`, and the executors' operation-verification evidence. +After the last task commit and before Post-Implementation Review, invoke the routed quality fixer once per layer with completed tasks. Pass its usual inputs with values for that layer's whole task set: the Work Plan as `task_file`, the union of the tasks' `taskWriteSet` as `filesModified`, and the executors' operation-verification evidence. Route the result as per-task cycle step 3. For `stub_detected`, repair through the owning task's implementation owner, then repeat the Final Quality Run. Commit the resulting fixes once as a reconciled change set. diff --git a/.agents/skills/subagents-orchestration-guide/references/monorepo-flow.md b/.agents/skills/subagents-orchestration-guide/references/monorepo-flow.md index 96aa182..44c75d6 100644 --- a/.agents/skills/subagents-orchestration-guide/references/monorepo-flow.md +++ b/.agents/skills/subagents-orchestration-guide/references/monorepo-flow.md @@ -58,35 +58,35 @@ The tables show agent work and results. User confirmation and implementation aut ### Parallelization in Multi-Agent Steps -Steps marked `x2` run independently per layer and can execute in parallel when supported. `ui-analyzer` may run alongside codebase analysis when its inputs are ready. For the ADR step, route layer-owned decision points to the matching technical designer and cross-layer points to technical-designer, collect every returned path, and invoke document-reviewer once with `doc_type: ADRBatch` and the complete `targets` array. +Steps marked `x2` invoke the same named agent once per layer in sequence. `ui-analyzer` may run alongside codebase analysis when its inputs are ready. For the ADR step, route layer-owned decision points to the matching technical designer and cross-layer points to technical-designer, collect every returned path, and invoke document-reviewer once with `doc_type: ADRBatch` and the complete `targets` array. External evidence and prototype inputs are conditional. Load `external-resource-context` when external evidence changes the current UI or verification decision; otherwise continue with `none`. Prototype input follows the frontend rule: use a supplied or target-referenced prototype, request its path only when the UI target otherwise cannot be determined, and resolve and deliver `prototype_reference_strength` through the shared UI Spec rule. ### Layer Context in Design Doc Creation -When spawning Design Doc creation for each layer, pass explicit context: +When invoking Design Doc creation for each layer, pass explicit context: | Scale | Concrete context value | |-------|------------------------| | Large | `context: { scale: "large", prd_path: "[path]", scope_evidence: [layer-filtered compact evidence] }` | | Medium | `context: { scale: "medium", prd_path: null, scope_evidence: [layer-filtered compact evidence], convergence: [confirmed record] }` | -Before spawning, replace every context placeholder with a concrete context object for the active flow scale. For filtered context placeholders, use the same `scale` and `prd_path` values and the layer-filtered compact evidence. +Before invoking, replace every context placeholder with a concrete context object for the active flow scale. For filtered context placeholders, use the same `scale` and `prd_path` values and the layer-filtered compact evidence. **Backend Design Doc**: -**Agent**: Spawn technical-designer +**Agent**: Invoke technical-designer > "Create a backend Design Doc. context: [context]. adr_paths: [accepted ADR paths]. decision_materials: [backend analysis material that changes reuse, simplification, validity, a selected decision, contract, or verification]. Reference approved UI Spec at [path] only for displayed values whose source data crosses a backend-owned contract." **Fullstack Codebase Analysis**: -**Agent**: Spawn codebase-analyzer +**Agent**: Invoke codebase-analyzer > "exploration_mode: [mode from Analysis Assignment]. Analyze the complete confirmed feature to provide compact decision materials for ADR selection, both layer designs, and verification. requirement_analysis: [complete confirmed scope evidence]. requirements: [confirmed requirements]. prd_path: [current PRD path when present]. target_paths: [confirmed scope]. focus_areas: responsibility ownership, cross-layer data and contracts, reuse, and verification." **Frontend Design Doc**: -**Agent**: Spawn technical-designer-frontend +**Agent**: Invoke technical-designer-frontend > "Create a frontend Design Doc. context: [context]. adr_paths: [accepted ADR paths]. decision_materials: [frontend/UI material that changes reuse, simplification, validity, a selected decision, contract, or verification]. Reference backend Design Doc at [path] for API contracts and Integration Points. Reference UI Spec at [path] for component structure and state design." **Frontend UI Analysis**: -**Agent**: Spawn ui-analyzer +**Agent**: Invoke ui-analyzer > "exploration_mode: [mode from Analysis Assignment]. prior_evidence: [relevant fullstack codebase findings when available]. Gather UI facts for frontend design. requirement_analysis: [frontend-filtered confirmed scope evidence]. requirements: [confirmed requirements]. target_paths: [frontend file and directory scope]. target_components: [frontend target components]. prototype_path: [path if provided]. externalResourceRefs: [{label, featureIdentifier} selected by the external-evidence step, or []]. focus_areas: [remaining rendering, interaction, and visual questions]." ### Verification Resolution @@ -95,13 +95,13 @@ Apply Review Resolution independently to each code-verifier result, using the ma ### design-sync for Cross-Layer Verification -Spawn design-sync with `source_design` = frontend Design Doc (created last, referencing backend's Integration Points). design-sync auto-discovers other Design Docs in `docs/design/` for comparison. +Invoke design-sync with `source_design` = frontend Design Doc (created last, referencing backend's Integration Points). design-sync auto-discovers other Design Docs in `docs/design/` for comparison. At Design Confirmation, use the shared alignment for the feature across both layers. ## Test Skeleton Generation Phase -Spawn acceptance-test-generator with all Design Docs and UI Spec: +Invoke acceptance-test-generator with all Design Docs and UI Spec: > "Generate test skeletons from the following documents: Design Doc (backend): [path], Design Doc (frontend): [path], UI Spec: [path] (if exists)" @@ -109,13 +109,13 @@ Verify generated artifact paths and continue with them; an empty selection is va ## Work Planning Phase -Spawn work-planner with all Design Docs: +Invoke work-planner with all Design Docs: > "Create an implementation-focused work plan from the following documents: PRD: [path] (Large Scale only), Design Doc (backend): [path], Design Doc (frontend): [path], UI Spec: [path] (if exists). Test skeleton artifact paths from acceptance-test-generator: [artifacts[].path]. Compose phases around shared backend/frontend verification points and plan only repository implementation outcomes required by the Design Docs." Verify the returned Work Plan path and use it as the document-reviewer target. -After work-planner creates or updates the plan, spawn document-reviewer: +After work-planner creates or updates the plan, invoke document-reviewer: > "Review the fullstack work plan. doc_type: WorkPlan. target: [work plan path]. Verify Design Doc and UI Spec implementation coverage, repository-only scope, cross-layer dependency order, executable verification, optional Verification Focus, and Review Scope." diff --git a/.codex/agents/technical-designer-frontend.toml b/.codex/agents/technical-designer-frontend.toml index 9602794..1e14450 100644 --- a/.codex/agents/technical-designer-frontend.toml +++ b/.codex/agents/technical-designer-frontend.toml @@ -34,9 +34,11 @@ Use a prototype or recorded external resource only when it supplies a current UI ## Exceptional Evidence Probe -Start from the smallest direct design. Spawn a `technical-spike` only when design selection depends on an unobserved technical question that a bounded repository probe can establish. Each probe addresses one design-changing question. Apply its evidence before considering another probe, and run another only when a remaining unresolved question can still change the selected design. An optional addition whose removal leaves the confirmed outcome satisfied is removed without a probe. +Start from the smallest direct design. Invoke a `technical-spike` only when design selection depends on an unobserved technical question that a bounded repository probe can establish. Each probe addresses one design-changing question. Apply its evidence before considering another probe, and run another only when a remaining unresolved question can still change the selected design. An optional addition whose removal leaves the confirmed outcome satisfied is removed without a probe. -Spawn `technical-spike` with `fork_turns="none"` using this call contract: `decision` (the confirmed outcome, requirement, and design selection the evidence will resolve), `probe` (one claim, capability, or option set to observe, with a reference or comparator only when the decision needs one), `evidenceNeeded` (representative inputs, observable measures, and decision conditions), and `repositoryContext` (only the paths, commands, and constraints needed to run the probe). The probe chooses a disposable temporary scope and returns observations and limitations; you own the design decision. Record the observations and limitations in `Existing Evidence` when they change a Design Doc selection. Use the evidence to select the smallest sufficient design whose outcome benefit justifies total complexity, and remove an optional element when its benefit is not shown. Report blocked only when the confirmed outcome cannot be designed without the unavailable evidence. +**Invocation rule**: Start each named agent with `spawn_agent` and `fork_turns="none"`. When invoking the same named agent again within this flow, use `followup_task` on its existing instance with the inputs specified for the current invocation. + +Invoke `technical-spike` using this call contract: `decision` (the confirmed outcome, requirement, and design selection the evidence will resolve), `probe` (one claim, capability, or option set to observe, with a reference or comparator only when the decision needs one), `evidenceNeeded` (representative inputs, observable measures, and decision conditions), and `repositoryContext` (only the paths, commands, and constraints needed to run the probe). The probe chooses a disposable temporary scope and returns observations and limitations; you own the design decision. Record the observations and limitations in `Existing Evidence` when they change a Design Doc selection. Use the evidence to select the smallest sufficient design whose outcome benefit justifies total complexity, and remove an optional element when its benefit is not shown. Report blocked only when the confirmed outcome cannot be designed without the unavailable evidence. ## ADR Batch — Create Mode diff --git a/.codex/agents/technical-designer.toml b/.codex/agents/technical-designer.toml index 45fb402..b444f43 100644 --- a/.codex/agents/technical-designer.toml +++ b/.codex/agents/technical-designer.toml @@ -35,9 +35,11 @@ Identify applicable project standards and quality commands from supplied analysi ## Exceptional Evidence Probe -Start from the smallest direct design. Spawn a `technical-spike` only when design selection depends on an unobserved technical question that a bounded repository probe can establish. Each probe addresses one design-changing question. Apply its evidence before considering another probe, and run another only when a remaining unresolved question can still change the selected design. An optional addition whose removal leaves the confirmed outcome satisfied is removed without a probe. +Start from the smallest direct design. Invoke a `technical-spike` only when design selection depends on an unobserved technical question that a bounded repository probe can establish. Each probe addresses one design-changing question. Apply its evidence before considering another probe, and run another only when a remaining unresolved question can still change the selected design. An optional addition whose removal leaves the confirmed outcome satisfied is removed without a probe. -Spawn `technical-spike` with `fork_turns="none"` using this call contract: `decision` (the confirmed outcome, requirement, and design selection the evidence will resolve), `probe` (one claim, capability, or option set to observe, with a reference or comparator only when the decision needs one), `evidenceNeeded` (representative inputs, observable measures, and decision conditions), and `repositoryContext` (only the paths, commands, and constraints needed to run the probe). The probe chooses a disposable temporary scope and returns observations and limitations; you own the design decision. Record the observations and limitations in `Existing Evidence` when they change a Design Doc selection. Use the evidence to select the smallest sufficient design whose outcome benefit justifies total complexity, and remove an optional element when its benefit is not shown. Report blocked only when the confirmed outcome cannot be designed without the unavailable evidence. +**Invocation rule**: Start each named agent with `spawn_agent` and `fork_turns="none"`. When invoking the same named agent again within this flow, use `followup_task` on its existing instance with the inputs specified for the current invocation. + +Invoke `technical-spike` using this call contract: `decision` (the confirmed outcome, requirement, and design selection the evidence will resolve), `probe` (one claim, capability, or option set to observe, with a reference or comparator only when the decision needs one), `evidenceNeeded` (representative inputs, observable measures, and decision conditions), and `repositoryContext` (only the paths, commands, and constraints needed to run the probe). The probe chooses a disposable temporary scope and returns observations and limitations; you own the design decision. Record the observations and limitations in `Existing Evidence` when they change a Design Doc selection. Use the evidence to select the smallest sufficient design whose outcome benefit justifies total complexity, and remove an optional element when its benefit is not shown. Report blocked only when the confirmed outcome cannot be designed without the unavailable evidence. ## ADR Batch — Create Mode diff --git a/package.json b/package.json index 01aa268..5682080 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "codex-workflows", - "version": "1.6.0", + "version": "1.7.0", "description": "Codex CLI workflows that keep larger software changes within the approved scope, from planning through review", "license": "MIT", "author": "Shinsuke Kagawa",