maestro-flow 0.3.7 → 0.3.9

package/.claude/commands/learn-decompose.md

@@ -145,9 +145,9 @@ Build the decomposition report grouped by dimension:
 6. Display summary with counts and next steps
 
 **Next-step routing:**
-- Follow-along on a specific pattern → `Skill({ skill: "learn-follow", args: "<anchor-file>" })`
-- Get second opinion on findings → `Skill({ skill: "learn-second-opinion", args: "<target>" })`
-- Add all new patterns to specs → `Skill({ skill: "spec-add", args: "pattern ..." })` per pattern
+- Follow-along on a specific pattern → `/learn-follow <anchor-file>`
+- Get second opinion on findings → `/learn-second-opinion <target>`
+- Add all new patterns to specs → `/spec-add pattern ...` per pattern
 </execution>
 
 <error_codes>

package/.claude/commands/learn-follow.md

@@ -134,17 +134,17 @@ Build a structured summary document:
 5. Display summary with key findings and next steps
 
 **Next-step routing:**
-- Deep dive into a discovered pattern → `Skill({ skill: "learn-decompose", args: "<path>" })`
-- Add undocumented pattern to specs → `Skill({ skill: "spec-add", args: "pattern <description>" })`
-- Get second opinion on a finding → `Skill({ skill: "learn-second-opinion", args: "<file>" })`
-- Browse related wiki entries → `Skill({ skill: "wiki-digest", args: "<topic>" })`
+- Deep dive into a discovered pattern → `/learn-decompose <path>`
+- Add undocumented pattern to specs → `/spec-add pattern <description>`
+- Get second opinion on a finding → `/learn-second-opinion <file>`
+- Browse related wiki entries → `/wiki-digest <topic>`
 </execution>
 
 <error_codes>
 | Code | Severity | Condition | Recovery |
 |------|----------|-----------|----------|
 | E001 | error | Target not resolvable (file not found, wiki ID not found, search returned 0) | Check path/ID, or rephrase topic for search |
-| E002 | error | `.workflow/` not initialized | Run `Skill({ skill: "maestro-init" })` first |
+| E002 | error | `.workflow/` not initialized | Run `/maestro-init` first |
 | W001 | warning | Wiki graph unavailable (no .workflow/ wiki entries) — skipping context web | Proceed with code-only context (imports/exports) |
 | W002 | warning | coding-conventions.md not found — skipping convention comparison | Patterns flagged as "unknown convention status" |
 | W003 | warning | Target is very large (>1000 lines) — auto-switching to shallow depth | Use --depth deep to override |

package/.claude/commands/learn-investigate.md

@@ -162,9 +162,9 @@ Write final `report.md`:
 3. Display summary with answer and next steps
 
 **Next-step routing:**
-- Save finding to specs → `Skill({ skill: "spec-add", args: "debug <finding>" })`
-- Follow-along on discovered code → `Skill({ skill: "learn-follow", args: "<path>" })`
-- Decompose patterns found → `Skill({ skill: "learn-decompose", args: "<module>" })`
+- Save finding to specs → `/spec-add debug <finding>`
+- Follow-along on discovered code → `/learn-follow <path>`
+- Decompose patterns found → `/learn-decompose <module>`
 - Create wiki entry for understanding → `maestro wiki create --type note`
 </execution>
 

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

@@ -0,0 +1,303 @@
+---
+name: learn-retro
+description: Unified retrospective — git activity metrics and decision quality evaluation with lens-based selection
+argument-hint: "[--lens git|decision|all] [--days N] [--author <name>] [--area <path>] [--phase N] [--tag <tag>] [--id <id>] [--compare]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Unified retrospective that combines git activity analysis and decision quality evaluation into a single command with lens-based selection. Works on raw git history and wiki/spec data — does not require completed phase artifacts (unlike `quality-retrospective`).
+
+Two lenses, usable independently or together:
+- **git**: Commit metrics, session detection, per-author breakdown, file hotspots, trend tracking
+- **decision**: Decision tracing across wiki/specs/git, multi-perspective evaluation, lifecycle classification
+
+All insights persist to `.workflow/learning/lessons.jsonl` for cross-session queryability via `manage-learn`.
+</purpose>
+
+<context>
+Arguments: $ARGUMENTS
+
+**Lens selection:**
+- `--lens git` — Git activity retrospective only
+- `--lens decision` — Decision evaluation only
+- `--lens all` — Both lenses (default)
+
+**Git lens 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 report if one exists
+
+**Decision lens flags:**
+- `--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-{YYYY-MM-DD}.md` — Unified human-readable report
+- `.workflow/learning/retro-{YYYY-MM-DD}.json` — Structured metrics (machine-readable)
+- `.workflow/learning/lessons.jsonl` — Appended insights (source: "retro-git" or "retro-decision")
+- `.workflow/learning/learning-index.json` — Updated index
+
+**Storage read:**
+- `.workflow/state.json` — Current phase context (optional)
+- `.workflow/learning/retro-*.json` — Prior retro for trend comparison
+- `.workflow/learning/lessons.jsonl` — Existing insights for dedup
+- `maestro wiki list --type spec --json` — Spec entries (decision lens)
+- `.workflow/specs/architecture-constraints.md` — Documented architectural decisions (decision lens)
+- `.workflow/phases/*/context.md` — Phase context with Locked/Free/Deferred decisions (decision lens)
+</context>
+
+<execution>
+
+### Stage 1: Parse Arguments & Select Lenses
+- Parse `--lens` flag: `git`, `decision`, or `all` (default: `all`)
+- Extract lens-specific flags
+- Check `.workflow/learning/` exists; bootstrap if missing
+
+Display banner:
+```
+============================================================
+  LEARN RETRO
+============================================================
+  Lens:    {git | decision | all}
+  Scope:   {days/author/area for git} {phase/tag/id for decision}
+```
+
+---
+
+### Stage 2: Git Lens (skip if --lens decision)
+
+#### 2a: Gather Raw Data (parallel git commands)
+Run ALL these git commands in parallel:
+
+```bash
+# Commit stats with author, timestamp, subject, files changed
+git log --since="<start-date>T00:00:00" --format="%H|%aN|%ae|%ai|%s" --shortstat
+
+# Per-commit numstat for test vs production LOC split
+git log --since="<start-date>T00:00:00" --format="COMMIT:%H|%aN" --numstat
+
+# Timestamps for session detection (sorted)
+git log --since="<start-date>T00:00:00" --format="%at|%aN|%ai|%s" | sort -n
+
+# 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
+
+# Per-author commit counts
+git shortlog --since="<start-date>T00:00:00" -sn --no-merges
+```
+
+Apply `--author` and `--area` filters if provided.
+
+#### 2b: Compute Metrics
+| 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 x 100% |
+| Churn rate | Files changed >2 times / total unique files |
+| Active days | Distinct dates with commits |
+
+#### 2c: Detect Work Sessions
+Cluster commits by >2hr gaps in timestamps:
+- Per session: start time, end time, duration, commit count, primary focus area
+- Compute: total sessions, avg session duration, avg LOC/session-hour
+
+#### 2d: 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
+
+#### 2e: Trend Comparison (if --compare or prior report exists)
+- Find most recent `.workflow/learning/retro-*.json`
+- Compute deltas: commits, LOC, test ratio, churn rate, session count
+- Flag significant changes (>20% delta) as trend highlights
+
+#### 2f: Distill Git Insights
+- **High churn files** (changed >3 times): instability signal
+- **Low test ratio areas** (<20%): testing gap
+- **Session patterns**: scattered vs deep sessions
+- **Area drift**: commits not aligned with current roadmap phase
+
+Each insight: title, description, category (pattern/antipattern/technique), tags, confidence.
+
+---
+
+### Stage 3: Decision Lens (skip if --lens git)
+
+#### 3a: Collect Decisions (parallel)
+```bash
+maestro wiki search "decision" --json
+maestro wiki list --type spec --json
+git log --oneline --all --grep="decision\|chose\|decided\|architecture" -20
+```
+
+Also read:
+- `.workflow/specs/architecture-constraints.md` — grep for `### [decision]` blocks
+- `.workflow/phases/*/context.md` — scan for "Locked:", "Deferred:" sections
+- `.workflow/learning/lessons.jsonl` — filter `category == "decision"`
+
+Apply scope filter (--phase, --tag, --id).
+
+#### 3b: Build Decision Registry
+Per decision:
+```json
+{
+  "id": "source id",
+  "title": "what was decided",
+  "source": "wiki|spec|phase-context|lesson|git",
+  "date": "when decided",
+  "rationale": "why",
+  "alternatives": "what was considered",
+  "phase": "which phase",
+  "implementation_evidence": ["file paths from git"]
+}
+```
+
+#### 3c: Multi-Perspective Evaluation
+Spawn 3 Agents in a single message:
+
+**Agent 1 — Technical Soundness:**
+- Does implementation match stated intent?
+- Has technical context changed since decision was made?
+- Grade: sound / degraded / violated
+
+**Agent 2 — Cost Assessment:**
+- What complexity did this decision add?
+- Is it creating coupling or tech debt?
+- Grade: low-cost / acceptable / expensive / debt-creating
+
+**Agent 3 — Alternative Hindsight:**
+- With what we know now, was this the right call?
+- Would reversing be feasible?
+- Grade: confirmed / questionable / should-revisit
+
+#### 3d: Classify Decision Lifecycle
+| Status | Criteria |
+|--------|---------|
+| **Validated** | Sound + Low/Acceptable cost + Confirmed |
+| **Aging** | Sound but Expensive + Confirmed |
+| **Questionable** | Degraded or Violated + Questionable |
+| **Stale** | Any + Should-revisit |
+| **Reversed** | Code contradicts the decision |
+
+#### 3e: Generate Recommendations
+- **Aging**: flag for tech debt review
+- **Questionable**: create issue for investigation
+- **Stale**: suggest decision refresh
+- **Reversed**: suggest documenting the reversal
+
+---
+
+### Stage 4: Unified Report
+
+Write `.workflow/learning/retro-{date}.md`:
+
+```markdown
+# Retrospective: {date}
+**Lenses:** {active lenses} | **Period:** {days}d
+
+## Git Activity  (if git lens active)
+### Metrics
+| Metric | Value | Trend |
+|--------|-------|-------|
+| Commits | N | +/-% |
+| ...
+
+### Work Sessions
+{session timeline}
+
+### File Hotspots
+{top 10 most-changed files}
+
+### Per-Author
+{author breakdown table}
+
+## Decision Health  (if decision lens active)
+### Dashboard
+| Status | Count | Decisions |
+|--------|-------|-----------|
+| Validated | N | {list} |
+| Aging | N | {list} |
+| ...
+
+### Per-Decision Evaluation
+{detailed evaluations}
+
+## Combined Insights
+{merged insights from both lenses, deduplicated}
+
+## Recommended Actions
+1. {action}: {reason}
+```
+
+Write `.workflow/learning/retro-{date}.json` with structured data.
+
+---
+
+### Stage 5: Persist
+1. Write report files
+2. Append insights to `lessons.jsonl`:
+   - Git insights: `source: "retro-git"`, `category` per insight type
+   - Decision insights: `source: "retro-decision"`, `category: "decision"`
+   - Stable INS-id from `hash(lens + metric_or_decision + date)`
+3. Update `learning-index.json`
+4. Display summary
+
+**Next-step routing:**
+- Browse insights → `/manage-learn list --tag retro`
+- Deep dive on high-churn file → `/learn-follow <path>`
+- Fix test gaps → `/quality-test-gen <area>`
+- Create issue for questionable decision → `/manage-issue create ...`
+- Investigate stale decision → `/learn-investigate <question>`
+- Full phase retrospective → `/quality-retrospective`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Not inside a git repository (git lens) | Navigate to a git repo directory |
+| E002 | error | No commits found in time window (git lens) | Increase --days or check filters |
+| E003 | error | No decisions found in any source (decision lens) | Check wiki/specs content, or provide --id |
+| E004 | error | --id not found in wiki or lessons (decision lens) | Verify the decision ID exists |
+| W001 | warning | `.workflow/learning/` not found, bootstrapping | Auto-created; proceed normally |
+| W002 | warning | No prior retro report for comparison | Skip trend section; first retro establishes baseline |
+| W003 | warning | One perspective agent failed — partial evaluation (decision lens) | Proceed with available perspectives |
+| W004 | warning | No git implementation evidence for a decision | Evaluation is theoretical only |
+| W005 | warning | Phase context files not found (decision lens) | Skip phase-context decisions |
+</error_codes>
+
+<success_criteria>
+- [ ] Lens selection parsed correctly (git / decision / all)
+- [ ] Git lens (if active):
+  - [ ] All git commands executed successfully
+  - [ ] Metrics computed: commits, LOC, test ratio, churn rate, sessions
+  - [ ] Sessions detected with >2hr gap clustering
+  - [ ] Per-author breakdown generated
+  - [ ] Trend comparison computed if prior report exists
+  - [ ] At least 1 actionable insight distilled
+- [ ] Decision lens (if active):
+  - [ ] Decisions collected from available sources
+  - [ ] Scope filter applied correctly
+  - [ ] 3 perspective agents spawned in parallel
+  - [ ] Each decision classified by lifecycle status
+  - [ ] Recommendations generated for non-Validated decisions
+- [ ] Unified report written to `retro-{date}.md`
+- [ ] Structured data written to `retro-{date}.json`
+- [ ] `lessons.jsonl` appended with insights (stable INS-ids)
+- [ ] `learning-index.json` updated
+- [ ] No files modified outside `.workflow/learning/`
+- [ ] Summary displayed with next-step routing
+</success_criteria>

package/.claude/commands/learn-second-opinion.md

@@ -136,9 +136,9 @@ Across all perspectives (or from single agent in challenge/consult):
 4. Display summary with verdict and recommendations
 
 **Next-step routing:**
-- Create issue for a finding → `Skill({ skill: "manage-issue", args: "create <description>" })`
-- Decompose patterns found → `Skill({ skill: "learn-decompose", args: "<path>" })`
-- Follow-along on the code → `Skill({ skill: "learn-follow", args: "<path>" })`
+- Create issue for a finding → `/manage-issue create <description>`
+- Decompose patterns found → `/learn-decompose <path>`
+- Follow-along on the code → `/learn-follow <path>`
 </execution>
 
 <error_codes>

package/.claude/commands/maestro-analyze.md

@@ -1,99 +1,123 @@
----
-name: maestro-analyze
-description: Multi-dimensional analysis with CLI exploration, decision extraction, and intent tracking
-argument-hint: "<phase|topic> [-y] [-c] [-q]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Perform multi-dimensional analysis of a technical proposal, decision, or architecture choice through iterative CLI-assisted exploration and interactive discussion. Produces a discussion timeline (discussion.md) with evolving understanding, multi-perspective findings, Decision Recording Protocol, Intent Coverage tracking, and a final conclusions package with Go/No-Go recommendation.
-
-Combines structured 6-dimension scoring with iterative deepening and decision extraction. Replaces both analysis and decision-capture workflows — produces analysis.md (scoring) AND context.md (Locked/Free/Deferred decisions for plan).
-
-Use `-q` for quick decision extraction only (skip exploration + scoring).
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/analyze.md
-</required_reading>
-
-<deferred_reading>
-- [scratch-index.json](~/.maestro/templates/scratch-index.json) — read when operating in scratch mode
-- [index.json](~/.maestro/templates/index.json) — read when operating in phase mode
-</deferred_reading>
-
-<context>
-$ARGUMENTS -- phase number for phase mode, topic text for scratch mode, with optional flags.
-
-**Flags:**
-- `-y` / `--yes`: Auto mode — skip interactive scoping, use recommended defaults, auto-deepen
-- `-c` / `--continue`: Resume from existing session (auto-detect session folder + discussion.md)
-- `-q` / `--quick`: Quick mode — skip exploration + scoring, go straight to decision extraction (context.md only)
-
-**Phase mode** (number): resolves phase directory from state.json + roadmap, updates index.json status to "exploring".
-**Scratch mode** (text): creates `.workflow/scratch/analyze-{slug}-{date}/` with index.json from scratch-index template (type="analyze").
-
-**Output artifacts:**
-| Artifact | Mode | Description |
-|----------|------|-------------|
-| `context.md` | both | Locked/Free/Deferred decisions for downstream plan |
-| `discussion.md` | full | Full discussion timeline with TOC, Current Understanding, rounds, decisions, intent coverage |
-| `analysis.md` | full | Executive summary with 6-dimension scores and risk matrix |
-| `conclusions.json` | full | Final synthesis with recommendations, decision trail, intent coverage |
-| `explorations.json` | full | Codebase exploration findings (single perspective) |
-| `perspectives.json` | full | Multi-perspective findings with synthesis (if multi-perspective) |
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/analyze.md' completely.
-
-**Handoff:** context.md is consumed by maestro-plan (Step 4 loads Locked/Free/Deferred decisions).
-
-**Next-step routing on completion:**
-
-Phase mode:
-- Go recommendation, UI work needed → Skill({ skill: "maestro-ui-design", args: "{phase}" })
-- Go recommendation, ready to plan → Skill({ skill: "maestro-plan", args: "{phase}" })
-- No-Go recommendation → revisit requirements or Skill({ skill: "maestro-brainstorm", args: "{topic}" })
-
-Scratch mode:
-- Ready to plan → Skill({ skill: "maestro-plan", args: "--dir {scratch_dir}" })
-- Need more exploration → Skill({ skill: "maestro-analyze", args: "{topic} -c" })
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Analysis subject required (no arguments provided) | Prompt user for phase number or topic text |
-| E002 | error | Phase directory not found | List available phases, prompt user to select |
-| W001 | warning | CLI exploration failed | Continue with available context, note limitation |
-| W002 | warning | CLI analysis timeout | Retry with shorter prompt, or skip perspective |
-| W003 | warning | Insufficient evidence for scoring dimensions | Note low-confidence dimensions, proceed with available evidence |
-| W004 | warning | Max rounds reached (5) | Force synthesis, offer continuation option |
-</error_codes>
-
-<success_criteria>
-Full mode:
-- [ ] CLI exploration completed with code anchors and call chains
-- [ ] discussion.md created with full timeline, TOC, Current Understanding
-- [ ] analysis.md written with all 6 dimensions scored with evidence
-- [ ] conclusions.json created with recommendations and decision trail
-- [ ] Intent Coverage tracked and verified (no unresolved ❌ items)
-
-Both modes (full + quick):
-- [ ] context.md written with all decisions classified as Locked/Free/Deferred
-- [ ] Gray areas identified through phase-specific analysis
-- [ ] Decision Recording Protocol applied to all decisions
-- [ ] Scope creep redirected to Deferred section
-- [ ] Deferred items auto-created as issues (if any)
-- [ ] project.md Key Decisions updated with Locked decisions (phase mode)
-- [ ] Next step routed (ui-design/plan for Go, brainstorm for No-Go)
-- [ ] index.json timestamps updated
-</success_criteria>
+---
+name: maestro-analyze
+description: Multi-dimensional analysis with CLI exploration, decision extraction, and intent tracking
+argument-hint: "[phase|topic] [-y] [-c] [-q]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Perform multi-dimensional analysis of a technical proposal, decision, or architecture choice through iterative CLI-assisted exploration and interactive discussion. Produces a discussion timeline (discussion.md) with evolving understanding, multi-perspective findings, Decision Recording Protocol, Intent Coverage tracking, and a final conclusions package with Go/No-Go recommendation.
+
+Combines structured 6-dimension scoring with iterative deepening and decision extraction. Replaces both analysis and decision-capture workflows — produces analysis.md (scoring) AND context.md (Locked/Free/Deferred decisions for plan).
+
+Use `-q` for quick decision extraction only (skip exploration + scoring).
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/analyze.md
+</required_reading>
+
+<deferred_reading>
+- [state.json](~/.maestro/templates/state.json) — read when registering artifact
+</deferred_reading>
+
+<context>
+$ARGUMENTS -- phase number for milestone-scoped, topic text for adhoc/standalone mode, no args for milestone-wide.
+
+**Flags:**
+- `-y` / `--yes`: Auto mode — skip interactive scoping, use recommended defaults, auto-deepen
+- `-c` / `--continue`: Resume from existing session (auto-detect session folder + discussion.md)
+- `-q` / `--quick`: Quick mode — skip exploration + scoring, go straight to decision extraction (context.md only)
+
+**Scope routing (per architecture):**
+
+| Invocation | Precondition | Scope | Behavior |
+|-----------|-------------|-------|----------|
+| `analyze` (no args) | init + roadmap | milestone | Analyze current milestone's all phases |
+| `analyze 1` | init + roadmap | phase | Analyze phase 1 only |
+| `analyze "topic"` (has milestone) | none | adhoc | Analyze topic, affiliated with current milestone |
+| `analyze "topic"` (no milestone) | none | standalone | Analyze topic, no milestone affiliation |
+
+**Scope detection rule**: Text argument + `state.json.current_milestone` non-null → adhoc. Text argument + no milestone → standalone. No args + no roadmap → error (need topic or roadmap).
+
+**Output directory**: `scratch/analyze-{slug}-{date}/` (relative to `.workflow/`)
+
+**Artifact registration**: On completion, register artifact in `state.json.artifacts[]`:
+```jsonc
+{
+  "id": "ANL-{NNN}",
+  "type": "analyze",
+  "milestone": "{current_milestone or null}",
+  "phase": "{phase_number or null}",
+  "scope": "{milestone|phase|adhoc|standalone}",
+  "path": "scratch/analyze-{slug}-{date}",
+  "status": "completed",
+  "depends_on": null,
+  "harvested": false,
+  "created_at": "...",
+  "completed_at": "..."
+}
+```
+
+**Output artifacts:**
+| Artifact | Mode | Description |
+|----------|------|-------------|
+| `context.md` | both | Locked/Free/Deferred decisions for downstream plan |
+| `discussion.md` | full | Full discussion timeline with TOC, Current Understanding, rounds, decisions, intent coverage |
+| `analysis.md` | full | Executive summary with 6-dimension scores and risk matrix |
+| `conclusions.json` | full | Final synthesis with recommendations, decision trail, intent coverage |
+| `explorations.json` | full | Codebase exploration findings (single perspective) |
+| `perspectives.json` | full | Multi-perspective findings with synthesis (if multi-perspective) |
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/analyze.md' completely.
+
+**Handoff:** context.md is consumed by maestro-plan (loads Locked/Free/Deferred decisions).
+
+**Next-step routing on completion:**
+
+Phase/Milestone scope:
+- Go recommendation, UI work needed → `/maestro-ui-design {phase}`
+- Go recommendation, ready to plan → `/maestro-plan` or `/maestro-plan {phase}`
+- No-Go recommendation → revisit requirements or `/maestro-brainstorm {topic}`
+
+Adhoc/Standalone scope:
+- Ready to plan → `/maestro-plan --dir {scratch_dir}`
+- Need more exploration → `/maestro-analyze {topic} -c`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No args and no roadmap (cannot determine scope) | Prompt user for topic text or create roadmap first |
+| W001 | warning | CLI exploration failed | Continue with available context, note limitation |
+| W002 | warning | CLI analysis timeout | Retry with shorter prompt, or skip perspective |
+| W003 | warning | Insufficient evidence for scoring dimensions | Note low-confidence dimensions, proceed with available evidence |
+| W004 | warning | Max rounds reached (5) | Force synthesis, offer continuation option |
+</error_codes>
+
+<success_criteria>
+Full mode:
+- [ ] CLI exploration completed with code anchors and call chains
+- [ ] discussion.md created with full timeline, TOC, Current Understanding
+- [ ] analysis.md written with all 6 dimensions scored with evidence
+- [ ] conclusions.json created with recommendations and decision trail
+- [ ] Intent Coverage tracked and verified (no unresolved ❌ items)
+
+Both modes (full + quick):
+- [ ] context.md written with all decisions classified as Locked/Free/Deferred
+- [ ] Gray areas identified through phase-specific analysis
+- [ ] Decision Recording Protocol applied to all decisions
+- [ ] Scope creep redirected to Deferred section
+- [ ] Deferred items auto-created as issues (if any)
+- [ ] Artifact registered in state.json with correct scope/milestone/phase
+- [ ] Next step routed (ui-design/plan for Go, brainstorm for No-Go)
+</success_criteria>

package/.claude/commands/maestro-brainstorm.md

@@ -30,8 +30,8 @@ $ARGUMENTS -- topic text for auto mode, or role name for single role mode.
 
 **Auto mode**: topic text (e.g., "Build real-time collaboration platform") triggers full pipeline.
 **Single role mode**: valid role name (e.g., "system-architect") runs one role analysis.
-**Phase mode** (number): resolves phase directory, creates .brainstorming/ inside it.
-**Scratch mode** (text): creates `.workflow/scratch/brainstorm-{slug}-{date}/`.
+**All output** goes to `.workflow/scratch/brainstorm-{slug}-{date}/`.
+**Artifact registration**: On completion, registers artifact (type=brainstorm) in state.json.
 
 **Valid roles**: data-architect, product-manager, product-owner, scrum-master, subject-matter-expert, system-architect, test-strategist, ui-designer, ux-expert