diff --git a/doc/plans/ceo-agent-creation-and-hiring.md b/doc/plans/ceo-agent-creation-and-hiring.md new file mode 100644 index 00000000..a2631e4f --- /dev/null +++ b/doc/plans/ceo-agent-creation-and-hiring.md @@ -0,0 +1,389 @@ +# 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.