@ybotok/loam 0.1.0-beta.2 → 0.2.0-alpha.1

package/dist/core/agent/tools/registry.js

@@ -0,0 +1,228 @@
+import { describedMd, hintedMd, namedMd, skillsIn, titledMd, tomlBlock, tomlLine, unprefixed, } from "./dialects.js";
+/**
+ * The original target and the default. This WRAPPER must stay byte-identical
+ * to what loam has always written — SLASH_COMMANDS (scaffold.ts) derives
+ * through it —
+ * and an already-initialized repo must still read as fully scaffolded
+ * (`skipped` is existsSync, never content). What the wrapper wraps now carries
+ * a version stamp, which is the one thing about a generated file loam will
+ * report on; see `stubbed`.
+ *
+ * It stands outside the registry object because SLASH_COMMANDS reaches for it
+ * by name. That lookup was `AGENT_TOOLS["claude"]!.format!` — two assertions on
+ * an exported const evaluated at import time, so renaming the key, or letting
+ * this entry lose `format` the way `codex` legitimately has, would have thrown
+ * a TypeError while the CLI entry point was still being loaded: before
+ * `program.exitOverride()` exists, and therefore with no envelope around it.
+ * Named and typed, both mistakes are typecheck failures instead. The registry
+ * still lists it first, and the emitted bytes are unchanged.
+ */
+export const CLAUDE = {
+    path: (name) => [".claude", "commands", `${name}.md`],
+    format: (c) => `---\ndescription: ${c.description}\nargument-hint: ${c.argumentHint}\n---\n\n${c.body}`,
+    skill: skillsIn(".claude"),
+    detect: [".claude"],
+};
+export const AGENT_TOOLS = {
+    claude: CLAUDE,
+    // Cursor invokes by flat file name (`/loam-check`); its frontmatter `name`
+    // field spells that invocation form.
+    cursor: {
+        path: (name) => [".cursor", "commands", `${name}.md`],
+        format: (c) => `---\nname: /${c.name}\n---\n\n${c.body}`,
+        skill: skillsIn(".cursor"),
+        detect: [".cursor"],
+    },
+    // Copilot prompt files: `.prompt.md` extension, description-only frontmatter.
+    // Detection cannot use `.github/` — almost every repo has one and almost none
+    // of them means Copilot — so it looks for the files Copilot itself reads.
+    "github-copilot": {
+        path: (name) => [".github", "prompts", `${name}.prompt.md`],
+        format: describedMd,
+        skill: skillsIn(".github"),
+        detect: [
+            ".github/copilot-instructions.md",
+            ".github/instructions",
+            ".github/prompts",
+            ".github/agents",
+            ".github/skills",
+            ".github/workflows/copilot-setup-steps.yml",
+            ".github/.mcp.json",
+        ],
+    },
+    // Gemini: TOML, and a namespace DIRECTORY — `.gemini/commands/loam/check.toml`
+    // is invoked as `/loam:check`, so the file name drops the `loam-` prefix the
+    // flat-named tools carry.
+    gemini: {
+        path: (name) => [".gemini", "commands", "loam", `${unprefixed(name)}.toml`],
+        format: (c) => `description = "${tomlLine(c.description)}"\nprompt = """\n${tomlBlock(c.body)}"""`,
+        skill: skillsIn(".gemini"),
+        detect: [".gemini"],
+    },
+    opencode: {
+        path: (name) => [".opencode", "commands", `${name}.md`],
+        format: describedMd,
+        skill: skillsIn(".opencode"),
+        detect: [".opencode"],
+    },
+    // Cline reads workflows from `.clinerules/` — plain markdown, no frontmatter —
+    // but its skills from `.cline/`. The two directories are unrelated, so both
+    // count as a sighting.
+    cline: {
+        path: (name) => [".clinerules", "workflows", `${name}.md`],
+        format: (c) => `# ${c.name}\n\n${c.body}`,
+        skill: skillsIn(".cline"),
+        detect: [".cline", ".clinerules"],
+    },
+    // Amazon Q surfaces these as its PROMPT library, not as commands: the file is
+    // invoked `@loam-check`, never `/loam-check`. Same file shape regardless.
+    "amazon-q": {
+        path: (name) => [".amazonq", "prompts", `${name}.md`],
+        format: describedMd,
+        skill: skillsIn(".amazonq"),
+        detect: [".amazonq"],
+    },
+    // Antigravity's directory is `.agent/`, which is why the id and the directory
+    // do not match here as they do almost everywhere else.
+    antigravity: {
+        path: (name) => [".agent", "workflows", `${name}.md`],
+        format: describedMd,
+        skill: skillsIn(".agent"),
+        detect: [".agent"],
+    },
+    // Auggie is the Augment CLI: id `auggie`, directory `.augment/`.
+    auggie: {
+        path: (name) => [".augment", "commands", `${name}.md`],
+        format: hintedMd,
+        skill: skillsIn(".augment"),
+        detect: [".augment"],
+    },
+    // Skills-only, deliberately: Codex reads `.codex/skills/` and does not load
+    // custom command files, so it declares no command emitter at all rather than
+    // laying down files nothing will ever open.
+    codex: {
+        skill: skillsIn(".codex"),
+        detect: [".codex"],
+    },
+    // Continue's prompt files take a bare `.prompt` extension, and `invokable`
+    // is what promotes one from a template to something you can call.
+    continue: {
+        path: (name) => [".continue", "prompts", `${name}.prompt`],
+        format: (c) => `---\nname: ${c.name}\ndescription: ${c.description}\ninvokable: true\n---\n\n${c.body}`,
+        skill: skillsIn(".continue"),
+        detect: [".continue"],
+    },
+    // Crush namespaces like Gemini does — `.crush/commands/loam/check.md` is
+    // `/loam:check` — but stays markdown.
+    crush: {
+        path: (name) => [".crush", "commands", "loam", `${unprefixed(name)}.md`],
+        format: namedMd,
+        skill: skillsIn(".crush"),
+        detect: [".crush"],
+    },
+    // Devin Desktop, formerly Windsurf: Cascade-style workflows, and the rename
+    // moved the directory from `.windsurf/` to `.devin/`. New files go to the new
+    // directory; a repo still holding the old one is still a Devin repo, so both
+    // are sightings.
+    devin: {
+        path: (name) => [".devin", "workflows", `${name}.md`],
+        format: namedMd,
+        skill: skillsIn(".devin"),
+        detect: [".devin", ".windsurf"],
+    },
+    factory: {
+        path: (name) => [".factory", "commands", `${name}.md`],
+        format: hintedMd,
+        skill: skillsIn(".factory"),
+        detect: [".factory"],
+    },
+    junie: {
+        path: (name) => [".junie", "commands", `${name}.md`],
+        format: describedMd,
+        skill: skillsIn(".junie"),
+        detect: [".junie"],
+    },
+    // Kilo Code workflows carry no frontmatter — the title line is all the
+    // wrapper there is.
+    kilocode: {
+        path: (name) => [".kilocode", "workflows", `${name}.md`],
+        format: titledMd,
+        skill: skillsIn(".kilocode"),
+        detect: [".kilocode"],
+    },
+    // Kiro uses Copilot's `.prompt.md` extension under its own directory.
+    kiro: {
+        path: (name) => [".kiro", "prompts", `${name}.prompt.md`],
+        format: describedMd,
+        skill: skillsIn(".kiro"),
+        detect: [".kiro"],
+    },
+    // Qwen Code retired its TOML commands in favour of markdown + frontmatter,
+    // so this is markdown despite the Gemini lineage.
+    qwen: {
+        path: (name) => [".qwen", "commands", `${name}.md`],
+        format: describedMd,
+        skill: skillsIn(".qwen"),
+        detect: [".qwen"],
+    },
+    // Roo/Zoo Code: id `roocode`, directory `.roo/`, no frontmatter.
+    roocode: {
+        path: (name) => [".roo", "commands", `${name}.md`],
+        format: titledMd,
+        skill: skillsIn(".roo"),
+        detect: [".roo"],
+    },
+    trae: {
+        path: (name) => [".trae", "commands", `${name}.md`],
+        format: namedMd,
+        skill: skillsIn(".trae"),
+        detect: [".trae"],
+    },
+    // The vendor-neutral skills root, and the only id here that names no vendor.
+    // `.agents/skills/<name>/SKILL.md` is read by six of the tools that already
+    // have entries above, each documenting it in its own words:
+    //
+    //   Cursor — "Skills are automatically loaded from `.agents/skills/`,
+    //     `.cursor/skills/`, `~/.agents/skills/` … and `~/.cursor/skills/`"
+    //     (Agent Skills, cursor.com/docs/skills).
+    //   GitHub Copilot — "For project skills, specific to a single repository,
+    //     create a `.github/skills`, `.claude/skills`, or `.agents/skills`
+    //     directory in your repository" (Adding agent skills for GitHub Copilot,
+    //     docs.github.com/en/copilot → customize-cloud-agent/add-skills).
+    //   Codex — "Codex scans `.agents/skills` in every directory from your
+    //     current working directory up to the repository root" (Build skills,
+    //     developers.openai.com/codex/skills).
+    //   Gemini CLI — `.agents/skills/` is the workspace-tier alias for
+    //     `.gemini/skills/`, and "within the same tier … takes precedence over
+    //     the `.gemini/skills/` directory" (docs/cli/skills.md in
+    //     google-gemini/gemini-cli).
+    //   Zed — "Skills are loaded from `~/.agents/skills/` and
+    //     `<worktree>/.agents/skills/` only" (Agent Skills, zed.dev/docs/ai/skills).
+    //   Roo Code — `.agents/skills/` is its cross-agent project location, ranked
+    //     below `.roo/skills/` at the same level (Skills,
+    //     docs.roocode.com/features/skills).
+    //
+    // Skills only, for the reason spelled out on `codex`: not one of those six
+    // documents a COMMAND file under this root, so a `.agents/commands/` would be
+    // files nothing will ever open — the thing this entry exists to stop.
+    //
+    // Purely ADDITIVE, and that is the design rather than an implementation
+    // detail. No tool above loses or re-points its own skill path: a repo already
+    // carrying `.claude/skills/` keeps getting them there. This entry is for the
+    // team that would rather have ONE copy those six read than six copies of the
+    // same bytes, and choosing that is the user's call — which is why selecting
+    // `agents` adds a target and never removes one.
+    //
+    // `detect` is `.agents/skills`, never a bare `.agents/`, for exactly
+    // `github-copilot`'s reason. `.agents/` is a shared root that other
+    // conventions also write into, so a bare marker would auto-scaffold into any
+    // repository where something else had made the directory — the failure that
+    // rules out `.github/` one entry up. It is also NOT `antigravity`'s
+    // `.agent/`: one letter apart, unrelated conventions, and `existsSync` on
+    // either says nothing about the other.
+    agents: {
+        skill: skillsIn(".agents"),
+        detect: [".agents/skills"],
+    },
+};
+//# sourceMappingURL=registry.js.map

package/dist/core/agent/tools/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../../src/core/agent/tools/registry.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The registry of agent tools loam can scaffold for — one entry per tool: its\n * paths, its wrapper dialect, and the marker paths whose presence means the\n * tool is in use. Paths and wrappers follow each tool's own documented\n * convention and are pinned byte-for-byte in test/agents.test.ts.\n */\nimport type { AgentTool } from \"../contract.js\";\nimport {\n  describedMd,\n  hintedMd,\n  namedMd,\n  skillsIn,\n  titledMd,\n  tomlBlock,\n  tomlLine,\n  unprefixed,\n} from \"./dialects.js\";\n\n/**\n * A registry entry that really does emit command files — both halves of the\n * command adapter present. The distinction is not hypothetical: `codex`\n * declares neither, on purpose. Naming it lets the one entry\n * scaffold.ts derives THROUGH carry that guarantee in its type, instead of at\n * the use site where the only way to state it was a pair of `!`.\n */\ntype CommandEmittingTool = AgentTool & Required<Pick<AgentTool, \"path\" | \"format\">>;\n\n/**\n * The original target and the default. This WRAPPER must stay byte-identical\n * to what loam has always written — SLASH_COMMANDS (scaffold.ts) derives\n * through it —\n * and an already-initialized repo must still read as fully scaffolded\n * (`skipped` is existsSync, never content). What the wrapper wraps now carries\n * a version stamp, which is the one thing about a generated file loam will\n * report on; see `stubbed`.\n *\n * It stands outside the registry object because SLASH_COMMANDS reaches for it\n * by name. That lookup was `AGENT_TOOLS[\"claude\"]!.format!` — two assertions on\n * an exported const evaluated at import time, so renaming the key, or letting\n * this entry lose `format` the way `codex` legitimately has, would have thrown\n * a TypeError while the CLI entry point was still being loaded: before\n * `program.exitOverride()` exists, and therefore with no envelope around it.\n * Named and typed, both mistakes are typecheck failures instead. The registry\n * still lists it first, and the emitted bytes are unchanged.\n */\nexport const CLAUDE: CommandEmittingTool = {\n  path: (name) => [\".claude\", \"commands\", `${name}.md`],\n  format: (c) =>\n    `---\\ndescription: ${c.description}\\nargument-hint: ${c.argumentHint}\\n---\\n\\n${c.body}`,\n  skill: skillsIn(\".claude\"),\n  detect: [\".claude\"],\n};\n\nexport const AGENT_TOOLS: Record<string, AgentTool> = {\n  claude: CLAUDE,\n  // Cursor invokes by flat file name (`/loam-check`); its frontmatter `name`\n  // field spells that invocation form.\n  cursor: {\n    path: (name) => [\".cursor\", \"commands\", `${name}.md`],\n    format: (c) => `---\\nname: /${c.name}\\n---\\n\\n${c.body}`,\n    skill: skillsIn(\".cursor\"),\n    detect: [\".cursor\"],\n  },\n  // Copilot prompt files: `.prompt.md` extension, description-only frontmatter.\n  // Detection cannot use `.github/` — almost every repo has one and almost none\n  // of them means Copilot — so it looks for the files Copilot itself reads.\n  \"github-copilot\": {\n    path: (name) => [\".github\", \"prompts\", `${name}.prompt.md`],\n    format: describedMd,\n    skill: skillsIn(\".github\"),\n    detect: [\n      \".github/copilot-instructions.md\",\n      \".github/instructions\",\n      \".github/prompts\",\n      \".github/agents\",\n      \".github/skills\",\n      \".github/workflows/copilot-setup-steps.yml\",\n      \".github/.mcp.json\",\n    ],\n  },\n  // Gemini: TOML, and a namespace DIRECTORY — `.gemini/commands/loam/check.toml`\n  // is invoked as `/loam:check`, so the file name drops the `loam-` prefix the\n  // flat-named tools carry.\n  gemini: {\n    path: (name) => [\".gemini\", \"commands\", \"loam\", `${unprefixed(name)}.toml`],\n    format: (c) =>\n      `description = \"${tomlLine(c.description)}\"\\nprompt = \"\"\"\\n${tomlBlock(c.body)}\"\"\"`,\n    skill: skillsIn(\".gemini\"),\n    detect: [\".gemini\"],\n  },\n  opencode: {\n    path: (name) => [\".opencode\", \"commands\", `${name}.md`],\n    format: describedMd,\n    skill: skillsIn(\".opencode\"),\n    detect: [\".opencode\"],\n  },\n  // Cline reads workflows from `.clinerules/` — plain markdown, no frontmatter —\n  // but its skills from `.cline/`. The two directories are unrelated, so both\n  // count as a sighting.\n  cline: {\n    path: (name) => [\".clinerules\", \"workflows\", `${name}.md`],\n    format: (c) => `# ${c.name}\\n\\n${c.body}`,\n    skill: skillsIn(\".cline\"),\n    detect: [\".cline\", \".clinerules\"],\n  },\n  // Amazon Q surfaces these as its PROMPT library, not as commands: the file is\n  // invoked `@loam-check`, never `/loam-check`. Same file shape regardless.\n  \"amazon-q\": {\n    path: (name) => [\".amazonq\", \"prompts\", `${name}.md`],\n    format: describedMd,\n    skill: skillsIn(\".amazonq\"),\n    detect: [\".amazonq\"],\n  },\n  // Antigravity's directory is `.agent/`, which is why the id and the directory\n  // do not match here as they do almost everywhere else.\n  antigravity: {\n    path: (name) => [\".agent\", \"workflows\", `${name}.md`],\n    format: describedMd,\n    skill: skillsIn(\".agent\"),\n    detect: [\".agent\"],\n  },\n  // Auggie is the Augment CLI: id `auggie`, directory `.augment/`.\n  auggie: {\n    path: (name) => [\".augment\", \"commands\", `${name}.md`],\n    format: hintedMd,\n    skill: skillsIn(\".augment\"),\n    detect: [\".augment\"],\n  },\n  // Skills-only, deliberately: Codex reads `.codex/skills/` and does not load\n  // custom command files, so it declares no command emitter at all rather than\n  // laying down files nothing will ever open.\n  codex: {\n    skill: skillsIn(\".codex\"),\n    detect: [\".codex\"],\n  },\n  // Continue's prompt files take a bare `.prompt` extension, and `invokable`\n  // is what promotes one from a template to something you can call.\n  continue: {\n    path: (name) => [\".continue\", \"prompts\", `${name}.prompt`],\n    format: (c) =>\n      `---\\nname: ${c.name}\\ndescription: ${c.description}\\ninvokable: true\\n---\\n\\n${c.body}`,\n    skill: skillsIn(\".continue\"),\n    detect: [\".continue\"],\n  },\n  // Crush namespaces like Gemini does — `.crush/commands/loam/check.md` is\n  // `/loam:check` — but stays markdown.\n  crush: {\n    path: (name) => [\".crush\", \"commands\", \"loam\", `${unprefixed(name)}.md`],\n    format: namedMd,\n    skill: skillsIn(\".crush\"),\n    detect: [\".crush\"],\n  },\n  // Devin Desktop, formerly Windsurf: Cascade-style workflows, and the rename\n  // moved the directory from `.windsurf/` to `.devin/`. New files go to the new\n  // directory; a repo still holding the old one is still a Devin repo, so both\n  // are sightings.\n  devin: {\n    path: (name) => [\".devin\", \"workflows\", `${name}.md`],\n    format: namedMd,\n    skill: skillsIn(\".devin\"),\n    detect: [\".devin\", \".windsurf\"],\n  },\n  factory: {\n    path: (name) => [\".factory\", \"commands\", `${name}.md`],\n    format: hintedMd,\n    skill: skillsIn(\".factory\"),\n    detect: [\".factory\"],\n  },\n  junie: {\n    path: (name) => [\".junie\", \"commands\", `${name}.md`],\n    format: describedMd,\n    skill: skillsIn(\".junie\"),\n    detect: [\".junie\"],\n  },\n  // Kilo Code workflows carry no frontmatter — the title line is all the\n  // wrapper there is.\n  kilocode: {\n    path: (name) => [\".kilocode\", \"workflows\", `${name}.md`],\n    format: titledMd,\n    skill: skillsIn(\".kilocode\"),\n    detect: [\".kilocode\"],\n  },\n  // Kiro uses Copilot's `.prompt.md` extension under its own directory.\n  kiro: {\n    path: (name) => [\".kiro\", \"prompts\", `${name}.prompt.md`],\n    format: describedMd,\n    skill: skillsIn(\".kiro\"),\n    detect: [\".kiro\"],\n  },\n  // Qwen Code retired its TOML commands in favour of markdown + frontmatter,\n  // so this is markdown despite the Gemini lineage.\n  qwen: {\n    path: (name) => [\".qwen\", \"commands\", `${name}.md`],\n    format: describedMd,\n    skill: skillsIn(\".qwen\"),\n    detect: [\".qwen\"],\n  },\n  // Roo/Zoo Code: id `roocode`, directory `.roo/`, no frontmatter.\n  roocode: {\n    path: (name) => [\".roo\", \"commands\", `${name}.md`],\n    format: titledMd,\n    skill: skillsIn(\".roo\"),\n    detect: [\".roo\"],\n  },\n  trae: {\n    path: (name) => [\".trae\", \"commands\", `${name}.md`],\n    format: namedMd,\n    skill: skillsIn(\".trae\"),\n    detect: [\".trae\"],\n  },\n  // The vendor-neutral skills root, and the only id here that names no vendor.\n  // `.agents/skills/<name>/SKILL.md` is read by six of the tools that already\n  // have entries above, each documenting it in its own words:\n  //\n  //   Cursor — \"Skills are automatically loaded from `.agents/skills/`,\n  //     `.cursor/skills/`, `~/.agents/skills/` … and `~/.cursor/skills/`\"\n  //     (Agent Skills, cursor.com/docs/skills).\n  //   GitHub Copilot — \"For project skills, specific to a single repository,\n  //     create a `.github/skills`, `.claude/skills`, or `.agents/skills`\n  //     directory in your repository\" (Adding agent skills for GitHub Copilot,\n  //     docs.github.com/en/copilot → customize-cloud-agent/add-skills).\n  //   Codex — \"Codex scans `.agents/skills` in every directory from your\n  //     current working directory up to the repository root\" (Build skills,\n  //     developers.openai.com/codex/skills).\n  //   Gemini CLI — `.agents/skills/` is the workspace-tier alias for\n  //     `.gemini/skills/`, and \"within the same tier … takes precedence over\n  //     the `.gemini/skills/` directory\" (docs/cli/skills.md in\n  //     google-gemini/gemini-cli).\n  //   Zed — \"Skills are loaded from `~/.agents/skills/` and\n  //     `<worktree>/.agents/skills/` only\" (Agent Skills, zed.dev/docs/ai/skills).\n  //   Roo Code — `.agents/skills/` is its cross-agent project location, ranked\n  //     below `.roo/skills/` at the same level (Skills,\n  //     docs.roocode.com/features/skills).\n  //\n  // Skills only, for the reason spelled out on `codex`: not one of those six\n  // documents a COMMAND file under this root, so a `.agents/commands/` would be\n  // files nothing will ever open — the thing this entry exists to stop.\n  //\n  // Purely ADDITIVE, and that is the design rather than an implementation\n  // detail. No tool above loses or re-points its own skill path: a repo already\n  // carrying `.claude/skills/` keeps getting them there. This entry is for the\n  // team that would rather have ONE copy those six read than six copies of the\n  // same bytes, and choosing that is the user's call — which is why selecting\n  // `agents` adds a target and never removes one.\n  //\n  // `detect` is `.agents/skills`, never a bare `.agents/`, for exactly\n  // `github-copilot`'s reason. `.agents/` is a shared root that other\n  // conventions also write into, so a bare marker would auto-scaffold into any\n  // repository where something else had made the directory — the failure that\n  // rules out `.github/` one entry up. It is also NOT `antigravity`'s\n  // `.agent/`: one letter apart, unrelated conventions, and `existsSync` on\n  // either says nothing about the other.\n  agents: {\n    skill: skillsIn(\".agents\"),\n    detect: [\".agents/skills\"],\n  },\n};\n"]}

package/dist/core/agent/workflows/adopt.js

@@ -0,0 +1,133 @@
+/** The adoption protocol: write one service's baseline docs from its code, as draft. */
+export const LOAM_ADOPT = {
+    name: "loam-adopt",
+    description: "Adopt a service — write its baseline docs from its code, as draft, then validate",
+    argumentHint: "<service-id>",
+    purpose: "Write one service's baseline documentation into the docs repo from its code, as `draft`. You read the code; loam states the work and checks the result — it never reads the service, so anything you cannot show, do not write.",
+    invocation: "loam instructions loam-adopt $1",
+    placeholders: ["service"],
+    spine: [
+        "wire this repo (`loam init`, then `loam doctor`) if it has no ./loam.json yet",
+        "`loam adopt` — the brief: the order to read the service in, every file to write, the grammar of each, and what the fleet map already says",
+        "walk the service in the brief's order — shape first, then one surface at a time — keeping the list of every path you open, because that list becomes `sources`",
+        "write the artifacts, everything `status: draft`",
+        "validate the service, then validate the whole fleet — a baseline that passes one and fails the other is documented and invisible",
+        "hand back with what you could not determine from the code, which directories you never opened, the branch-to-scenario count per operation, and three behaviours your documents do not describe — then let a human vouch",
+    ],
+    body: `Write one service's baseline documentation into the loam docs repo (its path is
+\`docsDir\` in ./loam.json). You read the code; loam states the work and checks the
+result. It never reads the service — so anything you cannot show, do not write.
+
+**The bar this artifact set aims at is reproducibility**: a reader should be able
+to answer, from these files alone — what this boundary exposes, what it reaches,
+what shapes it exchanges, how it is run, and what pages whom — without opening
+the code. \`loam validate\` grades form and joins, never depth: green means the
+files agree with each other, and the bar is what "done" is measured against — a
+thin baseline that validates is thin, not done.
+
+0. If there is no ./loam.json here, wire the repo first:
+   \`loam init --docs <path-to-docs-repo> --service $1\` (add \`--create\` ONLY if the
+   docs repo does not exist yet), then \`loam doctor\` — it resolves \`docsDir\`,
+   checks the docs repo is one, and reports the service binding. Do not go on with
+   \`docs-missing\`, \`services-missing\` or any \`doctor.*\` blocker standing.
+   Every \`doctor\` finding carries a \`fix\` field spelling the exact command —
+   type that, not an approximation of it.
+   If this repo is already wired, \`loam status --json\` in the docs repo is the
+   fastest way to see whether $1 is even the service that owes work next: its
+   \`next.adopt\` entries name the services with nothing written down yet.
+1. \`loam adopt --service $1 --json\`. That output IS the brief:
+   - \`warnings[]\` — read these FIRST. A near-miss against an existing service id
+     usually means \`$1\` is a typo, and a brief followed to the letter then produces
+     a complete, validating baseline for a service that does not exist.
+   - \`targets[]\` — every file to write. \`action: "diff"\` means the file ALREADY EXISTS:
+     read it, diff your findings against it, report what disagrees. Do not replace it.
+     \`action: "edit"\` appears on exactly one target — \`architecture/landscape.likec4\`,
+     the WHOLE FLEET's map: add this service's element and edges to it, never rewrite it.
+   - \`targets[].shape\` — the grammar of each artifact, and \`example\` where one is
+     shorter than a description. Every rule there is one a later check depends on;
+     rules nothing checks are in \`unchecked[]\` instead, and are still worth following.
+   - \`landscape\` — the elements and edges the fleet already has for this service.
+     Bind to them; do not draw a second version of the same box. \`landscape.expects\`
+     lists operations other services already call — your openapi.yaml owes them.
+     \`landscape.instruction\` is the write the fleet map still owes this service; it
+     is \`null\` once an element resolves to it, and only then.
+   - \`frontmatter\` — what to put in the header of every markdown artifact.
+   - \`checks[]\` — what \`loam validate\` will run. \`unchecked[]\` — what it will not.
+2. Read \`AGENTS.md\` at the docs repo root, then walk the service — \`walk[]\` in the
+   same \`adopt\` output is the order, and it is an order, not a menu. Each stop
+   names what to open, what to take from it, and which artifacts it feeds
+   (\`lands\`). The first two stops fix what the service IS — how many processes,
+   built from what — before any surface is enumerated: an agent that opens the
+   HTTP routes first has already decided the service is an API by the time it
+   meets the scheduler, and the consumer group and the outbox never get written
+   down. Do not stop at the surface you recognise fastest.
+   \`walkClose\` is the question that ends it: **list the directories you did not
+   open.** Nothing downstream can find a service you documented a third of —
+   \`api.ungoverned\` grades the operations you WROTE, and is silent about the twelve
+   you never did.
+   **Keep a list of every path you actually open.** That list becomes \`sources\` —
+   written as files and directories, never glob patterns — and it is the only line
+   tying the document to the repository. Never pad it with paths you did not read:
+   it is a record, and \`loam vouch\` hashes exactly what it names.
+3. Write the artifacts under \`services/$1/\`, in the order the brief lists them, and
+   make the landscape edit the brief asks for.
+   Everything \`status: draft\`. Never write \`last_verified\`, \`sources_digest\`,
+   \`content_digest\` or \`sources_files\`.
+4. \`loam validate --service $1 --json\`. Fix every error. \`sources.unvouched\` is
+   expected on a fresh baseline — it closes when a person vouches, not when you do.
+   \`sources.unwalked\` is the walk graded against the repository: its \`details\` name
+   the top-level paths git tracks and \`sources\` never reached into. Treat each one
+   as a place to go back to, not as a line to silence — the fix is reading it, or
+   one sentence in step 6 saying why this document does not owe it.
+5. \`loam validate --all --json\` in the docs repo. This is the run that grades the
+   fleet map: \`landscape.service-unmodelled\` means the element never landed,
+   \`landscape.binding-unknown\` / \`landscape.binding-duplicate\` mean it landed wrong,
+   and \`landscape.missing\` means there is no map at all. A baseline that passes step 4
+   and fails this one is documented and invisible.
+   Done, stated once: step 4 clean when run from inside the service's own repo, and
+   this run reporting no \`landscape.*\` finding. The fleet run is never SILENT —
+   \`sources.unverifiable-from-here\` (severity ok) appears per service as a
+   confirmation, not work — so "keep going until validation is quiet" is the wrong
+   loop; the two runs are the test.
+6. Hand back, and say seven things:
+   - what you could not determine from the code;
+   - what the existing artifacts disagreed with;
+   - which parts you are least sure of;
+   - what you did not open — every path \`sources.unwalked\` named, with one line
+     each on why the baseline does not owe it. That list is the only account
+     anybody gets of how much of the service was actually read; loam can name the
+     paths, and it can never say whether skipping one was right;
+   - **two counts per operation**: how many decisions its code makes — permission
+     checks, conditionally required fields, defaults and normalisations, refused
+     transitions — and how many scenarios you wrote for it.
+     \`12 branches / 3 scenarios\` is a fact a reader can act on; "the
+     requirements look complete" is not, and no check loam has can tell the two
+     apart;
+   - **how well this service is covered by its own tests**, and how many of them
+     became scenarios. Say the number the service's own coverage tooling
+     reports, and where you read it. This is the ceiling on the whole baseline:
+     a well-covered service can be documented from evidence, and a service with
+     almost no tests can only be documented from a reading of its code, which is
+     a weaker document however carefully it is written. Nothing in loam can
+     compute this — say it, or nobody ever knows which kind they are holding;
+   - **three behaviours this service has that your documents do not describe.**
+     Not "is this enough" — that question is answered yes by every agent that
+     ever wrote a baseline, including the ones that documented a third of a
+     service, because the only thing it can be answered against is the document
+     itself. Name three. If you looked for three and found none, say exactly
+     that: it is a claim a reviewer can go and check, which "it is complete"
+     is not.
+   Then a human runs \`loam vouch --service $1\` in the service's own repo.
+
+An empty docs repo's \`loam status --json\` names this recipe's own states as its
+first-hour ladder: \`next.author-landscape\` (the fleet map is missing, or still the
+scaffold's untouched bytes — step 3's landscape edit is what discharges it),
+\`next.bind-service\` (no service repository is wired to the fleet yet — step 0) and
+\`next.adopt-first\` (services/ is empty — this protocol, from step 1). Landing on
+one of those codes means: run this recipe, starting at the step it points at.
+
+Where the code does not say, write that it does not say. A confident sentence about
+behaviour nobody can find is the one failure mode none of loam's checks can catch.
+`,
+};
+//# sourceMappingURL=adopt.js.map

package/dist/core/agent/workflows/adopt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adopt.js","sourceRoot":"","sources":["../../../../src/core/agent/workflows/adopt.ts"],"names":[],"mappings":"AAEA,wFAAwF;AACxF,MAAM,CAAC,MAAM,UAAU,GAAmB;IACxC,IAAI,EAAE,YAAY;IAClB,WAAW,EACT,kFAAkF;IACpF,YAAY,EAAE,cAAc;IAC5B,OAAO,EACL,iOAAiO;IACnO,UAAU,EAAE,iCAAiC;IAC7C,YAAY,EAAE,CAAC,SAAS,CAAC;IACzB,KAAK,EAAE;QACL,+EAA+E;QAC/E,2IAA2I;QAC3I,gKAAgK;QAChK,iDAAiD;QACjD,kIAAkI;QAClI,yNAAyN;KAC1N;IACD,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkHP;CACA,CAAC","sourcesContent":["import type { CommandContent } from \"../contract.js\";\n\n/** The adoption protocol: write one service's baseline docs from its code, as draft. */\nexport const LOAM_ADOPT: CommandContent = {\n  name: \"loam-adopt\",\n  description:\n    \"Adopt a service — write its baseline docs from its code, as draft, then validate\",\n  argumentHint: \"<service-id>\",\n  purpose:\n    \"Write one service's baseline documentation into the docs repo from its code, as `draft`. You read the code; loam states the work and checks the result — it never reads the service, so anything you cannot show, do not write.\",\n  invocation: \"loam instructions loam-adopt $1\",\n  placeholders: [\"service\"],\n  spine: [\n    \"wire this repo (`loam init`, then `loam doctor`) if it has no ./loam.json yet\",\n    \"`loam adopt` — the brief: the order to read the service in, every file to write, the grammar of each, and what the fleet map already says\",\n    \"walk the service in the brief's order — shape first, then one surface at a time — keeping the list of every path you open, because that list becomes `sources`\",\n    \"write the artifacts, everything `status: draft`\",\n    \"validate the service, then validate the whole fleet — a baseline that passes one and fails the other is documented and invisible\",\n    \"hand back with what you could not determine from the code, which directories you never opened, the branch-to-scenario count per operation, and three behaviours your documents do not describe — then let a human vouch\",\n  ],\n  body: `Write one service's baseline documentation into the loam docs repo (its path is\n\\`docsDir\\` in ./loam.json). You read the code; loam states the work and checks the\nresult. It never reads the service — so anything you cannot show, do not write.\n\n**The bar this artifact set aims at is reproducibility**: a reader should be able\nto answer, from these files alone — what this boundary exposes, what it reaches,\nwhat shapes it exchanges, how it is run, and what pages whom — without opening\nthe code. \\`loam validate\\` grades form and joins, never depth: green means the\nfiles agree with each other, and the bar is what \"done\" is measured against — a\nthin baseline that validates is thin, not done.\n\n0. If there is no ./loam.json here, wire the repo first:\n   \\`loam init --docs <path-to-docs-repo> --service $1\\` (add \\`--create\\` ONLY if the\n   docs repo does not exist yet), then \\`loam doctor\\` — it resolves \\`docsDir\\`,\n   checks the docs repo is one, and reports the service binding. Do not go on with\n   \\`docs-missing\\`, \\`services-missing\\` or any \\`doctor.*\\` blocker standing.\n   Every \\`doctor\\` finding carries a \\`fix\\` field spelling the exact command —\n   type that, not an approximation of it.\n   If this repo is already wired, \\`loam status --json\\` in the docs repo is the\n   fastest way to see whether $1 is even the service that owes work next: its\n   \\`next.adopt\\` entries name the services with nothing written down yet.\n1. \\`loam adopt --service $1 --json\\`. That output IS the brief:\n   - \\`warnings[]\\` — read these FIRST. A near-miss against an existing service id\n     usually means \\`$1\\` is a typo, and a brief followed to the letter then produces\n     a complete, validating baseline for a service that does not exist.\n   - \\`targets[]\\` — every file to write. \\`action: \"diff\"\\` means the file ALREADY EXISTS:\n     read it, diff your findings against it, report what disagrees. Do not replace it.\n     \\`action: \"edit\"\\` appears on exactly one target — \\`architecture/landscape.likec4\\`,\n     the WHOLE FLEET's map: add this service's element and edges to it, never rewrite it.\n   - \\`targets[].shape\\` — the grammar of each artifact, and \\`example\\` where one is\n     shorter than a description. Every rule there is one a later check depends on;\n     rules nothing checks are in \\`unchecked[]\\` instead, and are still worth following.\n   - \\`landscape\\` — the elements and edges the fleet already has for this service.\n     Bind to them; do not draw a second version of the same box. \\`landscape.expects\\`\n     lists operations other services already call — your openapi.yaml owes them.\n     \\`landscape.instruction\\` is the write the fleet map still owes this service; it\n     is \\`null\\` once an element resolves to it, and only then.\n   - \\`frontmatter\\` — what to put in the header of every markdown artifact.\n   - \\`checks[]\\` — what \\`loam validate\\` will run. \\`unchecked[]\\` — what it will not.\n2. Read \\`AGENTS.md\\` at the docs repo root, then walk the service — \\`walk[]\\` in the\n   same \\`adopt\\` output is the order, and it is an order, not a menu. Each stop\n   names what to open, what to take from it, and which artifacts it feeds\n   (\\`lands\\`). The first two stops fix what the service IS — how many processes,\n   built from what — before any surface is enumerated: an agent that opens the\n   HTTP routes first has already decided the service is an API by the time it\n   meets the scheduler, and the consumer group and the outbox never get written\n   down. Do not stop at the surface you recognise fastest.\n   \\`walkClose\\` is the question that ends it: **list the directories you did not\n   open.** Nothing downstream can find a service you documented a third of —\n   \\`api.ungoverned\\` grades the operations you WROTE, and is silent about the twelve\n   you never did.\n   **Keep a list of every path you actually open.** That list becomes \\`sources\\` —\n   written as files and directories, never glob patterns — and it is the only line\n   tying the document to the repository. Never pad it with paths you did not read:\n   it is a record, and \\`loam vouch\\` hashes exactly what it names.\n3. Write the artifacts under \\`services/$1/\\`, in the order the brief lists them, and\n   make the landscape edit the brief asks for.\n   Everything \\`status: draft\\`. Never write \\`last_verified\\`, \\`sources_digest\\`,\n   \\`content_digest\\` or \\`sources_files\\`.\n4. \\`loam validate --service $1 --json\\`. Fix every error. \\`sources.unvouched\\` is\n   expected on a fresh baseline — it closes when a person vouches, not when you do.\n   \\`sources.unwalked\\` is the walk graded against the repository: its \\`details\\` name\n   the top-level paths git tracks and \\`sources\\` never reached into. Treat each one\n   as a place to go back to, not as a line to silence — the fix is reading it, or\n   one sentence in step 6 saying why this document does not owe it.\n5. \\`loam validate --all --json\\` in the docs repo. This is the run that grades the\n   fleet map: \\`landscape.service-unmodelled\\` means the element never landed,\n   \\`landscape.binding-unknown\\` / \\`landscape.binding-duplicate\\` mean it landed wrong,\n   and \\`landscape.missing\\` means there is no map at all. A baseline that passes step 4\n   and fails this one is documented and invisible.\n   Done, stated once: step 4 clean when run from inside the service's own repo, and\n   this run reporting no \\`landscape.*\\` finding. The fleet run is never SILENT —\n   \\`sources.unverifiable-from-here\\` (severity ok) appears per service as a\n   confirmation, not work — so \"keep going until validation is quiet\" is the wrong\n   loop; the two runs are the test.\n6. Hand back, and say seven things:\n   - what you could not determine from the code;\n   - what the existing artifacts disagreed with;\n   - which parts you are least sure of;\n   - what you did not open — every path \\`sources.unwalked\\` named, with one line\n     each on why the baseline does not owe it. That list is the only account\n     anybody gets of how much of the service was actually read; loam can name the\n     paths, and it can never say whether skipping one was right;\n   - **two counts per operation**: how many decisions its code makes — permission\n     checks, conditionally required fields, defaults and normalisations, refused\n     transitions — and how many scenarios you wrote for it.\n     \\`12 branches / 3 scenarios\\` is a fact a reader can act on; \"the\n     requirements look complete\" is not, and no check loam has can tell the two\n     apart;\n   - **how well this service is covered by its own tests**, and how many of them\n     became scenarios. Say the number the service's own coverage tooling\n     reports, and where you read it. This is the ceiling on the whole baseline:\n     a well-covered service can be documented from evidence, and a service with\n     almost no tests can only be documented from a reading of its code, which is\n     a weaker document however carefully it is written. Nothing in loam can\n     compute this — say it, or nobody ever knows which kind they are holding;\n   - **three behaviours this service has that your documents do not describe.**\n     Not \"is this enough\" — that question is answered yes by every agent that\n     ever wrote a baseline, including the ones that documented a third of a\n     service, because the only thing it can be answered against is the document\n     itself. Name three. If you looked for three and found none, say exactly\n     that: it is a claim a reviewer can go and check, which \"it is complete\"\n     is not.\n   Then a human runs \\`loam vouch --service $1\\` in the service's own repo.\n\nAn empty docs repo's \\`loam status --json\\` names this recipe's own states as its\nfirst-hour ladder: \\`next.author-landscape\\` (the fleet map is missing, or still the\nscaffold's untouched bytes — step 3's landscape edit is what discharges it),\n\\`next.bind-service\\` (no service repository is wired to the fleet yet — step 0) and\n\\`next.adopt-first\\` (services/ is empty — this protocol, from step 1). Landing on\none of those codes means: run this recipe, starting at the step it points at.\n\nWhere the code does not say, write that it does not say. A confident sentence about\nbehaviour nobody can find is the one failure mode none of loam's checks can catch.\n`,\n};\n"]}