Spellcaster

A structured workflow for AI-assisted coding that thinks before it builds, tracks what it's doing, and asks before it acts.

# Clone the repo
git clone https://github.com/rbgit/spellcaster.git
# Copy into your project's .claude directory
cp -r spellcaster/skills your-project/.claude/
cp -r spellcaster/agents your-project/.claude/

Your project should look like:

your-project/
├── .claude/
│   ├── skills/
│   │   └── SKILL.md
│   └── agents/
│       └── claude-codex-planner.md
├── src/
└── ...

Developed for Claude Code, but works with any AI coding agent that has access to Claude LLM:

• Cursor Agent
• Cline
• Amp
• Clawd
• GitHub Copilot CLI

Executes the RALPH Loop - a structured build workflow that breaks your project (expects a PRD but you can create one with Claude-Codex-Planner agent below) into Epics and Tasks, then iterates through Research, Code, Review, and Commit phases.

Multi-AI planning that pairs Claude with OpenAI Codex in structured dialogue. They challenge assumptions, explore tradeoffs, and produce validated architecture before you write any code.

flowchart TB
    subgraph phase1 ["Phase 1: PLAN"]
        A["Your idea"] --> B["Claude-Codex Planner"]
        B --> C["Claude + Codex dialogue"]
        C --> D["Challenged assumptions"]
        D --> E["Validated architecture"]
    end

    subgraph phase2 ["Phase 2: BUILD"]
        E --> F["Spellcaster breaks it into tasks"]
        F --> G["Beads tracks everything"]
        G --> H["RALPH Loop executes"]
        H --> I["Working software"]
    end

    style phase1 fill:#1a1a2e
    style phase2 fill:#16213e

Each task runs through four phases:

flowchart LR
    R["Research"] --> A["Code"] --> L["Review"] --> P["Commit"]
    P -.->|"Next task"| R

Repeat until Epic complete. Then ask: continue or stop?

Every task lives in Beads — your single source of truth.

bd ready          # What can I work on?
bd show task-1    # Show me the details
bd list           # Everything at a glance

Opus orchestrates subagents, with progress.md preserving state between sessions:

flowchart TD
    O["Opus (Orchestrator)"]
    O --> R["Researcher"]
    O --> C["Coder"]
    O --> V["Reviewer"]
    O --> M["Committer"]

    R & C & V & M --> B["Beads (task details)"]
    R & C & V & M --> P["progress.md (handoffs)"]
    P -.->|"next session"| O

How it works:

• Opus dispatches tasks to specialized subagents
• Subagents track work in Beads, write key findings to progress.md
• progress.md lets Opus resume context in the next session

progress.md enables multi-session work:

• Stop anytime — progress.md captures where you left off
• Next day, the orchestrator reads progress.md and continues
• Use /clear frequently to avoid context rot in long sessions

• Claude Code installed (or compatible agent)
• A project to work on

git clone https://github.com/rbgit/spellcaster.git
cp -r spellcaster/skills your-project/.claude/
cp -r spellcaster/agents your-project/.claude/

npm install -g @beadorg/bd
# OR
cargo install bd

# Initialize in your project
cd your-project
bd onboard

For multi-AI code reviews:

# Install Codex CLI
npm install -g @openai/codex

# Set your API key
export OPENAI_API_KEY="sk-..."

Not required — Spellcaster works great with just Claude.

Start Claude Code in your project, then:

You: I want to build a real-time notification system.
     Can we plan this with claude-codex-planner?

Claude: [Launches multi-AI dialogue]
        [Claude and Codex debate approaches]
        [Produces validated architecture]

You: /spellcaster

Claude: === Spellcaster Session Setup ===

        What would you like to build?

You: Implement the notification system we just planned

Claude: Creating Epic and tasks in Beads...
        Starting RALPH Loop...

        === Research Phase ===
        [Explores codebase, identifies patterns]

        === Code Phase ===
        [Implements based on research]

        === Review Phase ===
        [Runs tests, checks quality]

        === Commit Phase ===
        [Saves work with clear message]

        Task complete. Moving to next...

# Beads commands
bd ready              # Show unblocked tasks
bd show <id>          # Task details
bd list               # All tasks
bd update <id> --status complete

# Start Spellcaster
/spellcaster

# Start planning
"Let's plan this with claude-codex-planner"

Inspired by and built upon:

• RALPH Loop — The Research-Code-Review-Commit workflow pattern
• Beads — Task management system for AI agents
• OpenAI Codex Execution Plans — Multi-agent orchestration patterns

MIT