codex-workflows 0.4.11 → 0.6.0

package/.agents/skills/recipe-prepare-implementation/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: recipe-prepare-implementation
+description: "Verify that an approved work plan is implementable before build execution, resolving readiness gaps through Phase 0 prep tasks when needed."
+---
+
+## Required Skills [LOAD BEFORE EXECUTION]
+
+1. [LOAD IF NOT ACTIVE] `coding-rules` -- coding standards
+2. [LOAD IF NOT ACTIVE] `testing` -- test strategy and quality gates
+3. [LOAD IF NOT ACTIVE] `ai-development-guide` -- AI development patterns
+4. [LOAD IF NOT ACTIVE] `documentation-criteria` -- document templates
+5. [LOAD IF NOT ACTIVE] `subagents-orchestration-guide` -- agent coordination
+
+**Spawn rule**: every `spawn_agent` call MUST pass `fork_turns="none"` or `fork_context=false` for context isolation.
+
+## Purpose
+
+Run this recipe after work-plan approval and before any build or implementation execution. It verifies that the plan can be executed from Phase 1 onward without missing verification references, test prerequisites, UI render surfaces, or local execution instructions.
+
+The recipe is safe to invoke unconditionally. If all readiness criteria pass, it only updates the work plan readiness marker and report.
+
+Work plan: $ARGUMENTS
+
+## Readiness Marker Contract
+
+Use the Implementation Readiness Marker Contract defined in `subagents-orchestration-guide`. If the line is absent, treat the work plan as `pending` and insert it after `Related Issue/PR:` when persisting the report.
+
+## Readiness Criteria
+
+Each criterion produces `pass`, `fail`, or `not_applicable`, with file:line evidence where possible.
+
+| ID | Criterion | Pass Evidence |
+|----|-----------|---------------|
+| R1 | Verification Strategy references resolve | Every command, file path, function, endpoint, fixture, seed, and test reference in the work plan's Verification Strategies either exists now or is the deliverable of a task in the plan |
+| R2 | E2E prerequisites are addressed | For each fixture-e2e or service-integration-e2e skeleton, every noted precondition is present in the codebase or covered by a Phase 0 task |
+| R3 | Phase 1 observability exists | The first implementation phase includes at least one operation verification method executable at task completion using existing files, prior Phase 0 deliverables, or the task's own output |
+| R4 | UI rendering surface exists | When the plan implements UI components, a fixture entry, dev route, Storybook story, preview harness, or equivalent render surface exists or is covered by a Phase 0 task |
+| R5 | Local lane procedure exists | The work plan or referenced docs record commands needed to run the relevant local service stack or browser harness, including startup commands, ports, seed steps, and required environment variables |
+
+R4 applies only to UI work. R5 applies when the plan uses a local service stack or browser harness.
+
+## Execution Flow
+
+### Step 1: Load Inputs
+
+Read the work plan passed in `$ARGUMENTS`; if absent, select the most recent non-template `docs/plans/*.md`. Extract:
+- Verification Strategies
+- Quality Assurance Mechanisms
+- Design-to-Plan Traceability
+- UI Spec Component -> Task Mapping
+- Connection Map
+- test skeleton references and E2E absence reasons
+- phase structure and task IDs
+- referenced Design Docs and UI Specs
+
+If no work plan exists, stop and report the missing prerequisite.
+
+### Step 2: Readiness Scan
+
+Evaluate R1-R5 using repository search and the work plan content. Build a `## Implementation Readiness Report` regardless of outcome.
+
+For each `fail`, identify the smallest concrete prep task that closes the gap. Examples:
+- Add fixture data for a UI state
+- Add an API mock handler for fixture-e2e
+- Add a seed script for service-integration-e2e
+- Add a Storybook story, dev route, or equivalent render surface
+- Document local startup commands and required environment variables
+- Add a missing verification helper or script referenced by the plan
+
+### Step 3: No-Op Success
+
+When all applicable criteria are `pass`:
+1. Persist `## Implementation Readiness Report` in the work plan immediately after the header block.
+2. Set `Implementation Readiness: ready`.
+3. Do not create task files.
+4. Report `outcome: ready`.
+
+### Step 4: Create Resolution Tasks
+
+When one or more criteria fail:
+1. Present the proposed prep tasks to the user and continue only after explicit approval.
+2. Create task files in `docs/plans/tasks/` using the task template:
+   - Backend prep: `{plan-name}-backend-task-prep-{NN}.md`
+   - Frontend prep: `{plan-name}-frontend-task-prep-{NN}.md`
+   - Single-layer prep: `{plan-name}-task-prep-{NN}.md`
+3. Insert the tasks into the work plan's existing Phase 0 when one exists. If no Phase 0 exists, create `Phase 0: Implementation Readiness Prep` before Phase 1. Keep existing Phase 0 task IDs stable; assign prep task IDs after existing Phase 0 tasks or use a clearly labeled `P0-PREP-N` identifier when the plan's numbering would otherwise require renumbering.
+4. Each prep task must include Investigation Targets, concrete implementation steps, and Operation Verification Methods.
+
+Layer selection:
+- Use frontend prep when every target is UI, browser harness, component, page, or frontend fixture work.
+- Use backend prep when every target is API, server, service, repository, database, seed, or backend fixture work.
+- Use single-layer prep for non-layered repositories.
+- Escalate if the gap crosses layers and cannot be split into separate prep tasks.
+
+### Step 5: Execute Prep Tasks
+
+Run each prep task through the standard 4-step cycle:
+1. Spawn the layer-appropriate task executor with the exact prep task path in the prompt: "Execute implementation-readiness prep task. Task file: [exact prep task path]."
+2. Check for `blocked` or `escalation_needed`.
+3. Spawn the layer-appropriate quality fixer with the task file as `task_file`.
+4. Commit only when the quality fixer returns `approved`.
+
+Append this scope boundary to every subagent prompt:
+
+```
+[SYSTEM CONSTRAINT]
+This agent operates within implementation-readiness prep scope. Use the task file as the primary instruction source. Do not implement feature behavior beyond the readiness gap described by the task.
+```
+
+### Step 6: Re-Scan and Persist
+
+After prep tasks are complete:
+1. Re-run the readiness scan.
+2. Persist or replace `## Implementation Readiness Report` in the work plan.
+3. Set the header to `Implementation Readiness: ready` when all applicable criteria pass, otherwise `Implementation Readiness: escalated`.
+4. Collapse completed prep tasks out of active plan execution: remove the Phase 0 readiness prep task entries from the work plan and record their committed evidence under `Resolution Tasks Executed` in the Readiness Report. If Phase 0 becomes empty and was created only by this recipe, remove that Phase 0 section. Preserve any pre-existing Phase 0 content.
+5. Delete only these files for the current `{plan-name}`:
+   - `docs/plans/tasks/{plan-name}-task-prep-*.md`
+   - `docs/plans/tasks/{plan-name}-backend-task-prep-*.md`
+   - `docs/plans/tasks/{plan-name}-frontend-task-prep-*.md`
+   - `docs/plans/tasks/{plan-name}-phase0-completion.md`
+6. Report remaining gaps if any.
+
+## Readiness Report Format
+
+```markdown
+## Implementation Readiness Report
+
+Work plan: [path]
+Outcome: ready | escalated
+Gaps resolved: [N]
+phase0_created_by_recipe: true | false
+
+### Readiness Criteria
+
+| ID | Result | Evidence |
+|----|--------|----------|
+| R1 | pass / fail / not_applicable | [file:line or missing reference] |
+| R2 | ... | ... |
+| R3 | ... | ... |
+| R4 | ... | ... |
+| R5 | ... | ... |
+
+### Resolution Tasks Executed
+- [task file path] - [one-line summary] - committed
+
+### Remaining Gaps
+- [criterion ID]: [unresolved reference] - Next action: [recommendation]
+```
+
+## Completion Criteria
+
+- [ ] Work plan loaded and relevant sections extracted
+- [ ] Readiness scan completed with evidence per criterion
+- [ ] No-op success handled when all criteria pass
+- [ ] Failing criteria converted to approved prep tasks when needed
+- [ ] Prep tasks executed through executor -> quality-fixer -> commit
+- [ ] Re-scan completed after prep tasks
+- [ ] Work plan readiness marker updated to `ready` or `escalated`
+- [ ] Readiness Report persisted in the work plan
+- [ ] Completed prep task references collapsed into the Readiness Report
+- [ ] Prep task files created by this recipe removed from `docs/plans/tasks/`

package/.agents/skills/recipe-prepare-implementation/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "recipe-prepare-implementation"
+  short_description: "Preflight work plan readiness before implementation"
+  default_prompt: "Use $recipe-prepare-implementation to verify: "
+
+policy:
+  allow_implicit_invocation: false

package/.agents/skills/recipe-review/SKILL.md

@@ -23,7 +23,8 @@ description: "Design Doc compliance and security validation with optional auto-f
 
 - Compliance validation -> Spawn code-reviewer agent
 - Security validation -> Spawn security-reviewer agent
-- Fix implementation -> Spawn task-executor 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
 
@@ -82,22 +83,47 @@ Security Review: [status from security-reviewer]
   - [policy] [location]: [description] — [rationale]
   Notes: [notes from security-reviewer, if present]
 
-Execute fixes? (y/n):
+Resolve discrepancies by route:
+  c) Code-side fix
+  d) Design-side update
+  s) Skip
+
+Default: accept all recommended routes.
+
+Accepted response formats:
+- empty input -- accept every recommended route
+- `all-recommended` -- accept every recommended route
+- `all:c`, `all:d`, or `all:s` -- apply one route to every finding
+- Per-finding routes, e.g. `F1:c, F2:d, F3:s`
 ```
 
-**[STOP — BLOCKING]** Present results to user for confirmation.
-**CANNOT proceed until user explicitly confirms.**
+Before presenting results, recommend a route for each finding:
+- Use `d` when implementation intent matches the requirement but the Design Doc is stale or too narrow.
+- Use `c` when code drifted from a still-correct Design Doc, or when the finding is reliability, security, or maintainability related.
+- Use `s` only when the user explicitly accepts the current state without changes.
 
-If both pass and user selects `n`: Skip Steps 5-10, proceed to Step 11.
+**[STOP — BLOCKING]** Present results and recommended routes to user for confirmation.
+**CANNOT proceed until user explicitly confirms routes.**
+
+If all findings are skipped: Skip Steps 5-10, proceed to Step 11.
 
 ### Step 5: Prepare Fix Context
 
 Reference documentation-criteria skill for task file template.
 
+### Step 5d: Design-Side Update
+
+Run this step only when the user routes at least one finding to `d`.
+
+1. Spawn technical-designer agent in update mode: "Update Design Doc at [path]. The implementation is being accepted as correct for these findings: [d-routed findings with code locations and current Design Doc values]. Update the relevant sections and add change history."
+2. Spawn document-reviewer agent: "Review updated Design Doc at [path] for consistency and completeness."
+3. If multiple Design Docs exist in `docs/design/`, spawn design-sync agent: "Check cross-Design Doc consistency after updating [path]."
+4. If the user selected both `d` and `c` routes, re-evaluate the `c` findings against the updated Design Doc and drop any that are now satisfied.
+
 ### Step 6: Create Task File
 
 Create task file at `docs/plans/tasks/review-fixes-YYYYMMDD.md`
-Include both code compliance issues and security requiredFixes.
+Include only code-side compliance issues and security requiredFixes routed to `c`.
 
 ### Step 7: Execute Fixes
 
@@ -117,6 +143,8 @@ Spawn security-reviewer agent: "Re-validate security after fixes. Prior findings
 
 ### Step 11: Final Report
 
+Delete the review-fix task file this recipe created, if present. Its work is committed; `docs/plans/` is ephemeral working state.
+
 ```
 Code Compliance:
   Initial: [X]%

package/.agents/skills/subagents-orchestration-guide/SKILL.md

@@ -74,6 +74,7 @@ The following subagents are available:
 13. **code-verifier**: Document-code consistency verification for review inputs and post-implementation verification
 14. **design-sync**: Design Doc consistency verification across multiple documents
 15. **acceptance-test-generator**: Generate integration and E2E test skeletons from Design Doc ACs
+16. **ui-analyzer**: UI fact gathering from external resources and existing frontend code before UI Spec, Design Doc, or adjustment work
 
 ## Orchestration Principles
 
@@ -123,27 +124,10 @@ Close a running subagent only when the user redirects the workflow, the orchestr
 
 Spawn agents using natural language prompts. Provide clear context about what the agent should accomplish. Every `spawn_agent` call MUST include `fork_turns="none"` or `fork_context=false` (see Spawn rule at top of this skill).
 
-### Spawn Examples
+### Spawn Prompt Requirements
 
-Each example below is a spawn with `fork_turns="none"` or `fork_context=false` plus the quoted prompt.
-
-**requirement-analyzer** (`fork_turns="none"` or `fork_context=false`):
-> "Analyze the following requirements and determine the work scale: [user requirements]. Perform requirement analysis and scale determination."
-
-**codebase-analyzer** (`fork_turns="none"` or `fork_context=false`):
-> "Analyze the existing codebase to provide evidence for Design Doc creation. Focus on existing implementations, data model elements, and constraints the design should respect. requirement_analysis: [JSON]. prd_path: [path if available]. requirements: [original user requirements]. layer: [target layer if applicable]. target_paths: [paths if narrowed]. Return codebase facts and focus areas."
-
-**task-executor** (`fork_turns="none"` or `fork_context=false`):
-> "Execute the implementation task defined in docs/plans/tasks/[filename].md. Complete the implementation following TDD Red-Green-Refactor."
-
-**quality-fixer** (`fork_turns="none"` or `fork_context=false`):
-> "Run quality checks on the codebase: static analysis, style check, all test execution. Fix any issues found and report when all checks pass."
-
-**document-reviewer** (`fork_turns="none"` or `fork_context=false`):
-> "Review the document at [path] for quality and rule compliance. Check against documentation-criteria standards."
-
-**design-sync** (`fork_turns="none"` or `fork_context=false`):
-> "Verify consistency between Design Docs in docs/design/. Use [path] as the source document for comparison."
+- Set `fork_context=false` or `fork_turns="none"` on every spawn for context isolation.
+- Each spawn prompt must name the target deliverable, input paths, and expected result. When invoking `task-executor*`, include the exact task file path, for example: `Execute the implementation task. Task file: docs/plans/tasks/[filename].md.`
 
 ## Explicit Stop Points [MANDATORY]
 
@@ -200,6 +184,7 @@ Subagents respond in JSON format. The final response from each JSON-returning su
 |-------|--------------------------------------|
 | `requirement-analyzer` | `scale`, `confidence`, `affectedLayers`, `adrRequired`, `scopeDependencies`, `questions` |
 | `codebase-analyzer` | `focusAreas`, `dataModel`, `qualityAssurance`, `dataTransformationPipelines`, `limitations` |
+| `ui-analyzer` | `externalResources`, `componentStructure`, `propsPatterns`, `cssLayout`, `stateDisplay`, `focusAreas`, `candidateWriteSet`, `limitations` |
 | `task-executor*` | `status`, `escalation_type`, `filesModified`, `requiresTestReview` |
 | `quality-fixer*` | `status`, `reason`, `stubFindings`, `blockingIssues`, `missingPrerequisites` |
 | `document-reviewer` | `verdict.decision`, `verdict.conditions` |
@@ -207,7 +192,34 @@ Subagents respond in JSON format. The final response from each JSON-returning su
 | `design-sync` | `sync_status` |
 | `integration-test-reviewer` | `status`, `requiredFixes` |
 | `security-reviewer` | `status`, `findings`, `notes`, `requiredFixes` |
-| `acceptance-test-generator` | `status`, `generatedFiles`, `e2eAbsenceReason` |
+| `acceptance-test-generator` | `status`, `generatedFiles.integration`, `generatedFiles.fixtureE2e`, `generatedFiles.serviceE2e`, `e2eAbsenceReason.fixtureE2e`, `e2eAbsenceReason.serviceE2e` |
+
+## Implementation Readiness Marker Contract
+
+Work plans use the header line `Implementation Readiness: <status>`.
+
+| Status | Meaning | Consumer Action |
+|--------|---------|-----------------|
+| `pending` | Initial state from work-planner; readiness has not been checked | Present the unchecked state, recommend running implementation readiness preflight, and continue only on explicit user approval |
+| `ready` | Readiness scan completed and no applicable failures remain | Proceed with task execution |
+| `escalated` | Readiness scan completed, but one or more failures remain | Read the work plan's Implementation Readiness Report, present remaining gaps, and continue only on explicit user approval |
+| absent | Older work plan without the marker | Treat as `pending` |
+
+## Implementation Readiness Preflight Procedure
+
+Use this procedure after work-plan approval and before autonomous task execution when the flow needs to verify implementation readiness.
+
+1. Load the approved work plan exact path and extract Verification Strategies, Quality Assurance Mechanisms, Design-to-Plan Traceability, UI Spec Component -> Task Mapping, Connection Map, test skeleton references, E2E absence reasons, phase structure, referenced Design Docs, and UI Specs.
+2. Evaluate these criteria with evidence:
+   - R1 Verification Strategy references resolve
+   - R2 E2E prerequisites are addressed
+   - R3 Phase 1 observability exists
+   - R4 UI rendering surface exists when UI work is present
+   - R5 Local service stack or browser harness procedure exists when applicable
+3. If every applicable criterion passes, persist `## Implementation Readiness Report` in the work plan and set `Implementation Readiness: ready`.
+4. If any criterion fails, create the smallest approved prep tasks that close the gaps, execute each exact prep task file through the standard executor -> quality-fixer -> commit cycle, then re-run the scan.
+5. After re-scan, set `Implementation Readiness: ready` when all applicable criteria pass, otherwise `Implementation Readiness: escalated`, and persist remaining gaps in the Readiness Report.
+6. Collapse completed prep task references into the Readiness Report and delete only the prep task files created for the current work plan.
 
 ## Handling Requirement Changes
 
@@ -216,17 +228,7 @@ requirement-analyzer follows the "completely self-contained" principle and proce
 
 #### How to Integrate Requirements
 
-**Important**: To maximize accuracy, integrate requirements as complete sentences, including all contextual information communicated by the user.
-
-```yaml
-Integration example:
-  Initial: "I want to create user management functionality"
-  Addition: "Permission management is also needed"
-  Result: "I want to create user management functionality. Permission management is also needed.
-
-          Initial requirement: I want to create user management functionality
-          Additional requirement: Permission management is also needed"
-```
+Integrate initial requirements and later additions as complete sentences, preserving all contextual information communicated by the user. The updated input must remain self-contained without relying on prior conversation turns.
 
 ### Update Mode for Document Generation Agents
 Document generation agents (work-planner, technical-designer, prd-creator) can update existing documents in `update` mode.
@@ -350,11 +352,11 @@ Maximum retry count is 1 verification fix cycle. If any failed verifier still fa
 | `codebase-analyzer` | `technical-designer*` | `Codebase Analysis`, including `focusAreas`, `dataModel`, `qualityAssurance`, `dataTransformationPipelines`, `limitations` |
 | `technical-designer*` | `code-verifier` | Design Doc path |
 | `code-verifier` | `document-reviewer` | `code_verification` JSON |
-| `acceptance-test-generator` | `work-planner` | integration test path, E2E path or `null`, `e2eAbsenceReason` when E2E is absent |
+| `acceptance-test-generator` | `work-planner` | `generatedFiles.integration`, `generatedFiles.fixtureE2e`, `generatedFiles.serviceE2e`, `e2eAbsenceReason: { fixtureE2e, serviceE2e }` |
 | Design Doc | `work-planner` | Verification Strategy summary, Output Comparison details, implementation-relevant technical requirements, protected no-change boundaries |
 
 Handoff rules:
-- Verify generated integration and E2E file paths exist before passing them onward
+- Verify generated integration, fixture-e2e, and service-integration-e2e file paths exist before passing them onward
 - Escalate only when required outputs are missing without a valid absence reason
 - Require work-planner to map every carried-forward technical requirement to a covering task or a justified `gap`
 

package/.agents/skills/subagents-orchestration-guide/references/monorepo-flow.md

@@ -10,81 +10,78 @@ This reference defines the orchestration flow for projects spanning multiple lay
 
 ## Design Phase
 
-### Large Scale Fullstack (6+ Files) - 14 Steps
+### Large Scale Fullstack (6+ Files) - 15 Steps
 
 | Step | Agent | Purpose | Output |
 |------|-------|---------|--------|
 | 1 | requirement-analyzer | Requirement analysis + scale determination **[Stop]** | Requirements + scale |
 | 2 | prd-creator | PRD covering entire feature (all layers) | Single PRD |
 | 3 | document-reviewer | PRD review **[Stop]** | Approval |
-| 4 | (orchestrator) | Ask user for prototype code **[Stop]** | Prototype path or none |
-| 5 | ui-spec-designer | UI Spec from PRD + optional prototype | UI Spec |
-| 6 | document-reviewer | UI Spec review **[Stop]** | Approval |
-| 7 | codebase-analyzer x2 | Per-layer codebase analysis before Design Doc creation | Analysis JSON |
-| 8 | technical-designer | **Backend** Design Doc | Backend Design Doc |
-| 9 | technical-designer-frontend | **Frontend** Design Doc (references backend Integration Points + UI Spec) | Frontend Design Doc |
-| 10 | code-verifier x2 | Verify each Design Doc against code | Verification JSON |
-| 11 | document-reviewer x2 | Review each Design Doc with verification evidence | Reviews |
-| 12 | design-sync | Cross-layer consistency verification (source: frontend Design Doc) **[Stop]** | Sync status |
-| 13 | acceptance-test-generator | Integration/E2E test skeleton from cross-layer contracts | Test skeletons |
-| 14 | work-planner | Work plan from all Design Docs **[Stop: Batch approval]** | Work plan |
-
-### Medium Scale Fullstack (3-5 Files) - 12 Steps
+| 4 | (orchestrator) | External resource hearing **[Stop]** | Project context |
+| 5 | (orchestrator) | Ask user for prototype code **[Stop]** | Prototype path or none |
+| 6 | codebase-analyzer x2 + ui-analyzer x1 | Per-layer codebase analysis plus frontend UI analysis | Analysis JSON |
+| 7 | ui-spec-designer | UI Spec from PRD + UI analysis + optional prototype | UI Spec |
+| 8 | document-reviewer | UI Spec review **[Stop]** | Approval |
+| 9 | technical-designer | **Backend** Design Doc | Backend Design Doc |
+| 10 | technical-designer-frontend | **Frontend** Design Doc (references backend Integration Points + UI Spec + UI analysis) | Frontend Design Doc |
+| 11 | code-verifier x2 | Verify each Design Doc against code | Verification JSON |
+| 12 | document-reviewer x2 | Review each Design Doc with verification evidence | Reviews |
+| 13 | design-sync | Cross-layer consistency verification (source: frontend Design Doc) **[Stop]** | Sync status |
+| 14 | acceptance-test-generator | Integration/E2E test skeleton from cross-layer contracts | Test skeletons |
+| 15 | work-planner | Work plan from all Design Docs **[Stop: Batch approval]** | Work plan |
+
+### Medium Scale Fullstack (3-5 Files) - 13 Steps
 
 | Step | Agent | Purpose | Output |
 |------|-------|---------|--------|
 | 1 | requirement-analyzer | Requirement analysis + scale determination **[Stop]** | Requirements + scale |
-| 2 | codebase-analyzer x2 | Per-layer codebase analysis before Design Doc creation | Analysis JSON |
+| 2 | (orchestrator) | External resource hearing **[Stop]** | Project context |
 | 3 | (orchestrator) | Ask user for prototype code **[Stop]** | Prototype path or none |
-| 4 | ui-spec-designer | UI Spec from requirements + optional prototype | UI Spec |
-| 5 | document-reviewer | UI Spec review **[Stop]** | Approval |
-| 6 | technical-designer | **Backend** Design Doc | Backend Design Doc |
-| 7 | technical-designer-frontend | **Frontend** Design Doc (references backend Integration Points + UI Spec) | Frontend Design Doc |
-| 8 | code-verifier x2 | Verify each Design Doc against code | Verification JSON |
-| 9 | document-reviewer x2 | Review each Design Doc with verification evidence | Reviews |
-| 10 | design-sync | Cross-layer consistency verification (source: frontend Design Doc) **[Stop]** | Sync status |
-| 11 | acceptance-test-generator | Integration/E2E test skeleton from cross-layer contracts | Test skeletons |
-| 12 | work-planner | Work plan from all Design Docs **[Stop: Batch approval]** | Work plan |
+| 4 | codebase-analyzer x2 + ui-analyzer x1 | Per-layer codebase analysis plus frontend UI analysis | Analysis JSON |
+| 5 | ui-spec-designer | UI Spec from requirements + UI analysis + optional prototype | UI Spec |
+| 6 | document-reviewer | UI Spec review **[Stop]** | Approval |
+| 7 | technical-designer | **Backend** Design Doc | Backend Design Doc |
+| 8 | technical-designer-frontend | **Frontend** Design Doc (references backend Integration Points + UI Spec + UI analysis) | Frontend Design Doc |
+| 9 | code-verifier x2 | Verify each Design Doc against code | Verification JSON |
+| 10 | document-reviewer x2 | Review each Design Doc with verification evidence | Reviews |
+| 11 | design-sync | Cross-layer consistency verification (source: frontend Design Doc) **[Stop]** | Sync status |
+| 12 | acceptance-test-generator | Integration/E2E test skeleton from cross-layer contracts | Test skeletons |
+| 13 | work-planner | Work plan from all Design Docs **[Stop: Batch approval]** | Work plan |
 
 ### Parallelization in Multi-Agent Steps
 
-Steps marked `x2` run independently per layer and can execute in parallel when supported.
+Steps marked `x2` run independently per layer and can execute in parallel when supported. `ui-analyzer x1` runs once for the frontend layer alongside frontend codebase analysis and consumes the saved external resource context.
 
 ### Layer Context in Design Doc Creation
 
 When spawning Design Doc creation for each layer, pass explicit context:
 
-**Large Scale (PRD available) -- Backend Design Doc**:
-**Agent**: Spawn technical-designer
-> "Create a backend Design Doc from PRD at [path]. Codebase analysis: [backend analysis JSON]. Focus on: API contracts, data layer, business logic, service architecture."
-
-**Large Scale (PRD available) -- Backend Codebase Analysis**:
-**Agent**: Spawn codebase-analyzer
-> "Analyze the existing codebase to provide evidence for backend Design Doc creation. requirement_analysis: [requirement-analyzer output filtered to backend files]. prd_path: [path]. requirements: [original user requirements]. layer: backend. target_paths: [backend file and directory scope]. focus_areas: API contracts, data layer, business logic, service architecture."
+| Scale | Concrete context value |
+|-------|------------------------|
+| Large | `context: { scale: "large", prd_path: "[path]", requirement_analysis: [requirement-analyzer output] }` |
+| Medium | `context: { scale: "medium", prd_path: null, requirement_analysis: [requirement-analyzer output] }` |
 
-**Large Scale (PRD available) -- Frontend Design Doc**:
-**Agent**: Spawn technical-designer-frontend
-> "Create a frontend Design Doc from PRD at [path]. Codebase analysis: [frontend analysis JSON]. Reference backend Design Doc at [path] for API contracts and Integration Points. Reference UI Spec at [path] for component structure and state design. Focus on: component hierarchy, state management, UI interactions, data fetching."
+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 replace `requirement_analysis` with the layer-filtered requirement analysis.
 
-**Large Scale (PRD available) -- Frontend Codebase Analysis**:
-**Agent**: Spawn codebase-analyzer
-> "Analyze the existing codebase to provide evidence for frontend Design Doc creation. requirement_analysis: [requirement-analyzer output filtered to frontend files]. prd_path: [path]. requirements: [original user requirements]. layer: frontend. target_paths: [frontend file and directory scope]. focus_areas: component hierarchy, state management, UI interactions, data fetching."
-
-**Medium Scale (no PRD) -- Backend Design Doc**:
+**Backend Design Doc**:
 **Agent**: Spawn technical-designer
-> "Create a backend Design Doc based on the following requirements: [requirement-analyzer output]. Codebase analysis: [backend analysis JSON]. Focus on: API contracts, data layer, business logic, service architecture."
+> "Create a backend Design Doc. context: [context]. Codebase analysis: [backend analysis JSON]. Focus on: API contracts, data layer, business logic, service architecture."
 
-**Medium Scale (no PRD) -- Backend Codebase Analysis**:
+**Backend Codebase Analysis**:
 **Agent**: Spawn codebase-analyzer
-> "Analyze the existing codebase to provide evidence for backend Design Doc creation. requirement_analysis: [requirement-analyzer output filtered to backend files]. requirements: [original user requirements]. layer: backend. target_paths: [backend file and directory scope]. focus_areas: API contracts, data layer, business logic, service architecture."
+> "Analyze the existing codebase to provide evidence for backend Design Doc creation. context: [context with requirement_analysis filtered to backend files]. requirements: [original user requirements]. layer: backend. target_paths: [backend file and directory scope]. focus_areas: API contracts, data layer, business logic, service architecture."
 
-**Medium Scale (no PRD) -- Frontend Design Doc**:
+**Frontend Design Doc**:
 **Agent**: Spawn technical-designer-frontend
-> "Create a frontend Design Doc based on the following requirements: [requirement-analyzer output]. Codebase analysis: [frontend analysis JSON]. Reference backend Design Doc at [path] for API contracts and Integration Points. Reference UI Spec at [path] for component structure and state design. Focus on: component hierarchy, state management, UI interactions, data fetching."
+> "Create a frontend Design Doc. context: [context]. Codebase analysis: [frontend analysis JSON]. UI analysis: [ui-analyzer JSON]. Reference backend Design Doc at [path] for API contracts and Integration Points. Reference UI Spec at [path] for component structure and state design. Focus on: component hierarchy, state management, UI interactions, data fetching."
 
-**Medium Scale (no PRD) -- Frontend Codebase Analysis**:
+**Frontend Codebase Analysis**:
 **Agent**: Spawn codebase-analyzer
-> "Analyze the existing codebase to provide evidence for frontend Design Doc creation. requirement_analysis: [requirement-analyzer output filtered to frontend files]. requirements: [original user requirements]. layer: frontend. target_paths: [frontend file and directory scope]. focus_areas: component hierarchy, state management, UI interactions, data fetching."
+> "Analyze the existing codebase to provide evidence for frontend Design Doc creation. context: [context with requirement_analysis filtered to frontend files]. requirements: [original user requirements]. layer: frontend. target_paths: [frontend file and directory scope]. focus_areas: component hierarchy, state management, UI interactions, data fetching."
+
+**Frontend UI Analysis**:
+**Agent**: Spawn ui-analyzer
+> "Gather UI facts for frontend design. context: [context with requirement_analysis filtered to frontend files]. requirements: [original user requirements]. target_paths: [frontend file and directory scope]. target_components: [frontend target components]. prototype_path: [path if provided]. Read docs/project-context/external-resources.md, resolve relevant UI external resources through declared access methods, and analyze component structure, props patterns, CSS layout, state displays, accessibility, generated artifacts, and candidate write set."
 
 ### design-sync for Cross-Layer Verification
 
@@ -100,7 +97,7 @@ Spawn acceptance-test-generator with all Design Docs and UI Spec:
 
 Spawn work-planner with all Design Docs:
 
-> "Create a work plan from the following documents: PRD: [path] (Large Scale only), Design Doc (backend): [path], Design Doc (frontend): [path]. Compose phases as vertical feature slices where possible -- each phase should contain both backend and frontend work for the same feature area, enabling early integration verification per phase."
+> "Create a 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 skeletons from acceptance-test-generator: integration: [path or null], fixtureE2e: [path or null], serviceE2e: [path or null], e2eAbsenceReason: { fixtureE2e: [value or null], serviceE2e: [value or null] }. Compose phases as vertical feature slices where possible -- each phase should contain both backend and frontend work for the same feature area, enabling early integration verification per phase. Include `Implementation Readiness: pending` in the work plan header."
 
 work-planner's existing Integration Complete criteria naturally covers cross-layer verification when given multiple Design Docs.
 

package/.agents/skills/task-analyzer/SKILL.md

@@ -102,10 +102,11 @@ selectedSkills:
     tags: [...]
     typical-use: <string>
     size: <small|medium|large>
-    sections: [...]  # All sections from yaml, unfiltered
+    sections: [...]  # Full section list from yaml
+    references: [...]  # Full reference file list from yaml when present
 ```
 
-**Note**: Section selection (choosing which sections are relevant) is done after reading the actual SKILL.md files.
+**Note**: Section and reference selection (choosing which sections or reference files are relevant) is done after reading the actual SKILL.md files. For output-format templates, read only the reference files matching the document type being created or reviewed.
 
 ## Metacognitive Question Design