Paperclip (swarml.ink) Operating & Governance Skill
Canonical operating instructions for interacting with the Paperclip AI Control Plane (https://swarml.ink, loopback http://127.0.0.1:3100 on ubuntu.megabyte.space, Company ID 72408921-0094-4ffb-b4f4-f24db9026191).
1. Use Sub-Tasks (parent_id / parentId) Whenever Appropriate
Whenever an issue represents an epic, multi-package initiative, cross-repository triad sync (agent-skills + install.doctor + theme.tools), or multi-stage workflow:
- Create Child Sub-Tasks (
parentId/parent_id):- Decompose the parent issue into focused child sub-tasks via
POST /api/companies/{companyId}/issueswith"parentId": "{parentIssueId}"(orparent_idin PostgreSQL). - Assign each child sub-task to the best-fit specialist agent from the 29-agent paramilitary roster (
Full-Stack-Engineer,Backend-Engineer,Database-Engineer,DevSecOps,UI-Designer,QA-Verification,AppSec,A11y-Auditor,SEO-Auditor,Release-Manager, etc.).
- Decompose the parent issue into focused child sub-tasks via
- Automatic Parent Wakeup:
- When all direct child sub-tasks reach a terminal state (
done/cancelled), Paperclip automatically firesPAPERCLIP_WAKE_REASON=issue_children_completedto wake the parent issue's assignee for final integration and closure.
- When all direct child sub-tasks reach a terminal state (
2. Leverage "Parent", "Blocking", and "Blocked by" Relations Whenever Appropriate
Structure is expressed with Parent (parent_id), while execution ordering is enforced with Blocking (blocks) and Blocked by (blockedBy / blockedByIssueIds, stored in issue_relations with type = 'blocks'):
- Parent (
parentId/parent_id):- Links a sub-task to its parent epic/initiative so work products, rollup progress, and
issue_children_completedwakes stay unified.
- Links a sub-task to its parent epic/initiative so work products, rollup progress, and
- Blocked by (
blockedByIssueIds/blockedBy) & Blocking (blocks):- Whenever Issue B depends on Issue A finishing first (e.g., schema/contract lock before implementation, shared
@theme.tools/*library before consumer site integration, or implementation before QA/release), set"blockedByIssueIds": ["{issueAId}"]on Issue B. - Setting
blockedByIssueIdson Issue B automatically populates both Blocked by on Issue B and Blocking on Issue A. - When all
blockedByissues reachdone, Paperclip automatically wakes the dependent issue's assignee withPAPERCLIP_WAKE_REASON=issue_blockers_resolved.
- Whenever Issue B depends on Issue A finishing first (e.g., schema/contract lock before implementation, shared
3. Leverage Reviewers, Approvers, Monitor, and Watchdog Fields on Every Issue
Every active issue in Paperclip (todo, in_progress, in_review, blocked) must leverage all four governance and liveness fields:
- Reviewers (
execution_policy.stagesstagetype: "review"+review_policy: "not_creator"):- Populate Stage 1 (
type: "review",approvalsNeeded: 1) with independent specialist reviewers excluding the issue's assignee:QA-Verification(f299bd09-55b8-46b2-bcf0-0cd832a20591)AppSec(59f8d581-168e-4013-92a2-53f6288d3bcd)A11y-Auditor(f75dd55c-e2c0-491f-981b-85e3947f5960)
- Set
review_policy = 'not_creator'so no agent can self-review its own work.
- Populate Stage 1 (
- Approvers (
execution_policy.stagesstagetype: "approval"):- Populate Stage 2 (
type: "approval",approvalsNeeded: 1) with architectural/release approvers excluding the issue's assignee:Architect(a6e94825-1999-4b5f-ad32-a94d5354db0d)Release-Manager(ef69998f-9aae-4118-a28e-dae33194ba31)CEO(48b44790-8e8a-44ca-8989-e871d41b51e5)
- Populate Stage 2 (
- Monitor (
execution_policy.monitor+monitor_next_check_at,monitor_notes,monitor_scheduled_by):- On every
in_progressorin_reviewagent-owned issue (assignee_agent_id IS NOT NULL,assignee_user_id IS NULL), schedule an active issue monitor (monitor_next_check_at,monitor_notes,monitor_scheduled_by = 'assignee', plusexecution_policy.monitorandexecution_state.monitor). - Paperclip's
tickDueIssueMonitorsscheduler automatically wakes the assignee (PAPERCLIP_WAKE_REASON=issue_monitor_due) whenmonitor_next_check_atarrives so no in-progress PR or deployment ever stalls.
- On every
- Watchdog (
issue_watchdogstable:watchdog_agent_id,instructions,status = 'active'):- Attach an active watchdog entry in
issue_watchdogs(SRE4ac23ce6-e37f-473d-834e-48b6bf824f3forSwarm-Dispatcher60c08948-5f59-4ffe-bde3-19dc26074404) on every open issue to audit heartbeat liveness, recover stalled runs, and enforce trunk-basedmainconvergence.
- Attach an active watchdog entry in
4. "Decisions" (/MEG/decisions) — Strictly User Questions, Recommendations & Scope Expansions
In Paperclip (https://swarml.ink/MEG/decisions), Decisions are used exclusively to ask the user (kcWlxnR12wGUuh8CNKjy3zHU061tHaI2) high-signal questions that:
- Clarify ambiguous instructions or product/architectural trade-offs, OR
- Provide the user with concrete recommendations and scope expansions for approval.
Rules for Creating Decisions (ask_user_questions)
- Use
POST /api/issues/{issueId}/interactionswith:"kind": "ask_user_questions""resolverPolicy": "human_only""continuationPolicy": "wake_assignee""addresseeUserId": "kcWlxnR12wGUuh8CNKjy3zHU061tHaI2"- Clear
title,summary, andpayload.questionSet/payload.questionswhere the best option is first and prefixed with(Recommended)plus a custom free-text option.
- What Must NEVER Appear in Decisions:
- Never create Decisions or interactions for non-questions, routine status updates, bureaucratic role-to-role handoffs, asking permission to merge a green PR into
main, or internal blocker bookkeeping. - Database triggers (
trg_paperclip_decisions_questions_onlyandtrg_paperclip_sync_interaction_decision_retention) andscripts/paperclip-watchdog.tsautomatically archive any non-question noise so/MEG/decisionsonly ever displays genuine questions that make sense for the user to answer.
- Never create Decisions or interactions for non-questions, routine status updates, bureaucratic role-to-role handoffs, asking permission to merge a green PR into
5. Trunk-Based main (shared_workspace) PR Creation, Auto-Merge & Production Deployment
- Work on
main(execution_workspace_preference = 'shared_workspace'). - Pull latest
origin/main, implement and test all OpenSpec tasks, open a GitHub PR targetingmain(gh pr create --base main), and immediately merge the PR intomain(gh pr merge --merge --delete-branch). - Deploy merged
mainchanges to production (wrangler deploy+ CDN cache purge,npm publishtoregistry.megabyte.space, Coolify deployment, or systemd reload onubuntu.megabyte.space), verify live health, and post the merged PR URL,maincommit SHA, and production proof on the Paperclip issue before markingdone.