skill-based-architecture AGENTS.md

AGENTS.md

The skill-based-architecture meta-skill — a router-pattern scaffold for restructuring scattered project rules into a maintainable skill directory, with cross-tool thin shells, Task Closure Protocol, and self-evolving workflows.

Formal docs live at repo root (self-hosting layout). Read SKILL.md first — it is the router.

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.

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, and 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)