maestro-flow 0.5.2 → 0.5.31

package/workflows/init.md

@@ -1,148 +1,148 @@
-# Workflow: init
-
-Project initialization with automatic state detection. Creates project infrastructure only — roadmap creation is handled by maestro-roadmap (light or full mode).
-
----
-
-## Worktree Guard
-
-```
-If .workflow/worktree-scope.json exists: error "Cannot run maestro-init inside a worktree." and exit.
-```
-
-## Step 1: State Detection
-
-Detect current project state to determine initialization path.
-
-```
-state.json exists → Path C (existing) | source files exist → Path B (brownfield) | else → Path A (greenfield)
-```
-
-### Path A: Empty/Greenfield Project
-
-1. **Deep Questioning** -- Gather project context through conversational exploration:
-
-   Open with: "What do you want to build?"
-   Wait for response, then follow the thread:
-   - Ask about what excited them, what problem sparked this
-   - Challenge vague terms — make abstract concrete
-   - Surface assumptions and find edges
-   - Probe for: core value (the ONE thing), target users, constraints, tech preferences
-   - Weave in coverage checks (don't switch to checklist mode):
-     - Project name and vision
-     - Core value (if everything else fails, what must work?)
-     - Primary goals (2-5)
-     - Tech stack preferences
-     - Constraints and non-goals
-     - Target users / stakeholders
-     - Success criteria
-
-   Decision gate: When enough context for project.md, ask "Ready to create project.md?"
-   - "Create project.md" → proceed
-   - "Keep exploring" → continue questioning
-
-   If `--auto` flag: skip interactive questioning, extract from @ referenced document.
-   If `--from <source>` (alias: `--from-brainstorm`):
-   - Locate source directory (`.workflow/scratch/*-brainstorm-*/`, `.workflow/scratch/*-import-*/`, etc.)
-   - Load `context-package.json` (preferred) or fall back to `guidance-specification.md`:
-     - `domain` (name, description, problem_statement) → project vision + core value
-     - `requirements[]` → project goals (Active requirements)
-     - `constraints[locked]` → key decisions
-     - `non_goals[]` → constraints + Out of Scope requirements
-     - `domain.terminology[]` → project glossary context
-   - Skip interactive questioning (context already gathered)
-
-2. **Workflow Preferences** -- Configure project workflow settings:
-
-   Single round (AskUserQuestion):
-   - Research: Research before planning each phase? (`workflow.research`)
-   - Reflection: Reflect on results after each phase? (`workflow.reflection`)
-   - Git Tracking: Commit planning docs to git? (`git.commit_docs`)
-   - Auto-sync: Sync codebase docs after execute? (`codebase.auto_sync_after_execute`)
-
-   Write `.workflow/config.json` from template + user selections.
-   Other segments (`execution`, `gates`, `guard`, `collab`, `specInjection`, `dashboard`)
-   stay at template defaults; user can edit later or configure via dedicated commands
-   (`/maestro-guard`, `maestro spec injection set`).
-
-   If `--auto`: use template defaults (all the above on).
-
-3. **Research** (optional, based on config.workflow.research) -- Spawn 4 parallel `workflow-project-researcher` agents writing to `.workflow/research/`: STACK.md, FEATURES.md, ARCHITECTURE.md, PITFALLS.md.
-
-4. **Synthesize** -- Spawn `workflow-research-synthesizer` agent:
-   - Input: all `.workflow/research/` documents
-   - Output: `.workflow/research/SUMMARY.md` with consolidated findings
-
-5. **Create project files:**
-   - `.workflow/project.md` from @templates/project.md + user answers (include Core Value, Requirements, Key Decisions)
-   - `.workflow/state.json` from template (status: "idle")
-   - `.workflow/config.json` already created in step 2
-
-### Path B: Brownfield (has code, no .workflow/)
-
-1. Create `.workflow/` directory structure
-2. Create `.workflow/state.json` (status: "idle")
-3. Offer codebase mapping:
-   - "Map codebase first" → execute `/manage-codebase-rebuild` to understand existing architecture, then return
-   - "Skip mapping" → proceed
-4. Run Workflow Preferences (same as Path A step 2) → `.workflow/config.json`
-5. Ask user for project vision, goals, constraints (same deep questioning as Path A step 1)
-   - If `--from <source>` (alias: `--from-brainstorm`): load context-package.json (skip questioning)
-   - For brownfield: infer Validated requirements from existing code (what does codebase already do?)
-6. Create `.workflow/project.md` (include inferred Validated requirements + new Active requirements)
-
-### Path C: Existing Project (has .workflow/)
-
-1. Read `.workflow/state.json`
-2. Display: "Project already initialized. Current status: {status}"
-3. Route to `/workflow:status`
-
----
-
-## Step 2: Specs Init (first-run only)
-
-If `.workflow/specs/` does not exist:
-
-1. Run `Bash("maestro spec init")` — creates empty seed files (skeleton only, no codebase scan)
-
-2. If project has existing source files (package.json, tsconfig.json, pyproject.toml, go.mod, etc.):
-   - Auto-trigger `Skill({ skill: "spec-setup" })` — scan codebase and populate specs with detected conventions
-   - Note: Specs are further enriched by analyze, plan, and execute stages via `maestro spec add`
-
-3. If greenfield project (no source files):
-   - Skip spec-setup (nothing to scan)
-   - Note: Specs will be progressively populated as pipeline stages produce knowledge
-
-
----
-
-## Step 3: Directory Structure Verification
-
-Verify all required directories and files exist:
-
-```
-.workflow/
-  project.md        ✓
-  state.json         ✓
-  config.json        ✓
-  specs/             ✓
-  research/          ✓ (if research enabled)
-  scratch/           ✓ (create empty)
-  milestones/        ✓ (create empty)
-  codebase/          ✓ (create empty)
-```
-
----
-
-## Step 4: Commit and Route
-
-1. If git repo and config.git.commit_docs: commit all `.workflow/` files with message `"chore: initialize project workflow"`
-2. Display initialization summary:
-   - Project name and core value
-   - Config highlights (research/reflection/commit_docs/auto_sync_after_execute toggles)
-   - Research summary (if research was run)
-3. Route next steps:
-   - "Run `/maestro-roadmap --mode full` to create full spec package with roadmap (heavy path)"
-   - "Run `/maestro-roadmap` to create interactive roadmap directly (light path)"
-   - "Run `/manage-status` to view project dashboard"
-   - "Run `/maestro-brainstorm` to explore ideas first"
+# Workflow: init
+
+Project initialization with automatic state detection. Creates project infrastructure only — roadmap creation is handled by maestro-roadmap (light or full mode).
+
+---
+
+## Worktree Guard
+
+```
+If .workflow/worktree-scope.json exists: error "Cannot run maestro-init inside a worktree." and exit.
+```
+
+## Step 1: State Detection
+
+Detect current project state to determine initialization path.
+
+```
+state.json exists → Path C (existing) | source files exist → Path B (brownfield) | else → Path A (greenfield)
+```
+
+### Path A: Empty/Greenfield Project
+
+1. **Deep Questioning** -- Gather project context through conversational exploration:
+
+   Open with: "What do you want to build?"
+   Wait for response, then follow the thread:
+   - Ask about what excited them, what problem sparked this
+   - Challenge vague terms — make abstract concrete
+   - Surface assumptions and find edges
+   - Probe for: core value (the ONE thing), target users, constraints, tech preferences
+   - Weave in coverage checks (don't switch to checklist mode):
+     - Project name and vision
+     - Core value (if everything else fails, what must work?)
+     - Primary goals (2-5)
+     - Tech stack preferences
+     - Constraints and non-goals
+     - Target users / stakeholders
+     - Success criteria
+
+   Decision gate: When enough context for project.md, ask "Ready to create project.md?"
+   - "Create project.md" → proceed
+   - "Keep exploring" → continue questioning
+
+   If `--auto` flag: skip interactive questioning, extract from @ referenced document.
+   If `--from <source>` (alias: `--from-brainstorm`):
+   - Locate source directory (`.workflow/scratch/*-brainstorm-*/`, `.workflow/scratch/*-import-*/`, etc.)
+   - Load `context-package.json` (preferred) or fall back to `guidance-specification.md`:
+     - `domain` (name, description, problem_statement) → project vision + core value
+     - `requirements[]` → project goals (Active requirements)
+     - `constraints[locked]` → key decisions
+     - `non_goals[]` → constraints + Out of Scope requirements
+     - `domain.terminology[]` → project glossary context
+   - Skip interactive questioning (context already gathered)
+
+2. **Workflow Preferences** -- Configure project workflow settings:
+
+   Single round (AskUserQuestion):
+   - Research: Research before planning each phase? (`workflow.research`)
+   - Reflection: Reflect on results after each phase? (`workflow.reflection`)
+   - Git Tracking: Commit planning docs to git? (`git.commit_docs`)
+   - Auto-sync: Sync codebase docs after execute? (`codebase.auto_sync_after_execute`)
+
+   Write `.workflow/config.json` from template + user selections.
+   Other segments (`execution`, `gates`, `guard`, `collab`, `specInjection`, `dashboard`)
+   stay at template defaults; user can edit later or configure via dedicated commands
+   (`/maestro-guard`, `maestro spec injection set`).
+
+   If `--auto`: use template defaults (all the above on).
+
+3. **Research** (optional, based on config.workflow.research) -- Spawn 4 parallel `workflow-project-researcher` agents writing to `.workflow/research/`: STACK.md, FEATURES.md, ARCHITECTURE.md, PITFALLS.md.
+
+4. **Synthesize** -- Spawn `workflow-research-synthesizer` agent:
+   - Input: all `.workflow/research/` documents
+   - Output: `.workflow/research/SUMMARY.md` with consolidated findings
+
+5. **Create project files:**
+   - `.workflow/project.md` from @templates/project.md + user answers (include Core Value, Requirements, Key Decisions)
+   - `.workflow/state.json` from template (status: "idle")
+   - `.workflow/config.json` already created in step 2
+
+### Path B: Brownfield (has code, no .workflow/)
+
+1. Create `.workflow/` directory structure
+2. Create `.workflow/state.json` (status: "idle")
+3. Offer codebase mapping:
+   - "Map codebase first" → execute `/manage-codebase-rebuild` to understand existing architecture, then return
+   - "Skip mapping" → proceed
+4. Run Workflow Preferences (same as Path A step 2) → `.workflow/config.json`
+5. Ask user for project vision, goals, constraints (same deep questioning as Path A step 1)
+   - If `--from <source>` (alias: `--from-brainstorm`): load context-package.json (skip questioning)
+   - For brownfield: infer Validated requirements from existing code (what does codebase already do?)
+6. Create `.workflow/project.md` (include inferred Validated requirements + new Active requirements)
+
+### Path C: Existing Project (has .workflow/)
+
+1. Read `.workflow/state.json`
+2. Display: "Project already initialized. Current status: {status}"
+3. Route to `/workflow:status`
+
+---
+
+## Step 2: Specs Init (first-run only)
+
+If `.workflow/specs/` does not exist:
+
+1. Run `Bash("maestro spec init")` — creates empty seed files (skeleton only, no codebase scan)
+
+2. If project has existing source files (package.json, tsconfig.json, pyproject.toml, go.mod, etc.):
+   - Auto-trigger `Skill({ skill: "spec-setup" })` — scan codebase and populate specs with detected conventions
+   - Note: Specs are further enriched by analyze, plan, and execute stages via `maestro spec add`
+
+3. If greenfield project (no source files):
+   - Skip spec-setup (nothing to scan)
+   - Note: Specs will be progressively populated as pipeline stages produce knowledge
+
+
+---
+
+## Step 3: Directory Structure Verification
+
+Verify all required directories and files exist:
+
+```
+.workflow/
+  project.md        ✓
+  state.json         ✓
+  config.json        ✓
+  specs/             ✓
+  research/          ✓ (if research enabled)
+  scratch/           ✓ (create empty)
+  milestones/        ✓ (create empty)
+  codebase/          ✓ (create empty)
+```
+
+---
+
+## Step 4: Commit and Route
+
+1. If git repo and config.git.commit_docs: commit all `.workflow/` files with message `"chore: initialize project workflow"`
+2. Display initialization summary:
+   - Project name and core value
+   - Config highlights (research/reflection/commit_docs/auto_sync_after_execute toggles)
+   - Research summary (if research was run)
+3. Route next steps:
+   - "Run `/maestro-roadmap --mode full` to create full spec package with roadmap (heavy path)"
+   - "Run `/maestro-roadmap` to create interactive roadmap directly (light path)"
+   - "Run `/manage-status` to view project dashboard"
+   - "Run `/maestro-brainstorm` to explore ideas first"

package/workflows/instruction-authoring-guide.md

@@ -0,0 +1,97 @@
+# Instruction File Authoring Guide
+
+## Core Principle
+
+**Only write what changes the model's behavior.** If removing a line doesn't change what the model does, delete it.
+
+## Protected Content — NEVER Remove
+
+### P1. Structural Tags
+
+**ALWAYS preserve ALL XML-style tags** (open AND close) in command files. These serve overlay targeting, system parsing, or state machine definition. Never remove tags — only trim content inside them.
+
+Common tags: `<purpose>`, `<context>`, `<execution>`, `<required_reading>`, `<deferred_reading>`, `<success_criteria>`, `<completion>`, `<error_codes>`, `<interview_protocol>`, `<on_complete>`.
+
+Odyssey-specific: `<boundary>`, `<execution_discipline>`, `<self_iteration>`, `<state_machine>`, `<states>`, `<transitions>`, `<actions>`, `<appendix>`, `<next_step_routing>`.
+
+Rule: if it has `<` and `>` wrapping a section — keep it.
+
+### P2. Data Structure Schemas
+
+JSON/NDJSON templates that define write formats:
+- `state.json.artifacts[]` registration blocks — keep all field names and value patterns
+- `evidence.ndjson` / `decisions.ndjson` schema definitions
+- Any `Append to ...` with field structure
+
+Allowed: JSON code block → bullet-point field list. NOT allowed: compress to one narrative sentence.
+
+### P3. Completion Status Blocks
+
+`--- COMPLETION STATUS ---` blocks enable downstream command chaining. NEVER remove.
+
+### P4. Routing Tables
+
+`success_criteria` → next command mapping tables enable workflow transitions. NEVER remove.
+
+### P5. Cross-File Reference Integrity
+
+When removing content from command file because "workflow file has it":
+- VERIFY the workflow file actually contains the referenced content
+- If command says "X is defined in Y.md", Y.md MUST have X with matching identifiers
+- Missing target = broken reference = FAIL
+
+## Anti-Patterns — Fix These
+
+### 1. Passive Dependency Assumptions
+
+"hooks handle it" / "auto-loaded" → "ALWAYS search before acting."
+
+### 2. Flat Tables With Equal Weight
+
+7 equal triggers → L0 (unconditional) / L1 (conditional) / L2 (deep analysis).
+
+### 3. Implementation Details
+
+"BM25 full-text", "broker-managed lifecycle" → Delete. Model needs WHEN, not HOW.
+
+### 4. Teaching-Style Explanations
+
+"Not X but Y" pedagogy → Show template, drop explanation.
+
+### 5. Duplicate Sections
+
+Same info in summary + steps → Single source. Schemas are reference, NOT duplication of steps.
+
+### 6. Soft Language for Hard Rules
+
+"should" / "recommended" → `ALWAYS` / `NEVER`.
+
+### 7. Verbose Descriptions
+
+Purpose in ≤10 words. Trim `<purpose>` content but keep the tag.
+
+### 8. Phase Gates Without BLOCKED
+
+Every Phase Gate MUST have both `REQUIRED` conditions AND `BLOCKED if missing` consequence. A Gate with only REQUIRED is unenforceable.
+
+### 9. Missing Structural Sections
+
+Commands with `<execution>` logic MUST also have:
+- `<completion>` — standalone report + ralph completion + next-step routing table
+- `<error_codes>` — error/warning code table with recovery actions
+Do NOT embed completion/routing logic inside `<execution>`. Keep them in their own tags.
+
+## Checklist
+
+- [ ] ALL structural tags preserved (P1)
+- [ ] ALL data schemas preserved with field-level detail (P2)
+- [ ] ALL completion status blocks preserved (P3)
+- [ ] ALL routing tables preserved (P4)
+- [ ] No line explains HOW a tool works internally
+- [ ] No duplicate info across sections
+- [ ] Strong constraints use ALWAYS/NEVER
+- [ ] High-frequency actions visually prominent (L0 / top of list)
+- [ ] Command descriptions ≤10 words
+- [ ] No "fallback" framing implying automatic primary path
+- [ ] Phase Gates have REQUIRED + BLOCKED pairs
+- [ ] Commands with `<execution>` have matching `<completion>` and `<error_codes>`

package/workflows/issue-execute.md

@@ -1,110 +1,110 @@
-# Workflow: Issue Execution
-
-> **DEPRECATED**: This workflow was used by the deleted `manage-issue-execute` command.
-> Use `maestro-execute` instead, which handles wave-based execution with automatic issue status sync.
-
-Execute a planned solution for an issue via dual-mode agent dispatch (server or direct CLI).
-
-## Input
-
-- `$ARGUMENTS`: `<ISS-ID> [--executor claude-code|codex|gemini] [--dry-run]`
-- Operates on `.workflow/issues/`
-
----
-
-### Step 1: Parse Arguments
-
-```
-Extract ISS-ID (required, pattern ISS-\d{8}-\d{3}).
-Flags: --executor claude-code|codex|gemini (default: claude-code), --dry-run (default: false)
-```
-
----
-
-### Step 2: Load Issue and Validate
-
-```
-Load ISS-ID from .workflow/issues/issues.jsonl → fatal if file missing or ID not found.
-Require issue.solution with non-empty steps[] → error if missing (run `maestro-plan --gaps {ISS-ID}` first).
-Resolve EXECUTOR → CLI tool (claude-code→claude, codex→codex, gemini→gemini), all with --mode write.
-```
-
----
-
-### Step 3: Dry Run (if --dry-run)
-
-```
-If DRY_RUN: display prompt template, steps table (action | title | files),
-and context. No changes made. Exit before Step 4.
-```
-
----
-
-### Step 4: Detect Execution Mode
-
-```
-Health check: curl http://127.0.0.1:3001/api/health
-  HTTP 200 → SERVER_UP (server dispatch) | otherwise → Direct CLI
-```
-
----
-
-### Step 5a: Server UP Path
-
-```
-POST to http://127.0.0.1:3001/api/execution/dispatch:
-  { "issueId", "executor", "solution": { steps, context, promptTemplate } }
-
-Success (200/201) → server manages status lifecycle, skip to Step 6.
-Failure → fall through to Step 5b (direct CLI fallback).
-```
-
-### Step 5b: Server DOWN Path
-
-```
-Build EXEC_PROMPT from SOLUTION (promptTemplate + steps + context + constraints).
-
-Status transitions in issues.jsonl with issue_history entries:
-  1. Set status → in_progress (actor: EXECUTOR, note: "Execution started")
-  2. Execute: maestro delegate "{EXEC_PROMPT}" --to {CLI_TOOL} --mode write
-  3. On success → status = "resolved", resolved_at = NOW_ISO
-     On failure → status = "open" (revert, no stuck in_progress)
-
-Read-modify-write pattern preserves other issues.
-```
-
----
-
-### Step 6: Display Result
-
-```
-Display: execution status (COMPLETE/FAILED), mode, executor, issue title, new status.
-  Server dispatch → show dispatch ID, "server managing lifecycle"
-  Direct CLI success → show modified files list
-  Failure → "reverted to open", suggest re-run or revise plan
-```
-
----
-
-### Step 7: Suggest Next Steps
-
-```
-Success → close issue, view status, run tests
-Failure → retry with different executor, revise plan, re-analyze with --depth deep
-```
-
----
-
-## Output
-
-- **Updated**: `.workflow/issues/issues.jsonl` -- issue status transitions (open -> in_progress -> resolved/open)
-- **Execution modes**: Server dispatch (POST /api/execution/dispatch) or Direct delegate (maestro delegate --mode write)
-
-## Quality Criteria
-
-- Dual-mode execution: server dispatch preferred, CLI fallback automatic
-- Dry-run mode shows full prompt without side effects
-- Status transitions recorded in issue_history with actor and timestamp
-- Failed execution reverts status to open (no stuck in_progress)
-- Read-modify-write pattern preserves other issues in JSONL
-- Next-step routing adapts based on success or failure
+# Workflow: Issue Execution
+
+> **DEPRECATED**: This workflow was used by the deleted `manage-issue-execute` command.
+> Use `maestro-execute` instead, which handles wave-based execution with automatic issue status sync.
+
+Execute a planned solution for an issue via dual-mode agent dispatch (server or direct CLI).
+
+## Input
+
+- `$ARGUMENTS`: `<ISS-ID> [--executor claude-code|codex|gemini] [--dry-run]`
+- Operates on `.workflow/issues/`
+
+---
+
+### Step 1: Parse Arguments
+
+```
+Extract ISS-ID (required, pattern ISS-\d{8}-\d{3}).
+Flags: --executor claude-code|codex|gemini (default: claude-code), --dry-run (default: false)
+```
+
+---
+
+### Step 2: Load Issue and Validate
+
+```
+Load ISS-ID from .workflow/issues/issues.jsonl → fatal if file missing or ID not found.
+Require issue.solution with non-empty steps[] → error if missing (run `maestro-plan --gaps {ISS-ID}` first).
+Resolve EXECUTOR → CLI tool (claude-code→claude, codex→codex, gemini→gemini), all with --mode write.
+```
+
+---
+
+### Step 3: Dry Run (if --dry-run)
+
+```
+If DRY_RUN: display prompt template, steps table (action | title | files),
+and context. No changes made. Exit before Step 4.
+```
+
+---
+
+### Step 4: Detect Execution Mode
+
+```
+Health check: curl http://127.0.0.1:3001/api/health
+  HTTP 200 → SERVER_UP (server dispatch) | otherwise → Direct CLI
+```
+
+---
+
+### Step 5a: Server UP Path
+
+```
+POST to http://127.0.0.1:3001/api/execution/dispatch:
+  { "issueId", "executor", "solution": { steps, context, promptTemplate } }
+
+Success (200/201) → server manages status lifecycle, skip to Step 6.
+Failure → fall through to Step 5b (direct CLI fallback).
+```
+
+### Step 5b: Server DOWN Path
+
+```
+Build EXEC_PROMPT from SOLUTION (promptTemplate + steps + context + constraints).
+
+Status transitions in issues.jsonl with issue_history entries:
+  1. Set status → in_progress (actor: EXECUTOR, note: "Execution started")
+  2. Execute: maestro delegate "{EXEC_PROMPT}" --to {CLI_TOOL} --mode write
+  3. On success → status = "resolved", resolved_at = NOW_ISO
+     On failure → status = "open" (revert, no stuck in_progress)
+
+Read-modify-write pattern preserves other issues.
+```
+
+---
+
+### Step 6: Display Result
+
+```
+Display: execution status (COMPLETE/FAILED), mode, executor, issue title, new status.
+  Server dispatch → show dispatch ID, "server managing lifecycle"
+  Direct CLI success → show modified files list
+  Failure → "reverted to open", suggest re-run or revise plan
+```
+
+---
+
+### Step 7: Suggest Next Steps
+
+```
+Success → close issue, view status, run tests
+Failure → retry with different executor, revise plan, re-analyze with --depth deep
+```
+
+---
+
+## Output
+
+- **Updated**: `.workflow/issues/issues.jsonl` -- issue status transitions (open -> in_progress -> resolved/open)
+- **Execution modes**: Server dispatch (POST /api/execution/dispatch) or Direct delegate (maestro delegate --mode write)
+
+## Quality Criteria
+
+- Dual-mode execution: server dispatch preferred, CLI fallback automatic
+- Dry-run mode shows full prompt without side effects
+- Status transitions recorded in issue_history with actor and timestamp
+- Failed execution reverts status to open (no stuck in_progress)
+- Read-modify-write pattern preserves other issues in JSONL
+- Next-step routing adapts based on success or failure