@ybotok/loam 0.1.0-beta.3 → 0.2.0-alpha.13

package/dist/core/agent/support/report.js

@@ -0,0 +1,144 @@
+/**
+ * The incident-reporting protocol: preserve a small, sanitized reproducer when
+ * loam or its agent integration behaves unexpectedly, without turning loam
+ * into a telemetry service or retrying a risky write.
+ */
+export const LOAM_REPORT = {
+    name: "loam-report",
+    description: "Record unexpected loam or agent behavior as a sanitized, reproducible Markdown report",
+    argumentHint: "",
+    purpose: "Collect one unexpected loam or agent-integration incident into a separate, reviewable Markdown file. This is local diagnostics only: redact secrets, never upload automatically, and never repeat a writer merely to reproduce it.",
+    invocation: "loam instructions loam-report",
+    placeholders: [],
+    spine: [
+        "preserve the user's original symptom and expected result before investigating",
+        "collect the binary version, wiring diagnosis and the smallest safe reproduction",
+        "classify the failure without repairing, retrying a writer or changing project documents",
+        "sanitize commands, paths and output, then write one report under loam-reports/",
+        "hand back the report path, classification and any evidence that could not be collected",
+    ],
+    body: `Record one incident where loam, a generated command/skill, or the agent following it
+behaved unexpectedly. The result is a local diagnostic document, not a repair and not telemetry.
+Do not change architecture/spec files while collecting it.
+
+## Preserve the symptom first
+
+Before running anything, write down the user's original request, what they expected, what actually
+happened, the command or chat entry point involved, and whether any files may already have changed.
+Do not improve or reinterpret the failing command yet: a cleaned-up command is not a reproduction.
+
+Classify the incident as one of these, using \`inconclusive\` until the evidence supports another:
+
+- \`loam-product\` — the binary violated its documented contract or produced internally inconsistent output;
+- \`project-data\` — the binary correctly reported invalid, incomplete or stale repository documents;
+- \`agent-workflow\` — the generated command/skill was missing, stale, misrouted or followed incorrectly;
+- \`host-infrastructure\` — permissions, filesystem, process, shell or tool-host behavior prevented the run;
+- \`inconclusive\` — the available evidence does not distinguish the above.
+
+## Collect only safe evidence
+
+1. Run \`loam --version\` and record the result.
+2. Run \`loam doctor --json\`. If it succeeds, keep \`healthy\`, the finding codes and their structured
+   locations/fixes, the resolved repository role, and the write-path state. If it refuses, keep
+   \`error.code\` and the sanitized message. Do not apply the fixes during reporting.
+3. When the repository is wired, run \`loam status --json\` and keep only the state and next-action
+   rows relevant to this incident. A refusal is evidence too; keep its \`error.code\`.
+4. Re-run the original operation only when it is read-only and safe. Never re-run \`init\`, \`new\`,
+   \`rebase\`, \`subsystem\`, \`archive\`, \`unarchive\`, \`vouch\`, a recording form of \`verify\`, or
+   any other writer merely to make it fail twice. For a writer, record its original exit/output and
+   inspect \`doctor\`, \`status\` and version only. Do not repair, roll back or delete anything unless
+   the user separately asks for that action.
+5. Prefer the JSON envelope: record \`contractVersion\`, \`ok\`, \`command\`, \`error.code\`, finding
+   codes and \`locations[]\`. Quote only the smallest stdout/stderr excerpt that demonstrates the
+   symptom. State what was omitted.
+
+## Sanitize before writing
+
+Never include credentials, tokens, cookies, authorization headers, private keys, environment dumps,
+or values of variables whose names contain \`TOKEN\`, \`SECRET\`, \`PASSWORD\`, \`AUTH\`, \`COOKIE\` or
+\`KEY\`. Replace each value with \`<redacted>\`. Replace the user's home directory with \`<home>\` and
+prefer repository-relative paths. Do not copy source files, architecture/spec bodies, or a complete
+command output when a code and short excerpt prove the same fact. Review the finished report once
+more for secrets before handing it back.
+
+The fleet's own names are often confidential too: its services, topics, messages, operation ids and
+requirement ids. Write \`Minimal safe reproduction\` on neutral stand-ins — an order service, a
+payment service, a broker topic, a store — rebuilt until it shows the same finding or refusal, so the
+report can travel without the fleet. Where the excerpt under \`Actual\` must quote the fleet's own
+output, say in \`Sanitization\` that it does, so that whoever forwards the report knows that
+section stays behind.
+
+## Write one separate report
+
+Create \`loam-reports/NNN-YYYY-MM-DD-<short-slug>.md\` in the directory holding the \`loam.json\` that
+resolved — or, when a \`loam.json\` was found but does not parse, beside that file, so a report about
+the broken config joins the corpus already there; only when there is no config file at or above you
+is it the directory you run in.
+\`loam doctor --json\` hands you that whole directory — that root WITH \`loam-reports/\`
+already on the end — as \`reports.dir\`: write inside the path it gives, never joined onto
+\`loam-reports/\` a second time. \`NNN\` is an ordinal of at least three digits, zero-padded, one more
+than the highest already in that directory — read \`reports.next\` from the same output, which says
+\`001\` when the directory is empty or absent, and widens past three digits rather than reusing a
+number once the corpus gets there. Use a short neutral slug based on the symptom, not a customer,
+person or secret. Never
+overwrite a different incident: a path that already exists means a concurrent report claimed that
+ordinal, so take the next one rather than adding a suffix. That check is on the PATH, and the
+promise is about the ordinal, so re-run \`loam doctor --json\` after writing: if two entries carry
+the same \`ordinal\`, the one with the later \`Recorded\` timestamp renames itself to the next free
+number. The ordinal is the report's handle —
+cite one by its number in a commit message, an issue, or another report's cross-references, and
+never by filename, which is free to be renamed. The ordinal is unique within that directory, not
+across a fleet: a service repository and the docs repository each number their own, so when two
+repositories are in play cite \`<repo>/loam-reports/NNN\`.
+
+Reports are ordinary project files so the team can review or commit them deliberately, but
+do not upload, submit an issue, send telemetry, or contact any service automatically.
+\`loam doctor\` reads the directory — how many reports it holds, how many are in each status, and
+which ordinal comes next — and that is a local read of local files: nothing is transmitted.
+
+Use this shape, omitting only fields that truly cannot be known and marking them \`not collected\`:
+
+    # loam problem report: <short title>
+
+    - Recorded: <ISO-8601 timestamp>
+    - Classification: <one value above>
+    - Status: open
+    - Repository role: <docs | service | combined | unresolved>
+    - loam version: <version>
+    - Entry point: <chat command, skill, or CLI command; sanitized>
+    - Side effects observed: <none known | paths changed | unknown>
+
+    ## Summary
+    ## Expected
+    ## Actual
+    ## Minimal safe reproduction
+    ## Machine contract
+    ## Doctor and status evidence
+    ## Files changed or write state
+    ## Workaround
+    ## Missing evidence
+    ## Sanitization
+
+\`Status\` is written as \`open\` and stays the report's own record of where it got to. The vocabulary
+is \`open\`, \`sent\` (handed to loam's author — the person forwarding a report sets this, never the
+agent writing it), \`fixed in <version>\`, and \`superseded by <NNN>\` naming the report that
+replaced this one. Close a report by editing its own \`Status\` line: there is no index to keep in
+step, and \`loam doctor\` counts the directory by reading that line's first word, so
+\`fixed in 0.2.0-alpha.5\` counts as fixed. It reads that line from the HEADER FIELD BLOCK only —
+the lines above the first \`##\` heading, quoted code skipped in either markdown spelling: a fence
+(closed only by a run of the same character at least as long as the one that opened it, so a
+\`\`\` inside a \`\`\`\` block is content) and an indented block, which is the shape THIS template is
+printed in above. So a report that quotes this template, however it quotes it, still counts as
+whatever its own header says. A report written before this
+field existed has no \`Status\` line and counts as unstated.
+
+In \`Machine contract\`, include exit code plus the stable envelope fields and relevant finding
+codes/locations; do not paste an entire large JSON payload. In \`Sanitization\`, list the kinds of
+values removed without revealing them. If no workaround is known, say so rather than inventing one.
+
+Finish by telling the user the report path, classification, whether project files changed, and which
+evidence was unavailable. Keep diagnosis separate from certainty: a plausible cause belongs under
+\`Summary\` as a hypothesis until the reproduction proves it.
+`,
+};
+//# sourceMappingURL=report.js.map

package/dist/core/agent/support/report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../../../../src/core/agent/support/report.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAmB;IACzC,IAAI,EAAE,aAAa;IACnB,WAAW,EACT,uFAAuF;IACzF,YAAY,EAAE,EAAE;IAChB,OAAO,EACL,oOAAoO;IACtO,UAAU,EAAE,+BAA+B;IAC3C,YAAY,EAAE,EAAE;IAChB,KAAK,EAAE;QACL,+EAA+E;QAC/E,iFAAiF;QACjF,yFAAyF;QACzF,gFAAgF;QAChF,wFAAwF;KACzF;IACD,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0HP;CACA,CAAC","sourcesContent":["import type { CommandContent } from \"../contract.js\";\n\n/**\n * The incident-reporting protocol: preserve a small, sanitized reproducer when\n * loam or its agent integration behaves unexpectedly, without turning loam\n * into a telemetry service or retrying a risky write.\n */\nexport const LOAM_REPORT: CommandContent = {\n  name: \"loam-report\",\n  description:\n    \"Record unexpected loam or agent behavior as a sanitized, reproducible Markdown report\",\n  argumentHint: \"\",\n  purpose:\n    \"Collect one unexpected loam or agent-integration incident into a separate, reviewable Markdown file. This is local diagnostics only: redact secrets, never upload automatically, and never repeat a writer merely to reproduce it.\",\n  invocation: \"loam instructions loam-report\",\n  placeholders: [],\n  spine: [\n    \"preserve the user's original symptom and expected result before investigating\",\n    \"collect the binary version, wiring diagnosis and the smallest safe reproduction\",\n    \"classify the failure without repairing, retrying a writer or changing project documents\",\n    \"sanitize commands, paths and output, then write one report under loam-reports/\",\n    \"hand back the report path, classification and any evidence that could not be collected\",\n  ],\n  body: `Record one incident where loam, a generated command/skill, or the agent following it\nbehaved unexpectedly. The result is a local diagnostic document, not a repair and not telemetry.\nDo not change architecture/spec files while collecting it.\n\n## Preserve the symptom first\n\nBefore running anything, write down the user's original request, what they expected, what actually\nhappened, the command or chat entry point involved, and whether any files may already have changed.\nDo not improve or reinterpret the failing command yet: a cleaned-up command is not a reproduction.\n\nClassify the incident as one of these, using \\`inconclusive\\` until the evidence supports another:\n\n- \\`loam-product\\` — the binary violated its documented contract or produced internally inconsistent output;\n- \\`project-data\\` — the binary correctly reported invalid, incomplete or stale repository documents;\n- \\`agent-workflow\\` — the generated command/skill was missing, stale, misrouted or followed incorrectly;\n- \\`host-infrastructure\\` — permissions, filesystem, process, shell or tool-host behavior prevented the run;\n- \\`inconclusive\\` — the available evidence does not distinguish the above.\n\n## Collect only safe evidence\n\n1. Run \\`loam --version\\` and record the result.\n2. Run \\`loam doctor --json\\`. If it succeeds, keep \\`healthy\\`, the finding codes and their structured\n   locations/fixes, the resolved repository role, and the write-path state. If it refuses, keep\n   \\`error.code\\` and the sanitized message. Do not apply the fixes during reporting.\n3. When the repository is wired, run \\`loam status --json\\` and keep only the state and next-action\n   rows relevant to this incident. A refusal is evidence too; keep its \\`error.code\\`.\n4. Re-run the original operation only when it is read-only and safe. Never re-run \\`init\\`, \\`new\\`,\n   \\`rebase\\`, \\`subsystem\\`, \\`archive\\`, \\`unarchive\\`, \\`vouch\\`, a recording form of \\`verify\\`, or\n   any other writer merely to make it fail twice. For a writer, record its original exit/output and\n   inspect \\`doctor\\`, \\`status\\` and version only. Do not repair, roll back or delete anything unless\n   the user separately asks for that action.\n5. Prefer the JSON envelope: record \\`contractVersion\\`, \\`ok\\`, \\`command\\`, \\`error.code\\`, finding\n   codes and \\`locations[]\\`. Quote only the smallest stdout/stderr excerpt that demonstrates the\n   symptom. State what was omitted.\n\n## Sanitize before writing\n\nNever include credentials, tokens, cookies, authorization headers, private keys, environment dumps,\nor values of variables whose names contain \\`TOKEN\\`, \\`SECRET\\`, \\`PASSWORD\\`, \\`AUTH\\`, \\`COOKIE\\` or\n\\`KEY\\`. Replace each value with \\`<redacted>\\`. Replace the user's home directory with \\`<home>\\` and\nprefer repository-relative paths. Do not copy source files, architecture/spec bodies, or a complete\ncommand output when a code and short excerpt prove the same fact. Review the finished report once\nmore for secrets before handing it back.\n\nThe fleet's own names are often confidential too: its services, topics, messages, operation ids and\nrequirement ids. Write \\`Minimal safe reproduction\\` on neutral stand-ins — an order service, a\npayment service, a broker topic, a store — rebuilt until it shows the same finding or refusal, so the\nreport can travel without the fleet. Where the excerpt under \\`Actual\\` must quote the fleet's own\noutput, say in \\`Sanitization\\` that it does, so that whoever forwards the report knows that\nsection stays behind.\n\n## Write one separate report\n\nCreate \\`loam-reports/NNN-YYYY-MM-DD-<short-slug>.md\\` in the directory holding the \\`loam.json\\` that\nresolved — or, when a \\`loam.json\\` was found but does not parse, beside that file, so a report about\nthe broken config joins the corpus already there; only when there is no config file at or above you\nis it the directory you run in.\n\\`loam doctor --json\\` hands you that whole directory — that root WITH \\`loam-reports/\\`\nalready on the end — as \\`reports.dir\\`: write inside the path it gives, never joined onto\n\\`loam-reports/\\` a second time. \\`NNN\\` is an ordinal of at least three digits, zero-padded, one more\nthan the highest already in that directory — read \\`reports.next\\` from the same output, which says\n\\`001\\` when the directory is empty or absent, and widens past three digits rather than reusing a\nnumber once the corpus gets there. Use a short neutral slug based on the symptom, not a customer,\nperson or secret. Never\noverwrite a different incident: a path that already exists means a concurrent report claimed that\nordinal, so take the next one rather than adding a suffix. That check is on the PATH, and the\npromise is about the ordinal, so re-run \\`loam doctor --json\\` after writing: if two entries carry\nthe same \\`ordinal\\`, the one with the later \\`Recorded\\` timestamp renames itself to the next free\nnumber. The ordinal is the report's handle —\ncite one by its number in a commit message, an issue, or another report's cross-references, and\nnever by filename, which is free to be renamed. The ordinal is unique within that directory, not\nacross a fleet: a service repository and the docs repository each number their own, so when two\nrepositories are in play cite \\`<repo>/loam-reports/NNN\\`.\n\nReports are ordinary project files so the team can review or commit them deliberately, but\ndo not upload, submit an issue, send telemetry, or contact any service automatically.\n\\`loam doctor\\` reads the directory — how many reports it holds, how many are in each status, and\nwhich ordinal comes next — and that is a local read of local files: nothing is transmitted.\n\nUse this shape, omitting only fields that truly cannot be known and marking them \\`not collected\\`:\n\n    # loam problem report: <short title>\n\n    - Recorded: <ISO-8601 timestamp>\n    - Classification: <one value above>\n    - Status: open\n    - Repository role: <docs | service | combined | unresolved>\n    - loam version: <version>\n    - Entry point: <chat command, skill, or CLI command; sanitized>\n    - Side effects observed: <none known | paths changed | unknown>\n\n    ## Summary\n    ## Expected\n    ## Actual\n    ## Minimal safe reproduction\n    ## Machine contract\n    ## Doctor and status evidence\n    ## Files changed or write state\n    ## Workaround\n    ## Missing evidence\n    ## Sanitization\n\n\\`Status\\` is written as \\`open\\` and stays the report's own record of where it got to. The vocabulary\nis \\`open\\`, \\`sent\\` (handed to loam's author — the person forwarding a report sets this, never the\nagent writing it), \\`fixed in <version>\\`, and \\`superseded by <NNN>\\` naming the report that\nreplaced this one. Close a report by editing its own \\`Status\\` line: there is no index to keep in\nstep, and \\`loam doctor\\` counts the directory by reading that line's first word, so\n\\`fixed in 0.2.0-alpha.5\\` counts as fixed. It reads that line from the HEADER FIELD BLOCK only —\nthe lines above the first \\`##\\` heading, quoted code skipped in either markdown spelling: a fence\n(closed only by a run of the same character at least as long as the one that opened it, so a\n\\`\\`\\` inside a \\`\\`\\`\\` block is content) and an indented block, which is the shape THIS template is\nprinted in above. So a report that quotes this template, however it quotes it, still counts as\nwhatever its own header says. A report written before this\nfield existed has no \\`Status\\` line and counts as unstated.\n\nIn \\`Machine contract\\`, include exit code plus the stable envelope fields and relevant finding\ncodes/locations; do not paste an entire large JSON payload. In \\`Sanitization\\`, list the kinds of\nvalues removed without revealing them. If no workaround is known, say so rather than inventing one.\n\nFinish by telling the user the report path, classification, whether project files changed, and which\nevidence was unavailable. Keep diagnosis separate from certainty: a plausible cause belongs under\n\\`Summary\\` as a hypothesis until the reproduction proves it.\n`,\n};\n"]}

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

@@ -0,0 +1,151 @@
+/**
+ * The loam verbs a generated file pre-approves, so an agent that honors the
+ * field stops asking permission for each call. Everything else a command needs
+ * (Read, Write, the service's own test runner) stays under the user's normal
+ * permission settings, and a tool that does not know the field ignores it.
+ *
+ * Enumerated rather than spelled `Bash(loam:*)`, for one verb's sake. `vouch`
+ * is the only command in loam whose output is a claim about a HUMAN act — a
+ * person read the code and says the document matches it — and a blanket
+ * allowlist pre-approved it, which handed the agent that wrote a draft the
+ * power to promote its own draft to `verified` without anybody being asked.
+ * That inverts the argument loam makes everywhere else: it holds test evidence
+ * to "an agent must not be able to SAY a scenario is tested", and then let one
+ * say a spec matches the code. `vouch` now refuses without a terminal or
+ * `--yes` (commands/vouch.ts) — this list is the other half, so the refusal is
+ * something a person sees rather than something an agent routes around.
+ *
+ * A verb missing from this list is not forbidden, only unapproved: the agent
+ * asks, and the user says yes. That is the correct cost for this one.
+ *
+ * The rule the list obeys is **every verb the CLI registers except the keys of
+ * {@link UNAPPROVED}**, and it admits no silent third category: a verb is
+ * either here or there, with a written reason. The rule it does NOT obey is
+ * "read-only" — that is false of `subsystem`, which writes, and it was never
+ * what this list did anyway: `archive`, `rebase` and `new` all write, and all
+ * three have been on it since the day the wildcard came off.
+ *
+ * The rule is written down because a hand-kept list drifts, and this one had.
+ * Seventeen of the twenty-nine registered verbs were on it, and three of the
+ * twelve missing ones were instructed by loam's own protocols: `loam-implement`
+ * opens with `loam context` and calls `loam steps` mandatory before a step
+ * definition is written, and `loam-check`'s fix table says to run
+ * `loam subsystem sync`. Each stalled on a permission prompt at exactly the
+ * step its own protocol calls required. It was worst for `explain`: every
+ * generated file now tells the agent to read the protocol narrow
+ * (`loam instructions <workflow> --no-fix-tables`) and then look up the codes
+ * the run actually reported — so the one command that makes an 84 KB page
+ * payable was the one the skill could not invoke unasked.
+ */
+const LOAM_ALLOWED_VERBS = [
+    "adopt",
+    "archive",
+    "context",
+    "delta",
+    "dependencies",
+    "diff",
+    "doctor",
+    "explain",
+    "explore",
+    "gate",
+    "gherkin",
+    "init",
+    "instructions",
+    "list",
+    "new",
+    "rebase",
+    "show",
+    "status",
+    "steps",
+    "subsystem",
+    "tasks",
+    "unarchive",
+    "validate",
+    "verify",
+];
+/**
+ * The verbs deliberately left OFF {@link LOAM_ALLOWED_VERBS}, each with the
+ * reason it is off.
+ *
+ * A map rather than a paragraph, because "every verb but the named exclusions"
+ * is only a checkable rule if the exclusions are a VALUE. test/agents.test.ts
+ * reads this one: the emitted allowlist must equal the CLI's registered
+ * commands minus these keys, so an absent verb is either a decision recorded
+ * here or a test failure — never something nobody can tell from a forgotten
+ * one, which is what the previous list was. Only `vouch` had ever been reasoned
+ * in the source, and its reason is the paragraph above, unchanged.
+ *
+ * The equality is checked in the test layer and cannot be computed here:
+ * deriving the allowlist from the command registry would mean `core/`
+ * importing `commands/`, which AGENTS.md forbids outright.
+ */
+export const UNAPPROVED = {
+    "audit-openspec": "the OpenSpec on-ramp: a one-time migration a person drives against a foreign workspace, named by no workflow protocol",
+    mcp: "a long-running stdio server rather than a call that returns — an agent that starts it inside a step waits forever",
+    "migrate-openspec": "the same on-ramp, and `--apply` materializes a whole target tree from a mapping only a human can have filled in",
+    open: "writes a `.code-workspace` for a person's editor; the output is aimed at the human, and no protocol step reads it",
+    seed: "templates the fleet map from a human-authored fleet.yaml — who exists and who calls whom is the one thing no generator may state",
+    vouch: "a claim about a HUMAN act, so an agent must not be able to SAY a spec matches the code; the refusal has to be something a person sees rather than something an agent routes around",
+};
+const LOAM_ALLOWED_TOOLS = LOAM_ALLOWED_VERBS.map((v) => `Bash(loam ${v}:*)`).join(", ");
+/**
+ * Incident collection is intentionally narrower than a lifecycle workflow.
+ * The body names writers so an agent can recognize and avoid retrying them;
+ * inheriting the lifecycle allowlist would nevertheless pre-authorize those
+ * same writers while diagnosing a bad run. Version, doctor and status are the
+ * complete command set the reporting protocol asks to execute.
+ */
+const REPORT_ALLOWED_TOOLS = [
+    "Bash(loam --version)",
+    "Bash(loam doctor:*)",
+    "Bash(loam instructions:*)",
+    "Bash(loam status:*)",
+].join(", ");
+const skillAllowedTools = (c) => c.name === "loam-report" ? REPORT_ALLOWED_TOOLS : LOAM_ALLOWED_TOOLS;
+/**
+ * The Agent Skills convention loam EMITS: `<root>/skills/<name>/SKILL.md`, YAML
+ * frontmatter, then the shared body verbatim — where `<root>` is whatever the
+ * calling registry entry passes.
+ *
+ * It used to say that every tool in the registry which reads skills spells the
+ * path this way. That was an unevidenced universal, and the `agents` entry
+ * falsifies it: `.agents/skills/` is a vendor-neutral root several tools read
+ * INSTEAD of their own dot-directory, not another tool's directory. Where a
+ * path is documented by the tool, the citation lives on that tool's registry
+ * entry — this helper states only what it writes.
+ *
+ * `description` is load-bearing in a way no command file's is — it is the only
+ * thing the model sees before deciding whether to load the skill — so it comes
+ * from the same `CommandContent.description` the command wrappers use rather
+ * than a second, skill-flavoured copy that could drift into a better pitch for
+ * a worse protocol.
+ */
+export const skillsIn = (dir) => ({
+    path: (name) => [dir, "skills", name, "SKILL.md"],
+    format: (c) => `---\nname: ${c.name}\ndescription: ${c.description}\n` +
+        `allowed-tools: ${skillAllowedTools(c)}\n---\n\n${c.body}`,
+});
+/**
+ * TOML basic-string escapes for the one non-markdown format. Today's bodies
+ * carry neither backslashes nor `"""`, but the escape is what keeps a future
+ * body edit from silently corrupting the generated TOML.
+ */
+export const tomlLine = (s) => s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+export const tomlBlock = (s) => s.replace(/\\/g, "\\\\").replace(/"""/g, '""\\"');
+/* The four markdown command dialects the registry actually needs. Shared so a
+ * tool's entry is its PATH and its dialect's name — the part that differs —
+ * instead of a wall of near-identical template literals. `claude` deliberately
+ * spells its own wrapper inline even though `hintedMd` matches it byte for
+ * byte: an edit made here for some other tool must not be able to re-spell the
+ * one format that is frozen. */
+/** Description-only frontmatter — the most common dialect by a wide margin. */
+export const describedMd = (c) => `---\ndescription: ${c.description}\n---\n\n${c.body}`;
+/** Description plus Claude's `argument-hint`, for the tools that copied it. */
+export const hintedMd = (c) => `---\ndescription: ${c.description}\nargument-hint: ${c.argumentHint}\n---\n\n${c.body}`;
+/** Name plus description — the Cascade-style workflow frontmatter. */
+export const namedMd = (c) => `---\nname: ${c.name}\ndescription: ${c.description}\n---\n\n${c.body}`;
+/** No frontmatter at all: a title line is the whole wrapper. */
+export const titledMd = (c) => `# ${c.name}\n\n${c.body}`;
+/** The `loam-` prefix a namespace directory carries instead of the file name. */
+export const unprefixed = (name) => name.replace(/^loam-/, "");
+//# sourceMappingURL=dialects.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dialects.js","sourceRoot":"","sources":["../../../../src/core/agent/tools/dialects.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * How one shared command body is SPELLED per tool family: the markdown and\n * TOML wrapper dialects, and the Agent Skills convention. registry.ts builds\n * its entries from these — nothing here adds prose of its own, so the body\n * stays one source of truth however many tools spell it.\n */\nimport type { AgentFileEmitter, CommandContent } from \"../contract.js\";\n\n/**\n * The loam verbs a generated file pre-approves, so an agent that honors the\n * field stops asking permission for each call. Everything else a command needs\n * (Read, Write, the service's own test runner) stays under the user's normal\n * permission settings, and a tool that does not know the field ignores it.\n *\n * Enumerated rather than spelled `Bash(loam:*)`, for one verb's sake. `vouch`\n * is the only command in loam whose output is a claim about a HUMAN act — a\n * person read the code and says the document matches it — and a blanket\n * allowlist pre-approved it, which handed the agent that wrote a draft the\n * power to promote its own draft to `verified` without anybody being asked.\n * That inverts the argument loam makes everywhere else: it holds test evidence\n * to \"an agent must not be able to SAY a scenario is tested\", and then let one\n * say a spec matches the code. `vouch` now refuses without a terminal or\n * `--yes` (commands/vouch.ts) — this list is the other half, so the refusal is\n * something a person sees rather than something an agent routes around.\n *\n * A verb missing from this list is not forbidden, only unapproved: the agent\n * asks, and the user says yes. That is the correct cost for this one.\n *\n * The rule the list obeys is **every verb the CLI registers except the keys of\n * {@link UNAPPROVED}**, and it admits no silent third category: a verb is\n * either here or there, with a written reason. The rule it does NOT obey is\n * \"read-only\" — that is false of `subsystem`, which writes, and it was never\n * what this list did anyway: `archive`, `rebase` and `new` all write, and all\n * three have been on it since the day the wildcard came off.\n *\n * The rule is written down because a hand-kept list drifts, and this one had.\n * Seventeen of the twenty-nine registered verbs were on it, and three of the\n * twelve missing ones were instructed by loam's own protocols: `loam-implement`\n * opens with `loam context` and calls `loam steps` mandatory before a step\n * definition is written, and `loam-check`'s fix table says to run\n * `loam subsystem sync`. Each stalled on a permission prompt at exactly the\n * step its own protocol calls required. It was worst for `explain`: every\n * generated file now tells the agent to read the protocol narrow\n * (`loam instructions <workflow> --no-fix-tables`) and then look up the codes\n * the run actually reported — so the one command that makes an 84 KB page\n * payable was the one the skill could not invoke unasked.\n */\nconst LOAM_ALLOWED_VERBS = [\n  \"adopt\",\n  \"archive\",\n  \"context\",\n  \"delta\",\n  \"dependencies\",\n  \"diff\",\n  \"doctor\",\n  \"explain\",\n  \"explore\",\n  \"gate\",\n  \"gherkin\",\n  \"init\",\n  \"instructions\",\n  \"list\",\n  \"new\",\n  \"rebase\",\n  \"show\",\n  \"status\",\n  \"steps\",\n  \"subsystem\",\n  \"tasks\",\n  \"unarchive\",\n  \"validate\",\n  \"verify\",\n] as const;\n\n/**\n * The verbs deliberately left OFF {@link LOAM_ALLOWED_VERBS}, each with the\n * reason it is off.\n *\n * A map rather than a paragraph, because \"every verb but the named exclusions\"\n * is only a checkable rule if the exclusions are a VALUE. test/agents.test.ts\n * reads this one: the emitted allowlist must equal the CLI's registered\n * commands minus these keys, so an absent verb is either a decision recorded\n * here or a test failure — never something nobody can tell from a forgotten\n * one, which is what the previous list was. Only `vouch` had ever been reasoned\n * in the source, and its reason is the paragraph above, unchanged.\n *\n * The equality is checked in the test layer and cannot be computed here:\n * deriving the allowlist from the command registry would mean `core/`\n * importing `commands/`, which AGENTS.md forbids outright.\n */\nexport const UNAPPROVED: Record<string, string> = {\n  \"audit-openspec\":\n    \"the OpenSpec on-ramp: a one-time migration a person drives against a foreign workspace, named by no workflow protocol\",\n  mcp: \"a long-running stdio server rather than a call that returns — an agent that starts it inside a step waits forever\",\n  \"migrate-openspec\":\n    \"the same on-ramp, and `--apply` materializes a whole target tree from a mapping only a human can have filled in\",\n  open: \"writes a `.code-workspace` for a person's editor; the output is aimed at the human, and no protocol step reads it\",\n  seed: \"templates the fleet map from a human-authored fleet.yaml — who exists and who calls whom is the one thing no generator may state\",\n  vouch:\n    \"a claim about a HUMAN act, so an agent must not be able to SAY a spec matches the code; the refusal has to be something a person sees rather than something an agent routes around\",\n};\n\nconst LOAM_ALLOWED_TOOLS = LOAM_ALLOWED_VERBS.map((v) => `Bash(loam ${v}:*)`).join(\", \");\n\n/**\n * Incident collection is intentionally narrower than a lifecycle workflow.\n * The body names writers so an agent can recognize and avoid retrying them;\n * inheriting the lifecycle allowlist would nevertheless pre-authorize those\n * same writers while diagnosing a bad run. Version, doctor and status are the\n * complete command set the reporting protocol asks to execute.\n */\nconst REPORT_ALLOWED_TOOLS = [\n  \"Bash(loam --version)\",\n  \"Bash(loam doctor:*)\",\n  \"Bash(loam instructions:*)\",\n  \"Bash(loam status:*)\",\n].join(\", \");\n\nconst skillAllowedTools = (c: CommandContent): string =>\n  c.name === \"loam-report\" ? REPORT_ALLOWED_TOOLS : LOAM_ALLOWED_TOOLS;\n\n/**\n * The Agent Skills convention loam EMITS: `<root>/skills/<name>/SKILL.md`, YAML\n * frontmatter, then the shared body verbatim — where `<root>` is whatever the\n * calling registry entry passes.\n *\n * It used to say that every tool in the registry which reads skills spells the\n * path this way. That was an unevidenced universal, and the `agents` entry\n * falsifies it: `.agents/skills/` is a vendor-neutral root several tools read\n * INSTEAD of their own dot-directory, not another tool's directory. Where a\n * path is documented by the tool, the citation lives on that tool's registry\n * entry — this helper states only what it writes.\n *\n * `description` is load-bearing in a way no command file's is — it is the only\n * thing the model sees before deciding whether to load the skill — so it comes\n * from the same `CommandContent.description` the command wrappers use rather\n * than a second, skill-flavoured copy that could drift into a better pitch for\n * a worse protocol.\n */\nexport const skillsIn = (dir: string): AgentFileEmitter => ({\n  path: (name) => [dir, \"skills\", name, \"SKILL.md\"],\n  format: (c) =>\n    `---\\nname: ${c.name}\\ndescription: ${c.description}\\n` +\n    `allowed-tools: ${skillAllowedTools(c)}\\n---\\n\\n${c.body}`,\n});\n\n/**\n * TOML basic-string escapes for the one non-markdown format. Today's bodies\n * carry neither backslashes nor `\"\"\"`, but the escape is what keeps a future\n * body edit from silently corrupting the generated TOML.\n */\nexport const tomlLine = (s: string): string => s.replace(/\\\\/g, \"\\\\\\\\\").replace(/\"/g, '\\\\\"');\nexport const tomlBlock = (s: string): string => s.replace(/\\\\/g, \"\\\\\\\\\").replace(/\"\"\"/g, '\"\"\\\\\"');\n\n/* The four markdown command dialects the registry actually needs. Shared so a\n * tool's entry is its PATH and its dialect's name — the part that differs —\n * instead of a wall of near-identical template literals. `claude` deliberately\n * spells its own wrapper inline even though `hintedMd` matches it byte for\n * byte: an edit made here for some other tool must not be able to re-spell the\n * one format that is frozen. */\n/** Description-only frontmatter — the most common dialect by a wide margin. */\nexport const describedMd = (c: CommandContent): string =>\n  `---\\ndescription: ${c.description}\\n---\\n\\n${c.body}`;\n/** Description plus Claude's `argument-hint`, for the tools that copied it. */\nexport const hintedMd = (c: CommandContent): string =>\n  `---\\ndescription: ${c.description}\\nargument-hint: ${c.argumentHint}\\n---\\n\\n${c.body}`;\n/** Name plus description — the Cascade-style workflow frontmatter. */\nexport const namedMd = (c: CommandContent): string =>\n  `---\\nname: ${c.name}\\ndescription: ${c.description}\\n---\\n\\n${c.body}`;\n/** No frontmatter at all: a title line is the whole wrapper. */\nexport const titledMd = (c: CommandContent): string => `# ${c.name}\\n\\n${c.body}`;\n\n/** The `loam-` prefix a namespace directory carries instead of the file name. */\nexport const unprefixed = (name: string): string => name.replace(/^loam-/, \"\");\n"]}

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

@@ -0,0 +1,193 @@
+import { describedMd, hintedMd, namedMd, skillsIn, titledMd, tomlBlock, tomlLine, unprefixed, } from "./dialects.js";
+/**
+ * The shape most entries share: `<dir>/<sub>/<name>.md` command files in the
+ * given dialect, skills under `<dir>/skills/`, and the tool's own dot-directory
+ * as its one sighting. An entry that departs from any of the three — another
+ * extension, a namespace directory, a second marker, no commands at all — is
+ * written out in full below, so the departure is what its entry shows.
+ */
+function dotTool(dir, sub, format) {
+    return { path: (name) => [dir, sub, `${name}.md`], format, skill: skillsIn(dir), detect: [dir] };
+}
+/**
+ * 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 = dotTool(".claude", "commands", (c) => `---\ndescription: ${c.description}\nargument-hint: ${c.argumentHint}\n---\n\n${c.body}`);
+export const AGENT_TOOLS = {
+    claude: CLAUDE,
+    // Cursor invokes by flat file name (`/loam-check`); its frontmatter `name`
+    // field spells that invocation form.
+    cursor: dotTool(".cursor", "commands", (c) => `---\nname: /${c.name}\n---\n\n${c.body}`),
+    // 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: dotTool(".opencode", "commands", describedMd),
+    // 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: titledMd,
+        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": dotTool(".amazonq", "prompts", describedMd),
+    // Antigravity's directory is `.agent/`, which is why the id and the directory
+    // do not match here as they do almost everywhere else.
+    antigravity: dotTool(".agent", "workflows", describedMd),
+    // Auggie is the Augment CLI: id `auggie`, directory `.augment/`.
+    auggie: dotTool(".augment", "commands", hintedMd),
+    // Skills-only, deliberately: Codex does not load custom command files, so it
+    // declares no command emitter at all rather than laying down files nothing
+    // will ever open.
+    //
+    // The skill path is `.codex/skills/`, and that is NOT what Codex documents.
+    // Its own skills page (Build skills — developers.openai.com/codex/skills,
+    // which now redirects to learn.chatgpt.com/docs/build-skills; checked
+    // 2026-10-09) lists only `.agents/skills` — in the working directory, its
+    // parents up to the repository root — and never mentions `.codex/skills`;
+    // the `agents` entry below quotes it. `.codex/skills/` is undocumented but
+    // still loaded (Codex PR #10317 and third-party guides describe it as the
+    // older location, slated for deprecation), so the files this entry writes
+    // are read today and the break is latent: the day Codex drops it, a repo
+    // scaffolded for `codex` alone loses every skill silently. The path stays
+    // put on purpose — moving it re-points files in every repo already
+    // scaffolded, which is a migration with its own entry, not a comment fix —
+    // and choosing `agents` alongside `codex` already gives Codex the
+    // documented root.
+    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: dotTool(".factory", "commands", hintedMd),
+    junie: dotTool(".junie", "commands", describedMd),
+    // Kilo Code workflows carry no frontmatter — the title line is all the
+    // wrapper there is.
+    kilocode: dotTool(".kilocode", "workflows", titledMd),
+    // 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: dotTool(".qwen", "commands", describedMd),
+    // Roo/Zoo Code: id `roocode`, directory `.roo/`, no frontmatter.
+    roocode: dotTool(".roo", "commands", titledMd),
+    trae: dotTool(".trae", "commands", namedMd),
+    // 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, CommandContent } 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 shape most entries share: `<dir>/<sub>/<name>.md` command files in the\n * given dialect, skills under `<dir>/skills/`, and the tool's own dot-directory\n * as its one sighting. An entry that departs from any of the three — another\n * extension, a namespace directory, a second marker, no commands at all — is\n * written out in full below, so the departure is what its entry shows.\n */\nfunction dotTool(dir: string, sub: string, format: (c: CommandContent) => string): CommandEmittingTool {\n  return { path: (name) => [dir, sub, `${name}.md`], format, skill: skillsIn(dir), detect: [dir] };\n}\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 = dotTool(\n  \".claude\",\n  \"commands\",\n  (c) => `---\\ndescription: ${c.description}\\nargument-hint: ${c.argumentHint}\\n---\\n\\n${c.body}`,\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: dotTool(\".cursor\", \"commands\", (c) => `---\\nname: /${c.name}\\n---\\n\\n${c.body}`),\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: dotTool(\".opencode\", \"commands\", describedMd),\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: titledMd,\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\": dotTool(\".amazonq\", \"prompts\", describedMd),\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: dotTool(\".agent\", \"workflows\", describedMd),\n  // Auggie is the Augment CLI: id `auggie`, directory `.augment/`.\n  auggie: dotTool(\".augment\", \"commands\", hintedMd),\n  // Skills-only, deliberately: Codex does not load custom command files, so it\n  // declares no command emitter at all rather than laying down files nothing\n  // will ever open.\n  //\n  // The skill path is `.codex/skills/`, and that is NOT what Codex documents.\n  // Its own skills page (Build skills — developers.openai.com/codex/skills,\n  // which now redirects to learn.chatgpt.com/docs/build-skills; checked\n  // 2026-10-09) lists only `.agents/skills` — in the working directory, its\n  // parents up to the repository root — and never mentions `.codex/skills`;\n  // the `agents` entry below quotes it. `.codex/skills/` is undocumented but\n  // still loaded (Codex PR #10317 and third-party guides describe it as the\n  // older location, slated for deprecation), so the files this entry writes\n  // are read today and the break is latent: the day Codex drops it, a repo\n  // scaffolded for `codex` alone loses every skill silently. The path stays\n  // put on purpose — moving it re-points files in every repo already\n  // scaffolded, which is a migration with its own entry, not a comment fix —\n  // and choosing `agents` alongside `codex` already gives Codex the\n  // documented root.\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: dotTool(\".factory\", \"commands\", hintedMd),\n  junie: dotTool(\".junie\", \"commands\", describedMd),\n  // Kilo Code workflows carry no frontmatter — the title line is all the\n  // wrapper there is.\n  kilocode: dotTool(\".kilocode\", \"workflows\", titledMd),\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: dotTool(\".qwen\", \"commands\", describedMd),\n  // Roo/Zoo Code: id `roocode`, directory `.roo/`, no frontmatter.\n  roocode: dotTool(\".roo\", \"commands\", titledMd),\n  trae: dotTool(\".trae\", \"commands\", namedMd),\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"]}