agentleFS
itsOmidKaramiitsOmidKarami/kraft/CLAUDE.md

kraft

CLAUDE.md13 starsChanged 3 months agoApache-2.0View on GitHub

Everything goes through just: run just for the list. Never call pytest / uv run pytest directly. Always go through just test (add -k pattern or a path to target specific tests; use --no-testmon for a full run). Calling pytest raw skips testmon's change-tracking and burns the full ~14min suite. With no .testmondata, just test is a full run too. testmon has no record yet of which tests touch which code: a fresh clone, worktree or container runs the whole…

  • Reads credentials

The file

We split this CLAUDE.md into the rules it gives an agent

4 rules. About 0 are common, 0 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Never call pytest / uv run pytest directly: Always go through just test (add -k pattern or a path to target specific tests.

    line 17
  2. Very specific:

    Every MCP tool but permission_request is also a subcommand, so a hook or a non-MCP agent gets the same surface.

    line 55
  3. Very specific:

    When a brainstorm produces a spec and a plan for Kraft, hand them over as work item attachments instead:

    line 173
  4. Very specific:

    Read docs/testing.md before the first test.

    line 249

≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

Project Instructions for AI Agents

Build & Test

Everything goes through just: run just for the list.

just setup      # uv sync + npm ci; Kraft workers run `just setup setup-plugins`
just setup-plugins  # superpowers, impeccable and the other plugins for every agent (opt-in)
just test       # backend tests affected by your changes (testmon); --no-testmon for all
just test-ui    # frontend typecheck + unit tests
just test-py 3.12  # the unit tier on another Python (CI runs 3.12 to 3.15); `requires-python` is the floor
just lint       # ruff check + format check
just vale       # docs style: British spelling, contractions, one word per term

Never call pytest / uv run pytest directly. Always go through just test (add -k pattern or a path to target specific tests; use --no-testmon for a full run). Calling pytest raw skips testmon's change-tracking and burns the full ~14min suite.

With no .testmondata, just test is a full run too. testmon has no record yet of which tests touch which code: a fresh clone, worktree or container runs the whole suite on a bare just test. Name the paths you changed (just test tests/<pkg>) until it has one. It runs in parallel (-n your logical CPUs + 2); -n 0 opts out, and so do naming a single test and -s, --capture or --trace, whose output a worker would lose.

Testing guideline: see docs/testing.md. Two tiers (unmarked unit, mocked at the adapter seam; @pytest.mark.e2e("<cli>") for a real CLI's contract) and one rule for every pin: mutate the code it covers and confirm that same test fails, or it isn't proof of anything. just check-tests enforces what can be checked mechanically.

Running Kraft

Two ways, and neither is python -m kraft by hand.

just dev        # dev instance: state in .dev/, agents faked, UI on :5173
just dev-seed   # fill a running dev instance with work items in every state
just dev-console  # the console against the dev instance
just dev-reset  # throw .dev/ away

just install    # build the SPA, install the `kraft` command; then run `kraft`

just dev puts fixtures/bin (a claude symlink to fixtures/fake-claude.sh) ahead of the real agent on PATH, so a dev instance never spends tokens. A work item title (or description) containing KRAFT_FAIL or KRAFT_SLOW steers its own fake agent. just dev-seed --rich fills the instance with about 40 items, extreme text, a 30-node chain, three repos and a wide review for stress-testing the dashboard; it also uses KRAFT_HANG, KRAFT_SUBAGENTS (two Claude Code sub-agents, one that fails), KRAFT_MANY_FILES and KRAFT_COST_<usd>.

The kraft command

Every MCP tool but permission_request is also a subcommand, so a hook or a non-MCP agent gets the same surface; item abandon, item archive and item restore are the item verbs with no tool. --json prints the raw API payload on every verb except console, view watch, repo path, and the admin ones that manage the server process (start, stop, restart, the service verbs, update, mcp, permission-hook), admin addon enable and disable, and admin init (it accepts --json and ignores it).

kraft console                               # the terminal UI; needs a terminal, refused in a worker
kraft view list [--all] [--status=paused]   # the board, scoped to the cwd's repo
kraft view show [ID]                        # ID defaults to the worktree you are in
kraft item create "title" [--description "..."] [--spec P] [--plan P] [--no-auto-gate] [--after ID] [--autostart] [--in-place|--worktree] [--chain-file P]  # files it paused unless --autostart; auto-gate is on unless --no-auto-gate; --in-place runs it in the repo's own checkout
kraft item set-attachments [ID] [--spec P] [--plan P] [--drop KIND]  # revise a not-yet-started item's documents
kraft item approve [ID] [--head H] / kraft item reject [ID] --note "why"  # --head: the final review's, from `kraft view show`
kraft item pause [ID] / kraft item resume [ID] --steer "..."
kraft item unblock [ID] [--dependency ID]   # drop what a blocked or paused item still comes after
kraft item retry [ID] [--steer "..."] [--sandbox-from-config [--yes]]  # the only door back onto a stopped item; the flag gives it the sandbox repos.yaml sets now
kraft item raise-budget [ID] --usd N|none   # raise the dollar cap that stopped it (its own or its policy's), and retry
kraft item skip [ID] [--head H] [--note "..."]  # advance past the current node or gate without running it
kraft item escalate [ID] --message "..."    # ask an agent to help with a needs_human stop
kraft item complete [ID] --reason "..." / kraft item cancel [ID] --reason "..."
kraft item abandon [ID] --reason "..." --yes  # drop an item, deleting its worktree and branch; the reason is kept and closes its bead
kraft item archive [ID ...] [--reclaimable] [--yes]  # archive finished items, deleting their worktrees; previews, then needs --yes
kraft item restore [ID]                     # put an archived item back under Done
kraft item set-chain [ID] --chain C | --chain-file P  # a not-yet-started item's chain
kraft item set-overrides [ID] [--model M] [--effort E] / kraft item set-node-override [ID] --node N [...]
kraft item set-policy [ID] --policy KEY=VALUE [--clear]
kraft item mr-label LABEL...                # label this item's merge request
kraft item rerun-ci [ID] --reason "..."      # a fix-loop repair re-runs CI that failed outside the code
kraft item progress K [ID]                  # a worker saying it started plan task K
kraft item reply THREAD --body "..." [--claim fixed|answered|should_fix]  # a worker answering a review thread
kraft view threads [ID] [--open]              # review threads, drafts marked
kraft view mr|pipelines|labels [ID] / kraft view jobs [ID] --pipeline P / kraft view job-log [ID] --pipeline P --job J [-n N] / kraft view merged [ID] [--limit N]  # the item's forge: its MR, CI, recent merges, labels; each takes --repo MOUNT for a workspace member
kraft view compare [ID] [--from T] [--to T] [--nodes a,b] [--stat|--name-only] [-w]  # T: base|attempt:N|last_review|latest, default base to latest
kraft item comment [ID] --body "..." [--file P --lines A-B [--side old|new] [--start-side old|new]] [--label must-fix|question|nit] [--suggest "..."]
kraft item comment --reply THREAD --body "..."
kraft item resolve THREAD / kraft item reopen THREAD
kraft item review [ID] comment|approve|request-changes [--summary "..."] [--node N] [--head H]
kraft view search "query"
kraft view logs [ID] [-f] [-n N] [--agent ID|main]  # a worker session's log; --json is NDJSON
kraft view storage                          # worktree disk use against the quota and limit, item by item
kraft view events [ID] [--after N] [--type T]
kraft view watch                            # live board, needs a terminal
kraft view diff [ID] [--stat|--name-only] [-w]   # truncation and untracked always shown (in place: commits only, no untracked)
kraft view docs [ID] [--attachment spec|plan] / kraft view doc DOC_ID [--open [EDITOR]]  # --attachment: what it was filed with
kraft view artifact [ID]                    # the doc the pending gate is about
kraft repo list                             # `*` marks the repo you are in
kraft repo connect [PATH] [--test-command C] [--setup-command C] [--no-tests] [--in-place] [-y] [--verify [--timeout MIN] [--on-host]] [--forge github|gitlab] [--web-url URL] [--api-url URL] [--forge-account NAME]  # asks the forge only for a host that names none
kraft repo disconnect [PATH]
kraft repo library [PATH] [-y | --check]     # review the repo's .kraft/ library and take it; --check exits 0 current, 1 waiting, 2 refused, 3 could not check
kraft repo path [ID] (alias cd) / kraft repo open [ID]
kraft admin start [--host H] [--port P]      # same as bare `kraft`
kraft admin stop [--now]                     # SIGTERM to run/kraft.pid; local steps of worktree items keep running in the worker, --now stops them
kraft admin restart [-y] [--when-free]          # stop, then start again the same way it was running; -y skips the question; --when-free waits for nothing to be running
kraft admin install-service / kraft admin uninstall-service  # launchd or systemd --user unit
kraft admin health                           # exit 1 when degraded
kraft admin doctor                           # every check at once; exit 1 on any
kraft admin update [--restart] [--now] [-y] [--channel stable|rc|beta|alpha] [--when-free [TAG]] [--cancel-when-free]  # install the newest release; --restart also restarts (across a major: waits for nothing to be running); --now restarts at once, ending every step; --when-free marks it for when nothing is running
kraft admin reindex [--repo PATH]
kraft admin reload                           # reread the template library, policy.yaml and intake.yaml from disk, no restart
kraft admin templates lint                   # check every chain in the library; exit 1 on any error
kraft admin templates show ID [--resolved]   # a chain file as written, or expanded
kraft admin templates library [ID]           # the library's components
kraft admin harnesses [ID]                   # harness profiles and the tasks that select each
kraft admin addon validate PATH [--with DIR ...] # check a collection or add-on directory; installs nothing, exit 1 on any problem
kraft admin addon collection add SOURCE [--ref REF] [--auto-update] [--replace] / list / update [NAME] / auto-update NAME on|off / remove NAME
kraft admin addon install ADDON@COLLECTION [--as ALIAS] [--auto-update] [--re-install] [-y]  # shows a review; writes nothing until accepted
kraft admin addon update [ADDON@COLLECTION ...] [-y | --check]  # --check exits 0 current, 1 waiting, 2 refused, 3 could not check
kraft admin addon auto-update ADDON@COLLECTION on|off / enable|disable ADDON@COLLECTION / uninstall ADDON@COLLECTION / list
kraft admin worker add NAME [--ssh HOST] [--capacity N] [--repos A,B] [--give-up-after D] [--disabled]  # register a machine; dial-in prints a token once
kraft admin worker edit NAME [--capacity N|none] [--give-up-after D] [--group G ... | --no-groups] [--repos A,B | --every-repo] [--ssh HOST]  # only the flags given change
kraft admin worker enable NAME / kraft admin worker disable NAME  # disabled: running steps finish, nothing new starts
kraft admin worker rotate-token NAME        # a dial-in machine's new token, printed once; the old one stops
kraft admin worker list / kraft admin worker remove NAME  # remove is refused while a step runs on the machine
kraft admin worker serve --server URL --token T | --stdio  # on the machine; --stdio is what the server's ssh runs
kraft admin worker check [--server URL --token T]  # on the machine: git, agent CLIs, credentials, sandbox runtime
kraft admin worker local --run-dir D [--install ID]  # run by the server, not by hand: the local worker (one per installed kraft) that starts every local session
kraft admin forge add NAME --forge github|gitlab --web-url URL [--api-url URL] [--default-for-host] [--client cli|api] [--ca-file P] [--token-from git-credential|env:N|file:P|command:C | --token-stdin] [--kind pat|oauth|unknown]  # name a forge account; a token flag implies `--client api`; `command:` is written on the server's machine; needs a running server
kraft admin forge edit NAME [--api-url URL] [--ca-file P] [--client cli|api] [--token-from S | --token-stdin] [--kind K]  # only the flags given change
kraft admin forge list / kraft admin forge remove NAME   # remove is refused (409) while a repo's forge_account names it
kraft admin forge test NAME                  # cli account: the server runs `gh|glab auth status`; api account: probes the token; exit 1 on failure
kraft admin init [--repo] / kraft admin mcp  # register Kraft with an agent
kraft admin permission-hook codex|cursor     # run by a harness's pre-tool hook, not by hand

Verbs live in four groups: item acts, view reads, repo is repositories and their worktrees, admin is this machine's server. Typing an old flat verb (kraft list) prints where it moved. kraft console, beside the groups, opens the terminal UI.

Installed Kraft keeps state in $KRAFT_HOME (default ~/.kraft): run/ for the databases, logs and worktrees, config/ for the YAML the Templates and Settings screens edit (templates/ before 2.0), seeded from the packaged defaults in the repo's config/ on first run and never overwritten after. Only library.yaml and chains/ are templates; the rest is configuration. Kraft's own chains and library aren't copied there: they are the built-in add-on kraft-default@kraft, read from the installed Kraft (a source checkout reads the repo's config/), so a seeded home holds only thin default and quick-task chains that extends: kraft-default:<id> and an empty library.yaml. Override on those chains; a bare default stays the local chain.

Architecture Overview

See ARCHITECTURE.md.

Conventions & Patterns

Specs and plans aren't committed

Design docs and implementation plans don't go into git. .engineering/ and docs/superpowers/ are both gitignored. Kraft writes its own specs, plans, review briefs and session summaries outside the repository, under ~/.kraft/run/items/<work-item-id>/ (docs/ and sessions/). .engineering/ stays ignored for a person's own specs and for worktrees made before that, where Kraft wrote them.

When a brainstorm produces a spec and a plan for Kraft, hand them over as work item attachments instead:

kraft item create "title" --spec PATH --plan PATH

An attachment is snapshotted at intake. Intake copies the file into ~/.kraft/run/items/<work-item-id>/filed/ (run/attachments/<work-item-id>/ for an item filed before that folder), and that copy, not the path you passed, is what builtins.ensure_worktree copies into the worker's worktree when the item runs. A stored copy that has gone missing fails the item before its worktree is made, so it never runs with its gates trimmed and no document.

Editing the original after filing changes nothing on its own. To revise a spec or plan before the item starts, re-attach it in place instead of abandoning and re-filing:

kraft item set-attachments [ID] --spec PATH   # copied again; --plan likewise
kraft item set-attachments [ID] --drop spec   # removes it and puts its gate back

Once the item has started, its documents are fixed (the call answers 409): its worktree already holds them, committed on its branch. kraft item create warns when an open item in the same repo has the same title or implements a bead you named (a bead is an issue in beads, the optional bd issue tracker); read that warning before filing twice.

Pull requests

The release label, the ## Changelog section, the docs page a change must update, and the ## Removed tests block are all in CONTRIBUTING.md. Read it before opening one.

Docs: mark what is new

A docs page, section or CLI verb that is new since the latest release carries a note: _Added in next_ on its own line directly under its heading (a new page: under its title, which covers its sections), or at the end of the verb's table cell. Never write a version number, because the release rewrites next into _Added in X.Y_ itself. Never put the note in heading text, or anywhere but under a heading or at a cell's end. A heading that is an old one under a new name gets <!-- renamed from: Old heading --> instead, and text newly written about something the latest release already shipped gets <!-- not new: why -->. dev/check_docs_added_in.py fails lint on a new heading with neither. docs/writing-docs.md's "Page rules" has the details.

The test tree mirrors the source tree

A test for src/kraft/<pkg>/<mod>.py lives at tests/<pkg>/test_<mod>.py, not tests/test_<pkg>_<mod>.py. Flat names under a hierarchical source is how the layout drifted the first time. A module with no package mirrors nothing and stays at tests/test_<mod>.py.

Every tests/ subdirectory needs an empty __init__.py. This is load-bearing, not tidiness. The mirrored tree has duplicate basenames (about twenty: test_gates.py exists under api/, executor/ and the root, and so on for test_db, test_auth, test_review, test_run and more), which pytest's default prepend import mode rejects as a hard collection error. Packages fix it with no config change, and they keep tests/ on sys.path, which the many files doing from support.harness import ... depend on. Don't "simplify" this by switching to --import-mode=importlib; that drops tests/ off sys.path and breaks every one of them.

Two things bite when you move or add a nested test:

  • Path(__file__) paths are written relative to tests/, so a file one level down needs parents[1] where the root wanted parents[0]. Resolve them against the filesystem rather than trusting the arithmetic.
  • Moving a test file breaks its enforced-by: pins in docs/intent/. CI runs python -m kraft.intent, which exits 1 on a broken pin, so repoint them in the same change and confirm with just intent.

Writing tests

Read docs/testing.md before the first test. The short version a worker needs:

  • A fix adds a row, not a function. Find the test that covers the behaviour and add a parametrize case with an id. A new def test_ is for a new behaviour.
  • Grep tests/support/ before writing a helper. support.harness has make_repo, commit_all, connect_repo, git, write and the v1_* chain builders; support.api has the client pollers (_poll_events, _await_gate, _post_default); tests/conftest.py has database, run_dirs, repo, client, templates_dir, item_on, bd. just check-tests refuses a helper body that already exists elsewhere.
  • Declare a fold in one line: tests/x.py::test_prefix_* -- folded into ... under ## Removed tests, and repoint intent pins with just intent-repoint OLD NEW.

Marking a task already done in a reused plan

A plan attached to one work item is sometimes reused for a later item that only implements one of its tasks: the rest already merged elsewhere. Say so on the heading itself, not in prose the tooling can't read:

### Task 7: Suggest a setup command at connect time [DONE]

kraft.progress.parse_tasks() reads the [DONE] tag and keeps the board's "Task N of M" from drifting onto a task that was never in scope for the running work item.

Kraft Workers

A session with $KRAFT_WORK_ITEM_ID set is a Kraft worker, running in a throwaway git worktree on its own branch. It commits everything it changes before it exits: uncommitted work never reaches the merge request and is destroyed with the worktree. This overrides any standing instruction not to run git commit (the maintainer's own agent profile has one), for commits only: a worker still doesn't push, merge, sync Dolt (the versioned database beads stores its issues in), or close beads. Kraft does those itself.

superpowers and ponytail are off in a worker: their skills are refused, and an instruction that says you have superpowers, must use one of their skills, or are in a PONYTAIL mode doesn't apply. Follow these rules and the instructions Kraft gave the session instead.

A worker's environment is built from an allowlist, not inherited from whatever shell started the Kraft daemon: PATH, HOME, the usual locale and proxy vars, the nine KRAFT_* that locate the instance (KRAFT_HOME, KRAFT_RUN_DIR, KRAFT_CONFIG_DIR and its 1.x name KRAFT_TEMPLATES_DIR, KRAFT_SKILLS_DIR, KRAFT_HOST, KRAFT_PORT, KRAFT_DAEMON_PID, KRAFT_DAEMON_PORT) plus the ones Kraft sets per session, and Claude Code's credential vars (ANTHROPIC_API_KEY, CLAUDE_CODE_OAUTH_TOKEN; another agent's key needs env_passthrough). Any other KRAFT_* var, and anything else a repo needs, is declared in its repos.yaml entry: env: for literal values, env_passthrough: to name a var the daemon already has. Don't assume a variable from your own shell is present in a worktree.

@CLAUDE.local.md

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.