Centralized Rule Structures

#claude #githubcopilot #agents #ai

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.

System Architecture

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

Component Specifications

Primary Node

AGENTS.md: The mandatory initialization file. Contains routing matrices. Outlines file extension triggers and maps them to specific requisite documents.

Redirection Nodes

CLAUDE.md: Contains a single pointer instructing the parser to evaluate AGENTS.md.
.github/instructions/: Pointers redirecting GitHub Copilot to module-specific rules.

Operational Directives

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.

Absolute Documentation

docs/: The definitive repository. Contains complete technical specifications and rule text. The sole location for rule definitions.

Automated Mirrors

.claude/skills/: Automated mirror of agents/skills. Manual modification is strictly prohibited.

Interceptor Script Protocol

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:

Deployment Checklist

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.")
}

[ ] Initialize root entry node (AGENTS.md).
[ ] Define routing matrix mapping file extensions to required rules.
[ ] Isolate module-specific rules into distinct files.
[ ] Establish definitive rule repository (docs/) as the single source of truth.
[ ] Define skill triggers with explicit operational pre-conditions.
[ ] Deploy interceptor script to halt execution and mandate rule review.
[ ] Restrict tool-specific directories (.claude, .github) to pointer artifacts.