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
       │   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)

The complete ready-to-paste section lives in openclaw/agents-gstack-section.md. Copy it into your OpenClaw AGENTS.md.

Key behavioral rules (these go ABOVE the dispatch tiers):

1. Always spawn, never redirect. When the user asks to use ANY gstack skill, ALWAYS spawn a Claude Code session. Never tell the user to open Claude Code.
2. Resolve the repo. If the user names a repo, set the working directory. If unknown, ask which repo.
3. Autoplan runs end-to-end. Spawn, let it run the full pipeline, report back in chat. User should never have to leave Telegram.

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

Published to ClawHub. Install with clawhub install:

• gstack-openclaw-office-hours — Product interrogation (6 forcing questions)
• gstack-openclaw-ceo-review — Strategic challenge (10-section review, 4 modes)
• gstack-openclaw-retro — Operational retrospective (weekly review)

Source lives in openclaw/skills/ in the gstack repo. These are hand-crafted adaptations of the gstack methodology for OpenClaw's conversational context. No gstack infrastructure (no browser, 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; destructive or irreversible options are never auto-chosen — the conservative choice wins and gets recorded in the completion report)
• Suppresses interactive-onboarding instruction blocks at emission (upgrade checks, telemetry prompts, feature discovery, routing injection, tips), so one-time prompts survive intact for the next human session
• Suppresses the Conductor prose signal (CONDUCTOR_SESSION: true) — a spawned session inside a Conductor workspace auto-chooses instead of rendering prose to nobody
• Focuses on task completion and prose reporting

sessions_spawn has no per-spawn environment argument (openclaw/openclaw#51654 was closed without adding one), so an env field in the tool call is ignored. Set OPENCLAW_SESSION=1 in the environment of the Claude ACP harness or the Gateway service instead, keep credentials out of that wrapper, and confirm the variable from inside the spawned process (for example echo $OPENCLAW_SESSION) rather than trusting the session's final message.

Explicit override: GSTACK_SESSION_KIND

GSTACK_SESSION_KIND=spawned is the explicit per-command marker for the same classification, outranking every ambient env marker (including OPENCLAW_SESSION and GSTACK_HEADLESS). It exists because Claude Code subagents inherit the parent session's env byte-for-byte (#2733) — a dispatching skill marks its subagent by prefixing the preamble invocation on the same command line:

GSTACK_SESSION_KIND=spawned "$_SS" --skill "document-release" ...

gstack itself uses this: /ship Step 14.5 dispatches the /document-release subagent with this prefix before final commit, verification and publication. Its ship-owned scope overrides generic spawned auto-choice: risky or uncertain documentation changes return as blockers for the parent, without interactive questions or automatic approval. Deliberately narrow: only spawned and unattended are honored (unattended is a separate, explicitly selected contract for a parent that reads a run's artifacts; see unattended.md) — headless already has GSTACK_HEADLESS, and letting an env var force interactive over CI markers would be a misclassification footgun. Empty or other values are reserved and ignored (fall through to ambient detection). Note that hook processes inherit the harness env, so a per-command prefix never reaches PreToolUse/PostToolUse hooks — the hook texts carry a spawned escape sentence for that topology (hosts/claude/hooks/spawned-directive.ts).

Tamper visibility. Any mechanism that injects session-wide env (a cloned repo's .claude/settings.json env block, direnv, a CI wrapper) could set GSTACK_SESSION_KIND=spawned for a real human's session and silently flip its confirmation gates to auto-choose. When the env override drives the classification, the preamble emits a loud SPAWNED_OVERRIDE: env status line so the transcript shows WHY the session is spawned — audit .claude/settings.json env blocks in untrusted repos (/cso covers this).

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

Native skills or ACP. ./setup --host openclaw (or ./setup run inside an OpenClaw session) gives OpenClaw's own agent gstack's skills: the three task skills (review, qa, ship) listed directly and one gstack router skill for the rest in $OPENCLAW_STATE_DIR/skills, rendered with OpenClaw's tool names and pointing at the installed gstack, so the agent runs gstack's workflows and helpers itself. Use ACP when the work should happen in a Claude Code session with the full install (hooks, Claude tool names); use native skills when the OpenClaw agent should do it. Both can be installed together. OpenClaw serves a registered skill's SKILL.md whole or refuses it, and its limit is 32,768 bytes when it does not know the model's context window (32,000 characters with a 100K-200K-token one), so a skill over 32,000 bytes (review and ship among the three) is registered as a short entry that tells the agent to read the skill's full SKILL.md in gstack/skills/, a plain copy of every skill that OpenClaw reads in pages (.gstack-skills/ under --skills all). Install, verify and remove: hosts.md. Agents in OpenClaw read gstack's skills but rarely run their start command, so there is an opt-in start hook: gstack-harness register openclaw --start-hook adds a gstack-start plugin that puts a one-line note on every user turn, and grants it the conversation access OpenClaw requires for before_prompt_build through openclaw config set.

The ACP artifacts in openclaw/ 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 hand-ported coding skills (native registration copies the generated OpenClaw render)