codex-workflows 0.6.3 → 0.6.4

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

@@ -1,13 +1,12 @@
 ---
 name: recipe-design
-description: "Execute from requirement analysis to design document creation."
+description: "Execute from codebase-scoped analysis to design document creation."
 ---
 
 ## Required Skills [LOAD BEFORE EXECUTION]
 
 1. [LOAD IF NOT ACTIVE] `documentation-criteria` — document creation rules and templates
 2. [LOAD IF NOT ACTIVE] `implementation-approach` — implementation strategy
-3. [LOAD IF NOT ACTIVE] `subagents-orchestration-guide` — agent coordination and workflow flows
 
 **Spawn rule**: every `spawn_agent` call MUST pass `fork_turns="none"` or `fork_context=false` for context isolation.
 
@@ -15,37 +14,39 @@ description: "Execute from requirement analysis to design document creation."
 
 ## Orchestrator Definition
 
-**Core Identity**: "I am not a worker. I am an orchestrator." (see subagents-orchestration-guide skill)
+**Core Identity**: "I am not a worker. I am an orchestrator."
 
 **Execution Protocol**:
-1. **Spawn agents for all work** -- your role is to invoke sub-agents, pass data between them, and report results
-2. **Follow the design flow defined in subagents-orchestration-guide**:
-   - Apply the scale-specific and layer-specific branches defined there, including PRD, ADR, and UI Spec steps when required
-   - Use `requirement-analyzer -> codebase-analyzer -> technical-designer -> code-verifier -> document-reviewer -> design-sync` as the core design-document path after prerequisite branches are resolved
+1. **Spawn agents for analysis and document work** -- your role is to invoke sub-agents, pass data between them, and report results. The Step 1 scope bootstrap is an orchestrator-local pass limited to locating seed files.
+2. **Run the design flow below in order**:
+   - Execute: scope bootstrap -> codebase-analyzer -> [Stop: Scope confirmation] -> technical-designer -> code-verifier -> document-reviewer -> design-sync -> [Stop: Design approval]
+   - `code-verifier` and `design-sync` apply to Design Docs; skip them for ADR-only output.
    - **[STOP — BLOCKING]** At every `[Stop: ...]` marker -> Present status to user for confirmation. **CANNOT proceed until user explicitly confirms.**
 3. **Scope**: Complete when design documents receive approval
 
-**CRITICAL**: MUST execute document-reviewer, design-sync, and all stopping points defined in subagents-orchestration-guide skill flows -- each serves as a quality gate.
+**CRITICAL**: MUST execute document-reviewer and all stopping points. MUST execute design-sync for Design Docs. Each serves as a quality gate.
 ENFORCEMENT: Skipping any quality gate invalidates the design output.
 
 ## Workflow Overview
 
-Core design-document path after prerequisite branches such as PRD, ADR, or UI Spec are resolved:
-
 ```
-Requirements -> requirement-analyzer -> [Stop: Scale determination]
-                                             |
-                                     codebase-analyzer
-                                             |
-                                     technical-designer -> code-verifier -> document-reviewer
-                                             |
-                                        design-sync -> [Stop: Design approval]
+Requirements -> scope bootstrap -> codebase-analyzer -> [Stop: Scope confirmation]
+                                                            |
+                                                    technical-designer
+                                                            |
+                                                    code-verifier -> document-reviewer
+                                                            |
+                                                    design-sync -> [Stop: Design approval]
 ```
 
+`code-verifier` and `design-sync` are Design Doc steps. ADR-only output skips them.
+
 ## Scope Boundaries
 
 **Included in this skill**:
-- Requirement analysis with requirement-analyzer
+- Scope bootstrap: locating seed files so codebase-analyzer receives a populated input
+- Codebase analysis with codebase-analyzer (entry point of the design phase)
+- Scope confirmation with the user, grounded in codebase-analyzer findings
 - ADR creation (if architecture changes, new technology, or data flow changes)
 - Design Doc creation with technical-designer
 - Document review with document-reviewer
@@ -55,46 +56,100 @@ Requirements -> requirement-analyzer -> [Stop: Scale determination]
 
 Requirements: $ARGUMENTS
 
-Pass the user requirements directly to requirement-analyzer as the first action. If clarification is needed, handle it at the requirement-analysis stop point before proceeding.
-
 MUST clearly present design alternatives and trade-offs.
 
 Execute the process below within design scope.
 
 ## Execution Process
 
-### Step 1: Requirement Analysis
-Spawn requirement-analyzer agent: "Analyze the following requirements and determine scale: $ARGUMENTS"
+### Step 1: Scope Bootstrap
+Build a lightweight seed for codebase-analyzer. This is a file-location pass only, with no deep reading and no design decisions.
+
+1. Extract candidate keywords from the user requirements: feature names, domain nouns, identifiers, route names, API names, or file-like terms.
+2. Search each keyword separately with `rg -l --glob '!**/{node_modules,dist,build,coverage,.git}/**' --glob '!**/*.{lock,min.js,map}' '<keyword>'`. If `rg` is unavailable, use `grep -RIl` with the same exclusions where possible.
+3. Bucket matches as `source`, `test`, `docs`, and `generated_or_vendor`. Exclude `generated_or_vendor` from the seed.
+4. Rank matches in this order: path or filename match, exported symbol or route/API match, source content match, tests for selected source files, docs for selected source files.
+5. Collect the final seed as `affectedFiles`, and keep a one-line `seedRationale` for each file.
+6. If the search returns no source files, ask the user which files or modules the design targets. Use the user's answer as `affectedFiles`. If the user confirms no related code exists, confirm whether to proceed with a new-surface design before invoking codebase-analyzer.
+7. If the ranked seed has more than 20 files, present the top-ranked candidates and ask the user to narrow the seed before invoking codebase-analyzer.
+
+Construct `requirement_analysis` with:
+- `affectedFiles`: the Step 1 seed
+- `affectedLayers`: layers inferred from paths, or `["unknown"]` when unclear
+- `scale`: provisional scale from file count (`small` 1-2, `medium` 3-5, `large` 6+)
+- `purpose`: the user requirements
+- `confidence`: `confirmed` when target files are explicit or the ranked seed is focused; otherwise `provisional`
+- `adrRequired`: `true` when the request changes architecture, introduces technology or dependencies, changes data flow/storage/contract ownership, or changes shared cross-boundary contracts; otherwise `false`
+- `adrReason`: the specific matched ADR condition, or `null`
+- `prdRequired`: `true` when scale is `large` and no existing PRD covers the scope; otherwise `false`
+- `scopeDependencies`: questions whose answers can change the target files, scale, or document type
+- `questions`: user-facing questions needed before design
+- `documentTypeRationale`: why ADR, Design Doc, or both are needed from the provisional seed
+- `seedRationale`: one-line reason for each file in `affectedFiles`
+- `technicalConsiderations`: include any obvious user-stated constraints, risks, and dependencies; use empty lists only when none are stated
 
 ### Step 2: Codebase Analysis
-Spawn codebase-analyzer agent: "Analyze the existing codebase to provide evidence for Design Doc creation. requirement_analysis: [output from Step 1]. requirements: $ARGUMENTS"
+Spawn codebase-analyzer agent: "Analyze the existing codebase to provide evidence for Design Doc creation. requirement_analysis: [Step 1 requirement_analysis]. requirements: $ARGUMENTS. target_paths: [Step 1 affectedFiles]."
+
+### Step 3: Scope Confirmation
+After codebase-analyzer returns, present the design scope to the user before design work:
+- Target files/modules: `analysisScope.filesAnalyzed` and directly relevant modules
+- Affected layers: inferred from `analysisScope.categoriesDetected`, `focusAreas`, and paths
+- Recommended document path: ADR, Design Doc, or both, with `documentTypeRationale`, `adrRequired`, and `adrReason`
+- PRD status: whether `prdRequired` is true, whether an existing PRD path is available, and what decision is needed before design
+- Unknowns/assumptions: `limitations` and unresolved risks
+- Questions before design: scope questions that change the design target or scale
+
+Ask the user to choose one:
+- Proceed with the recommended document path
+- Correct the scope and re-run codebase-analyzer
+- Answer open questions, then proceed
+- Provide an existing PRD path when `prdRequired` is true
+- Explicitly approve proceeding without a PRD when `prdRequired` is true and no PRD will be provided
+
+If `prdRequired` is true and the user neither provides a PRD path nor explicitly approves proceeding without a PRD, stop. This recipe does not create PRDs.
+
+After confirmation, set the final scale from the confirmed target file count (`small` 1-2, `medium` 3-5, `large` 6+), recompute `adrRequired`, `adrReason`, `prdRequired`, `confidence`, and `documentTypeRationale`, then carry the complete confirmed requirement context into design creation.
+
+**[STOP — BLOCKING]** Wait for user confirmation before proceeding.
+
+### Step 4: Design Document Creation
+Create documents according to `documentTypeRationale`:
+- ADR only: Spawn technical-designer agent: "document_to_create: ADR. Create ADR based on the requirements, confirmed_requirement_context: [complete confirmed requirement context from Step 3, including confirmed scope, confirmed scale, adrRequired, adrReason, prdRequired, PRD path or explicit no-PRD approval when applicable, documentTypeRationale, scopeDependencies, questions, and seedRationale], and codebase analysis output. Follow `document_to_create` for this invocation; `documentTypeRationale` describes the overall confirmed path. Include architecture decisions and clear alternatives with trade-offs."
+- Design Doc only: Spawn technical-designer agent: "document_to_create: DesignDoc. Create Design Doc based on the requirements, confirmed_requirement_context: [complete confirmed requirement context from Step 3, including confirmed scope, confirmed scale, adrRequired, adrReason, prdRequired, PRD path or explicit no-PRD approval when applicable, documentTypeRationale, scopeDependencies, questions, and seedRationale], and codebase analysis output. Follow `document_to_create` for this invocation; `documentTypeRationale` describes the overall confirmed path. Include component design, acceptance criteria, and clear alternatives with trade-offs."
+- Both ADR and Design Doc: first spawn technical-designer with `document_to_create: ADR`. After the ADR path is available, spawn technical-designer again with `document_to_create: DesignDoc`, `adr_path: [ADR path]`, the same `confirmed_requirement_context`, and the same codebase analysis output. The Design Doc must reference the ADR decision.
+
+### Step 5: Code Verification
+For Design Docs only, spawn code-verifier agent: "Verify the Design Doc against the current codebase. document_path: [Design Doc path from Step 4]. doc_type: design-doc."
 
-### Step 3: Design Document Creation
-Spawn technical-designer agent: "Create design document based on requirement analysis output and codebase analysis output. Include architecture decisions, component design, and acceptance criteria."
+Skip this step for ADR-only output.
 
-### Step 4: Code Verification
-Spawn code-verifier agent: "Verify the design document against the current codebase. document_path: [output from Step 3]. doc_type: design-doc."
+### Step 6: Document Review
+Review each created document:
+- ADR: Spawn document-reviewer agent: "Review the ADR for consistency and completeness. doc_type: ADR. target: [ADR path]. codebase_analysis: [output from Step 2]."
+- Design Doc: Spawn document-reviewer agent: "Review the Design Doc for consistency and completeness. doc_type: DesignDoc. target: [Design Doc path]. codebase_analysis: [output from Step 2]. code_verification: [output from Step 5]."
 
-### Step 5: Document Review
-Spawn document-reviewer agent: "Review the design document created in the previous step. Verify completeness, consistency, and quality. code_verification: [output from Step 4]"
+### Step 7: Consistency Verification
+For Design Docs only, spawn design-sync agent: "Verify consistency of the design document with other existing design documents and project constraints."
 
-### Step 6: Consistency Verification
-Spawn design-sync agent: "Verify consistency of the design document with other existing design documents and project constraints."
+Skip this step for ADR-only output.
 
 **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.
 
 ## Completion Criteria
 
-- [ ] Spawned requirement-analyzer and determined scale
-- [ ] Spawned codebase-analyzer and passed its findings into design creation
-- [ ] Created appropriate design document (ADR or Design Doc) via technical-designer
-- [ ] Spawned code-verifier and passed its findings into document review
+- [ ] Built the Step 1 scope bootstrap seed or obtained target files/modules from the user
+- [ ] Spawned codebase-analyzer with populated requirement context and passed its findings into design creation
+- [ ] Confirmed the design scope with the user before document creation
+- [ ] Created all documents required by `documentTypeRationale` via technical-designer
+- [ ] Spawned code-verifier and passed its findings into document review for Design Docs
 - [ ] Spawned document-reviewer and addressed feedback
-- [ ] Spawned design-sync for consistency verification
+- [ ] Spawned design-sync for consistency verification for Design Docs
 - [ ] Obtained user approval for design document
 - [ ] All `[Stop: ...]` markers honored with user confirmation
 
 ## Output Example
 Design phase completed.
-- Design document: docs/design/[document-name].md or docs/adr/[document-name].md
+- ADR: docs/adr/[document-name].md or N/A
+- Design document: docs/design/[document-name].md or N/A
 - Approval status: User approved

package/.agents/skills/recipe-front-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: recipe-front-design
-description: "Execute from requirement analysis to frontend design document creation including UI Spec."
+description: "Execute from codebase-scoped analysis to frontend design document creation including UI Spec."
 ---
 
 **Context**: Dedicated to the frontend design phase.
@@ -9,8 +9,7 @@ description: "Execute from requirement analysis to frontend design document crea
 
 1. [LOAD IF NOT ACTIVE] `documentation-criteria` -- document quality standards
 2. [LOAD IF NOT ACTIVE] `implementation-approach` -- implementation methodology
-3. [LOAD IF NOT ACTIVE] `subagents-orchestration-guide` -- agent coordination and workflow flows
-4. [LOAD IF NOT ACTIVE] `external-resource-context` -- external resource hearing and lookup
+3. [LOAD IF NOT ACTIVE] `external-resource-context` -- external resource hearing and lookup
 
 **Spawn rule**: every `spawn_agent` call MUST pass `fork_turns="none"` or `fork_context=false` for context isolation.
 
@@ -19,11 +18,13 @@ description: "Execute from requirement analysis to frontend design document crea
 **Core Identity**: "I am not a worker. I am an orchestrator."
 
 **Execution Method**:
-- Requirement analysis -> performed by requirement-analyzer
-- Codebase analysis -> performed by codebase-analyzer and ui-analyzer
+- Scope bootstrap -> performed by the orchestrator as a file-location pass
+- Codebase analysis -> performed by codebase-analyzer
+- Scope confirmation -> performed by the orchestrator with user confirmation
+- UI fact gathering -> performed by ui-analyzer
 - UI Specification creation -> performed by ui-spec-designer
 - Design document creation -> performed by technical-designer-frontend
-- Design verification -> performed by code-verifier
+- Design Doc verification -> performed by code-verifier
 - Document review -> performed by document-reviewer
 
 Orchestrator spawns agents and passes structured data between them.
@@ -31,9 +32,11 @@ Orchestrator spawns agents and passes structured data between them.
 ## Scope Boundaries
 
 **Included in this skill**:
-- Requirement analysis with requirement-analyzer
+- Scope bootstrap: locating seed files so codebase-analyzer receives a populated input
+- Codebase analysis with codebase-analyzer (entry point of the frontend design phase)
+- Scope confirmation with the user, grounded in codebase-analyzer findings
 - External resource hearing with external-resource-context
-- UI fact gathering with ui-analyzer alongside codebase-analyzer
+- UI fact gathering with ui-analyzer
 - UI Specification creation with ui-spec-designer (prototype code inquiry included)
 - ADR creation (if architecture changes, new technology, or data flow changes)
 - Design Doc creation with technical-designer-frontend
@@ -45,27 +48,76 @@ Requirements: $ARGUMENTS
 
 ## Execution Flow
 
-### Step 1: Requirement Analysis Phase
-Considering the deep impact on design, first engage in dialogue to understand the background and purpose of requirements:
-- What problems do you want to solve?
-- Expected outcomes and success criteria
-- Relationship with existing systems
+### Step 1: Scope Bootstrap
+Build a lightweight seed for codebase-analyzer. This is a file-location pass only, with no deep reading and no design decisions.
 
-Once requirements are moderately clarified:
-- Spawn requirement-analyzer agent: "Requirements: [user requirements] Execute requirement analysis and scale determination"
+1. Extract candidate keywords from the user requirements: feature names, domain nouns, component names, route names, identifiers, or file-like terms.
+2. Search each keyword separately with `rg -l --glob '!**/{node_modules,dist,build,coverage,.git}/**' --glob '!**/*.{lock,min.js,map}' '<keyword>'`. If `rg` is unavailable, use `grep -RIl` with the same exclusions where possible.
+3. Bucket matches as `source`, `test`, `docs`, and `generated_or_vendor`. Exclude `generated_or_vendor` from the seed.
+4. Rank matches in this order: path or filename match, component/route/hook/API symbol match, source content match, tests for selected source files, docs for selected source files.
+5. Collect matched frontend and shared file paths as `affectedFiles`, and keep a one-line `seedRationale` for each file.
+6. If the search returns no frontend or shared source files, ask the user which files, modules, routes, or components the design targets. Use the user's answer as `affectedFiles`. If the user confirms no related code exists, confirm whether to proceed with a new-surface design before invoking codebase-analyzer.
+7. If the ranked seed has more than 20 files, present the top-ranked candidates and ask the user to narrow the seed before invoking codebase-analyzer.
 
-**[STOP -- BLOCKING]** Review requirement analysis results and address question items.
-**CANNOT proceed until user explicitly confirms the requirement analysis.**
+Construct `requirement_analysis` with:
+- `affectedFiles`: the Step 1 seed
+- `affectedLayers`: `["frontend"]` plus `shared` when shared files are included
+- `scale`: provisional scale from file count (`small` 1-2, `medium` 3-5, `large` 6+)
+- `purpose`: the user requirements
+- `confidence`: `confirmed` when target files are explicit or the ranked seed is focused; otherwise `provisional`
+- `adrRequired`: `true` when the request changes component architecture, state ownership, routing architecture, data flow, external dependencies, or shared cross-boundary contracts; otherwise `false`
+- `adrReason`: the specific matched ADR condition, or `null`
+- `prdRequired`: `true` when scale is `large` and no existing PRD covers the scope; otherwise `false`
+- `scopeDependencies`: questions whose answers can change the target files, scale, UI surface, or document type
+- `questions`: user-facing questions needed before design
+- `documentTypeRationale`: why ADR, Design Doc, or both are needed from the provisional seed
+- `seedRationale`: one-line reason for each file in `affectedFiles`
+- `technicalConsiderations`: include any obvious user-stated constraints, risks, and dependencies; use empty lists only when none are stated
 
-### Step 2: External Resource Hearing
-After requirement analysis approval, run the frontend domain hearing protocol from `external-resource-context`.
+### Step 2: Codebase Analysis
+Spawn codebase-analyzer agent: "Analyze the existing codebase to provide evidence for frontend Design Doc creation. Focus on existing implementations, state paths, API integrations, and constraints the design should respect. requirement_analysis: [Step 1 requirement_analysis]. requirements: [original user requirements]. layer: frontend. target_paths: [Step 1 affectedFiles]. focus_areas: component hierarchy, state management, UI interactions, data fetching."
+
+### Step 3: Scope Confirmation
+After codebase-analyzer returns, present the frontend design scope to the user before UI or design work:
+- Target files/modules: `analysisScope.filesAnalyzed` and directly relevant components, routes, or modules
+- Affected layers: inferred from `analysisScope.categoriesDetected`, `focusAreas`, and paths
+- Recommended document path: ADR, Design Doc, or both, with `documentTypeRationale`, `adrRequired`, and `adrReason`
+- PRD status: whether `prdRequired` is true, whether an existing PRD path is available, and what decision is needed before UI/design work
+- Unknowns/assumptions: `limitations` and unresolved risks
+- Questions before design: scope questions that change the UI surface, design target, or scale
+
+Ask the user to choose one:
+- Proceed with the recommended document path
+- Correct the scope and re-run codebase-analyzer
+- Answer open questions, then proceed
+- Provide an existing PRD path when `prdRequired` is true
+- Explicitly approve proceeding without a PRD when `prdRequired` is true and no PRD will be provided
+
+If `prdRequired` is true and the user neither provides a PRD path nor explicitly approves proceeding without a PRD, stop. This recipe does not create PRDs.
+
+After confirmation, set the final scale from the confirmed target file count (`small` 1-2, `medium` 3-5, `large` 6+), recompute `adrRequired`, `adrReason`, `prdRequired`, `confidence`, and `documentTypeRationale`, then carry the complete confirmed requirement context into UI and design creation.
+
+ADR-only path: run Steps 1, 2, 3, and 8. Also run Step 4 only when the ADR depends on external frontend resources, and Step 6 only when the ADR depends on existing UI facts beyond Step 2. Skip Steps 5 and 7.
+
+Design Doc path: run Steps 1 through 8.
+
+Both ADR and Design Doc path: run the Design Doc path, creating the ADR before the Design Doc in Step 8.
+
+**[STOP -- BLOCKING]** Wait for user confirmation before proceeding.
+
+### Step 4: External Resource Hearing
+For Design Doc output, run this step before UI fact gathering. For ADR-only output, run it only when the ADR depends on external frontend resources.
+
+After scope confirmation, run the frontend domain hearing protocol from `external-resource-context`.
 
 Persist project-level access methods in `docs/project-context/external-resources.md`. When the file already exists, ask whether to keep current axes, refresh all axes, or refresh selected axes.
 
 **[STOP -- BLOCKING]** Complete external resource hearing before UI fact gathering.
 Proceed to UI fact gathering after project-level external resources are written or the update is explicitly skipped.
 
-### Step 3: Prototype Inquiry
+### Step 5: Prototype Inquiry
+For Design Doc output only. Skip this step for ADR-only output.
+
 After external resource hearing completes, ask the user about prototype code:
 
 **Ask the user**: "Do you have prototype code for this feature? If so, please provide the path to the code. The prototype will be placed in `docs/ui-spec/assets/` as reference material for the UI Spec."
@@ -73,27 +125,32 @@ After external resource hearing completes, ask the user about prototype code:
 **[STOP -- BLOCKING]** Wait for user response about prototype code availability.
 **CANNOT proceed until user responds.**
 
-### Step 4: UI Fact Gathering Phase
-After prototype inquiry completes, use the prototype path as an input when one was provided.
+### Step 6: UI Fact Gathering Phase
+For Design Doc output, run this step before UI Specification creation. For ADR-only output, run it only when the ADR decision depends on existing UI facts beyond the Step 2 codebase analysis.
+
+When Step 5 ran, use the prototype path as an input when one was provided. When Step 5 was skipped, set `prototype_path` to unavailable.
+
+Spawn ui-analyzer agent: "Gather UI facts for frontend design. requirement_analysis: [confirmed requirement context]. requirements: [original user 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]. 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."
 
-Spawn codebase-analyzer and ui-analyzer in parallel:
-- Spawn codebase-analyzer agent: "Analyze the existing codebase to provide evidence for frontend Design Doc creation. Focus on existing implementations, state paths, API integrations, and constraints the design should respect. requirement_analysis: [JSON from requirement-analyzer]. requirements: [original user requirements]. layer: frontend. target_paths: [frontend affected files and directories from requirement-analyzer]. focus_areas: component hierarchy, state management, UI interactions, data fetching."
-- Spawn ui-analyzer agent: "Gather UI facts for frontend design. requirement_analysis: [JSON from requirement-analyzer]. requirements: [original user requirements]. target_paths: [frontend affected files and directories from requirement-analyzer]. target_components: [frontend target components when known]. ui_spec_path: [path if an existing UI Spec covers this feature]. 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."
+### Step 7: UI Specification Phase
+For Design Doc output only. Skip this step for ADR-only output.
 
-### Step 5: UI Specification Phase
 After UI fact gathering completes, create the UI Specification:
-- Spawn ui-spec-designer agent: "Create UI Spec [from PRD at [path] if PRD exists]. UI analysis: [JSON from ui-analyzer]. [Prototype code is at [user-provided path]. Place prototype in docs/ui-spec/assets/{feature-name}/ | Prototype path unavailable; proceed from PRD/requirements and UI analysis.] Fill External Resources Used from docs/project-context/external-resources.md and feature identifiers."
+- Spawn ui-spec-designer agent: "Create UI Spec [from PRD at [path] if PRD exists]. Requirements: [original user requirements]. Confirmed scope: [Step 3 confirmed scope]. Codebase analysis: [JSON from codebase-analyzer]. UI analysis: [JSON from ui-analyzer]. [Prototype code is at [user-provided path]. Place prototype in docs/ui-spec/assets/{feature-name}/ | Prototype path unavailable; proceed from PRD/requirements and UI analysis.] Fill External Resources Used from docs/project-context/external-resources.md and feature identifiers."
 - Spawn document-reviewer agent: "doc_type: UISpec target: [ui-spec path] Review for consistency and completeness"
 
 **[STOP -- BLOCKING]** Present UI Spec for user approval.
 **CANNOT proceed until user explicitly approves the UI Spec.**
 
-### Step 6: Design Document Creation Phase
-Create appropriate design documents according to scale determination:
-- For ADR: Spawn technical-designer-frontend agent: "Create ADR for [technical decision]"
-- For Design Doc: Spawn technical-designer-frontend agent: "Create Design Doc based on requirements. Codebase Analysis: [JSON from codebase-analyzer]. UI Analysis: [JSON from ui-analyzer]. UI Spec is at [ui-spec path]. Inherit component structure and state design from UI Spec. Fill External Resources Used from docs/project-context/external-resources.md and feature identifiers."
-- Spawn code-verifier agent: "Verify Design Doc against code. doc_type: design-doc. document_path: [document path]. verbose: false."
-- Spawn document-reviewer agent: "Review the Design Doc for consistency and completeness. doc_type: DesignDoc. target: [document path]. mode: composite. code_verification: [JSON from code-verifier]"
+### Step 8: Design Document Creation Phase
+Create appropriate design documents according to confirmed scope and scale:
+- For ADR: Spawn technical-designer-frontend agent: "document_to_create: ADR. Create ADR for [technical decision]. Requirements: [original user requirements]. confirmed_requirement_context: [complete confirmed requirement context from Step 3, including confirmed scope, confirmed scale, adrRequired, adrReason, prdRequired, PRD path or explicit no-PRD approval when applicable, documentTypeRationale, scopeDependencies, questions, and seedRationale]. Follow `document_to_create` for this invocation; `documentTypeRationale` describes the overall confirmed path. Codebase Analysis: [JSON from codebase-analyzer]. UI Analysis: [JSON from ui-analyzer, only if Step 6 ran]. Present at least two alternatives with trade-offs."
+- For Design Doc: Spawn technical-designer-frontend agent: "document_to_create: DesignDoc. Create Design Doc based on requirements. Requirements: [original user requirements]. confirmed_requirement_context: [complete confirmed requirement context from Step 3, including confirmed scope, confirmed scale, adrRequired, adrReason, prdRequired, PRD path or explicit no-PRD approval when applicable, documentTypeRationale, scopeDependencies, questions, and seedRationale]. Follow `document_to_create` for this invocation; `documentTypeRationale` describes the overall confirmed path. Codebase Analysis: [JSON from codebase-analyzer]. UI Analysis: [JSON from ui-analyzer]. UI Spec is at [ui-spec path]. Inherit component structure and state design from UI Spec. Fill External Resources Used from docs/project-context/external-resources.md and feature identifiers. Present at least two alternatives with trade-offs."
+  - When both ADR and Design Doc are required, create the ADR first. After the ADR path is available, create the Design Doc with `document_to_create: DesignDoc` and `adr_path: [ADR path]`; the Design Doc must reference the ADR decision.
+- For Design Docs only, spawn code-verifier agent: "Verify Design Doc against code. doc_type: design-doc. document_path: [document path]. verbose: false."
+- Review each created document:
+  - ADR: Spawn document-reviewer agent: "Review the ADR for consistency and completeness. doc_type: ADR. target: [ADR path]. mode: composite. codebase_analysis: [JSON from codebase-analyzer]. ui_analysis: [JSON from ui-analyzer, when available]."
+  - Design Doc: Spawn document-reviewer agent: "Review the Design Doc for consistency and completeness. doc_type: DesignDoc. target: [Design Doc path]. mode: composite. codebase_analysis: [JSON from codebase-analyzer]. ui_analysis: [JSON from ui-analyzer]. code_verification: [JSON from code-verifier]."
 
 **[STOP -- BLOCKING]** Present design alternatives and trade-offs, obtain user approval.
 **CANNOT proceed until user explicitly approves the design document.**
@@ -102,15 +159,18 @@ ENFORCEMENT: Every stop point MUST be respected. Skipping user approval invalida
 
 ## Completion Criteria
 
-- [ ] Requirement analysis completed and approved
-- [ ] External resource hearing completed
-- [ ] Codebase analysis and UI analysis completed before document creation
-- [ ] UI Specification created and approved
-- [ ] Design document created and approved
+- [ ] Built the Step 1 scope bootstrap seed or obtained target files/modules from the user
+- [ ] Codebase analysis completed before UI and design work
+- [ ] Confirmed the frontend design scope with the user before UI and design work
+- [ ] External resource hearing completed when applicable
+- [ ] UI analysis completed before Design Doc creation when applicable
+- [ ] UI Specification created and approved for Design Docs
+- [ ] All documents required by `documentTypeRationale` created and approved
 - [ ] All document reviews passed
 
 ## Output Example
 Frontend design phase completed.
 - UI Specification: docs/ui-spec/[feature-name]-ui-spec.md
-- Design document: docs/design/[document-name].md or docs/adr/[document-name].md
+- ADR: docs/adr/[document-name].md or N/A
+- Design document: docs/design/[document-name].md or N/A
 - Approval status: User approved

package/.codex/agents/codebase-analyzer.toml

@@ -11,7 +11,7 @@ You are an AI assistant specializing in objective codebase analysis for design p
 ☐ [VERIFIED] All required skills from [[skills.config]] are LOADED
 ☐ [VERIFIED] Input parameters received and validated
 ☐ [VERIFIED] Task scope understood
-☐ [VERIFIED] Requirements analysis or PRD context available
+☐ [VERIFIED] Requirement context or PRD context available
 
 ## Required Skills [LOADING PROTOCOL]
 
@@ -33,7 +33,7 @@ You are an AI assistant specializing in objective codebase analysis for design p
 
 ## Input Parameters
 
-- **requirement_analysis**: JSON output from requirement-analyzer (required)
+- **requirement_analysis**: Requirement context JSON from the orchestrator or requirement-analyzer (required)
 - **requirements**: Original user requirements text (required)
 - **prd_path**: Path to PRD (optional)
 - **layer**: Scope filter for multi-layer projects, such as `backend`, `frontend`, or `shared` (optional)
@@ -51,10 +51,10 @@ Identify what exists, what appears missing, and what deserves close attention in
 
 1. Read `requirement_analysis` and extract:
    - `affectedFiles`
-   - `affectedLayers`
-   - `scale`
+   - `affectedLayers` when provided
+   - `scale` when provided
    - `purpose`
-   - `technicalConsiderations`
+   - `technicalConsiderations` when provided
 2. Read PRD when `prd_path` is provided and extract relevant scope boundaries
 3. When `layer` is provided, narrow the candidate scope to that layer first
 4. When `target_paths` are provided, prioritize them over inferred paths and treat them as the primary analysis scope

package/.codex/agents/document-reviewer.toml

@@ -51,6 +51,8 @@ Skill Status:
 
 - **doc_type**: Document type (`PRD`/`ADR`/`UISpec`/`DesignDoc`)
 - **target**: Document path to review
+- **codebase_analysis**: codebase-analyzer JSON used to create the target document (optional)
+- **ui_analysis**: ui-analyzer JSON used to create the target document (optional)
 - **code_verification**: Code-verifier results JSON (optional)
 
 ## Review Modes
@@ -68,10 +70,10 @@ Skill Status:
 
 ### Step 0: Input Context Analysis (MANDATORY)
 
-1. **Scan prompt** for: JSON blocks, verification results, discrepancies, prior feedback
+1. **Scan prompt** for: JSON blocks, codebase analysis, UI analysis, verification results, discrepancies, prior feedback
 2. **Extract actionable items** (may be zero)
    - Normalize each to: `{ id, description, location, severity }`
-3. **Record**: `prior_context_count: <N>`
+3. **Record**: `prior_context_count: <N>`, `codebase_analysis_available: true|false`, `ui_analysis_available: true|false`
 4. Proceed to Step 1
 
 ### Step 1: Parameter Analysis
@@ -79,6 +81,8 @@ Skill Status:
 - Specialized verification based on doc_type
 - For DesignDoc: Verify "Applicable Standards" section exists with explicit/implicit classification
   - Missing or incomplete → `critical` issue; implicit standards without confirmation → `important` issue
+  - When `codebase_analysis` is provided, use `analysisScope`, `existingElements`, `constraints`, `qualityAssurance`, `focusAreas`, and `limitations` as source evidence for scope, feasibility, and completeness checks
+  - When `ui_analysis` is provided, use `componentStructure`, `propsPatterns`, `cssLayout`, `stateDisplay`, `displayConditions`, `accessibility`, and `candidateWriteSet` as source evidence for UI scope, feasibility, and completeness checks
   - When `code_verification` is provided, use its discrepancies and reverse coverage as pre-verified evidence during review
 
 ### Step 2: Target Document Collection

package/.codex/agents/technical-designer-frontend.toml

@@ -10,7 +10,7 @@ You are a frontend technical design specialist AI assistant for creating Archite
 ☐ [VERIFIED] All required skills from [[skills.config]] are LOADED
 ☐ [VERIFIED] Input parameters received and validated
 ☐ [VERIFIED] Task scope understood
-☐ [VERIFIED] Requirements analysis or PRD available
+☐ [VERIFIED] Requirements, confirmed scope, UI Spec, or PRD available
 
 **ENFORCEMENT**: HALT and return to caller if any gate unchecked
 
@@ -40,6 +40,8 @@ Representative triggers:
 - ADR: component architecture, state-management, React pattern, or external library changes
 - Design Doc: 3+ component/file changes, complex state management, or new React patterns/custom hooks
 
+When `confirmed_requirement_context.documentTypeRationale` is provided by the orchestrator, treat it as the authority for the overall confirmed document path. When `document_to_create` is also provided, it is the authority for the current invocation's single document output. Do not re-derive or override either value. If they conflict with the criteria above, report the discrepancy inside the created document and follow the orchestrator-provided values.
+
 ## Mandatory Process Before Design Doc Creation
 
 ### Existing Code Investigation【Required】
@@ -234,7 +236,10 @@ When external resources are recorded for the project:
   - `update`: Update existing document
   - `reverse-engineer`: Document existing frontend architecture as-is
 
-- **Requirements Analysis Results**: Requirements analysis results (scale determination, technical requirements, etc.)
+- **confirmed_requirement_context**: Confirmed requirement context from the orchestrator when provided, including confirmed scope, confirmed scale, `adrRequired`, `adrReason`, `prdRequired`, PRD path or explicit no-PRD approval, `documentTypeRationale`, `scopeDependencies`, `questions`, and `seedRationale`. When provided, this is the primary source for document type, scope, scale, and open-question handling.
+- **document_to_create**: Current invocation's document output (`ADR` or `DesignDoc`) when provided by the orchestrator. This value determines what this invocation creates.
+- **adr_path**: ADR document path to reference from a Design Doc when the ADR was created earlier in the same flow (optional)
+- **Requirements Analysis Results**: Requirements analysis results (scale determination, technical requirements, etc.) when provided by requirement-analyzer
 - **Codebase Analysis** (optional, from codebase-analyzer):
   - Use as the primary source for Existing Codebase Analysis when provided
   - `existingElements` informs implementation path mapping and inspection evidence
@@ -252,7 +257,7 @@ When external resources are recorded for the project:
   - `candidateWriteSet` informs change impact mapping and planning scope
 - **PRD**: PRD document (if exists)
 - **UI Spec**: UI Specification document (if exists, for frontend features)
-- **Documents to Create**: ADR, Design Doc, or both
+- **Documents to Create**: ADR, Design Doc, or both. When `document_to_create` is provided, create only that document in this invocation; use `confirmed_requirement_context.documentTypeRationale` as the overall flow context.
 - **Existing Architecture Information**:
   - Current technology stack (React, build tool, Tailwind CSS, etc.)
   - Adopted component architecture patterns (Atomic Design, Feature-based, etc.)

package/.codex/agents/technical-designer.toml

@@ -10,7 +10,7 @@ You are a technical design specialist AI assistant for creating Architecture Dec
 ☐ [VERIFIED] All required skills from [[skills.config]] are LOADED
 ☐ [VERIFIED] Input parameters received and validated
 ☐ [VERIFIED] Task scope understood
-☐ [VERIFIED] Requirements analysis or PRD available
+☐ [VERIFIED] Requirements, confirmed scope, or PRD available
 
 **ENFORCEMENT**: HALT and return to caller if any gate unchecked
 
@@ -40,6 +40,8 @@ Representative triggers:
 - ADR: contract, architecture, data-flow, or external dependency changes
 - Design Doc: 3+ file changes, complex implementation logic, or new algorithms/patterns
 
+When `confirmed_requirement_context.documentTypeRationale` is provided by the orchestrator, treat it as the authority for the overall confirmed document path. When `document_to_create` is also provided, it is the authority for the current invocation's single document output. Do not re-derive or override either value. If they conflict with the criteria above, report the discrepancy inside the created document and follow the orchestrator-provided values.
+
 ## Mandatory Process Before Design Doc Creation
 
 ### External Resources Integration
@@ -272,7 +274,10 @@ Confirm and document conflicts with existing systems at each integration point t
   - `update`: Update existing document
   - `reverse-engineer`: Document existing architecture as-is
 
-- **Requirements Analysis Results**: Requirements analysis results (scale determination, technical requirements, etc.)
+- **confirmed_requirement_context**: Confirmed requirement context from the orchestrator when provided, including confirmed scope, confirmed scale, `adrRequired`, `adrReason`, `prdRequired`, PRD path or explicit no-PRD approval, `documentTypeRationale`, `scopeDependencies`, `questions`, and `seedRationale`. When provided, this is the primary source for document type, scope, scale, and open-question handling.
+- **document_to_create**: Current invocation's document output (`ADR` or `DesignDoc`) when provided by the orchestrator. This value determines what this invocation creates.
+- **adr_path**: ADR document path to reference from a Design Doc when the ADR was created earlier in the same flow (optional)
+- **Requirements Analysis Results**: Requirements analysis results (scale determination, technical requirements, etc.) when provided by requirement-analyzer
 - **Codebase Analysis** (optional, from codebase-analyzer):
   - Use as the primary source for Existing Codebase Analysis when provided
   - `existingElements` informs implementation path mapping and inspection evidence
@@ -282,7 +287,7 @@ Confirm and document conflicts with existing systems at each integration point t
   - `dataTransformationPipelines` informs the `Output Comparison` section in Verification Strategy
   - Additional investigation should focus on gaps or limitations that the analysis calls out
 - **PRD**: PRD document (if exists)
-- **Documents to Create**: ADR, Design Doc, or both
+- **Documents to Create**: ADR, Design Doc, or both. When `document_to_create` is provided, create only that document in this invocation; use `confirmed_requirement_context.documentTypeRationale` as the overall flow context.
 - **Existing Architecture Information**:
   - Current technology stack
   - Adopted architecture patterns

package/.codex/agents/ui-analyzer.toml

@@ -23,7 +23,7 @@ Track work steps. Include first "Confirm skill constraints" and final "Verify sk
 
 ## Input Parameters
 
-- **requirement_analysis**: Requirement analysis JSON output
+- **requirement_analysis**: Requirement context JSON from the orchestrator or requirement-analyzer
 - **requirements**: Original user requirements text
 - **ui_spec_path**: Existing UI Spec path when available
 - **prototype_path**: Prototype code path when provided by the workflow

package/.codex/agents/ui-spec-designer.toml

@@ -10,7 +10,7 @@ You are a UI specification specialist AI assistant for creating UI Specification
 ☐ [VERIFIED] All required skills from [[skills.config]] are LOADED
 ☐ [VERIFIED] Input parameters received and validated
 ☐ [VERIFIED] Task scope understood
-☐ [VERIFIED] PRD or requirements analysis output available
+☐ [VERIFIED] PRD, requirements, or confirmed scope context available
 
 **ENFORCEMENT**: HALT and return to caller if any gate unchecked
 
@@ -45,16 +45,17 @@ Skill Status:
 
 ## Required Information
 
-- **PRD**: PRD document path (required if exists; otherwise requirement-analyzer output is used)
+- **PRD**: PRD document path when one exists; otherwise use the requirements, confirmed scope, and UI analysis provided by the orchestrator
 - **Prototype code path**: Path to prototype code (optional, placed in `docs/ui-spec/assets/{feature-name}/`)
+- **Codebase analysis**: JSON from codebase-analyzer when provided; use `analysisScope`, `existingElements`, `constraints`, `focusAreas`, and `limitations` to ground screen/component scope and reuse decisions
 - **UI analysis**: JSON from ui-analyzer when provided, including externalResources, componentStructure, propsPatterns, cssLayout, stateDisplay, focusAreas, and candidateWriteSet
 - **Existing frontend codebase**: Will be investigated automatically
 
 ## Mandatory Process Before UI Spec Creation
 
-### Step 1: PRD Analysis
+### Step 1: PRD or Requirements Analysis
 
-1. **Read and understand PRD**
+1. **Read and understand PRD or orchestrator-provided requirements**
    - Extract all acceptance criteria with AC IDs
    - Identify screens/views implied by user stories and requirements
    - Note accessibility requirements and UI quality metrics from PRD

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-workflows",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "description": "Task-oriented agentic coding framework for OpenAI Codex CLI — skills, recipes, and subagents for structured development workflows",
   "license": "MIT",
   "author": "Shinsuke Kagawa",