{"_id":"@agentpulselabs/pulse","name":"@agentpulselabs/pulse","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@agentpulselabs/pulse","version":"0.1.0","description":"Portable, contract-enforced build discipline for coding agents (Claude Code, Cursor, Codex, …). A pure phase state machine + pluggable architecture contract + validator + gate runner. Ships the brain; the host provides the model, UI, and human.","type":"module","license":"MIT","publishConfig":{"access":"public"},"exports":{".":"./src/core/index.js","./mcp":"./src/mcp/server.js"},"bin":{"pulse-mcp":"src/mcp/server.js"},"scripts":{"test":"node --test \"test/**/*.test.js\"","mcp":"node src/mcp/server.js"},"engines":{"node":">=20"},"keywords":["agent","mcp","architecture","discipline","agentpulse","codex","cursor","claude-code"],"peerDependencies":{"@modelcontextprotocol/sdk":">=1.0.0"},"peerDependenciesMeta":{"@modelcontextprotocol/sdk":{"optional":true}},"_id":"@agentpulselabs/pulse@0.1.0","_nodeVersion":"24.18.0","_npmVersion":"11.16.0","dist":{"integrity":"sha512-l4aoBRXh7cUSUQjexeIf7UUU9/0FuA/P1RSMrfMvu8mJn92sohRY5wJdXXUnZdCtPigWr3c6aVvIyXWBe9ewjw==","shasum":"fa34fd865ac7b53f547b8c7a2547e0965779218c","tarball":"https://registry.npmjs.org/@agentpulselabs/pulse/-/pulse-0.1.0.tgz","fileCount":19,"unpackedSize":80062,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCILvlXGzvZYfHqNPyvN94k5gvzvXaD3tIWos+QKvwYLAIgF6zkBbErVjIxd/+B3xawTUdpnQ+ljT5BLrskLhMWWLo="}]},"_npmUser":{"name":"ashishcloud","email":"ashishsujaka@gmail.com"},"directories":{},"maintainers":[{"name":"ashishcloud","email":"ashishsujaka@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pulse_0.1.0_1785737430365_0.03334566669121619"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-03T06:10:30.252Z","0.1.0":"2026-08-03T06:10:30.520Z","modified":"2026-08-03T06:10:30.759Z"},"maintainers":[{"name":"ashishcloud","email":"ashishsujaka@gmail.com"}],"description":"Portable, contract-enforced build discipline for coding agents (Claude Code, Cursor, Codex, …). A pure phase state machine + pluggable architecture contract + validator + gate runner. Ships the brain; the host provides the model, UI, and human.","keywords":["agent","mcp","architecture","discipline","agentpulse","codex","cursor","claude-code"],"license":"MIT","readme":"# @agentpulselabs/pulse\n\n**Portable, contract-enforced build discipline for coding agents.**\n\nPulse is a *discipline engine* — a phase state machine (Discovery → Stories → Architecture → Build → Deliver)\n+ a pluggable architecture **contract** + JSON schemas + a **validator** + a **gate runner**. It ships the\n**brain**; your coding agent (Claude Code, Cursor, Codex, Windsurf, Cline) provides the **model, the UI, and\nthe human**.\n\nThe point: an AI agent driving Pulse produces code that is *provably* inside your platform's architectural\nrules — because \"done\" is a deterministic gate command (`npm run check`), and a proposal that breaks an\ninvariant is **rejected by code**, not by review.\n\n> Formerly the Claude-Code-only \"SEAP\". Pulse ports the method to any host via MCP + a CLI plugin.\n\n---\n\n## How it works — brain vs. nervous system\n\n```\n   @agentpulselabs/pulse (BRAIN, pure)          your coding agent (NERVOUS SYSTEM)\n   · phase state machine                     · runs the LLM (its model)\n   · contract (the rules)          ── MCP ──▶ · renders progress (native UI)\n   · schemas + validator          ◀── CLI ── · holds the human gate\n   · gate runner (npm run check)             · edits files · owns PM-tool MCPs\n```\n\nPulse **never calls an LLM.** `pulse_next` emits a *work-list* (prompts + a JSON schema per task); your agent\nruns them on its model; `pulse_submit` validates the results against the schema **and** the contract;\n`pulse_gate` locks decisions and advances; `pulse_verify` runs the gate command. The discipline travels; the\nreasoning is the host's.\n\n## State lives in the repo (`.pulse/`)\n\nDurable, git-tracked, travels across agents and humans, validatable offline:\n\n```\n.pulse/\n  pulse.config.json     which contract governs + the gate command\n  engagement.json       phase · status\n  board.json            THE project board (machine truth)\n  BOARD.md              rendered kanban (regenerated — don't hand-edit)\n  STATUS.md             one-glance dashboard\n  sync.json             optional PM-tool sync intent (Jira/GitHub/Asana)\n  decisions/product/    human decisions\n  decisions/architecture/  platform-dictated ADRs (each cites the invariant)\n  design/               working design docs (graduate to docs/DESIGN_*.md on gate)\n```\n\n## Two ways to drive it\n\n**1. MCP (primary — every agent):** run the `pulse-mcp` stdio server. Requires the optional peer dep:\n\n```bash\nnpm i @agentpulselabs/pulse @modelcontextprotocol/sdk\n```\n\nRegister it with your agent (example — Claude Code `.mcp.json`):\n\n```jsonc\n{ \"mcpServers\": { \"pulse\": { \"command\": \"npx\", \"args\": [\"pulse-mcp\"] } } }\n```\n\nTools: `pulse_start · pulse_next · pulse_submit · pulse_gate · pulse_verify · pulse_status ·\npulse_board_update · pulse_claim · pulse_sync`.\n\n**2. CLI plugin (fallback):** the published `agentpulse` CLI can install a `pulse` topic:\n\n```bash\nagentpulse plugins install @agentpulselabs/cli-plugin-pulse\nagentpulse pulse start --requirements \"…\"\n```\n\n(The plugin is a thin shim that `import`s this core — see the parent design doc §4b.)\n\n## The contract is pluggable\n\n```jsonc\n// .pulse/pulse.config.json\n{ \"contract\": \"agentpulse\", \"gates\": \"npm run check && npm run check:types\" }\n```\n\n- `contract: \"agentpulse\"` → the built-in reference contract (10 non-negotiables + 8 invariants + deep checks\n  for table categories, migration-free schema, secrets-in-settings, no-DB-blobs).\n- `contract: \"generic\"` → point at your own `pulse.contract.md` + a `gates` command. Pulse enforces\n  schema-validity + the DAG + your gate; add your own deep checks with a JS contract (advanced).\n\n## What Pulse guarantees (and what it doesn't)\n\n**Guarantees (deterministic):** schema validity, contract-invariant compliance, an acyclic work-item DAG, and\nthat \"done\" = your gate command exited 0. Never delegated to an LLM.\n\n**Does NOT guarantee:** *insight*. Reasoning quality is your host model's. On a weak model, Discovery is\nshallow — Pulse keeps it *correct*, not *brilliant*.\n\n## Develop\n\n```bash\nnpm test        # node --test — pure, no network, no MCP SDK needed\n```\n","readmeFilename":"README.md","_rev":"1-0580b4d10630b0e0849c341b833d14f0"}