tasks

name	tasks
description	Breaks a spec and plan into small, ordered, self-contained tasks. Each task is completable in a single agent session with tests. Creates a GitHub issue and feature branch. Use when user says "break into tasks", "create tasks", "task breakdown", "decompose", "create issue", or after running /plan. Do NOT use without a spec and plan in context. Requires gh CLI authenticated and a Git repository.
allowed-tools	Read, Glob, Grep, Bash
argument-hint	[path to plan or plan content]
metadata	{"author":"roberto-ramirez","version":"1.0.0","category":"sdd","tags":["tasks","decomposition","github","sdd"]}

/tasks

You are breaking down the plan into executable tasks: Divide and conquer.

Each task must be self-contained and unambiguous. The agent should not need to make assumptions or search for missing context. If a task requires the agent to guess, it's not ready yet.

---

Input

You need the spec and plan from /spec and /plan. If they are not in context:

$ARGUMENTS

If $ARGUMENTS is empty and no spec/plan is in context, ask the user to paste them before continuing.

---

Step 1 — Verify prerequisites

gh auth status          # GitHub CLI authenticated
git remote -v           # Has a GitHub remote
git branch --show-current  # On a clean branch

If any check fails, report and stop.

---

Step 2 — Break the plan into tasks

From the plan, create an ordered task list. Each task must be:

• Self-contained: All context needed is embedded in the task description
• Single-session: Completable in one agent session (roughly one commit's worth of work)
• Testable: Produces a verifiable change with tests
• Ordered by dependency: Tasks that others depend on come first
• Parallelizable where possible: Note which tasks can run concurrently

Task format

### Task N: [imperative description]

**Depends on:** [task numbers, or "none"]
**Parallel:** [yes/no — can run alongside other tasks]

**What to do:**
1. [specific action]
2. [specific action]
3. [specific action]

**Acceptance criteria:**
- [ ] [testable criterion from spec]
- [ ] [testable criterion]
- [ ] Tests pass

**Files to create/modify:**
- `path/to/file` — [what changes]

Guidelines for good tasks

• A task should touch one concern. "Add the data model AND the API endpoint AND the tests" is too big. Split it.
• Each task should leave the codebase in a working state. No half-finished features.
• Include test writing in the same task as the feature it tests — don't separate "write code" from "write tests."
• If the plan has N steps, you likely need N±2 tasks. Don't inflate artificially.
• Check: is the agent creating unnecessary abstractions? Could 3 tasks become 2?

---

Step 3 — Present the task list for review

Show the complete task list, then use the AskUserQuestion tool to present an interactive approval prompt:

Task breakdown complete — N tasks identified.

  Task 1: [title]
  Task 2: [title] (depends on 1)
  Task 3: [title] (parallel with 2)
  ...

Parallelism: Tasks [X, Y] can run concurrently.
Estimated commits: N

• Question: "Task breakdown complete — N tasks identified. How do you want to proceed?"

• Header: "Task review"

• Options:

  1. Go — "Create the GitHub issue and branch"
  2. Go with comments — "Create the issue, but note my feedback for implementation"
  3. Request changes — "Revise the task breakdown based on my feedback"

• If the user selects Go: proceed to create the GitHub issue and branch.

• If the user selects Go with comments: read their feedback, carry it forward as context for implementation, and proceed to create the issue.

• If the user selects Request changes (or selects "Other" with feedback): revise the breakdown incorporating their feedback, then present the gate again.

Do NOT create the issue until the user approves the task breakdown.

---

Step 4 — Create GitHub issue

Once approved, create the GitHub issue with the full spec, plan, and task checklist.

All issue content — title, description, task names — must be written in English, regardless of what language the user, the spec, or the plan used. This is non-negotiable: GitHub issues are the shared contract across sessions and agents, and they must be unambiguous for any reader.

Issue title format

Use conventional commit style for the issue title:

<type>(<scope>): <imperative description>

• type: feat, fix, refactor, chore, perf, docs — same as conventional commits
• scope: the module, component, or area affected (e.g., auth, api, ui)
• description: imperative mood, lowercase, no period, under 70 characters

Examples:

• feat(auth): add OAuth2 login with Google and GitHub
• fix(checkout): prevent double-charge on concurrent submissions
• refactor(api): migrate REST endpoints to GraphQL schema

Issue body template

gh issue create \
  --title "<type>(<scope>): <imperative description — IN ENGLISH>" \
  --body "## Objective

<1-2 sentence summary of WHAT this feature/fix achieves and WHY it matters>

## Acceptance criteria

- [ ] Given [precondition], when [action], then [expected result]
- [ ] Given [precondition], when [action], then [expected result]
- [ ] All tests pass

## Architecture overview

<technical plan summary — architecture decisions, patterns, affected components>

\`\`\`mermaid
graph TD
    A[Component/Module affected] --> B[New/Modified component]
    B --> C[Downstream dependency]
    B --> D[Downstream dependency]
\`\`\`

> Replace with an actual architecture diagram showing the components involved
> and how they interact. Use flowchart for data/control flow, classDiagram for
> structural changes, or sequenceDiagram for interaction patterns.
> Omit this section if the change is trivial (e.g., single-file fix).

## Tasks

- [ ] Task 1: [title] — [brief what and why]
- [ ] Task 2: [title] — [brief what and why]
- [ ] Task 3: [title] — [brief what and why]

### Dependency graph

\`\`\`mermaid
graph LR
    T1[Task 1: title] --> T2[Task 2: title]
    T1 --> T3[Task 3: title]
    T2 --> T4[Task 4: title]
    T3 --> T4
\`\`\`

> Show task dependencies. Tasks without arrows between them can run in parallel.
> Omit if all tasks are sequential or there are fewer than 3 tasks.

## Context for implementers

- **Branch:** \`feat/<issue-number>-<short-kebab-name>\`
- **Key files:** \`path/to/main/file\`, \`path/to/other/file\`
- **Constraints:** [any technical constraints, API limits, backward compatibility, etc.]

## References

- Spec produced by: /spec
- Plan produced by: /plan" \
  --label "<feature|bug|chore>"

Diagram guidelines

Include Mermaid diagrams when they add clarity — not for every issue:

Include diagram when	Skip diagram when
Multiple components interact	Single-file change
Task dependencies are non-linear	All tasks are sequential
Data flows through multiple layers	Simple CRUD operation
Architecture changes affect boundaries	Cosmetic or config change

Capture the issue number and URL.

---

Step 5 — Validate repository and create the feature branch

Before creating the branch, confirm you are in the correct repository:

git remote get-url origin   # verify this is the expected repository

Show the remote URL to the user and ask them to confirm it is the correct repo before creating any branch. If the user's project has multiple repos (e.g., frontend and backend), this prevents creating branches in the wrong one.

Once confirmed, create the branch:

git checkout -b feat/<issue-number>-<short-kebab-name>

Where:

• <issue-number> is the GitHub issue number
• <short-kebab-name> is a 2-5 word kebab-case summary

---

Step 6 — Push the branch and link to the issue

Push the branch immediately so it is tracked on the remote and linked to the issue:

git push -u origin feat/<issue-number>-<short-kebab-name>

This ensures:

• The branch exists on the remote from the start (no "forgot to push" issues)
• Other agents or teammates can find it immediately
• The branch is associated with the issue early, not just at PR time

---

Step 7 — Confirm

✓ Tasks: N tasks defined
✓ Issue: #<number> — <title> (<URL>)
✓ Branch: feat/<number>-<name> (pushed to remote)
✓ Repository: <remote URL>

──────────────────────────────────────────────
Next steps:

  1. Run /clear  (fresh context for implementation)
  2. Enable auto-accept mode
  3. Run /implement  (paste the tasks if asked)
──────────────────────────────────────────────

---

Gotchas

These are common failure modes when breaking down tasks. Watch for them:

• Writing issues in the user's language instead of English. Even if the user writes the spec in Spanish, Portuguese, or any other language, the GitHub issue must be in English. Issues are the contract — they must be universally readable.
• Creating branches in the wrong repository. In multi-repo projects (e.g., frontend + backend), always verify git remote get-url origin before creating a branch. A branch in the wrong repo wastes time and causes confusion.
• Separating tests from implementation. "Task 3: Write tests for the new service" as a standalone task is wrong. Tests and implementation belong in the same task — that's how TDD works.
• Tasks that aren't self-contained. If a task says "continue from Task 2" or "using the service created in Task 1" without describing what that service does, the implementing agent will guess. Embed all needed context.
• Too many micro-tasks. If you have 12 tasks for a feature that touches 4 files, you've over-decomposed. The coordination overhead will exceed the benefit. Aim for 3-7 tasks for most features.
• Overlapping file ownership. Two tasks that both modify src/services/auth.ts will create merge conflicts when parallelized. Restructure so each task owns distinct files.
• Wrong dependency order. Data models and interfaces should come before the code that uses them. If Task 3 depends on Task 1's types but you didn't mark the dependency, the implementing agent will fail.
• Inflating tasks to match plan steps. Not every plan step needs its own task. If two plan steps touch the same file and make sense together, combine them.

---

Important constraints

• All GitHub issues must be in English. Title, description, task names, acceptance criteria — everything. Even if the user communicates in another language, translate to English for the issue. Issues are the cross-session contract.
• Verify the repository before creating branches. In multi-repo projects, confirm git remote get-url origin with the user. A branch in the wrong repo is worse than no branch at all.
• Push the branch immediately after creation. Don't wait until /ship. Early push ensures the branch is visible, trackable, and linked to the issue.
• Every task must be self-contained. If you remove all other tasks, a developer should still understand exactly what this one requires.
• Don't create busywork tasks. "Set up project structure" or "create boilerplate" are not tasks unless they involve real decisions.
• Tasks are the last checkpoint. After this, code gets written. Make sure the breakdown is pragmatic.
• The user must approve before creating the issue. The task breakdown is the contract.