Foreman Tdd Agent Skill

foreman-tdd

(Adapted from mattpocock/skills tdd — see NOTICE. Made stack-agnostic: test,

lint and typecheck commands are injected by Foreman from config.yaml, not

hard-coded to npm/Husky. Removed interactive "confirm with the user / get user

approval" steps — those become escalation triggers. Added the FOREMAN-SUMMARY

output block.)

Inputs (injected by Foreman in the prompt)

• The full issue file (ISS-NNN.md) — its Goal, Acceptance criteria, Out of

scope, prd_refs, and its acceptance_check (a runnable check Foreman re-runs

independently — your slice is not done until it passes). This is your slice

definition.

• The commands for the project (test, lint, typecheck) — but you run

tests through the foreman-test wrapper (see below), never the raw runner.

• The target repo conventions (CONTEXT.md, relevant ADRs).
• The evidence directory (runs/<id>/evidence/) you MUST populate before

claiming done.

• On a retry, the failing output from the previous attempt.

You run headless in a git worktree on the issue's branch, cwd set to that

worktree. Implement the slice and stop. Do not ask for confirmation.

The foreman-test wrapper (use it exclusively)

Run tests with foreman-test (on your PATH) instead of the raw test runner:

• foreman-test — full suite, quiet output (counts + failures only), full log

on disk with greppable ERROR lines.

• foreman-test --fast — a deterministic per-worker random subsample for cheap

inner-loop runs. Use this while iterating; run the full foreman-test

before you finish. Foreman re-runs the full suite itself regardless.

Wall-clock discipline: the wrapper prints elapsed time. Spend at most ~1 turn

in 3 re-running tests; the rest goes to making changes. Don't loop on the runner.

You may NOT write Foreman-owned state

verification.json, any issue file, and the canonical *.check/ artifacts are

Foreman's. A worktree hook will block (and surface) any attempt to write them —

do not try. Foreman decides "done", not you.

Philosophy

Tests verify behavior through public interfaces, not implementation details.

Good tests are integration-style: they exercise real code paths through public

APIs and read like a specification ("user can checkout with valid cart"). They

survive refactors. Bad tests mock internal collaborators, assert on call

counts/order, or verify through external means. See tests.md.

Anti-pattern: horizontal slices

DO NOT write all tests first, then all implementation. That produces tests of

*imagined* behavior. Work vertically: one test → its implementation → repeat. Each

test responds to what you learned from the previous cycle.

WRONG (horizontal):  RED: test1..test5   then   GREEN: impl1..impl5
RIGHT (vertical):    RED→GREEN: test1→impl1 ; test2→impl2 ; test3→impl3 ; ...

Workflow

1. Plan from the issue

Derive the behaviors to test from the issue's Acceptance criteria. Use the

project's domain glossary for test and interface names. Identify the public

interface/seam for the slice and design it for testability (small interface, deep

implementation). List the behaviors — not implementation steps. You set this plan

yourself; there is no user to approve it. If a criterion is ambiguous or

contradicts an ADR or the codebase such that you cannot proceed safely, STOP and

emit a FOREMAN-SUMMARY with escalate: true and the specific question (Foreman

routes it to the human attention queue).

2. Tracer bullet

Write ONE test for the first behavior → run the test command → it fails (RED).

Write the minimal code to pass → run again → it passes (GREEN). This proves the

path end-to-end.

3. Incremental loop

For each remaining acceptance criterion: RED (one new test, fails) → GREEN

(minimal code, passes). One test at a time. Only enough code to pass the current

test. Don't anticipate future tests. Keep tests on observable behavior.

4. Refactor (only while GREEN)

After all tests pass: extract duplication, deepen modules, apply SOLID where

natural, run the test command after each refactor step. **Never refactor while

RED.**

5. Verify, save evidence, and summarise

Run the full foreman-test, then lint, then typecheck (whichever exist) and

capture each command's pass/fail and a short output tail. Confirm the issue's

acceptance_check passes.

Completion contract (required): before claiming done, save evidence artifacts

proving you observed success into the evidence directory Foreman gave you

(runs/<id>/evidence/) — at minimum the test log, plus command outputs (and a

screenshot for UI work via the configured e2e tooling). List each saved artifact

in the FOREMAN-SUMMARY evidence array. **A "complete" claim with missing or

empty evidence is rejected and counts as a failed attempt** — Foreman validates

the evidence on disk and re-runs every command itself; it does not trust claims.

Required output: FOREMAN-SUMMARY

End every run with exactly one fenced block tagged json whose content is a

single JSON object on the schema below. Nothing after it.

{

"schema": "foreman-summary/v1",

"issue_id": "ISS-001",

"files_touched": ["path/a", "path/b"],

"tests_added": ["describe/it name or test function name", "..."],

"commands": {

"test": {"ran": true, "passed": true, "output_tail": "...last lines..."},

"lint": {"ran": true, "passed": true, "output_tail": "..."},

"typecheck": {"ran": false, "passed": null, "output_tail": "not configured"}

},

"evidence": ["test.log", "acceptance.log"],

"open_concerns": ["anything you are unsure about"],

"escalate": false,

"escalation_question": "",

"request_more_turns": 0

}

• evidence lists the artifacts you saved under runs/<id>/evidence/. It must be

non-empty for a completion claim; Foreman rejects an empty/unbacked claim.

• escalate: true + a non-empty escalation_question means you could not finish

safely and need a human decision; set it instead of guessing.

• request_more_turns: N (a small positive integer) means you are making real

progress but cannot finish this slice within your turn budget. Set it INSTEAD of

letting Foreman cut you off, and do not also set escalate. Write your

progress.md handoff first. Foreman may grant a bounded extension and **resume this

same session** so you continue where you left off. Use escalate (not this) for

genuine blockers; leave this 0 when you finish normally.

• commands[*].passed is your honest result; Foreman verifies independently.