Rule Layers & Trigger Index Architecture (v1.5.3)

Rules are .md files that govern AI Agent behavior — boundaries, priorities, and discipline. Unlike Workflows (execution steps), Rules define constraints the agent must follow.

Three key properties make the system efficient:

1. Layered — Kernel → Workspace → Project
2. Progressive Disclosure — load only when needed, never all at once
3. Trigger Index — lightweight table mapping actions to rule files

🏗️ The Three Rule Layers

┌────────────────────────────────────────────────────┐
│ Layer 1: KERNEL (Immutable)                        │
│ Resources/ai-agents/kernel/invariants.md           │
│ → 11 invariants (I1-I11), read only by audit       │
├────────────────────────────────────────────────────┤
│ Layer 2: GOVERNED RULES (Workspace)                │
│ .agent/rules/*.md                                  │
│ → 10 rules, synced via ./para install/update       │
│ → Apply to ALL projects in workspace               │
├────────────────────────────────────────────────────┤
│ Layer 3: PROJECT RULES (Per-project)               │
│ Projects/<name>/.agent/rules/*.md                  │
│ → Custom rules, supplement (not override)          │
│ → Declared via rules.md trigger index              │
└────────────────────────────────────────────────────┘

Layer 1: Kernel (Immutable)

• File: invariants.md — 11 hard rules, changing one requires an RFC + MAJOR version bump
• Read by: Only /para-audit (full-scan) — the sole workflow allowed to read the full kernel
• Think of it as: The constitution. Everyone follows it, but almost nobody reads the full document daily.

Layer 2: Governed Rules (Workspace)

Synced from catalog.yml by ./para install or ./para update. Apply to all projects in the workspace.

Layer 3: Project Rules (Per-project)

• Location: Projects/<name>/.agent/rules/
• Not synced from repo — user-created via /para-rule add
• Supplement workspace rules, never override them
• Examples: dogfooding-policy, content-accuracy, sync-upstream

🎯 Trigger Index (Two-Tier Progressive Disclosure)

The system uses two index files so the agent knows which rules exist and when to load them — without reading all rule files upfront.

Tier 1: Workspace Rules Index (ALWAYS READ)

File: .agent/rules.md

This lightweight table (~10 lines) is read at the start of every session. The agent memorizes the triggers but does NOT read the actual rule files yet.

| Rule                    | Trigger                                   | File                             |
| :---------------------- | :---------------------------------------- | :------------------------------- |
| Governance              | Touching kernel/, .para/, or system files | rules/governance.md              |
| Hybrid 3-File Integrity | Reading/writing artifacts/tasks/          | rules/hybrid-3-file-integrity.md |
| ...                     | ...                                       | ...                              |

Tier 2: Project Rules Index (CONDITIONAL)

File: Projects/<name>/.agent/rules.md

Only read if the project declares has_rules: true in project.md.

| Rule              | Trigger                                   | File                 |
| :---------------- | :---------------------------------------- | :------------------- |
| Dogfooding Policy | Editing repo/, syncing files to workspace | dogfooding-policy.md |
| Content Accuracy  | Writing documentation content             | content-accuracy.md  |

[!IMPORTANT] The agent reads the index (trigger table), not the rules files. Rule files are loaded on-demand when an action matches a trigger during the session. This is key to token efficiency.

🔄 Loading Flow

Here’s how rules are loaded during a typical session:

/open
  ↓
Step 2.5a: Read .agent/rules.md (workspace index) — ALWAYS
  → Memorize 10 triggers (do NOT read rule files)
  ↓
Step 2.5b: has_rules: true?
  → YES → Read Projects/<name>/.agent/rules.md (project index)
  → NO  → Skip (only project rules skipped, workspace rules already loaded)
  ↓
Coding session: agent about to edit repo/
  → Match: "Editing repo/" → load dogfooding-policy.md → comply
  ↓
Agent receives ad-hoc request "remove download button"
  → Match: "ad-hoc requests" → load hybrid-3-file-integrity.md → log hot lane first

The has_rules Gate

# In project.md
has_rules: true # Gate for /open Step 2.5b (project rules only)

• true → /open reads the project rules index
• false or missing → skip project rules (workspace rules still loaded)
• /para-audit update Step 5 checks consistency between has_rules and actual files

📊 Workflow Coverage

📚 References

• Rule: Context Rules Rule #4 — Two-Tier Progressive Disclosure protocol
• Workflow: /open Step 2.5a/2.5b, /plan Step 2.7 D1/D2
• Kernel: Invariant I2 (workspace-level rules)

→ Explore Workflow /open — Rules Loading → Explore Workflow /para-rule — Manage Project Rules → Learn: Hybrid 3-File Architecture → Learn: Defense-in-Depth — Context Recovery