JSPM

Describe what you want. Get production-ready code.

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

Quick Start · Command Spheres · 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. That release introduced what is now effect:dev:diagnose for post-mortem analysis, effectum:init for domain context, and effectum:explore for parallel brownfield mapping. Plus sentinel-based CLAUDE.md splitting so your project context survives updates.

v0.17.0 is the Apple-like clarity release. New users got /effectum as a starting point and what is now effect:next as a smart router that reads project state and tells you exactly what to do. Human-language aliases for run, stop, save, diagnose, and explore made the daily vocabulary more intuitive. It also cleaned up earlier namespace transitions and fixed 12 journey bugs found by 6 parallel code analysis agents.

v0.18 is Namespace Clarity. Effectum now separates commands into two clear spheres: effectum:* for system, setup, and meta work; effect:* for the actual software pipeline. effectum:status gives you a project-health dashboard, effect:prd:* owns the PRD lifecycle, and effect:dev:* owns implementation. /effectum stays the front door. /ralph-loop stays forever as the brand alias for effect:dev:run.

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

# Check project health and installation
effectum:status

# Onboard an existing codebase
effectum:onboard

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

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

[!NOTE] Upgrading from v0.17? All old names work as deprecated aliases until v0.20.

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
/effectum:setup ~/my-project

📦 What's Included

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

✨ Command Spheres

Effectum now has a cleaner mental model.

effectum:* — System Sphere

Use these before or around development. They set up the environment, understand the codebase, and tell you the current state.

effect:* — Pipeline Sphere

Use these while building. They move a feature from idea to spec to production-ready code.

[!TIP] Old names still work until v0.20, but the documentation now uses the canonical v0.18 namespace everywhere.

🎯 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["effect:dev:plan\nAnalyze & Plan"]
    D --> E["effect:dev:tdd\nTests → Code"]
    E --> F["effect:dev:verify\nQuality Gates"]
    F --> G["effect:dev: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

The namespace is now simple: System with effectum:*, Pipeline with effect:*, and /effectum as the entry point.

System Commands (effectum:*)

Pipeline Commands (effect:*)

PRD Pipeline (effect:prd:*)

Dev Pipeline (effect:dev:*)

Standalone Pipeline Commands

[!TIP] See the full Command Index for all commands organized by sphere and namespace.

effect:dev:run — Build while you sleep

[!IMPORTANT] This is the most powerful feature.

effect:dev:run is the canonical command. /ralph-loop remains a permanent alias and will never be removed.

effect:dev:run "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.

The 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

effect:dev:diagnose — Post-mortem diagnosis

When the autonomous loop stops unexpectedly — due to stuck detection, a context budget stop, or an incomplete run — effect:dev:diagnose gives you a clear picture of what happened.

effect:dev:diagnose

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 effect:dev:run on a new project, or before onboarding a Claude Code session to an existing domain.

effectum:explore — Parallel brownfield analysis

effectum:explore 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/:

effectum:explore

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

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

effectum:status — Project dashboard

Open a project and want instant orientation? effectum:status gives you a read-only dashboard of the current state.

effectum:status

It summarizes:

• installed Effectum version
• detected stack and autonomy level
• CLAUDE.md project context
• PRD inventory and status
• last loop run and health signals

If something is wrong — a recent STUCK.md, an incomplete handoff, missing installation — it tells you immediately and points to the next action.

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

Three mechanisms make the 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 effect:dev:diagnose to analyze the handoff, then effect: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 iterations on the same problem. Use effect:dev:diagnose 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 effect:dev:diagnose 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/.

effect:dev:verify — Every quality gate, every time

🎨 Design System Generation

effect: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).

effect:prd:new → PRD approved → effect:design → DESIGN.md generated → effect:dev:plan → effect:dev:run

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 effect:dev: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)
ℹ Namespace migration already applied
ℹ 1 command update available:
    ~ effectum:status
✔ Updated: commands refreshed, CLAUDE.md preserved, aliases kept for compatibility

📦 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

effect: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

effect: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 the autonomous 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

effect: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

effectum: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.

How It Works

Run effectum: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

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

[!TIP] Use effectum:onboard before starting effect:dev:run 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 command files include YAML frontmatter with machine-readable metadata:

---
name: "Effect 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.
• Autonomous 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/                    Command system with namespaces
│   │   └── README.md                Command index by sphere
│   ├── 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