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 0 → 1: functions.update_plan([{id:"phase-0",status:"completed"},{id:"phase-1",status:"in_progress"}])

Phase 1: Discovery & Seed Analysis
   |- Ref: phases/01-discovery.md
   |- Generate session ID: SPEC-{YYYY-MM-DD}-{slug}
   |- 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_turns: "none", message: ... })
   |  |- wait_agent({ timeout_ms: 1800000 })
   |  |- 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 → 1.5: functions.update_plan([{id:"phase-1",status:"completed"},{id:"phase-1.5",status:"in_progress"}])

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 1.5 → 2: functions.update_plan([{id:"phase-1.5",status:"completed"},{id:"phase-2",status:"in_progress"}])

Phase 2: Product Brief  [AGENT: doc-generator]
   |- spawn_agent({ task_name: "doc-gen-p2", fork_turns: "none", 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({ timeout_ms: 1800000 })
   |- close_agent({ target: "doc-gen-p2" })
   |- Orchestrator validates: files exist, spec-config.json updated

Phase 2 → 3: functions.update_plan([{id:"phase-2",status:"completed"},{id:"phase-3",status:"in_progress"}])

Phase 3: Requirements / PRD  [AGENT: doc-generator]
   |- spawn_agent({ task_name: "doc-gen-p3", fork_turns: "none", 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({ timeout_ms: 1800000 })
   |- close_agent({ target: "doc-gen-p3" })
   |- Orchestrator validates: directory exists, file count matches

Phase 3 → 4: functions.update_plan([{id:"phase-3",status:"completed"},{id:"phase-4",status:"in_progress"}])

Phase 4: Architecture  [AGENT: doc-generator]
   |- spawn_agent({ task_name: "doc-gen-p4", fork_turns: "none", 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({ timeout_ms: 1800000 })
   |- close_agent({ target: "doc-gen-p4" })
   |- Orchestrator validates: directory exists, ADR files present

Phase 4 → 5: functions.update_plan([{id:"phase-4",status:"completed"},{id:"phase-5",status:"in_progress"}])

Phase 5: Epics & Stories  [AGENT: doc-generator]
   |- spawn_agent({ task_name: "doc-gen-p5", fork_turns: "none", 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({ timeout_ms: 1800000 })
   |- close_agent({ target: "doc-gen-p5" })
   |- Orchestrator validates: directory exists, MVP epics present

Phase 5 → 6: functions.update_plan([{id:"phase-5",status:"completed"},{id:"phase-6",status:"in_progress"}])

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_turns: "none", message: <context envelope> })
   |- Agent reads: phases/06-5-auto-fix.md + readiness-report.md
   |- Agent executes: fix affected Phase 2-5 documents
   |- wait_agent({ timeout_ms: 1800000 })
   |- close_agent({ target: "doc-gen-fix" })
   |- Re-run Phase 6 validation
   |- Max 2 iterations, then force handoff

Phase 6 → 7: functions.update_plan([{id:"phase-6",status:"completed"},{id:"phase-7",status:"in_progress"}])

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

Phase 7 complete: functions.update_plan([{id:"phase-7",status:"completed"}])

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-${date}-${slug}`;
const workDir = `.workflow/.spec/${sessionId}`;

Bash(`mkdir -p "${workDir}"`);

// Initialize progress tracking (MANDATORY)
functions.update_plan([
  { id: "phase-0", title: "Phase 0: Specification Study", status: "in_progress" },
  { id: "phase-1", title: "Phase 1: Discovery", status: "pending" },
  { id: "phase-1.5", title: "Phase 1.5: Req Expansion", status: "pending" },
  { id: "phase-2", title: "Phase 2: Product Brief", status: "pending" },
  { id: "phase-3", title: "Phase 3: Requirements (PRD)", status: "pending" },
  { id: "phase-4", title: "Phase 4: Architecture", status: "pending" },
  { id: "phase-5", title: "Phase 5: Epics & Stories", status: "pending" },
  { id: "phase-6", title: "Phase 6: Readiness Check", status: "pending" },
  { id: "phase-7", title: "Phase 7: Issue Export", status: "pending" }
])

.workflow/.spec/SPEC-{YYYY-MM-DD}-{slug}/
+-- 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_turns: "none",
  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({ timeout_ms: 1800000 })

// 2. Handle timeout (4-step cascade)
if (result.timed_out) {
  // Step 1: Status probe
  followup_task({
    target: "doc-gen-p<N>",
    message: "STATUS_CHECK: Report current progress, findings so far, and estimated remaining work."
  })
  const status = wait_agent({ timeout_ms: 180000 })  // 3 min
  if (status.timed_out) {
    // Step 2: Force finalize
    followup_task({
      target: "doc-gen-p<N>",
      message: "FINALIZE: Output all current findings immediately. Time limit reached.",
      interrupt: true
    })
    const forced = wait_agent({ timeout_ms: 180000 })  // 3 min
    if (forced.timed_out) {
      // Step 3: Close agent
      close_agent({ target: "doc-gen-p<N>" })
      // Step 4: 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