name	commit-with-req-tag
description	Create final git commit with requirement traceability tags (REQ-*). Use after refactor-phase to finalize TDD cycle with proper requirement linkage for bidirectional traceability.
allowed-tools	Read, Bash, Grep, Glob

commit-with-req-tag

Skill Type: Actuator (TDD Workflow) Purpose: Create final commit with requirement traceability (REQ-* keys) Prerequisites:

RED, GREEN, REFACTOR phases complete
Tests passing
Code quality verified
Requirement key (REQ-*) available

Agent Instructions

You are creating the final commit for the TDD workflow with requirement traceability.

Your goal is to create a commit that:

Links code to requirements (forward traceability: REQ-* → code)
Enables reverse lookup (backward traceability: code → REQ-*)
Provides clear context for future developers
Follows semantic commit conventions (feat:, fix:, refactor:, etc.)

Workflow

Step 1: Gather Commit Information

Collect details:

What requirement(s) were implemented? (REQ-*)
What business rules were implemented? (BR-*)
What constraints were implemented? (C-*)
What files were created/modified?
How many tests were added?
What was the test coverage?

Example:

Requirement: <REQ-ID>
Description: User login with email and password
Business Rules: BR-001, BR-002, BR-003
Files Changed:
  - src/auth/login.py (created, 87 lines)
  - tests/auth/test_login.py (created, 94 lines)
Tests: 5 tests, all passing
Coverage: 95%

Step 2: Determine Commit Type

Use semantic commit prefixes:

Prefix	When to Use	Example
`feat:`	New functionality (REQ-F-*)	feat: Add user login
`fix:`	Bug fix (remediation)	fix: Correct email validation
`refactor:`	Code restructuring (REQ-NFR-*)	refactor: Simplify login logic
`perf:`	Performance improvement (REQ-NFR-PERF-*)	perf: Optimize password hashing
`test:`	Adding/fixing tests	test: Add edge cases for login
`docs:`	Documentation only	docs: Update auth API docs
`build:`	Build system changes	build: Update dependencies
`ci:`	CI/CD changes	ci: Add auth tests to pipeline

For most TDD workflows: Use feat: (new feature) or fix: (bug fix)

Step 3: Write Commit Message

Format:

<type>: <subject> (REQ-<KEY>)

<body>

<footer>

Components:

Subject line (< 72 chars):
- Prefix with type (feat:, fix:, etc.)
- Brief description
- REQ-* key in parentheses
- Example: feat: Add user login (<REQ-ID>)
Body (detailed description):
- What was implemented?
- Why was it implemented?
- Business rules/constraints implemented
- Test coverage summary
Footer (metadata):
- Requirement keys
- Business rule keys
- Test status
- Coverage percentage
- Co-authored-by (for AI pairing)

Step 4: Create Full Commit Message

Template:

feat: Add user login (<REQ-ID>)

Implement user authentication with email and password validation.
Users can log in with valid credentials and will be locked out after
3 failed attempts for 15 minutes.

Business Rules Implemented:
- BR-001: Email validation (regex pattern)
- BR-002: Password minimum 12 characters
- BR-003: Account lockout after 3 failed attempts (15 minutes)

Implementation:
- Created LoginResult dataclass
- Implemented login() function with validation
- Added email validation helper
- Added lockout tracking per user

Tests:
- 5 tests added, all passing
- Coverage: 95% (38/40 lines)

Files:
- src/auth/login.py (created, 87 lines)
- tests/auth/test_login.py (created, 94 lines)

Implements: <REQ-ID>
Validates: BR-001, BR-002, BR-003
Tests: 5 tests, 100% passing
Coverage: 95%

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

Step 5: Optional - Squash Previous Commits

If configured (squash_commits: true in plugin config):

# Squash RED, GREEN, REFACTOR commits into final commit
git reset --soft HEAD~3  # Undo last 3 commits (keeps changes)
git commit -F commit_message.txt

If not squashing: Keep RED, GREEN, REFACTOR commits separate + final commit.

Recommendation: Keep commits separate for better git history:

RED commit shows test-first approach
GREEN commit shows minimal implementation
REFACTOR commit shows quality improvements
Final commit provides summary

Step 6: Create Commit

Execute git commit:

git add .
git commit -m "feat: Add user login (<REQ-ID>)

Implement user authentication with email and password validation.
Users can log in with valid credentials and will be locked out after
3 failed attempts for 15 minutes.

Business Rules Implemented:
- BR-001: Email validation (regex pattern)
- BR-002: Password minimum 12 characters
- BR-003: Account lockout after 3 failed attempts (15 minutes)

Implementation:
- Created LoginResult dataclass
- Implemented login() function with validation
- Added email validation helper
- Added lockout tracking per user

Tests:
- 5 tests added, all passing
- Coverage: 95% (38/40 lines)

Files:
- src/auth/login.py (created, 87 lines)
- tests/auth/test_login.py (created, 94 lines)

Implements: <REQ-ID>
Validates: BR-001, BR-002, BR-003
Tests: 5 tests, 100% passing
Coverage: 95%

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

Step 7: Verify Commit

Check commit:

git log -1 --stat

Expected output:

commit abc123def456
Author: Developer <dev@example.com>
Date:   Thu Nov 20 22:00:00 2025 +1100

    feat: Add user login (<REQ-ID>)

    Implement user authentication with email and password validation.
    ...

 src/auth/login.py       | 87 ++++++++++++++++++++++++++++++++++++++++++
 tests/auth/test_login.py | 94 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 181 insertions(+)

Output Format

When you complete the commit, show:

[COMMIT Phase - <REQ-ID>]

Commit Type: feat (new feature)

Commit Message:
  Subject: feat: Add user login (<REQ-ID>)
  Body: Implement user authentication with email/password...
  Footer: Implements: <REQ-ID>, Validates: BR-001/002/003

Files Changed:
  + src/auth/login.py (87 lines)
  + tests/auth/test_login.py (94 lines)

Traceability:
  Forward: <REQ-ID> → commit abc123
  Backward: git log --grep="<REQ-ID>" → this commit

Commit SHA: abc123def456

✅ COMMIT Complete!
   Requirement traceability established
   Forward traceability: <REQ-ID> → code
   Backward traceability: code → <REQ-ID>

Traceability Benefits

Forward Traceability (REQ → Code)

From requirement, find implementation:

# Find all commits implementing <REQ-ID>
git log --grep="<REQ-ID>" --oneline

# Find files implementing <REQ-ID>
git log --grep="<REQ-ID>" --name-only

Backward Traceability (Code → REQ)

From code, find requirement:

# Find requirement for src/auth/login.py
git log src/auth/login.py --grep="REQ-" --oneline

# Find business rules in file
grep "Implements: BR-" src/auth/login.py

Impact Analysis

When requirement changes:

# Find all code implementing <REQ-ID>
git log --grep="<REQ-ID>" --name-only | grep -v "^commit" | sort -u

# Output:
# src/auth/login.py
# tests/auth/test_login.py

Now you know exactly what to update!

Prerequisites Check

Before invoking this skill, ensure:

RED, GREEN, REFACTOR phases complete
All tests passing
Code quality verified (tech debt = 0)
Requirement key (REQ-*) available

If prerequisites not met:

Tests failing → Go back to GREEN phase
Tech debt detected → Go back to REFACTOR phase
No REQ-* key → Cannot create commit (need traceability)

Next Steps

After commit created:

Push to remote (if desired): git push origin main
Move to next requirement: Start new TDD workflow for next REQ-*
Create pull request (if using PR workflow)

Configuration

This skill respects configuration in .claude/plugins.yml:

plugins:
  - name: "@aisdlc/code-skills"
    config:
      tdd:
        squash_commits: false      # Keep RED/GREEN/REFACTOR separate
        commit_co_author: true     # Add Claude as co-author
        include_coverage: true     # Include coverage in commit message
        include_test_count: true   # Include test count in commit message

Commit Message Examples

Feature (REQ-F-*)

feat: Add password reset (<REQ-ID>)

Implement password reset via email with time-limited tokens.

Business Rules:
- BR-010: Reset token expires after 1 hour
- BR-011: Token usable only once

Implements: <REQ-ID>
Tests: 7 tests, 100% passing
Coverage: 92%

Bug Fix (Remediation)

fix: Correct email validation regex (<REQ-ID>)

Fix email validation to reject invalid TLDs.

Issue: Email validation accepted invalid domains like user@example.c
Fix: Updated regex pattern to require minimum 2-char TLD

Fixes: <REQ-ID>, BR-001
Tests: 3 new tests added, all passing

Performance Improvement (REQ-NFR-PERF-*)

perf: Optimize password hashing (REQ-NFR-PERF-001)

Switch from MD5 to bcrypt with cost factor 12.

Before: 5ms per hash (insecure)
After: 250ms per hash (secure, prevents brute force)

Implements: REQ-NFR-PERF-001, REQ-NFR-SEC-003
Tests: Performance tests added

Notes

Why requirement traceability?

Compliance: Regulations require proof of requirements → code mapping
Impact analysis: Know what code to update when requirement changes
Audit trail: Prove all requirements are implemented
Debugging: Trace production issues back to requirements
Documentation: Commits become living documentation

Bidirectional traceability:

Intent (INT-042)
  ↓ (forward)
Requirements (<REQ-ID>)
  ↓ (forward)
Design (AuthService component)
  ↓ (forward)
Code (src/auth/login.py)
  ↓ (forward)
Tests (tests/auth/test_login.py)
  ↓ (forward)
Runtime (Datadog metrics tagged with <REQ-ID>)
  ↓ (forward)
Alerts ("ERROR: <REQ-ID> - Auth timeout")
  ↑ (backward)
New Intent (INT-150: "Fix auth timeout")

Homeostasis Goal:

desired_state:
  requirement_traceability: complete
  forward_traceability: REQ → code
  backward_traceability: code → REQ
  commit_contains_req_key: true

"Excellence or nothing" 🔥

commit-with-req-tag

Install Skill

SKILL.md

commit-with-req-tag

Agent Instructions

Workflow

Step 1: Gather Commit Information

Step 2: Determine Commit Type

Step 3: Write Commit Message

Step 4: Create Full Commit Message

Step 5: Optional - Squash Previous Commits

Step 6: Create Commit

Step 7: Verify Commit

Output Format

Traceability Benefits

Forward Traceability (REQ → Code)

Backward Traceability (Code → REQ)

Impact Analysis

Prerequisites Check

Next Steps

Configuration

Commit Message Examples

Feature (REQ-F-*)

Bug Fix (Remediation)

Performance Improvement (REQ-NFR-PERF-*)

Notes