maestro-flow 0.3.21 → 0.3.23

package/.claude/commands/maestro-spec-generate.md

@@ -1,78 +0,0 @@
----
-name: maestro-spec-generate
-description: Generate specification package from idea/requirements through 7-phase document chain producing product brief, PRD, architecture, epics, and interactive roadmap
-argument-hint: "<idea or @file> [-y] [-c] [--count N]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Transform an idea, brainstorm output, or user requirements into a complete specification package through a 7-phase document chain: Discovery → Requirement Clarification → Product Brief → PRD → Architecture → Epics & Stories → Readiness Check → Roadmap Generation. Outputs a validated specification package with roadmap in `.workflow/.spec/` and writes `.workflow/roadmap.md` for downstream execution.
-
-This is the heavy-path entry for structured decomposition: idea → spec-generate (spec + roadmap) → init → plan → execute.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/spec-generate.md
-</required_reading>
-
-<deferred_reading>
-- [spec-config.json](~/.maestro/templates/spec-config.json) — read when initializing spec configuration
-</deferred_reading>
-
-<context>
-$ARGUMENTS -- idea text, @file reference to requirements document, or brainstorm session reference.
-
-Flags, input types, output location, and pipeline position defined in workflow spec-generate.md.
-
-**Note:** `maestro-init` MUST run before this command. It creates the `.workflow/` directory and project context that spec-generate builds upon.
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/spec-generate.md' completely.
-
-**Next-step routing on completion:**
-- Roadmap generated, ready to plan → /maestro-plan 1
-- Need UI design first → /maestro-ui-design 1
-- Need analysis before planning → /maestro-analyze 1
-- View project dashboard → /manage-status
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Idea/topic text or @file required | Prompt user for input |
-| E002 | error | `.workflow/` not initialized (no parent dir) | Create `.workflow/` directory |
-| E003 | error | Brainstorm session not found (--from-brainstorm) | Show available sessions |
-| E004 | error | Phase 6 readiness Fail after 2 auto-fix iterations | Present manual fix options |
-| W001 | warning | CLI analysis failed, using fallback | Continue with available data |
-| W002 | warning | Codebase exploration failed | Continue without codebase context |
-| W005 | warning | External research agent failed | Continue without apiResearchContext |
-| W003 | warning | Glossary has < 5 terms | Note in readiness check |
-| W004 | warning | Review-level readiness score (60-79%) | Proceed with caveats |
-</error_codes>
-
-<success_criteria>
-- [ ] `spec-config.json` created with session metadata and phase tracking
-- [ ] `product-brief.md` with vision, goals, scope, multi-perspective synthesis
-- [ ] `glossary.json` with 5+ core terms for cross-document consistency
-- [ ] `requirements/` directory with `_index.md` + individual `REQ-*.md` + `NFR-*.md` files
-- [ ] All requirements have RFC 2119 keywords and acceptance criteria
-- [ ] `architecture/` directory with `_index.md` + individual `ADR-*.md` files
-- [ ] Architecture includes state machine, config model, error handling, observability (service type)
-- [ ] `epics/` directory with `_index.md` + individual `EPIC-*.md` files
-- [ ] Cross-Epic dependency map (Mermaid) and MVP subset tagged
-- [ ] `readiness-report.md` with 4-dimension quality scores and traceability matrix
-- [ ] `spec-summary.md` with one-page executive summary
-- [ ] All documents have valid YAML frontmatter with session_id
-- [ ] Glossary terms used consistently across all documents
-- [ ] Readiness gate: Pass (>=80%) or Review (>=60%) with documented caveats
-- [ ] `roadmap.md` generated from Epics with interactive user confirmation
-- [ ] `.workflow/roadmap.md` written (if `.workflow/` exists)
-</success_criteria>

package/.codex/skills/maestro-spec-generate/SKILL.md

@@ -1,355 +0,0 @@
----
-name: maestro-spec-generate
-description: Specification package generation via 2-wave CSV pipeline. Wave 1 runs parallel research agents (domain, competitive, tech stack). Wave 2 runs sequential 7-phase document chain using research context. Replaces maestro-spec-generate command.
-argument-hint: "\"<idea or @file>\" [-y|--yes] [--skip-research] [--from-brainstorm SESSION-ID]"
-allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
----
-
-<purpose>
-2-wave specification generation using `spawn_agents_on_csv`. Wave 1 runs parallel research agents to gather domain, competitive, and technical context. Wave 2 runs a single synthesis agent that produces the full 7-phase document chain (product brief, PRD, architecture, data model, API spec, UI wireframes, epic-to-roadmap) using Wave 1 research as context.
-
-**Core workflow**: Parse Input -> Parallel Research -> Sequential Document Chain -> Readiness Check -> Roadmap Output
-
-```
-+---------------------------------------------------------------------------+
-|                  SPEC GENERATE CSV WAVE WORKFLOW                          |
-+---------------------------------------------------------------------------+
-|                                                                           |
-|  Phase 1: Input Parsing + CSV Generation                                  |
-|     +-- Parse idea/topic from arguments                                   |
-|     +-- Detect input type (text, @file, brainstorm import)                |
-|     +-- Initialize session directory + spec-config.json                   |
-|     +-- Codebase detection (conditional exploration)                      |
-|     +-- Generate tasks.csv with research + synthesis rows                 |
-|     +-- User validates breakdown (skip if -y)                             |
-|                                                                           |
-|  Phase 2: Wave Execution Engine                                           |
-|     +-- Wave 1: Research (parallel)                                       |
-|     |   +-- Domain research agent: problem space, competitors, trends     |
-|     |   +-- Competitive analysis agent: existing solutions, gaps          |
-|     |   +-- Tech stack analysis agent: feasibility, constraints, stack    |
-|     |   +-- Discoveries shared via board (patterns, tech, domain)         |
-|     |   +-- Results: findings per research dimension                      |
-|     +-- Wave 2: Document Chain (sequential synthesis)                     |
-|     |   +-- Single agent produces 7-phase output:                         |
-|     |   |   1. Product Brief (vision, goals, scope)                       |
-|     |   |   2. PRD / Requirements (REQ-*, NFR-*)                          |
-|     |   |   3. Architecture (ADR-*, component design)                     |
-|     |   |   4. Data Model (entities, relationships)                       |
-|     |   |   5. API Specification (endpoints, contracts)                   |
-|     |   |   6. UI Wireframes (user flows, screen specs)                   |
-|     |   |   7. Epic-to-Roadmap (EPIC-*, phase mapping)                    |
-|     |   +-- Uses Wave 1 research as prev_context                          |
-|     |   +-- Generates glossary.json for terminology consistency           |
-|     +-- discoveries.ndjson shared across all waves (append-only)          |
-|                                                                           |
-|  Phase 3: Results Aggregation                                             |
-|     +-- Export results.csv                                                |
-|     +-- Run readiness check (completeness, consistency, traceability)     |
-|     +-- Generate context.md with spec summary                             |
-|     +-- Write spec package to .workflow/.spec/SPEC-{slug}-{date}/         |
-|     +-- Write .workflow/roadmap.md                                        |
-|     +-- Display summary with quality score + next steps                   |
-|                                                                           |
-+---------------------------------------------------------------------------+
-```
-</purpose>
-
-<context>
-$ARGUMENTS -- idea/topic text or @file reference, plus optional flags.
-
-**Usage**:
-
-```bash
-$maestro-spec-generate "Build a real-time collaboration platform"
-$maestro-spec-generate -y "@requirements.md"
-$maestro-spec-generate --skip-research "CLI workflow orchestration tool"
-$maestro-spec-generate --from-brainstorm WFS-001 "Enhance auth system"
-```
-
-**Flags**:
-- `-y, --yes`: Skip all confirmations (auto mode)
-- `--skip-research`: Skip Wave 1 research, jump directly to document generation
-- `--from-brainstorm SESSION-ID`: Import guidance-specification.md from brainstorm session as seed
-
-When `--yes` or `-y`: Auto-confirm all interactive decisions, skip requirement clarification rounds, use recommended defaults for spec type and depth.
-
-**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) + spec package in `.workflow/.spec/SPEC-{slug}-{date}/`
-</context>
-
-<csv_schema>
-
-### tasks.csv (Master State)
-
-```csv
-id,title,description,research_focus,doc_phase,deps,context_from,wave,status,findings,output_file,error
-"1","Domain Research","Research the problem domain: identify target users, market needs, existing solutions, industry trends, and domain terminology. Produce structured findings with confidence levels.","domain","","","","1","","","",""
-"2","Competitive Analysis","Analyze competing products and approaches: feature comparison matrix, UX patterns, pricing models, market positioning. Identify gaps and opportunities for differentiation.","competitive","","","","1","","","",""
-"3","Tech Stack Analysis","Evaluate technical feasibility: recommended languages, frameworks, databases, infrastructure. Assess constraints, integration complexity, scalability requirements. Reference existing codebase if available.","tech_stack","","","","1","","","",""
-"4","Document Chain","Generate complete 7-phase specification package using research context. Phases: (1) Product Brief with vision/goals/scope, (2) PRD with REQ-*/NFR-* requirements, (3) Architecture with ADR-* decisions, (4) Data Model with entity relationships, (5) API Specification with endpoint contracts, (6) UI Wireframes with user flows, (7) Epic-to-Roadmap with EPIC-* and phase mapping. Produce glossary.json for terminology consistency across all documents.","","1-7","1;2;3","1;2;3","2","","","",""
-```
-
-**Columns**:
-
-| Column | Phase | Description |
-|--------|-------|-------------|
-| `id` | Input | Unique task identifier (string) |
-| `title` | Input | Short task title |
-| `description` | Input | Detailed instructions for this task |
-| `research_focus` | Input | Research dimension: domain/competitive/tech_stack (Wave 1 only) |
-| `doc_phase` | Input | Document phase range: "1-7" (Wave 2 only, empty for research) |
-| `deps` | Input | Semicolon-separated dependency task IDs |
-| `context_from` | Input | Semicolon-separated task IDs whose findings this task needs |
-| `wave` | Computed | Wave number (1 = research, 2 = document chain) |
-| `status` | Output | `pending` -> `completed` / `failed` / `skipped` |
-| `findings` | Output | Key findings summary (max 500 chars) |
-| `output_file` | Output | Path to generated output file(s), semicolon-separated |
-| `error` | Output | Error message if failed |
-
-### Per-Wave CSV (Temporary)
-
-Each wave generates `wave-{N}.csv` with extra `prev_context` column.
-</csv_schema>
-
-<invariants>
-1. **Start Immediately**: First action is session initialization, then Phase 1
-2. **Wave Order is Sacred**: Never execute wave 2 before wave 1 completes and results are merged
-3. **CSV is Source of Truth**: Master tasks.csv holds all state
-4. **Context Propagation**: prev_context built from master CSV, not from memory
-5. **Discovery Board is Append-Only**: Never clear, modify, or recreate discoveries.ndjson
-6. **Graceful Degradation**: If research fails, document chain proceeds with seed input only
-7. **Cleanup Temp Files**: Remove wave-{N}.csv after results are merged
-8. **DO NOT STOP**: Continuous execution until all waves complete
-</invariants>
-
-<execution>
-
-### 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) | Created before wave, deleted after |
-| `results.csv` | Final export of all task results | Created in Phase 3 |
-| `discoveries.ndjson` | Shared exploration board | Append-only, carries across waves |
-| `context.md` | Human-readable spec generation report | Created in Phase 3 |
-| `spec-config.json` | Session metadata and phase tracking | Created in Phase 1 |
-
-### Session Structure
-
-```
-.workflow/.csv-wave/{YYYYMMDD}-spec-generate-{slug}/
-+-- tasks.csv
-+-- results.csv
-+-- discoveries.ndjson
-+-- context.md
-+-- spec-config.json
-+-- wave-{N}.csv (temporary)
-```
-
-**Spec package output**:
-```
-.workflow/.spec/SPEC-{slug}-{date}/
-+-- spec-config.json
-+-- product-brief.md
-+-- glossary.json
-+-- requirements/
-|   +-- _index.md
-|   +-- REQ-NNN-{slug}.md
-|   +-- NFR-{type}-NNN-{slug}.md
-+-- architecture/
-|   +-- _index.md
-|   +-- ADR-NNN-{slug}.md
-+-- epics/
-|   +-- _index.md
-|   +-- EPIC-NNN-{slug}.md
-+-- readiness-report.md
-+-- spec-summary.md
-+-- roadmap.md
-```
-
-### Session Initialization
-
-Parse `$ARGUMENTS` to extract:
-- `AUTO_YES` from `--yes` / `-y`
-- `skipResearch` from `--skip-research`
-- `brainstormSession` from `--from-brainstorm <SESSION-ID>`
-- `topicArg` = remaining text after stripping all flags
-- `slug` = topicArg lowercased, non-alphanumeric → `-`, max 40 chars
-
-Session ID: `{YYYYMMDD}-spec-generate-{slug}`
-Session folder: `.workflow/.csv-wave/{sessionId}/` — create via `mkdir -p`
-
-### Phase 1: Input Parsing + CSV Generation
-
-**Objective**: Parse input, detect type, initialize session, generate tasks.csv.
-
-**Decomposition Rules**:
-
-1. **Input parsing**: Parse `{topicArg}` -- direct text, `@file` reference, or brainstorm import
-2. **Brainstorm import**: If `--from-brainstorm`, read `guidance-specification.md` as enriched seed
-3. **Codebase detection**: Check for source files (*.ts, *.js, *.py); if found, add codebase context to research prompts
-4. **Session init**: Create `spec-config.json` with session metadata
-
-5. **CSV generation**:
-
-| Condition | Wave 1 Tasks | Wave 2 Tasks |
-|-----------|-------------|-------------|
-| Normal | 3 research agents | 1 document chain agent |
-| `--skip-research` | 0 (skipped) | 1 document chain agent (wave 1) |
-| `--from-brainstorm` | 3 research agents (enriched) | 1 document chain agent |
-
-6. **Wave computation**: Simple 2-wave -- all research tasks = wave 1, document chain = wave 2.
-
-**User validation**: Display task breakdown (skip if AUTO_YES).
-
-### Phase 2: Wave Execution Engine
-
-**Objective**: Execute research and document generation wave-by-wave via spawn_agents_on_csv.
-
-#### Wave 1: Research (Parallel)
-
-Filter master `tasks.csv` for `wave == 1 AND status == pending` → write `wave-1.csv` (no prev_context needed).
-
-```javascript
-spawn_agents_on_csv({
-  csv_path: `${sessionFolder}/wave-1.csv`,
-  id_column: "id",
-  instruction: buildResearchInstruction(sessionFolder, topicArg),
-  max_concurrency: 3,
-  max_runtime_seconds: 3600,
-  output_csv_path: `${sessionFolder}/wave-1-results.csv`,
-  output_schema: {
-    type: "object",
-    properties: {
-      id: { type: "string" },
-      status: { type: "string", enum: ["completed", "failed"] },
-      findings: { type: "string" },
-      output_file: { type: "string" },
-      error: { type: "string" }
-    },
-    required: ["id", "status", "findings"]
-  }
-})
-```
-
-Merge `wave-1-results.csv` into master `tasks.csv`, delete `wave-1.csv`.
-
-#### Wave 2: Document Chain (Sequential)
-
-Filter master `tasks.csv` for `wave == 2 AND status == pending`. If all wave 1 tasks failed, use degraded mode (basic seed only).
-
-Build `prev_context` from wave 1 findings (format: `[Task N: Title] summary...` per task).
-Write `wave-2.csv` with `prev_context` column → execute `spawn_agents_on_csv` → merge results → delete `wave-2.csv`.
-
-### Phase 3: Results Aggregation
-
-**Objective**: Generate final results, readiness check, and write spec package.
-
-Export master `tasks.csv` as `results.csv`. **Readiness check** -- score on 4 dimensions (25% each):
-   - Completeness: all required documents generated with substantive content
-   - Consistency: glossary terms used uniformly, scope containment
-   - Traceability: goals -> requirements -> architecture -> epics chain
-   - Depth: acceptance criteria testable, ADRs justified, stories estimable
-
-**Gate decision**:
-
-| Score | Gate | Action |
-|-------|------|--------|
-| >= 80% | Pass | Proceed to output |
-| 60-79% | Review | Proceed with caveats logged |
-| < 60% | Fail | Log issues, proceed with available output |
-
-Generate `context.md`:
-
-```markdown
-# Spec Generate Report
-
-## Summary
-- Topic: {topic}
-- Research agents: {research_count} ({completed_count} completed)
-- Document phases: 7
-- Quality score: {score}% ({gate})
-
-## Research Findings
-### Domain Research
-{findings}
-
-### Competitive Analysis
-{findings}
-
-### Tech Stack Analysis
-{findings}
-
-## Document Chain Output
-- Product Brief: {status}
-- Requirements: {req_count} REQs + {nfr_count} NFRs
-- Architecture: {adr_count} ADRs
-- Epics: {epic_count} Epics
-- Roadmap: {phase_count} phases
-
-## Readiness
-- Completeness: {score}%
-- Consistency: {score}%
-- Traceability: {score}%
-- Depth: {score}%
-- Overall: {score}% ({gate})
-```
-
-Write spec package to `.workflow/.spec/SPEC-{slug}-{date}/`, write `.workflow/roadmap.md`, display summary.
-
-### Shared Discovery Board Protocol
-
-#### Standard Discovery Types
-
-| Type | Dedup Key | Data Schema | Description |
-|------|-----------|-------------|-------------|
-| `code_pattern` | `data.name` | `{name, file, description}` | Reusable code pattern found |
-| `integration_point` | `data.file` | `{file, description, exports[]}` | Module connection point |
-| `convention` | singleton | `{naming, imports, formatting}` | Project code conventions |
-| `tech_stack` | singleton | `{framework, language, tools[]}` | Technology stack info |
-
-#### Domain Discovery Types
-
-| Type | Dedup Key | Data Schema | Description |
-|------|-----------|-------------|-------------|
-| `domain_term` | `data.term` | `{term, definition, aliases}` | Domain terminology |
-| `competitor` | `data.name` | `{name, features[], gaps[]}` | Competitive product |
-| `market_trend` | `data.name` | `{name, impact, relevance}` | Market trend |
-| `tech_constraint` | `data.name` | `{name, type, severity, mitigation}` | Technical constraint |
-
-#### Protocol
-
-Read `{session_folder}/discoveries.ndjson` before own analysis. Deduplicate by type + dedup key before writing. Append-only — never modify or delete.
-
-```bash
-echo '{"ts":"<ISO>","worker":"{id}","type":"domain_term","data":{"term":"workflow","definition":"A sequence of orchestrated tasks","aliases":["pipeline","process"]}}' >> {session_folder}/discoveries.ndjson
-```
-</execution>
-
-<error_codes>
-| Error | Resolution |
-|-------|------------|
-| No idea/topic provided | Abort with error: "Idea or topic text required" |
-| Brainstorm session not found | Abort with error: "Session {id} not found" -- list available sessions |
-| @file not found | Abort with error: "File {path} not found" |
-| Research agent timeout | Mark as failed, document chain uses available findings |
-| All research agents failed | Document chain runs in degraded mode (seed only) |
-| Document chain agent failed | Export partial output, log quality issues |
-| CSV parse error | Validate format, show line number |
-| discoveries.ndjson corrupt | Ignore malformed lines |
-| Readiness score < 60% | Log issues, proceed with available output |
-</error_codes>
-
-<success_criteria>
-- [ ] Input parsed from text, @file, or brainstorm session
-- [ ] Session initialized with spec-config.json and tasks.csv
-- [ ] Wave 1 research agents completed (domain, competitive, tech stack)
-- [ ] Wave 2 document chain produced 7-phase spec package
-- [ ] Readiness check scored on completeness, consistency, traceability, depth
-- [ ] Spec package written to .workflow/.spec/SPEC-{slug}-{date}/
-- [ ] .workflow/roadmap.md written
-- [ ] context.md generated with research and spec summary
-- [ ] Completion report displayed with quality score and next steps
-</success_criteria>