start-task（开始任务）

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):

1. 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.

1. 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}.
2. Story in In Progress (or can be transitioned) and assigned to current user.

Steps

1. 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

1. 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)

1. 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

• MCP status validation performed (see mcp-status.md)
• All MCP servers connected and authorized
• Relevant docs checked (spec and/or plan)
• Spec read (if exists) - Blueprint and Contract sections
• Plan read (if exists) - implementation steps
• Story status is "In Progress"
• Story assigned to current user
• Feature branch created
• Branch checked out locally
• Work checklist posted to issue

Implementation Checklist

• Requirements understood (from spec/plan)
• Spec Blueprint reviewed for architectural constraints (if exists)
• Spec Contract reviewed for acceptance criteria (if exists)
• Anti-Patterns from Spec identified (if exists)
• Codebase context reviewed
• Implementation in progress
• Code changes made
• Tests written (using Contract scenarios if spec exists)
• Spec updated if behavior changed (Same-Commit Rule)
• Documentation updated
• Changes ready for review and testing (uncommitted)

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:

1. Performing pre-flight validation checks
2. Setting up the development environment (branch creation, issue updates)
3. Implementing work according to the plan
4. 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):

1. 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

1. Read Spec First (if exists): Check for feature spec in specs/ and read Blueprint + Contract before implementation
2. Respect Anti-Patterns: If spec exists, do NOT implement forbidden approaches listed in Anti-Patterns section
3. Same-Commit Rule: If code changes API contracts, data models, or quality targets → update spec in same commit
4. Unit Tests Required: All new code must have corresponding unit tests. Use Contract scenarios from spec (if exists) for test cases.
5. No Automatic Commits: Do NOT commit changes automatically. Leave changes uncommitted for developer review and testing. Committing is handled by /complete-task.
6. 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

1. 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

1. Code Quality:

- Follow existing code patterns and conventions - Maintain or improve test coverage

1. 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

1. 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