maestro-flow-one 0.1.3 → 0.2.1

package/maestro-flow/commands/manage/issue.md

@@ -0,0 +1,73 @@
+---
+name: manage-issue
+description: Create, query, update, close, and link issues
+argument-hint: "<create|list|status|update|close|link> [options]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+<purpose>
+Issue lifecycle management for the project issue tracker. Supports create, list, status, update, close, and link (bidirectional issue-task cross-reference). All issues stored in `.workflow/issues/issues.jsonl` using the issue.json schema.
+
+For automated issue discovery, use `/manage-issue-discover`.
+
+**Closed-loop workflow**: After creating an issue, use `/maestro-analyze --gaps <ISS-ID>` for root cause analysis, `/maestro-plan --gaps` for solution planning, and `/maestro-execute` for execution.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/issue.md
+</required_reading>
+
+<deferred_reading>
+- [issue.json template](~/.maestro/templates/issue.json) — read when creating or updating issue records (create, update, close)
+</deferred_reading>
+
+<context>
+$ARGUMENTS -- subcommand + options. Parse first token as subcommand.
+
+**Valid subcommands:**
+- `create` -- create a new issue (--title, --severity, --source, --phase, --description)
+- `list` -- list issues with optional filters (--status, --phase, --severity, --source)
+- `status` -- show full detail for a specific issue (ISS-XXXXXXXX-NNN)
+- `update` -- update issue fields (ISS-XXXXXXXX-NNN --status, --priority, --severity, --tags, ...)
+- `close` -- close an issue with resolution (ISS-XXXXXXXX-NNN --resolution)
+- `link` -- link issue to a task (ISS-XXXXXXXX-NNN --task TASK-NNN)
+
+**State files:**
+- `.workflow/issues/issues.jsonl` -- active issues (one JSON per line)
+- `.workflow/issues/issue-history.jsonl` -- archived/closed issues
+</context>
+
+<execution>
+Parse subcommand from first token of $ARGUMENTS.
+Follow '~/.maestro/workflows/issue.md' completely.
+
+**Next-step routing on completion:**
+- create → `/maestro-analyze --gaps <ISS-ID>` or `/maestro-plan --gaps`
+- list → `/maestro-analyze --gaps <ISS-ID>` for any open issue
+- close → `/manage-status`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E_NO_SUBCOMMAND | error | No subcommand provided in $ARGUMENTS | Display valid subcommands, prompt user to select |
+| E_INVALID_SUBCOMMAND | error | Unrecognized subcommand | Display valid subcommands with usage hints |
+| E_ISSUES_DIR_MISSING | warning | `.workflow/issues/` directory does not exist | Auto-create directory and empty issues.jsonl |
+</error_codes>
+
+<success_criteria>
+- [ ] Subcommand parsed and routed to correct handler
+- [ ] Issue data read/written to correct JSONL file
+- [ ] Output displayed in appropriate format (table for list, detail for status)
+- [ ] Cross-references maintained (link creates bidirectional references)
+- [ ] Next step routing by subcommand:
+  - create → `/maestro-analyze --gaps <ISS-ID>` or `/maestro-plan --gaps`
+  - list → `/maestro-analyze --gaps <ISS-ID>` for any open issue
+  - close → `/manage-status`
+</success_criteria>

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

@@ -0,0 +1,193 @@
+---
+name: manage-knowhow-capture
+description: Capture reusable knowledge as templates, recipes, or tips
+argument-hint: "[type] [description] [--lang <lang>] [--source <url>] [--tag tag1,tag2]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+<purpose>
+Capture reusable knowledge into `.workflow/knowhow/` with type-specific structured fields.
+Six content types, each optimized for a different reuse pattern. All entries are automatically
+indexed by WikiIndexer (type=knowhow) and searchable via `maestro knowhow search`.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/knowhow.md
+</required_reading>
+
+<context>
+Arguments: $ARGUMENTS
+
+**Types:**
+
+| Type | Prefix | Use Case | Key Fields |
+|------|--------|----------|------------|
+| `compact` | KNW- | Session state recovery | objective, files, decisions, plan, pending |
+| `template` | TPL- | Code/config templates | language, code block, usage context |
+| `recipe` | RCP- | Step-by-step how-to | prerequisites, steps, expected outcome |
+| `reference` | REF- | External doc / API quick-ref | source URL, key points, scenarios |
+| `decision` | DCS- | Design decision record | context, alternatives, rationale, consequences |
+| `tip` | TIP- | Quick note / reminder | content, tags |
+
+No arguments: auto-detect type or ask user via AskUserQuestion.
+
+**Flags:**
+- `--lang <lang>` — Language for templates (typescript, python, bash, yaml, etc.)
+- `--source <url>` — Source URL for references
+- `--tag tag1,tag2` — Categorization tags
+- `--title <title>` — Explicit title (auto-generated if omitted)
+</context>
+
+<execution>
+
+### Step 1: Detect Type
+
+Parse first token as type. If ambiguous, AskUserQuestion with options:
+
+| Token Match | Type |
+|-------------|------|
+| `compact`, `session`, `压缩`, `保存` | compact |
+| `template`, `tpl`, `模板` | template |
+| `recipe`, `rcp`, `配方`, `步骤` | recipe |
+| `reference`, `ref`, `参考`, `引用` | reference |
+| `decision`, `dcs`, `决策`, `adr` | decision |
+| `tip`, `note`, `记录`, `快速` | tip |
+| No match, short text, `--tag` present | tip |
+| No arguments | AskUserQuestion (6 options) |
+
+### Step 2: Generate Content by Type
+
+#### compact (KNW-{YYYYMMDD}-{HHMM}.md)
+
+Extract from conversation history:
+- **Session ID** — WFS-* if workflow session active, else `manual-{date}`
+- **Project Root** — Absolute path
+- **Objective** — High-level goal
+- **Execution Plan** — Source + complete verbatim content (never summarize)
+- **Working Files** — Modified files with roles (absolute paths, 3-8 files)
+- **Reference Files** — Read-only context files
+- **Last Action** — Final action + result
+- **Decisions** — Table: decision | reasoning
+- **Constraints** — User-specified limitations
+- **Dependencies** — Added/changed packages
+- **Known Issues** — Deferred bugs
+- **Changes Made** — Completed modifications
+- **Pending** — Next steps
+- **Notes** — Unstructured thoughts
+
+Plan detection priority: workflow session IMPL_PLAN.md > TodoWrite items > user-stated > inferred.
+
+#### template (TPL-{YYYYMMDD}-{HHMM}.md)
+
+Ask for or extract:
+- **Language / Tech** — `--lang` flag or inferred from context
+- **Usage** — When/how to use this template
+- **Code** — The template content (ask user to provide or select from conversation)
+- **Parameters** — Placeholders to replace (e.g. `{{name}}`, `{{port}}`)
+- **Dependencies** — Required packages/config
+- **Tags** — From `--tag` flag
+
+If code not provided explicitly, prompt user: "Paste the template code:"
+
+#### recipe (RCP-{YYYYMMDD}-{HHMM}.md)
+
+Ask for or extract:
+- **Goal** — What this recipe accomplishes
+- **Prerequisites** — Tools, access, config needed
+- **Steps** — Numbered step-by-step instructions
+- **Expected Outcome** — What success looks like
+- **Common Pitfalls** — Known issues / gotchas
+- **Related** — Links to templates, references, decisions used
+- **Tags** — From `--tag` flag
+
+If steps not clear, prompt user: "Describe the steps (numbered list):"
+
+#### reference (REF-{YYYYMMDD}-{HHMM}.md)
+
+Ask for or extract:
+- **Source** — `--source` flag (URL, doc title, API endpoint)
+- **Key Points** — Bullet list of essential info
+- **Applicable Scenarios** — When to consult this reference
+- **Quick Examples** — Copy-paste ready code snippets
+- **Last Verified** — Date (today)
+- **Tags** — From `--tag` flag
+
+If `--source` provided, offer to fetch and summarize via WebFetch.
+
+#### decision (DCS-{YYYYMMDD}-{HHMM}.md)
+
+Ask for or extract:
+- **Context** — Background and problem statement
+- **Decision** — What was decided
+- **Alternatives Considered** — Table: alternative | pros | cons | rejected because
+- **Rationale** — Why this choice over alternatives
+- **Consequences** — Positive and negative impact
+- **Related** — Links to affected specs, recipes, templates
+- **Date** — Decision date
+- **Status** — proposed | accepted | superseded
+
+#### tip (TIP-{YYYYMMDD}-{HHMM}.md)
+
+Simple note:
+- **Content** — Everything after type token (or full $ARGUMENTS)
+- **Context** — Auto-detected from recent conversation files
+- **Tags** — From `--tag` flag
+- **Timestamp** — ISO format
+
+### Step 3: Write File
+
+Write to `.workflow/knowhow/{PREFIX}-{YYYYMMDD}-{HHMM}.md` with YAML frontmatter:
+
+```yaml
+---
+title: {auto or --title}
+type: {type}
+category: {type}
+created: {ISO timestamp}
+tags: [{tags}]
+source: {url if reference}
+lang: {language if template}
+status: {status if decision}
+---
+{markdown body}
+```
+
+### Step 4: Confirm
+
+```
+=== KNOWHOW CAPTURED ===
+Type: {type}
+ID:   knowhow-{slug}
+File: .workflow/knowhow/{filename}
+
+{type-specific summary line}
+```
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | error | `.workflow/` not initialized — run `/maestro-init` first | validate |
+| E002 | error | Template: no code provided after prompt | template |
+| E003 | error | Recipe: no steps provided after prompt | recipe |
+| W001 | warning | No active workflow session — compact captures conversation only | compact |
+| W002 | warning | Plan detection found no explicit plan — using inferred plan | compact |
+| W003 | warning | `--source` URL could not be fetched — proceeding with manual entry | reference |
+</error_codes>
+
+<success_criteria>
+- [ ] Type correctly detected or selected
+- [ ] All type-specific fields populated (not empty)
+- [ ] YAML frontmatter written with correct fields
+- [ ] Markdown body follows type structure
+- [ ] File written to `.workflow/knowhow/` with correct prefix
+- [ ] Auto-indexed by WikiIndexer (type=knowhow)
+- [ ] Confirmation displayed with ID, type, file path
+- [ ] Next step hint appropriate to type shown
+</success_criteria>

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

@@ -0,0 +1,77 @@
+---
+name: manage-knowhow
+description: Manage knowhow entries (workflow and system)
+argument-hint: "[list|search|view|edit|delete|prune] [query|id|file] [--store workflow|system|all] [--tag tag] [--type compact|tip]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+<purpose>
+Unified memory management across two stores:
+1. **Workflow knowhow** (`.workflow/knowhow/`) — Session compacts and tips with JSON index, created by `manage-knowhow-capture`
+2. **System memory** (`~/.claude/projects/{project}/memory/`) — Claude Code auto-memory (MEMORY.md + topic files), persists across conversations
+
+Provides list/search/view/edit/delete/prune operations. Default store is `all` (show both).
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/knowhow.md
+</required_reading>
+
+<context>
+Arguments: $ARGUMENTS
+
+Dual store architecture (paths, formats, index) defined in workflow knowhow.md.
+
+**Subcommands:**
+- `list` — List entries from both stores (default if no arguments)
+- `search <query>` — Full-text search across both stores
+- `view <id|file>` — Display a workflow entry by ID or system file by name
+- `edit <file>` — Edit a system memory file (MEMORY.md or topic file)
+- `delete <id|file>` — Remove an entry/file (with confirmation)
+- `prune` — Bulk cleanup by criteria
+
+**Flags:**
+- `--store <workflow|system|all>` — Target store (default: `all` for list/search, inferred for other ops)
+- `--tag <tag>` — Filter by tag (workflow store)
+- `--type <compact|tip>` — Filter by entry type (workflow store)
+- `--before <YYYY-MM-DD>` — Entries before date
+- `--after <YYYY-MM-DD>` — Entries after date
+- `--dry-run` — Preview destructive ops without executing
+- `--confirm` — Skip confirmation prompt
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/knowhow.md' Part A (KnowHow Management) completely.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | error | No memory stores found — run `/manage-knowhow-capture` or create MEMORY.md | resolve_paths |
+| E002 | error | Entry ID or filename not found | execute_view, execute_delete |
+| E003 | error | Prune requires at least one filter (--tag, --type, --before, --after) | execute_prune |
+| E004 | error | Cannot delete MEMORY.md — use `edit` subcommand instead | execute_delete |
+| W001 | warning | Workflow index has orphaned files or dangling references | integrity_check |
+| W002 | warning | MEMORY.md references non-existent topic file | integrity_check |
+| W003 | warning | MEMORY.md exceeds 200 lines — content will be truncated at load | execute_edit |
+</error_codes>
+
+<success_criteria>
+- [ ] Both store paths correctly resolved
+- [ ] Subcommand correctly detected from arguments
+- [ ] Store auto-detected from argument format (KNW-*/TIP-* vs filename)
+- [ ] List: both stores displayed with appropriate formatting
+- [ ] Search: results from both stores, ranked by relevance
+- [ ] View: correct store selected, full content displayed
+- [ ] Edit: system memory files editable, MEMORY.md kept under 200 lines
+- [ ] Delete: MEMORY.md protected, confirmation required, references checked
+- [ ] Prune: workflow-only, filters validated, index updated
+- [ ] Integrity check catches orphans and broken links
+- [ ] Next step: `/manage-knowhow-capture compact` to save new knowhow, or `/manage-status` to continue workflow
+</success_criteria>

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

@@ -0,0 +1,67 @@
+---
+name: manage-learn
+description: Capture and search learning insights and tips
+argument-hint: "[<text>|tip <text>|list|search|show <id>] [--category ...] [--tag t1,t2] [--phase N] [--confidence ...]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+<purpose>
+Unified atomic knowledge capture for the workflow learning library. Captures two types of knowledge:
+- **Insights**: Timeless "eureka moment" entries (patterns, gotchas, techniques) — the default mode
+- **Tips**: Quick contextual notes for cross-session recovery (formerly in `manage-knowhow-capture tip`)
+
+Both types are stored in `.workflow/learning/lessons.jsonl` with auto-detected phase linkage and keyword-based category inference. Tips are distinguished by `source: "tip"` and implicitly tagged `tip`. Same store as retrospective output, so search and list see the entire knowledge corpus.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/learn.md
+</required_reading>
+
+<context>
+Arguments: $ARGUMENTS
+
+**Modes (auto-detected from first token):**
+- `"<insight text>"` (or any non-keyword text) → insight capture mode
+- `tip <text>` → tip capture mode (quick contextual note, auto-tagged `tip`)
+- `list` → list recent entries (default 20)
+- `search <query>` → text search across lessons.jsonl
+- `show <INS-id>` → full detail with phase context
+- empty → AskUserQuestion to prompt for text
+
+Flags, storage paths, and shared store rationale defined in workflow learn.md.
+</context>
+
+<execution>
+Follow `~/.maestro/workflows/learn.md` Stages 1–5 in order.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | error | `.workflow/` not initialized — run `/maestro-init` first | parse_input |
+| E002 | error | Unknown `--category` value (allowed: pattern, antipattern, decision, tool, gotcha, technique, tip) | parse_input |
+| E003 | error | `show` mode requires an INS-id argument | show |
+| E004 | error | Insight id not found in lessons.jsonl | show |
+| W001 | warning | Auto-phase detection found a current_phase but no matching artifact in registry; phase set to null | capture |
+| W002 | warning | learning-index.json out of sync with lessons.jsonl (different row count); offer to rebuild | list/search |
+</error_codes>
+
+<success_criteria>
+- [ ] Mode correctly routed (capture / list / search / show)
+- [ ] Capture: `lessons.jsonl` row appended with valid JSON and all required fields
+- [ ] Capture: `learning-index.json` updated with matching entry
+- [ ] Capture: phase auto-link resolves correctly via artifact registry when `state.json` has `current_phase`
+- [ ] Capture: category inference produces a sensible default when `--category` absent
+- [ ] List: filters apply, output sorted newest-first, default limit 20
+- [ ] Search: results ranked by title (3) > tags (2) > summary (1) match
+- [ ] Show: full insight displayed with phase context and routed-artifact link if any
+- [ ] No file modifications outside `.workflow/learning/`
+- [ ] Confirmation banner displayed with INS-id and next-step hints
+- [ ] Next step: `/manage-learn list` to browse, or `/manage-learn search <query>` to find related insights
+</success_criteria>

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

@@ -0,0 +1,51 @@
+---
+name: manage-status
+description: Show project dashboard with progress and next steps
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+---
+<purpose>
+Display a unified project dashboard showing artifact progress, task counts, active work, and intelligent next-step suggestions.
+Reads state.json artifact registry and roadmap to render a formatted overview with progress and status tables.
+Provides situational awareness before continuing work. Uses virtual phase view derived from artifact registry.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/status.md
+</required_reading>
+
+<context>
+$ARGUMENTS (no arguments required)
+
+**State files read:**
+- `.workflow/state.json` -- project-level state machine + artifact registry
+- `.workflow/roadmap.md` -- milestone and phase structure
+- `.workflow/scratch/*/plan.json` -- plan metadata (via artifact registry paths)
+- `.workflow/scratch/*/.task/TASK-*.json` -- individual task statuses
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/status.md' completely.
+
+Next-step decision table defined in workflow status.md Step 5.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | fatal | `.workflow/` not initialized -- run `/maestro-init` first | parse_input |
+| E002 | fatal | `state.json` missing or corrupt -- project state unrecoverable | parse_input |
+</error_codes>
+
+<success_criteria>
+- [ ] Project state loaded from `state.json`
+- [ ] Roadmap parsed with milestone/phase structure
+- [ ] Per-phase progress calculated (task counts, completion %)
+- [ ] Dashboard rendered with progress bars and status table
+- [ ] Active work section shows current phase details
+- [ ] Next steps suggested based on current state analysis
+- [ ] Wiki health score displayed (or graceful unavailable message)
+</success_criteria>

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

@@ -0,0 +1,62 @@
+---
+name: manage-wiki
+description: Manage wiki graph — health, cleanup, search, stats
+argument-hint: "[health|search|cleanup|stats] [options]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+<purpose>
+Unified wiki graph management command. Provides interactive access to wiki health monitoring, entry search, orphan cleanup, and graph statistics — the day-to-day operations that 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 trends |
+| No args | Same as `health` |
+
+**Flags:**
+- `--type <type>` — Filter by wiki type: spec, knowhow, note, lesson, issue
+- `--fix` — Auto-fix issues found during cleanup (remove broken links, suggest connections)
+- `--json` — Output in JSON format
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/wiki-manage.md' completely.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | fatal | `.workflow/` not initialized — run `/maestro-init` first | validate |
+| E002 | fatal | No wiki entries found — create content first | load |
+| E003 | error | Invalid subcommand | parse_input |
+| W001 | warning | Health score below 50 — graph needs attention | health |
+| W002 | warning | Orphan cleanup had partial failures | cleanup |
+</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/maestro-flow/commands/milestone/audit.md

@@ -0,0 +1,68 @@
+---
+name: maestro-milestone-audit
+description: Audit current milestone for cross-phase integration gaps
+argument-hint: "[<milestone>]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+
+<purpose>
+Audit milestone completion using the artifact registry. Checks:
+1. Phase coverage — every phase in roadmap has plan + execute artifacts (completed)
+2. Ad-hoc completeness — all adhoc artifacts are completed (or explicitly skipped)
+3. Execution completeness — all tasks in executed plans are completed
+4. Cross-artifact integration — interfaces, data contracts, configuration consistency
+
+Data source: `state.json.artifacts[]` filtered by current milestone.
+Produces audit report at `.workflow/milestones/{milestone}/audit-report.md`.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/milestone-audit.md
+</required_reading>
+
+<context>
+Milestone: $ARGUMENTS (optional -- defaults to current_milestone from state.json).
+
+**Requires:** All phases in the milestone should have completed execute artifacts.
+
+**Data source:**
+- `.workflow/state.json` — artifacts[], current_milestone, milestones[]
+- `.workflow/roadmap.md` — milestone-to-phase mapping
+- Plan scratch dirs — for task status verification
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/milestone-audit.md' completely.
+
+Audit checklist steps (phase coverage, ad-hoc completeness, execution completeness, cross-artifact integration) are defined in workflow `milestone-audit.md`.
+
+**Next-step routing on completion:**
+- Verdict PASS → `/maestro-milestone-complete {milestone}`
+- Verdict FAIL, integration gaps → `/maestro-plan --gaps`
+- Verdict FAIL, incomplete execution → `/maestro-execute`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Milestone identifier required | Check arguments format |
+| E002 | error | Milestone not found in state.json | Check milestone ID |
+| E003 | error | No execute artifacts found for milestone | Run maestro-execute first |
+| W001 | warning | Some phases lack complete artifact chains | Review incomplete phases |
+</error_codes>
+
+<success_criteria>
+- [ ] All phases in milestone identified from roadmap
+- [ ] Artifact chains verified (ANL→PLN→EXC) per phase
+- [ ] Ad-hoc artifacts checked for completion
+- [ ] Integration check completed (shared interfaces, data contracts)
+- [ ] Audit report written with clear PASS/FAIL verdict
+- [ ] Next-step routing provided
+</success_criteria>

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

@@ -0,0 +1,75 @@
+---
+name: maestro-milestone-complete
+description: Archive completed milestone and prepare for next
+argument-hint: "[<milestone>]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+
+<purpose>
+Mark a milestone as complete after its audit has passed. Archives all scratch artifacts to `milestones/{M}/artifacts/`, moves artifact entries from `state.json.artifacts[]` to `milestone_history`, extracts final learnings, and advances to the next milestone.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/milestone-complete.md
+</required_reading>
+
+<context>
+Milestone: $ARGUMENTS (optional -- defaults to current_milestone from state.json).
+
+**Requires:** `/maestro-milestone-audit` should have passed.
+
+**State files:**
+- `.workflow/state.json` — artifacts[], milestones[], current_milestone, milestone_history[]
+- `.workflow/roadmap.md` — milestone structure
+- `.workflow/milestones/{milestone}/audit-report.md` — audit results
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/milestone-complete.md' completely.
+
+Archive flow steps (validation, directory archival, artifact history, learning extraction, state advancement, cleanup) are defined in workflow `milestone-complete.md`.
+
+### Knowledge Promotion Inquiry
+
+After learning extraction (step 4), scan `learnings.md` for promotion candidates:
+
+1. **High-frequency pattern detection**: Scan all `<spec-entry category="learning">` entries for keyword overlap (≥2 entries sharing keywords):
+   → Ask: "Keyword '{keyword}' appears in {N} learning entries. Should this be promoted to a formal coding convention? (`/spec-add coding`)"
+
+2. **Convention drift detection**: Compare executed task summaries against `coding-conventions.md` and `architecture-constraints.md`:
+   → Ask: "Were any established conventions bypassed during this milestone? Should conventions be updated?"
+
+3. **Wiki island check**: Auto-trigger `wiki-connect --fix` to link newly extracted knowledge.
+
+If user confirms promotion, invoke `Skill({ skill: "spec-add", args: "<category> <content>" })` with promoted content, preserving original date and source traceability.
+
+**Next-step routing on completion:**
+- Cut a release → `/maestro-milestone-release`
+- Next milestone → `/maestro-analyze` or `/maestro-plan 1`
+- View state → `/manage-status`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Milestone identifier required | Check arguments |
+| E002 | error | Audit not passed | Run maestro-milestone-audit first |
+| E003 | error | Incomplete artifacts remain | Complete remaining work first |
+</error_codes>
+
+<success_criteria>
+- [ ] Audit report verified as PASS
+- [ ] Scratch artifacts moved to milestones/{M}/artifacts/
+- [ ] Artifact entries archived to milestone_history
+- [ ] Learnings extracted to specs/learnings.md
+- [ ] state.json updated: next milestone as current, artifacts[] cleared
+- [ ] Roadmap snapshot saved
+- [ ] project.md Context updated with milestone summary
+</success_criteria>