maestro-flow 0.3.37 → 0.3.39

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

@@ -1,8 +1,8 @@
 ---
 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.
+description: Create or sync milestone worktree for parallel dev
 argument-hint: "-m <milestone-number> [--base <branch>] [--sync]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
 ---
 
 <purpose>
@@ -18,6 +18,11 @@ Also supports `--sync` mode to pull latest main into an active worktree.
 @~/.maestro/workflows/fork.md
 </required_reading>
 
+<deferred_reading>
+- [worktrees.json](~/.maestro/templates/worktrees.json) — read when initializing or updating worktree registry
+- [worktree-scope.json](~/.maestro/templates/worktree-scope.json) — read when creating worktree scope marker
+</deferred_reading>
+
 <context>
 $ARGUMENTS — milestone number and optional flags.
 
@@ -64,6 +69,55 @@ Follow '~/.maestro/workflows/fork.md' completely.
 2. `cd worktree && git merge main`
 3. Re-copy shared files (project.md, roadmap.md, config.json, specs/)
 
+**Registry: `worktrees.json`** (`.workflow/worktrees.json` in main worktree):
+
+Initialize if not exists: `{ "version": "1.0", "worktrees": [], "fork_sessions": [] }`
+
+On fork, append to `worktrees[]`:
+```json
+{
+  "milestone_num": "{milestoneNum}",
+  "milestone": "{milestoneName}",
+  "slug": "{milestoneSlug}",
+  "branch": "milestone/{milestoneSlug}",
+  "path": "{worktreeRoot}/m{milestoneNum}-{milestoneSlug}",
+  "base_commit": "{baseCommit}",
+  "status": "active",
+  "created_at": "{UTC8_ISO}",
+  "owned_phases": ["{ownedPhaseNumbers}"],
+  "fork_session": "{forkSessionId}"
+}
+```
+
+Append to `fork_sessions[]`:
+```json
+{
+  "session_id": "fork-{UTC8_compact_timestamp}",
+  "created_at": "{UTC8_ISO}",
+  "milestone_num": "{milestoneNum}",
+  "milestone": "{milestoneName}",
+  "base_branch": "{baseBranch}",
+  "base_commit": "{baseCommit}"
+}
+```
+
+**Scope marker: `worktree-scope.json`** (`{wtPath}/.workflow/worktree-scope.json`):
+```json
+{
+  "worktree": true,
+  "milestone_num": "{milestoneNum}",
+  "milestone": "{milestoneName}",
+  "owned_phases": ["{ownedPhaseNumbers}"],
+  "phase_dependencies": "{phaseDeps}",
+  "main_worktree": "{resolve(cwd)}",
+  "branch": "milestone/{milestoneSlug}",
+  "base_commit": "{baseCommit}",
+  "created_at": "{UTC8_ISO}"
+}
+```
+
+Presence of `worktree-scope.json` signals "inside a worktree" — used by E003 validation to prevent nested forks.
+
 **Next steps:**
 - Fork → `cd {wt.path} && $maestro-analyze`
 - Sync → resume work in worktree

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

@@ -1,8 +1,8 @@
 ---
 name: maestro-init
-description: Initialize project with auto state detection — creates .workflow/ directory, project.md, state.json, config.json, and specs/
+description: Initialize project with auto state detection
 argument-hint: "[-y] [--from-brainstorm SESSION-ID]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
 ---
 
 <purpose>
@@ -57,21 +57,26 @@ Classify as:
 
 **If `--from-brainstorm`**:
 - Read `.workflow/.brainstorm/{SESSION-ID}/guidance-specification.md`
-- Extract: vision, goals, constraints, terminology, tech decisions
-- Skip interactive questioning
+- Extract these fields from the document (match by heading or frontmatter key):
+  - `## Vision` or `vision:` → project.md Core Value Proposition
+  - `## Goals` or `goals:` → project.md Requirements (Validated)
+  - `## Constraints` or `constraints:` → project.md Constraints section
+  - `## Terminology` or `terminology:` → project.md Glossary section
+  - `## Tech Decisions` or `tech_stack:` → project.md Tech Stack section
+- Skip interactive questioning — all project info comes from the document
 
 **If `-y`**:
 - 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
+- Deep questioning flow (ask via `request_user_input`, follow each thread with clarifying questions until satisfied):
+  1. "What problem does this project solve? Who feels the pain today?" — core value proposition
+  2. "Who are the target users? How do they currently work around this problem?" — user personas
+  3. "What are the must-have features for a first usable version?" — key requirements (follow threads, don't rush)
+  4. "What are known constraints — budget, timeline, team size, tech mandates, compliance?" — constraints/limitations
+  5. "What tech stack preferences or existing infrastructure must be used?" — tech stack decisions
+- For each answer, probe deeper: "Why?", "What happens if not?", "Can you give an example?"
 
 ### Step 4: Read Templates
 
@@ -94,17 +99,36 @@ Initialize from template with `current_milestone: null`, `status: "initialized"`
 
 ### Step 8: Write config.json
 
-Configuration questions (or defaults for -y): granularity (fine/medium/coarse), workflow agents (enable/disable), gate preferences. Write to `.workflow/config.json`.
+Configuration questions (or defaults for -y). Ask via `request_user_input`:
+
+**Granularity** — task decomposition detail level:
+```json
+{ "questions": [{ "id": "granularity", "header": "Task Granularity", "question": "How granular should task breakdowns be?", "options": [{ "label": "medium (Recommended)", "description": "Balanced: one task per logical feature" }, { "label": "fine", "description": "Detailed: one task per function/component" }, { "label": "coarse", "description": "High-level: one task per epic/module" }] }] }
+```
+
+**Workflow agents** — enable parallel research agents during analyze/plan:
+```json
+{ "questions": [{ "id": "workflow_agents", "header": "Workflow Agents", "question": "Enable parallel research agents for analysis and planning phases?", "options": [{ "label": "enabled (Recommended)", "description": "Spawn parallel agents for research, patterns, risks" }, { "label": "disabled", "description": "Sequential single-agent flow only" }] }] }
+```
+
+**Gate preferences** — milestone completion gates:
+```json
+{ "questions": [{ "id": "gate_preferences", "header": "Quality Gates", "question": "What quality gates should be enforced at milestone boundaries?", "options": [{ "label": "standard (Recommended)", "description": "Audit report required, all tasks completed" }, { "label": "strict", "description": "Audit + code review + test coverage threshold" }, { "label": "relaxed", "description": "Manual approval only, no automated checks" }] }] }
+```
+
+Write collected configuration to `.workflow/config.json`.
 
 ### Step 9: Initialize specs/
 
 Run `Bash("maestro spec init")` to create empty seed files in `.workflow/specs/`.
 
-If project state is **code** (existing source files detected):
-- Auto-trigger `Skill({ skill: "spec-setup" })` to scan codebase and populate specs with detected conventions.
+If project state is **code** (existing source files detected in Step 2):
+- Auto-trigger `Skill({ skill: "spec-setup" })` to scan codebase and populate specs with detected conventions
+- This runs unconditionally for `code` state — existing source means conventions can be extracted
 
-If project state is **empty** (greenfield):
-- Skip spec-setup. Specs are populated progressively by analyze, plan, and execute stages via `maestro spec add`.
+If project state is **empty** (greenfield, no source files found in Step 2):
+- Skip spec-setup entirely — no code to scan
+- Specs are populated progressively by analyze, plan, and execute stages via `maestro spec add`
 
 ### Step 10: Completion Report
 

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

@@ -1,80 +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>
+---
+name: maestro-learn
+description: Route learning intent to learn-* commands
+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>