A talk with my dear colleague and friend Yishay Haspel about how we use Cursor and .md files to manage tasks led to a simple question: what if we had something like Mermaid, but for Kanban? Boards as code, in the repo, that both we and our AI tools could use. Statecraft is that idea turned into a real tool. Thanks, Yishay.
Statecraft is an AI-first, developer-friendly standard for representing Kanban-style task boards as code. Boards are defined in a small YAML DSL and live in your repo as the source of truth. The CLI validates and summarizes boards; a read-only web renderer lets you view them in the browser. No editing in the UI—boards are meant to be changed by AI agents (or in code) and versioned in Git.
Why? Task tools today are UI-first and hard for AI agents to use. Statecraft gives you a machine-readable task language in the repo—deterministic, diffable, and built for AI to read, update, and summarize. Read more about motivation and principles →
- Node.js 20 or later (LTS; actively maintained versions)
From npm (works with npm, pnpm, and Yarn):
# npm
npx statecraft init
# or install globally: npm install -g @stcrft/statecraft
# pnpm
pnpm add -g @stcrft/statecraft
# or: pnpm dlx statecraft init
# Yarn (v2+)
yarn global add @stcrft/statecraftFrom source (for development or contributing):
- pnpm 9 or later (or use corepack:
corepack enablethenpnpm install)
git clone https://github.com/KristijanS99/statecraft.git
cd statecraft
pnpm install
pnpm buildRun the CLI via the workspace script (requires a build first):
pnpm cli <command> [path]Path defaults to ./board.yaml when omitted.
| Command | Description |
|---|---|
statecraft init |
Interactive setup: create a board file and optionally generate rules for Cursor (.cursor/rules/statecraft.mdc), Claude Code (.claude/rules/statecraft.md), and/or Codex (AGENTS.md) so your AI assistant knows the board path, task lifecycle, and AI guidelines. Re-run to create a new board; edit generated files to tweak guidelines. |
statecraft spec |
Print the board format spec (for AI agents; no paths). |
statecraft validate [path] |
Parse and validate a board file. Exit 0 if valid, 1 on errors. |
statecraft summarize [path] |
Print a short text summary (board name, column counts, task list, WIP/blocked) to stdout. |
statecraft render [path] |
Serve the board in the browser. Serves the built renderer and the board at GET /api/board; WebSocket pushes updates when the file changes. |
statecraft sync |
Update generated rule files (Cursor, Claude, Codex) to the current template. Uses .statecraft.json if present; otherwise discovers and parses existing rule files. Overwrites generated content—back up if you customized. Use --dry-run to list files that would be updated. |
Render options: --port 3000 (default), --open (open browser).
Upgrade notification: After each command, the CLI may check the npm registry for a newer version. If one exists, a one-line message is printed to stderr with an upgrade hint. The check is skipped when CI=true, when STATECRAFT_NO_UPDATE_CHECK=1, or when running from the monorepo (development). A best-effort cache in the system temp directory is used to avoid hitting the registry on every run (cache write failures are ignored).
Example boards are in examples/: try pnpm cli validate examples/board.yaml, then pnpm cli render examples/board.yaml --open.
For a new project or repo, run statecraft init to create your board and connect it to your AI workflow. Init creates a board with the canonical columns (Backlog, Ready, In Progress, Done) and prompts for: board name; board file path (default board.yaml); task spec directory (default tasks); optional WIP limit for In Progress; workflow options (all default to yes)—enforce Statecraft workflow (create task before any work), require each task to have a spec .md file, include task spec .md format guidelines in generated rules; and whether to generate rules for Cursor (default yes), Claude Code, and Codex. Generated files (e.g. .cursor/rules/statecraft.mdc, .claude/rules/statecraft.md, or a Statecraft section in AGENTS.md) include the board path, commands (statecraft validate, render), task lifecycle (prepare for work → Ready, start → In Progress, finish → Done), and AI guidelines. Init also writes .statecraft.json in the project root when it generates any rule file (board path, tasks dir, and options). You can commit it for team consistency or add it to .gitignore. You can turn strict mode or spec requirements off during init and leave it to the agent to decide when to create tasks or add spec files. Edit any generated file to customize the guidelines. After upgrading Statecraft, run statecraft sync to refresh rule files to the latest template; sync overwrites generated content, so back up customizations first.
New project: Run pnpm cli init to create your board and optional Cursor / Claude Code / Codex rules, then validate and render the path init gave you.
Existing board or examples:
pnpm build
pnpm cli validate examples/board.yaml
pnpm cli summarize examples/board.yaml
pnpm cli render examples/board.yaml --openWhen you open the renderer without a server (e.g. Vite dev), you can paste YAML or choose a file to load a board.
The board format is a single YAML file with board (name), columns (canonical set: Backlog → Ready → In Progress → Done; optional WIP limit on In Progress), and tasks (id → title, status, optional description, owner, priority, depends_on). Full grammar and field reference:
AI agents and developer tools should use the spec as the single source of truth.
| Package | Role |
|---|---|
packages/core |
DSL parser, AST, validation, summarizer. No CLI or UI. |
packages/cli |
CLI for validate, summarize, and render (server + static app). |
packages/renderer |
Vite + React app: read-only board view, loads from API or paste/file. |
pnpm test # unit/integration (core + CLI)
pnpm test:e2e # Playwright E2E (renderer; builds and serves fixture)Contributions are welcome. See CONTRIBUTING.md for how to run the project, run tests, and open a PR. We use Conventional Commits for commit messages.
GPL-3.0 — see LICENSE.