pi-maestro-flow 0.2.0 → 0.3.0

package/templates/business-test-report.json

@@ -0,0 +1,68 @@
+{
+  "_template_note": "Template for business-test-report.json. Fields marked with {placeholder} are filled at runtime.",
+  "phase": "{phase}",
+  "blueprint_ref": "{blueprint_ref}",
+  "spec_mode": "full|degraded",
+  "completed_at": "{ISO timestamp}",
+  "execution_mode": "gen-code|agent",
+  "iterations": {
+    "L1": { "count": 0, "converged": false },
+    "L2": { "count": 0, "converged": false },
+    "L3": { "count": 0, "converged": false }
+  },
+  "layers": {
+    "L1": { "total": 0, "passed": 0, "failed": 0, "blocked": 0, "pass_rate": 0.0 },
+    "L2": { "total": 0, "passed": 0, "failed": 0, "blocked": 0, "pass_rate": 0.0 },
+    "L3": { "total": 0, "passed": 0, "failed": 0, "blocked": 0, "pass_rate": 0.0 }
+  },
+  "requirement_coverage": [
+    {
+      "_example": true,
+      "req_id": "REQ-001",
+      "title": "Requirement title",
+      "total_criteria": 0,
+      "criteria_results": [
+        {
+          "ac_id": "AC-1",
+          "description": "Acceptance criterion text",
+          "priority": "critical|high|medium",
+          "status": "passed|failed|blocked|untested",
+          "tests": ["BT-001"],
+          "failure": null
+        }
+      ],
+      "coverage_pct": 0.0,
+      "verdict": "verified|partial|unverified"
+    }
+  ],
+  "failures": [
+    {
+      "_example": true,
+      "id": "BF-001",
+      "test_id": "BT-001",
+      "req_ref": "REQ-001:AC-1",
+      "layer": "L1|L2|L3",
+      "severity": "critical|high|medium",
+      "classification": "code_defect|test_defect|env_issue",
+      "description": "Failure description",
+      "expected": "Expected behavior",
+      "actual": "Actual behavior",
+      "fix_suggestion": {
+        "file": "src/...",
+        "line": 0,
+        "direction": "Fix direction"
+      }
+    }
+  ],
+  "summary": {
+    "total_requirements": 0,
+    "fully_verified": 0,
+    "partially_verified": 0,
+    "unverified": 0,
+    "coverage_pct": 0.0,
+    "total_scenarios": 0,
+    "total_passed": 0,
+    "total_failed": 0,
+    "total_blocked": 0
+  }
+}

package/templates/config.json

@@ -0,0 +1,48 @@
+{
+  "workflow": {
+    "research": true,
+    "reflection": true
+  },
+
+  "execution": {
+    "method": "auto",
+    "auto_commit": true,
+    "default_executor": ""
+  },
+
+  "git": {
+    "commit_docs": true
+  },
+
+  "gates": {
+    "confirm_roadmap": true,
+    "confirm_plan": true
+  },
+
+  "codebase": {
+    "auto_sync_after_execute": true
+  },
+
+  "guard": {
+    "enabled": false,
+    "mode": "allow",
+    "paths": []
+  },
+
+  "collab": {
+    "preflight_mode": "warn",
+    "preflight_window_min": 30,
+    "auto_preflight": true
+  },
+
+  "specInjection": {},
+
+  "dashboard": {
+    "port": 3001
+  },
+
+  "worktree": {
+    "root": ".worktrees",
+    "branch_prefix": "milestone/"
+  }
+}

package/templates/context.md

@@ -0,0 +1,16 @@
+# Context: Phase {{PHASE_NUM}} — {{PHASE_TITLE}}
+
+## Decisions
+
+### Decision 1: {{DECISION_TITLE}}
+- **Context**: {{WHAT_NEEDS_DECIDING}}
+- **Options**:
+  1. {{OPTION_1}}
+  2. {{OPTION_2}}
+- **Chosen**: {{CHOSEN_OPTION}}
+- **Reason**: {{RATIONALE}}
+
+## Constraints
+- **Locked**: {{LOCKED_DECISIONS}}
+- **Free**: {{FREE_DECISIONS}}
+- **Deferred**: {{DEFERRED_DECISIONS}}

package/templates/doc-index.json

@@ -0,0 +1,11 @@
+{
+  "version": "1.0",
+  "schema_version": "1.0",
+  "project": "{{PROJECT_NAME}}",
+  "last_updated": "{{TIMESTAMP}}",
+  "features": [],
+  "components": [],
+  "requirements": [],
+  "architecture_decisions": [],
+  "actions": []
+}

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