maestro-flow 0.1.0

package/.codex/skills/spec-add/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: maestro-spec-add
+description: Add a spec entry (bug, pattern, decision, or rule) to the appropriate specs file
+argument-hint: "<type> <content>"
+allowed-tools: Read, Write, Bash, Glob, Grep
+---
+
+# Spec Add
+
+## Usage
+
+```bash
+$maestro-spec-add "pattern Always use named exports for utility functions"
+$maestro-spec-add "bug Off-by-one in pagination when page=0"
+$maestro-spec-add "decision Use Zod for runtime validation over io-ts"
+$maestro-spec-add "rule All API endpoints must return structured error objects"
+```
+
+**Arguments**: `<type> <content>` where type is one of: bug, pattern, decision, rule, debug, test, review, validation.
+
+---
+
+## Implementation
+
+### Step 1: Parse Input
+
+Extract type (first token) and content (remainder) from arguments.
+- Validate type is one of: bug, pattern, decision, rule, debug, test, review, validation (E003 if invalid)
+- Validate content is non-empty (E001 if missing)
+
+### Step 2: Validate Specs Directory
+
+```bash
+test -d .workflow/specs || exit 1  # E002: not initialized
+```
+
+### Step 3: Route to File
+
+| Type | Primary File | Secondary Update |
+|------|-------------|-----------------|
+| `bug` | `learnings.md` | -- |
+| `pattern` | `learnings.md` | `coding-conventions.md` |
+| `decision` | `learnings.md` | `architecture-constraints.md` |
+| `rule` | `learnings.md` | `quality-rules.md` |
+| `debug` | `learnings.md` | `debug-notes.md` |
+| `test` | `learnings.md` | `test-conventions.md` |
+| `review` | `learnings.md` | `review-standards.md` |
+| `validation` | `learnings.md` | `validation-rules.md` |
+
+### Step 4: Append Entry
+
+Append timestamped entry to `.workflow/specs/learnings.md` using the unified `[type] [date]` format:
+
+```markdown
+### [{type}] [{YYYY-MM-DD}] {first line of content}
+
+{content}
+```
+
+Example: `### [bug] [2026-03-21] Off-by-one in pagination when page=0`
+
+If type has a secondary file, also update that file with the new convention/rule/decision.
+
+### Step 5: Confirm
+
+```
+Added [{type}] to learnings.md
+{Secondary file updated if applicable}
+```
+
+---
+
+## Error Handling
+
+| Code | Severity | Description |
+|------|----------|-------------|
+| E001 | fatal | Category and content are both required |
+| E002 | fatal | `.workflow/specs/` not initialized -- run `Skill({ skill: "spec-setup" })` first |
+| E003 | fatal | Invalid category -- must be one of: bug, pattern, decision, rule, debug, test, review, validation |

package/.codex/skills/spec-load/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: maestro-spec-load
+description: Load relevant specs for current context, optionally filtered by category or keyword
+argument-hint: "[--category <type>] [keyword]"
+allowed-tools: Read, Bash, Glob, Grep
+---
+
+# Spec Load
+
+## Usage
+
+```bash
+$maestro-spec-load
+$maestro-spec-load "--category execution"
+$maestro-spec-load "authentication"
+$maestro-spec-load "--category debug error handling"
+```
+
+**Flags**: `--category <type>` filters by spec category. Optional keyword searches within loaded files.
+
+---
+
+## Implementation
+
+### Step 1: Validate Specs Directory
+
+```bash
+test -d .workflow/specs || exit 1  # E001: not initialized
+```
+
+### Step 2: Parse Arguments
+
+Extract optional `--category` flag and keyword from arguments.
+
+**Category-to-file mapping:**
+
+| Category | Files Loaded |
+|----------|-------------|
+| `general` | `learnings.md` |
+| `planning` | `architecture-constraints.md` |
+| `execution` | `coding-conventions.md`, `quality-rules.md` |
+| `debug` | `debug-notes.md` |
+| `test` | `test-conventions.md` |
+| `review` | `review-standards.md` |
+| `validation` | `validation-rules.md` |
+| `all` (default) | All spec files |
+
+### Step 3: Load Files
+
+Read the spec files matching the category filter.
+If no files exist for the category, fall back to loading all specs.
+
+### Step 4: Apply Keyword Filter
+
+If a keyword is provided, search within loaded files for matching sections using grep.
+Return only matching sections with file:line references.
+If no matches found, show all content in the category (W001).
+
+### Step 5: Display Results
+
+```
+=== SPECS: {category} ===
+{For each file}
+--- {filename} ---
+{content or matching sections}
+```
+
+---
+
+## Error Handling
+
+| Code | Severity | Description |
+|------|----------|-------------|
+| E001 | fatal | `.workflow/specs/` not initialized -- run `Skill({ skill: "spec-setup" })` first |
+| W001 | warning | No matching specs for keyword -- showing all in category |

package/.codex/skills/spec-map/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: maestro-spec-map
+description: Analyze codebase with 4 parallel mapper agents via CSV wave pipeline. Produces .workflow/codebase/ documents for tech-stack, architecture, features, and cross-cutting concerns.
+argument-hint: "[-y|--yes] [-c|--concurrency 4] [--continue] \"[focus area]\""
+allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+## Auto Mode
+
+When `--yes` or `-y`: Auto-confirm mapper assignment, skip validation.
+
+# Maestro Spec Map (CSV Wave)
+
+## Usage
+
+```bash
+$maestro-spec-map ""
+$maestro-spec-map "auth"
+$maestro-spec-map -c 4 "api layer"
+$maestro-spec-map --continue "map-auth-20260318"
+```
+
+**Flags**:
+- `-y, --yes`: Skip all confirmations
+- `-c, --concurrency N`: Max concurrent agents (default: 4)
+- `--continue`: Resume existing session
+
+**Output**: `.workflow/codebase/` (tech-stack.md, architecture.md, features.md, concerns.md)
+
+---
+
+## Overview
+
+Single-wave parallel execution — 4 independent mapper agents each analyze a different codebase dimension. No dependencies between tasks, maximum parallelism.
+
+**Topology**: Independent Parallel (single wave)
+
+```
+┌──────────────────────────────────────────────────────┐
+│               CODEBASE MAPPER WORKFLOW                 │
+├──────────────────────────────────────────────────────┤
+│                                                        │
+│  Phase 1: Setup → CSV                                  │
+│     ├─ Detect focus area from arguments                │
+│     ├─ Generate tasks.csv with 4 mapper tasks          │
+│     └─ All tasks wave 1 (no dependencies)              │
+│                                                        │
+│  Phase 2: Wave Execution (Single Wave)                 │
+│     ├─ Wave 1: All 4 mappers run concurrently          │
+│     │   ├─ Tech Stack mapper                           │
+│     │   ├─ Architecture mapper                         │
+│     │   ├─ Features mapper                             │
+│     │   └─ Cross-cutting Concerns mapper               │
+│     └─ discoveries.ndjson shared (append-only)         │
+│                                                        │
+│  Phase 3: Results → .workflow/codebase/                 │
+│     ├─ Write output files from agent findings          │
+│     ├─ Generate context.md summary                     │
+│     └─ Display completion report                       │
+│                                                        │
+└──────────────────────────────────────────────────────┘
+```
+
+---
+
+## CSV Schema
+
+### tasks.csv
+
+```csv
+id,title,description,focus_area,output_file,deps,context_from,wave,status,findings,error
+"1","Tech Stack Analysis","Analyze languages, frameworks, dependencies, build system, package managers, runtime configuration. Scan package.json, build configs, CI/CD files.","full","tech-stack.md","","","1","","",""
+"2","Architecture Analysis","Analyze project structure, module boundaries, layer architecture, data flow patterns, entry points, API surface. Map directory tree and import graph.","full","architecture.md","","","1","","",""
+"3","Features Analysis","Inventory user-facing capabilities, API endpoints, CLI commands, UI components, background jobs, integrations. Map to source locations.","full","features.md","","","1","","",""
+"4","Cross-cutting Concerns","Analyze error handling patterns, logging strategy, authentication/authorization, configuration management, testing approach, observability.","full","concerns.md","","","1","","",""
+```
+
+**Columns**:
+
+| Column | Phase | Description |
+|--------|-------|-------------|
+| `id` | Input | Mapper identifier |
+| `title` | Input | Mapper dimension title |
+| `description` | Input | Detailed analysis instructions |
+| `focus_area` | Input | Focus scope (full or specific area) |
+| `output_file` | Input | Target output filename in .workflow/codebase/ |
+| `deps` | Input | Empty (all independent) |
+| `context_from` | Input | Empty (no cross-task context) |
+| `wave` | Computed | Always 1 (single wave) |
+| `status` | Output | pending/completed/failed/skipped |
+| `findings` | Output | Analysis summary (max 500 chars) |
+| `error` | Output | Error if failed |
+
+---
+
+## Implementation
+
+### Session Initialization
+
+```javascript
+const AUTO_YES = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
+const focusArea = $ARGUMENTS.replace(/--yes|-y|--continue|--concurrency\s+\d+|-c\s+\d+/g, '').trim() || 'full'
+const dateStr = new Date(Date.now() + 8*60*60*1000).toISOString().substring(0,10).replace(/-/g,'')
+const sessionId = `map-${focusArea.substring(0,20)}-${dateStr}`
+const sessionFolder = `.workflow/.csv-wave/${sessionId}`
+
+Bash(`mkdir -p ${sessionFolder}`)
+Bash(`mkdir -p .workflow/codebase`)
+```
+
+### Phase 1: Generate tasks.csv
+
+Generate 4 mapper rows. If focus_area is specified, scope descriptions to that area.
+
+### Phase 2: Wave Execution
+
+Single wave — all 4 mappers run concurrently:
+
+```javascript
+spawn_agents_on_csv({
+  csv_path: `${sessionFolder}/wave-1.csv`,
+  id_column: "id",
+  instruction: buildMapperInstruction(sessionFolder, focusArea),
+  max_concurrency: 4,
+  max_runtime_seconds: 600,
+  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" },
+      error: { type: "string" }
+    },
+    required: ["id", "status", "findings"]
+  }
+})
+```
+
+### Phase 3: Write Output Files
+
+1. Read each agent's findings from results
+2. Write to `.workflow/codebase/{output_file}`
+3. Generate context.md summary
+4. Display report
+
+---
+
+## Shared Discovery Board Protocol
+
+Discovery types particularly valuable for mapper agents:
+
+| Type | Dedup Key | Data Schema |
+|------|-----------|-------------|
+| `tech_stack` | singleton | `{framework, language, tools[]}` |
+| `code_pattern` | `data.name` | `{name, file, description}` |
+| `integration_point` | `data.file` | `{file, description, exports[]}` |
+| `convention` | singleton | `{naming, imports, formatting}` |
+
+Mappers share discoveries so other mappers can skip redundant exploration (e.g., if tech-stack mapper discovers the framework, features mapper can focus on feature-level analysis).
+
+---
+
+## Error Handling
+
+| Error | Resolution |
+|-------|------------|
+| No source files found | Abort: "No source files in project" |
+| Mapper agent timeout | Mark failed, continue with other mappers |
+| Mapper agent failed | Mark failed, output partial results |
+| .workflow/codebase/ exists | Prompt: refresh/skip/merge (auto-refresh with -y) |
+
+---
+
+## Core Rules
+
+1. **Start Immediately**: Initialize session, generate CSV, execute
+2. **CSV is Source of Truth**: tasks.csv holds all mapper state
+3. **Discovery Board is Append-Only**: Mappers share findings
+4. **Partial Results OK**: If 3/4 mappers succeed, still write available docs
+5. **Focus Area Scoping**: When focus is specified, descriptions narrow to that area
+6. **DO NOT STOP**: Execute until all mappers complete or fail

package/.codex/skills/spec-setup/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: maestro-spec-setup
+description: Initialize project specs by scanning codebase for conventions and tech stack
+argument-hint: ""
+allowed-tools: Read, Write, Bash, Glob, Grep
+---
+
+# Spec Setup
+
+## Usage
+
+```bash
+$maestro-spec-setup
+```
+
+No arguments. Scans the codebase and generates spec files in `.workflow/specs/`.
+
+---
+
+## Implementation
+
+### Step 1: Validate Preconditions
+
+```bash
+test -d .workflow || exit 1  # E001: not initialized
+```
+
+Verify project contains source files to scan (E002 if empty).
+
+### Step 2: Scan Codebase
+
+Detect conventions and tech stack by scanning:
+- Package files (`package.json`, `Cargo.toml`, `go.mod`, etc.)
+- Config files (`.eslintrc`, `tsconfig.json`, `.prettierrc`, etc.)
+- Source structure (directories, naming patterns, import style)
+- Test patterns (framework, naming, location)
+
+### Step 3: Generate Spec Files
+
+Create `.workflow/specs/` directory and write:
+
+1. **`coding-conventions.md`** -- Detected naming, import, formatting patterns
+2. **`architecture-constraints.md`** -- Structural rules, layer boundaries
+3. **`quality-rules.md`** -- Linting, testing, coverage requirements
+4. **`learnings.md`** -- Initialized with format instructions for future entries
+
+### Step 4: Generate Tech Profile
+
+Read template from `~/.maestro/templates/project-tech.json` if available.
+Write `.workflow/project-tech.json` with detected tech stack:
+- Language, framework, build system, test framework
+- Key dependencies, module system, TypeScript config
+
+### Step 5: Display Report
+
+```
+=== SPEC SETUP COMPLETE ===
+Created:
+  - .workflow/specs/coding-conventions.md
+  - .workflow/specs/architecture-constraints.md
+  - .workflow/specs/quality-rules.md
+  - .workflow/specs/learnings.md
+  - .workflow/project-tech.json
+
+Next: Run Skill({ skill: "spec-add", args: "<type> <content>" }) to add entries
+```
+
+---
+
+## Error Handling
+
+| Code | Severity | Description |
+|------|----------|-------------|
+| E001 | fatal | `.workflow/` not initialized -- run `Skill({ skill: "maestro-init" })` first |
+| E002 | fatal | No source files found in project |
+| W001 | warning | Convention detection uncertain -- marked `[UNCERTAIN]` |