@starlein/paperclip-plugin-company-wizard 0.2.4 → 0.3.18

package/README.md

@@ -14,6 +14,60 @@
 
 ---
 
+> **Fork:** This is a community-maintained fork of [yesterday-AI/paperclip-plugin-company-wizard](https://github.com/yesterday-AI/paperclip-plugin-company-wizard), updated for the current Paperclip API (`>=2026.529.0`) with substantial bug fixes. End-to-end company setup is largely functional as of v0.3.18.
+
+<details>
+<summary><strong>What changed vs. upstream</strong></summary>
+
+#### Paperclip API compatibility
+
+- Bootstrap metadata fields renamed to match the Paperclip API exactly: `parentId`, `assigneeAgentId`, `projectId`, `goalIds`
+- CEO is provisioned with correct `capabilities` metadata so newly created CEOs are no longer saved with empty summaries
+- `@paperclipai/plugin-sdk` and `@paperclipai/shared` declared as `peerDependencies` with minimum version `>=2026.529.0` — the host provides the SDK at runtime (externalized from the bundle)
+- `security-engineer` role now maps to the dedicated Paperclip `security` enum value (was `general`)
+
+#### 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
+- **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.
+- Bootstrap ordering hardened; agent filter bug fixed (v0.3.7)
+
+#### Assembly and template fixes
+
+- **Broken `$AGENT_HOME` references** rewritten to absolute paths under `companyDir/agents/<role>/` and `companyDir/docs/` — `AGENT_HOME` points to a per-agent workspace dir that does not contain provisioned files
+- **Shared docs scoped per role** — each agent's AGENTS.md now lists only docs from modules relevant to that role (CEO still sees all); previously every agent was told to read every module's docs
+- **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)
+
+#### AI wizard
+
+- Config generation uses `claude-opus-4-8` with `max_tokens: 32768` so a full-spec config is never truncated mid-JSON
+- All Anthropic calls run as background jobs in the worker (start + poll), eliminating the 30 s RPC timeout that previously crashed config generation
+- AI wizard now generates domain-specific initial issues from the project brief that lead the bootstrap backlog ahead of generic scaffolding issues
+- Preset roles are defensively merged with AI-selected roles so preset roles are no longer silently dropped
+
+#### Error handling
+
+- All worker actions return `{ error }` instead of throwing — prevents the plugin host from swallowing error messages in generic 502 responses
+- Network errors in `PaperclipClient` are caught and surfaced with actionable messages referencing the `paperclipUrl` plugin setting
+
+#### New features (not in upstream)
+
+- **Existing-company provisioning** — target an existing Paperclip company instead of creating a new one (`existingCompanyId`); partial-failure cleanup never deletes existing companies
+- **Approval-aware agent hiring** — detects board-approval requirements, falls back to `/agent-hires` + auto-approve; surfaces pending approval ID if auto-approve fails
+- **`disableBoardApprovalOnNewCompanies` setting** — optionally patches new companies to skip board approval for fully-autonomous bootstrap
+- **Repository workspace setup** — choose between a fresh local Git repo or an existing external repository (GitHub, GitLab, etc.) via the manual wizard step or inline on the review/summary screen (available in both the manual and AI paths; the external option opens a repo-URL field)
+- **Routine schedules** tightened to run every few hours around the clock (auto-assign every 2 h, stall-detection every 3 h, backlog grooming every 4 h) with `skip_if_active` concurrency policy
+- **"Update templates" button** on the onboarding screen — deletes the cached templates dir and re-downloads from GitHub without restarting the plugin
+
+</details>
+
+---
+
 **Company Wizard** is a [Paperclip](https://github.com/paperclipai/paperclip) plugin that bootstraps an AI agent company for your project — roles, workflows, skills, and tasks — in a few clicks. Open it from the sidebar, answer a few questions (or just describe your project), and it assembles the workspace files and creates the company + CEO in Paperclip. The CEO then hires the team and sets up the backlog on its first heartbeat.
 
 <br>
@@ -59,6 +113,8 @@ Walk through the steps yourself: name your company, set a goal, pick a preset, a
 
 Before provisioning, you can **open any generated file and edit it inline** — tweak a persona, adjust a workflow, or add role-specific context.
 
+On the review step, repository setup is editable inline (fresh local repo vs external Git repo), and changing this now immediately updates preview/provisioning payloads in that step. Legacy source-mode values are normalized on save so mode switches can be applied reliably even when the configuration came from AI with older `workspaceSourceType` fields.
+
 <br>
 
 ## How Roles Work
@@ -424,11 +480,10 @@ Every company starts with just the **CEO** (the only base role). All other roles
 | **UX Researcher** | `researcher` | CEO | Takes over market-analysis and user-testing |
 | **CTO** | `cto` | CEO | Technical leadership, architecture oversight |
 | **CMO** | `cmo` | CEO | Marketing strategy, go-to-market, growth metrics |
-| **CFO** | `cfo` | CEO | Financial planning, budget tracking, cost analysis |
 | **DevOps Engineer** | `devops` | CEO | Takes over ci-cd and monitoring from Engineer |
 | **QA Engineer** | `qa` | CEO | Takes over user-testing, quality gates |
 | **Technical Writer** | `general` | CEO | Takes over documentation, adds doc review pass |
-| **Security Engineer** | `general` | CEO | Takes over security-audit, adds security review pass |
+| **Security Engineer** | `security` | CEO | Takes over security-audit, adds security review pass |
 | **Customer Success** | `general` | CEO | Takes over competitive-intel customer analysis |
 | **Game Designer** | `pm` | CEO | Takes over game-design from Engineer, playtesting focus |
 | **Level Designer** | `pm` | CEO | Takes over level-specific design from Game Designer |
@@ -520,6 +575,7 @@ Configure the plugin via **Settings → Plugins → Company Wizard** in the Pape
 | `paperclipPassword` | No | Board login password. Stored as a secret ref. |
 | `anthropicApiKey` | No | Anthropic API key for AI wizard mode. Stored as a secret ref. Required to use the AI-powered setup path. |
 | `disableBoardApprovalOnNewCompanies` | No | If `true`, the wizard PATCHes new companies to set `requireBoardApprovalForNewAgents=false` during provisioning. Leave `false` to preserve approval-gated hiring. Defaults to `false`. |
+For isolated worktrees: there is no plugin setting. The policy is controlled by Paperclip instance settings under **Settings → Instance → Experimental → enableIsolatedWorkspaces** and is consumed by the plugin during provisioning.
 
 <br>
 
@@ -686,7 +742,7 @@ templates/roles/<name>/
 | `base` | `true` for always-present roles (ceo only) |
 | `division` | Grouping: `leadership`, `engineering`, `design`, `product` |
 | `tagline` | One-liner for wizard UX and AI selection |
-| `paperclipRole` | Paperclip enum: `ceo`, `engineer`, `pm`, `qa`, `designer`, `cto`, `cmo`, `cfo`, `devops`, `researcher`, `general` |
+| `paperclipRole` | Paperclip enum: `ceo`, `engineer`, `pm`, `qa`, `designer`, `cto`, `cmo`, `cfo`, `security`, `devops`, `researcher`, `general` |
 | `adapter` | Passed to `adapterConfig` during provisioning |
 
 </details>

package/dist/manifest.js

@@ -2,7 +2,7 @@
 var manifest = {
   id: "starlein.paperclip-plugin-company-wizard",
   apiVersion: 1,
-  version: "0.2.4",
+  version: "0.3.18",
   displayName: "Company Wizard",
   description: "AI-powered wizard to bootstrap agent companies from composable templates",
   author: "starlein",
@@ -18,6 +18,7 @@ var manifest = {
     "projects.read",
     "plugin.state.read",
     "plugin.state.write",
+    "secrets.read-ref",
     "events.subscribe",
     "ui.page.register",
     "ui.sidebar.register"
@@ -40,8 +41,7 @@ var manifest = {
       },
       anthropicApiKey: {
         type: "string",
-        format: "secret-ref",
-        description: "Anthropic API key for the AI wizard. Required to use the AI-powered company setup path."
+        description: "Anthropic API key for the AI wizard (e.g. sk-ant-...). Required to use the AI-powered company setup path."
       },
       paperclipUrl: {
         type: "string",
@@ -53,8 +53,7 @@ var manifest = {
       },
       paperclipPassword: {
         type: "string",
-        format: "secret-ref",
-        description: "Board login password."
+        description: "Board login password (for authenticated instances)."
       },
       disableBoardApprovalOnNewCompanies: {
         type: "boolean",

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.2.4',\n  displayName: 'Company Wizard',\n  description: 'AI-powered wizard to bootstrap agent companies from composable templates',\n  author: 'starlein',\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    '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        format: 'secret-ref',\n        description:\n          'Anthropic API key for the AI wizard. 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        format: 'secret-ref',\n        description: 'Board login password.',\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    },\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,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,QAAQ;AAAA,QACR,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,QAAQ;AAAA,QACR,aAAa;AAAA,MACf;AAAA,MACA,oCAAoC;AAAA,QAClC,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;",
+  "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.18',\n  displayName: 'Company Wizard',\n  description: 'AI-powered wizard to bootstrap agent companies from composable templates',\n  author: 'starlein',\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    },\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,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": []
 }