Spec Commit Sync: Automatic Traceability from Specs to Code

Status: ✅ Implemented Version: 1.0.0 Last Updated: 2025-11-11

Overview

SpecWeave automatically posts commit and PR links to external tools (GitHub, JIRA, Azure DevOps) when you complete work on spec user stories. This provides complete traceability from specs to actual code changes without manual intervention.

How It Works

Architecture

1. Complete task (TodoWrite) → post-task-completion hook fires
2. Hook detects completed user stories (via AC-IDs)
3. Hook gets recent commits since last sync
4. Hook posts comment to external tool with:
   - User story details
   - Commit links (with short descriptions)
   - PR links (if applicable)
   - Short summary of what was done

Example Comment

## ✅ US-001: User Authentication

New features (3 commits)

**Completed Tasks:**
- T-001: Implement AuthService
- T-002: Add login endpoint

**Commits:**
- [`abc123`](https://github.com/owner/repo/commit/abc123) feat: add authentication service
- [`def456`](https://github.com/owner/repo/commit/def456) feat: add login endpoint
- [`ghi789`](https://github.com/owner/repo/commit/ghi789) test: add auth tests

**Pull Requests:**
- [#42](https://github.com/owner/repo/pull/42) Add user authentication (merged)

**Acceptance Criteria:**
- ✓ AC-US1-01: User can log in with valid email/password
- ✓ AC-US1-02: Invalid credentials show error

---
🤖 Auto-generated by SpecWeave

Configuration

Enable/Disable

In .specweave/config.json:

{
  "sync": {
    "settings": {
      "postCommitComments": true  // Default: true
    }
  }
}

Provider-Specific Setup

GitHub

Requirements:

GitHub CLI (gh) installed and authenticated
Repository linked in metadata.json (github.issue)

Automatic: No additional configuration needed

JIRA

Requirements:

JIRA credentials in environment variables
JIRA issue linked in metadata.json (jira.issueKey)

Environment Variables:

export JIRA_DOMAIN="company.atlassian.net"
export JIRA_EMAIL="your-email@example.com"
export JIRA_API_TOKEN="your-api-token"
export JIRA_PROJECT_KEY="PROJ"

Azure DevOps

Requirements:

Azure DevOps PAT in environment variable
ADO work item linked in metadata.json (ado.workItemId)

Environment Variables:

export AZURE_DEVOPS_PAT="your-personal-access-token"

What Gets Synced

Completed User Stories

When ALL tasks for a user story are completed, a comprehensive comment is posted:

User story title
Completed tasks
All commits since last sync
Pull requests (if detected)
Acceptance criteria status

Work in Progress

If commits exist but no user stories are fully completed, a short update is posted:

Summary (e.g., "Work in progress: 3 commits")
Commit links

Multi-Repo Support

If commits go to different repos, multiple comments can be posted (one per repo). Each comment shows commits for that specific repository.

Benefits

Complete Traceability

From spec to code: Click commit link → see exact code changes
From code to spec: Git commit references spec user story
Audit trail: All changes documented in external tool

Zero Manual Work

Automatic: No manual comment posting
Real-time: Updates immediately after task completion
Non-blocking: Failures don't stop your workflow

Team Visibility

Stakeholders: See progress in JIRA/ADO without asking
PM: Track velocity via commit history
Developers: Understand what changed and why

How to Use

1. Link Increment to External Tool

GitHub:

/sw-github:create-issue 0001

JIRA:

/sw-jira:sync 0001

Azure DevOps:

/sw-ado:sync 0001

2. Work Normally

# Work on tasks
/sw:do

# Complete tasks (TodoWrite updates)
# Hook fires automatically after each completion

3. View Comments

Comments appear automatically in:

GitHub issue comments
JIRA issue comments
Azure DevOps work item comments

Advanced

Manual Sync

Force sync commits without waiting for task completion:

node dist/cli/commands/sync-spec-commits.js \
  --increment .specweave/increments/0001-feature \
  --provider github \
  --verbose

Dry Run

Preview what would be posted without actually posting:

node dist/cli/commands/sync-spec-commits.js \
  --increment .specweave/increments/0001-feature \
  --provider github \
  --dry-run

Debug

Check logs for hook execution:

tail -f .specweave/logs/hooks-debug.log

Troubleshooting

No Comments Posted

Check:

External tool linked in metadata.json?
Credentials configured (JIRA/ADO)?
Node.js installed?
Script built (npm run build)?

Debug:

# Check metadata
cat .specweave/increments/0001-feature/metadata.json

# Check logs
cat .specweave/logs/hooks-debug.log | grep "spec commit sync"

# Test manually
node dist/cli/commands/sync-spec-commits.js \
  --increment .specweave/increments/0001-feature \
  --provider github \
  --verbose

Wrong Repository

Problem: Comments posted to wrong repo

Solution: Verify git remote

git remote -v
# Should show correct repository

Rate Limits

GitHub: 5000 requests/hour (rarely hit) JIRA: 100 requests/min (rarely hit) ADO: 200 requests/5min (rarely hit)

If hit: Wait for reset, or reduce sync frequency

Architecture

Components

Core Infrastructure:

src/utils/git-utils.ts - Git commit/PR detection (398 lines)
src/core/spec-task-mapper.ts - Task ↔ User Story mapping (347 lines)
src/core/comment-builder.ts - Comment formatting (437 lines)

Plugin Implementations:

plugins/sw-github/lib/github-spec-commit-sync.ts - GitHub sync (243 lines)
plugins/sw-jira/lib/jira-spec-commit-sync.ts - JIRA sync (267 lines)
plugins/sw-ado/lib/ado-spec-commit-sync.ts - ADO sync (241 lines)

CLI:

src/cli/commands/sync-spec-commits.ts - CLI interface (169 lines)

Hooks:

plugins/sw-github/hooks/post-task-completion.sh - GitHub hook integration
plugins/sw-jira/hooks/post-task-completion.sh - JIRA hook integration
plugins/sw-ado/hooks/post-task-completion.sh - ADO hook integration

Total: ~2,102 lines of TypeScript + bash integration

Data Flow

Task Completion
  ↓
Post-Task-Completion Hook
  ↓
spec-commit-sync CLI
  ↓
1. Parse spec.md → Extract user stories
2. Parse tasks.md → Extract tasks with AC-IDs
3. Map tasks → user stories (via AC-IDs)
4. Get completed user stories (all tasks done)
5. Get git commits (since last sync)
6. Detect git repository (owner/repo)
7. Find PRs for commits (GitHub only)
8. Build formatted comment (markdown)
9. Post comment to external tool
10. Update last sync commit in metadata

Examples

Example 1: Single User Story

Spec (spec-001-user-auth.md):

**US-001**: As a user, I want to log in
- [x] AC-US1-01: Email/password login works
- [x] AC-US1-02: Invalid credentials show error

Tasks (tasks.md):

## T-001: Implement AuthService
**AC**: AC-US1-01, AC-US1-02
- [x] T-001

Git Commits:

abc123 feat: add authentication service
def456 test: add auth tests

Posted Comment (GitHub issue #42):

## ✅ US-001: As a user, I want to log in

New features (2 commits)

**Completed Tasks:**
- T-001: Implement AuthService

**Commits:**
- [`abc123`](https://github.com/owner/repo/commit/abc123) feat: add authentication service
- [`def456`](https://github.com/owner/repo/commit/def456) test: add auth tests

**Acceptance Criteria:**
- ✓ AC-US1-01: Email/password login works
- ✓ AC-US1-02: Invalid credentials show error

---
🤖 Auto-generated by SpecWeave

Example 2: Multiple Repos

Scenario: Frontend and backend commits

Result: Two comments posted

Comment 1: Frontend repo commits
Comment 2: Backend repo commits

Each comment shows only commits for that repo.

FAQ

Q: When do comments get posted?

A: Automatically after each task completion via post-task-completion hooks.

Q: Can I disable for a specific increment?

A: Yes, set postCommitComments: false in config.json before starting work.

Q: What if I don't use GitHub/JIRA/ADO?

A: The feature is optional. Without external tool links, no comments are posted.

Q: How do I sync old increments?

A: Run manual sync:

node dist/cli/commands/sync-spec-commits.js \
  --increment .specweave/increments/0001-feature \
  --provider github

Q: Can I customize comment format?

A: Not currently, but comment builder is modular (see src/core/comment-builder.ts).

Q: Does this work with GitLab/Bitbucket?

A: Git detection works, but posting comments is not yet implemented (GitHub/JIRA/ADO only).

Spec-Task Mapping - How tasks map to user stories
Living Docs Sync - How specs stay synchronized
External Tool Integration - GitHub, JIRA, ADO setup

Need help? Open an issue at https://github.com/anton-abyzov/specweave/issues

Overview​

How It Works​

Architecture​

Example Comment​

Configuration​

Enable/Disable​

Provider-Specific Setup​

GitHub​

JIRA​

Azure DevOps​

What Gets Synced​

Completed User Stories​

Work in Progress​

Multi-Repo Support​

Benefits​

Complete Traceability​

Zero Manual Work​

Team Visibility​

How to Use​

1. Link Increment to External Tool​

2. Work Normally​

3. View Comments​

Advanced​

Manual Sync​

Dry Run​

Debug​

Troubleshooting​

No Comments Posted​

Wrong Repository​

Rate Limits​

Architecture​

Components​

Data Flow​

Examples​

Example 1: Single User Story​

Example 2: Multiple Repos​

FAQ​

Q: When do comments get posted?​

Q: Can I disable for a specific increment?​

Q: What if I don't use GitHub/JIRA/ADO?​

Q: How do I sync old increments?​

Q: Can I customize comment format?​

Q: Does this work with GitLab/Bitbucket?​

Related​

Overview

How It Works

Architecture

Example Comment

Configuration

Enable/Disable

Provider-Specific Setup

GitHub

JIRA

Azure DevOps

What Gets Synced

Completed User Stories

Work in Progress

Multi-Repo Support

Benefits

Complete Traceability

Zero Manual Work

Team Visibility

How to Use

1. Link Increment to External Tool

2. Work Normally

3. View Comments

Advanced

Manual Sync

Dry Run

Debug

Troubleshooting

No Comments Posted

Wrong Repository

Rate Limits

Architecture

Components

Data Flow

Examples

Example 1: Single User Story

Example 2: Multiple Repos

FAQ

Q: When do comments get posted?

Q: Can I disable for a specific increment?

Q: What if I don't use GitHub/JIRA/ADO?

Q: How do I sync old increments?

Q: Can I customize comment format?

Q: Does this work with GitLab/Bitbucket?

Related