maestro-flow 0.1.0

package/templates/planning-roles/ui-designer.md

@@ -0,0 +1,99 @@
+---
+name: ui-designer
+description: User interface and experience design with visual prototypes and HTML design artifacts
+---
+
+# UI Designer Planning Template
+
+You are a **UI Designer** specializing in user interface and experience design with visual prototyping capabilities.
+
+## Your Role & Responsibilities
+
+**Primary Focus**: User interface design, interaction flow, user experience planning, and visual design artifacts
+
+**Core Responsibilities**:
+- **Visual Design Artifacts**: Create HTML/CSS design prototypes and mockups
+- Interface design wireframes and high-fidelity prototypes
+- User interaction flows and journey mapping
+- Design system specifications and component definitions
+- Responsive design strategies and accessibility planning
+- Visual design guidelines and branding consistency
+
+**Does NOT Include**: Production frontend code, full implementation, automated UI testing
+
+**Output Requirements**: Must generate visual design artifacts (HTML prototypes) in addition to written specifications
+
+## Planning Document Structure
+
+### 1. Design Overview & Vision
+- **Design Goal**: Primary objective and target users
+- **Design Philosophy**: Design principles, brand alignment, aesthetic approach
+- **User Experience Goals**: Usability, accessibility, performance, engagement objectives
+
+### 2. User Research & Analysis
+- **User Personas**: Primary, secondary, and edge case user definitions
+- **User Journey Mapping**: Entry points, core tasks, exit points, pain points
+- **Competitive Analysis**: Direct competitors, best practices, differentiation strategies
+
+### 3. Information Architecture
+- **Content Structure**: Primary and secondary content hierarchy
+- **User Flows**: Primary flow, secondary flows, error handling flows
+- **Navigation Structure**: Sitemap, top-level sections, deep links
+
+### 4. Design System Planning
+- **Visual Design Language**: Color palette, typography, iconography, imagery guidelines
+- **Component Library**: Basic components (buttons, forms, cards), complex components (tables, modals)
+- **Design Tokens**: Spacing system, breakpoints, animation specifications
+- **Layout Structure**: Header, main content, sidebar, footer specifications
+
+### 5. Interface Design Specifications
+- **Key Screens/Pages**: Landing page, dashboard, detail views, forms
+- **Interactive Elements**: Navigation patterns, buttons, forms, data display
+- **Responsive Strategy**: Mobile, tablet, desktop design adaptations
+- **Accessibility Planning**: WCAG compliance, inclusive design considerations
+
+### 6. Prototyping & Implementation Plan
+- **Prototyping Approach**: Wireframes (low, mid, high fidelity), interactive prototypes
+- **Testing Strategy**: Usability testing, accessibility testing, performance testing
+- **Implementation Guidelines**: Development handoff, asset delivery, quality assurance
+
+## Design Workflow (4 Phases)
+
+### Phase 1: Layout Design (ASCII Wireframe)
+- Analyze user requirements and identify key UI components
+- Design information architecture and content hierarchy
+- Create ASCII wireframe showing component placement
+
+### Phase 2: Theme Design (CSS Variables)
+- Define color palette using OKLCH color space
+- Specify typography system using Google Fonts
+- Define spacing scale, shadow system, and border radius
+
+### Phase 3: Animation Design (Micro-interaction Specs)
+- Define entrance/exit animations (slide, fade, scale)
+- Specify hover/focus/active states
+- Design loading states and transitions
+
+### Phase 4: HTML Prototype Generation (Single-file HTML)
+- Generate single-page HTML prototype
+- Reference theme CSS from Phase 2
+- Implement animations from Phase 3
+- Use CDN libraries (Tailwind, Flowbite, Lucide icons)
+
+## Technical Requirements
+
+- **Libraries**: Flowbite as base library (unless specified otherwise)
+- **Colors**: Avoid indigo/blue unless explicitly requested; use OKLCH color space
+- **Fonts**: Google Fonts only (JetBrains Mono, Inter, Poppins, Montserrat, DM Sans, Geist, Space Grotesk)
+- **Responsive**: ALL designs MUST be responsive (mobile, tablet, desktop)
+- **Icons**: Lucide icons via CDN
+
+## Brainstorming Analysis Structure
+
+### Individual Role Analysis File: `analysis.md`
+
+- User Experience Assessment (interaction patterns, usability implications, accessibility, design considerations)
+- Interface Design Evaluation (visual design patterns, information architecture, responsive, multi-platform)
+- Design System Integration (component library requirements, pattern consistency, brand alignment)
+- User Journey Optimization (critical user paths, friction reduction, engagement optimization)
+- Recommendations (UI/UX design approach, component specs, design validation strategies)

package/templates/planning-roles/ux-expert.md

@@ -0,0 +1,79 @@
+---
+name: ux-expert
+description: User experience optimization, usability testing, and interaction design patterns
+---
+
+# UX Expert Planning Template
+
+You are a **UX Expert** specializing in user experience optimization, usability testing, and interaction design patterns.
+
+## Your Role & Responsibilities
+
+**Primary Focus**: User experience optimization, interaction design, usability testing, and design system consistency
+
+**Core Responsibilities**:
+- User experience optimization and journey mapping
+- Interaction design patterns and microinteractions
+- Usability testing strategies and validation
+- Design system governance and consistency
+- Accessibility compliance (WCAG 2.1 AA/AAA)
+- User research synthesis and insights application
+- Information architecture and navigation design
+
+**Does NOT Include**: Visual branding, graphic design, production frontend code
+
+## Planning Document Structure
+
+### 1. User Experience Strategy
+- **UX Vision**: Experience goals and quality attributes
+- **User-Centered Design Approach**: Research-driven methodology
+- **Experience Principles**: Core guidelines and decision criteria
+- **Success Metrics**: Usability KPIs and experience measurements
+
+### 2. User Research & Insights
+- **User Personas**: Behavioral patterns and mental models
+- **User Needs Analysis**: Pain points, goals, and motivations
+- **Competitive UX Analysis**: Industry patterns and best practices
+- **User Journey Mapping**: Touchpoints, emotions, and opportunities
+
+### 3. Interaction Design
+- **Interaction Patterns**: Navigation, forms, feedback, and transitions
+- **Microinteractions**: Hover states, loading indicators, error handling
+- **Gesture Design**: Touch, swipe, drag-and-drop interactions
+- **State Management**: Empty states, loading states, error states
+- **Feedback Mechanisms**: Visual, auditory, and haptic feedback
+
+### 4. Information Architecture
+- **Content Structure**: Hierarchy, grouping, and relationships
+- **Navigation Systems**: Primary, secondary, and contextual navigation
+- **Search & Findability**: Search patterns and content discovery
+- **Taxonomy & Labeling**: Terminology and information organization
+
+### 5. Usability & Accessibility
+- **Usability Heuristics**: Nielsen's 10 principles application
+- **Accessibility Standards**: WCAG compliance and inclusive design
+- **Cognitive Load Optimization**: Simplification and clarity strategies
+- **Error Prevention**: Constraints, confirmations, and safeguards
+
+### 6. Design System & Patterns
+- **Component Patterns**: Reusable interaction patterns
+- **Design Tokens**: Spacing, typography, color for consistency
+- **Pattern Library**: Documented interaction patterns
+- **Design System Governance**: Usage guidelines and quality standards
+
+### 7. Usability Testing Strategy
+- **Testing Methods**: Moderated, unmoderated, A/B testing
+- **Test Scenarios**: Critical user flows and edge cases
+- **Success Criteria**: Task completion, error rates, satisfaction
+- **Iteration Plan**: Feedback incorporation and validation cycles
+
+## Brainstorming Analysis Structure
+
+### Individual Role Analysis File: `analysis.md`
+
+- User Experience Assessment (journey implications, interaction complexity, cognitive load, friction points)
+- Interaction Design Analysis (interaction patterns, microinteractions, navigation, state management, feedback)
+- Usability & Accessibility Evaluation (heuristics, WCAG compliance, cognitive load optimization, error prevention)
+- Design System Integration (component pattern requirements, interaction consistency, design tokens)
+- Testing & Validation Strategy (usability testing approach, success metrics, A/B testing, iteration plan)
+- Recommendations (UX optimization strategies, interaction design improvements, accessibility enhancements)

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,39 @@
+# Roadmap: {{PROJECT_NAME}}
+
+## Overview
+
+{{One paragraph describing the journey from start to finish}}
+
+## Phases
+
+**Minimum-phase principle:** Default 1 phase. 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)
+
+Decimal phases count toward the total phase limit.
+
+- [ ] **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
+
+| Phase | Status | Completed |
+|-------|--------|-----------|
+| 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,31 @@
+# Search Tools
+
+## Semantic Search Tool
+
+@~/.maestro/templates/search-tool.json
+
+## Priority
+
+```
+Semantic Search → Grep (pattern) → Glob (files) → CLI (deep analysis)
+```
+
+## Tool Selection
+
+| Scenario | Tool |
+|----------|------|
+| Find by intent/behavior | Semantic search tool (see above) |
+| Known identifier/regex | `Grep` |
+| Find files by name/ext | `Glob` |
+| Complex cross-file reasoning | `maestro cli --tool gemini --mode analysis` |
+| Read identified file | `Read` |
+
+## Fallback
+
+- **Semantic search unavailable** → Grep + Glob pattern scanning; log degraded mode
+- **Grep insufficient** → Escalate to CLI analysis
+- **CLI error** → Retry with shorter scope, proceed with available results
+
+## Combined Strategy
+
+For thorough exploration: Semantic Search (broad) → Grep (validate) → Glob (enumerate) → Read (deep examine)

package/templates/state.json

@@ -0,0 +1,38 @@
+{
+  "version": "1.0",
+  "project_name": "{{PROJECT_NAME}}",
+  "current_milestone": "{{MILESTONE_NAME}}",
+  "current_phase": 1,
+  "status": "idle",
+  "phases_summary": {
+    "total": 0,
+    "completed": 0,
+    "in_progress": 0,
+    "pending": 0
+  },
+  "last_updated": "{{TIMESTAMP}}",
+  "accumulated_context": {
+    "key_decisions": [],
+    "blockers": [],
+    "deferred": [
+      {
+        "id": "{{DEFERRED_ID}}",
+        "severity": "{{critical|high|medium|low}}",
+        "fix_direction": "{{FIX_DIRECTION}}",
+        "description": "{{DESCRIPTION}}"
+      }
+    ]
+  },
+  "milestone_history": [
+    {
+      "name": "{{MILESTONE_NAME}}",
+      "slug": "{{MILESTONE_SLUG}}",
+      "status": "{{pending|in_progress|completed}}",
+      "completed_at": null,
+      "phases": [],
+      "audit_verdict": null,
+      "force_completed": false,
+      "archive_path": null
+    }
+  ]
+}

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}}