CLAUDE.md@viber git:20261022.beb922eA

Immutable. This exact content never changes and is served at /api/v1/blob/275eaf257af84c00.

# viber - the idea-to-commit workflow plugin

viber owns the pipeline that runs across its skills, agents, hooks, scripts and references: the `.claude/viber.yml` config, the run directory and its archive, the plan gate, and the user docs (`README.md`, `docs/configuration.md`, `docs/files.md`, `BRANCHING.md`, `PRODUCT.md`, the help page). Each subdirectory's own contracts live in its node; this file carries only what spans them.

## Terms

- Run: one approved plan being built in `docs/<directories.runs>/<yyyy-mm-dd-HH-mm-ss>_<slug>/` (default `_specs`), its directory name being the run key. The archive is `docs/<directories.specifications>/<same name>/` (default `specs`).
- Switch: a key of `.claude/viber.yml` that counts only as a child of its own group (`build.qa`, never a flat `qa`), on only when it reads `true`. `build.baseline-tests` is three-valued (`off`, `fast`, `full`); `build.extensions` is a map of agent entries, not a switch; `github.*-title`, `directories`, `tiers`, `branching`, `planning.questions-per-round` (`1` to `10` or `all`, read only by `config.sh --questions`) and the `build.red-check-tests`/`-links` lists (read only by `config.sh --red-check`) are settings.
- Fragment: `skills/<skill>/fragments/<name>.<value>.md`, the switch-dependent text a skill preloads through `scripts/switch-text.sh`, or, inside a `parts/<name>.md`, gets resolved by `scripts/skill-part.sh` when it prints the part. No file for a value means that value adds no text.
- Tier: `haiku` < `sonnet` < `opus` < `fable`. `implementor` clamps every dispatch into `tiers.min`..`tiers.max` and each next attempt climbs one tier; `fable` is reached only when a project names it.
- Close: the build's end steps after the final test run, in order `memory`, `rules`, `qa`, `extensions`, `cleanup`, each driven by its switch.

## Relationships

- Pipeline: `setup` once; `triage`, `issue-create`, `prototype` and `pr-feedback` (the review threads of a pull request, on its own branch) feed `intent` (or `fixer` for a bug); `intent` hands to `planner` (not user-invocable), which writes the plan in plan mode behind the plan gate; `implementor` (not user-invocable, entered from the approved plan's `source:` line) lands it with `scripts/plan-path.sh`, dispatches agents, commits each task with `scripts/commit-task.sh` and ends on the close, where the `closeout` agent commits the files the build left uncommitted without a deliberate reason (`scripts/commit-task.sh --outside`), writes `outcome.md` and calls `scripts/archive-run.sh`. `talk`, `e2e`, `pr-create`, `memory`, `rules`, `extension`, `code-auditor`, `help`, `handoff`, `commit`, `pro-designer`, `idea-validator` and `skill-designer` stand alone.
- Agents are dispatched only by viber skills, as `viber:<name>`; `hooks/scripts/plan-gate.sh` looks for dispatches of `viber:planner-review`, the review set (`viber:planner-spec-review`, `viber:planner-graph-review`, `viber:planner-task-review`) and `viber:outside-plan-review` in the transcript, and `kill-guard.sh` acts only on an `agent_type` starting with `viber:`.
- `PRODUCT.md` holds the product assumptions (the four test layers `unit`, `component`, `integration`, `e2e`; one final test run; e2e only on explicit request) for maintainers; no shipped file reads it.
- The root `README.md` of the repository is viber's landing page (pitch, loop, install); `README.md` here is the usage guide, and `docs/configuration.md` (every `.claude/viber.yml` key) and `docs/files.md` (every host write) hold the reference it links to.
- `BRANCHING.md` is the full `branching:` schema, linked from `README.md`, `docs/configuration.md` and `skills/setup/templates/viber.yml`. `skills/setup/assets/help.html` is the bilingual (`en`/`pl`) usage guide `/viber:help` opens.
- Child nodes: `agents/CLAUDE.md`, `hooks/CLAUDE.md`, `references/CLAUDE.md`, `scripts/CLAUDE.md`, `skills/CLAUDE.md`.

## Contracts

- `scripts/config.sh` is the one parser of `.claude/viber.yml`: resolved against the repository root, always exit 0, every switch false without the file. Skills preload it, and `switch-text.sh`, `pr-facts.sh` and `plan-gate.sh` run it rather than reading the file; only the `directories.runs` readers listed under Change together parse the file themselves. `.claude/viber.local.yml` overrides exactly `tiers.min`, `tiers.max`, `build.baseline-tests`, `github.issues` and `planning.questions-per-round`.
- The column-0 `schema:` of `skills/setup/templates/viber.yml` is the layout the installed viber expects: `hooks/scripts/session-start.sh` compares the project's number to it, and `skills/setup/scripts/bootstrap.sh` raises the project's number to it, never lowers it.
- Run directory, one writer per file: `plan.md` and `attachments/` (the files of the plan's `attachments:` map, replaced on a draft round, a former copy kept when its source is gone) by `plan-path.sh --land` (`plan.md` never edited after), `spec.md` and `tasks/T<n>.md` by `plan-index.sh --split`, `status.md` and `rulings.md` (`--rule`) by `commit-task.sh` alone, `qa.md`/`qa.e2e.md` by `qa-writer`, `outcome.md` by `closeout` (which also commits the leftovers through `commit-task.sh --outside`); in `work/`, `<id>-extra.md` and `<id>-options.md` by `task-coder`, `<id>-extra-review.md` by `task-reviewer`, `ruling-<subject>.md` by `arbiter`, which `commit-task.sh` reads. `archive-run.sh` drops the scaffolding `plan.md`, `status.md`, `tasks/`, `work/` and moves everything else to the archive in one commit.
- `implementor` opens no file: all it knows comes from its preloads and script stdout (`config.sh`, `run-clock.sh`, `plan-index.sh`, `plan-path.sh`, and `skill-part.sh` for its `close` part), so a fact it needs is added to a script's output, never to a file for it to read.
- Every agent but `scout`, `mapper` and `hunter` ends on a `VERDICT:` line; a refused tool call ends a non-auditor agent on `VERDICT: DENIED` plus `REASON: <tool>: <command or path>`, which the dispatching skill turns into a question, except a refusal whose reason opens with `viber guard:` (`kill-guard.sh`, `shell-guard.sh`): the agent corrects the command and goes on. A `SubagentStop` hook (`verdict-nudge.sh`) sends an agent that ended without that line back once, so no skill sends the nudge itself.
- TDD seal: a PASS of a `TDD: required` task carries `RED: <n> failing | <log>` or `RED: missing <symbol> | <log>` from `task-coder` (log `.temp/viber/<id>/red.log`, or `red-<n>.log` when a later attempt reverts the behaviour in the tree); `implementor` treats a PASS without it, or with `0 failing`, as a coder failure, then with `build.red-check` on runs `scripts/red-check.sh` and hands its one `red-check:` line (`FAIL-AS-EXPECTED`, `PASSED-WITHOUT-CHANGE`, `UNRUNNABLE`) and `red: <log>` to `task-reviewer`. Review of a `TDD: required` task is never waived.

## Change together

- A switch added, removed or renamed: `scripts/config.sh` (key grammar and its fixed stdout order), the key list of `scripts/switch-text.sh`, the switch list hard-coded in `skills/setup/scripts/bootstrap.sh`, `skills/setup/templates/viber.yml`, the `docs/configuration.md` switch table and its count sentence, `help.html` in both languages, and `tests/viber/config.test.ts` / `switch-text.test.ts`.
- The `RED:` and `red-check:` lines: `agents/task-coder.md`, `references/tdd.md`, `skills/implementor/SKILL.md` and `fragments/red-check.true.md`, `scripts/red-check.sh` and `agents/task-reviewer.md`.
- `directories.runs` is parsed with the same grammar (`[A-Za-z0-9._-]+`, not `.` or `..`, default `_specs`) in `scripts/config.sh`, `scripts/plan-path.sh`, and `scripts/archive-run.sh`.
- The `SCRATCH:` line: `agents/task-coder.md` (writes it), `agents/task-reviewer.md` (names it as the fix for a leftover), `skills/implementor/SKILL.md` (its Scratch return bullet calls `commit-task.sh --drop`, and a kept path becomes a `left uncommitted:` summary line) and `agents/arbiter.md` (its `## Actors` names the line as the only way to delete an untracked file).
- The plan's task block (`<!-- TASK -->` ... `<!-- /TASK -->`, `### T<n> - <title>`, the `- <Field>:` lines): `skills/planner/templates/tasks.md`, `references/plan-rules.md`, `scripts/plan-index.sh` (validates and splits), and `scripts/commit-task.sh` (commit subject from the heading, staging from `Files:`). A task's `Covers:` cites criteria as `AC<n>`, as do the QA documents of `references/qa-format.md`: `#<n>` would render as a link to an unrelated issue.
- The plan's `attachments:` map and the `attachments/<name>` form a task's `DoD` names: `skills/planner/templates/spec-full.md`/`spec-lite.md`, `planner/SKILL.md`, `agents/planner-review.md`, `agents/planner-spec-review.md`, `scripts/plan-path.sh` (validates and lands), `scripts/plan-index.sh` (lists in `spec.md`), `agents/task-coder.md` and `agents/task-reviewer.md` (read it from the run directory).
- `status.md`'s `done:`/`skipped:` lines: written by `commit-task.sh`, read by `plan-index.sh`.
- The plan frontmatter `source:` line: `skills/planner/templates/spec-full.md`/`spec-lite.md`, `planner/SKILL.md`, `implementor/SKILL.md` step 1 and `hooks/scripts/plan-gate.sh` (it picks the planner's reviewers over `outside-plan-review`).
- The planner's input: `skills/intent/parts/done.md` writes the confirmed summary to `.temp/viber/intent/summary-<stamp>.md` and passes its path (the text itself inside plan mode, `fixer` always text); `skills/planner/SKILL.md`, `references/adr-tasks.md`, `agents/planner-review.md`, `agents/planner-spec-review.md`, `agents/adr-screener.md` and the deny text of `hooks/scripts/plan-gate.sh` each take `input:` as that path or that text.
- The run branch decision: `scripts/run-branch.sh` (`branch_decide`, printed by `plan-path.sh --start` after today's lines) decides what to settle or ask; the four `branching-start.*` fragments of `skills/intent/` and `skills/fixer/` only show or ask it, so a new answer or note is added to the script and to those fragments together.
- The root cause of a fixed defect: the optional `## Root cause` of `skills/planner/templates/spec-full.md`/`spec-lite.md`, its `references/plan-rules.md` rule (present only for a `viber:fixer` diagnosis, code-auditor findings or an input carrying a `Root cause:` line, which `intent` writes into the first part's summary of a split `viber:fixer` diagnosis) and `agents/memory-writer.md` (turns it into the first traps of the run).
- The build-close rules behavior: `agents/rules-writer.md` (spec shape adds and corrects only, map shape compacts and splits), the per-run cap of `references/rule-admission.md` and the `/viber:rules` pointer of `skills/implementor/fragments/rules.true.md`.
- A user-facing behavior: `README.md`, `docs/` and `help.html` (`en` and `pl` spans) describe the same features; a headline capability also reaches the root `README.md`.

## Traps

- A new switch reaches an existing project only when `/viber:setup` reruns, and session start asks for that rerun only while the project's `schema:` is below the template's.
- `bootstrap.sh` restores a deleted key of `planning:`, `build:`, `github:` or `directories:`, but appends `tiers:` or `branching:` only when the whole group is missing: a deleted child there silently resolves to its `config.sh` default.
- A switch written at column 0 or under another group reads as off, with no error.
- `BRANCHING.md`'s "part 2" (`releases:`, `version:`, release branches) does not exist: never implement or document it as present.