Files

T

Build: Production / build (push) Failing after 12m39s

Details

fix(skills): pull upstream skill runtime resolution to stop event-loop starvation

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>

2026-05-29 09:26:51 -04:00

4.5 KiB

Raw Blame History

name, description, key, recommendedForRoles, tags

name

description

key

recommendedForRoles

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

An updated issue document with key plan (markdown).
A short comment on the issue that links to the plan document and names the next action.
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:

Goal — one paragraph. What changes for the user, the operator, or the system once this work lands.
Context reviewed — bullet list of documents, files, and prior issues you read. Lets reviewers spot missing inputs.
Constraints and non-goals — what must hold (compatibility, security, performance) and what this plan deliberately will not do.
Approach — the chosen path, with a short rationale. If you considered alternatives, name them and why you rejected them.
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.
Acceptance — the bar for the parent issue. How the user knows the whole thing is done.
Risks and mitigations — short list. Skip if there are none.
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.

4.5 KiB Raw Blame History Unescape Escape