Put the guide where the agent actually looks: miakapp agent-pack - #14
Conversation
The toolchain, the guide and the contract all existed, and none of them were where a coding agent actually looks. An agent opening the owner's home repository reads AGENTS.md or CLAUDE.md, and finds whatever the owner wrote there — which is not this. `miakapp agent-pack` puts the knowledge in the repository: the guide as a file under .miakapp/, a pointer to it in both instruction files, and the MCP server registered in .mcp.json so the tools are wired rather than described. The CLI's rule that it never rewrites what it did not generate is what shapes every merge. The guide is a file the command owns outright. The instruction files are edited only between markers it wrote, so prose above and below survives byte for byte and a second run rewrites the block in place instead of stacking another copy. .mcp.json is merged as a structure, one key by name: every other server survives, and a file that does not parse is refused rather than replaced with a valid one. Two new FileSystem methods carry this — `replace` is deliberately separate from `write`, so overwriting stays something a command asks for rather than something it falls into. The guide ships as a package asset, and a test asserts it is byte-equal to docs/agent-guide.md. Editing the doc without copying it across is a red test, not a pack that teaches an agent rules the CLI no longer has. Verified against the built binary, not only through injected tests: the pack installed into a repository with its own AGENTS.md and its own .mcp.json kept both, `claude mcp get miakapp` reads the generated entry back as a project-scope stdio server, a second run reported every file unchanged, and miakapp_agent_pack installed a pack over real MCP stdio.
Répétition de la porte de sortie de l'atelier F — elle ne tient pas encoreJ'ai joué la porte de sortie de l'atelier F contre le binaire construit depuis l'union locale de Les trois premières étapes sont solides :
L'export de test est volontairement dérivé du producteur : chaque nom de champ vient de L'impasse : une cause racine, trois manifestationsL'agent frais arrive à
Corollaire pour cette PR précisément : le Aucune commande ne comble le trou : Ce que je n'ai pas retenu comme défaut
La décision n'est pas de mon ressortLe trou se referme par une décision de distribution, pas par du code : publier Matériel et mode opératoire complet conservés hors dépôt, dans |
1 participant
Atelier F, livrable 1 — installable pack for Codex and Claude Code. Stacked on #13; base is
mathieu/agent-mcp, notmain.The gap this closes
We built the guide (#11), the discovery command (#12) and the MCP server (#13). None of them is where a coding agent actually looks. An agent handed someone's house opens the owner's repository and reads
AGENTS.mdorCLAUDE.md— and finds whatever the owner wrote there, which is not our guide. The exit gate for this workshop says a fresh agent should get to a working component "without undocumented human intervention". Until now the undocumented intervention was: a human tells the agent this repository exists.What
miakapp agent-packwrites.miakapp/agent-guide.mdAGENTS.mdCLAUDE.md.mcp.jsonmiakapp mcpIt reports an action per file (
created/updated/unchanged) rather than one summary line, because "I installed the pack" is not the same claim as "I replaced your AGENTS.md".The repository is the owner's
The CLI already refuses to rewrite what it did not generate —
nodeFileSystem.writeopens withwx. That invariant is what shaped every merge here rather than something this command had to work around:<!-- miakapp:begin -->and<!-- miakapp:end -->. Prose above and below is copied through byte for byte; the block is appended at the end on first run, because the top of an instruction file is where the owner put what matters to them; a second run rewrites the block in place instead of stacking another copy. An unterminated marker is refused rather than guessed at;.mcp.jsonis merged as a structure, one key by name. Every other server survives. A file that does not parse is refused — an owner who hand-edited it into a syntax error still wants their edit back, not a valid file where theirs used to be.FileSystemgainsreplaceandmakeDirectory.replaceis deliberately a separate method fromwrite: overwriting stays something a command asks for by name, never something it falls into.The server is registered as the bare
miakappcommand, not an absolute path. The file is committed, and the next machine to check it out will not have this one's directory layout.Drift is a red test, not a surprise
The guide ships as
packages/cli/assets/agent-guide.mdandfilesnow includesassets. A test asserts it is byte-equal todocs/agent-guide.md. Editing the doc without copying it across fails the suite — I confirmed that by editing the doc first and watching it go red, then copying. A pack that teaches an agent rules the CLI no longer has is worse than no pack.The command is also a tool,
miakapp_agent_pack, because #13'severy command except help, version and mcp itself is a tooltest does not let it be anything else. That test doing its job unprompted is the design working.Verified against the built binary
Not only through injected tests:
AGENTS.mdand an.mcp.jsonholding asentryserver: the owner's prose stayed on top,sentrysurvived, the block was appended;claude mcp get miakappin that repository reads the generated entry back — Scope: Project config (shared via.mcp.json), typestdio, commandmiakapp, argsmcp. The consuming client parses what we wrote; that is not my assertion about the format, it is the client's;unchanged;miakapp_agent_packinstalled a pack over real MCP stdio (initialize→notifications/initialized→tools/call),isError: false;npm pack --dry-runlistsassets/agent-guide.mdin the tarball.bun run check301 pass / 0 fail / exit 0.bun run check:packagesexit 0 — CLI 113 (was 93), component 38, template 8. No dependency added.What I did not do
Codex MCP wiring is not written by this command.
AGENTS.mdis Codex's instruction file and the pack writes it, but Codex's own MCP configuration format could not be verified in this environment — nocodexbinary, no local config, no network..mcp.jsonwas verified by running the client that consumes it. I would rather ship the half I proved than emit a TOML file in a schema I guessed at; the.mcp.jsonentry andmiakapp mcpare enough for a Codex user to wire it with their client's own tooling. Worth closing when someone can check it against a real Codex install.Stack
Fifth level, and nothing below is merged: #10 → #11 → #12 → #13 → this. Flagging it rather than adding quietly. The value of all five arrives when the stack comes down, starting at #10.