maestro-flow 0.1.0

package/workflows/execute.md

@@ -0,0 +1,413 @@
+# Execute Workflow
+
+Wave-based parallel execution with atomic commits, breakpoint resume, and optional sync/reflection.
+
+---
+
+## Prerequisites
+
+- Phase has a completed plan: `plan.json` + `.task/TASK-*.json` exist
+- `index.json` present with `plan.waves` populated
+- OR: executionContext handoff received from `/workflow:plan`
+
+---
+
+## Phase Resolution
+
+```
+Input: <phase> argument (number or slug) OR --dir <path>
+
+IF --dir <path> is provided:
+  1. Set PHASE_DIR = <path> (absolute or relative to project root)
+  2. Validate directory exists and contains index.json
+  3. Set SCRATCH_MODE = true (skip roadmap validation, phase transition)
+  4. Set PHASE_NUM = null, PHASE_SLUG = directory basename
+
+ELSE (standard phase resolution):
+  1. If number: find .workflow/phases/{NN}-*/index.json
+  2. If slug: find .workflow/phases/*-{slug}/index.json
+  3. Validate plan exists (index.json.plan.task_count > 0)
+  4. Set PHASE_DIR = resolved path
+```
+
+---
+
+## Flag Processing
+
+| Flag | Effect |
+|------|--------|
+| `--auto-commit` | Override config: commit after each task completion |
+| `--method agent\|cli` | Override execution method (default: config.json.execution.method) |
+| `--dir <path>` | Use arbitrary directory instead of phase resolution (skip roadmap validation) |
+
+---
+
+## E1: Load Plan
+
+**Purpose:** Build or receive the execution queue.
+
+### From executionContext handoff (preferred)
+
+```
+If executionContext is available in memory:
+  planObject = executionContext.planObject
+  explorations = executionContext.explorations
+  clarifications = executionContext.clarifications
+  executionMethod = executionContext.executionMethod
+  Skip disk reload
+```
+
+### From disk (fallback / resume)
+
+```
+Read ${PHASE_DIR}/index.json
+Read ${PHASE_DIR}/plan.json
+
+executionMethod = --method flag || config.json.execution.method || "agent"
+```
+
+### Detect completed tasks (breakpoint resume)
+
+```
+completed_tasks = []
+For each task_id in index.json.plan.task_ids:
+  Read .task/${task_id}.json
+  If status == "completed":
+    completed_tasks.push(task_id)
+
+If completed_tasks.length > 0:
+  Log "Resuming: {completed_tasks.length}/{total} tasks already completed"
+  Filter completed tasks out of wave execution queue
+  Set current_wave = first wave with pending tasks
+```
+
+### Build wave execution queue
+
+```
+waves = plan.json.waves (or index.json.plan.waves)
+
+execution_queue = []
+For each wave in waves:
+  pending_tasks = wave.tasks.filter(t => !completed_tasks.includes(t))
+  If pending_tasks.length > 0:
+    execution_queue.push({ wave: wave.wave, tasks: pending_tasks })
+```
+
+### Output
+- In-memory: execution_queue, executionMethod, loaded task definitions
+
+---
+
+## E1.5: Load Project Specs
+
+```
+specs_content = maestro spec load --category execution
+```
+
+Pass specs_content to each executor agent in E2.
+
+---
+
+## E2: Wave Parallel Execution
+
+**Purpose:** Execute tasks wave by wave, parallel within each wave.
+
+### Execution Loop
+
+```
+For each wave in execution_queue (sequential):
+
+  Log "=== Wave {wave.wave}: {wave.tasks.length} tasks ==="
+
+  Update index.json:
+    execution.current_wave = wave.wave
+    execution.started_at = execution.started_at || now()
+
+  # State tracking (once, on first wave entry)
+  If first_wave_entry (current_wave == execution_queue[0].wave):
+    Read .workflow/state.json
+    If state.json.status != "executing":
+      state.json.status = "executing"
+      state.json.phases_summary.in_progress += 1
+      state.json.last_updated = now()
+      Write .workflow/state.json
+
+  For each task_id in wave.tasks (parallel):
+
+    # --- Per-task execution ---
+
+    1. Load task definition
+       Read .task/${task_id}.json (lazy loading)
+
+    2. Spawn workflow-executor agent (fresh 200k context)
+       Input:
+         - Task definition (.task/${task_id}.json)
+         - Phase context (index.json goal, success_criteria)
+         - Relevant summaries from prior waves (.summaries/ of deps)
+         - Execution method override (if --method cli)
+         - Project specs (specs_content from E1.5 — coding conventions, architecture constraints, quality rules)
+        - Phase context decisions (context.md — Locked/Free/Deferred classification)
+        - Phase analysis scores (analysis.md — 6-dimension evaluation)
+
+       Agent responsibilities:
+         a. Read task definition (read_first, files, action, convergence.criteria)
+         b. Implement the task (create/modify files per task.files)
+         c. Verify convergence.criteria pass
+         d. If verification fails: auto-fix (max 3 attempts)
+         e. If auto-fix fails: write checkpoint, mark task as "blocked"
+         f. Atomic commit (if auto-commit enabled):
+            git add <task files>
+            git commit -m "{type}({slug}): {task.title}"
+         g. Write .summaries/${task_id}-summary.md
+         h. Update .task/${task_id}.json:
+            status = "completed" | "blocked"
+
+    3. Collect result
+       result = { task_id, status, summary_path, commit_hash }
+
+    # --- End per-task ---
+
+  Wait for all tasks in wave to complete
+
+  # Post-wave processing
+  For each result in wave_results:
+    Update index.json.execution:
+      tasks_completed += (completed count)
+      commits.push({ hash, task, message }) for each commit
+
+  If any task blocked:
+    Log "Wave {wave.wave}: {blocked_count} tasks blocked"
+    AskUserQuestion:
+      "Tasks blocked: {blocked_list}. Continue to next wave or stop?"
+      Options: [Continue (skip blocked), Stop and review]
+    If stop: break execution loop
+
+  Log "=== Wave {wave.wave} complete ==="
+```
+
+### Deviation Rule
+
+```
+Per task, max 3 auto-fix attempts:
+  Attempt 1: Re-read error, try alternative approach
+  Attempt 2: Simplify implementation
+  Attempt 3: Minimal viable implementation
+
+If all 3 fail:
+  Mark task as "blocked" with checkpoint data:
+    .task/${task_id}.json.meta.checkpoint = {
+      attempt: 3,
+      last_error: "...",
+      partial_files: [...]
+    }
+  Continue wave (other tasks unaffected)
+```
+
+---
+
+## E2.5: Post-Wave Validation
+
+**Purpose:** Validate execution integrity after all waves complete, before sync and reflection. Catches missing summaries, status inconsistencies, and tech stack constraint violations early.
+
+### Check 1: Summary Existence
+
+```
+For each task_id in index.json.plan.task_ids:
+  Read .task/${task_id}.json
+  If status == "completed":
+    If NOT file exists .summaries/${task_id}-summary.md:
+      violations.push({
+        type: "missing_summary",
+        severity: "warning",
+        task_id: task_id,
+        message: "Completed task ${task_id} has no summary file at .summaries/${task_id}-summary.md"
+      })
+```
+
+### Check 2: Task Status Consistency
+
+```
+For each task_id in index.json.plan.task_ids:
+  Read .task/${task_id}.json
+  task_status = task.status
+
+  # Verify completed tasks were actually in the execution results
+  If task_status == "completed":
+    If task_id NOT in wave_results (collected from E2):
+      violations.push({
+        type: "status_mismatch",
+        severity: "warning",
+        task_id: task_id,
+        message: "Task ${task_id} status is 'completed' but was not part of execution results"
+      })
+
+  # Verify tasks that ran successfully are marked completed
+  If task_id in wave_results AND wave_results[task_id].status == "completed":
+    If task_status != "completed":
+      violations.push({
+        type: "status_mismatch",
+        severity: "critical",
+        task_id: task_id,
+        message: "Task ${task_id} completed execution but .task/${task_id}.json status is '${task_status}'"
+      })
+```
+
+### Check 3: Tech Stack Constraint Compliance
+
+```
+# Load specs constraints from E1.5 specs_content (already loaded)
+tech_constraints = extract tech_stack constraints from specs_content
+  # e.g., allowed_languages, disallowed_imports, required_patterns
+
+If tech_constraints is not empty:
+  # Collect files modified during execution
+  modified_files = []
+  For each task_id in completed_tasks:
+    Read .task/${task_id}.json
+    For each file in task.files:
+      modified_files.push(file.path)
+
+  # Scan modified files for disallowed imports
+  For each file_path in modified_files:
+    If file exists ${file_path}:
+      file_content = Read ${file_path}
+      For each constraint in tech_constraints.disallowed_imports:
+        If file_content matches constraint.pattern:
+          violations.push({
+            type: "tech_stack_violation",
+            severity: "critical",
+            task_id: associated_task_id,
+            file: file_path,
+            message: "File ${file_path} contains disallowed import matching '${constraint.pattern}': ${constraint.reason}"
+          })
+```
+
+### Gate Logic
+
+```
+critical_violations = violations.filter(v => v.severity == "critical")
+warnings = violations.filter(v => v.severity == "warning")
+
+If warnings.length > 0:
+  Log "Post-wave validation: {warnings.length} warning(s)"
+  For each warning in warnings:
+    Log "  WARN: ${warning.message}"
+
+If critical_violations.length > 0:
+  Log "Post-wave validation: {critical_violations.length} critical violation(s)"
+  For each violation in critical_violations:
+    Log "  CRITICAL: ${violation.message}"
+
+  # Block execution
+  index.json.status = "blocked"
+  index.json.execution.blocked_reason = "Post-wave validation failed with critical violations"
+  index.json.execution.violations = violations
+  index.json.updated_at = now()
+  Write index.json
+
+  Abort: "Post-wave validation failed. Fix critical violations before proceeding."
+
+# No critical violations — continue to E3
+Log "Post-wave validation passed ({warnings.length} warnings, 0 critical)"
+```
+
+---
+
+## E3: Auto Sync
+
+**Purpose:** Update codebase documentation after execution.
+
+```
+If config.json.codebase.auto_sync_after_execute == true:
+  Trigger /workflow:sync logic:
+    1. Detect changed files (git diff from execution start)
+    2. Map changes to doc-index.json components/features
+    3. Update affected entries
+    4. Refresh tech-registry and feature-maps as needed
+Else:
+  Log "Auto-sync disabled. Run /workflow:sync manually if needed."
+```
+
+---
+
+## E4: Reflection (Optional)
+
+**Purpose:** Record strategy observations for future iterations.
+
+```
+If config.json.workflow.reflection == true:
+  Review execution results:
+    - Which tasks completed smoothly?
+    - Which required auto-fix attempts?
+    - Any blocked tasks?
+    - Patterns observed?
+
+  Append to ${PHASE_DIR}/reflection-log.md:
+    ## Reflection - Wave Execution {timestamp}
+    - Strategy adjustments: [...]
+    - Patterns noted: [...]
+    - Blocked tasks: [...]
+
+  Update index.json.reflection:
+    rounds += 1
+    strategy_adjustments.push(new adjustments)
+```
+
+---
+
+## Final State Update
+
+```
+all_completed = index.json.execution.tasks_completed == index.json.execution.tasks_total
+
+If all_completed:
+  index.json.status = "verifying"  (ready for /workflow:verify)
+  index.json.execution.completed_at = now()
+  Log "All tasks completed. Run /workflow:verify to validate results."
+Else:
+  index.json.status = "executing"  (partial, can resume)
+  Log "{completed}/{total} tasks completed. Re-run /workflow:execute to resume."
+
+index.json.updated_at = now()
+
+# Update project state.json (skip in SCRATCH_MODE)
+If NOT SCRATCH_MODE:
+  Read .workflow/state.json
+  If all_completed:
+    state.json.status = "verifying"
+  state.json.last_updated = now()
+  Write .workflow/state.json
+```
+
+---
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| Phase directory not found | Abort: "Phase {phase} not found." |
+| No plan exists | Abort: "No plan found. Run /workflow:plan first." |
+| Task file missing | Skip task, log error, continue wave |
+| Agent spawn fails | Retry once, then mark task as "blocked" |
+| Git commit fails | Log warning, continue (task still marked completed) |
+| All tasks in wave blocked | Stop execution, report blocked wave |
+
+---
+
+## Breakpoint Resume
+
+The execute workflow is fully resumable:
+
+```
+State tracking in index.json.execution:
+  tasks_completed: N     # Count of finished tasks
+  current_wave: W        # Last active wave
+  commits: [...]         # All commits made
+
+Re-running /workflow:execute <phase>:
+  1. Reads index.json.execution.tasks_completed
+  2. Checks each .task/TASK-*.json status
+  3. Builds queue of remaining tasks
+  4. Continues from next pending wave
+  5. No duplicate execution of completed tasks
+```

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-spec-generate or maestro-roadmap.
+
+---
+
+## Step 1: State Detection
+
+Detect current project state to determine initialization path.
+
+```
+CHECK .workflow/state.json exists?
+  YES → Path C (existing project)
+  NO  → CHECK if directory has source code files (*.ts, *.js, *.py, *.java, *.go, etc.)
+    YES → Path B (brownfield)
+    NO  → 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 enough context for project.md, 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-brainstorm SESSION-ID`:
+   - Locate brainstorm session directory (`.workflow/scratch/brainstorm-*/` or `.workflow/phases/*/`)
+   - Read `guidance-specification.md`:
+     - Problem statement → project vision + core value
+     - Features → project goals (Active requirements)
+     - Non-goals → constraints + Out of Scope requirements
+     - Terminology → project glossary context
+   - Skip interactive questioning (context already gathered)
+
+2. **Workflow Preferences** -- Configure project workflow settings:
+
+   Round 1 — Core settings (AskUserQuestion):
+   - Granularity: Coarse (3-5 phases) / Standard (5-8) / Fine (8-12)
+   - Execution: Parallel / Sequential
+   - Git Tracking: Commit planning docs to git?
+
+   Round 2 — Workflow agents:
+   - Research: Research before planning each phase?
+   - Plan Check: Verify plans achieve goals?
+   - Verifier: Verify work after each phase?
+
+   Write `.workflow/config.json` from template + user selections.
+   If `--auto`: use defaults (standard, parallel, commit, all agents on).
+
+3. **Research** (optional, based on config.workflow.research) -- Spawn 4 parallel `workflow-project-researcher` agents:
+   ```
+   Agent 1: Stack      → .workflow/research/STACK.md (standard tech stack for domain)
+   Agent 2: Features   → .workflow/research/FEATURES.md (table stakes vs differentiators)
+   Agent 3: Arch       → .workflow/research/ARCHITECTURE.md (component boundaries, data flow)
+   Agent 4: Pitfalls   → .workflow/research/PITFALLS.md (common mistakes, prevention)
+   ```
+   Each agent writes directly to `.workflow/research/` -- orchestrator receives confirmation only.
+
+4. **Synthesize** -- 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", current_phase: null)
+   - `.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 `/spec-map` 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-brainstorm SESSION-ID`: extract from guidance-specification.md (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 Setup (first-run only)
+
+If `.workflow/specs/` does not exist:
+
+1. Create `.workflow/specs/` directory
+2. Auto-trigger `/workflow:specs-setup` — **MUST follow `specs-setup.md` templates exactly**:
+   - Scan codebase for conventions
+   - Generate `project-tech.json`
+   - Generate `specs/coding-conventions.md`
+   - Generate `specs/architecture-constraints.md`
+   - Generate `specs/quality-rules.md`
+   - Generate `specs/debug-notes.md`
+   - Generate `specs/test-conventions.md`
+   - Generate `specs/review-standards.md`
+   - Generate `specs/validation-rules.md`
+   - Create empty `specs/learnings.md`
+
+
+---
+
+## Step 3: Directory Structure Verification
+
+Verify all required directories and files exist:
+
+```
+.workflow/
+  project.md        ✓
+  state.json         ✓
+  config.json        ✓
+  specs/             ✓
+  research/          ✓ (if research enabled)
+  phases/            ✓ (create empty)
+  scratch/           ✓ (create empty)
+  milestones/        ✓ (create empty)
+  codebase/          ✓ (create empty)
+  task-specs/        ✓ (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 (mode, granularity, execution method, enabled agents)
+   - Research summary (if research was run)
+3. Route next steps:
+   - "Run `/maestro-spec-generate` 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"