@starlein/paperclip-plugin-company-wizard 0.3.21 → 0.3.23

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

@@ -29,7 +29,7 @@
 #### Bootstrap reliability
 
 - **Agents provisioned with complete instructions** — every non-CEO agent is now created by the plugin directly with its full `instructionsBundle` (AGENTS.md + HEARTBEAT/SOUL/TOOLS + skills). Previously the CEO created these agents during bootstrap with only an `instructionsFilePath`, leaving each agent with a bare AGENTS.md and fragile external path references
-- **Routines created directly during provisioning** — Paperclip only allows an agent to create routines assigned to itself, so the CEO could not create routines owned by the Product Owner. The plugin now creates all routines with board authority at provisioning time; BOOTSTRAP.md tells the CEO they already exist
+- **Routines created directly during provisioning** — Paperclip only allows an agent to create routines assigned to itself, so the CEO could not create routines owned by the Product Owner. The plugin now creates all routines with board authority at provisioning time and pre-creates the main project so every routine — including those owned by non-CEO agents — is linked to it; BOOTSTRAP.md tells the CEO they already exist
 - **Worker agents no longer run always-on heartbeats** — enabling heartbeats on every provisioned agent caused bursts of concurrent runs that crashed the dev server. Only the CEO keeps an always-on heartbeat; all other agents are woken on assignment
 - **Fresh local repos no longer bootstrap with isolated git worktrees** — provisioning a brand-new `local_path` project with an `isolated_workspace` / `git_worktree` policy made worker agents try to branch off `main` before the repo existed, so early runs failed and agents flipped to `error`. The isolated policy is now suppressed for fresh local repos (agents work in the shared project workspace during bootstrap); existing external repos keep it. Guarded in `assemble.js` and removed at the source in `StepRepository` and the AI wizard prompts
 - **Workspace isolation follows Paperclip instance settings** — `enableIsolatedWorktrees` is no longer a plugin setting. The wizard reads `enableIsolatedWorkspaces` from the Paperclip instance experimental settings and only applies `isolated_workspace` / `git_worktree` for external repositories when that setting is enabled.
@@ -42,6 +42,7 @@
 - **Doc references use relative paths** (`docs/<file>`) instead of absolute paths that baked in the collision-suffixed company directory name
 - Duplicate bootstrap issues (same title from module + preset) are now deduplicated; preset issue wins
 - CFO role removed — was orphaned (no preset, no capability, never activated)
+- **PR bodies and comments use `--body-file`** — review skills posted GitHub PR bodies and comments with inline `gh pr … --body "..."`, where a double-quoted shell string keeps `\n` literal, so multi-line Markdown rendered as literal `text\ntext`. All PR-review guidance now writes Markdown to a file and uses `--body-file`, with a verdict-heading comment template documented in `pr-conventions.md`
 
 #### AI wizard
 

package/dist/manifest.js

@@ -2,7 +2,7 @@
 var manifest = {
   id: "starlein.paperclip-plugin-company-wizard",
   apiVersion: 1,
-  version: "0.3.21",
+  version: "0.3.23",
   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.21',\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.23',\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

@@ -10116,10 +10116,21 @@ Read: \`docs/${doc}\`
   };
   const mainProject = resolvedProjects[0];
   const mainProjectName = mainProject?.name || companyName;
+  const mainProjectInfo = mainProject ? {
+    name: mainProjectName,
+    description: mainProject.description || "",
+    workspace: normalizeProjectWorkspace(mainProject)
+  } : null;
+  const mainProjectPreCreated = initialRoutines.length > 0 && mainProjectInfo !== null;
   if (resolvedProjects.length > 0) {
     bootstrap += `## Projects
 
 `;
+    if (mainProjectPreCreated) {
+      bootstrap += `> **The Company Wizard has already created the main project "${mainProjectName}"** (with board authority) so the scheduled routines could be linked to it. Do NOT recreate it \u2014 create issues against it, and link the goals above to it.
+
+`;
+    }
     for (const proj of resolvedProjects) {
       const workspace = normalizeProjectWorkspace(proj);
       bootstrap += `### ${proj.name}
@@ -10312,14 +10323,20 @@ Read: \`docs/${doc}\`
     bootstrap += `${stepN++}. **Create goal** "${g.title}" (level: ${level}${parentNote})
 `;
   }
-  for (const proj of resolvedProjects) {
+  resolvedProjects.forEach((proj, idx) => {
     const workspace = normalizeProjectWorkspace(proj);
     const goalLinks = proj.goals?.length > 0 ? `, goalIds \u2192 [${proj.goals.map((g) => `"${g}"`).join(", ")}]` : "";
     const activePolicy = effectiveExecutionPolicy(proj, workspace);
     const policy = activePolicy?.defaultMode ? `, executionWorkspacePolicy.defaultMode: "${activePolicy.defaultMode}"` : "";
-    bootstrap += `${stepN++}. **Create project** "${proj.name}" (workspace: ${formatWorkspaceObject(workspace)}${policy}${goalLinks})
+    if (idx === 0 && mainProjectPreCreated) {
+      const goalLinkInstruction = goalLinks ? ` After creating the goals above, link them to it (${goalLinks.replace(/^, /, "")}).` : "";
+      bootstrap += `${stepN++}. **Main project already created** \u2014 the Company Wizard provisioned project "${proj.name}" (with board authority) so the scheduled routines could be linked to it. Do NOT recreate it.${goalLinkInstruction}
 `;
-  }
+    } else {
+      bootstrap += `${stepN++}. **Create project** "${proj.name}" (workspace: ${formatWorkspaceObject(workspace)}${policy}${goalLinks})
+`;
+    }
+  });
   if (bootstrapLabels.length > 0) {
     bootstrap += `${stepN++}. **Create labels** \u2014 create each label exactly as listed in the Labels section before creating issues
 `;
@@ -10338,7 +10355,14 @@ Read: \`docs/${doc}\`
 `;
   await writeFile(join(companyDir, "BOOTSTRAP.md"), bootstrap);
   onProgress("+ BOOTSTRAP.md");
-  return { companyDir, allRoles, initialIssues, initialRoutines, roleAdapterOverrides };
+  return {
+    companyDir,
+    allRoles,
+    initialIssues,
+    initialRoutines,
+    roleAdapterOverrides,
+    mainProject: mainProjectInfo
+  };
 }
 
 // src/api/client.js
@@ -11599,6 +11623,25 @@ var plugin = definePlugin({
           }
           if (!existingCompanyId) {
             const routines = Array.isArray(assembleResult.initialRoutines) ? assembleResult.initialRoutines : [];
+            let mainProjectId;
+            const mainProject = assembleResult.mainProject;
+            if (routines.length > 0 && mainProject?.name) {
+              try {
+                const createdProject = await client.createProject(companyId, {
+                  name: mainProject.name,
+                  description: mainProject.description,
+                  workspace: mainProject.workspace
+                });
+                mainProjectId = createdProject?.id;
+                log(
+                  `\u2713 Main project "${mainProject.name}" created${mainProjectId ? ` (${mainProjectId})` : " (no id returned)"}`
+                );
+              } catch (err) {
+                log(
+                  `\u26A0 Could not create main project "${mainProject.name}": ${err instanceof Error ? err.message : String(err)}. Routines will be created without a project.`
+                );
+              }
+            }
             for (const routine of routines) {
               const title = typeof routine.title === "string" && routine.title.trim() ? routine.title.trim() : typeof routine.name === "string" ? routine.name.trim() : "";
               if (!title) continue;
@@ -11609,6 +11652,7 @@ var plugin = definePlugin({
                   title,
                   description: routine.description,
                   assigneeAgentId,
+                  projectId: mainProjectId,
                   priority: routine.priority || "medium",
                   concurrencyPolicy: routine.concurrencyPolicy || "skip_if_active"
                 });