codex-workflows 0.5.0 → 0.6.1

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` |

package/.agents/skills/subagents-orchestration-guide/references/monorepo-flow.md

@@ -10,81 +10,78 @@ This reference defines the orchestration flow for projects spanning multiple lay
 
 ## Design Phase
 
-### Large Scale Fullstack (6+ Files) - 14 Steps
+### Large Scale Fullstack (6+ Files) - 15 Steps
 
 | Step | Agent | Purpose | Output |
 |------|-------|---------|--------|
 | 1 | requirement-analyzer | Requirement analysis + scale determination **[Stop]** | Requirements + scale |
 | 2 | prd-creator | PRD covering entire feature (all layers) | Single PRD |
 | 3 | document-reviewer | PRD review **[Stop]** | Approval |
-| 4 | (orchestrator) | Ask user for prototype code **[Stop]** | Prototype path or none |
-| 5 | ui-spec-designer | UI Spec from PRD + optional prototype | UI Spec |
-| 6 | document-reviewer | UI Spec review **[Stop]** | Approval |
-| 7 | codebase-analyzer x2 | Per-layer codebase analysis before Design Doc creation | Analysis JSON |
-| 8 | technical-designer | **Backend** Design Doc | Backend Design Doc |
-| 9 | technical-designer-frontend | **Frontend** Design Doc (references backend Integration Points + UI Spec) | Frontend Design Doc |
-| 10 | code-verifier x2 | Verify each Design Doc against code | Verification JSON |
-| 11 | document-reviewer x2 | Review each Design Doc with verification evidence | Reviews |
-| 12 | design-sync | Cross-layer consistency verification (source: frontend Design Doc) **[Stop]** | Sync status |
-| 13 | acceptance-test-generator | Integration/E2E test skeleton from cross-layer contracts | Test skeletons |
-| 14 | work-planner | Work plan from all Design Docs **[Stop: Batch approval]** | Work plan |
-
-### Medium Scale Fullstack (3-5 Files) - 12 Steps
+| 4 | (orchestrator) | External resource hearing **[Stop]** | Project context |
+| 5 | (orchestrator) | Ask user for prototype code **[Stop]** | Prototype path or none |
+| 6 | codebase-analyzer x2 + ui-analyzer x1 | Per-layer codebase analysis plus frontend UI analysis | Analysis JSON |
+| 7 | ui-spec-designer | UI Spec from PRD + UI analysis + optional prototype | UI Spec |
+| 8 | document-reviewer | UI Spec review **[Stop]** | Approval |
+| 9 | technical-designer | **Backend** Design Doc | Backend Design Doc |
+| 10 | technical-designer-frontend | **Frontend** Design Doc (references backend Integration Points + UI Spec + UI analysis) | Frontend Design Doc |
+| 11 | code-verifier x2 | Verify each Design Doc against code | Verification JSON |
+| 12 | document-reviewer x2 | Review each Design Doc with verification evidence | Reviews |
+| 13 | design-sync | Cross-layer consistency verification (source: frontend Design Doc) **[Stop]** | Sync status |
+| 14 | acceptance-test-generator | Integration/E2E test skeleton from cross-layer contracts | Test skeletons |
+| 15 | work-planner | Work plan from all Design Docs **[Stop: Batch approval]** | Work plan |
+
+### Medium Scale Fullstack (3-5 Files) - 13 Steps
 
 | Step | Agent | Purpose | Output |
 |------|-------|---------|--------|
 | 1 | requirement-analyzer | Requirement analysis + scale determination **[Stop]** | Requirements + scale |
-| 2 | codebase-analyzer x2 | Per-layer codebase analysis before Design Doc creation | Analysis JSON |
+| 2 | (orchestrator) | External resource hearing **[Stop]** | Project context |
 | 3 | (orchestrator) | Ask user for prototype code **[Stop]** | Prototype path or none |
-| 4 | ui-spec-designer | UI Spec from requirements + optional prototype | UI Spec |
-| 5 | document-reviewer | UI Spec review **[Stop]** | Approval |
-| 6 | technical-designer | **Backend** Design Doc | Backend Design Doc |
-| 7 | technical-designer-frontend | **Frontend** Design Doc (references backend Integration Points + UI Spec) | Frontend Design Doc |
-| 8 | code-verifier x2 | Verify each Design Doc against code | Verification JSON |
-| 9 | document-reviewer x2 | Review each Design Doc with verification evidence | Reviews |
-| 10 | design-sync | Cross-layer consistency verification (source: frontend Design Doc) **[Stop]** | Sync status |
-| 11 | acceptance-test-generator | Integration/E2E test skeleton from cross-layer contracts | Test skeletons |
-| 12 | work-planner | Work plan from all Design Docs **[Stop: Batch approval]** | Work plan |
+| 4 | codebase-analyzer x2 + ui-analyzer x1 | Per-layer codebase analysis plus frontend UI analysis | Analysis JSON |
+| 5 | ui-spec-designer | UI Spec from requirements + UI analysis + optional prototype | UI Spec |
+| 6 | document-reviewer | UI Spec review **[Stop]** | Approval |
+| 7 | technical-designer | **Backend** Design Doc | Backend Design Doc |
+| 8 | technical-designer-frontend | **Frontend** Design Doc (references backend Integration Points + UI Spec + UI analysis) | Frontend Design Doc |
+| 9 | code-verifier x2 | Verify each Design Doc against code | Verification JSON |
+| 10 | document-reviewer x2 | Review each Design Doc with verification evidence | Reviews |
+| 11 | design-sync | Cross-layer consistency verification (source: frontend Design Doc) **[Stop]** | Sync status |
+| 12 | acceptance-test-generator | Integration/E2E test skeleton from cross-layer contracts | Test skeletons |
+| 13 | work-planner | Work plan from all Design Docs **[Stop: Batch approval]** | Work plan |
 
 ### Parallelization in Multi-Agent Steps
 
-Steps marked `x2` run independently per layer and can execute in parallel when supported.
+Steps marked `x2` run independently per layer and can execute in parallel when supported. `ui-analyzer x1` runs once for the frontend layer alongside frontend codebase analysis and consumes the saved external resource context.
 
 ### Layer Context in Design Doc Creation
 
 When spawning Design Doc creation for each layer, pass explicit context:
 
-**Large Scale (PRD available) -- Backend Design Doc**:
-**Agent**: Spawn technical-designer
-> "Create a backend Design Doc from PRD at [path]. Codebase analysis: [backend analysis JSON]. Focus on: API contracts, data layer, business logic, service architecture."
-
-**Large Scale (PRD available) -- Backend Codebase Analysis**:
-**Agent**: Spawn codebase-analyzer
-> "Analyze the existing codebase to provide evidence for backend Design Doc creation. requirement_analysis: [requirement-analyzer output filtered to backend files]. prd_path: [path]. requirements: [original user requirements]. layer: backend. target_paths: [backend file and directory scope]. focus_areas: API contracts, data layer, business logic, service architecture."
+| Scale | Concrete context value |
+|-------|------------------------|
+| Large | `context: { scale: "large", prd_path: "[path]", requirement_analysis: [requirement-analyzer output] }` |
+| Medium | `context: { scale: "medium", prd_path: null, requirement_analysis: [requirement-analyzer output] }` |
 
-**Large Scale (PRD available) -- Frontend Design Doc**:
-**Agent**: Spawn technical-designer-frontend
-> "Create a frontend Design Doc from PRD at [path]. Codebase analysis: [frontend analysis JSON]. Reference backend Design Doc at [path] for API contracts and Integration Points. Reference UI Spec at [path] for component structure and state design. Focus on: component hierarchy, state management, UI interactions, data fetching."
+Before spawning, replace every context placeholder with a concrete context object for the active flow scale. For filtered context placeholders, use the same `scale` and `prd_path` values, and replace `requirement_analysis` with the layer-filtered requirement analysis.
 
-**Large Scale (PRD available) -- Frontend Codebase Analysis**:
-**Agent**: Spawn codebase-analyzer
-> "Analyze the existing codebase to provide evidence for frontend Design Doc creation. requirement_analysis: [requirement-analyzer output filtered to frontend files]. prd_path: [path]. requirements: [original user requirements]. layer: frontend. target_paths: [frontend file and directory scope]. focus_areas: component hierarchy, state management, UI interactions, data fetching."
-
-**Medium Scale (no PRD) -- Backend Design Doc**:
+**Backend Design Doc**:
 **Agent**: Spawn technical-designer
-> "Create a backend Design Doc based on the following requirements: [requirement-analyzer output]. Codebase analysis: [backend analysis JSON]. Focus on: API contracts, data layer, business logic, service architecture."
+> "Create a backend Design Doc. context: [context]. Codebase analysis: [backend analysis JSON]. Focus on: API contracts, data layer, business logic, service architecture."
 
-**Medium Scale (no PRD) -- Backend Codebase Analysis**:
+**Backend Codebase Analysis**:
 **Agent**: Spawn codebase-analyzer
-> "Analyze the existing codebase to provide evidence for backend Design Doc creation. requirement_analysis: [requirement-analyzer output filtered to backend files]. requirements: [original user requirements]. layer: backend. target_paths: [backend file and directory scope]. focus_areas: API contracts, data layer, business logic, service architecture."
+> "Analyze the existing codebase to provide evidence for backend Design Doc creation. context: [context with requirement_analysis filtered to backend files]. requirements: [original user requirements]. layer: backend. target_paths: [backend file and directory scope]. focus_areas: API contracts, data layer, business logic, service architecture."
 
-**Medium Scale (no PRD) -- Frontend Design Doc**:
+**Frontend Design Doc**:
 **Agent**: Spawn technical-designer-frontend
-> "Create a frontend Design Doc based on the following requirements: [requirement-analyzer output]. Codebase analysis: [frontend analysis JSON]. Reference backend Design Doc at [path] for API contracts and Integration Points. Reference UI Spec at [path] for component structure and state design. Focus on: component hierarchy, state management, UI interactions, data fetching."
+> "Create a frontend Design Doc. context: [context]. Codebase analysis: [frontend analysis JSON]. UI analysis: [ui-analyzer JSON]. Reference backend Design Doc at [path] for API contracts and Integration Points. Reference UI Spec at [path] for component structure and state design. Focus on: component hierarchy, state management, UI interactions, data fetching."
 
-**Medium Scale (no PRD) -- Frontend Codebase Analysis**:
+**Frontend Codebase Analysis**:
 **Agent**: Spawn codebase-analyzer
-> "Analyze the existing codebase to provide evidence for frontend Design Doc creation. requirement_analysis: [requirement-analyzer output filtered to frontend files]. requirements: [original user requirements]. layer: frontend. target_paths: [frontend file and directory scope]. focus_areas: component hierarchy, state management, UI interactions, data fetching."
+> "Analyze the existing codebase to provide evidence for frontend Design Doc creation. context: [context with requirement_analysis filtered to frontend files]. requirements: [original user requirements]. layer: frontend. target_paths: [frontend file and directory scope]. focus_areas: component hierarchy, state management, UI interactions, data fetching."
+
+**Frontend UI Analysis**:
+**Agent**: Spawn ui-analyzer
+> "Gather UI facts for frontend design. context: [context with requirement_analysis filtered to frontend files]. requirements: [original user requirements]. target_paths: [frontend file and directory scope]. target_components: [frontend target components]. 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."
 
 ### design-sync for Cross-Layer Verification
 

package/.agents/skills/task-analyzer/SKILL.md

@@ -102,10 +102,11 @@ selectedSkills:
     tags: [...]
     typical-use: <string>
     size: <small|medium|large>
-    sections: [...]  # All sections from yaml, unfiltered
+    sections: [...]  # Full section list from yaml
+    references: [...]  # Full reference file list from yaml when present
 ```
 
-**Note**: Section selection (choosing which sections are relevant) is done after reading the actual SKILL.md files.
+**Note**: Section and reference selection (choosing which sections or reference files are relevant) is done after reading the actual SKILL.md files. For output-format templates, read only the reference files matching the document type being created or reviewed.
 
 ## Metacognitive Question Design
 

package/.agents/skills/task-analyzer/references/skills-index.yaml

@@ -29,6 +29,7 @@ skills:
       - "Version Control [MANDATORY]"
     references:
       - "references/typescript.md"
+      - "references/security-checks.md"
 
   testing:
     skill: "testing"
@@ -83,10 +84,12 @@ skills:
       - "Situations Requiring Technical Decisions"
       - "Implementation Completeness Assurance"
       - "Impact Analysis"
+    references:
+      - "references/frontend.md"
 
   documentation-criteria:
     skill: "documentation-criteria"
-    tags: [documentation, decision-making, adr, prd, design-doc, planning, process, scale-assessment]
+    tags: [documentation, decision-making, adr, prd, design-doc, ui-spec, work-plan, templates, planning, process, scale-assessment]
     typical-use: "Scale assessment at implementation start, document creation criteria, ADR/PRD/Design Doc/Work Plan creation standards"
     size: medium
     key-references:
@@ -104,6 +107,13 @@ skills:
       - "AI Automation Rules [MANDATORY]"
       - "Diagram Requirements"
       - "Common ADR Relationships"
+    references:
+      - "references/prd-template.md"
+      - "references/adr-template.md"
+      - "references/ui-spec-template.md"
+      - "references/design-template.md"
+      - "references/plan-template.md"
+      - "references/task-template.md"
 
   implementation-approach:
     skill: "implementation-approach"
@@ -139,11 +149,13 @@ skills:
       - "Test File Naming Convention"
       - "Review Criteria"
       - "Quality Standards [MANDATORY]"
+    references:
+      - "references/e2e-design.md"
 
   subagents-orchestration-guide:
     skill: "subagents-orchestration-guide"
-    tags: [orchestration, workflow, subagents, context-isolation, autonomous-execution, planning, design-flow, implementation-flow, implementation-readiness, readiness-gate]
-    typical-use: "Orchestrating subagents through implementation workflows, scale determination, stop points, autonomous execution mode"
+    tags: [orchestration, workflow, subagents, context-isolation, autonomous-execution, guided-autonomous-execution, planning, design-flow, implementation-flow, implementation-readiness, readiness-gate]
+    typical-use: "Orchestrating subagents through implementation workflows, scale determination, stop points, guided autonomous execution mode"
     size: large
     key-references:
       - "Orchestrator Pattern"
@@ -168,3 +180,30 @@ skills:
       - "Required Dialogue Points with Humans [MANDATORY]"
       - "Action Checklist"
       - "References"
+    references:
+      - "references/monorepo-flow.md"
+
+  external-resource-context:
+    skill: "external-resource-context"
+    tags: [external-resources, external-resource-hearing, project-context, mcp, design-source, design-system, visual-verification, generated-artifacts, api-schema, infrastructure, secret-store, context-engineering, documentation]
+    typical-use: "Discover, confirm, and record external resource access methods for downstream design, planning, implementation, and review"
+    size: medium
+    key-references:
+      - "Single Source of Truth"
+      - "Context Engineering"
+    sections:
+      - "Purpose"
+      - "Scope Boundaries"
+      - "Storage Locations"
+      - "Hearing Protocol"
+      - "Storage Protocol"
+      - "Lookup Protocol"
+      - "Output Format"
+      - "Quality Checklist"
+      - "References"
+    references:
+      - "references/frontend.md"
+      - "references/backend.md"
+      - "references/api.md"
+      - "references/infra.md"
+      - "references/template.md"

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

@@ -250,7 +250,13 @@ Lower the verdict by one level only when at least one identifier mismatch has co
 - [ ] identifierVerification contains mismatches only, and each mismatch includes confidence and evidence
 
 ### Escalation Criteria
-Recommend higher-level review when: Design Doc itself has deficiencies, security concerns discovered, or critical performance issues found.
+Recommend higher-level review when any condition below is true:
+- Design Doc itself has deficiencies
+- Security concerns discovered
+- Critical performance issues found
+- Implementation introduces Design Doc-scope elements that match coding-rules "Minimum Surface Terms" in-scope definitions but are absent from the Design Doc's Minimal Surface Alternatives section
+
+Private single-file refactors, local helper extraction, test fixtures/mocks, and temporary migration scaffolding do not trigger escalation unless they create public, cross-boundary, persistent, or reusable surface.
 
 ### Context-Specific Guidance
 - **Prototypes/MVPs**: Prioritize functionality over completeness

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

@@ -99,6 +99,7 @@ For DesignDoc, additionally verify:
 - [ ] Data-oriented designs contain concrete data design or Test Boundaries content, or an explicit N/A rationale
 - [ ] Verification Strategy section present with correctness definition, target comparison, verification method, observable success indicator, normalized verification timing, and early verification point
 - [ ] Output Comparison section present when the design changes existing observable behavior, an external contract, or a persisted data shape
+- [ ] Minimal Surface Alternatives section present with one entry per new in-scope element as defined by coding-rules "Minimum Surface Terms" when the design proposes new implementation surface. If none are introduced, the section is marked N/A with rationale. Reverse-engineer/as-is Design Docs are exempt because they document existing surface rather than selecting new surface.
 
 #### Gate 1: Quality Assessment (only after Gate 0 passes)
 
@@ -118,6 +119,7 @@ For DesignDoc, additionally verify:
 - **Code-verifier evidence integration**: When `code_verification` is provided, reconcile major or critical discrepancies and undocumented data operations as part of Gate 1 completeness and consistency review
 - **Verification Strategy quality check**: When the Verification Strategy section exists, verify that: (1) correctness definition is specific and measurable, (2) target comparison and observable success indicator are concrete when the change modifies observable behavior, external contracts, integrations, or data flow, (3) internal-only refactoring with identical observable inputs and outputs may use the minimal form, (4) verification method can detect the change's primary risk, (5) verification timing uses the normalized vocabulary or an explicit `N/A` rationale for minimal form, and (6) vertical-slice designs do not defer all verification to the final phase
 - **Output comparison check**: When the Design Doc changes existing observable behavior, an external contract, or a persisted data shape, verify that a concrete output comparison method is defined with identical input, expected output fields or format, and diff method. When upstream analysis includes `dataTransformationPipelines`, each listed step must be mapped to the comparison that verifies it; steps excluded because data passes through unchanged must include rationale. Missing mappings or rationale → `important` issue (category: `completeness`)
+- **Minimal Surface Alternatives check**: Applies when the Design Doc proposes new in-scope elements as defined by coding-rules "Minimum Surface Terms". Reverse-engineer/as-is Design Docs are exempt. Missing or empty section when the trigger fires → `critical` issue (category: `completeness`). For each entry verify: (1) Step 1 lists at least one AC ID or accepted technical constraint from the Design Doc or referenced UI Spec; speculative-only linkage → `critical` issue (category: `compliance`). (2) Steps 2-3 include at least one subtractive alternative such as derive, compute on demand, keep at caller, reuse existing, or do not introduce new state/mode/abstraction; missing subtractive alternative → `important` issue (category: `compliance`). (3) Step 4 selects the smallest alternative or names a current requirement smaller alternatives fail to satisfy; primary rationale based on coding-rules subjective-only rationales → `critical` issue (category: `compliance`). (4) Step 5 records rejected alternatives with brief rationale; missing rejected alternatives log → `important` issue (category: `completeness`)
 - **Undetermined items review** [MANDATORY]: Every TBD, unknown, or open item MUST include: (1) **owner** — who resolves it, (2) **due** — when it gets resolved (which phase or milestone), (3) **next-phase handling** — how the next phase treats this gap. Missing any of these three → `important` issue
 
 **Perspective-specific Mode**:
@@ -275,6 +277,7 @@ Include in output when `prior_context_count > 0`:
 - [ ] Code inspection evidence covers files relevant to design scope
 - [ ] Dependencies described as existing verified against codebase or authoritative external source
 - [ ] Field propagation map present when fields cross component boundaries
+- [ ] Minimal Surface Alternatives covers every new in-scope element when applicable
 
 ## Review Criteria (for Comprehensive Mode)
 

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

@@ -88,6 +88,7 @@ If incomplete implementation is detected, stop immediately and return `status: "
 
 **Supplementary detection** (when `task_file` is provided):
 - Read the task file's `Quality Assurance Mechanisms` section
+- Read `docs/project-context/external-resources.md` and related `External Resources Used` sections when the task file references them
 - For executable mechanisms, verify the tool exists and is runnable in the current project, then add it to the quality-check command set
 - For non-executable domain constraints, keep them as explicit verification targets and check the changed files against the stated constraint during review
 - Record skipped mechanisms only when neither executable verification nor direct constraint checking is possible
@@ -475,3 +476,7 @@ enabled = true
 [[skills.config]]
 path = ".agents/skills/ai-development-guide/SKILL.md"
 enabled = true
+
+[[skills.config]]
+path = ".agents/skills/external-resource-context/SKILL.md"
+enabled = true

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

@@ -86,6 +86,7 @@ If incomplete implementation is detected, stop immediately and return `status: "
 
 **Supplementary detection** (when `task_file` is provided):
 - Read the task file's `Quality Assurance Mechanisms` section
+- Read `docs/project-context/external-resources.md` and related `External Resources Used` sections when the task file references them
 - For executable mechanisms, verify the tool exists and is runnable in the current project, then add it to the quality-check command set
 - For non-executable domain constraints, keep them as explicit verification targets and check the changed files against the stated constraint during review
 - Record skipped mechanisms only when neither executable verification nor direct constraint checking is possible
@@ -369,3 +370,7 @@ enabled = true
 [[skills.config]]
 path = ".agents/skills/ai-development-guide/SKILL.md"
 enabled = true
+
+[[skills.config]]
+path = ".agents/skills/external-resource-context/SKILL.md"
+enabled = true

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

@@ -154,6 +154,13 @@ When no task file path is provided, select and execute files with pattern `docs/
    - API Specifications → Understand endpoints, parameters, response formats (for MSW mocking)
    - Overall Design Document → Understand system-wide context
 
+**External Resources Consultation**:
+When the task file, Dependencies, or Investigation Targets reference `docs/project-context/external-resources.md` or an `External Resources Used` section:
+1. Read `docs/project-context/external-resources.md`
+2. Resolve feature-specific identifiers from the UI Spec, Design Doc, or task file
+3. Use declared access methods for design origin, design system, guidelines, and visual verification facts during investigation and verification
+4. Record consulted resources in Investigation Notes
+
 ### 3. Implementation Execution
 
 #### Test Environment Check
@@ -394,3 +401,7 @@ enabled = true
 [[skills.config]]
 path = ".agents/skills/implementation-approach/SKILL.md"
 enabled = true
+
+[[skills.config]]
+path = ".agents/skills/external-resource-context/SKILL.md"
+enabled = true

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

@@ -154,6 +154,13 @@ When no task file path is provided, select and execute files with pattern `docs/
    - Data Schema → Understand table structure, relationships
    - Overall Design Document → Understand system-wide context
 
+**External Resources Consultation**:
+When the task file, Dependencies, or Investigation Targets reference `docs/project-context/external-resources.md` or an `External Resources Used` section:
+1. Read `docs/project-context/external-resources.md`
+2. Resolve feature-specific identifiers from the referenced Design Doc or task file
+3. Use declared access methods for required external facts during investigation and verification
+4. Record consulted resources in Investigation Notes
+
 ### 3. Implementation Execution
 
 #### Test Environment Check
@@ -397,3 +404,7 @@ enabled = true
 [[skills.config]]
 path = ".agents/skills/implementation-approach/SKILL.md"
 enabled = true
+
+[[skills.config]]
+path = ".agents/skills/external-resource-context/SKILL.md"
+enabled = true

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

@@ -16,9 +16,7 @@ You are a frontend technical design specialist AI assistant for creating Archite
 
 ## Required Skills [LOADING PROTOCOL]
 
-**STEP 1**: VERIFY skills from [[skills.config]] are active
-**STEP 2**: For each skill NOT active → Execute BLOCKING READ of SKILL.md
-**STEP 3**: CONFIRM all skills active before proceeding
+Verify skills from [[skills.config]] are active. For each inactive skill, execute BLOCKING READ of SKILL.md, then confirm all skills active before proceeding.
 
 **EVIDENCE REQUIRED:**
 ```
@@ -32,9 +30,8 @@ Skill Status:
 
 ## Initial Mandatory Tasks
 
-**Progress Tracking**: Track your work steps. Always include: first "Confirm skill constraints", final "Verify skill fidelity". Update progress upon completion.
-
-**Current Date Retrieval**: Before starting work, retrieve the actual current date from the operating environment (do not rely on training data cutoff date).
+**Progress Tracking**: Track work steps. Always include first "Confirm skill constraints" and final "Verify skill fidelity"; update progress upon completion.
+**Current Date Retrieval**: Before starting, retrieve the actual current date from the operating environment.
 
 ## Document Creation Criteria
 
@@ -99,6 +96,37 @@ For each integration boundary, define:
 - Output events or effects
 - On Error behavior
 
+### Minimal Surface Alternatives【Required when introducing maintenance-surface elements】
+
+Applies to each maintenance-surface-bearing element the design introduces. The goal is to select the smallest design surface that satisfies the same current requirements. Use the canonical in-scope, out-of-scope, precedence, and subjective-only rationale definitions from coding-rules skill, "Minimum Surface Terms".
+
+Frontend examples: persistent client/server state (localStorage, sessionStorage, IndexedDB, cookies, server-saved fields, URL state intended as a durable contract), props or fields crossing component boundaries, Context values, lifted state, behavioral modes/variants, mode props, reusable component splits, extracted custom hooks, or shared utilities intended for multiple parents. Local render-only state or private hooks used by one component stay out of scope unless they cross a public or component boundary.
+
+Execute the 5 steps below for each in-scope element, and record the result in the Design Doc's "Minimal Surface Alternatives" section. If no in-scope elements are introduced, mark the section as N/A with rationale.
+
+1. **Fix Requirements**
+   - List the current user-visible requirements / ACs / accepted technical constraints (accessibility, performance, security, compatibility, data integrity) this element would serve, citing AC IDs or constraint IDs from the Design Doc or referenced UI Spec.
+   - Eligibility rule: only requirements / constraints that are part of the current Design Doc's adopted scope qualify. Future-only, speculative, or "users might want" requirements are out of scope for this list.
+
+2. **Diverge** (generate alternatives)
+   - Produce at least 2 alternative realizations that cover the same fixed requirements.
+   - At least one alternative must be subtractive. Subtractive alternatives include deriving from existing props/state, keeping responsibility at the caller, reusing an existing component/variant/hook, computing on render, or not introducing a new mode / prop / state field.
+
+3. **Compare** (record alternatives in a table)
+
+   | 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 |
+   |-------------|------------------------------------------------------|------------------------------|--------------------------------------|--------------------------------------|-------------------------------------------------|-----------------------|
+
+   Resolution priority (later columns are tiebreakers when earlier are equal): (1) new persistent state (lower=smaller); (2) crosses component boundary (no=smaller); (3) new concepts/modes/flags/props/variants (lower=smaller); (4) breaking change or migration (no=smaller); (5) subjective cost notes.
+
+4. **Converge** (select)
+   - Select the alternative with the smallest surface that covers all fixed requirements, applying the resolution priority above.
+   - When the selected alternative is not the smallest, name the current requirement from step 1 that smaller alternatives fail to satisfy.
+   - Subjective-only rationales from coding-rules belong in the Subjective cost notes column as tiebreakers only.
+
+5. **Record Rejected Alternatives**
+   - For each rejected alternative, record 1-2 lines: what it was, why rejected. Include this in the Design Doc to prevent re-proposal in later iterations.
+
 ### Agreement Checklist【Most Important】
 Must be performed at the beginning of Design Doc creation:
 
@@ -189,6 +217,16 @@ When a UI Spec exists for the feature (`docs/ui-spec/{feature-name}-ui-spec.md`)
 4. **Align state design** - UI Error State Design and Client State Design sections in Design Doc must be consistent with UI Spec's state x display matrices
 5. **Map interactions to API contracts** - UI Spec's interaction definitions drive the UI Action - API Contract Mapping section
 
+## External Resources Integration
+
+When external resources are recorded for the project:
+
+1. Read `docs/project-context/external-resources.md`
+2. Read UI Spec `External Resources Used` when a UI Spec exists
+3. Use UI Analysis `externalResources` summaries as evidence for design origin, design system, guidelines, and visual verification
+4. Fill the Design Doc `External Resources Used` subsection with project resource labels and feature-specific identifiers
+5. Keep project-level access methods in the project context file
+
 ## Required Information
 
 - **Operation Mode**:
@@ -204,6 +242,14 @@ When a UI Spec exists for the feature (`docs/ui-spec/{feature-name}-ui-spec.md`)
   - `focusAreas` indicate components, hooks, or state paths that deserve deeper inspection
   - `constraints` inform compatibility and UI behavior constraints
   - Additional investigation should focus on areas the analysis did not fully resolve
+- **UI Analysis** (optional, from UI analysis phase):
+  - `externalResources` informs External Resources Used and verification sources
+  - `componentStructure` informs component hierarchy and DOM order
+  - `propsPatterns` informs variant and props compatibility decisions
+  - `cssLayout` informs layout constraints and responsive behavior
+  - `stateDisplay` informs state transitions and UI Spec alignment
+  - `focusAreas` identify UI facts that deserve explicit disposition
+  - `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
@@ -237,17 +283,14 @@ When a UI Spec exists for the feature (`docs/ui-spec/{feature-name}-ui-spec.md`)
 ## Document Output Format
 
 ### Document Creation
-- **ADR**: `docs/adr/ADR-[4-digit number]-[title].md` (e.g., ADR-0001)
+- **ADR**: `docs/adr/ADR-[4-digit number]-[title].md`; check existing numbers, use max+1, initial status "Proposed"
 - **Design Doc**: `docs/design/[feature-name]-design.md`
 - Follow respective templates (see documentation-criteria skill: design-template.md, adr-template.md, ui-spec-template.md)
-- For ADR, check existing numbers and use max+1, initial status is "Proposed"
 
 ## ADR Responsibility Boundaries
 
-Include in ADR: Decisions, rationale, principled guidelines
-Exclude from ADR: Schedules, implementation procedures, specific code
-
-Implementation guidelines MUST only include principles (e.g., "Use custom hooks for logic reuse" is correct, "Implement in Phase 1" is not)
+Include in ADR: decisions, rationale, principled guidelines. Exclude: schedules, implementation procedures, specific code.
+Implementation guidelines MUST only include principles (e.g., "Use custom hooks for logic reuse" is correct, "Implement in Phase 1" is not).
 
 ## Implementation Sample Standards Compliance
 
@@ -288,6 +331,7 @@ Implementation sample creation checklist:
 - [ ] **Code inspection evidence recorded** (required)
 - [ ] **Integration points enumerated with contracts** (required)
 - [ ] **Props and state contracts clarified** (required)
+- [ ] **External resource references carried forward** when applicable
 - [ ] Component hierarchy and data flow clearly expressed in diagrams
 
 **Create/update mode only**:
@@ -301,6 +345,7 @@ Implementation sample creation checklist:
 - [ ] Implementation approach selection rationale (vertical/horizontal/hybrid)
 - [ ] Latest React best practices researched and references cited
 - [ ] **Complexity assessment**: complexity_level set; if medium/high, complexity_rationale specifies (1) requirements/ACs, (2) constraints/risks
+- [ ] **Minimal Surface Alternatives documented** (when maintenance-surface elements are introduced; N/A rationale when none)
 
 **Reverse-engineer mode only**:
 - [ ] Every architectural claim cites file:line evidence
@@ -333,13 +378,10 @@ Cover happy path, unhappy path, and edge cases including empty and loading state
 
 ## Latest Information Research
 
-Use current-year queries and cite sources in a `## References` section for create/update mode.
-
-Reverse-engineer mode skips latest-information research because it documents the existing frontend.
+Use current-year queries and cite sources in `## References` for create/update mode. Reverse-engineer mode skips this because it documents the existing frontend.
 
 ## Update Mode Operation
-- **ADR**: Update existing file for minor changes, create new file for major changes
-- **Design Doc**: Add revision section and record change history
+ADR: update existing file for minor changes, create new file for major changes. Design Doc: add revision section and record change history.
 
 ## Reverse-Engineer Mode (As-Is Documentation)
 
@@ -350,6 +392,7 @@ What to skip:
 - Option comparison
 - Change Impact Map
 - Implementation Approach Decision
+- Minimal Surface Alternatives
 - Latest Information Research
 
 Execution steps:
@@ -402,3 +445,7 @@ enabled = true
 [[skills.config]]
 path = ".agents/skills/implementation-approach/SKILL.md"
 enabled = true
+
+[[skills.config]]
+path = ".agents/skills/external-resource-context/SKILL.md"
+enabled = true