@penclipai/adapter-codex-local 2026.426.0 → 2026.505.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.d.ts +2 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +12 -0
- package/dist/index.js.map +1 -1
- package/dist/server/execute.d.ts.map +1 -1
- package/dist/server/execute.js +51 -36
- package/dist/server/execute.js.map +1 -1
- package/dist/server/execute.remote.test.js +56 -1
- package/dist/server/execute.remote.test.js.map +1 -1
- package/dist/server/test.d.ts.map +1 -1
- package/dist/server/test.js +27 -7
- package/dist/server/test.js.map +1 -1
- package/dist/ui/build-config.d.ts.map +1 -1
- package/dist/ui/build-config.js +0 -4
- package/dist/ui/build-config.js.map +1 -1
- package/package.json +2 -2
- package/skills/diagnose-why-work-stopped/SKILL.md +161 -0
- package/skills/paperclip/SKILL.md +37 -26
- package/skills/paperclip/references/api-reference.md +6 -2
- package/skills/paperclip-converting-plans-to-tasks/SKILL.md +42 -0
- package/skills/paperclip-create-agent/SKILL.md +3 -2
- package/skills/paperclip-create-agent/references/agent-instruction-templates.md +1 -1
- package/skills/paperclip-create-agent/references/api-reference.md +7 -2
- package/skills/paperclip-create-agent/references/baseline-role-guide.md +1 -1
- package/skills/paperclip-create-agent/references/draft-review-checklist.md +2 -2
- package/skills/paperclip-dev/SKILL.md +267 -0
- package/skills/terminal-bench-loop/SKILL.md +236 -0
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"build-config.js","sourceRoot":"","sources":["../../src/ui/build-config.ts"],"names":[],"mappings":"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
|
|
1
|
+
{"version":3,"file":"build-config.js","sourceRoot":"","sources":["../../src/ui/build-config.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@penclipai/adapter-codex-local",
|
|
3
|
-
"version": "2026.
|
|
3
|
+
"version": "2026.505.0",
|
|
4
4
|
"license": "MIT",
|
|
5
5
|
"homepage": "https://github.com/penclipai/paperclip-cn",
|
|
6
6
|
"bugs": {
|
|
@@ -38,7 +38,7 @@
|
|
|
38
38
|
"skills"
|
|
39
39
|
],
|
|
40
40
|
"dependencies": {
|
|
41
|
-
"@penclipai/adapter-utils": "2026.
|
|
41
|
+
"@penclipai/adapter-utils": "2026.505.0",
|
|
42
42
|
"picocolors": "^1.1.1"
|
|
43
43
|
},
|
|
44
44
|
"devDependencies": {
|
|
@@ -0,0 +1,161 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: diagnose-why-work-stopped
|
|
3
|
+
description: >
|
|
4
|
+
How to handle "why did this work stop / why is this looping?" assignments.
|
|
5
|
+
Forensics first on the named tree, surface the exact stop-point, frame the
|
|
6
|
+
fix as a general product rule that respects three invariants (productive
|
|
7
|
+
work continues, only real blockers stop work, no infinite loops), and
|
|
8
|
+
deliver a plan — no code changes — gated by board/CTO approval before
|
|
9
|
+
child issues are created. Use whenever the issue title or body asks for
|
|
10
|
+
forensics on a stalled, looping, or "went too deep" tree.
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
# Diagnose Why Work Stopped
|
|
14
|
+
|
|
15
|
+
A repeatable procedure for the recurring class of issues where the user (or a manager) points at a stalled / looping / over-recovered issue tree and asks "why did this stop / why is this looping / how do we make sure this doesn't happen again?"
|
|
16
|
+
|
|
17
|
+
This skill is **diagnostic + product-design**, not engineering. The output is a written root cause and an approved plan. No code changes leave this skill.
|
|
18
|
+
|
|
19
|
+
Canonical execution model: read `doc/execution-semantics.md` before diagnosing or proposing a new liveness/recovery rule. Use that document as the source of truth for status, action-path, post-run disposition, bounded continuation, productivity review, pause-hold, watchdog, and explicit recovery semantics. If the investigation finds a true product-rule gap, the plan should say whether `doc/execution-semantics.md` needs a matching update.
|
|
20
|
+
|
|
21
|
+
## When to use
|
|
22
|
+
|
|
23
|
+
Trigger on an assignment whose title or body matches any of:
|
|
24
|
+
|
|
25
|
+
- "why did this work stop", "why did this stall", "why did this just stop"
|
|
26
|
+
- "infinite loop", "looping", "spinning", "going too deep", "recovery went too deep"
|
|
27
|
+
- "liveness — what happened here", "this tree stopped working", "stuck"
|
|
28
|
+
- "approach it from a product perspective", "general product principle / rule"
|
|
29
|
+
- An attached link to a specific stalled / looping / over-recovered issue tree
|
|
30
|
+
|
|
31
|
+
Also use when the user asks for forensics, root cause, or a write-up *before* any product change.
|
|
32
|
+
|
|
33
|
+
## When NOT to use
|
|
34
|
+
|
|
35
|
+
- The assignment asks you to ship a code change directly. Use normal engineering flow.
|
|
36
|
+
- The assignment is a normal bug report against a specific feature. Use normal investigation.
|
|
37
|
+
- You are the original implementer being asked to fix your own bug. Use normal debugging.
|
|
38
|
+
|
|
39
|
+
## Three invariants you must preserve
|
|
40
|
+
|
|
41
|
+
Every diagnosis and every proposed rule must hold these three invariants together. The user has restated them on at least four issues; treat them as load-bearing:
|
|
42
|
+
|
|
43
|
+
1. **Productive work continues.** Agents that have a clear next action must keep working without needing the user to wake them. ([PAP-2674](/PAP/issues/PAP-2674), [PAP-2708](/PAP/issues/PAP-2708))
|
|
44
|
+
2. **Only real blockers stop work.** Stops happen when something genuinely cannot proceed (missing approval, missing dependency, human owner). Pseudo-stops (in_review with no action path, cancelled leaves, malformed metadata) must be detected and routed, not left silent. ([PAP-2335](/PAP/issues/PAP-2335), [PAP-2674](/PAP/issues/PAP-2674))
|
|
45
|
+
3. **No infinite loops.** Stranded-work recovery and continuation loops must be bounded and distinguishable from genuinely productive continuation. ([PAP-2602](/PAP/issues/PAP-2602), [PAP-2486](/PAP/issues/PAP-2486))
|
|
46
|
+
|
|
47
|
+
If a proposed rule violates any of the three, drop it or rework it. State explicitly in the plan how each invariant is held.
|
|
48
|
+
|
|
49
|
+
## Procedure
|
|
50
|
+
|
|
51
|
+
### 0. Read the current execution contract
|
|
52
|
+
|
|
53
|
+
Before walking the tree, read `doc/execution-semantics.md` and keep its terms intact:
|
|
54
|
+
|
|
55
|
+
- live path / waiting path / recovery path
|
|
56
|
+
- post-run disposition: terminal, explicitly live, explicitly waiting, invalid
|
|
57
|
+
- bounded `run_liveness_continuation`
|
|
58
|
+
- productivity review vs liveness recovery
|
|
59
|
+
- active subtree pause holds
|
|
60
|
+
- silent active-run watchdog
|
|
61
|
+
|
|
62
|
+
Do not invent a new rule until you can state how it differs from the current execution semantics document.
|
|
63
|
+
|
|
64
|
+
### 1. Forensics on the named tree — before anything else
|
|
65
|
+
|
|
66
|
+
Do this in the same heartbeat. Do not propose a rule until you have a concrete stop point.
|
|
67
|
+
|
|
68
|
+
- Open the linked issue (and its blocker chain, parents, recovery siblings, recent runs).
|
|
69
|
+
- Walk the tree node-by-node and find the exact issue + state combination that stops the world. Common shapes seen in the company so far:
|
|
70
|
+
- `in_review` with no typed execution participant, no active run, no pending interaction, no recovery issue ([PAP-2335](/PAP/issues/PAP-2335), [PAP-2674](/PAP/issues/PAP-2674)).
|
|
71
|
+
- `in_progress` after a successful run with no future action path queued ([PAP-2674](/PAP/issues/PAP-2674)).
|
|
72
|
+
- Blocker chain whose leaf is `cancelled` / malformed / cross-company-inaccessible ([PAP-2602](/PAP/issues/PAP-2602)).
|
|
73
|
+
- `issue.continuation_recovery` waking the same issue >N times after successful runs ([PAP-2602](/PAP/issues/PAP-2602)).
|
|
74
|
+
- Stranded-work recovery treating its own recovery issues as more recoverable source work ([PAP-2486](/PAP/issues/PAP-2486)).
|
|
75
|
+
- Quote the evidence: run ids, comment timestamps, status transitions. "Inferred" is acceptable only when an API boundary blocks direct evidence — say so explicitly and mark the claim provisional ([PAP-2631](/PAP/issues/PAP-2631)).
|
|
76
|
+
|
|
77
|
+
Respect the API boundary. If the linked issue is in another company and your agent token returns 403, do not bypass scoping. Either request a board-approved diagnostic path or proceed from inferred PAP-side evidence and label it.
|
|
78
|
+
|
|
79
|
+
### 2. Survey recent related work
|
|
80
|
+
|
|
81
|
+
Before proposing a new product rule, read what already shipped this week in the same area. The user has explicitly called this out: ([PAP-2602](/PAP/issues/PAP-2602)) "review our recent work on liveness that we shipped in the last couple of days." A new rule that contradicts code merged 48 hours ago is rework, not improvement.
|
|
82
|
+
|
|
83
|
+
Quick survey:
|
|
84
|
+
- Recent merged PRs in the affected area.
|
|
85
|
+
- Recent done issues whose title mentions liveness, recovery, productivity, continuation, or the affected subsystem.
|
|
86
|
+
- Any active plan documents on parent issues. The fix may belong as a revision to an existing plan, not as a new top-level proposal.
|
|
87
|
+
|
|
88
|
+
State in the forensics: "I reviewed X, Y, Z. The new gap is …"
|
|
89
|
+
|
|
90
|
+
### 3. Classify each non-progressing issue in the tree
|
|
91
|
+
|
|
92
|
+
For every issue in the affected tree that is not `done` / `cancelled` / actively running, decide:
|
|
93
|
+
|
|
94
|
+
- **Truly needs human or board intervention** — name the owner and the action.
|
|
95
|
+
- **Agent-actionable but not currently routed** — name the rule that would have routed it, and the agent that should have been waked.
|
|
96
|
+
- **Already covered** — point at the active run, queued wake, recovery issue, or pending interaction.
|
|
97
|
+
|
|
98
|
+
This is the table the user has asked for repeatedly ([PAP-2335](/PAP/issues/PAP-2335)). Without it the plan is abstract.
|
|
99
|
+
|
|
100
|
+
### 4. Frame as a general product rule
|
|
101
|
+
|
|
102
|
+
The user does not want a one-off patch on the named tree. They want the rule. Two checks:
|
|
103
|
+
|
|
104
|
+
- The rule is **stated as a contract**, not as an if/else patch. Example contract: "every agent-owned non-terminal issue must finish each heartbeat with a terminal state, an explicit waiting path, or an explicit live path" ([PAP-2674](/PAP/issues/PAP-2674)).
|
|
105
|
+
- The rule is reconciled against `doc/execution-semantics.md`. Prefer citing and applying the existing contract; propose a document change only when the current doc is incomplete or contradicted by accepted/implemented behavior.
|
|
106
|
+
- The rule **explicitly preserves the three invariants** above. Show the work.
|
|
107
|
+
|
|
108
|
+
If the rule would have blocked a recent productive run from succeeding, drop or narrow it.
|
|
109
|
+
|
|
110
|
+
### 5. Plan, do not code
|
|
111
|
+
|
|
112
|
+
Write the plan into the issue's `plan` document. Cover:
|
|
113
|
+
|
|
114
|
+
- Forensics summary (root cause + evidence).
|
|
115
|
+
- The general product rule, stated as a contract.
|
|
116
|
+
- Whether the existing `doc/execution-semantics.md` contract already covers the case, or what exact documentation update is needed.
|
|
117
|
+
- Phased subtasks: typically `Phase 0` resolves the named live tree (carefully, not destructively), `Phase 1` codifies the contract in docs, then implementation phases for detection, recovery, UI surfacing, security review, QA, and CTO review.
|
|
118
|
+
- Explicit assignees per phase; favor team specialty (CodexCoder for server, ClaudeCoder for FE, UXDesigner for visible state, SecurityEngineer for ownership/permissions, QA for validation).
|
|
119
|
+
- Blocking dependencies wired with `blockedByIssueIds`, parallel branches identified.
|
|
120
|
+
|
|
121
|
+
Do not create the child issues yet. Do not push code.
|
|
122
|
+
|
|
123
|
+
### 6. Request approval, then decompose
|
|
124
|
+
|
|
125
|
+
- Open a `request_confirmation` interaction targeting the latest plan revision. Idempotency key `confirmation:{issueId}:plan:{revisionId}`.
|
|
126
|
+
- Wait for board/CTO acceptance. If the user posts a new comment that supersedes the plan, the prior confirmation is invalidated — open a fresh confirmation tied to the new revision ([PAP-2602](/PAP/issues/PAP-2602) cycled three revisions; that is fine).
|
|
127
|
+
- Only after acceptance: create the phased child issues with the right assignees and dependencies, then block this parent on the final QA / CTO review issue so the parent only wakes when the chain finishes.
|
|
128
|
+
|
|
129
|
+
### 7. Phase 0 hygiene on the named tree
|
|
130
|
+
|
|
131
|
+
Phase 0 cleans up the live tree without papering over evidence:
|
|
132
|
+
|
|
133
|
+
- Move stalled `in_review` leaves with no participant to `todo` with a precise next action and named owner ([PAP-2335](/PAP/issues/PAP-2335)).
|
|
134
|
+
- Detach cancelled/dead blockers from chains they were holding hostage; do not silently mark issues `done` to clear backlog.
|
|
135
|
+
- Leave a comment on the original named issue summarizing what changed and why; never hide the recovery chain history.
|
|
136
|
+
|
|
137
|
+
### 8. Final close-out
|
|
138
|
+
|
|
139
|
+
When the phase chain is complete, post a board-level summary comment on the parent issue: what changed, what the new contract is, what the rollout step is (e.g. "restart the control-plane to pick up the new response shape"), and the live state of the originally-named tree. Then close the parent.
|
|
140
|
+
|
|
141
|
+
## Pitfalls
|
|
142
|
+
|
|
143
|
+
- **Coding before approval.** The user has said "make a plan first" on every recent diagnostic issue. Producing code in the forensic phase wastes the round-trip.
|
|
144
|
+
- **Restating one invariant at the cost of another.** Bound continuation too tightly and productive work stalls; loosen recovery and infinite loops return. Always check all three.
|
|
145
|
+
- **Skipping the recent-work survey.** Proposing a contract that contradicts what shipped 24 hours ago is the easiest way to get the plan rejected.
|
|
146
|
+
- **Letting "in_review" mean done.** A leaf assigned to another agent with no participant or active run is not progress; treat it as a stop.
|
|
147
|
+
- **Bypassing company scoping.** Cross-company forensics needs a board-approved diagnostic path, not a database read.
|
|
148
|
+
- **Recursive recovery.** Stranded-work recovery that recovers its own recovery issues is the canonical infinite loop ([PAP-2486](/PAP/issues/PAP-2486)). Detect it and refuse to deepen.
|
|
149
|
+
- **Hiding the chain.** Don't silently delete or hide the symptomatic recovery issues — the operator needs the audit trail.
|
|
150
|
+
|
|
151
|
+
## Verification checklist (before posting the plan)
|
|
152
|
+
|
|
153
|
+
- [ ] The exact stop point in the named tree is identified with run ids / comment ids.
|
|
154
|
+
- [ ] Recent shipped work in the same area was surveyed and is referenced.
|
|
155
|
+
- [ ] Every non-progressing issue is classified human-needed / agent-actionable / already-covered.
|
|
156
|
+
- [ ] The proposed rule is stated as a contract, not a patch.
|
|
157
|
+
- [ ] All three invariants are explicitly preserved.
|
|
158
|
+
- [ ] No code change has landed in this heartbeat.
|
|
159
|
+
- [ ] A `request_confirmation` against the latest plan revision is open.
|
|
160
|
+
- [ ] Phase 0 of the plan addresses the live named tree without destroying evidence.
|
|
161
|
+
- [ ] Implementation phases name specialty-appropriate assignees and `blockedByIssueIds` dependencies.
|
|
@@ -89,6 +89,7 @@ If `currentParticipant` does not match you, do not try to advance the stage —
|
|
|
89
89
|
- If the issue is actionable, start concrete work in the same heartbeat. Do not stop at a plan unless the issue specifically asks for planning.
|
|
90
90
|
- Leave durable progress in comments, issue documents, or work products, and include the next action before you exit.
|
|
91
91
|
- Use child issues for parallel or long delegated work; do not busy-poll agents, sessions, child issues, or processes waiting for completion.
|
|
92
|
+
- If your heartbeat creates a pending board/user interaction or approval before more work can proceed, leave the source issue in an explicit waiting posture before you exit. Prefer `in_review` for review, approval, `request_confirmation`, `ask_user_questions`, and `suggest_tasks` waits. Use `blocked` with `blockedByIssueIds` when another issue is the blocker.
|
|
92
93
|
- If blocked, move the issue to `blocked` with the unblock owner and exact action needed.
|
|
93
94
|
- Respect budget, pause/cancel, approval gates, execution policy stages, and company boundaries.
|
|
94
95
|
|
|
@@ -121,7 +122,7 @@ Status values: `backlog`, `todo`, `in_progress`, `in_review`, `done`, `blocked`,
|
|
|
121
122
|
- `backlog` — parked/unscheduled, not something you're about to start this heartbeat.
|
|
122
123
|
- `todo` — ready and actionable, but not checked out yet. Use for newly assigned or resumable work; don't PATCH into `in_progress` just to signal intent — enter `in_progress` by checkout.
|
|
123
124
|
- `in_progress` — actively owned, execution-backed work.
|
|
124
|
-
- `in_review` — paused pending reviewer/approver/board/user feedback. Use when handing work off for review
|
|
125
|
+
- `in_review` — paused pending reviewer/approver/board/user feedback. Use when handing work off for review, plan confirmation, issue-thread interaction response, or approval. This is a healthy waiting path, not a synonym for done. If a human asks to take the task back, reassign to them and set `in_review`.
|
|
125
126
|
- `blocked` — cannot proceed until something specific changes. Always name the blocker and who must act, and prefer `blockedByIssueIds` over free-text when another issue is the blocker. `parentId` alone does not imply a blocker.
|
|
126
127
|
- `done` — work complete, no follow-up on this issue.
|
|
127
128
|
- `cancelled` — intentionally abandoned, not to be resumed.
|
|
@@ -232,6 +233,10 @@ For commands, response fields, and MCP tools, read:
|
|
|
232
233
|
- **Hiring**: use the `paperclip-create-agent` skill for new agent creation workflows (links to reusable `AGENTS.md` templates like `Coder` and `QA`).
|
|
233
234
|
- **Commit Co-author**: if you make a git commit you MUST add EXACTLY `Co-Authored-By: Paperclip <noreply@paperclip.ing>` to the end of each commit message. Do not put in your agent name, put `Co-Authored-By: Paperclip <noreply@paperclip.ing>`.
|
|
234
235
|
|
|
236
|
+
This is rule #1:
|
|
237
|
+
|
|
238
|
+
IMPORTANT: **NEVER ASK A HUMAN TO DO WHAT AN AGENT COULD DO**. If you need to escalate, escalate. If you could ask your CEO to do it, then _you do that_ - don't hand it back to a human. Again: Never ask a human to do what an agent _could_ do. Rule number 1.
|
|
239
|
+
|
|
235
240
|
## Comment Style (Required)
|
|
236
241
|
|
|
237
242
|
When posting issue comments or writing issue descriptions, use concise markdown with:
|
|
@@ -276,7 +281,7 @@ Submitted CTO hire request and linked it for board review.
|
|
|
276
281
|
|
|
277
282
|
## Planning (Required when planning requested)
|
|
278
283
|
|
|
279
|
-
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.
|
|
284
|
+
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.
|
|
280
285
|
|
|
281
286
|
When you mention a plan or another issue document in a comment, include a direct document link using the key:
|
|
282
287
|
|
|
@@ -285,9 +290,13 @@ When you mention a plan or another issue document in a comment, include a direct
|
|
|
285
290
|
|
|
286
291
|
If the issue identifier is available, prefer the document deep link over a plain issue link so the reader lands directly on the updated document.
|
|
287
292
|
|
|
288
|
-
If you're asked to make a plan, _do not mark the issue as done_.
|
|
293
|
+
If you're asked to make a plan, _do not mark the issue as done_. When the plan is ready for review, leave the issue in `in_review` and make the reviewer/decision path explicit. If the requester specifically asked to take the issue back, reassign it to that user; otherwise keep the assignee in place so the accepted confirmation can wake the right agent.
|
|
294
|
+
|
|
295
|
+
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, then update the source issue to `in_review` with a comment that links the plan and names the pending confirmation. This is a deliberate waiting path, not an abandoned productive run. Wait for acceptance before creating implementation subtasks. See `references/api-reference.md` for the interaction payload.
|
|
289
296
|
|
|
290
|
-
|
|
297
|
+
When asked to convert a plan into executable Paperclip tasks — depth, assignment, dependencies, parallelization — use the companion skill `paperclip-converting-plans-to-tasks`.
|
|
298
|
+
|
|
299
|
+
When asked to convert a plan into executable Paperclip tasks — depth, assignment, dependencies, parallelization — use the companion skill `paperclip-converting-plans-to-tasks`.
|
|
291
300
|
|
|
292
301
|
Recommended API flow:
|
|
293
302
|
|
|
@@ -305,29 +314,29 @@ If `plan` already exists, fetch the current document first and send its latest `
|
|
|
305
314
|
|
|
306
315
|
## Key Endpoints (Hot Routes)
|
|
307
316
|
|
|
308
|
-
| Action | Endpoint
|
|
309
|
-
| ------------------------------------- |
|
|
310
|
-
| My identity | `GET /api/agents/me`
|
|
311
|
-
| My compact inbox | `GET /api/agents/me/inbox-lite`
|
|
312
|
-
| My assignments | `GET /api/companies/:companyId/issues?assigneeAgentId=:id&status=todo,in_progress,in_review,blocked`
|
|
313
|
-
| Checkout task | `POST /api/issues/:issueId/checkout`
|
|
314
|
-
| Get task + ancestors | `GET /api/issues/:issueId`
|
|
315
|
-
| Compact heartbeat context | `GET /api/issues/:issueId/heartbeat-context`
|
|
316
|
-
| Update task | `PATCH /api/issues/:issueId` (optional `comment` field)
|
|
317
|
-
| Get comments / delta / single | `GET /api/issues/:issueId/comments[?after=:commentId&order=asc]` • `/comments/:commentId`
|
|
318
|
-
| Add comment | `POST /api/issues/:issueId/comments`
|
|
317
|
+
| Action | Endpoint |
|
|
318
|
+
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
|
|
319
|
+
| My identity | `GET /api/agents/me` |
|
|
320
|
+
| My compact inbox | `GET /api/agents/me/inbox-lite` |
|
|
321
|
+
| My assignments | `GET /api/companies/:companyId/issues?assigneeAgentId=:id&status=todo,in_progress,in_review,blocked` |
|
|
322
|
+
| Checkout task | `POST /api/issues/:issueId/checkout` |
|
|
323
|
+
| Get task + ancestors | `GET /api/issues/:issueId` |
|
|
324
|
+
| Compact heartbeat context | `GET /api/issues/:issueId/heartbeat-context` |
|
|
325
|
+
| Update task | `PATCH /api/issues/:issueId` (optional `comment` field) |
|
|
326
|
+
| Get comments / delta / single | `GET /api/issues/:issueId/comments[?after=:commentId&order=asc]` • `/comments/:commentId` |
|
|
327
|
+
| Add comment | `POST /api/issues/:issueId/comments` |
|
|
319
328
|
| Issue-thread interactions | `GET\|POST /api/issues/:issueId/interactions` • `POST /api/issues/:issueId/interactions/:interactionId/{accept,reject,respond}` |
|
|
320
|
-
| Create subtask | `POST /api/companies/:companyId/issues`
|
|
321
|
-
| Release task | `POST /api/issues/:issueId/release`
|
|
322
|
-
| Search issues | `GET /api/companies/:companyId/issues?q=search+term`
|
|
323
|
-
| Issue documents (list/get/put) | `GET\|PUT /api/issues/:issueId/documents[/:key]`
|
|
324
|
-
| Create approval | `POST /api/companies/:companyId/approvals`
|
|
325
|
-
| Upload attachment (multipart, `file`) | `POST /api/companies/:companyId/issues/:issueId/attachments`
|
|
326
|
-
| List / get / delete attachment | `GET /api/issues/:issueId/attachments` • `GET\|DELETE /api/attachments/:attachmentId[/content]`
|
|
327
|
-
| Execution workspace + runtime | `GET /api/execution-workspaces/:id` • `POST …/runtime-services/:action`
|
|
328
|
-
| Set agent instructions path | `PATCH /api/agents/:agentId/instructions-path`
|
|
329
|
-
| List agents | `GET /api/companies/:companyId/agents`
|
|
330
|
-
| Dashboard | `GET /api/companies/:companyId/dashboard`
|
|
329
|
+
| Create subtask | `POST /api/companies/:companyId/issues` |
|
|
330
|
+
| Release task | `POST /api/issues/:issueId/release` |
|
|
331
|
+
| Search issues | `GET /api/companies/:companyId/issues?q=search+term` |
|
|
332
|
+
| Issue documents (list/get/put) | `GET\|PUT /api/issues/:issueId/documents[/:key]` |
|
|
333
|
+
| Create approval | `POST /api/companies/:companyId/approvals` |
|
|
334
|
+
| Upload attachment (multipart, `file`) | `POST /api/companies/:companyId/issues/:issueId/attachments` |
|
|
335
|
+
| List / get / delete attachment | `GET /api/issues/:issueId/attachments` • `GET\|DELETE /api/attachments/:attachmentId[/content]` |
|
|
336
|
+
| Execution workspace + runtime | `GET /api/execution-workspaces/:id` • `POST …/runtime-services/:action` |
|
|
337
|
+
| Set agent instructions path | `PATCH /api/agents/:agentId/instructions-path` |
|
|
338
|
+
| List agents | `GET /api/companies/:companyId/agents` |
|
|
339
|
+
| Dashboard | `GET /api/companies/:companyId/dashboard` |
|
|
331
340
|
|
|
332
341
|
Full endpoint table (company imports/exports, OpenClaw invites, company skills, routines, etc.) lives in `references/api-reference.md`.
|
|
333
342
|
|
|
@@ -344,3 +353,5 @@ Results are ranked by relevance: title matches first, then identifier, descripti
|
|
|
344
353
|
## Full Reference
|
|
345
354
|
|
|
346
355
|
For detailed API tables, JSON response schemas, worked examples (IC and Manager heartbeats), governance/approvals, cross-team delegation rules, error codes, issue lifecycle diagram, and the common mistakes table, read: `skills/paperclip/references/api-reference.md`
|
|
356
|
+
|
|
357
|
+
Again, rule #1 is: never ask a human to do what an agent could do. Try harder. Try again. Ask another agent to help. Keep working until the goal is fully accomplished.
|
|
@@ -683,7 +683,8 @@ Rules:
|
|
|
683
683
|
- Rejection does not wake the assignee by default. The board/user can add a normal comment when revisions are needed.
|
|
684
684
|
- Use idempotency keys that include the target and version, for example `confirmation:${issueId}:plan:${latestRevisionId}`.
|
|
685
685
|
- Set `supersedeOnUserComment: true` when a later board/user comment should expire the pending request. On that wake, revise the artifact/proposal and create a fresh confirmation if approval is still needed.
|
|
686
|
-
-
|
|
686
|
+
- A pending interaction is an explicit waiting path. Before ending the heartbeat, update the source issue into a visible waiting posture, normally `in_review`, and leave a comment that names what the board/user must decide.
|
|
687
|
+
- For plan approval, update the `plan` issue document first, create the confirmation against the latest plan revision, set the source issue to `in_review`, and wait for acceptance before creating implementation subtasks.
|
|
687
688
|
|
|
688
689
|
### Checking approval status
|
|
689
690
|
|
|
@@ -724,7 +725,7 @@ Terminal states: `done`, `cancelled`
|
|
|
724
725
|
- `backlog` = not ready to execute yet.
|
|
725
726
|
- `todo` = ready to execute, but not actively checked out yet.
|
|
726
727
|
- `in_progress` = actively owned work. For agents, this should correspond to a live execution path and should be entered via checkout.
|
|
727
|
-
- `in_review` = waiting on review
|
|
728
|
+
- `in_review` = waiting on review, approval, issue-thread interaction response, or board/user confirmation; not active execution.
|
|
728
729
|
- `blocked` = cannot proceed until a specific blocker changes; use `blockedByIssueIds` when another issue is the blocker.
|
|
729
730
|
- `done` = completed.
|
|
730
731
|
- `cancelled` = intentionally abandoned.
|
|
@@ -733,6 +734,9 @@ Terminal states: `done`, `cancelled`
|
|
|
733
734
|
- `completed_at` is auto-set on `done`.
|
|
734
735
|
- One assignee per task at a time.
|
|
735
736
|
- `parentId` is structural and does not create a blocker relationship by itself.
|
|
737
|
+
- Use formal approvals for governed actions such as hires, budget overrides, or CEO strategy gates.
|
|
738
|
+
- Use issue-thread interactions for issue-scoped board/user decisions such as plan acceptance, proposed task breakdowns, or missing-answer questions.
|
|
739
|
+
- Use `blockedByIssueIds` for real work dependencies between issues so Paperclip can wake the blocked assignee when all blockers resolve.
|
|
736
740
|
|
|
737
741
|
---
|
|
738
742
|
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: paperclip-converting-plans-to-tasks
|
|
3
|
+
description: >
|
|
4
|
+
The Paperclip way of converting a plan into executable tasks. Use whenever
|
|
5
|
+
you are asked to plan, scope, or break down work inside a Paperclip company.
|
|
6
|
+
Industry-agnostic guidance on how to translate a plan into assigned issues
|
|
7
|
+
with the right specialty, dependencies, and parallelization so Paperclip's
|
|
8
|
+
executor can pick up the work — it does not prescribe a plan format. Pair
|
|
9
|
+
with the `paperclip` skill, which covers the mechanics of writing the plan
|
|
10
|
+
document and reassigning the issue.
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
# Paperclip — Converting Plans to Tasks
|
|
14
|
+
|
|
15
|
+
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.
|
|
16
|
+
|
|
17
|
+
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.
|
|
18
|
+
|
|
19
|
+
## When you're asked to plan
|
|
20
|
+
|
|
21
|
+
- **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.
|
|
22
|
+
- **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.
|
|
23
|
+
- **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.
|
|
24
|
+
- **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.
|
|
25
|
+
- **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.
|
|
26
|
+
- **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.
|
|
27
|
+
- **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.
|
|
28
|
+
|
|
29
|
+
## Quick checklist before you publish a plan
|
|
30
|
+
|
|
31
|
+
- [ ] Enough detail that assignees can act without re-asking.
|
|
32
|
+
- [ ] Every concrete deliverable is an issue (or named as a known follow-up).
|
|
33
|
+
- [ ] Each issue has a deliberate, specialty-matched assignee — not the planner by default.
|
|
34
|
+
- [ ] Each issue's real blockers are declared via `blockedByIssueIds`.
|
|
35
|
+
- [ ] Independent branches can start in parallel.
|
|
36
|
+
- [ ] Gaps (missing skills, hires, decisions, external inputs) are surfaced, not hidden.
|
|
37
|
+
|
|
38
|
+
## What this skill is not
|
|
39
|
+
|
|
40
|
+
- Not a plan template. Use any format — prose, outline, table, RACI, Gantt, whatever fits.
|
|
41
|
+
- Not software-development–specific. The same rules apply to marketing, research, ops, design, hiring, finance, etc.
|
|
42
|
+
- 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" \
|
|
|
83
83
|
- 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
|
|
84
84
|
- if the role may handle private advisories or sensitive disclosures, confirm a confidential workflow exists first (dedicated skill or documented manual process)
|
|
85
85
|
- capabilities
|
|
86
|
-
-
|
|
86
|
+
- managed instructions bundle (`AGENTS.md`) for adapters that support it; avoid durable `promptTemplate` config
|
|
87
87
|
- 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
|
|
88
|
-
- instruction text such as `AGENTS.md` built from step 4; for local managed-bundle adapters,
|
|
88
|
+
- 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.
|
|
89
89
|
- source issue linkage (`sourceIssueId` or `sourceIssueIds`) when this hire came from an issue
|
|
90
90
|
|
|
91
91
|
### 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
|
|
|
109
109
|
"desiredSkills": ["vercel-labs/agent-browser/agent-browser"],
|
|
110
110
|
"adapterType": "codex_local",
|
|
111
111
|
"adapterConfig": {"cwd": "/abs/path/to/repo", "model": "o4-mini"},
|
|
112
|
+
"instructionsBundle": {"files": {"AGENTS.md": "You are the CTO..."}},
|
|
112
113
|
"runtimeConfig": {"heartbeat": {"enabled": false, "wakeOnDemand": true}},
|
|
113
114
|
"sourceIssueId": "<issue-id>"
|
|
114
115
|
}'
|
|
@@ -41,7 +41,7 @@ If you are hiring a role that is not in this index, do not force a fit. Use the
|
|
|
41
41
|
## How to apply an exact template
|
|
42
42
|
|
|
43
43
|
1. Open the matching reference in `references/agents/`.
|
|
44
|
-
2. Copy that template into the new agent's instruction bundle (usually `AGENTS.md`). For hire requests using local managed-bundle adapters,
|
|
44
|
+
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`.
|
|
45
45
|
3. Replace placeholders like `{{companyName}}`, `{{managerTitle}}`, `{{issuePrefix}}`, and URLs.
|
|
46
46
|
4. Remove tools or workflows the target adapter cannot use.
|
|
47
47
|
5. Keep the Paperclip heartbeat requirement and the task-comment requirement.
|
|
@@ -42,8 +42,13 @@ Request body matches agent create shape:
|
|
|
42
42
|
"adapterType": "claude_local",
|
|
43
43
|
"adapterConfig": {
|
|
44
44
|
"cwd": "/absolute/path",
|
|
45
|
-
"model": "claude-sonnet-4-5-20250929"
|
|
46
|
-
|
|
45
|
+
"model": "claude-sonnet-4-5-20250929"
|
|
46
|
+
},
|
|
47
|
+
"instructionsBundle": {
|
|
48
|
+
"entryFile": "AGENTS.md",
|
|
49
|
+
"files": {
|
|
50
|
+
"AGENTS.md": "You are CTO..."
|
|
51
|
+
}
|
|
47
52
|
},
|
|
48
53
|
"runtimeConfig": {
|
|
49
54
|
"heartbeat": {
|
|
@@ -118,7 +118,7 @@ How the agent verifies its own work before marking an issue done or handing it t
|
|
|
118
118
|
- **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.
|
|
119
119
|
- **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.
|
|
120
120
|
- **Permission sprawl.** Do not grant write access, admin endpoints, or broad skill sets "just in case." Grant exactly what the role needs.
|
|
121
|
-
- **Secrets in
|
|
121
|
+
- **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.
|
|
122
122
|
- **Silent timer heartbeats.** A timer heartbeat burns budget every interval. If the role has no scheduled work, leave it off.
|
|
123
123
|
- **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.
|
|
124
124
|
- **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.
|
|
|
57
57
|
- [ ] `sourceIssueId` (or `sourceIssueIds`) is set when the hire was triggered by an issue
|
|
58
58
|
- [ ] `desiredSkills` lists only skills that already exist in the company library, or will be installed first via the company-skills workflow
|
|
59
59
|
- [ ] Adapter config matches this Paperclip instance (cwd, model, credentials) per `/llms/agent-configuration/<adapter>.txt`
|
|
60
|
-
- [ ]
|
|
60
|
+
- [ ] Local managed-bundle adapters send custom instructions through top-level `instructionsBundle.files["AGENTS.md"]` and do not set `adapterConfig.promptTemplate` or `bootstrapPromptTemplate`
|
|
61
61
|
- [ ] Placeholders like `{{companyName}}`, `{{managerTitle}}`, `{{issuePrefix}}`, and any URL stubs are replaced with real values
|
|
62
62
|
|
|
63
63
|
## H. Safety and permissions (least privilege)
|
|
64
64
|
|
|
65
65
|
- [ ] The hire grants only the access the role needs — no "just in case" permissions
|
|
66
|
-
- [ ] No secrets are embedded in plain text in `adapterConfig` or
|
|
66
|
+
- [ ] No secrets are embedded in plain text in `adapterConfig`, `instructionsBundle`, or any legacy prompt field; prefer environment-injected credentials or scoped skills
|
|
67
67
|
- [ ] 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
|
|
68
68
|
- [ ] `runtimeConfig.heartbeat.enabled` is `false` unless the role genuinely needs scheduled recurring work AND `intervalSec` is justified in the hire comment
|
|
69
69
|
- [ ] `AGENTS.md` explicitly names anything the role must never do (external posts, shared infra changes, destructive ops without approval)
|