maestro-flow 0.1.0

package/workflows/milestone-audit.md

@@ -0,0 +1,130 @@
+# Workflow: milestone-audit
+
+Cross-phase integration audit for milestone completion.
+
+---
+
+## Step 1: Load Milestone Context
+
+1. Read `.workflow/state.json`:
+   - Determine target milestone (from $ARGUMENTS or current_milestone)
+   - Get phases_summary
+
+2. Identify all phases belonging to this milestone:
+   - Read `.workflow/roadmap.md` to map phases to milestones
+   - Collect phase directories: `.workflow/phases/{NN}-{slug}/`
+
+3. For each phase, read `index.json`:
+   - Collect: status, goal, success_criteria, verification, validation, uat
+   - Flag any phase not in "completed" status as a warning
+
+---
+
+## Step 2: Pre-audit Validation
+
+1. Check all phases are completed:
+   ```
+   incomplete = phases.filter(status != "completed")
+   if incomplete.length > 0:
+     WARN: "Phases not completed: {list}"
+     Ask user: "Continue audit anyway? Some phases are incomplete."
+     if NO → exit with "Complete phases first: /workflow:execute {phase}"
+   ```
+
+2. Check all phases have verification.json with status "passed":
+   ```
+   unverified = phases.filter(verification.status != "passed")
+   if unverified.length > 0:
+     WARN: "Phases not verified: {list}"
+   ```
+
+---
+
+## Step 3: Integration Check
+
+Spawn `workflow-integration-checker` agent:
+
+```
+Agent({
+  subagent_type: "workflow-integration-checker",
+  prompt: "
+    Audit cross-phase integration for milestone {milestone}.
+
+    Phases to audit:
+    {for each phase: number, title, goal, success_criteria}
+
+    Check:
+    1. SHARED INTERFACES -- Do phases that share interfaces have compatible types/contracts?
+    2. DEPENDENCY CHAINS -- Are all cross-phase dependencies satisfied?
+    3. DATA CONTRACTS -- Do data models used across phases match?
+    4. API CONSISTENCY -- Are API endpoints/interfaces consistent across phases?
+    5. CONFIGURATION -- Are shared configs compatible?
+    6. ERROR HANDLING -- Do error flows work across phase boundaries?
+
+    For each check, report:
+    - Status: passed | gap_found
+    - If gap: description, affected phases, severity (critical/high/medium/low), fix suggestion
+
+    Ensure directory exists: mkdir -p .workflow/milestones/{milestone}/
+    Write audit report to .workflow/milestones/{milestone}/audit-report.md
+    Return: summary with gap count and severity breakdown.
+  ",
+  run_in_background: false
+})
+```
+
+---
+
+## Step 4: Audit Report
+
+1. Read the audit report generated by the integration checker
+2. Display summary:
+
+```
+====================================================
+  MILESTONE AUDIT: {milestone}
+  PHASES AUDITED: {count}
+====================================================
+
+RESULTS:
+  Shared Interfaces:   {passed|N gaps}
+  Dependency Chains:   {passed|N gaps}
+  Data Contracts:      {passed|N gaps}
+  API Consistency:     {passed|N gaps}
+  Configuration:       {passed|N gaps}
+  Error Handling:      {passed|N gaps}
+
+TOTAL GAPS: {count}
+  Critical: {count}
+  High:     {count}
+  Medium:   {count}
+  Low:      {count}
+====================================================
+```
+
+---
+
+## Step 5: Route
+
+Based on audit results:
+
+### All checks passed (0 gaps):
+```
+AUDIT PASSED
+Next: Skill({ skill: "maestro-milestone-complete", args: "{milestone}" })
+```
+
+### Gaps found:
+```
+AUDIT FOUND GAPS
+{for each gap}
+  [{severity}] {description}
+    Affected: Phase {N1}, Phase {N2}
+    Fix: {suggestion}
+{/for}
+
+Suggested actions:
+  - Critical/High gaps: Skill({ skill: "quality-debug" }) for each critical gap
+  - Medium/Low gaps: /workflow:plan --gaps {phase} (add fix tasks)
+  - Re-audit after fixes: /workflow:milestone-audit {milestone}
+```

package/workflows/milestone-complete.md

@@ -0,0 +1,222 @@
+# Workflow: milestone-complete
+
+Archive completed milestone and prepare for next.
+
+---
+
+## Step 1: Validation
+
+1. Read `.workflow/state.json`:
+   - Determine target milestone (from $ARGUMENTS or current_milestone)
+
+2. Check milestone audit status:
+   - Read `.workflow/milestones/{milestone}/audit-report.md` if exists
+   - If no audit report exists:
+     - WARN: "No audit report found. Run `/workflow:milestone-audit` first."
+     - Ask user: "Complete without audit?"
+     - If NO → exit with route to `/workflow:milestone-audit`
+
+3. Verify all phases are completed:
+   ```
+   For each phase in milestone:
+     Read phases/{NN}-{slug}/index.json
+     if status != "completed":
+       ERROR: "Phase {NN} ({title}) is not completed (status: {status})"
+       Route: /workflow:execute {NN} or /workflow:verify {NN}
+       EXIT
+   ```
+
+---
+
+## Step 2: Create Milestone Archive
+
+1. Create archive directory:
+   ```
+   mkdir -p .workflow/milestones/v{X.Y}/phases/
+   ```
+
+2. Snapshot roadmap:
+   ```
+   cp .workflow/roadmap.md .workflow/milestones/v{X.Y}/roadmap-snapshot.md
+   ```
+
+3. Archive phase directories:
+   ```
+   For each phase in milestone:
+     cp -r .workflow/phases/{NN}-{slug}/ .workflow/milestones/v{X.Y}/phases/{NN}-{slug}/
+   ```
+
+4. Audit report:
+   - Report already exists at `.workflow/milestones/{milestone}/audit-report.md` (written by milestone-audit)
+   - No copy needed; verify file is present in archive directory
+
+---
+
+## 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 phase in milestone, read `reflection-log.md` if exists:
+   - Extract strategy adjustments
+   - Extract patterns discovered
+   - Extract pitfalls encountered
+
+2. Aggregate learnings and append to `.workflow/specs/learnings.md` under "## Entries", using spec-add entry format for each item:
+   ```
+   For each strategy adjustment:
+     ### [YYYY-MM-DD HH:mm] decision: {summary}
+
+     {content}
+     Milestone: {milestone} | Source: milestone-complete
+
+   For each pattern discovered:
+     ### [YYYY-MM-DD HH:mm] pattern: {summary}
+
+     {content}
+     Milestone: {milestone} | Source: milestone-complete
+
+   For each pitfall encountered:
+     ### [YYYY-MM-DD HH:mm] bug: {summary}
+
+     {content}
+     Milestone: {milestone} | Source: milestone-complete
+   ```
+
+---
+
+## Step 3.5: Update project.md Context
+
+```
+Read .workflow/project.md
+
+a. Append milestone summary to "## Context" section:
+   - Milestone version, completion date
+   - Key learnings summary (top 3 from Step 3 aggregated learnings)
+   - Significant strategy adjustments that affect future work
+
+   Format:
+     **Milestone {milestone} ({date})**: {1-2 sentence summary of what was accomplished
+     and key insights that inform future work.}
+
+b. Update "Last updated" footer timestamp
+
+Write updated project.md
+Display: "project.md: Context updated with milestone {milestone} summary"
+```
+
+---
+
+## Step 4: Update State
+
+1. Read existing `.workflow/state.json` to preserve accumulated values.
+
+2. Determine next milestone from roadmap (read BEFORE any delete):
+   ```
+   a. Read .workflow/roadmap.md
+   b. Scan for all milestone headings (e.g. ## Milestone: vX.Y, ## v1.0, etc.)
+   c. Locate the current milestone heading in the list
+   d. next_milestone = the milestone heading immediately after current
+      (If no next milestone exists in roadmap, next_milestone = null)
+   e. If next_milestone is not null:
+        Scan for phases belonging to next_milestone
+        next_phase_count = count of phases in next milestone
+      Else:
+        next_phase_count = 0
+   ```
+
+3. Calculate updated phases_summary (derived pending):
+   ```
+   new_phases_summary = {
+     "total": next_phase_count,
+     "completed": 0,
+     "in_progress": 0,
+     "pending": next_phase_count - 0 - 0  // total - completed - in_progress
+   }
+   ```
+
+4. Clean up completed phase directories:
+   - Remove `.workflow/phases/{NN}-{slug}/` for archived phases
+   - Keep `.workflow/phases/` directory (empty, ready for new milestone)
+
+5. Remove stale roadmap:
+   - Delete `.workflow/roadmap.md` (already archived as `milestones/v{X.Y}/roadmap-snapshot.md`)
+   - This creates a clear "no roadmap" state that the maestro coordinator detects for next-milestone routing
+
+6. Update milestone_history entry for completed milestone:
+   ```
+   FOR each entry IN existing_state.milestone_history:
+     IF entry.name == completed_milestone OR entry.slug == completed_milestone:
+       entry.status = "completed"
+       entry.completed_at = "{timestamp}"
+       entry.archive_path = ".workflow/milestones/{completed_milestone}/"
+       BREAK
+   ```
+
+7. Write updated `.workflow/state.json`:
+   ```json
+   // If next_milestone exists:
+   {
+     "current_milestone": "{next_milestone}",
+     "current_phase": 1,
+     "status": "idle",
+     "phases_summary": new_phases_summary,
+     "accumulated_context": existing_state.accumulated_context,
+     "milestone_history": existing_state.milestone_history,
+     "last_updated": "{timestamp}"
+   }
+
+   // If next_milestone is null (project complete):
+   {
+     "current_milestone": "{completed_milestone}",
+     "current_phase": null,
+     "status": "completed",
+     "phases_summary": new_phases_summary,
+     "accumulated_context": existing_state.accumulated_context,
+     "milestone_history": existing_state.milestone_history,
+     "last_updated": "{timestamp}"
+   }
+   ```
+   Preserve `accumulated_context` and `milestone_history` -- decisions, deferred items, and milestone history carry forward.
+
+---
+
+## Step 5: Commit and Route
+
+1. If git repo: commit with message `"chore: complete milestone {milestone}"`
+
+2. Display completion summary:
+   ```
+   ====================================================
+     MILESTONE COMPLETED: {milestone}
+   ====================================================
+
+   Archived:
+     - {N} phases archived to .workflow/milestones/v{X.Y}/
+     - Roadmap snapshot saved
+     - Audit report archived
+     - {M} learnings extracted to specs/learnings.md
+
+   State reset:
+     - Current milestone: {next_milestone or completed_milestone}
+     - Current phase: {1 or null}
+     - Status: {idle or completed}
+
+   ====================================================
+   ```
+
+3. Route next steps:
+   - If next_milestone exists:
+     - Ask user: "Start planning next milestone?"
+       - YES → Suggest Skill({ skill: "maestro", args: "continue" }) — coordinator auto-detects post-milestone state, loads deferred items from accumulated_context, and routes to roadmap creation
+       - NO → "Project is idle." Suggest Skill({ skill: "manage-status" }) to check state anytime.
+   - If next_milestone is null (project complete):
+     - Display: "All milestones completed. Project is done."
+     - Suggest Skill({ skill: "manage-status" }) to review final state.

package/workflows/phase-add.md

@@ -0,0 +1,252 @@
+# Workflow: phase-add
+
+Add or insert a new phase into the project roadmap with automatic renumbering of subsequent phases.
+
+## Trigger
+
+- Manual via `/workflow:phase-add <after-phase> <slug> <title>`
+
+## Arguments
+
+| Arg | Description | Required |
+|-----|-------------|----------|
+| `<after-phase>` | Phase number after which to insert (0 = insert at beginning) | Yes |
+| `<slug>` | URL-safe identifier for the phase (kebab-case) | Yes |
+| `<title>` | Human-readable phase title | Yes |
+
+## Prerequisites
+
+- `.workflow/state.json` must exist
+- `.workflow/roadmap.md` must exist
+- `.workflow/phases/` directory must exist
+
+---
+
+## Workflow Steps
+
+### Step 1: Parse Arguments
+
+```
+Parse $ARGUMENTS to extract:
+  after_phase: integer (0 = before all, N = after phase N)
+  slug: string (validate kebab-case: /^[a-z0-9]+(-[a-z0-9]+)*$/)
+  title: string (remaining text after slug)
+
+Validate:
+  - after_phase is a non-negative integer
+  - slug is valid kebab-case
+  - title is non-empty
+  If invalid: fail with usage message:
+    "Usage: /workflow:phase-add <after-phase> <slug> <title>"
+    "Example: /workflow:phase-add 2 caching Add caching layer"
+```
+
+### Step 2: Calculate New Phase Number
+
+```
+new_phase_number = after_phase + 1
+
+Scan existing phases:
+  Glob: .workflow/phases/*/
+  Parse directory names: {NN}-{slug}
+  Build list: existing_phases = [{ number, slug, dir_name, path }]
+  Sort by number ascending
+
+Check for conflicts:
+  conflicting_phases = existing_phases.filter(p => p.number >= new_phase_number)
+  needs_renumber = conflicting_phases.length > 0
+
+Also validate:
+  - No existing phase has the same slug
+  If duplicate slug found: fail "Phase with slug '{slug}' already exists"
+```
+
+### Step 3: Renumber Existing Phases (if needed)
+
+```
+If needs_renumber:
+  Process conflicting phases from HIGHEST number to LOWEST (to avoid conflicts):
+
+  For each phase in reverse(conflicting_phases):
+    old_number = phase.number
+    new_number = phase.number + 1
+    old_dir = .workflow/phases/{old_number padded to 2 digits}-{phase.slug}
+    new_dir = .workflow/phases/{new_number padded to 2 digits}-{phase.slug}
+
+    a. Rename directory:
+       mv {old_dir} {new_dir}
+
+    b. Update index.json inside the renamed directory:
+       Read {new_dir}/index.json
+       Update: phase = new_number
+       Write {new_dir}/index.json
+
+    c. Log: "Renumbered: {old_number}-{phase.slug} -> {new_number}-{phase.slug}"
+
+  Update state.json if current_phase was renumbered:
+    Read .workflow/state.json
+    If current_phase >= new_phase_number:
+      current_phase = current_phase + 1
+    Write .workflow/state.json
+```
+
+### Step 4: Create New Phase Directory
+
+```
+phase_dir = .workflow/phases/{new_phase_number padded to 2 digits}-{slug}
+
+Create directory: {phase_dir}/
+
+Create {phase_dir}/index.json:
+{
+  "phase": {new_phase_number},
+  "slug": "{slug}",
+  "title": "{title}",
+  "status": "pending",
+  "created_at": "{ISO timestamp}",
+  "updated_at": "{ISO timestamp}",
+  "goal": "",
+  "success_criteria": [],
+  "requirements": [],
+  "spec_ref": null,
+  "plan": {
+    "task_ids": [],
+    "task_count": 0,
+    "complexity": null,
+    "waves": []
+  },
+  "execution": {
+    "method": "agent",
+    "started_at": null,
+    "completed_at": null,
+    "tasks_completed": 0,
+    "tasks_total": 0,
+    "current_wave": 0,
+    "commits": []
+  },
+  "verification": {
+    "status": "pending",
+    "verified_at": null,
+    "must_haves": {},
+    "gaps": []
+  },
+  "validation": {
+    "status": "pending",
+    "test_coverage": null,
+    "gaps": []
+  },
+  "uat": {
+    "status": "pending",
+    "test_count": 0,
+    "passed": 0,
+    "gaps": []
+  },
+  "reflection": {
+    "rounds": 0,
+    "strategy_adjustments": []
+  }
+}
+
+Create subdirectories:
+  {phase_dir}/.task/
+  {phase_dir}/.summaries/
+  {phase_dir}/.process/
+```
+
+### Step 5: Update Roadmap
+
+```
+Read .workflow/roadmap.md
+
+Find the phase list section (look for numbered phase entries or table rows).
+
+Insert new phase entry at the correct position:
+
+  Format (match existing roadmap format):
+    ## Phase {new_phase_number}: {title}
+    - **Slug**: {slug}
+    - **Status**: pending
+    - **Goal**: (to be defined)
+
+  If roadmap uses table format:
+    | {new_phase_number} | {title} | {slug} | pending | - |
+
+  Update subsequent phase numbers in the document:
+    For each line referencing a phase number >= new_phase_number (excluding the new one):
+      Increment the phase number by 1
+
+Write updated roadmap.md
+```
+
+### Step 6: Update State Summary
+
+```
+Read .workflow/state.json
+
+Update phases_summary:
+  total: increment by 1
+  pending: increment by 1
+
+Write .workflow/state.json
+```
+
+### Step 7: Report
+
+```
+Display:
+  Phase added successfully:
+    Number: {new_phase_number}
+    Slug: {slug}
+    Title: {title}
+    Directory: .workflow/phases/{NN}-{slug}/
+
+  If renumbering occurred:
+    Phases renumbered:
+    {list of old -> new mappings}
+
+  Next steps:
+    - Define goals: Edit .workflow/phases/{NN}-{slug}/index.json
+    - Update roadmap details: Edit .workflow/roadmap.md
+    - Suggest: Skill({ skill: "maestro-analyze", args: "{new_phase_number} -q" }) or Skill({ skill: "maestro-plan", args: "{new_phase_number}" }) to start working on it
+```
+
+---
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| state.json missing | Fail: "Run /workflow:init first" |
+| roadmap.md missing | Fail: "No roadmap.md found" |
+| Duplicate slug | Fail: "Phase with slug '{slug}' already exists at phase {N}" |
+| Invalid slug format | Fail with slug format requirements |
+| after_phase > max existing | Insert at end (no renumbering needed) |
+| Rename conflict | Process highest-first to avoid; fail if OS rename fails |
+
+## Output Files
+
+| File | Action |
+|------|--------|
+| `.workflow/phases/{NN}-{slug}/index.json` | Created (new phase) |
+| `.workflow/phases/{NN}-{slug}/.task/` | Created (empty) |
+| `.workflow/phases/{NN}-{slug}/.summaries/` | Created (empty) |
+| `.workflow/phases/{NN}-{slug}/.process/` | Created (empty) |
+| `.workflow/phases/{MM}-{slug}/index.json` | Updated phase number (renumbered phases) |
+| `.workflow/roadmap.md` | Updated with new phase entry |
+| `.workflow/state.json` | Updated phases_summary totals |
+
+## Renumbering Example
+
+```
+Before: phases/01-setup, phases/02-auth, phases/03-api
+
+Command: /workflow:phase-add 1 caching "Add caching layer"
+
+Renumbering (highest first):
+  03-api -> 04-api
+  02-auth -> 03-auth
+
+Create: phases/02-caching
+
+After: phases/01-setup, phases/02-caching, phases/03-auth, phases/04-api
+```