task-board-setup — file-based Kanban scaffolder

opus status / install / upgrade / enable / disable / uninstall / purge user-invoked

Quick reference

Item	Value
Skill command	/brewtools:task-board-setup
Arguments	[status | install | upgrade | enable | disable | uninstall | purge] [target repo path | empty = cwd] [free-text directive] — e.g. install /path/to/repo, upgrade, 'skip module split'
No verb	Resolved from the target: a deployed board reports status, a fresh repo gets install. A bare path alone installs into that path
Emits	.claude/agents/task-tracker.md, .claude/skills/task-board/SKILL.md, .claude/rules/tasks.md, .claude/features/**
Emits (SPEC_MODE)	.claude/skills/task-spec/SKILL.md, .claude/features/specs/{SPEC_TEMPLATE,DESIGN_TEMPLATE}.md
Spawns	Parallel analysis subagents (architect + Explore + domain-agent inventory) + multi-agent doc sweep — one bounded unit each
Optional	Spec + system-design layer (SPEC_MODE), confirmed during Step 1; gated CLAUDE.md optimization pass — propose-only, opt-in during confirmation
Upgrade	upgrade directive retrofits SPEC_MODE onto an already-deployed board, additive-only
Model	opus
Commits?	Never — committing is a user / manager action

When to use

Scenario	Command
Inspect what is deployed, change nothing	/brewtools:task-board-setup status
New repo needs file-based task tracking	/brewtools:task-board-setup install
Standardize an existing Kanban convention across repos	/brewtools:task-board-setup install /path/to/repo
Migrate scattered TODO / backlog docs into a structured board	/brewtools:task-board-setup install — sweep subagents migrate legacy docs automatically
A task needs an architecture pass before code	Turn on SPEC_MODE at confirmation, then run the emitted /task-spec <ID>
An already-deployed board needs the spec + design layer	/brewtools:task-board-setup upgrade /path/to/repo
Pause the board machinery without deleting anything	/brewtools:task-board-setup disable
Resume after a disable	/brewtools:task-board-setup enable
Remove the generated machinery, keep every task you wrote	/brewtools:task-board-setup uninstall
Remove the machinery and delete .claude/features/** too	/brewtools:task-board-setup purge

Example

# Report what is deployed in the current repo
/brewtools:task-board-setup status

# Deploy into the current repo
/brewtools:task-board-setup install

# Deploy into another repo
/brewtools:task-board-setup install /path/to/some-repo

# Deploy, then steer the optional CLAUDE.md pass with a free-text directive
/brewtools:task-board-setup install /path/to/some-repo also dedupe rules, skip module split

# Retrofit the spec + design layer onto a repo that already has a board
/brewtools:task-board-setup upgrade /path/to/some-repo

After completion the repo gains /task-board (view/add/move tasks) and the task-tracker agent auto-runs at the start of every task.

How it works

Delegation

Every spawn prompt carries six fields. A bare one-line task is never enough:

Field	Content
GOAL	deploy the board into the target repo; this pass fills it from pre-existing task docs
ROLE	own the listed docs — no invented tasks, no source-dir edits, no CLAUDE.md
SCOPE	write only under .claude/features/**; out — exclusions, CLAUDE.md, .claude/agents, .claude/skills
CONTEXT	confirmed domains / release style / language, plus the already-written skeleton and templates; siblings sweep other groups now
CONSUMER	verification counts what landed, and the installed task-tracker agent reads those files from then on
DONE	files under closed/ + backlog/ plus a manifest — a no-op sweep must say so explicitly

The CONSUMER field is load-bearing here: an id or status folder that deviates from TASK_TEMPLATE.md makes the task invisible to the task-tracker agent forever after.

What gets deployed

Artifact	Path	Role
Curator agent	.claude/agents/task-tracker.md	Owns the board — create / move / close tasks, groom backlog, keep board.md canonical. Writes only .claude/features/**.
Dashboard skill	.claude/skills/task-board/SKILL.md	On-demand /task-board — view / add / move / backlog / groom; delegates bulk to the agent.
Paths-scoped rule	.claude/rules/tasks.md	Lifecycle, id convention, required FM, grooming — plus “run task-tracker at the start of any task”. Auto-loads on .claude/features/**.
Board file	.claude/features/board.md	The Kanban board — counts and task table, authored by the doc sweep.
Session progress	.claude/features/PROGRESS.md	SESSION progress against the board — five fields, overwritten in place. Ungated: written in both SPEC_MODE states, before any task exists.
Control files	.claude/features/{TRACKER,TASK_TEMPLATE,INDEX}.md + backlog/README.md	Tracker log, task template, index, backlog guide.
Folders	.claude/features/{backlog,todo,progress,closed,specs}/	Status folders — folder name = task status.
Spec skill (SPEC_MODE)	.claude/skills/task-spec/SKILL.md	On-demand /task-spec <ID> — authors the product + design spec via a domain-architect fan-out.
Spec templates (SPEC_MODE)	.claude/features/specs/{SPEC_TEMPLATE,DESIGN_TEMPLATE}.md	Fixed section skeletons for the two spec documents.

Session progress (PROGRESS.md)

Five fields, overwritten in place, never appended:

Field	Holds
Updated	ISO date of the last rewrite
In flight	task ids being worked right now
Moved since last update	<ID>: todo -> progress, one line each
Blocked	<ID>: what blocks it / who unblocks it
Next	the single next action for this session

The injection mechanism is a rule, not a hook: .claude/rules/tasks.md carries paths: [".claude/features/**"] frontmatter, and PROGRESS.md lives under that same glob — the rule auto-loads whenever a task touches the board, and rule 8 forces exactly that at the start of every task. task-board-setup installs no hooks for this.

Four rules bind it, in .claude/rules/tasks.md under “Session progress”:

#	Rule
P1	Always exists — created at board init. Missing → recreate it from board.md before anything else.
P2	The main session keeps it current: refresh it in the same change as any transition.
P3	Plan mode: a plan touching any task must carry an explicit final step — update .claude/features/PROGRESS.md. An otherwise-complete plan without that step is incomplete.
P4	task-tracker watches it: every run rewrites the five fields from board.md + the task files, and reports staleness in one line. It cannot run a skill for you — act on its NEXT: line yourself.

Board drain. When the progress count on the board reaches zero, task-tracker appends NEXT: run /brewtools:task-board-setup upgrade <path> — but only when this repo has no .claude/skills/task-spec/ yet. A board that already has the spec layer stays silent, because upgrade forces SPEC_MODE=on and would otherwise push the spec layer onto a repo that deliberately declined it.

Spec + design layer (SPEC_MODE)

With SPEC_MODE=on, a non-trivial task becomes three documents instead of one:

Doc	Path	Owns
Task	.claude/features/{backlog,todo,progress,closed}/<ID>.md	WHAT + WHY — context, links, the ask, and a ## Scope table of blocks S1..Sn
Product spec	.claude/features/specs/<ID>-spec.md	HOW — decisions D1..Dn, resolved + open questions Q1..Qn, scope-coverage matrix
Design spec	.claude/features/specs/<ID>-design.md	Architecture — components, data flow, interfaces, failure modes, complexity budget, non-goals

Every task’s frontmatter gains spec: none | pending | full | design-only — “no spec” is a recorded decision, never an omission. A task needs a spec if it touches more than one domain, more than ~5 files, adds an integration or dependency, changes a schema / API / contract, is ambiguous, or the user asked for a design.

The generated task-spec skill

Three ways in, all supported by the emitted skill:

Path	Form
Explicit	/task-spec <ID> (default full), /task-spec <ID> design, /task-spec <ID> refresh
Plain prose	model-invoked — “architect this task”, “write the spec”, “продумай архитектуру”. No skill name needed
Redirect	task-tracker ends its report with NEXT: run /task-spec <ID> (spec required: <reason>) when a task needs a spec and has none — an agent cannot call a skill for the main session, so it hands the call back to the user

Agent-resolution chain. Design docs are never written by a single generalist. For every domain the task touches, task-spec walks a 4-link chain, all spawned in one message: team agent (.claude/teams/team.md roster, if present) → the repo’s own project domain agent → any architecture-capable project agent → the built-in Plan. Whichever was used is named per domain in the design’s ## Evidence; domains with no owning agent are reported as gaps at install time and again in the design. An agent that refuses the task re-delegates to the colleague it names, capped at 2 retries.

Gate	Rule
Coverage (G1)	every in-scope id must appear as covered in both coverage tables; any partial/uncovered keeps the spec at status: draft
Close (G2)	progress -> closed is blocked while any open question is blocking: yes — override only with an explicit SPEC WAIVER: <reason> line in the task’s ## Notes
Sync (G3)	editing the task’s ## Scope invalidates both specs back to draft; run /task-spec <ID> refresh
Staleness (G5, close-time)	REPORT-ONLY — reuses the same two docs G2 already opened, zero extra reads. Frontmatter status: still draft, or an in scope id just marked done that is uncovered/partial in ## Scope coverage, emits SPEC STALE: <ID> ... plus one NEXT: run /task-spec <ID> refresh. Never blocks the close, never writes a spec doc, never touches ## Scope coverage.

Clarify before research

Before the domain-architect fan-out, task-spec runs one AskUserQuestion pass (3-5 questions, max 4 per call) over a fixed three-category table, then treats every answer as settled input for every later architect spawn:

#	Category	Asks about
1	Scope	what is in/out, which modules are affected
2	Constraints	required libraries, backward compat, API contracts
3	Edge cases	concurrent access, empty/null inputs, error recovery

Answers land verbatim in the spec’s new ## Original requirements (the task’s ask, unedited) and ## User Q&A (this exchange) — never re-opened later.

Size advisory

More than 3 touched domains, or more than 12 in scope ids, makes the final report propose a split — addressed to task-tracker, not acted on here. task-spec never splits, creates or moves tasks itself; the board owns that.

-n / --noask — non-interactive mode

Suppresses exactly three interactive points, each recording Skipped (--noask mode):

Suppressed	Phase
Clarify pass	P0.7
Open-questions batch	P5
Review escalation	P6-C

Blocking questions stay blocking: yes regardless. --noask does not suppress the two ground-truth stops — an ambiguous task id (several WIP candidates) and a missing ## Scope still AskUserQuestion and fail loud rather than guess.

Bounded self-review fix loop

After both docs are drafted:

Phase	Does
A — find	one adversarial reviewer per touched domain, all in one message; reports findings only, no edits
B — verify	every finding re-checked against docs and code: confirmed / rejected / duplicate
C — fix	while a confirmed blocker or major remains: apply fixes, re-run A for the affected domains, re-verify per B — capped at 3 iterations

Survivors after 3 rounds go to the user via AskUserQuestion (accept as-is, or convert to a blocking Q#/AQ#); under --noask every survivor converts to a blocking question automatically.

Structured final report

P7 replaces the old prose summary with a fixed block: mode, touched domains → agent used per domain, docs written + spec: value, decisions / open-questions counts, G1 coverage verdict, review counts (findings / confirmed / rejected / fix iterations / survivors), size advisory, and what synced in the same change.

Modes

Canonical order, shared by every -setup skill:

Mode	Requires	Effect
status	either state	Read-only inventory of the target: deployed or not, spec layer present, what to run next. Writes nothing, spawns nothing, asks nothing
install	fresh repo	The full multi-agent deploy below. Refuses a repo that already has .claude/features/board.md
upgrade	deployed board	Retrofits the spec + session-progress layers, additive-only
enable	deployed board, parked	Restores the machinery parked by disable — renames each .disabled file back. No re-analysis, no subagents, no confirmation
disable	deployed board	Parks the machinery — task-tracker.md, task-board/SKILL.md, task-spec/SKILL.md (if the spec layer is deployed) and tasks.md are each renamed to a .disabled twin. Claude Code stops discovering them; .claude/features/** and every task are untouched
uninstall	deployed board	Removes the generated machinery (curator agent, dashboard skill, rule, spec skill) and KEEPS .claude/features/**
purge	deployed board	uninstall plus deletion of .claude/features/** — every task you ever wrote

Only a standalone token counts as the verb; "upgrade the rules wording" inside a directive is prose, not a mode. init, setup, remove and reset are no longer commands — they are recognized as free-text synonyms and echoed back as the canonical verb. on/off are recognized as synonyms of enable/disable. The uninstall/purge split is deliberate: the generated files are machinery, .claude/features/** is your data. enable/disable on a FRESH (undeployed) target fall back to status and report there is no machinery to toggle.

Upgrading an existing board

/brewtools:task-board-setup upgrade <path> retrofits SPEC_MODE onto a repo that already has .claude/features/board.md — install refuses that repo outright and points here instead.

/brewtools:task-board-setup upgrade /path/to/repo

Upgrade installs two INDEPENDENT layers, gated file by file — not one all-or-nothing pass:

Layer	Gate	Adds
Spec layer	SPEC_MODE, forced on by upgrade	task-spec skill, SPEC_TEMPLATE.md, DESIGN_TEMPLATE.md, the spec-related sites inside existing files
Session-progress layer	ungated	PROGRESS.md + every site that references it (rule section, TRACKER.md, task-board skill, INDEX.md)

A repo that already has the spec layer but predates PROGRESS.md (an older run of this generator) gains only the session-progress layer on upgrade — no duplicate spec-layer insertion. A fresh init and an upgrade on that same repo converge on the identical final state either way.

• New files (the task-spec skill, the two spec templates, PROGRESS.md) are written outright.
• Every edit to an existing file is shown as a diff and gated behind AskUserQuestion, file by file. Declined means no edit.
• Task ids, scope ids and board rows are never renumbered, reordered or deleted. The one allowed board.md row edit is appending a spec cell (-- until task-spec fills it) to each existing progress/todo row.
• Backfilling spec: on existing tasks is opt-in and off by default; when accepted the value is pending or none — never full.
• Recovers domains / exclusions / language from the already-deployed artifacts instead of re-running analysis, and re-runs only the domain-agent inventory.
• Re-running upgrade on a repo where both layers are already installed is a no-op: upgrade: no-op, spec layer already installed.

Output discipline in the generated curator

task-tracker ships with an output contract: before returning, it spends one step on what the main session actually needs and returns only that — a verdict plus task ids and file:line pointers. It never pastes the board, task bodies or backlog listings back. Bulk material (long logs, full diffs, dumps, long reports) goes into a file under .claude/reports/<YYYYMMDD-HHMMSS>_<name>/ and only the path comes back. Its finishing checklist carries this as a row, so a curator run that dumps the whole board into the reply fails its own check.

ID convention

Task IDs follow UPPER-KEBAB: <PREFIX>-<DOMAIN>-<SLUG>.

Prefix	Use
T-	Feature / product task
BUG-	Defect
M-	Maintenance / refactor / tech-debt
EPIC-	Umbrella over several tasks

<DOMAIN> is the per-repo first kebab id-segment, discovered and confirmed in Step 1 (e.g. a frontend project might use UI, API, BUILD).

Version and ownership

Nine artifacts carry a four-key .md frontmatter: doc_type: llm, version, generated_by: "brewtools:task-board-setup", last_updated — the task-tracker agent, the task-board and task-spec skills, .claude/rules/tasks.md, and the five .claude/features/** control files. Per-task cards under backlog/, todo/, progress/, closed/ deliberately carry none of the four — they are your data, not generated machinery.

upgrade restamps version / generated_by / last_updated on every run, even when every content row is already a no-op SKIP. That restamp is the only thing that clears the stale verdict /brewcode:setup-status reads off board.md — an upgrade that reports success without moving the stamp sends you round the same loop next session.

Internals: placeholder map + reference files

Placeholder map — derived from confirmed Step 1 findings and substituted into every template before writing:

Placeholder	Derivation
{{DOMAINS}}	Confirmed domain id-segment list, comma-separated
{{FIRST_DOMAIN}}	DOMAINS[0]
{{EXCLUSIONS}}	Confirmed source-dir exclusion list
{{REPO_NAME}}	basename of TARGET
{{LANG}}	Confirmed doc language
{{TODAY}}	ISO date (YYYY-MM-DD)
{{CLOSE_MARKER}} / {{CLOSE_MARKER_SHORT}}	Derived from RELEASE_STYLE: vtag → vX.Y.Z tag + commit SHA / vX.Y.Z tag; sha → commit SHA; none → date / no tag / superseded / cancelled / no tag

Reference files (loaded from ${CLAUDE_SKILL_DIR}/references/):

File	Purpose
01-analysis.md	Step 1 analysis prompts + AskUserQuestion confirmation contract
02-task-tracker-agent.md	task-tracker agent template (placeholders)
03-task-board-skill.md	task-board skill template
04-tasks-rule.md	tasks.md rule template (includes run-at-start rule)
05-features-templates.md	.claude/features/** file templates
06-doc-sweep.md	Multi-agent doc-sweep procedure
07-claude-md-optimize.md	Optional gated CLAUDE.md optimization procedure (P5.5)
08-task-spec-skill.md	task-spec skill template (SPEC_MODE)
09-spec-templates.md	SPEC_TEMPLATE.md + DESIGN_TEMPLATE.md (SPEC_MODE)
10-upgrade.md	upgrade mode — retrofits the spec layer onto an already-deployed board