JSPM

Describe what you want. Get production-ready code.

Effectum (Latin): the result, the accomplishment — that which has been brought to completion.

Quick Start · Configurator · The Workflow · Design · Update Command · PRD Lifecycle · Project Onboarding · Foundation · How is this different? · Website

Built by Jason Salomon-Rinnert. Works for me — might work for you. MIT licensed, PRs welcome.

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.

v0.16.0 is the trust + brownfield release. The autonomous loop now knows when it's stuck (2 repeated errors → stop + diagnosis), when it's running out of context (80% budget → clean handoff), and it persists state to disk so crashed sessions can resume. There's /forensics for post-mortem analysis, /effectum:init to teach Claude about your domain, and /map-codebase that drops 4 parallel agents to produce 7 structured knowledge docs. Plus sentinel-based CLAUDE.md splitting so your project context survives updates.

v0.17.0 is the Apple-like clarity release. New users now have /effectum as a starting point and /next as a smart router that reads your project state and tells you exactly what to do. Five human-language aliases (/run, /stop, /save, /diagnose, /explore) make the daily vocabulary intuitive. The workshop: namespace moved to project:, and effectum:init became /context:init. Plus 12 journey bug fixes found by 6 parallel code analysis agents.

The result: from zero to autonomous development, for any stack, any language, with the self-awareness and crash recovery that make overnight builds actually trustworthy.

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 configurator detects your stack, asks what you're building, and sets everything up.

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

# Onboard an existing codebase
/onboard

# Or write a specification and build from scratch
/prd:new
/plan docs/prds/001-my-feature.md

[!TIP] New project? /prd:new → /plan → /ralph-loop. Existing codebase? Start with /onboard — it gives Claude a complete picture of what you already have.

Install options

npx @aslomon/effectum                   # Interactive configurator (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 three parts that work together:

graph LR
    A["💡 Your Idea"] --> B["⚙️ Configurator\nStack Detection"]
    B --> C["📋 PRD Lifecycle\nSpec & Tracking"]
    C --> D["/plan\nAnalyze & Plan"]
    D --> E["/tdd\nTests → Code"]
    E --> F["/verify\nQuality Gates"]
    F --> G["/code-review\nSecurity Audit"]
    G --> H["✅ Production Code"]

    style A fill:#fef3c7,stroke:#f59e0b,color:#92400e
    style B fill:#fde8d8,stroke:#f97316,color:#9a3412
    style C fill:#e0e7ff,stroke:#6366f1,color:#3730a3
    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:#f3f4f6,stroke:#9ca3af,color:#374151
    style H fill:#dcfce7,stroke:#22c55e,color:#166534

⚙️ Configurator

The configurator is what makes Effectum genuinely approachable for any stack. You don't configure Effectum — Effectum figures out what you need and configures itself.

Intelligent Setup Recommender

Tell it what type of app you're building and what you want to accomplish. It maps your input to a recommended stack and workflow configuration.

What are you building?
> A multi-tenant SaaS with Stripe billing and a REST API

Recommended setup:
  ✓ Stack: Next.js + Supabase
  ✓ Auth: Supabase RLS + JWT
  ✓ Payments: Stripe webhook pattern
  ✓ Testing: Vitest + Playwright
  ✓ Deploy: Vercel

Smart Auto-Detection

Drop it into any project and it reads your existing config files to detect your stack automatically:

Modular Stack Selection (4 Steps)

If auto-detection doesn't nail it, or you want to be explicit:

Step 1/4: Ecosystem    → Node.js / Python / Go / Swift / Dart / …
Step 2/4: Framework    → Next.js / FastAPI / Echo / SwiftUI / …
Step 3/4: Database     → Supabase / PostgreSQL / Firebase / SQLite / …
Step 4/4: Deploy       → Vercel / Railway / Fly.io / App Store / …

8 Quick Presets

One click. Instantly configured.

Language & CLI Setup

• 16 languages supported + custom
• CLI tool check on install: detects what's missing (brew, pipx, go, swiftpm, etc.)
• Guided installation walkthrough when tools are absent — no silent failures

🔧 The Workflow

42 commands. Each does exactly one thing, and does it well. Every command includes YAML frontmatter with machine-readable metadata and shows contextual next steps after completion.

Planning & Design

Core Build Cycle

Autonomy & Control

PRD Commands

Setup & Onboarding

Diagnosis & Context

[!TIP] See the full Command Index for all 42 commands organized by workflow category with decision trees.

/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.

Ralph Loop also detects PRD changes mid-run via PRD-hash comparison. If your spec was updated while the loop was running, it pauses and reconciles before continuing.

graph TD
    A["Start: Read PRD\n+ Compute PRD Hash"] --> B["Check current state\n(git diff, tests)"]
    B --> B2{"PRD hash\nchanged?"}
    B2 -- Yes --> B3["Reconcile\nspec changes"]
    B3 --> B
    B2 -- No --> 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
    style B3 fill:#fef3c7,stroke:#f59e0b

/forensics — Post-mortem diagnosis

When a Ralph Loop stops unexpectedly — due to stuck detection, a context budget stop, or an incomplete run — /forensics gives you a clear picture of what happened.

/forensics

It reads all available loop artifacts and produces a structured diagnosis report:

The output is a root-cause diagnosis with a recommended next action — whether that's fixing the blocker, resuming from checkpoint, or rewriting a failing test.

/effectum:init — Project context bootstrap

Teach Claude about your domain before it writes a single line of code. /effectum:init runs an interactive interview and writes the results into a sentinel block in CLAUDE.md:

/effectum:init

It asks about your domain model, key business rules, naming conventions, and any constraints the code must respect. The result is persisted between Effectum updates — the sentinel block is preserved when npx @aslomon/effectum update refreshes the rest of CLAUDE.md.

<!-- effectum:project-context:start -->
  Domain: Multi-tenant SaaS for event management
  Key entities: Tenant, Event, Booking, Venue
  Auth: Row-level security — all queries must be tenant-scoped
  ...
<!-- effectum:project-context:end -->

This is the right command to run before /ralph-loop on a new project, or before onboarding a Claude Code session to an existing domain.

/map-codebase — Parallel brownfield analysis

/map-codebase is purpose-built for understanding codebases you didn't write. It spawns 4 parallel analysis agents and produces 7 structured knowledge documents in knowledge/codebase/:

/map-codebase

Plus three synthesis documents: ENTRY-POINTS.md, RISK-MAP.md, and KNOWLEDGE-INDEX.md.

[!TIP] Use /map-codebase for fast brownfield orientation. Use /onboard when you want the full analysis including self-test loop and per-area PRDs.

Autonomous Loop — Self-Awareness Features (v0.16.0)

Three new mechanisms make Ralph Loop trustworthy enough for overnight builds:

Context Budget Monitor

The loop monitors its own context usage. At 80% of the context budget, it automatically:

1. Writes a clean HANDOFF.md to the project root — what's done, what's left, iteration count
2. Commits current state to git
3. Stops cleanly

The next Claude Code session can pick up exactly where it left off. Use /forensics to analyze the handoff, then /prd:resume to continue.

Stuck Detection

If the loop encounters the same error twice in a row, it:

1. Writes STUCK.md with the error, the context that produced it, and a preliminary diagnosis
2. Stops the loop
3. Returns control to you

This prevents the loop from burning 20 iterations on the same problem. Use /forensics to get a full diagnosis and recommended fix.

Per-Iteration Loop State

Every iteration, the loop persists its state to .effectum/loop-state.json:

{
  "iteration": 14,
  "maxIterations": 30,
  "lastAction": "Fixed failing auth test",
  "qualityGateStatus": { "build": "pass", "tests": "fail", "lint": "pass" },
  "blockers": [],
  "prdHash": "a3f8d2c1"
}

This enables /forensics to reconstruct exactly what the loop was doing when it stopped — even if it crashed mid-iteration.

Sentinel CLAUDE.md Split

Starting in v0.16.0, CLAUDE.md uses sentinel markers to separate system-managed content from your project context:

[System-managed Effectum configuration]
...

<!-- effectum:project-context:start -->
[Your project context — written by /effectum:init]
<!-- effectum:project-context:end -->

When you run npx @aslomon/effectum update, the system-managed section is refreshed with the latest templates and rules. Your project context between the sentinel markers is never touched. You can also edit the sentinel block manually — Effectum will preserve your changes across updates.

Hook Modernization

Foundation hooks now support richer configuration:

Hooks remain always-active for the three core guardrails (secret detection, TDD enforcement, destructive command blocking). The new features apply to custom hooks you add in system/hooks/.

/verify — Every quality gate, every time

🎨 Design System Generation

/design generates a structured DESIGN.md before you write a line of frontend code. It bridges the gap between "what to build" (PRD) and "how it should look" (implementation).

/prd:new → PRD approved → /design → DESIGN.md generated → /plan → /ralph-loop

How It Works

1. Reads the active PRD — extracts project name, app type, key features
2. Scans for design signals — detects Tailwind, shadcn/ui, CSS custom properties, UI libraries
3. Asks 3–5 lightweight questions — color palette, typography feel, UI complexity, references
4. Generates DESIGN.md — 7 sections: Overview, Color System, Typography, Component Patterns, Layout & Spacing, Interaction Design, Constraints
5. Confirms — summarizes key decisions, suggests /plan as next step

[!TIP] DESIGN.md is optional for CLI tools, API backends, and libraries. Only suggested for web apps, mobile apps, and fullstack projects.

🔄 Update Command

Already have Effectum installed? Update without re-running the full setup:

npx @aslomon/effectum update

The update command:

• Diffs commands — shows new and updated commands available in the latest version
• Re-renders templates — refreshes CLAUDE.md, settings.json, and guardrails.md from your existing config
• Preserves your config — reads .effectum.json, keeps your stack, autonomy level, and customizations
• Supports --yes — non-interactive mode for CI and automation

$ npx @aslomon/effectum update
ℹ Project: "my-app" (nextjs-supabase)
ℹ 3 new command(s) available:
    + /design
    + /prd:express
    + /prd:discuss
ℹ 5 command(s) with updates:
    ~ /ralph-loop
    ~ /onboard
    ...
✔ Updated: 3 new command(s) added, 5 command(s) updated, CLAUDE.md refreshed

📦 Package Manager Configurator

The configurator now auto-detects your package manager from lock files and recommends the best option for your ecosystem.

• Apple-like flow: detected package manager → confirm or change
• Ecosystem-aware defaults: pnpm for JS, uv for Python, cargo for Rust, go for Go
• Flows through all templates via {{PACKAGE_MANAGER}} — CLAUDE.md, guardrails, and settings all use the correct manager
• Supports: npm, pnpm, yarn, bun, uv, pip, poetry, cargo, go, swift package (SPM), flutter

📋 PRD Lifecycle

Specifications aren't static. They evolve. Effectum treats PRDs as living documents with full version control, semantic diffing, and automatic synchronization across your project.

Frontmatter & Changelog

Every PRD now has structured frontmatter:

---
id: prd-001
title: Auth System
status: in-progress
version: 1.3.0
created: 2026-01-15
updated: 2026-03-20
hash: a3f8d2c1
authors:
  - jason
implements:
  - prd-000-foundation
affects:
  - tasks.md
  - docs/network-map.html
---

And an auto-maintained changelog at the bottom:

## Changelog

- v1.3.0 (2026-03-20): Added rate limiting spec, revised token refresh flow
- v1.2.0 (2026-03-10): Expanded RLS policy section
- v1.1.0 (2026-02-28): Added 2FA requirements
- v1.0.0 (2026-01-15): Initial specification

Semantic Diff

/prd:update doesn't just append changes — it understands what changed and why:

Semantic diff v1.2.0 → v1.3.0:

  ADDED    Rate limiting requirements (3 acceptance criteria)
  REVISED  Token refresh flow — expiry window changed: 24h → 7d
  REMOVED  Session cookie approach (replaced by JWT)
  UNCHANGED Data model, API endpoints, security requirements

This diff is what powers delta handoffs.

Delta Handoff

/prd:handoff produces a focused summary of what changed since the last implementation run. Instead of handing Claude the full PRD every time, it gets a precise delta:

Handoff delta (v1.2.0 → v1.3.0):

  NEW WORK:
  - Implement rate limiter middleware (3 new tests required)
  - Update token expiry from 24h to 7d in auth service

  REMOVE:
  - Delete session cookie handler (replaced — see JWT module)

  UNCHANGED — no action needed:
  - Data model, user stories, error codes

This is what makes Ralph Loop so much more reliable on evolving projects.

Task Registry

tasks.md is auto-generated and kept in sync with your PRDs:

# Task Registry

## prd-001 · Auth System (v1.3.0)

- [x] JWT token generation
- [x] Supabase RLS policies
- [ ] Rate limiter middleware ← added in v1.3.0
- [ ] Token expiry update: 24h → 7d ← changed in v1.3.0
- [ ] Remove session cookie handler ← deprecated in v1.3.0

Last synced: 2026-03-20T14:32:00Z

Network Map Auto-Sync

/prd:network-map renders your PRD dependency graph as an interactive HTML file. With auto-sync enabled, it regenerates whenever a PRD changes.

docs/network-map.html  ← open in browser, zoom, click nodes

🔍 Project Onboarding

/onboard solves a real problem: dropping into an unfamiliar codebase (or coming back to your own after months away) and needing to get up to speed fast. In v0.15.0, the onboard command was refactored from 578 to 202 lines — 6 agent specs now live in dedicated files under system/agents/.

How It Works

Run /onboard in any project directory. Effectum spawns 6 parallel analysis agents, each with a specific lens:

Self-Test Loop (7 Tests)

After analysis, Effectum runs a 7-point self-test loop to verify its own understanding is correct:

1. Can it explain the main data flow end-to-end?
2. Can it identify all entry points to the system?
3. Can it describe every database table and its purpose?
4. Can it list every external API the project calls?
5. Can it find where authentication is enforced (and where it's missing)?
6. Can it predict where a specific type of bug is most likely to occur?
7. Can it identify what would break if a specific module were removed?

If any test produces an uncertain answer, it re-runs targeted analysis before continuing.

Output

Three artifacts, auto-generated:

docs/
├── onboarding/
│   ├── architecture.md      ← How the system is structured
│   ├── data-model.md        ← All entities, schemas, RLS
│   ├── api-surface.md       ← All endpoints documented
│   ├── test-coverage.md     ← Coverage map + gaps
│   ├── security-audit.md    ← Auth flows + risks
│   └── dependencies.md      ← Package health report
├── prds/
│   └── [feature-area].md    ← One PRD per major feature area
└── network-map.html         ← Interactive dependency visualization

/onboard:review re-runs a lightweight version after significant changes.

[!TIP] Use /onboard before starting a Ralph Loop on an unfamiliar codebase. It gives Claude the context it needs to make good decisions autonomously.

🧠 Foundation

25 Agent Specializations

Effectum ships with pre-configured agent roles. Each has a distinct behavior profile, toolset, and communication style appropriate to its function:

Each specialization is defined in system/agents/ and composed from shared skills.

43+ Skills

Skills are reusable capability blocks that agent specializations are composed from:

Foundation Hooks (Always Active)

Three hooks run on every Claude Code session, regardless of configuration:

These can't be disabled by mistake. They're the safety net.

📑 YAML Frontmatter

All 42 command files now include YAML frontmatter with machine-readable metadata:

---
name: "Design"
description: "Generate a structured DESIGN.md visual specification for frontend projects."
allowed-tools: ["Read", "Write", "Bash", "Glob", "Grep"]
---

This enables better context selection by Claude Code — each command declares exactly what tools it needs and what it does, reducing token waste and improving command routing.

Command Next Steps

Every command now shows contextual next steps after completion. The suggestions respect your autonomy level — conservative mode shows approval steps, while full autonomy mode suggests the next automated action.

🔌 Extensibility

Effectum is built to be extended. Everything is defined in JSON — no code changes needed.

JSON-Based Tool Definitions

Add new workflow commands by dropping a JSON file into system/tools/:

{
  "name": "db-migrate",
  "description": "Run and verify database migrations safely",
  "trigger": "/db-migrate",
  "agent": "engineer",
  "steps": [
    "backup current schema",
    "run migration",
    "verify integrity",
    "run post-migration tests"
  ],
  "quality_gates": ["build", "tests"]
}

JSON-Based Detection Rules

Extend stack auto-detection without touching the configurator:

{
  "name": "remix",
  "detect": {
    "files": ["remix.config.js", "remix.config.ts"],
    "package_deps": ["@remix-run/node"]
  },
  "maps_to": "nextjs-supabase",
  "overrides": {
    "build_command": "remix build",
    "test_command": "vitest run"
  }
}

Community Presets + Blocks

Presets and blocks are shareable. Drop a preset.json into system/stacks/community/ and it appears in the configurator automatically.

Pull requests for new stacks, presets, and detection rules are especially welcome. The goal is to have every common stack covered out of the box.

🆚 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.

On IDE tools (Kiro, Cursor, etc.): If you're happy in your IDE, great — stay there. Effectum is for developers who want a Claude Code-native, terminal-first workflow that doesn't require switching editors or agreeing to opaque pricing models.

On AGENTS.md: Effectum supports both CLAUDE.md (default) and AGENTS.md (the emerging multi-agent standard adopted by GSD 2.37+). Use --output-format agents-md or --output-format both to generate a tool-agnostic project instruction file alongside your Claude Code config.

Backwards compatibility: Existing Effectum projects continue working unchanged with CLAUDE.md. You do not need to migrate. AGENTS.md support is additive: choose claude-md, agents-md, or both. If an AGENTS.md already exists in your repo, Effectum detects it and updates that file automatically.

🎨 Stack Presets

Six full presets. Eight quick add-ons. Detected automatically from your project files.

Full Presets

Quick Presets (Add-Ons)

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.
• Onboarding quality depends on codebase legibility — heavily minified, obfuscated, or machine-generated code produces lower-quality analysis.
• 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.
• Delta handoffs accumulate — on very long-lived projects with many spec revisions, the changelog can grow large. Periodic archival is on the roadmap.

📁 Project Structure

effectum/
│
├── system/                          The installable workflow
│   ├── configurator/                Stack detection + setup recommender
│   ├── templates/                   CLAUDE.md, settings, guardrails (parameterized)
│   ├── commands/                    31 workflow commands (with YAML frontmatter)
│   │   └── README.md               Command index by category
│   ├── agents/                      25 agent specializations
│   ├── skills/                      43+ reusable skill blocks
│   ├── tools/                       JSON-based tool definitions
│   ├── stacks/                      6 full presets + community/
│   │   └── community/               Drop JSON presets here
│   ├── detection/                   JSON-based auto-detection rules
│   └── hooks/                       Foundation hooks (always active)
│
├── workshop/                        PRD lifecycle tools
│   ├── knowledge/                   Reference guides for spec writing
│   ├── templates/                   PRD + frontmatter templates
│   ├── tasks/                       Auto-generated task registry (tasks.md)
│   └── projects/                    Your spec projects (per branch)
│
├── docs/                            Documentation
│   ├── workflow-overview.md
│   ├── configurator-guide.md
│   ├── prd-lifecycle.md
│   ├── onboarding-guide.md
│   ├── customization.md
│   └── troubleshooting.md
│
├── CLAUDE.md                        Makes Claude understand this repo
├── CHANGELOG.md                     Version history
└── README.md                        You are here

📚 Documentation

❓ FAQ

🤝 Contributing

The most impactful areas:

• 🎨 Stack presets — Add Laravel, Rails, Bun, .NET, etc. (Rust+Actix already added!)
• 🔌 Detection rules — Better auto-detection for more project types
• 🔧 Workflow commands — Improve or add new ones
• 📚 Knowledge base — Better examples, more techniques
• 🌍 Documentation — Clearer guides, translations