maestro-flow 0.3.10 → 0.3.12

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

@@ -0,0 +1,98 @@
+---
+name: maestro-fork
+description: Create git worktree for milestone-level parallel development, or sync existing worktree with main. Copies .workflow/ context and scratch artifacts into worktree since .workflow/ is gitignored.
+argument-hint: "-m <milestone-number> [--base <branch>] [--sync]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+<purpose>
+Create a git worktree for an entire milestone, enabling inter-milestone parallel development.
+The worktree scope is milestone-level — all scratch artifacts for that milestone are owned by
+the worktree. Since `.workflow/` is gitignored, this command explicitly copies project context
+and milestone scratch artifacts into the worktree.
+
+Also supports `--sync` mode to pull latest main into an active worktree.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/fork.md
+</required_reading>
+
+<context>
+$ARGUMENTS — milestone number and optional flags.
+
+**Modes:**
+| Mode | Trigger | Behavior |
+|------|---------|----------|
+| Fork | `-m 2` or `2` | Create worktree for milestone 2 |
+| Sync | `-m 2 --sync` | Sync existing worktree with main |
+
+**Flags:**
+- `-m <N>` or bare `<N>`: Milestone number
+- `--base <branch>`: Override base branch (default: HEAD)
+- `--sync`: Pull main into existing worktree, re-copy shared artifacts
+
+**Worktree layout:**
+```
+.worktrees/m{N}-{slug}/
+├── .workflow/
+│   ├── worktree-scope.json     (milestone scope marker)
+│   ├── state.json              (scoped — this milestone's artifacts only)
+│   ├── project.md, roadmap.md, config.json, specs/  (read-only copies)
+│   └── scratch/                (milestone's existing + new artifacts)
+└── <source code>
+```
+
+**Artifact scoping:**
+Fork copies scratch artifacts belonging to the target milestone (filtered from `state.json.artifacts[]` where `milestone == target`). New work creates scratch artifacts normally, registered in the worktree's local `state.json`.
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/fork.md' completely.
+
+**Fork flow:**
+1. Validate: initialized, roadmap exists, not inside worktree, milestone not forked
+2. Resolve milestone: `state.json.milestones[N-1]`
+3. Create worktree: `git worktree add -b milestone/{slug} .worktrees/m{N}-{slug} HEAD`
+4. Copy `.workflow/`: shared files + milestone scratch artifacts
+5. Write `worktree-scope.json` with milestone scope
+6. Write scoped `state.json` (this milestone's artifacts only)
+7. Update main: `worktrees.json` registry, mark milestone `"forked"`
+
+**Sync flow:**
+1. Find worktree from `worktrees.json`
+2. `cd worktree && git merge main`
+3. Re-copy shared files (project.md, roadmap.md, config.json, specs/)
+
+**Next steps:**
+- Fork → `cd {wt.path} && $maestro-analyze`
+- Sync → resume work in worktree
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Project not initialized | Run maestro-init |
+| E002 | error | No roadmap found | Run maestro-roadmap |
+| E003 | error | Running inside a worktree | Run from main worktree |
+| E004 | error | No milestone number | Provide `-m <N>` |
+| E006 | error | Milestone out of range | Check available milestones |
+| E008 | error | Milestone already has active worktree | Merge or cleanup first |
+</error_codes>
+
+<success_criteria>
+Fork mode:
+- [ ] Milestone resolved from state.json.milestones[]
+- [ ] Git worktree created with branch `milestone/{slug}`
+- [ ] Shared `.workflow/` files copied (project.md, roadmap.md, config.json, specs/)
+- [ ] Milestone scratch artifacts copied (filtered from artifact registry)
+- [ ] `worktree-scope.json` written with milestone scope
+- [ ] Scoped `state.json` written (this milestone's artifacts only)
+- [ ] `worktrees.json` registry updated in main worktree
+- [ ] Milestone marked `"forked"` in main state.json
+
+Sync mode:
+- [ ] Git merge main into worktree branch
+- [ ] Shared artifacts re-copied
+- [ ] Conflicts reported if any
+</success_criteria>

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

@@ -1,167 +1,172 @@
----
-name: maestro-init
-description: Initialize project with auto state detection — creates .workflow/ directory, project.md, state.json, config.json, and specs/
-argument-hint: "[--auto] [--from-brainstorm SESSION-ID]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
----
-
-## Auto Mode
-
-When `--auto`: After config questions, run research without further interaction. Expects idea document via @ reference.
-
-# Maestro Init (Single Agent)
-
-## Usage
-
-```bash
-$maestro-init ""
-$maestro-init "--auto"
-$maestro-init "--from-brainstorm brainstorm-auth-20260318"
-```
-
-**Flags**:
-- `--auto`: Skip interactive questioning; extract from provided document
-- `--from-brainstorm SESSION-ID`: Import vision/goals/constraints from brainstorm guidance-specification.md
-
-**Output**: `.workflow/` directory with project.md, state.json, config.json, specs/
-
----
-
-## Overview
-
-Sequential project setup skill. Detects project state (empty/code/existing), gathers project information through deep questioning or document extraction, then creates the `.workflow/` directory structure. No parallel agents — single sequential flow.
-
----
-
-## Implementation
-
-### Step 1: Parse Arguments
-
-Extract flags from arguments:
-- `--auto` flag presence
-- `--from-brainstorm SESSION-ID` value
-- Remaining text as project description
-
-### Step 2: Detect Project State
-
-```bash
-# Check existing state
-ls .workflow/state.json 2>/dev/null
-ls package.json pyproject.toml Cargo.toml go.mod 2>/dev/null
-```
-
-Classify as:
-- **existing**: `.workflow/state.json` found — warn and exit (E002)
-- **code**: Source files present but no `.workflow/` — onboarding existing codebase
-- **empty**: Greenfield project
-
-### Step 3: Gather Project Information
-
-**If `--from-brainstorm`**:
-- Read `.workflow/.brainstorm/{SESSION-ID}/guidance-specification.md`
-- Extract: vision, goals, constraints, terminology, tech decisions
-- Skip interactive questioning
-
-**If `--auto`**:
-- Extract project info from provided document/@ reference
-- Minimal interactive questions (confirm core value only)
-
-**Otherwise (interactive)**:
-- Deep questioning flow:
-  1. What is the core value proposition?
-  2. Who are the target users?
-  3. What are the key requirements? (follow threads, don't rush)
-  4. What are known constraints/limitations?
-  5. What tech stack preferences exist?
-- Follow each thread with clarifying questions until satisfied
-
-### Step 4: Read Templates
-
-Read the following templates:
-- `~/.maestro/templates/project.md`
-- `~/.maestro/templates/state.json`
-- `~/.maestro/templates/config.json`
-
-### Step 5: Create .workflow/ Structure
-
-```bash
-mkdir -p .workflow/specs .workflow/phases .workflow/scratch .workflow/codebase
-```
-
-### Step 6: Write project.md
-
-Populate template with gathered information:
-- Project name, core value proposition
-- Requirements: Validated / Active / Out of Scope
-- Key decisions and constraints
-- Tech stack (detected or specified)
-
-Write to `.workflow/project.md`.
-
-### Step 7: Write state.json
-
-Initialize state from template:
-- `current_phase`: null
-- `current_milestone`: null
-- `status`: "initialized"
-
-Write to `.workflow/state.json`.
-
-### Step 8: Write config.json
-
-Configuration questions (or defaults for --auto):
-- Granularity: fine / medium / coarse
-- Workflow agents: enable/disable optional agents
-- Gate preferences: verification strictness
-
-Write to `.workflow/config.json`.
-
-### Step 9: Initialize specs/
-
-Create convention files in `.workflow/specs/`:
-- `conventions.md` — detected or specified coding conventions
-- `learnings.md` — empty, populated during phase transitions
-
-### Step 10: Completion Report
-
-```
-=== WORKFLOW INITIALIZED ===
-Project: {project_name}
-State:   .workflow/state.json (active)
-
-Created:
-  .workflow/project.md
-  .workflow/state.json
-  .workflow/config.json
-  .workflow/specs/
-
-Next steps (choose one path to create roadmap):
-  $maestro-spec-generate "<idea>"   -- Full spec package + roadmap (heavy)
-  $maestro-roadmap "<requirement>"  -- Direct interactive roadmap (light)
-
-Other commands:
-  $manage-status                   -- View project dashboard
-  $maestro-brainstorm "<topic>"     -- Explore ideas first
-  $maestro-quick "<task>"           -- Quick ad-hoc task
-```
-
----
-
-## Error Handling
-
-| Code | Severity | Description | Recovery |
-|------|----------|-------------|----------|
-| E001 | error | No arguments when --auto requires document | Ask user for document reference |
-| E002 | error | .workflow/ already exists | Show status, suggest manage-status |
-| E003 | error | Brainstorm session not found | List available sessions |
-| W001 | warning | Could not detect tech stack | Continue with manual input |
-
----
-
-## Core Rules
-
-1. **Never create roadmap** — init only creates .workflow/ structure; roadmap is a separate step
-2. **Deep questioning over speed** — follow threads, ask clarifying questions (unless --auto)
-3. **Detect, don't assume** — scan for existing files, package managers, frameworks before asking
-4. **Templates are source of truth** — always read templates before writing files
-5. **Idempotent check** — if .workflow/ exists, refuse to overwrite (E002)
+---
+name: maestro-init
+description: Initialize project with auto state detection — creates .workflow/ directory, project.md, state.json, config.json, and specs/
+argument-hint: "[--auto] [--from-brainstorm SESSION-ID]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+<purpose>
+Sequential project setup skill. Detects project state (empty/code/existing), gathers project information through deep questioning or document extraction, then creates the `.workflow/` directory structure. No parallel agents — single sequential flow.
+
+When `--auto`: After config questions, run research without further interaction. Expects idea document via @ reference.
+</purpose>
+
+<context>
+
+```bash
+$maestro-init ""
+$maestro-init "--auto"
+$maestro-init "--from-brainstorm brainstorm-auth-20260318"
+```
+
+**Flags**:
+- `--auto`: Skip interactive questioning; extract from provided document
+- `--from-brainstorm SESSION-ID`: Import vision/goals/constraints from brainstorm guidance-specification.md
+
+**Output**: `.workflow/` directory with project.md, state.json, config.json, specs/
+
+</context>
+
+<invariants>
+1. **Never create roadmap** — init only creates .workflow/ structure; roadmap is a separate step
+2. **Deep questioning over speed** — follow threads, ask clarifying questions (unless --auto)
+3. **Detect, don't assume** — scan for existing files, package managers, frameworks before asking
+4. **Templates are source of truth** — always read templates before writing files
+5. **Idempotent check** — if .workflow/ exists, refuse to overwrite (E002)
+</invariants>
+
+<execution>
+
+### Step 1: Parse Arguments
+
+Extract flags from arguments:
+- `--auto` flag presence
+- `--from-brainstorm SESSION-ID` value
+- Remaining text as project description
+
+### Step 2: Detect Project State
+
+```bash
+# Check existing state
+ls .workflow/state.json 2>/dev/null
+ls package.json pyproject.toml Cargo.toml go.mod 2>/dev/null
+```
+
+Classify as:
+- **existing**: `.workflow/state.json` found — warn and exit (E002)
+- **code**: Source files present but no `.workflow/` — onboarding existing codebase
+- **empty**: Greenfield project
+
+### Step 3: Gather Project Information
+
+**If `--from-brainstorm`**:
+- Read `.workflow/.brainstorm/{SESSION-ID}/guidance-specification.md`
+- Extract: vision, goals, constraints, terminology, tech decisions
+- Skip interactive questioning
+
+**If `--auto`**:
+- Extract project info from provided document/@ reference
+- Minimal interactive questions (confirm core value only)
+
+**Otherwise (interactive)**:
+- Deep questioning flow:
+  1. What is the core value proposition?
+  2. Who are the target users?
+  3. What are the key requirements? (follow threads, don't rush)
+  4. What are known constraints/limitations?
+  5. What tech stack preferences exist?
+- Follow each thread with clarifying questions until satisfied
+
+### Step 4: Read Templates
+
+Read the following templates:
+- `~/.maestro/templates/project.md`
+- `~/.maestro/templates/state.json`
+- `~/.maestro/templates/config.json`
+
+### Step 5: Create .workflow/ Structure
+
+```bash
+mkdir -p .workflow/specs .workflow/scratch .workflow/codebase
+```
+
+### Step 6: Write project.md
+
+Populate template with gathered information:
+- Project name, core value proposition
+- Requirements: Validated / Active / Out of Scope
+- Key decisions and constraints
+- Tech stack (detected or specified)
+
+Write to `.workflow/project.md`.
+
+### Step 7: Write state.json
+
+Initialize state from template:
+- `current_milestone`: null
+- `current_task_id`: null
+- `status`: "initialized"
+- `artifacts`: []
+
+Write to `.workflow/state.json`.
+
+### Step 8: Write config.json
+
+Configuration questions (or defaults for --auto):
+- Granularity: fine / medium / coarse
+- Workflow agents: enable/disable optional agents
+- Gate preferences: verification strictness
+
+Write to `.workflow/config.json`.
+
+### Step 9: Initialize specs/
+
+Create convention files in `.workflow/specs/`:
+- `conventions.md` — detected or specified coding conventions
+- `learnings.md` — empty, populated during execute summaries extraction
+
+### Step 10: Completion Report
+
+```
+=== WORKFLOW INITIALIZED ===
+Project: {project_name}
+State:   .workflow/state.json (active)
+
+Created:
+  .workflow/project.md
+  .workflow/state.json
+  .workflow/config.json
+  .workflow/specs/
+
+Next steps (choose one path to create roadmap):
+  $maestro-spec-generate "<idea>"   -- Full spec package + roadmap (heavy)
+  $maestro-roadmap "<requirement>"  -- Direct interactive roadmap (light)
+
+Other commands:
+  $manage-status                   -- View project dashboard
+  $maestro-brainstorm "<topic>"     -- Explore ideas first
+  $maestro-quick "<task>"           -- Quick ad-hoc task
+```
+
+</execution>
+
+<error_codes>
+
+| Code | Severity | Description | Recovery |
+|------|----------|-------------|----------|
+| E001 | error | No arguments when --auto requires document | Ask user for document reference |
+| E002 | error | .workflow/ already exists | Show status, suggest manage-status |
+| E003 | error | Brainstorm session not found | List available sessions |
+| W001 | warning | Could not detect tech stack | Continue with manual input |
+
+</error_codes>
+
+<success_criteria>
+- [ ] Project state correctly detected (empty/code/existing)
+- [ ] `.workflow/` directory structure created
+- [ ] `project.md` populated with project information
+- [ ] `state.json` initialized with correct status
+- [ ] `config.json` written with configuration
+- [ ] `specs/` initialized with convention files
+- [ ] Completion report displayed with next steps
+</success_criteria>

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

@@ -0,0 +1,80 @@
+---
+name: maestro-learn
+description: Learning coordinator — route intent to learn commands, execute single or multi-step chains sequentially. Supports 7 chains from single-step (follow, investigate) to multi-step (deep-understand, pattern-catalog).
+argument-hint: "\"intent text\" [-y] [--dry-run] [--chain <name>]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+<purpose>
+Route learning requests to the optimal learn command or multi-step chain.
+Executes commands sequentially with session tracking.
+
+```
+Intent → Route to Chain → Execute Steps → Session Summary
+```
+</purpose>
+
+<context>
+$ARGUMENTS — learning intent text, or flags.
+
+**Flags:**
+- `-y, --yes` — Auto mode: skip confirmation
+- `--dry-run` — Show planned chain without executing
+- `--chain <name>` — Force specific chain
+
+**Chains:**
+| Chain | Steps | Use when |
+|-------|-------|----------|
+| `follow` | learn-follow | Read/understand code or docs |
+| `investigate` | learn-investigate | Answer "how/why" questions |
+| `decompose` | learn-decompose | Catalog patterns in a module |
+| `second-opinion` | learn-second-opinion | Get review/challenge on code |
+| `retro` | learn-retro --lens all | Full retrospective |
+| `deep-understand` | follow → decompose → second-opinion | Thorough module analysis |
+| `pattern-catalog` | decompose --save-spec --save-wiki → second-opinion --mode review | Full pattern extraction + review |
+
+**Session state:** `.workflow/learning/.maestro-learn/{session_id}/status.json`
+</context>
+
+<execution>
+
+### Step 1: Parse & Route
+
+**Intent routing:**
+| Keywords | Route |
+|----------|-------|
+| File path (contains `/` or `\`) | `follow` |
+| read, follow, walk through, understand | `follow` |
+| why, how, what if, investigate | `investigate` |
+| pattern, decompose, catalog | `decompose` |
+| opinion, review, challenge, consult | `second-opinion` |
+| retro, git, commit, decision | `retro` |
+| thorough, deep | `deep-understand` |
+
+No match → present menu via AskUserQuestion. Max 1 clarification.
+
+### Step 2: Resolve Target & Build Args
+Map chain to skill invocations. Extract target and flags from arguments.
+
+### Step 3: Confirm & Execute
+- `--dry-run`: display chain and exit
+- Not `-y`: show plan, ask confirmation
+- Execute each step sequentially. On failure: retry/skip/abort
+- Write session `status.json`, display summary
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No intent provided | Provide learning goal or use --chain |
+| E002 | error | Cannot determine intent | Rephrase or use --chain |
+| E005 | error | Invalid --chain name | Show valid chains |
+| W001 | warning | Intent ambiguous | Present options |
+</error_codes>
+
+<success_criteria>
+- [ ] Intent routed to correct chain
+- [ ] Session directory created with status.json
+- [ ] All chain steps executed
+- [ ] Session summary displayed with next-step routing
+</success_criteria>