██████████████
                ████░░░░░░░░░░░░░░████
              ██░░░░░░░░░░░░░░░░░░░░░░██
            ██░░░░░░░░████████░░░░░░░░░░██
          ██░░░░░░████        ████░░░░░░░░██
         ██░░░░██                  ██░░░░░░██
        ██░░░░██   ██████  ██████   ██░░░░░░██
       ██░░░░██   ████████████████   ██░░░░░░██
       ██░░░░██   ██▓▓▓▓████▓▓▓▓██   ██░░░░░░██
       ██░░░░██   ██▓▓▓▓████▓▓▓▓██   ██░░░░░░██
       ██░░░░██   ████████████████   ██░░░░░░██
        ██░░░░██    ████    ████    ██░░░░░░██
         ██░░░░██                  ██░░░░░░██
          ██░░░░░░████        ████░░░░░░░░██
            ██░░░░░░░░████████░░░░░░░░░░██
              ██░░░░░░░░░░░░░░░░░░░░░░██
                ████░░░░░░░░░░░░░░████
                    ██████████████

MEGAMIND

The AI brain that builds while you sleep. By Itsjwill

./megamind.sh

Autonomous AI agents that loop until your project is complete.

"Fresh context every iteration. Memory persists. Quality guaranteed."

How It Works · Quick Start · The MEGAMIND Advantage · Commands

---

What Is MEGAMIND?

MEGAMIND runs AI coding agents in an autonomous loop. Give it user stories or a project plan, and it builds everything — piece by piece — until done.

You → Define what you want (prd.json or GSD plans)
         ↓
MEGAMIND → Loops AI agents until complete
         ↓
You → Wake up to working software

Each iteration:

1. 🧠 Spawns a fresh AI agent (Claude Code or Amp)
2. 📋 Picks the next incomplete task
3. ⚡ Implements it with full focus
4. ✅ Runs quality checks
5. 💾 Commits if passing
6. 📝 Updates progress & patterns
7. 🔄 Loops until everything passes

---

The MEGAMIND Advantage

🧠 Fresh Brain Every Time

As AI fills its context, quality degrades. You've seen this:

"Due to context limits, I'll be more concise..."

Translation: The AI is about to cut corners.

MEGAMIND prevents this. Each iteration starts with a fresh 200k context:

Traditional AI	MEGAMIND
Context fills up	Fresh start each loop
Quality degrades	Peak quality always
Forgets earlier work	Memory via files
Does too much	ONE task per loop

📚 Memory Without Context Bloat

MEGAMIND remembers everything via files, not context:

File	Purpose
PATTERNS.md	Codebase patterns & gotchas
progress.txt	What was built & learned
prd.json	Task completion status
Git history	Actual changes

The AI reads these fresh each iteration. Full memory, zero bloat.

🎯 One Task = One Commit

Each loop produces exactly one focused commit:

abc123f feat: US-001 - Add user login
def456g feat: US-002 - Add logout button
hij789k feat: US-003 - Add password reset

Benefits:

• git bisect finds exact breaking change
• Each task independently revertable
• Clean history for future AI iterations

🔄 Self-Improving Loop

MEGAMIND learns as it works:

Iteration 1: Discovers codebase uses Zod
         ↓ Updates PATTERNS.md
Iteration 2: Uses Zod without trial/error
         ↓ Faster implementation
Iteration N: Knows all patterns
         ↓ Maximum efficiency

---

How It Works

┌─────────────────────────────────────────────────────────────┐
│                     🧠 MEGAMIND LOOP                        │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ 1. READ BRAIN STATE                                 │   │
│  │    • PATTERNS.md (codebase knowledge)               │   │
│  │    • progress.txt (history)                         │   │
│  │    • prd.json / PLAN.md (tasks)                     │   │
│  └─────────────────────────────────────────────────────┘   │
│                            ↓                                │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ 2. SPAWN FRESH AI AGENT                             │   │
│  │    • Clean 200k context                             │   │
│  │    • Full focus on ONE task                         │   │
│  │    • No degradation                                 │   │
│  └─────────────────────────────────────────────────────┘   │
│                            ↓                                │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ 3. IMPLEMENT                                        │   │
│  │    • Follow patterns from PATTERNS.md               │   │
│  │    • Implement the task/story                       │   │
│  │    • Run quality checks                             │   │
│  └─────────────────────────────────────────────────────┘   │
│                            ↓                                │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ 4. COMMIT & UPDATE                                  │   │
│  │    • Commit if checks pass                          │   │
│  │    • Update progress.txt                            │   │
│  │    • Update PATTERNS.md (if learned)                │   │
│  │    • Mark task complete                             │   │
│  └─────────────────────────────────────────────────────┘   │
│                            ↓                                │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ 5. LOOP OR EXIT                                     │   │
│  │    • More tasks? → Loop to step 1                   │   │
│  │    • All done? → Exit with success                  │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

---

Quick Start

Prerequisites

Install one of these AI CLIs:

# Claude Code (Anthropic)
npm install -g @anthropic-ai/claude-code

# Or Amp
# Visit https://ampcode.com

Option 1: PRD Mode (User Stories)

Best for: Feature work with clear requirements.

1. Create your stories:

mkdir -p .planning/mind

Create .planning/mind/prd.json:

{
  "project": "MyApp",
  "branchName": "feature/user-auth",
  "userStories": [
    {
      "id": "US-001",
      "title": "Add user registration",
      "description": "As a new user, I want to register with email/password",
      "acceptanceCriteria": [
        "Registration form at /register",
        "Email validation",
        "Password min 8 chars",
        "Redirect to /login on success"
      ],
      "priority": 1,
      "passes": false
    },
    {
      "id": "US-002",
      "title": "Add user login",
      "description": "As a registered user, I want to log in",
      "acceptanceCriteria": [
        "Login form at /login",
        "JWT token on success",
        "Error on invalid credentials"
      ],
      "priority": 2,
      "passes": false
    }
  ]
}

2. Run MEGAMIND:

./megamind.sh

3. Watch it build. Each story implemented one at a time.

Option 2: Plan Mode (GSD Phases)

Best for: Full project lifecycle, architecture-heavy work.

1. Initialize project:

claude '/gsd:new-project'

Answer the questions. Creates PROJECT.md.

2. Create roadmap:

claude '/gsd:create-roadmap'

Creates phases in ROADMAP.md.

3. Plan first phase:

claude '/gsd:plan-phase 1'

Creates detailed PLAN.md with tasks.

4. Run MEGAMIND:

./megamind.sh

5. Watch it execute. Each task committed individually.

---

Modes

PRD Mode

./megamind.sh --mode=prd

• Reads .planning/mind/prd.json
• Implements one user story per iteration
• Marks passes: true when done
• Exits when all stories pass

Plan Mode

./megamind.sh --mode=plan

• Reads .planning/phases/*/PLAN.md files
• Executes tasks from each plan
• Creates SUMMARY.md per plan
• Updates STATE.md and ROADMAP.md
• Full GSD deviation rules

Auto Mode (Default)

./megamind.sh

• If prd.json exists with incomplete stories → PRD mode
• Otherwise → Plan mode

---

Commands

./megamind.sh [iterations] [--mode=prd|plan|auto] [--help]

Option	Description
iterations	Max loops before stopping (default: 10)
--mode=prd	Force PRD mode
--mode=plan	Force Plan mode
--mode=auto	Auto-detect (default)
--help	Show help

Examples:

./megamind.sh              # 10 iterations, auto
./megamind.sh 50           # 50 iterations, auto
./megamind.sh --mode=prd   # 10 iterations, PRD
./megamind.sh 100 --mode=plan  # 100 iterations, Plan

---

File Structure

your-project/
├── .planning/
│   ├── PROJECT.md          # Project vision
│   ├── ROADMAP.md          # Phase roadmap
│   ├── STATE.md            # Session state
│   ├── ISSUES.md           # Deferred issues
│   ├── phases/             # GSD plans
│   │   ├── 01-foundation/
│   │   │   ├── 01-01-PLAN.md
│   │   │   └── 01-01-SUMMARY.md
│   │   └── ...
│   └── mind/               # 🧠 MEGAMIND files
│       ├── prd.json        # User stories
│       ├── progress.txt    # Execution log
│       ├── PATTERNS.md     # Learned patterns
│       └── archive/        # Previous runs
└── megamind.sh             # The brain

---

Pattern Learning

MEGAMIND learns as it builds. The PATTERNS.md file grows with each iteration.

Example PATTERNS.md:

# 🧠 MEGAMIND Brain Patterns

## Architecture
- API routes: `src/app/api/[route]/route.ts`
- Components: `src/components/[Name]/index.tsx`
- Database: `src/db/schema.ts` (Drizzle ORM)

## Conventions
- Use `jose` for JWT (not jsonwebtoken)
- Zod for validation with `.safeParse()`
- TailwindCSS only, no inline styles
- "use client" for interactive components

## Gotchas
- Always add new routes to middleware.ts
- Migrations need `IF NOT EXISTS`
- Form components need client directive

## Dependencies
- auth.ts depends on db/schema.ts
- Changing user schema requires migration
- API routes import from @/lib/*

Every iteration reads this first. The AI gets smarter each loop.

---

GSD Integration

MEGAMIND includes full GSD (Get Shit Done) support.

GSD Commands

Use with Claude Code:

Command	What It Does
/gsd:new-project	Initialize with questions
/gsd:create-roadmap	Create phase roadmap
/gsd:plan-phase N	Plan phase N
/gsd:execute-plan	Execute one plan
/gsd:progress	Check status
/gsd:verify-work	Manual testing
/gsd:rollback	Undo changes

Deviation Rules

When executing plans, MEGAMIND follows these rules:

1. Auto-fix bugs — Fix immediately, document
2. Auto-add critical — Security/correctness gaps
3. Auto-fix blockers — Unblock and continue
4. Ask about architectural — STOP and ask human
5. Log enhancements — Add to ISSUES.md

---

Quality Gates

Every iteration must pass:

• Typecheck
• Lint
• Tests
• Focused changes only
• Individual file staging

If checks fail, no commit. Fix then retry.

---

Use Cases

🚀 Ship an MVP overnight

# Define your features
cat > .planning/mind/prd.json << 'EOF'
{
  "project": "SaaS MVP",
  "branchName": "feature/mvp",
  "userStories": [
    {"id": "US-001", "title": "Landing page", "priority": 1, "passes": false},
    {"id": "US-002", "title": "User signup", "priority": 2, "passes": false},
    {"id": "US-003", "title": "Dashboard", "priority": 3, "passes": false},
    {"id": "US-004", "title": "Stripe integration", "priority": 4, "passes": false}
  ]
}
EOF

# Let MEGAMIND build it
./megamind.sh 20

# Wake up to working MVP

🔧 Refactor a legacy codebase

# Initialize GSD
claude '/gsd:new-project'
# "I want to modernize this Express app to Next.js"

claude '/gsd:create-roadmap'
# Creates phased migration plan

claude '/gsd:plan-phase 1'
# Plans first phase

./megamind.sh 50
# MEGAMIND migrates piece by piece

🐛 Fix a backlog of bugs

cat > .planning/mind/prd.json << 'EOF'
{
  "project": "Bug Fixes",
  "branchName": "fix/q1-bugs",
  "userStories": [
    {"id": "BUG-101", "title": "Fix login timeout", "priority": 1, "passes": false},
    {"id": "BUG-102", "title": "Fix cart calculation", "priority": 2, "passes": false},
    {"id": "BUG-103", "title": "Fix email templates", "priority": 3, "passes": false}
  ]
}
EOF

./megamind.sh
# Each bug fixed with its own commit

---

Troubleshooting

"No AI CLI found"

# Install Claude Code
npm install -g @anthropic-ai/claude-code

# Or install Amp from https://ampcode.com

"prd.json not found"

Create .planning/mind/prd.json with your user stories. See examples above.

".planning directory not found"

Initialize with GSD:

claude '/gsd:new-project'

AI not following patterns

Make sure .planning/mind/PATTERNS.md exists. MEGAMIND reads this first each iteration.

Stuck in infinite loop

The loop exits when:

• All stories have passes: true
• All PLAN.md files have SUMMARY.md
• Max iterations reached

Check your status:

# PRD mode
cat .planning/mind/prd.json | jq '.userStories[] | {id, passes}'

# Plan mode
ls .planning/phases/*/*.md

---

Credits

MEGAMIND combines the best of:

• GSD (Get Shit Done) by TÂCHES — Project lifecycle management
• Ralph by Ryan Carson — Iterative agent loop
• Geoffrey Huntley's Ralph pattern — Original concept

---

License

MIT License. See LICENSE for details.

---

    🧠 MEGAMIND

    The AI brain that builds while you sleep.
    Fresh context. Persistent memory. Ship faster.

Star this repo if MEGAMIND helps you ship!