trending/paperclip
1
0
Fork 0
mirror of https://github.com/paperclipai/paperclip.git synced 2026-10-02 02:07:25 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: remove automatic agent escalation from coordination skill (#14188)

Browse Source 
## Thinking Path

> - Paperclip manages work for AI agents.
> - The coordination skill tells agents how to handle blocked work.
> - The skill directs blocked work to managers and other agents.
> - Those agents may lack the same access or authority.
> - These extra assignments delay the required human action.
> - This pull request removes automatic escalation advice.
> - Agents must identify the missing capability and use the correct
approval or human-input path.

## Linked Issues or Issue Description

**Issue type**

Incorrect information.

**Where is the issue?**

The critical rules in `skills/paperclip/SKILL.md` and blocker guidance
in `skills/paperclip/references/api-reference.md`.

**What's wrong?**

The skill tells agents to escalate through `chainOfCommand`, ask another
agent for help, and avoid human help. A manager title does not grant
permission to fix a connection or complete an administrator action.

**Suggested fix**

Remove blanket escalation and agent-first rules. Keep normal delegation
when the recipient has a concrete capability for a bounded task. Use
saved human-input interactions or existing connection and approval flows
for human-only actions.

Searches for open PRs with “escalation”, “chainOfCommand”, and “ask
another agent” found no duplicate skill change. Recovery-routing PRs
change server behavior, which is outside this change.

## What Changed

- Remove the chain-of-command escalation rule and both repeated
agent-first directives.
- Replace manager handoffs in the API reference with direct blocker
handling.
- Keep reporting fields, normal delegation, approval gates, and the ban
on bypassing permission denials.
- Keep the ban on cancelling cross-team tasks. Request a decision
instead of automatically assigning the task to a manager.

## Verification

- Final head `1483e82cc3fe10a7c910230b3779635d6d54c162`: Greptile 5/5,
no outstanding findings, all CI checks pass (optional Storybook jobs
skipped).

- Created a fresh worktree at `.worktrees/skill-blocker-guidance` from
the current master commit.
- Ran `git diff --check`: passed.
- Ran Node assertions against both documents: passed. Removed directives
are absent. Human-input and capability-based delegation guidance is
present.
- Checked that checkout conflict, approval, dependency, and normal
delegation instructions remain.
- Attempted `pnpm -r typecheck`, `pnpm test:run`, and `pnpm build`. None
could run because this environment has no `pnpm` executable.
- Refreshed both generated capability inventories and their derived
contract after skill heading positions changed. Both generator and
live-inventory checks pass. The eval and MCP baselines remain unchanged.
- Ran `node --test
packages/paperclip-runner/scripts/check-capability-inventory.test.mjs`:
all four tests pass.
- Ran `node
packages/paperclip-runner/scripts/check-capability-inventory.mjs` and
`node packages/paperclip-runner/scripts/generate-capability-contract.mjs
--check`: both pass.
- Added explicit requester routing for agent and human scope questions.
Focused Node assertions pass.

## Risks

- Agents can request human input earlier for actions that require human
authority.
- Existing runs or installed copies can keep old skill text until
refreshed.
- This change does not alter server recovery routing or permission
checks.

## Model Used

OpenAI Codex, with reasoning, tool use, and shell execution. The runtime
does not expose a verifiable exact model ID or context window size.

## 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 searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [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
2026-09-28 08:37:26 -05:00
committed by GitHub
co-authored by Paperclip
parent 0f14d26123
commit bacc0e6a98
6 changed files with 244 additions and 248 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/paperclip-runner/docs/capability-contract.md
+35 -35
View File
@@ -65,12 +65,12 @@ The skill/reference inventory and eval cases are the only normative behavior sou
| skill:skills/paperclip/SKILL.md:proposing-credentials-safely:514 | optional_agent_tool | skills/paperclip/SKILL.md:514 |
| skill:skills/paperclip/SKILL.md:reading-granted-secrets:521 | optional_agent_tool | skills/paperclip/SKILL.md:521 |
| skill:skills/paperclip/SKILL.md:critical-rules:547 | optional_agent_tool | skills/paperclip/SKILL.md:547 |
| skill:skills/paperclip/SKILL.md:comment-style-required:571 | always_agent_tool | skills/paperclip/SKILL.md:571 |
| skill:skills/paperclip/SKILL.md:update:603 | optional_agent_tool | skills/paperclip/SKILL.md:603 |
| skill:skills/paperclip/SKILL.md:planning-required-when-planning-requested:613 | optional_agent_tool | skills/paperclip/SKILL.md:613 |
| skill:skills/paperclip/SKILL.md:key-endpoints-hot-routes:646 | optional_agent_tool | skills/paperclip/SKILL.md:646 |
| skill:skills/paperclip/SKILL.md:searching-issues:675 | optional_agent_tool | skills/paperclip/SKILL.md:675 |
| skill:skills/paperclip/SKILL.md:full-reference:685 | optional_agent_tool | skills/paperclip/SKILL.md:685 |
| skill:skills/paperclip/SKILL.md:comment-style-required:567 | always_agent_tool | skills/paperclip/SKILL.md:567 |
| skill:skills/paperclip/SKILL.md:update:599 | optional_agent_tool | skills/paperclip/SKILL.md:599 |
| skill:skills/paperclip/SKILL.md:planning-required-when-planning-requested:609 | optional_agent_tool | skills/paperclip/SKILL.md:609 |
| skill:skills/paperclip/SKILL.md:key-endpoints-hot-routes:642 | optional_agent_tool | skills/paperclip/SKILL.md:642 |
| skill:skills/paperclip/SKILL.md:searching-issues:671 | optional_agent_tool | skills/paperclip/SKILL.md:671 |
| skill:skills/paperclip/SKILL.md:full-reference:681 | optional_agent_tool | skills/paperclip/SKILL.md:681 |
| skill:skills/paperclip/references/artifacts.md:generated-artifacts-and-work-products:1 | always_agent_tool | skills/paperclip/references/artifacts.md:1 |
| skill:skills/paperclip/references/artifacts.md:workspace-only-file-references:15 | optional_agent_tool | skills/paperclip/references/artifacts.md:15 |
| skill:skills/paperclip/references/cases.md:cases:1 | optional_agent_tool | skills/paperclip/references/cases.md:1 |
@@ -167,35 +167,35 @@ The skill/reference inventory and eval cases are the only normative behavior sou
| skill:skills/paperclip/references/api-reference.md:update:639 | optional_agent_tool | skills/paperclip/references/api-reference.md:639 |
| skill:skills/paperclip/references/api-reference.md:cross-team-work-and-delegation:677 | optional_agent_tool | skills/paperclip/references/api-reference.md:677 |
| skill:skills/paperclip/references/api-reference.md:receiving-cross-team-work:681 | optional_agent_tool | skills/paperclip/references/api-reference.md:681 |
| skill:skills/paperclip/references/api-reference.md:escalation:691 | optional_agent_tool | skills/paperclip/references/api-reference.md:691 |
| skill:skills/paperclip/references/api-reference.md:company-context:701 | optional_agent_tool | skills/paperclip/references/api-reference.md:701 |
| skill:skills/paperclip/references/api-reference.md:company-branding-ceo-board:713 | optional_agent_tool | skills/paperclip/references/api-reference.md:713 |
| skill:skills/paperclip/references/api-reference.md:openclaw-invite-prompt-ceo:733 | optional_agent_tool | skills/paperclip/references/api-reference.md:733 |
| skill:skills/paperclip/references/api-reference.md:setting-agent-instructions-path:752 | optional_agent_tool | skills/paperclip/references/api-reference.md:752 |
| skill:skills/paperclip/references/api-reference.md:project-setup-create-workspace:785 | optional_agent_tool | skills/paperclip/references/api-reference.md:785 |
| skill:skills/paperclip/references/api-reference.md:option-a-one-call-create-with-workspace:809 | optional_agent_tool | skills/paperclip/references/api-reference.md:809 |
| skill:skills/paperclip/references/api-reference.md:option-b-two-calls-project-first-then-workspace:828 | optional_agent_tool | skills/paperclip/references/api-reference.md:828 |
| skill:skills/paperclip/references/api-reference.md:governance-and-approvals:857 | optional_agent_tool | skills/paperclip/references/api-reference.md:857 |
| skill:skills/paperclip/references/api-reference.md:requesting-a-hire-management-only:861 | optional_agent_tool | skills/paperclip/references/api-reference.md:861 |
| skill:skills/paperclip/references/api-reference.md:ceo-strategy-approval:926 | optional_agent_tool | skills/paperclip/references/api-reference.md:926 |
| skill:skills/paperclip/references/api-reference.md:questions-and-waiting-for-human-input:935 | always_agent_tool | skills/paperclip/references/api-reference.md:935 |
| skill:skills/paperclip/references/api-reference.md:issue-thread-confirmations:1032 | always_agent_tool | skills/paperclip/references/api-reference.md:1032 |
| skill:skills/paperclip/references/api-reference.md:checkbox-confirmations:1090 | always_agent_tool | skills/paperclip/references/api-reference.md:1090 |
| skill:skills/paperclip/references/api-reference.md:item-verdict-requests:1205 | optional_agent_tool | skills/paperclip/references/api-reference.md:1205 |
| skill:skills/paperclip/references/api-reference.md:checking-approval-status:1315 | optional_agent_tool | skills/paperclip/references/api-reference.md:1315 |
| skill:skills/paperclip/references/api-reference.md:approval-follow-up-requesting-agent:1321 | always_agent_tool | skills/paperclip/references/api-reference.md:1321 |
| skill:skills/paperclip/references/api-reference.md:issue-lifecycle:1339 | always_agent_tool | skills/paperclip/references/api-reference.md:1339 |
| skill:skills/paperclip/references/api-reference.md:error-handling:1369 | control_plane_owned | skills/paperclip/references/api-reference.md:1369 |
| skill:skills/paperclip/references/api-reference.md:full-api-reference:1383 | optional_agent_tool | skills/paperclip/references/api-reference.md:1383 |
| skill:skills/paperclip/references/api-reference.md:agents:1385 | optional_agent_tool | skills/paperclip/references/api-reference.md:1385 |
| skill:skills/paperclip/references/api-reference.md:issues-tasks:1406 | optional_agent_tool | skills/paperclip/references/api-reference.md:1406 |
| skill:skills/paperclip/references/api-reference.md:companies-projects-goals:1446 | optional_agent_tool | skills/paperclip/references/api-reference.md:1446 |
| skill:skills/paperclip/references/api-reference.md:routines:1470 | optional_agent_tool | skills/paperclip/references/api-reference.md:1470 |
| skill:skills/paperclip/references/api-reference.md:approvals-costs-activity-dashboard:1486 | optional_agent_tool | skills/paperclip/references/api-reference.md:1486 |
| skill:skills/paperclip/references/api-reference.md:secrets:1508 | optional_agent_tool | skills/paperclip/references/api-reference.md:1508 |
| skill:skills/paperclip/references/api-reference.md:agent-secret-proposals:1521 | optional_agent_tool | skills/paperclip/references/api-reference.md:1521 |
| skill:skills/paperclip/references/api-reference.md:agent-secret-access:1621 | optional_agent_tool | skills/paperclip/references/api-reference.md:1621 |
| skill:skills/paperclip/references/api-reference.md:common-mistakes:1661 | optional_agent_tool | skills/paperclip/references/api-reference.md:1661 |
| skill:skills/paperclip/references/api-reference.md:questions-and-dependencies:691 | always_agent_tool | skills/paperclip/references/api-reference.md:691 |
| skill:skills/paperclip/references/api-reference.md:company-context:703 | optional_agent_tool | skills/paperclip/references/api-reference.md:703 |
| skill:skills/paperclip/references/api-reference.md:company-branding-ceo-board:715 | optional_agent_tool | skills/paperclip/references/api-reference.md:715 |
| skill:skills/paperclip/references/api-reference.md:openclaw-invite-prompt-ceo:735 | optional_agent_tool | skills/paperclip/references/api-reference.md:735 |
| skill:skills/paperclip/references/api-reference.md:setting-agent-instructions-path:754 | optional_agent_tool | skills/paperclip/references/api-reference.md:754 |
| skill:skills/paperclip/references/api-reference.md:project-setup-create-workspace:787 | optional_agent_tool | skills/paperclip/references/api-reference.md:787 |
| skill:skills/paperclip/references/api-reference.md:option-a-one-call-create-with-workspace:811 | optional_agent_tool | skills/paperclip/references/api-reference.md:811 |
| skill:skills/paperclip/references/api-reference.md:option-b-two-calls-project-first-then-workspace:830 | optional_agent_tool | skills/paperclip/references/api-reference.md:830 |
| skill:skills/paperclip/references/api-reference.md:governance-and-approvals:859 | optional_agent_tool | skills/paperclip/references/api-reference.md:859 |
| skill:skills/paperclip/references/api-reference.md:requesting-a-hire-management-only:863 | optional_agent_tool | skills/paperclip/references/api-reference.md:863 |
| skill:skills/paperclip/references/api-reference.md:ceo-strategy-approval:928 | optional_agent_tool | skills/paperclip/references/api-reference.md:928 |
| skill:skills/paperclip/references/api-reference.md:questions-and-waiting-for-human-input:937 | always_agent_tool | skills/paperclip/references/api-reference.md:937 |
| skill:skills/paperclip/references/api-reference.md:issue-thread-confirmations:1034 | always_agent_tool | skills/paperclip/references/api-reference.md:1034 |
| skill:skills/paperclip/references/api-reference.md:checkbox-confirmations:1092 | always_agent_tool | skills/paperclip/references/api-reference.md:1092 |
| skill:skills/paperclip/references/api-reference.md:item-verdict-requests:1207 | optional_agent_tool | skills/paperclip/references/api-reference.md:1207 |
| skill:skills/paperclip/references/api-reference.md:checking-approval-status:1317 | optional_agent_tool | skills/paperclip/references/api-reference.md:1317 |
| skill:skills/paperclip/references/api-reference.md:approval-follow-up-requesting-agent:1323 | always_agent_tool | skills/paperclip/references/api-reference.md:1323 |
| skill:skills/paperclip/references/api-reference.md:issue-lifecycle:1341 | always_agent_tool | skills/paperclip/references/api-reference.md:1341 |
| skill:skills/paperclip/references/api-reference.md:error-handling:1371 | control_plane_owned | skills/paperclip/references/api-reference.md:1371 |
| skill:skills/paperclip/references/api-reference.md:full-api-reference:1385 | optional_agent_tool | skills/paperclip/references/api-reference.md:1385 |
| skill:skills/paperclip/references/api-reference.md:agents:1387 | optional_agent_tool | skills/paperclip/references/api-reference.md:1387 |
| skill:skills/paperclip/references/api-reference.md:issues-tasks:1408 | optional_agent_tool | skills/paperclip/references/api-reference.md:1408 |
| skill:skills/paperclip/references/api-reference.md:companies-projects-goals:1448 | optional_agent_tool | skills/paperclip/references/api-reference.md:1448 |
| skill:skills/paperclip/references/api-reference.md:routines:1472 | optional_agent_tool | skills/paperclip/references/api-reference.md:1472 |
| skill:skills/paperclip/references/api-reference.md:approvals-costs-activity-dashboard:1488 | optional_agent_tool | skills/paperclip/references/api-reference.md:1488 |
| skill:skills/paperclip/references/api-reference.md:secrets:1510 | optional_agent_tool | skills/paperclip/references/api-reference.md:1510 |
| skill:skills/paperclip/references/api-reference.md:agent-secret-proposals:1523 | optional_agent_tool | skills/paperclip/references/api-reference.md:1523 |
| skill:skills/paperclip/references/api-reference.md:agent-secret-access:1623 | optional_agent_tool | skills/paperclip/references/api-reference.md:1623 |
| skill:skills/paperclip/references/api-reference.md:common-mistakes:1663 | optional_agent_tool | skills/paperclip/references/api-reference.md:1663 |
## Legacy MCP Alias Index
packages/paperclip-runner/generated/capability/capabilities.yaml
+74 -74
View File
@@ -218,54 +218,54 @@
"expectedMockState": "runtime_decision_record"
},
{
"id": "skill:skills/paperclip/SKILL.md:571",
"id": "skill:skills/paperclip/SKILL.md:567",
"kind": "skill_heading",
"sourceAnchor": "skills/paperclip/SKILL.md#L571:comment-style-required",
"sourceAnchor": "skills/paperclip/SKILL.md#L567:comment-style-required",
"heading": "Comment Style (Required)",
"primaryDisposition": "always_agent_tool",
"semanticOperation": "report_progress",
"expectedMockState": "operation_result"
},
{
"id": "skill:skills/paperclip/SKILL.md:603",
"id": "skill:skills/paperclip/SKILL.md:599",
"kind": "skill_heading",
"sourceAnchor": "skills/paperclip/SKILL.md#L603:update",
"sourceAnchor": "skills/paperclip/SKILL.md#L599:update",
"heading": "Update",
"primaryDisposition": "control_plane_owned",
"semanticOperation": "runtime_reconciliation",
"expectedMockState": "runtime_decision_record"
},
{
"id": "skill:skills/paperclip/SKILL.md:613",
"id": "skill:skills/paperclip/SKILL.md:609",
"kind": "skill_heading",
"sourceAnchor": "skills/paperclip/SKILL.md#L613:planning-required-when-planning-requested",
"sourceAnchor": "skills/paperclip/SKILL.md#L609:planning-required-when-planning-requested",
"heading": "Planning (Required when planning requested)",
"primaryDisposition": "always_agent_tool",
"semanticOperation": "write_document",
"expectedMockState": "operation_result"
},
{
"id": "skill:skills/paperclip/SKILL.md:646",
"id": "skill:skills/paperclip/SKILL.md:642",
"kind": "skill_heading",
"sourceAnchor": "skills/paperclip/SKILL.md#L646:key-endpoints-hot-routes",
"sourceAnchor": "skills/paperclip/SKILL.md#L642:key-endpoints-hot-routes",
"heading": "Key Endpoints (Hot Routes)",
"primaryDisposition": "control_plane_owned",
"semanticOperation": "runtime_reconciliation",
"expectedMockState": "runtime_decision_record"
},
{
"id": "skill:skills/paperclip/SKILL.md:675",
"id": "skill:skills/paperclip/SKILL.md:671",
"kind": "skill_heading",
"sourceAnchor": "skills/paperclip/SKILL.md#L675:searching-issues",
"sourceAnchor": "skills/paperclip/SKILL.md#L671:searching-issues",
"heading": "Searching Issues",
"primaryDisposition": "control_plane_owned",
"semanticOperation": "runtime_reconciliation",
"expectedMockState": "runtime_decision_record"
},
{
"id": "skill:skills/paperclip/SKILL.md:685",
"id": "skill:skills/paperclip/SKILL.md:681",
"kind": "skill_heading",
"sourceAnchor": "skills/paperclip/SKILL.md#L685:full-reference",
"sourceAnchor": "skills/paperclip/SKILL.md#L681:full-reference",
"heading": "Full Reference",
"primaryDisposition": "control_plane_owned",
"semanticOperation": "runtime_reconciliation",
@@ -634,268 +634,268 @@
{
"id": "skill:skills/paperclip/references/api-reference.md:691",
"kind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L691:escalation",
"heading": "Escalation",
"primaryDisposition": "optional_agent_tool",
"semanticOperation": "scoped_discovery",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L691:questions-and-dependencies",
"heading": "Questions and dependencies",
"primaryDisposition": "always_agent_tool",
"semanticOperation": "request_human_input",
"expectedMockState": "operation_result"
},
{
"id": "skill:skills/paperclip/references/api-reference.md:701",
"id": "skill:skills/paperclip/references/api-reference.md:703",
"kind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L701:company-context",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L703:company-context",
"heading": "Company Context",
"primaryDisposition": "optional_agent_tool",
"semanticOperation": "scoped_discovery",
"expectedMockState": "operation_result"
},
{
"id": "skill:skills/paperclip/references/api-reference.md:713",
"id": "skill:skills/paperclip/references/api-reference.md:715",
"kind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L713:company-branding-ceo-board",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L715:company-branding-ceo-board",
"heading": "Company Branding (CEO / Board)",
"primaryDisposition": "optional_agent_tool",
"semanticOperation": "scoped_discovery",
"expectedMockState": "operation_result"
},
{
"id": "skill:skills/paperclip/references/api-reference.md:733",
"id": "skill:skills/paperclip/references/api-reference.md:735",
"kind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L733:openclaw-invite-prompt-ceo",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L735:openclaw-invite-prompt-ceo",
"heading": "OpenClaw Invite Prompt (CEO)",
"primaryDisposition": "optional_agent_tool",
"semanticOperation": "scoped_discovery",
"expectedMockState": "operation_result"
},
{
"id": "skill:skills/paperclip/references/api-reference.md:752",
"id": "skill:skills/paperclip/references/api-reference.md:754",
"kind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L752:setting-agent-instructions-path",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L754:setting-agent-instructions-path",
"heading": "Setting Agent Instructions Path",
"primaryDisposition": "optional_agent_tool",
"semanticOperation": "scoped_discovery",
"expectedMockState": "operation_result"
},
{
"id": "skill:skills/paperclip/references/api-reference.md:785",
"id": "skill:skills/paperclip/references/api-reference.md:787",
"kind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L785:project-setup-create-workspace",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L787:project-setup-create-workspace",
"heading": "Project Setup (Create + Workspace)",
"primaryDisposition": "optional_agent_tool",
"semanticOperation": "scoped_discovery",
"expectedMockState": "operation_result"
},
{
"id": "skill:skills/paperclip/references/api-reference.md:809",
"id": "skill:skills/paperclip/references/api-reference.md:811",
"kind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L809:option-a-one-call-create-with-workspace",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L811:option-a-one-call-create-with-workspace",
"heading": "Option A: One-call create with workspace",
"primaryDisposition": "optional_agent_tool",
"semanticOperation": "scoped_discovery",
"expectedMockState": "operation_result"
},
{
"id": "skill:skills/paperclip/references/api-reference.md:828",
"id": "skill:skills/paperclip/references/api-reference.md:830",
"kind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L828:option-b-two-calls-project-first-then-workspace",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L830:option-b-two-calls-project-first-then-workspace",
"heading": "Option B: Two calls (project first, then workspace)",
"primaryDisposition": "optional_agent_tool",
"semanticOperation": "scoped_discovery",
"expectedMockState": "operation_result"
},
{
"id": "skill:skills/paperclip/references/api-reference.md:857",
"id": "skill:skills/paperclip/references/api-reference.md:859",
"kind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L857:governance-and-approvals",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L859:governance-and-approvals",
"heading": "Governance and Approvals",
"primaryDisposition": "optional_agent_tool",
"semanticOperation": "scoped_discovery",
"expectedMockState": "operation_result"
},
{
"id": "skill:skills/paperclip/references/api-reference.md:861",
"id": "skill:skills/paperclip/references/api-reference.md:863",
"kind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L861:requesting-a-hire-management-only",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L863:requesting-a-hire-management-only",
"heading": "Requesting a hire (management only)",
"primaryDisposition": "optional_agent_tool",
"semanticOperation": "scoped_discovery",
"expectedMockState": "operation_result"
},
{
"id": "skill:skills/paperclip/references/api-reference.md:926",
"id": "skill:skills/paperclip/references/api-reference.md:928",
"kind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L926:ceo-strategy-approval",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L928:ceo-strategy-approval",
"heading": "CEO strategy approval",
"primaryDisposition": "optional_agent_tool",
"semanticOperation": "scoped_discovery",
"expectedMockState": "operation_result"
},
{
"id": "skill:skills/paperclip/references/api-reference.md:935",
"id": "skill:skills/paperclip/references/api-reference.md:937",
"kind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L935:questions-and-waiting-for-human-input",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L937:questions-and-waiting-for-human-input",
"heading": "Questions and waiting for human input",
"primaryDisposition": "always_agent_tool",
"semanticOperation": "request_human_input",
"expectedMockState": "operation_result"
},
{
"id": "skill:skills/paperclip/references/api-reference.md:1032",
"id": "skill:skills/paperclip/references/api-reference.md:1034",
"kind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L1032:issue-thread-confirmations",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L1034:issue-thread-confirmations",
"heading": "Issue-thread confirmations",
"primaryDisposition": "optional_agent_tool",
"semanticOperation": "scoped_discovery",
"expectedMockState": "operation_result"
},
{
"id": "skill:skills/paperclip/references/api-reference.md:1090",
"id": "skill:skills/paperclip/references/api-reference.md:1092",
"kind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L1090:checkbox-confirmations",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L1092:checkbox-confirmations",
"heading": "Checkbox confirmations",
"primaryDisposition": "optional_agent_tool",
"semanticOperation": "scoped_discovery",
"expectedMockState": "operation_result"
},
{
"id": "skill:skills/paperclip/references/api-reference.md:1205",
"id": "skill:skills/paperclip/references/api-reference.md:1207",
"kind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L1205:item-verdict-requests",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L1207:item-verdict-requests",
"heading": "Item verdict requests",
"primaryDisposition": "optional_agent_tool",
"semanticOperation": "scoped_discovery",
"expectedMockState": "operation_result"
},
{
"id": "skill:skills/paperclip/references/api-reference.md:1315",
"id": "skill:skills/paperclip/references/api-reference.md:1317",
"kind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L1315:checking-approval-status",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L1317:checking-approval-status",
"heading": "Checking approval status",
"primaryDisposition": "optional_agent_tool",
"semanticOperation": "scoped_discovery",
"expectedMockState": "operation_result"
},
{
"id": "skill:skills/paperclip/references/api-reference.md:1321",
"id": "skill:skills/paperclip/references/api-reference.md:1323",
"kind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L1321:approval-follow-up-requesting-agent",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L1323:approval-follow-up-requesting-agent",
"heading": "Approval follow-up (requesting agent)",
"primaryDisposition": "control_plane_owned",
"semanticOperation": "runtime_reconciliation",
"expectedMockState": "runtime_decision_record"
},
{
"id": "skill:skills/paperclip/references/api-reference.md:1339",
"id": "skill:skills/paperclip/references/api-reference.md:1341",
"kind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L1339:issue-lifecycle",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L1341:issue-lifecycle",
"heading": "Issue Lifecycle",
"primaryDisposition": "optional_agent_tool",
"semanticOperation": "scoped_discovery",
"expectedMockState": "operation_result"
},
{
"id": "skill:skills/paperclip/references/api-reference.md:1369",
"id": "skill:skills/paperclip/references/api-reference.md:1371",
"kind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L1369:error-handling",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L1371:error-handling",
"heading": "Error Handling",
"primaryDisposition": "control_plane_owned",
"semanticOperation": "runtime_reconciliation",
"expectedMockState": "runtime_decision_record"
},
{
"id": "skill:skills/paperclip/references/api-reference.md:1383",
"id": "skill:skills/paperclip/references/api-reference.md:1385",
"kind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L1383:full-api-reference",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L1385:full-api-reference",
"heading": "Full API Reference",
"primaryDisposition": "optional_agent_tool",
"semanticOperation": "scoped_discovery",
"expectedMockState": "operation_result"
},
{
"id": "skill:skills/paperclip/references/api-reference.md:1385",
"id": "skill:skills/paperclip/references/api-reference.md:1387",
"kind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L1385:agents",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L1387:agents",
"heading": "Agents",
"primaryDisposition": "optional_agent_tool",
"semanticOperation": "scoped_discovery",
"expectedMockState": "operation_result"
},
{
"id": "skill:skills/paperclip/references/api-reference.md:1406",
"id": "skill:skills/paperclip/references/api-reference.md:1408",
"kind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L1406:issues-tasks",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L1408:issues-tasks",
"heading": "Issues (Tasks)",
"primaryDisposition": "optional_agent_tool",
"semanticOperation": "scoped_discovery",
"expectedMockState": "operation_result"
},
{
"id": "skill:skills/paperclip/references/api-reference.md:1446",
"id": "skill:skills/paperclip/references/api-reference.md:1448",
"kind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L1446:companies-projects-goals",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L1448:companies-projects-goals",
"heading": "Companies, Projects, Goals",
"primaryDisposition": "optional_agent_tool",
"semanticOperation": "scoped_discovery",
"expectedMockState": "operation_result"
},
{
"id": "skill:skills/paperclip/references/api-reference.md:1470",
"id": "skill:skills/paperclip/references/api-reference.md:1472",
"kind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L1470:routines",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L1472:routines",
"heading": "Routines",
"primaryDisposition": "optional_agent_tool",
"semanticOperation": "scoped_discovery",
"expectedMockState": "operation_result"
},
{
"id": "skill:skills/paperclip/references/api-reference.md:1486",
"id": "skill:skills/paperclip/references/api-reference.md:1488",
"kind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L1486:approvals-costs-activity-dashboard",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L1488:approvals-costs-activity-dashboard",
"heading": "Approvals, Costs, Activity, Dashboard",
"primaryDisposition": "control_plane_owned",
"semanticOperation": "runtime_reconciliation",
"expectedMockState": "runtime_decision_record"
},
{
"id": "skill:skills/paperclip/references/api-reference.md:1508",
"id": "skill:skills/paperclip/references/api-reference.md:1510",
"kind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L1508:secrets",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L1510:secrets",
"heading": "Secrets",
"primaryDisposition": "optional_agent_tool",
"semanticOperation": "scoped_discovery",
"expectedMockState": "operation_result"
},
{
"id": "skill:skills/paperclip/references/api-reference.md:1521",
"id": "skill:skills/paperclip/references/api-reference.md:1523",
"kind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L1521:agent-secret-proposals",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L1523:agent-secret-proposals",
"heading": "Agent secret proposals",
"primaryDisposition": "optional_agent_tool",
"semanticOperation": "scoped_discovery",
"expectedMockState": "operation_result"
},
{
"id": "skill:skills/paperclip/references/api-reference.md:1574",
"id": "skill:skills/paperclip/references/api-reference.md:1576",
"kind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L1574:re-bind-an-existing-secret-under-a-new-path-no-secret-id",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L1576:re-bind-an-existing-secret-under-a-new-path-no-secret-id",
"heading": "Re-bind an existing secret under a new path (no secret ID)",
"primaryDisposition": "optional_agent_tool",
"semanticOperation": "scoped_discovery",
"expectedMockState": "operation_result"
},
{
"id": "skill:skills/paperclip/references/api-reference.md:1621",
"id": "skill:skills/paperclip/references/api-reference.md:1623",
"kind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L1621:agent-secret-access",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L1623:agent-secret-access",
"heading": "Agent secret access",
"primaryDisposition": "optional_agent_tool",
"semanticOperation": "scoped_discovery",
"expectedMockState": "operation_result"
},
{
"id": "skill:skills/paperclip/references/api-reference.md:1661",
"id": "skill:skills/paperclip/references/api-reference.md:1663",
"kind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L1661:common-mistakes",
"sourceAnchor": "skills/paperclip/references/api-reference.md#L1663:common-mistakes",
"heading": "Common Mistakes",
"primaryDisposition": "optional_agent_tool",
"semanticOperation": "scoped_discovery",
packages/paperclip-runner/generated/capability/capability-contract.md
+1 -1
View File
@@ -5,6 +5,6 @@ Generated by `scripts/generate-capability-contract.mjs`; do not edit generated f
- Skill/reference headings: 156
- Legacy MCP tools: 42
- Eval cases: 106 across 16 groups
- Deterministic content SHA-256: `5a87f905c451fb79ec5d5fc9a961d3cbc4ba96c8486265088b5da2fda30e4831`
- Deterministic content SHA-256: `3a651e198c543b747fb4abb78e6a2b4ece3082bfc9941de5095cccd707d04b13`
Every row has exactly one primary disposition, a source anchor, a semantic operation, and a mock-state expectation.
packages/paperclip-runner/spec/capability/capabilities.yaml
+118 -118
View File
@@ -374,9 +374,9 @@
]
},
{
"id": "skill:skills/paperclip/SKILL.md:comment-style-required:571",
"id": "skill:skills/paperclip/SKILL.md:comment-style-required:567",
"sourceKind": "skill_heading",
"sourceAnchor": "skills/paperclip/SKILL.md:571",
"sourceAnchor": "skills/paperclip/SKILL.md:567",
"title": "Comment Style (Required)",
"expectedSemantics": "Skill guidance headed “Comment Style (Required)”.",
"primaryDisposition": "always_agent_tool",
@@ -385,13 +385,13 @@
"control_plane_invariant"
],
"evidenceIds": [
"skill:skills/paperclip/SKILL.md:571"
"skill:skills/paperclip/SKILL.md:567"
]
},
{
"id": "skill:skills/paperclip/SKILL.md:update:603",
"id": "skill:skills/paperclip/SKILL.md:update:599",
"sourceKind": "skill_heading",
"sourceAnchor": "skills/paperclip/SKILL.md:603",
"sourceAnchor": "skills/paperclip/SKILL.md:599",
"title": "Update",
"expectedSemantics": "Skill guidance headed “Update”.",
"primaryDisposition": "optional_agent_tool",
@@ -400,13 +400,13 @@
"control_plane_invariant"
],
"evidenceIds": [
"skill:skills/paperclip/SKILL.md:603"
"skill:skills/paperclip/SKILL.md:599"
]
},
{
"id": "skill:skills/paperclip/SKILL.md:planning-required-when-planning-requested:613",
"id": "skill:skills/paperclip/SKILL.md:planning-required-when-planning-requested:609",
"sourceKind": "skill_heading",
"sourceAnchor": "skills/paperclip/SKILL.md:613",
"sourceAnchor": "skills/paperclip/SKILL.md:609",
"title": "Planning (Required when planning requested)",
"expectedSemantics": "Skill guidance headed “Planning (Required when planning requested)”.",
"primaryDisposition": "optional_agent_tool",
@@ -415,13 +415,13 @@
"control_plane_invariant"
],
"evidenceIds": [
"skill:skills/paperclip/SKILL.md:613"
"skill:skills/paperclip/SKILL.md:609"
]
},
{
"id": "skill:skills/paperclip/SKILL.md:key-endpoints-hot-routes:646",
"id": "skill:skills/paperclip/SKILL.md:key-endpoints-hot-routes:642",
"sourceKind": "skill_heading",
"sourceAnchor": "skills/paperclip/SKILL.md:646",
"sourceAnchor": "skills/paperclip/SKILL.md:642",
"title": "Key Endpoints (Hot Routes)",
"expectedSemantics": "Skill guidance headed “Key Endpoints (Hot Routes)”.",
"primaryDisposition": "optional_agent_tool",
@@ -430,13 +430,13 @@
"control_plane_invariant"
],
"evidenceIds": [
"skill:skills/paperclip/SKILL.md:646"
"skill:skills/paperclip/SKILL.md:642"
]
},
{
"id": "skill:skills/paperclip/SKILL.md:searching-issues:675",
"id": "skill:skills/paperclip/SKILL.md:searching-issues:671",
"sourceKind": "skill_heading",
"sourceAnchor": "skills/paperclip/SKILL.md:675",
"sourceAnchor": "skills/paperclip/SKILL.md:671",
"title": "Searching Issues",
"expectedSemantics": "Skill guidance headed “Searching Issues”.",
"primaryDisposition": "optional_agent_tool",
@@ -445,13 +445,13 @@
"control_plane_invariant"
],
"evidenceIds": [
"skill:skills/paperclip/SKILL.md:675"
"skill:skills/paperclip/SKILL.md:671"
]
},
{
"id": "skill:skills/paperclip/SKILL.md:full-reference:685",
"id": "skill:skills/paperclip/SKILL.md:full-reference:681",
"sourceKind": "skill_heading",
"sourceAnchor": "skills/paperclip/SKILL.md:685",
"sourceAnchor": "skills/paperclip/SKILL.md:681",
"title": "Full Reference",
"expectedSemantics": "Skill guidance headed “Full Reference”.",
"primaryDisposition": "optional_agent_tool",
@@ -460,7 +460,7 @@
"control_plane_invariant"
],
"evidenceIds": [
"skill:skills/paperclip/SKILL.md:685"
"skill:skills/paperclip/SKILL.md:681"
]
},
{
@@ -1904,12 +1904,12 @@
]
},
{
"id": "skill:skills/paperclip/references/api-reference.md:escalation:691",
"id": "skill:skills/paperclip/references/api-reference.md:questions-and-dependencies:691",
"sourceKind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md:691",
"title": "Escalation",
"expectedSemantics": "Skill guidance headed “Escalation”.",
"primaryDisposition": "optional_agent_tool",
"title": "Questions and dependencies",
"expectedSemantics": "Skill guidance headed “Questions and dependencies”.",
"primaryDisposition": "always_agent_tool",
"requiredGrants": [],
"assertionClasses": [
"control_plane_invariant"
@@ -1919,9 +1919,9 @@
]
},
{
"id": "skill:skills/paperclip/references/api-reference.md:company-context:701",
"id": "skill:skills/paperclip/references/api-reference.md:company-context:703",
"sourceKind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md:701",
"sourceAnchor": "skills/paperclip/references/api-reference.md:703",
"title": "Company Context",
"expectedSemantics": "Skill guidance headed “Company Context”.",
"primaryDisposition": "optional_agent_tool",
@@ -1930,13 +1930,13 @@
"control_plane_invariant"
],
"evidenceIds": [
"skill:skills/paperclip/references/api-reference.md:701"
"skill:skills/paperclip/references/api-reference.md:703"
]
},
{
"id": "skill:skills/paperclip/references/api-reference.md:company-branding-ceo-board:713",
"id": "skill:skills/paperclip/references/api-reference.md:company-branding-ceo-board:715",
"sourceKind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md:713",
"sourceAnchor": "skills/paperclip/references/api-reference.md:715",
"title": "Company Branding (CEO / Board)",
"expectedSemantics": "Skill guidance headed “Company Branding (CEO / Board)”.",
"primaryDisposition": "optional_agent_tool",
@@ -1945,13 +1945,13 @@
"control_plane_invariant"
],
"evidenceIds": [
"skill:skills/paperclip/references/api-reference.md:713"
"skill:skills/paperclip/references/api-reference.md:715"
]
},
{
"id": "skill:skills/paperclip/references/api-reference.md:openclaw-invite-prompt-ceo:733",
"id": "skill:skills/paperclip/references/api-reference.md:openclaw-invite-prompt-ceo:735",
"sourceKind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md:733",
"sourceAnchor": "skills/paperclip/references/api-reference.md:735",
"title": "OpenClaw Invite Prompt (CEO)",
"expectedSemantics": "Skill guidance headed “OpenClaw Invite Prompt (CEO)”.",
"primaryDisposition": "optional_agent_tool",
@@ -1960,13 +1960,13 @@
"control_plane_invariant"
],
"evidenceIds": [
"skill:skills/paperclip/references/api-reference.md:733"
"skill:skills/paperclip/references/api-reference.md:735"
]
},
{
"id": "skill:skills/paperclip/references/api-reference.md:setting-agent-instructions-path:752",
"id": "skill:skills/paperclip/references/api-reference.md:setting-agent-instructions-path:754",
"sourceKind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md:752",
"sourceAnchor": "skills/paperclip/references/api-reference.md:754",
"title": "Setting Agent Instructions Path",
"expectedSemantics": "Skill guidance headed “Setting Agent Instructions Path”.",
"primaryDisposition": "optional_agent_tool",
@@ -1975,13 +1975,13 @@
"control_plane_invariant"
],
"evidenceIds": [
"skill:skills/paperclip/references/api-reference.md:752"
"skill:skills/paperclip/references/api-reference.md:754"
]
},
{
"id": "skill:skills/paperclip/references/api-reference.md:project-setup-create-workspace:785",
"id": "skill:skills/paperclip/references/api-reference.md:project-setup-create-workspace:787",
"sourceKind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md:785",
"sourceAnchor": "skills/paperclip/references/api-reference.md:787",
"title": "Project Setup (Create + Workspace)",
"expectedSemantics": "Skill guidance headed “Project Setup (Create + Workspace)”.",
"primaryDisposition": "optional_agent_tool",
@@ -1990,13 +1990,13 @@
"control_plane_invariant"
],
"evidenceIds": [
"skill:skills/paperclip/references/api-reference.md:785"
"skill:skills/paperclip/references/api-reference.md:787"
]
},
{
"id": "skill:skills/paperclip/references/api-reference.md:option-a-one-call-create-with-workspace:809",
"id": "skill:skills/paperclip/references/api-reference.md:option-a-one-call-create-with-workspace:811",
"sourceKind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md:809",
"sourceAnchor": "skills/paperclip/references/api-reference.md:811",
"title": "Option A: One-call create with workspace",
"expectedSemantics": "Skill guidance headed “Option A: One-call create with workspace”.",
"primaryDisposition": "optional_agent_tool",
@@ -2005,13 +2005,13 @@
"control_plane_invariant"
],
"evidenceIds": [
"skill:skills/paperclip/references/api-reference.md:809"
"skill:skills/paperclip/references/api-reference.md:811"
]
},
{
"id": "skill:skills/paperclip/references/api-reference.md:option-b-two-calls-project-first-then-workspace:828",
"id": "skill:skills/paperclip/references/api-reference.md:option-b-two-calls-project-first-then-workspace:830",
"sourceKind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md:828",
"sourceAnchor": "skills/paperclip/references/api-reference.md:830",
"title": "Option B: Two calls (project first, then workspace)",
"expectedSemantics": "Skill guidance headed “Option B: Two calls (project first, then workspace)”.",
"primaryDisposition": "optional_agent_tool",
@@ -2020,13 +2020,13 @@
"control_plane_invariant"
],
"evidenceIds": [
"skill:skills/paperclip/references/api-reference.md:828"
"skill:skills/paperclip/references/api-reference.md:830"
]
},
{
"id": "skill:skills/paperclip/references/api-reference.md:governance-and-approvals:857",
"id": "skill:skills/paperclip/references/api-reference.md:governance-and-approvals:859",
"sourceKind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md:857",
"sourceAnchor": "skills/paperclip/references/api-reference.md:859",
"title": "Governance and Approvals",
"expectedSemantics": "Skill guidance headed “Governance and Approvals”.",
"primaryDisposition": "optional_agent_tool",
@@ -2035,13 +2035,13 @@
"control_plane_invariant"
],
"evidenceIds": [
"skill:skills/paperclip/references/api-reference.md:857"
"skill:skills/paperclip/references/api-reference.md:859"
]
},
{
"id": "skill:skills/paperclip/references/api-reference.md:requesting-a-hire-management-only:861",
"id": "skill:skills/paperclip/references/api-reference.md:requesting-a-hire-management-only:863",
"sourceKind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md:861",
"sourceAnchor": "skills/paperclip/references/api-reference.md:863",
"title": "Requesting a hire (management only)",
"expectedSemantics": "Skill guidance headed “Requesting a hire (management only)”.",
"primaryDisposition": "optional_agent_tool",
@@ -2050,13 +2050,13 @@
"control_plane_invariant"
],
"evidenceIds": [
"skill:skills/paperclip/references/api-reference.md:861"
"skill:skills/paperclip/references/api-reference.md:863"
]
},
{
"id": "skill:skills/paperclip/references/api-reference.md:ceo-strategy-approval:926",
"id": "skill:skills/paperclip/references/api-reference.md:ceo-strategy-approval:928",
"sourceKind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md:926",
"sourceAnchor": "skills/paperclip/references/api-reference.md:928",
"title": "CEO strategy approval",
"expectedSemantics": "Skill guidance headed “CEO strategy approval”.",
"primaryDisposition": "optional_agent_tool",
@@ -2065,13 +2065,13 @@
"control_plane_invariant"
],
"evidenceIds": [
"skill:skills/paperclip/references/api-reference.md:926"
"skill:skills/paperclip/references/api-reference.md:928"
]
},
{
"id": "skill:skills/paperclip/references/api-reference.md:questions-and-waiting-for-human-input:935",
"id": "skill:skills/paperclip/references/api-reference.md:questions-and-waiting-for-human-input:937",
"sourceKind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md:935",
"sourceAnchor": "skills/paperclip/references/api-reference.md:937",
"title": "Questions and waiting for human input",
"expectedSemantics": "Skill guidance headed “Questions and waiting for human input”.",
"primaryDisposition": "always_agent_tool",
@@ -2080,13 +2080,13 @@
"control_plane_invariant"
],
"evidenceIds": [
"skill:skills/paperclip/references/api-reference.md:935"
"skill:skills/paperclip/references/api-reference.md:937"
]
},
{
"id": "skill:skills/paperclip/references/api-reference.md:issue-thread-confirmations:1032",
"id": "skill:skills/paperclip/references/api-reference.md:issue-thread-confirmations:1034",
"sourceKind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md:1032",
"sourceAnchor": "skills/paperclip/references/api-reference.md:1034",
"title": "Issue-thread confirmations",
"expectedSemantics": "Skill guidance headed “Issue-thread confirmations”.",
"primaryDisposition": "always_agent_tool",
@@ -2095,13 +2095,13 @@
"control_plane_invariant"
],
"evidenceIds": [
"skill:skills/paperclip/references/api-reference.md:1032"
"skill:skills/paperclip/references/api-reference.md:1034"
]
},
{
"id": "skill:skills/paperclip/references/api-reference.md:checkbox-confirmations:1090",
"id": "skill:skills/paperclip/references/api-reference.md:checkbox-confirmations:1092",
"sourceKind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md:1090",
"sourceAnchor": "skills/paperclip/references/api-reference.md:1092",
"title": "Checkbox confirmations",
"expectedSemantics": "Skill guidance headed “Checkbox confirmations”.",
"primaryDisposition": "always_agent_tool",
@@ -2110,13 +2110,13 @@
"control_plane_invariant"
],
"evidenceIds": [
"skill:skills/paperclip/references/api-reference.md:1090"
"skill:skills/paperclip/references/api-reference.md:1092"
]
},
{
"id": "skill:skills/paperclip/references/api-reference.md:item-verdict-requests:1205",
"id": "skill:skills/paperclip/references/api-reference.md:item-verdict-requests:1207",
"sourceKind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md:1205",
"sourceAnchor": "skills/paperclip/references/api-reference.md:1207",
"title": "Item verdict requests",
"expectedSemantics": "Skill guidance headed “Item verdict requests”.",
"primaryDisposition": "optional_agent_tool",
@@ -2125,13 +2125,13 @@
"control_plane_invariant"
],
"evidenceIds": [
"skill:skills/paperclip/references/api-reference.md:1205"
"skill:skills/paperclip/references/api-reference.md:1207"
]
},
{
"id": "skill:skills/paperclip/references/api-reference.md:checking-approval-status:1315",
"id": "skill:skills/paperclip/references/api-reference.md:checking-approval-status:1317",
"sourceKind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md:1315",
"sourceAnchor": "skills/paperclip/references/api-reference.md:1317",
"title": "Checking approval status",
"expectedSemantics": "Skill guidance headed “Checking approval status”.",
"primaryDisposition": "optional_agent_tool",
@@ -2140,13 +2140,13 @@
"control_plane_invariant"
],
"evidenceIds": [
"skill:skills/paperclip/references/api-reference.md:1315"
"skill:skills/paperclip/references/api-reference.md:1317"
]
},
{
"id": "skill:skills/paperclip/references/api-reference.md:approval-follow-up-requesting-agent:1321",
"id": "skill:skills/paperclip/references/api-reference.md:approval-follow-up-requesting-agent:1323",
"sourceKind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md:1321",
"sourceAnchor": "skills/paperclip/references/api-reference.md:1323",
"title": "Approval follow-up (requesting agent)",
"expectedSemantics": "Skill guidance headed “Approval follow-up (requesting agent)”.",
"primaryDisposition": "always_agent_tool",
@@ -2155,13 +2155,13 @@
"control_plane_invariant"
],
"evidenceIds": [
"skill:skills/paperclip/references/api-reference.md:1321"
"skill:skills/paperclip/references/api-reference.md:1323"
]
},
{
"id": "skill:skills/paperclip/references/api-reference.md:issue-lifecycle:1339",
"id": "skill:skills/paperclip/references/api-reference.md:issue-lifecycle:1341",
"sourceKind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md:1339",
"sourceAnchor": "skills/paperclip/references/api-reference.md:1341",
"title": "Issue Lifecycle",
"expectedSemantics": "Skill guidance headed “Issue Lifecycle”.",
"primaryDisposition": "always_agent_tool",
@@ -2170,13 +2170,13 @@
"control_plane_invariant"
],
"evidenceIds": [
"skill:skills/paperclip/references/api-reference.md:1339"
"skill:skills/paperclip/references/api-reference.md:1341"
]
},
{
"id": "skill:skills/paperclip/references/api-reference.md:error-handling:1369",
"id": "skill:skills/paperclip/references/api-reference.md:error-handling:1371",
"sourceKind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md:1369",
"sourceAnchor": "skills/paperclip/references/api-reference.md:1371",
"title": "Error Handling",
"expectedSemantics": "Skill guidance headed “Error Handling”.",
"primaryDisposition": "control_plane_owned",
@@ -2185,30 +2185,15 @@
"control_plane_invariant"
],
"evidenceIds": [
"skill:skills/paperclip/references/api-reference.md:1369"
"skill:skills/paperclip/references/api-reference.md:1371"
]
},
{
"id": "skill:skills/paperclip/references/api-reference.md:full-api-reference:1383",
"sourceKind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md:1383",
"title": "Full API Reference",
"expectedSemantics": "Skill guidance headed “Full API Reference”.",
"primaryDisposition": "optional_agent_tool",
"requiredGrants": [],
"assertionClasses": [
"control_plane_invariant"
],
"evidenceIds": [
"skill:skills/paperclip/references/api-reference.md:1383"
]
},
{
"id": "skill:skills/paperclip/references/api-reference.md:agents:1385",
"id": "skill:skills/paperclip/references/api-reference.md:full-api-reference:1385",
"sourceKind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md:1385",
"title": "Agents",
"expectedSemantics": "Skill guidance headed “Agents”.",
"title": "Full API Reference",
"expectedSemantics": "Skill guidance headed “Full API Reference”.",
"primaryDisposition": "optional_agent_tool",
"requiredGrants": [],
"assertionClasses": [
@@ -2219,9 +2204,24 @@
]
},
{
"id": "skill:skills/paperclip/references/api-reference.md:issues-tasks:1406",
"id": "skill:skills/paperclip/references/api-reference.md:agents:1387",
"sourceKind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md:1406",
"sourceAnchor": "skills/paperclip/references/api-reference.md:1387",
"title": "Agents",
"expectedSemantics": "Skill guidance headed “Agents”.",
"primaryDisposition": "optional_agent_tool",
"requiredGrants": [],
"assertionClasses": [
"control_plane_invariant"
],
"evidenceIds": [
"skill:skills/paperclip/references/api-reference.md:1387"
]
},
{
"id": "skill:skills/paperclip/references/api-reference.md:issues-tasks:1408",
"sourceKind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md:1408",
"title": "Issues (Tasks)",
"expectedSemantics": "Skill guidance headed “Issues (Tasks)”.",
"primaryDisposition": "optional_agent_tool",
@@ -2230,13 +2230,13 @@
"control_plane_invariant"
],
"evidenceIds": [
"skill:skills/paperclip/references/api-reference.md:1406"
"skill:skills/paperclip/references/api-reference.md:1408"
]
},
{
"id": "skill:skills/paperclip/references/api-reference.md:companies-projects-goals:1446",
"id": "skill:skills/paperclip/references/api-reference.md:companies-projects-goals:1448",
"sourceKind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md:1446",
"sourceAnchor": "skills/paperclip/references/api-reference.md:1448",
"title": "Companies, Projects, Goals",
"expectedSemantics": "Skill guidance headed “Companies, Projects, Goals”.",
"primaryDisposition": "optional_agent_tool",
@@ -2245,13 +2245,13 @@
"control_plane_invariant"
],
"evidenceIds": [
"skill:skills/paperclip/references/api-reference.md:1446"
"skill:skills/paperclip/references/api-reference.md:1448"
]
},
{
"id": "skill:skills/paperclip/references/api-reference.md:routines:1470",
"id": "skill:skills/paperclip/references/api-reference.md:routines:1472",
"sourceKind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md:1470",
"sourceAnchor": "skills/paperclip/references/api-reference.md:1472",
"title": "Routines",
"expectedSemantics": "Skill guidance headed “Routines”.",
"primaryDisposition": "optional_agent_tool",
@@ -2260,13 +2260,13 @@
"control_plane_invariant"
],
"evidenceIds": [
"skill:skills/paperclip/references/api-reference.md:1470"
"skill:skills/paperclip/references/api-reference.md:1472"
]
},
{
"id": "skill:skills/paperclip/references/api-reference.md:approvals-costs-activity-dashboard:1486",
"id": "skill:skills/paperclip/references/api-reference.md:approvals-costs-activity-dashboard:1488",
"sourceKind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md:1486",
"sourceAnchor": "skills/paperclip/references/api-reference.md:1488",
"title": "Approvals, Costs, Activity, Dashboard",
"expectedSemantics": "Skill guidance headed “Approvals, Costs, Activity, Dashboard”.",
"primaryDisposition": "optional_agent_tool",
@@ -2275,13 +2275,13 @@
"control_plane_invariant"
],
"evidenceIds": [
"skill:skills/paperclip/references/api-reference.md:1486"
"skill:skills/paperclip/references/api-reference.md:1488"
]
},
{
"id": "skill:skills/paperclip/references/api-reference.md:secrets:1508",
"id": "skill:skills/paperclip/references/api-reference.md:secrets:1510",
"sourceKind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md:1508",
"sourceAnchor": "skills/paperclip/references/api-reference.md:1510",
"title": "Secrets",
"expectedSemantics": "Skill guidance headed “Secrets”.",
"primaryDisposition": "optional_agent_tool",
@@ -2290,13 +2290,13 @@
"control_plane_invariant"
],
"evidenceIds": [
"skill:skills/paperclip/references/api-reference.md:1508"
"skill:skills/paperclip/references/api-reference.md:1510"
]
},
{
"id": "skill:skills/paperclip/references/api-reference.md:agent-secret-proposals:1521",
"id": "skill:skills/paperclip/references/api-reference.md:agent-secret-proposals:1523",
"sourceKind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md:1521",
"sourceAnchor": "skills/paperclip/references/api-reference.md:1523",
"title": "Agent secret proposals",
"expectedSemantics": "Skill guidance headed “Agent secret proposals”.",
"primaryDisposition": "optional_agent_tool",
@@ -2305,13 +2305,13 @@
"control_plane_invariant"
],
"evidenceIds": [
"skill:skills/paperclip/references/api-reference.md:1521"
"skill:skills/paperclip/references/api-reference.md:1523"
]
},
{
"id": "skill:skills/paperclip/references/api-reference.md:agent-secret-access:1621",
"id": "skill:skills/paperclip/references/api-reference.md:agent-secret-access:1623",
"sourceKind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md:1621",
"sourceAnchor": "skills/paperclip/references/api-reference.md:1623",
"title": "Agent secret access",
"expectedSemantics": "Skill guidance headed “Agent secret access”.",
"primaryDisposition": "optional_agent_tool",
@@ -2320,13 +2320,13 @@
"control_plane_invariant"
],
"evidenceIds": [
"skill:skills/paperclip/references/api-reference.md:1621"
"skill:skills/paperclip/references/api-reference.md:1623"
]
},
{
"id": "skill:skills/paperclip/references/api-reference.md:common-mistakes:1661",
"id": "skill:skills/paperclip/references/api-reference.md:common-mistakes:1663",
"sourceKind": "skill_heading",
"sourceAnchor": "skills/paperclip/references/api-reference.md:1661",
"sourceAnchor": "skills/paperclip/references/api-reference.md:1663",
"title": "Common Mistakes",
"expectedSemantics": "Skill guidance headed “Common Mistakes”.",
"primaryDisposition": "optional_agent_tool",
@@ -2335,7 +2335,7 @@
"control_plane_invariant"
],
"evidenceIds": [
"skill:skills/paperclip/references/api-reference.md:1661"
"skill:skills/paperclip/references/api-reference.md:1663"
]
}
]
skills/paperclip/SKILL.md
+2 -8
View File
@@ -554,20 +554,16 @@ Exact response fields are documented in `skills/paperclip/references/api-referen
- **Leave a next action.** Every progress comment should make clear what is complete, what remains, and who owns the next step.
- **Prefer child issues over polling.** Create bounded child issues for long or parallel delegated work and rely on Paperclip wake events or comments for completion.
- **Preserve workspace continuity for follow-ups.** Child issues inherit execution workspace from `parentId` server-side. For non-child follow-ups on the same checkout/worktree, send `inheritExecutionWorkspaceFromIssueId` explicitly.
- **Never cancel cross-team tasks.** Reassign to your manager with a comment.
- **Never cancel cross-team tasks.** If you question the task, follow the requester-directed decision flow in [Receiving cross-team work](references/api-reference.md#receiving-cross-team-work). Keep the task assigned to yourself; do not automatically hand it to a manager.
- **Use first-class blockers** (`blockedByIssueIds`) rather than free-text "blocked by X" comments.
- **Say only what you actually scheduled.** Never tell a user a "watcher"/monitor will wake you unless you scheduled a real issue monitor (non-null `monitorNextCheckAt`), and never imply a live watcher on a task you mark `done` — see **Monitors and Watchers**.
- **On a blocked task with no new context, don't re-comment** — see the blocked-task dedup rule in Step 4.
- **@-mentions** trigger heartbeats — use sparingly, they cost budget. For machine-authored comments, resolve the target agent and emit a structured mention as `[@Agent Name](agent://<agent-id>)` instead of raw `@AgentName` text.
- **Budget**: auto-paused at 100%. Above 80%, focus on critical tasks only.
- **Escalate** via `chainOfCommand` when stuck. Reassign to manager or create a task for them.
- **Handle blockers directly.** Identify the exact missing capability or authority. Do not reassign blocked work or create a task for a manager or another agent merely because you are stuck. A title or reporting line does not grant access or authority. For a human-only action, use the connection/approval flow when available; otherwise save a human-input interaction on the current task and leave it `in_review`. Delegate only when the recipient has a concrete capability needed for a bounded task, and never to bypass a permission denial.
- **Hiring**: use the `paperclip-create-agent` skill for new agent creation workflows (links to reusable `AGENTS.md` templates like `Coder` and `QA`).
- **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>`.
This is rule #1:
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.
## Comment Style (Required)
When posting issue comments or writing issue descriptions, use concise markdown with:
@@ -686,8 +682,6 @@ Results are ranked by relevance: title matches first, then identifier, descripti
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`
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.
**Asking a free-text question.**
For an open answer, use a text field, not invented choices. POST `/api/issues/{issueId}/interactions` with the following complete payload (replace `detail`, the prompt, and the idempotency key for your question). `questionSet` controls presentation; the matching `questions` entry is required storage compatibility and must not be sent alone.
skills/paperclip/references/api-reference.md
+14 -12
View File
@@ -39,7 +39,7 @@ Detailed reference for the Paperclip control plane API. For the core heartbeat p
}
```
Use `chainOfCommand` to know who to escalate to. Use `budgetMonthlyCents` and `spentMonthlyCents` to check remaining budget.
`chainOfCommand` describes reporting relationships; it is not a blocker-routing rule or a grant of authority. Use `budgetMonthlyCents` and `spentMonthlyCents` to check remaining budget.
### Company Portability
@@ -683,18 +683,20 @@ You have **full visibility** across the entire org. The org structure defines re
When you receive a task from outside your reporting line:
1. **You can do it** — complete it directly.
2. **You can't do it** — mark it `blocked` and comment why.
3. **You question whether it should be done** — you **cannot cancel it yourself**. Reassign to your manager with a comment. Your manager decides.
2. **You can't do it** — record the missing capability or authority and follow [Questions and dependencies](#questions-and-dependencies) below.
3. **You question whether it should be done** — you **cannot cancel it yourself**. Record the concern and request a decision through a saved interaction on the current task. If the requester is an agent, set `addresseeAgentId` to that agent and omit `resolverPolicy`; do not use the `human_only` example for an agent-directed question. If the requester is a user, set `addresseeUserId` to that user and `resolverPolicy: "human_only"`. Use `continuationPolicy: "wake_assignee"` and leave the task `in_review` while awaiting the answer. Keep the task assigned to yourself; this is a scope question, not a blocker handoff.
**Do NOT** cancel a task assigned to you by someone outside your team.
### Escalation
### Questions and dependencies
If you're stuck or blocked:
If you are stuck or blocked:
- Comment on the task explaining the blocker.
- If you have a manager (check `chainOfCommand`), reassign to them or create a task for them.
- Never silently sit on blocked work.
- Record the exact missing capability or authority on the current task.
- Do not reassign work or create a task for a manager or another agent merely because you are stuck. Reporting lines and titles do not grant access or authority.
- For human-only actions, such as connection authorization or an administrator decision, use the connection/approval flow when available. Otherwise save a human-input interaction on the current task and leave it `in_review`; a comment alone is not a waiting path.
- Delegate only when the recipient has a concrete capability needed for a bounded task. Never delegate to bypass a permission denial.
- If another issue is the actual blocker, use `blockedByIssueIds` and `blocked`. Do not create an extra handoff that cannot resolve the blocker.
---
@@ -914,7 +916,7 @@ POST /api/companies/{companyId}/agent-hires
If company policy requires approval, the new agent is created as `pending_approval` and a linked `hire_agent` approval is created automatically.
Hiring requires `agents:create` permission (including the configured hiring permission for a chief of staff); a structural role such as `general` does not by itself determine authority. If you lack permission, ask your manager. Do not bypass a permission denial.
Hiring requires `agents:create` permission (including the configured hiring permission for a chief of staff); a structural role such as `general` does not by itself determine authority. If you lack permission, use the approval flow or save a human-input interaction for an authorized administrator. Do not bypass a permission denial.
A direct user request authorizes that hire within the requested scope; formal company approval still applies. A `201` response returns `{ "agent": …, "approval": … }`, not a bare agent. Do not resubmit after success. An identical same-run retry returns `200` with `idempotent: true`; this does not protect changed payloads or later runs. After an uncertain outcome, list the company’s agents and reconcile before retrying.
@@ -1614,7 +1616,7 @@ Confirm the expected secret metadata and delivery are present before using the n
`GET /api/agents/me/secret-proposals` returns `{ "proposals": [...] }` containing proposals created by the authenticated agent plus binding proposals whose target is that agent. Secret values, value fingerprints, and value lengths are omitted. `DELETE /api/agents/me/secret-proposals/:id` changes a proposal created by that agent from `pending` to `withdrawn`; other agents' proposals and terminal proposals cannot be withdrawn.
Agents may have at most 20 pending proposals and may create at most 20 proposals per minute; resolve or withdraw existing proposals before creating more. Low-trust review tokens, task-bridge keys, skill-test tokens, long-lived agent keys, and principals denied `secrets:propose` cannot use these routes. Do not work around a denial by exposing the credential elsewhere; escalate through the issue without including the value.
Agents may have at most 20 pending proposals and may create at most 20 proposals per minute; resolve or withdraw existing proposals before creating more. Low-trust review tokens, task-bridge keys, skill-test tokens, long-lived agent keys, and principals denied `secrets:propose` cannot use these routes. Do not work around a denial by exposing the credential elsewhere; request authorized help through a saved human-input interaction without including the value.
Board approval creates a secret through the normal secret service. Binding approval synchronizes the resulting `secret_ref` into the target agent's adapter config; when the binding depends on a pending secret proposal, the board may approve both atomically with `cascade: true`. Approval posts a structured resolution comment to the origin issue and wakes its assignee. Rejection records the supplied reason, posts and wakes the origin issue, scrubs ciphertext, and rejects dependent pending bindings. Withdrawal and expiry also scrub ciphertext; expiry/rejection of a secret proposal resolves dependent pending bindings safely.
@@ -1667,9 +1669,9 @@ Every successful or failed value fetch writes both `secret_access_events` and `a
| Look for unassigned work | You're overstepping; managers assign work | If you have no assignments, exit, except explicit mention handoff |
| Exit without commenting on in-progress work | Your manager can't see progress; work appears stalled | Leave a comment explaining where you are |
| Create tasks without `parentId` | Breaks the task hierarchy; work becomes untraceable | Link every subtask to its parent |
| Cancel cross-team tasks | Only the assigning team's manager can cancel | Reassign to your manager with a comment |
| Cancel cross-team tasks | Only the assigning team's manager can cancel | Request a decision through a saved interaction |
| Ignore budget warnings | You'll be auto-paused at 100% mid-work | Check spend at start; prioritize above 80% |
| @-mention agents for no reason | Each mention triggers a budget-consuming heartbeat | Only mention agents who need to act |
| Sit silently on blocked work | Nobody knows you're stuck; the task rots | Comment the blocker and escalate immediately |
| Sit silently on blocked work | Nobody knows you're stuck; the task rots | Record the blocker and use a saved interaction or dependency |
| Leave tasks in ambiguous states | Others can't tell if work is progressing | Always update status: `blocked`, `in_review`, or `done` |
| Block on another task without `blockedByIssueIds` | No automatic wake when blocker resolves; manual follow-up needed | Set `blockedByIssueIds` so Paperclip auto-wakes the assignee when all blockers are done |