A build system for AI-coding harnesses.

One command resolves and emits for every active target and prints what it wrote, removed and skipped, file by file. With a git-URL Forge, ref follows a branch or pins a tag or full SHA; sync fetches first and fails when it cannot, so CI never syncs from a stale copy unless it passes --offline. craftar cache prune removes the Forge cache entries nothing uses — no registered workspace and not the current one — entries whose first fetch never completed, and trees unused for 14 days; it never touches a workspace, a lock or the registry, and --dry-run shows what it would remove. A symbolic link never carries sync out of the tree it works on: a Forge file read through a link that leaves the Forge or leads into its .git, and a workspace path that leaves through one, refuse the run before anything is written — there is no flag; a link that stays inside works as before. In a git repository, sync and sync --check warn for each generated file git ignores, naming the ignore rule by file, line and pattern; craftar never edits an ignore file, and mayBeIgnored in craftar.yaml lists the paths kept out of git on purpose.

Three layers: the open standards — AGENTS.md (the always-on rules, then each scoped rule listed at the file a target writes for it or embedded when none does), Agent Skills (SKILL.md) and mcp.json — written by the target emitters; tool-specific formats; Craftar post-processors for known gaps, e.g. injecting resources: file://.kiro/steering/*.md into Kiro custom agents. Today Craftar's own emitters cover Claude Code, Kiro and AGENTS.md, and the Kiro emitter reproduces a hand-built workspace byte for byte, including agent JSON and command mirrors. Delegating Codex, Kimi and Cursor formats to rulesync is planned. Importing a second client into an existing Forge reuses every ingredient whose render for that profile equals the workspace file, infers declared {{key}} values into the profile, and makes the rest variants; forge unify resolves each one back into its base (see Growing the Forge). craftar forge promote <type/name> --profile <p> goes the other way: it makes a profile's variant the base and gives the old base back, as a variant of its own, to every other profile that resolved it — gated on git, proved before the first write, never a commit. craftar import --report <file.md> also writes a Markdown report of the import: what was created, reused, made a variant or rejected, and the .kiro/ files that differ from what sync would generate — as paths and line counts, never content. craftar import --prefer-kiro <rule,…> takes the named rules from .kiro/steering/<name>.md instead of .claude/rules/<name>.md, for a steering mirror that was edited by hand and is the text to keep; the text is accepted only when it is proved to render back to that steering file's body for Kiro. Rules only: commands, agents and skills are not taken from Kiro. Import reads a Claude rule's paths: frontmatter as its scope, so a scoped rule stays scoped — fileMatch for Kiro, and a scoped rule in AGENTS.md — and keeps that frontmatter verbatim, so .claude/rules/<name>.md comes back byte for byte. At schema: 7 import never writes a generated rules index over its placeholder silently: a variant that holds the placeholder and whose file differs from what sync writes is refused, a new variant that freezes the list is warned, and --prefer-kiro refuses a rule whose ingredient holds the placeholder. Import takes nothing from behind a symbolic link that leaves the workspace or leads into its .git: such a source is rejected and listed, never adopted. In a Forge at schema: 8, a source equal to the importing profile's own local is reused there, one that differs is refused, and the Forge it would write is first loaded on a scratch copy. With --local=auto, a new source of the profile becomes a local there instead of a root ingredient, and a local that differs is rewritten; --local=always writes no ingredient at the root. A new local no recipe of the profile's folder cites is wired into the recipe <p>-local. With agents-md.primary: true, in a Forge that declares schema: 5 and a workspace whose targets include agents-md, an always-on rule with the default targets is written to AGENTS.md alone — with all three targets, instead of three times (.claude/rules/, .kiro/steering/ and AGENTS.md): its other files become orphans sync removes; the .claude/, .kiro/ and AGENTS.md texts that cite it point at its place in AGENTS.md; scripts, hooks and files copied as bytes are never rewritten — a reference left there is warned with its file and line; and generated Kiro resources name only the steering files the plan writes, while a hand-written entry naming a file the plan does not write and the disk lacks fails sync --check (a writing sync still writes). Craftar writes no CLAUDE.md; when one keeps Claude Code from reading AGENTS.md, every plan says so. The mode is opt-in — a workspace that does not set it sees no change — and every craftar before 0.36.0 refuses a schema: 5 Forge. A hook ingredient can declare its registration — the event, matcher and command Claude Code runs it with — and claude-code writes it to .claude/settings.craftar.example.json, to copy into .claude/settings.json; Craftar never writes a settings file Claude Code reads. Every craftar before 0.38.0 refuses a Forge whose hook holds registration.

Recipes declaring the same slot are mutually exclusive. craftar add recipe and craftar remove recipe change the workspace's choice in craftar.yaml in place — refusing a recipe that would share a slot (unless --replace), removing one another recipe still brings in through extends, or an edit that would not resolve — and print what the next sync would do; they never sync. craftar recipes and craftar ingredients list the whole Forge read-only, mark what the workspace uses (and, for recipes, why), and --recipe shows what choosing one would bring. The profile sets the team default; the workspace may override; the local file (craftar.local.yaml, git-ignored) overrides the workspace for one developer; its arrays replace the workspace's. An ingredient body can also mark a client-specific block as a section (<!-- craftar:section flavors --> … <!-- /craftar:section -->): the block is the default, a profile's sections or the workspace's overrides.sections replace or empty it, no rendered body holds the markers, explain names the layer each section came from, and forge unify can extract a section from a variant (take: section). A Forge that uses sections declares schema: 2 or above, so an older CLI refuses it rather than leak the markers. In a Forge that declares schema: 6, an opening marker can name the targets that receive the block (<!-- craftar:section flavors targets=claude-code,kiro -->): a target it names gets the section as any other, a target it does not name gets nothing of it, whatever a profile or the workspace sets, and a marker with no targets= is read as before. A Forge that writes no targets= sees no change, and every craftar before 0.39.0 refuses a schema: 6 Forge. In a Forge that declares schema: 7, a line of a rule or steering body that holds {{craftar.rules.index}} alone becomes the list of the rules the profile resolves, as each target names them: up to three groups — Always on:, Scoped:, On request: — one line per rule with its description, or by its reference alone, warned, when it has none; a rule no target of the workspace writes is left out. explain names an indexed file's list, AGENTS.md aside. A placeholder not alone on its line, or in an agent, a command or a skill, is left as written and warned; so is one alone on its line below schema: 7. Either warning makes doctor --strict exit 1. The index is generated, never a parameter, and every key starting with craftar. is reserved: forge unify never extracts into one and import never infers one. A Forge that writes no placeholder and sets no craftar. key sees no change from the index, and every craftar before 0.40.0 refuses a schema: 7 Forge. In a Forge that declares schema: 8, a profile's folder holds its own ingredients and recipes (profiles/<p>/ingredients/, profiles/<p>/recipes/), which only that profile sees: they render exactly as they would at the root, a root recipe can never reach them, and a broken reference fails the load, naming the files. explain names where a file's ingredient lives. Every craftar before 0.45.0 refuses a schema: 8 Forge. craftar forge localize moves a root ingredient only one profile resolves into that profile's folder, with the root recipes that cite it, and craftar forge share moves a local back to the root — each gated on git and proved, before the first write, to change no byte any profile or registered workspace plans; neither commits. In a Forge that declares schema: 9, an ingredient's metadata takes {{param}} too — a rule's paths: and pattern, an agent's or a command's description — a value that would break the file it lands in fails the plan, and forge diff and forge unify work on those fields; every craftar before 0.47.0 refuses a schema: 9 Forge.

Writes craftar.yaml — the Forge, the profile, and the recipe and target choices, given as flags or as answers — only once the workspace resolves and plans, then runs the first sync, which registers the workspace. Files already on disk are adopted when they equal the plan and otherwise left as they are and reported; an existing craftar.yaml is never edited. In a terminal, craftar init asks for a --forge or a --profile it was not given — the Forge last synced on this machine offered, the profile from the Forge's list, then the recipes and targets to keep or adjust — confirms once before anything is written, and ends by printing the same run as flags, for CI; off a terminal a missing flag is refused. When a declared parameter a file the plan writes cites has no value, craftar.yaml is still written and the first sync is not run. With --clone it then clones each repository the profile's repos lists into the workspace — git clone over https or ssh only, with the git found on PATH, never over a file sync writes, into the Forge or out of the workspace; when init asks for what the flags do not give, it lists the URLs first and asks, the default no. A clone is recorded nowhere, and sync never updates or removes it. craftar repos lists those repositories in an existing workspace — present, missing or blocked, with their URLs — and craftar repos clone clones the missing ones. With --new-profile <name> (optionally --like <profile>), init first writes one new file in a Forge directory, profiles/<name>/profile.yaml — the recipes and targets chosen, nothing else of the template — behind a git gate and never committed, then starts the workspace on it; in a terminal the profile list offers 0) a new profile.

In a Forge that declares schema: 3 or above, a profile's integrations block selects recipes and gives params. integrations.<slot>.kind: <kind> selects the recipe named <slot>-<kind> — integrations.pm.kind: azure-devops selects pm-azure-devops, a recipe that lists, say, the MCP ingredient and a rule describing where stories live — and every scalar of the block is the param integrations.<slot>.<key>, cited in a body as {{integrations.pm.org}}. An integration with no kind gives params only. A schema 3 Forge is read only by craftar 0.27.0 and later; below schema: 3 the block is ignored, without a warning; a kind with no recipe stops sync. In a Forge that declares schema: 4, an MCP server takes the params its ingredient declares, so one server serves every client: url: "{{integrations.idp.url}}", with integrations.idp.url declared in the ingredient's params, renders each profile's own URL, and .mcp.json and .kiro/settings/mcp.json get the same rendered server. A declared key with no value stops sync; a key the ingredient does not declare is left as written, with a warning when some layer gives it a value; below schema: 4 a server is written exactly as the Forge holds it. A schema 4 Forge is read only by craftar 0.28.0 and later. Tokens are referenced by authEnv, never stored (FM-8).

A service ingredient is a Docker Compose fragment plus the files it mounts. sync writes it under .craftar/services/<name>/, with the stack .craftar/compose.yaml — a Compose include of every fragment — for no target, text always LF without a BOM (a file listed as binary is copied as bytes), and records each file in craftar.lock (schema 3 only for a workspace that has a service). They are generated files like any other: status, diff and sync --check treat them the same. craftar services up reads the lock, not the Forge, and refuses to start a stack with a missing or hand-edited file, or with a stack or fragment the lock does not record; down stops it and status shows it. sync never runs Docker; up needs Docker Compose 2.20.0 or later. A Forge that holds a service ingredient is read only by craftar 0.25.0 and later.

A profile's templates block lists packages per kind — dotnet-new today — with an optional source feed. craftar templates list shows what the profile declares; craftar templates install runs dotnet new install once per entry, into the user's own template store. Nothing installs implicitly — not sync, not init, not doctor. An entry of a kind this CLI cannot install (npm-create, nx) is listed, skipped and warned. A source carrying a user or a password is refused; authentication is NuGet's. Planned: a generated rule mapping archetype → template, and a wrapping /create-project command.

Normalized hashes from the lock are compared with disk. drift discard is a sync that also regenerates the named hand-edited files and removes a named hand-edited file the Forge no longer produces. drift promote carries one hand edit of a .claude/ file into the Forge's working tree — a value in the profile's params or sections when the edit is only that, otherwise a variant for the workspace's profile — gated on git and proved before the first write; it never syncs and never commits. A file that holds an expanded rules index is not promotable: edit the Forge's rule, or the description of the rules it lists. So is a hand edit of a metadata field the Forge renders from a parameter, at schema: 9; drift show says why. At schema: 8, a hand edit of a profile-local file is promoted into the local itself: a value inference proves goes to the profile's params or sections, otherwise the local's own files are edited in place, with no variant. Sync direction is Forge → workspace; reverse flow is always explicit.

AGENTS.md has a byte budget, agents-md.maxBytes (default 32768, Codex's project_doc_max_bytes; 0 turns it off): over it every plan warns, naming the largest rules, and when a recipe, the profile or the workspace sets it, sync --check, status and diff --exit-code with no path fail — a writing sync still writes. Two thin wrappers in the CLI's repository make a pull request fail when a workspace is out of step with its Forge: a GitHub Action (ci/github/action.yml) and an Azure Pipelines step template (ci/azure/check.yml). Each installs an exact craftar version, outside the checkout, runs sync --check — its exit code is the step's — and names the files out of sync as annotations and a job summary, never a file's content; they write nothing to the workspace. A private Forge's token comes only from the workflow, for an origin the workflow names. Pin them to a commit SHA or a v<version> tag: a change under ci/ reaches a branch reference the moment it merges. The action ran on GitHub's Linux and Windows runners; the Azure template has not run on a real agent. craftar sync --check --committed [rev] and --check --index give the same verdict over what git holds — a commit or the index — instead of the folder, writing nothing and starting no hook, filter or core.fsmonitor of the repository. craftar git-hooks install writes, only when typed, a pre-push (or pre-commit) hook that runs that check, only inside the repository, starting only the craftar on PATH; uninstall and status complete it.

A writing sync records its workspace in ~/.craftar/registry.json. craftar workspaces prints each one — profile, stack, targets, Forge, last sync — with a status computed on the spot: up to date, outdated, drift, no lock, missing or error, plus forge moved when the Forge's commit is no longer the lock's; it reads a remote Forge from the cache unless --fetch is given. CRAFTAR_NO_REGISTRY turns the registry off, for CI runners and throwaway checkouts. From the Forge's side, craftar forge impact lists every registered workspace that reads it — by its path, by a git remote, or through another clone — with what its next sync would do; a workspace synced on CI, on another machine or with the registry off is not in it. craftar ui serves these views as a local page in a browser: the table of craftar workspaces and, for a registered workspace, what status, diff and explain say about it and what recipes and ingredients say about its Forge. Without --allow-writes it is read-only — it writes nothing (the Forge cache is used as every reader uses it) and never runs sync: it prints the command to copy. It reaches no network either way: a remote Forge is read from the cached copy, and the page says so. Started with --allow-writes — typing the flag is the consent — the page also offers Sync for a workspace and Discard edit for one hand-edited file (drift or orphan-drift, from its open diff), each confirmed in the page: a sync that never passes --overwrite-drift — every hand edit and collision is skipped and listed — or a craftar drift discard of that one path. Neither is offered for .claude/settings.craftar.example.json or for a workspace whose Forge is remote, and either is refused when the workspace changed since the page showed it. It listens on 127.0.0.1 only (port 4747 by default; --port 0 takes a free one), answers GET only — with --allow-writes, also POST to its two writing routes, from its own address — and every answer that carries data needs a token generated for that run, carried in the address it prints — whoever holds that address can read what the reading commands print, so open it only in a browser of the same user on the same machine, exactly as printed. It takes no --workspace, and exits 1 when the registry is off or cannot be read. craftar ls stays the view of one workspace's resolution.

An MCP server the AI coder starts — registered in its own MCP configuration, or for a whole team as an ordinary mcp ingredient that sync writes like any other server. It serves the one workspace it was started in through seven tools that only read — status, diff, explain, recipes, ingredients, targets, doctor — each answering with the data its command prints, so the agent can say "run craftar sync" instead of editing a generated file. Without --allow-writes it writes nothing — no workspace file, lock, registry or Forge (the Forge cache is used as every reader uses it) — reads no network unless started with --fetch, and never returns a hand-edited MCP configuration file; a result can carry the Forge's profile names, so register it only where that is acceptable. Started with --allow-writes, it also serves sync, add_recipe and remove_recipe. The flag grants nothing by itself: a writing call acts only in a workspace where a person typed craftar mcp allow-writes in a terminal, for the Forge, ref and profile the server is pinned to — the shell tools of Claude Code and Kiro give a program no terminal, so an agent cannot grant it through them (one that drives a real terminal could) — and craftar mcp revoke-writes takes it back without a restart. The sync tool never overwrites or removes a hand edit: every drift, orphan-drift and collision is skipped and listed, for a person to resolve with drift discard or drift promote, and a remote Forge needs --fetch; add_recipe and remove_recipe never sync. A result carries what the commands print, never a file's content. Upgrade every machine to craftar 0.29.0 or later before adding it to a shared Forge, and to 0.35.0 or later before registering it with --allow-writes. In Claude Code, a plugin in the CLI's repository holds a /craftar skill and starts the craftar on PATH — install 0.40.1 or later — as craftar mcp with its reading tools only — never --allow-writes, never --fetch; in a project with no craftar.yaml it does not start. When craftar comes from a version manager's shim (asdf, volta, mise once trusted), a project's files can choose what runs when the server starts. Planned: an Agent Plugin.

Checks this machine — Node ≥ 22, git, ~/.craftar, the registry, the Forge cache — and, inside a workspace, its configuration and Forge, the plan's warnings, declared parameters with no value (an error when a file the plan writes cites one, a warn when nothing does), the variables a written MCP server declares in authEnv or references as ${NAME} and the environment lacks (names only, never values), the lock, status and registration, and — in a workspace with a local service — Docker with its Compose plugin and the variables a service fragment needs that nothing sets (names only), and — when the profile declares templates — the templates block and, for a dotnet-new entry, the .NET SDK — and the planned AGENTS.md against its byte budget — and, under agents-md.primary, a CLAUDE.md, CLAUDE.local.md or .claude/CLAUDE.md — at the root or in a directory above it — that keeps Claude Code from reading AGENTS.md and the Kiro agents' hand-written resources — and, when the plan writes a hook's registration, a planned handler that is in no settings file Claude Code reads (at most a warn, so --strict exits 1 until the block is copied) — and, when claude-code writes a skill as one file, that Claude Code (measured with 2.1.310) does not list it (a warn per skill, with the fix, so --strict exits 1; the file is still written) — and, in a git repository, a generated file git ignores (generated-ignored, a warn, unless the path is listed under mayBeIgnored) — and a hook craftar git-hooks wrote (git-hooks) — and a path that leaves the workspace through a symbolic link (workspace-links, an error). Each finding is one line — ok, warn or error — with the command that fixes it. It only reports: nothing is written to a workspace, a lock or the registry, and a remote Forge is read from the cache unless --fetch is given. It exits 1 on an error, or on a warn under --strict; --json is a contract for tooling. craftar docs validate checks a workspace's Markdown under docs/, .claude/ and at its root — links that resolve inside the workspace, tool-call tags leaked outside code, files that are not UTF-8 text and, where the profile declares a docs: block, its categories, required frontmatter, dated file names and related: entries — one line per finding, naming a file, a line and a column, never a line of the file; it writes nothing and reads without the network unless --fetch, which concerns the Forge only. Planned: a rulesync check once it is a dependency.