pi-maestro-flow 0.2.0 → 0.3.1

package/templates/index.json

@@ -0,0 +1,68 @@
+{
+  "phase": 0,
+  "slug": "{{SLUG}}",
+  "title": "{{TITLE}}",
+  "milestone": "{{MILESTONE_NAME}}",
+  "status": "pending",
+  "created_at": "{{TIMESTAMP}}",
+  "updated_at": "{{TIMESTAMP}}",
+  "completed_at": null,
+  "force_transition": false,
+  "depends_on": [],
+
+  "goal": "{{GOAL}}",
+  "success_criteria": [],
+  "requirements": [],
+  "blueprint_ref": null,
+
+  "session_id": null,
+  "recommendation": null,
+  "confidence": null,
+  "analysis_at": null,
+  "planning_at": null,
+
+  "plan": {
+    "task_ids": [],
+    "task_count": 0,
+    "complexity": null,
+    "waves": []
+  },
+
+  "execution": {
+    "method": "agent",
+    "started_at": null,
+    "completed_at": null,
+    "tasks_completed": 0,
+    "tasks_total": 0,
+    "current_wave": 0,
+    "commits": []
+  },
+
+  "verification": {
+    "status": "pending",
+    "verified_at": null,
+    "must_haves": [],
+    "gaps": []
+  },
+
+  "_optional_note_validation": "Populated only when quality-test/quality-test-gen workflows run",
+  "validation": {
+    "status": "pending",
+    "test_coverage": null,
+    "gaps": []
+  },
+
+  "_optional_note_uat": "Populated only when quality-test UAT workflow runs",
+  "uat": {
+    "status": "pending",
+    "test_count": 0,
+    "passed": 0,
+    "gaps": []
+  },
+
+  "_optional_note_reflection": "Populated only when reflection/strategy-adjustment workflows run",
+  "reflection": {
+    "rounds": 0,
+    "strategy_adjustments": []
+  }
+}

package/templates/issue.json

@@ -0,0 +1,36 @@
+{
+  "id": "ISS-{{YYYYMMDD}}-{{NNN}}",
+  "title": "{{TITLE}}",
+  "status": "open",
+  "priority": 3,
+  "severity": "medium",
+  "source": "verification",
+
+  "phase_ref": null,
+  "gap_ref": null,
+
+  "description": "{{DESCRIPTION}}",
+  "fix_direction": "{{SUGGESTED_FIX_APPROACH}}",
+
+  "context": {
+    "location": "{{FILE_PATH:LINE}}",
+    "suggested_fix": "{{REMEDIATION_CODE_OR_STEPS}}",
+    "notes": ""
+  },
+
+  "analysis": null,
+  "path": null,
+  "phase_id": null,
+
+  "tags": [],
+  "affected_components": [],
+
+  "feedback": [],
+
+  "issue_history": [],
+
+  "created_at": "{{TIMESTAMP}}",
+  "updated_at": "{{TIMESTAMP}}",
+  "resolved_at": null,
+  "resolution": null
+}

package/templates/plan.json

@@ -0,0 +1,38 @@
+{
+  "summary": "{{PLAN_SUMMARY}}",
+  "approach": "{{APPROACH}}",
+  "task_ids": [],
+  "task_count": 0,
+  "complexity": null,
+  "estimated_time": null,
+  "recommended_execution": "Agent",
+
+  "waves": [
+    {
+      "wave": 1,
+      "tasks": []
+    }
+  ],
+
+  "data_flow": {
+    "diagram": null,
+    "stages": []
+  },
+
+  "design_decisions": [],
+
+  "shared_context": {
+    "patterns": [],
+    "conventions": [],
+    "dependencies": []
+  },
+
+  "_metadata": {
+    "timestamp": "{{ISO_8601}}",
+    "source": "workflow-planner",
+    "planning_mode": "full",
+    "plan_type": "feature",
+    "schema_version": "2.0",
+    "git_commit": null
+  }
+}

package/templates/project.md

@@ -0,0 +1,60 @@
+# Project: {{PROJECT_NAME}}
+
+## What This Is
+
+{{CURRENT_DESCRIPTION — 2-3 sentences. What does this product do and who is it for?}}
+
+## Core Value
+
+{{THE_ONE_THING — If everything else fails, this must work. Drives prioritization on tradeoffs.}}
+
+## Requirements
+
+### Validated
+
+<!-- Shipped and confirmed valuable. -->
+
+(None yet — ship to validate)
+
+### Active
+
+<!-- Current scope being built toward. These are hypotheses until shipped. -->
+
+- [ ] {{REQUIREMENT_1}}
+- [ ] {{REQUIREMENT_2}}
+- [ ] {{REQUIREMENT_3}}
+
+### Out of Scope
+
+<!-- Explicit boundaries. Include reasoning to prevent re-adding. -->
+
+- {{EXCLUSION_1}} — {{WHY}}
+
+## Context
+
+{{Background that informs implementation: technical environment, prior work, user feedback, known issues.}}
+
+## Constraints
+
+- **{{TYPE}}**: {{WHAT}} — {{WHY}}
+
+## Tech Stack
+
+- **Language**: {{LANGUAGE}}
+- **Framework**: {{FRAMEWORK}}
+- **Database**: {{DATABASE}}
+
+## Key Decisions
+
+<!-- Decisions that constrain future work. Add throughout project lifecycle. -->
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| {{CHOICE}} | {{WHY}} | — Pending |
+
+## Stakeholders
+
+- {{STAKEHOLDER_1}}
+
+---
+*Last updated: {{DATE}} after initialization*

package/templates/reflection-log.md

@@ -0,0 +1,20 @@
+# Reflection Log — Phase {NN}: {Title}
+
+## Entry {N}
+
+**Date**: {ISO date}
+**Trigger**: {What prompted this reflection}
+
+### What Happened
+
+{Description of the situation}
+
+### Strategy Adjustment
+
+- **Before**: {Previous approach}
+- **After**: {New approach}
+- **Reason**: {Why the change was needed}
+
+### Impact
+
+{How this adjustment affected subsequent work}

package/templates/roadmap.md

@@ -0,0 +1,45 @@
+# Roadmap: {{PROJECT_NAME}}
+
+## Overview
+
+{{One paragraph describing the journey from start to finish}}
+
+## Milestones
+
+### Milestone 1: {{MILESTONE_1_NAME}} ({{VERSION}})
+**Target**: {{DELIVERABLE_DESCRIPTION}}
+**Status**: active | completed | planned
+
+**Minimum-phase principle:** Default 1 phase per milestone. Only add phases for hard dependencies (runtime + not parallelizable + full barrier). Wave DAG inside each phase handles task ordering.
+
+**Phase Numbering:**
+- Integer phases (1, 2, 3): Planned milestone work
+- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)
+
+#### Phases
+
+- [ ] **Phase 1: {{PHASE_1_TITLE}}** — {{ONE_LINE_DESCRIPTION}}
+
+#### Phase Details
+
+##### Phase 1: {{PHASE_1_TITLE}}
+**Goal**: {{WHAT_THIS_PHASE_DELIVERS}}
+**Depends on**: Nothing (first phase)
+**Requirements**: {{REQ_IDS}}
+**Success Criteria** (what must be TRUE):
+  1. {{OBSERVABLE_BEHAVIOR_FROM_USER_PERSPECTIVE}}
+  2. {{OBSERVABLE_BEHAVIOR_FROM_USER_PERSPECTIVE}}
+
+---
+
+## Scope Decisions
+
+- **In scope**: {{INCLUDED}}
+- **Deferred**: {{LATER_MILESTONES}}
+- **Out of scope**: {{EXCLUDED}}
+
+## Progress
+
+| Milestone | Phase | Status | Completed |
+|-----------|-------|--------|-----------|
+| 1. {{MILESTONE_1_NAME}} | 1. {{PHASE_1_TITLE}} | Not started | - |

package/templates/scratch-index.json

@@ -0,0 +1,19 @@
+{
+  "id": "{{TYPE}}-{{SLUG}}-{{DATE}}",
+  "type": "quick",
+  "title": "{{TITLE}}",
+  "status": "active",
+  "created_at": "{{TIMESTAMP}}",
+  "updated_at": "{{TIMESTAMP}}",
+
+  "plan": {
+    "task_ids": [],
+    "task_count": 0
+  },
+
+  "execution": {
+    "method": "agent",
+    "tasks_completed": 0,
+    "tasks_total": 0
+  }
+}

package/templates/search-tool.json

@@ -0,0 +1 @@
+{ "name": "mcp__ace-tool__search_context" }

package/templates/search-tools.md

@@ -0,0 +1,47 @@
+# Search Tools
+
+## Semantic Search Tool
+
+@~/.maestro/templates/search-tool.json
+
+## Priority
+
+```
+maestro explore (structured) → Semantic Search → Grep (pattern) → Glob (files)
+```
+
+## Tool Selection
+
+| Scenario | Tool |
+|----------|------|
+| Multi-angle codebase scan | `maestro explore` with multi-prompt parallel |
+| Targeted code search (known scope) | `maestro explore` single prompt with FIND/SCOPE |
+| Find by intent/behavior | Semantic search tool (see above) |
+| Known identifier/regex | `Grep` |
+| Find files by name/ext | `Glob` |
+| Deep cross-file reasoning | `maestro delegate --role analyze --mode analysis` |
+| Read identified file | `Read` |
+
+## maestro explore Prompt Format
+
+```
+FIND: [what to search for]
+SCOPE: [file patterns or directories]
+EXCLUDE: [what to skip]
+ATTENTION: [caveats, edge cases]
+EXPECTED: [output format]
+```
+
+Single prompt: `maestro explore "FIND: ... SCOPE: src/" --max-turns 3`
+
+Multi-prompt parallel: `maestro explore "prompt1" "prompt2" --json`
+
+## Fallback
+
+- **explore unavailable** → Semantic search + Grep + Glob pattern scanning
+- **Semantic search unavailable** → Grep + Glob; log degraded mode
+- **Grep insufficient** → Escalate to CLI delegate analysis
+
+## Combined Strategy
+
+For thorough exploration: maestro explore (broad) → Grep (validate specific) → Read (deep examine)

package/templates/state.json

@@ -0,0 +1,18 @@
+{
+  "version": "3.1",
+  "project_name": "{{PROJECT_NAME}}",
+  "status": "idle",
+  "current_milestone": null,
+  "current_task_id": null,
+  "milestones": [],
+  "_milestone_schema": "{ id, name, type: 'standard'|'adhoc', status, phases[], phase_slugs{}, roadmap_ref, created_at }",
+  "artifacts": [],
+  "last_updated": "{{TIMESTAMP}}",
+  "accumulated_context": {
+    "key_decisions": [],
+    "blockers": [],
+    "deferred": []
+  },
+  "transition_history": [],
+  "milestone_history": []
+}

package/templates/task-summary.md

@@ -0,0 +1,21 @@
+# Task Summary — {TASK-NNN}: {Title}
+
+## Status: {completed | failed}
+
+## Changes Made
+
+| File | Action | Description |
+|------|--------|-------------|
+| {path} | create/modify | {What changed} |
+
+## Verification
+
+- {Verification step and result}
+
+## Key Decisions
+
+- {Decision made during implementation}
+
+## Notes
+
+{Any additional context for future reference}

package/templates/task.json

@@ -0,0 +1,89 @@
+{
+  "id": "TASK-{{NNN}}",
+  "title": "{{TITLE}}",
+  "description": "{{DESCRIPTION}}",
+
+  "issue_id": null,
+  "issue_refs": [],
+  "type": "feature",
+  "priority": "medium",
+  "effort": "medium",
+  "action": "{{CONCRETE_ACTION_WITH_EXACT_VALUES}}",
+  "status": "pending",
+  "completed_at": null,
+  "actual_duration": null,
+
+  "scope": "{{MODULE_PATH}}",
+  "focus_paths": [],
+
+  "read_first": [
+    "{{FILE_BEING_MODIFIED}}",
+    "{{SOURCE_OF_TRUTH_OR_PATTERN_FILE}}"
+  ],
+
+  "depends_on": [],
+  "wave": 1,
+  "parallel_group": null,
+  "execution_group": null,
+  "executor": "agent",
+
+  "convergence": {
+    "criteria": [
+      "{{FILE_PATH}} contains '{{EXACT_STRING_OR_PATTERN}}'",
+      "{{TEST_COMMAND}} exits 0"
+    ],
+    "verification": "{{VERIFICATION_COMMAND_OR_STEPS}}",
+    "definition_of_done": "{{BUSINESS_LANGUAGE_COMPLETION}}"
+  },
+
+  "files": [
+    {
+      "path": "{{FILE_PATH}}",
+      "action": "modify",
+      "target": "{{FUNCTION_OR_CLASS}}",
+      "change": "{{CONCRETE_CHANGE_WITH_EXACT_VALUES}}"
+    }
+  ],
+
+  "implementation": [
+    "{{STEP_1_WITH_CONCRETE_VALUES}}",
+    "{{STEP_2_WITH_CONCRETE_VALUES}}"
+  ],
+
+  "test": {
+    "commands": [],
+    "unit": [],
+    "integration": [],
+    "success_metrics": []
+  },
+
+  "reference": {
+    "pattern": "{{EXISTING_PATTERN}}",
+    "files": [],
+    "examples": null
+  },
+
+  "rationale": {
+    "chosen_approach": "{{WHY_THIS_APPROACH}}",
+    "decision_factors": [],
+    "tradeoffs": null
+  },
+
+  "risks": [],
+
+  "code_skeleton": null,
+
+  "doc_context": {
+    "affected_features": [],
+    "affected_components": [],
+    "affected_requirements": [],
+    "adr_ids": []
+  },
+
+  "meta": {
+    "estimated_time": null,
+    "risk": "low",
+    "autonomous": true,
+    "checkpoint": false
+  }
+}

package/templates/terminology-template.json

@@ -0,0 +1,22 @@
+{
+  "version": "1.0",
+  "description": "Terminology glossary schema for brainstorm guidance-specification",
+  "schema": {
+    "terminology": {
+      "type": "array",
+      "items": {
+        "term": "string (required) - canonical term",
+        "definition": "string (required) - concise definition",
+        "aliases": "array of strings - alternative names",
+        "category": "enum: core|technical|business (required)",
+        "first_used_in": "string - source document"
+      }
+    }
+  },
+  "validation_rules": {
+    "min_terms": 5,
+    "max_terms": 20,
+    "term_format": "lowercase, alphanumeric + hyphens",
+    "definition_max_length": 200
+  }
+}

package/templates/uat.md

@@ -0,0 +1,21 @@
+# UAT: Phase {{PHASE_NUM}} — {{PHASE_TITLE}}
+
+## Test Results
+
+| # | Test | Expected | Result | Status |
+|---|------|----------|--------|--------|
+| 1 | {{TEST_1}} | {{EXPECTED_1}} | {{RESULT_1}} | ⏳ |
+
+## Issues Found
+
+### Issue 1: {{ISSUE_TITLE}}
+- **Severity**: {{SEVERITY}}
+- **Description**: {{DESCRIPTION}}
+- **Steps to Reproduce**: {{STEPS}}
+- **Fix Direction**: {{FIX}}
+
+## Summary
+- **Total Tests**: 0
+- **Passed**: 0
+- **Failed**: 0
+- **Blocked**: 0

package/templates/validation.json

@@ -0,0 +1,31 @@
+{
+  "phase": 0,
+  "status": "pending",
+  "validated_at": null,
+  "test_framework": null,
+  "infrastructure": {
+    "framework": null,
+    "runner": null,
+    "config_file": null
+  },
+  "coverage": {
+    "statements": 0,
+    "branches": 0,
+    "functions": 0,
+    "lines": 0
+  },
+  "requirement_coverage": [],
+  "gaps": [
+    {
+      "_schema": "Unified gap object",
+      "id": "GAP-NNN",
+      "type": "must_have|coverage|anti_pattern|uat",
+      "severity": "critical|high|medium|low",
+      "description": "...",
+      "source": "layer1|layer2|layer3|nyquist|uat",
+      "status": "open|planned|fixed",
+      "related_issue": null
+    }
+  ],
+  "suggested_tests": []
+}

package/templates/verification.json

@@ -0,0 +1,37 @@
+{
+  "phase": 0,
+  "status": "pending",
+  "verified_at": null,
+  "verifier": "workflow-verifier",
+  "must_haves": {
+    "truths": [],
+    "artifacts": [],
+    "key_links": []
+  },
+  "layer1_truths": [],
+  "layer2_artifacts": [],
+  "layer3_wiring": [],
+  "anti_pattern_scan": {
+    "status": "pending",
+    "blockers": [],
+    "warnings": []
+  },
+  "nyquist": {
+    "status": "pending",
+    "coverage_score": null,
+    "requirement_map": []
+  },
+  "gaps": [
+    {
+      "_schema": "Unified gap object",
+      "id": "GAP-NNN",
+      "type": "must_have|coverage|anti_pattern|uat",
+      "severity": "critical|high|medium|low",
+      "description": "...",
+      "source": "layer1|layer2|layer3|nyquist|uat",
+      "status": "open|planned|fixed",
+      "related_issue": null
+    }
+  ],
+  "fix_plans": []
+}

package/templates/workflow.md

@@ -0,0 +1,14 @@
+# Workflow: {{WORKFLOW_NAME}}
+
+## Trigger
+{{TRIGGER_DESCRIPTION}}
+
+## Steps
+
+### Step 1: {{STEP_NAME}}
+- **Action**: {{ACTION}}
+- **Input**: {{INPUT}}
+- **Output**: {{OUTPUT}}
+
+## Completion Criteria
+- {{CRITERIA}}

package/templates/worktree-scope.json

@@ -0,0 +1,9 @@
+{
+  "worktree": true,
+  "milestone_num": "{{MILESTONE_NUMBER}}",
+  "milestone": "{{MILESTONE_NAME}}",
+  "main_worktree": "{{MAIN_WORKTREE_PATH}}",
+  "branch": "milestone/{{MILESTONE_SLUG}}",
+  "base_commit": "{{BASE_COMMIT}}",
+  "created_at": "{{TIMESTAMP}}"
+}

package/templates/worktrees.json

@@ -0,0 +1,26 @@
+{
+  "version": "1.0",
+  "worktrees": [
+    {
+      "milestone_num": "{{MILESTONE_NUMBER}}",
+      "milestone": "{{MILESTONE_NAME}}",
+      "slug": "{{MILESTONE_SLUG}}",
+      "branch": "milestone/{{MILESTONE_SLUG}}",
+      "path": "{{WORKTREE_ROOT}}/m{{MILESTONE_NUMBER}}-{{MILESTONE_SLUG}}",
+      "base_commit": "{{BASE_COMMIT}}",
+      "status": "active",
+      "created_at": "{{TIMESTAMP}}",
+      "fork_session": "{{FORK_SESSION_ID}}"
+    }
+  ],
+  "fork_sessions": [
+    {
+      "session_id": "fork-{{TIMESTAMP_SHORT}}",
+      "created_at": "{{TIMESTAMP}}",
+      "milestone_num": "{{MILESTONE_NUMBER}}",
+      "milestone": "{{MILESTONE_NAME}}",
+      "base_branch": "{{BASE_BRANCH}}",
+      "base_commit": "{{BASE_COMMIT}}"
+    }
+  ]
+}