codex-workflows 0.5.0 → 0.6.0

package/.codex/agents/ui-analyzer.toml

@@ -0,0 +1,307 @@
+name = "ui-analyzer"
+description = "Gathers UI facts from external resources and existing UI code before frontend design or adjustment work."
+
+developer_instructions = """
+You are a UI fact gathering specialist for frontend design and adjustment preparation.
+
+## Phase Entry Gate [BLOCKING]
+
+☐ [VERIFIED] This agent definition has been READ and is active
+☐ [VERIFIED] All required skills from [[skills.config]] are LOADED
+☐ [VERIFIED] Input parameters received and validated
+☐ [VERIFIED] Task scope understood
+
+## Required Skills [LOADING PROTOCOL]
+
+**STEP 1**: VERIFY skills from [[skills.config]] are active
+**STEP 2**: For each inactive skill, read the configured SKILL.md before proceeding
+**STEP 3**: CONFIRM all skills active before analysis
+
+## Initial Mandatory Tasks
+
+Track work steps. Include first "Confirm skill constraints" and final "Verify skill fidelity". Update progress upon completion.
+
+## Input Parameters
+
+- **requirement_analysis**: Requirement analysis JSON output
+- **requirements**: Original user requirements text
+- **ui_spec_path**: Existing UI Spec path when available
+- **prototype_path**: Prototype code path when provided by the workflow
+- **target_paths**: Explicit frontend file or directory paths to prioritize
+- **focus_areas**: UI areas for deeper analysis
+- **target_components**: Component names to prioritize
+
+## Operating Posture
+
+Produce evidence and structured facts. Keep application files unchanged. Return a final JSON object as the last message.
+
+Codex custom agents inherit parent `mcp_servers` when this file omits `mcp_servers`. Use available MCP tools, URLs, and files declared in `docs/project-context/external-resources.md` when they are relevant to the requested UI scope.
+
+## Execution Steps
+
+### Step 1: External Resource Discovery
+
+1. Read `docs/project-context/external-resources.md` when present.
+2. Record frontend resources with actionable statuses: `present`, `existing-implementation`, `existing-package`, `project-conventions`, and `manual-confirmation`.
+3. Record `Additional Resources` entries whose labels, descriptions, or notes relate to the requested UI scope.
+4. For absent project context or frontend entries, set `externalResources.status` to `not_recorded` and continue with codebase analysis.
+
+### Step 2: External Resource Resolution
+
+For each relevant resource, resolve the subset implied by `requirement_analysis.affectedFiles`, `target_paths`, `focus_areas`, `target_components`, and `prototype_path`:
+
+| Status / Access Method | Handling |
+|------------------------|----------|
+| `present` + MCP server | Use the available MCP tool matching the server and requested resource |
+| `present` + public URL | Use available web fetch or browser tooling |
+| `present` + file path | Read the file |
+| `present` + command | Inspect with the command when it is safe and relevant |
+| `existing-implementation` | Treat existing UI code as the source of truth and inspect matching files |
+| `existing-package` | Inspect package usage, imports, local docs, and story files |
+| `project-conventions` | Infer conventions from local code, config, and docs |
+| `manual-confirmation` | Record the verification path for the parent session |
+
+For large design files, component catalogs, or prototype directories, resolve only the relevant subset. Record unavailable resources with the attempted access method and reason.
+
+When `prototype_path` is provided, read it as analysis input. Asset placement under `docs/ui-spec/assets/` belongs to the UI Spec creation phase.
+
+### Step 3: UI Surface Discovery in Code
+
+1. Identify UI-rendering files from `requirement_analysis.affectedFiles` and inferred frontend paths.
+2. Build a component-file index using project-appropriate glob patterns.
+3. Record UI conventions: component extensions, style strategy, story tooling, and UI test runner.
+
+### Step 4: Component Structure Extraction
+
+For each component file in scope, read the file and extract:
+- component name and export form
+- props interface or parameter shape
+- top-level JSX element and immediate children
+- conditional rendering branches
+- imported child components and call sites
+- source-order DOM sequence for layout siblings
+
+### Step 5: Props and Variant Patterns
+
+For each relevant call site:
+- record literal and computed props
+- group variant, size, color, and state combinations
+- identify canonical usage patterns and outliers with file:line evidence
+
+### Step 6: CSS Layout State
+
+For each style source in scope:
+- class naming convention
+- layout primitives: display, direction, gap, wrap, logical properties
+- state selectors and responsive breakpoints
+
+### Step 7: State x Display Matrix
+
+For each component in scope:
+- infer states from props, hooks, branches, fetch flags, and route context
+- record rendered output for each state
+- record expected states that lack an observed code path as `unsupportedStates`
+
+### Step 8: Display Conditions
+
+Record feature flags, role or permission gates, route context, tenant or region gates, and page-context modifiers that affect rendered UI.
+
+### Step 9: i18n and Generated Artifacts
+
+When localized strings or generated UI artifacts appear in scope, record formats, naming conventions, generator commands, output paths, and consumers.
+
+### Step 10: Accessibility Attributes
+
+Record roles, accessible names, ARIA attributes, keyboard handling, focus styling, and accessibility test coverage in scope.
+
+### Step 11: Candidate Write Set
+
+Produce `candidateWriteSet[]` with likely modified files:
+- `path`
+- `reasonRef`
+- `confidence`: `high`, `medium`, or `low`
+
+## Output Format
+
+Return a single JSON object as the final response:
+
+```json
+{
+  "analysisScope": {
+    "filesAnalyzed": ["path/to/component.tsx"],
+    "stylesAnalyzed": ["path/to/styles.module.css"],
+    "uiConventions": {
+      "componentExtension": ".tsx",
+      "styleStrategy": "css-modules|vanilla-css|css-in-js|utility-classes|unknown",
+      "storybook": true,
+      "testRunner": "vitest|jest|other|unknown"
+    }
+  },
+  "externalResources": {
+    "status": "resolved|partial|not_recorded",
+    "designOrigin": {
+      "resource_status": "present|existing-implementation|not_applicable",
+      "resolution_status": "fetched|inspected_local|recorded_for_manual_confirmation|unavailable|not_applicable",
+      "accessMethod": "MCP name | URL | file path | existing implementation",
+      "summary": "brief description of resolved content"
+    },
+    "designSystem": {
+      "resource_status": "present|existing-package|not_applicable",
+      "resolution_status": "fetched|inspected_local|unavailable|not_applicable",
+      "accessMethod": "MCP name | URL | file path | package imports | local docs",
+      "summary": "components, tokens, and variants captured"
+    },
+    "guidelines": {
+      "resource_status": "present|project-conventions|not_applicable",
+      "resolution_status": "fetched|inspected_local|unavailable|not_applicable",
+      "accessMethod": "URL | file path | local docs | project conventions",
+      "summary": "rule categories captured"
+    },
+    "visualVerification": {
+      "resource_status": "present|manual-confirmation|not_applicable",
+      "resolution_status": "available|recorded_for_manual_confirmation|unavailable|not_applicable",
+      "accessMethod": "MCP name | URL | command | manual confirmation",
+      "notes": "rendering verification path"
+    },
+    "generatedUiArtifacts": {
+      "resource_status": "present|not_applicable",
+      "resolution_status": "inspected_local|available|unavailable|not_applicable",
+      "accessMethod": "command | config path | file path | package script",
+      "summary": "generated UI artifact source, trigger, and verification path"
+    },
+    "additionalResources": [
+      {
+        "label": "resource-label",
+        "description": "resource description",
+        "accessMethod": "URL | MCP name | file path | command | notes",
+        "resource_status": "present|existing-implementation|existing-package|project-conventions|manual-confirmation",
+        "resolution_status": "fetched|inspected_local|recorded_for_manual_confirmation|unavailable",
+        "summary": "facts relevant to the requested UI scope"
+      }
+    ]
+  },
+  "componentStructure": [
+    {
+      "name": "ComponentName",
+      "filePath": "path/to/file:line",
+      "propsInterface": "name and brief shape",
+      "topLevelElement": "tag or component name",
+      "domOrder": ["child1", "child2"],
+      "conditionalBranches": [
+        {"predicate": "condition", "renderedSubtree": "brief description"}
+      ],
+      "callSites": ["path/to/consumer:line"]
+    }
+  ],
+  "propsPatterns": [
+    {
+      "component": "ComponentName",
+      "callSite": "path/to/file:line",
+      "props": {"variant": "primary"},
+      "computedProps": ["onClick"],
+      "groupKey": "primary"
+    }
+  ],
+  "cssLayout": [
+    {
+      "filePath": "path/to/styles.module.css",
+      "classNamingConvention": "camelCase|kebab-case|BEM|unknown",
+      "baseClass": "root",
+      "layouts": [
+        {
+          "selector": ".root",
+          "display": "flex|grid|block|unknown",
+          "direction": "row|column|grid-template|unknown",
+          "gap": "8px|none|unknown",
+          "wrap": "wrap|nowrap|absent|unknown",
+          "logicalProperties": true,
+          "stateSelectors": ["[data-state=active]"]
+        }
+      ],
+      "responsiveBreakpoints": ["768px"]
+    }
+  ],
+  "stateDisplay": [
+    {
+      "component": "ComponentName",
+      "states": [
+        {"name": "loading|empty|partial|error|ready|disabled", "trigger": "what causes this state", "renders": "brief description"}
+      ],
+      "unsupportedStates": ["state absent from current component"]
+    }
+  ],
+  "displayConditions": [
+    {
+      "component": "ComponentName",
+      "condition": "feature_flag|role|route|region|tenant|page_context",
+      "predicateLocation": "path/to/file:line",
+      "predicate": "expression",
+      "gatedSubtree": "brief description"
+    }
+  ],
+  "i18n": {
+    "format": "csv|json|code-catalog|other|none",
+    "structuralConventions": {},
+    "keyNamingConvention": "",
+    "locales": [],
+    "localeGaps": [],
+    "generatedTypings": {"command": "", "outputPath": ""}
+  },
+  "accessibility": [
+    {
+      "component": "ComponentName",
+      "ariaAttributes": ["role=button", "aria-label from prop"],
+      "keyboardHandling": "Enter and Space trigger action",
+      "focusStyling": "focus-visible outline",
+      "testCoverage": "axe checks present|absent|unknown"
+    }
+  ],
+  "generatedArtifacts": [
+    {
+      "kind": "css-module-typings|message-catalog-typings|route-typings|other",
+      "command": "generator command",
+      "trigger": "on source change|manual|unknown",
+      "consumers": ["typecheck", "test", "build", "runtime"],
+      "resourceRef": "externalResources.generatedUiArtifacts"
+    }
+  ],
+  "focusAreas": [
+    {
+      "fact_id": "path:identifier",
+      "area": "Brief UI area name",
+      "evidence": "componentStructure[name=...]",
+      "factsToAddress": "Concrete UI facts to respect",
+      "risk": "What inconsistency results if omitted"
+    }
+  ],
+  "candidateWriteSet": [
+    {
+      "path": "src/components/Card.tsx",
+      "reasonRef": "focusAreas[fact_id=...]",
+      "confidence": "high|medium|low"
+    }
+  ],
+  "limitations": []
+}
+```
+
+## Quality Checklist
+
+- [ ] Each external resource entry records `resource_status` and `resolution_status`
+- [ ] `candidateWriteSet` reflects the requested UI change
+- [ ] Every `focusAreas` entry carries an evidence pointer
+- [ ] Sections outside scope use empty arrays or concise N/A values
+- [ ] Final message is a JSON object
+"""
+
+[[skills.config]]
+path = ".agents/skills/coding-rules/SKILL.md"
+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/ui-spec-designer.toml

@@ -41,11 +41,13 @@ Skill Status:
 4. Define component decomposition with state x display matrices
 5. Identify reusable existing components in the codebase
 6. Define accessibility requirements
+7. Carry forward external resource references used for UI decisions
 
 ## Required Information
 
 - **PRD**: PRD document path (required if exists; otherwise requirement-analyzer output is used)
 - **Prototype code path**: Path to prototype code (optional, placed in `docs/ui-spec/assets/{feature-name}/`)
+- **UI analysis**: JSON from ui-analyzer when provided, including externalResources, componentStructure, propsPatterns, cssLayout, stateDisplay, focusAreas, and candidateWriteSet
 - **Existing frontend codebase**: Will be investigated automatically
 
 ## Mandatory Process Before UI Spec Creation
@@ -93,6 +95,13 @@ Skill Status:
    - Search for existing theme/token definitions
    - Note spacing, color, typography conventions in use
 
+### Step 3a: External Resource Integration
+
+1. Read `docs/project-context/external-resources.md` when present
+2. Use `ui_analysis.externalResources` as the fetched summary for design origin, design system, guidelines, and visual verification
+3. Fill `External Resources Used` with project resource labels and feature-specific identifiers
+4. Keep project-level access methods in `docs/project-context/external-resources.md`
+
 ### Step 4: Draft UI Spec
 
 1. **Copy ui-spec-template** from documentation-criteria skill
@@ -103,6 +112,7 @@ Skill Status:
    - Interaction definitions linked to AC IDs with EARS format
    - Existing component reuse map
    - Design tokens (from existing codebase)
+   - External Resources Used
    - Visual acceptance criteria
    - Accessibility requirements (keyboard, screen reader, contrast)
 3. **Output path**: `docs/ui-spec/{feature-name}-ui-spec.md`
@@ -118,6 +128,7 @@ Execute file output immediately. Final approval is managed by the orchestrator r
 - [ ] Interaction definitions use EARS format and reference AC IDs
 - [ ] Screen transitions have trigger and guard conditions defined
 - [ ] Existing component reuse map is complete (reuse/extend/new for each element)
+- [ ] External Resources Used lists project resource labels and feature identifiers when external resources informed the UI Spec
 - [ ] Accessibility requirements cover keyboard navigation and screen reader support
 - [ ] If prototype provided: AC traceability table is complete with adoption decisions
 - [ ] If prototype provided: prototype is placed in `docs/ui-spec/assets/`
@@ -148,3 +159,7 @@ enabled = true
 [[skills.config]]
 path = ".agents/skills/coding-rules/SKILL.md"
 enabled = true
+
+[[skills.config]]
+path = ".agents/skills/external-resource-context/SKILL.md"
+enabled = true

package/README.md

@@ -4,9 +4,11 @@
 [![Agent Skills](https://img.shields.io/badge/Agent%20Skills-Spec%20Compliant-blue)](https://developers.openai.com/codex/skills/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**Structured agentic coding workflows for [OpenAI Codex CLI](https://developers.openai.com/codex/cli)** — specialized AI coding agents plan, implement, test, and review changes with traceable docs, task-level commits, and quality gates.
+**Structured workflows for [OpenAI Codex CLI](https://developers.openai.com/codex/cli).**
 
-Built on the [Agent Skills specification](https://developers.openai.com/codex/skills/) and [Codex subagents](https://developers.openai.com/codex/subagents). Designed for long-running tasks, large refactors, and reviewable changes.
+They help when multi-step changes stop being easy to reason about, test, or review.
+
+Built on the [Agent Skills specification](https://developers.openai.com/codex/skills/) and [Codex subagents](https://developers.openai.com/codex/subagents). This starts to matter when tasks get large: refactors, migrations, or anything that spans multiple files and needs to stay reviewable.
 
 ---
 
@@ -25,43 +27,49 @@ $recipe-implement Add user authentication with JWT
 
 `$` is Codex CLI's syntax for invoking a skill explicitly. Type `$recipe-` to see all available recipes via tab completion.
 
-Small changes stay lightweight. Larger tasks get structure: requirements → design → task decomposition → TDD implementation → quality gates.
+Small changes stay lightweight. Larger tasks are broken into requirements, design, task decomposition, TDD implementation, and quality checks.
 
 ---
 
 ## Why codex-workflows?
 
-Codex is already strong at one-shot implementation. The problem starts when a change spans multiple files, needs design decisions to stay visible, or has to survive review, testing, and follow-up edits.
+Codex works well for short, focused tasks. The problems start when a change spans multiple files, needs design decisions to stay visible, or has to survive review, testing, and follow-up edits.
 
-For larger tasks, explicit planning changes the job from raw generation into verification against a design, a task breakdown, and acceptance criteria. That matters because review loops are more reliable than first-shot generation once scope and ambiguity grow.
+Many developers have seen the same pattern: things work at first, then drift. Context grows, assumptions accumulate, intermediate decisions disappear, and results become harder to trust.
 
-codex-workflows adds the missing structure around those jobs:
+codex-workflows is built around those failure modes. Instead of asking Codex to "just implement it", it turns a request into a sequence of steps you can inspect and verify:
 - Traceable artifacts: PRD → Design Doc → Task → Commit
-- Built-in TDD and quality gates before code is ready to commit
+- Built-in TDD and quality checks before code is ready to commit
 - Agent context separation for large refactors, migrations, and PR-sized changes
 - Diagnosis and reverse-engineering flows for bugs and legacy code
 
+## Background
+
+The recipes, subagents, and quality checks in this repo were not designed top-down. Each piece was added in response to a concrete failure mode encountered during delivery work.
+
+That is why the workflow separates requirements, design, verification, implementation, and quality checks instead of treating them as one long session.
+
 ## Not Designed For
 
-- One-shot toy scripts or vibe-coding sessions where speed matters more than traceability
-- Repositories that do not use tests, lint, builds, or reviewable commits
-- Teams that do not want design docs, task breakdowns, or explicit quality gates
+- One-shot scripts or exploratory sessions where speed matters more than traceability
+- Repositories without tests, lint, builds, or reviewable commits
+- Teams that would rather skip design docs and quality checks entirely
 
 ---
 
 ## What It Does
 
-A single request becomes a structured development process. The framework chooses the level of ceremony based on scope:
+Instead of forcing a fixed workflow, the framework adjusts how much structure it adds based on scope:
 
 | Scale | File Count | What Happens |
 |-------|------------|-------------|
 | Small | 1-2 | Simplified plan → direct implementation |
 | Medium | 3-5 | Design Doc → work plan → task execution |
-| Large | 6+ | PRD → ADR → Design Doc → test skeletons → work plan → autonomous execution |
+| Large | 6+ | PRD → ADR → Design Doc → test skeletons → work plan → guided autonomous execution |
 
 For larger work, the path usually looks like this: understand the problem, analyze the codebase, design the change, break it into atomic tasks, implement with tests, and run quality checks before commit.
 
-Each step is handled by a specialized subagent in its own context, using context engineering to prevent context pollution and reduce error accumulation in long-running tasks:
+Each step isolates one concern, so decisions can be checked before they carry into later stages. Specialized subagents run in their own contexts to reduce carry-over assumptions during changes that would otherwise require long sessions:
 
 ```
 User Request
@@ -86,7 +94,7 @@ task-decomposer       →  Atomic tasks (1 task = 1 commit)
     ↓
 task-executor         →  TDD implementation per task
     ↓
-quality-fixer         →  Lint, test, build — no failing checks
+quality-fixer         →  Lint, test, build; no failing checks
     ↓
 Ready to commit
 ```
@@ -158,7 +166,7 @@ Invoke recipes with `$recipe-name` in Codex. Type `$recipe-` and use tab complet
 | `$recipe-design` | Requirements → ADR/Design Doc | Architecture planning |
 | `$recipe-plan` | Design Doc → test skeletons → work plan | Planning phase, including nullable E2E skeleton handling |
 | `$recipe-prepare-implementation` | Verify work plan readiness and resolve prep gaps | Pre-build check that the plan is implementable |
-| `$recipe-build` | Execute backend tasks autonomously | Resume backend implementation |
+| `$recipe-build` | Execute backend tasks with validation between steps | Resume backend implementation |
 | `$recipe-review` | Design Doc compliance and security validation with auto-fixes | Post-implementation check |
 | `$recipe-diagnose` | Problem investigation → failure-point verification → solution | Bug investigation |
 | `$recipe-reverse-engineer` | Generate PRD + Design Docs from existing code | Legacy system documentation |
@@ -170,6 +178,7 @@ Invoke recipes with `$recipe-name` in Codex. Type `$recipe-` and use tab complet
 | Recipe | What it does | When to use |
 |--------|-------------|-------------|
 | `$recipe-front-design` | Requirements → UI Spec → frontend Design Doc | Frontend architecture planning |
+| `$recipe-front-adjust` | Implemented UI adjustment with external context and verification | Focused UI changes after implementation |
 | `$recipe-front-plan` | Frontend Design Doc → test skeletons → work plan | Frontend planning phase |
 | `$recipe-front-build` | Execute frontend tasks with RTL + quality checks | Resume frontend implementation |
 | `$recipe-front-review` | Frontend compliance and security validation with React-specific fixes | Frontend post-implementation check |
@@ -217,7 +226,7 @@ $recipe-reverse-engineer src/auth module
 
 ## Foundational Skills
 
-These load automatically when the conversation context matches — no explicit invocation needed:
+These are applied automatically based on context. You rarely need to think about them directly.
 
 | Skill | What it provides |
 |-------|-----------------|
@@ -227,8 +236,9 @@ These load automatically when the conversation context matches — no explicit i
 | `documentation-criteria` | Document creation rules and templates (PRD, ADR, Design Doc, Work Plan) |
 | `implementation-approach` | Strategy selection: vertical / horizontal / hybrid slicing |
 | `integration-e2e-testing` | Integration/E2E test design, value-based selection, review criteria |
+| `external-resource-context` | Access methods for design sources, design systems, API schemas, and verification environments |
 | `task-analyzer` | Task analysis, scale estimation, skill selection |
-| `subagents-orchestration-guide` | Multi-agent coordination, workflow flows, autonomous execution |
+| `subagents-orchestration-guide` | Multi-agent coordination, workflow flows, guided autonomous execution |
 
 Language-specific references are included for TypeScript/React projects (`coding-rules/references/typescript.md`, `testing/references/typescript.md`).
 
@@ -236,7 +246,7 @@ Language-specific references are included for TypeScript/React projects (`coding
 
 ## Subagents
 
-Codex spawns these as needed during recipe execution. Each agent runs in its own context with specialized instructions and skill configurations.
+Codex spawns these as needed during recipe execution. You do not need to learn them first; recipes route work to the right agents automatically. Each agent runs in its own context with specialized instructions and skill configurations.
 
 ### Document Creation Agents
 
@@ -248,6 +258,7 @@ Codex spawns these as needed during recipe execution. Each agent runs in its own
 | `technical-designer-frontend` | Frontend ADR and Design Doc creation (React) |
 | `ui-spec-designer` | UI Specification from PRD and optional prototype code |
 | `codebase-analyzer` | Existing codebase analysis before Design Doc creation |
+| `ui-analyzer` | UI facts from external resources (design tools, design-system docs, deployed UI) and frontend code |
 | `work-planner` | Work plan creation from Design Docs |
 | `document-reviewer` | Document consistency and approval |
 | `design-sync` | Cross-document consistency verification |
@@ -286,18 +297,18 @@ Codex spawns these as needed during recipe execution. Each agent runs in its own
 
 ## How It Works
 
-### Autonomous Execution Mode
+### Guided Autonomous Execution Mode
 
-After work plan approval, the framework enters guided autonomous execution with escalation points:
+After work plan approval, the framework executes task files with explicit validation points:
 
 1. **task-executor** implements each task with TDD
 2. **quality-fixer** first rejects incomplete task-scoped implementations, then runs lint, tests, and build before every commit
 3. Escalation pauses execution when design deviation or ambiguity is detected
-4. Each task produces one commit — rollback-friendly granularity
+4. Each task produces one commit for rollback-friendly granularity
 
 ### Context Separation
 
-Each subagent runs in a fresh context. This context-engineering pattern keeps long-running agentic coding tasks legible and reviewable:
+Each subagent runs in a fresh context. This pattern keeps multi-step coding tasks legible and reviewable:
 - generation and verification happen in separate contexts, reducing author bias and carry-over assumptions
 - **document-reviewer** reviews without the author's bias
 - **investigator** collects evidence without confirmation bias
@@ -318,11 +329,13 @@ your-project/
 │   ├── documentation-criteria/
 │   ├── implementation-approach/
 │   ├── integration-e2e-testing/
+│   ├── external-resource-context/
 │   ├── task-analyzer/
 │   ├── subagents-orchestration-guide/
 │   ├── recipe-implement/     # Recipes ($recipe-*)
 │   ├── recipe-design/
 │   ├── recipe-build/
+│   ├── recipe-front-adjust/
 │   ├── recipe-plan/
 │   ├── recipe-prepare-implementation/
 │   ├── recipe-review/
@@ -334,8 +347,9 @@ your-project/
 ├── .codex/agents/            # Subagent TOML definitions
 │   ├── requirement-analyzer.toml
 │   ├── technical-designer.toml
+│   ├── ui-analyzer.toml
 │   ├── task-executor.toml
-│   └── ... (23 agents total)
+│   └── ... (25 agents total)
 └── docs/                     # Created as you use the recipes
     ├── prd/
     ├── design/
@@ -371,7 +385,11 @@ A: `$recipe-implement` is the universal entry point. It runs requirement-analyze
 
 **Q: Does this work with MCP servers?**
 
-A: Yes. Codex skills and subagents work alongside [MCP](https://developers.openai.com/codex/mcp) — skills operate at the instruction layer while MCP operates at the tool transport layer. You can add MCP servers to any agent's TOML configuration.
+A: Yes. Codex skills and subagents work alongside [MCP](https://developers.openai.com/codex/mcp) — skills operate at the instruction layer while MCP operates at the tool transport layer. Custom agents inherit parent `mcp_servers` when the agent TOML omits `mcp_servers`; add agent-local MCP config only for agent-specific servers or tool filtering.
+
+**Q: How is this related to claude-code-workflows?**
+
+A: [claude-code-workflows](https://github.com/shinpr/claude-code-workflows) is the Claude Code counterpart. The repositories share the same workflow philosophy, adapted to each tool's native extension points. They can coexist in the same project because Codex uses `.agents/skills/`, `.codex/agents/`, and `AGENTS.md`, while Claude Code uses its own `.claude/` files and `CLAUDE.md`.
 
 **Q: What if a subagent seems stuck?**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-workflows",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Task-oriented agentic coding framework for OpenAI Codex CLI — skills, recipes, and subagents for structured development workflows",
   "license": "MIT",
   "author": "Shinsuke Kagawa",