maestro-flow 0.3.10 → 0.3.11

package/workflows/map.md

@@ -1,111 +1,111 @@
-# Workflow: map
-
-Codebase scanning with parallel mapper agents.
-
----
-
-## Step 1: Pre-check
-
-1. Check if `.workflow/research/` already exists with documents:
-   - If documents exist and are recent (< 7 days):
-     - Ask user: "Codebase map exists. Refresh or skip?"
-     - "refresh" → continue to Step 2 (overwrite)
-     - "skip" → exit with route suggestions
-   - If documents are stale or missing → continue to Step 2
-
-2. Create `.workflow/research/` directory if it does not exist.
-
----
-
-## Step 2: Spawn Parallel Mapper Agents
-
-Spawn 4 parallel `workflow-codebase-mapper` agents. Each agent scans the codebase independently with a specific focus and writes its output directly to `.workflow/research/`.
-
-```
-Agent 1: tech focus
-  Scan: package.json, go.mod, requirements.txt, build files, dependencies
-  Output: .workflow/research/STACK.md
-  Content: languages, frameworks, build tools, key dependencies, versions
-
-Agent 2: arch focus
-  Scan: directory structure, module boundaries, entry points, data flow
-  Output: .workflow/research/ARCHITECTURE.md
-  Content: architecture style, layer separation, module graph, key abstractions
-
-Agent 3: features focus
-  Scan: routes, handlers, components, services, models
-  Output: .workflow/research/FEATURES.md
-  Content: feature inventory, feature-to-file mapping, completeness assessment
-
-Agent 4: concerns focus
-  Scan: error handling, logging, tests, config, security, performance
-  Output: .workflow/research/PITFALLS.md
-  Content: tech debt, missing tests, security gaps, performance concerns, known issues
-```
-
-If `$ARGUMENTS` (focus area) is provided, pass it to each agent as a focus filter: "Prioritize analysis of {focus_area} subsystem."
-
-**Load project specs for mapper context:**
-```
-specs_content = maestro spec load --category planning
-```
-
-**Agent spawn pattern:**
-```
-For each agent (1-4) in parallel:
-  Agent({
-    subagent_type: "workflow-codebase-mapper",
-    prompt: "Focus: {focus}. Scan the codebase and write {output_file}.
-             Project specs for reference: ${specs_content}
-             Write directly to the file. Return only a confirmation with line count.",
-    run_in_background: false
-  })
-```
-
----
-
-## Step 3: Verification
-
-After all 4 agents complete:
-
-1. Verify all documents exist with content:
-   ```
-   .workflow/research/STACK.md         — exists, >10 lines
-   .workflow/research/ARCHITECTURE.md  — exists, >10 lines
-   .workflow/research/FEATURES.md      — exists, >10 lines
-   .workflow/research/PITFALLS.md      — exists, >10 lines
-   ```
-
-2. If any document is missing or empty:
-   - Log which agent failed
-   - Re-spawn that specific agent (max 1 retry per agent)
-
----
-
-## Step 4: Summary
-
-1. Create `.workflow/research/SUMMARY.md`:
-   - Read all 4 documents
-   - Write a consolidated executive summary covering:
-     - Tech stack overview (from STACK.md)
-     - Architecture highlights (from ARCHITECTURE.md)
-     - Feature inventory count (from FEATURES.md)
-     - Top 3 concerns (from PITFALLS.md)
-     - Recommendations for next steps
-
----
-
-## Step 5: Commit and Route
-
-1. If git repo: commit `.workflow/research/` with message `"chore: map codebase"`
-
-2. Display summary:
-   ```
-   Codebase mapped successfully.
-   Documents: 5 files in .workflow/research/
-   ```
-
-3. Route next steps based on project state:
-   - No `.workflow/state.json` → "Run `/workflow:init` to initialize project"
-   - Has state, no roadmap → "Run `/workflow:init` to create roadmap"
-   - Has roadmap → "Run `/workflow:plan {next_phase}` to start planning"
+# Workflow: map
+
+Codebase scanning with parallel mapper agents.
+
+---
+
+## Step 1: Pre-check
+
+1. Check if `.workflow/research/` already exists with documents:
+   - If documents exist and are recent (< 7 days):
+     - Ask user: "Codebase map exists. Refresh or skip?"
+     - "refresh" → continue to Step 2 (overwrite)
+     - "skip" → exit with route suggestions
+   - If documents are stale or missing → continue to Step 2
+
+2. Create `.workflow/research/` directory if it does not exist.
+
+---
+
+## Step 2: Spawn Parallel Mapper Agents
+
+Spawn 4 parallel `workflow-codebase-mapper` agents. Each agent scans the codebase independently with a specific focus and writes its output directly to `.workflow/research/`.
+
+```
+Agent 1: tech focus
+  Scan: package.json, go.mod, requirements.txt, build files, dependencies
+  Output: .workflow/research/STACK.md
+  Content: languages, frameworks, build tools, key dependencies, versions
+
+Agent 2: arch focus
+  Scan: directory structure, module boundaries, entry points, data flow
+  Output: .workflow/research/ARCHITECTURE.md
+  Content: architecture style, layer separation, module graph, key abstractions
+
+Agent 3: features focus
+  Scan: routes, handlers, components, services, models
+  Output: .workflow/research/FEATURES.md
+  Content: feature inventory, feature-to-file mapping, completeness assessment
+
+Agent 4: concerns focus
+  Scan: error handling, logging, tests, config, security, performance
+  Output: .workflow/research/PITFALLS.md
+  Content: tech debt, missing tests, security gaps, performance concerns, known issues
+```
+
+If `$ARGUMENTS` (focus area) is provided, pass it to each agent as a focus filter: "Prioritize analysis of {focus_area} subsystem."
+
+**Load project specs for mapper context:**
+```
+specs_content = maestro spec load --category arch
+```
+
+**Agent spawn pattern:**
+```
+For each agent (1-4) in parallel:
+  Agent({
+    subagent_type: "workflow-codebase-mapper",
+    prompt: "Focus: {focus}. Scan the codebase and write {output_file}.
+             Project specs for reference: ${specs_content}
+             Write directly to the file. Return only a confirmation with line count.",
+    run_in_background: false
+  })
+```
+
+---
+
+## Step 3: Verification
+
+After all 4 agents complete:
+
+1. Verify all documents exist with content:
+   ```
+   .workflow/research/STACK.md         — exists, >10 lines
+   .workflow/research/ARCHITECTURE.md  — exists, >10 lines
+   .workflow/research/FEATURES.md      — exists, >10 lines
+   .workflow/research/PITFALLS.md      — exists, >10 lines
+   ```
+
+2. If any document is missing or empty:
+   - Log which agent failed
+   - Re-spawn that specific agent (max 1 retry per agent)
+
+---
+
+## Step 4: Summary
+
+1. Create `.workflow/research/SUMMARY.md`:
+   - Read all 4 documents
+   - Write a consolidated executive summary covering:
+     - Tech stack overview (from STACK.md)
+     - Architecture highlights (from ARCHITECTURE.md)
+     - Feature inventory count (from FEATURES.md)
+     - Top 3 concerns (from PITFALLS.md)
+     - Recommendations for next steps
+
+---
+
+## Step 5: Commit and Route
+
+1. If git repo: commit `.workflow/research/` with message `"chore: map codebase"`
+
+2. Display summary:
+   ```
+   Codebase mapped successfully.
+   Documents: 5 files in .workflow/research/
+   ```
+
+3. Route next steps based on project state:
+   - No `.workflow/state.json` → "Run `/workflow:init` to initialize project"
+   - Has state, no roadmap → "Run `/workflow:init` to create roadmap"
+   - Has roadmap → "Run `/workflow:plan {next_phase}` to start planning"

package/workflows/milestone-complete.md

@@ -1,176 +1,176 @@
-# Workflow: milestone-complete
-
-Archive completed milestone, move artifacts to history, and prepare for next.
-
----
-
-## Step 1: Validation
-
-1. Read `.workflow/state.json`:
-   - Determine target milestone (from $ARGUMENTS or current_milestone)
-   - If no milestone: ERROR E001
-
-2. Check milestone audit status:
-   - Read `.workflow/milestones/{milestone}/audit-report.md` if exists
-   - If no audit report:
-     - WARN: "No audit report found. Run `/maestro-milestone-audit` first."
-     - Ask user: "Complete without audit?"
-     - If NO → exit
-   - If verdict is FAIL: ERROR E002
-
-3. Verify all artifacts completed:
-   ```
-   milestone_artifacts = state.json.artifacts.filter(a => a.milestone == target_milestone)
-   incomplete = milestone_artifacts.filter(a => a.status != "completed")
-   IF incomplete.length > 0:
-     ERROR E003: "Incomplete artifacts: {list ids and statuses}"
-   ```
-
----
-
-## Step 2: Create Milestone Archive
-
-1. Create archive directory:
-   ```
-   mkdir -p .workflow/milestones/{milestone}/artifacts/
-   ```
-
-2. Snapshot roadmap:
-   ```
-   cp .workflow/roadmap.md .workflow/milestones/{milestone}/roadmap-snapshot.md
-   ```
-
-3. Archive scratch directories:
-   ```
-   FOR each artifact IN milestone_artifacts:
-     IF directory exists at .workflow/{artifact.path}:
-       cp -r .workflow/{artifact.path} .workflow/milestones/{milestone}/artifacts/{basename}/
-   ```
-
----
-
-## Step 2.5: Load Existing Learnings
-
-```
-existing_learnings = maestro spec load --category general
-```
-
-Check existing entries to avoid duplicates when appending in Step 3.
-
----
-
-## Step 3: Extract Learnings
-
-1. For each execute artifact, read `.summaries/` and `reflection-log.md` if exists:
-   - Extract strategy adjustments
-   - Extract patterns discovered
-   - Extract pitfalls encountered
-
-2. Aggregate learnings and append to `.workflow/specs/learnings.md`:
-   ```
-   For each strategy adjustment:
-     ### [YYYY-MM-DD HH:mm] decision: {summary}
-     {content}
-     Milestone: {milestone} | Source: milestone-complete
-
-   For each pattern:
-     ### [YYYY-MM-DD HH:mm] pattern: {summary}
-     {content}
-     Milestone: {milestone} | Source: milestone-complete
-
-   For each pitfall:
-     ### [YYYY-MM-DD HH:mm] bug: {summary}
-     {content}
-     Milestone: {milestone} | Source: milestone-complete
-   ```
-
----
-
-## Step 4: Update State
-
-1. Archive artifact entries to milestone_history:
-   ```json
-   {
-     "milestone_history": [
-       {
-         "id": "{milestone}",
-         "name": "{milestone_name}",
-         "status": "completed",
-         "completed_at": "{now}",
-         "archive_path": "milestones/{milestone}/",
-         "archived_artifacts": [ ...all milestone artifacts entries... ]
-       }
-     ]
-   }
-   ```
-
-2. Clear artifacts array (remove milestone-affiliated entries):
-   ```
-   state.json.artifacts = state.json.artifacts.filter(a => a.milestone != target_milestone)
-   ```
-
-3. Advance to next milestone:
-   ```
-   next_milestone = state.json.milestones.find(m => m.status == "pending")
-   IF next_milestone:
-     state.json.current_milestone = next_milestone.id
-     next_milestone.status = "active"
-   ELSE:
-     state.json.current_milestone = null
-     state.json.status = "completed"
-   ```
-
-4. Write state.json (atomic)
-
----
-
-## Step 5: Clean Scratch
-
-Remove archived scratch directories:
-```
-FOR each artifact IN archived_artifacts:
-  IF directory exists at .workflow/{artifact.path}:
-    rm -rf .workflow/{artifact.path}
-```
-
----
-
-## Step 6: Generate Summary
-
-Write `.workflow/milestones/{milestone}/summary.md`:
-```markdown
-# Milestone: {milestone} — {name}
-
-**Completed**: {date}
-**Artifacts**: {count} (analyze: {n}, plan: {n}, execute: {n}, verify: {n})
-
-## Key Outcomes
-{extracted from audit report + learnings}
-
-## Learnings
-{top patterns and pitfalls}
-
-## Next Milestone
-{next milestone name and first phase, or "Project complete"}
-```
-
-Update `.workflow/project.md` Context section with milestone summary.
-
----
-
-## Step 7: Report
-
-```
-=== MILESTONE COMPLETE ===
-Milestone: {milestone} ({name})
-Artifacts: {count} archived
-Learnings: {learnings_count} extracted
-
-Archive: .workflow/milestones/{milestone}/
-Next:    {next_milestone or "Project complete"}
-
-Next steps:
-  /maestro-milestone-release    -- Cut a release
-  /maestro-analyze              -- Start next milestone
-  /manage-status                -- View project state
-```
+# Workflow: milestone-complete
+
+Archive completed milestone, move artifacts to history, and prepare for next.
+
+---
+
+## Step 1: Validation
+
+1. Read `.workflow/state.json`:
+   - Determine target milestone (from $ARGUMENTS or current_milestone)
+   - If no milestone: ERROR E001
+
+2. Check milestone audit status:
+   - Read `.workflow/milestones/{milestone}/audit-report.md` if exists
+   - If no audit report:
+     - WARN: "No audit report found. Run `/maestro-milestone-audit` first."
+     - Ask user: "Complete without audit?"
+     - If NO → exit
+   - If verdict is FAIL: ERROR E002
+
+3. Verify all artifacts completed:
+   ```
+   milestone_artifacts = state.json.artifacts.filter(a => a.milestone == target_milestone)
+   incomplete = milestone_artifacts.filter(a => a.status != "completed")
+   IF incomplete.length > 0:
+     ERROR E003: "Incomplete artifacts: {list ids and statuses}"
+   ```
+
+---
+
+## Step 2: Create Milestone Archive
+
+1. Create archive directory:
+   ```
+   mkdir -p .workflow/milestones/{milestone}/artifacts/
+   ```
+
+2. Snapshot roadmap:
+   ```
+   cp .workflow/roadmap.md .workflow/milestones/{milestone}/roadmap-snapshot.md
+   ```
+
+3. Archive scratch directories:
+   ```
+   FOR each artifact IN milestone_artifacts:
+     IF directory exists at .workflow/{artifact.path}:
+       cp -r .workflow/{artifact.path} .workflow/milestones/{milestone}/artifacts/{basename}/
+   ```
+
+---
+
+## Step 2.5: Load Existing Learnings
+
+```
+existing_learnings = maestro spec load --category learning
+```
+
+Check existing entries to avoid duplicates when appending in Step 3.
+
+---
+
+## Step 3: Extract Learnings
+
+1. For each execute artifact, read `.summaries/` and `reflection-log.md` if exists:
+   - Extract strategy adjustments
+   - Extract patterns discovered
+   - Extract pitfalls encountered
+
+2. Aggregate learnings and append to `.workflow/specs/learnings.md`:
+   ```
+   For each strategy adjustment:
+     ### [YYYY-MM-DD HH:mm] decision: {summary}
+     {content}
+     Milestone: {milestone} | Source: milestone-complete
+
+   For each pattern:
+     ### [YYYY-MM-DD HH:mm] pattern: {summary}
+     {content}
+     Milestone: {milestone} | Source: milestone-complete
+
+   For each pitfall:
+     ### [YYYY-MM-DD HH:mm] bug: {summary}
+     {content}
+     Milestone: {milestone} | Source: milestone-complete
+   ```
+
+---
+
+## Step 4: Update State
+
+1. Archive artifact entries to milestone_history:
+   ```json
+   {
+     "milestone_history": [
+       {
+         "id": "{milestone}",
+         "name": "{milestone_name}",
+         "status": "completed",
+         "completed_at": "{now}",
+         "archive_path": "milestones/{milestone}/",
+         "archived_artifacts": [ ...all milestone artifacts entries... ]
+       }
+     ]
+   }
+   ```
+
+2. Clear artifacts array (remove milestone-affiliated entries):
+   ```
+   state.json.artifacts = state.json.artifacts.filter(a => a.milestone != target_milestone)
+   ```
+
+3. Advance to next milestone:
+   ```
+   next_milestone = state.json.milestones.find(m => m.status == "pending")
+   IF next_milestone:
+     state.json.current_milestone = next_milestone.id
+     next_milestone.status = "active"
+   ELSE:
+     state.json.current_milestone = null
+     state.json.status = "completed"
+   ```
+
+4. Write state.json (atomic)
+
+---
+
+## Step 5: Clean Scratch
+
+Remove archived scratch directories:
+```
+FOR each artifact IN archived_artifacts:
+  IF directory exists at .workflow/{artifact.path}:
+    rm -rf .workflow/{artifact.path}
+```
+
+---
+
+## Step 6: Generate Summary
+
+Write `.workflow/milestones/{milestone}/summary.md`:
+```markdown
+# Milestone: {milestone} — {name}
+
+**Completed**: {date}
+**Artifacts**: {count} (analyze: {n}, plan: {n}, execute: {n}, verify: {n})
+
+## Key Outcomes
+{extracted from audit report + learnings}
+
+## Learnings
+{top patterns and pitfalls}
+
+## Next Milestone
+{next milestone name and first phase, or "Project complete"}
+```
+
+Update `.workflow/project.md` Context section with milestone summary.
+
+---
+
+## Step 7: Report
+
+```
+=== MILESTONE COMPLETE ===
+Milestone: {milestone} ({name})
+Artifacts: {count} archived
+Learnings: {learnings_count} extracted
+
+Archive: .workflow/milestones/{milestone}/
+Next:    {next_milestone or "Project complete"}
+
+Next steps:
+  /maestro-milestone-release    -- Cut a release
+  /maestro-analyze              -- Start next milestone
+  /manage-status                -- View project state
+```

package/workflows/plan.md

@@ -100,7 +100,7 @@ mkdir -p {OUTPUT_DIR}/.task/
 
 3. **Load project specs**
    ```
-   specs_content = maestro spec load --category planning
+   specs_content = maestro spec load --category arch
    ```
    Pass to planner agent as project constraints context.