agentloom 0.1.0 → 0.1.1

package/README.md

@@ -28,6 +28,18 @@ Project scope:
   agents/
     reviewer.md
     debugger.md
+  commands/
+    review.md
+    ship.md
+  skills/
+    reviewing/
+      SKILL.md
+      references/
+      assets/
+    debugging/
+      SKILL.md
+      references/
+      assets/
   mcp.json
   agents.lock.json
   settings.local.json
@@ -37,100 +49,83 @@ Global scope uses `~/.agents` with the same file layout.
 
 ## Commands
 
-### `agentloom skills ...`
-Pass-through wrapper to `npx skills ...` from
-[`vercel-labs/skills`](https://github.com/vercel-labs/skills).
+### Aggregate verbs
 
-### `agentloom add <source>`
-Import canonical agents/MCP from:
+- `agentloom add <source>`
+- `agentloom find <query>`
+- `agentloom update [source]`
+- `agentloom sync`
+- `agentloom delete <source|name>`
 
-- local repo path
-- GitHub slug (`owner/repo`)
-- generic git URL
+Aggregate `add` imports discoverable entities from a source (agents, commands, MCP servers, skills). In interactive sessions, each entity supports two tracking modes:
 
-Options:
+- `Sync everything from source` (default): updates include newly added source items.
+- `Use custom selection`: updates stay pinned to the selected items, even if all current items were selected.
 
-- `--ref <ref>`: git ref (branch/tag/commit) for remote sources
-- `--subdir <path>`: subdirectory inside source repo
-- `--rename <name>`: rename imported agent when importing a single agent
-- `--local | --global`: choose destination scope
-- `--yes`: skip interactive conflict prompts
-- `--no-sync`: skip post-import sync
-- `--providers <csv>`: limit post-import sync providers
-- `--dry-run`: show sync changes without writing provider files
+Source path resolution is additive and priority-ordered:
 
-Example:
+- Agents: `.agents/agents` -> `agents`
+- Commands: `.agents/commands` -> `commands` -> `prompts`
+- Skills: `.agents/skills` -> `skills` -> root `SKILL.md` fallback
+- MCP: `.agents/mcp.json` -> `mcp.json`
 
-```bash
-agentloom add vercel-labs/skills --subdir skills
-```
-
-### `agentloom update`
-Refresh lockfile sources (`agents.lock.json`) and re-import changed revisions.
-
-Options:
-
-- `--local | --global`: choose lockfile scope
-- `--yes`: skip conflict prompts during re-import
-- `--no-sync`: skip post-update sync
-- `--providers <csv>`: limit post-update sync providers
-- `--dry-run`: show sync changes without writing provider files
-
-### `agentloom sync`
-Generate provider-specific outputs from canonical `.agents` data.
-
-Options:
-
-- `--local | --global`: choose canonical scope
-- `--providers <csv>`: limit sync providers
-- `--yes`: auto-delete stale generated files
-- `--dry-run`: show planned changes without writing files
-
-Example:
-
-```bash
-agentloom sync --providers codex,claude,cursor
-```
+Aggregate `agentloom add <source>` can import command/skill/MCP-only repositories even when no `agents/` directory exists.
 
-### `agentloom mcp add|list|delete`
-Manage canonical MCP servers in `.agents/mcp.json`.
+### Entity verbs
 
-`mcp add` options:
+- `agentloom agent <add|list|delete|find|update|sync>`
+- `agentloom command <add|list|delete|find|update|sync>`
+- `agentloom mcp <add|list|delete|find|update|sync>`
+- `agentloom skill <add|list|delete|find|update|sync>`
 
-- `--url <url>` or `--command <cmd>`: required transport config
-- `--arg <value>`: repeatable command arg
-- `--env KEY=VALUE`: repeatable environment variable
-- `--providers <csv>`: provider-specific assignment
-- `--local | --global`: choose canonical scope
-- `--no-sync`: skip post-change sync
+### Selector flags
 
-`mcp list` options:
+- `--agents <csv>`
+- `--commands <csv>`
+- `--mcps <csv>`
+- `--skills <csv>`
+- `--selection-mode <all|sync-all|custom>`
+- `--source <value>`
+- `--name <value>`
+- `--entity <agent|command|mcp|skill>`
 
-- `--json`: print raw canonical JSON
-- `--local | --global`: choose canonical scope
+### MCP manual server mode
 
-`mcp delete` options:
+Source-based MCP import lives under `agentloom mcp add ...`.
+Manual server management is under:
 
-- `--local | --global`: choose canonical scope
-- `--no-sync`: skip post-change sync
+- `agentloom mcp server add <name> (--url <url> | --command <cmd>)`
+- `agentloom mcp server list`
+- `agentloom mcp server delete <name>`
 
 Examples:
 
 ```bash
-agentloom mcp add browser-tools --command npx --arg browser-tools-mcp
-agentloom mcp list
-agentloom mcp delete browser-tools
+agentloom add farnoodma/agents
+agentloom agent add farnoodma/agents --agents issue-creator
+agentloom command add farnoodma/agents --commands review
+agentloom mcp add farnoodma/agents --mcps browser
+agentloom skill add farnoodma/agents --skills pr-review
+agentloom delete farnoodma/agents
+agentloom mcp server add browser-tools --command npx --arg browser-tools-mcp
 ```
 
 ### Top-level help
 
 ```bash
 agentloom --help
+agentloom find --help
 agentloom add --help
 agentloom update --help
 agentloom sync --help
+agentloom delete --help
+agentloom agent --help
+agentloom skill --help
+agentloom command --help
+agentloom command add --help
 agentloom mcp --help
 agentloom mcp add --help
+agentloom mcp server --help
 ```
 
 ### Version update notice
@@ -146,6 +141,27 @@ agentloom mcp add --help
 AGENTLOOM_DISABLE_UPDATE_NOTIFIER=1
 ```
 
+### Manage-agents bootstrap prompt
+
+In interactive sessions, `agentloom` checks for:
+
+- `~/.agents/skills/manage-agents/SKILL.md`
+- `.agents/skills/manage-agents/SKILL.md` (in the current workspace)
+
+If missing in both locations, it offers to bootstrap `manage-agents` because that skill helps agents reliably manage Agentloom resources (find/create/import/update/sync/delete).
+
+The install runs after the requested command completes so scope/provider selections from that command can be reused.
+
+- disable this prompt via `AGENTLOOM_DISABLE_MANAGE_AGENTS_PROMPT=1`
+
+### Telemetry
+
+Successful GitHub-based `agentloom add` imports can send anonymous telemetry
+to the Agentloom directory API.
+
+- disable telemetry via `AGENTLOOM_DISABLE_TELEMETRY=1`
+- override endpoint via `AGENTLOOM_TELEMETRY_ENDPOINT`
+
 ### Scope resolution
 
 If neither `--local` nor `--global` is provided:
@@ -207,6 +223,10 @@ For Codex, `agentloom sync` writes role-based multi-agent config:
 
 This follows official Codex multi-agent guidance.
 
+For canonical commands (`.agents/commands`), Codex output is always written to
+global prompts under `~/.codex/prompts` (Codex prompts are global-only), even
+when syncing local scope.
+
 ## Development
 
 ```bash
@@ -219,15 +239,14 @@ pnpm build
 
 The GitHub Actions publish workflow is defined in `.github/workflows/release.yml`.
 
-- Push to `main` with `[patch]` or `[minor]` in commit subjects to trigger an automated npm release.
-- Run the workflow manually (`workflow_dispatch`) and choose `patch` or `minor` to force a release.
-- Push a `v*` tag (for example `v0.2.0`) to publish an already-versioned commit without bumping.
-- Automated bump releases create a `vX.Y.Z` commit/tag via `npm version`, push both to GitHub, then publish to npm with provenance.
+- Publish runs only when a GitHub Release is published (`release.published` event).
+- Release tags must use stable semver (`vX.Y.Z`).
+- The release tag version must match `packages/cli/package.json`.
+- The workflow publishes only the CLI package to npm with provenance.
 
 Required GitHub configuration:
 
-- Secret: `NPM_TOKEN` (automation token from the npm account that should own `agentloom`).
-- Repository setting: `Actions -> General -> Workflow permissions -> Read and write permissions` (required so CI can push version commits/tags).
+- npm Trusted Publisher configured for this repo/workflow (`farnoodma/agentloom`, workflow file `release.yml`).
 
 ## License
 

package/bin/cli.mjs

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 
-import { runCli } from '../dist/cli.js';
+import { formatCliErrorMessage, runCli } from '../dist/cli.js';
 
 runCli(process.argv.slice(2)).catch((err) => {
-  console.error(err instanceof Error ? err.message : String(err));
+  const message = err instanceof Error ? err.message : String(err);
+  console.error(formatCliErrorMessage(message));
   process.exit(1);
 });

package/dist/cli.d.ts

@@ -1 +1,2 @@
 export declare function runCli(argv: string[]): Promise<void>;
+export declare function formatCliErrorMessage(message: string): string;

package/dist/cli.js

@@ -1,14 +1,26 @@
 import { parseArgs } from "./core/argv.js";
+import { parseProvidersFlag } from "./core/argv.js";
+import { runAgentCommand } from "./commands/agent.js";
 import { runAddCommand } from "./commands/add.js";
+import { runCommandCommand } from "./commands/command.js";
+import { runDeleteCommand } from "./commands/delete.js";
+import { runFindCommand } from "./commands/find.js";
 import { runMcpCommand } from "./commands/mcp.js";
-import { runSkillsPassthrough } from "./commands/skills.js";
+import { runSkillCommand } from "./commands/skills.js";
 import { runSyncCommand } from "./commands/sync.js";
 import { runUpdateCommand } from "./commands/update.js";
 import { formatUnknownCommandError, getRootHelpText } from "./core/copy.js";
+import { maybePromptManageAgentsBootstrap } from "./core/manage-agents-bootstrap.js";
+import { parseCommandRoute } from "./core/router.js";
+import { buildScopePaths } from "./core/scope.js";
+import { getGlobalSettingsPath, readSettings } from "./core/settings.js";
 import { maybeNotifyVersionUpdate } from "./core/version-notifier.js";
 import { getCliVersion } from "./core/version.js";
+import { ALL_PROVIDERS } from "./types.js";
+const MANAGE_AGENTS_SOURCE = "farnoodma/agentloom";
+const MANAGE_AGENTS_SELECTOR = "manage-agents";
 export async function runCli(argv) {
-    const command = argv[0];
+    const command = argv[0] ?? "";
     const version = getCliVersion();
     if (!command ||
         command === "help" ||
@@ -21,41 +33,161 @@ export async function runCli(argv) {
         console.log(version);
         return;
     }
-    if (command === "skills") {
-        runSkillsPassthrough(argv.slice(1));
-        return;
-    }
     const parsed = parseArgs(argv);
     const cwd = process.cwd();
+    const shouldBootstrapManageAgents = await maybePromptManageAgentsBootstrap({
+        command,
+        help: Boolean(parsed.help),
+        yes: Boolean(parsed.yes),
+        cwd,
+    });
+    const route = parseCommandRoute(argv);
     if (!parsed.help) {
         await maybeNotifyVersionUpdate({
             command,
             currentVersion: version,
         });
     }
-    switch (command) {
-        case "add":
-            await runAddCommand(parsed, cwd);
-            return;
-        case "update":
-            await runUpdateCommand(parsed, cwd);
+    if (!route) {
+        throw new Error(formatUnknownCommandError(command));
+    }
+    await runRoutedCommand(route, parsed, cwd, command);
+    if (shouldBootstrapManageAgents) {
+        const bootstrapArgs = buildManageAgentsBootstrapArgs(parsed, cwd);
+        await runAddCommand(parseArgs(bootstrapArgs), cwd);
+    }
+}
+function printHelp() {
+    console.log(getRootHelpText());
+}
+async function runRoutedCommand(route, parsed, cwd, command) {
+    if (!route) {
+        throw new Error(formatUnknownCommandError(command));
+    }
+    if (route.mode === "aggregate") {
+        switch (route.verb) {
+            case "add":
+                await runAddCommand(parsed, cwd);
+                return;
+            case "find":
+                await runFindCommand(parsed);
+                return;
+            case "update":
+                await runUpdateCommand(parsed, cwd);
+                return;
+            case "sync":
+                await runSyncCommand(parsed, cwd);
+                return;
+            case "delete":
+                await runDeleteCommand(parsed, cwd);
+                return;
+            default:
+                throw new Error(formatUnknownCommandError(command));
+        }
+    }
+    if (route.mode === "mcp-server") {
+        await runMcpCommand(parsed, cwd);
+        return;
+    }
+    switch (route.entity) {
+        case "agent":
+            await runAgentCommand(parsed, cwd);
             return;
-        case "sync":
-            await runSyncCommand(parsed, cwd);
+        case "command":
+            await runCommandCommand(parsed, cwd);
             return;
         case "mcp":
             await runMcpCommand(parsed, cwd);
             return;
+        case "skill":
+            await runSkillCommand(parsed, cwd);
+            return;
         default:
             throw new Error(formatUnknownCommandError(command));
     }
 }
-function printHelp() {
-    console.log(getRootHelpText());
+function buildManageAgentsBootstrapArgs(parsed, cwd) {
+    const scope = resolveBootstrapScope(parsed);
+    const providers = resolveBootstrapProviders(parsed, cwd, scope);
+    const args = [
+        "skill",
+        "add",
+        MANAGE_AGENTS_SOURCE,
+        "--skills",
+        MANAGE_AGENTS_SELECTOR,
+    ];
+    if (scope === "local")
+        args.push("--local");
+    if (scope === "global")
+        args.push("--global");
+    if (typeof parsed["selection-mode"] === "string" &&
+        parsed["selection-mode"].trim().length > 0) {
+        args.push("--selection-mode", parsed["selection-mode"].trim());
+    }
+    if (parsed["no-sync"])
+        args.push("--no-sync");
+    if (parsed["dry-run"])
+        args.push("--dry-run");
+    if (providers && providers.length > 0) {
+        args.push("--providers", providers.join(","));
+    }
+    return args;
+}
+function resolveBootstrapScope(parsed) {
+    if (parsed.local)
+        return "local";
+    if (parsed.global)
+        return "global";
+    const globalSettings = readSettings(getGlobalSettingsPath());
+    if (globalSettings.lastScope === "local" ||
+        globalSettings.lastScope === "global") {
+        return globalSettings.lastScope;
+    }
+    return undefined;
+}
+function resolveBootstrapProviders(parsed, cwd, scope) {
+    const explicitProviders = parseProvidersFlag(parsed.providers);
+    if (explicitProviders && explicitProviders.length > 0) {
+        return explicitProviders;
+    }
+    if (!scope)
+        return undefined;
+    const settingsPath = buildScopePaths(cwd, scope).settingsPath;
+    const scopeSettings = readSettings(settingsPath);
+    return normalizeProviders(scopeSettings.defaultProviders);
+}
+function normalizeProviders(providers) {
+    const selected = new Set();
+    for (const provider of providers ?? []) {
+        const normalized = provider.trim().toLowerCase();
+        if (ALL_PROVIDERS.includes(normalized)) {
+            selected.add(normalized);
+        }
+    }
+    return [...selected];
+}
+function colorRed(text) {
+    return process.stderr.isTTY ? `\u001b[31m${text}\u001b[0m` : text;
+}
+export function formatCliErrorMessage(message) {
+    const trimmed = message.trim();
+    if (trimmed.length === 0) {
+        return `\n${colorRed("✖")} Error`;
+    }
+    const lines = trimmed.split("\n");
+    const firstLine = lines.shift();
+    if (!firstLine) {
+        return `\n${colorRed("✖")} Error`;
+    }
+    const formatted = `${colorRed("✖")} ${firstLine}`;
+    return lines.length > 0
+        ? `\n${formatted}\n${lines.join("\n")}`
+        : `\n${formatted}`;
 }
 if (import.meta.url === `file://${process.argv[1]}`) {
     runCli(process.argv.slice(2)).catch((err) => {
-        console.error(err instanceof Error ? err.message : String(err));
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(formatCliErrorMessage(message));
         process.exit(1);
     });
 }

package/dist/commands/add.d.ts

@@ -1,2 +1,9 @@
 import type { ParsedArgs } from "minimist";
+import type { EntityType } from "../types.js";
 export declare function runAddCommand(argv: ParsedArgs, cwd: string): Promise<void>;
+export declare function runScopedAddCommand(options: {
+    argv: ParsedArgs;
+    cwd: string;
+    entity: EntityType;
+    sourceIndex: number;
+}): Promise<void>;

package/dist/commands/add.js

@@ -1,56 +1,117 @@
-import { importSource, NonInteractiveConflictError } from "../core/importer.js";
-import { resolveScope } from "../core/scope.js";
-import { updateLastScope } from "../core/settings.js";
-import { parseProvidersFlag } from "../core/argv.js";
+import { parseProvidersFlag, parseSelectionModeFlag } from "../core/argv.js";
 import { formatUsageError, getAddHelpText } from "../core/copy.js";
-import { formatSyncSummary, syncFromCanonical } from "../sync/index.js";
+import { importSource, NonInteractiveConflictError } from "../core/importer.js";
+import { sendAddTelemetryEvent } from "../core/telemetry.js";
+import { resolveProvidersForSync } from "../sync/index.js";
+import { getEntitySelectors, getNonInteractiveMode, resolvePathsForCommand, runPostMutationSync, } from "./entity-utils.js";
 export async function runAddCommand(argv, cwd) {
     if (argv.help) {
         console.log(getAddHelpText());
         return;
     }
-    const source = argv._[1];
+    await runEntityAwareAdd({
+        argv,
+        cwd,
+        target: "all",
+        sourceIndex: 1,
+    });
+}
+export async function runScopedAddCommand(options) {
+    await runEntityAwareAdd({
+        argv: options.argv,
+        cwd: options.cwd,
+        target: options.entity,
+        sourceIndex: options.sourceIndex,
+    });
+}
+async function runEntityAwareAdd(options) {
+    const source = options.argv._[options.sourceIndex];
     if (typeof source !== "string" || source.trim() === "") {
         throw new Error(formatUsageError({
             issue: "Missing required <source>.",
-            usage: "agentloom add <source> [--ref <ref>] [--subdir <path>] [options]",
-            example: "agentloom add vercel-labs/skills --subdir skills",
+            usage: buildAddUsage(options.target),
+            example: buildAddExample(options.target),
         }));
     }
-    const nonInteractive = !(process.stdin.isTTY && process.stdout.isTTY);
-    const paths = await resolveScope({
-        cwd,
-        global: Boolean(argv.global),
-        local: Boolean(argv.local),
-        interactive: !nonInteractive,
-    });
+    const nonInteractive = getNonInteractiveMode(options.argv);
+    const paths = await resolvePathsForCommand(options.argv, options.cwd);
+    const explicitProviders = parseProvidersFlag(options.argv.providers);
+    const selectionMode = parseSelectionModeFlag(options.argv["selection-mode"]);
+    const importAgents = options.target === "all" || options.target === "agent";
+    const importCommands = options.target === "all" || options.target === "command";
+    const importMcp = options.target === "all" || options.target === "mcp";
+    const importSkills = options.target === "all" || options.target === "skill";
+    const agentSelectors = getEntitySelectors(options.argv, "agent");
+    const commandSelectors = getEntitySelectors(options.argv, "command");
+    const mcpSelectors = getEntitySelectors(options.argv, "mcp");
+    const skillSelectors = getEntitySelectors(options.argv, "skill");
+    let resolvedSkillProviders;
+    const resolveProvidersForSkills = async () => {
+        if (explicitProviders && explicitProviders.length > 0) {
+            return explicitProviders;
+        }
+        if (resolvedSkillProviders && resolvedSkillProviders.length > 0) {
+            return resolvedSkillProviders;
+        }
+        resolvedSkillProviders = await resolveProvidersForSync({
+            paths,
+            explicitProviders,
+            nonInteractive,
+        });
+        return resolvedSkillProviders;
+    };
     try {
         const summary = await importSource({
             source,
-            ref: typeof argv.ref === "string" ? argv.ref : undefined,
-            subdir: typeof argv.subdir === "string" ? argv.subdir : undefined,
-            rename: typeof argv.rename === "string" ? argv.rename : undefined,
-            yes: Boolean(argv.yes),
+            ref: typeof options.argv.ref === "string" ? options.argv.ref : undefined,
+            subdir: typeof options.argv.subdir === "string"
+                ? options.argv.subdir
+                : undefined,
+            rename: typeof options.argv.rename === "string"
+                ? options.argv.rename
+                : undefined,
+            agents: agentSelectors,
+            yes: Boolean(options.argv.yes),
             nonInteractive,
             paths,
+            importAgents,
+            requireAgents: options.target === "agent",
+            importCommands,
+            requireCommands: options.target === "command",
+            importMcp,
+            requireMcp: options.target === "mcp",
+            mcpSelectors,
+            promptForMcp: mcpSelectors.length === 0,
+            importSkills,
+            requireSkills: options.target === "skill",
+            skillSelectors,
+            promptForSkills: skillSelectors.length === 0,
+            skillsProviders: explicitProviders,
+            resolveSkillsProviders: importSkills && !explicitProviders
+                ? resolveProvidersForSkills
+                : undefined,
+            commandSelectors,
+            promptForCommands: commandSelectors.length === 0,
+            promptForAgentSelection: agentSelectors.length === 0,
+            selectionMode,
         });
         console.log(`Imported source: ${summary.source}`);
         console.log(`Source type: ${summary.sourceType}`);
         console.log(`Resolved commit: ${summary.resolvedCommit}`);
         console.log(`Imported agents: ${summary.importedAgents.length}`);
+        console.log(`Imported commands: ${summary.importedCommands.length}`);
         console.log(`Imported MCP servers: ${summary.importedMcpServers.length}`);
-        updateLastScope(paths.settingsPath, paths.scope);
-        if (!argv["no-sync"]) {
-            const syncSummary = await syncFromCanonical({
-                paths,
-                providers: parseProvidersFlag(argv.providers),
-                yes: Boolean(argv.yes),
-                nonInteractive,
-                dryRun: Boolean(argv["dry-run"]),
-            });
-            console.log("");
-            console.log(formatSyncSummary(syncSummary, paths.agentsRoot));
-        }
+        console.log(`Imported skills: ${summary.importedSkills.length}`);
+        await sendAddTelemetryEvent({
+            rawSource: source,
+            summary,
+        });
+        await runPostMutationSync({
+            argv: options.argv,
+            paths,
+            target: options.target,
+            providers: explicitProviders ?? resolvedSkillProviders,
+        });
     }
     catch (err) {
         if (err instanceof NonInteractiveConflictError) {
@@ -60,3 +121,33 @@ export async function runAddCommand(argv, cwd) {
         throw err;
     }
 }
+function buildAddUsage(target) {
+    if (target === "agent") {
+        return "agentloom agent add <source> [--ref <ref>] [--subdir <path>] [--agents <name>] [options]";
+    }
+    if (target === "command") {
+        return "agentloom command add <source> [--ref <ref>] [--subdir <path>] [--commands <name>] [options]";
+    }
+    if (target === "mcp") {
+        return "agentloom mcp add <source> [--ref <ref>] [--subdir <path>] [--mcps <name>] [options]";
+    }
+    if (target === "skill") {
+        return "agentloom skill add <source> [--ref <ref>] [--subdir <path>] [--skills <name>] [options]";
+    }
+    return "agentloom add <source> [--ref <ref>] [--subdir <path>] [options]";
+}
+function buildAddExample(target) {
+    if (target === "agent") {
+        return "agentloom agent add farnoodma/agents --agents issue-creator";
+    }
+    if (target === "command") {
+        return "agentloom command add farnoodma/agents --commands review";
+    }
+    if (target === "mcp") {
+        return "agentloom mcp add farnoodma/agents --mcps browser";
+    }
+    if (target === "skill") {
+        return "agentloom skill add farnoodma/agents --skills code-review";
+    }
+    return "agentloom add farnoodma/agents --providers codex,claude";
+}

package/dist/commands/agent.d.ts

@@ -0,0 +1,2 @@
+import type { ParsedArgs } from "minimist";
+export declare function runAgentCommand(argv: ParsedArgs, cwd: string): Promise<void>;