fix(skills): pull upstream skill runtime resolution to stop event-loop starvation
Build: Production / build (push) Failing after 12m39s
Build: Production / build (push) Failing after 12m39s
The fork's listRuntimeSkillEntries rematerialized every skill's files from the DB on every heartbeat run dispatch — fs.rm + fs.mkdir + per-file readFile/writeFile, sequentially per skill. With 24 configured skills and 5 concurrent agents, this saturated the Node event loop badly enough that executeRun continuations couldn't reach activeRunExecutions.add() within the orphan-reaper's 5-min threshold, causing reaper to false-positive runs as "process_lost". Upstream's listRuntimeSkillEntries calls resolveRuntimeSkillSource, which checks if the materialized directory already exists on disk and short- circuits when it does. Fixes the symptom at the root. Replaces these files with upstream/master content: - server/src/services/company-skills.ts - server/src/services/heartbeat.ts - server/src/services/workspace-runtime.ts - server/src/services/company-portability.ts - server/src/routes/company-skills.ts - server/src/routes/agents.ts - packages/adapter-utils/src/server-utils.ts Pulls in supporting upstream files: - server/src/services/catalog-provenance.ts - server/src/services/skills-catalog.ts - server/src/services/github-fetch.ts - server/src/services/portable-path.ts - packages/skills-catalog/ (new package) - packages/db document_annotation_* schema + migration 0091 - packages/shared document-annotation types/validators Drops fork features (to be re-evaluated later): - Gitea/Forgejo git skill sources (server/src/services/git-source.ts deleted) - PAT support for private skill repos - Fork-specific secret-export portability extensions Adds agentId: null to acquireRunLease test-probe call in routes/agents.ts to satisfy the fork's environment-runtime agentId requirement (kept). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,74 @@
|
||||
---
|
||||
name: issue-triage
|
||||
description: Triage Paperclip inbox issues that are stale, blocked, in-review, or assigned-but-not-progressing, and decide a single next action per issue (resume, reassign, unblock, escalate, or close).
|
||||
key: paperclipai/bundled/paperclip-operations/issue-triage
|
||||
recommendedForRoles:
|
||||
- manager
|
||||
- ceo
|
||||
- engineer
|
||||
tags:
|
||||
- paperclip
|
||||
- triage
|
||||
- inbox
|
||||
- workflow
|
||||
---
|
||||
|
||||
# Issue Triage
|
||||
|
||||
Convert a noisy inbox into a small set of clear next actions. Each pass through this skill should leave every touched issue with a defined owner, status, and the single concrete action that will move it forward.
|
||||
|
||||
## When to use
|
||||
|
||||
- Daily or shift-start review of `in_progress`, `in_review`, and `blocked` assignments.
|
||||
- An inbox has many open assignments and no clear priority.
|
||||
- A manager wants a status read on their reports without asking each agent.
|
||||
- You are woken by a comment that suggests an old issue stalled.
|
||||
|
||||
## When not to use
|
||||
|
||||
- You are checked out on one specific issue and the wake context names it. Work that issue, do not triage the whole inbox.
|
||||
- An issue thread already has an open `request_confirmation` or `ask_user_questions`. Wait for the response — re-triage is noise.
|
||||
|
||||
## Inputs
|
||||
|
||||
- `GET /api/agents/me/inbox-lite` for the compact assignment list.
|
||||
- For each candidate issue, `GET /api/issues/{issueId}/heartbeat-context` for compact state including `blockerAttention`, `executionState`, ancestors, and `commentCursor`.
|
||||
- Only fall back to the full thread when the heartbeat context is not enough.
|
||||
|
||||
## Per-issue triage decision
|
||||
|
||||
For each issue, classify into exactly one of:
|
||||
|
||||
1. **Resume** — execution path is alive. Confirm the assignee is set and let the heartbeat continue. Do not comment.
|
||||
2. **Wake-needed** — assignee is stalled with no live continuation. Post one comment that names the blocker resolution or the exact next action, then leave `in_progress` or move to `todo` so the assignee picks it up.
|
||||
3. **Reassign** — the assignee is not the right specialty. Reassign and set `in_review` only if the new assignee is human, otherwise leave `in_progress`.
|
||||
4. **Unblock** — a first-class `blockedByIssueIds` entry is now `done` or `cancelled`. If `cancelled`, replace or remove it from `blockedByIssueIds`. The blockers-resolved wake will fire automatically when all are `done`.
|
||||
5. **Escalate** — the issue needs board, CTO, or user input. Create a `request_confirmation`, `ask_user_questions`, or `request_board_approval` and set the issue to `in_review`.
|
||||
6. **Close** — work is complete, duplicate, or no longer relevant. Set `done` or `cancelled` with a one-line reason.
|
||||
|
||||
If you cannot classify in under a minute of reading, escalate rather than guess.
|
||||
|
||||
## Stuck-state heuristics
|
||||
|
||||
- `in_progress` with no comments or document updates in the last 24h and no monitor or queued continuation → wake-needed.
|
||||
- `in_review` with no reviewer participant, no pending interaction, no approval — invalid review path → reassign to a real reviewer or move to `todo`.
|
||||
- `blocked` with no `blockedByIssueIds`, only free-text "blocked by X" → convert to first-class blockers or move to `todo` with a named action.
|
||||
- `blocked` with all blockers `done` → unblock the issue by setting status back; the assignee will wake.
|
||||
- Child issues all complete but parent still `in_progress` → confirm parent acceptance, then close.
|
||||
|
||||
## Don't-do list
|
||||
|
||||
- Do not @-mention agents during triage; mentions cost budget. Use direct reassignment instead.
|
||||
- Do not re-comment on a `blocked` issue if your most recent comment was also a blocked update with no reply since.
|
||||
- Do not cancel cross-team issues. Reassign to the responsible manager with a comment.
|
||||
- Do not change status without a comment that explains the change.
|
||||
|
||||
## Output of a triage pass
|
||||
|
||||
A short comment chain or summary message that lists, per issue touched:
|
||||
|
||||
- Issue id and title.
|
||||
- Verdict (resume / wake-needed / reassign / unblock / escalate / close).
|
||||
- The one action you took or asked for.
|
||||
|
||||
This is the bar for "the triage is done."
|
||||
@@ -0,0 +1,84 @@
|
||||
---
|
||||
name: task-planning
|
||||
description: Turn a Paperclip issue or request into a structured implementation plan with child task graph, blockers, owners, and acceptance criteria, then save it as the issue `plan` document.
|
||||
key: paperclipai/bundled/paperclip-operations/task-planning
|
||||
recommendedForRoles:
|
||||
- manager
|
||||
- engineer
|
||||
- product
|
||||
tags:
|
||||
- paperclip
|
||||
- planning
|
||||
- issues
|
||||
- delegation
|
||||
---
|
||||
|
||||
# Task Planning
|
||||
|
||||
Produce implementation plans that the Paperclip executor can actually run: explicit child issues, real blockers, named owners, and a defined acceptance bar. Avoid plans that read well but cannot be split into work.
|
||||
|
||||
## When to use
|
||||
|
||||
- An issue asks you to "plan", "scope", "break down", "design the rollout", "propose the work", or similar.
|
||||
- A user wants a written plan before approving implementation.
|
||||
- A manager needs to delegate non-trivial work and the shape of the work is not obvious yet.
|
||||
- You inherited an issue too large to deliver in one heartbeat and need to split it.
|
||||
|
||||
## When not to use
|
||||
|
||||
- The issue is a single small change you can ship in the same heartbeat. Just ship it.
|
||||
- The issue is forensic ("why did this break"). Use a diagnosis skill first; plan only after the root cause is named.
|
||||
- A current `plan` document already exists and the change is minor. Update that document; do not start fresh.
|
||||
|
||||
## Outputs
|
||||
|
||||
1. An updated issue document with key `plan` (markdown).
|
||||
2. A short comment on the issue that links to the plan document and names the next action.
|
||||
3. Where the plan requires approval, an issue-thread interaction of kind `request_confirmation` bound to the latest plan revision.
|
||||
|
||||
Do not create implementation subtasks until the plan is accepted.
|
||||
|
||||
## Plan structure
|
||||
|
||||
Required sections, in order:
|
||||
|
||||
1. **Goal** — one paragraph. What changes for the user, the operator, or the system once this work lands.
|
||||
2. **Context reviewed** — bullet list of documents, files, and prior issues you read. Lets reviewers spot missing inputs.
|
||||
3. **Constraints and non-goals** — what must hold (compatibility, security, performance) and what this plan deliberately will not do.
|
||||
4. **Approach** — the chosen path, with a short rationale. If you considered alternatives, name them and why you rejected them.
|
||||
5. **Work breakdown** — ordered list of child issues. Each child has:
|
||||
- Title in imperative form.
|
||||
- Owner specialty (Engineer, QA, Designer, Security, DevRel, Manager, etc.).
|
||||
- Scope and deliverables.
|
||||
- Acceptance criteria.
|
||||
- Blocks/blocked-by relationships expressed by phase letter or child title.
|
||||
6. **Acceptance** — the bar for the parent issue. How the user knows the whole thing is done.
|
||||
7. **Risks and mitigations** — short list. Skip if there are none.
|
||||
8. **Deferrals** — what is intentionally pushed to follow-up issues, with why.
|
||||
|
||||
## Rules of thumb for splitting
|
||||
|
||||
- One child issue, one specialty. If two specialties have to coordinate inside the same issue, split it.
|
||||
- One child issue, one acceptance verdict. If a reviewer would say "this is half done", split it.
|
||||
- A child must be checkout-able by the owner from its title and description alone. Reviewers should not have to re-read the parent plan to understand a child.
|
||||
- Order children by real blocker chains, not by author preference. Parallel children should explicitly say `blockers: none`.
|
||||
- Avoid `polish` or `cleanup` child issues without acceptance criteria — they never close.
|
||||
|
||||
## Filing the plan
|
||||
|
||||
Use the Paperclip API to write the plan document, then comment:
|
||||
|
||||
- `PUT /api/issues/{issueId}/documents/plan` with the markdown body. If `plan` already exists, include the latest `baseRevisionId`.
|
||||
- `POST /api/issues/{issueId}/comments` with a short summary that links the plan: `/<prefix>/issues/<issue-id>#document-plan`.
|
||||
- If approval is required: `POST /api/issues/{issueId}/interactions` with `kind: request_confirmation`, `targetRevisionId` set to the new plan revision, `continuationPolicy: wake_assignee`, and `idempotencyKey: "confirmation:{issueId}:plan:{revisionId}"`.
|
||||
- Set the issue to `in_review` after creating the confirmation. Stay assigned so the acceptance wakes the planner.
|
||||
|
||||
When the plan is accepted, see the companion skill for converting accepted plans into Paperclip executable tasks.
|
||||
|
||||
## Anti-patterns
|
||||
|
||||
- Plan disguised as a description edit. Use the `plan` document.
|
||||
- "Phases A–Z" with no work breakdown inside the phases.
|
||||
- Children with descriptions that say "see parent" — they fail at delegation time.
|
||||
- Acceptance written as "code review approval". Reviewers need a behavior bar, not a process bar.
|
||||
- Plans that bury blocker chains in prose. Use explicit blocked-by lines.
|
||||
Reference in New Issue
Block a user