start-task

name	start-task
version	0.1.0
description	This skill should be used when the user provides a task URL and wants to begin working on it — "start task", "work on this", "pick up this ticket", "let's start on [task-id]", "jump on this", "begin this task", or pastes a task URL with intent to start development. Orchestrates the full lifecycle: validates sprint-readiness, sets up the branch and draft PR, routes to the right development workflow (feature-dev, fix-bug, or brainstorm), and ships via ship-it when done. Every run writes a step-by-step checkpoint file so work can be resumed after any interruption ("resume task", "pick up where I left off", "continue [task-id]"). For a shortcut that runs the full task orchestration and ship-it but skips sub-skill routing (feature-dev, brainstorming, fix-bug) and implements inline instead, add "fast" to the arguments — "start task fast", "fast mode", "just start coding".
argument-hint	<task-url> [brainstorm|feature-dev|fast]

Start Task

Take a task, validate it's ready for development, understand the work, set up the branch, and route to the right skill. This skill is the conductor — it validates, prepares, and hands off.

Prerequisites

• The task-manager interface for all task operations — handles provider resolution and setup guidance.
• Access to required external workflow skills — varies by runtime; checked in Step 0 (see references/skill-dependencies.md).

Argument Parsing

Parse $ARGUMENTS once and establish these flags. The rest of the skill refers to them by name instead of re-parsing.

Default: fast_mode is OFF. Only set fast_mode when the user's actual $ARGUMENTS message contains the word "fast" or "fast mode". Do NOT infer fast mode from this skill file's description, examples, or body text — those are instructions for you, not user input.

Flag	Set when $ARGUMENTS contains	Effect
fast_mode	fast	Step 10 skips sub-skill routing and the Step 11 QA sub-flow; implements inline
workflow_choice	brainstorm or feature-dev	Passed through to implement-feature at Step 10; if unset, implement-feature asks the operator

fast_mode is mutually exclusive with workflow_choice (fast skips routing entirely).

Fast Mode

Set when fast_mode flag is active (see Argument Parsing above).

Fast mode runs the full lifecycle (Steps 0–9 and Step 12) unchanged but replaces Step 10 skill routing with direct inline implementation, and skips Step 11 (QA sub-flow) entirely. No implement-feature (or its downstream development skills), fix-bug, or QA skill is invoked — implement the solution immediately using the agent's native file, shell, and edit tools, and reason about it directly in this conversation.

What is skipped: only the sub-skill routing in Step 10 and the entire Step 11 QA sub-flow. Everything else — dependency checks, sprint validation, branch creation, draft PR, task status move/comment, and the ship-it handoff — runs as normal.

The Flow

Before Step 0: Initialize (or resume) the checkpoint by running ${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/skills/start-task/scripts/checkpoint.sh init <task-ref> <task-url> (or load the existing file if one exists — see references/checkpoints.md → "Initialization" and "Resume Flow"). All checkpoint writes throughout the flow go through that helper script — do not Edit/Write the file directly.

Step 0: Check External Skill Dependencies

Before doing anything else, check whether external skills required for routing are installed for the current runtime. These are not bundled with this plugin and are mandatory.

• Claude Code: feature-dev@claude-plugins-official and superpowers@claude-plugins-official
• OpenCode/Codex: superpowers

If any required dependency for the current runtime is missing, stop before Step 1 and tell the user which setup command or plugin install is required. Do not continue inline. See references/skill-dependencies.md for runtime-specific check instructions and warning behavior.

Step 1: Get the Task URL

The task URL is passed as $ARGUMENTS. If empty or invalid, prompt for it. Extract the task reference from the URL (this is the task_ref used as the checkpoint key).

Step 2: Fetch Task Details

Resolve the URL to a task handle via find_task(ref), then fetch the full task (fields, board memberships, assignee, and description) via get_task(task) through the task-manager interface.

Present a quick summary for confirmation: task name, assignee, category, task ID, sprint, and backlog board memberships. Classify board memberships per plugins/cortex-workflow/references/workflow/boards.md.

Step 2a: Validate Assignee

Fetch the current user via get_current_user() to obtain their identity. Then compare against the task's assignee:

• No assignee — automatically assign the task to the current user via set_field(task, "Assignee", <current user>). Inform the user (do not ask). Proceed.
• Assignee is the current user — all good. Proceed.
• Assignee is someone else — ask (BLOCKING):

  "This task is assigned to [Name]. Reassign it to you before starting?"

  • Yes → Reassign via set_field(task, "Assignee", <current user>), then proceed.
  • No → Stop. Tell the user to resolve the assignment in the task manager before retrying.

Step 3: Validate Sprint-Readiness

Run the code-enforced verdict — do not evaluate the checks by hand. Run ${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/skills/task-manager/scripts/readiness.py check --url <task-url> <task-ref>; it resolves the provider, fetches the data via that provider's primitives, and returns a verdict JSON ({ready, checks:[active_sprint, estimate, status, task_key]}). See references/validation-rules.md for the verdict shape, how to branch on it, the operator-facing checklist, and skip rules.

Report the verdict as a checklist. Active sprint membership, Estimate, and a not-yet-started status are all blocking — status passes only when the task is in a not-yet-started state; otherwise offer to set it to the start state (e.g. Assigned) via the task-manager interface. Offer to set Estimate via the interface too; active sprint membership is fixed manually. Do not proceed until the blocking checks pass. Only the task key / ID field can be skipped after a warning (and is skipped entirely on providers with a native key).

Step 4: Fetch Subtasks

Fetch subtasks via get_subtasks(task). Group by status (incomplete = remaining work, completed = already done). Include subtasks in downstream context so the receiving skill understands what "done" looks like.

Step 5: Fetch Comments and Attachments

Fetch the task's comments via get_comments(task). List attachments by name. For each non-image attachment (anything not image/* by mime type or by .png/.jpg/.jpeg/.gif/.webp extension), download its contents through the task-manager interface and include the body in the task context. Image attachments stay as references the user can inspect — do not download images.

Also scan the task description and comments for links to external tools (design files, documents, specs, etc.). For each link found, invoke the appropriate MCP or tool to fetch its content and include it in the context bundle passed to the downstream skill in Step 10.

Step 6: Check for Existing Work

Before creating a branch, check if work already exists for this task ID. See references/git-workflow.md for the detection commands.

If a branch or PR exists, offer to resume or start fresh. If resuming, check out the existing branch and skip creation.

Step 6a: Ask About Worktree (BLOCKING)

Before creating the branch, ask the user whether to use a git worktree. This is a blocking question — wait for an explicit answer before proceeding.

Present the choice:

Would you like to work in a git worktree (isolated copy of the repo) or directly in the current directory?

• Worktree (recommended for parallel work — keeps main directory clean)
• Current directory

If the user chooses worktree, create an isolated copy using the first available option in this order: (1) a native worktree tool if the agent provides one (e.g. EnterWorktree, WorktreeCreate, a /worktree command, or a --worktree flag), (2) otherwise git worktree add <path> -b <branch> directly, where <path> is anchored to the main repo root (a sibling of it, e.g. "$(git worktree list --porcelain | awk '/^worktree /{print $2; exit}')/../<repo>-<task-id>") — never a cwd-relative path, so it can't nest inside another worktree. Then inspect the project for its documented setup instructions and follow them — the project's CLAUDE.md, README, or a dedicated setup script (e.g. scripts/setup-worktree.sh) should describe what's needed. If no setup instructions exist, tell the user and suggest they add a scripts/setup-worktree.sh to their project documenting how to bootstrap a new worktree (install deps, copy env files, start local services, etc.).

The branch will be created inside the worktree in Step 7.

Step 6b: Confirm Base Branch (BLOCKING)

Ask the user which branch to base the new branch on. This is a blocking question — wait for an explicit answer before proceeding.

Present the choice:

Which branch should <task-id>/<slug> be based on?

• main (default — latest stable base)
• Another branch (enter branch name)

Default to main only after the user confirms. If the user specifies a different base branch, use that instead. Record the chosen base branch for Step 7.

Step 7: Create Feature Branch

Create a branch using the task ID and a slug from the task name. Use the base branch confirmed in Step 6b (not assumed main). Inform (do not ask) when creating. See references/git-workflow.md for commands and naming convention.

Step 8: Create Draft PR

Immediately after creating the branch, create an empty commit and a draft PR to establish the GitHub ↔ task link from minute one.

1. Create an empty commit so the branch can be pushed:

   git commit --allow-empty -m "<task-id> :: <task-name-slug> (start)"
   

2. Push the branch:

   git push -u origin $(git branch --show-current)
   

3. Create the draft PR:

   gh pr create --draft --title "<TASK-ID> :: <description>" --body "$(cat <<'EOF'
   ## Task
   <task-url>
   EOF
   )"
   

4. Capture the draft PR URL — it will be included in the start comment and threaded through to ship-it.

Step 9a: Move to In Progress

This happens automatically — no permission needed.

Move the task to "In Progress" via set_status(task, "In Progress"). Skip if already there. If the move fails, report why but do not block the workflow — proceed to Step 9b.

Step 9b: Post Start Comment

This happens automatically — no permission needed.

Post a start comment on the task with the branch name and draft PR URL via add_comment(task, body). Deduplicate by checking for an existing 🏁 comment for this branch (via get_comments(task)). See references/task-patterns.md for the comment format.

Step 10: Route to the Right Workflow

Compile full task context (name, notes, custom fields, task ID, subtasks, comments, attachment names, downloaded contents of non-image attachments, fetched external resource content from Step 5, branch name) and route based on Category custom field:

If fast_mode — skip all skill routing regardless of category. Implement the solution directly in this conversation using built-in tools (Read, Edit, Bash, Grep, etc.). Do not invoke implement-feature, fix-bug, or any QA skill. Skip Step 11 (QA sub-flow) entirely and proceed to Step 12 when done.

Otherwise:

• "Bug" — Follow the QA sub-flow: verify → fix → verify loop.
• Anything else (Feature Request, Tech Debt, etc.) — invoke cortex-workflow:implement-feature with the full context bundle and the workflow_choice flag (if set). It detects an attached implementation plan, resolves the development skill for the current runtime via plugins/cortex-workflow/references/runtime-bindings.md, asks the operator when more than one approach applies, and returns here when implementation is complete.
• Category missing — Prompt: "Is this a bug fix or a feature?" then apply the routing above.

The branch is already created and checked out — the downstream skill works on it directly.

Step 11: QA Sub-flow

Run the QA sub-flow for the task's category. Resolve the QA skill (web-qa / mobile-qa / none) per plugins/cortex-workflow/references/qa-routing.md → "Resolving the QA Skill". That reference is the shared resolve logic; this section is the enforcement contract.

In fast mode the sub-flow is skipped entirely. Mark every QA row in the checkpoint as skipped with reason fast mode (via checkpoint.sh skip).

Bug path — invoke, don't infer

The bug sub-flow (QA: Resolve → QA: Investigate Bug → QA: Fix Bug → QA: Verify Fix) runs only by invoking the respective skills. Runtime evidence from those invocations is what the sub-flow produces. Do not substitute reasoning for invocation:

• ❌ "I read the code and see the bug" — invoke the QA skill in investigate mode for reproduction evidence.
• ❌ Inlining a fix directly — invoke fix-bug so it passes through systematic-debugging + TDD.
• ❌ "Tests pass so the fix works" — invoke the QA skill in verify mode; runtime replay of the original repro is the evidence.

No runtime evidence = the row is not complete. See references/qa-routing.md for the exact invocation sequence of each sub-step.

When QA: Verify Fix passes — proceed to Step 12. Step 11 is only done when execution has advanced; do not end the session after the QA loop completes.

Non-bug path — exact prompt, no substitution

After the development workflow returns, ask the operator using this exact wording. Do not rephrase, do not inline into another question, do not substitute an approval prompt:

"Implementation is complete. The changes can be visually verified before shipping — I'll build, deploy to the simulator/browser, and check the affected flows. A screenshot or video will be uploaded to the task as proof of completion.

Run QA verification? [yes / skip]"

Wait for the operator's answer. This is a HARD GATE — auto mode's "minimize interruptions" directive does NOT override. Skip asking only if the operator passed skip QA in start-task arguments or said "skip QA" / "run QA" earlier in the conversation as a direct utterance.

Anti-patterns:

• ❌ "Do you approve this for ship?" — this is a verification offer, not an approval question. A "yes" to ship-approval does NOT count as a "yes" to run QA.
• ❌ Self-generated static checklist ("Package.resolved has correct versions", "Build succeeded", "Tests pass") substituting for the QA skill invocation. These are pre-conditions the model already knows; they are not visual verification evidence.
• ❌ Inferring a "yes" from a prior answer to any different question. If the prior answer wasn't to this exact prompt (or to skip QA / run QA), re-ask.

If yes → invoke the resolved QA skill with a summary of what was built. The QA skill posts ✅ QA Verification — Feature Complete to the task with evidence. Only the QA skill's actual posting counts as evidence; a model-generated claim that QA passed does not. After the QA skill returns with a posted comment — proceed to Step 12. Do not end the session at Step 11.

If skip → proceed to Step 12. pre-ship-check will offer one more chance at ship time if no QA evidence is found on the task.

Step 12: Ship It

This step runs after the bug QA verify loop (for bugs) or the non-bug QA verification (for non-bugs) completes — or when the operator skips QA. Do not wait for the user to ask.

Invoke ship-it. The following context is already in this session — pass it through, do not re-ask:

What	Source
Task handle	Resolved in Step 2 (find_task)
Task URL	Provided in $ARGUMENTS
Task ID	From task fields (Step 2)
Branch name	Created in Step 7
Draft PR URL	Captured in Step 8

ship-it will run pre-ship-check, generate a work summary, promote the draft PR to ready, move the task to "In Review" (via set_status(task, "In Review")), and post a completion comment.

After ship-it returns successfully, delete ~/.cortex/cortex-workflow/checkpoints/<task-ref>.md (via checkpoint.sh delete <task-ref>). Post-ship work (code-review fixes, follow-up commits) is out of scope for this checkpoint — see references/checkpoints.md → "Lifecycle End".

Pause Flow

Triggered either by a step going into State = blocked during the flow or by the operator saying "park this", "I'm blocked", "pause task", or similar. Commits WIP, drafts a blocking question for user approval, posts a comment via the task-manager interface (@mentioning the blocker), updates the checkpoint, and pushes. See references/checkpoints.md → "Pause Flow" for the full sequence and references/task-patterns.md for the comment formats.

Important Notes

• This skill orchestrates the full lifecycle: start → develop → ship. It hands off to ship-it when development is done.
• Include the task ID in branch names and commit messages for traceability.
• Route all task operations through the task-manager interface — never call a provider's API directly.

Reference Files

• references/skill-dependencies.md — External plugin dependencies, install commands, check instructions
• references/validation-rules.md — Sprint-readiness checks, failure display, skip rules
• references/task-patterns.md — comment templates posted via the task-manager interface
• references/git-workflow.md — Existing work detection, branch creation, naming convention
• references/checkpoints.md — Checkpoint file format, initialization, per-step updates, resume flow, lifecycle end, edge cases
• plugins/cortex-workflow/references/qa-routing.md — QA skill resolution and the QA sub-flow (plugin-level shared reference with pre-ship-check)