codex-workflows 0.6.2 → 0.6.4

package/.agents/skills/documentation-criteria/SKILL.md

@@ -81,7 +81,7 @@ description: "Documentation creation criteria for PRD, ADR, Design Doc, UI Spec,
 
 ### Work Plan
 **Purpose**: Implementation task management and progress tracking
-**Scope**: Task breakdown, dependencies, schedule estimates, test skeleton file paths, Verification Strategy summaries from each Design Doc, Design-to-Plan Traceability mapping for implementation-relevant technical requirements, final Quality Assurance phase, and progress tracking only. Technical rationale belongs in ADR and design details belong in Design Doc.
+**Scope**: Task breakdown, dependencies, schedule estimates, test skeleton file paths, Verification Strategy summaries from each Design Doc, Design-to-Plan Traceability mapping for implementation-relevant technical requirements, ADR Bindings for implementation-binding ADR decisions, final Quality Assurance phase, and progress tracking only. Technical rationale belongs in ADR and design details belong in Design Doc.
 
 **Phase Division Criteria**:
 

package/.agents/skills/documentation-criteria/references/design-template.md

@@ -30,8 +30,9 @@ unknowns:
 
 ### Prerequisite ADRs
 
-- [ADR File Name]: [Related decision items]
+- docs/adr/ADR-XXXX-title.md: [Related decision items]
 - Reference common technical ADRs when applicable
+- ADR placeholders use the repository ADR filename convention: replace `XXXX` with the four-digit ADR number and `title` with the file slug.
 
 ### External Resources Used
 

package/.agents/skills/documentation-criteria/references/plan-template.md

@@ -11,9 +11,11 @@ Implementation Readiness: pending
 - Design Doc(s):
   - [docs/design/XXX.md]
   - [docs/design/YYY.md] (if multiple, e.g. backend + frontend)
-- ADR: [docs/adr/ADR-XXXX.md] (if any)
+- ADR: docs/adr/ADR-XXXX-title.md (if any)
 - PRD: [docs/prd/XXX.md] (if any)
 
+ADR placeholders use the repository ADR filename convention: replace `XXXX` with the four-digit ADR number and `title` with the file slug.
+
 ## Verification Strategies (from Design Docs)
 
 Repeat this block for each Design Doc when multiple Design Docs exist. Preserve each strategy's identity and source document path. Merge strategies only when the Design Docs explicitly define a shared one.
@@ -77,6 +79,23 @@ Include this section when a UI Spec is among the inputs. Map each UI component s
 
 **Reference key rule**: The component identifier is the UI Spec section heading verbatim. Component headings must be unique within a UI Spec.
 
+## ADR Bindings
+
+Include this section when ADRs are provided as input or listed in the Design Doc's "Prerequisite ADRs" section. Map each implementation-binding ADR decision to the task(s) it constrains. Omit this section when no ADR applies.
+
+A decision is **implementation-binding** when it constrains code placement, dependency direction, contract/schema shape, data flow, or persistence. Acceptance criteria and required behavior remain in the Design Doc; this table covers structural implementation constraints from ADRs.
+
+| ADR | Source Section | Axis (exactly one value) | Binding Decision | Covered By Task(s) | Gap Status | Notes |
+|-----|----------------|--------------------------|------------------|--------------------|------------|-------|
+| docs/adr/ADR-XXXX-title.md | Decision | dependency_direction | [One implementation-binding decision sentence, copied or condensed from the named section] | P1-T1, P2-T1 | covered | |
+| docs/adr/ADR-YYYY-title.md | Implementation Guidance | persistence | [Binding decision with no covering task yet] | - | gap | [Justification and user-confirmation note] |
+
+**Axis values**: `placement` (where code belongs), `dependency_direction` (allowed import or call direction), `contract_schema` (interface, payload, or schema shape), `data_flow` (how data moves across components), `persistence` (where and how state is stored)
+
+One row represents one independently checkable binding decision. A single ADR can contribute multiple rows. A single task can appear in multiple rows.
+
+**Gap Status values**: `covered` (mapped to one or more tasks), `gap` (no task exists yet; set Covered By Task(s) to `-`, include justification in Notes, and require user confirmation before plan approval)
+
 ## Connection Map
 
 Include this section when implementation crosses runtime, process, deployment, or service boundaries. Omit it when the change stays inside one runtime or only uses in-process package imports.

package/.agents/skills/documentation-criteria/references/task-template.md

@@ -17,9 +17,19 @@ Metadata:
 Files to read before starting implementation. Use concrete file paths, optionally with a section/function hint:
 - [e.g., src/orders/checkout.ts (processOrder function)]
 
+## Binding Decisions
+(Include this section when the work plan's ADR Bindings table covers this task. Omit otherwise.)
+
+Each row is an ADR decision the implementation in this task must comply with.
+
+| Source | Axis | Decision | Compliance Check |
+|--------|------|----------|------------------|
+| docs/adr/ADR-XXXX-title.md (§ <Source Section>) | [Axis value copied verbatim from the work plan's ADR Bindings row] | [Binding decision copied from the work plan's ADR Bindings row] | [Y/N-answerable positive predicate that evaluates whether the planned and final implementation satisfy the decision] |
+
 ## Investigation Notes
 Brief observations recorded after reading Investigation Targets:
 - [path] - [interfaces, control/data flow, state transitions, side effects relevant to this task]
+- When Binding Decisions exist, record the planned implementation approach and each Compliance Check result here.
 
 ## Implementation Steps (TDD: Red-Green-Refactor)
 ### 1. Red Phase
@@ -52,6 +62,7 @@ Brief observations recorded after reading Investigation Targets:
 - [ ] All added tests pass
 - [ ] Operation verified per Operation Verification Methods above
 - [ ] Deliverables created (for research/design tasks)
+- [ ] When Binding Decisions exist, every Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes
 
 ## Notes
 - Impact scope: [Areas where changes may propagate]

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/recipe-prepare-implementation/SKILL.md

@@ -31,7 +31,7 @@ Each criterion produces `pass`, `fail`, or `not_applicable`, with file:line evid
 
 | ID | Criterion | Pass Evidence |
 |----|-----------|---------------|
-| R1 | Verification Strategy references resolve | Every command, file path, function, endpoint, fixture, seed, and test reference in the work plan's Verification Strategies either exists now or is the deliverable of a task in the plan |
+| R1 | Verification Strategy and ADR Binding references resolve | Every command, file path, function, endpoint, fixture, seed, and test reference in the work plan's Verification Strategies either exists now or is the deliverable of a task in the plan; every ADR Bindings source path resolves; every ADR Bindings `covered` row references existing task IDs |
 | R2 | E2E prerequisites are addressed | For each fixture-e2e or service-integration-e2e skeleton, every noted precondition is present in the codebase or covered by a Phase 0 task |
 | R3 | Phase 1 observability exists | The first implementation phase includes at least one operation verification method executable at task completion using existing files, prior Phase 0 deliverables, or the task's own output |
 | R4 | UI rendering surface exists | When the plan implements UI components, a fixture entry, dev route, Storybook story, preview harness, or equivalent render surface exists or is covered by a Phase 0 task |
@@ -47,11 +47,12 @@ Read the work plan passed in `$ARGUMENTS`; if absent, select the most recent non
 - Verification Strategies
 - Quality Assurance Mechanisms
 - Design-to-Plan Traceability
+- ADR Bindings
 - UI Spec Component -> Task Mapping
 - Connection Map
 - test skeleton references and E2E absence reasons
 - phase structure and task IDs
-- referenced Design Docs and UI Specs
+- referenced Design Docs, ADRs, and UI Specs
 
 If no work plan exists, stop and report the missing prerequisite.
 

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`, `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`), `filesModified`, `requiresTestReview` |
 | `quality-fixer*` | `status`, `reason`, `stubFindings`, `blockingIssues`, `missingPrerequisites` |
 | `document-reviewer` | `verdict.decision`, `verdict.conditions` |
 | `code-verifier` | `summary.status`, `discrepancies`, `reverseCoverage` |
@@ -209,9 +209,9 @@ Work plans use the header line `Implementation Readiness: <status>`.
 
 Use this procedure after work-plan approval and before autonomous task execution when the flow needs to verify implementation readiness.
 
-1. Load the approved work plan exact path and extract Verification Strategies, Quality Assurance Mechanisms, Design-to-Plan Traceability, UI Spec Component -> Task Mapping, Connection Map, test skeleton references, E2E absence reasons, phase structure, referenced Design Docs, and UI Specs.
+1. Load the approved work plan exact path and extract Verification Strategies, Quality Assurance Mechanisms, Design-to-Plan Traceability, ADR Bindings, UI Spec Component -> Task Mapping, Connection Map, test skeleton references, E2E absence reasons, phase structure, referenced Design Docs, ADRs, and UI Specs.
 2. Evaluate these criteria with evidence:
-   - R1 Verification Strategy references resolve
+   - R1 Verification Strategy and ADR Binding references resolve
    - R2 E2E prerequisites are addressed
    - R3 Phase 1 observability exists
    - R4 UI rendering surface exists when UI work is present

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/task-decomposer.toml

@@ -66,6 +66,7 @@ Decompose tasks based on implementation strategy patterns determined in implemen
    - Create individual task files in `docs/plans/tasks/`
    - Document concrete executable procedures
    - Include task-level Quality Assurance Mechanisms when the work plan defines them
+   - Include task-level Binding Decisions when ADR Bindings cover the task
    - **Always include operation verification methods**
    - Define clear completion criteria (within executor's scope of responsibility)
 
@@ -92,6 +93,7 @@ Decompose tasks based on implementation strategy patterns determined in implemen
    - Extract task list
    - Identify dependencies
    - Read Design-to-Plan Traceability rows and verify every `covered` item has a corresponding generated task or phase completion task
+   - Read ADR Bindings rows and verify every `covered` item has a corresponding generated task
    - **Overall Optimization Considerations**
      - Identify common processing (prevent redundant implementation)
      - Pre-map impact scope
@@ -136,6 +138,7 @@ Decompose tasks based on implementation strategy patterns determined in implemen
    | fixture-e2e environment/setup work | Existing fixture data, API mock layer, browser harness configuration |
    | service-integration-e2e environment/setup work | Current environment config, startup scripts, seed scripts, auth flow references, external service stubs |
    | Cross-boundary implementation | Connection Map rows touching the task target files, caller/producer module, callee/consumer module, expected signal, contract definition |
+   | Task constrained by an ADR | ADR file with section hint matching the ADR Bindings row's Source Section value |
    | Bug fix/refactor | Affected code paths, failing tests, reproduction-related files |
    | Behavior replacement/rewrite | Existing implementation being replaced, observable outputs, Verification Strategy section in the Design Doc |
 
@@ -146,6 +149,7 @@ Decompose tasks based on implementation strategy patterns determined in implemen
    - When test skeletons exist, include them explicitly
    - When the work plan contains a UI Spec Component -> Task Mapping table, propagate matching component sections to every task listed in the row
    - When the work plan contains a Connection Map, propagate boundary rows touching the task's target files to every task on either side of the boundary
+   - When the work plan contains an ADR Bindings table, propagate matching binding rows to every covered task
    - When a task matches multiple natures, include Investigation Targets from all matching rows and deduplicate overlaps
 
 7. **Implementation Pattern Consistency**
@@ -191,6 +195,26 @@ When the work plan includes a `Design-to-Plan Traceability` section:
 5. **Verification integrity**: For `verification` rows, ensure the corresponding task file includes the required comparison or verification method in Operation Verification Methods.
 6. **Prerequisite integrity**: For `prerequisite` rows, place setup, migration, seed, auth, or environment work before dependent implementation tasks.
 
+## ADR Binding Propagation
+
+When the work plan includes an `ADR Bindings` section:
+
+1. **Coverage preservation**: For each row marked `covered`, locate every task ID listed in `Covered By Task(s)`.
+2. **Gap handling**: Preserve each `gap` row as a planning issue and surface it to the caller when task generation would otherwise assume the ADR decision is implemented.
+3. **Investigation Targets**: Add the ADR file path with the row's Source Section as a section hint to each matched task, formatted as `docs/adr/ADR-XXXX-title.md (§ [Source Section])`.
+4. **Binding Decisions table**: Add one row to each matched task's `Binding Decisions` section:
+   - `Source`: ADR path with section hint
+   - `Axis`: value copied verbatim from the plan row
+   - `Decision`: binding decision copied from the plan row
+   - `Compliance Check`: a Y/N-answerable positive predicate that evaluates whether the planned and final implementation satisfy the decision
+5. **Predicate shape**: Write each Compliance Check as a concrete positive statement. Examples by Axis:
+   - `placement`: `Auth entrypoint is in src/middleware/**`
+   - `dependency_direction`: `Domain code imports only from src/domain/** and src/shared/**`
+   - `contract_schema`: `API responses match the ResponseEnvelope<T> schema`
+   - `data_flow`: `Session tokens are written through the Redis client`
+   - `persistence`: `User records are persisted through the UsersRepository interface`
+6. **Validation**: Treat missing Axis, unknown Axis value, or non-checkable Compliance Check as an incomplete task file. Non-checkable means the implementation cannot be observed and answered as `Y` or `N`, or the predicate is written as a negative or compound condition.
+
 ## UI Spec Propagation
 
 When the work plan includes a `UI Spec Component -> Task Mapping` section:
@@ -310,6 +334,10 @@ Please execute decomposed tasks according to the order.
 - [ ] Appropriate granularity (1-5 files/task)
 - [ ] Investigation Targets specified for every task
 - [ ] Quality Assurance Mechanisms propagated to relevant tasks when present in the plan header
+- [ ] ADR Bindings rows propagated to relevant tasks when present in the work plan
+  - [ ] ADR source includes section hint
+  - [ ] Axis copied verbatim from the work plan row
+  - [ ] Compliance Check is a Y/N-answerable positive predicate
 - [ ] Operation Verification Methods specified for every task
 - [ ] Clear completion criteria setting
 - [ ] Overall design document creation

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

@@ -176,6 +176,22 @@ When the task file, Dependencies, or Investigation Targets reference `docs/proje
 3. **Cross-check against Investigation Notes**: Ensure planned implementation is consistent with the observations recorded in the task file
 4. **Execute determination**: Determine continue/escalation per "Mandatory Judgment Criteria" above
 
+#### 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.
+
+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.
+   - `### Binding Decisions Evaluation`
+   - `[axis] planned: [one sentence planned approach]`
+   - `[source] [Compliance Check] -> Y|N|Unknown — [one-line rationale]`
+3. Record the planned implementation approach in Investigation Notes, one sentence per distinct `Axis` value present in the Binding Decisions table. Group rows that share an Axis value when one sentence covers the group.
+4. Evaluate each row's Compliance Check against the planned approach. Record the result as `Y`, `N`, or `Unknown` with a one-line rationale.
+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.
+
 #### Reference Representativeness (Applied During Implementation)
 
 When adopting a pattern, UI composition, or dependency from existing code, apply repository-wide representativeness checks at the point of adoption:
@@ -218,7 +234,7 @@ For research tasks, includes creating deliverable files specified in metadata "P
 ### 5. Return JSON Result
 Return one of the following as the final response (see Structured Response Specification for schemas):
 - `status: "completed"` — task fully implemented
-- `status: "escalation_needed"` — design deviation or similar component discovered
+- `status: "escalation_needed"` — a structured escalation case from the schemas below applies
 
 ## Structured Response Specification
 
@@ -260,6 +276,8 @@ Report in the following JSON format upon task completion (**without executing qu
 #### 2-1. Design Doc Deviation Escalation
 When unable to implement per Design Doc, escalate in following JSON format:
 
+Use Binding Decision Violation Escalation instead when the task has a Binding Decisions row covering the same issue.
+
 ```json
 {
   "status": "escalation_needed",
@@ -366,6 +384,36 @@ When repository-wide verification is insufficient to determine the appropriate d
 }
 ```
 
+#### 2-5. Binding Decision Violation Escalation
+When one or more Compliance Checks in the task's Binding Decisions section evaluate to `N` during pre-implementation, or to `N` or `Unknown` during completion, escalate in following JSON format:
+
+```json
+{
+  "status": "escalation_needed",
+  "reason": "Binding decision violation",
+  "taskName": "[Task name being executed]",
+  "escalation_type": "binding_decision_violation",
+  "phase": "pre_implementation | completion_gate",
+  "implementationApproach": "[1-2 sentence summary of the planned or final implementation approach]",
+  "failures": [
+    {
+      "source": "[ADR file path with section hint, copied from Source column]",
+      "axis": "[Axis value copied from the Axis column]",
+      "decision": "[Decision text copied from Decision column]",
+      "complianceCheck": "[Compliance Check predicate copied from Compliance Check column]",
+      "evaluation": "N | Unknown",
+      "rationale": "[One line explaining why the implementation does not satisfy the check, or why it cannot be evaluated]"
+    }
+  ],
+  "user_decision_required": true,
+  "suggested_options": [
+    "Adjust the implementation plan to satisfy the binding decision",
+    "Update the ADR, then update the work plan ADR Bindings and task Binding Decisions",
+    "Provide additional context that resolves the Unknown evaluation"
+  ]
+}
+```
+
 ## Scope Boundary (delegate to orchestrator)
 - Overall quality checks → handled by quality-fixer-frontend
 - Commit creation → handled by orchestrator after quality checks
@@ -378,11 +426,12 @@ When repository-wide verification is insufficient to determine the appropriate d
 ☐ Investigation Targets were processed, or marked N/A when the task file has no Investigation Targets section
 ☐ 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)
 ☐ 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`
 
-**ENFORCEMENT**: HALT if any gate unchecked. Return `status: "escalation_needed"` to caller.
+**ENFORCEMENT**: HALT if any gate unchecked. Return `status: "escalation_needed"` to caller. Use `escalation_type: "binding_decision_violation"` with `phase: "completion_gate"` when the unchecked item is a Binding Decisions Compliance Check. Use `escalation_type: "design_compliance_violation"` for other completion gate failures.
 
 """
 

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

@@ -176,6 +176,22 @@ When the task file, Dependencies, or Investigation Targets reference `docs/proje
 3. **Cross-check against Investigation Notes**: Ensure planned implementation is consistent with the observations recorded in the task file
 4. **Execute determination**: Determine continue/escalation per "Mandatory Judgment Criteria" above
 
+#### 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.
+
+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.
+   - `### Binding Decisions Evaluation`
+   - `[axis] planned: [one sentence planned approach]`
+   - `[source] [Compliance Check] -> Y|N|Unknown — [one-line rationale]`
+3. Record the planned implementation approach in Investigation Notes, one sentence per distinct `Axis` value present in the Binding Decisions table. Group rows that share an Axis value when one sentence covers the group.
+4. Evaluate each row's Compliance Check against the planned approach. Record the result as `Y`, `N`, or `Unknown` with a one-line rationale.
+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.
+
 #### Reference Representativeness (Applied During Implementation)
 
 When adopting a pattern, API usage, or dependency from existing code, apply repository-wide representativeness checks at the point of adoption:
@@ -221,7 +237,7 @@ For research tasks, includes creating deliverable files specified in metadata "P
 ### 5. Return JSON Result
 Return one of the following as the final response (see Structured Response Specification for schemas):
 - `status: "completed"` — task fully implemented
-- `status: "escalation_needed"` — design deviation or similar function discovered
+- `status: "escalation_needed"` — a structured escalation case from the schemas below applies
 
 ## Structured Response Specification
 
@@ -263,6 +279,8 @@ Report in the following JSON format upon task completion (**without executing qu
 #### 2-1. Design Doc Deviation Escalation
 When unable to implement per Design Doc, escalate in following JSON format:
 
+Use Binding Decision Violation Escalation instead when the task has a Binding Decisions row covering the same issue.
+
 ```json
 {
   "status": "escalation_needed",
@@ -369,6 +387,36 @@ When repository-wide verification is insufficient to determine the appropriate d
 }
 ```
 
+#### 2-5. Binding Decision Violation Escalation
+When one or more Compliance Checks in the task's Binding Decisions section evaluate to `N` during pre-implementation, or to `N` or `Unknown` during completion, escalate in following JSON format:
+
+```json
+{
+  "status": "escalation_needed",
+  "reason": "Binding decision violation",
+  "taskName": "[Task name being executed]",
+  "escalation_type": "binding_decision_violation",
+  "phase": "pre_implementation | completion_gate",
+  "implementationApproach": "[1-2 sentence summary of the planned or final implementation approach]",
+  "failures": [
+    {
+      "source": "[ADR file path with section hint, copied from Source column]",
+      "axis": "[Axis value copied from the Axis column]",
+      "decision": "[Decision text copied from Decision column]",
+      "complianceCheck": "[Compliance Check predicate copied from Compliance Check column]",
+      "evaluation": "N | Unknown",
+      "rationale": "[One line explaining why the implementation does not satisfy the check, or why it cannot be evaluated]"
+    }
+  ],
+  "user_decision_required": true,
+  "suggested_options": [
+    "Adjust the implementation plan to satisfy the binding decision",
+    "Update the ADR, then update the work plan ADR Bindings and task Binding Decisions",
+    "Provide additional context that resolves the Unknown evaluation"
+  ]
+}
+```
+
 ## Execution Principles
 - Follow RED-GREEN-REFACTOR (see the principles in testing skill)
 - Update progress checkboxes per step
@@ -381,11 +429,12 @@ When repository-wide verification is insufficient to determine the appropriate d
 ☐ Investigation Targets were processed, or marked N/A when the task file has no Investigation Targets section
 ☐ 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)
 ☐ 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`
 
-**ENFORCEMENT**: HALT if any gate unchecked. Return `status: "escalation_needed"` to caller.
+**ENFORCEMENT**: HALT if any gate unchecked. Return `status: "escalation_needed"` to caller. Use `escalation_type: "binding_decision_violation"` with `phase: "completion_gate"` when the unchecked item is a Binding Decisions Compliance Check. Use `escalation_type: "design_compliance_violation"` for other completion gate failures.
 
 """
 

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/.codex/agents/work-planner.toml

@@ -44,7 +44,8 @@ Skill Status:
 6. Concretize risks and countermeasures
 7. Create explicit Design-to-Plan Traceability so Design Doc technical requirements are covered without silent omission
 8. Propagate UI Spec component and runtime boundary context into the plan so task decomposition can pass it to executors
-9. Document in progress-trackable format
+9. Map implementation-binding ADR decisions to constrained tasks
+10. Document in progress-trackable format
 
 ## Input Parameters
 
@@ -68,10 +69,16 @@ Read the Design Doc(s), UI Spec, PRD, and ADR (if provided). Extract:
 - Verification Strategy from each Design Doc: correctness definition, target comparison, verification method, observable success indicator, normalized verification timing, and early verification point
 - Quality Assurance Mechanisms from each Design Doc: all items marked `adopted`, including mechanism name, enforced quality aspect, configuration path, and covered files or project-wide scope
 - Implementation-relevant technical requirements from each Design Doc section using the category values defined in the plan template's `Design-to-Plan Traceability` section
+- Prerequisite ADR references from each Design Doc and implementation-binding decisions from each resolved ADR
 
 Focus on implementation-relevant items only: items that directly inform task creation, dependency ordering, verification design, or protected no-change boundaries.
 Extract `scope-boundary` rows from explicit non-target statements such as `No Ripple Effect`, compatibility constraints, or protected boundaries that must remain unchanged.
 
+For ADR references, resolve paths using these rules:
+- Explicit `docs/adr/ADR-XXXX-title.md` path: read that file directly
+- Short `docs/adr/ADR-XXXX.md` or `ADR-XXXX` reference: match `docs/adr/ADR-XXXX-*.md`
+- Zero matches or two or more matches: flag a planning gap requiring user confirmation before plan approval
+
 ### 2. Process Test Design Information (when provided)
 Read test skeleton files and extract meta information (see Test Design Information Processing section).
 
@@ -141,6 +148,29 @@ Map only boundaries satisfying all three qualifications above: separate runtime,
 
 For each boundary, record the caller/producer, callee/consumer, expected signal, and covering tasks in the `Connection Map` table.
 
+### 5c. Map ADR Decisions to Tasks
+
+When ADRs are provided as input or listed in a Design Doc's "Prerequisite ADRs" section, create an `ADR Bindings` table before finalizing tasks.
+
+For each resolved ADR:
+1. Extract decisions from sections such as `Decision`, `Implementation Guidance`, `Consequences`, or clearly labeled decision bullets.
+2. Select only implementation-binding decisions: constraints on code placement, dependency direction, contract/schema shape, data flow, or persistence.
+3. Classify each selected decision with exactly one Axis value:
+   - `placement`: constrains where code, modules, components, or responsibilities belong
+   - `dependency_direction`: constrains allowed import, call, ownership, or layering direction
+   - `contract_schema`: constrains interface, payload, schema, props, DTO, event, or persisted record shape
+   - `data_flow`: constrains how data moves, transforms, is passed, emitted, or observed
+   - `persistence`: constrains storage location, repository boundary, migration, cache, or durable state behavior
+   - When multiple Axis values apply, prefer the ADR's explicit subject. If the subject remains ambiguous, use this priority order: `persistence` > `contract_schema` > `dependency_direction` > `data_flow` > `placement`.
+4. Map each binding decision to the task IDs that implement or verify the constrained area.
+5. Record one row per binding decision in the plan template's `ADR Bindings` table.
+
+Mapping rules:
+- A binding decision can map to multiple tasks when the constrained implementation spans boundaries.
+- A task can be covered by multiple binding decisions.
+- Acceptance criteria and required user-visible behaviors belong in `Design-to-Plan Traceability`; `ADR Bindings` covers structural implementation constraints.
+- If an ADR decision constrains the design but no task covers it, add a justified gap and flag it for user confirmation before plan approval.
+
 ### 6. Define Tasks with Completion Criteria
 For each task, derive completion criteria from Design Doc acceptance criteria. Apply the 3-element completion definition (Implementation Complete, Quality Complete, Integration Complete).
 
@@ -333,6 +363,10 @@ When creating work plans, **Phase Structure Diagrams** and **Task Dependency Dia
   - [ ] Scope-boundary items mapped explicitly when the Design Doc defines protected no-change areas
   - [ ] Covered By Task(s) uses only normalized task IDs
   - [ ] No unjustified `gap` entries remain
+- [ ] ADR Bindings table completed when ADRs are provided or listed in Design Doc prerequisites
+  - [ ] ADR references resolved with exact path or single `docs/adr/ADR-XXXX-*.md` match
+  - [ ] Each binding row has one valid Axis value
+  - [ ] Each binding row maps to covering task(s) or a justified gap
 - [ ] Phase structure matches the implementation approach
 - [ ] Early verification point placed in the earliest applicable phase
 - [ ] Normalized verification timing mapped consistently to phases

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-workflows",
-  "version": "0.6.2",
+  "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",