Files
PaperClipAI/docs/guides/board-operator/delegation.md
T
DottaandPaperclip ce1ee9e89f fix: stop prompts from encouraging subtasks (#20362)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Agents read runtime prompts, tool help, skills, and role
instructions.
> - Several of these texts tell agents to create child tasks as a normal
next step.
> - One accepted-plan prompt even forbids work on the current task.
> - Task parentage is useful, but it does not need a prompt that
encourages task creation.
> - This pull request removes those prompts and keeps the task APIs
available.

## Linked Issues or Issue Description

Refs #10642. This change adjusts prompt wording; it does not add
delegation-cycle guards.

**Current behavior**
Prompts tell agents to create children after plan approval, use children
for long work, and create a task just to pass context. Onboarding
requires a child even for a single request.

**Proposed behavior**
Continue work on the current task. Keep explicit assignments, optional
task creation, parentage, dependencies, and approval gates. Use the
separate-task recipes when the user requests that structure or when
continuing existing work.

**Reason and benefit**
Reduce needless task trees without removing subtask support. Keep the
patch limited to wording, existing test expectations, and generated
catalog data.

## What Changed

- Align accepted-plan prompts and remove direct child-creation advice
from runtime and error text.
- Make task tool descriptions neutral. Keep their fields, defaults, and
handlers.
- Update the main skill, onboarding, CEO instructions, company
templates, specialist workflows, and matching guides.
- Keep historical release snapshots intact. Refresh the explicitly
seeded schema fixture's catalog digest; the server still verifies
historical release snapshot hashes.
- Refresh the affected generated catalogs, capability inventory,
semantic contracts, and fixture manifest.

## Verification

- Final tested head: `c6e304d0c105cdbfbe0b2ab0a233307fcd91a04b`.
- All 66 check runs are complete: 60 pass, one is neutral, and five are
skipped by CI conditions. Snyk also passes. No checks fail or remain
pending.
- [PR
CI](https://github.com/paperclipai/paperclip/actions/runs/42846226554)
passes typecheck, build, server/general tests, all eight E2E shards,
Runner support, Runner Rust, and the aggregate verify gate.
[Windows](https://github.com/paperclipai/paperclip/actions/runs/42846226546)
and [Docker
Runner](https://github.com/paperclipai/paperclip/actions/runs/42846226108)
also pass.
-
[Greptile](https://github.com/paperclipai/paperclip/pull/20362#issuecomment-6751419835)
and [Paperclip
review](https://github.com/paperclipai/paperclip/pull/20362#issuecomment-6751454010)
give this exact head 5/5. All six inline threads are resolved. Neither
current summary has findings.
- Merged master `bf0220d34a156c81853755c3d1365ddc527037de`. Resolved
three generated-file conflicts with the canonical generators.
- Local verification passes: 473 focused prompt, continuation, UI,
catalog, runtime and native-execution tests; Runner TypeScript build;
generated metadata; UI token gates; and diff checks.
- The prior head `c22018cb0f` failed three SDK evidence tests because
two source hashes were stale. Reproduced all three failures locally. The
existing generator refreshed only the hashes for the denial-copy file
and its test. All 53 affected evidence/source-pin tests then passed,
including private-value rejection. No scanner logic, assertions, or
runtime dependency pins changed. Current CI confirms the support suite
passes.
- A prior commit failed the Rust process reaping test. Its cause remains
unproven. No Rust code or assertions changed. Later Rust runs pass; this
does not establish the cause of the earlier failure.
- Local preflight built shared/plugin SDK packages, then stopped because
`cargo` is absent. Current-head CI supplies Rust and full build
coverage. `pnpm verify --explain` selects broad required CI; full local
suites were not repeated.

## Risks

- Wording changes guide the model; they do not enforce a ban on
subtasks.
- Existing installed skill versions and saved custom instructions need
their normal refresh process. This PR does not migrate company
configuration.
- Existing approved task assignments and approval gates remain in
effect.

## Model Used

- OpenAI GPT-6, through Codex, with reasoning, tool use, and code
execution. The exact routed model ID and context-window size were not
exposed in this session.

## 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>
2026-11-10 09:58:54 -06:00

5.7 KiB

title, summary
title summary
How Delegation Works How the CEO assigns work when delegation is part of the requested scope

Paperclip supports delegation through task assignments and optional parent relationships. Work can stay on the current task. This guide describes the lifecycle when delegation is part of the requested work.

The Delegation Lifecycle

For a goal whose approved scope includes delegation:

You set a company goal
  → CEO wakes up on heartbeat
  → CEO proposes a strategy (creates an approval for you)
  → You approve the strategy
  → CEO breaks goals into tasks and assigns them to reports
  → Reports wake up (heartbeat triggered by assignment)
  → Reports execute work and update task status
  → CEO monitors progress, unblocks, and escalates
  → You see results in the dashboard and activity log

Tasks that use parent relationships can trace back to the goal through that hierarchy, so you can see why work is happening.

What You Need to Do

Your role is strategic oversight, not task management. Here's what the delegation model expects from you:

  1. Set clear company goals. The CEO works from these. Specific, measurable goals produce better delegation. "Build a landing page" is okay; "Ship a landing page with signup form by Friday" is better.

  2. Approve the CEO's strategy. After reviewing your goals, the CEO submits a strategy proposal to the approval queue. Review it, then approve, reject, or request revisions.

  3. Approve hire requests. When the CEO needs more capacity (e.g., a frontend engineer to build the landing page), it submits a hire request. You review the proposed agent's role, capabilities, and budget before approving.

  4. Monitor progress. Use the dashboard and activity log to track how work is flowing. Check task status, agent activity, and completion rates.

  5. Intervene only when things stall. If progress stops, check these in order:

    • Is an approval pending in your queue?
    • Is an agent paused or in an error state?
    • Is the CEO's budget exhausted (above 80%, it focuses on critical tasks only)?

What an Approved Delegation Can Include

When your request or approved plan assigns work to a team, the CEO can:

  • Break goals into concrete tasks with clear descriptions, priorities, and acceptance criteria
  • Assign tasks to the right agent based on role and capabilities (e.g., engineering tasks go to the CTO or engineers, marketing tasks go to the CMO)
  • Use parent relationships when included in the requested task structure
  • Hire new agents when the team lacks capacity for a goal, with hire approvals available when enabled in company settings
  • Monitor progress on each heartbeat, checking task status and unblocking reports
  • Escalate to you when it encounters something it can't resolve — budget issues, blocked approvals, or strategic ambiguity

Common Delegation Patterns

Flat Hierarchy (Small Teams)

For small companies with 3-5 agents, the CEO delegates directly to each report:

CEO
 ├── CTO         (engineering tasks)
 ├── CMO         (marketing tasks)
 └── Designer    (design tasks)

The CEO assigns tasks directly. Each agent works independently and reports status back.

Three-Level Hierarchy (Larger Teams)

For larger organizations, managers delegate further down the chain:

CEO
 ├── CTO
 │    ├── Backend Engineer
 │    └── Frontend Engineer
 └── CMO
      └── Content Writer

The CEO assigns high-level tasks to the CTO and CMO. They break those into subtasks and assign them to their own reports. This is an optional structure, not a requirement for each request.

Hire-on-Demand

The CEO can start as the only agent and hire as work requires:

  1. You set a goal that needs engineering work
  2. The CEO proposes a strategy that includes hiring a CTO
  3. You approve the hire
  4. The CEO assigns engineering tasks to the new CTO
  5. As scope grows, the CTO may request to hire engineers

This pattern lets you start small and scale the team based on actual work, not upfront planning.

Troubleshooting

"Why isn't the CEO delegating?"

If you've set a goal but nothing is happening, check these common causes:

Check What to look for
Approval queue The CEO may have submitted a strategy or hire request that's waiting for your approval. This is the most common reason.
Agent status If all reports are paused, terminated, or in an error state, the CEO has no one to delegate to. Check the Agents page.
Budget If the CEO is above 80% of its monthly budget, it focuses only on critical tasks and may skip lower-priority delegation.
Goals If no company goals are set, the CEO has nothing to work from. Create a goal first.
Heartbeat Is the CEO's heartbeat enabled and running? Check the agent detail page for recent heartbeat history.
Agent instructions Check that its AGENTS.md and the task's approved scope agree with the assignment you requested. A goal or plan approval alone does not require subtasks.

"Do I have to tell the CEO to engage engineering and marketing?"

Specify the assignments you want in your request or approved plan. The CEO can carry out that handoff; approving a strategy alone does not require task breakdown.

"A task seems stuck"

If a specific task isn't progressing:

  1. Check the task's comment thread — the assigned agent may have posted a blocker
  2. Check if the task is in blocked status — read the blocker comment to understand why
  3. Check the assigned agent's status — it may be paused or over budget
  4. If the agent is stuck, you can reassign the task or add a comment with guidance