git:20260814.b9c6b5a to git:20260821.c3e8d1d

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

-

- Apply these rules to every file under `plugins/`; `plugins/CLAUDE.md` remains the full authoring reference, and this file is the Codex-facing distillation.

- Root `AGENTS.md` already applies here and is not restated: edit scope, core principles, multi-OS executables, benchmark isolation, focused delegation, Markdown no-wrap, and the test/lint workflow. This file adds only what is specific to authoring plugins.

- In plugin Markdown files, write prose annotations, notes, and load directives as `>` blockquotes. Use `#` for intentional Markdown headings and, inside fenced `bash` or `python` blocks, code comments; never use `#` as a fake prose comment or load directive because plain-text `#` changes heading hierarchy.

-

- Comments in procedural code explain only WHY: non-obvious constraints, workarounds, incidents, or safety rationale. Comments in example or pattern code may also explain expected output, motivation, or when to apply the pattern.

- Every file must work after `claude plugin install <name>@borda-ai-rig`; assume only the installed plugin path, never the source tree. Do not hardcode sibling-plugin paths, `plugins/<name>/` directories, or absolute user or temporary paths; use `~/`, `$(git rev-parse --show-toplevel)`, or `$CLAUDE_PLUGIN_ROOT` as appropriate.

-

- Use a bare `plugins/` path only as the final fallback after resolving the installed cache path. A skill that starts background agents must provide the sentinel, five-minute polling, and fifteen-minute cutoff required by the shared agent-spawn protocol.

- Treat each plugin as independently installable: never use local or relative paths to another plugin, and use plugin-prefixed agent or skill names such as `foundry:sw-engineer`. An agent `subagent_type` must match its filename.

-

- Cross-plugin calls and prose references must check whether the dependency plugin is available, degrade gracefully when it is absent, and annotate prose command references with (requires `<plugin>` plugin). Never propose a prerequisite-plugin or global-registration dependency as the resilience mechanism.

- Each file added under a skill's `modes/`, `templates/`, or `_shared/` must either have its basename as a literal string in a consumer Markdown file or carry a `<!-- file: <basename> — consumers: ... -->` header. Add the consumer reference before creating the shared file.

-

- Manifested shared files are byte-identical copies: edit the canonical file, run `plugins/cc_foundry/bin/propagate_shared.py --apply`, and verify with its default `--check` mode. Keep resilience code in the plugin whose users need the fallback, not in the plugin that may be absent.

-

- Every plugin resolves its **own** `skills/_shared` through its own resolver and reads only files it ships itself. Never use `$HOME/.claude/skills/_shared/...` or a bare `.claude/skills/_shared/...` path — `/foundry:setup` symlinks only `rules/*.md` and `TEAM_PROTOCOL.md`, and purges any leftover `~/.claude/skills/` link, because a directory carrying `SKILL.md` there registers as a user-level skill and shadows Claude Code's bundled skill of the same name. Never read another plugin's `_shared` or `bin/` either; duplicate the content into each plugin and add a `propagate_shared.py` MANIFEST entry instead of borrowing. Audit Check 27 enforces both halves.

- Any edit to `agents/`, `skills/`, `rules/`, or `hooks/` requires the owning plugin README to be updated before completion. Synchronize tables, descriptions, triggers, scope, NOT-for boundaries, hook behavior, user-facing arguments, invocation syntax, cross-plugin references, model-tier lines, relationship tiering, and relevant curator antipatterns; propagate changed interfaces to every cross-plugin README that mentions them.

- Python is the default `bin/` language and requires Python 3.10+, type hints, a module docstring, an `if __name__ == "__main__"` guard, and ruff-format at 120 columns. Pure functions use doctests; code that performs I/O, subprocesses, environment reads, or argv parsing uses pytest coverage in the adjacent `tests/` directory.

-

- Use `bin/` only for deterministic transforms such as argument parsing, path resolution, or one-value computation. Keep decision flow, branching prompts, and agent dispatch in SKILL.md prose. Use Bash only for install-path resolution, safe `$ARGUMENTS` parsing, or simple `find | sort | head` pipelines without business logic; inline SKILL.md Python is limited to cases requiring JSON parsing, multiline string manipulation, or numeric computation.

- Every commit touching a plugin's non-test file must apply exactly one SemVer bump to that plugin from its HEAD baseline. A commit changing only files under `plugins/<name>/tests/` needs no bump; each touched plugin is evaluated independently, and one commit applies at most one bump per plugin.

-

- Before changing a version, run `git diff HEAD --name-only -- plugins/<name>/` and stop with no bump when every changed path is under `tests/`. Otherwise read the baseline with `git show HEAD:plugins/<name>/.claude-plugin/plugin.json | grep version`, read the on-disk version with `grep version plugins/<name>/.claude-plugin/plugin.json`, and stop if disk already differs from HEAD. Classify patch (`Y`) for a fix, wording change, refactor, cleanup, or restoration of intended behavior; classify minor (`X`) for a new capability, agent, skill, or designed behavior, resetting patch to zero. Test-only changes need no bump. Calculate from HEAD and write exactly that single bump; never increment from a previously bumped on-disk value.

-

- After calculating the bump, update every shipped runtime manifest, including `.codex-plugin/plugin.json` when present, so it shares the bumped version with `.claude-plugin/plugin.json`; update CHANGELOG or release metadata whenever the plugin's convention requires it.

- Before editing policy, inspect the document-level `policy-sibling-sync` contract and any section-specific `policy-sibling` marker. Review every listed instruction sibling even when no synchronized edit is ultimately needed, and update applicable shared policy in either direction. Before completion, verify the intended README and cross-references, run `plugins/cc_foundry/bin/propagate_shared.py --check` when shared files are involved, run `check_orphaned_bin.py` when `bin/` files are involved, and run the relevant tests or lint checks. Run `git diff --check` on every owned file and confirm added prose paragraphs are not hard-wrapped.