# @agentpulselabs/pulse

**Portable, contract-enforced build discipline for coding agents.**

Pulse is a *discipline engine* — a phase state machine (Discovery → Stories → Architecture → Build → Deliver)
+ a pluggable architecture **contract** + JSON schemas + a **validator** + a **gate runner**. It ships the
**brain**; your coding agent (Claude Code, Cursor, Codex, Windsurf, Cline) provides the **model, the UI, and
the human**.

The point: an AI agent driving Pulse produces code that is *provably* inside your platform's architectural
rules — because "done" is a deterministic gate command (`npm run check`), and a proposal that breaks an
invariant is **rejected by code**, not by review.

> Formerly the Claude-Code-only "SEAP". Pulse ports the method to any host via MCP + a CLI plugin.

---

## How it works — brain vs. nervous system

```
   @agentpulselabs/pulse (BRAIN, pure)          your coding agent (NERVOUS SYSTEM)
   · phase state machine                     · runs the LLM (its model)
   · contract (the rules)          ── MCP ──▶ · renders progress (native UI)
   · schemas + validator          ◀── CLI ── · holds the human gate
   · gate runner (npm run check)             · edits files · owns PM-tool MCPs
```

Pulse **never calls an LLM.** `pulse_next` emits a *work-list* (prompts + a JSON schema per task); your agent
runs them on its model; `pulse_submit` validates the results against the schema **and** the contract;
`pulse_gate` locks decisions and advances; `pulse_verify` runs the gate command. The discipline travels; the
reasoning is the host's.

## State lives in the repo (`.pulse/`)

Durable, git-tracked, travels across agents and humans, validatable offline:

```
.pulse/
  pulse.config.json     which contract governs + the gate command
  engagement.json       phase · status
  board.json            THE project board (machine truth)
  BOARD.md              rendered kanban (regenerated — don't hand-edit)
  STATUS.md             one-glance dashboard
  sync.json             optional PM-tool sync intent (Jira/GitHub/Asana)
  decisions/product/    human decisions
  decisions/architecture/  platform-dictated ADRs (each cites the invariant)
  design/               working design docs (graduate to docs/DESIGN_*.md on gate)
```

## Two ways to drive it

**1. MCP (primary — every agent):** run the `pulse-mcp` stdio server. Requires the optional peer dep:

```bash
npm i @agentpulselabs/pulse @modelcontextprotocol/sdk
```

Register it with your agent (example — Claude Code `.mcp.json`):

```jsonc
{ "mcpServers": { "pulse": { "command": "npx", "args": ["pulse-mcp"] } } }
```

Tools: `pulse_start · pulse_next · pulse_submit · pulse_gate · pulse_verify · pulse_status ·
pulse_board_update · pulse_claim · pulse_sync`.

**2. CLI plugin (fallback):** the published `agentpulse` CLI can install a `pulse` topic:

```bash
agentpulse plugins install @agentpulselabs/cli-plugin-pulse
agentpulse pulse start --requirements "…"
```

(The plugin is a thin shim that `import`s this core — see the parent design doc §4b.)

## The contract is pluggable

```jsonc
// .pulse/pulse.config.json
{ "contract": "agentpulse", "gates": "npm run check && npm run check:types" }
```

- `contract: "agentpulse"` → the built-in reference contract (10 non-negotiables + 8 invariants + deep checks
  for table categories, migration-free schema, secrets-in-settings, no-DB-blobs).
- `contract: "generic"` → point at your own `pulse.contract.md` + a `gates` command. Pulse enforces
  schema-validity + the DAG + your gate; add your own deep checks with a JS contract (advanced).

## What Pulse guarantees (and what it doesn't)

**Guarantees (deterministic):** schema validity, contract-invariant compliance, an acyclic work-item DAG, and
that "done" = your gate command exited 0. Never delegated to an LLM.

**Does NOT guarantee:** *insight*. Reasoning quality is your host model's. On a weak model, Discovery is
shallow — Pulse keeps it *correct*, not *brilliant*.

## Develop

```bash
npm test        # node --test — pure, no network, no MCP SDK needed
```