ContextPillar

A VS Code extension that brings structure, hierarchy, and traceability to AI context documents — rules, skills, agent instructions, and specs — used in agentic AI IDEs like Cursor and Windsurf.

The Problem

Developers using agentic AI IDEs maintain a growing set of markdown-based instruction documents (.cursor/rules/, SKILL.md, AGENTS.md, openspec/). These are flat files with no hierarchy, no cross-referencing, and no type system. This causes:

• Duplication — the same instruction copy-pasted into multiple files
• Conflicts — contradictory instructions with no visibility
• Low confidence — no way to verify the AI has the right context before starting a task

The Solution

ContextPillar introduces a single source of truth for reusable instructions (called statements) and lets all other documents link to them rather than duplicate them. The plugin indexes all documents, builds a graph of links, detects conflicts, and provides a pre-flight checker before AI tasks.

Getting Started

1. Create a statements directory

your-repo/
└── statements/
    ├── no-raw-sql.md
    └── async-await.md

2. Add frontmatter to statement files

---
id: stmt-no-raw-sql
type: statement
title: No Raw SQL
tags: [database, sql]
---
Never write raw SQL queries. Always use the ORM layer.

3. Link statements from consumer documents

Add frontmatter to your .cursor/rules/*.md, SKILL.md, or AGENTS.md:

---
type: cursor-rule
title: Database Rules
includes:
  - stmt-no-raw-sql
  - stmt-async-await
---
# Database Rules
...

Frontmatter Schema

Statement file (statements/*.md or .mdlink/statements/*.md)

Consumer file (rules, skills, agents, specs)

Document Types

Features

Document Navigator

Opens in the Activity Bar. Shows all indexed documents grouped by type, with includes links and back-references visible as children. Click any item to open the file.

Conflict & Duplication Detection

ContextPillar automatically detects:

• Duplication — body text substantially identical to a statement body (warns to link instead)
• Inline conflict — a consumer's body contradicts one of its linked statements
• Cross-document conflict — two consumers include mutually contradictory statements
• Layer conflict — a local statement contradicts a workspace-level statement

Issues appear in the VS Code Problems panel and as inline diagnostics.

Pre-flight Checker

Run ContextPillar: Open Pre-flight Checker from the Command Palette before starting an AI task. Select the document types that will be active, and ContextPillar shows whether all statements are reachable and flags any active conflicts.

Multi-Root Workspaces

In a workspace with multiple repos, place shared (authoritative) statements in:

workspace/
└── .mdlink/
    └── statements/
        └── shared-statement.md

Workspace-level statements take precedence over repo-local ones. Conflicts between layers are flagged as errors.

Configuration

Create .mdlink/config.yaml at the workspace root or per-repo root:

statements_dir: statements   # default: "statements"

See .mdlink/config.yaml in this repository for a full example.

Commands