bc-harness

Beer and Code Harness (bc-harness)

🇧🇷 Documentação em português

A Claude Code plugin with commands, agents, and scripts that take a project from idea to implementation in a structured way: formal specification, phased planning, and autonomous execution with mechanical validation — while keeping a human in control at every decision point.

The harness is stack-agnostic: language, framework, commands, and conventions are defined by the project's own documents (AGENTS.md, CLAUDE.md, the .spec/ chain), never by the harness.

Workflow overview

 IDEA                                              CODE
   │                                                 ▲
   ▼                                                 │
 /init:project-description  ──┐                      │
 /init:user-stories           │  init chain          │
 /init:database-schema        │  (.spec/init/)       │
 /init:project-phases       ──┘                      │
   │                                                 │
   │            /plan "<feature description>"        │
   │            (.spec/features/<slug>/)             │
   ▼                                                 │
 project-phases.md  or  PHASES.md ────────► scripts/ralph.sh
                                            (autonomous execution
                                             with 4 gates)

 /ai-context ─► AGENTS.md + docs/agents/*  (documents the ALREADY implemented
                                            code; feeds /plan and ralph)

Three independent pipelines that fit together:

1. /init — from zero to a project build plan (description → user stories → schema → phases).
2. /plan — from a feature description to a formal SPEC + phased plan, ready for execution.
3. ralph.sh — executes any phase document autonomously, one fresh agent session per phase, with mechanical gates and one commit per completed phase.

Cross-cutting: /ai-context keeps the context tree (AGENTS.md, CLAUDE.md, docs/agents/*.md) in sync with the real code.

Installation

This repository is a Claude Code plugin (.claude-plugin/plugin.json). Install it via marketplace/local path according to your plugin setup:

/plugin install bc-harness

Commands are namespaced: /bc-harness:init, /bc-harness:plan, etc. (abbreviated without the namespace throughout this document).

ralph.sh is a standalone bash script — copy or reference scripts/ralph.sh and run it directly in the target project's repository.

ralph.sh prerequisites:

• Codex engine: npm install -g @openai/codex + OPENAI_API_KEY
• Claude engine: npm install -g @anthropic-ai/claude-code + ANTHROPIC_API_KEY
• Root of a git repository with a clean working tree

Commands

/init — init chain router

Shows the state of the .spec/init/ artifacts (present / absent / stale) and invokes the next command in the chain (one hop per run — re-run /init to advance). Writes nothing itself; all authoring lives in the invoked init:* command.

The chain, in order:

#	Artifact	Command	Inputs
1	.spec/init/project-description.md	/init:project-description	— (head of chain)
2	.spec/init/user-stories.md	/init:user-stories	project-description
3	.spec/init/database-schema.md	/init:database-schema	description + stories
4	.spec/init/project-phases.md	/init:project-phases	description + stories + schema
—	.spec/init/design/	manual (optional)	—

Every generated artifact carries a stamp of its inputs on line 3 (file@sha256:<12 chars>). If an input changes later, /init detects it and reports the downstream artifact as stale — re-running the corresponding command is upsert-safe: it interviews only about the deltas and refreshes the stamp.

• /init:project-description — interviews the developer, discovers the stack, and produces a structured project description.
• /init:user-stories — derives structured, testable user stories from the description.
• /init:database-schema — derives a suggested database schema in DBML.
• /init:project-phases — plans the build into numbered, agent-ready phases with tasks, acceptance criteria, and feature tests. This is ralph.sh's default input. Reads .spec/init/design/ when present (screen/component refs).

/plan — feature planning pipeline

/plan "<feature description or path to a description file>"

Produces, under .spec/features/<slug>/: