Tdd orchestrator

<execution_mode>

Mode Detection — Resolve Before Anything Else

IF invoked by autonomous-orchestrator:
    mode = AUTONOMOUS
    → Read ${featureId}, ${domain}, ${projectPaths}, and ${tasks} 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

<step id="1" name="Write Tests — RED Phase">

AUTONOMOUS → translate the Given-When-Then scenarios relevant to `${tasks}` 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> <step id="2" name="Implement Code — GREEN + REFACTOR Phases">

AUTONOMOUS → implement only `${tasks}`, following their order and dependencies in 003-*-tactical-design.md
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:
    1. Route diagnosis to the developer-debugging agent BEFORE attempting any fix
    2. Follow 4 debugging phases: Root Cause → Pattern Analysis → Hypothesis → Implementation
    3. Fix production code through this tdd-orchestrator RED/GREEN/REFACTOR workflow
       IRON LAW: never change tests to force passing unless test was conceptually wrong
    4. Re-run tests → repeat until all pass

</step> <step id="4" name="Final Validation">

• Execute this final validation gate before declaring any completion
• 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> <step id="5" name="Update Documentation">

INTERACTIVE mode only: 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:

{
  "featureId": "string",
  "status": "SUCCESS",
  "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
}

status must be either "SUCCESS" or "FAILED". Write "SUCCESS" only when the final test run has zero failures.

</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
• Follow this skill's RED phase before writing any production code
• Run tests after every change
• Fix production code — never alter correct tests to force passing
• Execute the final validation step before declaring completion
• 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
• Propose fixes for failing tests without first routing root-cause analysis to developer-debugging

</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

In INTERACTIVE mode, emit a status block at each step. In AUTONOMOUS mode, keep console output minimal and rely on TDD-OUTPUT.json as the machine-readable result.

📋 Step {N}: {Step Name} ({skill} — {phase})
✅ / ⚠️ / ❌  {outcome or next action}

Example sequence:

📋 Step 1: Writing Tests (tdd-orchestrator — RED)
✅ Tests written and verified failing — TESTS.md consulted

📋 Step 2: Implementing Feature (tdd-orchestrator — GREEN + REFACTOR)
✅ Minimal implementation complete; tests green; code refactored

📋 Step 3: Running Tests
⚠️  2 tests failed — routing diagnosis to developer-debugging...
✅ Root cause identified — fixing via tdd-orchestrator

📋 Step 3: Re-running Tests
✅ All tests passed

📋 Step 4: Final Validation (tdd-orchestrator)
✅ [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>