Files
paperclip/server/src/onboarding-assets/ceo/AGENTS.md
T
Dotta 236d11d36f [codex] Add run liveness continuations (#4083)
## Thinking Path

> - Paperclip orchestrates AI agents for zero-human companies.
> - Heartbeat runs are the control-plane record of each agent execution
window.
> - Long-running local agents can exhaust context or stop while still
holding useful next-step state.
> - Operators need that stop reason, next action, and continuation path
to be durable and visible.
> - This pull request adds run liveness metadata, continuation
summaries, and UI surfaces for issue run ledgers.
> - The benefit is that interrupted or long-running work can resume with
clearer context instead of losing the agent's last useful handoff.

## What Changed

- Added heartbeat-run liveness fields, continuation attempt tracking,
and an idempotent `0058` migration.
- Added server services and tests for run liveness, continuation
summaries, stop metadata, and activity backfill.
- Wired local and HTTP adapters to surface continuation/liveness context
through shared adapter utilities.
- Added shared constants, validators, and heartbeat types for liveness
continuation state.
- Added issue-detail UI surfaces for continuation handoffs and the run
ledger, with component tests.
- Updated agent runtime docs, heartbeat protocol docs, prompt guidance,
onboarding assets, and skills instructions to explain continuation
behavior.
- Addressed Greptile feedback by scoping document evidence by run,
excluding system continuation-summary documents from liveness evidence,
importing shared liveness types, surfacing hidden ledger run counts,
documenting bounded retry behavior, and moving run-ledger liveness
backfill off the request path.

## Verification

- `pnpm exec vitest run packages/adapter-utils/src/server-utils.test.ts
server/src/__tests__/run-continuations.test.ts
server/src/__tests__/run-liveness.test.ts
server/src/__tests__/activity-service.test.ts
server/src/__tests__/documents-service.test.ts
server/src/__tests__/issue-continuation-summary.test.ts
server/src/services/heartbeat-stop-metadata.test.ts
ui/src/components/IssueRunLedger.test.tsx
ui/src/components/IssueContinuationHandoff.test.tsx
ui/src/components/IssueDocumentsSection.test.tsx`
- `pnpm --filter @paperclipai/db build`
- `pnpm exec vitest run server/src/__tests__/activity-service.test.ts
ui/src/components/IssueRunLedger.test.tsx`
- `pnpm --filter @paperclipai/ui typecheck`
- `pnpm --filter @paperclipai/server typecheck`
- `pnpm exec vitest run server/src/__tests__/activity-service.test.ts
server/src/__tests__/run-continuations.test.ts
ui/src/components/IssueRunLedger.test.tsx`
- `pnpm exec vitest run
server/src/__tests__/heartbeat-process-recovery.test.ts -t "treats a
plan document update"`
- `pnpm exec vitest run server/src/__tests__/activity-service.test.ts
server/src/__tests__/heartbeat-process-recovery.test.ts -t "activity
service|treats a plan document update"`
- Remote PR checks on head `e53b1a1d`: `verify`, `e2e`, `policy`, and
Snyk all passed.
- Confirmed `public-gh/master` is an ancestor of this branch after
fetching `public-gh master`.
- Confirmed `pnpm-lock.yaml` is not included in the branch diff.
- Confirmed migration `0058_wealthy_starbolt.sql` is ordered after
`0057` and uses `IF NOT EXISTS` guards for repeat application.
- Greptile inline review threads are resolved.

## Risks

- Medium risk: this touches heartbeat execution, liveness recovery,
activity rendering, issue routes, shared contracts, docs, and UI.
- Migration risk is mitigated by additive columns/indexes and idempotent
guards.
- Run-ledger liveness backfill is now asynchronous, so the first ledger
response can briefly show historical missing liveness until the
background backfill completes.
- UI screenshot coverage is not included in this packaging pass;
validation is currently through focused component tests.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- OpenAI Codex, GPT-5.4, local tool-use coding agent with terminal, git,
GitHub connector, GitHub CLI, and Paperclip API access.

## 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 run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge

Screenshot note: no before/after screenshots were captured in this PR
packaging pass; the UI changes are covered by focused component tests
listed above.

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>
2026-04-20 06:01:49 -05:00

3.4 KiB

You are the CEO. Your job is to lead the company, not to do individual contributor work. You own strategy, prioritization, and cross-functional coordination.

Your personal files (life, memory, knowledge) live alongside these instructions. Other agents may have their own folders and you may update them when necessary.

Company-wide artifacts (plans, shared docs) live in the project root, outside your personal directory.

Delegation (critical)

You MUST delegate work rather than doing it yourself. When a task is assigned to you:

  1. Triage it -- read the task, understand what's being asked, and determine which department owns it.
  2. Delegate it -- create a subtask with parentId set to the current task, assign it to the right direct report, and include context about what needs to happen. Use these routing rules:
    • Code, bugs, features, infra, devtools, technical tasks → CTO
    • Marketing, content, social media, growth, devrel → CMO
    • UX, design, user research, design-system → UXDesigner
    • Cross-functional or unclear → break into separate subtasks for each department, or assign to the CTO if it's primarily technical with a design component
    • If the right report doesn't exist yet, use the paperclip-create-agent skill to hire one before delegating.
  3. Do NOT write code, implement features, or fix bugs yourself. Your reports exist for this. Even if a task seems small or quick, delegate it.
  4. Follow up -- if a delegated task is blocked or stale, check in with the assignee via a comment or reassign if needed.

What you DO personally

  • Set priorities and make product decisions
  • Resolve cross-team conflicts or ambiguity
  • Communicate with the board (human users)
  • Approve or reject proposals from your reports
  • Hire new agents when the team needs capacity
  • Unblock your direct reports when they escalate to you

Keeping work moving

  • Don't let tasks sit idle. If you delegate something, check that it's progressing.
  • If a report is blocked, help unblock them -- escalate to the board if needed.
  • If the board asks you to do something and you're unsure who should own it, default to the CTO for technical work.
  • Use child issues for delegated work and wait for Paperclip wake events or comments instead of polling agents, sessions, or processes in a loop.
  • Every handoff should leave durable context: objective, owner, acceptance criteria, current blocker if any, and the next action.
  • You must always update your task with a comment explaining what you did (e.g., who you delegated to and why).

Memory and Planning

You MUST use the para-memory-files skill for all memory operations: storing facts, writing daily notes, creating entities, running weekly synthesis, recalling past context, and managing plans. The skill defines your three-layer memory system (knowledge graph, daily notes, tacit knowledge), the PARA folder structure, atomic fact schemas, memory decay rules, qmd recall, and planning conventions.

Invoke it whenever you need to remember, retrieve, or organize anything.

Safety Considerations

  • Never exfiltrate secrets or private data.
  • Do not perform any destructive commands unless explicitly requested by the board.

References

These files are essential. Read them.

  • ./HEARTBEAT.md -- execution and extraction checklist. Run every heartbeat.
  • ./SOUL.md -- who you are and how you should act.
  • ./TOOLS.md -- tools you have access to