Create Task

Overview

Create a task in the issue tracker with a specified type (epic, story, bug, task, etc.). The command adapts its workflow based on the task type.

Definitions

{TASK_KEY}: Issue/task identifier format that will be generated by the issue tracker (e.g., FB-6, PROJ-123, KAN-42). Used to reference the created task after creation.
{FEATURE_DOMAIN}: Kebab-case feature name identifying the functional area (e.g., user-authentication, payment-processing, notifications). Used to link PBIs to their corresponding Specs at specs/{feature-domain}/spec.md.
Task Types: Categories of work items supported by the issue tracker:
- Epic: High-level initiative or phase plan that contains multiple stories
- Story: User story or feature request representing a single piece of functionality
- Bug: Defect or issue that needs to be fixed
- Task: Technical work item or chore that doesn't fit into story/bug categories
- Subtask: Child task of another task
- Improvement: Enhancement request
- Spike: Research or investigation task
- Technical Debt: Code quality improvement task
Validation Thresholds: Information density scoring used to assess task information completeness (type-specific):
- 0-2 elements present: INSUFFICIENT (must ask for missing information, STOP creation)
- 3-4 elements present: MARGINAL (proceed with caution, note assumptions)
- 5+ elements present: SUFFICIENT (proceed confidently with creation)
Format Specifications: Command syntax styles supported:
- Natural Language Style: /create-task [type] [description or source] (e.g., /create-task story for user authentication)
- Explicit Flag Style: /create-task --type=[type] [description or source] (e.g., /create-task --type=story for user authentication)
- Type can be specified as first word before "for", "from", or colon, or via --type= flag
Epic Plan File: Plan document used for epic creation (e.g., .plans/phase-one.md, .cursor/plans/commands-improvement-plan.md). Plan files may be located in .plans/ or .cursor/plans/ directories depending on project conventions.

Prerequisites

Before proceeding, verify:

MCP Status Validation: Perform MCP server status checks (see mcp-status.md for detailed steps)
- Test each configured MCP server connection (Atlassian, GitHub, etc.)
- Verify all required integrations are authorized and operational
- If any MCP server fails validation, STOP and report the failure. Do not proceed.
- 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.
- Required MCP servers:
  - Atlassian MCP: Required for Jira task creation
  - GitHub MCP: Required for GitHub Issues task creation
Tracker Access Verification: Verify user has permission to create issues in the issue tracker
- Test by attempting to fetch tracker configuration or verify access
- Use mcp_atlassian_getAccessibleAtlassianResources for Jira
- Use a lightweight read-only GitHub MCP tool for GitHub (see Cursor Settings → Tools & MCP for exact names)
- If access denied, STOP and report: "Access denied to issue tracker. Please verify permissions."
Epic/Parent Verification (if creating child task):
- Verify parent epic or task exists (if linking to parent)
- Use mcp_atlassian_getJiraIssue for Jira or mcp_github_issue_read for GitHub
- If parent task doesn't exist, STOP and report: "Parent task {key} not found."
Epic Plan File Verification (if creating epic from file):
- Verify plan file exists at specified path (e.g., .plans/phase-one.md or .cursor/plans/phase-one.md)
- Use read_file or glob_file_search to locate plan file
- If plan file not found, STOP and report: "Epic plan file not found: {path}"

Usage

The command supports two syntax styles:

Natural Language Style

/create-task [type] [description or source]

Explicit Flag Style

/create-task --type=[type] [description or source]

Examples:

Natural Language:

/create-task story for user authentication
/create-task epic from phase-one.md
/create-task bug: login fails with OAuth
/create-task task: refactor auth service

PBI 4-part anatomy

Use this structure when generating Stories and Epics. Template: assets/pbi-anatomy.md — load when building PBI descriptions. Populate from user input and {feature-domain}; link to specs/{feature-domain}/spec.md (Blueprint and Contract). If spec is missing, use placeholders and warn.

Summary: (1) Directive — scope and constraints; (2) Context Pointer — spec#blueprint; (3) Verification Pointer — spec#contract; (4) Refinement Rule — Same-Commit Rule on divergence.

Task Types

Epic

High-level initiative or phase plan that contains multiple stories.

Usage:

/create-task --type=epic from [plan-file.md]
/create-task epic from [plan-file.md]
/create-task --type=epic [description]
/create-task epic: [description]

Workflow:

Read the epic plan (if from file)
- Review plan document (e.g., .plans/phase-one.md)
- Understand goals and scope
- Identify major tasks and milestones
Create the epic
- Generate epic title and description
- Set priority and labels
- Create epic in issue tracker
Break down into stories (optional, if plan contains tasks)
- Identify individual work items
- Create child stories for each task
- Link stories to parent epic
- Set priorities for each story

Epic Validation (Before Creation):

MCP status validation performed (see Prerequisites section)
Tracker access verified
Epic plan file exists and readable (if creating from file) - see Prerequisites section
Clear goals and objectives defined
Scope boundaries identified
Success criteria or key metrics specified
Major milestones or phases outlined
Business context or motivation provided
Information density score assessed (see Intelligent Information Validation section)

Epic Checklist:

Story

User story or feature request that represents a single piece of functionality.

Usage:

/create-task --type=story for [feature]
/create-task story for [feature]
/create-task --type=story [description]
/create-task story: [description]

Workflow:

Analyze the request
- Understand the feature scope and goals
- Identify acceptance criteria
- Determine priority level
Generate story details
- Write clear, descriptive title
- Create comprehensive description
- Define acceptance criteria
- Add relevant labels and tags
Create in issue tracker
- Create story with generated content
- Set appropriate priority
- Link to parent epic if applicable
- Leave unassigned in "To Do" status

Story Validation (Before Creation):

MCP status validation performed (see Prerequisites section)
Tracker access verified
User persona or user type identified
Clear value proposition ("so that...")
Acceptance criteria defined (3-5 criteria)
Feature scope is clear
Business context or motivation provided
Information density score assessed (see Intelligent Information Validation section)

Story Checklist:

Bug

Defect or issue that needs to be fixed.

Usage:

/create-task --type=bug [description]
/create-task bug: [description]
/create-task --type=bug for [description]
/create-task bug for [description]

Workflow:

Analyze the bug report
- Understand the problem and symptoms
- Identify reproduction steps
- Determine severity and priority
- Identify affected components/systems
Generate bug details
- Write clear, descriptive title
- Create detailed description
- Document reproduction steps
- Add expected vs actual behavior
- Include environment details if available
Create in issue tracker
- Create bug with generated content
- Set appropriate severity and priority
- Add relevant labels (e.g., "bug", component tags)
- Link to related stories/epics if applicable
- Leave unassigned in "To Do" status

Bug Validation (Before Creation):

MCP status validation performed (see Prerequisites section)
Tracker access verified
Problem clearly described (not just "it's broken")
Reproduction steps provided (or "cannot reproduce" noted)
Expected behavior specified
Actual behavior specified
Environment/context provided (browser, OS, version, etc.)
Impact or severity indicated
Information density score assessed (see Intelligent Information Validation section)

Bug Checklist:

Task

Technical work item or chore that doesn't fit into story/bug categories.

Usage:

/create-task --type=task [description]
/create-task task: [description]
/create-task --type=task for [description]
/create-task task for [description]

Workflow:

Analyze the task
- Understand the work to be done
- Identify technical requirements
- Determine priority and effort
Generate task details
- Write clear, descriptive title
- Create detailed description
- Document technical requirements
- Add relevant labels and tags
Create in issue tracker
- Create task with generated content
- Set appropriate priority
- Link to parent epic if applicable
- Leave unassigned in "To Do" status

Task Validation (Before Creation):

MCP status validation performed (see Prerequisites section)
Tracker access verified
Technical work clearly defined
Scope boundaries identified
Technical requirements or constraints specified
Success criteria or definition of done provided
Dependencies or prerequisites identified (if any)
Information density score assessed (see Intelligent Information Validation section)

Task Checklist:

Other Types

For any other task type (e.g., "subtask", "improvement", "spike", etc.), the command will:

Analyze the request
- Understand the work scope
- Identify requirements
- Determine priority
Generate task details
- Write clear, descriptive title
- Create comprehensive description
- Add relevant labels and tags
Create in issue tracker
- Create task with generated content
- Set appropriate priority
- Link to parent task if applicable
- Leave unassigned in "To Do" status

Steps

Pre-flight validation
- MCP Status Validation: Perform MCP server status checks (see mcp-status.md for detailed steps)
  - Test Atlassian MCP connection: mcp_atlassian_atlassianUserInfo
  - Test GitHub MCP connection: use a read-only GitHub MCP tool (see Cursor Settings → Tools & MCP)
  - If any MCP server fails validation, STOP and report the failure. Do not proceed.
- Tracker Access Verification: Verify user has permission to create issues
  - For Jira: Use mcp_atlassian_getAccessibleAtlassianResources to verify access
  - For GitHub: Use a read-only GitHub MCP tool to verify access (see Cursor Settings → Tools & MCP)
  - If access denied, STOP and report: "Access denied to issue tracker. Please verify permissions."
Parse command arguments
- Extract task type from command:
  - Check for --type= flag first (most explicit)
  - Look for type as first word before "for", "from", or colon
  - If no type specified, prompt user or default to "story"
- Extract description or source file:
  - Parse description text after type indicator
  - Extract source file path if "from [file]" pattern detected
- Validate task type is supported:
  - Check against supported types (epic, story, bug, task, subtask, improvement, spike, technical-debt)
  - Use mcp_atlassian_getJiraProjectIssueTypesMetadata for Jira to verify type is available
  - If task type is invalid or not supported, STOP and report: "Task type '{type}' is not supported. Supported types: {list}"
  - Suggest similar types if typo detected (e.g., "stroy" → "story")
  - Case-insensitive matching (e.g., --type=BUG = --type=bug)
Gather context (if applicable)
- Read source file if provided (for epic creation):
  - Use glob_file_search or list_dir to locate plan file (check both .plans/ and .cursor/plans/ directories)
  - Use read_file to read plan file content
  - If plan file not found, STOP and report: "Epic plan file not found: {path}"
- Check for related tasks/epics (if parent/linking mentioned):
  - Use mcp_atlassian_getJiraIssue for Jira or mcp_github_issue_read for GitHub
  - Verify parent task exists and is accessible
  - If parent task doesn't exist, STOP and report: "Parent task {key} not found."
- Review project conventions for task creation:
  - Use codebase_search or grep to find existing task examples if needed for context
  - Note any project-specific conventions (labels, components, custom fields)

3a. Determine feature domain (for stories and epics requiring PBI structure)

When to determine feature domain:
- Required for: Stories, Epics (PBI structure enforced)
- Optional for: Bugs, Tasks (simpler format acceptable)
Feature domain detection strategies (in order of preference):
1. Extract from user input:
  - Check if user specified feature domain explicitly (e.g., "for user-authentication feature")
  - Parse from command arguments
2. Extract from labels:
  - Look for label pattern: feature:{domain} → extract {domain}
  - Example: feature:user-authentication → user-authentication
3. Extract from epic/parent task:
  - If creating child story, inherit domain from parent epic
  - Use mcp_atlassian_getJiraIssue to fetch parent
  - Extract domain from parent's labels or description
4. Parse from title/description keywords:
  - Analyze task title and description for domain clues
  - Match against known domains (check existing specs in specs/ directory)
  - Example: "Add OAuth login" → suggest user-authentication
5. Ask user if ambiguous:
  - If multiple domains detected or domain unclear, present options
  - Ask: "Which feature domain? (e.g., user-authentication, payment-processing, notifications)"
  - Provide examples from existing specs if available
Validate feature domain format:
- Must be kebab-case (lowercase with hyphens)
- Pattern: [a-z]+(-[a-z]+)*
- Examples: user-authentication, payment-processing, skill-audit
- If invalid format, STOP and report: "Feature domain must be kebab-case (e.g., user-authentication)"
Check if spec exists:
- Use glob_file_search with pattern: **/specs/{feature-domain}/spec.md
- If spec exists:
  - Note: "✅ Spec found at specs/{feature-domain}/spec.md"
  - PBI will link to valid Blueprint and Contract sections
- If spec doesn't exist:
  - Warn: "⚠️ Spec not found at specs/{feature-domain}/spec.md. Consider creating spec with /create-plan {TASK_KEY}"
  - PBI will use placeholder links
  - Do NOT block task creation - proceed with placeholders
Store feature domain for PBI generation:
- Save domain for use in step 5 (issue description generation)

Validate task information (Intelligent Analysis)
- Analyze provided information intelligently:
  - Parse description/source for completeness
  - Detect vague language patterns (type-specific)
    - Epic: "improve system", "add features" without specifics
    - Story: Missing user persona, no "so that" value
    - Bug: "broken", "doesn't work" without details
    - Task: "refactor", "improve" without specifics
  - Assess information density using type-specific scoring:
    - Epic: Count elements: goals, scope, success criteria, milestones, context (target: 5+)
    - Story: Count elements: persona, acceptance criteria, value proposition, scope, context (target: 5+)
    - Bug: Count elements: problem, reproduction steps, expected vs actual, environment, impact (target: 5+)
    - Task: Count elements: work definition, technical requirements, scope, success criteria, constraints (target: 5+)
  - Identify missing critical elements (type-specific):
    - Epic: Goals, scope, success criteria, major milestones
    - Story: User persona, acceptance criteria, value proposition
    - Bug: Reproduction steps, expected vs actual, environment
    - Task: Technical requirements, scope, success criteria
- Decision logic based on information density score:
  - 0-2 elements present: INSUFFICIENT
    - STOP and ask specific questions
    - Generate 3-5 type-specific, actionable questions
    - Present questions with context explaining why information is needed
    - Wait for user response before proceeding
    - Do NOT create task with incomplete information
  - 3-4 elements present: MARGINAL
    - Proceed with caution, note assumptions in task description
    - Add clarifying comments about what assumptions were made
  - 5+ elements present: SUFFICIENT
    - Proceed confidently with creation
Validate task information (Intelligent Analysis)
- Analyze provided information intelligently:
  - Parse description/source for completeness
  - Detect vague language patterns (type-specific)
    - Epic: "improve system", "add features" without specifics
    - Story: Missing user persona, no "so that" value
    - Bug: "broken", "doesn't work" without details
    - Task: "refactor", "improve" without specifics
  - Assess information density using type-specific scoring:
    - Epic: Count elements: goals, scope, success criteria, milestones, context (target: 5+)
    - Story: Count elements: persona, acceptance criteria, value proposition, scope, context (target: 5+)
    - Bug: Count elements: problem, reproduction steps, expected vs actual, environment, impact (target: 5+)
    - Task: Count elements: work definition, technical requirements, scope, success criteria, constraints (target: 5+)
  - Identify missing critical elements (type-specific):
    - Epic: Goals, scope, success criteria, major milestones
    - Story: User persona, acceptance criteria, value proposition
    - Bug: Reproduction steps, expected vs actual, environment
    - Task: Technical requirements, scope, success criteria
- Decision logic based on information density score:
  - 0-2 elements present: INSUFFICIENT
    - STOP and ask specific questions
    - Generate 3-5 type-specific, actionable questions
    - Present questions with context explaining why information is needed
    - Wait for user response before proceeding
    - Do NOT create task with incomplete information
  - 3-4 elements present: MARGINAL
    - Proceed with caution, note assumptions in task description
    - Add clarifying comments about what assumptions were made
  - 5+ elements present: SUFFICIENT
    - Proceed confidently with creation
- For detailed validation patterns and examples, see "Intelligent Information Validation" section below
Execute type-specific workflow
- Follow the workflow for the specified task type:
  - Epic: Read plan file, create epic, optionally break down into stories
  - Story: Analyze request, generate story details, create story
  - Bug: Analyze bug report, generate bug details, create bug
  - Task: Analyze task, generate task details, create task
  - See "Task Types" section above for detailed workflows
- Generate appropriate content based on type:
  - Write clear, descriptive title
  - Generate description with PBI structure (for Stories and Epics):
    - Use the PBI 4-part anatomy — load assets/pbi-anatomy.md when building PBI descriptions (see "PBI 4-part anatomy" section above).
    - Populate 4-part anatomy:
      1. Directive Section:
        
        Extract what to do from user input/task description
        
        Define explicit scope boundaries (in scope / out of scope)
        
        Include constraints and dependencies
      2. Context Pointer Section:
        
        Use {feature-domain} determined in step 3a
        
        Generate link: ../../specs/{feature-domain}/spec.md#blueprint
        
        If spec exists: Link to real spec
        
        If spec missing: Use placeholder link + warning note
        
        Explain what's in Blueprint: Why, Architecture, Anti-Patterns
      3. Verification Pointer Section:
        
        Use same {feature-domain}
        
        Generate link: ../../specs/{feature-domain}/spec.md#contract
        
        If spec exists: Link to real Contract section
        
        If spec missing: Use placeholder link
        
        Explain what's in Contract: DoD, Guardrails, Scenarios
      4. Refinement Rule Section:
        
        Use the Refinement Rule from the PBI template (STOP / update spec same commit / flag review if architectural boundaries affected)
        
        Customize if specific review needs (e.g., security, performance)
    - Validate PBI structure:
      - Verify all 4 sections present
      - Verify links are well-formed
      - Verify feature domain is valid kebab-case
    - Fallback for Bugs/Tasks:
      - Use simpler description format (traditional format acceptable)
      - PBI structure optional but recommended
  - Define acceptance criteria (for stories)
  - Document reproduction steps (for bugs)
  - Add relevant labels and tags (include feature:{domain} label)
- Create task in tracker:
  - AGENTS.md Tier 1 (ALWAYS): Follow MCP tool usage standards - check schema files before invoking tools, validate required parameters, handle errors gracefully. See AGENTS.md §3 Operational Boundaries.
  - Use mcp_atlassian_createJiraIssue for Jira
    - Parameters: cloudId, projectKey, issueTypeName, summary, description, and other fields
  - Use mcp_github_create_issue for GitHub
    - Parameters: owner, repo, title, body, labels
  - Set appropriate priority
  - Link to parent epic/task if applicable
  - Add relevant labels/components
  - Leave unassigned in "To Do" status
  - If task creation fails, STOP and report the error with details
Verify creation
- Confirm task was created successfully:
  - Fetch created task using mcp_atlassian_getJiraIssue or mcp_github_issue_read
  - Verify all fields were set correctly
  - If task creation verification fails, report warning but don't fail (creation may have succeeded)
- Display task key/ID:
  - Extract task key/ID from creation response
  - Display in format: "Task created: {TASK_KEY}"
- Provide link to created task:
  - Generate URL: https://{site}.atlassian.net/browse/{TASK_KEY} for Jira
  - Generate URL: https://github.com/{owner}/{repo}/issues/{number} for GitHub
  - Display link to user

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_getAccessibleAtlassianResources - Get cloudId for Atlassian API calls
- Returns list of accessible resources with cloudId values
- Use to obtain cloudId before other Atlassian API calls
mcp_atlassian_getJiraIssue - Check if epic/parent exists or fetch task details
- Parameters: cloudId, issueIdOrKey = {TASK_KEY} or parent key
- Use to verify parent tasks exist before linking
mcp_atlassian_getJiraProjectIssueTypesMetadata - Get available issue types for a project
- Parameters: cloudId, projectIdOrKey = project key
- Use to validate task type is supported
mcp_atlassian_createJiraIssue - Create task in Jira
- Parameters: cloudId, projectKey, issueTypeName (e.g., "Story", "Bug", "Epic"), summary, description, additional_fields (for labels, components, parent, priority, etc.)
- Use to create the task after validation
mcp_atlassian_addCommentToJiraIssue - Add comments to issues (if needed)
- Parameters: cloudId, issueIdOrKey = {TASK_KEY}, commentBody = markdown text
- Use to add additional context or notes after creation

MCP Tools (GitHub)

A read-only GitHub MCP tool to verify connection (see Cursor Settings → Tools & MCP for exact names)
- Use to verify GitHub integration is operational
mcp_github_issue_read - Check if parent issue exists or fetch issue details
- Parameters: owner, repo, issue_number = issue number
- Use to verify parent issues exist before linking
mcp_github_create_issue - Create issue in GitHub
- Parameters: owner, repo, title, body (markdown description), labels (array)
- Use to create the issue after validation

Filesystem Tools

read_file - Read epic plan files
- Read plan files: .plans/phase-one.md, .cursor/plans/phase-one.md
- Parameters: target_file = path to file
- Use to read plan documents when creating epics from files. PBI template: assets/pbi-anatomy.md (see "PBI 4-part anatomy" section).
glob_file_search - Search for specs and plan files
- Find specs: Pattern **/specs/{feature-domain}/spec.md
- Find plans: Pattern **/.plans/*.md or **/.cursor/plans/*.md
- Parameters: pattern = glob pattern to search
- Use to check if spec exists for feature domain
- Use to locate plan files in various directories
list_dir - Explore directory structure to find plan files or existing specs
- Parameters: target_directory = directory to explore (e.g., .plans/, .cursor/plans/, specs/)
- Use to discover existing feature domains in specs/ directory
- Use to locate plan files in different directory structures
glob_file_search - Find plan files matching patterns
- Pattern: **/.plans/*.md, **/.cursor/plans/*.md
- Use to search for plan files when path is not fully specified

Codebase Tools

codebase_search - Find related context if needed
- Query: "How are tasks created in this project?" or "What labels are used for tasks?"
- Use to understand project conventions for task creation
grep - Find specific patterns in plan files or code
- Pattern: Task type names, label patterns, component names
- Use to identify project-specific conventions or patterns

Pre-flight Checklist

MCP status validation performed (see mcp-status.md)
All MCP servers connected and authorized
Tracker access verified (user can create issues)
Task type validated against supported types
Epic plan file exists and readable (if creating epic from file)
Parent task exists (if linking to parent)
Task information validated (sufficient detail for creation)
Missing information requested from user (if needed)

Type Detection

The command supports multiple ways to specify the task type:

Explicit Flag Style (Recommended for clarity):

/create-task --type=story for ...
/create-task --type=bug ...
/create-task --type=epic from ...

Natural Language Style:

/create-task story for ...
/create-task bug: ... (colon syntax)
/create-task epic from ...

Type Parsing Priority:

Check for --type= flag first (most explicit)
Look for type as first word before "for", "from", or colon
If no type specified, prompt user or default to "story"

Type Validation:

Validate type against supported task types for the tracker
Suggest similar types if typo detected (e.g., "stroy" → "story")
Case-insensitive matching (e.g., --type=BUG = --type=bug)

Common Task Types

epic - High-level initiative
story - User story or feature
bug - Defect or issue
task - Technical work item
subtask - Child of another task
improvement - Enhancement request
spike - Research or investigation
technical-debt - Code quality improvement

Note: Available types may vary by issue tracker. The command should adapt to the tracker's supported types.

Guidance

Role

Act as a Product Manager or Engineer responsible for creating well-defined tasks in the issue tracker. You are thorough, methodical, and ensure tasks have sufficient detail for the team to understand and implement them.

Instruction

Execute the create-task workflow to create tasks with proper validation and structure. This includes:

Performing prerequisite validation checks (MCP status, tracker access)
Parsing command arguments to extract task type and description
Gathering context (plan files, parent tasks, project conventions)
Validating task information using intelligent analysis to ensure sufficient detail
Executing type-specific workflows to generate appropriate content
Creating the task in the issue tracker with all required fields

Context

Tasks are created in issue trackers (Jira, GitHub Issues, Azure DevOps, etc.)
Different task types require different information and have different workflows
Tasks must have sufficient detail for team members to understand and implement them
MCP integrations provide access to issue trackers for task creation
Epic plan files may be located in .plans/ or .cursor/plans/ directories depending on project conventions
The command uses intelligent validation to detect vague or incomplete information before creation
PBI Structure: Stories and Epics use ASDLC PBI 4-part anatomy (Directive, Context Pointer, Verification Pointer, Refinement Rule)
Feature Domain: Kebab-case identifier linking PBIs to Specs at specs/{feature-domain}/spec.md
Spec Integration: PBIs reference permanent Specs (pointers, not containers)
ASDLC patterns: The PBI, Agent Constitution
ASDLC pillars: Factory Architecture (workflow), Standardized Parts (PBI anatomy, issue types)

Examples

ASDLC: The PBI — Task creation produces PBIs that reference Specs; Agent Constitution shapes issue types and fields.

Example 1: Epic from Plan File

Input: /create-task --type=epic from phase-one.md

Workflow:
1. Validate MCP connections and tracker access
2. Parse command: epic type, source file "phase-one.md"
3. Read plan file from `.plans/phase-one.md` or `.cursor/plans/phase-one.md`
4. Validate epic information (goals, scope, success criteria)
5. Create epic in Jira with title, description, labels
6. Optionally break down into stories if plan contains tasks

Output:
Task created: FB-10
Link: https://{site}.atlassian.net/browse/{TASK_KEY}

Example 2: Story Creation

Input: /create-task story for user authentication with OAuth2

Workflow:
1. Validate MCP connections and tracker access
2. Parse command: story type, description "user authentication with OAuth2"
3. Analyze description for completeness (persona, acceptance criteria, value)
4. Information density: 2/5 elements (INSUFFICIENT)
5. STOP and ask:
   - Which user persona is this for?
   - What are the acceptance criteria?
   - What value does this deliver?

After user provides details:
6. Validate updated information (now 5/5 elements - SUFFICIENT)
7. Generate story with title, description, acceptance criteria
8. Create story in Jira

Output:
Task created: FB-15
Link: https://{site}.atlassian.net/browse/{TASK_KEY}

Example 2a: Story with PBI Structure (NEW)

Input: /create-task story for OAuth login implementation

Workflow:
1. Validate MCP connections and tracker access
2. Parse command: story type, description "OAuth login implementation"
3. Determine feature domain:
   - Parse title: "OAuth login" → suggest "user-authentication"
   - Check existing specs: specs/user-authentication/spec.md ✅ EXISTS
   - Domain confirmed: user-authentication
4. Validate information (after user provides details): SUFFICIENT
5. Generate story with PBI structure (use template assets/pbi-anatomy.md):
   - Populate 4 sections with feature-domain = "user-authentication"
6. Create story in Jira with PBI description + label "feature:user-authentication"

Output:
Task created: FB-42
Link: https://{site}.atlassian.net/browse/{TASK_KEY}

Description (PBI format):
---
## Directive

Implement OAuth2 login flow with Google provider.

**Scope:**
- In scope: Login, logout, session management
- Out of scope: Registration, password reset, MFA

**Constraints:**
- Must use OAuth2 standard
- Session must persist 24 hours
- Failed attempts must be logged

---

## Context Pointer

See [Spec Blueprint](../../specs/user-authentication/spec.md#blueprint) for:
- **Why this feature exists** (secure user access)
- **Architecture** (OAuth2 flow, session storage, middleware)
- **Anti-Patterns** (don't store tokens in localStorage, don't skip CSRF protection)

---

## Verification Pointer

See [Spec Contract](../../specs/user-authentication/spec.md#contract) for:
- **Definition of Done** (login works, session persists, logout clears session, tests pass)
- **Regression Guardrails** (security requirements, performance targets)
- **Test Scenarios** (successful login, failed login, session expiry, logout)

---

## Refinement Rule

If implementation diverges from Spec:
1. STOP and document the divergence
2. Update Spec in same commit as code changes (Same-Commit Rule)
3. Flag for security review if auth boundaries affected

Example 3: Bug Report

Input: /create-task bug: login fails with Google OAuth on Chrome

Workflow:
1. Validate MCP connections and tracker access
2. Parse command: bug type, description "login fails with Google OAuth on Chrome"
3. Analyze description for completeness (reproduction steps, expected vs actual, environment)
4. Information density: 2/5 elements (INSUFFICIENT)
5. STOP and ask:
   - What are the reproduction steps?
   - What was the expected behavior?
   - What actually happened?
   - What environment details (Chrome version, OS)?

After user provides details:
6. Validate updated information (now 5/5 elements - SUFFICIENT)
7. Generate bug with title, description, reproduction steps, expected vs actual, environment
8. Create bug in Jira with severity and labels

Output:
Task created: FB-20
Link: https://{site}.atlassian.net/browse/{TASK_KEY}

Example 4: Task Creation

Input: /create-task task: refactor authentication service to use dependency injection

Workflow:
1. Validate MCP connections and tracker access
2. Parse command: task type, description "refactor authentication service to use dependency injection"
3. Analyze description for completeness (technical requirements, scope, success criteria)
4. Information density: 3/5 elements (MARGINAL)
5. Proceed with caution, note assumptions
6. Generate task with title, description, technical requirements
7. Create task in Jira

Output:
Task created: FB-25
Link: https://{site}.atlassian.net/browse/{TASK_KEY}
Note: Assumed scope includes only authentication service, not related services.

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 in task descriptions
- 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
MCP Validation Required: Do not proceed if MCP server validation fails. See mcp-status.md for validation steps.
Tracker Access Verification: Verify user has permission to create issues before proceeding.
Validation Before Creation: Always validate task information using intelligent analysis before creating tasks. Do NOT create tasks with insufficient information (0-2 elements).
Type-Specific Validation: Apply type-specific validation patterns (see "Intelligent Information Validation" section below).
Information Density Scoring: Use scoring logic (0-2: INSUFFICIENT, 3-4: MARGINAL, 5+: SUFFICIENT) to determine if task should be created.
STOP on Insufficient Information: If information is insufficient (0-2 elements), STOP and ask 3-5 type-specific questions. Do NOT proceed with creation.
Parent Task Verification: If linking to parent task, verify parent exists before creating child task.
Plan File Verification: If creating epic from file, verify plan file exists and is readable.
Task Type Validation: Validate task type against supported types for the tracker.
Leave Unassigned: Created tasks should be left unassigned in "To Do" status (not assigned to current user).
PBI Structure Required (Stories and Epics): Generate issue descriptions with ASDLC PBI 4-part anatomy:
- Directive (what to do, with scope boundaries)
- Context Pointer (link to Spec Blueprint)
- Verification Pointer (link to Spec Contract)
- Refinement Rule (protocol for handling divergence)
Feature Domain Detection: For Stories/Epics, determine feature domain using detection strategies (labels, parent, title parsing, or ask user).
Feature Domain Format: Must be kebab-case (e.g., user-authentication, payment-processing).
Spec Validation: Check if spec exists at specs/{feature-domain}/spec.md. Warn if missing but don't block creation.
PBI structure (Stories/Epics): Use the PBI template at assets/pbi-anatomy.md; populate with task-specific content.
Feature Label: Add label feature:{domain} to Stories/Epics for domain tracking.

Existing Standards (Reference):

MCP status validation: See mcp-status.md for detailed MCP server connection checks
Validation logic: See "Intelligent Information Validation" section below for detailed validation patterns and examples
Plan file format: See create-plan.md for plan file structure
Epic breakdown: See decompose-task.md for breaking down epics into stories
PBI structure: Template at assets/pbi-anatomy.md (see "PBI 4-part anatomy" section)
Spec Structure: See specs/README.md for Blueprint + Contract format
ASDLC Patterns: The PBI (4-part anatomy), The Spec (permanent pointer target)

Output

Created Task: Task created in issue tracker with:
- Task key/ID (e.g., FB-10, PROJ-123)
- Link to task in tracker
- All required fields populated (title, description, type, priority, labels, etc.)
- Status: "To Do" (unassigned)
Validation Feedback (if information was insufficient):
- Clear explanation of what information is missing
- 3-5 type-specific questions to gather missing information
- Request to provide additional information before proceeding
Assumption Notes (if information was marginal):
- Notes about assumptions made during creation
- Recommendations for additional details to add later

Intelligent Information Validation

Note: This validation logic is integrated into Step 4 of the workflow (see "Steps" section above). This section provides detailed patterns, examples, and scoring logic for reference.

The command uses intelligent analysis to validate task information before creation:

Type-Specific Validation Patterns

Epic Validation:

Detects vague goals: "improve system", "add features" without specifics
Requires: Clear objectives, defined scope, success criteria
Questions if missing: "What are the specific goals?", "What's in/out of scope?", "How will we measure success?"

Story Validation:

Detects missing user context: No persona, no "so that" value
Requires: User persona, acceptance criteria, value proposition
Questions if missing: "Which user persona?", "What's the acceptance criteria?", "What value does this deliver?"

Bug Validation:

Detects incomplete reports: "broken", "doesn't work" without details
Requires: Reproduction steps, expected vs actual, environment
Questions if missing: "What are the reproduction steps?", "What was expected vs actual?", "What environment?"

Task Validation:

Detects vague technical work: "refactor", "improve" without specifics
Requires: Technical requirements, scope, success criteria
Questions if missing: "What technical requirements?", "What's the scope?", "What's the definition of done?"

Information Density Scoring

Minimum viable information (type-specific):

Epic: 3+ of: goals, scope, criteria, milestones, context
Story: 3+ of: persona, criteria, value, scope, context
Bug: 3+ of: problem, steps, expected, actual, environment
Task: 3+ of: work, requirements, scope, criteria, constraints

Scoring logic:

0-2 elements present: INSUFFICIENT (must ask)
3-4 elements present: MARGINAL (proceed with caution, note assumptions)
5+ elements present: SUFFICIENT (proceed confidently)

Example Intelligent Interactions

Example 1: Vague Story

You: /create-task story for better UX

AI:
✓ Parsing command: story type detected
✓ Analyzing provided information...

Analysis:
- Description: "better UX" (vague, undefined)
- Missing: user persona, acceptance criteria, value proposition, scope
- Information density: 0/5 elements

⚠ Insufficient information. To create a proper story, I need:

1. Which user persona is this for? (e.g., new users, power users, mobile users)
2. What specific UX problems are we solving? (e.g., confusing navigation, slow load times)
3. What are the acceptance criteria? (e.g., user can complete task in < 30 seconds)
4. What value does this deliver? (e.g., reduce user frustration, increase conversions)

Please provide this information so I can create a well-defined story.

Example 2: Incomplete Bug

You: /create-task bug: login broken

AI:
✓ Parsing command: bug type detected
✓ Analyzing provided information...

Analysis:
- Description: "login broken" (too vague)
- Missing: reproduction steps, expected vs actual, environment
- Information density: 1/5 elements

⚠ Insufficient information. To create a proper bug report, I need:

1. What are the reproduction steps? (e.g., go to /login, enter credentials, click submit)
2. What was the expected behavior? (e.g., user should be logged in and redirected)
3. What actually happened? (e.g., error message appears, no redirect)
4. What environment? (e.g., Chrome 120, macOS, production)

Please provide this information so I can create a complete bug report.

Example 3: Well-Defined Story

You: /create-task story: As a mobile user, I want to save articles offline so that I can read them without internet

AI:
✓ Parsing command: story type detected
✓ Analyzing provided information...

Analysis:
- Contains: user persona (mobile user), value (read offline), clear goal
- Information density: 4/5 elements

✓ Sufficient information. Proceeding with story creation...