make-it-done 0.1.0

package/makeitdone/steps/model-route.md

@@ -0,0 +1,70 @@
+# Model Routing Pattern
+
+Route Claude models based on task complexity and context window.
+
+## Profiles
+
+From config.json `model_profile` field:
+
+| Profile | Executor | Verifier | Use Case |
+|---------|----------|----------|----------|
+| **budget** | haiku | haiku | Token-constrained, simple tasks |
+| **balanced** | sonnet | haiku | Default, good speed/quality trade-off |
+| **quality** | opus | sonnet | Complex design, safety-critical code |
+
+## Context Window Tiers
+
+Based on `context_window` from config.json:
+
+| Range | Tier | Behavior |
+|-------|------|----------|
+| < 300k | **POOR** | Read-only, no generation, agent spawn disabled |
+| 300-500k | **DEGRADING** | Frontmatter-only reads, small tasks only |
+| 500k-1M | **GOOD** | Full reads, normal task complexity |
+| > 1M | **PEAK** | All features enabled, complex synthesis |
+
+## Model Selection Logic
+
+```
+if tier == POOR:
+  disable agents, return "context too low"
+
+if tier == DEGRADING:
+  use haiku for all work
+  forbid agents
+  use frontmatter-only reads
+
+if tier == GOOD:
+  use config model_profile routing
+  enable research agent if --research
+
+if tier == PEAK:
+  use config model_profile routing
+  enable all agents
+  parallelization enabled
+```
+
+## Practical Usage in Workflows
+
+```
+<context>
+context_window: (mid-tools config get context_window)
+model_profile: (mid-tools config get model_profile)
+</context>
+
+Determine Tier:
+- If context_window < 300k: POOR tier → escalate to user
+- If context_window < 500k: DEGRADING tier → frontmatter-only reads
+- Else: Use normal read strategy
+
+Route Executor:
+- budget: use haiku
+- balanced: use sonnet
+- quality: use opus
+```
+
+## Anti-patterns
+
+- Ignoring context_window (causes context exhaustion)
+- Using opus for verification (wastes tokens)
+- Not adjusting for POOR tier (causes failures)

package/makeitdone/steps/state-read.md

@@ -0,0 +1,56 @@
+# State Read Pattern
+
+Token-optimized STATE.md reading with context window guard.
+
+## Pattern
+
+```bash
+# Check context
+if context_window < 500k:
+  FRONTMATTER=$(node ~/.claude/makeitdone/bin/mid-tools.cjs fm get .planning/STATE.md)
+else:
+  STATE=$(node ~/.claude/makeitdone/bin/mid-tools.cjs state get)
+```
+
+## Frontmatter-Only Read (< 500k tokens)
+
+When context is tight, read only frontmatter:
+```bash
+mid-tools fm get .planning/STATE.md
+```
+
+Returns TOON with only:
+```
+phase: 1
+current_wave: 1
+wave_1_complete: false
+wave_2_complete: false
+...
+```
+
+## Full State Read (>= 500k tokens)
+
+When context is abundant:
+```bash
+mid-tools state get
+```
+
+Returns TOON with entire STATE.md frontmatter + body structure.
+
+## Atomic State Updates
+
+Always use mid-tools for writes (never write STATE.md directly):
+
+```bash
+# Set single field
+mid-tools state set current_wave 2
+
+# Advance to next phase
+mid-tools state advance 2
+```
+
+## Anti-patterns
+
+- Never write STATE.md directly
+- Never load full STATE.md if context < 500k (use fm)
+- Never update multiple fields without atomic operation

package/makeitdone/templates/plan.md

@@ -0,0 +1,94 @@
+---
+phase: 1
+phase_name: Foundation
+tasks: 8
+estimated_hours: 16
+waves: 2
+acceptance_criteria: 8
+dependencies: []
+---
+
+# Phase 1 Plan: Foundation
+
+## Overview
+
+Establish project infrastructure, authentication, and core data models.
+
+**Target**: 16 hours / 2 weeks / 2 waves
+
+---
+
+## Wave 1: Infrastructure & Auth (6 tasks, ~8 hours)
+
+### 01-01 Project Setup
+- User stories: US-Setup-001
+- Create git repo, CI/CD pipeline, Docker setup
+- Tests: setup.test.ts
+- Acceptance: CI passes, Docker builds, README complete
+
+### 01-02 Database Schema
+- User stories: US-Data-001, US-Data-002
+- Design and implement core tables (users, data)
+- Tests: schema.test.ts
+- Acceptance: Migrations run, schema documented
+
+### 01-03 Authentication System
+- User stories: US-Auth-001, US-Auth-002
+- JWT implementation, login/logout endpoints
+- Tests: auth.test.ts (> 80% coverage)
+- Acceptance: Login works, tokens refresh, security review passed
+
+### 01-04 User Model
+- User stories: US-User-001
+- User model, validation, serialization
+- Tests: user.test.ts
+- Acceptance: Model works, validation complete
+
+### 01-05 API Foundation
+- User stories: US-API-001
+- API server setup, routing, middleware
+- Tests: api.test.ts
+- Acceptance: Server runs, endpoints respond
+
+### 01-06 Documentation
+- User stories: US-Docs-001
+- API docs (OpenAPI/Postman), README
+- Tests: docs validation
+- Acceptance: Docs complete, links valid
+
+---
+
+## Wave 2: Testing & Polish (2 tasks, ~8 hours)
+
+### 01-07 Integration Tests
+- User stories: US-Test-001
+- End-to-end auth flow, data consistency
+- Tests: integration.test.ts
+- Acceptance: All flows pass, coverage > 80%
+
+### 01-08 Security Audit & Fixes
+- User stories: US-Security-001
+- OWASP top 10 check, CVE scan
+- Tests: security.test.ts
+- Acceptance: No critical/high vulns, audit report
+
+---
+
+## Acceptance Criteria (for Phase Complete)
+
+1. ✓ All 8 tasks completed with SUMMARY.md
+2. ✓ Unit test coverage > 80%
+3. ✓ Integration tests pass
+4. ✓ Security audit passed
+5. ✓ API documentation complete
+6. ✓ README and setup guide done
+7. ✓ Code reviewed (2+ approvals)
+8. ✓ Deployed to staging environment
+
+---
+
+## Notes
+
+- Wave 1 can be parallelized (01-02, 01-03, 01-04 independent)
+- Wave 2 requires Wave 1 complete
+- Estimated 16-20 hours total (accounting for meetings, reviews)

package/makeitdone/templates/project.md

@@ -0,0 +1,62 @@
+---
+name: Project Name
+description: |
+  One-line project description / mission statement
+created: 2026-04-05
+owner: User Name
+---
+
+# Project Overview
+
+## Vision
+
+What is this project about? What does it accomplish?
+
+## Goals
+
+- Goal 1: Clear, measurable outcome
+- Goal 2: Must have (vs nice-to-have)
+- Goal 3: Success criteria
+
+## Scope
+
+What's IN scope:
+- Feature A
+- Feature B
+
+What's OUT of scope:
+- Non-goal 1
+- Non-goal 2
+
+## Key Constraints
+
+- **Timeline**: Estimate in weeks (if applicable)
+- **Tech Stack**: Framework/language choices and why
+- **Team**: Who's involved? Roles?
+
+## Success Metrics
+
+How do we know this is done?
+- Metric 1: Measurable, objective
+- Metric 2: User feedback / adoption
+- Metric 3: Performance / quality baseline
+
+---
+
+## Dependencies
+
+- External APIs or services required?
+- Third-party libraries or frameworks?
+- Data or configurations needed from elsewhere?
+
+## Risks & Mitigations
+
+| Risk | Impact | Mitigation |
+|------|--------|-----------|
+| Technical debt from old codebase | High | Allocate refactor phase |
+| Resource constraints | Medium | Prioritize MVP features |
+
+## Next Steps
+
+See REQUIREMENTS.md for detailed requirements.
+See ROADMAP.md for phase breakdown.

package/makeitdone/templates/requirements.md

@@ -0,0 +1,97 @@
+---
+name: Requirements
+description: Functional and non-functional requirements
+---
+
+# Requirements
+
+## Functional Requirements
+
+### User Stories
+
+**US-001: User can authenticate**
+- As a user, I can log in with email/password
+- Acceptance: Login form appears, credentials validated, JWT token issued
+- Status: Not started
+
+**US-002: User can view dashboard**
+- As an authenticated user, I can see my dashboard
+- Acceptance: Dashboard loads, shows user data, respects permissions
+- Status: Not started
+
+### Features
+
+| Feature | Priority | Story Points | Status |
+|---------|----------|--------------|--------|
+| Authentication | Must-have | 8 | Not started |
+| Dashboard | Must-have | 13 | Not started |
+| Data Export | Nice-to-have | 5 | Backlog |
+
+---
+
+## Non-Functional Requirements
+
+### Performance
+
+- Page load time: < 2s (P95)
+- API response: < 200ms (P95)
+- Database query: < 50ms (P95)
+
+### Scalability
+
+- Support 1000+ concurrent users
+- Horizontal scaling via load balancer
+- Auto-scaling based on CPU/memory
+
+### Security
+
+- Password hashing (bcrypt, min 12 rounds)
+- HTTPS-only (no HTTP)
+- CSRF protection on forms
+- SQL injection protection via ORM/parameterized queries
+- Rate limiting on login (5 attempts / 15 min)
+
+### Reliability
+
+- 99.9% uptime SLA
+- Database backups (daily)
+- Disaster recovery plan
+- Monitoring & alerting
+
+### Accessibility
+
+- WCAG 2.1 Level AA compliance
+- Keyboard navigation
+- Screen reader support
+
+---
+
+## Acceptance Criteria (for phase completion)
+
+Phase must meet ALL of these:
+
+1. ✓ All unit tests pass (> 80% coverage)
+2. ✓ Integration tests pass
+3. ✓ Security scan passes (no critical/high vulnerabilities)
+4. ✓ Performance benchmarks meet targets
+5. ✓ Documentation updated (README, API docs)
+6. ✓ Code review passed (2 approvals)
+7. ✓ Manual QA sign-off
+
+---
+
+## Constraints
+
+- **Technology**: Must use [framework/language]
+- **Platform**: Target [browser/OS/device]
+- **Data**: Comply with [regulation: GDPR/CCPA/etc]
+- **Timeline**: Soft deadline [date]
+
+---
+
+## Open Questions
+
+- [ ] Question 1: Details?
+- [ ] Question 2: Details?
+
+*Once planning phase completes, update this section with answers.*

package/makeitdone/templates/roadmap.md

@@ -0,0 +1,111 @@
+---
+name: Roadmap
+description: Phase breakdown and timeline
+---
+
+# Roadmap
+
+## Phase Summary
+
+Total phases: [N]
+Timeline: [approx weeks]
+Current phase: 1
+
+---
+
+## 01 - Foundation [not-started]
+
+**Goal**: Set up infrastructure, authentication, data models
+
+**Milestone**: Foundation ready for feature development
+
+**Dependencies**: None (project start)
+
+**Deliverables**:
+- Project structure
+- CI/CD pipeline
+- Authentication system
+- Core data models
+- Database schema
+
+**Duration**: 1-2 weeks
+
+---
+
+## 02 - Core Features [not-started]
+
+**Goal**: Implement primary user-facing features
+
+**Milestone**: MVP ready for internal testing
+
+**Dependencies**: Phase 1 complete
+
+**Deliverables**:
+- Dashboard
+- Data management UI
+- API endpoints
+- Admin panel
+
+**Duration**: 2-3 weeks
+
+---
+
+## 03 - Refinement [not-started]
+
+**Goal**: Polish, optimize, security hardening
+
+**Milestone**: Ready for production release
+
+**Dependencies**: Phase 2 complete
+
+**Deliverables**:
+- Performance optimization
+- Security audit fixes
+- Documentation
+- User guide
+
+**Duration**: 1-2 weeks
+
+---
+
+## 04 - Launch [not-started]
+
+**Goal**: Deploy to production, monitor, support
+
+**Milestone**: Live and stable
+
+**Dependencies**: Phase 3 complete
+
+**Deliverables**:
+- Production deployment
+- Monitoring setup
+- Support runbook
+- Launch announcement
+
+**Duration**: 1 week
+
+---
+
+## 05 - Iteration [backlog]
+
+**Goal**: Feedback loop, feature requests, tech debt
+
+**Milestone**: Continuous improvement
+
+**Dependencies**: Phase 4 complete
+
+**Deliverables**:
+- Bug fixes
+- Performance tuning
+- Feature enhancements
+- Tech debt paydown
+
+**Duration**: Ongoing
+
+---
+
+## Notes
+
+- **Critical path**: Foundation → Core → Launch (minimum 4-5 weeks)
+- **Risk**: Scope creep in Core Features phase
+- **Slack**: Refinement phase acts as buffer

package/makeitdone/templates/state.md

@@ -0,0 +1,28 @@
+---
+phase: 1
+phase_name: Foundation
+current_wave: 1
+wave_1_complete: false
+wave_2_complete: false
+branch: phase-01-foundation
+executor_model: sonnet
+verifier_model: haiku
+last_updated: 2026-04-05
+status: in-progress
+---
+
+# Execution State
+
+Current state of phase execution. Updated via `mid-tools state set/advance`.
+
+**Last update**: [timestamp]
+**By**: [agent/user]
+
+## Current Wave
+
+Wave 1: [Task 1, Task 2, Task 3] — in progress
+
+## Notes
+
+- Any blockers?
+- Any context for next run?

package/makeitdone/templates/summary.md

@@ -0,0 +1,58 @@
+---
+phase: 1
+phase_name: Foundation
+completed_at: 2026-04-05
+actual_hours: 18
+status: complete
+---
+
+# Phase 1 Summary
+
+## Results
+
+**Status**: ✅ Complete
+
+| Metric | Target | Actual |
+|--------|--------|--------|
+| Tasks | 8 | 8 |
+| Waves | 2 | 2 |
+| Hours | 16 | 18 |
+| Test coverage | > 80% | 84% |
+| Blockers | 0 | 1 (resolved) |
+
+## What We Built
+
+- CI/CD pipeline (GitHub Actions)
+- PostgreSQL schema + migrations
+- JWT authentication (Express.js)
+- User model with validation
+- REST API with 12 endpoints
+- OpenAPI documentation
+- Integration tests (15 scenarios)
+- Security audit (OWASP, passed)
+
+## Blockers Encountered
+
+1. **Database migration tool** — initially chose Knex, switched to Prisma (1 hour)
+   - Resolution: Discussed with team, used Prisma template
+
+## Quality Gates Passed
+
+- ✅ Unit tests: 84% coverage
+- ✅ Integration tests: all pass
+- ✅ Security: no critical vulns
+- ✅ Performance: API < 100ms
+- ✅ Code review: 2 approvals
+- ✅ Staging deployment: stable
+
+## Lessons Learned
+
+1. Database selection impacts velocity — Prisma migrations faster than manual SQL
+2. Early authentication scaffolding saved Wave 2 time
+3. Integration test setup should happen earlier (Wave 1)
+
+## Next Phase
+
+Foundation is ready. Proceed to **Phase 2: Core Features**
+
+See ROADMAP.md Phase 2 section.

package/makeitdone/workflows/debug.md

@@ -0,0 +1,135 @@
+# Debug Workflow
+
+Diagnose phase execution issues and unblock work.
+
+**Token budget**: ~10K (mid-debugger spawn + context)
+
+---
+
+## Context Setup
+
+@/Users/ismailalam/Development/my/makeitdone/makeitdone/steps/state-read.md
+@/Users/ismailalam/Development/my/makeitdone/makeitdone/steps/model-route.md
+
+---
+
+## Execution
+
+### 1. Capture Context
+
+```bash
+PHASE=${phase_arg}
+PLAN_SPEC=${plan_arg:-"current"}
+
+PHASE_DIR=".planning/phases/$(printf '%02d' $PHASE)-*"
+
+# Get error/blocker from STATE.md
+LAST_ERROR=$(mid-tools fm get .planning/STATE.md --field "last_error")
+BLOCKED_AT=$(mid-tools fm get .planning/STATE.md --field "blocked_task_id")
+```
+
+### 2. Check Recent Output
+
+```bash
+# Look for executor/verifier output in session context
+if [ -f "$PHASE_DIR/.last_execution_output" ]; then
+  ERROR_CONTEXT=$(cat "$PHASE_DIR/.last_execution_output")
+else
+  ERROR_CONTEXT="No recent execution output"
+fi
+```
+
+### 3. Spawn Debugger
+
+```bash
+DEBUGGER_OUTPUT=$(spawn agent \
+  name=mid-debugger \
+  model=sonnet \
+  context=$(cat << EOF
+phase: $PHASE
+plan_spec: $PLAN_SPEC
+last_error: $LAST_ERROR
+blocked_at: $BLOCKED_AT
+error_context: $ERROR_CONTEXT
+phase_dir: $PHASE_DIR
+EOF
+))
+```
+
+### 4. Parse Debugger Output
+
+```bash
+if [[ $DEBUGGER_OUTPUT == *"## ROOT CAUSE:"* ]]; then
+  # Extract root cause
+  ROOT_CAUSE=$(echo "$DEBUGGER_OUTPUT" | grep -A 2 "ROOT CAUSE:")
+  
+  output "## ROOT CAUSE IDENTIFIED"
+  echo "$ROOT_CAUSE"
+  
+elif [[ $DEBUGGER_OUTPUT == *"## ESCALATION NEEDED"* ]]; then
+  # Extract escalation reason
+  REASON=$(echo "$DEBUGGER_OUTPUT" | grep -A 5 "ESCALATION NEEDED")
+  
+  output "## ESCALATION NEEDED"
+  echo "$REASON"
+  
+  ask_user "Next steps?"
+else
+  output "## DEBUG INCOMPLETE"
+fi
+```
+
+### 5. Suggest Actions
+
+```bash
+# Debugger outputs recommended action
+RECOMMENDED=$(echo "$DEBUGGER_OUTPUT" | grep -A 3 "Recommended Action:")
+
+echo "Suggested fix:"
+echo "$RECOMMENDED"
+
+ask_user "Apply fix and retry? Or escalate?"
+```
+
+### 6. Checkpoint State
+
+```bash
+# Save debug output for record
+cp <(echo "$DEBUGGER_OUTPUT") "$PHASE_DIR/.debug_$(date +%s).txt"
+
+# Update STATE
+mid-tools state set last_error ""
+mid-tools state set last_debug_time $(date -u +%s)
+```
+
+---
+
+## Usage Examples
+
+```bash
+# Debug current blocked phase
+/mid:debug
+
+# Debug specific phase
+/mid:debug --phase 2
+
+# Debug specific task
+/mid:debug --phase 1 --plan 01-03
+```
+
+---
+
+## Error Handling
+
+- **No error context**: Ask user to describe issue
+- **Debugger timeout**: Partial diagnosis OK
+- **Root cause unclear**: Escalate with findings
+
+---
+
+## Anti-patterns Avoided
+
+✓ Single agent spawn (debugger only)
+✓ Context-aware (reads recent state)
+✓ Fast diagnosis (5 min budget)
+✓ Escalation when needed