Start Task

Overview

Begin development on a task with proper setup and pre-flight checks.

Definitions

{TASK_KEY}: Story/Issue ID from the issue tracker (e.g., FB-6, PROJ-123, KAN-42)
Branch Name Format: Use short format {type}/{TASK_KEY} (e.g., feat/FB-6, fix/PROJ-123)
- Short format is recommended: feat/FB-6 (not feat/FB-6-file-watching-workspace-commands)
- Important: Be consistent within a project - use the same format for all branches

Prerequisites

Before proceeding, verify (see Steps 1–2 for how):

MCP Status Validation: All required MCP servers connected and authorized. If any fail, STOP.
- MCP Tool Usage Standards: MCP tool usage should follow best practices (check schema files, validate parameters, handle errors gracefully). These standards are documented in AGENTS.md §3 Operational Boundaries if AGENTS.md exists, but apply universally regardless.
Spec or Plan exists: At least one of specs/{FEATURE_DOMAIN}/spec.md or .plans/{TASK_KEY}-*.plan.md. If neither, STOP and suggest /create-plan {TASK_KEY}.
Story in In Progress (or can be transitioned) and assigned to current user.

Steps

Pre-flight checks
- MCP Status Validation: Perform MCP server status checks (see mcp-status.md for detailed steps)
  - Test each configured MCP server connection
  - Verify all required integrations are authorized and operational
  - If any MCP server fails validation, STOP and report the failure. Do not proceed.
- Read relevant documents:
  - First, check for Spec: Look for related spec in specs/{FEATURE_DOMAIN}/spec.md
    - If feature spec exists, read Blueprint for architectural constraints and Anti-Patterns
    - Read Contract for Definition of Done and Regression Guardrails
    - Specs provide permanent context for how the feature works
  - Then, read Plan (if exists): Look for task plan at .plans/{TASK_KEY}-*.plan.md
    - Plan File Selection: If multiple files match the pattern .plans/{TASK_KEY}-*.plan.md:
      - Use the most recently modified file (check file modification time)
      - If modification time cannot be determined, use the first file found alphabetically
      - Report which file was selected: "Using plan file: {filename}"
    - Plans provide transient task-level implementation steps
    - If no plan and no spec exist, STOP and report error: "No plan or spec found for {TASK_KEY}. Run /create-plan {TASK_KEY} first."
- Verify story is in "In Progress"
  - Fetch story status using mcp_atlassian_getJiraIssue
  - If status is NOT "In Progress":
    1. Get available transitions using mcp_atlassian_getTransitionsForJiraIssue
    2. Find transition to "In Progress" status
    3. Transition using mcp_atlassian_transitionJiraIssue
    4. Verify transition succeeded
  - If transition fails or "In Progress" status not available:
    - STOP and report: "Story {TASK_KEY} cannot be moved to 'In Progress'. Current status: {status}. Available transitions: {list}"
- Confirm story is assigned to current user
Set up development environment
- Determine branch type prefix based on task type:
  - Story → feat/{TASK_KEY}
  - Bug → fix/{TASK_KEY}
  - Task/Chore → chore/{TASK_KEY}
  - Refactor → refactor/{TASK_KEY}
  - Default to feat/{TASK_KEY} if task type is unclear
- First, check if branch already exists:
  - Use mcp_github_list_branches to list existing branches
  - Or use run_terminal_cmd: git branch -a | grep {type}/{TASK_KEY}
  - If branch exists:
    - Ask user: "Branch {type}/{TASK_KEY} already exists. Use existing branch or create new one?"
    - If "use existing": Checkout existing branch
    - If "create new": Use different name or delete old branch first
- If branch doesn't exist:
  - Create locally: git checkout -b {type}/{TASK_KEY}
  - Or create on remote first: mcp_github_create_branch (if remote-first workflow)
- Add work checklist comment to issue (include the actual branch name created):
  - Timing: Post immediately after branch creation, before starting implementation
  - This provides visibility that work has begun
  - Include the actual branch name created (e.g., feat/FB-6)
Implement according to spec and plan
- Read and understand documents:
  - Spec (if exists): Review Blueprint for design constraints, read Contract for acceptance criteria
  - Plan (if exists): Review implementation steps, identify files to create/modify
  - Understand dependencies and order
- Analyze existing codebase:
  - Use codebase_search to find related code
  - Review similar implementations for patterns
  - Understand existing test structure
- Implement changes:
  - Create new files as specified
  - Modify existing files as needed
  - Follow existing code patterns and conventions
  - Respect Anti-Patterns from Spec (if spec exists)
- Write tests alongside code:
  - Create test files for new code
  - Update existing tests for modified code
  - Use Spec's Contract scenarios for test cases (if spec exists)
  - Ensure tests follow existing test patterns
- Update Spec if behavior changes:
  - If code changes API contracts, data models, or quality targets → update Spec
  - Spec updates must be committed in same commit as code changes (Same-Commit Rule)
  - See specs/README.md for when to update specs
- Leave changes uncommitted for review:
  - Do NOT commit changes automatically
  - Changes remain in working directory for developer review and testing
  - Developer can review, test, and commit changes manually or use /complete-task to commit and push

Tools

MCP Tools (Atlassian)

mcp_atlassian_atlassianUserInfo - Verify Atlassian MCP connection
Obtaining CloudId for Atlassian Tools:
- Method 1 (Recommended): Use mcp_atlassian_getAccessibleAtlassianResources
  - Returns list of accessible resources with cloudId values
  - Use the first result or match by site name
  - Only call if cloudId is not already known or has expired
- Method 2: Extract from Atlassian URLs
  - Jira URL format: https://{site}.atlassian.net/...
  - CloudId can be extracted from the URL or obtained via API
- Error Handling: If cloudId cannot be determined, STOP and report: "Unable to determine Atlassian cloudId. Please verify MCP configuration."
mcp_atlassian_getJiraIssue - Fetch story details by {TASK_KEY}
- Parameters: cloudId, issueIdOrKey = {TASK_KEY}
mcp_atlassian_getTransitionsForJiraIssue - Get available status transitions
- Parameters: cloudId, issueIdOrKey = {TASK_KEY}
mcp_atlassian_transitionJiraIssue - Transition issue to "In Progress" (if needed)
- Parameters: cloudId, issueIdOrKey = {TASK_KEY}, transition = {id: "transition-id"}
mcp_atlassian_addCommentToJiraIssue - Add work checklist comment to issue
- Parameters: cloudId, issueIdOrKey = {TASK_KEY}, commentBody = markdown checklist

MCP Tools (GitHub)

A lightweight read-only GitHub MCP tool to verify connection (see Cursor Settings → Tools & MCP for exact names; e.g. a list/read tool)
mcp_github_list_branches - List existing branches (check if branch already exists)
mcp_github_create_branch - Create new branch on remote
- Parameters: owner, repo, branch = {type}/{TASK_KEY}, from_branch = main (or default branch)

Filesystem Tools

glob_file_search - Find specs matching specs/{FEATURE_DOMAIN}/spec.md or plans matching .plans/{TASK_KEY}-*.plan.md
- Pattern for plans: **/.plans/{TASK_KEY}-*.plan.md
- Pattern for specs: **/specs/*/spec.md
read_file - Read spec/plan files and existing code
- Spec location: specs/{FEATURE_DOMAIN}/spec.md
- Plan location: .plans/{TASK_KEY}-{description}.plan.md
write - Create new files
search_replace - Modify existing files (including specs when behavior changes)
list_dir - Explore directory structure

Codebase Tools

codebase_search - Search for similar implementations, patterns, or related code
- Query: "How is [similar feature] implemented?"
- Query: "Where is [component] used?"
grep - Find specific patterns, functions, or classes
- Pattern: function names, class names, imports, etc.

Terminal Tools

run_terminal_cmd - Execute git commands
- git status - Check current branch and status
- git checkout -b {type}/{TASK_KEY} - Create and checkout new branch locally
- git branch - List branches
- Note: Committing changes is handled in /complete-task, not in this command

Pre-flight Checklist

Implementation Checklist

Guidance

Role

Act as a software engineer responsible for beginning development work on a task. You are methodical, thorough, and follow established development workflows and standards.

Instruction

Execute the start-task workflow to begin development on a specified task. This includes:

Performing pre-flight validation checks
Setting up the development environment (branch creation, issue updates)
Implementing work according to the plan
Following all established conventions and standards

Context

The task is tracked in an issue management system (Jira, Azure DevOps, etc.)
Specs may exist at specs/{FEATURE_DOMAIN}/spec.md with permanent feature contracts
Plans may exist at .plans/{TASK_KEY}-*.plan.md with transient task-level implementation steps
Specs define State (how feature works), Plans define Delta (what changes)
The task should already be in "In Progress" status and assigned to the current user
MCP integrations provide access to issue trackers and version control
The codebase has existing patterns, conventions, and architectural decisions that should be respected
Same-Commit Rule: If code changes behavior/contracts, update spec in same commit
ASDLC patterns: The Spec, The PBI, Context Gates
ASDLC pillars: Factory Architecture (command station), Quality Control (pre-flight gates)

Examples

ASDLC: Context Gates — MCP and plan checks act as input gates before implementation.

Example Branch Names:

feat/PROJ-123 (story/feature)
fix/PROJ-456 (bug fix)
chore/PROJ-789 (maintenance task)
refactor/PROJ-321 (refactoring)

Note on Commits: Changes are left uncommitted in this command. Use /complete-task to commit, push, and optionally create a PR when ready.

Example Issue Comment (Work Checklist):

## Work Checklist

- [ ] Plan reviewed
- [ ] Branch created: `feat/PROJ-123`
- [ ] Implementation in progress
- [ ] Code changes in progress
- [ ] Tests being written
- [ ] Documentation updated

Note: The branch name in the comment must match the actual branch name created (including the type prefix).

Constraints

Rules (Must Follow):

Operational Standards Compliance: This command follows operational standards (documented in AGENTS.md if present, but apply universally):
- MCP Tool Usage: Check schema files, validate parameters, handle errors gracefully
- Safety Limits: Never commit secrets, API keys, or sensitive data. Never commit changes automatically without user review.
- AGENTS.md Optional: Commands work without AGENTS.md. Standards apply regardless of whether AGENTS.md exists.
- See AGENTS.md §3 Operational Boundaries (if present) for detailed standards
Read Spec First (if exists): Check for feature spec in specs/ and read Blueprint + Contract before implementation
Respect Anti-Patterns: If spec exists, do NOT implement forbidden approaches listed in Anti-Patterns section
Same-Commit Rule: If code changes API contracts, data models, or quality targets → update spec in same commit
Unit Tests Required: All new code must have corresponding unit tests. Use Contract scenarios from spec (if exists) for test cases.
No Automatic Commits: Do NOT commit changes automatically. Leave changes uncommitted for developer review and testing. Committing is handled by /complete-task.
Branch Naming: Use short format: {type}/{TASK_KEY} (e.g., feat/FB-6, fix/PROJ-123)
- Determine type prefix from task type:
  - Story → feat/
  - Bug → fix/
  - Task/Chore → chore/
  - Refactor → refactor/
  - Default to feat/ if task type is unclear
- Example: Story FB-6 → feat/FB-6 (short format, not descriptive format)
- Important: Be consistent - use short format for all branches
Pre-flight Validation: Do not proceed if:
- MCP status validation fails (see mcp-status.md for validation steps - if any MCP server is not connected or authorized, STOP immediately)
- Neither spec nor plan exists (STOP and suggest running /create-plan {TASK_KEY} first)
- Story is not in "In Progress" status
- Story is not assigned to current user
Code Quality:
- Follow existing code patterns and conventions
- Maintain or improve test coverage
Documentation: Update relevant documentation when adding features or changing behavior

Existing Standards (Reference):

MCP status validation: See mcp-status.md for detailed MCP server connection checks
Spec guidance: See specs/README.md for when to update specs and Same-Commit Rule
Branch naming: Type prefix format ({type}/{TASK_KEY}) as shown in current workflow
Test requirements: Tests written alongside code (per Implementation Checklist)
Commit workflow: Changes are committed in /complete-task, not in this command
Issue workflow: Tasks transition through "To Do" → "In Progress" → "Code Review" → "Done"
ASDLC patterns: The Spec (permanent state), The PBI (transient delta)

Output

Development Work: Implement the work specified in spec/plan:
- Code changes implemented according to spec constraints and plan steps (left uncommitted for review)
- Unit tests created or updated alongside code (using Contract scenarios if spec exists)
- Spec updated if behavior/contracts changed (Same-Commit Rule)
- Documentation updated as needed
- Changes ready for developer review and testing
- Use /complete-task when ready to commit, push, and optionally create a PR