guardrail

guardrail

<guardrail_skill>

A guardrail doc carries rules, and a rule holds whether or not the code satisfies it yet. The doc states what must be true of this project, written as a general rule rather than a report on the current tree. Code that falls short of a rule is unmet work, never evidence that the rule is wrong, and softening a rule to match the code is the move the doc exists to prevent — the misreading an agent that treats a doc as a description of the present will make the moment the code disagrees with it. A rule becomes true along three paths: work filed and done to close the gap deliberately; new code written to the rule from the start; and touch-it-and-fix-it — existing code brought to the rule whenever ordinary work touches or rewrites it. The third path carries most of the distance, which is why a rule needs no migration plan attached to be worth stating.

The system is universal. It serves a single software system, a knowledge or content repository, a meta-repository whose product is components or documents, and a mixed multi-project layout alike, in any language and any stack. This skill carries only the general knowledge — the what and the how that hold everywhere; every actual guardrail doc is tailored to its repository, and a doc type that fits one repo nature can be a bad fit for another.

<when_to_activate> Activate this skill when the user:

• Asks what guardrail documents are, which ones exist or could exist, or how the guardrail system works.
• Asks which guardrail docs their repository should adopt, or asks for a suggestion, recommendation, or assessment of guardrail coverage.
• Asks to set up, bootstrap, draft, or create a CHARTER.md, ARCHITECTURE.md, TESTING.md, or SECURITY.md — or a guardrail layer as a whole.
• Asks how guardrail docs relate to or rank against each other or against the harness rule files (CLAUDE.md / AGENTS.md / GEMINI.md and equivalents).
• Asks how a skill, agent, or workflow should consult or enforce a guardrail doc.

Route to guardrail_audit when the user wants the repo's existing guardrail docs audited for contradictions and doc-vs-code divergence. Route to the task family for backlog work; the task skills consume guardrail docs but are not the place that defines them. </when_to_activate>

<doc_set> Four core guardrail types are recognized. Each has a bundled reference (sibling of this SKILL.md) carrying its general template, its universally valid rules, and its tailoring guidance — read the reference before explaining, suggesting, drafting, or assessing a doc of that type:

• CHARTER.md — the falsifiable project-identity contract: core purpose, DOES / DOES NOT domain boundaries, key invariants, intentional constraints. The one doc that stops work rather than informing it. Reference: references/charter.md.
• ARCHITECTURE.md — the descriptive account of how the project is structured and where its structure is deliberately headed: goals, stack, components and their responsibilities, load-bearing design decisions, declared direction. Reference: references/architecture.md.
• TESTING.md — the project's verification methodology: what counts as tested, the discipline verification follows, and how the suite runs. Reference: references/testing.md.
• SECURITY.md — the security constraints that must hold: secrets, trust boundaries, data handling, dependencies, attack surface. Reference: references/security.md.