Ground Control

For the local disposable Incus coding-VM operator workflow, see Local Incus coding sandbox.

Ground Control is an MCP server for the /implement workflow, a gated, agentic development loop that gives coding agents full codebase context, from use case to implementation, and keeps the coding agent separated from its reviewers.

Requirements, ADRs, and use cases live as files in the consuming repo (docs/requirements/<UID>/requirement.md, architecture/adrs/*.md). There is no backend, database, or web console: the MCP server is the only running service, and it reads and writes those files and the GitHub issue thread directly. The optional Graphify index is available for code+docs comprehension when an agent wants it, it is not required.

This repository was re-platformed from a graph-native GRC/requirements product to the MCP server alone (issue #1500). The requirements-as-files record is ADR-093; the optional comprehension index is ADR-094.

What the MCP server does

The surviving tool surface (34 tools, down from 215) is exactly what the /implement workflow needs, and every tool operates over gh/git/files, no backend:

• Orchestration, gc_implement_mechanical drives the mechanical bands (bootstrap, verify, publish, monitor, readiness, finalize); gc_codex_job carries the long async actions and can hold one request until a job is terminal; gc_get_repo_ground_control_context reads .ground-control.yaml.
• Git / GitHub mechanics, branch prep, issue pickup, issue-thread reads, base sync, synchronized PR creation, PR-body rendering, issue close, and issue creation from a requirement file.
• CI / quality signals, gc_watch_ci_run (GitHub) and gc_watch_sonar_analysis (direct), read live.
• Reviewer separation, the Codex review, architecture-preflight, and verify tools plus the review-cap disposition; the coding agent never reviews its own work.
• Durable records, plan, decision records, execution obligations, and the final report all post to the GitHub issue thread (ADR-029).
• Release identities, gc_release_identity reserves each versioned evidence-release identity in a repository reference log before capture, so concurrent runs never produce the same version (ADR-097).

Requirement status and traceability are recorded by the agent directly in the requirement file, reviewed in the PR like any other change.

Repository map

Where each top-level directory belongs, so a contributor can tell where a new file goes. The Documentation table further down is the reading index; this is the ownership map.

Path	What lives here
mcp/	The MCP servers. mcp/ground-control/ is the only running service (Node.js ES modules), published to npm as grndctl; see the MCP server reference. mcp/citation/ is a separate research companion.
skills/	Agent-neutral workflow skills. The gated /implement loop lives in skills/implement/; the development workflow explains it.
docs/	The public user documentation (docs/public/, built by Read the Docs), requirements (docs/requirements/<UID>/requirement.md), the architecture overview, coding standards, and the knowledge base.
architecture/	Architecture Decision Records (architecture/adrs/) and the machine-enforced ADR policy.
tools/	Repo-native policy checks (tools/policy/) and their tests, plus CI, Sonar, and release tooling. Run by make policy.
bin/	Executable entry points: the gates (bin/policy, bin/adr-guard, bin/check-pr-body), the host installers (bin/install-ground-control.sh, bin/install-skills.sh), and the host-wide verification dispatcher (bin/gc-test-dispatch).
scripts/	Developer and CI shell helpers (scripts/): hook install, bootstrap, PR-body checks.
.github/	GitHub Actions workflows, issue/PR templates, CODEOWNERS, and the branch-protection baseline.

Agent/editor tooling directories (.claude, .cursor, .gc, .serena, .vale) are configuration, not source surfaces, and are intentionally left out. The map is kept in sync with the tracked directory tree by a policy gate (tools/policy/repo_map.py, GC-P029 / ADR-095).

Install

npm install -g grndctl      # Node.js 22+, with gh signed in
grndctl install-skills      # /implement, /quickfix, /integrate, /review

Then, in each repository agents should work in:

grndctl init                # confirm the detected settings, review the changes, then write
grndctl doctor              # check the machine and the repository

Restart your agent session and run /implement <issue-number>. The documentation covers installation, repository setup, configuration, and upgrading.

Isolated coding VMs

To run agents in disposable Incus VMs instead of on the host, the same package sets up the sandbox and fetches its published guest template from the GitHub Container Registry:

grndctl sandbox setup install   # privileged, one-time host setup
grndctl sandbox image           # pull ghcr.io/autarchy-ai/gc-sandbox-template:latest

The pull prints the local:<fingerprint> line to pin in /etc/gc-incus-sandbox/config.json. After that, grndctl sandbox create, prepare, migrate, task-start, and attach give an agent a private checkout and an explicitly started task in its own VM. Repository-scoped task variables are opt-in; setup creates no shared or per-repository values. See docs/operations/incus-sandbox.md.

Developing Ground Control

To work on Ground Control itself, clone it and see CONTRIBUTING:

make ground-control-mcp-install   # npm ci in mcp/ground-control
make mcp-test     # MCP node --test suite (primary test gate)
make mcp-lint     # ESLint on the MCP server (also run by `make policy`)
make policy       # repo-native ADR/workflow/spec guardrails + MCP lint + Vale
make vale-lint    # prose lint on changed docs
make docs         # build the public docs with warnings as errors
make graphify     # (optional) rebuild the disposable Graphify index

Run make help to see all targets.

Documentation

Document	Description
User documentation	Install, repository setup, configuration, upgrading (published on Read the Docs)
MCP Server	Tool reference, workflows
Development Workflow	The /implement loop
Coding Standards	Style and testing policy
Graphify	Optional comprehension index
ADRs	Architecture Decision Records
Contributing	Setup, workflow, PR process
Changelog	Release history

License

MIT