maestro-flow 0.1.1 → 0.1.3

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

@@ -1,75 +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 |
+---
+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

@@ -1,182 +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
+---
+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

@@ -1,76 +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]` |
+---
+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]` |