Bring PRD seeding into Tilth as `uv run tilth prep-feature`

[samkeen]

Related: #10 (prd.json leak from worktree). Closes #10 when landed — the artifact-placement section below resolves the leak by construction.

Why

Tilth runs are only as good as their seed. Today the seeding workflow lives in two places that aren't Tilth:

1. A Claude Code skill (tilth-prd-seeder) that runs an interview against the target codebase and writes prd.json + matching tests/test_t00N_*.py.
2. The user, who is expected to commit those artifacts into the source repo before running uv run tilth <workspace>.

This has three problems for Tilth's mission:

• It pollutes the target repo. A finished feature should ship via a clean PR. Today prd.json (and progress.txt, post-run) ride the session branch into the PR diff. The seeder skill writes prd.json to <workspace>/prd.json, where it gets committed by git add -A in commit_task.
• The seeder isn't discoverable or versioned with the harness. It only exists for users who installed the skill. Anyone else hits a docs gap at the most load-bearing step of using Tilth on a non-demo codebase (docs/getting-started/your-own-project.md).
• Seed quality is the single biggest predictor of run quality. A weak seed collapses the quality gate to "ruff passed + judge said OK", which the docs explicitly call out as the worst-case failure. The interview that produces a strong seed should ship with the harness.

Proposed shape

A new subcommand:

uv run tilth prep-feature <workspace>

It runs the seeding interview against <workspace>, produces the seed, and stages it as a prepared (but not started) session under sessions/<id>/. The next uv run tilth <workspace> either auto-picks the prepared session for that workspace or accepts --session <id> to choose explicitly.

This makes prep-feature a peer of --resume, --reset, --visualize — all session-lifecycle verbs.

What prep-feature does (distilled from the skill)

Sequence matters; same order as tilth-prd-seeder/SKILL.md:

1. Confirm intent. One sentence: what feature/refactor, what workspace path. Paraphrase if both were in the prompt; ask one targeted question otherwise.
2. Strategic codebase scan. Seed-steered, not exhaustive: glob/grep for the area the feature touches, sample 2–4 most-relevant files end-to-end, inventory existing tests/ for style/fixtures, check for an existing prd.json (and continue task IDs from the highest existing T-NNN). Spawn an Explore subagent in parallel for unfamiliar/large codebases.
3. Anchored interview. Adaptive, one question per turn. Mix AskUserQuestion (decision-style, 2–4 plausible options surfaced by the scan) and free-form (clarification, motivation, scope-boundary calls). Return to the codebase mid-interview when an answer makes a new area relevant.
   • Coverage targets (all must be hit before writing): motivation & context, observable contract, task slicing + per-task acceptance criteria, test strategy, scope boundaries, risks & open questions.
4. Surface blockers as they appear. Refactor with no existing tests to ratchet against. Task slice that contradicts the code. Acceptance criterion that isn't programmatically checkable. Slice too coarse. No tests/ directory yet.
5. Wrap interview when there's enough. Don't drag to 100% certainty; unknowns belong in the chat summary.
6. Confirm IDs, slugs, workspace. Restate the path, propose contiguous T-NNN IDs and test_<task-id-lower>_<slug>.py file names via AskUserQuestion. The naming pattern is load-bearing — Tilth's pytest filter keys on it.
7. Write the artifacts. prd entries (always status: "pending", append-don't-overwrite) and one matching test file per task (assertion-clusters mapping 1:1 to acceptance criteria, matching project's existing test style). See "Where artifacts land" for where they're written.
8. Surface chat summary (TL;DR + Open Questions + Blockers, no disk writes), then suggest next steps and stop.

Behavior to avoid (carry across from the skill verbatim):

• Don't skip the codebase scan; don't read every file end-to-end in step 2.
• Don't batch interview questions into a megaprompt.
• Don't fabricate acceptance criteria the user didn't agree to.
• Don't write a prd entry without its matching test file (the pair is the unit).
• Don't overwrite an existing prd.json; don't reuse existing task IDs.
• Don't paper over contradictions because they're awkward.

Refuse / redirect cases (also from the skill):

• Bug fix small enough for one task → write the single entry directly, no interview.
• Greenfield with no existing code → can't anchor; redirect to architecture sketch first.
• Already-detailed PRD just needs more tasks → open and edit directly.

(The full skill is at /Users/sam/.claude/skills/tilth-prd-seeder/SKILL.md with the file template at references/tilth-task-seed-template.md. The substance ports into the new command verbatim; the rest of this issue is about how it lives inside Tilth.)

Where artifacts land

Aligned to the three invariants this touches (Brain/Hands/Session split, agent-visibility boundary, worktree-branch-not-auto-merged):

Artifact	Lives in	Why
prd.json (runtime)	sessions/<id>/prd.json	Session state. Mutated by harness as tasks flip pending → in_progress → done. Outside the worktree — agent never sees it (closes #10).
Test files (tests/test_t0NN_*.py)	<workspace>/tests/	Legitimate repo artifact. They are the quality gate; they should be reviewed in the PR and committed to main like any other test.
progress.txt	sessions/<id>/progress.txt	Within-session journal. Outside worktree — no PR pollution.
AGENTS.md	<workspace>/AGENTS.md	Cross-session memory channel. Legitimate repo artifact under modern conventions; user may commit and share across machines. Stays in worktree.

Net effect: target repo gains tests (intentional) and possibly AGENTS.md (user's call). No prd.json, no progress.txt, no .tilth/ directory, no auto-.gitignore writes. A feature dev → PR → merge cycle leaves zero Tilth-specific runtime artifacts in origin.

prep-feature's write path

• Creates sessions/<id>/ and writes sessions/<id>/prd.json directly (no intermediate "seed file in the source repo" step).
• Writes test files to <workspace>/tests/test_t0NN_*.py as the skill does today.
• Records a session_prepared event in events.jsonl with the seed details for traceability.
• Session has status: prepared in checkpoint.json — distinguishable from "in-progress" and "all_done".

Resume / pickup flow

• uv run tilth <workspace> looks for the most recent prepared session for that source path. If exactly one, uses it. If multiple, lists them and asks. If zero, errors with: "No prepared session. Run uv run tilth prep-feature <workspace> first."
• uv run tilth --session <id> accepts an explicit session.
• --resume semantics unchanged for in-progress sessions.

Migration

• Existing demo repo (AlteredCraft/tilth-demo-todo-cli) has prd.json and progress.txt committed in main. Document a one-time cleanup: delete from main; future seeding happens via prep-feature and lands in sessions/<id>/.
• Tests in <workspace>/tests/ already work and stay where they are.
• The standalone tilth-prd-seeder Claude Code skill gets deprecated in favor of uv run tilth prep-feature. Skill docs point users at the new command.

Open questions

• Worker model for the interview. Same model the harness uses for run-time tool-use? Or a smaller/cheaper model? The interview is conversational + reading code; doesn't need the same horsepower as a task-execution turn. Probably configurable via TILTH_PREP_MODEL env var, defaulting to the same model.
• Auto-start option. Should prep-feature end by asking "kick off the run now?" (Y/n) — or always stop after writing the seed and let the user invoke tilth <workspace> separately? Skill's current behavior is the latter (interview → summary → stop).
• Interactive interview UX in a CLI. The skill ran inside Claude Code where AskUserQuestion is first-class. In uv run tilth prep-feature, do we render AskUserQuestion-equivalents as numbered TTY prompts? Use a richer prompt library (questionary)? Or run the interview via the LLM's tool-use loop with a prompt_user(question, options) tool the harness implements?
• Re-prep on an existing prepared session. If the user runs prep-feature on a workspace that already has a prepared session, do we append to it (continue the PRD), replace it, or refuse? Probably refuse with a hint to --reset <id> or --session <id> --append.

Related

• prd.json is reachable from the worker (invariant 2 leak) #10 — prd.json reachable from the worker. Closed by the artifact-placement section here.
• Research: Docker Sandboxes (sbx) as opt-in process isolation #13 — opt-in process isolation. Complementary; this issue is about where artifacts live, Research: Docker Sandboxes (sbx) as opt-in process isolation #13 is about whether the worker can reach them regardless of where they live.
• tilth/loop.py:_load_prd, tilth/loop.py:_save_prd — touched by the artifact move.
• tilth/memory.py:_load_progress_tail, tilth/memory.py:append_progress — touched by the progress.txt move.
• docs/getting-started/your-own-project.md — currently describes the manual seed flow; rewrites around prep-feature once landed.

[samkeen]

existing skill for reference

====================================
SKILL.md

---
name: tilth-prd-seeder
description: Produces a Tilth task seed (prd.json entries + matching acceptance tests) from a feature or refactor request, via an interview anchored on the target app's codebase. Use whenever the user wants to "seed Tilth with this feature", "draft a prd.json for adding X to my app", "generate Tilth tasks and tests for this refactor", or "create acceptance criteria and unit tests for a new feature so Tilth can build it". Do NOT use for: bug fixes small enough to fit a single PRD task (just write the task directly), greenfield projects with no existing code (the interview can't be anchored), or editing/extending an already-detailed PRD (open and edit it directly).
argument-hint: [Feature description or refactor request, plus path to the target app's code]
---

# Tilth PRD Seeder

Interview the user to produce a focused **Tilth task seed**: new entries appended to `<workspace>/prd.json` plus one matching pytest acceptance-test file per task under `<workspace>/tests/`. The output is consumed by the Tilth harness on the next `uv run tilth <workspace>` invocation — the worker reads one task at a time, the harness gates progress on those test files.

## Why this skill exists

A Tilth run is only as good as its seed. Vague task descriptions waste tokens and produce branches the human reviewer ends up rewriting; missing or weak acceptance tests collapse the quality gate down to "ruff passed and the judge model said it was fine" — which is the worst-case failure: confident-sounding green that masks broken work. The interview exists to catch both before code gets written: it pulls the feature apart into Tilth-shaped slices, pins each slice to a checkable contract, and ensures every contract has a test file the harness will actually run. The invariant: **ground in the target app's code first, slice the work in conversation, then write prd.json + tests together as one seed.**

## Workflow

The sequence matters. Do not jump ahead.

### 1. Confirm the seed in one sentence

Before opening any code, get the user's intent in one sentence: *what feature or refactor are we seeding, and where is the target app?*

If they named both clearly in the prompt, paraphrase and confirm — don't make them repeat themselves. If the feature is vague ("improve the export flow") or the path is missing, ask one targeted question to nail down (a) the feature/refactor in concrete terms and (b) the absolute path to the workspace. Scanning the wrong codebase is wasted work.

### 2. Strategic codebase + Tilth-seed scan to seed context

The grounding read is **steered by the seed, not exhaustive.** Read what the feature makes relevant; ignore what it doesn't. The goal is to know enough to ask sharp anchored questions in step 3 and to recognize when an answer contradicts the code — not to internalize the whole app. Deep reading for writing the prd entries and tests happens after the interview narrows scope (see step 7), not here.

Specifically:

- **Inventory `prd.json` and `tests/`** at the source repo root. These are the only two artifacts the skill reads or writes. (`AGENTS.md` and `progress.txt` live in Tilth's session worktree at runtime — they are not the skill's concern.) If `prd.json` exists, parse it and find the highest existing `T-NNN` id — new entries continue from `N+1`. If `tests/` exists, sample one or two files to lock onto the project's test patterns (subprocess vs in-process, fixture style, naming convention).
- **Locate the area the feature touches.** Glob/Grep for likely module names, entrypoints, CLI subcommands, route handlers, models. Read 2–4 of the most relevant files end-to-end.
- **Skim adjacent material:** existing tests in the affected area (they tell you what the test surface looks like), `pyproject.toml` or equivalent (deps, test config), any existing similar feature (the prd should slice the new work the same way).
- **For refactors specifically:** locate the existing tests covering the code being refactored. If they don't exist, flag it in step 4 — a refactor with no behavior-preservation tests cannot be safely seeded for Tilth (there's nothing to ratchet against).
- If the codebase is large or unfamiliar, spawn an Explore subagent in parallel rather than reading serially. Tell it: "Inventory the project at `<path>` for a Tilth seed on `<feature>`. Identify (a) where this work would naturally live, (b) similar existing features and how they were structured, (c) existing test patterns and fixtures, (d) the highest existing T-NNN in `prd.json`. Report under 400 words."

After the scan, tell the user what you found in *one paragraph max* — the `prd.json` state (next task ID, or "no prd.json yet"), the area of the code the feature touches, and the test pattern in use. Let them redirect ("no, that's the v1 module, we use the v2 path").

### 3. Anchored interview

Drive the interview adaptively — match the tool to the question type:

- **`AskUserQuestion`** for **decision-style** questions — choices among 2–4 plausible options the codebase scan has surfaced. These are the high-leverage moments. Always include `"Other (I'll specify)"` so the user is never boxed in. Suggested options should be concrete and grounded in what's actually in the code (e.g., "Extend the existing `exporters/csv_exporter.py` module" rather than "Reuse existing code").
- **Free-form text** for **clarification-style** questions — places where the code is vague, contradictory, or silent and you need the user's own words to fill the gap. Motivation, scope-boundary judgment calls, and risk callouts usually want free-form.

One question per turn; follow up freely when an answer surfaces a new question or contradicts the codebase.

**Return to the codebase during the interview when needed.** The step-2 scan was strategic, not exhaustive. When an answer makes a new area of the code relevant — a claim worth validating, an integration point the user assumes works a certain way, a module worth a closer read before the next question is sharp enough — go back and read or grep. Anchoring is continuous; don't bluff past a question with vibes from a half-read file.

**Coverage targets** (must be covered before writing the seed; order is up to you):

- **Motivation & context** — why this feature/refactor, why now, who's asking, what changes for the human or downstream system if it ships. Quote the user's framing if it captured the why.
- **Observable contract** — the concrete, externally-checkable behavior changes. What CLI invocation produces what output? What function signature with what return shape? What file format changes? What HTTP request returns what status and body? This is what the tests will pin down — push the user toward specifics. "User can export a CSV with columns A, B, C and a header row" beats "export works."
- **Task slicing + per-task acceptance criteria** — how to break the work into 3–8 small, sequenced Tilth tasks. Each task should be (a) shippable as a single atomic commit, (b) buildable on the prior tasks' state, (c) verifiable by a checkable test. For each task, draft the 2–4 acceptance criteria that will become assertions. The first task in a slice is often a sentinel/scaffold (cf. the demo's T-001 `hello.py`); the last is usually the user-visible payoff.
- **Test strategy** — what shape do tests take for *this* project? Subprocess-style CLI tests with `tmp_path` (like the demo), in-process unit tests with fixtures, HTTP integration tests, snapshot tests? What fixtures and helpers exist already? What should be mocked vs. exercised end-to-end? Anchor the answer on the test patterns the scan found.
- **Scope boundaries** — explicitly *what is out of scope* for this seed. This is the highest-leverage area — ask at least one out-of-scope question even if the user thinks the scope is obvious. A Tilth seed that quietly grows scope mid-run burns hours.
- **Risks & open questions** — performance concerns, security/privacy considerations, backwards compatibility, data migration risks, things the user is unsure about. These don't always block seeding, but they belong in the chat summary so the reviewer sees them before merging the session branch.

The test for an anchored question: *could this have been asked before the scan?* If yes, it's generic — replace it with one the scan made possible.

**Examples of good interview behavior:**

> User: "Add a `priority` field to the todo CLI so I can sort by it."
> *(After scanning: `todo_cli/` has `add`, `list`, `done`, `remove` subcommands; on-disk format is `- [ ] <text>` / `- [x] <text>` in `TODOS.md`; the existing tests use subprocess + `tmp_path` and assert exact file contents.)*
> Good question: "The on-disk format is currently `- [ ] <text>` lines in TODOS.md. Where should priority live? [Suffix tag like `- [ ] buy milk !high` / Prefix tag like `- [ ] [P1] buy milk` / Separate JSON sidecar file / Other]"
> Bad question: "How should priority work?" *(Generic — the scan surfaced three plausible formats; ask which.)*

> User: "Slice it into adding the field, then sorting, then a UI."
> *(But the project has no UI — it's CLI-only, and the user just said "the todo CLI." The scan confirmed only `todo_cli/__main__.py` exists, no web/TUI code.)*
> Good followup: "I only see CLI code in the project — `todo_cli/__main__.py`, no web/TUI module. Did you mean a `--sort priority` flag on `list`, or is there a UI layer I'm missing?"

### 4. Surface blockers and contradictions as you go

Flag these as soon as you spot them — don't bury them in the prd or tests:

- **Refactor with no existing tests** to ratchet against. Tilth's quality gate for a refactor is "behavior preserved" — without tests capturing the old behavior, the harness can't tell you when the refactor broke something. Surface it: "I don't see existing tests for `<module>`. A Tilth-seeded refactor needs them — want to slice the first 1–2 tasks as 'capture current behavior in tests', then refactor against those, or pause and add the tests first?"
- **Task slice contradicts existing code.** The user proposed a slice that assumes a function/module exists, but the code is structured differently. "Task 3 assumes a `Renderer` class; the project has `render()` as a module-level function. Should we refactor first, or rework the slice?"
- **Acceptance criterion isn't checkable.** "Users find it intuitive" can't be a test. "Returns exit code 0 and stdout matches `^\d+ items\n$`" can. Push back: "That criterion isn't programmatically checkable — what's the concrete behavior the test would assert?"
- **Slice is too coarse.** A single Tilth task should land in one cohesive iteration set (the demo's tasks each fit in a few hundred LOC of diff). If a proposed task touches 8 files across 4 modules, push for sub-slicing.
- **No `tests/` directory yet.** If the project has no tests directory at all, surface it: "There's no `tests/` directory at the repo root. I'll create it as part of writing the new test files — confirm that's the right location, or point me at the convention you use."

Frame contradictions as questions, not assertions. If a blocker is severe enough to change feasibility (e.g., a refactor with no test coverage and the user doesn't want to add tests first), pause and ask how to proceed.

### 5. Wrap up the interview

When you have enough to write the seed, say so explicitly: "I think I have enough — let me write the prd entries and test files. I'll flag anything I'm still unsure about in the chat summary." Don't drag the interview out chasing 100% certainty; unknowns belong in the Open Questions list of the chat summary, not in more interview turns.

### 6. Confirm task IDs, slugs, and workspace path

The save locations are convention-fixed (prd.json at workspace root, tests under `<workspace>/tests/`), but the *names within them* aren't. Before writing, confirm via `AskUserQuestion`:

- **Workspace path** — the absolute path you'll write into. Restate it from the seed.
- **Task ID range** — propose contiguous IDs continuing from the highest existing `T-NNN` in `prd.json` (or `T-001` if no prd.json exists yet). Show the proposed list of `T-NNN: <title>` pairs.
- **Test file slugs** — propose `test_<task-id-lower>_<short-slug>.py` for each task (e.g., `test_t006_priority_field.py`). Slugs come from the task title.

Do **not** silently pick. The Tilth harness's pytest filtering is based on exact file naming — getting it wrong silently breaks the quality gate.

### 7. Write the prd entries and test files

Use [`references/tilth-task-seed-template.md`](references/tilth-task-seed-template.md) verbatim — same structures, same conventions.

This is the step where deep reading happens. Now that the slice is locked, go back to the modules the user named as load-bearing and read them carefully — pull real import paths, verify the test fixtures actually exist, check the project's existing test style and copy it (don't import patterns that aren't already there). The scan in step 2 was for the interview; this read is for the artifact. The prd descriptions should reference real file paths and real symbols; the test files should import the real modules with the real names and use the real fixture patterns.

Rules when writing:

- **Append, don't overwrite.** If `prd.json` exists, read it, append the new entries, write it back as one valid JSON array. Preserve existing tasks verbatim, including their `status` values. If it doesn't exist, create it as a JSON array containing only the new entries.
- **Always `status: "pending"`** for new entries. The harness flips status; the seed never sets `in_progress` or `done`.
- **Acceptance criteria map 1:1 to test assertions.** If a criterion says "exits 0 and stdout is `(no todos)\n`", the test file should have an assertion checking exactly that. A criterion the tests don't pin down is decorative; an assertion that doesn't correspond to a criterion is scope creep.
- **One test file per task, named `test_<task-id-lower>_<slug>.py`.** The harness filters pytest to active + completed tasks by this naming pattern. Files outside the pattern get skipped silently.
- **Match the project's test style.** If existing tests use subprocess + `tmp_path`, write yours the same way. If they use in-process imports with pytest fixtures, do that. Don't introduce a new style.
- **Quote the user's framing for motivation** when their phrasing was strong. The prd `description` field is what the worker sees as the user message — their voice carries the why better than your paraphrase.
- **Be concrete in descriptions.** Reference real paths and symbols. `todo_cli/__main__.py:main()` is more useful than "the CLI entrypoint."
- **Don't touch `AGENTS.md` or `progress.txt`.** Those are runtime artifacts Tilth manages inside the session worktree — not source-repo files this skill reads or writes. The skill's surface is `prd.json` + `tests/` only.

After writing, surface the chat summary (do **not** write to disk):

- **TL;DR.** One line per task: `T-NNN: <title> → <one-sentence outcome>`.
- **Open Questions.** Anything you guessed at, anything the user was unsure about, anything that needs a decision before the Tilth run starts.
- **Blockers / contradictions surfaced.** Only if you flagged any during the interview.

### 8. Suggest next steps and stop

End with a short list in chat — *do not* create them as artifacts:

- "Want to dry-run by reading the new prd entries and tests together to sanity-check the criterion↔assertion mapping before committing?"
- "Ready to commit the seed and run `uv run tilth <workspace>`?"
- "Should we walk through the open questions before kicking off the run?"

Then stop. The skill produces the Tilth task seed only.

## Behavior to avoid

- **Don't skip the codebase scan.** A prd written without grounding is just a wishlist; tests written without grounding don't import the real symbols and fail at collection time.
- **Don't read every file end-to-end in step 2.** Strategic, seed-steered reading first; the deep read happens in step 7 once the slice is locked.
- **Don't batch interview questions into a single megaprompt.** Adaptivity is the value. One question, get the answer, decide what to ask next.
- **Don't fabricate acceptance criteria the user didn't agree to.** If a behavior wasn't specified, write it as an open question in the chat summary — don't invent a contract the worker will then try to satisfy.
- **Don't write a single prd entry without its matching test file.** The pair is the unit; an entry without a test reduces Tilth's quality gate to "judge said OK," which the docs explicitly warn against.
- **Don't overwrite an existing `prd.json`.** Read, append, write back. Existing tasks (including completed ones with `status: "done"`) must survive verbatim.
- **Don't use task IDs that collide with existing ones.** The harness keys on `id`; collisions silently break selection.
- **Don't paper over contradictions because they're awkward.** Surfacing the "refactor has no existing tests" blocker is the job. Frame as a question if uncertain, but don't skip it.

## When to refuse / redirect

- **Bug fix that fits one task** → "A full interview is overkill for a one-task bug fix. Want me to just append a single PRD entry + one test file directly, or investigate the bug first?"
- **Greenfield project with no existing code** → "This skill anchors on a real codebase to slice the work. For a greenfield project, you probably want a product brief or architecture sketch first — and even then, Tilth itself expects a git repo to seed against. Want help with the brief instead?"
- **Already-detailed PRD just needs more tasks** → "If the PRD shape is already clear and you just want more entries in the same style, opening `prd.json` and adding them directly is faster than an interview. Want me to do that as a one-shot instead?"
If the user pushes back, defer and proceed.

## Reference files

- [`references/tilth-task-seed-template.md`](references/tilth-task-seed-template.md) — the structure of the prd.json entries and matching test files; the chat-summary template; the rules for appending vs. overwriting.

====================================
references/tilth-task-seed-template.md

# Tilth task seed template

A Tilth task seed is **two file types written together**, plus a chat summary. The pair is the unit — never write one without the other.

| What | Where | How |
|---|---|---|
| prd.json entries | `<workspace>/prd.json` | Append to existing array, or create if missing |
| Test files | `<workspace>/tests/test_<task-id-lower>_<slug>.py` | One per task, new file each |
| Chat summary | Output to user, not disk | TL;DR + Open Questions + Blockers |

Replace everything in `{{ braces }}` with content from the interview. Delete the inline guidance (italicized hints) once you've filled the structure.

---

## 1. prd.json entries

A `prd.json` is a JSON array of task objects. Each new task added by this skill follows the shape below. **Always set `status: "pending"`** — the harness flips it.

```json
{
  "id": "{{ T-NNN — continue from highest existing id, or T-001 if no prd.json exists }}",
  "title": "{{ Short imperative title. ~6–10 words. Verb-first. }}",
  "description": "{{ What needs to be done, concretely. Reference real file paths and symbols. State inputs, outputs, error cases, and on-disk format if relevant. Long enough to remove ambiguity, short enough that the worker won't get lost. ~2–6 sentences. Quote the user's own framing where it captured the contract well — this string becomes the user message the worker sees. }}",
  "acceptance_criteria": [
    "{{ Concrete, programmatically checkable statement #1. Maps 1:1 to a specific assertion in the test file. }}",
    "{{ Concrete, programmatically checkable statement #2. }}",
    "{{ Concrete, programmatically checkable statement #3. Aim for 2–4 criteria per task. }}"
  ],
  "status": "pending"
}

Examples grounded in the demo (from tilth-demo/prd.json):

{
  "id": "T-003",
  "title": "Implement the `add` subcommand",
  "description": "Extend `todo_cli` so that `python3 -m todo_cli add <text>` appends a new open item to `TODOS.md` in the current working directory and exits 0. Multiple words after `add` are joined with single spaces. The on-disk format is one item per line: `- [ ] <text>` for open and `- [x] <text>` for done. Adding when TODOS.md does not exist creates it; adding when it exists preserves prior content. With no text after `add`, print a usage line to stderr and exit 2.",
  "acceptance_criteria": [
    "Running `python3 -m todo_cli add buy milk` in an empty cwd creates TODOS.md whose contents are exactly `- [ ] buy milk\\n` and exits 0.",
    "Running `python3 -m todo_cli add` with no further arguments prints a usage line to stderr and exits 2.",
    "Adding to a non-empty TODOS.md appends the new open item without modifying or reordering prior lines."
  ],
  "status": "pending"
}

How to write back the file

• If <workspace>/prd.json does not exist: write a JSON array containing only the new entries.
• If <workspace>/prd.json exists: read it, parse the JSON array, append the new entries to the end, re-serialize as a valid JSON array (2-space indent, matches the demo style), write back. Existing entries — including any with status: "in_progress", "done", or "failed" — survive verbatim.
• Never set status to anything other than "pending" for new entries.
• Never delete or reorder existing entries.

2. Test file template

One file per task, at <workspace>/tests/test_<task-id-lower>_<slug>.py. The naming pattern is load-bearing — Tilth's pytest filter keys on it. A task with no matching file gets the judge as its only gate.

"""Acceptance tests for {{ T-NNN }}: {{ short purpose }}."""

{{ imports — match the project's existing test style. Common shapes:

# Style A: subprocess-based CLI tests (matches the tilth-demo pattern)
import os
import subprocess
import sys
from pathlib import Path

ROOT = Path(__file__).resolve().parent.parent

# Style B: in-process unit tests (use when the project's existing tests do)
import pytest
from {{ package }} import {{ symbol }}

}}


{{ optional helper for repeated subprocess invocations — match the project's existing pattern if any:

def _run_module(args: list[str], cwd: Path) -> subprocess.CompletedProcess:
    env = os.environ.copy()
    env["PYTHONPATH"] = str(ROOT)
    return subprocess.run(
        [sys.executable, "-m", "{{ package }}", *args],
        cwd=str(cwd),
        env=env,
        capture_output=True,
        text=True,
        timeout=10,
        check=False,
    )

}}


def test_{{ short_slug_for_criterion_1 }}({{ fixtures }}):
    {{ Assertion(s) directly checking acceptance criterion #1.
       Use exact equality where the spec is exact ("exits 0", "stdout is `(no todos)\n`").
       Use substring or regex only when the spec genuinely allows variance. }}


def test_{{ short_slug_for_criterion_2 }}({{ fixtures }}):
    {{ Assertion(s) directly checking acceptance criterion #2. }}


def test_{{ short_slug_for_criterion_3 }}({{ fixtures }}):
    {{ Assertion(s) directly checking acceptance criterion #3. }}

Example grounded in the demo (tilth-demo/tests/test_t003_add.py):

"""Acceptance tests for T-003: add subcommand."""

import os
import subprocess
import sys
from pathlib import Path

ROOT = Path(__file__).resolve().parent.parent


def _run_module(args: list[str], cwd: Path) -> subprocess.CompletedProcess:
    env = os.environ.copy()
    env["PYTHONPATH"] = str(ROOT)
    return subprocess.run(
        [sys.executable, "-m", "todo_cli", *args],
        cwd=str(cwd),
        env=env,
        capture_output=True,
        text=True,
        timeout=10,
        check=False,
    )


def test_add_creates_todos_file(tmp_path: Path):
    proc = _run_module(["add", "buy", "milk"], tmp_path)
    assert proc.returncode == 0, f"non-zero exit {proc.returncode}; stderr={proc.stderr!r}"
    todos = tmp_path / "TODOS.md"
    assert todos.is_file(), "TODOS.md was not created"
    assert todos.read_text() == "- [ ] buy milk\n", f"unexpected: {todos.read_text()!r}"

Rules for the test files

• One assertion-cluster per acceptance criterion. Three criteria → three (or three-ish) test functions, each pinning down one criterion. The mapping should be readable end-to-end: criterion validators: include completed tasks' tests to catch regressions #2 → test_<criterion-2-thing>.
• Match the project's existing test style. If the project uses tmp_path, you use tmp_path. If it uses a tmpdir fixture, mock factories, or something custom, match it. Don't introduce a new style.
• Use the project's existing helpers. If tests/conftest.py defines fixtures, prefer them over rolling your own. If there's a shared _run_module helper pattern across files (as in the demo), copy it consistently — don't redefine it inconsistently across new files.
• Assertion failure messages should name what went wrong. assert proc.returncode == 0, f"non-zero exit; stderr={proc.stderr!r}" is more useful than a bare assert proc.returncode == 0 because it surfaces the actual failure cause in the harness's validator output.
• Don't use pytest.skip, pytest.xfail, or @pytest.mark.parametrize to dodge writing real assertions. A test that skips on the first run is invisible to the harness's quality gate.

3. Chat summary template

After writing the files, output the summary to the user (do not write it to disk):

**Tilth seed written.**

`<workspace>/prd.json` ← appended {{ N }} new task(s).
`<workspace>/tests/` ← created {{ N }} new test file(s).

## TL;DR

- **T-NNN:** {{ title }} — {{ one-sentence outcome the user can scan }}
- **T-NNN:** {{ title }} — {{ ... }}
- {{ ... one bullet per task ... }}

## Open Questions

- [ ] {{ Anything the user wasn't sure about, anything you guessed at, anything that needs a decision before the run starts. Be honest — an explicit unknown is more valuable than a confident-sounding default that gets reversed mid-run. }}
- [ ] {{ ... }}

## Blockers / contradictions surfaced

{{ Only include this section if you flagged a blocker or contradiction in step 4. Examples: refactor with no existing tests, slice that contradicts the code, a missing capability the feature depends on. State the blocker, what was decided (or that no decision was made), and what would need to be true for the seed to be safe to run. Omit the section entirely if there were none. }}

## Next

- `uv run tilth <workspace>` to start the run.
- See `<tilth-clone>/sessions/<id>/events.jsonl` after the run for the per-task lifecycle.

Notes on filling this in

• Date — the demo's prd.json has no dates per entry; don't add one. If you need today's date for the chat summary, run date '+%Y-%m-%d'.
• Task ID continuation. If the existing prd.json ends at T-005, the first new task is T-006. Pad to three digits (T-006, not T-6). If new entries push the count past T-999, ask the user — the format might need widening, but that's a project-level decision.
• Empty sections in the chat summary are OK to omit. If there are no open questions and no blockers, drop those sections. Keep TL;DR + Next always.
• Quote the user's framing in description where their phrasing captures the contract well. The description string becomes the user message the worker reads — their voice carries the why better than your paraphrase.
• Keep it tight. A good Tilth seed is 3–8 tasks per pass, not 20. If you're past 8, the slice is probably too coarse or the seed should be split across runs. If it's at 2, consider whether the interview was worth it vs. just writing the entries directly.
• No AGENTS.md or progress.txt reads or writes. Those live in Tilth's session worktree at runtime and are managed by the harness — not source-repo files this skill interacts with.