Enforcing AI Agent Adherence Through Single-Source Architecture in CrystaCode projects
AI agents require strict directory structures to execute project rules without logic divergence. Rule duplication causes execution failure. Establish a single source of truth. Define each rule in exactly one location. Secondary files function exclusively as routing parameters.
AGENTS.md # Primary entry file
CLAUDE.md # Pointer to AGENTS.md
agents/
rules/
productA.md # Component directives
productB.md
skills/
styling-guidelines-a/SKILL.md
styling-guidelines-b/SKILL.md
hooks/
styling-guard.ps1 # Interceptor execution script
docs/
Conventions/
ProductA/styling-guidelines.md # Absolute rule text
ProductB/styling-guidelines.md
.claude/
settings.json # Claude hook directive
skills/*/SKILL.md # Auto-generated artifacts
.github/
instructions/*.instructions.md # GitHub agent pointers
hooks/preToolUse.json # GitHub hook directive
AGENTS.md: The mandatory initialization file. Contains routing matrices. Outlines file extension triggers and maps them to specific requisite documents.
CLAUDE.md: Contains a single pointer instructing the parser to evaluate AGENTS.md
.
.github/instructions/: Pointers redirecting GitHub Copilot to module-specific rules.
agents/rules/: Isolated procedural steps and checklists mapped to specific project modules. Defers rule definitions to the skills directory.
agents/skills/: Contextual triggers dictating exact pre-conditions for operation. Defers absolute rule text to the docs/
repository.
docs/: The definitive repository. Contains complete technical specifications and rule text. The sole location for rule definitions.
.claude/skills/: Automated mirror of agents/skills
. Manual modification is strictly prohibited.
The styling-guard.ps1
hook enforces compliance by gating execution based on session markers.
Intercept Request:
The script intercepts the AI file modification request pre-execution.
Evaluate Target Parameters:
The file extension is evaluated against target parameters (.scss
, .razor
). Unmatched files bypass interception.
Ascertain Product Association:
The script evaluates the target file path to identify the associated project module.
Query Session Data:
The script checks session data for an existing execution marker corresponding to the file type and module. If present, the AI bypasses interception.
Halt Execution:
If the marker is absent, execution is blocked. The AI receives an explicit directive to parse the required skill documentation.
Write Execution Marker:
The script writes the execution marker to session data. Subsequent modification attempts in the same session proceed without interruption.
Interceptor Implementation Logic
The interception mechanism outputs explicit standard error directives to halt execution when session markers are absent:
if ($category -eq 'scss') {
[Console]::Error.WriteLine(
"MANDATORY styling gate: this is the first .scss edit in this session for the " +
"'$product' product. Invoke the '$skill' skill (canonical rules: $doc), apply its " +
"rules -- $checklist -- then retry this exact edit. $forbidden " +
"This gate fires once per session per product per file category.")
} else {
[Console]::Error.WriteLine(
"MANDATORY component gate: this is the first .razor edit in this session for the " +
"'$product' product. Before this edit: (1) invoke the '$skill' skill (canonical " +
"rules: $doc) for color/typography/component conventions -- use $components. " +
"(2) invoke the 'localize-app-strings' skill -- never hardcode user-facing text, " +
"always route through IStringLocalizer<AppStrings>. Then retry this exact edit. " +
"This gate fires once per session per product per file category.")
}
AGENTS.md
).docs/
) as the single source of truth..claude
, .github
) to pointer artifacts.Enjoy it: CrystaCode