mcp-status.md

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

• Use MCP tools to fetch story by

  {TASK_KEY}

• If story doesn't exist, STOP and report error: "Story {TASK_KEY} not found"

• Clear description or user story format
• At least 3-5 acceptance criteria
• Context about the problem being solved
• If story lacks sufficient detail, STOP and ask user for clarification before proceeding.

• Create Spec when: New feature domain, architectural patterns, API contracts, data models, cross-team dependencies
• Create Plan when: Bug fix, task-level implementation details, transient work
• Both when: Feature needs permanent spec AND task needs implementation plan
• If unclear, ask user: "Should I create a Spec (permanent) or Plan (transient)?"

• Fetch story from issue tracker using MCP:
  • Use

    mcp_atlassian_getJiraIssue

    for Jira issues
  • Use

    mcp_github_issue_read

    for GitHub Issues
  • Extract: title, description, acceptance criteria, labels, priority, related issues
• Parse user story format:
  • Identify user persona ("As a...")
  • Extract goal ("I want...")
  • Understand benefit ("so that...")
  • If not in user story format, extract requirements from description
• Extract acceptance criteria:
  • Look for numbered lists, checkboxes, or "Given/When/Then" format
  • Convert each criterion into a testable requirement
  • If no acceptance criteria found, STOP and ask user to provide them.
• Identify technical requirements:
  • Parse technical constraints from description
  • Note any dependencies mentioned
  • Identify performance or security requirements
• Check for missing information:
  • Is the problem clearly defined?
  • Are acceptance criteria specific and testable? (Minimum 3-5 criteria)
  • Is the scope clear?
  • Does it follow user story format or have clear requirements?
  • If critical information is missing, STOP and ask specific questions to fill gaps.
  • Reference: See

    create-task.md

    for detailed validation criteria
• Extract keywords for ASDLC pattern queries:
  • Parse story title and description for domain terms (nouns, technical terms)
  • Identify keywords: authentication, security, testing, review, spec, plan, etc.
  • Map keywords to ASDLC pattern search terms:
    • "authentication", "security" → search for "security", "specs", "contracts"
    • "spec", "plan" → search for "the-spec", "the-pbi", "living-specs"
    • "review", "code review" → search for "adversarial-code-review", "constitutional-review"
    • "test", "testing" → search for "behavior-driven-development", "gherkin"
  • Use story labels if available (e.g., "asdlc-alignment" → search for ASDLC patterns)
  • Store keywords for use in Step 2.5

• Use codebase_search to find similar implementations:
  • Search for similar features or patterns
  • Example: "How is file watching implemented?" or "Where is user authentication handled?"
  • Review 3-5 similar implementations to understand patterns
• Identify affected components:
  • Use

    codebase_search

    to find related modules/components
  • Use

    grep

    to find specific patterns, functions, or classes
  • Review directory structure to understand organization
• Review existing patterns:
  • How are similar features structured?
  • What testing patterns are used?
  • What naming conventions are followed?
  • How are errors handled?
• Identify files to examine:
  • Main implementation files
  • Test files (look for

    *.test.ts

    ,

    *_test.py

    ,

    *Test.java

    , etc.)
  • Configuration files
  • Documentation files
• Review related test files:
  • Understand test structure and patterns
  • Note test utilities and helpers
  • Identify test coverage expectations
• If codebase analysis reveals blockers or unclear patterns, note them in the plan for discussion.

• For Specs: Design Blueprint + Contract structure
  • Blueprint:
    • Context: Why does this feature exist? What problem does it solve?
    • Architecture: API contracts, data models, dependencies, dependency directions
    • Anti-Patterns: What agents must NOT do (with rationale)
  • Contract:
    • Definition of Done: Observable success criteria (checkboxes)
    • Regression Guardrails: Critical invariants that must never break
    • Scenarios: Gherkin-style (Given/When/Then) behavioral specifications
• For Plans: Design task-level implementation steps
  • Break down into subtasks (3-7 logical units)
  • Identify files to create/modify
  • Plan test strategy
  • Document dependencies
• Identify files to create/modify:
  • List new files to create (with paths)
  • List existing files to modify (with specific changes)
  • Group by component/module
• Plan database changes (if applicable):
  • Schema changes
  • Migration scripts
  • Data model updates
• Design API changes (if applicable):
  • New endpoints
  • Modified endpoints
  • Request/response formats
  • Error handling
• Plan test strategy:
  • Unit tests for each component
  • Integration tests for workflows
  • Test data requirements
  • Mock/stub requirements
• Document dependencies:
  • External libraries needed
  • Internal dependencies
  • Order of implementation
• Plan error handling:
  • Error scenarios to handle
  • Error messages and codes
  • Logging requirements

Option A: Generate Spec Document

• Check if spec already exists:
  • Ask user for

    {FEATURE_DOMAIN}

    (kebab-case feature name)
  • Check if

    specs/{FEATURE_DOMAIN}/spec.md

    exists
  • If exists, ask: "Spec exists. Update existing or create new?"
• Create spec directory and file:
  • Create directory:

    specs/{FEATURE_DOMAIN}/

  • Create file:

    specs/{FEATURE_DOMAIN}/spec.md

• Write spec using Blueprint + Contract structure:
  markdown

  # Feature: {Feature Name}
  
  > **ASDLC Pattern**: [The Spec](https://asdlc.io/patterns/the-spec/)
  > **Status**: Active | Deprecated | Superseded
  > **Last Updated**: YYYY-MM-DD
  
  ---
  
  ## Blueprint
  
  ### Context
  [Why does this feature exist? What business problem does it solve?]
  
  ### Architecture
  - **API Contracts**: Endpoints, request/response formats
  - **Data Models**: Schemas, validation rules, data structures
  - **Dependencies**: What this depends on, what depends on this
  - **Dependency Directions**: Inbound/outbound relationships
  
  ### Anti-Patterns
  - [What agents must NOT do, with rationale]
  - [Forbidden approaches that were considered and rejected]
  
  ---
  
  ## Contract
  
  ### Definition of Done
  - [ ] [Observable success criterion 1]
  - [ ] [Observable success criterion 2]
  - [ ] [Observable success criterion 3]
  - [ ] [Automated verification: tests pass, lint passes, builds successfully]
  
  ### Regression Guardrails
  - [Critical invariant that must never break]
  - [Performance targets that must be maintained]
  - [Security requirements that must hold]
  
  ### Scenarios
  **Scenario: {Scenario Name}**
  - **Given**: [Precondition]
  - **When**: [Action]
  - **Then**: [Expected outcome]
  
  [Additional scenarios as needed]

• Post spec summary to issue tracker:
  • Comment should include:
    • Link to spec file:

      specs/{FEATURE_DOMAIN}/spec.md

    • Brief summary of Blueprint (Context, Architecture)
    • Brief summary of Contract (Definition of Done, key scenarios)
  • If posting fails, note it but don't stop - spec file creation is the primary goal.

Option B: Generate Plan Document (for transient task-level work)

• Create plan file at

  .plans/{TASK_KEY}-{kebab-case-description}.plan.md

  :
  • First, check if file already exists (optional - for information only):
    • Use

      glob_file_search

      with pattern:

      **/.plans/{TASK_KEY}-*.plan.md

    • If files found, note them but proceed with creation (overwriting is acceptable for plan updates)
  • Use kebab-case for description (e.g.,

    PROJ-123-user-authentication.plan.md

    )
• Write plan using the following structure:
  markdown

  # {Story Title} ({TASK_KEY})
  
  ## Story
  [User story format or description]
  
  ## Context
  [Background information, why this is needed, related issues]
  
  ## Scope
  ### In Scope
  - [What is included]
  
  ### Out of Scope
  - [What is explicitly excluded]
  
  ## Acceptance Criteria
  1. [Criterion 1]
  2. [Criterion 2]
  3. [Criterion 3]
  ...
  
  ## Technical Design
  ### Architecture
  [High-level design approach]
  
  ### Components
  - Component 1: [Description]
  - Component 2: [Description]
  
  ### Data Model
  [If applicable: database schema, data structures]
  
  ### API Design
  [If applicable: endpoints, request/response formats]
  
  ## Implementation Steps
  1. **Subtask 1**: [Description]
     - Files to create: `path/to/file1.ts`
     - Files to modify: `path/to/file2.ts`
     - Tests: `path/to/file1.test.ts`
  
  2. **Subtask 2**: [Description]
     ...
  
  ## Testing
  ### Unit Tests
  - [Test cases for component 1]
  - [Test cases for component 2]
  
  ### Integration Tests
  - [Integration test scenarios]
  
  ### Test Data
  - [Test data requirements]
  
  ## Dependencies
  - [External libraries]
  - [Internal dependencies]
  
  ## Referenced ASDLC Patterns
  
  [If ASDLC patterns were discovered during analysis (Step 2.5), include them here]
  
  The following ASDLC patterns are relevant to this implementation:
  
  - **[{Pattern Title}](https://asdlc.io/patterns/{slug}/)** - {Brief description from search results}
  - **[{Pattern Title}](https://asdlc.io/practices/{slug}/)** - {Brief description}
  
  [If no patterns found or ASDLC MCP unavailable, omit this section or note: "No ASDLC patterns identified for this task."]
  
  ## Status
  - [ ] Story analyzed
  - [ ] Codebase reviewed
  - [ ] Technical design complete
  - [ ] Implementation steps defined
  - [ ] Testing strategy defined
  - [ ] Ready for implementation

• Verify plan file was created successfully
• Post plan summary to issue tracker:
  • Sequence:
    1. Fetch issue to verify it exists:

       mcp_atlassian_getJiraIssue

       or

       mcp_github_issue_read

    2. Create comment with plan summary:

       mcp_atlassian_addCommentToJiraIssue

       or

       mcp_github_add_issue_comment

    3. Verify comment was posted (optional - check issue comments)
  • Comment should include:
    • Link to plan file:

      .plans/{TASK_KEY}-*.plan.md

    • Brief summary of approach
    • Key implementation steps (3-5 bullets)
  • If posting fails, note it but don't stop - plan file creation is the primary goal.

• Context: Business problem and solution rationale
• Architecture: API contracts, data models, dependencies, dependency directions
• Anti-Patterns: Forbidden approaches with rationale

• Definition of Done: Observable, testable success criteria (checkboxes)
• Regression Guardrails: Critical invariants that must never break
• Scenarios: Gherkin-style (Given/When/Then) behavioral specifications

• Files to create:

  src/auth/config.ts

• Tests:

  src/auth/config.test.ts

• Files to create:

  src/auth/service.ts

• Tests:

  src/auth/service.test.ts

• Files to create:

  src/auth/session.ts

• Tests:

  src/auth/session.test.ts

• Files to create:

  src/auth/middleware.ts

• Tests:

  src/auth/middleware.test.ts

• Files to modify:

  src/routes/auth.ts

• Tests:

  src/routes/auth.test.ts

• MCP Tool Usage: Check schema files, validate parameters, handle errors gracefully
• Safety Limits: Never commit secrets, API keys, or sensitive data in documents
• 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

specs/{FEATURE_DOMAIN}/spec.md

• Feature domains are conceptual groupings (e.g.,

  user-authentication

  ,

  payment-processing

  )
• Ask user for feature domain name if unclear

.plans/{TASK_KEY}-{kebab-case-description}.plan.md

• Example:

  PROJ-123-user-authentication.plan.md

• Spec must include: Feature header, Blueprint (Context, Architecture, Anti-Patterns), Contract (DoD, Guardrails, Scenarios)
• Plan must include: Story, Context, Scope, Acceptance Criteria, Technical Design, Implementation Steps, Testing, Dependencies, Status

• Spec = State (how feature works permanently)
• Plan = Delta (what changes for this task)
• Don't duplicate content between them

specs/{FEATURE_DOMAIN}/spec.md

• Blueprint: Context, Architecture, Anti-Patterns
• Contract: Definition of Done, Regression Guardrails, Scenarios
• Permanent living specification that evolves with code

.plans/{TASK_KEY}-{description}.plan.md

• Story details and context
• Technical design and architecture
• Step-by-step implementation guide
• Testing strategy
• Dependencies and status tracking
• Transient document discarded after merge

• Link to spec/plan file
• Brief approach summary
• Key sections or implementation steps