# tdd

Adopt this skill: https://proskills.md/skills/other/shelpuk-ai-technology-consulting-agent-skill-tdd-skills-tdd

Page: https://proskills.md/skills/other/shelpuk-ai-technology-consulting-agent-skill-tdd-skills-tdd
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/tdd/SKILL.md
size: 8795
sha: 81e0be03db14fe64c284490156fdb04c54994f05
upstream: https://github.com/shelpuk-ai-technology-consulting/agent-skill-tdd/blob/main/skills/tdd/SKILL.md

````text
---
name: tdd
description: "Use for every coding task. Enforce strict TDD workflow: activate Serena, investigate first, clarify+confirm requirements, write per-task REQUIREMENTS.md in .requirements/<datetime>_<feature_name>/, verify APIs via web search, then implement in tiny test-verified steps."
metadata:
  short-description: Always-on TDD workflow + requirements discipline.
---

## Working Agreement

This skill is intentionally **always-on** for coding tasks. Follow it exactly unless the user explicitly opts out.

### Non-negotiables

1. **Serena first**: Start by activating the Serena project (if the Serena tools exist in the environment). If activation fails for reasons outside your control, continue without Serena and say why.
2. **Investigate before changing anything**: Understand the current state (application state, execution results, user input, logs) before proposing edits.
3. **No requirement changes without confirmation**: If requirements are unclear, ask clarifying questions. Before you change/add/interpret requirements, get explicit confirmation.
4. **Create a per-task `REQUIREMENTS.md` before implementation**:
   - Create/use root `.requirements/`.
   - For each task, choose a short snake_case feature name using lowercase ASCII letters, digits, and underscores only (for example, `update_github_authentication`).
   - Create a folder named `<datetime>_<feature_name>` using UTC datetime format `YYYYMMDDTHHMMSSZ` (for example, `20260301T143210Z_update_github_authentication`).
   - If the folder already exists, append a numeric suffix (`_01`, `_02`, and so on) to avoid collisions. Example: `.requirements/20260301T143210Z_update_github_authentication_01/`.
   - Write the task requirements file to `.requirements/<datetime>_<feature_name>/REQUIREMENTS.md` using the mandated structure (below).
5. **Use up-to-date docs**: When you rely on an API/package/technology detail, use Kindly Web Search (if available) to confirm signatures, version behavior, breaking changes, and deprecations.
6. **Smallest possible steps (TDD)**: Implement one small change at a time and test each change (unit → integration → smoke as appropriate) before proceeding.

## Per-task `REQUIREMENTS.md` Structure (Mandated)

For each task, write `REQUIREMENTS.md` to `.requirements/<datetime>_<feature_name>/REQUIREMENTS.md` with:

1. **As Is**: current behavior/state (what exists today).
2. **To Be**: desired behavior/state after the change.
3. **Requirements**: functional requirements (numbered).
4. **Acceptance Criteria**: for every functional requirement, add explicit acceptance criteria.
5. **Testing Plan**: test strategy + cases (TDD best practices).
6. **Implementation Plan**: the smallest sequential code changes; for each change, include how you’ll test it.

## Workflow (Step-by-step)

### 1) Investigate

- Inspect the repository structure, relevant code paths, current behavior, and existing tests.
- Run the smallest commands needed to confirm the current state (build/test, smoke, reproducer), when applicable.
- Summarize findings briefly.

### 2) Clarify + confirm requirements

- Ask clarifying questions where anything is ambiguous (scope, UX, edge cases, compatibility, performance).
- Propose the requirements in concrete, testable language.
- Ask for explicit confirmation before finalizing requirements or changing them.

### 3) Create task requirements folder + `REQUIREMENTS.md`

- Ensure `.requirements/` exists at repository root.
- Choose a concise snake_case `<feature_name>` (lowercase ASCII letters, digits, and underscores only).
- Generate UTC `<datetime>` in format `YYYYMMDDTHHMMSSZ`.
- Create `.requirements/<datetime>_<feature_name>/`.
- If that folder already exists, append `_01`, `_02`, and so on, until you get a unique folder name.
- Write `.requirements/<datetime>_<feature_name>/REQUIREMENTS.md` before implementation.
- First, write the "As Is" section explaining the current state of the system. 
- Then, write the "To Be" section, describing in detail how the system should behave after the necessary changes. 
- Then write the "Requirements" section describing functional requirements.
- Use Kindly Web Search to get up-to-date documentation and information on packages, functions, APIs, and other technologies you plan to use.
- Record useful Kindly Web Search findings to Serena memories for future use.
- Then go over the "Requirements" section once again, and for every functional requirement, you add acceptance criteria.
- Then you add the "Testing Plan" section. You list there the testing plan for this new feature, following the test-driven development (TDD) best practices.
- Write the "Implementation Plan" section. The Implementation Plan describes the feature implementation order and attributes every feature to the tests from the Testing Plan that should validate it. Now, this is super important! In the "Implementation Plan", you always describe the smallest possible changes that need to be implemented one after the other to implement the requirements. For every change, you describe how to test it.

### 4) Validate assumptions

- Use Kindly Web Search to verify any API or dependency assumptions.
- Update the current task's `.requirements/<datetime>_<feature_name>/REQUIREMENTS.md` if assumptions change (and re-confirm requirements when needed).

### 5) Review with Lad MCP

- Review your system design in the current task's requirements file with `system_design_review` tool of the Lad MCP Server. Explain the requirements. Provide as much context as you can. 
- Review Lad's feedback and consider whether it is worth taking into account. Then, if necessary, update the current task's requirements file to incorporate this feedback.
- Keep reviewing the current task's requirements file with Lad until it stops providing useful feedback.

### 6) Implement with TDD and review with Lad

- Follow the Implementation Plan in order.
- Follow Test-Driven Development (TDD) best practices. Implement tests first. Implement feature next. Make sure the tests pass.
- After each test is implemented, review the test implementation with Lad MCP Server `code_review` tool. Implement the suggestions that are worthy of consideration.
- After each step: run the smallest relevant tests first; expand to broader tests when confidence is needed.
- Keep diffs minimal and focused; avoid unrelated refactors.
- Use Lad MCP Server `code_review` tool to review each of your code changes. Implement the suggestions that are worthy of consideration.
- Keep reviewing your code with Lad until it stops providing useful feedback.
- Record useful implementation comments and design information to Serena memories for future use.

## Workflow Activity Diagram (PlantUML)

This diagram explains the same workflow as above in PlantUML format.

```plantuml
@startuml
start

:Activate Serena project;
if (Serena activation succeeds?) then (yes)
  :Proceed with Serena-enabled workflow;
else (no)
  :Continue without Serena;
  :State why activation failed;
endif

:Investigate repository structure and current behavior;

repeat
  :Clarify scope and requirements;
  :Ask questions when requirements are unclear;
  :Propose concrete, testable requirements;
repeat while (Requirements confirmed?) is (no)

:Ensure .requirements/ exists;
:Choose <feature_name> and UTC <datetime>;
:Create .requirements/<datetime>_<feature_name>/;
if (Task folder exists?) then (yes)
  :Append _01, _02, ... until unique;
endif
:Write REQUIREMENTS.md (As Is/To Be/Requirements/AC/Testing/Plan);
:Use Kindly Web Search for API/dependency assumptions;
:Record useful web findings to Serena memory;

while (Assumptions changed?) is (yes)
  :Update current task REQUIREMENTS.md;
  :Re-confirm requirements if needed;
  :Re-check assumptions with web search;
endwhile (no)

repeat
  :Run Lad system_design_review on requirements;
  :Apply useful requirements feedback;
repeat while (More useful design feedback?) is (yes)

repeat
  :Pick next smallest implementation step;
  :Write or update tests first;
  :Review test implementation with Lad code_review;
  :Apply worthwhile test feedback;
  :Implement code change;
  :Run smallest relevant tests;
  :Review code change with Lad code_review;
  :Apply worthwhile code feedback;
repeat while (Implementation plan remaining?) is (yes)

:Record useful implementation notes to Serena memory;
stop
@enduml
```

## Serena memories (when supported)

When Serena memory tools are available, store important information as short memories:

- `project_overview.md`: what the repo is, key architectural facts.
- `suggested_commands.md`: build/test/lint/smoke commands.
- `style_and_conventions.md`: coding conventions, patterns, gotchas.
- `bugs.md`: notable bugs + fixes (date, cause, prevention) when applicable.
````

## File: README.md
upstream: https://github.com/shelpuk-ai-technology-consulting/agent-skill-tdd/blob/main/README.md

````text
# Improve AI-generated code quality by 20%

TDD Skill is a part of the **[Shelpuk AI Technology Consulting](https://shelpuk.com) agentic suite** – a set of tools that together improve the code quality produced by AI coding agents by **15–20%**. [Read more on Claude Code generation quality improvement](https://shelpuk.com/en/blog/how-to-increase-claude-code-generation-quality-by-20-percent/).

Works with **Claude Code**, **Codex**, **Antigravity**, **Cursor**, **Windsurf**, and any agent that supports skills or MCP servers.

| Component | Role |
|---|---|
| **tdd** ← you are here | Enforces TDD, requirements discipline, and peer review for every coding task |
| [Serena](https://github.com/oraios/serena) | Semantic code navigation + persistent project memory |
| [Kindly Web Search](https://github.com/Shelpuk-AI-Technology-Consulting/kindly-web-search-mcp-server) | Up-to-date API and package documentation via web search |
| [Lad MCP Server](https://github.com/Shelpuk-AI-Technology-Consulting/lad_mcp_server) | Project-aware AI design and code review |

If you like what we're building, please ⭐ **star this repo** – it's a huge motivation for us to keep going!

## How to use the suite

**1. Install three MCP servers and one skill:**

- [Serena](https://github.com/oraios/serena)
- [Kindly Web Search](https://github.com/Shelpuk-AI-Technology-Consulting/kindly-web-search-mcp-server)
- [Lad MCP Server](https://github.com/Shelpuk-AI-Technology-Consulting/lad_mcp_server)
- [tdd](https://github.com/Shelpuk-AI-Technology-Consulting/agent-skill-tdd)

**2. Use the skill when requesting a feature:**

Prompt your favorite AI coding agent (Claude Code, Codex, Cursor, etc.) as usual. Then just add `Follow $tdd` in the end.

```
> Build [your feature description]. Follow $tdd.
```

# TDD Skill

## Why enforce TDD with a skill?

Picture this: Your AI coding agent just finished a new feature. The code looks clean, the agent is confident – but there's no record of what the feature was supposed to do, the edge cases were never discussed, and when you ask the agent about its design decisions next week, it has no idea what you're referring to. A month later you discover it silently broke an integration that was agreed on in a conversation the agent never saw.

This isn't a bug in the code. It's a bug in the **process**.

### The "No Process" Problem

AI coding agents are stateless by default. Each session starts fresh. Without a structured workflow, even the best models routinely:

- Jump straight to implementation without understanding requirements
- Skip tests or write them after the fact as an afterthought
- Make design decisions without checking current API documentation
- Review their own code and miss "bad token" self-reinforcing mistakes
- Lose all decisions and reasoning the moment the session ends

The result? Technically coherent code that solves the wrong problem – and no paper trail to figure out how you got there.

### What This Skill Does Differently

We built this skill at [Shelpuk AI Technology Consulting](https://shelpuk.com) because we needed our AI coding agents to work the way **disciplined engineers** work: clarify before building, document before coding, test before shipping, and get a second opinion before merging.

✅ **Investigate first, code second** – agents understand the current state before proposing any changes

✅ **Explicit requirements confirmation** – no requirement changes without human sign-off, no silent interpretation

✅ **Per-task requirements history** – each task gets its own `.requirements/<datetime>_<feature_name>/REQUIREMENTS.md` with *As Is / To Be / Requirements / Acceptance Criteria / Testing Plan / Implementation Plan*; nothing is ever overwritten

✅ **Validated assumptions** – agents use [Kindly Web Search](https://github.com/Shelpuk-AI-Technology-Consulting/kindly-web-search-mcp-server) to confirm API signatures, breaking changes, and deprecations before implementing

✅ **Design review before code** – architectural proposals go through [Lad MCP Server](https://github.com/Shelpuk-AI-Technology-Consulting/lad_mcp_server) `system_design_review` before a line is written

✅ **Strict TDD in the smallest possible steps** – tests first, implementation second, then Lad `code_review` on every change

✅ **Project memory via Serena** – design decisions, debug findings, and conventions are stored in [Serena](https://github.com/oraios/serena) memories and survive across sessions and team members

If you find this useful, please drop us a star ⭐ – it's huge motivation for us to keep improving it!

## How It Works

The `tdd` skill is a `SKILL.md` file that Codex and Claude Code discover automatically from `~/.codex/skills/tdd/` or `~/.claude/skills/tdd/`. When active, it instructs the agent to follow a 6-step workflow for every coding task:

1. **Activate Serena** – for semantic code navigation and persistent project memory
2. **Investigate** – understand the current state before proposing any changes
3. **Clarify + confirm requirements** – ask questions, propose concrete testable requirements, get explicit confirmation
4. **Write `REQUIREMENTS.md`** – create `.requirements/<YYYYMMDDTHHMMSSZ>_<feature_name>/REQUIREMENTS.md` before any implementation begins
5. **Review design with Lad** – run the requirements and system design through `system_design_review`, iterate until feedback runs dry
6. **Implement with TDD, reviewed by Lad** – write tests first, implement, run tests, run `code_review` on each change, iterate

## Skill Suite

This skill is part of a suite designed to work together:

| Tool | Role |
|---|---|
| [Serena](https://github.com/oraios/serena) | Semantic code navigation + persistent project memory |
| [Kindly Web Search](https://github.com/Shelpuk-AI-Technology-Consulting/kindly-web-search-mcp-server) | Up-to-date API/package documentation via web search |
| [Lad MCP Server](https://github.com/Shelpuk-AI-Technology-Consulting/lad_mcp_server) | Project-aware AI code and design review |

## Install

### skill-installer (recommended for Codex)

Use `skill-installer` to pull directly from GitHub without copying or symlinking files manually. This uses the built-in Codex system skill (`skill-installer`) and its helper script.

Primary (recommended, branch-agnostic):

```bash
python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
  --repo Shelpuk-AI-Technology-Consulting/agent-skill-tdd --path skills/tdd
```

Alternative (explicit branch/path URL):

```
$skill-installer install https://github.com/Shelpuk-AI-Technology-Consulting/agent-skill-tdd/tree/main/skills/tdd
```

(Replace `main` with another ref if needed.)

> **Troubleshooting:** A bare repo URL (e.g. `https://github.com/Shelpuk-AI-Technology-Consulting/agent-skill-tdd`) fails with `Missing --path for GitHub URL.` Use one of the path-aware forms above.

Restart Codex after installing. Claude Code loads/updates skills automatically when they change.

### Codex (manual)

Codex discovers skills from `.codex/skills/` (repo-scoped) and `~/.codex/skills/` (user-scoped).

User-scoped (applies to all repos):

```bash
mkdir -p ~/.codex/skills
ln -s "$(pwd)/skills/tdd" ~/.codex/skills/tdd
# or: cp -R skills/tdd ~/.codex/skills/tdd
```

Repo-scoped (applies to one target repo):

```bash
mkdir -p <target-repo>/.codex/skills
ln -s "$(pwd)/skills/tdd" <target-repo>/.codex/skills/tdd
# or: cp -R skills/tdd <target-repo>/.codex/skills/tdd
```

Restart Codex. Verify with `/skills` (or type `$` to browse skills).

> **Troubleshooting:** If Codex reports `invalid YAML: mapping values are not allowed in this context`, the frontmatter `description` contains `: ` without quoting. Fix: `description: "…workflow: activate…"`.

### Claude Code (manual)

Claude Code discovers skills from `.claude/skills/` (repo-scoped) and `~/.claude/skills/` (user-scoped).

User-scoped (applies to all repos):

```bash
mkdir -p ~/.claude/skills
ln -s "$(pwd)/skills/tdd" ~/.claude/skills/td
````
