Market Trends
Gemini Executive Synthesis
Hardening and extending GSD-2's headless mode and JSON-RPC protocol for ecosystem integration
Technical Positioning
GSD-2 as the execution backend for the broader AI agent ecosystem (OpenClaw, MCP, CI/CD)
SaaS Insight & Market Implications
This Architectural Decision Record (ADR) outlines a critical strategic move for GSD-2: solidifying its headless mode and JSON-RPC protocol as the primary programmable surface for AI agent ecosystems. Positioning GSD-2 as an execution backend for platforms like OpenClaw and CI/CD pipelines is a direct response to market demand for robust, interoperable AI tools. The proposal addresses current limitations like weak completion detection and lack of versioning, which are anti-patterns in automation. While the strategic direction is sound, the internal audit reveals factual inaccuracies regarding existing MCP server capabilities, indicating a need for precise baseline assessment before locking in architectural changes.
Proprietary Technical Taxonomy
Raw Developer Origin & Technical Request
GitHub Issue
Mar 25, 2026
Repo: gsd-build/gsd-2
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...
Developer Debate & Comments
**Overall Impression:** 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...
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...
## 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:'`...
## 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...
## 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.
Adjacent Repository Pain Points
Other highly discussed features and pain points extracted from gsd-build/gsd-2.
Extracted Positioning
Integration of Gherkin DSL and cryptographic locking for improved AI code generation reliability
Algorithmically reliable, spec-driven AI code generation system
Top Replies
👋 Thanks for opening this issue! This was automatically flagged for maintainer review. **Flag:** Complexity without user value This proposal introduces significant architectural complexity (crypto...
I think is not a bad idea. > BDD (Behavior-Driven Development) is a software development approach where you define how the system should behave from the user’s perspective before writing the actual...
> It's kind of a natural fit to describe what needs to be done to AI. Agree. And instinctively i've been interacting with AI using Gherkin habits.... But it was nice to see a formal demonstration a...
Extracted Positioning
Architectural decision (ADR-005) for a multi-model, multi-provider, and tool strategy, addressing compatibility and routing complexities.
Establishing a robust, intelligent, and adaptable architecture for GSD2 to seamlessly integrate and manage diverse AI models and providers, ensuring tool compatibility and optimal model selection for autonomous agents. The goal is to enable agents to "work for long periods of time autonomously without losing track of the big picture."
Top Replies
Codex [P1] `ProviderSwitchReport` cannot be consumed by `before_model_select` at the point the ADR says it can. In the ADR, the report is defined after provider switching and message transformation...
### **Gemini ADR-005 Review: Multi-Model, Multi-Provider, and Tool Strategy** I have reviewed the proposal and its alignment with the existing routing architecture (ADR-004). This is a necessary ev...
## ADR-005 Review: Findings and Recommendations (Revised) As Grok, built by xAI, I've reviewed ADR-005: Multi-Model, Multi-Provider, and Tool Strategy based on a deep exploration of the codebase an...
Extracted Positioning
Architectural decision to modularize GSD2's monolithic structure into shippable extensions with install infrastructure.
Evolving GSD2 from a monolithic application to a modular, extensible platform with optimized resource consumption and improved performance, enhancing its appeal as a "powerful meta-prompting, context engineering and spec-driven development system."
Top Replies
## ADR-006 Review: Findings and Recommendations As Grok, built by xAI, I've reviewed ADR-006: Extension Modularization & Install Infrastructure based on a deep exploration of the codebase and the A...
## Research Findings (2026-03-28) 4 parallel researchers completed — Stack, Features, Architecture, Pitfalls. Full synthesis in `.planning/research/SUMMARY.md`. ### Stack - **One new dependency:** ...
## Implementation Plan: Extension Modularization **Full plan:** [`.plans/IMPLEMENTATION-PLAN-extension-modularization.md`](https://github.com/jeremymcs/gsd-2/blob/feat/extension-system-analysis/.pl...
Engagement Signals
Cross-Market Term Frequency
Quantifies the cross-market adoption of foundational terms like MCP and OpenClaw by tracking occurrence frequency across active SaaS architectures and enterprise developer debates.