Company Wizard

Bootstrap AI agent teams from modular templates.

---

---

Fork: This is a community-maintained fork of yesterday-AI/paperclip-plugin-company-wizard, updated for Paperclip plugin API v1 and the current published SDK with substantial bug fixes. End-to-end company setup is governed through current Paperclip workflows as of v0.5.0.

Version 0.6.4: adds an explicit sync option for a configured empty template directory and fixes generated Company Skills so Codex can load their SKILL.md files. See the changelog and compatibility notes.

Upgrading from 0.6.3: update the installed plugin package and reload it; refreshing templates alone does not update the worker. Newly provisioned or refreshed Company Skills gain Codex-compatible YAML frontmatter. Existing skills are not changed merely by installing the release. If templatesPath is intentionally empty, the wizard can offer an explicit sync from the configured GitHub template URL; clearing the path still selects bundled templates. companiesDir does not need to change.

Requires Node 24.11+, matching the current Paperclip SDK/shared runtime requirement.

Update Company: select an existing company to refresh its agent instructions, documents, skills, routines, and live project execution policies. Preview shows policy changes; existing workspace paths, explicit operator policies, and goal links are preserved. Partial failures never delete an existing company.

What changed vs. upstream

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
• No numeric manifest host floor: current Paperclip source initializes its plugin loader with 0.0.0, unrelated to SDK release versions. Plugin API and declared-capability validation remain active; older hosts are not implied to be supported
• @paperclipai/plugin-sdk and @paperclipai/shared use tested stable 2026.831.1, with peer floor >=2026.831.1; the host provides the externalized SDK at runtime
• security-engineer role now maps to the dedicated Paperclip security enum value (was general)

Bootstrap reliability

• Agents provisioned with complete instructions and Company Skills — every non-CEO agent is created directly with its external AGENTS/HEARTBEAT/SOUL/TOOLS instruction bundle, while resolved module skills are installed in Paperclip's Company Skills Store and assigned through desiredSkills. Previously the CEO created agents during bootstrap with only an instructionsFilePath, leaving each agent with incomplete runtime context.
• 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 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). 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. Base refs are preserved from project/worktree settings and are no longer rewritten to main, master, or origin/*.
• Completed issues preserve reusable execution workspaces — generated roles no longer archive/delete isolated worktrees while marking work done. Paperclip's cleanupEligibleAt / "Cleanup: Not scheduled" field is lifecycle metadata, not an active cleanup scheduler; normal cleanup is left to a separate board/operator action so reviews, follow-ups, and dependent issues can safely reuse the workspace record.
• Stall recovery follows Paperclip's current liveness model — generated roles recognize pending interactions, approvals, user owners, monitors, wakes, and recovery issues as valid action paths even when executionPolicy is null. Stall-detection routines use blocker/wake/subtree diagnostics before reassigning or changing state.
• Role handoffs protect workspace isolation and review ownership — Engineers move unrelated fixes and dependency upgrades to separately isolated top-level issues, Product Owners route implementation and codebase audits to Engineering, and Security Engineers require exact-head green CI evidence before resubmitting a CI-only rejection.
• 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)
• 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

• Choose Anthropic or OpenAI in plugin settings. Anthropic generation uses claude-opus-5 with adaptive thinking, max effort, and a 65,536-token ceiling; OpenAI/Codex generation uses gpt-6-astra with high reasoning effort and the same output ceiling. The AI wizard provider/model is separate from the CEO/team adapter model settings.
• All provider 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
• Governed agent hiring — submits agent creation through /agent-hires, preserves pending approval IDs, and does not auto-approve board-gated hires
• Explicit approval and bootstrap controls — select pending hires from this run, approve them with board authority, then explicitly start bootstrap; the wizard never disables the company's approval policy
• 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 — validates custom GitHub downloads before atomically replacing their source-specific cache; bundled templates stay release-pinned and operator-managed local paths are never overwritten

---

Company Wizard is a 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, creates the company, records Board Operations / Hiring Plan issues, submits governed agent-hire requests, creates routines, and adds the bootstrap task in Paperclip.

Major v0.4.1 workflow update: generated companies now use Paperclip's governed agent-hire flow, decision-log/hiring-plan work products, current heartbeat task-management contract, native executionPolicy review/approval stages, and always-on persona enrichment where templates provide LENSES.md, DONE.md, or skill output bars. Isolated execution workspaces are only applied when Paperclip's experimental instance setting is enabled, and configured project/worktree refs are preserved verbatim.

Why Company Wizard?

• 🗣️ Describe it, don't configure it. AI mode reads a plain-language brief and picks the right preset, modules, and roles for you. Manual mode is there for the steps you want to control yourself.
• 🧩 Composable, not monolithic. 15 curated presets layered from 27 modules and 17 roles. Mix and match freely — modules add skills, tasks, and heartbeat logic to the roles that are present, and degrade gracefully when they're not.
• 🤝 Works from day one with a single CEO. Every capability has an owner chain. Add a specialist and responsibilities shift to them automatically; leave one out and the next-best person — ultimately the CEO — steps in. No setup ever leaves a gap.
• ✏️ Review and edit before anything ships. Preview every generated file, tweak a persona, workflow, or the repository setup inline on the review screen, then provision.
• 🚀 Real end-to-end provisioning. Not just scaffolded files — it creates the company, CEO, goals, projects, and backlog in Paperclip via the API. Target a brand-new or existing company, with a fresh local or existing external Git repo.
• 💸 Token-aware by default. Worker agents are woken on assignment and driven by scheduled routines instead of always-on heartbeats, so the team doesn't burn tokens idling.

npm package installation (Paperclip > Settings > Plugins > Install Plugin):

@starlein/paperclip-plugin-company-wizard

Table of Contents

• Two Ways to Start
• How Roles Work
• Presets
• Modules
• Roles
• Configuration
• Development
• Extending
• How It Works
• Changelog
• Contributing

Two Ways to Start

AI mode

Describe your project in plain language. The wizard analyzes it and picks the right preset, modules, and roles automatically.

"A fintech startup building a payment API, security is critical" → selects secure preset, Security Engineer + Product Owner roles, provisions everything

Great for getting started fast when you're not sure which template fits.

Manual mode

Walk through the steps yourself: name your company, set a goal, pick a preset, add modules, choose roles. Each step shows descriptions and hover-card previews so you know what you're getting.

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.

How Roles Work

Every company starts with just the CEO — and that's already a functional team. Add roles and responsibilities shift automatically:

• Add an Engineer → they take over implementation, git workflow, and technical decisions
• Add a Product Owner → they take over backlog management and auto-assignment from the CEO
• Add a UX Researcher → they become the primary market analyst
• Add DevOps → they own CI/CD and monitoring (instead of Engineer or CEO)

No role is ever truly missing. When a specialist isn't present, the next best available person steps in. The CEO is always the final fallback.

Enriched personas: roles/modules that ship LENSES.md, DONE.md, or <skill>.bar.md are enriched automatically. Domain lenses are appended into SOUL.md, done criteria into HEARTBEAT.md, and output/review bars into the primary skill. Fragment files never ship as standalone files.

Full capability ownership table

Start with just a CEO. Everything works. Add roles and responsibilities shift automatically:

Capability	Primary Owner	Fallback	Module
market-analysis	UX Researcher → CMO → Product Owner	CEO	market-analysis
hiring-review	Product Owner	CEO	hiring-review
backlog-health	Product Owner	CEO	backlog
auto-assign	Product Owner	CEO	auto-assign
user-testing	QA → UX Researcher → Product Owner	CEO	user-testing
brand-identity	UI Designer → CMO	CEO	brand-identity
ci-cd	DevOps	Engineer	ci-cd
monitoring	DevOps	Engineer	monitoring
tech-stack	Engineer	CEO	tech-stack
architecture-plan	Engineer	CEO	architecture-plan
design-system	UI Designer	Engineer	architecture-plan
pr-review	QA (review) / Security Engineer (review, security-relevant) / Product Owner (approval, when present) / Code Reviewer (merge gate, non-author); 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
competitive-tracking	Customer Success → CMO → Product Owner	CEO	competitive-intel
accessibility-audit	QA → UI Designer	Engineer	accessibility
codebase-audit	Engineer	CEO	codebase-onboarding
issue-triage	Product Owner → Engineer	CEO	triage
dependency-audit	DevOps → Security Engineer	Engineer	dependency-management
release-process	DevOps → Engineer	CEO	release-management
game-design	Game Designer → Engineer	CEO	game-design
stall-detection	CEO (always)	—	stall-detection
vision-workshop	CEO (always)	—	vision-workshop

How it works: Primary owners get the full skill. Fallback owners get a safety-net variant that only activates when the primary is absent or stalled.

Example: CEO only? They handle everything — strategy, backlog, auto-assign. Add an Engineer and they take over implementation. Add a Product Owner and they take over backlog management, with the CEO as fallback.

Presets

Presets are curated starting points that bundle a set of modules and optional roles for a specific use case. Pick one in the wizard and you're ready to go — or use it as a base and add modules on top.

Preset	Modules	Best for
fast	github-repo, backlog, auto-assign, stall-detection	Solo engineer, prototypes, MVPs
quality	+ pr-review, + Product Owner, + Code Reviewer	Teams, production systems
rad	+ tech-stack, + hiring-review	Rapid prototyping, formalize later
startup	+ vision, market, hiring, tech, architecture	Strategy-first, grow organically
research	vision, market, tech, hiring (no repo/code)	Planning phase only
full	All modules + Product Owner + Code Reviewer	Full planning + quality engineering
secure	+ security-audit, + Security Engineer + Code Reviewer + PO	Regulated industries, fintech, healthtech
gtm	+ competitive-intel, brand-identity, + CMO + Customer Success + PO	Market-facing products, competitive positioning
content	+ documentation, accessibility, + Technical Writer + PO	Dev tools, documentation-heavy projects
launch-mvp	launch-mvp, github-repo, backlog, auto-assign, stall-detection	Ship a first version end-to-end
build-api	build-api, github-repo, backlog, auto-assign, ci-cd, stall-detection	Build a REST/GraphQL API from scratch
website-relaunch	website-relaunch, github-repo, pr-review, backlog, auto-assign, stall-detection + UI Designer + PO	Relaunch a website with external design assets
repo-maintenance	triage, codebase-onboarding, dependency-management, release-management, github-repo, pr-review, backlog, auto-assign, stall-detection + Code Reviewer + PO	Maintain an existing repository
build-game	game-design, tech-stack, github-repo, backlog, auto-assign, stall-detection + Game Designer + Game Artist + Audio Designer	Build a game from idea to release
launch-pack	vision-workshop, market-analysis, competitive-intel, brand-identity, tech-stack, architecture-plan, launch-mvp, github-repo, backlog, auto-assign, stall-detection + CTO + CMO	Full executive team launch: strategy, tech, and marketing from day one

fast is for a single engineer — multiple engineers without review will cause conflicts.

research has no code workflow. Add github-repo and backlog when ready to build.

Preset details

fast — Solo engineer, direct-to-main, automated backlog. No review, no planning phase.

quality — Full review pipeline. Product Owner manages backlog and product alignment, Code Reviewer gates code quality. Feature branches with PR workflow.

rad — Rapid Application Development. Pick a tech stack, start building, hire when you hit bottlenecks. No upfront market research or architecture formalization — prototype first, learn from what you build, formalize later.

startup — Strategy-first. Starts with vision, market analysis, tech evaluation, and hiring review before any code. Grow the team through board approvals.

research — Planning only. Vision, market research, tech evaluation, and team assessment. No repo, no code workflow. Upgrade to startup or full when ready to build.

full — Everything. Full strategic planning, quality engineering with PR review, team growth via hiring review. Product Owner and Code Reviewer included. Best for serious projects that need both strategy and engineering rigor.

secure — Security-first. Threat modeling, security reviews, and quality gates on top of full planning and PR review. Security Engineer, Code Reviewer, and Product Owner included. Best for regulated industries, fintech, healthtech, or any project where security is a hard requirement.

gtm — Go-to-market focused. Competitive intelligence, market analysis, and brand identity. CMO for marketing strategy, Customer Success for competitive tracking, Product Owner for backlog. Best for products entering or competing in established markets.

content — Content and documentation focused. Technical Writer for developer docs and guides, accessibility for inclusive design, market analysis for positioning. Best for developer tools, documentation-heavy projects, or content-driven products.

website-relaunch — Relaunch an existing website with external design assets. Site audit, design ingestion, implementation, content migration, QA, and go-live. UI Designer for design analysis, Product Owner for backlog management. Includes a user-assigned "Provide design assets" issue as the entry point — upload your agency's designs, the team handles the rest.

repo-maintenance — Custodial maintenance for existing repositories. Agents review and merge open PRs, triage inbound GitHub issues, audit codebase health, manage dependencies, and handle releases. Code Reviewer for PR quality gates, Product Owner for issue triage and backlog. Inline goal bootstraps the team through repo onboarding, process setup, initial sweep, and steady-state maintenance.

build-game — Game development from idea to playable release. Game Designer owns the GDD, mechanics, and balancing. Game Artist generates sprites, textures, and tilesets via AI image generation and code-based approaches. Audio Designer creates sound effects, music, and soundscapes via AI generation and code-based synthesis. Inline goal with 5 milestones: concept (GDD + engine + art style), prototype (core loop + placeholder art + first playtest), vertical slice (one polished level), production (all content), polish & ship (balancing + distribution). Works for any genre.

Modules

Modules are composable capabilities you layer on top of the base team. Each module adds skills, tasks, and optionally heartbeat sections to the relevant roles. Modules are additive — you can combine them freely and they degrade gracefully when a role they extend isn't present.

Strategy & Planning

Module	What it does	Kickoff task
vision-workshop	Define vision, success metrics, strategic milestones	CEO defines vision
market-analysis	Research market, competitors, positioning	Primary owner conducts analysis
hiring-review	Evaluate team gaps, propose hires via board approval	Primary owner reviews team
tech-stack	Evaluate and document technology choices	Primary owner evaluates stack
architecture-plan	Design system architecture + design system	Engineer + Designer (if present)
brand-identity	Brand book, visual identity, design guidelines	Primary owner defines brand
user-testing	Usability evaluations and findings	Primary owner runs evaluations
competitive-intel	Competitive landscape analysis and tracking	Primary owner builds landscape
documentation	Project docs, API refs, onboarding guides	Primary owner creates docs
security-audit	Threat modeling and security code review	Primary owner conducts audit
accessibility	WCAG 2.2 compliance audit and remediation	Primary owner runs audit
website-relaunch	Website relaunch: audit, design ingestion, implementation, migration	Primary owner audits + analyzes designs
launch-mvp	MVP lifecycle: scope, build core feature, deploy, iterate from feedback	CEO scopes, primary owner builds
game-design	Game Design Document, core mechanics, progression, balancing	Primary owner creates GDD

Maintenance & Operations

Module	What it does	Kickoff task
codebase-onboarding	Audit existing codebase, map architecture, track tech debt, ongoing cleanup	Primary owner audits codebase
triage	Classify, prioritize, and respond to inbound GitHub issues	Primary owner triages open issues
dependency-management	Dependency audits, CVE scanning, safe patching, upgrade planning	Primary owner audits dependencies
release-management	Semver, changelogs, git tagging, GitHub Releases, rollback procedures	Primary owner documents release process

Engineering Workflow

Module	What it does	Kickoff task
github-repo	Git workflow and commit conventions	Engineer initializes repo
pr-review	PR-based review workflow	Engineer configures PR workflow and branch protection (requires PRs, no approval gate)
lean-delivery	Optional single merge gate, risk-triggered evidence, and bounded WIP (requires pr-review)	—
backlog	Auto-generate issues from goals when backlog runs low	Primary owner creates initial backlog
auto-assign	Assign unassigned issues to idle agents	—
stall-detection	Detect stuck handovers, nudge or escalate	—
build-api	REST API: schema design, endpoints, auth, documentation	Engineer designs and implements
ci-cd	Continuous integration and deployment pipeline	Primary owner sets up CI/CD
monitoring	Observability, alerting, health checks	Primary owner sets up monitoring

Module details

vision-workshop

Defines the strategic foundation. The CEO runs a vision workshop to refine the company goal into a vision statement, success metrics, and milestones.

• Capability: none (CEO-only strategic task)
• Doc: docs/vision-template.md
• With UX Researcher: contributes user-centered metrics and journey mapping

market-analysis

Researches the target market, competitors, and positioning.

• Capability: market-analysis — owners: ux-researcher → cmo → product-owner → ceo
• Fallback: CMO focuses on positioning and competitive landscape; CEO creates a brief overview only
• Doc: docs/market-analysis-template.md

hiring-review

Evaluates team composition against the goal and proposes hires through board approval.

• Capability: hiring-review — owners: product-owner → ceo
• Fallback: CEO proposes one urgent hire only

tech-stack

Evaluates technology options and documents decisions with rationale and trade-offs.

• Capability: tech-stack — owners: engineer → ceo
• Fallback: CEO makes pragmatic defaults, marks them provisional
• Doc: docs/tech-stack-template.md

architecture-plan

Designs the system architecture. Requires tech-stack. Includes a design-system capability for UI Designers.

• Capability: architecture-plan — owners: engineer → ceo
• Capability: design-system — owners: ui-designer → engineer
• Docs: docs/architecture-template.md, docs/design-system-template.md

github-repo

Git workflow and commit conventions.

• Task: Engineer initializes repo
• Doc: docs/git-workflow.md

pr-review

PR-based review workflow. Requires github-repo. Activates with code-reviewer, product-owner, ui-designer, ux-researcher, qa, or devops.

Standard review uses the issue's native executionPolicy: QA review when present, Security review only for security-relevant changes, Product Owner approval when present, then a non-author Code Reviewer merge gate. The merge owner verifies the exact reviewed head, merges the PR, and only then records approval to close the issue. Omit absent roles and the executor from every stage — Paperclip excludes the author and an author-only stage stalls. Without an eligible non-author Code Reviewer, set no stages and use gh pr merge <N> --merge (PR Self-Merge Flow).

• Task: Engineer configures PR workflow and branch protection (requires PRs, no approval gate)
• Doc: docs/pr-conventions.md

lean-delivery (optional)

Select lean-delivery in the setup wizard's Modules step; pr-review and github-repo are automatically included as dependencies. It is not selected by any built-in preset. Deselect it to keep standard review. In AI setup, explicitly request lean delivery.

With this module, the policy has exactly one default stage: the non-author Code Reviewer merge gate. Product acceptance is finalized before implementation; QA, Security, Product, UI/UX, and DevOps provide risk-triggered same-issue evidence instead of serial executionPolicy stages. The docs/lean-delivery.md contract uses advisory queue signals, not a fixed PR-count gate. In both modes, real dependencies, workspace safety, required CI, and explicit company capacity policies remain binding. Selecting this module never disables repository protections.

backlog

Owns the product backlog lifecycle — from goal decomposition to a steady pipeline of actionable issues.

• Capability: backlog-health — owners: product-owner → ceo
• Fallback: CEO creates 1-2 issues only when backlog is critically empty
• Doc: docs/backlog-process.md

auto-assign

Assigns unassigned issues to idle agents.

• Capability: auto-assign — owners: product-owner → ceo
• Fallback: CEO assigns only when agents are critically idle

brand-identity

Creates brand guidelines: logo usage, color palette, typography, iconography, and tone of voice.

• Capability: brand-identity — owners: ui-designer → cmo → ceo
• Fallback: CMO focuses on brand strategy and messaging; CEO creates minimal provisional placeholder
• Doc: docs/brand-identity-template.md

user-testing

Designs and executes usability evaluations, documents findings with severity ratings.

• Capability: user-testing — owners: qa → ux-researcher → product-owner → ceo
• Fallback: QA adds test automation and edge case coverage; CEO creates a basic heuristic checklist
• Doc: docs/user-testing-template.md

ci-cd

Continuous integration and deployment pipeline. Requires github-repo.

• Capability: ci-cd — owners: devops → engineer
• Fallback: Engineer sets up basic CI (lint, test, build); DevOps owns full pipeline lifecycle including CD
• Doc: docs/ci-cd-template.md

monitoring

Observability, error tracking, logging, alerting, and health checks. Requires github-repo.

• Capability: monitoring — owners: devops → engineer
• Fallback: Engineer sets up basic health checks and structured logging; DevOps owns full observability stack
• Doc: docs/monitoring-template.md

security-audit

Threat modeling and security code review. Identifies attack surfaces, OWASP Top 10 vulnerabilities, and dependency CVEs.

• Capability: threat-model — owners: security-engineer → devops → engineer
• Capability: security-review — owners: security-engineer → devops → engineer
• Fallback: DevOps focuses on infrastructure security; Engineer runs basic checks only

documentation

Project documentation: READMEs, API references, architecture overviews, onboarding guides.

• Capability: project-docs — owners: technical-writer → engineer → ceo
• Fallback: Engineer writes minimal README; CEO creates bare-bones project overview

competitive-intel

Living competitive landscape — competitor profiles that evolve over time with positioning, strengths, and differentiation insights.

• Capability: competitive-tracking — owners: customer-success → cmo → product-owner → ceo
• Fallback: CMO focuses on positioning angles; CEO creates brief overview only

accessibility

WCAG 2.2 compliance auditing: semantic HTML, keyboard navigation, color contrast, ARIA, screen reader compatibility.

• Capability: accessibility-audit — owners: qa → ui-designer → engineer
• Fallback: UI Designer focuses on visual accessibility; Engineer runs automated checks

website-relaunch

Full website relaunch lifecycle: audit the current site, ingest design assets from an external agency, implement the new design, migrate content, and go live. Includes an inline goal with 5 milestones and 10 issues.

• Capability: design-ingestion — owners: ui-designer → engineer → ceo
• Capability: site-audit — owners: ui-designer → engineer → ceo
• Goal: Website Relaunch (with dedicated project, 5 milestones, 10 issues)

build-api

REST API development from schema to documentation. Inline goal with 4 milestones and 8 issues.

• Capability: api-design — owners: engineer → ceo
• Requires: github-repo
• Goal: Build a REST API (with dedicated project, 4 milestones, 8 issues)

launch-mvp

MVP project lifecycle: define scope tightly, build the core feature, deploy, and iterate from user feedback. No capabilities or skills — structured goal with milestones and issues.

• Goal: Launch MVP (with dedicated project, 4 milestones, 8 issues)

codebase-onboarding

Audit an existing codebase and maintain its health over time. Requires github-repo.

• Capability: codebase-audit — owners: engineer → ceo
• Output: docs/CODEBASE-AUDIT.md

triage

Processes inbound GitHub issues: classify by type and priority, respond to reporters, close duplicates, convert actionable items into Paperclip tasks. Requires github-repo.

• Capability: issue-triage — owners: product-owner → engineer → ceo

dependency-management

Dependency lifecycle: vulnerability scanning, outdated package detection, safe patch-level updates, and major version migration planning. Requires github-repo.

• Capability: dependency-audit — owners: devops → security-engineer → engineer
• Output: docs/DEPENDENCY-AUDIT.md

release-management

Release lifecycle: semantic versioning, changelog generation, git tagging, GitHub Releases, and rollback documentation. Requires github-repo.

• Capability: release-process — owners: devops → engineer → ceo
• Output: docs/RELEASE-PROCESS.md

game-design

Game Design Document creation and ongoing mechanic design, progression, and balancing. Ships a GDD template and engine reference docs (Phaser, PixiJS, Three.js).

• Capability: game-design — owners: game-designer → engineer → ceo
• Docs: docs/gdd-template.md, docs/engine-phaser.md, docs/engine-pixijs.md, docs/engine-threejs.md

stall-detection

Detects issues stuck in in_progress or in_review with no recent activity. Nudges the assigned agent, escalates to the board if nudging doesn't help.

• Capability: CEO-only

Roles

Every company starts with just the CEO (the only base role). All other roles are optional:

Role	Paperclip role	Reports to	Enhances
Software Engineer	engineer	CEO	Takes over implementation, git workflow, and technical decisions from CEO
Product Owner	pm	CEO	Takes over roadmap, auto-assign, hiring-review from CEO
Code Reviewer	general	CEO	Enables pr-review activation
UI & Brand Designer	designer	CEO	Takes over design-system and brand-identity
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
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	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
Game Artist	designer	CEO	Takes over art asset creation from Engineer
Audio Designer	designer	CEO	Takes over audio asset creation from Engineer

Role details

Software Engineer

Builds the product: implements features, fixes bugs, writes tests, and manages the git workflow. The default owner of technical execution — without an Engineer present, the CEO carries implementation.

Product Owner

The voice of the user. Owns the backlog pipeline, validates engineering output against goals, manages scope discipline. Adds product-alignment review pass with pr-review module.

Code Reviewer

Owns code quality. Reviews PRs for correctness, style, security, and test coverage. Never writes code — only reviews it.

UI & Brand Designer

Owns visual identity, design systems, and brand consistency. Creates design specs that engineers implement. Outputs are design documents, not code. Adds design review pass with pr-review module.

UX Researcher

Owns user experience research, usability analysis, and journey mapping. Grounds design and product decisions in evidence-based user insights. Adds UX review pass with pr-review module.

CTO

Technical leadership and architecture oversight. Guides technology decisions, reviews system design, and ensures engineering quality at scale.

CMO

Owns marketing strategy, brand positioning, go-to-market planning, and growth metrics. Data-driven, measures everything.

DevOps Engineer

Owns infrastructure, CI/CD pipelines, deployment, monitoring, and platform reliability. Automation over manual work, infrastructure as code.

QA Engineer

Owns test strategy, test automation, quality gates, and regression prevention. Prevention over detection.

Technical Writer

Owns developer documentation, API references, READMEs, and onboarding guides. Keeps docs accurate as the codebase evolves.

Security Engineer

Owns threat modeling, security code reviews, OWASP compliance, and secure coding standards. Security issues are always blocking.

Customer Success Manager

Owns customer health monitoring, feedback synthesis, churn prevention, and competitive intelligence from the customer perspective.

Game Designer

Owns the Game Design Document, core mechanics, game loop, progression systems, difficulty curves, and balancing. Runs design experiments and iterates based on playtest data.

Level Designer

Owns level layout, pacing, difficulty curves, environmental storytelling, and spatial progression.

Game Artist

Owns visual art production: sprites, textures, tilesets, UI elements, and visual effects. Creates assets using AI image generation tools, code-based approaches, and asset pipeline tools.

Audio Designer

Owns audio production: sound effects, music, ambient soundscapes, and audio systems design. Creates audio using AI generation tools, code-based synthesis, and audio processing pipelines.

Configuration

Configure the plugin via Settings → Plugins → Company Wizard in the Paperclip UI.

Field	Required	Description
companiesDir	No	Where assembled company workspaces are written. Defaults to ~/.paperclip/instances/default/companies. Override for Docker setups.
templatesPath	No	Existing operator-managed template root, not a download destination. Overrides templatesRepoUrl; never populated or overwritten by refresh. Leave empty to use bundled templates or a custom GitHub source.
templatesRepoUrl	No	Custom GitHub tree URL opts into a source-specific remote cache. The official default uses bundled templates. Refresh explicitly before preview to update a custom source.
paperclipUrl	No	Paperclip instance URL. Defaults to http://localhost:3100 or PAPERCLIP_PUBLIC_URL env var.
paperclipEmail	No	Board login email. Required for authenticated (non-local_trusted) instances.
paperclipPassword	No	Board login password. Stored as a secret ref.
aiProvider	No	AI wizard provider: anthropic (default) or openai.
anthropicApiKey	No	Anthropic API key for AI wizard mode. Stored as a governed secret ref. Required when aiProvider is anthropic.
openaiApiKey	No	OpenAI API key for GPT/Codex AI wizard mode. Stored as a governed secret ref. Required when aiProvider is openai.
If the wizard only shows Custom and /templates contains empty arrays, check templatesPath first. It must point directly to the template root (normally containing roles/, modules/, and presets/), not an empty directory or the repository root above templates/. Clear the field to use the installed release templates; the official GitHub URL does not override an explicit local path. Save and reload the wizard. Test Configuration now validates template availability and metadata before checking Paperclip connectivity; it does not make a paid AI generation request or verify model entitlement. A custom CEO-only library is supported, but roles/ceo/role.meta.json must declare name: "ceo" and base: true.

For enriched personas: there is no plugin setting. Template fragments are applied automatically when present.

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. External repository base refs are taken from project/worktree settings; leaving the ref blank lets Paperclip resolve its default instead of the wizard inventing main, master, or origin/*.

Shared workspace guard: new policies default to sharedWorkspaceConcurrency: "serialize". Current Paperclip enforces this only for project-bound shared runs when enableIsolatedWorkspaces and the project policy are enabled. Explicit auto/allow and per-issue settings can override it; the wizard preserves these choices and does not turn on instance settings. A stored policy alone is not proof that a run is serialized.

Development

pnpm install
pnpm build          # esbuild: worker + manifest + UI → dist/
pnpm dev            # watch mode
pnpm test           # vitest: tests/**/*.spec.ts
pnpm test:logic     # node --test: src/logic/*.test.js
pnpm typecheck      # tsc --noEmit

After pnpm build, reload the plugin in the Paperclip UI — no reinstall required.

Extending

Add a module

templates/modules/<name>/
├── module.meta.json             # Name, capabilities, tasks, dependencies, permissions
├── skills/                      # Shared skills (used by any primary owner)
│   └── <skill>.md
├── agents/<role>/
│   ├── skills/                  # Role-specific overrides and fallbacks
│   │   ├── <skill>.md           # Override (replaces shared for this role)
│   │   └── <skill>.fallback.md  # Fallback (safety-net for non-primary)
│   └── heartbeat-section.md     # Optional: injected into role's HEARTBEAT.md
└── docs/                        # Shared docs (→ docs/)

module.meta.json schema

{
  "name": "my-module",
  "requires": ["other-module"],
  "activatesWithRoles": ["my-role"],
  "permissions": ["tasks:assign"],
  "adapterOverrides": { "chrome": true },
  "capabilities": [
    {
      "skill": "my-skill",
      "owners": ["my-role", "ceo"],
      "fallbackSkill": "my-skill.fallback"
    }
  ],
  "tasks": [
    {
      "title": "Initial task",
      "assignTo": "capability:my-skill",
      "description": "Task description"
    }
  ],
  "goal": {
    "title": "My Goal",
    "description": "What this goal achieves",
    "project": true,
    "milestones": [
      { "id": "phase-1", "title": "Phase 1", "project": false }
    ],
    "issues": [
      { "title": "First task", "milestone": "phase-1", "assignTo": "engineer", "priority": "high" }
    ]
  }
}

Field	Description
requires	Other modules that must be selected
activatesWithRoles	Module only applies if one of these roles is present
capabilities[].owners	Priority order — first present role gets the primary skill
capabilities[].fallbackSkill	Filename (without .md) of the fallback variant
tasks[].assignTo	A role name or "capability:<skill>" to auto-resolve
adapterOverrides	Adapter config keys merged into all capability owner agents during provisioning
goal	Optional inline goal. When active, tasks are skipped.
goal.project	If true (default), creates a dedicated Paperclip project for this goal
goal.issues[].assignTo	Role name, "capability:<skill>", or "user" (human pickup)

Skill resolution

When assembling a capability's primary skill, the system checks in order:

1. Role-specific override: agents/<role>/skills/<skill>.md
2. Shared skill: skills/<skill>.md

First match wins. Most capabilities only need a shared skill. Role-specific overrides exist only when a role brings a genuinely different approach.

Example: market-analysis module
├── skills/
│   └── market-analysis.md                    # Shared: any primary owner
├── agents/
│   ├── ux-researcher/skills/
│   │   └── market-analysis.md                # Override: user-focused
│   └── ceo/skills/
│       └── market-analysis.fallback.md       # Fallback: brief overview

• UX Researcher present → gets role-specific override (user-focused)
• Product Owner primary → gets shared skill
• CEO as fallback → gets fallback variant

Doc references in skills

Two kinds of docs end up in {company}/docs/:

• Templates (lowercase-kebab.md) — Shipped by modules, copied at assembly time. Guaranteed to exist if the module is active.
• Agent output (UPPERCASE.md) — Created by agents during execution. May or may not exist yet.

Reference	Rule	Example
Define own output	Name the path directly	"Document in docs/TECH-STACK.md"
Read own template	Reference directly	"Follow conventions in docs/pr-conventions.md"
Read cross-module output	Always conditional	"If docs/TECH-STACK.md exists, review it. Otherwise, proceed based on project context."

Add a role

templates/roles/<name>/
├── role.meta.json   # Name, title, base, paperclipRole, reportsTo, adapter
├── AGENTS.md
├── SOUL.md
├── HEARTBEAT.md
└── TOOLS.md

role.meta.json schema

{
  "name": "my-role",
  "title": "My Role",
  "base": false,
  "division": "engineering",
  "tagline": "One-liner for wizard display and AI selection",
  "paperclipRole": "general",
  "description": "What this role does",
  "reportsTo": "ceo",
  "enhances": ["Takes over X from CEO"],
  "adapter": {
    "model": "claude-sonnet-4-6"
  }
}

Field	Description
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, security, devops, researcher, general
adapter	Passed to adapterConfig during provisioning

Add a preset

Create templates/presets/<name>/preset.meta.json:

{
  "name": "my-preset",
  "description": "What this preset is for",
  "constraints": [],
  "roles": ["product-owner"],
  "modules": ["github-repo", "backlog"]
}

How It Works

┌─────────────┐     ┌──────────────┐     ┌──────────────────┐
│   Wizard    │────▶│   Assembly   │────▶│   Provisioning   │
│   (UI)      │     │  (files)     │     │   (Paperclip API)│
└─────────────┘     └──────────────┘     └──────────────────┘

Assembly (always runs):

1. Copies base role files (CEO — the only base role) into agents/
2. Copies selected extra roles into agents/
3. For each module: resolves capability ownership, collects deduplicated Company Skills, copies docs
4. Injects module heartbeat sections into each role's HEARTBEAT.md
5. Generates BOOTSTRAP.md with goal, project, agent paths, Company Skill slugs, and initial tasks

Provisioning (Review → Provision step):

1. Connects to Paperclip API (auto-detects local_trusted vs authenticated)
2. Creates a new company in Paperclip — or targets an existing one if existingCompanyId is set in the review step
3. Creates Board Operations and Hiring Plan issues with decision-log and hiring-plan documents
4. Upserts assembled Company Skills in the Skills Store and resolves their stable keys
5. Submits the CEO and team agents through /agent-hires with external instruction bundles, desiredSkills, and sourceIssueId provenance; pending approvals are logged for board action instead of auto-approved
6. Creates scheduled routines with board authority and links them to the pre-created main project when needed
7. Creates a Bootstrap task assigned to the CEO

On the final step, review and approve selected pending hires, then click Start bootstrap. The CEO creates remaining goals/backlog work and links newly created projects where needed; existing project goal links remain untouched. Starting is separate from approval, and normal scheduled/assignment wakes remain governed by Paperclip. If provisioning fails after a new company is created, the partial company is automatically deleted — existing target companies are never deleted on error.

Changelog

See CHANGELOG.md for version history.

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT