CalvinBackup/gstack
1
0
Fork 0
mirror of https://github.com/garrytan/gstack.git synced 2026-06-28 12:39:58 +02:00
Code Issues Packages Projects Releases Wiki Activity

feat(gbrain): /setup-gbrain Step 1.5/4.5 + /sync-gbrain Step 1.5 templates

Browse Source 
Per plan D4, D10, D11, D12. Wires the skill prose to the new
split-engine flow + classifier introduced in earlier commits.

setup-gbrain/SKILL.md.tmpl:
  - Step 1: detect output description now includes the v1.34.0.0
    gbrain_local_status field (5 values).
  - Step 1.5 (NEW): broken-db / broken-config remediation. AskUserQuestion
    with 4 options — Retry / Switch to PGLite / Switch brain mode / Quit
    (plan D4). Retry is recommended first since broken-db often = transient
    Postgres outage. PGLite is explicitly one-way + destructive (moves
    existing config to ~/.gbrain/config.json.gstack-bak-<ts>); rollback on
    init failure restores the .bak (plan D7).
  - Step 4d → Step 4.5 (NEW): in Path 4, after the verify step, offer
    local PGLite for code search. AskUserQuestion Yes/No (plan D10/D11).
    Yes path runs gstack-gbrain-install + `gbrain init --pglite --json`
    with the same rollback-safe sequence. No path skips Steps 3/4/5/7.5.
  - Step 10 verdict (Path 4): adds "Code search" row reflecting Step 4.5
    choice. Updates "Transcripts" row to describe the new D11 routing
    (artifacts repo → remote brain).

sync-gbrain/SKILL.md.tmpl:
  - Step 1 split-engine prose: corrects the prior misleading claim that
    "memory routes through whatever setup-gbrain configured, including
    remote-MCP" (codex finding #3). Memory stage shells out to local
    `gbrain import` in local-stdio mode; in remote-http mode it persists
    to ~/.gstack/transcripts/ for the artifacts pipeline.
  - Step 1.5 (NEW): local-engine pre-flight. STOP on no-cli, broken-config,
    broken-db. Soft skip (continue with code+memory SKIP) on
    missing-config + remote-http per plan D12. Surfaces actionable user
    remediation message instead of the orchestrator crashing two stages
    with ERR.

Regenerated SKILL.md for all hosts (claude, kiro, opencode, slate,
cursor, openclaw, hermes, gbrain). All 712 skill-validation + gen-skill-docs
tests pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Garry Tan
2026-05-13 11:53:56 -07:00
parent dc51fa9de1
commit 0668f928a6
4 changed files with 380 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files
sync-gbrain/SKILL.md
+51 -21
View File
@@ -788,28 +788,20 @@ Before doing anything, check that /setup-gbrain has been run on this Mac.
~/.claude/skills/gstack/bin/gstack-gbrain-detect 2>/dev/null
```
**Split-engine model.** Code stage always runs locally against a per-machine
PGLite brain (or whatever `gbrain config` points to), with each worktree of a
repo registered as its own source. Artifacts/memory stages route through
whatever `setup-gbrain` configured — including remote-MCP (Path 4). The two
sides are independent: code lookups are local + worktree-scoped, artifacts
remain cross-machine.
**Split-engine model (v1.34.0.0+).** Code stage runs locally against the
per-machine gbrain engine (PGLite or whatever `gbrain config` points to),
with each worktree of a repo registered as its own source. **Memory stage
also runs locally** in local-stdio MCP mode — `gstack-memory-ingest` shells
out to `gbrain import` against the same local engine. In remote-http MCP
mode (Path 4), the memory stage instead persists staged markdown to
`~/.gstack/transcripts/<run-id>/` and the artifacts pipeline pushes it to
the brain admin's pull job (plan D11). Brain-sync (the `gstack-brain-sync`
push to git) is the one stage that never touches local engine and runs
regardless of mode.
A previous version of this skill bounced remote-MCP users out of the code
stage entirely. That was wrong: the code-stage CLI calls (`gbrain sources
add`, `sync --strategy code`, `sources attach`) target the LOCAL gbrain CLI
+ DB regardless of whether `~/.claude.json` has `gbrain` registered as a
remote HTTP MCP for artifacts. We no longer skip the code stage in
remote-MCP mode.
If `gbrain_on_path=false` OR `gbrain_config_exists=false`, STOP and tell
the user:
> "/sync-gbrain requires /setup-gbrain to be run first. Run `/setup-gbrain`
> to install gbrain, register the MCP server, and set per-repo trust policy."
Do NOT continue — the skill is unsafe when the local gbrain CLI is missing
(we'd write a CLAUDE.md guidance block referencing tools that don't exist).
Practically: local PGLite stays code-only on remote-http machines; the
remote brain holds everything else. Local-stdio machines mix code +
transcripts in one local engine, as they always have.
Also check the per-repo trust policy. If `gstack-gbrain-repo-policy get` for
this repo returns `deny`, STOP:
@@ -819,6 +811,44 @@ this repo returns `deny`, STOP:
---
## Step 1.5: Local engine pre-flight (plan D12)
Read `gbrain_local_status` from the Step 1 detect output. Branch as follows
BEFORE invoking the orchestrator:
- **`ok`**: proceed to Step 2 normally.
- **`no-cli`**: STOP. "Local gbrain CLI not installed. Run `/setup-gbrain`
first."
- **`missing-config`** AND `gbrain_mcp_mode == "remote-http"`: tell the user
"Your brain queries (the `mcp__gbrain__*` tools) work via remote MCP, but
symbol code search needs a local PGLite. Run `/setup-gbrain` and pick
'Yes' at the new 'local code index' prompt (Step 4.5), or run
`gbrain init --pglite --json` directly. Continuing without code stage."
Then proceed to Step 2 — the orchestrator's `runCodeImport()` and
`runMemoryIngest()` will return SKIP per plan D12; only `runBrainSyncPush()`
will run. Do NOT abort.
- **`missing-config`** AND `gbrain_mcp_mode != "remote-http"`: STOP. "Local
gbrain CLI is installed but no engine config. Run `/setup-gbrain` first."
- **`broken-config`** OR **`broken-db`**: STOP with a clear message:
```
Local gbrain config at ~/.gbrain/config.json points at an unreachable
engine (status: {gbrain_local_status}). Two options:
1. Re-run /setup-gbrain — Step 1.5 offers Retry / Switch to PGLite /
Switch brain mode / Quit (plan D4).
2. Repair manually: mv ~/.gbrain/config.json ~/.gbrain/config.json.bak
&& gbrain init --pglite --json
Re-run /sync-gbrain after.
```
Do NOT continue — the orchestrator would skip code+memory and only run
brain-sync, which is a degraded state the user should fix explicitly.
This pre-flight short-circuits the orchestrator before it spends ~80ms
probing the engine again. The orchestrator independently runs the same
classifier for defense-in-depth, but Step 1.5's STOP is where the user
gets the actionable remediation message.
---
## Step 2: Run the orchestrator
Pass user args to the orchestrator. Do not paraphrase them — pass through
sync-gbrain/SKILL.md.tmpl
+51 -21
View File
@@ -66,28 +66,20 @@ Before doing anything, check that /setup-gbrain has been run on this Mac.
~/.claude/skills/gstack/bin/gstack-gbrain-detect 2>/dev/null
```
**Split-engine model.** Code stage always runs locally against a per-machine
PGLite brain (or whatever `gbrain config` points to), with each worktree of a
repo registered as its own source. Artifacts/memory stages route through
whatever `setup-gbrain` configured — including remote-MCP (Path 4). The two
sides are independent: code lookups are local + worktree-scoped, artifacts
remain cross-machine.
**Split-engine model (v1.34.0.0+).** Code stage runs locally against the
per-machine gbrain engine (PGLite or whatever `gbrain config` points to),
with each worktree of a repo registered as its own source. **Memory stage
also runs locally** in local-stdio MCP mode — `gstack-memory-ingest` shells
out to `gbrain import` against the same local engine. In remote-http MCP
mode (Path 4), the memory stage instead persists staged markdown to
`~/.gstack/transcripts/<run-id>/` and the artifacts pipeline pushes it to
the brain admin's pull job (plan D11). Brain-sync (the `gstack-brain-sync`
push to git) is the one stage that never touches local engine and runs
regardless of mode.
A previous version of this skill bounced remote-MCP users out of the code
stage entirely. That was wrong: the code-stage CLI calls (`gbrain sources
add`, `sync --strategy code`, `sources attach`) target the LOCAL gbrain CLI
+ DB regardless of whether `~/.claude.json` has `gbrain` registered as a
remote HTTP MCP for artifacts. We no longer skip the code stage in
remote-MCP mode.
If `gbrain_on_path=false` OR `gbrain_config_exists=false`, STOP and tell
the user:
> "/sync-gbrain requires /setup-gbrain to be run first. Run `/setup-gbrain`
> to install gbrain, register the MCP server, and set per-repo trust policy."
Do NOT continue — the skill is unsafe when the local gbrain CLI is missing
(we'd write a CLAUDE.md guidance block referencing tools that don't exist).
Practically: local PGLite stays code-only on remote-http machines; the
remote brain holds everything else. Local-stdio machines mix code +
transcripts in one local engine, as they always have.
Also check the per-repo trust policy. If `gstack-gbrain-repo-policy get` for
this repo returns `deny`, STOP:
@@ -97,6 +89,44 @@ this repo returns `deny`, STOP:
---
## Step 1.5: Local engine pre-flight (plan D12)
Read `gbrain_local_status` from the Step 1 detect output. Branch as follows
BEFORE invoking the orchestrator:
- **`ok`**: proceed to Step 2 normally.
- **`no-cli`**: STOP. "Local gbrain CLI not installed. Run `/setup-gbrain`
first."
- **`missing-config`** AND `gbrain_mcp_mode == "remote-http"`: tell the user
"Your brain queries (the `mcp__gbrain__*` tools) work via remote MCP, but
symbol code search needs a local PGLite. Run `/setup-gbrain` and pick
'Yes' at the new 'local code index' prompt (Step 4.5), or run
`gbrain init --pglite --json` directly. Continuing without code stage."
Then proceed to Step 2 — the orchestrator's `runCodeImport()` and
`runMemoryIngest()` will return SKIP per plan D12; only `runBrainSyncPush()`
will run. Do NOT abort.
- **`missing-config`** AND `gbrain_mcp_mode != "remote-http"`: STOP. "Local
gbrain CLI is installed but no engine config. Run `/setup-gbrain` first."
- **`broken-config`** OR **`broken-db`**: STOP with a clear message:
```
Local gbrain config at ~/.gbrain/config.json points at an unreachable
engine (status: {gbrain_local_status}). Two options:
1. Re-run /setup-gbrain — Step 1.5 offers Retry / Switch to PGLite /
Switch brain mode / Quit (plan D4).
2. Repair manually: mv ~/.gbrain/config.json ~/.gbrain/config.json.bak
&& gbrain init --pglite --json
Re-run /sync-gbrain after.
```
Do NOT continue — the orchestrator would skip code+memory and only run
brain-sync, which is a degraded state the user should fix explicitly.
This pre-flight short-circuits the orchestrator before it spends ~80ms
probing the engine again. The orchestrator independently runs the same
classifier for defense-in-depth, but Step 1.5's STOP is where the user
gets the actionable remediation message.
---
## Step 2: Run the orchestrator
Pass user args to the orchestrator. Do not paraphrase them — pass through