make-it-done 0.1.0

package/makeitdone/steps/agent-contracts.md

@@ -0,0 +1,184 @@
+# Agent Completion Contracts
+
+Strict contract definitions. Workflows MUST check for these exact markers.
+
+## mid-executor
+
+**Completion Markers:**
+```
+## WAVE COMPLETE
+## PHASE EXECUTION FAILED
+## BLOCKED - USER INPUT NEEDED
+## ALL WAVES COMPLETE
+```
+
+**Contract:**
+- Executes one complete wave (all tasks in wave)
+- Updates STATE.md via mid-tools after each task
+- Spawns mid-verifier for per-task validation
+- Returns exact completion marker + blockers list
+- Never continues if task fails (unless --skip-failed flag)
+
+**Output Format:**
+```
+## WAVE COMPLETE
+
+Completed tasks: 3/3
+Wave runtime: 12m
+State updated: wave_1_complete = true
+
+Next: Run mid:do 1 --wave 2
+```
+
+---
+
+## mid-planner
+
+**Completion Markers:**
+```
+## ROADMAP CREATED
+## PHASE PLAN CREATED
+## GAP PLANS CREATED
+## PLAN VALIDATION PASSED
+## PLAN VALIDATION FAILED
+```
+
+**Contract:**
+- Creates file(s) in .planning/ directory
+- Respects size limits (PLAN.md < 150 lines)
+- Returns completion marker + file path(s)
+- Includes acceptance criteria in plan
+- Validates against previous phase (dependencies)
+
+**Output Format:**
+```
+## PHASE PLAN CREATED
+
+File: .planning/phases/01-foundation/PLAN.md
+Tasks: 5 (1 wave)
+Estimated: 6-8 hours
+Acceptance: 8 criteria
+
+Next: Review with /mid:plan --mode check --phase 1
+```
+
+---
+
+## mid-researcher
+
+**Completion Markers:**
+```
+## RESEARCH COMPLETE
+## RESEARCH PARTIAL (context limit)
+## RESEARCH FAILED
+```
+
+**Contract:**
+- Creates research.md in phase directory
+- Respects context_window limits
+- Returns marker + summary (20-50 lines max)
+- Partial research includes "(PARTIAL)" in marker and lists stopped-at section
+- Failed research includes error reason
+
+**Output Format:**
+```
+## RESEARCH COMPLETE
+
+File: .planning/phases/01-foundation/research.md
+Coverage: 8 areas
+Lines: 45/150
+
+Key findings:
+- [fact 1]
+- [fact 2]
+```
+
+---
+
+## mid-verifier
+
+**Completion Markers:**
+```
+## VERIFICATION PASSED
+## VERIFICATION FAILED - <reason>
+## VERIFICATION INCOMPLETE
+```
+
+**Contract:**
+- Checks against ACCEPTANCE.md criteria
+- Returns marker + pass/fail per criterion
+- Fast-fails on critical blockers
+- Returns blockers list with remediation steps
+- Never modifies code (read-only)
+
+**Output Format:**
+```
+## VERIFICATION PASSED
+
+Criteria passed: 8/8
+Coverage: 100%
+Duration: 2m
+
+Status: Phase 1 ready for /mid:next
+```
+
+---
+
+## mid-debugger
+
+**Completion Markers:**
+```
+## DEBUG COMPLETE - <action>
+## ROOT CAUSE: <identified issue>
+## ESCALATION NEEDED - <reason>
+```
+
+**Contract:**
+- Identifies root cause of error/blocker
+- Returns diagnostic report (20-40 lines max)
+- Suggests specific fix or escalation path
+- Never attempts to fix (only diagnose)
+- Respects ~5 min time budget
+
+**Output Format:**
+```
+## ROOT CAUSE: Missing environment variable
+
+Error: TypeError: Cannot read property 'apiKey' of undefined
+File: src/api/client.ts:23
+
+Finding: process.env.API_KEY not loaded from .env
+
+Action: Add API_KEY to .env.example, load in config.ts
+
+Next: Run /mid:do 1 --rerun-task 3-2
+```
+
+---
+
+## Verification Pattern (in Workflows)
+
+Always check for completion marker:
+
+```bash
+# Spawn agent
+AGENT_OUTPUT=$(... spawn mid-executor ...)
+
+# Parse completion marker
+if [[ $AGENT_OUTPUT == *"## WAVE COMPLETE"* ]]; then
+  handle_wave_complete
+elif [[ $AGENT_OUTPUT == *"## BLOCKED"* ]]; then
+  handle_blocked
+elif [[ $AGENT_OUTPUT == *"## FAILED"* ]]; then
+  handle_failed
+else
+  error "Unexpected output, no completion marker"
+fi
+```
+
+## Anti-patterns
+
+- Checking for partial strings ("complete" instead of "## WAVE COMPLETE")
+- Ignoring "FAILED" markers (must escalate)
+- Assuming marker presence without verification (use explicit check)
+- Parsing agent output besides marker (markers are contract boundary)

package/makeitdone/steps/anti-patterns.md

@@ -0,0 +1,291 @@
+# Universal Anti-patterns
+
+Patterns to avoid across all workflows and agents.
+
+## Reading & Context
+
+### ❌ Full File Reads When Frontmatter Suffices
+
+```bash
+# BAD: loads 5K tokens
+STATE=$(cat .planning/STATE.md)
+
+# GOOD: loads 200 tokens (frontmatter only)
+STATE_FM=$(mid-tools fm get .planning/STATE.md)
+```
+
+**Rule**: If context_window < 500k, always use frontmatter-only reads.
+
+---
+
+### ❌ Loading All Phases at Once
+
+```bash
+# BAD: loads 50K tokens
+ALL_PHASES=$(find .planning/phases -name "PLAN.md" -exec cat {} \;)
+
+# GOOD: load only active phase
+PHASE_PLAN=$(cat .planning/phases/01-foundation/PLAN.md)
+```
+
+**Rule**: Query by phase number, never enumerate all phases.
+
+---
+
+### ❌ Importing All Step Fragments
+
+```bash
+# BAD: monolithic
+@makeitdone/steps/*.md
+
+# GOOD: surgical inclusion
+@makeitdone/steps/init-gate.md
+@makeitdone/steps/model-route.md
+```
+
+**Rule**: Only @include steps actually used in workflow.
+
+---
+
+## Agent Spawning
+
+### ❌ Spawning Multiple Agents Per Wave
+
+```bash
+# BAD: context overload
+spawn mid-planner
+spawn mid-researcher
+spawn mid-verifier
+(all in same wave)
+
+# GOOD: sequential necessity
+spawn mid-executor (wave 1)
+-> spawn mid-verifier (per-task)
+-> next wave
+```
+
+**Rule**: Max 1 primary agent per wave. Spawn verifier only as quality gate.
+
+---
+
+### ❌ Passing File Contents to Agents
+
+```bash
+# BAD: bloats context
+PLAN_CONTENT=$(cat .planning/phases/01/PLAN.md)
+spawn mid-executor with "${PLAN_CONTENT}"
+
+# GOOD: path-based delegation
+spawn mid-executor with phase_dir=".planning/phases/01"
+```
+
+**Rule**: Pass file paths, let agents read. Exceptions: frontmatter extracts (< 500 tokens).
+
+---
+
+### ❌ Lazy Agents Without Guards
+
+```bash
+# BAD: always spawns
+spawn mid-researcher
+
+# GOOD: conditional
+if [ "$research_required" = true ] || [ "$RESEARCH_FLAG" = true ]; then
+  spawn mid-researcher
+fi
+```
+
+**Rule**: Researchers are lazy-loaded. Check flags first.
+
+---
+
+## State Management
+
+### ❌ Direct STATE.md Writes
+
+```bash
+# BAD: inconsistent, whitespace bloat
+echo "phase: 2" >> .planning/STATE.md
+
+# GOOD: atomic via mid-tools
+mid-tools state set phase 2
+mid-tools state advance 2
+```
+
+**Rule**: Never write STATE.md directly. Always use mid-tools CLI.
+
+---
+
+### ❌ Parsing STATE.md Manually
+
+```bash
+# BAD: brittle, breaks on format changes
+PHASE=$(grep "^phase:" .planning/STATE.md | cut -d: -f2)
+
+# GOOD: structured extraction
+PHASE=$(mid-tools fm get .planning/STATE.md --field phase)
+```
+
+**Rule**: Use mid-tools for all state reads.
+
+---
+
+## Data Formats
+
+### ❌ JSON in Context
+
+```bash
+# BAD: 40% more tokens
+echo '{"phase":1,"tasks":["a","b"]}'
+
+# GOOD: TOON compression
+mid-tools toon <(echo '{"phase":1,"tasks":["a","b"]}')
+```
+
+**Rule**: All JSON payloads → TOON conversion. Output TOON, not JSON.
+
+---
+
+### ❌ Verbose Task Descriptions
+
+```markdown
+# BAD: 20 lines per task
+### 01-01 Implement Auth Module
+This task involves building an authentication system using JWT tokens.
+We need to support login, logout, token refresh, and logout-all operations.
+The implementation should use industry best practices including:
+- Secure token storage
+- HTTPS-only cookies
+- Rate limiting
+...
+
+# GOOD: 5 lines per task
+### 01-01 Implement JWT auth (login, refresh, logout)
+User stories: US-001, US-002
+Tests: auth.test.ts
+Acceptance: login works, tokens refreshed, logout clears
+```
+
+**Rule**: PLAN.md max 150 lines. Tasks max 10-12 lines each.
+
+---
+
+## Error Handling
+
+### ❌ Silent Failures
+
+```bash
+# BAD: fails silently
+node ~/.claude/makeitdone/bin/mid-tools.cjs state set phase 2 || true
+
+# GOOD: explicit error handling
+if ! node ~/.claude/makeitdone/bin/mid-tools.cjs state set phase 2; then
+  error "Failed to advance phase"
+  escalate_to_user
+fi
+```
+
+**Rule**: All critical operations must check exit codes and escalate on failure.
+
+---
+
+### ❌ Ignoring Context Exhaustion
+
+```bash
+# BAD: crashes when context < 500k
+STATE=$(cat .planning/STATE.md)  # fails silently
+
+# GOOD: context-aware fallback
+if [ "$context_window" -lt 500000 ]; then
+  STATE=$(mid-tools fm get .planning/STATE.md)
+else
+  STATE=$(cat .planning/STATE.md)
+fi
+```
+
+**Rule**: Always check context_window and degrade gracefully.
+
+---
+
+## Workflow Structure
+
+### ❌ Monolithic Workflows
+
+```markdown
+# BAD: one 50KB workflow
+## Init Gate
+## Model Routing
+## Executor Spawn
+## Verification
+## State Update
+## Report Generation
+...all in one file
+```
+
+**Rule**: One workflow = one responsibility. Max 10-15KB per file.
+
+---
+
+### ❌ Unclear Completion Markers
+
+```markdown
+# BAD: multiple possible outputs
+"execution done"
+"all tasks complete"
+"FINISHED"
+"ready for next"
+```
+
+**Rule**: Exact markers only. See agent-contracts.md.
+
+---
+
+## Performance
+
+### ❌ N+1 Grep Queries
+
+```bash
+# BAD: 10 separate greps
+grep "pattern1" .
+grep "pattern2" .
+grep "pattern3" .
+...
+
+# GOOD: single batched grep
+grep "pattern1|pattern2|pattern3" .
+```
+
+**Rule**: Batch patterns when possible. Grep is ~100 tokens, accumulates fast.
+
+---
+
+### ❌ Polling Loops
+
+```bash
+# BAD: spins waiting
+while [ ! -f .planning/STATE.md ]; do
+  sleep 1
+done
+
+# GOOD: immediate check or delegation
+if [ ! -f .planning/STATE.md ]; then
+  error "STATE.md not found"
+fi
+```
+
+**Rule**: No sleep loops. Check once, escalate if needed.
+
+---
+
+## Summary
+
+**Golden Rules:**
+
+1. **Frontmatter-first** when context < 500k
+2. **Path-based** delegation to agents
+3. **mid-tools** for all state operations
+4. **TOON** for all JSON output
+5. **Selective @include** for steps
+6. **Exact markers** for agent completion
+7. **Context guard** every workflow
+8. **Fast-fail** on errors (escalate immediately)

package/makeitdone/steps/context-budget.md

@@ -0,0 +1,157 @@
+# Context Budget Guidelines
+
+Structural guidelines for all workflows to stay within token budget.
+
+## Per-File Limits (hard constraints)
+
+- **STATE.md**: Max 100 lines (YAML frontmatter only, no body)
+- **PLAN.md**: Max 150 lines (task descriptions, no implementation)
+- **SUMMARY.md**: Max 80 lines (results only, no verbose explanations)
+- **PROJECT.md**: Max 200 lines (first 50 read, rest optional)
+- **ROADMAP.md**: Max 100 lines (all phases must fit)
+
+## Workflow-Level Budget
+
+Typical workflow token distribution:
+
+```
+System prompt (workflow file): ~2-3K tokens
+Agent definition (injected): ~1K tokens
+Step fragments (selective @include): ~2-4K tokens
+Context data (state, init payload): ~1-2K tokens
+Output/completion: ~1K tokens
+
+Total: ~7-11K tokens per workflow run
+```
+
+## Per-Agent Budget
+
+When spawning agent:
+
+```
+Agent definition: ~1K tokens
+Agent context (task, findings): ~2-4K tokens
+Agent output: ~3-5K tokens
+
+Total agent spawn: ~6-10K tokens
+```
+
+Max 3 agent spawns per workflow (18-30K tokens).
+
+## Token Optimization Strategies
+
+### 1. Selective @include of Steps
+
+Instead of importing all steps, only include needed ones:
+
+```
+# Good: surgical inclusion
+@~/makeitdone/steps/init-gate.md
+@~/makeitdone/steps/model-route.md
+
+# Bad: monolithic inclusion
+@~/makeitdone/steps/*.md
+```
+
+### 2. Lazy Agent Spawning
+
+Default: no agents unless necessary.
+
+```
+if research_required or --research flag:
+  spawn mid-researcher
+else:
+  skip
+
+if verification_needed:
+  spawn mid-verifier
+else:
+  skip
+```
+
+### 3. Frontmatter-First Reads
+
+Always check context_window:
+
+```
+if context_window < 500k:
+  use: mid-tools fm get <file> --field <specific>
+else:
+  use: normal Read
+```
+
+### 4. Batch Grep Queries
+
+Instead of N separate grep calls:
+
+```
+# Bad: 10 separate greps
+grep "pattern1" ...
+grep "pattern2" ...
+grep "pattern3" ...
+
+# Good: single grep with alternation
+grep "pattern1|pattern2|pattern3" ...
+```
+
+### 5. Pass Paths, Not Contents
+
+When delegating to agent:
+
+```
+# Good: path-based
+task: "Review PLAN.md at .planning/phases/01/PLAN.md"
+
+# Bad: content-based
+task: "Review this plan: [full 150-line PLAN.md content]"
+```
+
+## Context Tier Actions
+
+### POOR (< 300k)
+
+- Frontmatter-only reads
+- No agent spawning
+- Return error: "Context too low for this workflow"
+
+### DEGRADING (300-500k)
+
+- Frontmatter-only reads
+- Single agent max (critical path only)
+- Skip optional research
+- Use haiku exclusively
+
+### GOOD (500k-1M)
+
+- Full reads enabled
+- Up to 3 agents
+- Model routing by profile
+- Research optional
+
+### PEAK (> 1M)
+
+- All features enabled
+- Full parallelization
+- Multiple agents
+- Synthesis work enabled
+
+## Budget Worksheet (for phase plan creators)
+
+When creating PLAN.md, estimate waves:
+
+```
+Rough formula:
+- Each wave: ~5-10 tasks
+- Each task: ~10-15 lines in PLAN.md
+- Max PLAN.md: 150 lines
+
+If tasks > 10, split into 2+ waves
+If PLAN.md approaches 150 lines, create secondary phase plan
+```
+
+## Anti-patterns
+
+- Loading all documentation at once (use frontmatter)
+- Reading files when context_window < 500k (use mid-tools fm)
+- Creating large context data structures (use TOON, not JSON)
+- Spawning multiple agents per wave (1 executor, 1 verifier max)

package/makeitdone/steps/init-gate.md

@@ -0,0 +1,42 @@
+# Init Gate Pattern
+
+Token-optimized initialization payload pattern. Use this in any workflow that needs fresh execution context.
+
+## Pattern
+
+```bash
+PAYLOAD=$(node ~/.claude/makeitdone/bin/mid-tools.cjs init <workflow> <phase>)
+```
+
+The PAYLOAD contains (in TOON format):
+- `phase_dir`: Full path to current phase directory
+- `plans`: List of all PLAN.md files in phase
+- `incomplete_plans`: Plans without SUMMARY.md (not yet done)
+- `branch_name`: Conventional branch name `phase-{number}`
+- `parallelization`: true if multiple plans (waves enabled)
+- `executor_model`: Model routed for execution (sonnet/haiku based on profile)
+- `verifier_model`: Model routed for verification (haiku/sonnet)
+- `context_window`: Token budget from config.json
+- `model_profile`: Current profile (budget/balanced/quality)
+
+## Usage in Workflows
+
+At start of workflow:
+
+```
+# Get fresh context
+<context>
+init_payload: (mid-tools init <workflow> <phase-number>)
+</context>
+
+Parse TOON payload:
+- Extract phase_dir
+- Extract incomplete_plans count
+- Route models based on executor_model, verifier_model fields
+```
+
+## Token Savings
+
+- TOON format saves ~40% vs JSON
+- Only includes essential fields (not full phase history)
+- Frontmatter-safe for context_window < 500k