@agentplate/cli 1.0.0

package/src/skills/types.ts

@@ -0,0 +1,107 @@
+/**
+ * Self-improving skills — domain types.
+ *
+ * A **Skill** is a reusable, versioned, executable playbook distilled from a
+ * successful task: a goal, when-to-use signals, ordered steps (prose + concrete
+ * command snippets), file-pattern hints, gotchas, and an earned confidence track
+ * record. Skills are the unit of Agentplate's closed learning loop:
+ *
+ *   retrieve (at spawn) → apply (agent uses them) → distill (at session-end,
+ *   gated on quality gates) → feedback (append outcome, evolve confidence).
+ *
+ * On disk each skill is a directory `.agentplate/skills/<slug>/` containing
+ * `skill.md` (YAML frontmatter + markdown body — the source of truth) and
+ * `outcomes.jsonl` (append-only outcome log). A derived, gitignored SQLite FTS
+ * index (`skills.db`) accelerates retrieval and is rebuildable from the files.
+ */
+
+import type { OutcomeStatus } from "../types.ts";
+
+/** Lifecycle status. `quarantined`/`deprecated` skills are excluded from retrieval. */
+export type SkillStatus = "active" | "deprecated" | "quarantined";
+
+/** Provenance of a distilled skill. */
+export interface SkillProvenance {
+	taskId: string | null;
+	agent: string;
+	commit: string | null;
+}
+
+/** A reusable, versioned playbook. */
+export interface Skill {
+	/** Stable content-independent id. */
+	id: string;
+	/** URL/dir-safe identifier (the directory name). */
+	slug: string;
+	title: string;
+	/** Bumped on every UPDATE distillation. */
+	version: number;
+	status: SkillStatus;
+	/** One-line statement of what applying this skill accomplishes. */
+	goal: string;
+	/** Preconditions / retrieval signals ("when should an agent use this?"). */
+	whenToUse: string[];
+	/** Glob patterns of files this skill is relevant to (file-overlap ranking). */
+	filePatterns: string[];
+	tags: string[];
+	created: string;
+	updatedAt: string;
+	distilledFrom?: SkillProvenance;
+	/** Slugs of related skills. */
+	relatesTo: string[];
+	/** Slugs this skill structurally replaces. */
+	supersedes: string[];
+	/** Markdown body after the frontmatter (steps / gotchas / verification). */
+	body: string;
+
+	// --- derived (computed from outcomes.jsonl; never hand-edited) ---
+	/** 0..1 confidence (Wilson lower bound over weighted outcomes). */
+	confidence: number;
+	appliedCount: number;
+	successCount: number;
+	lastOutcome: OutcomeStatus | null;
+}
+
+/** One appended line in a skill's `outcomes.jsonl`. */
+export interface SkillOutcome {
+	status: OutcomeStatus;
+	agent: string;
+	taskId: string | null;
+	/** Quality-gate status that produced this outcome (null if gates not run). */
+	gates: OutcomeStatus | null;
+	ts: string;
+	note?: string;
+}
+
+/**
+ * Output of the AI distiller, pre-validation. `skip` is first-class — most
+ * sessions should NOT mint a skill, preventing skill spam.
+ */
+export interface SkillDraft {
+	action: "create" | "update" | "skip";
+	/** Required when action is "update": the slug to update. */
+	targetSlug?: string;
+	title?: string;
+	goal?: string;
+	whenToUse?: string[];
+	filePatterns?: string[];
+	tags?: string[];
+	body?: string;
+}
+
+/** A skill plus its relevance score (retrieval output). */
+export interface RankedSkill {
+	skill: Skill;
+	score: number;
+}
+
+/**
+ * Written to `.agentplate/agents/<name>/applied-skills.json` at spawn so the
+ * session-end feedback step knows which skills to score.
+ */
+export interface AppliedSkillsRecord {
+	taskId: string;
+	agent: string;
+	capability: string;
+	skills: Array<{ id: string; slug: string; injected: "full" | "summary" }>;
+}

package/src/types.ts

@@ -0,0 +1,442 @@
+/**
+ * Shared types and interfaces for Agentplate.
+ *
+ * ALL cross-module types live here so there is a single import site and no
+ * circular dependencies between feature modules. Feature-local types that are
+ * never shared may live in their own module, but anything referenced by more
+ * than one subsystem belongs here.
+ */
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+/** Top-level Agentplate project configuration (`.agentplate/config.yaml`). */
+export interface AgentplateConfig {
+	project: ProjectConfig;
+	runtime: RuntimeConfig;
+	/** Id of the active provider (a key into {@link AgentplateConfig.providers}). */
+	activeProvider: string;
+	providers: Record<string, ProviderConfig>;
+	agents: AgentsConfig;
+	merge: MergeConfig;
+	skills: SkillsConfig;
+	deploy: DeployConfig;
+	logging: LoggingConfig;
+}
+
+/** Build → CI/CD → Deploy configuration. */
+export interface DeployConfig {
+	/** Default deploy target id (e.g. "docker-gha"); empty until configured. */
+	default: string;
+	/** Per-target non-secret settings + secret env-var bindings. */
+	targets: Record<string, DeployTargetConfig>;
+	/** Per-environment gate policy: "confirm" requires approval, "auto" does not. */
+	gates: Record<string, "confirm" | "auto">;
+}
+
+/** Non-secret settings + secret bindings for one deploy target. */
+export interface DeployTargetConfig {
+	/** Arbitrary non-secret settings (region, registry, cluster, app name…). */
+	settings: Record<string, string | number | boolean>;
+	/** Secret bindings: logical key → { fromEnv: ENV_VAR_NAME } (no values). */
+	secretEnv: Record<string, { fromEnv: string }>;
+	/** Environments this target deploys to. */
+	environments: string[];
+}
+
+/** Self-improving skills behavior. */
+export interface SkillsConfig {
+	/** Master switch for retrieval + distillation. */
+	enabled: boolean;
+	/** Retrieval budget + count caps. */
+	retrieval: {
+		/** Max characters of skills injected into an overlay. */
+		budgetChars: number;
+		/** Max number of full-body skills injected (rest become summaries). */
+		maxFull: number;
+	};
+	/** Distillation behavior. */
+	distill: {
+		/** Only distill when quality gates pass (recommended). */
+		onlyOnGatesPass: boolean;
+		/** Model override for the distiller (null = runtime default). */
+		model: string | null;
+	};
+	/** Auto-pruning thresholds. */
+	prune: {
+		/** Quarantine when confidence drops below this (with >= minSamples). */
+		quarantineBelow: number;
+		minSamples: number;
+		/** Delete quarantined skills older than this many days. */
+		maxAgeDays: number;
+	};
+}
+
+/** Identity and git context for the project being orchestrated. */
+export interface ProjectConfig {
+	/** Human-readable project name (auto-detected at init). */
+	name: string;
+	/** Absolute path to the project root. */
+	root: string;
+	/** Branch agent work is ultimately merged into (e.g. "main"). */
+	canonicalBranch: string;
+	/** Commands run at session-end to score an agent's work (test/lint/typecheck). */
+	qualityGates?: QualityGate[];
+}
+
+/** A single quality gate: a named command whose exit code determines pass/fail. */
+export interface QualityGate {
+	name: string;
+	command: string;
+	description?: string;
+}
+
+/** Which coding-agent runtime drives workers, and per-capability overrides. */
+export interface RuntimeConfig {
+	/** Default runtime adapter id (e.g. "claude"). */
+	default: string;
+	/** Optional per-capability runtime overrides. */
+	capabilities?: Partial<Record<Capability, string>>;
+}
+
+/**
+ * How a provider's credentials are obtained:
+ *  - `subscription`  — the runtime CLI's own login (e.g. Claude Pro/Max OAuth,
+ *    `codex login`, `gcloud`/`gemini` auth). Agentplate stores NO key; auth is
+ *    delegated to the already-logged-in CLI.
+ *  - `api-key`       — a key Agentplate stores in the gitignored secrets file.
+ *  - `env`           — a key Agentplate reads from an existing environment
+ *    variable at run time (never stored).
+ *  - `none`          — local/keyless provider (e.g. Ollama).
+ */
+export type AuthMode = "subscription" | "api-key" | "env" | "none";
+
+/**
+ * An AI provider (LLM backend). `native` providers are reached through the
+ * runtime's own auth; `gateway` providers route through a base URL with a
+ * bearer token read from the named environment variable.
+ */
+export interface ProviderConfig {
+	type: "native" | "gateway";
+	/** How credentials are obtained for this provider. */
+	authMode?: AuthMode;
+	/** Base URL for gateway providers. */
+	baseUrl?: string;
+	/** Name of the env var holding the auth token (value never stored in config). */
+	authTokenEnv?: string;
+	/** Default model id for this provider. */
+	model?: string;
+}
+
+/** Orchestration limits and agent registry locations. */
+export interface AgentsConfig {
+	/** Path to the agent manifest, relative to project root. */
+	manifestPath: string;
+	/** Directory holding deployed base agent definitions, relative to root. */
+	baseDir: string;
+	/** Maximum agents running concurrently across the whole fleet. */
+	maxConcurrent: number;
+	/** Maximum delegation depth (coordinator → lead → worker = 2). */
+	maxDepth: number;
+	/** Maximum children a single lead may spawn. */
+	maxAgentsPerLead: number;
+	/**
+	 * Terminate a worker after this many minutes with no activity (no streamed
+	 * events and not between-turn progress) — the session is marked `stopped`, its
+	 * process killed, and its worktree removed. The coordinator is never reaped.
+	 * `0` disables idle reaping. Default 10.
+	 */
+	idleTimeoutMinutes: number;
+}
+
+/** Conflict-resolution behavior for merging agent branches. */
+export interface MergeConfig {
+	/** Allow AI-assisted resolution of semantic conflicts. */
+	aiResolveEnabled: boolean;
+}
+
+/** Logging behavior. */
+export interface LoggingConfig {
+	/** Emit verbose diagnostic output. */
+	verbose: boolean;
+	/** Redact secrets from logs and captured output. */
+	redactSecrets: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Agents & capabilities
+// ---------------------------------------------------------------------------
+
+/**
+ * The role an agent plays. The orchestration core (Phase 2) uses the first
+ * group; the delivery pipeline (Phase 4) adds `architect`/`devops`/`deployer`/
+ * `verifier`. Declared here up front so config typing is stable across phases.
+ */
+export type Capability =
+	| "scout"
+	| "builder"
+	| "reviewer"
+	| "lead"
+	| "merger"
+	| "coordinator"
+	| "architect"
+	| "devops"
+	| "deployer"
+	| "verifier";
+
+/** Every supported capability, in canonical order. */
+export const SUPPORTED_CAPABILITIES: readonly Capability[] = [
+	"scout",
+	"builder",
+	"reviewer",
+	"lead",
+	"merger",
+	"coordinator",
+	"architect",
+	"devops",
+	"deployer",
+	"verifier",
+];
+
+// ---------------------------------------------------------------------------
+// Outcomes (shared by quality gates, skills, and identity)
+// ---------------------------------------------------------------------------
+
+/** Result classification for a unit of work, threaded from quality gates. */
+export type OutcomeStatus = "success" | "partial" | "failure";
+
+// ---------------------------------------------------------------------------
+// Model resolution (runtime ↔ provider bridge)
+// ---------------------------------------------------------------------------
+
+/** A concrete model id plus the env vars needed to reach it (API keys, base URLs). */
+export interface ResolvedModel {
+	/** Concrete model id passed to the runtime CLI. */
+	model: string;
+	/** Provider env vars to inject into the spawned process. */
+	env?: Record<string, string>;
+}
+
+// ---------------------------------------------------------------------------
+// Runs & sessions
+// ---------------------------------------------------------------------------
+
+/** Lifecycle state of an agent session. */
+export type SessionState = "booting" | "working" | "idle" | "completed" | "failed" | "stopped";
+
+/** A run groups all agent sessions started by one coordinator session. */
+export interface RunRecord {
+	/** Run id, e.g. "run-20260531-140000". */
+	id: string;
+	createdAt: string;
+	status: "active" | "completed";
+	label?: string;
+}
+
+/** A single spawned agent worker (one row per agent in the sessions store). */
+export interface AgentSession {
+	/** Unique session id. */
+	id: string;
+	agentName: string;
+	capability: Capability;
+	taskId: string;
+	runId: string;
+	worktreePath: string;
+	branchName: string;
+	state: SessionState;
+	/** Parent agent name (null for top-level spawns). */
+	parentAgent: string | null;
+	/** Delegation depth (coordinator = 0). */
+	depth: number;
+	/** OS process id of the most recent turn, if known. */
+	pid: number | null;
+	/** Runtime session id used for `--resume` across turns. */
+	runtimeSessionId: string | null;
+	startedAt: string;
+	lastActivity: string;
+}
+
+// ---------------------------------------------------------------------------
+// Mail
+// ---------------------------------------------------------------------------
+
+/** Protocol + semantic message types carried on the mail bus. */
+export type MailType =
+	| "dispatch"
+	| "worker_done"
+	| "worker_died"
+	| "merge_ready"
+	| "merged"
+	| "merge_failed"
+	| "escalation"
+	| "health_check"
+	| "assign"
+	| "status"
+	| "question"
+	| "result"
+	| "error"
+	// Delivery-pipeline protocol messages (Phase 4).
+	| "pipeline_ready"
+	| "deploy_gate"
+	| "deploy_done"
+	| "deploy_failed"
+	| "verify_done"
+	| "verify_failed";
+
+export type MailPriority = "low" | "normal" | "high" | "urgent";
+
+/** A message on the SQLite mail bus. */
+export interface MailMessage {
+	id: string;
+	from: string;
+	to: string;
+	subject: string;
+	body: string;
+	type: MailType;
+	priority: MailPriority;
+	/** Thread id for grouping replies (null starts a new thread). */
+	threadId: string | null;
+	/** Structured JSON payload for protocol messages (null otherwise). */
+	payload: string | null;
+	read: boolean;
+	createdAt: string;
+}
+
+/** Fields accepted when sending a message (id/createdAt/read are assigned by the store). */
+export interface NewMail {
+	from: string;
+	to: string;
+	subject: string;
+	body: string;
+	type: MailType;
+	priority?: MailPriority;
+	threadId?: string | null;
+	payload?: string | null;
+}
+
+// ---------------------------------------------------------------------------
+// Events (observability)
+// ---------------------------------------------------------------------------
+
+/** A recorded agent event (tool call, lifecycle transition, error). */
+export interface EventRecord {
+	id: string;
+	agentName: string;
+	runId: string | null;
+	/** e.g. "tool-start" | "tool-end" | "session-end" | "error". */
+	type: string;
+	/** Tool name for tool events (null otherwise). */
+	tool: string | null;
+	/** JSON-encoded detail (null otherwise). */
+	detail: string | null;
+	createdAt: string;
+}
+
+// ---------------------------------------------------------------------------
+// Agent manifest
+// ---------------------------------------------------------------------------
+
+/** Static definition of one capability: which base .md, model, tools, constraints. */
+export interface AgentDefinition {
+	/** Base definition filename under the agent base dir (e.g. "builder.md"). */
+	file: string;
+	/** Model alias ("opus"/"sonnet"/"haiku") or a concrete model id. */
+	model: string;
+	/** Tools the agent is permitted to use. */
+	tools: string[];
+	/** Capabilities this definition provides. */
+	capabilities: Capability[];
+	/** May this agent spawn children? */
+	canSpawn: boolean;
+	/** Hard constraints injected into the overlay. */
+	constraints: string[];
+}
+
+/** The agent registry, loaded from `.agentplate/agent-manifest.json`. */
+export interface AgentManifest {
+	version: string;
+	agents: Partial<Record<Capability, AgentDefinition>>;
+	/** Maps each capability to the definitions that provide it. */
+	capabilityIndex: Partial<Record<Capability, Capability[]>>;
+}
+
+// ---------------------------------------------------------------------------
+// Overlay (per-spawn instruction assembly)
+// ---------------------------------------------------------------------------
+
+/** Inputs to the dynamic overlay generator (the per-task instruction file). */
+export interface OverlayConfig {
+	agentName: string;
+	capability: Capability;
+	taskId: string;
+	specPath?: string;
+	branchName: string;
+	worktreePath: string;
+	parentAgent: string | null;
+	depth: number;
+	/** Exclusive file scope the agent owns (empty = no restriction). */
+	fileScope: string[];
+	/** Contents of the base .md definition (the HOW). */
+	baseDefinition: string;
+	canSpawn: boolean;
+	qualityGates: QualityGate[];
+	constraints: string[];
+	/** Parallel sibling agent names (for rebase-before-merge guidance). */
+	siblings?: string[];
+	/** Reserved for Phase 3: retrieved skills block. */
+	skillsOverlay?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Merge
+// ---------------------------------------------------------------------------
+
+/** Conflict-resolution tier applied (or predicted) for a merge. */
+export type MergeTier = "clean-merge" | "auto-resolve" | "ai-resolve" | "reimagine";
+
+export type MergeStatus = "pending" | "merged" | "failed";
+
+/** A queued merge of an agent branch into a target branch. */
+export interface MergeEntry {
+	id: string;
+	branchName: string;
+	agentName: string;
+	taskId: string;
+	targetBranch: string;
+	status: MergeStatus;
+	createdAt: string;
+}
+
+/** Outcome of attempting (or predicting) a merge. */
+export interface MergeResult {
+	branchName: string;
+	status: MergeStatus;
+	/** The tier that resolved (or would resolve) the merge. */
+	tier: MergeTier | null;
+	conflictFiles: string[];
+	message: string;
+}
+
+// ---------------------------------------------------------------------------
+// Deploy audit
+// ---------------------------------------------------------------------------
+
+/** One append-only row in the deploy audit log (`deploys.db`). No secrets, ever. */
+export interface DeployAuditRow {
+	id: string;
+	runId: string | null;
+	agentName: string;
+	target: string;
+	environment: string;
+	action: "deploy" | "rollback";
+	dryRun: boolean;
+	gateDecision: "auto" | "approved" | "denied" | "n/a";
+	approvedBy: string | null;
+	status: "success" | "failed";
+	deploymentId: string | null;
+	urls: string[];
+	outputs: Record<string, string>;
+	commitSha: string;
+	createdAt: string;
+}

package/src/utils/detect.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, test } from "bun:test";
+import { commandOnPath, resolveArgv } from "./detect.ts";
+
+describe("commandOnPath", () => {
+	test("finds a binary that is on PATH (cross-platform via Bun.which)", async () => {
+		// `node` ships with the Bun/CI toolchain on every OS we run on.
+		expect(await commandOnPath("node")).toBe(true);
+	});
+
+	test("returns false for a definitely-absent command", async () => {
+		expect(await commandOnPath("definitely-not-a-real-cli-xyz")).toBe(false);
+	});
+});
+
+describe("resolveArgv", () => {
+	test("returns the argv unchanged on POSIX (the proven path)", () => {
+		// On macOS/Linux (where this suite runs) the argv is passed through verbatim.
+		if (process.platform !== "win32") {
+			const argv = ["gemini", "--model", "x", "--prompt", "hi"];
+			expect(resolveArgv(argv)).toEqual(argv);
+		}
+	});
+
+	test("handles an empty argv without throwing", () => {
+		expect(resolveArgv([])).toEqual([]);
+	});
+
+	test("on Windows, resolves argv[0] to a real path and keeps the rest", () => {
+		// The win32 branch can only run on Windows; here we just assert the contract
+		// holds for the args tail regardless of OS (argv[0] is resolved or left as-is).
+		const out = resolveArgv(["gemini", "--prompt", "hi"]);
+		expect(out.slice(1)).toEqual(["--prompt", "hi"]);
+		expect(out.length).toBe(3);
+	});
+});

package/src/utils/detect.ts

@@ -0,0 +1,82 @@
+/**
+ * Environment detection helpers used by `init`/`setup`.
+ *
+ * All detection is best-effort and side-effect-free: failures fall back to
+ * sensible defaults rather than throwing, so initialization never blocks on a
+ * missing remote or an absent CLI.
+ */
+
+import { basename } from "node:path";
+
+/** Runtime adapter ids Agentplate knows how to detect by their CLI name. */
+const RUNTIME_CLIS: ReadonlyArray<{ runtime: string; cli: string }> = [
+	{ runtime: "claude", cli: "claude" },
+	{ runtime: "opencode", cli: "opencode" },
+	{ runtime: "codex", cli: "codex" },
+	{ runtime: "gemini", cli: "gemini" },
+	{ runtime: "cursor", cli: "cursor-agent" },
+];
+
+async function runGit(root: string, args: string[]): Promise<string | null> {
+	try {
+		const proc = Bun.spawn(["git", ...args], { cwd: root, stdout: "pipe", stderr: "pipe" });
+		const code = await proc.exited;
+		if (code !== 0) return null;
+		return (await new Response(proc.stdout).text()).trim();
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * True if `cli` is resolvable on PATH. Uses `Bun.which`, which is cross-platform
+ * and honors Windows `PATHEXT` (so `.cmd`/`.exe` shims are found). The previous
+ * `which` subprocess was Unix-only, so on Windows every CLI looked "not installed"
+ * — the wizard hid them and `detectDefaultRuntime` always fell back to claude.
+ */
+export async function commandOnPath(cli: string): Promise<boolean> {
+	return Bun.which(cli) !== null;
+}
+
+/**
+ * Resolve an argv so its executable can be launched on every OS. On Windows,
+ * npm-installed CLIs (gemini, codex, opencode, cursor-agent) are `.cmd`/`.ps1`
+ * shims that `Bun.spawn` will NOT launch by bare name (it looks for an exact
+ * `name`/`name.exe`), causing ENOENT; `Bun.which` resolves the real shim path via
+ * `PATHEXT`. On POSIX the argv is returned unchanged so the proven path is kept.
+ */
+export function resolveArgv(argv: string[]): string[] {
+	if (process.platform !== "win32" || argv.length === 0) return argv;
+	const resolved = Bun.which(argv[0] as string);
+	return resolved ? [resolved, ...argv.slice(1)] : argv;
+}
+
+/** Detect the project name from the git remote URL, falling back to the dir name. */
+export async function detectProjectName(root: string): Promise<string> {
+	const remote = await runGit(root, ["config", "--get", "remote.origin.url"]);
+	if (remote) {
+		const match = remote.match(/([^/:]+?)(?:\.git)?$/);
+		if (match?.[1]) return match[1];
+	}
+	return basename(root);
+}
+
+/** Detect the canonical branch (origin HEAD, else current branch, else "main"). */
+export async function detectCanonicalBranch(root: string): Promise<string> {
+	const originHead = await runGit(root, ["symbolic-ref", "refs/remotes/origin/HEAD"]);
+	if (originHead) {
+		const name = originHead.split("/").pop();
+		if (name) return name;
+	}
+	const current = await runGit(root, ["branch", "--show-current"]);
+	if (current) return current;
+	return "main";
+}
+
+/** Detect the first installed coding-agent runtime, defaulting to "claude". */
+export async function detectDefaultRuntime(): Promise<string> {
+	for (const { runtime, cli } of RUNTIME_CLIS) {
+		if (await commandOnPath(cli)) return runtime;
+	}
+	return "claude";
+}

package/src/version.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, test } from "bun:test";
+import { join } from "node:path";
+import { VERSION } from "./version.ts";
+
+// The CLI version is intentionally a plain constant (so it survives bundling and
+// needs no filesystem access at runtime), but that makes it easy to bump
+// package.json and forget version.ts — which silently ships a wrong --version.
+// This guard reads the REAL package.json and fails the gates on any drift.
+describe("VERSION", () => {
+	test("matches the version in package.json", async () => {
+		const pkgPath = join(import.meta.dir, "..", "package.json");
+		const pkg = (await Bun.file(pkgPath).json()) as { version: string };
+		expect(VERSION).toBe(pkg.version);
+	});
+
+	test("is a valid semver string", () => {
+		expect(VERSION).toMatch(/^\d+\.\d+\.\d+(?:-[\w.]+)?$/);
+	});
+});

package/src/version.ts

@@ -0,0 +1,7 @@
+/**
+ * Single source of truth for the Agentplate CLI version.
+ *
+ * Kept as a plain constant (not read from package.json at runtime) so the value
+ * is available without filesystem access and survives bundling.
+ */
+export const VERSION = "1.0.0";