13 added, 0 removed. Audit A to A.
# Spellbook Agent Contract
Spellbook is a cross-runtime skill library, not a prompt dump. Keep this file
short: path-scoped `AGENTS.md` files carry directory-specific rules.
## Routing
- Search before creating a new skill, script, registry entry, or support file.
Prefer `rg`, `rg --files`, and `python3 scripts/validate_skills.py search`.
- For skill authoring or refactors, read `docs/skill-format-policy.md`,
`docs/skill-quality-playbook.md`, and
`docs/spellbook-operating-contract.md` before editing.
- For generated registry or install metadata, change the source of truth and
regenerate; do not hand-edit generated outputs.
- For high-context files such as `AGENTS.md`, `CLAUDE.md`, and skill
`SKILL.md` files, keep changes intentional, scoped, and visible in the final
summary.
## Scope Rules
- Do exactly the requested change. Do not add opportunistic migrations,
rewrites, or broad cleanup.
- Prefer existing scripts, validators, parsers, and local conventions over new
helper code.
- Do not invent metadata fields, registry fields, runtime targets, install
behavior, or API surfaces. No data means blank or blocked.
- Do not silently swallow validation errors. Fix the root cause or report the
blocker.
- Never commit secrets, tokens, private keys, or credential material.
+ ## Threads Long-Run Guardrails
+
+ - Generic context-budget and output-firewall policy for Codex subagent
+ orchestration belongs in `skills/threads/`; repository-specific queue policy
+ belongs in the consumer workflow pack.
+ - For long queues or multi-lane runs, keep parent context thin: raw logs, broad
+ searches, CI output, and session JSONL must go to artifacts or stay out of
+ parent context.
+ - `threads` run-log schema, `SKILL.md`, and `references/run-log.md` must stay in
+ sync when adding fields, failure codes, or lane contracts.
+ - Installed copies under `~/.agents/skills/threads` and `~/.spellbook/skills/threads`
+ should be synced and hash-checked when local runtime behavior matters.
+
## Validation
- Skill, registry, install, or README count changes:
`python3 scripts/validate_skills.py --check`.
- Material skill content changes:
`python3 scripts/audit_skill_quality.py <skill-name>`.
- Registry regeneration:
`python3 scripts/validate_skills.py --write` followed by
`python3 scripts/validate_skills.py --check`.
- Python script changes: run targeted tests when present; otherwise run
`python3 -m py_compile scripts/*.py` plus the relevant workflow command.
- If verification cannot run in the current environment, report the missing
precondition and the exact command to run later.
## Generated Files
These files are generated or derived and should not be manually edited unless
the generator itself is being repaired:
- `registry/skills.json`
- `registry/tags.json`
- `docs/skill-registry.md`
## Decision Defaults
| Situation | Default |
|---|---|
| New installable skill | Use `skills/<name>/SKILL.md`. |
| Small existing file skill | Keep it as `skills/<name>.SKILL.md` unless it needs support files. |
| Long examples, templates, or references | Move them under the skill's support directories and link from `SKILL.md`. |
| Repeated manual command | Prefer adding or updating a script after the workflow is proven manually. |
| Destructive, remote production, publishing, billing, or credential action | Ask before acting unless the user already gave explicit approval. |
## VibeGuard Summary
- L1: Search first before creating anything new.
- L2: Use snake_case internally; preserve camelCase only at API boundaries.
- L3: Do not use `Any`-style public APIs or silent exception swallowing.
- L4: Do not invent undeclared data, fields, APIs, or fallback output.
- L5: Keep to the requested scope.
- L6: Route work as execute directly, plan first, or clarify first based on
risk and missing inputs.
- L7: Do not submit keys, force-push, or hide high-context changes.