pi-maestro-flow 0.2.0 → 0.3.0

package/workflows/init.md

@@ -0,0 +1,157 @@
+# 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 ≥3 research dimensions gathered, 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** (conditional, triggered when `config.workflow.research == true`) -- MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep when triggered: Spawn 4 parallel `workflow-project-researcher` agents writing to `.workflow/research/`: STACK.md, FEATURES.md, ARCHITECTURE.md, PITFALLS.md.
+
+4. **Synthesize** -- MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: 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. MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: 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.):
+   - MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: 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 2.5: Domain Init (first-run only)
+
+If `.workflow/domain/` does not exist:
+
+1. MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: Run `Bash("maestro domain init")` — creates `.workflow/domain/glossary.yaml` with empty terms array
+2. If brownfield project (has source files): MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: run `maestro domain discover --auto` to scan codebase for initial term candidates, present top 5 for confirmation
+3. If greenfield project: skip discovery (no codebase to scan); domain terms will be populated by grill/brainstorm sessions via finish-work extraction
+
+
+---
+
+## Step 3: Directory Structure Verification
+
+Verify all required directories and files exist:
+
+```
+.workflow/
+  project.md        ✓
+  state.json         ✓
+  config.json        ✓
+  specs/             ✓
+  domain/            ✓ (glossary.yaml)
+  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/integration-test.md

@@ -0,0 +1,186 @@
+# Integration Test Workflow
+
+Self-iterating integration test cycle that combines exploration, test design, execution, reflection, and adaptive strategy adjustment. Runs automated tests in a closed loop that self-corrects until convergence.
+
+6-phase cycle: Explore -> Design -> Develop -> Test -> Reflect -> Adjust
+Adaptive strategy: Conservative -> Aggressive -> Surgical -> Reflective
+L0-L3 progressive layers: Static Analysis -> Unit -> Integration -> E2E
+
+---
+
+### Step 1: Parse Input and Initialize
+
+**Parse arguments:**
+
+| Input | Result |
+|-------|--------|
+| No arguments | Error E001 |
+| Phase number | Resolve phase dir from artifact registry |
+| `--max-iter N` | Set MAX_ITER = N (default 5) |
+| `--layer L2` | Start from L2 layer |
+
+**Resolve phase dir:** from state.json artifact registry (type='execute', matching phase). Error if not found.
+
+If existing session at `${PHASE_DIR}/.tests/integration/state.json`: offer resume or restart.
+
+**Initialize session:** create `.tests/integration/` directory, write initial `state.json` (iteration=0, strategy=conservative, layer=L0, threshold=95, status=running), initialize `reflection-log.md`.
+
+---
+
+### Step 1.3: Load Project Specs
+
+```
+# MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep
+specs_content = maestro spec load --category test
+arch_content = maestro spec load --category arch
+```
+
+`specs_content` for test conventions; `arch_content` for module boundaries in Step 2-3.
+
+---
+
+### Step 1.5: Load Previously Generated Tests
+
+Load pre-generated integration/e2e tests from `${PHASE_DIR}/.tests/test-gen-report.json` (if exists).
+These are merged into the test plan in Step 3 -- executed but not re-generated.
+
+---
+
+### Step 2: Explore
+
+**Phase 1: Explore codebase for testable integration points.**
+
+Discover:
+- Module boundaries and cross-module calls
+- API endpoints and their handlers
+- Database interactions and queries
+- External service integrations
+- Event flows and message passing
+
+Scan for cross-module imports, API route definitions, and database calls.
+Map integration points: which modules communicate through what interfaces.
+
+---
+
+### Step 3: Design
+
+**Phase 2: Design integration test plan.**
+
+**Merge pre-generated tests** (from Step 1.5):
+If `generated_tests` is not empty, incorporate them into the test plan directly — mark as "pre-existing" so Step 4 (Develop) skips writing them and Step 5 (Test Execute) includes them in the run.
+
+Based on exploration (and pre-generated tests if available), design tests per layer:
+
+**L0 - Static Analysis:**
+- Type check command
+- Lint command
+- Dead code detection
+
+**L1 - Unit Tests (isolation):**
+- Critical functions identified in explore
+- Edge cases for core logic
+
+**L2 - Integration Tests:**
+- API endpoint tests (request -> response)
+- Cross-module interaction tests
+- Database query tests (with fixtures)
+
+**L3 - E2E Tests:**
+- Critical user flows
+- Happy path + error path
+
+Write test plan to `.tests/integration/test-plan.json`:
+```json
+{
+  "layers": {
+    "L0": { "commands": ["tsc --noEmit", "eslint src/"], "expected_pass": true },
+    "L1": { "test_files": [...], "test_count": N },
+    "L2": { "test_files": [...], "test_count": N },
+    "L3": { "test_files": [...], "test_count": N }
+  },
+  "total_tests": M
+}
+```
+
+---
+
+### Step 4: Develop
+
+**Phase 3: Develop/write test code.**
+
+For each layer (current and below), write tests following existing patterns.
+Use auto-test's RED-GREEN methodology for test writing.
+
+For integration tests (L2) specifically:
+- Set up test fixtures (DB seeds, mock services)
+- Write request/response assertions
+- Test error handling paths
+- Verify cross-module data flow
+
+---
+
+### Step 5: Test Execute
+
+**Phase 4: Execute tests for current layer.**
+
+Run tests progressively (L0 must pass before L1, etc.):
+- L0: `tsc --noEmit` + `eslint src/`
+- L1: unit tests (`--testPathPattern="unit|__tests__"`)
+- L2: integration tests (`--testPathPattern="integration"`)
+- L3: E2E tests (`--testPathPattern="e2e"`)
+
+Record per-layer results (status, total/passed/failed/pass_rate) and overall_pass_rate in `test-results-iter-{N}.json`.
+
+---
+
+### Step 6: Reflect
+
+**Phase 5: Reflect on iteration results.**
+
+Analyze: which tests failed, is pass rate improving/plateauing/regressing, are failures clustered, is strategy working.
+
+Append to `reflection-log.md`: iteration strategy, pass rate delta, what worked/failed, detected patterns, strategy assessment (effective/ineffective + recommendation).
+
+---
+
+### Step 7: Adjust
+
+**Phase 6: Adjust strategy based on reflection.**
+
+**Adaptive Strategy Engine:**
+
+| Condition | Strategy | Behavior |
+|-----------|----------|----------|
+| Iteration 1-2 | Conservative | Fix obvious failures, don't refactor |
+| Pass rate >80% AND failures similar to previous | Aggressive | Batch-fix related failures together |
+| New regressions appeared | Surgical | Revert last changes, fix regression only |
+| Stuck 3+ iterations (rate not improving) | Reflective | Step back, re-analyze root cause pattern |
+
+**Strategy transitions:** Conservative --(>80%)--> Aggressive --(regression)--> Surgical --(fixed)--> Aggressive. Any --(stuck 3+ iters)--> Reflective --(insight)--> Conservative.
+
+Update state.json. **Convergence:** pass_rate >= 95% -> Step 8. max_iterations reached -> Step 8. Otherwise -> Step 4.
+
+---
+
+### Step 8: Complete
+
+Update state.json status to "complete" or "max_iter_reached".
+Write `.tests/integration/summary.json`: iterations, final_pass_rate, converged flag, strategy_history, per-layer results, bugs_discovered, regressions_fixed.
+Update index.json with integration test results.
+
+---
+
+### Step 9: Report
+
+Display summary: iterations, convergence status, per-layer pass rates, overall rate, strategy transitions, bugs/regressions found.
+
+List output files: state.json, reflection-log.md, summary.json.
+
+**Next step routing:**
+
+| Result | Suggestion |
+|--------|------------|
+| Converged (>=95%) | Skill({ skill: "quality-review", args: "{phase}" }) to update validation |
+| Max iter, >80% | Skill({ skill: "quality-test", args: "{phase}" }) for manual UAT on remaining gaps |
+| Max iter, <80% | Skill({ skill: "quality-debug" }) for deep investigation |
+| Bugs discovered | Skill({ skill: "maestro-plan", args: "{phase} --gaps" }) to plan fixes |

package/workflows/interview-mechanics.md

@@ -0,0 +1,8 @@
+# Interview Interaction Mechanics
+
+- **One decision per turn** via AskUserQuestion, 2-4 options, first marked `(Recommended)`. User can redirect via `Other`.
+- **Search-first**: resolve via state.json → session artifacts → `maestro spec/wiki` → Glob/Grep/Read → Agent(Explore) / delegate. Never ask what code can answer.
+- **Writeback**: each decision **immediately written to disk** before the next question. No batching.
+- **Skip**: auto mode (`-y`) → 逐问题 Search-first 代答（不跳过整段 interview）；仅当代码给出高置信答案时跳过该问题。**例外**：broad intent 的边界澄清永不跳过（即使 `-y`）；phase 歧义永不跳过。resume (`-c`) → 跳过已答问题。unambiguous 单一答案输入 → 仅跳过该问题。
+- **Decision table**: `| # | Decision | Choice | Source (user / code / default) | Confidence (high / medium / LOW) |`
+  - `code` source：Search-first 派生（state.json / spec / Glob / Grep）。`code` + 非 broad → 可自动定；`code` + broad → 标 `LOW CONFIDENCE` 需用户确认；`default` source → 一律标 `LOW CONFIDENCE`。

package/workflows/issue-analyze.md

@@ -0,0 +1,20 @@
+# Workflow: Issue Analysis
+
+> **DEPRECATED**: Superseded by `issue-gaps-analyze.md` which adds batch support and context.md output.
+> Use `maestro-analyze --gaps [ISS-ID]` instead.
+
+## Migration
+
+| Old usage | New usage |
+|-----------|-----------|
+| `manage-issue-analyze ISS-ID` | `/maestro-analyze --gaps ISS-ID` |
+| `manage-issue-analyze` (batch) | `/maestro-analyze --gaps` |
+| `manage-issue-plan ISS-ID` (follow-up) | `/maestro-plan --gaps ISS-ID` |
+
+## See Also
+
+- `issue-gaps-analyze.md` — current implementation (single + batch, classification, parallel exploration, context.md)
+- `issue-gaps-analyze.codex.md` — codex variant using `spawn_agents_on_csv` waves
+- `issue-execute.md` — downstream execution after planning
+
+## Notes