Tdd

TDD Skill

General-purpose Test-Driven Development workflow for product code.

Rule

For implementation work, TDD is the default.

• Do not start with production code changes.
• Start with a test plan, then failing tests (RED), then minimum code (GREEN), then cleanup (REFACTOR).
• Only skip TDD when the user explicitly says tests are out of scope.

TDD Config Bootstrap (MANDATORY)

Persist TDD preference in the same tracking config hierarchy used by create/plan/run:

1. .agent/tracking.config.json
2. ${ICA_HOME}/tracking.config.json
3. $HOME/.codex/tracking.config.json or $HOME/.claude/tracking.config.json

Behavior:

• If project config is missing, ask explicitly:
  • "Use system tracking config for this project, or create a project-specific backend config?"
• On first TDD invocation, if selected config file does not exist, create it.
• If tdd.enabled is missing, ask explicitly and persist:
  • "TDD is active. Set default TDD behavior to enabled for this scope/config? (yes/no)"
• Write/update:

{
  "tdd": { "enabled": true }
}

• Scope-level decision always takes precedence over stored default for current run.
• If user asks to change default later, update tdd.enabled in the selected config file and confirm.

When to Use

• User asks for TDD, test-first, or red-green-refactor
• Implementing a new feature with clear behavior
• Fixing a bug and preventing regression
• Refactoring code while preserving behavior
• Working in unfamiliar code where tests reduce risk

When Not to Use

• One-off prototypes where tests are explicitly out of scope
• Tasks with no practical automated verification path
• Purely cosmetic edits where behavior does not change

Core Loop: Red -> Green -> Refactor

1. Define a single behavior slice

   • Capture one user-visible outcome at a time.
   • Prefer smallest meaningful increment.

2. Write a failing test first (RED)

   • Add or update one focused test.
   • Run the narrowest command that executes the test.
   • Confirm it fails for the expected reason.

3. Implement the minimum code to pass (GREEN)

   • Change only what is needed to satisfy the test.
   • Avoid speculative abstractions.
   • Re-run the focused test, then nearby tests.

4. Improve design without changing behavior (REFACTOR)

   • Remove duplication and improve naming/structure.
   • Keep tests green after each small refactor step.

5. Repeat

   • Add the next failing test for the next behavior slice.
   • Continue until acceptance criteria are covered.

Acceptance Tests (for this skill)

Test Planning Pattern (implementation work)

Before coding, define lightweight acceptance checks:

Practical Rules

• Start with behavior, not internal implementation details.
• Use deterministic tests (no flaky timing/network dependencies).
• Keep tests readable (Arrange -> Act -> Assert).
• For bug fixes, write the regression test before the code fix.
• For legacy code, write characterization tests first, then refactor.
• Run full relevant test suite before finishing.
• Record the command/output proving the first failing test run.
• Record the command/output proving the final passing run.

Validation Checklist

• Tests were written/updated before implementation changes
• First test run failed for expected reason
• Minimal implementation made tests pass
• Refactor preserved green test state
• New behavior and regression paths are covered
• Relevant suite passes end-to-end

Output Contract

When this skill is used, produce:

1. Test plan (happy path, edge, error, regression)
2. Evidence of initial failing test(s)
3. Code change summary tied to passing tests
4. Final test results and residual risks (if any)