In 1928, Ford opened the River Rouge Complex. Iron ore went in one end. Finished cars came out the other. Raw materials to finished product, under one roof.

Rouge is the software version. A product idea goes in. A deployed, tested, monitored application comes out.

Not one-shot code generation. Iterative product development: build, evaluate against external signals, fix, repeat until the quality bar is met. The same loop a good engineering team runs, except it runs overnight while you sleep.

Quick start

npm install -g the-rouge

rouge setup                 # First-time: install dashboard, check prerequisites
rouge dashboard start       # Start the dashboard

How it works

Dashboard

The dashboard is your control plane: real-time project visibility, escalation responses, build logs, milestone progress, and seeding sessions. One process, one port (default 3001; override via ROUGE_DASHBOARD_PORT), auto-opens in your browser. Start it with rouge dashboard start (background) or rouge dashboard (foreground). Global installs ship a prebuilt Next.js standalone server — cold start is ~2s, no dev toolchain required. Pass --no-open to skip the auto-open.

A Slack integration exists in src/slack/ as a notification-only sidecar. It's no longer recommended for new setups — the dashboard is the supported control surface. Existing Slack setups can opt back into the legacy write paths via ROUGE_SLACK_ALLOW_WRITES=1 during the deprecation window. See docs/how-to/slack-setup.md.

The loop

Inspired by Karpathy's AutoResearch. No long-running process. Each phase starts fresh, reads state from the filesystem, does one thing, saves, and exits. Git is the audit trail. The loop iterates as many times as it needs to. There's no fixed limit. It's done when it's done.

Seed — you describe the product. Eight discipline-specific personas run through it (brainstorming, competition, taste, spec, infrastructure, design, legal, marketing). About 10-20 minutes of your time. Then it's autonomous. See a full seeding example.

Build — reads specs, writes code with TDD, deploys to staging. All work happens on a single branch with milestone tags per shipped feature area — no branch-per-story sprawl. State is tracked via a dual ledger: task_ledger.json for task tracking and checkpoints.jsonl for immutable cycle history.

Evaluate — five-lens assessment: test integrity, code review, browser QA, product evaluation, design review. One browser session, three evaluation lenses reading the same observation data. All evaluation prompts write output to cycle_context.json only — they never mutate the task ledger or project state directly. A strict I/O contract keeps evaluation data readable by the analyse phase without side-effects.

Analyse — reads all reports, classifies root causes, decides: fix, advance to the next feature, restructure the architecture, or ship.

The loop runs until all feature areas meet the quality bar. Then it promotes to production and notifies you via the dashboard (or Slack, if configured).

Self-improvement — after each completed product, Rouge reviews its own prompts against what worked and what didn't. Improvement proposals become GitHub issues, run in an isolated git worktree with an allowlist/blocklist, and land as PRs for human review. The running loop never modifies itself.

Linked projects — products can depend on each other. A fleet manager that needs a maps API triggers the maps project to be built first. The project registry tracks what's shipped and what each project provides. Circular dependencies are detected at seed time.

Composable decomposition

This is the core innovation. A timer app needs no decomposition. A fleet management system with trips, vehicles, a dashboard, maps, and a trip simulator needs a completely different approach.

Rouge derives a complexity profile from your spec. Measurements, not categories. How many entities share relationships? How many integrations? How dense is the dependency graph? These measurements activate composable capabilities:

A timer app produces a trivial infrastructure manifest and a single milestone. A fleet management SaaS activates everything: foundation cycles, multi-milestone dependency ordering, integration escalation, linked project resolution. Same system, different measurements.

The capability avoidance problem. Without this, the builder optimises for what it CAN build, not what the product NEEDS. No maps pattern? It substitutes a table of coordinates. Every test passes. The product is useless. Rouge's fix: hard blocking. If maps are needed and the pattern doesn't exist, Rouge blocks and escalates. It either builds the pattern autonomously (researches the API, evaluates scale trade-offs, creates a wrapper) or escalates. When it does build that pattern, it gets added to the catalogue. The next product that needs maps doesn't start from scratch.

The backwards flow. Sometimes the decomposition is wrong. The analysing phase detects the structural issue and inserts a foundation cycle mid-flight, like a startup pivot at a smaller scale. Autonomous when bounded. Escalates when it isn't.

The integration catalogue

Three tiers of patterns that grow as Rouge builds products:

• Stacks — language, framework, runtime (Next.js on Cloudflare, Godot, etc.)
• Services — external services with lifecycle (Supabase, Stripe, Sentry, Counterscale)
• Integrations — code patterns within services (Stripe checkout, Supabase RLS, Sentry error boundary)

Each entry has setup guides, env vars, free tier limits, scale considerations, and working code. The catalogue ships with seed entries and grows as Rouge builds products. When a foundation cycle creates a new integration pattern, Rouge automatically drafts a catalogue entry and opens a PR to contribute it back. Every product Rouge builds potentially makes Rouge better at building the next one.

The Library

Rouge's accumulated design intelligence. Not documentation. Machine-readable context that feeds into every phase.

• Global standards — 15 universal quality heuristics (page load, accessibility, error recovery)
• Domain-specific taste — grows per domain (web apps, APIs, games)
• Learned judgment — accumulated from your feedback. Your Rouge learns your taste.

Taste encoded as testable signals: "page load under 2 seconds," "core tasks in 3 clicks or fewer," "primary content in dominant visual position."

Economics

Set budget_cap_usd in rouge.config.json before any real build. The loop escalates when the cap is hit. Without a cap, a misconfigured run can burn through thousands of dollars of API credits before you notice.

Rouge runs on your Claude Code subscription or via direct API keys. Each phase consumes either session time (subscription) or token credits (API). Costs vary widely with product complexity, evaluation cycles, and how many fix stories the loop generates — these are rough order-of-magnitude estimates, not guarantees:

Rouge runs on Opus by default for every phase except milestone-check (a bookkeeping step that runs on Sonnet). Override per-phase via rouge.config.json.model_overrides.

Run rouge cost <project> for a live estimate during a build. Infrastructure on free tiers (Cloudflare, Supabase, Vercel hobby) typically adds nothing for small projects.

Built with

• AI Factory by Greg Jackson — the factory that built Rouge
• GStack by Garry Tan — Rouge uses GStack's headless browser for milestone evaluation, product walks, and QA
• Superpowers by Jesse Vincent — engineering discipline skills
• OpenSpec — product specification and task management
• Excalidraw — hand-drawn diagrams
• Supabase — database, auth, and storage for products Rouge builds
• Cloudflare Workers / Vercel — deployment targets for products Rouge builds

Getting started (detailed)

npm install -g the-rouge

Or clone from source:

git clone https://github.com/gregario/the-rouge.git
cd the-rouge && npm install

Prerequisites

• Claude Code CLI — the execution engine for every phase

  npm install -g @anthropic-ai/claude-code

  Requires a Claude subscription (Pro or Max). Verify: claude --version
• Node.js 18+ — launcher, dashboard, scripts
• Git — every phase commits
• GStack — required for web product evaluation (browser QA, product walk, design review). Install: git clone --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup. Verify: rouge doctor

Optional:

• Wrangler CLI — Cloudflare Workers deployment
• Supabase CLI — database, auth, storage
• Vercel CLI — Vercel deployment

Run rouge doctor to verify all prerequisites are installed.

First-time setup

rouge setup                 # Install dashboard, check prerequisites, create dirs

This runs rouge doctor, installs the dashboard, and prepares the projects directory. Everything else is optional.

Start the dashboard

rouge dashboard start       # Background mode (persistent, survives terminal close; auto-opens browser)
rouge dashboard status      # Check if running
rouge dashboard stop        # Stop the dashboard
rouge dashboard             # Foreground mode (Ctrl+C to stop)
rouge dashboard --no-open   # Skip the auto-open

The dashboard is the primary control plane: real-time project visibility, escalation responses, build logs, milestone progress, and seeding sessions. It runs on port 3001 by default (override via ROUGE_DASHBOARD_PORT) and reads live project state from ~/.rouge/projects/. The actual URL is printed when the dashboard starts.

Set up integrations

rouge setup supabase
rouge setup stripe
rouge secrets list

Secrets stored in your OS credential store (macOS Keychain, Linux secret-service, Windows Credential Manager). Rouge never sees the values.

Alternative: Slack notification-only sidecar (legacy)

The Slack control plane is deprecated. Code stays in src/slack/ as a notification-only sidecar — incoming write commands are skipped with a deprecation warning. Existing setups can opt back into the legacy write paths via ROUGE_SLACK_ALLOW_WRITES=1 during the deprecation window. New features and bug fixes land in the dashboard only. See docs/how-to/slack-setup.md.

Build a product

rouge init my-product
rouge seed my-product       # Interactive seeding (~10-20 min)
rouge build my-product      # Start the autonomous loop
rouge status                # Check progress
rouge cost my-product       # See cost estimate

Safety

Safety is deterministic JavaScript, not LLM judgment. Every safety mechanism is enforced in the launcher — pure code that cannot be hallucinated away, argued with, or forgotten by a prompt. The LLM builds; the launcher constrains.

• Blocked commands — rouge-safety-check.sh runs as a PreToolUse hook on every Bash and Write call. Blocks rm -rf /, git push --force to main, production deploys, Stripe live keys, destructive database operations, and writes to safety-critical files
• Deploy blocking — only staging and preview deploys allowed by default. Deploy must succeed (with 3 retries) before milestone evaluation runs. Failed deploy → escalation, not stale evaluation
• Cost caps — per-phase token tracking with cumulative USD budget. The loop escalates when the cap is hit — it does not silently continue
• Spin detection — 3+ zero-delta stories, duplicate story names, or 30 minutes without meaningful progress → escalation. This is what prevented the V2 overnight 12-hour spin
• Milestone lock — promoted milestones are locked in the checkpoint stream. The loop cannot regress to re-build a shipped milestone, even after a crash and restart
• Story deduplication — stories completed in earlier milestones are skipped, not re-executed
• Audit trail — every tool call logged to tools.jsonl; every state transition checkpointed to checkpoints.jsonl. Both append-only
• Self-improvement isolation — Rouge can propose prompt improvements, but changes run in a git worktree with an allowlist/blocklist. The running loop never modifies its own launcher, config, or safety hooks

For common issues, see troubleshooting.

Contributing

See CONTRIBUTING.md.

Integration catalogue entries — service adapters (Tier 2) or code patterns (Tier 3). Each product you build with Rouge can contribute patterns back. All contributions reviewed by maintainers. This is the fastest way to expand what Rouge can build.

Stack support — new deployment targets, frameworks, runtimes. This is how Rouge goes from "builds web apps" to "builds tech products."

Bug reports and prompt improvements — if Rouge produces bad output, the fix is usually in a prompt. PRs welcome.

What's next

Rouge builds products. The architecture is stack-agnostic — what it can build depends on what stacks and integrations are in the catalogue, and that surface grows with every product shipped and every community contribution.

Current priorities:

• More stacks — Vercel, Docker Compose, additional database providers, framework support beyond Next.js
• Dashboard polish — the dashboard ships as the primary control plane; next steps are live SSE event streaming and the onboarding wizard
• Community patterns — every product Rouge builds can contribute integration patterns back to the catalogue, making Rouge better at building the next one

License

MIT. Use it for whatever you want — personal projects, commercial products, hosted services, reselling, anything. The only thing the license asks is that you keep the copyright notice in copies you distribute.

If Rouge is useful to you, sponsorship helps fund continued development, but it's not required.