maqcli 0.2.0

package/dist/core/pipeline.js

@@ -0,0 +1,223 @@
+/**
+ * Pipeline orchestrator: Scout -> Plan -> Execute -> Verify.
+ *
+ * The cost/quality dial lives here: trivial tasks skip Scout+Plan and go
+ * straight to a minimal Execute; standard/complex tasks run the full pipeline.
+ * Every phase transition emits a normalized event so a UI can render progress
+ * uniformly regardless of which worker CLI runs underneath.
+ */
+import { makeEvent } from "./types.js";
+import { shouldRunPreflight } from "./complexity.js";
+import { getProvider } from "./model.js";
+import { Router } from "./router.js";
+import { SkillsManager } from "./skills.js";
+import { RecallMemory } from "./recall.js";
+import { recordLesson } from "./memory.js";
+import { CostMeter } from "./cost.js";
+import { meteredProvider } from "./metered.js";
+import { AuditLog } from "./audit.js";
+import { randomUUID } from "node:crypto";
+import { Headroom } from "./headroom.js";
+import { detectAgents, resolveTarget, agentSpec } from "./registry.js";
+import { loadConfig } from "./config-store.js";
+import { runScout } from "../phases/scout.js";
+import { runPlan } from "../phases/plan.js";
+import { runExecute } from "../phases/execute.js";
+import { runVerify } from "../phases/verify.js";
+import { Board } from "./board.js";
+import { CostTracker } from "./cost-tracker.js";
+export async function runPipeline(task, opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const baseCfg = loadConfig();
+    // Ad-hoc overrides (do not persist).
+    const cfg = {
+        ...baseCfg,
+        ...(opts.provider ? { provider: opts.provider } : {}),
+        ...(opts.model ? { cheapModel: opts.model, strongModel: opts.model } : {}),
+    };
+    const provider = getProvider(cfg.provider);
+    const router = new Router(cfg);
+    const skillsMgr = new SkillsManager(cwd, { skillsDir: cfg.skillsDir });
+    const headroom = new Headroom();
+    const meter = new CostMeter();
+    const runId = randomUUID();
+    const audit = opts.audit || baseCfg.auditRuns ? new AuditLog(cwd, runId) : undefined;
+    const board = new Board(cwd);
+    const costTracker = new CostTracker(cwd);
+    const boardTaskId = board.createTask(task);
+    const events = [];
+    const emit = (e) => {
+        events.push(e);
+        opts.onEvent?.(e);
+    };
+    emit(makeEvent("task.started", { task, cwd, provider: provider.name, cheapModel: cfg.cheapModel, strongModel: cfg.strongModel, boardTaskId }));
+    audit?.record("task.started", { task, provider: provider.name });
+    // --- SCOUT ---
+    board.phaseStart(boardTaskId, "scout");
+    emit(makeEvent("phase.started", { phase: "scout" }));
+    const scout = await runScout(task, cwd);
+    board.phaseData(boardTaskId, "scout", { complexity: scout.complexity, files: scout.files.length, notes: scout.notes });
+    board.phaseDone(boardTaskId, "scout");
+    emit(makeEvent("phase.done", { phase: "scout", complexity: scout.complexity, files: scout.files.length }));
+    audit?.record("scout.done", { complexity: scout.complexity, files: scout.files.length });
+    audit?.artifact("scout.json", scout);
+    // Resolve worker target.
+    const agents = detectAgents();
+    const requested = opts.target ?? cfg.projectTargets[cwd] ?? cfg.defaultTarget;
+    const { target, ambiguous } = resolveTarget(requested, agents);
+    const binPath = target === "none" ? null : (agents.find((a) => a.name === target)?.binPath ?? null);
+    if (ambiguous.length > 1) {
+        emit(makeEvent("agent.event", { note: "multiple ready agents; picked first", ambiguous, target }));
+    }
+    // --- PLAN (gated by complexity, routed to a model tier) ---
+    await opts.checkpoint?.();
+    let plan = null;
+    if (shouldRunPreflight(scout.complexity)) {
+        const route = router.routeByComplexity(scout.complexity);
+        const skillsBlock = skillsMgr.contextBlock(route.tier);
+        const recallBlock = new RecallMemory(cwd).contextBlock(task);
+        const context = [recallBlock, skillsBlock].filter(Boolean).join("\n\n");
+        board.phaseStart(boardTaskId, "plan", { tier: route.tier, model: route.model });
+        emit(makeEvent("phase.started", { phase: "plan", tier: route.tier, model: route.model, skills: skillsMgr.forTier(route.tier).length, recalled: recallBlock ? true : false }));
+        plan = await runPlan(scout, meteredProvider(route.provider, meter), route.model, context);
+        board.phaseData(boardTaskId, "plan", { winner: plan.winner.summary, candidates: plan.candidatesGenerated, earlyExit: plan.earlyExit });
+        board.phaseDone(boardTaskId, "plan");
+        emit(makeEvent("phase.done", {
+            phase: "plan",
+            winner: plan.winner.summary,
+            candidates: plan.candidatesGenerated,
+            earlyExit: plan.earlyExit,
+        }));
+        audit?.record("plan.done", { winner: plan.winner.summary, candidates: plan.candidatesGenerated });
+        audit?.artifact("plan.json", plan);
+    }
+    else {
+        board.phaseStart(boardTaskId, "plan", { skipped: true });
+        board.phaseDone(boardTaskId, "plan", { skipped: true, reason: "trivial task" });
+        emit(makeEvent("phase.done", { phase: "plan", skipped: true, reason: "trivial task" }));
+        plan = trivialPlan(task);
+    }
+    // --- EXECUTE ---
+    await opts.checkpoint?.();
+    board.phaseStart(boardTaskId, "execute", { target });
+    emit(makeEvent("phase.started", { phase: "execute", target }));
+    const execResult = await runExecute(plan, {
+        cwd,
+        target,
+        binPath,
+        dryRun: opts.dryRun,
+        timeoutMs: opts.timeoutMs,
+        headroom,
+        onEvent: emit,
+        signal: opts.signal,
+    });
+    board.phaseData(boardTaskId, "execute", { status: execResult.status, exitCode: execResult.exitCode, filesChanged: execResult.filesChanged });
+    board.phaseDone(boardTaskId, "execute");
+    emit(makeEvent("phase.done", { phase: "execute", status: execResult.status, exitCode: execResult.exitCode }));
+    audit?.record("execute.done", { status: execResult.status, exitCode: execResult.exitCode });
+    audit?.artifact("execute.json", execResult);
+    // --- VERIFY (cheap tier) ---
+    await opts.checkpoint?.();
+    board.phaseStart(boardTaskId, "verify");
+    emit(makeEvent("phase.started", { phase: "verify" }));
+    const verifyRoute = router.route("cheap");
+    const verifyResult = await runVerify(execResult, {
+        cwd,
+        provider: meteredProvider(verifyRoute.provider, meter),
+        model: verifyRoute.model,
+        skipTests: opts.dryRun,
+        timeoutMs: opts.timeoutMs,
+    });
+    board.phaseData(boardTaskId, "verify", { verified: verifyResult.verified, method: verifyResult.method });
+    board.phaseDone(boardTaskId, "verify");
+    emit(makeEvent("phase.done", { phase: "verify", verified: verifyResult.verified, method: verifyResult.method }));
+    audit?.record("verify.done", { verified: verifyResult.verified, method: verifyResult.method });
+    audit?.artifact("verify.json", verifyResult);
+    // Self-learning loop: on verify failure, append a lesson to AGENTS.md so the
+    // worker sees corrective guidance next time. Skipped for dry runs.
+    if (!opts.dryRun && !verifyResult.verified) {
+        const lessonPath = recordLesson(cwd, {
+            task,
+            method: verifyResult.method,
+            details: verifyResult.details,
+            errors: execResult.errors,
+        });
+        if (lessonPath)
+            emit(makeEvent("agent.event", { note: "recorded lesson", file: "AGENTS.md" }));
+    }
+    emit(makeEvent("task.done", {
+        verified: verifyResult.verified,
+        status: execResult.status,
+        compressionStoreSize: headroom.size(),
+        cost: meter.summary,
+    }));
+    audit?.record("task.done", { verified: verifyResult.verified, status: execResult.status, cost: meter.summary });
+    // Finalize the board task.
+    if (verifyResult.verified && execResult.status !== "failed") {
+        board.taskDone(boardTaskId, { verified: true, cost: meter.summary });
+    }
+    else {
+        board.taskError(boardTaskId, verifyResult.details || execResult.errors.join("; "));
+    }
+    // Record aggregated cost for this run.
+    if (meter.summary.calls > 0) {
+        costTracker.record({
+            ts: new Date().toISOString(),
+            taskId: boardTaskId,
+            task: task.slice(0, 100),
+            provider: cfg.provider,
+            model: cfg.cheapModel,
+            ...meter.summary,
+        });
+    }
+    // Auto-write a skill file when verify succeeds on a non-trivial task.
+    if (!opts.dryRun && verifyResult.verified && scout.complexity !== "trivial") {
+        try {
+            const skillName = task.replace(/[^a-zA-Z0-9]+/g, "-").toLowerCase().slice(0, 40);
+            const skillContent = [
+                "maq-tier: all",
+                "maq-kind: context",
+                "",
+                `# Learned: ${task.slice(0, 80)}`,
+                "",
+                `Verified approach: ${plan?.winner.summary ?? task}`,
+                plan?.winner.steps?.length ? `Steps: ${plan.winner.steps.join("; ")}` : "",
+                `Complexity: ${scout.complexity}, target: ${execResult.target}`,
+            ].filter(Boolean).join("\n");
+            const { writeFileSync, existsSync, mkdirSync } = await import("node:fs");
+            const { join } = await import("node:path");
+            const dir = join(cwd, cfg.skillsDir);
+            if (!existsSync(dir))
+                mkdirSync(dir, { recursive: true });
+            const skillPath = join(dir, `learned-${skillName}.md`);
+            if (!existsSync(skillPath)) {
+                writeFileSync(skillPath, skillContent, "utf8");
+                emit(makeEvent("agent.event", { note: "auto-learned skill", file: skillPath }));
+            }
+        }
+        catch { /* skill write is best-effort */ }
+    }
+    const result = {
+        task,
+        scout,
+        plan,
+        execute: execResult,
+        verify: verifyResult,
+        events,
+        cost: meter.summary,
+        runId: audit ? runId : undefined,
+    };
+    audit?.artifact("result.json", { ...result, events: undefined });
+    return result;
+}
+function trivialPlan(task) {
+    const winner = {
+        summary: task,
+        steps: [],
+        score: 1,
+        pass: true,
+        reason: "trivial task; no planning needed",
+    };
+    return { winner, allEvaluated: [winner], candidatesGenerated: 0, earlyExit: true };
+}
+export { agentSpec };

package/dist/core/plugins.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Plugins (outbound) — forward MAQ events to external targets (Slack / Discord /
+ * any webhook), CAO-style but dependency-free (global fetch). Observer-only:
+ * plugins never drive MAQ, they only stream events out. Attach one to the
+ * SessionRegistry's event bus and it POSTs each event to a URL.
+ */
+import type { SessionRegistry } from "./session.js";
+export interface WebhookOptions {
+    url: string;
+    /** Only forward these event types (default: task.* lifecycle). */
+    types?: string[];
+    timeoutMs?: number;
+    log?: (msg: string) => void;
+}
+/** POST a single event to a webhook. Never throws. */
+export declare function postWebhook(url: string, payload: unknown, timeoutMs?: number): Promise<boolean>;
+/**
+ * Attach a webhook forwarder to a registry. Returns an unsubscribe function.
+ * By default forwards lifecycle events (task.started/done/error/cancelled).
+ */
+export declare function attachWebhook(registry: SessionRegistry, opts: WebhookOptions): () => void;

package/dist/core/plugins.js

@@ -0,0 +1,38 @@
+/**
+ * Plugins (outbound) — forward MAQ events to external targets (Slack / Discord /
+ * any webhook), CAO-style but dependency-free (global fetch). Observer-only:
+ * plugins never drive MAQ, they only stream events out. Attach one to the
+ * SessionRegistry's event bus and it POSTs each event to a URL.
+ */
+/** POST a single event to a webhook. Never throws. */
+export async function postWebhook(url, payload, timeoutMs = 5000) {
+    try {
+        const res = await fetch(url, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(payload),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Attach a webhook forwarder to a registry. Returns an unsubscribe function.
+ * By default forwards lifecycle events (task.started/done/error/cancelled).
+ */
+export function attachWebhook(registry, opts) {
+    const types = new Set(opts.types ?? ["task.started", "task.done", "task.error", "task.cancelled"]);
+    const listener = (payload) => {
+        if (!types.has(payload.event.type))
+            return;
+        void postWebhook(opts.url, { sessionId: payload.sessionId, event: payload.event }, opts.timeoutMs).then((ok) => {
+            if (!ok)
+                opts.log?.(`webhook POST failed: ${opts.url}`);
+        });
+    };
+    registry.onAny(listener);
+    return () => registry.offAny(listener);
+}

package/dist/core/probe.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Connectivity probe — turns the pure decision logic in connectivity.ts into a
+ * real measurement, dependency-free (node:dgram, node:net, node:os).
+ *
+ *  - LAN presence: is there a private-range IPv4 interface (a LAN to discover
+ *    peers on)? Full mDNS discovery lives in the native track; this is the
+ *    cheap signal the daemon can compute alone.
+ *  - P2P reachability: a real STUN Binding Request over UDP to a public STUN
+ *    server. A Binding Success Response means UDP hole-punching is viable
+ *    (direct P2P likely works). Timeout/refusal suggests UDP is blocked.
+ *  - Relay reachability: an outbound TCP connect to a relay host:443 — the
+ *    outbound-only path the product relies on when P2P fails.
+ *  - Symmetric-NAT suspicion: outbound TCP works but STUN/UDP does not.
+ */
+import { type NetworkObservation, type TierDecision } from "./connectivity.js";
+export interface ProbeResult {
+    observation: NetworkObservation;
+    decision: TierDecision;
+    details: {
+        lanInterfaces: string[];
+        stun: {
+            ok: boolean;
+            rttMs?: number;
+            mapped?: string;
+            server: string;
+        };
+        relay: {
+            ok: boolean;
+            rttMs?: number;
+            host: string;
+        };
+    };
+}
+/** List non-internal private-range IPv4 addresses (a sign of a usable LAN). */
+export declare function lanIpv4Interfaces(): string[];
+/** Send a STUN Binding Request; resolve with the mapped address if we get one. */
+export declare function stunProbe(host?: string, port?: number, timeoutMs?: number): Promise<{
+    ok: boolean;
+    rttMs?: number;
+    mapped?: string;
+}>;
+/** Attempt an outbound TCP connection; resolve with reachability + RTT. */
+export declare function tcpReachable(host?: string, port?: number, timeoutMs?: number): Promise<{
+    ok: boolean;
+    rttMs?: number;
+}>;
+/** Run all probes and produce a tier decision. */
+export declare function probeConnectivity(premium?: boolean): Promise<ProbeResult>;

package/dist/core/probe.js

@@ -0,0 +1,156 @@
+/**
+ * Connectivity probe — turns the pure decision logic in connectivity.ts into a
+ * real measurement, dependency-free (node:dgram, node:net, node:os).
+ *
+ *  - LAN presence: is there a private-range IPv4 interface (a LAN to discover
+ *    peers on)? Full mDNS discovery lives in the native track; this is the
+ *    cheap signal the daemon can compute alone.
+ *  - P2P reachability: a real STUN Binding Request over UDP to a public STUN
+ *    server. A Binding Success Response means UDP hole-punching is viable
+ *    (direct P2P likely works). Timeout/refusal suggests UDP is blocked.
+ *  - Relay reachability: an outbound TCP connect to a relay host:443 — the
+ *    outbound-only path the product relies on when P2P fails.
+ *  - Symmetric-NAT suspicion: outbound TCP works but STUN/UDP does not.
+ */
+import { createSocket } from "node:dgram";
+import { connect } from "node:net";
+import { networkInterfaces } from "node:os";
+import { randomBytes } from "node:crypto";
+import { selectTier } from "./connectivity.js";
+const STUN_SERVER = { host: process.env.MAQ_STUN_HOST ?? "stun.l.google.com", port: Number(process.env.MAQ_STUN_PORT ?? 19302) };
+const RELAY_HOST = process.env.MAQ_RELAY_HOST ?? "1.1.1.1";
+const RELAY_PORT = Number(process.env.MAQ_RELAY_PORT ?? 443);
+/** List non-internal private-range IPv4 addresses (a sign of a usable LAN). */
+export function lanIpv4Interfaces() {
+    const out = [];
+    const ifaces = networkInterfaces();
+    for (const addrs of Object.values(ifaces)) {
+        for (const a of addrs ?? []) {
+            if (a.family === "IPv4" && !a.internal && isPrivate(a.address))
+                out.push(a.address);
+        }
+    }
+    return out;
+}
+function isPrivate(ip) {
+    return (ip.startsWith("10.") ||
+        ip.startsWith("192.168.") ||
+        /^172\.(1[6-9]|2\d|3[01])\./.test(ip) ||
+        ip.startsWith("169.254."));
+}
+/** Send a STUN Binding Request; resolve with the mapped address if we get one. */
+export function stunProbe(host = STUN_SERVER.host, port = STUN_SERVER.port, timeoutMs = 3000) {
+    return new Promise((resolve) => {
+        const sock = createSocket("udp4");
+        const txId = randomBytes(12);
+        // 20-byte header: type=0x0001 (Binding Request), length=0, magic cookie, txid.
+        const msg = Buffer.alloc(20);
+        msg.writeUInt16BE(0x0001, 0);
+        msg.writeUInt16BE(0x0000, 2);
+        msg.writeUInt32BE(0x2112a442, 4);
+        txId.copy(msg, 8);
+        const start = Date.now();
+        let done = false;
+        const finish = (r) => {
+            if (done)
+                return;
+            done = true;
+            try {
+                sock.close();
+            }
+            catch {
+                /* ignore */
+            }
+            resolve(r);
+        };
+        const timer = setTimeout(() => finish({ ok: false }), timeoutMs);
+        sock.on("error", () => {
+            clearTimeout(timer);
+            finish({ ok: false });
+        });
+        sock.on("message", (resp) => {
+            clearTimeout(timer);
+            const rttMs = Date.now() - start;
+            const mapped = parseMappedAddress(resp);
+            finish({ ok: resp.readUInt16BE(0) === 0x0101, rttMs, mapped });
+        });
+        sock.send(msg, port, host, (err) => {
+            if (err) {
+                clearTimeout(timer);
+                finish({ ok: false });
+            }
+        });
+    });
+}
+/** Parse XOR-MAPPED-ADDRESS (0x0020) or MAPPED-ADDRESS (0x0001) from a response. */
+function parseMappedAddress(resp) {
+    try {
+        let offset = 20;
+        const magic = 0x2112a442;
+        while (offset + 4 <= resp.length) {
+            const type = resp.readUInt16BE(offset);
+            const len = resp.readUInt16BE(offset + 2);
+            const valStart = offset + 4;
+            if (type === 0x0020 || type === 0x0001) {
+                const family = resp.readUInt8(valStart + 1);
+                if (family === 0x01) {
+                    let port = resp.readUInt16BE(valStart + 2);
+                    let ip = [resp[valStart + 4], resp[valStart + 5], resp[valStart + 6], resp[valStart + 7]];
+                    if (type === 0x0020) {
+                        port ^= magic >>> 16;
+                        ip = ip.map((b, i) => b ^ ((magic >>> (24 - i * 8)) & 0xff));
+                    }
+                    return `${ip.join(".")}:${port & 0xffff}`;
+                }
+            }
+            offset = valStart + len + ((4 - (len % 4)) % 4);
+        }
+    }
+    catch {
+        /* ignore malformed */
+    }
+    return undefined;
+}
+/** Attempt an outbound TCP connection; resolve with reachability + RTT. */
+export function tcpReachable(host = RELAY_HOST, port = RELAY_PORT, timeoutMs = 3000) {
+    return new Promise((resolve) => {
+        const start = Date.now();
+        const socket = connect({ host, port });
+        let done = false;
+        const finish = (ok) => {
+            if (done)
+                return;
+            done = true;
+            socket.destroy();
+            resolve(ok ? { ok: true, rttMs: Date.now() - start } : { ok: false });
+        };
+        socket.setTimeout(timeoutMs);
+        socket.once("connect", () => finish(true));
+        socket.once("timeout", () => finish(false));
+        socket.once("error", () => finish(false));
+    });
+}
+/** Run all probes and produce a tier decision. */
+export async function probeConnectivity(premium = false) {
+    const lan = lanIpv4Interfaces();
+    const [stun, relay] = await Promise.all([stunProbe(), tcpReachable()]);
+    const observation = {
+        lanPeerFound: false, // real peer discovery is the native track's job; interfaces alone don't imply a peer
+        lanLatencyMs: undefined,
+        p2pConnected: stun.ok,
+        relayAvailable: relay.ok,
+        relayLatencyMs: relay.rttMs,
+        symmetricNatSuspected: !stun.ok && relay.ok,
+        premium,
+    };
+    const decision = selectTier(observation);
+    return {
+        observation,
+        decision,
+        details: {
+            lanInterfaces: lan,
+            stun: { ok: stun.ok, rttMs: stun.rttMs, mapped: stun.mapped, server: `${STUN_SERVER.host}:${STUN_SERVER.port}` },
+            relay: { ok: relay.ok, rttMs: relay.rttMs, host: `${RELAY_HOST}:${RELAY_PORT}` },
+        },
+    };
+}

package/dist/core/profiles.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Agent profiles — named, reusable specialists (CAO-style), mapped onto MAQ's
+ * existing target/provider/skills/tools machinery. A profile pins how a session
+ * runs: which worker target + provider/model, a role, an optional tool
+ * allow-list (enforced by the tool registry), and which skills apply.
+ *
+ * Sources (later wins): built-ins below, then `<cwd>/.maq/agents/*.md`.
+ * Profile files use light front-matter, e.g.:
+ *   name: reviewer
+ *   target: none
+ *   role: reviewer
+ *   allowedTools: read_file, list_dir, grep_text
+ *   skills: verify-before-done, minimal-diff
+ *   ---
+ *   <freeform description / system guidance>
+ */
+export interface AgentProfile {
+    name: string;
+    description: string;
+    /** Worker target: auto | claude-code | codex | gemini | none | … */
+    target?: string;
+    /** Provider override (e.g. openai, anthropic, cli:gemini). */
+    provider?: string;
+    /** Model override. */
+    model?: string;
+    role?: string;
+    /** Allow-list of tool names this agent may use (undefined = all). */
+    allowedTools?: string[];
+    /** Skill names relevant to this agent (advisory). */
+    skills?: string[];
+    path: string | null;
+}
+export declare class ProfileManager {
+    private cwd;
+    private dir;
+    constructor(cwd: string);
+    load(): AgentProfile[];
+    get(name: string): AgentProfile | undefined;
+    private parse;
+    /** Scaffold a starter profile dir. Returns files written. */
+    init(): string[];
+}

package/dist/core/profiles.js

@@ -0,0 +1,153 @@
+/**
+ * Agent profiles — named, reusable specialists (CAO-style), mapped onto MAQ's
+ * existing target/provider/skills/tools machinery. A profile pins how a session
+ * runs: which worker target + provider/model, a role, an optional tool
+ * allow-list (enforced by the tool registry), and which skills apply.
+ *
+ * Sources (later wins): built-ins below, then `<cwd>/.maq/agents/*.md`.
+ * Profile files use light front-matter, e.g.:
+ *   name: reviewer
+ *   target: none
+ *   role: reviewer
+ *   allowedTools: read_file, list_dir, grep_text
+ *   skills: verify-before-done, minimal-diff
+ *   ---
+ *   <freeform description / system guidance>
+ */
+import { existsSync, readFileSync, readdirSync, statSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+const BUILT_INS = [
+    {
+        name: "code_supervisor",
+        description: "Plans and delegates: scopes the task, splits it, assigns workers, verifies and merges results.",
+        role: "supervisor",
+        target: "auto",
+        skills: ["verify-before-done", "plan-then-act", "structured-handoff"],
+        path: null,
+    },
+    {
+        name: "developer",
+        description: "Implements a scoped change with the smallest diff and keeps tests green.",
+        role: "developer",
+        target: "auto",
+        skills: ["minimal-diff", "read-before-write", "tests-are-truth"],
+        path: null,
+    },
+    {
+        name: "reviewer",
+        description: "Read-only reviewer: inspects code against acceptance criteria; never edits.",
+        role: "reviewer",
+        target: "none",
+        allowedTools: ["read_file", "list_dir", "grep_text"],
+        skills: ["verify-before-done", "cite-what-you-checked"],
+        path: null,
+    },
+];
+const FIELDS = new Set(["name", "target", "provider", "model", "role", "allowedtools", "skills"]);
+export class ProfileManager {
+    cwd;
+    dir;
+    constructor(cwd) {
+        this.cwd = cwd;
+        this.dir = join(cwd, ".maq", "agents");
+    }
+    load() {
+        const byName = new Map();
+        for (const p of BUILT_INS)
+            byName.set(p.name, p);
+        if (existsSync(this.dir)) {
+            let entries = [];
+            try {
+                entries = readdirSync(this.dir);
+            }
+            catch {
+                entries = [];
+            }
+            for (const e of entries) {
+                if (!e.toLowerCase().endsWith(".md"))
+                    continue;
+                const p = this.parse(join(this.dir, e), e.replace(/\.md$/i, ""));
+                if (p)
+                    byName.set(p.name, p);
+            }
+        }
+        return [...byName.values()];
+    }
+    get(name) {
+        return this.load().find((p) => p.name === name);
+    }
+    parse(path, fallbackName) {
+        try {
+            if (!statSync(path).isFile())
+                return null;
+            const raw = readFileSync(path, "utf8");
+            const lines = raw.split(/\r?\n/);
+            const p = { name: fallbackName, description: "", path };
+            let i = 0;
+            const desc = [];
+            let inFront = true;
+            for (; i < lines.length; i++) {
+                const line = lines[i];
+                if (inFront) {
+                    if (line.trim() === "---") {
+                        inFront = false;
+                        continue;
+                    }
+                    const m = /^\s*([a-zA-Z]+)\s*:\s*(.+)$/.exec(line);
+                    if (m && FIELDS.has(m[1].toLowerCase())) {
+                        const key = m[1].toLowerCase();
+                        const val = m[2].trim();
+                        if (key === "name")
+                            p.name = val;
+                        else if (key === "target")
+                            p.target = val;
+                        else if (key === "provider")
+                            p.provider = val;
+                        else if (key === "model")
+                            p.model = val;
+                        else if (key === "role")
+                            p.role = val;
+                        else if (key === "allowedtools")
+                            p.allowedTools = val.split(/[,\s]+/).filter(Boolean);
+                        else if (key === "skills")
+                            p.skills = val.split(/[,\s]+/).filter(Boolean);
+                        continue;
+                    }
+                    // No recognized front-matter -> treat rest as description.
+                    inFront = false;
+                }
+                desc.push(line);
+            }
+            p.description = desc.join("\n").trim();
+            return p;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Scaffold a starter profile dir. Returns files written. */
+    init() {
+        const written = [];
+        try {
+            mkdirSync(this.dir, { recursive: true });
+        }
+        catch {
+            /* ignore */
+        }
+        const example = join(this.dir, "reviewer.md");
+        if (!existsSync(example)) {
+            writeFileSync(example, [
+                "name: reviewer",
+                "target: none",
+                "role: reviewer",
+                "allowedTools: read_file, list_dir, grep_text",
+                "skills: verify-before-done, cite-what-you-checked",
+                "---",
+                "Read-only reviewer. Inspect the change against acceptance criteria and report",
+                "findings; never edit files.",
+            ].join("\n"), "utf8");
+            written.push(example);
+        }
+        return written;
+    }
+}