maestro-flow 0.1.0

package/templates/cli/prompts/workflow-task-json-agent-mode.txt

@@ -0,0 +1,123 @@
+Task JSON Schema - Agent Mode (No Command Field)
+
+## Schema Structure
+
+```json
+{
+  "id": "IMPL-N[.M]",
+  "title": "Descriptive task name",
+  "status": "pending",
+  "context_package_path": "{context_package_path}",
+  "meta": {
+    "type": "feature|bugfix|refactor|test|docs",
+    "agent": "@code-developer|@test-fix-agent|@universal-executor"
+  },
+  "context": {
+    "requirements": ["extracted from analysis"],
+    "focus_paths": ["src/paths"],
+    "acceptance": ["measurable criteria"],
+    "depends_on": ["IMPL-N"],
+    "artifacts": [
+      {
+        "type": "synthesis_specification",
+        "path": "{synthesis_spec_path}",
+        "priority": "highest",
+        "usage": "Primary requirement source - use for consolidated requirements and cross-role alignment"
+      },
+      {
+        "type": "role_analysis",
+        "path": "{role_analysis_path}",
+        "priority": "high",
+        "usage": "Technical/design/business details from specific roles. Common roles: system-architect (ADRs, APIs, caching), ui-designer (design tokens, layouts), product-manager (user stories, metrics)"
+      }
+    ]
+  },
+  "flow_control": {
+    "pre_analysis": [
+      {
+        "step": "load_role_analyses_specification",
+        "action": "Load consolidated role analyses",
+        "commands": [
+          "Read({synthesis_spec_path})"
+        ],
+        "output_to": "synthesis_specification",
+        "on_error": "fail"
+      },
+      {
+        "step": "load_context_package",
+        "action": "Load context package for project structure",
+        "commands": [
+          "Read({context_package_path})"
+        ],
+        "output_to": "context_pkg",
+        "on_error": "fail"
+      },
+      {
+        "step": "local_codebase_exploration",
+        "action": "Explore codebase using local search",
+        "commands": [
+          "bash(rg '^(function|class|interface).*{keyword}' --type ts -n --max-count 15)",
+          "bash(find . -name '*{keyword}*' -type f | grep -v node_modules | head -10)"
+        ],
+        "output_to": "codebase_structure",
+        "on_error": "skip_optional"
+      }
+    ],
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Implement task following role analyses",
+        "description": "Implement '{title}' following [synthesis_specification] requirements and [context_pkg] patterns. Use role analyses as primary source, consult artifacts for technical details.",
+        "modification_points": [
+          "Apply consolidated requirements from role analyses",
+          "Follow technical guidelines from synthesis",
+          "Consult artifacts for implementation details when needed",
+          "Integrate with existing patterns"
+        ],
+        "logic_flow": [
+          "Load role analyses and context package",
+          "Analyze existing patterns from [codebase_structure]",
+          "Implement following specification",
+          "Consult artifacts for technical details when needed",
+          "Validate against acceptance criteria"
+        ],
+        "depends_on": [],
+        "output": "implementation"
+      }
+    ],
+    "target_files": ["file:function:lines", "path/to/NewFile.ts"]
+  }
+}
+```
+
+## Key Features - Agent Mode
+
+**Execution Model**: Agent interprets `modification_points` and `logic_flow` to execute autonomously
+
+**No Command Field**: Steps in `implementation_approach` do NOT include `command` field
+
+**Context Loading**: Context loaded via `pre_analysis` steps, available as variables (e.g., [synthesis_specification], [context_pkg])
+
+**Agent Execution**:
+- Agent reads modification_points and logic_flow
+- Agent performs implementation autonomously
+- Agent validates against acceptance criteria
+
+## Field Descriptions
+
+**implementation_approach**: Array of step objects (NO command field)
+- **step**: Sequential step number
+- **title**: Step description
+- **description**: Detailed instructions with variable references
+- **modification_points**: Specific code modifications to apply
+- **logic_flow**: Business logic execution sequence
+- **depends_on**: Step dependencies (empty array for independent steps)
+- **output**: Expected deliverable variable name
+
+## Usage Guidelines
+
+1. **Load Context**: Use pre_analysis to load synthesis, context package, and explore codebase
+2. **Reference Variables**: Use [variable_name] to reference outputs from pre_analysis steps
+3. **Clear Instructions**: Provide detailed modification_points and logic_flow for agent
+4. **No Commands**: Never add command field to implementation_approach steps
+5. **Agent Autonomy**: Let agent interpret and execute based on provided instructions

package/templates/cli/prompts/workflow-task-json-cli-mode.txt

@@ -0,0 +1,182 @@
+Task JSON Schema - CLI Execute Mode (With Command Field)
+
+## Schema Structure
+
+```json
+{
+  "id": "IMPL-N[.M]",
+  "title": "Descriptive task name",
+  "status": "pending",
+  "context_package_path": "{context_package_path}",
+  "meta": {
+    "type": "feature|bugfix|refactor|test|docs",
+    "agent": "@code-developer|@test-fix-agent|@universal-executor"
+  },
+  "context": {
+    "requirements": ["extracted from analysis"],
+    "focus_paths": ["src/paths"],
+    "acceptance": ["measurable criteria"],
+    "depends_on": ["IMPL-N"],
+    "artifacts": [
+      {
+        "type": "synthesis_specification",
+        "path": "{synthesis_spec_path}",
+        "priority": "highest",
+        "usage": "Primary requirement source - use for consolidated requirements and cross-role alignment"
+      },
+      {
+        "type": "role_analysis",
+        "path": "{role_analysis_path}",
+        "priority": "high",
+        "usage": "Technical/design/business details from specific roles"
+      }
+    ]
+  },
+  "flow_control": {
+    "pre_analysis": [
+      {
+        "step": "load_synthesis_specification",
+        "action": "Load consolidated synthesis specification",
+        "commands": [
+          "Read({synthesis_spec_path})"
+        ],
+        "output_to": "synthesis_specification",
+        "on_error": "fail"
+      },
+      {
+        "step": "load_context_package",
+        "action": "Load context package",
+        "commands": [
+          "Read({context_package_path})"
+        ],
+        "output_to": "context_pkg",
+        "on_error": "fail"
+      },
+      {
+        "step": "local_codebase_exploration",
+        "action": "Explore codebase using local search",
+        "commands": [
+          "bash(rg '^(function|class|interface).*{keyword}' --type ts -n --max-count 15)",
+          "bash(find . -name '*{keyword}*' -type f | grep -v node_modules | head -10)"
+        ],
+        "output_to": "codebase_structure",
+        "on_error": "skip_optional"
+      }
+    ],
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Implement task with Codex",
+        "description": "Implement '{title}' using Codex CLI tool",
+        "command": "bash(codex -C {focus_path} --full-auto exec \"PURPOSE: {purpose} TASK: {task_description} MODE: auto CONTEXT: @{{synthesis_spec_path}} @{{context_package_path}} EXPECTED: {expected_output} RULES: Follow synthesis specification\" --skip-git-repo-check -s danger-full-access)",
+        "modification_points": [
+          "Create/modify implementation files",
+          "Follow synthesis specification requirements",
+          "Integrate with existing patterns"
+        ],
+        "logic_flow": [
+          "Codex loads context package and synthesis",
+          "Codex implements according to specification",
+          "Codex validates against acceptance criteria"
+        ],
+        "depends_on": [],
+        "output": "implementation"
+      }
+    ],
+    "target_files": ["file:function:lines", "path/to/NewFile.ts"]
+  }
+}
+```
+
+## Multi-Step Example (Complex Task with Resume)
+
+```json
+{
+  "id": "IMPL-002",
+  "title": "Implement RBAC system",
+  "flow_control": {
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Create RBAC models",
+        "description": "Create role and permission data models",
+        "command": "bash(codex -C src/models --full-auto exec \"PURPOSE: Create RBAC models TASK: Define role and permission models MODE: auto CONTEXT: @{{synthesis_spec_path}} @{{context_package_path}} EXPECTED: Models with migrations RULES: Follow synthesis spec\" --skip-git-repo-check -s danger-full-access)",
+        "modification_points": ["Define role model", "Define permission model"],
+        "logic_flow": ["Design schema", "Implement models", "Generate migrations"],
+        "depends_on": [],
+        "output": "rbac_models"
+      },
+      {
+        "step": 2,
+        "title": "Implement RBAC middleware",
+        "description": "Create route protection middleware",
+        "command": "bash(codex --full-auto exec \"PURPOSE: Create RBAC middleware TASK: Route protection middleware MODE: auto CONTEXT: RBAC models from step 1 EXPECTED: Middleware for route protection RULES: Use session patterns\" resume --last --skip-git-repo-check -s danger-full-access)",
+        "modification_points": ["Create permission checker", "Add route decorators"],
+        "logic_flow": ["Check user role", "Validate permissions", "Allow/deny access"],
+        "depends_on": [1],
+        "output": "rbac_middleware"
+      }
+    ]
+  }
+}
+```
+
+## Key Features - CLI Execute Mode
+
+**Execution Model**: Commands in `command` field execute steps directly
+
+**Command Field Required**: Every step in `implementation_approach` MUST include `command` field
+
+**Context Delivery**: Context provided via CONTEXT field in command prompt using `@{path}` syntax
+
+**Multi-Step Support**:
+- First step: Full context with `-C directory` and complete CONTEXT field
+- Subsequent steps: Use `resume --last` to maintain session continuity
+- Step dependencies: Use `depends_on` array to specify step order
+
+## Command Templates
+
+### Single-Step Codex Command
+```bash
+bash(codex -C {focus_path} --full-auto exec "PURPOSE: {purpose} TASK: {task} MODE: auto CONTEXT: @{{synthesis_spec_path}} @{{context_package_path}} EXPECTED: {expected} RULES: {rules}" --skip-git-repo-check -s danger-full-access)
+```
+
+### Multi-Step Codex with Resume
+```bash
+# First step
+bash(codex -C {path} --full-auto exec "..." --skip-git-repo-check -s danger-full-access)
+
+# Subsequent steps
+bash(codex --full-auto exec "..." resume --last --skip-git-repo-check -s danger-full-access)
+```
+
+### Gemini/Qwen Commands (Analysis/Documentation)
+```bash
+bash(gemini "PURPOSE: {purpose} TASK: {task} MODE: analysis CONTEXT: @{synthesis_spec_path} EXPECTED: {expected} RULES: {rules}")
+
+# With write permission
+bash(gemini --approval-mode yolo "PURPOSE: {purpose} TASK: {task} MODE: write CONTEXT: @{context} EXPECTED: {expected} RULES: {rules}")
+```
+
+## Field Descriptions
+
+**implementation_approach**: Array of step objects (WITH command field)
+- **step**: Sequential step number
+- **title**: Step description
+- **description**: Brief step description
+- **command**: Complete CLI command to execute the step
+- **modification_points**: Specific code modifications (for reference)
+- **logic_flow**: Execution sequence (for reference)
+- **depends_on**: Step dependencies (array of step numbers, empty for independent)
+- **output**: Expected deliverable variable name
+
+## Usage Guidelines
+
+1. **Always Include Command**: Every step MUST have a `command` field
+2. **Context via CONTEXT Field**: Provide context using `@{path}` syntax in command prompt
+3. **First Step Full Context**: First step should include `-C directory` and full context package
+4. **Resume for Continuity**: Use `resume --last` for subsequent steps in same task
+5. **Step Dependencies**: Use `depends_on: [1, 2]` to specify execution order
+6. **Parameter Position**:
+   - Codex: `--skip-git-repo-check -s danger-full-access` at END
+   - Gemini/Qwen: `--approval-mode yolo` BEFORE the prompt

package/templates/cli/protocols/analysis-protocol.md

@@ -0,0 +1,121 @@
+# Analysis Mode Protocol
+
+## Mode Definition
+**Mode**: `analysis` (READ-ONLY)
+## Prompt Structure
+
+```
+PURPOSE: [development goal]
+TASK: [specific implementation task]
+MODE: [auto|write]
+CONTEXT: [file patterns]
+EXPECTED: [deliverables]
+RULES: [templates | additional constraints]
+```
+## Operation Boundaries
+
+### ALLOWED Operations
+- **READ**: All CONTEXT files and analyze content
+- **ANALYZE**: Code patterns, architecture, dependencies
+- **GENERATE**: Text output, insights, recommendations
+- **DOCUMENT**: Analysis results in output response only
+
+### FORBIDDEN Operations
+- **NO FILE CREATION**: Cannot create any files on disk
+- **NO FILE MODIFICATION**: Cannot modify existing files
+- **NO FILE DELETION**: Cannot delete any files
+- **NO DIRECTORY OPERATIONS**: Cannot create/modify directories
+
+**CRITICAL**: Absolutely NO file system operations - OUTPUT ONLY
+
+## Execution Flow
+
+0. **Load Project Specs** - MANDATORY first step: run `ccw spec load` to retrieve project specifications and constraints before any analysis. Adapt analysis scope and standards based on loaded specs
+1. **Parse** all 6 fields (PURPOSE, TASK, MODE, CONTEXT, EXPECTED, RULES)
+2. **Read** and analyze CONTEXT files thoroughly
+3. **Identify** patterns, issues, and dependencies
+4. **Generate** insights and recommendations
+5. **Validate** EXPECTED deliverables met
+6. **Output** structured analysis (text response only)
+
+## Core Requirements
+
+**ALWAYS**:
+- Run `ccw spec load` FIRST to obtain project specifications before starting any work
+- Analyze ALL CONTEXT files completely
+- Apply RULES (templates + constraints) exactly
+- Provide code evidence with `file:line` references
+- List all related/analyzed files at output beginning
+- Match EXPECTED deliverables precisely
+
+**NEVER**:
+- Assume behavior without code verification
+- Ignore CONTEXT file patterns
+- Skip RULES or templates
+- Make unsubstantiated claims
+- Create/modify/delete any files
+
+## RULES Processing
+
+- Parse RULES field to extract template content and constraints
+- Recognize `|` as separator: `template content | additional constraints`
+- Apply ALL template guidelines as mandatory
+- Treat rule violations as task failures
+
+## Error Handling
+
+**File Not Found**: Report missing files, continue with available, note in output
+**Invalid CONTEXT Pattern**: Report invalid pattern, request correction, do not guess
+
+## Quality Standards
+
+- **Thoroughness**: Analyze ALL files, check cross-file patterns, quantify metrics
+- **Evidence-Based**: Quote code with `file:line`, link patterns, support claims with examples
+- **Actionable**: Clear recommendations, prioritized by impact, incremental changes
+
+---
+
+## Output Format
+
+### Format Priority
+
+**If template defines output format** → Follow template format EXACTLY
+
+**If template has no format** → Use default format below
+
+### Default Analysis Output
+
+```markdown
+# Analysis: [TASK Title]
+
+## Related Files
+- `path/to/file1.ext` - [Brief description of relevance]
+- `path/to/file2.ext` - [Brief description of relevance]
+
+## Summary
+[2-3 sentence overview]
+
+## Key Findings
+1. [Finding] - path/to/file:123
+2. [Finding] - path/to/file:456
+
+## Detailed Analysis
+[Evidence-based analysis with code quotes]
+
+## Recommendations
+1. [Actionable recommendation]
+2. [Actionable recommendation]
+```
+
+### Code References
+
+**Format**: `path/to/file:line_number`
+**Example**: `src/auth/jwt.ts:45` - Authentication uses deprecated algorithm
+
+### Quality Checklist
+
+- [ ] All CONTEXT files analyzed
+- [ ] Code evidence with `file:line` references
+- [ ] Specific, actionable recommendations
+- [ ] No unsubstantiated claims
+- [ ] EXPECTED deliverables met

package/templates/cli/protocols/write-protocol.md

@@ -0,0 +1,138 @@
+# Write Mode Protocol
+## Prompt Structure
+
+```
+PURPOSE: [development goal]
+TASK: [specific implementation task]
+MODE: [auto|write]
+CONTEXT: [file patterns]
+EXPECTED: [deliverables]
+RULES: [templates | additional constraints]
+```
+## Operation Boundaries
+
+### MODE: write
+- **READ**: All CONTEXT files and analyze content
+- **CREATE**: New files (documentation, code, configuration)
+- **MODIFY**: Existing files (update content, refactor code)
+- **DELETE**: Files when explicitly required
+
+**Restrictions**: Follow project conventions, cannot break existing functionality
+
+**Constraint**: Must test every change
+
+## Execution Flow
+
+### MODE: write
+0. **Load Project Specs** - MANDATORY first step: run `ccw spec load` to retrieve project specifications and constraints before any implementation. Apply loaded specs to guide coding standards, architecture decisions, and quality gates
+1. **Parse** all 6 fields (PURPOSE, TASK, MODE, CONTEXT, EXPECTED, RULES)
+2. **Read** CONTEXT files, find 3+ similar patterns
+3. **Plan** implementation following RULES
+4. **Execute** requested file operations
+5. **Validate** changes
+6. **Report** file changes
+
+## Core Requirements
+
+**ALWAYS**:
+- Run `ccw spec load` FIRST to obtain project specifications before starting any work
+- Study CONTEXT files - find 3+ similar patterns before implementing
+- Apply RULES exactly
+- Test continuously (auto mode)
+- Commit incrementally (auto mode)
+- Match project style exactly
+- List all created/modified files at output beginning
+
+**NEVER**:
+- Make assumptions without code verification
+- Ignore existing patterns
+- Skip tests (auto mode)
+- Use clever tricks over boring solutions
+- Break backward compatibility
+- Exceed 3 failed attempts without stopping
+
+
+**Three-Attempt Rule**: On 3rd failure, stop and report what attempted, what failed, root cause
+
+| Error Type | Response |
+|------------|----------|
+| Syntax/Type | Review → Fix → Re-run tests |
+| Runtime | Analyze stack → Add handling → Test |
+| Test Failure | Debug → Review setup → Fix |
+| Build Failure | Check messages → Fix incrementally |
+
+---
+
+## Output Format
+
+### Format Priority
+
+**If template defines output format** → Follow template format EXACTLY
+
+**If template has no format** → Use default format below
+
+### Task Implementation
+
+```markdown
+# Implementation: [TASK Title]
+
+## Changes
+- Created: `path/to/file1.ext` (X lines)
+- Modified: `path/to/file2.ext` (+Y/-Z lines)
+- Deleted: `path/to/file3.ext`
+
+## Summary
+[2-3 sentence overview]
+
+## Key Decisions
+1. [Decision] - Rationale and reference to similar pattern
+2. [Decision] - path/to/reference:line
+
+## Implementation Details
+[Evidence-based description with code references]
+
+## Testing
+- Tests written: X new tests
+- Tests passing: Y/Z tests
+
+## Validation
+✅ Tests: X passing
+✅ Build: Success
+
+## Next Steps
+[Recommendations if any]
+```
+
+### Partial Completion
+
+```markdown
+# Task Status: Partially Completed
+
+## Completed
+- [What worked]
+- Files: `path/to/completed.ext`
+
+## Blocked
+- **Issue**: [What failed]
+- **Root Cause**: [Analysis]
+- **Attempted**: [Solutions tried - attempt X of 3]
+
+## Required
+[What's needed to proceed]
+
+## Recommendation
+[Suggested next steps]
+```
+
+### Code References
+
+**Format**: `path/to/file:line_number`
+**Example**: `src/auth/jwt.ts:45` - Implemented following pattern from `src/auth/session.ts:78`
+
+### Quality Checklist
+
+- [ ] All tests pass
+- [ ] Build succeeds
+- [ ] All EXPECTED deliverables met
+- [ ] Code follows existing patterns
+- [ ] File changes listed at beginning

package/templates/config.json

@@ -0,0 +1,53 @@
+{
+  "mode": "interactive",
+  "granularity": "standard",
+  "model_profile": "balanced",
+
+  "workflow": {
+    "research": true,
+    "plan_check": true,
+    "verify_after_execute": true,
+    "nyquist_validation": true,
+    "auto_sync": true,
+    "reflection": true,
+    "decision_protocol": true,
+    "auto_advance": false
+  },
+
+  "execution": {
+    "method": "agent",
+    "parallel": true,
+    "max_concurrent": 3,
+    "auto_commit": true,
+    "lazy_loading": true
+  },
+
+  "git": {
+    "branching": "none",
+    "commit_docs": true
+  },
+
+  "gates": {
+    "confirm_project": true,
+    "confirm_roadmap": true,
+    "confirm_plan": true,
+    "confirm_execute": true,
+    "confirm_transition": true
+  },
+
+  "safety": {
+    "always_confirm_destructive": true,
+    "always_confirm_external_services": true
+  },
+
+  "specs": {
+    "auto_setup_on_init": true,
+    "extract_learnings_on_complete": true
+  },
+
+  "codebase": {
+    "doc_index": true,
+    "auto_sync_after_execute": true,
+    "action_log": true
+  }
+}

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": []
+}