slag

Smelt ideas, skim the bugs, forge the product.

Bash orchestrator for AI-powered development. Breaks requirements into S-expression ingots and forges them via Claude agents with automatic retry and proof-based verification.

▱▱▱▰▰▰▰ cold → hot → pure

Quick Start

# install curl -fsSL https://slag.dev/slag -o /usr/local/bin/slag && chmod +x /usr/local/bin/slag

# forge slag "Build a REST API with auth and rate limiting"

⚠ Runs Claude with --dangerously-skip-permissions. Use at your own discretion.

Pipeline

  PRD.md                                          PROGRESS.md
  (ore)                                             (ledger)
    |                                                 ^
    v                                                 |
 +-----------+    +--------------+    +--------+    +-------+
 | SURVEYOR  |--->| FOUNDER      |--->| FORGE  |--->| ASSAY |
 | analyze   |    | cast ingots  |    | strike |    | report|
 +-----------+    +--------------+    +--------+    +-------+
    |                    |                    |
    v                    v                    v
 BLUEPRINT.md        PLAN.md             git commits
 (analysis)        (s-expr ingots)      (per ingot)

Forge Loop

 PICK ORE                       PARALLEL ANVILS
    |                           +---------+---------+
    v                           |         |         |
 :solo t? ----yes-----> ANVIL 1   ANVIL 2   ANVIL 3
    |                      |         |         |
    no                     v         v         v
    |                   (each anvil is independent subshell)
    v
 SELECT SMITH by :skill + :grade
    |
    |  web/frontend --> +Playwright
    |  grade >= 3   --> plan mode
    |  default      --> base tools
    v
 STRIKE (claude invocation)
    |
    v
 CMD (extract & run shell command)
    |
    v
 PROOF (run :proof shell command)
    |
    +----- pass ----> :forged  + git commit
    |
    +----- fail ----> :heat++ retry with slag feedback
    |
    +----- max -----> :cracked + halt

Four Phases

1 SURVEYOR

Deep analysis with plan mode. Reads PRD.md (ore), produces BLUEPRINT.md with architecture, dependency graph, risk assessment, and forging sequence. Self-iterates to resolve any ambiguity.

2 FOUNDER

Casts S-expression ingots from the blueprint. Each ingot has an ID, complexity grade, skill tag, proof command, and work description. Outputs PLAN.md as the crucible.

3 FORGE

Strikes each ingot via Claude. Solo ingots run on parallel anvils (up to 3). Selects smith by skill and grade. Retries with slag feedback on failure. Commits on success.

4 ASSAY

Final quality report. Shows forged/cracked counts, temperature bar, and identifies any cracked ingots. Exits 0 on full forge, 1 if any ingot cracked.

Design Decisions

Why S-Expressions?

S-expressions are single-line, grep/sed parseable, require zero dependencies, and survive bash string handling. Every ingot is one line in PLAN.md. The entire orchestrator can manipulate state with sed_i without any JSON/YAML parser. Fields are keyword-prefixed (:id, :status) making them unambiguous to extract with pattern matching.

Why Parallel Anvils?

Independent ingots (:solo t) run concurrently in background subshells, up to MAX_ANVILS=3. This gives 3x throughput for foundation tasks that have no dependencies. Each anvil gets its own smith process. Sequential ingots (:solo nil) run one at a time after parallel work completes.

Why Proof-Based Verification?

Every ingot carries a :proof field containing a shell command. Exit code 0 means pass, anything else means fail. No human review needed. Proofs are concrete: "test -f file", "npm test", "grep -q pattern file". This enables fully autonomous forging with machine-verifiable quality gates.

Why Self-Iteration?

When a surveyor or founder output contains questions, slag detects them and feeds the output back with instructions to resolve autonomously. Up to 3 rounds. This prevents the forge from stalling on ambiguity. The AI is instructed to make expert decisions rather than ask for clarification.

Why Metallurgical Metaphor?

Unambiguous vocabulary that maps naturally to the pipeline. Ore (raw input) is surveyed, cast into ingots, heated in a forge, and either becomes forged steel or cracked waste. Every term has exactly one meaning. The temperature gradient (cold → hot → pure) maps to progress from unstarted to complete.

Ingot Examples

Field Reference

Field	Values	Meaning
`:id`	"i1", "i2", ...	Unique ingot identifier
`:status`	ore \| molten \| forged \| cracked	Lifecycle state
`:solo`	t \| nil	Can run in parallel (t) or must be sequential (nil)
`:grade`	1-5	Complexity level; grade ≥ 3 uses plan mode
`:skill`	web \| api \| cli \| default	Selects smith tools/plugins
`:heat`	0-N	Current retry attempt
`:max`	5-8+	Max retries before cracking
`:proof`	shell command	Acceptance test (exit 0 = pass)
`:work`	string	Task description for the smith