| name | tdd-workflow |
| description | Use this skill for test-first implementation of new features, bug fixes, and refactors with RED-GREEN-REFACTOR discipline and explicit verification gates. |
| version | 0.3.0 |
| source | fork |
| checksum | 1b54242d35974d22731943be036dd0e2e70504bd3681a2bf17d126bb54e92c27 |
| updated_at | 2026-03-12T10:57:03.000Z |
| intent | tdd |
| layer | quality |
TDD Workflow Skill
Codex invocation: use $tdd-workflow ... or tdd-workflow: ...
Enforce test-first development with explicit phase gates and reproducible verification evidence.
Capabilities
- Translate requirements into testable behaviors before implementation.
- Enforce RED -> GREEN -> REFACTOR sequence.
- Generate unit/integration/e2e test plans by risk.
- Prevent implementation-first drift with phase gate checks.
- Output machine-readable status for pause/resume workflows.
Input Requirements
goal (required): feature, bug fix, or refactor target.scope (required): files/modules allowed to change.risk_level (optional): low | medium | high.test_layers (optional): unit | integration | e2e.done_definition (required): objective completion criteria.
How to Use
$tdd-workflow Add refresh-token rotation for OAuth login
$tdd-workflow Fix race condition in cache invalidation path
$tdd-workflow Refactor order pricing module without behavior change
Routing Boundary
Use this skill when implementation has not started and you need strict test-first execution.
- Use
$tdd-workflow for pre-implementation TDD flow.
- Use
$test-gen for post-implementation backfill/regression tests.
- Use
$verification-loop for repeated fix-verify cycles after failures.
Native Subagent Protocol (Codex)
Codex supports native subagents. Delegate with spawn_agent, coordinate with send_input, collect via wait_agent, and clean up with close_agent.
Minimal orchestration pattern:
spawn_agent -> send_input (optional) -> wait_agent -> close_agent
Fallback: if delegation is unavailable, execute the same phases sequentially in a single thread.
Workflow Phases
State file: .omc/state/tdd-workflow-state.json
Phase 0: Scope and Behaviors
- Convert goal into behavior statements (Given/When/Then).
- Identify edge cases and failure modes.
- Map each behavior to a test layer.
Exit criteria:
- Behavior list complete.
- Test layer mapping complete.
Phase 1: RED
- Write tests for target behaviors before production code edits.
- Run targeted tests and confirm expected failures.
Exit criteria:
- New tests fail for expected reason.
- Failure output captured.
Phase 2: GREEN
- Implement minimal code to satisfy failing tests.
- Re-run targeted tests until green.
Exit criteria:
- Targeted tests pass.
- No unrelated behavior changed.
Phase 3: REFACTOR
- Improve readability/structure while preserving behavior.
- Keep tests green after each small refactor step.
Exit criteria:
- All targeted tests remain green.
- Diff remains scoped to declared files.
Phase 4: VERIFY
Run broader quality gates:
omcodex test changed
npm run build
npm run lint
npm run test
Use project-native equivalents when scripts differ.
Exit criteria:
- Required checks pass.
- Residual risks documented.
Coverage and Risk Policy
- Do not enforce blanket 80% if repository threshold differs.
- For
high risk paths, require regression assertions and negative-path tests.
- For refactors, require no behavior drift and strong snapshot/contract checks.
Output Contract
[TDD-WORKFLOW]
- goal
- scope
- risk_level
[RED]
- tests added
- expected failures observed
[GREEN]
- implementation summary
- targeted tests passed
[REFACTOR]
- cleanup summary
- behavior preservation evidence
[VERIFY]
- commands executed
- pass/fail summary
- remaining risks
[STATUS]
- phase: <scope|red|green|refactor|verify>
- result: <complete|blocked|in_progress>
- promise: <PROMISE tag>
Completion and Blocking Tags
[PROMISE:TDD_WORKFLOW_COMPLETE][PROMISE:TDD_WORKFLOW_BLOCKED]
Block when:
- tests cannot be executed in current environment
- failures are nondeterministic and cannot be stabilized
- required scope or acceptance criteria are missing
Cancellation and Resume
- Cancel with
$cancel or stop/cancel.
- Persist state file and latest phase summary.
- Resume from last incomplete phase only.
