agentplane 0.3.12 → 0.3.13

package/dist/commands/pr/open.js

@@ -3,6 +3,8 @@ import { mapBackendError } from "../../cli/error-map.js";
 import { exitCodeForError } from "../../cli/exit-codes.js";
 import { createCliEmitter } from "../../cli/output.js";
 import { CliError } from "../../shared/errors.js";
+import { execFileAsync, gitEnv } from "../shared/git.js";
+import { gitBranchUpstream } from "../shared/git-ops.js";
 import { loadCommandContext } from "../shared/task-backend.js";
 import { maybeAutoCommitTaskPrArtifacts } from "./internal/auto-commit.js";
 import { syncPrArtifacts } from "./internal/sync.js";
@@ -16,6 +18,24 @@ function prOpenOutcomeDetails(meta, openOutcome) {
     }
     return "local PR artifacts synced; remote PR creation staged";
 }
+async function pushTaskBranchUpstreamIfConfigured(opts) {
+    const upstream = await gitBranchUpstream(opts.gitRoot, opts.branch);
+    const trimmed = upstream?.trim() ?? "";
+    if (!trimmed)
+        return false;
+    const slashIndex = trimmed.indexOf("/");
+    if (slashIndex <= 0 || slashIndex === trimmed.length - 1)
+        return false;
+    const remote = trimmed.slice(0, slashIndex);
+    const upstreamBranch = trimmed.slice(slashIndex + 1);
+    if (!remote || !upstreamBranch)
+        return false;
+    await execFileAsync("git", ["push", "--no-verify", remote, `HEAD:${upstreamBranch}`], {
+        cwd: opts.gitRoot,
+        env: gitEnv(),
+    });
+    return true;
+}
 export async function cmdPrOpen(opts) {
     try {
         const output = createCliEmitter();
@@ -27,25 +47,43 @@ export async function cmdPrOpen(opts) {
                 message: "Invalid value for --author.",
             });
         }
-        const { meta, prDir, resolved, openOutcome } = await syncPrArtifacts({
-            ctx: opts.ctx,
+        const commandCtx = opts.ctx ??
+            (await loadCommandContext({ cwd: opts.cwd, rootOverride: opts.rootOverride ?? null }));
+        const initialSync = await syncPrArtifacts({
+            ctx: commandCtx,
             cwd: opts.cwd,
             rootOverride: opts.rootOverride,
             taskId: opts.taskId,
             mode: "open",
             author,
             branch: opts.branch,
-            remoteMode: opts.syncOnly ? "sync-only" : "auto",
+            remoteMode: "sync-only",
         });
-        const commandCtx = opts.ctx ??
-            (await loadCommandContext({ cwd: opts.cwd, rootOverride: opts.rootOverride ?? null }));
-        if (meta.branch) {
-            await maybeAutoCommitTaskPrArtifacts({
+        const didAutoCommit = initialSync.meta.branch
+            ? await maybeAutoCommitTaskPrArtifacts({
                 ctx: commandCtx,
                 taskId: opts.taskId,
-                branch: meta.branch,
+                branch: initialSync.meta.branch,
+            })
+            : false;
+        if (didAutoCommit && !opts.syncOnly && initialSync.meta.branch) {
+            await pushTaskBranchUpstreamIfConfigured({
+                gitRoot: commandCtx.resolvedProject.gitRoot,
+                branch: initialSync.meta.branch,
             });
         }
+        const { meta, prDir, resolved, openOutcome } = opts.syncOnly
+            ? initialSync
+            : await syncPrArtifacts({
+                ctx: commandCtx,
+                cwd: opts.cwd,
+                rootOverride: opts.rootOverride,
+                taskId: opts.taskId,
+                mode: "open",
+                author,
+                branch: opts.branch,
+                remoteMode: "auto",
+            });
         output.success("pr open", path.relative(resolved.gitRoot, prDir), prOpenOutcomeDetails(meta, openOutcome ?? null));
         return 0;
     }

package/dist/commands/recipes/active.command.d.ts

@@ -0,0 +1,7 @@
+import type { CommandHandler, CommandSpec } from "../../cli/spec/spec.js";
+export type RecipesActiveParsed = {
+    full: boolean;
+};
+export declare const recipesActiveSpec: CommandSpec<RecipesActiveParsed>;
+export declare const runRecipesActive: CommandHandler<RecipesActiveParsed>;
+//# sourceMappingURL=active.command.d.ts.map

package/dist/commands/recipes/active.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"active.command.d.ts","sourceRoot":"","sources":["../../../src/commands/recipes/active.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAI1E,MAAM,MAAM,mBAAmB,GAAG;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAEpD,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,mBAAmB,CAS9D,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,cAAc,CAAC,mBAAmB,CAC2B,CAAC"}

package/dist/commands/recipes/active.command.js

@@ -0,0 +1,12 @@
+import { cmdRecipeActiveParsed } from "../recipes.js";
+export const recipesActiveSpec = {
+    id: ["recipes", "active"],
+    group: "Recipes",
+    summary: "List active project overlays.",
+    options: [
+        { kind: "boolean", name: "full", default: false, description: "Print full JSON payload." },
+    ],
+    examples: [{ cmd: "agentplane recipes active", why: "Show overlays active for the project." }],
+    parse: (raw) => ({ full: raw.opts.full === true }),
+};
+export const runRecipesActive = (ctx, parsed) => cmdRecipeActiveParsed({ cwd: ctx.cwd, rootOverride: ctx.rootOverride, full: parsed.full });

package/dist/commands/recipes/add.command.d.ts

@@ -0,0 +1,8 @@
+import type { CommandHandler, CommandSpec } from "../../cli/spec/spec.js";
+export type RecipesAddParsed = {
+    recipeRef: string;
+    mode?: "copy" | "link";
+};
+export declare const recipesAddSpec: CommandSpec<RecipesAddParsed>;
+export declare const runRecipesAdd: CommandHandler<RecipesAddParsed>;
+//# sourceMappingURL=add.command.d.ts.map

package/dist/commands/recipes/add.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"add.command.d.ts","sourceRoot":"","sources":["../../../src/commands/recipes/add.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAI1E,MAAM,MAAM,gBAAgB,GAAG;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACxB,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,gBAAgB,CAyBxD,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,cAAc,CAAC,gBAAgB,CAMvD,CAAC"}

package/dist/commands/recipes/add.command.js

@@ -0,0 +1,33 @@
+import { cmdRecipeAddParsed } from "../recipes.js";
+export const recipesAddSpec = {
+    id: ["recipes", "add"],
+    group: "Recipes",
+    summary: "Vendor a cached recipe into the current project.",
+    args: [{ name: "recipe", required: true, valueHint: "<id|id@version>" }],
+    options: [
+        {
+            kind: "string",
+            name: "mode",
+            valueHint: "<copy|link>",
+            choices: ["copy", "link"],
+            description: "Materialization mode for the project-local package.",
+        },
+    ],
+    examples: [
+        { cmd: "agentplane recipes add tdd", why: "Vendor the latest cached recipe into the project." },
+        {
+            cmd: "agentplane recipes add tdd@1.2.0 --mode link",
+            why: "Link a cached recipe into the project for local recipe development.",
+        },
+    ],
+    parse: (raw) => ({
+        recipeRef: String(raw.args.recipe ?? "").trim(),
+        mode: raw.opts.mode === "copy" || raw.opts.mode === "link" ? raw.opts.mode : undefined,
+    }),
+};
+export const runRecipesAdd = (ctx, parsed) => cmdRecipeAddParsed({
+    cwd: ctx.cwd,
+    rootOverride: ctx.rootOverride,
+    recipeRef: parsed.recipeRef,
+    mode: parsed.mode,
+});

package/dist/commands/recipes/detach.command.d.ts

@@ -0,0 +1,7 @@
+import type { CommandHandler, CommandSpec } from "../../cli/spec/spec.js";
+export type RecipesDetachParsed = {
+    id: string;
+};
+export declare const recipesDetachSpec: CommandSpec<RecipesDetachParsed>;
+export declare const runRecipesDetach: CommandHandler<RecipesDetachParsed>;
+//# sourceMappingURL=detach.command.d.ts.map

package/dist/commands/recipes/detach.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detach.command.d.ts","sourceRoot":"","sources":["../../../src/commands/recipes/detach.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAI1E,MAAM,MAAM,mBAAmB,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjD,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,mBAAmB,CAY9D,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,cAAc,CAAC,mBAAmB,CAK7D,CAAC"}

package/dist/commands/recipes/detach.command.js

@@ -0,0 +1,19 @@
+import { cmdRecipeDetachParsed } from "../recipes.js";
+export const recipesDetachSpec = {
+    id: ["recipes", "detach"],
+    group: "Recipes",
+    summary: "Convert a linked vendored recipe into a project-local copy.",
+    args: [{ name: "id", required: true, valueHint: "<id>" }],
+    examples: [
+        {
+            cmd: "agentplane recipes detach tdd",
+            why: "Freeze a linked recipe into a portable project copy before sharing the repo.",
+        },
+    ],
+    parse: (raw) => ({ id: String(raw.args.id ?? "").trim() }),
+};
+export const runRecipesDetach = (ctx, parsed) => cmdRecipeDetachParsed({
+    cwd: ctx.cwd,
+    rootOverride: ctx.rootOverride,
+    id: parsed.id,
+});

package/dist/commands/recipes/disable.command.d.ts

@@ -0,0 +1,7 @@
+import type { CommandHandler, CommandSpec } from "../../cli/spec/spec.js";
+export type RecipesDisableParsed = {
+    id: string;
+};
+export declare const recipesDisableSpec: CommandSpec<RecipesDisableParsed>;
+export declare const runRecipesDisable: CommandHandler<RecipesDisableParsed>;
+//# sourceMappingURL=disable.command.d.ts.map

package/dist/commands/recipes/disable.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"disable.command.d.ts","sourceRoot":"","sources":["../../../src/commands/recipes/disable.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAI1E,MAAM,MAAM,oBAAoB,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAElD,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,oBAAoB,CAOhE,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,cAAc,CAAC,oBAAoB,CACsB,CAAC"}

package/dist/commands/recipes/disable.command.js

@@ -0,0 +1,10 @@
+import { cmdRecipeDisableParsed } from "../recipes.js";
+export const recipesDisableSpec = {
+    id: ["recipes", "disable"],
+    group: "Recipes",
+    summary: "Disable an active project overlay for the current project.",
+    args: [{ name: "id", required: true, valueHint: "<recipe-id>" }],
+    examples: [{ cmd: "agentplane recipes disable tdd", why: "Deactivate an overlay." }],
+    parse: (raw) => ({ id: String(raw.args.id ?? "").trim() }),
+};
+export const runRecipesDisable = (ctx, parsed) => cmdRecipeDisableParsed({ cwd: ctx.cwd, rootOverride: ctx.rootOverride, id: parsed.id });

package/dist/commands/recipes/enable.command.d.ts

@@ -0,0 +1,7 @@
+import type { CommandHandler, CommandSpec } from "../../cli/spec/spec.js";
+export type RecipesEnableParsed = {
+    id: string;
+};
+export declare const recipesEnableSpec: CommandSpec<RecipesEnableParsed>;
+export declare const runRecipesEnable: CommandHandler<RecipesEnableParsed>;
+//# sourceMappingURL=enable.command.d.ts.map

package/dist/commands/recipes/enable.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enable.command.d.ts","sourceRoot":"","sources":["../../../src/commands/recipes/enable.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAI1E,MAAM,MAAM,mBAAmB,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjD,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,mBAAmB,CAO9D,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,cAAc,CAAC,mBAAmB,CACuB,CAAC"}

package/dist/commands/recipes/enable.command.js

@@ -0,0 +1,10 @@
+import { cmdRecipeEnableParsed } from "../recipes.js";
+export const recipesEnableSpec = {
+    id: ["recipes", "enable"],
+    group: "Recipes",
+    summary: "Enable an installed project overlay for the current project.",
+    args: [{ name: "id", required: true, valueHint: "<recipe-id>" }],
+    examples: [{ cmd: "agentplane recipes enable tdd", why: "Activate an installed overlay." }],
+    parse: (raw) => ({ id: String(raw.args.id ?? "").trim() }),
+};
+export const runRecipesEnable = (ctx, parsed) => cmdRecipeEnableParsed({ cwd: ctx.cwd, rootOverride: ctx.rootOverride, id: parsed.id });

package/dist/commands/recipes/explain-active.command.d.ts

@@ -0,0 +1,5 @@
+import type { CommandHandler, CommandSpec } from "../../cli/spec/spec.js";
+export type RecipesExplainActiveParsed = Record<string, never>;
+export declare const recipesExplainActiveSpec: CommandSpec<RecipesExplainActiveParsed>;
+export declare const runRecipesExplainActive: CommandHandler<RecipesExplainActiveParsed>;
+//# sourceMappingURL=explain-active.command.d.ts.map

package/dist/commands/recipes/explain-active.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain-active.command.d.ts","sourceRoot":"","sources":["../../../src/commands/recipes/explain-active.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAI1E,MAAM,MAAM,0BAA0B,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAE/D,eAAO,MAAM,wBAAwB,EAAE,WAAW,CAAC,0BAA0B,CAQ5E,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,cAAc,CAAC,0BAA0B,CACC,CAAC"}

package/dist/commands/recipes/explain-active.command.js

@@ -0,0 +1,11 @@
+import { cmdRecipeExplainActiveParsed } from "../recipes.js";
+export const recipesExplainActiveSpec = {
+    id: ["recipes", "explain-active"],
+    group: "Recipes",
+    summary: "Print the compiled active overlay bundle.",
+    examples: [
+        { cmd: "agentplane recipes explain-active", why: "Inspect compiled overlay runtime data." },
+    ],
+    parse: () => ({}),
+};
+export const runRecipesExplainActive = (ctx) => cmdRecipeExplainActiveParsed({ cwd: ctx.cwd, rootOverride: ctx.rootOverride });

package/dist/commands/recipes/explain.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"explain.command.d.ts","sourceRoot":"","sources":["../../../src/commands/recipes/explain.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAG1E,MAAM,MAAM,oBAAoB,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAElD,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,oBAAoB,CAOhE,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,cAAc,CAAC,oBAAoB,CACiB,CAAC"}
+{"version":3,"file":"explain.command.d.ts","sourceRoot":"","sources":["../../../src/commands/recipes/explain.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAG1E,MAAM,MAAM,oBAAoB,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAElD,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,oBAAoB,CAShE,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,cAAc,CAAC,oBAAoB,CACiB,CAAC"}

package/dist/commands/recipes/explain.command.js

@@ -2,9 +2,11 @@ import { cmdRecipeExplainParsed } from "../recipes.js";
 export const recipesExplainSpec = {
     id: ["recipes", "explain"],
     group: "Recipes",
-    summary: "Show detailed info for an installed recipe.",
+    summary: "Show detailed info for a vendored recipe.",
     args: [{ name: "id", required: true, valueHint: "<id>" }],
-    examples: [{ cmd: "agentplane recipes explain viewer", why: "Show detailed recipe info." }],
+    examples: [
+        { cmd: "agentplane recipes explain viewer", why: "Show detailed project-local recipe info." },
+    ],
     parse: (raw) => ({ id: String(raw.args.id ?? "") }),
 };
 export const runRecipesExplain = (ctx, p) => cmdRecipeExplainParsed({ cwd: ctx.cwd, rootOverride: ctx.rootOverride, id: p.id });

package/dist/commands/recipes/impl/apply.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../../../src/commands/recipes/impl/apply.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAErE,wBAAsB,aAAa,CAAC,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAarF;AAkBD,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,QAAQ,EAAE,cAAc,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4BhB;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,QAAQ,EAAE,cAAc,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,kBAAkB,CAAC;CAChC,GAAG,OAAO,CAAC,IAAI,CAAC,CAgDhB;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,QAAQ,EAAE,cAAc,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,IAAI,CAAC,CA0BhB"}
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../../../src/commands/recipes/impl/apply.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAErE,wBAAsB,aAAa,CAAC,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAarF;AAyBD,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,QAAQ,EAAE,cAAc,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,IAAI,CAAC,CAmChB;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,QAAQ,EAAE,cAAc,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,kBAAkB,CAAC;CAChC,GAAG,OAAO,CAAC,IAAI,CAAC,CAuDhB;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,QAAQ,EAAE,cAAc,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,IAAI,CAAC,CA0BhB"}

package/dist/commands/recipes/impl/apply.js

@@ -1,4 +1,4 @@
-import { cp, mkdir, readFile, readdir, rename, rm } from "node:fs/promises";
+import { cp, mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { exitCodeForError } from "../../../cli/exit-codes.js";
 import { fileExists, getPathKind } from "../../../cli/fs-utils.js";
@@ -24,22 +24,29 @@ export async function moveRecipeDir(opts) {
         throw err;
     }
 }
-async function readRecipeJsonObject(recipeDir, relativePath, label) {
+function isMarkdownAssetPath(relativePath) {
+    const normalized = relativePath.trim().toLowerCase();
+    return normalized.endsWith(".md") || normalized.endsWith(".markdown");
+}
+async function readRecipeMarkdownAsset(recipeDir, relativePath, label) {
     const sourcePath = path.join(recipeDir, relativePath);
     if (!(await fileExists(sourcePath))) {
         throw new Error(missingFileMessage(label, relativePath));
     }
-    const raw = JSON.parse(await readFile(sourcePath, "utf8"));
-    if (!isRecord(raw)) {
-        throw new Error(invalidFieldMessage(label, "JSON object", relativePath));
+    if (!isMarkdownAssetPath(relativePath)) {
+        throw new Error(invalidFieldMessage(label, "markdown file (*.md)", relativePath));
+    }
+    const raw = await readFile(sourcePath, "utf8");
+    if (!raw.trim()) {
+        throw new Error(invalidFieldMessage(label, "non-empty markdown document", relativePath));
     }
 }
 export async function validateRecipeAssets(opts) {
     for (const skill of opts.manifest.skills ?? []) {
-        await readRecipeJsonObject(opts.recipeDir, skill.file, "recipe skill file");
+        await readRecipeMarkdownAsset(opts.recipeDir, skill.file, "recipe skill file");
     }
     for (const agent of opts.manifest.agents ?? []) {
-        await readRecipeJsonObject(opts.recipeDir, agent.file, "recipe agent file");
+        await readRecipeMarkdownAsset(opts.recipeDir, agent.file, "recipe agent file");
     }
     for (const tool of opts.manifest.tools ?? []) {
         const entrypointPath = path.join(opts.recipeDir, tool.entrypoint);
@@ -47,6 +54,12 @@ export async function validateRecipeAssets(opts) {
             throw new Error(missingFileMessage("recipe tool entrypoint", tool.entrypoint));
         }
     }
+    for (const prompt of opts.manifest.prompts ?? []) {
+        const sourcePath = path.join(opts.recipeDir, prompt.file);
+        if (!(await fileExists(sourcePath))) {
+            throw new Error(missingFileMessage("overlay prompt file", prompt.file));
+        }
+    }
     for (const scenario of opts.manifest.scenarios ?? []) {
         const sourcePath = path.join(opts.recipeDir, scenario.file);
         if (!(await fileExists(sourcePath))) {
@@ -75,13 +88,16 @@ export async function applyRecipeAgents(opts) {
         if (!(await fileExists(sourcePath))) {
             throw new Error(missingFileMessage("recipe agent file", rawFile));
         }
-        const rawAgent = JSON.parse(await readFile(sourcePath, "utf8"));
-        if (!isRecord(rawAgent)) {
-            throw new Error(invalidFieldMessage("recipe agent file", "JSON object", rawFile));
+        if (!isMarkdownAssetPath(rawFile)) {
+            throw new Error(invalidFieldMessage("recipe agent file", "markdown file (*.md)", rawFile));
+        }
+        const rawAgent = await readFile(sourcePath, "utf8");
+        if (!rawAgent.trim()) {
+            throw new Error(invalidFieldMessage("recipe agent file", "non-empty markdown document", rawFile));
         }
         const baseId = `${opts.manifest.id}__${agentId}`;
         let targetId = baseId;
-        let targetPath = path.join(agentsDir, `${targetId}.json`);
+        let targetPath = path.join(agentsDir, `${targetId}.md`);
         if (await getPathKind(targetPath)) {
             if (opts.onConflict === "fail") {
                 throw new CliError({
@@ -94,13 +110,16 @@ export async function applyRecipeAgents(opts) {
                 let counter = 1;
                 while (await getPathKind(targetPath)) {
                     targetId = `${baseId}__${counter}`;
-                    targetPath = path.join(agentsDir, `${targetId}.json`);
+                    targetPath = path.join(agentsDir, `${targetId}.md`);
                     counter += 1;
                 }
             }
         }
-        rawAgent.id = targetId;
-        await writeJsonStableIfChanged(targetPath, rawAgent);
+        const namespacedHeader = `# Agent: ${targetId}\n\n`;
+        const content = rawAgent.startsWith("# Agent:")
+            ? rawAgent
+            : `${namespacedHeader}${rawAgent.trimStart()}`;
+        await writeFile(targetPath, content, "utf8");
     }
 }
 export async function applyRecipeScenarios(opts) {

package/dist/commands/recipes/impl/commands/active.d.ts

@@ -0,0 +1,6 @@
+export declare function cmdRecipeActiveParsed(opts: {
+    cwd: string;
+    rootOverride?: string;
+    full: boolean;
+}): Promise<number>;
+//# sourceMappingURL=active.d.ts.map

package/dist/commands/recipes/impl/commands/active.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"active.d.ts","sourceRoot":"","sources":["../../../../../src/commands/recipes/impl/commands/active.ts"],"names":[],"mappings":"AASA,wBAAsB,qBAAqB,CAAC,IAAI,EAAE;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,OAAO,CAAC;CACf,GAAG,OAAO,CAAC,MAAM,CAAC,CA2ClB"}

package/dist/commands/recipes/impl/commands/active.js

@@ -0,0 +1,46 @@
+import { resolveProject } from "@agentplaneorg/core";
+import { mapCoreError } from "../../../../cli/error-map.js";
+import { emptyStateMessage } from "../../../../cli/output.js";
+import { CliError } from "../../../../shared/errors.js";
+import { readActiveRecipeIds } from "../overlay-project.js";
+import { readProjectInstalledRecipes } from "../project-installed-recipes.js";
+export async function cmdRecipeActiveParsed(opts) {
+    try {
+        const project = await resolveProject({
+            cwd: opts.cwd,
+            rootOverride: opts.rootOverride ?? null,
+        });
+        const [activeIds, installed] = await Promise.all([
+            readActiveRecipeIds(project),
+            readProjectInstalledRecipes(project),
+        ]);
+        const active = activeIds
+            .map((id) => installed.recipes.find((entry) => entry.id === id))
+            .filter(Boolean);
+        if (active.length === 0) {
+            process.stdout.write(`${emptyStateMessage("active overlays")}\n`);
+            return 0;
+        }
+        if (opts.full) {
+            process.stdout.write(`${JSON.stringify({
+                schema_version: 1,
+                active: active.map((entry) => ({
+                    id: entry.id,
+                    version: entry.version,
+                    kind: entry.manifest.kind,
+                    summary: entry.manifest.summary,
+                })),
+            }, null, 2)}\n`);
+            return 0;
+        }
+        for (const entry of active) {
+            process.stdout.write(`${entry.id}@${entry.version} [${entry.manifest.kind}]\n`);
+        }
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof CliError)
+            throw err;
+        throw mapCoreError(err, { command: "recipes active", root: opts.rootOverride ?? null });
+    }
+}

package/dist/commands/recipes/impl/commands/add.d.ts

@@ -0,0 +1,7 @@
+export declare function cmdRecipeAddParsed(opts: {
+    cwd: string;
+    rootOverride?: string;
+    recipeRef: string;
+    mode?: "copy" | "link";
+}): Promise<number>;
+//# sourceMappingURL=add.d.ts.map

package/dist/commands/recipes/impl/commands/add.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"add.d.ts","sourceRoot":"","sources":["../../../../../src/commands/recipes/impl/commands/add.ts"],"names":[],"mappings":"AAqCA,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC7C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACxB,GAAG,OAAO,CAAC,MAAM,CAAC,CAkFlB"}

package/dist/commands/recipes/impl/commands/add.js

@@ -0,0 +1,100 @@
+import { cp, mkdir, rm, symlink } from "node:fs/promises";
+import { loadConfig, resolveProject } from "@agentplaneorg/core";
+import { mapCoreError } from "../../../../cli/error-map.js";
+import { exitCodeForError } from "../../../../cli/exit-codes.js";
+import { CliError } from "../../../../shared/errors.js";
+import { refreshProjectOverlayArtifacts } from "../overlay-project.js";
+import { readInstalledRecipesFile } from "../installed-recipes.js";
+import { normalizeRecipeTags } from "../normalize.js";
+import { hashRecipeTree } from "../project-recipe-state.js";
+import { readProjectRecipesRegistry, upsertProjectRecipeRegistryEntry, } from "../project-registry.js";
+import { resolveInstalledRecipeDir, resolveInstalledRecipesPath, resolveProjectRecipesPackagesDir, resolveProjectVendoredRecipeDir, } from "../paths.js";
+function parseRecipeRef(raw) {
+    const value = raw.trim();
+    if (!value) {
+        throw new CliError({
+            exitCode: 3,
+            code: "E_VALIDATION",
+            message: "Recipe id must not be empty",
+        });
+    }
+    const atIndex = value.lastIndexOf("@");
+    if (atIndex <= 0)
+        return { id: value };
+    return { id: value.slice(0, atIndex), version: value.slice(atIndex + 1) || undefined };
+}
+export async function cmdRecipeAddParsed(opts) {
+    try {
+        const project = await resolveProject({
+            cwd: opts.cwd,
+            rootOverride: opts.rootOverride ?? null,
+        });
+        const loaded = await loadConfig(project.agentplaneDir);
+        const requested = parseRecipeRef(opts.recipeRef);
+        const cache = await readInstalledRecipesFile(resolveInstalledRecipesPath());
+        const cachedEntries = cache.recipes
+            .filter((entry) => entry.id === requested.id)
+            .toSorted((left, right) => left.version.localeCompare(right.version));
+        const cached = requested.version
+            ? cachedEntries.find((entry) => entry.version === requested.version)
+            : cachedEntries.at(-1);
+        if (!cached) {
+            throw new CliError({
+                exitCode: exitCodeForError("E_IO"),
+                code: "E_IO",
+                message: requested.version
+                    ? `Recipe not found in global cache: ${requested.id}@${requested.version}. Run agentplane recipes install ${requested.id}@${requested.version}`
+                    : `Recipe not found in global cache: ${requested.id}. Run agentplane recipes install ${requested.id}`,
+            });
+        }
+        const materialization = opts.mode ?? (loaded.config.recipes?.storage_default === "link" ? "link" : "copy");
+        const sourceDir = resolveInstalledRecipeDir({ id: cached.id, version: cached.version });
+        const targetDir = resolveProjectVendoredRecipeDir(project, cached.id);
+        const registry = await readProjectRecipesRegistry(project);
+        const existing = registry.recipes.find((entry) => entry.id === cached.id);
+        if (existing) {
+            throw new CliError({
+                exitCode: exitCodeForError("E_USAGE"),
+                code: "E_USAGE",
+                message: existing.version === cached.version
+                    ? `Recipe already vendored: ${cached.id}@${cached.version}. Use agentplane recipes update ${cached.id} to resync it from cache.`
+                    : `Recipe already vendored: ${cached.id}@${existing.version}. Remove it first or use a dedicated update flow instead of overwriting it with recipes add.`,
+            });
+        }
+        await mkdir(resolveProjectRecipesPackagesDir(project), { recursive: true });
+        await rm(targetDir, { recursive: true, force: true });
+        await (materialization === "link"
+            ? symlink(sourceDir, targetDir, "dir")
+            : cp(sourceDir, targetDir, { recursive: true }));
+        const installedAt = new Date().toISOString();
+        const tags = normalizeRecipeTags(cached.tags ?? cached.manifest.tags ?? []);
+        const sourceSha256 = await hashRecipeTree(sourceDir);
+        const vendoredSha256 = await hashRecipeTree(targetDir);
+        await upsertProjectRecipeRegistryEntry({
+            project,
+            entry: {
+                id: cached.id,
+                version: cached.version,
+                path: `packages/${cached.id}`,
+                active: false,
+                materialization,
+                source_ref: `${cached.id}@${cached.version}`,
+                source_sha256: sourceSha256,
+                vendored_sha256: vendoredSha256,
+                installed_at: installedAt,
+                tags,
+            },
+        });
+        await refreshProjectOverlayArtifacts(project);
+        process.stdout.write(`Vendored recipe ${cached.id}@${cached.version} into project (${materialization})\n`);
+        if (materialization === "link") {
+            process.stdout.write("Warning: link mode is not portable; use `agentplane recipes detach` before sharing the repo.\n");
+        }
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof CliError)
+            throw err;
+        throw mapCoreError(err, { command: "recipes add", root: opts.rootOverride ?? null });
+    }
+}

package/dist/commands/recipes/impl/commands/detach.d.ts

@@ -0,0 +1,6 @@
+export declare function cmdRecipeDetachParsed(opts: {
+    cwd: string;
+    rootOverride?: string;
+    id: string;
+}): Promise<number>;
+//# sourceMappingURL=detach.d.ts.map

package/dist/commands/recipes/impl/commands/detach.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detach.d.ts","sourceRoot":"","sources":["../../../../../src/commands/recipes/impl/commands/detach.ts"],"names":[],"mappings":"AAgBA,wBAAsB,qBAAqB,CAAC,IAAI,EAAE;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,EAAE,EAAE,MAAM,CAAC;CACZ,GAAG,OAAO,CAAC,MAAM,CAAC,CA+ElB"}