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 rel