Market Trends
GitHub Issue
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...
View Raw Thread
Developer & User Discourse
glittercowboy • Mar 25, 2026
Independent audit against current `main` plus the cited external surfaces.
I think the direction is good, but I would not merge this ADR as written yet. There are a few baseline mismatches in the “current state” section, and one protocol design gap that I think needs to be resolved before the v2 shape is locked in.
1. High: “No MCP server” is not accurate in the current tree.
The repo already ships `gsd --mode mcp` from the main CLI, and it already exposes a stdio MCP server over the current tool registry. Relevant code paths:
`src/cli.ts` wires `mode === 'mcp'` into `startMcpServer()`.
`src/mcp-server.ts` implements `tools/list` and `tools/call` over stdio.
`src/tests/mcp-server.test.ts` covers the module shape.
The missing thing is not “MCP exists vs does not exist”; it is “there is no orchestration-oriented MCP surface for long-running GSD workflows”. That distinction matters. As written, Phase 5 reads like greenfield work, when the real decision is whether to evolve the existing...
I think the direction is good, but I would not merge this ADR as written yet. There are a few baseline mismatches in the “current state” section, and one protocol design gap that I think needs to be resolved before the v2 shape is locked in.
1. High: “No MCP server” is not accurate in the current tree.
The repo already ships `gsd --mode mcp` from the main CLI, and it already exposes a stdio MCP server over the current tool registry. Relevant code paths:
`src/cli.ts` wires `mode === 'mcp'` into `startMcpServer()`.
`src/mcp-server.ts` implements `tools/list` and `tools/call` over stdio.
`src/tests/mcp-server.test.ts` covers the module shape.
The missing thing is not “MCP exists vs does not exist”; it is “there is no orchestration-oriented MCP surface for long-running GSD workflows”. That distinction matters. As written, Phase 5 reads like greenfield work, when the real decision is whether to evolve the existing...
glittercowboy • Mar 25, 2026
## Independent ADR Review
Thorough review grounding each claim against the current codebase and external ecosystem state.
---
### Overall Assessment
This is a well-structured ADR with genuine strategic vision. The phased approach is sound, the dependency graph is correct, and the "What We're NOT Doing" section shows good discipline. That said, there are factual inaccuracies, missing risks, and architectural gaps that should be addressed before this moves to "Accepted."
---
### Factual Accuracy Audit
#### Verified ✅
| Claim | Finding |
|---|---|
| "~30 commands" in RPC server | **31 commands** — close enough. Accurate. |
| Typed union types in `rpc-types.ts` | Confirmed. Discriminated unions for `RpcCommand`, `RpcResponse`, `RpcExtensionUIRequest`. |
| `waitForIdle()`, `collectEvents()`, `promptAndWait()` on RpcClient | All three exist. |
| String-matching completion detection | Confirmed in `headless-events.ts`: matches `'auto-mode stopped'`, `'step-mode stopped'`, `'blocked:'`...
Thorough review grounding each claim against the current codebase and external ecosystem state.
---
### Overall Assessment
This is a well-structured ADR with genuine strategic vision. The phased approach is sound, the dependency graph is correct, and the "What We're NOT Doing" section shows good discipline. That said, there are factual inaccuracies, missing risks, and architectural gaps that should be addressed before this moves to "Accepted."
---
### Factual Accuracy Audit
#### Verified ✅
| Claim | Finding |
|---|---|
| "~30 commands" in RPC server | **31 commands** — close enough. Accurate. |
| Typed union types in `rpc-types.ts` | Confirmed. Discriminated unions for `RpcCommand`, `RpcResponse`, `RpcExtensionUIRequest`. |
| `waitForIdle()`, `collectEvents()`, `promptAndWait()` on RpcClient | All three exist. |
| String-matching completion detection | Confirmed in `headless-events.ts`: matches `'auto-mode stopped'`, `'step-mode stopped'`, `'blocked:'`...
glittercowboy • Mar 25, 2026
## Synthesized Review — Final Assessment
After reading the ADR and both prior reviews in full, here's where things stand.
---
### Verdict: Accept with revisions before treating as implementation contract
The strategic thesis is correct — GSD as an execution backend for the agent ecosystem is the right play, and the phased approach is sound. But the ADR has enough baseline inaccuracies and underspecified areas that implementing against it as-is would create rework.
---
### Three blocking issues (must fix before accepting)
**1. Current-state baseline is wrong in several places — fix before locking v2 shape**
Both reviews caught this independently, which makes it high-confidence:
- An MCP server already ships (`gsd --mode mcp` → `startMcpServer()`). Phase 5 is not greenfield — it's "build an orchestration-oriented MCP surface on top of what exists." That's a meaningfully different scope and effort.
- `RpcClient` is exported from `@gsd/pi-coding-agent`. The gap is distribution (st...
After reading the ADR and both prior reviews in full, here's where things stand.
---
### Verdict: Accept with revisions before treating as implementation contract
The strategic thesis is correct — GSD as an execution backend for the agent ecosystem is the right play, and the phased approach is sound. But the ADR has enough baseline inaccuracies and underspecified areas that implementing against it as-is would create rework.
---
### Three blocking issues (must fix before accepting)
**1. Current-state baseline is wrong in several places — fix before locking v2 shape**
Both reviews caught this independently, which makes it high-confidence:
- An MCP server already ships (`gsd --mode mcp` → `startMcpServer()`). Phase 5 is not greenfield — it's "build an orchestration-oriented MCP surface on top of what exists." That's a meaningfully different scope and effort.
- `RpcClient` is exported from `@gsd/pi-coding-agent`. The gap is distribution (st...
trek-e • Mar 29, 2026
## VISION.md Alignment Review
**Supports:**
- **Extension-first**: Making GSD an execution backend for OpenClaw, MCP, and CI/CD is exactly the kind of ecosystem integration that the extension model enables
- **Ship fast**: The headless/RPC layer already exists with three internal consumers -- hardening it for external use is incremental, not greenfield
**Concerns:**
- The scope is broad (OpenClaw, MCP server, CI/CD, SDKs). Each integration should be independently shippable.
- The MCP server integration has a timing challenge (60s timeout vs 5-30min operations) that needs careful design for the start/poll/complete pattern.
**Recommendation:** Accept. Prioritize the MCP server exposure first (highest ecosystem demand), then OpenClaw/CI/CD integrations. Each should ship independently.
**Supports:**
- **Extension-first**: Making GSD an execution backend for OpenClaw, MCP, and CI/CD is exactly the kind of ecosystem integration that the extension model enables
- **Ship fast**: The headless/RPC layer already exists with three internal consumers -- hardening it for external use is incremental, not greenfield
**Concerns:**
- The scope is broad (OpenClaw, MCP server, CI/CD, SDKs). Each integration should be independently shippable.
- The MCP server integration has a timing challenge (60s timeout vs 5-30min operations) that needs careful design for the start/poll/complete pattern.
**Recommendation:** Accept. Prioritize the MCP server exposure first (highest ecosystem demand), then OpenClaw/CI/CD integrations. Each should ship independently.
The proposal to solidify the headless mode and JSON-RPC protocol as a programmable surface is a highly strategic and necessary evolution. By treating GSD as an execution engine for other AI agents and CI/CD pipelines, you are positioning it perfectly within the expanding AI ecosystem (OpenClaw, MCP, LangChain, etc.). The phased approach is logical, starting with foundational protocol hardening before moving to ecosystem integrations.
**Strengths:**
- **Clear Problem Definition:** The current pain points (lack of versioning, weak completion detection via string matching, missing shutdown command) are well-articulated. Relying on string-matching for completion is a known anti-pattern in automation that this ADR directly addresses.
- **Phased Rollout:** Breaking the work into manageable phases (Protocol -> CLI -> SDK -> Ecosystem -> Transports) mitigates risk and ensures incremental delivery of value.
- **Addressing the MCP Timeout:** Acknowledging the 60s MCP tim...