Execute

→ Implementing a feature or bugfix under TDD Route strict? → No production code without a failing test first. Gate: medium/high complexity? → route to brainstorming or writing-plans first. Mode: auto chooses strict/light/skipped by risk; off disables automatic TDD, not completion verification. Cycle: RED (write test → watch it fail) → GREEN (minimal code → watch it pass) → REFACTOR (clean up → keep green) Regression: shared module → related tests. contract change → producer + consumer. core logic → old + new tests. Ripple signal hit → cover producer+consumer or real user path before claiming green. → Done when: chosen TDD Route is recorded, strict-route tests pass, TDD preflight gate passed when applicable, pre-edit complexity risk was checked for non-trivial source edits, and verification-before-completion has fresh evidence.

Test-Driven Development (TDD)

Overview

Write the test first. Watch it fail. Write minimal code to pass.

If you didn't watch the test fail, you don't know if it tests the right thing.

TDD Mode has two values: auto and off. auto lets Aegis choose a TDD Route; off disables automatic TDD routing but never disables verification-before-completion.

When to Use

New features, bug fixes, refactoring, behavior/logic changes, interface/data contract changes, cross-module or shared module changes, core logic refactors.

Exceptions (ask your human partner): throwaway prototypes, generated code, config files, pure docs cleanup, read-only diagnosis, comment-only changes.

TDD Mode and Route

Before source edits, decide:

TDD Route:
- Mode: auto | off
- Decision: strict | light | skipped
- 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. Explicit user/project TDD requests still apply, and risky work may still justify recommending strict TDD. verification-before-completion still applies before any completion claim.

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, and verification path are already clear.

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.

Pre-Edit Complexity Check:
- Target edit file:
- Existing pressure signal:
- Owner fit:
- Safer edit boundary:
- Decision: edit-in-place | extract helper | add owner file | split task | pause for plan update

Pressure signals: 800+ line file, 80+ line block, deep nesting, mixed reasons to change, generic owner receiving new responsibility, owner mismatch, or new fallback/adapter/guard paths. If the decision is pause for plan update, stop TDD and return to writing-plans or brainstorming with the evidence.

When a medium- or high-complexity task needs project records, use configured Aegis workspace support lazily. Prefer the installed Aegis workspace helper (python <aegis-workspace-helper> init --root <target-project-root>) when it is available. If the task needs a process trail under work/, prefer python <aegis-workspace-helper> new-work --root <target-project-root> ... so the intent, checkpoint, drift, and evidence paths are indexed and structurally checkable:

docs/aegis/
  README.md
  INDEX.md
  BASELINE-GOVERNANCE.md
  adr/
  baseline/
  specs/
  plans/
  work/YYYY-MM-DD-<task-slug>/
    10-intent.md
    20-checkpoint.md
    90-evidence.md
    99-reflection.md

Do not promote reusable project facts, decisions, specs, or plans into those directories unless the workflow needs them and no existing project authority already owns them.

Red-Green-Refactor

RED - Write Failing Test

State: input | output | boundary | acceptance criteria. Check existing test coverage first. Write one minimal test showing what should happen.

Clear name, tests real behavior, one thing
</Good>

<Bad>
```typescript
test('retry works', async () => {
  const mock = jest.fn()
    .mockRejectedValueOnce(new Error())
    .mockRejectedValueOnce(new Error())
    .mockResolvedValueOnce('success');
  await retryOperation(mock);
  expect(mock).toHaveBeenCalledTimes(3);
});

npm test path/to/test.test.ts

npm test path/to/test.test.ts

test('rejects empty email', async () => {
  const result = await submitForm({ email: '' });
  expect(result.error).toBe('Email required');
});

$ npm test
FAIL: expected 'Email required', got undefined

function submitForm(data: FormData) {
  if (!data.email?.trim()) {
    return { error: 'Email required' };
  }
  // ...
}

$ npm test
PASS