Ground Control

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 (33 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; 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, the test-quality review tools, and 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).

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.

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