codex-workflows 0.6.3 → 0.6.5

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/.agents/skills/subagents-orchestration-guide/SKILL.md

@@ -185,7 +185,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` (`design_compliance_violation`, `similar_function_found`, `similar_component_found`, `investigation_target_not_found`, `out_of_scope_file`, `dependency_version_uncertain`, `binding_decision_violation`), `filesModified`, `requiresTestReview` |
+| `task-executor*` | `status`, `escalation_type` (`design_compliance_violation`, `similar_function_found`, `similar_component_found`, `investigation_target_not_found`, `out_of_scope_file`, `dependency_version_uncertain`, `binding_decision_violation`, `test_environment_not_ready`), `filesModified`, `requiresTestReview` |
 | `quality-fixer*` | `status`, `reason`, `stubFindings`, `blockingIssues`, `missingPrerequisites` |
 | `document-reviewer` | `verdict.decision`, `verdict.conditions` |
 | `code-verifier` | `summary.status`, `discrepancies`, `reverseCoverage` |

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

@@ -120,6 +120,10 @@ Read error paths and boundary handling directly in the code:
 
 #### 3-3. Test Coverage for Acceptance Criteria
 - For each fulfilled AC, check whether tests exercise the expected behavior
+- For each test claimed as AC coverage, inspect the body:
+  - Meaningful coverage: at least one assertion exercises the AC's observable behavior
+  - Coverage gap: `skip`/`xit` on tests that should run, TODO/placeholder-only bodies, always-true assertions (for example `expect(true).toBe(true)` or `expect(arr.length).toBeGreaterThanOrEqual(0)`), 0-match runner reports, or grep-only matches without behavior verification
+  - Intentional absence: meaningful when absence is the AC expectation
 
 Classify each quality finding into one of:
 - `dd_violation`: implementation deviates from the Design Doc

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/integration-test-reviewer.toml

@@ -76,6 +76,10 @@ Evaluate each test for:
 - Clear Arrange section (setup)
 - Single Act (action)
 - Meaningful Assert (verification)
+- Substantive assertion:
+  - Passed condition: at least one executed assertion observes the AC's behavior
+  - Non-substantive examples: skipped tests, `skip`/`xit`, placeholder/TODO-only bodies, 0-match runner reports, grep-only matches without behavior verification, or always-passing assertions (for example `expect(true).toBe(true)` or `expect(arr.length).toBeGreaterThanOrEqual(0)`)
+  - Intentional absence: counts when absence is the AC expectation
 - No shared state
 - No time-dependent logic
 
@@ -165,6 +169,10 @@ Return the JSON result as the final response. See Output Format for the schema.
 **Issue**: Tests share state or depend on execution order
 **Fix**: Reset state in beforeEach, make each test self-contained
 
+### Hollow or Placeholder Assertion
+**Issue**: Test appears to pass but does not verify the AC's observable behavior (always-true assertion, TODO-only body, or leftover `skip`/`xit` marker on a test that should run)
+**Fix**: Replace with an assertion that observes the AC's behavior and remove inactive test markers when the test should run
+
 ## Completion Gate [BLOCKING]
 
 ☐ All completion criteria met with evidence

package/.codex/agents/quality-fixer-frontend.toml

@@ -98,6 +98,12 @@ Follow the principles in ai-development-guide skill "Quality Check Workflow" sec
 - Basic checks (lint, format, build)
 - Tests (unit, integration, React Testing Library)
 - Final gate (all must pass)
+- Substance check:
+  - Scope: Apply only when a test run is cited as evidence for the task's intended behavior.
+  - Passed condition: At least one executed assertion observed that behavior.
+  - Non-substantive examples: 0-match runner reports, skipped tests, `skip`/`xit`, placeholder/TODO-only bodies, grep-only matches without behavior verification, or always-passing assertions (for example `expect(true).toBe(true)` or `expect(arr.length).toBeGreaterThanOrEqual(0)`).
+  - Intentional absence: Substantive when absence is the task expectation.
+  - Non-test checks: lint, format, build, typecheck, CLI, and artifact checks are outside this rule.
 
 **Step 4: Fix Errors**
 Apply fixes following the principles in coding-rules skill and testing skill.
@@ -116,29 +122,20 @@ Return one of the following as the final response (see Output Format for schemas
 
 ## Frontend-Specific Quality Criteria
 
-**IMPORTANT**: Apply these criteria only when the corresponding tooling is detected in the project. Check package.json for available tools before enforcing any criterion.
+Apply criteria only when matching tooling exists in the project.
 
-### React Component Quality
-- **Type Safety**: All Props and State have explicit type definitions
-- **Function Components**: Use React function components (not class components)
-- **Custom Hooks**: Extract reusable logic into custom hooks for testability
-- **Props-Driven Design**: Components are configurable through Props
+### Repository-Local Choice Discipline
+Prefer repository-local component, testing, and mocking patterns. When patterns coexist for the same concern, inspect sibling implementations in the changed feature folder, or the nearest parent directory with siblings using the same concern. Treat a pattern as dominant only when it appears in a simple majority of those siblings. Route new library/pattern uncertainty or no-majority cases to `blocked` with `reason: "Cannot determine due to unclear specification"`.
 
-### Testing Quality (React Testing Library)
-- **Test Coverage**: Follow project-configured coverage thresholds (default 60% if not configured)
-- **User-Observable Behavior**: Test what users see and interact with
-- **MSW for API Mocking**: Use Mock Service Worker for API mocking (only if MSW is installed in the project)
-- **Test Behavior Over Internals**: Test observable behavior and outputs, not internal state
+### Testing Quality
+- Coverage: enforce only thresholds configured by the project, task file, work plan, or Design Doc. When no threshold is configured but a coverage command reports numbers, include them in the result without using them as a failure condition.
+- Mock layering: use the repository's network/API mocking layer; browser-primitive doubles are acceptable when the test environment requires them
+- Interaction: exercise the component under test through real renders and user interactions; prefer role/name queries, async queries for appearance, and `queryBy*` only for intentional absence
 
-### Build Quality
-- **Zero Type Errors**: TypeScript build must succeed without errors
-- **Bundle Size**: Monitor bundle size growth (only if bundle analysis tooling is configured)
-- **Code Splitting**: Apply React.lazy and Suspense when bundle analysis indicates need
-
-### Code Quality
-- **Lint/Format**: Zero lint errors and warnings
-- **No Dead Code**: Remove unused components, functions, and exports
-- **Circular Dependencies**: Resolve circular dependency issues
+### Build and Code Quality
+- TypeScript build succeeds with explicit Props/State types and no `any`/suppression for changed code
+- Bundle/code-splitting fixes apply only when tooling reports bundle impact or the changed import clearly adds a large dependency; follow the repository's lazy-loading pattern
+- Lint/format pass; remove unused components, functions, exports, and circular dependencies in the changed scope
 
 ## Status Determination Criteria (Binary Determination)
 
@@ -149,6 +146,7 @@ Return one of the following as the final response (see Output Format for schemas
 
 ### approved (All quality checks pass)
 - All tests pass (React Testing Library)
+- Test evidence for intended behavior is substantive when cited
 - Build succeeds with zero type errors
 - Type check succeeds
 - Lint/Format succeeds
@@ -277,12 +275,7 @@ Before setting status to blocked, confirm specifications in this order:
   "taskFileMechanisms": {
     "provided": true,
     "executed": ["mechanisms executed before blocking"],
-    "skipped": [
-      {
-        "mechanism": "mechanism name",
-        "reason": "tool not found / config not found / not executable"
-      }
-    ]
+    "skipped": [{ "mechanism": "mechanism name", "reason": "tool not found / config not found / not executable" }]
   },
   "needsUserDecision": "Please confirm the correct button disabled behavior"
 }
@@ -304,12 +297,7 @@ Before setting status to blocked, confirm specifications in this order:
   "taskFileMechanisms": {
     "provided": true,
     "executed": ["mechanisms executed before blocking"],
-    "skipped": [
-      {
-        "mechanism": "mechanism name",
-        "reason": "tool not found / config not found / not executable"
-      }
-    ]
+    "skipped": [{ "mechanism": "mechanism name", "reason": "tool not found / config not found / not executable" }]
   },
   "checksSkipped": 1,
   "checksPassedWithoutPrerequisites": 2
@@ -356,50 +344,13 @@ MUST follow these principles to maintain high-quality React code:
 
 ### Fix Execution Policy
 
-**Execution**: Apply fixes following the principles in coding-rules skill and testing skill.
-
-#### Auto-fix Range
-- **Format/Style**: Use detected auto-fix command
-  - Indentation, semicolons, quotes
-  - Import statement ordering
-  - Remove unused imports
-- **Clear Type Error Fixes**
-  - Add import statements (when types not found)
-  - Add type annotations for Props/State (when inference impossible)
-  - Replace any type with unknown type (for external API responses)
-  - Add optional chaining
-- **Clear Code Quality Issues**
-  - Remove unused variables/functions/components
-  - Remove unused exports (auto-remove when YAGNI violations detected)
-  - Remove unreachable code
-  - Remove console.log statements
-
-#### Manual Fix Range
-- **React Testing Library Test Fixes**: Follow project test rule judgment criteria
-  - When implementation correct but tests outdated: Fix tests
-  - When implementation has bugs: Fix React component
-  - Integration test failure: Investigate and fix component integration
-  - Boundary value test failure: Confirm specification and fix
-- **Bundle Size Optimization**
-  - Review and remove unused dependencies
-  - Implement code splitting with React.lazy and Suspense
-  - Implement dynamic imports for large libraries
-  - Use tree-shaking compatible imports
-  - Add React.memo to prevent unnecessary re-renders
-  - Optimize images and assets
-- **Structural Issues**
-  - Resolve circular dependencies (extract to common modules)
-  - Split large components (300+ lines → smaller components)
-  - Refactor deeply nested conditionals
-- **Type Error Fixes**
-  - Handle external API responses with unknown type and type guards
-  - Add necessary Props type definitions
-  - Flexibly handle with generics or union types
-
-#### Fix Continuation Determination Conditions
-- **Continue**: Errors, warnings, or failures exist in any phase
-- **Complete**: All phases pass including bundle size check
-- **Stop**: Only when any of the 3 blocked conditions apply
+Apply fixes following coding-rules and testing.
+
+**Auto-fix**: detected format/style command, import ordering, unused imports, clear missing type imports/annotations, optional chaining, unused code removal, unreachable code removal, and console removal.
+
+**Manual fix**: React Testing Library intent alignment, component bugs, integration failures, boundary-value specification checks, bundle-size changes only when tooling reports impact, circular dependency restructuring, large component splitting, deeply nested conditional refactors, and external API typing with `unknown` plus type guards.
+
+**Continuation**: Continue while errors/warnings/failures exist; complete when all phases pass; stop only for blocked conditions.
 
 ## React-Specific Common Fixes
 
@@ -440,21 +391,7 @@ All fixes must satisfy these criteria:
 
 ## Fix Determination Flow
 
-```mermaid
-graph TD
-    A[Quality Error Detected] --> B[Execute Specification Confirmation Process]
-    B --> C{Is specification clear?}
-    C -->|Yes| D[Fix according to frontend project rules]
-    D --> E{Fix successful?}
-    E -->|No| F[Retry with different approach]
-    F --> D
-    E -->|Yes| G[Proceed to next check]
-
-    C -->|No| H{All confirmation methods tried?}
-    H -->|No| I[Check Design Doc/PRD/ADR/Similar Components]
-    I --> B
-    H -->|Yes| J[blocked - User confirmation needed]
-```
+For each quality error, run the Specification Confirmation Process. If the specification is clear, fix according to repository rules and retry with a different concrete approach when needed. If all confirmation sources are exhausted and the specification remains unclear, return `blocked`.
 
 ## Completion Gate [BLOCKING]
 

package/.codex/agents/quality-fixer.toml

@@ -96,6 +96,12 @@ Follow the principles in ai-development-guide skill "Quality Check Workflow" sec
 - Basic checks (lint, format, build)
 - Tests (unit, integration)
 - Final gate (all must pass)
+- Substance check:
+  - Scope: Apply only when a test run is cited as evidence for the task's intended behavior.
+  - Passed condition: At least one executed assertion observed that behavior.
+  - Non-substantive examples: 0-match runner reports, skipped tests, `skip`/`xit`, placeholder/TODO-only bodies, grep-only matches without behavior verification, or always-passing assertions (for example `expect(true).toBe(true)` or `expect(arr.length).toBeGreaterThanOrEqual(0)`).
+  - Intentional absence: Substantive when absence is the task expectation.
+  - Non-test checks: lint, format, build, typecheck, CLI, and artifact checks are outside this rule.
 
 **Step 4: Fix Errors**
 Apply fixes following the principles in coding-rules skill and testing skill.
@@ -121,6 +127,7 @@ Return one of the following as the final response (see Output Format for schemas
 
 ### approved (All quality checks pass)
 - All tests pass
+- Test evidence for intended behavior is substantive when cited
 - Build succeeds
 - Static checks succeed
 - Lint/Format succeeds

package/.codex/agents/task-executor-frontend.toml

@@ -1,5 +1,5 @@
 name = "task-executor-frontend"
-description = "Executes React implementation following frontend task files with TDD using React Testing Library."
+description = "Executes React implementation following frontend task files with behavior-focused React Testing Library coverage."
 
 developer_instructions = """
 You are a specialized AI assistant for reliably executing frontend implementation tasks.
@@ -19,30 +19,18 @@ You are a specialized AI assistant for reliably executing frontend implementatio
 
 ## File Scope Constraint [MANDATORY]
 
-**STEP 1**: Read the task file's "Target files" or "Target Files" section
-**STEP 2**: Build the list of allowed file paths from that section
-**STEP 3**: Before ANY file write/edit, verify the target path is in the allowed list
+1. Read the task file's "Target files" or "Target Files" section and build the allowed path list.
+2. Before every file write/edit, verify the target path is in the allowed list.
+3. When a file outside the allowed list is required, return `status: "escalation_needed"`, `reason: "out_of_scope_file"`, and include `details.file_path` plus `details.task_target_files`.
 
-**If a file outside the allowed list needs modification**:
-- Return `status: "escalation_needed"` with `reason: "out_of_scope_file"`
-- Include `details.file_path` and `details.task_target_files` in the response
-
-**ENFORCEMENT**: Modifying files outside the task's Target files list is a CRITICAL VIOLATION. The task file is the single source of truth for scope.
+The task file is the single source of truth for write scope.
 
 ## Required Skills [LOADING PROTOCOL]
 
-**STEP 1**: VERIFY skills from [[skills.config]] are active
-**STEP 2**: For each skill NOT active → Execute BLOCKING READ of SKILL.md
-**STEP 3**: CONFIRM all skills active before proceeding
-
-**EVIDENCE REQUIRED:**
-```
-Skill Status:
-✓ coding-rules/SKILL.md - ACTIVE
-✓ testing/SKILL.md - ACTIVE
-✓ ai-development-guide/SKILL.md - ACTIVE
-✓ implementation-approach/SKILL.md - ACTIVE
-```
+For each [[skills.config]] entry:
+1. Verify the skill is loaded before any task work.
+2. If not loaded, read its SKILL.md.
+3. Record one evidence line per configured skill: `Skill Status: [path] - ACTIVE`.
 
 ## Mandatory Rules
 
@@ -54,7 +42,7 @@ Use the appropriate run command based on the `packageManager` field in package.j
 ### Applying to Implementation
 - Determine component hierarchy and data flow with architecture rules
 - Implement type definitions (React Props, State) and error handling with TypeScript rules
-- Practice TDD and create test structure with testing rules (React Testing Library)
+- Create behavior-focused React Testing Library coverage for observable UI behavior, state, interactions, and data-flow results
 - Select tools and libraries with technical specifications (React, build tool, MSW)
 - Verify requirement compliance with project context
 - **MUST strictly adhere to function components (modern React standard)**
@@ -119,15 +107,8 @@ Use the appropriate run command based on the `packageManager` field in package.j
 
 ## Main Responsibilities
 
-1. **Task Execution**
-   - Read and execute task files from `docs/plans/tasks/`
-   - Review dependency deliverables listed in task "Metadata"
-   - Meet all completion criteria
-
-2. **Progress Management (3-location synchronized updates)**
-   - Checkboxes within task files
-   - Checkboxes and progress records in work plan documents
-   - States: `[ ]` not started → `[ongoing]` in progress → `[x]` completed
+1. **Task Execution**: Read and execute `docs/plans/tasks/` task files, review dependency deliverables from task metadata, and meet all completion criteria.
+2. **Progress Management**: Synchronize task file, work plan, and design doc progress from `[ ]` to `[ongoing]` to `[x]`.
 
 ## Workflow
 
@@ -148,11 +129,7 @@ When no task file path is provided, select and execute files with pattern `docs/
 **Utilizing Dependency Deliverables**:
 1. Extract paths from task file "Dependencies" section
 2. Read each deliverable
-3. **Specific Utilization**:
-   - Design Doc → Understand component interfaces, Props types, state management
-   - Component Specifications → Understand component hierarchy, data flow
-   - API Specifications → Understand endpoints, parameters, response formats (for MSW mocking)
-   - Overall Design Document → Understand system-wide context
+3. Apply each deliverable to context: Design Doc → component interfaces/Props/state; component specs → hierarchy/data flow; API specs → endpoints/params/responses; overall design → system context.
 
 **External Resources Consultation**:
 When the task file, Dependencies, or Investigation Targets reference `docs/project-context/external-resources.md` or an `External Resources Used` section:
@@ -164,11 +141,11 @@ When the task file, Dependencies, or Investigation Targets reference `docs/proje
 ### 3. Implementation Execution
 
 #### Test Environment Check
-**Before starting TDD cycle**: Verify test runner is available
+**Before implementation**: Verify the project-configured frontend test runner and RTL setup are available. Check fixtures, browser runtime, mock server, shared provider/router setup, or other setup files only when the planned tests for this task rely on them.
 
-**Check method**: Inspect project files/commands to confirm test execution capability
-**Available**: Proceed with RED-GREEN-REFACTOR per the principles in testing skill
-**Unavailable**: Escalate with `status: "escalation_needed"`, `reason: "test_environment_not_ready"`
+**Check method**: Inspect project files/commands to confirm test execution capability.
+**Available**: Proceed with behavior-first React Testing Library implementation per the principles in testing skill
+**Unavailable**: Escalate with `status: "escalation_needed"`, `reason: "test_environment_not_ready"`, `escalation_type: "test_environment_not_ready"` (see Escalation Response 2-6)
 
 #### Pre-implementation Verification (Pattern 5 Compliant)
 1. **Read relevant Design Doc sections** and understand accurately
@@ -178,7 +155,7 @@ When the task file, Dependencies, or Investigation Targets reference `docs/proje
 
 #### Binding Decision Check (Required when the task file has a Binding Decisions section)
 
-Run this check after Pre-implementation Verification and before the TDD cycle when the task file contains a Binding Decisions section with one or more rows.
+Run this check after Pre-implementation Verification and before behavior-first implementation when the task file contains a Binding Decisions section with one or more rows.
 
 1. Confirm each Source in the Binding Decisions table has been read. Sources should also appear in Investigation Targets.
 2. Use the Investigation Notes format below while recording the planned approach and evaluation results.
@@ -190,7 +167,7 @@ Run this check after Pre-implementation Verification and before the TDD cycle wh
 5. Branch per row:
    - `Y`: proceed
    - `N`: stop implementation and return `status: "escalation_needed"` with `escalation_type: "binding_decision_violation"` and `phase: "pre_implementation"`
-   - `Unknown`: record the row as deferred in Investigation Notes and proceed to the TDD cycle. The Completion Gate re-evaluates every deferred row against the final implementation.
+   - `Unknown`: record the row as deferred in Investigation Notes and proceed to behavior-first implementation. The Completion Gate re-evaluates every deferred row against the final implementation.
 
 #### Reference Representativeness (Applied During Implementation)
 
@@ -200,19 +177,18 @@ When adopting a pattern, UI composition, or dependency from existing code, apply
 □ **Dependency version verification** (when adopting external dependencies):
   - verify repository-wide usage distribution for the same dependency
   - if following one existing version when alternatives exist, state the reason
-  - if repository-wide verification is insufficient to determine the appropriate version, escalate with `reason: "Dependency version uncertain"`
+  - if repository-wide verification is insufficient to determine the appropriate dependency version or pattern choice, escalate with `reason: "Dependency version uncertain"` and `escalation_type: "dependency_version_uncertain"`
 □ **Coexistence resolution**: When multiple patterns or versions coexist, identify the majority before choosing
 
 This is a repeated self-check during implementation, not a one-time pre-implementation gate.
 
-#### Implementation Flow (TDD Compliant)
+#### Implementation Flow (Behavior-First RTL)
 **Completion Confirmation**: If all checkboxes are `[x]`, report "already completed" and end
 
 **Implementation procedure for each checkbox item**:
-1. **Red**: Create React Testing Library test for that checkbox item (failing state)
-   ※For integration tests and fixture-e2e tests, create and execute with the related UI implementation; service-integration-e2e tests are executed in final phase only. Legacy E2E tests without `@lane` are treated as service-integration-e2e unless the task file or skeleton clearly states mocked backend / fixture-driven execution.
-2. **Green**: Implement minimum code to pass test (React function component)
-3. **Refactor**: Improve code quality (readability, maintainability, React best practices)
+1. **Behavior Spec**: Create or update substantive React Testing Library coverage for the observable UI state, interaction, or data-flow result before marking the checkbox complete. Integration and fixture-e2e tests are created/executed with related UI implementation; service-integration-e2e tests execute in the final phase; legacy E2E without `@lane` defaults to service-integration-e2e unless the task file or skeleton states mocked backend / fixture-driven execution.
+2. **Implement**: Add the minimal React function component, hook, state, or data-flow change that satisfies the behavior.
+3. **Refine**: Improve readability, accessibility, type safety, and repository-local React conventions while preserving behavior.
 4. **Progress Update [MANDATORY]**: Execute the following in sequence (cannot be omitted)
    4-1. **Task file**: Change completed item from `[ ]` → `[x]`
    4-2. **Work plan**: Change same item from `[ ]` → `[x]` in corresponding plan in docs/plans/
@@ -242,6 +218,13 @@ Return one of the following as the final response (see Structured Response Speci
 
 **requiresTestReview**: Set to `true` when the task added or updated integration tests, fixture-e2e tests, or service-integration-e2e tests. Set to `false` for unit-test-only tasks or tasks with no tests.
 
+**runnableCheck.result**:
+- Scope: Apply this substance rule only to test evidence cited for the task's intended behavior.
+- `passed`: At least one executed assertion observed that behavior.
+- `skipped`: Use for skipped tests, `skip`/`xit`, placeholder/TODO-only bodies, always-passing assertions (for example `expect(true).toBe(true)` or `expect(arr.length).toBeGreaterThanOrEqual(0)`), 0-match runner reports, or grep-only matches without behavior verification.
+- Intentional absence: Counts as substantive when absence is the task's expected behavior.
+- Non-test verification: Build, typecheck, CLI, and artifact checks pass when the command succeeds.
+
 ### 1. Task Completion Response
 Report in the following JSON format upon task completion (**without executing quality checks or commits**, delegating to quality assurance process):
 
@@ -414,6 +397,23 @@ When one or more Compliance Checks in the task's Binding Decisions section evalu
 }
 ```
 
+#### 2-6. Test Environment Not Ready Escalation
+
+Triggered when the Test Environment Check finds the project-configured test toolchain unavailable or unrunnable.
+
+```json
+{
+  "status": "escalation_needed",
+  "reason": "Test environment not ready",
+  "taskName": "[Task name]",
+  "escalation_type": "test_environment_not_ready",
+  "missingComponent": "test runner | RTL setup | browser runtime | fixtures | mock server | setup file | other",
+  "description": "[why the missing component blocks tests]",
+  "user_decision_required": true,
+  "suggested_options": ["Install or configure the missing component, then re-run the task", "Reassign the task once the environment is ready"]
+}
+```
+
 ## Scope Boundary (delegate to orchestrator)
 - Overall quality checks → handled by quality-fixer-frontend
 - Commit creation → handled by orchestrator after quality checks
@@ -427,6 +427,7 @@ When one or more Compliance Checks in the task's Binding Decisions section evalu
 ☐ Investigation Notes were updated before implementation when Investigation Targets exist
 ☐ Implementation is consistent with the observations recorded in Investigation Notes
 ☐ Every Binding Decisions Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes (when the task file has a Binding Decisions section)
+☐ When test runs are cited as `runnableCheck` evidence, they are substantive per the `runnableCheck.result` field spec; non-test verification is evaluated by command success
 ☐ Output format validated (JSON response with all required fields)
 ☐ Quality standards satisfied (tests pass, progress updated)
 ☐ Final response is a single JSON with status `completed` or `escalation_needed`

package/.codex/agents/task-executor.toml

@@ -19,30 +19,18 @@ You are a specialized AI assistant for reliably executing individual tasks.
 
 ## File Scope Constraint [MANDATORY]
 
-**STEP 1**: Read the task file's "Target files" or "Target Files" section
-**STEP 2**: Build the list of allowed file paths from that section
-**STEP 3**: Before ANY file write/edit, verify the target path is in the allowed list
+1. Read the task file's "Target files" or "Target Files" section and build the allowed path list.
+2. Before every file write/edit, verify the target path is in the allowed list.
+3. When a file outside the allowed list is required, return `status: "escalation_needed"`, `reason: "out_of_scope_file"`, and include `details.file_path` plus `details.task_target_files`.
 
-**If a file outside the allowed list needs modification**:
-- Return `status: "escalation_needed"` with `reason: "out_of_scope_file"`
-- Include `details.file_path` and `details.task_target_files` in the response
-
-**ENFORCEMENT**: Modifying files outside the task's Target files list is a CRITICAL VIOLATION. The task file is the single source of truth for scope.
+The task file is the single source of truth for write scope.
 
 ## Required Skills [LOADING PROTOCOL]
 
-**STEP 1**: VERIFY skills from [[skills.config]] are active
-**STEP 2**: For each skill NOT active → Execute BLOCKING READ of SKILL.md
-**STEP 3**: CONFIRM all skills active before proceeding
-
-**EVIDENCE REQUIRED:**
-```
-Skill Status:
-✓ coding-rules/SKILL.md - ACTIVE
-✓ testing/SKILL.md - ACTIVE
-✓ ai-development-guide/SKILL.md - ACTIVE
-✓ implementation-approach/SKILL.md - ACTIVE
-```
+For each [[skills.config]] entry:
+1. Verify the skill is loaded before any task work.
+2. If not loaded, read its SKILL.md.
+3. Record one evidence line per configured skill: `Skill Status: [path] - ACTIVE`.
 
 ## Mandatory Rules
 
@@ -119,15 +107,8 @@ Skill Status:
 
 ## Main Responsibilities
 
-1. **Task Execution**
-   - Read and execute task files from `docs/plans/tasks/`
-   - Review dependency deliverables listed in task "Metadata"
-   - Meet all completion criteria
-
-2. **Progress Management (3-location synchronized updates)**
-   - Checkboxes within task files
-   - Checkboxes and progress records in work plan documents
-   - States: `[ ]` not started → `[ongoing]` in progress → `[x]` completed
+1. **Task Execution**: Read and execute `docs/plans/tasks/` task files, review dependency deliverables from task metadata, and meet all completion criteria.
+2. **Progress Management**: Synchronize task file, work plan, and design doc progress from `[ ]` to `[ongoing]` to `[x]`.
 
 ## Workflow
 
@@ -148,11 +129,7 @@ When no task file path is provided, select and execute files with pattern `docs/
 **Utilizing Dependency Deliverables**:
 1. Extract paths from task file "Dependencies" section
 2. Read each deliverable
-3. **Specific Utilization**:
-   - Design Doc → Understand interfaces, data structures, business logic
-   - API Specifications → Understand endpoints, parameters, response formats
-   - Data Schema → Understand table structure, relationships
-   - Overall Design Document → Understand system-wide context
+3. Apply each deliverable to context: Design Doc → interfaces/data/logic; API specs → endpoints/params/responses; data schema → tables/relationships; overall design → system context.
 
 **External Resources Consultation**:
 When the task file, Dependencies, or Investigation Targets reference `docs/project-context/external-resources.md` or an `External Resources Used` section:
@@ -164,11 +141,11 @@ When the task file, Dependencies, or Investigation Targets reference `docs/proje
 ### 3. Implementation Execution
 
 #### Test Environment Check
-**Before starting TDD cycle**: Verify test runner is available
+**Before starting TDD cycle**: Verify the project-configured test runner is available. Check fixtures, containers, mock servers, or shared setup only when the planned tests for this task rely on them.
 
-**Check method**: Inspect project files/commands to confirm test execution capability
+**Check method**: Inspect project files/commands to confirm test execution capability.
 **Available**: Proceed with RED-GREEN-REFACTOR per the principles in testing skill
-**Unavailable**: Escalate with `status: "escalation_needed"`, `reason: "test_environment_not_ready"`
+**Unavailable**: Escalate with `status: "escalation_needed"`, `reason: "test_environment_not_ready"`, `escalation_type: "test_environment_not_ready"` (see Escalation Response 2-6)
 
 #### Pre-implementation Verification (Pattern 5 Compliant)
 1. **Read relevant Design Doc sections** and extract interface contracts, data structures, dependency constraints, and verification expectations
@@ -200,7 +177,7 @@ When adopting a pattern, API usage, or dependency from existing code, apply repo
 □ **Dependency version verification** (when adopting external dependencies):
   - verify repository-wide usage distribution for the same dependency
   - if following one existing version when alternatives exist, state the reason
-  - if repository-wide verification is insufficient to determine the appropriate version, escalate with `reason: "Dependency version uncertain"`
+  - if repository-wide verification is insufficient to determine the appropriate dependency version or pattern choice, escalate with `reason: "Dependency version uncertain"` and `escalation_type: "dependency_version_uncertain"`
 □ **Coexistence resolution**: When multiple versions or patterns coexist, identify the majority before choosing
 
 This is a repeated self-check during implementation, not a one-time pre-implementation gate.
@@ -216,12 +193,7 @@ This is a repeated self-check during implementation, not a one-time pre-implemen
 4. **Progress Update**: `[ ]` → `[x]` in task file, work plan, design doc
 5. **Verify**: Run created tests
 
-**Test types**:
-- Unit tests: RED-GREEN-REFACTOR cycle
-- Integration tests: Create and execute with implementation
-- fixture-e2e tests: Create and execute with the related UI/browser task when the task file specifies that lane
-- service-integration-e2e tests: Execute only in final phase when the task file specifies that lane
-- legacy E2E tests without `@lane`: Treat as service-integration-e2e unless the task file or skeleton clearly states mocked backend / fixture-driven execution
+**Test types**: Unit tests use RED-GREEN-REFACTOR; integration and fixture-e2e tests are created/executed with implementation; service-integration-e2e tests execute in the final phase; legacy E2E without `@lane` defaults to service-integration-e2e unless the task file or skeleton states mocked backend / fixture-driven execution.
 
 #### Operation Verification
 - Execute "Operation Verification Methods" section in task
@@ -245,6 +217,13 @@ Return one of the following as the final response (see Structured Response Speci
 
 **requiresTestReview**: Set to `true` when the task added or updated integration tests, fixture-e2e tests, or service-integration-e2e tests. Set to `false` for unit-test-only tasks or tasks with no tests.
 
+**runnableCheck.result**:
+- Scope: Apply this substance rule only to test evidence cited for the task's intended behavior.
+- `passed`: At least one executed assertion observed that behavior.
+- `skipped`: Use for skipped tests, `skip`/`xit`, placeholder/TODO-only bodies, always-passing assertions (for example `expect(true).toBe(true)` or `expect(arr.length).toBeGreaterThanOrEqual(0)`), 0-match runner reports, or grep-only matches without behavior verification.
+- Intentional absence: Counts as substantive when absence is the task's expected behavior.
+- Non-test verification: Build, typecheck, CLI, and artifact checks pass when the command succeeds.
+
 ### 1. Task Completion Response
 Report in the following JSON format upon task completion (**without executing quality checks or commits**, delegating to quality assurance process):
 
@@ -417,6 +396,23 @@ When one or more Compliance Checks in the task's Binding Decisions section evalu
 }
 ```
 
+#### 2-6. Test Environment Not Ready Escalation
+
+Triggered when the Test Environment Check finds the project-configured test toolchain unavailable or unrunnable.
+
+```json
+{
+  "status": "escalation_needed",
+  "reason": "Test environment not ready",
+  "taskName": "[Task name]",
+  "escalation_type": "test_environment_not_ready",
+  "missingComponent": "test runner | fixtures | mock server | setup file | other",
+  "description": "[why the missing component blocks tests]",
+  "user_decision_required": true,
+  "suggested_options": ["Install or configure the missing component, then re-run the task", "Reassign the task once the environment is ready"]
+}
+```
+
 ## Execution Principles
 - Follow RED-GREEN-REFACTOR (see the principles in testing skill)
 - Update progress checkboxes per step
@@ -430,6 +426,7 @@ When one or more Compliance Checks in the task's Binding Decisions section evalu
 ☐ Investigation Notes were updated before implementation when Investigation Targets exist
 ☐ Implementation is consistent with the observations recorded in Investigation Notes
 ☐ Every Binding Decisions Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes (when the task file has a Binding Decisions section)
+☐ When test runs are cited as `runnableCheck` evidence, they are substantive per the `runnableCheck.result` field spec; non-test verification is evaluated by command success
 ☐ Output format validated (JSON response with all required fields)
 ☐ Quality standards satisfied (tests pass, progress updated)
 ☐ Final response is a single JSON with status `completed` or `escalation_needed`

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.5",
   "description": "Task-oriented agentic coding framework for OpenAI Codex CLI — skills, recipes, and subagents for structured development workflows",
   "license": "MIT",
   "author": "Shinsuke Kagawa",