maestro-flow-one 0.1.0

package/codex/maestro-flow/commands/manage/knowhow.md

@@ -0,0 +1,95 @@
+---
+name: manage-knowhow
+description: Manage knowhow entries across workflow and system stores (list, search, view, edit, delete, prune)
+argument-hint: "[list|search|view|edit|delete|prune] [query|id|file] [--store workflow|system|all] [--tag tag] [--type type]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+<purpose>
+Manage knowhow entries across workflow and system stores. Provides list, search, view, edit, delete, and prune operations over `.workflow/knowhow/` (workflow store) and `~/.claude/projects/{project}/memory/` (system store).
+</purpose>
+
+<context>
+$ARGUMENTS — subcommand followed by options. Defaults to `list` if no arguments.
+
+```bash
+$manage-knowhow
+$manage-knowhow "list --store workflow"
+$manage-knowhow "search authentication"
+$manage-knowhow "view KNW-20260318-001"
+$manage-knowhow "edit MEMORY.md"
+$manage-knowhow "delete TIP-20260318-001 --confirm"
+$manage-knowhow "prune --before 2026-01-01 --type tip --dry-run"
+```
+
+**Subcommands**: `list`, `search`, `view`, `edit`, `delete`, `prune`.
+
+**Flags**:
+- `--store workflow|system|all` — Target store (default: all)
+- `--tag <tag>` — Filter by tag
+- `--type <session|tip|template|recipe|reference|decision>` — Filter by knowhow type
+- `--confirm` — Skip delete confirmation prompt
+- `--before <date>` / `--after <date>` — Date filters for prune
+- `--dry-run` — Preview prune without deleting
+</context>
+
+<execution>
+
+### Step 1: Resolve Store Paths
+
+- **Workflow store**: `.workflow/knowhow/` (entries: `KNW-*.md`, `TIP-*.md`, `TPL-*.md`, `RCP-*.md`, `REF-*.md`, `DCS-*.md`, indexed in `.workflow/wiki-index.json`)
+- **System store**: `~/.claude/projects/{project}/memory/` (files: `MEMORY.md` + topic `.md` files)
+
+Derive system path from project root (replace path separators with `--`, prefix drive letter).
+
+### Step 2: Parse Subcommand
+
+Default to `list` if no arguments. Parse first token as subcommand.
+
+### Step 3: Execute Subcommand
+
+**list**: Show entries from both stores (or filtered by `--store`, `--tag`, `--type`).
+- Workflow: use `maestro wiki list --type knowhow --json` or read `.workflow/wiki-index.json`, display ID, type, category, date, tags, title
+- System: list `.md` files in system memory directory
+
+**search `<query>`**: Full-text grep across both stores. Rank by match count.
+
+**view `<id|file>`**: Auto-detect store from format (`KNW-*/TIP-*/TPL-*/RCP-*/REF-*/DCS-*` = workflow, else system). Display full content.
+
+**edit `<file>`**: Edit a system memory file. Read current content, apply changes. Warn if MEMORY.md exceeds 200 lines (W003).
+
+**delete `<id|file>`**: Require confirmation (or `--confirm` flag). MEMORY.md cannot be deleted (E004). Remove entry file (WikiIndexer auto-updates `.workflow/wiki-index.json` on next access).
+
+**prune**: Requires at least one filter (`--tag`, `--type`, `--before`, `--after`). Workflow store only. `--dry-run` previews without deleting.
+
+### Step 4: Integrity Check
+
+After write operations, verify:
+- No orphaned files without index entries (W001)
+- No dangling index references to missing files (W001)
+- System MEMORY.md references valid topic files (W002)
+</execution>
+
+<error_codes>
+| Code | Severity | Description |
+|------|----------|-------------|
+| E001 | error | No stores found — run `Skill({ skill: "maestro-flow", args: "--cmd manage-knowhow-capture" })` or create MEMORY.md |
+| E002 | error | Entry ID or filename not found |
+| E003 | error | Prune requires at least one filter flag |
+| E004 | error | Cannot delete MEMORY.md — use `edit` subcommand instead |
+| W001 | warning | Index has orphaned files or dangling references |
+| W002 | warning | MEMORY.md references non-existent topic file |
+| W003 | warning | MEMORY.md exceeds 200 lines — content truncated at load |
+</error_codes>
+
+<success_criteria>
+- [ ] Store paths resolved correctly for both workflow and system stores
+- [ ] Subcommand parsed and validated (defaults to list)
+- [ ] list: displays entries from selected stores with filtering
+- [ ] search: full-text grep across stores, ranked by match count
+- [ ] view: auto-detects store, displays full content
+- [ ] edit: reads and applies changes to system memory files
+- [ ] delete: requires confirmation, prevents MEMORY.md deletion
+- [ ] prune: requires filter, supports --dry-run, workflow store only
+- [ ] Integrity check after write operations (orphans, dangling refs)
+</success_criteria>

package/codex/maestro-flow/commands/manage/learn.md

@@ -0,0 +1,137 @@
+---
+name: manage-learn
+description: Capture atomic learning insights into .workflow/learning/lessons.jsonl. Lightweight CRUD over the shared learning store — supports capture, list, search, and show modes. No LLM or CLI calls; all operations are pure file reads and writes.
+argument-hint: "[\"<insight text>\"|list|search <query>|show <INS-id>] [--category pattern|antipattern|decision|tool|gotcha|technique] [--tag t1,t2] [--phase N] [--confidence high|medium|low]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+<purpose>
+Pure file-operation CRUD skill for the workflow learning library. No agent spawning, no CLI calls, no LLM inference — just parse-infer-append-confirm. Complements `quality-retrospective`: where retrospective extracts insights in bulk from completed phases, `manage-learn` captures one timeless insight at a time during active work. Both write to the same `lessons.jsonl` store, disambiguated by `source` and `lens` fields.
+
+```
+Parse Mode  →  Bootstrap Store  →  Execute Mode  →  Confirm
+(capture /       (on first use)     (Bash/Read/      (INS-id
+  list /          Bash+Write)        Write/Grep)      + hints)
+  search /
+  show)
+```
+</purpose>
+
+<context>
+$ARGUMENTS — mode token followed by options.
+
+```bash
+$manage-learn "Always read state.json before planning to detect current phase"
+$manage-learn "list --limit 10 --category antipattern"
+$manage-learn "search context propagation"
+$manage-learn "show INS-a3f7b2c1"
+$manage-learn "\"Zod v4 breaks z.object().strict() API\" --category gotcha --tag zod,typescript"
+```
+
+**Flags** (capture mode):
+- `--category <name>` — `pattern|antipattern|decision|tool|gotcha|technique`. Default: inferred from text keywords.
+- `--tag t1,t2` — Comma-separated tags. Always adds `manual` implicitly.
+- `--phase <N>` — Override auto-detected current phase. `--phase 0` forces no phase link.
+- `--confidence high|medium|low` — Default: medium.
+
+**Flags** (list/search mode):
+- `--tag t1,t2` — Filter by tag
+- `--category <name>` — Filter by category
+- `--phase <N>` — Filter by phase
+- `--lens <name>` — Filter by retrospective lens (technical|process|quality|decision)
+- `--limit <N>` — Row limit (default 20)
+
+**Storage**:
+- `.workflow/learning/lessons.jsonl` — append-only JSONL (shared with `quality-retrospective`)
+- `.workflow/learning/learning-index.json` — searchable index
+</context>
+
+<invariants>
+1. **No LLM or CLI calls**: This skill is pure file I/O — parse, infer, append, confirm. No `exec_command`, no `spawn_agent`.
+2. **Bootstrap on demand**: Create `.workflow/learning/` structure on first use; do not require it to exist.
+3. **Append-only lessons.jsonl**: Never rewrite or delete existing rows.
+4. **Stable INS-ids**: `INS-{8hex}` from `hash(insightText + timestamp)` — same text at different times gets different ids.
+5. **Source field**: Always `"manual"` for captures from this skill; `"retrospective"` is reserved for `quality-retrospective`.
+6. **Phase auto-link**: Read `state.json` automatically; `--phase 0` is the only way to force null.
+7. **Keyword inference is approximate**: When in doubt, default to `pattern` category rather than prompting user.
+</invariants>
+
+<execution>
+
+### Step 1: Parse Mode and Validate Arguments
+
+Parse the first non-flag token from `$ARGUMENTS`:
+
+| First token | Mode |
+|-------------|------|
+| `list` | list |
+| `search` followed by query | search |
+| `show` followed by INS-id | show |
+| Empty | Prompt with `functions.request_user_input` |
+| Any other text (quoted or not) | capture |
+
+Validate `--category` if provided (allowed: pattern, antipattern, decision, tool, gotcha, technique). E002 if unknown.
+
+### Step 2: Bootstrap Learning Store (on first use)
+
+Verify `.workflow/` exists (E001 if not). If `.workflow/learning/lessons.jsonl` missing: create directory, empty `lessons.jsonl`, and initialize `learning-index.json` with `{"version":1,"entries":[]}`.
+
+### Step 3: Execute Mode
+
+#### Capture Mode
+
+1. **Infer category** from keywords (no LLM):
+
+| Keywords | Category |
+|----------|----------|
+| always, should, prefer, best practice | pattern |
+| never, avoid, don't, pitfall, breaks | antipattern |
+| decided, chose, tradeoff, because | decision |
+| tool, library, framework, package | tool |
+| gotcha, surprising, unexpected | gotcha |
+| technique, approach, method | technique |
+
+2. **Auto-link phase** from `state.json` artifact registry. `--phase 0` forces null.
+3. **Generate INS-id**: `INS-{8 hex}` from `hash(insightText + timestamp)`.
+4. **Build row** with fields: id, title (first 80 chars), summary, source="manual", lens=null, category, tags (includes "manual"), phase, phase_slug, confidence, routed_to=null, created_at.
+5. **Append** JSON line to `lessons.jsonl` (append-only, never rewrite).
+6. **Update** `learning-index.json`: push entry with id, title, category, tags, phase, created_at.
+
+#### List Mode
+
+Read `learning-index.json`, apply filters (`--tag`, `--category`, `--phase`, `--lens`), sort newest-first, display up to `--limit` rows (default 20) as table.
+
+#### Search Mode
+
+Grep `lessons.jsonl` for query. Rank by field weight: title (3) > tags (2) > summary (1). Display top matches.
+
+#### Show Mode
+
+Validate `INS-[0-9a-f]{8}` format. Find matching row, display full record. Show linked artifact if `routed_to` is set.
+
+### Step 4: Display Confirmation
+
+Capture mode: display ID, category, phase, confidence, tags, and next-step commands (`$manage-learn "list"`, `$manage-learn "search ..."`).
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | error | `.workflow/` not initialized — run `$maestro-init` first | parse_input |
+| E002 | error | Unknown `--category` value | parse_input |
+| E003 | error | `show` mode requires INS-id argument | show |
+| E004 | error | INS-id not found in lessons.jsonl | show |
+| W001 | warning | Auto-phase detection: no matching artifact directory found; phase set to null | capture |
+| W002 | warning | `learning-index.json` row count differs from `lessons.jsonl`; offer to rebuild index | list/search |
+</error_codes>
+
+<success_criteria>
+- [ ] Mode parsed correctly (capture, list, search, show)
+- [ ] Learning store bootstrapped on first use
+- [ ] Capture: category inferred from keywords, phase auto-linked, INS-id generated
+- [ ] Capture: row appended to lessons.jsonl (append-only), index updated
+- [ ] List: filters applied, newest-first, respects --limit
+- [ ] Search: grep with weighted ranking across title/tags/summary
+- [ ] Show: full record displayed for valid INS-id
+- [ ] No LLM or CLI calls — pure file I/O only
+</success_criteria>

package/codex/maestro-flow/commands/manage/status.md

@@ -0,0 +1,76 @@
+---
+name: manage-status
+description: Display project dashboard with phase progress, active tasks, and next steps
+argument-hint: ""
+allowed-tools: Read, Bash, Glob, Grep
+---
+
+<purpose>
+Display project dashboard with phase progress, active tasks, and suggested next steps. Reads `.workflow/` state files and renders a formatted project overview. No arguments required.
+</purpose>
+
+<context>
+$ARGUMENTS — none required.
+
+```bash
+$manage-status
+```
+
+Reads from:
+- `.workflow/state.json` — project-level state machine
+- `.workflow/roadmap.md` — milestone and phase structure
+- `.workflow/scratch/*/index.json` — per-phase metadata and progress (resolved via state.json artifact registry)
+- `.workflow/scratch/*/.task/TASK-*.json` — individual task statuses (resolved via state.json artifact registry)
+- `.workflow/wiki-index.json` — unified wiki graph index (entry counts, health)
+</context>
+
+<execution>
+
+### Step 1: Validate Project
+
+Verify `.workflow/` exists (E001) and `state.json` is present (E002).
+
+### Step 2: Load State Files
+
+Read: `state.json`, `roadmap.md`, per-phase `scratch/*/index.json`, task files `scratch/*/.task/TASK-*.json` (all resolved via artifact registry).
+
+### Step 3: Calculate Progress
+
+For each phase directory found:
+1. Count total tasks, completed, failed, blocked, pending
+2. Calculate completion percentage
+3. Determine phase status from index.json
+
+### Step 4: Render Dashboard
+
+Display sections: **Milestones & Phases** (per-phase status, progress bars, completion %), **Active Work** (in-progress and blocked tasks), **Knowledge Graph** (wiki entry counts by type, health score, orphans), **Next Steps** (state-based suggestion).
+
+### Step 5: Suggest Next Steps
+
+Use this decision table to suggest the next action:
+
+| Current State | Suggestion |
+|---------------|------------|
+| No phases planned | `Skill({ skill: "maestro-flow", args: "--cmd maestro-brainstorm" })` or `Skill({ skill: "maestro-flow", args: "--cmd maestro-plan" })` |
+| Phase planned, not executed | `Skill({ skill: "maestro-flow", args: "--cmd maestro-execute <N>" })` |
+| Phase executed, not verified | `Skill({ skill: "maestro-flow", args: "--cmd maestro-verify <N>" })` |
+| Phase verified with gaps | `Skill({ skill: "maestro-flow", args: "--cmd maestro-plan <N> --gaps" })` |
+| Phase reviewed PASS/WARN | `Skill({ skill: "maestro-flow", args: "--cmd quality-test <N>" })` |
+| UAT passed | `Skill({ skill: "maestro-flow", args: "--cmd maestro-milestone-audit" })` |
+| All milestone phases done | `Skill({ skill: "maestro-flow", args: "--cmd maestro-milestone-audit" })` |
+</execution>
+
+<error_codes>
+| Code | Severity | Description |
+|------|----------|-------------|
+| E001 | fatal | `.workflow/` not initialized -- run `Skill({ skill: "maestro-flow", args: "--cmd maestro-init" })` first |
+| E002 | fatal | `state.json` missing or corrupt |
+</error_codes>
+
+<success_criteria>
+- [ ] `.workflow/` and `state.json` validated
+- [ ] All state sources loaded (state.json, roadmap, phase indexes, task files)
+- [ ] Progress calculated per phase (total, completed, failed, blocked, pending, percentage)
+- [ ] Dashboard rendered with milestones, phases, active work, and next steps
+- [ ] Next step suggestion matches current project state via decision table
+</success_criteria>

package/codex/maestro-flow/commands/manage/wiki.md

@@ -0,0 +1,55 @@
+---
+name: manage-wiki
+description: Wiki knowledge graph management — health dashboard, orphan cleanup, entry search, and graph statistics
+argument-hint: "[health|search|cleanup|stats] [options]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+<purpose>
+Unified wiki graph management. Health monitoring, interactive search, orphan cleanup, and graph statistics. Day-to-day operations to keep the knowledge graph healthy.
+
+Complements `wiki-connect` (link discovery) and `wiki-digest` (synthesis) with operational tooling.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/wiki-manage.md
+</required_reading>
+
+<context>
+$ARGUMENTS — subcommand and optional flags.
+
+**Subcommands:**
+| Subcommand | Description |
+|-----------|-------------|
+| `health` | Health dashboard — score, broken links, orphans, hubs (default) |
+| `search <query>` | Interactive BM25 search with follow-up actions |
+| `cleanup` | Find and resolve orphans, broken links, stale entries |
+| `stats` | Graph statistics — type distribution, tag frequency, growth |
+
+**Flags:**
+- `--type <type>` — Filter: spec, knowhow, note, lesson, issue
+- `--fix` — Auto-fix issues during cleanup
+- `--json` — JSON output
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/wiki-manage.md' completely.
+</execution>
+
+<error_codes>
+| Code | Severity | Description |
+|------|----------|-------------|
+| E001 | fatal | `.workflow/` not initialized |
+| E002 | fatal | No wiki entries found |
+| E003 | error | Invalid subcommand |
+| W001 | warning | Health score below 50 |
+| W002 | warning | Cleanup had partial failures |
+</error_codes>
+
+<success_criteria>
+- [ ] Subcommand parsed (health/search/cleanup/stats)
+- [ ] Wiki data loaded via `maestro wiki` CLI
+- [ ] Results displayed in formatted output
+- [ ] If cleanup --fix: issues resolved and delta reported
+- [ ] Next-step suggestions provided
+</success_criteria>

package/codex/maestro-flow/commands/milestone/audit.md

@@ -0,0 +1,87 @@
+---
+name: maestro-milestone-audit
+description: Audit current milestone using artifact registry for cross-phase integration gaps and produce verdict report
+argument-hint: "[milestone, e.g., 'M1']"
+allowed-tools: Read, Write, Bash, Glob, Grep, Agent
+---
+
+<purpose>
+Sequential audit based on artifact registry in state.json. Checks phase coverage (ANL->PLN->EXC chains), ad-hoc completeness, execution completeness, and cross-artifact integration. Produces PASS/FAIL verdict report.
+</purpose>
+
+<context>
+
+```bash
+$maestro-milestone-audit ""
+$maestro-milestone-audit "M1"
+```
+
+**Output**: Audit report with artifact chain verification, integration analysis, and PASS/FAIL verdict
+
+</context>
+
+<invariants>
+1. **Artifact registry is source of truth** — don't scan directories, read state.json
+2. **Non-blocking warnings** — missing analyze is warning, missing execute is error
+3. **Integration check is required** — always spawn checker agent
+4. **Clear verdict** — PASS or FAIL with specific reasons
+</invariants>
+
+<execution>
+
+### Step 1: Parse Arguments
+
+Extract milestone identifier from arguments. Fallback: read `current_milestone` from `.workflow/state.json`. If still empty: E001.
+
+### Step 2: Load Artifact Registry
+
+Read `.workflow/state.json` and `.workflow/roadmap.md`. Filter `artifacts[]` by milestone, parse phase list, group by type and phase.
+
+### Step 3: Phase Coverage Check
+
+For each phase: check for completed analyze (optional), plan (required), execute (required) artifacts. Report coverage matrix.
+
+### Step 4: Ad-hoc & Execution Completeness
+
+Verify all adhoc-scoped artifacts completed. For each execute artifact, verify all tasks in plan dir completed.
+
+### Step 5: Integration Check
+
+Spawn Agent for cross-phase validation: shared interfaces, dependency chains, data contracts, API consistency. Write report to `.workflow/milestones/{milestone}/audit-report.md`.
+
+### Step 6: Verdict
+
+**PASS**: All phases have completed EXC artifacts, no critical integration gaps, all adhoc completed.
+**FAIL**: Missing EXC artifacts or critical integration gaps found.
+
+Display structured audit report.
+
+**Next-step routing:**
+
+| Verdict | Next Step |
+|---------|-----------|
+| PASS | `$maestro-milestone-complete "{milestone}"` |
+| FAIL, integration gaps | `$maestro-plan "--gaps"` |
+| FAIL, incomplete execution | `$maestro-execute` |
+
+</execution>
+
+<error_codes>
+
+| Code | Severity | Description | Recovery |
+|------|----------|-------------|----------|
+| E001 | error | Milestone identifier required | Specify milestone or ensure current_milestone is set |
+| E002 | error | Milestone not found in state.json | Check milestone ID |
+| E003 | error | No execute artifacts found | Run maestro-execute first |
+| W001 | warning | Some phases lack analyze artifacts | Note: analysis optional but recommended |
+
+</error_codes>
+
+<success_criteria>
+- [ ] Artifact registry loaded and filtered by milestone
+- [ ] Phase coverage matrix generated
+- [ ] Ad-hoc and execution completeness verified
+- [ ] Integration check performed via agent
+- [ ] Audit report written to milestones/ directory
+- [ ] Clear PASS/FAIL verdict with specific reasons
+</success_criteria>

package/codex/maestro-flow/commands/milestone/complete.md

@@ -0,0 +1,91 @@
+---
+name: maestro-milestone-complete
+description: Archive completed milestone scratch artifacts to milestones/ dir, move artifact entries to milestone_history, extract learnings, advance state.
+argument-hint: "[milestone] [--force] [-y]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+<purpose>
+Sequential milestone archival: validate audit → archive scratch dirs → extract learnings → move artifact entries to milestone_history → advance state → clean scratch.
+</purpose>
+
+<context>
+
+```bash
+$maestro-milestone-complete "M1"
+$maestro-milestone-complete              # uses current_milestone from state.json
+$maestro-milestone-complete --force "M1"  # skip audit check
+```
+
+**Output**: `.workflow/milestones/{milestone}/` archive directory
+
+</context>
+
+<invariants>
+1. **Audit before archive** — refuse without passing audit (unless --force)
+2. **Atomic state update** — write state.json via tmp+rename
+3. **Learnings are mandatory** — always extract before archiving
+4. **Clean after archive** — remove scratch dirs only after successful copy
+5. **Advance state** — always set next milestone or mark project complete
+</invariants>
+
+<execution>
+
+### Step 1: Parse & Validate
+
+Read `.workflow/state.json` for `current_milestone`, `artifacts[]`, `milestones[]`. Determine target from args or current_milestone (E001 if none). Validate audit report at `.workflow/milestones/{milestone}/audit-report.md` with PASS verdict (E002 unless `--force`). Verify all milestone artifacts completed (E003 unless `--force`).
+
+### Step 2: Archive Scratch Dirs
+
+Copy each milestone artifact's directory to `.workflow/milestones/{milestone}/artifacts/`. Snapshot `roadmap.md` as `roadmap-snapshot.md` in the milestone archive.
+
+### Step 3: Extract Learnings
+
+Read `.summaries/` and `reflection-log.md` from execute artifacts. Extract patterns, pitfalls, strategy adjustments. Dedup against existing entries via `maestro spec load --category learning`. Append to `.workflow/specs/learnings.md` using `<spec-entry>` closed-tag format (category=`learning`, auto-extract keywords, date=today, source=`milestone-complete`).
+
+### Step 3b: Knowledge Promotion Inquiry
+
+1. **High-frequency patterns**: Scan learning entries for keyword overlap (>=2 entries) -- offer promotion to coding convention via `/spec-add coding`
+2. **Convention drift**: Compare summaries against `coding-conventions.md` and `architecture-constraints.md` -- ask if conventions need updating
+3. **Wiki island check**: Auto-trigger `wiki-connect --fix` to link new knowledge
+
+If `-y`: auto-accept all promotions without asking.
+If not `-y`: ask user for confirmation. If user confirms, append `<spec-entry>` to target category file preserving original date and source.
+
+### Step 4: Archive Artifact Entries
+
+Move milestone artifacts from `state.json.artifacts[]` to `milestone_history[]` with completion metadata (id, name, status, completed_at, archive_path, archived_artifacts). Remove from active `artifacts[]`.
+
+### Step 5: Advance State
+
+Set `current_milestone` to next pending milestone (mark it active), or set project `status: "completed"` if none remain. Atomic write to `state.json`.
+
+### Step 6: Clean Scratch
+
+Remove archived artifact directories from `.workflow/`.
+
+### Step 7: Generate Summary & Report
+
+Write `.workflow/milestones/{milestone}/summary.md` with outcomes and learnings. Update `.workflow/project.md` Context section. Display completion report with next steps: `$maestro-milestone-release`, `$maestro-analyze`, `$manage-status`, `$manage-wiki health`, `$wiki-digest`.
+
+</execution>
+
+<error_codes>
+
+| Code | Severity | Description | Recovery |
+|------|----------|-------------|----------|
+| E001 | error | Milestone identifier required | Specify milestone |
+| E002 | error | Audit not passed | Run milestone-audit first |
+| E003 | error | Incomplete artifacts remain | Complete work first |
+
+</error_codes>
+
+<success_criteria>
+- [ ] Audit report validated (or --force used)
+- [ ] Scratch directories archived to milestones/
+- [ ] Learnings extracted and appended to specs/learnings.md
+- [ ] Artifact entries moved to milestone_history in state.json
+- [ ] State advanced to next milestone (or project marked complete)
+- [ ] Scratch directories cleaned
+- [ ] Summary and completion report generated
+</success_criteria>

package/codex/maestro-flow/commands/milestone/release.md

@@ -0,0 +1,70 @@
+---
+name: maestro-milestone-release
+description: Version bump, changelog generation, and git tag for a completed milestone. Auto-detects version manifest (package.json, pyproject.toml, Cargo.toml), generates changelog from milestone summaries + git log, creates annotated tag.
+argument-hint: "[<version>] [--bump patch|minor|major] [--dry-run] [--no-tag] [--no-push]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+<purpose>
+Package a completed milestone into a releasable version. Bumps project version in manifest,
+generates CHANGELOG.md entry from phase/milestone summaries and git log, creates annotated
+git tag, optionally pushes to remote. Runs after `/maestro-milestone-complete`.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/milestone-release.md
+</required_reading>
+
+<context>
+$ARGUMENTS — optional explicit version and flags.
+
+**Flags:**
+- `<version>` — Explicit version (e.g. `1.2.0`). If omitted, derived from `--bump`.
+- `--bump patch|minor|major` — Semver bump (default: `minor`)
+- `--dry-run` — Compute version + changelog without writing
+- `--no-tag` — Skip git tag creation
+- `--no-push` — Skip `git push --follow-tags`
+
+**Preconditions:**
+- Current milestone completed (audit PASS + milestone-complete run)
+- Working tree clean (no uncommitted changes) unless `--dry-run`
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/milestone-release.md' completely.
+
+**Flow:** Validate preconditions → Resolve version → Collect changes → Generate CHANGELOG →
+Bump manifest → Commit → Tag → Push
+
+**Report:**
+```
+=== RELEASE COMPLETE ===
+Version:   v{previous} → v{new}
+Milestone: {name}
+Tag:       v{new} {pushed|local-only}
+Changelog: {N} entries
+```
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Milestone not completed | Run `$maestro-milestone-complete` first |
+| E002 | error | Audit verdict not PASS | Re-run `$maestro-milestone-audit` |
+| E003 | error | Working tree not clean | Commit or stash changes |
+| E004 | error | Version manifest not found | Add manifest or pass explicit version |
+| E005 | error | Version not greater than current | Choose higher version |
+| W001 | warning | No changes since last tag | Confirm release is desired |
+| W002 | warning | Remote push failed | Retry `git push --follow-tags` |
+</error_codes>
+
+<success_criteria>
+- [ ] Preconditions validated
+- [ ] Target version computed and greater than previous
+- [ ] Version manifest(s) updated
+- [ ] CHANGELOG.md entry with milestone summary + grouped changes
+- [ ] Release commit created
+- [ ] Annotated git tag created (unless --no-tag)
+- [ ] Pushed to remote (unless --no-push)
+- [ ] state.json updated with last_release_version
+</success_criteria>