paperclip/doc/plans/ceo-agent-creation-and-hiring.md

# CEO Agent Creation and Hiring Governance Plan (V1.1)

Status: Proposed  
Date: 2026-02-19  
Owner: Product + Server + UI + Skills

## 1. Goal

Enable a CEO agent to create new agents directly, with lightweight but explicit governance:

- Company-level toggle: new hires require board approval (default ON).
- Agent-level permission: `can_create_agents` (default ON for CEO, OFF for everyone else).
- Clear hire workflow with draft/limbo state until approval.
- Config reflection so hiring agents can inspect available adapter configuration and compare existing agent configs (including self).
- Approval collaboration flow with comments, revision requests, and audit trail.

## 2. Current State (Repo Reality)

- Agent creation is board-only at `POST /api/companies/:companyId/agents` (`server/src/routes/agents.ts`).
- Approvals support `pending/approved/rejected/cancelled` and `hire_agent` + `approve_ceo_strategy` (`packages/shared/src/constants.ts`, `server/src/services/approvals.ts`).
- `hire_agent` approval currently creates the agent only on approval; there is no pre-created limbo agent.
- There is no agent permissions system today.
- There is no company setting for "new hires require board approval".
- Approvals have no comment thread or revision-request state.
- Inbox and Approvals UIs support approve/reject only; no approval detail route exists in app routes.
- Agent adapter configuration is free-form JSON; no runtime reflection endpoint exists for machine-readable or text discovery.

## 3. Product Decisions

## 3.1 Company setting

Add company setting:

- `requireBoardApprovalForNewAgents: boolean`
- Default: `true`
- Editable only in company advanced settings (not onboarding/company creation flow UI)

## 3.2 Agent permissions

Introduce lightweight permission model with one explicit permission now:

- `can_create_agents: boolean`

Defaults:

- CEO: `true`
- Everyone else: `false`

Authority:

- Board can edit permissions for any agent.
- CEO can edit permissions for agents in same company.

No broader RBAC system in this phase.

## 3.3 Limbo state for hires

Introduce dedicated non-operational status:

- `pending_approval`

Meaning:

- Agent record exists in org tree and can be reviewed.
- Agent cannot run, receive assignments, create keys, or be resumed to active states until approved.

## 4. Data Model Changes

## 4.1 `companies`

Add column:

- `require_board_approval_for_new_agents` boolean not null default `true`

Sync required:

- `packages/db/src/schema/companies.ts`
- `packages/shared/src/types/company.ts`
- `packages/shared/src/validators/company.ts`
- UI company API type usage and company advanced settings form

## 4.2 `agents`

Add columns:

- `permissions` jsonb not null default `{}`
- status value expansion to include `pending_approval`

Sync required:

- `packages/db/src/schema/agents.ts`
- `packages/shared/src/constants.ts` (`AGENT_STATUSES`)
- `packages/shared/src/types/agent.ts`
- `packages/shared/src/validators/agent.ts`
- status badges, filters, and lifecycle controls in UI

## 4.3 `approvals`

Keep approval as central governance record; extend workflow support:

- add status `revision_requested`
- ensure payload for hire approvals contains:
  - `agentId`
  - `requestedByAgentId`
  - `requestedConfigurationSnapshot`

## 4.4 New `approval_comments` table

Add discussion thread for approvals:

- `id`, `company_id`, `approval_id`, `author_agent_id`, `author_user_id`, `body`, timestamps

Purpose:

- review comments
- revision requests
- rationale for approve/reject
- permanent audit trail

## 5. API and AuthZ Plan

## 5.1 Permission helpers

Add server-side authz helpers:

- `assertCanCreateAgents(req, companyId)`
- `assertCanManageAgentPermissions(req, companyId)`

Rules:

- Board always passes.
- Agent passes `can_create_agents` check if self permission true and same company.
- Permission management by CEO or board.

## 5.2 Hire creation flow

Add route:

- `POST /api/companies/:companyId/agent-hires`

Behavior:

- Requires `can_create_agents` (or board).
- Creates agent row first.
- If company setting requires approval:
  - create agent with `status=pending_approval`
  - create `approvals(type=hire_agent,status=pending,payload.agentId=...)`
  - return both agent + approval
- If setting disabled:
  - create agent as `idle`
  - no approval record required

Board may continue using direct create route, but this route becomes canonical for CEO/agent-led hiring.

## 5.3 Approval workflow endpoints

Add/extend:

- `GET /api/approvals/:id`
- `POST /api/approvals/:id/request-revision`
- `POST /api/approvals/:id/resubmit`
- `GET /api/approvals/:id/comments`
- `POST /api/approvals/:id/comments`

Update existing approve/reject semantics:

- approve of hire transitions linked agent `pending_approval -> idle`
- reject keeps linked agent in non-active state (`pending_approval` or `terminated`/purged later)

## 5.4 Agent permission management endpoints

Add:

- `PATCH /api/agents/:id/permissions`

Supports initial key only:

- `{ "canCreateAgents": boolean }`

## 5.5 Read config endpoints (protected)

Add permission-gated config-read endpoints:

- `GET /api/companies/:companyId/agent-configurations`
- `GET /api/agents/:id/configuration`

Access:

- board
- CEO
- any agent with `can_create_agents`

Security:

- redact obvious secret values from adapter config (`env`, API keys, tokens, JWT-looking values)
- include redaction marker in response

## 5.6 Reflection endpoints for adapter configuration

Add plain-text reflection routes:

- `GET /llms/agent-configuration.txt`
- `GET /llms/agent-configuration/:adapterType.txt`

Index file includes:

- installed adapter list for this Paperclip instance
- per-adapter doc URLs
- brief "how to hire" API sequence links

Per-adapter file includes:

- required/optional config keys
- defaults
- field descriptions
- safety notes
- example payloads

Auth:

- same gate as config-read endpoints (board/CEO/`can_create_agents`).

## 6. Adapter Protocol Extension

Extend `ServerAdapterModule` contract to expose config docs:

- `agentConfigurationDoc` (string) or `getAgentConfigurationDoc()`

Implement in:

- `packages/adapters/claude-local`
- `packages/adapters/codex-local`
- `server/src/adapters/registry.ts`

This is required so reflection is generated from installed adapters, not hardcoded.

## 7. UI Plan

## 7.1 Company advanced settings

In Companies UI, add advanced settings panel/modal with:

- toggle: "Require board approval for new agent hires" (default on)

Not shown in onboarding flow.

## 7.2 Agent permissions UI

In Agent Detail (board/CEO context):

- permissions section
- toggle for "Can create new agents"

## 7.3 Hire UX

Add "Hire Agent" flow (for CEO/authorized agents):

- choose role/name/title/reportsTo
- compose initial prompt/capabilities
- inspect adapter reflection docs
- inspect existing related agent configurations
- submit hire

State messaging:

- if approval required: show "Pending board approval"
- if not required: show active-ready state

## 7.4 Approvals UX

Add approval detail page and expand inbox integration:

- `/approvals/:approvalId`
- threaded comments
- revision request action
- approve/reject with decision note
- activity timeline (created, revisions, decisions)

## 7.5 Disapproved agent cleanup

Provide board-only destructive action in approval detail:

- "Delete disapproved agent"
- explicit confirmation dialog
- preserves approval + comment history (audit)

## 8. New Skill: `paperclip-create-agent`

Create new skill directory:

- `skills/paperclip-create-agent/SKILL.md`
- `skills/paperclip-create-agent/references/api-reference.md`

Skill responsibilities:

- Discover available adapter configuration via `/llms/agent-configuration*.txt`
- Read existing agent configurations (including self and related roles)
- Propose best-fit config for current environment
- Draft high-quality initial prompt for new agent
- Set manager/reporting line
- Execute hire API flow
- Handle revision loop with board comments

Also update `skills/paperclip/SKILL.md` to reference this skill for hiring workflows.

## 9. Enforcement and Invariants

New/updated invariants:

- `pending_approval` agents cannot:
  - be invoked/woken
  - be assigned issues
  - create or use API keys
  - transition to active lifecycle states except through hire approval
- approval transitions:
  - `pending -> revision_requested | approved | rejected | cancelled`
  - `revision_requested -> pending | rejected | cancelled`
- every mutation writes `activity_log` records.

## 10. Implementation Phases

## Phase 1: Contracts and migration

- DB schema updates (`companies`, `agents`, approvals status expansion, `approval_comments`)
- shared constants/types/validators updates
- migration generation and typecheck

## Phase 2: Server authz + hire flow

- permission resolver and authz guards
- `agent-hires` route
- limbo status enforcement in heartbeat/issue/key flows
- approval revision/comment endpoints

## Phase 3: Reflection and config-read APIs

- adapter protocol docs support
- `/llms/agent-configuration*.txt` routes
- protected config-read endpoints with redaction

## Phase 4: UI and skilling

- company advanced setting UI
- permission controls
- approval detail + comments/revision flow in inbox/approvals
- disapproved agent delete flow
- `paperclip-create-agent` skill + docs updates

## 11. Test Plan

Server tests:

- permission gate tests for hire/config-read/permission-update endpoints
- hire creation behavior with company setting on/off
- approval transitions including revision cycle
- pending_approval enforcement across wakeup/invoke/assignment/keys
- config redaction tests

UI tests:

- advanced setting toggle persistence
- approval detail comment/revision interactions
- hire flow states (pending vs immediate)

Repo verification before merge:

- `pnpm -r typecheck`
- `pnpm test:run`
- `pnpm build`

## 12. Risks and Mitigations

- Risk: leaking secrets through agent config reads.
  - Mitigation: strict redaction pass + allowlist/denylist tests.
- Risk: status explosion complexity.
  - Mitigation: single added status (`pending_approval`) with explicit transition guards.
- Risk: approval flow regressions.
  - Mitigation: centralize transition logic in approval service and back it with tests.

## 13. Open Decisions (Default Recommendation)

1. Should board direct-create bypass approval setting?
Recommendation: yes, board is explicit governance override.

2. Should non-authorized agents still see basic agent metadata?
Recommendation: yes (name/role/status), but configuration fields stay restricted.

3. On rejection, should limbo agent remain `pending_approval` or move to `terminated`?
Recommendation: move to `terminated` on final reject; keep optional hard delete action for cleanup.