@starlein/paperclip-plugin-company-wizard 0.4.13 → 0.4.17

package/CHANGELOG.md

@@ -4,6 +4,64 @@ All notable changes to the Company Wizard plugin are documented here.
 
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.4.17] - 2026-06-29
+
+### Fixed
+
+**Worker agents no longer send `reasoning.effort: "auto"` to Codex (400 error)**
+
+Worker agents default to `DEFAULT_WORKER_THINKING_LEVEL = 'auto'` ("let the model decide"), but Codex's `reasoning.effort` API rejects `"auto"` with a 400 — the accepted values are `none|minimal|low|medium|high|xhigh`. The "let the model decide" semantics are achieved by **omitting the parameter entirely**. Both the worker provisioning path (`ceo-defaults.js` → `buildAdapterConfig`) and the BOOTSTRAP.md generation path (`assemble.js` → `resolveRoleAdapterConfig`) now strip `modelReasoningEffort` and `thinkingLevel` when the resolved level is `"auto"` for `codex_local` adapters, so Codex picks its own effort instead of failing. Explicit levels (`none`–`xhigh`) are still passed through unchanged.
+
+## [0.4.16] - 2026-06-28
+
+### Changed
+
+**Agents and projects use external paths under `companies/<Company>/…` with relative instruction references**
+
+Agents were provisioned with a **managed** instructions bundle (materialized by the host under `companies/<companyId>/agents/<agentId>/instructions/`), and the assembled instruction files hard-coded **absolute** `$AGENT_HOME/...` paths that pointed at the human-readable `companies/<CompanyName>/agents/<role>/` dir — a mismatch that made references fragile and unportable.
+
+- **External instructions bundle (all agents, incl. CEO):** provisioning now points each agent at its assembled on-disk dir via `updateInstructionsBundle({ mode: 'external', rootPath: '…/companies/<Company>/agents/<role>', entryFile: 'AGENTS.md' })`. That call also sets `adapterConfig.instructionsFilePath`, which every local adapter (codex/claude/acpx) loads — instructing the model to *"resolve relative file references from the instructions directory"*. Existing managed agents are migrated to external on the next update.
+- **Relative references** in assembled files: `$AGENT_HOME/HEARTBEAT.md` → `HEARTBEAT.md`, `$AGENT_HOME/skills/<x>.md` → `skills/<x>.md`. Bare `$AGENT_HOME` prose (the runtime home env var) is left intact. The old absolute-path rewrite is removed; no managed-bundle file upload happens anymore.
+- **Company doc references unified to `../../docs/<y>.md`** across every agent-facing file (AGENTS.md, HEARTBEAT, skills, the shipped docs themselves like `git-workflow.md`/`pr-conventions.md`, heartbeat-sections, bootstrap-instructions, and module/preset issue descriptions) — 170+ refs. This path is **cwd-independent**: both the instructions dir (`agents/<role>/`) and the execution cwd (the project workspace `projects/<name>/`) sit at depth 2 under the company dir, so `../../docs/` resolves to `companies/<Company>/docs/` from either. A bare `docs/<y>.md` would have broken once the agent runs in a project workspace.
+- **Project workspaces** are realized under `companies/<Company>/projects/<Project>` for external (`git_repo`) projects too — the repo is cloned into that dir via `workspace.cwd` instead of a separate host-managed clone path (local projects already used this path).
+
+> Deploy + "Update templates" + update-company to migrate a live company's agents from managed to external instructions.
+
+## [0.4.15] - 2026-06-28
+
+### Fixed
+
+**Template-cache refresh now hits the dir the worker reads (Docker) — fixes "fixed but never deployed"**
+
+`refresh-templates` (the "Update templates" button) always deleted/re-downloaded `~/.paperclip/plugin-templates`, but on Docker instances the worker reads `~/plugin-templates` (`isDockerLayout()`). So refreshing never updated the dir the worker actually assembles from, and shipped template fixes (e.g. the v0.4.7 Code-Reviewer merge-ownership fix) silently never reached agents. A shared `resolveTemplatesCacheDir`/`refreshTemplatesCache` helper now targets the same Docker-aware dir, and `start-provision` refreshes the cache from the repo before assembling (best-effort; `params.refreshTemplates: false` opts out) so an update always provisions the latest published instructions.
+
+### Changed
+
+**CI/CD is a merge gate only when the company owns it (`ci-cd` module)**
+
+The merge gate enforced "CI must be green" whenever the repo had any CI checks — so a pre-existing/external CI on an imported repo (broken or flaky, never configured by the company) deadlocked the merge queue. Now the **authoritative gate is the merge-gate agent's executed local lint/test/build** (run it, paste the output); a green CI is required *in addition* only when the `ci-cd` module is active (the company runs its own pipeline). Without a CI/CD module, pre-existing repo checks are advisory — never block a merge solely on a check the company never set up. Reworded across `pr-conventions.md`, `code-review.md`, `qa-review.md`, the Code-Reviewer `AGENTS.md`, and the engineer `git-workflow.md`.
+
+**Without the pr-review module, the engineer works direct-to-base instead of opening a PR**
+
+The no-pr-review fallback was a "PR Self-Merge Flow" that still opened a PR per change — the source of the orphan/draft/conflict PR pile-up. With no reviewer, that PR adds no value, so the engineer now commits and pushes **directly to the base ref** after local verification, and opens a PR *only* as a fallback when branch protection rejects the direct push. Rewrote `github-repo` `git-workflow.md` (skill + `docs/git-workflow.md`) to the Direct-to-Base Flow, updated Branch-Protection guidance (do not require PRs for an unreviewed company), and scoped the engineer `HEARTBEAT.md` review-path rule to "pr-review active". The PR workflow remains gated to the `pr-review` module only.
+
+## [0.4.14] - 2026-06-25
+
+### Fixed
+
+**Stranded-blocked merge issues — a CEO-routine safety net (templates)**
+
+> The longstanding, CI-independent root cause of "agents open PRs but never merge them" was a **contradiction in the Code Reviewer's instructions** — the role's `AGENTS.md` said "Never merge PRs. That's the engineer's job." while its skill (and the engineer's pr-workflow) made the Code Reviewer the merge owner, so nobody merged. That was already fixed in **v0.4.7** (commit `3e065cf`); instances still piling up PRs are running pre-v0.4.7 instruction bundles and need a template-cache refresh + update-company to pick up the corrected instructions. This v0.4.14 entry addresses a **secondary, downstream** failure, not that root cause.
+
+Observed on two live instances (LeadConversionOptimizer, Dial24Modern2): because the normal merge never fired, the CEO fanned a single PR out into separate per-role issues (QA/Security/Product) plus a standalone "Code review and merge PR #N" issue assigned to the Code Reviewer and `blockedBy` those reviews. When the reviews close `done`, Paperclip does not reliably re-wake the blocked merge issue (worker heartbeats are disabled, and the liveness watchdog skips a `blocked` issue whose blockers are all `done`), so even those explicit merge issues strand. Evidence: merge issues sitting `blocked` with `blockerAttention.needs_attention` and zero unresolved blockers.
+
+Template fixes:
+
+- `stall-detection.md` (CEO skill): new `## Stranded blocked` recovery — detect a `blocked` issue whose blockers are all `done`/`cancelled` (or `blockerAttention` with `unresolvedBlockerCount: 0`), flag `STRANDED-BLOCKED`, reactivate via `PATCH {"status":"in_progress"}`, re-assign to the merge owner to trigger a wake, and run the merge. Step 4's skip-rule now treats "blocked with all blockers done" as a stall, not validly blocked. PR-queue hygiene gains a step 7 that reconciles each open green/mergeable PR against its owning issue and merges/reactivates when the merge step was skipped.
+- `bootstrap-instructions.md` + `pr-review/README.md`: explicit prohibition — one PR ⇒ one issue ⇒ its `executionPolicy` stages. Never fan a PR out into per-role `blocks`-linked issues, and never model the merge as a standalone `blockedBy` merge issue; the merge gate is the last stage on the same implementation issue, which advances in place.
+
+> Note: the durable platform-level guarantee (auto-reactivate a `blocked` issue once it has no unresolved blockers, and/or a workspace-finalize-barrier timeout) lives in the Paperclip server, not this plugin. These template changes prevent the fan-out and add a CEO-routine safety net that recovers already-stranded merges.
+
 ## [0.4.13] - 2026-06-25
 
 ### Changed

package/dist/manifest.js

@@ -2,7 +2,7 @@
 var manifest = {
   id: "starlein.paperclip-plugin-company-wizard",
   apiVersion: 1,
-  version: "0.4.13",
+  version: "0.4.17",
   displayName: "Company Wizard",
   description: "AI-powered wizard to bootstrap agent companies from composable templates",
   author: "Sascha Pietrowski <sp@speednetwork.de>",

package/dist/manifest.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/manifest.ts"],
-  "sourcesContent": ["import type { PaperclipPluginManifestV1 } from '@paperclipai/plugin-sdk';\n\nconst manifest: PaperclipPluginManifestV1 = {\n  id: 'starlein.paperclip-plugin-company-wizard',\n  apiVersion: 1,\n  version: '0.4.13',\n  displayName: 'Company Wizard',\n  description: 'AI-powered wizard to bootstrap agent companies from composable templates',\n  author: 'Sascha Pietrowski <sp@speednetwork.de>',\n  categories: ['workspace', 'ui'],\n  capabilities: [\n    'companies.read',\n    'issues.create',\n    'issues.read',\n    'issues.update',\n    'goals.create',\n    'goals.read',\n    'agents.read',\n    'projects.read',\n    'plugin.state.read',\n    'plugin.state.write',\n    'secrets.read-ref',\n    'events.subscribe',\n    'ui.page.register',\n    'ui.sidebar.register',\n  ],\n  instanceConfigSchema: {\n    type: 'object',\n    properties: {\n      companiesDir: {\n        type: 'string',\n        description:\n          'Directory where assembled company workspaces are written. Auto-detected: ~/instances/default/companies in Docker setups, ~/.paperclip/instances/default/companies otherwise. Rarely needs manual override.',\n      },\n      templatesPath: {\n        type: 'string',\n        description:\n          'Path to the templates directory. Auto-detected: ~/plugin-templates in Docker setups, ~/.paperclip/plugin-templates otherwise. Rarely needs manual override.',\n      },\n      templatesRepoUrl: {\n        type: 'string',\n        default: 'https://github.com/starlein/paperclip-plugin-company-wizard/tree/main/templates',\n        description:\n          'GitHub tree URL for template downloads. The default is correct for most setups \u2014 only change this if using a custom fork.',\n      },\n      anthropicApiKey: {\n        type: 'string',\n        description:\n          'Anthropic API key for the AI wizard (e.g. sk-ant-...). Required to use the AI-powered company setup path.',\n      },\n      paperclipUrl: {\n        type: 'string',\n        description:\n          'Paperclip instance URL. Defaults to http://localhost:3100 or the PAPERCLIP_PUBLIC_URL env var.',\n      },\n      paperclipEmail: {\n        type: 'string',\n        description: 'Board login email (for authenticated instances).',\n      },\n      paperclipPassword: {\n        type: 'string',\n        description: 'Board login password (for authenticated instances).',\n      },\n    },\n  },\n  entrypoints: {\n    worker: './dist/worker.js',\n    ui: './dist/ui',\n  },\n  ui: {\n    slots: [\n      {\n        type: 'page',\n        id: 'company-wizard',\n        displayName: 'Company Wizard',\n        exportName: 'WizardPage',\n        routePath: 'company-creator',\n      },\n      {\n        type: 'sidebar',\n        id: 'company-wizard-link',\n        displayName: 'Create Company',\n        exportName: 'SidebarLink',\n      },\n    ],\n  },\n};\n\nexport default manifest;\n"],
+  "sourcesContent": ["import type { PaperclipPluginManifestV1 } from '@paperclipai/plugin-sdk';\n\nconst manifest: PaperclipPluginManifestV1 = {\n  id: 'starlein.paperclip-plugin-company-wizard',\n  apiVersion: 1,\n  version: '0.4.17',\n  displayName: 'Company Wizard',\n  description: 'AI-powered wizard to bootstrap agent companies from composable templates',\n  author: 'Sascha Pietrowski <sp@speednetwork.de>',\n  categories: ['workspace', 'ui'],\n  capabilities: [\n    'companies.read',\n    'issues.create',\n    'issues.read',\n    'issues.update',\n    'goals.create',\n    'goals.read',\n    'agents.read',\n    'projects.read',\n    'plugin.state.read',\n    'plugin.state.write',\n    'secrets.read-ref',\n    'events.subscribe',\n    'ui.page.register',\n    'ui.sidebar.register',\n  ],\n  instanceConfigSchema: {\n    type: 'object',\n    properties: {\n      companiesDir: {\n        type: 'string',\n        description:\n          'Directory where assembled company workspaces are written. Auto-detected: ~/instances/default/companies in Docker setups, ~/.paperclip/instances/default/companies otherwise. Rarely needs manual override.',\n      },\n      templatesPath: {\n        type: 'string',\n        description:\n          'Path to the templates directory. Auto-detected: ~/plugin-templates in Docker setups, ~/.paperclip/plugin-templates otherwise. Rarely needs manual override.',\n      },\n      templatesRepoUrl: {\n        type: 'string',\n        default: 'https://github.com/starlein/paperclip-plugin-company-wizard/tree/main/templates',\n        description:\n          'GitHub tree URL for template downloads. The default is correct for most setups \u2014 only change this if using a custom fork.',\n      },\n      anthropicApiKey: {\n        type: 'string',\n        description:\n          'Anthropic API key for the AI wizard (e.g. sk-ant-...). Required to use the AI-powered company setup path.',\n      },\n      paperclipUrl: {\n        type: 'string',\n        description:\n          'Paperclip instance URL. Defaults to http://localhost:3100 or the PAPERCLIP_PUBLIC_URL env var.',\n      },\n      paperclipEmail: {\n        type: 'string',\n        description: 'Board login email (for authenticated instances).',\n      },\n      paperclipPassword: {\n        type: 'string',\n        description: 'Board login password (for authenticated instances).',\n      },\n    },\n  },\n  entrypoints: {\n    worker: './dist/worker.js',\n    ui: './dist/ui',\n  },\n  ui: {\n    slots: [\n      {\n        type: 'page',\n        id: 'company-wizard',\n        displayName: 'Company Wizard',\n        exportName: 'WizardPage',\n        routePath: 'company-creator',\n      },\n      {\n        type: 'sidebar',\n        id: 'company-wizard-link',\n        displayName: 'Create Company',\n        exportName: 'SidebarLink',\n      },\n    ],\n  },\n};\n\nexport default manifest;\n"],
   "mappings": ";AAEA,IAAM,WAAsC;AAAA,EAC1C,IAAI;AAAA,EACJ,YAAY;AAAA,EACZ,SAAS;AAAA,EACT,aAAa;AAAA,EACb,aAAa;AAAA,EACb,QAAQ;AAAA,EACR,YAAY,CAAC,aAAa,IAAI;AAAA,EAC9B,cAAc;AAAA,IACZ;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AAAA,EACA,sBAAsB;AAAA,IACpB,MAAM;AAAA,IACN,YAAY;AAAA,MACV,cAAc;AAAA,QACZ,MAAM;AAAA,QACN,aACE;AAAA,MACJ;AAAA,MACA,eAAe;AAAA,QACb,MAAM;AAAA,QACN,aACE;AAAA,MACJ;AAAA,MACA,kBAAkB;AAAA,QAChB,MAAM;AAAA,QACN,SAAS;AAAA,QACT,aACE;AAAA,MACJ;AAAA,MACA,iBAAiB;AAAA,QACf,MAAM;AAAA,QACN,aACE;AAAA,MACJ;AAAA,MACA,cAAc;AAAA,QACZ,MAAM;AAAA,QACN,aACE;AAAA,MACJ;AAAA,MACA,gBAAgB;AAAA,QACd,MAAM;AAAA,QACN,aAAa;AAAA,MACf;AAAA,MACA,mBAAmB;AAAA,QACjB,MAAM;AAAA,QACN,aAAa;AAAA,MACf;AAAA,IACF;AAAA,EACF;AAAA,EACA,aAAa;AAAA,IACX,QAAQ;AAAA,IACR,IAAI;AAAA,EACN;AAAA,EACA,IAAI;AAAA,IACF,OAAO;AAAA,MACL;AAAA,QACE,MAAM;AAAA,QACN,IAAI;AAAA,QACJ,aAAa;AAAA,QACb,YAAY;AAAA,QACZ,WAAW;AAAA,MACb;AAAA,MACA;AAAA,QACE,MAAM;AAAA,QACN,IAAI;AAAA,QACJ,aAAa;AAAA,QACb,YAAY;AAAA,MACd;AAAA,IACF;AAAA,EACF;AACF;AAEA,IAAO,mBAAQ;",
   "names": []
 }

package/dist/worker.js

@@ -9319,8 +9319,11 @@ function buildAdapterConfig({
   delete adapterConfig.reasoningEffort;
   delete adapterConfig.effort;
   if (adapterType === "codex_local") {
-    adapterConfig.modelReasoningEffort = thinkingLevel;
-    adapterConfig.thinkingLevel = thinkingLevel;
+    const codexEffort = thinkingLevel && thinkingLevel !== "auto" ? thinkingLevel : "";
+    if (codexEffort) {
+      adapterConfig.modelReasoningEffort = codexEffort;
+      adapterConfig.thinkingLevel = codexEffort;
+    }
     adapterConfig.dangerouslyBypassApprovalsAndSandbox = true;
   } else if (adapterType === "claude_local") {
     adapterConfig.dangerouslySkipPermissions = true;
@@ -9730,7 +9733,7 @@ ${stages.join("\n")}
       await appendToFile(
         join(companyDir, "agents", roleName, "AGENTS.md"),
         `
-Read and follow: \`$AGENT_HOME/skills/${fileName}\`
+Read and follow: \`skills/${fileName}\`
 `
       );
       const sourceTag = resolved.source === "shared" ? ", shared" : "";
@@ -9769,7 +9772,7 @@ Read and follow: \`$AGENT_HOME/skills/${fileName}\`
           await appendToFile(
             join(companyDir, "agents", role.name, "AGENTS.md"),
             `
-Read and follow: \`$AGENT_HOME/skills/${skillFile}\`
+Read and follow: \`skills/${skillFile}\`
 `
           );
           onProgress(`+ agents/${role.name}/skills/${skillFile} (${moduleName})`);
@@ -9837,10 +9840,10 @@ Read and follow: \`$AGENT_HOME/skills/${skillFile}\`
           return !roles || roles.has("*") || roles.has(role.name);
         });
         if (relevantDocs.length === 0) continue;
-        let docRefs = "\n## Shared Documentation\n\nReference docs relevant to your role (paths are relative to your workspace home):\n";
+        let docRefs = "\n## Shared Documentation\n\nReference docs relevant to your role (paths are relative to this AGENTS.md, in the shared company docs dir):\n";
         for (const doc of relevantDocs) {
           docRefs += `
-Read: \`docs/${doc}\`
+Read: \`../../docs/${doc}\`
 `;
         }
         await appendToFile(agentsMd, docRefs);
@@ -9852,7 +9855,6 @@ Read: \`docs/${doc}\`
     const agentRoleDirs = await readdir(agentsBaseDirForSubst, { withFileTypes: true });
     for (const roleDir of agentRoleDirs) {
       if (!roleDir.isDirectory()) continue;
-      const absoluteAgentHome = join(agentsBaseDirForSubst, roleDir.name);
       const subst = async (dir) => {
         const entries = await readdir(dir, { withFileTypes: true });
         for (const entry of entries) {
@@ -9861,8 +9863,8 @@ Read: \`docs/${doc}\`
             await subst(full);
           } else if (entry.name.endsWith(".md")) {
             const content = await readFile(full, "utf-8");
-            if (content.includes("$AGENT_HOME")) {
-              await writeFile(full, content.split("$AGENT_HOME").join(absoluteAgentHome));
+            if (content.includes("$AGENT_HOME/")) {
+              await writeFile(full, content.split("$AGENT_HOME/").join(""));
             }
           }
         }
@@ -9909,8 +9911,11 @@ Read: \`docs/${doc}\`
       }
     }
     if (adapterType === DEFAULT_CEO_ADAPTER_TYPE) {
-      adapterConfig.modelReasoningEffort = thinkingLevel;
-      adapterConfig.thinkingLevel = thinkingLevel;
+      const codexEffort = thinkingLevel && thinkingLevel !== "auto" ? thinkingLevel : "";
+      if (codexEffort) {
+        adapterConfig.modelReasoningEffort = codexEffort;
+        adapterConfig.thinkingLevel = codexEffort;
+      }
       adapterConfig.dangerouslyBypassApprovalsAndSandbox = true;
     }
     return { adapterType, adapterConfig };
@@ -10079,7 +10084,7 @@ Read: \`docs/${doc}\`
       if (repoUrl) workspace.repoUrl = repoUrl;
       if (repoRef) workspace.repoRef = repoRef;
       if (defaultRef) workspace.defaultRef = defaultRef;
-      delete workspace.cwd;
+      if (!workspace.cwd) workspace.cwd = localCwd;
     } else {
       if (!workspace.cwd) workspace.cwd = localCwd;
       const trimmedSetup = typeof workspace.setupCommand === "string" ? workspace.setupCommand.trim() : "";
@@ -11023,7 +11028,7 @@ var __dirname = path2.dirname(fileURLToPath2(import.meta.url));
 var DEFAULT_TEMPLATES_REPO_URL = "https://github.com/starlein/paperclip-plugin-company-wizard/tree/main/templates";
 var BUNDLED_TEMPLATES_DIR = path2.resolve(__dirname, "..", "templates");
 var PLUGIN_PACKAGE_NAME = "@starlein/paperclip-plugin-company-wizard";
-var CURRENT_PLUGIN_VERSION = "0.4.13";
+var CURRENT_PLUGIN_VERSION = "0.4.16";
 var NPM_LATEST_URL = "https://registry.npmjs.org/@starlein%2Fpaperclip-plugin-company-wizard/latest";
 function copyDirSync(src, dest) {
   fs2.mkdirSync(dest, { recursive: true });
@@ -11102,6 +11107,21 @@ async function ensureTemplatesDir(cfg) {
     );
   }
 }
+function resolveTemplatesCacheDir(cfg) {
+  if (cfg.templatesPath) return cfg.templatesPath;
+  if (isDockerLayout()) return path2.join(os.homedir(), "plugin-templates");
+  return path2.join(os.homedir(), ".paperclip", "plugin-templates");
+}
+function refreshTemplatesCache(cfg, log) {
+  const repoUrl = cfg.templatesRepoUrl || DEFAULT_TEMPLATES_REPO_URL;
+  const targetDir = resolveTemplatesCacheDir(cfg);
+  if (fs2.existsSync(targetDir)) {
+    fs2.rmSync(targetDir, { recursive: true, force: true });
+  }
+  downloadTemplatesFromGithub(targetDir, repoUrl);
+  log?.(`\u2713 Refreshed templates cache from ${repoUrl} \u2192 ${targetDir}`);
+  return targetDir;
+}
 function isLikelyAnthropicApiKey(value) {
   return value.startsWith("sk-ant-");
 }
@@ -11344,57 +11364,24 @@ function prepareLocalProjectWorkspace(mainProject, companyDir, log, gitIdentity)
 function formatRoleName(role) {
   return role.split("-").map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
 }
-function collectInstructionFiles(rootDir) {
-  const out = {};
-  if (!fs2.existsSync(rootDir)) return out;
-  const walk = (dir) => {
-    for (const entry of fs2.readdirSync(dir, { withFileTypes: true })) {
-      const abs = path2.join(dir, entry.name);
-      if (entry.isDirectory()) {
-        walk(abs);
-        continue;
-      }
-      if (!entry.isFile()) continue;
-      const rel = path2.relative(rootDir, abs).split(path2.sep).join("/");
-      out[rel] = fs2.readFileSync(abs, "utf-8");
-    }
-  };
-  walk(rootDir);
-  return out;
-}
-async function syncAgentInstructionsIntoManagedBundle({
+async function setExternalInstructionsBundle({
   client,
   agentId,
   sourceDir,
   entryFile,
-  fallbackEntryContent,
   log
 }) {
   try {
     await client.updateInstructionsBundle(agentId, {
-      mode: "managed",
+      mode: "external",
+      rootPath: sourceDir,
       entryFile,
       clearLegacyPromptTemplate: true
     });
-    const files = collectInstructionFiles(sourceDir);
-    if (!files[entryFile] && typeof fallbackEntryContent === "string" && fallbackEntryContent.trim()) {
-      files[entryFile] = fallbackEntryContent;
-    }
-    const entries = Object.entries(files).sort(([a], [b]) => a.localeCompare(b));
-    if (entries.length === 0) {
-      log("\u26A0 No instruction files found to sync into managed bundle.");
-      return;
-    }
-    for (const [relativePath, content] of entries) {
-      await client.upsertInstructionsBundleFile(agentId, {
-        path: relativePath,
-        content
-      });
-    }
-    log(`\u2713 Synced ${entries.length} instruction file(s) into managed bundle`);
+    log(`\u2713 Pointed instructions at external dir ${sourceDir} (entry ${entryFile})`);
   } catch (err) {
     log(
-      `\u26A0 Could not sync managed instructions bundle: ${err instanceof Error ? err.message : String(err)}`
+      `\u26A0 Could not set external instructions bundle: ${err instanceof Error ? err.message : String(err)}`
     );
   }
 }
@@ -11627,13 +11614,8 @@ var plugin = definePlugin({
     ctx.actions.register("refresh-templates", async () => {
       try {
         const cfg = await ctx.config.get() ?? {};
-        const repoUrl = cfg.templatesRepoUrl || DEFAULT_TEMPLATES_REPO_URL;
-        const targetDir = cfg.templatesPath || path2.join(os.homedir(), ".paperclip", "plugin-templates");
-        if (fs2.existsSync(targetDir)) {
-          fs2.rmSync(targetDir, { recursive: true, force: true });
-        }
-        downloadTemplatesFromGithub(targetDir, repoUrl);
-        return { ok: true };
+        const targetDir = refreshTemplatesCache(cfg);
+        return { ok: true, targetDir };
       } catch (err) {
         return { ok: false, error: err instanceof Error ? err.message : String(err) };
       }
@@ -12035,6 +12017,17 @@ var plugin = definePlugin({
         const companyName = typeof params.companyName === "string" ? params.companyName.trim() : "";
         const existingCompanyId = typeof params.existingCompanyId === "string" && params.existingCompanyId.trim() ? params.existingCompanyId.trim() : "";
         if (!companyName) return { error: "companyName is required", logs };
+        if (params.refreshTemplates !== false && !cfg.templatesPath) {
+          try {
+            refreshTemplatesCache(cfg, log);
+          } catch (err) {
+            log(
+              `\u26A0 Could not refresh templates cache (${err instanceof Error ? err.message : String(err)}); using existing cache.`
+            );
+          }
+        } else if (cfg.templatesPath) {
+          log(`Using configured templatesPath (${cfg.templatesPath}); skipping auto-refresh.`);
+        }
         const templatesDir = await ensureTemplatesDir(cfg);
         const [presets, allModules, roleTemplates] = await Promise.all([
           loadPresets(templatesDir),
@@ -12102,7 +12095,11 @@ var plugin = definePlugin({
         const ceoInstructionsDir = path2.join(companyDir, "agents", "ceo");
         const ceoEntryFile = "AGENTS.md";
         const ceoEntryPath = path2.join(ceoInstructionsDir, ceoEntryFile);
-        const ceoPromptTemplate = fs2.existsSync(ceoEntryPath) ? fs2.readFileSync(ceoEntryPath, "utf-8") : "";
+        if (!fs2.existsSync(ceoEntryPath)) {
+          log(
+            `\u26A0 Assembled CEO entry file missing at ${ceoEntryPath}; external bundle may be empty.`
+          );
+        }
         log("");
         log(`\u2713 Generated files: ${companyDir}`);
         let company;
@@ -12216,11 +12213,7 @@ var plugin = definePlugin({
             companyDir,
             roleAdapterOverrides: assembleResult.roleAdapterOverrides?.get("ceo") ?? {}
           });
-          const ceoInstructionFiles = collectInstructionFiles(ceoInstructionsDir);
-          if (!ceoInstructionFiles[ceoEntryFile] && typeof ceoPromptTemplate === "string" && ceoPromptTemplate.trim()) {
-            ceoInstructionFiles[ceoEntryFile] = ceoPromptTemplate;
-          }
-          const ceoInstructionsBundle = Object.keys(ceoInstructionFiles).length > 0 ? { entryFile: ceoEntryFile, files: ceoInstructionFiles } : void 0;
+          adapterConfig.instructionsFilePath = ceoEntryPath;
           const logPendingApproval = (agent) => {
             if (!agent?._pendingApprovalId) return;
             log(
@@ -12268,7 +12261,6 @@ var plugin = definePlugin({
                 reportsTo: null,
                 adapterType,
                 adapterConfig,
-                instructionsBundle: ceoInstructionsBundle,
                 runtimeConfig: ceoRuntimeConfig,
                 permissions: { canCreateAgents: true },
                 ...boardOperationsIssue?.id ? { sourceIssueId: boardOperationsIssue.id } : {}
@@ -12288,7 +12280,6 @@ var plugin = definePlugin({
               reportsTo: null,
               adapterType,
               adapterConfig,
-              instructionsBundle: ceoInstructionsBundle,
               runtimeConfig: ceoRuntimeConfig,
               permissions: { canCreateAgents: true },
               ...boardOperationsIssue?.id ? { sourceIssueId: boardOperationsIssue.id } : {}
@@ -12297,12 +12288,11 @@ var plugin = definePlugin({
             log(`\u2713 CEO agent created (${ceoAgentId})`);
             logPendingApproval(ceoAgent);
           }
-          await syncAgentInstructionsIntoManagedBundle({
+          await setExternalInstructionsBundle({
             client,
             agentId: ceoAgentId,
             sourceDir: ceoInstructionsDir,
             entryFile: ceoEntryFile,
-            fallbackEntryContent: ceoPromptTemplate,
             log
           });
           for (const govIssue of [
@@ -12350,8 +12340,7 @@ var plugin = definePlugin({
               roleAdapterOverrides: assembleResult.roleAdapterOverrides?.get(roleName) ?? {}
             });
             const roleInstructionsDir = path2.join(companyDir, "agents", roleName);
-            const roleInstructionFiles = collectInstructionFiles(roleInstructionsDir);
-            const roleInstructionsBundle = Object.keys(roleInstructionFiles).length > 0 ? { entryFile: "AGENTS.md", files: roleInstructionFiles } : void 0;
+            roleAdapterConfig.instructionsFilePath = path2.join(roleInstructionsDir, "AGENTS.md");
             const existingAgent = existingByTemplateRole.get(roleName);
             if (existingAgent?.id) {
               try {
@@ -12370,7 +12359,7 @@ var plugin = definePlugin({
                 );
               }
               teamAgentIds[roleName] = existingAgent.id;
-              await syncAgentInstructionsIntoManagedBundle({
+              await setExternalInstructionsBundle({
                 client,
                 agentId: existingAgent.id,
                 sourceDir: roleInstructionsDir,
@@ -12389,11 +12378,17 @@ var plugin = definePlugin({
               reportsTo: ceoAgentId,
               adapterType,
               adapterConfig: roleAdapterConfig,
-              instructionsBundle: roleInstructionsBundle,
               runtimeConfig: roleRuntimeConfig,
               ...hiringPlanIssue?.id ? { sourceIssueId: hiringPlanIssue.id } : {}
             });
             teamAgentIds[roleName] = roleAgent.id;
+            await setExternalInstructionsBundle({
+              client,
+              agentId: roleAgent.id,
+              sourceDir: roleInstructionsDir,
+              entryFile: "AGENTS.md",
+              log
+            });
             log(`\u2713 ${roleTitle} created (${roleAgent.id})`);
             if (roleAgent?._pendingApprovalId) {
               log(