Foreman To Issues Agent Skill

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.