Specs and plans

A spec says what you want; a plan says how the loop gets there, one task per line. You write the spec, rafa writes the plan, and you read the plan before it runs.

A spec

A spec has six headings: what you get, the starting position, the design, what can go wrong, the tasks the plan must carry, and the definition of done. The tasks heading is a floor, not the plan: it lists what the plan may not leave out.

A spec can live in two places:

• A file under .rafa/specs/. Nothing else is needed, and you never touch a board.
• A GitHub issue opened from the Spec template that rafa init --board installs. This is the choice once you want the queue, the specs and their history in one shared place.

A plan

rafa plan create --spec=.rafa/specs/my-feature.md   # from a file
rafa plan create --issue=42                          # from issue #42's body
rafa plan create --next                              # from the first undone line of the roadmap

Each starts one Claude Code session that reads the spec and the repository and writes a checklist the loop can parse, in .rafa/plans/PLAN-<stub>.md. rafa plan validate checks that a plan reads as written and routes to agents that exist, and rafa plan risk reads what a run of it may do on this machine.

A task line may end with a declaration the planner writes and you can change, for example {agent=tdd-guide skills=dev-planner effort=medium}:

• agent= routes the task to a Claude Code subagent. Agents and skills come from three tiers: the project (.claude/agents, .claude/skills), the copies rafa ships, and your user folder (~/.claude). A loop session sees the user tier only when loop.settingSources includes user, which the default does not, so an agent you keep only in ~/.claude/agents is not found. rafa agent vendor <name> copies it into the project, and rafa agent list shows what a run sees. When two tiers hold different items under one name, the loop refuses until a tiers.agents or tiers.skills pin in the config names the tier to use.
• skills= names the skills offered to that task.
• model=, effort=, tools= and budget= set the session's model, reasoning effort, tool list and spending cap when no agent decides them.

rafa loop start refuses a plan that names an agent or a skill it cannot find, before any session is paid for.

Specs as issues

On a board, a few labels carry each spec's state:

Label	Means
type:spec	the issue is a spec
spec:ready	a person says a plan may be made from it
spec:needs-work	details are pending, or the planner's review found gaps
type:bug with needs-triage	a bug a run filed on its own

rafa issue ready <n> checks that an issue fills every heading the template asks for, then adds spec:ready. rafa never adds that label by itself.

An issue's text ends up in an agent's prompt, so rafa plans only from an issue that a person who can write to the repository opened, that a maintainer labelled spec:ready, that is complete, and that holds no local path or token. Comments are never read into a plan.

The roadmap

The pinned Roadmap issue is one ordered task list of specs. rafa roadmap shows it as a table: what is ready, what blocks it, and what already has a plan, a branch or a pull request. rafa plan create --next takes the first line that is neither done nor being worked on, and stops rather than skipping ahead when that issue is not ready.

When the list grows into features, Epics and boards groups specs under epics without changing how a solo roadmap works.