Company

Also read the Agent Companies spec:

docs/companies/companies-spec.md

Workflow

Phase 1: Discovery Interview

Use AskUserQuestion. Ask 2-3 focused questions per round:

From scratch:

• Company purpose and domain
• Tech stack preferences (default: React/TS frontend, Python/FastAPI backend, Docker/K8s)
• Required software (Slack, Google Workspace, Stripe?) — if Google Workspace, ask for the company domain used for GWS (e.g. figurio.cellarwood.org)
• Infrastructure (existing or from scratch?)
• Logistics (physical products?)

From repo:

• Whether to reference or vendor discovered skills (default: reference)
• Company name and customization

Do NOT ask about agents or team structure yet — that comes after the work is defined.

Phase 2: Goals

This is mandatory — do not skip or defer goals to later.

Use the work-planning skill, Step 1 (Goal Design). Draft 2-5 company goals following the skill's quality bar and hierarchy rules. Break each goal into subgoals with project linkage (projectSlugs).

Do NOT assign ownerAgentSlug yet — agents don't exist. Focus on what success looks like, not who owns it.

Ask: "Do these goals capture what success looks like for your company?"

Do not proceed to Phase 3 until the user has confirmed or adjusted the goals.

Phase 3: Projects & Tasks

Continue with the work-planning skill, Steps 2-3 (Project Design, Task Design).

Propose:

1. Projects (1-3) — group related work under a clear theme and scope
2. Starter tasks per project (3-8 each) — with 01-, 02- ordering prefixes on directories
3. Company-level strategic tasks — cross-cutting directives at top-level tasks/

Do NOT assign owner or assignee yet — define what work needs to happen, not who does it.

Ask: "Does this project and task plan look right?"

Phase 4: Org Design

Now that the work is defined, design the team to execute it.

Propose an org chart with:

• Agent names, roles, and reporting lines — informed by the goals, projects, and tasks from Phases 2-3
• Monthly budgets per agent
• Plugin assignments per agent (from references/role-plugin-matrix.md)
• Total monthly cost
• Per-agent custom skills (name + description for each)
• Per-agent custom subagents (name + description for each)
• GWS settings for eligible roles (email addresses, domain)

Use references/standard-roles.md as a catalog of available roles.

GWS-eligible roles: CEO, CMO, COO, HeadOfOperations, Content Creator, Marketing Specialist, Product Manager, Customer Support (see role-plugin-matrix.md). Only these roles need email addresses.

Ask: "Based on the work we've planned, does this team look right?"

Phase 5: Assignment

Connect the work to the team:

1. Assign ownerAgentSlug to each goal and subgoal
2. Assign owner to each project
3. Assign assignee to each task

Present the full connected plan (goals → agents, projects → agents, tasks → agents) for user confirmation.

Ask: "Here's the full plan with assignments. Does everything look right? I'll start generating files next."

Phase 6: Pre-Generate Scaffold

Before writing any creative content, run the pre-generation scripts. These handle all deterministic setup.

Company root convention: generate the package in the current working directory unless the user explicitly asks for a different target path.

• Do not create an extra nested folder named after the company slug.
• Example: if the user is in /home/lukas/Projects/Github/cellarwood/figurio, then that directory itself is the company root.
• Write COMPANY.md, agents/, projects/, tasks/, skills/, global/, and the temp files directly into the current directory.

Step 1: Write a ._generation-config.json file in the company root with your org decisions from Phases 1-5:

{
  "companySlug": "my-company",
  "companyName": "My Company",
  "gwsDomain": "company.example.org",
  "gwsCredentialsFile": "/paperclip/.gws/my-company.json",
  "agents": [
    {
      "slug": "ceo",
      "role": "CEO",
      "reportsTo": null,
      "email": "[email protected]",
      "plugins": ["dev-tools", "office"],
      "chromeMcp": false,
      "skills": [
        {
          "name": "strategy-review",
          "description": "Weekly strategic review process — evaluate progress against company goals, identify blockers, reprioritize work across agents"
        },
        {
          "name": "delegation-playbook",
          "description": "Rules for delegating tasks to direct reports — when to delegate vs handle personally, escalation criteria, follow-up cadence"
        }
      ],
      "gwsSkills": ["gws-gmail", "gws-gmail-send", "gws-gmail-read", "gws-gmail-reply", "gws-gmail-triage", "gws-calendar", "gws-calendar-agenda", "gws-calendar-insert", "gws-drive", "gws-docs", "gws-tasks", "gws-meet", "gws-shared", "persona-exec-assistant", "gws-workflow-meeting-prep", "gws-workflow-standup-report", "gws-workflow-weekly-digest"],
      "subagents": [
        {
          "name": "research-assistant",
          "description": "Researches market trends, competitor analysis, and strategic opportunities for the CEO's weekly reviews and board prep"
        },
        {
          "name": "task-planner",
          "description": "Breaks down CEO strategic directives into actionable tasks with priorities, deadlines, and agent assignments"
        },
        {
          "name": "report-generator",
          "description": "Generates weekly company status reports, board updates, and goal progress summaries from agent activity"
        }
      ]
    },
    {
      "slug": "backend-engineer",
      "role": "Backend Engineer",
      "reportsTo": "cto",
      "email": null,
      "plugins": ["dev-tools"],
      "chromeMcp": false,
      "skills": [
        {
          "name": "api-design",
          "description": "REST API conventions for the platform — endpoint naming, pagination, error responses, authentication patterns, and Stripe integration"
        }
      ],
      "gwsSkills": [],
      "subagents": [
        {
          "name": "code-generator",
          "description": "Generates Python/FastAPI code — product catalog CRUD, order pipeline, payment integration endpoints. Follows api-design skill conventions."
        },
        {
          "name": "test-writer",
          "description": "Writes pytest tests — unit tests for business logic, integration tests for Stripe webhooks and database operations"
        }
      ]
    }
  ]
}

Field reference:

• gwsDomain and gwsCredentialsFile: set if company uses Google Workspace, leave empty otherwise
• email: only for GWS-eligible roles
• plugins: use short names from role-plugin-matrix.md (dev-tools, office, infra, media, design, web-design, company). The script expands dependencies automatically.
• chromeMcp: true for Frontend Engineer, QA Engineer, UX Tester
• skills: custom business-specific skills — each with name and description. The description is the design brief for the skill-creator agent.
• gwsSkills: GWS skills for this agent from the "Role -> GWS Skills Mapping" table in role-plugin-matrix.md. Empty array for non-GWS roles.
• subagents: custom subagents — each with name and description. The description is the design brief for the subagent-creator agent.

Step 2: Run the pre-generation script:

bash ../../scripts/pre-generate.sh . ./._generation-config.json

Use the current directory as <company-root>. In practice that means:

bash ../../scripts/pre-generate.sh . ./._generation-config.json

Note: the temp file path should be ./._generation-config.json in the current directory.

This creates:

• Full directory skeleton
• GWS skills in skills/ (imported from googleworkspace/cli repo)
• global/config.toml and global/plugins.json
• Per-agent runtime/config.toml (plugins, env, MCP)
• Per-agent AGENTS.md frontmatter skeleton (with merged custom + GWS skills)
• scripts/setup-secrets.sh

Step 3: Write a ._planning.json file in the company root with the confirmed goals, projects, and tasks from Phases 2-3, now with assignments from Phase 5. Follow the schema defined in the work-planning skill, Step 4.

{
  "goals": [
    {
      "slug": "launch-mvp",
      "title": "Launch MVP web application with user authentication and core workflow",
      "description": "Ship a functional product that users can sign up for and use daily",
      "level": "company",
      "status": "active",
      "ownerAgentSlug": "cto",
      "projectSlugs": ["mvp-backend", "mvp-frontend"],
      "subgoals": [
        {
          "slug": "build-auth-system",
          "title": "Build authentication and user management",
          "description": "Implement email/password and OAuth sign-up, session management, and RBAC",
          "level": "team",
          "ownerAgentSlug": "backend-engineer",
          "projectSlugs": ["mvp-backend"]
        }
      ]
    }
  ],
  "projects": [
    {
      "slug": "mvp-backend",
      "name": "MVP Backend",
      "description": "Backend API with auth, core workflow, and payment integration",
      "owner": "backend-engineer",
      "body": "## Scope\n\nBuild and deploy the backend API.\n\n## Success Criteria\n\n- API deployed to production\n- All endpoints tested"
    }
  ],
  "tasks": {
    "projects": {
      "mvp-backend": [
        {
          "slug": "setup-project",
          "name": "Set up FastAPI project structure",
          "assignee": "backend-engineer",
          "body": "Initialize the FastAPI project with directory structure and Docker setup.",
          "recurring": false
        }
      ]
    },
    "companyLevel": [
      {
        "slug": "strategic-review",
        "name": "Weekly strategic review",
        "assignee": "ceo",
        "body": "Review company progress against goals.",
        "recurring": true
      }
    ]
  }
}

Step 4: Run the plan generation script:

bash ../../scripts/generate-plan.sh . ./._planning.json

This creates all goals/, projects/, and tasks/ directories with proper frontmatter, ordering prefixes, and cross-references.

Phase 7: Generate Creative Content

Do NOT overwrite files created by pre-generate (runtime/config.toml, global/*, scripts/setup-secrets.sh, GWS skills, AGENTS.md frontmatter).

This phase has two waves. Wave 1 generates all agent instruction bundles. Wave 2 generates skills and subagents (which can reference the agent files from Wave 1).

Important: use real Codex subagent delegation for this phase.

• Use spawn_agent for the Paperclip creator workers.
• Use wait_agent before entering the dependent next wave.
• Do not simulate these workers in the parent thread if delegation is available.
• Only fall back to writing a delegated slice yourself if subagent spawning fails or is unavailable. If that happens, say so explicitly in the final summary.

Wave 1: Agent files + package files (parallel)

Spawn one agent-creator per paperclip agent so they run in parallel. Each subagent owns exactly one paperclip agent directory and writes AGENTS.md body (append), SOUL.md, HEARTBEAT.md, TOOLS.md for that agent.

Use this exact orchestration pattern:

1. Call spawn_agent once per paperclip agent with agent_type: "paperclip-plugin:agent-creator".
2. Pass the full company context plus the exact agent slice that worker owns.
3. After launching all Wave 1 subagents, keep working locally only on COMPANY.md and .paperclip.yaml.
4. Before Wave 2, call wait_agent until every Wave 1 subagent has finished.
5. If one worker fails, retry once or complete only that failed slice locally.

For each agent in the roster:

spawn_agent(agent_type="paperclip-plugin:agent-creator", message="
  Company: {name} — {description}
  Tech stack: {stack}
  Goals: {goal list}
  Company root: {path}

  Agent: {slug}
  Role: {role}
  Title: {title}
  Reports to: {reportsTo}
  Plugins: {plugins from runtime/config.toml}
  GWS eligible: {yes/no, email if yes}
  Skills: {list from AGENTS.md frontmatter}
  Responsibilities: {brief description of what this agent does}

  Write: agents/{slug}/AGENTS.md body (append below frontmatter), SOUL.md, HEARTBEAT.md, TOOLS.md
")

While the agent-creators run, write these package files yourself in the parent thread:

• COMPANY.md — with schema: agentcompanies/v1, name, slug, version, goals (2-5)
• .paperclip.yaml — adapter config, budgets, env inputs

Note: projects/, tasks/, and goals/ directories were already created by generate-plan.sh in Phase 6.

Wave 2: Skills + subagents (parallel, after Wave 1 completes)

After all agent-creators finish, spawn skill-creator and subagent-creator subagents in parallel. Do not start this wave until Wave 1 has completed, because these workers may rely on the agent files generated in Wave 1.

Use this orchestration pattern:

1. Build the Wave 2 spawn list only for agents that actually have custom skills or custom subagents.
2. Launch one paperclip-plugin:skill-creator per agent with custom skills.
3. Launch one paperclip-plugin:subagent-creator per agent with custom subagents.
4. Call wait_agent for all Wave 2 workers before post-generate validation.
5. Do not write custom skill files or runtime subagent files in the parent thread unless the delegated worker for that slice failed.

For each agent with custom skills:

spawn_agent(agent_type="paperclip-plugin:skill-creator", message="
  Company: {name} — {description}
  Tech stack: {stack}

  You are writing skills for the {role} agent ({slug}).

  Write these SKILL.md files:
  {for each skill from ._generation-config.json:
    - name: {skill.name}
    - description: {skill.description}
    - path: skills/{skill.name}/SKILL.md}
")

For each agent with subagents:

spawn_agent(agent_type="paperclip-plugin:subagent-creator", message="
  Company: {name} — {description}
  Tech stack: {stack}

  You are creating subagents for the {role} agent ({slug}).
  This agent's responsibilities: {brief role description}

  Create these subagent files from scratch:
  {for each subagent from ._generation-config.json:
    - name: {subagent.name}
    - description: {subagent.description}
    - path: agents/{slug}/runtime/agents/{subagent.name}.md}
")

Quality bar

• COMPANY.md — proper YAML frontmatter with schema: agentcompanies/v1, version, goals (2-5 specific, measurable)
• AGENTS.md — specific to the business, not generic. Mentions actual systems and domains.
• HEARTBEAT.md — follows standard Paperclip heartbeat procedure with role-specific additions
• SOUL.md — two sections: strategic posture + voice and tone. Unique per agent.
• TOOLS.md — pre-filled with plugin capabilities, MCP servers, and role-specific usage guidelines
• PROJECT.md — proper YAML frontmatter with name, description, slug, owner. At least one project per company.
• Tasks under projects — every non-strategic task lives at projects/{slug}/tasks/{slug}/TASK.md with project and assignee frontmatter. See the work-planning skill for detailed guidance.
• .paperclip.yaml — adapter config, budgets, env inputs. Only agents with overrides appear.

Phase 8: Post-Generate Validation

After all files are written (including the agent results), run the validation script:

bash ../../scripts/post-generate.sh .

If the script reports ERRORs: fix each error and re-run the script. Repeat until 0 errors.

After validation passes: delete ._generation-config.json and ._planning.json (cleanup).

Phase 9: README and LICENSE

README.md — company description, org chart, how to import, citations LICENSE — MIT default, or match source repo

Phase 10: Summary

Present:

1. Files created with brief descriptions
2. Step-by-step deployment instructions (see "Importing Into Paperclip" below)

Output Structure

The generated package MUST follow this structure in the current working directory:

.
├── COMPANY.md
├── agents/
│   └── {agent-slug}/
│       ├── AGENTS.md
│       ├── HEARTBEAT.md
│       ├── SOUL.md
│       ├── TOOLS.md
│       └── runtime/
│           ├── config.toml
│           └── agents/              # Subagent definitions
│               └── *.md
├── goals/
│   └── {goal-slug}/
│       ├── GOAL.md
│       └── {subgoal-slug}/GOAL.md
├── projects/
│   └── {project-slug}/
│       ├── PROJECT.md
│       └── tasks/
│           └── {NN-task-slug}/TASK.md
├── tasks/
│   └── {NN-task-slug}/TASK.md
├── skills/
│   └── {skill-slug}/SKILL.md
├── global/
│   ├── config.toml
│   └── plugins.json
├── .paperclip.yaml
├── README.md
└── LICENSE

Importing Into Paperclip

After generation, instruct the user on the two import paths:

1. Via Paperclip UI/API (spec-compliant files):

• Push the package to a GitHub repo
• Import via Paperclip UI (Company Import page) or API: POST /companies/import with source.type: "github"
• The import handles: COMPANY.md, AGENTS.md + instruction bundles, projects, tasks, skills, .paperclip.yaml
• The import also deploys runtime/ files (config.toml and subagents) to agent workspaces

2. Global config (requires manual setup):

• Copy global/config.toml and global/plugins.json into .company/codex/ in the Paperclip repo root
• Rebuild/restart the container

Rules

1. Be thorough — generate ALL files, not stubs. Every AGENTS.md, SOUL.md, HEARTBEAT.md should be complete and specific to the business.
2. Be specific — no generic boilerplate. Every agent's persona, responsibilities, and tech stack should reflect the actual company.
3. Goals are mandatory — every company must have 2-5 specific, measurable goals in COMPANY.md frontmatter. Never generate a company without goals. Present goals to the user and confirm before generating files.
4. Tasks belong to projects — every non-strategic task must live under projects/{slug}/tasks/ with project frontmatter.
5. Ask before generating — confirm org structure, goals, projects, and tasks before writing files.
6. Follow the spec — output must be a valid agentcompanies/v1 package.
7. Working import — the package must be importable via Paperclip's company import system.