CLAUDE.md · diff

git:20261006.1ff74f0 to git:20261007.aaa7079

21 added, 166 removed. Audit A to A.

- # P2P2 Claude Code plugins (one per subdir) + marketplace catalog

- > Always in English: every CLAUDE.md, script, skill, agent and reference.

- > Every plugin script MUST work on Windows (Git Bash) and macOS.

- > Do not use `heredoc` - it is unreliable.

- > Do not use `red` color in agents.

- > Present state only: every CLAUDE.md, README, help page and `.claude/rules/` file says what holds

- > now, never a change history (what changed, was renamed, replaced or used to hold): git keeps that.

- > Tokens are a design constraint: every token a skill, agent or reference makes a model read

- > counts against the user's Claude Code usage limits (5-hour and weekly), and an agent holding

- > too many instructions at once drifts. Prefer the design that makes a model read and re-read less.

- This repo is the **source** of four independently installable Claude Code plugins - `superui`,

- `superbiz`, `supercc`, `viber` - co-listed by the root

- `.claude-plugin/marketplace.json` (marketplace name `p2p2`). The retired `superdev` plugin sits in

- `docs/archive/superdev/` for reference only: not listed, not released, not tested, not shipped.

- Editing a file here does NOT change the plugins loaded in the current session: skill bodies and

- the injected manifest were frozen at install / session start and change only after a release is

- published and reinstalled. This repo's own `CLAUDE.md` files and `.claude/rules/` are dev-time

- orientation for editing the source, never plugin inputs, never read at runtime.

- No application code ships: artifacts are markdown (skills, agents, references) + JSON

- (manifests) + bundled scripts (bash everywhere, plus `viber`/`superui` `.ts` run by Node and

- `superbiz`'s Python report builder). Editing markdown/JSON IS shipping - no build step, no lint,

- no test tooling inside any plugin. The only automated checks are the dev-time suites under

- `tests/` (per-plugin suites for superui and viber - supercc and superbiz have none -

- plus `github/` for `release.sh` and the root-level `harness`, `portability` and `orphan-tags`

- sweeps): locally only the unit tier (`*.unit.test.ts`, seconds), the integration tier in CI only

- (`tests/CLAUDE.md` defines both); every other contract between files is enforced by a human

- reading carefully.

- All four plugins are **stack-agnostic on purpose**: skills read project-specific knowledge (test

- framework, build tool, naming, how to launch the app) from the HOST project's `CLAUDE.md` /

- `.claude/rules/`, never from plugin sources. Never bake ecosystem assumptions (dotnet, npm,

- pytest) into a skill prompt. This binds the projects being planned/built, not a plugin's own

- tooling: a plugin may depend on a specific tool for its own work as a deliberate, documented

- choice (Node for superui's contrast checker and viber's `code-auditor` gates, Python for superbiz's report, playwright-cli and

- `@playwright/test` for viber's user-only `e2e` skill, installed only once the user agrees), always named in the owning plugin's node. Prefer putting such a dependency

- behind an opt-in switch or a skip-with-note fallback where that is practical - a recommendation,

- not a requirement.

- **DO NOT use ADR capture for this project.** The plugins are constantly refactored; never write

- ADRs here and never suggest them (`.claude/viber.yml` keeps `adr: false`).

- # During plan-mode

- When user ask and you need to decide how to design a solution for this repository and plan implementation, always find out what the functional scope of claude code harnes is for today using exited precedent or use `claude-code-guide`.

- # Readme files

- Readme files are for human. Should be short, simple and contain only essential information how to use it, without implementation details of these plugins.

- ## Layout (top level)

- ```

- .claude-plugin/marketplace.json Co-lists the four plugins by subdir source

- superui/ superbiz/ supercc/ viber/ One dir per plugin, each with README.md

- README.md Catalog page for humans (install commands, requirements)

- LICENSE, CONTRIBUTING.md, SECURITY.md MIT; issues welcome, outside PRs not accepted; vulnerability reports

- .github/ CI, release workflow + scripts/release.sh, CODEOWNERS

- .claude/ Dev-time rules/, settings, viber.yml switches for building THIS repo

- tests/ Dev-time regression suites for plugin scripts (outside every plugin)

- docs/archive/ Retired plugins kept for reference (superdev), never shipped

- docs/specs/ viber's archived runs of work on this repo

- ```

- Each plugin dir carries `.claude-plugin/plugin.json`, whose `skills[]` (and `agents[]` for

- `viber`) is the catalog of record. Only `viber` carries `hooks/`.

- ## Versioning and CI

- Tag-driven, one shared version across all four plugins, bumped only by a manual release workflow.

- Read `CLAUDE.release.md` before editing `.github/` (CI, release workflow, `release.sh`) or

- cutting a release.

- ## Cross-plugin architecture invariants

+ # P2P2 Claude Code plugins

- - **Host-repo `docs/` is the one home for persisted, user-facing knowledge.** viber's run

- directory `docs/_specs/<stamp>_<slug>/` (plan, `status.md`, decomposition, QA documents,

- `work/`, the run's notes - committed, because a build resumes from it in another session or

- machine) and its archive `docs/specs/<stamp>_<slug>/` (what `cleanup` leaves: the

- specification and QA documents; both directory names configurable in `viber.yml`);

- `docs/business/<slug>/` (superbiz's rendered report only); `docs/adr/`, written by viber

- through a plan task. `supercc` writes no `docs/<layer>/` - its deliverable is the skill/agent

- file itself.

- - **No plugin ever creates a plugin-named dot-dir in the host repo** (no `.superui/` etc.). Only

- three host locations are writable at a plugin's own choosing: `docs/<layer>/`, `.claude/`

- (user-owned config/rules) and `.temp/<plugin>/` (every temporary artifact). A fourth is writable

- only because the HOST names it: the host's e2e test dir, resolved by viber's `e2e` skill from

- the project's own instructions, else one direct answer from the user, and passed to

- `e2e-writer` as `spec-dir:` - never a default of its own, never a sibling it invented.

- - **`viber` is the only manifest-bearing plugin.** Its `SessionStart` hook injects

- `hooks/content/manifest.md` verbatim once per session (`resume` excluded, fail-open: an empty

- or unreadable file leaves only the banner). The manifest is not a dispatcher: it names a

- viber skill only to scope a rule (an exception or a limit), never to route to it; routing is

- each skill's own CSO `description:`.

- - **Script vs. fork.** A step collapses to a deterministic bundled script when it operates on a

- known, fixed tool/format (git, a basename, paths, globs); it stays an LLM fork when it must

- interpret heterogeneous, stack-specific output. A script whose header carries its I/O contract

- is TRUSTED by its caller - never re-verified or retried.

- - **Pre-approved bundled-script calls, skill side.** In viber, every `!` preload and every

- runtime `Bash` call of a bundled script is one literal line `"${CLAUDE_PLUGIN_ROOT}/.../x.sh" <args>` (never

- `bash`-prefixed, never assigned, never after `cd`, never chained with `;`), with one matching

- `Bash(${CLAUDE_PLUGIN_ROOT}/.../x.sh:*)` PATTERN in the skill's `allowed-tools` - a bare `Bash`

- allow does not cover a preload, and the permission classifier matches the literal prefix, so

- any other form is a new, unapproved command. Single-quote any preload argument holding `?`,

- `*` or `[`: the host shell (zsh on macOS) parses it first and `nomatch` kills the fork load. No

- PowerShell syntax anywhere. The script-side half lives in `.claude/rules/`. The other three

- plugins, and viber's `code-auditor` (a bare `Bash` allow), call their scripts through an

- interpreter (`sh`, `bash`, `node`, `python3`).

- - **`allowed-tools` does NOT restrict the tool set** - it is a one-turn pre-approval only. A

- strictly read-only skill needs `disallowed-tools:` (bare names, never `Tool(pattern)`) PLUS a

- body line naming its only tools; the agent-side equivalent is `tools:`. A skill that dispatches

- agents never carries `disallowed-tools:`: the removal holds until the next user message,

- subagents included, so every agent dispatched meanwhile runs without those tools. Such a skill

- states its limits in its body, which is soft: a hard limit goes into each dispatched agent's

- `tools:` or into permissions. A skill that both `!`-preloads and denies bare `Bash` is

- undefined behavior.

- - **Dispatch strength.** An orchestrator's dispatch passes only `model` - the `Agent` tool takes

- no `effort`, so an agent's frontmatter is the only place its effort is set.

- - **Text is the product in THIS repo.** Skill, agent and reference markdown plus the JSON

- manifests are production code here, so no task editing them ever skips its per-task review,

- however mechanical it looks. This line is the host declaration the planning track reads:

- - viber: `implementor` never profiles a task touching this repo's markdown or `plugin.json` as

- mechanical/no-review; such a task gets at least the `sonnet` plus review profile, and

- `task-reviewer` gates it before `commit-task.sh`.

- - **No orphan closing tag in a written file.** Writer agents sometimes end a created file with a

- bare `</content>` leaked from their own write call; the read-back guard in every writing agent

- lowers the rate but never removes it. `tests/orphan-tags.unit.test.ts` fails CI on any tracked file

- outside `docs/` holding a closing tag with no opener.

- - **Self-documentation.** A skill add/remove/rename updates the owning `plugin.json` `skills[]`,

- an agent one its `agents[]`, and the owning `<plugin>/CLAUDE.md` in the same edit (this root

- file only when the change is repo-wide). A worker never appears in both arrays. A user-only

- command (`disable-model-invocation: true`) never participates in routing and stays out of any

- manifest - that gap is deliberate.

+ Source of four independently installable Claude Code plugins (`superui`, `superbiz`, `supercc`, `viber`), co-listed as the `p2p2` marketplace by `.claude-plugin/marketplace.json`; the artifacts are markdown, JSON manifests and bundled scripts.

- ## Where contracts live

+ ## Owner strict rules

+ - Always in English: every CLAUDE.md, script, skill, agent and reference.

+ - Every plugin script MUST work on Windows (Git Bash) and MacOS.

+ - Do not use `heredoc` - it is unreliable.

+ - Do not use `red` color in agents.

+ - Present state only: every CLAUDE.md, README, help page and `.claude/rules/` file says what holds now, never a change history (what changed, was renamed, replaced or used to hold): git keeps that.

+ - Tokens are a design constraint: every token a skill, agent or reference makes a model read counts against the user's Claude Code usage limits (5-hour and weekly), and an agent holding too many instructions at once drifts. Prefer the design that makes a model read and re-read less.

- This file is orientation only. A skill's authoritative contract is its own body

- (`# Input contract` / `# Output format`); an agent's is its own file; hook contracts live in

- `viber/hooks/hooks.json` and the header comments of `viber/hooks/scripts/*.sh`.

+ ## Commands

- ## When editing

+ - Whole test suite (both tiers, as CI runs it): `CI=true node --test --test-concurrency=12 "tests/**/*.test.ts"`

+ - Single test file: `node --test tests/viber/config.test.ts`

+ - Fast (unit tier only): `node --test "tests/**/*.unit.test.ts"`

- - **No source attribution.** Never add a "Sources" section, never name where knowledge came from

- (upstream repos, skills, courses, authors) - anywhere: skills, references, agents, CLAUDE.md,

- reports, chat answers.

- - **Catalog/install layer** (`.claude-plugin/marketplace.json`, root `README.md`): keep changes

- minimal and structural. READMEs are for humans: short, usage only, no implementation detail.

- - **Plugin internals**: paths in each `plugin.json` are plugin-root-relative; hook commands and

- bundled-script calls use `${CLAUDE_PLUGIN_ROOT}` (or `${CLAUDE_SKILL_DIR}` for a skill's own

- files).

+ ## Test layers

- ## Memory Layer

+ - `*.unit.test.ts`: unit tier, the only one a developer machine runs.

+ - Every other `*.test.ts` under `tests/`: integration tier, run in CI only.

- **Before working on an area, read its node first.**

+ ## Traps

- | Node | Read when working on |

- |---|---|

- | `CLAUDE.md` | anything repo-wide - catalog, release, CI, cross-plugin invariants |

- | `superbiz/CLAUDE.md` | `idea-validator` - the side-project viability workflow and its report |

- | `supercc/CLAUDE.md` | `skill-designer` (authoring and linting skills and agents), `model-prompting` |

- | `supercc/skills/CLAUDE.md` | the files of both supercc skills |

- | `superui/CLAUDE.md` | the `pro-designer` skill (design/frontend advisory, contrast check) |

- | `superui/skills/CLAUDE.md` | the `pro-designer` skill files and its scripts |

- | `tests/CLAUDE.md` | running tests (which suite a change reaches), any `*.test.ts` under `tests/` |

- | `tests/harness/CLAUDE.md` | the shared test helpers |

- | `tests/superui/CLAUDE.md` | superui's test suite |

- | `tests/viber/CLAUDE.md` | viber's test suite |

- | `viber/CLAUDE.md` | anything viber - the run directory and its archive, config switches, the plan gate |

- | `viber/agents/CLAUDE.md` | viber's twenty-three agents, the five `code-auditor` sweep agents included |

- | `viber/hooks/CLAUDE.md` | viber's hooks - the `plan-gate.sh`, `plan-hints.sh` and `kill-guard.sh` contracts, the `register.tsx` module |

- | `viber/references/CLAUDE.md` | viber's shared references |

- | `viber/scripts/CLAUDE.md` | viber's plugin-level scripts |

- | `viber/skills/CLAUDE.md` | viber's seventeen skills and their bundled scripts, `code-auditor` included |

+ - Nothing builds and nothing lints: editing markdown or JSON is shipping. There is no `package.json`; `node --test` runs the `.ts` tests directly through Node's type stripping.

+ - Editing a file here does not change the plugins loaded in the current session: they change only after a release is published and reinstalled.

+ - Every plugin script must work on Windows (Git Bash) and macOS: `tests/portability.unit.test.ts` sweeps shebangs, CRLF, exec bits and bash-only syntax in `#!/bin/sh` scripts.

+ - `docs/archive/superdev/` is a retired plugin kept for reference: not listed, not released, not tested.