ank and the alternatives
ank is not the first curated layer over a codebase. Here is what each alternative does well, where ank differs, and what the difference costs it.
At a glance
| Alternative | Good at | Where ank differs | What it costs ank |
|---|---|---|---|
| Retrieval (RAG) | Good atFinding what looks relevant to a query, in a corpus nobody curated. | Where ank differsAnswers what applies to a path: a set-membership test, not a ranking. No embeddings, no index service. | What it costs ankSomebody has to have written the constraint and its scope. |
| An LLM-maintained wiki | Good atPages derived from raw sources, which the model can regenerate if they are lost. | Where ank differsAn ADR records a choice that has no source. It is hash-anchored and signed at ratification, never rewritten. | What it costs ankNothing regenerates a record: the decision is written once and ratified by a human. |
| Open Knowledge Format | Good atKnowledge crossing organisations: a consumer never rejects a document for what it lacks. | Where ank differsSame instinct and same shape, markdown with YAML frontmatter and no server. But ank rejects an unknown field. | What it costs ankA malformed file is refused rather than read. |
| Process-skill workflows | Good atA rich method for the whole cycle, from interviewing the human to reviewing before merge. | Where ank differsank ships methods too, and measures the outcome: ank done runs the verifiers and never reads which method was used. | What it costs ankA method nobody honours is a line of frontmatter. Only the tree says the work was done. |
Against retrieval
RAG answers what looks relevant to this query; ank context src/auth/ answers what applies to this path. The first ranks by similarity, the second is a set-membership test. For a constraint that is the whole point: a rule that should have bound but ranked seventh did not bind, and nothing says so.
No embeddings, no index service, no re-indexing on every commit. The cost is real: somebody has to have written the constraint and its scope. ank does not replace search over a corpus nobody curated. It replaces the wiki page that was never found.
ank context src/auth/
CONSTRAINTS (1 active)
ADR-06d2 Opaque sessions rather than stateless JWT
TASKS (1)
TASK-820d [open] Migrate auth to opaque sessions
> ank claim TASK-820d to start
Against an LLM-maintained wiki
Karpathy’s pattern has three layers (raw sources, a wiki the model owns, a schema file) and three operations: ingest, query, lint. ank has that shape and differs on what the middle layer is.
A wiki page is derived from sources and can be regenerated if lost. An ADR records a choice that has no source: somebody decided opaque sessions over JWTs, the record is the only copy, and nothing can re-ingest its way back to it. So it is hash-anchored and signed at ratification rather than rewritten, and the lint is mechanical rather than a model re-reading for contradictions.
Against the Open Knowledge Format
Google’s Open Knowledge Format is the closest relative, reached independently: markdown with YAML frontmatter, no server, no SDK, identity carried by the path, the format as the contract. Its v0.2 trust signals are the same instinct as ank’s proofs, and ank adopted two of them outright: the actor convention and verified.
One axis diverges, deliberately on both sides. OKF tells consumers never to reject a document for what it lacks, because across organisations a rejected document is knowledge lost. ank rejects an unknown field, because for a criterion that must not be quietly weakened, an accepted but malformed file is a rule that silently stopped applying.
Against a process-skills workflow
Matt Pocock’s skills are the richest example: two dozen prompts covering the whole cycle, interviewing the human until the spec is precise, cutting it into tickets, driving the implementation test-first, reviewing before merge. The skill is the method, and the agent is held to it while it works.
ank ships methods too: six skills inside the binary, the contract and five siblings for plan, drift, loop, tdd and diagnose. A task can name one with ank new --method tdd, ank context names it once the task is claimed, and ank skills counts designations against firings. What no verb does is enforce one. ank done never reads the method: it runs the declared verifiers itself, because an agent graded on its process learns to fake the process, and an agent graded on the tree has to change the tree.
What it costs to run
Two numbers rather than an adjective.
- ~280 tokens
- in every session for the six skills: their frontmatter, the name and description a harness keeps loaded. 38 for the contract, 41 to 57 for each sibling, counted with
cl100k_base. A body is read only when its skill is invoked. - 8000 characters
- the default bound on what
ank contexthands a reader.
What ank is not
Said plainly, so you can rule it out quickly if it is not what you need.
Not a tracker. No cycles, estimates, velocity or roadmap.
Not a wiki. Only what is actionable or binding for an agent goes in.
Not a search engine. It does not replace search over a corpus nobody curated.
Not a process enforcer. It teaches methods and measures only the outcome.
Not a security boundary. It protects against drift, not against an attacker.
Install ank
Two commands. Linux, macOS and Windows, with git 2.34 or newer.
npm install -g @haksolot/ank
npx skills add haksolot/ank