# 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 (Wintermute)                    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

Wintermute 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 |

### 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**

### Dispatch routing guide (for AGENTS.md)

Add this to Wintermute's AGENTS.md:

```markdown
## 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
```

### 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

### 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 (Wintermute has its own)
- No full skill porting (coding skills stay native to Claude Code)