@starlein/paperclip-plugin-company-wizard 0.3.22 → 0.3.24

package/CONTRIBUTING.md

@@ -0,0 +1,90 @@
+# Contributing to Company Wizard
+
+Thanks for your interest in contributing! Company Wizard is a [Paperclip](https://github.com/paperclipai/paperclip) plugin that bootstraps agent company workspaces from composable templates.
+
+## Getting Started
+
+```sh
+git clone <repo-url>
+cd paperclip-plugin-company-wizard
+pnpm install
+pnpm build
+```
+
+## Development
+
+```sh
+pnpm build           # esbuild: worker + manifest + UI → dist/
+pnpm dev             # watch mode (rebuilds on change)
+pnpm test            # vitest: tests/**/*.spec.ts
+pnpm test:logic      # node --test: src/logic/*.test.js
+pnpm typecheck       # tsc --noEmit
+```
+
+Load the plugin in Paperclip by pointing to this directory (the `paperclipPlugin` field in `package.json` tells Paperclip where to find the built artifacts). After `pnpm build`, reload the plugin in the Paperclip UI — no reinstall required.
+
+## Project Structure
+
+```text
+src/
+├── worker.ts             # Plugin worker: actions (preview-files, start-provision, check-auth)
+├── manifest.ts           # Plugin manifest (id, displayName, slots)
+├── logic/                # Pure functions (assembly, resolution, template loading)
+├── api/                  # Paperclip REST API client and provisioning
+└── ui/
+    ├── main.tsx          # UI entry point
+    ├── context/          # WizardContext (state machine + reducer)
+    └── components/       # React components (WizardShell, step components, ConfigReview)
+
+templates/
+├── roles/                # All roles with role.meta.json (base: true for always-present)
+├── modules/              # Composable capabilities with module.meta.json
+└── presets/              # Curated module+role combinations with preset.meta.json
+```
+
+## Adding Templates
+
+### New module
+
+See [docs/TEMPLATES.md](docs/TEMPLATES.md) for the full module schema. Key points:
+
+- Every capability needs a shared skill in `skills/<skill>.md`
+- Role-specific overrides go in `agents/<role>/skills/<skill>.md` (only when genuinely different)
+- Fallback variants are always role-specific (`.fallback.md`)
+- Add `node --test` tests in `src/logic/` if the module has non-trivial resolution logic
+
+### New role
+
+See [docs/TEMPLATES.md](docs/TEMPLATES.md). Map `paperclipRole` to a valid Paperclip enum value. Set `base: true` only for roles that belong in every company (only the CEO currently has `base: true`).
+
+### New preset
+
+See [docs/TEMPLATES.md](docs/TEMPLATES.md). Test that the module combination resolves correctly. Presets can include inline `goals[]` arrays with milestones and issues.
+
+## Pull Requests
+
+- Keep PRs focused — one feature or fix per PR
+- Add or update tests for logic changes
+- Run `pnpm test && pnpm test:logic` before submitting
+- Update `docs/TEMPLATES.md` if you add modules, roles, or presets
+- Update `CHANGELOG.md` with your changes
+
+## Code Style
+
+- TypeScript for plugin infrastructure (`src/worker.ts`, `src/manifest.ts`, `src/ui/`)
+- ESM only (`type: "module"`)
+- Plain JS for logic/API modules (`src/logic/`, `src/api/`) — JSDoc where helpful
+- Prettier via pre-commit hook (lint-staged)
+
+## Reporting Issues
+
+Use GitHub Issues. Include:
+
+- What you expected vs what happened
+- Plugin version (from `package.json`)
+- Node.js version (`node --version`)
+- OS
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).

package/README.md

@@ -1,5 +1,4 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/starlein/paperclip-plugin-company-wizard/main/public/favicon.svg" alt="Company Wizard" width="48" height="48">
   <h1 align="center">Company Wizard</h1>
   <p align="center">
     <strong>Bootstrap AI agent teams from modular templates.</strong>
@@ -10,6 +9,8 @@
     <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License"></a>
     <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen" alt="Node.js"></a>
   </p>
+<hr>
+  <img src="https://raw.githubusercontent.com/starlein/paperclip-plugin-company-wizard/main/docs/GIF-Screencast-Paperclip-Plugin-Company-Wizard.gif" alt="Screencast Paperclip Plugin Company Wizard" height="240">
 </p>
 
 ---
@@ -160,7 +161,7 @@ Start with just a CEO. Everything works. Add roles and responsibilities shift au
 | `tech-stack` | Engineer | CEO | tech-stack |
 | `architecture-plan` | Engineer | CEO | architecture-plan |
 | `design-system` | UI Designer | Engineer | architecture-plan |
-| `pr-review` | Code Reviewer / Product Owner / UI Designer / UX Researcher / QA / DevOps | — | pr-review |
+| `pr-review` | QA (gate) / Security Engineer (security-relevant) / Product Owner (approval) / Engineer (merge); Code Reviewer / UI / UX / DevOps advisory | — | pr-review |
 | `threat-model` | Security Engineer → DevOps | Engineer | security-audit |
 | `security-review` | Security Engineer → DevOps | Engineer | security-audit |
 | `project-docs` | Technical Writer → Engineer | CEO | documentation |

package/dist/manifest.js

@@ -2,7 +2,7 @@
 var manifest = {
   id: "starlein.paperclip-plugin-company-wizard",
   apiVersion: 1,
-  version: "0.3.22",
+  version: "0.3.24",
   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.3.22',\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. Defaults to ~/.paperclip/instances/default/companies. Override for Docker setups (e.g. /paperclip/instances/default/companies).',\n      },\n      templatesPath: {\n        type: 'string',\n        description:\n          'Path to the templates directory. Defaults to ~/.paperclip/plugin-templates (auto-downloaded from templatesRepoUrl if missing). Override for Docker setups (e.g. /paperclip/plugin-templates).',\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 to pull templates from when the templates directory does not exist.',\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      disableBoardApprovalOnNewCompanies: {\n        type: 'boolean',\n        default: false,\n        description:\n          'Optional. If true, the wizard will PATCH new companies to set requireBoardApprovalForNewAgents=false during provisioning. Leave false to preserve approval-gated hiring policies.',\n      },\n      enableEnrichedPersonas: {\n        type: 'boolean',\n        default: false,\n        description:\n          'Optional. If true, expert roles are enriched with domain lenses (named mental models), module skills gain concrete output/review bars with negative examples, and HEARTBEAT.md gains explicit done-criteria. Leave false (default) for the lean baseline personas.',\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.3.24',\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. Defaults to ~/.paperclip/instances/default/companies. Override for Docker setups (e.g. /paperclip/instances/default/companies).',\n      },\n      templatesPath: {\n        type: 'string',\n        description:\n          'Path to the templates directory. Defaults to ~/.paperclip/plugin-templates (auto-downloaded from templatesRepoUrl if missing). Override for Docker setups (e.g. /paperclip/plugin-templates).',\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 to pull templates from when the templates directory does not exist.',\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      disableBoardApprovalOnNewCompanies: {\n        type: 'boolean',\n        default: false,\n        description:\n          'Optional. If true, the wizard will PATCH new companies to set requireBoardApprovalForNewAgents=false during provisioning. Leave false to preserve approval-gated hiring policies.',\n      },\n      enableEnrichedPersonas: {\n        type: 'boolean',\n        default: false,\n        description:\n          'Optional. If true, expert roles are enriched with domain lenses (named mental models), module skills gain concrete output/review bars with negative examples, and HEARTBEAT.md gains explicit done-criteria. Leave false (default) for the lean baseline personas.',\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,MACA,oCAAoC;AAAA,QAClC,MAAM;AAAA,QACN,SAAS;AAAA,QACT,aACE;AAAA,MACJ;AAAA,MACA,wBAAwB;AAAA,QACtB,MAAM;AAAA,QACN,SAAS;AAAA,QACT,aACE;AAAA,MACJ;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

@@ -9551,6 +9551,7 @@ async function assembleCompany({
     if (reviewers.length === 0 && !approver && !mergeGate) return null;
     return { reviewers, approver, mergeGate };
   };
+  const hasCi = moduleNames.includes("ci-cd");
   const renderReviewGate = (gate) => {
     const stages = [];
     for (const role of gate.reviewers) {
@@ -9562,12 +9563,14 @@ async function assembleCompany({
       );
     }
     if (gate.mergeGate) {
+      const gatePrecondition = hasCi ? "CI must be green before merge" : "no CI configured \u2014 run the test suite/build and paste the output before merge";
       stages.push(
-        `  - stage ${stages.length + 1} (approval) \u2192 assign ${JSON.stringify(gate.mergeGate)}  \u2014 merge gate: merge the PR, then record approved to close`
+        `  - stage ${stages.length + 1} (approval) \u2192 assign ${JSON.stringify(gate.mergeGate)}  \u2014 merge gate: ${gatePrecondition}; merge the PR, then record approved to close`
       );
     }
     return `- **executionPolicy** (set when creating this issue; resolve each role to its agentId):
 ${stages.join("\n")}
+  - every verdict must cite executed verification (commands + results); "looks good" without evidence is not a valid verdict
 
 `;
   };
@@ -10274,7 +10277,8 @@ Read: \`docs/${doc}\`
     bootstrap += `- Do not reuse parent workspaces for subissues unless explicitly requested.
 `;
     if (moduleNames.includes("pr-review")) {
-      bootstrap += `- Required PR reviews use the issue's \`executionPolicy\`: a \`review\` stage for the Code Reviewer (plus any relevant domain reviewer \u2014 QA/UI/UX/DevOps), an \`approval\` stage for the Product Owner, then a final \`approval\` merge-gate stage for the Engineer (who merges the PR before recording approval, which closes the issue). The merge gate must be last so the Product Owner's approval does not auto-close the issue with the PR still open. Resolve each role to its agentId. Do not create separate child review issues and do not use @-mentions.
+      const ciClause = hasCi ? "CI (lint/test/build) must be green before the Engineer merges \u2014 this is the hard gate and cannot be skipped" : "no CI is configured, so the Engineer must run the test suite/build and paste the real output into the merge-gate verdict before merging \u2014 this is the hard gate";
+      bootstrap += `- Required PR reviews use the issue's \`executionPolicy\`. The substantive gate is execution, not opinion: ${ciClause}. Stages, in order: a \`review\` stage for QA when present (test adequacy / running the tests), a \`review\` stage for the Security Engineer **only when the change is security-relevant** (auth, secrets, input boundaries, crypto, dependencies, infra exposure), an \`approval\` stage for the Product Owner (intent/scope), then a final \`approval\` merge-gate stage for the Engineer (who satisfies the hard gate above, merges the PR, then records approval to close the issue). The merge gate must be last so the Product Owner's approval does not auto-close the issue with the PR still open. The Code Reviewer and other domain reviewers may add advisory, non-blocking comments but do not gate the merge. Every verdict must cite executed verification. Resolve each role to its agentId. Do not create separate child review issues and do not use @-mentions.
 `;
     }
     bootstrap += `
@@ -11090,6 +11094,49 @@ function resolveCompaniesDir(cfg) {
   if (cfg.companiesDir) return cfg.companiesDir;
   return path2.join(os.homedir(), ".paperclip", "instances", "default", "companies");
 }
+function mkdirErrorMessage(err) {
+  if (err instanceof Error) return err.message;
+  return String(err);
+}
+function ensureWritableDir(dir) {
+  fs2.mkdirSync(dir, { recursive: true });
+  fs2.accessSync(dir, fs2.constants.W_OK);
+}
+function resolveWritableCompaniesDir(cfg, log) {
+  const configuredDir = typeof cfg.companiesDir === "string" ? cfg.companiesDir.trim() : "";
+  if (configuredDir) {
+    try {
+      ensureWritableDir(configuredDir);
+      return configuredDir;
+    } catch (err) {
+      throw new Error(
+        `Configured companiesDir is not writable (${configuredDir}): ${mkdirErrorMessage(err)}`
+      );
+    }
+  }
+  const candidates = [
+    resolveCompaniesDir(cfg),
+    path2.join("/paperclip", "instances", "default", "companies"),
+    path2.join(os.tmpdir(), "paperclip-companies")
+  ];
+  const attempted = /* @__PURE__ */ new Set();
+  let lastError = "";
+  for (const candidate of candidates) {
+    if (attempted.has(candidate)) continue;
+    attempted.add(candidate);
+    try {
+      ensureWritableDir(candidate);
+      return candidate;
+    } catch (err) {
+      const message = mkdirErrorMessage(err);
+      lastError = `${candidate}: ${message}`;
+      if (log) log(`\u26A0 Companies dir unavailable: ${candidate} (${message})`);
+    }
+  }
+  throw new Error(
+    `Unable to prepare a writable companies directory. Last attempt failed at ${lastError}`
+  );
+}
 function formatRoleName(role) {
   return role.split("-").map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
 }
@@ -11197,7 +11244,7 @@ var plugin = definePlugin({
         const companyName = typeof params.companyName === "string" && params.companyName.trim() ? params.companyName.trim() : "Preview";
         const templatesDir = await ensureTemplatesDir(cfg);
         tmpDir = path2.join(os.tmpdir(), `company-wizard-preview-${Date.now()}`);
-        const companiesDir = resolveCompaniesDir(cfg);
+        const companiesDir = resolveWritableCompaniesDir(cfg);
         const [presets, allModules] = await Promise.all([
           loadPresets(templatesDir),
           loadModules(templatesDir)
@@ -11352,8 +11399,7 @@ var plugin = definePlugin({
         );
         const goals = collectGoals(selectedPreset, allModules, new Set(effectiveModules));
         const presetBootstrapData = collectPresetBootstrapData(selectedPreset);
-        const outputDir = resolveCompaniesDir(cfg);
-        fs2.mkdirSync(outputDir, { recursive: true });
+        const outputDir = resolveWritableCompaniesDir(cfg, log);
         log("Assembling company workspace...");
         const companyDescription = typeof params.companyDescription === "string" ? params.companyDescription.trim() : "";
         const userGoals = Array.isArray(params.goals) ? params.goals : params.goal ? [params.goal] : [];
@@ -11750,6 +11796,7 @@ var plugin = definePlugin({
 var worker_default = plugin;
 runWorker(plugin, import.meta.url);
 export {
-  worker_default as default
+  worker_default as default,
+  resolveWritableCompaniesDir
 };
 //# sourceMappingURL=worker.js.map