ADR: Headless Mode as GSD's Programmable Surface for the Agent Ecosystem

## ADR: Headless Mode as GSD's Programmable Surface for the Agent Ecosystem **Status:** Proposed **Date:** 2026-03-25 **Author:** @glittercowboy **Scope:** Headless mode, JSON-RPC protocol, ecosystem integrations (OpenClaw, MCP, CI/CD, SDKs) --- ## Context GSD-2 is a structured project execution engine that takes a vague spec and delivers a working implementation through a research → plan → execute → verify pipeline. It currently ships with a TUI as the primary interface. GSD also ships a **headless mode** (`gsd headless`) and a **JSON-RPC protocol** (`--mode rpc`) that allow programmatic, non-interactive operation. Three internal consumers already use this: the headless CLI orchestrator, a web bridge (`bridge-service.ts`), and a VS Code extension. GSD is gaining thousands of GitHub stars. The opportunity is to make GSD the **execution backend that any AI agent can call** — from OpenClaw skills to MCP servers to CI pipelines. The headless mode is the programmable surface that enables this. This ADR proposes hardening and extending the headless/RPC layer to be a world-class, ecosystem-ready API. --- ## Decision Drivers 1. **OpenClaw (300K+ GitHub stars)** is the dominant agent platform. Its skills integrate external tools via subprocess exec — calling CLI tools and reading stdout. A GSD OpenClaw skill would give instant distribution to the entire ecosystem. The integration contract is: a CLI that accepts a task, produces machine-parseable output, and exits with meani...