maestro-flow 0.3.7 → 0.3.9

package/.claude/commands/learn-retro-decision.md

@@ -1,198 +0,0 @@
----
-name: learn-retro-decision
-description: Decision trace and evaluation with multi-perspective analysis and lifecycle classification
-argument-hint: "[--phase N] [--tag <tag>] [--id <decision-id>]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Decision retrospective that traces architectural and design decisions across wiki, specs, phase contexts, and git history. Evaluates each decision from 3 perspectives (technical soundness, cost assessment, alternative hindsight) and classifies its lifecycle status.
-
-Inspired by gstack's cross-functional review pipeline (CEO/Eng/Design perspectives). Unlike `quality-retrospective` which reviews completed phases holistically, this command focuses specifically on decision quality and evolution.
-</purpose>
-
-<context>
-Arguments: $ARGUMENTS
-
-**Scope:**
-- No arguments → scan all sources for decisions, prompt for selection
-- `--phase N` → decisions from phase N's context and related specs
-- `--tag <tag>` → decisions tagged with specific tag in wiki/specs
-- `--id <id>` → single decision by wiki ID or lessons.jsonl INS-id
-
-**Storage written:**
-- `.workflow/learning/retro-decision-{YYYY-MM-DD}.md` — Decision evaluation report
-- `.workflow/learning/lessons.jsonl` — Decision evaluation insights (source: "retro-decision")
-- `.workflow/learning/learning-index.json` — Updated index
-
-**Storage read:**
-- `maestro wiki list --type spec --json` — Spec entries (many contain decisions)
-- `maestro wiki search "decision"` — Decision-tagged entries
-- `.workflow/specs/architecture-constraints.md` — Documented architectural decisions
-- `.workflow/phases/*/context.md` — Phase context with Locked/Free/Deferred decisions (if exists)
-- `.workflow/learning/lessons.jsonl` — Entries with `category: "decision"`
-- Git log — Implementation evidence for decision tracing
-</context>
-
-<execution>
-
-### Stage 1: Collect Decisions
-Gather decisions from all sources in parallel:
-
-```bash
-# Wiki decisions
-maestro wiki search "decision" --json
-maestro wiki list --type spec --json  # specs often contain decision entries
-
-# Git evidence
-git log --oneline --all --grep="decision\|chose\|decided\|architecture" -20
-```
-
-Also read:
-- `.workflow/specs/architecture-constraints.md` — grep for `### [decision]` heading blocks
-- `.workflow/phases/*/context.md` — scan for "Locked:", "Deferred:" sections
-- `.workflow/learning/lessons.jsonl` — filter entries where `category == "decision"`
-
-Apply scope filter (--phase, --tag, --id) to reduce the set.
-
-If no decisions found, AskUserQuestion: "No decisions found in wiki/specs. Would you like to: A) Scan git commit messages for implicit decisions, B) Provide a specific decision to evaluate"
-
-### Stage 2: Build Decision Registry
-For each decision, build a structured record:
-
-```json
-{
-  "id": "decision source id",
-  "title": "what was decided",
-  "source": "wiki|spec|phase-context|lesson|git",
-  "date": "when decided",
-  "rationale": "why (if documented)",
-  "alternatives": "what was considered (if documented)",
-  "phase": "which phase",
-  "tags": ["related tags"],
-  "implementation_evidence": ["file paths from git that implement this"]
-}
-```
-
-For implementation evidence: search git log for commits that reference the decision topic, and grep source files for patterns consistent with the decision.
-
-### Stage 3: Multi-Perspective Evaluation
-Spawn 3 Agents in a single message, each evaluating all decisions from one perspective:
-
-**Agent 1 — Technical Soundness:**
-- Does the implementation match the stated intent?
-- Are there code-level violations of the decision?
-- Has the technical context changed since the decision was made?
-- Grade: sound / degraded / violated
-
-**Agent 2 — Cost Assessment:**
-- What complexity did this decision add?
-- How many files/modules are affected?
-- Is the decision creating coupling or technical debt?
-- Grade: low-cost / acceptable / expensive / debt-creating
-
-**Agent 3 — Alternative Hindsight:**
-- With what we know now, was this the right call?
-- What alternative would we choose today?
-- Would reversing this decision be feasible?
-- Grade: confirmed / questionable / should-revisit
-
-Each agent receives the full decision registry and returns evaluations per decision.
-
-### Stage 4: Classify Decision Lifecycle
-Based on the 3 perspectives, classify each decision:
-
-| Status | Criteria |
-|--------|---------|
-| **Validated** | Sound + Low/Acceptable cost + Confirmed | 
-| **Aging** | Sound but Expensive + Confirmed (still right but costly) |
-| **Questionable** | Degraded or Violated + Any cost + Questionable |
-| **Stale** | Any soundness + Any cost + Should-revisit |
-| **Reversed** | Evidence in code contradicts the decision |
-
-### Stage 5: Generate Recommendations
-For each non-Validated decision:
-- **Aging**: flag for tech debt review, suggest cost reduction
-- **Questionable**: create issue for investigation, suggest brainstorm
-- **Stale**: suggest decision refresh (re-evaluate with current context)
-- **Reversed**: suggest documenting the reversal and updating specs/wiki
-
-### Stage 6: Write Report
-`.workflow/learning/retro-decision-{date}.md`:
-
-```markdown
-# Decision Retrospective: {scope}
-**Date:** {date} | **Decisions evaluated:** {count}
-
-## Decision Health Dashboard
-| Status | Count | Decisions |
-|--------|-------|-----------|
-| Validated | N | {list} |
-| Aging | N | {list} |
-| Questionable | N | {list} |
-| Stale | N | {list} |
-
-## Per-Decision Evaluation
-
-### {Decision Title}
-**Source:** {wiki/spec/phase} | **Date:** {when} | **Status:** {lifecycle}
-
-| Perspective | Grade | Assessment |
-|------------|-------|-----------|
-| Technical | sound/degraded/violated | {one-line} |
-| Cost | low/acceptable/expensive | {one-line} |
-| Hindsight | confirmed/questionable/revisit | {one-line} |
-
-**Implementation evidence:** {file references}
-**Recommendation:** {action if non-validated}
-
-## Recommended Actions
-1. {action}: {reason}
-```
-
-### Stage 7: Persist
-1. Write report file
-2. Append decision evaluation insights to `lessons.jsonl`:
-   - `source: "retro-decision"`, `category: "decision"`
-   - Tags: `["retro-decision", "{lifecycle-status}"]`
-   - One insight per non-Validated decision with the recommendation
-3. Update `learning-index.json`
-4. Optionally: update wiki entries with evaluation metadata via `maestro wiki update`
-5. Display health dashboard summary
-
-**Next-step routing:**
-- Create issue for questionable decision → `Skill({ skill: "manage-issue", args: "create ..." })`
-- Brainstorm alternatives → `Skill({ skill: "maestro-brainstorm", args: "<decision topic>" })`
-- Investigate stale decision → `Skill({ skill: "learn-investigate", args: "<question>" })`
-- Update spec → `Skill({ skill: "spec-add", args: "decision <updated rationale>" })`
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | No decisions found in any source | Check wiki/specs content, or provide --id |
-| E002 | error | --id not found in wiki or lessons | Verify the decision ID exists |
-| W001 | warning | One perspective agent failed — partial evaluation | Proceed with available perspectives, note gap |
-| W002 | warning | No git implementation evidence found for a decision | Decision evaluation is theoretical only |
-| W003 | warning | Phase context files not found | Skip phase-context decisions, proceed with wiki/spec sources |
-</error_codes>
-
-<success_criteria>
-- [ ] Decisions collected from all available sources (wiki, specs, phase-context, lessons, git)
-- [ ] Scope filter applied correctly (--phase, --tag, or --id)
-- [ ] Decision registry built with structured records
-- [ ] 3 perspective agents spawned in parallel
-- [ ] Each decision classified: Validated / Aging / Questionable / Stale / Reversed
-- [ ] Recommendations generated for non-Validated decisions
-- [ ] Report written to `retro-decision-{date}.md` with health dashboard
-- [ ] Insights appended to `lessons.jsonl` (source: "retro-decision")
-- [ ] `learning-index.json` updated
-- [ ] No files modified outside `.workflow/learning/`
-- [ ] Health dashboard displayed with next-step routing
-</success_criteria>

package/.claude/commands/learn-retro-git.md

@@ -1,160 +0,0 @@
----
-name: learn-retro-git
-description: Git activity retrospective with metrics, session detection, per-author breakdown, and trend tracking
-argument-hint: "[--days N] [--author <name>] [--area <path>] [--compare]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Git-activity retrospective that works on raw git history regardless of workflow phase state. Complements `quality-retrospective` (which requires completed phase artifacts) by analyzing commit metrics, detecting work sessions, computing test ratios, and tracking trends over time.
-
-Inspired by gstack `/retro`: per-author breakdown, session clustering, LOC metrics, file hotspot detection, and comparison against prior retrospectives.
-
-All insights are persisted to `.workflow/learning/lessons.jsonl` (source: "git-retro") so they're queryable via `manage-learn search/list`.
-</purpose>
-
-<context>
-Arguments: $ARGUMENTS
-
-**Flags:**
-- `--days N` — Time window in days (default: 7)
-- `--author <name>` — Filter commits by author name (substring match)
-- `--area <path>` — Scope to files under a specific directory
-- `--compare` — Compare against the previous retro-git report if one exists
-
-**Storage written:**
-- `.workflow/learning/retro-git-{YYYY-MM-DD}.json` — Structured metrics (machine-readable)
-- `.workflow/learning/retro-git-{YYYY-MM-DD}.md` — Human-readable retrospective report
-- `.workflow/learning/lessons.jsonl` — Appended insights (source: "git-retro")
-- `.workflow/learning/learning-index.json` — Updated index
-
-**Storage read:**
-- `.workflow/state.json` — Current phase context (optional)
-- `.workflow/learning/retro-git-*.json` — Prior retro for trend comparison
-- `.workflow/learning/lessons.jsonl` — Existing insights for dedup
-</context>
-
-<execution>
-
-### Stage 1: Parse Arguments
-- Resolve date range: `--days N` or default 7. Compute absolute start date at midnight.
-- Extract `--author`, `--area`, `--compare` flags.
-- Check `.workflow/learning/` exists; bootstrap if missing.
-
-### Stage 2: Gather Raw Data (parallel git commands)
-Run ALL these git commands in parallel (they are independent):
-
-```bash
-# 1. Commit stats with author, timestamp, subject, files changed
-git log --since="<start-date>T00:00:00" --format="%H|%aN|%ae|%ai|%s" --shortstat
-
-# 2. Per-commit numstat for test vs production LOC split
-# Test files: match test/|spec/|__tests__/|*.test.*|*.spec.*
-git log --since="<start-date>T00:00:00" --format="COMMIT:%H|%aN" --numstat
-
-# 3. Timestamps for session detection (sorted)
-git log --since="<start-date>T00:00:00" --format="%at|%aN|%ai|%s" | sort -n
-
-# 4. File hotspots (most frequently changed files)
-git log --since="<start-date>T00:00:00" --format="" --name-only | grep -v '^$' | sort | uniq -c | sort -rn | head -20
-
-# 5. Per-author commit counts
-git shortlog --since="<start-date>T00:00:00" -sn --no-merges
-
-# 6. Per-author file hotspots
-git log --since="<start-date>T00:00:00" --format="AUTHOR:%aN" --name-only
-```
-
-Apply `--author` filter and `--area` path filter to all commands if provided.
-
-### Stage 3: Compute Metrics
-Calculate and build a metrics object:
-
-| Metric | Computation |
-|--------|-------------|
-| Commits | Count of non-merge commits |
-| Contributors | Unique author count |
-| Total insertions / deletions | Sum from shortstat |
-| Net LOC | insertions - deletions |
-| Test LOC (insertions) | Sum insertions for test files from numstat |
-| Test ratio | test_insertions / total_insertions × 100% |
-| Churn rate | Files changed >2 times / total unique files |
-| Active days | Distinct dates with commits |
-| Area concentration | Top directory % of total commits (Herfindahl) |
-
-### Stage 4: Detect Work Sessions
-Cluster commits by >2hr gaps in timestamps:
-- Group consecutive commits within 2-hour windows into sessions
-- Per session: start time, end time, duration, commit count, primary focus area (most-touched directory)
-- Compute: total sessions, avg session duration, avg LOC/session-hour
-
-### Stage 5: Per-Author Breakdown
-For each author:
-- Commit count, LOC added/removed, top 3 file areas
-- Test ratio (their test LOC / their total LOC)
-- Session count and patterns
-
-### Stage 6: Trend Comparison (if --compare or prior report exists)
-- Find most recent `.workflow/learning/retro-git-*.json`
-- If found, compute deltas: commits Δ, LOC Δ, test ratio Δ, churn rate Δ, session count Δ
-- Flag significant changes (>20% delta) as trend highlights
-
-### Stage 7: Distill Insights
-Identify actionable insights from metrics:
-- **High churn files** (changed >3 times): instability signal → suggest refactor or test coverage
-- **Low test ratio areas** (<20%): testing gap → suggest test generation
-- **Session patterns**: scattered sessions (many short) vs deep sessions (few long)
-- **Area drift**: if commits don't align with current roadmap phase
-
-Each insight: title, description, category (pattern/antipattern/technique), tags, confidence.
-
-### Stage 8: Persist & Report
-1. Write `.workflow/learning/retro-git-{date}.json` with full metrics structure
-2. Write `.workflow/learning/retro-git-{date}.md` with formatted report:
-   - Summary metrics table
-   - Per-author leaderboard
-   - Session timeline
-   - File hotspots
-   - Insights with recommendations
-   - Trend deltas (if comparing)
-3. Append each insight to `lessons.jsonl` with `source: "git-retro"`, `lens: null`, using stable INS-id from `hash(metric_name + date)`
-4. Update `learning-index.json`
-5. Display summary and next-step suggestions
-
-**Next-step routing:**
-- Browse insights → `Skill({ skill: "manage-learn", args: "list --tag git-retro" })`
-- Deep dive on high-churn file → `Skill({ skill: "learn-follow", args: "<path>" })`
-- Fix test gaps → `Skill({ skill: "quality-test-gen", args: "<area>" })`
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Not inside a git repository | Navigate to a git repo directory |
-| E002 | error | No commits found in the specified time window | Increase --days or check --author/--area filters |
-| W001 | warning | `.workflow/learning/` not found, bootstrapping | Auto-created; proceed normally |
-| W002 | warning | No prior retro-git report for comparison | Skip trend section; first retro establishes baseline |
-| W003 | warning | Author filter matched 0 commits | Show available authors and re-prompt |
-</error_codes>
-
-<success_criteria>
-- [ ] Date range parsed correctly (absolute midnight-aligned start date)
-- [ ] All 6 git commands executed successfully
-- [ ] Metrics computed: commits, LOC, test ratio, churn rate, sessions, area concentration
-- [ ] Sessions detected with >2hr gap clustering
-- [ ] Per-author breakdown generated for all contributors
-- [ ] Trend comparison computed if prior report exists and --compare used
-- [ ] At least 1 actionable insight distilled from metrics
-- [ ] `retro-git-{date}.json` written with valid JSON
-- [ ] `retro-git-{date}.md` written and human-readable
-- [ ] `lessons.jsonl` appended with insights (source: "git-retro", stable INS-ids)
-- [ ] `learning-index.json` updated
-- [ ] No files modified outside `.workflow/learning/`
-- [ ] Summary displayed with next-step routing
-</success_criteria>

package/.claude/commands/maestro-phase-add.md

@@ -1,63 +0,0 @@
----
-name: maestro-phase-add
-description: Add or insert a new phase into the project roadmap with automatic renumbering
-argument-hint: "<slug> <title> [--after N]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-
-<purpose>
-Add a new phase to the project roadmap, either appending it at the end or inserting it after a specified phase number. Handles automatic renumbering of subsequent phase directories, updates roadmap.md with the new entry, and initializes the phase directory with an index.json so it is ready for planning.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/phase-add.md
-</required_reading>
-
-<deferred_reading>
-- [index.json](~/.maestro/templates/index.json) — read when creating new phase index
-</deferred_reading>
-
-<context>
-$ARGUMENTS -- phase slug and title (required), optional --after N flag.
-
-**Flags:**
-- `--after N` -- Insert after phase N (renumbers subsequent phases). If omitted, appends at end.
-
-**State files:**
-- `.workflow/roadmap.md` -- milestone and phase structure
-- `.workflow/state.json` -- project-level state
-- `.workflow/phases/` -- existing phase directories
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/phase-add.md' completely.
-
-**Next-step routing on completion:**
-- Plan the new phase → Skill({ skill: "maestro-plan", args: "{new_phase_number}" })
-- Analyze before planning → Skill({ skill: "maestro-analyze", args: "{new_phase_number}" })
-- View updated roadmap → Skill({ skill: "manage-status" })
-</execution>
-
-<error_codes>
-| Code | Meaning                          |
-|------|----------------------------------|
-| E001 | Phase name/slug required         |
-| E002 | roadmap.md not found             |
-| E003 | Duplicate phase name/slug exists |
-</error_codes>
-
-<success_criteria>
-- [ ] Phase directory created with NN-slug format
-- [ ] roadmap.md updated with new phase entry at correct position
-- [ ] index.json initialized in new phase directory with status = "pending"
-- [ ] Subsequent phases renumbered correctly (if --after N used)
-- [ ] state.json updated if renumbering affected tracked phases
-</success_criteria>

package/.claude/commands/maestro-phase-transition.md

@@ -1,75 +0,0 @@
----
-name: maestro-phase-transition
-description: Mark current or specified phase as complete, extract learnings, advance to next phase
-argument-hint: "[phase-number] [--force]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-
-<purpose>
-Transition from one phase to the next after verification passes. Validates that the current phase meets all completion criteria (tasks done, verification passed, no unresolved gaps), marks it complete in the phase index, and advances the project state to the next phase. If the next phase directory does not exist, it is created and initialized.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/phase-transition.md
-</required_reading>
-
-<deferred_reading>
-- [state.json](~/.maestro/templates/state.json) — read when updating project state
-- [index.json](~/.maestro/templates/index.json) — read when updating phase index
-</deferred_reading>
-
-<context>
-$ARGUMENTS -- phase number to transition from (optional, defaults to current_phase from state.json).
-
-**Flags:**
-- `--force` -- Skip gap check and force transition even with warnings
-
-**State files:**
-- `.workflow/state.json` -- project-level state (current_phase, milestones)
-- `.workflow/phases/{NN}-{slug}/index.json` -- phase metadata and status
-- `.workflow/phases/{NN}-{slug}/verification.json` -- verification results
-- `.workflow/phases/{NN}-{slug}/review.json` -- code review results (if exists)
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/phase-transition.md' completely.
-
-**Next-step routing on completion:**
-- Next phase exists, ready to plan → Skill({ skill: "maestro-plan", args: "{next_phase}" })
-- Next phase needs analysis first → Skill({ skill: "maestro-analyze", args: "{next_phase}" })
-- Next phase needs UI design → Skill({ skill: "maestro-ui-design", args: "{next_phase}" })
-- All phases in milestone complete → Skill({ skill: "maestro-milestone-audit" })
-- View updated dashboard → Skill({ skill: "manage-status" })
-</execution>
-
-<error_codes>
-| Code | Meaning                                    |
-|------|--------------------------------------------|
-| E001 | Phase number required (could not determine) |
-| E002 | Phase has not passed verification           |
-| E003 | Phase has unresolved critical gaps          |
-| W001 | Phase has warnings but no blockers          |
-| W002 | UAT test failures exist (quality-test) — review recommended before transition |
-| W003 | Code review verdict is BLOCK — Skill({ skill: "quality-review" }) findings should be fixed first |
-| W004 | Code review not yet run — Skill({ skill: "quality-review" }) recommended before transition |
-| W005 | Orphan specs found in wiki — consider linking or removing before transition |
-</error_codes>
-
-<success_criteria>
-- [ ] Current phase index.json marked status = "complete" with completed_at timestamp
-- [ ] Next phase directory created (if not already existing)
-- [ ] Next phase index.json initialized with status = "pending"
-- [ ] state.json current_phase updated to next phase number
-- [ ] Wiki health score reported — warnings emitted if orphan specs found
-- [ ] Learnings extracted and appended to specs/learnings.md
-- [ ] project.md requirements moved Active → Validated for completed phase
-- [ ] roadmap.md phase marked as ✅ COMPLETED
-</success_criteria>

package/.codex/skills/maestro-phase-add/SKILL.md

@@ -1,154 +0,0 @@
----
-name: maestro-phase-add
-description: Add or insert a new phase into the project roadmap with automatic renumbering
-argument-hint: "\"phase name\" [--after N] [--before N]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
----
-
-# Maestro Phase Add (Single Agent)
-
-## Usage
-
-```bash
-$maestro-phase-add "authentication"
-$maestro-phase-add "caching-layer" --after 2
-$maestro-phase-add "security-hardening" --before 5
-```
-
-**Flags**:
-- `"phase name"`: Required. Used as both slug and title (slug = lowercase, hyphens)
-- `--after N`: Insert after phase N (renumbers subsequent phases)
-- `--before N`: Insert before phase N (renumbers from N onward)
-- If neither: append at end
-
-**Output**: New phase directory, updated roadmap.md, updated state.json
-
----
-
-## Overview
-
-Single mutation operation on the project roadmap. Creates a new phase directory with initialized index.json, inserts the phase entry into roadmap.md at the correct position, and handles automatic renumbering of all affected phase directories and references.
-
----
-
-## Implementation
-
-### Step 1: Parse Arguments
-
-Extract:
-- Phase name/slug (required — E001 if missing)
-- `--after N` or `--before N` flag (mutually exclusive)
-- Generate slug: lowercase, replace spaces with hyphens, strip special chars
-
-### Step 2: Load Roadmap State
-
-```bash
-cat .workflow/roadmap.md
-cat .workflow/state.json
-ls -d .workflow/phases/*/
-```
-
-- Parse existing phases from roadmap.md
-- List existing phase directories
-- Check for duplicate slug (E003 if exists)
-- Verify roadmap.md exists (E002 if not)
-
-### Step 3: Calculate Position
-
-- If `--after N`: new phase number = N + 1
-- If `--before N`: new phase number = N
-- If neither: new phase number = max_existing + 1
-
-### Step 4: Renumber Existing Phases (if inserting)
-
-**Only when `--after N` or `--before N` is used.**
-
-For each phase with number >= new phase number (process in reverse order to avoid collisions):
-
-1. Rename directory: `.workflow/phases/{NN}-{slug}` → `.workflow/phases/{NN+1}-{slug}`
-2. Update index.json inside renamed directory: `"phase": N+1`
-
-```bash
-# Rename in reverse order to prevent collisions
-for dir in $(ls -rd .workflow/phases/*/); do
-  # Extract number, if >= insertion point, rename to number+1
-done
-```
-
-### Step 5: Create Phase Directory
-
-```bash
-mkdir -p .workflow/phases/{NN}-{slug}
-```
-
-Format NN as zero-padded 2-digit number (e.g., 03).
-
-### Step 6: Initialize Phase index.json
-
-Read template from `~/.maestro/templates/index.json` if available, otherwise create:
-
-```json
-{
-  "phase": <N>,
-  "slug": "<slug>",
-  "title": "<phase name>",
-  "status": "pending",
-  "created_at": "<ISO timestamp>",
-  "tasks": []
-}
-```
-
-Write to `.workflow/phases/{NN}-{slug}/index.json`.
-
-### Step 7: Update roadmap.md
-
-Insert new phase entry at the correct position in roadmap.md:
-- Match the existing phase entry format
-- If inserting, update all subsequent phase numbers in the document
-
-### Step 8: Update state.json
-
-If renumbering affected `current_phase` or `phases_completed`:
-- Adjust `current_phase` number if it was shifted
-- Adjust all entries in `phases_completed` that were shifted
-
-### Step 9: Completion Report
-
-```
-=== PHASE ADDED ===
-Phase: {NN} - {phase name}
-Location: .workflow/phases/{NN}-{slug}/
-
-{if renumbered}
-Renumbered: Phases {start}-{end} shifted by +1
-{endif}
-
-Updated:
-  .workflow/roadmap.md
-  .workflow/phases/{NN}-{slug}/index.json
-  {if renumbered}.workflow/state.json{endif}
-
-Next steps:
-  $maestro-plan ""         -- Plan tasks for the new phase
-  $manage-status          -- View updated roadmap
-```
-
----
-
-## Error Handling
-
-| Code | Severity | Description | Recovery |
-|------|----------|-------------|----------|
-| E001 | error | Phase name/slug required | Provide phase name as argument |
-| E002 | error | roadmap.md not found | Run maestro-init first |
-| E003 | error | Duplicate phase name/slug exists | Choose a different name |
-
----
-
-## Core Rules
-
-1. **Reverse-order renumbering** — always rename directories from highest to lowest to prevent collisions
-2. **State consistency** — state.json phase references must be adjusted after renumbering
-3. **Match existing format** — new roadmap.md entries must match the style of existing entries
-4. **Zero-padded numbers** — always use 2-digit format (01, 02, ... 99)
-5. **Slug normalization** — lowercase, hyphens only, no special characters