# Requirement Intake > Turns an untagged task on the board — a paragraph of intent — into an approved, executable plan before any code is written. Covers the workflow/ scratch folder, the questions protocol, sizing, and what must be exported before a task can finish. Use when a board task has no [tag], or when asked how requirements become plans. - Skill: `digitaldreams/requirement-intake` (Agent Skill) - Install (CLI): `npx skillmds@latest add digitaldreams/requirement-intake` - Raw SKILL.md: https://api.skillmd.com/api/skills/digitaldreams/requirement-intake/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: digitaldreams (https://skillmd.com/u/digitaldreams) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/digitaldreams/requirement-intake --- # Requirement Intake A tagged task (`[backend] Add /health endpoint with test`) means you already did the requirement engineering — it goes straight to the task-workflow skill. An **untagged** task is a requirement. It gets a requirement engineer first. ``` - [ ] TASK-31 Reply digest for operator — status: todo Operator gets a daily email digest of new replies grouped by niche. Link each reply to the business detail page. ``` Title on the line, description indented. That is the only thing a human writes. ## One pen **The human writes in `tasks.md` and nowhere else.** They may read anything. Everything an agent produces goes in `workflow/` — a gitignored scratch folder at the repo root. Two surfaces, one owner each, no ambiguity about who wrote what. ``` / tasks.md human writes here. git-tracked. short. the index. workflow/ agents write here. gitignored. verbose. the working memory. .env knobs (self-created on first run) TASK-31-reply-digest/ state.md plan.md assumptions.md questions.md review-1.md review-2.md backlog.md ``` ### workflow/ is organised by slice, never by file type One task = one folder = every artifact for that task, together. ``` ✗ workflow/plans/ workflow/reviews/ workflow/state/ grouping by file type ✗ workflow/backend/ workflow/frontend/ grouping by agent ✓ workflow/TASK-31-reply-digest/ grouping by task ``` The second one matters: a requirement usually spans modules and agents, so it has no home module. The task is the slice. ### Bootstrap (first run, idempotent) 1. `workflow/` missing → create it. 2. `/workflow/` missing from `.gitignore` → append it. Never rewrite the rest of the file. 3. `workflow/.env` missing → write it with these defaults and comments: ```ini # task-agent workflow knobs. Per developer, gitignored. PLAN_GATE=medium # never | small | medium | always — sizes that need your approval AUTO_MERGE=off # off | gated (gated conditions are in the task-workflow skill) MERGE_TARGET=develop MAX_REVIEW_ROUNDS=3 # reviewer FAIL -> fix -> re-review, this many times, then blocked MAX_FIX_CYCLES=2 # gate failures fed back to the implementer per round NOTIFY=osascript # osascript | print | ``` Unreadable, missing, or unparseable `.env` → use these defaults with **`AUTO_MERGE=off`**. The one irreversible action always fails closed. ## The intake phases Intake is **one phase**: a run sets `status: planning`, runs the requirement engineer, and does not stop until the task has landed on its next human gate or gone straight to implementation. `planning` is a crash marker, never a resting place — a task found sitting in `planning` had its run interrupted, and the next run restarts the phase. | board status | what runs | next | |---|---|---| | `todo` (untagged) | create `workflow/-/` + `state.md`, set `planning`, run the **task-requirement-engineer** agent: understand → validate → feasibility → size → plan | `needs-answer`, `plan-review`, or `doing` | | `needs-answer` | **the human** answers on the board, then writes `answered: yes` | re-run this phase with the answers | | `plan-review` | **the human** writes `approved: yes` on the board | `doing` | | `doing` and after | the **task-workflow** skill takes over unchanged | — | Both human gates behave identically: the loop skips the task entirely until the confirming line is present. Neither ever times out into a guess. `PLAN_GATE` decides whether `plan-review` happens at all: | `PLAN_GATE` | plans you approve | |---|---| | `always` | every plan | | `medium` *(default)* | MEDIUM and LARGE. SMALL is auto-approved. | | `small` | SMALL only (unusual; for trusting the RE on big work but not small) | | `never` | none — fully hands off | A skipped gate is not a skipped plan. `plan.md` is still written, still linked from the board, still the implementer's contract, and still reviewed as part of the PR. A gate the knob skips is recorded as an approval, not as an absence of one: ``` plan: workflow/TASK-31-reply-digest/plan.md (SMALL · 1 slice) approved: yes (auto — PLAN_GATE=medium, size SMALL) ``` The board still reads `status: plan-review`, so the next run picks it up through the ordinary claim rule and nothing special-cases the bypass. You can also see, six months later, that no human ever read that plan. ## The questions protocol RE questions go **on the board**, short, with a stated default. The human answers in place. Long-form context stays in `workflow//questions.md`. ``` - [ ] TASK-31 Reply digest for operator — status: needs-answer Operator gets a daily email digest of new replies grouped by niche. workflow: TASK-31-reply-digest Q1: One email with niche sections, or one email per niche? (default: one email) A1: Q2: Include replies from suppressed businesses? (default: no) A2: answered: ``` - Max five questions. One line each. **Every question names its default**, so the human can accept the lot without typing an answer. - `needs-answer` is human-gated. A driver skips the task until the human writes `answered: yes` — same shape as `approved: yes`, same meaning: your turn is over. A loop ticking every few minutes must never answer its own questions. - On resume: `A: ` wins and goes into `plan.md` verbatim. An `A` the human left empty means **use the stated default** — record it in `assumptions.md` and continue. Answer the two that matter, ignore the rest. ## Handing the plan back to the board When RE finishes, the dispatcher writes to the board (RE never touches `tasks.md`): 1. **Add the tag** from `plan.md`'s `## Agent` section — the line stops being untagged, and every downstream rule works as it always has. 2. **Add the pointer**: `workflow: TASK-31-reply-digest`. 3. **Add the plan line**: `plan: workflow/TASK-31-reply-digest/plan.md (MEDIUM · 2 slices · 1 migration)`. 4. **Set the status** per `PLAN_GATE`. ``` - [ ] TASK-31 [backend] Reply digest for operator — status: plan-review Operator gets a daily email digest of new replies grouped by niche. workflow: TASK-31-reply-digest plan: workflow/TASK-31-reply-digest/plan.md (MEDIUM · 2 slices · 1 migration) approved: ``` ### When the work is bigger than one sitting RE writes proposed child lines to `workflow//tasks.md`. The dispatcher appends them to the board with real ids and `depends:` lines, then closes the parent: ``` - [x] TASK-31 Reply digest for operator — status: done decomposed into TASK-32, TASK-33 - [ ] TASK-32 [backend] Build digest query + BuildDigestService with tests — status: todo plan: workflow/TASK-31-reply-digest/plan.md - [ ] TASK-33 [backend] Schedule SendDigestJob daily 07:00 with tests — status: todo depends: TASK-32 plan: workflow/TASK-31-reply-digest/plan.md ``` Children are tagged, so they skip intake entirely and share the parent's plan. ## The export rule `workflow/` is gitignored. Anything that must outlive the task has to leave it before the task can reach `done`: | must land in | what | |---|---| | the PR body | the original requirement text, the plan, and the assumptions | | `tasks/architecture.md` | `architecture-delta.md` applied — LARGE only, inside the worktree | | `tasks/system_model.md` | `system-model-delta.md` applied — LARGE only, inside the worktree | | the project's manual test cases | updated whenever operator-visible behavior changed | | `docs/conventions.md` or `CLAUDE.md` | only if the task established a new project rule | **A task must not be set to `done` while a durable artifact exists only inside `workflow/`.** That single rule is what makes gitignoring the folder safe. ## Absolute paths in worktrees `workflow/` is gitignored, so **it does not exist inside a task worktree**. An implementation agent running in `../-worktrees/TASK-31` that reads `workflow/TASK-31-reply-digest/plan.md` finds nothing — and will happily invent a plan instead of failing. Every prompt handed to an implementation or review agent passes the plan by **absolute path**: ``` /Users/you/code/my-store/workflow/TASK-31-reply-digest/plan.md ``` Working directory is the worktree. Plan reads come from the main checkout. ## Cleanup A task reaching `done` keeps its workflow folder until the PR is merged (the review rounds need it). After that it is garbage. Deleting `workflow/TASK-31-reply-digest/` costs nothing — the PR holds everything durable.