loadouts 0.2.3 → 0.2.5

package/docs/authoring.md

@@ -1,6 +1,6 @@
 # Authoring Artifacts
 
-This guide covers creating rules, skills, and instructions. The typical workflow:
+This guide covers creating agents, rules, skills, and instructions. The typical workflow:
 
 1. **Create** an artifact (`loadouts rule add`, `loadouts skill add`, etc.)
 2. **Include** it in a loadout (`loadouts add-to <loadout> <artifact>`)
@@ -9,6 +9,71 @@ This guide covers creating rules, skills, and instructions. The typical workflow
 
 ---
 
+## Agents
+
+Agents are self-contained Markdown files under `.loadouts/agents/`. The body is the agent prompt. Top-level frontmatter holds portable fields, while `targets.<tool>` holds harness-specific fields.
+
+```markdown
+---
+name: code-reviewer
+description: Reviews code for correctness, security, and missing tests.
+model: inherit
+readonly: true
+background: false
+
+targets:
+  opencode:
+    mode: subagent
+    steps: 8
+    color: accent
+    permission:
+      bash:
+        "*": ask
+        "git diff*": allow
+
+  cursor:
+    is_background: false
+
+  claude-code:
+    tools: Read, Glob, Grep, Bash
+    maxTurns: 8
+
+  codex:
+    sandbox_mode: read-only
+    model_reasoning_effort: high
+---
+
+Review code like an owner. Prioritize real bugs, behavior regressions,
+security issues, and missing tests.
+```
+
+Project scope renders agents to:
+
+- OpenCode: `.opencode/agents/<name>.md`
+- Cursor: `.cursor/agents/<name>.md`
+- Claude Code: `.claude/agents/<name>.md`
+- Codex: `.codex/agents/<name>.toml`
+
+Markdown targets are symlinked only when the source frontmatter is already native-safe for that harness. If the file contains `targets:` overlays, Loadouts writes a cleaned managed copy for each Markdown harness. Codex always gets generated TOML, with the Markdown body mapped to `developer_instructions`.
+
+After creating an agent manually, add it to a loadout:
+
+```bash
+loadouts add-to backend agents/code-reviewer.md
+```
+
+**Import or migrate existing agents:**
+
+```bash
+loadouts install .opencode/agents/reviewer.md --kinds agent --keep
+loadouts migrate agents --dry-run
+loadouts migrate agents
+```
+
+`install --kinds agent` imports native harness files from outside the target loadout. `migrate agents` converts native files already inside a loadout, such as `opencode/agents/*.md`, `cursor/agents/*.md`, `.claude/agents/*.md`, or `.codex/agents/*.toml`.
+
+---
+
 ## Rules
 
 Rules are scoped advisory files with YAML frontmatter:

package/docs/commands.md

@@ -46,6 +46,18 @@ loadouts info              # Active loadout(s)
 loadouts info backend      # Specific loadout
 ```
 
+### `loadouts runtime [names...]`
+Compile a runtime bundle for inspection (no filesystem activation). Defaults to the root `default` loadout (or `base`).
+```bash
+loadouts runtime                     # Compile default loadout
+loadouts runtime base backend        # Compile multiple loadouts
+loadouts runtime base --tool cursor  # Target a different tool
+loadouts runtime base --json         # Output RuntimeBundle JSON only
+loadouts runtime base --system-block # Output renderRuntimeSystemBlock(bundle) only
+```
+
+See `docs/runtime.md` for architecture, OpenCode-first integration flow, and per-tool capability flags.
+
 ### `loadouts diff [name]`
 Preview what would change if a loadout were applied.
 ```bash
@@ -73,10 +85,26 @@ loadouts install ./rule.mdc        # Import a single rule file
 loadouts install --dry-run         # Preview
 loadouts install -i                # Interactive
 loadouts install --rules           # Rules only
+loadouts install --kinds agent     # Import and canonicalize agents
 loadouts install --from cursor     # From specific tool
 loadouts install --keep            # Don't delete originals
 ```
 
+Native agent files are converted to canonical `.loadouts/agents/*.md` during import. OpenCode, Cursor, Claude Code, and Codex fields are preserved under `targets.<tool>` overlays where needed.
+
+### `loadouts migrate agents [source]`
+Migrate native harness agent definitions that already live in a loadout tree into canonical `.loadouts/agents/*.md` files.
+
+```bash
+loadouts migrate agents                  # Scan legacy agent paths in current loadout
+loadouts migrate agents --dry-run         # Preview migration
+loadouts migrate agents --keep            # Keep old native files
+loadouts migrate agents --force           # Overwrite existing canonical agents
+loadouts migrate agents ./agents --from opencode
+```
+
+When migrating from a harness-specific source path such as `opencode/agents/reviewer.md`, loadout includes are updated to `agents/reviewer.md` with `tools: [opencode]` to preserve existing behavior. The canonical file still receives compatible fields for other harnesses where Loadouts can infer them.
+
 ### `loadouts create <name>`
 Create a new loadout definition.
 ```bash
@@ -196,6 +224,8 @@ Most state commands (`activate`, `deactivate`, `sync`, `status`, `clear`, `list`
 | `-g, --global` | Global scope only |
 | `-a, --all` | Both scopes |
 
+`runtime` supports `-l/--local` and `-g/--global` only (no `--all`).
+
 When omitted, commands auto-detect scope based on context. Use `--dry-run` to preview behavior before destructive operations.
 
 ---

package/docs/compatibility.md

@@ -4,13 +4,13 @@ Current built-in rendering targets for canonical artifacts.
 
 ## Artifact Paths (Project Scope)
 
-| Tool | Rule | Skill | Instruction |
-|------|------|-------|-------------|
-| Claude Code | `.claude/rules/<name>.md` | `.claude/skills/<name>/` | `CLAUDE.md` (generated wrapper to `AGENTS.md`) |
-| Cursor | `.cursor/rules/<name>.mdc` | `.cursor/skills/<name>/` | `AGENTS.md` |
-| OpenCode | `.opencode/rules/<name>.md` | `.opencode/skills/<name>/` | `AGENTS.md` |
-| Codex | - (no rule target) | `.agents/skills/<name>/` | `AGENTS.md` |
-| Pi | - (no native rule target) | `.pi/skills/<name>/` | `AGENTS.md` |
+| Tool | Rule | Skill | Agent | Instruction |
+|------|------|-------|-------|-------------|
+| Claude Code | `.claude/rules/<name>.md` | `.claude/skills/<name>/` | `.claude/agents/<name>.md` | `CLAUDE.md` (generated wrapper to `AGENTS.md`) |
+| Cursor | `.cursor/rules/<name>.mdc` | `.cursor/skills/<name>/` | `.cursor/agents/<name>.md` | `AGENTS.md` |
+| OpenCode | `.opencode/rules/<name>.md` | `.opencode/skills/<name>/` | `.opencode/agents/<name>.md` | `AGENTS.md` |
+| Codex | - (no rule target) | `.agents/skills/<name>/` | `.codex/agents/<name>.toml` | `AGENTS.md` |
+| Pi | - (no native rule target) | `.pi/skills/<name>/` | - | `AGENTS.md` |
 
 Global scope uses each tool's configured global base path. Instruction files may render to home-level `AGENTS.md` or `CLAUDE.md` paths depending on the tool.
 
@@ -18,17 +18,24 @@ Global scope uses each tool's configured global base path. Instruction files may
 
 - Canonical rule fields: `description`, `paths`, `activation` (`always` or `scoped`).
 - Canonical skill fields: `name`, `description`, `user-invocable`, `model-invocable`.
+- Canonical agent files are Markdown under `.loadouts/agents/<name>.md`; use top-level portable fields plus `targets.<tool>` overlays for harness-specific config.
 
 Rendered aliases for compatibility:
 
 - Cursor/OpenCode rules: `paths` is mirrored to `globs`.
 - Cursor/OpenCode rules: `activation` is mirrored to `alwaysApply` (`always -> true`, `scoped -> false`).
 - OpenCode skills: `model-invocable` is mirrored to `disable-model-invocation` (inverted boolean).
+- Agent overlays are rendered into each harness' native frontmatter. Codex agents are generated as TOML with the Markdown body mapped to `developer_instructions`.
 
 Transforms add aliases when canonical fields are present and alias fields are not already set.
 
+Agent Markdown targets use symlinks only when the source frontmatter is already native-safe for that harness. Files with `targets:` overlays are rendered as managed copies so tool-specific fields do not leak into other harnesses.
+
+Agent import and migration canonicalize native harness definitions. Compatible fields are inferred when possible: read-only native settings become canonical `readonly: true`, Cursor/Claude background settings become canonical `background`, OpenCode/Codex/Claude reasoning effort settings are mirrored across compatible target overlays, and OpenCode `steps` / Claude `maxTurns` are mirrored between those harnesses.
+
 ## Known Limitations
 
 - Codex and Pi do not currently have a built-in rule output target.
-- Frontmatter aliasing is only applied on transformed targets (currently Cursor/OpenCode rules and OpenCode skills).
+- Pi does not currently have a built-in agent output target.
+- Frontmatter aliasing is only applied on transformed targets.
 - If both canonical and alias fields are set by hand, existing alias values are preserved.

package/docs/concepts.md

@@ -74,6 +74,7 @@ include:
 |------|--------|-------------|
 | `rule` | file | Scoped advisory rules (`.md`) |
 | `skill` | directory | On-demand capabilities with `SKILL.md` |
+| `agent` | file | Specialized agents and subagents |
 | `instruction` | file | Always-on project instructions |
 | `prompt` | file | Slash command templates |
 | `extension` | directory | Runtime code extensions |
@@ -83,13 +84,13 @@ include:
 
 ## Supported Tools
 
-| Tool | Rules | Skills | Instructions | Extra Artifacts |
-|------|-------|--------|--------------|-----------------|
-| Claude Code | `.claude/rules/*.md` | `.claude/skills/` | `CLAUDE.md` | — |
-| Cursor | `.cursor/rules/*.mdc` | `.cursor/skills/` | `AGENTS.md` | — |
-| OpenCode | `.opencode/rules/*.md` | `.opencode/skills/` | `AGENTS.md` | `opencode.json(c)`, `.opencode/plugins/` |
-| Codex | — | `.agents/skills/` | `AGENTS.md` | — |
-| Pi | `.pi/rules/*.md` | `.pi/skills/` | `AGENTS.md` | `.pi/extensions/`, `.pi/themes/` |
+| Tool | Rules | Skills | Agents | Instructions | Extra Artifacts |
+|------|-------|--------|--------|--------------|-----------------|
+| Claude Code | `.claude/rules/*.md` | `.claude/skills/` | `.claude/agents/*.md` | `CLAUDE.md` | — |
+| Cursor | `.cursor/rules/*.mdc` | `.cursor/skills/` | `.cursor/agents/*.md` | `AGENTS.md` | — |
+| OpenCode | `.opencode/rules/*.md` | `.opencode/skills/` | `.opencode/agents/*.md` | `AGENTS.md` | `opencode.json(c)`, `.opencode/plugins/` |
+| Codex | — | `.agents/skills/` | `.codex/agents/*.toml` | `AGENTS.md` | — |
+| Pi | `.pi/rules/*.md` | `.pi/skills/` | — | `AGENTS.md` | `.pi/extensions/`, `.pi/themes/` |
 
 ## Sources (Cross-Project Config)
 

package/docs/examples/opencode-runtime-plugin.ts

@@ -0,0 +1,143 @@
+/**
+ * OpenCode runtime integration scaffold (reference implementation).
+ *
+ * This is intentionally conservative and uses the current CLI JSON bridge:
+ *   loadouts runtime <names...> --tool opencode --json
+ *
+ * Notes:
+ * - API shapes below are placeholders where OpenCode plugin APIs are uncertain.
+ * - This scaffold does not claim native skill hot-swap.
+ * - Skills are exposed as path-discovery references only.
+ */
+
+import { spawn } from "node:child_process";
+
+interface RuntimeBundle {
+  tool: string;
+  fingerprint: string;
+  injection: {
+    instructions: Array<{ relativePath: string; content: string }>;
+    rules: Array<{ relativePath: string; content: string }>;
+    skills: Array<{ name: string; path: string; sourcePath: string }>;
+  };
+  capabilities: {
+    runtimeMode: "native-runtime" | "experimental-runtime" | "filesystem-activation";
+    modelInjection: { instructions: boolean; rules: boolean };
+    skillPathDiscovery: boolean;
+    nativeSkillHotSwap: boolean;
+  };
+}
+
+type SessionRuntimeState = {
+  fingerprint?: string;
+  bundle?: RuntimeBundle;
+};
+
+// Placeholder/uncertain plugin API. Replace with actual OpenCode interfaces.
+interface OpenCodePluginApi {
+  // Possible session lifecycle hook (name/signature may differ).
+  onSessionStart?: (handler: (ctx: { cwd: string; state: SessionRuntimeState }) => Promise<void>) => void;
+  // Possible system prompt composition hook (name/signature may differ).
+  onSystemPrompt?: (handler: (ctx: { state: SessionRuntimeState }) => string | Promise<string>) => void;
+  // Possible skill discovery registration hook (name/signature may differ).
+  registerSkillDiscoveryPath?: (path: string) => void;
+}
+
+export function registerLoadoutsRuntimeScaffold(api: OpenCodePluginApi): void {
+  if (!api.onSessionStart || !api.onSystemPrompt) {
+    return;
+  }
+
+  api.onSessionStart(async ({ cwd, state }) => {
+    const names = ["base"]; // Replace with user/session-selected runtime loadouts.
+    const bundle = await compileRuntimeBundleViaCli(names, cwd);
+
+    state.bundle = bundle;
+    state.fingerprint = bundle.fingerprint;
+
+    if (bundle.capabilities.skillPathDiscovery && api.registerSkillDiscoveryPath) {
+      for (const skill of bundle.injection.skills) {
+        api.registerSkillDiscoveryPath(skill.path);
+      }
+    }
+  });
+
+  api.onSystemPrompt(({ state }) => {
+    const bundle = state.bundle;
+    if (!bundle) return "";
+
+    // Either render your own system block from bundle fields,
+    // or call `loadouts runtime ... --system-block` in environments that prefer text passthrough.
+    return renderRuntimeSystemBlockText(bundle);
+  });
+}
+
+async function compileRuntimeBundleViaCli(names: string[], cwd: string): Promise<RuntimeBundle> {
+  const args = ["runtime", ...names, "--tool", "opencode", "--json", "--local"];
+  const { stdout } = await execFile("loadouts", args, cwd);
+  return JSON.parse(stdout) as RuntimeBundle;
+}
+
+function renderRuntimeSystemBlockText(bundle: RuntimeBundle): string {
+  const lines: string[] = [];
+  lines.push("[loadout-runtime:v1]");
+  lines.push(`tool: ${bundle.tool}`);
+  lines.push(`fingerprint: ${bundle.fingerprint}`);
+  lines.push("");
+  lines.push("## Instructions (Model Injected)");
+
+  if (bundle.injection.instructions.length === 0) {
+    lines.push("(none)");
+  } else {
+    for (const item of bundle.injection.instructions) {
+      lines.push(`### ${item.relativePath}`);
+      lines.push(item.content);
+      lines.push("");
+    }
+  }
+
+  lines.push("## Rules (Model Injected)");
+  if (bundle.injection.rules.length === 0) {
+    lines.push("(none)");
+  } else {
+    for (const item of bundle.injection.rules) {
+      lines.push(`### ${item.relativePath}`);
+      lines.push(item.content);
+      lines.push("");
+    }
+  }
+
+  lines.push("## Skills (Path Discovery Only)");
+  lines.push("Native skill hot-swap is not available in runtime v1.");
+  for (const skill of bundle.injection.skills) {
+    lines.push(`- ${skill.name}`);
+    lines.push(`  path: ${skill.path}`);
+  }
+
+  return lines.join("\n").trimEnd() + "\n";
+}
+
+function execFile(command: string, args: string[], cwd: string): Promise<{ stdout: string; stderr: string }> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+
+    let stdout = "";
+    let stderr = "";
+
+    child.stdout.on("data", (chunk) => {
+      stdout += String(chunk);
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += String(chunk);
+    });
+
+    child.on("error", reject);
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve({ stdout, stderr });
+        return;
+      }
+      reject(new Error(`loadouts runtime failed (${code}): ${stderr || stdout}`));
+    });
+  });
+}

package/docs/index.md

@@ -53,6 +53,7 @@ loadouts check                     # Validate configuration
 loadouts docs quickstart       # Get started in 60 seconds
 loadouts docs concepts         # Loadouts, artifacts, scopes, tools
 loadouts docs commands         # Full command reference
+loadouts docs runtime          # Runtime activation architecture and capabilities
 loadouts docs authoring        # Creating rules, skills, instructions
 loadouts docs compatibility    # Tool paths, frontmatter aliases, limits
 loadouts docs workflows        # Team setup, git, CI/CD

package/docs/runtime.md

@@ -0,0 +1,72 @@
+# Runtime Activation (OpenCode First)
+
+`loadouts runtime` compiles loadouts into a session-time bundle without touching activated outputs on disk. Runtime v1 is designed as an OpenCode-first integration path and a reference surface for other tools.
+
+## Why Runtime Exists
+
+- Keep activation side-effect free for agent sessions.
+- Reuse the existing resolver and include semantics from standard loadout compilation.
+- Make instruction/rule injection explicit and auditable in one JSON payload.
+- Expose skill directories as references (path discovery only), without claiming native skill hot-swap.
+
+## Architecture
+
+Runtime activation follows a resolver-backed bundle compiler:
+
+1. Resolve loadouts exactly like normal activation (`include`, source imports, bundled/global fallback, tool filtering).
+2. Compile supported artifacts into a `RuntimeBundle`.
+3. Return bundle JSON (`--json`) or a model-ready block (`--system-block`).
+
+Key properties:
+
+- Session-local state: caller owns lifecycle in memory/process state.
+- No persistent activation changes: runtime commands do not mutate `.loadouts/.state.json`.
+- No output rendering: runtime does not write `.opencode/`, `AGENTS.md`, or other tool target files.
+- Deterministic fingerprinting: `fingerprint` is stable across `generatedAt` changes for equivalent content.
+
+## OpenCode-First Flow
+
+Use OpenCode as the primary runtime consumer in v1:
+
+```bash
+# JSON bridge for plugin/session adapters
+loadouts runtime base backend --tool opencode --json
+
+# Pre-rendered system block text
+loadouts runtime base backend --tool opencode --system-block
+```
+
+Recommended integration pattern:
+
+- Compile once when a session starts or active runtime loadouts change.
+- Cache by `fingerprint`.
+- Inject `instructions` and `rules` into model/system context.
+- Register `skills[*].path` for discovery only.
+
+## Tool Capability Matrix (Runtime v1)
+
+The bundle always includes resolved instructions, rules, and skill references. Capability flags tell consumers what should be treated as native runtime behavior for each tool.
+
+| Tool | Runtime mode | Instruction/rule model injection | Skill path discovery | Native skill hot-swap |
+|------|--------------|----------------------------------|----------------------|-----------------------|
+| OpenCode | `experimental-runtime` | Yes | Yes | No |
+| Pi | `native-runtime` | Yes | Yes | No |
+| Codex | `experimental-runtime` | Yes | Yes | No |
+| Claude Code | `filesystem-activation` | No | No | No |
+| Cursor | `filesystem-activation` | No (not native) | No | No |
+
+For filesystem-first tools, use standard `activate/sync` as the primary path and treat runtime output as inspection/debugging data.
+
+## Runtime v1 Limits
+
+- Supported kinds: `instruction`, `rule`, `skill`.
+- Agents are filesystem-rendered native definitions for supported harnesses; they are not injected through runtime v1.
+- Unsupported kinds are reported as diagnostics, not hard failures.
+- Skills require a `SKILL.md` entrypoint for runtime discovery metadata.
+- Runtime v1 does not implement native skill hot-swap.
+
+## Reference Scaffold
+
+- Example OpenCode plugin scaffold: `docs/examples/opencode-runtime-plugin.ts`
+- Core compiler implementation: `src/core/runtime.ts`
+- CLI command surface: `src/cli/commands/runtime.ts`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loadouts",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Composable configuration bundles for AI coding agents",
   "type": "module",
   "bin": {