gstack/docs/OPENCLAW.md

gstack x OpenClaw Integration

gstack integrates with OpenClaw as a methodology source, not a ported codebase. OpenClaw's ACP runtime spawns Claude Code sessions natively. gstack provides the planning discipline and methodology that makes those sessions better.

This is a lightweight protocol encoded as prompt text. No daemon. No JSON-RPC. No compatibility matrices. The prompt is the bridge.

Architecture

  OpenClaw                               gstack repo
  ─────────────────────                    ──────────────
  Orchestrator: messaging,                 Source of truth for
  calendar, memory, EA                     methodology + planning
       │                                        │
       ├── Native skills (conversational)       ├── Generates native skills
       │   office-hours, ceo-review,            │   via gen-skill-docs pipeline
       │   investigate, retro                   │
       │                                        ├── Generates gstack-lite
       ├── sessions_spawn(runtime: "acp")       │   (planning discipline)
       │       │                                │
       │       └── Claude Code                  ├── Generates gstack-full
       │           └── gstack installed at      │   (complete pipeline)
       │               ~/.claude/skills/gstack  │
       │                                        └── docs/OPENCLAW.md (this file)
       └── Dispatch routing (AGENTS.md)

Dispatch Routing

OpenClaw decides at spawn time which tier of gstack support to use:

Tier	When	Prompt prefix
Simple	One-file edits, typos, config changes	No gstack context injected
Medium	Multi-file features, refactors	gstack-lite CLAUDE.md appended
Heavy	Specific gstack skill needed	"Load gstack. Run /X"
Full	Complete features, objectives, projects	gstack-full pipeline appended
Plan	"Help me plan a Claude Code project"	gstack-plan pipeline appended

Decision heuristic

• Can it be done in <10 lines of code? -> Simple
• Does it touch multiple files but the approach is obvious? -> Medium
• Does the user name a specific skill (/cso, /review, /qa)? -> Heavy
• Is it a feature, project, or objective (not a task)? -> Full
• Does the user want to PLAN something for Claude Code without implementing yet? -> Plan

Dispatch routing guide (for AGENTS.md)

Add this to OpenClaw's AGENTS.md:

## Coding Task Dispatch

When asked for coding work, pick the dispatch tier:

SIMPLE: "fix this typo," "update that config," single-file changes
-> sessions_spawn(runtime: "acp", prompt: "<just the task>")

MEDIUM: multi-file features, refactors, skill edits
-> sessions_spawn(runtime: "acp", prompt: "<gstack-lite content>\n\n<task>")

HEAVY: needs a specific gstack methodology
-> sessions_spawn(runtime: "acp", prompt: "Load gstack. Run /qa https://...")
  Skills: /cso, /review, /qa, /ship, /investigate, /design-review, /benchmark

FULL: build a complete feature, multi-day scope, needs planning + review
-> sessions_spawn(runtime: "acp", prompt: "<gstack-full content>\n\n<task>")
  Claude Code runs: /autoplan -> implement -> /ship -> report back

PLAN: user wants to plan a Claude Code project, spec out a feature, or design
  something before any code is written
-> sessions_spawn(runtime: "acp", prompt: "<gstack-plan content>\n\n<task>")
  Claude Code runs: /office-hours -> /autoplan -> saves plan file -> reports back
  The orchestrator persists the plan link to its memory/knowledge store.
  When the user is ready to implement, spawn a new FULL session pointing at the plan.

CLAUDE.md collision handling

When spawning Claude Code in a repo that already has a CLAUDE.md, APPEND gstack-lite/full as a new section. Do not replace the repo's existing instructions.

What gstack generates for OpenClaw

All artifacts live in the openclaw/ directory and are generated by bun run gen:skill-docs --host openclaw:

gstack-lite (Medium tier)

openclaw/gstack-lite-CLAUDE.md — ~15 lines of planning discipline:

1. Read every file before modifying
2. Write a 5-line plan: what, why, which files, test case, risk
3. Resolve ambiguity using decision principles
4. Self-review before reporting done
5. Completion report: what shipped, decisions made, anything uncertain

A/B tested: 2x time, meaningfully better output.

gstack-full (Full tier)

openclaw/gstack-full-CLAUDE.md — chains existing gstack skills:

1. Read CLAUDE.md and understand the project
2. Run /autoplan (CEO + eng + design review)
3. Implement the approved plan
4. Run /ship to create a PR
5. Report back with PR URL and decisions

gstack-plan (Plan tier)

openclaw/gstack-plan-CLAUDE.md — full review gauntlet, no implementation:

1. Run /office-hours to produce a design doc
2. Run /autoplan (CEO + eng + design + DX reviews + codex adversarial)
3. Save the reviewed plan to plans/<project-slug>-plan-<date>.md
4. Report back: plan path, summary, key decisions, recommended next step

The orchestrator persists the plan link to its own memory store (brain repo, knowledge base, or whatever is configured in AGENTS.md). When the user is ready to build, spawn a FULL session that references the saved plan.

Native methodology skills

Conversational skills for non-coding work, generated from gstack source templates:

• openclaw/office-hours.md — Product interrogation (6 forcing questions)
• openclaw/ceo-review.md — Strategic challenge (10-section review, 4 modes)
• openclaw/investigate.md — Operational debugging (4-phase methodology)
• openclaw/retro.md — Operational retrospective (weekly review)

These are lean adaptations. They contain the methodology, not the full gstack skill infrastructure (no browse, no telemetry, no preamble).

Spawned session detection

When Claude Code runs inside a session spawned by OpenClaw, the OPENCLAW_SESSION environment variable should be set. gstack detects this and adjusts:

• Skips interactive prompts (auto-chooses recommended options)
• Skips upgrade checks and telemetry prompts
• Focuses on task completion and prose reporting

Set the env var in sessions_spawn: env: { OPENCLAW_SESSION: "1" }

Installation

For OpenClaw users: tell your OpenClaw agent "install gstack for openclaw."

The agent should:

1. Install gstack-lite CLAUDE.md into its coding session templates
2. Install the 4 native methodology skills
3. Add dispatch routing to AGENTS.md
4. Verify with a test spawn

For gstack developers: ./setup --host openclaw outputs this documentation. The actual artifacts are generated by bun run gen:skill-docs --host openclaw.

What we don't do

• No dispatch daemon (ACP handles session spawning)
• No Clawvisor relay (no security layer needed)
• No bidirectional learnings bridge (brain repo is the knowledge store)
• No JSON schemas or protocol versioning
• No SOUL.md from gstack (OpenClaw has its own)
• No full skill porting (coding skills stay native to Claude Code)