Task — single-task TDD execution

Toolkit paths. Every toolkit script or template path cited here resolves, first hit wins, against: a repo-local copy installed by setup.sh; else the plugin root (this skill's base directory two levels up, <base>/../..) when it holds that path; else ~/.claude/brainstorm-toolkit/ (the global shell install).

Boundaries

/task always executes TDD on the current branch. Want the full pipeline (evals + validate + plan check, changes left for you to commit)? That's /sdlc. Want just the row written and nothing run? Edit TASKS.md directly.

Flow

1. Prepare the task record

1. TASKS.md: if missing, create it from templates/TASKS.md.template (or from scratch with sections Active / Pending, Blocked, Done).
2. Determine the next task number by reading existing rows ((P?) <title> — plans/tasks/task-<N>-...) and taking max(N) + 1. Start at 1 if empty.
3. Slugify the description (lowercase, hyphen-separated, ≤40 chars).
4. Append a row to the Active / Pending section: - [ ] (P2) <one-line title> — plans/tasks/task-<N>-<slug>.md.
5. Initialize a minimal state record (best-effort): write .claude/pipeline/task-<N>-<slug>/run.json with {schema_version: 1, feature_slug: "task-<N>-<slug>", pipeline: "task", stage: "implement", status: "in_progress", started_at} (shape per skills/sdlc/templates/state-schema.md). This puts /task runs in the same state journal as /sdlc. If the write fails (permissions, read-only volume), log a one-line stderr warning and continue — state writes never fail a task.

2. Write the task file

Create plans/tasks/task-<N>-<slug>.md:

---
id: task-<N>
status: pending
priority: P2
files: []
---

# <Title>

## Description
<1–3 sentences restating the ask.>

## Steps
- [ ] <first concrete step>
- [ ] <next step>

## Acceptance criteria
- <observable condition for done>

## Files
<expected paths to create/modify; fill in as you go>

## Notes
<open questions, links, context>

3. (Claude only; optional) Mirror to native Tasks

If running under Claude Code, call TaskCreate with the same title. This gives the user a live progress indicator in the UI. Skip silently on other agents.

4. Execute with TDD

Pure-docs / no-testable-surface asks: if the change has nothing to assert against (docs, comments, config, copy edits), skip steps 1, 2, and 5 — make the edit directly at step 4 and note "no testable surface" in the report. Don't manufacture a hollow test, and don't punt the task to another skill.

1. Write a failing test encoding the acceptance criterion, using the project's configured runner (.claude/project.json → test.unit or test.frontend; the conventional location if none is configured), and confirm it fails for the expected reason. Then run bash scripts/protect-tests.sh arm <test-file> --slug task-<N>-<slug> (best-effort, ignore a nonzero exit) — this is a detector, not a preventer: it records the file's hash so verify at close-out can prove the test was not quietly rewritten to pass; it cannot stop a rewrite. Always pass --slug with the same task-<N>-<slug> this run's own envelope (Section 1 step 5) was written under — unaddressed, a second run open at the same time can get armed/verified instead. For a bug fix, that test must be shown red against the unfixed code (this is TDD's red). If the test was written after the fix, apply the "Red-check a regression guard" procedure in skills/sdlc/templates/fix-loop.md before trusting it.
2. Mark the TASKS.md row in-progress ([ ] → [~]) and, on Claude, TaskUpdate status: in_progress.
3. Implement the change, following existing patterns, until the test passes without weakening it. Rule: never write plan or task references (plans/ paths, task IDs, brainstorm names) into code — this covers comments, docstrings, string literals and data (e.g. TASKS.md:N, task-N, plans/<file>.md, phase/step numbers, a plan slug). Write the reason itself: the plan is deleted once delivered and TASKS.md rows move, so it rots.
4. Run the wider test suite if one is configured (/test-check or the project's root test command).

5. Close out

1. Update the task file: set status: completed, mark all step checkboxes [x], fill in Files with the actual paths touched.
2. Run bash scripts/protect-tests.sh verify --slug task-<N>-<slug> (the same slug arm used). A nonzero exit means a protected test's bytes changed since it was armed — investigate before closing out; it does not block by itself.
3. Mark the TASKS.md row done ([~] → [x]) and move it to the Done section.
4. On Claude: TaskUpdate status: completed.
5. Update the state record (best-effort): set run.json.status = "complete", stage = "done", and record the files touched (and commit_sha if you committed). Same never-fail rule as Section 1.
6. Report a concise summary: files touched, tests that now pass (or "no testable surface"), anything left open.

Commit only if the user asked for it, or if they have a durable "always commit finished tasks" instruction. When you do commit, append a blank line and Co-Authored-By: Claude <noreply@anthropic.com> only if .claude/project.json coauthor_trailer is true; absent or false means no trailer.

Gotchas

• Don't inflate small tasks. If the ask is one line of code, the task file can be terse. Don't pad acceptance criteria to look thorough.
• Respect GOTCHAS.md. Before writing code, check the configured gotchas_file (if it exists) for entries that apply to the area you're touching — scoped to the touched area, not the whole file.
• Capture at exit (flywheel). If the run hit a real trap (a test flipped red→green, or something surprised you), run the loop-exit capture protocol in skills/gotcha/SKILL.md — auto-draft + one-tap confirm; clean runs stay silent. If capture is declined/deferred, append a /gotcha <drafted text> sentinel line — structured + deduped by cmd (multi-slot seam, see docs/SEAM.md): line='{"cmd":"/gotcha <drafted text>","source":"task","confirm":false}'; grep -qF "$line" .claude/.next-action 2>/dev/null || echo "$line" >> .claude/.next-action (never a bare /gotcha). On Codex (as a fallback until its .codex/hooks.json Stop hook is wired+trusted) also print Next: /gotcha … inline so the seam degrades gracefully. If no Stop hook is wired at all, apply the no-hook nudge (docs/SEAM.md SEAM2).
• One task at a time. /task handles a single bounded item. If the ask implies a batch of tasks, don't fire /task repeatedly — run them through /sdlc <range> (e.g. /sdlc 1-5), which keeps full-pipeline discipline across the set and commits nothing until you review. For an open-ended feature, start with /brainstorm.