🤖 Chappie

A man... in a van...

chappie is a CLI that turns a repository into an automated build machine. Design a feature with /brainstorming, then chappie execute kicks off a wave-based agent pipeline: tests get written first, builders implement until they pass, a reviewer gates every commit, and a PM writes the sprint summary when it's done.

Progress is logged wherever you want — GitHub Issues, a local Markdown file, Trello, or multiple at once. Every run has a full log.

---

⚙️ How it works

  /brainstorming  →  prd.json
  chappie execute →  pick a progress logger (once, saved to prd.json)
                  →  wave-ordered dependency graph
                       └─ per task:
                            test-writer   (write failing tests)
                            builder(s)    (implement until green)
                            code-reviewer (SHIP IT or CHANGES NEEDED × 6)
                            git-committer (commit on approval)
                            verification  (run shell script, exit 0 = done)
                     pm agent writes sprint summary

  chappie troubleshoot  →  fix agent reads failure logs, patches, resets tasks
  chappie execute       →  resume from where it left off

  chappie sync          →  replay a completed run into GitHub Issues retroactively

Tasks are grouped into waves based on a dependency graph Claude generates before execution starts. Tasks in the same wave run in parallel. You review and optionally adjust the plan before anything runs.

---

📦 Install

git clone https://github.com/your-org/chappie
cd chappie
bun install

Then add an alias to your ~/.zshrc (or wherever you keep aliases):

alias chappie="bun run /path/to/chappie/src/index.ts"

Requires: Bun · Claude Code CLI (claude in PATH, logged in) · GitHub CLI (gh in PATH, authenticated — only needed for the GitHub logger)

---

🚀 Getting started

1. 🛠️ Initialize

Run this once in your project to install the /brainstorming skill into Claude:

chappie init

This drops a skill file at .claude/skills/brainstorming/SKILL.md. Now open Claude in your project directory.

2. 🧠 Brainstorm

In Claude, run:

/brainstorming

You'll go through:

• 🔍 Explore — lateral thinking about what the feature touches
• ❓ Clarify — 3 rounds of focused questions
• 💡 Propose — 3 rounds of distinct solution approaches with tradeoffs
• ✅ Verify — deterministic verification scripts per task

On approval, chappie creates a prd.json, a plan doc, and verification scripts — then commits everything to a feature branch.

3. ▶️ Execute

chappie execute

On first run, chappie asks where to log progress. Your choice is saved to prd.json for future runs:

📋  --logger github     GitHub Issues  (default)
📝  --logger markdown   Local .agentloop/progress.md
🗂️   --logger trello     Trello board
🔀  --logger github,markdown   Multiple loggers at once

You can also pass --logger directly to skip the prompt:

chappie execute --logger markdown
chappie execute --resume              # ↩️  pick up where a failed run left off
chappie execute --branch feat/name   #    specify the branch

chappie reads prd.json, builds a dependency graph, shows you the execution plan, waits for your go-ahead, then runs the pipeline. A live terminal dashboard shows agents working in real time.

4. 🔧 Troubleshoot (optional)

If a run fails, chappie prints inline diagnostics — reviewer feedback or extracted test output — right in your terminal. To auto-fix failed tasks and resume:

chappie troubleshoot    # or: chappie fix

This spawns a fix agent for each failed task, hands it the failure reason and the last 200 lines of the agent log, and asks it to diagnose and patch the issue. Fixed tasks are reset to pending so chappie execute can resume them automatically.

5. 🐙 Sync to GitHub (optional)

If you ran offline, used a different logger, or GitHub issues failed to create, you can replay the entire run into GitHub Issues after the fact:

chappie sync

This creates the epic and task issues if they don't exist, then walks through the saved run state and reconstructs what would have happened in real time: checkboxes get ticked for completed steps, done tasks are closed, failed tasks get a blocked comment with the failure reason, and the PM summary (if one was written) is posted to the epic.

chappie sync is idempotent — safe to run multiple times. It also detects if prd.json contains issue numbers from a different repo and tells you exactly what to do.

---

🤖 The agent team

Agent	Role	Stops when
test-writer	✍️ Writes failing tests before any code exists	Tests don't fail at write time (hard stop)
backend-builder	🔨 Implements code until all task tests pass	Tests pass, or emits BLOCKED: <reason>
frontend-builder	🎨 Same as above for frontend tasks	Same
code-reviewer	🔍 Read-only audit: security, perf, style, full suite	Emits SHIP IT or CHANGES NEEDED: <...>
git-committer	📝 Commits approved work	After commit
pm	📋 Writes sprint summary	After all tasks complete

The review loop retries up to 6 times. If a builder hits BLOCKED:, a lightweight remediation agent diagnoses and attempts a fix before giving up.

All agents are invoked by spawning the claude CLI directly — no Anthropic SDK or API key needed. chappie uses your Claude Code session credentials.

---

📊 Progress loggers

Logger	What it does	Requirements
github	Creates GitHub Issues (epic + per task), ticks checkboxes at each checkpoint, closes issues when done	gh CLI, authenticated, repo with GitHub remote
markdown	Writes a running log to .agentloop/progress.md	Nothing extra
trello	Creates and updates Trello cards on a board	TRELLO_API_KEY + TRELLO_TOKEN env vars

Combine any of them with commas: --logger github,markdown

GitHub logger notes

• Issues are tied to a specific repo. The repo slug is stored in prd.json and verified on every run — if you move a project or change the remote, chappie will tell you rather than silently posting to the wrong place.
• To re-create issues for a new repo, remove the "github" field from prd.json.
• Use chappie sync to create issues retroactively from a saved run.

---

🎛️ Agent customization

Agents are defined as markdown files in .claude/agents/ with YAML frontmatter. chappie ships with defaults; override them by dropping same-named files in your project's .claude/agents/:

---
model: sonnet
tools: Read,Write,Edit,Glob,Grep,Bash
---

Your custom system prompt here...

Available agent names: test-writer, backend-builder, frontend-builder, code-reviewer, git-committer, pm

---

📁 Artifacts produced

Artifact	Location
📄 PRD + logger config	prd.json
📝 Plan document	docs/plans/<feature>.md
🧪 Verification scripts	tests/verification/<feature>/<task-id>.sh
📋 Run logs	.agentloop/logs/
💾 Run state	.agentloop/state.json

---

🔧 Requirements

• 🥟 Bun ≥ 1.0
• 🤖 Claude Code CLI (claude) — logged in and in PATH
• 🐙 GitHub CLI (gh) — authenticated and in PATH (only for the GitHub logger)

---

🤝 Contributing

See CONTRIBUTING.md.

---

📜 License

MIT