first-task skill

First task

Use this workflow only for the onboarding task that invokes /first-task, including later replies and approval wakes on that same task. Do not apply it to the agent's other tasks just because this skill is installed. Follow it without announcing the first-task skill in routine messages, cards, or documents. Say "I'm doing X," not "I'm using the first-task skill to do X," and explain next steps directly. This is a wording preference: answer truthfully if the user asks about the workflow, and always disclose relevant permissions, security implications, and execution actions.

Talk in outcomes. The user is new to Paperclip. In chat replies, cards, and task text, say what happened, what it means for them, and the next step. Never narrate internal mechanics such as receipts, execution policies, patches, runs, wake payloads, tool calls, or raw IDs, and name tasks by identifier (for example PIX-3), not UUID. If a step did not work, say plainly what is not done yet and what you will do next; keep the technical detail out of the message.

This is the user's first task in Paperclip. Your job is to understand what they want and propose a path forward. A greeting and an opening question card were already posted for you; the card offered two choices: "Interview me and propose a plan and an agent team to execute it." (option interview) or "I have a task in mind" (option task, with a text field). You are running because the user answered that card (the answer is in your wake payload) or wrote a message instead of answering. Don't re-introduce yourself and don't post the opening card again.

Work in this order.

1. Take the path the user picked.

• interview → ask the user 3–4 questions in one Paperclip question card (requesthumaninput with interactionKind: "questions" when available, otherwise the askuserquestions API) that pin down what their organization does, what they want to achieve first, any constraints (time, budget, tools), and what "done" looks like. Don't guess; ask. Don't post anything else before the card. The answers lead to the plan-and-team path in step 2.

• task → the text they typed is the task. If it is clear enough to propose on, go straight to step 2. If not, reply by asking 2–3 questions specific to their message (concrete goal, constraints, what "done" looks like), then go to step 2.

• If they wrote a message instead of answering the card, treat the message as the task path.

• Determine the requested outcome before choosing an approval boundary. The interview path and requests to build, improve, or deliver something are execution requests: the plan is an intermediate artifact. Treat a request as plan-only only when the user explicitly limits the deliverable to planning. Asking to review a plan before work begins does not make it plan-only. Preserve any separate hiring or execution approvals the user explicitly requests and any applicable company policies.

• If the user asks to continue onboarding in your chat with them instead, ask your questions there. Your first question in the chat replaces this task's pending question cards, and Paperclip closes this task with a link to the chat. From then on the chat replaces this task for the rest of this workflow: save the plan and post proposal cards in the chat, create accepted execution tasks from the chat, and report their results there. Skip the steps below that keep this task in_review, save documents on it, or make it wait for a child. Do not reopen this task or ask the user what should happen to it.

1. Propose, then wait for acceptance.

• Choose the proposal form from the user’s request first: an explicit plan request or the interview path always requires a saved plan, even when the task description says confirmation.
• For the interview path or an explicit plan request, save a plan document on this onboarding task describing the goal, scope, steps, proposed team, and what done means. Post one requestcheckboxconfirmation targeting the saved plan revision. A card or thread message alone is not a saved plan. This applies to explicit plan requests regardless of the single-task proposal mode. Proposing a team alone does not authorize hiring it; the recorded acceptance authorizes only the team and work actually included in the accepted scope, subject to normal hiring and budget policies.
• For an execution request, make the saved plan and approval card say "Approve this plan and start the described work." Describe the tasks and any proposed hires the user is approving. Do not add a separate implementation-approval requirement unless the user or an applicable policy requires it. For an explicitly plan-only request, make the card say "Approve this plan only; do not start implementation."
• If they want one thing done, propose completing it on this task with a clear outcome and scope. Ask them to accept the scope before execution. Do not produce the requested finished work inside the proposal, even when it is quick to do.
• For a single-task proposal, follow the Single-task proposal mode saved in the task description: confirmation means one requestconfirmation card describing the work, without a plan document; plan means save a short plan document describing that same work and post one requestcheckbox_confirmation targeting its saved revision.
• With native tools, create those proposal cards using requesthumaninput: interactionKind: "confirmation" creates requestconfirmation; interactionKind: "checkbox" creates requestcheckboxconfirmation. Use continuationPolicy: "wakeassignee" so acceptance and rejection both return the decision to you; only a saved acceptance authorizes the approved work. Use interactionKind: "questions" only to collect scope or clarification answers. An Approve/Revise choice question is still a question, so answering it does not record proposal acceptance or authorize child creation. Present the proposal through the matching confirmation kind instead.
• Keep this task in_review while waiting. You may clarify, research for planning, and save or revise a plan/proposal before acceptance. Do not hire, create execution tasks, perform the deliverable, save finished output, or claim completion yet.

For a native single-task confirmation, call requesthumaninput with arguments like these. Replace with the proposed title and describe its actual scope in the prompt. Use a new idempotency key for each changed or revised proposal. Reuse a key only for the exact same proposal when reconciling an interrupted call; the example key below is for the first proposal.

The tool's root fields are idempotencyKey, interactionKind, title, prompt, continuationPolicy, and payload, with optional targetRevisionId and resolverPolicy as advertised. Put version and supersedeOnUserComment inside payload; neither is a root argument. If validation rejects a proposal, correct its argument placement and keep the confirmation or checkbox approval kind. Switching it to a question form cannot authorize the proposed work. Wait for a successful saved card receipt before claiming you requested approval.

For ordinary first-task proposals that accept a reply in this conversation, omit the optional resolverPolicy and inherit the server/company default. Do not add humanonly merely because you are asking the user to decide: resolve-from-comment records your interpretation as the responding agent; on a human-only card it accepts only the bound user's verified latest reply, and only when you requested humanonly yourself. Preserve explicit user requirements for human-only approval, company restrictions, and governed-action requirements; omission does not override them. Never lower a saved card's policy or recreate it to bypass a denial. Restricted cards must keep their required human response controls.

{
     "idempotencyKey": "first-task-proposal-confirmation",
     "interactionKind": "confirmation",
     "title": "Approve work",
     "prompt": "Approve completing \"<task-title>\" on this task for the scope described above?",
     "continuationPolicy": "wake_assignee",
     "payload": {
       "version": 1,
       "supersedeOnUserComment": false,
       "acceptLabel": "Approve",
       "rejectLabel": "Revise",
       "rejectRequiresReason": true
     }
   }

For a native single-task proposal in plan mode, save the plan first, then call requesthumaninput with a checkbox card bound to its actual revision. Replace and ; make the options describe the scope the user is approving. For an explicitly plan-only request, change the prompt and option to approve the plan alone without implementation or hiring.

{
     "idempotencyKey": "first-task-proposal-plan:<plan-revision-id>",
     "interactionKind": "checkbox",
     "title": "Approve plan and start work",
     "prompt": "Approve this plan and start the described work?",
     "continuationPolicy": "wake_assignee",
     "payload": {
       "version": 1,
       "supersedeOnUserComment": false,
       "options": [{ "id": "scope", "label": "Approve the plan and start <task-title>" }],
       "defaultSelectedOptionIds": ["scope"],
       "minSelected": 1,
       "maxSelected": 1,
       "target": { "type": "issue_document", "key": "plan", "revisionId": "<plan-revision-id>" }
     }
   }

1. Interpret the next reply against the latest proposal.

• Acceptance is an accepted confirmation card or an explicit conversational reply agreeing to the proposal. The opening answer, a clear request, and answers to clarification questions supply scope; they are not acceptance of a proposal you have not yet made.
• When acceptance or rejection arrives in chat, persist it on the corresponding pending confirmation before hiring, creating a child, executing, or closing this task. Read this task's interactions and comments, then POST /api/issues/{issueId}/interactions/{interactionId}/resolve-from-comment with { "commentId": "", "decision": "accept" } (or "reject" and the user's reason). Native runners use call_api. For a checkbox card, include selectedOptionIds for the user's actual selection; never infer acceptance from defaults. Wait for the saved accepted/rejected result. Retry an interrupted write using the same message and decision; inspect a conflicting result instead of proceeding. Do not tell the user to return to the card after answering in chat.
• An ambiguous reply with multiple pending proposals is not permission to resolve them all. Ask which proposal or options they mean. A card already answered through the UI needs no second resolution. Forms, governed actions, and human-only policies keep their existing response rules.
• A clarification answer means update the proposal if needed and ask for acceptance. A requested revision supersedes the old scope: revise the proposal and wait for acceptance of the revised version.
• If they reject the proposal, acknowledge and stop. Do not execute it. You may close the onboarding task after acknowledging the rejection; do not describe rejected work as completed.

1. Carry out the accepted scope.

• For a plan-only request, retain the accepted plan on this task. Do not start its implementation or hire the proposed team without authorization to do that work.
• For an accepted interview execution plan, carry out the approved work on this task unless the accepted plan explicitly assigns work elsewhere. Use normal hiring controls for any approved hires. Check for existing tasks from this proposal first so later wakes and retries continue the same work.
• A recorded acceptance of an execution proposal authorizes starting its selected work. Start that work without asking the user to approve the same scope again. Honor an accepted proposal that explicitly reserved a later approval; never expand its authorization retroactively. Missing credentials or connections block only the steps that require them; continue independent approved work.
• For an accepted single task, complete the work here. Save the output document and publish any requested file on this task before marking it done. If the accepted proposal already specified a separate task, honor that assignment and reuse any task already created for it.
• A saved, approved plan alone does not complete an execution request. Follow the execution and result-delivery steps below for the approved tasks, and report the actual output before completing onboarding. An explicitly plan-only request is complete when its accepted plan is retained.

The following handoff steps apply only when the accepted proposal explicitly includes a separate task. They do not require a new task for work you can complete here.

• If the accepted child work requires a file deliverable, include the approved scope, document requirements, and requested filenames in a self-contained child description. Delegate the work to the child's own Paperclip execution, even when the child is assigned to yourself. That execution must save the document and publish the requested file on the child before marking it done. Do not create or register that file from the onboarding run, or mark the child done before its execution delivers the file. Native register_deliverable is bound to its current task.
• Copy required input payloads verbatim, including encoded bytes, nonces, constraints, and requested filenames, from the accepted request and its accepted corrections into the child description. The child has its own execution context and does not inherit this conversation. Do not leave references such as "provided above" or "same as the parent" in place of actual inputs. When an input is not inline, include its actual retrievable source reference as an identifier link such as BRA-2, not a raw UUID, and ensure the child is authorized to read it. Keep credentials and secrets out of handoff text.
• Parent-child linkage is not a dependency. Do not put this onboarding task in the child's blockedByTaskIds: the child must execute before this task can finish. Create the child ready to run, then make this onboarding task wait for the child.
• While waiting for that file-producing child, preserve existing blocker IDs and add the child as a dependency. Native runners use setdependencies, then paperclipblock with the child agent as owner and child completion as the unblock action; legacy runners use the normal issue API with blockedByIssueIds and a blocked disposition. End the turn so the child can execute. Do not poll for its result while holding the onboarding run.
• When child completion resumes the onboarding task, verify the saved child document and retrievable file, then reply with the actual child task and download links. Reuse the recorded result instead of producing another file on the parent or creating another child.
• For document-only child work, you may execute it directly. Save the finished output as a document on the child task and mark that child done. Link it from the onboarding conversation. Completing the onboarding parent in place, or saving the output only on the parent, does not fulfill the accepted child-task proposal.

For a new native file-producing handoff, the following JSON contains two argument objects, not one tool call. Call createtask with createTask first. After its successful receipt, call setdependencies with setDependencies on this onboarding task, then paperclipblock as above. Replace every placeholder before calling a tool: use the accepted proposal's ID, your actual agent ID, and the created child's task ID. Replace with the self-contained description and actual inputs described above. Replace with all current blocker IDs; remove that placeholder when there are none, leaving only the child ID. Never replace it with this onboarding task's own ID. Keep each blocker ID only once. If the child already exists, reuse its ID and continue with setdependencies instead of creating another child.

{
     "createTask": {
       "idempotencyKey": "first-task-child:<proposal-id>",
       "title": "<child-title>",
       "description": "<approved-child-description>",
       "assigneeActorId": "<self-agent-id>",
       "status": "todo",
       "blockedByTaskIds": []
     },
     "setDependencies": {
       "idempotencyKey": "first-task-wait:<proposal-id>",
       "blockedByTaskIds": ["<existing-blocker-id>", "<child-task-id>"]
     }
   }