skill-based-architecture

# CLAUDE.md

This repo is the **skill-based-architecture** meta-skill itself. Formal docs live at the repo root (self-hosting layout, see [references/layout.md](references/layout.md)). Read [SKILL.md](SKILL.md) first — it is the router.

<!-- SELF_ROUTING_BLOCK_START -->
## Quick Routing (survives context truncation)

Task routes live in `references/self-hosting-routing.yaml`.

For every new task:
1. Read `SKILL.md`.
2. Read `references/self-hosting-routing.yaml`.
3. Match exactly one route by `labels`, `trigger_examples`, and task intent; if none matches, use `other`.
4. Follow only that route's `workflow`; the route does not preload project knowledge.
5. Let the workflow inspect the smallest evidence that can decide the next action, then pull later knowledge only when that unresolved decision requires it.
<!-- SELF_ROUTING_BLOCK_END -->

## Auto-Triggers

- **New task in same session** → always re-match the route above. After a route change, read the new workflow; after compaction, recover only the current workflow and decision-relevant evidence. Only one clear read-only or fixed-contract maintenance action/check with no new desired behavior executes directly. A request that adds or changes user-visible behavior, a business flow/state, or an external contract first reaches `requirement-ready`; if meaning is incomplete, return current understanding, real risk/conflict, and the minimum normative question without an implementation Plan. Then establish a Task Anchor, prove the current owner and Current -> Target until `implementation-ready`, and only afterward derive a concise harness-native Plan before mutation. Present only useful alignment, do not repeat visible steps in chat, write user-facing messages in the user's natural language, and explain any internal term in one plain sentence where it appears; run the compact Anchor Checkpoint before each main step. This is Session recitation, not planning-file persistence. Can't tell if context compacted? Re-read the current workflow.
- Before any requested commit/push/MR/deploy/publish delivery, enter `templates/skill/workflows/task-closure.md`; `Ready for Delivery` is not completion, and Closure remains open until the requested artifact is verified.
- Closure checks fire by **blast-radius bucket** (path-based classification of files changed):
  - **A** (entry shells / SKILL.md / routing yaml / scripts / `*.tpl`) → full AAR + smoke-test + path-integrity gates
  - **B** (template rules/workflows non-example, references linked from SKILL.md, `workflows/full-migration.md`) → lightweight AAR only
  - **C** (README, examples, docs, UPSTREAM-CHANGES, references not linked from SKILL.md) → skip closure entirely
  - Multiple files in one task → take the max bucket. Path not in any list → default B. Trivial edit (typo / whitespace) in an A-bucket file still = full closure (bucket measures *what could break*, not *what changed*).
  - Pure Q&A / code explanation / read-only investigation / advice with no file changes → exempt; no AAR, no smoke-test.
  - Full path lists + canonical bucket rules: `references/protocols.md` § Task Closure Protocol.
- When adding to `templates/` → apply the "would two real projects disagree?" admission test (`templates/ANTI-TEMPLATES.md`)

## Red Flags — STOP

- "Just this once I'll skip the AAR" → stop. See `templates/skill/workflows/task-closure.md` § Rationalizations to Reject.
- "I'll inline this in SKILL.md instead of linking a reference" → stop. SKILL.md stays within dual budget (description ≤ 25 + body ≤ 90 lines); content goes to `references/` or `templates/`.
- "Let me pre-fill a gotchas example so the template feels complete" → stop. `templates/ANTI-TEMPLATES.md` forbids project-specific content in templates.