Foreman To Issues

foreman-to-issues

(Adapted from mattpocock/skills to-issues — see NOTICE. Removed: all gh CLI usage, GitHub labels/triage vocabulary, and the interactive "quiz the user" loop. Issues are emitted as local files; the human reviews them in Foreman's queue-review screen instead.)

Break the approved PRD into independently-grabbable issues using vertical slices (tracer bullets). Run headless: produce the files and stop. The human will reorder/edit/delete/add in Foreman's queue-review screen — do not ask them anything here.

Process

1. Gather context

Read the approved prd.md (path injected by Foreman) — its body, user stories, and user flows. Read the approved plan.md and adr.md too for decisions.

2. Explore the codebase

Understand the current state so titles and descriptions use the project's domain glossary (CONTEXT.md) and respect ADRs in the area you're touching.

3. Draft vertical slices

Break the PRD into tracer-bullet issues. Each issue is a thin vertical slice that cuts through ALL integration layers end-to-end (schema → logic → API → UI → tests), NOT a horizontal slice of one layer.

4. Emit one file per slice

Write each slice to .foreman/features/<slug>/issues/ISS-NNN.md, numbered from 001 in dependency order (blockers first, so depends_on can reference real ids). Each file is YAML frontmatter + markdown body in exactly this schema:

mdCopy code
---
id: ISS-001
title: <short descriptive name>
status: queued
depends_on: []            # list of blocking issue ids, e.g. ["ISS-001"]
branch: feature/<slug>/iss-001
attempts: 0
budget: { max_turns: 80, max_cost_usd: 5.00, timeout_min: 45 }
prd_refs: ["PRD §<section>", "Story #<n>"]   # traceability back to the PRD
acceptance_check: tests/<area>/test_<slice>.py   # runnable check (REQUIRED)
touches: ["src/<area>/...", "tests/<area>/..."]  # declared file footprint
kind: feature
---
## Goal

A concise description of this vertical slice — the end-to-end behavior, not a
layer-by-layer implementation plan. Avoid file paths and code snippets (they go
stale); a prototype-derived decision snippet may be inlined if it encodes a
decision more precisely than prose.

## Acceptance criteria (testable)

- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3

## Out of scope

- What this slice deliberately does not do.

Rules:

• id is ISS- + zero-padded three-digit number, unique within the feature.
• branch is feature/<slug>/iss-NNN (lowercase).
• budget defaults come from the feature's config run_budget; only deviate when a slice is clearly bigger or smaller, and say why in the body if you do.
• prd_refs MUST be present and non-empty — every issue traces to the PRD.
• depends_on MUST be acyclic and reference only earlier issues.

acceptance_check — the executable form of acceptance (REQUIRED)

Every issue MUST carry a runnable acceptance_check derived directly from a PRD acceptance criterion, so "done" is executable, not prose. It is either:

• a bare test-file path (Foreman runs it with the project's test command), e.g. acceptance_check: tests/todo/test_done.py; or
• a command (more than one token), e.g. acceptance_check: "pytest tests/todo/test_done.py::test_marks_complete".

If the check is a dedicated test the slice must add, write that test file into a canonical issues/ISS-NNN.check/ directory (same relative path it should have in the repo, e.g. issues/ISS-001.check/tests/todo/test_done.py). Foreman re-installs it into the worktree before verifying so the worker cannot weaken or delete it. An issue with no acceptance_check is rejected from the queue.

touches — the declared file footprint (for safe parallelism)

List the files/dirs/modules the slice will create or modify. Foreman builds a conflict graph from these and never runs two overlapping issues concurrently, so maximise disjointness when slicing — prefer slices whose footprints don't overlap. An empty/unknown footprint is treated as conflicting with everything (the safe default), which serialises the slice — so always declare it.

Do not create any external tickets. Do not modify the PRD.