agentplane 0.3.7 → 0.3.9

package/dist/cli/run-cli/commands/config.js

@@ -1,7 +1,11 @@
+import fs from "node:fs/promises";
 import path from "node:path";
-import { buildExecutionProfile, saveConfig, setByDottedKey } from "@agentplaneorg/core";
+import { buildExecutionProfile, loadConfig, saveConfig, setByDottedKey } from "@agentplaneorg/core";
+import { createCliEmitter } from "../../output.js";
 import { usageError } from "../../spec/errors.js";
+import { ensureWorkflowArtifacts } from "../../../shared/workflow-artifacts.js";
 import { wrapCommand } from "./wrap-command.js";
+const output = createCliEmitter();
 export const configShowSpec = {
     id: ["config", "show"],
     group: "Config",
@@ -12,13 +16,41 @@ export const configShowSpec = {
 async function cmdConfigShow(opts) {
     return wrapCommand({ command: "config show", rootOverride: opts.rootOverride }, async () => {
         const loaded = await opts.deps.getLoadedConfig("config show");
-        process.stdout.write(`${JSON.stringify(loaded.raw, null, 2)}\n`);
+        output.json(loaded.raw);
         return 0;
     });
 }
 export function makeRunConfigShowHandler(deps) {
     return (ctx) => cmdConfigShow({ cwd: ctx.cwd, rootOverride: ctx.rootOverride, deps });
 }
+function shouldRefreshWorkflowArtifactsForKey(key) {
+    const normalized = key.trim();
+    return normalized === "workflow_mode" || normalized.startsWith("agents.approvals.");
+}
+async function syncWorkflowArtifactsFromSavedConfig(opts) {
+    try {
+        const agentEntries = await fs.readdir(path.join(opts.agentplaneDir, "agents"), {
+            withFileTypes: true,
+        });
+        if (!agentEntries.some((entry) => entry.isFile() && entry.name.endsWith(".json"))) {
+            return false;
+        }
+    }
+    catch {
+        return false;
+    }
+    const refreshed = await loadConfig(opts.agentplaneDir);
+    await ensureWorkflowArtifacts({
+        gitRoot: opts.gitRoot,
+        workflowMode: refreshed.config.workflow_mode,
+        approvals: {
+            requirePlanApproval: refreshed.config.agents?.approvals?.require_plan ?? true,
+            requireVerifyApproval: refreshed.config.agents?.approvals?.require_verify ?? true,
+            requireNetworkApproval: refreshed.config.agents?.approvals?.require_network ?? true,
+        },
+    });
+    return true;
+}
 export const configSetSpec = {
     id: ["config", "set"],
     group: "Config",
@@ -47,7 +79,13 @@ async function cmdConfigSet(opts) {
         const raw = { ...loaded.raw };
         setByDottedKey(raw, opts.key, opts.value);
         await saveConfig(resolved.agentplaneDir, raw);
-        process.stdout.write(`${path.relative(resolved.gitRoot, path.join(resolved.agentplaneDir, "config.json"))}\n`);
+        if (shouldRefreshWorkflowArtifactsForKey(opts.key)) {
+            await syncWorkflowArtifactsFromSavedConfig({
+                gitRoot: resolved.gitRoot,
+                agentplaneDir: resolved.agentplaneDir,
+            });
+        }
+        output.line(path.relative(resolved.gitRoot, path.join(resolved.agentplaneDir, "config.json")));
         return 0;
     });
 }
@@ -70,7 +108,7 @@ export const modeGetSpec = {
 async function cmdModeGet(opts) {
     return wrapCommand({ command: "mode get", rootOverride: opts.rootOverride }, async () => {
         const loaded = await opts.deps.getLoadedConfig("mode get");
-        process.stdout.write(`${loaded.config.workflow_mode}\n`);
+        output.line(loaded.config.workflow_mode);
         return 0;
     });
 }
@@ -105,7 +143,11 @@ async function cmdModeSet(opts) {
         const raw = { ...loaded.raw };
         setByDottedKey(raw, "workflow_mode", opts.mode);
         await saveConfig(resolved.agentplaneDir, raw);
-        process.stdout.write(`${opts.mode}\n`);
+        await syncWorkflowArtifactsFromSavedConfig({
+            gitRoot: resolved.gitRoot,
+            agentplaneDir: resolved.agentplaneDir,
+        });
+        output.line(opts.mode);
         return 0;
     });
 }
@@ -190,7 +232,11 @@ async function cmdProfileSet(opts) {
         setByDottedKey(raw, "agents.approvals.require_verify", String(preset.requireVerify));
         setByDottedKey(raw, "execution", JSON.stringify(execution));
         await saveConfig(resolved.agentplaneDir, raw);
-        process.stdout.write(`${opts.profile}\n`);
+        await syncWorkflowArtifactsFromSavedConfig({
+            gitRoot: resolved.gitRoot,
+            agentplaneDir: resolved.agentplaneDir,
+        });
+        output.line(opts.profile);
         return 0;
     });
 }

package/dist/cli/run-cli/commands/core/agent-profiles.d.ts

@@ -0,0 +1,34 @@
+import type { RoleProfileGuide } from "../../../command-guide.js";
+export type AgentProfile = {
+    id?: string;
+    role?: string;
+    description?: string;
+    inputs?: unknown;
+    outputs?: unknown;
+    permissions?: unknown;
+    workflow?: unknown;
+};
+export declare function parseAgentProfileJson(filePath: string, text: string): AgentProfile;
+export declare function normalizeRoleId(roleRaw: string): string;
+export declare function listAgentProfileIds(opts: {
+    cwd: string;
+    rootOverride?: string;
+}): Promise<{
+    agentplaneDir: string;
+    ids: string[];
+} | null>;
+export declare function readAgentProfile(opts: {
+    cwd: string;
+    rootOverride?: string;
+    roleId: string;
+}): Promise<{
+    agentplaneDir: string;
+    filename: string;
+    profile: AgentProfile;
+} | null>;
+export declare function toRoleProfileGuide(opts: {
+    filename: string;
+    roleId: string;
+    profile: AgentProfile;
+}): RoleProfileGuide;
+//# sourceMappingURL=agent-profiles.d.ts.map

package/dist/cli/run-cli/commands/core/agent-profiles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-profiles.d.ts","sourceRoot":"","sources":["../../../../../src/cli/run-cli/commands/core/agent-profiles.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAKlE,MAAM,MAAM,YAAY,GAAG;IACzB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,CAmBlF;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,wBAAsB,mBAAmB,CAAC,IAAI,EAAE;IAC9C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,OAAO,CAAC;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,IAAI,CAAC,CAgB3D;AAED,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE,GAAG,IAAI,CAAC,CA4BrF;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,YAAY,CAAC;CACvB,GAAG,gBAAgB,CAsBnB"}

package/dist/cli/run-cli/commands/core/agent-profiles.js

@@ -0,0 +1,97 @@
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { resolveProject } from "@agentplaneorg/core";
+import { fileExists } from "../../../fs-utils.js";
+import { toStringList } from "../../../spec/parse-utils.js";
+import { CliError } from "../../../../shared/errors.js";
+export function parseAgentProfileJson(filePath, text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new CliError({
+            exitCode: 3,
+            code: "E_VALIDATION",
+            message: `Invalid agent profile JSON: ${filePath} (malformed JSON)`,
+        });
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new CliError({
+            exitCode: 3,
+            code: "E_VALIDATION",
+            message: `Invalid agent profile JSON: ${filePath} (expected object)`,
+        });
+    }
+    return parsed;
+}
+export function normalizeRoleId(roleRaw) {
+    return roleRaw.trim().toUpperCase();
+}
+export async function listAgentProfileIds(opts) {
+    try {
+        const resolved = await resolveProject({
+            cwd: opts.cwd,
+            rootOverride: opts.rootOverride ?? null,
+        });
+        const agentsDir = path.join(resolved.agentplaneDir, "agents");
+        if (!(await fileExists(agentsDir)))
+            return null;
+        const entriesRaw = await readdir(agentsDir);
+        const entries = entriesRaw.filter((name) => name.endsWith(".json")).toSorted();
+        const ids = entries.map((name) => name.replace(/\.json$/i, ""));
+        return { agentplaneDir: resolved.agentplaneDir, ids };
+    }
+    catch {
+        // Best-effort: role should not fail if we're not in an agentplane project.
+        return null;
+    }
+}
+export async function readAgentProfile(opts) {
+    const listing = await listAgentProfileIds({ cwd: opts.cwd, rootOverride: opts.rootOverride });
+    if (!listing)
+        return null;
+    const roleId = normalizeRoleId(opts.roleId);
+    const candidates = [roleId, opts.roleId.trim()].filter(Boolean);
+    const idsLower = new Map();
+    for (const id of listing.ids)
+        idsLower.set(id.toLowerCase(), id);
+    let foundId = null;
+    for (const candidate of candidates) {
+        const exact = listing.ids.find((id) => id === candidate);
+        if (exact) {
+            foundId = exact;
+            break;
+        }
+        const ci = idsLower.get(candidate.toLowerCase());
+        if (ci) {
+            foundId = ci;
+            break;
+        }
+    }
+    if (!foundId)
+        return null;
+    const filename = `${foundId}.json`;
+    const filePath = path.join(listing.agentplaneDir, "agents", filename);
+    const profile = parseAgentProfileJson(filePath, await readFile(filePath, "utf8"));
+    return { agentplaneDir: listing.agentplaneDir, filename, profile };
+}
+export function toRoleProfileGuide(opts) {
+    const id = (typeof opts.profile.id === "string" ? opts.profile.id : "").trim() || opts.roleId;
+    const role = (typeof opts.profile.role === "string" ? opts.profile.role : "").trim();
+    const description = (typeof opts.profile.description === "string" ? opts.profile.description : "").trim();
+    const inputs = toStringList(opts.profile.inputs);
+    const outputs = toStringList(opts.profile.outputs);
+    const permissions = toStringList(opts.profile.permissions);
+    const workflow = toStringList(opts.profile.workflow);
+    return {
+        filename: opts.filename,
+        id,
+        role,
+        description,
+        inputs,
+        outputs,
+        permissions,
+        workflow,
+    };
+}

package/dist/cli/run-cli/commands/core/agents.d.ts

@@ -0,0 +1,7 @@
+import type { CommandHandler, CommandSpec } from "../../../spec/spec.js";
+import type { RunDeps } from "../../command-catalog.js";
+type AgentsParsed = Record<string, never>;
+export declare const agentsSpec: CommandSpec<AgentsParsed>;
+export declare function makeRunAgentsHandler(deps: RunDeps): CommandHandler<AgentsParsed>;
+export {};
+//# sourceMappingURL=agents.d.ts.map

package/dist/cli/run-cli/commands/core/agents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../../../../src/cli/run-cli/commands/core/agents.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEzE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAOxD,KAAK,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAE1C,eAAO,MAAM,UAAU,EAAE,WAAW,CAAC,YAAY,CAMhD,CAAC;AA4BF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAAC,YAAY,CAAC,CAqEhF"}

package/dist/cli/run-cli/commands/core/agents.js

@@ -0,0 +1,97 @@
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { dedupeStrings } from "../../../../shared/strings.js";
+import { CliError } from "../../../../shared/errors.js";
+import { createCliEmitter } from "../../../output.js";
+import { fileExists } from "../../../fs-utils.js";
+import { parseAgentProfileJson } from "./agent-profiles.js";
+import { wrapCommand } from "../wrap-command.js";
+const output = createCliEmitter();
+export const agentsSpec = {
+    id: ["agents"],
+    group: "Core",
+    summary: "List agent definitions under .agentplane/agents.",
+    examples: [{ cmd: "agentplane agents", why: "Print available agent ids and roles." }],
+    parse: () => ({}),
+};
+function formatAgentsTableLines(rows, showRawIdColumn) {
+    const widthId = Math.max(...rows.map((row) => row.canonicalId.length), "ID".length);
+    const widthFile = Math.max(...rows.map((row) => row.filename.length), "FILE".length);
+    if (showRawIdColumn) {
+        const widthRawId = Math.max(...rows.map((row) => row.rawId.length), "RAW_ID".length);
+        return [
+            `${"ID".padEnd(widthId)}  ${"FILE".padEnd(widthFile)}  ${"RAW_ID".padEnd(widthRawId)}  ROLE`,
+            `${"-".repeat(widthId)}  ${"-".repeat(widthFile)}  ${"-".repeat(widthRawId)}  ----`,
+            ...rows.map((row) => `${row.canonicalId.padEnd(widthId)}  ${row.filename.padEnd(widthFile)}  ${row.rawId.padEnd(widthRawId)}  ${row.role}`),
+        ];
+    }
+    return [
+        `${"ID".padEnd(widthId)}  ${"FILE".padEnd(widthFile)}  ROLE`,
+        `${"-".repeat(widthId)}  ${"-".repeat(widthFile)}  ----`,
+        ...rows.map((row) => `${row.canonicalId.padEnd(widthId)}  ${row.filename.padEnd(widthFile)}  ${row.role}`),
+    ];
+}
+export function makeRunAgentsHandler(deps) {
+    return async (ctx) => wrapCommand({ command: "agents", rootOverride: ctx.rootOverride }, async () => {
+        const resolved = await deps.getResolvedProject("agents");
+        const agentsDir = path.join(resolved.agentplaneDir, "agents");
+        if (!(await fileExists(agentsDir))) {
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: `Agents directory not found: ${agentsDir} (run \`agentplane init\`)`,
+            });
+        }
+        const entriesRaw = await readdir(agentsDir);
+        const entries = entriesRaw.filter((name) => name.endsWith(".json")).toSorted();
+        if (entries.length === 0) {
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: `No agent definitions found under ${agentsDir} (expected *.json)`,
+            });
+        }
+        const rows = [];
+        const seen = new Set();
+        const duplicates = [];
+        const mismatches = [];
+        for (const entry of entries) {
+            const canonicalId = entry.replace(/\.json$/i, "");
+            const filePath = path.join(agentsDir, entry);
+            const raw = parseAgentProfileJson(filePath, await readFile(filePath, "utf8"));
+            const rawId = typeof raw.id === "string" ? raw.id : "";
+            const rawRole = typeof raw.role === "string" ? raw.role : "";
+            const normalizedRawId = rawId.trim();
+            const role = rawRole.trim() || "-";
+            if (seen.has(canonicalId)) {
+                duplicates.push(canonicalId);
+            }
+            else {
+                seen.add(canonicalId);
+            }
+            if (normalizedRawId.length > 0 && normalizedRawId !== canonicalId) {
+                mismatches.push({ filename: entry, canonicalId, rawId: normalizedRawId });
+            }
+            rows.push({ canonicalId, role, filename: entry, rawId: normalizedRawId });
+        }
+        output.lines(formatAgentsTableLines(rows, mismatches.length > 0));
+        if (duplicates.length > 0) {
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: `Duplicate canonical agent ids: ${dedupeStrings(duplicates).toSorted().join(", ")}`,
+            });
+        }
+        if (mismatches.length > 0) {
+            const details = mismatches
+                .map((mismatch) => `${mismatch.filename}: raw id "${mismatch.rawId}" != canonical "${mismatch.canonicalId}"`)
+                .join("; ");
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: `Agent profile id mismatch: ${details}`,
+            });
+        }
+        return 0;
+    });
+}

package/dist/cli/run-cli/commands/core/preflight.d.ts

@@ -0,0 +1,10 @@
+import type { CommandHandler, CommandSpec } from "../../../spec/spec.js";
+type PreflightMode = "quick" | "full";
+type PreflightParsed = {
+    json: boolean;
+    mode: PreflightMode;
+};
+export declare const preflightSpec: CommandSpec<PreflightParsed>;
+export declare const runPreflight: CommandHandler<PreflightParsed>;
+export {};
+//# sourceMappingURL=preflight.d.ts.map

package/dist/cli/run-cli/commands/core/preflight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preflight.d.ts","sourceRoot":"","sources":["../../../../../src/cli/run-cli/commands/core/preflight.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAMzE,KAAK,aAAa,GAAG,OAAO,GAAG,MAAM,CAAC;AACtC,KAAK,eAAe,GAAG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,aAAa,CAAA;CAAE,CAAC;AAyO9D,eAAO,MAAM,aAAa,EAAE,WAAW,CAAC,eAAe,CAuCtD,CAAC;AAoDF,eAAO,MAAM,YAAY,EAAE,cAAc,CAAC,eAAe,CAOxD,CAAC"}

package/dist/cli/run-cli/commands/core/preflight.js

@@ -0,0 +1,286 @@
+import { loadConfig, resolveProject } from "@agentplaneorg/core";
+import { loadTaskBackend } from "../../../../backends/task-backend.js";
+import { GitContext } from "../../../../commands/shared/git-context.js";
+import { gitCurrentBranch } from "../../../../commands/shared/git-ops.js";
+import { dedupeStrings } from "../../../../shared/strings.js";
+import { isWorkflowEnforcementDisabled, validateWorkflowAtPath, workflowEnforcementEnvHint, } from "../../../../workflow-runtime/index.js";
+import { renderQuickstart } from "../../../command-guide.js";
+import { createCliEmitter } from "../../../output.js";
+import { wrapCommand } from "../wrap-command.js";
+const output = createCliEmitter();
+function compactError(err) {
+    if (err instanceof Error) {
+        const first = (err.message ?? "").split("\n", 1)[0] ?? "";
+        return first.trim() || err.name;
+    }
+    return String(err);
+}
+function probeYesNo(probe) {
+    return probe.ok ? "yes" : "no";
+}
+function probeValueOrUnknown(probe) {
+    return probe.ok && probe.value !== undefined ? String(probe.value) : "unknown";
+}
+function inferWorkflowMode(config) {
+    if (!config)
+        return "unknown";
+    return config.workflow_mode === "direct" || config.workflow_mode === "branch_pr"
+        ? config.workflow_mode
+        : "unknown";
+}
+function inferApprovals(config) {
+    if (!config?.agents?.approvals) {
+        return {
+            require_plan: "unknown",
+            require_verify: "unknown",
+            require_network: "unknown",
+        };
+    }
+    const approvals = config.agents.approvals;
+    return {
+        require_plan: approvals.require_plan,
+        require_verify: approvals.require_verify,
+        require_network: approvals.require_network,
+    };
+}
+async function buildPreflightReport(opts) {
+    const nextActions = [];
+    const harnessHealthReasons = [];
+    const quickstartText = renderQuickstart();
+    const quickstartLoaded = {
+        ok: quickstartText.trim().length > 0,
+        error: quickstartText.trim().length > 0 ? undefined : "quickstart renderer returned empty output",
+    };
+    let resolved = null;
+    try {
+        resolved = await resolveProject({ cwd: opts.cwd, rootOverride: opts.rootOverride ?? null });
+    }
+    catch (err) {
+        nextActions.push({
+            command: "agentplane init",
+            reason: `project not resolved (${compactError(err)})`,
+        });
+    }
+    let config = null;
+    let configLoaded = { ok: false, error: "project not resolved" };
+    if (resolved) {
+        try {
+            const loaded = await loadConfig(resolved.agentplaneDir);
+            config = loaded.config;
+            configLoaded = { ok: true };
+        }
+        catch (err) {
+            const message = compactError(err);
+            configLoaded = { ok: false, error: message };
+            nextActions.push({
+                command: "agentplane config show",
+                reason: `config failed validation (${message})`,
+            });
+            harnessHealthReasons.push("config_unavailable");
+        }
+    }
+    let taskListLoaded = {
+        ok: false,
+        error: opts.mode === "quick" ? "skipped in quick mode" : "project not resolved",
+    };
+    if (opts.mode === "full" && resolved) {
+        try {
+            const loaded = await loadTaskBackend({
+                cwd: opts.cwd,
+                rootOverride: opts.rootOverride ?? null,
+            });
+            const tasks = await loaded.backend.listTasks();
+            taskListLoaded = { ok: true, count: tasks.length };
+        }
+        catch (err) {
+            const message = compactError(err);
+            taskListLoaded = { ok: false, error: message };
+            nextActions.push({
+                command: "agentplane task list",
+                reason: `task backend unavailable (${message})`,
+            });
+            harnessHealthReasons.push("task_backend_unavailable");
+        }
+    }
+    let workflowLoaded = { ok: false, error: "project not resolved" };
+    if (resolved) {
+        if (isWorkflowEnforcementDisabled()) {
+            workflowLoaded = {
+                ok: true,
+                error: `workflow checks disabled via ${workflowEnforcementEnvHint()}`,
+            };
+        }
+        else {
+            try {
+                const workflowValidation = await validateWorkflowAtPath(resolved.gitRoot);
+                workflowLoaded = workflowValidation.ok
+                    ? { ok: true }
+                    : {
+                        ok: false,
+                        error: workflowValidation.diagnostics
+                            .filter((diagnostic) => diagnostic.severity === "ERROR")
+                            .map((diagnostic) => `${diagnostic.code}:${diagnostic.path}`)
+                            .join(", "),
+                    };
+                if (!workflowValidation.ok) {
+                    harnessHealthReasons.push("workflow_contract_invalid");
+                    nextActions.push({
+                        command: "agentplane workflow build --validate --dry-run",
+                        reason: "workflow contract is invalid",
+                    });
+                }
+            }
+            catch (err) {
+                const message = compactError(err);
+                workflowLoaded = { ok: false, error: message };
+                harnessHealthReasons.push("workflow_contract_unreadable");
+                nextActions.push({
+                    command: "agentplane workflow build --validate --dry-run",
+                    reason: `cannot validate workflow (${message})`,
+                });
+            }
+        }
+    }
+    let workingTree = {
+        ok: false,
+        error: "project not resolved",
+    };
+    let branch = {
+        ok: false,
+        error: "project not resolved",
+    };
+    if (resolved) {
+        try {
+            const git = new GitContext({ gitRoot: resolved.gitRoot });
+            const [staged, unstagedTracked] = await Promise.all([
+                git.statusStagedPaths(),
+                git.statusUnstagedTrackedPaths(),
+            ]);
+            workingTree = { ok: true, value: staged.length === 0 && unstagedTracked.length === 0 };
+            if (!workingTree.value) {
+                harnessHealthReasons.push("working_tree_dirty");
+                nextActions.push({
+                    command: "git status --short --untracked-files=no",
+                    reason: "tracked changes detected",
+                });
+            }
+        }
+        catch (err) {
+            const message = compactError(err);
+            workingTree = { ok: false, error: message };
+            harnessHealthReasons.push("working_tree_unreadable");
+            nextActions.push({
+                command: "git status --short --untracked-files=no",
+                reason: `cannot inspect git status (${message})`,
+            });
+        }
+        try {
+            branch = { ok: true, value: await gitCurrentBranch(resolved.gitRoot) };
+        }
+        catch (err) {
+            branch = { ok: false, error: compactError(err) };
+        }
+    }
+    return {
+        mode: opts.mode,
+        project_detected: resolved !== null,
+        config_loaded: configLoaded,
+        quickstart_loaded: quickstartLoaded,
+        workflow_loaded: workflowLoaded,
+        task_list_loaded: taskListLoaded,
+        working_tree_clean_tracked: workingTree,
+        current_branch: branch,
+        workflow_mode: inferWorkflowMode(config),
+        approvals: inferApprovals(config),
+        harness_health: {
+            status: harnessHealthReasons.length === 0 ? "ok" : "warn",
+            reasons: dedupeStrings(harnessHealthReasons),
+        },
+        outside_repo_needed: false,
+        next_actions: nextActions,
+    };
+}
+export const preflightSpec = {
+    id: ["preflight"],
+    group: "Core",
+    summary: "Run aggregated preflight checks and print a deterministic readiness report.",
+    options: [
+        {
+            kind: "string",
+            name: "mode",
+            valueHint: "<quick|full>",
+            choices: ["quick", "full"],
+            default: "quick",
+            description: "Preflight depth. quick skips backend task-list probe; full includes backend readiness.",
+        },
+        {
+            kind: "boolean",
+            name: "full",
+            default: false,
+            description: "Shortcut for --mode full.",
+        },
+        {
+            kind: "boolean",
+            name: "json",
+            default: false,
+            description: "Emit machine-readable JSON report.",
+        },
+    ],
+    examples: [
+        { cmd: "agentplane preflight --json", why: "Produce one-shot agent-readable preflight." },
+        {
+            cmd: "agentplane preflight --json --mode full",
+            why: "Run full preflight including backend task-list probe.",
+        },
+    ],
+    parse: (raw) => ({
+        json: raw.opts.json === true,
+        mode: raw.opts.full === true ? "full" : (raw.opts.mode ?? "quick"),
+    }),
+};
+async function cmdPreflight(opts) {
+    return wrapCommand({ command: "preflight", rootOverride: opts.rootOverride }, async () => {
+        const report = await buildPreflightReport({
+            cwd: opts.cwd,
+            rootOverride: opts.rootOverride,
+            mode: opts.mode,
+        });
+        if (opts.json) {
+            output.json(report);
+            return 0;
+        }
+        const lines = [
+            "Preflight Summary",
+            `- mode: ${report.mode}`,
+            `- project detected: ${report.project_detected ? "yes" : "no"}`,
+            `- config loaded: ${probeYesNo(report.config_loaded)}`,
+            `- quickstart loaded: ${probeYesNo(report.quickstart_loaded)}`,
+            `- workflow loaded: ${probeYesNo(report.workflow_loaded)}`,
+            `- task list loaded: ${probeYesNo(report.task_list_loaded)}`,
+            `- working tree clean (tracked-only): ${probeValueOrUnknown(report.working_tree_clean_tracked)}`,
+            `- current git branch: ${probeValueOrUnknown(report.current_branch)}`,
+            `- workflow_mode: ${report.workflow_mode}`,
+            `- harness engeneering health: ${report.harness_health.status}`,
+        ];
+        if (report.harness_health.reasons.length > 0) {
+            lines.push(`  - reasons: ${report.harness_health.reasons.join(", ")}`);
+        }
+        lines.push("- approval gates:", `  - require_plan: ${String(report.approvals.require_plan)}`, `  - require_verify: ${String(report.approvals.require_verify)}`, `  - require_network: ${String(report.approvals.require_network)}`, "- outside-repo: not needed");
+        if (report.next_actions.length > 0) {
+            lines.push("Next actions:");
+            for (const action of report.next_actions) {
+                lines.push(`- ${action.command}: ${action.reason}`);
+            }
+        }
+        output.lines(lines);
+        return 0;
+    });
+}
+export const runPreflight = (ctx, parsed) => {
+    return cmdPreflight({
+        cwd: ctx.cwd,
+        rootOverride: ctx.rootOverride,
+        json: parsed.json,
+        mode: parsed.mode,
+    });
+};

package/dist/cli/run-cli/commands/core/quickstart.d.ts

@@ -0,0 +1,8 @@
+import type { CommandHandler, CommandSpec } from "../../../spec/spec.js";
+type QuickstartParsed = {
+    json: boolean;
+};
+export declare const quickstartSpec: CommandSpec<QuickstartParsed>;
+export declare const runQuickstart: CommandHandler<QuickstartParsed>;
+export {};
+//# sourceMappingURL=quickstart.d.ts.map

package/dist/cli/run-cli/commands/core/quickstart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quickstart.d.ts","sourceRoot":"","sources":["../../../../../src/cli/run-cli/commands/core/quickstart.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAMzE,KAAK,gBAAgB,GAAG;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAE1C,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,gBAAgB,CAcxD,CAAC;AA4BF,eAAO,MAAM,aAAa,EAAE,cAAc,CAAC,gBAAgB,CAE1D,CAAC"}