codex-workflows 0.5.0 → 0.6.0

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

@@ -33,6 +33,14 @@ unknowns:
 - [ADR File Name]: [Related decision items]
 - Reference common technical ADRs when applicable
 
+### External Resources Used
+
+| Project Resource Label | Feature Identifier | Purpose |
+|------------------------|--------------------|---------|
+| frontend-design-origin | [screen / node / frame / route / story id] | [why this feature uses it] |
+| api-schema-source | [endpoint / operation id / schema name] | [why this feature uses it] |
+| infra-iac-source | [service / module / environment] | [why this feature uses it] |
+
 ### Agreement Checklist
 
 #### Scope

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

@@ -119,7 +119,7 @@ Use when implementation approach is Vertical Slice. Each phase represents one va
 #### Tasks
 - [ ] [P1-T1] Specific work content
 - [ ] [P1-T2] Verification for this value unit
-- [ ] Quality check: Implement staged quality checks (refer to ai-development-guide skill)
+- [ ] Quality check: Run staged static analysis, build verification, tests, and final quality gate
 
 #### Phase Completion Criteria
 - [ ] Early verification point passed
@@ -151,7 +151,7 @@ Use when implementation approach is Horizontal Slice. Phases follow Foundation -
 #### Tasks
 - [ ] [P1-T1] Specific work content
 - [ ] [P1-T2] Specific work content
-- [ ] Quality check: Implement staged quality checks (refer to ai-development-guide skill)
+- [ ] Quality check: Run staged static analysis, build verification, tests, and final quality gate
 - [ ] Unit tests: All related tests pass
 
 #### Phase Completion Criteria
@@ -201,7 +201,7 @@ This phase is required for all implementation approaches.
 - [ ] Document updates
 
 ### Quality Assurance
-- [ ] Implement staged quality checks (details: refer to ai-development-guide skill)
+- [ ] Run staged static analysis, build verification, tests, and final quality gate
 - [ ] All tests pass
 - [ ] Static check pass
 - [ ] Lint check pass

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

@@ -46,7 +46,7 @@ Brief observations recorded after reading Investigation Targets:
 - **Verification method**: [What to verify and how]
 - **Success criteria**: [Observable outcome that proves correctness]
 - **Failure response**: [What to do if verification fails]
-- **Verification level**: [L1/L2/L3, per implementation-approach skill]
+- **Verification level**: [L1 unit/local verification, L2 integration verification, or L3 end-to-end verification]
 
 ## Completion Criteria
 - [ ] All added tests pass

package/.agents/skills/documentation-criteria/references/ui-spec-template.md

@@ -13,6 +13,14 @@
 |--------|------|---------|
 | Prototype code | [docs/ui-spec/assets/xxx/] | [commit SHA / tag] |
 
+## External Resources Used
+
+| Project Resource Label | Feature Identifier | Purpose |
+|------------------------|--------------------|---------|
+| [frontend-design-origin] | [screen / node / frame / route / story id] | [why this feature uses it] |
+| [frontend-design-system] | [component / token / variant / story id] | [why this feature uses it] |
+| [frontend-visual-verification] | [route / story / viewport / scenario] | [how this feature is verified] |
+
 ## Prototype Management
 
 Prototype code is an **attachment** to this UI Spec. The canonical specification is always this document + the Design Doc.

package/.agents/skills/external-resource-context/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: external-resource-context
+description: "Discovers, confirms, and records external resource access methods for project design and implementation work, including design sources, design systems, API schemas, database schemas, IaC sources, secret stores, environment config, and verification environments. Use when external resource context needs to be discovered or refreshed, recorded in docs/project-context/external-resources.md, or referenced from a Design Doc/UI Spec."
+---
+
+# External Resource Context
+
+## Purpose
+
+This skill helps Codex discover required external resources, record stable access methods, and reuse recorded context during design, planning, implementation, and review work.
+
+Covered resources include design origin, design system, guidelines, visual verification environment, database schema source, migration history, secret store location, API schema source, mock environment, IaC source, and environment configuration.
+
+## Scope Boundaries
+
+**In scope**: hearing protocol for unclear external resources, storage location, single-source ownership rule, and lookup protocol for known resources.
+
+**Freshness handling**: record access methods and feature identifiers here. The consuming workflow checks current resource content at use time.
+
+## Storage Locations
+
+| Tier | Location | Holds | Update Frequency |
+|------|----------|-------|------------------|
+| Project | `docs/project-context/external-resources.md` | Environment-stable facts: resource labels, presence, and access methods | When the project environment changes |
+| Feature | `## External Resources Used` section in the relevant UI Spec or Design Doc | Feature-specific identifiers that reference project-tier labels | Per feature |
+
+### Single Source Rule
+
+The project tier owns environment facts such as URLs, MCP server names, file paths, commands, and secret-store locations. Feature-tier sections list feature-specific identifiers such as design node ids, API paths, schema names, or IaC module names, then reference the project-tier label.
+
+## Hearing Protocol
+
+### When to Hear
+
+| Condition | Action |
+|-----------|--------|
+| `docs/project-context/external-resources.md` is absent | Run full hearing for the relevant domain |
+| File exists | Ask for one choice: keep current axes, refresh all axes, or refresh selected axes |
+
+When the user chooses `refresh selected axes`, ask for the exact domain and axis labels before updating. Confirm the selected labels against the loaded domain reference, then hear only those axes.
+
+### Domain Routing
+
+Load the domain reference matching the current task:
+
+| Task type | References to load |
+|-----------|--------------------|
+| Frontend UI work | [references/frontend.md](references/frontend.md) |
+| Backend or data work | [references/backend.md](references/backend.md) |
+| API contract work | [references/api.md](references/api.md) |
+| Infrastructure or deployment | [references/infra.md](references/infra.md) |
+| Fullstack | Load each relevant domain reference |
+
+Each domain reference defines axes and question templates. Use `N/A` for axes outside the current project.
+
+### Two-Phase Hearing
+
+1. **Structured hearing**: ask each axis from the domain reference. For each non-N/A axis, collect the access or reference method: MCP server name, URL, file path, command, repository-owned source, project convention, manual confirmation path, or existing implementation.
+2. **Self-declaration**: ask for additional external resources outside the structured axes. Append any resources the user provides under `Additional Resources`.
+
+## Storage Protocol
+
+After hearing completes:
+
+1. Build project-tier content from the answers using [references/template.md](references/template.md).
+2. Write `docs/project-context/external-resources.md`, creating `docs/project-context/` as needed.
+3. When a target UI Spec or Design Doc exists, update its `External Resources Used` section with project-tier labels plus feature-specific identifiers.
+4. If a write fails, return the error with the intended path and leave completion status unresolved.
+5. Report touched file paths to the calling workflow.
+
+## Lookup Protocol
+
+Consumers resolve external context in this order:
+
+1. Read `docs/project-context/external-resources.md`.
+2. Read the target UI Spec or Design Doc `External Resources Used` section for feature-specific identifiers.
+3. Use the project-tier access method to fetch or inspect the resource.
+
+Codex custom agents inherit parent `mcp_servers` when the agent file omits `mcp_servers`. Preserve that inheritance for agents that may need project-specific MCP tools. Reserve MCP `enabled_tools` for a deliberately narrow server-level allow list.
+
+## Output Format
+
+The project-tier file follows [references/template.md](references/template.md). Feature-tier sections use the fixed heading `External Resources Used`; heading level follows the parent document structure.
+
+## Quality Checklist
+
+- [ ] Each relevant axis has a presence indicator and access method, or is marked `N/A`
+- [ ] Self-declaration phase completed
+- [ ] Project-tier file contains environment facts
+- [ ] Feature-tier sections contain feature identifiers and project-tier labels
+- [ ] Existing project-tier updates are confirmed before writes
+
+## References
+
+- [references/frontend.md](references/frontend.md)
+- [references/backend.md](references/backend.md)
+- [references/api.md](references/api.md)
+- [references/infra.md](references/infra.md)
+- [references/template.md](references/template.md)

package/.agents/skills/external-resource-context/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "external-resource-context"
+  short_description: "Discover and reuse external resource context"
+  default_prompt: "Use $external-resource-context to identify or consult external resources for: "
+
+policy:
+  allow_implicit_invocation: true

package/.agents/skills/external-resource-context/references/api.md

@@ -0,0 +1,20 @@
+# API External Resource Axes
+
+Use these axes when work depends on API contracts outside the repository.
+
+| Axis | Purpose | Presence Choices | Access Method Examples |
+|------|---------|------------------|------------------------|
+| API Schema Source | OpenAPI, GraphQL SDL, proto, or typed contract source | Present / Repository-owned / N/A | schema repo path, docs URL, MCP |
+| API Explorer | Interactive or generated contract inspection | Present / N/A | Swagger UI URL, GraphQL explorer URL |
+| Mock Server | Contract-backed mock or sandbox endpoint | Present / N/A | mock URL, command, docker compose service |
+| Consumer Contract Source | Downstream expectations or contract tests | Present / N/A | contract repo, pact broker URL, file path |
+
+## Question Template
+
+Ask each axis in positive form:
+
+1. "Which API contract resources are available for this work?"
+2. "For each applicable resource, what access method or reference method should Codex use?"
+3. "Which feature-specific identifier applies, such as endpoint path, operation id, schema name, or event name?"
+
+Record `N/A` for axes outside the project.

package/.agents/skills/external-resource-context/references/backend.md

@@ -0,0 +1,21 @@
+# Backend External Resource Axes
+
+Use these axes when backend or data work depends on resources outside the repository.
+
+| Axis | Purpose | Presence Choices | Access Method Examples |
+|------|---------|------------------|------------------------|
+| Database Schema Source | Canonical schema, ERD, or generated model source | Present / Repository-owned / N/A | schema repo path, DB docs URL, MCP |
+| Migration History | Deployment-applied migration sequence | Present / Repository-owned / N/A | migration repo, migration table query command |
+| Secret Store | Runtime secret names and lookup location | Present / N/A | cloud secret manager path, vault path |
+| Environment Configuration | Runtime config source and environment matrix | Present / Repository-owned / N/A | config repo, deployment docs, command |
+| Mock or Fixture Environment | Local or shared backend verification setup | Present / N/A | docker compose path, seeded DB command, service URL |
+
+## Question Template
+
+Ask each axis in positive form:
+
+1. "Which backend external resources are available for this work?"
+2. "For each applicable resource, what access method or reference method should Codex use?"
+3. "Which feature-specific identifier applies, such as table name, service name, secret name, or environment name?"
+
+Record `N/A` for axes outside the project.

package/.agents/skills/external-resource-context/references/frontend.md

@@ -0,0 +1,21 @@
+# Frontend External Resource Axes
+
+Use these axes when frontend UI work depends on resources outside the repository.
+
+| Axis | Purpose | Presence Choices | Access Method Examples |
+|------|---------|------------------|------------------------|
+| Design Origin | Canonical visual or interaction source | Present / Existing implementation / N/A | Figma MCP, public URL, exported file path |
+| Design System | Component catalog, tokens, variants, usage rules | Present / Existing package only / N/A | Storybook URL, package docs, MCP, local docs |
+| Guidelines | Accessibility, responsive, copy, brand, i18n, or platform rules | Present / Project conventions only / N/A | URL, file path, wiki export |
+| Visual Verification Environment | Rendered UI inspection path | Present / Manual confirmation / N/A | browser MCP, Playwright command, Storybook URL, dev server URL |
+| Generated UI Artifacts | Generated CSS typings, route typings, message catalogs, snapshots | Present / N/A | generator command, config path |
+
+## Question Template
+
+Ask each axis in positive form:
+
+1. "Which frontend external resources are available for this work?"
+2. "For each applicable resource, what access method or reference method should Codex use?"
+3. "Which feature-specific identifier applies, such as screen name, node id, route, story id, or component name?"
+
+Record `N/A` for axes outside the project.

package/.agents/skills/external-resource-context/references/infra.md

@@ -0,0 +1,21 @@
+# Infrastructure External Resource Axes
+
+Use these axes when infrastructure, deployment, or runtime environment work depends on resources outside the repository.
+
+| Axis | Purpose | Presence Choices | Access Method Examples |
+|------|---------|------------------|------------------------|
+| IaC Source | Terraform, Pulumi, CDK, or deployment source | Present / Repository-owned / N/A | repo path, module registry, docs URL |
+| Environment Inventory | Accounts, regions, clusters, services | Present / N/A | cloud console URL, inventory file, command |
+| Deployment Pipeline | CI/CD workflow and promotion process | Present / Repository-owned / N/A | pipeline URL, workflow file path |
+| Observability Source | Logs, metrics, traces, dashboards | Present / N/A | dashboard URL, MCP, CLI command |
+| Runtime Access Method | How to inspect deployed state | Present / N/A | kubectl context, cloud CLI profile, bastion docs |
+
+## Question Template
+
+Ask each axis in positive form:
+
+1. "Which infrastructure external resources are available for this work?"
+2. "For each applicable resource, what access method or reference method should Codex use?"
+3. "Which feature-specific identifier applies, such as module name, service name, environment, account, or dashboard?"
+
+Record `N/A` for axes outside the project.

package/.agents/skills/external-resource-context/references/template.md

@@ -0,0 +1,72 @@
+# Project External Resources Template
+
+Use this structure for `docs/project-context/external-resources.md`.
+
+```markdown
+# External Resources
+
+## Overview
+
+This file records project-level access methods for resources outside the repository. Feature documents reference these labels and add feature-specific identifiers.
+
+## Frontend
+
+| Label | Axis | Status | Access Method | Owner / Notes |
+|-------|------|--------|---------------|---------------|
+| frontend-design-origin | Design Origin | present / existing-implementation / N/A | MCP / URL / file path / command | [owner or notes] |
+| frontend-design-system | Design System | present / existing-package / N/A | MCP / URL / file path / command | [owner or notes] |
+| frontend-guidelines | Guidelines | present / project-conventions / N/A | URL / file path | [owner or notes] |
+| frontend-visual-verification | Visual Verification Environment | present / manual-confirmation / N/A | MCP / URL / command | [owner or notes] |
+| frontend-generated-artifacts | Generated UI Artifacts | present / N/A | command / config path | [owner or notes] |
+
+## Backend
+
+| Label | Axis | Status | Access Method | Owner / Notes |
+|-------|------|--------|---------------|---------------|
+| backend-schema-source | Database Schema Source | present / repository-owned / N/A | URL / file path / command | [owner or notes] |
+| backend-migration-history | Migration History | present / repository-owned / N/A | URL / file path / command | [owner or notes] |
+| backend-secret-store | Secret Store | present / N/A | store path / docs path | [owner or notes] |
+| backend-environment-config | Environment Configuration | present / repository-owned / N/A | URL / file path / command | [owner or notes] |
+| backend-mock-environment | Mock or Fixture Environment | present / N/A | URL / command | [owner or notes] |
+
+## API
+
+| Label | Axis | Status | Access Method | Owner / Notes |
+|-------|------|--------|---------------|---------------|
+| api-schema-source | API Schema Source | present / repository-owned / N/A | URL / file path / MCP | [owner or notes] |
+| api-explorer | API Explorer | present / N/A | URL / MCP | [owner or notes] |
+| api-mock-server | Mock Server | present / N/A | URL / command | [owner or notes] |
+| api-consumer-contract | Consumer Contract Source | present / N/A | URL / file path | [owner or notes] |
+
+## Infrastructure
+
+| Label | Axis | Status | Access Method | Owner / Notes |
+|-------|------|--------|---------------|---------------|
+| infra-iac-source | IaC Source | present / repository-owned / N/A | URL / file path | [owner or notes] |
+| infra-environment-inventory | Environment Inventory | present / N/A | URL / file path / command | [owner or notes] |
+| infra-deployment-pipeline | Deployment Pipeline | present / repository-owned / N/A | URL / file path | [owner or notes] |
+| infra-observability-source | Observability Source | present / N/A | URL / MCP / command | [owner or notes] |
+| infra-runtime-access | Runtime Access Method | present / N/A | command / docs path | [owner or notes] |
+
+## Additional Resources
+
+| Label | Description | Access Method | Owner / Notes |
+|-------|-------------|---------------|---------------|
+| [label] | [description] | [URL / MCP / file path / command] | [owner or notes] |
+
+## Update History
+
+| Date | Change | Author |
+|------|--------|--------|
+| YYYY-MM-DD | Initial capture | [name] |
+```
+
+Feature-tier sections use this compact table:
+
+```markdown
+## External Resources Used
+
+| Project Resource Label | Feature Identifier | Purpose |
+|------------------------|--------------------|---------|
+| frontend-design-origin | [screen / node / frame id] | [why this feature uses it] |
+```

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

@@ -0,0 +1,113 @@
+---
+name: recipe-front-adjust
+description: "Adjust an implemented UI with external resource context, focused write-set confirmation, verification, and quality checks."
+---
+
+**Context**: UI adjustment for implemented frontend features. The parent session owns the edit and verification loop; subagents handle bounded fact gathering, planning, and quality checks.
+
+## Required Skills [LOAD BEFORE EXECUTION]
+
+1. [LOAD IF NOT ACTIVE] `documentation-criteria` -- scale and planning criteria
+2. [LOAD IF NOT ACTIVE] `external-resource-context` -- external resource hearing and lookup
+3. [LOAD IF NOT ACTIVE] `subagents-orchestration-guide` -- agent coordination rules
+
+**Spawn rule**: every `spawn_agent` call MUST pass `fork_turns="none"` or `fork_context=false` for context isolation.
+
+## Execution Pattern
+
+**Core Identity**: "I am a guided executor. I run the UI adjustment and verification loop in the parent session."
+
+**Execution Protocol**:
+1. Delegate bounded one-shot work to `ui-analyzer`, `work-planner`, and `quality-fixer-frontend`.
+2. Run user dialogue, write-set confirmation, edits, and verification in the parent session.
+3. Respect every `[STOP]` marker before moving to the next phase.
+
+Adjustment request: $ARGUMENTS
+
+## Execution Flow
+
+### Step 1: External Resource Hearing
+
+Run the frontend domain hearing protocol from `external-resource-context`.
+
+### Step 2: UI Fact Gathering
+
+Spawn `ui-analyzer`:
+
+`requirement_analysis: { affectedFiles: [files inferred from request], purpose: "UI adjustment", technicalConsiderations: [] }. requirements: [adjustment request]. target_paths: [paths named or inferred from request]. target_components: [components named in request]. ui_spec_path: [path if available]. Read docs/project-context/external-resources.md, resolve relevant UI sources through declared access methods, analyze existing UI code, and populate candidateWriteSet[].`
+
+### Step 3: Confirm Write Set and Scale
+
+1. Present `candidateWriteSet[]` to the user.
+2. Ask the user to confirm high-confidence entries, confirm all entries, or provide an edited file list.
+3. Apply documentation-criteria Creation Decision Matrix to the confirmed write set:
+   - `0 files`: ask the user for the component or path that owns the change, then pause this recipe.
+   - `1-2 files`: proceed with direct adjustment.
+   - `3-5 files`: create a focused work plan.
+   - `6+ files` or ADR conditions: route to the frontend design flow.
+
+### Step 4: Plan Creation When Needed
+
+For `3-5 files`, spawn `work-planner`:
+
+`Create a focused UI adjustment plan. Adjustment request: [verbatim]. ui_analysis: [ui-analyzer JSON]. External resources: docs/project-context/external-resources.md. Confirmed write set: [files]. Each phase should be implementable as 1-3 commits. Include visual verification, accessibility, i18n parity, and generated artifact checks when relevant. Output path: docs/plans/[YYYYMMDD]-adjust-[short-description].md.`
+
+**[STOP]** Present the plan and wait for approval.
+
+For `1-2 files`, present a concise adjustment context:
+- request
+- confirmed write set
+- relevant `focusAreas[]`
+- relevant external resource summaries and access methods
+
+**[STOP]** Wait for user confirmation that the context covers the work.
+
+### Step 5: Adjustment and Verification
+
+For each adjustment unit:
+1. Plan the edit from `focusAreas[]`, confirmed write set, and relevant external resource summaries.
+2. Apply the edit in the parent session.
+3. Verify against declared access methods:
+   - design origin: compare implementation target to the recorded design source
+   - visual verification: use the recorded browser, test runner, Storybook, dev server, or manual confirmation path
+   - design system: confirm tokens, variants, and usage rules through the recorded source
+4. Refine until the implemented UI matches the design source or the user-confirmed adjustment target.
+
+### Step 6: Quality Verification
+
+Spawn `quality-fixer-frontend` for each unit:
+
+- Direct adjustment: pass `filesModified: [edited files]`
+- Planned adjustment: pass `task_file: [work plan path]` and `filesModified: [edited files]`
+
+Route `quality-fixer-frontend` results:
+- `approved`: proceed to commit
+- `stub_detected`: complete the implementation gap and rerun quality verification
+- `blocked`: surface missing prerequisites or unclear specification points to the user
+
+### Step 7: Commit
+
+Commit each approved adjustment unit with affected files and relevant generated artifacts.
+
+## Completion Criteria
+
+- [ ] External resource hearing completed or update explicitly skipped
+- [ ] `ui-analyzer` returned JSON with external resource status and `candidateWriteSet`
+- [ ] User confirmed write set before scale judgment
+- [ ] Scale judgment completed with matching branch
+- [ ] Direct context or work plan approved
+- [ ] Adjustment units edited and verified through declared resource paths
+- [ ] Each unit passed `quality-fixer-frontend`
+- [ ] Each approved unit committed
+
+## Output Example
+
+```
+Frontend adjustment completed.
+- External resources: docs/project-context/external-resources.md (updated|unchanged)
+- UI analysis: [N] components, [M] focus areas
+- Scale: 1-2 files | 3-5 files
+- Work plan: path | N/A
+- Adjustment units committed: [count]
+- Quality status: approved
+```

package/.agents/skills/recipe-front-adjust/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "recipe-front-adjust"
+  short_description: "Implemented UI adjustment flow"
+  default_prompt: "Use $recipe-front-adjust to adjust an implemented UI: "
+
+policy:
+  allow_implicit_invocation: false

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

@@ -10,6 +10,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
 
 **Spawn rule**: every `spawn_agent` call MUST pass `fork_turns="none"` or `fork_context=false` for context isolation.
 
@@ -19,7 +20,7 @@ description: "Execute from requirement analysis to frontend design document crea
 
 **Execution Method**:
 - Requirement analysis -> performed by requirement-analyzer
-- Codebase analysis -> performed by codebase-analyzer
+- Codebase analysis -> performed by codebase-analyzer and ui-analyzer
 - UI Specification creation -> performed by ui-spec-designer
 - Design document creation -> performed by technical-designer-frontend
 - Design verification -> performed by code-verifier
@@ -31,6 +32,8 @@ Orchestrator spawns agents and passes structured data between them.
 
 **Included in this skill**:
 - Requirement analysis with requirement-analyzer
+- External resource hearing with external-resource-context
+- UI fact gathering with ui-analyzer alongside codebase-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
@@ -54,26 +57,41 @@ Once requirements are moderately clarified:
 **[STOP -- BLOCKING]** Review requirement analysis results and address question items.
 **CANNOT proceed until user explicitly confirms the requirement analysis.**
 
-### Step 2: UI Specification Phase
-After requirement analysis approval, ask the user about prototype code:
+### Step 2: External Resource Hearing
+After requirement analysis approval, 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
+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."
 
 **[STOP -- BLOCKING]** Wait for user response about prototype code availability.
 **CANNOT proceed until user responds.**
 
-Then create the UI Specification:
-- Spawn ui-spec-designer agent: "Create UI Spec [from PRD at [path] if PRD exists]. [Prototype code is at [user-provided path]. Place prototype in docs/ui-spec/assets/{feature-name}/ | No prototype code available.]"
+### Step 4: UI Fact Gathering Phase
+After prototype inquiry completes, use the prototype path as an input when one was provided.
+
+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 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 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 3: Design Document Creation Phase
+### 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 codebase-analyzer agent first: "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."
-- For Design Doc: Spawn technical-designer-frontend agent: "Create Design Doc based on requirements. Codebase Analysis: [JSON from codebase-analyzer]. UI Spec is at [ui-spec path]. Inherit component structure and state design from UI Spec."
+- 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]"
 
@@ -85,8 +103,9 @@ 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
-- [ ] Codebase analysis completed before frontend Design Doc creation
 - [ ] Design document created and approved
 - [ ] All document reviews passed
 

package/.agents/skills/recipe-fullstack-implement/SKILL.md

@@ -13,6 +13,7 @@ description: "Orchestrate full-cycle implementation across backend and frontend
 4. [LOAD IF NOT ACTIVE] `documentation-criteria` -- document quality standards
 5. [LOAD IF NOT ACTIVE] `implementation-approach` -- implementation methodology
 6. [LOAD IF NOT ACTIVE] `subagents-orchestration-guide` -- agent coordination and workflow flows
+7. [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.
 
@@ -29,7 +30,7 @@ ENFORCEMENT: Proceeding without reading monorepo-flow.md invalidates the entire
 ## Execution Protocol
 
 1. **Spawn agents for all work** -- your role is to invoke sub-agents, pass data between them, and report results
-2. **Follow monorepo-flow.md** for the design phase (multiple Design Docs, design-sync, vertical slicing)
+2. **Follow monorepo-flow.md** for the design phase (external resource hearing at design entry, multiple Design Docs, design-sync, vertical slicing)
 3. **Follow subagents-orchestration-guide skill** for all other orchestration rules (stop points, structured responses, escalation)
 4. **Enter autonomous mode** only after "batch approval for entire implementation phase"
 
@@ -59,6 +60,7 @@ When continuing existing flow, verify:
 ### 3. Execute monorepo-flow.md
 
 **Follow monorepo-flow.md step-by-step** for the complete flow from UI Spec through Design Docs through Work Plan. The flow includes:
+- External resource hearing at the design phase entry
 - UI Spec creation (with prototype inquiry)
 - Separate Design Docs per layer (technical-designer for backend, technical-designer-frontend for frontend)
 - **Backend Design Doc**: Spawn technical-designer agent
@@ -89,6 +91,7 @@ When user responds to questions:
 **Pre-execution Checklist (MANDATORY)**:
 - [ ] Read monorepo-flow.md reference
 - [ ] Confirmed relevant flow steps
+- [ ] External resource hearing included when entering design flow
 - [ ] Identified current progress position
 - [ ] Clarified next step
 - [ ] Recognized stopping points

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

@@ -74,6 +74,7 @@ The following subagents are available:
 13. **code-verifier**: Document-code consistency verification for review inputs and post-implementation verification
 14. **design-sync**: Design Doc consistency verification across multiple documents
 15. **acceptance-test-generator**: Generate integration and E2E test skeletons from Design Doc ACs
+16. **ui-analyzer**: UI fact gathering from external resources and existing frontend code before UI Spec, Design Doc, or adjustment work
 
 ## Orchestration Principles
 
@@ -183,6 +184,7 @@ Subagents respond in JSON format. The final response from each JSON-returning su
 |-------|--------------------------------------|
 | `requirement-analyzer` | `scale`, `confidence`, `affectedLayers`, `adrRequired`, `scopeDependencies`, `questions` |
 | `codebase-analyzer` | `focusAreas`, `dataModel`, `qualityAssurance`, `dataTransformationPipelines`, `limitations` |
+| `ui-analyzer` | `externalResources`, `componentStructure`, `propsPatterns`, `cssLayout`, `stateDisplay`, `focusAreas`, `candidateWriteSet`, `limitations` |
 | `task-executor*` | `status`, `escalation_type`, `filesModified`, `requiresTestReview` |
 | `quality-fixer*` | `status`, `reason`, `stubFindings`, `blockingIssues`, `missingPrerequisites` |
 | `document-reviewer` | `verdict.decision`, `verdict.conditions` |