Imported from Wirasm/kild (
AGENTS.md). Install upstream withnpx skills add Wirasm/kild. Copyright stays with the author.
AGENTS.md — kild
kild is an orchestration engine for agent teams: kilds (a git worktree and the agents
working in it — the unit of isolated, parallel work), the agents themselves, and the
observability around them. It is engine + CLI + pi extension only — there is no UI in this
repo; UI clients (helm) consume the REST/WS API on localhost:4517.
One inhabitant type: the agent. No ranks, no lead, no operator, no privileged human.
What wins, in order
- Simplicity. The smallest mechanism that does the job. A rule that only applies at one size, a default the engine infers, an abstraction with one implementation — all cost more than they pay.
- Dogfood. Run it before believing it. Green unit tests are not a working system;
scripts/e2e.shexists because four real bugs were invisible to 313 passing tests. - Apply the learnings. When something bites, fix the class, not the instance.
Boundaries (violations are bugs)
- Only the engine knows pi exists. pi shapes are translated into kild domain types in one place; the CLI and API clients never see them.
- kild ships mechanism, never intelligence. No personas, no process prompts in code —
personas are data (
.pi/agents/, configplugins:); the only shipped prompt is the generic mechanism prompt. - kild knows nothing about prp (or any intelligence layer). Integration happens via
generic config paths (
plugins,memory.dir,hooks.onClose) only. - Never read intent out of an agent's prose. No regex over a message body to decide what the engine does. Addressing did that and the "who is this for?" bug hid in it for months; the decisions ledger did it and parsed a protocol out of English. Both are gone. A sender names its recipients as data; a hook is declared in config; anything an agent means, it states through a tool call.
- Don't enforce what you can't enforce. The engine is loopback and single-operator: any local process can read any credential it holds. Attribution is worth building; authorization ceremony on top of it is not. Solve the problems that exist.
- Vocabulary:
docs/VOCABULARY.md— one word per concept, and the dead words are listed.
How to work here
- Layout:
engine/src/(server.ts,cli.ts,agent.ts,kild/domain slices),engine/scripts/e2e.sh,pi-extension/,docs/. - The engine is usually RUNNING from this checkout, and may be hosting the very run you are
part of. Never shut it down, and never bind port 4517. Starting your own engine on a
different port is fine. Do code work in a git worktree on a branch, PR to
main(bun installfirst — a fresh worktree has nonode_modules, so the gates cannot run). - Gates:
bun test,bun run typecheck,bun run lintfromengine/— all green before any PR../scripts/e2e.shfor anything touching the HTTP surface. - Never delete an existing test to make a gate green. If a test is genuinely obsolete, say which and why in the commit message.
- A malformed request is a 400, never a 500. The server does not report its own failure for a client's mistake.
- Conventional commits, written as a human — no AI attribution, no Co-Authored-By.
- Vertical slices: a change owns its types and logic; extend by adding a slice, never by growing a god-module. No shims, no backwards-compat aliases — the only consumers are our own CLI and UI, so rename outright and port them.
Docs
docs/VOCABULARY.md (naming) · docs/upgrading.md (what an existing setup must change) ·
docs/helm-migration.md (the API, for clients) · docs/onclose-hook.md (the lifecycle seam) ·
docs/attached-agents.md (the harness-kild-does-not-own transport) ·
docs/api-surface.md and docs/DEMOLITION.md (why the shape is what it is)
