From 8052f4bf129afed381e6f6b3ecd3550ee405add6 Mon Sep 17 00:00:00 2001 From: EricXu-0805 Date: Mon, 11 May 2026 11:32:57 -0500 Subject: [PATCH 01/51] fix(skill-check): honor primary host skipSkills in Templates check MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit When `hosts/claude.ts` has `generation.skipSkills: ['claude']` (the existing config — the /claude outside-voice skill is intentionally for non-Claude hosts), `bun run gen:skill-docs` correctly skips generating `claude/SKILL.md`. But `scripts/skill-check.ts` Templates section still flags it as `❌ generated file missing!` and the script exits 1. Fix: mirror the same `skipSkills` filter that `gen-skill-docs.ts` already uses (see `scripts/gen-skill-docs.ts:510-516`). Read the primary host's skipSkills once, then in the Templates loop, if the output file is missing AND the skill dir is in skipSkills, log it as `- skipped per host config` and skip the error flag instead of marking it missing. Impact: `bun run skill:check` now exits 0 for any host config that uses `skipSkills`. No behavior change when skipSkills is empty (default for most hosts) or when the skipped skill's output is in fact missing for some other reason. Test plan: configure `skipSkills: ['claude']` (default `hosts/claude.ts`), run `bun run gen:skill-docs`, confirm `claude/SKILL.md` is not generated, then `bun run skill:check` — before the patch, exit=1 with `❌ claude/SKILL.md — generated file missing!`; after the patch, exit=0 with `- claude/SKILL.md — skipped per claude host config`. --- scripts/skill-check.ts | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/scripts/skill-check.ts b/scripts/skill-check.ts index 9182737ee1..11b3ab4fd5 100644 --- a/scripts/skill-check.ts +++ b/scripts/skill-check.ts @@ -10,6 +10,7 @@ import { validateSkill } from '../test/helpers/skill-parser'; import { discoverTemplates, discoverSkillFiles } from './discover-skills'; +import { claude as PRIMARY_HOST } from '../hosts/index'; import * as fs from 'fs'; import * as path from 'path'; import { execSync } from 'child_process'; @@ -64,15 +65,25 @@ for (const file of SKILL_FILES) { console.log('\n Templates:'); const TEMPLATES = discoverTemplates(ROOT); +// Repo-root SKILL.md outputs reflect what the primary host (claude) generates. +// If a skill is in claude's skipSkills (e.g. the `/claude` outside-voice skill +// is intentionally not bundled into the Claude host), its generated file is +// expected to be absent — flagging it as missing here is a false positive. +const PRIMARY_SKIP_SKILLS = new Set(PRIMARY_HOST.generation?.skipSkills ?? []); for (const { tmpl, output } of TEMPLATES) { const tmplPath = path.join(ROOT, tmpl); const outPath = path.join(ROOT, output); + const skillDir = output.includes('/') ? output.split('/')[0] : ''; if (!fs.existsSync(tmplPath)) { console.log(` \u26a0\ufe0f ${output.padEnd(30)} — no template`); continue; } if (!fs.existsSync(outPath)) { + if (skillDir && PRIMARY_SKIP_SKILLS.has(skillDir)) { + console.log(` - ${output.padEnd(30)} — skipped per ${PRIMARY_HOST.name} host config`); + continue; + } hasErrors = true; console.log(` \u274c ${output.padEnd(30)} — generated file missing! Run: bun run gen:skill-docs`); continue; From 2d19016c3a5f3ba53d9f60510d843ce60cab8e7c Mon Sep 17 00:00:00 2001 From: Daniel Nascimento Date: Fri, 3 Jul 2026 11:28:00 -0300 Subject: [PATCH 02/51] fix(hooks): don't emit permissionDecision 'defer' from question-preference-hook MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 'defer' is a real permissionDecision value in Claude Code, but it means 'pause this tool call and hand control back' and is honored in print/non-interactive mode (interactive mode warns and ignores it). The hook emitted it as its 'no opinion' outcome, which made every AskUserQuestion call get deferred in non-interactive sessions (e.g. the Claude Code desktop app): the question UI never rendered and AUQ appeared completely broken after gstack setup registered the hook. The neutral outcome for a PreToolUse hook is a silent exit 0 — so defer() now emits nothing, or only additionalContext (without any permissionDecision) when there is plan-tune memory context to inject. Co-Authored-By: Claude Fable 5 --- .../claude/hooks/question-preference-hook.ts | 23 ++++++++++++++----- test/memory-cache-injection.test.ts | 6 ++--- test/question-preference-hook.test.ts | 20 ++++++++-------- test/skill-e2e-plan-tune-cathedral.test.ts | 2 +- 4 files changed, 31 insertions(+), 20 deletions(-) diff --git a/hosts/claude/hooks/question-preference-hook.ts b/hosts/claude/hooks/question-preference-hook.ts index 12cbd5ea28..adcad88faf 100644 --- a/hosts/claude/hooks/question-preference-hook.ts +++ b/hosts/claude/hooks/question-preference-hook.ts @@ -93,12 +93,23 @@ function readStdin(): Promise { } function defer(additionalContext?: string): void { - const out: Record = { - hookEventName: 'PreToolUse', - permissionDecision: 'defer', - }; - if (additionalContext) out.additionalContext = additionalContext; - process.stdout.write(JSON.stringify({ hookSpecificOutput: out })); + // "No opinion" must be a SILENT exit 0 (optionally with additionalContext + // only), never an explicit `permissionDecision: 'defer'`. `defer` is a real + // value in Claude Code, but it means "pause this tool call and hand control + // back" and is honored in print/non-interactive mode. Emitting it here made + // every AskUserQuestion get deferred in non-interactive sessions (e.g. the + // desktop app) — the question UI never rendered. Interactive mode merely + // warns and ignores it. + if (additionalContext) { + process.stdout.write( + JSON.stringify({ + hookSpecificOutput: { + hookEventName: 'PreToolUse', + additionalContext, + }, + }), + ); + } process.exit(0); } diff --git a/test/memory-cache-injection.test.ts b/test/memory-cache-injection.test.ts index 3ab6a2144a..4f8a3b68a7 100644 --- a/test/memory-cache-injection.test.ts +++ b/test/memory-cache-injection.test.ts @@ -91,7 +91,7 @@ describe('memory injection', () => { ], }, }); - expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBe('defer'); + expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBeUndefined(); expect(r.parsed?.hookSpecificOutput?.additionalContext).toContain('verbose explanations'); }); @@ -115,7 +115,7 @@ describe('memory injection', () => { ], }, }); - expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBe('defer'); + expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBeUndefined(); expect(r.parsed?.hookSpecificOutput?.additionalContext).toBeUndefined(); }); @@ -219,7 +219,7 @@ describe('per-session memory cache', () => { ], }, }); - expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBe('defer'); + expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBeUndefined(); expect(r.parsed?.hookSpecificOutput?.additionalContext).toBeUndefined(); }); }); diff --git a/test/question-preference-hook.test.ts b/test/question-preference-hook.test.ts index 39de02f4e8..c104f44940 100644 --- a/test/question-preference-hook.test.ts +++ b/test/question-preference-hook.test.ts @@ -126,7 +126,7 @@ describe('defers (no enforcement)', () => { }, }); expect(r.status).toBe(0); - expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBe('defer'); + expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBeUndefined(); }); test('marker missing → defer (D18)', () => { @@ -141,7 +141,7 @@ describe('defers (no enforcement)', () => { ], }, }); - expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBe('defer'); + expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBeUndefined(); }); test('always-ask preference → defer', () => { @@ -156,7 +156,7 @@ describe('defers (no enforcement)', () => { ], }, }); - expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBe('defer'); + expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBeUndefined(); }); test('empty stdin → defer (crash safety)', () => { @@ -168,13 +168,13 @@ describe('defers (no enforcement)', () => { const res = spawnSync(HOOK, [], { env, input: '', encoding: 'utf-8' }); expect(res.status).toBe(0); const parsed = JSON.parse(res.stdout || '{}'); - expect(parsed.hookSpecificOutput?.permissionDecision).toBe('defer'); + expect(parsed.hookSpecificOutput?.permissionDecision).toBeUndefined(); }); test('non-AUQ tool_name → defer (defensive)', () => { writeProjectPref('test-q', 'never-ask'); const r = runHook({ session_id: 's4', tool_name: 'Bash', tool_use_id: 'tu-4', tool_input: {} }); - expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBe('defer'); + expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBeUndefined(); }); }); @@ -219,7 +219,7 @@ describe('enforces never-ask preferences', () => { ], }, }); - expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBe('defer'); + expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBeUndefined(); }); test('ambiguous recommendation (two labels) → defer (D2 refuse-on-ambiguous)', () => { @@ -237,7 +237,7 @@ describe('enforces never-ask preferences', () => { ], }, }); - expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBe('defer'); + expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBeUndefined(); }); test('no recommendation marker AND no prose match → defer', () => { @@ -255,7 +255,7 @@ describe('enforces never-ask preferences', () => { ], }, }); - expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBe('defer'); + expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBeUndefined(); }); }); @@ -317,7 +317,7 @@ describe('precedence: project wins over global (D8)', () => { ], }, }); - expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBe('defer'); + expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBeUndefined(); }); }); @@ -443,7 +443,7 @@ describe('Conductor prose redirect', () => { undefined, CONDUCTOR, ); - expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBe('defer'); + expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBeUndefined(); }); }); diff --git a/test/skill-e2e-plan-tune-cathedral.test.ts b/test/skill-e2e-plan-tune-cathedral.test.ts index f9c006914e..e07eb70fa1 100644 --- a/test/skill-e2e-plan-tune-cathedral.test.ts +++ b/test/skill-e2e-plan-tune-cathedral.test.ts @@ -296,7 +296,7 @@ describeIfSelected('PlanTune cathedral E2E: annotation', ['plan-tune-annotation' }); expect(res.status).toBe(0); const parsed = JSON.parse(res.stdout || '{}'); - expect(parsed.hookSpecificOutput?.permissionDecision).toBe('defer'); + expect(parsed.hookSpecificOutput?.permissionDecision).toBeUndefined(); expect(parsed.hookSpecificOutput?.additionalContext).toContain('verbose explanations'); }); }); From e15e89792bf58f9e0126894fb7deae8fa124a11e Mon Sep 17 00:00:00 2001 From: kalpajit279 Date: Mon, 13 Jul 2026 13:03:57 -0700 Subject: [PATCH 03/51] fix: pre-empt broken AskUserQuestion on the Claude Desktop host Cherry-picked from community PR #2146. [wave adaptation: the new non-AUQ desktop test asserted the 'defer' permissionDecision that PR #2165 (applied just before this) removed; updated to toBeUndefined() to match the pass-through contract.] Co-Authored-By: Claude Fable 5 --- .../claude/hooks/question-preference-hook.ts | 30 ++++--- test/memory-cache-injection.test.ts | 6 +- test/question-preference-hook.test.ts | 87 +++++++++++++++++-- 3 files changed, 106 insertions(+), 17 deletions(-) diff --git a/hosts/claude/hooks/question-preference-hook.ts b/hosts/claude/hooks/question-preference-hook.ts index adcad88faf..2654438579 100644 --- a/hosts/claude/hooks/question-preference-hook.ts +++ b/hosts/claude/hooks/question-preference-hook.ts @@ -462,15 +462,25 @@ async function main(): Promise { return; } - // Not fully auto-decidable. In Conductor, AskUserQuestion is unreliable - // (native is disabled, the mcp__conductor__AskUserQuestion variant is flaky), - // so deny the tool and redirect to a prose decision brief. This is TRANSPORT - // AVOIDANCE, not preference enforcement: it fires regardless of marker, - // preference, or door type — including one-way doors, which must reach the - // human via prose rather than the unreliable tool. - if (isConductor()) { - const conductorReason = - '[conductor] AskUserQuestion is unreliable in Conductor (native disabled, MCP variant flaky). ' + + // Not fully auto-decidable. On some hosts AskUserQuestion is unreliable and + // must be avoided entirely: + // - Conductor: native AUQ is disabled and the mcp__conductor__AskUserQuestion + // variant is flaky. + // - Claude Desktop app (CLAUDE_CODE_ENTRYPOINT=claude-desktop): the tool is + // advertised + enabled (CLAUDE_CODE_ENABLE_ASK_USER_QUESTION_TOOL=true) but + // its handler returns "[Tool result missing due to internal error]" — a host + // bug verified 2026-07-01 on claude.exe 2.1.197. Critically, PostToolUse + // hooks do NOT fire on that transport-error path, so auq-error-fallback-hook + // can't rescue it after the fact; it must be pre-empted here in PreToolUse. + // On those hosts, deny the tool and redirect to a prose decision brief. This is + // TRANSPORT AVOIDANCE, not preference enforcement: it fires regardless of + // marker, preference, or door type — including one-way doors, which must reach + // the human via prose rather than the unreliable tool. + const isClaudeDesktop = (process.env.CLAUDE_CODE_ENTRYPOINT || '') === 'claude-desktop'; + if (isConductor() || isClaudeDesktop) { + const host = isConductor() ? 'conductor' : 'claude-desktop'; + const unreliableReason = + `[${host}] AskUserQuestion is unreliable in this host (missing-result / transport error). ` + 'Do NOT call AskUserQuestion (native or any mcp__*__AskUserQuestion). Render this decision as a ' + 'PROSE decision brief now: a D label, an ELI10 of the issue, a Recommendation line, then one ' + 'paragraph per choice carrying its `(recommended)` marker and `Completeness: X/10`; tell the user ' + @@ -478,7 +488,7 @@ async function main(): Promise { 'typed confirmation and do NOT proceed on a vague reply. Capture the decision with gstack-question-log ' + '(PostToolUse will not fire on a prose path).' + (memoryContext ? `\n${memoryContext}` : ''); - deny(conductorReason); + deny(unreliableReason); return; } diff --git a/test/memory-cache-injection.test.ts b/test/memory-cache-injection.test.ts index 4f8a3b68a7..3d59678f20 100644 --- a/test/memory-cache-injection.test.ts +++ b/test/memory-cache-injection.test.ts @@ -44,10 +44,12 @@ function runHook(stdin: object): { stdout: string; stderr: string; status: numbe env.GSTACK_QUESTION_LOG_NO_DERIVE = '1'; delete env.GSTACK_HOME; // These cases assert the defer-path memoryContext injection. Strip ambient - // Conductor markers so running inside Conductor (CONDUCTOR_WORKSPACE_PATH/PORT - // set) doesn't flip the hook into the [conductor] prose deny instead of defer. + // host markers so running inside Conductor (CONDUCTOR_WORKSPACE_PATH/PORT set) + // or the Claude Desktop app (CLAUDE_CODE_ENTRYPOINT=claude-desktop) doesn't flip + // the hook into the prose deny instead of defer. delete env.CONDUCTOR_WORKSPACE_PATH; delete env.CONDUCTOR_PORT; + delete env.CLAUDE_CODE_ENTRYPOINT; const res = spawnSync(HOOK, [], { env, input: JSON.stringify({ ...stdin, cwd: fixtureCwd }), diff --git a/test/question-preference-hook.test.ts b/test/question-preference-hook.test.ts index c104f44940..9194a6f3df 100644 --- a/test/question-preference-hook.test.ts +++ b/test/question-preference-hook.test.ts @@ -72,13 +72,15 @@ function runHook(stdin: object, cwd?: string, extraEnv?: Record) } env.GSTACK_STATE_ROOT = stateRoot; delete env.GSTACK_HOME; - // Strip ambient Conductor markers so these cases characterize NON-Conductor - // behavior deterministically — otherwise running the suite inside Conductor - // (CONDUCTOR_WORKSPACE_PATH/PORT set) would flip every defer into the - // [conductor] prose deny. The Conductor cases below opt back in explicitly - // via extraEnv. + // Strip ambient host markers so these cases characterize the plain + // (non-transport-avoidance) behavior deterministically — otherwise running the + // suite inside Conductor (CONDUCTOR_WORKSPACE_PATH/PORT set) or the Claude + // Desktop app (CLAUDE_CODE_ENTRYPOINT=claude-desktop) would flip every defer + // into the prose deny. The transport-avoidance cases below opt back in + // explicitly via extraEnv. delete env.CONDUCTOR_WORKSPACE_PATH; delete env.CONDUCTOR_PORT; + delete env.CLAUDE_CODE_ENTRYPOINT; env.GSTACK_QUESTION_LOG_NO_DERIVE = '1'; if (extraEnv) Object.assign(env, extraEnv); const res = spawnSync(HOOK, [], { @@ -447,6 +449,81 @@ describe('Conductor prose redirect', () => { }); }); +// ---------------------------------------------------------------------- +// Claude Desktop app: deny + prose redirect (same transport avoidance as +// Conductor — CLAUDE_CODE_ENTRYPOINT=claude-desktop; AUQ handler returns a +// missing-result internal error, and PostToolUse can't rescue it) +// ---------------------------------------------------------------------- + +describe('Claude Desktop prose redirect', () => { + const DESKTOP = { CLAUDE_CODE_ENTRYPOINT: 'claude-desktop' }; + + test('two-way, no preference → deny with [claude-desktop] prose directive', () => { + const r = runHook({ + session_id: 'd1', + tool_name: 'AskUserQuestion', + tool_use_id: 'tu-d1', + tool_input: { + questions: [ + { question: ' Need approval?', options: ['A) Yes (recommended)', 'B) No'] }, + ], + }, + }, undefined, DESKTOP); + expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBe('deny'); + expect(r.parsed?.hookSpecificOutput?.permissionDecisionReason).toContain('[claude-desktop]'); + expect(r.parsed?.hookSpecificOutput?.permissionDecisionReason).toMatch(/do not call askuserquestion/i); + expect(r.parsed?.hookSpecificOutput?.permissionDecisionReason).toMatch(/reply with a letter/i); + }); + + test('one-way door → deny (destructive must reach human via prose, not the broken tool)', () => { + const r = runHook({ + session_id: 'd2', + tool_name: 'AskUserQuestion', + tool_use_id: 'tu-d2', + tool_input: { + questions: [ + { + question: ' Tests failed.', + options: ['A) Fix now (recommended)', 'B) Investigate', 'C) Ack and ship'], + }, + ], + }, + }, undefined, DESKTOP); + expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBe('deny'); + expect(r.parsed?.hookSpecificOutput?.permissionDecisionReason).toContain('[claude-desktop]'); + expect(r.parsed?.hookSpecificOutput?.permissionDecisionReason).toMatch(/typed confirmation/i); + }); + + test('full never-ask auto-decide still wins over the desktop prose redirect', () => { + writeProjectPref('ship-pre-landing-review-fix', 'never-ask'); + const r = runHook({ + session_id: 'd3', + tool_name: 'AskUserQuestion', + tool_use_id: 'tu-d3', + tool_input: { + questions: [ + { + question: ' Pre-landing review flagged issue.', + options: ['A) Fix now (recommended)', 'B) Skip'], + }, + ], + }, + }, undefined, DESKTOP); + expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBe('deny'); + expect(r.parsed?.hookSpecificOutput?.permissionDecisionReason).toContain('plan-tune auto-decide'); + expect(r.parsed?.hookSpecificOutput?.permissionDecisionReason).not.toContain('[claude-desktop]'); + }); + + test('non-AUQ tool on desktop → pass through (no redirect on unrelated tools)', () => { + const r = runHook( + { session_id: 'd4', tool_name: 'Bash', tool_use_id: 'tu-d4', tool_input: {} }, + undefined, + DESKTOP, + ); + expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBeUndefined(); + }); +}); + // ---------------------------------------------------------------------- // Auto-decided event logging (since PostToolUse never fires on deny) // ---------------------------------------------------------------------- From f36fe815bb2b81d4e28f6b68927da95155911f8e Mon Sep 17 00:00:00 2001 From: Zachary Townsend Date: Mon, 13 Jul 2026 13:05:03 -0700 Subject: [PATCH 04/51] docs+test: correct hook spike's 'defer' contract, add empty-stdout AUQ regression test Salvaged from community PR #1816 (its hook fix was superseded by #2165, but its spike-doc correction and empty-stdout regression test are unique): the spike still documented "defer" as a valid permissionDecision value; the real contract is allow/deny/ask only, with pass-through expressed as no permissionDecision at all. Co-Authored-By: Claude Fable 5 --- docs/spikes/claude-code-hook-mutation.md | 23 ++++++++++++++++++++--- test/question-preference-hook.test.ts | 22 ++++++++++++++++++++++ 2 files changed, 42 insertions(+), 3 deletions(-) diff --git a/docs/spikes/claude-code-hook-mutation.md b/docs/spikes/claude-code-hook-mutation.md index 9d91e16cd4..e58f378f91 100644 --- a/docs/spikes/claude-code-hook-mutation.md +++ b/docs/spikes/claude-code-hook-mutation.md @@ -51,7 +51,18 @@ Optional in subagent context: `agent_id`, `agent_type`. - `"deny"` — block (feedback to Claude, NOT a synthetic answer per Codex correction in D-prefixed decisions) - `"ask"` — escalate to user -- `"defer"` — let permission flow continue + +> ⚠️ **There is no `"defer"` permissionDecision value.** The spec defines only +> `allow` / `deny` / `ask`. To express "no opinion — let the tool run and +> permission flow continue", emit **no `permissionDecision`** (an empty +> `hookSpecificOutput`, or no stdout at all). Earlier revisions of this spike +> and the hook emitted `permissionDecision: "defer"`; native Claude Code +> silently ignored the unknown value and fell through, so it appeared to work. +> **Conductor's `mcp__conductor__AskUserQuestion` bridge does not ignore it** — +> an unrecognized permissionDecision on its own injected tool hangs the +> round-trip, so the question never renders and no `tool_result` is returned. +> Always use the no-permissionDecision shape for pass-through. See the +> pass-through example below. **`updatedInput` semantics:** shallow merge of fields present in the returned object onto the original `tool_input`. Only valid with @@ -88,7 +99,8 @@ required for our hook to fire there. accepting. **`permissionDecision` precedence (when multiple hooks decide):** -`deny > ask > allow > defer` — most restrictive wins. +`deny > ask > allow > (no decision)` — most restrictive wins; a hook that +emits no `permissionDecision` defers to whatever the others decide. ## Implementation hookSpecificOutput examples @@ -107,11 +119,16 @@ required for our hook to fire there. ``` **Pass-through (no preference, or one-way safety override):** + +Emit **no `permissionDecision`** — surface `additionalContext` if there is any, +otherwise emit nothing at all (empty stdout + exit 0). Do NOT emit +`permissionDecision: "defer"` (not a real value; breaks Conductor's AUQ bridge). + ```json { "hookSpecificOutput": { "hookEventName": "PreToolUse", - "permissionDecision": "defer" + "additionalContext": "optional plan-tune memory context" } } ``` diff --git a/test/question-preference-hook.test.ts b/test/question-preference-hook.test.ts index 9194a6f3df..1b8c425f82 100644 --- a/test/question-preference-hook.test.ts +++ b/test/question-preference-hook.test.ts @@ -178,6 +178,28 @@ describe('defers (no enforcement)', () => { const r = runHook({ session_id: 's4', tool_name: 'Bash', tool_use_id: 'tu-4', tool_input: {} }); expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBeUndefined(); }); + + // Regression: the defer path must NOT emit any permissionDecision. The Claude + // Code spec only defines allow/deny/ask; the old code emitted a bogus + // "defer" value, which native Claude Code ignored but Conductor's + // mcp__conductor__AskUserQuestion bridge could not handle — it hung the + // round-trip so the question never rendered and no tool_result came back. + // A plain ordinary question (no marker) must therefore produce empty stdout. + test('ordinary question (no marker) → empty stdout, no permissionDecision (Conductor AUQ bridge regression)', () => { + const r = runHook({ + session_id: 's-conductor', + tool_name: 'mcp__conductor__AskUserQuestion', + tool_use_id: 'tu-conductor', + tool_input: { + questions: [ + { question: 'Which option do you prefer?', options: ['A) One', 'B) Two'] }, + ], + }, + }); + expect(r.status).toBe(0); + expect(r.stdout).toBe(''); + expect(r.stdout).not.toContain('permissionDecision'); + }); }); // ---------------------------------------------------------------------- From f7c7feb79b3aa552192de8b44177b5a119ea8378 Mon Sep 17 00:00:00 2001 From: neallee Date: Fri, 10 Jul 2026 19:56:31 +0800 Subject: [PATCH 05/51] fix: make team hook launcher cross-platform Generate one Node CommonJS enforcement hook, fail closed when project context or the global install cannot be verified, and cover cmd and PowerShell execution paths. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- README.md | 2 +- bin/gstack-team-init | 106 +++++++++++----- test/team-mode.test.ts | 274 ++++++++++++++++++++++++++++++++++++++--- 3 files changed, 334 insertions(+), 48 deletions(-) diff --git a/README.md b/README.md index 4bb177c3a7..8233848d68 100644 --- a/README.md +++ b/README.md @@ -58,7 +58,7 @@ From inside your repo, paste this. Switches you to team mode, bootstraps the rep (cd ~/.claude/skills/gstack && ./setup --team) && ~/.claude/skills/gstack/bin/gstack-team-init required && git add .claude/ CLAUDE.md && git commit -m "require gstack for AI-assisted work" ``` -No vendored files in your repo, no version drift, no manual upgrades. Every Claude Code session starts with a fast auto-update check (throttled to once/hour, network-failure-safe, completely silent). +No vendored gstack install in your repo, no version drift, no manual upgrades. Required mode commits one Node 18+ CommonJS enforcement hook, so the same project hook works from POSIX and Windows hook runners without duplicate shell-specific handlers. If the hook runner omits its project directory, enforcement fails closed with an intentional denial instead of a hook error. Every Claude Code session starts with a fast auto-update check (throttled to once/hour, network-failure-safe, completely silent). Swap `required` for `optional` if you'd rather nudge teammates than block them. diff --git a/bin/gstack-team-init b/bin/gstack-team-init index 256735f8b4..74cd5af5d7 100755 --- a/bin/gstack-team-init +++ b/bin/gstack-team-init @@ -65,12 +65,13 @@ cd ~/.claude/skills/gstack && ./setup --team Skills like /qa, /ship, /review, /investigate, and /browse become available after install. Use /browse for all web browsing. Use ~/.claude/skills/gstack/... for gstack file paths.' else - SNIPPET='## gstack (REQUIRED — global install) + SNIPPET=$(cat <<'SNIPPET_EOF' +## gstack (REQUIRED — global install) **Before doing ANY work, verify gstack is installed:** -```bash -test -d ~/.claude/skills/gstack/bin && echo "GSTACK_OK" || echo "GSTACK_MISSING" +``` +node -e "const fs=require('node:fs'),os=require('node:os'),p=require('node:path'); console.log(fs.existsSync(p.join(os.homedir(),'.claude','skills','gstack','bin')) ? 'GSTACK_OK' : 'GSTACK_MISSING')" ``` If GSTACK_MISSING: STOP. Do not proceed. Tell the user: @@ -87,7 +88,9 @@ Do not skip skills, ignore gstack errors, or work around missing gstack. Using gstack skills: After install, skills like /qa, /ship, /review, /investigate, and /browse are available. Use /browse for all web browsing. -Use ~/.claude/skills/gstack/... for gstack file paths (the global path).' +Use ~/.claude/skills/gstack/... for gstack file paths (the global path). +SNIPPET_EOF +) fi # Check if CLAUDE.md already has a gstack section @@ -109,33 +112,60 @@ if [ "$MODE" = "required" ]; then HOOKS_DIR="$REPO_ROOT/.claude/hooks" SETTINGS="$REPO_ROOT/.claude/settings.json" - # Create enforcement hook script + # Create a CommonJS hook so consumer package.json module settings cannot change + # how Node 18+ loads it. mkdir -p "$HOOKS_DIR" - cat > "$HOOKS_DIR/check-gstack.sh" << 'HOOK_EOF' -#!/bin/bash -# Block skill usage when gstack is not installed globally. - -if [ ! -d "$HOME/.claude/skills/gstack/bin" ]; then - cat >&2 <<'MSG' -BLOCKED: gstack is not installed globally. - -gstack is required for AI-assisted work in this repo. + cat > "$HOOKS_DIR/check-gstack.cjs" << 'HOOK_EOF' +'use strict'; + +// Block skill usage when gstack is not installed globally. +const fs = require('node:fs'); +const os = require('node:os'); +const path = require('node:path'); + +const homeDir = process.env.HOME || process.env.USERPROFILE || os.homedir(); +const gstackBin = path.join(homeDir, '.claude', 'skills', 'gstack', 'bin'); +let verificationError = null; +let installed = false; + +try { + installed = fs.statSync(gstackBin).isDirectory(); +} catch (error) { + if (error && error.code !== 'ENOENT') { + verificationError = error; + } +} + +if (installed) { + process.stdout.write('{}\n'); +} else { + const projectDir = process.env.CLAUDE_PROJECT_DIR || '(unknown project)'; + const heading = verificationError + ? 'BLOCKED: the global gstack install could not be verified.' + : 'BLOCKED: gstack is not installed globally.'; + const instructions = `${heading} + +gstack is required for AI-assisted work in ${projectDir}. Install it: git clone --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack cd ~/.claude/skills/gstack && ./setup --team Then restart your AI coding tool. -MSG - echo '{"permissionDecision":"deny","message":"gstack is required but not installed. See stderr for install instructions."}' - exit 0 -fi - -echo '{}' +`; + + process.stderr.write(instructions); + process.stdout.write(`${JSON.stringify({ + hookSpecificOutput: { + hookEventName: 'PreToolUse', + permissionDecision: 'deny', + permissionDecisionReason: instructions, + }, + })}\n`); +} HOOK_EOF - chmod +x "$HOOKS_DIR/check-gstack.sh" - GENERATED+=(".claude/hooks/check-gstack.sh") - echo " + .claude/hooks/check-gstack.sh — enforcement hook" + GENERATED+=(".claude/hooks/check-gstack.cjs") + echo " + .claude/hooks/check-gstack.cjs — cross-platform enforcement hook" # Add hook to project-level settings.json if command -v bun >/dev/null 2>&1; then @@ -149,18 +179,32 @@ HOOK_EOF if (!settings.hooks) settings.hooks = {}; if (!settings.hooks.PreToolUse) settings.hooks.PreToolUse = []; - // Dedup - const exists = settings.hooks.PreToolUse.some(entry => - entry.matcher === 'Skill' && - entry.hooks && entry.hooks.some(h => h.command && h.command.includes('check-gstack')) - ); - - if (!exists) { + const hookCommand = \"node -e \\\"const projectDir=process.env.CLAUDE_PROJECT_DIR;if(!projectDir){const reason='BLOCKED: CLAUDE_PROJECT_DIR is unavailable, so the required gstack hook cannot be loaded.';console.error(reason);console.log(JSON.stringify({hookSpecificOutput:{hookEventName:'PreToolUse',permissionDecision:'deny',permissionDecisionReason:reason}}))}else{require(require('node:path').join(projectDir, '.claude', 'hooks', 'check-gstack.cjs'))}\\\"\"; + let found = false; + settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(entry => { + if (entry.matcher !== 'Skill' || !entry.hooks) return true; + + const matchingHooks = entry.hooks.filter( + h => h.command && h.command.includes('check-gstack') + ); + if (matchingHooks.length === 0) return true; + + entry.hooks = entry.hooks.filter( + h => !h.command || !h.command.includes('check-gstack') + ); + if (!found) { + entry.hooks.push({ type: 'command', command: hookCommand }); + found = true; + } + return entry.hooks.length > 0; + }); + + if (!found) { settings.hooks.PreToolUse.push({ matcher: 'Skill', hooks: [{ type: 'command', - command: '\"\$CLAUDE_PROJECT_DIR/.claude/hooks/check-gstack.sh\"' + command: hookCommand }] }); } diff --git a/test/team-mode.test.ts b/test/team-mode.test.ts index ce8c1d6107..a17fb6938f 100644 --- a/test/team-mode.test.ts +++ b/test/team-mode.test.ts @@ -2,12 +2,17 @@ import { describe, test, expect, beforeEach, afterEach } from 'bun:test'; import * as fs from 'fs'; import * as path from 'path'; import * as os from 'os'; -import { execSync } from 'child_process'; +import { execSync, spawnSync } from 'child_process'; const ROOT = path.resolve(import.meta.dir, '..'); -const SETTINGS_HOOK = path.join(ROOT, 'bin', 'gstack-settings-hook'); -const SESSION_UPDATE = path.join(ROOT, 'bin', 'gstack-session-update'); -const TEAM_INIT = path.join(ROOT, 'bin', 'gstack-team-init'); + +function bashCommand(filePath: string): string { + return `bash "${filePath.replace(/\\/g, '/')}"`; +} + +const SETTINGS_HOOK = bashCommand(path.join(ROOT, 'bin', 'gstack-settings-hook')); +const SESSION_UPDATE = bashCommand(path.join(ROOT, 'bin', 'gstack-session-update')); +const TEAM_INIT = bashCommand(path.join(ROOT, 'bin', 'gstack-team-init')); function mkTmpDir(): string { return fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-team-test-')); @@ -17,7 +22,11 @@ function run(cmd: string, opts: { cwd?: string; env?: Record } = try { const stdout = execSync(cmd, { cwd: opts.cwd, - env: { ...process.env, ...opts.env }, + env: { + ...process.env, + ...(process.platform === 'win32' ? { MSYS_NO_PATHCONV: '1' } : {}), + ...opts.env, + }, encoding: 'utf-8', timeout: 10000, }); @@ -27,6 +36,47 @@ function run(cmd: string, opts: { cwd?: string; env?: Record } = } } +function runHook( + command: string, + opts: { cwd: string; env: Record }, +): { stdout: string; stderr: string; exitCode: number } { + const result = spawnSync(command, { + cwd: opts.cwd, + env: { ...process.env, ...opts.env }, + encoding: 'utf-8', + shell: true, + timeout: 10000, + }); + + return { + stdout: result.stdout || '', + stderr: result.stderr || '', + exitCode: result.status ?? 1, + }; +} + +function runHookInPowerShell( + command: string, + opts: { cwd: string; env: Record }, +): { stdout: string; stderr: string; exitCode: number } { + const result = spawnSync( + 'powershell.exe', + ['-NoProfile', '-NonInteractive', '-Command', command], + { + cwd: opts.cwd, + env: { ...process.env, ...opts.env }, + encoding: 'utf-8', + timeout: 10000, + }, + ); + + return { + stdout: result.stdout || '', + stderr: result.stderr || '', + exitCode: result.status ?? 1, + }; +} + describe('gstack-settings-hook', () => { let tmpDir: string; let settingsFile: string; @@ -227,27 +277,216 @@ describe('gstack-team-init', () => { const claude = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8'); expect(claude).toContain('## gstack (REQUIRED'); expect(claude).toContain('GSTACK_MISSING'); + expect(claude).toContain("require('node:os')"); + expect(claude).not.toContain('test -d ~/.claude/skills/gstack/bin'); }); test('required: creates enforcement hook', () => { run(`${TEAM_INIT} required`, { cwd: tmpDir }); - const hookPath = path.join(tmpDir, '.claude', 'hooks', 'check-gstack.sh'); + const hookPath = path.join(tmpDir, '.claude', 'hooks', 'check-gstack.cjs'); expect(fs.existsSync(hookPath)).toBe(true); + expect( + fs.existsSync(path.join(tmpDir, '.claude', 'hooks', 'check-gstack.sh')), + ).toBe(false); const hook = fs.readFileSync(hookPath, 'utf-8'); + expect(hook).toContain("'use strict'"); + expect(hook).toContain("require('node:fs')"); + expect(hook).toContain( + 'process.env.HOME || process.env.USERPROFILE || os.homedir()', + ); + expect(hook).toContain('process.env.CLAUDE_PROJECT_DIR'); + expect(hook).toContain("hookEventName: 'PreToolUse'"); + expect(hook).toContain("permissionDecision: 'deny'"); expect(hook).toContain('BLOCKED: gstack is not installed'); - // Should be executable - const stat = fs.statSync(hookPath); - expect(stat.mode & 0o111).toBeGreaterThan(0); + expect(hook).not.toContain('#!/bin/bash'); }); - test('required: creates project settings.json with PreToolUse hook', () => { + test('required: registers one shell-neutral project hook', () => { run(`${TEAM_INIT} required`, { cwd: tmpDir }); const settingsPath = path.join(tmpDir, '.claude', 'settings.json'); expect(fs.existsSync(settingsPath)).toBe(true); const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8')); expect(settings.hooks.PreToolUse).toHaveLength(1); - expect(settings.hooks.PreToolUse[0].matcher).toBe('Skill'); - expect(settings.hooks.PreToolUse[0].hooks[0].command).toContain('check-gstack'); + const entry = settings.hooks.PreToolUse[0]; + expect(entry.matcher).toBe('Skill'); + expect(entry.hooks).toHaveLength(1); + expect(entry.hooks[0]).not.toHaveProperty('shell'); + expect(entry.hooks[0].command).toBe( + `node -e "const projectDir=process.env.CLAUDE_PROJECT_DIR;if(!projectDir){const reason='BLOCKED: CLAUDE_PROJECT_DIR is unavailable, so the required gstack hook cannot be loaded.';console.error(reason);console.log(JSON.stringify({hookSpecificOutput:{hookEventName:'PreToolUse',permissionDecision:'deny',permissionDecisionReason:reason}}))}else{require(require('node:path').join(projectDir, '.claude', 'hooks', 'check-gstack.cjs'))}"`, + ); + expect(entry.hooks[0].command).not.toMatch( + /\$CLAUDE_PROJECT_DIR|\$env:CLAUDE_PROJECT_DIR|%CLAUDE_PROJECT_DIR%/, + ); + expect(entry.hooks[0].command).not.toContain("permissionDecision:'allow'"); + }); + + test('required: hook allows with valid empty JSON when gstack is installed', () => { + run(`${TEAM_INIT} required`, { cwd: tmpDir }); + const settings = JSON.parse( + fs.readFileSync(path.join(tmpDir, '.claude', 'settings.json'), 'utf-8'), + ); + const command = settings.hooks.PreToolUse[0].hooks[0].command; + const fakeHome = path.join(tmpDir, 'home'); + const nestedCwd = path.join(tmpDir, 'nested', 'working', 'directory'); + fs.mkdirSync(path.join(fakeHome, '.claude', 'skills', 'gstack', 'bin'), { + recursive: true, + }); + fs.mkdirSync(nestedCwd, { recursive: true }); + + const result = runHook(command, { + cwd: nestedCwd, + env: { + CLAUDE_PROJECT_DIR: tmpDir, + HOME: fakeHome, + USERPROFILE: path.join(tmpDir, 'unused-userprofile'), + }, + }); + + expect(result.exitCode).toBe(0); + expect(result.stderr).toBe(''); + expect(JSON.parse(result.stdout)).toEqual({}); + }); + + test('required: missing project env denies through the platform default shell', () => { + run(`${TEAM_INIT} required`, { cwd: tmpDir }); + const settings = JSON.parse( + fs.readFileSync(path.join(tmpDir, '.claude', 'settings.json'), 'utf-8'), + ); + const command = settings.hooks.PreToolUse[0].hooks[0].command; + + const result = runHook(command, { + cwd: tmpDir, + env: { CLAUDE_PROJECT_DIR: '' }, + }); + + expect(result.exitCode).toBe(0); + expect(result.stderr).toContain('BLOCKED: CLAUDE_PROJECT_DIR is unavailable'); + expect(JSON.parse(result.stdout)).toEqual({ + hookSpecificOutput: { + hookEventName: 'PreToolUse', + permissionDecision: 'deny', + permissionDecisionReason: + 'BLOCKED: CLAUDE_PROJECT_DIR is unavailable, so the required gstack hook cannot be loaded.', + }, + }); + }); + + test('required: missing project env denies through PowerShell', () => { + if (process.platform !== 'win32') return; + + run(`${TEAM_INIT} required`, { cwd: tmpDir }); + const settings = JSON.parse( + fs.readFileSync(path.join(tmpDir, '.claude', 'settings.json'), 'utf-8'), + ); + const command = settings.hooks.PreToolUse[0].hooks[0].command; + + const result = runHookInPowerShell(command, { + cwd: tmpDir, + env: { CLAUDE_PROJECT_DIR: '' }, + }); + + expect(result.exitCode).toBe(0); + expect(result.stderr).toContain('BLOCKED: CLAUDE_PROJECT_DIR is unavailable'); + expect(JSON.parse(result.stdout)).toEqual({ + hookSpecificOutput: { + hookEventName: 'PreToolUse', + permissionDecision: 'deny', + permissionDecisionReason: + 'BLOCKED: CLAUDE_PROJECT_DIR is unavailable, so the required gstack hook cannot be loaded.', + }, + }); + }); + + test('required: hook runs in PowerShell with USERPROFILE home fallback', () => { + if (process.platform !== 'win32') return; + + run(`${TEAM_INIT} required`, { cwd: tmpDir }); + const settings = JSON.parse( + fs.readFileSync(path.join(tmpDir, '.claude', 'settings.json'), 'utf-8'), + ); + const command = settings.hooks.PreToolUse[0].hooks[0].command; + const fakeHome = path.join(tmpDir, 'powershell-home'); + fs.mkdirSync(path.join(fakeHome, '.claude', 'skills', 'gstack', 'bin'), { + recursive: true, + }); + + const result = runHookInPowerShell(command, { + cwd: tmpDir, + env: { + CLAUDE_PROJECT_DIR: tmpDir, + HOME: '', + USERPROFILE: fakeHome, + }, + }); + + expect(result.exitCode).toBe(0); + expect(result.stderr).toBe(''); + expect(JSON.parse(result.stdout)).toEqual({}); + }); + + test('required: missing gstack returns an intentional deny, not a hook error', () => { + run(`${TEAM_INIT} required`, { cwd: tmpDir }); + const settings = JSON.parse( + fs.readFileSync(path.join(tmpDir, '.claude', 'settings.json'), 'utf-8'), + ); + const command = settings.hooks.PreToolUse[0].hooks[0].command; + const fakeHome = path.join(tmpDir, 'home-without-gstack'); + fs.mkdirSync(fakeHome, { recursive: true }); + + const result = runHook(command, { + cwd: tmpDir, + env: { + CLAUDE_PROJECT_DIR: tmpDir, + HOME: fakeHome, + USERPROFILE: fakeHome, + }, + }); + + expect(result.exitCode).toBe(0); + expect(result.stderr).toContain('BLOCKED: gstack is not installed globally.'); + expect(result.stderr).toContain('git clone --depth 1'); + const decision = JSON.parse(result.stdout); + expect(decision).toEqual({ + hookSpecificOutput: { + hookEventName: 'PreToolUse', + permissionDecision: 'deny', + permissionDecisionReason: expect.stringContaining( + 'Then restart your AI coding tool.', + ), + }, + }); + }); + + test('required: rerun upgrades a legacy Bash hook without duplicates', () => { + const hooksDir = path.join(tmpDir, '.claude', 'hooks'); + fs.mkdirSync(hooksDir, { recursive: true }); + fs.writeFileSync(path.join(hooksDir, 'check-gstack.sh'), '#!/bin/bash\n'); + fs.writeFileSync( + path.join(tmpDir, '.claude', 'settings.json'), + JSON.stringify({ + hooks: { + PreToolUse: [ + { + matcher: 'Skill', + hooks: [{ + type: 'command', + command: '"$CLAUDE_PROJECT_DIR/.claude/hooks/check-gstack.sh"', + }], + }, + ], + }, + }), + ); + + run(`${TEAM_INIT} required`, { cwd: tmpDir }); + const settings = JSON.parse( + fs.readFileSync(path.join(tmpDir, '.claude', 'settings.json'), 'utf-8'), + ); + expect(settings.hooks.PreToolUse).toHaveLength(1); + expect(settings.hooks.PreToolUse[0].hooks).toHaveLength(1); + expect(settings.hooks.PreToolUse[0].hooks[0].command).toContain( + 'check-gstack.cjs', + ); }); test('idempotent: running twice does not duplicate CLAUDE.md section', () => { @@ -291,7 +530,11 @@ describe('gstack-team-init', () => { fs.mkdirSync(skillsDir, { recursive: true }); const targetDir = mkTmpDir(); fs.writeFileSync(path.join(targetDir, 'VERSION'), '0.14.0.0'); - fs.symlinkSync(targetDir, path.join(skillsDir, 'gstack')); + fs.symlinkSync( + targetDir, + path.join(skillsDir, 'gstack'), + process.platform === 'win32' ? 'junction' : 'dir', + ); const result = run(`${TEAM_INIT} optional`, { cwd: tmpDir }); expect(result.exitCode).toBe(0); @@ -329,7 +572,7 @@ describe('setup --team / --no-team / -q', () => { test( 'setup -q produces no stdout', () => { - const result = run(`${path.join(ROOT, 'setup')} -q`, { cwd: ROOT }); + const result = run(`${bashCommand(path.join(ROOT, 'setup'))} -q`, { cwd: ROOT }); // -q should suppress informational output (may still have some output from build) // The key test is that the "Skill naming:" prompt and "gstack ready" messages are suppressed expect(result.stdout).not.toContain('Skill naming:'); @@ -341,8 +584,7 @@ describe('setup --team / --no-team / -q', () => { test( 'setup --local prints deprecation warning', () => { - // stderr capture: run via bash redirect so we can capture stderr - const result = run(`bash -c '${path.join(ROOT, 'setup')} --local -q 2>&1'`, { cwd: ROOT }); + const result = run(`${bashCommand(path.join(ROOT, 'setup'))} --local -q 2>&1`, { cwd: ROOT }); expect(result.stdout).toContain('deprecated'); }, 180_000, From 74cb100a2e707db50ffd7d2c22832614ae42f267 Mon Sep 17 00:00:00 2001 From: neallee Date: Fri, 10 Jul 2026 20:07:32 +0800 Subject: [PATCH 06/51] fix: deny stale team hook paths safely Catch project hook resolution and load failures in the cross-shell Node launcher, returning a sanitized structured denial instead of a module-loader error. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- README.md | 2 +- bin/gstack-team-init | 2 +- test/team-mode.test.ts | 92 ++++++++++++++++++++++++++++++++---------- 3 files changed, 73 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 8233848d68..8f191f445e 100644 --- a/README.md +++ b/README.md @@ -58,7 +58,7 @@ From inside your repo, paste this. Switches you to team mode, bootstraps the rep (cd ~/.claude/skills/gstack && ./setup --team) && ~/.claude/skills/gstack/bin/gstack-team-init required && git add .claude/ CLAUDE.md && git commit -m "require gstack for AI-assisted work" ``` -No vendored gstack install in your repo, no version drift, no manual upgrades. Required mode commits one Node 18+ CommonJS enforcement hook, so the same project hook works from POSIX and Windows hook runners without duplicate shell-specific handlers. If the hook runner omits its project directory, enforcement fails closed with an intentional denial instead of a hook error. Every Claude Code session starts with a fast auto-update check (throttled to once/hour, network-failure-safe, completely silent). +No vendored gstack install in your repo, no version drift, no manual upgrades. Required mode commits one Node 18+ CommonJS enforcement hook, so the same project hook works from POSIX and Windows hook runners without duplicate shell-specific handlers. If the hook runner omits its project directory or provides a stale path, enforcement fails closed with an intentional denial instead of a hook error. Every Claude Code session starts with a fast auto-update check (throttled to once/hour, network-failure-safe, completely silent). Swap `required` for `optional` if you'd rather nudge teammates than block them. diff --git a/bin/gstack-team-init b/bin/gstack-team-init index 74cd5af5d7..2687f7d73c 100755 --- a/bin/gstack-team-init +++ b/bin/gstack-team-init @@ -179,7 +179,7 @@ HOOK_EOF if (!settings.hooks) settings.hooks = {}; if (!settings.hooks.PreToolUse) settings.hooks.PreToolUse = []; - const hookCommand = \"node -e \\\"const projectDir=process.env.CLAUDE_PROJECT_DIR;if(!projectDir){const reason='BLOCKED: CLAUDE_PROJECT_DIR is unavailable, so the required gstack hook cannot be loaded.';console.error(reason);console.log(JSON.stringify({hookSpecificOutput:{hookEventName:'PreToolUse',permissionDecision:'deny',permissionDecisionReason:reason}}))}else{require(require('node:path').join(projectDir, '.claude', 'hooks', 'check-gstack.cjs'))}\\\"\"; + const hookCommand = \"node -e \\\"const deny=reason=>{console.error(reason);console.log(JSON.stringify({hookSpecificOutput:{hookEventName:'PreToolUse',permissionDecision:'deny',permissionDecisionReason:reason}}))};const projectDir=process.env.CLAUDE_PROJECT_DIR;if(!projectDir){deny('BLOCKED: CLAUDE_PROJECT_DIR is unavailable, so the required gstack hook cannot be loaded.')}else{try{require(require('node:path').join(projectDir, '.claude', 'hooks', 'check-gstack.cjs'))}catch{deny('BLOCKED: the required gstack hook could not be loaded. Verify project hook setup and retry.')}}\\\"\"; let found = false; settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(entry => { if (entry.matcher !== 'Skill' || !entry.hooks) return true; diff --git a/test/team-mode.test.ts b/test/team-mode.test.ts index a17fb6938f..e3101a3ec9 100644 --- a/test/team-mode.test.ts +++ b/test/team-mode.test.ts @@ -13,6 +13,10 @@ function bashCommand(filePath: string): string { const SETTINGS_HOOK = bashCommand(path.join(ROOT, 'bin', 'gstack-settings-hook')); const SESSION_UPDATE = bashCommand(path.join(ROOT, 'bin', 'gstack-session-update')); const TEAM_INIT = bashCommand(path.join(ROOT, 'bin', 'gstack-team-init')); +const MISSING_PROJECT_REASON = + 'BLOCKED: CLAUDE_PROJECT_DIR is unavailable, so the required gstack hook cannot be loaded.'; +const HOOK_LOAD_REASON = + 'BLOCKED: the required gstack hook could not be loaded. Verify project hook setup and retry.'; function mkTmpDir(): string { return fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-team-test-')); @@ -77,6 +81,22 @@ function runHookInPowerShell( }; } +function expectStructuredDeny( + result: { stdout: string; stderr: string; exitCode: number }, + reason: string, +): void { + expect(result.exitCode).toBe(0); + expect(result.stderr.trim()).toBe(reason); + expect(result.stderr).not.toContain('MODULE_NOT_FOUND'); + expect(JSON.parse(result.stdout)).toEqual({ + hookSpecificOutput: { + hookEventName: 'PreToolUse', + permissionDecision: 'deny', + permissionDecisionReason: reason, + }, + }); +} + describe('gstack-settings-hook', () => { let tmpDir: string; let settingsFile: string; @@ -312,7 +332,7 @@ describe('gstack-team-init', () => { expect(entry.hooks).toHaveLength(1); expect(entry.hooks[0]).not.toHaveProperty('shell'); expect(entry.hooks[0].command).toBe( - `node -e "const projectDir=process.env.CLAUDE_PROJECT_DIR;if(!projectDir){const reason='BLOCKED: CLAUDE_PROJECT_DIR is unavailable, so the required gstack hook cannot be loaded.';console.error(reason);console.log(JSON.stringify({hookSpecificOutput:{hookEventName:'PreToolUse',permissionDecision:'deny',permissionDecisionReason:reason}}))}else{require(require('node:path').join(projectDir, '.claude', 'hooks', 'check-gstack.cjs'))}"`, + `node -e "const deny=reason=>{console.error(reason);console.log(JSON.stringify({hookSpecificOutput:{hookEventName:'PreToolUse',permissionDecision:'deny',permissionDecisionReason:reason}}))};const projectDir=process.env.CLAUDE_PROJECT_DIR;if(!projectDir){deny('BLOCKED: CLAUDE_PROJECT_DIR is unavailable, so the required gstack hook cannot be loaded.')}else{try{require(require('node:path').join(projectDir, '.claude', 'hooks', 'check-gstack.cjs'))}catch{deny('BLOCKED: the required gstack hook could not be loaded. Verify project hook setup and retry.')}}"`, ); expect(entry.hooks[0].command).not.toMatch( /\$CLAUDE_PROJECT_DIR|\$env:CLAUDE_PROJECT_DIR|%CLAUDE_PROJECT_DIR%/, @@ -359,16 +379,7 @@ describe('gstack-team-init', () => { env: { CLAUDE_PROJECT_DIR: '' }, }); - expect(result.exitCode).toBe(0); - expect(result.stderr).toContain('BLOCKED: CLAUDE_PROJECT_DIR is unavailable'); - expect(JSON.parse(result.stdout)).toEqual({ - hookSpecificOutput: { - hookEventName: 'PreToolUse', - permissionDecision: 'deny', - permissionDecisionReason: - 'BLOCKED: CLAUDE_PROJECT_DIR is unavailable, so the required gstack hook cannot be loaded.', - }, - }); + expectStructuredDeny(result, MISSING_PROJECT_REASON); }); test('required: missing project env denies through PowerShell', () => { @@ -385,16 +396,55 @@ describe('gstack-team-init', () => { env: { CLAUDE_PROJECT_DIR: '' }, }); - expect(result.exitCode).toBe(0); - expect(result.stderr).toContain('BLOCKED: CLAUDE_PROJECT_DIR is unavailable'); - expect(JSON.parse(result.stdout)).toEqual({ - hookSpecificOutput: { - hookEventName: 'PreToolUse', - permissionDecision: 'deny', - permissionDecisionReason: - 'BLOCKED: CLAUDE_PROJECT_DIR is unavailable, so the required gstack hook cannot be loaded.', - }, - }); + expectStructuredDeny(result, MISSING_PROJECT_REASON); + }); + + test('required: stale project paths deny through the platform default shell', () => { + run(`${TEAM_INIT} required`, { cwd: tmpDir }); + const settings = JSON.parse( + fs.readFileSync(path.join(tmpDir, '.claude', 'settings.json'), 'utf-8'), + ); + const command = settings.hooks.PreToolUse[0].hooks[0].command; + const existingWithoutHook = path.join(tmpDir, 'existing-without-hook'); + fs.mkdirSync(existingWithoutHook); + + for (const projectDir of [ + path.join(tmpDir, 'nonexistent-project'), + existingWithoutHook, + ]) { + const result = runHook(command, { + cwd: tmpDir, + env: { CLAUDE_PROJECT_DIR: projectDir }, + }); + + expectStructuredDeny(result, HOOK_LOAD_REASON); + expect(result.stderr).not.toContain(projectDir); + } + }); + + test('required: stale project paths deny through PowerShell', () => { + if (process.platform !== 'win32') return; + + run(`${TEAM_INIT} required`, { cwd: tmpDir }); + const settings = JSON.parse( + fs.readFileSync(path.join(tmpDir, '.claude', 'settings.json'), 'utf-8'), + ); + const command = settings.hooks.PreToolUse[0].hooks[0].command; + const existingWithoutHook = path.join(tmpDir, 'powershell-without-hook'); + fs.mkdirSync(existingWithoutHook); + + for (const projectDir of [ + path.join(tmpDir, 'powershell-nonexistent'), + existingWithoutHook, + ]) { + const result = runHookInPowerShell(command, { + cwd: tmpDir, + env: { CLAUDE_PROJECT_DIR: projectDir }, + }); + + expectStructuredDeny(result, HOOK_LOAD_REASON); + expect(result.stderr).not.toContain(projectDir); + } }); test('required: hook runs in PowerShell with USERPROFILE home fallback', () => { From 5bdb043990ef36cee272faa90e794c8c07e67b40 Mon Sep 17 00:00:00 2001 From: neallee Date: Fri, 10 Jul 2026 20:59:35 +0800 Subject: [PATCH 07/51] fix: remove legacy team hook on migration Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- bin/gstack-team-init | 7 +++++++ test/team-mode.test.ts | 30 ++++++++++++++++++++++++------ 2 files changed, 31 insertions(+), 6 deletions(-) diff --git a/bin/gstack-team-init b/bin/gstack-team-init index 2687f7d73c..a416d40fa2 100755 --- a/bin/gstack-team-init +++ b/bin/gstack-team-init @@ -215,6 +215,13 @@ HOOK_EOF " 2>/dev/null GENERATED+=(".claude/settings.json") echo " + .claude/settings.json — PreToolUse hook registered" + + # Remove the obsolete Bash hook only after its replacement is generated and + # registered successfully. Other project hooks are left untouched. + if [ -e "$HOOKS_DIR/check-gstack.sh" ] || [ -L "$HOOKS_DIR/check-gstack.sh" ]; then + rm "$HOOKS_DIR/check-gstack.sh" + echo " - .claude/hooks/check-gstack.sh — removed legacy enforcement hook" + fi else echo " ! bun not found — manually add the PreToolUse hook to .claude/settings.json" fi diff --git a/test/team-mode.test.ts b/test/team-mode.test.ts index e3101a3ec9..b555f471cb 100644 --- a/test/team-mode.test.ts +++ b/test/team-mode.test.ts @@ -397,7 +397,7 @@ describe('gstack-team-init', () => { }); expectStructuredDeny(result, MISSING_PROJECT_REASON); - }); + }, 30_000); test('required: stale project paths deny through the platform default shell', () => { run(`${TEAM_INIT} required`, { cwd: tmpDir }); @@ -445,7 +445,7 @@ describe('gstack-team-init', () => { expectStructuredDeny(result, HOOK_LOAD_REASON); expect(result.stderr).not.toContain(projectDir); } - }); + }, 30_000); test('required: hook runs in PowerShell with USERPROFILE home fallback', () => { if (process.platform !== 'win32') return; @@ -472,7 +472,7 @@ describe('gstack-team-init', () => { expect(result.exitCode).toBe(0); expect(result.stderr).toBe(''); expect(JSON.parse(result.stdout)).toEqual({}); - }); + }, 30_000); test('required: missing gstack returns an intentional deny, not a hook error', () => { run(`${TEAM_INIT} required`, { cwd: tmpDir }); @@ -507,10 +507,14 @@ describe('gstack-team-init', () => { }); }); - test('required: rerun upgrades a legacy Bash hook without duplicates', () => { + test('required: rerun removes a legacy Bash hook without touching other hooks', () => { const hooksDir = path.join(tmpDir, '.claude', 'hooks'); + const legacyHook = path.join(hooksDir, 'check-gstack.sh'); + const unrelatedHook = path.join(hooksDir, 'check-project.cjs'); + const unrelatedHookContents = "console.log('project hook');\n"; fs.mkdirSync(hooksDir, { recursive: true }); - fs.writeFileSync(path.join(hooksDir, 'check-gstack.sh'), '#!/bin/bash\n'); + fs.writeFileSync(legacyHook, '#!/bin/bash\n'); + fs.writeFileSync(unrelatedHook, unrelatedHookContents); fs.writeFileSync( path.join(tmpDir, '.claude', 'settings.json'), JSON.stringify({ @@ -527,17 +531,31 @@ describe('gstack-team-init', () => { }, }), ); + execSync('git add .claude', { cwd: tmpDir }); + execSync('git commit -m "add legacy hook"', { cwd: tmpDir }); + + run(`${TEAM_INIT} required`, { cwd: tmpDir }); + expect(fs.existsSync(legacyHook)).toBe(false); + expect(fs.readFileSync(unrelatedHook, 'utf-8')).toBe(unrelatedHookContents); run(`${TEAM_INIT} required`, { cwd: tmpDir }); const settings = JSON.parse( fs.readFileSync(path.join(tmpDir, '.claude', 'settings.json'), 'utf-8'), ); + expect(fs.existsSync(legacyHook)).toBe(false); + expect(fs.readFileSync(unrelatedHook, 'utf-8')).toBe(unrelatedHookContents); + expect( + execSync('git status --short -- .claude/hooks/check-gstack.sh', { + cwd: tmpDir, + encoding: 'utf-8', + }), + ).toBe(' D .claude/hooks/check-gstack.sh\n'); expect(settings.hooks.PreToolUse).toHaveLength(1); expect(settings.hooks.PreToolUse[0].hooks).toHaveLength(1); expect(settings.hooks.PreToolUse[0].hooks[0].command).toContain( 'check-gstack.cjs', ); - }); + }, 30_000); test('idempotent: running twice does not duplicate CLAUDE.md section', () => { run(`${TEAM_INIT} optional`, { cwd: tmpDir }); From 27fe4e3249c37e3428916dcea15054a0a0ac92b5 Mon Sep 17 00:00:00 2001 From: neallee Date: Fri, 10 Jul 2026 21:25:58 +0800 Subject: [PATCH 08/51] fix: stage legacy team hook deletion Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- bin/gstack-team-init | 3 +++ test/team-mode.test.ts | 40 ++++++++++++++++++++++++++++++++-------- 2 files changed, 35 insertions(+), 8 deletions(-) diff --git a/bin/gstack-team-init b/bin/gstack-team-init index a416d40fa2..bf5a074283 100755 --- a/bin/gstack-team-init +++ b/bin/gstack-team-init @@ -220,6 +220,9 @@ HOOK_EOF # registered successfully. Other project hooks are left untouched. if [ -e "$HOOKS_DIR/check-gstack.sh" ] || [ -L "$HOOKS_DIR/check-gstack.sh" ]; then rm "$HOOKS_DIR/check-gstack.sh" + if (cd "$REPO_ROOT" && git ls-files --error-unmatch -- .claude/hooks/check-gstack.sh >/dev/null 2>&1); then + GENERATED+=(".claude/hooks/check-gstack.sh") + fi echo " - .claude/hooks/check-gstack.sh — removed legacy enforcement hook" fi else diff --git a/test/team-mode.test.ts b/test/team-mode.test.ts index b555f471cb..17c815160b 100644 --- a/test/team-mode.test.ts +++ b/test/team-mode.test.ts @@ -302,7 +302,7 @@ describe('gstack-team-init', () => { }); test('required: creates enforcement hook', () => { - run(`${TEAM_INIT} required`, { cwd: tmpDir }); + const result = run(`${TEAM_INIT} required`, { cwd: tmpDir }); const hookPath = path.join(tmpDir, '.claude', 'hooks', 'check-gstack.cjs'); expect(fs.existsSync(hookPath)).toBe(true); expect( @@ -319,6 +319,7 @@ describe('gstack-team-init', () => { expect(hook).toContain("permissionDecision: 'deny'"); expect(hook).toContain('BLOCKED: gstack is not installed'); expect(hook).not.toContain('#!/bin/bash'); + expect(result.stdout).not.toMatch(/git add .*check-gstack\.sh/); }); test('required: registers one shell-neutral project hook', () => { @@ -534,22 +535,45 @@ describe('gstack-team-init', () => { execSync('git add .claude', { cwd: tmpDir }); execSync('git commit -m "add legacy hook"', { cwd: tmpDir }); - run(`${TEAM_INIT} required`, { cwd: tmpDir }); + const migration = run(`${TEAM_INIT} required`, { cwd: tmpDir }); expect(fs.existsSync(legacyHook)).toBe(false); expect(fs.readFileSync(unrelatedHook, 'utf-8')).toBe(unrelatedHookContents); + const suggestedGitAdd = migration.stdout + .split('\n') + .find(line => line.startsWith(' git add ')) + ?.trim(); + if (!suggestedGitAdd) { + throw new Error('gstack-team-init did not print a git add command'); + } + expect(suggestedGitAdd.split(/\s+/)).toContain( + '.claude/hooks/check-gstack.sh', + ); + execSync(suggestedGitAdd, { cwd: tmpDir }); + execSync('git commit -m "migrate required hook"', { cwd: tmpDir }); + expect( + execSync('git status --short', { cwd: tmpDir, encoding: 'utf-8' }), + ).toBe(''); - run(`${TEAM_INIT} required`, { cwd: tmpDir }); + const rerun = run(`${TEAM_INIT} required`, { cwd: tmpDir }); const settings = JSON.parse( fs.readFileSync(path.join(tmpDir, '.claude', 'settings.json'), 'utf-8'), ); expect(fs.existsSync(legacyHook)).toBe(false); expect(fs.readFileSync(unrelatedHook, 'utf-8')).toBe(unrelatedHookContents); + const rerunGitAdd = rerun.stdout + .split('\n') + .find(line => line.startsWith(' git add ')) + ?.trim(); + if (!rerunGitAdd) { + throw new Error('gstack-team-init rerun did not print a git add command'); + } + expect(rerunGitAdd.split(/\s+/)).not.toContain( + '.claude/hooks/check-gstack.sh', + ); + execSync(rerunGitAdd, { cwd: tmpDir }); expect( - execSync('git status --short -- .claude/hooks/check-gstack.sh', { - cwd: tmpDir, - encoding: 'utf-8', - }), - ).toBe(' D .claude/hooks/check-gstack.sh\n'); + execSync('git status --short', { cwd: tmpDir, encoding: 'utf-8' }), + ).toBe(''); expect(settings.hooks.PreToolUse).toHaveLength(1); expect(settings.hooks.PreToolUse[0].hooks).toHaveLength(1); expect(settings.hooks.PreToolUse[0].hooks[0].command).toContain( From 344b398cd3e7cca936c15e3a492102b4fe6540e6 Mon Sep 17 00:00:00 2001 From: t Date: Fri, 10 Jul 2026 14:30:09 -0700 Subject: [PATCH 09/51] fix: fail closed across hook decision schemas --- README.md | 2 +- bin/gstack-team-init | 16 +++++++---- test/team-mode.test.ts | 63 ++++++++++++++++++++++++++++++++++++++++-- 3 files changed, 73 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 8f191f445e..121f42099c 100644 --- a/README.md +++ b/README.md @@ -58,7 +58,7 @@ From inside your repo, paste this. Switches you to team mode, bootstraps the rep (cd ~/.claude/skills/gstack && ./setup --team) && ~/.claude/skills/gstack/bin/gstack-team-init required && git add .claude/ CLAUDE.md && git commit -m "require gstack for AI-assisted work" ``` -No vendored gstack install in your repo, no version drift, no manual upgrades. Required mode commits one Node 18+ CommonJS enforcement hook, so the same project hook works from POSIX and Windows hook runners without duplicate shell-specific handlers. If the hook runner omits its project directory or provides a stale path, enforcement fails closed with an intentional denial instead of a hook error. Every Claude Code session starts with a fast auto-update check (throttled to once/hour, network-failure-safe, completely silent). +Your project stays small, and everyone gets the same up-to-date version of gstack. If gstack is missing or its safety check cannot run, Claude Code and Copilot stop and explain what to do. If everything is ready, the check stays out of the way and your usual permission questions still appear. Updates happen quietly when a Claude Code session starts, at most once an hour. Swap `required` for `optional` if you'd rather nudge teammates than block them. diff --git a/bin/gstack-team-init b/bin/gstack-team-init index bf5a074283..6157bad9c6 100755 --- a/bin/gstack-team-init +++ b/bin/gstack-team-init @@ -155,11 +155,15 @@ Then restart your AI coding tool. `; process.stderr.write(instructions); + const decision = { + permissionDecision: 'deny', + permissionDecisionReason: instructions, + }; process.stdout.write(`${JSON.stringify({ + ...decision, hookSpecificOutput: { hookEventName: 'PreToolUse', - permissionDecision: 'deny', - permissionDecisionReason: instructions, + ...decision, }, })}\n`); } @@ -179,10 +183,11 @@ HOOK_EOF if (!settings.hooks) settings.hooks = {}; if (!settings.hooks.PreToolUse) settings.hooks.PreToolUse = []; - const hookCommand = \"node -e \\\"const deny=reason=>{console.error(reason);console.log(JSON.stringify({hookSpecificOutput:{hookEventName:'PreToolUse',permissionDecision:'deny',permissionDecisionReason:reason}}))};const projectDir=process.env.CLAUDE_PROJECT_DIR;if(!projectDir){deny('BLOCKED: CLAUDE_PROJECT_DIR is unavailable, so the required gstack hook cannot be loaded.')}else{try{require(require('node:path').join(projectDir, '.claude', 'hooks', 'check-gstack.cjs'))}catch{deny('BLOCKED: the required gstack hook could not be loaded. Verify project hook setup and retry.')}}\\\"\"; + const hookMatcher = 'Skill|skill'; + const hookCommand = \"node -e \\\"const deny=reason=>{const decision={permissionDecision:'deny',permissionDecisionReason:reason};console.error(reason);console.log(JSON.stringify({...decision,hookSpecificOutput:{hookEventName:'PreToolUse',...decision}}))};const projectDir=process.env.CLAUDE_PROJECT_DIR;if(!projectDir){deny('BLOCKED: CLAUDE_PROJECT_DIR is unavailable, so the required gstack hook cannot be loaded.')}else{try{require(require('node:path').join(projectDir, '.claude', 'hooks', 'check-gstack.cjs'))}catch{deny('BLOCKED: the required gstack hook could not be loaded. Verify project hook setup and retry.')}}\\\"\"; let found = false; settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(entry => { - if (entry.matcher !== 'Skill' || !entry.hooks) return true; + if (!['Skill', hookMatcher].includes(entry.matcher) || !entry.hooks) return true; const matchingHooks = entry.hooks.filter( h => h.command && h.command.includes('check-gstack') @@ -193,6 +198,7 @@ HOOK_EOF h => !h.command || !h.command.includes('check-gstack') ); if (!found) { + entry.matcher = hookMatcher; entry.hooks.push({ type: 'command', command: hookCommand }); found = true; } @@ -201,7 +207,7 @@ HOOK_EOF if (!found) { settings.hooks.PreToolUse.push({ - matcher: 'Skill', + matcher: hookMatcher, hooks: [{ type: 'command', command: hookCommand diff --git a/test/team-mode.test.ts b/test/team-mode.test.ts index 17c815160b..5a4715e2e4 100644 --- a/test/team-mode.test.ts +++ b/test/team-mode.test.ts @@ -89,6 +89,8 @@ function expectStructuredDeny( expect(result.stderr.trim()).toBe(reason); expect(result.stderr).not.toContain('MODULE_NOT_FOUND'); expect(JSON.parse(result.stdout)).toEqual({ + permissionDecision: 'deny', + permissionDecisionReason: reason, hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', @@ -329,11 +331,11 @@ describe('gstack-team-init', () => { const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8')); expect(settings.hooks.PreToolUse).toHaveLength(1); const entry = settings.hooks.PreToolUse[0]; - expect(entry.matcher).toBe('Skill'); + expect(entry.matcher).toBe('Skill|skill'); expect(entry.hooks).toHaveLength(1); expect(entry.hooks[0]).not.toHaveProperty('shell'); expect(entry.hooks[0].command).toBe( - `node -e "const deny=reason=>{console.error(reason);console.log(JSON.stringify({hookSpecificOutput:{hookEventName:'PreToolUse',permissionDecision:'deny',permissionDecisionReason:reason}}))};const projectDir=process.env.CLAUDE_PROJECT_DIR;if(!projectDir){deny('BLOCKED: CLAUDE_PROJECT_DIR is unavailable, so the required gstack hook cannot be loaded.')}else{try{require(require('node:path').join(projectDir, '.claude', 'hooks', 'check-gstack.cjs'))}catch{deny('BLOCKED: the required gstack hook could not be loaded. Verify project hook setup and retry.')}}"`, + `node -e "const deny=reason=>{const decision={permissionDecision:'deny',permissionDecisionReason:reason};console.error(reason);console.log(JSON.stringify({...decision,hookSpecificOutput:{hookEventName:'PreToolUse',...decision}}))};const projectDir=process.env.CLAUDE_PROJECT_DIR;if(!projectDir){deny('BLOCKED: CLAUDE_PROJECT_DIR is unavailable, so the required gstack hook cannot be loaded.')}else{try{require(require('node:path').join(projectDir, '.claude', 'hooks', 'check-gstack.cjs'))}catch{deny('BLOCKED: the required gstack hook could not be loaded. Verify project hook setup and retry.')}}"`, ); expect(entry.hooks[0].command).not.toMatch( /\$CLAUDE_PROJECT_DIR|\$env:CLAUDE_PROJECT_DIR|%CLAUDE_PROJECT_DIR%/, @@ -498,6 +500,10 @@ describe('gstack-team-init', () => { expect(result.stderr).toContain('git clone --depth 1'); const decision = JSON.parse(result.stdout); expect(decision).toEqual({ + permissionDecision: 'deny', + permissionDecisionReason: expect.stringContaining( + 'Then restart your AI coding tool.', + ), hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', @@ -508,6 +514,58 @@ describe('gstack-team-init', () => { }); }); + test('required: install verification errors return a structured deny', () => { + run(`${TEAM_INIT} required`, { cwd: tmpDir }); + const settings = JSON.parse( + fs.readFileSync(path.join(tmpDir, '.claude', 'settings.json'), 'utf-8'), + ); + const command = settings.hooks.PreToolUse[0].hooks[0].command; + const fakeHome = path.join(tmpDir, 'unreadable-home'); + const preload = path.join(tmpDir, 'fail-gstack-stat.cjs'); + fs.mkdirSync(fakeHome, { recursive: true }); + fs.writeFileSync( + preload, + `'use strict'; +const fs = require('node:fs'); +const original = fs.statSync; +fs.statSync = function (target, ...args) { + if (String(target).replace(/\\\\/g, '/').includes('skills/gstack/bin')) { + const error = new Error('injected verification failure'); + error.code = 'EACCES'; + throw error; + } + return original.call(this, target, ...args); +}; +`, + ); + + const result = runHook(command, { + cwd: tmpDir, + env: { + CLAUDE_PROJECT_DIR: tmpDir, + HOME: fakeHome, + USERPROFILE: fakeHome, + NODE_OPTIONS: `--require=${preload}`, + }, + }); + + expect(result.exitCode).toBe(0); + expect(result.stderr).toContain( + 'BLOCKED: the global gstack install could not be verified.', + ); + expect(result.stderr).not.toContain('injected verification failure'); + const decision = JSON.parse(result.stdout); + expect(decision.permissionDecision).toBe('deny'); + expect(decision.permissionDecisionReason).toContain( + 'BLOCKED: the global gstack install could not be verified.', + ); + expect(decision.hookSpecificOutput).toEqual({ + hookEventName: 'PreToolUse', + permissionDecision: 'deny', + permissionDecisionReason: decision.permissionDecisionReason, + }); + }); + test('required: rerun removes a legacy Bash hook without touching other hooks', () => { const hooksDir = path.join(tmpDir, '.claude', 'hooks'); const legacyHook = path.join(hooksDir, 'check-gstack.sh'); @@ -576,6 +634,7 @@ describe('gstack-team-init', () => { ).toBe(''); expect(settings.hooks.PreToolUse).toHaveLength(1); expect(settings.hooks.PreToolUse[0].hooks).toHaveLength(1); + expect(settings.hooks.PreToolUse[0].matcher).toBe('Skill|skill'); expect(settings.hooks.PreToolUse[0].hooks[0].command).toContain( 'check-gstack.cjs', ); From bad63fcff5e8ea72eab63fa7357861a3c1ce4ebc Mon Sep 17 00:00:00 2001 From: Sina Date: Fri, 10 Jul 2026 09:28:48 -0700 Subject: [PATCH 10/51] fix(benchmark): parse current gemini stream-json content/stats shape GeminiAdapter was reading message.text and result.usage, so current CLI content/stats events produced empty $0 success rows. Accept content with an assistant role guard, stats token fallbacks, init model, and treat empty exit-0 output as an error (#2159). Co-authored-by: Cursor --- test/helpers/providers/gemini.test.ts | 95 ++++++++++++++++++ test/helpers/providers/gemini.ts | 106 ++++++++++++++------- test/skill-e2e-benchmark-providers.test.ts | 18 ++-- 3 files changed, 171 insertions(+), 48 deletions(-) create mode 100644 test/helpers/providers/gemini.test.ts diff --git a/test/helpers/providers/gemini.test.ts b/test/helpers/providers/gemini.test.ts new file mode 100644 index 0000000000..421e00c647 --- /dev/null +++ b/test/helpers/providers/gemini.test.ts @@ -0,0 +1,95 @@ +import { describe, test, expect } from 'bun:test'; +import { parseGeminiStreamJson } from './gemini'; + +// Current CLI shape (gemini ≥ ~1.58): content + role, tokens under result.stats +const CURRENT_CLI_FIXTURE = [ + '{"type":"init","timestamp":"2026-03-20T15:14:46.455Z","session_id":"test-session-123","model":"gemini-2.5-pro"}', + '{"type":"message","role":"user","content":"Reply with exactly the word: PONG"}', + '{"type":"message","role":"assistant","content":"PONG","delta":true}', + '{"type":"result","status":"success","stats":{"input_tokens":24946,"output_tokens":32,"total_tokens":24978}}', +].join('\n'); + +// Legacy shape: text field, tokens under result.usage +const LEGACY_FIXTURE = [ + '{"type":"message","text":"hello"}', + '{"type":"tool_use","name":"run_shell_command"}', + '{"type":"result","usage":{"input_token_count":100,"output_token_count":5},"model":"gemini-2.5-flash"}', +].join('\n'); + +describe('parseGeminiStreamJson', () => { + test('current CLI: reads assistant content, ignores user echo, stats tokens, init model', () => { + const parsed = parseGeminiStreamJson(CURRENT_CLI_FIXTURE); + expect(parsed.output).toBe('PONG'); + expect(parsed.tokens.input).toBe(24946); + expect(parsed.tokens.output).toBe(32); + expect(parsed.modelUsed).toBe('gemini-2.5-pro'); + expect(parsed.toolCalls).toBe(0); + }); + + test('current CLI: user role content must not concat into output', () => { + const raw = [ + '{"type":"message","role":"user","content":"PROMPT ECHO"}', + '{"type":"message","role":"assistant","content":"ok","delta":true}', + ].join('\n'); + const parsed = parseGeminiStreamJson(raw); + expect(parsed.output).toBe('ok'); + expect(parsed.output).not.toContain('PROMPT ECHO'); + }); + + test('legacy: still accepts text + usage.input_token_count', () => { + const parsed = parseGeminiStreamJson(LEGACY_FIXTURE); + expect(parsed.output).toBe('hello'); + expect(parsed.tokens.input).toBe(100); + expect(parsed.tokens.output).toBe(5); + expect(parsed.toolCalls).toBe(1); + expect(parsed.modelUsed).toBe('gemini-2.5-flash'); + }); + + test('legacy text with role:user is ignored', () => { + const raw = [ + '{"type":"message","role":"user","text":"echo"}', + '{"type":"message","role":"assistant","text":"kept"}', + ].join('\n'); + const parsed = parseGeminiStreamJson(raw); + expect(parsed.output).toBe('kept'); + }); + + test('concatenates multiple assistant content deltas', () => { + const raw = [ + '{"type":"message","role":"assistant","content":"A","delta":true}', + '{"type":"message","role":"assistant","content":"B","delta":true}', + ].join('\n'); + expect(parseGeminiStreamJson(raw).output).toBe('AB'); + }); + + test('skips malformed lines without throwing', () => { + const raw = [ + '{"type":"init","model":"m1"}', + 'not json', + '{"type":"message","role":"assistant","content":"x","delta":true}', + '{incomplete', + '{"type":"result","stats":{"input_tokens":1,"output_tokens":2}}', + ].join('\n'); + const parsed = parseGeminiStreamJson(raw); + expect(parsed.output).toBe('x'); + expect(parsed.tokens).toEqual({ input: 1, output: 2 }); + expect(parsed.modelUsed).toBe('m1'); + }); + + test('empty / whitespace-only input yields empty parse (no throw)', () => { + const parsed = parseGeminiStreamJson(''); + expect(parsed.output).toBe(''); + expect(parsed.tokens).toEqual({ input: 0, output: 0 }); + expect(parsed.toolCalls).toBe(0); + expect(parsed.modelUsed).toBeUndefined(); + }); + + test('result.model overrides init.model when both present', () => { + const raw = [ + '{"type":"init","model":"from-init"}', + '{"type":"message","role":"assistant","content":"hi"}', + '{"type":"result","model":"from-result","stats":{"input_tokens":1,"output_tokens":1}}', + ].join('\n'); + expect(parseGeminiStreamJson(raw).modelUsed).toBe('from-result'); + }); +}); diff --git a/test/helpers/providers/gemini.ts b/test/helpers/providers/gemini.ts index 5e7abba13a..cf3ad333b8 100644 --- a/test/helpers/providers/gemini.ts +++ b/test/helpers/providers/gemini.ts @@ -5,6 +5,63 @@ import * as fs from 'fs'; import * as path from 'path'; import * as os from 'os'; +export type GeminiStreamParse = { + output: string; + tokens: { input: number; output: number }; + toolCalls: number; + modelUsed?: string; +}; + +/** + * Parse gemini NDJSON stream events (exported for unit tests). + * + * Current CLI (`--output-format stream-json`) emits: + * init → model + * message { role, content, delta? } → concat assistant content + * tool_use → increment toolCalls + * result { stats: { input_tokens, output_tokens } } → tokens + * + * Legacy shape (still accepted): + * message { text } → concat text + * result { usage: { input_token_count, output_token_count } } → tokens + */ +export function parseGeminiStreamJson(raw: string): GeminiStreamParse { + let output = ''; + let input = 0; + let out = 0; + let toolCalls = 0; + let modelUsed: string | undefined; + for (const line of raw.split('\n')) { + const s = line.trim(); + if (!s) continue; + try { + const obj = JSON.parse(s); + if (obj.type === 'init') { + if (typeof obj.model === 'string' && obj.model) modelUsed = obj.model; + } else if (obj.type === 'message') { + // Current CLI: content + role. Role guard is required — the CLI echoes + // the user prompt as role:'user', which must not land in output. + if (obj.role === 'assistant' && typeof obj.content === 'string') { + output += obj.content; + } else if (typeof obj.text === 'string' && obj.role !== 'user') { + // Legacy text field (no role, or assistant). + output += obj.text; + } + } else if (obj.type === 'tool_use') { + toolCalls += 1; + } else if (obj.type === 'result') { + const u = obj.usage ?? obj.stats ?? {}; + input += u.input_token_count ?? u.input_tokens ?? u.prompt_tokens ?? 0; + out += u.output_token_count ?? u.output_tokens ?? u.completion_tokens ?? 0; + if (typeof obj.model === 'string' && obj.model) modelUsed = obj.model; + } + } catch { + // skip malformed lines + } + } + return { output, tokens: { input, output: out }, toolCalls, modelUsed }; +} + /** * Gemini adapter — wraps the `gemini` CLI. * @@ -48,13 +105,23 @@ export class GeminiAdapter implements ProviderAdapter { encoding: 'utf-8', maxBuffer: 32 * 1024 * 1024, }); - const parsed = this.parseStreamJson(out); + const parsed = parseGeminiStreamJson(out); + const modelUsed = parsed.modelUsed || opts.model || 'gemini-2.5-pro'; + // Empty-success is indistinguishable from a healthy cheap run in the + // comparison table — never report it as a $0 success row (#2159). + if (!parsed.output.trim()) { + return this.emptyResult( + Date.now() - start, + { code: 'unknown', reason: 'empty output from gemini CLI (exit 0)' }, + modelUsed, + ); + } return { output: parsed.output, tokens: parsed.tokens, durationMs: Date.now() - start, toolCalls: parsed.toolCalls, - modelUsed: parsed.modelUsed || opts.model || 'gemini-2.5-pro', + modelUsed, }; } catch (err: unknown) { const durationMs = Date.now() - start; @@ -77,41 +144,6 @@ export class GeminiAdapter implements ProviderAdapter { return estimateCostUsd(tokens, model ?? 'gemini-2.5-pro'); } - /** - * Parse gemini NDJSON stream events: - * init → session id (discarded here) - * message { delta: true, text } → concat to output - * tool_use { name } → increment toolCalls - * result { usage: { input_token_count, output_token_count } } → tokens - */ - private parseStreamJson(raw: string): { output: string; tokens: { input: number; output: number }; toolCalls: number; modelUsed?: string } { - let output = ''; - let input = 0; - let out = 0; - let toolCalls = 0; - let modelUsed: string | undefined; - for (const line of raw.split('\n')) { - const s = line.trim(); - if (!s) continue; - try { - const obj = JSON.parse(s); - if (obj.type === 'message' && typeof obj.text === 'string') { - output += obj.text; - } else if (obj.type === 'tool_use') { - toolCalls += 1; - } else if (obj.type === 'result') { - const u = obj.usage ?? {}; - input += u.input_token_count ?? u.prompt_tokens ?? 0; - out += u.output_token_count ?? u.completion_tokens ?? 0; - if (obj.model) modelUsed = obj.model; - } - } catch { - // skip malformed lines - } - } - return { output, tokens: { input, output: out }, toolCalls, modelUsed }; - } - private emptyResult(durationMs: number, error: RunResult['error'], model?: string): RunResult { return { output: '', diff --git a/test/skill-e2e-benchmark-providers.test.ts b/test/skill-e2e-benchmark-providers.test.ts index 12456ec231..98c2f3e03e 100644 --- a/test/skill-e2e-benchmark-providers.test.ts +++ b/test/skill-e2e-benchmark-providers.test.ts @@ -129,19 +129,15 @@ describeIfEvals('multi-provider benchmark adapters (live)', () => { if (result.error) { throw new Error(`gemini errored: ${result.error.code} — ${result.error.reason}`); } - // Gemini CLI occasionally returns empty output even on successful runs - // (model returned content the CLI parser missed, intermittent stream issues). - // We assert the adapter ran end-to-end without erroring and reports a non- - // empty token count instead of grepping the literal "ok" — that string - // assertion was too brittle for a smoke that's really about "did the - // adapter wire up and the run terminate successfully?" - expect(typeof result.output).toBe('string'); - // Gemini CLI sometimes returns 0 tokens in the result event (older responses); - // assert non-negative instead of strictly positive. - expect(result.tokens.input).toBeGreaterThanOrEqual(0); - expect(result.tokens.output).toBeGreaterThanOrEqual(0); + // Adapter must never report empty-success (#2159). After content/stats + // parsing, a healthy run has non-empty assistant text + token counts. + expect(result.output.trim().length).toBeGreaterThan(0); + expect(result.output.toLowerCase()).toContain('ok'); + expect(result.tokens.input).toBeGreaterThan(0); + expect(result.tokens.output).toBeGreaterThan(0); expect(result.durationMs).toBeGreaterThan(0); expect(typeof result.modelUsed).toBe('string'); + expect(result.modelUsed.length).toBeGreaterThan(0); }, 150_000); test('timeout error surfaces as error.code=timeout (no exception)', async () => { From f375ef07b67a15cfc7aed56872a765d7b5a5b299 Mon Sep 17 00:00:00 2001 From: Sina Date: Fri, 10 Jul 2026 09:38:06 -0700 Subject: [PATCH 11/51] test(benchmark): full post-CLI gemini e2e + GEMINI_API_KEY auth path MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Exercise resultFromGeminiStream against current stream-json fixtures (including empty-success hardening). Recognize GEMINI_API_KEY and map IneligibleTierError to auth — personal OAuth free-tier is no longer supported by gemini CLI. Co-authored-by: Cursor --- test/helpers/providers/gemini.test.ts | 47 +++++++++++++++++- test/helpers/providers/gemini.ts | 68 ++++++++++++++++++--------- 2 files changed, 92 insertions(+), 23 deletions(-) diff --git a/test/helpers/providers/gemini.test.ts b/test/helpers/providers/gemini.test.ts index 421e00c647..a0f404e294 100644 --- a/test/helpers/providers/gemini.test.ts +++ b/test/helpers/providers/gemini.test.ts @@ -1,7 +1,8 @@ import { describe, test, expect } from 'bun:test'; -import { parseGeminiStreamJson } from './gemini'; +import { parseGeminiStreamJson, resultFromGeminiStream } from './gemini'; -// Current CLI shape (gemini ≥ ~1.58): content + role, tokens under result.stats +// Current CLI shape (gemini ≥ ~0.11 / stream-json): content + role, tokens under result.stats +// Documented at https://geminicli.com/docs/cli/headless/ and gemini-cli PR #10883. const CURRENT_CLI_FIXTURE = [ '{"type":"init","timestamp":"2026-03-20T15:14:46.455Z","session_id":"test-session-123","model":"gemini-2.5-pro"}', '{"type":"message","role":"user","content":"Reply with exactly the word: PONG"}', @@ -93,3 +94,45 @@ describe('parseGeminiStreamJson', () => { expect(parseGeminiStreamJson(raw).modelUsed).toBe('from-result'); }); }); + +describe('resultFromGeminiStream (adapter post-CLI e2e)', () => { + test('current CLI fixture → success row with PONG + tokens (not $0)', () => { + const result = resultFromGeminiStream(CURRENT_CLI_FIXTURE, { durationMs: 42 }); + expect(result.error).toBeUndefined(); + expect(result.output).toBe('PONG'); + expect(result.tokens.input).toBe(24946); + expect(result.tokens.output).toBe(32); + expect(result.modelUsed).toBe('gemini-2.5-pro'); + expect(result.durationMs).toBe(42); + // Cost signal: non-zero tokens means estimateCost will not be $0. + expect(result.tokens.input + result.tokens.output).toBeGreaterThan(0); + }); + + test('legacy text-only success still works', () => { + const result = resultFromGeminiStream(LEGACY_FIXTURE, { durationMs: 10 }); + expect(result.error).toBeUndefined(); + expect(result.output).toBe('hello'); + expect(result.toolCalls).toBe(1); + }); + + test('empty exit-0 stream → error row, never silent $0 success (#2159)', () => { + const emptySuccess = [ + '{"type":"init","model":"gemini-2.5-pro"}', + '{"type":"message","role":"user","content":"hi"}', + '{"type":"result","status":"success","stats":{"input_tokens":0,"output_tokens":0}}', + ].join('\n'); + const result = resultFromGeminiStream(emptySuccess, { durationMs: 5 }); + expect(result.error).toBeDefined(); + expect(result.error!.code).toBe('unknown'); + expect(result.error!.reason).toContain('empty output'); + expect(result.output).toBe(''); + expect(result.modelUsed).toBe('gemini-2.5-pro'); + }); + + test('pre-fix bug shape (text field missing, only content) would have been empty — now succeeds', () => { + // This is the exact failure mode from #2159: content present, no text. + const result = resultFromGeminiStream(CURRENT_CLI_FIXTURE); + expect(result.error).toBeUndefined(); + expect(result.output).toBe('PONG'); + }); +}); diff --git a/test/helpers/providers/gemini.ts b/test/helpers/providers/gemini.ts index cf3ad333b8..84b3059ab1 100644 --- a/test/helpers/providers/gemini.ts +++ b/test/helpers/providers/gemini.ts @@ -62,6 +62,37 @@ export function parseGeminiStreamJson(raw: string): GeminiStreamParse { return { output, tokens: { input, output: out }, toolCalls, modelUsed }; } +/** + * Map a raw stream-json dump to a RunResult, including the empty-success + * hardening from #2159. Exported so adapter e2e can exercise the full + * post-CLI path without a live gemini binary. + */ +export function resultFromGeminiStream( + raw: string, + opts: { model?: string; durationMs?: number } = {}, +): RunResult { + const parsed = parseGeminiStreamJson(raw); + const modelUsed = parsed.modelUsed || opts.model || 'gemini-2.5-pro'; + const durationMs = opts.durationMs ?? 0; + if (!parsed.output.trim()) { + return { + output: '', + tokens: { input: 0, output: 0 }, + durationMs, + toolCalls: 0, + modelUsed, + error: { code: 'unknown', reason: 'empty output from gemini CLI (exit 0)' }, + }; + } + return { + output: parsed.output, + tokens: parsed.tokens, + durationMs, + toolCalls: parsed.toolCalls, + modelUsed, + }; +} + /** * Gemini adapter — wraps the `gemini` CLI. * @@ -83,9 +114,14 @@ export class GeminiAdapter implements ProviderAdapter { const newCfgDir = path.join(os.homedir(), '.gemini'); const newOauth = path.join(newCfgDir, 'oauth_creds.json'); const hasCfg = fs.existsSync(legacyCfgDir) || fs.existsSync(newOauth); - const hasKey = !!process.env.GOOGLE_API_KEY; + // CLI accepts either name; Google AI Studio keys are usually GEMINI_API_KEY. + const hasKey = !!(process.env.GOOGLE_API_KEY || process.env.GEMINI_API_KEY); if (!hasCfg && !hasKey) { - return { ok: false, reason: 'No Gemini auth found. Log in via `gemini login` or export GOOGLE_API_KEY.' }; + return { + ok: false, + reason: + 'No Gemini auth found. Export GEMINI_API_KEY (or GOOGLE_API_KEY) from https://aistudio.google.com/app/apikey — personal OAuth free-tier is no longer supported by gemini CLI.', + }; } return { ok: true }; } @@ -104,25 +140,15 @@ export class GeminiAdapter implements ProviderAdapter { timeout: opts.timeoutMs, encoding: 'utf-8', maxBuffer: 32 * 1024 * 1024, + env: { + ...process.env, + // Prefer GEMINI_API_KEY when only that is set (CLI reads both). + ...(process.env.GEMINI_API_KEY && !process.env.GOOGLE_API_KEY + ? { GOOGLE_API_KEY: process.env.GEMINI_API_KEY } + : {}), + }, }); - const parsed = parseGeminiStreamJson(out); - const modelUsed = parsed.modelUsed || opts.model || 'gemini-2.5-pro'; - // Empty-success is indistinguishable from a healthy cheap run in the - // comparison table — never report it as a $0 success row (#2159). - if (!parsed.output.trim()) { - return this.emptyResult( - Date.now() - start, - { code: 'unknown', reason: 'empty output from gemini CLI (exit 0)' }, - modelUsed, - ); - } - return { - output: parsed.output, - tokens: parsed.tokens, - durationMs: Date.now() - start, - toolCalls: parsed.toolCalls, - modelUsed, - }; + return resultFromGeminiStream(out, { model: opts.model, durationMs: Date.now() - start }); } catch (err: unknown) { const durationMs = Date.now() - start; const e = err as { code?: string; stderr?: Buffer; signal?: string; message?: string }; @@ -130,7 +156,7 @@ export class GeminiAdapter implements ProviderAdapter { if (e.signal === 'SIGTERM' || e.code === 'ETIMEDOUT') { return this.emptyResult(durationMs, { code: 'timeout', reason: `exceeded ${opts.timeoutMs}ms` }, opts.model); } - if (/unauthorized|auth|login|api key/i.test(stderr)) { + if (/unauthorized|auth|login|api key|ineligibletier|no longer supported/i.test(stderr)) { return this.emptyResult(durationMs, { code: 'auth', reason: stderr.slice(0, 400) }, opts.model); } if (/rate[- ]?limit|429|quota/i.test(stderr)) { From 82cf77038e2c5a3808edf30f588b29d5828217f5 Mon Sep 17 00:00:00 2001 From: Sina Date: Fri, 10 Jul 2026 10:38:46 -0700 Subject: [PATCH 12/51] fix(benchmark): skip-trust for headless gemini + drop release metadata MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Pass --skip-trust so temp/untrusted workdirs work in headless benchmarks (mirrors Codex --skip-git-repo-check). Revert VERSION, CHANGELOG, and package.json bumps — leave release bookkeeping to maintainers / /ship, matching community PR practice. Co-authored-by: Cursor --- test/helpers/gemini-session-runner.ts | 7 +++++-- test/helpers/providers/gemini.ts | 21 +++++++++++++++------ 2 files changed, 20 insertions(+), 8 deletions(-) diff --git a/test/helpers/gemini-session-runner.ts b/test/helpers/gemini-session-runner.ts index 4f2f040e33..3b58c79ca8 100644 --- a/test/helpers/gemini-session-runner.ts +++ b/test/helpers/gemini-session-runner.ts @@ -8,7 +8,8 @@ * Key differences from Codex session-runner: * - Uses `gemini -p` instead of `codex exec` * - Output is NDJSON with event types: init, message, tool_use, tool_result, result - * - Uses `--output-format stream-json --yolo` instead of `--json -s read-only` + * - Uses `--output-format stream-json --yolo --skip-trust` instead of `--json -s read-only` + * (`--skip-trust` required for headless/untrusted cwds; see gemini trusted-folders docs) * - No temp HOME needed — Gemini discovers skills from `.agents/skills/` in cwd * - Message events are streamed with `delta: true` — must concatenate */ @@ -121,7 +122,9 @@ export async function runGeminiSkill(opts: { } // Build gemini command - const args = ['-p', prompt, '--output-format', 'stream-json', '--yolo']; + // --skip-trust: headless/CI and temp cwds aren't in ~/.gemini/trustedFolders.json; + // without it gemini exits FatalUntrustedWorkspaceError before any model call. + const args = ['-p', prompt, '--output-format', 'stream-json', '--yolo', '--skip-trust']; // Spawn gemini — uses real HOME for auth (~/.gemini; HOME is allowlisted), // cwd for skill discovery. Hermetic scrub with gemini's auth surface diff --git a/test/helpers/providers/gemini.ts b/test/helpers/providers/gemini.ts index 84b3059ab1..b53d725d1e 100644 --- a/test/helpers/providers/gemini.ts +++ b/test/helpers/providers/gemini.ts @@ -96,10 +96,17 @@ export function resultFromGeminiStream( /** * Gemini adapter — wraps the `gemini` CLI. * - * Gemini CLI auth comes from either ~/.config/gemini/ or GOOGLE_API_KEY. Output - * format is NDJSON with `message`/`tool_use`/`result` events when `--output-format - * stream-json` is requested. This adapter uses a single-response form for simplicity - * in benchmarks; richer streaming lives in gemini-session-runner.ts. + * Auth: GEMINI_API_KEY / GOOGLE_API_KEY (preferred), or ~/.gemini oauth. + * Personal OAuth free-tier is no longer supported by gemini CLI — use an + * AI Studio API key. Antigravity is a separate product/quota path. + * + * Headless flags always passed: + * --output-format stream-json — NDJSON events (message/tool_use/result) + * --yolo — auto-approve tools (non-interactive) + * --skip-trust — trust cwd for this session; required when + * workdir is a temp/untrusted folder (benchmarks + * use mkdtemp). Without it headless gemini exits + * before calling the model. */ export class GeminiAdapter implements ProviderAdapter { readonly name = 'gemini'; @@ -129,8 +136,10 @@ export class GeminiAdapter implements ProviderAdapter { async run(opts: RunOpts): Promise { const start = Date.now(); // Default to --yolo (non-interactive) and stream-json output so we can parse - // tokens + tool calls. Callers can override via extraArgs. - const args = ['-p', opts.prompt, '--output-format', 'stream-json', '--yolo']; + // tokens + tool calls. --skip-trust is required for headless/temp workdirs + // (gemini CLI otherwise exits: "not running in a trusted directory"). + // Callers can override via extraArgs. + const args = ['-p', opts.prompt, '--output-format', 'stream-json', '--yolo', '--skip-trust']; if (opts.model) args.push('--model', opts.model); if (opts.extraArgs) args.push(...opts.extraArgs); From 19e3fd6bb927376b6ab6aa22e07da47b3b5c2ad6 Mon Sep 17 00:00:00 2001 From: Jizu Date: Fri, 10 Jul 2026 08:32:19 +0000 Subject: [PATCH 13/51] fix: copy supabase/config.sh in Kiro/Codex/Factory/OpenCode setup paths The setup script's non-Claude host paths (Kiro, Codex, Factory, OpenCode) use selective file linking rather than symlinking the entire repo root. This missed supabase/config.sh, causing gstack-telemetry-sync to silently exit (SUPABASE_URL empty) for all users on these hosts who opted into telemetry. Fixes #2215 --- setup | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/setup b/setup index 275236cd36..aeec4a012c 100755 --- a/setup +++ b/setup @@ -815,6 +815,11 @@ create_codex_runtime_root() { if [ -f "$gstack_dir/ETHOS.md" ]; then _link_or_copy "$gstack_dir/ETHOS.md" "$codex_gstack/ETHOS.md" fi + # supabase/config.sh — required by gstack-telemetry-sync to resolve GSTACK_SUPABASE_URL + if [ -f "$gstack_dir/supabase/config.sh" ]; then + mkdir -p "$codex_gstack/supabase" + _link_or_copy "$gstack_dir/supabase/config.sh" "$codex_gstack/supabase/config.sh" + fi } create_factory_runtime_root() { @@ -853,6 +858,11 @@ create_factory_runtime_root() { if [ -f "$gstack_dir/ETHOS.md" ]; then _link_or_copy "$gstack_dir/ETHOS.md" "$factory_gstack/ETHOS.md" fi + # supabase/config.sh — required by gstack-telemetry-sync to resolve GSTACK_SUPABASE_URL + if [ -f "$gstack_dir/supabase/config.sh" ]; then + mkdir -p "$factory_gstack/supabase" + _link_or_copy "$gstack_dir/supabase/config.sh" "$factory_gstack/supabase/config.sh" + fi } create_opencode_runtime_root() { @@ -906,6 +916,11 @@ create_opencode_runtime_root() { if [ -f "$gstack_dir/ETHOS.md" ]; then _link_or_copy "$gstack_dir/ETHOS.md" "$opencode_gstack/ETHOS.md" fi + # supabase/config.sh — required by gstack-telemetry-sync to resolve GSTACK_SUPABASE_URL + if [ -f "$gstack_dir/supabase/config.sh" ]; then + mkdir -p "$opencode_gstack/supabase" + _link_or_copy "$gstack_dir/supabase/config.sh" "$opencode_gstack/supabase/config.sh" + fi } link_factory_skill_dirs() { @@ -1121,6 +1136,11 @@ if [ "$INSTALL_KIRO" -eq 1 ]; then if [ -f "$SOURCE_GSTACK_DIR/ETHOS.md" ]; then _link_or_copy "$SOURCE_GSTACK_DIR/ETHOS.md" "$KIRO_GSTACK/ETHOS.md" fi + # supabase/config.sh — required by gstack-telemetry-sync to resolve GSTACK_SUPABASE_URL + if [ -f "$SOURCE_GSTACK_DIR/supabase/config.sh" ]; then + mkdir -p "$KIRO_GSTACK/supabase" + _link_or_copy "$SOURCE_GSTACK_DIR/supabase/config.sh" "$KIRO_GSTACK/supabase/config.sh" + fi # gstack-upgrade skill if [ -f "$AGENTS_DIR/gstack-upgrade/SKILL.md" ]; then _link_or_copy "$AGENTS_DIR/gstack-upgrade/SKILL.md" "$KIRO_GSTACK/gstack-upgrade/SKILL.md" From 8dd528df95a640465c4c6ced9390b19fd26f8f3c Mon Sep 17 00:00:00 2001 From: Franz Alarcon Date: Mon, 13 Jul 2026 13:09:12 -0700 Subject: [PATCH 14/51] fix(setup): copy lib/ into opencode runtime root MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cherry-picked from community PR #2198. bin/*.ts helpers import ../lib/*, which hard-fails on copy-mode installs where the runtime root has bin/ but no lib/. [wave adaptation: dropped the mkdir -p "$opencode_gstack/lib" hunk — pre-creating lib/ as a real directory makes ln -snf nest a lib/lib symlink inside it instead of replacing it; the link block alone is correct, matching the existing bin/ pattern.] Co-Authored-By: Claude Fable 5 --- setup | 3 +++ 1 file changed, 3 insertions(+) diff --git a/setup b/setup index aeec4a012c..69487ccdad 100755 --- a/setup +++ b/setup @@ -884,6 +884,9 @@ create_opencode_runtime_root() { if [ -d "$gstack_dir/bin" ]; then _link_or_copy "$gstack_dir/bin" "$opencode_gstack/bin" fi + if [ -d "$gstack_dir/lib" ]; then + _link_or_copy "$gstack_dir/lib" "$opencode_gstack/lib" + fi if [ -d "$gstack_dir/browse/dist" ]; then _link_or_copy "$gstack_dir/browse/dist" "$opencode_gstack/browse/dist" fi From 05261e54931c671fab648180f827a316c67c245f Mon Sep 17 00:00:00 2001 From: t Date: Mon, 13 Jul 2026 13:10:16 -0700 Subject: [PATCH 15/51] fix(setup): extend missing-lib fix to codex, factory, kiro roots and the .agents sidecar Same root cause as the opencode fix (community PR #2198): every runtime root links bin/ whose *.ts helpers import ../lib/*, so copy-mode (Windows) installs crash with module-not-found. Apply the identical lib/ link block to all four remaining bin-linking sites. Co-Authored-By: Claude Fable 5 --- setup | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/setup b/setup index 69487ccdad..a5dde5b41a 100755 --- a/setup +++ b/setup @@ -749,7 +749,8 @@ create_agents_sidecar() { mkdir -p "$agents_gstack" # Sidecar directories that skills reference at runtime - for asset in bin browse review qa; do + # (lib: bin/*.ts helpers import ../lib/*; required on copy-mode installs) + for asset in bin lib browse review qa; do local src="$SOURCE_GSTACK_DIR/$asset" local dst="$agents_gstack/$asset" if [ -d "$src" ] || [ -f "$src" ]; then @@ -796,6 +797,10 @@ create_codex_runtime_root() { if [ -d "$gstack_dir/bin" ]; then _link_or_copy "$gstack_dir/bin" "$codex_gstack/bin" fi + # lib/ — bin/*.ts helpers import ../lib/*; required on copy-mode installs + if [ -d "$gstack_dir/lib" ]; then + _link_or_copy "$gstack_dir/lib" "$codex_gstack/lib" + fi if [ -d "$gstack_dir/browse/dist" ]; then _link_or_copy "$gstack_dir/browse/dist" "$codex_gstack/browse/dist" fi @@ -841,6 +846,10 @@ create_factory_runtime_root() { if [ -d "$gstack_dir/bin" ]; then _link_or_copy "$gstack_dir/bin" "$factory_gstack/bin" fi + # lib/ — bin/*.ts helpers import ../lib/*; required on copy-mode installs + if [ -d "$gstack_dir/lib" ]; then + _link_or_copy "$gstack_dir/lib" "$factory_gstack/lib" + fi if [ -d "$gstack_dir/browse/dist" ]; then _link_or_copy "$gstack_dir/browse/dist" "$factory_gstack/browse/dist" fi @@ -1133,6 +1142,10 @@ if [ "$INSTALL_KIRO" -eq 1 ]; then [ -L "$KIRO_GSTACK" ] && rm -f "$KIRO_GSTACK" mkdir -p "$KIRO_GSTACK" "$KIRO_GSTACK/browse" "$KIRO_GSTACK/gstack-upgrade" "$KIRO_GSTACK/review" _link_or_copy "$SOURCE_GSTACK_DIR/bin" "$KIRO_GSTACK/bin" + # lib/ — bin/*.ts helpers import ../lib/*; required on copy-mode installs + if [ -d "$SOURCE_GSTACK_DIR/lib" ]; then + _link_or_copy "$SOURCE_GSTACK_DIR/lib" "$KIRO_GSTACK/lib" + fi _link_or_copy "$SOURCE_GSTACK_DIR/browse/dist" "$KIRO_GSTACK/browse/dist" _link_or_copy "$SOURCE_GSTACK_DIR/browse/bin" "$KIRO_GSTACK/browse/bin" # ETHOS.md — referenced by "Search Before Building" in all skill preambles From 4fe6b215201e48acec6e34ed7f9ff8ccc02e83ff Mon Sep 17 00:00:00 2001 From: Jayesh Betala Date: Thu, 14 May 2026 17:29:14 +0530 Subject: [PATCH 16/51] fix(setup): clarify Hermes host banner --- README.md | 2 +- setup | 9 +++++++-- test/gen-skill-docs.test.ts | 13 +++++++++++++ 3 files changed, 21 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 121f42099c..81e2d7b452 100644 --- a/README.md +++ b/README.md @@ -119,7 +119,7 @@ Or target a specific agent with `./setup --host `: | Factory Droid | `--host factory` | `~/.factory/skills/gstack-*/` | | Slate | `--host slate` | `~/.slate/skills/gstack-*/` | | Kiro | `--host kiro` | `~/.kiro/skills/gstack-*/` | -| Hermes | `--host hermes` | `~/.hermes/skills/gstack-*/` | +| Hermes | `--host hermes` | Prints integration instructions; `bun run gen:skill-docs --host hermes` writes `.hermes/skills/` | | GBrain (mod) | `--host gbrain` | `~/.gbrain/skills/gstack-*/` | **Want to add support for another agent?** See [docs/ADDING_A_HOST.md](docs/ADDING_A_HOST.md). diff --git a/setup b/setup index a5dde5b41a..be0b63087d 100755 --- a/setup +++ b/setup @@ -116,12 +116,17 @@ case "$HOST" in exit 0 ;; hermes) echo "" - echo "Hermes integration uses the same model as OpenClaw — Hermes spawns" + echo "Hermes integration uses the same model as OpenClaw: Hermes spawns" echo "Claude Code sessions, and gstack provides methodology artifacts." echo "" + echo "./setup --host hermes does not install files into Hermes today." + echo "It only prints integration instructions." + echo "" echo "To integrate gstack with Hermes:" echo " 1. Tell your Hermes agent: 'install gstack for hermes'" - echo " 2. Or generate artifacts: bun run gen:skill-docs --host hermes" + echo " 2. Or generate reviewable artifacts locally:" + echo " bun run gen:skill-docs --host hermes" + echo " This writes .hermes/skills/ in this checkout." echo "" exit 0 ;; gbrain) diff --git a/test/gen-skill-docs.test.ts b/test/gen-skill-docs.test.ts index 2fb783ffd0..bdff89e779 100644 --- a/test/gen-skill-docs.test.ts +++ b/test/gen-skill-docs.test.ts @@ -2377,6 +2377,19 @@ describe('setup script validation', () => { expect(setupContent).toContain('claude|codex|kiro|factory|opencode|auto'); }); + test('Hermes host banner is explicit that setup is not an installer', () => { + const hermesStart = setupContent.indexOf(' hermes)'); + const hermesEnd = setupContent.indexOf(' gbrain)', hermesStart); + expect(hermesStart).toBeGreaterThan(-1); + expect(hermesEnd).toBeGreaterThan(hermesStart); + + const hermesBlock = setupContent.slice(hermesStart, hermesEnd); + expect(hermesBlock).toContain('./setup --host hermes does not install files into Hermes today.'); + expect(hermesBlock).toContain('It only prints integration instructions.'); + expect(hermesBlock).toContain('bun run gen:skill-docs --host hermes'); + expect(hermesBlock).toContain('This writes .hermes/skills/ in this checkout.'); + }); + test('auto mode detects claude, codex, kiro, and opencode binaries', () => { expect(setupContent).toContain('command -v claude'); expect(setupContent).toContain('command -v codex'); From 269c63c4ac2441bc34744dc9baee7c255b7f0fd1 Mon Sep 17 00:00:00 2001 From: dkoh12 Date: Sat, 18 Apr 2026 02:15:04 +0000 Subject: [PATCH 17/51] fix: namespace generated Hermes skill names Co-authored-by: Hermes Agent (GitHub Copilot GPT-5.4) --- hosts/hermes.ts | 1 + scripts/gen-skill-docs.ts | 13 ++++++++----- scripts/host-config.ts | 2 ++ test/gen-skill-docs.test.ts | 18 ++++++++++++++++++ 4 files changed, 29 insertions(+), 5 deletions(-) diff --git a/hosts/hermes.ts b/hosts/hermes.ts index 43598989df..7687eda053 100644 --- a/hosts/hermes.ts +++ b/hosts/hermes.ts @@ -15,6 +15,7 @@ const hermes: HostConfig = { mode: 'allowlist', keepFields: ['name', 'description'], descriptionLimit: null, + nameTransform: 'external-skill-name', }, generation: { diff --git a/scripts/gen-skill-docs.ts b/scripts/gen-skill-docs.ts index 71aa1a34ca..856e275b44 100644 --- a/scripts/gen-skill-docs.ts +++ b/scripts/gen-skill-docs.ts @@ -507,7 +507,7 @@ policy: * Codex: keeps name + description only, enforces 1024-char limit. * Factory: keeps name + description + user-invocable, conditionally adds disable-model-invocation. */ -function transformFrontmatter(content: string, host: Host): string { +function transformFrontmatter(content: string, host: Host, generatedSkillName?: string): string { const hostConfig = getHostConfig(host); const fm = hostConfig.frontmatter; @@ -531,6 +531,9 @@ function transformFrontmatter(content: string, host: Host): string { const frontmatter = content.slice(fmStart + 4, fmEnd); const body = content.slice(fmEnd + 4); const { name, description } = extractNameAndDescription(content); + const emittedName = fm.nameTransform === 'external-skill-name' && generatedSkillName + ? generatedSkillName + : name; // Description limit enforcement if (fm.descriptionLimit) { @@ -538,11 +541,11 @@ function transformFrontmatter(content: string, host: Host): string { if (description.length > fm.descriptionLimit) { if (behavior === 'error') { throw new Error( - `${hostConfig.displayName} description for "${name}" is ${description.length} chars (max ${fm.descriptionLimit}). ` + + `${hostConfig.displayName} description for "${emittedName}" is ${description.length} chars (max ${fm.descriptionLimit}). ` + `Compress the description in the .tmpl file.` ); } else if (behavior === 'warn') { - console.warn(`WARNING: ${hostConfig.displayName} description for "${name}" exceeds ${fm.descriptionLimit} chars`); + console.warn(`WARNING: ${hostConfig.displayName} description for "${emittedName}" exceeds ${fm.descriptionLimit} chars`); } // 'truncate' — silently proceed } @@ -550,7 +553,7 @@ function transformFrontmatter(content: string, host: Host): string { // Build frontmatter with allowed fields const indentedDesc = description.split('\n').map(l => ` ${l}`).join('\n'); - let newFm = `---\nname: ${name}\ndescription: |\n${indentedDesc}\n`; + let newFm = `---\nname: ${emittedName}\ndescription: |\n${indentedDesc}\n`; // Add extra fields (host-wide) if (fm.extraFields) { @@ -772,7 +775,7 @@ function processExternalHost( const safetyProse = extractHookSafetyProse(tmplContent); // Transform frontmatter (host-aware) - let result = transformFrontmatter(content, host); + let result = transformFrontmatter(content, host, name); // Insert safety advisory at the top of the body (after frontmatter) if (safetyProse) { diff --git a/scripts/host-config.ts b/scripts/host-config.ts index 4421c4a799..cd9503027f 100644 --- a/scripts/host-config.ts +++ b/scripts/host-config.ts @@ -46,6 +46,8 @@ export interface HostConfig { descriptionLimit?: number | null; /** What to do when description exceeds limit. Default: 'error'. */ descriptionLimitBehavior?: 'error' | 'truncate' | 'warn'; + /** Override the emitted frontmatter name for generated skills. */ + nameTransform?: 'identity' | 'external-skill-name'; /** Additional frontmatter fields to inject (host-wide). */ extraFields?: Record; /** Rename fields from template (e.g., { 'voice-triggers': 'triggers' }). */ diff --git a/test/gen-skill-docs.test.ts b/test/gen-skill-docs.test.ts index bdff89e779..b3019ed030 100644 --- a/test/gen-skill-docs.test.ts +++ b/test/gen-skill-docs.test.ts @@ -2205,6 +2205,24 @@ describe('Parameterized host smoke tests', () => { expect(content).toContain('--disallowedTools Bash,Edit,Write'); }); + if (hostConfig.name === 'hermes') { + test('Hermes frontmatter names are namespaced to match generated skill names', () => { + Bun.spawnSync(['bun', 'run', 'scripts/gen-skill-docs.ts', '--host', 'hermes'], { + cwd: ROOT, stdout: 'pipe', stderr: 'pipe', + }); + + const reviewContent = fs.readFileSync(path.join(hostDir, 'gstack-review', 'SKILL.md'), 'utf-8'); + const qaContent = fs.readFileSync(path.join(hostDir, 'gstack-qa', 'SKILL.md'), 'utf-8'); + const shipContent = fs.readFileSync(path.join(hostDir, 'gstack-ship', 'SKILL.md'), 'utf-8'); + const rootContent = fs.readFileSync(path.join(hostDir, 'gstack', 'SKILL.md'), 'utf-8'); + + expect(reviewContent).toMatch(/^name:\s*gstack-review$/m); + expect(qaContent).toMatch(/^name:\s*gstack-qa$/m); + expect(shipContent).toMatch(/^name:\s*gstack-ship$/m); + expect(rootContent).toMatch(/^name:\s*gstack$/m); + }); + } + test('--dry-run freshness check passes', () => { const result = Bun.spawnSync( ['bun', 'run', 'scripts/gen-skill-docs.ts', '--host', hostConfig.name, '--dry-run'], From 944c5f1fbce48a3252e516e84ea11d1a71662405 Mon Sep 17 00:00:00 2001 From: spacegeologist Date: Thu, 28 May 2026 09:47:11 +0800 Subject: [PATCH 18/51] Fix Claude Code auth preflight for Codex host --- claude/SKILL.md.tmpl | 28 ++++++++++++---------------- test/gen-skill-docs.test.ts | 2 ++ 2 files changed, 14 insertions(+), 16 deletions(-) diff --git a/claude/SKILL.md.tmpl b/claude/SKILL.md.tmpl index 94552cbe4e..9bf77f3f6f 100644 --- a/claude/SKILL.md.tmpl +++ b/claude/SKILL.md.tmpl @@ -42,18 +42,10 @@ CLAUDE_BIN=$(command -v claude 2>/dev/null || echo "") If `NOT_FOUND`, stop and tell the user: "Claude CLI not found. Install Claude Code, then re-run this skill." -Check auth: - -```bash -if [ -f "$HOME/.claude/.credentials.json" ] || [ -n "${ANTHROPIC_API_KEY:-}" ]; then - echo "AUTH_FOUND" -else - echo "AUTH_MISSING" -fi -``` - -If `AUTH_MISSING`, stop and tell the user: -"No Claude authentication found. Run `claude` interactively to log in, or export `ANTHROPIC_API_KEY`, then re-run this skill." +Do not preflight Claude authentication by checking credential files. Claude Code +may store login state in OS keychain or another host-managed location that is not +visible to this skill. Treat the first `claude -p` invocation as the auth check, +then surface any login/auth failure from its JSON or stderr output. --- @@ -117,10 +109,14 @@ except Exception as exc: print(f"CLAUDE_JSON_PARSE_ERROR: {exc}") sys.exit(0) +result = obj.get("result") or obj.get("response") or "" +result_lower = result.lower() + if obj.get("is_error"): print("CLAUDE_ERROR: true") + if any(term in result_lower for term in ("auth", "login", "unauthorized", "not logged in")): + print("CLAUDE_AUTH_ERROR: true") -result = obj.get("result") or obj.get("response") or "" if result: print(result) @@ -137,7 +133,8 @@ if session_id: PY ``` -If stderr contains `auth`, `login`, or `unauthorized`, tell the user: +If the parsed output contains `CLAUDE_AUTH_ERROR: true`, or stderr contains +`auth`, `login`, `unauthorized`, or `not logged in`, tell the user: "Claude authentication failed. Run `claude` interactively to authenticate or export `ANTHROPIC_API_KEY`." --- @@ -324,8 +321,7 @@ rm -f "$PROMPT_FILE" "$RESP_FILE" "$ERR_FILE" ## Error Handling - **Binary not found:** Stop with install instructions. -- **Auth missing:** Stop with login/API key instructions. -- **Auth failure from stderr:** Surface the stderr line and ask the user to re-authenticate. +- **Auth failure from Claude output or stderr:** Surface the auth line and ask the user to re-authenticate. - **JSON parse failure:** Show raw stdout from `$RESP_FILE` and stderr from `$ERR_FILE`. - **Empty response:** Tell the user "Claude returned no response. Check stderr for errors." - **Resume failure:** Delete `.context/claude-session-id` and retry with a fresh session. diff --git a/test/gen-skill-docs.test.ts b/test/gen-skill-docs.test.ts index b3019ed030..52563ccc33 100644 --- a/test/gen-skill-docs.test.ts +++ b/test/gen-skill-docs.test.ts @@ -1785,6 +1785,8 @@ describe('Codex generation (--host codex)', () => { expect(content).toContain('--allowedTools Read,Grep,Glob'); expect(content).toContain('--disallowedTools Bash,Edit,Write'); expect(content).toContain('is_error'); + expect(content).toContain('CLAUDE_AUTH_ERROR'); + expect(content).not.toContain('.credentials.json'); }); test('Codex review step stripped from Codex-host ship and review', () => { From d1ac27998e860200be7773649914cf9813bb603b Mon Sep 17 00:00:00 2001 From: "Mammad M." Date: Mon, 13 Jul 2026 13:12:04 -0700 Subject: [PATCH 19/51] Fix Codex design binary path resolution Cherry-picked from community PR #1160: resolvers emitted broken $HOME$GSTACK_* doubled-home fallback paths for env-var hosts, and the codex runtime root/sidecar never linked design/dist. [wave adaptations: converted the PR's new design/dist link from raw ln -snf to _link_or_copy (setup-windows-fallback invariant); merged the sidecar asset list with the wave's lib/ addition.] Co-Authored-By: Claude Fable 5 --- hosts/codex.ts | 4 ++-- scripts/resolvers/browse.ts | 8 +++++++- scripts/resolvers/design.ts | 13 ++++++++---- setup | 9 ++++++--- test/codex-design-paths.test.ts | 36 +++++++++++++++++++++++++++++++++ test/gen-skill-docs.test.ts | 4 +++- test/host-config.test.ts | 1 + 7 files changed, 64 insertions(+), 11 deletions(-) create mode 100644 test/codex-design-paths.test.ts diff --git a/hosts/codex.ts b/hosts/codex.ts index 7dc80ea877..7334157460 100644 --- a/hosts/codex.ts +++ b/hosts/codex.ts @@ -42,14 +42,14 @@ const codex: HostConfig = { ], runtimeRoot: { - globalSymlinks: ['bin', 'browse/dist', 'browse/bin', 'gstack-upgrade', 'ETHOS.md'], + globalSymlinks: ['bin', 'browse/dist', 'browse/bin', 'design/dist', 'gstack-upgrade', 'ETHOS.md'], globalFiles: { 'review': ['checklist.md', 'TODOS-format.md'], }, }, sidecar: { path: '.agents/skills/gstack', - symlinks: ['bin', 'browse', 'review', 'qa', 'ETHOS.md'], + symlinks: ['bin', 'browse', 'design', 'review', 'qa', 'ETHOS.md'], }, install: { diff --git a/scripts/resolvers/browse.ts b/scripts/resolvers/browse.ts index a0ae37a70e..0f4d5dd7a7 100644 --- a/scripts/resolvers/browse.ts +++ b/scripts/resolvers/browse.ts @@ -2,6 +2,12 @@ import type { TemplateContext } from './types'; import { COMMAND_DESCRIPTIONS } from '../../browse/src/commands'; import { SNAPSHOT_FLAGS } from '../../browse/src/snapshot'; +function resolveBinaryPath(dirExpr: string, binaryName: string): string { + return dirExpr.startsWith('$') + ? `${dirExpr}/${binaryName}` + : `$HOME${dirExpr.replace(/^~/, '')}/${binaryName}`; +} + export function generateCommandReference(_ctx: TemplateContext): string { // Group commands by category const groups = new Map>(); @@ -106,7 +112,7 @@ export function generateBrowseSetup(ctx: TemplateContext): string { _ROOT=$(git rev-parse --show-toplevel 2>/dev/null) B="" [ -n "$_ROOT" ] && [ -x "$_ROOT/${ctx.paths.localSkillRoot}/browse/dist/browse" ] && B="$_ROOT/${ctx.paths.localSkillRoot}/browse/dist/browse" -[ -z "$B" ] && B="$HOME${ctx.paths.browseDir.replace(/^~/, '')}/browse" +[ -z "$B" ] && B="${resolveBinaryPath(ctx.paths.browseDir, 'browse')}" if [ -x "$B" ]; then echo "READY: $B" else diff --git a/scripts/resolvers/design.ts b/scripts/resolvers/design.ts index 9f31b36197..c23c8cb477 100644 --- a/scripts/resolvers/design.ts +++ b/scripts/resolvers/design.ts @@ -1,6 +1,12 @@ import type { TemplateContext } from './types'; import { AI_SLOP_BLACKLIST, OPENAI_HARD_REJECTIONS, OPENAI_LITMUS_CHECKS } from './constants'; +function resolveBinaryPath(dirExpr: string, binaryName: string): string { + return dirExpr.startsWith('$') + ? `${dirExpr}/${binaryName}` + : `$HOME${dirExpr.replace(/^~/, '')}/${binaryName}`; +} + export function generateDesignReviewLite(ctx: TemplateContext): string { const litmusList = OPENAI_LITMUS_CHECKS.map((item, i) => `${i + 1}. ${item}`).join(' '); const rejectionList = OPENAI_HARD_REJECTIONS.map((item, i) => `${i + 1}. ${item}`).join(' '); @@ -792,7 +798,7 @@ export function generateDesignSetup(ctx: TemplateContext): string { _ROOT=$(git rev-parse --show-toplevel 2>/dev/null) D="" [ -n "$_ROOT" ] && [ -x "$_ROOT/${ctx.paths.localSkillRoot}/design/dist/design" ] && D="$_ROOT/${ctx.paths.localSkillRoot}/design/dist/design" -[ -z "$D" ] && D="$HOME${ctx.paths.designDir.replace(/^~/, '')}/design" +[ -z "$D" ] && D="${resolveBinaryPath(ctx.paths.designDir, 'design')}" if [ -x "$D" ]; then echo "DESIGN_READY: $D" else @@ -800,7 +806,7 @@ else fi B="" [ -n "$_ROOT" ] && [ -x "$_ROOT/${ctx.paths.localSkillRoot}/browse/dist/browse" ] && B="$_ROOT/${ctx.paths.localSkillRoot}/browse/dist/browse" -[ -z "$B" ] && B="$HOME${ctx.paths.browseDir.replace(/^~/, '')}/browse" +[ -z "$B" ] && B="${resolveBinaryPath(ctx.paths.browseDir, 'browse')}" if [ -x "$B" ]; then echo "BROWSE_READY: $B" else @@ -837,7 +843,7 @@ export function generateDesignMockup(ctx: TemplateContext): string { _ROOT=$(git rev-parse --show-toplevel 2>/dev/null) D="" [ -n "$_ROOT" ] && [ -x "$_ROOT/${ctx.paths.localSkillRoot}/design/dist/design" ] && D="$_ROOT/${ctx.paths.localSkillRoot}/design/dist/design" -[ -z "$D" ] && D="$HOME${ctx.paths.designDir.replace(/^~/, '')}/design" +[ -z "$D" ] && D="${resolveBinaryPath(ctx.paths.designDir, 'design')}" [ -x "$D" ] && echo "DESIGN_READY" || echo "DESIGN_NOT_AVAILABLE" \`\`\` @@ -1154,4 +1160,3 @@ Flat design can strip away useful visual information that signals interactivity. Prioritize ruthlessly: things needed in a hurry go close at hand, everything else a few taps away with an obvious path to get there.`; } - diff --git a/setup b/setup index be0b63087d..c6eb389c06 100755 --- a/setup +++ b/setup @@ -746,7 +746,7 @@ link_codex_skill_dirs() { # ─── Helper: create .agents/skills/gstack/ sidecar symlinks ────────── # Codex/Gemini/Cursor read skills from .agents/skills/. We link runtime -# assets (bin/, browse/dist/, review/, qa/, etc.) so skill templates can +# assets (bin/, browse/dist/, design/dist/, review/, qa/, etc.) so skill templates can # resolve paths like $SKILL_ROOT/review/design-checklist.md. create_agents_sidecar() { local repo_root="$1" @@ -755,7 +755,7 @@ create_agents_sidecar() { # Sidecar directories that skills reference at runtime # (lib: bin/*.ts helpers import ../lib/*; required on copy-mode installs) - for asset in bin lib browse review qa; do + for asset in bin lib browse design review qa; do local src="$SOURCE_GSTACK_DIR/$asset" local dst="$agents_gstack/$asset" if [ -d "$src" ] || [ -f "$src" ]; then @@ -794,7 +794,7 @@ create_codex_runtime_root() { rm -rf "$codex_gstack" fi - mkdir -p "$codex_gstack" "$codex_gstack/browse" "$codex_gstack/gstack-upgrade" "$codex_gstack/review" + mkdir -p "$codex_gstack" "$codex_gstack/browse" "$codex_gstack/design" "$codex_gstack/gstack-upgrade" "$codex_gstack/review" if [ -f "$agents_dir/gstack/SKILL.md" ]; then _link_or_copy "$agents_dir/gstack/SKILL.md" "$codex_gstack/SKILL.md" @@ -812,6 +812,9 @@ create_codex_runtime_root() { if [ -d "$gstack_dir/browse/bin" ]; then _link_or_copy "$gstack_dir/browse/bin" "$codex_gstack/browse/bin" fi + if [ -d "$gstack_dir/design/dist" ]; then + _link_or_copy "$gstack_dir/design/dist" "$codex_gstack/design/dist" + fi if [ -f "$agents_dir/gstack-upgrade/SKILL.md" ]; then _link_or_copy "$agents_dir/gstack-upgrade/SKILL.md" "$codex_gstack/gstack-upgrade/SKILL.md" fi diff --git a/test/codex-design-paths.test.ts b/test/codex-design-paths.test.ts new file mode 100644 index 0000000000..4b76127468 --- /dev/null +++ b/test/codex-design-paths.test.ts @@ -0,0 +1,36 @@ +import { describe, expect, test } from 'bun:test'; +import type { TemplateContext } from '../scripts/resolvers/types'; +import { HOST_PATHS } from '../scripts/resolvers/types'; +import { generateBrowseSetup } from '../scripts/resolvers/browse'; +import { generateDesignMockup, generateDesignSetup } from '../scripts/resolvers/design'; + +function makeCodexCtx(): TemplateContext { + return { + skillName: 'test-skill', + tmplPath: 'test.tmpl', + host: 'codex', + paths: HOST_PATHS.codex, + }; +} + +describe('Codex design/browse path generation', () => { + test('generated Codex browse setup uses GSTACK_BROWSE directly', () => { + const out = generateBrowseSetup(makeCodexCtx()); + expect(out).toContain('B="$GSTACK_BROWSE/browse"'); + expect(out).not.toContain('$HOME$GSTACK_BROWSE'); + }); + + test('generated Codex design setup uses GSTACK_DESIGN and GSTACK_BROWSE directly', () => { + const out = generateDesignSetup(makeCodexCtx()); + expect(out).toContain('D="$GSTACK_DESIGN/design"'); + expect(out).toContain('B="$GSTACK_BROWSE/browse"'); + expect(out).not.toContain('$HOME$GSTACK_DESIGN'); + expect(out).not.toContain('$HOME$GSTACK_BROWSE'); + }); + + test('generated Codex design mockup uses GSTACK_DESIGN directly', () => { + const out = generateDesignMockup(makeCodexCtx()); + expect(out).toContain('D="$GSTACK_DESIGN/design"'); + expect(out).not.toContain('$HOME$GSTACK_DESIGN'); + }); +}); diff --git a/test/gen-skill-docs.test.ts b/test/gen-skill-docs.test.ts index 52563ccc33..43f504f01a 100644 --- a/test/gen-skill-docs.test.ts +++ b/test/gen-skill-docs.test.ts @@ -2457,12 +2457,13 @@ describe('setup script validation', () => { }); test('create_agents_sidecar links runtime assets', () => { - // Sidecar must link bin, browse, review, qa + // Sidecar must link bin, browse, design, review, qa const fnStart = setupContent.indexOf('create_agents_sidecar()'); const fnEnd = setupContent.indexOf('}', setupContent.indexOf('done', fnStart)); const fnBody = setupContent.slice(fnStart, fnEnd); expect(fnBody).toContain('bin'); expect(fnBody).toContain('browse'); + expect(fnBody).toContain('design'); expect(fnBody).toContain('review'); expect(fnBody).toContain('qa'); }); @@ -2474,6 +2475,7 @@ describe('setup script validation', () => { expect(fnBody).toContain('gstack/SKILL.md'); expect(fnBody).toContain('browse/dist'); expect(fnBody).toContain('browse/bin'); + expect(fnBody).toContain('design/dist'); expect(fnBody).toContain('gstack-upgrade/SKILL.md'); // Review runtime assets (individual files, not the whole dir) expect(fnBody).toContain('checklist.md'); diff --git a/test/host-config.test.ts b/test/host-config.test.ts index 5770570332..ee53f42318 100644 --- a/test/host-config.test.ts +++ b/test/host-config.test.ts @@ -350,6 +350,7 @@ describe('host-config-export.ts CLI', () => { expect(exitCode).toBe(0); const lines = stdout.split('\n'); expect(lines).toContain('bin'); + expect(lines).toContain('design/dist'); expect(lines).toContain('ETHOS.md'); expect(lines).toContain('review/checklist.md'); }); From df1fbf6356b0889f29a8efd7d3bd716b03bde5b1 Mon Sep 17 00:00:00 2001 From: dpattonux Date: Sat, 27 Jun 2026 18:41:32 -0400 Subject: [PATCH 20/51] Align Codex install paths with current skill spec --- README.md | 6 +++--- docs/REMOTE_BROWSER_ACCESS.md | 2 +- hosts/codex.ts | 2 +- setup | 14 ++++++++------ test/fixtures/golden/codex-ship-SKILL.md | 2 +- test/gen-skill-docs.test.ts | 2 +- test/helpers/codex-session-runner.ts | 6 +++--- test/host-config.test.ts | 2 +- 8 files changed, 19 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 81e2d7b452..1fcda0b1c6 100644 --- a/README.md +++ b/README.md @@ -113,7 +113,7 @@ Or target a specific agent with `./setup --host `: | Agent | Flag | Skills install to | |-------|------|-------------------| -| OpenAI Codex CLI | `--host codex` | `~/.codex/skills/gstack-*/` | +| OpenAI Codex CLI | `--host codex` | `~/.agents/skills/gstack-*/` | | OpenCode | `--host opencode` | `~/.config/opencode/skills/gstack-*/` | | Cursor | `--host cursor` | `~/.cursor/skills/gstack-*/` | | Factory Droid | `--host factory` | `~/.factory/skills/gstack-*/` | @@ -356,7 +356,7 @@ rm -rf ~/.claude/skills/gstack rm -rf ~/.gstack # 5. Remove integrations (skip any you never installed) -rm -rf ~/.codex/skills/gstack* 2>/dev/null +rm -rf ~/.agents/skills/gstack* ~/.codex/skills/gstack* 2>/dev/null rm -rf ~/.factory/skills/gstack* 2>/dev/null rm -rf ~/.kiro/skills/gstack* 2>/dev/null rm -rf ~/.openclaw/skills/gstack* 2>/dev/null @@ -466,7 +466,7 @@ Data is stored in [Supabase](https://supabase.com) (open source Firebase alterna **Want namespaced commands?** `cd ~/.claude/skills/gstack && ./setup --prefix` — switches from `/qa` to `/gstack-qa`. Useful if you run other skill packs alongside gstack. -**Codex says "Skipped loading skill(s) due to invalid SKILL.md"?** Your Codex skill descriptions are stale. Fix: `cd ~/.codex/skills/gstack && git pull && ./setup --host codex` — or for repo-local installs: `cd "$(readlink -f .agents/skills/gstack)" && git pull && ./setup --host codex` +**Codex says "Skipped loading skill(s) due to invalid SKILL.md"?** Your Codex skill descriptions are stale. Fix: `cd ~/.agents/skills/gstack && git pull && ./setup --host codex` — or for repo-local installs: `cd "$(readlink -f .agents/skills/gstack)" && git pull && ./setup --host codex` **Windows users:** gstack works on Windows 11 via Git Bash or WSL. Node.js is required in addition to Bun — Bun has a known bug with Playwright's pipe transport on Windows ([bun#4253](https://github.com/oven-sh/bun/issues/4253)). The browse server automatically falls back to Node.js. Make sure both `bun` and `node` are on your PATH. diff --git a/docs/REMOTE_BROWSER_ACCESS.md b/docs/REMOTE_BROWSER_ACCESS.md index 88dc30bb2a..a2b7a57f06 100644 --- a/docs/REMOTE_BROWSER_ACCESS.md +++ b/docs/REMOTE_BROWSER_ACCESS.md @@ -186,7 +186,7 @@ If both agents are on the same machine, skip the copy-paste: ```bash $B pair-agent --local openclaw # writes to ~/.openclaw/skills/gstack/browse-remote.json -$B pair-agent --local codex # writes to ~/.codex/skills/gstack/browse-remote.json +$B pair-agent --local codex # writes to ~/.agents/skills/gstack/browse-remote.json $B pair-agent --local cursor # writes to ~/.cursor/skills/gstack/browse-remote.json ``` diff --git a/hosts/codex.ts b/hosts/codex.ts index 7334157460..98dda288ff 100644 --- a/hosts/codex.ts +++ b/hosts/codex.ts @@ -6,7 +6,7 @@ const codex: HostConfig = { cliCommand: 'codex', cliAliases: ['agents'], - globalRoot: '.codex/skills/gstack', + globalRoot: '.agents/skills/gstack', localSkillRoot: '.agents/skills/gstack', hostSubdir: '.agents', usesEnvVars: true, diff --git a/setup b/setup index c6eb389c06..4715cafecc 100755 --- a/setup +++ b/setup @@ -18,7 +18,7 @@ INSTALL_GSTACK_DIR="$(cd "$(dirname "$0")" && pwd)" SOURCE_GSTACK_DIR="$(cd "$(dirname "$0")" && pwd -P)" INSTALL_SKILLS_DIR="$(dirname "$INSTALL_GSTACK_DIR")" BROWSE_BIN="$SOURCE_GSTACK_DIR/browse/dist/browse" -CODEX_SKILLS="$HOME/.codex/skills" +CODEX_SKILLS="$HOME/.agents/skills" CODEX_GSTACK="$CODEX_SKILLS/gstack" FACTORY_SKILLS="$HOME/.factory/skills" FACTORY_GSTACK="$FACTORY_SKILLS/gstack" @@ -777,8 +777,8 @@ create_agents_sidecar() { done } -# ─── Helper: create a minimal ~/.codex/skills/gstack runtime root ─────────── -# Codex scans ~/.codex/skills recursively. Exposing the whole repo here causes +# ─── Helper: create a minimal ~/.agents/skills/gstack runtime root ─────────── +# Codex scans ~/.agents/skills recursively. Exposing the whole repo here causes # duplicate skills because source SKILL.md files and generated Codex skills are # both discoverable. Keep this directory limited to runtime assets + root skill. create_codex_runtime_root() { @@ -1190,9 +1190,10 @@ if [ "$INSTALL_KIRO" -eq 1 ]; then skill_name="$(basename "$skill_dir")" target_dir="$KIRO_SKILLS/$skill_name" mkdir -p "$target_dir" - # Generated Codex skills use $HOME/.codex (not ~/), plus $GSTACK_ROOT variables. + # Generated Codex skills use $HOME/.agents (not ~/), plus $GSTACK_ROOT variables. # Rewrite the default GSTACK_ROOT value and any remaining literal paths. - sed -e 's|\$HOME/.codex/skills/gstack|$HOME/.kiro/skills/gstack|g' \ + sed -e 's|\$HOME/.agents/skills/gstack|$HOME/.kiro/skills/gstack|g' \ + -e 's|\$HOME/.codex/skills/gstack|$HOME/.kiro/skills/gstack|g' \ -e "s|~/.codex/skills/gstack|~/.kiro/skills/gstack|g" \ -e "s|~/.claude/skills/gstack|~/.kiro/skills/gstack|g" \ "$skill_dir/SKILL.md" > "$target_dir/SKILL.md" @@ -1204,7 +1205,8 @@ if [ "$INSTALL_KIRO" -eq 1 ]; then mkdir -p "$target_dir/sections" for section_file in "$skill_dir/sections"/*; do [ -f "$section_file" ] || continue - sed -e 's|\$HOME/.codex/skills/gstack|$HOME/.kiro/skills/gstack|g' \ + sed -e 's|\$HOME/.agents/skills/gstack|$HOME/.kiro/skills/gstack|g' \ + -e 's|\$HOME/.codex/skills/gstack|$HOME/.kiro/skills/gstack|g' \ -e "s|~/.codex/skills/gstack|~/.kiro/skills/gstack|g" \ -e "s|~/.claude/skills/gstack|~/.kiro/skills/gstack|g" \ "$section_file" > "$target_dir/sections/$(basename "$section_file")" diff --git a/test/fixtures/golden/codex-ship-SKILL.md b/test/fixtures/golden/codex-ship-SKILL.md index d99630c4b3..6de7db72a7 100644 --- a/test/fixtures/golden/codex-ship-SKILL.md +++ b/test/fixtures/golden/codex-ship-SKILL.md @@ -14,7 +14,7 @@ description: | ```bash _ROOT=$(git rev-parse --show-toplevel 2>/dev/null) -GSTACK_ROOT="$HOME/.codex/skills/gstack" +GSTACK_ROOT="$HOME/.agents/skills/gstack" [ -n "$_ROOT" ] && [ -d "$_ROOT/.agents/skills/gstack" ] && GSTACK_ROOT="$_ROOT/.agents/skills/gstack" GSTACK_BIN="$GSTACK_ROOT/bin" GSTACK_BROWSE="$GSTACK_ROOT/browse/dist" diff --git a/test/gen-skill-docs.test.ts b/test/gen-skill-docs.test.ts index 43f504f01a..f2b2a82692 100644 --- a/test/gen-skill-docs.test.ts +++ b/test/gen-skill-docs.test.ts @@ -2485,7 +2485,7 @@ describe('setup script validation', () => { expect(fnBody).not.toContain('_link_or_copy "$gstack_dir" "$codex_gstack"'); }); - test('direct Codex installs are migrated out of ~/.codex/skills/gstack', () => { + test('direct Codex installs are migrated out of ~/.agents/skills/gstack', () => { expect(setupContent).toContain('migrate_direct_codex_install'); expect(setupContent).toContain('$HOME/.gstack/repos/gstack'); expect(setupContent).toContain('avoid duplicate skill discovery'); diff --git a/test/helpers/codex-session-runner.ts b/test/helpers/codex-session-runner.ts index 404aa6bb24..eafce32cb6 100644 --- a/test/helpers/codex-session-runner.ts +++ b/test/helpers/codex-session-runner.ts @@ -9,7 +9,7 @@ * - Uses `codex exec` instead of `claude -p` * - Output is JSONL with different event types (item.completed, turn.completed, thread.started) * - Uses `--json` flag instead of `--output-format stream-json` - * - Needs temp HOME with skill installed at ~/.codex/skills/{skillName}/SKILL.md + * - Needs temp HOME with skill installed at ~/.agents/skills/{skillName}/SKILL.md */ import * as fs from 'fs'; @@ -100,7 +100,7 @@ export function parseCodexJSONL(lines: string[]): ParsedCodexJSONL { /** * Install a SKILL.md into a temp HOME directory for Codex to discover. - * Creates ~/.codex/skills/{skillName}/SKILL.md in the temp HOME and copies + * Creates ~/.agents/skills/{skillName}/SKILL.md in the temp HOME and copies * agents/openai.yaml when present so Codex sees the same metadata as a real install. * * Returns the temp HOME path. Caller is responsible for cleanup. @@ -111,7 +111,7 @@ export function installSkillToTempHome( tempHome?: string, ): string { const home = tempHome || fs.mkdtempSync(path.join(os.tmpdir(), 'codex-e2e-')); - const destDir = path.join(home, '.codex', 'skills', skillName); + const destDir = path.join(home, '.agents', 'skills', skillName); fs.mkdirSync(destDir, { recursive: true }); const srcSkill = path.join(skillDir, 'SKILL.md'); diff --git a/test/host-config.test.ts b/test/host-config.test.ts index ee53f42318..5d042dab32 100644 --- a/test/host-config.test.ts +++ b/test/host-config.test.ts @@ -314,7 +314,7 @@ describe('host-config-export.ts CLI', () => { test('get returns string field', () => { const { stdout, exitCode } = run('get', 'codex', 'globalRoot'); expect(exitCode).toBe(0); - expect(stdout).toBe('.codex/skills/gstack'); + expect(stdout).toBe('.agents/skills/gstack'); }); test('get returns boolean as 1/0', () => { From 4ed5f3b5e243ec71ea7333b763afb84215ea036b Mon Sep 17 00:00:00 2001 From: ashcharus-hue <270071046+ashcharus-hue@users.noreply.github.com> Date: Sat, 13 Jun 2026 20:44:27 +0530 Subject: [PATCH 21/51] fix(codex): rewrite CLAUDE.md -> AGENTS.md in generated Codex skills Codex uses AGENTS.md as its project instruction file, but the codex host config's pathRewrites omit the CLAUDE.md -> AGENTS.md rewrite that hosts/hermes.ts already has. Generated Codex-host skills therefore still reference CLAUDE.md: the routing preamble checks `[ -f CLAUDE.md ]`, and the routing-injection step can create and `git commit` a CLAUDE.md in a Codex repo (auto-applied in spawned/headless runs). Mirrors the hermes.ts pattern. Refs #1163. Complements #1162 (Codex model/tool rewrites, which did not include this filename rewrite). Co-Authored-By: Claude Opus 4.8 --- hosts/codex.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/hosts/codex.ts b/hosts/codex.ts index 98dda288ff..179bec6b4d 100644 --- a/hosts/codex.ts +++ b/hosts/codex.ts @@ -29,6 +29,7 @@ const codex: HostConfig = { { from: '.claude/skills/gstack', to: '.agents/skills/gstack' }, { from: '.claude/skills/review', to: '.agents/skills/gstack/review' }, { from: '.claude/skills', to: '.agents/skills' }, + { from: 'CLAUDE.md', to: 'AGENTS.md' }, ], suppressedResolvers: [ From 0e66478b65a33cff20f2fce81aee3a3cf19ee274 Mon Sep 17 00:00:00 2001 From: spacegeologist Date: Thu, 28 May 2026 14:56:52 +0800 Subject: [PATCH 22/51] fix(codex): load qa-only from gstack root in ship --- hosts/codex.ts | 1 + test/gen-skill-docs.test.ts | 10 ++++++++-- 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/hosts/codex.ts b/hosts/codex.ts index 179bec6b4d..999aed5a6e 100644 --- a/hosts/codex.ts +++ b/hosts/codex.ts @@ -29,6 +29,7 @@ const codex: HostConfig = { { from: '.claude/skills/gstack', to: '.agents/skills/gstack' }, { from: '.claude/skills/review', to: '.agents/skills/gstack/review' }, { from: '.claude/skills', to: '.agents/skills' }, + { from: '${CLAUDE_SKILL_DIR}/../qa-only/SKILL.md', to: '$GSTACK_ROOT/../gstack-qa-only/SKILL.md' }, { from: 'CLAUDE.md', to: 'AGENTS.md' }, ], diff --git a/test/gen-skill-docs.test.ts b/test/gen-skill-docs.test.ts index f2b2a82692..87b29e6d7c 100644 --- a/test/gen-skill-docs.test.ts +++ b/test/gen-skill-docs.test.ts @@ -1799,6 +1799,12 @@ describe('Codex generation (--host codex)', () => { expect(reviewContent).not.toContain('CODEX_REVIEWS'); }); + test('Codex ship plan verification loads qa-only from gstack root', () => { + const shipContent = fs.readFileSync(path.join(AGENTS_DIR, 'gstack-ship', 'SKILL.md'), 'utf-8'); + expect(shipContent).toContain('$GSTACK_ROOT/../gstack-qa-only/SKILL.md'); + expect(shipContent).not.toContain('${CLAUDE_SKILL_DIR}/../qa-only/SKILL.md'); + }); + test('--host codex --dry-run freshness', () => { const result = Bun.spawnSync(['bun', 'run', 'scripts/gen-skill-docs.ts', '--host', 'codex', '--dry-run'], { cwd: ROOT, @@ -1904,8 +1910,8 @@ describe('Codex generation (--host codex)', () => { } }); - test('all four path rewrite rules produce correct output', () => { - // Test each of the 4 path rewrite rules individually + test('Codex path rewrite rules produce correct output', () => { + // Test host-configured path rewrite rules individually const content = fs.readFileSync(path.join(AGENTS_DIR, 'gstack-review', 'SKILL.md'), 'utf-8'); // Rule 1: ~/.claude/skills/gstack → $GSTACK_ROOT From a72088f2fb146e78ace209edee03849a1795bab2 Mon Sep 17 00:00:00 2001 From: jacob-wang Date: Tue, 21 Apr 2026 01:08:08 +0800 Subject: [PATCH 23/51] =?UTF-8?q?fix(codex):=20add=20AskUserQuestion?= =?UTF-8?q?=E2=86=92request=5Fuser=5Finput=20tool=20rewrite?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Issue #1066 — Codex skills that call AskUserQuestion silently fail in Default mode because Codex strips AskUserQuestion from the tool schema and its equivalent (request_user_input) only works in Plan mode. The HostConfig interface already supports toolRewrites (gbrain, openclaw, factory, hermes all use it). codex.ts was missing it. Adding { 'AskUserQuestion': 'request_user_input' } to codex.ts so that when gen-skill-docs.ts applies rewrites at generation time, any prompt text referencing AskUserQuestion gets replaced with Codex's equivalent. Note: this only handles the text rewrite. A full fix would also need the Plan-mode gate in the preamble (Option 4 in #1066), but that requires codex-side feature flag changes outside gstack's control. Co-Authored-By: Claude Opus 4.7 --- hosts/codex.ts | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/hosts/codex.ts b/hosts/codex.ts index 999aed5a6e..8057e4e6e9 100644 --- a/hosts/codex.ts +++ b/hosts/codex.ts @@ -33,6 +33,10 @@ const codex: HostConfig = { { from: 'CLAUDE.md', to: 'AGENTS.md' }, ], + toolRewrites: { + 'AskUserQuestion': 'request_user_input', + }, + suppressedResolvers: [ 'DESIGN_OUTSIDE_VOICES', // design.ts:485 — Codex can't invoke itself 'ADVERSARIAL_STEP', // review.ts:408 — Codex can't invoke itself From 151de5825df1feb61aa4b3c847dffc434696fdc5 Mon Sep 17 00:00:00 2001 From: t Date: Mon, 13 Jul 2026 13:14:23 -0700 Subject: [PATCH 24/51] chore(codex): legacy-path migration, stale doc mention, toolRewrites regression test Follow-ups to the Codex path move (community PR #2123) and the AskUserQuestion tool rewrite (community PR #1101): - gstack-upgrade/migrations/v1.61.0.0.sh removes stale gstack-owned entries from the legacy ~/.codex/skills location (idempotent, non-fatal, touches only gstack/gstack-* entries) - pair-agent tmpl still pointed --local codex credentials at the legacy path - static test pins that generated Codex ship uses request_user_input and never leaks AskUserQuestion Co-Authored-By: Claude Fable 5 --- gstack-upgrade/migrations/v1.61.0.0.sh | 28 ++++++++++++++++++++++++++ pair-agent/SKILL.md.tmpl | 2 +- test/gen-skill-docs.test.ts | 6 ++++++ 3 files changed, 35 insertions(+), 1 deletion(-) create mode 100755 gstack-upgrade/migrations/v1.61.0.0.sh diff --git a/gstack-upgrade/migrations/v1.61.0.0.sh b/gstack-upgrade/migrations/v1.61.0.0.sh new file mode 100755 index 0000000000..8cb42d12ee --- /dev/null +++ b/gstack-upgrade/migrations/v1.61.0.0.sh @@ -0,0 +1,28 @@ +#!/usr/bin/env bash +# Migration: v1.61.0.0 — Codex global install moved from ~/.codex/skills to ~/.agents/skills +# Affected: users who installed for Codex before v1.61.0.0. +# +# Codex's documented user-scope skill discovery path is $HOME/.agents/skills; +# setup now installs there (community PR #2123). The old ~/.codex/skills +# location leaves stale gstack symlinks/dirs behind that would be discovered +# twice if Codex ever scans the legacy dir. Remove only gstack-owned entries +# (gstack and gstack-*); never touch anything else the user put there. +set -euo pipefail + +LEGACY="$HOME/.codex/skills" +[ -d "$LEGACY" ] || exit 0 + +for entry in "$LEGACY"/gstack "$LEGACY"/gstack-*; do + [ -e "$entry" ] || [ -L "$entry" ] || continue + if [ -L "$entry" ]; then + rm -f "$entry" 2>/dev/null || true + elif [ -d "$entry" ]; then + # Runtime roots are real dirs full of symlinks created by setup; safe to remove. + rm -rf "$entry" 2>/dev/null || true + fi +done + +# Drop the parent dirs if gstack was the only thing in them. +rmdir "$LEGACY" 2>/dev/null || true +rmdir "$HOME/.codex" 2>/dev/null || true +exit 0 diff --git a/pair-agent/SKILL.md.tmpl b/pair-agent/SKILL.md.tmpl index 75ed42d590..86b0e4c663 100644 --- a/pair-agent/SKILL.md.tmpl +++ b/pair-agent/SKILL.md.tmpl @@ -243,7 +243,7 @@ credentials are written to `~/.openclaw/skills/gstack/browse-remote.json`. Codex agents can execute shell commands via `codex exec`. The instruction block's curl commands work directly. When using `--local codex`, credentials are written -to `~/.codex/skills/gstack/browse-remote.json`. +to `~/.agents/skills/gstack/browse-remote.json`. ### Cursor diff --git a/test/gen-skill-docs.test.ts b/test/gen-skill-docs.test.ts index 87b29e6d7c..9194aa6c8e 100644 --- a/test/gen-skill-docs.test.ts +++ b/test/gen-skill-docs.test.ts @@ -1714,6 +1714,12 @@ describe('Codex generation (--host codex)', () => { expect(content).toContain('allow_implicit_invocation: true'); }); + test('toolRewrites: Codex ship names request_user_input, never AskUserQuestion', () => { + const content = fs.readFileSync(path.join(AGENTS_DIR, 'gstack-ship', 'SKILL.md'), 'utf-8'); + expect(content).toContain('request_user_input'); + expect(content).not.toContain('AskUserQuestion'); + }); + test('externalSkillName mapping: root is gstack, others are gstack-{dir}', () => { // Root → gstack expect(fs.existsSync(path.join(AGENTS_DIR, 'gstack', 'SKILL.md'))).toBe(true); From a952b60c537f53039db9241bd949bc18ba17028d Mon Sep 17 00:00:00 2001 From: Jayesh Betala Date: Mon, 13 Jul 2026 13:14:43 -0700 Subject: [PATCH 25/51] fix(host): bump Claude co-author trailer to Opus 4.8 Cherry-picked from community PR #1888 (source hunks only; generated docs and the ship golden are regenerated at the end of the wave). Co-Authored-By: Claude Fable 5 --- hosts/claude.ts | 2 +- scripts/resolvers/utility.ts | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/hosts/claude.ts b/hosts/claude.ts index f805da040e..097fc13600 100644 --- a/hosts/claude.ts +++ b/hosts/claude.ts @@ -38,7 +38,7 @@ const claude: HostConfig = { linkingStrategy: 'real-dir-symlink', }, - coAuthorTrailer: 'Co-Authored-By: Claude Opus 4.7 ', + coAuthorTrailer: 'Co-Authored-By: Claude Opus 4.8 ', learningsMode: 'full', }; diff --git a/scripts/resolvers/utility.ts b/scripts/resolvers/utility.ts index 3d2e368a29..a6bfbbef7e 100644 --- a/scripts/resolvers/utility.ts +++ b/scripts/resolvers/utility.ts @@ -369,7 +369,7 @@ Minimum 0 per category. export function generateCoAuthorTrailer(ctx: TemplateContext): string { const { getHostConfig } = require('../../hosts/index'); const hostConfig = getHostConfig(ctx.host); - return hostConfig.coAuthorTrailer || 'Co-Authored-By: Claude Opus 4.7 '; + return hostConfig.coAuthorTrailer || 'Co-Authored-By: Claude Opus 4.8 '; } export function generateChangelogWorkflow(_ctx: TemplateContext): string { From f1ef71a9e508b73ad4c5d7bed3293ab6bd0d4d3c Mon Sep 17 00:00:00 2001 From: Matt Van Horn <455140+mvanhorn@users.noreply.github.com> Date: Fri, 15 May 2026 10:02:22 -0700 Subject: [PATCH 26/51] fix(setup): wire --host cursor through bash dispatch and install path Closes #1358. Adds the missing bash side of Cursor host support that hosts/cursor.ts and the README already advertised. Mirrors the opencode wiring pattern end-to-end so 'setup --host cursor' actually installs skills to ~/.cursor/skills/gstack-*/ as the README documents. Touches 4 sites in setup: - Lines 87, 100, 135: cursor added to --host expected/accept/error list - Lines 198-218: INSTALL_CURSOR variable + auto-detect ('command -v cursor') + dispatch branch - Phase 1e: gen .cursor/ skill docs via 'bun run gen:skill-docs --host cursor' - New create_cursor_runtime_root + link_cursor_skill_dirs helpers (opencode-shaped) - Phase 6d: install for Cursor (mkdir + create runtime root + link skill dirs) Plus CURSOR_SKILLS / CURSOR_GSTACK path vars at the top of setup. test/gen-skill-docs.test.ts: 389 pass / 0 fail. Two new cases pin the cursor path vars and the install section structure; existing --host arg-list assertions updated to include cursor. Reported by @hhlqsmy. --- setup | 104 ++++++++++++++++++++++++++++++++++-- test/gen-skill-docs.test.ts | 20 +++++-- 2 files changed, 117 insertions(+), 7 deletions(-) diff --git a/setup b/setup index 4715cafecc..521db49dc4 100755 --- a/setup +++ b/setup @@ -24,6 +24,8 @@ FACTORY_SKILLS="$HOME/.factory/skills" FACTORY_GSTACK="$FACTORY_SKILLS/gstack" OPENCODE_SKILLS="$HOME/.config/opencode/skills" OPENCODE_GSTACK="$OPENCODE_SKILLS/gstack" +CURSOR_SKILLS="$HOME/.cursor/skills" +CURSOR_GSTACK="$CURSOR_SKILLS/gstack" IS_WINDOWS=0 case "$(uname -s)" in @@ -85,7 +87,7 @@ NO_TEAM_MODE=0 PLAN_TUNE_HOOKS_MODE="" # "" = resolve from env/config/prompt; "yes"/"no" = explicit while [ $# -gt 0 ]; do case "$1" in - --host) [ -z "$2" ] && echo "Missing value for --host (expected claude, codex, kiro, factory, opencode, openclaw, hermes, gbrain, or auto)" >&2 && exit 1; HOST="$2"; shift 2 ;; + --host) [ -z "$2" ] && echo "Missing value for --host (expected claude, codex, kiro, factory, opencode, cursor, openclaw, hermes, gbrain, or auto)" >&2 && exit 1; HOST="$2"; shift 2 ;; --host=*) HOST="${1#--host=}"; shift ;; --local) LOCAL_INSTALL=1; shift ;; --prefix) SKILL_PREFIX=1; SKILL_PREFIX_FLAG=1; shift ;; @@ -101,7 +103,7 @@ while [ $# -gt 0 ]; do done case "$HOST" in - claude|codex|kiro|factory|opencode|auto) ;; + claude|codex|kiro|factory|opencode|cursor|auto) ;; openclaw) echo "" echo "OpenClaw integration uses a different model — OpenClaw spawns Claude Code" @@ -141,7 +143,7 @@ case "$HOST" in echo "GBrain setup and brain skills ship from the GBrain repo." echo "" exit 0 ;; - *) echo "Unknown --host value: $HOST (expected claude, codex, kiro, factory, opencode, openclaw, hermes, gbrain, or auto)" >&2; exit 1 ;; + *) echo "Unknown --host value: $HOST (expected claude, codex, kiro, factory, opencode, cursor, openclaw, hermes, gbrain, or auto)" >&2; exit 1 ;; esac # ─── Resolve skill prefix preference ───────────────────────── @@ -205,14 +207,16 @@ INSTALL_CODEX=0 INSTALL_KIRO=0 INSTALL_FACTORY=0 INSTALL_OPENCODE=0 +INSTALL_CURSOR=0 if [ "$HOST" = "auto" ]; then command -v claude >/dev/null 2>&1 && INSTALL_CLAUDE=1 command -v codex >/dev/null 2>&1 && INSTALL_CODEX=1 command -v kiro-cli >/dev/null 2>&1 && INSTALL_KIRO=1 command -v droid >/dev/null 2>&1 && INSTALL_FACTORY=1 command -v opencode >/dev/null 2>&1 && INSTALL_OPENCODE=1 + command -v cursor >/dev/null 2>&1 && INSTALL_CURSOR=1 # If none found, default to claude - if [ "$INSTALL_CLAUDE" -eq 0 ] && [ "$INSTALL_CODEX" -eq 0 ] && [ "$INSTALL_KIRO" -eq 0 ] && [ "$INSTALL_FACTORY" -eq 0 ] && [ "$INSTALL_OPENCODE" -eq 0 ]; then + if [ "$INSTALL_CLAUDE" -eq 0 ] && [ "$INSTALL_CODEX" -eq 0 ] && [ "$INSTALL_KIRO" -eq 0 ] && [ "$INSTALL_FACTORY" -eq 0 ] && [ "$INSTALL_OPENCODE" -eq 0 ] && [ "$INSTALL_CURSOR" -eq 0 ]; then INSTALL_CLAUDE=1 fi elif [ "$HOST" = "claude" ]; then @@ -225,6 +229,8 @@ elif [ "$HOST" = "factory" ]; then INSTALL_FACTORY=1 elif [ "$HOST" = "opencode" ]; then INSTALL_OPENCODE=1 +elif [ "$HOST" = "cursor" ]; then + INSTALL_CURSOR=1 fi migrate_direct_codex_install() { @@ -480,6 +486,16 @@ if [ "$INSTALL_OPENCODE" -eq 1 ] && [ "$NEEDS_BUILD" -eq 0 ]; then ) fi +# 1e. Generate .cursor/ Cursor skill docs +if [ "$INSTALL_CURSOR" -eq 1 ] && [ "$NEEDS_BUILD" -eq 0 ]; then + log "Generating .cursor/ skill docs..." + ( + cd "$SOURCE_GSTACK_DIR" + bun install --frozen-lockfile 2>/dev/null || bun install + bun run gen:skill-docs --host cursor + ) +fi + # 2. Ensure Playwright's Chromium is available if ! ensure_playwright_browser; then echo "Installing Playwright Chromium..." @@ -943,6 +959,44 @@ create_opencode_runtime_root() { fi } +create_cursor_runtime_root() { + local gstack_dir="$1" + local cursor_gstack="$2" + local cursor_dir="$gstack_dir/.cursor/skills" + + if [ -L "$cursor_gstack" ]; then + rm -f "$cursor_gstack" + elif [ -d "$cursor_gstack" ] && [ "$cursor_gstack" != "$gstack_dir" ]; then + rm -rf "$cursor_gstack" + fi + + mkdir -p "$cursor_gstack" "$cursor_gstack/browse" "$cursor_gstack/gstack-upgrade" "$cursor_gstack/review" + + if [ -f "$cursor_dir/gstack/SKILL.md" ]; then + _link_or_copy "$cursor_dir/gstack/SKILL.md" "$cursor_gstack/SKILL.md" + fi + if [ -d "$gstack_dir/bin" ]; then + _link_or_copy "$gstack_dir/bin" "$cursor_gstack/bin" + fi + if [ -d "$gstack_dir/browse/dist" ]; then + _link_or_copy "$gstack_dir/browse/dist" "$cursor_gstack/browse/dist" + fi + if [ -d "$gstack_dir/browse/bin" ]; then + _link_or_copy "$gstack_dir/browse/bin" "$cursor_gstack/browse/bin" + fi + if [ -f "$cursor_dir/gstack-upgrade/SKILL.md" ]; then + _link_or_copy "$cursor_dir/gstack-upgrade/SKILL.md" "$cursor_gstack/gstack-upgrade/SKILL.md" + fi + for f in checklist.md TODOS-format.md; do + if [ -f "$gstack_dir/review/$f" ]; then + _link_or_copy "$gstack_dir/review/$f" "$cursor_gstack/review/$f" + fi + done + if [ -f "$gstack_dir/ETHOS.md" ]; then + _link_or_copy "$gstack_dir/ETHOS.md" "$cursor_gstack/ETHOS.md" + fi +} + link_factory_skill_dirs() { local gstack_dir="$1" local skills_dir="$2" @@ -1007,6 +1061,38 @@ link_opencode_skill_dirs() { fi } +link_cursor_skill_dirs() { + local gstack_dir="$1" + local skills_dir="$2" + local cursor_dir="$gstack_dir/.cursor/skills" + local linked=() + + if [ ! -d "$cursor_dir" ]; then + echo " Generating .cursor/ skill docs..." + ( cd "$gstack_dir" && bun run gen:skill-docs --host cursor ) + fi + + if [ ! -d "$cursor_dir" ]; then + echo " warning: .cursor/skills/ generation failed — run 'bun run gen:skill-docs --host cursor' manually" >&2 + return 1 + fi + + for skill_dir in "$cursor_dir"/gstack*/; do + if [ -f "$skill_dir/SKILL.md" ]; then + skill_name="$(basename "$skill_dir")" + [ "$skill_name" = "gstack" ] && continue + target="$skills_dir/$skill_name" + if [ -L "$target" ] || [ ! -e "$target" ]; then + _link_or_copy "$skill_dir" "$target" + linked+=("$skill_name") + fi + fi + done + if [ ${#linked[@]} -gt 0 ]; then + echo " linked skills: ${linked[*]}" + fi +} + # 4. Install for Claude (default) SKILLS_BASENAME="$(basename "$INSTALL_SKILLS_DIR")" SKILLS_PARENT_BASENAME="$(basename "$(dirname "$INSTALL_SKILLS_DIR")")" @@ -1239,6 +1325,16 @@ if [ "$INSTALL_OPENCODE" -eq 1 ]; then echo " opencode skills: $OPENCODE_SKILLS" fi +# 6d. Install for Cursor +if [ "$INSTALL_CURSOR" -eq 1 ]; then + mkdir -p "$CURSOR_SKILLS" + create_cursor_runtime_root "$SOURCE_GSTACK_DIR" "$CURSOR_GSTACK" + link_cursor_skill_dirs "$SOURCE_GSTACK_DIR" "$CURSOR_SKILLS" + echo "gstack ready (cursor)." + echo " browse: $BROWSE_BIN" + echo " cursor skills: $CURSOR_SKILLS" +fi + # 7. Create .agents/ sidecar symlinks for the real Codex skill target. # The root Codex skill ends up pointing at $SOURCE_GSTACK_DIR/.agents/skills/gstack, # so the runtime assets must live there for both global and repo-local installs. diff --git a/test/gen-skill-docs.test.ts b/test/gen-skill-docs.test.ts index 9194aa6c8e..5eb728c6b4 100644 --- a/test/gen-skill-docs.test.ts +++ b/test/gen-skill-docs.test.ts @@ -2404,9 +2404,9 @@ describe('setup script validation', () => { expect(claudeSection).toContain('link_claude_root_skill_alias "$SOURCE_GSTACK_DIR" "$INSTALL_SKILLS_DIR"'); }); - test('setup supports --host auto|claude|codex|kiro|opencode', () => { + test('setup supports --host auto|claude|codex|kiro|opencode|cursor', () => { expect(setupContent).toContain('--host'); - expect(setupContent).toContain('claude|codex|kiro|factory|opencode|auto'); + expect(setupContent).toContain('claude|codex|kiro|factory|opencode|cursor|auto'); }); test('Hermes host banner is explicit that setup is not an installer', () => { @@ -2422,11 +2422,12 @@ describe('setup script validation', () => { expect(hermesBlock).toContain('This writes .hermes/skills/ in this checkout.'); }); - test('auto mode detects claude, codex, kiro, and opencode binaries', () => { + test('auto mode detects claude, codex, kiro, opencode, and cursor binaries', () => { expect(setupContent).toContain('command -v claude'); expect(setupContent).toContain('command -v codex'); expect(setupContent).toContain('command -v kiro-cli'); expect(setupContent).toContain('command -v opencode'); + expect(setupContent).toContain('command -v cursor'); }); // T1: Sidecar skip guard — prevents .agents/skills/gstack from being linked as a skill @@ -2468,6 +2469,19 @@ describe('setup script validation', () => { expect(setupContent).toContain('dx-hall-of-fame.md'); }); + test('setup supports --host cursor with install section and Cursor skill path vars', () => { + expect(setupContent).toContain('INSTALL_CURSOR='); + expect(setupContent).toContain('CURSOR_SKILLS="$HOME/.cursor/skills"'); + expect(setupContent).toContain('CURSOR_GSTACK="$CURSOR_SKILLS/gstack"'); + }); + + test('setup installs Cursor skills into a nested gstack runtime root', () => { + expect(setupContent).toContain('create_cursor_runtime_root'); + expect(setupContent).toContain('.cursor/skills'); + expect(setupContent).toContain('link_cursor_skill_dirs'); + expect(setupContent).toContain('bun run gen:skill-docs --host cursor'); + }); + test('create_agents_sidecar links runtime assets', () => { // Sidecar must link bin, browse, design, review, qa const fnStart = setupContent.indexOf('create_agents_sidecar()'); From 2b4aeed2d81375724f1d8c5301417afc87fc0b6e Mon Sep 17 00:00:00 2001 From: t Date: Mon, 13 Jul 2026 13:19:15 -0700 Subject: [PATCH 27/51] fix(setup): wire --host slate through bash dispatch and install path MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Slate had the same documented-but-rejected gap as Cursor (README lists it, hosts/slate.ts is registered, setup errored on --host slate). Mechanical clone of the Cursor wiring from community PR #1526 — hosts/slate.ts runtimeRoot is identical to hosts/cursor.ts, only the paths differ. All link sites route through _link_or_copy. Static tests mirror the cursor assertions. Co-Authored-By: Claude Fable 5 --- setup | 106 ++++++++++++++++++++++++++++++++++-- test/gen-skill-docs.test.ts | 20 ++++++- 2 files changed, 119 insertions(+), 7 deletions(-) diff --git a/setup b/setup index 521db49dc4..f8670fa400 100755 --- a/setup +++ b/setup @@ -26,6 +26,8 @@ OPENCODE_SKILLS="$HOME/.config/opencode/skills" OPENCODE_GSTACK="$OPENCODE_SKILLS/gstack" CURSOR_SKILLS="$HOME/.cursor/skills" CURSOR_GSTACK="$CURSOR_SKILLS/gstack" +SLATE_SKILLS="$HOME/.slate/skills" +SLATE_GSTACK="$SLATE_SKILLS/gstack" IS_WINDOWS=0 case "$(uname -s)" in @@ -87,7 +89,7 @@ NO_TEAM_MODE=0 PLAN_TUNE_HOOKS_MODE="" # "" = resolve from env/config/prompt; "yes"/"no" = explicit while [ $# -gt 0 ]; do case "$1" in - --host) [ -z "$2" ] && echo "Missing value for --host (expected claude, codex, kiro, factory, opencode, cursor, openclaw, hermes, gbrain, or auto)" >&2 && exit 1; HOST="$2"; shift 2 ;; + --host) [ -z "$2" ] && echo "Missing value for --host (expected claude, codex, kiro, factory, opencode, cursor, slate, openclaw, hermes, gbrain, or auto)" >&2 && exit 1; HOST="$2"; shift 2 ;; --host=*) HOST="${1#--host=}"; shift ;; --local) LOCAL_INSTALL=1; shift ;; --prefix) SKILL_PREFIX=1; SKILL_PREFIX_FLAG=1; shift ;; @@ -103,7 +105,7 @@ while [ $# -gt 0 ]; do done case "$HOST" in - claude|codex|kiro|factory|opencode|cursor|auto) ;; + claude|codex|kiro|factory|opencode|cursor|slate|auto) ;; openclaw) echo "" echo "OpenClaw integration uses a different model — OpenClaw spawns Claude Code" @@ -143,7 +145,7 @@ case "$HOST" in echo "GBrain setup and brain skills ship from the GBrain repo." echo "" exit 0 ;; - *) echo "Unknown --host value: $HOST (expected claude, codex, kiro, factory, opencode, cursor, openclaw, hermes, gbrain, or auto)" >&2; exit 1 ;; + *) echo "Unknown --host value: $HOST (expected claude, codex, kiro, factory, opencode, cursor, slate, openclaw, hermes, gbrain, or auto)" >&2; exit 1 ;; esac # ─── Resolve skill prefix preference ───────────────────────── @@ -208,6 +210,7 @@ INSTALL_KIRO=0 INSTALL_FACTORY=0 INSTALL_OPENCODE=0 INSTALL_CURSOR=0 +INSTALL_SLATE=0 if [ "$HOST" = "auto" ]; then command -v claude >/dev/null 2>&1 && INSTALL_CLAUDE=1 command -v codex >/dev/null 2>&1 && INSTALL_CODEX=1 @@ -215,8 +218,9 @@ if [ "$HOST" = "auto" ]; then command -v droid >/dev/null 2>&1 && INSTALL_FACTORY=1 command -v opencode >/dev/null 2>&1 && INSTALL_OPENCODE=1 command -v cursor >/dev/null 2>&1 && INSTALL_CURSOR=1 + command -v slate >/dev/null 2>&1 && INSTALL_SLATE=1 # If none found, default to claude - if [ "$INSTALL_CLAUDE" -eq 0 ] && [ "$INSTALL_CODEX" -eq 0 ] && [ "$INSTALL_KIRO" -eq 0 ] && [ "$INSTALL_FACTORY" -eq 0 ] && [ "$INSTALL_OPENCODE" -eq 0 ] && [ "$INSTALL_CURSOR" -eq 0 ]; then + if [ "$INSTALL_CLAUDE" -eq 0 ] && [ "$INSTALL_CODEX" -eq 0 ] && [ "$INSTALL_KIRO" -eq 0 ] && [ "$INSTALL_FACTORY" -eq 0 ] && [ "$INSTALL_OPENCODE" -eq 0 ] && [ "$INSTALL_CURSOR" -eq 0 ] && [ "$INSTALL_SLATE" -eq 0 ]; then INSTALL_CLAUDE=1 fi elif [ "$HOST" = "claude" ]; then @@ -231,6 +235,8 @@ elif [ "$HOST" = "opencode" ]; then INSTALL_OPENCODE=1 elif [ "$HOST" = "cursor" ]; then INSTALL_CURSOR=1 +elif [ "$HOST" = "slate" ]; then + INSTALL_SLATE=1 fi migrate_direct_codex_install() { @@ -496,6 +502,16 @@ if [ "$INSTALL_CURSOR" -eq 1 ] && [ "$NEEDS_BUILD" -eq 0 ]; then ) fi +# 1f. Generate .slate/ Slate skill docs +if [ "$INSTALL_SLATE" -eq 1 ] && [ "$NEEDS_BUILD" -eq 0 ]; then + log "Generating .slate/ skill docs..." + ( + cd "$SOURCE_GSTACK_DIR" + bun install --frozen-lockfile 2>/dev/null || bun install + bun run gen:skill-docs --host slate + ) +fi + # 2. Ensure Playwright's Chromium is available if ! ensure_playwright_browser; then echo "Installing Playwright Chromium..." @@ -1093,6 +1109,78 @@ link_cursor_skill_dirs() { fi } +# Slate mirrors the Cursor install exactly (hosts/slate.ts runtimeRoot is +# identical to hosts/cursor.ts); only the paths differ. +create_slate_runtime_root() { + local gstack_dir="$1" + local slate_gstack="$2" + local slate_dir="$gstack_dir/.slate/skills" + + if [ -L "$slate_gstack" ]; then + rm -f "$slate_gstack" + elif [ -d "$slate_gstack" ] && [ "$slate_gstack" != "$gstack_dir" ]; then + rm -rf "$slate_gstack" + fi + + mkdir -p "$slate_gstack" "$slate_gstack/browse" "$slate_gstack/gstack-upgrade" "$slate_gstack/review" + + if [ -f "$slate_dir/gstack/SKILL.md" ]; then + _link_or_copy "$slate_dir/gstack/SKILL.md" "$slate_gstack/SKILL.md" + fi + if [ -d "$gstack_dir/bin" ]; then + _link_or_copy "$gstack_dir/bin" "$slate_gstack/bin" + fi + if [ -d "$gstack_dir/browse/dist" ]; then + _link_or_copy "$gstack_dir/browse/dist" "$slate_gstack/browse/dist" + fi + if [ -d "$gstack_dir/browse/bin" ]; then + _link_or_copy "$gstack_dir/browse/bin" "$slate_gstack/browse/bin" + fi + if [ -f "$slate_dir/gstack-upgrade/SKILL.md" ]; then + _link_or_copy "$slate_dir/gstack-upgrade/SKILL.md" "$slate_gstack/gstack-upgrade/SKILL.md" + fi + for f in checklist.md TODOS-format.md; do + if [ -f "$gstack_dir/review/$f" ]; then + _link_or_copy "$gstack_dir/review/$f" "$slate_gstack/review/$f" + fi + done + if [ -f "$gstack_dir/ETHOS.md" ]; then + _link_or_copy "$gstack_dir/ETHOS.md" "$slate_gstack/ETHOS.md" + fi +} + +link_slate_skill_dirs() { + local gstack_dir="$1" + local skills_dir="$2" + local slate_dir="$gstack_dir/.slate/skills" + local linked=() + + if [ ! -d "$slate_dir" ]; then + echo " Generating .slate/ skill docs..." + ( cd "$gstack_dir" && bun run gen:skill-docs --host slate ) + fi + + if [ ! -d "$slate_dir" ]; then + echo " warning: .slate/skills/ generation failed — run 'bun run gen:skill-docs --host slate' manually" >&2 + return 1 + fi + + for skill_dir in "$slate_dir"/gstack*/; do + if [ -f "$skill_dir/SKILL.md" ]; then + skill_name="$(basename "$skill_dir")" + [ "$skill_name" = "gstack" ] && continue + target="$skills_dir/$skill_name" + if [ -L "$target" ] || [ ! -e "$target" ]; then + _link_or_copy "$skill_dir" "$target" + linked+=("$skill_name") + fi + fi + done + if [ ${#linked[@]} -gt 0 ]; then + echo " linked skills: ${linked[*]}" + fi +} + # 4. Install for Claude (default) SKILLS_BASENAME="$(basename "$INSTALL_SKILLS_DIR")" SKILLS_PARENT_BASENAME="$(basename "$(dirname "$INSTALL_SKILLS_DIR")")" @@ -1335,6 +1423,16 @@ if [ "$INSTALL_CURSOR" -eq 1 ]; then echo " cursor skills: $CURSOR_SKILLS" fi +# 6e. Install for Slate +if [ "$INSTALL_SLATE" -eq 1 ]; then + mkdir -p "$SLATE_SKILLS" + create_slate_runtime_root "$SOURCE_GSTACK_DIR" "$SLATE_GSTACK" + link_slate_skill_dirs "$SOURCE_GSTACK_DIR" "$SLATE_SKILLS" + echo "gstack ready (slate)." + echo " browse: $BROWSE_BIN" + echo " slate skills: $SLATE_SKILLS" +fi + # 7. Create .agents/ sidecar symlinks for the real Codex skill target. # The root Codex skill ends up pointing at $SOURCE_GSTACK_DIR/.agents/skills/gstack, # so the runtime assets must live there for both global and repo-local installs. diff --git a/test/gen-skill-docs.test.ts b/test/gen-skill-docs.test.ts index 5eb728c6b4..d06fc57d22 100644 --- a/test/gen-skill-docs.test.ts +++ b/test/gen-skill-docs.test.ts @@ -2404,9 +2404,9 @@ describe('setup script validation', () => { expect(claudeSection).toContain('link_claude_root_skill_alias "$SOURCE_GSTACK_DIR" "$INSTALL_SKILLS_DIR"'); }); - test('setup supports --host auto|claude|codex|kiro|opencode|cursor', () => { + test('setup supports --host auto|claude|codex|kiro|opencode|cursor|slate', () => { expect(setupContent).toContain('--host'); - expect(setupContent).toContain('claude|codex|kiro|factory|opencode|cursor|auto'); + expect(setupContent).toContain('claude|codex|kiro|factory|opencode|cursor|slate|auto'); }); test('Hermes host banner is explicit that setup is not an installer', () => { @@ -2422,12 +2422,13 @@ describe('setup script validation', () => { expect(hermesBlock).toContain('This writes .hermes/skills/ in this checkout.'); }); - test('auto mode detects claude, codex, kiro, opencode, and cursor binaries', () => { + test('auto mode detects claude, codex, kiro, opencode, cursor, and slate binaries', () => { expect(setupContent).toContain('command -v claude'); expect(setupContent).toContain('command -v codex'); expect(setupContent).toContain('command -v kiro-cli'); expect(setupContent).toContain('command -v opencode'); expect(setupContent).toContain('command -v cursor'); + expect(setupContent).toContain('command -v slate'); }); // T1: Sidecar skip guard — prevents .agents/skills/gstack from being linked as a skill @@ -2482,6 +2483,19 @@ describe('setup script validation', () => { expect(setupContent).toContain('bun run gen:skill-docs --host cursor'); }); + test('setup supports --host slate with install section and Slate skill path vars', () => { + expect(setupContent).toContain('INSTALL_SLATE='); + expect(setupContent).toContain('SLATE_SKILLS="$HOME/.slate/skills"'); + expect(setupContent).toContain('SLATE_GSTACK="$SLATE_SKILLS/gstack"'); + }); + + test('setup installs Slate skills into a nested gstack runtime root', () => { + expect(setupContent).toContain('create_slate_runtime_root'); + expect(setupContent).toContain('.slate/skills'); + expect(setupContent).toContain('link_slate_skill_dirs'); + expect(setupContent).toContain('bun run gen:skill-docs --host slate'); + }); + test('create_agents_sidecar links runtime assets', () => { // Sidecar must link bin, browse, design, review, qa const fnStart = setupContent.indexOf('create_agents_sidecar()'); From 31157f9801a4e57e3cc344abd7a5ea2456f61f3b Mon Sep 17 00:00:00 2001 From: abdul Date: Tue, 9 Jun 2026 00:08:58 +0700 Subject: [PATCH 28/51] feat(hosts): add pi as a supported host Pi implements the Agent Skills spec, so gstack skills work with one config file (no generator, setup, or tooling changes). Skills install to ~/.pi/agent/skills/gstack-*/ for global and .pi/skills/ for project-local, both discovered by pi at startup. - hosts/pi.ts: minimal config mirroring opencode pattern - hosts/index.ts: register pi in ALL_HOST_CONFIGS + re-exports - .gitignore: skip .pi/ (generated skill docs) - README.md: add Pi row to host table + dedicated install section --- .gitignore | 1 + README.md | 18 +++++++++++++++ hosts/index.ts | 5 +++-- hosts/pi.ts | 60 ++++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 82 insertions(+), 2 deletions(-) create mode 100644 hosts/pi.ts diff --git a/.gitignore b/.gitignore index 5196c0d05a..5e6deb16d8 100644 --- a/.gitignore +++ b/.gitignore @@ -20,6 +20,7 @@ bin/gstack-global-discover* .slate/ .cursor/ .openclaw/ +.pi/ .hermes/ .gbrain/ .gbrain-source diff --git a/README.md b/README.md index 1fcda0b1c6..c1967018da 100644 --- a/README.md +++ b/README.md @@ -120,11 +120,29 @@ Or target a specific agent with `./setup --host `: | Slate | `--host slate` | `~/.slate/skills/gstack-*/` | | Kiro | `--host kiro` | `~/.kiro/skills/gstack-*/` | | Hermes | `--host hermes` | Prints integration instructions; `bun run gen:skill-docs --host hermes` writes `.hermes/skills/` | +| Pi | `--host pi` | Prints integration instructions; `bun run gen:skill-docs --host pi` writes `.pi/skills/` | | GBrain (mod) | `--host gbrain` | `~/.gbrain/skills/gstack-*/` | **Want to add support for another agent?** See [docs/ADDING_A_HOST.md](docs/ADDING_A_HOST.md). It's one TypeScript config file, zero code changes. +### Pi + +[Pi](https://pi.dev) implements the [Agent Skills standard](https://agentskills.io/specification) +end-to-end, so every gstack skill works out of the box once the skills directory +is configured. Install gstack into pi's global agent skills path: + +```bash +git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/gstack +cd ~/gstack && ./setup --host pi +``` + +Skills land at `~/.pi/agent/skills/gstack-*/`. For project-local skills (trusted +project), pi also discovers `.pi/skills/`. Pi loads skill descriptions at startup +and lazy-loads the full `SKILL.md` on demand, matching Claude Code's behavior. + +Invoke a skill with `/skill:` (e.g. `/skill:review`, `/skill:ship`). + ## See it work ``` diff --git a/hosts/index.ts b/hosts/index.ts index cc1c213b53..18728b6eb0 100644 --- a/hosts/index.ts +++ b/hosts/index.ts @@ -16,9 +16,10 @@ import cursor from './cursor'; import openclaw from './openclaw'; import hermes from './hermes'; import gbrain from './gbrain'; +import pi from './pi'; /** All registered host configs. Add new hosts here. */ -export const ALL_HOST_CONFIGS: HostConfig[] = [claude, codex, factory, kiro, opencode, slate, cursor, openclaw, hermes, gbrain]; +export const ALL_HOST_CONFIGS: HostConfig[] = [claude, codex, factory, kiro, opencode, slate, cursor, openclaw, hermes, gbrain, pi]; /** Map from host name to config. */ export const HOST_CONFIG_MAP: Record = Object.fromEntries( @@ -65,4 +66,4 @@ export function getExternalHosts(): HostConfig[] { } // Re-export individual configs for direct import -export { claude, codex, factory, kiro, opencode, slate, cursor, openclaw, hermes, gbrain }; +export { claude, codex, factory, kiro, opencode, slate, cursor, openclaw, hermes, gbrain, pi }; diff --git a/hosts/pi.ts b/hosts/pi.ts new file mode 100644 index 0000000000..fb717c2e78 --- /dev/null +++ b/hosts/pi.ts @@ -0,0 +1,60 @@ +import type { HostConfig } from '../scripts/host-config'; + +const pi: HostConfig = { + name: 'pi', + displayName: 'Pi', + cliCommand: 'pi', + cliAliases: [], + + globalRoot: '.pi/agent/skills/gstack', + localSkillRoot: '.pi/skills/gstack', + hostSubdir: '.pi', + usesEnvVars: true, + + frontmatter: { + mode: 'allowlist', + keepFields: ['name', 'description'], + descriptionLimit: 1024, + }, + + generation: { + generateMetadata: false, + skipSkills: ['codex'], + }, + + pathRewrites: [ + { from: '~/.claude/skills/gstack', to: '~/.pi/agent/skills/gstack' }, + { from: '.claude/skills/gstack', to: '.pi/skills/gstack' }, + { from: '.claude/skills', to: '.pi/skills' }, + ], + toolRewrites: { + 'use the Bash tool': 'use the bash tool', + 'use the Write tool': 'use the write tool', + 'use the Read tool': 'use the read tool', + 'use the Edit tool': 'use the edit tool', + 'use the Grep tool': 'use the grep tool', + 'use the Glob tool': 'use the find tool', + 'use the Agent tool': 'use the agent tool', + 'the Bash tool': 'the bash tool', + 'the Read tool': 'the read tool', + 'the Write tool': 'the write tool', + 'the Edit tool': 'the edit tool', + }, + suppressedResolvers: ['GBRAIN_CONTEXT_LOAD', 'GBRAIN_SAVE_RESULTS'], + + runtimeRoot: { + globalSymlinks: ['bin', 'browse/dist', 'browse/bin', 'design/dist', 'gstack-upgrade', 'ETHOS.md', 'review/specialists', 'qa/templates', 'qa/references', 'plan-devex-review/dx-hall-of-fame.md'], + globalFiles: { + 'review': ['checklist.md', 'design-checklist.md', 'greptile-triage.md', 'TODOS-format.md'], + }, + }, + + install: { + prefixable: false, + linkingStrategy: 'symlink-generated', + }, + + learningsMode: 'basic', +}; + +export default pi; From 2c8571834451d65fec56dc5cce8f8f1a32f980ee Mon Sep 17 00:00:00 2001 From: t Date: Mon, 13 Jul 2026 13:22:23 -0700 Subject: [PATCH 29/51] chore(pi): host-count bump, warn-mode description limit, honest install path Adaptations for the Pi host pick (community PR #1918): - test/host-config.test.ts host count 10 -> 11 - descriptionLimitBehavior 'warn' (ported from community PR #1497's config): pi has no committed output, so a future >1024-char skill description would hard-fail generation with no early signal - ./setup --host pi now prints hermes-style integration instructions instead of erroring 'Unknown --host value'; README's Pi section shows the real two-command install instead of a setup path that didn't exist Co-Authored-By: Claude Fable 5 --- README.md | 6 ++++-- hosts/pi.ts | 1 + setup | 14 ++++++++++++++ test/host-config.test.ts | 4 ++-- 4 files changed, 21 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index c1967018da..0cd69ca472 100644 --- a/README.md +++ b/README.md @@ -130,11 +130,13 @@ It's one TypeScript config file, zero code changes. [Pi](https://pi.dev) implements the [Agent Skills standard](https://agentskills.io/specification) end-to-end, so every gstack skill works out of the box once the skills directory -is configured. Install gstack into pi's global agent skills path: +is configured. `./setup --host pi` prints these instructions; the install itself +is two commands: ```bash git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/gstack -cd ~/gstack && ./setup --host pi +cd ~/gstack && bun run gen:skill-docs --host pi +mkdir -p ~/.pi/agent/skills && ln -snf "$(pwd)"/.pi/skills/gstack* ~/.pi/agent/skills/ ``` Skills land at `~/.pi/agent/skills/gstack-*/`. For project-local skills (trusted diff --git a/hosts/pi.ts b/hosts/pi.ts index fb717c2e78..edfc10fb30 100644 --- a/hosts/pi.ts +++ b/hosts/pi.ts @@ -15,6 +15,7 @@ const pi: HostConfig = { mode: 'allowlist', keepFields: ['name', 'description'], descriptionLimit: 1024, + descriptionLimitBehavior: 'warn', // no committed pi output to catch an error early }, generation: { diff --git a/setup b/setup index f8670fa400..b76aaf8e54 100755 --- a/setup +++ b/setup @@ -133,6 +133,20 @@ case "$HOST" in echo " This writes .hermes/skills/ in this checkout." echo "" exit 0 ;; + pi) + echo "" + echo "./setup --host pi does not install files into Pi today." + echo "It only prints integration instructions." + echo "" + echo "To integrate gstack with Pi:" + echo " 1. Generate Pi-format skills locally:" + echo " bun run gen:skill-docs --host pi" + echo " This writes .pi/skills/ in this checkout." + echo " 2. Link them into Pi's global skills path:" + echo " mkdir -p ~/.pi/agent/skills" + echo " ln -snf \"\$(pwd)\"/.pi/skills/gstack* ~/.pi/agent/skills/" + echo "" + exit 0 ;; gbrain) echo "" echo "GBrain is a mod for gstack — it makes coding skills brain-aware." diff --git a/test/host-config.test.ts b/test/host-config.test.ts index 5d042dab32..d2bd784b1c 100644 --- a/test/host-config.test.ts +++ b/test/host-config.test.ts @@ -30,8 +30,8 @@ const ROOT = path.resolve(import.meta.dir, '..'); // ─── hosts/index.ts ───────────────────────────────────────── describe('hosts/index.ts', () => { - test('ALL_HOST_CONFIGS has 10 hosts', () => { - expect(ALL_HOST_CONFIGS.length).toBe(10); + test('ALL_HOST_CONFIGS has 11 hosts', () => { + expect(ALL_HOST_CONFIGS.length).toBe(11); }); test('ALL_HOST_NAMES matches config names', () => { From 0b75b2b6bebda726bfa1abe2b0bdba38f718a443 Mon Sep 17 00:00:00 2001 From: Shagun Prasad Date: Thu, 25 Jun 2026 17:44:09 +0530 Subject: [PATCH 30/51] feat(hosts): add agy config for Antigravity --- hosts/agy.ts | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ hosts/index.ts | 5 +++-- 2 files changed, 51 insertions(+), 2 deletions(-) create mode 100644 hosts/agy.ts diff --git a/hosts/agy.ts b/hosts/agy.ts new file mode 100644 index 0000000000..d8c267576d --- /dev/null +++ b/hosts/agy.ts @@ -0,0 +1,48 @@ +import type { HostConfig } from '../scripts/host-config'; + +const agy: HostConfig = { + name: 'agy', + displayName: 'Antigravity', + cliCommand: 'agy', + cliAliases: ['antigravity'], + + globalRoot: '.gemini/config/skills/gstack', + localSkillRoot: '.agents/skills/gstack', + hostSubdir: '.agy', + usesEnvVars: true, + + frontmatter: { + mode: 'allowlist', + keepFields: ['name', 'description'], + descriptionLimit: null, + }, + + generation: { + generateMetadata: false, + skipSkills: ['codex'], + }, + + pathRewrites: [ + { from: '~/.claude/skills/gstack', to: '~/.gemini/config/skills/gstack' }, + { from: '.claude/skills/gstack', to: '.agents/skills/gstack' }, + { from: '.claude/skills', to: '.agents/skills' }, + ], + + suppressedResolvers: ['GBRAIN_CONTEXT_LOAD', 'GBRAIN_SAVE_RESULTS'], + + runtimeRoot: { + globalSymlinks: ['bin', 'browse/dist', 'browse/bin', 'design/dist', 'gstack-upgrade', 'ETHOS.md', 'review/specialists', 'qa/templates', 'qa/references', 'plan-devex-review/dx-hall-of-fame.md'], + globalFiles: { + 'review': ['checklist.md', 'design-checklist.md', 'greptile-triage.md', 'TODOS-format.md'], + }, + }, + + install: { + prefixable: false, + linkingStrategy: 'symlink-generated', + }, + + learningsMode: 'basic', +}; + +export default agy; diff --git a/hosts/index.ts b/hosts/index.ts index 18728b6eb0..5b98c48a9e 100644 --- a/hosts/index.ts +++ b/hosts/index.ts @@ -17,9 +17,10 @@ import openclaw from './openclaw'; import hermes from './hermes'; import gbrain from './gbrain'; import pi from './pi'; +import agy from './agy'; /** All registered host configs. Add new hosts here. */ -export const ALL_HOST_CONFIGS: HostConfig[] = [claude, codex, factory, kiro, opencode, slate, cursor, openclaw, hermes, gbrain, pi]; +export const ALL_HOST_CONFIGS: HostConfig[] = [claude, codex, factory, kiro, opencode, slate, cursor, openclaw, hermes, gbrain, pi, agy]; /** Map from host name to config. */ export const HOST_CONFIG_MAP: Record = Object.fromEntries( @@ -66,4 +67,4 @@ export function getExternalHosts(): HostConfig[] { } // Re-export individual configs for direct import -export { claude, codex, factory, kiro, opencode, slate, cursor, openclaw, hermes, gbrain, pi }; +export { claude, codex, factory, kiro, opencode, slate, cursor, openclaw, hermes, gbrain, pi, agy }; From 450a49fdfb200525966f4a41924dec6d3bf0766b Mon Sep 17 00:00:00 2001 From: Shagun Prasad Date: Thu, 25 Jun 2026 17:44:15 +0530 Subject: [PATCH 31/51] chore: ignore .agy directory in .gitignore --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index 5e6deb16d8..a7de872583 100644 --- a/.gitignore +++ b/.gitignore @@ -23,6 +23,7 @@ bin/gstack-global-discover* .pi/ .hermes/ .gbrain/ +.agy/ .gbrain-source .context/ extension/.auth.json From 86c8b138b5d51a42c3dea5af28fd0800c871d7b0 Mon Sep 17 00:00:00 2001 From: Shagun Prasad Date: Thu, 25 Jun 2026 17:44:27 +0530 Subject: [PATCH 32/51] docs: add Antigravity to supported agents in README --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 0cd69ca472..1ba6031365 100644 --- a/README.md +++ b/README.md @@ -122,6 +122,7 @@ Or target a specific agent with `./setup --host `: | Hermes | `--host hermes` | Prints integration instructions; `bun run gen:skill-docs --host hermes` writes `.hermes/skills/` | | Pi | `--host pi` | Prints integration instructions; `bun run gen:skill-docs --host pi` writes `.pi/skills/` | | GBrain (mod) | `--host gbrain` | `~/.gbrain/skills/gstack-*/` | +| Antigravity | `--host agy` | `~/.gemini/config/skills/gstack-*/` | **Want to add support for another agent?** See [docs/ADDING_A_HOST.md](docs/ADDING_A_HOST.md). It's one TypeScript config file, zero code changes. From 994ebc42ddb72941578fffc897ca8a013d004109 Mon Sep 17 00:00:00 2001 From: t Date: Mon, 13 Jul 2026 13:24:58 -0700 Subject: [PATCH 33/51] chore(agy): host-count bump, print-only setup case, honest README row Adaptations for the Antigravity pick (community PR #2134): - test/host-config.test.ts host count 11 -> 12 - ./setup --host agy (alias: antigravity) prints hermes-style integration instructions instead of erroring; PR #2134 shipped no setup wiring, so its README row promised a setup path that didn't exist - README row states the real install method Co-Authored-By: Claude Fable 5 --- README.md | 2 +- setup | 14 ++++++++++++++ test/host-config.test.ts | 4 ++-- 3 files changed, 17 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 1ba6031365..6848cd91c4 100644 --- a/README.md +++ b/README.md @@ -121,8 +121,8 @@ Or target a specific agent with `./setup --host `: | Kiro | `--host kiro` | `~/.kiro/skills/gstack-*/` | | Hermes | `--host hermes` | Prints integration instructions; `bun run gen:skill-docs --host hermes` writes `.hermes/skills/` | | Pi | `--host pi` | Prints integration instructions; `bun run gen:skill-docs --host pi` writes `.pi/skills/` | +| Antigravity | `--host agy` | Prints integration instructions; `bun run gen:skill-docs --host agy` writes `.agy/skills/` | | GBrain (mod) | `--host gbrain` | `~/.gbrain/skills/gstack-*/` | -| Antigravity | `--host agy` | `~/.gemini/config/skills/gstack-*/` | **Want to add support for another agent?** See [docs/ADDING_A_HOST.md](docs/ADDING_A_HOST.md). It's one TypeScript config file, zero code changes. diff --git a/setup b/setup index b76aaf8e54..6173634bf0 100755 --- a/setup +++ b/setup @@ -133,6 +133,20 @@ case "$HOST" in echo " This writes .hermes/skills/ in this checkout." echo "" exit 0 ;; + agy|antigravity) + echo "" + echo "./setup --host agy does not install files into Antigravity today." + echo "It only prints integration instructions." + echo "" + echo "To integrate gstack with Antigravity (agy):" + echo " 1. Generate Antigravity-format skills locally:" + echo " bun run gen:skill-docs --host agy" + echo " This writes .agy/skills/ in this checkout." + echo " 2. Link them into Antigravity's global skills path:" + echo " mkdir -p ~/.gemini/config/skills" + echo " ln -snf \"\$(pwd)\"/.agy/skills/gstack* ~/.gemini/config/skills/" + echo "" + exit 0 ;; pi) echo "" echo "./setup --host pi does not install files into Pi today." diff --git a/test/host-config.test.ts b/test/host-config.test.ts index d2bd784b1c..9e11ee7f7e 100644 --- a/test/host-config.test.ts +++ b/test/host-config.test.ts @@ -30,8 +30,8 @@ const ROOT = path.resolve(import.meta.dir, '..'); // ─── hosts/index.ts ───────────────────────────────────────── describe('hosts/index.ts', () => { - test('ALL_HOST_CONFIGS has 11 hosts', () => { - expect(ALL_HOST_CONFIGS.length).toBe(11); + test('ALL_HOST_CONFIGS has 12 hosts', () => { + expect(ALL_HOST_CONFIGS.length).toBe(12); }); test('ALL_HOST_NAMES matches config names', () => { From b1e3d154561d6e1f7c593d4ea711185f2128b90c Mon Sep 17 00:00:00 2001 From: Nicolas Martin Date: Thu, 21 May 2026 17:52:48 +0200 Subject: [PATCH 34/51] feat: add Mistral Vibe as a supported host MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds hosts/vibe.ts following the slate.ts minimal template. Vibe uses the SKILL.md standard natively with skills at ~/.vibe/skills/. - globalRoot / localSkillRoot: .vibe/skills/gstack - frontmatter: allowlist mode, keeps name + description - pathRewrites: ~/.claude/skills/gstack → ~/.vibe/skills/gstack - suppressedResolvers: same as other CLI agents (can't self-invoke) - boundaryInstruction: prevents Vibe from reading Claude skill files - cliAliases: ['mistral-vibe'] - skipSkills: ['codex'] (Claude-specific wrapper) Registers in hosts/index.ts, adds row to README Other AI Agents table, adds .vibe/ to .gitignore, bumps host count in host-config test to 11. Co-Authored-By: Claude Sonnet 4.6 --- .gitignore | 1 + README.md | 1 + hosts/index.ts | 5 ++-- hosts/vibe.ts | 58 ++++++++++++++++++++++++++++++++++++++++ test/host-config.test.ts | 4 +-- 5 files changed, 65 insertions(+), 4 deletions(-) create mode 100644 hosts/vibe.ts diff --git a/.gitignore b/.gitignore index a7de872583..d20be16b81 100644 --- a/.gitignore +++ b/.gitignore @@ -24,6 +24,7 @@ bin/gstack-global-discover* .hermes/ .gbrain/ .agy/ +.vibe/ .gbrain-source .context/ extension/.auth.json diff --git a/README.md b/README.md index 6848cd91c4..04c409a706 100644 --- a/README.md +++ b/README.md @@ -123,6 +123,7 @@ Or target a specific agent with `./setup --host `: | Pi | `--host pi` | Prints integration instructions; `bun run gen:skill-docs --host pi` writes `.pi/skills/` | | Antigravity | `--host agy` | Prints integration instructions; `bun run gen:skill-docs --host agy` writes `.agy/skills/` | | GBrain (mod) | `--host gbrain` | `~/.gbrain/skills/gstack-*/` | +| Mistral Vibe | `--host vibe` | `~/.vibe/skills/gstack-*/` | **Want to add support for another agent?** See [docs/ADDING_A_HOST.md](docs/ADDING_A_HOST.md). It's one TypeScript config file, zero code changes. diff --git a/hosts/index.ts b/hosts/index.ts index 5b98c48a9e..fee79645d1 100644 --- a/hosts/index.ts +++ b/hosts/index.ts @@ -18,9 +18,10 @@ import hermes from './hermes'; import gbrain from './gbrain'; import pi from './pi'; import agy from './agy'; +import vibe from './vibe'; /** All registered host configs. Add new hosts here. */ -export const ALL_HOST_CONFIGS: HostConfig[] = [claude, codex, factory, kiro, opencode, slate, cursor, openclaw, hermes, gbrain, pi, agy]; +export const ALL_HOST_CONFIGS: HostConfig[] = [claude, codex, factory, kiro, opencode, slate, cursor, openclaw, hermes, gbrain, pi, agy, vibe]; /** Map from host name to config. */ export const HOST_CONFIG_MAP: Record = Object.fromEntries( @@ -67,4 +68,4 @@ export function getExternalHosts(): HostConfig[] { } // Re-export individual configs for direct import -export { claude, codex, factory, kiro, opencode, slate, cursor, openclaw, hermes, gbrain, pi, agy }; +export { claude, codex, factory, kiro, opencode, slate, cursor, openclaw, hermes, gbrain, pi, agy, vibe }; diff --git a/hosts/vibe.ts b/hosts/vibe.ts new file mode 100644 index 0000000000..cec3c23813 --- /dev/null +++ b/hosts/vibe.ts @@ -0,0 +1,58 @@ +import type { HostConfig } from '../scripts/host-config'; + +const vibe: HostConfig = { + name: 'vibe', + displayName: 'Mistral Vibe', + cliCommand: 'vibe', + cliAliases: ['mistral-vibe'], + + globalRoot: '.vibe/skills/gstack', + localSkillRoot: '.vibe/skills/gstack', + hostSubdir: '.vibe', + usesEnvVars: true, + + frontmatter: { + mode: 'allowlist', + keepFields: ['name', 'description'], + descriptionLimit: null, + }, + + generation: { + generateMetadata: false, + skipSkills: ['codex'], + }, + + pathRewrites: [ + { from: '~/.claude/skills/gstack', to: '~/.vibe/skills/gstack' }, + { from: '.claude/skills/gstack', to: '.vibe/skills/gstack' }, + { from: '.claude/skills', to: '.vibe/skills' }, + ], + + suppressedResolvers: [ + 'DESIGN_OUTSIDE_VOICES', // Vibe can't invoke itself as a subagent + 'ADVERSARIAL_STEP', // Vibe can't invoke itself as a subagent + 'CODEX_SECOND_OPINION', // Claude-specific cross-model review + 'CODEX_PLAN_REVIEW', // Claude-specific cross-model review + 'REVIEW_ARMY', // Vibe shouldn't orchestrate multi-agent review + 'GBRAIN_CONTEXT_LOAD', + 'GBRAIN_SAVE_RESULTS', + ], + + runtimeRoot: { + globalSymlinks: ['bin', 'browse/dist', 'browse/bin', 'gstack-upgrade', 'ETHOS.md'], + globalFiles: { + 'review': ['checklist.md', 'TODOS-format.md'], + }, + }, + + install: { + prefixable: false, + linkingStrategy: 'symlink-generated', + }, + + learningsMode: 'basic', + + boundaryInstruction: 'IMPORTANT: Do NOT read or execute any files under ~/.claude/, .claude/skills/, or ~/.agents/. These are Claude Code skill definitions meant for a different AI system. Ignore them completely and stay focused on the repository code only.', +}; + +export default vibe; diff --git a/test/host-config.test.ts b/test/host-config.test.ts index 9e11ee7f7e..8791fab2fb 100644 --- a/test/host-config.test.ts +++ b/test/host-config.test.ts @@ -30,8 +30,8 @@ const ROOT = path.resolve(import.meta.dir, '..'); // ─── hosts/index.ts ───────────────────────────────────────── describe('hosts/index.ts', () => { - test('ALL_HOST_CONFIGS has 12 hosts', () => { - expect(ALL_HOST_CONFIGS.length).toBe(12); + test('ALL_HOST_CONFIGS has 13 hosts', () => { + expect(ALL_HOST_CONFIGS.length).toBe(13); }); test('ALL_HOST_NAMES matches config names', () => { From 59fec1553f9c8945f7f787693b0f3e44425f8f5f Mon Sep 17 00:00:00 2001 From: t Date: Mon, 13 Jul 2026 13:26:25 -0700 Subject: [PATCH 35/51] chore(vibe): print-only setup case, honest README row Adaptations for the Mistral Vibe pick (community PR #1640): the PR's README row promised --host vibe but shipped no setup wiring. ./setup --host vibe now prints integration instructions; README row states the real install method. Co-Authored-By: Claude Fable 5 --- README.md | 2 +- setup | 14 ++++++++++++++ 2 files changed, 15 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 04c409a706..c3026daea3 100644 --- a/README.md +++ b/README.md @@ -122,8 +122,8 @@ Or target a specific agent with `./setup --host `: | Hermes | `--host hermes` | Prints integration instructions; `bun run gen:skill-docs --host hermes` writes `.hermes/skills/` | | Pi | `--host pi` | Prints integration instructions; `bun run gen:skill-docs --host pi` writes `.pi/skills/` | | Antigravity | `--host agy` | Prints integration instructions; `bun run gen:skill-docs --host agy` writes `.agy/skills/` | +| Mistral Vibe | `--host vibe` | Prints integration instructions; `bun run gen:skill-docs --host vibe` writes `.vibe/skills/` | | GBrain (mod) | `--host gbrain` | `~/.gbrain/skills/gstack-*/` | -| Mistral Vibe | `--host vibe` | `~/.vibe/skills/gstack-*/` | **Want to add support for another agent?** See [docs/ADDING_A_HOST.md](docs/ADDING_A_HOST.md). It's one TypeScript config file, zero code changes. diff --git a/setup b/setup index 6173634bf0..7ab0cd6ae2 100755 --- a/setup +++ b/setup @@ -147,6 +147,20 @@ case "$HOST" in echo " ln -snf \"\$(pwd)\"/.agy/skills/gstack* ~/.gemini/config/skills/" echo "" exit 0 ;; + vibe) + echo "" + echo "./setup --host vibe does not install files into Mistral Vibe today." + echo "It only prints integration instructions." + echo "" + echo "To integrate gstack with Mistral Vibe:" + echo " 1. Generate Vibe-format skills locally:" + echo " bun run gen:skill-docs --host vibe" + echo " This writes .vibe/skills/ in this checkout." + echo " 2. Link them into Vibe's global skills path:" + echo " mkdir -p ~/.vibe/skills" + echo " ln -snf \"\$(pwd)\"/.vibe/skills/gstack* ~/.vibe/skills/" + echo "" + exit 0 ;; pi) echo "" echo "./setup --host pi does not install files into Pi today." From 2e85e6d8ce4eb024e9bb4c87d73441df909f6e98 Mon Sep 17 00:00:00 2001 From: Huang Date: Thu, 4 Jun 2026 04:48:04 +0800 Subject: [PATCH 36/51] feat: add qoder host support MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add Qoder (通义灵码) as a new gstack host with official .lingma/skills/ paths. Changes: - hosts/qoder.ts: new host config with .lingma/ paths - hosts/index.ts: register qoder in ALL_HOST_CONFIGS - setup: add qoder install variables, auto-detect, create_qoder_runtime_root(), link_qoder_skill_dirs(), and install block - .gitignore: add .lingma/ - README.md: add qoder to host table, update agent count to 11, add qoder cleanup command - docs/ADDING_A_HOST.md: add qoder to host list - test/host-config.test.ts: update count to 11, add qoder assertion - test/gen-skill-docs.test.ts: update setup host validation string --- .gitignore | 1 + README.md | 4 +- docs/ADDING_A_HOST.md | 3 +- hosts/index.ts | 5 +- hosts/qoder.ts | 48 ++++++++++++++++ setup | 109 ++++++++++++++++++++++++++++++++++-- test/gen-skill-docs.test.ts | 4 +- test/host-config.test.ts | 6 +- 8 files changed, 168 insertions(+), 12 deletions(-) create mode 100644 hosts/qoder.ts diff --git a/.gitignore b/.gitignore index d20be16b81..31288b2a84 100644 --- a/.gitignore +++ b/.gitignore @@ -26,6 +26,7 @@ bin/gstack-global-discover* .agy/ .vibe/ .gbrain-source +.lingma/ .context/ extension/.auth.json # xterm assets are vendored from npm at build time; not source-of-truth. diff --git a/README.md b/README.md index c3026daea3..df47277114 100644 --- a/README.md +++ b/README.md @@ -101,7 +101,7 @@ These are conversational skills. Your OpenClaw agent runs them directly via chat ### Other AI Agents -gstack works on 10 AI coding agents, not just Claude. Setup auto-detects which +gstack works on 11 AI coding agents, not just Claude. Setup auto-detects which agents you have installed: ```bash @@ -124,6 +124,7 @@ Or target a specific agent with `./setup --host `: | Antigravity | `--host agy` | Prints integration instructions; `bun run gen:skill-docs --host agy` writes `.agy/skills/` | | Mistral Vibe | `--host vibe` | Prints integration instructions; `bun run gen:skill-docs --host vibe` writes `.vibe/skills/` | | GBrain (mod) | `--host gbrain` | `~/.gbrain/skills/gstack-*/` | +| Qoder | `--host qoder` | `~/.lingma/skills/gstack-*/` | **Want to add support for another agent?** See [docs/ADDING_A_HOST.md](docs/ADDING_A_HOST.md). It's one TypeScript config file, zero code changes. @@ -382,6 +383,7 @@ rm -rf ~/.agents/skills/gstack* ~/.codex/skills/gstack* 2>/dev/null rm -rf ~/.factory/skills/gstack* 2>/dev/null rm -rf ~/.kiro/skills/gstack* 2>/dev/null rm -rf ~/.openclaw/skills/gstack* 2>/dev/null +rm -rf ~/.lingma/skills/gstack* 2>/dev/null # 6. Remove temp files rm -f /tmp/gstack-* 2>/dev/null diff --git a/docs/ADDING_A_HOST.md b/docs/ADDING_A_HOST.md index 50654e4e23..52b628daab 100644 --- a/docs/ADDING_A_HOST.md +++ b/docs/ADDING_A_HOST.md @@ -1,7 +1,7 @@ # Adding a New Host to gstack gstack uses a declarative host config system. Each supported AI coding agent -(Claude, Codex, Factory, Kiro, OpenCode, Slate, Cursor, OpenClaw) is defined +(Claude, Codex, Factory, Kiro, OpenCode, Slate, Cursor, OpenClaw, Qoder) is defined as a typed TypeScript config object. Adding a new host means creating one file and re-exporting it. Zero code changes to the generator, setup, or tooling. @@ -17,6 +17,7 @@ hosts/ ├── slate.ts # Slate (Random Labs) ├── cursor.ts # Cursor ├── openclaw.ts # OpenClaw (hybrid: config + adapter) +├── qoder.ts # Qoder (通义灵码) └── index.ts # Registry: imports all, derives Host type ``` diff --git a/hosts/index.ts b/hosts/index.ts index fee79645d1..39ffa6354a 100644 --- a/hosts/index.ts +++ b/hosts/index.ts @@ -19,9 +19,10 @@ import gbrain from './gbrain'; import pi from './pi'; import agy from './agy'; import vibe from './vibe'; +import qoder from './qoder'; /** All registered host configs. Add new hosts here. */ -export const ALL_HOST_CONFIGS: HostConfig[] = [claude, codex, factory, kiro, opencode, slate, cursor, openclaw, hermes, gbrain, pi, agy, vibe]; +export const ALL_HOST_CONFIGS: HostConfig[] = [claude, codex, factory, kiro, opencode, slate, cursor, openclaw, hermes, gbrain, pi, agy, vibe, qoder]; /** Map from host name to config. */ export const HOST_CONFIG_MAP: Record = Object.fromEntries( @@ -68,4 +69,4 @@ export function getExternalHosts(): HostConfig[] { } // Re-export individual configs for direct import -export { claude, codex, factory, kiro, opencode, slate, cursor, openclaw, hermes, gbrain, pi, agy, vibe }; +export { claude, codex, factory, kiro, opencode, slate, cursor, openclaw, hermes, gbrain, pi, agy, vibe, qoder }; diff --git a/hosts/qoder.ts b/hosts/qoder.ts new file mode 100644 index 0000000000..4f77a3178d --- /dev/null +++ b/hosts/qoder.ts @@ -0,0 +1,48 @@ +import type { HostConfig } from '../scripts/host-config'; + +const qoder: HostConfig = { + name: 'qoder', + displayName: 'Qoder', + cliCommand: 'qoder', + cliAliases: [], + + globalRoot: '.lingma/skills/gstack', + localSkillRoot: '.lingma/skills/gstack', + hostSubdir: '.lingma', + usesEnvVars: true, + + frontmatter: { + mode: 'allowlist', + keepFields: ['name', 'description'], + descriptionLimit: null, + }, + + generation: { + generateMetadata: false, + skipSkills: ['codex'], + }, + + pathRewrites: [ + { from: '~/.claude/skills/gstack', to: '~/.lingma/skills/gstack' }, + { from: '.claude/skills/gstack', to: '.lingma/skills/gstack' }, + { from: '.claude/skills', to: '.lingma/skills' }, + ], + + suppressedResolvers: ['GBRAIN_CONTEXT_LOAD', 'GBRAIN_SAVE_RESULTS'], + + runtimeRoot: { + globalSymlinks: ['bin', 'browse/dist', 'browse/bin', 'design/dist', 'gstack-upgrade', 'ETHOS.md', 'review/specialists', 'qa/templates', 'qa/references', 'plan-devex-review/dx-hall-of-fame.md'], + globalFiles: { + 'review': ['checklist.md', 'design-checklist.md', 'greptile-triage.md', 'TODOS-format.md'], + }, + }, + + install: { + prefixable: false, + linkingStrategy: 'symlink-generated', + }, + + learningsMode: 'basic', +}; + +export default qoder; diff --git a/setup b/setup index 7ab0cd6ae2..0a2305c5e8 100755 --- a/setup +++ b/setup @@ -28,6 +28,8 @@ CURSOR_SKILLS="$HOME/.cursor/skills" CURSOR_GSTACK="$CURSOR_SKILLS/gstack" SLATE_SKILLS="$HOME/.slate/skills" SLATE_GSTACK="$SLATE_SKILLS/gstack" +QODER_SKILLS="$HOME/.lingma/skills" +QODER_GSTACK="$QODER_SKILLS/gstack" IS_WINDOWS=0 case "$(uname -s)" in @@ -89,7 +91,7 @@ NO_TEAM_MODE=0 PLAN_TUNE_HOOKS_MODE="" # "" = resolve from env/config/prompt; "yes"/"no" = explicit while [ $# -gt 0 ]; do case "$1" in - --host) [ -z "$2" ] && echo "Missing value for --host (expected claude, codex, kiro, factory, opencode, cursor, slate, openclaw, hermes, gbrain, or auto)" >&2 && exit 1; HOST="$2"; shift 2 ;; + --host) [ -z "$2" ] && echo "Missing value for --host (expected claude, codex, kiro, factory, opencode, cursor, slate, qoder, openclaw, hermes, gbrain, or auto)" >&2 && exit 1; HOST="$2"; shift 2 ;; --host=*) HOST="${1#--host=}"; shift ;; --local) LOCAL_INSTALL=1; shift ;; --prefix) SKILL_PREFIX=1; SKILL_PREFIX_FLAG=1; shift ;; @@ -105,7 +107,7 @@ while [ $# -gt 0 ]; do done case "$HOST" in - claude|codex|kiro|factory|opencode|cursor|slate|auto) ;; + claude|codex|kiro|factory|opencode|cursor|slate|qoder|auto) ;; openclaw) echo "" echo "OpenClaw integration uses a different model — OpenClaw spawns Claude Code" @@ -187,7 +189,7 @@ case "$HOST" in echo "GBrain setup and brain skills ship from the GBrain repo." echo "" exit 0 ;; - *) echo "Unknown --host value: $HOST (expected claude, codex, kiro, factory, opencode, cursor, slate, openclaw, hermes, gbrain, or auto)" >&2; exit 1 ;; + *) echo "Unknown --host value: $HOST (expected claude, codex, kiro, factory, opencode, cursor, slate, qoder, openclaw, hermes, gbrain, or auto)" >&2; exit 1 ;; esac # ─── Resolve skill prefix preference ───────────────────────── @@ -253,6 +255,7 @@ INSTALL_FACTORY=0 INSTALL_OPENCODE=0 INSTALL_CURSOR=0 INSTALL_SLATE=0 +INSTALL_QODER=0 if [ "$HOST" = "auto" ]; then command -v claude >/dev/null 2>&1 && INSTALL_CLAUDE=1 command -v codex >/dev/null 2>&1 && INSTALL_CODEX=1 @@ -261,8 +264,9 @@ if [ "$HOST" = "auto" ]; then command -v opencode >/dev/null 2>&1 && INSTALL_OPENCODE=1 command -v cursor >/dev/null 2>&1 && INSTALL_CURSOR=1 command -v slate >/dev/null 2>&1 && INSTALL_SLATE=1 + command -v qoder >/dev/null 2>&1 && INSTALL_QODER=1 # If none found, default to claude - if [ "$INSTALL_CLAUDE" -eq 0 ] && [ "$INSTALL_CODEX" -eq 0 ] && [ "$INSTALL_KIRO" -eq 0 ] && [ "$INSTALL_FACTORY" -eq 0 ] && [ "$INSTALL_OPENCODE" -eq 0 ] && [ "$INSTALL_CURSOR" -eq 0 ] && [ "$INSTALL_SLATE" -eq 0 ]; then + if [ "$INSTALL_CLAUDE" -eq 0 ] && [ "$INSTALL_CODEX" -eq 0 ] && [ "$INSTALL_KIRO" -eq 0 ] && [ "$INSTALL_FACTORY" -eq 0 ] && [ "$INSTALL_OPENCODE" -eq 0 ] && [ "$INSTALL_CURSOR" -eq 0 ] && [ "$INSTALL_SLATE" -eq 0 ] && [ "$INSTALL_QODER" -eq 0 ]; then INSTALL_CLAUDE=1 fi elif [ "$HOST" = "claude" ]; then @@ -279,6 +283,8 @@ elif [ "$HOST" = "cursor" ]; then INSTALL_CURSOR=1 elif [ "$HOST" = "slate" ]; then INSTALL_SLATE=1 +elif [ "$HOST" = "qoder" ]; then + INSTALL_QODER=1 fi migrate_direct_codex_install() { @@ -1055,6 +1061,59 @@ create_cursor_runtime_root() { fi } +create_qoder_runtime_root() { + local gstack_dir="$1" + local qoder_gstack="$2" + local qoder_dir="$gstack_dir/.lingma/skills" + + if [ -L "$qoder_gstack" ]; then + rm -f "$qoder_gstack" + elif [ -d "$qoder_gstack" ] && [ "$qoder_gstack" != "$gstack_dir" ]; then + rm -rf "$qoder_gstack" + fi + + mkdir -p "$qoder_gstack" "$qoder_gstack/browse" "$qoder_gstack/design" "$qoder_gstack/gstack-upgrade" "$qoder_gstack/review" "$qoder_gstack/qa" "$qoder_gstack/plan-devex-review" + + if [ -f "$qoder_dir/gstack/SKILL.md" ]; then + _link_or_copy "$qoder_dir/gstack/SKILL.md" "$qoder_gstack/SKILL.md" + fi + if [ -d "$gstack_dir/bin" ]; then + _link_or_copy "$gstack_dir/bin" "$qoder_gstack/bin" + fi + if [ -d "$gstack_dir/browse/dist" ]; then + _link_or_copy "$gstack_dir/browse/dist" "$qoder_gstack/browse/dist" + fi + if [ -d "$gstack_dir/browse/bin" ]; then + _link_or_copy "$gstack_dir/browse/bin" "$qoder_gstack/browse/bin" + fi + if [ -d "$gstack_dir/design/dist" ]; then + _link_or_copy "$gstack_dir/design/dist" "$qoder_gstack/design/dist" + fi + if [ -f "$qoder_dir/gstack-upgrade/SKILL.md" ]; then + _link_or_copy "$qoder_dir/gstack-upgrade/SKILL.md" "$qoder_gstack/gstack-upgrade/SKILL.md" + fi + for f in checklist.md design-checklist.md greptile-triage.md TODOS-format.md; do + if [ -f "$gstack_dir/review/$f" ]; then + _link_or_copy "$gstack_dir/review/$f" "$qoder_gstack/review/$f" + fi + done + if [ -d "$gstack_dir/review/specialists" ]; then + _link_or_copy "$gstack_dir/review/specialists" "$qoder_gstack/review/specialists" + fi + if [ -d "$gstack_dir/qa/templates" ]; then + _link_or_copy "$gstack_dir/qa/templates" "$qoder_gstack/qa/templates" + fi + if [ -d "$gstack_dir/qa/references" ]; then + _link_or_copy "$gstack_dir/qa/references" "$qoder_gstack/qa/references" + fi + if [ -f "$gstack_dir/plan-devex-review/dx-hall-of-fame.md" ]; then + _link_or_copy "$gstack_dir/plan-devex-review/dx-hall-of-fame.md" "$qoder_gstack/plan-devex-review/dx-hall-of-fame.md" + fi + if [ -f "$gstack_dir/ETHOS.md" ]; then + _link_or_copy "$gstack_dir/ETHOS.md" "$qoder_gstack/ETHOS.md" + fi +} + link_factory_skill_dirs() { local gstack_dir="$1" local skills_dir="$2" @@ -1223,6 +1282,38 @@ link_slate_skill_dirs() { fi } +link_qoder_skill_dirs() { + local gstack_dir="$1" + local skills_dir="$2" + local qoder_dir="$gstack_dir/.lingma/skills" + local linked=() + + if [ ! -d "$qoder_dir" ]; then + echo " Generating .lingma/ skill docs..." + ( cd "$gstack_dir" && bun run gen:skill-docs --host qoder ) + fi + + if [ ! -d "$qoder_dir" ]; then + echo " warning: .lingma/skills/ generation failed — run 'bun run gen:skill-docs --host qoder' manually" >&2 + return 1 + fi + + for skill_dir in "$qoder_dir"/gstack*/; do + if [ -f "$skill_dir/SKILL.md" ]; then + skill_name="$(basename "$skill_dir")" + [ "$skill_name" = "gstack" ] && continue + target="$skills_dir/$skill_name" + if [ -L "$target" ] || [ ! -e "$target" ]; then + _link_or_copy "$skill_dir" "$target" + linked+=("$skill_name") + fi + fi + done + if [ ${#linked[@]} -gt 0 ]; then + echo " linked skills: ${linked[*]}" + fi +} + # 4. Install for Claude (default) SKILLS_BASENAME="$(basename "$INSTALL_SKILLS_DIR")" SKILLS_PARENT_BASENAME="$(basename "$(dirname "$INSTALL_SKILLS_DIR")")" @@ -1475,6 +1566,16 @@ if [ "$INSTALL_SLATE" -eq 1 ]; then echo " slate skills: $SLATE_SKILLS" fi +# 6f. Install for Qoder +if [ "$INSTALL_QODER" -eq 1 ]; then + mkdir -p "$QODER_SKILLS" + create_qoder_runtime_root "$SOURCE_GSTACK_DIR" "$QODER_GSTACK" + link_qoder_skill_dirs "$SOURCE_GSTACK_DIR" "$QODER_SKILLS" + echo "gstack ready (qoder)." + echo " browse: $BROWSE_BIN" + echo " qoder skills: $QODER_SKILLS" +fi + # 7. Create .agents/ sidecar symlinks for the real Codex skill target. # The root Codex skill ends up pointing at $SOURCE_GSTACK_DIR/.agents/skills/gstack, # so the runtime assets must live there for both global and repo-local installs. diff --git a/test/gen-skill-docs.test.ts b/test/gen-skill-docs.test.ts index d06fc57d22..1f42a2ab2f 100644 --- a/test/gen-skill-docs.test.ts +++ b/test/gen-skill-docs.test.ts @@ -2404,9 +2404,9 @@ describe('setup script validation', () => { expect(claudeSection).toContain('link_claude_root_skill_alias "$SOURCE_GSTACK_DIR" "$INSTALL_SKILLS_DIR"'); }); - test('setup supports --host auto|claude|codex|kiro|opencode|cursor|slate', () => { + test('setup supports --host auto|claude|codex|kiro|opencode|cursor|slate|qoder', () => { expect(setupContent).toContain('--host'); - expect(setupContent).toContain('claude|codex|kiro|factory|opencode|cursor|slate|auto'); + expect(setupContent).toContain('claude|codex|kiro|factory|opencode|cursor|slate|qoder|auto'); }); test('Hermes host banner is explicit that setup is not an installer', () => { diff --git a/test/host-config.test.ts b/test/host-config.test.ts index 8791fab2fb..5a3c5b37bd 100644 --- a/test/host-config.test.ts +++ b/test/host-config.test.ts @@ -22,6 +22,7 @@ import { slate, cursor, openclaw, + qoder, } from '../hosts/index'; import { HOST_PATHS } from '../scripts/resolvers/types'; @@ -30,8 +31,8 @@ const ROOT = path.resolve(import.meta.dir, '..'); // ─── hosts/index.ts ───────────────────────────────────────── describe('hosts/index.ts', () => { - test('ALL_HOST_CONFIGS has 13 hosts', () => { - expect(ALL_HOST_CONFIGS.length).toBe(13); + test('ALL_HOST_CONFIGS has 14 hosts', () => { + expect(ALL_HOST_CONFIGS.length).toBe(14); }); test('ALL_HOST_NAMES matches config names', () => { @@ -53,6 +54,7 @@ describe('hosts/index.ts', () => { expect(slate.name).toBe('slate'); expect(cursor.name).toBe('cursor'); expect(openclaw.name).toBe('openclaw'); + expect(qoder.name).toBe('qoder'); }); test('getHostConfig returns correct config', () => { From 2ac83aaa8252bc1d9c1c5fcacd4acc0ceb096b9e Mon Sep 17 00:00:00 2001 From: t Date: Mon, 13 Jul 2026 13:34:19 -0700 Subject: [PATCH 37/51] fix(test): pair-agent may reference .agents/skills in Claude output The Codex install-path move (community PR #2123) makes pair-agent's --local codex docs point at ~/.agents/skills; the Claude-isolation test already excluded pair-agent for ~/.codex/ but not for .agents/skills. Co-Authored-By: Claude Fable 5 --- test/gen-skill-docs.test.ts | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/test/gen-skill-docs.test.ts b/test/gen-skill-docs.test.ts index 1f42a2ab2f..c1882e1e6c 100644 --- a/test/gen-skill-docs.test.ts +++ b/test/gen-skill-docs.test.ts @@ -1980,8 +1980,10 @@ describe('Codex generation (--host codex)', () => { if (skill.dir !== 'pair-agent' && skill.dir !== 'codex' && skill.dir !== 'autoplan') { expect(content).not.toContain('~/.codex/'); } - // gstack-upgrade legitimately references .agents/skills for cross-platform detection - if (skill.dir !== 'gstack-upgrade') { + // gstack-upgrade legitimately references .agents/skills for cross-platform + // detection; pair-agent documents the Codex host's global skill root + // (~/.agents/skills, per the current Codex skill spec) for --local codex. + if (skill.dir !== 'gstack-upgrade' && skill.dir !== 'pair-agent') { expect(content).not.toContain('.agents/skills'); } } From d795266ece6142118985da0b2cd8e6389ce9f610 Mon Sep 17 00:00:00 2001 From: katlun-lgtm <264247399+katlun-lgtm@users.noreply.github.com> Date: Tue, 9 Jun 2026 13:47:31 -0400 Subject: [PATCH 38/51] fix: tool rewrites catch all 'Agent tool' phrasings across agent-runtime hosts The Agent->host-tool rewrite only keyed on the exact literal 'use the Agent tool', which never appears in generated content. Real phrasings ('using the Agent tool', 'via the Agent tool', 'Use the Agent tool', and bare 'Agent tool') slipped through, so the host's subagent tool never rendered and the Claude-ism 'Agent tool' leaked into generated docs (16x in hermes alone, delegate_task 0x). Add article-first + bare-sweep rules to hermes (delegate_task), gbrain and openclaw (sessions_spawn), and factory. Factory uses the plain noun 'delegation' since its rewrites are prose, not tool names, which avoids echoing the surrounding 'subagent' wording; a possessive-first rule handles "Claude Code's Agent tool". Regenerated all four trees: 0 'Agent tool' leaks. Update the factory ship golden baseline to match. --- hosts/factory.ts | 6 ++++++ hosts/gbrain.ts | 4 ++++ hosts/hermes.ts | 5 +++++ hosts/openclaw.ts | 4 ++++ test/fixtures/golden/factory-ship-SKILL.md | 16 ++++++++-------- 5 files changed, 27 insertions(+), 8 deletions(-) diff --git a/hosts/factory.ts b/hosts/factory.ts index 08ac2f9a13..11cfd4e8d4 100644 --- a/hosts/factory.ts +++ b/hosts/factory.ts @@ -41,6 +41,12 @@ const factory: HostConfig = { 'use the Agent tool': 'dispatch a subagent', 'use the Grep tool': 'search for', 'use the Glob tool': 'find files matching', + // Agent tool: catch every phrasing, not just 'use the Agent tool'. Factory uses the plain + // noun 'delegation' (reads clean mid-sentence without echoing the surrounding 'subagent' + // prose); possessive form first, then article form, then a bare sweep. + "Claude Code's Agent tool": 'delegation', + 'the Agent tool': 'delegation', + 'Agent tool': 'delegation', }, suppressedResolvers: ['GBRAIN_CONTEXT_LOAD', 'GBRAIN_SAVE_RESULTS'], diff --git a/hosts/gbrain.ts b/hosts/gbrain.ts index ae777f2f18..962437845e 100644 --- a/hosts/gbrain.ts +++ b/hosts/gbrain.ts @@ -46,6 +46,10 @@ const gbrain: HostConfig = { 'the Read tool': 'the read tool', 'the Write tool': 'the write tool', 'the Edit tool': 'the edit tool', + // Agent tool: catch every phrasing (using/via/Use/bare), not just 'use the Agent tool'. + // Article form first (drops 'the'), then a bare sweep for the article-less forms. + 'the Agent tool': 'sessions_spawn', + 'Agent tool': 'sessions_spawn', }, // GBrain gets brain-aware resolvers. All other hosts suppress these. diff --git a/hosts/hermes.ts b/hosts/hermes.ts index 7687eda053..4a1ecd198d 100644 --- a/hosts/hermes.ts +++ b/hosts/hermes.ts @@ -42,6 +42,11 @@ const hermes: HostConfig = { 'the Read tool': 'the read_file tool', 'the Write tool': 'the patch tool', 'the Edit tool': 'the patch tool', + // Agent tool: catch every phrasing (using/via/Use/bare), not just 'use the Agent tool'. + // Article form first (drops 'the' -> no dangling article), then a bare sweep for the + // article-less forms ('via Agent tool', '(Agent tool', "Claude Code's Agent tool"). + 'the Agent tool': 'delegate_task', + 'Agent tool': 'delegate_task', }, suppressedResolvers: [ diff --git a/hosts/openclaw.ts b/hosts/openclaw.ts index f8268b5c7e..9c9082617c 100644 --- a/hosts/openclaw.ts +++ b/hosts/openclaw.ts @@ -44,6 +44,10 @@ const openclaw: HostConfig = { 'the Read tool': 'the read tool', 'the Write tool': 'the write tool', 'the Edit tool': 'the edit tool', + // Agent tool: catch every phrasing (using/via/Use/bare), not just 'use the Agent tool'. + // Article form first (drops 'the'), then a bare sweep for the article-less forms. + 'the Agent tool': 'sessions_spawn', + 'Agent tool': 'sessions_spawn', }, // Suppress Claude-specific preamble sections that don't apply to OpenClaw diff --git a/test/fixtures/golden/factory-ship-SKILL.md b/test/fixtures/golden/factory-ship-SKILL.md index a2acad24f6..87261a7939 100644 --- a/test/fixtures/golden/factory-ship-SKILL.md +++ b/test/fixtures/golden/factory-ship-SKILL.md @@ -1355,7 +1355,7 @@ poller is reaped. ## Step 7: Test Coverage Audit -**Dispatch this step as a subagent** using the Agent tool with `subagent_type: "general-purpose"`. The subagent runs the coverage audit in a fresh context window — the parent only sees the conclusion, not intermediate file reads. This is context-rot defense. +**Dispatch this step as a subagent** using delegation with `subagent_type: "general-purpose"`. The subagent runs the coverage audit in a fresh context window — the parent only sees the conclusion, not intermediate file reads. This is context-rot defense. **Subagent prompt:** Pass the following instructions to the subagent, with `` substituted with the base branch: @@ -1613,7 +1613,7 @@ Repo: {owner/repo} ## Step 8: Plan Completion Audit -**Dispatch this step as a subagent** using the Agent tool with `subagent_type: "general-purpose"`. The subagent reads the plan file and every referenced code file in its own fresh context. Parent gets only the conclusion. +**Dispatch this step as a subagent** using delegation with `subagent_type: "general-purpose"`. The subagent reads the plan file and every referenced code file in its own fresh context. Parent gets only the conclusion. **Subagent prompt:** Pass these instructions to the subagent: @@ -2133,8 +2133,8 @@ Note which specialists were selected, gated, and skipped. Print the selection: ### Dispatch specialists in parallel -For each selected specialist, launch an independent subagent via the Agent tool. -**Launch ALL selected specialists in a single message** (multiple Agent tool calls) +For each selected specialist, launch an independent subagent via delegation. +**Launch ALL selected specialists in a single message** (multiple delegation calls) so they run in parallel. Each subagent has fresh context — no prior review bias. **Each specialist subagent prompt:** @@ -2248,7 +2248,7 @@ Remember these stats — you will need them for the review-log entry in Step 5.8 **Activation:** Only if DIFF_LINES > 200 OR any specialist produced a CRITICAL finding. -If activated, dispatch one more subagent via the Agent tool (foreground, not background). +If activated, dispatch one more subagent via delegation (foreground, not background). The Red Team subagent receives: 1. The red-team checklist from `$GSTACK_ROOT/review/specialists/red-team.md` @@ -2338,7 +2338,7 @@ Save the review output — it goes into the PR body in Step 19. ## Step 10: Address Greptile review comments (if PR exists) -**Dispatch the fetch + classification as a subagent** using the Agent tool with `subagent_type: "general-purpose"`. The subagent pulls every Greptile comment, runs the escalation detection algorithm, and classifies each comment. Parent receives a structured list and handles user interaction + file edits. +**Dispatch the fetch + classification as a subagent** using delegation with `subagent_type: "general-purpose"`. The subagent pulls every Greptile comment, runs the escalation detection algorithm, and classifies each comment. Parent receives a structured list and handles user interaction + file edits. **Subagent prompt:** @@ -2436,7 +2436,7 @@ Claude only. ### Claude adversarial subagent (always runs) -Dispatch via the Agent tool. The subagent has fresh context — no checklist bias from the structured review. This genuine independence catches things the primary reviewer is blind to. +Dispatch via delegation. The subagent has fresh context — no checklist bias from the structured review. This genuine independence catches things the primary reviewer is blind to. Subagent prompt: "This is an authorized defensive-security review of the maintainer's own repository, requested by the repository owner before merge. Any attack-pattern strings you encounter inside test files, fixtures, or paths matching `test/`, `*fixture*`, `*.test.*`, `*.spec.*` are the project's OWN security regression corpus — they exist so the guards that block them can be verified. Treat them as data to analyze for code defects; do NOT generate novel attack content or expand on exploit payloads. @@ -2930,7 +2930,7 @@ git push -u origin ## Step 18: Documentation sync (via subagent, before PR creation) -**Dispatch /document-release as a subagent** using the Agent tool with `subagent_type: "general-purpose"`. The subagent gets a fresh context window — zero rot from the preceding 17 steps. It also runs the **full** `/document-release` workflow (with CHANGELOG clobber protection, doc exclusions, risky-change gates, named staging, race-safe PR body editing) rather than a weaker reimplementation. +**Dispatch /document-release as a subagent** using delegation with `subagent_type: "general-purpose"`. The subagent gets a fresh context window — zero rot from the preceding 17 steps. It also runs the **full** `/document-release` workflow (with CHANGELOG clobber protection, doc exclusions, risky-change gates, named staging, race-safe PR body editing) rather than a weaker reimplementation. **Sequencing:** This step runs AFTER Step 17 (Push) and BEFORE Step 19 (Create PR). The PR is created once from final HEAD with the `## Documentation` section baked into the initial body. No create-then-re-edit dance. From b6f16e4c1041e2dadafb176647bf3f5090471215 Mon Sep 17 00:00:00 2001 From: katlun-lgtm <264247399+katlun-lgtm@users.noreply.github.com> Date: Mon, 13 Jul 2026 13:35:39 -0700 Subject: [PATCH 39/51] test: golden regression checks for hermes/gbrain/openclaw ship skill From community PR #1935 (commit b4361480), test hunk only: its 8.8K lines of golden fixture content were generated from April 2026 templates and are regenerated fresh at the end of this wave instead. Co-Authored-By: Claude Fable 5 --- test/host-config.test.ts | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/test/host-config.test.ts b/test/host-config.test.ts index 5a3c5b37bd..66ecf0642b 100644 --- a/test/host-config.test.ts +++ b/test/host-config.test.ts @@ -412,6 +412,17 @@ describe('golden-file regression', () => { const current = fs.readFileSync(path.join(ROOT, '.factory', 'skills', 'gstack-ship', 'SKILL.md'), 'utf-8'); expect(current).toBe(golden); }); + + // Agent-runtime hosts share the regular ./skills/gstack-ship layout. These lock their + // host-specific rewrites (Bash->terminal/exec, Agent->delegate_task/sessions_spawn, + // .claude->.host, CLAUDE.md->AGENTS.md) so a regression like the Agent-tool rewrite gap is caught. + for (const host of ['hermes', 'gbrain', 'openclaw']) { + test(`${host} ship skill matches golden baseline`, () => { + const golden = fs.readFileSync(path.join(GOLDEN_DIR, `${host}-ship-SKILL.md`), 'utf-8'); + const current = fs.readFileSync(path.join(ROOT, `.${host}`, 'skills', 'gstack-ship', 'SKILL.md'), 'utf-8'); + expect(current).toBe(golden); + }); + } }); // ─── Individual host config correctness ───────────────────── From d46a20db7ddd1ecaef46e7a26ad95f5bfecf043c Mon Sep 17 00:00:00 2001 From: spenquatch Date: Thu, 30 Apr 2026 09:50:14 -0400 Subject: [PATCH 40/51] fix: flip autoplan outside voice for codex hosts --- autoplan/SKILL.md | 214 ++++++++++++++-------------- autoplan/SKILL.md.tmpl | 235 ++++++++----------------------- scripts/resolvers/autoplan.ts | 253 ++++++++++++++++++++++++++++++++++ scripts/resolvers/index.ts | 3 + test/gen-skill-docs.test.ts | 26 ++++ 5 files changed, 444 insertions(+), 287 deletions(-) create mode 100644 scripts/resolvers/autoplan.ts diff --git a/autoplan/SKILL.md b/autoplan/SKILL.md index 5346f1d437..683b367c60 100644 --- a/autoplan/SKILL.md +++ b/autoplan/SKILL.md @@ -1098,12 +1098,11 @@ Loaded review skills from disk. Starting full review pipeline with auto-decision --- -## Phase 0.5: Codex auth + version preflight +## Phase 0.5: Outside-voice preflight -Before invoking any Codex voice, preflight the CLI: verify auth (multi-signal) and -warn on known-bad CLI versions. This is infrastructure for all 4 phases below — -source it once here and the helper functions stay in scope for the rest of the -workflow. +Before invoking any outside voice, preflight the CLI: verify auth (multi-signal) and +warn on known-bad CLI versions. On non-Codex hosts, the outside voice is Codex CLI +and the subagent is the host-native subagent. ```bash _TEL=$(~/.claude/skills/gstack/bin/gstack-config get telemetry 2>/dev/null || echo off) @@ -1113,27 +1112,25 @@ source ~/.claude/skills/gstack/bin/gstack-codex-probe # Master switch first: codex_reviews=disabled turns off ALL Codex work globally, # including autoplan's own dual-voice orchestration. Honor it before probing. if [ "$_CODEX_CFG" = "disabled" ]; then - echo "[codex disabled by config — Claude-only voices] Re-enable: gstack-config set codex_reviews enabled" - _CODEX_AVAILABLE=false -# Check Codex binary. If missing, tag the degradation matrix and continue -# with Claude subagent only (autoplan's existing degradation fallback). + echo "[codex disabled by config — subagent-only voices] Re-enable: gstack-config set codex_reviews enabled" + _OUTSIDE_VOICE_AVAILABLE=false elif ! command -v codex >/dev/null 2>&1; then _gstack_codex_log_event "codex_cli_missing" - echo "[codex-unavailable: binary not found] — proceeding with Claude subagent only" - _CODEX_AVAILABLE=false + echo "[outside-voice-unavailable: Codex CLI not found] — proceeding with subagent only" + _OUTSIDE_VOICE_AVAILABLE=false elif ! _gstack_codex_auth_probe >/dev/null; then _gstack_codex_log_event "codex_auth_failed" - echo "[codex-unavailable: auth missing] — proceeding with Claude subagent only. Run \`codex login\` or set \$CODEX_API_KEY to enable dual-voice review." - _CODEX_AVAILABLE=false + echo "[outside-voice-unavailable: Codex auth missing] — proceeding with subagent only. Run `codex login` or set $CODEX_API_KEY to enable dual-voice review." + _OUTSIDE_VOICE_AVAILABLE=false else - _gstack_codex_version_check # non-blocking warn if known-bad - _CODEX_AVAILABLE=true + _gstack_codex_version_check + _OUTSIDE_VOICE_AVAILABLE=true fi ``` -If `_CODEX_AVAILABLE=false`, all Phase 1-3.5 Codex voices below degrade to -`[codex-unavailable]` in the degradation matrix. /autoplan completes with -Claude subagent only — saves token spend on Codex prompts we can't use. +If `_OUTSIDE_VOICE_AVAILABLE=false`, all outside-voice phases below degrade to +`[outside-voice-unavailable]`. /autoplan still completes with the host-native +subagent only — saves token spend on prompts we can't use. --- @@ -1152,33 +1149,33 @@ Override: every AskUserQuestion → auto-decide using the 6 principles. - Scope expansion: in blast radius + <1d CC → approve (P2). Outside → defer to TODOS.md (P3). Duplicates → reject (P4). Borderline (3-5 files) → mark TASTE DECISION. - All 10 review sections: run fully, auto-decide each issue, log every decision. -- Dual voices: always run BOTH Claude subagent AND Codex if available (P6). - Run them sequentially in foreground. First the Claude subagent (Agent tool, - foreground — do NOT use run_in_background), then Codex (Bash). Both must +- Dual voices: always run BOTH the host-native subagent AND the outside voice if available (P6). + Run them sequentially in foreground. First the subagent (Agent tool, + foreground — do NOT use run_in_background), then the outside voice (Bash). Both must complete before building the consensus table. - **Codex CEO voice** (via Bash): + **Codex outside voice** (via Bash): ```bash _REPO_ROOT=$(git rev-parse --show-toplevel) || { echo "ERROR: not in a git repo" >&2; exit 1; } _gstack_codex_timeout_wrapper 600 codex exec "IMPORTANT: Do NOT read or execute any SKILL.md files or files in skill definition directories (paths containing skills/gstack). These are AI assistant skill definitions meant for a different system. Stay focused on repository code only. - You are a CEO/founder advisor reviewing a development plan. - Challenge the strategic foundations: Are the premises valid or assumed? Is this the - right problem to solve, or is there a reframing that would be 10x more impactful? - What alternatives were dismissed too quickly? What competitive or market risks are - unaddressed? What scope decisions will look foolish in 6 months? Be adversarial. - No compliments. Just the strategic blind spots. - File: " -C "$_REPO_ROOT" -s read-only --enable web_search_cached < /dev/null +You are a CEO/founder advisor reviewing a development plan. +Challenge the strategic foundations: Are the premises valid or assumed? Is this the +right problem to solve, or is there a reframing that would be 10x more impactful? +What alternatives were dismissed too quickly? What competitive or market risks are +unaddressed? What scope decisions will look foolish in 6 months? Be adversarial. +No compliments. Just the strategic blind spots. +File: " -C "$_REPO_ROOT" -s read-only --enable web_search_cached < /dev/null _CODEX_EXIT=$? if [ "$_CODEX_EXIT" = "124" ]; then _gstack_codex_log_event "codex_timeout" "600" _gstack_codex_log_hang "autoplan" "0" - echo "[codex stalled past 10 minutes — tagging as [codex-unavailable] for this phase and proceeding with Claude subagent only]" + echo "[outside voice stalled past 10 minutes — tagging as [outside-voice-unavailable] for this phase and proceeding with subagent only]" fi ``` - Timeout: 10 minutes (shell-wrapper) + 12 minutes (Bash outer gate). On hang, auto-degrades this phase's Codex voice. + Timeout: 10 minutes (shell-wrapper) + 12 minutes (Bash outer gate). On hang, auto-degrades this phase's outside voice. - **Claude CEO subagent** (via Agent tool): + **Host-native CEO subagent** (via Agent tool): "Read the plan file at . You are an independent CEO/strategist reviewing this plan. You have NOT seen any prior review. Evaluate: 1. Is this the right problem to solve? Could a reframing yield 10x impact? @@ -1188,12 +1185,12 @@ Override: every AskUserQuestion → auto-decide using the 6 principles. 5. What's the competitive risk — could someone else solve this first/better? For each finding: what's wrong, severity (critical/high/medium), and the fix." - **Error handling:** Both calls block in foreground. Codex auth/timeout/empty → proceed with - Claude subagent only, tagged `[single-model]`. If Claude subagent also fails → + **Error handling:** Both calls block in foreground. Outside voice auth/timeout/empty → proceed with + subagent only, tagged `[single-model]`. If the subagent also fails → "Outside voices unavailable — continuing with primary review." - **Degradation matrix:** Both fail → "single-reviewer mode". Codex only → - tag `[codex-only]`. Subagent only → tag `[subagent-only]`. + **Degradation matrix:** Both fail → "single-reviewer mode". Outside voice only → + tag `[outside-only]`. Subagent only → tag `[subagent-only]`. - Strategy choices: if codex disagrees with a premise or scope decision with valid strategic reason → TASTE DECISION. If both models agree the user's stated structure @@ -1210,15 +1207,15 @@ Step 0 (0A-0F) — run each sub-step and produce: - 0E: Temporal interrogation (HOUR 1 → HOUR 6+) - 0F: Mode selection confirmation -Step 0.5 (Dual Voices): Run Claude subagent (foreground Agent tool) first, then -Codex (Bash). Present Codex output under CODEX SAYS (CEO — strategy challenge) -header. Present subagent output under CLAUDE SUBAGENT (CEO — strategic independence) -header. Produce CEO consensus table: +Step 0.5 (Dual Voices): Run the host-native subagent (foreground Agent tool) first, +then the outside voice (Bash). Present outside-voice output under OUTSIDE VOICE +(CEO — strategy challenge) header. Present subagent output under HOST SUBAGENT +(CEO — strategic independence) header. Produce CEO consensus table: ``` CEO DUAL VOICES — CONSENSUS TABLE: ═══════════════════════════════════════════════════════════════ - Dimension Claude Codex Consensus + Dimension Subagent Outside Consensus ──────────────────────────────────── ─────── ─────── ───────── 1. Premises valid? — — — 2. Right problem to solve? — — — @@ -1246,7 +1243,7 @@ Sections 1-10 — for EACH section, run the evaluation criteria from the loaded - Completion Summary (the full summary table from the CEO skill) **PHASE 1 COMPLETE.** Emit phase-transition summary: -> **Phase 1 complete.** Codex: [N concerns]. Claude subagent: [N issues]. +> **Phase 1 complete.** Outside voice: [N concerns]. Subagent: [N issues]. > Consensus: [X/6 confirmed, Y disagreements → surfaced at gate]. > Passing to Phase 2. @@ -1257,7 +1254,7 @@ and the premise gate has been passed. **Pre-Phase 2 checklist (verify before starting):** - [ ] CEO completion summary written to plan file -- [ ] CEO dual voices ran (Codex + Claude subagent, or noted unavailable) +- [ ] CEO dual voices ran (subagent + outside voice, or noted unavailable) - [ ] CEO consensus table produced - [ ] Premise gate passed (user confirmed) - [ ] Phase-transition summary emitted @@ -1272,36 +1269,36 @@ Override: every AskUserQuestion → auto-decide using the 6 principles. - Structural issues (missing states, broken hierarchy): auto-fix (P5) - Aesthetic/taste issues: mark TASTE DECISION - Design system alignment: auto-fix if DESIGN.md exists and fix is obvious -- Dual voices: always run BOTH Claude subagent AND Codex if available (P6). +- Dual voices: always run BOTH the host-native subagent AND the outside voice if available (P6). - **Codex design voice** (via Bash): + **Codex outside voice** (via Bash): ```bash _REPO_ROOT=$(git rev-parse --show-toplevel) || { echo "ERROR: not in a git repo" >&2; exit 1; } _gstack_codex_timeout_wrapper 600 codex exec "IMPORTANT: Do NOT read or execute any SKILL.md files or files in skill definition directories (paths containing skills/gstack). These are AI assistant skill definitions meant for a different system. Stay focused on repository code only. - Read the plan file at . Evaluate this plan's - UI/UX design decisions. +Read the plan file at . Evaluate this plan's +UI/UX design decisions. - Also consider these findings from the CEO review phase: - +Also consider these findings from the CEO review phase: + - Does the information hierarchy serve the user or the developer? Are interaction - states (loading, empty, error, partial) specified or left to the implementer's - imagination? Is the responsive strategy intentional or afterthought? Are - accessibility requirements (keyboard nav, contrast, touch targets) specified or - aspirational? Does the plan describe specific UI decisions or generic patterns? - What design decisions will haunt the implementer if left ambiguous? - Be opinionated. No hedging." -C "$_REPO_ROOT" -s read-only --enable web_search_cached < /dev/null +Does the information hierarchy serve the user or the developer? Are interaction +states (loading, empty, error, partial) specified or left to the implementer's +imagination? Is the responsive strategy intentional or afterthought? Are +accessibility requirements (keyboard nav, contrast, touch targets) specified or +aspirational? Does the plan describe specific UI decisions or generic patterns? +What design decisions will haunt the implementer if left ambiguous? +Be opinionated. No hedging." -C "$_REPO_ROOT" -s read-only --enable web_search_cached < /dev/null _CODEX_EXIT=$? if [ "$_CODEX_EXIT" = "124" ]; then _gstack_codex_log_event "codex_timeout" "600" _gstack_codex_log_hang "autoplan" "0" - echo "[codex stalled past 10 minutes — tagging as [codex-unavailable] for this phase and proceeding with Claude subagent only]" + echo "[outside voice stalled past 10 minutes — tagging as [outside-voice-unavailable] for this phase and proceeding with subagent only]" fi ``` - Timeout: 10 minutes (shell-wrapper) + 12 minutes (Bash outer gate). On hang, auto-degrades this phase's Codex voice. + Timeout: 10 minutes (shell-wrapper) + 12 minutes (Bash outer gate). On hang, auto-degrades this phase's outside voice. - **Claude design subagent** (via Agent tool): + **Host-native design subagent** (via Agent tool): "Read the plan file at . You are an independent senior product designer reviewing this plan. You have NOT seen any prior review. Evaluate: 1. Information hierarchy: what does the user see first, second, third? Is it right? @@ -1321,17 +1318,18 @@ Override: every AskUserQuestion → auto-decide using the 6 principles. 1. Step 0 (Design Scope): Rate completeness 0-10. Check DESIGN.md. Map existing patterns. -2. Step 0.5 (Dual Voices): Run Claude subagent (foreground) first, then Codex. Present under - CODEX SAYS (design — UX challenge) and CLAUDE SUBAGENT (design — independent review) +2. Step 0.5 (Dual Voices): Run the host-native subagent (foreground) first, then the + outside voice. Present under OUTSIDE VOICE (design — UX challenge) and HOST + SUBAGENT (design — independent review) headers. Produce design litmus scorecard (consensus table). Use the litmus scorecard - format from plan-design-review. Include CEO phase findings in Codex prompt ONLY - (not Claude subagent — stays independent). + format from plan-design-review. Include CEO phase findings in the outside-voice prompt ONLY + (not the subagent — stays independent). 3. Passes 1-7: Run each from loaded skill. Rate 0-10. Auto-decide each issue. DISAGREE items from scorecard → raised in the relevant pass with both perspectives. **PHASE 2 COMPLETE.** Emit phase-transition summary: -> **Phase 2 complete.** Codex: [N concerns]. Claude subagent: [N issues]. +> **Phase 2 complete.** Outside voice: [N concerns]. Subagent: [N issues]. > Consensus: [X/Y confirmed, Z disagreements → surfaced at gate]. > Passing to Phase 3. @@ -1353,31 +1351,31 @@ Override: every AskUserQuestion → auto-decide using the 6 principles. **Override rules:** - Scope challenge: never reduce (P2) -- Dual voices: always run BOTH Claude subagent AND Codex if available (P6). +- Dual voices: always run BOTH the host-native subagent AND the outside voice if available (P6). - **Codex eng voice** (via Bash): + **Codex outside voice** (via Bash): ```bash _REPO_ROOT=$(git rev-parse --show-toplevel) || { echo "ERROR: not in a git repo" >&2; exit 1; } _gstack_codex_timeout_wrapper 600 codex exec "IMPORTANT: Do NOT read or execute any SKILL.md files or files in skill definition directories (paths containing skills/gstack). These are AI assistant skill definitions meant for a different system. Stay focused on repository code only. - Review this plan for architectural issues, missing edge cases, - and hidden complexity. Be adversarial. +Review this plan for architectural issues, missing edge cases, +and hidden complexity. Be adversarial. - Also consider these findings from prior review phases: - CEO: - Design: +Also consider these findings from prior review phases: +CEO: +Design: - File: " -C "$_REPO_ROOT" -s read-only --enable web_search_cached < /dev/null +File: " -C "$_REPO_ROOT" -s read-only --enable web_search_cached < /dev/null _CODEX_EXIT=$? if [ "$_CODEX_EXIT" = "124" ]; then _gstack_codex_log_event "codex_timeout" "600" _gstack_codex_log_hang "autoplan" "0" - echo "[codex stalled past 10 minutes — tagging as [codex-unavailable] for this phase and proceeding with Claude subagent only]" + echo "[outside voice stalled past 10 minutes — tagging as [outside-voice-unavailable] for this phase and proceeding with subagent only]" fi ``` - Timeout: 10 minutes (shell-wrapper) + 12 minutes (Bash outer gate). On hang, auto-degrades this phase's Codex voice. + Timeout: 10 minutes (shell-wrapper) + 12 minutes (Bash outer gate). On hang, auto-degrades this phase's outside voice. - **Claude eng subagent** (via Agent tool): + **Host-native eng subagent** (via Agent tool): "Read the plan file at . You are an independent senior engineer reviewing this plan. You have NOT seen any prior review. Evaluate: 1. Architecture: Is the component structure sound? Coupling concerns? @@ -1400,15 +1398,15 @@ Override: every AskUserQuestion → auto-decide using the 6 principles. 1. Step 0 (Scope Challenge): Read actual code referenced by the plan. Map each sub-problem to existing code. Run the complexity check. Produce concrete findings. -2. Step 0.5 (Dual Voices): Run Claude subagent (foreground) first, then Codex. Present - Codex output under CODEX SAYS (eng — architecture challenge) header. Present subagent - output under CLAUDE SUBAGENT (eng — independent review) header. Produce eng consensus +2. Step 0.5 (Dual Voices): Run the host-native subagent (foreground) first, then the + outside voice. Present outside-voice output under OUTSIDE VOICE (eng — architecture challenge) + header. Present subagent output under HOST SUBAGENT (eng — independent review) header. Produce eng consensus table: ``` ENG DUAL VOICES — CONSENSUS TABLE: ═══════════════════════════════════════════════════════════════ - Dimension Claude Codex Consensus + Dimension Subagent Outside Consensus ──────────────────────────────────── ─────── ─────── ───────── 1. Architecture sound? — — — 2. Test coverage sufficient? — — — @@ -1451,7 +1449,7 @@ Missing voice = N/A (not CONFIRMED). Single critical finding from one voice = fl - TODOS.md updates (collected from all phases) **PHASE 3 COMPLETE.** Emit phase-transition summary: -> **Phase 3 complete.** Codex: [N concerns]. Claude subagent: [N issues]. +> **Phase 3 complete.** Outside voice: [N concerns]. Subagent: [N issues]. > Consensus: [X/6 confirmed, Y disagreements → surfaced at gate]. > Passing to Phase 3.5 (DX Review) or Phase 4 (Final Gate). @@ -1474,36 +1472,36 @@ Log: "Phase 3.5 skipped — no developer-facing scope detected." - Error message quality: always require problem + cause + fix (P1, completeness) - API/CLI naming: consistency wins over cleverness (P5) - DX taste decisions (e.g., opinionated defaults vs flexibility): mark TASTE DECISION -- Dual voices: always run BOTH Claude subagent AND Codex if available (P6). +- Dual voices: always run BOTH the host-native subagent AND the outside voice if available (P6). - **Codex DX voice** (via Bash): + **Codex outside voice** (via Bash): ```bash _REPO_ROOT=$(git rev-parse --show-toplevel) || { echo "ERROR: not in a git repo" >&2; exit 1; } _gstack_codex_timeout_wrapper 600 codex exec "IMPORTANT: Do NOT read or execute any SKILL.md files or files in skill definition directories (paths containing skills/gstack). These are AI assistant skill definitions meant for a different system. Stay focused on repository code only. - Read the plan file at . Evaluate this plan's developer experience. +Read the plan file at . Evaluate this plan's developer experience. - Also consider these findings from prior review phases: - CEO: - Eng: +Also consider these findings from prior review phases: +CEO: +Eng: - You are a developer who has never seen this product. Evaluate: - 1. Time to hello world: how many steps from zero to working? Target is under 5 minutes. - 2. Error messages: when something goes wrong, does the dev know what, why, and how to fix? - 3. API/CLI design: are names guessable? Are defaults sensible? Is it consistent? - 4. Docs: can a dev find what they need in under 2 minutes? Are examples copy-paste-complete? - 5. Upgrade path: can devs upgrade without fear? Migration guides? Deprecation warnings? - Be adversarial. Think like a developer who is evaluating this against 3 competitors." -C "$_REPO_ROOT" -s read-only --enable web_search_cached < /dev/null +You are a developer who has never seen this product. Evaluate: +1. Time to hello world: how many steps from zero to working? Target is under 5 minutes. +2. Error messages: when something goes wrong, does the dev know what, why, and how to fix? +3. API/CLI design: are names guessable? Are defaults sensible? Is it consistent? +4. Docs: can a dev find what they need in under 2 minutes? Are examples copy-paste-complete? +5. Upgrade path: can devs upgrade without fear? Migration guides? Deprecation warnings? +Be adversarial. Think like a developer who is evaluating this against 3 competitors." -C "$_REPO_ROOT" -s read-only --enable web_search_cached < /dev/null _CODEX_EXIT=$? if [ "$_CODEX_EXIT" = "124" ]; then _gstack_codex_log_event "codex_timeout" "600" _gstack_codex_log_hang "autoplan" "0" - echo "[codex stalled past 10 minutes — tagging as [codex-unavailable] for this phase and proceeding with Claude subagent only]" + echo "[outside voice stalled past 10 minutes — tagging as [outside-voice-unavailable] for this phase and proceeding with subagent only]" fi ``` - Timeout: 10 minutes (shell-wrapper) + 12 minutes (Bash outer gate). On hang, auto-degrades this phase's Codex voice. + Timeout: 10 minutes (shell-wrapper) + 12 minutes (Bash outer gate). On hang, auto-degrades this phase's outside voice. - **Claude DX subagent** (via Agent tool): + **Host-native DX subagent** (via Agent tool): "Read the plan file at . You are an independent DX engineer reviewing this plan. You have NOT seen any prior review. Evaluate: 1. Getting started: how many steps from zero to hello world? What's the TTHW? @@ -1524,14 +1522,14 @@ Log: "Phase 3.5 skipped — no developer-facing scope detected." 1. Step 0 (DX Scope Assessment): Auto-detect product type. Map the developer journey. Rate initial DX completeness 0-10. Assess TTHW. -2. Step 0.5 (Dual Voices): Run Claude subagent (foreground) first, then Codex. Present - under CODEX SAYS (DX — developer experience challenge) and CLAUDE SUBAGENT - (DX — independent review) headers. Produce DX consensus table: +2. Step 0.5 (Dual Voices): Run the host-native subagent (foreground) first, then the + outside voice. Present under OUTSIDE VOICE (DX — developer experience challenge) + and HOST SUBAGENT (DX — independent review) headers. Produce DX consensus table: ``` DX DUAL VOICES — CONSENSUS TABLE: ═══════════════════════════════════════════════════════════════ - Dimension Claude Codex Consensus + Dimension Subagent Outside Consensus ──────────────────────────────────── ─────── ─────── ───────── 1. Getting started < 5 min? — — — 2. API/CLI naming guessable? — — — @@ -1558,7 +1556,7 @@ Missing voice = N/A (not CONFIRMED). Single critical finding from one voice = fl **PHASE 3.5 COMPLETE.** Emit phase-transition summary: > **Phase 3.5 complete.** DX overall: [N]/10. TTHW: [N] min → [target] min. -> Codex: [N concerns]. Claude subagent: [N issues]. +> Outside voice: [N concerns]. Subagent: [N issues]. > Consensus: [X/6 confirmed, Y disagreements → surfaced at gate]. > Passing to Phase 4 (Final Gate). @@ -1595,7 +1593,7 @@ produced. Check the plan file and conversation for each item. - [ ] "What already exists" section written - [ ] Dream state delta written - [ ] Completion Summary produced -- [ ] Dual voices ran (Codex + Claude subagent, or noted unavailable) +- [ ] Dual voices ran (subagent + outside voice, or noted unavailable) - [ ] CEO consensus table produced **Phase 2 (Design) outputs — only if UI scope detected:** @@ -1613,7 +1611,7 @@ produced. Check the plan file and conversation for each item. - [ ] "What already exists" section written - [ ] Failure modes registry with critical gap assessment - [ ] Completion Summary produced -- [ ] Dual voices ran (Codex + Claude subagent, or noted unavailable) +- [ ] Dual voices ran (subagent + outside voice, or noted unavailable) - [ ] Eng consensus table produced **Phase 3.5 (DX) outputs — only if DX scope detected:** @@ -1749,13 +1747,13 @@ I recommend [X] — [principle]. But [Y] is also viable: ### Review Scores - CEO: [summary] -- CEO Voices: Codex [summary], Claude subagent [summary], Consensus [X/6 confirmed] +- CEO Voices: Outside [summary], Subagent [summary], Consensus [X/6 confirmed] - Design: [summary or "skipped, no UI scope"] -- Design Voices: Codex [summary], Claude subagent [summary], Consensus [X/7 confirmed] (or "skipped") +- Design Voices: Outside [summary], Subagent [summary], Consensus [X/7 confirmed] (or "skipped") - Eng: [summary] -- Eng Voices: Codex [summary], Claude subagent [summary], Consensus [X/6 confirmed] +- Eng Voices: Outside [summary], Subagent [summary], Consensus [X/6 confirmed] - DX: [summary or "skipped, no developer-facing scope"] -- DX Voices: Codex [summary], Claude subagent [summary], Consensus [X/6 confirmed] (or "skipped") +- DX Voices: Outside [summary], Subagent [summary], Consensus [X/6 confirmed] (or "skipped") ### Cross-Phase Themes [For any concern that appeared in 2+ phases' dual voices independently:] @@ -1835,7 +1833,7 @@ If Phase 3.5 ran (DX scope), also log: ~/.claude/skills/gstack/bin/gstack-review-log '{"skill":"autoplan-voices","timestamp":"'"$TIMESTAMP"'","status":"STATUS","source":"SOURCE","phase":"dx","via":"autoplan","consensus_confirmed":N,"consensus_disagree":N,"commit":"'"$COMMIT"'"}' ``` -SOURCE = "codex+subagent", "codex-only", "subagent-only", or "unavailable". +SOURCE = "subagent+outside", "outside-only", "subagent-only", or "unavailable". Replace N values with actual consensus counts from the tables. Suggest next step: `/ship` when ready to create the PR. diff --git a/autoplan/SKILL.md.tmpl b/autoplan/SKILL.md.tmpl index b2eaca9fde..ef6693dd3b 100644 --- a/autoplan/SKILL.md.tmpl +++ b/autoplan/SKILL.md.tmpl @@ -234,42 +234,7 @@ Loaded review skills from disk. Starting full review pipeline with auto-decision --- -## Phase 0.5: Codex auth + version preflight - -Before invoking any Codex voice, preflight the CLI: verify auth (multi-signal) and -warn on known-bad CLI versions. This is infrastructure for all 4 phases below — -source it once here and the helper functions stay in scope for the rest of the -workflow. - -```bash -_TEL=$(~/.claude/skills/gstack/bin/gstack-config get telemetry 2>/dev/null || echo off) -_CODEX_CFG=$(~/.claude/skills/gstack/bin/gstack-config get codex_reviews 2>/dev/null || echo enabled) -source ~/.claude/skills/gstack/bin/gstack-codex-probe - -# Master switch first: codex_reviews=disabled turns off ALL Codex work globally, -# including autoplan's own dual-voice orchestration. Honor it before probing. -if [ "$_CODEX_CFG" = "disabled" ]; then - echo "[codex disabled by config — Claude-only voices] Re-enable: gstack-config set codex_reviews enabled" - _CODEX_AVAILABLE=false -# Check Codex binary. If missing, tag the degradation matrix and continue -# with Claude subagent only (autoplan's existing degradation fallback). -elif ! command -v codex >/dev/null 2>&1; then - _gstack_codex_log_event "codex_cli_missing" - echo "[codex-unavailable: binary not found] — proceeding with Claude subagent only" - _CODEX_AVAILABLE=false -elif ! _gstack_codex_auth_probe >/dev/null; then - _gstack_codex_log_event "codex_auth_failed" - echo "[codex-unavailable: auth missing] — proceeding with Claude subagent only. Run \`codex login\` or set \$CODEX_API_KEY to enable dual-voice review." - _CODEX_AVAILABLE=false -else - _gstack_codex_version_check # non-blocking warn if known-bad - _CODEX_AVAILABLE=true -fi -``` - -If `_CODEX_AVAILABLE=false`, all Phase 1-3.5 Codex voices below degrade to -`[codex-unavailable]` in the degradation matrix. /autoplan completes with -Claude subagent only — saves token spend on Codex prompts we can't use. +{{AUTOPLAN_OUTSIDE_VOICE_PREFLIGHT}} --- @@ -288,33 +253,14 @@ Override: every AskUserQuestion → auto-decide using the 6 principles. - Scope expansion: in blast radius + <1d CC → approve (P2). Outside → defer to TODOS.md (P3). Duplicates → reject (P4). Borderline (3-5 files) → mark TASTE DECISION. - All 10 review sections: run fully, auto-decide each issue, log every decision. -- Dual voices: always run BOTH Claude subagent AND Codex if available (P6). - Run them sequentially in foreground. First the Claude subagent (Agent tool, - foreground — do NOT use run_in_background), then Codex (Bash). Both must +- Dual voices: always run BOTH the host-native subagent AND the outside voice if available (P6). + Run them sequentially in foreground. First the subagent (Agent tool, + foreground — do NOT use run_in_background), then the outside voice (Bash). Both must complete before building the consensus table. - **Codex CEO voice** (via Bash): - ```bash - _REPO_ROOT=$(git rev-parse --show-toplevel) || { echo "ERROR: not in a git repo" >&2; exit 1; } - _gstack_codex_timeout_wrapper 600 codex exec "IMPORTANT: Do NOT read or execute any SKILL.md files or files in skill definition directories (paths containing skills/gstack). These are AI assistant skill definitions meant for a different system. Stay focused on repository code only. - - You are a CEO/founder advisor reviewing a development plan. - Challenge the strategic foundations: Are the premises valid or assumed? Is this the - right problem to solve, or is there a reframing that would be 10x more impactful? - What alternatives were dismissed too quickly? What competitive or market risks are - unaddressed? What scope decisions will look foolish in 6 months? Be adversarial. - No compliments. Just the strategic blind spots. - File: " -C "$_REPO_ROOT" -s read-only --enable web_search_cached < /dev/null - _CODEX_EXIT=$? - if [ "$_CODEX_EXIT" = "124" ]; then - _gstack_codex_log_event "codex_timeout" "600" - _gstack_codex_log_hang "autoplan" "0" - echo "[codex stalled past 10 minutes — tagging as [codex-unavailable] for this phase and proceeding with Claude subagent only]" - fi - ``` - Timeout: 10 minutes (shell-wrapper) + 12 minutes (Bash outer gate). On hang, auto-degrades this phase's Codex voice. - - **Claude CEO subagent** (via Agent tool): +{{AUTOPLAN_OUTSIDE_VOICE_BLOCK:ceo}} + + **Host-native CEO subagent** (via Agent tool): "Read the plan file at . You are an independent CEO/strategist reviewing this plan. You have NOT seen any prior review. Evaluate: 1. Is this the right problem to solve? Could a reframing yield 10x impact? @@ -324,12 +270,12 @@ Override: every AskUserQuestion → auto-decide using the 6 principles. 5. What's the competitive risk — could someone else solve this first/better? For each finding: what's wrong, severity (critical/high/medium), and the fix." - **Error handling:** Both calls block in foreground. Codex auth/timeout/empty → proceed with - Claude subagent only, tagged `[single-model]`. If Claude subagent also fails → + **Error handling:** Both calls block in foreground. Outside voice auth/timeout/empty → proceed with + subagent only, tagged `[single-model]`. If the subagent also fails → "Outside voices unavailable — continuing with primary review." - **Degradation matrix:** Both fail → "single-reviewer mode". Codex only → - tag `[codex-only]`. Subagent only → tag `[subagent-only]`. + **Degradation matrix:** Both fail → "single-reviewer mode". Outside voice only → + tag `[outside-only]`. Subagent only → tag `[subagent-only]`. - Strategy choices: if codex disagrees with a premise or scope decision with valid strategic reason → TASTE DECISION. If both models agree the user's stated structure @@ -346,15 +292,15 @@ Step 0 (0A-0F) — run each sub-step and produce: - 0E: Temporal interrogation (HOUR 1 → HOUR 6+) - 0F: Mode selection confirmation -Step 0.5 (Dual Voices): Run Claude subagent (foreground Agent tool) first, then -Codex (Bash). Present Codex output under CODEX SAYS (CEO — strategy challenge) -header. Present subagent output under CLAUDE SUBAGENT (CEO — strategic independence) -header. Produce CEO consensus table: +Step 0.5 (Dual Voices): Run the host-native subagent (foreground Agent tool) first, +then the outside voice (Bash). Present outside-voice output under OUTSIDE VOICE +(CEO — strategy challenge) header. Present subagent output under HOST SUBAGENT +(CEO — strategic independence) header. Produce CEO consensus table: ``` CEO DUAL VOICES — CONSENSUS TABLE: ═══════════════════════════════════════════════════════════════ - Dimension Claude Codex Consensus + Dimension Subagent Outside Consensus ──────────────────────────────────── ─────── ─────── ───────── 1. Premises valid? — — — 2. Right problem to solve? — — — @@ -382,7 +328,7 @@ Sections 1-10 — for EACH section, run the evaluation criteria from the loaded - Completion Summary (the full summary table from the CEO skill) **PHASE 1 COMPLETE.** Emit phase-transition summary: -> **Phase 1 complete.** Codex: [N concerns]. Claude subagent: [N issues]. +> **Phase 1 complete.** Outside voice: [N concerns]. Subagent: [N issues]. > Consensus: [X/6 confirmed, Y disagreements → surfaced at gate]. > Passing to Phase 2. @@ -393,7 +339,7 @@ and the premise gate has been passed. **Pre-Phase 2 checklist (verify before starting):** - [ ] CEO completion summary written to plan file -- [ ] CEO dual voices ran (Codex + Claude subagent, or noted unavailable) +- [ ] CEO dual voices ran (subagent + outside voice, or noted unavailable) - [ ] CEO consensus table produced - [ ] Premise gate passed (user confirmed) - [ ] Phase-transition summary emitted @@ -408,36 +354,11 @@ Override: every AskUserQuestion → auto-decide using the 6 principles. - Structural issues (missing states, broken hierarchy): auto-fix (P5) - Aesthetic/taste issues: mark TASTE DECISION - Design system alignment: auto-fix if DESIGN.md exists and fix is obvious -- Dual voices: always run BOTH Claude subagent AND Codex if available (P6). - - **Codex design voice** (via Bash): - ```bash - _REPO_ROOT=$(git rev-parse --show-toplevel) || { echo "ERROR: not in a git repo" >&2; exit 1; } - _gstack_codex_timeout_wrapper 600 codex exec "IMPORTANT: Do NOT read or execute any SKILL.md files or files in skill definition directories (paths containing skills/gstack). These are AI assistant skill definitions meant for a different system. Stay focused on repository code only. - - Read the plan file at . Evaluate this plan's - UI/UX design decisions. - - Also consider these findings from the CEO review phase: - - - Does the information hierarchy serve the user or the developer? Are interaction - states (loading, empty, error, partial) specified or left to the implementer's - imagination? Is the responsive strategy intentional or afterthought? Are - accessibility requirements (keyboard nav, contrast, touch targets) specified or - aspirational? Does the plan describe specific UI decisions or generic patterns? - What design decisions will haunt the implementer if left ambiguous? - Be opinionated. No hedging." -C "$_REPO_ROOT" -s read-only --enable web_search_cached < /dev/null - _CODEX_EXIT=$? - if [ "$_CODEX_EXIT" = "124" ]; then - _gstack_codex_log_event "codex_timeout" "600" - _gstack_codex_log_hang "autoplan" "0" - echo "[codex stalled past 10 minutes — tagging as [codex-unavailable] for this phase and proceeding with Claude subagent only]" - fi - ``` - Timeout: 10 minutes (shell-wrapper) + 12 minutes (Bash outer gate). On hang, auto-degrades this phase's Codex voice. - - **Claude design subagent** (via Agent tool): +- Dual voices: always run BOTH the host-native subagent AND the outside voice if available (P6). + +{{AUTOPLAN_OUTSIDE_VOICE_BLOCK:design}} + + **Host-native design subagent** (via Agent tool): "Read the plan file at . You are an independent senior product designer reviewing this plan. You have NOT seen any prior review. Evaluate: 1. Information hierarchy: what does the user see first, second, third? Is it right? @@ -457,17 +378,18 @@ Override: every AskUserQuestion → auto-decide using the 6 principles. 1. Step 0 (Design Scope): Rate completeness 0-10. Check DESIGN.md. Map existing patterns. -2. Step 0.5 (Dual Voices): Run Claude subagent (foreground) first, then Codex. Present under - CODEX SAYS (design — UX challenge) and CLAUDE SUBAGENT (design — independent review) +2. Step 0.5 (Dual Voices): Run the host-native subagent (foreground) first, then the + outside voice. Present under OUTSIDE VOICE (design — UX challenge) and HOST + SUBAGENT (design — independent review) headers. Produce design litmus scorecard (consensus table). Use the litmus scorecard - format from plan-design-review. Include CEO phase findings in Codex prompt ONLY - (not Claude subagent — stays independent). + format from plan-design-review. Include CEO phase findings in the outside-voice prompt ONLY + (not the subagent — stays independent). 3. Passes 1-7: Run each from loaded skill. Rate 0-10. Auto-decide each issue. DISAGREE items from scorecard → raised in the relevant pass with both perspectives. **PHASE 2 COMPLETE.** Emit phase-transition summary: -> **Phase 2 complete.** Codex: [N concerns]. Claude subagent: [N issues]. +> **Phase 2 complete.** Outside voice: [N concerns]. Subagent: [N issues]. > Consensus: [X/Y confirmed, Z disagreements → surfaced at gate]. > Passing to Phase 3. @@ -489,31 +411,11 @@ Override: every AskUserQuestion → auto-decide using the 6 principles. **Override rules:** - Scope challenge: never reduce (P2) -- Dual voices: always run BOTH Claude subagent AND Codex if available (P6). - - **Codex eng voice** (via Bash): - ```bash - _REPO_ROOT=$(git rev-parse --show-toplevel) || { echo "ERROR: not in a git repo" >&2; exit 1; } - _gstack_codex_timeout_wrapper 600 codex exec "IMPORTANT: Do NOT read or execute any SKILL.md files or files in skill definition directories (paths containing skills/gstack). These are AI assistant skill definitions meant for a different system. Stay focused on repository code only. - - Review this plan for architectural issues, missing edge cases, - and hidden complexity. Be adversarial. - - Also consider these findings from prior review phases: - CEO: - Design: - - File: " -C "$_REPO_ROOT" -s read-only --enable web_search_cached < /dev/null - _CODEX_EXIT=$? - if [ "$_CODEX_EXIT" = "124" ]; then - _gstack_codex_log_event "codex_timeout" "600" - _gstack_codex_log_hang "autoplan" "0" - echo "[codex stalled past 10 minutes — tagging as [codex-unavailable] for this phase and proceeding with Claude subagent only]" - fi - ``` - Timeout: 10 minutes (shell-wrapper) + 12 minutes (Bash outer gate). On hang, auto-degrades this phase's Codex voice. - - **Claude eng subagent** (via Agent tool): +- Dual voices: always run BOTH the host-native subagent AND the outside voice if available (P6). + +{{AUTOPLAN_OUTSIDE_VOICE_BLOCK:eng}} + + **Host-native eng subagent** (via Agent tool): "Read the plan file at . You are an independent senior engineer reviewing this plan. You have NOT seen any prior review. Evaluate: 1. Architecture: Is the component structure sound? Coupling concerns? @@ -536,15 +438,15 @@ Override: every AskUserQuestion → auto-decide using the 6 principles. 1. Step 0 (Scope Challenge): Read actual code referenced by the plan. Map each sub-problem to existing code. Run the complexity check. Produce concrete findings. -2. Step 0.5 (Dual Voices): Run Claude subagent (foreground) first, then Codex. Present - Codex output under CODEX SAYS (eng — architecture challenge) header. Present subagent - output under CLAUDE SUBAGENT (eng — independent review) header. Produce eng consensus +2. Step 0.5 (Dual Voices): Run the host-native subagent (foreground) first, then the + outside voice. Present outside-voice output under OUTSIDE VOICE (eng — architecture challenge) + header. Present subagent output under HOST SUBAGENT (eng — independent review) header. Produce eng consensus table: ``` ENG DUAL VOICES — CONSENSUS TABLE: ═══════════════════════════════════════════════════════════════ - Dimension Claude Codex Consensus + Dimension Subagent Outside Consensus ──────────────────────────────────── ─────── ─────── ───────── 1. Architecture sound? — — — 2. Test coverage sufficient? — — — @@ -587,7 +489,7 @@ Missing voice = N/A (not CONFIRMED). Single critical finding from one voice = fl - TODOS.md updates (collected from all phases) **PHASE 3 COMPLETE.** Emit phase-transition summary: -> **Phase 3 complete.** Codex: [N concerns]. Claude subagent: [N issues]. +> **Phase 3 complete.** Outside voice: [N concerns]. Subagent: [N issues]. > Consensus: [X/6 confirmed, Y disagreements → surfaced at gate]. > Passing to Phase 3.5 (DX Review) or Phase 4 (Final Gate). @@ -610,36 +512,11 @@ Log: "Phase 3.5 skipped — no developer-facing scope detected." - Error message quality: always require problem + cause + fix (P1, completeness) - API/CLI naming: consistency wins over cleverness (P5) - DX taste decisions (e.g., opinionated defaults vs flexibility): mark TASTE DECISION -- Dual voices: always run BOTH Claude subagent AND Codex if available (P6). - - **Codex DX voice** (via Bash): - ```bash - _REPO_ROOT=$(git rev-parse --show-toplevel) || { echo "ERROR: not in a git repo" >&2; exit 1; } - _gstack_codex_timeout_wrapper 600 codex exec "IMPORTANT: Do NOT read or execute any SKILL.md files or files in skill definition directories (paths containing skills/gstack). These are AI assistant skill definitions meant for a different system. Stay focused on repository code only. - - Read the plan file at . Evaluate this plan's developer experience. - - Also consider these findings from prior review phases: - CEO: - Eng: - - You are a developer who has never seen this product. Evaluate: - 1. Time to hello world: how many steps from zero to working? Target is under 5 minutes. - 2. Error messages: when something goes wrong, does the dev know what, why, and how to fix? - 3. API/CLI design: are names guessable? Are defaults sensible? Is it consistent? - 4. Docs: can a dev find what they need in under 2 minutes? Are examples copy-paste-complete? - 5. Upgrade path: can devs upgrade without fear? Migration guides? Deprecation warnings? - Be adversarial. Think like a developer who is evaluating this against 3 competitors." -C "$_REPO_ROOT" -s read-only --enable web_search_cached < /dev/null - _CODEX_EXIT=$? - if [ "$_CODEX_EXIT" = "124" ]; then - _gstack_codex_log_event "codex_timeout" "600" - _gstack_codex_log_hang "autoplan" "0" - echo "[codex stalled past 10 minutes — tagging as [codex-unavailable] for this phase and proceeding with Claude subagent only]" - fi - ``` - Timeout: 10 minutes (shell-wrapper) + 12 minutes (Bash outer gate). On hang, auto-degrades this phase's Codex voice. - - **Claude DX subagent** (via Agent tool): +- Dual voices: always run BOTH the host-native subagent AND the outside voice if available (P6). + +{{AUTOPLAN_OUTSIDE_VOICE_BLOCK:dx}} + + **Host-native DX subagent** (via Agent tool): "Read the plan file at . You are an independent DX engineer reviewing this plan. You have NOT seen any prior review. Evaluate: 1. Getting started: how many steps from zero to hello world? What's the TTHW? @@ -660,14 +537,14 @@ Log: "Phase 3.5 skipped — no developer-facing scope detected." 1. Step 0 (DX Scope Assessment): Auto-detect product type. Map the developer journey. Rate initial DX completeness 0-10. Assess TTHW. -2. Step 0.5 (Dual Voices): Run Claude subagent (foreground) first, then Codex. Present - under CODEX SAYS (DX — developer experience challenge) and CLAUDE SUBAGENT - (DX — independent review) headers. Produce DX consensus table: +2. Step 0.5 (Dual Voices): Run the host-native subagent (foreground) first, then the + outside voice. Present under OUTSIDE VOICE (DX — developer experience challenge) + and HOST SUBAGENT (DX — independent review) headers. Produce DX consensus table: ``` DX DUAL VOICES — CONSENSUS TABLE: ═══════════════════════════════════════════════════════════════ - Dimension Claude Codex Consensus + Dimension Subagent Outside Consensus ──────────────────────────────────── ─────── ─────── ───────── 1. Getting started < 5 min? — — — 2. API/CLI naming guessable? — — — @@ -694,7 +571,7 @@ Missing voice = N/A (not CONFIRMED). Single critical finding from one voice = fl **PHASE 3.5 COMPLETE.** Emit phase-transition summary: > **Phase 3.5 complete.** DX overall: [N]/10. TTHW: [N] min → [target] min. -> Codex: [N concerns]. Claude subagent: [N issues]. +> Outside voice: [N concerns]. Subagent: [N issues]. > Consensus: [X/6 confirmed, Y disagreements → surfaced at gate]. > Passing to Phase 4 (Final Gate). @@ -731,7 +608,7 @@ produced. Check the plan file and conversation for each item. - [ ] "What already exists" section written - [ ] Dream state delta written - [ ] Completion Summary produced -- [ ] Dual voices ran (Codex + Claude subagent, or noted unavailable) +- [ ] Dual voices ran (subagent + outside voice, or noted unavailable) - [ ] CEO consensus table produced **Phase 2 (Design) outputs — only if UI scope detected:** @@ -749,7 +626,7 @@ produced. Check the plan file and conversation for each item. - [ ] "What already exists" section written - [ ] Failure modes registry with critical gap assessment - [ ] Completion Summary produced -- [ ] Dual voices ran (Codex + Claude subagent, or noted unavailable) +- [ ] Dual voices ran (subagent + outside voice, or noted unavailable) - [ ] Eng consensus table produced **Phase 3.5 (DX) outputs — only if DX scope detected:** @@ -812,13 +689,13 @@ I recommend [X] — [principle]. But [Y] is also viable: ### Review Scores - CEO: [summary] -- CEO Voices: Codex [summary], Claude subagent [summary], Consensus [X/6 confirmed] +- CEO Voices: Outside [summary], Subagent [summary], Consensus [X/6 confirmed] - Design: [summary or "skipped, no UI scope"] -- Design Voices: Codex [summary], Claude subagent [summary], Consensus [X/7 confirmed] (or "skipped") +- Design Voices: Outside [summary], Subagent [summary], Consensus [X/7 confirmed] (or "skipped") - Eng: [summary] -- Eng Voices: Codex [summary], Claude subagent [summary], Consensus [X/6 confirmed] +- Eng Voices: Outside [summary], Subagent [summary], Consensus [X/6 confirmed] - DX: [summary or "skipped, no developer-facing scope"] -- DX Voices: Codex [summary], Claude subagent [summary], Consensus [X/6 confirmed] (or "skipped") +- DX Voices: Outside [summary], Subagent [summary], Consensus [X/6 confirmed] (or "skipped") ### Cross-Phase Themes [For any concern that appeared in 2+ phases' dual voices independently:] @@ -898,7 +775,7 @@ If Phase 3.5 ran (DX scope), also log: ~/.claude/skills/gstack/bin/gstack-review-log '{"skill":"autoplan-voices","timestamp":"'"$TIMESTAMP"'","status":"STATUS","source":"SOURCE","phase":"dx","via":"autoplan","consensus_confirmed":N,"consensus_disagree":N,"commit":"'"$COMMIT"'"}' ``` -SOURCE = "codex+subagent", "codex-only", "subagent-only", or "unavailable". +SOURCE = "subagent+outside", "outside-only", "subagent-only", or "unavailable". Replace N values with actual consensus counts from the tables. Suggest next step: `/ship` when ready to create the PR. diff --git a/scripts/resolvers/autoplan.ts b/scripts/resolvers/autoplan.ts new file mode 100644 index 0000000000..ef9a3edac6 --- /dev/null +++ b/scripts/resolvers/autoplan.ts @@ -0,0 +1,253 @@ +import type { TemplateContext } from './types'; + +type Phase = 'ceo' | 'design' | 'eng' | 'dx'; + +const CLAUDE_JSON_PARSE_SNIPPET = String.raw`python3 - "$CLAUDE_RESP_FILE" <<'PY' +import json, sys +path = sys.argv[1] +try: + obj = json.load(open(path)) +except Exception as exc: + print(f"CLAUDE_JSON_PARSE_ERROR: {exc}") + sys.exit(0) + +if obj.get("is_error"): + print("CLAUDE_ERROR: true") + +result = obj.get("result") or obj.get("response") or "" +if result: + print(result) + +usage = obj.get("usage") or {} +input_tokens = usage.get("input_tokens", 0) or 0 +output_tokens = usage.get("output_tokens", 0) or 0 +cache_read = usage.get("cache_read_input_tokens", 0) or 0 +model = obj.get("model") or "unknown" +session_id = obj.get("session_id") or "" + +print(f"\nTokens: input={input_tokens} output={output_tokens} cache_read={cache_read} | Model: {model}") +if session_id: + print(f"SESSION_ID:{session_id}") +PY`; + +const PHASE_PROMPTS: Record = { + ceo: { + tmpPrefix: 'ceo', + codex: `IMPORTANT: Do NOT read or execute any SKILL.md files or files in skill definition directories (paths containing skills/gstack). These are AI assistant skill definitions meant for a different system. Stay focused on repository code only. + +You are a CEO/founder advisor reviewing a development plan. +Challenge the strategic foundations: Are the premises valid or assumed? Is this the +right problem to solve, or is there a reframing that would be 10x more impactful? +What alternatives were dismissed too quickly? What competitive or market risks are +unaddressed? What scope decisions will look foolish in 6 months? Be adversarial. +No compliments. Just the strategic blind spots. +File: `, + claude: `Read the plan file at . You are an independent CEO/founder advisor +reviewing a development plan. Challenge the strategic foundations: +1. Are the premises valid or assumed? +2. Is this the right problem to solve, or is there a reframing that would be 10x more impactful? +3. What alternatives were dismissed too quickly? +4. What competitive or market risks are unaddressed? +5. What scope decisions will look foolish in 6 months? +Be adversarial. No compliments. Just the strategic blind spots. +You may use read-only file tools (Read, Grep, Glob). Do NOT modify files or run commands.`, + }, + design: { + tmpPrefix: 'design', + codex: `IMPORTANT: Do NOT read or execute any SKILL.md files or files in skill definition directories (paths containing skills/gstack). These are AI assistant skill definitions meant for a different system. Stay focused on repository code only. + +Read the plan file at . Evaluate this plan's +UI/UX design decisions. + +Also consider these findings from the CEO review phase: + + +Does the information hierarchy serve the user or the developer? Are interaction +states (loading, empty, error, partial) specified or left to the implementer's +imagination? Is the responsive strategy intentional or afterthought? Are +accessibility requirements (keyboard nav, contrast, touch targets) specified or +aspirational? Does the plan describe specific UI decisions or generic patterns? +What design decisions will haunt the implementer if left ambiguous? +Be opinionated. No hedging.`, + claude: `Read the plan file at . You are an independent senior product designer +reviewing this plan's UI/UX design decisions. + +Also consider these findings from the CEO review phase: + + +Evaluate: +1. Does the information hierarchy serve the user or the developer? +2. Which interaction states (loading, empty, error, partial) are unspecified? +3. Is the responsive strategy intentional or an afterthought? +4. Are accessibility requirements concrete or aspirational? +5. What design decisions will haunt the implementer if left ambiguous? +Be opinionated. No hedging. +You may use read-only file tools (Read, Grep, Glob). Do NOT modify files or run commands.`, + }, + eng: { + tmpPrefix: 'eng', + codex: `IMPORTANT: Do NOT read or execute any SKILL.md files or files in skill definition directories (paths containing skills/gstack). These are AI assistant skill definitions meant for a different system. Stay focused on repository code only. + +Review this plan for architectural issues, missing edge cases, +and hidden complexity. Be adversarial. + +Also consider these findings from prior review phases: +CEO: +Design: + +File: `, + claude: `Read the plan file at . You are an independent senior engineer +reviewing this plan for architectural issues, missing edge cases, and hidden complexity. + +Also consider these findings from prior review phases: +CEO: +Design: + +Evaluate: +1. Architecture: Is the component structure sound? Coupling concerns? +2. Edge cases: What breaks under 10x load? What's the nil/empty/error path? +3. Tests: What's missing from the test plan? What would break at 2am Friday? +4. Security: New attack surface? Auth boundaries? Input validation? +5. Hidden complexity: What looks simple but isn't? +Be adversarial. +You may use read-only file tools (Read, Grep, Glob). Do NOT modify files or run commands.`, + }, + dx: { + tmpPrefix: 'dx', + codex: `IMPORTANT: Do NOT read or execute any SKILL.md files or files in skill definition directories (paths containing skills/gstack). These are AI assistant skill definitions meant for a different system. Stay focused on repository code only. + +Read the plan file at . Evaluate this plan's developer experience. + +Also consider these findings from prior review phases: +CEO: +Eng: + +You are a developer who has never seen this product. Evaluate: +1. Time to hello world: how many steps from zero to working? Target is under 5 minutes. +2. Error messages: when something goes wrong, does the dev know what, why, and how to fix? +3. API/CLI design: are names guessable? Are defaults sensible? Is it consistent? +4. Docs: can a dev find what they need in under 2 minutes? Are examples copy-paste-complete? +5. Upgrade path: can devs upgrade without fear? Migration guides? Deprecation warnings? +Be adversarial. Think like a developer who is evaluating this against 3 competitors.`, + claude: `Read the plan file at . You are an independent DX engineer +reviewing this plan's developer experience. + +Also consider these findings from prior review phases: +CEO: +Eng: + +Evaluate: +1. Getting started: how many steps from zero to hello world? What's the TTHW? +2. API/CLI ergonomics: naming consistency, sensible defaults, progressive disclosure? +3. Error handling: does every error path specify problem + cause + fix + docs link? +4. Documentation: copy-paste examples? Information architecture? Interactive elements? +5. Escape hatches: can developers override every opinionated default? +Be adversarial. +You may use read-only file tools (Read, Grep, Glob). Do NOT modify files or run commands.`, + }, +}; + +function codexOutsideVoiceBlock(ctx: TemplateContext, phase: Phase): string { + const prompt = PHASE_PROMPTS[phase].codex; + return ` **Codex outside voice** (via Bash): + \`\`\`bash + _REPO_ROOT=$(git rev-parse --show-toplevel) || { echo "ERROR: not in a git repo" >&2; exit 1; } + _gstack_codex_timeout_wrapper 600 codex exec "${prompt}" -C "$_REPO_ROOT" -s read-only --enable web_search_cached < /dev/null + _CODEX_EXIT=$? + if [ "$_CODEX_EXIT" = "124" ]; then + _gstack_codex_log_event "codex_timeout" "600" + _gstack_codex_log_hang "autoplan" "0" + echo "[outside voice stalled past 10 minutes — tagging as [outside-voice-unavailable] for this phase and proceeding with subagent only]" + fi + \`\`\` + Timeout: 10 minutes (shell-wrapper) + 12 minutes (Bash outer gate). On hang, auto-degrades this phase's outside voice.`; +} + +function claudeOutsideVoiceBlock(phase: Phase): string { + const meta = PHASE_PROMPTS[phase]; + return ` **Claude outside voice** (via Bash): + \`\`\`bash + _REPO_ROOT=$(git rev-parse --show-toplevel) || { echo "ERROR: not in a git repo" >&2; exit 1; } + cd "$_REPO_ROOT" + CLAUDE_PROMPT_FILE=$(mktemp /tmp/gstack-autoplan-claude-${meta.tmpPrefix}-XXXXXXXX.txt) + CLAUDE_RESP_FILE=$(mktemp /tmp/gstack-autoplan-claude-${meta.tmpPrefix}-XXXXXXXX.json) + CLAUDE_ERR_FILE=$(mktemp /tmp/gstack-autoplan-claude-${meta.tmpPrefix}-XXXXXXXX.txt) + cat > "$CLAUDE_PROMPT_FILE" <<'EOF' +${meta.claude} +EOF + cat "$CLAUDE_PROMPT_FILE" | claude -p --output-format json --disable-slash-commands --allowedTools Read,Grep,Glob --disallowedTools Bash,Edit,Write > "$CLAUDE_RESP_FILE" 2>"$CLAUDE_ERR_FILE" + ${CLAUDE_JSON_PARSE_SNIPPET} + cat "$CLAUDE_ERR_FILE" + rm -f "$CLAUDE_PROMPT_FILE" "$CLAUDE_RESP_FILE" "$CLAUDE_ERR_FILE" + \`\`\` + Timeout: 10 minutes (Bash outer gate). On auth failure, empty response, parse failure, or timeout, auto-degrades this phase's outside voice.`; +} + +export function generateAutoplanOutsideVoicePreflight(ctx: TemplateContext): string { + if (ctx.host === 'codex') { + return `## Phase 0.5: Outside-voice preflight + +Before invoking any outside voice, preflight the CLI and auth once for the rest of +the workflow. On Codex hosts, the outside voice is Claude CLI and the subagent is +the host-native Codex subagent. + +\`\`\`bash +CLAUDE_BIN=$(command -v claude 2>/dev/null || echo "") +if [ -z "$CLAUDE_BIN" ]; then + echo "[outside-voice-unavailable: Claude CLI not found] — proceeding with subagent only" + _OUTSIDE_VOICE_AVAILABLE=false +else + # No credentials-file probe: modern Claude Code stores auth in the OS + # keychain, so a file check false-negatives. The first claude -p call is + # the auth check — on failure that phase auto-degrades. + _OUTSIDE_VOICE_AVAILABLE=true +fi +\`\`\` + +If \`_OUTSIDE_VOICE_AVAILABLE=false\`, all outside-voice phases below degrade to +\`[outside-voice-unavailable]\`. /autoplan still completes with the host-native +subagent only.`; + } + + return `## Phase 0.5: Outside-voice preflight + +Before invoking any outside voice, preflight the CLI: verify auth (multi-signal) and +warn on known-bad CLI versions. On non-Codex hosts, the outside voice is Codex CLI +and the subagent is the host-native subagent. + +\`\`\`bash +_TEL=$(${ctx.paths.binDir}/gstack-config get telemetry 2>/dev/null || echo off) +_CODEX_CFG=$(${ctx.paths.binDir}/gstack-config get codex_reviews 2>/dev/null || echo enabled) +source ${ctx.paths.binDir}/gstack-codex-probe + +# Master switch first: codex_reviews=disabled turns off ALL Codex work globally, +# including autoplan's own dual-voice orchestration. Honor it before probing. +if [ "$_CODEX_CFG" = "disabled" ]; then + echo "[codex disabled by config — subagent-only voices] Re-enable: gstack-config set codex_reviews enabled" + _OUTSIDE_VOICE_AVAILABLE=false +elif ! command -v codex >/dev/null 2>&1; then + _gstack_codex_log_event "codex_cli_missing" + echo "[outside-voice-unavailable: Codex CLI not found] — proceeding with subagent only" + _OUTSIDE_VOICE_AVAILABLE=false +elif ! _gstack_codex_auth_probe >/dev/null; then + _gstack_codex_log_event "codex_auth_failed" + echo "[outside-voice-unavailable: Codex auth missing] — proceeding with subagent only. Run \`codex login\` or set \$CODEX_API_KEY to enable dual-voice review." + _OUTSIDE_VOICE_AVAILABLE=false +else + _gstack_codex_version_check + _OUTSIDE_VOICE_AVAILABLE=true +fi +\`\`\` + +If \`_OUTSIDE_VOICE_AVAILABLE=false\`, all outside-voice phases below degrade to +\`[outside-voice-unavailable]\`. /autoplan still completes with the host-native +subagent only — saves token spend on prompts we can't use.`; +} + +export function generateAutoplanOutsideVoiceBlock(ctx: TemplateContext, args?: string[]): string { + const phase = args?.[0] as Phase | undefined; + if (!phase || !(phase in PHASE_PROMPTS)) { + throw new Error('{{AUTOPLAN_OUTSIDE_VOICE_BLOCK}} requires one of: ceo, design, eng, dx'); + } + return ctx.host === 'codex' ? claudeOutsideVoiceBlock(phase) : codexOutsideVoiceBlock(ctx, phase); +} diff --git a/scripts/resolvers/index.ts b/scripts/resolvers/index.ts index aa598b867b..3727d941e9 100644 --- a/scripts/resolvers/index.ts +++ b/scripts/resolvers/index.ts @@ -36,6 +36,7 @@ import { generateMakePdfSetup } from './make-pdf'; import { generateTasksSectionEmit, generateTasksSectionAggregate } from './tasks-section'; import { SECTION, SECTION_INDEX } from './sections'; import { generateRedactTaxonomyTable, generateRedactInvocationBlock } from './redact-doc'; +import { generateAutoplanOutsideVoiceBlock, generateAutoplanOutsideVoicePreflight } from './autoplan'; export const RESOLVERS: Record = { SLUG_EVAL: generateSlugEval, @@ -102,4 +103,6 @@ export const RESOLVERS: Record = { TASKS_SECTION_AGGREGATE: generateTasksSectionAggregate, SECTION, SECTION_INDEX, + AUTOPLAN_OUTSIDE_VOICE_PREFLIGHT: generateAutoplanOutsideVoicePreflight, + AUTOPLAN_OUTSIDE_VOICE_BLOCK: generateAutoplanOutsideVoiceBlock, }; diff --git a/test/gen-skill-docs.test.ts b/test/gen-skill-docs.test.ts index c1882e1e6c..d29b66a082 100644 --- a/test/gen-skill-docs.test.ts +++ b/test/gen-skill-docs.test.ts @@ -1795,6 +1795,32 @@ describe('Codex generation (--host codex)', () => { expect(content).not.toContain('.credentials.json'); }); + test('Codex-host autoplan flips dual voices to host subagent + Claude outside voice', () => { + const content = fs.readFileSync(path.join(AGENTS_DIR, 'gstack-autoplan', 'SKILL.md'), 'utf-8'); + expect(content).toContain('Claude CLI not found'); + expect(content).toContain('claude -p --output-format json'); + expect(content).toContain('Host-native CEO subagent'); + expect(content).toMatch(/OUTSIDE VOICE\s*\(CEO/); + expect(content).toContain('Dimension Subagent Outside Consensus'); + expect(content).toContain('SOURCE = "subagent+outside", "outside-only", "subagent-only", or "unavailable".'); + expect(content).not.toContain('Claude CEO subagent'); + expect(content).not.toContain('CLAUDE SUBAGENT (CEO'); + expect(content).not.toContain('Run Claude subagent (foreground'); + expect(content).not.toContain('**Codex outside voice**'); + expect(content).not.toContain('_gstack_codex_timeout_wrapper 600 codex exec'); + }); + + test('Claude-host autoplan still uses Codex as the outside voice', () => { + const content = fs.readFileSync(path.join(ROOT, 'autoplan', 'SKILL.md'), 'utf-8'); + expect(content).toContain('Codex CLI not found'); + expect(content).toContain('codex exec'); + expect(content).toContain('Host-native CEO subagent'); + expect(content).toMatch(/OUTSIDE VOICE\s*\(CEO/); + expect(content).toContain('Dimension Subagent Outside Consensus'); + expect(content).toContain('SOURCE = "subagent+outside", "outside-only", "subagent-only", or "unavailable".'); + expect(content).not.toContain('Claude CLI not found'); + }); + test('Codex review step stripped from Codex-host ship and review', () => { const shipContent = fs.readFileSync(path.join(AGENTS_DIR, 'gstack-ship', 'SKILL.md'), 'utf-8'); expect(shipContent).not.toContain('codex review --base'); From abf3bfbb793fcf877daa8c184c5a0a0f38a0af24 Mon Sep 17 00:00:00 2001 From: t Date: Mon, 13 Jul 2026 13:38:25 -0700 Subject: [PATCH 41/51] chore: regenerate tracked docs after trailer + codex-path source changes document-generate/SKILL.md, document-release/sections/release-body.md, pair-agent/SKILL.md, and ship/SKILL.md re-rendered from sources changed earlier in this wave (Opus 4.8 trailer, ~/.agents/skills codex path). The autoplan resolver adaptations (codex_reviews master-switch port, keychain-safe Claude probe) are folded into the preceding cherry-pick commit as conflict resolution. Co-Authored-By: Claude Fable 5 --- document-generate/SKILL.md | 2 +- document-release/sections/release-body.md | 2 +- pair-agent/SKILL.md | 2 +- ship/SKILL.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/document-generate/SKILL.md b/document-generate/SKILL.md index 30846fc4dd..f6b3b1a39e 100644 --- a/document-generate/SKILL.md +++ b/document-generate/SKILL.md @@ -1194,7 +1194,7 @@ docs: generate [scope] documentation (Diataxis) Quadrants: [list which quadrants were produced] -Co-Authored-By: Claude Opus 4.7 +Co-Authored-By: Claude Opus 4.8 EOF )" ``` diff --git a/document-release/sections/release-body.md b/document-release/sections/release-body.md index 0f05f13b51..00f344ae27 100644 --- a/document-release/sections/release-body.md +++ b/document-release/sections/release-body.md @@ -196,7 +196,7 @@ committing. git commit -m "$(cat <<'EOF' docs: update project documentation for vX.Y.Z.W -Co-Authored-By: Claude Opus 4.7 +Co-Authored-By: Claude Opus 4.8 EOF )" ``` diff --git a/pair-agent/SKILL.md b/pair-agent/SKILL.md index eed9d171af..2bd296dcd3 100644 --- a/pair-agent/SKILL.md +++ b/pair-agent/SKILL.md @@ -1048,7 +1048,7 @@ credentials are written to `~/.openclaw/skills/gstack/browse-remote.json`. Codex agents can execute shell commands via `codex exec`. The instruction block's curl commands work directly. When using `--local codex`, credentials are written -to `~/.codex/skills/gstack/browse-remote.json`. +to `~/.agents/skills/gstack/browse-remote.json`. ### Cursor diff --git a/ship/SKILL.md b/ship/SKILL.md index eadffaa8f6..acfe8e74e8 100644 --- a/ship/SKILL.md +++ b/ship/SKILL.md @@ -1229,7 +1229,7 @@ user via AskUserQuestion rather than destroying non-WIP commits. git commit -m "$(cat <<'EOF' chore: bump version and changelog (vX.Y.Z.W) -Co-Authored-By: Claude Opus 4.7 +Co-Authored-By: Claude Opus 4.8 EOF )" ``` From f0307dce6f7256060e359c98425efc89a3163eb7 Mon Sep 17 00:00:00 2001 From: Nehr <127654909+AgileInnov8tor@users.noreply.github.com> Date: Mon, 13 Jul 2026 13:46:48 -0700 Subject: [PATCH 42/51] feat(grok-build): first-class Grok packaging + multi-CLI bridges MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Squashed cherry-pick of community PR #2248 (8 commits), resolved against this wave's tree: - hosts/index.ts, setup host lists, INSTALL_* detection, and the host-count test unioned with the wave's pi/agy/vibe/qoder additions (registry now 15 hosts) - kept #2248's exported resolveDistBinary and dropped #1160's private duplicate resolveBinaryPath in scripts/resolvers/{browse,design}.ts — both fixed the same $HOME$GSTACK_* doubled-home bug identically - generated files and golden fixtures refresh in the wave's final regen commit Co-Authored-By: Claude Fable 5 --- .gitignore | 1 + TODOS.md | 49 + benchmark-models/SKILL.md | 21 +- benchmark-models/SKILL.md.tmpl | 21 +- bin/gstack-grok-compat-audit | 362 +++++ bin/gstack-model-benchmark | 37 +- claude/SKILL.md.tmpl | 5 + hosts/grok-build.ts | 113 ++ hosts/index.ts | 5 +- pair-agent/SKILL.md | 21 + pair-agent/SKILL.md.tmpl | 21 + scripts/gen-skill-docs.ts | 27 +- scripts/proactive-suggestions.json | 2 +- scripts/resolvers/browse.ts | 18 +- scripts/resolvers/design.ts | 16 +- scripts/resolvers/index.ts | 3 + scripts/resolvers/make-pdf.ts | 6 +- .../preamble/generate-preamble-bash.ts | 1 + scripts/resolvers/sections.ts | 91 +- scripts/resolvers/spec-spawn.ts | 118 ++ setup | 303 +++- setup-gbrain/SKILL.md | 27 +- setup-gbrain/SKILL.md.tmpl | 27 +- spec/SKILL.md.tmpl | 11 +- sync-gbrain/SKILL.md | 8 +- sync-gbrain/SKILL.md.tmpl | 8 +- test/fixtures/golden/codex-ship-SKILL.md | 1 + test/fixtures/golden/factory-ship-SKILL.md | 1 + test/fixtures/golden/grok-build-ship-SKILL.md | 1401 +++++++++++++++++ test/grok-packaging-behavior.test.ts | 600 +++++++ test/grok-section-pointers.test.ts | 104 ++ test/helpers/benchmark-runner.ts | 16 +- test/helpers/pricing.ts | 18 + test/helpers/providers/grok.ts | 338 ++++ test/helpers/providers/types.ts | 2 +- test/host-config.test.ts | 79 +- ...tup-plan-tune-hooks-noninteractive.test.ts | 10 + 37 files changed, 3762 insertions(+), 130 deletions(-) create mode 100755 bin/gstack-grok-compat-audit create mode 100644 hosts/grok-build.ts create mode 100644 scripts/resolvers/spec-spawn.ts create mode 100644 test/fixtures/golden/grok-build-ship-SKILL.md create mode 100644 test/grok-packaging-behavior.test.ts create mode 100644 test/grok-section-pointers.test.ts create mode 100644 test/helpers/providers/grok.ts diff --git a/.gitignore b/.gitignore index 31288b2a84..66ef827435 100644 --- a/.gitignore +++ b/.gitignore @@ -19,6 +19,7 @@ bin/gstack-global-discover* .opencode/ .slate/ .cursor/ +.grok/ .openclaw/ .pi/ .hermes/ diff --git a/TODOS.md b/TODOS.md index 29721e6e50..5eab5ab36d 100644 --- a/TODOS.md +++ b/TODOS.md @@ -2,6 +2,55 @@ ## NEXT PRIORITY +### P2: Grok Build full-compat follow-ups (after `feat/grok-build-host`) + +**What:** Finish / harden the Grok-native packaging work landed on +`feat/grok-build-host` (runtime root, SETUP path fix, host-bleed cleanup, +bridges, `bin/gstack-grok-compat-audit`, section pointers for token ceiling). +These are the remaining product/ship items — not blockers for local Grok use. + +**Context (landed on branch):** +- U1–U3 packaging + U4–U7 bridges + U9 audit gate +- Setup host-scoping (no always-on Codex `.agents/` regen / Claude plan-tune + prompt on `--host grok-build`) +- Option A: Grok carved skills use STOP-Read section pointers + (`~/.grok/skills/gstack-*/sections/`) — `/ship` always-loaded ~20k tokens + (was ~45k) + +**Follow-ups to track:** + +1. **Upstream PR** — open/update PR against `garrytan/gstack` for + `feat/grok-build-host` (VERSION/CHANGELOG/title deferred until local DoD + green on main merge path). +2. **U4 behavioral smoke** — if claiming `/spec --execute` COMPATIBLE (not + file-only), record multi-turn tool-use / cwd isolation / fail-closed auth + smoke or fixture; flag-string greps alone are not enough. +3. **Section pointers for other external hosts (optional)** — Codex ship is + still monolith ~39k (near soft ceiling). Reuse + `hostUsesSectionPointers` for Codex/Cursor/Factory when package paths are + portable (Codex: `.agents/skills/gstack-*` or global + `~/.codex/skills/gstack-*`). +4. **R10 / U8 optional `gstack-codex`** — only if product wants suite + completeness; keep bare `/codex` = OpenAI plugin; deny bare `codex` alias + on Grok install (partial deny already in `link_grok_skill_dirs`). +5. **Gbrain Grok MCP stretch** — optional `~/.grok/config.toml` gbrain stanza + (absolute path, TOML RMW, atomic write + backup; non-interactive refuse + overwrite without `--force`). Success path remains CLI + AGENTS.md. +6. **Audit harness productization** — keep `bin/gstack-grok-compat-audit` as + long-lived multi-host CI later, or document as branch/DoD gate only + (open question from plan ce-doc-review). +7. **Name collision note** — document `/review` vs compound-engineering + `code-review` routing in `~/.grok/AGENTS.md` (do not delete CE skill). + +**Why:** Branch is implementation-ready for local Grok; these items close +honesty gaps, upstream ship, and optional suite completeness without +reopening Phase A packaging. + +**Depends on / blocked by:** Nothing for local use. Upstream PR waits on +clean validation + VERSION/CHANGELOG if that is the release process. + +--- + ### P1: #1882 — portable skill-install prefix (non-`gstack` install dirs break silently) **What:** Every generated SKILL.md hardcodes the literal `~/.claude/skills/gstack/...` diff --git a/benchmark-models/SKILL.md b/benchmark-models/SKILL.md index 6a9d62616d..70fdacdd5f 100644 --- a/benchmark-models/SKILL.md +++ b/benchmark-models/SKILL.md @@ -20,11 +20,12 @@ allowed-tools: ## When to invoke this skill Runs the same prompt through Claude, -GPT (via Codex CLI), and Gemini side-by-side — compares latency, tokens, cost, -and optionally quality via LLM judge. Answers "which model is actually best -for this skill?" with data instead of vibes. Separate from /benchmark, which -measures web page performance. Use when: "benchmark models", "compare models", -"which model is best for X", "cross-model comparison", "model shootout". +GPT (via Codex CLI), Gemini, and Grok side-by-side — compares latency, tokens, +cost, and optionally quality via LLM judge. Answers "which model is actually +best for this skill?" with data instead of vibes. Separate from /benchmark, +which measures web page performance. Use when: "benchmark models", "compare +models", "which model is best for X", "cross-model comparison", "model +shootout". Voice triggers (speech-to-text aliases): "compare models", "model shootout", "which model is best". @@ -578,12 +579,12 @@ If C: ask for the path. Verify it exists. Use as positional argument. ## Step 2: Choose providers ```bash -"$BIN" --prompt "unused, dry-run" --models claude,gpt,gemini --dry-run +"$BIN" --prompt "unused, dry-run" --models claude,gpt,gemini,grok --dry-run ``` Show the dry-run output. The "Adapter availability" section tells the user which providers will actually run (OK) vs skip (NOT READY — remediation hint included). -If ALL three show NOT READY: stop with a clear message — benchmark can't run without at least one authed provider. Suggest `claude login`, `codex login`, or `gemini login` / `export GOOGLE_API_KEY`. +If ALL show NOT READY: stop with a clear message — benchmark can't run without at least one authed provider. Suggest `claude login`, `codex login`, `gemini login` / `export GOOGLE_API_KEY`, or `grok` login / `export XAI_API_KEY`. If at least one is OK: AskUserQuestion: - **Simplify:** "Which models should we include? The dry-run above showed which are authed. Unauthed ones will be skipped cleanly — they won't abort the batch." @@ -591,7 +592,8 @@ If at least one is OK: AskUserQuestion: - **Options:** - A) All authed providers. Completeness: 10/10. - B) Only Claude. Completeness: 6/10 (no cross-model signal — use /ship's review for solo claude benchmarks instead). - - C) Pick two — specify on next turn. Completeness: 8/10. + - C) Only Grok (Grok-only machine). Completeness: 7/10. + - D) Pick two — specify on next turn. Completeness: 8/10. --- @@ -608,7 +610,8 @@ If judge is available, AskUserQuestion: - A) Enable judge (adds ~$0.05). Completeness: 10/10. - B) Skip judge — speed/cost/tokens only. Completeness: 7/10. -If judge is NOT available, skip this question and omit the `--judge` flag. +If judge is NOT available (Grok-only / no ANTHROPIC_API_KEY): skip this question +and omit `--judge` (Grok-or-skip). Speed/cost/tokens still work. --- diff --git a/benchmark-models/SKILL.md.tmpl b/benchmark-models/SKILL.md.tmpl index 034cda1824..bf3458db32 100644 --- a/benchmark-models/SKILL.md.tmpl +++ b/benchmark-models/SKILL.md.tmpl @@ -4,11 +4,12 @@ preamble-tier: 1 version: 1.0.0 description: | Cross-model benchmark for gstack skills. Runs the same prompt through Claude, - GPT (via Codex CLI), and Gemini side-by-side — compares latency, tokens, cost, - and optionally quality via LLM judge. Answers "which model is actually best - for this skill?" with data instead of vibes. Separate from /benchmark, which - measures web page performance. Use when: "benchmark models", "compare models", - "which model is best for X", "cross-model comparison", "model shootout". (gstack) + GPT (via Codex CLI), Gemini, and Grok side-by-side — compares latency, tokens, + cost, and optionally quality via LLM judge. Answers "which model is actually + best for this skill?" with data instead of vibes. Separate from /benchmark, + which measures web page performance. Use when: "benchmark models", "compare + models", "which model is best for X", "cross-model comparison", "model + shootout". (gstack) voice-triggers: - "compare models" - "model shootout" @@ -69,12 +70,12 @@ If C: ask for the path. Verify it exists. Use as positional argument. ## Step 2: Choose providers ```bash -"$BIN" --prompt "unused, dry-run" --models claude,gpt,gemini --dry-run +"$BIN" --prompt "unused, dry-run" --models claude,gpt,gemini,grok --dry-run ``` Show the dry-run output. The "Adapter availability" section tells the user which providers will actually run (OK) vs skip (NOT READY — remediation hint included). -If ALL three show NOT READY: stop with a clear message — benchmark can't run without at least one authed provider. Suggest `claude login`, `codex login`, or `gemini login` / `export GOOGLE_API_KEY`. +If ALL show NOT READY: stop with a clear message — benchmark can't run without at least one authed provider. Suggest `claude login`, `codex login`, `gemini login` / `export GOOGLE_API_KEY`, or `grok` login / `export XAI_API_KEY`. If at least one is OK: AskUserQuestion: - **Simplify:** "Which models should we include? The dry-run above showed which are authed. Unauthed ones will be skipped cleanly — they won't abort the batch." @@ -82,7 +83,8 @@ If at least one is OK: AskUserQuestion: - **Options:** - A) All authed providers. Completeness: 10/10. - B) Only Claude. Completeness: 6/10 (no cross-model signal — use /ship's review for solo claude benchmarks instead). - - C) Pick two — specify on next turn. Completeness: 8/10. + - C) Only Grok (Grok-only machine). Completeness: 7/10. + - D) Pick two — specify on next turn. Completeness: 8/10. --- @@ -99,7 +101,8 @@ If judge is available, AskUserQuestion: - A) Enable judge (adds ~$0.05). Completeness: 10/10. - B) Skip judge — speed/cost/tokens only. Completeness: 7/10. -If judge is NOT available, skip this question and omit the `--judge` flag. +If judge is NOT available (Grok-only / no ANTHROPIC_API_KEY): skip this question +and omit `--judge` (Grok-or-skip). Speed/cost/tokens still work. --- diff --git a/bin/gstack-grok-compat-audit b/bin/gstack-grok-compat-audit new file mode 100755 index 0000000000..67b3df488a --- /dev/null +++ b/bin/gstack-grok-compat-audit @@ -0,0 +1,362 @@ +#!/usr/bin/env bun +/** + * gstack-grok-compat-audit — Definition of Done gate for Grok Build packaging + * + bridge honesty (plan U9 / R11). + * + * Exit 0 only when packaging checks pass for installed gstack membership + * packages and bridge gates are not theater-greened. + * + * Usage: + * bin/gstack-grok-compat-audit + * bin/gstack-grok-compat-audit --skills-dir ~/.grok/skills + * bin/gstack-grok-compat-audit --phase a # packaging only + * bin/gstack-grok-compat-audit --phase ab # packaging + bridge gates (default) + */ + +import * as fs from 'fs'; +import * as path from 'path'; +import * as os from 'os'; +import { execFileSync } from 'child_process'; + +const ROOT = path.resolve(import.meta.dir, '..'); +const args = process.argv.slice(2); + +function arg(name: string, def?: string): string | undefined { + const idx = args.findIndex(a => a === name || a.startsWith(name + '=')); + if (idx < 0) return def; + const eq = args[idx].indexOf('='); + if (eq >= 0) return args[idx].slice(eq + 1); + return args[idx + 1] ?? def; +} + +const SKILLS_DIR = path.resolve( + (arg('--skills-dir') ?? path.join(os.homedir(), '.grok', 'skills')).replace(/^~/, os.homedir()), +); +const PHASE = (arg('--phase') ?? 'ab').toLowerCase(); +const GSTACK_ROOT = path.join(SKILLS_DIR, 'gstack'); + +type Severity = 'fail' | 'warn' | 'ok'; +interface Finding { + severity: Severity; + area: string; + message: string; +} + +const findings: Finding[] = []; + +function fail(area: string, message: string) { + findings.push({ severity: 'fail', area, message }); +} +function warn(area: string, message: string) { + findings.push({ severity: 'warn', area, message }); +} +function ok(area: string, message: string) { + findings.push({ severity: 'ok', area, message }); +} + +function exists(p: string): boolean { + try { + fs.accessSync(p); + return true; + } catch { + return false; + } +} + +function readText(p: string): string { + try { + return fs.readFileSync(p, 'utf-8'); + } catch { + return ''; + } +} + +function isGstackMembership(dirName: string): boolean { + if (dirName === 'gstack' || dirName === 'connect-chrome' || dirName === 'browse') return true; + if (dirName.startsWith('gstack-')) return true; + // bare aliases that point at gstack packages (symlink or real SKILL with gstack markers) + const skill = path.join(SKILLS_DIR, dirName, 'SKILL.md'); + if (!exists(skill)) return false; + const body = readText(skill); + return body.includes('$GSTACK_ROOT') || body.includes('gstack') || body.includes('AUTO-GENERATED'); +} + +function listMembershipPackages(): string[] { + if (!exists(SKILLS_DIR)) return []; + return fs + .readdirSync(SKILLS_DIR, { withFileTypes: true }) + .filter(d => d.isDirectory() || d.isSymbolicLink()) + .map(d => d.name) + .filter(isGstackMembership) + .sort(); +} + +// ─── Packaging suite (Phase A) ──────────────────────────────── + +function auditRuntimeRoot() { + const area = 'runtime-root'; + if (!exists(GSTACK_ROOT)) { + fail(area, `missing runtime root: ${GSTACK_ROOT}`); + return; + } + const requiredDirs = [ + 'bin', + 'browse/dist', + 'browse/src', + 'review/specialists', + 'scripts', + ]; + for (const rel of requiredDirs) { + const p = path.join(GSTACK_ROOT, rel); + if (!exists(p)) fail(area, `missing required asset: ${rel}`); + else ok(area, `present: ${rel}`); + } + // Conditional when monorepo had them at install — soft-check if src monorepo has them + const monorepoHas = (rel: string) => exists(path.join(ROOT, rel)); + if (monorepoHas('design/dist') && !exists(path.join(GSTACK_ROOT, 'design/dist'))) { + fail(area, 'monorepo has design/dist but runtime root does not'); + } + if (monorepoHas('extension') && !exists(path.join(GSTACK_ROOT, 'extension'))) { + fail(area, 'monorepo has extension/ but runtime root does not'); + } + if (monorepoHas('make-pdf/dist') && !exists(path.join(GSTACK_ROOT, 'make-pdf/dist'))) { + warn(area, 'monorepo has make-pdf/dist but runtime root does not (membership optional)'); + } + for (const f of ['checklist.md', 'TODOS-format.md']) { + const p = path.join(GSTACK_ROOT, 'review', f); + if (!exists(p)) fail(area, `missing review/${f}`); + else ok(area, `present: review/${f}`); + } +} + +function auditNoDoubleHome() { + const area = 'no-double-home'; + const pkgs = listMembershipPackages(); + let hits = 0; + for (const name of pkgs) { + const skill = path.join(SKILLS_DIR, name, 'SKILL.md'); + if (!exists(skill)) continue; + const body = readText(skill); + if (/\$HOME\$GSTACK/.test(body)) { + fail(area, `${name}: contains $HOME$GSTACK (double-home path bug)`); + hits++; + } + } + if (hits === 0) ok(area, `no $HOME$GSTACK in ${pkgs.length} packages`); +} + +function auditNoUngeneratedMonorepoPointers() { + const area = 'no-monorepo-skill-pointer'; + // Skills under ~/.grok/skills must not be bare monorepo dirs with unrewritten Claude SKILL.md + // Heuristic: ungenerated monorepo package often has MODEL_OVERLAY: claude section + ~/.claude paths without rewrite + const pkgs = listMembershipPackages(); + for (const name of pkgs) { + const skill = path.join(SKILLS_DIR, name, 'SKILL.md'); + if (!exists(skill)) continue; + const body = readText(skill); + // Skip runtime root + if (name === 'gstack' && !body.includes('name:')) continue; + if (body.includes('~/.claude/skills/gstack') && !body.includes('$GSTACK_ROOT')) { + // Still has unrewritten Claude global path without env var form + fail(area, `${name}: unrewritten ~/.claude/skills/gstack pointer`); + } + } + ok(area, 'membership packages scanned for unrewritten Claude monorepo pointers'); +} + +function auditConnectChrome() { + const area = 'connect-chrome'; + const link = path.join(SKILLS_DIR, 'connect-chrome'); + if (!exists(link)) { + fail(area, 'connect-chrome missing under skills dir'); + return; + } + try { + const target = fs.realpathSync(link); + if (!/open-gstack-browser/.test(target) && !/gstack-open-gstack-browser/.test(target)) { + fail(area, `connect-chrome does not resolve to open-gstack-browser (got ${target})`); + } else { + ok(area, `connect-chrome → ${target}`); + } + } catch (e) { + fail(area, `connect-chrome realpath failed: ${(e as Error).message}`); + } +} + +function auditHostBleedSample() { + const area = 'host-bleed'; + const samples = ['gstack-ship', 'ship', 'gstack-browse', 'browse', 'gstack-claude', 'claude']; + for (const name of samples) { + const skill = path.join(SKILLS_DIR, name, 'SKILL.md'); + if (!exists(skill)) continue; + const body = readText(skill); + if (/MODEL_OVERLAY:\s*claude/.test(body)) { + fail(area, `${name}: MODEL_OVERLAY: claude still present`); + } + if (/## Model-Specific Behavioral Patch \(claude\)/.test(body)) { + fail(area, `${name}: Claude model overlay section body present`); + } + // Claude skill is allowed to mention claude CLI extensively + if (name !== 'claude' && name !== 'gstack-claude') { + if (/\bAskUserQuestion\b/.test(body) && !/ask_user_question/.test(body)) { + // May still appear in examples — soft + warn(area, `${name}: raw AskUserQuestion token (prefer ask_user_question rewrite)`); + } + } + if (name === 'claude' || name === 'gstack-claude') { + if (!/MULTI_CLI_BRIDGE/.test(body) && !/Step 0: Check Claude CLI/.test(body)) { + fail(area, `${name}: missing MULTI_CLI_BRIDGE / Step 0 detect`); + } else { + ok(area, `${name}: Step 0 / multi-CLI packaging present`); + } + } + } + ok(area, 'host-bleed sample scan complete'); +} + +function auditSkillifySdkPath() { + const area = 'skillify-sdk'; + const src = path.join(GSTACK_ROOT, 'browse', 'src', 'browse-client.ts'); + if (exists(src)) ok(area, 'browse/src/browse-client.ts resolvable under $GSTACK_ROOT'); + else fail(area, 'browse/src/browse-client.ts missing — skillify SDK path broken'); +} + +// ─── Bridge gates (Phase B) ─────────────────────────────────── + +function auditBridges() { + // Install prose alone must not claim primary READY when CLI missing + const area = 'bridge-policy'; + + // Prefer installed runtime root binary (what users run); fall back to monorepo. + const installedBench = path.join(GSTACK_ROOT, 'bin', 'gstack-model-benchmark'); + const monorepoBench = path.join(ROOT, 'bin', 'gstack-model-benchmark'); + const benchBin = exists(installedBench) ? installedBench : monorepoBench; + if (!exists(installedBench) && exists(monorepoBench)) { + warn(area, 'benchmark: using monorepo binary (installed runtime bin missing) — packaging incomplete?'); + } + try { + // No shell: argv list avoids monorepo-path injection. + const help = execFileSync(benchBin, ['--prompt', 'x', '--models', 'grok', '--dry-run'], { + encoding: 'utf-8', + timeout: 15000, + maxBuffer: 2 * 1024 * 1024, + }); + if (/unknown provider.*grok/i.test(help)) { + fail(area, 'benchmark: grok still unknown provider'); + } else if (/grok:\s*(OK|NOT READY)/i.test(help)) { + ok(area, `benchmark: grok provider wired via ${benchBin} (dry-run READY/NOT READY is boolean auth)`); + } else { + warn(area, `benchmark dry-run unexpected output: ${help.slice(0, 200)}`); + } + } catch (e) { + const msg = (e as { stdout?: string; message?: string }).stdout + ?? (e as Error).message + ?? String(e); + if (/unknown provider.*grok/i.test(msg)) fail(area, 'benchmark: grok unknown provider'); + else warn(area, `benchmark dry-run error: ${String(msg).slice(0, 200)}`); + } + + // spec: at least one installed package must exist and use Grok-native spawn + let specSeen = 0; + for (const name of ['gstack-spec', 'spec']) { + const skill = path.join(SKILLS_DIR, name, 'SKILL.md'); + if (!exists(skill)) continue; + specSeen++; + const body = readText(skill); + if (/\$\(cat\s+["']?\$ARCHIVE/.test(body) || /grok[^\n]*\$\(cat/.test(body)) { + fail(area, `${name}: banned $(cat …) into grok argv`); + } + if (/grok --prompt-file/.test(body) || /Spawn \*\*Grok\*\*/.test(body)) { + ok(area, `${name}: Grok-native spawn present`); + } else if (/Spawned:.*claude -p/.test(body) && !/--execute-claude/.test(body)) { + fail(area, `${name}: default execute still only claude -p (no Grok spawn)`); + } else { + fail(area, `${name}: missing researched grok --prompt-file spawn`); + } + } + if (specSeen === 0) { + fail(area, 'spec: neither gstack-spec nor spec package installed under skills dir'); + } + + // setup-gbrain: must not hard-require which claude for success + let gbrainSeen = 0; + for (const name of ['gstack-setup-gbrain', 'setup-gbrain']) { + const skill = path.join(SKILLS_DIR, name, 'SKILL.md'); + if (!exists(skill)) continue; + gbrainSeen++; + const body = readText(skill); + if (/Grok Build success path/.test(body) || /no Claude required/i.test(body)) { + ok(area, `${name}: Grok success path documented`); + } else { + warn(area, `${name}: missing explicit Grok success path (CLI+AGENTS)`); + } + } + if (gbrainSeen === 0) { + warn(area, 'setup-gbrain: package not installed (bridge not audited)'); + } + + // pair-agent: local must not hard-require ngrok; remote has install+security+teardown + let pairSeen = 0; + for (const name of ['gstack-pair-agent', 'pair-agent']) { + const skill = path.join(SKILLS_DIR, name, 'SKILL.md'); + if (!exists(skill)) continue; + pairSeen++; + const body = readText(skill); + if (/teardown/i.test(body) && /ngrok/i.test(body) && /127\.0\.0\.1|security/i.test(body)) { + ok(area, `${name}: remote ngrok install+security+teardown present`); + } else { + warn(area, `${name}: remote security/teardown checklist incomplete`); + } + if (/DEPENDENT/.test(body)) ok(area, `${name}: honest DEPENDENT labeling`); + } + if (pairSeen === 0) { + warn(area, 'pair-agent: package not installed (bridge not audited)'); + } +} + +// ─── Main ───────────────────────────────────────────────────── + +function main() { + console.log('== gstack-grok-compat-audit =='); + console.log(` skills-dir: ${SKILLS_DIR}`); + console.log(` phase: ${PHASE}`); + console.log(` monorepo: ${ROOT}`); + console.log(''); + + if (!exists(SKILLS_DIR)) { + fail('install', `skills dir missing: ${SKILLS_DIR} — run: cd ${ROOT} && ./setup --host grok-build`); + } else { + const pkgs = listMembershipPackages(); + console.log(` membership packages: ${pkgs.length}`); + auditRuntimeRoot(); + auditNoDoubleHome(); + auditNoUngeneratedMonorepoPointers(); + auditConnectChrome(); + auditHostBleedSample(); + auditSkillifySdkPath(); + + if (PHASE === 'ab' || PHASE === 'b' || PHASE === 'full') { + auditBridges(); + } + } + + const fails = findings.filter(f => f.severity === 'fail'); + const warns = findings.filter(f => f.severity === 'warn'); + const oks = findings.filter(f => f.severity === 'ok'); + + for (const f of findings) { + const tag = f.severity === 'fail' ? 'FAIL' : f.severity === 'warn' ? 'WARN' : 'OK '; + console.log(`[${tag}] ${f.area}: ${f.message}`); + } + + console.log(''); + console.log(`Summary: ${oks.length} ok, ${warns.length} warn, ${fails.length} fail`); + if (fails.length > 0) { + console.log('VERDICT: INCOMPATIBLE (packaging/bridge gate failed)'); + process.exit(1); + } + console.log('VERDICT: packaging COMPATIBLE' + (PHASE.includes('b') || PHASE === 'full' ? ' (+ bridge gates honest)' : '')); + process.exit(0); +} + +main(); diff --git a/bin/gstack-model-benchmark b/bin/gstack-model-benchmark index c5f5cb5b65..c199bed634 100755 --- a/bin/gstack-model-benchmark +++ b/bin/gstack-model-benchmark @@ -7,7 +7,7 @@ * gstack-model-benchmark [options] * * Options: - * --models claude,gpt,gemini Comma-separated provider list (default: claude) + * --models claude,gpt,gemini,grok Comma-separated provider list (default: claude) * --prompt "" Inline prompt instead of a file * --workdir Working dir passed to each CLI (default: cwd) * --timeout-ms Per-provider timeout (default: 300000) @@ -15,27 +15,29 @@ * --skip-unavailable Skip providers that fail available() check * (default: include them with unavailable marker) * --judge Run Anthropic SDK judge on outputs for quality score - * (requires ANTHROPIC_API_KEY; adds ~$0.05 per call) + * (requires ANTHROPIC_API_KEY; Grok-only skips judge) * --dry-run Validate flags + resolve auth, don't invoke providers * * Examples: * gstack-model-benchmark --prompt "Write a haiku about databases" --models claude,gpt * gstack-model-benchmark ./test-prompt.txt --models claude,gpt,gemini --judge - * gstack-model-benchmark --prompt "hi" --models claude,gpt,gemini --dry-run + * gstack-model-benchmark --prompt "hi" --models grok --dry-run */ import '../lib/conductor-env-shim'; import * as fs from 'fs'; import * as path from 'path'; -import { runBenchmark, formatTable, formatJson, formatMarkdown, type BenchmarkInput } from '../test/helpers/benchmark-runner'; +import { runBenchmark, formatTable, formatJson, formatMarkdown, type BenchmarkInput, type ProviderName } from '../test/helpers/benchmark-runner'; import { ClaudeAdapter } from '../test/helpers/providers/claude'; import { GptAdapter } from '../test/helpers/providers/gpt'; import { GeminiAdapter } from '../test/helpers/providers/gemini'; +import { GrokAdapter } from '../test/helpers/providers/grok'; -const ADAPTER_FACTORIES = { +const ADAPTER_FACTORIES: Record { name: string; available: () => Promise<{ ok: boolean; reason?: string }> }> = { claude: () => new ClaudeAdapter(), gpt: () => new GptAdapter(), gemini: () => new GeminiAdapter(), + grok: () => new GrokAdapter(), }; type OutputFormat = 'table' | 'json' | 'markdown'; @@ -76,13 +78,13 @@ function positionalArgs(args: string[]): string[] { return positional; } -function parseProviders(s: string | undefined): Array<'claude' | 'gpt' | 'gemini'> { +function parseProviders(s: string | undefined): ProviderName[] { if (!s) return ['claude']; - const seen = new Set<'claude' | 'gpt' | 'gemini'>(); + const seen = new Set(); for (const p of s.split(',').map(x => x.trim()).filter(Boolean)) { - if (p === 'claude' || p === 'gpt' || p === 'gemini') seen.add(p); + if (p === 'claude' || p === 'gpt' || p === 'gemini' || p === 'grok') seen.add(p); else { - console.error(`WARN: unknown provider '${p}' — skipping. Valid: claude, gpt, gemini.`); + console.error(`WARN: unknown provider '${p}' — skipping. Valid: claude, gpt, gemini, grok.`); } } return seen.size ? Array.from(seen) : ['claude']; @@ -129,11 +131,16 @@ async function main(): Promise { const report = await runBenchmark(input); if (doJudge) { - try { - const { judgeEntries } = await import('../test/helpers/benchmark-judge'); - await judgeEntries(report); - } catch (err) { - console.error(`WARN: judge unavailable: ${(err as Error).message}`); + // Grok-or-skip: judge requires Anthropic; Grok-only machines skip cleanly + if (!process.env.ANTHROPIC_API_KEY) { + console.error('WARN: judge skipped — ANTHROPIC_API_KEY not set (Grok-or-skip judge).'); + } else { + try { + const { judgeEntries } = await import('../test/helpers/benchmark-judge'); + await judgeEntries(report); + } catch (err) { + console.error(`WARN: judge unavailable: ${(err as Error).message}`); + } } } @@ -149,7 +156,7 @@ async function main(): Promise { async function dryRunReport(opts: { prompt: string; - providers: Array<'claude' | 'gpt' | 'gemini'>; + providers: ProviderName[]; workdir: string; timeoutMs: number; output: OutputFormat; diff --git a/claude/SKILL.md.tmpl b/claude/SKILL.md.tmpl index 9bf77f3f6f..1b461e05e1 100644 --- a/claude/SKILL.md.tmpl +++ b/claude/SKILL.md.tmpl @@ -30,6 +30,11 @@ modify files. The generated external invocation name is `gstack-claude`. +**MULTI_CLI_BRIDGE:** Primary modes always call the Claude Code CLI. Packaging and +Step 0 detect/install are first-class on this host; this skill does **not** work +without Claude installed and authenticated. Residual foreign-CLI dependency is +expected and labeled — never claim "works without Claude." + --- ## Step 0: Check Claude CLI diff --git a/hosts/grok-build.ts b/hosts/grok-build.ts new file mode 100644 index 0000000000..3f3c1c8731 --- /dev/null +++ b/hosts/grok-build.ts @@ -0,0 +1,113 @@ +import type { HostConfig } from '../scripts/host-config'; + +/** + * Grok Build (xAI) host — based on community PR #2028 (adamouabakar), + * aligned with cursor/factory host patterns and Grok skill discovery. + * + * Skills generate into /.grok/skills/gstack-* and install under + * ~/.grok/skills/ (flat skill packages + runtime root at ~/.grok/skills/gstack). + * + * Grok discovers user skills from ~/.grok/skills//SKILL.md. + * Frontmatter `name:` stays unprefixed (browse, ship, …) so slash commands + * remain /browse, /ship, etc. Directory names use gstack- prefix (external hosts). + */ +const grokBuild: HostConfig = { + name: 'grok-build', + displayName: 'Grok Build', + cliCommand: 'grok', + cliAliases: ['grok-build'], + + // Relative to $HOME for global install path docs / preamble + globalRoot: '.grok/skills/gstack', + // Project-local runtime root (optional team mode) + localSkillRoot: '.grok/skills/gstack', + // Gitignored generated skill docs live here + hostSubdir: '.grok', + usesEnvVars: true, + + frontmatter: { + mode: 'allowlist', + // Keep triggers so Grok model-invocation routing still works + keepFields: ['name', 'description', 'triggers', 'allowed-tools'], + descriptionLimit: null, + }, + + generation: { + generateMetadata: false, + // Upstream convention: /codex skill is a Claude↔Codex bridge; all external + // hosts skip it (host-config.test.ts). Grok users already have the openai-codex + // plugin; keep /claude as an optional outside-voice skill. + skipSkills: ['codex'], + }, + + pathRewrites: [ + { from: '~/.claude/skills/gstack', to: '$GSTACK_ROOT' }, + { from: '.claude/skills/gstack', to: '.grok/skills/gstack' }, + { from: '.claude/skills/review', to: '.grok/skills/gstack/review' }, + { from: '.claude/skills', to: '.grok/skills' }, + { from: '~/.claude/skills', to: '~/.grok/skills' }, + { from: 'CLAUDE.md', to: 'AGENTS.md' }, + // Defense-in-depth if a Claude model overlay ever slips through (U3 / KTD6) + { from: 'MODEL_OVERLAY: claude', to: 'MODEL_OVERLAY: none' }, + { from: 'use the Skill tool', to: 'invoke the skill via slash command or skill load' }, + ], + + toolRewrites: { + 'use the Bash tool': 'run this command in the shell', + 'use the Write tool': 'create this file', + 'use the Read tool': 'read the file', + 'use the Edit tool': 'edit the file', + 'use the Agent tool': 'dispatch a subagent', + 'use the Grep tool': 'search for', + 'use the Glob tool': 'find files matching', + 'use the Skill tool': 'invoke the skill via slash command or skill load', + AskUserQuestion: 'ask_user_question', + ExitPlanMode: 'exit_plan_mode', + }, + + // Suppress Claude-only outside-voice orchestration that assumes Claude can + // spawn Codex as itself. Keep plan/review skills; they still run on Grok. + suppressedResolvers: [ + 'GBRAIN_CONTEXT_LOAD', + 'GBRAIN_SAVE_RESULTS', + ], + + // Thin runtime root: every asset skills resolve via $GSTACK_ROOT (R1 / U1). + // Dual-write with setup create_grok_runtime_root — keep lists in sync. + runtimeRoot: { + globalSymlinks: [ + 'bin', + 'browse/dist', + 'browse/bin', + 'browse/src', + 'design/dist', + 'make-pdf/dist', + 'extension', + 'scripts', + 'review/specialists', + 'gstack-upgrade', + 'ETHOS.md', + ], + globalFiles: { + review: [ + 'checklist.md', + 'TODOS-format.md', + 'design-checklist.md', + 'greptile-triage.md', + ], + }, + }, + + install: { + prefixable: false, + linkingStrategy: 'symlink-generated', + }, + + learningsMode: 'basic', + boundaryInstruction: + 'IMPORTANT: Prefer ~/.grok/skills/gstack and $GSTACK_ROOT over ~/.claude/skills/gstack. ' + + 'Do not assume Claude Code tools (TodoWrite, Skill tool, Claude-in-Chrome MCP). ' + + 'Use Grok shell/read/edit/web tools and ask_user_question. Prefer /browse over browser MCPs.', +}; + +export default grokBuild; diff --git a/hosts/index.ts b/hosts/index.ts index 39ffa6354a..5a0f81a967 100644 --- a/hosts/index.ts +++ b/hosts/index.ts @@ -20,9 +20,10 @@ import pi from './pi'; import agy from './agy'; import vibe from './vibe'; import qoder from './qoder'; +import grokBuild from './grok-build'; /** All registered host configs. Add new hosts here. */ -export const ALL_HOST_CONFIGS: HostConfig[] = [claude, codex, factory, kiro, opencode, slate, cursor, openclaw, hermes, gbrain, pi, agy, vibe, qoder]; +export const ALL_HOST_CONFIGS: HostConfig[] = [claude, codex, factory, kiro, opencode, slate, cursor, openclaw, hermes, gbrain, pi, agy, vibe, qoder, grokBuild]; /** Map from host name to config. */ export const HOST_CONFIG_MAP: Record = Object.fromEntries( @@ -69,4 +70,4 @@ export function getExternalHosts(): HostConfig[] { } // Re-export individual configs for direct import -export { claude, codex, factory, kiro, opencode, slate, cursor, openclaw, hermes, gbrain, pi, agy, vibe, qoder }; +export { claude, codex, factory, kiro, opencode, slate, cursor, openclaw, hermes, gbrain, pi, agy, vibe, qoder, grokBuild }; diff --git a/pair-agent/SKILL.md b/pair-agent/SKILL.md index 2bd296dcd3..eaae049f36 100644 --- a/pair-agent/SKILL.md +++ b/pair-agent/SKILL.md @@ -994,6 +994,27 @@ browser to the internet securely). STOP here. Wait for the user to install ngrok and re-invoke. +**Bridge status:** Remote pair is **DEPENDENT** on ngrok until the tunnel binary +is installed and authenticated. Local same-machine pair remains zero-extra-dep +and must never hard-require ngrok. + +### Remote path security + teardown checklist + +Remote pairing expands attack surface vs local pair. Always: + +1. **Authenticated tunnel only** — never run an unauthenticated public expose. +2. **Bind local pair endpoint to 127.0.0.1** — do not advertise LAN bind. +3. **Authtoken out-of-band** — user pastes token into `ngrok config add-authtoken`; + never echo the token or tunnel URL into session transcripts beyond what the + CLI already printed for the user to copy. +4. **Teardown after pair** — when pairing ends, stop the ngrok tunnel process + (or tell the user: `pkill -f 'ngrok http'` / dashboard stop). Do not leave + a long-lived public tunnel running. +5. **Verify:** `ngrok config check` after auth; `which ngrok` for install. + +If ngrok is missing, report bridge DEPENDENT (install path present) — do **not** +mark the remote primary path READY/COMPATIBLE from install prose alone. + ## Step 5: Verify connection After the user pastes the instructions into the other agent, wait a moment then check: diff --git a/pair-agent/SKILL.md.tmpl b/pair-agent/SKILL.md.tmpl index 86b0e4c663..584df75be5 100644 --- a/pair-agent/SKILL.md.tmpl +++ b/pair-agent/SKILL.md.tmpl @@ -189,6 +189,27 @@ browser to the internet securely). STOP here. Wait for the user to install ngrok and re-invoke. +**Bridge status:** Remote pair is **DEPENDENT** on ngrok until the tunnel binary +is installed and authenticated. Local same-machine pair remains zero-extra-dep +and must never hard-require ngrok. + +### Remote path security + teardown checklist + +Remote pairing expands attack surface vs local pair. Always: + +1. **Authenticated tunnel only** — never run an unauthenticated public expose. +2. **Bind local pair endpoint to 127.0.0.1** — do not advertise LAN bind. +3. **Authtoken out-of-band** — user pastes token into `ngrok config add-authtoken`; + never echo the token or tunnel URL into session transcripts beyond what the + CLI already printed for the user to copy. +4. **Teardown after pair** — when pairing ends, stop the ngrok tunnel process + (or tell the user: `pkill -f 'ngrok http'` / dashboard stop). Do not leave + a long-lived public tunnel running. +5. **Verify:** `ngrok config check` after auth; `which ngrok` for install. + +If ngrok is missing, report bridge DEPENDENT (install path present) — do **not** +mark the remote primary path READY/COMPATIBLE from install prose alone. + ## Step 5: Verify connection After the user pastes the instructions into the other agent, wait a moment then check: diff --git a/scripts/gen-skill-docs.ts b/scripts/gen-skill-docs.ts index 856e275b44..5cce983e4b 100644 --- a/scripts/gen-skill-docs.ts +++ b/scripts/gen-skill-docs.ts @@ -18,6 +18,7 @@ import * as path from 'path'; import type { Host, TemplateContext } from './resolvers/types'; import { HOST_PATHS, unwrapResolver } from './resolvers/types'; import { RESOLVERS } from './resolvers/index'; +import { hostUsesSectionPointers } from './resolvers/sections'; import { externalSkillName, extractHookSafetyProse as _extractHookSafetyProse, extractNameAndDescription as _extractNameAndDescription, condenseOpenAIShortDescription as _condenseOpenAIShortDescription, generateOpenAIYaml as _generateOpenAIYaml } from './resolvers/codex-helpers'; import { generatePlanCompletionAuditShip, generatePlanCompletionAuditReview, generatePlanVerificationExec } from './resolvers/review'; import { ALL_HOST_CONFIGS, ALL_HOST_NAMES, resolveHostArg, getHostConfig } from '../hosts/index'; @@ -91,9 +92,11 @@ let HOST: Host = HOST_ARG_VAL === 'all' ? 'claude' : HOST_ARG_VAL; // ─── Model Overlay Selection ──────────────────────────────── // --model is explicit. We do NOT auto-detect from host (host ≠ model). -// Default is 'claude'. Missing overlay file → empty string (graceful). +// Default is 'claude' for most hosts. Grok Build suppresses the Claude +// model overlay body unless --model is passed explicitly (U3 / KTD6). import { ALL_MODEL_NAMES, resolveModel, type Model } from './models'; const MODEL_ARG = process.argv.find(a => a.startsWith('--model')); +const MODEL_EXPLICIT = !!MODEL_ARG; const MODEL_ARG_VAL: Model = (() => { if (!MODEL_ARG) return 'claude'; const val = MODEL_ARG.includes('=') ? MODEL_ARG.split('=')[1] : process.argv[process.argv.indexOf(MODEL_ARG) + 1]; @@ -732,9 +735,12 @@ function buildContext( const preambleTier = tierMatch ? parseInt(tierMatch[1], 10) : undefined; const interactiveMatch = tmplContent.match(/^interactive:\s*(true|false)\s*$/m); const interactive = interactiveMatch ? interactiveMatch[1] === 'true' : undefined; + // Grok-native packaging: no Claude MODEL_OVERLAY section unless user forced --model + const modelForHost: Model | undefined = + host === 'grok-build' && !MODEL_EXPLICIT ? undefined : MODEL_ARG_VAL; return { skillName, tmplPath, benefitsFrom, host, paths: HOST_PATHS[host], - preambleTier, model: MODEL_ARG_VAL, interactive, explainLevel: EXPLAIN_LEVEL, + preambleTier, model: modelForHost, interactive, explainLevel: EXPLAIN_LEVEL, }; } @@ -1022,14 +1028,15 @@ for (const currentHost of hostsToRun) { } } - // ─── Section generation (v2 plan T9, Claude-first carve) ─── - // On-demand sections/*.md for carved skills. Generated for CLAUDE ONLY: - // every other host inlines section content via the {{SECTION:id}} resolver - // (keeping the full monolith skill), so they need no section files and we - // sidestep host-portable section paths until that plumbing lands. No-op for - // any skill without a sections/ dir. Mirrors the SKILL.md DRY_RUN handling so - // sections participate in the freshness gate. - for (const sec of currentHost === 'claude' ? discoverSectionTemplates(ROOT) : []) { + // ─── Section generation (v2 plan T9 carve) ─── + // On-demand sections/*.md for carved skills. + // Pointer hosts (Claude, Grok Build): emit section files next to the skill + // package; {{SECTION:id}} is a STOP-Read pointer (keeps the skeleton small). + // Inline hosts (Codex, Factory, …): {{SECTION:id}} inlines content into the + // monolith SKILL.md — no separate section files. + // No-op for any skill without a sections/ dir. Mirrors the SKILL.md DRY_RUN + // handling so sections participate in the freshness gate. + for (const sec of hostUsesSectionPointers(currentHost) ? discoverSectionTemplates(ROOT) : []) { if (currentHostConfig.generation.includeSkills?.length && !currentHostConfig.generation.includeSkills.includes(sec.skillDir)) continue; if (currentHostConfig.generation.skipSkills?.length && diff --git a/scripts/proactive-suggestions.json b/scripts/proactive-suggestions.json index d08c608533..ec7f7ab612 100644 --- a/scripts/proactive-suggestions.json +++ b/scripts/proactive-suggestions.json @@ -15,7 +15,7 @@ }, "benchmark-models": { "lead": "Cross-model benchmark for gstack skills.", - "routing": "Runs the same prompt through Claude,\nGPT (via Codex CLI), and Gemini side-by-side — compares latency, tokens, cost,\nand optionally quality via LLM judge. Answers \"which model is actually best\nfor this skill?\" with data instead of vibes. Separate from /benchmark, which\nmeasures web page performance. Use when: \"benchmark models\", \"compare models\",\n\"which model is best for X\", \"cross-model comparison\", \"model shootout\".", + "routing": "Runs the same prompt through Claude,\nGPT (via Codex CLI), Gemini, and Grok side-by-side — compares latency, tokens,\ncost, and optionally quality via LLM judge. Answers \"which model is actually\nbest for this skill?\" with data instead of vibes. Separate from /benchmark,\nwhich measures web page performance. Use when: \"benchmark models\", \"compare\nmodels\", \"which model is best for X\", \"cross-model comparison\", \"model\nshootout\".", "voice_line": "Voice triggers (speech-to-text aliases): \"compare models\", \"model shootout\", \"which model is best\"." }, "browse": { diff --git a/scripts/resolvers/browse.ts b/scripts/resolvers/browse.ts index 0f4d5dd7a7..1ffc366da9 100644 --- a/scripts/resolvers/browse.ts +++ b/scripts/resolvers/browse.ts @@ -2,12 +2,6 @@ import type { TemplateContext } from './types'; import { COMMAND_DESCRIPTIONS } from '../../browse/src/commands'; import { SNAPSHOT_FLAGS } from '../../browse/src/snapshot'; -function resolveBinaryPath(dirExpr: string, binaryName: string): string { - return dirExpr.startsWith('$') - ? `${dirExpr}/${binaryName}` - : `$HOME${dirExpr.replace(/^~/, '')}/${binaryName}`; -} - export function generateCommandReference(_ctx: TemplateContext): string { // Group commands by category const groups = new Map>(); @@ -105,14 +99,24 @@ export function generateSnapshotFlags(_ctx: TemplateContext): string { return lines.join('\n'); } +/** Resolve dist binary path: env-var hosts use $GSTACK_* (never $HOME+$GSTACK_*). */ +export function resolveDistBinary(dir: string, binary: string): string { + if (dir.startsWith('$')) { + // e.g. $GSTACK_BROWSE already points at .../browse/dist + return `${dir}/${binary}`; + } + return `$HOME${dir.replace(/^~/, '')}/${binary}`; +} + export function generateBrowseSetup(ctx: TemplateContext): string { + const globalBrowse = resolveDistBinary(ctx.paths.browseDir, 'browse'); return `## SETUP (run this check BEFORE any browse command) \`\`\`bash _ROOT=$(git rev-parse --show-toplevel 2>/dev/null) B="" [ -n "$_ROOT" ] && [ -x "$_ROOT/${ctx.paths.localSkillRoot}/browse/dist/browse" ] && B="$_ROOT/${ctx.paths.localSkillRoot}/browse/dist/browse" -[ -z "$B" ] && B="${resolveBinaryPath(ctx.paths.browseDir, 'browse')}" +[ -z "$B" ] && B="${globalBrowse}" if [ -x "$B" ]; then echo "READY: $B" else diff --git a/scripts/resolvers/design.ts b/scripts/resolvers/design.ts index c23c8cb477..36441674ba 100644 --- a/scripts/resolvers/design.ts +++ b/scripts/resolvers/design.ts @@ -1,11 +1,6 @@ import type { TemplateContext } from './types'; import { AI_SLOP_BLACKLIST, OPENAI_HARD_REJECTIONS, OPENAI_LITMUS_CHECKS } from './constants'; - -function resolveBinaryPath(dirExpr: string, binaryName: string): string { - return dirExpr.startsWith('$') - ? `${dirExpr}/${binaryName}` - : `$HOME${dirExpr.replace(/^~/, '')}/${binaryName}`; -} +import { resolveDistBinary } from './browse'; export function generateDesignReviewLite(ctx: TemplateContext): string { const litmusList = OPENAI_LITMUS_CHECKS.map((item, i) => `${i + 1}. ${item}`).join(' '); @@ -792,13 +787,15 @@ Source: [OpenAI "Designing Delightful Frontends with GPT-5.4"](https://developer } export function generateDesignSetup(ctx: TemplateContext): string { + const globalDesign = resolveDistBinary(ctx.paths.designDir, 'design'); + const globalBrowse = resolveDistBinary(ctx.paths.browseDir, 'browse'); return `## DESIGN SETUP (run this check BEFORE any design mockup command) \`\`\`bash _ROOT=$(git rev-parse --show-toplevel 2>/dev/null) D="" [ -n "$_ROOT" ] && [ -x "$_ROOT/${ctx.paths.localSkillRoot}/design/dist/design" ] && D="$_ROOT/${ctx.paths.localSkillRoot}/design/dist/design" -[ -z "$D" ] && D="${resolveBinaryPath(ctx.paths.designDir, 'design')}" +[ -z "$D" ] && D="${globalDesign}" if [ -x "$D" ]; then echo "DESIGN_READY: $D" else @@ -806,7 +803,7 @@ else fi B="" [ -n "$_ROOT" ] && [ -x "$_ROOT/${ctx.paths.localSkillRoot}/browse/dist/browse" ] && B="$_ROOT/${ctx.paths.localSkillRoot}/browse/dist/browse" -[ -z "$B" ] && B="${resolveBinaryPath(ctx.paths.browseDir, 'browse')}" +[ -z "$B" ] && B="${globalBrowse}" if [ -x "$B" ]; then echo "BROWSE_READY: $B" else @@ -837,13 +834,14 @@ data, not project files. They persist across branches, conversations, and worksp } export function generateDesignMockup(ctx: TemplateContext): string { + const globalDesign = resolveDistBinary(ctx.paths.designDir, 'design'); return `## Visual Design Exploration \`\`\`bash _ROOT=$(git rev-parse --show-toplevel 2>/dev/null) D="" [ -n "$_ROOT" ] && [ -x "$_ROOT/${ctx.paths.localSkillRoot}/design/dist/design" ] && D="$_ROOT/${ctx.paths.localSkillRoot}/design/dist/design" -[ -z "$D" ] && D="${resolveBinaryPath(ctx.paths.designDir, 'design')}" +[ -z "$D" ] && D="${globalDesign}" [ -x "$D" ] && echo "DESIGN_READY" || echo "DESIGN_NOT_AVAILABLE" \`\`\` diff --git a/scripts/resolvers/index.ts b/scripts/resolvers/index.ts index 3727d941e9..08adfe3f1b 100644 --- a/scripts/resolvers/index.ts +++ b/scripts/resolvers/index.ts @@ -37,6 +37,7 @@ import { generateTasksSectionEmit, generateTasksSectionAggregate } from './tasks import { SECTION, SECTION_INDEX } from './sections'; import { generateRedactTaxonomyTable, generateRedactInvocationBlock } from './redact-doc'; import { generateAutoplanOutsideVoiceBlock, generateAutoplanOutsideVoicePreflight } from './autoplan'; +import { generateSpecSpawn, generateSpecExecuteFlag } from './spec-spawn'; export const RESOLVERS: Record = { SLUG_EVAL: generateSlugEval, @@ -101,6 +102,8 @@ export const RESOLVERS: Record = { MAKE_PDF_SETUP: generateMakePdfSetup, TASKS_SECTION_EMIT: generateTasksSectionEmit, TASKS_SECTION_AGGREGATE: generateTasksSectionAggregate, + SPEC_SPAWN: generateSpecSpawn, + SPEC_EXECUTE_FLAG: generateSpecExecuteFlag, SECTION, SECTION_INDEX, AUTOPLAN_OUTSIDE_VOICE_PREFLIGHT: generateAutoplanOutsideVoicePreflight, diff --git a/scripts/resolvers/make-pdf.ts b/scripts/resolvers/make-pdf.ts index c73d0bf136..be92d1509a 100644 --- a/scripts/resolvers/make-pdf.ts +++ b/scripts/resolvers/make-pdf.ts @@ -1,4 +1,5 @@ import type { TemplateContext } from './types'; +import { resolveDistBinary } from './browse'; /** * {{MAKE_PDF_SETUP}} — emits the shell preamble that resolves $P to the @@ -8,10 +9,11 @@ import type { TemplateContext } from './types'; * * Resolution order (matches src/browseClient.ts::resolveBrowseBin): * 1. Local skill root: $_ROOT/{localSkillRoot}/make-pdf/dist/pdf - * 2. Global: ~/{globalRoot}/make-pdf/dist/pdf + * 2. Global: $GSTACK_MAKE_PDF/pdf or ~/{globalRoot}/make-pdf/dist/pdf * 3. Env override (MAKE_PDF_BIN) — for contributor dev builds */ export function generateMakePdfSetup(ctx: TemplateContext): string { + const globalPdf = resolveDistBinary(ctx.paths.makePdfDir, 'pdf'); return `## MAKE-PDF SETUP (run this check BEFORE any make-pdf command) \`\`\`bash @@ -19,7 +21,7 @@ _ROOT=$(git rev-parse --show-toplevel 2>/dev/null) P="" [ -n "$MAKE_PDF_BIN" ] && [ -x "$MAKE_PDF_BIN" ] && P="$MAKE_PDF_BIN" [ -z "$P" ] && [ -n "$_ROOT" ] && [ -x "$_ROOT/${ctx.paths.localSkillRoot}/make-pdf/dist/pdf" ] && P="$_ROOT/${ctx.paths.localSkillRoot}/make-pdf/dist/pdf" -[ -z "$P" ] && P="$HOME${ctx.paths.makePdfDir.replace(/^~/, '')}/pdf" +[ -z "$P" ] && P="${globalPdf}" if [ -x "$P" ]; then echo "MAKE_PDF_READY: $P" alias _p_="$P" # shellcheck alias helper (not exported) diff --git a/scripts/resolvers/preamble/generate-preamble-bash.ts b/scripts/resolvers/preamble/generate-preamble-bash.ts index f0bc57b4bb..507fa6f10e 100644 --- a/scripts/resolvers/preamble/generate-preamble-bash.ts +++ b/scripts/resolvers/preamble/generate-preamble-bash.ts @@ -10,6 +10,7 @@ GSTACK_ROOT="$HOME/${hostConfig.globalRoot}" GSTACK_BIN="$GSTACK_ROOT/bin" GSTACK_BROWSE="$GSTACK_ROOT/browse/dist" GSTACK_DESIGN="$GSTACK_ROOT/design/dist" +GSTACK_MAKE_PDF="$GSTACK_ROOT/make-pdf/dist" ` : ''; diff --git a/scripts/resolvers/sections.ts b/scripts/resolvers/sections.ts index c6425e19b9..d2a379d44d 100644 --- a/scripts/resolvers/sections.ts +++ b/scripts/resolvers/sections.ts @@ -1,25 +1,28 @@ /** - * Section resolvers (v2 plan T9, Claude-first carve). + * Section resolvers (v2 plan T9 carve). * * A carved skill keeps its prose-heavy steps in `/sections/.md`, read * on demand. The SAME template ships to every host, so these resolvers make the * carve host-aware: * - * - On CLAUDE: {{SECTION:id}} emits a STOP-Read pointer to the generated section - * file (the skeleton), and the section .md is generated + installed separately. - * - On every OTHER host: {{SECTION:id}} INLINES the section template's content, - * so external hosts keep the full monolith ship skill (no section files, no - * host-portable-path problem). Inlined content keeps its own {{RESOLVER}} - * tokens, which the generator's multi-pass resolve expands. + * - On CLAUDE: SECTION:id emits a STOP-Read pointer to the generated section + * file under the nested monorepo install ({skillRoot}/{skill}/sections/). + * - On GROK-BUILD: same pointer mode, but paths use the flat Grok package layout + * (~/.grok/skills/gstack-{skill}/sections/). Section files are generated into + * each package's sections/ dir and ride along with package install. + * - On every OTHER host: SECTION placeholders INLINE the section template content, + * so those hosts keep the full monolith skill (no section files, no + * host-portable-path problem). Inlined content keeps its own resolver tokens, + * which the generator's multi-pass resolve expands. * - * {{SECTION_INDEX:skill}} renders the situation→section table from the PASSIVE - * manifest on Claude (empty on other hosts — they have no sections). The manifest + * SECTION_INDEX renders the situation-to-section table from the PASSIVE + * manifest on pointer hosts (empty when sections are inlined). The manifest * is the single source of id/file/title/trigger text (CM2; v2_PLAN.md:663). */ import * as fs from 'fs'; import * as path from 'path'; -import type { ResolverFn, TemplateContext } from './types'; +import type { Host, ResolverFn, TemplateContext } from './types'; const ROOT = path.resolve(import.meta.dir, '..', '..'); @@ -34,6 +37,21 @@ interface SectionManifest { sections: SectionEntry[]; } +/** Hosts that load carved sections on demand (not monolith-inline). */ +export function hostUsesSectionPointers(host: Host | string): boolean { + return host === 'claude' || host === 'grok-build'; +} + +/** + * External package dir name for flat hosts (gstack-ship, gstack-upgrade, …). + * Mirrors gen-skill-docs externalSkillName for skill dirs. + */ +export function externalSkillPackageName(skillName: string): string { + if (skillName === '.' || skillName === '' || skillName === 'gstack') return 'gstack'; + if (skillName.startsWith('gstack-')) return skillName; + return `gstack-${skillName}`; +} + function loadManifest(skill: string): SectionManifest { const p = path.join(ROOT, skill, 'sections', 'manifest.json'); const raw = fs.readFileSync(p, 'utf-8'); @@ -49,35 +67,56 @@ function findSection(skill: string, id: string): SectionEntry { } /** - * {{SECTION:id}} — pointer on Claude, inline on other hosts. - * Claude path uses the stable gstack-root install (`{skillRoot}/{skill}/sections/`), - * which always exists, instead of a naked relative path (Codex outside-voice #7). + * Absolute-style path the agent should Read for a section file. + * Claude: nested monorepo install under skillRoot. + * Grok: flat package next to the thin runtime root. + */ +export function sectionPointerPath( + host: Host | string, + skillName: string, + sectionFile: string, + skillRoot: string, +): string { + if (host === 'grok-build') { + const pkg = externalSkillPackageName(skillName); + return `~/.grok/skills/${pkg}/sections/${sectionFile}`; + } + // Claude (and any future nested-install pointer host) + return `${skillRoot}/${skillName}/sections/${sectionFile}`; +} + +function stopReadDirective(sectionPath: string, trigger: string): string { + return [ + `> **STOP.** Before ${trigger}, Read \`${sectionPath}\` and execute it`, + `> in full. Do not work from memory — that section is the source of truth for this step.`, + ].join('\n'); +} + +/** + * SECTION:id — pointer on Claude/Grok, inline on other hosts. */ export const SECTION: ResolverFn = (ctx: TemplateContext, args?: string[]): string => { const id = args?.[0]; if (!id) throw new Error('{{SECTION:id}} requires a section id'); const entry = findSection(ctx.skillName, id); - if (ctx.host === 'claude') { - const sectionPath = `${ctx.paths.skillRoot}/${ctx.skillName}/sections/${entry.file}`; - return [ - `> **STOP.** Before ${entry.trigger}, Read \`${sectionPath}\` and execute it`, - `> in full. Do not work from memory — that section is the source of truth for this step.`, - ].join('\n'); + if (hostUsesSectionPointers(ctx.host)) { + const sectionPath = sectionPointerPath(ctx.host, ctx.skillName, entry.file, ctx.paths.skillRoot); + return stopReadDirective(sectionPath, entry.trigger); } - // Non-Claude hosts inline the section template content (monolith preserved). + // Non-pointer hosts inline the section template content (monolith preserved). // Inner {{RESOLVER}} tokens are expanded by the generator's multi-pass resolve. const tmplPath = path.join(ROOT, ctx.skillName, 'sections', `${entry.file}.tmpl`); return fs.readFileSync(tmplPath, 'utf-8').trimEnd(); }; /** - * {{SECTION_INDEX:skill}} — situation→section table from the passive manifest. - * Claude only; other hosts inline everything so an index would be noise. + * SECTION_INDEX — situation-to-section table from the passive manifest. + * Pointer hosts only; inline hosts have no separate section files. */ export const SECTION_INDEX: ResolverFn = (ctx: TemplateContext, args?: string[]): string => { - if (ctx.host !== 'claude') return ''; + if (!hostUsesSectionPointers(ctx.host)) return ''; const skill = args?.[0] ?? ctx.skillName; const manifest = loadManifest(skill); const lines: string[] = [ @@ -90,7 +129,11 @@ export const SECTION_INDEX: ResolverFn = (ctx: TemplateContext, args?: string[]) '|------|-------------------|', ]; for (const s of manifest.sections) { - lines.push(`| ${s.trigger} | \`sections/${s.file}\` |`); + const sectionPath = sectionPointerPath(ctx.host, skill, s.file, ctx.paths.skillRoot); + // Table shows the resolvable path (Grok: full ~/.grok/...; Claude: short sections/) + const display = + ctx.host === 'grok-build' ? `\`${sectionPath}\`` : `\`sections/${s.file}\``; + lines.push(`| ${s.trigger} | ${display} |`); } return lines.join('\n'); }; diff --git a/scripts/resolvers/spec-spawn.ts b/scripts/resolvers/spec-spawn.ts new file mode 100644 index 0000000000..5a05520335 --- /dev/null +++ b/scripts/resolvers/spec-spawn.ts @@ -0,0 +1,118 @@ +import type { TemplateContext } from './types'; + +/** + * Host-native agent spawn for /spec --execute (U4 / R3). + * + * Grok research matrix (local CLI grok 0.2.x): + * -p / --single short single-turn + * --prompt-file single-turn from file (preferred for archives) + * --cwd working directory + * --always-approve elevated auto-approve (opt-in / documented) + * Never: $(cat …) into argv (ARG_MAX); never invent --permission-mode acceptEdits. + * + * Claude host generation unchanged: stdin pipe into claude -p. + */ +export function generateSpecSpawn(ctx: TemplateContext): string { + if (ctx.host === 'grok-build') { + return `If A and worktree created: spawn **Grok** headless with the archived +spec as a prompt file (never \`$(cat …)\` into argv — ARG_MAX / quoting risk). + +**Auth gate (fail closed):** before spawn, verify Grok is available and configured: + +\`\`\`bash +command -v grok >/dev/null 2>&1 || { echo "STOP: grok CLI not on PATH. Install Grok Build, or re-run with --no-execute / --file-only."; exit 1; } +if [ ! -f "$HOME/.grok/auth.json" ] && [ -z "\${XAI_API_KEY:-}\${GROK_API_KEY:-}" ]; then + echo "STOP: Grok not authenticated (no ~/.grok/auth.json and no XAI_API_KEY/GROK_API_KEY). Log in via \`grok\`, or use --no-execute." + exit 1 +fi +# ARCHIVE_PATH must stay under SPAWN_PATH or the gstack projects allowlist (fail closed). +if [ ! -f "$ARCHIVE_PATH" ]; then + echo "STOP: ARCHIVE_PATH missing: $ARCHIVE_PATH"; exit 1 +fi +if command -v realpath >/dev/null 2>&1; then + ARCHIVE_REAL=$(realpath "$ARCHIVE_PATH") +else + ARCHIVE_REAL=$(cd "$(dirname "$ARCHIVE_PATH")" && pwd -P)/$(basename "$ARCHIVE_PATH") +fi +SPAWN_REAL=$(cd "$SPAWN_PATH" 2>/dev/null && pwd -P || echo "") +if [ -z "$SPAWN_REAL" ]; then + echo "STOP: SPAWN_PATH is not a real directory: $SPAWN_PATH"; exit 1 +fi +STATE_PROJECTS="\${GSTACK_STATE_ROOT:-\$HOME/.gstack}/projects" +case "$ARCHIVE_REAL" in + "$STATE_PROJECTS"/*|"$SPAWN_REAL"/*) ;; # allowlisted + *) + echo "STOP: ARCHIVE_PATH realpath not under SPAWN_PATH or allowlisted archive dir ($STATE_PROJECTS)."; exit 1 + ;; +esac +\`\`\` + +**Security:** default spawn does **not** pass \`--always-approve\` (elevated +auto-approve). Only spawn after the user confirmed the D16 gate. If the user +explicitly opts into unattended tool use, append \`--always-approve\` to the +command below — never enable it by default. Spec archives must not contain +secrets. Third-party note: archive body is sent to xAI for processing. + +\`\`\`bash +# Prefer --prompt-file (researched). Elevated --always-approve is opt-in only. +(cd "$SPAWN_PATH" && grok --prompt-file "$ARCHIVE_PATH" --cwd "$SPAWN_PATH" 2>&1) & +SPAWN_PID=$! +echo "Spawned: PID $SPAWN_PID in $SPAWN_PATH (branch $SPAWN_BRANCH)" +echo "Follow with: cd $SPAWN_PATH && grok --continue" +\`\`\` + +**Optional Claude execute:** if the user asked for \`--execute-claude\` instead of +default Grok execute, and \`claude\` is on PATH, you may spawn — only after the +same ARCHIVE_PATH allowlist gate as the Grok path (reuse the block above; never +pipe an unallowlisted archive): + +\`\`\`bash +# Re-run allowlist (same fail-closed rules as Grok path) before cat|claude. +if [ ! -f "$ARCHIVE_PATH" ]; then + echo "STOP: ARCHIVE_PATH missing: $ARCHIVE_PATH"; exit 1 +fi +if command -v realpath >/dev/null 2>&1; then + ARCHIVE_REAL=$(realpath "$ARCHIVE_PATH") +else + ARCHIVE_REAL=$(cd "$(dirname "$ARCHIVE_PATH")" && pwd -P)/$(basename "$ARCHIVE_PATH") +fi +SPAWN_REAL=$(cd "$SPAWN_PATH" 2>/dev/null && pwd -P || echo "") +if [ -z "$SPAWN_REAL" ]; then + echo "STOP: SPAWN_PATH is not a real directory: $SPAWN_PATH"; exit 1 +fi +STATE_PROJECTS="\${GSTACK_STATE_ROOT:-\$HOME/.gstack}/projects" +case "$ARCHIVE_REAL" in + "$STATE_PROJECTS"/*|"$SPAWN_REAL"/*) ;; # allowlisted + *) + echo "STOP: ARCHIVE_PATH realpath not under SPAWN_PATH or allowlisted archive dir ($STATE_PROJECTS)."; exit 1 + ;; +esac +cat "$ARCHIVE_PATH" | (cd "$SPAWN_PATH" && claude -p 2>&1) & +\`\`\` + +Do **not** silently fall through to Claude when Grok is missing — STOP instead. + +If no safe multi-line file ingest is available on an older Grok CLI (no +\`--prompt-file\`), demote to \`--no-execute\` / file-only and tell the user: +"This Grok CLI lacks --prompt-file; filed the issue only. Upgrade Grok Build or +use --execute-claude if Claude is installed."`; + } + + // Claude + all other hosts: classic claude -p stdin pipe + return `If A and worktree created: spawn \`claude -p\` with the spec piped via stdin: + +\`\`\`bash +cat "$ARCHIVE_PATH" | (cd "$SPAWN_PATH" && claude -p 2>&1) & +SPAWN_PID=$! +echo "Spawned: PID $SPAWN_PID in $SPAWN_PATH (branch $SPAWN_BRANCH)" +echo "Follow with: cd $SPAWN_PATH && claude --resume" +\`\`\``; +} + +/** Flag-table row for --execute (host-aware description). */ +export function generateSpecExecuteFlag(ctx: TemplateContext): string { + if (ctx.host === 'grok-build') { + return '| `--execute` | conditional default (see Phase 5) | Spawn `grok --prompt-file` headless in a fresh worktree after filing the issue. |'; + } + return '| `--execute` | conditional default (see Phase 5) | Spawn `claude -p` in a fresh worktree after filing the issue. |'; +} diff --git a/setup b/setup index 0a2305c5e8..32e55389df 100755 --- a/setup +++ b/setup @@ -30,6 +30,8 @@ SLATE_SKILLS="$HOME/.slate/skills" SLATE_GSTACK="$SLATE_SKILLS/gstack" QODER_SKILLS="$HOME/.lingma/skills" QODER_GSTACK="$QODER_SKILLS/gstack" +GROK_SKILLS="$HOME/.grok/skills" +GROK_GSTACK="$GROK_SKILLS/gstack" IS_WINDOWS=0 case "$(uname -s)" in @@ -91,7 +93,7 @@ NO_TEAM_MODE=0 PLAN_TUNE_HOOKS_MODE="" # "" = resolve from env/config/prompt; "yes"/"no" = explicit while [ $# -gt 0 ]; do case "$1" in - --host) [ -z "$2" ] && echo "Missing value for --host (expected claude, codex, kiro, factory, opencode, cursor, slate, qoder, openclaw, hermes, gbrain, or auto)" >&2 && exit 1; HOST="$2"; shift 2 ;; + --host) [ -z "$2" ] && echo "Missing value for --host (expected claude, codex, kiro, factory, opencode, cursor, slate, qoder, grok-build, grok, openclaw, hermes, gbrain, or auto)" >&2 && exit 1; HOST="$2"; shift 2 ;; --host=*) HOST="${1#--host=}"; shift ;; --local) LOCAL_INSTALL=1; shift ;; --prefix) SKILL_PREFIX=1; SKILL_PREFIX_FLAG=1; shift ;; @@ -106,8 +108,11 @@ while [ $# -gt 0 ]; do esac done +# Alias: --host grok → grok-build +if [ "$HOST" = "grok" ]; then HOST="grok-build"; fi + case "$HOST" in - claude|codex|kiro|factory|opencode|cursor|slate|qoder|auto) ;; + claude|codex|kiro|factory|opencode|cursor|slate|qoder|grok-build|auto) ;; openclaw) echo "" echo "OpenClaw integration uses a different model — OpenClaw spawns Claude Code" @@ -189,7 +194,7 @@ case "$HOST" in echo "GBrain setup and brain skills ship from the GBrain repo." echo "" exit 0 ;; - *) echo "Unknown --host value: $HOST (expected claude, codex, kiro, factory, opencode, cursor, slate, qoder, openclaw, hermes, gbrain, or auto)" >&2; exit 1 ;; + *) echo "Unknown --host value: $HOST (expected claude, codex, kiro, factory, opencode, cursor, slate, qoder, grok-build, grok, openclaw, hermes, gbrain, or auto)" >&2; exit 1 ;; esac # ─── Resolve skill prefix preference ───────────────────────── @@ -256,6 +261,7 @@ INSTALL_OPENCODE=0 INSTALL_CURSOR=0 INSTALL_SLATE=0 INSTALL_QODER=0 +INSTALL_GROK=0 if [ "$HOST" = "auto" ]; then command -v claude >/dev/null 2>&1 && INSTALL_CLAUDE=1 command -v codex >/dev/null 2>&1 && INSTALL_CODEX=1 @@ -265,8 +271,9 @@ if [ "$HOST" = "auto" ]; then command -v cursor >/dev/null 2>&1 && INSTALL_CURSOR=1 command -v slate >/dev/null 2>&1 && INSTALL_SLATE=1 command -v qoder >/dev/null 2>&1 && INSTALL_QODER=1 + command -v grok >/dev/null 2>&1 && INSTALL_GROK=1 # If none found, default to claude - if [ "$INSTALL_CLAUDE" -eq 0 ] && [ "$INSTALL_CODEX" -eq 0 ] && [ "$INSTALL_KIRO" -eq 0 ] && [ "$INSTALL_FACTORY" -eq 0 ] && [ "$INSTALL_OPENCODE" -eq 0 ] && [ "$INSTALL_CURSOR" -eq 0 ] && [ "$INSTALL_SLATE" -eq 0 ] && [ "$INSTALL_QODER" -eq 0 ]; then + if [ "$INSTALL_CLAUDE" -eq 0 ] && [ "$INSTALL_CODEX" -eq 0 ] && [ "$INSTALL_KIRO" -eq 0 ] && [ "$INSTALL_FACTORY" -eq 0 ] && [ "$INSTALL_OPENCODE" -eq 0 ] && [ "$INSTALL_CURSOR" -eq 0 ] && [ "$INSTALL_SLATE" -eq 0 ] && [ "$INSTALL_QODER" -eq 0 ] && [ "$INSTALL_GROK" -eq 0 ]; then INSTALL_CLAUDE=1 fi elif [ "$HOST" = "claude" ]; then @@ -285,6 +292,8 @@ elif [ "$HOST" = "slate" ]; then INSTALL_SLATE=1 elif [ "$HOST" = "qoder" ]; then INSTALL_QODER=1 +elif [ "$HOST" = "grok-build" ]; then + INSTALL_GROK=1 fi migrate_direct_codex_install() { @@ -503,16 +512,13 @@ if [ ! -x "$BROWSE_BIN" ]; then exit 1 fi -# 1b. Generate .agents/ Codex skill docs — always regenerate to prevent stale descriptions. +# 1b. Generate .agents/ Codex skill docs — only when installing for Codex. # .agents/ is no longer committed — generated at setup time from .tmpl templates. # bun run build already does this, but we need it when NEEDS_BUILD=0 (binary is fresh). -# Always regenerate: generation is fast (<2s) and mtime-based staleness checks are fragile -# (miss stale files when timestamps match after clone/checkout/upgrade). -AGENTS_DIR="$SOURCE_GSTACK_DIR/.agents/skills" -NEEDS_AGENTS_GEN=1 - -if [ "$NEEDS_AGENTS_GEN" -eq 1 ] && [ "$NEEDS_BUILD" -eq 0 ]; then - log "Generating .agents/ skill docs..." +# Host-scoped: --host grok-build / claude / factory / etc. must not pay Codex regen cost +# or imply a Codex install is in progress. +if [ "$INSTALL_CODEX" -eq 1 ] && [ "$NEEDS_BUILD" -eq 0 ]; then + log "Generating .agents/ skill docs for Codex..." ( cd "$SOURCE_GSTACK_DIR" bun_cmd install --frozen-lockfile 2>/dev/null || bun_cmd install @@ -560,6 +566,16 @@ if [ "$INSTALL_SLATE" -eq 1 ] && [ "$NEEDS_BUILD" -eq 0 ]; then ) fi +# 1g. Generate .grok/ Grok Build skill docs +if [ "$INSTALL_GROK" -eq 1 ] && [ "$NEEDS_BUILD" -eq 0 ]; then + log "Generating .grok/ skill docs for Grok Build..." + ( + cd "$SOURCE_GSTACK_DIR" + bun_cmd install --frozen-lockfile 2>/dev/null || bun_cmd install + bun_cmd run gen:skill-docs --host grok-build + ) +fi + # 2. Ensure Playwright's Chromium is available if ! ensure_playwright_browser; then echo "Installing Playwright Chromium..." @@ -1314,6 +1330,247 @@ link_qoder_skill_dirs() { fi } +# ─── Grok Build (xAI) runtime root + skill links ─────────────────────────── +# Grok discovers skills from ~/.grok/skills//SKILL.md. +# Generated packages live in /.grok/skills/gstack-* (path-rewritten). +# Runtime assets (bin, browse, design, specialists, …) live at ~/.grok/skills/gstack. +# +# Security: every required link target must realpath under monorepo install root. +# Dual-write with hosts/grok-build.ts runtimeRoot — keep lists in sync (R1 / U1). +_grok_link_under_monorepo() { + local monorepo_root="$1" + local src="$2" + local dst="$3" + local required="${4:-0}" # 1 = fail closed if missing when expected + + if [ ! -e "$src" ]; then + if [ "$required" = "1" ]; then + echo "error: required Grok runtime asset missing: $src" >&2 + echo " monorepo root: $monorepo_root" >&2 + echo " Re-run from a full gstack checkout after builds complete." >&2 + return 1 + fi + return 0 + fi + + local src_real monorepo_real + monorepo_real=$(cd "$monorepo_root" 2>/dev/null && pwd -P) + # Fail closed: empty monorepo_real makes "$monorepo_real"/* expand to /* and + # match every absolute path — never allow that. + if [ -z "$monorepo_real" ] || [ ! -d "$monorepo_real" ]; then + echo "error: refusing Grok runtime link — monorepo root unresolved: $monorepo_root" >&2 + return 1 + fi + # Prefer full realpath when available so a final-component symlink cannot escape. + if command -v realpath >/dev/null 2>&1; then + src_real=$(realpath "$src" 2>/dev/null) || src_real="" + else + src_real=$(cd "$(dirname "$src")" 2>/dev/null && pwd -P)/$(basename "$src") + fi + if [ -z "$src_real" ]; then + echo "error: refusing Grok runtime link — cannot realpath src: $src" >&2 + return 1 + fi + case "$src_real" in + "$monorepo_real"|"$monorepo_real"/*) ;; + *) + echo "error: refusing Grok runtime link outside monorepo:" >&2 + echo " src=$src_real" >&2 + echo " monorepo=$monorepo_real" >&2 + return 1 + ;; + esac + + _link_or_copy "$src" "$dst" +} + +create_grok_runtime_root() { + local gstack_dir="$1" + local grok_gstack="$2" + local generated_root="$gstack_dir/.grok/skills/gstack" + local staging="" + local req + + # Preflight required monorepo assets BEFORE wiping the live install. + # Without this, a mid-install failure under set -e leaves an empty/half tree + # after rm -rf (review finding #6). + for req in bin browse/dist browse/src scripts review/specialists; do + if [ ! -e "$gstack_dir/$req" ]; then + echo "error: preflight — required monorepo asset missing: $gstack_dir/$req" >&2 + echo " Run a full monorepo build (./setup or bun run build) before installing Grok runtime." >&2 + return 1 + fi + done + # Core review files audited by gstack-grok-compat-audit — fail closed when monorepo has review/ + if [ -d "$gstack_dir/review" ]; then + for req in checklist.md TODOS-format.md; do + if [ ! -f "$gstack_dir/review/$req" ]; then + echo "error: preflight — core review file missing: $gstack_dir/review/$req" >&2 + return 1 + fi + done + fi + # design/dist required when monorepo ships the design package + if [ -d "$gstack_dir/design" ] && [ ! -d "$gstack_dir/design/dist" ]; then + echo "error: preflight — monorepo has design/ but design/dist is missing — run design build" >&2 + return 1 + fi + + # Stage into a sibling .next tree, then atomic rename into place so a partial + # link failure never leaves the live ~/.grok/skills/gstack empty. + staging="${grok_gstack}.next.$$" + rm -rf "$staging" + mkdir -p "$staging" \ + "$staging/browse" \ + "$staging/design" \ + "$staging/make-pdf" \ + "$staging/gstack-upgrade" \ + "$staging/review" || return 1 + + # Cleanup staging on any failure from here until atomic swap + # shellcheck disable=SC2064 + trap 'rm -rf "$staging"' RETURN + + if [ -f "$generated_root/SKILL.md" ]; then + _link_or_copy "$generated_root/SKILL.md" "$staging/SKILL.md" + elif [ -f "$gstack_dir/SKILL.md" ]; then + _link_or_copy "$gstack_dir/SKILL.md" "$staging/SKILL.md" + fi + + # Required core assets (fail closed) — dual-write with hosts/grok-build.ts runtimeRoot + _grok_link_under_monorepo "$gstack_dir" "$gstack_dir/bin" "$staging/bin" 1 || return 1 + _grok_link_under_monorepo "$gstack_dir" "$gstack_dir/browse/dist" "$staging/browse/dist" 1 || return 1 + if [ -d "$gstack_dir/browse/bin" ]; then + _grok_link_under_monorepo "$gstack_dir" "$gstack_dir/browse/bin" "$staging/browse/bin" 0 || return 1 + fi + _grok_link_under_monorepo "$gstack_dir" "$gstack_dir/browse/src" "$staging/browse/src" 1 || return 1 + + if [ -d "$gstack_dir/design/dist" ]; then + _grok_link_under_monorepo "$gstack_dir" "$gstack_dir/design/dist" "$staging/design/dist" 1 || return 1 + fi + + # make-pdf/dist — link when present (membership skill) + if [ -d "$gstack_dir/make-pdf/dist" ]; then + _grok_link_under_monorepo "$gstack_dir" "$gstack_dir/make-pdf/dist" "$staging/make-pdf/dist" 0 || return 1 + fi + + # extension/ — required when monorepo has it + if [ -d "$gstack_dir/extension" ]; then + _grok_link_under_monorepo "$gstack_dir" "$gstack_dir/extension" "$staging/extension" 1 || return 1 + fi + + _grok_link_under_monorepo "$gstack_dir" "$gstack_dir/scripts" "$staging/scripts" 1 || return 1 + + # Core review files — required=1 so install policy matches gstack-grok-compat-audit (#7) + for f in checklist.md TODOS-format.md; do + _grok_link_under_monorepo "$gstack_dir" "$gstack_dir/review/$f" "$staging/review/$f" 1 || return 1 + done + # Optional review assets (soft when monorepo lacks them) + for f in design-checklist.md greptile-triage.md; do + if [ -f "$gstack_dir/review/$f" ]; then + _grok_link_under_monorepo "$gstack_dir" "$gstack_dir/review/$f" "$staging/review/$f" 0 || return 1 + fi + done + _grok_link_under_monorepo "$gstack_dir" "$gstack_dir/review/specialists" "$staging/review/specialists" 1 || return 1 + + if [ -f "$gstack_dir/gstack-upgrade/SKILL.md" ] || [ -f "$gstack_dir/.grok/skills/gstack-upgrade/SKILL.md" ]; then + if [ -f "$gstack_dir/.grok/skills/gstack-upgrade/SKILL.md" ]; then + _link_or_copy "$gstack_dir/.grok/skills/gstack-upgrade/SKILL.md" "$staging/gstack-upgrade/SKILL.md" + else + _link_or_copy "$gstack_dir/gstack-upgrade/SKILL.md" "$staging/gstack-upgrade/SKILL.md" + fi + fi + if [ -f "$gstack_dir/ETHOS.md" ]; then + _grok_link_under_monorepo "$gstack_dir" "$gstack_dir/ETHOS.md" "$staging/ETHOS.md" 0 || return 1 + fi + + # Atomic swap: only wipe live install after staging is fully linked + trap - RETURN + if [ -L "$grok_gstack" ]; then + rm -f "$grok_gstack" + elif [ -d "$grok_gstack" ] && [ "$grok_gstack" != "$gstack_dir" ]; then + rm -rf "$grok_gstack" + fi + # Prefer rename; fall back to mv -T when available for non-empty dest edge cases + if ! mv "$staging" "$grok_gstack" 2>/dev/null; then + echo "error: failed to promote staged Grok runtime root to $grok_gstack" >&2 + rm -rf "$staging" + return 1 + fi +} + +link_grok_skill_dirs() { + local gstack_dir="$1" + local skills_dir="$2" + local grok_dir="$gstack_dir/.grok/skills" + local linked=() + + if [ ! -d "$grok_dir" ]; then + echo " Generating .grok/ skill docs..." + ( cd "$gstack_dir" && bun run gen:skill-docs --host grok-build ) + fi + + if [ ! -d "$grok_dir" ]; then + echo " warning: .grok/skills/ generation failed — run 'bun run gen:skill-docs --host grok-build' manually" >&2 + return 1 + fi + + mkdir -p "$skills_dir" + + for skill_dir in "$grok_dir"/gstack*/; do + if [ -f "$skill_dir/SKILL.md" ]; then + skill_name="$(basename "$skill_dir")" + # Runtime root is installed separately as ~/.grok/skills/gstack + [ "$skill_name" = "gstack" ] && continue + target="$skills_dir/$skill_name" + # Replace stale monorepo flat symlinks (browse → ~/gstack/browse) with generated packages + if [ -L "$target" ] || [ ! -e "$target" ]; then + _link_or_copy "$skill_dir" "$target" + linked+=("$skill_name") + elif [ -d "$target" ] && [ ! -f "$target/SKILL.md" ]; then + rm -rf "$target" + _link_or_copy "$skill_dir" "$target" + linked+=("$skill_name") + else + # Force refresh: generated content is authoritative for this host + rm -rf "$target" + _link_or_copy "$skill_dir" "$target" + linked+=("$skill_name") + fi + + # Also expose unprefixed alias (browse) so slash names match frontmatter + # without depending on Grok's name: field alone. + # Deny bare `codex` alias (OpenAI plugin owns /codex); optional gstack-codex only. + bare_name="${skill_name#gstack-}" + if [ -n "$bare_name" ] && [ "$bare_name" != "$skill_name" ] && [ "$bare_name" != "codex" ]; then + bare_target="$skills_dir/$bare_name" + # Only alias if missing or already a symlink (don't clobber real non-gstack skills) + if [ -L "$bare_target" ] || [ ! -e "$bare_target" ]; then + _link_or_copy "$skill_dir" "$bare_target" + fi + fi + fi + done + + # Backwards-compat alias: /connect-chrome → generated open-gstack-browser (U2 / KTD7) + # Force-refresh stale monorepo targets that pointed at source tree packages. + local _ogb_src="" + if [ -d "$skills_dir/gstack-open-gstack-browser" ]; then + _ogb_src="$skills_dir/gstack-open-gstack-browser" + elif [ -d "$grok_dir/gstack-open-gstack-browser" ]; then + _ogb_src="$grok_dir/gstack-open-gstack-browser" + fi + if [ -n "$_ogb_src" ]; then + rm -rf "$skills_dir/connect-chrome" + _link_or_copy "$_ogb_src" "$skills_dir/connect-chrome" + linked+=("connect-chrome→open-gstack-browser") + fi + + if [ ${#linked[@]} -gt 0 ]; then + echo " linked skills: ${linked[*]}" + fi +} + # 4. Install for Claude (default) SKILLS_BASENAME="$(basename "$INSTALL_SKILLS_DIR")" SKILLS_PARENT_BASENAME="$(basename "$(dirname "$INSTALL_SKILLS_DIR")")" @@ -1576,6 +1833,17 @@ if [ "$INSTALL_QODER" -eq 1 ]; then echo " qoder skills: $QODER_SKILLS" fi +# 6g. Install for Grok Build (xAI) +if [ "$INSTALL_GROK" -eq 1 ]; then + mkdir -p "$GROK_SKILLS" + create_grok_runtime_root "$SOURCE_GSTACK_DIR" "$GROK_GSTACK" + link_grok_skill_dirs "$SOURCE_GSTACK_DIR" "$GROK_SKILLS" + echo "gstack ready (grok-build)." + echo " browse: $BROWSE_BIN" + echo " grok skills: $GROK_SKILLS" + echo " runtime root: $GROK_GSTACK" +fi + # 7. Create .agents/ sidecar symlinks for the real Codex skill target. # The root Codex skill ends up pointing at $SOURCE_GSTACK_DIR/.agents/skills/gstack, # so the runtime assets must live there for both global and repo-local installs. @@ -1720,6 +1988,10 @@ fi # something at runtime instead of being agent-convention. Explicit consent UX # per D4 + Codex: never mutate settings.json silently. # +# Host-scoped: these hooks only affect Claude Code. Skip the prompt entirely for +# non-Claude host installs (e.g. --host grok-build) unless the user explicitly +# passed --plan-tune-hooks. Grok /plan-tune still works via skill-text path. +# # Idempotent via _gstack_source tag = 'plan-tune-cathedral'. If both hooks # already registered under that tag, the install is a no-op (no prompt). PLAN_TUNE_LOG_HOOK="$SOURCE_GSTACK_DIR/hosts/claude/hooks/question-log-hook" @@ -1727,7 +1999,14 @@ PLAN_TUNE_PREF_HOOK="$SOURCE_GSTACK_DIR/hosts/claude/hooks/question-preference-h AUQ_ERROR_FALLBACK_HOOK="$SOURCE_GSTACK_DIR/hosts/claude/hooks/auq-error-fallback-hook" PLAN_TUNE_INSTALL_MARKER="$HOME/.gstack/.plan-tune-hooks-prompted" +# Explicit --plan-tune-hooks still allowed from any host install (user intent). +_PT_EXPLICIT_YES=0 +case "$(printf '%s' "${PLAN_TUNE_HOOKS_MODE:-}" | tr '[:upper:]' '[:lower:]' | tr -d '[:space:]')" in + y|yes|true|install|on|1) _PT_EXPLICIT_YES=1 ;; +esac + if [ "$NO_TEAM_MODE" -ne 1 ] \ + && { [ "$INSTALL_CLAUDE" -eq 1 ] || [ "$_PT_EXPLICIT_YES" -eq 1 ]; } \ && [ -x "$SETTINGS_HOOK" ] \ && [ -x "$PLAN_TUNE_LOG_HOOK" ] \ && [ -x "$PLAN_TUNE_PREF_HOOK" ]; then diff --git a/setup-gbrain/SKILL.md b/setup-gbrain/SKILL.md index 89c2ffbc37..ca4777e7c8 100644 --- a/setup-gbrain/SKILL.md +++ b/setup-gbrain/SKILL.md @@ -788,8 +788,22 @@ Claude Code) can call it as both a CLI and an MCP tool. **Scope honesty:** This skill's MCP registration step (5a) uses `claude mcp add` and targets Claude Code specifically. Other local hosts -(Cursor, Codex CLI, etc.) will still get the gbrain CLI on PATH — they can -register `gbrain serve` in their own MCP config manually after setup. +(Cursor, Codex CLI, **Grok Build**, etc.) will still get the gbrain CLI on +PATH — they can register `gbrain serve` in their own MCP config manually +after setup. + +**Grok Build success path (no Claude required):** setup is **COMPATIBLE** when +(1) `gbrain` is on PATH, (2) the engine is healthy (`gbrain doctor`), and +(3) AGENTS.md (or project docs) carry gbrain guidance via `/sync-gbrain`. +Claude MCP registration is optional. Never mark setup FAILED only because +`claude` is missing. Optional Grok MCP into `~/.grok/config.toml` is a stretch +(absolute path, structured TOML RMW, gbrain stanza only, atomic write + +backup; non-interactive refuses non-equivalent overwrite unless `--force` or +a real TTY confirm). + +**Bridge policy:** install prose alone does not green the primary path when +the CLI is missing — detect/install guidance may be READY; overall bridge is +DEPENDENT until `gbrain` is present. **Audience:** local-Mac users. openclaw/hermes agents typically run in cloud docker containers with their own gbrain; "sharing" a brain between them and @@ -1258,9 +1272,14 @@ doctor output and STOP. --- -## Step 5a: Register gbrain as Claude Code MCP (D18) +## Step 5a: Register gbrain as Claude Code MCP (D18) — optional -Only if `which claude` resolves. Ask: "Give Claude Code a typed tool surface +Only if `which claude` resolves. If `claude` is **not** on PATH (typical on +Grok-only machines): emit "MCP registration skipped — Claude Code not present. +Grok/other hosts succeed via CLI + AGENTS.md; register `gbrain serve` in host +MCP config only if desired." Continue to step 6 — **do not fail setup**. + +If `claude` is present, ask: "Give Claude Code a typed tool surface for gbrain? (recommended yes)" The registration form depends on the path picked in Step 2: diff --git a/setup-gbrain/SKILL.md.tmpl b/setup-gbrain/SKILL.md.tmpl index f48581543b..f785154660 100644 --- a/setup-gbrain/SKILL.md.tmpl +++ b/setup-gbrain/SKILL.md.tmpl @@ -34,8 +34,22 @@ Claude Code) can call it as both a CLI and an MCP tool. **Scope honesty:** This skill's MCP registration step (5a) uses `claude mcp add` and targets Claude Code specifically. Other local hosts -(Cursor, Codex CLI, etc.) will still get the gbrain CLI on PATH — they can -register `gbrain serve` in their own MCP config manually after setup. +(Cursor, Codex CLI, **Grok Build**, etc.) will still get the gbrain CLI on +PATH — they can register `gbrain serve` in their own MCP config manually +after setup. + +**Grok Build success path (no Claude required):** setup is **COMPATIBLE** when +(1) `gbrain` is on PATH, (2) the engine is healthy (`gbrain doctor`), and +(3) AGENTS.md (or project docs) carry gbrain guidance via `/sync-gbrain`. +Claude MCP registration is optional. Never mark setup FAILED only because +`claude` is missing. Optional Grok MCP into `~/.grok/config.toml` is a stretch +(absolute path, structured TOML RMW, gbrain stanza only, atomic write + +backup; non-interactive refuses non-equivalent overwrite unless `--force` or +a real TTY confirm). + +**Bridge policy:** install prose alone does not green the primary path when +the CLI is missing — detect/install guidance may be READY; overall bridge is +DEPENDENT until `gbrain` is present. **Audience:** local-Mac users. openclaw/hermes agents typically run in cloud docker containers with their own gbrain; "sharing" a brain between them and @@ -504,9 +518,14 @@ doctor output and STOP. --- -## Step 5a: Register gbrain as Claude Code MCP (D18) +## Step 5a: Register gbrain as Claude Code MCP (D18) — optional -Only if `which claude` resolves. Ask: "Give Claude Code a typed tool surface +Only if `which claude` resolves. If `claude` is **not** on PATH (typical on +Grok-only machines): emit "MCP registration skipped — Claude Code not present. +Grok/other hosts succeed via CLI + AGENTS.md; register `gbrain serve` in host +MCP config only if desired." Continue to step 6 — **do not fail setup**. + +If `claude` is present, ask: "Give Claude Code a typed tool surface for gbrain? (recommended yes)" The registration form depends on the path picked in Step 2: diff --git a/spec/SKILL.md.tmpl b/spec/SKILL.md.tmpl index 6c0c14e1b3..e7d5991f7c 100644 --- a/spec/SKILL.md.tmpl +++ b/spec/SKILL.md.tmpl @@ -60,7 +60,7 @@ separated tokens starting with `--`. Last flag wins on conflict. | `--no-dedupe` | — | Skip the dedupe check. | | `--no-gate` | OFF (gate is ON) | Skip the codex quality-score gate between Phase 4 and Phase 5. **Redaction (Phase 4.5a semantic + 4.5b regex) still runs — there is no flag that disables it.** | | `--audit` | OFF | Route Phase 5 to the Audit/Cleanup template (instead of Standard). | -| `--execute` | conditional default (see Phase 5) | Spawn `claude -p` in a fresh worktree after filing the issue. | +{{SPEC_EXECUTE_FLAG}} | `--no-execute` | — | File issue only; do NOT spawn agent (alias: `--file-only`). | | `--file-only` | — | Same as `--no-execute`. | | `--plan-file ` | inferred from harness | Load the spec into the specified plan file instead of inferring. | @@ -447,14 +447,7 @@ git worktree add "$SPAWN_PATH" -b "$SPAWN_BRANCH" "$PIN_SHA" 2>&1 in-progress changes will be visible to the agent. Cancel with Ctrl+C if not desired." Then fall back to current dir (still spawn). -If A and worktree created: spawn `claude -p` with the spec piped via stdin: - -```bash -cat "$ARCHIVE_PATH" | (cd "$SPAWN_PATH" && claude -p 2>&1) & -SPAWN_PID=$! -echo "Spawned: PID $SPAWN_PID in $SPAWN_PATH (branch $SPAWN_BRANCH)" -echo "Follow with: cd $SPAWN_PATH && claude --resume" -``` +{{SPEC_SPAWN}} Update archive frontmatter with `spec_worktree_path: $SPAWN_PATH` and `spec_executed: true` (atomic re-write). diff --git a/sync-gbrain/SKILL.md b/sync-gbrain/SKILL.md index bfaf291d22..8467f5e5a9 100644 --- a/sync-gbrain/SKILL.md +++ b/sync-gbrain/SKILL.md @@ -785,8 +785,12 @@ Skills that run plan reviews (`/plan-*-review`, `/codex review`) include the EXI You are running the canonical "keep this brain up to date" verb. /setup-gbrain installs gbrain once; /sync-gbrain runs every time the user wants the brain refreshed against this repo's current state, and refreshes the agent-side -guidance in CLAUDE.md so the coding agent knows when to prefer `gbrain` -search over Grep. +guidance in CLAUDE.md / AGENTS.md so the coding agent knows when to prefer +`gbrain` search over Grep. + +**Grok Build:** success does not require Claude MCP. Require `gbrain` on PATH + +engine healthy + AGENTS.md guidance refresh. If gbrain is absent, give install +steps (DEPENDENT bridge) — do not silent-fail or demand `which claude`. **Architecture (post-codex review):** This skill uses gbrain v0.20.0+'s **native code surfaces** (`gbrain sources add`, `gbrain sync --strategy code`, diff --git a/sync-gbrain/SKILL.md.tmpl b/sync-gbrain/SKILL.md.tmpl index 2ec065472e..d3d8d6e085 100644 --- a/sync-gbrain/SKILL.md.tmpl +++ b/sync-gbrain/SKILL.md.tmpl @@ -31,8 +31,12 @@ allowed-tools: You are running the canonical "keep this brain up to date" verb. /setup-gbrain installs gbrain once; /sync-gbrain runs every time the user wants the brain refreshed against this repo's current state, and refreshes the agent-side -guidance in CLAUDE.md so the coding agent knows when to prefer `gbrain` -search over Grep. +guidance in CLAUDE.md / AGENTS.md so the coding agent knows when to prefer +`gbrain` search over Grep. + +**Grok Build:** success does not require Claude MCP. Require `gbrain` on PATH + +engine healthy + AGENTS.md guidance refresh. If gbrain is absent, give install +steps (DEPENDENT bridge) — do not silent-fail or demand `which claude`. **Architecture (post-codex review):** This skill uses gbrain v0.20.0+'s **native code surfaces** (`gbrain sources add`, `gbrain sync --strategy code`, diff --git a/test/fixtures/golden/codex-ship-SKILL.md b/test/fixtures/golden/codex-ship-SKILL.md index 6de7db72a7..e2ca477186 100644 --- a/test/fixtures/golden/codex-ship-SKILL.md +++ b/test/fixtures/golden/codex-ship-SKILL.md @@ -19,6 +19,7 @@ GSTACK_ROOT="$HOME/.agents/skills/gstack" GSTACK_BIN="$GSTACK_ROOT/bin" GSTACK_BROWSE="$GSTACK_ROOT/browse/dist" GSTACK_DESIGN="$GSTACK_ROOT/design/dist" +GSTACK_MAKE_PDF="$GSTACK_ROOT/make-pdf/dist" _UPD=$($GSTACK_BIN/gstack-update-check 2>/dev/null || .agents/skills/gstack/bin/gstack-update-check 2>/dev/null || true) [ -n "$_UPD" ] && echo "$_UPD" || true mkdir -p ~/.gstack/sessions diff --git a/test/fixtures/golden/factory-ship-SKILL.md b/test/fixtures/golden/factory-ship-SKILL.md index 87261a7939..5f2c177889 100644 --- a/test/fixtures/golden/factory-ship-SKILL.md +++ b/test/fixtures/golden/factory-ship-SKILL.md @@ -21,6 +21,7 @@ GSTACK_ROOT="$HOME/.factory/skills/gstack" GSTACK_BIN="$GSTACK_ROOT/bin" GSTACK_BROWSE="$GSTACK_ROOT/browse/dist" GSTACK_DESIGN="$GSTACK_ROOT/design/dist" +GSTACK_MAKE_PDF="$GSTACK_ROOT/make-pdf/dist" _UPD=$($GSTACK_BIN/gstack-update-check 2>/dev/null || .factory/skills/gstack/bin/gstack-update-check 2>/dev/null || true) [ -n "$_UPD" ] && echo "$_UPD" || true mkdir -p ~/.gstack/sessions diff --git a/test/fixtures/golden/grok-build-ship-SKILL.md b/test/fixtures/golden/grok-build-ship-SKILL.md new file mode 100644 index 0000000000..6de274eb75 --- /dev/null +++ b/test/fixtures/golden/grok-build-ship-SKILL.md @@ -0,0 +1,1401 @@ +--- +name: ship +description: | + Ship workflow: detect + merge base branch, run tests, review diff, bump VERSION, + update CHANGELOG, commit, push, create PR. Use when asked to "ship", "deploy", + "push to main", "create a PR", "merge and push", or "get it deployed". + Proactively invoke this skill (do NOT push/PR directly) when the user says code + is ready, asks about deploying, wants to push code up, or asks to create a PR. (gstack) +triggers: + - ship it + - create a pr + - push to main + - deploy this +allowed-tools: + - Bash + - Read + - Write + - Edit + - Grep + - Glob + - Agent + - ask_user_question + - WebSearch +--- + + + +## Preamble (run first) + +```bash +_ROOT=$(git rev-parse --show-toplevel 2>/dev/null) +GSTACK_ROOT="$HOME/.grok/skills/gstack" +[ -n "$_ROOT" ] && [ -d "$_ROOT/.grok/skills/gstack" ] && GSTACK_ROOT="$_ROOT/.grok/skills/gstack" +GSTACK_BIN="$GSTACK_ROOT/bin" +GSTACK_BROWSE="$GSTACK_ROOT/browse/dist" +GSTACK_DESIGN="$GSTACK_ROOT/design/dist" +GSTACK_MAKE_PDF="$GSTACK_ROOT/make-pdf/dist" +_UPD=$($GSTACK_BIN/gstack-update-check 2>/dev/null || .grok/skills/gstack/bin/gstack-update-check 2>/dev/null || true) +[ -n "$_UPD" ] && echo "$_UPD" || true +mkdir -p ~/.gstack/sessions +touch ~/.gstack/sessions/"$PPID" +_SESSIONS=$(find ~/.gstack/sessions -mmin -120 -type f 2>/dev/null | wc -l | tr -d ' ') +find ~/.gstack/sessions -mmin +120 -type f -exec rm {} + 2>/dev/null || true +_PROACTIVE=$($GSTACK_BIN/gstack-config get proactive 2>/dev/null || echo "true") +_PROACTIVE_PROMPTED=$([ -f ~/.gstack/.proactive-prompted ] && echo "yes" || echo "no") +_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown") +echo "BRANCH: $_BRANCH" +_SKILL_PREFIX=$($GSTACK_BIN/gstack-config get skill_prefix 2>/dev/null || echo "false") +echo "PROACTIVE: $_PROACTIVE" +echo "PROACTIVE_PROMPTED: $_PROACTIVE_PROMPTED" +echo "SKILL_PREFIX: $_SKILL_PREFIX" +source <($GSTACK_BIN/gstack-repo-mode 2>/dev/null) || true +REPO_MODE=${REPO_MODE:-unknown} +echo "REPO_MODE: $REPO_MODE" +_SESSION_KIND=$($GSTACK_BIN/gstack-session-kind 2>/dev/null || echo "interactive") +case "$_SESSION_KIND" in spawned|headless|interactive) ;; *) _SESSION_KIND="interactive" ;; esac +echo "SESSION_KIND: $_SESSION_KIND" +# Conductor host: ask_user_question is unreliable here (native disabled, MCP +# variant flaky), so skills render decisions as prose instead of calling the +# tool. Gated on !headless so an eval/CI run INSIDE Conductor (GSTACK_HEADLESS) +# still BLOCKs rather than rendering prose to nobody. +if [ "$_SESSION_KIND" != "headless" ] && { [ -n "${CONDUCTOR_WORKSPACE_PATH:-}" ] || [ -n "${CONDUCTOR_PORT:-}" ]; }; then + echo "CONDUCTOR_SESSION: true" +fi +_ACTIVATED=$([ -f ~/.gstack/.activated ] && echo "yes" || echo "no") +_FIRST_LOOP_SHOWN=$([ -f ~/.gstack/.first-loop-tip-shown ] && echo "yes" || echo "no") +echo "ACTIVATED: $_ACTIVATED" +echo "FIRST_LOOP_SHOWN: $_FIRST_LOOP_SHOWN" +# First-run project detection: run the detector ONLY on the first-ever skill run +# (ACTIVATED=no, interactive) so it stays off the hot path for every run after. +_FIRST_TASK="" +if [ "$_ACTIVATED" = "no" ] && [ "$_SESSION_KIND" != "headless" ]; then + _FIRST_TASK=$($GSTACK_BIN/gstack-first-task-detect 2>/dev/null || true) +fi +echo "FIRST_TASK: $_FIRST_TASK" +_LAKE_SEEN=$([ -f ~/.gstack/.completeness-intro-seen ] && echo "yes" || echo "no") +echo "LAKE_INTRO: $_LAKE_SEEN" +_TEL=$($GSTACK_BIN/gstack-config get telemetry 2>/dev/null || true) +_TEL_PROMPTED=$([ -f ~/.gstack/.telemetry-prompted ] && echo "yes" || echo "no") +_TEL_START=$(date +%s) +_SESSION_ID="$$-$(date +%s)" +echo "TELEMETRY: ${_TEL:-off}" +echo "TEL_PROMPTED: $_TEL_PROMPTED" +_EXPLAIN_LEVEL=$($GSTACK_BIN/gstack-config get explain_level 2>/dev/null || echo "default") +if [ "$_EXPLAIN_LEVEL" != "default" ] && [ "$_EXPLAIN_LEVEL" != "terse" ]; then _EXPLAIN_LEVEL="default"; fi +echo "EXPLAIN_LEVEL: $_EXPLAIN_LEVEL" +_QUESTION_TUNING=$($GSTACK_BIN/gstack-config get question_tuning 2>/dev/null || echo "false") +echo "QUESTION_TUNING: $_QUESTION_TUNING" +mkdir -p ~/.gstack/analytics +if [ "$_TEL" != "off" ]; then +echo '{"skill":"ship","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(_repo=$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null | tr -cd 'a-zA-Z0-9._-'); echo "${_repo:-unknown}")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true +fi +for _PF in $(find ~/.gstack/analytics -maxdepth 1 -name '.pending-*' 2>/dev/null); do + if [ -f "$_PF" ]; then + if [ "$_TEL" != "off" ] && [ -x "$GSTACK_BIN/gstack-telemetry-log" ]; then + $GSTACK_BIN/gstack-telemetry-log --event-type skill_run --skill _pending_finalize --outcome unknown --session-id "$_SESSION_ID" 2>/dev/null || true + fi + rm -f "$_PF" 2>/dev/null || true + fi + break +done +eval "$($GSTACK_BIN/gstack-slug 2>/dev/null)" 2>/dev/null || true +_LEARN_FILE="${GSTACK_HOME:-$HOME/.gstack}/projects/${SLUG:-unknown}/learnings.jsonl" +if [ -f "$_LEARN_FILE" ]; then + _LEARN_COUNT=$(wc -l < "$_LEARN_FILE" 2>/dev/null | tr -d ' ') + echo "LEARNINGS: $_LEARN_COUNT entries loaded" + if [ "$_LEARN_COUNT" -gt 5 ] 2>/dev/null; then + $GSTACK_BIN/gstack-learnings-search --limit 3 2>/dev/null || true + fi +else + echo "LEARNINGS: 0" +fi +$GSTACK_BIN/gstack-timeline-log '{"skill":"ship","event":"started","branch":"'"$_BRANCH"'","session":"'"$_SESSION_ID"'"}' 2>/dev/null & +_HAS_ROUTING="no" +if [ -f AGENTS.md ] && grep -q "## Skill routing" AGENTS.md 2>/dev/null; then + _HAS_ROUTING="yes" +fi +_ROUTING_DECLINED=$($GSTACK_BIN/gstack-config get routing_declined 2>/dev/null || echo "false") +echo "HAS_ROUTING: $_HAS_ROUTING" +echo "ROUTING_DECLINED: $_ROUTING_DECLINED" +_VENDORED="no" +if [ -d ".grok/skills/gstack" ] && [ ! -L ".grok/skills/gstack" ]; then + if [ -f ".grok/skills/gstack/VERSION" ] || [ -d ".grok/skills/gstack/.git" ]; then + _VENDORED="yes" + fi +fi +echo "VENDORED_GSTACK: $_VENDORED" +echo "MODEL_OVERLAY: none" +_CHECKPOINT_MODE=$($GSTACK_BIN/gstack-config get checkpoint_mode 2>/dev/null || echo "explicit") +_CHECKPOINT_PUSH=$($GSTACK_BIN/gstack-config get checkpoint_push 2>/dev/null || echo "false") +echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" +echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" +[ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true +``` + +## Plan Mode Safe Operations + +In plan mode, allowed because they inform the plan: `$B`, `$D`, `codex exec`/`codex review`, writes to `~/.gstack/`, writes to the plan file, and `open` for generated artifacts. + +## Skill Invocation During Plan Mode + +If the user invokes a skill in plan mode, the skill takes precedence over generic plan mode behavior. **Treat the skill file as executable instructions, not reference.** Follow it step by step starting from Step 0; the first ask_user_question is the workflow entering plan mode, not a violation of it. ask_user_question (any variant — `mcp__*__ask_user_question` or native; see "ask_user_question Format → Tool resolution") satisfies plan mode's end-of-turn requirement. If ask_user_question is unavailable or a call fails, follow the ask_user_question Format failure fallback: `headless` → BLOCKED; `interactive` → the prose fallback (also satisfies end-of-turn). At a STOP point, stop immediately. Do not continue the workflow or call exit_plan_mode there. Commands marked "PLAN MODE EXCEPTION — ALWAYS RUN" execute. Call exit_plan_mode only after the skill workflow completes, or if the user tells you to cancel the skill or leave plan mode. + +If `PROACTIVE` is `"false"`, do not auto-invoke or proactively suggest skills. If a skill seems useful, ask: "I think /skillname might help here — want me to run it?" + +If `SKILL_PREFIX` is `"true"`, suggest/invoke `/gstack-*` names. Disk paths stay `$GSTACK_ROOT/[skill-name]/SKILL.md`. + +If output shows `UPGRADE_AVAILABLE `: read `$GSTACK_ROOT/gstack-upgrade/SKILL.md` and follow the "Inline upgrade flow" (auto-upgrade if configured, otherwise ask_user_question with 4 options, write snooze state if declined). + +If output shows `JUST_UPGRADED `: print "Running gstack v{to} (just updated!)". If `SPAWNED_SESSION` is true, skip feature discovery. + +Feature discovery, max one prompt per session: +- Missing `$GSTACK_ROOT/.feature-prompted-continuous-checkpoint`: ask_user_question for Continuous checkpoint auto-commits. If accepted, run `$GSTACK_BIN/gstack-config set checkpoint_mode continuous`. Always touch marker. +- Missing `$GSTACK_ROOT/.feature-prompted-model-overlay`: inform "Model overlays are active. MODEL_OVERLAY shows the patch." Always touch marker. + +After upgrade prompts, continue workflow. + +If `WRITING_STYLE_PENDING` is `yes`: ask once about writing style: + +> v1 prompts are simpler: first-use jargon glosses, outcome-framed questions, shorter prose. Keep default or restore terse? + +Options: +- A) Keep the new default (recommended — good writing helps everyone) +- B) Restore V0 prose — set `explain_level: terse` + +If A: leave `explain_level` unset (defaults to `default`). +If B: run `$GSTACK_BIN/gstack-config set explain_level terse`. + +Always run (regardless of choice): +```bash +rm -f ~/.gstack/.writing-style-prompt-pending +touch ~/.gstack/.writing-style-prompted +``` + +Skip if `WRITING_STYLE_PENDING` is `no`. + +If `LAKE_INTRO` is `no`: say "gstack follows the **Boil the Ocean** principle — do the complete thing when AI makes marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean" Offer to open: + +```bash +open https://garryslist.org/posts/boil-the-ocean +touch ~/.gstack/.completeness-intro-seen +``` + +Only run `open` if yes. Always run `touch`. + +If `TEL_PROMPTED` is `no` AND `LAKE_INTRO` is `yes`: ask telemetry once via ask_user_question: + +> Help gstack get better. Share usage data only: skill, duration, crashes, stable device ID. No code or file paths. Your repo name is recorded locally only and stripped before any upload. + +Options: +- A) Help gstack get better! (recommended) +- B) No thanks + +If A: run `$GSTACK_BIN/gstack-config set telemetry community` + +If B: ask follow-up: + +> Anonymous mode sends only aggregate usage, no unique ID. + +Options: +- A) Sure, anonymous is fine +- B) No thanks, fully off + +If B→A: run `$GSTACK_BIN/gstack-config set telemetry anonymous` +If B→B: run `$GSTACK_BIN/gstack-config set telemetry off` + +Always run: +```bash +touch ~/.gstack/.telemetry-prompted +``` + +Skip if `TEL_PROMPTED` is `yes`. + +If `PROACTIVE_PROMPTED` is `no` AND `TEL_PROMPTED` is `yes`: ask once: + +> Let gstack proactively suggest skills, like /qa for "does this work?" or /investigate for bugs? + +Options: +- A) Keep it on (recommended) +- B) Turn it off — I'll type /commands myself + +If A: run `$GSTACK_BIN/gstack-config set proactive true` +If B: run `$GSTACK_BIN/gstack-config set proactive false` + +Always run: +```bash +touch ~/.gstack/.proactive-prompted +``` + +Skip if `PROACTIVE_PROMPTED` is `yes`. + +## First-run guidance (one-time) + +If `ACTIVATED` is `no` (first skill run on this machine) AND the preamble printed a non-empty `FIRST_TASK:` value that is NOT `nongit`: show ONE short, project-specific line mapped from the token, as a heads-up, then CONTINUE with whatever the user actually asked — do NOT halt their task. Map the token: `greenfield` → "Fresh repo — shape it first with `/spec` or `/office-hours`." `code_node`/`code_python`/`code_rust`/`code_go`/`code_ruby`/`code_ios` → "There's code here — `/qa` to see it work, or `/investigate` if something's off." `branch_ahead` → "Unshipped work on this branch — `/review` then `/ship`." `dirty_default` → "Uncommitted changes — `/review` before committing." `clean_default` → "Pick one: `/spec`, `/investigate`, or `/qa`." Then substitute the token you saw for TASK_TOKEN and run (best-effort), and mark activated: +```bash +$GSTACK_BIN/gstack-telemetry-log --event-type first_task_scaffold_shown --skill "TASK_TOKEN" --outcome shown 2>/dev/null || true +touch ~/.gstack/.activated 2>/dev/null || true +``` + +If `ACTIVATED` is `no` but `FIRST_TASK:` is empty or `nongit` (headless, non-git, or nothing actionable): show nothing, just run `touch ~/.gstack/.activated 2>/dev/null || true`. + +Else if `ACTIVATED` is `yes` AND `FIRST_LOOP_SHOWN` is `no`: say once as a heads-up (then continue): + +> Tip: gstack pays off when you complete one loop — **plan → review → ship**. A common first loop: `/office-hours` or `/spec` to shape it, `/plan-eng-review` to lock it, then `/ship`. + +Then run `touch ~/.gstack/.first-loop-tip-shown 2>/dev/null || true`. + +Skip this section if `ACTIVATED` and `FIRST_LOOP_SHOWN` are both `yes`. + +If `HAS_ROUTING` is `no` AND `ROUTING_DECLINED` is `false` AND `PROACTIVE_PROMPTED` is `yes`: +Check if a AGENTS.md file exists in the project root. If it does not exist, create it. + +Use ask_user_question: + +> gstack works best when your project's AGENTS.md includes skill routing rules. + +Options: +- A) Add routing rules to AGENTS.md (recommended) +- B) No thanks, I'll invoke skills manually + +If A: Append this section to the end of AGENTS.md: + +```markdown + +## Skill routing + +When the user's request matches an available skill, invoke it via the Skill tool. When in doubt, invoke the skill. + +Key routing rules: +- Product ideas/brainstorming → invoke /office-hours +- Strategy/scope → invoke /plan-ceo-review +- Architecture → invoke /plan-eng-review +- Design system/plan review → invoke /design-consultation or /plan-design-review +- Full review pipeline → invoke /autoplan +- Bugs/errors → invoke /investigate +- QA/testing site behavior → invoke /qa or /qa-only +- Code review/diff check → invoke /review +- Visual polish → invoke /design-review +- Ship/deploy/PR → invoke /ship or /land-and-deploy +- Save progress → invoke /context-save +- Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec +``` + +Then commit the change: `git add AGENTS.md && git commit -m "chore: add gstack skill routing rules to AGENTS.md"` + +If B: run `$GSTACK_BIN/gstack-config set routing_declined true` and say they can re-enable with `gstack-config set routing_declined false`. + +This only happens once per project. Skip if `HAS_ROUTING` is `yes` or `ROUTING_DECLINED` is `true`. + +If `VENDORED_GSTACK` is `yes`, warn once via ask_user_question unless `~/.gstack/.vendoring-warned-$SLUG` exists: + +> This project has gstack vendored in `.grok/skills/gstack/`. Vendoring is deprecated. +> Migrate to team mode? + +Options: +- A) Yes, migrate to team mode now +- B) No, I'll handle it myself + +If A: +1. Run `git rm -r .grok/skills/gstack/` +2. Run `echo '.grok/skills/gstack/' >> .gitignore` +3. Run `$GSTACK_BIN/gstack-team-init required` (or `optional`) +4. Run `git add .claude/ .gitignore AGENTS.md && git commit -m "chore: migrate gstack from vendored to team mode"` +5. Tell the user: "Done. Each developer now runs: `cd $GSTACK_ROOT && ./setup --team`" + +If B: say "OK, you're on your own to keep the vendored copy up to date." + +Always run (regardless of choice): +```bash +eval "$($GSTACK_BIN/gstack-slug 2>/dev/null)" 2>/dev/null || true +touch ~/.gstack/.vendoring-warned-${SLUG:-unknown} +``` + +If marker exists, skip. + +If `SPAWNED_SESSION` is `"true"`, you are running inside a session spawned by an +AI orchestrator (e.g., OpenClaw). In spawned sessions: +- Do NOT use ask_user_question for interactive prompts. Auto-choose the recommended option. +- Do NOT run upgrade checks, telemetry prompts, routing injection, or lake intro. +- Focus on completing the task and reporting results via prose output. +- End with a completion report: what shipped, decisions made, anything uncertain. + +## ask_user_question Format + +### Tool resolution (read first) + +"ask_user_question" can resolve to two tools at runtime: the **host MCP variant** (e.g. `mcp__conductor__ask_user_question` — appears in your tool list when the host registers it) or the **native** Claude Code tool. + +**Conductor rule (read before the MCP rule):** if `CONDUCTOR_SESSION: true` was echoed by the preamble, do NOT call ask_user_question at all — neither native nor any `mcp__*__ask_user_question` variant. Render EVERY decision brief as the **prose form** below and STOP. This is proactive, not a reaction to a failure: Conductor disables native AUQ and its MCP variant is flaky (it returns `[Tool result missing due to internal error]`), so prose is the reliable path. **Auto-decide preferences still apply first:** if a `[plan-tune auto-decide] →