codex-workflows 0.5.0 → 0.6.0

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

@@ -189,6 +189,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 +214,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
@@ -288,6 +306,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**:
@@ -402,3 +421,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.toml

@@ -45,6 +45,15 @@ Representative triggers:
 
 ## Mandatory Process Before Design Doc Creation
 
+### External Resources Integration
+
+When external resources are recorded for the project:
+
+1. Read `docs/project-context/external-resources.md`
+2. Read the target Design Doc's `External Resources Used` section in update mode
+3. Fill the Design Doc `External Resources Used` subsection with project resource labels and feature-specific identifiers for API, backend, data, or infrastructure sources
+4. Keep project-level access methods in the project context file
+
 ### Standards Identification Gate【Required】
 Must be performed before any investigation:
 
@@ -441,3 +450,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