--- name: task-board-setup description: "Generator: deploys a file-based Kanban into any repo via multi-agent analysis, an optional spec + system-design layer (task-spec skill, per-task spec/design docs, domain-architect fan-out), and an optional gated CLAUDE.md-optimization pass. `upgrade` retrofits the spec layer onto an already-deployed board. Triggers: init task board, scaffold kanban, task tracker, upgrade task board, канбан-доска, спек-слой." user-invocable: true disable-model-invocation: true argument-hint: "[prompt] [status|install|upgrade|enable|disable|uninstall|purge] [target repo path | empty = cwd] [free-text directive, e.g. 'also dedupe rules', 'skip module split']" allowed-tools: [Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion] model: opus --- [DICT: TT=task-tracker agent (generated), TB=task-board skill (generated), BRD=board.md, FEAT=.claude/features, EXCL=source-path exclusions, REL=release style (vX.Y.Z tag | commit SHA | no tag), DOM=domain id segment, FM=frontmatter, TS=task-spec skill (generated), SPEC_MODE=spec+design layer opt-in, PS=status phase, PU=upgrade phase, PR=uninstall/purge phase] # task-board-setup Generator. Run from the MAIN conversation in (or pointed at) a TARGET repo. Deploys a self-contained, file-based Kanban into that repo: | Emits | Path | Mirrors etalon | |-------|------|----------------| | Curator agent | `.claude/agents/task-tracker.md` | brewpage `task-tracker.md` | | Dashboard skill | `.claude/skills/task-board/SKILL.md` | yasna `task-board` SKILL | | Paths-scoped rule | `.claude/rules/tasks.md` | brewpage `tasks.md` | | Board + control files | `.claude/features/{board,PROGRESS,TRACKER,TASK_TEMPLATE,INDEX}.md` + `{backlog,todo,progress,closed,specs}/` | brewpage `.claude/features/**` | | Spec skill (SPEC_MODE only) | `.claude/skills/task-spec/SKILL.md` | `references/08-task-spec-skill.md` | | Spec template (SPEC_MODE only) | `.claude/features/specs/SPEC_TEMPLATE.md` | `references/09-spec-templates.md` | | Design template (SPEC_MODE only) | `.claude/features/specs/DESIGN_TEMPLATE.md` | `references/09-spec-templates.md` | > **SPEC_MODE** (confirmed in P1) gates the three rows above AND every spec-related addition inside the other emitted artifacts. `SPEC_MODE=off` -> nothing spec-related is emitted and every artifact is byte-identical to the pre-spec-layer generator. > **`PROGRESS.md` is UNGATED** -- the session-progress artifact and every site that references it belong to BOTH modes' baseline. `SPEC_MODE` never removes them; byte-identity above means identical to the pre-spec-layer generator *plus* those sites. Each reference's own header enumerates its ungated sites (`02`, `03`, `04`, `05`) -- read it there, !=count from here. This skill ORCHESTRATES. It does not hand-do the bulk analysis or the doc sweep -- it spawns subagents (Task) for those passes and integrates their output. All emitted artifacts are PARAMETRIZED from Step 1 findings; templates live in `references/`. > **Spawn from MAIN only.** This skill is inline (no `context`), so its Task spawns are first-level. Do not nest. > **Read reference templates** with the `Read` tool using `${CLAUDE_SKILL_DIR}/references/` to load them into context. > **Fence rule -- GLOBAL, every emit on every path (P2, P3, P3.5, P4a-b, and `PU`'s U3/U4 drift-ADD).** When writing any generated file, unescape its inner code fences (`\`\`\`` -> ```` ``` ````) so the emitted file has valid fences. Stated once here; the reference templates !=repeat it. ## Prompt contract Position 1 of `$ARGUMENTS` is a **free-form prompt** -- the verb, the target path and the optional directive (P0 below) may all follow it in any order, exactly as P0 already parses them. Nobody types keys: a plain sentence resolves the verb. | Mode | EN keywords | RU keywords | Mutates? | |------|-------------|-------------|----------| | `status` | *(empty)*, status, check, show, what's deployed | статус, проверь, покажи, что стоит | no | | `install` | install, setup, deploy, scaffold, init, create board | установи, разверни, создай доску, настрой | yes | | `upgrade` | upgrade, retrofit, add spec layer, update | обнови, добавь спек-слой, апгрейд | yes | | `enable` | enable, turn on, resume, unpause | включи, возобнови, сними паузу | yes | | `disable` | disable, turn off, pause, mute | выключи, поставь на паузу, приглуши | yes | | `uninstall` | uninstall, remove, unwire | удали, убери, деинсталлируй | yes | | `purge` | purge, wipe, delete everything, nuke | вычисти, снеси, удали всё | yes, destructive | The verb-detection rule already in P0 (a standalone canonical token wins outright; a word merely containing one inside a sentence does not) IS this contract's steps 1-2 -- no reordering needed, P0 already scores correctly. Empty / no verb -> the documented default: `status` on a deployed board, else `install` into the resolved `TARGET` (P0's "No verb given" rule). A destructive tie (`uninstall` vs `purge`) still goes to `AskUserQuestion`; that already happens in P0's two-verb-conflict rule. Prose that names no canonical verb is DIR (the free-text directive), never guessed as a verb or path. Immediately after P0 finalizes `MODE` and `TARGET` -- before dispatching into `PS`/`PU`/`PE`/`PR`/P1 -- print this block once: ``` PLAN — brewtools:task-board-setup INPUT: MODE: -- SCOPE: ; SPEC_MODE ; touching DO: <2-5 imperative bullets> RESULT: ``` Labels are literal ASCII; values follow the conversation language. Every skill this generator emits (`task-board`, and `task-spec` when `SPEC_MODE=on`) carries this same contract baked into its own template -- prompt-first hint, its own keyword table, its own PLAN block. P5's prompt-contract gate below verifies both. ## Delegation A big task handed to one agent = an agent gone for an hour: you cannot observe it, cannot correct it, and it usually drifts off-target. One subagent = ONE bounded unit -- ONE doc group, ~<=5 files, ~<=10 steps. Bigger MUST be split into N tasks, all spawned in ONE message. Applies to both spawn points: P1 analysis and P4c doc sweep. Every spawn prompt MUST carry: | Field | Content | |-------|---------| | GOAL | the overall task and why it exists -- the point beyond the file edit | | ROLE | what this agent owns; what it must NOT touch | | SCOPE | exact paths/commands in bounds + explicit out-of-bounds | | CONTEXT | what is already done, by whom, what runs in parallel -- trimmed to what THIS agent needs | | CONSUMER | who or what uses the result next, and the shape it must fit | | DONE | acceptance criteria + the exact report shape you want back | A bare one-line task is never enough. Shape (P4c sweep agent): ``` Task(subagent_type="general-purpose", prompt=" GOAL: deploying a file-based Kanban into TARGET; the board skeleton exists and this pass fills it from the repo's pre-existing task docs. Sibling agents handle other doc groups. ROLE: you own . Do NOT create tasks that no document supports, do NOT edit source dirs, do NOT touch CLAUDE.md. SCOPE: in -- write ONLY under TARGET/.claude/features/**; read the listed DOCS. Out -- EXCLUSIONS (), TARGET/CLAUDE.md, .claude/agents, .claude/skills. CONTEXT: P1 already confirmed DOMAINS=<...>, REL_STYLE=<...>, LANG=<...> with the user, and P4a-b already wrote the board skeleton, TASK_TEMPLATE.md (id convention) and board.md (row format) -- read them, do not reinvent either. Sibling agents sweep the other doc groups into the same tree right now, so touch only the DOCS listed for you. CONSUMER: P5 verification counts what landed under closed/ + backlog/, and the installed task-tracker agent reads those files from then on -- an id or status dir that deviates from TASK_TEMPLATE.md makes the task invisible to it. DONE: files written under closed/ + backlog/, and a manifest: docs migrated by status, docs trashed, board rows authored. A no-op sweep must say so explicitly. ") ``` --- ## P0: Resolve verb + target repo + parse directive `$ARGUMENTS` carries THREE optional, order-independent things: (a) a MODE verb, (b) a target repo PATH, (c) a free-text DIRECTIVE that tunes the optional CLAUDE.md-optimization phase (e.g. "also dedupe rules", "skip module split", "report only"). Disambiguate: - A standalone token (case-insensitive) from the canonical set `status | install | upgrade | enable | disable | uninstall | purge` sets `MODE` and is CONSUMED -- it never reaches `DIR`. A word merely containing one of them inside a sentence (e.g. "upgrade the rules wording") is NOT the verb; only a standalone token is. Two conflicting verbs -> `AskUserQuestion`. - A token that resolves to an existing directory (abs, or relative to cwd) = the PATH. Empty / unresolvable-as-dir = cwd. - Everything else (the remaining free text) = `DIR`, passed verbatim to P5.5. If no path-like token is present, the whole non-verb argument is `DIR` and `TARGET`=cwd. - If ambiguous (e.g. a bare word that is both a plausible relative dir and a directive verb), prefer PATH only if it resolves to an existing dir; else treat as DIR. > `init`, `on`, `off`, `setup`, `remove`, `reset`, `create`, `update` and `cleanup` are NOT verbs any more. Recognize `init`/`setup`/`create` in free text as a synonym of `install`, `update` as a synonym of `upgrade`, `on`/`off` as synonyms of `enable`/`disable`, and `remove`/`reset`/`cleanup` as a synonym of `uninstall`/`purge` (ask which), then always echo the canonical verb back. Never print a removed alias as a command. **No verb given** -- resolve `MODE` from the board itself, after `TARGET` is known: a deployed board (`TARGET/.claude/features/board.md` exists) -> `status`; nothing deployed -> `install` into that `TARGET`. A bare path on a fresh repo therefore still installs, and a bare invocation on a repo that already has a board reports instead of touching anything. **EXECUTE** using Bash tool. Set `ARG` to the path-like token (or `.`): ```bash ARG="{{ARGUMENTS_PATH_OR_DOT}}" # the path-like token, or . for cwd TARGET="$(cd "$ARG" 2>/dev/null && pwd)" test -n "$TARGET" && test -d "$TARGET" && echo "TARGET=$TARGET" && echo "OK" || echo "FAIL: target not a dir" ``` > **STOP if FAIL** -- ask the user for a valid repo path. > **Shell state does NOT survive between Bash tool calls.** Every call is a fresh shell: a variable another block assigned is EMPTY here. So EVERY later block that consumes `TARGET` MUST open by re-establishing it literally -- `TARGET=""`, with the actual resolved path written in, !=the variable name, !=a re-derivation. Same for anything derived from it (`F`, `T`). This applies to all blocks below without exception. > **Gate blocks assert before they test.** A block whose SILENCE (or whose sole `OK` line) is read as PASS MUST first prove it ran, by opening with this exact statement: ```bash test -n "$TARGET" && test -d "$TARGET" || { echo "MISS TARGET unresolved -- re-resolve per P0"; exit 1; } ``` > Without it an empty `TARGET` makes the test run against a nonexistent path, the error gets eaten by `2>/dev/null` / `|| true`, and the gate reports PASS having checked nothing. "No output == PASS" is true ONLY when the gate actually ran. > `{{ARGUMENTS_PATH_OR_DOT}}` is resolved inline in P0 (the parsed path-like token, or `.`), not a template-emit placeholder -- it is absent from the Placeholder map by design. Record `DIR` = the remaining free text (may be empty) and `MODE` (`status|install|upgrade|enable|disable|uninstall|purge`, or unset); hold both. **Branch on board presence.** An existing `TARGET/.claude/features/board.md` means the board is already deployed. `install` refuses it; `upgrade`, `enable`, `disable`, `uninstall` and `purge` EXPECT it. **EXECUTE** using Bash tool: ```bash TARGET="" test -n "$TARGET" && test -d "$TARGET" || { echo "MISS TARGET unresolved -- re-resolve per P0"; exit 1; } test -f "$TARGET/.claude/features/board.md" && echo "EXISTS" || echo "FRESH" ``` Resolve an unset `MODE` here: `EXISTS` -> `status`, `FRESH` -> `install`. Then dispatch: | `MODE` | board.md | Do | |--------|----------|-----| | `status` | either | go to **PS**. Read-only -- never writes, never asks | | `install` | `FRESH` | continue to the MAJOR-4 guard, then P1 (fresh deploy) | | `install` | `EXISTS` | STOP. "Board already deployed. To retrofit the spec + design layer onto it, re-run as `/brewtools:task-board-setup upgrade `. To operate the existing board, use `/task-board`." Do not overwrite | | `upgrade` | `EXISTS` | go to **PU** -- control transfers to `references/10-upgrade.md`. Skip P1-P5.5 entirely | | `upgrade` | `FRESH` | STOP. "Nothing to upgrade: no `.claude/features/board.md` in TARGET. Run `/brewtools:task-board-setup install ` to deploy a fresh board" | | `enable` | `EXISTS` | go to **PE** with `WANT=enable` | | `disable` | `EXISTS` | go to **PE** with `WANT=disable` | | `enable` / `disable` | `FRESH` | run **PS** instead and report that nothing is deployed. There is no machinery to toggle | | `uninstall` | `EXISTS` | go to **PR** with `KEEP_DATA=true` | | `purge` | `EXISTS` | go to **PR** with `KEEP_DATA=false` | | `uninstall` / `purge` | `FRESH` | run **PS** instead and report that nothing is deployed. Do not delete anything on a guess | > Print the `## Prompt contract` PLAN block once here -- `MODE` and `TARGET` are both resolved -- > before continuing into the dispatched phase. **MAJOR 4 -- idempotency guard.** `install` path ONLY (`MODE=install` and board.md `FRESH`); `upgrade`, `uninstall` and `purge` skip it, since pre-existing artifacts are exactly what they operate on. A `FRESH` board.md does not prove a clean slate: a prior run may have left other artifacts. After the board.md check, **EXECUTE** using Bash tool: ```bash TARGET="" test -n "$TARGET" && test -d "$TARGET" || { echo "MISS TARGET unresolved -- re-resolve per P0"; exit 1; } PARTIAL="" for p in .claude/agents/task-tracker.md .claude/skills/task-board/SKILL.md .claude/rules/tasks.md \ .claude/skills/task-spec/SKILL.md; do # A parked `.disabled` twin still occupies the slot -- an install over it would orphan it. test -f "$TARGET/$p" -o -f "$TARGET/$p.disabled" && PARTIAL="$PARTIAL $p" done test -z "$PARTIAL" && echo "CLEAN" || echo "PARTIAL:$PARTIAL" ``` > If `PARTIAL:` is non-empty (and board.md was `FRESH`), STOP and report the partial deployment. Do NOT blindly overwrite -- ask the user whether to clean those artifacts and redo, or abort. `upgrade` is NOT the fix here: with no board.md there is nothing to upgrade. --- ## PS: Status (read-only inventory of the TARGET) Runs for `MODE=status` -- the default on an already-deployed board -- as the fallback when `enable`/`disable`/`uninstall`/`purge` find nothing, and as the proof block after **PE** and **PR**. **Writes nothing, spawns nothing, asks nothing.** **EXECUTE** using Bash tool: ```bash TARGET="" test -n "$TARGET" && test -d "$TARGET" || { echo "MISS TARGET unresolved -- re-resolve per P0"; exit 1; } C="$TARGET/.claude"; F="$C/features" # A `.disabled` twin is a PARKED artifact (see PE), not a missing one -- never report it as MISS. for p in agents/task-tracker.md skills/task-board/SKILL.md rules/tasks.md skills/task-spec/SKILL.md \ features/board.md features/PROGRESS.md features/TRACKER.md features/TASK_TEMPLATE.md features/INDEX.md \ features/specs/SPEC_TEMPLATE.md features/specs/DESIGN_TEMPLATE.md; do if test -f "$C/$p"; then echo " ok $p" elif test -f "$C/$p.disabled"; then echo " off $p (parked as $(basename "$p").disabled)" else echo " MISS $p"; fi done for d in backlog todo progress closed specs; do n=$(ls -1 "$F/$d"/*.md 2>/dev/null | wc -l | tr -d ' ') test -d "$F/$d" && echo " ok features/$d/ ($n md)" || echo " MISS features/$d/" done echo "TARGET=$TARGET" ``` Report, in this shape: ``` task-board-setup — status target: deployed: yes|no|partial (board.md present / absent / some artifacts only) machinery: enabled|DISABLED|mixed (every artifact live / every one parked as .disabled / some of each) spec layer: on|off|parked (.claude/skills/task-spec/SKILL.md present / absent / .disabled) tasks: backlog=N todo=N progress=N closed=N specs=N next: install | upgrade | enable | nothing to do ``` `partial` -> name the missing artifacts and say a fresh `install` refuses to overwrite; the user must clean them first. `deployed: yes` + no spec layer -> `next: upgrade`. `machinery: DISABLED` -> `next: enable`, and say the tasks are all still there. `machinery: mixed` -> list which side each artifact is on and recommend re-running the verb that was interrupted. --- ## PU: Upgrade mode (retrofit onto a deployed board) Runs ONLY when `MODE=upgrade` and `board.md` EXISTS. Replaces P1-P5.5 -- do not run the fresh-init phases. Load the upgrade procedure: Read file: `${CLAUDE_SKILL_DIR}/references/10-upgrade.md` Hand it: | Input | Value | |-------|-------| | `TARGET` | resolved in P0 | | `DIR` | remaining free text from P0 (may be empty) | | recovered FINDINGS | `DOMAINS`, `EXCLUSIONS`, `LANG` re-read from the DEPLOYED artifacts (`.claude/rules/tasks.md`, `.claude/features/TRACKER.md`, `.claude/agents/task-tracker.md`), NOT re-derived from scratch. Anything unrecoverable is ASKED of the user per `10-upgrade.md` U2 -- !=re-analysed, !=guessed. P1 does NOT run on this path, and Agent C (row below) is the only analysis spawn in upgrade mode | | Agent C output | `DOMAIN_AGENTS`, `ARCHITECT_AGENT`, `AGENT_GAPS` -- always run fresh (the target's agent roster is the whole point) | | `SPEC_MODE` | forced `on` | Rules that bind the whole phase: - **Additive only.** New files (`task-spec` skill, `SPEC_TEMPLATE.md`, `DESIGN_TEMPLATE.md`) are written outright. No existing task file, board row, agent, skill or rule is rewritten wholesale. - **Every edit of an existing file is gated:** show the exact diff, then **AskUserQuestion** per file. Declined = no edit, continue cleanly. - **The metadata restamp (`10-upgrade.md` U5b) is UNGATED and always runs**, including when every content row is already SKIP. It rewrites `version` / `generated_by` / `last_updated` in the frontmatter of the nine stamped artifacts and nothing else -- that 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 the user round the same loop next session. - **Never renumber, never delete.** Existing task ids, scope ids and closed tasks are untouchable. `board.md` rows are never REORDERED and existing cell content is never CHANGED -- the one allowed row edit is APPENDING the new `spec` cell holding `--` to each existing Progress/Todo row, per `10-upgrade.md` U4 (header + separator cells patch with it; a 6-column header over 5-cell rows is corruption, not caution). `spec:` FM backfill is opt-in and !=run by default -- the default writes nothing to task files. When the user accepts it, the value is `pending` or `none` per the needs-spec heuristic -- never `full`. > `PU` is a thin handoff: `10-upgrade.md` owns detect, verify and report. Do NOT reuse P5 here. --- ## PE: Enable / Disable (park or restore the machinery, keep every task) Runs for `MODE=enable` / `MODE=disable` on a deployed board. Replaces P1-P5.5. Writes no content, deletes nothing, spawns nothing. Claude Code discovers a project agent only as `.claude/agents/.md`, a project skill only as `/SKILL.md`, and auto-loads a rule only as `.cl