The guide an agent reads before building a home - #11
Merged
Merged
Conversation
The toolchain shipped before the document that explains it. An agent handed someone's house could read the SDK reference and the template, but nothing stated the judgment neither of them carries: that the coordinator is the only place authorization happens, that component requirements and coordinator grants intersect silently so a mismatch renders a hole instead of raising, and that a call whose outcome is unknown must never be retried because the lamp may already have moved. Everything here is taken from the code it describes: the UI vocabulary and limits from packages/component, the command surface and the exit-code table from packages/cli, the ordering and authorization rules from templates/home. The two CI lessons are the ones this repository paid for on #10 — a check that exists is not a check that runs, and a local run under the wrong Bun proves nothing about the runner. Closes the second deliverable of workstream F.
This was referenced Sep 14, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stacked on #10, whose code this documents. Base is
mathieu/agent-cli, notmain.Why
The agent-first toolchain landed before the document explaining it. Someone's Claude Code or Codex, handed a house, could read the SDK reference and copy
templates/home— but nothing stated the judgment neither of them carries:miakapp.yamlrequirements and coordinator grants intersect silently. Asking for more does not fail at publication; the component never receives the path and the interface renders a hole. This is the quietest way a Miakapp home breaks;What is in it
docs/agent-guide.md, ten sections: what the three artifacts are and who trusts whom, characterizing an existing house before designing anything, the coordinator's four declarations with the state-before-event ordering rule, the component's semantic vocabulary and the two states it must never hide, the intersection rule and the test that enforces it, the check loop, publishing with generation CAS, and a pre-delivery checklist.Plus the exit-code table as a table, since the usual caller is a program: branch on the code, reconcile on 7, never retry it.
Provenance
Every claim is taken from the code it describes — UI vocabulary and limits from
packages/component, command surface and exit codes frompackages/cli, ordering and authorization rules fromtemplates/home. Protocol claims are pinned to their source:4409to RFC 0001 §7.4, the staleness requirement to RFC 0002 §12.2, and the guide says explicitly that the broker, not RFC 0002, is the authority for the guest ABI.The two CI lessons are the ones this repository paid for on #10: a check that exists is not a check that runs, and a local run under Bun 1.4 proves nothing about a runner pinned to 1.2.23.
Closes the second deliverable of workstream F.
Review
Docs only — one new file and a README pointer. The useful review question is not prose but accuracy: whether any rule here is stated more confidently than the code supports.