loadout-ai 0.8.0 → 0.9.1

package/catalog/packages.json

@@ -116,7 +116,7 @@
     "description": "Skills Catalog for Codex.",
     "category": "agent-skills",
     "tier": "official",
-    "license": "NOASSERTION",
+    "license": "MIT",
     "components": ["skill"],
     "operatingSystems": ["windows", "macos", "linux"],
     "stars": 23702,
@@ -139,7 +139,7 @@
     "description": "Public repository for Agent Skills.",
     "category": "agent-skills",
     "tier": "official",
-    "license": "NOASSERTION",
+    "license": "MIT",
     "components": ["skill"],
     "operatingSystems": ["windows", "macos", "linux"],
     "stars": 161108,
@@ -185,7 +185,7 @@
     "description": "Vercel's official collection of agent skills.",
     "category": "frontend-development",
     "tier": "official",
-    "license": "NOASSERTION",
+    "license": "Apache-2.0",
     "components": ["skill"],
     "operatingSystems": ["windows", "macos", "linux"],
     "stars": 29060,
@@ -810,7 +810,7 @@
     "description": "Official reference MCP servers for filesystem, Git, memory, fetching, time, and protocol testing.",
     "category": "mcp-reference",
     "tier": "official",
-    "license": "NOASSERTION",
+    "license": "MIT",
     "components": ["mcp"],
     "operatingSystems": ["windows", "macos", "linux"],
     "stars": 88530,

package/dist/src/cli.js

@@ -12,6 +12,7 @@ import { registerInventory } from "./commands/inventory.js";
 import { registerCatalog } from "./commands/catalog.js";
 import { registerMcp } from "./commands/mcp.js";
 import { registerLifecycle } from "./commands/lifecycle.js";
+import { registerCoordinate } from "./commands/coordinate.js";
 const program = new Command();
 program
     .name("loadout")
@@ -35,10 +36,17 @@ registerInventory(program);
 registerCatalog(program);
 registerMcp(program);
 registerLifecycle(program);
-registerCompletionCommands(program.commands.map((command) => ({
-    name: command.name(),
-    subcommands: command.commands.map((sub) => sub.name()),
-})));
+registerCoordinate(program);
+registerCompletionCommands(program.commands.flatMap((command) => {
+    const subcommands = command.commands.flatMap((subcommand) => [
+        subcommand.name(),
+        ...subcommand.aliases(),
+    ]);
+    return [command.name(), ...command.aliases()].map((name) => ({
+        name,
+        subcommands,
+    }));
+}));
 for (const command of program.commands)
     // Commander supports `hidden` when a command is created. These commands are
     // registered by separate feature blocks, so use the same runtime flag here

package/dist/src/commands/agents.js

@@ -37,7 +37,9 @@ export function registerAgents(program) {
             const snapshotId = await applyProjectActivation(plan);
             console.log(options.json
                 ? JSON.stringify({ plan, snapshotId }, null, 2)
-                : `${formatProjectActivation(plan)}\nApplied and verified. Snapshot: ${snapshotId}\nRollback: loadout rollback --snapshot ${snapshotId}`);
+                : snapshotId
+                    ? `${formatProjectActivation(plan)}\nApplied and verified. Snapshot: ${snapshotId}\nRollback: loadout rollback --snapshot ${snapshotId}`
+                    : `${formatProjectActivation(plan)}\nAlready within the requested active-set limit. No changes or snapshot were needed.`);
         });
     }
     for (const action of [

package/dist/src/commands/catalog-candidate.js

@@ -0,0 +1,150 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { loadEffectiveCatalog, promoteCatalogCandidate, validateCatalog, } from "../core/catalog/catalog.js";
+import { buildCandidateDossier, buildCatalogProposal, formatCandidateDossier, formatCandidateSummaries, listDiscoveryCandidates, readCandidateDossier, verifyCandidateDossierSource, writeCandidateDossier, } from "../core/discovery/candidate-intelligence.js";
+import { markPromoted } from "../core/discovery/review-queue.js";
+import { writeFileAtomically } from "../core/install/atomic-file.js";
+export function registerCandidateCommands(program) {
+    const candidate = program
+        .command("candidate")
+        .description("Triage and statically inspect daily discovery candidates; never auto-promotes");
+    candidate
+        .command("list")
+        .allowExcessArguments(false)
+        .description("Rank discovery leads for human triage, not as universal quality")
+        .option("--limit <count>", "maximum candidates", "20")
+        .option("--query <words>", "require all search words")
+        .option("--include-reviewed", "include repositories already in the catalog")
+        .option("--feed <path>", "alternate discovered.json evidence feed")
+        .option("--json", "emit machine-readable JSON")
+        .action(async (options) => {
+        const limit = Number(options.limit);
+        if (!Number.isInteger(limit) || limit < 1 || limit > 500)
+            throw new Error("--limit must be an integer from 1 to 500");
+        const result = await listDiscoveryCandidates({
+            limit,
+            query: options.query,
+            includeReviewed: options.includeReviewed,
+            path: options.feed,
+        });
+        console.log(options.json
+            ? JSON.stringify(result, null, 2)
+            : formatCandidateSummaries(result));
+    });
+    candidate
+        .command("inspect")
+        .allowExcessArguments(false)
+        .description("Clone one lead at an immutable commit and build a static evidence dossier")
+        .argument("<repository>", "owner/repository present in the discovery feed")
+        .option("--feed <path>", "alternate discovered.json evidence feed")
+        .option("--write", "persist the dossier in private Loadout state")
+        .option("--output <path>", "persist at an explicit path (implies --write)")
+        .option("--json", "emit the complete dossier as JSON")
+        .action(async (repository, options) => {
+        const dossier = await buildCandidateDossier(repository, {
+            discoveryPath: options.feed,
+        });
+        const path = options.write || options.output
+            ? await writeCandidateDossier(dossier, options.output)
+            : undefined;
+        if (options.json)
+            return console.log(JSON.stringify({
+                dossier,
+                persisted: Boolean(path),
+                ...(path ? { path } : {}),
+            }, null, 2));
+        console.log(formatCandidateDossier(dossier));
+        if (path)
+            console.log(`Dossier: ${path}`);
+        else {
+            console.log("Preview only. Re-run with --write to persist this dossier.");
+        }
+    });
+    candidate
+        .command("propose")
+        .allowExcessArguments(false)
+        .description("Convert a reviewed dossier into a catalog-record proposal; never edits the catalog")
+        .argument("<dossier>", "persisted candidate dossier JSON")
+        .requiredOption("--id <id>", "lowercase kebab-case catalog id")
+        .requiredOption("--category <category>", "inspected catalog category")
+        .requiredOption("--platforms <ids>", "explicitly reviewed comma-separated platforms: windows,macos,linux")
+        .option("--display-name <name>", "reviewed display name")
+        .option("--description <text>", "reviewed description")
+        .option("--license <spdx>", "human-reviewed license override")
+        .option("--tier <tier>", "official, stable, trending, or community", "community")
+        .option("--approve", "confirm human review and write the proposal")
+        .option("--output <path>", "proposal JSON output path; required with --approve")
+        .option("--json", "emit machine-readable JSON")
+        .action(async (dossierPath, options) => {
+        const platforms = options.platforms
+            .split(",")
+            .map((item) => item.trim())
+            .filter(Boolean);
+        const knownPlatforms = new Set(["windows", "macos", "linux"]);
+        if (platforms.some((item) => !knownPlatforms.has(item)))
+            throw new Error("--platforms supports only windows, macos, and linux");
+        const knownTiers = new Set([
+            "official",
+            "stable",
+            "trending",
+            "community",
+        ]);
+        if (!knownTiers.has(options.tier))
+            throw new Error("--tier is invalid");
+        if (options.approve && !options.output)
+            throw new Error("--approve requires --output so catalog mutation stays separate");
+        const proposal = buildCatalogProposal(await verifyCandidateDossierSource(await readCandidateDossier(dossierPath)), {
+            id: options.id,
+            category: options.category,
+            operatingSystems: platforms,
+            tier: options.tier,
+            displayName: options.displayName,
+            description: options.description,
+            license: options.license,
+        }, await loadEffectiveCatalog());
+        const output = options.approve ? resolve(options.output) : undefined;
+        if (output)
+            await writeFileAtomically(output, `${JSON.stringify(proposal, null, 2)}\n`);
+        if (options.json)
+            return console.log(JSON.stringify({
+                proposal,
+                approved: Boolean(output),
+                catalogMutated: false,
+                ...(output ? { output } : {}),
+            }, null, 2));
+        console.log(JSON.stringify(proposal, null, 2));
+        if (!output)
+            console.log("Proposal preview only. Human review is still required; use --approve --output <path> to persist it.");
+        else
+            console.log(`Approved proposal written to ${output}.`);
+    });
+    candidate
+        .command("promote")
+        .allowExcessArguments(false)
+        .description("Merge a reviewed proposal into the local catalog; requires --approve")
+        .argument("<proposal>", "proposal JSON file from `candidate propose --approve`")
+        .option("--approve", "confirm human review and write to catalog")
+        .option("--json", "emit machine-readable JSON")
+        .action(async (proposalPath, options) => {
+        const proposal = JSON.parse(await readFile(resolve(proposalPath), "utf8"));
+        validateCatalog([proposal], { requireEvidence: true });
+        if (!options.approve) {
+            if (options.json)
+                return console.log(JSON.stringify({ proposal, promoted: false, catalogMutated: false }, null, 2));
+            console.log(JSON.stringify(proposal, null, 2));
+            console.log("Preview only. Re-run with --approve to merge into the catalog.");
+            return;
+        }
+        const result = await promoteCatalogCandidate(proposal);
+        const item = await markPromoted(proposal.repository);
+        if (options.json)
+            return console.log(JSON.stringify({
+                proposal,
+                promoted: true,
+                catalogMutated: true,
+                ...result,
+                reviewQueue: item,
+            }, null, 2));
+        console.log(`Promoted '${proposal.id}' into ${result.catalogPath} (${result.totalRecords} records). Review queue: ${item.repository} marked promoted.`);
+    });
+}

package/dist/src/commands/catalog-workflows.js

@@ -0,0 +1,365 @@
+import { parseAgentSelection } from "../core/agents/paths.js";
+import { applyFirstPartySkill, FIRST_PARTY_SKILLS, formatFirstPartySkillList, formatFirstPartySkillPlan, installedFirstPartySkills, planFirstPartySkill, removeFirstPartySkill, } from "../core/delegation/first-party-skills.js";
+import { applyPickup, formatHandoffStatus, formatInboxWithBundles, getHandoffState, initHandoff, isHandoffInitialized, isPickupTarget, planPickup, readInbox, sendHandoff, } from "../core/delegation/handoff.js";
+import { createHandoffBundle, removeHandoffBundle, } from "../core/delegation/handoff-bundle.js";
+import { completeHandoff } from "../core/delegation/handoff-verification.js";
+import { applyTemplate, deleteTemplate, formatTemplateDetail, formatTemplateList, listTemplates, loadTemplate, saveTemplate, } from "../core/delegation/handoff-templates.js";
+import { completionCommandPaths, parseCompletionShell, renderShellCompletion, } from "../core/reporting/completion.js";
+export function registerWorkflowCommands(program) {
+    const skills = program
+        .command("skills")
+        .description("Install the skills Loadout ships so your agents can use Loadout from inside a conversation");
+    skills
+        .command("list", { isDefault: true })
+        .description("Show the skills Loadout ships and whether they are installed")
+        .option("--json", "emit machine-readable JSON")
+        .action(async (options) => {
+        const installed = await installedFirstPartySkills();
+        console.log(options.json
+            ? JSON.stringify(FIRST_PARTY_SKILLS.map((skill) => ({
+                ...skill,
+                installed: installed.has(skill.id),
+            })), null, 2)
+            : formatFirstPartySkillList(installed));
+    });
+    skills
+        .command("install")
+        .description("Preview or install one Loadout skill into detected agents")
+        .argument("<id>", "skill id, for example loadout-handoff")
+        .option("--agents <ids>", "comma-separated agent ids; defaults to all detected")
+        .option("--yes", "apply after previewing")
+        .action(async (id, options) => {
+        const plan = await planFirstPartySkill(id, {
+            ...(options.agents
+                ? { agents: parseAgentSelection(options.agents) }
+                : {}),
+        });
+        console.log(formatFirstPartySkillPlan(plan));
+        if (!plan.targets.length)
+            return;
+        if (!options.yes) {
+            console.log("\nPreview only. Re-run with --yes to install.");
+            return;
+        }
+        const snapshotId = await applyFirstPartySkill(plan);
+        console.log(`\nInstalled '${plan.skill.id}' for ${plan.targets.length} agent(s). Snapshot: ${snapshotId}\nStart a new agent session to pick it up.`);
+    });
+    skills
+        .command("remove")
+        .description("Preview or remove one Loadout skill from detected agents")
+        .argument("<id>", "skill id")
+        .option("--agents <ids>", "comma-separated agent ids; defaults to all detected")
+        .option("--yes", "apply after previewing")
+        .action(async (id, options) => {
+        const plan = await planFirstPartySkill(id, {
+            ...(options.agents
+                ? { agents: parseAgentSelection(options.agents) }
+                : {}),
+        });
+        const present = plan.targets.filter((target) => target.replacing);
+        if (!present.length) {
+            console.log(`'${id}' is not installed for any detected agent.`);
+            return;
+        }
+        for (const target of present)
+            console.log(`  remove → ${target.destination}  [${target.displayName}]`);
+        if (!options.yes) {
+            console.log("\nPreview only. Re-run with --yes to remove.");
+            return;
+        }
+        const snapshotId = await removeFirstPartySkill(plan);
+        console.log(`\nRemoved '${id}' from ${present.length} agent(s). Snapshot: ${snapshotId}`);
+    });
+    const handoff = program
+        .command("handoff")
+        .description("Hand a task to your other agent, or see what has been handed to you");
+    handoff
+        .argument("[agent]", "who should do it, for example codex")
+        .argument("[task...]", "what they should do")
+        .option("--context <text>", "anything they need that is not in the task")
+        .option("--bundle <paths...>", "attach bounded snapshots of project-relative text files")
+        .option("--from <agent>", "who is sending", "user")
+        .option("--verify <criteria>", "acceptance criteria for this task")
+        .option("--verify-command <executable>", "executable to run on --done (never uses a shell)")
+        .option("--verify-args <json>", "JSON array of literal arguments for --verify-command")
+        .option("--verify-timeout <seconds>", "verification timeout in seconds (1-900; default 120)")
+        .option("--done <id>", "mark a task finished")
+        .option("--run-verification", "explicitly approve the stored no-shell verification command")
+        .option("--evidence <text>", "manual evidence for human-only criteria")
+        .option("--template <name>", "use a handoff template for defaults")
+        .option("--json", "emit machine-readable JSON")
+        .action(async (agent, taskWords, options) => {
+        const cwd = process.cwd();
+        // Apply template defaults if specified
+        if (options.template) {
+            const tmpl = await loadTemplate(cwd, options.template);
+            if (!tmpl) {
+                throw new Error(`Unknown template '${options.template}'. List with: loadout template list`);
+            }
+            const applied = applyTemplate(tmpl, {
+                input: taskWords.join(" ").trim() || undefined,
+                agent: agent || undefined,
+            });
+            if (applied.agent && !agent)
+                agent = applied.agent;
+            if (applied.description)
+                taskWords = [applied.description];
+            if (applied.context && !options.context)
+                options.context = applied.context;
+            if (applied.bundleGlobs?.length) {
+                options.bundle = [
+                    ...new Set([...(options.bundle ?? []), ...applied.bundleGlobs]),
+                ];
+            }
+            if (applied.verifyCriteria && !options.verify)
+                options.verify = applied.verifyCriteria;
+            if (applied.verifyCommand && !options.verifyCommand) {
+                options.verifyCommand = applied.verifyCommand.executable;
+                options.verifyArgs = JSON.stringify(applied.verifyCommand.args);
+                options.verifyTimeout = String(applied.verifyCommand.timeoutMs / 1000);
+            }
+        }
+        if (options.verifyCommand && !options.verify)
+            throw new Error("--verify-command requires --verify");
+        if (options.verifyArgs && !options.verifyCommand)
+            throw new Error("--verify-args requires --verify-command");
+        if (options.verifyTimeout && !options.verifyCommand)
+            throw new Error("--verify-timeout requires --verify-command");
+        if (options.evidence && !options.done)
+            throw new Error("--evidence requires --done");
+        if (options.runVerification && !options.done)
+            throw new Error("--run-verification requires --done");
+        let verifyArgs = [];
+        if (options.verifyArgs) {
+            let parsed;
+            try {
+                parsed = JSON.parse(options.verifyArgs);
+            }
+            catch {
+                throw new Error("--verify-args must be a JSON array of strings");
+            }
+            if (!Array.isArray(parsed) ||
+                parsed.some((value) => typeof value !== "string"))
+                throw new Error("--verify-args must be a JSON array of strings");
+            verifyArgs = parsed;
+        }
+        const timeoutSeconds = options.verifyTimeout
+            ? Number(options.verifyTimeout)
+            : 120;
+        if (options.verifyCommand &&
+            (!Number.isInteger(timeoutSeconds) ||
+                timeoutSeconds < 1 ||
+                timeoutSeconds > 900))
+            throw new Error("--verify-timeout must be an integer from 1 to 900");
+        if (options.done) {
+            const outcome = await completeHandoff(cwd, options.done, {
+                ...(options.runVerification ? { approveCommand: true } : {}),
+                ...(options.evidence ? { manualEvidence: options.evidence } : {}),
+            });
+            console.log(options.json
+                ? JSON.stringify(outcome, null, 2)
+                : outcome.completed
+                    ? outcome.message.evidence
+                        ? `Marked ${options.done} done with verification evidence.`
+                        : `Marked ${options.done} done.`
+                    : `Verification failed for ${options.done}; the task remains pending.\n${outcome.message.evidence?.stderr || outcome.message.evidence?.stdout || "No command output."}`);
+            if (!outcome.completed)
+                process.exitCode = 1;
+            return;
+        }
+        // No agent named: show what is waiting, for everyone.
+        if (!agent) {
+            const state = await getHandoffState(cwd);
+            console.log(options.json
+                ? JSON.stringify(state, null, 2)
+                : formatHandoffStatus(state));
+            return;
+        }
+        // An agent with no task means "show me my inbox".
+        const task = taskWords.join(" ").trim();
+        if (!task) {
+            const messages = await readInbox(cwd, agent);
+            console.log(options.json
+                ? JSON.stringify(messages, null, 2)
+                : await formatInboxWithBundles(cwd, agent, messages));
+            return;
+        }
+        // Sending is the common case, so it sets itself up rather than failing
+        // with instructions to run two other commands first.
+        const setup = [];
+        if (!(await isHandoffInitialized(cwd))) {
+            await initHandoff(cwd);
+            setup.push("created .handoff/");
+        }
+        for (const target of [options.from, agent]) {
+            if (!isPickupTarget(target))
+                continue;
+            const plan = await planPickup(cwd, target);
+            if (!plan.replacing) {
+                await applyPickup(plan);
+                setup.push(`told ${target} to check its inbox`);
+            }
+        }
+        const bundle = options.bundle
+            ? await createHandoffBundle(cwd, options.bundle)
+            : undefined;
+        let message;
+        try {
+            message = await sendHandoff(cwd, agent, task, {
+                from: options.from,
+                ...(options.context ? { context: options.context } : {}),
+                ...(bundle ? { bundle } : {}),
+                ...(options.verify
+                    ? {
+                        verification: {
+                            criteria: options.verify,
+                            ...(options.verifyCommand
+                                ? {
+                                    command: {
+                                        executable: options.verifyCommand,
+                                        args: verifyArgs,
+                                        timeoutMs: timeoutSeconds * 1_000,
+                                    },
+                                }
+                                : {}),
+                        },
+                    }
+                    : {}),
+            });
+        }
+        catch (error) {
+            if (bundle)
+                await removeHandoffBundle(cwd, bundle);
+            throw error;
+        }
+        if (options.json) {
+            console.log(JSON.stringify({ message, setup }, null, 2));
+            return;
+        }
+        for (const line of setup)
+            console.log(`  ${line}`);
+        console.log(`Sent to ${agent}: ${task}`);
+        if (bundle)
+            console.log(`Bundled ${bundle.fileCount} file(s) at ${bundle.path}${bundle.isTruncated ? " (truncated to safety limits)" : ""}.`);
+        if (options.verify)
+            console.log(options.verifyCommand
+                ? `Verification runs only with: loadout handoff --done ${message.id} --run-verification`
+                : `Completion requires evidence: loadout handoff --done ${message.id} --evidence "what you checked"`);
+        console.log(`It will pick this up next session, or now with: loadout handoff ${agent}`);
+    });
+    // `loadout template` — manage handoff templates
+    const template = program
+        .command("template")
+        .description("Manage reusable handoff task templates");
+    template
+        .command("list")
+        .description("List available templates (built-in and custom)")
+        .option("--json", "machine-readable output")
+        .action(async (opts) => {
+        const templates = await listTemplates(process.cwd());
+        if (opts.json) {
+            console.log(JSON.stringify({
+                custom: templates.custom,
+                builtin: templates.builtin,
+            }, null, 2));
+        }
+        else {
+            console.log(formatTemplateList(templates));
+        }
+    });
+    template
+        .command("show")
+        .description("Show details of a template")
+        .argument("<name>", "template name")
+        .option("--json", "machine-readable output")
+        .action(async (name, opts) => {
+        const tmpl = await loadTemplate(process.cwd(), name);
+        if (!tmpl) {
+            console.error(`No template named '${name}'.`);
+            process.exitCode = 1;
+            return;
+        }
+        if (opts.json) {
+            console.log(JSON.stringify(tmpl, null, 2));
+        }
+        else {
+            console.log(formatTemplateDetail(tmpl));
+        }
+    });
+    template
+        .command("create")
+        .description("Create a custom handoff template")
+        .argument("<name>", "template name (kebab-case)")
+        .requiredOption("--description <text>", "one-line description")
+        .option("--agent <agent>", "default receiver agent")
+        .option("--task <text>", "task template (use {{placeholders}})")
+        .option("--context <text>", "default context")
+        .option("--bundle <paths...>", "default project-relative bundle paths")
+        .option("--verify <criteria>", "default verification criteria")
+        .option("--verify-command <executable>", "verification command")
+        .option("--verify-args <json>", "JSON array of args for verify command")
+        .option("--verify-timeout <seconds>", "verification timeout in seconds")
+        .option("--json", "machine-readable output")
+        .action(async (name, opts) => {
+        const tmpl = {
+            name,
+            description: opts.description,
+            ...(opts.agent ? { defaultAgent: opts.agent } : {}),
+            ...(opts.task ? { taskTemplate: opts.task } : {}),
+            ...(opts.context ? { context: opts.context } : {}),
+            ...(opts.bundle ? { bundleGlobs: opts.bundle } : {}),
+            ...(opts.verify ? { verifyCriteria: opts.verify } : {}),
+        };
+        if (opts.verifyCommand) {
+            let args = [];
+            if (opts.verifyArgs) {
+                const parsed = JSON.parse(opts.verifyArgs);
+                if (!Array.isArray(parsed) ||
+                    parsed.some((v) => typeof v !== "string"))
+                    throw new Error("--verify-args must be a JSON array of strings");
+                args = parsed;
+            }
+            const timeoutMs = opts.verifyTimeout
+                ? Number(opts.verifyTimeout) * 1000
+                : 120_000;
+            tmpl.verifyCommand = {
+                executable: opts.verifyCommand,
+                args,
+                timeoutMs,
+            };
+        }
+        await saveTemplate(process.cwd(), tmpl);
+        if (opts.json) {
+            console.log(JSON.stringify(tmpl, null, 2));
+        }
+        else {
+            console.log(`\x1b[32m✓\x1b[0m Template '${name}' saved.`);
+        }
+    });
+    template
+        .command("delete")
+        .description("Delete a custom template")
+        .argument("<name>", "template name to delete")
+        .action(async (name) => {
+        const deleted = await deleteTemplate(process.cwd(), name);
+        if (deleted) {
+            console.log(`Deleted template '${name}'.`);
+        }
+        else {
+            console.error(`No custom template named '${name}'.`);
+            process.exitCode = 1;
+        }
+    });
+    program
+        .command("completion")
+        .description("Print a shell-completion script; redirect it to your shell profile")
+        .argument("[shell]", "bash, zsh, fish, or powershell")
+        .option("--commands-json", "print registered command paths as JSON for tooling")
+        .action((shell, options) => {
+        if (options.commandsJson) {
+            console.log(JSON.stringify(completionCommandPaths(), null, 2));
+            return;
+        }
+        process.stdout.write(renderShellCompletion(parseCompletionShell(shell ?? "")));
+    });
+}