intake
Turn a goal, meeting notes, a transcript, an email or a `distill` candidate into decision records, specification changes and implementable tasks. Works in local repositories (decision and task files)
SKILL.mdskills/intake/SKILL.md
GitHubintake
Turn one source into the three records the loop needs: a decision the owner accepts, the specification lines it changes, and tasks a worker can take without asking. Every task cites the specification; every change cites its task.
Which backend
Read the repository's own instructions (AGENTS.md or its equivalent) for where its tasks live.
- local (the default for
new-repo): decisions are files underdocs/decisions/, tasks are files underdocs/tasks/, and nothing leaves the machine.#Nmeans task N. - GitHub-backed: decisions and tasks are GitHub issues written with plain
gh issue createunder the identity the repository's instructions name.#Nmeans issue N. - Unclear: ask the owner which one, or work with local files in the same format.
Procedure
- Source. One of: the owner's goal in a sentence or a paragraph; meeting notes, a call
transcript or an email; a candidate block pasted from
docs/incoming.html(cite its id). Raw records stay in the owner's notes and are never copied into a repository. Refer to them by date and type only (client call, 2026-09-17); no quotes, no private names. - Resolve current requirements. Use the project's configured specification reader or
project-local spec tool first, preserving native item IDs and format. If none exists, fall back
to
docs/spec/SDD.md,docs/spec/TDD.mdanddocs/decisions/. Read open tasks withloop tasks list(or the files underdocs/tasks/) for local repositories andgh issue listfor GitHub-backed ones. Then inspect only the code the TDD or spec-reader output names. - Map each takeaway. Already satisfied: nothing. Contradicted or left open: one decision.
An empty specification (a new repository) leaves everything open; the first decisions write
the first requirements, following the conventions at the top of
SDD.mdandTDD.md. - Decision drafts. Context with the spec items quoted, options, consequences, a
recommendation and the one question the owner answers.
- local:
docs/decisions/NNNN-<slug>.mdfrom0000-template.md, the next unused four-digit number,Status: proposed. - GitHub: a
decisionissue withgh issue create --label decision, on the owner's word. Stop here and ask. A goal the owner already stated plainly may be accepted in the same conversation; recordStatus: acceptedand the date.
- local:
- Specification change, after acceptance, on one branch cut from the base
(
docs/<slug>; in a worktree when another writer holds the checkout): edit the exact SDD and TDD lines, set each touched status topending:#<task>, set the decision'sSpec:field, and append one row todocs/spec/SPEC-AMENDMENTS.md. - Cut tasks from the spec diff, dependency ordered, each small enough for one worker. Use the
task backend chosen above; do not hand-write task records when the backend command can create
and validate them.
- local:
loop tasks new "<title>" --scope <prefixes> --depends "#N"|none [--labels spec|enhancement|documentation] [--ready], run inside the branch's worktree; it picks the number and writesdocs/tasks/<N>-<slug>.mdindocs/tasks/README.mdformat. Replace the body with what to build, the acceptance criteria and the SDD/TDD items that govern it. Thenloop tasks checkmust report ok. Without theloopcommand, write the file by hand in the same format, with the next unused number. - GitHub:
gh issue createwith the same body plusScope:andDepends on:lines, a milestone andneeds-triage; the owner labels themsprint-ready. Fill thepending:#<task>markers with the numbers just assigned.
- local:
- Check with
spec-lintand any project-specific spec check on the branch, then hand over. Local: the owner merges the branch into the base in a terminal (git merge --no-ff docs/<slug>); the loop sees tasks only on the base. GitHub: one draft pull request citing the decision issue.
Where it runs
The specification is decided before it is built. Intake runs on its own branch from the base and lands before any goal branch that builds it; a spec change never rides inside a build task, and the loop's fold refuses a build branch that edits spec text.
- From zero:
new-repo, then intake in the new repository with the goal as the source, from an agent opened in that repository. The owner accepts the decision and merges the spec branch; thenloop start <type/slug>builds it. - During a goal: a worker that finds the spec wrong blocks. Whoever coordinates the goal, a
reviewer, or the owner runs intake for that one change and writes it as a task labeled
spec; only that task's branch may change the specification. - Many raw notes at once:
distillfirst, then intake on the candidates worth acting on.
Traceability: decision, then the specification change that cites it, then tasks depending on
it, then the worker changes that close them (Closes #N in the worker's .worker-pr.md).
Keep the scope honest. A simple change the specification already covers goes straight to one task; do not manufacture decisions or tasks for every thought.