/ Directory / Playground / agent-skill-tdd
← All servers ↗ GitHub
● Community Shelpuk-AI-Technology-Consulting ⚡ Instant

agent-skill-tdd

by Shelpuk-AI-Technology-Consulting · Shelpuk-AI-Technology-Consulting/agent-skill-tdd

Six-step workflow that forces AI coding agents into requirements-first, test-first discipline — Serena + requirements docs + Lad MCP design review + TDD + peer review.

A discipline skill for coding agents. Activates Serena for semantic code navigation, forces investigation before changes, demands explicit requirements confirmation, writes timestamped .requirements/ docs with As-Is/To-Be/Acceptance, validates architecture via Lad MCP Server, then runs strict TDD with per-change peer review. Claims 15–20% quality uplift. Works with Claude Code, Codex, Cursor, Windsurf, Antigravity.

▶ Watch demo 📦 Install 💡 Use Cases

Why use it

Key features

Live Demo

What it looks like in practice

agent-skill-tdd-skill.replay ▶ ready
0/0

Install

Author repository · Claude Skills documentation

Use Cases

Real-world ways to use agent-skill-tdd

Implement a new feature with full TDD discipline

👤 Teams where AI coders jump to implementation and miss requirements ⏱ ~120 min intermediate

When to use: Non-trivial feature where 'just write it' has burned you before.

Flow
  1. Kick off with the skill
    Use agent-skill-tdd. I want to add a 'saved searches' feature. Start from step 1 — activate Serena and investigate.✓ Copied
    → Claude reads code, summarizes current state
  2. Clarify requirements
    Confirm what I just said maps to these acceptance criteria — don't code yet.✓ Copied
    → Back-and-forth until confirmed; .requirements/ file saved
  3. Design review via Lad
    Run design review — architecture fit, hotspots.✓ Copied
    → Design critique, not just approval
  4. TDD loop
    Now begin TDD — write a failing test, minimum code to pass, refactor. Peer review each step.✓ Copied
    → Red-green-refactor cycles, each reviewed

Outcome: Feature shipped with tests, requirements history, and design rationale preserved.

Pitfalls
  • Skipping clarify to 'save time' — That's where most AI coding value is lost — hold the line
Combine with: filesystem · github

Fix a bug after writing down what correct behavior should be

👤 Devs tired of AI 'fixes' that break other paths ⏱ ~60 min intermediate

When to use: A subtle bug where the reproduction is half the battle.

Flow
  1. Investigate + document
    Use agent-skill-tdd bug mode. Symptom: <description>. Write the reproduction + expected behavior to .requirements/ first.✓ Copied
    → Timestamped doc with As-Is and To-Be
  2. Write failing test
    Test that expresses the expected behavior — currently failing.✓ Copied
    → Red test
  3. Fix + peer review
    Minimum fix to go green. Peer review.✓ Copied
    → Green + review notes

Outcome: A bug fix with a test preventing regression.

Stop before implementing — validate you understand the spec

👤 Teams where spec-misreading causes rework ⏱ ~30 min beginner

When to use: The ticket is ambiguous and you suspect you're about to build the wrong thing.

Flow
  1. Only run steps 1–4
    Use agent-skill-tdd — investigate + clarify + document + design review. Stop before coding.✓ Copied
    → Requirements doc + design review without touching code

Outcome: You either discover you misread the ticket or greenlight with confidence.

Combinations

Pair with other MCPs for X10 leverage

agent-skill-tdd-skill + filesystem

Keep .requirements/ in the repo for future agents to read

Commit .requirements/ to git so the next session has context.✓ Copied
agent-skill-tdd-skill + github

Link requirements doc in the PR description

When opening the PR, paste the .requirements/ file path in the description.✓ Copied

Tools

What this MCP exposes

ToolInputsWhen to callCost
activate_serena repo path Step 1 0 — local
investigate task description Step 2 0
clarify task, user answers Step 3 0
document_requirements confirmed requirements Step 4 0
design_review requirements + repo Step 5 0
tdd_cycle requirements Step 6 0

Cost & Limits

What this costs to run

API quota
None from the skill; Serena and Lad have their own footprints
Tokens per call
Moderate — each step is a round trip
Monetary
Free
Tip
Full 6-step is overkill for trivial tasks — run steps 1–4 only on small work

Security

Permissions, secrets, blast radius

Credential storage: None
Data egress: Only via Serena/Lad if configured

Troubleshooting

Common errors and fixes

Requirements doc not created

Ensure filesystem write access to .requirements/

Verify: ls .requirements/
Design review step feels rubber-stamp

Force an adversarial framing: 'what's the strongest objection to this design?'

Alternatives

agent-skill-tdd vs others

AlternativeWhen to use it insteadTradeoff
claude-gpt-workflowYou want cross-model review instead of self-TDD disciplineHigher API cost
planning-with-files-skillYou want persistence across sessions but less TDD rigorNo test-first enforcement

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills

Continue exploring

Related tools and workflows

Choose another guide for your workflow, or explore a collection.

Browse all topic collections → · See 29 new official additions →