Repo Context Kit

repo-context-kit

An MCP-first, runtime/v1 JSON repository context layer that gives AI coding agents bounded repo knowledge, task state, verification framing, and confirmation-gated execution.

Role: Solo Developer / Maintainer

Highlights

Node.jsJavaScriptESMnpm CLIMCP serverRuntime/v1 JSONConfirmation gatesDeterministic repository scanningNode test runnerGitHub Actions

Published a public npm CLI with a companion MCP server for AI-assisted repository context and workflow governance.
Reworked the product around MCP-first usage, runtime/v1 JSON contracts, and a deliberately slim CLI fallback surface.
Built deterministic scan outputs for project summaries, file indexes, symbol indexes, task maps, runtime state, and verification requirements.
Implemented bounded context, task prompt, checklist, PR framing, file search, symbol lookup, and runtime validation surfaces for AI tools.
Added tiered MCP capabilities and confirmation-gated task/test execution so writes, tests, and side effects stay explicit and reviewable.

Problem

AI coding agents often lose repository structure, task intent, workflow rules, and verification expectations across longer sessions.

Large markdown prompt dumps waste context budget and make agent behavior harder to audit or reproduce.

Many AI development workflows treat project context as temporary chat text instead of persistent, inspectable runtime state.

Teams need AI tools to read context and prepare work without silently crossing into edits, tests, shell execution, or external side effects.

Approach

I built repo-context-kit as an installable repository runtime layer for existing projects rather than as another autonomous agent.

I made MCP tools and runtime/v1 JSON the primary agent-facing interface, with the CLI kept as a compact debug, compatibility, and CI surface.

I modeled task, context, execution, and verification as bounded JSON envelopes under `.aidw/runtime/*.json`.

I designed the workflow around explicit human approval boundaries: bounded context first, then gated actions, then verification evidence.

Result

Published a reusable npm package that gives AI coding tools a portable repository runtime and context governance layer.

Created a compact MCP and JSON-first workflow for maintaining structured project context, task state, execution policy, and verification requirements.

Reduced the agent-facing surface to bounded context and explicit gates, making AI-assisted development easier to inspect, resume, and trust.

Implementation

MCP-first runtime

Implemented `repo-context-kit-mcp` with read-only tools for repo summaries, bounded context, task worksets, file search, symbol lookup, metrics, and runtime validation
Added opt-in MCP capability tiers for workflow writes, test execution, and external side effects
Kept MCP outputs compact JSON with runtime budgeting so tool responses remain deterministic and agent-friendly

Runtime JSON and scanning

Generated runtime/v1 envelopes for task, context, execution, and verification state
Built deterministic scan outputs for `.aidw/AI_project.md`, system overview, file indexes, symbol indexes, file summaries, file groups, entrypoints, and task maps
Added schema validation, stable sorting, payload budgeting, and legacy contract rejection to keep runtime data predictable

Workflow and verification gates

Implemented task prompt, checklist, and PR-framing commands backed by runtime JSON rather than full markdown injection
Added scan freshness checks, project consistency checks, lesson-based warnings, and task registry validation
Built confirmation-gated task approval and test execution with scoped tokens, explicit human confirmation evidence, and recorded loop events

Slim CLI surface

Consolidated the public CLI around `init`, `scan`, `context`, `task`, `gate`, `check`, and `metrics`
Removed broader automation-style commands and aliases so the project stays focused on context governance rather than autonomous execution
Covered the supported surface with regression tests for CLI output, MCP tool lists, runtime contracts, gates, budgeting, and deterministic behavior

Lessons

AI-assisted development is more reliable when repository context is treated as versioned runtime state instead of temporary prompt text.
A slim, deterministic command surface is easier to test and safer to expose than a broad automation toolkit.
MCP tools work best when read-only behavior is the default and higher-risk capabilities are opt-in, tiered, and gated.
Compact JSON contracts are more dependable for agents than markdown-heavy context dumps, especially when payloads are budgeted and schema-validated.
Signals such as stale scans, lessons, metrics, and risk summaries should guide attention, not silently trigger actions.