guidelines-ingestion

Guidelines Ingestion

Overview

Load coding guidelines from up to 3 sources and merge them deterministically using section-level replacement. The result is a single, merged guidelines document that the agent follows during coding.

Three-Layer Merge

Layer 3 (highest priority): Per-invocation overrides
         ↓ overrides
Layer 2: Team's custom guidelines file
         ↓ overrides
Layer 1 (lowest priority): Plugin shipped defaults

Merge Algorithm (Deterministic — No LLM Judgment)

Guidelines are organized by ## heading sections.

1. Start with Layer 1 — read the language module's defaults/coding-guidelines.md
2. Apply Layer 2 — read the team's custom guidelines file (path from config):
   • For each ## section in the custom file:
     • If a section with the same heading exists in Layer 1 → fully replace Layer 1's section with the custom section
     • If the section heading is new (not in Layer 1) → append it to the merged result
   • Sections in Layer 1 that have no matching heading in the custom file → keep as-is
3. Apply Layer 3 — inject per-invocation instructions as ## Overrides section at the top:
   • This section takes precedence over all other sections
   • If the user said "use repository pattern, no static methods" → add as ## Overrides content

Process

1. Identify the guidelines file path:

   • From config-resolver output: languages.<lang>.guidelines path
   • If path is relative, resolve from workspace root

2. Read Layer 1 (plugin defaults):

   • Read defaults/coding-guidelines.md from the active language module
   • Parse into sections by ## headings

3. Read Layer 2 (team custom guidelines):

   • Read the file at the resolved guidelines path
   • If file does not exist and mandatoryGuidelines is true → config-resolver already blocked
   • If file does not exist and mandatoryGuidelines is false → skip Layer 2, use Layer 1 only
   • Parse into sections by ## headings

4. Merge Layer 1 + Layer 2:

   • Apply section-level replacement as described above

5. Add Layer 3 (per-invocation overrides):

   • If user prompt contains explicit coding instructions, prepend as ## Overrides

6. Validate merged result:

   • Check for contradictions within the same section (e.g., "use mocks" and "never use mocks")
   • If contradictions found → surface a warning listing the conflicting rules, but proceed (higher layer wins)

7. Inject into agent context:

   • The merged guidelines become part of the agent's system context for the session
   • All subsequent coding, review, and testing actions must follow these guidelines

Output

State the merged guidelines summary:

• Which sections came from defaults
• Which sections were overridden by team custom
• Which overrides were injected from the prompt
• Any warnings about contradictions