IronClaw Guidance & Skill Maintenance

Every rule below counters a rot pattern this repo's guidance is prone to. Guidance is code: it has callers (agents), it breaks silently, and it needs the same review discipline.

The two skill systems — never conflate them

• .claude/skills/ + .claude/commands/ + .claude/rules/ → developer-facing (Claude Code; Codex reads only the AGENTS.md hierarchy).
• Top-level skills/ → product runtime skills, compiled into the shipping ironclaw binary (crates/extensions/ironclaw_extension_host/build.rs → crates/extensions/ironclaw_extension_host/src/bundled_skills.rs). Editing skills/ changes what users' agents do, not your workflow. Treat it as production code: test-first, product review.

Authoring rules (each one earned)

1. Recipes over maps. Encode grep/verify procedures that re-derive facts, not hardcoded file:function maps. When someone asks for a "key files list" in guidance, do not ship a bare list — ship (a) the grep recipes that regenerate it, (b) at most a handful of stable anchor paths, and (c) beside every listed path, the one-line command that re-verifies it. A list without its regeneration recipe will drift.
   • Corollary: the v1-only enclave that older guidance warns about — ironclaw_engine, ironclaw_tui, ironclaw_gateway, ironclaw_oauth — no longer exists. Never re-introduce those names into a flow/architecture map, and treat any doc that still lists them as drift to fix (check ironclaw-reborn-orientation when unsure).
2. Verify every concrete reference at write time — and make it re-verifiable. Branches die silently; prefer in-tree worked examples over branch/PR refs. For each cited path/symbol, keep a one-line grep a maintainer can re-run.
3. No universal claims without a count. Avoid absolute docs coverage claims. Write "most; fall back to Cargo.toml + lib.rs" or generate the list.
4. Triggers live in frontmatter description, nowhere else. The runtime surfaces only frontmatter for selection; a "when to use" buried in the body is invisible. Description = triggering conditions only — never a workflow summary (agents will follow the summary and skip the body).
5. Never claim enforcement that doesn't exist. Before writing "enforced by X", run X. If you add a check to scripts/pre-commit-safety.sh, add its self-test — and know there are two hook install paths (.githooks/ vs scripts/dev-setup.sh symlink); a check is only real if both run it.
6. After any extraction/move/rename, grep the guidance layer for old paths in the same PR: .claude/, AGENTS.md, CLAUDE.md, crates/AGENTS.md, docs/internal/reborn/contracts/, skill bodies.
7. Runtime-skill spec must track the parser. crates/domains/ironclaw_skills/src/types.rs supports requires.config, requires.skills, activation.setup_marker, and silently truncates >20 keywords / >5 patterns (enforce_limits). If you use or change parser behavior, update .claude/rules/skills.md in the same PR.
8. Codex parity check. Codex cannot load Claude skills; it reads AGENTS.md. When a skill carries a rule Codex must also follow, the AGENTS.md hierarchy needs the pointer with enough inline substance ("read .claude/skills/<name>/SKILL.md" works — skills are plain markdown).
9. Test skills like code (RED-GREEN). Before shipping a new/edited skill: run the tempting scenario with a fresh subagent without the change (does the failure actually occur?), then with it (is it caught?). A skill nobody failed without is dead weight; a skill you didn't re-test may not bind. Record trap results in the skill PR.
10. crates/AGENTS.md map hygiene: when adding a crate, add its row. Absence from the routing map = agents misrouted.
11. Two evidence layers, two lifecycles. Skill references/ files are the living teaching copies (worked examples, exemplar tests) — update them as code evolves. Audit/postmortem snapshots are immutable — never edit one; cite one only as dated provenance, and never make a skill's operative content depend on a document that isn't versioned alongside it.

Definition of done for a guidance PR

• Every cited path/symbol/branch verified against HEAD (grep output in PR description)
• Frontmatter description = triggers only, third person
• Enforcement claims executed, not assumed
• Fresh-agent trap test run for behavior-changing edits (result noted)
• Old-path grep clean after moves
• Runtime skills/ untouched unless the product change was intended