/start-task

Start Task

Determine task complexity and use appropriate workflow for efficient development.

Usage

/start-task <task-description>

Steps

0. Pre-Task Checklist

Before starting any new task:

**Context Recovery Check**:

• [ ] Check if `.beads/plans/active-plan.md` exists with `status: in-progress`
• [ ] If YES: An interrupted execution exists. Ask user: "There's an active plan from a previous session. Resume it or start fresh?"
• Resume → run `bd prime --work-type recovery` and pick up where execution stopped
• Start fresh → mark the old plan as `status: abandoned` and proceed normally

**Knowledge Priming (CRITICAL)**:

• [ ] Run BEADS prime: `bd prime --keywords "<task-keywords>" --work-type planning`
• [ ] Review MUST FOLLOW rules and GOTCHAS before proceeding
• [ ] Note any relevant patterns or decisions that constrain the approach

**PR Check**:

• [ ] Check if there are active PRs with pending comments
• [ ] Ask: "Before we start the new task, should we check if there are any PR comments to address?"
• [ ] If yes, run: `gh pr list --author @me --state open`
• [ ] Check each PR for new CodeRabbit comments

0.5. External Tools Check (informational only — never blocks the task)

Check if external AI tools (Codex, Gemini) are available for cost savings and cross-model review:

• Run the health check scripts to detect installed tools:

  command -v codex >/dev/null 2>&1 && echo "codex: available" || echo "codex: not found"
  command -v gemini >/dev/null 2>&1 && echo "gemini: available" || echo "gemini: not found"

• **If tools are detected but `.metaswarm/external-tools.yaml` does not exist**: Suggest the user enable them:

> "External tools (Codex/Gemini) are installed but not configured. Run `mkdir -p .metaswarm && cp templates/external-tools.yaml .metaswarm/` to enable cost-saving delegation."

• **If no tools are detected**: Briefly mention they can be installed:

> "Optional: Install Codex and Gemini CLIs for cost savings and cross-model review — see `templates/external-tools-setup.md`."

• **If tools are configured and working**: No message needed — proceed silently.

This check is informational only. Always proceed to the task regardless of the result.

1. Task Assessment

**Use extended thinking** to analyze the task complexity before asking the user.

Consider:

• Number of files likely to be modified
• Whether database changes are needed
• Impact on existing functionality
• Testing requirements
• Integration points

Then ask the user to confirm your assessment:

> **Proposed complexity**: [Simple / Complex] - Does this match your expectation?

**Simple Task (streamlined flow):**

• Bug fixes
• Small UI tweaks
• Minor text/copy changes
• Simple configuration updates
• Adding basic validation
• Fixing linting/test issues

**Complex Task (full checklist + BEADS epic):**

• New features with database changes
• New API endpoints
• Complex UI components
• Background job modifications
• Onboarding flow changes
• Multi-file refactoring
• Performance optimizations

1.5. Problem Definition Phase

Before implementation, ensure the problem is well-defined:

**If a GitHub Issue exists:**

# Read the issue
gh issue view <number> --json title,body,labels,comments

# Extract and verify:
# - Clear scope (what's in, what's out)
# - Definition of Done items (verifiable acceptance criteria)
# - File scope (which files will be affected)
# - Human checkpoints (where should we pause for review?)

If the issue lacks DoD items or clear scope, ask the user to clarify before proceeding.

**If no GitHub Issue exists:**

• For **simple tasks**: No issue needed. Proceed directly.
• For **complex tasks**: An issue is ALWAYS needed. Ask the user:

> "This is a complex task. Should I create a GitHub Issue to track it?"

**If the problem is unclear:**

• Route to `superpowers:brainstorming` first to refine the idea into a design
• **MANDATORY HANDOFF**: After brainstorming commits a design document, you MUST:

1. STOP — do NOT proceed directly to `writing-plans` or implementation 2. Run the Design Review Gate (`/review-design` or invoke the `design-review-gate` skill) 3. Wait for all 5 review agents (PM, Architect, Designer, Security, CTO) to APPROVE 4. Only after ALL APPROVED, proceed to planning

• This handoff is required even if the brainstorming skill instructs you to invoke `writing-plans` next. The design review gate catches issues before expensive implementation begins.
• After design review approval, create a GitHub Issue from the refined design
• The issue should contain: scope, DoD items, file scope, human checkpoints

**Problem Definition outputs:**

• [ ] Clear scope (what's in, what's out)
• [ ] DoD items (enumerated, independently verifiable)
• [ ] File scope (which files will be affected)
• [ ] Human checkpoints (where to pause for review)

2. Simple Task Flow

If user confirms it's a simple task:

Essential Steps

• [ ] Read relevant docs if unfamiliar with area
• [ ] Check existing patterns for similar functionality
• [ ] Make the change following existing patterns
• [ ] Write/update tests if logic changes
• [ ] Run tests, lint, and build
• [ ] Create simple PR with clear description

3. Complex Task Flow

If it's a complex task:

• Create a BEADS epic: `bd create --title "<task>" --type epic --priority 2`
• Use the full task completion checklist
• Consider breaking into smaller tasks as BEADS sub-issues
• Use extended thinking for planning
• Create detailed implementation plan

Orchestrated Execution (for tasks with DoD items)

When the task has a spec with Definition of Done items, use the orchestrated execution pattern:

1. **Create implementation plan** — decompose into work units with DoD items, file scopes, dependencies 2. **Plan Review Gate (BLOCKING)** — submit plan to adversarial review (3 reviewers: Feasibility, Completeness, Scope & Alignment must all PASS). This gate is MANDATORY — do NO