codex-workflows 0.5.0 → 0.6.1

package/.agents/skills/coding-rules/SKILL.md

@@ -14,11 +14,23 @@ For language-specific rules, also read:
 
 1. **Maintainability over Speed**: Prioritize long-term code health
 2. **Simplicity First**: YAGNI principle — simplest solution that meets requirements
-3. **Explicit over Implicit**: Clear intentions through code structure and naming
-4. **Delete over Comment**: Remove unused code instead of commenting it out
+3. **Minimum Surface for Required Coverage**: At a fixed coverage point, choose the smallest design surface that satisfies current user-visible requirements and accepted technical constraints. See "Minimum Surface Terms" below.
+4. **Explicit over Implicit**: Clear intentions through code structure and naming
+5. **Delete over Comment**: Remove unused code instead of commenting it out
 
 **ENFORCEMENT**: Every code change MUST align with these principles
 
+## Minimum Surface Terms [MANDATORY]
+
+Use these definitions whenever a design, review, or implementation instruction references "Minimum Surface for Required Coverage".
+
+- **Maintenance-surface-bearing elements**: persistent state; public-contract or cross-boundary fields/props; behavioral modes, flags, or variants; reusable abstractions; extracted services; shared utilities; component splits.
+- **Out of scope**: private local variables, internal helper functions with no external observers, test fixtures or mocks, temporary migration scaffolding removed before completion, and private implementation details confined to one function or file.
+- **Precedence rule**: When an element matches both in-scope and out-of-scope conditions, the in-scope classification wins.
+- **Selection rule**: Adopt a larger surface only by naming a current requirement or accepted technical constraint that smaller alternatives fail to cover. Value-based arguments are tiebreakers only.
+- **Subjective-only rationales**: "reusable", "useful", "future-ready", "convenient", "convenient for implementation", and "users might want".
+- **Relation to YAGNI**: YAGNI decides present vs. future need over time; Minimum Surface minimizes surface area for the current accepted scope.
+
 ## Code Quality [MANDATORY]
 
 - Refactor as you go — eliminate technical debt immediately

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
@@ -171,6 +179,8 @@ Use this table for runtime wiring, switching, or registration points. Record how
 
 ### Main Components
 
+Repeat the block below for each component.
+
 #### Component 1
 
 - **Responsibility**: [Scope of responsibility for this component]
@@ -188,6 +198,38 @@ Use this table for runtime wiring, switching, or registration points. Record how
 
 **Decision**: [reuse / extend / new] -- [rationale in 1-2 sentences]
 
+### Minimal Surface Alternatives (When Introducing Maintenance-Surface Elements)
+
+One entry per new in-scope element as defined by coding-rules "Minimum Surface Terms". Mark this section as N/A with brief rationale when the design introduces no in-scope elements.
+
+#### Element 1: [name of the new element]
+
+**Step 1 - Fixed Requirements**
+- [AC ID or constraint ID]: [requirement / constraint text]
+- [AC ID or constraint ID]: [requirement / constraint text]
+
+**Steps 2-3 - Alternatives Compared**
+
+| Alternative | Current requirements covered (AC or constraint IDs) | New state introduced (count) | New concept / mode / flag / prop / variant (count) | Crosses component boundary (yes/no) | Breaking change or migration required (yes/no) | Subjective cost notes |
+|-------------|------------------------------------------------------|------------------------------|------------------------------------|--------------------------------------|-------------------------------------------------|-----------------------|
+| [The added element as proposed] | | | | | | |
+| [Subtractive alternative: derive / compute on demand / keep at caller / reuse existing / do not introduce new state] | | | | | | |
+| [Optional third alternative] | | | | | | |
+
+**Step 4 - Selected Alternative and Rationale**
+- **Selected**: [alternative name]
+- **Rationale**:
+  - If selected = smallest alternative considered: state "smallest alternative considered; no further reduction available"
+  - If selected > smallest: name the current requirement(s) from step 1 that smaller alternatives fail to satisfy
+
+**Step 5 - Rejected Alternatives Log**
+- [Alternative name]: [1-2 lines on what it was and why rejected]
+- [Alternative name]: [1-2 lines on what it was and why rejected]
+
+(Repeat the Element block above for each additional in-scope element.)
+
+Rejected Alternatives Log is element-level. Future Extensibility below is design-level.
+
 ### Contract Definitions
 
 ```
@@ -347,9 +389,11 @@ Mark items as N/A with brief rationale when the feature has no relevant trust bo
 
 ## Future Extensibility
 
-- **Extension points**: [Interfaces, hooks, or plugin mechanisms designed for future use]
-- **Known future requirements**: [Planned features that influenced current design decisions]
-- **Intentional limitations**: [What was deliberately kept simple and why]
+This section records what was excluded from the current design surface. Speculative inclusions belong in a separate proposal.
+
+- **Deferred possibilities**: [Capabilities considered during design and explicitly excluded from the current design surface. Each entry names either the current requirement it would have served, or marks itself as speculative]
+- **Intentional limitations**: [What was deliberately kept small and why]
+- **Extension points (existing, with current consumers)**: [Interfaces or hooks already in use by named current consumers. Each entry names a current consumer]
 
 ## Alternative Solutions
 

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