agentloom 0.1.10 → 0.1.12

package/README.md

@@ -12,6 +12,8 @@ npx agentloom init
 
 That's all you need. Agentloom picks up your existing provider configs, migrates them into a unified `.agents/` directory, and syncs everything back out to all your tools. From here on, manage your agents, commands, rules, skills, and MCP servers in one place and run `agentloom sync` whenever you make changes.
 
+`agentloom init` is the provider-to-canonical bootstrap step. After that, `agentloom sync` is one-way: it reads from `.agents/` and writes provider-native outputs. If you intentionally want to pull provider state back into canonical `.agents/`, rerun `agentloom init`.
+
 ## Install
 
 ```bash
@@ -72,7 +74,7 @@ Source path resolution is additive and priority-ordered:
 - Agents: `.agents/agents` -> `agents`
 - Commands: `.agents/commands` -> `commands` -> `prompts` -> provider fallbacks `.github/prompts` + `.gemini/commands`
 - Rules: `.agents/rules` -> `rules`
-- Skills: `.agents/skills` -> `skills` -> root `SKILL.md` fallback
+- Skills: `.agents/skills` -> `skills` -> root `SKILL.md` -> root `<name>/SKILL.md` fallback
 - MCP: `.agents/mcp.json` -> `mcp.json`
 
 Aggregate `agentloom add <source>` can import command/skill/MCP-only repositories even when no `agents/` directory exists.

package/dist/commands/init.js

@@ -10,5 +10,6 @@ export async function runInitCommand(argv, cwd) {
         cwd,
         target: "all",
         skipSync: Boolean(argv["no-sync"]),
+        migrateProviderState: true,
     });
 }

package/dist/commands/sync.d.ts

@@ -6,4 +6,5 @@ export declare function runScopedSyncCommand(options: {
     cwd: string;
     target: EntityType | "all";
     skipSync?: boolean;
+    migrateProviderState?: boolean;
 }): Promise<void>;

package/dist/commands/sync.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import { parseProvidersFlag } from "../core/argv.js";
 import { getSyncHelpText } from "../core/copy.js";
 import { formatMigrationSummary, initializeCanonicalLayout, migrateProviderStateToCanonical, MigrationConflictError, } from "../core/migration.js";
+import { hasInitializedCanonicalLayout, resolveScopeForSync, } from "../core/scope.js";
 import { getNonInteractiveMode, resolvePathsForCommand, } from "./entity-utils.js";
 import { formatSyncSummary, resolveProvidersForSync, syncFromCanonical, } from "../sync/index.js";
 export async function runSyncCommand(argv, cwd) {
@@ -21,29 +22,42 @@ export async function runScopedSyncCommand(options) {
     const nonInteractive = getNonInteractiveMode(options.argv);
     let cleanupDryRunPaths;
     try {
-        const paths = await resolvePathsForCommand(options.argv, options.cwd);
+        const shouldMigrateProviderState = Boolean(options.migrateProviderState);
+        const paths = shouldMigrateProviderState
+            ? await resolvePathsForCommand(options.argv, options.cwd)
+            : await resolveScopeForSync({
+                cwd: options.cwd,
+                global: Boolean(options.argv.global),
+                local: Boolean(options.argv.local),
+                interactive: !nonInteractive,
+            });
         const explicitProviders = parseProvidersFlag(options.argv.providers);
         const providers = await resolveProvidersForSync({
             paths,
             explicitProviders,
             nonInteractive,
         });
+        if (!shouldMigrateProviderState) {
+            assertInitializedCanonicalStateExists(paths);
+        }
         const dryRun = Boolean(options.argv["dry-run"]);
         const effectivePaths = dryRun
             ? createDryRunCanonicalPaths(paths)
             : { paths, cleanup: undefined };
         cleanupDryRunPaths = effectivePaths.cleanup;
         initializeCanonicalLayout(effectivePaths.paths, providers);
-        const migrationSummary = await migrateProviderStateToCanonical({
-            paths: effectivePaths.paths,
-            providers,
-            target: options.target,
-            yes: Boolean(options.argv.yes),
-            nonInteractive,
-            dryRun,
-            materializeCanonical: dryRun,
-        });
-        console.log(formatMigrationSummary(migrationSummary));
+        if (shouldMigrateProviderState) {
+            const migrationSummary = await migrateProviderStateToCanonical({
+                paths: effectivePaths.paths,
+                providers,
+                target: options.target,
+                yes: Boolean(options.argv.yes),
+                nonInteractive,
+                dryRun,
+                materializeCanonical: dryRun,
+            });
+            console.log(formatMigrationSummary(migrationSummary));
+        }
         if (options.skipSync) {
             return;
         }
@@ -69,6 +83,15 @@ export async function runScopedSyncCommand(options) {
         cleanupDryRunPaths?.();
     }
 }
+function assertInitializedCanonicalStateExists(paths) {
+    if (hasInitializedCanonicalLayout(paths)) {
+        return;
+    }
+    const initCommand = paths.scope === "global"
+        ? "agentloom init --global"
+        : "agentloom init --local";
+    throw new Error(`No initialized canonical .agents state found at ${paths.agentsRoot}.\nRun \`${initCommand}\` to bootstrap from provider configs first, or use \`agentloom add\` to create canonical content before syncing.`);
+}
 function createDryRunCanonicalPaths(paths) {
     const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "agentloom-dry-run-"));
     const tempAgentsRoot = path.join(tempRoot, ".agents");

package/dist/core/copy.js

@@ -9,11 +9,11 @@ Usage:
 
 Aggregate commands:
   add <source>               Import agents/commands/mcp/rules/skills from a source
-  init                       Bootstrap canonical files, migrate providers, then sync
+  init                       Bootstrap canonical files from provider configs, then sync
   find <query>               Search remote + local entities
   update [source]            Refresh lockfile-managed imports
   upgrade                    Install the latest CLI release
-  sync                       Migrate provider configs then generate provider outputs
+  sync                       Generate provider outputs from canonical .agents
   delete <source|name...>    Delete imported entities by source or name(s)
 
 Entity commands:
@@ -76,7 +76,7 @@ Source discovery:
   agents: .agents/agents -> agents
   commands: .agents/commands -> commands -> prompts -> (.github/prompts + .gemini/commands fallback)
   rules: .agents/rules -> rules
-  skills: .agents/skills -> skills -> root SKILL.md
+  skills: .agents/skills -> skills -> root SKILL.md -> root <name>/SKILL.md
 
 Usage:
   agentloom add <source> [options]
@@ -134,7 +134,9 @@ Behavior:
 `;
 }
 export function getSyncHelpText() {
-    return `Migrate provider configs into canonical .agents data, then generate provider-specific outputs.
+    return `Generate provider-specific outputs from canonical .agents data.
+
+Use \`agentloom init\` when you want to bootstrap or re-import provider configs into canonical state.
 
 Usage:
   agentloom sync [options]
@@ -148,7 +150,7 @@ Options:
 `;
 }
 export function getInitHelpText() {
-    return `Bootstrap canonical .agents files, migrate provider configs into canonical state, and sync providers.
+    return `Bootstrap canonical .agents files from existing provider configs, then sync providers.
 
 Usage:
   agentloom init [options]

package/dist/core/importer.js

@@ -121,7 +121,7 @@ export async function importSource(options) {
         if (shouldImportSkills &&
             options.requireSkills &&
             sourceSkillsDirs.length === 0) {
-            throw new Error(`No source skills directory found under ${prepared.importRoot} (expected .agents/skills/, skills/, or root SKILL.md, including plugin sources declared in .claude-plugin/marketplace.json).`);
+            throw new Error(`No source skills directory found under ${prepared.importRoot} (expected .agents/skills/, skills/, root SKILL.md, or root <name>/SKILL.md directories, including plugin sources declared in .claude-plugin/marketplace.json).`);
         }
         if (shouldImportSkills &&
             options.requireSkills &&
@@ -134,7 +134,7 @@ export async function importSource(options) {
             sourceRules.length === 0 &&
             sourceSkills.length === 0 &&
             Object.keys(sourceMcp?.mcpServers ?? {}).length === 0) {
-            throw new Error(`No importable entities found in source "${sourceLocation}".\nExpected agents/, .agents/agents/, .github/agents/, commands/, .agents/commands/, prompts/, .gemini/commands/, .github/prompts/, mcp.json/.agents/mcp.json, rules/.agents/rules/, skills/, .agents/skills/, root SKILL.md, or plugin sources from .claude-plugin/marketplace.json.`);
+            throw new Error(`No importable entities found in source "${sourceLocation}".\nExpected agents/, .agents/agents/, .github/agents/, commands/, .agents/commands/, prompts/, .gemini/commands/, .github/prompts/, mcp.json/.agents/mcp.json, rules/.agents/rules/, skills/, .agents/skills/, root SKILL.md, root <name>/SKILL.md directories, or plugin sources from .claude-plugin/marketplace.json.`);
         }
         const shouldResolveAgents = shouldImportAgents &&
             (sourceAgents.length > 0 ||

package/dist/core/scope.d.ts

@@ -5,5 +5,7 @@ export interface ScopeResolutionOptions {
     local?: boolean;
     interactive?: boolean;
 }
+export declare function hasInitializedCanonicalLayout(paths: Pick<ScopePaths, "agentsRoot" | "agentsDir" | "commandsDir" | "rulesDir" | "skillsDir" | "mcpPath" | "lockPath" | "manifestPath">): boolean;
 export declare function buildScopePaths(cwd: string, scope: Scope, homeDir?: string): ScopePaths;
 export declare function resolveScope(options: ScopeResolutionOptions): Promise<ScopePaths>;
+export declare function resolveScopeForSync(options: ScopeResolutionOptions): Promise<ScopePaths>;

package/dist/core/scope.js

@@ -3,6 +3,24 @@ import os from "node:os";
 import path from "node:path";
 import { cancel, isCancel, select } from "@clack/prompts";
 import { getGlobalSettingsPath, readSettings } from "./settings.js";
+function directoryHasEntries(dirPath) {
+    return fs.existsSync(dirPath) && fs.readdirSync(dirPath).length > 0;
+}
+export function hasInitializedCanonicalLayout(paths) {
+    if (!fs.existsSync(paths.agentsRoot) ||
+        !fs.statSync(paths.agentsRoot).isDirectory()) {
+        return false;
+    }
+    if (fs.existsSync(paths.mcpPath) ||
+        fs.existsSync(paths.lockPath) ||
+        fs.existsSync(paths.manifestPath)) {
+        return true;
+    }
+    return (directoryHasEntries(paths.agentsDir) ||
+        directoryHasEntries(paths.commandsDir) ||
+        directoryHasEntries(paths.rulesDir) ||
+        directoryHasEntries(paths.skillsDir));
+}
 export function buildScopePaths(cwd, scope, homeDir = os.homedir()) {
     const workspaceRoot = cwd;
     const agentsRoot = scope === "local"
@@ -37,33 +55,76 @@ export async function resolveScope(options) {
     if (!interactive) {
         return buildScopePaths(cwd, hasLocalAgents ? "local" : "global");
     }
-    const globalSettings = readSettings(getGlobalSettingsPath());
-    const defaultScope = globalSettings.lastScope === "local" ? "local" : "global";
+    const defaultScope = getDefaultScope();
+    const selected = await promptForScopeSelection({
+        hasLocalAgents,
+        defaultScope,
+    });
+    return buildScopePaths(cwd, selected);
+}
+export async function resolveScopeForSync(options) {
+    const { cwd } = options;
+    if (options.global && options.local) {
+        throw new Error("Use either --global or --local, not both.");
+    }
+    if (options.global)
+        return buildScopePaths(cwd, "global");
+    if (options.local)
+        return buildScopePaths(cwd, "local");
+    const localPaths = buildScopePaths(cwd, "local");
+    const globalPaths = buildScopePaths(cwd, "global");
+    const hasLocalAgents = fs.existsSync(localPaths.agentsRoot);
+    const hasLocalCanonical = hasInitializedCanonicalLayout(localPaths);
+    const hasGlobalCanonical = hasInitializedCanonicalLayout(globalPaths);
+    const interactive = options.interactive ?? (process.stdin.isTTY && process.stdout.isTTY);
+    if (!interactive) {
+        return hasLocalAgents ? localPaths : globalPaths;
+    }
+    if (hasLocalAgents && hasGlobalCanonical) {
+        const selected = await promptForScopeSelection({
+            hasLocalAgents: true,
+            defaultScope: getDefaultScope(globalPaths.homeDir),
+        });
+        return buildScopePaths(cwd, selected, globalPaths.homeDir);
+    }
+    if (hasLocalCanonical)
+        return localPaths;
+    if (hasGlobalCanonical)
+        return globalPaths;
+    if (hasLocalAgents)
+        return localPaths;
+    throw new Error(`No initialized canonical .agents state found at ${localPaths.agentsRoot} or ${globalPaths.agentsRoot}.\nRun \`agentloom init --local\` or \`agentloom init --global\` to bootstrap from provider configs first, or use \`agentloom add\` to create canonical content before syncing.`);
+}
+function getDefaultScope(homeDir = os.homedir()) {
+    const globalSettings = readSettings(getGlobalSettingsPath(homeDir));
+    return globalSettings.lastScope === "local" ? "local" : "global";
+}
+async function promptForScopeSelection(options) {
     const selected = await select({
         message: "Choose scope for this command",
         options: [
             {
                 value: "local",
                 label: ".agents in this repository",
-                hint: hasLocalAgents
-                    ? defaultScope === "local"
+                hint: options.hasLocalAgents
+                    ? options.defaultScope === "local"
                         ? "default"
                         : undefined
-                    : defaultScope === "local"
+                    : options.defaultScope === "local"
                         ? "default (creates .agents)"
                         : "creates .agents",
             },
             {
                 value: "global",
                 label: "~/.agents shared config",
-                hint: defaultScope === "global" ? "default" : undefined,
+                hint: options.defaultScope === "global" ? "default" : undefined,
             },
         ],
-        initialValue: defaultScope,
+        initialValue: options.defaultScope,
     });
     if (isCancel(selected)) {
         cancel("Operation cancelled.");
         process.exit(1);
     }
-    return buildScopePaths(cwd, selected);
+    return selected;
 }

package/dist/core/sources.js

@@ -209,6 +209,9 @@ function discoverSourceSkillsDirsForRoot(importRoot) {
     if (fs.existsSync(rootSkill) && fs.statSync(rootSkill).isFile()) {
         return [importRoot];
     }
+    if (hasImmediateRootSkillDirs(importRoot)) {
+        return [importRoot];
+    }
     return [];
 }
 function discoverSourceRulesDirsForRoot(importRoot) {
@@ -225,6 +228,18 @@ function discoverSourceRulesDirsForRoot(importRoot) {
 function dedupePaths(paths) {
     return [...new Set(paths)];
 }
+function hasImmediateRootSkillDirs(importRoot) {
+    for (const entry of fs.readdirSync(importRoot, { withFileTypes: true })) {
+        if (!entry.isDirectory()) {
+            continue;
+        }
+        const skillFile = path.join(importRoot, entry.name, "SKILL.md");
+        if (fs.existsSync(skillFile) && fs.statSync(skillFile).isFile()) {
+            return true;
+        }
+    }
+    return false;
+}
 function isPathWithinRoot(rootPath, targetPath) {
     const relative = path.relative(rootPath, targetPath);
     return (relative === "" ||

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentloom",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "Unified agent and MCP sync CLI for multi-provider AI tooling",
   "type": "module",
   "bin": {