@drunkcoding/agents-and-skills 0.0.39 → 0.0.41

package/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "tech-graph",
       "source": "./plugins/tech-graph",
       "description": "6-step wizard for technical diagrams (SVG/PNG) via fireworks-tech-graph",
-      "version": "0.0.39",
+      "version": "0.0.41",
       "category": "diagram",
       "keywords": [
         "diagram",
@@ -26,7 +26,7 @@
       "name": "html-effectiveness",
       "source": "./plugins/html-effectiveness",
       "description": "Generate self-contained interactive HTML reports from 20 upstream templates via a conversational agent.",
-      "version": "0.0.39",
+      "version": "0.0.41",
       "category": "reports",
       "keywords": [
         "html",
@@ -41,7 +41,7 @@
       "name": "plugin-validator",
       "source": "./plugins/plugin-validator",
       "description": "Orchestrated validator for Claude Code plugins — validates skills, agents, commands, and hooks across every plugin under plugins/**.",
-      "version": "0.0.39",
+      "version": "0.0.41",
       "category": "tooling",
       "keywords": [
         "validation",
@@ -57,7 +57,7 @@
       "name": "team-share",
       "source": "./plugins/team-share",
       "description": "Onboard your team with an interactive setup menu: install CodeGraph, build the Understand-Anything knowledge graph, and share Claude Code settings — run any combination, all idempotent.",
-      "version": "0.0.39",
+      "version": "0.0.41",
       "category": "tooling",
       "keywords": [
         "onboarding",
@@ -73,7 +73,7 @@
       "name": "multica-tool",
       "source": "./plugins/multica-tool",
       "description": "Export, import, and sync Multica skills, agents, and squads between workspaces.",
-      "version": "0.0.39",
+      "version": "0.0.41",
       "category": "workflow",
       "keywords": [
         "multica",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drunkcoding/agents-and-skills",
-  "version": "0.0.39",
+  "version": "0.0.41",
   "description": "Personal collection of Claude Code skills and agents, installable via `npx skills`.",
   "keywords": [
     "claude-code",

package/plugins/html-effectiveness/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "html-effectiveness",
   "displayName": "HTML Effectiveness Reports",
-  "version": "0.0.39",
+  "version": "0.0.41",
   "description": "Generate self-contained interactive HTML reports from 20 upstream templates via a conversational agent.",
   "author": {
     "name": "Steven Hoang"

package/plugins/multica-tool/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "multica-tool",
-  "version": "0.0.39",
+  "version": "0.0.41",
   "description": "Export, import, and sync Multica skills, agents, and squads between workspaces via the multica CLI."
 }

package/plugins/multica-tool/scripts/lib.mjs

@@ -104,3 +104,26 @@ export const getSquadMembers = (cli, id) =>
   (cli.json(["squad", "member", "list", id]) ?? []).map((m) => ({
     member_id: m.member_id, member_type: m.member_type, role: m.role || "member",
   }));
+
+export const listProjects = (cli) => cli.json(["project", "list"]);
+
+export function findByTitle(list, title) {
+  const hits = (list || []).filter((x) => x.title === title);
+  if (hits.length > 1) throw new Error(`Duplicate title "${title}" — refusing to guess`);
+  return hits[0] || null;
+}
+
+export function getProject(cli, id) {
+  const p = cli.json(["project", "get", id]);
+  return {
+    id: p.id, title: p.title, description: p.description ?? "",
+    icon: p.icon ?? null, priority: p.priority ?? "none", status: p.status ?? null,
+    due_date: p.due_date ?? null, start_date: p.start_date ?? null,
+    lead_id: p.lead_id ?? null, lead_type: p.lead_type ?? null,
+  };
+}
+
+export const getProjectResources = (cli, id) =>
+  (cli.json(["project", "resource", "list", id]) ?? []).map((r) => ({
+    resource_type: r.resource_type, resource_ref: r.resource_ref, label: r.label ?? null,
+  }));

package/plugins/multica-tool/scripts/multica-export.mjs

@@ -1,7 +1,7 @@
 import * as nodeFs from "node:fs";
 import { spawnSync } from "node:child_process";
 import { dirname } from "node:path";
-import { slugify, getSkill, getAgent, getAgentCustomEnv, getSquad, getSquadMembers, listRuntimes, listSkills, listAgents, listSquads, makeCli, realExec, requireAuth, resolveWorkspaceId } from "./lib.mjs";
+import { slugify, getSkill, getAgent, getAgentCustomEnv, getSquad, getSquadMembers, listRuntimes, listSkills, listAgents, listSquads, listProjects, getProject, getProjectResources, makeCli, realExec, requireAuth, resolveWorkspaceId } from "./lib.mjs";
 
 const nonEmpty = (v) => v && typeof v === "object" && Object.keys(v).length > 0;
 
@@ -31,7 +31,7 @@ export function redactAgent(a) {
   // a is a normalized agent from getAgent, with `custom_env`/
   // `custom_env_fetch_failed` attached by the caller (collectAgent) — getAgent
   // itself never fetches custom_env, since it requires a separate audited call.
-  const { id, has_custom_env, mcp_config_redacted, custom_env_fetch_failed, mcp_config, custom_env, skills, runtime_id, ...rest } = a;
+  const { id, has_custom_env, mcp_config_redacted, custom_env_fetch_failed, mcp_config, custom_env, skills, runtime_id, instructions, ...rest } = a;
   const mcpUsable = !mcp_config_redacted && nonEmpty(mcp_config);
   const envUsable = !custom_env_fetch_failed && nonEmpty(custom_env);
   // mcp_config_redacted / custom_env_fetch_failed alone still flag hadSecrets even
@@ -39,10 +39,10 @@ export function redactAgent(a) {
   // but couldn't be captured, not just silently see an empty bundle.
   const hadSecrets = mcpUsable || envUsable || !!mcp_config_redacted || !!custom_env_fetch_failed;
   return {
-    // source_id lets import-time mention rewriting map stale `mention://agent/<id>`
-    // links (in this or another agent's/squad's instructions) to the new id.
     record: {
       ...rest,
+      // source_id lets import-time mention rewriting map stale `mention://agent/<id>`
+      // links (in this or another agent's/squad's instructions) to the new id.
       source_id: id,
       source_runtime_id: runtime_id,
       skill_names: [],
@@ -51,21 +51,36 @@ export function redactAgent(a) {
       had_secrets: hadSecrets,
     },
     hadSecrets,
+    // instructions are written to a sibling .md by the caller (see avatar_file),
+    // never embedded in the JSON record.
+    instructions: instructions ?? "",
   };
 }
 
-export function buildManifest({ scope, sourceWorkspaceId, skills, agents, squads }) {
+export function buildManifest({ scope, sourceWorkspaceId, skills, agents, squads, projects }) {
   const seenSkills = new Map();
   for (const s of skills) if (!seenSkills.has(s.name)) seenSkills.set(s.name, s);
   const seenAgents = new Map();
   for (const a of agents) if (!seenAgents.has(a.name)) seenAgents.set(a.name, a);
+  const seenProjects = new Map();
+  for (const p of projects ?? []) if (!seenProjects.has(p.title)) seenProjects.set(p.title, p);
   return {
     version: "1",
     scope,
     source_workspace_id: sourceWorkspaceId,
     skills: [...seenSkills.values()].map((s) => ({ name: s.name, dir: `skills/${slugify(s.name)}`, source_id: s.source_id })),
     agents: [...seenAgents.values()].map((a) => ({ name: a.name, file: `agents/${slugify(a.name)}.json`, source_id: a.source_id, source_runtime_id: a.source_runtime_id, source_runtime_provider: a.source_runtime_provider ?? null, skill_names: a.skill_names, had_secrets: !!a.had_secrets })),
-    squads: (squads ?? []).map((squad) => ({ name: squad.name, file: `squads/${slugify(squad.name)}.json`, description: squad.description ?? "", instructions: squad.instructions ?? "", avatar_url: squad.avatar_url ?? null, leader_name: squad.leader_name, members: squad.members })),
+    squads: (squads ?? []).map((squad) => {
+      const file = `squads/${slugify(squad.name)}.json`;
+      const entry = { name: squad.name, file, description: squad.description ?? "", avatar_url: squad.avatar_url ?? null, leader_name: squad.leader_name, members: squad.members };
+      // Instructions go to a sibling .md (see squad write loop); only referenced when non-empty.
+      if (squad.instructions) entry.instructions_file = file.replace(/\.json$/, ".md");
+      return entry;
+    }),
+    projects: [...seenProjects.values()].map((p) => ({
+      title: p.title, file: `projects/${slugify(p.title)}.json`,
+      source_id: p.source_id, lead_name: p.lead_name ?? null, lead_type: p.lead_type ?? null,
+    })),
   };
 }
 
@@ -97,10 +112,27 @@ function collectAgent(cli, id, agentsById, skills, providerById) {
   return entry;
 }
 
+// Collect a project's portable metadata + its lead agent (bundled, like a squad
+// leader) and github_repo/other resources. Returns the project bundle record.
+function collectProject(cli, id, agentsById, skills, providerById) {
+  const p = getProject(cli, id);
+  let lead_name = null;
+  if (p.lead_type === "agent" && p.lead_id) {
+    lead_name = collectAgent(cli, p.lead_id, agentsById, skills, providerById).raw.name;
+  }
+  return {
+    title: p.title, description: p.description, icon: p.icon,
+    priority: p.priority, status: p.status, due_date: p.due_date, start_date: p.start_date,
+    source_id: id, lead_type: p.lead_type, lead_name, lead_source_id: p.lead_id,
+    resources: getProjectResources(cli, id),
+  };
+}
+
 export function exportResource({ cli, scope, ids, outDir, sourceWorkspaceId, fs = nodeFs, download = fetchBinary }) {
   const skills = new Map();       // name -> normalized skill
   const agentsById = new Map();   // id   -> { raw, red, skill_names }
   const squads = [];
+  const projects = [];
   // Lazy + memoized: only fetched when an agent is actually collected (skips
   // the extra CLI call on skill-only exports).
   let providerById = null;
@@ -123,10 +155,26 @@ export function exportResource({ cli, scope, ids, outDir, sourceWorkspaceId, fs
   if (scope === "skill") collectSkill(cli, ids.skillId, skills);
   else if (scope === "agent") collectAgent(cli, ids.agentId, agentsById, skills, getProviderById());
   else if (scope === "squad") squads.push(collectOneSquad(ids.squadId));
+  else if (scope === "project") projects.push(collectProject(cli, ids.projectId, agentsById, skills, getProviderById()));
+  else if (scope === "projects") for (const p of listProjects(cli)) projects.push(collectProject(cli, p.id, agentsById, skills, getProviderById()));
   else if (scope === "all") {
     for (const s of listSkills(cli)) collectSkill(cli, s.id, skills);
     for (const a of listAgents(cli)) collectAgent(cli, a.id, agentsById, skills, getProviderById());
     for (const sq of listSquads(cli)) squads.push(collectOneSquad(sq.id));
+    for (const p of listProjects(cli)) projects.push(collectProject(cli, p.id, agentsById, skills, getProviderById()));
+  }
+
+  // Orphan-skill cleanup: drop skills that no exported agent references via its
+  // skill_names. Only `all` ever produces these — standalone workspace skills
+  // from listSkills that no agent uses. Skipped for `skill` scope: its one
+  // skill is the explicit target, not an orphan.
+  const pruned_skills = [];
+  if (scope !== "skill") {
+    const referenced = new Set();
+    for (const a of agentsById.values()) for (const n of a.skill_names) referenced.add(n);
+    for (const name of [...skills.keys()]) {
+      if (!referenced.has(name)) { pruned_skills.push(name); skills.delete(name); }
+    }
   }
 
   const manifest = buildManifest({
@@ -134,6 +182,7 @@ export function exportResource({ cli, scope, ids, outDir, sourceWorkspaceId, fs
     skills: [...skills.values()].map((s) => ({ name: s.name, source_id: s.id })),
     agents: [...agentsById.values()].map((a) => ({ name: a.raw.name, source_id: a.raw.id, source_runtime_id: a.raw.runtime_id, source_runtime_provider: a.raw.source_runtime_provider, skill_names: a.skill_names, had_secrets: a.red.hadSecrets })),
     squads,
+    projects,
   });
 
   const warnings = [];
@@ -170,14 +219,30 @@ export function exportResource({ cli, scope, ids, outDir, sourceWorkspaceId, fs
         record.avatar_file = rel;
       }
     }
+    // Instructions live in a sibling .md for reviewability (same sibling-file
+    // pattern as avatar_file); only written when non-empty.
+    if (red.instructions) {
+      const rel = entry.file.replace(/\.json$/, ".md");
+      fs.writeFileSync(`${outDir}/${rel}`, red.instructions);
+      record.instructions_file = rel;
+    }
     fs.writeFileSync(`${outDir}/${entry.file}`, JSON.stringify(record, null, 2));
   }
+  const squadInstrByName = new Map(squads.map((s) => [s.name, s.instructions ?? ""]));
   for (const entry of manifest.squads) {
     fs.mkdirSync(`${outDir}/squads`, { recursive: true });
+    if (entry.instructions_file) {
+      fs.writeFileSync(`${outDir}/${entry.instructions_file}`, squadInstrByName.get(entry.name) ?? "");
+    }
     fs.writeFileSync(`${outDir}/${entry.file}`, JSON.stringify(entry, null, 2));
   }
+  const projectByTitle = new Map(projects.map((p) => [p.title, p]));
+  for (const entry of manifest.projects) {
+    fs.mkdirSync(`${outDir}/projects`, { recursive: true });
+    fs.writeFileSync(`${outDir}/${entry.file}`, JSON.stringify(projectByTitle.get(entry.title), null, 2));
+  }
   fs.writeFileSync(`${outDir}/manifest.json`, JSON.stringify(manifest, null, 2));
-  return { manifest, warnings };
+  return { manifest, warnings, pruned_skills };
 }
 
 function main() {
@@ -189,8 +254,8 @@ function main() {
   const out       = get("--out");
   const workspace = get("--workspace"); // optional: source workspace name
 
-  if (!scope || !out || (scope !== "all" && !id)) {
-    console.error("Usage: multica-export.mjs --scope <skill|agent|squad|all> --id <id> --out <dir> [--workspace <name>]  (--id not needed for --scope all)");
+  if (!scope || !out || (scope !== "all" && scope !== "projects" && !id)) {
+    console.error("Usage: multica-export.mjs --scope <skill|agent|squad|project|projects|all> --id <id> --out <dir> [--workspace <name>]  (--id not needed for --scope all|projects)");
     process.exit(1);
   }
 
@@ -205,8 +270,10 @@ function main() {
   if (scope === "skill")       ids.skillId  = id;
   else if (scope === "agent")  ids.agentId  = id;
   else if (scope === "squad")  ids.squadId  = id;
+  else if (scope === "project")  ids.projectId = id;
+  else if (scope === "projects") { /* all projects — no id */ }
   else if (scope === "all")    { /* whole workspace — no id */ }
-  else { console.error(`Unknown scope "${scope}" — use skill|agent|squad|all`); process.exit(1); }
+  else { console.error(`Unknown scope "${scope}" — use skill|agent|squad|project|projects|all`); process.exit(1); }
 
   const result = exportResource({ cli, scope, ids, outDir: out, sourceWorkspaceId, fs: nodeFs });
   console.log(JSON.stringify(result, null, 2));

package/plugins/multica-tool/scripts/multica-import.mjs

@@ -1,5 +1,22 @@
 import * as nodeFs from "node:fs";
-import { listSkills, listAgents, listSquads, listRuntimes, listWorkspaceMembers, getSquadMembers, findByName, makeCli, realExec, requireAuth, resolveWorkspaceId } from "./lib.mjs";
+import { listSkills, listAgents, listSquads, listRuntimes, listWorkspaceMembers, getSquadMembers, findByName, makeCli, realExec, requireAuth, resolveWorkspaceId, listProjects, getProjectResources, findByTitle } from "./lib.mjs";
+
+// User-facing selectable types are agents/squads/projects; skills follow agents.
+export function parseInclude(raw) {
+  const set = new Set((raw ? raw.split(",") : ["agents", "squads"]).map((s) => s.trim()).filter(Boolean));
+  if (set.has("agents")) set.add("skills");
+  return set;
+}
+
+// Instructions live in a sibling .md referenced by `instructions_file` (mirrors
+// avatar_file). Legacy bundles carry no instructions_file and keep instructions
+// inline in the JSON — fall back to that so older exports still import.
+function readInstructions(fs, dir, rec) {
+  if (rec.instructions_file && fs.existsSync(`${dir}/${rec.instructions_file}`)) {
+    return fs.readFileSync(`${dir}/${rec.instructions_file}`, "utf8");
+  }
+  return rec.instructions ?? "";
+}
 
 // Relative paths of every file under root (recursing into subdirs like scripts/).
 function walkSkillFiles(fs, root, rel = "") {
@@ -82,7 +99,8 @@ export function importAgents({ cli, manifest, dir, skillIdMap, runtimeMap, fs =
       "--max-concurrent-tasks", String(rec.max_concurrent_tasks ?? 6),
     ];
     if (rec.description) common.push("--description", rec.description);
-    if (rec.instructions) common.push("--instructions", rec.instructions);
+    const instructions = readInstructions(fs, dir, rec);
+    if (instructions) common.push("--instructions", instructions);
     if (rec.model) common.push("--model", rec.model);
     if (rec.thinking_level) common.push("--thinking-level", rec.thinking_level);
     if (rec.runtime_config && Object.keys(rec.runtime_config).length) common.push("--runtime-config", JSON.stringify(rec.runtime_config));
@@ -184,9 +202,10 @@ export function rewriteAgentMentions({ cli, manifest, dir, agentIdMap, sourceIdM
   let updated = 0;
   for (const a of manifest.agents) {
     const rec = JSON.parse(fs.readFileSync(`${dir}/${a.file}`, "utf8"));
-    if (!rec.instructions) continue;
-    const rewritten = rewriteMentions(rec.instructions, sourceIdMap);
-    if (rewritten === rec.instructions) continue;
+    const instructions = readInstructions(fs, dir, rec);
+    if (!instructions) continue;
+    const rewritten = rewriteMentions(instructions, sourceIdMap);
+    if (rewritten === instructions) continue;
     cli.run(["agent", "update", agentIdMap.get(rec.name), "--instructions", rewritten]);
     updated++;
   }
@@ -196,6 +215,7 @@ export function rewriteAgentMentions({ cli, manifest, dir, agentIdMap, sourceIdM
 export function importSquad({ cli, squad, agentIdMap, sourceIdMap }) {
   const existing = listSquads(cli);
   const leaderId = agentIdMap.get(squad.leader_name);
+  if (!leaderId) return { skipped: true, created: 0, updated: 0 };
   const match = findByName(existing, squad.name);
   let id, created = 0, updated = 0;
   // Squad instructions commonly list @mentions of teammate agents by their
@@ -221,12 +241,63 @@ export function importSquad({ cli, squad, agentIdMap, sourceIdMap }) {
   for (const m of squad.members) {
     if (m.agent_name === squad.leader_name) continue;
     const memberId = agentIdMap.get(m.agent_name);
-    if (present.has(memberId)) continue;
+    if (!memberId || present.has(memberId)) continue;
     cli.run(["squad", "member", "add", id, "--member-id", memberId, "--role", m.role, "--type", "agent"]);
   }
   return { newId: id, created, updated };
 }
 
+export function importProjects({ cli, manifest, dir, agentIdMap, fs = nodeFs }) {
+  const idMap = new Map();
+  let created = 0, updated = 0;
+  const priorityUnsupported = [], resourcesUnsupported = [], leadUnresolved = [];
+  const existing = listProjects(cli);
+  // Lead resolves against just-imported agents first, then destination agents.
+  let destAgentNames = null;
+  const leadResolvable = (name) =>
+    agentIdMap.has(name) || (destAgentNames ??= new Set(listAgents(cli).map((a) => a.name))).has(name);
+
+  for (const entry of manifest.projects ?? []) {
+    const rec = JSON.parse(fs.readFileSync(`${dir}/${entry.file}`, "utf8"));
+    const flags = ["--title", rec.title];
+    if (rec.description) flags.push("--description", rec.description);
+    if (rec.icon) flags.push("--icon", rec.icon);
+    if (rec.status) flags.push("--status", rec.status);
+    if (rec.due_date) flags.push("--due-date", rec.due_date);
+    if (rec.start_date) flags.push("--start-date", rec.start_date);
+    const wantsLead = rec.lead_type === "agent" && !!rec.lead_name;
+    const leadOk = wantsLead && leadResolvable(rec.lead_name);
+    if (leadOk) flags.push("--lead", rec.lead_name);
+
+    const match = findByTitle(existing, rec.title);
+    let id;
+    if (match) {
+      cli.run(["project", "update", match.id, ...flags]);
+      id = match.id; updated++;
+    } else {
+      id = JSON.parse(cli.run(["project", "create", ...flags])).id;
+      created++;
+    }
+    idMap.set(rec.title, id);
+
+    if (wantsLead && !leadOk) leadUnresolved.push(rec.title);
+    if (rec.priority && rec.priority !== "none") priorityUnsupported.push(rec.title);
+
+    // Resources: recreate github_repo only, idempotent by url.
+    const existingUrls = new Set(
+      getProjectResources(cli, id).filter((r) => r.resource_type === "github_repo").map((r) => r.resource_ref?.url).filter(Boolean),
+    );
+    for (const r of rec.resources ?? []) {
+      if (r.resource_type !== "github_repo") { resourcesUnsupported.push(`${rec.title}:${r.resource_type}`); continue; }
+      const url = r.resource_ref?.url;
+      if (!url || existingUrls.has(url)) continue;
+      cli.run(["project", "resource", "add", id, "--type", "github_repo", "--url", url, ...(r.label ? ["--label", r.label] : [])]);
+      existingUrls.add(url);
+    }
+  }
+  return { idMap, created, updated, priorityUnsupported, resourcesUnsupported, leadUnresolved };
+}
+
 export function collectSourceRuntimes(manifest) {
   return [...new Set((manifest.agents ?? []).map((a) => a.source_runtime_id).filter(Boolean))];
 }
@@ -263,45 +334,124 @@ export function resolveRuntimeMap({ cli, manifest, runtimeMap }) {
   return { effective, unresolved };
 }
 
-export function importBundle({ cli, dir, runtimeMap, fs = nodeFs }) {
+export function importBundle({ cli, dir, runtimeMap, include, fs = nodeFs }) {
+  const inc = include ?? new Set(["skills", "agents", "squads"]);
   const manifest = JSON.parse(fs.readFileSync(`${dir}/manifest.json`, "utf8"));
-  const { effective, unresolved } = resolveRuntimeMap({ cli, manifest, runtimeMap });
-  if (unresolved.length) {
-    const detail = unresolved.map(({ srcId, provider, matchCount }) => provider
-      ? `${srcId} (provider "${provider}": ${matchCount} matching runtimes in destination, expected exactly 1)`
-      : `${srcId} (no provider recorded)`).join(", ");
-    throw new Error(`Unmapped runtimes: ${detail} — pass --runtime-map, aborting before any write`);
+
+  let effective = new Map();
+  if (inc.has("agents")) {
+    const r = resolveRuntimeMap({ cli, manifest, runtimeMap });
+    if (r.unresolved.length) {
+      const detail = r.unresolved.map(({ srcId, provider, matchCount }) => provider
+        ? `${srcId} (provider "${provider}": ${matchCount} matching runtimes in destination, expected exactly 1)`
+        : `${srcId} (no provider recorded)`).join(", ");
+      throw new Error(`Unmapped runtimes: ${detail} — pass --runtime-map, aborting before any write`);
+    }
+    effective = r.effective;
   }
 
-  const skillRes = importSkills({ cli, manifest, dir, fs });
-  const agentRes = importAgents({ cli, manifest, dir, skillIdMap: skillRes.idMap, runtimeMap: effective, fs });
+  const skillRes = inc.has("skills")
+    ? importSkills({ cli, manifest, dir, fs })
+    : { idMap: new Map(), created: 0, updated: 0 };
+  const agentRes = inc.has("agents")
+    ? importAgents({ cli, manifest, dir, skillIdMap: skillRes.idMap, runtimeMap: effective, fs })
+    : { idMap: new Map(), sourceIdMap: new Map(), created: 0, updated: 0, secretsApplyFailures: [], avatarApplyFailures: [], avatarUnsupported: [], permissionApplyFailures: [], permissionUnsupported: [] };
   // Runs after every agent exists so forward-referencing mentions resolve.
-  const mentionRes = rewriteAgentMentions({ cli, manifest, dir, agentIdMap: agentRes.idMap, sourceIdMap: agentRes.sourceIdMap, fs });
+  const mentionRes = inc.has("agents")
+    ? rewriteAgentMentions({ cli, manifest, dir, agentIdMap: agentRes.idMap, sourceIdMap: agentRes.sourceIdMap, fs })
+    : { updated: 0 };
+
   const squadIdMap = new Map();
   let squadsCreated = 0, squadsUpdated = 0;
-  for (const squad of manifest.squads ?? []) {
-    const r = importSquad({ cli, squad, agentIdMap: agentRes.idMap, sourceIdMap: agentRes.sourceIdMap });
-    squadIdMap.set(squad.name, r.newId);
-    squadsCreated += r.created;
-    squadsUpdated += r.updated;
+  const squadsSkipped = [];
+  if (inc.has("squads")) {
+    for (const squad of manifest.squads ?? []) {
+      squad.instructions = readInstructions(fs, dir, squad);
+      const r = importSquad({ cli, squad, agentIdMap: agentRes.idMap, sourceIdMap: agentRes.sourceIdMap });
+      if (r.skipped) { squadsSkipped.push(squad.name); continue; }
+      squadIdMap.set(squad.name, r.newId);
+      squadsCreated += r.created;
+      squadsUpdated += r.updated;
+    }
+  }
+
+  let projectRes = { idMap: new Map(), created: 0, updated: 0, priorityUnsupported: [], resourcesUnsupported: [], leadUnresolved: [] };
+  if (inc.has("projects")) {
+    projectRes = importProjects({ cli, manifest, dir, agentIdMap: agentRes.idMap, fs });
   }
 
   return {
-    created: { skills: skillRes.created, agents: agentRes.created, squads: squadsCreated },
-    updated: { skills: skillRes.updated, agents: agentRes.updated, squads: squadsUpdated },
+    include: [...inc],
+    created: { skills: skillRes.created, agents: agentRes.created, squads: squadsCreated, projects: projectRes.created },
+    updated: { skills: skillRes.updated, agents: agentRes.updated, squads: squadsUpdated, projects: projectRes.updated },
     mentionsRewritten: mentionRes.updated,
     skillIdMap: Object.fromEntries(skillRes.idMap),
     agentIdMap: Object.fromEntries(agentRes.idMap),
     squadIdMap: Object.fromEntries(squadIdMap),
+    projectIdMap: Object.fromEntries(projectRes.idMap),
     secretsReminder: (manifest.agents ?? []).filter((a) => a.had_secrets).map((a) => a.name),
     secretsApplyFailures: agentRes.secretsApplyFailures,
     avatarApplyFailures: agentRes.avatarApplyFailures,
     avatarUnsupported: agentRes.avatarUnsupported,
     permissionApplyFailures: agentRes.permissionApplyFailures,
     permissionUnsupported: agentRes.permissionUnsupported,
+    squadsSkipped,
+    priorityUnsupported: projectRes.priorityUnsupported,
+    resourcesUnsupported: projectRes.resourcesUnsupported,
+    leadUnresolved: projectRes.leadUnresolved,
   };
 }
 
+export function preflight({ cli, dir, runtimeMap, include, fs = nodeFs }) {
+  const inc = include ?? new Set(["skills", "agents", "squads"]);
+  const manifest = JSON.parse(fs.readFileSync(`${dir}/manifest.json`, "utf8"));
+  const count = (k) => (manifest[k] ?? []).length;
+  const bundle = { skills: count("skills"), agents: count("agents"), squads: count("squads"), projects: count("projects") };
+  const willImport = {
+    skills: inc.has("skills") ? bundle.skills : 0,
+    agents: inc.has("agents") ? bundle.agents : 0,
+    squads: inc.has("squads") ? bundle.squads : 0,
+    projects: inc.has("projects") ? bundle.projects : 0,
+  };
+
+  const incompatibilities = [];
+  let runtimes = { resolved: [], unresolved: [] };
+  if (inc.has("agents")) {
+    const { effective, unresolved } = resolveRuntimeMap({ cli, manifest, runtimeMap });
+    runtimes = {
+      resolved: [...effective.entries()].map(([s, d]) => `${s}=${d}`),
+      unresolved: unresolved.map((u) => u.srcId),
+    };
+    for (const u of unresolved) {
+      incompatibilities.push({ type: "unmapped-runtime", detail: u.provider
+        ? `${u.srcId} (provider "${u.provider}": ${u.matchCount} matches, expected 1)`
+        : `${u.srcId} (no provider recorded)` });
+    }
+  }
+
+  if (inc.has("projects")) {
+    const bundleAgentNames = new Set((manifest.agents ?? []).map((a) => a.name));
+    for (const entry of manifest.projects ?? []) {
+      const rec = JSON.parse(fs.readFileSync(`${dir}/${entry.file}`, "utf8"));
+      if (rec.priority && rec.priority !== "none") {
+        incompatibilities.push({ type: "priority-not-settable", detail: `${rec.title} (priority "${rec.priority}")` });
+      }
+      for (const r of rec.resources ?? []) {
+        if (r.resource_type !== "github_repo") {
+          incompatibilities.push({ type: "resource-not-portable", detail: `${rec.title} (${r.resource_type})` });
+        }
+      }
+      const leadAvailable = inc.has("agents") && bundleAgentNames.has(rec.lead_name);
+      if (rec.lead_type === "agent" && rec.lead_name && !leadAvailable) {
+        incompatibilities.push({ type: "lead-agent-missing", detail: `${rec.title} → ${rec.lead_name} (ensure this agent exists in the destination)` });
+      }
+    }
+  }
+
+  const secretsReminder = (manifest.agents ?? []).filter((a) => a.had_secrets).map((a) => a.name);
+  return { bundle, willImport, runtimes, incompatibilities, secretsReminder };
+}
+
 function parseRuntimeMap(raw) {
   // Parse "srcId1=dstId1,srcId2=dstId2" into a Map.
   const map = new Map();
@@ -321,9 +471,11 @@ function main() {
   const dir       = get("--dir");
   const workspace = get("--workspace");
   const rawMap    = get("--runtime-map");
+  const rawInclude = get("--include");
+  const dryRun    = args.includes("--dry-run");
 
   if (!dir || !workspace) {
-    console.error("Usage: multica-import.mjs --dir <folder> --workspace <name> [--runtime-map <src=dst,...>]");
+    console.error("Usage: multica-import.mjs --dir <folder> --workspace <name> [--runtime-map <src=dst,...>] [--include <csv>] [--dry-run]");
     process.exit(1);
   }
 
@@ -332,8 +484,13 @@ function main() {
   const wsId      = resolveWorkspaceId(resolver, workspace);
   const cli       = makeCli(realExec, { workspaceId: wsId });
   const runtimeMap = parseRuntimeMap(rawMap);
+  const include = parseInclude(rawInclude);
 
-  const result = importBundle({ cli, dir, runtimeMap, fs: nodeFs });
+  if (dryRun) {
+    console.log(JSON.stringify(preflight({ cli, dir, runtimeMap, include, fs: nodeFs }), null, 2));
+    return;
+  }
+  const result = importBundle({ cli, dir, runtimeMap, include, fs: nodeFs });
   console.log(JSON.stringify(result, null, 2));
 }
 

package/plugins/multica-tool/scripts/multica-sync.mjs

@@ -1,13 +1,18 @@
 import * as nodeFs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { makeCli, resolveWorkspaceId, findByName, listSkills, listAgents, listSquads, realExec, requireAuth } from "./lib.mjs";
+import { makeCli, resolveWorkspaceId, findByName, findByTitle, listSkills, listAgents, listSquads, listProjects, realExec, requireAuth } from "./lib.mjs";
 import { exportResource } from "./multica-export.mjs";
 import { importBundle } from "./multica-import.mjs";
 
 export function resolveScopeId(cli, type, name) {
+  if (type === "project") {
+    const match = findByTitle(listProjects(cli), name);
+    if (!match) throw new Error(`Unknown project "${name}" in source workspace`);
+    return { scope: "project", ids: { projectId: match.id } };
+  }
   const lists = { skill: listSkills, agent: listAgents, squad: listSquads };
-  if (!lists[type]) throw new Error(`Unknown type "${type}" (skill|agent|squad)`);
+  if (!lists[type]) throw new Error(`Unknown type "${type}" (skill|agent|squad|project)`);
   const match = findByName(lists[type](cli), name);
   if (!match) throw new Error(`Unknown ${type} "${name}" in source workspace`);
   const key = { skill: "skillId", agent: "agentId", squad: "squadId" }[type];
@@ -23,7 +28,10 @@ export function sync({ exec, type, name, srcWsName, destWsName, tmpDir, runtimeM
 
   const { scope, ids } = resolveScopeId(srcCli, type, name);
   exportResource({ cli: srcCli, scope, ids, outDir: tmpDir, sourceWorkspaceId: srcId, fs });
-  return importBundle({ cli: destCli, dir: tmpDir, runtimeMap, fs });
+  const includeByType = { skill: ["skills"], agent: ["agents"], squad: ["agents", "squads"], project: ["agents", "projects"] };
+  const include = new Set(includeByType[type] ?? ["agents", "squads"]);
+  if (include.has("agents")) include.add("skills");
+  return importBundle({ cli: destCli, dir: tmpDir, runtimeMap, include, fs });
 }
 
 function parseRuntimeMap(raw) {

package/plugins/multica-tool/skills/export/SKILL.md

@@ -10,17 +10,17 @@ Export a Multica resource (skill, agent, or squad) to a local bundle directory.
 
 ## Step 1 — Verify authentication
 
-Run the export script; it calls `multica auth status` internally and exits with an error message if unauthenticated:
+Run `multica auth status` directly. The export script performs this same check internally before doing any work (via `requireAuth` in `scripts/lib.mjs`), but only after `--scope`/`--out` are supplied — so checking it here up front avoids masking an auth failure behind a later usage error:
 
 ```bash
-node "${CLAUDE_PLUGIN_ROOT}/scripts/multica-export.mjs" --help 2>&1 || true
+multica auth status 2>&1 || true
 ```
 
 If `multica login` is required, surface that message verbatim and stop.
 
 ## Step 2 — Determine scope and resource ID
 
-If the user named a specific resource and type (`skill`, `agent`, or `squad`), use those directly.
+If the user named a specific resource and type (`skill`, `agent`, `squad`, or `project`), use those directly.
 
 Otherwise, list available resources for the chosen type and present a pick list:
 
@@ -44,15 +44,19 @@ where `<slug>` is a lowercased, hyphenated form of the resource name.
 
 ```bash
 node "${CLAUDE_PLUGIN_ROOT}/scripts/multica-export.mjs" \
-  --scope <type|all> \
+  --scope <skill|agent|squad|project|projects|all> \
   --id <id> \
   --out <dir> \
   [--workspace <workspace-name>]
 ```
 
-Pass `--scope all` (with no `--id`) to export the **entire workspace** — every skill, agent, and squad — into one flat, deduped bundle. A skill or agent shared across many agents/squads is written exactly once and referenced by name.
+`--id` is required for `skill`, `agent`, `squad`, and `project` (a single named resource); it is **not needed** for `projects` (every project in the workspace) or `all` (the entire workspace).
 
-The script writes `manifest.json`, skill SKILL.md files, agent JSON files, and squad JSON files into `<dir>`.
+Pass `--scope all` (with no `--id`) to export the **entire workspace** — every skill, agent, squad, and project — into one flat, deduped bundle. A skill or agent shared across many agents/squads is written exactly once and referenced by name.
+
+Exporting a project (or `projects`/`all`) also **bundles the project's lead agent** so the bundle is self-contained; projects carry metadata only (title, description, icon, priority, status, dates, lead mapping) plus their attached resource records — never issues. On import, only `github_repo` resources are portable and recreated; other resource types are reported and skipped.
+
+The script writes `manifest.json`, skill `SKILL.md` files, agent JSON files, and squad JSON files into `<dir>`. Each agent's and squad's **instructions** (system prompt / charter) are written to a sibling Markdown file — `agents/<slug>.md`, `squads/<slug>.md` — referenced by an `instructions_file` key in the JSON, so the prose is easy to read, diff, and edit. Agents/squads with no instructions get no `.md`.
 
 Avatars are captured automatically: an agent's uploaded-image avatar is downloaded into the bundle (`agents/<slug>.avatar.<ext>`) and referenced by `avatar_file`; emoji avatars (agents and squads) and a squad's avatar are recorded as the `avatar_url` string.
 
@@ -61,5 +65,6 @@ Avatars are captured automatically: an agent's uploaded-image avatar is download
 Parse the JSON output from the script and report:
 
 - Directory written to.
-- Count of skills, agents, and squads exported.
+- Count of skills, agents, squads, and projects exported.
+- If `pruned_skills` is non-empty, note it: "Pruned N orphan skill(s) not linked to any agent: `<name>`, …" (these are standalone workspace skills that no exported agent references — only `--scope all` produces them).
 - If `warnings` is non-empty, surface every agent name verbatim with this message: "WARNING: the following agents' exported files contain custom environment variables or MCP config in PLAINTEXT — treat the export directory as sensitive (avoid committing it to a public repo, restrict file permissions, delete it once the import is done): `<agent-name>`."

package/plugins/multica-tool/skills/import/SKILL.md

@@ -12,14 +12,36 @@ Import a local Multica bundle (produced by the export skill) into a target works
 
 Ask the user to confirm the name of the target workspace if not already stated. You will need the exact workspace name as registered in Multica.
 
-## Step 2 — Run the import (auto-mapping first)
+## Step 2 — Pre-flight (dry run)
 
-Each exported agent record carries its source runtime's `provider` (e.g. `claude`, `opencode`) alongside its ID. The import script auto-maps a source runtime to the target workspace's runtime when there is **exactly one** runtime of that provider there — no manual mapping needed in the common case. Try the import without `--runtime-map` first:
+Before writing anything, run the import script with `--dry-run` to preview the bundle. Preview against the **full** set (`--include agents,squads,projects`) regardless of what the user ultimately chooses to import — incompatibilities for a type (e.g. project caveats) are only computed when that type is included, so previewing everything up front is what lets the user see a project's cost before deciding whether to opt it in:
 
 ```bash
 node "${CLAUDE_PLUGIN_ROOT}/scripts/multica-import.mjs" \
   --dir <folder> \
-  --workspace <workspace-name>
+  --workspace <workspace-name> \
+  --include agents,squads,projects \
+  [--runtime-map <srcId1=dstId1,srcId2=dstId2,...>] \
+  --dry-run
+```
+
+Present the `bundle` and `willImport` counts, and every entry in `incompatibilities`, to the user.
+
+## Step 3 — Select which types to import
+
+Ask the user which of `agents`, `squads`, `projects` they want to import. **Default is `agents,squads`** — `projects` requires explicit opt-in.
+
+If the pre-flight's `incompatibilities` list contains an `unmapped-runtime` entry, tell the user it must be resolved with `--runtime-map` before the real import — the import **aborts** otherwise (see Step 4 below). Other incompatibility kinds are informational only and applied best-effort, fixed up afterward in the Multica UI: `priority-not-settable` (priority isn't settable via the CLI, so it never round-trips), `resource-not-portable` (only `github_repo` resources are portable — other resource kinds are dropped), and `lead-agent-missing` (a non-agent lead isn't re-applied to the imported project).
+
+## Step 4 — Run the import (auto-mapping first)
+
+Each exported agent record carries its source runtime's `provider` (e.g. `claude`, `opencode`) alongside its ID. The import script auto-maps a source runtime to the target workspace's runtime when there is **exactly one** runtime of that provider there — no manual mapping needed in the common case. Try the import without `--runtime-map` first, passing the selected types from Step 3 via `--include`:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/multica-import.mjs" \
+  --dir <folder> \
+  --workspace <workspace-name> \
+  --include <agents,squads,projects>
 ```
 
 If it aborts with `Unmapped runtimes: ...` (0 or 2+ runtimes share that provider in the target workspace, or the bundle predates provider capture), resolve manually:
@@ -35,21 +57,25 @@ Ask the user to pick a matching target runtime by name or ID for each unmapped `
 node "${CLAUDE_PLUGIN_ROOT}/scripts/multica-import.mjs" \
   --dir <folder> \
   --workspace <workspace-name> \
+  --include <agents,squads,projects> \
   --runtime-map <srcId1=dstId1,srcId2=dstId2,...>
 ```
 
 The import also rewrites any `mention://agent/<id>` link inside squad and agent instructions (e.g. `[@dev-backend](mention://agent/<id>)`) from the source agent's id to its new id in the target workspace — the CLI does this automatically for every agent captured in the bundle; no extra flag needed. Mentions pointing to an agent outside the bundle are left untouched.
 
+Instructions are read back from each resource's sibling `.md` (`agents/<slug>.md`, `squads/<slug>.md`) when present — editing that Markdown is the supported way to review and enhance an agent's or squad's instructions before import. Older bundles that predate the split (instructions inline in the JSON, no `instructions_file`) still import unchanged.
+
 Avatars are restored automatically, but **only when the target resource has none** — an existing agent or squad that already carries an avatar is never overwritten. New agents get their bundled image re-uploaded; new squads get their `avatar_url` (emoji or URL) set. An agent whose source avatar was an emoji can't be restored (the CLI has no emoji setter for agents) and is reported as unsupported.
 
-## Step 3 — Report results
+## Step 5 — Report results
 
 Parse the JSON output and report:
 
-- Created and updated counts for skills, agents, and squads.
+- Created and updated counts for skills, agents, squads, and projects (`created.projects`/`updated.projects`).
 - Name-to-ID maps for skills and agents (`skillIdMap`, `agentIdMap`).
 - `squadIdMap`: name-to-ID map for every squad imported.
 - `mentionsRewritten`: how many agents had an agent-mention link rewritten to its new id.
+- If `leadUnresolved`, `priorityUnsupported`, `resourcesUnsupported`, or `squadsSkipped` is non-empty, surface each entry verbatim as an "applied best-effort; adjust in the UI" note — e.g. "NOTE: applied best-effort; adjust in the UI — `<entry>`."
 - If `secretsReminder` is non-empty, surface every agent name verbatim with: "WARNING: the following agents' bundle files contained custom environment variables or MCP config in PLAINTEXT — the source export directory should be treated as sensitive: `<agent-name>`."
 - If `secretsApplyFailures` is non-empty, surface every agent name verbatim with: "WARNING: mcp_config or custom_env failed to apply to the following agents during import (the agent itself was still created/updated) — set them manually in the Multica UI: `<agent-name>`."
 - If `avatarApplyFailures` is non-empty, surface every agent name verbatim with: "WARNING: the avatar image failed to upload for the following agents — set it manually in the Multica UI: `<agent-name>`."

package/plugins/multica-tool/skills/sync/SKILL.md

@@ -16,7 +16,9 @@ Expect the user's request in the form:
 sync <type> <name> from <src-ws> to <dest-ws>
 ```
 
-Where `<type>` is `skill`, `agent`, or `squad`; `<name>` is the resource name; `<src-ws>` and `<dest-ws>` are workspace names registered in Multica.
+Where `<type>` is `skill`, `agent`, `squad`, or `project`; `<name>` is the resource name (for `project`, its **title**); `<src-ws>` and `<dest-ws>` are workspace names registered in Multica.
+
+Projects are resolved by title, not ID, e.g. `multica-sync.mjs project "<title>" from <src-ws> <dest-ws>` — the project's lead agent is synced alongside it.
 
 ## Step 2 — Run the sync (auto-mapping first)
 
@@ -47,7 +49,7 @@ The script exports to a temporary directory, imports into the destination worksp
 
 Parse the JSON output and report:
 
-- Created and updated counts for skills, agents, and squads.
+- Created and updated counts for skills, agents, squads, and projects.
 - Name-to-ID maps (`skillIdMap`, `agentIdMap`).
 - `squadIdMap`: name-to-ID map for every squad synced.
 - If `secretsReminder` is non-empty, surface every agent name verbatim with: "WARNING: the following agents' bundle files contained custom environment variables or MCP config in PLAINTEXT — the temporary export directory (already cleaned up) briefly held these secrets in plaintext: `<agent-name>`."

package/plugins/plugin-validator/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "plugin-validator",
   "displayName": "Plugin Validator",
-  "version": "0.0.39",
+  "version": "0.0.41",
   "description": "Orchestrated validator for Claude Code plugins — validates skills, agents, commands, and hooks across every plugin under plugins/**.",
   "author": {
     "name": "Steven Hoang"

package/plugins/team-share/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "team-share",
   "displayName": "Team Share",
-  "version": "0.0.39",
+  "version": "0.0.41",
   "description": "Onboard your team with an interactive setup menu: install CodeGraph, build the Understand-Anything knowledge graph, and share Claude Code settings — run any combination, all idempotent.",
   "author": {
     "name": "Steven Hoang"

package/plugins/tech-graph/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "tech-graph",
-  "version": "0.0.39",
+  "version": "0.0.41",
   "description": "Step-by-step wizard for generating technical diagrams as SVG+PNG.",
   "author": {
     "name": "steven"