tdd-test-writer

Writes failing tests first, establishing a strict implementation contract for test-driven development.

am-will/codex-skills|Updated Apr 8, 2026

Works with

Claude CodeCursorClineWindsurfCodexGoose

What it does

Completes the RED phase of TDD by authoring behavior-focused tests that fail for the right reason, then hands off to implementation agents with objective pass criteria
Delegates test authoring to a tdd_test_writer subagent when available, ensuring tests remain unmodified during implementation
Detects existing test frameworks and conventions (pytest, jest, vitest, go test, cargo test

Repository

am-will/codex-skills

Last updated

Apr 8, 2026

Installation Guide

Select your AI agent

How to use tdd-test-writer on Cursor

AI-first code editor with Composer

Prerequisites

Before installing skills in Cursor, ensure your development environment meets these requirements:

›Cursor installed and configured on your machine
›Node.js 16+ with npm — verify with node --version
›Active project directory where you want to add tdd-test-writer

Run the install command

Execute the skills CLI command in your project's root directory to begin installation:

$npx skills add https://github.com/am-will/codex-skills --skill tdd-test-writer

Fetches tdd-test-writer from am-will/codex-skills and configures it for Cursor.

Select Cursor when prompted

The CLI shows a list of agents. Use arrow keys and space to select Cursor:

◆ Which agents do you want to install to?

│

│ ── Universal (.agents/skills) ────────────────

│ · Cline · Codex · Goose · Windsurf

│ ●Cursor(selected)

│ · Cursor · Aider · Continue

Verify installation

Confirm successful installation by checking the skill directory location:

.cursor/skills/tdd-test-writer

Restart Cursor to activate tdd-test-writer. Access via /tdd-test-writer in your agent's command palette.

⚠

Security Notice

We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.

Skills execute code in your environment. Always review source, verify the publisher, and test in isolation before production.

›View source on GitHub ›Skills CLI docs ›About Cursor ›What are agent skills?

Documentation

List & Monetize Your Skill

Submit your Claude Code skill and start earning

Get started →

Use Cases

Task Automation & Efficiency

Automate repetitive workflows and reduce manual effort

Example

Generate reports, summarize documents, draft communications

✓

Save 3-5 hours per week on routine tasks

Knowledge Enhancement

Learn new skills, understand complex topics, get expert guidance

Example

Explain concepts, provide examples, suggest learning resources

✓

Accelerate learning and skill development by 2x

Quality Improvement

Enhance output quality through reviews, suggestions, and refinements

Example

Review drafts, suggest improvements, catch errors

✓

Improve work quality by 30-40% with less effort

Required Rules

Do not modify production code while running this skill.

Use subagent role tdd_test_writer for RED-phase test authoring whenever available.

Write behavior-focused tests, not placeholders.

Every new/updated test must fail before handoff.

Failures must come from missing or incorrect production behavior, not broken tests.

Prefer deterministic, targeted test commands over full-suite runs when possible.

For bugfix tasks, add a regression test that captures the reported failure mode.

Workflow

1. Define Behavior Contract

Convert user request into explicit acceptance criteria.

Identify happy path, edge cases, and negative-path expectations.

If requirements are ambiguous, record ASSUMPTION: lines in output.

2. Delegate Test Authoring To tdd_test_writer

Spawn a tdd_test_writer subagent with task scope, target files, and acceptance criteria.

Require the subagent to write/update tests only (no production code changes).

Require command output proving RED-state failure for the new tests.

If tdd_test_writer is unavailable, continue directly and note FALLBACK: tdd_test_writer unavailable.

3. Discover Existing Test Conventions

Detect framework and runner from the repo (for example vitest, jest, pytest, go test, cargo test).

Follow existing directory, naming, and fixture conventions.

Reuse existing helpers instead of introducing duplicate test utilities.

4. Author RED-Phase Tests

Create or update test files that encode the behavior contract.

Keep tests small and intention-revealing (clear names and assertions).

Include at least one negative-path assertion where applicable.

Avoid network/time randomness; mock or fixture external systems.

5. Verify RED State

Run the narrowest command that executes the new tests.

Confirm they fail for the expected behavioral gap.

If failure is caused by test syntax/setup, fix tests and rerun.

6. Produce Implementation Handoff

Return a block that implementation agents must follow. The handoff must include:

subagent used (tdd_test_writer) or explicit fallback reason

exact test files created/updated

exact verification command(s)

short failure summary proving RED state

immutable test constraint (do not edit tests unless requirement changes)

pass criteria that define task completion

Required Output Format

TDD RED PHASE COMPLETE ## Authoring Mode - Subagent: tdd_test_writer - Fallback: [only if subagent unavailable] ## Test Files - [path] ## Verification - Command: [exact command] - Result: FAIL (expected) - Failure reason: [1-2 lines tied to missing behavior] ## Implementation Contract (for next agent) 1. Do not modify these tests: [paths] 2. Implement production changes only in: [paths or modules] 3. Completion gate: [exact command] passes with no test weakening. 4. Run broader safety check: [secondary command] 5. Return evidence: changed files + command output summary. ## Assumptions - ASSUMPTION: [only if needed]

tdd-test-writer

What it does

Category

Repository

Last updated

Installation Guide

How to use tdd-test-writer on Cursor

Prerequisites

Run the install command

Select Cursor when prompted

Verify installation

Security Notice

Documentation

List & Monetize Your Skill

Use Cases

Task Automation & Efficiency

Knowledge Enhancement

Quality Improvement

Install Skill

TDD Test Writer

When To Use

Required Rules

Workflow

1. Define Behavior Contract

2. Delegate Test Authoring To tdd_test_writer

3. Discover Existing Test Conventions

4. Author RED-Phase Tests

5. Verify RED State

6. Produce Implementation Handoff

Required Output Format

Quality Bar

Implementation Guide

Best Practices

When to Use This

Learning Path

Related Skills

llm-council

frontend-design

codex-subagent

polyglot-test-agent

novel-writer-cn

research-paper-writer

Reviews

Discussion

2. Delegate Test Authoring To `tdd_test_writer`