trellis-implement-tdd - SKILL.md Agent Skill

name: trellis-implement-tdd description: | Implement a Trellis subtask using strict TDD (RED→GREEN→REFACTOR), turning acceptance criteria into code one by one. Used when Codex / Claude Code drives a small-parameter model like qwen3.6 35b—transforms "understand and implement requirements" into a mechanical "make this failing test green" loop with objective signals at every step.

Trellis TDD Implementation (RED-GREEN-REFACTOR)

Overview

Implement a planned Trellis subtask by going through its prd.md acceptance criteria (AC) one by one using TDD: write a failing test and see red, write minimal code and see green, run self-checks to confirm no regression, record progress, move to the next AC.

This skill is invoked by the orchestration session (main session, typically a strong model) to drive the implementation executor (which may be a small model like qwen3.6 35b). The flow is "held" by this skill; the executor only performs mechanically verifiable steps without needing to judge "am I done?"—test turns green = done.

Input: A subtask directory with status in-progress and dependencies satisfied (contains prd.md, may contain design.md, implement.md, implement.jsonl, check.jsonl). Output: Code changes passing tests + progress written back to <task-dir>/tdd-progress.md, without executing git commit (Trellis implementation executors forbid commit/push/merge).

Constraints

Do not write implementation code before a failing test. The first step for every AC is always writing a test that fails.
Only handle one AC at a time. Don't start the next AC until the current one turns green.
Do not judge "what the requirement is". Requirements are locked down by prd.md acceptance criteria, decision table, and contracts; executor's job is to make the corresponding test green.
Landing point is locked. Where new code goes is decided by prd.md file manifest + design.md orchestration-computation layering; don't decide on your own.
Do not touch files outside file manifest / forbidden list. When you need to touch other files, stop and report—don't spread modifications autonomously.
Do not execute git commit / git push / git merge. After completing an AC, only stage/record.
RED/GREEN signals are the only completion criteria. Test doesn't show red means test didn't capture the behavior—stop and fix the test, don't write implementation to "make it green".
When test should be green but stays red, or self-check command fails, switch to trellis-debug-systematic—don't trial-and-error in this loop.
If prd.md lacks executable test definitions or self-check commands (violates planning-phase quality gate), stop and report—ask to supplement planning artifacts first, don't force through.

Workflow

1. Load task context (must-read before editing)

Read in order, loading only "must-read-before-editing" stable context to control small-model context occupancy:

Subtask prd.md: focus on Acceptance Criteria, Automated Tests Required, Reference Implementation, File Manifest, Decision Table, Behavior Constraints, Self-Check Commands, Forbidden.
If implement.jsonl exists: pre-load each stable context item listed (spec / contract / research).
If design.md exists: read Orchestration-Computation Separation and Mount Point Checklist sections to confirm each new code's landing point.
If .trellis/spec/<relevant-layer> exists: read specs directly related to this task.

Before editing code, copy references/tdd-progress-template.md to <task-dir>/tdd-progress.md. This task-local file is the writable progress record; the template under the skill directory stays read-only.

Extract each AC-xxx from prd.md into a TODO test list, write to <task-dir>/tdd-progress.md.

2. Run RED-GREEN loop for each AC

For each AC in order, execute the loop from references/tdd-loop-protocol.md:

1. RED  ── Copy prd.md「Reference Implementation/Test Example」, write a test for AC-xxx asserting its expected observable result
2. See red ── Run the test, must see failure (objective evidence). No failure → test didn't cover behavior, go back to step 1 to fix test
3. GREEN ── Write "just enough to turn it green" minimal code; landing point per file manifest+orchestration layering, decisions per decision table, no free improvisation
4. See green ── Run the test again, see it pass (objective signal)
5. Self-check ── Run prd.md「Self-Check Commands」full set, confirm no breakage of already-green ACs (no regression)
6. Record ── Mark AC-xxx as done in `<task-dir>/tdd-progress.md`, stage changes (no commit)
7. Next AC

Any step fails and not obvious → trigger trellis-debug-systematic, fix, then return to the failed step and re-run.

3. Wrap-up self-check

After all ACs turn green:

Run all prd.md self-check commands + project lint / type-check, all green.
Check design.md Mount Point Checklist item by item to confirm wiring (route registration / config item / event subscription / DI binding, etc.), preventing "wrote implementation but didn't wire it".
<task-dir>/tdd-progress.md shows all ACs as done, no remaining red lights.

4. Handoff to review

After implementation self-check all green, do not mark task complete on your own. Hand off to trellis-review-twostage for two-stage review; mark task complete only after review passes, via orchestration session.

Small-model adaptation highlights

Decisions left-shifted: Naming / branching / schema / landing points decided by strong model in planning phase, executor just mechanically copies.
Objective signal-driven: Each step's completion determined by test red/green / command exit code, not letting small model subjectively judge.
Narrow context: Only face one AC + one test at a time, naturally slicing context to minimum.
Role-layered model assignment: This skill drives implementation executor configured with small model (e.g. qwen3.6 35b); debugging beyond 3 rounds, review Stage 2 escalate to strong model (see trellis-review-twostage).

Reference files

references/tdd-loop-protocol.md —— Detailed RED-GREEN loop per AC, iron rules and anti-patterns, read before starting implementation.
references/tdd-progress-template.md —— Read-only template for <task-dir>/tdd-progress.md; update the task-local file throughout execution.