/test-driven-development

name: test-driven-development
description: "Use when the user explicitly requests strict or test-first TDD, or when the current conversation already contains an explicit `TDD Route: strict` decision from another Aegis workflow."

Execute

• **False-positive entry on a native-direct-skill host?** Exit immediately unless

the user explicitly requested TDD or the conversation records `TDD Route: strict`. Return to the selecting workflow or fast path with proportional verification.

• Under `strict`, validate preflight and Change Necessity before production

edits. No production code without an observed failing behavior test first.

• RED (test and observe failure) -> GREEN (minimum owner repair and observe pass)

-> REFACTOR (clean up while green). Apply Regression Scope before closeout.

• GREEN proves only the expressed behavior slice, not parent-task acceptance,

business-value completion or final completion. Use `verification-before-completion`.

Entry Boundary

Enter only for an explicit strict TDD/test-first/RED / GREEN / REFACTOR request or a recorded `TDD Route: strict`. Native-direct-skill hosts must not infer entry from generic risky-code wording. Consume the selected route; a missing or invalid automatic decision returns to its selecting workflow.

Once strict entry is justified, it may cover features, bug fixes, refactoring, behavior/logic, interface/data contracts, shared modules and core logic. Exceptions (ask your human partner): throwaway prototypes, generated code, config files, pure docs cleanup, read-only diagnosis and comment-only changes.

TDD Mode and Route

TDD Mode defaults to `off`, disabling automatic TDD, not completion verification. In `auto`, the selecting workflow chooses strict/light/skipped by task risk.

Before source edits, decide:

Aegis Visibility:
- Why this TDD route is strict, light, or skipped:
- What RED/GREEN proves:
- What still needs verification:

TDD Route:
- Mode: auto | off
- Decision: strict | light | skipped
- Strict authority: explicit user/project request | recorded auto decision | not applicable
- Test posture: diagnostic reproduction | post-change regression | strict RED test
- Reason:
- Verification:

In `auto`, use `strict` for behavior, bugfix, contract, shared/core, producer / consumer, persistence, permission, migration, or meaningful regression risk. Use `light` for tiny low-risk edits with an obvious readback or command check. Use `skipped` for read-only, docs-only, generated, throwaway, comment-only, or environment-bound work where TDD does not fit.

In `off`, do not automatically require TDD, create a strict route, or infer one from risk alone. Explicit user/project TDD requests still apply; risky work may still need regression coverage and `verification-before-completion` before any completion claim. For plan or execution review, `Mode: off / Decision: skipped` is the normal record unless an explicit user/project strict request overrides it. That record does not load this skill or turn a diagnostic reproduction into RED. An approved plan does not supply strict authority by itself. If this skill was loaded anyway without an explicit TDD request or a visible `TDD Route: strict` marker, exit instead of improvising an automatic strict route from risk words alone.

Keep `Aegis Visibility` task-specific: explain the route decision and the regression boundary, not a generic claim that TDD was used.

Preflight Gate

TDD is the implementation discipline for an approved behavior or atomic task. It is not a substitute for task routing, product clarification, or planning.

Before writing tests or production code, stop and route to brainstorming or writing-plans if the current request has any medium- or high-complexity signal:

• multiple files, modules, pages, screens, services, or owners
• user-visible flows such as navigation, onboarding, checkout, lifecycle, or

recovery paths

• state transitions, routing rules, API or data contracts, compatibility

boundaries, migrations, permissions, or persistence

• more than one acceptance path or manual/visual verification requirement
• unclear product behavior, competing constraints, or long-running execution

For these tasks, require a baseline read-set, plan, and atomic tasks before TDD. High-complexity or ambiguous tasks also need a spec/design review before planning. Only proceed directly with TDD for low-complexity work whose intent, owner, compatibility boundary, verification path, and slice goal / success evidence are already clear.

Change Necessity

Before strict RED/GREEN enters production edits, expose why code needs to change: user-visible need, no-change/non-code alternative, why it is insufficient, and the minimum owner/file boundary. This is behavior-triggered, not prompt-triggered: any new source-code path, including a tiny helper, guard, branch, fallback, adapter or owner, needs the decision before RED/GREEN normalizes it as work. Keep this natural; it creates no new artifact or hot-path entry requirement.

• `no-change`: do not write tests or production code for a non-change.
• `docs/config-only`: route to that narrower surface and verify it.
• `needs-clarification`: pause before RED/GREEN.
• `code-change`: carry the minimum boundary into TDD Route, RED and regression.

Complexity Budget

Before strict TDD on non-trivial work, record the planned complexity budget so RED/GREEN does not silently normalize a wrong or overloaded owner.

For the Complexity Budget, state artifact class, current pressure, projected post-change pressure and planned governance in the existing task record.

Use `using-aegis/references/complexity-governance.md` for shared artifact classes, pressure signals, and the meaning of planned governance.

Pre-Edit Complexity Check

Before production code edits, check whether the intended source edit would add logic to an overloaded or wrong owner. Tiny edits can keep this to one line.

Use `using-aegis/references/complexi