Files

T

Dotta d9f540c331 [codex] Refresh docs and agent skills (#4693 )

## Thinking Path

> - Paperclip orchestrates AI agents through a company-scoped control
plane
> - Contributors and agents need docs and skills that match the current
V1 behavior
> - The source branch included documentation updates alongside
implementation work
> - Keeping docs and skill guidance separate makes the implementation PR
easier to review
> - This pull request refreshes the V1 docs and agent-operating guidance
without changing runtime behavior
> - The benefit is current contributor guidance that can merge
independently from code changes

## What Changed

- Refreshed V1 product, goal, implementation, database, and development
documentation.
- Updated the Paperclip heartbeat skill guidance and create-agent skill
references.
- Added the Paperclip plan-to-task conversion skill.
- Updated release changelog skill guidance.

## Verification

- `git diff --check public-gh/master..HEAD` passed in the PR worktree
after the Greptile fix.
- Greptile Review passed on head `673317ed` with zero unresolved review
threads.
- GitHub PR checks passed on head `673317ed`: `policy`, `verify`, `e2e`,
and `security/snyk (cryppadotta)`.

## Risks

- Low runtime risk because this branch only changes docs and skill
guidance.
- Documentation may need follow-up wording adjustments if reviewers want
a different framing for V1 behavior.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- OpenAI Codex, GPT-5 coding agent, tool-enabled terminal/GitHub
workflow. Exact runtime context window was not exposed by the harness.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

2026-04-28 16:12:03 -05:00

3.1 KiB

Raw Blame History

Paperclip Create Agent API Reference

Core Endpoints

GET /llms/agent-configuration.txt
GET /llms/agent-configuration/:adapterType.txt
GET /llms/agent-icons.txt
GET /api/companies/:companyId/agent-configurations
GET /api/companies/:companyId/skills
POST /api/companies/:companyId/skills/import
GET /api/agents/:agentId/configuration
POST /api/agents/:agentId/skills/sync
POST /api/companies/:companyId/agent-hires
POST /api/companies/:companyId/agents
GET /api/agents/:agentId/config-revisions
POST /api/agents/:agentId/config-revisions/:revisionId/rollback
POST /api/issues/:issueId/approvals
GET /api/approvals/:approvalId/issues

Approval collaboration:

GET /api/approvals/:approvalId
POST /api/approvals/:approvalId/request-revision (board)
POST /api/approvals/:approvalId/resubmit
GET /api/approvals/:approvalId/comments
POST /api/approvals/:approvalId/comments
GET /api/approvals/:approvalId/issues

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

Request body matches agent create shape:

{
  "name": "CTO",
  "role": "cto",
  "title": "Chief Technology Officer",
  "icon": "crown",
  "reportsTo": "uuid-or-null",
  "capabilities": "Owns architecture and engineering execution",
  "desiredSkills": ["vercel-labs/agent-browser/agent-browser"],
  "adapterType": "claude_local",
  "adapterConfig": {
    "cwd": "/absolute/path",
    "model": "claude-sonnet-4-5-20250929"
  },
  "instructionsBundle": {
    "entryFile": "AGENTS.md",
    "files": {
      "AGENTS.md": "You are CTO..."
    }
  },
  "runtimeConfig": {
    "heartbeat": {
      "enabled": false,
      "wakeOnDemand": true
    }
  },
  "budgetMonthlyCents": 0,
  "sourceIssueId": "uuid-or-null",
  "sourceIssueIds": ["uuid-1", "uuid-2"]
}

Response:

{
  "agent": {
    "id": "uuid",
    "status": "pending_approval"
  },
  "approval": {
    "id": "uuid",
    "type": "hire_agent",
    "status": "pending",
    "payload": {
      "desiredSkills": ["vercel-labs/agent-browser/agent-browser"]
    }
  }
}

If company setting disables required approval, approval is null and the agent is created as idle.

desiredSkills accepts company skill ids, canonical keys, or a unique slug. The server resolves and stores canonical company skill keys. Leave timer heartbeats disabled by default. Only set runtimeConfig.heartbeat.enabled=true and include an intervalSec when the role truly needs scheduled recurring work or the user explicitly requested it.

Approval Lifecycle

Statuses:

pending
revision_requested
approved
rejected
cancelled

For hire approvals:

approved: linked agent transitions pending_approval -> idle
rejected: linked agent is terminated

Safety Notes

Config read APIs redact obvious secrets.
pending_approval agents cannot run heartbeats, receive assignments, or create keys.
All actions are logged in activity for auditability.
Use markdown in issue/approval comments and include links to approval, agent, and source issue.
After approval resolution, requester may be woken with PAPERCLIP_APPROVAL_ID and should reconcile linked issues.

3.1 KiB Raw Blame History