codebase-context-governor
Audit, partition, budget, and enforce multi-layer codebase context files across coding agents. Eliminates context rot through Three-Layer boundaries, automated CI linters, and dynamic compute tier calibration. Do not use for generic prompt writing.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- codebase-context-governor
- description
- Audit, partition, budget, and enforce multi-layer codebase context files across coding agents. Eliminates context rot through Three-Layer boundaries, automated CI linters, and dynamic compute tier calibration. Do not use for generic prompt writing.
02 资源文件 4
- 参考文档CARD.md3.5 KB
- 参考文档config.default.yaml833 B
- 参考文档references/governance-playbook.md1.2 KB
- 脚本scripts/context_governance_driver.py2.9 KB
03 SKILL.md 正文
Codebase Context Governor: Multi-Agent Context Lifecycle & Budgeting
codebase-context-governor is an authoritative composite meta-skill that orchestrates the governance, partitioning, linting, and synchronization of codebase context files (AGENTS.md, CLAUDE.md, .cursor/rules/) across heterogeneous AI coding agents.
It coordinates four specialized capabilities:
- Multi-Layer Context Architecture & Synchronization (
codebase-context-architect) - Repository Instruction Hygiene & Boundary Enforcement (
agent-instruction-architect) - Enterprise Skill Specification & Progressive Governance (
agent-skills-architect) - 5D Dynamic Compute & Reasoning Tier Assessment (
compute-model-assessor)
See CARD.md for the companion summary card, 5-stage progression matrix, and invariants checklist.
Consult /codebase-context-architect for synchronization engines, /agent-instruction-architect for negative boundary guidelines, and governance-playbook.md for governance playbooks.
The 5-Stage Context Governance Progression
[1. Smell & Budget Audit] ──► [2. Three-Layer Partitioning] ──► [3. SSOT Synchronization]
│
▼
[5. Dynamic Compute Calibration] ◄── [4. Automated CI Linter Enforcement] ◄─────┘
1. Context Rot & Smell Auditing
Conduct a comprehensive scan across all agent context and instruction files in the workspace:
- Smell Diagnostics (Rule 11):
- Identify Lint Leakage: Repetitive compiler/linter error lists that pollute context windows.
- Identify Context Bloat: Instruction files exceeding 150 lines or 4,000 tokens.
- Identify Instruction Contradiction: Divergent commands or architectural patterns across competing tool files.
- Verify Execution Seams:
- Confirm explicit build, test, and lint commands are defined with zero ambiguity.
- Inspect Negative Boundaries:
- Confirm explicit "what NOT to touch" boundaries are present in instruction files.
Completion criterion: Context smell diagnostic scorecard generated with token budget violations and line count hotspots isolated.
2. Three-Layer Context Partitioning
Partition unstructured context into three strictly bounded architectural layers:
- Layer 1: Constitution & Kernel Invariants:
- System identity, core security boundaries, immutable architectural invariants (Rule 1 to Rule 44).
- Layer 2: Project Execution Seams (SSOT):
- Command palettes, test contracts, domain taxonomies, and modular plugin directories.
- Preserved under canonical instruction files (
AGENTS.md).
- Layer 3: Ephemeral Task Context:
- Session trajectories, sub-agent task allocations, and in-flight transaction states.
Completion criterion: Codebase context partitioned across all 3 layers with zero cross-layer bleeding.
3. Single Source of Truth (SSOT) Synchronization
Synchronize derived context files from primary repository manifests:
- Single Source Generation:
- Derive agent tool lists, plugin registries, and CLI schemas from active workspace code rather than manual copy-paste.
- Cross-Agent Export:
- Project shared architectural rules into client-specific locations (
CLAUDE.md,.cursorrules) using deterministic generators.
- Project shared architectural rules into client-specific locations (
- Preserve Custom Overrides:
- Support zero-fork configuration layers (
config.default.yamlvs.agents/skills.config.yaml).
- Support zero-fork configuration layers (
Completion criterion: All agent context files synchronized against SSOT with zero drift detected.
4. Automated CI Linter Enforcement
Embed context validation into continuous integration and pre-commit pipelines:
- Context Linter Execution (Rule 10):
- Execute
harness context lintto assert line counts ($\le 150$ lines for instructions), token limits, and link integrity.
- Execute
- Format & Delimiter Verification:
- Verify frontmatter budgets ($100 \le \text{chars} \le 350$) and ASCII delimiter syntax (Rule 37).
- Git Pre-Commit Seams:
- Block commits that introduce unbudgeted instruction files or malformed YAML configs.
Completion criterion: CI linter passes 100% with zero critical warnings across all repository context files.
5. Dynamic Compute Model Assessment
Evaluate the governed repository state and calibrate optimal reasoning compute budgets:
- 5D Complexity Evaluation (Rule 25):
- Score repository Span, Depth, Concurrency, Rigor, and Domain Heterogeneity.
- Thinking Budget Calibration:
- Route agent sessions to optimal reasoning tiers (High, Medium, Low, Off) calibrated for target foundation models.
- Subprocess Timeout Scaling:
- Dynamically adjust async subprocess runner timeouts to prevent false-positive watchdog terminations during deep refactors.
Completion criterion: Compute tier recommendation and reasoning budget calibrated for current codebase complexity.
The Three Foundational Pillars
1. The Visual Brief Pillar
Every context governance cycle renders an interactive HTML visual brief in %TEMP% displaying layer allocation pie charts, line count distributions, and token budget gauges.
2. The Mandatory Checkpoint Pillar
The agent must never prune, truncate, or rewrite repository instruction files without first presenting implementation_plan.md with RequestFeedback: true and awaiting explicit user confirmation.
3. Explicit Anti-Patterns
Rigid architectural boundaries prevent context bloating, instruction drift, and silent linter bypasses.
Anti-Patterns
- Unbounded Instruction Bloat — Allowing
AGENTS.mdorCLAUDE.mdto exceed 150 lines or contain verbose tutorials. - Lint Leakage Infiltration — Pasting transient linter warnings or error logs directly into persistent agent instruction files.
- Multi-Source Instruction Drift — Maintaining duplicate manual rule sets across different agent files instead of generating from SSOT.
- Static Reasoning Misallocation — Running heavy reasoning models on trivial tasks or starving complex multi-agent audits of compute budget.
- Unchecked Link Rot — Maintaining dead markdown links or invalid symbol anchors in context files.
- Missing Negative Boundaries — Specifying agent permissions without explicit negative constraints ("Do not edit...").
04 同仓库更多 Skills
ui-behavior-primitive-architect
Architect, audit, and verify zero-dependency headless UI behavior primitives, WebMCP agent bridges, WAI-ARIA/SSR/RTL tri-modal checks, and framework expert routing. Do not use for static CSS theme styling or backend database migrations.
trustgraph-ontology-governor
Govern knowledge graphs, SHACL-AF triple policies, OntologyRAG subclass validation, PROV-O dual named graphs, and Laya entropy decision scoring. Do not use for relational SQL queries or generic web scraping.
shim-harness-governor
Govern universal CLI agent loops, 4-tier tool permissions, ancestor-symlink workspace sandboxes, deterministic-first command routing, collision-safe MCP namespacing, and layered skill loading. Do not use for static UI styling or external SQL analytics.
graphiti-zep-memory-governor
Govern bi-temporal knowledge graphs with Graphiti future-edge clamping, MinHash/LSH entity dedup, RRF/MMR reranking, and Zep typed ontologies. Do not use for static SQL joins or generic web crawling.
agora-mcp-workbench-architect
Architect, audit, and orchestrate Agora Workbench MCP servers, loopback sidecars, unified state graphs, gateway/dispatcher connectors, and policy-enforced data lakes. Do not use for static frontend CSS styling or non-MCP desktop GUI automation.
skill-eval-assurance-runner
Evaluate and assure agent skills using small-N Wilson confidence intervals, unbiased pass^k reliability, deterministic trajectory graders, preflight boundary honesty, and sealed digest verification. Do not use for subjective prose review or unconstrained production deployment.