make-it-done 0.1.0

package/makeitdone/workflows/execute.md

@@ -0,0 +1,218 @@
+# Execute Phase Workflow
+
+Wave-based phase execution with parallelization and per-task verification.
+
+**Token budget**: ~12K per wave (includes executor + verifier spawns)
+
+---
+
+## Context Setup
+
+@/Users/ismailalam/Development/my/makeitdone/makeitdone/steps/init-gate.md
+@/Users/ismailalam/Development/my/makeitdone/makeitdone/steps/state-read.md
+@/Users/ismailalam/Development/my/makeitdone/makeitdone/steps/model-route.md
+@/Users/ismailalam/Development/my/makeitdone/makeitdone/steps/agent-contracts.md
+@/Users/ismailalam/Development/my/makeitdone/makeitdone/steps/anti-patterns.md
+
+---
+
+## Initialization
+
+### 1. Get Phase Context
+
+```bash
+PHASE=${phase_arg}
+PHASE_DIR=".planning/phases/$(printf '%02d' $PHASE)-*"
+
+if [ ! -d "$PHASE_DIR" ]; then
+  error "Phase $PHASE not found"
+fi
+
+if [ ! -f "$PHASE_DIR/PLAN.md" ]; then
+  error "PLAN.md not found for phase $PHASE"
+fi
+```
+
+### 2. Load Execution Payload
+
+```bash
+PAYLOAD=$(node ~/.claude/makeitdone/bin/mid-tools.cjs init execute $PHASE)
+
+# Parse TOON payload
+BRANCH_NAME=$(echo "$PAYLOAD" | grep "branch_name" | cut -d: -f2 | tr -d ' ')
+EXECUTOR_MODEL=$(echo "$PAYLOAD" | grep "executor_model" | cut -d: -f2 | tr -d ' ')
+EXECUTOR=$(echo "$PAYLOAD" | grep "parallelization" | grep -q "true" && echo "parallel" || echo "serial")
+```
+
+### 3. Check State
+
+```bash
+STATE=$(mid-tools state get)
+
+CURRENT_WAVE=$(echo "$STATE" | grep "current_wave" | cut -d: -f2)
+CURRENT_PHASE=$(echo "$STATE" | grep "phase" | cut -d: -f2)
+
+if [ "$CURRENT_PHASE" != "$PHASE" ]; then
+  warn "Phase mismatch: state says $CURRENT_PHASE, executing $PHASE"
+  mid-tools state set phase $PHASE
+fi
+```
+
+---
+
+## Wave Execution Loop
+
+### 1. Extract Wave Tasks
+
+```bash
+WAVE=$CURRENT_WAVE
+
+# Parse PLAN.md for Wave N tasks
+TASKS=$(grep -A 200 "^## Wave $WAVE" "$PHASE_DIR/PLAN.md" | \
+        grep "^### [0-9]" | \
+        sed 's/### //' | \
+        cut -d' ' -f1-2)
+```
+
+### 2. Update STATE (Wave Start)
+
+```bash
+mid-tools state set current_wave $WAVE
+mid-tools state set wave_${WAVE}_start $(date -u +%s)
+```
+
+### 3. Spawn Executor
+
+```bash
+EXECUTOR_OUTPUT=$(spawn agent \
+  name=mid-executor \
+  model=$EXECUTOR_MODEL \
+  context=$(cat << EOF
+phase: $PHASE
+wave: $WAVE
+tasks: $TASKS
+phase_dir: $PHASE_DIR
+branch: $BRANCH_NAME
+mode: execute
+parallelization: $EXECUTOR
+EOF
+))
+```
+
+### 4. Parse Completion Marker
+
+```bash
+if [[ $EXECUTOR_OUTPUT == *"## WAVE COMPLETE"* ]]; then
+  handle_wave_complete
+elif [[ $EXECUTOR_OUTPUT == *"## BLOCKED"* ]]; then
+  handle_blocked
+elif [[ $EXECUTOR_OUTPUT == *"## FAILED"* ]]; then
+  handle_failed
+else
+  error "Unexpected executor output, no completion marker"
+fi
+```
+
+### 5. Wave Complete Actions
+
+```bash
+mid-tools state set wave_${WAVE}_complete true
+mid-tools state set wave_${WAVE}_end $(date -u +%s)
+
+# Check if more waves
+NEXT_WAVE=$((WAVE + 1))
+
+if grep -q "^## Wave $NEXT_WAVE" "$PHASE_DIR/PLAN.md"; then
+  # More waves exist
+  mid-tools state set current_wave $NEXT_WAVE
+  
+  echo "Wave $WAVE complete. Ready for Wave $NEXT_WAVE."
+  echo "Run: /mid:do $PHASE --wave $NEXT_WAVE"
+  
+  output_marker "## WAVE COMPLETE"
+else
+  # No more waves - phase complete
+  spawn mid-verifier mode=integration phase=$PHASE
+  
+  # After verification passes
+  mid-tools state advance $PHASE
+  
+  output_marker "## PHASE EXECUTION COMPLETE"
+fi
+```
+
+---
+
+## Error Handling
+
+### Blocked by User Decision
+
+```bash
+if [[ $EXECUTOR_OUTPUT == *"## BLOCKED"* ]]; then
+  # Extract blocker details
+  BLOCKER=$(echo "$EXECUTOR_OUTPUT" | grep -A 5 "BLOCKED")
+  
+  echo "$BLOCKER"
+  
+  ask_user "How should we proceed?"
+  - "Skip this task and continue"
+  - "Retry task"
+  - "Stop and escalate"
+  
+  if [ $user_choice = "Skip" ]; then
+    mark_task_skipped $task_id
+    continue_wave
+  fi
+fi
+```
+
+### Task Failure
+
+```bash
+if [[ $EXECUTOR_OUTPUT == *"## FAILED"* ]]; then
+  spawn mid-debugger with executor_output
+  
+  # Wait for debug report
+  
+  ask_user "Debugging complete. Options:"
+  - "Apply suggested fix and retry"
+  - "Skip task"
+  - "Stop phase execution"
+fi
+```
+
+### Context Exhaustion
+
+```bash
+if [ "$context_window" -lt 300000 ]; then
+  error "Context too low for continuation"
+  output "Current state saved in .planning/STATE.md"
+  output "Resume later: /mid:do $PHASE --wave $WAVE"
+fi
+```
+
+---
+
+## Per-Wave Verification (Optional)
+
+If `--verify` flag:
+
+```bash
+after_wave_complete:
+  spawn mid-verifier \
+    mode=integration \
+    phase=$PHASE \
+    wave=$WAVE \
+    tasks=$COMPLETED_TASKS
+```
+
+---
+
+## Anti-patterns Avoided
+
+✓ Fresh init payload per wave (not cached)
+✓ Exact completion marker checking
+✓ Atomic state updates via mid-tools
+✓ Spawn verifier only as quality gate
+✓ Escalate on failure (don't continue blindly)
+✓ Fast-fail on context < 300k

package/makeitdone/workflows/init.md

@@ -0,0 +1,113 @@
+# Initialize makeitdone Project
+
+Token optimized initialization workflow for new projects.
+
+**Token budget**: ~8K (init-gate + questions + template copy)
+
+---
+
+## Context Setup
+
+@/Users/ismailalam/Development/my/makeitdone/makeitdone/steps/init-gate.md
+@/Users/ismailalam/Development/my/makeitdone/makeitdone/steps/anti-patterns.md
+
+---
+
+## Execution
+
+### 1. Project Metadata Collection
+
+Ask user 5 critical questions:
+
+- Project name: ?
+- Description (one-liner): ?
+- Team size (1-5+ people): ?
+- Timeline estimate (weeks): ?
+- Tech stack (framework/lang): ?
+
+Store in memory for next session.
+
+### 2. Create .planning Directory
+
+```bash
+mkdir -p .planning/phases/{01,02,03}
+touch .planning/config.json
+```
+
+### 3. Initialize Templates
+
+Copy templates to project:
+
+```bash
+cp ~/.claude/makeitdone/templates/project.md .planning/PROJECT.md
+cp ~/.claude/makeitdone/templates/requirements.md .planning/REQUIREMENTS.md
+cp ~/.claude/makeitdone/templates/roadmap.md .planning/ROADMAP.md
+cp ~/.claude/makeitdone/templates/state.md .planning/STATE.md
+```
+
+### 4. Populate Config
+
+```json
+{
+  "project_name": "[user input]",
+  "description": "[user input]",
+  "model_profile": "balanced",
+  "context_window": 200000,
+  "team_size": [user input],
+  "created": "2026-04-05"
+}
+```
+
+### 5. Update PROJECT.md
+
+Populate with user answers:
+- Name, description (frontmatter)
+- Goals section (auto-generate 3 generic + ask user for specific)
+- Scope, constraints, timeline
+- Tech stack
+
+### 6. First Roadmap Question
+
+Ask: "How many phases do you estimate? (2-5)"
+
+Create ROADMAP.md structure with user's phase count.
+
+### 7. Success Checkpoint
+
+```bash
+# Verify structure
+test -f .planning/PROJECT.md && echo "✅ PROJECT.md"
+test -f .planning/REQUIREMENTS.md && echo "✅ REQUIREMENTS.md"
+test -f .planning/ROADMAP.md && echo "✅ ROADMAP.md"
+test -f .planning/STATE.md && echo "✅ STATE.md"
+test -f .planning/config.json && echo "✅ config.json"
+```
+
+Output completion marker:
+
+```
+## PROJECT INITIALIZED
+
+Name: [project name]
+Location: .planning/
+Files: 5 created
+
+Next step: Run /mid:plan --mode roadmap to detail your phases
+```
+
+---
+
+## Error Handling
+
+- **Missing input**: Re-ask question
+- **.planning already exists**: Skip creation, verify files
+- **Invalid JSON**: Use defaults, warn user
+
+---
+
+## Anti-patterns Avoided
+
+✓ Frontmatter-first (no full-file reads needed)
+✓ No agents spawned (user-facing interview only)
+✓ Templates via copy, not text generation
+✓ Fast-fail on directory issues (escalate to user)

package/makeitdone/workflows/next.md

@@ -0,0 +1,114 @@
+# Next Phase Workflow
+
+Move to next phase after current phase verification passes.
+
+**Token budget**: ~6K (state reads + verification spawn)
+
+---
+
+## Context Setup
+
+@/Users/ismailalam/Development/my/makeitdone/makeitdone/steps/state-read.md
+
+---
+
+## Execution
+
+### 1. Check Current Phase State
+
+```bash
+STATE=$(mid-tools state get)
+CURRENT_PHASE=$(echo "$STATE" | grep "^phase:" | cut -d: -f2 | tr -d ' ')
+PHASE_COMPLETE=$(echo "$STATE" | grep "phase_complete:" | cut -d: -f2 | tr -d ' ')
+
+if [ "$PHASE_COMPLETE" != "true" ]; then
+  error "Phase $CURRENT_PHASE not marked complete"
+  output "Run /mid:verify --mode audit --phase $CURRENT_PHASE first"
+fi
+```
+
+### 2. Verify All Waves Complete
+
+```bash
+PHASE_DIR=".planning/phases/$(printf '%02d' $CURRENT_PHASE)-*"
+
+# Extract max wave number from PLAN.md
+MAX_WAVE=$(grep "^## Wave" "$PHASE_DIR/PLAN.md" | tail -1 | grep -o "[0-9]")
+
+for wave in $(seq 1 $MAX_WAVE); do
+  WAVE_COMPLETE=$(echo "$STATE" | grep "wave_${wave}_complete" | cut -d: -f2)
+  if [ "$WAVE_COMPLETE" != "true" ]; then
+    error "Wave $wave not complete"
+  fi
+done
+```
+
+### 3. Calculate Next Phase
+
+```bash
+NEXT_PHASE=$((CURRENT_PHASE + 1))
+
+# Check if next phase exists in roadmap
+if ! grep -q "^## $(printf '%02d' $NEXT_PHASE)" .planning/ROADMAP.md; then
+  output "All phases complete! Project done."
+  output "Final report: /mid:report"
+  exit 0
+fi
+```
+
+### 4. Update State
+
+```bash
+mid-tools state set phase $NEXT_PHASE
+mid-tools state set current_wave 1
+mid-tools state set phase_start_time $(date -u +%s)
+
+# Clear wave tracking for new phase
+for wave in 1 2 3 4 5; do
+  mid-tools state set wave_${wave}_complete false || true
+done
+```
+
+### 5. Create PLAN.md Stub for Next Phase
+
+If PLAN.md doesn't exist for next phase:
+
+```bash
+NEXT_DIR=".planning/phases/$(printf '%02d' $NEXT_PHASE)-*"
+
+if [ ! -f "$NEXT_DIR/PLAN.md" ]; then
+  cp ~/.claude/makeitdone/templates/plan.md "$NEXT_DIR/PLAN.md"
+  output "Created PLAN.md stub for Phase $NEXT_PHASE"
+  output "Next: /mid:plan --mode phase --phase $NEXT_PHASE"
+fi
+```
+
+### 6. Success Output
+
+```
+## PHASE TRANSITION COMPLETE
+
+Previous phase: $CURRENT_PHASE ✅
+Current phase: $NEXT_PHASE (ready)
+
+Status: Waiting for /mid:plan --mode phase --phase $NEXT_PHASE
+
+To start execution: /mid:do $NEXT_PHASE
+```
+
+---
+
+## Error Handling
+
+- **Current phase not marked complete**: Fail, guide to `/mid:verify`
+- **Waves not complete**: Fail, guide to `/mid:do`
+- **No next phase in roadmap**: Success, output final report option
+- **PLAN.md creation fails**: Warn, ask user to create manually
+
+---
+
+## Anti-patterns Avoided
+
+✓ Fast-fail on state inconsistency
+✓ Atomic state updates (no partial updates)
+✓ Clear next steps for user

package/makeitdone/workflows/plan.md

@@ -0,0 +1,231 @@
+# Plan Phase Workflow
+
+Create or update project plans with token-optimized research gate.
+
+**Token budget**: ~10K (depends on research flag; lazy-loaded)
+
+---
+
+## Context Setup
+
+@/Users/ismailalam/Development/my/makeitdone/makeitdone/steps/init-gate.md
+@/Users/ismailalam/Development/my/makeitdone/makeitdone/steps/state-read.md
+@/Users/ismailalam/Development/my/makeitdone/makeitdone/steps/model-route.md
+@/Users/ismailalam/Development/my/makeitdone/makeitdone/steps/context-budget.md
+
+---
+
+## Modes
+
+- `--mode roadmap` — create ROADMAP.md from PROJECT.md + REQUIREMENTS.md
+- `--mode phase --phase N` — create PLAN.md for specific phase
+- `--mode gap --phase N` — identify missing requirements, create gap plan
+- `--mode check --phase N` — validate plan against requirements
+
+---
+
+## Execution (Roadmap Mode)
+
+### 1. Check Context
+
+```bash
+context_window=$(mid-tools config get context_window)
+
+if [ "$context_window" -lt 300000 ]; then
+  error "Context too low for roadmap planning (need > 300k)"
+fi
+```
+
+### 2. Research Gate
+
+```bash
+if [ "$research_required" = true ] || [ "$RESEARCH_FLAG" = true ]; then
+  spawn mid-researcher mode=project
+else:
+  skip research
+fi
+```
+
+### 3. Spawn Planner (Roadmap)
+
+```bash
+spawn mid-planner \
+  mode=roadmap \
+  context=$(cat .planning/PROJECT.md | head -50) \
+  requirements=$(mid-tools fm get .planning/REQUIREMENTS.md)
+```
+
+**mid-planner contract**: Must output `## ROADMAP CREATED` when complete.
+
+### 4. Verify Output
+
+```bash
+if [ -f .planning/ROADMAP.md ] && grep -q "^## [0-9]" .planning/ROADMAP.md; then
+  success "ROADMAP.md created"
+else
+  error "ROADMAP.md not created or invalid format"
+fi
+```
+
+### 5. Update STATE.md
+
+```bash
+mid-tools state set current_phase 1
+mid-tools state set status planning_complete
+```
+
+Output completion marker:
+
+```
+## PHASE PLAN CREATED
+
+File: .planning/ROADMAP.md
+Phases: 3
+Status: Ready for phase-level planning
+
+Next: Run /mid:plan --mode phase --phase 1
+```
+
+---
+
+## Execution (Phase Mode)
+
+### 1. Load Phase Context
+
+```bash
+PHASE=${phase_arg}
+PHASE_DIR=".planning/phases/$(printf '%02d' $PHASE)-*"
+
+if [ ! -d "$PHASE_DIR" ]; then
+  error "Phase $PHASE directory not found"
+fi
+```
+
+### 2. Research Gate
+
+Only if `--research` flag:
+
+```bash
+if [ "$RESEARCH_FLAG" = true ]; then
+  spawn mid-researcher mode=phase phase=$PHASE
+else
+  skip
+fi
+```
+
+### 3. Spawn Planner (Phase)
+
+```bash
+spawn mid-planner \
+  mode=phase \
+  phase=$PHASE \
+  requirements=$(mid-tools fm get .planning/REQUIREMENTS.md) \
+  phase_context=$(mid-tools fm get "$PHASE_DIR/PLAN.md" 2>/dev/null || echo "")
+```
+
+**Expectation**: Output `## PHASE PLAN CREATED` + PLAN.md file.
+
+### 4. Validate Plan Size
+
+```bash
+LINES=$(wc -l < "$PHASE_DIR/PLAN.md")
+if [ "$LINES" -gt 150 ]; then
+  warn "PLAN.md exceeds 150 lines ($LINES), may need splitting"
+fi
+```
+
+### 5. Update STATE
+
+```bash
+mid-tools state set current_phase $PHASE
+TASKS=$(grep -c "^### [0-9]" "$PHASE_DIR/PLAN.md")
+mid-tools state set phase_${PHASE}_tasks $TASKS
+```
+
+Output:
+
+```
+## PHASE PLAN CREATED
+
+Phase: $PHASE
+Tasks: $TASKS (N waves)
+File: .planning/phases/NN-name/PLAN.md
+
+Next: Run /mid:do $PHASE to execute
+```
+
+---
+
+## Execution (Gap Mode)
+
+### 1. Load PLAN.md
+
+```bash
+if [ ! -f "$PHASE_DIR/PLAN.md" ]; then
+  error "PLAN.md not found for phase $PHASE"
+fi
+```
+
+### 2. Spawn Planner (Gap)
+
+```bash
+spawn mid-planner \
+  mode=gap \
+  phase=$PHASE \
+  plan=$(cat "$PHASE_DIR/PLAN.md") \
+  requirements=$(cat .planning/REQUIREMENTS.md)
+```
+
+### 3. Handle Output
+
+Creates gap-closure plan file(s): `$PHASE_DIR/gap-plan-N.md`
+
+Output:
+
+```
+## GAP PLANS CREATED
+
+Gaps found: N
+Plans: gap-plan-1.md, gap-plan-2.md
+
+Next: Review gaps, then /mid:do $PHASE --include-gaps
+```
+
+---
+
+## Execution (Check Mode)
+
+### 1. Spawn Planner (Check)
+
+```bash
+spawn mid-planner \
+  mode=check \
+  phase=$PHASE \
+  plan=$(cat "$PHASE_DIR/PLAN.md")
+```
+
+### 2. Parse Result
+
+If contains `## PLAN VALIDATION PASSED`:
+- Success, continue
+If contains `## PLAN VALIDATION FAILED`:
+- Show issues, escalate to user
+
+---
+
+## Error Handling
+
+- **Phase not found**: Create phase directory, ask user for phase name
+- **PLAN.md invalid format**: Show format error, offer template
+- **Research timeout**: Partial research OK, continue with findings
+- **Planner blocked**: Escalate findings to user
+
+---
+
+## Anti-patterns Avoided
+
+✓ Lazy research gate (only spawn if flagged)
+✓ Frontmatter reads for context (no full files)
+✓ Path-based delegation to agents
+✓ Exact completion markers for verification
+✓ Context guard for roadmap mode (> 300k required)