agentloom 0.1.5 → 0.1.7

package/README.md

@@ -10,7 +10,7 @@ For monorepo-level documentation and architecture context, see the [root README]
 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, skills, and MCP servers in one place and run `agentloom sync` whenever you make changes.
+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.
 
 ## Install
 
@@ -32,6 +32,9 @@ Project scope:
   commands/
     review.md
     ship.md
+  rules/
+    always-test.md
+    enforce-logs.md
   skills/
     reviewing/
       SKILL.md
@@ -59,7 +62,7 @@ Global scope uses `~/.agents` with the same file layout.
 - `agentloom sync`
 - `agentloom delete <source|name>`
 
-Aggregate `add` imports discoverable entities from a source (agents, commands, MCP servers, skills). In interactive sessions, each entity supports two tracking modes:
+Aggregate `add` imports discoverable entities from a source (agents, commands, rules, MCP servers, skills). In interactive sessions, each entity supports two tracking modes:
 
 - `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.
@@ -67,7 +70,8 @@ Aggregate `add` imports discoverable entities from a source (agents, commands, M
 Source path resolution is additive and priority-ordered:
 
 - Agents: `.agents/agents` -> `agents`
-- Commands: `.agents/commands` -> `commands` -> `prompts`
+- Commands: `.agents/commands` -> `commands` -> `prompts` -> provider fallbacks `.github/prompts` + `.gemini/commands`
+- Rules: `.agents/rules` -> `rules`
 - Skills: `.agents/skills` -> `skills` -> root `SKILL.md` fallback
 - MCP: `.agents/mcp.json` -> `mcp.json`
 
@@ -78,6 +82,7 @@ Aggregate `agentloom add <source>` can import command/skill/MCP-only repositorie
 - `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 rule <add|list|delete|find|update|sync>`
 - `agentloom skill <add|list|delete|find|update|sync>`
 
 ### Selector flags
@@ -85,11 +90,13 @@ Aggregate `agentloom add <source>` can import command/skill/MCP-only repositorie
 - `--agents <csv>`
 - `--commands <csv>`
 - `--mcps <csv>`
+- `--rule <csv>` (alias)
+- `--rules <csv>`
 - `--skills <csv>`
 - `--selection-mode <all|sync-all|custom>`
 - `--source <value>`
 - `--name <value>`
-- `--entity <agent|command|mcp|skill>`
+- `--entity <agent|command|mcp|rule|skill>`
 
 ### MCP manual server mode
 
@@ -107,6 +114,7 @@ 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 rule add farnoodma/agents --rules always-test
 agentloom skill add farnoodma/agents --skills pr-review
 agentloom delete farnoodma/agents
 agentloom mcp server add browser-tools --command npx --arg browser-tools-mcp
@@ -128,6 +136,7 @@ agentloom command --help
 agentloom command add --help
 agentloom mcp --help
 agentloom mcp add --help
+agentloom rule --help
 agentloom mcp server --help
 ```
 
@@ -166,6 +175,7 @@ The install runs after the requested command completes so scope/provider selecti
 Successful GitHub-based `agentloom add` imports can send anonymous telemetry
 to the Agentloom directory API.
 
+- tracked entities: agents, commands, rules, skills, MCP servers
 - disable telemetry via `AGENTLOOM_DISABLE_TELEMETRY=1`
 - override endpoint via `AGENTLOOM_TELEMETRY_ENDPOINT`
 
@@ -188,14 +198,67 @@ description: Review changes and report issues.
 claude:
   model: sonnet
 codex:
-  model: gpt-5.3-codex
-  reasoningEffort: low
+  model: gpt-5-codex
+  reasoningEffort: medium
   webSearch: true
 ---
 
 You are a strict reviewer...
 ```
 
+## Command schema
+
+Canonical commands are markdown files. Frontmatter is optional. When present,
+provider-specific command config can be nested per provider:
+
+```md
+---
+copilot:
+  description: Review current changes
+  agent: agent
+  tools:
+    - codebase
+  model: gpt-5
+  argument-hint: "<scope>"
+---
+
+# /review
+
+Review active changes with scope $ARGUMENTS.
+```
+
+Notes:
+
+- Provider configs follow the same pattern as agents:
+  - omit provider key for default behavior
+  - `provider: { ... }` to add provider-specific overrides
+  - `provider: false` to disable output for that provider
+- Provider-specific frontmatter keys are passed through as-is to that provider output.
+- Canonical command bodies can use `$ARGUMENTS`; provider-specific placeholder translation is applied during sync (for example Copilot receives `${input:args}` and Gemini receives `{{args}}`).
+
+## Rule schema
+
+Canonical rules are markdown files under `.agents/rules/*.md`.
+Rules require `frontmatter.name`. Additional frontmatter keys are preserved.
+
+```md
+---
+name: Always run tests
+description: Require tests before merge
+globs:
+  - "**/*.ts"
+alwaysApply: true
+---
+
+Before finishing any change, run the project checks and include the result.
+```
+
+Notes:
+
+- Rule ID is the canonical filename stem (for example `.agents/rules/always-test.md` -> `always-test`).
+- Managed instruction-block rendering uses only `frontmatter.name` + body.
+- Extra frontmatter keys are used only for Cursor `.cursor/rules/*.mdc` rendering.
+
 ## MCP schema
 
 Canonical MCP file format:
@@ -234,6 +297,29 @@ 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.
 
+## Rule sync behavior
+
+Rule sync is additive on top of agent/command/MCP/skill sync:
+
+- Local scope always updates managed rule blocks in `AGENTS.md`.
+- Local + Cursor writes `.cursor/rules/<rule-id>.mdc`.
+- Local + Claude writes managed blocks to `CLAUDE.md`.
+- Local + Gemini writes managed blocks to `GEMINI.md`.
+- Local + Copilot writes managed blocks to `.github/copilot-instructions.md`.
+- Local + OpenCode/Codex/Pi use the same managed `AGENTS.md` baseline blocks.
+- Global + Claude writes `~/.claude/CLAUDE.md`.
+- Global + Gemini writes `~/.gemini/GEMINI.md`.
+- Global + Copilot writes `~/.copilot/copilot-instructions.md` and adds that location to VS Code `chat.instructionsFilesLocations`.
+- Global + OpenCode writes `~/.config/opencode/AGENTS.md`.
+- Global Cursor/Codex/Pi rule settings are no-op unless a stable provider settings key exists.
+
+## Provider contract notes
+
+- Cursor provider output uses Cursor subagents (`.cursor/agents/*.md`).
+- Gemini command sync writes TOML files (`.gemini/commands/*.toml`).
+- Copilot global output uses `~/.copilot/{agents,prompts,skills}` and `~/.copilot/copilot-instructions.md` (workspace output remains `.github/*`).
+- Claude global user-scope MCP is not file-synced by Agentloom. Project MCP remains synced via `.mcp.json`.
+
 ## Development
 
 ```bash

package/dist/cli.js

@@ -7,6 +7,7 @@ import { runDeleteCommand } from "./commands/delete.js";
 import { runFindCommand } from "./commands/find.js";
 import { runInitCommand } from "./commands/init.js";
 import { runMcpCommand } from "./commands/mcp.js";
+import { runRuleCommand } from "./commands/rule.js";
 import { runSkillCommand } from "./commands/skills.js";
 import { runSyncCommand } from "./commands/sync.js";
 import { runUpgradeCommand } from "./commands/upgrade.js";
@@ -54,9 +55,11 @@ export async function runCli(argv) {
         yes: Boolean(parsed.yes),
         cwd,
     });
+    const bootstrapArgs = shouldBootstrapManageAgents
+        ? buildManageAgentsBootstrapArgs(parsed, cwd)
+        : undefined;
     await runRoutedCommand(route, parsed, cwd, command, version);
-    if (shouldBootstrapManageAgents) {
-        const bootstrapArgs = buildManageAgentsBootstrapArgs(parsed, cwd);
+    if (bootstrapArgs) {
         await runSkillCommand(parseArgs(bootstrapArgs), cwd);
     }
 }
@@ -111,13 +114,17 @@ async function runRoutedCommand(route, parsed, cwd, command, version) {
         case "skill":
             await runSkillCommand(parsed, cwd);
             return;
+        case "rule":
+            await runRuleCommand(parsed, cwd);
+            return;
         default:
             throw new Error(formatUnknownCommandError(command));
     }
 }
 function buildManageAgentsBootstrapArgs(parsed, cwd) {
-    const scope = resolveBootstrapScope(parsed);
-    const providers = resolveBootstrapProviders(parsed, cwd, scope);
+    const inferredScope = resolveBootstrapScope(parsed);
+    const scope = inferredScope ?? "global";
+    const providers = resolveBootstrapProviders(parsed, cwd, inferredScope);
     const args = [
         "skill",
         "add",

package/dist/commands/add.js

@@ -40,10 +40,12 @@ async function runEntityAwareAdd(options) {
     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 importRules = options.target === "all" || options.target === "rule";
     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 ruleSelectors = getEntitySelectors(options.argv, "rule");
     const skillSelectors = getEntitySelectors(options.argv, "skill");
     let resolvedSkillProviders;
     const resolveProvidersForSkills = async () => {
@@ -82,6 +84,10 @@ async function runEntityAwareAdd(options) {
             requireMcp: options.target === "mcp",
             mcpSelectors,
             promptForMcp: mcpSelectors.length === 0,
+            importRules,
+            requireRules: options.target === "rule",
+            ruleSelectors,
+            promptForRules: ruleSelectors.length === 0,
             importSkills,
             requireSkills: options.target === "skill",
             skillSelectors,
@@ -95,12 +101,14 @@ async function runEntityAwareAdd(options) {
             promptForAgentSelection: agentSelectors.length === 0,
             selectionMode,
         });
+        const importedRules = summary.importedRules ?? [];
         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}`);
+        console.log(`Imported rules: ${importedRules.length}`);
         console.log(`Imported skills: ${summary.importedSkills.length}`);
         await sendAddTelemetryEvent({
             rawSource: source,
@@ -131,6 +139,9 @@ function buildAddUsage(target) {
     if (target === "mcp") {
         return "agentloom mcp add <source> [--ref <ref>] [--subdir <path>] [--mcps <name>] [options]";
     }
+    if (target === "rule") {
+        return "agentloom rule add <source> [--ref <ref>] [--subdir <path>] [--rules <name>] [options]";
+    }
     if (target === "skill") {
         return "agentloom skill add <source> [--ref <ref>] [--subdir <path>] [--skills <name>] [options]";
     }
@@ -146,6 +157,9 @@ function buildAddExample(target) {
     if (target === "mcp") {
         return "agentloom mcp add farnoodma/agents --mcps browser";
     }
+    if (target === "rule") {
+        return "agentloom rule add farnoodma/agents --rules always-test";
+    }
     if (target === "skill") {
         return "agentloom skill add farnoodma/agents --skills code-review";
     }

package/dist/commands/delete.js

@@ -6,10 +6,11 @@ import { parseCommandsDir } from "../core/commands.js";
 import { formatUsageError } from "../core/copy.js";
 import { readLockfile, writeLockfile } from "../core/lockfile.js";
 import { readCanonicalMcp, writeCanonicalMcp } from "../core/mcp.js";
+import { normalizeRuleSelector, parseRulesDir, stripRuleFileExtension, } from "../core/rules.js";
 import { parseSourceSpec } from "../core/sources.js";
 import { parseSkillsDir } from "../core/skills.js";
 import { getNonInteractiveMode, resolvePathsForCommand, runPostMutationSync, } from "./entity-utils.js";
-const ALL_ENTITIES = ["agent", "command", "mcp", "skill"];
+const ALL_ENTITIES = ["agent", "command", "mcp", "rule", "skill"];
 const MULTISELECT_HELP_TEXT = "↑↓ move, space select, enter confirm";
 function withMultiselectHelp(message) {
     return `${message}\n${MULTISELECT_HELP_TEXT}`;
@@ -165,6 +166,11 @@ async function deleteBySource(options) {
                 delete mcp.mcpServers[server];
             }
         }
+        if (options.entities.includes("rule")) {
+            for (const imported of entry.importedRules) {
+                removeIfExists(path.join(options.paths.agentsRoot, imported));
+            }
+        }
         if (options.entities.includes("skill")) {
             for (const skill of entry.importedSkills) {
                 removeIfExists(path.join(options.paths.skillsDir, skill));
@@ -185,6 +191,7 @@ async function deleteBySource(options) {
 }
 async function deleteByName(options) {
     let selectedEntities = options.entities;
+    let deletedRuleIdentifiers;
     if (selectedEntities.length > 1) {
         const matches = detectNameMatches(options.paths, options.candidate);
         const matchingEntities = selectedEntities.filter((entity) => matches.includes(entity));
@@ -227,6 +234,14 @@ async function deleteByName(options) {
             }
             delete mcp.mcpServers[existing];
         }
+        else if (entity === "rule") {
+            const deletedRule = deleteRuleByName(options.paths, options.candidate);
+            deletedRuleIdentifiers = [
+                deletedRule.name,
+                deletedRule.fileName,
+                stripRuleFileExtension(deletedRule.fileName),
+            ];
+        }
         else if (entity === "skill") {
             deleteSkillByName(options.paths, options.candidate);
         }
@@ -236,7 +251,7 @@ async function deleteByName(options) {
     }
     const lockfile = readLockfile(options.paths);
     lockfile.entries = lockfile.entries
-        .map((entry) => removeNameFromEntry(entry, selectedEntities, options.candidate))
+        .map((entry) => removeNameFromEntry(entry, selectedEntities, options.candidate, deletedRuleIdentifiers))
         .filter((entry) => Boolean(entry));
     writeLockfile(options.paths, lockfile);
 }
@@ -269,6 +284,15 @@ function deleteSkillByName(paths, name) {
     }
     removeIfExists(target.sourcePath);
 }
+function deleteRuleByName(paths, name) {
+    const rules = parseRulesDir(paths.rulesDir);
+    const target = rules.find((rule) => ruleMatchesCandidate(rule, name));
+    if (!target) {
+        throw new Error(`Rule "${name}" was not found in canonical rules.`);
+    }
+    removeIfExists(target.sourcePath);
+    return target;
+}
 function removeIfExists(filePath) {
     if (!fs.existsSync(filePath))
         return;
@@ -293,6 +317,9 @@ function detectNameMatches(paths, candidate) {
     const hasMcp = Object.keys(mcp.mcpServers).some((name) => normalizeName(name) === normalized);
     if (hasMcp)
         matches.push("mcp");
+    const hasRule = parseRulesDir(paths.rulesDir).some((rule) => ruleMatchesCandidate(rule, candidate));
+    if (hasRule)
+        matches.push("rule");
     const hasSkill = parseSkillsDir(paths.skillsDir).some((skill) => normalizeName(skill.name) === normalized);
     if (hasSkill)
         matches.push("skill");
@@ -322,6 +349,14 @@ function removeEntityDataFromEntry(entry, entities) {
             selectedSourceMcpServers: undefined,
         };
     }
+    if (entities.includes("rule")) {
+        next = {
+            ...next,
+            importedRules: [],
+            selectedSourceRules: undefined,
+            ruleRenameMap: undefined,
+        };
+    }
     if (entities.includes("skill")) {
         next = {
             ...next,
@@ -333,7 +368,7 @@ function removeEntityDataFromEntry(entry, entities) {
     }
     return finalizeEntry(next);
 }
-function removeNameFromEntry(entry, entities, candidate) {
+function removeNameFromEntry(entry, entities, candidate, deletedRuleIdentifiers) {
     let next = { ...entry };
     const normalized = normalizeName(candidate);
     if (entities.includes("agent")) {
@@ -373,6 +408,37 @@ function removeNameFromEntry(entry, entities, candidate) {
             next.selectedSourceMcpServers = [...next.importedMcpServers];
         }
     }
+    if (entities.includes("rule")) {
+        const before = [...next.importedRules];
+        const ruleMatchKeys = new Set([candidate, ...(deletedRuleIdentifiers ?? [])].flatMap(getRuleMatchKeys));
+        const matchesDeletedRule = (value) => getRuleMatchKeys(value).some((key) => ruleMatchKeys.has(key));
+        next.importedRules = next.importedRules.filter((item) => {
+            const base = path.basename(item).replace(/\.(md|mdc)$/i, "");
+            return !matchesDeletedRule(base);
+        });
+        if (next.importedRules.length !== before.length) {
+            const remainingImportedNames = new Set(next.importedRules.map((item) => path.basename(item)));
+            if (next.ruleRenameMap) {
+                const filteredRenameEntries = Object.entries(next.ruleRenameMap).filter(([, importedName]) => remainingImportedNames.has(path.basename(importedName)));
+                next.ruleRenameMap =
+                    filteredRenameEntries.length > 0
+                        ? Object.fromEntries(filteredRenameEntries)
+                        : undefined;
+            }
+            const selectorsFromRenameMap = next.ruleRenameMap
+                ? Object.keys(next.ruleRenameMap)
+                : [];
+            const renamedRuleTargets = new Set(Object.values(next.ruleRenameMap ?? {}).map((importedName) => normalizeName(path.basename(importedName))));
+            const selectorsFromUnrenamedRules = next.importedRules
+                .map((item) => path.basename(item))
+                .filter((item) => !renamedRuleTargets.has(normalizeName(path.basename(item))));
+            next.selectedSourceRules =
+                selectorsFromRenameMap.length > 0 ||
+                    selectorsFromUnrenamedRules.length > 0
+                    ? [...selectorsFromRenameMap, ...selectorsFromUnrenamedRules]
+                    : [];
+        }
+    }
     if (entities.includes("skill")) {
         const renameEntriesBeforeRemoval = Object.entries(next.skillRenameMap ?? {});
         const removedSkillTargets = next.importedSkills.filter((name) => normalizeName(name) === normalized);
@@ -400,9 +466,19 @@ function removeNameFromEntry(entry, entities, candidate) {
     }
     return finalizeEntry(next);
 }
+function ruleMatchesCandidate(rule, candidate) {
+    const candidateKeys = new Set(getRuleMatchKeys(candidate));
+    return [rule.name, rule.fileName, stripRuleFileExtension(rule.fileName)].some((value) => getRuleMatchKeys(value).some((key) => candidateKeys.has(key)));
+}
+function getRuleMatchKeys(value) {
+    const normalized = normalizeName(value);
+    const selector = normalizeRuleSelector(value);
+    return [...new Set([normalized, selector].filter(Boolean))];
+}
 function finalizeEntry(entry) {
     const hasOtherEntities = entry.importedAgents.length > 0 ||
         entry.importedMcpServers.length > 0 ||
+        entry.importedRules.length > 0 ||
         entry.importedSkills.length > 0;
     if (entry.importedCommands.length === 0) {
         entry.commandRenameMap = undefined;
@@ -412,6 +488,10 @@ function finalizeEntry(entry) {
         entry.skillRenameMap = undefined;
         entry.skillsProviders = undefined;
     }
+    if (entry.importedRules.length === 0) {
+        entry.ruleRenameMap = undefined;
+        entry.selectedSourceRules = hasOtherEntities ? [] : undefined;
+    }
     const trackedEntities = (entry.trackedEntities ?? []).filter((entity) => {
         if (entity === "agent") {
             return entry.importedAgents.length > 0 || Boolean(entry.requestedAgents);
@@ -425,6 +505,11 @@ function finalizeEntry(entry) {
             return (entry.importedMcpServers.length > 0 ||
                 Boolean(entry.selectedSourceMcpServers));
         }
+        if (entity === "rule") {
+            return (entry.importedRules.length > 0 ||
+                Boolean(entry.selectedSourceRules) ||
+                Boolean(entry.ruleRenameMap));
+        }
         return (entry.importedSkills.length > 0 ||
             Boolean(entry.selectedSourceSkills) ||
             Boolean(entry.skillsProviders) ||
@@ -437,6 +522,7 @@ function finalizeEntry(entry) {
     if (next.importedAgents.length === 0 &&
         next.importedCommands.length === 0 &&
         next.importedMcpServers.length === 0 &&
+        next.importedRules.length === 0 &&
         next.importedSkills.length === 0) {
         return null;
     }

package/dist/commands/entity-utils.js

@@ -32,6 +32,9 @@ export function getEntitySelectors(argv, entity) {
     if (entity === "mcp") {
         return getStringArrayFlag(argsRecord.mcps, getStringArrayFlag(argsRecord.mcp));
     }
+    if (entity === "rule") {
+        return getStringArrayFlag(argsRecord.rules, getStringArrayFlag(argsRecord.rule));
+    }
     return getStringArrayFlag(argsRecord.skills, getStringArrayFlag(argsRecord.skill));
 }
 export async function runPostMutationSync(options) {