Appearance
Use cases — situation → what to say
Load when: someone describes a situation rather than naming an action, or asks what this can do.
You never need a command. Say it in plain language, in any language, and it routes. Commands are shortcuts for when you already know the name — both columns do the same thing.
Who opens this, and what they get
| Situation | Just say | Runs |
|---|---|---|
| "Didn't we already look into this?" | "what have we concluded about X?" | the findings are read before anything is fetched — one file per question, each opening with what we now believe in a paragraph. An agent that needs the answer reads that and stops; the register underneath is for whoever argues. If nothing is there, the new research task links to what it did rest on, so the next person is one step further along rather than back at the start |
| "Look into X for me" — with no idea what that costs | "how deep do you want me to go on this?" comes back before any fetching, with three named rungs and what each costs in turns and wall-clock | the depth is agreed, then stated in the answer itself. orienting buys a direction in minutes · deciding buys a defensible call · standing buys something quotable in a year, and is the only one worth refusing. If the run outgrows its rung that is a new question at a new price, never a quiet overrun |
| "We keep doing this by hand — make it a skill" | "build the skill for the newsletter assembly, it's in T-18 and T-21" | the routine is read out of the tree, not asked about · the skill is born from the scaffold with its budget in the frontmatter · and its commands are run against an input they must reject before the file is saved, with what they printed pasted into Tested against. A door that runs nothing answers none: — a commit that skips either is refused by §18, because the sentence asking for it politely measured 0 of 5 |
| "Someone quoted a study at me — how solid is it, really?" | "we're about to bet on this finding — what pulls against it?" | the register entry is read out with its Reads against field, which names what it must be read beside and whether anyone looked. The three answers are different and the field keeps them apart: named tensions with the resolution · none found, a claim that someone checked · not checked, which is why the answer arrives with "and nobody has looked" rather than confidence nobody earned |
| "I'm a designer and I want one helper, not a team" | "I need someone to draft screens and write the docs for them" | one role, its craft and its tools — no roster, no org chart |
| "I'm a PM and I want a second opinion" | "what do you make of this pricing idea?" | an answer, nothing created — and disagreement when the evidence disagrees |
| "I want that opinion to have sources" | "who says so?" | an expert that cites, or the honest admission that this is a judgement call |
| "I want to know how real users would react" | "run this past our audience" | angles, never percentages — said before anything runs |
| "I'm a solo founder wearing every hat" | "I'll do the design, you do the rest" | you hold an assignment like anyone, reviewed by an agent that did not write it |
| "I'm a writer and this is not software" | "we publish a weekly essay" | ship means the issue goes out; the words follow yours |
| "I'm promoting my open-source library" | "the product lives in its own repo — this is the campaign" | the library becomes a watched resource (version_seen, releases land in triage as content candidates); its tree is mapped read-only; the competitors get a register with dated cells → tooling, templates/COMPETITORS-template.md |
| "I'm an engineer inside a company repo" | "fix the flaky test in this repo" | guest mode — their conventions bind, nothing of ours lands in their tree |
| "I run a workshop, not a product" | "we glaze tiles to order" | the process is discovered first, then a tool per step |
| "I already have Claude Code / Codex / Antigravity" | — | it installs into all of them; what it can run depends on the runtime, and it says so |
Someone else's repository
| Situation | Just say | What holds |
|---|---|---|
| "I'm fixing one issue in a public library" | "fix the crash in issue 412" | read as guest, not takeover — no debt list for the maintainers, and the takeover gates stand down rather than demand one |
| "I don't want my notes in their PR" | nothing | not one of our files lands in their tree, not even an ignored one |
| "But I want a record of what I did" | "where is my record?" | kept with you, keyed to the repo, surviving the clone being deleted |
| "Should I open the PR?" | "open it" | leaving their repo is outward — it waits for you |
| "I might come back to this in a month" | "leave it for now" | leave it as it is is a full answer, and it resurfaces when you return |
| "The team here already runs its own docs" | "they own the docs, keep mine separate" | the layer manifest splits them; a clone still gets the map |
Getting going
| Situation | Just say | Runs |
|---|---|---|
| "I have an idea and no team" | "I want to build X — set it up" | the interview, then the first task |
| "There's already a repo here" | "take this over, see what's missing" | audit → the debt list → fixes you approve — and the first two are held by hooks, not goodwill: nothing is edited before the list exists, and deferrable findings cannot be left unwritten |
| "My backlog is in another tool" | "move my backlog here" | mapping shown first, then items created unassigned |
| "Small job, no ceremony" | "quick: rename the buttons and push" | three questions, build → review — and the push is asked about |
| "Just use sensible defaults" | "defaults" | everything but the two hard gates |
| "I'm tired of questions — you decide" | "you decide" | a full reasoned configuration as one list to confirm; the floor still waits at execution |
| "I just have a question" | "what do you make of X?" | an answer, and nothing is created |
| "I want it to interview me properly" | "ask me what you need" | progressive — defaults everywhere, and only two questions have none |
| "I don't know what I'm building yet" | "help me think about it" | consulting, and it turns into a project only when you say so |
| "A colleague handed me this project" | "take this over" | besides the debt list, what this machine lacks of what the project declares: each mise.toml and .mcp.json entry not here, with what the dry runs would change; nothing is installed — mise trust included — before you say yes, because a project that changes versions by itself breaks the other projects on your machine → tooling |
| "My project is on the old flat layout" | "migrate the layout" | migrate-layout.py — every move a git mv, the hook and .gitignore follow, and anything it does not recognise stays put, named |
Day to day
| Situation | Just say |
|---|---|
| "What's happening?" | "status" · "what's stuck?" |
| "New idea for a feature" | "add: remember volume per app" |
| "Every task comes out a different shape" | "make a task for X" — the door writes it from the template with the id minted, and the guard refuses a new task that departs from it; a project working in another language keeps its own translated _ops/templates/TASK.md, which both of them read |
| "Nobody ever drew how the product actually works" | "map it" — _ops/MAP.md is seeded from what you already know, not commissioned as a project, and a feature's flow lands in it in the same task that changes the behaviour; a shipping project without one is now told so, and one honest line turns that off |
| "I didn't know there was a shelf for that" | nothing — the advisor says it first: when a decision appears (a landing page, a survey, a billing model, a style), two or three named candidates arrive with one line each on what makes them different → choosing-tools |
| "The interface it generated looks generated" | "which kit are we building from?" — the component library goes in _ops/design-system/ with a register row, the references in _ops/brand/, and a named style (Neo-Brutalism, Glassmorphism…) buys search terms, never a specification → visual |
| "Does the graph actually work?" | "check the graph" — notes, edges, orphans, phantom targets, links no vault can follow, and how many mentions are still edges waiting to happen. On one live project the answer was 19 notes and 0 edges |
| "We hired three roles and it still feels like one agent doing everything" | "is the roster wired?" — a role owes .claude/agents/<role>.md beside its file, or nobody loads it; the work quietly goes to the advisor and nothing errors |
| "Will this MCP server clutter my machine?" | "add it to the project" — --scope project writes .mcp.json in the repo and leaves with it; the default writes your global config keyed by this path and stays there after the directory is gone |
| "Where do a role's skills actually come from?" | "attach the house style to the writer" — the pool (_ops/skills/) or a register row naming the runtime that provides it, and the row is a link when there is a file: a skill that resolves to nothing loads nothing, silently |
| "What has this release cost us?" | "what did we spend on v0.2?" — rolled up from the run records per release, task, model or month, with the four token numbers kept apart and every run that reported nothing counted as not counted rather than as zero |
| "I want a board — and should the status go in the filename?" | "show me the board" — _ops/BOARD.md is generated from the tasks, every id a link, and no: a status in the filename renames the file on every move and breaks every link that cited it |
| "Tasks reach accepted and nobody ever reviewed them" | "who reviewed this?" — and the ladder now asks instead: the edge into the terminal stage carries review_by: non-author, a new ladder without it is refused, an old one says so on every move |
| "Design work keeps landing on the frontend engineer" | "who is this task's craft?" — and if the answer is nobody, hire rather than route to the nearest name; a task assigned to a role that exists in no file is refused, which is the only trace an uncovered craft leaves |
| "The advisor keeps fixing things itself instead of opening a task" | nothing to say — the guard says it: a commit that moves the product with nothing under _ops/ in it warns, and a third in a row is refused, naming the two before it. A one-line fix stays a one-line fix, an amend stays possible — a hook cannot see one — and a habit stops |
| "The guard is in the repo and nothing ever refused anything" | "is the guard actually wired?" — the file is not the guard, the hook is; the check says which of the four states this project is in, and the fix is one line |
| "The idea is still fuzzy" | "I'm thinking about onboarding, not sure what yet" |
| "Something is broken in production" | "urgent: signup fails on Safari" |
| "A user complained" | "a customer says export is confusing" |
| "Every bug arrives shaped differently" | "give this kind of work its fields" — often already done: proposed when the type was born, from its craft's own standard |
| "Ship it" | "release this" · "publish the episode" · "send the batch" |
| "It pushed without asking me" | nothing — the outward gate stops the push itself and names the three doors: you run it, you switch the gate off on purpose, or — if what it caught was a sentence about publishing rather than the act — it says so to you rather than rewording itself past the gate |
| "It refused a command that wasn't publishing anything" | nothing — a command starts a command; a word after another word is prose. A file being written, a search for the phrase — **a ` |
| "It said "noted" and my rule vanished" | "remember this: …" — the memory-write is refused; the rule lands in a file workers read, and the home is named back |
| "Did it work?" | "did the new onboarding move the metric?" |
| "I'll do this part myself" | "I'll design it, pick it up after" — and you'll be asked what you did, what proves it, and what's next |
| "I'm done for today" | "wrapping up" — the tail written, applied work landed, decisions recorded |
| "I want to continue in another tool" | "I'll carry on in Antigravity" — same wrap-up, then open the project there |
| "Can I just close the terminal?" | "done?" — yes, once the wrap-up ran; nothing lives in the session |
| "I closed it without saying anything" | nothing lost but talk: recovery reads the tree, and where the runtime resumes, the old session gives up its wrap-up once |
| "This is taking ages — did it die?" | "still going?" — you are told before you ask, and an overrun says so |
| "I asked a question and it went quiet" | nothing — an agent with a long answer says it is looking and comes back with it |
| "Don't make me sit here" | "audit the repo" — it leaves the turn and you keep talking |
| "Why did that cost so much?" | "what ran?" — every helper is named with its tier |
| "Close it, the work's done" | "close T-…" — the door checks the ladder and the gates, and a refusal returns as the reason; acceptance stays with whoever owns it, never the worker |
| "Show me how work moves here" | "show the pipeline" — the ladder drawn from its own block: stages as nodes, gates on the edges |
| "Spec this one properly" | "spec it" — the type's cut decides the shape; where no format is bound, the stock template carries guardrail metrics, prior attempts and a plan per outcome |
| "Did we already try this?" | "prior attempts?" — answered from the spec's own section, with outcomes named, including "effect never measured" |
| "Did anything we watch move?" | "check the resources for new versions" — the sweep runs now: unchanged is said per row, a move arrives as its distillate, and accepting it opens the delta against everything that cites it → tooling |
| "Is anything we use out of date — and does it matter?" | "check our dependencies" — mise, npm and osv-scanner are asked and the answers sorted: a vulnerability first, a move outside the pin as a decision with its release notes, a move inside it as one routine line; anything that could not be asked is said, never read as current, and nothing is installed → tooling |
| "What is this package even for?" | "why do we have lodash?" — deps-report.py --why answers from the project's own files: the register row, or the decision that named it, or no why recorded — a view, not a second list to keep → tooling |
| "The build just found a hole in the spec" | "the spec assumed X and it's false" — the gap is named to its place and the artefact's owning group gets the request; a fix task is born there, the build takes blocked_by or narrows and says so → escalating |
| "I don't want everyone to see this at once" | "roll it out quietly" — the release names its rollout: soft · canary · staged · flag-gated · shadow — guardrails own the halt, the kill switch is named first, expansion never advances itself → shipping |
| "Which survey do we attach to this?" | "what should we ask, and when?" — the instrument matches the layer: effort at the step, the scenario after it closes, the software quarterly, the brand twice a year — and one layer read with another's tool is the trap → catalogue |
| "We want our automations in a visual tool" | "set this up in Node-RED" — the tool is ranked by what it costs to leave: a flow that is a file in the repository beats one kept in a dashboard, and a dashboard's flows are exported into the repository on every change (automations) |
| "How should people sign in?" | "add login" — passkeys first, a password as the fallback: a passkey cannot be phished onto another site or leaked from a database, and the library comes off the shelf rather than being written by hand (choosing-tools) |
| "Remember this — always do it this way" | "remember: we never ship on Fridays" — the rule is routed to where workers read: a guide line, an ABOUT.md word, a decision, a register entry — named back to you, never left in the chat's memory → checking |
| "Break this big thing up" | "split the checkout flow" — parallel children share a wave, and the next one waits |
| "Run these two at once" | "do both" — they never own the same file, decided at decomposition |
| "Three people told me the same thing" | "users say the transfer screen is confusing" — filed as triage, marked recalled, not designed off memory |
| "That report was useful, don't lose it" | "make that a task" — findings become work rather than dying in the scroll |
People and craft
| Situation | Just say |
|---|---|
| "I need someone who can do X" | "we need packaging design" |
| "Bring in a real person" | "add Anna as our design reviewer" |
| "Is anyone idle?" | "who's loaded, who isn't?" |
| "This role is doing too much" | "the engineer is carrying design too" → a hiring signal, not a pruning task |
| "We don't need this role now" | "park the second engineer" → archived with a note on what brings them back |
| "Design my app properly" | "design the app" → structure before pixels, and you approve the structure |
| "It improvised and it's bad" | "redo it properly" → the process is named step by step |
Knowing things
| Situation | Just say | What holds |
|---|---|---|
| "How does anyone get from signup to paying?" | "show me the map" | _ops/MAP.md answers — and where it cannot, that is a gap written as one, not a guess |
| "We keep redesigning the same flow" | "what does the map say, and what did we decide?" | the map holds the current move; _ops/DECISIONS.md holds why the last redesign was rejected |
| "Why does this screen exist at all?" | "what job is this move hired for?" | every move on the map carries a job story — when <situation>, someone wants to <motivation>, so they can <outcome> — and the guard refuses a move added without one. A route is a how; the job is the why, and it is written so it can turn out to be wrong |
| "It said it was done but nothing landed" | — | the ending is refused while _ops/ sits uncommitted, once, naming the files — because every gate here fires at the commit, so work that stops short of one is held by prose alone. Leaving it deliberately is a valid answer, said in a line |
| "The session died and I lost the thread" | "what did that run actually do?" | the record was opened when the work opened and its checkpoint moved with it, so committed · applied · remains reads from the tree — a run that writes only at the end leaves nothing to resume from |
| "We keep writing rules the day something breaks" | "is this a lesson or a repair?" | a repair lands now; a lesson waits a week between its dated field note and any promotion into the guide, because what survives the week is about the system and what evaporates was about that afternoon |
| "It passed, then it failed, then it passed" | "the answer will not hold still" | the work stops at the second disagreement — the count is flips, not attempts — and what escalates is the question is unstable, and here is what differed between the askings, never which run was right |
| "A new study says the opposite of one we rely on" | "add this paper to the sources" | the entry records what it reads against, and the commit is refused until every finding resting on the contested source is re-read — Answered re-stamped — or marked stale; a finding is read instead of its sources, so this is the only place the disagreement could reach it → resources |
| "Pull the papers on this for me" | "what does the literature say about X?" | a 200 is believed only after its body is read — an article with no text, one entry titled Error, zero citations for a DOI that does not exist all arrive looking like answers — and what comes back carries its endpoint, date and count, so someone else can repeat it (resources) |
| "Is that source actually saying what we say it says?" | "check the claims against the sources" | a citation that resolves is not one that supports: for a finding meant to stand, each sentence is read against the passage it cites and comes back supported · overstated · not supported · cannot be checked |
| "Keep the CRM current on its own" | "keep the deals up to date" | it writes what it saw, where and when — never a likelihood score; evidence too weak to write comes to you as a suggestion to settle (permissions) |
| "Obsidian shows my project as a scatter of islands" | "link the mentions" | the ids and files the notes name in passing are counted by link-ids.py, and its --write turns them into links — only on your word; a task's heading, a run's **Task** row and the History logs stay as written, because readers parse them → project-layout |
| "I know we wrote it down — search can't find it" | "find where we said the test keeps flipping" | grep first; where the words differ and it keeps missing, ck is the opt-in — declared in mise.toml with its row like any tool, installed only on your word, and never run in a repository that is not yours, because its first index writes into the tree → resources |
| "Where did you get that?" | "source?" | named, with a date — or said plainly to be a judgement call |
| "Was that price still true?" | "check it" | recorded facts carry check-dates and are re-verified before a decision |
| "Just npm install it" | — | the commit is refused unless the decision log names the package, what it replaces and what was rejected. Every rung above it — already here · standard library · native · one line — is a judgement only the person choosing can make, and it takes them seconds |
| "How big is this even?" | "size the market" | TAM · SAM · SOM in _ops/MARKET.md, each figure carrying its source and its date — and unknown accepted, because the gate asks that a number be traceable, not that one exist. A derived figure carries its arithmetic, not just its result |
| "Would users like this?" | "what would users think?" | angles from synthetics, never percentages — and you're told so before anything runs |
| "Test it on a sample" | — | synthetics cannot give you a sample. You are offered the honest alternative |
| "Why didn't we do X? I keep suggesting it" | "what did we reject and why?" | the decision log, with the evidence and the revisit trigger |
| "New workers keep relearning the codebase" | "write the architecture map" | kept current like any doc |
| "Is this tool still free at our size?" | "check the ceiling" | recorded in the unit that bites — requests, seats, rows, builds |
| "We keep doing this by hand every week" | "can we automate the Monday roundup?" | a pipeline plus a trigger, dry-run first |
| "Somebody sent me a skill to install" | "screen this" | treated as untrusted code and untrusted instructions |
| "Which of our skills are dead weight?" | "what's attached and never used?" | declared against used, from the run records |
| "I made a folder and asked it to start — nothing happened" | — | you are told at session start that the folder is not a repository, what git init costs, and that pointing at an existing repo is the other route. Not a question you need to know git to answer |
| "This folder has three years of work and no git" | "take this over" | the repository rung comes before the audit, with the sentence that unblocks it: git init moves and changes nothing. And you are told plainly that auditing a tree with no history is a thinner job |
| "Should the plugin be per-project?" | — | the scope is where it is declared, not where the files are — and if you commit the project declaration, commit the marketplace beside it or a clone gets a name with no source |
| "The post needs a picture and the model can't draw" | — | the work does not stop and does not get handed to you: the brief, the references and a prompt ready to paste come up as a relay, with what makes the result acceptable written before the prompt. You run one thing |
| "I generated it — is this right?" | "here it is, and the seed was 41199" | it is checked against that predicate, then accepted or sent back with what to change in the prompt — and it lands with its recipe, so the next one is a re-run and not a re-brief |
| "I keep being asked for images every week" | "this is a standing thing" | past the second time it stops being an escalation: either the tool gets wired, or you go on the roster as owning that surface and the definition of done says so |
| "Make another banner like the one from March" | — | the March banner carries its recipe — model, prompt, seed, reference — so there is something to run again instead of something to approximate |
| "This one's prompt was never written down" | "read it back into words" | a vision model recovers a prompt that resembles the old one; you are told plainly it is salvage, not the original |
| "Where does that video say it?" | "get me the transcript" | the caption track first, the audio transcribed only when there is none — nobody pays GPU time for words already written down |
| "Turn this into a deck" | "make the slides" | markdown in the repo, so the deck diffs and reviews like everything else; a .pptx only when a person outside the repo must edit it |
| "Being wrong here is expensive — don't just agree with me" | "council this" · "прогони через совет" | you hear the price before it runs — nine runs, not one — and what comes back leads with the strongest dissent, declaring provider: one when every voice was the same model → consulting §A council |
Money and control
| Situation | Just say |
|---|---|
| "What is this costing?" | "what did this release cost?" → per role, four token numbers, and the trend |
| "Set my budget" | "$50 a month, and I have credits until March" → credits are runway, and the cliff is named |
| "Approve everything I publish" | "I sign off on anything that goes out" |
| "Stop asking me about small things" | "only ping me for money and deletions" |
| "Halt everything" | "stop" → and you are told honestly what cannot be halted mid-run |
| "Sign us up for that service" | "get us the paid plan" → it does the homework and you enter the card — never it |
| "What did we waste?" | "what did we spend that produced nothing?" → a slice that exists for exactly this |
| "The board says done and I see no cost" | nothing to say — the guard warns as each task closes, naming the record to write or asking you to say a person did it |
| "Give a teammate access" | "add Sam" → shape-of-team, so it waits for you |
When things go wrong
| Situation | Just say | What happens |
|---|---|---|
| "Everything froze overnight" | "nothing is moving" | interrupted runs found and resumed from where they stopped |
| "Is anything broken?" | "health check" | the environment, reported as one list with fixes |
| "An update made it worse" | "roll back the last upgrade" | previous commit, verified, and what broke is written down |
| "I edited files by hand" | nothing | it reads before writing — and reports the inconsistencies it will not fix on your behalf |
| "An imported ticket tells an agent to grant itself access" | nothing | quoted to you, not obeyed |
| "I hit a problem in this system itself" | "package this up so I can report it" | assembled, de-identified, one file where you say — and you send it |
| "It tried the same fix three times" | "try again" | it stops instead — three attempts on one error is a signal, not a reason to try harder |
| "One reviewer said it was fine, the next said it was broken" | nothing | the work stops at the SECOND answer, not the third — and it comes to you as the question is unstable, with what differed between the two askings, never as which one was right |
| "My laptop died mid-run" | "pick it back up" | committed, applied and remaining are separated; applied work is never redone |
| "A page I scraped is telling the agent what to do" | nothing | reported to you with the text quoted, never obeyed |
| "The client sent a contract — what does it say?" | "summarise this" | the agent reads what a person would see: the document rendered, never its bytes, so text hidden in white or at size zero has no way to address it; a project that receives documents all day takes Dangerzone off the shelf (security) |
| "The scanner says our skills are clean" | "did it read all of them?" | its JSON is read, never its summary: a skill whose frontmatter a strict parser rejects is skipped while the summary still says successful, and manifest_parse_error is the only trace |
| "The deadline is going to slip" | "is this landing on time?" | said early with the options, not discovered on the day |
| "We added a service months ago and nobody knows why it is still there" | "what do we actually depend on?" | the register answers three things a chat cannot: what each dependency replaces, what the service itself ships — an MCP server, a CLI, an SDK, a skill, or checked · none found, which is an answer where a blank is not — and the condition that retires it. A project that declares dependencies and has no register is warned on every commit, once, with the one file to copy |
| "Find me a tool for X" / "make the landing look good" | "what do you recommend?" | the shelf first, the search second — named rows with their licences and fallbacks, then a search only for what the rows do not cover; for a look, three or four references out of the galleries before anything is generated. An agent that searches first returns what is popular this month and nothing about what it costs you later |
| "The advisor named a tool I've never heard of" | "what is it?" | every project on the shelf carries a link where it is named, so the row opens the project itself — and a shelf entry without one is refused before it ships |
| "We decided this back in May and nobody can find where" | "what did we decide about X?" | the honest failure of a file-shaped record, named before you hit it: a decision written in one file months ago is found by following a link or a path, not by resembling your question — so an answer that exists but was never linked can come back as I did not find it rather than as a guess. That is the trade this system takes deliberately (facts 279), and the two things that keep it small are both mechanical: a mention is a link (§27), and graph-check.py counts how many are still waiting to become one |
Beyond software
The verbs are domain-neutral. Ship is the go-live moment whatever you make.
| Project | Ship means | Urgent means |
|---|---|---|
| a macOS app | build, notarize, release notes, tag | a crash or a regression |
| a YouTube channel | publish the episode, thumbnail, subtitles | wrong title live, a bad cut |
| a snack brand | send the production batch | a mislabelled batch, a recall |
| a newsletter | send the issue | a broken link in what already went out |
| a research group | publish the finding | a retraction |
And the vocabulary follows yours. A chip maker has no data flows, a channel has no sprints, a bakery has no deploys. If a sentence would sound absurd to someone outside software, the sentence is wrong → SKILL.md.
What this file is for
Discoverability for someone who does not know what this can do. Not a command reference — the commands have their own place, and plain language reaches everything either way.
If a situation you hit is not here and the route was not obvious, that is a field note, not a failure of memory → self-maintenance.