agency-rules 0.5.0 → 0.6.1

package/CHANGELOG.md

@@ -5,6 +5,28 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.1](https://github.com/deuriib/agency-rules/compare/v0.6.0...v0.6.1) (2026-10-31)
+
+
+### Bug Fixes
+
+* **pkg:** move runtime dependencies out of devDependencies ([b39c1c8](https://github.com/deuriib/agency-rules/commit/b39c1c8e1f4e46c36c5854f8887b64c335cce01a))
+
+## [0.6.0](https://github.com/deuriib/agency-rules/compare/v0.5.0...v0.6.0) (2026-10-31)
+
+
+### Features
+
+* **rules:** add Agentmemory MCP guidelines ([0d68b32](https://github.com/deuriib/agency-rules/commit/0d68b32e91b5385087b34d9dc93b45576bf88ceb))
+* **rules:** add Agentmemory MCP guidelines ([1c846f5](https://github.com/deuriib/agency-rules/commit/1c846f5715137ea0d98d5365b99e4589a129a92b)), closes [#14](https://github.com/deuriib/agency-rules/issues/14)
+* **rules:** add subagent delegation guidelines ([4527e1f](https://github.com/deuriib/agency-rules/commit/4527e1f7a16fb131a09406083562d59ff9f0eb8b))
+* **rules:** add subagent delegation guidelines ([1042370](https://github.com/deuriib/agency-rules/commit/1042370beb15a15e9f9a57831a754da4ee05edbc)), closes [#15](https://github.com/deuriib/agency-rules/issues/15)
+
+
+### Bug Fixes
+
+* unused variable via biome ([7bd25b1](https://github.com/deuriib/agency-rules/commit/7bd25b1c8c1b28521d6aaee57e1d5179e0cfafab))
+
 ## [0.5.0](https://github.com/deuriib/agency-rules/compare/v0.4.1...v0.5.0) (2026-10-31)
 
 

package/bin/agency-rules.mjs

@@ -2,137 +2,25 @@
 
 import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
-import { pathToFileURL } from 'node:url';
-
-const command = process.argv[2];
-
-// ── Read version dynamically ──────────────────────────────────────────
-const getVersion = async () => {
-    try {
-        const pkgPath = resolve(import.meta.dirname, '..', 'package.json');
-        const pkg = JSON.parse(await readFile(pkgPath, 'utf8'));
-        return pkg.version || '0.0.0';
-    } catch {
-        return '0.0.0';
-    }
-};
-
-const version = await getVersion();
-
-// ── Help Menus ────────────────────────────────────────────────────────
-const showHelp = () => {
-    console.log(`
-\x1b[36magency-rules\x1b[0m v${version}
-Write rules once. Run them in every harness.
-
-\x1b[33mUsage:\x1b[0m
-  $ agency-rules <command> [options]
-
-\x1b[33mCommands:\x1b[0m
-  \x1b[32mlist\x1b[0m         List all available rules
-  \x1b[32mconvert\x1b[0m      Compile rules/ into each harness's native format
-  \x1b[32minstall\x1b[0m      Install compiled artifacts into detected harnesses
-  \x1b[32mvalidate\x1b[0m     Validate each rule's frontmatter against the schema
-
-\x1b[33mGlobal Options:\x1b[0m
-  -h, --help      Show this help message
-  -v, --version   Show version number
-
-\x1b[33mExamples:\x1b[0m
-  $ agency-rules list
-  $ agency-rules validate
-  $ agency-rules convert --dry-run
-  $ agency-rules install --scope user --harness opencode
-`);
-};
-
-const showCommandHelp = (cmd) => {
-    const helps = {
-        list: `
-\x1b[36magency-rules list\x1b[0m
-List all available rules and their descriptions.
-
-\x1b[33mOptions:\x1b[0m
-  --json            Output the list in JSON format (useful for scripting)
-
-\x1b[33mExamples:\x1b[0m
-  $ agency-rules list
-  $ agency-rules list --json | jq '.'
-`,
-        convert: `
-\x1b[36magency-rules convert\x1b[0m
-Compile rules/ into each harness's native format.
-
-\x1b[33mOptions:\x1b[0m
-  --dry-run         Preview which files would be written (no writes)
-  --harness <id>    Limit compilation to a specific harness (e.g., antigravity)
-
-\x1b[33mExamples:\x1b[0m
-  $ agency-rules convert
-  $ agency-rules convert --dry-run
-  $ agency-rules convert --harness pi-agent
-`,
-        install: `
-\x1b[36magency-rules install\x1b[0m
-Install compiled artifacts into detected harnesses.
-
-\x1b[33mOptions:\x1b[0m
-  --dry-run              Preview which files would be copied (no writes)
-  --scope <project|user> Install local to project or global to user (default: project)
-  --harness <id>         Install into a specific harness
-  --all                  Force installation for all harnesses, ignoring auto-detection
-
-\x1b[33mExamples:\x1b[0m
-  $ agency-rules install
-  $ agency-rules install --dry-run
-  $ agency-rules install --scope user
-  $ agency-rules install --harness opencode --scope project
-`,
-        validate: `
-\x1b[36magency-rules validate\x1b[0m
-Validate each rule's frontmatter against the schema.
-
-\x1b[33mOptions:\x1b[0m
-  (No specific options)
-
-\x1b[33mExamples:\x1b[0m
-  $ agency-rules validate
-`,
-    };
-    console.log(helps[cmd] || '');
-};
-
-// ── Global Flags ──────────────────────────────────────────────────────
-if (process.argv.includes('--version') || process.argv.includes('-v')) {
-    console.log(version);
-    process.exit(0);
-}
-
-if (!command || command === 'help' || command === '--help' || command === '-h') {
-    showHelp();
-    process.exit(0);
-}
-
-if (!['list', 'convert', 'install', 'validate'].includes(command)) {
-    console.error(`\x1b[31mError:\x1b[0m Unknown command '${command}'`);
-    showHelp();
-    process.exit(1);
-}
-
-// ── Command-specific Help ─────────────────────────────────────────────
-if (process.argv.includes('--help') || process.argv.includes('-h')) {
-    showCommandHelp(command);
-    process.exit(0);
-}
-
-// ── Execute ───────────────────────────────────────────────────────────
-process.argv.splice(2, 1);
-
-const scriptPath = resolve(import.meta.dirname, '..', 'scripts', `${command}.mjs`);
-
-try {
-    await import(pathToFileURL(scriptPath).href);
-} catch (err) {
-    console.error(`\x1b[31m❌ Failed to execute '${command}':\x1b[0m`, err.message);
-    process.exit(1);
-}
+import { defineCommand, runMain } from 'citty';
+
+// Read version dynamically from package.json
+const pkgPath = resolve(import.meta.dirname, '..', 'package.json');
+const pkg = JSON.parse(await readFile(pkgPath, 'utf8'));
+
+const main = defineCommand({
+  meta: {
+    name: 'agency-rules',
+    version: pkg.version,
+    description: 'Write rules once. Run them in every harness.',
+  },
+  subCommands: {
+    // Lazy load each command only when invoked
+    list: () => import('../scripts/list.mjs').then((m) => m.default),
+    convert: () => import('../scripts/convert.mjs').then((m) => m.default),
+    install: () => import('../scripts/install.mjs').then((m) => m.default),
+    validate: () => import('../scripts/validate.mjs').then((m) => m.default),
+  },
+});
+
+runMain(main);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agency-rules",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Write rules once. Run them in every harness.",
   "type": "module",
   "license": "MIT",
@@ -42,7 +42,8 @@
     "access": "public",
     "provenance": true
   },
-  "devDependencies": {
+  "dependencies": {
+    "citty": "^0.2.2",
     "ajv": "^8.17.1",
     "gray-matter": "^4.0.3",
     "yaml": "^2.5.0"

package/rules/base/agentmemory.md

@@ -0,0 +1,15 @@
+---
+name: agentmemory
+description: Guidelines and strict rules for interacting with the Agentmemory MCP server.
+alwaysApply: true
+tags: [mcp, memory, context]
+---
+
+# Agentmemory MCP Rules
+
+- **MEM-01** — Recall Before Asking. At the START of any task, call `memory_recall` (or `memory_smart_search`) with the task context before asking the user to repeat anything.
+- **MEM-02** — Save at Decision Points. When you learn something durable (a decision, a fix, a gotcha, a user preference, a project convention), call `memory_save` in the same session — do not batch it for later.
+- **MEM-03** — Lessons From Corrections. Signals this applies: explicit "always/never", "learn this", "from now on", a repeated user fix to the same behavior, "I told you before". Call `memory_save` with a confidence score; re-saving duplicate content strengthens the existing lesson instead of forking it. Before similar work, call `memory_lesson_recall` — check what was learned before deciding. One concept per lesson; state when and where it applies via context and tags.
+- **MEM-04** — Resume, Don't Restart. Resume / recap / "where were we" → `memory_sessions` plus `memory_timeline` around the anchor before doing anything else. Lead with any unanswered question from the prior session. Use `memory_timeline` for chronological context and `memory_smart_search` with `expandIds` for detail — never re-derive what history already holds.
+- **MEM-05** — Track Multi-Step Work as Actions. Work with 3+ steps → `memory_action_create` with typed dependencies; pull from `memory_frontier` / `memory_next`, not vibes. Memory lease acquire before starting an action; release or renew explicitly — leases prevent double-work across agents. Update status in real time; resolving to done unblocks dependents. Hand off via `memory_signal_send`, pick up via `memory_signal_read`.
+- **MEM-06** — Slots Are Small, Pinned State. Durable user or project state (persona, pending items) → memory slots: `memory_slot_get` / `memory_slot_list` first, then `memory_slot_replace`. Appends fail past `sizeLimit` — compact via replace first, never loop blind appends. Seeded defaults are starting values, not gospel; replace them when the user corrects them.

package/rules/base/subagent-delegation.md

@@ -0,0 +1,17 @@
+---
+name: subagent-delegation
+description: Guidelines for delegating tasks to subagents using spawn, dispatch, or invoke.
+trigger: model_decision
+tags: [workflow, subagents, context-management]
+---
+
+# Subagent Delegation Rules
+
+- **SUB-01** — Trigger Words. When the user says `spawn`, `dispatch`, or `invoke`, they are explicitly asking you to delegate the task to a subagent. Do not attempt to execute the task in the main thread.
+- **SUB-02** — When to Delegate. Use subagents for:
+  - **Context-heavy tasks:** Searching large codebases, reading multiple files, or exploring documentation.
+  - **Parallelizable work:** Multiple independent fixes or searches that can happen concurrently.
+  - **Specialized tasks:** Writing tests, refactoring specific modules, or applying strict formatting.
+- **SUB-03** — Clear Prompts. When spawning a subagent, provide a self-contained prompt. Do not assume the subagent has access to the current conversation history. Pass all necessary context, file paths, and constraints explicitly.
+- **SUB-04** — Await and Synthesize. Wait for the subagent to complete and return its result. Verify the output and synthesize it back into the main workflow before presenting the final answer to the user.
+- **SUB-05** — Fail Safely. If a subagent fails or hits a limit, do not silently retry in the main thread. Report the failure, analyze the error, and decide whether to retry the subagent with a better prompt or escalate to the user.

package/scripts/convert.mjs

@@ -1,114 +1,123 @@
-import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
-import { parseArgs } from 'node:util';
+import { defineCommand } from 'citty';
 import { readRules } from './lib/frontmatter.mjs';
 import { renderers } from './lib/renderers/index.mjs';
 
-const { values: args } = parseArgs({
-    options: {
-        'dry-run': { type: 'boolean', default: false },
-        harness: { type: 'string' },
+export default defineCommand({
+    meta: {
+        name: 'convert',
+        description: "Compile rules/ into each harness's native format",
     },
-});
-
-const dryRun = args['dry-run'];
-const prefix = dryRun ? '  [dry-run]' : ' ';
-
-// Resolve paths: Use local if exists, otherwise fallback to the package's bundled files
-const PACKAGE_ROOT = resolve(import.meta.dirname, '..');
-const localRules = resolve(process.cwd(), 'rules');
-const localTools = resolve(process.cwd(), 'tools.json');
-
-const RULES_DIR =
-    process.env.RULES_DIR ||
-    ((await import('node:fs').then((fs) => fs.existsSync(localRules)))
-        ? localRules
-        : resolve(PACKAGE_ROOT, 'rules'));
-const TOOLS_PATH = (await import('node:fs').then((fs) => fs.existsSync(localTools)))
-    ? localTools
-    : resolve(PACKAGE_ROOT, 'tools.json');
-
-const INTEGRATIONS_DIR = process.env.INTEGRATIONS_DIR || 'integrations';
-
-const tools = JSON.parse(await readFile(TOOLS_PATH, 'utf8'));
-const rules = await readRules(RULES_DIR);
-
-console.log(
-    `📚 Found ${rules.length} rule(s) in ${RULES_DIR}${dryRun ? ' (dry-run — nothing will be written)' : ''}\n`,
-);
-
-const harnessIds = args.harness ? [args.harness] : Object.keys(tools.harnesses);
-
-for (const id of harnessIds) {
-    if (!tools.harnesses[id]) {
-        console.error(`❌ Unknown harness: ${id}`);
-        process.exit(1);
-    }
-}
-
-let totalFiles = 0;
-
-for (const id of harnessIds) {
-    const harness = tools.harnesses[id];
-    const render = renderers[harness.format];
-    if (!render) {
-        console.error(`❌ No renderer for format "${harness.format}" (harness: ${id})`);
-        process.exit(1);
-    }
-
-    if (!harness.integrationPath) {
-        console.error(`❌ Missing "integrationPath" for harness "${id}" in tools.json`);
-        process.exit(1);
-    }
-
-    const harnessDir = join(INTEGRATIONS_DIR, id);
-    const manifest = [];
-
-    for (const rule of rules) {
-        let output;
-        try {
-            output = render(rule, harness);
-        } catch (err) {
-            console.error(`❌ ${id}: failed to render "${rule.slug}": ${err.message}`);
+    args: {
+        'dry-run': {
+            type: 'boolean',
+            description: 'Preview which files would be written (no writes)',
+        },
+        harness: { type: 'string', description: 'Limit compilation to a specific harness' },
+    },
+    async run({ args }) {
+        const dryRun = args['dry-run'];
+        const prefix = dryRun ? '  [dry-run]' : ' ';
+
+        const PACKAGE_ROOT = resolve(import.meta.dirname, '..');
+        const localRules = resolve(process.cwd(), 'rules');
+        const localTools = resolve(process.cwd(), 'tools.json');
+
+        const RULES_DIR =
+            process.env.RULES_DIR ||
+            ((await import('node:fs').then((fs) => fs.existsSync(localRules)))
+                ? localRules
+                : resolve(PACKAGE_ROOT, 'rules'));
+        const TOOLS_PATH = (await import('node:fs').then((fs) => fs.existsSync(localTools)))
+            ? localTools
+            : resolve(PACKAGE_ROOT, 'tools.json');
+
+        const INTEGRATIONS_DIR = process.env.INTEGRATIONS_DIR || 'integrations';
+
+        const tools = JSON.parse(await readFile(TOOLS_PATH, 'utf8'));
+        const rules = await readRules(RULES_DIR);
+
+        if (rules.length === 0) {
+            console.error(`❌ No rules found in ${RULES_DIR}`);
             process.exit(1);
         }
 
-        const relPath = harness.integrationPath.replace('{{slug}}', rule.slug);
-        const outPath = join(harnessDir, relPath);
-        manifest.push({ slug: rule.slug, path: relPath, size: output.length });
-        totalFiles++;
+        const harnessIds = args.harness ? [args.harness] : Object.keys(tools.harnesses);
 
-        if (!dryRun) {
-            await mkdir(dirname(outPath), { recursive: true });
-            await writeFile(outPath, output);
+        for (const id of harnessIds) {
+            if (!tools.harnesses[id]) {
+                console.error(`❌ Unknown harness: ${id}`);
+                process.exit(1);
+            }
         }
-    }
-
-    if (!dryRun) {
-        await writeFile(
-            join(harnessDir, '_manifest.json'),
-            JSON.stringify(
-                {
-                    harness: id,
-                    format: harness.format,
-                    files: manifest.map(({ slug, path }) => ({ slug, path })),
-                },
-                null,
-                2,
-            ),
+
+        console.log(
+            `📚 Found ${rules.length} rule(s) in ${RULES_DIR}${dryRun ? ' (dry-run — nothing will be written)' : ''}\n`,
         );
-    }
 
-    console.log(`✅ ${id.padEnd(12)} → ${manifest.length} file(s)`);
-    if (dryRun) {
-        for (const f of manifest) {
-            console.log(`${prefix} would write ${join(harnessDir, f.path)} (${f.size} bytes)`);
+        let totalFiles = 0;
+
+        for (const id of harnessIds) {
+            const harness = tools.harnesses[id];
+            const render = renderers[harness.format];
+            if (!render) {
+                console.error(`❌ No renderer for format "${harness.format}" (harness: ${id})`);
+                process.exit(1);
+            }
+
+            const harnessDir = join(INTEGRATIONS_DIR, id);
+            const manifest = [];
+
+            for (const rule of rules) {
+                let output;
+                try {
+                    output = render(rule, harness);
+                } catch (err) {
+                    console.error(`❌ ${id}: failed to render "${rule.slug}": ${err.message}`);
+                    process.exit(1);
+                }
+
+                const relPath = harness.integrationPath.replace('{{slug}}', rule.slug);
+                const outPath = join(harnessDir, relPath);
+                manifest.push({ slug: rule.slug, path: relPath, size: output.length });
+                totalFiles++;
+
+                if (!dryRun) {
+                    await mkdir(dirname(outPath), { recursive: true });
+                    await writeFile(outPath, output);
+                }
+            }
+
+            if (!dryRun) {
+                await writeFile(
+                    join(harnessDir, '_manifest.json'),
+                    JSON.stringify(
+                        {
+                            harness: id,
+                            format: harness.format,
+                            files: manifest.map(({ slug, path }) => ({ slug, path })),
+                        },
+                        null,
+                        2,
+                    ),
+                );
+            }
+
+            console.log(`✅ ${id.padEnd(12)} → ${manifest.length} file(s)`);
+            if (dryRun) {
+                for (const f of manifest) {
+                    console.log(
+                        `${prefix} would write ${join(harnessDir, f.path)} (${f.size} bytes)`,
+                    );
+                }
+            }
         }
-    }
-}
 
-const summary = dryRun
-    ? `\n🔎 Dry-run: would write ${totalFiles} file(s) across ${harnessIds.length} harness(es). Nothing was written.`
-    : `\n🎉 Wrote ${totalFiles} file(s) across ${harnessIds.length} harness(es).`;
+        const summary = dryRun
+            ? `\n🔎 Dry-run: would write ${totalFiles} file(s) across ${harnessIds.length} harness(es). Nothing was written.`
+            : `\n🎉 Wrote ${totalFiles} file(s) across ${harnessIds.length} harness(es).`;
 
-console.log(summary);
+        console.log(summary);
+    },
+});

package/scripts/install.mjs

@@ -3,159 +3,176 @@ import { copyFile, mkdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { stdin as input, stdout as output } from 'node:process';
 import { createInterface } from 'node:readline/promises';
-import { parseArgs } from 'node:util';
+import { defineCommand } from 'citty';
 import { detectHarnesses, expandHome, pathExists } from './lib/detect.mjs';
 
-const { values: args } = parseArgs({
-    options: {
-        scope: { type: 'string' },
-        harness: { type: 'string' },
-        all: { type: 'boolean', default: false },
-        'dry-run': { type: 'boolean', default: false },
+export default defineCommand({
+    meta: {
+        name: 'install',
+        description: 'Install compiled artifacts into detected harnesses',
     },
-});
-
-const dryRun = args['dry-run'];
-const tag = dryRun ? '[dry-run]' : '     ';
-const log = (msg) => console.log(`  ${tag} ${msg}`);
-
-const INTEGRATIONS_DIR = process.env.INTEGRATIONS_DIR || 'integrations';
-
-const PACKAGE_ROOT = resolve(import.meta.dirname, '..');
-const localTools = resolve(process.cwd(), 'tools.json');
-const TOOLS_PATH = existsSync(localTools) ? localTools : resolve(PACKAGE_ROOT, 'tools.json');
-
-const tools = JSON.parse(await readFile(TOOLS_PATH, 'utf8'));
-
-let finalScope = args.scope;
-let finalHarness = args.harness;
-
-// ── Interactive Mode (si no se pasan parámetros y es una terminal) ─────
-if (input.isTTY && ((!finalHarness && !args.all) || !finalScope)) {
-    const rl = createInterface({ input, output });
-
-    if (!finalHarness && !args.all) {
-        console.log('\n🎯 Select a harness to install into:');
-        const keys = Object.keys(tools.harnesses);
-        keys.forEach((k, i) => {
-            console.log(`  ${i + 1}) ${k} (${tools.harnesses[k].label})`);
-        });
-        console.log(`  ${keys.length + 1}) Detect automatically`);
-        console.log(`  ${keys.length + 2}) All harnesses`);
-
-        const answer = await rl.question(`\nChoice [1-${keys.length + 2}] (default: detect): `);
-        const num = parseInt(answer.trim(), 10);
-
-        if (!Number.isNaN(num) && num >= 1 && num <= keys.length) {
-            finalHarness = keys[num - 1];
-        } else if (num === keys.length + 2 || answer.trim().toLowerCase() === 'all') {
-            args.all = true;
+    args: {
+        scope: {
+            type: 'string',
+            description: 'Install local to project or global to user (default: project)',
+        },
+        harness: { type: 'string', description: 'Install into a specific harness' },
+        all: {
+            type: 'boolean',
+            description: 'Force installation for all harnesses, ignoring auto-detection',
+        },
+        'dry-run': {
+            type: 'boolean',
+            description: 'Preview which files would be copied (no writes)',
+        },
+    },
+    async run({ args }) {
+        const dryRun = args['dry-run'];
+        const tag = dryRun ? '[dry-run]' : '     ';
+        const log = (msg) => console.log(`  ${tag} ${msg}`);
+
+        const INTEGRATIONS_DIR = process.env.INTEGRATIONS_DIR || 'integrations';
+
+        const PACKAGE_ROOT = resolve(import.meta.dirname, '..');
+        const localTools = resolve(process.cwd(), 'tools.json');
+        const TOOLS_PATH = existsSync(localTools)
+            ? localTools
+            : resolve(PACKAGE_ROOT, 'tools.json');
+
+        const tools = JSON.parse(await readFile(TOOLS_PATH, 'utf8'));
+
+        let finalScope = args.scope;
+        let finalHarness = args.harness;
+        let forceAll = args.all;
+
+        // Interactive Mode
+        if (input.isTTY && ((!finalHarness && !forceAll) || !finalScope)) {
+            const rl = createInterface({ input, output });
+
+            if (!finalHarness && !forceAll) {
+                console.log('\n🎯 Select a harness to install into:');
+                const keys = Object.keys(tools.harnesses);
+                keys.forEach((k, i) => {
+                    console.log(`  ${i + 1}) ${k} (${tools.harnesses[k].label})`);
+                });
+                console.log(`  ${keys.length + 1}) Detect automatically`);
+                console.log(`  ${keys.length + 2}) All harnesses`);
+
+                const answer = await rl.question(
+                    `\nChoice [1-${keys.length + 2}] (default: detect): `,
+                );
+                const num = parseInt(answer.trim(), 10);
+
+                if (!Number.isNaN(num) && num >= 1 && num <= keys.length) {
+                    finalHarness = keys[num - 1];
+                } else if (num === keys.length + 2 || answer.trim().toLowerCase() === 'all') {
+                    forceAll = true;
+                }
+            }
+
+            if (!finalScope) {
+                console.log('\n🌍 Select installation scope:');
+                console.log('  1) project (local to this repo)');
+                console.log('  2) user (global for your user)');
+
+                const answer = await rl.question('\nChoice [1-2] (default: 1): ');
+                finalScope =
+                    answer.trim() === '2' || answer.trim().toLowerCase() === 'user'
+                        ? 'user'
+                        : 'project';
+            }
+
+            rl.close();
+            console.log('');
         }
-    }
-
-    if (!finalScope) {
-        console.log('\n🌍 Select installation scope:');
-        console.log('  1) project (local to this repo)');
-        console.log('  2) user (global for your user)');
-
-        const answer = await rl.question('\nChoice [1-2] (default: 1): ');
-        finalScope =
-            answer.trim() === '2' || answer.trim().toLowerCase() === 'user' ? 'user' : 'project';
-    }
 
-    rl.close();
-    console.log('');
-}
-
-// Fallback si no se seleccionó nada
-if (!finalScope) finalScope = 'project';
+        if (!finalScope) finalScope = 'project';
 
-if (!['project', 'user'].includes(finalScope)) {
-    console.error(`❌ Invalid --scope: ${finalScope} (use "project" or "user")`);
-    process.exit(1);
-}
-
-let targets;
-if (finalHarness) {
-    if (!tools.harnesses[finalHarness]) {
-        console.error(`❌ Unknown harness: ${finalHarness}`);
-        process.exit(1);
-    }
-    targets = [finalHarness];
-} else if (args.all) {
-    targets = Object.keys(tools.harnesses);
-} else {
-    targets = await detectHarnesses(tools);
-    if (targets.length === 0) {
-        console.warn('⚠️  No harness detected. Pass --harness <id> or --all to force.');
-        process.exit(0);
-    }
-}
-
-console.log(
-    `🔍 Targets: ${targets.join(', ')} (scope: ${finalScope})${
-        dryRun ? ' — dry-run, no changes will be made' : ''
-    }\n`,
-);
-
-let copied = 0;
-let skippedHarnesses = 0;
-let pluginChanges = 0;
+        if (!['project', 'user'].includes(finalScope)) {
+            console.error(`❌ Invalid --scope: ${finalScope} (use "project" or "user")`);
+            process.exit(1);
+        }
 
-for (const id of targets) {
-    const harness = tools.harnesses[id];
-    const srcDir = join(INTEGRATIONS_DIR, id);
+        let targets;
+        if (finalHarness) {
+            if (!tools.harnesses[finalHarness]) {
+                console.error(`❌ Unknown harness: ${finalHarness}`);
+                process.exit(1);
+            }
+            targets = [finalHarness];
+        } else if (forceAll) {
+            targets = Object.keys(tools.harnesses);
+        } else {
+            targets = await detectHarnesses(tools);
+            if (targets.length === 0) {
+                console.warn('⚠️  No harness detected. Pass --harness <id> or --all to force.');
+                process.exit(0);
+            }
+        }
 
-    if (!(await pathExists(srcDir))) {
-        console.warn(
-            `⚠️  ${id}: no compiled output at ${srcDir}, skipping. Run "mise run convert" first.`,
+        console.log(
+            `🔍 Targets: ${targets.join(', ')} (scope: ${finalScope})${dryRun ? ' — dry-run, no changes will be made' : ''}\n`,
         );
-        skippedHarnesses++;
-        continue;
-    }
-
-    const manifest = JSON.parse(await readFile(join(srcDir, '_manifest.json'), 'utf8'));
-    const destTemplate = harness.dest[finalScope];
-    if (!destTemplate) {
-        console.warn(`⚠️  ${id}: no dest for scope "${finalScope}"`);
-        skippedHarnesses++;
-        continue;
-    }
 
-    for (const { slug, path: relPath } of manifest.files) {
-        const destPath = expandHome(destTemplate.replace('{{slug}}', slug));
-        if (dryRun) {
-            log(`${id}: would copy ${relPath} → ${destPath}`);
-        } else {
-            await mkdir(dirname(destPath), { recursive: true });
-            await copyFile(join(srcDir, relPath), destPath);
-            log(`${id}: ${destPath}`);
+        let copied = 0;
+        let skippedHarnesses = 0;
+        let pluginChanges = 0;
+
+        for (const id of targets) {
+            const harness = tools.harnesses[id];
+            const srcDir = join(INTEGRATIONS_DIR, id);
+
+            if (!(await pathExists(srcDir))) {
+                console.warn(
+                    `⚠️  ${id}: no compiled output at ${srcDir}, skipping. Run "mise run convert" first.`,
+                );
+                skippedHarnesses++;
+                continue;
+            }
+
+            const manifest = JSON.parse(await readFile(join(srcDir, '_manifest.json'), 'utf8'));
+            const destTemplate = harness.dest[finalScope];
+            if (!destTemplate) {
+                console.warn(`⚠️  ${id}: no dest for scope "${finalScope}"`);
+                skippedHarnesses++;
+                continue;
+            }
+
+            for (const { slug, path: relPath } of manifest.files) {
+                const destPath = expandHome(destTemplate.replace('{{slug}}', slug));
+                if (dryRun) {
+                    log(`${id}: would copy ${relPath} → ${destPath}`);
+                } else {
+                    await mkdir(dirname(destPath), { recursive: true });
+                    await copyFile(join(srcDir, relPath), destPath);
+                    log(`${id}: ${destPath}`);
+                }
+                copied++;
+            }
+
+            if (harness.plugin) {
+                const changed = await handlePlugin(id, harness.plugin, finalScope, dryRun, log);
+                if (changed) pluginChanges++;
+            }
         }
-        copied++;
-    }
 
-    if (harness.plugin) {
-        const changed = await handlePlugin(id, harness.plugin, finalScope, dryRun, log);
-        if (changed) pluginChanges++;
-    }
-}
+        console.log(
+            dryRun
+                ? `\n🔎 Dry-run: would copy ${copied} file(s) across ${targets.length - skippedHarnesses} harness(es).` +
+                      (pluginChanges ? ` Would update ${pluginChanges} plugin config(s).` : '') +
+                      ' Nothing was written.'
+                : `\n🎉 Installed ${copied} file(s) across ${targets.length - skippedHarnesses} harness(es).` +
+                      (pluginChanges ? ` Updated ${pluginChanges} plugin config(s).` : ''),
+        );
 
-console.log(
-    dryRun
-        ? `\n🔎 Dry-run: would copy ${copied} file(s) across ${targets.length - skippedHarnesses} harness(es).` +
-              (pluginChanges ? ` Would update ${pluginChanges} plugin config(s).` : '') +
-              ' Nothing was written.'
-        : `\n🎉 Installed ${copied} file(s) across ${targets.length - skippedHarnesses} harness(es).` +
-              (pluginChanges ? ` Updated ${pluginChanges} plugin config(s).` : ''),
-);
-
-if (dryRun && skippedHarnesses > 0) {
-    console.log(
-        `\n⚠️  ${skippedHarnesses} harness(es) skipped due to missing integrations. Run "mise run convert" first.`,
-    );
-}
+        if (dryRun && skippedHarnesses > 0) {
+            console.log(
+                `\n⚠️  ${skippedHarnesses} harness(es) skipped due to missing integrations. Run "mise run convert" first.`,
+            );
+        }
+    },
+});
 
-// ── Plugin registration ──────────────────────────────────────────────
 async function handlePlugin(id, plugin, scope, dry, logFn) {
     const configPath =
         scope === 'user'

package/scripts/list.mjs

@@ -1,48 +1,53 @@
 import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { parseArgs } from 'node:util';
+import { defineCommand } from 'citty';
 import { readRules } from './lib/frontmatter.mjs';
 
-const { values: args } = parseArgs({
-    options: {
-        json: { type: 'boolean', default: false },
+export default defineCommand({
+    meta: {
+        name: 'list',
+        description: 'List all available rules',
+    },
+    args: {
+        json: {
+            type: 'boolean',
+            description: 'Output in JSON format',
+            default: false,
+        },
+    },
+    async run({ args }) {
+        const PACKAGE_ROOT = resolve(import.meta.dirname, '..');
+        const localRules = resolve(process.cwd(), 'rules');
+        const RULES_DIR =
+            process.env.RULES_DIR ||
+            (existsSync(localRules) ? localRules : resolve(PACKAGE_ROOT, 'rules'));
+
+        const rules = await readRules(RULES_DIR);
+
+        if (rules.length === 0) {
+            console.error(`❌ No rules found in ${RULES_DIR}`);
+            process.exit(1);
+        }
+
+        if (args.json) {
+            const output = rules.map((r) => ({
+                name: r.slug,
+                description: r.data.description || 'No description provided',
+                source: r.source,
+            }));
+            console.log(JSON.stringify(output, null, 2));
+            return;
+        }
+
+        const maxSlugLength = Math.max(...rules.map((r) => r.slug.length));
+        console.log(`\n📚 \x1b[1mAvailable Rules\x1b[0m (${rules.length})\n`);
+
+        for (const rule of rules) {
+            const paddedSlug = rule.slug.padEnd(maxSlugLength);
+            console.log(
+                `  \x1b[36m${paddedSlug}\x1b[0m  ${rule.data.description || 'No description'}`,
+            );
+        }
+        console.log('\n');
     },
 });
-
-// Resolve paths (local vs package fallback)
-const PACKAGE_ROOT = resolve(import.meta.dirname, '..');
-const localRules = resolve(process.cwd(), 'rules');
-const RULES_DIR =
-    process.env.RULES_DIR || (existsSync(localRules) ? localRules : resolve(PACKAGE_ROOT, 'rules'));
-
-const rules = await readRules(RULES_DIR);
-
-if (rules.length === 0) {
-    console.error(`❌ No rules found in ${RULES_DIR}`);
-    process.exit(1);
-}
-
-// ── JSON Output ───────────────────────────────────────────────────────
-if (args.json) {
-    const output = rules.map((r) => ({
-        name: r.slug,
-        description: r.data.description || 'No description provided',
-        source: r.source,
-    }));
-    console.log(JSON.stringify(output, null, 2));
-    process.exit(0);
-}
-
-// ── Pretty Terminal Output ────────────────────────────────────────────
-// Find the longest name to align the columns perfectly
-const maxSlugLength = Math.max(...rules.map((r) => r.slug.length));
-
-console.log(`\n📚 \x1b[1mAvailable Rules\x1b[0m (${rules.length})\n`);
-
-for (const rule of rules) {
-    const paddedSlug = rule.slug.padEnd(maxSlugLength);
-    // Using Cyan for the rule name
-    console.log(`  \x1b[36m${paddedSlug}\x1b[0m  ${rule.data.description || 'No description'}`);
-}
-
-console.log('\n');

package/scripts/validate.mjs

@@ -1,52 +1,67 @@
 import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
 import Ajv from 'ajv';
+import { defineCommand } from 'citty';
 import { readRules } from './lib/frontmatter.mjs';
 
-const RULES_DIR = process.env.RULES_DIR || 'rules';
+export default defineCommand({
+    meta: {
+        name: 'validate',
+        description: "Validate each rule's frontmatter against the schema",
+    },
+    async run() {
+        const PACKAGE_ROOT = resolve(import.meta.dirname, '..');
+        const localRules = resolve(process.cwd(), 'rules');
+        const RULES_DIR =
+            process.env.RULES_DIR || (localRules ? localRules : resolve(PACKAGE_ROOT, 'rules'));
 
-const schema = JSON.parse(await readFile(join(RULES_DIR, '_schema.json'), 'utf8'));
-const ajv = new Ajv({ allErrors: true, strict: false });
-const validate = ajv.compile(schema);
+        const schema = JSON.parse(await readFile(join(RULES_DIR, '_schema.json'), 'utf8'));
+        const ajv = new Ajv({ allErrors: true, strict: false });
+        const validate = ajv.compile(schema);
 
-const rules = await readRules(RULES_DIR);
+        const rules = await readRules(RULES_DIR);
 
-if (rules.length === 0) {
-    console.error(`❌ No rules found in ${RULES_DIR}`);
-    process.exit(1);
-}
+        if (rules.length === 0) {
+            console.error(`❌ No rules found in ${RULES_DIR}`);
+            process.exit(1);
+        }
 
-const seen = new Set();
-let failures = 0;
+        const seen = new Set();
+        let failures = 0;
 
-for (const rule of rules) {
-    const errors = [];
+        for (const rule of rules) {
+            const errors = [];
 
-    if (seen.has(rule.slug)) {
-        errors.push({ instancePath: '/name', message: `duplicate rule name "${rule.slug}"` });
-    }
-    seen.add(rule.slug);
+            if (seen.has(rule.slug)) {
+                errors.push({
+                    instancePath: '/name',
+                    message: `duplicate rule name "${rule.slug}"`,
+                });
+            }
+            seen.add(rule.slug);
 
-    if (!validate(rule.data)) {
-        for (const e of validate.errors ?? []) {
-            errors.push(e);
-        }
-    }
+            if (!validate(rule.data)) {
+                for (const e of validate.errors ?? []) {
+                    errors.push(e);
+                }
+            }
 
-    if (errors.length > 0) {
-        failures++;
-        console.error(`❌ ${rule.source}`);
-        for (const e of errors) {
-            console.error(`   ${e.instancePath || '/'} ${e.message}`);
+            if (errors.length > 0) {
+                failures++;
+                console.error(`❌ ${rule.source}`);
+                for (const e of errors) {
+                    console.error(`   ${e.instancePath || '/'} ${e.message}`);
+                }
+            } else {
+                console.log(`✅ ${rule.source}`);
+            }
         }
-    } else {
-        console.log(`✅ ${rule.source}`);
-    }
-}
 
-if (failures > 0) {
-    console.error(`\n💥 ${failures}/${rules.length} rule(s) failed validation.`);
-    process.exit(1);
-}
+        if (failures > 0) {
+            console.error(`\n💥 ${failures}/${rules.length} rule(s) failed validation.`);
+            process.exit(1);
+        }
 
-console.log(`\n🎉 ${rules.length} rule(s) validated successfully.`);
+        console.log(`\n🎉 ${rules.length} rule(s) validated successfully.`);
+    },
+});