Claude Code Skills for Brighter Development

This directory contains Claude Code skills (slash commands) that enforce Brighter's engineering practices and streamline common development workflows.

Quick Start

Skills are invoked using slash commands in Claude Code:

/test-first <behavior description>    # TDD with an approval gate (armed by default)
/adr <title>                          # Create Architecture Decision Record
/tidy-first <change description>      # Separate structural from behavioral changes

Available Skills

1. Test-Driven Development

Command: /test-first <behavior description>

Purpose: Enforces TDD workflow with mandatory user approval before implementation.

When to use:

Adding new behavior or functionality
Fixing bugs with test-first approach
Want to ensure tests are correct before writing implementation

Workflow:

🔴 RED: Claude writes a failing test following Brighter conventions
✅ APPROVAL: You must approve the test before implementation
🟢 GREEN: Claude implements minimum code to pass the test
🔵 REFACTOR: Claude suggests design improvements (optional)

Example:

/test-first when an invalid message is received it should be sent to the dead letter queue

Why it matters: The approval step is MANDATORY per testing.md when working with AI. This skill enforces that requirement, preventing implementation before you validate the test specification.

📖 Documentation: .claude/commands/tdd/README.md

2. Architecture Decision Records

Command: /adr <title>

Purpose: Automates creation of properly formatted and numbered ADRs.

When to use:

Making significant architectural decisions
Need to document WHY a design choice was made
Want to capture alternatives considered
Required for new capabilities per CONTRIBUTING.md

What it does:

Scans docs/adr/ to find next sequence number
Checks for current spec and links if applicable
Prompts for key ADR content (context, decision, alternatives, consequences)
Creates properly named file: docs/adr/[NNNN]-[title].md
Updates spec's .adr-list if part of spec workflow

Example:

/adr kafka message serialization strategy

Output: Creates docs/adr/0037-kafka-message-serialization-strategy.md with proper structure, Status: Proposed.

Why it matters: ADRs capture the WHY behind decisions, not just the WHAT. This skill ensures they're created consistently and tracked properly.

📖 Documentation: .claude/commands/adr/README.md

3. Tidy First - Separate Structural from Behavioral Changes

Command: /tidy-first <change description>

Purpose: Enforces Beck's "Tidy First" methodology by separating refactoring from functionality changes into distinct commits.

When to use:

Need to refactor code AND add/change functionality
Existing code is messy and needs cleanup before modification
Want cleaner git history and easier code reviews
Large methods need breaking down before adding features

Workflow:

Analysis: Categorizes changes into structural (refactoring) vs behavioral (functionality)
Plan: Gets your approval of categorization
Structural Phase: Makes refactoring changes only
Validate: Runs tests - all must pass (behavior unchanged)
Commit: Creates refactor: commit
Behavioral Phase: Makes functionality changes
Validate: Runs tests with new behavior
Commit: Creates feat:/fix:/perf: commit

Example:

/tidy-first optimize the message processing in KafkaConsumer

Output: Two separate commits:

refactor: simplify message processing structure in KafkaConsumer
feat: add caching and exponential backoff to message processing

Why it matters: Separating structural from behavioral changes makes code reviews easier, git history clearer, and reduces bugs. Required per code_style.md.

📖 Documentation: .claude/commands/refactor/README.md

4. Bugfix - Diagnosis-First Bug Workflow

Commands: /bugfix:triage, /bugfix:confirm, /bugfix:test, /bugfix:fix, /bugfix:verify (plus /bugfix:status, /bugfix:switch)

Purpose: A lightweight, diagnosis-first workflow for fixing bugs. It is /test-first wrapped with an explicit Confirm gate up front — because a bug's root cause is a hypothesis until proven.

When to use:

A defect whose root cause is not yet proven
An issue that arrived with a suggested fix (including agent-authored) you should verify before trusting
Anywhere /test-first alone would jump to a test for an assumed cause

Workflow:

Triage (/bugfix:triage [issue|description]) - Restate the symptom, locate the code, form a root-cause hypothesis (any suggested fix is UNVERIFIED)
✋ Confirm (/bugfix:confirm) - Prove the hypothesis by code-trace and/or red repro before any fix; surfaces scope changes / extra defects
✋ Test-first (/bugfix:test) - Delegates to /test-first for the failing regression test
Fix (/bugfix:fix) - Minimal change to green, scoped to the confirmed cause
Verify (/bugfix:verify) - Run the suite; capture the root cause and Fixes #N in the commit/PR

Example:

/bugfix:triage 4054     # ASB SessionId case-sensitivity
/bugfix:confirm         # proves CamelCase round-trip cause; finds a 2nd defect
/bugfix:test            # red regression test (via /test-first)
/bugfix:fix             # minimal fix scoped to the confirmed cause
/bugfix:verify          # suite green; fix: commit with Fixes #4054

Why it matters: The Confirm gate stops you fixing a symptom or trusting a wrong suggested fix — and frequently changes the scope of the fix. It deliberately omits the ADR/requirements/review rounds that /spec mandates.

📖 Documentation: .claude/commands/bugfix/README.md

Skill Categories

Development Workflow Skills

/test-first - TDD with an approval gate, armed by default (shift it with /spec:gear)
/tidy-first - Safe refactoring workflow
/bugfix:* - Diagnosis-first bug workflow (Triage → Confirm → Test-first → Fix → Verify)

Documentation Skills

/adr - Architecture Decision Records

Specification Workflow Skills (Pre-existing)

/spec:requirements - Capture requirements
/spec:design - Create design ADRs
/spec:tasks - Break down implementation
/spec:implement - TDD implementation
/spec:status - Show spec status
/spec:approve - Approve phases
/spec:review - Review phases

📖 Documentation: .claude/commands/spec/README.md

When to Use Which Skill

Decision Tree

Do you need to document an architectural decision?
├─ Yes → /adr <title>
└─ No ↓

Are you fixing a bug?
├─ Yes ↓
│   └─ Is the root cause already proven/obvious?
│       ├─ No  → /bugfix:triage  (Triage → Confirm gate → Test-first → Fix → Verify)
│       └─ Yes → /test-first <behavior>  (cause is clear; just need the test)
└─ No ↓

Are you adding new behavior?
├─ Yes ↓
│   └─ Does existing code need refactoring first?
│       ├─ Yes → /tidy-first <description>
│       └─ No → /test-first <behavior>
└─ No ↓

Are you just refactoring with no behavior changes?
├─ Yes → /tidy-first <description> (will create single refactor commit)
└─ No → Use standard workflow

Common Scenarios

Scenario 1: Adding a new feature

# If code is clean, use test-first
/test-first when message fails validation it should log detailed error

# If code needs cleanup first, use tidy-first
/tidy-first add validation logging with error details

Scenario 2: Implementing from a specification

# Part of spec workflow
/spec:requirements 123
/spec:design message-validation-strategy  # Uses /adr internally
/spec:tasks
/spec:implement  # Uses /test-first approach

Scenario 3: Making architectural decision

# Standalone or part of spec
/adr error-handling-strategy-for-kafka-consumer

Scenario 4: Optimizing existing code

# Refactor structure, then add optimizations
/tidy-first optimize message batch processing for better throughput

Integration with Brighter Practices

These skills enforce practices documented in .agent_instructions/:

Skill	Enforces	Reference
`/test-first`	TDD approval workflow (gate armed by default)	testing.md → "TDD Style" / "The review gear"
`/adr`	ADR creation standards	documentation.md lines 49-62
`/tidy-first`	Structural/behavioral separation	code_style.md lines 74-83

All three make mandatory workflows enforceable rather than just documented.

Benefits

For Individual Developers

Faster workflows: One command does multi-step processes correctly
Less to remember: Skills encode the practices, you just invoke them
Built-in guardrails: Approval gates, armed by default, prevent mistakes
Better habits: Using skills reinforces best practices

For Code Reviews

Clearer commits: Structural and behavioral changes are separated
Better context: ADRs explain WHY decisions were made
Correct tests: Approval gate ensures tests are reviewed before implementation
Easier review: Small, focused commits are easier to review

For Project Quality

Consistent ADRs: All architectural decisions are documented the same way
Better git history: Commits have single purpose (structure OR behavior)
Test coverage: TDD approach ensures tests are written first
Design quality: Approval and refactoring phases promote better design

Skill Implementation Details

Skills are implemented as Markdown files with frontmatter defining:

---
allowed-tools: Read, Write, Edit, Bash, AskUserQuestion, ...
description: Brief description shown in skill list
argument-hint: <what user should provide>
---

The body contains instructions for Claude Code to follow when the skill is invoked.

Location: .claude/commands/[category]/[skill-name].md

Examples of Skills in Action

Example 1: Test-First Development

Developer: /test-first when a message is rejected it should be sent to dead letter queue

Claude:
🔴 RED: Writing test When_message_is_rejected_should_send_to_dead_letter_queue

[Shows test code following BDD naming, Arrange/Act/Assert structure]

Test fails: ✓ "SendToDeadLetterQueue method not found"

✅ APPROVAL REQUIRED: Should I proceed to implement the code to make this test pass?

Developer: Yes

Claude:
🟢 GREEN: Implementing SendToDeadLetterQueue method
[Shows implementation with XML docs]
✓ Test passes
✓ All 47 tests pass

🔵 REFACTOR: Extracting rejection logic into separate method
[Shows refactoring]
✓ All tests still pass

Suggested commit: feat: send rejected messages to dead letter queue

Example 2: Architecture Decision Record

Developer: /adr kafka consumer error handling strategy

Claude:
Next ADR number: 0037
Found current spec: specs/0001-kafka-dead-letter-queue/

What is the architectural problem or decision to be made?
Developer: We need to decide how to handle different types of errors in the Kafka consumer...

What is your proposed solution?
Developer: Use different exception types to route to DLQ vs invalid message topics...

What alternatives did you consider?
Developer: Single error topic - rejected because can't differentiate error types...

✓ Created: docs/adr/0037-kafka-consumer-error-handling-strategy.md
✓ Added to: specs/0001-kafka-dead-letter-queue/.adr-list

Status: Proposed

Next: Review and commit: git commit -m "docs: add ADR for kafka consumer error handling"

Example 3: Tidy First Refactoring

Developer: /tidy-first optimize KafkaConsumer message processing

Claude:
Analyzing KafkaConsumer.cs...

STRUCTURAL changes (refactoring):
- Extract IsValidMessage() method
- Rename 'msg' to 'message'
- Reduce nesting in ProcessBatch
- Move magic number to constant

BEHAVIORAL changes (new functionality):
- Add message caching
- Implement early exit for empty batches
- Change to exponential backoff

Proceed with structural changes first?
Developer: Yes

Claude:
🔧 STRUCTURAL: Making refactoring changes...
[Shows refactoring]

Running tests... ✓ All 47 tests pass (no behavior changed)

✓ Committed: refactor: simplify message processing structure

Proceed with behavioral changes?
Developer: Yes

Claude:
✨ BEHAVIORAL: Adding optimizations...
[Shows new features]

Running tests... ✓ All 47 tests pass

✓ Committed: feat: add caching and exponential backoff to message processing

Complete! Two commits created for easier review.

Tips for Using Skills

Best Practices

Use skills proactively: Don't wait until you're stuck - use them from the start
Trust the process: The approval gates and validations are there for good reasons
Combine skills: Use /adr to document, /test-first to implement
Review skill output: Always review what the skill produces before accepting
Iterate: Skills support iteration - if categorization is wrong, adjust and continue

Common Patterns

Pattern 1: Feature Development

/adr <design decision>        # Document the approach
/test-first <behavior>        # Implement with TDD
# Repeat test-first for each behavior

Pattern 2: Refactoring + Feature

/tidy-first <optimization>    # Clean up + add feature
# Results in two commits: refactor + feat

Pattern 3: Specification-Driven

/spec:requirements <issue>    # Capture requirements
/spec:design <focus>          # Uses /adr internally
/spec:tasks                   # Break down work
/spec:implement               # Uses /test-first approach

Getting Help

Skill documentation: Each skill has a README.md in its directory
Brighter guidelines: See .agent_instructions/ for full practices
Issues: Report skill issues at https://github.com/anthropics/claude-code/issues
Contributing guidelines: See CONTRIBUTING.md

Summary

Three new skills enforce Brighter's mandatory engineering practices:

Skill	Enforces	Creates
`/test-first`	TDD with an approval gate (armed by default)	Tests → Implementation → Refactoring
`/adr`	Documented decisions	Numbered ADR files
`/tidy-first`	Structural/behavioral separation	Two commits: refactor + feat
`/bugfix:*`	Confirm root cause before fixing	Bug record + regression test + scoped `fix:` commit

Key insight: These skills make the correct approach the easy path by automating multi-step workflows and enforcing approval gates — and where a gate is a matter of pace rather than principle, they give you a deliberate, visible way to change gear (/spec:gear) instead of quietly ignoring it.

Try them: Start with /test-first for your next feature or /tidy-first for your next optimization.

Navigation Menu

Uh oh!

Claude Code Skills for Brighter Development

Quick Start

Available Skills

1. Test-Driven Development

2. Architecture Decision Records

3. Tidy First - Separate Structural from Behavioral Changes

4. Bugfix - Diagnosis-First Bug Workflow

Skill Categories

Development Workflow Skills

Documentation Skills

Specification Workflow Skills (Pre-existing)

When to Use Which Skill

Decision Tree

Common Scenarios

Integration with Brighter Practices

Benefits

For Individual Developers

For Code Reviews

For Project Quality

Skill Implementation Details

Examples of Skills in Action

Example 1: Test-First Development

Example 2: Architecture Decision Record

Example 3: Tidy First Refactoring

Tips for Using Skills

Best Practices

Common Patterns

Getting Help

Summary

Uh oh!

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Claude Code Skills for Brighter Development

Quick Start

Available Skills

1. Test-Driven Development

2. Architecture Decision Records

3. Tidy First - Separate Structural from Behavioral Changes

4. Bugfix - Diagnosis-First Bug Workflow

Skill Categories

Development Workflow Skills

Documentation Skills

Specification Workflow Skills (Pre-existing)

When to Use Which Skill

Decision Tree

Common Scenarios

Integration with Brighter Practices

Benefits

For Individual Developers

For Code Reviews

For Project Quality

Skill Implementation Details

Examples of Skills in Action

Example 1: Test-First Development

Example 2: Architecture Decision Record

Example 3: Tidy First Refactoring

Tips for Using Skills

Best Practices

Common Patterns

Getting Help

Summary