chore: release v7.2.5

Update DDD commands (doc-generate, doc-refresh, sync), workflow commands
(session/sync, spec/add, spec/setup, spec/load), ccw specs, personal
preferences, and add generate-ddd-docs tool.

.ccw/personal/coding-style.md

@@ -0,0 +1,27 @@
+---
+title: "Personal Coding Style"
+dimension: personal
+category: general
+keywords:
+  - style
+  - preference
+readMode: optional
+priority: medium
+---
+
+# Personal Coding Style
+
+## Preferences
+
+- Describe your preferred coding style here
+- Example: verbose variable names vs terse, functional vs imperative
+
+## Patterns I Prefer
+
+- List patterns you reach for most often
+- Example: builder pattern, factory functions, tagged unions
+
+## Things I Avoid
+
+- List anti-patterns or approaches you dislike
+- Example: deep inheritance hierarchies, magic strings

.ccw/personal/tool-preferences.md

@@ -0,0 +1,25 @@
+---
+title: "Tool Preferences"
+dimension: personal
+category: general
+keywords:
+  - tool
+  - cli
+  - editor
+readMode: optional
+priority: low
+---
+
+# Tool Preferences
+
+## Editor
+
+- Preferred editor and key extensions/plugins
+
+## CLI Tools
+
+- Preferred shell, package manager, build tools
+
+## Debugging
+
+- Preferred debugging approach and tools

.ccw/specs/architecture-constraints.md

@@ -1,3 +1,13 @@
+---
+title: Architecture Constraints
+readMode: optional
+priority: medium
+category: general
+scope: project
+dimension: specs
+keywords: [architecture, constraint, schema, compatibility, portability, design, arch]
+---
+
 # Architecture Constraints
 
 ## Schema Evolution

.ccw/specs/coding-conventions.md

@@ -1,3 +1,13 @@
+---
+title: Coding Conventions
+readMode: optional
+priority: medium
+category: general
+scope: project
+dimension: specs
+keywords: [coding, convention, style, naming, pattern, navigation, schema, error-handling, implementation, validation, clarity, doc]
+---
+
 # Coding Conventions
 
 ## Navigation & Path Handling
@@ -9,6 +19,7 @@
 ## Document Generation
 
 - [architecture] For document generation systems, adopt Layer 3→2→1 pattern (components → features → indexes) for efficient incremental updates. (learned: 2026-03-07)
+- [tools] When commands need to generate files with deterministic paths and frontmatter, use dedicated ccw tool endpoints (`ccw tool exec`) instead of raw `ccw cli -p` calls. Endpoints control output path, file naming, and structural metadata; CLI tools only generate prose content. (learned: 2026-03-09)
 
 ## Implementation Quality
 

.claude/agents/team-worker.md

@@ -8,12 +8,12 @@ description: |
 
   Examples:
   - Context: Coordinator spawns analyst worker
-    user: "role: analyst\nrole_spec: .claude/skills/team-lifecycle/role-specs/analyst.md\nsession: .workflow/.team/TLS-xxx"
+    user: "role: analyst\nrole_spec: ~  or <project>/.claude/skills/team-lifecycle/role-specs/analyst.md\nsession: .workflow/.team/TLS-xxx"
     assistant: "Loading role spec, discovering RESEARCH-* tasks, executing Phase 2-4 domain logic"
     commentary: Agent parses prompt, loads role spec, runs built-in Phase 1 then role-specific Phase 2-4 then built-in Phase 5
 
   - Context: Coordinator spawns writer worker with inner loop
-    user: "role: writer\nrole_spec: .claude/skills/team-lifecycle/role-specs/writer.md\ninner_loop: true"
+    user: "role: writer\nrole_spec: ~  or <project>/.claude/skills/team-lifecycle/role-specs/writer.md\ninner_loop: true"
     assistant: "Loading role spec, processing all DRAFT-* tasks in inner loop"
     commentary: Agent detects inner_loop=true, loops Phase 1-5 for each same-prefix task
 color: green

.claude/commands/ddd/doc-generate.md

@@ -48,8 +48,9 @@ doc-index.json → tech-registry/*.md (L3) → feature-maps/*.md (L2) → _index
 ├── tech-registry/              ← Component documentation (Layer 3)
 │   ├── _index.md
 │   └── {component-slug}.md
-└── sessions/
-    └── _index.md               ← Planning sessions index (Layer 1)
+└── planning/                   ← Planning sessions (Layer 1)
+    ├── _index.md               ← Planning sessions index
+    └── {task-slug}-{date}/     ← Individual session folders
 ```
 
 ## Phase 1: Load & Validate
@@ -87,147 +88,82 @@ IF docs already exist AND NOT --force:
   Ask user (unless -y → overwrite)
 ```
 
-## Phase 2: Layer 3 — Component Documentation
+## Phase 2: Layer 3 -- Component Documentation
 
-For each component in `technicalComponents[]`:
+For each component in `technicalComponents[]`, call the generate_ddd_docs endpoint:
 
 ```bash
-ccw cli -p "PURPOSE: Generate component documentation for {component.name}
-TASK:
-• Document component purpose and responsibility
-• List exported symbols (classes, functions, types)
-• Document dependencies (internal and external)
-• Include code examples for key APIs
-• Document integration points with other components
-MODE: write
-CONTEXT: @{component.codeLocations[].path}
-EXPECTED: Markdown file with: Overview, API Reference, Dependencies, Usage Examples
-CONSTRAINTS: Focus on public API | Include type signatures
-" --tool gemini --mode write --cd .workflow/.doc-index/tech-registry/
+for COMPONENT_ID in "${technicalComponents[@]}"; do
+  ccw tool exec generate_ddd_docs '{"strategy":"component","entityId":"'"$COMPONENT_ID"'","tool":"gemini"}'
+done
 ```
 
+The endpoint handles:
+- Loading the component entity from doc-index.json
+- Building YAML frontmatter (layer: 3, component_id, name, type, features, code_locations, generated_at)
+- Constructing the CLI prompt with code context paths
+- **Including Change History section**: Pull related entries from `doc-index.json.actions[]` where `affectedComponents` includes this component ID. Display as timeline (date, action type, description)
+- Writing output to `.workflow/.doc-index/tech-registry/{slug}.md`
+- Tool fallback (gemini -> qwen -> codex) on failure
+
 Output: `.workflow/.doc-index/tech-registry/{component-slug}.md`
 
-Frontmatter:
-```markdown
----
-layer: 3
-component_id: tech-{slug}
-name: ComponentName
-type: service|controller|model|...
-features: [feat-auth]
-code_locations:
-  - path: src/services/auth.ts
-    symbols: [AuthService, AuthService.login]
-generated_at: ISO8601
----
-```
+## Phase 3: Layer 2 -- Feature Documentation
 
-Sections: Responsibility, Code Locations, Related Requirements, Architecture Decisions, Dependencies (in/out)
-
-## Phase 3: Layer 2 — Feature Documentation
-
-For each feature in `features[]`:
+For each feature in `features[]`, call the generate_ddd_docs endpoint:
 
 ```bash
-ccw cli -p "PURPOSE: Generate feature documentation for {feature.name}
-TASK:
-• Describe feature purpose and business value
-• List requirements (from requirementIds)
-• Document components involved (from techComponentIds)
-• Include architecture decisions (from adrIds)
-• Provide integration guide
-MODE: write
-CONTEXT: @.workflow/.doc-index/tech-registry/{related-components}.md
-EXPECTED: Markdown file with: Overview, Requirements, Components, Architecture, Integration
-CONSTRAINTS: Reference Layer 3 component docs | Business-focused language
-" --tool gemini --mode write --cd .workflow/.doc-index/feature-maps/
+for FEATURE_ID in "${features[@]}"; do
+  ccw tool exec generate_ddd_docs '{"strategy":"feature","entityId":"'"$FEATURE_ID"'","tool":"gemini"}'
+done
 ```
 
+The endpoint handles:
+- Loading the feature entity from doc-index.json
+- Building YAML frontmatter (layer: 2, feature_id, name, epic_id, status, requirements, components, tags, generated_at)
+- Constructing the CLI prompt referencing Layer 3 component docs
+- **Including Change History section**: Pull related entries from `doc-index.json.actions[]` where `affectedFeatures` includes this feature ID. Display as timeline (date, action type, description)
+- Writing output to `.workflow/.doc-index/feature-maps/{slug}.md`
+- Tool fallback (gemini -> qwen -> codex) on failure
+
 Output: `.workflow/.doc-index/feature-maps/{feature-slug}.md`
 
-Frontmatter:
-```markdown
----
-layer: 2
-feature_id: feat-{slug}
-name: Feature Name
-epic_id: EPIC-NNN|null
-status: implemented|in-progress|planned|partial
-requirements: [REQ-001, REQ-002]
-components: [tech-auth-service, tech-user-model]
-depends_on_layer3: [tech-auth-service, tech-user-model]
-tags: [auth, security]
-generated_at: ISO8601
----
-```
-
-Sections: Overview, Requirements (with mapping status), Technical Components, Architecture Decisions, Change History
-
-## Phase 4: Layer 1 — Index & Overview Documentation
+## Phase 4: Layer 1 -- Index & Overview Documentation
 
 ### 4.1 Index Documents
 
-Generate catalog files:
+Generate catalog files for each subdirectory:
 
-- **feature-maps/_index.md** — Feature overview table with status
-- **tech-registry/_index.md** — Component registry table with types
-- **action-logs/_index.md** — Action history table (empty initially for new projects)
+```bash
+# Feature maps index
+ccw tool exec generate_ddd_docs '{"strategy":"index","entityId":"feature-maps","tool":"gemini"}'
+
+# Tech registry index
+ccw tool exec generate_ddd_docs '{"strategy":"index","entityId":"tech-registry","tool":"gemini"}'
+
+# Action logs index
+ccw tool exec generate_ddd_docs '{"strategy":"index","entityId":"action-logs","tool":"gemini"}'
+
+# Planning sessions index
+ccw tool exec generate_ddd_docs '{"strategy":"index","entityId":"planning","tool":"gemini"}'
+```
+
+Or generate all indexes at once (omit entityId):
+
+```bash
+ccw tool exec generate_ddd_docs '{"strategy":"index","tool":"gemini"}'
+```
 
 ### 4.2 README.md (unless --skip-overview)
 
 ```bash
-ccw cli -p "PURPOSE: Generate project README with overview and navigation
-TASK:
-• Project summary and purpose
-• Quick start guide
-• Navigation to features, components, and architecture
-• Link to doc-index.json
-MODE: write
-CONTEXT: @.workflow/.doc-index/doc-index.json @.workflow/.doc-index/feature-maps/_index.md
-EXPECTED: README.md with: Overview, Quick Start, Navigation, Links
-CONSTRAINTS: High-level only | Entry point for new developers
-" --tool gemini --mode write --cd .workflow/.doc-index/
+ccw tool exec generate_ddd_docs '{"strategy":"overview","tool":"gemini"}'
 ```
 
 ### 4.3 ARCHITECTURE.md (unless --skip-overview)
 
 ```bash
-ccw cli -p "PURPOSE: Generate architecture overview document
-TASK:
-• System design overview
-• Component relationships and dependencies
-• Key architecture decisions (from ADRs)
-• Technology stack
-MODE: write
-CONTEXT: @.workflow/.doc-index/doc-index.json @.workflow/.doc-index/tech-registry/*.md
-EXPECTED: ARCHITECTURE.md with: System Design, Component Diagram, ADRs, Tech Stack
-CONSTRAINTS: Architecture-focused | Reference component docs for details
-" --tool gemini --mode write --cd .workflow/.doc-index/
-```
-
-### 4.4 sessions/_index.md (unless --skip-overview)
-
-```bash
-ccw cli -p "PURPOSE: Generate planning sessions index
-TASK:
-• List all planning session folders chronologically
-• Link to each session's plan.json
-• Show session status and task count
-MODE: write
-CONTEXT: @.workflow/.doc-index/planning/*/plan.json
-EXPECTED: sessions/_index.md with: Session List, Links, Status
-CONSTRAINTS: Chronological order | Link to session folders
-" --tool gemini --mode write --cd .workflow/.doc-index/sessions/
-```
-
-Layer 1 frontmatter:
-```markdown
----
-layer: 1
-depends_on_layer2: [feat-auth, feat-orders]
-generated_at: ISO8601
----
+ccw tool exec generate_ddd_docs '{"strategy":"overview","entityId":"architecture","tool":"gemini"}'
 ```
 
 ## Phase 5: SCHEMA.md (unless --skip-schema)
@@ -235,17 +171,7 @@ generated_at: ISO8601
 ### 5.1 Generate Schema Documentation
 
 ```bash
-ccw cli -p "PURPOSE: Document doc-index.json schema structure and versioning
-TASK:
-• Document current schema structure (all fields)
-• Define versioning policy (semver: major.minor)
-• Document migration protocol for version upgrades
-• Provide examples for each schema section
-MODE: write
-CONTEXT: @.workflow/.doc-index/doc-index.json
-EXPECTED: SCHEMA.md with: Schema Structure, Versioning Policy, Migration Protocol, Examples
-CONSTRAINTS: Complete field documentation | Clear migration steps
-" --tool gemini --mode write --cd .workflow/.doc-index/
+ccw tool exec generate_ddd_docs '{"strategy":"schema","tool":"gemini"}'
 ```
 
 ### 5.2 Versioning Policy
@@ -284,7 +210,7 @@ Total: {N} documents generated
 | `-y, --yes` | Auto-confirm all decisions |
 | `--layer <3\|2\|1\|all>` | Generate specific layer only (default: all) |
 | `--force` | Overwrite existing documents |
-| `--skip-overview` | Skip README.md, ARCHITECTURE.md, sessions/_index.md |
+| `--skip-overview` | Skip README.md, ARCHITECTURE.md, planning/_index.md |
 | `--skip-schema` | Skip SCHEMA.md generation |
 
 ## Integration Points
@@ -293,3 +219,4 @@ Total: {N} documents generated
 - **Called by**: `/ddd:scan` (after index assembly), `/ddd:index-build` (after index assembly)
 - **Standalone**: Can be run independently on any project with existing doc-index.json
 - **Output**: Complete document tree in `.workflow/.doc-index/`
+- **Endpoint**: `ccw tool exec generate_ddd_docs` handles prompt construction, frontmatter, tool fallback, and file creation

.claude/commands/ddd/doc-refresh.md

@@ -163,7 +163,7 @@ ccw cli -p "PURPOSE: Update project overview docs after feature changes
 TASK:
 • Update README.md feature list
 • Update ARCHITECTURE.md if new components added
-• Update sessions/_index.md with new planning sessions
+• Update planning/_index.md with new planning sessions
 MODE: write
 CONTEXT: @.workflow/.doc-index/feature-maps/*.md @.workflow/.doc-index/doc-index.json
 EXPECTED: Updated overview docs with current project state

.claude/commands/ddd/sync.md

@@ -37,11 +37,42 @@ After completing a development task, synchronize the document index with actual
 - `doc-index.json` must exist
 - Git repository with committed or staged changes
 
+## Phase 0: Consistency Validation
+
+Before processing changes, verify that `doc-index.json` entries are consistent with actual code state.
+
+### 0.1 Validate Code Locations
+
+For each `technicalComponents[].codeLocations[]`:
+- Verify file exists on disk
+- If file was deleted/moved → flag for removal or update
+- If file exists → verify listed `symbols[]` still exist (quick grep/AST check)
+
+### 0.2 Validate Symbols
+
+For components with `codeLocations[].symbols[]`:
+- Check each symbol still exists in the referenced file
+- Detect new exported symbols not yet tracked
+- Report: `{N} stale symbols, {N} untracked symbols`
+
+### 0.3 Validation Report
+
+```
+Consistency Check:
+  Components validated: {N}
+  Files verified: {N}
+  Stale references: {N} (files missing or symbols removed)
+  Untracked symbols: {N} (new exports not in index)
+```
+
+If stale references found: warn and auto-fix during Phase 3 updates.
+If `--dry-run`: report only, no fixes.
+
 ## Phase 1: Change Detection
 
-### 0.1 Schema Version Check (TASK-006)
+### 1.0.1 Schema Version Check
 
-Before processing changes, verify doc-index schema compatibility:
+Before processing changes, verify doc-index.json schema compatibility:
 
 ```javascript
 const docIndex = JSON.parse(Read('.workflow/.doc-index/doc-index.json'));
@@ -201,6 +232,7 @@ For each affected component in `doc-index.json`:
 - Update `codeLocations` if file paths or line ranges changed
 - Update `symbols` if new exports were added
 - Add new `actionIds` entry
+- **Auto-update `responsibility`**: If symbols changed (new methods/exports added or removed), re-infer responsibility from current symbols list using Gemini analysis. This prevents stale descriptions (e.g., responsibility still says "登录、注册" after adding logout support)
 
 ### 3.2 Register New Components
 

.claude/commands/workflow/session/sync.md

@@ -65,11 +65,14 @@ Analyze context and produce two update payloads. Use LLM reasoning (current agen
 ```javascript
 // ── Guidelines extraction ──
 // Scan git diff + session for:
-//   - New patterns adopted → convention
-//   - Restrictions discovered → constraint
-//   - Surprises / gotchas → learning
+//   - Debugging experiences → bug
+//   - Reusable code patterns → pattern
+//   - Architecture/design decisions → decision
+//   - Conventions, constraints, insights → rule
 //
-// Output: array of { type, category, text }
+// Output: array of { type, tag, text }
+//   type: 'bug' | 'pattern' | 'decision' | 'rule'
+//   tag: domain tag (api, routing, schema, security, etc.)
 // RULE: Only extract genuinely reusable insights. Skip trivial/obvious items.
 // RULE: Deduplicate against existing guidelines before adding.
 
@@ -118,7 +121,7 @@ console.log(`
 ── Sync Preview ──
 
 Guidelines (${guidelineUpdates.length} items):
-${guidelineUpdates.map(g => `  [${g.type}/${g.category}] ${g.text}`).join('\n') || '  (none)'}
+${guidelineUpdates.map(g => `  [${g.type}:${g.tag}] ${g.text}`).join('\n') || '  (none)'}
 
 Tech [${detectCategory(summary)}]:
   ${techEntry.title}
@@ -137,26 +140,102 @@ if (!autoYes) {
 ## Step 4: Write
 
 ```javascript
-// ── Update specs/*.md ──
-// Uses .ccw/specs/ directory (same as frontend/backend spec-index-builder)
-if (guidelineUpdates.length > 0) {
-  // Map guideline types to spec files
-  const specFileMap = {
-    convention: '.ccw/specs/coding-conventions.md',
-    constraint: '.ccw/specs/architecture-constraints.md',
-    learning: '.ccw/specs/coding-conventions.md' // learnings appended to conventions
+const matter = require('gray-matter')  // YAML frontmatter parser
+
+// ── Frontmatter check & repair helper ──
+// Ensures target spec file has valid YAML frontmatter with keywords
+// Uses gray-matter for robust parsing (handles malformed frontmatter, missing fields)
+function ensureFrontmatter(filePath, tag, type) {
+  const titleMap = {
+    'coding-conventions': 'Coding Conventions',
+    'architecture-constraints': 'Architecture Constraints',
+    'learnings': 'Learnings',
+    'quality-rules': 'Quality Rules'
+  }
+  const basename = filePath.split('/').pop().replace('.md', '')
+  const title = titleMap[basename] || basename
+  const defaultFm = {
+    title,
+    readMode: 'optional',
+    priority: 'medium',
+    scope: 'project',
+    dimension: 'specs',
+    keywords: [tag, type]
   }
 
+  if (!file_exists(filePath)) {
+    // Case A: Create new file with frontmatter
+    Write(filePath, matter.stringify(`\n# ${title}\n\n`, defaultFm))
+    return
+  }
+
+  const raw = Read(filePath)
+  let parsed
+  try {
+    parsed = matter(raw)
+  } catch {
+    parsed = { data: {}, content: raw }
+  }
+
+  const hasFrontmatter = raw.trimStart().startsWith('---')
+
+  if (!hasFrontmatter) {
+    // Case B: File exists but no frontmatter → prepend
+    Write(filePath, matter.stringify(raw, defaultFm))
+    return
+  }
+
+  // Case C: Frontmatter exists → ensure keywords include current tag
+  const existingKeywords = parsed.data.keywords || []
+  const newKeywords = [...new Set([...existingKeywords, tag, type])]
+
+  if (newKeywords.length !== existingKeywords.length) {
+    parsed.data.keywords = newKeywords
+    Write(filePath, matter.stringify(parsed.content, parsed.data))
+  }
+}
+
+// ── Update specs/*.md ──
+// Uses .ccw/specs/ directory - unified [type:tag] entry format
+if (guidelineUpdates.length > 0) {
+  // Map knowledge types to spec files
+  const specFileMap = {
+    bug: '.ccw/specs/learnings.md',
+    pattern: '.ccw/specs/coding-conventions.md',
+    decision: '.ccw/specs/architecture-constraints.md',
+    rule: null // determined by content below
+  }
+
+  const date = new Date().toISOString().split('T')[0]
+  const needsDate = { bug: true, pattern: true, decision: true, rule: false }
+
   for (const g of guidelineUpdates) {
-    const targetFile = specFileMap[g.type]
+    // For rule type, route by content and tag
+    let targetFile = specFileMap[g.type]
+    if (!targetFile) {
+      const isQuality = /\b(test|coverage|lint|eslint|质量|测试覆盖|pre-commit|tsc|type.check)\b/i.test(g.text)
+        || ['testing', 'quality', 'lint'].includes(g.tag)
+      const isConstraint = /\b(禁止|no|never|must not|forbidden|不得|不允许)\b/i.test(g.text)
+      if (isQuality) {
+        targetFile = '.ccw/specs/quality-rules.md'
+      } else if (isConstraint) {
+        targetFile = '.ccw/specs/architecture-constraints.md'
+      } else {
+        targetFile = '.ccw/specs/coding-conventions.md'
+      }
+    }
+
+    // Ensure frontmatter exists and keywords are up-to-date
+    ensureFrontmatter(targetFile, g.tag, g.type)
+
     const existing = Read(targetFile)
-    const ruleText = g.type === 'learning'
-      ? `- [${g.category}] ${g.text} (learned: ${new Date().toISOString().split('T')[0]})`
-      : `- [${g.category}] ${g.text}`
+    const entryLine = needsDate[g.type]
+      ? `- [${g.type}:${g.tag}] ${g.text} (${date})`
+      : `- [${g.type}:${g.tag}] ${g.text}`
 
     // Deduplicate: skip if text already in file
     if (!existing.includes(g.text)) {
-      const newContent = existing.trimEnd() + '\n' + ruleText + '\n'
+      const newContent = existing.trimEnd() + '\n' + entryLine + '\n'
       Write(targetFile, newContent)
     }
   }
@@ -198,4 +277,5 @@ Write(techPath, JSON.stringify(tech, null, 2))
 ## Related Commands
 
 - `/workflow:spec:setup` - Initialize project with specs scaffold
-- `/workflow:spec:add` - Interactive wizard to create individual specs with scope selection
+- `/workflow:spec:add` - Add knowledge entries (bug/pattern/decision/rule) with unified [type:tag] format
+- `/workflow:spec:load` - Interactive spec loader with keyword/type/tag filtering

.claude/commands/workflow/spec/load.md

@@ -0,0 +1,392 @@
+---
+name: load
+description: Interactive spec loader - ask what user needs, then load relevant specs by keyword routing
+argument-hint: "[--all] [--type <bug|pattern|decision|rule>] [--tag <tag>] [\"keyword query\"]"
+examples:
+  - /workflow:spec:load
+  - /workflow:spec:load "api routing"
+  - /workflow:spec:load --type bug
+  - /workflow:spec:load --all
+  - /workflow:spec:load --tag security
+---
+
+# Spec Load Command (/workflow:spec:load)
+
+## Overview
+
+Interactive entry point for loading and browsing project specs. Asks the user what they need, then routes to the appropriate spec content based on keywords, type filters, or tag filters.
+
+**Design**: Menu-driven → keyword match → load & display. No file modifications.
+
+**Note**: This command may be called by other workflow commands. Upon completion, return immediately to continue the calling workflow.
+
+## Usage
+```bash
+/workflow:spec:load                    # Interactive menu
+/workflow:spec:load "api routing"      # Direct keyword search
+/workflow:spec:load --type bug         # Filter by knowledge type
+/workflow:spec:load --tag security     # Filter by domain tag
+/workflow:spec:load --all              # Load all specs
+```
+
+## Execution Process
+
+```
+Input Parsing:
+   ├─ Parse --all flag → loadAll = true | false
+   ├─ Parse --type (bug|pattern|decision|rule)
+   ├─ Parse --tag (domain tag)
+   └─ Parse keyword query (positional text)
+
+Decision:
+   ├─ --all → Load all specs (Path C)
+   ├─ --type or --tag or keyword → Direct filter (Path B)
+   └─ No args → Interactive menu (Path A)
+
+Path A: Interactive Menu
+   ├─ Step A1: Ask user intent
+   ├─ Step A2: Route to action
+   └─ Step A3: Display results
+
+Path B: Direct Filter
+   ├─ Step B1: Build filter from args
+   ├─ Step B2: Search specs
+   └─ Step B3: Display results
+
+Path C: Load All
+   └─ Display all spec contents
+
+Output:
+   └─ Formatted spec entries matching user query
+```
+
+## Implementation
+
+### Step 1: Parse Input
+
+```javascript
+const args = $ARGUMENTS
+const argsLower = args.toLowerCase()
+
+const loadAll = argsLower.includes('--all')
+const hasType = argsLower.includes('--type')
+const hasTag = argsLower.includes('--tag')
+
+let type = hasType ? args.match(/--type\s+(\w+)/i)?.[1]?.toLowerCase() : null
+let tag = hasTag ? args.match(/--tag\s+([\w-]+)/i)?.[1]?.toLowerCase() : null
+
+// Extract keyword query (everything that's not a flag)
+let keyword = args
+  .replace(/--type\s+\w+/gi, '')
+  .replace(/--tag\s+[\w-]+/gi, '')
+  .replace(/--all/gi, '')
+  .replace(/^["']|["']$/g, '')
+  .trim()
+
+// Validate type
+if (type && !['bug', 'pattern', 'decision', 'rule'].includes(type)) {
+  console.log("Invalid type. Use 'bug', 'pattern', 'decision', or 'rule'.")
+  return
+}
+```
+
+### Step 2: Determine Mode
+
+```javascript
+const useInteractive = !loadAll && !hasType && !hasTag && !keyword
+```
+
+### Path A: Interactive Menu
+
+```javascript
+if (useInteractive) {
+  const answer = AskUserQuestion({
+    questions: [{
+      question: "What specs would you like to load?",
+      header: "Action",
+      multiSelect: false,
+      options: [
+        {
+          label: "Browse all specs",
+          description: "Load and display all project spec entries"
+        },
+        {
+          label: "Search by keyword",
+          description: "Find specs matching a keyword (e.g., api, security, routing)"
+        },
+        {
+          label: "View bug experiences",
+          description: "Load all [bug:*] debugging experience entries"
+        },
+        {
+          label: "View code patterns",
+          description: "Load all [pattern:*] reusable code pattern entries"
+        }
+      ]
+    }]
+  })
+
+  const choice = answer.answers["Action"]
+
+  if (choice === "Browse all specs") {
+    loadAll = true
+  } else if (choice === "View bug experiences") {
+    type = "bug"
+  } else if (choice === "View code patterns") {
+    type = "pattern"
+  } else if (choice === "Search by keyword") {
+    // Ask for keyword
+    const kwAnswer = AskUserQuestion({
+      questions: [{
+        question: "Enter keyword(s) to search for:",
+        header: "Keyword",
+        multiSelect: false,
+        options: [
+          { label: "api", description: "API endpoints, HTTP, REST, routing" },
+          { label: "security", description: "Authentication, authorization, input validation" },
+          { label: "arch", description: "Architecture, design patterns, module structure" },
+          { label: "perf", description: "Performance, caching, optimization" }
+        ]
+      }]
+    })
+    keyword = kwAnswer.answers["Keyword"].toLowerCase()
+  } else {
+    // "Other" — user typed custom input, use as keyword
+    keyword = choice.toLowerCase()
+  }
+}
+```
+
+### Step 3: Load Spec Files
+
+```javascript
+// Discover all spec files
+const specFiles = [
+  '.ccw/specs/coding-conventions.md',
+  '.ccw/specs/architecture-constraints.md',
+  '.ccw/specs/learnings.md',
+  '.ccw/specs/quality-rules.md'
+]
+
+// Also check personal specs
+const personalFiles = [
+  '~/.ccw/personal/conventions.md',
+  '~/.ccw/personal/constraints.md',
+  '~/.ccw/personal/learnings.md',
+  '.ccw/personal/conventions.md',
+  '.ccw/personal/constraints.md',
+  '.ccw/personal/learnings.md'
+]
+
+// Read all existing spec files
+const allEntries = []
+
+for (const file of [...specFiles, ...personalFiles]) {
+  if (!file_exists(file)) continue
+  const content = Read(file)
+
+  // Extract entries using unified format regex
+  // Entry line: - [type:tag] summary (date)
+  // Extended:       - key: value
+  const lines = content.split('\n')
+  let currentEntry = null
+
+  for (const line of lines) {
+    const entryMatch = line.match(/^- \[(\w+):([\w-]+)\] (.*?)(?:\s+\((\d{4}-\d{2}-\d{2})\))?$/)
+    if (entryMatch) {
+      if (currentEntry) allEntries.push(currentEntry)
+      currentEntry = {
+        type: entryMatch[1],
+        tag: entryMatch[2],
+        summary: entryMatch[3],
+        date: entryMatch[4] || null,
+        extended: {},
+        source: file,
+        raw: line
+      }
+    } else if (currentEntry && /^\s{4}- ([\w-]+):\s?(.*)/.test(line)) {
+      const fieldMatch = line.match(/^\s{4}- ([\w-]+):\s?(.*)/)
+      currentEntry.extended[fieldMatch[1]] = fieldMatch[2]
+    } else if (currentEntry && !/^\s{4}/.test(line) && line.trim() !== '') {
+      // Non-indented non-empty line = end of current entry
+      allEntries.push(currentEntry)
+      currentEntry = null
+    }
+
+    // Also handle legacy format: - [tag] text (learned: date)
+    const legacyMatch = line.match(/^- \[([\w-]+)\] (.+?)(?:\s+\(learned: (\d{4}-\d{2}-\d{2})\))?$/)
+    if (!entryMatch && legacyMatch) {
+      if (currentEntry) allEntries.push(currentEntry)
+      currentEntry = {
+        type: 'rule',
+        tag: legacyMatch[1],
+        summary: legacyMatch[2],
+        date: legacyMatch[3] || null,
+        extended: {},
+        source: file,
+        raw: line,
+        legacy: true
+      }
+    }
+  }
+  if (currentEntry) allEntries.push(currentEntry)
+}
+```
+
+### Step 4: Filter Entries
+
+```javascript
+let filtered = allEntries
+
+// Filter by type
+if (type) {
+  filtered = filtered.filter(e => e.type === type)
+}
+
+// Filter by tag
+if (tag) {
+  filtered = filtered.filter(e => e.tag === tag)
+}
+
+// Filter by keyword (search in tag, summary, and extended fields)
+if (keyword) {
+  const kw = keyword.toLowerCase()
+  const kwTerms = kw.split(/\s+/)
+
+  filtered = filtered.filter(e => {
+    const searchText = [
+      e.type, e.tag, e.summary,
+      ...Object.values(e.extended)
+    ].join(' ').toLowerCase()
+
+    return kwTerms.every(term => searchText.includes(term))
+  })
+}
+
+// If --all, keep everything (no filter)
+```
+
+### Step 5: Display Results
+
+```javascript
+if (filtered.length === 0) {
+  const filterDesc = []
+  if (type) filterDesc.push(`type=${type}`)
+  if (tag) filterDesc.push(`tag=${tag}`)
+  if (keyword) filterDesc.push(`keyword="${keyword}"`)
+
+  console.log(`
+No specs found matching: ${filterDesc.join(', ') || '(all)'}
+
+Available spec files:
+${specFiles.filter(f => file_exists(f)).map(f => `  - ${f}`).join('\n') || '  (none)'}
+
+Suggestions:
+- Use /workflow:spec:setup to initialize specs
+- Use /workflow:spec:add to add new entries
+- Use /workflow:spec:load --all to see everything
+`)
+  return
+}
+
+// Group by source file
+const grouped = {}
+for (const entry of filtered) {
+  if (!grouped[entry.source]) grouped[entry.source] = []
+  grouped[entry.source].push(entry)
+}
+
+// Display
+console.log(`
+## Specs Loaded (${filtered.length} entries)
+${type ? `Type: ${type}` : ''}${tag ? ` Tag: ${tag}` : ''}${keyword ? ` Keyword: "${keyword}"` : ''}
+`)
+
+for (const [source, entries] of Object.entries(grouped)) {
+  console.log(`### ${source}`)
+  console.log('')
+
+  for (const entry of entries) {
+    // Render entry
+    const datePart = entry.date ? ` (${entry.date})` : ''
+    console.log(`- [${entry.type}:${entry.tag}] ${entry.summary}${datePart}`)
+
+    // Render extended fields
+    for (const [key, value] of Object.entries(entry.extended)) {
+      console.log(`    - ${key}: ${value}`)
+    }
+  }
+  console.log('')
+}
+
+// Summary footer
+const typeCounts = {}
+for (const e of filtered) {
+  typeCounts[e.type] = (typeCounts[e.type] || 0) + 1
+}
+const typeBreakdown = Object.entries(typeCounts)
+  .map(([t, c]) => `${t}: ${c}`)
+  .join(', ')
+
+console.log(`---`)
+console.log(`Total: ${filtered.length} entries (${typeBreakdown})`)
+console.log(`Sources: ${Object.keys(grouped).join(', ')}`)
+```
+
+## Examples
+
+### Interactive Browse
+```bash
+/workflow:spec:load
+# → Menu: "What specs would you like to load?"
+# → User selects "Browse all specs"
+# → Displays all entries grouped by file
+```
+
+### Keyword Search
+```bash
+/workflow:spec:load "api routing"
+# → Filters entries where tag/summary/extended contains "api" AND "routing"
+# → Displays matching entries
+```
+
+### Type Filter
+```bash
+/workflow:spec:load --type bug
+# → Shows all [bug:*] entries from learnings.md
+```
+
+### Tag Filter
+```bash
+/workflow:spec:load --tag security
+# → Shows all [*:security] entries across all spec files
+```
+
+### Combined Filters
+```bash
+/workflow:spec:load --type rule --tag api
+# → Shows all [rule:api] entries
+```
+
+### Load All
+```bash
+/workflow:spec:load --all
+# → Displays every entry from every spec file
+```
+
+## Error Handling
+
+| Error | Resolution |
+|-------|------------|
+| No spec files found | Suggest `/workflow:spec:setup` to initialize |
+| No matching entries | Show available files and suggest alternatives |
+| Invalid type | Exit with valid type list |
+| Corrupt entry format | Skip unparseable lines, continue loading |
+
+## Related Commands
+
+- `/workflow:spec:setup` - Initialize project with specs scaffold
+- `/workflow:spec:add` - Add knowledge entries (bug/pattern/decision/rule) with unified [type:tag] format
+- `/workflow:session:sync` - Quick-sync session work to specs and project-tech
+- `ccw spec list` - View spec file index
+- `ccw spec load` - CLI-level spec loading (used by hooks)

.claude/commands/workflow/spec/setup.md

@@ -471,70 +471,129 @@ For each category of collected answers, append rules to the corresponding spec M
 - Round 5 (quality): `category: execution` (testing phase)
 
 ```javascript
+const matter = require('gray-matter')  // YAML frontmatter parser
+
+// ── Frontmatter check & repair helper ──
+// Ensures target spec file has valid YAML frontmatter with keywords
+// Uses gray-matter for robust parsing (handles malformed frontmatter, missing fields)
+function ensureSpecFrontmatter(filePath, extraKeywords = []) {
+  const titleMap = {
+    'coding-conventions': 'Coding Conventions',
+    'architecture-constraints': 'Architecture Constraints',
+    'learnings': 'Learnings',
+    'quality-rules': 'Quality Rules'
+  }
+  const basename = filePath.split('/').pop().replace('.md', '')
+  const title = titleMap[basename] || basename
+  const defaultKw = filePath.includes('conventions') ? 'convention'
+    : filePath.includes('constraints') ? 'constraint' : 'quality'
+  const defaultFm = {
+    title,
+    readMode: 'optional',
+    priority: 'medium',
+    category: 'general',
+    scope: 'project',
+    dimension: 'specs',
+    keywords: [...new Set([defaultKw, ...extraKeywords])]
+  }
+
+  if (!file_exists(filePath)) {
+    // Case A: Create new file with frontmatter
+    const specDir = path.dirname(filePath)
+    if (!fs.existsSync(specDir)) {
+      fs.mkdirSync(specDir, { recursive: true })
+    }
+    Write(filePath, matter.stringify(`\n# ${title}\n\n`, defaultFm))
+    return
+  }
+
+  const raw = Read(filePath)
+  let parsed
+  try {
+    parsed = matter(raw)
+  } catch {
+    parsed = { data: {}, content: raw }
+  }
+
+  const hasFrontmatter = raw.trimStart().startsWith('---')
+
+  if (!hasFrontmatter) {
+    // Case B: File exists but no frontmatter → prepend
+    Write(filePath, matter.stringify(raw, defaultFm))
+    return
+  }
+
+  // Case C: Frontmatter exists → ensure keywords include extras
+  const existingKeywords = parsed.data.keywords || []
+  const newKeywords = [...new Set([...existingKeywords, defaultKw, ...extraKeywords])]
+
+  if (newKeywords.length !== existingKeywords.length) {
+    parsed.data.keywords = newKeywords
+    Write(filePath, matter.stringify(parsed.content, parsed.data))
+  }
+}
+
 // Helper: append rules to a spec MD file with category support
 // Uses .ccw/specs/ directory (same as frontend/backend spec-index-builder)
 function appendRulesToSpecFile(filePath, rules, defaultCategory = 'general') {
   if (rules.length === 0) return
 
-  // Ensure .ccw/specs/ directory exists
-  const specDir = path.dirname(filePath)
-  if (!fs.existsSync(specDir)) {
-    fs.mkdirSync(specDir, { recursive: true })
-  }
+  // Extract domain tags from rules for keyword accumulation
+  const ruleTags = rules
+    .map(r => r.match(/\[[\w]+:([\w-]+)\]/)?.[1])
+    .filter(Boolean)
 
-  // Check if file exists
-  if (!file_exists(filePath)) {
-    // Create file with frontmatter including category
-    const frontmatter = `---
-title: ${filePath.includes('conventions') ? 'Coding Conventions' : filePath.includes('constraints') ? 'Architecture Constraints' : 'Quality Rules'}
-readMode: optional
-priority: medium
-category: ${defaultCategory}
-scope: project
-dimension: specs
-keywords: [${defaultCategory}, ${filePath.includes('conventions') ? 'convention' : filePath.includes('constraints') ? 'constraint' : 'quality'}]
----
-
-# ${filePath.includes('conventions') ? 'Coding Conventions' : filePath.includes('constraints') ? 'Architecture Constraints' : 'Quality Rules'}
-
-`
-    Write(filePath, frontmatter)
-  }
+  // Ensure frontmatter exists and keywords include rule tags
+  ensureSpecFrontmatter(filePath, [...new Set(ruleTags)])
 
   const existing = Read(filePath)
-  // Append new rules as markdown list items after existing content
-  const newContent = existing.trimEnd() + '\n' + rules.map(r => `- ${r}`).join('\n') + '\n'
+  // Append new rules as markdown list items - rules are already in [type:tag] format from caller
+  const newContent = existing.trimEnd() + '\n' + rules.map(r => {
+    // If rule already has - prefix or [type:tag] format, use as-is
+    if (/^- /.test(r)) return r
+    if (/^\[[\w]+:[\w-]+\]/.test(r)) return `- ${r}`
+    return `- [rule:${defaultCategory}] ${r}`
+  }).join('\n') + '\n'
   Write(filePath, newContent)
 }
 
-// Write conventions (general category) - use .ccw/specs/ (same as frontend/backend)
-appendRulesToSpecFile('.ccw/specs/coding-conventions.md',
-  [...newCodingStyle, ...newNamingPatterns, ...newFileStructure, ...newDocumentation],
-  'general')
+// Helper: infer domain tag from rule content
+function inferTag(text) {
+  const t = text.toLowerCase()
+  if (/\b(api|http|rest|endpoint|routing)\b/.test(t)) return 'api'
+  if (/\b(security|auth|permission|xss|sql|sanitize)\b/.test(t)) return 'security'
+  if (/\b(database|db|sql|postgres|mysql)\b/.test(t)) return 'db'
+  if (/\b(react|component|hook|jsx|tsx)\b/.test(t)) return 'react'
+  if (/\b(performance|cache|lazy|async|slow)\b/.test(t)) return 'perf'
+  if (/\b(test|coverage|mock|jest|vitest)\b/.test(t)) return 'testing'
+  if (/\b(architecture|layer|module|dependency)\b/.test(t)) return 'arch'
+  if (/\b(naming|camel|pascal|prefix|suffix)\b/.test(t)) return 'naming'
+  if (/\b(file|folder|directory|structure)\b/.test(t)) return 'file'
+  if (/\b(doc|comment|jsdoc|readme)\b/.test(t)) return 'doc'
+  if (/\b(build|webpack|vite|compile)\b/.test(t)) return 'build'
+  if (/\b(deploy|ci|cd|docker)\b/.test(t)) return 'deploy'
+  if (/\b(lint|eslint|prettier|format)\b/.test(t)) return 'lint'
+  if (/\b(type|typescript|strict|any)\b/.test(t)) return 'typing'
+  return 'style' // fallback for coding conventions
+}
 
-// Write constraints (planning category)
+// Write conventions - infer domain tags from content
+appendRulesToSpecFile('.ccw/specs/coding-conventions.md',
+  [...newCodingStyle, ...newNamingPatterns, ...newFileStructure, ...newDocumentation]
+    .map(r => /^\[[\w]+:[\w-]+\]/.test(r) ? r : `[rule:${inferTag(r)}] ${r}`),
+  'style')
+
+// Write constraints - infer domain tags from content
 appendRulesToSpecFile('.ccw/specs/architecture-constraints.md',
-  [...newArchitecture, ...newTechStack, ...newPerformance, ...newSecurity],
-  'planning')
+  [...newArchitecture, ...newTechStack, ...newPerformance, ...newSecurity]
+    .map(r => /^\[[\w]+:[\w-]+\]/.test(r) ? r : `[rule:${inferTag(r)}] ${r}`),
+  'arch')
 
 // Write quality rules (execution category)
 if (newQualityRules.length > 0) {
   const qualityPath = '.ccw/specs/quality-rules.md'
-  if (!file_exists(qualityPath)) {
-    Write(qualityPath, `---
-title: Quality Rules
-readMode: required
-priority: high
-category: execution
-scope: project
-dimension: specs
-keywords: [execution, quality, testing, coverage, lint]
----
-
-# Quality Rules
-
-`)
-  }
+  // ensureSpecFrontmatter handles create/repair/keyword-update
+  ensureSpecFrontmatter(qualityPath, ['quality', 'testing', 'coverage', 'lint'])
   appendRulesToSpecFile(qualityPath,
     newQualityRules.map(q => `${q.rule} (scope: ${q.scope}, enforced by: ${q.enforced_by})`),
     'execution')
@@ -644,7 +703,8 @@ Next steps:
 
 ## Related Commands
 
-- `/workflow:spec:add` - Interactive wizard to create individual specs with scope selection
+- `/workflow:spec:add` - Add knowledge entries (bug/pattern/decision/rule) with unified [type:tag] format
+- `/workflow:spec:load` - Interactive spec loader with keyword/type/tag filtering
 - `/workflow:session:sync` - Quick-sync session work to specs and project-tech
 - `workflow-plan` skill - Start planning with initialized project context
 - `/workflow:status --project` - View project state and guidelines

.claude/skills/team-arch-opt/SKILL.md

@@ -66,7 +66,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-arch-opt/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-arch-opt/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: arch-opt

.claude/skills/team-arch-opt/roles/coordinator/commands/monitor.md

@@ -95,7 +95,7 @@ Find ready tasks, spawn workers, STOP.
         run_in_background: true,
         prompt: `## Role Assignment
       role: <role>
-      role_spec: .claude/skills/team-arch-opt/roles/<role>/role.md
+      role_spec: ~  or <project>/.claude/skills/team-arch-opt/roles/<role>/role.md
       session: <session-folder>
       session_id: <session-id>
       team_name: arch-opt

.claude/skills/team-arch-opt/specs/team-config.json

@@ -3,7 +3,7 @@
   "team_name": "arch-opt",
   "team_display_name": "Architecture Optimization",
   "skill_name": "team-arch-opt",
-  "skill_path": ".claude/skills/team-arch-opt/",
+  "skill_path": "~  or <project>/.claude/skills/team-arch-opt/",
   "pipeline_type": "Linear with Review-Fix Cycle (Parallel-Capable)",
   "completion_action": "interactive",
   "has_inline_discuss": true,

.claude/skills/team-brainstorm/SKILL.md

@@ -65,7 +65,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-brainstorm/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-brainstorm/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: brainstorm
@@ -89,7 +89,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: ideator
-role_spec: .claude/skills/team-brainstorm/roles/ideator/role.md
+role_spec: ~  or <project>/.claude/skills/team-brainstorm/roles/ideator/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: brainstorm

.claude/skills/team-brainstorm/roles/coordinator/commands/monitor.md

@@ -91,7 +91,7 @@ Find ready tasks, spawn workers, STOP.
         run_in_background: true,
         prompt: `## Role Assignment
       role: <role>
-      role_spec: .claude/skills/team-brainstorm/roles/<role>/role.md
+      role_spec: ~  or <project>/.claude/skills/team-brainstorm/roles/<role>/role.md
       session: <session-folder>
       session_id: <session-id>
       team_name: brainstorm

.claude/skills/team-coordinate/SKILL.md

@@ -32,6 +32,18 @@ Universal team coordination skill: analyze task -> generate role-specs -> dispat
     ccw cli --mode write     - code generation and modification
 ```
 
+## Shared Constants
+
+| Constant | Value |
+|----------|-------|
+| Session prefix | `TC` |
+| Session path | `.workflow/.team/TC-<slug>-<date>/` |
+| Worker agent | `team-worker` |
+| Message bus | `mcp__ccw-tools__team_msg(session_id=<session-id>, ...)` |
+| CLI analysis | `ccw cli --mode analysis` |
+| CLI write | `ccw cli --mode write` |
+| Max roles | 5 |
+
 ## Role Router
 
 This skill is **coordinator-only**. Workers do NOT invoke this skill -- they are spawned as `team-worker` agents directly.
@@ -85,6 +97,9 @@ User provides task description
 |---------|--------|
 | `check` / `status` | Output execution status graph, no advancement |
 | `resume` / `continue` | Check worker states, advance next step |
+| `revise <TASK-ID> [feedback]` | Revise specific task with optional feedback |
+| `feedback <text>` | Inject feedback into active pipeline |
+| `improve [dimension]` | Auto-improve weakest quality dimension |
 
 ---
 
@@ -150,6 +165,17 @@ AskUserQuestion({
 
 ---
 
+## Specs Reference
+
+| Spec | Purpose |
+|------|---------|
+| [specs/pipelines.md](specs/pipelines.md) | Dynamic pipeline model, task naming, dependency graph |
+| [specs/role-spec-template.md](specs/role-spec-template.md) | Template for dynamic role-spec generation |
+| [specs/quality-gates.md](specs/quality-gates.md) | Quality thresholds and scoring dimensions |
+| [specs/knowledge-transfer.md](specs/knowledge-transfer.md) | Context transfer protocols between roles |
+
+---
+
 ## Session Directory
 
 ```

.claude/skills/team-coordinate/roles/coordinator/commands/analyze-task.md

@@ -16,6 +16,20 @@ Parse user task description -> detect required capabilities -> build dependency
 
 If task context requires codebase knowledge, set `needs_research: true`. Phase 2 will spawn researcher worker.
 
+## When to Use
+
+| Trigger | Condition |
+|---------|-----------|
+| New task | Coordinator Phase 1 receives task description |
+| Re-analysis | User provides revised requirements |
+| Adapt | handleAdapt extends analysis for new capability |
+
+## Strategy
+
+- **Delegation**: Inline execution (coordinator processes directly)
+- **Mode**: Text-level analysis only (no codebase reading)
+- **Output**: `<session>/task-analysis.json`
+
 ## Phase 2: Context Loading
 
 | Input | Source | Required |

.claude/skills/team-coordinate/roles/coordinator/commands/dispatch.md

@@ -4,6 +4,20 @@
 
 Create task chains from dynamic dependency graphs. Builds pipelines from the task-analysis.json produced by Phase 1. Workers are spawned as team-worker agents with role-spec paths.
 
+## When to Use
+
+| Trigger | Condition |
+|---------|-----------|
+| After analysis | Phase 1 complete, task-analysis.json exists |
+| After adapt | handleAdapt created new roles, needs new tasks |
+| Re-dispatch | Pipeline restructuring (rare) |
+
+## Strategy
+
+- **Delegation**: Inline execution (coordinator processes directly)
+- **Inputs**: task-analysis.json + team-session.json
+- **Output**: TaskCreate calls with dependency chains
+
 ## Phase 2: Context Loading
 
 | Input | Source | Required |

.claude/skills/team-coordinate/roles/coordinator/commands/monitor.md

@@ -4,6 +4,22 @@
 
 Event-driven pipeline coordination with Spawn-and-Stop pattern. Role names are read from `team-session.json#roles`. Workers are spawned as `team-worker` agents with role-spec paths. Includes `handleComplete` for pipeline completion action and `handleAdapt` for mid-pipeline capability gap handling.
 
+## When to Use
+
+| Trigger | Condition |
+|---------|-----------|
+| Worker callback | Message contains [role-name] from session roles |
+| User command | "check", "status", "resume", "continue" |
+| Capability gap | Worker reports capability_gap |
+| Pipeline spawn | After dispatch, initial spawn needed |
+| Pipeline complete | All tasks done |
+
+## Strategy
+
+- **Delegation**: Inline execution with handler routing
+- **Beat model**: ONE_STEP_PER_INVOCATION — one handler then STOP
+- **Workers**: Spawned as team-worker via Agent() in background
+
 ## Constants
 
 | Constant | Value | Description |

.claude/skills/team-coordinate/roles/coordinator/role.md

@@ -1,3 +1,7 @@
+---
+role: coordinator
+---
+
 # Coordinator Role
 
 Orchestrate the team-coordinate workflow: task analysis, dynamic role-spec generation, task dispatching, progress monitoring, session state, and completion action. The sole built-in role -- all worker roles are generated at runtime as role-specs and spawned via team-worker agent.
@@ -33,6 +37,30 @@ Orchestrate the team-coordinate workflow: task analysis, dynamic role-spec gener
 
 ---
 
+## Message Types
+
+| Type | Direction | Trigger |
+|------|-----------|---------|
+| state_update | outbound | Session init, pipeline progress |
+| task_unblocked | outbound | Task ready for execution |
+| fast_advance | inbound | Worker skipped coordinator |
+| capability_gap | inbound | Worker needs new capability |
+| error | inbound | Worker failure |
+| impl_complete | inbound | Worker task done |
+| consensus_blocked | inbound | Discussion verdict conflict |
+
+## Message Bus Protocol
+
+All coordinator state changes MUST be logged to team_msg BEFORE SendMessage:
+
+1. `team_msg(operation="log", ...)` — log the event
+2. `SendMessage(...)` — communicate to worker/user
+3. `TaskUpdate(...)` — update task state
+
+Read state before every handler: `team_msg(operation="get_state", session_id=<session-id>)`
+
+---
+
 ## Command Execution Protocol
 
 When coordinator needs to execute a command (analyze-task, dispatch, monitor):
@@ -52,6 +80,20 @@ Phase 1 needs task analysis
   -> Continue to Phase 2
 ```
 
+## Toolbox
+
+| Tool | Type | Purpose |
+|------|------|---------|
+| commands/analyze-task.md | Command | Task analysis and role design |
+| commands/dispatch.md | Command | Task chain creation |
+| commands/monitor.md | Command | Pipeline monitoring and handlers |
+| team-worker | Subagent | Worker spawning |
+| TeamCreate / TeamDelete | System | Team lifecycle |
+| TaskCreate / TaskList / TaskGet / TaskUpdate | System | Task lifecycle |
+| team_msg | System | Message bus operations |
+| SendMessage | System | Inter-agent communication |
+| AskUserQuestion | System | User interaction |
+
 ---
 
 ## Entry Router

.claude/skills/team-coordinate/specs/knowledge-transfer.md

@@ -0,0 +1,111 @@
+# Knowledge Transfer Protocols
+
+## 1. Transfer Channels
+
+| Channel | Scope | Mechanism | When to Use |
+|---------|-------|-----------|-------------|
+| **Artifacts** | Producer -> Consumer | Write to `<session>/artifacts/<name>.md`, consumer reads in Phase 2 | Structured deliverables (reports, plans, specs) |
+| **State Updates** | Cross-role | `team_msg(operation="log", type="state_update", data={...})` / `team_msg(operation="get_state", session_id=<session-id>)` | Key findings, decisions, metadata (small, structured data) |
+| **Wisdom** | Cross-task | Append to `<session>/wisdom/{learnings,decisions,conventions,issues}.md` | Patterns, conventions, risks discovered during execution |
+| **Context Accumulator** | Intra-role (inner loop) | In-memory array, passed to each subsequent task in same-prefix loop | Prior task summaries within same role's inner loop |
+| **Exploration Cache** | Cross-role | `<session>/explorations/cache-index.json` + per-angle JSON | Codebase discovery results, prevents duplicate exploration |
+
+## 2. Context Loading Protocol (Phase 2)
+
+Every role MUST load context in this order before starting work.
+
+| Step | Action | Required |
+|------|--------|----------|
+| 1 | Extract session path from task description | Yes |
+| 2 | `team_msg(operation="get_state", session_id=<session-id>)` | Yes |
+| 3 | Read artifact files from upstream state's `ref` paths | Yes |
+| 4 | Read `<session>/wisdom/*.md` if exists | Yes |
+| 5 | Check `<session>/explorations/cache-index.json` before new exploration | If exploring |
+| 6 | For inner_loop roles: load context_accumulator from prior tasks | If inner_loop |
+
+**Loading rules**:
+- Never skip step 2 -- state contains key decisions and findings
+- If `ref` path in state does not exist, log warning and continue
+- Wisdom files are append-only -- read all entries, newest last
+
+## 3. Context Publishing Protocol (Phase 4)
+
+| Step | Action | Required |
+|------|--------|----------|
+| 1 | Write deliverable to `<session>/artifacts/<task-id>-<name>.md` | Yes |
+| 2 | Send `team_msg(type="state_update")` with payload (see schema below) | Yes |
+| 3 | Append wisdom entries for learnings, decisions, issues found | If applicable |
+
+## 4. State Update Schema
+
+Sent via `team_msg(type="state_update")` on task completion.
+
+```json
+{
+  "status": "task_complete",
+  "task_id": "<TASK-NNN>",
+  "ref": "<session>/artifacts/<filename>",
+  "key_findings": [
+    "Finding 1",
+    "Finding 2"
+  ],
+  "decisions": [
+    "Decision with rationale"
+  ],
+  "files_modified": [
+    "path/to/file.ts"
+  ],
+  "verification": "self-validated | peer-reviewed | tested"
+}
+```
+
+**Field rules**:
+- `ref`: Always an artifact path, never inline content
+- `key_findings`: Max 5 items, each under 100 chars
+- `decisions`: Include rationale, not just the choice
+- `files_modified`: Only for implementation tasks
+- `verification`: One of `self-validated`, `peer-reviewed`, `tested`
+
+**Write state** (namespaced by role):
+```
+team_msg(operation="log", session_id=<session-id>, from=<role>, type="state_update", data={
+  "<role_name>": { "key_findings": [...], "scope": "..." }
+})
+```
+
+**Read state**:
+```
+team_msg(operation="get_state", session_id=<session-id>)
+// Returns merged state from all state_update messages
+```
+
+## 5. Exploration Cache Protocol
+
+Prevents redundant research across tasks and discussion rounds.
+
+| Step | Action |
+|------|--------|
+| 1 | Read `<session>/explorations/cache-index.json` |
+| 2 | If angle already explored, read cached result from `explore-<angle>.json` |
+| 3 | If not cached, perform exploration |
+| 4 | Write result to `<session>/explorations/explore-<angle>.json` |
+| 5 | Update `cache-index.json` with new entry |
+
+**cache-index.json format**:
+```json
+{
+  "entries": [
+    {
+      "angle": "competitor-analysis",
+      "file": "explore-competitor-analysis.json",
+      "created_by": "RESEARCH-001",
+      "timestamp": "2026-01-15T10:30:00Z"
+    }
+  ]
+}
+```
+
+**Rules**:
+- Cache key is the exploration `angle` (normalized to kebab-case)
+- Cache entries never expire within a session
+- Any role can read cached explorations; only the creator updates them

.claude/skills/team-coordinate/specs/pipelines.md

@@ -81,3 +81,17 @@ message_types:
 ## Specs Reference
 
 - [role-spec-template.md](role-spec-template.md) — Template for generating dynamic role-specs
+- [quality-gates.md](quality-gates.md) — Quality thresholds and scoring dimensions
+- [knowledge-transfer.md](knowledge-transfer.md) — Context transfer protocols between roles
+
+## Quality Gate Integration
+
+Dynamic pipelines reference quality thresholds from [specs/quality-gates.md](quality-gates.md).
+
+| Gate Point | Trigger | Criteria Source |
+|------------|---------|----------------|
+| After artifact production | Producer role Phase 4 | Behavioral Traits in role-spec |
+| After validation tasks | Tester/analyst completion | quality-gates.md thresholds |
+| Pipeline completion | All tasks done | Aggregate scoring |
+
+Issue classification: Error (blocks) > Warning (proceed with justification) > Info (log for future).

.claude/skills/team-coordinate/specs/quality-gates.md

@@ -0,0 +1,112 @@
+# Quality Gates
+
+## 1. Quality Thresholds
+
+| Result | Score | Action |
+|--------|-------|--------|
+| Pass | >= 80% | Report completed |
+| Review | 60-79% | Report completed with warnings |
+| Fail | < 60% | Retry Phase 3 (max 2 retries) |
+
+## 2. Scoring Dimensions
+
+| Dimension | Weight | Criteria |
+|-----------|--------|----------|
+| Completeness | 25% | All required outputs present with substantive content |
+| Consistency | 25% | Terminology, formatting, cross-references are uniform |
+| Accuracy | 25% | Outputs are factually correct and verifiable against sources |
+| Depth | 25% | Sufficient detail for downstream consumers to act on deliverables |
+
+**Score** = weighted average of all dimensions (0-100 per dimension).
+
+## 3. Dynamic Role Quality Checks
+
+Quality checks vary by `output_type` (from task-analysis.json role metadata).
+
+### output_type: artifact
+
+| Check | Pass Criteria |
+|-------|---------------|
+| Artifact exists | File written to `<session>/artifacts/` |
+| Content non-empty | Substantive content, not just headers |
+| Format correct | Expected format (MD, JSON) matches deliverable |
+| Cross-references | All references to upstream artifacts resolve |
+
+### output_type: codebase
+
+| Check | Pass Criteria |
+|-------|---------------|
+| Files modified | Claimed files actually changed (Read to confirm) |
+| Syntax valid | No syntax errors in modified files |
+| No regressions | Existing functionality preserved |
+| Summary artifact | Implementation summary written to artifacts/ |
+
+### output_type: mixed
+
+All checks from both `artifact` and `codebase` apply.
+
+## 4. Verification Protocol
+
+Derived from Behavioral Traits in [role-spec-template.md](role-spec-template.md).
+
+| Step | Action | Required |
+|------|--------|----------|
+| 1 | Verify all claimed files exist via Read | Yes |
+| 2 | Confirm artifact written to `<session>/artifacts/` | Yes |
+| 3 | Check verification summary fields present | Yes |
+| 4 | Score against quality dimensions | Yes |
+| 5 | Apply threshold -> Pass/Review/Fail | Yes |
+
+**On Fail**: Retry Phase 3 (max 2 retries). After 2 retries, report `partial_completion`.
+
+**On Review**: Proceed with warnings logged to `<session>/wisdom/issues.md`.
+
+## 5. Code Review Dimensions
+
+For REVIEW-* or validation tasks during implementation pipelines.
+
+### Quality
+
+| Check | Severity |
+|-------|----------|
+| Empty catch blocks | Error |
+| `as any` type casts | Warning |
+| `@ts-ignore` / `@ts-expect-error` | Warning |
+| `console.log` in production code | Warning |
+| Unused imports/variables | Info |
+
+### Security
+
+| Check | Severity |
+|-------|----------|
+| Hardcoded secrets/credentials | Error |
+| SQL injection vectors | Error |
+| `eval()` or `Function()` usage | Error |
+| `innerHTML` assignment | Warning |
+| Missing input validation | Warning |
+
+### Architecture
+
+| Check | Severity |
+|-------|----------|
+| Circular dependencies | Error |
+| Deep cross-boundary imports (3+ levels) | Warning |
+| Files > 500 lines | Warning |
+| Functions > 50 lines | Info |
+
+### Requirements Coverage
+
+| Check | Severity |
+|-------|----------|
+| Core functionality implemented | Error if missing |
+| Acceptance criteria covered | Error if missing |
+| Edge cases handled | Warning |
+| Error states handled | Warning |
+
+## 6. Issue Classification
+
+| Class | Label | Action |
+|-------|-------|--------|
+| Error | Must fix | Blocks progression, must resolve before proceeding |
+| Warning | Should fix | Should resolve, can proceed with justification |
+| Info | Nice to have | Optional improvement, log for future |

.claude/skills/team-coordinate/specs/role-spec-template.md

@@ -46,6 +46,7 @@ message_types:
 | `prefix` | Yes | Task prefix to filter (e.g., RESEARCH, DRAFT, IMPL) |
 | `inner_loop` | Yes | Whether team-worker loops through same-prefix tasks |
 | `CLI tools` | No | Array of CLI tool types this role may call |
+| `output_tag` | Yes | Output tag for all messages, e.g., `[researcher]` |
 | `message_types` | Yes | Message type mapping for team_msg |
 | `message_types.success` | Yes | Type string for successful completion |
 | `message_types.error` | Yes | Type string for errors (usually "error") |
@@ -63,6 +64,29 @@ message_types:
 | `<placeholder>` notation | Use angle brackets for variable substitution |
 | Reference CLI tools by name | team-worker resolves invocation from its delegation templates |
 
+## Generated Role-Spec Structure
+
+Every generated role-spec MUST include these blocks:
+
+### Identity Block (mandatory — first section of generated spec)
+
+```
+Tag: [<role_name>] | Prefix: <PREFIX>-*
+Responsibility: <one-line from task analysis>
+```
+
+### Boundaries Block (mandatory — after Identity)
+
+```
+### MUST
+- <3-5 rules derived from task analysis>
+
+### MUST NOT
+- Execute work outside assigned prefix
+- Modify artifacts from other roles
+- Skip Phase 4 verification
+```
+
 ## Behavioral Traits
 
 All dynamically generated role-specs MUST embed these traits into Phase 4. Coordinator copies this section verbatim into every generated role-spec as a Phase 4 appendix.
@@ -93,6 +117,11 @@ Phase 4 must produce a verification summary with these fields:
 - Still fails → report `partial_completion` with details, NOT `completed`
 - Update shared state via `team_msg(operation="log", type="state_update", data={...})` after verification passes
 
+Quality thresholds from [specs/quality-gates.md](quality-gates.md):
+- Pass >= 80%: report completed
+- Review 60-79%: report completed with warnings
+- Fail < 60%: retry Phase 3 (max 2)
+
 ### Error Protocol
 
 - Primary approach fails → try alternative (different CLI tool / different tool)
@@ -139,48 +168,25 @@ Coordinator MAY reference these patterns when composing Phase 2-4 content for a
 
 ## Knowledge Transfer Protocol
 
-How context flows between roles. Coordinator MUST reference this when composing Phase 2 of any role-spec.
+Full protocol: [specs/knowledge-transfer.md](knowledge-transfer.md)
 
-### Transfer Channels
+Generated role-specs Phase 2 MUST declare which upstream sources to load.
+Generated role-specs Phase 4 MUST include state update and artifact publishing.
 
-| Channel | Scope | Mechanism | When to Use |
-|---------|-------|-----------|-------------|
-| **Artifacts** | Producer -> Consumer | Write to `<session>/artifacts/<name>.md`, consumer reads in Phase 2 | Structured deliverables (reports, plans, specs) |
-| **State Updates** | Cross-role | `team_msg(operation="log", type="state_update", data={...})` / `team_msg(operation="get_state", session_id=<session-id>)` | Key findings, decisions, metadata (small, structured data) |
-| **Wisdom** | Cross-task | Append to `<session>/wisdom/{learnings,decisions,conventions,issues}.md` | Patterns, conventions, risks discovered during execution |
-| **context_accumulator** | Intra-role (inner loop) | In-memory array, passed to each subsequent task in same-prefix loop | Prior task summaries within same role's inner loop |
-| **Exploration cache** | Cross-role | `<session>/explorations/cache-index.json` + per-angle JSON | Codebase discovery results, prevents duplicate exploration |
+---
 
-### Phase 2 Context Loading (role-spec must specify)
+## Generated Role-Spec Validation
 
-Every generated role-spec Phase 2 MUST declare which upstream sources to load:
+Coordinator verifies before writing each role-spec:
 
-```
-1. Extract session path from task description
-2. Read upstream artifacts: <list which artifacts from which upstream role>
-3. Read cross-role state via `team_msg(operation="get_state", session_id=<session-id>)`
-4. Load wisdom files for accumulated knowledge
-5. For inner_loop roles: load context_accumulator from prior tasks
-6. Check exploration cache before running new explorations
-```
-
-### State Update Convention
-
-Cross-role state is managed via `team_msg` state updates instead of a separate file:
-
-- **Write state**: `team_msg(operation="log", session_id=<session-id>, from=<role>, type="state_update", data={ "<role_name>": { ... } })`
-- **Read state**: `team_msg(operation="get_state", session_id=<session-id>)`
-- **Namespaced keys**: Each role writes under its own namespace key in `data`
-- **Small data only**: Key findings, decision summaries, metadata. NOT full documents
-- **State stored in**: `.msg/meta.json` (auto-managed by team_msg)
-- **Example write**:
-  ```
-  team_msg(operation="log", session_id="TC-auth-2026-03-03", from="researcher", type="state_update", data={
-    "researcher": { "key_findings": [...], "scope": "..." }
-  })
-  ```
-- **Example read**:
-  ```
-  team_msg(operation="get_state", session_id="TC-auth-2026-03-03")
-  // Returns merged state from all state_update messages
-  ```
+| Check | Criteria |
+|-------|----------|
+| Frontmatter complete | All required fields present (role, prefix, inner_loop, output_tag, message_types, CLI tools) |
+| Identity block | Tag, prefix, responsibility defined |
+| Boundaries | MUST and MUST NOT rules present |
+| Phase 2 | Context loading sources specified |
+| Phase 3 | Execution goal clear, not prescriptive about tools |
+| Phase 4 | Behavioral Traits copied verbatim |
+| Error Handling | Table with 3+ scenarios |
+| Line count | Target ~80 lines (max 120) |
+| No built-in overlap | No Phase 1/5, no message bus code, no consensus handling |

.claude/skills/team-designer/SKILL.md

@@ -32,7 +32,7 @@ Generate complete team skills following the team-lifecycle-v4 architecture: SKIL
 ## Key Design Principles
 
 1. **v4 Architecture Compliance**: Generated skills follow team-lifecycle-v4 pattern — SKILL.md = pure router, beat model = coordinator-only, unified structure (roles/ + specs/ + templates/)
-2. **Golden Sample Reference**: Uses `team-lifecycle-v4` as reference implementation at `.claude/skills/team-lifecycle-v4/`
+2. **Golden Sample Reference**: Uses `team-lifecycle-v4` as reference implementation at `~  or <project>/.claude/skills/team-lifecycle-v4/`
 3. **Intelligent Commands Distribution**: Auto-determines which roles need `commands/` (2+ commands) vs inline logic (1 command)
 4. **team-worker Compatibility**: Role.md files include correct YAML frontmatter for team-worker agent parsing
 
@@ -76,7 +76,7 @@ Return:
 
 ## Golden Sample
 
-Generated skills follow the architecture of `.claude/skills/team-lifecycle-v4/`:
+Generated skills follow the architecture of `~  or <project>/.claude/skills/team-lifecycle-v4/`:
 
 ```
 .claude/skills/<skill-name>/

.claude/skills/team-designer/phases/03-content-generation.md

@@ -12,7 +12,7 @@ Generate all role files, specs, and templates based on `teamConfig` and the gene
 
 ## Golden Sample Reference
 
-Read the golden sample at `.claude/skills/team-lifecycle-v4/` for each file type before generating. This ensures pattern fidelity.
+Read the golden sample at `~  or <project>/.claude/skills/team-lifecycle-v4/` for each file type before generating. This ensures pattern fidelity.
 
 ## Step 3.1: Generate Coordinator
 
@@ -305,7 +305,7 @@ For each additional spec in `teamConfig.specs` (beyond pipelines), generate doma
 
 For each template in `teamConfig.templates`:
 
-1. Check if golden sample has matching template at `.claude/skills/team-lifecycle-v4/templates/`
+1. Check if golden sample has matching template at `~  or <project>/.claude/skills/team-lifecycle-v4/templates/`
 2. If exists: copy and adapt for new domain
 3. If not: generate domain-appropriate template structure
 

.claude/skills/team-edict/SKILL.md

@@ -193,7 +193,7 @@ Agent({
   name: "<role>",
   team_name: "<team_name>",
   prompt: `role: <role>
-role_spec: .claude/skills/team-edict/role-specs/<role>.md
+role_spec: ~  or <project>/.claude/skills/team-edict/role-specs/<role>.md
 session: <session_path>
 session_id: <session_id>
 team_name: <team_name>

.claude/skills/team-edict/role-specs/xingbu.md

@@ -24,7 +24,7 @@ team_msg(operation="log", session_id=<session_id>, from="xingbu",
 
 1. 读取当前任务（QA-* task description）
 2. 读取 `<session_path>/plan/dispatch-plan.md` 获取验收标准
-3. 读取 `.claude/skills/team-edict/specs/quality-gates.md` 获取质量门标准
+3. 读取 `~  or <project>/.claude/skills/team-edict/specs/quality-gates.md` 获取质量门标准
 4. 读取被测部门（通常为工部）的产出报告
 
 ## Phase 3: 质量审查

.claude/skills/team-edict/roles/coordinator/role.md

@@ -18,7 +18,7 @@
 
 ```javascript
 // Phase 0/1 启动时执行
-Read(".claude/skills/team-edict/specs/team-config.json")  // 加载路由规则和artifact路径
+Read("~  or <project>/.claude/skills/team-edict/specs/team-config.json")  // 加载路由规则和artifact路径
 ```
 
 ---
@@ -106,7 +106,7 @@ Read(".claude/skills/team-edict/specs/team-config.json")  // 加载路由规则
      name: "zhongshu",
      team_name: <team_name>,
      prompt: `role: zhongshu
-role_spec: .claude/skills/team-edict/role-specs/zhongshu.md
+role_spec: ~  or <project>/.claude/skills/team-edict/role-specs/zhongshu.md
 session: <session_path>
 session_id: <session_id>
 team_name: <team_name>
@@ -138,7 +138,7 @@ inner_loop: false`,
      name: "menxia",
      team_name: <team_name>,
      prompt: `role: menxia
-role_spec: .claude/skills/team-edict/role-specs/menxia.md
+role_spec: ~  or <project>/.claude/skills/team-edict/role-specs/menxia.md
 session: <session_path>
 session_id: <session_id>
 team_name: <team_name>
@@ -177,7 +177,7 @@ inner_loop: false`,
      name: "shangshu",
      team_name: <team_name>,
      prompt: `role: shangshu
-role_spec: .claude/skills/team-edict/role-specs/shangshu.md
+role_spec: ~  or <project>/.claude/skills/team-edict/role-specs/shangshu.md
 session: <session_path>
 session_id: <session_id>
 team_name: <team_name>

.claude/skills/team-frontend-debug/SKILL.md

@@ -99,7 +99,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-frontend-debug/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-frontend-debug/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: <team-name>

.claude/skills/team-frontend-debug/roles/coordinator/commands/dispatch.md

@@ -29,7 +29,7 @@ EXPECTED: <artifact path> + <quality criteria>
 CONSTRAINTS: <scope limits>
 ---
 InnerLoop: <true|false>
-RoleSpec: .claude/skills/team-frontend-debug/roles/<role>/role.md
+RoleSpec: ~  or <project>/.claude/skills/team-frontend-debug/roles/<role>/role.md
 ```
 
 ---
@@ -55,7 +55,7 @@ EXPECTED: <session>/artifacts/TEST-001-report.md + <session>/artifacts/TEST-001-
 CONSTRAINTS: Use Chrome DevTools MCP only | Do not modify any code | Test all listed features
 ---
 InnerLoop: true
-RoleSpec: .claude/skills/team-frontend-debug/roles/tester/role.md
+RoleSpec: ~  or <project>/.claude/skills/team-frontend-debug/roles/tester/role.md
 ```
 
 ### ANALYZE-001 (Test Mode): Analyze Discovered Issues
@@ -75,7 +75,7 @@ EXPECTED: <session>/artifacts/ANALYZE-001-rca.md with root causes for all issues
 CONSTRAINTS: Read-only analysis | Skip low-severity warnings unless user requests
 ---
 InnerLoop: false
-RoleSpec: .claude/skills/team-frontend-debug/roles/analyzer/role.md
+RoleSpec: ~  or <project>/.claude/skills/team-frontend-debug/roles/analyzer/role.md
 ```
 
 **Conditional**: If TEST-001 reports zero issues → skip ANALYZE-001, FIX-001, VERIFY-001. Pipeline completes.
@@ -96,7 +96,7 @@ EXPECTED: Modified source files + <session>/artifacts/FIX-001-changes.md
 CONSTRAINTS: Minimal changes per issue | Follow existing code style
 ---
 InnerLoop: true
-RoleSpec: .claude/skills/team-frontend-debug/roles/fixer/role.md
+RoleSpec: ~  or <project>/.claude/skills/team-frontend-debug/roles/fixer/role.md
 ```
 
 ### VERIFY-001 (Test Mode): Re-Test After Fix
@@ -117,7 +117,7 @@ EXPECTED: <session>/artifacts/VERIFY-001-report.md with pass/fail per previously
 CONSTRAINTS: Only re-test failed scenarios | Use Chrome DevTools MCP only
 ---
 InnerLoop: false
-RoleSpec: .claude/skills/team-frontend-debug/roles/verifier/role.md
+RoleSpec: ~  or <project>/.claude/skills/team-frontend-debug/roles/verifier/role.md
 ```
 
 ---
@@ -143,7 +143,7 @@ EXPECTED: <session>/evidence/ directory with all captures + reproduction report
 CONSTRAINTS: Use Chrome DevTools MCP only | Do not modify any code
 ---
 InnerLoop: false
-RoleSpec: .claude/skills/team-frontend-debug/roles/reproducer/role.md
+RoleSpec: ~  or <project>/.claude/skills/team-frontend-debug/roles/reproducer/role.md
 ```
 
 ### ANALYZE-001 (Debug Mode): Root Cause Analysis
@@ -164,7 +164,7 @@ EXPECTED: <session>/artifacts/ANALYZE-001-rca.md with root cause, file:line, fix
 CONSTRAINTS: Read-only analysis | Request more evidence if inconclusive
 ---
 InnerLoop: false
-RoleSpec: .claude/skills/team-frontend-debug/roles/analyzer/role.md
+RoleSpec: ~  or <project>/.claude/skills/team-frontend-debug/roles/analyzer/role.md
 ```
 
 ### FIX-001 (Debug Mode): Code Fix
@@ -183,7 +183,7 @@ EXPECTED: Modified source files + <session>/artifacts/FIX-001-changes.md
 CONSTRAINTS: Minimal changes | Follow existing code style | No breaking changes
 ---
 InnerLoop: true
-RoleSpec: .claude/skills/team-frontend-debug/roles/fixer/role.md
+RoleSpec: ~  or <project>/.claude/skills/team-frontend-debug/roles/fixer/role.md
 ```
 
 ### VERIFY-001 (Debug Mode): Fix Verification
@@ -203,7 +203,7 @@ EXPECTED: <session>/artifacts/VERIFY-001-report.md with pass/fail verdict
 CONSTRAINTS: Use Chrome DevTools MCP only | Same steps as reproduction
 ---
 InnerLoop: false
-RoleSpec: .claude/skills/team-frontend-debug/roles/verifier/role.md
+RoleSpec: ~  or <project>/.claude/skills/team-frontend-debug/roles/verifier/role.md
 ```
 
 ---
@@ -219,7 +219,7 @@ TASK: <specific evidence requests from Analyzer>
 CONTEXT: Session + Analyzer request
 ---
 InnerLoop: false
-RoleSpec: .claude/skills/team-frontend-debug/roles/reproducer/role.md
+RoleSpec: ~  or <project>/.claude/skills/team-frontend-debug/roles/reproducer/role.md
 ```
 
 ### FIX-002 (Either Mode): Re-Fix After Failed Verification
@@ -231,7 +231,7 @@ TASK: Review VERIFY-001 failure details, apply corrective fix
 CONTEXT: Session + VERIFY-001-report.md
 ---
 InnerLoop: true
-RoleSpec: .claude/skills/team-frontend-debug/roles/fixer/role.md
+RoleSpec: ~  or <project>/.claude/skills/team-frontend-debug/roles/fixer/role.md
 ```
 
 ## Conditional Skip Rules

.claude/skills/team-frontend/SKILL.md

@@ -66,7 +66,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-frontend/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-frontend/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: frontend

.claude/skills/team-frontend/roles/coordinator/commands/monitor.md

@@ -129,7 +129,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-frontend/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-frontend/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: frontend

.claude/skills/team-issue/SKILL.md

@@ -67,7 +67,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-issue/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-issue/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: issue
@@ -89,7 +89,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-issue/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-issue/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: issue

.claude/skills/team-issue/roles/coordinator/commands/monitor.md

@@ -101,7 +101,7 @@ Find ready tasks, spawn workers, STOP.
         run_in_background: true,
         prompt: `## Role Assignment
       role: <role>
-      role_spec: .claude/skills/team-issue/roles/<role>/role.md
+      role_spec: ~  or <project>/.claude/skills/team-issue/roles/<role>/role.md
       session: <session-folder>
       session_id: <session-id>
       team_name: issue
@@ -133,7 +133,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-issue/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-issue/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: issue

.claude/skills/team-iterdev/SKILL.md

@@ -66,7 +66,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-iterdev/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-iterdev/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: iterdev

.claude/skills/team-iterdev/roles/coordinator/commands/monitor.md

@@ -101,7 +101,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-iterdev/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-iterdev/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: iterdev

.claude/skills/team-lifecycle-v4/SKILL.md

@@ -71,7 +71,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-lifecycle-v4/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-lifecycle-v4/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: <team-name>
@@ -98,7 +98,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: supervisor
-role_spec: .claude/skills/team-lifecycle-v4/roles/supervisor/role.md
+role_spec: ~  or <project>/.claude/skills/team-lifecycle-v4/roles/supervisor/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: <team-name>

.claude/skills/team-lifecycle-v4/roles/coordinator/commands/dispatch.md

@@ -29,7 +29,7 @@ EXPECTED: <artifact path> + <quality criteria>
 CONSTRAINTS: <scope limits>
 ---
 InnerLoop: <true|false>
-RoleSpec: .claude/skills/team-lifecycle-v4/roles/<role>/role.md
+RoleSpec: ~  or <project>/.claude/skills/team-lifecycle-v4/roles/<role>/role.md
 ```
 
 ## InnerLoop Flag Rules
@@ -45,7 +45,7 @@ CHECKPOINT tasks are dispatched like regular tasks but handled differently at sp
 - Owner: supervisor
 - **NOT spawned as team-worker** — coordinator wakes the resident supervisor via SendMessage
 - If `supervision: false` in team-session.json, skip creating CHECKPOINT tasks entirely
-- RoleSpec in description: `.claude/skills/team-lifecycle-v4/roles/supervisor/role.md`
+- RoleSpec in description: `~  or <project>/.claude/skills/team-lifecycle-v4/roles/supervisor/role.md`
 
 ## Dependency Validation
 

.claude/skills/team-perf-opt/SKILL.md

@@ -78,7 +78,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-perf-opt/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-perf-opt/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: perf-opt

.claude/skills/team-perf-opt/roles/coordinator/commands/monitor.md

@@ -73,7 +73,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-perf-opt/role-specs/<role>.md
+role_spec: ~  or <project>/.claude/skills/team-perf-opt/role-specs/<role>.md
 session: <session-folder>
 session_id: <session-id>
 team_name: perf-opt

.claude/skills/team-perf-opt/roles/coordinator/role.md

@@ -112,7 +112,7 @@ Execute `commands/dispatch.md` inline (Command Execution Protocol).
 ### Initial Spawn
 
 Find first unblocked task and spawn its worker using SKILL.md Worker Spawn Template with:
-- `role_spec: .claude/skills/team-perf-opt/roles/<role>/role.md`
+- `role_spec: ~  or <project>/.claude/skills/team-perf-opt/roles/<role>/role.md`
 - `team_name: perf-opt`
 
 **STOP** after spawning. Wait for worker callback.

.claude/skills/team-perf-opt/specs/team-config.json

@@ -3,7 +3,7 @@
   "team_name": "perf-opt",
   "team_display_name": "Performance Optimization",
   "skill_name": "team-perf-opt",
-  "skill_path": ".claude/skills/team-perf-opt/",
+  "skill_path": "~  or <project>/.claude/skills/team-perf-opt/",
   "worker_agent": "team-worker",
   "pipeline_type": "Linear with Review-Fix Cycle (Parallel-Capable)",
   "completion_action": "interactive",

.claude/skills/team-planex/SKILL.md

@@ -65,7 +65,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-planex/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-planex/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: planex

.claude/skills/team-planex/roles/coordinator/commands/monitor.md

@@ -125,7 +125,7 @@ Collect task states from TaskList()
            run_in_background: true,
            prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-planex/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-planex/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: <team-name>

.claude/skills/team-quality-assurance/SKILL.md

@@ -68,7 +68,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-quality-assurance/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-quality-assurance/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: quality-assurance

.claude/skills/team-quality-assurance/roles/coordinator/commands/dispatch.md

@@ -30,7 +30,7 @@ EXPECTED: <artifact path> + <quality criteria>
 CONSTRAINTS: <scope limits>
 ---
 InnerLoop: <true|false>
-RoleSpec: .claude/skills/team-quality-assurance/roles/<role>/role.md
+RoleSpec: ~  or <project>/.claude/skills/team-quality-assurance/roles/<role>/role.md
 ```
 
 ## Pipeline Task Registry

.claude/skills/team-quality-assurance/roles/coordinator/commands/monitor.md

@@ -59,7 +59,7 @@ EXPECTED: Fixed test files | Improved coverage
 CONSTRAINTS: Only modify test files | No source changes
 ---
 InnerLoop: false
-RoleSpec: .claude/skills/team-quality-assurance/roles/generator/role.md"
+RoleSpec: ~  or <project>/.claude/skills/team-quality-assurance/roles/generator/role.md"
 })
 TaskCreate({
   subject: "QARUN-gc-<round>: Re-execute <layer> (GC #<round>)",
@@ -72,7 +72,7 @@ EXPECTED: <session>/results/run-<layer>-gc-<round>.json
 CONSTRAINTS: Read-only execution
 ---
 InnerLoop: false
-RoleSpec: .claude/skills/team-quality-assurance/roles/executor/role.md",
+RoleSpec: ~  or <project>/.claude/skills/team-quality-assurance/roles/executor/role.md",
   blockedBy: ["QAGEN-fix-<round>"]
 })
 ```
@@ -149,7 +149,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-quality-assurance/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-quality-assurance/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: quality-assurance

.claude/skills/team-review/SKILL.md

@@ -66,7 +66,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-review/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-review/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: review

.claude/skills/team-review/roles/coordinator/commands/dispatch.md

@@ -30,7 +30,7 @@ EXPECTED: <artifact path> + <quality criteria>
 CONSTRAINTS: <scope limits>
 ---
 InnerLoop: <true|false>
-RoleSpec: .claude/skills/team-review/roles/<role>/role.md
+RoleSpec: ~  or <project>/.claude/skills/team-review/roles/<role>/role.md
 ```
 
 ## Pipeline Task Registry

.claude/skills/team-review/roles/coordinator/commands/monitor.md

@@ -24,9 +24,9 @@ Event-driven pipeline coordination. Beat model: coordinator wake -> process -> s
 
 | Prefix | Role | Role Spec | inner_loop |
 |--------|------|-----------|------------|
-| SCAN-* | scanner | `.claude/skills/team-review/roles/scanner/role.md` | false |
-| REV-* | reviewer | `.claude/skills/team-review/roles/reviewer/role.md` | false |
-| FIX-* | fixer | `.claude/skills/team-review/roles/fixer/role.md` | true |
+| SCAN-* | scanner | `~  or <project>/.claude/skills/team-review/roles/scanner/role.md` | false |
+| REV-* | reviewer | `~  or <project>/.claude/skills/team-review/roles/reviewer/role.md` | false |
+| FIX-* | fixer | `~  or <project>/.claude/skills/team-review/roles/fixer/role.md` | true |
 
 ## handleCallback
 
@@ -123,7 +123,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-review/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-review/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: review

.claude/skills/team-roadmap-dev/SKILL.md

@@ -72,7 +72,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-roadmap-dev/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-roadmap-dev/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: roadmap-dev

.claude/skills/team-roadmap-dev/roles/coordinator/commands/monitor.md

@@ -15,9 +15,9 @@ Handle all coordinator monitoring events for the roadmap-dev pipeline using the
 
 | Prefix | Role | Role Spec | inner_loop |
 |--------|------|-----------|------------|
-| PLAN | planner | `.claude/skills/team-roadmap-dev/roles/planner/role.md` | true (cli_tools: gemini --mode analysis) |
-| EXEC | executor | `.claude/skills/team-roadmap-dev/roles/executor/role.md` | true (cli_tools: gemini --mode write) |
-| VERIFY | verifier | `.claude/skills/team-roadmap-dev/roles/verifier/role.md` | true |
+| PLAN | planner | `~  or <project>/.claude/skills/team-roadmap-dev/roles/planner/role.md` | true (cli_tools: gemini --mode analysis) |
+| EXEC | executor | `~  or <project>/.claude/skills/team-roadmap-dev/roles/executor/role.md` | true (cli_tools: gemini --mode write) |
+| VERIFY | verifier | `~  or <project>/.claude/skills/team-roadmap-dev/roles/verifier/role.md` | true |
 
 ### Pipeline Structure
 
@@ -247,7 +247,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-roadmap-dev/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-roadmap-dev/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: roadmap-dev

.claude/skills/team-roadmap-dev/specs/pipelines.md

@@ -88,6 +88,6 @@ Phase N: PLAN-N01 --> EXEC-N01 --> VERIFY-N01
 
 | Prefix | Role | Role Spec | Inner Loop |
 |--------|------|-----------|------------|
-| PLAN | planner | `.claude/skills/team-roadmap-dev/roles/planner/role.md` | true |
-| EXEC | executor | `.claude/skills/team-roadmap-dev/roles/executor/role.md` | true |
-| VERIFY | verifier | `.claude/skills/team-roadmap-dev/roles/verifier/role.md` | true |
+| PLAN | planner | `~  or <project>/.claude/skills/team-roadmap-dev/roles/planner/role.md` | true |
+| EXEC | executor | `~  or <project>/.claude/skills/team-roadmap-dev/roles/executor/role.md` | true |
+| VERIFY | verifier | `~  or <project>/.claude/skills/team-roadmap-dev/roles/verifier/role.md` | true |

.claude/skills/team-roadmap-dev/specs/team-config.json

@@ -2,7 +2,7 @@
   "team_name": "roadmap-dev",
   "team_display_name": "Roadmap Dev",
   "skill_name": "team-roadmap-dev",
-  "skill_path": ".claude/skills/team-roadmap-dev/",
+  "skill_path": "~  or <project>/.claude/skills/team-roadmap-dev/",
   "design_source": "roadmap-driven development workflow design (2026-02-24)",
   "pipeline_type": "Phased",
   "pipeline": {

.claude/skills/team-tech-debt/SKILL.md

@@ -68,7 +68,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-tech-debt/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-tech-debt/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: tech-debt

.claude/skills/team-tech-debt/roles/coordinator/commands/monitor.md

@@ -123,7 +123,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-tech-debt/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-tech-debt/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: tech-debt

.claude/skills/team-testing/SKILL.md

@@ -67,7 +67,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-testing/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-testing/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: testing

.claude/skills/team-testing/roles/coordinator/commands/dispatch.md

@@ -31,7 +31,7 @@ EXPECTED: <deliverable path> + <quality criteria>
 CONSTRAINTS: <scope limits, focus areas>
 ---
 InnerLoop: <true|false>
-RoleSpec: .claude/skills/team-testing/roles/<role>/role.md
+RoleSpec: ~  or <project>/.claude/skills/team-testing/roles/<role>/role.md
 ```
 
 ## Pipeline Task Registry

.claude/skills/team-testing/roles/coordinator/commands/monitor.md

@@ -25,10 +25,10 @@ Event-driven pipeline coordination. Beat model: coordinator wake -> process -> s
 
 | Prefix | Role | Role Spec | inner_loop |
 |--------|------|-----------|------------|
-| STRATEGY-* | strategist | `.claude/skills/team-testing/roles/strategist/role.md` | false |
-| TESTGEN-* | generator | `.claude/skills/team-testing/roles/generator/role.md` | true |
-| TESTRUN-* | executor | `.claude/skills/team-testing/roles/executor/role.md` | true |
-| TESTANA-* | analyst | `.claude/skills/team-testing/roles/analyst/role.md` | false |
+| STRATEGY-* | strategist | `~  or <project>/.claude/skills/team-testing/roles/strategist/role.md` | false |
+| TESTGEN-* | generator | `~  or <project>/.claude/skills/team-testing/roles/generator/role.md` | true |
+| TESTRUN-* | executor | `~  or <project>/.claude/skills/team-testing/roles/executor/role.md` | true |
+| TESTANA-* | analyst | `~  or <project>/.claude/skills/team-testing/roles/analyst/role.md` | false |
 
 ## handleCallback
 
@@ -68,7 +68,7 @@ EXPECTED: Revised test files in <session>/tests/<layer>/
 CONSTRAINTS: Only modify test files
 ---
 InnerLoop: true
-RoleSpec: .claude/skills/team-testing/roles/generator/role.md"
+RoleSpec: ~  or <project>/.claude/skills/team-testing/roles/generator/role.md"
 })
 TaskCreate({
   subject: "TESTRUN-<layer>-fix-<round>: Re-execute <layer> (GC #<round>)",
@@ -80,7 +80,7 @@ CONTEXT:
 EXPECTED: <session>/results/run-<N>-gc.json
 ---
 InnerLoop: true
-RoleSpec: .claude/skills/team-testing/roles/executor/role.md",
+RoleSpec: ~  or <project>/.claude/skills/team-testing/roles/executor/role.md",
   blockedBy: ["TESTGEN-<layer>-fix-<round>"]
 })
 ```
@@ -150,7 +150,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-testing/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-testing/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: testing

.claude/skills/team-uidesign/SKILL.md

@@ -67,7 +67,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-uidesign/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-uidesign/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: uidesign

.claude/skills/team-uidesign/roles/coordinator/commands/monitor.md

@@ -127,7 +127,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-uidesign/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-uidesign/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: uidesign

.claude/skills/team-ultra-analyze/SKILL.md

@@ -75,7 +75,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-ultra-analyze/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-ultra-analyze/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: ultra-analyze

.claude/skills/team-ultra-analyze/roles/coordinator/commands/monitor.md

@@ -211,10 +211,10 @@ Find and spawn the next ready tasks.
 
 | Task Prefix | Role | Role Spec |
 |-------------|------|-----------|
-| `EXPLORE-*` | explorer | `.claude/skills/team-ultra-analyze/role-specs/explorer.md` |
-| `ANALYZE-*` | analyst | `.claude/skills/team-ultra-analyze/role-specs/analyst.md` |
-| `DISCUSS-*` | discussant | `.claude/skills/team-ultra-analyze/role-specs/discussant.md` |
-| `SYNTH-*` | synthesizer | `.claude/skills/team-ultra-analyze/role-specs/synthesizer.md` |
+| `EXPLORE-*` | explorer | `~  or <project>/.claude/skills/team-ultra-analyze/role-specs/explorer.md` |
+| `ANALYZE-*` | analyst | `~  or <project>/.claude/skills/team-ultra-analyze/role-specs/analyst.md` |
+| `DISCUSS-*` | discussant | `~  or <project>/.claude/skills/team-ultra-analyze/role-specs/discussant.md` |
+| `SYNTH-*` | synthesizer | `~  or <project>/.claude/skills/team-ultra-analyze/role-specs/synthesizer.md` |
 
 3. Spawn team-worker for each ready task:
 
@@ -227,7 +227,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-ultra-analyze/role-specs/<role>.md
+role_spec: ~  or <project>/.claude/skills/team-ultra-analyze/role-specs/<role>.md
 session: <session-folder>
 session_id: <session-id>
 team_name: ultra-analyze

.claude/skills/team-ultra-analyze/roles/coordinator/role.md

@@ -152,7 +152,7 @@ Execute `commands/dispatch.md` inline (Command Execution Protocol):
 ### Initial Spawn
 
 Find first unblocked tasks and spawn their workers. Use SKILL.md Worker Spawn Template with:
-- `role_spec: .claude/skills/team-ultra-analyze/roles/<role>/role.md`
+- `role_spec: ~  or <project>/.claude/skills/team-ultra-analyze/roles/<role>/role.md`
 - `team_name: ultra-analyze`
 - `inner_loop: false`
 

.claude/skills/team-ux-improve/SKILL.md

@@ -76,7 +76,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-ux-improve/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-ux-improve/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: ux-improve

.claude/skills/team-ux-improve/roles/coordinator/commands/monitor.md

@@ -102,7 +102,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-ux-improve/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-ux-improve/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: ux-improve

.claude/skills/team-ux-improve/roles/coordinator/role.md

@@ -76,7 +76,7 @@ TEXT-LEVEL ONLY. No source code reading.
    ├── explorations/
    └── wisdom/contributions/
    ```
-3. **Wisdom Initialization**: Copy `.claude/skills/team-ux-improve/wisdom/` to `<session>/wisdom/`
+3. **Wisdom Initialization**: Copy `~  or <project>/.claude/skills/team-ux-improve/wisdom/` to `<session>/wisdom/`
 4. Initialize `.msg/meta.json` via team_msg state_update with pipeline metadata
 5. TeamCreate(team_name="ux-improve")
 6. Do NOT spawn workers yet - deferred to Phase 4
@@ -110,7 +110,7 @@ Delegate to `commands/monitor.md#handleSpawnNext`:
 
 3. **Wisdom Consolidation**: Check `<session>/wisdom/contributions/` for worker contributions
    - If contributions exist -> AskUserQuestion to merge to permanent wisdom
-   - If approved -> copy to `.claude/skills/team-ux-improve/wisdom/`
+   - If approved -> copy to `~  or <project>/.claude/skills/team-ux-improve/wisdom/`
 
 4. Calculate: completed_tasks, total_issues_found, issues_fixed, test_pass_rate
 5. Output pipeline summary with [coordinator] prefix

.claude/skills/team-ux-improve/specs/pipelines.md

@@ -44,7 +44,7 @@ UX improvement pipeline modes and task registry.
 
 ## Wisdom System
 
-Workers contribute learnings to `<session>/wisdom/contributions/`. On pipeline completion, coordinator asks user to merge approved contributions to permanent wisdom at `.claude/skills/team-ux-improve/wisdom/`.
+Workers contribute learnings to `<session>/wisdom/contributions/`. On pipeline completion, coordinator asks user to merge approved contributions to permanent wisdom at `~  or <project>/.claude/skills/team-ux-improve/wisdom/`.
 
 | Directory | Purpose |
 |-----------|---------|

.claude/skills/team-ux-improve/specs/team-config.json

@@ -4,7 +4,7 @@
   "team_display_name": "UX Improve",
   "team_purpose": "Systematically discover and fix UI/UX interaction issues including unresponsive buttons, missing feedback, and state refresh problems",
   "skill_name": "team-ux-improve",
-  "skill_path": ".claude/skills/team-ux-improve/",
+  "skill_path": "~  or <project>/.claude/skills/team-ux-improve/",
   "worker_agent": "team-worker",
   "pipeline_type": "Standard",
   "completion_action": "interactive",

.codex/skills/spec-generator/README.md

@@ -0,0 +1,110 @@
+# Spec Generator
+
+Structured specification document generator producing a complete document chain (Product Brief -> PRD -> Architecture -> Epics).
+
+## Usage
+
+```bash
+# Via workflow command
+/workflow:spec "Build a task management system"
+/workflow:spec -y "User auth with OAuth2"    # Auto mode
+/workflow:spec -c "task management"           # Resume session
+```
+
+## Architecture
+
+```
+spec-generator/
+|- SKILL.md                          # Entry point: metadata + architecture + flow
+|- phases/
+|  |- 01-discovery.md                # Seed analysis + codebase exploration + spec type selection
+|  |- 01-5-requirement-clarification.md  # Interactive requirement expansion
+|  |- 02-product-brief.md            # Multi-CLI product brief + glossary generation
+|  |- 03-requirements.md             # PRD with MoSCoW priorities + RFC 2119 constraints
+|  |- 04-architecture.md             # Architecture + state machine + config model + observability
+|  |- 05-epics-stories.md            # Epic/Story decomposition
+|  |- 06-readiness-check.md          # Quality validation + handoff + iterate option
+|  |- 06-5-auto-fix.md               # Auto-fix loop for readiness issues (max 2 iterations)
+|  |- 07-issue-export.md             # Issue creation from Epics + export report
+|- specs/
+|  |- document-standards.md          # Format, frontmatter, naming rules
+|  |- quality-gates.md               # Per-phase quality criteria + iteration tracking
+|  |- glossary-template.json         # Terminology glossary schema
+|- templates/
+|  |- product-brief.md               # Product brief template (+ Concepts & Non-Goals)
+|  |- requirements-prd.md            # PRD template
+|  |- architecture-doc.md            # Architecture template (+ state machine, config, observability)
+|  |- epics-template.md              # Epic/Story template (+ versioning)
+|  |- profiles/                      # Spec type specialization profiles
+|     |- service-profile.md          # Service spec: lifecycle, observability, trust
+|     |- api-profile.md              # API spec: endpoints, auth, rate limiting
+|     |- library-profile.md          # Library spec: public API, examples, compatibility
+|- README.md                         # This file
+```
+
+## 7-Phase Pipeline
+
+| Phase | Name | Output | CLI Tools | Key Features |
+|-------|------|--------|-----------|-------------|
+| 1 | Discovery | spec-config.json | Gemini (analysis) | Spec type selection |
+| 1.5 | Req Expansion | refined-requirements.json | Gemini (analysis) | Multi-round interactive |
+| 2 | Product Brief *(Agent)* | product-brief.md, glossary.json | Gemini + Codex + Claude (parallel) | Terminology glossary |
+| 3 | Requirements *(Agent)* | requirements/ | Gemini + **Codex review** | RFC 2119, data model |
+| 4 | Architecture *(Agent)* | architecture/ | Gemini + Codex (sequential) | State machine, config, observability |
+| 5 | Epics & Stories *(Agent)* | epics/ | Gemini + **Codex review** | Glossary consistency |
+| 6 | Readiness Check | readiness-report.md, spec-summary.md | Gemini + **Codex** (parallel) | Per-requirement verification |
+| 6.5 | Auto-Fix *(Agent)* | Updated phase docs | Gemini (analysis) | Max 2 iterations |
+| 7 | Issue Export | issue-export-report.md | ccw issue create | Epic→Issue mapping, wave assignment |
+
+## Runtime Output
+
+```
+.workflow/.spec/SPEC-{slug}-{YYYY-MM-DD}/
+|- spec-config.json              # Session state
+|- discovery-context.json        # Codebase context (optional)
+|- refined-requirements.json     # Phase 1.5 (requirement expansion)
+|- glossary.json                 # Phase 2 (terminology)
+|- product-brief.md              # Phase 2
+|- requirements/                 # Phase 3 (directory)
+|  |- _index.md
+|  |- REQ-*.md
+|  └── NFR-*.md
+|- architecture/                 # Phase 4 (directory)
+|  |- _index.md
+|  └── ADR-*.md
+|- epics/                        # Phase 5 (directory)
+|  |- _index.md
+|  └── EPIC-*.md
+|- readiness-report.md           # Phase 6
+|- spec-summary.md              # Phase 6
+└── issue-export-report.md       # Phase 7 (issue export)
+```
+
+## Flags
+
+- `-y|--yes`: Auto mode - skip all interactive confirmations
+- `-c|--continue`: Resume from last completed phase
+
+Spec type is selected interactively in Phase 1 (defaults to `service` in auto mode)
+Available types: `service`, `api`, `library`, `platform`
+
+## Handoff
+
+After Phase 6, choose execution path:
+- `Export Issues (Phase 7)` - Create issues per Epic with spec links → team-planex
+- `workflow-lite-plan` - Execute per Epic
+- `workflow:req-plan-with-file` - Roadmap decomposition
+- `workflow-plan` - Full planning
+- `Iterate & improve` - Re-run failed phases (max 2 iterations)
+
+## Design Principles
+
+- **Document chain**: Each phase builds on previous outputs
+- **Multi-perspective**: Gemini/Codex/Claude provide different viewpoints
+- **Template-driven**: Consistent format via templates + frontmatter
+- **Resumable**: spec-config.json tracks completed phases
+- **Pure documentation**: No code generation - clean handoff to execution workflows
+- **Type-specialized**: Profiles adapt templates to service/api/library/platform requirements
+- **Iterative quality**: Phase 6.5 auto-fix repairs issues, max 2 iterations before handoff
+- **Terminology-first**: glossary.json ensures consistent terminology across all documents
+- **Agent-delegated**: Heavy document phases (2-5, 6.5) run in doc-generator agents to minimize main context usage

.codex/skills/spec-generator/SKILL.md

@@ -0,0 +1,425 @@
+---
+name: spec-generator
+description: Specification generator - 7 phase document chain producing product brief, PRD, architecture, epics, and issues. Agent-delegated heavy phases (2-5, 6.5) with Codex review gates. Triggers on "generate spec", "create specification", "spec generator", "workflow:spec".
+allowed-tools: Agent, AskUserQuestion, TaskCreate, TaskUpdate, TaskList, Read, Write, Edit, Bash, Glob, Grep, Skill
+---
+
+# Spec Generator
+
+Structured specification document generator producing a complete specification package (Product Brief, PRD, Architecture, Epics, Issues) through 7 sequential phases with multi-CLI analysis, Codex review gates, and interactive refinement. Heavy document phases are delegated to `doc-generator` agents to minimize main context usage. **Document generation only** - execution handoff via issue export to team-planex or existing workflows.
+
+## Architecture Overview
+
+```
+Phase 0:   Specification Study (Read specs/ + templates/ - mandatory prerequisite)      [Inline]
+           |
+Phase 1:   Discovery               -> spec-config.json + discovery-context.json         [Inline]
+           |                           (includes spec_type selection)
+Phase 1.5: Req Expansion           -> refined-requirements.json                         [Inline]
+           |                           (interactive discussion + CLI gap analysis)
+Phase 2:   Product Brief            -> product-brief.md + glossary.json                 [Agent]
+           |                           (3-CLI parallel + synthesis)
+Phase 3:   Requirements (PRD)      -> requirements/  (_index.md + REQ-*.md + NFR-*.md)  [Agent]
+           |                           (Gemini + Codex review)
+Phase 4:   Architecture            -> architecture/  (_index.md + ADR-*.md)             [Agent]
+           |                           (Gemini + Codex review)
+Phase 5:   Epics & Stories         -> epics/  (_index.md + EPIC-*.md)                   [Agent]
+           |                           (Gemini + Codex review)
+Phase 6:   Readiness Check         -> readiness-report.md + spec-summary.md             [Inline]
+           |                           (Gemini + Codex dual validation + per-req verification)
+           ├── Pass (>=80%): Handoff or Phase 7
+           ├── Review (60-79%): Handoff with caveats or Phase 7
+           └── Fail (<60%): Phase 6.5 Auto-Fix (max 2 iterations)
+                 |
+Phase 6.5: Auto-Fix               -> Updated Phase 2-5 documents                       [Agent]
+                 |
+                 └── Re-run Phase 6 validation
+                       |
+Phase 7:   Issue Export            -> issue-export-report.md                            [Inline]
+                                      (Epic→Issue mapping, ccw issue create, wave assignment)
+```
+
+## Key Design Principles
+
+1. **Document Chain**: Each phase builds on previous outputs, creating a traceable specification chain from idea to executable issues
+2. **Agent-Delegated**: Heavy document phases (2-5, 6.5) run in `doc-generator` agents, keeping main context lean (summaries only)
+3. **Multi-Perspective Analysis**: CLI tools (Gemini/Codex/Claude) provide product, technical, and user perspectives in parallel
+4. **Codex Review Gates**: Phases 3, 5, 6 include Codex CLI review for quality validation before output
+5. **Interactive by Default**: Each phase offers user confirmation points; `-y` flag enables full auto mode
+6. **Resumable Sessions**: `spec-config.json` tracks completed phases; `-c` flag resumes from last checkpoint
+7. **Template-Driven**: All documents generated from standardized templates with YAML frontmatter
+8. **Pure Documentation**: No code generation or execution - clean handoff via issue export to execution workflows
+9. **Spec Type Specialization**: Templates adapt to spec type (service/api/library/platform) via profiles for domain-specific depth
+10. **Iterative Quality**: Phase 6.5 auto-fix loop repairs issues found in readiness check (max 2 iterations)
+11. **Terminology Consistency**: glossary.json generated in Phase 2, injected into all subsequent phases
+
+---
+
+## Mandatory Prerequisites
+
+> **Do NOT skip**: Before performing any operations, you **must** completely read the following documents. Proceeding without reading the specifications will result in outputs that do not meet quality standards.
+
+### Specification Documents (Required Reading)
+
+| Document | Purpose | Priority |
+|----------|---------|----------|
+| [specs/document-standards.md](specs/document-standards.md) | Document format, frontmatter, naming conventions | **P0 - Must read before execution** |
+| [specs/quality-gates.md](specs/quality-gates.md) | Per-phase quality gate criteria and scoring | **P0 - Must read before execution** |
+
+### Template Files (Must read before generation)
+
+| Document | Purpose |
+|----------|---------|
+| [templates/product-brief.md](templates/product-brief.md) | Product brief document template |
+| [templates/requirements-prd.md](templates/requirements-prd.md) | PRD document template |
+| [templates/architecture-doc.md](templates/architecture-doc.md) | Architecture document template |
+| [templates/epics-template.md](templates/epics-template.md) | Epic/Story document template |
+
+---
+
+## Execution Flow
+
+```
+Input Parsing:
+   |- Parse $ARGUMENTS: extract idea/topic, flags (-y, -c, -m)
+   |- Detect mode: new | continue
+   |- If continue: read spec-config.json, resume from first incomplete phase
+   |- If new: proceed to Phase 1
+
+Phase 1: Discovery & Seed Analysis
+   |- Ref: phases/01-discovery.md
+   |- Generate session ID: SPEC-{slug}-{YYYY-MM-DD}
+   |- Parse input (text or file reference)
+   |- Gemini CLI seed analysis (problem, users, domain, dimensions)
+   |- Codebase exploration (conditional, if project detected)
+   |- Spec type selection: service|api|library|platform (interactive, -y defaults to service)
+   |- User confirmation (interactive, -y skips)
+   |- Output: spec-config.json, discovery-context.json (optional)
+
+Phase 1.5: Requirement Expansion & Clarification
+   |- Ref: phases/01-5-requirement-clarification.md
+   |- CLI gap analysis: completeness scoring, missing dimensions detection
+   |- Multi-round interactive discussion (max 5 rounds)
+   |  |- Round 1: present gap analysis + expansion suggestions
+   |  |- Round N: follow-up refinement based on user responses
+   |- User final confirmation of requirements
+   |- Auto mode (-y): CLI auto-expansion without interaction
+   |- Output: refined-requirements.json
+
+Phase 2: Product Brief  [AGENT: doc-generator]
+   |- Delegate to Task(subagent_type="doc-generator")
+   |- Agent reads: phases/02-product-brief.md
+   |- Agent executes: 3 parallel CLI analyses + synthesis + glossary generation
+   |- Agent writes: product-brief.md, glossary.json
+   |- Agent returns: JSON summary {files_created, quality_notes, key_decisions}
+   |- Orchestrator validates: files exist, spec-config.json updated
+
+Phase 3: Requirements / PRD  [AGENT: doc-generator]
+   |- Delegate to Task(subagent_type="doc-generator")
+   |- Agent reads: phases/03-requirements.md
+   |- Agent executes: Gemini expansion + Codex review (Step 2.5) + priority sorting
+   |- Agent writes: requirements/ directory (_index.md + REQ-*.md + NFR-*.md)
+   |- Agent returns: JSON summary {files_created, codex_review_integrated, key_decisions}
+   |- Orchestrator validates: directory exists, file count matches
+
+Phase 4: Architecture  [AGENT: doc-generator]
+   |- Delegate to Task(subagent_type="doc-generator")
+   |- Agent reads: phases/04-architecture.md
+   |- Agent executes: Gemini analysis + Codex review + codebase mapping
+   |- Agent writes: architecture/ directory (_index.md + ADR-*.md)
+   |- Agent returns: JSON summary {files_created, codex_review_rating, key_decisions}
+   |- Orchestrator validates: directory exists, ADR files present
+
+Phase 5: Epics & Stories  [AGENT: doc-generator]
+   |- Delegate to Task(subagent_type="doc-generator")
+   |- Agent reads: phases/05-epics-stories.md
+   |- Agent executes: Gemini decomposition + Codex review (Step 2.5) + validation
+   |- Agent writes: epics/ directory (_index.md + EPIC-*.md)
+   |- Agent returns: JSON summary {files_created, codex_review_integrated, mvp_epic_count}
+   |- Orchestrator validates: directory exists, MVP epics present
+
+Phase 6: Readiness Check  [INLINE + ENHANCED]
+   |- Ref: phases/06-readiness-check.md
+   |- Gemini CLI: cross-document validation (completeness, consistency, traceability)
+   |- Codex CLI: technical depth review (ADR quality, data model, security, observability)
+   |- Per-requirement verification: iterate all REQ-*.md / NFR-*.md
+   |  |- Check: AC exists + testable, Brief trace, Story coverage, Arch coverage
+   |  |- Generate: Per-Requirement Verification table
+   |- Merge dual CLI scores into quality report
+   |- Output: readiness-report.md, spec-summary.md
+   |- Handoff options: Phase 7 (issue export), lite-plan, req-plan, plan, iterate
+
+Phase 6.5: Auto-Fix (conditional)  [AGENT: doc-generator]
+   |- Delegate to Task(subagent_type="doc-generator")
+   |- Agent reads: phases/06-5-auto-fix.md + readiness-report.md
+   |- Agent executes: fix affected Phase 2-5 documents
+   |- Agent returns: JSON summary {files_modified, issues_fixed, phases_touched}
+   |- Re-run Phase 6 validation
+   |- Max 2 iterations, then force handoff
+
+Phase 7: Issue Export  [INLINE]
+   |- Ref: phases/07-issue-export.md
+   |- Read EPIC-*.md files, assign waves (MVP→wave-1, others→wave-2)
+   |- Create issues via ccw issue create (one per Epic)
+   |- Map Epic dependencies to issue dependencies
+   |- Generate issue-export-report.md
+   |- Update spec-config.json with issue_ids
+   |- Handoff: team-planex, wave-1 only, view issues, done
+
+Complete: Full specification package with issues ready for execution
+
+Phase 6/7 → Handoff Bridge (conditional, based on user selection):
+   ├─ team-planex: Execute issues via coordinated team workflow
+   ├─ lite-plan: Extract first MVP Epic description → direct text input
+   ├─ plan / req-plan: Create WFS session + .brainstorming/ bridge files
+   │   ├─ guidance-specification.md (synthesized from spec outputs)
+   │   ├─ feature-specs/feature-index.json (Epic → Feature mapping)
+   │   └─ feature-specs/F-{num}-{slug}.md (one per Epic)
+   └─ context-search-agent auto-discovers .brainstorming/
+       → context-package.json.brainstorm_artifacts populated
+       → action-planning-agent consumes: guidance_spec (P1) → feature_index (P2)
+```
+
+## Directory Setup
+
+```javascript
+// Session ID generation
+const slug = topic.toLowerCase().replace(/[^a-z0-9\u4e00-\u9fff]+/g, '-').slice(0, 40);
+const date = new Date().toISOString().slice(0, 10);
+const sessionId = `SPEC-${slug}-${date}`;
+const workDir = `.workflow/.spec/${sessionId}`;
+
+Bash(`mkdir -p "${workDir}"`);
+```
+
+## Output Structure
+
+```
+.workflow/.spec/SPEC-{slug}-{YYYY-MM-DD}/
+├── spec-config.json              # Session configuration + phase state
+├── discovery-context.json        # Codebase exploration results (optional)
+├── refined-requirements.json     # Phase 1.5: Confirmed requirements after discussion
+├── glossary.json                 # Phase 2: Terminology glossary for cross-doc consistency
+├── product-brief.md              # Phase 2: Product brief
+├── requirements/                 # Phase 3: Detailed PRD (directory)
+│   ├── _index.md                 #   Summary, MoSCoW table, traceability, links
+│   ├── REQ-NNN-{slug}.md         #   Individual functional requirement
+│   └── NFR-{type}-NNN-{slug}.md  #   Individual non-functional requirement
+├── architecture/                 # Phase 4: Architecture decisions (directory)
+│   ├── _index.md                 #   Overview, components, tech stack, links
+│   └── ADR-NNN-{slug}.md         #   Individual Architecture Decision Record
+├── epics/                        # Phase 5: Epic/Story breakdown (directory)
+│   ├── _index.md                 #   Epic table, dependency map, MVP scope
+│   └── EPIC-NNN-{slug}.md        #   Individual Epic with Stories
+├── readiness-report.md           # Phase 6: Quality report (+ per-req verification table)
+├── spec-summary.md               # Phase 6: One-page executive summary
+└── issue-export-report.md        # Phase 7: Issue mapping table + spec links
+```
+
+## State Management
+
+**spec-config.json** serves as core state file:
+```json
+{
+  "session_id": "SPEC-xxx-2026-02-11",
+  "seed_input": "User input text",
+  "input_type": "text",
+  "timestamp": "ISO8601",
+  "mode": "interactive",
+  "complexity": "moderate",
+  "depth": "standard",
+  "focus_areas": [],
+  "spec_type": "service",
+  "iteration_count": 0,
+  "iteration_history": [],
+  "seed_analysis": {
+    "problem_statement": "...",
+    "target_users": [],
+    "domain": "...",
+    "constraints": [],
+    "dimensions": []
+  },
+  "has_codebase": false,
+  "refined_requirements_file": "refined-requirements.json",
+  "issue_ids": [],
+  "issues_created": 0,
+  "phasesCompleted": [
+    { "phase": 1, "name": "discovery", "output_file": "spec-config.json", "completed_at": "ISO8601" },
+    { "phase": 1.5, "name": "requirement-clarification", "output_file": "refined-requirements.json", "discussion_rounds": 2, "completed_at": "ISO8601" },
+    { "phase": 3, "name": "requirements", "output_dir": "requirements/", "output_index": "requirements/_index.md", "file_count": 8, "completed_at": "ISO8601" }
+  ]
+}
+```
+
+**Resume mechanism**: `-c|--continue` flag reads `spec-config.json.phasesCompleted`, resumes from first incomplete phase.
+
+## Core Rules
+
+1. **Start Immediately**: First action is TaskCreate initialization, then Phase 0 (spec study), then Phase 1
+2. **Progressive Phase Loading**: Read phase docs ONLY when that phase is about to execute
+3. **Auto-Continue**: All phases run autonomously; check TaskList to execute next pending phase
+4. **Parse Every Output**: Extract required data from each phase for next phase context
+5. **DO NOT STOP**: Continuous 7-phase pipeline until all phases complete or user exits
+6. **Respect -y Flag**: When auto mode, skip all AskUserQuestion calls, use recommended defaults
+7. **Respect -c Flag**: When continue mode, load spec-config.json and resume from checkpoint
+8. **Inject Glossary**: From Phase 3 onward, inject glossary.json terms into every CLI prompt
+9. **Load Profile**: Read templates/profiles/{spec_type}-profile.md and inject requirements into Phase 2-5 prompts
+10. **Iterate on Failure**: When Phase 6 score < 60%, auto-trigger Phase 6.5 (max 2 iterations)
+11. **Agent Delegation**: Phase 2-5 and 6.5 MUST be delegated to `doc-generator` agents via Task tool — never execute inline
+12. **Lean Context**: Orchestrator only sees agent return summaries (JSON), never the full document content
+13. **Validate Agent Output**: After each agent returns, verify files exist on disk and spec-config.json was updated
+
+## Agent Delegation Protocol
+
+For Phase 2-5 and 6.5, the orchestrator delegates to a `doc-generator` agent via the Task tool. The orchestrator builds a lean context envelope — passing only paths, never file content.
+
+### Context Envelope Template
+
+```javascript
+Task({
+  subagent_type: "doc-generator",
+  run_in_background: false,
+  description: `Spec Phase ${N}: ${phaseName}`,
+  prompt: `
+## Spec Generator - Phase ${N}: ${phaseName}
+
+### Session
+- ID: ${sessionId}
+- Work Dir: ${workDir}
+- Auto Mode: ${autoMode}
+- Spec Type: ${specType}
+
+### Input (read from disk)
+${inputFilesList}  // Only file paths — agent reads content itself
+
+### Instructions
+Read: ${skillDir}/phases/${phaseFile}  // Agent reads the phase doc for full instructions
+Apply template: ${skillDir}/templates/${templateFile}
+
+### Glossary (Phase 3+ only)
+Read: ${workDir}/glossary.json
+
+### Output
+Write files to: ${workDir}/${outputPath}
+Update: ${workDir}/spec-config.json (phasesCompleted)
+Return: JSON summary { files_created, quality_notes, key_decisions }
+`
+});
+```
+
+### Orchestrator Post-Agent Validation
+
+After each agent returns:
+
+```javascript
+// 1. Parse agent return summary
+const summary = JSON.parse(agentResult);
+
+// 2. Validate files exist
+summary.files_created.forEach(file => {
+  const exists = Glob(`${workDir}/${file}`);
+  if (!exists.length) throw new Error(`Agent claimed to create ${file} but file not found`);
+});
+
+// 3. Verify spec-config.json updated
+const config = JSON.parse(Read(`${workDir}/spec-config.json`));
+const phaseComplete = config.phasesCompleted.some(p => p.phase === N);
+if (!phaseComplete) throw new Error(`Agent did not update phasesCompleted for Phase ${N}`);
+
+// 4. Store summary for downstream context (do NOT read full documents)
+phasesSummaries[N] = summary;
+```
+
+---
+
+## Reference Documents by Phase
+
+### Phase 1: Discovery
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/01-discovery.md](phases/01-discovery.md) | Seed analysis and session setup | Phase start |
+| [templates/profiles/](templates/profiles/) | Spec type profiles | Spec type selection |
+| [specs/document-standards.md](specs/document-standards.md) | Frontmatter format for spec-config.json | Config generation |
+
+### Phase 1.5: Requirement Expansion & Clarification
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/01-5-requirement-clarification.md](phases/01-5-requirement-clarification.md) | Interactive requirement discussion workflow | Phase start |
+| [specs/quality-gates.md](specs/quality-gates.md) | Quality criteria for refined requirements | Validation |
+
+### Phase 2: Product Brief
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/02-product-brief.md](phases/02-product-brief.md) | Multi-CLI analysis orchestration | Phase start |
+| [templates/product-brief.md](templates/product-brief.md) | Document template | Document generation |
+| [specs/glossary-template.json](specs/glossary-template.json) | Glossary schema | Glossary generation |
+
+### Phase 3: Requirements
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/03-requirements.md](phases/03-requirements.md) | PRD generation workflow | Phase start |
+| [templates/requirements-prd.md](templates/requirements-prd.md) | Document template | Document generation |
+
+### Phase 4: Architecture
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/04-architecture.md](phases/04-architecture.md) | Architecture decision workflow | Phase start |
+| [templates/architecture-doc.md](templates/architecture-doc.md) | Document template | Document generation |
+
+### Phase 5: Epics & Stories
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/05-epics-stories.md](phases/05-epics-stories.md) | Epic/Story decomposition | Phase start |
+| [templates/epics-template.md](templates/epics-template.md) | Document template | Document generation |
+
+### Phase 6: Readiness Check
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/06-readiness-check.md](phases/06-readiness-check.md) | Cross-document validation | Phase start |
+| [specs/quality-gates.md](specs/quality-gates.md) | Quality scoring criteria | Validation |
+
+### Phase 6.5: Auto-Fix
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/06-5-auto-fix.md](phases/06-5-auto-fix.md) | Auto-fix workflow for readiness issues | When Phase 6 score < 60% |
+| [specs/quality-gates.md](specs/quality-gates.md) | Iteration exit criteria | Validation |
+
+### Phase 7: Issue Export
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/07-issue-export.md](phases/07-issue-export.md) | Epic→Issue mapping and export | Phase start |
+| [specs/quality-gates.md](specs/quality-gates.md) | Issue export quality criteria | Validation |
+
+### Debugging & Troubleshooting
+| Issue | Solution Document |
+|-------|-------------------|
+| Phase execution failed | Refer to the relevant Phase documentation |
+| Output does not meet expectations | [specs/quality-gates.md](specs/quality-gates.md) |
+| Document format issues | [specs/document-standards.md](specs/document-standards.md) |
+
+## Error Handling
+
+| Phase | Error | Blocking? | Action |
+|-------|-------|-----------|--------|
+| Phase 1 | Empty input | Yes | Error and exit |
+| Phase 1 | CLI seed analysis fails | No | Use basic parsing fallback |
+| Phase 1.5 | Gap analysis CLI fails | No | Skip to user questions with basic prompts |
+| Phase 1.5 | User skips discussion | No | Proceed with seed_analysis as-is |
+| Phase 1.5 | Max rounds reached (5) | No | Force confirmation with current state |
+| Phase 2 | Single CLI perspective fails | No | Continue with available perspectives |
+| Phase 2 | All CLI calls fail | No | Generate basic brief from seed analysis |
+| Phase 3 | Gemini CLI fails | No | Use codex fallback |
+| Phase 4 | Architecture review fails | No | Skip review, proceed with initial analysis |
+| Phase 5 | Story generation fails | No | Generate epics without detailed stories |
+| Phase 6 | Validation CLI fails | No | Generate partial report with available data |
+| Phase 6.5 | Auto-fix CLI fails | No | Log failure, proceed to handoff with Review status |
+| Phase 6.5 | Max iterations reached | No | Force handoff, report remaining issues |
+| Phase 7 | ccw issue create fails for one Epic | No | Log error, continue with remaining Epics |
+| Phase 7 | No EPIC files found | Yes | Error and return to Phase 5 |
+| Phase 7 | All issue creations fail | Yes | Error with CLI diagnostic, suggest manual creation |
+| Phase 2-5 | Agent fails to return | Yes | Retry once, then fall back to inline execution |
+| Phase 2-5 | Agent returns incomplete files | No | Log gaps, attempt inline completion for missing files |
+
+### CLI Fallback Chain
+
+Gemini -> Codex -> Claude -> degraded mode (local analysis only)

.codex/skills/spec-generator/phases/01-5-requirement-clarification.md

@@ -0,0 +1,404 @@
+# Phase 1.5: Requirement Expansion & Clarification
+
+在进入正式文档生成前，通过多轮交互讨论对原始需求进行深度挖掘、扩展和确认。
+
+## Objective
+
+- 识别原始需求中的模糊点、遗漏和潜在风险
+- 通过 CLI 辅助分析需求完整性，生成深度探测问题
+- 支持多轮交互讨论，逐步细化需求
+- 生成经用户确认的 `refined-requirements.json` 作为后续阶段的高质量输入
+
+## Input
+
+- Dependency: `{workDir}/spec-config.json` (Phase 1 output)
+- Optional: `{workDir}/discovery-context.json` (codebase context)
+
+## Execution Steps
+
+### Step 1: Load Phase 1 Context
+
+```javascript
+const specConfig = JSON.parse(Read(`${workDir}/spec-config.json`));
+const { seed_analysis, seed_input, focus_areas, has_codebase, depth } = specConfig;
+
+let discoveryContext = null;
+if (has_codebase) {
+  try {
+    discoveryContext = JSON.parse(Read(`${workDir}/discovery-context.json`));
+  } catch (e) { /* proceed without */ }
+}
+```
+
+### Step 2: CLI Gap Analysis & Question Generation
+
+调用 Gemini CLI 分析原始需求的完整性，识别模糊点并生成探测问题。
+
+```javascript
+Bash({
+  command: `ccw cli -p "PURPOSE: 深度分析用户的初始需求，识别模糊点、遗漏和需要澄清的领域。
+Success: 生成 3-5 个高质量的探测问题，覆盖功能范围、边界条件、非功能性需求、用户场景等维度。
+
+ORIGINAL SEED INPUT:
+${seed_input}
+
+SEED ANALYSIS:
+${JSON.stringify(seed_analysis, null, 2)}
+
+FOCUS AREAS: ${focus_areas.join(', ')}
+${discoveryContext ? `
+CODEBASE CONTEXT:
+- Existing patterns: ${discoveryContext.existing_patterns?.slice(0,5).join(', ') || 'none'}
+- Tech stack: ${JSON.stringify(discoveryContext.tech_stack || {})}
+` : ''}
+
+TASK:
+1. 评估当前需求描述的完整性（1-10 分，列出缺失维度）
+2. 识别 3-5 个关键模糊区域，每个区域包含：
+   - 模糊点描述（为什么不清楚）
+   - 1-2 个开放式探测问题
+   - 1-2 个扩展建议（基于领域最佳实践）
+3. 检查以下维度是否有遗漏：
+   - 功能范围边界（什么在范围内/外？）
+   - 核心用户场景和流程
+   - 非功能性需求（性能、安全、可用性、可扩展性）
+   - 集成点和外部依赖
+   - 数据模型和存储需求
+   - 错误处理和异常场景
+4. 基于领域经验提供需求扩展建议
+
+MODE: analysis
+EXPECTED: JSON output:
+{
+  \"completeness_score\": 7,
+  \"missing_dimensions\": [\"Performance requirements\", \"Error handling\"],
+  \"clarification_areas\": [
+    {
+      \"area\": \"Scope boundary\",
+      \"rationale\": \"Input does not clarify...\",
+      \"questions\": [\"Question 1?\", \"Question 2?\"],
+      \"suggestions\": [\"Suggestion 1\", \"Suggestion 2\"]
+    }
+  ],
+  \"expansion_recommendations\": [
+    {
+      \"category\": \"Non-functional\",
+      \"recommendation\": \"Consider adding...\",
+      \"priority\": \"high|medium|low\"
+    }
+  ]
+}
+CONSTRAINTS: 问题必须是开放式的，建议必须具体可执行，使用用户输入的语言
+" --tool gemini --mode analysis`,
+  run_in_background: true
+});
+// Wait for CLI result before continuing
+```
+
+解析 CLI 输出为结构化数据：
+```javascript
+const gapAnalysis = {
+  completeness_score: 0,
+  missing_dimensions: [],
+  clarification_areas: [],
+  expansion_recommendations: []
+};
+// Parse from CLI output
+```
+
+### Step 3: Interactive Discussion Loop
+
+核心多轮交互循环。每轮：展示分析结果 → 用户回应 → 更新需求状态 → 判断是否继续。
+
+```javascript
+// Initialize requirement state
+let requirementState = {
+  problem_statement: seed_analysis.problem_statement,
+  target_users: seed_analysis.target_users,
+  domain: seed_analysis.domain,
+  constraints: seed_analysis.constraints,
+  confirmed_features: [],
+  non_functional_requirements: [],
+  boundary_conditions: [],
+  integration_points: [],
+  key_assumptions: [],
+  discussion_rounds: 0
+};
+
+let discussionLog = [];
+let userSatisfied = false;
+
+// === Round 1: Present gap analysis results ===
+// Display completeness_score, clarification_areas, expansion_recommendations
+// Then ask user to respond
+
+while (!userSatisfied && requirementState.discussion_rounds < 5) {
+  requirementState.discussion_rounds++;
+
+  if (requirementState.discussion_rounds === 1) {
+    // --- First round: present initial gap analysis ---
+    // Format questions and suggestions from gapAnalysis for display
+    // Present as a structured summary to the user
+
+    AskUserQuestion({
+      questions: [
+        {
+          question: buildDiscussionPrompt(gapAnalysis, requirementState),
+          header: "Req Expand",
+          multiSelect: false,
+          options: [
+            { label: "I'll answer", description: "I have answers/feedback to provide (type in 'Other')" },
+            { label: "Accept all suggestions", description: "Accept all expansion recommendations as-is" },
+            { label: "Skip to generation", description: "Requirements are clear enough, proceed directly" }
+          ]
+        }
+      ]
+    });
+  } else {
+    // --- Subsequent rounds: refine based on user feedback ---
+    // Call CLI with accumulated context for follow-up analysis
+    Bash({
+      command: `ccw cli -p "PURPOSE: 基于用户最新回应，更新需求理解，识别剩余模糊点。
+
+CURRENT REQUIREMENT STATE:
+${JSON.stringify(requirementState, null, 2)}
+
+DISCUSSION HISTORY:
+${JSON.stringify(discussionLog, null, 2)}
+
+USER'S LATEST RESPONSE:
+${lastUserResponse}
+
+TASK:
+1. 将用户回应整合到需求状态中
+2. 识别 1-3 个仍需澄清或可扩展的领域
+3. 生成后续问题（如有必要）
+4. 如果需求已充分，输出最终需求摘要
+
+MODE: analysis
+EXPECTED: JSON output:
+{
+  \"updated_fields\": { /* fields to merge into requirementState */ },
+  \"status\": \"need_more_discussion\" | \"ready_for_confirmation\",
+  \"follow_up\": {
+    \"remaining_areas\": [{\"area\": \"...\", \"questions\": [\"...\"]}],
+    \"summary\": \"...\"
+  }
+}
+CONSTRAINTS: 避免重复已回答的问题，聚焦未覆盖的领域
+" --tool gemini --mode analysis`,
+      run_in_background: true
+    });
+    // Wait for CLI result, parse and continue
+
+    // If status === "ready_for_confirmation", break to confirmation step
+    // If status === "need_more_discussion", present follow-up questions
+
+    AskUserQuestion({
+      questions: [
+        {
+          question: buildFollowUpPrompt(followUpAnalysis, requirementState),
+          header: "Follow-up",
+          multiSelect: false,
+          options: [
+            { label: "I'll answer", description: "I have more feedback (type in 'Other')" },
+            { label: "Looks good", description: "Requirements are sufficiently clear now" },
+            { label: "Accept suggestions", description: "Accept remaining suggestions" }
+          ]
+        }
+      ]
+    });
+  }
+
+  // Process user response
+  // - "Skip to generation" / "Looks good" → userSatisfied = true
+  // - "Accept all suggestions" → merge suggestions into requirementState, userSatisfied = true
+  // - "I'll answer" (with Other text) → record in discussionLog, continue loop
+  // - User selects Other with custom text → parse and record
+
+  discussionLog.push({
+    round: requirementState.discussion_rounds,
+    agent_prompt: currentPrompt,
+    user_response: userResponse,
+    timestamp: new Date().toISOString()
+  });
+}
+```
+
+#### Helper: Build Discussion Prompt
+
+```javascript
+function buildDiscussionPrompt(gapAnalysis, state) {
+  let prompt = `## Requirement Analysis Results\n\n`;
+  prompt += `**Completeness Score**: ${gapAnalysis.completeness_score}/10\n`;
+
+  if (gapAnalysis.missing_dimensions.length > 0) {
+    prompt += `**Missing Dimensions**: ${gapAnalysis.missing_dimensions.join(', ')}\n\n`;
+  }
+
+  prompt += `### Key Questions\n\n`;
+  gapAnalysis.clarification_areas.forEach((area, i) => {
+    prompt += `**${i+1}. ${area.area}**\n`;
+    prompt += `  ${area.rationale}\n`;
+    area.questions.forEach(q => { prompt += `  - ${q}\n`; });
+    if (area.suggestions.length > 0) {
+      prompt += `  Suggestions: ${area.suggestions.join('; ')}\n`;
+    }
+    prompt += `\n`;
+  });
+
+  if (gapAnalysis.expansion_recommendations.length > 0) {
+    prompt += `### Expansion Recommendations\n\n`;
+    gapAnalysis.expansion_recommendations.forEach(rec => {
+      prompt += `- [${rec.priority}] **${rec.category}**: ${rec.recommendation}\n`;
+    });
+  }
+
+  prompt += `\nPlease answer the questions above, or choose an option below.`;
+  return prompt;
+}
+```
+
+### Step 4: Auto Mode Handling
+
+```javascript
+if (autoMode) {
+  // Skip interactive discussion
+  // CLI generates default requirement expansion based on seed_analysis
+  Bash({
+    command: `ccw cli -p "PURPOSE: 基于种子分析自动生成需求扩展，无需用户交互。
+
+SEED ANALYSIS:
+${JSON.stringify(seed_analysis, null, 2)}
+
+SEED INPUT: ${seed_input}
+DEPTH: ${depth}
+${discoveryContext ? `CODEBASE: ${JSON.stringify(discoveryContext.tech_stack || {})}` : ''}
+
+TASK:
+1. 基于领域最佳实践，自动扩展功能需求清单
+2. 推断合理的非功能性需求
+3. 识别明显的边界条件
+4. 列出关键假设
+
+MODE: analysis
+EXPECTED: JSON output matching refined-requirements.json schema
+CONSTRAINTS: 保守推断，只添加高置信度的扩展
+" --tool gemini --mode analysis`,
+    run_in_background: true
+  });
+  // Parse output directly into refined-requirements.json
+}
+```
+
+### Step 5: Generate Requirement Confirmation Summary
+
+在写入文件前，向用户展示最终的需求确认摘要（非 auto mode）。
+
+```javascript
+if (!autoMode) {
+  // Build confirmation summary from requirementState
+  const summary = buildConfirmationSummary(requirementState);
+
+  AskUserQuestion({
+    questions: [
+      {
+        question: `## Requirement Confirmation\n\n${summary}\n\nConfirm and proceed to specification generation?`,
+        header: "Confirm",
+        multiSelect: false,
+        options: [
+          { label: "Confirm & proceed", description: "Requirements confirmed, start spec generation" },
+          { label: "Need adjustments", description: "Go back and refine further" }
+        ]
+      }
+    ]
+  });
+
+  // If "Need adjustments" → loop back to Step 3
+  // If "Confirm & proceed" → continue to Step 6
+}
+```
+
+### Step 6: Write refined-requirements.json
+
+```javascript
+const refinedRequirements = {
+  session_id: specConfig.session_id,
+  phase: "1.5",
+  generated_at: new Date().toISOString(),
+  source: autoMode ? "auto-expansion" : "interactive-discussion",
+  discussion_rounds: requirementState.discussion_rounds,
+
+  // Core requirement content
+  clarified_problem_statement: requirementState.problem_statement,
+  confirmed_target_users: requirementState.target_users.map(u =>
+    typeof u === 'string' ? { name: u, needs: [], pain_points: [] } : u
+  ),
+  confirmed_domain: requirementState.domain,
+
+  confirmed_features: requirementState.confirmed_features.map(f => ({
+    name: f.name,
+    description: f.description,
+    acceptance_criteria: f.acceptance_criteria || [],
+    edge_cases: f.edge_cases || [],
+    priority: f.priority || "unset"
+  })),
+
+  non_functional_requirements: requirementState.non_functional_requirements.map(nfr => ({
+    type: nfr.type,    // Performance, Security, Usability, Scalability, etc.
+    details: nfr.details,
+    measurable_criteria: nfr.measurable_criteria || ""
+  })),
+
+  boundary_conditions: {
+    in_scope: requirementState.boundary_conditions.filter(b => b.scope === 'in'),
+    out_of_scope: requirementState.boundary_conditions.filter(b => b.scope === 'out'),
+    constraints: requirementState.constraints
+  },
+
+  integration_points: requirementState.integration_points,
+  key_assumptions: requirementState.key_assumptions,
+
+  // Traceability
+  discussion_log: autoMode ? [] : discussionLog
+};
+
+Write(`${workDir}/refined-requirements.json`, JSON.stringify(refinedRequirements, null, 2));
+```
+
+### Step 7: Update spec-config.json
+
+```javascript
+specConfig.refined_requirements_file = "refined-requirements.json";
+specConfig.phasesCompleted.push({
+  phase: 1.5,
+  name: "requirement-clarification",
+  output_file: "refined-requirements.json",
+  discussion_rounds: requirementState.discussion_rounds,
+  completed_at: new Date().toISOString()
+});
+
+Write(`${workDir}/spec-config.json`, JSON.stringify(specConfig, null, 2));
+```
+
+## Output
+
+- **File**: `refined-requirements.json`
+- **Format**: JSON
+- **Updated**: `spec-config.json` (added `refined_requirements_file` field and phase 1.5 to `phasesCompleted`)
+
+## Quality Checklist
+
+- [ ] Problem statement refined (>= 30 characters, more specific than seed)
+- [ ] At least 2 confirmed features with descriptions
+- [ ] At least 1 non-functional requirement identified
+- [ ] Boundary conditions defined (in-scope + out-of-scope)
+- [ ] Key assumptions listed (>= 1)
+- [ ] Discussion rounds recorded (>= 1 in interactive mode)
+- [ ] User explicitly confirmed requirements (non-auto mode)
+- [ ] `refined-requirements.json` written with valid JSON
+- [ ] `spec-config.json` updated with phase 1.5 completion
+
+## Next Phase
+
+Proceed to [Phase 2: Product Brief](02-product-brief.md). Phase 2 should load `refined-requirements.json` as primary input instead of relying solely on `spec-config.json.seed_analysis`.

.codex/skills/spec-generator/phases/01-discovery.md

@@ -0,0 +1,257 @@
+# Phase 1: Discovery
+
+Parse input, analyze the seed idea, optionally explore codebase, establish session configuration.
+
+## Objective
+
+- Generate session ID and create output directory
+- Parse user input (text description or file reference)
+- Analyze seed via Gemini CLI to extract problem space dimensions
+- Conditionally explore codebase for existing patterns and constraints
+- Gather user preferences (depth, focus areas) via interactive confirmation
+- Write `spec-config.json` as the session state file
+
+## Input
+
+- Dependency: `$ARGUMENTS` (user input from command)
+- Flags: `-y` (auto mode), `-c` (continue mode)
+
+## Execution Steps
+
+### Step 1: Session Initialization
+
+```javascript
+// Parse arguments
+const args = $ARGUMENTS;
+const autoMode = args.includes('-y') || args.includes('--yes');
+const continueMode = args.includes('-c') || args.includes('--continue');
+
+// Extract the idea/topic (remove flags)
+const idea = args.replace(/(-y|--yes|-c|--continue)\s*/g, '').trim();
+
+// Generate session ID
+const slug = idea.toLowerCase()
+  .replace(/[^a-z0-9\u4e00-\u9fff]+/g, '-')
+  .replace(/^-|-$/g, '')
+  .slice(0, 40);
+const date = new Date().toISOString().slice(0, 10);
+const sessionId = `SPEC-${slug}-${date}`;
+const workDir = `.workflow/.spec/${sessionId}`;
+
+// Check for continue mode
+if (continueMode) {
+  // Find existing session
+  const existingSessions = Glob('.workflow/.spec/SPEC-*/spec-config.json');
+  // If slug matches an existing session, load it and resume
+  // Read spec-config.json, find first incomplete phase, jump to that phase
+  return; // Resume logic handled by orchestrator
+}
+
+// Create output directory
+Bash(`mkdir -p "${workDir}"`);
+```
+
+### Step 2: Input Parsing
+
+```javascript
+// Determine input type
+if (idea.startsWith('@') || idea.endsWith('.md') || idea.endsWith('.txt')) {
+  // File reference - read and extract content
+  const filePath = idea.replace(/^@/, '');
+  const fileContent = Read(filePath);
+  // Use file content as the seed
+  inputType = 'file';
+  seedInput = fileContent;
+} else {
+  // Direct text description
+  inputType = 'text';
+  seedInput = idea;
+}
+```
+
+### Step 3: Seed Analysis via Gemini CLI
+
+```javascript
+Bash({
+  command: `ccw cli -p "PURPOSE: Analyze this seed idea/requirement to extract structured problem space dimensions.
+Success: Clear problem statement, target users, domain identification, 3-5 exploration dimensions.
+
+SEED INPUT:
+${seedInput}
+
+TASK:
+- Extract a clear problem statement (what problem does this solve?)
+- Identify target users (who benefits?)
+- Determine the domain (technical, business, consumer, etc.)
+- List constraints (budget, time, technical, regulatory)
+- Generate 3-5 exploration dimensions (key areas to investigate)
+- Assess complexity: simple (1-2 components), moderate (3-5 components), complex (6+ components)
+
+MODE: analysis
+EXPECTED: JSON output with fields: problem_statement, target_users[], domain, constraints[], dimensions[], complexity
+CONSTRAINTS: Be specific and actionable, not vague
+" --tool gemini --mode analysis`,
+  run_in_background: true
+});
+// Wait for CLI result before continuing
+```
+
+Parse the CLI output into structured `seedAnalysis`:
+```javascript
+const seedAnalysis = {
+  problem_statement: "...",
+  target_users: ["..."],
+  domain: "...",
+  constraints: ["..."],
+  dimensions: ["..."]
+};
+const complexity = "moderate"; // from CLI output
+```
+
+### Step 4: Codebase Exploration (Conditional)
+
+```javascript
+// Detect if running inside a project with code
+const hasCodebase = Glob('**/*.{ts,js,py,java,go,rs}').length > 0
+  || Glob('package.json').length > 0
+  || Glob('Cargo.toml').length > 0;
+
+if (hasCodebase) {
+  Agent({
+    subagent_type: "cli-explore-agent",
+    run_in_background: false,
+    description: `Explore codebase for spec: ${slug}`,
+    prompt: `
+## Spec Generator Context
+Topic: ${seedInput}
+Dimensions: ${seedAnalysis.dimensions.join(', ')}
+Session: ${workDir}
+
+## MANDATORY FIRST STEPS
+1. Search for code related to topic keywords
+2. Read project config files (package.json, pyproject.toml, etc.) if they exist
+
+## Exploration Focus
+- Identify existing implementations related to the topic
+- Find patterns that could inform architecture decisions
+- Map current architecture constraints
+- Locate integration points and dependencies
+
+## Output
+Write findings to: ${workDir}/discovery-context.json
+
+Schema:
+{
+  "relevant_files": [{"path": "...", "relevance": "high|medium|low", "rationale": "..."}],
+  "existing_patterns": ["pattern descriptions"],
+  "architecture_constraints": ["constraint descriptions"],
+  "integration_points": ["integration point descriptions"],
+  "tech_stack": {"languages": [], "frameworks": [], "databases": []},
+  "_metadata": { "exploration_type": "spec-discovery", "timestamp": "ISO8601" }
+}
+`
+  });
+}
+```
+
+### Step 5: User Confirmation (Interactive)
+
+```javascript
+if (!autoMode) {
+  // Confirm problem statement and select depth
+  AskUserQuestion({
+    questions: [
+      {
+        question: `Problem statement: "${seedAnalysis.problem_statement}" - Is this accurate?`,
+        header: "Problem",
+        multiSelect: false,
+        options: [
+          { label: "Accurate", description: "Proceed with this problem statement" },
+          { label: "Needs adjustment", description: "I'll refine the problem statement" }
+        ]
+      },
+      {
+        question: "What specification depth do you need?",
+        header: "Depth",
+        multiSelect: false,
+        options: [
+          { label: "Light", description: "Quick overview - key decisions only" },
+          { label: "Standard (Recommended)", description: "Balanced detail for most projects" },
+          { label: "Comprehensive", description: "Maximum detail for complex/critical projects" }
+        ]
+      },
+      {
+        question: "Which areas should we focus on?",
+        header: "Focus",
+        multiSelect: true,
+        options: seedAnalysis.dimensions.map(d => ({ label: d, description: `Explore ${d} in depth` }))
+      },
+      {
+        question: "What type of specification is this?",
+        header: "Spec Type",
+        multiSelect: false,
+        options: [
+          { label: "Service (Recommended)", description: "Long-running service with lifecycle, state machine, observability" },
+          { label: "API", description: "REST/GraphQL API with endpoints, auth, rate limiting" },
+          { label: "Library/SDK", description: "Reusable package with public API surface, examples" },
+          { label: "Platform", description: "Multi-component system, uses Service profile" }
+        ]
+      }
+    ]
+  });
+} else {
+  // Auto mode defaults
+  depth = "standard";
+  focusAreas = seedAnalysis.dimensions;
+  specType = "service"; // default for auto mode
+}
+```
+
+### Step 6: Write spec-config.json
+
+```javascript
+const specConfig = {
+  session_id: sessionId,
+  seed_input: seedInput,
+  input_type: inputType,
+  timestamp: new Date().toISOString(),
+  mode: autoMode ? "auto" : "interactive",
+  complexity: complexity,
+  depth: depth,
+  focus_areas: focusAreas,
+  seed_analysis: seedAnalysis,
+  has_codebase: hasCodebase,
+  spec_type: specType, // "service" | "api" | "library" | "platform"
+  iteration_count: 0,
+  iteration_history: [],
+  phasesCompleted: [
+    {
+      phase: 1,
+      name: "discovery",
+      output_file: "spec-config.json",
+      completed_at: new Date().toISOString()
+    }
+  ]
+};
+
+Write(`${workDir}/spec-config.json`, JSON.stringify(specConfig, null, 2));
+```
+
+## Output
+
+- **File**: `spec-config.json`
+- **File**: `discovery-context.json` (optional, if codebase detected)
+- **Format**: JSON
+
+## Quality Checklist
+
+- [ ] Session ID matches `SPEC-{slug}-{date}` format
+- [ ] Problem statement exists and is >= 20 characters
+- [ ] Target users identified (>= 1)
+- [ ] 3-5 exploration dimensions generated
+- [ ] spec-config.json written with all required fields
+- [ ] Output directory created
+
+## Next Phase
+
+Proceed to [Phase 2: Product Brief](02-product-brief.md) with the generated spec-config.json.

.codex/skills/spec-generator/phases/02-product-brief.md

@@ -0,0 +1,298 @@
+# Phase 2: Product Brief
+
+> **Execution Mode: Agent Delegated**
+> This phase is executed by a `doc-generator` agent. The orchestrator (SKILL.md) passes session context via the Task tool. The agent reads this file for instructions, executes all steps, writes output files, and returns a JSON summary.
+
+Generate a product brief through multi-perspective CLI analysis, establishing "what" and "why".
+
+## Objective
+
+- Read Phase 1 outputs (spec-config.json, discovery-context.json)
+- Launch 3 parallel CLI analyses from product, technical, and user perspectives
+- Synthesize convergent themes and conflicting views
+- Optionally refine with user input
+- Generate product-brief.md using template
+
+## Input
+
+- Dependency: `{workDir}/spec-config.json`
+- Primary: `{workDir}/refined-requirements.json` (Phase 1.5 output, preferred over raw seed_analysis)
+- Optional: `{workDir}/discovery-context.json`
+- Config: `{workDir}/spec-config.json`
+- Template: `templates/product-brief.md`
+
+## Execution Steps
+
+### Step 1: Load Phase 1 Context
+
+```javascript
+const specConfig = JSON.parse(Read(`${workDir}/spec-config.json`));
+const { seed_analysis, seed_input, has_codebase, depth, focus_areas } = specConfig;
+
+// Load refined requirements (Phase 1.5 output) - preferred over raw seed_analysis
+let refinedReqs = null;
+try {
+  refinedReqs = JSON.parse(Read(`${workDir}/refined-requirements.json`));
+} catch (e) {
+  // No refined requirements, fall back to seed_analysis
+}
+
+let discoveryContext = null;
+if (has_codebase) {
+  try {
+    discoveryContext = JSON.parse(Read(`${workDir}/discovery-context.json`));
+  } catch (e) {
+    // No discovery context available, proceed without
+  }
+}
+
+// Build shared context string for CLI prompts
+// Prefer refined requirements over raw seed_analysis
+const problem = refinedReqs?.clarified_problem_statement || seed_analysis.problem_statement;
+const users = refinedReqs?.confirmed_target_users?.map(u => u.name || u).join(', ')
+  || seed_analysis.target_users.join(', ');
+const domain = refinedReqs?.confirmed_domain || seed_analysis.domain;
+const constraints = refinedReqs?.boundary_conditions?.constraints?.join(', ')
+  || seed_analysis.constraints.join(', ');
+const features = refinedReqs?.confirmed_features?.map(f => f.name).join(', ') || '';
+const nfrs = refinedReqs?.non_functional_requirements?.map(n => `${n.type}: ${n.details}`).join('; ') || '';
+
+const sharedContext = `
+SEED: ${seed_input}
+PROBLEM: ${problem}
+TARGET USERS: ${users}
+DOMAIN: ${domain}
+CONSTRAINTS: ${constraints}
+FOCUS AREAS: ${focus_areas.join(', ')}
+${features ? `CONFIRMED FEATURES: ${features}` : ''}
+${nfrs ? `NON-FUNCTIONAL REQUIREMENTS: ${nfrs}` : ''}
+${discoveryContext ? `
+CODEBASE CONTEXT:
+- Existing patterns: ${discoveryContext.existing_patterns?.slice(0,5).join(', ') || 'none'}
+- Architecture constraints: ${discoveryContext.architecture_constraints?.slice(0,3).join(', ') || 'none'}
+- Tech stack: ${JSON.stringify(discoveryContext.tech_stack || {})}
+` : ''}`;
+```
+
+### Step 2: Multi-CLI Parallel Analysis (3 perspectives)
+
+Launch 3 CLI calls in parallel:
+
+**Product Perspective (Gemini)**:
+```javascript
+Bash({
+  command: `ccw cli -p "PURPOSE: Product analysis for specification - identify market fit, user value, and success criteria.
+Success: Clear vision, measurable goals, competitive positioning.
+
+${sharedContext}
+
+TASK:
+- Define product vision (1-3 sentences, aspirational)
+- Analyze market/competitive landscape
+- Define 3-5 measurable success metrics
+- Identify scope boundaries (in-scope vs out-of-scope)
+- Assess user value proposition
+- List assumptions that need validation
+
+MODE: analysis
+EXPECTED: Structured product analysis with: vision, goals with metrics, scope, competitive positioning, assumptions
+CONSTRAINTS: Focus on 'what' and 'why', not 'how'
+" --tool gemini --mode analysis`,
+  run_in_background: true
+});
+```
+
+**Technical Perspective (Codex)**:
+```javascript
+Bash({
+  command: `ccw cli -p "PURPOSE: Technical feasibility analysis for specification - assess implementation viability and constraints.
+Success: Clear technical constraints, integration complexity, technology recommendations.
+
+${sharedContext}
+
+TASK:
+- Assess technical feasibility of the core concept
+- Identify technical constraints and blockers
+- Evaluate integration complexity with existing systems
+- Recommend technology approach (high-level)
+- Identify technical risks and dependencies
+- Estimate complexity: simple/moderate/complex
+
+MODE: analysis
+EXPECTED: Technical analysis with: feasibility assessment, constraints, integration complexity, tech recommendations, risks
+CONSTRAINTS: Focus on feasibility and constraints, not detailed architecture
+" --tool codex --mode analysis`,
+  run_in_background: true
+});
+```
+
+**User Perspective (Claude)**:
+```javascript
+Bash({
+  command: `ccw cli -p "PURPOSE: User experience analysis for specification - understand user journeys, pain points, and UX considerations.
+Success: Clear user personas, journey maps, UX requirements.
+
+${sharedContext}
+
+TASK:
+- Elaborate user personas with goals and frustrations
+- Map primary user journey (happy path)
+- Identify key pain points in current experience
+- Define UX success criteria
+- List accessibility and usability considerations
+- Suggest interaction patterns
+
+MODE: analysis
+EXPECTED: User analysis with: personas, journey map, pain points, UX criteria, interaction recommendations
+CONSTRAINTS: Focus on user needs and experience, not implementation
+" --tool claude --mode analysis`,
+  run_in_background: true
+});
+
+// STOP: Wait for all 3 CLI results before continuing
+```
+
+### Step 3: Synthesize Perspectives
+
+```javascript
+// After receiving all 3 CLI results:
+// Extract convergent themes (all agree)
+// Identify conflicting views (need resolution)
+// Note unique contributions from each perspective
+
+const synthesis = {
+  convergent_themes: [], // themes all 3 perspectives agree on
+  conflicts: [],         // areas where perspectives differ
+  product_insights: [],  // unique from product perspective
+  technical_insights: [], // unique from technical perspective
+  user_insights: []      // unique from user perspective
+};
+```
+
+### Step 4: Interactive Refinement (Optional)
+
+```javascript
+if (!autoMode) {
+  // Present synthesis summary to user
+  // AskUserQuestion with:
+  // - Confirm vision statement
+  // - Resolve any conflicts between perspectives
+  // - Adjust scope if needed
+  AskUserQuestion({
+    questions: [
+      {
+        question: "Review the synthesized product brief. Any adjustments needed?",
+        header: "Review",
+        multiSelect: false,
+        options: [
+          { label: "Looks good", description: "Proceed to PRD generation" },
+          { label: "Adjust scope", description: "Narrow or expand the scope" },
+          { label: "Revise vision", description: "Refine the vision statement" }
+        ]
+      }
+    ]
+  });
+}
+```
+
+### Step 5: Generate product-brief.md
+
+```javascript
+// Read template
+const template = Read('templates/product-brief.md');
+
+// Fill template with synthesized content
+// Apply document-standards.md formatting rules
+// Write with YAML frontmatter
+
+const frontmatter = `---
+session_id: ${specConfig.session_id}
+phase: 2
+document_type: product-brief
+status: ${autoMode ? 'complete' : 'draft'}
+generated_at: ${new Date().toISOString()}
+stepsCompleted: ["load-context", "multi-cli-analysis", "synthesis", "generation"]
+version: 1
+dependencies:
+  - spec-config.json
+---`;
+
+// Combine frontmatter + filled template content
+Write(`${workDir}/product-brief.md`, `${frontmatter}\n\n${filledContent}`);
+
+// Update spec-config.json
+specConfig.phasesCompleted.push({
+  phase: 2,
+  name: "product-brief",
+  output_file: "product-brief.md",
+  completed_at: new Date().toISOString()
+});
+Write(`${workDir}/spec-config.json`, JSON.stringify(specConfig, null, 2));
+```
+
+### Step 5.5: Generate glossary.json
+
+```javascript
+// Extract terminology from product brief and CLI analysis
+// Generate structured glossary for cross-document consistency
+
+const glossary = {
+  session_id: specConfig.session_id,
+  terms: [
+    // Extract from product brief content:
+    // - Key domain nouns from problem statement
+    // - User persona names
+    // - Technical terms from multi-perspective synthesis
+    // Each term should have:
+    // { term: "...", definition: "...", aliases: [], first_defined_in: "product-brief.md", category: "core|technical|business" }
+  ]
+};
+
+Write(`${workDir}/glossary.json`, JSON.stringify(glossary, null, 2));
+```
+
+**Glossary Injection**: In all subsequent phase prompts, inject the following into the CONTEXT section:
+```
+TERMINOLOGY GLOSSARY (use these terms consistently):
+${JSON.stringify(glossary.terms, null, 2)}
+```
+
+## Output
+
+- **File**: `product-brief.md`
+- **Format**: Markdown with YAML frontmatter
+
+## Quality Checklist
+
+- [ ] Vision statement: clear, 1-3 sentences
+- [ ] Problem statement: specific and measurable
+- [ ] Target users: >= 1 persona with needs
+- [ ] Goals: >= 2 with measurable metrics
+- [ ] Scope: in-scope and out-of-scope defined
+- [ ] Multi-perspective synthesis included
+- [ ] YAML frontmatter valid
+
+## Next Phase
+
+Proceed to [Phase 3: Requirements](03-requirements.md) with the generated product-brief.md.
+
+---
+
+## Agent Return Summary
+
+When executed as a delegated agent, return the following JSON summary to the orchestrator:
+
+```json
+{
+  "phase": 2,
+  "status": "complete",
+  "files_created": ["product-brief.md", "glossary.json"],
+  "quality_notes": ["list of any quality concerns or deviations"],
+  "key_decisions": ["list of significant synthesis decisions made"]
+}
+```
+
+The orchestrator will:
+1. Validate that listed files exist on disk
+2. Read `spec-config.json` to confirm `phasesCompleted` was updated
+3. Store the summary for downstream phase context

.codex/skills/spec-generator/phases/03-requirements.md

@@ -0,0 +1,248 @@
+# Phase 3: Requirements (PRD)
+
+> **Execution Mode: Agent Delegated**
+> This phase is executed by a `doc-generator` agent. The orchestrator (SKILL.md) passes session context via the Task tool. The agent reads this file for instructions, executes all steps, writes output files, and returns a JSON summary.
+
+Generate a detailed Product Requirements Document with functional/non-functional requirements, acceptance criteria, and MoSCoW prioritization.
+
+## Objective
+
+- Read product-brief.md and extract goals, scope, constraints
+- Expand each goal into functional requirements with acceptance criteria
+- Generate non-functional requirements
+- Apply MoSCoW priority labels (user input or auto)
+- Generate requirements.md using template
+
+## Input
+
+- Dependency: `{workDir}/product-brief.md`
+- Config: `{workDir}/spec-config.json`
+- Template: `templates/requirements-prd.md` (directory structure: `_index.md` + `REQ-*.md` + `NFR-*.md`)
+
+## Execution Steps
+
+### Step 1: Load Phase 2 Context
+
+```javascript
+const specConfig = JSON.parse(Read(`${workDir}/spec-config.json`));
+const productBrief = Read(`${workDir}/product-brief.md`);
+
+// Extract key sections from product brief
+// - Goals & Success Metrics table
+// - Scope (in-scope items)
+// - Target Users (personas)
+// - Constraints
+// - Technical perspective insights
+```
+
+### Step 2: Requirements Expansion via Gemini CLI
+
+```javascript
+Bash({
+  command: `ccw cli -p "PURPOSE: Generate detailed functional and non-functional requirements from product brief.
+Success: Complete PRD with testable acceptance criteria for every requirement.
+
+PRODUCT BRIEF CONTEXT:
+${productBrief}
+
+TASK:
+- For each goal in the product brief, generate 3-7 functional requirements
+- Each requirement must have:
+  - Unique ID: REQ-NNN (zero-padded)
+  - Clear title
+  - Detailed description
+  - User story: As a [persona], I want [action] so that [benefit]
+  - 2-4 specific, testable acceptance criteria
+- Generate non-functional requirements:
+  - Performance (response times, throughput)
+  - Security (authentication, authorization, data protection)
+  - Scalability (user load, data volume)
+  - Usability (accessibility, learnability)
+- Assign initial MoSCoW priority based on:
+  - Must: Core functionality, cannot launch without
+  - Should: Important but has workaround
+  - Could: Nice-to-have, enhances experience
+  - Won't: Explicitly deferred
+- Use RFC 2119 keywords (MUST, SHOULD, MAY, MUST NOT, SHOULD NOT) to define behavioral constraints for each requirement. Example: 'The system MUST return a 401 response within 100ms for invalid tokens.'
+- For each core domain entity referenced in requirements, define its data model: fields, types, constraints, and relationships to other entities
+- Maintain terminology consistency with the glossary below:
+  TERMINOLOGY GLOSSARY:
+  \${glossary ? JSON.stringify(glossary.terms, null, 2) : 'N/A - generate terms inline'}
+
+MODE: analysis
+EXPECTED: Structured requirements with: ID, title, description, user story, acceptance criteria, priority, traceability to goals
+CONSTRAINTS: Every requirement must be specific enough to estimate and test. No vague requirements like 'system should be fast'.
+" --tool gemini --mode analysis`,
+  run_in_background: true
+});
+
+// Wait for CLI result
+```
+
+### Step 2.5: Codex Requirements Review
+
+After receiving Gemini expansion results, validate requirements quality via Codex CLI before proceeding:
+
+```javascript
+Bash({
+  command: `ccw cli -p "PURPOSE: Critical review of generated requirements - validate quality, testability, and scope alignment.
+Success: Actionable feedback on requirement quality with specific issues identified.
+
+GENERATED REQUIREMENTS:
+${geminiRequirementsOutput.slice(0, 5000)}
+
+PRODUCT BRIEF SCOPE:
+${productBrief.slice(0, 2000)}
+
+TASK:
+- Verify every acceptance criterion is specific, measurable, and testable (not vague like 'should be fast')
+- Validate RFC 2119 keyword usage: MUST/SHOULD/MAY used correctly per RFC 2119 semantics
+- Check scope containment: no requirement exceeds the product brief's defined scope boundaries
+- Assess data model completeness: all referenced entities have field-level definitions
+- Identify duplicate or overlapping requirements
+- Rate overall requirements quality: 1-5 with justification
+
+MODE: analysis
+EXPECTED: Requirements review with: per-requirement feedback, testability assessment, scope violations, data model gaps, quality rating
+CONSTRAINTS: Be genuinely critical. Focus on requirements that would block implementation if left vague.
+" --tool codex --mode analysis`,
+  run_in_background: true
+});
+
+// Wait for Codex review result
+// Integrate feedback into requirements before writing files:
+// - Fix vague acceptance criteria flagged by Codex
+// - Correct RFC 2119 keyword misuse
+// - Remove or flag requirements that exceed brief scope
+// - Fill data model gaps identified by Codex
+```
+
+### Step 3: User Priority Sorting (Interactive)
+
+```javascript
+if (!autoMode) {
+  // Present requirements grouped by initial priority
+  // Allow user to adjust MoSCoW labels
+  AskUserQuestion({
+    questions: [
+      {
+        question: "Review the Must-Have requirements. Any that should be reprioritized?",
+        header: "Must-Have",
+        multiSelect: false,
+        options: [
+          { label: "All correct", description: "Must-have requirements are accurate" },
+          { label: "Too many", description: "Some should be Should/Could" },
+          { label: "Missing items", description: "Some Should requirements should be Must" }
+        ]
+      },
+      {
+        question: "What is the target MVP scope?",
+        header: "MVP Scope",
+        multiSelect: false,
+        options: [
+          { label: "Must-Have only (Recommended)", description: "MVP includes only Must requirements" },
+          { label: "Must + key Should", description: "Include critical Should items in MVP" },
+          { label: "Comprehensive", description: "Include all Must and Should" }
+        ]
+      }
+    ]
+  });
+  // Apply user adjustments to priorities
+} else {
+  // Auto mode: accept CLI-suggested priorities as-is
+}
+```
+
+### Step 4: Generate requirements/ directory
+
+```javascript
+// Read template
+const template = Read('templates/requirements-prd.md');
+
+// Create requirements directory
+Bash(`mkdir -p "${workDir}/requirements"`);
+
+const status = autoMode ? 'complete' : 'draft';
+const timestamp = new Date().toISOString();
+
+// Parse CLI output into structured requirements
+const funcReqs = parseFunctionalRequirements(cliOutput);  // [{id, slug, title, priority, ...}]
+const nfReqs = parseNonFunctionalRequirements(cliOutput);  // [{id, type, slug, title, ...}]
+
+// Step 4a: Write individual REQ-*.md files (one per functional requirement)
+funcReqs.forEach(req => {
+  // Use REQ-NNN-{slug}.md template from templates/requirements-prd.md
+  // Fill: id, title, priority, description, user_story, acceptance_criteria, traces
+  Write(`${workDir}/requirements/REQ-${req.id}-${req.slug}.md`, reqContent);
+});
+
+// Step 4b: Write individual NFR-*.md files (one per non-functional requirement)
+nfReqs.forEach(nfr => {
+  // Use NFR-{type}-NNN-{slug}.md template from templates/requirements-prd.md
+  // Fill: id, type, category, title, requirement, metric, target, traces
+  Write(`${workDir}/requirements/NFR-${nfr.type}-${nfr.id}-${nfr.slug}.md`, nfrContent);
+});
+
+// Step 4c: Write _index.md (summary + links to all individual files)
+// Use _index.md template from templates/requirements-prd.md
+// Fill: summary table, functional req links table, NFR links tables,
+//       data requirements, integration requirements, traceability matrix
+Write(`${workDir}/requirements/_index.md`, indexContent);
+
+// Update spec-config.json
+specConfig.phasesCompleted.push({
+  phase: 3,
+  name: "requirements",
+  output_dir: "requirements/",
+  output_index: "requirements/_index.md",
+  file_count: funcReqs.length + nfReqs.length + 1,
+  completed_at: timestamp
+});
+Write(`${workDir}/spec-config.json`, JSON.stringify(specConfig, null, 2));
+```
+
+## Output
+
+- **Directory**: `requirements/`
+  - `_index.md` — Summary, MoSCoW table, traceability matrix, links
+  - `REQ-NNN-{slug}.md` — Individual functional requirement (per requirement)
+  - `NFR-{type}-NNN-{slug}.md` — Individual non-functional requirement (per NFR)
+- **Format**: Markdown with YAML frontmatter, cross-linked via relative paths
+
+## Quality Checklist
+
+- [ ] Functional requirements: >= 3 with REQ-NNN IDs, each in own file
+- [ ] Every requirement file has >= 1 acceptance criterion
+- [ ] Every requirement has MoSCoW priority tag in frontmatter
+- [ ] Non-functional requirements: >= 1, each in own file
+- [ ] User stories present for Must-have requirements
+- [ ] `_index.md` links to all individual requirement files
+- [ ] Traceability links to product-brief.md goals
+- [ ] All files have valid YAML frontmatter
+
+## Next Phase
+
+Proceed to [Phase 4: Architecture](04-architecture.md) with the generated requirements.md.
+
+---
+
+## Agent Return Summary
+
+When executed as a delegated agent, return the following JSON summary to the orchestrator:
+
+```json
+{
+  "phase": 3,
+  "status": "complete",
+  "files_created": ["requirements/_index.md", "requirements/REQ-001-*.md", "..."],
+  "file_count": 0,
+  "codex_review_integrated": true,
+  "quality_notes": ["list of quality concerns or Codex feedback items addressed"],
+  "key_decisions": ["MoSCoW priority rationale", "scope adjustments from Codex review"]
+}
+```
+
+The orchestrator will:
+1. Validate that `requirements/` directory exists with `_index.md` and individual files
+2. Read `spec-config.json` to confirm `phasesCompleted` was updated
+3. Store the summary for downstream phase context

.codex/skills/spec-generator/phases/04-architecture.md

@@ -0,0 +1,274 @@
+# Phase 4: Architecture
+
+> **Execution Mode: Agent Delegated**
+> This phase is executed by a `doc-generator` agent. The orchestrator (SKILL.md) passes session context via the Task tool. The agent reads this file for instructions, executes all steps, writes output files, and returns a JSON summary.
+
+Generate technical architecture decisions, component design, and technology selections based on requirements.
+
+## Objective
+
+- Analyze requirements to identify core components and system architecture
+- Generate Architecture Decision Records (ADRs) with alternatives
+- Map architecture to existing codebase (if applicable)
+- Challenge architecture via Codex CLI review
+- Generate architecture.md using template
+
+## Input
+
+- Dependency: `{workDir}/requirements/_index.md` (and individual `REQ-*.md` files)
+- Reference: `{workDir}/product-brief.md`
+- Optional: `{workDir}/discovery-context.json`
+- Config: `{workDir}/spec-config.json`
+- Template: `templates/architecture-doc.md`
+
+## Execution Steps
+
+### Step 1: Load Phase 2-3 Context
+
+```javascript
+const specConfig = JSON.parse(Read(`${workDir}/spec-config.json`));
+const productBrief = Read(`${workDir}/product-brief.md`);
+const requirements = Read(`${workDir}/requirements.md`);
+
+let discoveryContext = null;
+if (specConfig.has_codebase) {
+  try {
+    discoveryContext = JSON.parse(Read(`${workDir}/discovery-context.json`));
+  } catch (e) { /* no context */ }
+}
+
+// Load glossary for terminology consistency
+let glossary = null;
+try {
+  glossary = JSON.parse(Read(`${workDir}/glossary.json`));
+} catch (e) { /* proceed without */ }
+
+// Load spec type profile for specialized sections
+const specType = specConfig.spec_type || 'service';
+let profile = null;
+try {
+  profile = Read(`templates/profiles/${specType}-profile.md`);
+} catch (e) { /* use base template only */ }
+```
+
+### Step 2: Architecture Analysis via Gemini CLI
+
+```javascript
+Bash({
+  command: `ccw cli -p "PURPOSE: Generate technical architecture for the specified requirements.
+Success: Complete component architecture, tech stack, and ADRs with justified decisions.
+
+PRODUCT BRIEF (summary):
+${productBrief.slice(0, 3000)}
+
+REQUIREMENTS:
+${requirements.slice(0, 5000)}
+
+${discoveryContext ? `EXISTING CODEBASE:
+- Tech stack: ${JSON.stringify(discoveryContext.tech_stack || {})}
+- Existing patterns: ${discoveryContext.existing_patterns?.slice(0,5).join('; ') || 'none'}
+- Architecture constraints: ${discoveryContext.architecture_constraints?.slice(0,3).join('; ') || 'none'}
+` : ''}
+
+TASK:
+- Define system architecture style (monolith, microservices, serverless, etc.) with justification
+- Identify core components and their responsibilities
+- Create component interaction diagram (Mermaid graph TD format)
+- Specify technology stack: languages, frameworks, databases, infrastructure
+- Generate 2-4 Architecture Decision Records (ADRs):
+  - Each ADR: context, decision, 2-3 alternatives with pros/cons, consequences
+  - Focus on: data storage, API design, authentication, key technical choices
+- Define data model: key entities and relationships (Mermaid erDiagram format)
+- Identify security architecture: auth, authorization, data protection
+- List API endpoints (high-level)
+${discoveryContext ? '- Map new components to existing codebase modules' : ''}
+- For each core entity with a lifecycle, create an ASCII state machine diagram showing:
+  - All states and transitions
+  - Trigger events for each transition
+  - Side effects of transitions
+  - Error states and recovery paths
+- Define a Configuration Model: list all configurable fields with name, type, default value, constraint, and description
+- Define Error Handling strategy:
+  - Classify errors (transient/permanent/degraded)
+  - Per-component error behavior using RFC 2119 keywords
+  - Recovery mechanisms
+- Define Observability requirements:
+  - Key metrics (name, type: counter/gauge/histogram, labels)
+  - Structured log format and key log events
+  - Health check endpoints
+\${profile ? \`
+SPEC TYPE PROFILE REQUIREMENTS (\${specType}):
+\${profile}
+\` : ''}
+\${glossary ? \`
+TERMINOLOGY GLOSSARY (use consistently):
+\${JSON.stringify(glossary.terms, null, 2)}
+\` : ''}
+
+MODE: analysis
+EXPECTED: Complete architecture with: style justification, component diagram, tech stack table, ADRs, data model, security controls, API overview
+CONSTRAINTS: Architecture must support all Must-have requirements. Prefer proven technologies over cutting-edge.
+" --tool gemini --mode analysis`,
+  run_in_background: true
+});
+
+// Wait for CLI result
+```
+
+### Step 3: Architecture Review via Codex CLI
+
+```javascript
+// After receiving Gemini analysis, challenge it with Codex
+Bash({
+  command: `ccw cli -p "PURPOSE: Critical review of proposed architecture - identify weaknesses and risks.
+Success: Actionable feedback with specific concerns and improvement suggestions.
+
+PROPOSED ARCHITECTURE:
+${geminiArchitectureOutput.slice(0, 5000)}
+
+REQUIREMENTS CONTEXT:
+${requirements.slice(0, 2000)}
+
+TASK:
+- Challenge each ADR: are the alternatives truly the best options?
+- Identify scalability bottlenecks in the component design
+- Assess security gaps: authentication, authorization, data protection
+- Evaluate technology choices: maturity, community support, fit
+- Check for over-engineering or under-engineering
+- Verify architecture covers all Must-have requirements
+- Rate overall architecture quality: 1-5 with justification
+
+MODE: analysis
+EXPECTED: Architecture review with: per-ADR feedback, scalability concerns, security gaps, technology risks, quality rating
+CONSTRAINTS: Be genuinely critical, not just validating. Focus on actionable improvements.
+" --tool codex --mode analysis`,
+  run_in_background: true
+});
+
+// Wait for CLI result
+```
+
+### Step 4: Interactive ADR Decisions (Optional)
+
+```javascript
+if (!autoMode) {
+  // Present ADRs with review feedback to user
+  // For each ADR where review raised concerns:
+  AskUserQuestion({
+    questions: [
+      {
+        question: "Architecture review raised concerns. How should we proceed?",
+        header: "ADR Review",
+        multiSelect: false,
+        options: [
+          { label: "Accept as-is", description: "Architecture is sound, proceed" },
+          { label: "Incorporate feedback", description: "Adjust ADRs based on review" },
+          { label: "Simplify", description: "Reduce complexity, fewer components" }
+        ]
+      }
+    ]
+  });
+  // Apply user decisions to architecture
+}
+```
+
+### Step 5: Codebase Integration Mapping (Conditional)
+
+```javascript
+if (specConfig.has_codebase && discoveryContext) {
+  // Map new architecture components to existing code
+  const integrationMapping = discoveryContext.relevant_files.map(f => ({
+    new_component: "...", // matched from architecture
+    existing_module: f.path,
+    integration_type: "Extend|Replace|New",
+    notes: f.rationale
+  }));
+  // Include in architecture document
+}
+```
+
+### Step 6: Generate architecture/ directory
+
+```javascript
+const template = Read('templates/architecture-doc.md');
+
+// Create architecture directory
+Bash(`mkdir -p "${workDir}/architecture"`);
+
+const status = autoMode ? 'complete' : 'draft';
+const timestamp = new Date().toISOString();
+
+// Parse CLI outputs into structured ADRs
+const adrs = parseADRs(geminiArchitectureOutput, codexReviewOutput);  // [{id, slug, title, ...}]
+
+// Step 6a: Write individual ADR-*.md files (one per decision)
+adrs.forEach(adr => {
+  // Use ADR-NNN-{slug}.md template from templates/architecture-doc.md
+  // Fill: id, title, status, context, decision, alternatives, consequences, traces
+  Write(`${workDir}/architecture/ADR-${adr.id}-${adr.slug}.md`, adrContent);
+});
+
+// Step 6b: Write _index.md (overview + components + tech stack + links to ADRs)
+// Use _index.md template from templates/architecture-doc.md
+// Fill: system overview, component diagram, tech stack, ADR links table,
+//       data model, API design, security controls, infrastructure, codebase integration
+Write(`${workDir}/architecture/_index.md`, indexContent);
+
+// Update spec-config.json
+specConfig.phasesCompleted.push({
+  phase: 4,
+  name: "architecture",
+  output_dir: "architecture/",
+  output_index: "architecture/_index.md",
+  file_count: adrs.length + 1,
+  completed_at: timestamp
+});
+Write(`${workDir}/spec-config.json`, JSON.stringify(specConfig, null, 2));
+```
+
+## Output
+
+- **Directory**: `architecture/`
+  - `_index.md` — Overview, component diagram, tech stack, data model, security, links
+  - `ADR-NNN-{slug}.md` — Individual Architecture Decision Record (per ADR)
+- **Format**: Markdown with YAML frontmatter, cross-linked to requirements via relative paths
+
+## Quality Checklist
+
+- [ ] Component diagram present in `_index.md` (Mermaid or ASCII)
+- [ ] Tech stack specified (languages, frameworks, key libraries)
+- [ ] >= 1 ADR file with alternatives considered
+- [ ] Each ADR file lists >= 2 options
+- [ ] `_index.md` ADR table links to all individual ADR files
+- [ ] Integration points identified
+- [ ] Data model described
+- [ ] Codebase mapping present (if has_codebase)
+- [ ] All files have valid YAML frontmatter
+- [ ] ADR files link back to requirement files
+
+## Next Phase
+
+Proceed to [Phase 5: Epics & Stories](05-epics-stories.md) with the generated architecture.md.
+
+---
+
+## Agent Return Summary
+
+When executed as a delegated agent, return the following JSON summary to the orchestrator:
+
+```json
+{
+  "phase": 4,
+  "status": "complete",
+  "files_created": ["architecture/_index.md", "architecture/ADR-001-*.md", "..."],
+  "file_count": 0,
+  "codex_review_rating": 0,
+  "quality_notes": ["list of quality concerns or review feedback addressed"],
+  "key_decisions": ["architecture style choice", "key ADR decisions"]
+}
+```
+
+The orchestrator will:
+1. Validate that `architecture/` directory exists with `_index.md` and ADR files
+2. Read `spec-config.json` to confirm `phasesCompleted` was updated
+3. Store the summary for downstream phase context

.codex/skills/spec-generator/phases/05-epics-stories.md

@@ -0,0 +1,241 @@
+# Phase 5: Epics & Stories
+
+> **Execution Mode: Agent Delegated**
+> This phase is executed by a `doc-generator` agent. The orchestrator (SKILL.md) passes session context via the Task tool. The agent reads this file for instructions, executes all steps, writes output files, and returns a JSON summary.
+
+Decompose the specification into executable Epics and Stories with dependency mapping.
+
+## Objective
+
+- Group requirements into 3-7 logical Epics
+- Tag MVP subset of Epics
+- Generate 2-5 Stories per Epic in standard user story format
+- Map cross-Epic dependencies (Mermaid diagram)
+- Generate epics.md using template
+
+## Input
+
+- Dependency: `{workDir}/requirements/_index.md`, `{workDir}/architecture/_index.md` (and individual files)
+- Reference: `{workDir}/product-brief.md`
+- Config: `{workDir}/spec-config.json`
+- Template: `templates/epics-template.md` (directory structure: `_index.md` + `EPIC-*.md`)
+
+## Execution Steps
+
+### Step 1: Load Phase 2-4 Context
+
+```javascript
+const specConfig = JSON.parse(Read(`${workDir}/spec-config.json`));
+const productBrief = Read(`${workDir}/product-brief.md`);
+const requirements = Read(`${workDir}/requirements.md`);
+const architecture = Read(`${workDir}/architecture.md`);
+
+let glossary = null;
+try {
+  glossary = JSON.parse(Read(`${workDir}/glossary.json`));
+} catch (e) { /* proceed without */ }
+```
+
+### Step 2: Epic Decomposition via Gemini CLI
+
+```javascript
+Bash({
+  command: `ccw cli -p "PURPOSE: Decompose requirements into executable Epics and Stories for implementation planning.
+Success: 3-7 Epics with prioritized Stories, dependency map, and MVP subset clearly defined.
+
+PRODUCT BRIEF (summary):
+${productBrief.slice(0, 2000)}
+
+REQUIREMENTS:
+${requirements.slice(0, 5000)}
+
+ARCHITECTURE (summary):
+${architecture.slice(0, 3000)}
+
+TASK:
+- Group requirements into 3-7 logical Epics:
+  - Each Epic: EPIC-NNN ID, title, description, priority (Must/Should/Could)
+  - Group by functional domain or user journey stage
+  - Tag MVP Epics (minimum set for initial release)
+  
+- For each Epic, generate 2-5 Stories:
+  - Each Story: STORY-{EPIC}-NNN ID, title
+  - User story format: As a [persona], I want [action] so that [benefit]
+  - 2-4 acceptance criteria per story (testable)
+  - Relative size estimate: S/M/L/XL
+  - Trace to source requirement(s): REQ-NNN
+  
+- Create dependency map:
+  - Cross-Epic dependencies (which Epics block others)
+  - Mermaid graph LR format
+  - Recommended execution order with rationale
+  
+- Define MVP:
+  - Which Epics are in MVP
+  - MVP definition of done (3-5 criteria)
+  - What is explicitly deferred post-MVP
+
+MODE: analysis
+EXPECTED: Structured output with: Epic list (ID, title, priority, MVP flag), Stories per Epic (ID, user story, AC, size, trace), dependency Mermaid diagram, execution order, MVP definition
+CONSTRAINTS:
+- Every Must-have requirement must appear in at least one Story
+- Stories must be small enough to implement independently (no XL stories in MVP)
+- Dependencies should be minimized across Epics
+\${glossary ? \`- Maintain terminology consistency with glossary: \${glossary.terms.map(t => t.term).join(', ')}\` : ''}
+" --tool gemini --mode analysis`,
+  run_in_background: true
+});
+
+// Wait for CLI result
+```
+
+### Step 2.5: Codex Epics Review
+
+After receiving Gemini decomposition results, validate epic/story quality via Codex CLI:
+
+```javascript
+Bash({
+  command: `ccw cli -p "PURPOSE: Critical review of epic/story decomposition - validate coverage, sizing, and dependency structure.
+Success: Actionable feedback on epic quality with specific issues identified.
+
+GENERATED EPICS AND STORIES:
+${geminiEpicsOutput.slice(0, 5000)}
+
+REQUIREMENTS (Must-Have):
+${mustHaveRequirements.slice(0, 2000)}
+
+TASK:
+- Verify Must-Have requirement coverage: every Must requirement appears in at least one Story
+- Check MVP story sizing: no XL stories in MVP epics (too large to implement independently)
+- Validate dependency graph: no circular dependencies between Epics
+- Assess acceptance criteria: every Story AC is specific and testable
+- Verify traceability: Stories trace back to specific REQ-NNN IDs
+- Check Epic granularity: 3-7 epics (not too few/many), 2-5 stories each
+- Rate overall decomposition quality: 1-5 with justification
+
+MODE: analysis
+EXPECTED: Epic review with: coverage gaps, oversized stories, dependency issues, traceability gaps, quality rating
+CONSTRAINTS: Focus on issues that would block execution planning. Be specific about which Story/Epic has problems.
+" --tool codex --mode analysis`,
+  run_in_background: true
+});
+
+// Wait for Codex review result
+// Integrate feedback into epics before writing files:
+// - Add missing Stories for uncovered Must requirements
+// - Split XL stories in MVP epics into smaller units
+// - Fix dependency cycles identified by Codex
+// - Improve vague acceptance criteria
+```
+
+### Step 3: Interactive Validation (Optional)
+
+```javascript
+if (!autoMode) {
+  // Present Epic overview table and dependency diagram
+  AskUserQuestion({
+    questions: [
+      {
+        question: "Review the Epic breakdown. Any adjustments needed?",
+        header: "Epics",
+        multiSelect: false,
+        options: [
+          { label: "Looks good", description: "Epic structure is appropriate" },
+          { label: "Merge epics", description: "Some epics should be combined" },
+          { label: "Split epic", description: "An epic is too large, needs splitting" },
+          { label: "Adjust MVP", description: "Change which epics are in MVP" }
+        ]
+      }
+    ]
+  });
+  // Apply user adjustments
+}
+```
+
+### Step 4: Generate epics/ directory
+
+```javascript
+const template = Read('templates/epics-template.md');
+
+// Create epics directory
+Bash(`mkdir -p "${workDir}/epics"`);
+
+const status = autoMode ? 'complete' : 'draft';
+const timestamp = new Date().toISOString();
+
+// Parse CLI output into structured Epics
+const epicsList = parseEpics(cliOutput);  // [{id, slug, title, priority, mvp, size, stories[], reqs[], adrs[], deps[]}]
+
+// Step 4a: Write individual EPIC-*.md files (one per Epic, stories included)
+epicsList.forEach(epic => {
+  // Use EPIC-NNN-{slug}.md template from templates/epics-template.md
+  // Fill: id, title, priority, mvp, size, description, requirements links,
+  //       architecture links, dependency links, stories with user stories + AC
+  Write(`${workDir}/epics/EPIC-${epic.id}-${epic.slug}.md`, epicContent);
+});
+
+// Step 4b: Write _index.md (overview + dependency map + MVP scope + traceability)
+// Use _index.md template from templates/epics-template.md
+// Fill: epic overview table (with links), dependency Mermaid diagram,
+//       execution order, MVP scope, traceability matrix, estimation summary
+Write(`${workDir}/epics/_index.md`, indexContent);
+
+// Update spec-config.json
+specConfig.phasesCompleted.push({
+  phase: 5,
+  name: "epics-stories",
+  output_dir: "epics/",
+  output_index: "epics/_index.md",
+  file_count: epicsList.length + 1,
+  completed_at: timestamp
+});
+Write(`${workDir}/spec-config.json`, JSON.stringify(specConfig, null, 2));
+```
+
+## Output
+
+- **Directory**: `epics/`
+  - `_index.md` — Overview table, dependency map, MVP scope, traceability matrix, links
+  - `EPIC-NNN-{slug}.md` — Individual Epic with Stories (per Epic)
+- **Format**: Markdown with YAML frontmatter, cross-linked to requirements and architecture via relative paths
+
+## Quality Checklist
+
+- [ ] 3-7 Epic files with EPIC-NNN IDs
+- [ ] >= 1 Epic tagged as MVP in frontmatter
+- [ ] 2-5 Stories per Epic file
+- [ ] Stories use "As a...I want...So that..." format
+- [ ] `_index.md` has cross-Epic dependency map (Mermaid)
+- [ ] `_index.md` links to all individual Epic files
+- [ ] Relative sizing (S/M/L/XL) per Story
+- [ ] Epic files link to requirement files and ADR files
+- [ ] All files have valid YAML frontmatter
+
+## Next Phase
+
+Proceed to [Phase 6: Readiness Check](06-readiness-check.md) to validate the complete specification package.
+
+---
+
+## Agent Return Summary
+
+When executed as a delegated agent, return the following JSON summary to the orchestrator:
+
+```json
+{
+  "phase": 5,
+  "status": "complete",
+  "files_created": ["epics/_index.md", "epics/EPIC-001-*.md", "..."],
+  "file_count": 0,
+  "codex_review_integrated": true,
+  "mvp_epic_count": 0,
+  "total_story_count": 0,
+  "quality_notes": ["list of quality concerns or Codex feedback items addressed"],
+  "key_decisions": ["MVP scope decisions", "dependency resolution choices"]
+}
+```
+
+The orchestrator will:
+1. Validate that `epics/` directory exists with `_index.md` and EPIC files
+2. Read `spec-config.json` to confirm `phasesCompleted` was updated
+3. Store the summary for downstream phase context

.codex/skills/spec-generator/phases/06-5-auto-fix.md

@@ -0,0 +1,172 @@
+# Phase 6.5: Auto-Fix
+
+> **Execution Mode: Agent Delegated**
+> This phase is executed by a `doc-generator` agent when triggered by the orchestrator after Phase 6 identifies issues. The agent reads this file for instructions, applies fixes to affected documents, and returns a JSON summary.
+
+Automatically repair specification issues identified in Phase 6 Readiness Check.
+
+## Objective
+
+- Parse readiness-report.md to extract Error and Warning items
+- Group issues by originating Phase (2-5)
+- Re-generate affected sections with error context injected into CLI prompts
+- Re-run Phase 6 validation after fixes
+
+## Input
+
+- Dependency: `{workDir}/readiness-report.md` (Phase 6 output)
+- Config: `{workDir}/spec-config.json` (with iteration_count)
+- All Phase 2-5 outputs
+
+## Execution Steps
+
+### Step 1: Parse Readiness Report
+
+```javascript
+const readinessReport = Read(`${workDir}/readiness-report.md`);
+const specConfig = JSON.parse(Read(`${workDir}/spec-config.json`));
+
+// Load glossary for terminology consistency during fixes
+let glossary = null;
+try {
+  glossary = JSON.parse(Read(`${workDir}/glossary.json`));
+} catch (e) { /* proceed without */ }
+
+// Extract issues from readiness report
+// Parse Error and Warning severity items
+// Group by originating phase:
+//   Phase 2 issues: vision, problem statement, scope, personas
+//   Phase 3 issues: requirements, acceptance criteria, priority, traceability
+//   Phase 4 issues: architecture, ADRs, tech stack, data model, state machine
+//   Phase 5 issues: epics, stories, dependencies, MVP scope
+
+const issuesByPhase = {
+  2: [], // product brief issues
+  3: [], // requirements issues
+  4: [], // architecture issues
+  5: []  // epics issues
+};
+
+// Parse structured issues from report
+// Each issue: { severity: "Error"|"Warning", description: "...", location: "file:section" }
+
+// Map phase numbers to output files
+const phaseOutputFile = {
+  2: 'product-brief.md',
+  3: 'requirements/_index.md',
+  4: 'architecture/_index.md',
+  5: 'epics/_index.md'
+};
+```
+
+### Step 2: Fix Affected Phases (Sequential)
+
+For each phase with issues (in order 2 -> 3 -> 4 -> 5):
+
+```javascript
+for (const [phase, issues] of Object.entries(issuesByPhase)) {
+  if (issues.length === 0) continue;
+
+  const errorContext = issues.map(i => `[${i.severity}] ${i.description} (at ${i.location})`).join('\n');
+
+  // Read current phase output
+  const currentOutput = Read(`${workDir}/${phaseOutputFile[phase]}`);
+
+  Bash({
+    command: `ccw cli -p "PURPOSE: Fix specification issues identified in readiness check for Phase ${phase}.
+Success: All listed issues resolved while maintaining consistency with other documents.
+
+CURRENT DOCUMENT:
+${currentOutput.slice(0, 5000)}
+
+ISSUES TO FIX:
+${errorContext}
+
+${glossary ? `GLOSSARY (maintain consistency):
+${JSON.stringify(glossary.terms, null, 2)}` : ''}
+
+TASK:
+- Address each listed issue specifically
+- Maintain all existing content that is not flagged
+- Ensure terminology consistency with glossary
+- Preserve YAML frontmatter and cross-references
+- Use RFC 2119 keywords for behavioral requirements
+- Increment document version number
+
+MODE: analysis
+EXPECTED: Corrected document content addressing all listed issues
+CONSTRAINTS: Minimal changes - only fix flagged issues, do not restructure unflagged sections
+" --tool gemini --mode analysis`,
+    run_in_background: true
+  });
+
+  // Wait for result, apply fixes to document
+  // Update document version in frontmatter
+}
+```
+
+### Step 3: Update State
+
+```javascript
+specConfig.phasesCompleted.push({
+  phase: 6.5,
+  name: "auto-fix",
+  iteration: specConfig.iteration_count,
+  phases_fixed: Object.keys(issuesByPhase).filter(p => issuesByPhase[p].length > 0),
+  completed_at: new Date().toISOString()
+});
+Write(`${workDir}/spec-config.json`, JSON.stringify(specConfig, null, 2));
+```
+
+### Step 4: Re-run Phase 6 Validation
+
+```javascript
+// Re-execute Phase 6: Readiness Check
+// This creates a new readiness-report.md
+// If still Fail and iteration_count < 2: loop back to Step 1
+// If Pass or iteration_count >= 2: proceed to handoff
+```
+
+## Output
+
+- **Updated**: Phase 2-5 documents (only affected ones)
+- **Updated**: `spec-config.json` (iteration tracking)
+- **Triggers**: Phase 6 re-validation
+
+## Quality Checklist
+
+- [ ] All Error-severity issues addressed
+- [ ] Warning-severity issues attempted (best effort)
+- [ ] Document versions incremented for modified files
+- [ ] Terminology consistency maintained
+- [ ] Cross-references still valid after fixes
+- [ ] Iteration count not exceeded (max 2)
+
+## Next Phase
+
+Re-run [Phase 6: Readiness Check](06-readiness-check.md) to validate fixes.
+
+---
+
+## Agent Return Summary
+
+When executed as a delegated agent, return the following JSON summary to the orchestrator:
+
+```json
+{
+  "phase": 6.5,
+  "status": "complete",
+  "files_modified": ["list of files that were updated"],
+  "issues_fixed": {
+    "errors": 0,
+    "warnings": 0
+  },
+  "quality_notes": ["list of fix decisions and remaining concerns"],
+  "phases_touched": [2, 3, 4, 5]
+}
+```
+
+The orchestrator will:
+1. Validate that listed files were actually modified (check version increment)
+2. Update `spec-config.json` iteration tracking
+3. Re-trigger Phase 6 validation

.codex/skills/spec-generator/phases/06-readiness-check.md

@@ -0,0 +1,581 @@
+# Phase 6: Readiness Check
+
+Validate the complete specification package, generate quality report and executive summary, provide execution handoff options.
+
+## Objective
+
+- Cross-document validation: completeness, consistency, traceability, depth
+- Generate quality scores per dimension
+- Produce readiness-report.md with issue list and traceability matrix
+- Produce spec-summary.md as one-page executive summary
+- Update all document frontmatter to `status: complete`
+- Present handoff options to execution workflows
+
+## Input
+
+- All Phase 2-5 outputs: `product-brief.md`, `requirements/_index.md` (+ `REQ-*.md`, `NFR-*.md`), `architecture/_index.md` (+ `ADR-*.md`), `epics/_index.md` (+ `EPIC-*.md`)
+- Config: `{workDir}/spec-config.json`
+- Reference: `specs/quality-gates.md`
+
+## Execution Steps
+
+### Step 1: Load All Documents
+
+```javascript
+const specConfig = JSON.parse(Read(`${workDir}/spec-config.json`));
+const productBrief = Read(`${workDir}/product-brief.md`);
+const requirementsIndex = Read(`${workDir}/requirements/_index.md`);
+const architectureIndex = Read(`${workDir}/architecture/_index.md`);
+const epicsIndex = Read(`${workDir}/epics/_index.md`);
+const qualityGates = Read('specs/quality-gates.md');
+
+// Load individual files for deep validation
+const reqFiles = Glob(`${workDir}/requirements/REQ-*.md`);
+const nfrFiles = Glob(`${workDir}/requirements/NFR-*.md`);
+const adrFiles = Glob(`${workDir}/architecture/ADR-*.md`);
+const epicFiles = Glob(`${workDir}/epics/EPIC-*.md`);
+```
+
+### Step 2: Cross-Document Validation via Gemini CLI
+
+```javascript
+Bash({
+  command: `ccw cli -p "PURPOSE: Validate specification package for completeness, consistency, traceability, and depth.
+Success: Comprehensive quality report with scores, issues, and traceability matrix.
+
+DOCUMENTS TO VALIDATE:
+
+=== PRODUCT BRIEF ===
+${productBrief.slice(0, 3000)}
+
+=== REQUIREMENTS INDEX (${reqFiles.length} REQ + ${nfrFiles.length} NFR files) ===
+${requirementsIndex.slice(0, 3000)}
+
+=== ARCHITECTURE INDEX (${adrFiles.length} ADR files) ===
+${architectureIndex.slice(0, 2500)}
+
+=== EPICS INDEX (${epicFiles.length} EPIC files) ===
+${epicsIndex.slice(0, 2500)}
+
+QUALITY CRITERIA (from quality-gates.md):
+${qualityGates.slice(0, 2000)}
+
+TASK:
+Perform 4-dimension validation:
+
+1. COMPLETENESS (25%):
+   - All required sections present in each document?
+   - All template fields filled with substantive content?
+   - Score 0-100 with specific gaps listed
+
+2. CONSISTENCY (25%):
+   - Terminology uniform across documents?
+   - Terminology glossary compliance: all core terms used consistently per glossary.json definitions?
+   - No synonym drift (e.g., "user" vs "client" vs "consumer" for same concept)?
+   - User personas consistent?
+   - Scope consistent (PRD does not exceed brief)?
+   - Scope containment: PRD requirements do not exceed product brief's defined scope?
+   - Non-Goals respected: no requirement or story contradicts explicit Non-Goals?
+   - Tech stack references match between architecture and epics?
+   - Score 0-100 with inconsistencies listed
+
+3. TRACEABILITY (25%):
+   - Every goal has >= 1 requirement?
+   - Every Must requirement has architecture coverage?
+   - Every Must requirement appears in >= 1 story?
+   - ADR choices reflected in epics?
+   - Build traceability matrix: Goal -> Requirement -> Architecture -> Epic/Story
+   - Score 0-100 with orphan items listed
+
+4. DEPTH (25%):
+   - Acceptance criteria specific and testable?
+   - Architecture decisions justified with alternatives?
+   - Stories estimable by dev team?
+   - Score 0-100 with vague areas listed
+
+ALSO:
+- List all issues found, classified as Error/Warning/Info
+- Generate overall weighted score
+- Determine gate: Pass (>=80) / Review (60-79) / Fail (<60)
+
+MODE: analysis
+EXPECTED: JSON-compatible output with: dimension scores, overall score, gate, issues list (severity + description + location), traceability matrix
+CONSTRAINTS: Be thorough but fair. Focus on actionable issues.
+" --tool gemini --mode analysis`,
+  run_in_background: true
+});
+
+// Wait for CLI result
+```
+
+### Step 2b: Codex Technical Depth Review
+
+Launch Codex review in parallel with Gemini validation for deeper technical assessment:
+
+```javascript
+Bash({
+  command: `ccw cli -p "PURPOSE: Deep technical quality review of specification package - assess architectural rigor and implementation readiness.
+Success: Technical quality assessment with specific actionable feedback on ADR quality, data model, security, and observability.
+
+ARCHITECTURE INDEX:
+${architectureIndex.slice(0, 3000)}
+
+ADR FILES (summaries):
+${adrFiles.map(f => Read(f).slice(0, 500)).join('\n---\n')}
+
+REQUIREMENTS INDEX:
+${requirementsIndex.slice(0, 2000)}
+
+TASK:
+- ADR Alternative Quality: Each ADR has >= 2 genuine alternatives with substantive pros/cons (not strawman options)
+- Data Model Completeness: All entities referenced in requirements have field-level definitions with types and constraints
+- Security Coverage: Authentication, authorization, data protection, and input validation addressed for all external interfaces
+- Observability Specification: Metrics, logging, and health checks defined for service/platform types
+- Error Handling: Error classification and recovery strategies defined per component
+- Configuration Model: All configurable parameters documented with types, defaults, and constraints
+- Rate each dimension 1-5 with specific gaps identified
+
+MODE: analysis
+EXPECTED: Technical depth review with: per-dimension scores (1-5), specific gaps, improvement recommendations, overall technical readiness assessment
+CONSTRAINTS: Focus on gaps that would cause implementation ambiguity. Ignore cosmetic issues.
+" --tool codex --mode analysis`,
+  run_in_background: true
+});
+
+// Codex result merged with Gemini result in Step 3
+```
+
+### Step 2c: Per-Requirement Verification
+
+Iterate through all individual requirement files for fine-grained verification:
+
+```javascript
+// Load all requirement files
+const reqFiles = Glob(`${workDir}/requirements/REQ-*.md`);
+const nfrFiles = Glob(`${workDir}/requirements/NFR-*.md`);
+const allReqFiles = [...reqFiles, ...nfrFiles];
+
+// Load reference documents for cross-checking
+const productBrief = Read(`${workDir}/product-brief.md`);
+const epicFiles = Glob(`${workDir}/epics/EPIC-*.md`);
+const adrFiles = Glob(`${workDir}/architecture/ADR-*.md`);
+
+// Read all epic content for coverage check
+const epicContents = epicFiles.map(f => ({ path: f, content: Read(f) }));
+const adrContents = adrFiles.map(f => ({ path: f, content: Read(f) }));
+
+// Per-requirement verification
+const verificationResults = allReqFiles.map(reqFile => {
+  const content = Read(reqFile);
+  const reqId = extractReqId(content);  // e.g., REQ-001 or NFR-PERF-001
+  const priority = extractPriority(content);  // Must/Should/Could/Won't
+
+  // Check 1: AC exists and is testable
+  const hasAC = content.includes('- [ ]') || content.includes('Acceptance Criteria');
+  const acTestable = !content.match(/should be (fast|good|reliable|secure)/i);  // No vague AC
+
+  // Check 2: Traces back to Brief goal
+  const tracesLinks = content.match(/product-brief\.md/);
+
+  // Check 3: Must requirements have Story coverage (search EPIC files)
+  let storyCoverage = priority !== 'Must' ? 'N/A' :
+    epicContents.some(e => e.content.includes(reqId)) ? 'Covered' : 'MISSING';
+
+  // Check 4: Must requirements have architecture coverage (search ADR files)
+  let archCoverage = priority !== 'Must' ? 'N/A' :
+    adrContents.some(a => a.content.includes(reqId)) ||
+    Read(`${workDir}/architecture/_index.md`).includes(reqId) ? 'Covered' : 'MISSING';
+
+  return {
+    req_id: reqId,
+    priority,
+    ac_exists: hasAC ? 'Yes' : 'MISSING',
+    ac_testable: acTestable ? 'Yes' : 'VAGUE',
+    brief_trace: tracesLinks ? 'Yes' : 'MISSING',
+    story_coverage: storyCoverage,
+    arch_coverage: archCoverage,
+    pass: hasAC && acTestable && tracesLinks &&
+          (priority !== 'Must' || (storyCoverage === 'Covered' && archCoverage === 'Covered'))
+  };
+});
+
+// Generate Per-Requirement Verification table for readiness-report.md
+const verificationTable = `
+## Per-Requirement Verification
+
+| Req ID | Priority | AC Exists | AC Testable | Brief Trace | Story Coverage | Arch Coverage | Status |
+|--------|----------|-----------|-------------|-------------|----------------|---------------|--------|
+${verificationResults.map(r =>
+  `| ${r.req_id} | ${r.priority} | ${r.ac_exists} | ${r.ac_testable} | ${r.brief_trace} | ${r.story_coverage} | ${r.arch_coverage} | ${r.pass ? 'PASS' : 'FAIL'} |`
+).join('\n')}
+
+**Summary**: ${verificationResults.filter(r => r.pass).length}/${verificationResults.length} requirements pass all checks.
+`;
+```
+
+### Step 3: Generate readiness-report.md
+
+```javascript
+const frontmatterReport = `---
+session_id: ${specConfig.session_id}
+phase: 6
+document_type: readiness-report
+status: complete
+generated_at: ${new Date().toISOString()}
+stepsCompleted: ["load-all", "cross-validation", "codex-technical-review", "per-req-verification", "scoring", "report-generation"]
+version: 1
+dependencies:
+  - product-brief.md
+  - requirements/_index.md
+  - architecture/_index.md
+  - epics/_index.md
+---`;
+
+// Report content from CLI validation output:
+// - Quality Score Summary (4 dimensions + overall)
+// - Gate Decision (Pass/Review/Fail)
+// - Issue List (grouped by severity: Error, Warning, Info)
+// - Traceability Matrix (Goal -> Req -> Arch -> Epic/Story)
+// - Codex Technical Depth Review (per-dimension scores from Step 2b)
+// - Per-Requirement Verification Table (from Step 2c)
+// - Recommendations for improvement
+
+Write(`${workDir}/readiness-report.md`, `${frontmatterReport}\n\n${reportContent}`);
+```
+
+### Step 4: Generate spec-summary.md
+
+```javascript
+const frontmatterSummary = `---
+session_id: ${specConfig.session_id}
+phase: 6
+document_type: spec-summary
+status: complete
+generated_at: ${new Date().toISOString()}
+stepsCompleted: ["synthesis"]
+version: 1
+dependencies:
+  - product-brief.md
+  - requirements/_index.md
+  - architecture/_index.md
+  - epics/_index.md
+  - readiness-report.md
+---`;
+
+// One-page executive summary:
+// - Product Name & Vision (from product-brief.md)
+// - Problem & Target Users (from product-brief.md)
+// - Key Requirements count (Must/Should/Could from requirements.md)
+// - Architecture Style & Tech Stack (from architecture.md)
+// - Epic Overview (count, MVP scope from epics.md)
+// - Quality Score (from readiness-report.md)
+// - Recommended Next Step
+// - File manifest with links
+
+Write(`${workDir}/spec-summary.md`, `${frontmatterSummary}\n\n${summaryContent}`);
+```
+
+### Step 5: Update All Document Status
+
+```javascript
+// Update frontmatter status to 'complete' in all documents (directories + single files)
+// product-brief.md is a single file
+const singleFiles = ['product-brief.md'];
+singleFiles.forEach(doc => {
+  const content = Read(`${workDir}/${doc}`);
+  Write(`${workDir}/${doc}`, content.replace(/status: draft/, 'status: complete'));
+});
+
+// Update all files in directories (index + individual files)
+const dirFiles = [
+  ...Glob(`${workDir}/requirements/*.md`),
+  ...Glob(`${workDir}/architecture/*.md`),
+  ...Glob(`${workDir}/epics/*.md`)
+];
+dirFiles.forEach(filePath => {
+  const content = Read(filePath);
+  if (content.includes('status: draft')) {
+    Write(filePath, content.replace(/status: draft/, 'status: complete'));
+  }
+});
+
+// Update spec-config.json
+specConfig.phasesCompleted.push({
+  phase: 6,
+  name: "readiness-check",
+  output_file: "readiness-report.md",
+  completed_at: new Date().toISOString()
+});
+Write(`${workDir}/spec-config.json`, JSON.stringify(specConfig, null, 2));
+```
+
+### Step 6: Handoff Options
+
+```javascript
+AskUserQuestion({
+  questions: [
+    {
+      question: "Specification package is complete. What would you like to do next?",
+      header: "Next Step",
+      multiSelect: false,
+      options: [
+        {
+          label: "Execute via lite-plan",
+          description: "Start implementing with /workflow-lite-plan, one Epic at a time"
+        },
+        {
+          label: "Create roadmap",
+          description: "Generate execution roadmap with /workflow:req-plan-with-file"
+        },
+        {
+          label: "Full planning",
+          description: "Detailed planning with /workflow-plan for the full scope"
+        },
+        {
+          label: "Export Issues (Phase 7)",
+          description: "Create issues per Epic with spec links and wave assignment"
+        },
+        {
+          label: "Iterate & improve",
+          description: "Re-run failed phases based on readiness report issues (max 2 iterations)"
+        }
+      ]
+    }
+  ]
+});
+
+// Based on user selection, execute the corresponding handoff:
+
+if (selection === "Execute via lite-plan") {
+  // lite-plan accepts a text description directly
+  // Read first MVP Epic from individual EPIC-*.md files
+  const epicFiles = Glob(`${workDir}/epics/EPIC-*.md`);
+  const firstMvpFile = epicFiles.find(f => {
+    const content = Read(f);
+    return content.includes('mvp: true');
+  });
+  const epicContent = Read(firstMvpFile);
+  const title = extractTitle(epicContent);       // First # heading
+  const description = extractSection(epicContent, "Description");
+  Skill(skill="workflow-lite-plan", args=`"${title}: ${description}"`)
+}
+
+if (selection === "Full planning" || selection === "Create roadmap") {
+  // === Bridge: Build brainstorm_artifacts compatible structure ===
+  // Reads from directory-based outputs (individual files), maps to .brainstorming/ format
+  // for context-search-agent auto-discovery → action-planning-agent consumption.
+
+  // Step A: Read spec documents from directories
+  const specSummary = Read(`${workDir}/spec-summary.md`);
+  const productBrief = Read(`${workDir}/product-brief.md`);
+  const requirementsIndex = Read(`${workDir}/requirements/_index.md`);
+  const architectureIndex = Read(`${workDir}/architecture/_index.md`);
+  const epicsIndex = Read(`${workDir}/epics/_index.md`);
+
+  // Read individual EPIC files (already split — direct mapping to feature-specs)
+  const epicFiles = Glob(`${workDir}/epics/EPIC-*.md`);
+
+  // Step B: Build structured description from spec-summary
+  const structuredDesc = `GOAL: ${extractGoal(specSummary)}
+SCOPE: ${extractScope(specSummary)}
+CONTEXT: Generated from spec session ${specConfig.session_id}. Source: ${workDir}/`;
+
+  // Step C: Create WFS session (provides session directory + .brainstorming/)
+  Skill(skill="workflow:session:start", args=`--auto "${structuredDesc}"`)
+  // → Produces sessionId (WFS-xxx) and session directory at .workflow/active/{sessionId}/
+
+  // Step D: Create .brainstorming/ bridge files
+  const brainstormDir = `.workflow/active/${sessionId}/.brainstorming`;
+  Bash(`mkdir -p "${brainstormDir}/feature-specs"`);
+
+  // D.1: guidance-specification.md (highest priority — action-planning-agent reads first)
+  // Synthesized from spec-summary + product-brief + architecture/requirements indexes
+  Write(`${brainstormDir}/guidance-specification.md`, `
+# ${specConfig.seed_analysis.problem_statement} - Confirmed Guidance Specification
+
+**Source**: spec-generator session ${specConfig.session_id}
+**Generated**: ${new Date().toISOString()}
+**Spec Directory**: ${workDir}
+
+## 1. Project Positioning & Goals
+${extractSection(productBrief, "Vision")}
+${extractSection(productBrief, "Goals")}
+
+## 2. Requirements Summary
+${extractSection(requirementsIndex, "Functional Requirements")}
+
+## 3. Architecture Decisions
+${extractSection(architectureIndex, "Architecture Decision Records")}
+${extractSection(architectureIndex, "Technology Stack")}
+
+## 4. Implementation Scope
+${extractSection(epicsIndex, "Epic Overview")}
+${extractSection(epicsIndex, "MVP Scope")}
+
+## Feature Decomposition
+${extractSection(epicsIndex, "Traceability Matrix")}
+
+## Appendix: Source Documents
+| Document | Path | Description |
+|----------|------|-------------|
+| Product Brief | ${workDir}/product-brief.md | Vision, goals, scope |
+| Requirements | ${workDir}/requirements/ | _index.md + REQ-*.md + NFR-*.md |
+| Architecture | ${workDir}/architecture/ | _index.md + ADR-*.md |
+| Epics | ${workDir}/epics/ | _index.md + EPIC-*.md |
+| Readiness Report | ${workDir}/readiness-report.md | Quality validation |
+`);
+
+  // D.2: feature-index.json (each EPIC file mapped to a Feature)
+  // Path: feature-specs/feature-index.json (matches context-search-agent discovery)
+  // Directly read from individual EPIC-*.md files (no monolithic parsing needed)
+  const features = epicFiles.map(epicFile => {
+    const content = Read(epicFile);
+    const fm = parseFrontmatter(content);  // Extract YAML frontmatter
+    const basename = path.basename(epicFile, '.md');  // EPIC-001-slug
+    const epicNum = fm.id.replace('EPIC-', '');       // 001
+    const slug = basename.replace(/^EPIC-\d+-/, '');   // slug
+    return {
+      id: `F-${epicNum}`,
+      slug: slug,
+      name: extractTitle(content),
+      description: extractSection(content, "Description"),
+      priority: fm.mvp ? "High" : "Medium",
+      spec_path: `${brainstormDir}/feature-specs/F-${epicNum}-${slug}.md`,
+      source_epic: fm.id,
+      source_file: epicFile
+    };
+  });
+  Write(`${brainstormDir}/feature-specs/feature-index.json`, JSON.stringify({
+    version: "1.0",
+    source: "spec-generator",
+    spec_session: specConfig.session_id,
+    features,
+    cross_cutting_specs: []
+  }, null, 2));
+
+  // D.3: Feature-spec files — directly adapt from individual EPIC-*.md files
+  // Since Epics are already individual documents, transform format directly
+  // Filename pattern: F-{num}-{slug}.md (matches context-search-agent glob F-*-*.md)
+  features.forEach(feature => {
+    const epicContent = Read(feature.source_file);
+    Write(feature.spec_path, `
+# Feature Spec: ${feature.source_epic} - ${feature.name}
+
+**Source**: ${feature.source_file}
+**Priority**: ${feature.priority === "High" ? "MVP" : "Post-MVP"}
+
+## Description
+${extractSection(epicContent, "Description")}
+
+## Stories
+${extractSection(epicContent, "Stories")}
+
+## Requirements
+${extractSection(epicContent, "Requirements")}
+
+## Architecture
+${extractSection(epicContent, "Architecture")}
+`);
+  });
+
+  // Step E: Invoke downstream workflow
+  // context-search-agent will auto-discover .brainstorming/ files
+  // → context-package.json.brainstorm_artifacts populated
+  // → action-planning-agent loads guidance_specification (P1) + feature_index (P2)
+  if (selection === "Full planning") {
+    Skill(skill="workflow-plan", args=`"${structuredDesc}"`)
+  } else {
+    Skill(skill="workflow:req-plan-with-file", args=`"${extractGoal(specSummary)}"`)
+  }
+}
+
+if (selection === "Export Issues (Phase 7)") {
+  // Proceed to Phase 7: Issue Export
+  // Read phases/07-issue-export.md and execute
+}
+
+// If user selects "Other": Export only or return to specific phase
+
+if (selection === "Iterate & improve") {
+  // Check iteration count
+  if (specConfig.iteration_count >= 2) {
+    // Max iterations reached, force handoff
+    // Present handoff options again without iterate
+    return;
+  }
+
+  // Update iteration tracking
+  specConfig.iteration_count = (specConfig.iteration_count || 0) + 1;
+  specConfig.iteration_history.push({
+    iteration: specConfig.iteration_count,
+    timestamp: new Date().toISOString(),
+    readiness_score: overallScore,
+    errors_found: errorCount,
+    phases_to_fix: affectedPhases
+  });
+  Write(`${workDir}/spec-config.json`, JSON.stringify(specConfig, null, 2));
+
+  // Proceed to Phase 6.5: Auto-Fix
+  // Read phases/06-5-auto-fix.md and execute
+}
+```
+
+#### Helper Functions Reference (pseudocode)
+
+The following helper functions are used in the handoff bridge. They operate on markdown content from individual spec files:
+
+```javascript
+// Extract title from a markdown document (first # heading)
+function extractTitle(markdown) {
+  // Return the text after the first # heading (e.g., "# EPIC-001: Title" → "Title")
+}
+
+// Parse YAML frontmatter from markdown (between --- markers)
+function parseFrontmatter(markdown) {
+  // Return object with: id, priority, mvp, size, requirements, architecture, dependencies
+}
+
+// Extract GOAL/SCOPE from spec-summary frontmatter or ## sections
+function extractGoal(specSummary) { /* Return the Vision/Goal line */ }
+function extractScope(specSummary) { /* Return the Scope/MVP boundary */ }
+
+// Extract a named ## section from a markdown document
+function extractSection(markdown, sectionName) {
+  // Return content between ## {sectionName} and next ## heading
+}
+```
+
+## Output
+
+- **File**: `readiness-report.md` - Quality validation report
+- **File**: `spec-summary.md` - One-page executive summary
+- **Format**: Markdown with YAML frontmatter
+
+## Quality Checklist
+
+- [ ] All document directories validated (product-brief, requirements/, architecture/, epics/)
+- [ ] All frontmatter parseable and valid (index + individual files)
+- [ ] Cross-references checked (relative links between directories)
+- [ ] Overall quality score calculated
+- [ ] No unresolved Error-severity issues
+- [ ] Traceability matrix generated
+- [ ] spec-summary.md created
+- [ ] All document statuses updated to 'complete' (all files in all directories)
+- [ ] Handoff options presented
+
+## Completion
+
+This is the final phase. The specification package is ready for execution handoff.
+
+### Output Files Manifest
+
+| Path | Phase | Description |
+|------|-------|-------------|
+| `spec-config.json` | 1 | Session configuration and state |
+| `discovery-context.json` | 1 | Codebase exploration (optional) |
+| `product-brief.md` | 2 | Product brief with multi-perspective synthesis |
+| `requirements/` | 3 | Directory: `_index.md` + `REQ-*.md` + `NFR-*.md` |
+| `architecture/` | 4 | Directory: `_index.md` + `ADR-*.md` |
+| `epics/` | 5 | Directory: `_index.md` + `EPIC-*.md` |
+| `readiness-report.md` | 6 | Quality validation report |
+| `spec-summary.md` | 6 | One-page executive summary |

.codex/skills/spec-generator/phases/07-issue-export.md

@@ -0,0 +1,329 @@
+# Phase 7: Issue Export
+
+Map specification Epics to issues, create them via `ccw issue create`, and generate an export report with spec document links.
+
+> **Execution Mode: Inline**
+> This phase runs in the main orchestrator context (not delegated to agent) for direct access to `ccw issue create` CLI and interactive handoff options.
+
+## Objective
+
+- Read all EPIC-*.md files from Phase 5 output
+- Assign waves: MVP epics → wave-1, non-MVP → wave-2
+- Create one issue per Epic via `ccw issue create`
+- Map Epic dependencies to issue dependencies
+- Generate issue-export-report.md with mapping table and spec links
+- Present handoff options for execution
+
+## Input
+
+- Dependency: `{workDir}/epics/_index.md` (and individual `EPIC-*.md` files)
+- Reference: `{workDir}/readiness-report.md`, `{workDir}/spec-config.json`
+- Reference: `{workDir}/product-brief.md`, `{workDir}/requirements/_index.md`, `{workDir}/architecture/_index.md`
+
+## Execution Steps
+
+### Step 1: Load Epic Files
+
+```javascript
+const specConfig = JSON.parse(Read(`${workDir}/spec-config.json`));
+const epicFiles = Glob(`${workDir}/epics/EPIC-*.md`);
+const epicsIndex = Read(`${workDir}/epics/_index.md`);
+
+// Parse each Epic file
+const epics = epicFiles.map(epicFile => {
+  const content = Read(epicFile);
+  const fm = parseFrontmatter(content);
+  const title = extractTitle(content);
+  const description = extractSection(content, "Description");
+  const stories = extractSection(content, "Stories");
+  const reqRefs = extractSection(content, "Requirements");
+  const adrRefs = extractSection(content, "Architecture");
+  const deps = fm.dependencies || [];
+
+  return {
+    file: epicFile,
+    id: fm.id,           // e.g., EPIC-001
+    title,
+    description,
+    stories,
+    reqRefs,
+    adrRefs,
+    priority: fm.priority,
+    mvp: fm.mvp || false,
+    dependencies: deps,   // other EPIC IDs this depends on
+    size: fm.size
+  };
+});
+```
+
+### Step 2: Wave Assignment
+
+```javascript
+const epicWaves = epics.map(epic => ({
+  ...epic,
+  wave: epic.mvp ? 1 : 2
+}));
+
+// Log wave assignment
+const wave1 = epicWaves.filter(e => e.wave === 1);
+const wave2 = epicWaves.filter(e => e.wave === 2);
+// wave-1: MVP epics (must-have, core functionality)
+// wave-2: Post-MVP epics (should-have, enhancements)
+```
+
+### Step 3: Issue Creation Loop
+
+```javascript
+const createdIssues = [];
+const epicToIssue = {};  // EPIC-ID -> Issue ID mapping
+
+for (const epic of epicWaves) {
+  // Build issue JSON matching roadmap-with-file schema
+  const issueData = {
+    title: `[${specConfig.session_id}] ${epic.title}`,
+    status: "pending",
+    priority: epic.wave === 1 ? 2 : 3,  // wave-1 = higher priority
+    context: `## ${epic.title}
+
+${epic.description}
+
+## Stories
+${epic.stories}
+
+## Spec References
+- Epic: ${epic.file}
+- Requirements: ${epic.reqRefs}
+- Architecture: ${epic.adrRefs}
+- Product Brief: ${workDir}/product-brief.md
+- Full Spec: ${workDir}/`,
+    source: "text",
+    tags: [
+      "spec-generated",
+      `spec:${specConfig.session_id}`,
+      `wave-${epic.wave}`,
+      epic.mvp ? "mvp" : "post-mvp",
+      `epic:${epic.id}`
+    ],
+    extended_context: {
+      notes: {
+        session: specConfig.session_id,
+        spec_dir: workDir,
+        source_epic: epic.id,
+        wave: epic.wave,
+        depends_on_issues: [],  // Filled in Step 4
+        spec_documents: {
+          product_brief: `${workDir}/product-brief.md`,
+          requirements: `${workDir}/requirements/_index.md`,
+          architecture: `${workDir}/architecture/_index.md`,
+          epic: epic.file
+        }
+      }
+    },
+    lifecycle_requirements: {
+      test_strategy: "acceptance",
+      regression_scope: "affected",
+      acceptance_type: "manual",
+      commit_strategy: "per-epic"
+    }
+  };
+
+  // Create issue via ccw issue create (pipe JSON to avoid shell escaping)
+  const result = Bash(`echo '${JSON.stringify(issueData)}' | ccw issue create`);
+
+  // Parse returned issue ID
+  const issueId = JSON.parse(result).id;  // e.g., ISS-20260308-001
+  epicToIssue[epic.id] = issueId;
+
+  createdIssues.push({
+    epic_id: epic.id,
+    epic_title: epic.title,
+    issue_id: issueId,
+    wave: epic.wave,
+    priority: issueData.priority,
+    mvp: epic.mvp
+  });
+}
+```
+
+### Step 4: Epic Dependency → Issue Dependency Mapping
+
+```javascript
+// Map EPIC dependencies to Issue dependencies
+for (const epic of epicWaves) {
+  if (epic.dependencies.length === 0) continue;
+
+  const issueId = epicToIssue[epic.id];
+  const depIssueIds = epic.dependencies
+    .map(depEpicId => epicToIssue[depEpicId])
+    .filter(Boolean);
+
+  if (depIssueIds.length > 0) {
+    // Update issue's extended_context.notes.depends_on_issues
+    // This is informational — actual dependency enforcement is in execution phase
+    // Note: ccw issue create already created the issue; dependency info is in the context
+  }
+}
+```
+
+### Step 5: Generate issue-export-report.md
+
+```javascript
+const timestamp = new Date().toISOString();
+
+const reportContent = `---
+session_id: ${specConfig.session_id}
+phase: 7
+document_type: issue-export-report
+status: complete
+generated_at: ${timestamp}
+stepsCompleted: ["load-epics", "wave-assignment", "issue-creation", "dependency-mapping", "report-generation"]
+version: 1
+dependencies:
+  - epics/_index.md
+  - readiness-report.md
+---
+
+# Issue Export Report
+
+## Summary
+
+- **Session**: ${specConfig.session_id}
+- **Issues Created**: ${createdIssues.length}
+- **Wave 1 (MVP)**: ${wave1.length} issues
+- **Wave 2 (Post-MVP)**: ${wave2.length} issues
+- **Export Date**: ${timestamp}
+
+## Issue Mapping
+
+| Epic ID | Epic Title | Issue ID | Wave | Priority | MVP |
+|---------|-----------|----------|------|----------|-----|
+${createdIssues.map(i =>
+  `| ${i.epic_id} | ${i.epic_title} | ${i.issue_id} | ${i.wave} | ${i.priority} | ${i.mvp ? 'Yes' : 'No'} |`
+).join('\n')}
+
+## Spec Document Links
+
+| Document | Path | Description |
+|----------|------|-------------|
+| Product Brief | ${workDir}/product-brief.md | Vision, goals, scope |
+| Requirements | ${workDir}/requirements/_index.md | Functional + non-functional requirements |
+| Architecture | ${workDir}/architecture/_index.md | Components, ADRs, tech stack |
+| Epics | ${workDir}/epics/_index.md | Epic/Story breakdown |
+| Readiness Report | ${workDir}/readiness-report.md | Quality validation |
+| Spec Summary | ${workDir}/spec-summary.md | Executive summary |
+
+## Dependency Map
+
+| Issue ID | Depends On |
+|----------|-----------|
+${createdIssues.map(i => {
+  const epic = epicWaves.find(e => e.id === i.epic_id);
+  const deps = (epic.dependencies || []).map(d => epicToIssue[d]).filter(Boolean);
+  return `| ${i.issue_id} | ${deps.length > 0 ? deps.join(', ') : 'None'} |`;
+}).join('\n')}
+
+## Next Steps
+
+1. **team-planex**: Execute all issues via coordinated team workflow
+2. **Wave 1 only**: Execute MVP issues first (${wave1.length} issues)
+3. **View issues**: Browse created issues via \`ccw issue list --tag spec:${specConfig.session_id}\`
+4. **Manual review**: Review individual issues before execution
+`;
+
+Write(`${workDir}/issue-export-report.md`, reportContent);
+```
+
+### Step 6: Update spec-config.json
+
+```javascript
+specConfig.issue_ids = createdIssues.map(i => i.issue_id);
+specConfig.issues_created = createdIssues.length;
+specConfig.phasesCompleted.push({
+  phase: 7,
+  name: "issue-export",
+  output_file: "issue-export-report.md",
+  issues_created: createdIssues.length,
+  wave_1_count: wave1.length,
+  wave_2_count: wave2.length,
+  completed_at: timestamp
+});
+Write(`${workDir}/spec-config.json`, JSON.stringify(specConfig, null, 2));
+```
+
+### Step 7: Handoff Options
+
+```javascript
+AskUserQuestion({
+  questions: [
+    {
+      question: `${createdIssues.length} issues created from ${epicWaves.length} Epics. What would you like to do next?`,
+      header: "Next Step",
+      multiSelect: false,
+      options: [
+        {
+          label: "Execute via team-planex",
+          description: `Execute all ${createdIssues.length} issues with coordinated team workflow`
+        },
+        {
+          label: "Wave 1 only",
+          description: `Execute ${wave1.length} MVP issues first`
+        },
+        {
+          label: "View issues",
+          description: "Browse created issues before deciding"
+        },
+        {
+          label: "Done",
+          description: "Export complete, handle manually"
+        }
+      ]
+    }
+  ]
+});
+
+// Based on user selection:
+if (selection === "Execute via team-planex") {
+  const issueIds = createdIssues.map(i => i.issue_id).join(',');
+  Skill({ skill: "team-planex", args: `--issues ${issueIds}` });
+}
+
+if (selection === "Wave 1 only") {
+  const wave1Ids = createdIssues.filter(i => i.wave === 1).map(i => i.issue_id).join(',');
+  Skill({ skill: "team-planex", args: `--issues ${wave1Ids}` });
+}
+
+if (selection === "View issues") {
+  Bash(`ccw issue list --tag spec:${specConfig.session_id}`);
+}
+```
+
+## Output
+
+- **File**: `issue-export-report.md` — Issue mapping table + spec links + next steps
+- **Updated**: `.workflow/issues/issues.jsonl` — New issue entries appended
+- **Updated**: `spec-config.json` — Phase 7 completion + issue IDs
+
+## Quality Checklist
+
+- [ ] All MVP Epics have corresponding issues created
+- [ ] All non-MVP Epics have corresponding issues created
+- [ ] Issue tags include `spec-generated` and `spec:{session_id}`
+- [ ] Issue `extended_context.notes.spec_documents` paths are correct
+- [ ] Wave assignment matches MVP status (MVP → wave-1, non-MVP → wave-2)
+- [ ] Epic dependencies mapped to issue dependency references
+- [ ] `issue-export-report.md` generated with mapping table
+- [ ] `spec-config.json` updated with `issue_ids` and `issues_created`
+- [ ] Handoff options presented
+
+## Error Handling
+
+| Error | Blocking? | Action |
+|-------|-----------|--------|
+| `ccw issue create` fails for one Epic | No | Log error, continue with remaining Epics, report partial creation |
+| No EPIC files found | Yes | Error and return to Phase 5 |
+| All issue creations fail | Yes | Error with CLI diagnostic, suggest manual creation |
+| Dependency EPIC not found in mapping | No | Skip dependency link, log warning |
+
+## Completion
+
+Phase 7 is the final phase. The specification package has been fully converted to executable issues ready for team-planex or manual execution.

.codex/skills/spec-generator/specs/document-standards.md

@@ -0,0 +1,295 @@
+# Document Standards
+
+Defines format conventions, YAML frontmatter schema, naming rules, and content structure for all spec-generator outputs.
+
+## When to Use
+
+| Phase | Usage | Section |
+|-------|-------|---------|
+| All Phases | Frontmatter format | YAML Frontmatter Schema |
+| All Phases | File naming | Naming Conventions |
+| Phase 2-5 | Document structure | Content Structure |
+| Phase 6 | Validation reference | All sections |
+
+---
+
+## YAML Frontmatter Schema
+
+Every generated document MUST begin with YAML frontmatter:
+
+```yaml
+---
+session_id: SPEC-{slug}-{YYYY-MM-DD}
+phase: {1-6}
+document_type: {product-brief|requirements|architecture|epics|readiness-report|spec-summary|issue-export-report}
+status: draft|review|complete
+generated_at: {ISO8601 timestamp}
+stepsCompleted: []
+version: 1
+dependencies:
+  - {list of input documents used}
+---
+```
+
+### Field Definitions
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `session_id` | string | Yes | Session identifier matching spec-config.json |
+| `phase` | number | Yes | Phase number that generated this document (1-6) |
+| `document_type` | string | Yes | One of: product-brief, requirements, architecture, epics, readiness-report, spec-summary, issue-export-report |
+| `status` | enum | Yes | draft (initial), review (user reviewed), complete (finalized) |
+| `generated_at` | string | Yes | ISO8601 timestamp of generation |
+| `stepsCompleted` | array | Yes | List of step IDs completed during generation |
+| `version` | number | Yes | Document version, incremented on re-generation |
+| `dependencies` | array | No | List of input files this document depends on |
+
+### Status Transitions
+
+```
+draft -> review -> complete
+  |                   ^
+  +-------------------+  (direct promotion in auto mode)
+```
+
+- **draft**: Initial generation, not yet user-reviewed
+- **review**: User has reviewed and provided feedback
+- **complete**: Finalized, ready for downstream consumption
+
+In auto mode (`-y`), documents are promoted directly from `draft` to `complete`.
+
+---
+
+## Naming Conventions
+
+### Session ID Format
+
+```
+SPEC-{slug}-{YYYY-MM-DD}
+```
+
+- **slug**: Lowercase, alphanumeric + Chinese characters, hyphens as separators, max 40 chars
+- **date**: UTC+8 date in YYYY-MM-DD format
+
+Examples:
+- `SPEC-task-management-system-2026-02-11`
+- `SPEC-user-auth-oauth-2026-02-11`
+
+### Output Files
+
+| File | Phase | Description |
+|------|-------|-------------|
+| `spec-config.json` | 1 | Session configuration and state |
+| `discovery-context.json` | 1 | Codebase exploration results (optional) |
+| `refined-requirements.json` | 1.5 | Confirmed requirements after discussion |
+| `glossary.json` | 2 | Terminology glossary for cross-document consistency |
+| `product-brief.md` | 2 | Product brief document |
+| `requirements.md` | 3 | PRD document |
+| `architecture.md` | 4 | Architecture decisions document |
+| `epics.md` | 5 | Epic/Story breakdown document |
+| `readiness-report.md` | 6 | Quality validation report |
+| `spec-summary.md` | 6 | One-page executive summary |
+| `issue-export-report.md` | 7 | Issue export report with Epic→Issue mapping |
+
+### Output Directory
+
+```
+.workflow/.spec/{session-id}/
+```
+
+---
+
+## Content Structure
+
+### Heading Hierarchy
+
+- `#` (H1): Document title only (one per document)
+- `##` (H2): Major sections
+- `###` (H3): Subsections
+- `####` (H4): Detail items (use sparingly)
+
+Maximum depth: 4 levels. Prefer flat structures.
+
+### Section Ordering
+
+Every document follows this general pattern:
+
+1. **YAML Frontmatter** (mandatory)
+2. **Title** (H1)
+3. **Executive Summary** (2-3 sentences)
+4. **Core Content Sections** (H2, document-specific)
+5. **Open Questions / Risks** (if applicable)
+6. **References / Traceability** (links to upstream/downstream docs)
+
+### Formatting Rules
+
+| Element | Format | Example |
+|---------|--------|---------|
+| Requirements | `REQ-{NNN}` prefix | REQ-001: User login |
+| Acceptance criteria | Checkbox list | `- [ ] User can log in with email` |
+| Architecture decisions | `ADR-{NNN}` prefix | ADR-001: Use PostgreSQL |
+| Epics | `EPIC-{NNN}` prefix | EPIC-001: Authentication |
+| Stories | `STORY-{EPIC}-{NNN}` prefix | STORY-001-001: Login form |
+| Priority tags | MoSCoW labels | `[Must]`, `[Should]`, `[Could]`, `[Won't]` |
+| Mermaid diagrams | Fenced code blocks | ````mermaid ... ``` `` |
+| Code examples | Language-tagged blocks | ````typescript ... ``` `` |
+
+### Cross-Reference Format
+
+Use relative references between documents:
+
+```markdown
+See [Product Brief](product-brief.md#section-name) for details.
+Derived from [REQ-001](requirements.md#req-001).
+```
+
+### Language
+
+- Document body: Follow user's input language (Chinese or English)
+- Technical identifiers: Always English (REQ-001, ADR-001, EPIC-001)
+- YAML frontmatter keys: Always English
+
+---
+
+## spec-config.json Schema
+
+```json
+{
+  "session_id": "string (required)",
+  "seed_input": "string (required) - original user input",
+  "input_type": "text|file (required)",
+  "timestamp": "ISO8601 (required)",
+  "mode": "interactive|auto (required)",
+  "complexity": "simple|moderate|complex (required)",
+  "depth": "light|standard|comprehensive (required)",
+  "focus_areas": ["string array"],
+  "seed_analysis": {
+    "problem_statement": "string",
+    "target_users": ["string array"],
+    "domain": "string",
+    "constraints": ["string array"],
+    "dimensions": ["string array - 3-5 exploration dimensions"]
+  },
+  "has_codebase": "boolean",
+  "spec_type": "service|api|library|platform (required) - type of specification",
+  "iteration_count": "number (required, default 0) - number of auto-fix iterations completed",
+  "iteration_history": [
+    {
+      "iteration": "number",
+      "timestamp": "ISO8601",
+      "readiness_score": "number (0-100)",
+      "errors_found": "number",
+      "phases_fixed": ["number array - phase numbers that were re-generated"]
+    }
+  ],
+  "refined_requirements_file": "string (optional) - path to refined-requirements.json",
+  "phasesCompleted": [
+    {
+      "phase": "number (1-6)",
+      "name": "string (phase name)",
+      "output_file": "string (primary output file)",
+      "completed_at": "ISO8601"
+    }
+  ],
+  "issue_ids": ["string array (optional) - IDs of issues created in Phase 7"],
+  "issues_created": "number (optional, default 0) - count of issues created in Phase 7"
+}
+```
+
+---
+
+## refined-requirements.json Schema
+
+```json
+{
+  "session_id": "string (required) - matches spec-config.json",
+  "phase": "1.5",
+  "generated_at": "ISO8601 (required)",
+  "source": "interactive-discussion|auto-expansion (required)",
+  "discussion_rounds": "number (required) - 0 for auto mode",
+  "clarified_problem_statement": "string (required) - refined problem statement",
+  "confirmed_target_users": [
+    {
+      "name": "string",
+      "needs": ["string array"],
+      "pain_points": ["string array"]
+    }
+  ],
+  "confirmed_domain": "string",
+  "confirmed_features": [
+    {
+      "name": "string",
+      "description": "string",
+      "acceptance_criteria": ["string array"],
+      "edge_cases": ["string array"],
+      "priority": "must|should|could|unset"
+    }
+  ],
+  "non_functional_requirements": [
+    {
+      "type": "Performance|Security|Usability|Scalability|Reliability|...",
+      "details": "string",
+      "measurable_criteria": "string (optional)"
+    }
+  ],
+  "boundary_conditions": {
+    "in_scope": ["string array"],
+    "out_of_scope": ["string array"],
+    "constraints": ["string array"]
+  },
+  "integration_points": ["string array"],
+  "key_assumptions": ["string array"],
+  "discussion_log": [
+    {
+      "round": "number",
+      "agent_prompt": "string",
+      "user_response": "string",
+      "timestamp": "ISO8601"
+    }
+  ]
+}
+```
+
+---
+
+## glossary.json Schema
+
+```json
+{
+  "session_id": "string (required) - matches spec-config.json",
+  "generated_at": "ISO8601 (required)",
+  "version": "number (required, default 1) - incremented on updates",
+  "terms": [
+    {
+      "term": "string (required) - the canonical term",
+      "definition": "string (required) - concise definition",
+      "aliases": ["string array - acceptable alternative names"],
+      "first_defined_in": "string (required) - source document path",
+      "category": "core|technical|business (required)"
+    }
+  ]
+}
+```
+
+### Glossary Usage Rules
+
+- Terms MUST be defined before first use in any document
+- All documents MUST use the canonical term from glossary; aliases are for reference only
+- Glossary is generated in Phase 2 and injected into all subsequent phase prompts
+- Phase 6 validates glossary compliance across all documents
+
+---
+
+## Validation Checklist
+
+- [ ] Every document starts with valid YAML frontmatter
+- [ ] `session_id` matches across all documents in a session
+- [ ] `status` field reflects current document state
+- [ ] All cross-references resolve to valid targets
+- [ ] Heading hierarchy is correct (no skipped levels)
+- [ ] Technical identifiers use correct prefixes
+- [ ] Output files are in the correct directory
+- [ ] `glossary.json` created with >= 5 terms
+- [ ] `spec_type` field set in spec-config.json
+- [ ] All documents use glossary terms consistently
+- [ ] Non-Goals section present in product brief (if applicable)

.codex/skills/spec-generator/specs/glossary-template.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "glossary-v1",
+  "description": "Template for terminology glossary used across spec-generator documents",
+  "session_id": "",
+  "generated_at": "",
+  "version": 1,
+  "terms": [
+    {
+      "term": "",
+      "definition": "",
+      "aliases": [],
+      "first_defined_in": "product-brief.md",
+      "category": "core"
+    }
+  ],
+  "_usage_notes": {
+    "category_values": {
+      "core": "Domain-specific terms central to the product (e.g., 'Workspace', 'Session')",
+      "technical": "Technical terms specific to the architecture (e.g., 'gRPC', 'event bus')",
+      "business": "Business/process terms (e.g., 'Sprint', 'SLA', 'stakeholder')"
+    },
+    "rules": [
+      "Terms MUST be defined before first use in any document",
+      "All documents MUST use the canonical 'term' field consistently",
+      "Aliases are for reference only - prefer canonical term in all documents",
+      "Phase 6 validates glossary compliance across all documents"
+    ]
+  }
+}

.codex/skills/spec-generator/specs/quality-gates.md

@@ -0,0 +1,270 @@
+# Quality Gates
+
+Per-phase quality gate criteria and scoring dimensions for spec-generator outputs.
+
+## When to Use
+
+| Phase | Usage | Section |
+|-------|-------|---------|
+| Phase 2-5 | Post-generation self-check | Per-Phase Gates |
+| Phase 6 | Cross-document validation | Cross-Document Validation |
+| Phase 6 | Final scoring | Scoring Dimensions |
+
+---
+
+## Quality Thresholds
+
+| Gate | Score | Action |
+|------|-------|--------|
+| **Pass** | >= 80% | Continue to next phase |
+| **Review** | 60-79% | Log warnings, continue with caveats |
+| **Fail** | < 60% | Must address issues before continuing |
+
+In auto mode (`-y`), Review-level issues are logged but do not block progress.
+
+---
+
+## Scoring Dimensions
+
+### 1. Completeness (25%)
+
+All required sections present with substantive content.
+
+| Score | Criteria |
+|-------|----------|
+| 100% | All template sections filled with detailed content |
+| 75% | All sections present, some lack detail |
+| 50% | Major sections present but minor sections missing |
+| 25% | Multiple major sections missing or empty |
+| 0% | Document is a skeleton only |
+
+### 2. Consistency (25%)
+
+Terminology, formatting, and references are uniform across documents.
+
+| Score | Criteria |
+|-------|----------|
+| 100% | All terms consistent, all references valid, formatting uniform |
+| 75% | Minor terminology variations, all references valid |
+| 50% | Some inconsistent terms, 1-2 broken references |
+| 25% | Frequent inconsistencies, multiple broken references |
+| 0% | Documents contradict each other |
+
+### 3. Traceability (25%)
+
+Requirements, architecture decisions, and stories trace back to goals.
+
+| Score | Criteria |
+|-------|----------|
+| 100% | Every story traces to a requirement, every requirement traces to a goal |
+| 75% | Most items traceable, few orphans |
+| 50% | Partial traceability, some disconnected items |
+| 25% | Weak traceability, many orphan items |
+| 0% | No traceability between documents |
+
+### 4. Depth (25%)
+
+Content provides sufficient detail for execution teams.
+
+| Score | Criteria |
+|-------|----------|
+| 100% | Acceptance criteria specific and testable, architecture decisions justified, stories estimable |
+| 75% | Most items detailed enough, few vague areas |
+| 50% | Mix of detailed and vague content |
+| 25% | Mostly high-level, lacking actionable detail |
+| 0% | Too abstract for execution |
+
+---
+
+## Per-Phase Quality Gates
+
+### Phase 1: Discovery
+
+| Check | Criteria | Severity |
+|-------|----------|----------|
+| Session ID valid | Matches `SPEC-{slug}-{date}` format | Error |
+| Problem statement exists | Non-empty, >= 20 characters | Error |
+| Target users identified | >= 1 user group | Error |
+| Dimensions generated | 3-5 exploration dimensions | Warning |
+| Constraints listed | >= 0 (can be empty with justification) | Info |
+
+### Phase 1.5: Requirement Expansion & Clarification
+
+| Check | Criteria | Severity |
+|-------|----------|----------|
+| Problem statement refined | More specific than seed, >= 30 characters | Error |
+| Confirmed features | >= 2 features with descriptions | Error |
+| Non-functional requirements | >= 1 identified (performance, security, etc.) | Warning |
+| Boundary conditions | In-scope and out-of-scope defined | Warning |
+| Key assumptions | >= 1 assumption listed | Warning |
+| User confirmation | Explicit user confirmation recorded (non-auto mode) | Info |
+| Discussion rounds | >= 1 round of interaction (non-auto mode) | Info |
+
+### Phase 2: Product Brief
+
+| Check | Criteria | Severity |
+|-------|----------|----------|
+| Vision statement | Clear, 1-3 sentences | Error |
+| Problem statement | Specific and measurable | Error |
+| Target users | >= 1 persona with needs described | Error |
+| Goals defined | >= 2 measurable goals | Error |
+| Success metrics | >= 2 quantifiable metrics | Warning |
+| Scope boundaries | In-scope and out-of-scope listed | Warning |
+| Multi-perspective | >= 2 CLI perspectives synthesized | Info |
+| Terminology glossary generated | glossary.json created with >= 5 terms | Warning |
+| Non-Goals section present | At least 1 non-goal with rationale | Warning |
+| Concepts section present | Terminology table in product brief | Warning |
+
+### Phase 3: Requirements (PRD)
+
+| Check | Criteria | Severity |
+|-------|----------|----------|
+| Functional requirements | >= 3 with REQ-NNN IDs | Error |
+| Acceptance criteria | Every requirement has >= 1 criterion | Error |
+| MoSCoW priority | Every requirement tagged | Error |
+| Non-functional requirements | >= 1 (performance, security, etc.) | Warning |
+| User stories | >= 1 per Must-have requirement | Warning |
+| Traceability | Requirements trace to product brief goals | Warning |
+| RFC 2119 keywords used | Behavioral requirements use MUST/SHOULD/MAY | Warning |
+| Data model defined | Core entities have field-level definitions | Warning |
+
+### Phase 4: Architecture
+
+| Check | Criteria | Severity |
+|-------|----------|----------|
+| Component diagram | Present (Mermaid or ASCII) | Error |
+| Tech stack specified | Languages, frameworks, key libraries | Error |
+| ADR present | >= 1 Architecture Decision Record | Error |
+| ADR has alternatives | Each ADR lists >= 2 options considered | Warning |
+| Integration points | External systems/APIs identified | Warning |
+| Data model | Key entities and relationships described | Warning |
+| Codebase mapping | Mapped to existing code (if has_codebase) | Info |
+| State machine defined | >= 1 lifecycle state diagram (if service/platform type) | Warning |
+| Configuration model defined | All config fields with type/default/constraint (if service type) | Warning |
+| Error handling strategy | Per-component error classification and recovery | Warning |
+| Observability metrics | >= 3 metrics defined (if service/platform type) | Warning |
+| Trust model defined | Trust levels documented (if service type) | Info |
+| Implementation guidance | Key decisions for implementers listed | Info |
+
+### Phase 5: Epics & Stories
+
+| Check | Criteria | Severity |
+|-------|----------|----------|
+| Epics defined | 3-7 epics with EPIC-NNN IDs | Error |
+| MVP subset | >= 1 epic tagged as MVP | Error |
+| Stories per epic | 2-5 stories per epic | Error |
+| Story format | "As a...I want...So that..." pattern | Warning |
+| Dependency map | Cross-epic dependencies documented | Warning |
+| Estimation hints | Relative sizing (S/M/L/XL) per story | Info |
+| Traceability | Stories trace to requirements | Warning |
+
+### Phase 6: Readiness Check
+
+| Check | Criteria | Severity |
+|-------|----------|----------|
+| All documents exist | product-brief, requirements, architecture, epics | Error |
+| Frontmatter valid | All YAML frontmatter parseable and correct | Error |
+| Cross-references valid | All document links resolve | Error |
+| Overall score >= 60% | Weighted average across 4 dimensions | Error |
+| No unresolved Errors | All Error-severity issues addressed | Error |
+| Summary generated | spec-summary.md created | Warning |
+| Per-requirement verified | All Must requirements pass 4-check verification | Error |
+| Codex technical review | Technical depth assessment completed | Warning |
+| Dual-source validation | Both Gemini and Codex scores recorded | Warning |
+
+### Phase 7: Issue Export
+
+| Check | Criteria | Severity |
+|-------|----------|----------|
+| All MVP epics have issues | Every MVP-tagged Epic has a corresponding issue created | Error |
+| Issue tags correct | Each issue has `spec-generated` and `spec:{session_id}` tags | Error |
+| Export report generated | `issue-export-report.md` exists with mapping table | Error |
+| Wave assignment correct | MVP epics → wave-1, non-MVP epics → wave-2 | Warning |
+| Spec document links valid | `extended_context.notes.spec_documents` paths resolve | Warning |
+| Epic dependencies mapped | Cross-epic dependencies reflected in issue dependency references | Warning |
+| All epics covered | Non-MVP epics also have corresponding issues | Info |
+
+---
+
+## Cross-Document Validation
+
+Checks performed during Phase 6 across all documents:
+
+### Completeness Matrix
+
+```
+Product Brief goals  ->  Requirements (each goal has >= 1 requirement)
+Requirements         ->  Architecture (each Must requirement has design coverage)
+Requirements         ->  Epics (each Must requirement appears in >= 1 story)
+Architecture ADRs    ->  Epics (tech choices reflected in implementation stories)
+Glossary terms       ->  All Documents (core terms used consistently)
+Non-Goals (Brief)    ->  Requirements + Epics (no contradictions)
+```
+
+### Consistency Checks
+
+| Check | Documents | Rule |
+|-------|-----------|------|
+| Terminology | All | Same term used consistently (no synonyms for same concept) |
+| User personas | Brief + PRD + Epics | Same user names/roles throughout |
+| Scope | Brief + PRD | PRD scope does not exceed brief scope |
+| Tech stack | Architecture + Epics | Stories reference correct technologies |
+| Glossary compliance | All | Core terms match glossary.json definitions, no synonym drift |
+| Scope containment | Brief + PRD | PRD requirements do not introduce scope beyond brief boundaries |
+| Non-Goals respected | Brief + PRD + Epics | No requirement/story contradicts explicit Non-Goals |
+
+### Traceability Matrix Format
+
+```markdown
+| Goal | Requirements | Architecture | Epics |
+|------|-------------|--------------|-------|
+| G-001: ... | REQ-001, REQ-002 | ADR-001 | EPIC-001 |
+| G-002: ... | REQ-003 | ADR-002 | EPIC-002, EPIC-003 |
+```
+
+---
+
+## Issue Classification
+
+### Error (Must Fix)
+
+- Missing required document or section
+- Broken cross-references
+- Contradictory information between documents
+- Empty acceptance criteria on Must-have requirements
+- No MVP subset defined in epics
+
+### Warning (Should Fix)
+
+- Vague acceptance criteria
+- Missing non-functional requirements
+- No success metrics defined
+- Incomplete traceability
+- Missing architecture review notes
+
+### Info (Nice to Have)
+
+- Could add more detailed personas
+- Consider additional ADR alternatives
+- Story estimation hints missing
+- Mermaid diagrams could be more detailed
+
+---
+
+## Iteration Quality Tracking
+
+When Phase 6.5 (Auto-Fix) is triggered:
+
+| Iteration | Expected Improvement | Max Iterations |
+|-----------|---------------------|----------------|
+| 1st | Fix all Error-severity issues | - |
+| 2nd | Fix remaining Warnings, improve scores | Max reached |
+
+### Iteration Exit Criteria
+
+| Condition | Action |
+|-----------|--------|
+| Overall score >= 80% after fix | Pass, proceed to handoff |
+| Overall score 60-79% after 2 iterations | Review, proceed with caveats |
+| Overall score < 60% after 2 iterations | Fail, manual intervention required |
+| No Error-severity issues remaining | Eligible for handoff regardless of score |

.codex/skills/spec-generator/templates/architecture-doc.md

@@ -0,0 +1,373 @@
+# Architecture Document Template (Directory Structure)
+
+Template for generating architecture decision documents as a directory of individual ADR files in Phase 4.
+
+## Usage Context
+
+| Phase | Usage |
+|-------|-------|
+| Phase 4 (Architecture) | Generate `architecture/` directory from requirements analysis |
+| Output Location | `{workDir}/architecture/` |
+
+## Output Structure
+
+```
+{workDir}/architecture/
+├── _index.md                      # Overview, components, tech stack, data model, security
+├── ADR-001-{slug}.md              # Individual Architecture Decision Record
+├── ADR-002-{slug}.md
+└── ...
+```
+
+---
+
+## Template: _index.md
+
+```markdown
+---
+session_id: {session_id}
+phase: 4
+document_type: architecture-index
+status: draft
+generated_at: {timestamp}
+version: 1
+dependencies:
+  - ../spec-config.json
+  - ../product-brief.md
+  - ../requirements/_index.md
+---
+
+# Architecture: {product_name}
+
+{executive_summary - high-level architecture approach and key decisions}
+
+## System Overview
+
+### Architecture Style
+{description of chosen architecture style: microservices, monolith, serverless, etc.}
+
+### System Context Diagram
+
+```mermaid
+C4Context
+    title System Context Diagram
+    Person(user, "User", "Primary user")
+    System(system, "{product_name}", "Core system")
+    System_Ext(ext1, "{external_system}", "{description}")
+    Rel(user, system, "Uses")
+    Rel(system, ext1, "Integrates with")
+```
+
+## Component Architecture
+
+### Component Diagram
+
+```mermaid
+graph TD
+    subgraph "{product_name}"
+        A[Component A] --> B[Component B]
+        B --> C[Component C]
+        A --> D[Component D]
+    end
+    B --> E[External Service]
+```
+
+### Component Descriptions
+
+| Component | Responsibility | Technology | Dependencies |
+|-----------|---------------|------------|--------------|
+| {component_name} | {what it does} | {tech stack} | {depends on} |
+
+## Technology Stack
+
+### Core Technologies
+
+| Layer | Technology | Version | Rationale |
+|-------|-----------|---------|-----------|
+| Frontend | {technology} | {version} | {why chosen} |
+| Backend | {technology} | {version} | {why chosen} |
+| Database | {technology} | {version} | {why chosen} |
+| Infrastructure | {technology} | {version} | {why chosen} |
+
+### Key Libraries & Frameworks
+
+| Library | Purpose | License |
+|---------|---------|---------|
+| {library_name} | {purpose} | {license} |
+
+## Architecture Decision Records
+
+| ADR | Title | Status | Key Choice |
+|-----|-------|--------|------------|
+| [ADR-001](ADR-001-{slug}.md) | {title} | Accepted | {one-line summary} |
+| [ADR-002](ADR-002-{slug}.md) | {title} | Accepted | {one-line summary} |
+| [ADR-003](ADR-003-{slug}.md) | {title} | Proposed | {one-line summary} |
+
+## Data Architecture
+
+### Data Model
+
+```mermaid
+erDiagram
+    ENTITY_A ||--o{ ENTITY_B : "has many"
+    ENTITY_A {
+        string id PK
+        string name
+        datetime created_at
+    }
+    ENTITY_B {
+        string id PK
+        string entity_a_id FK
+        string value
+    }
+```
+
+### Data Storage Strategy
+
+| Data Type | Storage | Retention | Backup |
+|-----------|---------|-----------|--------|
+| {type} | {storage solution} | {retention policy} | {backup strategy} |
+
+## API Design
+
+### API Overview
+
+| Endpoint | Method | Purpose | Auth |
+|----------|--------|---------|------|
+| {/api/resource} | {GET/POST/etc} | {purpose} | {auth type} |
+
+## Security Architecture
+
+### Security Controls
+
+| Control | Implementation | Requirement |
+|---------|---------------|-------------|
+| Authentication | {approach} | [NFR-S-{NNN}](../requirements/NFR-S-{NNN}-{slug}.md) |
+| Authorization | {approach} | [NFR-S-{NNN}](../requirements/NFR-S-{NNN}-{slug}.md) |
+| Data Protection | {approach} | [NFR-S-{NNN}](../requirements/NFR-S-{NNN}-{slug}.md) |
+
+## Infrastructure & Deployment
+
+### Deployment Architecture
+
+{description of deployment model: containers, serverless, VMs, etc.}
+
+### Environment Strategy
+
+| Environment | Purpose | Configuration |
+|-------------|---------|---------------|
+| Development | Local development | {config} |
+| Staging | Pre-production testing | {config} |
+| Production | Live system | {config} |
+
+## Codebase Integration
+
+{if has_codebase is true:}
+
+### Existing Code Mapping
+
+| New Component | Existing Module | Integration Type | Notes |
+|--------------|----------------|------------------|-------|
+| {component} | {existing module path} | Extend/Replace/New | {notes} |
+
+### Migration Notes
+{any migration considerations for existing code}
+
+## Quality Attributes
+
+| Attribute | Target | Measurement | ADR Reference |
+|-----------|--------|-------------|---------------|
+| Performance | {target} | {how measured} | [ADR-{NNN}](ADR-{NNN}-{slug}.md) |
+| Scalability | {target} | {how measured} | [ADR-{NNN}](ADR-{NNN}-{slug}.md) |
+| Reliability | {target} | {how measured} | [ADR-{NNN}](ADR-{NNN}-{slug}.md) |
+
+## State Machine
+
+{For each core entity with a lifecycle (e.g., Order, Session, Task):}
+
+### {Entity} Lifecycle
+
+```
+{ASCII state diagram showing all states, transitions, triggers, and error paths}
+
+  ┌──────────┐
+  │  Created  │
+  └─────┬────┘
+        │ start()
+        ▼
+  ┌──────────┐     error      ┌──────────┐
+  │  Running  │ ──────────▶   │  Failed   │
+  └─────┬────┘               └──────────┘
+        │ complete()
+        ▼
+  ┌──────────┐
+  │ Completed │
+  └──────────┘
+```
+
+| From State | Event | To State | Side Effects | Error Handling |
+|-----------|-------|----------|-------------|----------------|
+| {from} | {event} | {to} | {side_effects} | {error_behavior} |
+
+## Configuration Model
+
+### Required Configuration
+
+| Field | Type | Default | Constraint | Description |
+|-------|------|---------|------------|-------------|
+| {field_name} | {string/number/boolean/enum} | {default_value} | {validation rule} | {description} |
+
+### Optional Configuration
+
+| Field | Type | Default | Constraint | Description |
+|-------|------|---------|------------|-------------|
+| {field_name} | {type} | {default} | {constraint} | {description} |
+
+### Environment Variables
+
+| Variable | Maps To | Required |
+|----------|---------|----------|
+| {ENV_VAR} | {config_field} | {yes/no} |
+
+## Error Handling
+
+### Error Classification
+
+| Category | Severity | Retry | Example |
+|----------|----------|-------|---------|
+| Transient | Low | Yes, with backoff | Network timeout, rate limit |
+| Permanent | High | No | Invalid configuration, auth failure |
+| Degraded | Medium | Partial | Dependency unavailable, fallback active |
+
+### Per-Component Error Strategy
+
+| Component | Error Scenario | Behavior | Recovery |
+|-----------|---------------|----------|----------|
+| {component} | {scenario} | {MUST/SHOULD behavior} | {recovery strategy} |
+
+## Observability
+
+### Metrics
+
+| Metric Name | Type | Labels | Description |
+|-------------|------|--------|-------------|
+| {metric_name} | {counter/gauge/histogram} | {label1, label2} | {what it measures} |
+
+### Logging
+
+| Event | Level | Fields | Description |
+|-------|-------|--------|-------------|
+| {event_name} | {INFO/WARN/ERROR} | {structured fields} | {when logged} |
+
+### Health Checks
+
+| Check | Endpoint | Interval | Failure Action |
+|-------|----------|----------|----------------|
+| {check_name} | {/health/xxx} | {duration} | {action on failure} |
+
+## Trust & Safety
+
+### Trust Levels
+
+| Level | Description | Approval Required | Allowed Operations |
+|-------|-------------|-------------------|-------------------|
+| High Trust | {description} | None | {operations} |
+| Standard | {description} | {approval type} | {operations} |
+| Low Trust | {description} | {approval type} | {operations} |
+
+### Security Controls
+
+{Detailed security controls beyond the basic auth covered in Security Architecture}
+
+## Implementation Guidance
+
+### Key Decisions for Implementers
+
+| Decision | Options | Recommendation | Rationale |
+|----------|---------|---------------|-----------|
+| {decision_area} | {option_1, option_2} | {recommended} | {why} |
+
+### Implementation Order
+
+1. {component/module 1}: {why first}
+2. {component/module 2}: {depends on #1}
+
+### Testing Strategy
+
+| Layer | Scope | Tools | Coverage Target |
+|-------|-------|-------|-----------------|
+| Unit | {scope} | {tools} | {target} |
+| Integration | {scope} | {tools} | {target} |
+| E2E | {scope} | {tools} | {target} |
+
+## Risks & Mitigations
+
+| Risk | Impact | Probability | Mitigation |
+|------|--------|-------------|------------|
+| {risk} | High/Medium/Low | High/Medium/Low | {mitigation approach} |
+
+## Open Questions
+
+- [ ] {architectural question 1}
+- [ ] {architectural question 2}
+
+## References
+
+- Derived from: [Requirements](../requirements/_index.md), [Product Brief](../product-brief.md)
+- Next: [Epics & Stories](../epics/_index.md)
+```
+
+---
+
+## Template: ADR-NNN-{slug}.md (Individual Architecture Decision Record)
+
+```markdown
+---
+id: ADR-{NNN}
+status: Accepted
+traces_to: [{REQ-NNN}, {NFR-X-NNN}]
+date: {timestamp}
+---
+
+# ADR-{NNN}: {decision_title}
+
+## Context
+
+{what is the situation that motivates this decision}
+
+## Decision
+
+{what is the chosen approach}
+
+## Alternatives Considered
+
+| Option | Pros | Cons |
+|--------|------|------|
+| {option_1 - chosen} | {pros} | {cons} |
+| {option_2} | {pros} | {cons} |
+| {option_3} | {pros} | {cons} |
+
+## Consequences
+
+- **Positive**: {positive outcomes}
+- **Negative**: {tradeoffs accepted}
+- **Risks**: {risks to monitor}
+
+## Traces
+
+- **Requirements**: [REQ-{NNN}](../requirements/REQ-{NNN}-{slug}.md), [NFR-X-{NNN}](../requirements/NFR-X-{NNN}-{slug}.md)
+- **Implemented by**: [EPIC-{NNN}](../epics/EPIC-{NNN}-{slug}.md) (added in Phase 5)
+```
+
+---
+
+## Variable Descriptions
+
+| Variable | Source | Description |
+|----------|--------|-------------|
+| `{session_id}` | spec-config.json | Session identifier |
+| `{timestamp}` | Runtime | ISO8601 generation timestamp |
+| `{product_name}` | product-brief.md | Product/feature name |
+| `{NNN}` | Auto-increment | ADR/requirement number |
+| `{slug}` | Auto-generated | Kebab-case from decision title |
+| `{has_codebase}` | spec-config.json | Whether existing codebase exists |

.codex/skills/spec-generator/templates/epics-template.md

@@ -0,0 +1,209 @@
+# Epics & Stories Template (Directory Structure)
+
+Template for generating epic/story breakdown as a directory of individual Epic files in Phase 5.
+
+## Usage Context
+
+| Phase | Usage |
+|-------|-------|
+| Phase 5 (Epics & Stories) | Generate `epics/` directory from requirements decomposition |
+| Output Location | `{workDir}/epics/` |
+
+## Output Structure
+
+```
+{workDir}/epics/
+├── _index.md                      # Overview table + dependency map + MVP scope + execution order
+├── EPIC-001-{slug}.md             # Individual Epic with its Stories
+├── EPIC-002-{slug}.md
+└── ...
+```
+
+---
+
+## Template: _index.md
+
+```markdown
+---
+session_id: {session_id}
+phase: 5
+document_type: epics-index
+status: draft
+generated_at: {timestamp}
+version: 1
+dependencies:
+  - ../spec-config.json
+  - ../product-brief.md
+  - ../requirements/_index.md
+  - ../architecture/_index.md
+---
+
+# Epics & Stories: {product_name}
+
+{executive_summary - overview of epic structure and MVP scope}
+
+## Epic Overview
+
+| Epic ID | Title | Priority | MVP | Stories | Est. Size |
+|---------|-------|----------|-----|---------|-----------|
+| [EPIC-001](EPIC-001-{slug}.md) | {title} | Must | Yes | {n} | {S/M/L/XL} |
+| [EPIC-002](EPIC-002-{slug}.md) | {title} | Must | Yes | {n} | {S/M/L/XL} |
+| [EPIC-003](EPIC-003-{slug}.md) | {title} | Should | No | {n} | {S/M/L/XL} |
+
+## Dependency Map
+
+```mermaid
+graph LR
+    EPIC-001 --> EPIC-002
+    EPIC-001 --> EPIC-003
+    EPIC-002 --> EPIC-004
+    EPIC-003 --> EPIC-005
+```
+
+### Dependency Notes
+{explanation of why these dependencies exist and suggested execution order}
+
+### Recommended Execution Order
+1. [EPIC-{NNN}](EPIC-{NNN}-{slug}.md): {reason - foundational}
+2. [EPIC-{NNN}](EPIC-{NNN}-{slug}.md): {reason - depends on #1}
+3. ...
+
+## MVP Scope
+
+### MVP Epics
+{list of epics included in MVP with justification, linking to each}
+
+### MVP Definition of Done
+- [ ] {MVP completion criterion 1}
+- [ ] {MVP completion criterion 2}
+- [ ] {MVP completion criterion 3}
+
+## Traceability Matrix
+
+| Requirement | Epic | Stories | Architecture |
+|-------------|------|---------|--------------|
+| [REQ-001](../requirements/REQ-001-{slug}.md) | [EPIC-001](EPIC-001-{slug}.md) | STORY-001-001, STORY-001-002 | [ADR-001](../architecture/ADR-001-{slug}.md) |
+| [REQ-002](../requirements/REQ-002-{slug}.md) | [EPIC-001](EPIC-001-{slug}.md) | STORY-001-003 | Component B |
+| [REQ-003](../requirements/REQ-003-{slug}.md) | [EPIC-002](EPIC-002-{slug}.md) | STORY-002-001 | [ADR-002](../architecture/ADR-002-{slug}.md) |
+
+## Estimation Summary
+
+| Size | Meaning | Count |
+|------|---------|-------|
+| S | Small - well-understood, minimal risk | {n} |
+| M | Medium - some complexity, moderate risk | {n} |
+| L | Large - significant complexity, should consider splitting | {n} |
+| XL | Extra Large - high complexity, must split before implementation | {n} |
+
+## Risks & Considerations
+
+| Risk | Affected Epics | Mitigation |
+|------|---------------|------------|
+| {risk description} | [EPIC-{NNN}](EPIC-{NNN}-{slug}.md) | {mitigation} |
+
+## Versioning & Changelog
+
+### Version Strategy
+- **Versioning Scheme**: {semver/calver/custom}
+- **Breaking Change Definition**: {what constitutes a breaking change}
+- **Deprecation Policy**: {how deprecated features are handled}
+
+### Changelog
+
+| Version | Date | Type | Description |
+|---------|------|------|-------------|
+| {version} | {date} | {Added/Changed/Fixed/Removed} | {description} |
+
+## Open Questions
+
+- [ ] {question about scope or implementation 1}
+- [ ] {question about scope or implementation 2}
+
+## References
+
+- Derived from: [Requirements](../requirements/_index.md), [Architecture](../architecture/_index.md)
+- Handoff to: execution workflows (lite-plan, plan, req-plan)
+```
+
+---
+
+## Template: EPIC-NNN-{slug}.md (Individual Epic)
+
+```markdown
+---
+id: EPIC-{NNN}
+priority: {Must|Should|Could}
+mvp: {true|false}
+size: {S|M|L|XL}
+requirements: [REQ-{NNN}]
+architecture: [ADR-{NNN}]
+dependencies: [EPIC-{NNN}]
+status: draft
+---
+
+# EPIC-{NNN}: {epic_title}
+
+**Priority**: {Must|Should|Could}
+**MVP**: {Yes|No}
+**Estimated Size**: {S|M|L|XL}
+
+## Description
+
+{detailed epic description}
+
+## Requirements
+
+- [REQ-{NNN}](../requirements/REQ-{NNN}-{slug}.md): {title}
+- [REQ-{NNN}](../requirements/REQ-{NNN}-{slug}.md): {title}
+
+## Architecture
+
+- [ADR-{NNN}](../architecture/ADR-{NNN}-{slug}.md): {title}
+- Component: {component_name}
+
+## Dependencies
+
+- [EPIC-{NNN}](EPIC-{NNN}-{slug}.md) (blocking): {reason}
+- [EPIC-{NNN}](EPIC-{NNN}-{slug}.md) (soft): {reason}
+
+## Stories
+
+### STORY-{EPIC}-001: {story_title}
+
+**User Story**: As a {persona}, I want to {action} so that {benefit}.
+
+**Acceptance Criteria**:
+- [ ] {criterion 1}
+- [ ] {criterion 2}
+- [ ] {criterion 3}
+
+**Size**: {S|M|L|XL}
+**Traces to**: [REQ-{NNN}](../requirements/REQ-{NNN}-{slug}.md)
+
+---
+
+### STORY-{EPIC}-002: {story_title}
+
+**User Story**: As a {persona}, I want to {action} so that {benefit}.
+
+**Acceptance Criteria**:
+- [ ] {criterion 1}
+- [ ] {criterion 2}
+
+**Size**: {S|M|L|XL}
+**Traces to**: [REQ-{NNN}](../requirements/REQ-{NNN}-{slug}.md)
+```
+
+---
+
+## Variable Descriptions
+
+| Variable | Source | Description |
+|----------|--------|-------------|
+| `{session_id}` | spec-config.json | Session identifier |
+| `{timestamp}` | Runtime | ISO8601 generation timestamp |
+| `{product_name}` | product-brief.md | Product/feature name |
+| `{EPIC}` | Auto-increment | Epic number (3 digits) |
+| `{NNN}` | Auto-increment | Story/requirement number |
+| `{slug}` | Auto-generated | Kebab-case from epic/story title |
+| `{S\|M\|L\|XL}` | CLI analysis | Relative size estimate |

.codex/skills/spec-generator/templates/product-brief.md

@@ -0,0 +1,153 @@
+# Product Brief Template
+
+Template for generating product brief documents in Phase 2.
+
+## Usage Context
+
+| Phase | Usage |
+|-------|-------|
+| Phase 2 (Product Brief) | Generate product-brief.md from multi-CLI analysis |
+| Output Location | `{workDir}/product-brief.md` |
+
+---
+
+## Template
+
+```markdown
+---
+session_id: {session_id}
+phase: 2
+document_type: product-brief
+status: draft
+generated_at: {timestamp}
+stepsCompleted: []
+version: 1
+dependencies:
+  - spec-config.json
+---
+
+# Product Brief: {product_name}
+
+{executive_summary - 2-3 sentences capturing the essence of the product/feature}
+
+## Concepts & Terminology
+
+| Term | Definition | Aliases |
+|------|-----------|---------|
+| {term_1} | {definition} | {comma-separated aliases if any} |
+| {term_2} | {definition} | |
+
+{Note: All documents in this specification MUST use these terms consistently.}
+
+## Vision
+
+{vision_statement - clear, aspirational 1-3 sentence statement of what success looks like}
+
+## Problem Statement
+
+### Current Situation
+{description of the current state and pain points}
+
+### Impact
+{quantified impact of the problem - who is affected, how much, how often}
+
+## Target Users
+
+{for each user persona:}
+
+### {Persona Name}
+- **Role**: {user's role/context}
+- **Needs**: {primary needs related to this product}
+- **Pain Points**: {current frustrations}
+- **Success Criteria**: {what success looks like for this user}
+
+## Goals & Success Metrics
+
+| Goal ID | Goal | Success Metric | Target |
+|---------|------|----------------|--------|
+| G-001 | {goal description} | {measurable metric} | {specific target} |
+| G-002 | {goal description} | {measurable metric} | {specific target} |
+
+## Scope
+
+### In Scope
+- {feature/capability 1}
+- {feature/capability 2}
+- {feature/capability 3}
+
+### Out of Scope
+- {explicitly excluded item 1}
+- {explicitly excluded item 2}
+
+### Non-Goals
+
+{Explicit list of things this project will NOT do, with rationale for each:}
+
+| Non-Goal | Rationale |
+|----------|-----------|
+| {non_goal_1} | {why this is explicitly excluded} |
+| {non_goal_2} | {why this is explicitly excluded} |
+
+### Assumptions
+- {key assumption 1}
+- {key assumption 2}
+
+## Competitive Landscape
+
+| Aspect | Current State | Proposed Solution | Advantage |
+|--------|--------------|-------------------|-----------|
+| {aspect} | {how it's done now} | {our approach} | {differentiator} |
+
+## Constraints & Dependencies
+
+### Technical Constraints
+- {constraint 1}
+- {constraint 2}
+
+### Business Constraints
+- {constraint 1}
+
+### Dependencies
+- {external dependency 1}
+- {external dependency 2}
+
+## Multi-Perspective Synthesis
+
+### Product Perspective
+{summary of product/market analysis findings}
+
+### Technical Perspective
+{summary of technical feasibility and constraints}
+
+### User Perspective
+{summary of user journey and UX considerations}
+
+### Convergent Themes
+{themes where all perspectives agree}
+
+### Conflicting Views
+{areas where perspectives differ, with notes on resolution approach}
+
+## Open Questions
+
+- [ ] {unresolved question 1}
+- [ ] {unresolved question 2}
+
+## References
+
+- Derived from: [spec-config.json](spec-config.json)
+- Next: [Requirements PRD](requirements.md)
+```
+
+## Variable Descriptions
+
+| Variable | Source | Description |
+|----------|--------|-------------|
+| `{session_id}` | spec-config.json | Session identifier |
+| `{timestamp}` | Runtime | ISO8601 generation timestamp |
+| `{product_name}` | Seed analysis | Product/feature name |
+| `{executive_summary}` | CLI synthesis | 2-3 sentence summary |
+| `{vision_statement}` | CLI product perspective | Aspirational vision |
+| `{term_1}`, `{term_2}` | CLI synthesis | Domain terms with definitions and optional aliases |
+| `{non_goal_1}`, `{non_goal_2}` | CLI synthesis | Explicit exclusions with rationale |
+| All `{...}` fields | CLI analysis outputs | Filled from multi-perspective analysis |

.codex/skills/spec-generator/templates/profiles/api-profile.md

@@ -0,0 +1,27 @@
+# API Spec Profile
+
+Defines additional required sections for API-type specifications.
+
+## Required Sections (in addition to base template)
+
+### In Architecture Document
+- **Endpoint Definition**: MUST list all endpoints with method, path, auth, request/response schema
+- **Authentication Model**: MUST define auth mechanism (OAuth2/JWT/API Key), token lifecycle
+- **Rate Limiting**: MUST define rate limits per tier/endpoint, throttling behavior
+- **Error Codes**: MUST define error response format, standard error codes with descriptions
+- **API Versioning**: MUST define versioning strategy (URL/header/query), deprecation policy
+- **Pagination**: SHOULD define pagination strategy for list endpoints
+- **Idempotency**: SHOULD define idempotency requirements for write operations
+
+### In Requirements Document
+- **Endpoint Acceptance Criteria**: Each requirement SHOULD map to specific endpoints
+- **SLA Definitions**: MUST define response time, availability targets per endpoint tier
+
+### Quality Gate Additions
+| Check | Criteria | Severity |
+|-------|----------|----------|
+| Endpoints documented | All endpoints with method + path | Error |
+| Auth model defined | Authentication mechanism specified | Error |
+| Error codes defined | Standard error format + codes | Warning |
+| Rate limits defined | Per-endpoint or per-tier limits | Warning |
+| API versioning strategy | Versioning approach specified | Warning |

.codex/skills/spec-generator/templates/profiles/library-profile.md

@@ -0,0 +1,25 @@
+# Library Spec Profile
+
+Defines additional required sections for library/SDK-type specifications.
+
+## Required Sections (in addition to base template)
+
+### In Architecture Document
+- **Public API Surface**: MUST define all public interfaces with signatures, parameters, return types
+- **Usage Examples**: MUST provide >= 3 code examples showing common usage patterns
+- **Compatibility Matrix**: MUST define supported language versions, runtime environments
+- **Dependency Policy**: MUST define transitive dependency policy, version constraints
+- **Extension Points**: SHOULD define plugin/extension mechanisms if applicable
+- **Bundle Size**: SHOULD define target bundle size and tree-shaking strategy
+
+### In Requirements Document
+- **API Ergonomics**: Requirements SHOULD address developer experience and API consistency
+- **Error Reporting**: MUST define error types, messages, and recovery hints for consumers
+
+### Quality Gate Additions
+| Check | Criteria | Severity |
+|-------|----------|----------|
+| Public API documented | All public interfaces with types | Error |
+| Usage examples | >= 3 working examples | Warning |
+| Compatibility matrix | Supported environments listed | Warning |
+| Dependency policy | Transitive deps strategy defined | Info |

.codex/skills/spec-generator/templates/profiles/service-profile.md

@@ -0,0 +1,28 @@
+# Service Spec Profile
+
+Defines additional required sections for service-type specifications.
+
+## Required Sections (in addition to base template)
+
+### In Architecture Document
+- **Concepts & Terminology**: MUST define all domain terms with consistent aliases
+- **State Machine**: MUST include ASCII state diagram for each entity with a lifecycle
+- **Configuration Model**: MUST define all configurable fields with types, defaults, constraints
+- **Error Handling**: MUST define per-component error classification and recovery strategies
+- **Observability**: MUST define >= 3 metrics, structured log format, health check endpoints
+- **Trust & Safety**: SHOULD define trust levels and approval matrix
+- **Graceful Shutdown**: MUST describe shutdown sequence and cleanup procedures
+- **Implementation Guidance**: SHOULD provide implementation order and key decisions
+
+### In Requirements Document
+- **Behavioral Constraints**: MUST use RFC 2119 keywords (MUST/SHOULD/MAY) for all requirements
+- **Data Model**: MUST define core entities with field-level detail (type, constraint, relation)
+
+### Quality Gate Additions
+| Check | Criteria | Severity |
+|-------|----------|----------|
+| State machine present | >= 1 lifecycle state diagram | Error |
+| Configuration model | All config fields documented | Warning |
+| Observability metrics | >= 3 metrics defined | Warning |
+| Error handling defined | Per-component strategy | Warning |
+| RFC keywords used | Behavioral requirements use MUST/SHOULD/MAY | Warning |

.codex/skills/spec-generator/templates/requirements-prd.md

@@ -0,0 +1,224 @@
+# Requirements PRD Template (Directory Structure)
+
+Template for generating Product Requirements Document as a directory of individual requirement files in Phase 3.
+
+## Usage Context
+
+| Phase | Usage |
+|-------|-------|
+| Phase 3 (Requirements) | Generate `requirements/` directory from product brief expansion |
+| Output Location | `{workDir}/requirements/` |
+
+## Output Structure
+
+```
+{workDir}/requirements/
+├── _index.md                      # Summary + MoSCoW table + traceability matrix + links
+├── REQ-001-{slug}.md              # Individual functional requirement
+├── REQ-002-{slug}.md
+├── NFR-P-001-{slug}.md            # Non-functional: Performance
+├── NFR-S-001-{slug}.md            # Non-functional: Security
+├── NFR-SC-001-{slug}.md           # Non-functional: Scalability
+├── NFR-U-001-{slug}.md            # Non-functional: Usability
+└── ...
+```
+
+---
+
+## Template: _index.md
+
+```markdown
+---
+session_id: {session_id}
+phase: 3
+document_type: requirements-index
+status: draft
+generated_at: {timestamp}
+version: 1
+dependencies:
+  - ../spec-config.json
+  - ../product-brief.md
+---
+
+# Requirements: {product_name}
+
+{executive_summary - brief overview of what this PRD covers and key decisions}
+
+## Requirement Summary
+
+| Priority | Count | Coverage |
+|----------|-------|----------|
+| Must Have | {n} | {description of must-have scope} |
+| Should Have | {n} | {description of should-have scope} |
+| Could Have | {n} | {description of could-have scope} |
+| Won't Have | {n} | {description of explicitly excluded} |
+
+## Functional Requirements
+
+| ID | Title | Priority | Traces To |
+|----|-------|----------|-----------|
+| [REQ-001](REQ-001-{slug}.md) | {title} | Must | [G-001](../product-brief.md#goals--success-metrics) |
+| [REQ-002](REQ-002-{slug}.md) | {title} | Must | [G-001](../product-brief.md#goals--success-metrics) |
+| [REQ-003](REQ-003-{slug}.md) | {title} | Should | [G-002](../product-brief.md#goals--success-metrics) |
+
+## Non-Functional Requirements
+
+### Performance
+
+| ID | Title | Target |
+|----|-------|--------|
+| [NFR-P-001](NFR-P-001-{slug}.md) | {title} | {target value} |
+
+### Security
+
+| ID | Title | Standard |
+|----|-------|----------|
+| [NFR-S-001](NFR-S-001-{slug}.md) | {title} | {standard/framework} |
+
+### Scalability
+
+| ID | Title | Target |
+|----|-------|--------|
+| [NFR-SC-001](NFR-SC-001-{slug}.md) | {title} | {target value} |
+
+### Usability
+
+| ID | Title | Target |
+|----|-------|--------|
+| [NFR-U-001](NFR-U-001-{slug}.md) | {title} | {target value} |
+
+## Data Requirements
+
+### Data Entities
+
+| Entity | Description | Key Attributes |
+|--------|-------------|----------------|
+| {entity_name} | {description} | {attr1, attr2, attr3} |
+
+### Data Flows
+
+{description of key data flows, optionally with Mermaid diagram}
+
+## Integration Requirements
+
+| System | Direction | Protocol | Data Format | Notes |
+|--------|-----------|----------|-------------|-------|
+| {system_name} | Inbound/Outbound/Both | {REST/gRPC/etc} | {JSON/XML/etc} | {notes} |
+
+## Constraints & Assumptions
+
+### Constraints
+- {technical or business constraint 1}
+- {technical or business constraint 2}
+
+### Assumptions
+- {assumption 1 - must be validated}
+- {assumption 2 - must be validated}
+
+## Priority Rationale
+
+{explanation of MoSCoW prioritization decisions, especially for Should/Could boundaries}
+
+## Traceability Matrix
+
+| Goal | Requirements |
+|------|-------------|
+| G-001 | [REQ-001](REQ-001-{slug}.md), [REQ-002](REQ-002-{slug}.md), [NFR-P-001](NFR-P-001-{slug}.md) |
+| G-002 | [REQ-003](REQ-003-{slug}.md), [NFR-S-001](NFR-S-001-{slug}.md) |
+
+## Open Questions
+
+- [ ] {unresolved question 1}
+- [ ] {unresolved question 2}
+
+## References
+
+- Derived from: [Product Brief](../product-brief.md)
+- Next: [Architecture](../architecture/_index.md)
+```
+
+---
+
+## Template: REQ-NNN-{slug}.md (Individual Functional Requirement)
+
+```markdown
+---
+id: REQ-{NNN}
+type: functional
+priority: {Must|Should|Could|Won't}
+traces_to: [G-{NNN}]
+status: draft
+---
+
+# REQ-{NNN}: {requirement_title}
+
+**Priority**: {Must|Should|Could|Won't}
+
+## Description
+
+{detailed requirement description}
+
+## User Story
+
+As a {persona}, I want to {action} so that {benefit}.
+
+## Acceptance Criteria
+
+- [ ] {specific, testable criterion 1}
+- [ ] {specific, testable criterion 2}
+- [ ] {specific, testable criterion 3}
+
+## Traces
+
+- **Goal**: [G-{NNN}](../product-brief.md#goals--success-metrics)
+- **Architecture**: [ADR-{NNN}](../architecture/ADR-{NNN}-{slug}.md) (if applicable)
+- **Implemented by**: [EPIC-{NNN}](../epics/EPIC-{NNN}-{slug}.md) (added in Phase 5)
+```
+
+---
+
+## Template: NFR-{type}-NNN-{slug}.md (Individual Non-Functional Requirement)
+
+```markdown
+---
+id: NFR-{type}-{NNN}
+type: non-functional
+category: {Performance|Security|Scalability|Usability}
+priority: {Must|Should|Could}
+status: draft
+---
+
+# NFR-{type}-{NNN}: {requirement_title}
+
+**Category**: {Performance|Security|Scalability|Usability}
+**Priority**: {Must|Should|Could}
+
+## Requirement
+
+{detailed requirement description}
+
+## Metric & Target
+
+| Metric | Target | Measurement Method |
+|--------|--------|--------------------|
+| {metric} | {target value} | {how measured} |
+
+## Traces
+
+- **Goal**: [G-{NNN}](../product-brief.md#goals--success-metrics)
+- **Architecture**: [ADR-{NNN}](../architecture/ADR-{NNN}-{slug}.md) (if applicable)
+```
+
+---
+
+## Variable Descriptions
+
+| Variable | Source | Description |
+|----------|--------|-------------|
+| `{session_id}` | spec-config.json | Session identifier |
+| `{timestamp}` | Runtime | ISO8601 generation timestamp |
+| `{product_name}` | product-brief.md | Product/feature name |
+| `{NNN}` | Auto-increment | Requirement number (zero-padded 3 digits) |
+| `{slug}` | Auto-generated | Kebab-case from requirement title |
+| `{type}` | Category | P (Performance), S (Security), SC (Scalability), U (Usability) |
+| `{Must\|Should\|Could\|Won't}` | User input / auto | MoSCoW priority tag |

.codex/skills/team-arch-opt/SKILL.md

@@ -0,0 +1,698 @@
+---
+name: team-arch-opt
+description: Architecture optimization team skill. Analyzes codebase architecture, designs refactoring plans, implements changes, validates improvements, and reviews code quality via CSV wave pipeline with interactive review-fix cycles.
+argument-hint: "[-y|--yes] [-c|--concurrency N] [--continue] \"architecture optimization task description\""
+allowed-tools: spawn_agents_on_csv, spawn_agent, wait, send_input, close_agent, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+## Auto Mode
+
+When `--yes` or `-y`: Auto-confirm task decomposition, skip interactive validation, use defaults.
+
+# Team Architecture Optimization
+
+## Usage
+
+```bash
+$team-arch-opt "Refactor the auth module to reduce coupling and eliminate circular dependencies"
+$team-arch-opt -c 4 "Analyze and fix God Classes across the service layer"
+$team-arch-opt -y "Remove dead code and clean up barrel exports in src/utils"
+$team-arch-opt --continue "tao-refactor-auth-20260308"
+```
+
+**Flags**:
+- `-y, --yes`: Skip all confirmations (auto mode)
+- `-c, --concurrency N`: Max concurrent agents within each wave (default: 3)
+- `--continue`: Resume existing session
+
+**Output Directory**: `.workflow/.csv-wave/{session-id}/`
+**Core Output**: `tasks.csv` (master state) + `results.csv` (final) + `discoveries.ndjson` (shared exploration) + `context.md` (human-readable report)
+
+---
+
+## Overview
+
+Orchestrate multi-agent architecture optimization: analyze codebase structure, design refactoring plan, implement changes, validate improvements, review code quality. The pipeline has five domain roles (analyzer, designer, refactorer, validator, reviewer) mapped to CSV wave stages with an interactive review-fix cycle.
+
+**Execution Model**: Hybrid -- CSV wave pipeline (primary) + individual agent spawn (secondary)
+
+```
++-------------------------------------------------------------------+
+|           TEAM ARCHITECTURE OPTIMIZATION WORKFLOW                   |
++-------------------------------------------------------------------+
+|                                                                     |
+|  Phase 0: Pre-Wave Interactive (Requirement Clarification)          |
+|     +- Parse user task description                                  |
+|     +- Detect scope: targeted module vs full architecture           |
+|     +- Clarify ambiguous requirements (AskUserQuestion)             |
+|     +- Output: refined requirements for decomposition               |
+|                                                                     |
+|  Phase 1: Requirement -> CSV + Classification                       |
+|     +- Identify architecture issues to target                       |
+|     +- Build 5-stage pipeline (analyze->design->refactor->validate  |
+|     |  +review)                                                     |
+|     +- Classify tasks: csv-wave | interactive (exec_mode)           |
+|     +- Compute dependency waves (topological sort)                  |
+|     +- Generate tasks.csv with wave + exec_mode columns             |
+|     +- User validates task breakdown (skip if -y)                   |
+|                                                                     |
+|  Phase 2: Wave Execution Engine (Extended)                          |
+|     +- For each wave (1..N):                                        |
+|     |   +- Execute pre-wave interactive tasks (if any)              |
+|     |   +- Build wave CSV (filter csv-wave tasks for this wave)     |
+|     |   +- Inject previous findings into prev_context column        |
+|     |   +- spawn_agents_on_csv(wave CSV)                            |
+|     |   +- Execute post-wave interactive tasks (if any)             |
+|     |   +- Merge all results into master tasks.csv                  |
+|     |   +- Check: any failed? -> skip dependents                    |
+|     +- discoveries.ndjson shared across all modes (append-only)     |
+|     +- Review-fix cycle: max 3 iterations per branch               |
+|                                                                     |
+|  Phase 3: Post-Wave Interactive (Completion Action)                 |
+|     +- Pipeline completion report with improvement metrics          |
+|     +- Interactive completion choice (Archive/Keep/Export)           |
+|     +- Final aggregation / report                                   |
+|                                                                     |
+|  Phase 4: Results Aggregation                                       |
+|     +- Export final results.csv                                     |
+|     +- Generate context.md with all findings                        |
+|     +- Display summary: completed/failed/skipped per wave           |
+|     +- Offer: view results | retry failed | done                    |
+|                                                                     |
++-------------------------------------------------------------------+
+```
+
+---
+
+## Pipeline Definition
+
+```
+Stage 1           Stage 2           Stage 3           Stage 4
+ANALYZE-001  -->  DESIGN-001  -->  REFACTOR-001 --> VALIDATE-001
+[analyzer]        [designer]       [refactorer]     [validator]
+                                       ^                |
+                                       +<-- FIX-001 ----+
+                                       |           REVIEW-001
+                                       +<-------->  [reviewer]
+                                              (max 3 iterations)
+```
+
+---
+
+## Task Classification Rules
+
+Each task is classified by `exec_mode`:
+
+| exec_mode | Mechanism | Criteria |
+|-----------|-----------|----------|
+| `csv-wave` | `spawn_agents_on_csv` | One-shot, structured I/O, no multi-round interaction |
+| `interactive` | `spawn_agent`/`wait`/`send_input`/`close_agent` | Multi-round, revision cycles, user checkpoints |
+
+**Classification Decision**:
+
+| Task Property | Classification |
+|---------------|---------------|
+| Architecture analysis (single-pass scan) | `csv-wave` |
+| Refactoring plan design (single-pass) | `csv-wave` |
+| Code refactoring implementation | `csv-wave` |
+| Validation (build, test, metrics) | `csv-wave` |
+| Code review (single-pass) | `csv-wave` |
+| Review-fix cycle (iterative revision) | `interactive` |
+| User checkpoint (plan approval) | `interactive` |
+| Discussion round (DISCUSS-REFACTOR, DISCUSS-REVIEW) | `interactive` |
+
+---
+
+## CSV Schema
+
+### tasks.csv (Master State)
+
+```csv
+id,title,description,role,issue_type,priority,target_files,deps,context_from,exec_mode,wave,status,findings,verdict,artifacts_produced,error
+"ANALYZE-001","Analyze architecture","Analyze codebase architecture to identify structural issues: cycles, coupling, cohesion, God Classes, dead code, API bloat. Produce baseline metrics and ranked report.","analyzer","","","","","","csv-wave","1","pending","","","",""
+"DESIGN-001","Design refactoring plan","Analyze architecture report to design prioritized refactoring plan with strategies, expected improvements, and risk assessments.","designer","","","","ANALYZE-001","ANALYZE-001","csv-wave","2","pending","","","",""
+"REFACTOR-001","Implement refactorings","Implement architecture refactoring changes following design plan in priority order (P0 first).","refactorer","","","","DESIGN-001","DESIGN-001","csv-wave","3","pending","","","",""
+"VALIDATE-001","Validate changes","Validate refactoring: build checks, test suite, dependency metrics, API compatibility.","validator","","","","REFACTOR-001","REFACTOR-001","csv-wave","4","pending","","PASS","",""
+"REVIEW-001","Review refactoring code","Review refactoring changes for correctness, patterns, completeness, migration safety, best practices.","reviewer","","","","REFACTOR-001","REFACTOR-001","csv-wave","4","pending","","APPROVE","",""
+```
+
+**Columns**:
+
+| Column | Phase | Description |
+|--------|-------|-------------|
+| `id` | Input | Unique task identifier (PREFIX-NNN format) |
+| `title` | Input | Short task title |
+| `description` | Input | Detailed task description (self-contained) |
+| `role` | Input | Worker role: analyzer, designer, refactorer, validator, reviewer |
+| `issue_type` | Input | Architecture issue category: CYCLE, COUPLING, COHESION, GOD_CLASS, DUPLICATION, LAYER_VIOLATION, DEAD_CODE, API_BLOAT |
+| `priority` | Input | P0 (Critical), P1 (High), P2 (Medium), P3 (Low) |
+| `target_files` | Input | Semicolon-separated file paths to focus on |
+| `deps` | Input | Semicolon-separated dependency task IDs |
+| `context_from` | Input | Semicolon-separated task IDs whose findings this task needs |
+| `exec_mode` | Input | `csv-wave` or `interactive` |
+| `wave` | Computed | Wave number (computed by topological sort, 1-based) |
+| `status` | Output | `pending` -> `completed` / `failed` / `skipped` |
+| `findings` | Output | Key discoveries or implementation notes (max 500 chars) |
+| `verdict` | Output | Validation/review verdict: PASS, WARN, FAIL, APPROVE, REVISE, REJECT |
+| `artifacts_produced` | Output | Semicolon-separated paths of produced artifacts |
+| `error` | Output | Error message if failed (empty if success) |
+
+### Per-Wave CSV (Temporary)
+
+Each wave generates a temporary `wave-{N}.csv` with extra `prev_context` column (csv-wave tasks only).
+
+---
+
+## Agent Registry (Interactive Agents)
+
+| Agent | Role File | Pattern | Responsibility | Position |
+|-------|-----------|---------|----------------|----------|
+| Plan Reviewer | agents/plan-reviewer.md | 2.3 (send_input cycle) | Review architecture report or refactoring plan at user checkpoint | pre-wave |
+| Fix Cycle Handler | agents/fix-cycle-handler.md | 2.3 (send_input cycle) | Manage review-fix iteration cycle (max 3 rounds) | post-wave |
+| Completion Handler | agents/completion-handler.md | 2.3 (send_input cycle) | Handle pipeline completion action (Archive/Keep/Export) | standalone |
+
+> **COMPACT PROTECTION**: Agent files are execution documents. When context compression occurs, **you MUST immediately `Read` the corresponding agent.md** to reload.
+
+---
+
+## Output Artifacts
+
+| File | Purpose | Lifecycle |
+|------|---------|-----------|
+| `tasks.csv` | Master state -- all tasks with status/findings | Updated after each wave |
+| `wave-{N}.csv` | Per-wave input (temporary, csv-wave tasks only) | Created before wave, deleted after |
+| `results.csv` | Final export of all task results | Created in Phase 4 |
+| `discoveries.ndjson` | Shared exploration board (all agents, both modes) | Append-only, carries across waves |
+| `context.md` | Human-readable execution report | Created in Phase 4 |
+| `task-analysis.json` | Phase 1 output: scope, issues, pipeline config | Created in Phase 1 |
+| `artifacts/architecture-baseline.json` | Analyzer: pre-refactoring metrics | Created by analyzer |
+| `artifacts/architecture-report.md` | Analyzer: ranked structural issue findings | Created by analyzer |
+| `artifacts/refactoring-plan.md` | Designer: prioritized refactoring plan | Created by designer |
+| `artifacts/validation-results.json` | Validator: post-refactoring validation | Created by validator |
+| `artifacts/review-report.md` | Reviewer: code review findings | Created by reviewer |
+| `interactive/{id}-result.json` | Results from interactive tasks | Created per interactive task |
+
+---
+
+## Session Structure
+
+```
+.workflow/.csv-wave/{session-id}/
++-- tasks.csv                  # Master state (all tasks, both modes)
++-- results.csv                # Final results export
++-- discoveries.ndjson         # Shared discovery board (all agents)
++-- context.md                 # Human-readable report
++-- task-analysis.json         # Phase 1 analysis output
++-- wave-{N}.csv               # Temporary per-wave input (csv-wave only)
++-- artifacts/
+|   +-- architecture-baseline.json   # Analyzer output
+|   +-- architecture-report.md       # Analyzer output
+|   +-- refactoring-plan.md          # Designer output
+|   +-- validation-results.json      # Validator output
+|   +-- review-report.md             # Reviewer output
++-- interactive/               # Interactive task artifacts
+|   +-- {id}-result.json
++-- wisdom/
+    +-- patterns.md            # Discovered patterns and conventions
+```
+
+---
+
+## Implementation
+
+### Session Initialization
+
+```javascript
+const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
+
+const AUTO_YES = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
+const continueMode = $ARGUMENTS.includes('--continue')
+const concurrencyMatch = $ARGUMENTS.match(/(?:--concurrency|-c)\s+(\d+)/)
+const maxConcurrency = concurrencyMatch ? parseInt(concurrencyMatch[1]) : 3
+
+const requirement = $ARGUMENTS
+  .replace(/--yes|-y|--continue|--concurrency\s+\d+|-c\s+\d+/g, '')
+  .trim()
+
+const slug = requirement.toLowerCase()
+  .replace(/[^a-z0-9\u4e00-\u9fa5]+/g, '-')
+  .substring(0, 40)
+const dateStr = getUtc8ISOString().substring(0, 10).replace(/-/g, '')
+const sessionId = `tao-${slug}-${dateStr}`
+const sessionFolder = `.workflow/.csv-wave/${sessionId}`
+
+Bash(`mkdir -p ${sessionFolder}/artifacts ${sessionFolder}/interactive ${sessionFolder}/wisdom`)
+
+// Initialize discoveries.ndjson
+Write(`${sessionFolder}/discoveries.ndjson`, '')
+
+// Initialize wisdom
+Write(`${sessionFolder}/wisdom/patterns.md`, '# Patterns & Conventions\n')
+```
+
+---
+
+### Phase 0: Pre-Wave Interactive (Requirement Clarification)
+
+**Objective**: Parse user task, detect architecture scope, clarify ambiguities, prepare for decomposition.
+
+**Workflow**:
+
+1. **Parse user task description** from $ARGUMENTS
+
+2. **Check for existing sessions** (continue mode):
+   - Scan `.workflow/.csv-wave/tao-*/tasks.csv` for sessions with pending tasks
+   - If `--continue`: resume the specified or most recent session, skip to Phase 2
+   - If active session found: ask user whether to resume or start new
+
+3. **Identify architecture optimization target**:
+
+| Signal | Target |
+|--------|--------|
+| Specific file/module mentioned | Scoped refactoring |
+| "coupling", "dependency", "structure", generic | Full architecture analysis |
+| Specific issue (cycles, God Class, duplication) | Targeted issue resolution |
+
+4. **Clarify if ambiguous** (skip if AUTO_YES):
+   ```javascript
+   AskUserQuestion({
+     questions: [{
+       question: "Please confirm the architecture optimization scope:",
+       header: "Architecture Scope",
+       multiSelect: false,
+       options: [
+         { label: "Proceed as described", description: "Scope is clear" },
+         { label: "Narrow scope", description: "Specify modules/files to focus on" },
+         { label: "Add constraints", description: "Exclude areas, set priorities" }
+       ]
+     }]
+   })
+   ```
+
+5. **Output**: Refined requirement string for Phase 1
+
+**Success Criteria**:
+- Refined requirements available for Phase 1 decomposition
+- Existing session detected and handled if applicable
+
+---
+
+### Phase 1: Requirement -> CSV + Classification
+
+**Objective**: Decompose architecture optimization task into the 5-stage pipeline tasks, assign waves, generate tasks.csv.
+
+**Decomposition Rules**:
+
+1. **Stage mapping** -- architecture optimization always follows this pipeline:
+
+| Stage | Role | Task Prefix | Wave | Description |
+|-------|------|-------------|------|-------------|
+| 1 | analyzer | ANALYZE | 1 | Scan codebase, identify structural issues, produce baseline metrics |
+| 2 | designer | DESIGN | 2 | Design refactoring plan from architecture report |
+| 3 | refactorer | REFACTOR | 3 | Implement refactorings per plan priority |
+| 4a | validator | VALIDATE | 4 | Validate build, tests, metrics, API compatibility |
+| 4b | reviewer | REVIEW | 4 | Review refactoring code for correctness and patterns |
+
+2. **Single-pipeline decomposition**: Generate one task per stage with sequential dependencies:
+   - ANALYZE-001 (wave 1, no deps)
+   - DESIGN-001 (wave 2, deps: ANALYZE-001)
+   - REFACTOR-001 (wave 3, deps: DESIGN-001)
+   - VALIDATE-001 (wave 4, deps: REFACTOR-001)
+   - REVIEW-001 (wave 4, deps: REFACTOR-001)
+
+3. **Description enrichment**: Each task description must be self-contained with:
+   - Clear goal statement
+   - Input artifacts to read
+   - Output artifacts to produce
+   - Success criteria
+   - Session folder path
+
+**Classification Rules**:
+
+| Task Property | exec_mode |
+|---------------|-----------|
+| ANALYZE, DESIGN, REFACTOR, VALIDATE, REVIEW (initial pass) | `csv-wave` |
+| FIX tasks (review-fix cycle) | `interactive` (handled by fix-cycle-handler agent) |
+
+**Wave Computation**: Kahn's BFS topological sort with depth tracking (csv-wave tasks only).
+
+**User Validation**: Display task breakdown with wave + exec_mode assignment (skip if AUTO_YES).
+
+**Success Criteria**:
+- tasks.csv created with valid schema, wave, and exec_mode assignments
+- task-analysis.json written with scope and pipeline config
+- No circular dependencies
+- User approved (or AUTO_YES)
+
+---
+
+### Phase 2: Wave Execution Engine (Extended)
+
+**Objective**: Execute tasks wave-by-wave with hybrid mechanism support and cross-wave context propagation.
+
+```javascript
+const masterCsv = Read(`${sessionFolder}/tasks.csv`)
+let tasks = parseCsv(masterCsv)
+const maxWave = Math.max(...tasks.map(t => t.wave))
+
+for (let wave = 1; wave <= maxWave; wave++) {
+  console.log(`\nWave ${wave}/${maxWave}`)
+
+  // 1. Separate tasks by exec_mode
+  const waveTasks = tasks.filter(t => t.wave === wave && t.status === 'pending')
+  const csvTasks = waveTasks.filter(t => t.exec_mode === 'csv-wave')
+  const interactiveTasks = waveTasks.filter(t => t.exec_mode === 'interactive')
+
+  // 2. Check dependencies -- skip tasks whose deps failed
+  for (const task of waveTasks) {
+    const depIds = (task.deps || '').split(';').filter(Boolean)
+    const depStatuses = depIds.map(id => tasks.find(t => t.id === id)?.status)
+    if (depStatuses.some(s => s === 'failed' || s === 'skipped')) {
+      task.status = 'skipped'
+      task.error = `Dependency failed: ${depIds.filter((id, i) =>
+        ['failed','skipped'].includes(depStatuses[i])).join(', ')}`
+    }
+  }
+
+  // 3. Execute pre-wave interactive tasks (if any)
+  for (const task of interactiveTasks.filter(t => t.status === 'pending')) {
+    // Determine agent file based on task type
+    const agentFile = task.id.startsWith('FIX') ? 'agents/fix-cycle-handler.md' : 'agents/plan-reviewer.md'
+    Read(agentFile)
+
+    const agent = spawn_agent({
+      message: `## TASK ASSIGNMENT\n\n### MANDATORY FIRST STEPS\n1. Read: ${agentFile}\n2. Read: ${sessionFolder}/discoveries.ndjson\n3. Read: .workflow/project-tech.json (if exists)\n\n---\n\nGoal: ${task.description}\nScope: ${task.title}\nSession: ${sessionFolder}\n\n### Previous Context\n${buildPrevContext(task, tasks)}`
+    })
+    const result = wait({ ids: [agent], timeout_ms: 600000 })
+    if (result.timed_out) {
+      send_input({ id: agent, message: "Please finalize and output current findings." })
+      wait({ ids: [agent], timeout_ms: 120000 })
+    }
+    Write(`${sessionFolder}/interactive/${task.id}-result.json`, JSON.stringify({
+      task_id: task.id, status: "completed", findings: parseFindings(result),
+      timestamp: getUtc8ISOString()
+    }))
+    close_agent({ id: agent })
+    task.status = 'completed'
+    task.findings = parseFindings(result)
+  }
+
+  // 4. Build prev_context for csv-wave tasks
+  const pendingCsvTasks = csvTasks.filter(t => t.status === 'pending')
+  for (const task of pendingCsvTasks) {
+    task.prev_context = buildPrevContext(task, tasks)
+  }
+
+  if (pendingCsvTasks.length > 0) {
+    // 5. Write wave CSV
+    Write(`${sessionFolder}/wave-${wave}.csv`, toCsv(pendingCsvTasks))
+
+    // 6. Determine instruction -- read from instructions/agent-instruction.md
+    Read('instructions/agent-instruction.md')
+
+    // 7. Execute wave via spawn_agents_on_csv
+    spawn_agents_on_csv({
+      csv_path: `${sessionFolder}/wave-${wave}.csv`,
+      id_column: "id",
+      instruction: archOptInstruction,  // from instructions/agent-instruction.md
+      max_concurrency: maxConcurrency,
+      max_runtime_seconds: 900,
+      output_csv_path: `${sessionFolder}/wave-${wave}-results.csv`,
+      output_schema: {
+        type: "object",
+        properties: {
+          id: { type: "string" },
+          status: { type: "string", enum: ["completed", "failed"] },
+          findings: { type: "string" },
+          verdict: { type: "string" },
+          artifacts_produced: { type: "string" },
+          error: { type: "string" }
+        }
+      }
+    })
+
+    // 8. Merge results into master CSV
+    const results = parseCsv(Read(`${sessionFolder}/wave-${wave}-results.csv`))
+    for (const r of results) {
+      const t = tasks.find(t => t.id === r.id)
+      if (t) Object.assign(t, r)
+    }
+  }
+
+  // 9. Update master CSV
+  Write(`${sessionFolder}/tasks.csv`, toCsv(tasks))
+
+  // 10. Cleanup temp files
+  Bash(`rm -f ${sessionFolder}/wave-${wave}.csv ${sessionFolder}/wave-${wave}-results.csv`)
+
+  // 11. Post-wave: check for review-fix cycle
+  const validateTask = tasks.find(t => t.id.startsWith('VALIDATE') && t.wave === wave)
+  const reviewTask = tasks.find(t => t.id.startsWith('REVIEW') && t.wave === wave)
+
+  if ((validateTask?.verdict === 'FAIL' || reviewTask?.verdict === 'REVISE' || reviewTask?.verdict === 'REJECT')) {
+    const fixCycleCount = tasks.filter(t => t.id.startsWith('FIX')).length
+    if (fixCycleCount < 3) {
+      // Create FIX task, add to tasks, re-run refactor -> validate+review cycle
+      const fixId = `FIX-${String(fixCycleCount + 1).padStart(3, '0')}`
+      const feedback = [validateTask?.error, reviewTask?.findings].filter(Boolean).join('\n')
+      tasks.push({
+        id: fixId, title: `Fix issues from review/validation cycle ${fixCycleCount + 1}`,
+        description: `Fix issues found:\n${feedback}`,
+        role: 'refactorer', issue_type: '', priority: 'P0', target_files: '',
+        deps: '', context_from: '', exec_mode: 'interactive',
+        wave: wave + 1, status: 'pending', findings: '', verdict: '',
+        artifacts_produced: '', error: ''
+      })
+    }
+  }
+
+  // 12. Display wave summary
+  const completed = waveTasks.filter(t => t.status === 'completed').length
+  const failed = waveTasks.filter(t => t.status === 'failed').length
+  const skipped = waveTasks.filter(t => t.status === 'skipped').length
+  console.log(`Wave ${wave} Complete: ${completed} completed, ${failed} failed, ${skipped} skipped`)
+}
+```
+
+**Success Criteria**:
+- All waves executed in order
+- Both csv-wave and interactive tasks handled per wave
+- Each wave's results merged into master CSV before next wave starts
+- Dependent tasks skipped when predecessor failed
+- Review-fix cycle handled with max 3 iterations
+- discoveries.ndjson accumulated across all waves and mechanisms
+
+---
+
+### Phase 3: Post-Wave Interactive (Completion Action)
+
+**Objective**: Pipeline completion report with architecture improvement metrics and interactive completion choice.
+
+```javascript
+// 1. Generate pipeline summary
+const tasks = parseCsv(Read(`${sessionFolder}/tasks.csv`))
+const completed = tasks.filter(t => t.status === 'completed')
+const failed = tasks.filter(t => t.status === 'failed')
+
+// 2. Load improvement metrics from validation results
+let improvements = ''
+try {
+  const validation = JSON.parse(Read(`${sessionFolder}/artifacts/validation-results.json`))
+  improvements = `Architecture Improvements:\n${validation.dimensions.map(d =>
+    `  ${d.name}: ${d.baseline} -> ${d.current} (${d.improvement})`).join('\n')}`
+} catch {}
+
+console.log(`
+============================================
+ARCHITECTURE OPTIMIZATION COMPLETE
+
+Deliverables:
+  - Architecture Baseline: artifacts/architecture-baseline.json
+  - Architecture Report: artifacts/architecture-report.md
+  - Refactoring Plan: artifacts/refactoring-plan.md
+  - Validation Results: artifacts/validation-results.json
+  - Review Report: artifacts/review-report.md
+
+${improvements}
+
+Pipeline: ${completed.length}/${tasks.length} tasks
+Session: ${sessionFolder}
+============================================
+`)
+
+// 3. Completion action
+if (!AUTO_YES) {
+  AskUserQuestion({
+    questions: [{
+      question: "Architecture optimization complete. What would you like to do?",
+      header: "Completion",
+      multiSelect: false,
+      options: [
+        { label: "Archive & Clean (Recommended)", description: "Archive session, output final summary" },
+        { label: "Keep Active", description: "Keep session for follow-up work" },
+        { label: "Retry Failed", description: "Re-run failed tasks" }
+      ]
+    }]
+  })
+}
+```
+
+**Success Criteria**:
+- Post-wave interactive processing complete
+- User informed of results and improvement metrics
+
+---
+
+### Phase 4: Results Aggregation
+
+**Objective**: Generate final results and human-readable report.
+
+```javascript
+// 1. Export results.csv
+Bash(`cp ${sessionFolder}/tasks.csv ${sessionFolder}/results.csv`)
+
+// 2. Generate context.md
+const tasks = parseCsv(Read(`${sessionFolder}/tasks.csv`))
+let contextMd = `# Architecture Optimization Report\n\n`
+contextMd += `**Session**: ${sessionId}\n`
+contextMd += `**Date**: ${getUtc8ISOString().substring(0, 10)}\n\n`
+
+contextMd += `## Summary\n`
+contextMd += `| Status | Count |\n|--------|-------|\n`
+contextMd += `| Completed | ${tasks.filter(t => t.status === 'completed').length} |\n`
+contextMd += `| Failed | ${tasks.filter(t => t.status === 'failed').length} |\n`
+contextMd += `| Skipped | ${tasks.filter(t => t.status === 'skipped').length} |\n\n`
+
+contextMd += `## Deliverables\n\n`
+contextMd += `| Artifact | Path |\n|----------|------|\n`
+contextMd += `| Architecture Baseline | artifacts/architecture-baseline.json |\n`
+contextMd += `| Architecture Report | artifacts/architecture-report.md |\n`
+contextMd += `| Refactoring Plan | artifacts/refactoring-plan.md |\n`
+contextMd += `| Validation Results | artifacts/validation-results.json |\n`
+contextMd += `| Review Report | artifacts/review-report.md |\n\n`
+
+const maxWave = Math.max(...tasks.map(t => t.wave))
+contextMd += `## Wave Execution\n\n`
+for (let w = 1; w <= maxWave; w++) {
+  const waveTasks = tasks.filter(t => t.wave === w)
+  contextMd += `### Wave ${w}\n\n`
+  for (const t of waveTasks) {
+    const icon = t.status === 'completed' ? '[DONE]' : t.status === 'failed' ? '[FAIL]' : '[SKIP]'
+    contextMd += `${icon} **${t.title}** [${t.role}] ${t.verdict ? `(${t.verdict})` : ''} ${t.findings || ''}\n\n`
+  }
+}
+
+Write(`${sessionFolder}/context.md`, contextMd)
+
+console.log(`Results exported to: ${sessionFolder}/results.csv`)
+console.log(`Report generated at: ${sessionFolder}/context.md`)
+```
+
+**Success Criteria**:
+- results.csv exported (all tasks, both modes)
+- context.md generated with deliverables list
+- Summary displayed to user
+
+---
+
+## Shared Discovery Board Protocol
+
+All agents (csv-wave and interactive) share a single `discoveries.ndjson` file for cross-task knowledge exchange.
+
+**Format**: One JSON object per line (NDJSON):
+
+```jsonl
+{"ts":"2026-03-08T10:00:00Z","worker":"ANALYZE-001","type":"cycle_found","data":{"modules":["auth","user"],"depth":2,"description":"Circular dependency between auth and user modules"}}
+{"ts":"2026-03-08T10:05:00Z","worker":"REFACTOR-001","type":"file_modified","data":{"file":"src/auth/index.ts","change":"Extracted interface to break cycle","lines_added":15}}
+```
+
+**Discovery Types**:
+
+| Type | Data Schema | Description |
+|------|-------------|-------------|
+| `cycle_found` | `{modules, depth, description}` | Circular dependency detected |
+| `god_class_found` | `{file, loc, methods, description}` | God Class/Module identified |
+| `coupling_issue` | `{module, fan_in, fan_out, description}` | High coupling detected |
+| `dead_code_found` | `{file, type, description}` | Dead code or dead export found |
+| `file_modified` | `{file, change, lines_added}` | File change recorded |
+| `pattern_found` | `{pattern_name, location, description}` | Code pattern identified |
+| `metric_measured` | `{metric, value, unit, module}` | Architecture metric measured |
+| `artifact_produced` | `{name, path, producer, type}` | Deliverable created |
+
+**Protocol**:
+1. Agents MUST read discoveries.ndjson at start of execution
+2. Agents MUST append relevant discoveries during execution
+3. Agents MUST NOT modify or delete existing entries
+4. Deduplication by `{type, data.file}` or `{type, data.modules}` key
+
+---
+
+## Error Handling
+
+| Error | Resolution |
+|-------|------------|
+| Circular dependency in tasks | Detect in wave computation, abort with error message |
+| CSV agent timeout | Mark as failed in results, continue with wave |
+| CSV agent failed | Mark as failed, skip dependent tasks in later waves |
+| Interactive agent timeout | Urge convergence via send_input, then close if still timed out |
+| Interactive agent failed | Mark as failed, skip dependents |
+| All agents in wave failed | Log error, offer retry or abort |
+| CSV parse error | Validate CSV format before execution, show line number |
+| discoveries.ndjson corrupt | Ignore malformed lines, continue with valid entries |
+| Review-fix cycle exceeds 3 iterations | Escalate to user with summary of remaining issues |
+| Validation fails on build | Create FIX task with compilation error details |
+| Architecture baseline unavailable | Fall back to static analysis estimates |
+| Continue mode: no session found | List available sessions, prompt user to select |
+
+---
+
+## Core Rules
+
+1. **Start Immediately**: First action is session initialization, then Phase 0/1
+2. **Wave Order is Sacred**: Never execute wave N before wave N-1 completes and results are merged
+3. **CSV is Source of Truth**: Master tasks.csv holds all state (both csv-wave and interactive)
+4. **CSV First**: Default to csv-wave for tasks; only use interactive when interaction pattern requires it
+5. **Context Propagation**: prev_context built from master CSV, not from memory
+6. **Discovery Board is Append-Only**: Never clear, modify, or recreate discoveries.ndjson -- both mechanisms share it
+7. **Skip on Failure**: If a dependency failed, skip the dependent task (regardless of mechanism)
+8. **Max 3 Fix Cycles**: Review-fix cycle capped at 3 iterations; escalate to user after
+9. **Cleanup Temp Files**: Remove wave-{N}.csv after results are merged
+10. **DO NOT STOP**: Continuous execution until all waves complete or all remaining tasks are skipped
+
+
+---
+
+## Coordinator Role Constraints (Main Agent)
+
+**CRITICAL**: The coordinator (main agent executing this skill) is responsible for **orchestration only**, NOT implementation.
+
+15. **Coordinator Does NOT Execute Code**: The main agent MUST NOT write, modify, or implement any code directly. All implementation work is delegated to spawned team agents. The coordinator only:
+    - Spawns agents with task assignments
+    - Waits for agent callbacks
+    - Merges results and coordinates workflow
+    - Manages workflow transitions between phases
+
+16. **Patient Waiting is Mandatory**: Agent execution takes significant time (typically 10-30 minutes per phase, sometimes longer). The coordinator MUST:
+    - Wait patiently for `wait()` calls to complete
+    - NOT skip workflow steps due to perceived delays
+    - NOT assume agents have failed just because they're taking time
+    - Trust the timeout mechanisms defined in the skill
+
+17. **Use send_input for Clarification**: When agents need guidance or appear stuck, the coordinator MUST:
+    - Use `send_input()` to ask questions or provide clarification
+    - NOT skip the agent or move to next phase prematurely
+    - Give agents opportunity to respond before escalating
+    - Example: `send_input({ id: agent_id, message: "Please provide status update or clarify blockers" })`
+
+18. **No Workflow Shortcuts**: The coordinator MUST NOT:
+    - Skip phases or stages defined in the workflow
+    - Bypass required approval or review steps
+    - Execute dependent tasks before prerequisites complete
+    - Assume task completion without explicit agent callback
+    - Make up or fabricate agent results
+
+19. **Respect Long-Running Processes**: This is a complex multi-agent workflow that requires patience:
+    - Total execution time may range from 30-90 minutes or longer
+    - Each phase may take 10-30 minutes depending on complexity
+    - The coordinator must remain active and attentive throughout the entire process
+    - Do not terminate or skip steps due to time concerns

.codex/skills/team-arch-opt/agents/completion-handler.md

@@ -0,0 +1,138 @@
+# Completion Handler Agent
+
+Handle pipeline completion action for architecture optimization: present results summary, offer Archive/Keep/Export options, execute chosen action.
+
+## Identity
+
+- **Type**: `interactive`
+- **Responsibility**: Pipeline completion and session lifecycle management
+
+## Boundaries
+
+### MUST
+
+- Load role definition via MANDATORY FIRST STEPS pattern
+- Present complete pipeline summary with improvement metrics
+- Offer completion action choices
+- Execute chosen action (archive, keep, export)
+- Produce structured output
+
+### MUST NOT
+
+- Skip presenting results summary
+- Execute destructive actions without confirmation
+- Modify source code
+
+---
+
+## Toolbox
+
+### Available Tools
+
+| Tool | Type | Purpose |
+|------|------|---------|
+| `Read` | builtin | Load result artifacts |
+| `Write` | builtin | Write export files |
+| `Bash` | builtin | Archive/cleanup operations |
+| `AskUserQuestion` | builtin | Present completion choices |
+
+---
+
+## Execution
+
+### Phase 1: Results Collection
+
+**Objective**: Gather all pipeline results for summary.
+
+**Input**:
+
+| Source | Required | Description |
+|--------|----------|-------------|
+| tasks.csv | Yes | Master task state |
+| Architecture baseline | Yes | Pre-refactoring metrics |
+| Validation results | Yes | Post-refactoring metrics |
+| Review report | Yes | Code review findings |
+
+**Steps**:
+
+1. Read tasks.csv -- count completed/failed/skipped
+2. Read architecture-baseline.json -- extract before metrics
+3. Read validation-results.json -- extract after metrics, compute improvements
+4. Read review-report.md -- extract final verdict
+
+**Output**: Compiled results summary
+
+---
+
+### Phase 2: Present and Choose
+
+**Objective**: Display results and get user's completion choice.
+
+**Steps**:
+
+1. Display pipeline summary with improvement metrics
+2. Present completion action:
+
+```javascript
+AskUserQuestion({
+  questions: [{
+    question: "Architecture optimization complete. What would you like to do?",
+    header: "Completion",
+    multiSelect: false,
+    options: [
+      { label: "Archive & Clean (Recommended)", description: "Archive session, output final summary" },
+      { label: "Keep Active", description: "Keep session for follow-up work or inspection" },
+      { label: "Export Results", description: "Export deliverables to a specified location" }
+    ]
+  }]
+})
+```
+
+**Output**: User's choice
+
+---
+
+### Phase 3: Execute Action
+
+**Objective**: Execute the chosen completion action.
+
+| Choice | Action |
+|--------|--------|
+| Archive & Clean | Copy results.csv and context.md to archive, mark session completed |
+| Keep Active | Mark session as paused, leave all artifacts in place |
+| Export Results | Copy key deliverables to user-specified location |
+
+---
+
+## Structured Output Template
+
+```
+## Pipeline Summary
+- Tasks: X completed, Y failed, Z skipped
+- Duration: estimated from timestamps
+
+## Architecture Improvements
+- Metric 1: before -> after (improvement %)
+- Metric 2: before -> after (improvement %)
+
+## Deliverables
+- Architecture Report: path
+- Refactoring Plan: path
+- Validation Results: path
+- Review Report: path
+
+## Action Taken
+- Choice: Archive & Clean / Keep Active / Export Results
+- Status: completed
+```
+
+---
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Result artifacts missing | Report partial summary with available data |
+| Archive operation fails | Default to Keep Active |
+| Export path invalid | Ask user for valid path |
+| Timeout approaching | Default to Keep Active |

.codex/skills/team-arch-opt/agents/fix-cycle-handler.md

@@ -0,0 +1,146 @@
+# Fix Cycle Handler Agent
+
+Manage the review-fix iteration cycle for architecture refactoring. Reads validation/review feedback, applies targeted fixes, re-validates, up to 3 iterations.
+
+## Identity
+
+- **Type**: `interactive`
+- **Responsibility**: Iterative fix-verify cycle for refactoring issues
+
+## Boundaries
+
+### MUST
+
+- Load role definition via MANDATORY FIRST STEPS pattern
+- Read validation results and review report to understand failures
+- Apply targeted fixes addressing specific feedback items
+- Re-validate after each fix attempt
+- Track iteration count (max 3)
+- Produce structured output with fix summary
+
+### MUST NOT
+
+- Skip reading feedback before attempting fixes
+- Apply broad changes unrelated to feedback
+- Exceed 3 fix iterations
+- Modify code outside the scope of reported issues
+
+---
+
+## Toolbox
+
+### Available Tools
+
+| Tool | Type | Purpose |
+|------|------|---------|
+| `Read` | builtin | Load feedback artifacts and source files |
+| `Edit` | builtin | Apply targeted code fixes |
+| `Write` | builtin | Write updated artifacts |
+| `Bash` | builtin | Run build/test validation |
+| `Grep` | builtin | Search for patterns |
+| `Glob` | builtin | Find files |
+
+---
+
+## Execution
+
+### Phase 1: Feedback Loading
+
+**Objective**: Load and parse validation/review feedback.
+
+**Input**:
+
+| Source | Required | Description |
+|--------|----------|-------------|
+| Validation results | Yes (if validation failed) | From artifacts/validation-results.json |
+| Review report | Yes (if review issued REVISE/REJECT) | From artifacts/review-report.md |
+| Refactoring plan | Yes | Original plan for reference |
+| Discoveries | No | Shared findings |
+
+**Steps**:
+
+1. Read validation-results.json -- identify failed dimensions (build, test, metrics, API)
+2. Read review-report.md -- identify Critical/High findings with file:line references
+3. Categorize issues by type and priority
+
+**Output**: Prioritized list of issues to fix
+
+---
+
+### Phase 2: Fix Implementation (Iterative)
+
+**Objective**: Apply fixes and re-validate, up to 3 rounds.
+
+**Steps**:
+
+For each iteration (1..3):
+
+1. **Apply fixes**:
+   - Address highest-severity issues first
+   - Make minimal, targeted changes at reported file:line locations
+   - Update imports if structural changes are needed
+   - Preserve existing behavior
+
+2. **Self-validate**:
+   - Run build check (no new compilation errors)
+   - Run test suite (no new test failures)
+   - Verify fix addresses the specific concern raised
+
+3. **Check convergence**:
+
+| Validation Result | Action |
+|-------------------|--------|
+| All checks pass | Exit loop, report success |
+| Some checks still fail, iteration < 3 | Continue to next iteration |
+| Still failing at iteration 3 | Report remaining issues for escalation |
+
+**Output**: Fix results per iteration
+
+---
+
+### Phase 3: Result Reporting
+
+**Objective**: Produce final fix cycle summary.
+
+**Steps**:
+
+1. Update validation-results.json with post-fix metrics
+2. Append fix discoveries to discoveries.ndjson
+3. Report final status
+
+---
+
+## Structured Output Template
+
+```
+## Summary
+- Fix cycle completed: N iterations, M issues resolved, K remaining
+
+## Iterations
+### Iteration 1
+- Fixed: [list of fixes applied with file:line]
+- Validation: [pass/fail per dimension]
+
+### Iteration 2 (if needed)
+- Fixed: [list of fixes]
+- Validation: [pass/fail]
+
+## Final Status
+- verdict: PASS | PARTIAL | ESCALATE
+- Remaining issues (if any): [list]
+
+## Artifacts Updated
+- artifacts/validation-results.json (updated metrics)
+```
+
+---
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Fix introduces new errors | Revert fix, try alternative approach |
+| Cannot reproduce reported issue | Log as resolved-by-environment, continue |
+| Fix scope exceeds current files | Report scope expansion needed, escalate |
+| Timeout approaching | Output partial results with iteration count |
+| 3 iterations exhausted | Report remaining issues for user escalation |

.codex/skills/team-arch-opt/agents/plan-reviewer.md

@@ -0,0 +1,150 @@
+# Plan Reviewer Agent
+
+Review architecture report or refactoring plan at user checkpoints, providing interactive approval or revision requests.
+
+## Identity
+
+- **Type**: `interactive`
+- **Responsibility**: Review and approve/revise plans before execution proceeds
+
+## Boundaries
+
+### MUST
+
+- Load role definition via MANDATORY FIRST STEPS pattern
+- Read the architecture report or refactoring plan being reviewed
+- Produce structured output with clear APPROVE/REVISE verdict
+- Include specific file:line references in findings
+
+### MUST NOT
+
+- Skip the MANDATORY FIRST STEPS role loading
+- Modify source code directly
+- Produce unstructured output
+- Approve without actually reading the plan
+
+---
+
+## Toolbox
+
+### Available Tools
+
+| Tool | Type | Purpose |
+|------|------|---------|
+| `Read` | builtin | Load plan artifacts and project files |
+| `Grep` | builtin | Search for patterns in codebase |
+| `Glob` | builtin | Find files by pattern |
+| `Bash` | builtin | Run build/test commands |
+
+### Tool Usage Patterns
+
+**Read Pattern**: Load context files before review
+```
+Read("{session_folder}/artifacts/architecture-report.md")
+Read("{session_folder}/artifacts/refactoring-plan.md")
+Read("{session_folder}/discoveries.ndjson")
+```
+
+---
+
+## Execution
+
+### Phase 1: Context Loading
+
+**Objective**: Load the plan or report to review.
+
+**Input**:
+
+| Source | Required | Description |
+|--------|----------|-------------|
+| Architecture report | Yes (if reviewing analysis) | Ranked issue list from analyzer |
+| Refactoring plan | Yes (if reviewing design) | Prioritized plan from designer |
+| Discoveries | No | Shared findings from prior stages |
+
+**Steps**:
+
+1. Read the artifact being reviewed from session artifacts folder
+2. Read discoveries.ndjson for additional context
+3. Identify which checkpoint this review corresponds to (CP-1 for analysis, CP-2 for design)
+
+**Output**: Loaded plan context for review
+
+---
+
+### Phase 2: Plan Review
+
+**Objective**: Evaluate plan quality, completeness, and feasibility.
+
+**Steps**:
+
+1. **For architecture report review (CP-1)**:
+   - Verify all issue categories are covered (cycles, coupling, cohesion, God Classes, dead code, API bloat)
+   - Check that severity rankings are justified with evidence
+   - Validate baseline metrics are quantified and reproducible
+   - Check scope coverage matches original requirement
+
+2. **For refactoring plan review (CP-2)**:
+   - Verify each refactoring has unique REFACTOR-ID and self-contained detail
+   - Check priority assignments follow impact/effort matrix
+   - Validate target files are non-overlapping between refactorings
+   - Verify success criteria are measurable
+   - Check that implementation guidance is actionable
+   - Assess risk levels and mitigation strategies
+
+3. **Issue classification**:
+
+| Finding Severity | Condition | Impact |
+|------------------|-----------|--------|
+| Critical | Missing key analysis area or infeasible plan | REVISE required |
+| High | Unclear criteria or overlapping targets | REVISE recommended |
+| Medium | Minor gaps in coverage or detail | Note for improvement |
+| Low | Style or formatting issues | Informational |
+
+**Output**: Review findings with severity classifications
+
+---
+
+### Phase 3: Verdict
+
+**Objective**: Issue APPROVE or REVISE verdict.
+
+| Verdict | Condition | Action |
+|---------|-----------|--------|
+| APPROVE | No Critical or High findings | Plan is ready for next stage |
+| REVISE | Has Critical or High findings | Return specific feedback for revision |
+
+**Output**: Verdict with detailed feedback
+
+---
+
+## Structured Output Template
+
+```
+## Summary
+- One-sentence verdict: APPROVE or REVISE with rationale
+
+## Findings
+- Finding 1: [severity] description with artifact reference
+- Finding 2: [severity] description with specific section reference
+
+## Verdict
+- APPROVE: Plan is ready for execution
+  OR
+- REVISE: Specific items requiring revision
+  1. Issue description + suggested fix
+  2. Issue description + suggested fix
+
+## Recommendations
+- Optional improvement suggestions (non-blocking)
+```
+
+---
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Artifact file not found | Report in findings, request re-generation |
+| Plan structure invalid | Report as Critical finding, REVISE verdict |
+| Scope mismatch | Report in findings, note for coordinator |
+| Timeout approaching | Output current findings with "PARTIAL" status |

.codex/skills/team-arch-opt/instructions/agent-instruction.md

@@ -0,0 +1,114 @@
+## TASK ASSIGNMENT
+
+### MANDATORY FIRST STEPS
+1. Read shared discoveries: {session_folder}/discoveries.ndjson (if exists, skip if not)
+2. Read project context: .workflow/project-tech.json (if exists)
+3. Read task schema: ~  or <project>/.codex/skills/team-arch-opt/schemas/tasks-schema.md
+
+---
+
+## Your Task
+
+**Task ID**: {id}
+**Title**: {title}
+**Description**: {description}
+**Role**: {role}
+**Issue Type**: {issue_type}
+**Priority**: {priority}
+**Target Files**: {target_files}
+
+### Previous Tasks' Findings (Context)
+{prev_context}
+
+---
+
+## Execution Protocol
+
+1. **Read discoveries**: Load {session_folder}/discoveries.ndjson for shared exploration findings
+2. **Use context**: Apply previous tasks' findings from prev_context above
+3. **Execute by role**:
+
+   **If role = analyzer**:
+   - Scan codebase for architecture issues within target scope
+   - Build import/require graph, detect circular dependencies
+   - Identify God Classes (>500 LOC, >10 public methods)
+   - Calculate coupling (fan-in/fan-out) and cohesion metrics
+   - Detect dead code, dead exports, layering violations
+   - Collect quantified baseline metrics
+   - Rank top 3-7 issues by severity (Critical/High/Medium)
+   - Write `{session_folder}/artifacts/architecture-baseline.json` (metrics)
+   - Write `{session_folder}/artifacts/architecture-report.md` (ranked issues)
+
+   **If role = designer**:
+   - Read architecture report and baseline from {session_folder}/artifacts/
+   - For each issue, select refactoring strategy by type:
+     - CYCLE: interface extraction, dependency inversion, mediator
+     - GOD_CLASS: SRP decomposition, extract class/module
+     - COUPLING: introduce interface/abstraction, DI, events
+     - DUPLICATION: extract shared utility/base class
+     - LAYER_VIOLATION: move to correct layer, add facade
+     - DEAD_CODE: safe removal with reference verification
+     - API_BLOAT: privatize internals, barrel file cleanup
+   - Prioritize by impact/effort: P0 (high impact+low effort) to P3 (low impact or high effort)
+   - Assign unique REFACTOR-IDs (REFACTOR-001, 002, ...) with non-overlapping file targets
+   - Write `{session_folder}/artifacts/refactoring-plan.md`
+
+   **If role = refactorer**:
+   - Read refactoring plan from {session_folder}/artifacts/refactoring-plan.md
+   - Apply refactorings in priority order (P0 first)
+   - Preserve existing behavior -- refactoring must not change functionality
+   - Update ALL import references when moving/renaming modules
+   - Update ALL test files referencing moved/renamed symbols
+   - Verify no dangling imports after module moves
+
+   **If role = validator**:
+   - Read baseline from {session_folder}/artifacts/architecture-baseline.json
+   - Read plan from {session_folder}/artifacts/refactoring-plan.md
+   - Build validation: compile/type-check, zero new errors
+   - Test validation: run test suite, no new failures
+   - Metric validation: coupling improved or neutral, no new cycles
+   - API validation: public signatures preserved, no dangling references
+   - Write `{session_folder}/artifacts/validation-results.json`
+   - Set verdict: PASS / WARN / FAIL
+
+   **If role = reviewer**:
+   - Read plan from {session_folder}/artifacts/refactoring-plan.md
+   - Review changed files across 5 dimensions:
+     - Correctness: no behavior changes, all references updated
+     - Pattern consistency: follows existing conventions
+     - Completeness: imports, tests, configs all updated
+     - Migration safety: no dangling refs, backward compatible
+     - Best practices: SOLID, appropriate abstraction
+   - Write `{session_folder}/artifacts/review-report.md`
+   - Set verdict: APPROVE / REVISE / REJECT
+
+4. **Share discoveries**: Append exploration findings to shared board:
+   ```bash
+   echo '{"ts":"<ISO8601>","worker":"{id}","type":"<type>","data":{...}}' >> {session_folder}/discoveries.ndjson
+   ```
+5. **Report result**: Return JSON via report_agent_job_result
+
+### Discovery Types to Share
+- `cycle_found`: `{modules, depth, description}` -- Circular dependency detected
+- `god_class_found`: `{file, loc, methods, description}` -- God Class identified
+- `coupling_issue`: `{module, fan_in, fan_out, description}` -- High coupling
+- `dead_code_found`: `{file, type, description}` -- Dead code found
+- `layer_violation`: `{from, to, description}` -- Layering violation
+- `file_modified`: `{file, change, lines_added}` -- File change recorded
+- `pattern_found`: `{pattern_name, location, description}` -- Pattern identified
+- `metric_measured`: `{metric, value, unit, module}` -- Metric measured
+- `artifact_produced`: `{name, path, producer, type}` -- Deliverable created
+
+---
+
+## Output (report_agent_job_result)
+
+Return JSON:
+{
+  "id": "{id}",
+  "status": "completed" | "failed",
+  "findings": "Key discoveries and implementation notes (max 500 chars)",
+  "verdict": "PASS|WARN|FAIL|APPROVE|REVISE|REJECT or empty",
+  "artifacts_produced": "semicolon-separated artifact paths",
+  "error": ""
+}

.codex/skills/team-arch-opt/schemas/tasks-schema.md

@@ -0,0 +1,174 @@
+# Team Architecture Optimization -- CSV Schema
+
+## Master CSV: tasks.csv
+
+### Column Definitions
+
+#### Input Columns (Set by Decomposer)
+
+| Column | Type | Required | Description | Example |
+|--------|------|----------|-------------|---------|
+| `id` | string | Yes | Unique task identifier (PREFIX-NNN) | `"ANALYZE-001"` |
+| `title` | string | Yes | Short task title | `"Analyze architecture"` |
+| `description` | string | Yes | Detailed task description (self-contained) with goal, inputs, outputs, success criteria | `"Analyze codebase architecture..."` |
+| `role` | enum | Yes | Worker role: `analyzer`, `designer`, `refactorer`, `validator`, `reviewer` | `"analyzer"` |
+| `issue_type` | string | No | Architecture issue category: CYCLE, COUPLING, COHESION, GOD_CLASS, DUPLICATION, LAYER_VIOLATION, DEAD_CODE, API_BLOAT | `"CYCLE"` |
+| `priority` | enum | No | P0 (Critical), P1 (High), P2 (Medium), P3 (Low) | `"P0"` |
+| `target_files` | string | No | Semicolon-separated file paths to focus on | `"src/auth/index.ts;src/user/index.ts"` |
+| `deps` | string | No | Semicolon-separated dependency task IDs | `"ANALYZE-001"` |
+| `context_from` | string | No | Semicolon-separated task IDs for context | `"ANALYZE-001"` |
+| `exec_mode` | enum | Yes | Execution mechanism: `csv-wave` or `interactive` | `"csv-wave"` |
+
+#### Computed Columns (Set by Wave Engine)
+
+| Column | Type | Description | Example |
+|--------|------|-------------|---------|
+| `wave` | integer | Wave number (1-based, from topological sort) | `2` |
+| `prev_context` | string | Aggregated findings from context_from tasks (per-wave CSV only) | `"[ANALYZE-001] Found 5 architecture issues..."` |
+
+#### Output Columns (Set by Agent)
+
+| Column | Type | Description | Example |
+|--------|------|-------------|---------|
+| `status` | enum | `pending` -> `completed` / `failed` / `skipped` | `"completed"` |
+| `findings` | string | Key discoveries (max 500 chars) | `"Found 3 circular deps, 2 God Classes..."` |
+| `verdict` | string | Validation/review verdict: PASS, WARN, FAIL, APPROVE, REVISE, REJECT | `"PASS"` |
+| `artifacts_produced` | string | Semicolon-separated paths of produced artifacts | `"artifacts/architecture-report.md"` |
+| `error` | string | Error message if failed | `""` |
+
+---
+
+### exec_mode Values
+
+| Value | Mechanism | Description |
+|-------|-----------|-------------|
+| `csv-wave` | `spawn_agents_on_csv` | One-shot batch execution within wave |
+| `interactive` | `spawn_agent`/`wait`/`send_input`/`close_agent` | Multi-round individual execution |
+
+Interactive tasks appear in master CSV for dependency tracking but are NOT included in wave-{N}.csv files.
+
+---
+
+### Role Prefix Mapping
+
+| Role | Prefix | Stage | Responsibility |
+|------|--------|-------|----------------|
+| analyzer | ANALYZE | 1 | Architecture analysis, baseline metrics, issue identification |
+| designer | DESIGN | 2 | Refactoring plan design, strategy selection, prioritization |
+| refactorer | REFACTOR / FIX | 3 | Code implementation, refactoring application, targeted fixes |
+| validator | VALIDATE | 4 | Build checks, test suite, metric validation, API compatibility |
+| reviewer | REVIEW | 4 | Code review for correctness, patterns, completeness, safety |
+
+---
+
+### Example Data
+
+```csv
+id,title,description,role,issue_type,priority,target_files,deps,context_from,exec_mode,wave,status,findings,verdict,artifacts_produced,error
+"ANALYZE-001","Analyze architecture","PURPOSE: Analyze codebase architecture to identify structural issues\nTASK:\n- Build import graph, detect circular deps\n- Identify God Classes (>500 LOC, >10 methods)\n- Calculate coupling/cohesion metrics\n- Detect dead code and dead exports\nINPUT: Codebase under target scope\nOUTPUT: artifacts/architecture-baseline.json + artifacts/architecture-report.md\nSUCCESS: Ranked issue list with severity, baseline metrics collected\nSESSION: .workflow/.csv-wave/tao-example-20260308","analyzer","","","","","","csv-wave","1","pending","","","",""
+"DESIGN-001","Design refactoring plan","PURPOSE: Design prioritized refactoring plan from architecture report\nTASK:\n- For each issue, select refactoring strategy\n- Prioritize by impact/effort ratio (P0-P3)\n- Define measurable success criteria per refactoring\n- Assign unique REFACTOR-IDs with non-overlapping file targets\nINPUT: artifacts/architecture-report.md + artifacts/architecture-baseline.json\nOUTPUT: artifacts/refactoring-plan.md\nSUCCESS: Prioritized plan with self-contained REFACTOR blocks\nSESSION: .workflow/.csv-wave/tao-example-20260308","designer","","","","ANALYZE-001","ANALYZE-001","csv-wave","2","pending","","","",""
+"REFACTOR-001","Implement refactorings","PURPOSE: Implement architecture refactoring changes per plan\nTASK:\n- Apply refactorings in priority order (P0 first)\n- Update all import references when moving/renaming\n- Update all test files referencing moved symbols\n- Preserve existing behavior\nINPUT: artifacts/refactoring-plan.md\nOUTPUT: Modified source files\nSUCCESS: All planned structural changes applied, no dangling imports\nSESSION: .workflow/.csv-wave/tao-example-20260308","refactorer","","","","DESIGN-001","DESIGN-001","csv-wave","3","pending","","","",""
+"VALIDATE-001","Validate refactoring","PURPOSE: Validate refactoring improves architecture without breaking functionality\nTASK:\n- Build check: zero new compilation errors\n- Test suite: all previously passing tests still pass\n- Metrics: coupling improved or neutral, no new cycles\n- API: public signatures preserved\nINPUT: artifacts/architecture-baseline.json + artifacts/refactoring-plan.md\nOUTPUT: artifacts/validation-results.json\nSUCCESS: All dimensions PASS\nSESSION: .workflow/.csv-wave/tao-example-20260308","validator","","","","REFACTOR-001","REFACTOR-001","csv-wave","4","pending","","","",""
+"REVIEW-001","Review refactoring code","PURPOSE: Review refactoring changes for correctness and quality\nTASK:\n- Correctness: no behavior changes, all references updated\n- Pattern consistency: follows existing conventions\n- Completeness: imports, tests, configs all updated\n- Migration safety: no dangling refs, backward compatible\n- Best practices: SOLID principles, appropriate abstraction\nINPUT: artifacts/refactoring-plan.md + changed files\nOUTPUT: artifacts/review-report.md\nSUCCESS: APPROVE verdict (no Critical/High findings)\nSESSION: .workflow/.csv-wave/tao-example-20260308","reviewer","","","","REFACTOR-001","REFACTOR-001","csv-wave","4","pending","","","",""
+```
+
+---
+
+### Column Lifecycle
+
+```
+Decomposer (Phase 1)     Wave Engine (Phase 2)    Agent (Execution)
+---------------------    --------------------     -----------------
+id          ---------->  id          ---------->  id
+title       ---------->  title       ---------->  (reads)
+description ---------->  description ---------->  (reads)
+role        ---------->  role        ---------->  (reads)
+issue_type  ---------->  issue_type  ---------->  (reads)
+priority    ---------->  priority    ---------->  (reads)
+target_files---------->  target_files---------->  (reads)
+deps        ---------->  deps        ---------->  (reads)
+context_from---------->  context_from---------->  (reads)
+exec_mode   ---------->  exec_mode   ---------->  (reads)
+                         wave         ---------->  (reads)
+                         prev_context ---------->  (reads)
+                                                   status
+                                                   findings
+                                                   verdict
+                                                   artifacts_produced
+                                                   error
+```
+
+---
+
+## Output Schema (JSON)
+
+Agent output via `report_agent_job_result` (csv-wave tasks):
+
+```json
+{
+  "id": "ANALYZE-001",
+  "status": "completed",
+  "findings": "Found 5 architecture issues: 2 circular deps (auth<->user, service<->repo), 1 God Class (UserManager 850 LOC), 1 dead code cluster (src/legacy/), 1 API bloat (utils/ exports 45 symbols, 12 unused).",
+  "verdict": "",
+  "artifacts_produced": "artifacts/architecture-baseline.json;artifacts/architecture-report.md",
+  "error": ""
+}
+```
+
+Interactive tasks output via structured text or JSON written to `interactive/{id}-result.json`.
+
+---
+
+## Discovery Types
+
+| Type | Dedup Key | Data Schema | Description |
+|------|-----------|-------------|-------------|
+| `cycle_found` | `data.modules` (sorted) | `{modules, depth, description}` | Circular dependency detected |
+| `god_class_found` | `data.file` | `{file, loc, methods, description}` | God Class/Module identified |
+| `coupling_issue` | `data.module` | `{module, fan_in, fan_out, description}` | High coupling detected |
+| `dead_code_found` | `data.file+data.type` | `{file, type, description}` | Dead code or dead export |
+| `layer_violation` | `data.from+data.to` | `{from, to, description}` | Layering violation detected |
+| `file_modified` | `data.file` | `{file, change, lines_added}` | File change recorded |
+| `pattern_found` | `data.pattern_name+data.location` | `{pattern_name, location, description}` | Code pattern identified |
+| `metric_measured` | `data.metric+data.module` | `{metric, value, unit, module}` | Architecture metric measured |
+| `artifact_produced` | `data.path` | `{name, path, producer, type}` | Deliverable created |
+
+### Discovery NDJSON Format
+
+```jsonl
+{"ts":"2026-03-08T10:00:00Z","worker":"ANALYZE-001","type":"cycle_found","data":{"modules":["auth","user"],"depth":2,"description":"Circular dependency: auth imports user, user imports auth"}}
+{"ts":"2026-03-08T10:01:00Z","worker":"ANALYZE-001","type":"god_class_found","data":{"file":"src/services/UserManager.ts","loc":850,"methods":15,"description":"UserManager handles auth, profile, permissions, notifications"}}
+{"ts":"2026-03-08T10:05:00Z","worker":"ANALYZE-001","type":"metric_measured","data":{"metric":"coupling_score","value":0.72,"unit":"normalized","module":"src/auth/"}}
+{"ts":"2026-03-08T10:20:00Z","worker":"REFACTOR-001","type":"file_modified","data":{"file":"src/auth/index.ts","change":"Extracted IAuthService interface to break cycle","lines_added":25}}
+{"ts":"2026-03-08T10:25:00Z","worker":"REFACTOR-001","type":"artifact_produced","data":{"name":"refactoring-summary","path":"artifacts/refactoring-plan.md","producer":"designer","type":"markdown"}}
+```
+
+> Both csv-wave and interactive agents read/write the same discoveries.ndjson file.
+
+---
+
+## Cross-Mechanism Context Flow
+
+| Source | Target | Mechanism |
+|--------|--------|-----------|
+| CSV task findings | Interactive task | Injected via spawn message or send_input |
+| Interactive task result | CSV task prev_context | Read from interactive/{id}-result.json |
+| Any agent discovery | Any agent | Shared via discoveries.ndjson |
+
+---
+
+## Validation Rules
+
+| Rule | Check | Error |
+|------|-------|-------|
+| Unique IDs | No duplicate `id` values | "Duplicate task ID: {id}" |
+| Valid deps | All dep IDs exist in tasks | "Unknown dependency: {dep_id}" |
+| No self-deps | Task cannot depend on itself | "Self-dependency: {id}" |
+| No circular deps | Topological sort completes | "Circular dependency detected involving: {ids}" |
+| context_from valid | All context IDs exist and in earlier waves | "Invalid context_from: {id}" |
+| exec_mode valid | Value is `csv-wave` or `interactive` | "Invalid exec_mode: {value}" |
+| Description non-empty | Every task has description | "Empty description for task: {id}" |
+| Status enum | status in {pending, completed, failed, skipped} | "Invalid status: {status}" |
+| Role valid | role in {analyzer, designer, refactorer, validator, reviewer} | "Invalid role: {role}" |
+| Verdict enum | verdict in {PASS, WARN, FAIL, APPROVE, REVISE, REJECT, ""} | "Invalid verdict: {verdict}" |
+| Cross-mechanism deps | Interactive to CSV deps resolve correctly | "Cross-mechanism dependency unresolvable: {id}" |

.codex/skills/team-brainstorm/SKILL.md

@@ -0,0 +1,725 @@
+---
+name: team-brainstorm
+description: Multi-agent brainstorming pipeline with Generator-Critic loop. Generates ideas, challenges assumptions, synthesizes themes, and evaluates proposals. Supports Quick, Deep, and Full pipeline modes.
+argument-hint: "[-y|--yes] [-c|--concurrency N] [--continue] \"topic description\""
+allowed-tools: spawn_agents_on_csv, spawn_agent, wait, send_input, close_agent, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+## Auto Mode
+
+When `--yes` or `-y`: Auto-confirm task decomposition, skip interactive validation, use defaults.
+
+# Team Brainstorm
+
+## Usage
+
+```bash
+$team-brainstorm "How should we approach microservices migration?"
+$team-brainstorm -c 4 "Innovation strategies for AI-powered developer tools"
+$team-brainstorm -y "Quick brainstorm on naming conventions"
+$team-brainstorm --continue "brs-microservices-20260308"
+```
+
+**Flags**:
+- `-y, --yes`: Skip all confirmations (auto mode)
+- `-c, --concurrency N`: Max concurrent agents within each wave (default: 3)
+- `--continue`: Resume existing session
+
+**Output Directory**: `.workflow/.csv-wave/{session-id}/`
+**Core Output**: `tasks.csv` (master state) + `results.csv` (final) + `discoveries.ndjson` (shared exploration) + `context.md` (human-readable report)
+
+---
+
+## Overview
+
+Multi-agent brainstorming with Generator-Critic loop: generate ideas across multiple angles, challenge assumptions, synthesize themes, and evaluate proposals. Supports three pipeline modes (Quick/Deep/Full) with configurable depth and parallel ideation.
+
+**Execution Model**: Hybrid — CSV wave pipeline (primary) + individual agent spawn (secondary for Generator-Critic control)
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                    TEAM BRAINSTORM WORKFLOW                              │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│  Phase 0: Pre-Wave Interactive                                           │
+│     ├─ Topic clarification + complexity scoring                          │
+│     ├─ Pipeline mode selection (quick/deep/full)                         │
+│     └─ Output: refined requirements for decomposition                    │
+│                                                                          │
+│  Phase 1: Requirement → CSV + Classification                             │
+│     ├─ Parse topic into brainstorm tasks per selected pipeline            │
+│     ├─ Assign roles: ideator, challenger, synthesizer, evaluator         │
+│     ├─ Classify tasks: csv-wave | interactive (exec_mode)                │
+│     ├─ Compute dependency waves (topological sort → depth grouping)      │
+│     ├─ Generate tasks.csv with wave + exec_mode columns                  │
+│     └─ User validates task breakdown (skip if -y)                        │
+│                                                                          │
+│  Phase 2: Wave Execution Engine (Extended)                               │
+│     ├─ For each wave (1..N):                                             │
+│     │   ├─ Execute pre-wave interactive tasks (if any)                   │
+│     │   ├─ Build wave CSV (filter csv-wave tasks for this wave)          │
+│     │   ├─ Inject previous findings into prev_context column             │
+│     │   ├─ spawn_agents_on_csv(wave CSV)                                 │
+│     │   ├─ Execute post-wave interactive tasks (if any)                  │
+│     │   ├─ Merge all results into master tasks.csv                       │
+│     │   └─ Check: any failed? → skip dependents                         │
+│     └─ discoveries.ndjson shared across all modes (append-only)          │
+│                                                                          │
+│  Phase 3: Post-Wave Interactive                                          │
+│     ├─ Generator-Critic (GC) loop control                                │
+│     ├─ If critique severity >= HIGH: trigger revision wave               │
+│     └─ Max 2 GC rounds, then force convergence                          │
+│                                                                          │
+│  Phase 4: Results Aggregation                                            │
+│     ├─ Export final results.csv                                          │
+│     ├─ Generate context.md with all findings                             │
+│     ├─ Display summary: completed/failed/skipped per wave                │
+│     └─ Offer: view results | retry failed | done                        │
+│                                                                          │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Task Classification Rules
+
+Each task is classified by `exec_mode`:
+
+| exec_mode | Mechanism | Criteria |
+|-----------|-----------|----------|
+| `csv-wave` | `spawn_agents_on_csv` | One-shot, structured I/O, no multi-round interaction |
+| `interactive` | `spawn_agent`/`wait`/`send_input`/`close_agent` | Multi-round, clarification, inline utility |
+
+**Classification Decision**:
+
+| Task Property | Classification |
+|---------------|---------------|
+| Idea generation (single angle) | `csv-wave` |
+| Parallel ideation (Full pipeline, multiple angles) | `csv-wave` (parallel in same wave) |
+| Idea revision (GC loop) | `csv-wave` |
+| Critique / challenge | `csv-wave` |
+| Synthesis (theme extraction) | `csv-wave` |
+| Evaluation (scoring / ranking) | `csv-wave` |
+| GC loop control (severity check → decide revision or convergence) | `interactive` |
+| Topic clarification (Phase 0) | `interactive` |
+
+---
+
+## CSV Schema
+
+### tasks.csv (Master State)
+
+```csv
+id,title,description,role,angle,gc_round,deps,context_from,exec_mode,wave,status,findings,gc_signal,severity_summary,error
+"IDEA-001","Multi-angle idea generation","Generate 3+ ideas per angle with title, description, assumption, impact","ideator","Technical;Product;Innovation","0","","","csv-wave","1","pending","","","",""
+"CHALLENGE-001","Critique generated ideas","Challenge each idea across assumption, feasibility, risk, competition dimensions","challenger","","0","IDEA-001","IDEA-001","csv-wave","2","pending","","","",""
+"GC-CHECK-001","GC loop decision","Evaluate critique severity and decide: revision or convergence","gc-controller","","1","CHALLENGE-001","CHALLENGE-001","interactive","3","pending","","","",""
+```
+
+**Columns**:
+
+| Column | Phase | Description |
+|--------|-------|-------------|
+| `id` | Input | Unique task identifier (string) |
+| `title` | Input | Short task title |
+| `description` | Input | Detailed task description |
+| `role` | Input | Worker role: ideator, challenger, synthesizer, evaluator |
+| `angle` | Input | Brainstorming angle(s) for ideator tasks (semicolon-separated) |
+| `gc_round` | Input | Generator-Critic round number (0 = initial, 1+ = revision) |
+| `deps` | Input | Semicolon-separated dependency task IDs |
+| `context_from` | Input | Semicolon-separated task IDs whose findings this task needs |
+| `exec_mode` | Input | `csv-wave` or `interactive` |
+| `wave` | Computed | Wave number (computed by topological sort, 1-based) |
+| `status` | Output | `pending` → `completed` / `failed` / `skipped` |
+| `findings` | Output | Key discoveries or implementation notes (max 500 chars) |
+| `gc_signal` | Output | Generator-Critic signal: `REVISION_NEEDED` or `CONVERGED` (challenger only) |
+| `severity_summary` | Output | Severity count: e.g. "CRITICAL:1 HIGH:2 MEDIUM:3 LOW:1" |
+| `error` | Output | Error message if failed (empty if success) |
+
+### Per-Wave CSV (Temporary)
+
+Each wave generates a temporary `wave-{N}.csv` with extra `prev_context` column (csv-wave tasks only).
+
+---
+
+## Agent Registry (Interactive Agents)
+
+| Agent | Role File | Pattern | Responsibility | Position |
+|-------|-----------|---------|----------------|----------|
+| gc-controller | agents/gc-controller.md | 2.3 (wait-respond) | Evaluate critique severity, decide revision vs convergence | post-wave (after challenger wave) |
+| topic-clarifier | agents/topic-clarifier.md | 2.3 (wait-respond) | Clarify topic, assess complexity, select pipeline mode | standalone (Phase 0) |
+
+> **COMPACT PROTECTION**: Agent files are execution documents. When context compression occurs, **you MUST immediately `Read` the corresponding agent.md** to reload.
+
+---
+
+## Output Artifacts
+
+| File | Purpose | Lifecycle |
+|------|---------|-----------|
+| `tasks.csv` | Master state — all tasks with status/findings | Updated after each wave |
+| `wave-{N}.csv` | Per-wave input (temporary, csv-wave tasks only) | Created before wave, deleted after |
+| `results.csv` | Final export of all task results | Created in Phase 4 |
+| `discoveries.ndjson` | Shared exploration board (all agents, both modes) | Append-only, carries across waves |
+| `context.md` | Human-readable execution report | Created in Phase 4 |
+| `interactive/{id}-result.json` | Results from interactive tasks | Created per interactive task |
+
+---
+
+## Session Structure
+
+```
+.workflow/.csv-wave/{session-id}/
+├── tasks.csv                  # Master state (all tasks, both modes)
+├── results.csv                # Final results export
+├── discoveries.ndjson         # Shared discovery board (all agents)
+├── context.md                 # Human-readable report
+├── wave-{N}.csv               # Temporary per-wave input (csv-wave only)
+└── interactive/               # Interactive task artifacts
+    └── {id}-result.json       # Per-task results
+```
+
+---
+
+## Implementation
+
+### Session Initialization
+
+```javascript
+const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
+
+// Parse flags
+const AUTO_YES = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
+const continueMode = $ARGUMENTS.includes('--continue')
+const concurrencyMatch = $ARGUMENTS.match(/(?:--concurrency|-c)\s+(\d+)/)
+const maxConcurrency = concurrencyMatch ? parseInt(concurrencyMatch[1]) : 3
+
+// Clean requirement text (remove flags)
+const topic = $ARGUMENTS
+  .replace(/--yes|-y|--continue|--concurrency\s+\d+|-c\s+\d+/g, '')
+  .trim()
+
+const slug = topic.toLowerCase()
+  .replace(/[^a-z0-9\u4e00-\u9fa5]+/g, '-')
+  .substring(0, 40)
+const dateStr = getUtc8ISOString().substring(0, 10).replace(/-/g, '')
+let sessionId = `brs-${slug}-${dateStr}`
+let sessionFolder = `.workflow/.csv-wave/${sessionId}`
+
+// Continue mode: find existing session
+if (continueMode) {
+  const existing = Bash(`ls -t .workflow/.csv-wave/brs-* 2>/dev/null | head -1`).trim()
+  if (existing) {
+    sessionId = existing.split('/').pop()
+    sessionFolder = existing
+    // Read existing tasks.csv, find incomplete waves, resume from Phase 2
+  }
+}
+
+Bash(`mkdir -p ${sessionFolder}/interactive`)
+```
+
+---
+
+### Phase 0: Pre-Wave Interactive
+
+**Objective**: Clarify topic, assess complexity, and select pipeline mode.
+
+**Execution**:
+
+```javascript
+const clarifier = spawn_agent({
+  message: `
+## TASK ASSIGNMENT
+
+### MANDATORY FIRST STEPS (Agent Execute)
+1. **Read role definition**: ~  or <project>/.codex/skills/team-brainstorm/agents/topic-clarifier.md (MUST read first)
+2. Read: .workflow/project-tech.json (if exists)
+
+---
+
+Goal: Clarify brainstorming topic and select pipeline mode
+Topic: ${topic}
+
+### Task
+1. Assess topic complexity using signal detection:
+   - Strategic/systemic keywords (+3): strategy, architecture, system, framework, paradigm
+   - Multi-dimensional keywords (+2): multiple, compare, tradeoff, versus, alternative
+   - Innovation-focused keywords (+2): innovative, creative, novel, breakthrough
+   - Simple/basic keywords (-2): simple, quick, straightforward, basic
+2. Score >= 4 → full, 2-3 → deep, 0-1 → quick
+3. Suggest divergence angles (e.g., Technical, Product, Innovation, Risk)
+4. Return structured result
+`
+})
+
+const clarifierResult = wait({ ids: [clarifier], timeout_ms: 120000 })
+
+if (clarifierResult.timed_out) {
+  send_input({ id: clarifier, message: "Please finalize and output current findings." })
+  const retry = wait({ ids: [clarifier], timeout_ms: 60000 })
+}
+
+// Parse result for pipeline_mode, angles
+close_agent({ id: clarifier })
+
+// Store result
+Write(`${sessionFolder}/interactive/topic-clarifier-result.json`, JSON.stringify({
+  task_id: "topic-clarification",
+  status: "completed",
+  pipeline_mode: parsedMode, // "quick" | "deep" | "full"
+  angles: parsedAngles,      // ["Technical", "Product", "Innovation", "Risk"]
+  complexity_score: parsedScore,
+  timestamp: getUtc8ISOString()
+}))
+```
+
+If not AUTO_YES, present user with pipeline mode selection for confirmation:
+
+```javascript
+if (!AUTO_YES) {
+  const answer = AskUserQuestion({
+    questions: [{
+      question: `Topic: "${topic}"\nRecommended pipeline: ${pipeline_mode} (complexity: ${complexity_score})\nAngles: ${angles.join(', ')}\n\nApprove?`,
+      header: "Pipeline Selection",
+      multiSelect: false,
+      options: [
+        { label: "Approve", description: `Use ${pipeline_mode} pipeline` },
+        { label: "Quick", description: "3 tasks: generate → challenge → synthesize" },
+        { label: "Deep", description: "6 tasks: generate → challenge → revise → re-challenge → synthesize → evaluate" },
+        { label: "Full", description: "7 tasks: 3x parallel generation → challenge → revise → synthesize → evaluate" }
+      ]
+    }]
+  })
+  // Update pipeline_mode based on user choice
+}
+```
+
+**Success Criteria**:
+- Refined requirements available for Phase 1 decomposition
+- Interactive agents closed, results stored
+
+---
+
+### Phase 1: Requirement → CSV + Classification
+
+**Objective**: Build tasks.csv from selected pipeline mode with proper wave assignments.
+
+**Decomposition Rules**:
+
+| Pipeline | Tasks | Wave Structure |
+|----------|-------|---------------|
+| quick | IDEA-001 → CHALLENGE-001 → SYNTH-001 | 3 waves, serial |
+| deep | IDEA-001 → CHALLENGE-001 → IDEA-002 → CHALLENGE-002 → SYNTH-001 → EVAL-001 | 6 waves, serial with GC loop |
+| full | IDEA-001,002,003 (parallel) → CHALLENGE-001 → IDEA-004 → SYNTH-001 → EVAL-001 | 5 waves, fan-out + GC |
+
+**Classification Rules**:
+
+All brainstorm work tasks (ideation, challenging, synthesis, evaluation) are `csv-wave`. The GC loop controller between challenger and next ideation revision is `interactive` (post-wave, spawned by orchestrator to decide the GC outcome).
+
+**Wave Computation**: Kahn's BFS topological sort with depth tracking (csv-wave tasks only).
+
+**User Validation**: Display task breakdown with wave + exec_mode assignment (skip if AUTO_YES).
+
+**Pipeline Task Definitions**:
+
+#### Quick Pipeline (3 csv-wave tasks)
+
+| Task ID | Role | Wave | Deps | Description |
+|---------|------|------|------|-------------|
+| IDEA-001 | ideator | 1 | (none) | Generate multi-angle ideas: 3+ ideas per angle with title, description, assumption, impact |
+| CHALLENGE-001 | challenger | 2 | IDEA-001 | Challenge each idea across 4 dimensions (assumption, feasibility, risk, competition). Assign severity per idea. Output GC signal |
+| SYNTH-001 | synthesizer | 3 | CHALLENGE-001 | Synthesize ideas and critiques into 1-3 integrated proposals with feasibility and innovation scores |
+
+#### Deep Pipeline (6 csv-wave tasks + 1 interactive GC check)
+
+Same as Quick plus:
+
+| Task ID | Role | Wave | Deps | Description |
+|---------|------|------|------|-------------|
+| IDEA-002 | ideator | 4 | CHALLENGE-001 | Revise ideas based on critique feedback (GC Round 1). Address HIGH/CRITICAL challenges |
+| CHALLENGE-002 | challenger | 5 | IDEA-002 | Validate revised ideas (GC Round 2). Re-evaluate previously challenged ideas |
+| SYNTH-001 | synthesizer | 6 | CHALLENGE-002 | Synthesize all ideas and critiques |
+| EVAL-001 | evaluator | 7 | SYNTH-001 | Score and rank proposals: Feasibility 30%, Innovation 25%, Impact 25%, Cost 20% |
+
+GC-CHECK-001 (interactive) runs post-wave after CHALLENGE-001 to decide whether to proceed with revision or skip to synthesis.
+
+#### Full Pipeline (7 csv-wave tasks + GC control)
+
+| Task ID | Role | Wave | Deps | Description |
+|---------|------|------|------|-------------|
+| IDEA-001 | ideator | 1 | (none) | Generate ideas from angle 1 |
+| IDEA-002 | ideator | 1 | (none) | Generate ideas from angle 2 |
+| IDEA-003 | ideator | 1 | (none) | Generate ideas from angle 3 |
+| CHALLENGE-001 | challenger | 2 | IDEA-001;IDEA-002;IDEA-003 | Critique all generated ideas |
+| IDEA-004 | ideator | 3 | CHALLENGE-001 | Revise ideas based on critique |
+| SYNTH-001 | synthesizer | 4 | IDEA-004 | Synthesize all ideas and critiques |
+| EVAL-001 | evaluator | 5 | SYNTH-001 | Score and rank proposals |
+
+**Success Criteria**:
+- tasks.csv created with valid schema, wave, and exec_mode assignments
+- No circular dependencies
+- User approved (or AUTO_YES)
+
+---
+
+### Phase 2: Wave Execution Engine (Extended)
+
+**Objective**: Execute tasks wave-by-wave with hybrid mechanism support and cross-wave context propagation.
+
+```javascript
+const failedIds = new Set()
+const skippedIds = new Set()
+const MAX_GC_ROUNDS = 2
+let gcRound = 0
+
+for (let wave = 1; wave <= maxWave; wave++) {
+  console.log(`\n## Wave ${wave}/${maxWave}\n`)
+
+  // 1. Read current master CSV
+  const masterCsv = parseCsv(Read(`${sessionFolder}/tasks.csv`))
+
+  // 2. Separate csv-wave and interactive tasks for this wave
+  const waveTasks = masterCsv.filter(row => parseInt(row.wave) === wave)
+  const csvTasks = waveTasks.filter(t => t.exec_mode === 'csv-wave')
+  const interactiveTasks = waveTasks.filter(t => t.exec_mode === 'interactive')
+
+  // 3. Skip tasks whose deps failed
+  const executableCsvTasks = []
+  for (const task of csvTasks) {
+    const deps = task.deps.split(';').filter(Boolean)
+    if (deps.some(d => failedIds.has(d) || skippedIds.has(d))) {
+      skippedIds.add(task.id)
+      updateMasterCsvRow(sessionFolder, task.id, {
+        status: 'skipped',
+        error: 'Dependency failed or skipped'
+      })
+      continue
+    }
+    executableCsvTasks.push(task)
+  }
+
+  // 4. Build prev_context for each csv-wave task
+  for (const task of executableCsvTasks) {
+    const contextIds = task.context_from.split(';').filter(Boolean)
+    const prevFindings = contextIds
+      .map(id => {
+        const prevRow = masterCsv.find(r => r.id === id)
+        if (prevRow && prevRow.status === 'completed' && prevRow.findings) {
+          return `[Task ${id}: ${prevRow.title}] ${prevRow.findings}`
+        }
+        return null
+      })
+      .filter(Boolean)
+      .join('\n')
+    task.prev_context = prevFindings || 'No previous context available'
+  }
+
+  // 5. Write wave CSV and execute csv-wave tasks
+  if (executableCsvTasks.length > 0) {
+    const waveHeader = 'id,title,description,role,angle,gc_round,deps,context_from,exec_mode,wave,prev_context'
+    const waveRows = executableCsvTasks.map(t =>
+      [t.id, t.title, t.description, t.role, t.angle, t.gc_round, t.deps, t.context_from, t.exec_mode, t.wave, t.prev_context]
+        .map(cell => `"${String(cell).replace(/"/g, '""')}"`)
+        .join(',')
+    )
+    Write(`${sessionFolder}/wave-${wave}.csv`, [waveHeader, ...waveRows].join('\n'))
+
+    const waveResult = spawn_agents_on_csv({
+      csv_path: `${sessionFolder}/wave-${wave}.csv`,
+      id_column: "id",
+      instruction: buildBrainstormInstruction(sessionFolder, wave),
+      max_concurrency: maxConcurrency,
+      max_runtime_seconds: 600,
+      output_csv_path: `${sessionFolder}/wave-${wave}-results.csv`,
+      output_schema: {
+        type: "object",
+        properties: {
+          id: { type: "string" },
+          status: { type: "string", enum: ["completed", "failed"] },
+          findings: { type: "string" },
+          gc_signal: { type: "string" },
+          severity_summary: { type: "string" },
+          error: { type: "string" }
+        },
+        required: ["id", "status", "findings"]
+      }
+    })
+    // Blocks until wave completes
+
+    // Merge results into master CSV
+    const waveResults = parseCsv(Read(`${sessionFolder}/wave-${wave}-results.csv`))
+    for (const result of waveResults) {
+      updateMasterCsvRow(sessionFolder, result.id, {
+        status: result.status,
+        findings: result.findings || '',
+        gc_signal: result.gc_signal || '',
+        severity_summary: result.severity_summary || '',
+        error: result.error || ''
+      })
+      if (result.status === 'failed') failedIds.add(result.id)
+    }
+
+    Bash(`rm -f "${sessionFolder}/wave-${wave}.csv"`)
+  }
+
+  // 6. Execute post-wave interactive tasks (GC controller)
+  for (const task of interactiveTasks) {
+    if (task.status !== 'pending') continue
+    const deps = task.deps.split(';').filter(Boolean)
+    if (deps.some(d => failedIds.has(d) || skippedIds.has(d))) {
+      skippedIds.add(task.id)
+      continue
+    }
+
+    // Spawn GC controller agent
+    const gcAgent = spawn_agent({
+      message: `
+## TASK ASSIGNMENT
+
+### MANDATORY FIRST STEPS (Agent Execute)
+1. **Read role definition**: ~  or <project>/.codex/skills/team-brainstorm/agents/gc-controller.md (MUST read first)
+2. Read: ${sessionFolder}/discoveries.ndjson (shared discoveries)
+
+---
+
+Goal: Evaluate critique severity and decide revision vs convergence
+Session: ${sessionFolder}
+GC Round: ${gcRound}
+Max GC Rounds: ${MAX_GC_ROUNDS}
+
+### Context
+Read the latest critique file and determine the GC signal.
+If REVISION_NEEDED and gcRound < maxRounds: output "REVISION"
+If CONVERGED or gcRound >= maxRounds: output "CONVERGE"
+`
+    })
+
+    const gcResult = wait({ ids: [gcAgent], timeout_ms: 120000 })
+    if (gcResult.timed_out) {
+      send_input({ id: gcAgent, message: "Please finalize your decision now." })
+      wait({ ids: [gcAgent], timeout_ms: 60000 })
+    }
+    close_agent({ id: gcAgent })
+
+    // Parse GC decision and potentially create/skip revision tasks
+    Write(`${sessionFolder}/interactive/${task.id}-result.json`, JSON.stringify({
+      task_id: task.id, status: "completed",
+      gc_decision: gcDecision, gc_round: gcRound,
+      timestamp: getUtc8ISOString()
+    }))
+
+    if (gcDecision === "CONVERGE") {
+      // Skip remaining GC tasks, mark revision tasks as skipped
+      // Unblock SYNTH directly
+    } else {
+      gcRound++
+      // Let the revision wave proceed naturally
+    }
+
+    updateMasterCsvRow(sessionFolder, task.id, { status: 'completed', findings: `GC decision: ${gcDecision}` })
+  }
+}
+```
+
+**Success Criteria**:
+- All waves executed in order
+- Both csv-wave and interactive tasks handled per wave
+- Each wave's results merged into master CSV before next wave starts
+- Dependent tasks skipped when predecessor failed
+- discoveries.ndjson accumulated across all waves and mechanisms
+- GC loop controlled with max 2 rounds
+
+---
+
+### Phase 3: Post-Wave Interactive
+
+**Objective**: Handle any final GC loop convergence and prepare for synthesis.
+
+If the pipeline used GC loops and the final GC decision was CONVERGE or max rounds reached, ensure SYNTH-001 is unblocked and all remaining GC-related tasks are properly marked.
+
+**Success Criteria**:
+- Post-wave interactive processing complete
+- Interactive agents closed, results stored
+
+---
+
+### Phase 4: Results Aggregation
+
+**Objective**: Generate final results and human-readable report.
+
+```javascript
+const masterCsv = Read(`${sessionFolder}/tasks.csv`)
+Write(`${sessionFolder}/results.csv`, masterCsv)
+
+const tasks = parseCsv(masterCsv)
+const completed = tasks.filter(t => t.status === 'completed')
+const failed = tasks.filter(t => t.status === 'failed')
+const skipped = tasks.filter(t => t.status === 'skipped')
+
+const contextContent = `# Team Brainstorm Report
+
+**Session**: ${sessionId}
+**Topic**: ${topic}
+**Pipeline**: ${pipeline_mode}
+**Completed**: ${getUtc8ISOString()}
+
+---
+
+## Summary
+
+| Metric | Count |
+|--------|-------|
+| Total Tasks | ${tasks.length} |
+| Completed | ${completed.length} |
+| Failed | ${failed.length} |
+| Skipped | ${skipped.length} |
+| GC Rounds | ${gcRound} |
+
+---
+
+## Wave Execution
+
+${waveDetails}
+
+---
+
+## Task Details
+
+${taskDetails}
+
+---
+
+## Brainstorm Artifacts
+
+- Ideas: discoveries with type "idea" in discoveries.ndjson
+- Critiques: discoveries with type "critique" in discoveries.ndjson
+- Synthesis: discoveries with type "synthesis" in discoveries.ndjson
+- Evaluation: discoveries with type "evaluation" in discoveries.ndjson
+`
+
+Write(`${sessionFolder}/context.md`, contextContent)
+```
+
+If not AUTO_YES and there are failed tasks, offer retry or view report.
+
+**Success Criteria**:
+- results.csv exported (all tasks, both modes)
+- context.md generated
+- All interactive agents closed
+- Summary displayed to user
+
+---
+
+## Shared Discovery Board Protocol
+
+All agents across all waves share `discoveries.ndjson`. This enables cross-role knowledge sharing.
+
+**Discovery Types**:
+
+| Type | Dedup Key | Data Schema | Description |
+|------|-----------|-------------|-------------|
+| `idea` | `data.title` | `{title, angle, description, assumption, impact}` | Generated idea |
+| `critique` | `data.idea_title` | `{idea_title, dimension, severity, challenge, rationale}` | Critique of an idea |
+| `theme` | `data.name` | `{name, strength, supporting_ideas[]}` | Extracted theme from synthesis |
+| `proposal` | `data.title` | `{title, source_ideas[], feasibility, innovation, description}` | Integrated proposal |
+| `evaluation` | `data.proposal_title` | `{proposal_title, weighted_score, rank, recommendation}` | Proposal evaluation |
+| `gc_decision` | `data.round` | `{round, signal, severity_counts}` | GC loop decision |
+
+**Format**: NDJSON, each line is self-contained JSON:
+
+```jsonl
+{"ts":"2026-03-08T10:00:00+08:00","worker":"IDEA-001","type":"idea","data":{"title":"API Gateway Pattern","angle":"Technical","description":"Centralized API gateway for microservice routing","assumption":"Services need unified entry point","impact":"Simplifies client integration"}}
+{"ts":"2026-03-08T10:05:00+08:00","worker":"CHALLENGE-001","type":"critique","data":{"idea_title":"API Gateway Pattern","dimension":"feasibility","severity":"MEDIUM","challenge":"Single point of failure","rationale":"Requires high availability design"}}
+```
+
+**Protocol Rules**:
+1. Read board before own work → leverage existing context
+2. Write discoveries immediately via `echo >>` → don't batch
+3. Deduplicate — check existing entries by type + dedup key
+4. Append-only — never modify or delete existing lines
+
+---
+
+## Consensus Severity Routing
+
+When the challenger returns critique results with severity-graded verdicts:
+
+| Severity | Action |
+|----------|--------|
+| HIGH | Trigger revision round (GC loop), max 2 rounds total |
+| MEDIUM | Log warning, continue pipeline |
+| LOW | Treat as consensus reached |
+
+**Constraints**: Max 2 GC rounds (revision cycles). If still HIGH after 2 rounds, force convergence to synthesizer.
+
+---
+
+## Error Handling
+
+| Error | Resolution |
+|-------|------------|
+| Circular dependency | Detect in wave computation, abort with error message |
+| CSV agent timeout | Mark as failed in results, continue with wave |
+| CSV agent failed | Mark as failed, skip dependent tasks in later waves |
+| Interactive agent timeout | Urge convergence via send_input, then close if still timed out |
+| Interactive agent failed | Mark as failed, skip dependents |
+| All agents in wave failed | Log error, offer retry or abort |
+| CSV parse error | Validate CSV format before execution, show line number |
+| discoveries.ndjson corrupt | Ignore malformed lines, continue with valid entries |
+| GC loop exceeds 2 rounds | Force convergence to synthesizer |
+| No ideas generated | Report failure, suggest refining topic |
+| Continue mode: no session found | List available sessions, prompt user to select |
+
+---
+
+## Core Rules
+
+1. **Start Immediately**: First action is session initialization, then Phase 0/1
+2. **Wave Order is Sacred**: Never execute wave N before wave N-1 completes and results are merged
+3. **CSV is Source of Truth**: Master tasks.csv holds all state (both csv-wave and interactive)
+4. **CSV First**: Default to csv-wave for tasks; only use interactive when interaction pattern requires it
+5. **Context Propagation**: prev_context built from master CSV, not from memory
+6. **Discovery Board is Append-Only**: Never clear, modify, or recreate discoveries.ndjson — both mechanisms share it
+7. **Skip on Failure**: If a dependency failed, skip the dependent task (regardless of mechanism)
+8. **Lifecycle Balance**: Every spawn_agent MUST have a matching close_agent
+9. **Cleanup Temp Files**: Remove wave-{N}.csv after results are merged
+10. **DO NOT STOP**: Continuous execution until all waves complete or all remaining tasks are skipped
+
+
+---
+
+## Coordinator Role Constraints (Main Agent)
+
+**CRITICAL**: The coordinator (main agent executing this skill) is responsible for **orchestration only**, NOT implementation.
+
+15. **Coordinator Does NOT Execute Code**: The main agent MUST NOT write, modify, or implement any code directly. All implementation work is delegated to spawned team agents. The coordinator only:
+    - Spawns agents with task assignments
+    - Waits for agent callbacks
+    - Merges results and coordinates workflow
+    - Manages workflow transitions between phases
+
+16. **Patient Waiting is Mandatory**: Agent execution takes significant time (typically 10-30 minutes per phase, sometimes longer). The coordinator MUST:
+    - Wait patiently for `wait()` calls to complete
+    - NOT skip workflow steps due to perceived delays
+    - NOT assume agents have failed just because they're taking time
+    - Trust the timeout mechanisms defined in the skill
+
+17. **Use send_input for Clarification**: When agents need guidance or appear stuck, the coordinator MUST:
+    - Use `send_input()` to ask questions or provide clarification
+    - NOT skip the agent or move to next phase prematurely
+    - Give agents opportunity to respond before escalating
+    - Example: `send_input({ id: agent_id, message: "Please provide status update or clarify blockers" })`
+
+18. **No Workflow Shortcuts**: The coordinator MUST NOT:
+    - Skip phases or stages defined in the workflow
+    - Bypass required approval or review steps
+    - Execute dependent tasks before prerequisites complete
+    - Assume task completion without explicit agent callback
+    - Make up or fabricate agent results
+
+19. **Respect Long-Running Processes**: This is a complex multi-agent workflow that requires patience:
+    - Total execution time may range from 30-90 minutes or longer
+    - Each phase may take 10-30 minutes depending on complexity
+    - The coordinator must remain active and attentive throughout the entire process
+    - Do not terminate or skip steps due to time concerns