Spec Generator

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)

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)
   |  |- spawn_agent({ task_name: "spec-explorer", fork_context: false, message: ... })
   |  |- wait_agent({ targets: ["spec-explorer"], timeout_ms: 300000 })
   |  |- close_agent({ target: "spec-explorer" })
   |- 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]
   |- spawn_agent({ task_name: "doc-gen-p2", fork_context: false, message: <context envelope> })
   |- Agent reads: phases/02-product-brief.md
   |- Agent executes: 3 parallel CLI analyses + synthesis + glossary generation
   |- Agent writes: product-brief.md, glossary.json
   |- wait_agent({ targets: ["doc-gen-p2"], timeout_ms: 600000 })
   |- close_agent({ target: "doc-gen-p2" })
   |- Orchestrator validates: files exist, spec-config.json updated

Phase 3: Requirements / PRD  [AGENT: doc-generator]
   |- spawn_agent({ task_name: "doc-gen-p3", fork_context: false, message: <context envelope> })
   |- 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)
   |- wait_agent({ targets: ["doc-gen-p3"], timeout_ms: 600000 })
   |- close_agent({ target: "doc-gen-p3" })
   |- Orchestrator validates: directory exists, file count matches

Phase 4: Architecture  [AGENT: doc-generator]
   |- spawn_agent({ task_name: "doc-gen-p4", fork_context: false, message: <context envelope> })
   |- Agent reads: phases/04-architecture.md
   |- Agent executes: Gemini analysis + Codex review + codebase mapping
   |- Agent writes: architecture/ directory (_index.md + ADR-*.md)
   |- wait_agent({ targets: ["doc-gen-p4"], timeout_ms: 600000 })
   |- close_agent({ target: "doc-gen-p4" })
   |- Orchestrator validates: directory exists, ADR files present

Phase 5: Epics & Stories  [AGENT: doc-generator]
   |- spawn_agent({ task_name: "doc-gen-p5", fork_context: false, message: <context envelope> })
   |- 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)
   |- wait_agent({ targets: ["doc-gen-p5"], timeout_ms: 600000 })
   |- close_agent({ target: "doc-gen-p5" })
   |- 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]
   |- spawn_agent({ task_name: "doc-gen-fix", fork_context: false, message: <context envelope> })
   |- Agent reads: phases/06-5-auto-fix.md + readiness-report.md
   |- Agent executes: fix affected Phase 2-5 documents
   |- wait_agent({ targets: ["doc-gen-fix"], timeout_ms: 600000 })
   |- close_agent({ target: "doc-gen-fix" })
   |- 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)

// 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}"`);

.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

{
  "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" }
  ]
}

spawn_agent({
  task_name: "doc-gen-p<N>",
  fork_context: false,
  message: `
## Spec Generator - Phase <N>: <phase-name>

### MANDATORY FIRST STEPS (Agent Execute)
1. **Read role definition**: ~/.codex/agents/doc-generator.toml (MUST read first)
2. Read: <skill-dir>/phases/<phase-file>

---

### Session
- ID: <session-id>
- Work Dir: <work-dir>
- Auto Mode: <auto-mode>
- Spec Type: <spec-type>

### Input (read from disk)
<input-files-list>

### Instructions
Read: <skill-dir>/phases/<phase-file>
Apply template: <skill-dir>/templates/<template-file>

### Glossary (Phase 3+ only)
Read: <work-dir>/glossary.json

### Output
Write files to: <work-dir>/<output-path>
Update: <work-dir>/spec-config.json (phasesCompleted)
Return: JSON summary { files_created, quality_notes, key_decisions }
`
})

// 1. Wait for agent completion
const result = wait_agent({ targets: ["doc-gen-p<N>"], timeout_ms: 600000 })

// 2. Handle timeout
if (result.timed_out) {
  assign_task({
    target: "doc-gen-p<N>",
    items: [{ type: "text", text: "Please finalize current work and output results immediately." }]
  })
  const retryResult = wait_agent({ targets: ["doc-gen-p<N>"], timeout_ms: 120000 })
  if (retryResult.timed_out) {
    close_agent({ target: "doc-gen-p<N>" })
    // Fall back to inline execution for this phase
  }
}

// 3. Close agent (lifecycle balance)
close_agent({ target: "doc-gen-p<N>" })

// 4. Parse agent return summary
const summary = parseJSON(result.status["doc-gen-p<N>"].completed)

// 5. Validate files exist
summary.files_created.forEach(file => {
  const exists = Glob(`<work-dir>/${file}`)
  if (!exists.length) → Error: agent claimed file but not found
})

// 6. Verify spec-config.json updated
const config = JSON.parse(Read(`<work-dir>/spec-config.json`))
const phaseComplete = config.phasesCompleted.some(p => p.phase === N)
if (!phaseComplete) → Error: agent did not update phasesCompleted

// 7. Store summary for downstream context (do NOT read full documents)
phasesSummaries[N] = summary

// Standard per-phase cleanup (after wait_agent succeeds)
close_agent({ target: "doc-gen-p<N>" })

// On workflow abort / user cancellation
const activeAgents = ["doc-gen-p2", "doc-gen-p3", "doc-gen-p4", "doc-gen-p5", "doc-gen-fix", "spec-explorer"]
activeAgents.forEach(name => {
  try { close_agent({ target: name }) } catch { /* not active */ }
})