mirror of
https://github.com/alkimake/paperclip.git
synced 2026-06-14 01:50:39 +09:00
[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>
This commit is contained in:
Dotta
GitHub
parent
d0bdbe11a9
commit
d9f540c331
13 changed files with 192 additions and 76 deletions
42
skills/paperclip-converting-plans-to-tasks/SKILL.md
Normal file
42
skills/paperclip-converting-plans-to-tasks/SKILL.md
Normal file
|
|
@ -0,0 +1,42 @@
|
|||
---
|
||||
name: paperclip-converting-plans-to-tasks
|
||||
description: >
|
||||
The Paperclip way of converting a plan into executable tasks. Use whenever
|
||||
you are asked to plan, scope, or break down work inside a Paperclip company.
|
||||
Industry-agnostic guidance on how to translate a plan into assigned issues
|
||||
with the right specialty, dependencies, and parallelization so Paperclip's
|
||||
executor can pick up the work — it does not prescribe a plan format. Pair
|
||||
with the `paperclip` skill, which covers the mechanics of writing the plan
|
||||
document and reassigning the issue.
|
||||
---
|
||||
|
||||
# Paperclip — Converting Plans to Tasks
|
||||
|
||||
A companion skill for turning a plan into executable Paperclip work. It does **not** dictate a plan structure — bring whatever format fits the work and the user's preference. It tells you _how_ to translate that plan into issues so that the rest of Paperclip works for you.
|
||||
|
||||
For the **mechanics** of recording a plan (issue document with key `plan`, comment links, approval gating, who to reassign back to), follow the _Planning_ section of the `paperclip` skill. This skill covers planning method, not the API surface.
|
||||
|
||||
## When you're asked to plan
|
||||
|
||||
- **Plan deeply.** Capture as much real detail as you have: goals, constraints, unknowns, success criteria, risks. A shallow plan becomes rework downstream — assignees can only act on what they can read.
|
||||
- **Know your team.** Before assigning anything, look up the company's agents and their specialties (reporting lines, role descriptions, prior work). Don't default work to yourself when a better-suited agent exists; don't assign to a name you haven't checked.
|
||||
- **Assign for specialty.** Hand each piece of work to the agent most relevant to it. If no one fits, call that out — a hire, a tool, an external dependency, a board decision — instead of papering over the gap.
|
||||
- **Take responsibility.** Specialty-matching cuts both ways: when _you_ are the best-suited agent for a piece of work, assign it to yourself instead of reflexively delegating. Don't hand off to avoid load.
|
||||
- **Use the dependency tree.** Paperclip's executor automatically starts any assigned task with no open blockers. Express every concrete deliverable as an issue, and wire real blockers via `blockedByIssueIds` (not prose like "blocked by X"). When `done`, dependents auto-wake.
|
||||
- **Order, then parallelize.** Sequence work by real dependencies, not by personal preference. Independent branches of the graph should start in parallel. Unlike humans, most agents allow concurrent runs, so you can assign parallel work to the same agent.
|
||||
- **Enough is enough.** Plans exist to unblock execution, not replace it. If the next step is small and clear, just do it or allow the plan to stand on its own. Re-planning a plan, or splitting work that one agent could finish in the time it took to break it up, is procrastination — ship something.
|
||||
|
||||
## Quick checklist before you publish a plan
|
||||
|
||||
- [ ] Enough detail that assignees can act without re-asking.
|
||||
- [ ] Every concrete deliverable is an issue (or named as a known follow-up).
|
||||
- [ ] Each issue has a deliberate, specialty-matched assignee — not the planner by default.
|
||||
- [ ] Each issue's real blockers are declared via `blockedByIssueIds`.
|
||||
- [ ] Independent branches can start in parallel.
|
||||
- [ ] Gaps (missing skills, hires, decisions, external inputs) are surfaced, not hidden.
|
||||
|
||||
## What this skill is not
|
||||
|
||||
- Not a plan template. Use any format — prose, outline, table, RACI, Gantt, whatever fits.
|
||||
- Not software-development–specific. The same rules apply to marketing, research, ops, design, hiring, finance, etc.
|
||||
- Not a replacement for the `paperclip` skill's planning mechanics. Use both.
|
||||
|
|
@ -83,9 +83,9 @@ curl -sS "$PAPERCLIP_API_URL/llms/agent-icons.txt" \
|
|||
- leave timer heartbeats off by default; only set `runtimeConfig.heartbeat.enabled=true` with an `intervalSec` when the role genuinely needs scheduled recurring work or the user explicitly asked for it
|
||||
- if the role may handle private advisories or sensitive disclosures, confirm a confidential workflow exists first (dedicated skill or documented manual process)
|
||||
- capabilities
|
||||
- run prompt in adapter config (`promptTemplate` where applicable)
|
||||
- managed instructions bundle (`AGENTS.md`) for adapters that support it; avoid durable `promptTemplate` config
|
||||
- for coding or execution agents, include the Paperclip execution contract: start actionable work in the same heartbeat; do not stop at a plan unless planning was requested; leave durable progress with a clear next action; use child issues for long or parallel delegated work instead of polling; mark blocked work with owner/action; respect budget, pause/cancel, approval gates, and company boundaries
|
||||
- instruction text such as `AGENTS.md` built from step 4; for local managed-bundle adapters, put the adapted `AGENTS.md` content in `adapterConfig.promptTemplate` unless you are a board user intentionally managing bundle paths/files
|
||||
- instruction text such as `AGENTS.md` built from step 4; for local managed-bundle adapters, send this as top-level `instructionsBundle.files["AGENTS.md"]`. Do not set `adapterConfig.promptTemplate` or `bootstrapPromptTemplate` for new agents.
|
||||
- source issue linkage (`sourceIssueId` or `sourceIssueIds`) when this hire came from an issue
|
||||
|
||||
### 7. Review the draft against the quality checklist
|
||||
|
|
@ -109,6 +109,7 @@ curl -sS -X POST "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/agent-h
|
|||
"desiredSkills": ["vercel-labs/agent-browser/agent-browser"],
|
||||
"adapterType": "codex_local",
|
||||
"adapterConfig": {"cwd": "/abs/path/to/repo", "model": "o4-mini"},
|
||||
"instructionsBundle": {"files": {"AGENTS.md": "You are the CTO..."}},
|
||||
"runtimeConfig": {"heartbeat": {"enabled": false, "wakeOnDemand": true}},
|
||||
"sourceIssueId": "<issue-id>"
|
||||
}'
|
||||
|
|
|
|||
|
|
@ -41,7 +41,7 @@ If you are hiring a role that is not in this index, do not force a fit. Use the
|
|||
## How to apply an exact template
|
||||
|
||||
1. Open the matching reference in `references/agents/`.
|
||||
2. Copy that template into the new agent's instruction bundle (usually `AGENTS.md`). For hire requests using local managed-bundle adapters, set the adapted template as `adapterConfig.promptTemplate`; Paperclip materializes it into `AGENTS.md`.
|
||||
2. Copy that template into the new agent's instruction bundle (usually `AGENTS.md`). For hire requests using local managed-bundle adapters, send the adapted template as top-level `instructionsBundle.files["AGENTS.md"]`. Do not put new-agent instructions in `adapterConfig.promptTemplate`.
|
||||
3. Replace placeholders like `{{companyName}}`, `{{managerTitle}}`, `{{issuePrefix}}`, and URLs.
|
||||
4. Remove tools or workflows the target adapter cannot use.
|
||||
5. Keep the Paperclip heartbeat requirement and the task-comment requirement.
|
||||
|
|
|
|||
|
|
@ -42,8 +42,13 @@ Request body matches agent create shape:
|
|||
"adapterType": "claude_local",
|
||||
"adapterConfig": {
|
||||
"cwd": "/absolute/path",
|
||||
"model": "claude-sonnet-4-5-20250929",
|
||||
"promptTemplate": "You are CTO..."
|
||||
"model": "claude-sonnet-4-5-20250929"
|
||||
},
|
||||
"instructionsBundle": {
|
||||
"entryFile": "AGENTS.md",
|
||||
"files": {
|
||||
"AGENTS.md": "You are CTO..."
|
||||
}
|
||||
},
|
||||
"runtimeConfig": {
|
||||
"heartbeat": {
|
||||
|
|
|
|||
|
|
@ -118,7 +118,7 @@ How the agent verifies its own work before marking an issue done or handing it t
|
|||
- **Over-generic prompts.** "Be helpful, be thorough, be correct" is worthless — the next agent drafts a better version by reading the template you adapted from. Write role-specific guidance only.
|
||||
- **Lens dumping.** Copying every lens from an expert template into an unrelated role adds noise and burns context. Five well-chosen lenses beat fifteen irrelevant ones.
|
||||
- **Permission sprawl.** Do not grant write access, admin endpoints, or broad skill sets "just in case." Grant exactly what the role needs.
|
||||
- **Secrets in adapter config.** Do not embed long-lived tokens, API keys, or private URLs in `adapterConfig` or `promptTemplate` when environment injection or a scoped skill can carry the capability instead.
|
||||
- **Secrets in agent config.** Do not embed long-lived tokens, API keys, or private URLs in `adapterConfig`, `instructionsBundle`, or legacy prompt fields when environment injection or a scoped skill can carry the capability instead.
|
||||
- **Silent timer heartbeats.** A timer heartbeat burns budget every interval. If the role has no scheduled work, leave it off.
|
||||
- **Bypassing governance.** Never skip `sourceIssueId`, reporting line, icon, or approval flow to ship faster. Hires without these are hard to audit and hard to hand off.
|
||||
- **Copying another company's prompt verbatim.** Placeholders like `{{companyName}}`, `{{managerTitle}}`, and `{{issuePrefix}}` must be replaced with this company's values before submitting the hire.
|
||||
|
|
|
|||
|
|
@ -57,13 +57,13 @@ Use it for every path: exact template, adjacent template, or generic fallback.
|
|||
- [ ] `sourceIssueId` (or `sourceIssueIds`) is set when the hire was triggered by an issue
|
||||
- [ ] `desiredSkills` lists only skills that already exist in the company library, or will be installed first via the company-skills workflow
|
||||
- [ ] Adapter config matches this Paperclip instance (cwd, model, credentials) per `/llms/agent-configuration/<adapter>.txt`
|
||||
- [ ] `adapterConfig.promptTemplate` holds the adapted `AGENTS.md` for local managed-bundle adapters (unless you are intentionally managing bundle paths)
|
||||
- [ ] Local managed-bundle adapters send custom instructions through top-level `instructionsBundle.files["AGENTS.md"]` and do not set `adapterConfig.promptTemplate` or `bootstrapPromptTemplate`
|
||||
- [ ] Placeholders like `{{companyName}}`, `{{managerTitle}}`, `{{issuePrefix}}`, and any URL stubs are replaced with real values
|
||||
|
||||
## H. Safety and permissions (least privilege)
|
||||
|
||||
- [ ] The hire grants only the access the role needs — no "just in case" permissions
|
||||
- [ ] No secrets are embedded in plain text in `adapterConfig` or `promptTemplate` unless the adapter explicitly requires it; prefer environment-injected credentials or scoped skills
|
||||
- [ ] No secrets are embedded in plain text in `adapterConfig`, `instructionsBundle`, or any legacy prompt field; prefer environment-injected credentials or scoped skills
|
||||
- [ ] Any `desiredSkills` or adapter settings that expand external-system access, browser/network reach, filesystem scope, or secret-handling capability are individually justified in the hire comment
|
||||
- [ ] `runtimeConfig.heartbeat.enabled` is `false` unless the role genuinely needs scheduled recurring work AND `intervalSec` is justified in the hire comment
|
||||
- [ ] `AGENTS.md` explicitly names anything the role must never do (external posts, shared infra changes, destructive ops without approval)
|
||||
|
|
|
|||
|
|
@ -276,7 +276,7 @@ Submitted CTO hire request and linked it for board review.
|
|||
|
||||
## Planning (Required when planning requested)
|
||||
|
||||
If you're asked to make a plan, create or update the issue document with key `plan`. Do not append plans into the issue description anymore. If you're asked for plan revisions, update that same `plan` document. In both cases, leave a comment as you normally would and mention that you updated the plan document.
|
||||
If you're asked to make a plan, create or update the issue document with key `plan`. Do not append plans into the issue description anymore. If you're asked for plan revisions, update that same `plan` document. In both cases, leave a comment as you normally would and mention that you updated the plan document. Plans-as-issue-documents is the norm: don't make plans as files in the repo unless you're specifically asked.
|
||||
|
||||
When you mention a plan or another issue document in a comment, include a direct document link using the key:
|
||||
|
||||
|
|
@ -289,6 +289,8 @@ If you're asked to make a plan, _do not mark the issue as done_. Re-assign the i
|
|||
|
||||
If the plan needs explicit approval before implementation, update the `plan` document, create a `request_confirmation` issue-thread interaction bound to the latest plan revision, and wait for acceptance before creating implementation subtasks. See `references/api-reference.md` for the interaction payload.
|
||||
|
||||
When asked to convert a plan into executable Paperclip tasks — depth, assignment, dependencies, parallelization — use the companion skill `paperclip-converting-plans-to-tasks`.
|
||||
|
||||
Recommended API flow:
|
||||
|
||||
```bash
|
||||
|
|
@ -305,29 +307,29 @@ If `plan` already exists, fetch the current document first and send its latest `
|
|||
|
||||
## Key Endpoints (Hot Routes)
|
||||
|
||||
| Action | Endpoint |
|
||||
| ------------------------------------- | ---------------------------------------------------------------------------------------------------- |
|
||||
| My identity | `GET /api/agents/me` |
|
||||
| My compact inbox | `GET /api/agents/me/inbox-lite` |
|
||||
| My assignments | `GET /api/companies/:companyId/issues?assigneeAgentId=:id&status=todo,in_progress,in_review,blocked` |
|
||||
| Checkout task | `POST /api/issues/:issueId/checkout` |
|
||||
| Get task + ancestors | `GET /api/issues/:issueId` |
|
||||
| Compact heartbeat context | `GET /api/issues/:issueId/heartbeat-context` |
|
||||
| Update task | `PATCH /api/issues/:issueId` (optional `comment` field) |
|
||||
| Get comments / delta / single | `GET /api/issues/:issueId/comments[?after=:commentId&order=asc]` • `/comments/:commentId` |
|
||||
| Add comment | `POST /api/issues/:issueId/comments` |
|
||||
| Action | Endpoint |
|
||||
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| My identity | `GET /api/agents/me` |
|
||||
| My compact inbox | `GET /api/agents/me/inbox-lite` |
|
||||
| My assignments | `GET /api/companies/:companyId/issues?assigneeAgentId=:id&status=todo,in_progress,in_review,blocked` |
|
||||
| Checkout task | `POST /api/issues/:issueId/checkout` |
|
||||
| Get task + ancestors | `GET /api/issues/:issueId` |
|
||||
| Compact heartbeat context | `GET /api/issues/:issueId/heartbeat-context` |
|
||||
| Update task | `PATCH /api/issues/:issueId` (optional `comment` field) |
|
||||
| Get comments / delta / single | `GET /api/issues/:issueId/comments[?after=:commentId&order=asc]` • `/comments/:commentId` |
|
||||
| Add comment | `POST /api/issues/:issueId/comments` |
|
||||
| Issue-thread interactions | `GET\|POST /api/issues/:issueId/interactions` • `POST /api/issues/:issueId/interactions/:interactionId/{accept,reject,respond}` |
|
||||
| Create subtask | `POST /api/companies/:companyId/issues` |
|
||||
| Release task | `POST /api/issues/:issueId/release` |
|
||||
| Search issues | `GET /api/companies/:companyId/issues?q=search+term` |
|
||||
| Issue documents (list/get/put) | `GET\|PUT /api/issues/:issueId/documents[/:key]` |
|
||||
| Create approval | `POST /api/companies/:companyId/approvals` |
|
||||
| Upload attachment (multipart, `file`) | `POST /api/companies/:companyId/issues/:issueId/attachments` |
|
||||
| List / get / delete attachment | `GET /api/issues/:issueId/attachments` • `GET\|DELETE /api/attachments/:attachmentId[/content]` |
|
||||
| Execution workspace + runtime | `GET /api/execution-workspaces/:id` • `POST …/runtime-services/:action` |
|
||||
| Set agent instructions path | `PATCH /api/agents/:agentId/instructions-path` |
|
||||
| List agents | `GET /api/companies/:companyId/agents` |
|
||||
| Dashboard | `GET /api/companies/:companyId/dashboard` |
|
||||
| Create subtask | `POST /api/companies/:companyId/issues` |
|
||||
| Release task | `POST /api/issues/:issueId/release` |
|
||||
| Search issues | `GET /api/companies/:companyId/issues?q=search+term` |
|
||||
| Issue documents (list/get/put) | `GET\|PUT /api/issues/:issueId/documents[/:key]` |
|
||||
| Create approval | `POST /api/companies/:companyId/approvals` |
|
||||
| Upload attachment (multipart, `file`) | `POST /api/companies/:companyId/issues/:issueId/attachments` |
|
||||
| List / get / delete attachment | `GET /api/issues/:issueId/attachments` • `GET\|DELETE /api/attachments/:attachmentId[/content]` |
|
||||
| Execution workspace + runtime | `GET /api/execution-workspaces/:id` • `POST …/runtime-services/:action` |
|
||||
| Set agent instructions path | `PATCH /api/agents/:agentId/instructions-path` |
|
||||
| List agents | `GET /api/companies/:companyId/agents` |
|
||||
| Dashboard | `GET /api/companies/:companyId/dashboard` |
|
||||
|
||||
Full endpoint table (company imports/exports, OpenClaw invites, company skills, routines, etc.) lives in `references/api-reference.md`.
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue