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	Task-tracker, task-board skill, tasks rule, board tree, domain methodology, anti-drift instructions, task graph, and session progress
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), the task-tracker curator, and shared methodology and anti-drift controls. Each task prepares its own work units, review and test strategy, acceptance evidence, and tick prompt before implementation.

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.
Domain methodology	.claude/features/METHODOLOGY.md	Shared domain risks, authoritative instructions, review strategy, and reliable check commands; each task specializes it.
Anti-drift instructions	.claude/features/ANTI-DRIFT.md	Task-specific tick prompts, timer lifecycle, reconciliation, and compact reporting contract.
Active task graph	.claude/features/task-graph.md	Derived dependencies, owners, statuses, and acceptance evidence; all unfinished nodes plus the latest ten completed nodes.
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.

Task methodology and session anti-drift

These controls are installed in both spec modes. The shared methodology comes from your domain and repository instructions: how work should be reviewed, which checks are reliable, and what evidence proves completion. Every accepted task specializes it in its own ## Methodology, with goal and acceptance criteria, domain reviews/tests, base work units, owners, dependencies, and a parent task id when applicable.

The baseline work is to confirm scope and user corrections, assign bounded work, implement, simplify, review correctness and safety, review clarity and missing validation, run reliable checks, and reconcile evidence and the board. Each task refines those units for its actual goal.

One session timer per active top-level task

The main session’s /task-board flow owns timer creation and cleanup. Task-tracker owns file and graph reconciliation and returns scheduling actions to the main session. Each top-level task stores a complete, unique prompt in ## Anti-drift cron before scheduling. Queued tasks retain prepared prompts; scheduling begins when a task becomes active. Child work units use their parent’s timer.

The default schedule is hourly (0 * * * *). Your cadence override or opt-out takes precedence. Task-board lists existing timers before creating one, reuses a matching task/project timer, and verifies duplicate removal or replacement. It announces the effective cadence, timezone, confirmed timer id and state, known first due time, session scope, and stop/change controls.

With available Claude Code scheduling tools, the main session uses CronList, CronCreate, and CronDelete. If tools are unavailable, denied, or at capacity, it retains the task prompt and reports that scheduling is unavailable. Saved ids do not prove a timer is live. Timers are session-scoped; scheduled time, firing, and actual receipt are distinct, and delivery time is approximate. The task record persists evidence, not a scheduler that survives session closure.

What each delivered tick does

• Reread shared and task methodology, anti-drift controls, current goal/spec, task records, and user corrections.
• Obtain concise evidence from available active agents; reconcile statuses, dependencies, counts, and next work.
• Rebuild task-graph.md, retaining every unfinished node and the latest ten completed nodes. Preserve older completion evidence in task Notes or closed records before pruning graph rows.
• Check drift against the goal and acceptance criteria, correct deviations within authorized scope, quantify remaining work or mark it unknown, and advance the next unblocked step.
• Persist the delivered tick number and actual receipt time, then produce at most five compact lines using only 🟢 🔵 🔴 ⚪ as status circles.

For example, a delivered tick can report:

🔵 TASK-ID · 14:03 Europe/Lisbon · tick 2 · elapsed 2h
🟢 Implemented API change; targeted checks pass
🔵 2 work units remain · next: independent review
🔴 Blocker: missing fixture · question: provide approved sample?
⚪ Drift: none verified against recorded acceptance criteria

Omit the blocker/question line when absent. Full evidence belongs in the task record. Graph pruning removes rows only: the canonical board and closed task records retain completed work. On completion, cancellation, or parking, task-board stops this task’s timers and verifies their absence; a failed deletion remains a reported cleanup gap. Resume reconciles scheduling again.

Planning and +++

In Plan mode, include methodology, base work and graph reconciliation, the complete task-specific prompt, a timer execution step, and the final PROGRESS refresh. Planning is read-only: defer file writes and timer creation/deletion until authorized execution. A tick received during planning reports proposed reconciliation only.

Typing +++ in Plan mode injects this planning requirement through the plugin’s prompt hook. Outside Plan mode, it adds no cron instruction. A /task-board view remains read-only and reports missing or stale state without scheduling.

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	Adds missing controls and refreshes generated machinery while preserving task-specific methodology, prompts, and evidence
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 checks independent layers, gated file by file:

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)
Methodology and anti-drift	ungated	Shared methodology, anti-drift instructions, derived task graph, task-template sections, and runtime/discovery instructions

A repo with an existing spec layer can still gain missing progress or methodology controls. Upgrade preserves domain decisions, task-specific methodology, saved prompts, runtime state, and completion evidence; it adds missing sections instead of replacing that content.

• Missing control files and approved new spec artifacts are added; existing user content is preserved.
• 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.
• A content-no-op upgrade still reports provenance refresh separately; installed spec artifacts do not bypass missing methodology checks.

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).

Content version and ownership

With the optional spec layer deployed, twelve control artifacts carry doc_type: llm and the provenance quartet: version, content_version, generated_by: "brewtools:task-board-setup", and last_updated. These are the task-tracker agent, task-board and task-spec skills, .claude/rules/tasks.md, and eight controls under .claude/features/: board.md, TRACKER.md, INDEX.md, PROGRESS.md, backlog/README.md, METHODOLOGY.md, ANTI-DRIFT.md, and task-graph.md. Without the optional spec layer, task-spec is absent. TASK_TEMPLATE.md and per-task cards under backlog/, todo/, progress/, and closed/ deliberately carry no generator stamps: their frontmatter describes task data.

content_version is the headline for content freshness; version records the plugin release that wrote the artifact. Setup reads the former from this generator’s own brewcode-meta marker and resolves the latter from the installed brewtools plugin. /brewcode:setup-status reads board.md as the anchor, comparing its content_version with the generator’s content version; legacy anchors without that key fall back to version.

Every upgrade runs the ungated metadata refresh, even when all content rows are SKIP. It updates only the quartet in each present control artifact’s existing frontmatter, preserving doc_type, body content, task decisions, saved prompts, scheduler ids, and tick counters. A refreshed content stamp can clear the version-related stale signal. Metadata refresh does not prove that content changes were accepted or that missing artifacts were repaired; read the separate added, patched, skipped, and declined results and the named absent controls.

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)
{PLUGIN_VERSION} / {CONTENT_VERSION}	Installed brewtools release / this generator’s own brewcode-meta content version; resolved independently
{GENERATED_BY} / {LAST_UPDATED}	brewtools:task-board-setup / the same ISO date as {{TODAY}}
{{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
11-methodology-cron.md	Shared methodology, anti-drift lifecycle, derived task graph, and task-local work and cron sections