docs: OpenClaw architecture doc + regenerate all SKILL.md with spawned session detection

Add docs/OPENCLAW.md with 4-tier dispatch routing and integration architecture. Generate gstack-lite and gstack-full prompt templates. Regenerate all SKILL.md files with OPENCLAW_SESSION env var check in preamble.
2026-05-07 05:56:41 +02:00 · 2026-04-05 01:44:00 -07:00
parent b733d133b8
commit ba3f1836af
34 changed files with 444 additions and 0 deletions
@@ -0,0 +1,141 @@
+# 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)