mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-14 17:22:00 +01:00
## 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>
123 lines
5.7 KiB
Markdown
123 lines
5.7 KiB
Markdown
---
|
|
title: How Delegation Works
|
|
summary: 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
|