diff --git a/hosts/claude.ts b/hosts/claude.ts index 7c563dcb..47470d96 100644 --- a/hosts/claude.ts +++ b/hosts/claude.ts @@ -24,7 +24,7 @@ const claude: HostConfig = { pathRewrites: [], // Claude is the primary host — no rewrites needed toolRewrites: {}, - suppressedResolvers: [], + suppressedResolvers: ['GBRAIN_CONTEXT_LOAD', 'GBRAIN_SAVE_RESULTS'], runtimeRoot: { globalSymlinks: ['bin', 'browse/dist', 'browse/bin', 'gstack-upgrade', 'ETHOS.md'], diff --git a/hosts/codex.ts b/hosts/codex.ts index cf60742f..7dc80ea8 100644 --- a/hosts/codex.ts +++ b/hosts/codex.ts @@ -37,6 +37,8 @@ const codex: HostConfig = { 'CODEX_SECOND_OPINION', // review.ts:257 — Codex can't invoke itself 'CODEX_PLAN_REVIEW', // review.ts:541 — Codex can't invoke itself 'REVIEW_ARMY', // review-army.ts:180 — Codex shouldn't orchestrate + 'GBRAIN_CONTEXT_LOAD', + 'GBRAIN_SAVE_RESULTS', ], runtimeRoot: { diff --git a/hosts/cursor.ts b/hosts/cursor.ts index 5aa38407..48e3a0f1 100644 --- a/hosts/cursor.ts +++ b/hosts/cursor.ts @@ -28,6 +28,8 @@ const cursor: HostConfig = { { from: '.claude/skills', to: '.cursor/skills' }, ], + suppressedResolvers: ['GBRAIN_CONTEXT_LOAD', 'GBRAIN_SAVE_RESULTS'], + runtimeRoot: { globalSymlinks: ['bin', 'browse/dist', 'browse/bin', 'gstack-upgrade', 'ETHOS.md'], globalFiles: { diff --git a/hosts/factory.ts b/hosts/factory.ts index b57e3426..08ac2f9a 100644 --- a/hosts/factory.ts +++ b/hosts/factory.ts @@ -43,6 +43,8 @@ const factory: HostConfig = { 'use the Glob tool': 'find files matching', }, + suppressedResolvers: ['GBRAIN_CONTEXT_LOAD', 'GBRAIN_SAVE_RESULTS'], + runtimeRoot: { globalSymlinks: ['bin', 'browse/dist', 'browse/bin', 'gstack-upgrade', 'ETHOS.md'], globalFiles: { diff --git a/hosts/kiro.ts b/hosts/kiro.ts index f79cbbca..31adc7c7 100644 --- a/hosts/kiro.ts +++ b/hosts/kiro.ts @@ -30,6 +30,8 @@ const kiro: HostConfig = { { from: '.codex/skills', to: '.kiro/skills' }, ], + suppressedResolvers: ['GBRAIN_CONTEXT_LOAD', 'GBRAIN_SAVE_RESULTS'], + runtimeRoot: { globalSymlinks: ['bin', 'browse/dist', 'browse/bin', 'gstack-upgrade', 'ETHOS.md'], globalFiles: { diff --git a/hosts/openclaw.ts b/hosts/openclaw.ts index 38428f20..f8268b5c 100644 --- a/hosts/openclaw.ts +++ b/hosts/openclaw.ts @@ -53,6 +53,8 @@ const openclaw: HostConfig = { 'CODEX_SECOND_OPINION', 'CODEX_PLAN_REVIEW', 'REVIEW_ARMY', + 'GBRAIN_CONTEXT_LOAD', + 'GBRAIN_SAVE_RESULTS', ], runtimeRoot: { @@ -69,8 +71,6 @@ const openclaw: HostConfig = { coAuthorTrailer: 'Co-Authored-By: OpenClaw Agent ', learningsMode: 'basic', - - adapter: './scripts/host-adapters/openclaw-adapter', }; export default openclaw; diff --git a/hosts/opencode.ts b/hosts/opencode.ts index de1dcbca..dc4a5bfc 100644 --- a/hosts/opencode.ts +++ b/hosts/opencode.ts @@ -28,6 +28,8 @@ const opencode: HostConfig = { { from: '.claude/skills', to: '.opencode/skills' }, ], + suppressedResolvers: ['GBRAIN_CONTEXT_LOAD', 'GBRAIN_SAVE_RESULTS'], + runtimeRoot: { globalSymlinks: ['bin', 'browse/dist', 'browse/bin', 'gstack-upgrade', 'ETHOS.md'], globalFiles: { diff --git a/hosts/slate.ts b/hosts/slate.ts index 3db9ac99..0c29cf8f 100644 --- a/hosts/slate.ts +++ b/hosts/slate.ts @@ -28,6 +28,8 @@ const slate: HostConfig = { { from: '.claude/skills', to: '.slate/skills' }, ], + suppressedResolvers: ['GBRAIN_CONTEXT_LOAD', 'GBRAIN_SAVE_RESULTS'], + runtimeRoot: { globalSymlinks: ['bin', 'browse/dist', 'browse/bin', 'gstack-upgrade', 'ETHOS.md'], globalFiles: { diff --git a/investigate/SKILL.md.tmpl b/investigate/SKILL.md.tmpl index 3004300e..07d78d1d 100644 --- a/investigate/SKILL.md.tmpl +++ b/investigate/SKILL.md.tmpl @@ -45,6 +45,8 @@ Fixing symptoms creates whack-a-mole debugging. Every fix that doesn't address r --- +{{GBRAIN_CONTEXT_LOAD}} + ## Phase 1: Root Cause Investigation Gather context before forming any hypothesis. @@ -61,6 +63,8 @@ Gather context before forming any hypothesis. 4. **Reproduce:** Can you trigger the bug deterministically? If not, gather more evidence before proceeding. +5. **Check investigation history:** Search prior learnings for investigations on the same files. Recurring bugs in the same area are an architectural smell. If prior investigations exist, note patterns and check if the root cause was structural. + {{LEARNINGS_SEARCH}} Output: **"Root cause hypothesis: ..."** — a specific, testable claim about what is wrong and why. @@ -186,8 +190,16 @@ Status: DONE | DONE_WITH_CONCERNS | BLOCKED ════════════════════════════════════════ ``` +Log the investigation as a learning for future sessions. Use `type: "investigation"` and include the affected files so future investigations on the same area can find this: + +```bash +~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"investigate","type":"investigation","key":"ROOT_CAUSE_KEY","insight":"ROOT_CAUSE_SUMMARY","confidence":9,"source":"observed","files":["affected/file1.ts","affected/file2.ts"]}' +``` + {{LEARNINGS_LOG}} +{{GBRAIN_SAVE_RESULTS}} + --- ## Important Rules diff --git a/office-hours/SKILL.md.tmpl b/office-hours/SKILL.md.tmpl index 23fd8176..b59f616b 100644 --- a/office-hours/SKILL.md.tmpl +++ b/office-hours/SKILL.md.tmpl @@ -37,6 +37,8 @@ You are a **YC office hours partner**. Your job is to ensure the problem is unde --- +{{GBRAIN_CONTEXT_LOAD}} + ## Phase 1: Context Gathering Understand the project and the area the user wants to change. @@ -462,7 +464,10 @@ PRIOR=$(ls -t ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head ``` If `$PRIOR` exists, the new doc gets a `Supersedes:` field referencing it. This creates a revision chain — you can trace how a design evolved across office hours sessions. -Write to `~/.gstack/projects/{slug}/{user}-{branch}-design-{datetime}.md`: +Write to `~/.gstack/projects/{slug}/{user}-{branch}-design-{datetime}.md`. + +After writing the design doc, tell the user: +**"Design doc saved to: {full path}. Other skills (/plan-ceo-review, /plan-eng-review) will find it automatically."** ### Startup mode design doc template: @@ -591,6 +596,8 @@ Present the reviewed design doc to the user via AskUserQuestion: - B) Revise — specify which sections need changes (loop back to revise those sections) - C) Start over — return to Phase 2 +{{GBRAIN_SAVE_RESULTS}} + --- ## Phase 6: Handoff — The Relationship Closing diff --git a/plan-ceo-review/SKILL.md.tmpl b/plan-ceo-review/SKILL.md.tmpl index 225cd05d..8a7921ef 100644 --- a/plan-ceo-review/SKILL.md.tmpl +++ b/plan-ceo-review/SKILL.md.tmpl @@ -190,6 +190,8 @@ Feed into the Premise Challenge (0A) and Dream State Mapping (0C). If you find a {{LEARNINGS_SEARCH}} +{{GBRAIN_CONTEXT_LOAD}} + ## Step 0: Nuclear Scope Challenge + Mode Selection ### 0A. Premise Challenge @@ -352,6 +354,7 @@ After mode is selected, confirm which implementation approach (from 0C-bis) appl Once selected, commit fully. Do not silently drift. **STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**Reminder: Do NOT make any code changes. Review only.** ## Review Sections (11 sections, after scope and mode are agreed) @@ -381,6 +384,7 @@ Evaluate and diagram: Required ASCII diagram: full system architecture showing new components and their relationships to existing ones. **STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**Reminder: Do NOT make any code changes. Review only.** ### Section 2: Error & Rescue Map This is the section that catches silent failures. It is not optional. @@ -410,6 +414,7 @@ Rules for this section: * For each GAP (unrescued error that should be rescued): specify the rescue action and what the user should see. * For LLM/AI service calls specifically: what happens when the response is malformed? When it's empty? When it hallucinates invalid JSON? When the model returns a refusal? Each of these is a distinct failure mode. **STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**Reminder: Do NOT make any code changes. Review only.** ### Section 3: Security & Threat Model Security is not a sub-bullet of architecture. It gets its own section. @@ -425,6 +430,7 @@ Evaluate: For each finding: threat, likelihood (High/Med/Low), impact (High/Med/Low), and whether the plan mitigates it. **STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**Reminder: Do NOT make any code changes. Review only.** ### Section 4: Data Flow & Interaction Edge Cases This section traces data through the system and interactions through the UI with adversarial thoroughness. @@ -461,6 +467,7 @@ For each node: what happens on each shadow path? Is it tested? ``` Flag any unhandled edge case as a gap. For each gap, specify the fix. **STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**Reminder: Do NOT make any code changes. Review only.** ### Section 5: Code Quality Review Evaluate: @@ -473,6 +480,7 @@ Evaluate: * Under-engineering check. Anything fragile, assuming happy path only, or missing obvious defensive checks? * Cyclomatic complexity. Flag any new method that branches more than 5 times. Propose a refactor. **STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**Reminder: Do NOT make any code changes. Review only.** ### Section 6: Test Review Make a complete diagram of every new thing this plan introduces: @@ -513,6 +521,7 @@ Load/stress test requirements: For any new codepath called frequently or process For LLM/prompt changes: Check CLAUDE.md for the "Prompt/LLM changes" file patterns. If this plan touches ANY of those patterns, state which eval suites must be run, which cases should be added, and what baselines to compare against. **STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**Reminder: Do NOT make any code changes. Review only.** ### Section 7: Performance Review Evaluate: @@ -524,6 +533,7 @@ Evaluate: * Slow paths. Top 3 slowest new codepaths and estimated p99 latency. * Connection pool pressure. New DB connections, Redis connections, HTTP connections? **STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**Reminder: Do NOT make any code changes. Review only.** ### Section 8: Observability & Debuggability Review New systems break. This section ensures you can see why. @@ -540,6 +550,7 @@ Evaluate: **EXPANSION and SELECTIVE EXPANSION addition:** * What observability would make this feature a joy to operate? (For SELECTIVE EXPANSION, include observability for any accepted cherry-picks.) **STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**Reminder: Do NOT make any code changes. Review only.** ### Section 9: Deployment & Rollout Review Evaluate: @@ -555,6 +566,7 @@ Evaluate: **EXPANSION and SELECTIVE EXPANSION addition:** * What deploy infrastructure would make shipping this feature routine? (For SELECTIVE EXPANSION, assess whether accepted cherry-picks change the deployment risk profile.) **STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**Reminder: Do NOT make any code changes. Review only.** ### Section 10: Long-Term Trajectory Review Evaluate: @@ -570,6 +582,7 @@ Evaluate: * Platform potential. Does this create capabilities other features can leverage? * (SELECTIVE EXPANSION only) Retrospective: Were the right cherry-picks accepted? Did any rejected expansions turn out to be load-bearing for the accepted ones? **STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**Reminder: Do NOT make any code changes. Review only.** ### Section 11: Design & UX Review (skip if no UI scope detected) The CEO calling in the designer. Not a pixel-level audit — that's /plan-design-review and /design-review. This is ensuring the plan has design intentionality. @@ -592,6 +605,7 @@ Required ASCII diagram: user flow showing screens/states and transitions. If this plan has significant UI scope, recommend: "Consider running /plan-design-review for a deep design review of this plan before implementation." **STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**Reminder: Do NOT make any code changes. Review only.** {{CODEX_PLAN_REVIEW}} @@ -783,6 +797,8 @@ If promoted, copy the CEO plan content to `docs/designs/{FEATURE}.md` (create th {{LEARNINGS_LOG}} +{{GBRAIN_SAVE_RESULTS}} + ## Mode Quick Reference ``` ┌────────────────────────────────────────────────────────────────────────────────┐ diff --git a/retro/SKILL.md.tmpl b/retro/SKILL.md.tmpl index d89cb717..1d85abe1 100644 --- a/retro/SKILL.md.tmpl +++ b/retro/SKILL.md.tmpl @@ -37,6 +37,8 @@ When the user types `/retro`, run this skill. - `/retro global` — cross-project retro across all AI coding tools (7d default) - `/retro global 14d` — cross-project retro with explicit window +{{GBRAIN_CONTEXT_LOAD}} + ## Instructions Parse the argument to determine the time window. Default to 7 days if no argument given. All times should be reported in the user's **local timezone** (use the system default — do NOT set `TZ`). @@ -60,6 +62,16 @@ Usage: /retro [window | compare | global] {{LEARNINGS_SEARCH}} +### Non-git context (optional) + +Check for non-git context that should be included in the retro: + +```bash +[ -f ~/.gstack/retro-context.md ] && echo "RETRO_CONTEXT_FOUND" || echo "NO_RETRO_CONTEXT" +``` + +If `RETRO_CONTEXT_FOUND`: read `~/.gstack/retro-context.md`. This file is user-authored and may contain meeting notes, calendar events, decisions, and other context that doesn't appear in git history. Incorporate this context into the retro narrative where relevant. + ### Step 1: Gather Raw Data First, fetch origin and identify the current user: @@ -281,6 +293,8 @@ For each contributor (including the current user), compute: {{LEARNINGS_LOG}} +{{GBRAIN_SAVE_RESULTS}} + ### Step 10: Week-over-Week Trends (if window >= 14d) If the time window is 14 days or more, split into weekly buckets and show trends: diff --git a/scripts/resolvers/gbrain.ts b/scripts/resolvers/gbrain.ts new file mode 100644 index 00000000..103dab08 --- /dev/null +++ b/scripts/resolvers/gbrain.ts @@ -0,0 +1,42 @@ +/** + * GBrain resolver — brain-first lookup and save-to-brain for thinking skills. + * + * GBrain is a "mod" for gstack. When installed, coding skills become brain-aware: + * they search the brain for context before starting and save results after finishing. + * + * These resolvers are suppressed on ALL hosts except gbrain (via suppressedResolvers + * in each host config). For non-gbrain hosts, {{GBRAIN_CONTEXT_LOAD}} and + * {{GBRAIN_SAVE_RESULTS}} resolve to empty string and vanish from the output. + */ +import type { TemplateContext } from './types'; + +export function generateGBrainContextLoad(_ctx: TemplateContext): string { + return `## Brain Context Load + +Before starting this skill, search your brain for relevant context: + +1. Search GBrain: \`gbrain query ""\` +2. If results found, read the top 3 pages for context +3. Use this brain context to inform your analysis + +If GBrain is not available or returns no results, proceed without brain context.`; +} + +export function generateGBrainSaveResults(ctx: TemplateContext): string { + const skillSaveMap: Record = { + 'office-hours': 'Save the design document as a brain page: `gbrain put_page` with the design doc content, tagged with the project slug and "design-doc".', + 'investigate': 'Save the root cause analysis as a brain page: `gbrain put_page` with the investigation findings, tagged with affected files and "investigation".', + 'plan-ceo-review': 'Save the CEO plan as a brain page: `gbrain put_page` with the scope decisions and vision, tagged with the feature slug and "ceo-plan".', + 'retro': 'Save the retrospective as a brain page: `gbrain put_page` with the retro output, tagged with the date range and "retro".', + }; + + const saveInstruction = skillSaveMap[ctx.skillName] || 'Save the skill output as a brain page if the results are worth preserving.'; + + return `## Save Results to Brain + +After completing this skill, persist the results to your brain for future reference: + +${saveInstruction} + +Add backlinks to related brain pages if they exist. If GBrain is not available, skip this step.`; +} diff --git a/scripts/resolvers/index.ts b/scripts/resolvers/index.ts index 072b1a3d..b195c1ed 100644 --- a/scripts/resolvers/index.ts +++ b/scripts/resolvers/index.ts @@ -18,6 +18,7 @@ import { generateConfidenceCalibration } from './confidence'; import { generateInvokeSkill } from './composition'; import { generateReviewArmy } from './review-army'; import { generateDxFramework } from './dx'; +import { generateGBrainContextLoad, generateGBrainSaveResults } from './gbrain'; export const RESOLVERS: Record = { SLUG_EVAL: generateSlugEval, @@ -62,4 +63,6 @@ export const RESOLVERS: Record = { REVIEW_ARMY: generateReviewArmy, CROSS_REVIEW_DEDUP: generateCrossReviewDedup, DX_FRAMEWORK: generateDxFramework, + GBRAIN_CONTEXT_LOAD: generateGBrainContextLoad, + GBRAIN_SAVE_RESULTS: generateGBrainSaveResults, };