Tdd Test Writer
Run the RED phase of TDD: write behavior-focused failing tests and hand implementation agents a pass/fail contract without touching production code.
Overview
tdd-test-writer is an agent skill most often used in Ship (also Build) that completes the RED phase of TDD—writing failing behavior tests and a strict implementation contract without editing production code.
Install
npx skills add https://github.com/am-will/codex-skills --skill tdd-test-writerWhat is this skill?
- RED-phase only: explicitly forbids modifying production code during the skill run
- Behavior-focused tests with mandatory pre-handoff failure verification
- Regression test requirement for bugfix tasks capturing the reported failure mode
- Subagent role `tdd_test_writer` when the host supports delegated test authoring
- 7 numbered Required Rules governing determinism, targeted test commands, and valid failure reasons
- 7 Required Rules for RED-phase test authoring
- 5-step workflow starting with Define Behavior Contract
Adoption & trust: 857 installs on skills.sh; 941 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You want test-first delivery but agents mix test and implementation edits, producing green tests that do not actually require the right behavior.
Who is it for?
Solo builders running agentic TDD on features or bugfixes where tests must define the contract before any production patch.
Skip if: Spikes with no automated test harness, pure manual QA-only tasks, or sessions where you explicitly want implementation-first without failing tests.
When should I use this skill?
Users ask for test-first development, TDD / RED-GREEN-REFACTOR workflow, tests implementation agents must satisfy, or bugfixes needing regression tests before code changes.
What do I get? / Deliverables
You receive failing, behavior-gated tests plus documented acceptance criteria so an implementation agent can pursue GREEN against objective pass/fail signals.
- New or updated behavior-focused tests that fail pre-handoff
- Documented acceptance criteria (happy path, edges, negative paths)
- Regression test for bugfix scenarios when applicable
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Canonical shelf is Ship/testing because the skill’s output is failing automated tests and explicit acceptance criteria that gate release quality. testing is where RED/GREEN discipline lives—tests must fail for missing behavior before any implementation agent edits app code.
Where it fits
Author failing API contract tests before merging a billing webhook change.
Define edge-case unit tests for a new authorization rule prior to handler implementation.
Attach a regression test reproducing a reported production bug for the implementer to fix against.
How it compares
Use instead of asking one agent to write tests and production code in the same pass when you need RED isolation and verified failures.
Common Questions / FAQ
Who is tdd-test-writer for?
Developers using Codex or similar agents who want a dedicated RED-phase writer that leaves implementation to a follow-up agent with clear acceptance criteria.
When should I use tdd-test-writer?
Use it in Ship/testing for test-first features and regressions, and in Build/backend when behavior must be locked in tests before code; also for bugfixes that need a failing reproduction test first.
Is tdd-test-writer safe to install?
It orchestrates test authoring in your repo—review the Security Audits panel on this Prism page and ensure test commands match your CI before delegating.
SKILL.md
READMESKILL.md - Tdd Test Writer
# TDD Test Writer Use this skill to complete the RED phase of TDD: define behavior with tests first, verify they fail for the right reason, then hand off implementation with objective pass criteria. ## When To Use Use this skill when the user asks for: - test-first development - TDD / RED-GREEN-REFACTOR workflow - writing tests that implementation agents must satisfy - bugfixes that need regression tests before code changes ## Required Rules 1. Do not modify production code while running this skill. 2. Use subagent role `tdd_test_writer` for RED-phase test authoring whenever available. 3. Write behavior-focused tests, not placeholders. 4. Every new/updated test must fail before handoff. 5. Failures must come from missing or incorrect production behavior, not broken tests. 6. Prefer deterministic, targeted test commands over full-suite runs when possible. 7. 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 ```markdown 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] ``` ## Quality Bar - Tests fail before implementation and are reproducible locally. - Assertions are specific enough to prevent false positives. - Regression coverage is present for bugf