maestro-flow 0.3.4 → 0.3.6

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

@@ -22,6 +22,7 @@ Unified brainstorming combining interactive framework generation, multi-role par
 <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
+- [brainstorm-visualize.md](~/.maestro/workflows/brainstorm-visualize.md) — read when html-prototypes/ produced and user wants to browse them
 </deferred_reading>
 
 <context>
@@ -54,6 +55,7 @@ Auto mode:
 - Project initialized, need spec package → Skill({ skill: "maestro-spec-generate", args: "--from-brainstorm {session_id}" })
 - Project initialized, quick roadmap → Skill({ skill: "maestro-roadmap", args: "--from-brainstorm {session_id}" })
 - Need deeper analysis first → Skill({ skill: "maestro-analyze", args: "{topic}" })
+- `html-prototypes/` produced with 2+ files and user wants to browse → load `~/.maestro/workflows/brainstorm-visualize.md` and launch visualizer server (optional, user-triggered)
 
 Single role mode:
 - More roles needed → Skill({ skill: "maestro-brainstorm", args: "{next_role} --session {session_id}" })
@@ -76,9 +78,16 @@ Single role mode:
 <success_criteria>
 **Auto mode**:
 - [ ] guidance-specification.md with RFC 2119 keywords, terminology, non-goals, feature decomposition
-- [ ] Role analysis files for each selected role in `.brainstorming/{role}/`
+- [ ] design-research.md persisted when Step 1.7 external research ran (fail-soft: absence not a failure)
+- [ ] Spec Review Gate passed (Step 3.5) or `--yes` bypassed
+- [ ] Role analysis files for each selected NON-UI role in `.brainstorming/{role}/`
+- [ ] If `ui-designer` in selected_roles: `ui-designer/analysis.md` exists AND exactly one of `html-prototypes/` / `ascii-mockups/` / `api-sketches/` exists with `README.md` + ≥1 prototype file
+- [ ] ui-designer/analysis.md references each prototype via `@-notation`
+- [ ] HTML prototypes are self-contained (no external `<link>`/`<script src>` URLs — warn only)
 - [ ] Feature specs in `.brainstorming/feature-specs/` (or synthesis-specification.md)
+- [ ] UI-bearing feature specs reference the corresponding prototype in Section 3 (Interface Contract)
 - [ ] feature-index.json and synthesis-changelog.md
+- [ ] Final Output Gate passed (Step 5.5) or `--yes` bypassed
 - [ ] All user decisions captured with Decision Recording Protocol
 - [ ] Session metadata updated with completion status
 

package/.claude/commands/maestro-milestone-audit.md

@@ -1,7 +1,7 @@
 ---
 name: maestro-milestone-audit
 description: Audit current milestone for cross-phase integration gaps
-argument-hint: "[milestone, e.g., 'v1.0']"
+argument-hint: "[<milestone>]"
 allowed-tools:
   - Read
   - Write

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

@@ -1,7 +1,7 @@
 ---
 name: maestro-milestone-complete
 description: Archive completed milestone and prepare for next
-argument-hint: "[milestone, e.g., 'v1.0']"
+argument-hint: "[<milestone>]"
 allowed-tools:
   - Read
   - Write
@@ -35,6 +35,7 @@ Milestone: $ARGUMENTS (optional -- defaults to current_milestone from state.json
 Follow '~/.maestro/workflows/milestone-complete.md' completely.
 
 **Next-step routing on completion:**
+- Cut a release for this milestone → Skill({ skill: "maestro-milestone-release" })
 - Next milestone has phases → Skill({ skill: "maestro-plan", args: "{next_milestone_first_phase}" })
 - Need to capture learnings → Skill({ skill: "manage-memory-capture", args: "compact" })
 - View updated project state → Skill({ skill: "manage-status" })

package/.claude/commands/maestro-milestone-release.md

@@ -0,0 +1,96 @@
+---
+name: maestro-milestone-release
+description: Version bump, changelog generation, and git tag for a completed milestone
+argument-hint: "[<version>] [--bump patch|minor|major] [--dry-run] [--no-tag] [--no-push]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+
+<purpose>
+Package a completed milestone into a releasable version. Bumps the project version (e.g. `package.json`, `pyproject.toml`, or language-specific manifest), generates or appends a changelog entry from phase/milestone summaries and git log, creates an annotated git tag, and optionally pushes to the remote. Runs after Skill({ skill: "maestro-milestone-complete" }) has archived the milestone; serves as the final delivery step in the SDLC loop.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/milestone-release.md
+</required_reading>
+
+<context>
+$ARGUMENTS -- optional explicit version string and flags.
+
+**Flags:**
+- `<version>` -- explicit version (e.g. `1.2.0`). If omitted, version is derived from `--bump` or prompted.
+- `--bump patch|minor|major` -- semver bump relative to the current version (default: `minor`)
+- `--dry-run` -- compute the next version, changelog diff, and tag name without writing files or creating tags
+- `--no-tag` -- skip git tag creation (version bump + changelog only)
+- `--no-push` -- skip `git push --follow-tags` after tagging
+
+**State files:**
+- `.workflow/state.json` -- current_milestone, previous release version
+- `.workflow/milestones/{milestone}/summary.md` -- milestone summary (from `maestro-milestone-complete`)
+- `.workflow/milestones/{milestone}/audit-report.md` -- audit verdict (must be PASS)
+- `CHANGELOG.md` -- release notes file (created if missing)
+- Version manifest -- `package.json` / `pyproject.toml` / `Cargo.toml` / etc. (auto-detected)
+
+**Preconditions:**
+- Current milestone must be completed (audit PASS + Skill({ skill: "maestro-milestone-complete" }) run)
+- Working tree must be clean (no uncommitted changes) unless `--dry-run`
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/release.md' completely.
+
+**High-level flow:**
+1. Validate preconditions (milestone completed, clean tree, audit PASS)
+2. Resolve target version from `<version>` or `--bump` against current manifest
+3. Collect changes since last release tag: milestone summary + phase summaries + git log between tags
+4. Generate `CHANGELOG.md` entry (grouped by phase / change type)
+5. Write version to manifest file(s) + commit with message `chore(release): v{version}`
+6. Create annotated git tag `v{version}` with release notes body (unless `--no-tag`)
+7. Push commit + tag to remote (unless `--no-push`)
+
+**Report format on completion:**
+```
+=== RELEASE COMPLETE ===
+Version:   v{previous} → v{new}
+Milestone: {milestone_name}
+Tag:       v{new} {pushed|local-only}
+Changelog: {N} entries written to CHANGELOG.md
+Manifest:  {file_path} updated
+
+Next steps:
+  Skill({ skill: "maestro-plan", args: "{next_phase}" })  -- Start next milestone's first phase
+  Skill({ skill: "manage-status" })                        -- View project dashboard
+```
+
+For `--dry-run`, print the computed version, changelog diff, and tag name without side effects.
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Current milestone not completed (no milestone-complete run) | Run Skill({ skill: "maestro-milestone-complete" }) first |
+| E002 | error | Audit verdict not PASS | Re-run Skill({ skill: "maestro-milestone-audit" }) and resolve findings |
+| E003 | error | Working tree not clean (uncommitted changes) | Commit or stash changes, then retry |
+| E004 | error | Version manifest not found / unsupported | Add supported manifest or pass `<version>` explicitly with `--no-tag` |
+| E005 | error | Target version not greater than current (would break semver monotonicity) | Choose a higher version or run with explicit `<version>` |
+| W001 | warning | No changes detected since last release tag | Confirm whether release is still desired |
+| W002 | warning | Remote push failed (network / auth) | Retry manually with `git push --follow-tags` |
+</error_codes>
+
+<success_criteria>
+- [ ] Preconditions validated (milestone complete, audit PASS, clean tree)
+- [ ] Target version computed and greater than previous
+- [ ] Version manifest(s) updated with new version
+- [ ] CHANGELOG.md contains new entry with milestone summary + grouped changes
+- [ ] Release commit created with conventional message
+- [ ] Annotated git tag created (unless `--no-tag`)
+- [ ] Commit + tag pushed to remote (unless `--no-push` or push failed → W002)
+- [ ] state.json updated with last_release_version + last_release_at timestamp
+</success_criteria>

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

@@ -2,7 +2,15 @@
 name: maestro-phase-add
 description: Add or insert a new phase into the project roadmap with automatic renumbering
 argument-hint: "<slug> <title> [--after N]"
-allowed-tools: [Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion]
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
 ---
 
 <purpose>

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

@@ -2,7 +2,15 @@
 name: maestro-phase-transition
 description: Mark current or specified phase as complete, extract learnings, advance to next phase
 argument-hint: "[phase-number] [--force]"
-allowed-tools: [Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion]
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
 ---
 
 <purpose>

package/.claude/commands/maestro.md

@@ -75,6 +75,12 @@ In auto mode, maestro also:
 - Skips chain confirmation (Step 5d)
 - Auto-skips on step errors (retry once, then skip and continue)
 
+**Context window reminder:**
+
+Before each Step 7 Skill() call, if context usage is near the window limit:
+- `-y` active → print one-line warning and continue.
+- Otherwise → stop before the next step and ask the user (Continue / Pause to resume with `-c` / Abort). Wait for explicit choice.
+
 **Report format on completion:**
 
 ```

package/.claude/commands/manage-codebase-rebuild.md

@@ -1,50 +1,76 @@
----
-name: manage-codebase-rebuild
-description: Full rebuild of codebase documentation - scans project, builds doc-index.json, generates all tech-registry and feature-maps
-argument-hint: "[--force] [--skip-commit]"
-allowed-tools: [Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion]
----
-
-<purpose>
-Perform a full rebuild of the .workflow/codebase/ documentation system from scratch. Scans the entire project source to identify components, features, requirements, and ADRs, then spawns parallel workflow-codebase-mapper agents to generate all documentation artifacts. This is a destructive operation that overwrites existing codebase docs.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/codebase-rebuild.md
-</required_reading>
-
-<context>
-$ARGUMENTS -- optional flags.
-
-**Flags:**
-- `--force` -- Skip confirmation prompt and proceed directly
-- `--skip-commit` -- Do not auto-commit after rebuild
-
-**State files:**
-- `.workflow/` -- must be initialized (project.md, state.json exist)
-- `.workflow/codebase/` -- target directory (will be cleared and rebuilt)
-- `.workflow/codebase/doc-index.json` -- generated documentation index
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/codebase-rebuild.md' completely.
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | .workflow/ not initialized | Run maestro-init first to create .workflow/ |
-| W001 | warning | A mapper agent failed (partial results) | Retry failed mapper or accept partial results |
-</error_codes>
-
-<success_criteria>
-- [ ] User confirmed rebuild (or --force used)
-- [ ] .workflow/codebase/ cleared and rebuilt from scratch
-- [ ] All 4 mapper agents spawned (failures logged as W001)
-- [ ] doc-index.json generated and valid
-- [ ] All documentation files regenerated
-- [ ] state.json updated with rebuild timestamp
-- [ ] project-tech.json refreshed with detected tech stack
-- [ ] project.md Tech Stack section updated if changes detected
-- [ ] Next step routing: Skill({ skill: "manage-status" }) or Skill({ skill: "manage-codebase-refresh" }) for incremental updates later
-</success_criteria>
+---
+name: manage-codebase-rebuild
+description: Full rebuild of codebase documentation - scans project, builds doc-index.json, generates all tech-registry and feature-maps
+argument-hint: "[--focus <area>] [--force] [--skip-commit]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+
+<purpose>
+Perform a full rebuild of the .workflow/codebase/ documentation system from scratch. Scans the entire project source to identify components, features, requirements, and ADRs, then spawns parallel workflow-codebase-mapper agents to generate all documentation artifacts. This is a destructive operation that overwrites existing codebase docs.
+
+Can run before or after Skill({ skill: "maestro-init" }) -- works on any codebase with source files. Also serves the previous `spec-map` use case via `--focus <area>` for scoped dimension analysis.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/codebase-rebuild.md
+</required_reading>
+
+<context>
+$ARGUMENTS -- optional flags.
+
+**Flags:**
+- `--focus <area>` -- Scope mapper agents to a single domain (e.g., `auth`, `api`, `database`). When omitted, all 4 mappers run on the full codebase.
+- `--force` -- Skip confirmation prompt and proceed directly
+- `--skip-commit` -- Do not auto-commit after rebuild
+
+**Mapper agent assignments (when `--focus` omitted):**
+| Agent | Focus | Output file |
+|-------|-------|-------------|
+| Mapper 1 | **Tech stack** -- languages, frameworks, dependencies, build system | `tech-stack.md` |
+| Mapper 2 | **Architecture** -- layers, module boundaries, data flow, entry points | `architecture.md` |
+| Mapper 3 | **Features** -- capabilities, API surface, user-facing functionality | `features.md` |
+| Mapper 4 | **Cross-cutting concerns** -- error handling, logging, auth, config, testing | `concerns.md` |
+
+**State files:**
+- `.workflow/` -- must be initialized (project.md, state.json exist)
+- `.workflow/codebase/` -- target directory (will be cleared and rebuilt)
+- `.workflow/codebase/doc-index.json` -- generated documentation index
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/codebase-rebuild.md' completely.
+
+**When `--focus <area>` is set:** pass the area string to each mapper agent as scoping context; only regenerate the docs relevant to that scope (leave others untouched unless missing).
+
+**Next-step routing on completion:**
+- View updated project state → Skill({ skill: "manage-status" })
+- Incremental updates later → Skill({ skill: "manage-codebase-refresh" })
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | .workflow/ not initialized | Run maestro-init first to create .workflow/ |
+| W001 | warning | A mapper agent failed (partial results) | Retry failed mapper or accept partial results |
+| W002 | warning | `.workflow/codebase/` already exists -- user prompted for rebuild/skip | check_existing |
+</error_codes>
+
+<success_criteria>
+- [ ] User confirmed rebuild (or --force used)
+- [ ] .workflow/codebase/ cleared and rebuilt from scratch (or scoped subset when --focus set)
+- [ ] All 4 mapper agents spawned (failures logged as W001)
+- [ ] doc-index.json generated and valid
+- [ ] All documentation files regenerated
+- [ ] state.json updated with rebuild timestamp
+- [ ] project-tech.json refreshed with detected tech stack
+- [ ] project.md Tech Stack section updated if changes detected
+- [ ] Next step routing: Skill({ skill: "manage-status" }) or Skill({ skill: "manage-codebase-refresh" }) for incremental updates later
+</success_criteria>

package/.claude/commands/manage-codebase-refresh.md

@@ -2,7 +2,15 @@
 name: manage-codebase-refresh
 description: Incremental refresh of codebase docs based on recent changes
 argument-hint: "[--since <date>] [--deep]"
-allowed-tools: [Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion]
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
 ---
 
 <purpose>

package/.claude/commands/quality-refactor.md

@@ -1,7 +1,7 @@
 ---
 name: quality-refactor
 description: Tech debt reduction with reflection-driven iteration
-argument-hint: "[scope: module path, feature area, or 'all']"
+argument-hint: "[<scope>]"
 allowed-tools:
   - Read
   - Write

package/.claude/commands/quality-sync.md

@@ -2,7 +2,15 @@
 name: quality-sync
 description: Sync codebase docs after code changes - traces git diff through component/feature/requirement impact chain
 argument-hint: "[--full] [--since <commit|HEAD~N>] [--dry-run]"
-allowed-tools: [Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion]
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
 ---
 <purpose>
 Synchronize project state after manual code changes or to refresh codebase documentation. Detects changes via git diff, traces impact through doc-index.json (file -> component -> feature -> requirement), updates state.json and index.json, and refreshes affected `.workflow/codebase/` documentation. Use --full flag for a complete resync of all tracked files regardless of git diff.

package/.claude/commands/spec-setup.md

@@ -51,7 +51,7 @@ Follow '~/.maestro/workflows/specs-setup.md' completely.
 - [ ] `learnings.md` initialized with format instructions
 - [ ] `project-tech.json` written with detected tech stack
 - [ ] Report displayed with summary and next steps:
-  - Build codebase docs → Skill({ skill: "spec-map" })
+  - Build codebase docs → Skill({ skill: "manage-codebase-rebuild" })
   - Load specs for task → Skill({ skill: "spec-load" })
   - Add new knowledge → Skill({ skill: "spec-add", args: "<type> <content>" })
 </success_criteria>

package/.codex/skills/maestro-coordinate/SKILL.md

@@ -164,11 +164,25 @@ for (const step of state.steps.filter(s => s.status === 'pending')) {
   // Spawn step agent
   const agent = spawn_agent({ message: stepPrompt })
 
-  // Wait — with timeout urge
-  let result = wait_agent({ timeout_ms: 600000 })
+  // Wait — initial spawn: 30 min
+  let result = wait_agent({ timeout_ms: 1800000 })
   if (result.timed_out) {
-    send_message({ target: agent, message: "Please wrap up and output your findings JSON now." })
-    result = wait_agent({ timeout_ms: 600000 })
+    // Step 1: Status probe (non-interrupting, 3 min)
+    followup_task({ target: agent, message: "STATUS_CHECK: Report current progress, findings so far, and estimated remaining work." })
+    const status = wait_agent({ timeout_ms: 180000 })
+    if (status.timed_out) {
+      // Step 2: Force finalize (interrupt, 3 min)
+      followup_task({ target: agent, message: "FINALIZE: Output all current findings immediately. Time limit reached.", interrupt: true })
+      const forced = wait_agent({ timeout_ms: 180000 })
+      if (forced.timed_out) {
+        // Step 3: Abort
+        close_agent({ target: agent })
+      } else {
+        result = forced
+      }
+    } else {
+      result = status
+    }
   }
 
   // Parse structured output from agent
@@ -290,7 +304,7 @@ Resume: $maestro-coordinate --continue
 |------|----------|-----------|----------|
 | E001 | error | Intent unclassifiable after clarification | Default to `feature` chain; note in state.json |
 | E002 | error | `--chain` value not in chain map | List valid chains, abort |
-| E003 | error | Step agent timeout (both waits) | Mark step `failed`; skip remaining steps; suggest `--continue` |
+| E003 | error | Step agent timeout (4-step cascade exhausted) | Mark step `failed`; skip remaining steps; suggest `--continue` |
 | E004 | error | Step agent failed (non-JSON output) | Mark step `failed`; preserve raw output in `findings`; skip remaining |
 | E005 | error | `--continue`: no session found | Glob `.workflow/.maestro-coordinate/MCC-*/`, list sessions, prompt |
 | W001 | warning | Step output JSON missing `hints_for_next` | Continue with empty hints; next step still gets `findings` |
@@ -306,5 +320,5 @@ Resume: $maestro-coordinate --continue
 5. **Skip on Failure**: Step failure immediately marks all remaining steps `skipped` and aborts the loop
 6. **Close before spawn**: Always `close_agent` the current step agent before spawning the next
 7. **Dry-run is read-only**: Stop after displaying the chain plan — never spawn agents
-8. **Timeout handling**: One urge via `send_message`; if still timed out → mark `failed`
+8. **Timeout handling**: 4-step cascade — status probe → force finalize → abort; if all timed out → mark `failed`
 9. **No CLI fallback**: All execution is agent-native — no `exec_command("maestro delegate ...")`