# Plugin Authoring Rules Any policy change in one listed instruction file must trigger a relevance review of every other listed file before completion. Synchronize applicable shared policy in either direction; preserve intentional agent-specific differences and record when no counterpart change is needed. Plugins under `plugins/`. See `README.md` for user-facing detail. Sections below with a "Full ... : `AUTHORING.md` §X" pointer have narrow-trigger detail (worked checklists, mechanism rationale, precedent, catalogues) in `plugins/AUTHORING.md`, same directory — load on demand, not needed for routine edits. ## Markdown Annotation Convention In `.md` plugin files, prose annotations, notes, and load directives use `>` blockquotes. Use `#` only for real Markdown headings and, inside fenced `bash`/`python` blocks, code comments — never as a fake prose comment or load directive, since that changes heading hierarchy. ``` > loads: modes/resume.md ✓ # loads: modes/resume.md ✗ (H1) ``` ## Markdown No-Wrap Never hard-wrap prose in any Markdown file — one physical line per prose paragraph; preserve breaks in headings/lists/tables/blockquotes/links/`

`/fenced code. Edit only the intended prose, never a whole-file reflow. **Code block comments**: procedural code (steps an agent/skill executes) — comments explain WHY only (non-obvious constraint, workaround, incident ref, safety rationale), never WHAT/HOW; remove self-documenting comments. Example/pattern code (illustrates a pattern, not executed directly) — comments may also document expected output, motivation, or when to apply. Self-documenting-comment examples: `AUTHORING.md` §Markdown No-Wrap. ## GitHub Reference Scoping — `#N` and `@name` `#N` bare in prose = GitHub issue/PR/discussion number only; `@name` bare in prose = a real GitHub username mention only — both are live link/notify tokens once text lands in a GH comment, PR body, issue, or commit message. Never use bare `#N` for local ordinals (list items, step indices, ranks, internal check IDs) or bare `@word` for non-GitHub tokens (decorators, role handles) — use plain numbers/words instead, or backticks to render as code; backticks are for code-shaped tokens only, never to defang a real person's handle. `#N` is same-repo only (cross-repo needs the full URL, never `#N` or `owner/repo#N`); `@name` needs certainty of ping intent — drop the `@` if uncertain, except release-note/CHANGELOG contributor credit, which is deliberate ping intent and stays live. Full forbidden/OK catalogue: `AUTHORING.md` §GitHub Reference Scoping. ## Writing Style — Compression Tiers Three compression tiers by reader: user-facing docs = verbose (full sentences, rationale); reports/human-read output = normal caveman (drop filler, keep clarity); agent source/handover files/inter-agent prose = ultra caveman (max compression, fragments OK). Code, commands, file:line refs, JSON keys/envelopes are always verbatim, never compressed. Full tier table + unsure-rule: `AUTHORING.md` §Writing Style — Compression Tiers. **Comments inside `.md` code blocks are prose, not code — ultra caveman.** The verbatim rule above covers the *code*; a `#` comment beside it is agent-source prose and compresses like any other. It is also re-sent into context on every invocation of that skill, so verbosity there is a recurring cost. One to two lines, fragments, no articles or hedging. **Strip dates, audit/basket names and back-references** ("2026-08 audit (…)", "already computed above") — git history holds provenance. Keep the measured fact, the mechanism, and any deliberate exclusion with its reason. - **Never remove or reword `# timeout: N`** — parsed by the harness to set the Bash tool timeout; it is functional, not documentation. Same for `# tmpdir-exempt:`, `# noqa:`, `# shellcheck`. - **Compress wording, never content**, for any comment encoding a constraint, a why-not, or a bug that was fixed — those comments are why the bug stays fixed. Losing one silently re-opens it. - **`.py` files are exempt**: Python docstrings and comments stay plain and extensive. They serve maintainers, and cost nothing at skill-load time. Worked before/after example: `AUTHORING.md` §Comment Compression. ## Code Density — Bash/Code Blocks Balance compression against readability in inline bash/code blocks — don't trade one for the other, tune both. Readability is carried by **variable names**, not by extra blank lines, comments, or nesting — `MATCH_REPORT`/`GATE_LINE` need no surrounding whitespace to stay legible; a cryptic name does. Compression is validated by **tokens actually used** (`$(( $(wc -c < file) / 4 ))`, per §Length Unit Convention), not by how short a snippet looks — cutting a line that adds no information (a blank separator, a nested nothing block, a nested loop a single `grep`/pipeline replaces) lowers the real number; renaming a variable to something shorter but vaguer does not, it just moves the cost onto whoever reads it next. - Prefer an early-exit guard (`[ -n "$X" ] || exit 0`) over wrapping the rest of the block in `if`. - Collapse a loop-with-break searching for one match into a single `grep`/`awk`/pipeline when the semantics are identical (mind edge cases — e.g. a glob expanding to zero files feeding a filter with no explicit input turns into a stdin hang). - Drop blank lines between statements that read as one step; keep one where it marks a genuine phase change. - Terse code never overrides correctness — a safety check (fail-closed on an unverifiable value) stays even if it costs a line. ## Length Unit Convention All size/length limits: **tokens primary, lines secondary** — format `N tokens (~M lines)` (e.g. `10K tokens (~500 lines)`); never lines-only or chars-only as sole unit. Token estimate: `$(( $(wc -c < file) / 4 ))`. Applies to per-file limits, per-turn budgets, envelope caps, consolidator thresholds. Rationale + full apply-list: `AUTHORING.md` §Length Unit Convention. ## File Layout - `.claude-plugin/plugin.json` — version + metadata; `agents/`, `skills/`, `README.md`, `CLAUDE.md` (optional); `rules/`, `hooks/` — foundry only (exception: `bridge_cc-codex/rules/` = packaged contract docs pinned by its tests, not Claude-loaded rules) - `bin/` — standalone executables (`.py`, ≥3.10 — never `.sh`, see §Installability), auto-added to Bash `PATH`, invoked via `python "${CLAUDE_PLUGIN_ROOT}/bin/