Why I built this

I'm a solo developer who builds everything with Claude Code. I tried BMAD, SpecKit, Taskmaster, GSD — they all taught me something. BMAD was too enterprise. SpecKit too rigid. GSD is brilliant at context engineering but doesn't help you write the spec in the first place.

So I built Effectum. It combines what I learned from all of them: structured specifications (like SpecKit), autonomous execution (like GSD's approach), and quality gates that actually enforce standards.

The result: describe what you want, write a proper spec with the PRD Workshop, then let Claude Code build it overnight with the Ralph Loop.

This isn't a new idea — it's the best combination of existing ideas I've found, packaged so it actually works.

🚀 Quick Start

npx @aslomon/effectum

The interactive installer asks two questions — scope (global or local) and runtime — then sets everything up.

# Open Claude Code in your project
cd ~/my-project && claude

# Set up your project (substitutes placeholders in settings.json)
/setup .

# Write a specification
/prd:new

# Build it
/plan docs/prds/001-my-feature.md

[!TIP] That's it. Four steps from zero to autonomous development.

Install options

npx @aslomon/effectum                   # Interactive (recommended)
npx @aslomon/effectum --global          # Install to ~/.claude/ for all projects
npx @aslomon/effectum --local           # Install to ./.claude/ for this project only
npx @aslomon/effectum --global --claude # Non-interactive, Claude Code runtime

git clone https://github.com/aslomon/effectum.git
cd effectum
claude
/setup ~/my-project

📦 What's Included

One command. Everything you need for autonomous Claude Code development.

🎯 How It Works

Effectum has two parts that work together:

graph LR
    A["💡 Your Idea"] --> B["📋 Specification\n(PRD Workshop)"]
    B --> C["/plan\nAnalyze & Plan"]
    C --> D["/tdd\nTests → Code"]
    D --> E["/verify\nQuality Gates"]
    E --> F["/code-review\nSecurity Audit"]
    F --> G["✅ Production Code"]

    style A fill:#fef3c7,stroke:#f59e0b,color:#92400e
    style B fill:#e0e7ff,stroke:#6366f1,color:#3730a3
    style C fill:#f3f4f6,stroke:#9ca3af,color:#374151
    style D fill:#f3f4f6,stroke:#9ca3af,color:#374151
    style E fill:#f3f4f6,stroke:#9ca3af,color:#374151
    style F fill:#f3f4f6,stroke:#9ca3af,color:#374151
    style G fill:#dcfce7,stroke:#22c55e,color:#166534

🔧 The Workflow

/plan — Think before building

Claude reads your specification, explores your codebase, and creates a plan. It identifies risks, asks questions, and waits for your OK before writing a single line of code.

/tdd — Tests first, always

Write a failing test → Write code to pass it → Improve → Repeat. Every feature is tested before it exists.

/verify — Every quality gate, every time

/code-review — A second pair of eyes

Reviews every change for security issues, code quality, architecture violations, and common mistakes. Rates findings as Critical, Warning, or Info.

/ralph-loop — Build while you sleep

[!IMPORTANT] This is the most powerful feature.

/ralph-loop "Build the auth system"
  --max-iterations 30
  --completion-promise "All tests pass, build succeeds, 0 lint errors"

Claude works autonomously — writing code, running tests, fixing errors, iterating — until every quality gate passes. It only stops when the promise is 100% true.

You go to sleep. You wake up to a working feature.

graph TD
    A["Start: Read PRD"] --> B["Check current state\n(git diff, tests)"]
    B --> C["Implement next step"]
    C --> D["Run quality gates"]
    D --> E{"All gates\npass?"}
    E -- No --> F{"Same error\n3+ times?"}
    F -- No --> B
    F -- Yes --> G["Try different approach"]
    G --> B
    E -- Yes --> H{"Completion\npromise true?"}
    H -- No --> B
    H -- Yes --> I["✅ Output promise\nDone!"]

    D --> J{"80% iterations\nused?"}
    J -- Yes --> K["📝 Write status report"]
    K --> B

    style I fill:#dcfce7,stroke:#22c55e
    style A fill:#e0e7ff,stroke:#6366f1

📋 The PRD Workshop

A specification (PRD) is the bridge between "I want this" and "Claude builds this."

The better the spec, the better the code.

Two Modes

What a Specification Contains

┌─────────────────────────────────────────┐
│  📋 EFFECTUM SPECIFICATION (PRD)        │
├─────────────────────────────────────────┤
│                                         │
│  Problem & Goal                         │
│  ── What are we solving? Why?           │
│                                         │
│  User Stories                           │
│  ── What can users do when done?        │
│                                         │
│  Acceptance Criteria                    │
│  ── Given X, When Y, Then Z            │
│  ── (every criterion = one test)        │
│                                         │
│  Data Model                            │
│  ── Tables, fields, types, RLS          │
│                                         │
│  API Design                            │
│  ── Endpoints, formats, error codes     │
│                                         │
│  Quality Gates                         │
│  ── 8 automated checks that must pass   │
│                                         │
│  Completion Promise                    │
│  ── "All tests pass, build succeeds,    │
│     0 lint errors"                      │
│                                         │
└─────────────────────────────────────────┘

Workshop Commands

🆚 How is this different?

The short version: Effectum doesn't invent new concepts. It combines what already works, removes what doesn't, and packages it so it actually runs.

🎨 Stack Presets

Effectum adapts to your technology:

Each preset configures build commands, test frameworks, linters, formatters, and architecture rules for your stack.

🎚️ Three Autonomy Levels

Choose how much Claude decides on its own:

Choose during /setup. Change anytime in .claude/settings.json.

⚠️ Limitations

Effectum is useful, but it's honest about what it can't do yet:

• Only works with Claude Code — workflow commands are Claude Code specific. Other runtimes (Codex, Gemini CLI) are on the roadmap.
• PRD Workshop requires Claude Code slash commands — you can't use it from the web interface or API directly.
• Ralph Loop effectiveness depends on PRD quality — garbage in, garbage out. A vague spec produces vague code, even autonomously.
• MCP servers need npm/Node.js — if you're in a restricted environment without npm access, MCP setup will fail.
• No test suite yet — ironic for a TDD tool. It's on the list.

📁 Project Structure

effectum/
│
├── system/                          The installable workflow
│   ├── templates/                   CLAUDE.md, settings, guardrails (parameterized)
│   ├── commands/                    10 workflow commands
│   └── stacks/                     Next.js · Python · Swift · Generic
│
├── workshop/                        Specification tools
│   ├── knowledge/                   8 reference guides
│   ├── templates/                   PRD & project templates
│   └── projects/                    Your spec projects (per branch)
│
├── docs/                            Documentation
│   ├── workflow-overview.md         The complete workflow
│   ├── installation-guide.md        Setup step by step
│   ├── prd-workshop-guide.md        Writing great specs
│   ├── customization.md            Adapting Effectum
│   └── troubleshooting.md          Common fixes
│
├── CLAUDE.md                        Makes Claude understand this repo
└── README.md                        You are here

📚 Documentation

❓ FAQ

🤝 Contributing

The most impactful areas:

• 🎨 Stack presets — Add Go, Rust, Ruby, Django, etc.
• 🔧 Workflow commands — Improve or add new ones
• 📚 Knowledge base — Better examples, more techniques
• 🌍 Documentation — Clearer guides, translations