paperclip-plugin-company-wizard
CLAUDE.md171 starsChanged 8 months agoMITView on GitHub
Company Wizard is a Paperclip plugin for bootstrapping agent company workspaces. It provides an interactive wizard UI (manual and AI-powered paths) that assembles companies from modular templates and optionally provisions them via the Paperclip API. Derived from the standalone @yesterday-ai/paperclip-plugin-company-wizard CLI. After pnpm build, reload the plugin in the Paperclip UI. No reinstall required. Plugin worker (src/worker.ts) — Registers actions via the Paperclip Plugin SDK: - preview-files — Assembles to a temp dir, returns .md file tree as {path, content}[],…
In this repository5 other files it gives its agents.
- AGENTS.mdAGENTS.md
- paperclip-aiSkill
- releaseSkill
- routinesSkill
- setup-routinesSkill
The file
We split this CLAUDE.md into the rules it gives an agent
3 rules. About 0 are common, 0 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 19
After pnpm build, reload the plugin in the Paperclip UI.
- Very specific: line 31
All worker actions return errors as { error } instead of throwing, so the plugin host never swallows messages in generic 502 responses.
- Very specific: line 126
All paths in agent adapterConfig must be absolute (agents may run in different cwd)
≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
What This Is
Company Wizard is a Paperclip plugin for bootstrapping agent company workspaces. It provides an interactive wizard UI (manual and AI-powered paths) that assembles companies from modular templates and optionally provisions them via the Paperclip API. Derived from the standalone @yesterday-ai/paperclip-plugin-company-wizard CLI.
Commands
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 --noEmitAfter pnpm build, reload the plugin in the Paperclip UI. No reinstall required.
Architecture
Plugin worker (src/worker.ts) — Registers actions via the Paperclip Plugin SDK:
preview-files— Assembles to a temp dir, returns.mdfile tree as{path, content}[], cleans up. Used by the ConfigReview step for inline preview+edit before provisioning.start-provision— Assembles to the workspacecompanies/dir, appliesfileOverrides(edits from preview), then provisions via Paperclip API.check-auth— Validates Paperclip API credentials early (used by the summary step).ai-chat— Proxies messages to the Anthropic API using the configured key. Returns{ text, error? }— never throws.check-ai-config— Lightweight check thatanthropicApiKeyis configured. Called by the AI wizard on mount to show a warning banner.refresh-templates— Deletes cached templates dir and re-downloads from GitHub. Triggered by the "Update templates" button on the onboarding screen.
All worker actions return errors as { error } instead of throwing, so the plugin host never swallows messages in generic 502 responses.
Plugin UI (src/ui/) — React state machine (WizardContext + reducer). Manual path: ONBOARDING → NAME → GOAL → PRESET → MODULES → ROLES → SUMMARY → PROVISION → DONE. AI path: ONBOARDING → AI_WIZARD → PROVISION → DONE.
Build — esbuild bundles src/worker.ts, src/manifest.ts, and src/ui/main.tsx into dist/. CSS via PostCSS/Tailwind 4.
Source Layout
src/worker.ts— Worker entry point; registers actions withctx.actions.registersrc/manifest.ts— Plugin manifest:id: "yesterday-ai.paperclip-plugin-company-wizard",displayName: "Company Wizard"src/logic/assemble.js— File assembly: copies templates, resolves capabilities, generates BOOTSTRAP.mdsrc/logic/resolve.js— Capability resolution, role formatting, module dependency expansionsrc/logic/load-templates.js— Loads presets, modules, roles. ExportscollectGoals(),validateGoal()src/api/client.js— Paperclip REST API client (auto-detects auth: no-op for local_trusted, Better Auth sign-in for authenticated). Network errors wrapped with actionable messages. Methods:createCompany,getCompany,updateCompany,deleteCompany,listAgents,getAgent,createAgent(approval-aware: falls back to/agent-hires+ auto-approve when board approval is required),createGoal,createProject,createIssue,createRoutine,createRoutineTrigger,triggerHeartbeatsrc/ui/context/WizardContext.tsx— State machine + reducer. Key state:goals: Goal[],projects: WizardProject[],fileOverrides: Record<string,string>,existingCompanyId: string(when set, provisioning targets this company instead of creating a new one)src/ui/components/ConfigReview.tsx— Review step: callspreview-files, shows collapsibleFileEntrycomponents with inline edit. Overrides dispatched viaSET_FILE_OVERRIDE/DELETE_FILE_OVERRIDEsrc/ui/components/steps/StepProvision.tsx— PassesfileOverridestostart-provision
Template System
templates/
├── roles/ # All roles with role.meta.json (base: true for always-present roles)
├── modules/ # Composable capabilities with module.meta.json
│ └── <module>/
│ ├── module.meta.json # capabilities[], activatesWithRoles[], issues[], routines[]?, permissions[], adapterOverrides?, goal?
│ ├── skills/ # Shared primary skills (any owner can use)
│ │ └── <skill>.md
│ ├── agents/<role>/
│ │ ├── skills/ # Role-specific overrides + fallback variants
│ │ │ ├── <skill>.md # Override (replaces shared for this role)
│ │ │ └── <skill>.fallback.md # Fallback (reduced scope for non-primary)
│ │ └── heartbeat-section.md # Optional: injected into role's HEARTBEAT.md
│ └── docs/ # Shared docs injected into all agents
├── presets/ # Curated module+role combinations with preset.meta.json (may include goals[])
└── ai-wizard/ # Configurable prompts for AI wizard mode
├── config-format.md
├── single-shot-system.md
├── interview-system.md
└── messages.jsonCurrent counts: 15 presets, 26 modules, 17 optional roles (CEO is the only base role).
Skill Resolution
For a capability's primary skill, assembly checks two locations in order:
agents/<role>/skills/<skill>.md— role-specific override (wins if present)skills/<skill>.md— shared skill (default for any primary owner)
Role-specific overrides exist only when a role brings a genuinely different approach. Fallback variants are always role-specific.
Doc References in Skills
Two kinds of docs live in {company}/docs/:
- Templates (
lowercase-kebab.md) — Shipped by modules, copied at assembly time. Safe to reference directly. - Agent output (
UPPERCASE.md) — Created by agents during execution. Always wrap in "if exists" conditionals.
Heartbeat Injection
Convention-based: if a module provides agents/<role>/heartbeat-section.md, assembly injects it into that role's HEARTBEAT.md before the <!-- Module-specific ... --> marker comment. Multiple modules can inject into the same role.
Currently 3 modules have heartbeat sections: stall-detection (CEO), auto-assign (CEO fallback + PO primary), backlog (CEO fallback + PO primary).
Key Concepts
- Goals and projects —
WizardState.goals: Goal[]holds user-specified goals (from manual step or AI wizard).WizardState.projects: WizardProject[]holds user-specified projects. EachGoalhastitle,description, and optionalparentGoalfor sub-goal hierarchy. EachWizardProjecthasname,description, andgoals[](goal titles it's linked to, matching Paperclip APIgoalIds). - Inline goals — Module-level goals (
goal: {}inmodule.meta.json) and preset goals (goals: []inpreset.meta.json). Goals can havesubgoals[](nested goals withid,title,level,description).collectGoals()merges them at runtime asinlineGoals. During assembly, inline goals become sub-goals of the main user goal, and subgoals are expanded into the goal hierarchy. - Module issues and routines — Issues are at module/preset level (
issues[]), not inside goals. Routines (routines[]) define recurring scheduled work withassignTo,schedule(cron), andconcurrencyPolicy. Both are collected from active modules during assembly. assembleCompany()params —userGoals(from wizard),userProjects(from wizard),inlineGoals(fromcollectGoals()). Module inline goals are auto-parented touserGoals[0]. If nouserProjectsspecified, a default project linked to all goals is created.- Paperclip object model — Goals have
level(company|team|agent|task), nested viaparentId. Projects link to goals viagoalIds. Issues link to projects viaprojectId. Routines haveassigneeAgentId,schedule, and cron triggers.instructionsFilePathsets the agent's working directory. assignTo: "user"— Issues assigned to the board user viaassigneeUserId(resolved duringclient.connect()).companyDescription— AI wizard generates a comprehensive description. Stored inWizardContext.companyDescription, rendered in BOOTSTRAP.md, and sent to the Paperclip API as the company'sdescriptionfield.- File overrides —
WizardContext.fileOverrides(Record<string,string>) stores edits made in ConfigReview. Passed tostart-provisionasparams.fileOverrides; written over assembled files before API provisioning. - Gracefully optimistic architecture — Capabilities extend when roles are present, degrade gracefully when absent. A capability's
owners[]chain determines primary/fallback assignment at assembly time. adapterOverridesfield — Module-level adapter config (e.g.,{ "chrome": true }) merged into agentadapterConfigat provisioning. Keeps role templates clean.- toPascalCase — Company and project names become PascalCase directory names. Special characters are stripped.
- BOOTSTRAP.md — Generated guide with: company description, goal hierarchy (with
levelandparentGoalin HTML-comment frontmatter), projects with workspace + goal links, agents with role + instructionsFilePath, issues with assignee + project, routines with schedule + concurrencyPolicy, and provisioning steps in API dependency order. Used as the bootstrap issue description for the CEO.
Paperclip API Flow (start-provision)
Connects to Paperclip API (auto-detects auth mode). Resolves the target company: creates a new one (with companyDescription) or, when existingCompanyId is passed, loads it via getCompany (existing-company runs skip company creation and skip cleanup on error). Resolves the CEO: reuses an active CEO on existing companies, otherwise creates one (with instructionsFilePath, adapter config). If direct agent creation is rejected because board approval is required, createAgent hires via /agent-hires and auto-approves. Finally creates a Bootstrap Issue (assigned to CEO, description = BOOTSTRAP.md content, title uses the resolved company name). The CEO then reads the bootstrap issue and creates goals, projects, agents, and issues as described in BOOTSTRAP.md.
Optional setting disableBoardApprovalOnNewCompanies (default false): when true, new companies are PATCHed to requireBoardApprovalForNewAgents=false right after creation for legacy fully-autonomous bootstrap behavior. Ignored for existing-company runs.
Test Suites
Two separate test runners:
pnpm test— vitest,tests/**/*.spec.ts— TypeScript plugin testspnpm test:logic—node --test,src/logic/*.test.js— Plain-JS logic tests
React Considerations
- All paths in agent
adapterConfigmust be absolute (agents may run in different cwd) - Tailwind 4: use
wrap-break-wordnotbreak-words @ts-ignoresuppresses hints on the three plain-JS imports inworker.ts
Legacy Note
This plugin was derived from @yesterday-ai/paperclip-plugin-company-wizard, the standalone Ink-based CLI. The template system, assembly logic, and API client were carried over intact. The CLI entry points (src/cli.jsx, src/app.jsx, src/headless.js), Ink components, and old build config were removed. See CHANGELOG.md for the full v0.1.0 feature list.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

