@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:

npm i @agentpulselabs/pulse @modelcontextprotocol/sdk

{ "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:

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

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

The contract is pluggable

// .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

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