git:20261020.80d8396 to git:20261021.0401561

# 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` 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.

- `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` and `github.issues`.

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

- `status.md`'s `done:`/`skipped:` lines: written by `commit-task.sh`, read by `plan-index.sh`.

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