mirror of
https://github.com/alkimake/paperclip.git
synced 2026-06-14 01:50:39 +09:00
d9f540c331
## 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>
110 lines
3.1 KiB
Markdown
110 lines
3.1 KiB
Markdown
# 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:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```json
|
|
{
|
|
"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.
|