mirror of
https://github.com/garrytan/gstack.git
synced 2026-10-31 22:14:25 +01:00
Garry Tanandcapy-ai[bot]
b61744517c
* fix(harness): register OpenClaw skills over its 32 KB whole-read limit as entries pointing at SKILL.full.md (GST-110) #3555's hybrid layout registered review, investigate, ship and plan-eng-review as OpenClaw skills; OpenClaw serves a registered SKILL.md whole or refuses it, at 32,768 bytes when the model's context window is unknown. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * docs(harness): OpenClaw entry skills and the whole-read limit; CHANGELOG (GST-110) Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * fix: pre-landing review fixes (GST-110) Entries point at a full SKILL.md in a plain copy of every skill (the router's gstack/skills/ in hybrid, .gstack-skills/ under --skills all), so autoplan's ../gstack-plan-eng-review/SKILL.md and other sibling paths reach full texts; test the #3555 upgrade path. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * docs: remove .gstack-skills in the manual OpenClaw uninstall (GST-110) Step 14.5 audit gst110-docs-1: the gstack* glob never matched the dot folder that --skills all registrations now write. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * fix(harness): OpenClaw entry threshold 32,000 bytes so served skills also fit a 100K-200K-token tool-result budget (GST-110) Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * v1.91.334.0 stamp Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --------- Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
209 lines
10 KiB
Markdown
209 lines
10 KiB
Markdown
# 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)
|
|
|
|
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-investigate` — Operational debugging (4-phase methodology)
|
|
- `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](https://github.com/openclaw/openclaw/issues/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:
|
|
|
|
```bash
|
|
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](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 five task
|
|
skills (review, investigate, qa, ship, plan-eng-review) 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, investigate, ship and plan-eng-review among the five) 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](hosts.md#agent-harnesses).
|
|
|
|
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)
|