AI-DLC Bolt Implementation

Guide the implementation of a bolt (rapid iteration cycle) with emphasis on Test-Driven Development (TDD). This skill helps developers execute focused, testable increments of work.

What is a Bolt?

A Bolt is the smallest iteration cycle in AI-DLC, typically lasting hours to days. It delivers a testable increment of functionality and follows the TDD rhythm: Red (write failing test) → Green (make it pass) → Refactor (improve code quality).

AI-Drives-Conversation Pattern

This skill follows the AI-DLC principle where AI initiates and directs the conversation:

•AI gathers — Collect context from Jira artifact and repository
•AI plans — Create TDD-focused implementation plan
•Human approves — Review and approve the plan
•AI executes — Create branch and begin implementation with progress tracking

Example Invocations

•"Start a bolt for PROJ-123"
•"Implement the authentication story"
•"Begin a bolt for the API endpoint task"
•"New bolt for the database migration"

References

•Use @${CLAUDE_PLUGIN_ROOT}/references/planning-shared.md for Bolt guidance and templates.

Workflow

Jira Status Management Utility

Throughout the Bolt workflow, use this utility pattern to transition Jira statuses with automatic fallback:

Function: transition_jira_status(issue_key, target_status, issue_type)

Strategy:

•Check if acli is available: which acli

•If available, use acli:

bash

acli jira workitem transition PROJ-123 --transition "In Progress"

•If acli fails or unavailable, fall back to MCP tools:

code

- Call getTransitionsForJiraIssue(PROJ-123)
- Find transition ID matching target_status name
- Call transitionJiraIssue(PROJ-123, {id: "21"})

Error Handling:

•Status already set → Log info, treat as success
•Invalid transition → Log warning, ask user to verify manually
•Network/auth failure → Log error, continue workflow (non-blocking)
•acli not installed → Silent fallback to MCP tools

Return Format:

json

{
  "success": true,
  "method": "acli",
  "message": "Transitioned BOLT-123 to In Progress",
  "previous_status": "To Do",
  "new_status": "In Progress"
}

Display results with indicators:

•✓ Success
•⚠ Warning (already in target state)
•✗ Failed (manual intervention needed)

Phase 1: Context Gathering

Step 1: Gather Jira Context

Ask for the work context:

•Jira artifact (Bolt/Story key, e.g., PROJ-123)

•Fetch the Jira issue using the acli CLI (preferred for lower token usage):

bash

# First check acli is installed
which acli || echo "acli not installed - see: https://developer.atlassian.com/cloud/acli/"

# Fetch the Bolt (Story) with relevant fields
acli jira workitem view PROJ-123 --fields summary,description,status,issuetype --json

# Fetch child Tasks (Sub-tasks) for context
acli jira workitem children PROJ-123 --json

•Extract acceptance criteria, description, and dependencies from the response
•Note the Tasks (Sub-tasks) that are part of this Bolt

Smart Status Sync:

After fetching Jira context, analyze current statuses and offer to transition to "In Progress":

•
Parse current statuses from JSON response:
- •Story status (e.g., "To Do", "In Progress", "In Review", "Done")
- •Each Sub-task status
•
Identify items to transition:
- •Story: "To Do" → "In Progress" (skip if already "In Progress", "In Review", or "Done")
- •Sub-tasks: "To Do" → "In Progress" (only items still in "To Do")

•

Display summary to user:

code

Ready to start Bolt PROJ-123 with 3 Sub-tasks.

Status transitions needed:
- Story PROJ-123: "To Do" → "In Progress"
- Sub-task TASK-456: "To Do" → "In Progress"
- Sub-task TASK-457: "To Do" → "In Progress"
- Sub-task TASK-458: Already "In Progress" (resuming)

Proceed with status updates? (y/n)

•
If user confirms:
- •Execute transitions using transition_jira_status() for each item
- •Display results with ✓/⚠/✗ indicators
- •Log any items that are already in the correct state
•
If user declines:
- •Log: "Skipping status updates. Please update manually if needed."
- •Continue workflow

•

Status Inconsistency Detection:

•If Story is "In Review" but Sub-tasks are not all "Done", warn:

code

⚠ Warning: Status mismatch detected
Story PROJ-123 is "In Review" but TASK-456 is "In Progress"

This may indicate incomplete work. Continue anyway? (y/n)

If no Jira key provided, ask:

code

What Jira Bolt (Story) should I work on?
Please provide the issue key (e.g., PROJ-123).

Step 2: Validate Repository Context

Confirm the user is in the correct repository context:

•Check current working directory
•Verify the repository is relevant to the Jira artifact
•If multiple repositories are needed, confirm they are cloned locally

Ask if needed:

code

I see you're in [current repo]. Is this the correct repository for this work?
If this bolt spans multiple services, please list the local paths to all repositories.

Step 2.5: Determine Sub-agent Strategy

Based on the Bolt's Tasks, decide whether to use parallel sub-agents:

Single Task: Proceed with single-agent exploration (Step 3).

Multiple Tasks: Spawn parallel Task Context Agents to explore in parallel.

Ask:

code

This Bolt has [N] Tasks. Should I explore the codebase for each Task in parallel?
(Recommended for efficiency - each Task gets focused exploration)

1. Yes, explore in parallel (recommended)
2. No, explore sequentially

Step 3: Explore Codebase (Parallel or Sequential)

If single Task or user declines parallel:

Understand the implementation area:

•Identify relevant files and modules
•Understand existing patterns and conventions
•Note any related tests that exist
•Identify integration points

If multiple Tasks and parallel approved:

•Spawn one Task Context Agent per Task using the Task tool
•Use subagent_type: "general-purpose"
•Pass Task content + repo context to each agent
•Use the Task Context Subagent template from planning-shared.md
•Spawn all agents in a single message (parallel execution)

After agents return:

•Parse JSON results from each agent
•Merge relevant files lists (dedupe by path)
•Combine existing patterns discovered
•Surface any conflicting approaches
•Present unified context summary:

code

## Codebase Context (Consolidated)

### Relevant Files
- [file1] - relates to [Task A, Task B]
- [file2] - relates to [Task C]

### Existing Patterns
- [pattern 1]
- [pattern 2]

### Related Tests
- [test file 1] - covers [related functionality]

### Integration Points
- [API/service/database]

Phase 2: TDD-Focused Planning

Step 4: Plan Test Cases First

Following TDD principles, identify what tests need to be written:

•
Unit Tests
- •What functions/methods need tests?
- •What edge cases should be covered?
- •What mocks/stubs are needed?
•
Integration Tests (if applicable)
- •What API endpoints need testing?
- •What database interactions need verification?
- •What external service interactions need mocking?
•
Acceptance Tests (if applicable)
- •How will acceptance criteria be verified?
- •What end-to-end scenarios should be tested?

Present the test plan:

code

## Proposed Test Cases

### Unit Tests
1. [Test description] - verifies [acceptance criterion]
2. [Test description] - handles [edge case]

### Integration Tests
1. [Test description] - verifies [integration point]

### Test Files to Create/Modify
- tests/unit/test_[feature].py
- tests/integration/test_[feature]_api.py

Step 4.5: Parallel Test Planning (Multi-Task Bolts)

If Bolt has multiple Tasks:

•Spawn one Task Test Planning Agent per Task using the Task tool
•Use subagent_type: "general-purpose"
•Pass Task content + context from Phase 1 to each agent
•Use the Task Test Planning Subagent template from planning-shared.md
•Spawn all agents in a single message (parallel execution)

Consolidation:

•Merge test plans into unified structure
•Identify shared test fixtures/utilities
•Resolve any conflicting approaches
•Present combined test plan for approval

Optional: Expert Perspectives

For high-risk Tasks (security-sensitive, performance-critical, complex domain logic):

Ask:

code

This Bolt includes [security-sensitive/performance-critical/complex] Tasks.
Would you like expert perspectives on:
1. Security (OWASP, auth, input validation)
2. Performance (latency, memory, scalability)
3. Domain (business rules, edge cases)
4. All of the above
5. Skip expert review

If yes, spawn Expert Perspective Agents in parallel using templates from planning-shared.md, then integrate their recommendations into the test plan.

Step 5: Plan Implementation Steps

Create a detailed implementation plan structured as TDD cycles:

code

## Implementation Plan

### Cycle 1: [Feature slice]
1. RED: Write failing test for [specific behavior]
2. GREEN: Implement [minimal code to pass]
3. REFACTOR: [Specific improvements]

### Cycle 2: [Next feature slice]
1. RED: Write failing test for [specific behavior]
2. GREEN: Implement [minimal code to pass]
3. REFACTOR: [Specific improvements]

...

Phase 3: Plan Approval

Step 6: Present Plan for Approval

Present the complete plan to the user:

•Summary of the Jira artifact
•Test cases to be written
•Implementation cycles (Red → Green → Refactor)
•Estimated files to be created/modified
•Any risks or dependencies identified

Ask explicitly:

code

Does this plan look correct? Please approve or suggest changes before I proceed.

Do NOT proceed until explicit approval is received.

Phase 4: Local Plan Storage

Step 7: Prompt for Plan File Location

Ask where to store the plan:

code

Where should I save the implementation plan?

Suggested locations:
1. ./bolt-plan.md (current directory)
2. ./docs/bolts/[jira-key].md
3. Custom path

Please specify or press enter for the default (./bolt-plan.md).

Step 8: Save Plan to Local File

Create the plan file with:

•Jira context and link
•Full implementation plan
•Progress tracking checklist
•Test cases with checkboxes

Plan File Template:

markdown

# Bolt: [Jira Key] - [Summary]

**Jira:** [Link to issue]
**Branch:** [branch-name]
**Created:** [date]

## Context

[Brief description from Jira]

## Acceptance Criteria

- [ ] [Criterion 1]
- [ ] [Criterion 2]
- [ ] [Criterion 3]

## Test Plan

### Unit Tests
- [ ] [Test 1]
- [ ] [Test 2]

### Integration Tests
- [ ] [Test 1]

## Implementation Progress

### Cycle 1: [Description]
- [ ] RED: Write failing test
- [ ] GREEN: Make test pass
- [ ] REFACTOR: Clean up

### Cycle 2: [Description]
- [ ] RED: Write failing test
- [ ] GREEN: Make test pass
- [ ] REFACTOR: Clean up

## Notes

[Space for implementation notes]

Phase 5: Feature Branch Creation

Step 9: Prompt for Base Branch

Ask which branch to use as the base:

code

Which branch should I create the feature branch from?

1. main (recommended for trunk-based development)
2. master
3. dev/develop
4. Other (please specify)

Default to main if user presses enter.

Step 10: Create Feature Branch

Create the feature branch with naming convention:

•Format: <jira-key>-<description>
•Example: PROJ-123-add-user-authentication

bash

git checkout [base-branch]
git pull origin [base-branch]
git checkout -b [jira-key]-[short-description]

Report branch creation:

code

Created feature branch: PROJ-123-add-user-authentication
Based on: main

Ready to begin implementation. The plan is saved at [plan-file-path].

Phase 6: Begin Implementation

Step 10.5: Determine Implementation Strategy

If single Task: Proceed with sequential TDD cycles (Step 11).

If multiple Tasks:

•Analyze Task dependencies from Phase 1 context
•Identify which Tasks are independent (no shared file modifications, no sequential dependencies)
•Offer parallel implementation for independent Tasks

Ask:

code

Based on the context gathered:

**Independent Tasks** (can run in parallel):
- [Task A] - touches [files]
- [Task B] - touches [files]

**Dependent Tasks** (must run sequentially):
- [Task C] depends on [Task A]

Should I implement the independent Tasks in parallel using separate agents?
(Recommended for efficiency - each Task gets focused TDD cycles)

1. Yes, implement in parallel (recommended)
2. No, implement sequentially

Important Constraints:

•Only parallelize Tasks with no shared file modifications
•Each agent owns its TDD cycles (Red → Green → Refactor)
•Main agent coordinates merging and resolves conflicts

Step 11: Execute TDD Cycles (Parallel or Sequential)

Sequential (single Task or dependent Tasks):

Begin with the first test case:

•Create the test file if it doesn't exist
•Write the first failing test
•Run the test to confirm it fails (RED)
•Report status and await approval to continue

At each step, update the plan file to mark completed items.

Parallel (independent Tasks):

•Spawn one Task Implementation Agent per independent Task using the Task tool
•Use subagent_type: "general-purpose"
•Pass Task content + test plan + context to each agent
•Use the Task Implementation Subagent template from planning-shared.md
•Spawn all agents in a single message (parallel execution)
•Agents commit independently with meaningful messages

After parallel agents complete:

•Parse JSON results from each agent
•Verify no file conflicts between agents
•Merge any overlapping changes (rare if dependencies analyzed correctly)
•Run full test suite to verify integration
•
Transition Sub-task statuses to "Done":
- •
  For each completed agent's Sub-task:
  code
  transition_jira_status(TASK-456, "Done", "Sub-task")
- •Display results: "✓ Sub-task TASK-456: 'In Progress' → 'Done'"
•Update plan file with combined progress
•Report completion status for all Tasks:

code

## Implementation Progress

### Task A: [Title] ✅ Complete
- Cycles completed: 3
- Files modified: [list]
- Tests passing: Yes
- Jira status: ✓ Done

### Task B: [Title] ✅ Complete
- Cycles completed: 2
- Files modified: [list]
- Tests passing: Yes
- Jira status: ✓ Done

### Integration Verification
- Full test suite: ✅ Passing
- Conflicts resolved: None

Step 12: Continue TDD Cycles (Sequential Mode)

For each cycle (when running sequentially):

•Write failing test (RED) - run to confirm failure
•Implement minimal code (GREEN) - run to confirm pass
•Refactor if needed - run to confirm still passing
•Update plan file progress
•Commit with meaningful message

When Task complete (all TDD cycles for a Sub-task done):

•Verify all tests for this Task pass

•Transition Sub-task to "Done":

code

transition_jira_status(TASK-456, "Done", "Sub-task")

•Display result: "✓ Sub-task TASK-456: 'In Progress' → 'Done'"
•Continue to next Task or proceed to Bolt completion check

Commit message format:

code

[JIRA-KEY] [type]: [description]

- [detail 1]
- [detail 2]

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Step 13: Bolt Completion Check

After all Tasks (Sub-tasks) complete, verify Bolt readiness for review:

•

Verify Prerequisites:

•Query Jira: Are all Sub-tasks marked "Done"?

bash

acli jira workitem children PROJ-123 --json | jq '.[] | {key, status}'

•Run full test suite: Do all tests pass?

bash

[test command for project, e.g., pytest, npm test, dotnet test]

•

If both prerequisites met:

•Display completion summary:

code

🎉 Bolt PROJ-123 complete!

✓ All 3 Sub-tasks marked Done
✓ Full test suite passing (45 tests, 0 failures)

Ready to transition Story to "In Review"? (y/n)

•

If user confirms:

•Transition Story to "In Review":

code

transition_jira_status(PROJ-123, "In Review", "Story")

•Display result: "✓ Story PROJ-123: 'In Progress' → 'In Review'"

•Suggest next step:

code

Next steps:
1. Create Pull/Merge Request: /issues:create-mr
2. After PR merged, manually transition to "Done" in Jira

•

If prerequisites NOT met:

•List incomplete items:

code

⚠ Cannot transition to "In Review" yet:

Incomplete Sub-tasks:
- TASK-458: Still "In Progress"

Test failures:
- test_authentication_flow: AssertionError
- test_user_validation: ConnectionError

Please complete remaining work before transitioning to "In Review".

•
Parent-Child Synchronization Validation:
- •
  Before transitioning Story to "In Review", verify:
  - •All Sub-tasks are "Done" (not just complete in local code)
  - •No Sub-tasks are "To Do" or "In Progress"
- •
  If mismatch detected:
  code
  ⚠ Warning: Status mismatch detected Story PROJ-123 will be "In Review" but TASK-456 is "In Progress" Options: 1. Wait - fix TASK-456 first (recommended) 2. Force transition - manual cleanup later 3. Cancel Choice (1/2/3):

Workflow Chain

•Previous: Bolt (Story) in Jira with Tasks (Sub-tasks) from /aidlc-verify
•Next: Pull/Merge Request (manual or via /issues:create-mr)

Definition of Done

•Jira context gathered and understood
•Story and Sub-tasks transitioned to "In Progress" (with user confirmation)
•TDD-focused plan created with test cases first
•Plan approved by user
•Plan saved to local file with progress tracking
•Feature branch created from specified base
•Implementation proceeds with TDD rhythm
•Each Sub-task transitioned to "Done" upon completion
•Plan file updated as progress is made
•All Sub-tasks marked "Done" in Jira
•Full test suite passing
•Story transitioned to "In Review" (with user confirmation)
•Ready for Pull/Merge Request creation

Troubleshooting

•No Jira access: Allow manual entry of acceptance criteria and description
•Multiple repositories: Confirm which repo to work in first; can switch later
•Existing branch: Ask whether to use existing or create new
•Tests failing unexpectedly: Investigate before proceeding; may indicate design issue
•Plan file location conflict: Offer alternative paths or append timestamp