first-task

Imported from paperclipai/paperclip (server/src/onboarding-assets/first-task/skills/first-task/SKILL.md). Install upstream with npx skills add paperclipai/paperclip --skill first-task. Copyright stays with the author.

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.

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 (request_human_input with interactionKind: "questions" when available, otherwise the ask_user_questions 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.

2. 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.
   • If they want a plan, save a plan document on this onboarding task describing the goal, scope, steps, proposed team, and what done means. Post one request_checkbox_confirmation 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 does not authorize hiring it.
   • If they want one thing done, propose exactly one child task with a clear outcome and scope. Ask them to accept it before creating the child. 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 request_confirmation card describing the child task, without a plan document; plan means save a short plan document describing that same child task and post one request_checkbox_confirmation targeting its saved revision.
   • With native tools, create those proposal cards using request_human_input: interactionKind: "confirmation" creates request_confirmation; interactionKind: "checkbox" creates request_checkbox_confirmation. Use continuationPolicy: "wake_assignee" 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 request_human_input with arguments like these. Replace <child-title> 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.

   {
     "idempotencyKey": "first-task-proposal-confirmation",
     "interactionKind": "confirmation",
     "title": "Approve child task",
     "prompt": "Approve creating exactly one child task named \"<child-title>\" 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 request_human_input with a checkbox card bound to its actual revision. Replace <child-title> and <plan-revision-id>; make the options describe the scope the user is approving. For a plan-only request, the option approves the plan alone and does not authorize implementation or hiring.

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

3. 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": "<user-message-id>", "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.

4. 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 single task, check for an existing child from this proposal before creating anything. Create exactly one child linked to this onboarding task and assign it to yourself. On later wakes, continue that same child instead of creating another.
   • 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 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 set_dependencies, then paperclip_block 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 create_task with createTask first. After its successful receipt, call set_dependencies with setDependencies on this onboarding task, then paperclip_block 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 <approved-child-description> with the self-contained description and actual inputs described above. Replace <existing-blocker-id> 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 set_dependencies 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>"]
     }
   }