@ahood/cli 0.12.0 → 0.13.0

package/README.md

@@ -189,9 +189,9 @@ Shared alice/pdf-tools with design-team.
 Sharing is additive -- it doesn't change `alice/pdf-tools`'s own public/private visibility, it just makes it visible to everyone in `design-team` too. On the other side, whoever received the link runs `ahood group join <the link>` to join.
 </details>
 
-## Kinds: skills, agents, MCP servers, docs, and project guides
+## Kinds: skills, agents, MCP servers, docs, project guides, and loops
 
-The registry holds five kinds of artifact, each with its own command group. All five take the same verbs (`search`, `list`, `view`/`show`, `read`, `versions`, `diff`, `add`, `update`, `outdated`, `remove`, `edit`, `unpublish`, `star`, `unstar`, `share`, `unshare`, `init`, `publish`), run by the same code:
+The registry holds six kinds of artifact, each with its own command group. All six take the same verbs (`search`, `list`, `view`/`show`, `read`, `versions`, `diff`, `add`, `update`, `outdated`, `remove`, `edit`, `unpublish`, `star`, `unstar`, `share`, `unshare`, `init`, `publish`), run by the same code:
 
 | Kind | Root file | `add` installs to | Group |
 | --- | --- | --- | --- |
@@ -200,6 +200,7 @@ The registry holds five kinds of artifact, each with its own command group. All
 | mcp | `server.json` | an entry merged into `.mcp.json` | `ahood mcp <verb>` |
 | doc | `DOC.md` | `.claude/docs/<owner>@<doc>.md` | `ahood doc <verb>` |
 | project | `PROJECT.md` | `.claude/project.md` (one per repository) | `ahood project <verb>` |
+| loop | `LOOP.md` | `.claude/loops/<owner>@<loop>.md` | `ahood loop <verb>` |
 
 ```
 $ ahood agent search review
@@ -212,15 +213,18 @@ $ ahood doc add alice/setup-guide       # ./.claude/docs/alice@setup-guide.md, p
 $ ahood project                         # project guides for this repo's git remote
 $ ahood project add alice/acme-api      # ./.claude/project.md, pinned
 $ ahood project init acme-api           # ./acme-api/PROJECT.md, `project:` filled from git origin
+$ ahood loop read alice/code-review-pass    # print a loop without installing it
+$ ahood loop add alice/code-review-pass     # ./.claude/loops/alice@code-review-pass.md, pinned
 $ ahood agent add alice/pdf-tools
 alice/pdf-tools is a skill, not an agent -- refusing to install it. Use `ahood skill add alice/pdf-tools` instead.
 ```
 
-- **`ahood agent`, `ahood mcp`, `ahood doc` and `ahood project` are strict.** A target of another kind is refused -- exit code `2`, naming the kind it found -- before anything is downloaded, prompted for, written, or sent. That covers `add`, `update`, `remove`, `edit`, `unpublish`, `share`/`unshare`, `star`/`unstar`, and `publish` (an existing entry of another kind is refused before anything is packed or uploaded); the read-only verbs refuse too, rather than show the wrong kind. `search` asks the registry for that kind only, `list` keeps only that kind of your own entries, and `update`/`outdated` with no argument consider only installed pins of that kind. `agent publish`/`mcp publish`/`doc publish`/`project publish` imply their kind and reject a contradictory `--kind`.
-- **Missing or unexpected kind metadata is refused, never guessed.** If the registry's answer carries no kind (or one this CLI doesn't handle), a kind-scoped command stops with exit `1` and points at the legacy form. `remove` reads the kind from the project's own files (the skill directory, the agent file, the mcp fingerprint in the lockfile, or a doc or project pin's recorded `kind`) and asks the registry only when those can't tell; if neither can, nothing is removed.
-- **`ahood skill` is legacy and cross-kind in this release.** `ahood skill search` and `ahood skill list` include every kind, and `ahood skill add`/`update`/`remove`/... act on whatever kind the target is, exactly as before -- including `--json` output and exit codes -- so existing scripts keep working. The exceptions are a doc and a project guide: `ahood skill add` refuses them and points at `ahood doc add` / `ahood project add`. Add `--kind skill|agent|mcp|doc|project` to any `ahood skill` verb (except `publish`, whose `--kind` keeps its original meaning) to scope it, or `--kind all` to spell out the cross-kind behavior.
-- **Docs install as one pinned file.** `ahood doc add` saves a doc's `DOC.md` to `.claude/docs/<owner>@<doc>.md` and pins it in `.claude/skills.lock.json` with `"kind": "doc"`. It refuses to overwrite a file at that path that isn't pinned as that doc. `ahood doc update`/`outdated`/`remove` manage those pins like any other kind. Kind dispatch is table-driven (`src/kind-info.ts`).
+- **`ahood agent`, `ahood mcp`, `ahood doc`, `ahood project` and `ahood loop` are strict.** A target of another kind is refused -- exit code `2`, naming the kind it found -- before anything is downloaded, prompted for, written, or sent. That covers `add`, `update`, `remove`, `edit`, `unpublish`, `share`/`unshare`, `star`/`unstar`, and `publish` (an existing entry of another kind is refused before anything is packed or uploaded); the read-only verbs refuse too, rather than show the wrong kind. `search` asks the registry for that kind only, `list` keeps only that kind of your own entries, and `update`/`outdated` with no argument consider only installed pins of that kind. `agent publish`/`mcp publish`/`doc publish`/`project publish`/`loop publish` imply their kind and reject a contradictory `--kind`.
+- **Missing or unexpected kind metadata is refused, never guessed.** If the registry's answer carries no kind (or one this CLI doesn't handle), a kind-scoped command stops with exit `1` and points at the legacy form. `remove` reads the kind from the project's own files (the skill directory, the agent file, the mcp fingerprint in the lockfile, or a doc, project, or loop pin's recorded `kind`) and asks the registry only when those can't tell; if neither can, nothing is removed.
+- **`ahood skill` is legacy and cross-kind in this release.** `ahood skill search` and `ahood skill list` include every kind, and `ahood skill add`/`update`/`remove`/... act on whatever kind the target is, exactly as before -- including `--json` output and exit codes -- so existing scripts keep working. The exceptions are a doc, a project guide, and a loop: `ahood skill add` refuses them and points at `ahood doc add` / `ahood project add` / `ahood loop add`. Add `--kind skill|agent|mcp|doc|project|loop` to any `ahood skill` verb (except `publish`, whose `--kind` keeps its original meaning) to scope it, or `--kind all` to spell out the cross-kind behavior.
+- **Docs and loops install as one pinned file per owner/slug.** `ahood doc add` saves a doc's `DOC.md` to `.claude/docs/<owner>@<doc>.md` and pins it in `.claude/skills.lock.json` with `"kind": "doc"`; `ahood loop add` does the same for a loop's `LOOP.md`, to `.claude/loops/<owner>@<loop>.md` with `"kind": "loop"`. Both refuse to overwrite a file at that path that isn't pinned as that entry. `update`/`outdated`/`remove` manage those pins like any other kind. Kind dispatch is table-driven (`src/kind-info.ts`).
 - **A project guide is one pinned file per repository.** `ahood project add` saves the guide's `PROJECT.md` to `.claude/project.md` and pins it with `"kind": "project"`. It never touches `CLAUDE.md` or `AGENTS.md` (point those at `.claude/project.md` yourself), refuses to overwrite an unpinned `.claude/project.md`, and refuses a second guide while another is pinned (`ahood project remove` it first). `ahood project init` fills the optional `project` frontmatter field from `git remote get-url origin`, normalized to `host/owner/repo` exactly as the registry does (credentials stripped; `--project <remote>` or `--no-project` to override). Bare `ahood project` lists the guides you can see for this repository's remote, through the hosted `get_project_guide` MCP tool.
+- **A loop is a reusable procedure, not scoped to one repository.** It is pseudocode and rules for running a recurring kind of agentic session (a code review pass, a migration sweep, ...), meant to be installed the same way in many different projects -- unlike a project guide, `LOOP.md` has no `project` remote field, just `DOC.md`'s plain `name`/`description` frontmatter. `ahood loop init` has no `--project`/`--no-project` flags for that reason.
 
 **Migration plan for a strict `ahood skill`.** A future major version will make `ahood skill <verb>` skills-only by default, matching `agent` and `mcp`. Until then: (1) this release adds the strict groups and `--kind`, and labels `ahood skill` as legacy in `--help`; (2) a following minor release prints a stderr deprecation note when an `ahood skill` command actually touches a non-skill entry (stdout and `--json` unchanged); (3) the major release flips the default, keeping `ahood skill <verb> --kind all` as the explicit cross-kind escape hatch. Scripts that want today's behavior forever can pass `--kind all` now.
 
@@ -362,6 +366,29 @@ alice/pdf-tools is a skill, not an agent -- refusing to install it. Use `ahood s
 | `ahood project init [name] [--project <git-remote> \| --no-project]` | Scaffold a new project guide folder with a minimal, valid PROJECT.md. |
 | `ahood project publish <owner>/<slug>@<version> [--path <dir>] [--name <text>] [--tagline <text>] [--tags <comma,separated>] [--license <id>] [--homepage <url>] [--repository <url>] [--changelog <text>] [--json]` | Publish a new version of a project guide from a folder containing PROJECT.md, creating it first if it doesn't exist yet. |
 
+### Loop
+
+| Command | What it does |
+| --- | --- |
+| `ahood loop search <query> [--json] [--limit <n>]` | Search published loops. |
+| `ahood loop view\|show <owner>/<loop> [--json] [--web]` | Show a single loop's details without installing it (alias: ahood loop show). |
+| `ahood loop read <owner>/<loop> [--json]` | Print a published loop's LOOP.md, without installing it. |
+| `ahood loop versions <owner>/<loop> [--json]` | List a loop's published-version history. |
+| `ahood loop diff <owner>/<loop> <versionA> <versionB> [--json]` | Show what changed between two published versions of a loop. |
+| `ahood loop list [--json]` | List your own loops, public and private. |
+| `ahood loop add <owner>/<loop>[@version]` | Install a loop into .claude/loops/<owner>@<loop>.md, pinned in the lockfile. |
+| `ahood loop update [<owner>/<loop> ...] [--dry-run] [--json]` | Move loop pins forward to the latest version. |
+| `ahood loop outdated [<owner>/<loop> ...] [--json]` | Read-only staleness check for installed loops. |
+| `ahood loop remove <owner>/<loop> [--yes]` | Uninstall and unpin a loop (local only, prompts unless --yes is passed). |
+| `ahood loop edit <owner>/<loop> [--tagline] [--tags] [--license] [--visibility] [--homepage] [--repository]` | Update a loop you own, changing only the flags you pass. |
+| `ahood loop unpublish <owner>/<loop>[@version] [--yes]` | Delete a loop from the registry for every consumer, or yank one version (prompts unless --yes is passed). |
+| `ahood loop star <owner>/<loop>` | Star a loop. |
+| `ahood loop unstar <owner>/<loop>` | Remove your star from a loop. |
+| `ahood loop share <owner>/<loop> --group <group>` | Share a loop you own with a group, without changing its visibility. |
+| `ahood loop unshare <owner>/<loop> --group <group>` | Stop sharing a loop you own with a group. |
+| `ahood loop init [name]` | Scaffold a new loop folder with a minimal, valid LOOP.md. |
+| `ahood loop publish <owner>/<loop>@<version> [--path <dir>] [--name <text>] [--tagline <text>] [--tags <comma,separated>] [--license <id>] [--homepage <url>] [--repository <url>] [--changelog <text>] [--json]` | Publish a new version of a loop from a folder containing LOOP.md, creating it first if it doesn't exist yet. |
+
 ### Group
 
 | Command | What it does |

package/dist/archive-entries.js

@@ -0,0 +1,59 @@
+import { posix } from "node:path";
+import * as tarStream from "tar-stream";
+import { sanitizeForTerminal } from "./terminal-safe.js";
+// AlexKay28/ahood#792 -- the one archive-entry path rule, mirroring the
+// server's lib/publish/entry-path.ts. `SKILL.md` and `././SKILL.md` used to be
+// two entries to the server (which reads the FIRST) but one file to
+// extractTarGz (resolve() collapsed them and the LAST write won), so a hidden
+// later duplicate could overwrite the reviewed file at install. Every
+// extractor now refuses such an archive up front instead.
+/** True when `path` is already a canonical relative POSIX path: non-empty,
+ *  no backslash or NUL, not absolute, no empty / "." / ".." segment, and
+ *  unchanged by posix.normalize. */
+export function isCanonicalEntryPath(path) {
+    if (path === "" || path.includes("\\") || path.includes("\0"))
+        return false;
+    if (posix.isAbsolute(path) || posix.normalize(path) !== path)
+        return false;
+    return path.split("/").every((segment) => segment !== "" && segment !== "." && segment !== "..");
+}
+/** A tar header name relative to the archive root. `tar -C dir .` names
+ *  every entry `./x`, so exactly ONE leading "./" is dropped; whatever
+ *  remains must already be canonical (`././x` is rejected, not collapsed). */
+export function tarEntryPath(headerName) {
+    return headerName.startsWith("./") ? headerName.slice(2) : headerName;
+}
+/** Walks every header of an already-decompressed tar and throws unless each
+ *  non-directory entry has a canonical, unique path. Runs before an extractor
+ *  writes or returns anything, so a bad entry anywhere refuses the whole
+ *  archive. Directory entries (`./`, `./scripts/`) are not files and are
+ *  skipped. */
+export async function assertCanonicalEntryPaths(tar) {
+    const seen = new Set();
+    const extract = tarStream.extract();
+    await new Promise((resolvePromise, reject) => {
+        extract.on("entry", (header, stream, next) => {
+            stream.resume();
+            if (header.type === "directory") {
+                next();
+                return;
+            }
+            const path = tarEntryPath(header.name);
+            const problem = !isCanonicalEntryPath(path)
+                ? `Refusing to extract unsafe archive entry: ${sanitizeForTerminal(header.name)} (not a canonical relative path)`
+                : seen.has(path)
+                    ? `Refusing to extract archive: it has more than one entry for "${sanitizeForTerminal(path)}"`
+                    : null;
+            if (problem) {
+                reject(new Error(problem));
+                extract.destroy();
+                return;
+            }
+            seen.add(path);
+            next();
+        });
+        extract.on("finish", () => resolvePromise());
+        extract.on("error", reject);
+        extract.end(tar);
+    });
+}

package/dist/commands/add.js

@@ -8,6 +8,7 @@ import { LOCKFILE_PATH, parseOwnerSkillVersion, skillDir, agentPath, pinnedFileP
 import { readLockfile, withLock, writeFileAtomic, writeJsonFileAtomic, writeLockfileEntryVerifyingChecksum, LockfileChecksumConflictError, } from "../lockfile.js";
 import { promptSecret } from "../secret-prompt.js";
 import { sanitizeForTerminal } from "../terminal-safe.js";
+import { assertCanonicalEntryPaths, tarEntryPath } from "../archive-entries.js";
 import { UsageError } from "../usage-error.js";
 import { assertKind, describeKind, isPinnedFileKind, KINDS, strictKind } from "../kinds.js";
 const USAGE = "Usage: ahood skill add <owner>/<skill>[@version]";
@@ -92,6 +93,10 @@ export async function extractTarGz(buffer, destDir) {
     catch (error) {
         throw new Error(`Archive decompresses to more than ${MAX_EXTRACTED_BYTES / (1024 * 1024)} MB, or is not valid gzip -- refusing to extract.`, { cause: error });
     }
+    // Every entry path is canonical and unique before the first write
+    // (AlexKay28/ahood#792): otherwise `././SKILL.md` lands on SKILL.md and the
+    // last of the two wins, while the server validated the first.
+    await assertCanonicalEntryPaths(decompressed);
     const extract = tarStream.extract();
     const resolvedDest = resolve(destDir);
     let entryCount = 0;
@@ -112,7 +117,7 @@ export async function extractTarGz(buffer, destDir) {
             // segments (and, on Windows, drive-absolute and backslash-separated
             // names) so the comparison catches every escape shape, not just a
             // literal leading "../".
-            const entryPath = header.name.replace(/^\.\//, "");
+            const entryPath = tarEntryPath(header.name);
             const fullPath = resolve(destDir, entryPath);
             if (fullPath !== resolvedDest && !fullPath.startsWith(resolvedDest + sep)) {
                 stream.resume();
@@ -198,27 +203,20 @@ export async function extractSingleFileContent(buffer, entryName) {
     catch (error) {
         throw new Error(`Archive decompresses to more than ${MAX_EXTRACTED_BYTES / (1024 * 1024)} MB, or is not valid gzip -- refusing to extract.`, { cause: error });
     }
+    // A duplicate or non-canonical entry anywhere refuses the archive, rather
+    // than this reader and extractTarGz picking different copies of one file
+    // (AlexKay28/ahood#792; this used to take the first, extractTarGz the last).
+    await assertCanonicalEntryPaths(decompressed);
     const extract = tarStream.extract();
     let found = null;
     await new Promise((resolvePromise, reject) => {
         extract.on("entry", (header, stream, next) => {
-            // Normalize a leading "./" the same way extractTarGz and the server's
-            // extract-and-checksum.ts normalizeEntryPath do -- a plain `tar czf`
-            // commonly prefixes entries with "./", which would otherwise pass
-            // server-side validation/publish but then fail to install here with
-            // "AGENT.md not found" (ahood-cli final review finding #3).
-            const normalizedName = header.name.replace(/^\.\//, "");
-            if (normalizedName !== entryName) {
-                stream.resume();
-                next();
-                return;
-            }
-            // Only take the FIRST matching entry, mirroring the server side's
-            // `files.find(...)` lookup -- otherwise a tar with two entries at the
-            // same normalized name would resolve to whichever one happens to come
-            // last here, diverging from what the server validated against
-            // (ahood-cli final review finding #4).
-            if (found !== null) {
+            // Drop tar's one leading "./" the same way extractTarGz and the server
+            // do -- a plain `tar czf` commonly prefixes entries with "./", which
+            // would otherwise pass server-side validation/publish but then fail to
+            // install here with "AGENT.md not found" (ahood-cli final review
+            // finding #3).
+            if (header.type === "directory" || tarEntryPath(header.name) !== entryName) {
                 stream.resume();
                 next();
                 return;

package/dist/commands/completion.js

@@ -1,8 +1,8 @@
-import { TOP_LEVEL_COMMANDS_HELP, SKILL_COMMANDS_HELP, AGENT_COMMANDS_HELP, MCP_COMMANDS_HELP, DOC_COMMANDS_HELP, PROJECT_COMMANDS_HELP, GROUP_COMMANDS_HELP, SNAP_COMMANDS_HELP, COMMAND_ALIASES, } from "../help.js";
+import { TOP_LEVEL_COMMANDS_HELP, SKILL_COMMANDS_HELP, AGENT_COMMANDS_HELP, MCP_COMMANDS_HELP, DOC_COMMANDS_HELP, PROJECT_COMMANDS_HELP, LOOP_COMMANDS_HELP, GROUP_COMMANDS_HELP, SNAP_COMMANDS_HELP, COMMAND_ALIASES, } from "../help.js";
 import { UsageError } from "../usage-error.js";
 const USAGE = "Usage: ahood completion <bash|zsh|fish>";
 // Every entity noun with its own verb list, in the order completion offers
-// them. Registry nouns (skill, agent, mcp -- ahood-cli#172; doc -- #182; project -- #185) come first; group
+// them. Registry nouns (skill, agent, mcp -- ahood-cli#172; doc -- #182; project -- #185; loop -- ahood#858) come first; group
 // and snap were already real nouns but had no completion at all before.
 const NOUNS = [
     ["skill", SKILL_COMMANDS_HELP],
@@ -10,6 +10,7 @@ const NOUNS = [
     ["mcp", MCP_COMMANDS_HELP],
     ["doc", DOC_COMMANDS_HELP],
     ["project", PROJECT_COMMANDS_HELP],
+    ["loop", LOOP_COMMANDS_HELP],
     ["group", GROUP_COMMANDS_HELP],
     ["snap", SNAP_COMMANDS_HELP],
 ];

package/dist/commands/init.js

@@ -139,12 +139,32 @@ TODO -- how to work in this repository: conventions, how to verify a change, and
 traps. Plain Markdown; \`ahood project add\` saves this whole file to .claude/project.md.
 `;
 }
+// LOOP.md, for `ahood loop init` (ahood-cli, ahood#858). The backend's
+// validator (lib/publish/parse-loop-frontmatter.ts) is DOC.md's exact flat
+// reader -- no extra field, unlike PROJECT.md's optional `project` remote,
+// since a loop is explicitly portable across repositories rather than
+// scoped to one. Same rules as buildDocMd apply: nothing above the opening
+// `---`, and no colon in a comment line inside the frontmatter.
+function buildLoopMd(name) {
+    return `---
+name: ${name}
+description: TODO -- one line saying what kind of recurring agentic session this loop is for.
+---
+
+# ${name}
+
+TODO -- the pseudocode and rules for running this kind of session: the steps, the order,
+and what to do at each decision point. Plain Markdown; \`ahood loop add\` saves this whole
+file to .claude/loops/<owner>@<loop>.md.
+`;
+}
 const TEMPLATES = {
     skill: buildSkillMd,
     agent: buildAgentMd,
     mcp: buildServerJson,
     doc: buildDocMd,
     project: buildProjectMd,
+    loop: buildLoopMd,
 };
 const NEXT_STEPS = {
     skill: ["Fill in the description, then flesh out the ## Instructions section."],
@@ -156,6 +176,7 @@ const NEXT_STEPS = {
     ],
     doc: ["Fill in the description, then write the doc below the frontmatter."],
     project: ["Fill in the description, then write the guide below the frontmatter."],
+    loop: ["Fill in the description, then write the loop's pseudocode and rules below the frontmatter."],
 };
 function parseProjectFlags(args) {
     const raw = flagValue(args, "--project");

package/dist/help.js

@@ -386,6 +386,10 @@ function registryCommandsHelp(kind) {
 }
 export const AGENT_COMMANDS_HELP = registryCommandsHelp("agent");
 export const DOC_COMMANDS_HELP = registryCommandsHelp("doc");
+// `ahood loop` (ahood-cli, ahood#858): the shared verbs, no extras -- a loop
+// is portable across repositories (unlike `project`), so it needs none of
+// PROJECT_COMMANDS_HELP's bare-listing or `--project` flag additions below.
+export const LOOP_COMMANDS_HELP = registryCommandsHelp("loop");
 // `ahood project` (ahood-cli#185): the shared verbs, with init's `project`
 // field flags, plus bare `ahood project` -- the guides for this repository.
 export const PROJECT_COMMANDS_HELP = [
@@ -619,6 +623,7 @@ const ENTITY_COMMANDS_HELP = {
     mcp: MCP_COMMANDS_HELP,
     doc: DOC_COMMANDS_HELP,
     project: PROJECT_COMMANDS_HELP,
+    loop: LOOP_COMMANDS_HELP,
     group: GROUP_COMMANDS_HELP,
     snap: SNAP_COMMANDS_HELP,
 };
@@ -801,12 +806,22 @@ export function formatProjectHelp() {
         "this repository's git remote.",
     ], PROJECT_COMMANDS_HELP, "project");
 }
+export function formatLoopHelp() {
+    return formatRegistryKindHelp("ahood loop -- loops (LOOP.md) in the ahood registry", [
+        "A loop is a pseudocode-and-rules procedure for running a recurring kind of agentic session",
+        "(a code review pass, a migration sweep, ...), reusable across repositories -- unlike a project",
+        "guide, it names no single repository. Every verb here acts on loops only: a target of another",
+        "kind is refused before anything is downloaded, prompted for, written, or sent. Installs land in",
+        ".claude/loops/<owner>@<loop>.md. To look at a loop without installing it, use `ahood loop read`.",
+    ], LOOP_COMMANDS_HELP, "loop");
+}
 const KIND_HELP = {
     skill: formatSkillHelp,
     agent: formatAgentHelp,
     mcp: formatMcpHelp,
     doc: formatDocHelp,
     project: formatProjectHelp,
+    loop: formatLoopHelp,
 };
 export function formatKindHelp(noun) {
     return KIND_HELP[noun]();
@@ -850,6 +865,8 @@ export function formatHelp() {
     const docGroupSummary = "The same verbs, for docs (DOC.md) only -- run `ahood doc --help` for the full list.";
     const projectGroupUsage = "ahood project <command>";
     const projectGroupSummary = "The same verbs, for project guides (PROJECT.md) only; bare `ahood project` lists this repository's guides.";
+    const loopGroupUsage = "ahood loop <command>";
+    const loopGroupSummary = "The same verbs, for loops (LOOP.md) only -- run `ahood loop --help` for the full list.";
     const groupGroupUsage = "ahood group <command>";
     const groupGroupSummary = "Create private groups and share skills with them -- run `ahood group --help` for the full list.";
     const snapGroupUsage = "ahood snap <command>";
@@ -861,6 +878,7 @@ export function formatHelp() {
         { usage: mcpGroupUsage, summary: mcpGroupSummary },
         { usage: docGroupUsage, summary: docGroupSummary },
         { usage: projectGroupUsage, summary: projectGroupSummary },
+        { usage: loopGroupUsage, summary: loopGroupSummary },
         { usage: groupGroupUsage, summary: groupGroupSummary },
         { usage: snapGroupUsage, summary: snapGroupSummary },
     ]);
@@ -882,7 +900,7 @@ export function formatHelp() {
         "",
         "Run `ahood <command> --help` (or `ahood help <command>`) for a single command's flags and examples.",
         "Run `ahood skill --help` for the full list of skill commands.",
-        "Run `ahood agent|mcp|doc|project --help` for the kind-scoped agent, MCP, doc and project guide commands.",
+        "Run `ahood agent|mcp|doc|project|loop --help` for the kind-scoped agent, MCP, doc, project guide and loop commands.",
         "Run `ahood group --help` for the full list of group commands.",
         "Run `ahood snap --help` for the full list of snap commands.",
         "Run `ahood --version` to print the installed CLI version.",

package/dist/index.js

@@ -99,6 +99,7 @@ const COMMANDS = {
     agent: dispatchAgent,
     doc: dispatchDoc,
     project: dispatchProject,
+    loop: dispatchLoop,
     group: dispatchGroup,
     snap: dispatchSnap,
 };
@@ -111,7 +112,7 @@ const COMMANDS = {
 // sense "skill" already used before "group" (the entity) existed. "snap"
 // joins this set for the exact same reason (ahood-cli#107).
 // Every registry noun joins it (ahood-cli#172), taken from the kind table so
-// a new kind (doc #182, project #185) needs no edit here.
+// a new kind (doc #182, project #185, loop ahood#858) needs no edit here.
 const GROUP_COMMANDS = new Set([...CLI_KINDS, "group", "snap"]);
 function levenshtein(a, b) {
     const dp = Array.from({ length: a.length + 1 }, () => new Array(b.length + 1).fill(0));
@@ -141,6 +142,19 @@ function closestOf(input, candidates) {
 function closestCommand(input) {
     return closestOf(input, Object.keys(COMMANDS));
 }
+// Plural alias (ahood-cli#190): `ahood skills`, `ahood agents`, `ahood mcps`,
+// `ahood docs`, `ahood projects`, `ahood loops` dispatch exactly as the
+// singular kind would. A straight trailing-`s` strip-and-match
+// against the KINDS registry is enough -- every current and planned kind
+// pluralizes this way, and no COMMANDS key ends in "s" (checked below), so a
+// real top-level command can never be shadowed by this. Scoped to CLI_KINDS
+// only, not "group"/"snap" (those are separate entities, not kinds).
+function pluralKindAlias(word) {
+    if (!word.endsWith("s"))
+        return undefined;
+    const singular = word.slice(0, -1);
+    return isCliKind(singular) ? singular : undefined;
+}
 function closestSkillCommand(input) {
     return closestOf(input, Object.keys(SKILL_COMMANDS));
 }
@@ -217,6 +231,13 @@ async function dispatchAgent(args) {
 async function dispatchDoc(args) {
     await dispatchRegistry("doc", args);
 }
+// `ahood loop` (ahood-cli, ahood#858): a loop is portable across
+// repositories (unlike `project`), so it has no bare-command listing of its
+// own -- every verb is the shared registry dispatch, help included, the
+// same shape as dispatchDoc above.
+async function dispatchLoop(args) {
+    await dispatchRegistry("loop", args);
+}
 // `ahood project` (ahood-cli#185): with no verb -- nothing, or only its own
 // flags -- it lists the project guides for this repository's git remote
 // (commands/project-guides.ts). Everything else is the shared registry
@@ -359,7 +380,13 @@ async function main() {
         console.log(formatHelp());
         return;
     }
-    const handler = COMMANDS[command];
+    // Resolve a plural kind alias (ahood-cli#190) before the generic lookup, so
+    // everything downstream -- the handler itself and the GROUP_COMMANDS
+    // --help interception below -- treats `ahood projects` exactly like
+    // `ahood project`. Only applies when `command` isn't already a real
+    // command (so it never shadows one).
+    const resolvedCommand = COMMANDS[command] ? command : (pluralKindAlias(command) ?? command);
+    const handler = COMMANDS[resolvedCommand];
     if (!handler) {
         console.error(`Unknown command: ${command}`);
         // Every previously-flat skill command moved under `ahood skill <verb>`
@@ -381,8 +408,8 @@ async function main() {
     // GROUP_COMMANDS despite the name, unrelated to the "group" entity itself)
     // own their own --help handling at both the entity and per-verb level --
     // don't intercept here.
-    if (!GROUP_COMMANDS.has(command) && (args.includes("--help") || args.includes("-h"))) {
-        const entry = findCommandHelp(command);
+    if (!GROUP_COMMANDS.has(resolvedCommand) && (args.includes("--help") || args.includes("-h"))) {
+        const entry = findCommandHelp(resolvedCommand);
         console.log(entry ? formatCommandHelp(entry) : formatHelp());
         return;
     }
@@ -413,4 +440,4 @@ if (isEntrypoint) {
     main();
 }
 // Exported for tests only -- the CLI itself only ever calls main() above.
-export { main, dispatchSkill, dispatchAgent, dispatchDoc, dispatchProject, dispatchMcp, dispatchRegistry, dispatchGroup, dispatchSnap, COMMANDS, SKILL_COMMANDS, GROUP_VERBS, SNAP_VERBS };
+export { main, dispatchSkill, dispatchAgent, dispatchDoc, dispatchProject, dispatchLoop, dispatchMcp, dispatchRegistry, dispatchGroup, dispatchSnap, COMMANDS, SKILL_COMMANDS, GROUP_VERBS, SNAP_VERBS };

package/dist/kind-info.js

@@ -4,15 +4,20 @@
 //
 // Kind-aware registry commands (ahood-cli#172).
 //
-// The registry stores five artifact kinds (the backend's
-// lib/skills/validation.ts ALLOWED_KINDS: skill, agent, mcp, doc, project), and a
+// The registry stores six artifact kinds (the backend's
+// lib/artifact-kinds.ts ALLOWED_KINDS: skill, agent, mcp, doc, project, loop), and a
 // kind is fixed when an entry is created -- PATCH's allow-list has no `kind`
 // -- so the kind an entry reports now is the kind it has always had. Each
 // kind has a noun group (`ahood skill|agent|mcp|doc <verb>`), all run by one
 // shared dispatcher. `doc` joined as the fourth in ahood-cli#182: it installs
 // as one flat Markdown file, its DOC.md, the same shape an agent has.
 // `project` joined as the fifth in ahood-cli#185: one PROJECT.md per
-// repository, installed to the fixed path .claude/project.md.
+// repository, installed to the fixed path .claude/project.md. `loop` joined
+// as the sixth (ahood-cli, ahood#858): a portable, reusable procedure for a
+// recurring kind of agentic session, installed many-per-project like `doc`
+// (.claude/loops/<owner>@<loop>.md), with DOC.md's exact frontmatter shape --
+// no extra field, unlike `project`'s optional `project` remote, since a loop
+// is explicitly not scoped to one repository.
 //
 // Per-kind facts live here, not in per-command branches: `placeholder` and
 // `example` feed help and init, `about` the legacy `skill add` refusal.
@@ -64,16 +69,27 @@ export const KINDS = {
         example: { slug: "alice/acme-api", name: "Acme API" },
         about: "a guide to working in one repository",
     },
+    loop: {
+        label: "loop",
+        article: "a",
+        plural: "loops",
+        rootDoc: "LOOP.md",
+        installsTo: ".claude/loops/<owner>@<loop>.md",
+        placeholder: "<loop>",
+        example: { slug: "alice/code-review-pass", name: "Code Review Pass" },
+        about: "a reusable procedure for a recurring kind of agentic session, portable across repositories",
+    },
 };
 export const CLI_KINDS = Object.keys(KINDS);
 export function isCliKind(value) {
     return typeof value === "string" && CLI_KINDS.includes(value);
 }
 // Kinds that install as one root-doc file pinned with its kind in the
-// lockfile (doc: ahood-cli#182, project: #185). The recorded kind is how
-// remove/update recognise the pin offline, and how a project guide's shared
-// path is claimed by exactly one pin. Legacy `skill add` refuses these.
-export const PINNED_FILE_KINDS = ["doc", "project"];
+// lockfile (doc: ahood-cli#182, project: #185, loop: ahood#858). The
+// recorded kind is how remove/update recognise the pin offline, and how a
+// project guide's shared path is claimed by exactly one pin. Legacy
+// `skill add` refuses these.
+export const PINNED_FILE_KINDS = ["doc", "project", "loop"];
 export function isPinnedFileKind(value) {
     return typeof value === "string" && PINNED_FILE_KINDS.includes(value);
 }

package/dist/spec.js

@@ -134,7 +134,23 @@ export function docPath(owner, doc) {
 // file the user owns. Being shared, the path is claimed by exactly one pin:
 // add.ts refuses a second guide while another is pinned.
 export const PROJECT_GUIDE_PATH = join(".claude", "project.md");
+// A loop installs as one flat file, .claude/loops/<owner>@<loop>.md
+// (ahood-cli, ahood#858) -- the same shape as docPath above, not
+// PROJECT_GUIDE_PATH's single fixed path, since a loop is explicitly
+// portable across repositories rather than scoped to one (see
+// docs/adr/backend/0015-loop-artifact-kind.md in the ahood repo).
+export const LOOPS_ROOT = join(".claude", "loops");
+export function loopPath(owner, loop) {
+    const spec = `${owner}/${loop}`;
+    validateSegment(owner, "owner", spec);
+    validateSegment(loop, "skill", spec);
+    return join(LOOPS_ROOT, `${owner}@${loop}.md`);
+}
 // Where a pinned-file kind's install lives (kind-info.ts PINNED_FILE_KINDS).
 export function pinnedFilePath(kind, owner, slug) {
-    return kind === "doc" ? docPath(owner, slug) : PROJECT_GUIDE_PATH;
+    if (kind === "doc")
+        return docPath(owner, slug);
+    if (kind === "loop")
+        return loopPath(owner, slug);
+    return PROJECT_GUIDE_PATH;
 }

package/dist/useme/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ahood
-description: How to use the ahood CLI (@ahood/cli), the registry for reusable AI-agent skills, subagent definitions (AGENT.md), MCP server manifests (server.json), docs (DOC.md), and project guides (PROJECT.md). Load BEFORE running any ahood command; before writing a non-trivial reusable skill, subagent, or MCP integration from scratch (search the registry first); when installing, updating, removing, publishing, sharing, or unpublishing one; when wiring ahood into an MCP host; or when setting up headless/CI access with AHOOD_TOKEN. Triggers - ahood, skill registry, is there a skill for this, install a skill, install an agent, add an MCP server, read a doc, project guide, publish a skill, ahood mcp, ahood doc, ahood project, AHOOD_TOKEN.
+description: How to use the ahood CLI (@ahood/cli), the registry for reusable AI-agent skills, subagent definitions (AGENT.md), MCP server manifests (server.json), docs (DOC.md), project guides (PROJECT.md), and loops (LOOP.md). Load BEFORE running any ahood command; before writing a non-trivial reusable skill, subagent, MCP integration, or recurring-session procedure from scratch (search the registry first); when installing, updating, removing, publishing, sharing, or unpublishing one; when wiring ahood into an MCP host; or when setting up headless/CI access with AHOOD_TOKEN. Triggers - ahood, skill registry, is there a skill for this, install a skill, install an agent, add an MCP server, read a doc, project guide, loop, recurring agentic session procedure, publish a skill, ahood mcp, ahood doc, ahood project, ahood loop, AHOOD_TOKEN.
 ---
 
 # ahood
@@ -13,7 +13,7 @@ and only moves when someone runs an update.
 This guide ships inside the CLI itself (`ahood help useme`), so it matches the installed
 version (`ahood --version`). It needs no login or network to print.
 
-## Five kinds, five command groups
+## Six kinds, six command groups
 
 | Kind | Root file | Installs to | Commands |
 |---|---|---|---|
@@ -22,19 +22,20 @@ version (`ahood --version`). It needs no login or network to print.
 | mcp | `server.json` | an entry merged into `.mcp.json` | `ahood mcp <verb>` |
 | doc | `DOC.md` | `.claude/docs/<owner>@<doc>.md` | `ahood doc <verb>` |
 | project | `PROJECT.md` | `.claude/project.md` (one per repository) | `ahood project <verb>` |
+| loop | `LOOP.md` | `.claude/loops/<owner>@<loop>.md` | `ahood loop <verb>` |
 
-All five groups take the same verbs: `search`, `list`, `view`/`show`, `read`, `versions`,
+All six groups take the same verbs: `search`, `list`, `view`/`show`, `read`, `versions`,
 `diff`, `add`, `update`, `outdated`, `remove`, `edit`, `unpublish`, `star`, `unstar`,
 `share`, `unshare`, `init`, `publish`.
 
-- `ahood agent <verb>`, `ahood mcp <verb>`, `ahood doc <verb>` and `ahood project <verb>` act on their own kind only.
+- `ahood agent <verb>`, `ahood mcp <verb>`, `ahood doc <verb>`, `ahood project <verb>` and `ahood loop <verb>` act on their own kind only.
   A target of another kind is refused (exit 2) before anything is downloaded, prompted for,
   written, or sent, and the error names the kind it found and the right command.
 - `ahood skill <verb>` is the **legacy, cross-kind** group in this CLI release: `skill search`
   and `skill list` include every kind, and `skill add`/`skill update` install whatever kind
-  they resolve, except a doc or project guide: `skill add` refuses one and points at
-  `ahood doc add` / `ahood project add`.
-  Add `--kind skill` (or `agent`, `mcp`, `doc`, `project`) to any verb to scope it to one kind;
+  they resolve, except a doc, project guide, or loop: `skill add` refuses one and points at
+  `ahood doc add` / `ahood project add` / `ahood loop add`.
+  Add `--kind skill` (or `agent`, `mcp`, `doc`, `project`, `loop`) to any verb to scope it to one kind;
   `--kind all` spells out the legacy behavior. Prefer the kind-specific form in anything new --
   a future major version makes `ahood skill` skills-only.
 - A doc is a documentation page. `ahood doc read alice/setup-guide` prints it without
@@ -44,6 +45,11 @@ All five groups take the same verbs: `search`, `list`, `view`/`show`, `read`, `v
   `ahood project` inside a repository to list the guides naming its git remote;
   `ahood project add alice/acme-api` saves one to `.claude/project.md` (pinned, one per
   repository) and never touches `CLAUDE.md` or `AGENTS.md` -- point those at it yourself.
+- A loop is a pseudocode-and-rules procedure for running a recurring kind of agentic session
+  (a code review pass, a migration sweep, ...), reusable across repositories -- unlike a
+  project guide, `LOOP.md` has no repository field. `ahood loop read alice/code-review-pass`
+  prints it without installing anything; `ahood loop add alice/code-review-pass` saves it as
+  one pinned file under `.claude/loops/`, managed like any other pin.
 
 ## Find, inspect, then install
 
@@ -93,7 +99,7 @@ ahood skill update --dry-run --json    # preview, machine-readable
 ahood agent remove alice/code-reviewer # local uninstall; prompts unless --yes
 ```
 
-With no target, `agent`/`mcp`/`doc`/`project` `update` and `outdated` consider only installed pins of that
+With no target, `agent`/`mcp`/`doc`/`project`/`loop` `update` and `outdated` consider only installed pins of that
 kind; the legacy `skill update` covers every pin. Updates only affect the current project.
 An `.mcp.json` entry you edited by hand is refused rather than overwritten.
 
@@ -107,13 +113,14 @@ ahood agent init code-reviewer         # ./code-reviewer/AGENT.md
 ahood mcp init github-server           # ./github-server/server.json (placeholder URL)
 ahood doc init setup-guide             # ./setup-guide/DOC.md
 ahood project init acme-api            # ./acme-api/PROJECT.md, `project:` filled from git origin
+ahood loop init code-review-pass       # ./code-review-pass/LOOP.md
 
 ahood agent publish alice/code-reviewer@1.0.0 --path code-reviewer --name "Code Reviewer"
 ahood skill publish alice/pdf-tools@1.1.0 --path pdf-tools --changelog "Adds split"
 ```
 
 - `--name` is required only on the first publish, which creates the entry under your
-  account. `agent publish`/`mcp publish`/`doc publish`/`project publish` imply the kind and refuse a contradictory `--kind`
+  account. `agent publish`/`mcp publish`/`doc publish`/`project publish`/`loop publish` imply the kind and refuse a contradictory `--kind`
   or an existing entry of another kind before uploading anything.
 - **New entries are private.** Make one discoverable explicitly:
   `ahood skill edit alice/pdf-tools --visibility public`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahood/cli",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "CLI for ahood, a registry for installing and publishing Claude Code skills.",
   "license": "MIT",
   "homepage": "https://github.com/AlexKay28/ahood-cli",