beat

English | 繁體中文

Beat

Think first, code second. Beat is a Claude Code plugin that makes you write Gherkin scenarios before touching code — then drives TDD implementation from those specs.

The Problem

You: "Add user login"
Claude: *writes 400 lines, misses rate limiting, 
        tests are an afterthought, edge cases surface in PR review*

With Beat

You: /beat:design add-user-login

Beat generates:
┌─────────────────────────────────────────────────┐
│ Feature: User Login                             │
│                                                 │
│   Scenario: Successful login with valid creds   │
│   Scenario: Invalid password shows error        │
│   Scenario: Account locked after 5 attempts     │
│   Scenario: Session expires after 30 min idle   │
│   Scenario: Login from new device sends email   │
└─────────────────────────────────────────────────┘

You: /beat:apply

Beat implements each scenario with TDD:
  ✗ Write test for "Account locked after 5 attempts"  (red)
  ✓ Implement lockout logic                            (green)
  ✓ Refactor                                           (clean)
  → Next scenario...

Every scenario gets a test. Every test links back to the spec. Nothing slips through.

Install

From the plugin marketplace:

/install kirkchen/beat

Or locally:

claude --plugin-dir /path/to/beat

On Codex:

codex plugin marketplace add https://github.com/kirkchen/beat

Then in the Codex UI plugins panel, install Beat. See docs/INSTALL-CODEX.md for the full flow and the AGENTS.md snippet that replaces the SessionStart hook (Codex doesn't support hooks).

Then, in your project:

/beat:setup    # Detects your stack, creates beat/config.yaml

Quick Start — 3 Commands

For most changes, this is all you need:

/beat:design fix-expired-session    # Describe the behavior change → generates Gherkin
/beat:apply                         # TDD: test → implement → next scenario
/beat:archive                       # Sync features to living docs, clean up

For complex changes, add /beat:verify before archive — it dispatches an independent agent to validate your implementation against the specs, catching gaps that the implementer's own context would miss.

Beat scales up when you need it (see Full Pipeline), but the simple path works for everyday fixes and small features.

Already Have Code? Start with Distill

Most BDD tools only work for new code. Beat works backwards too — extract Gherkin from your existing codebase:

/beat:distill src/billing/          # Reads your code, generates feature files

@distilled @behavior @happy-path
Scenario: Monthly billing adjusts for short months
  Given a subscription billing on the 31st
  When February billing cycle runs
  Then the charge date adjusts to the 28th

Now you have living documentation of what your system actually does. Next time you change billing logic, Beat knows what behavior exists and what tests to write.

This is the recommended entry point for existing projects. Distill first, then use the full pipeline for future changes.

Full Pipeline

explore → design → plan → apply → verify → archive

Command	What it does	When to use
/beat:explore	Think through ideas, no code	Unclear requirements, brainstorming
/beat:design	Create change + generate specs	Starting any change
/beat:plan	Task breakdown + multi-role review	Complex features (5+ scenarios)
/beat:apply	TDD implementation per scenario	Every change
/beat:verify	Independent verification against specs	Before shipping complex changes
/beat:archive	Sync features + archive change	After every change

Pick your path by size:

Change size	Commands	Example
Bug fix	design → apply → archive	Fix off-by-one in date calc
Feature	design → apply → verify → archive	Add password reset flow
Large feature	design → plan → apply → verify → archive	Payment processing system

Every change lives in beat/changes/<name>/ with a status.yaml tracking where you are.

What Beat Generates

Each change can include these artifacts (you choose which):

Artifact	Default	Purpose
features/*.feature	Included	Gherkin scenarios — the spec
proposal.md	Optional	Why this change exists
design.md	Optional	Technical decisions
tasks.md	Optional	Implementation plan

For purely technical changes (refactoring, tooling, deps), you can skip Gherkin entirely and drive from proposal.md instead.

Living Documentation (three layers)