2026-08-10_13-23-08_claim-office-example-mapping_v6.6-lab-split-pi_gpt-5-6-sol-4

Imported from marcoemrich/agentic_coding_lab (experiments/runs/2026-08-10_13-23-08_claim-office-example-mapping_v6.6-lab-split-pi_gpt-5-6-sol-4/AGENTS.md). Install upstream with npx skills add marcoemrich/agentic_coding_lab --skill 2026-08-10_13-23-08_claim-office-example-mapping_v6.6-lab-split-pi_gpt-5-6-sol-4. Copyright stays with the author.

Test-Driven Development (TDD) Rules -- Hybrid (v6.6, pi)

Lab-only content is fenced at the end of this file. Everything between the LAB-ONLY:START / LAB-ONLY:END markers is measurement infrastructure for the agentic-coding-lab harness -- autonomous execution, the done-marker contract, and the phase-continuation fix. To export this workflow for real-world use, delete that block. Nothing above it is lab-specific.

CRITICAL: Mandatory Output Format

This workflow runs on pi, where skills are auto-loaded documents, not tool calls. The model reads each SKILL.md once and then follows its instructions directly. This means the measurement pipeline cannot count tool invocations to track cycles. Instead, it relies on text markers in the assistant output.

Phase-Completion Markers Are MANDATORY

Every TDD phase MUST produce a specific text marker in your output. These markers are mechanically parsed to compute cycle_count, predictions_correct_rate, and refactorings_applied. Missing markers silently zero the corresponding metric, invalidating the data point.

Format for each Red phase output:

## Red -- Test N: <test description>

<prediction and failure verification steps>

Red Phase Complete:
**Compilation Prediction**: <what you expect> Correct
**Runtime Prediction**: <what you expect> Correct

<Result summary>

The two prediction lines (Compilation Prediction: ... Correct / Runtime Prediction: ... Correct) are parsed mechanically. You MUST output them verbatim with Correct or Incorrect at the end. Do not abbreviate, summarize, or collapse them. Do not skip them when a test already passes -- in that case, write:

## Red -- Test N: <test description>

Test already passes -- no new failure to fix. Skipping green/refactor.

Format for Green phase output:

## Green -- <brief summary of what was added>

Format for Test List phase output:

## Test List

<test list details>

Overview

This project follows strict Test-Driven Development practices using the Red-Green-Refactor cycle. v6 keeps red and green in a shared context so the predictions, error messages, and minimal implementations stay coherent -- and isolates refactoring so the model evaluates the resulting code on its own merits.

Architecture: Skills + Subagent

• test-list, red, green -- Their SKILL.md files are auto-loaded as context. Read each SKILL.md before the first use of that phase, then follow its instructions directly in the main context. You execute the phase yourself, following the skill content.
• Refactor -- Runs as a Subagent with isolated context via the subagent tool. The refactor agent sees only the current source/tests, not the full red/green history. Hypothesis: refactoring benefits most from a fresh perspective free of implementation bias.

Do NOT skip reading the skill files. Do NOT skip the mandatory output markers.

Which Mechanism to Use:

TDD Workflow

1. Test List Phase

READ SKILL: .pi/skills/test-list/SKILL.md

Provide: feature, test file path, implementation file path, requirements.

The skill creates a comprehensive test list using it.todo() covering every rule and example from the specification.

DO NOT write the test list yourself. Follow the skill instructions and produce the ## Test List marker.

DO NOT end your turn after the test list. The moment the ## Test List marker is complete, continue in the same turn into the Red Phase for test 1 (read red/SKILL.md, produce ## Red). See "Phase Continuation" in the LAB-ONLY block at the end of this file -- the Test-List -> Red boundary is where runs most often stall.

2. Red Phase

READ SKILL: .pi/skills/red/SKILL.md

Provide: test file path, which it.todo() to activate, current passing-test count, implementation file path.

The skill activates exactly ONE test, makes explicit predictions, and verifies failure.

DO NOT write test code yourself. Follow the skill instructions and produce the ## Red and Red Phase Complete: markers with prediction lines.

3. Green Phase

READ SKILL: .pi/skills/green/SKILL.md

Provide: test file path, failing test name, current error, implementation file path.

The skill implements minimal code to make the test pass -- hardcoded returns are fine for early tests.

DO NOT write implementation code yourself. Follow the skill instructions and produce the ## Green marker.

4. Refactor Phase

INVOKE SUBAGENT: Use the subagent tool with these parameters:

{
  "agent": "refactor",
  "agentScope": "both",
  "task": "Test file: src/<feature>.spec.ts\nImplementation file: src/<feature>.ts\nPassing tests: <count>\nRecent Green phase: <one-line summary of what was just added>\n\nRefactor the implementation while keeping all tests green.\n\nRun autonomously, return when done."
}

agentScope: "both" is REQUIRED because the refactor agent lives in .pi/agents/ (project-local). Without this flag the subagent extension only sees user-level agents and the call fails with "Unknown agent: refactor".

The agent will improve code while keeping tests green:

• MUST attempt at least one refactoring (or document why none is possible)
• Evaluate naming FIRST
• Apply Four Rules of Simple Design (priority order)
• Calculate APP (Absolute Priority Premise) mass before/after

DO NOT refactor code yourself -- let the subagent do it. After it returns, read its summary, apply any test-runs needed for sanity, and proceed to the next Red phase.

5. Repeat

Return to step 2 (Red phase) for the next test.

6. End-Refactor (once, after the last green cycle)

INVOKE SUBAGENT: subagent tool with agent: "end-refactor", agentScope: "both"

After the last per-cycle refactor returns and all tests pass, invoke the end-refactor subagent exactly once. It refactors the whole production tree (src/, excluding *.spec.ts) using deterministic pre/post measurements: ESLint smells + SonarJS cognitive complexity, plus APP mass and McCabe cyclomatic complexity. It iterates one change at a time until no metric improves further.

{
  "agent": "end-refactor",
  "agentScope": "both",
  "task": "Implementation files: src/<all non-spec *.ts>\nTest files: src/<*.spec.ts>\nPassing tests: <count>\n\nRun the final metric-driven refactoring pass over the whole src/. Iterate ONE change at a time with pre/post measurement (ESLint, cognitive, APP, McCabe). Stop when no metric improves further."
}

DO NOT refactor the whole src/ yourself — delegate to the end-refactor subagent.

Core TDD Principles

TDD Mindset

TDD practices will feel counterintuitive:

• Hardcoded returns feel "too simple" -- This is correct!
• The urge to implement ahead is strong -- Resist this
• Minimal steps feel inefficient -- They actually accelerate development
• Predictions feel unnecessary -- They build crucial understanding

Common TDD Failure Modes

• MISSING OUTPUT MARKERS -- The most critical failure mode on pi. Every cycle MUST have ## Red and ## Green headings. Every Red cycle with a failing test MUST have Red Phase Complete: with prediction lines.
• Multiple active tests at once
• Implementing beyond what tests demand
• Skipping predictions
• Avoiding refactoring
• Refactoring in the main context instead of via the subagent

Technical Setup: TypeScript and Vitest

TypeScript Conventions

• Use proper type annotations
• Leverage TypeScript's type checking during development
• Name files after their content
• Import with explicit .js extensions for local modules

Test File Conventions

• Use .spec.ts extension for test files
• Place tests near implementation files
• Import test functions: import { describe, it, expect } from "vitest"

Running Tests

Run tests with pnpm test.

Example Test Template

The test list comes from the kata's specification -- do not add generic "validate input types" or "edge cases" tests unless the spec calls for them.

// some-feature.spec.ts
import { describe, it, expect } from "vitest";
import { someFeature } from "./some-feature.js";

describe("Some Feature", () => {
  it.todo("[first behaviour from the spec]");
  it.todo("[second behaviour from the spec]");
});

Workflow Sequence

1. Test List Phase -- Read skill, produce ## Test List marker
2. For each test:
   • Red Phase -- Read skill, produce ## Red and Red Phase Complete: with predictions
   • Green Phase -- Read skill, produce ## Green marker
   • Refactor Phase -- Invoke subagent tool with agent: "refactor", agentScope: "both"
3. Continue until all tests are implemented and passing
4. End-Refactor -- invoke subagent with agent: "end-refactor", once, over the whole src/

Required Task Content for the Refactor Subagent

The refactor subagent has no memory of the red/green phases. Pass everything it needs in the task parameter:

Test file: [path]
Implementation file: [path]
Passing tests: [count]
Recent changes: [one-line summary of the Green phase]

After the subagent returns, read its summary and proceed directly to the next Red phase.

Remember

• ALWAYS PRODUCE THE MANDATORY MARKERS -- ## Red, Red Phase Complete:, ## Green, ## Test List
• ALWAYS USE THE SUBAGENT for refactor -- subagent tool with agent: "refactor", agentScope: "both"
• Follow skill content (test-list/red/green SKILL.md) for the actual work
• Pass agentScope: "both" to the subagent tool so the project-local refactor agent is discovered
• Trust the process -- discomfort is a signal you're doing it right

Lab-Only Execution Rules

This block is lab infrastructure, not TDD methodology. Everything between LAB-ONLY:START and LAB-ONLY:END exists to make a run measurable and unattended inside the agentic-coding-lab harness.

To export this workflow for real-world use: delete this whole block. Nothing outside it is lab-specific. Removing it drops the autonomous-execution mandate, the done-marker contract, and the phase-continuation fix — which is exactly what an interactive or human-in-the-loop setup wants.

Autonomous Execution

The TDD cycle runs autonomously -- no human-approval gates between phases. The measurement pipeline parses the output text for phase markers and subagent tool calls; user prompts inserted between phases would split that sequence and produce unattributable cycles.

When executing:

• Do NOT wait for human approval between phases
• Complete the full TDD cycle without interruption

Append an autonomy instruction to every subagent task parameter, e.g. Run autonomously, return after completion.

Done Marker

When all tests are implemented and passing AND the end-refactor pass has completed, write a file experiment-done.txt with the single word DONE as its only content. Do not write any other summary or report file.

This is parser marker P7 -- see experiments/workflows/MARKERS.md. Without it the run-driver cannot detect clean termination and the container hits its timeout, flagging the run exit_reason: timeout.

Phase Continuation

Origin: on pi, some models (qwen, kimi, minimax) read a prose phase announcement ("Proceeding to Red phase") as a turn terminus and settle at the Test-List -> Red boundary. The run dies mid-flight with no error. This section is the fix. It is a workaround for a harness-specific parsing quirk, not a workflow advance -- it carries real prose cost (see RQ-lean / RQ-rules on added-instruction overhead), so it lives here in the droppable block rather than in the workflow proper.

This entire workflow -- Test List, then Red/Green/Refactor for every test, through to writing experiment-done.txt -- is one single autonomous turn. There are no human-approval gates and no natural stopping points between phases.

A phase-completion line (e.g. "Test List Phase Complete", "Red Phase Complete", a returned refactor subagent) is a checkpoint, not a terminus. After emitting it you MUST immediately continue with the next phase's action in the same turn:

• After the Test List -> read red/SKILL.md and produce ## Red for test 1.
• After Red -> read green/SKILL.md and produce ## Green.
• After Green -> invoke the refactor subagent.
• After Refactor returns -> produce ## Red for the next test.
• After the last cycle -> invoke the end-refactor subagent once.

The only place your turn may end is after you have written experiment-done.txt containing DONE. Ending the turn on a "Proceeding to..." / "Next Step..." announcement -- without actually taking that step -- is the single most common failure mode on this harness and invalidates the run. Announcing an action is not doing it; always do it in the same turn.

NEVER STOP AT A PHASE BOUNDARY -- Test List -> Red -> Green -> Refactor -> next Red all happen in one turn. The only turn-end is after experiment-done.txt says DONE.