/foreman-to-issues

name: foreman-to-issues
description: Break an approved PRD into small, dependency-ordered, vertically-sliced implementation issues written as local files in the Foreman feature directory. Each issue ships a runnable acceptance check and a declared file footprint. No GitHub, no live quizzing of the user — emits files matching Foreman's issue schema with PRD traceability.
foreman_skill_version: 2

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.

<vertical-slice-rules>

• Each slice delivers a narrow but COMPLETE path through every layer.
• A completed slice is demoable or verifiable on its own.
• Prefer many thin slices over few thick ones.
• Order slices by dependency: a slice that others build on comes first.
• Every slice traces back to one or more PRD sections / user stories.

</vertical-slice-rules>

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:

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