git:20260809.4e06658 to git:20260810.48f7be1

---

name: tdd-orchestrator

description: Orchestrates development workflow using Test-Driven Development (TDD) methodology. Coordinates between testing and development skills to ensure quality implementation. Guides the process from test creation to implementation, validation, and documentation updates, strictly following the project-specific guidelines defined in the ./docs/ folder.

---

<execution_mode>

## Mode Detection — Resolve Before Anything Else

```

IF invoked by autonomous-orchestrator:

mode = AUTONOMOUS

→ Read ${featureId}, ${domain}, ${projectPaths} from runtime context

→ Skip all interactive prompts

→ Use docs/specs/${domain}/ as single source of truth

IF invoked directly by human:

mode = INTERACTIVE

→ Follow prompts and manual verification gates normally

```

</execution_mode>

---

<context>

## Project Context — Read Before Starting Any Flow

### Fast-path Orientation (check first):

| Document | Purpose |

|---|---|

| `docs/.digest.md` | Executive summary of architecture pattern, layers, test framework, run commands, coverage thresholds |

| `docs/.graph.json` | Complete relation graph index for 1-hop document lookup and dependency traversal |

*Note: If `docs/.digest.md` is present and provides complete stack/test commands, proceed directly. Fall back to reading full baseline documents below if `.digest.md` is missing or deeper technical context is required.*

### Feature micrograph routing

After macro orientation:

1. Match `${featureId}` and `${domain}` against `.graph.json` node IDs, titles, paths, and tags.

2. Read only frontmatter and top `graph` block from selected `docs/feature/*.md` document.

3. Validate every routed path exists. If any path is stale or feature node is absent, use `rg --files` plus targeted `rg` searches, then continue with discovered paths.

4. RED phase: read relevant `test_files` first.

5. GREEN phase: read relevant files in this order: `entrypoints`, `registration_files`, `reference_files`, then `code_files`.

6. Read full feature prose only when implementation needs design context not present in digest, graph, specs, or routed code.

Do not copy routing arrays into `.graph.json` or create another routing artifact.

### Baseline documents (fallback / deep-dive):

| Document | Purpose |

|---|---|

| `docs/README.md` | Project ecosystem overview; identifies mandatory vs optional docs |

| `docs/adr/ARCHITECTURE.md` | Architectural guides, design patterns, code structure |

| `docs/adr/TESTS.md` | Testing tools, frameworks, and adopted standards |

### Mandatory documents (Autonomous Mode only):

| Document | Purpose |

|---|---|

| `docs/specs/${domain}/003-*-tactical-design.md` | Ordered dev tasks, aggregates, value objects, domain services, persistence interfaces — **implementation blueprint** |

| `docs/specs/${domain}/004-*-test-scenarios.md` | Pre-specified unit/integration/functional scenarios — **drives RED phase; do not invent test cases** |

| `docs/specs/${domain}/REWORK-LOG.md` | Present only on retry — findings from previous validation to address |

### Optional documents:

Read on-demand as indicated in `README.md` or `.graph.json` (API specs, deployment, configuration, etc.).

</context>

---

<retry_fast_path>

## RETRY FAST-PATH (when REWORK-LOG.md exists)

REQUIRED: When `docs/specs/${domain}/REWORK-LOG.md` is present, apply these optimizations:

1. Read `REWORK-LOG.md` FIRST — extract all findings before any other action

2. Prioritize Step 1 (RED) — write NEW failing tests for each finding immediately

3. SKIP Step 5 (Update Documentation) until final validation passes

4. SKIP Step 6 (Machine-Readable Output) until all tests pass — regenerate only at the end

</retry_fast_path>

---

<workflow>

## TDD Workflow — Execute Steps in Order

```

AUTONOMOUS → translate each Given-When-Then from 004-*-test-scenarios.md into executable test code

INTERACTIVE → analyze requirement and identify what needs to be tested

```

- Use test framework and commands from `.digest.md`; consult `docs/adr/TESTS.md` only when digest detail is missing or ambiguous

- Create test structure (unit / integration / functional)

- Write tests following AAA pattern (Arrange, Act, Assert)

- Include positive and negative scenarios

- **REWORK (if `REWORK-LOG.md` present)**: translate each vulnerability and missed edge case from `REWORK-LOG.md` into new failing test cases to ensure regression protection

- **IRON LAW: verify test FAILS before proceeding**

</step>

```

AUTONOMOUS → follow ordered tasks from 003-*-tactical-design.md as implementation blueprint

INTERACTIVE → analyze newly created tests to understand exact requirements

```

- Implement **minimum code** to make tests pass — no over-engineering

- **REWORK (if `REWORK-LOG.md` present)**: address all architectural questions, vulnerabilities, and open points listed in `REWORK-LOG.md` alongside tactical tasks

- After GREEN: refactor to remove duplication and improve readability

- Keep tests green throughout refactor

- Follow constraints from `.digest.md`; consult `docs/adr/ARCHITECTURE.md` only when work crosses architectural boundaries or digest detail is insufficient

</step>

<step id="3" name="Run Tests">

Execute full test suite using verified command from `.digest.md`; fall back to `docs/adr/TESTS.md` when unavailable.

```

IF all tests pass → proceed to Step 4

IF any test fails:

2. Follow 4 debugging phases: Root Cause → Pattern Analysis → Hypothesis → Implementation

IRON LAW: never change tests to force passing unless test was conceptually wrong

4. Re-run tests → repeat until all pass

```

</step>

- Run full test suite one last time — check for regressions

- Provide concrete evidence (actual test command output)

```

Task is COMPLETE only when: 100% tests pass WITH verified output evidence

```

</step>

When applicable, invoke `project-memory` to update:

- OpenAPI/Swagger specs, GraphQL schemas, internal endpoint docs

- Input/Output schemas, descriptions, HTTP status codes

- The `docs/feature/{FEATURE_NAME}.md` file must be updated whenever a feature is created or updated.

> `project-memory` auto-creates baseline docs (`README.md`, `docs/adr/ARCHITECTURE.md`, `docs/adr/TESTS.md`) if missing.

</step>

<step id="6" name="Machine-Readable Output">

Only necessary for AUTONOMOUS mode. If using INTERACTIVE mode, skip this step.

In the case of AUTONOMOUS, save the structured JSON in `docs/specs/${domain}/TDD-OUTPUT.json`:

```json

{

"featureId": "string",

"status": "SUCCESS" | "FAILED",

"metrics": {

"totalTests": 0,

"passed": 0,

"failed": 0,

"coverage": 0.00

},

"modifiedFiles": [

"relative/path/to/modified/file1.ts",

"relative/path/to/modified/file2.py"

],

"reworksCount": 0

}

```

</step>

</workflow>

---

<rules>

## Rules of Conduct

**✅ Do:**

- Read `docs/.digest.md` and `docs/.graph.json` first if present; select one feature micrograph and follow its role-based paths before broad search

- Verify routed files exist; use targeted `rg` discovery when metadata is stale or missing

- Run tests after every change

- Fix production code — never alter correct tests to force passing

- Invoke `project-memory` for new or changes in the project

**❌ Don't:**

- Skip mandatory orientation context or baseline docs in `docs/adr/`

- Write production code before having failing, verified tests

- Assume language, framework, or architecture without consulting docs

- Run package installation commands automatically — always instruct the user

- Declare "tests passed" without executed, verified output in the same message

</rules>

---

<manual_actions>

## Manual User Actions

The following must always be performed by the user — **never automate these**:

| Trigger | Action Required |

|---|---|

| Dependency file changed (`package.json`, `requirements.txt`, `pom.xml`, `go.mod`) | Inform user of the install command to run |

| New environment variables or virtualization needed | Instruct user to configure them |

| Restricted environment | Provide exact terminal commands for user to execute |

</manual_actions>

---

<communication_protocol>

## Console Output Format

At each step, emit a status block:

```

📋 Step {N}: {Step Name} ({skill} — {phase})

✅ / ⚠️ / ❌ {outcome or next action}

```

**Example sequence:**

```

✅ Tests written and verified failing — TESTS.md consulted

✅ Minimal implementation complete; tests green; code refactored

📋 Step 3: Running Tests

📋 Step 3: Re-running Tests

✅ All tests passed

✅ [test output evidence] All tests passed — claim verified

📋 Step 5: Updating Documentation (project-memory)

✅ API contracts updated

📋 Step 6: Machine-Readable Output

✅ JSON report generated

```

</communication_protocol>