diff --git a/PREAMBLE-BLOAT-NOTES.md b/PREAMBLE-BLOAT-NOTES.md index 832c1b736..0077ebab3 100644 --- a/PREAMBLE-BLOAT-NOTES.md +++ b/PREAMBLE-BLOAT-NOTES.md @@ -171,3 +171,29 @@ upstream churn per release. upstream-owned, intentionally-tuned behaviour per the token-ceiling comment, so propose it upstream per-skill via the same `sections/` mechanism rather than forking it. + +--- + +## 6. Upstream duplicate check (2026-07-05, Opus session) + +Ran the check the strategy said to do first. Findings on garrytan/gstack: + +- **#1572 (open) — "skill: cache preamble bash output within session to + reduce duplication"** is the closest existing issue: same preamble-duplication + concern, no PR carving the interaction-framework prose yet. Our proposal is + complementary, not a duplicate. +- Active adjacent preamble work (do NOT collide): #2001/#2022 gate + upgrade-handling prose; #1150/#1188 gate telemetry session tracking; #1982 + surface failed update-checks; #1972 shrink skill descriptions (codex budget). +- No open PR implements a `sections/` carve of the preamble prose. + +Verification blockers confirming proposal-first: +- `bun run skill:check` is **red on a clean `11de390b` checkout** — unrelated + cause: `.gbrain/skills/gstack-*/SKILL.md` stale under `gen:skill-docs --host + gbrain` detection. A fork can't cleanly prove Claude-host freshness in + isolation against that baseline. +- Real behaviour gate is `test:evals` (EVALS=1, live model calls) — API-gated. + +Deliverable: `~/worktrees/gstack-preamble-trim/PR-PROPOSAL.md` — maintainer-ready +text to post on #1572 for buy-in before implementing. Branch `pr/preamble-trim` +sits on clean upstream; no code committed (proposal-first, per above). diff --git a/autoplan/SKILL.md b/autoplan/SKILL.md index 5346f1d43..a7c41e4e8 100644 --- a/autoplan/SKILL.md +++ b/autoplan/SKILL.md @@ -21,7 +21,6 @@ allowed-tools: - ## When to invoke this skill Surfaces @@ -460,7 +459,6 @@ Before calling AskUserQuestion, verify: - [ ] If you split, you checked dependencies between options before firing the chain - [ ] If a per-option Hold fires, you stopped the chain immediately (didn't queue) - ## Artifacts Sync (skill start) ```bash @@ -558,8 +556,6 @@ else fi ``` - - Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once: > gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync? @@ -586,7 +582,6 @@ At skill END before telemetry: "~/.claude/skills/gstack/bin/gstack-brain-sync" --once 2>/dev/null || true ``` - ## Model-Specific Behavioral Patch (claude) The following nudges are tuned for the claude model family. They are @@ -667,7 +662,6 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i Curated jargon list lives at `~/.claude/skills/gstack/scripts/jargon-list.json` (80+ terms). On the first jargon term you encounter this session, Read that file once; treat the `terms` array as the canonical list. The list is repo-owned and may grow between releases. - ## Completeness Principle — Boil the Ocean AI makes completeness cheap, so the complete thing is the goal. Recommend full coverage (tests, edge cases, error paths) — boil the ocean one lake at a time. The only thing out of scope is genuinely unrelated work (rewrites, multi-quarter migrations); flag that as separate scope, never as an excuse for a shortcut. @@ -1713,7 +1707,6 @@ skills ran in this session), render: skill writes its own; if you ran one of them but no list appears here, check that jq is installed and the tasks--*.jsonl files exist._` - **STOP here and present the final state to the user.** Present as a message, then use AskUserQuestion: diff --git a/benchmark-models/SKILL.md b/benchmark-models/SKILL.md index 6a9d62616..c2d5eae38 100644 --- a/benchmark-models/SKILL.md +++ b/benchmark-models/SKILL.md @@ -16,7 +16,6 @@ allowed-tools: - ## When to invoke this skill Runs the same prompt through Claude, @@ -427,8 +426,6 @@ else fi ``` - - Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once: > gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync? @@ -455,7 +452,6 @@ At skill END before telemetry: "~/.claude/skills/gstack/bin/gstack-brain-sync" --once 2>/dev/null || true ``` - ## Model-Specific Behavioral Patch (claude) The following nudges are tuned for the claude model family. They are diff --git a/benchmark/SKILL.md b/benchmark/SKILL.md index 9451d2d4f..e86812fc6 100644 --- a/benchmark/SKILL.md +++ b/benchmark/SKILL.md @@ -17,7 +17,6 @@ allowed-tools: - ## When to invoke this skill Establishes @@ -427,8 +426,6 @@ else fi ``` - - Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once: > gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync? @@ -455,7 +452,6 @@ At skill END before telemetry: "~/.claude/skills/gstack/bin/gstack-brain-sync" --once 2>/dev/null || true ``` - ## Model-Specific Behavioral Patch (claude) The following nudges are tuned for the claude model family. They are diff --git a/bin/gstack-artifacts-init b/bin/gstack-artifacts-init index b8bfe830c..2a308fc87 100755 --- a/bin/gstack-artifacts-init +++ b/bin/gstack-artifacts-init @@ -1,4 +1,5 @@ -#!/usr/bin/env bash +#!/bin/bash +# /bin/bash, not env bash: Homebrew bash 5.3 heredocs >511B deadlock on macOS (512-byte pipe buffers, no F_GETPIPE_SZ) # gstack-artifacts-init — set up ~/.gstack/ as a git repo synced to a private # git host (GitHub or GitLab) so a remote gbrain can ingest your artifacts # (CEO plans, designs, /investigate reports) as a federated source. @@ -48,7 +49,7 @@ while [ $# -gt 0 ]; do --remote) REMOTE_URL="$2"; shift 2 ;; --host) HOST_PREF="$2"; shift 2 ;; --url-form-supported) URL_FORM_SUPPORTED="$2"; shift 2 ;; - --help|-h) sed -n '2,32p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; + --help|-h) sed -n '3,33p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; *) echo "Unknown flag: $1" >&2; exit 1 ;; esac done diff --git a/bin/gstack-brain-consumer b/bin/gstack-brain-consumer index 12403ae58..5fb320051 100755 --- a/bin/gstack-brain-consumer +++ b/bin/gstack-brain-consumer @@ -1,4 +1,5 @@ -#!/usr/bin/env bash +#!/bin/bash +# /bin/bash, not env bash: Homebrew bash 5.3 heredocs >511B deadlock on macOS (512-byte pipe buffers, no F_GETPIPE_SZ) # gstack-brain-consumer — manage the consumer (reader) registry. # # DEPRECATED in v1.17.0.0. This binary targets a gbrain HTTP /ingest-repo @@ -196,6 +197,6 @@ case "${1:-}" in list) sub_list ;; remove) shift; sub_remove "$@" ;; test) shift; sub_test "$@" ;; - --help|-h|"") sed -n '2,20p' "$0" | sed 's/^# \{0,1\}//' ;; + --help|-h|"") sed -n '3,21p' "$0" | sed 's/^# \{0,1\}//' ;; *) echo "Unknown subcommand: $1" >&2; exit 1 ;; esac diff --git a/bin/gstack-brain-restore b/bin/gstack-brain-restore index 21f7c1134..8b4fad6fd 100755 --- a/bin/gstack-brain-restore +++ b/bin/gstack-brain-restore @@ -1,4 +1,5 @@ -#!/usr/bin/env bash +#!/bin/bash +# /bin/bash, not env bash: Homebrew bash 5.3 heredocs >511B deadlock on macOS (512-byte pipe buffers, no F_GETPIPE_SZ) # gstack-brain-restore — bootstrap a new machine from an existing brain repo. # # Usage: diff --git a/bin/gstack-brain-sync b/bin/gstack-brain-sync index 2ad0fe773..4a932a071 100755 --- a/bin/gstack-brain-sync +++ b/bin/gstack-brain-sync @@ -1,4 +1,5 @@ -#!/usr/bin/env bash +#!/bin/bash +# /bin/bash, not env bash: Homebrew bash 5.3 heredocs >511B deadlock on macOS (512-byte pipe buffers, no F_GETPIPE_SZ) # gstack-brain-sync — drain queue, commit allowlisted paths, push to remote. # # Usage: @@ -487,7 +488,7 @@ case "${1:-}" in --drop-queue) shift; subcmd_drop_queue "${1:-}" ;; --discover-new) subcmd_discover_new ;; --help|-h) - sed -n '2,18p' "$0" | sed 's/^# \{0,1\}//' + sed -n '3,19p' "$0" | sed 's/^# \{0,1\}//' ;; *) echo "Unknown subcommand: $1" >&2 diff --git a/bin/gstack-distill-free-text b/bin/gstack-distill-free-text index 4f0688dcb..d930b4d63 100755 --- a/bin/gstack-distill-free-text +++ b/bin/gstack-distill-free-text @@ -1,4 +1,5 @@ -#!/usr/bin/env bash +#!/bin/bash +# /bin/bash, not env bash: Homebrew bash 5.3 heredocs >511B deadlock on macOS (512-byte pipe buffers, no F_GETPIPE_SZ) # gstack-distill-free-text — Layer 8 "dream cycle" batch distiller. # # Reads auq-other free-text events from this project's question-log.jsonl, @@ -37,7 +38,7 @@ case "${1:-}" in --dry-run) MODE="dry-run" ;; --status) MODE="status" ;; --help|-h) - sed -n '1,/^set -euo/p' "$0" | sed 's|^# \?||' + sed -n '3,/^set -euo/p' "$0" | sed 's|^# \?||' exit 0 ;; '') ;; diff --git a/bin/gstack-jsonl-merge b/bin/gstack-jsonl-merge index d2fa5744c..8878db3c6 100755 --- a/bin/gstack-jsonl-merge +++ b/bin/gstack-jsonl-merge @@ -1,4 +1,5 @@ -#!/usr/bin/env bash +#!/bin/bash +# /bin/bash, not env bash: Homebrew bash 5.3 heredocs >511B deadlock on macOS (512-byte pipe buffers, no F_GETPIPE_SZ) # gstack-jsonl-merge — git merge driver for append-only JSONL files. # # Usage (called by git, not by users): diff --git a/bin/gstack-settings-hook b/bin/gstack-settings-hook index 6d663b23f..aa02e6b37 100755 --- a/bin/gstack-settings-hook +++ b/bin/gstack-settings-hook @@ -1,4 +1,5 @@ -#!/usr/bin/env bash +#!/bin/bash +# /bin/bash, not env bash: Homebrew bash 5.3 heredocs >511B deadlock on macOS (512-byte pipe buffers, no F_GETPIPE_SZ) # gstack-settings-hook — manage Claude Code hooks in ~/.claude/settings.json # # Two shapes: diff --git a/bin/gstack-team-init b/bin/gstack-team-init index 256735f8b..da97173b5 100755 --- a/bin/gstack-team-init +++ b/bin/gstack-team-init @@ -1,4 +1,5 @@ -#!/usr/bin/env bash +#!/bin/bash +# /bin/bash, not env bash: Homebrew bash 5.3 heredocs >511B deadlock on macOS (512-byte pipe buffers, no F_GETPIPE_SZ) # gstack-team-init — generate repo-level bootstrap files for team mode # # Usage: diff --git a/browse/SKILL.md b/browse/SKILL.md index a8138dbbc..730975a2a 100644 --- a/browse/SKILL.md +++ b/browse/SKILL.md @@ -16,7 +16,6 @@ allowed-tools: - ## When to invoke this skill Navigate any URL, interact with @@ -425,8 +424,6 @@ else fi ``` - - Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once: > gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync? @@ -453,7 +450,6 @@ At skill END before telemetry: "~/.claude/skills/gstack/bin/gstack-brain-sync" --once 2>/dev/null || true ``` - ## Model-Specific Behavioral Patch (claude) The following nudges are tuned for the claude model family. They are diff --git a/canary/SKILL.md b/canary/SKILL.md index 08d4d7369..1d991e21b 100644 --- a/canary/SKILL.md +++ b/canary/SKILL.md @@ -17,7 +17,6 @@ triggers: - ## When to invoke this skill Watches the live app for console errors, @@ -452,7 +451,6 @@ Before calling AskUserQuestion, verify: - [ ] If you split, you checked dependencies between options before firing the chain - [ ] If a per-option Hold fires, you stopped the chain immediately (didn't queue) - ## Artifacts Sync (skill start) ```bash @@ -550,8 +548,6 @@ else fi ``` - - Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once: > gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync? @@ -578,7 +574,6 @@ At skill END before telemetry: "~/.claude/skills/gstack/bin/gstack-brain-sync" --once 2>/dev/null || true ``` - ## Model-Specific Behavioral Patch (claude) The following nudges are tuned for the claude model family. They are @@ -659,7 +654,6 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i Curated jargon list lives at `~/.claude/skills/gstack/scripts/jargon-list.json` (80+ terms). On the first jargon term you encounter this session, Read that file once; treat the `terms` array as the canonical list. The list is repo-owned and may grow between releases. - ## Completeness Principle — Boil the Ocean AI makes completeness cheap, so the complete thing is the goal. Recommend full coverage (tests, edge cases, error paths) — boil the ocean one lake at a time. The only thing out of scope is genuinely unrelated work (rewrites, multi-quarter migrations); flag that as separate scope, never as an excuse for a shortcut. diff --git a/codex/SKILL.md b/codex/SKILL.md index 33228ff9b..8932d56f0 100644 --- a/codex/SKILL.md +++ b/codex/SKILL.md @@ -18,7 +18,6 @@ allowed-tools: - ## When to invoke this skill Code review: independent diff review via @@ -455,7 +454,6 @@ Before calling AskUserQuestion, verify: - [ ] If you split, you checked dependencies between options before firing the chain - [ ] If a per-option Hold fires, you stopped the chain immediately (didn't queue) - ## Artifacts Sync (skill start) ```bash @@ -553,8 +551,6 @@ else fi ``` - - Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once: > gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync? @@ -581,7 +577,6 @@ At skill END before telemetry: "~/.claude/skills/gstack/bin/gstack-brain-sync" --once 2>/dev/null || true ``` - ## Model-Specific Behavioral Patch (claude) The following nudges are tuned for the claude model family. They are @@ -662,7 +657,6 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i Curated jargon list lives at `~/.claude/skills/gstack/scripts/jargon-list.json` (80+ terms). On the first jargon term you encounter this session, Read that file once; treat the `terms` array as the canonical list. The list is repo-owned and may grow between releases. - ## Completeness Principle — Boil the Ocean AI makes completeness cheap, so the complete thing is the goal. Recommend full coverage (tests, edge cases, error paths) — boil the ocean one lake at a time. The only thing out of scope is genuinely unrelated work (rewrites, multi-quarter migrations); flag that as separate scope, never as an excuse for a shortcut. diff --git a/context-restore/SKILL.md b/context-restore/SKILL.md index 59b40e82c..7335fd017 100644 --- a/context-restore/SKILL.md +++ b/context-restore/SKILL.md @@ -19,7 +19,6 @@ triggers: - ## When to invoke this skill Loads the most recent @@ -456,7 +455,6 @@ Before calling AskUserQuestion, verify: - [ ] If you split, you checked dependencies between options before firing the chain - [ ] If a per-option Hold fires, you stopped the chain immediately (didn't queue) - ## Artifacts Sync (skill start) ```bash @@ -554,8 +552,6 @@ else fi ``` - - Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once: > gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync? @@ -582,7 +578,6 @@ At skill END before telemetry: "~/.claude/skills/gstack/bin/gstack-brain-sync" --once 2>/dev/null || true ``` - ## Model-Specific Behavioral Patch (claude) The following nudges are tuned for the claude model family. They are @@ -663,7 +658,6 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i Curated jargon list lives at `~/.claude/skills/gstack/scripts/jargon-list.json` (80+ terms). On the first jargon term you encounter this session, Read that file once; treat the `terms` array as the canonical list. The list is repo-owned and may grow between releases. - ## Completeness Principle — Boil the Ocean AI makes completeness cheap, so the complete thing is the goal. Recommend full coverage (tests, edge cases, error paths) — boil the ocean one lake at a time. The only thing out of scope is genuinely unrelated work (rewrites, multi-quarter migrations); flag that as separate scope, never as an excuse for a shortcut. diff --git a/context-save/SKILL.md b/context-save/SKILL.md index a1eb24595..ac8eeff9d 100644 --- a/context-save/SKILL.md +++ b/context-save/SKILL.md @@ -19,7 +19,6 @@ triggers: - ## When to invoke this skill Captures git state, decisions made, and remaining work @@ -455,7 +454,6 @@ Before calling AskUserQuestion, verify: - [ ] If you split, you checked dependencies between options before firing the chain - [ ] If a per-option Hold fires, you stopped the chain immediately (didn't queue) - ## Artifacts Sync (skill start) ```bash @@ -553,8 +551,6 @@ else fi ``` - - Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once: > gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync? @@ -581,7 +577,6 @@ At skill END before telemetry: "~/.claude/skills/gstack/bin/gstack-brain-sync" --once 2>/dev/null || true ``` - ## Model-Specific Behavioral Patch (claude) The following nudges are tuned for the claude model family. They are @@ -662,7 +657,6 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i Curated jargon list lives at `~/.claude/skills/gstack/scripts/jargon-list.json` (80+ terms). On the first jargon term you encounter this session, Read that file once; treat the `terms` array as the canonical list. The list is repo-owned and may grow between releases. - ## Completeness Principle — Boil the Ocean AI makes completeness cheap, so the complete thing is the goal. Recommend full coverage (tests, edge cases, error paths) — boil the ocean one lake at a time. The only thing out of scope is genuinely unrelated work (rewrites, multi-quarter migrations); flag that as separate scope, never as an excuse for a shortcut. diff --git a/cso/SKILL.md b/cso/SKILL.md index a08d7e9fe..87dcc8b0c 100644 --- a/cso/SKILL.md +++ b/cso/SKILL.md @@ -20,7 +20,6 @@ triggers: - ## When to invoke this skill Infrastructure-first security audit: secrets archaeology, @@ -458,7 +457,6 @@ Before calling AskUserQuestion, verify: - [ ] If you split, you checked dependencies between options before firing the chain - [ ] If a per-option Hold fires, you stopped the chain immediately (didn't queue) - ## Artifacts Sync (skill start) ```bash @@ -556,8 +554,6 @@ else fi ``` - - Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once: > gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync? @@ -584,7 +580,6 @@ At skill END before telemetry: "~/.claude/skills/gstack/bin/gstack-brain-sync" --once 2>/dev/null || true ``` - ## Model-Specific Behavioral Patch (claude) The following nudges are tuned for the claude model family. They are @@ -665,7 +660,6 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i Curated jargon list lives at `~/.claude/skills/gstack/scripts/jargon-list.json` (80+ terms). On the first jargon term you encounter this session, Read that file once; treat the `terms` array as the canonical list. The list is repo-owned and may grow between releases. - ## Completeness Principle — Boil the Ocean AI makes completeness cheap, so the complete thing is the goal. Recommend full coverage (tests, edge cases, error paths) — boil the ocean one lake at a time. The only thing out of scope is genuinely unrelated work (rewrites, multi-quarter migrations); flag that as separate scope, never as an excuse for a shortcut. @@ -784,7 +778,17 @@ Replace `SKILL_NAME`, `OUTCOME`, and `USED_BROWSE` before running. Skills that run plan reviews (`/plan-*-review`, `/codex review`) include the EXIT PLAN MODE GATE blocking checklist at the end of the skill, which verifies the plan file ends with `## GSTACK REVIEW REPORT` before ExitPlanMode is called. Skills that don't run plan reviews (operational skills like `/ship`, `/qa`, `/review`) typically don't operate in plan mode and have no review report to verify; this footer is a no-op for them. Writing the plan file is the one edit allowed in plan mode. +## Brain Context Load +**Skip this entire section if `gbrain` is not on PATH.** + +Extract 2-4 keywords from the user's request. Search the brain: +`gbrain search ""`. Read the top 3 results with +`gbrain get_page ""`. Use that context to inform your analysis. + +If `gbrain search` returns no results or any non-zero exit, proceed +without brain context. Full search/read protocol + examples: +see `docs/gbrain-write-surfaces.md` §Context Load. # /cso — Chief Security Officer Audit (v2) @@ -829,7 +833,6 @@ sections. Read a section in full before doing its step; do not work from memory. | running the scope-dependent audit phases (Phases 2-11) selected by the resolved mode, after the Phase 0 stack detection and Phase 1 attack-surface census | `sections/audit-phases.md` | --- - ## Important: Use the Grep tool for all code searches The bash blocks throughout this skill show WHAT patterns to search for, not HOW to run them. Use Claude Code's Grep tool (which handles permissions and access correctly) rather than raw bash grep. The bash blocks are illustrative examples — do NOT copy-paste them into a terminal. Do NOT use `| head` to truncate results. @@ -1257,7 +1260,28 @@ staleness detection: if those files are later deleted, the learning can be flagg **Only log genuine discoveries.** Don't log obvious things. Don't log things the user already knows. A good test: would this insight save time in a future session? If yes, log it. +## Save Results to Brain +**Skip this entire section if `gbrain` is not on PATH.** + +After completing this skill, save the output: + +```bash +gbrain put "security-audits/" --content "$(cat <<'EOF' +--- +title: "Security Audit: " +tags: [security-audit, ] +--- + +EOF +)" +``` + +Then extract person/org entities and create stub pages for each one. +Throttle errors (exit 1 with "throttle"/"rate limit"/"busy") and any +other non-zero exit are transient — don't retry inline. Full entity-stub +template, throttle handling, and backlink protocol: +see `docs/gbrain-write-surfaces.md` §Save Template. ## Important Rules diff --git a/design-consultation/SKILL.md b/design-consultation/SKILL.md index 83eed0a2d..743fdbcf2 100644 --- a/design-consultation/SKILL.md +++ b/design-consultation/SKILL.md @@ -43,7 +43,6 @@ gbrain: - ## When to invoke this skill Creates DESIGN.md as your project's design source @@ -478,7 +477,6 @@ Before calling AskUserQuestion, verify: - [ ] If you split, you checked dependencies between options before firing the chain - [ ] If a per-option Hold fires, you stopped the chain immediately (didn't queue) - ## Artifacts Sync (skill start) ```bash @@ -576,8 +574,6 @@ else fi ``` - - Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once: > gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync? @@ -604,7 +600,6 @@ At skill END before telemetry: "~/.claude/skills/gstack/bin/gstack-brain-sync" --once 2>/dev/null || true ``` - ## Model-Specific Behavioral Patch (claude) The following nudges are tuned for the claude model family. They are @@ -685,7 +680,6 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i Curated jargon list lives at `~/.claude/skills/gstack/scripts/jargon-list.json` (80+ terms). On the first jargon term you encounter this session, Read that file once; treat the `terms` array as the canonical list. The list is repo-owned and may grow between releases. - ## Completeness Principle — Boil the Ocean AI makes completeness cheap, so the complete thing is the goal. Recommend full coverage (tests, edge cases, error paths) — boil the ocean one lake at a time. The only thing out of scope is genuinely unrelated work (rewrites, multi-quarter migrations); flag that as separate scope, never as an excuse for a shortcut. @@ -953,7 +947,17 @@ If `DESIGN_NOT_AVAILABLE`: Phase 5 falls back to the HTML preview page (still go --- +## Brain Context Load +**Skip this entire section if `gbrain` is not on PATH.** + +Extract 2-4 keywords from the user's request. Search the brain: +`gbrain search ""`. Read the top 3 results with +`gbrain get_page ""`. Use that context to inform your analysis. + +If `gbrain search` returns no results or any non-zero exit, proceed +without brain context. Full search/read protocol + examples: +see `docs/gbrain-write-surfaces.md` §Context Load. ## Prior Learnings @@ -1216,7 +1220,28 @@ staleness detection: if those files are later deleted, the learning can be flagg **Only log genuine discoveries.** Don't log obvious things. Don't log things the user already knows. A good test: would this insight save time in a future session? If yes, log it. +## Save Results to Brain +**Skip this entire section if `gbrain` is not on PATH.** + +After completing this skill, save the output: + +```bash +gbrain put "design-systems/" --content "$(cat <<'EOF' +--- +title: "Design System: " +tags: [design-system, ] +--- + +EOF +)" +``` + +Then extract person/org entities and create stub pages for each one. +Throttle errors (exit 1 with "throttle"/"rate limit"/"busy") and any +other non-zero exit are transient — don't retry inline. Full entity-stub +template, throttle handling, and backlink protocol: +see `docs/gbrain-write-surfaces.md` §Save Template. ## Important Rules diff --git a/design-html/SKILL.md b/design-html/SKILL.md index a480bd62c..3523c9ac1 100644 --- a/design-html/SKILL.md +++ b/design-html/SKILL.md @@ -20,7 +20,6 @@ allowed-tools: - ## When to invoke this skill Works with approved mockups from /design-shotgun, CEO plans from /plan-ceo-review, @@ -459,7 +458,6 @@ Before calling AskUserQuestion, verify: - [ ] If you split, you checked dependencies between options before firing the chain - [ ] If a per-option Hold fires, you stopped the chain immediately (didn't queue) - ## Artifacts Sync (skill start) ```bash @@ -557,8 +555,6 @@ else fi ``` - - Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once: > gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync? @@ -585,7 +581,6 @@ At skill END before telemetry: "~/.claude/skills/gstack/bin/gstack-brain-sync" --once 2>/dev/null || true ``` - ## Model-Specific Behavioral Patch (claude) The following nudges are tuned for the claude model family. They are @@ -666,7 +661,6 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i Curated jargon list lives at `~/.claude/skills/gstack/scripts/jargon-list.json` (80+ terms). On the first jargon term you encounter this session, Read that file once; treat the `terms` array as the canonical list. The list is repo-owned and may grow between releases. - ## Completeness Principle — Boil the Ocean AI makes completeness cheap, so the complete thing is the goal. Recommend full coverage (tests, edge cases, error paths) — boil the ocean one lake at a time. The only thing out of scope is genuinely unrelated work (rewrites, multi-quarter migrations); flag that as separate scope, never as an excuse for a shortcut. diff --git a/design-review/SKILL.md b/design-review/SKILL.md index 645453162..60e841cd2 100644 --- a/design-review/SKILL.md +++ b/design-review/SKILL.md @@ -20,7 +20,6 @@ triggers: - ## When to invoke this skill Iteratively fixes issues @@ -456,7 +455,6 @@ Before calling AskUserQuestion, verify: - [ ] If you split, you checked dependencies between options before firing the chain - [ ] If a per-option Hold fires, you stopped the chain immediately (didn't queue) - ## Artifacts Sync (skill start) ```bash @@ -554,8 +552,6 @@ else fi ``` - - Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once: > gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync? @@ -582,7 +578,6 @@ At skill END before telemetry: "~/.claude/skills/gstack/bin/gstack-brain-sync" --once 2>/dev/null || true ``` - ## Model-Specific Behavioral Patch (claude) The following nudges are tuned for the claude model family. They are @@ -663,7 +658,6 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i Curated jargon list lives at `~/.claude/skills/gstack/scripts/jargon-list.json` (80+ terms). On the first jargon term you encounter this session, Read that file once; treat the `terms` array as the canonical list. The list is repo-owned and may grow between releases. - ## Completeness Principle — Boil the Ocean AI makes completeness cheap, so the complete thing is the goal. Recommend full coverage (tests, edge cases, error paths) — boil the ocean one lake at a time. The only thing out of scope is genuinely unrelated work (rewrites, multi-quarter migrations); flag that as separate scope, never as an excuse for a shortcut. @@ -800,7 +794,17 @@ Replace `SKILL_NAME`, `OUTCOME`, and `USED_BROWSE` before running. Skills that run plan reviews (`/plan-*-review`, `/codex review`) include the EXIT PLAN MODE GATE blocking checklist at the end of the skill, which verifies the plan file ends with `## GSTACK REVIEW REPORT` before ExitPlanMode is called. Skills that don't run plan reviews (operational skills like `/ship`, `/qa`, `/review`) typically don't operate in plan mode and have no review report to verify; this footer is a no-op for them. Writing the plan file is the one edit allowed in plan mode. +## Brain Context Load +**Skip this entire section if `gbrain` is not on PATH.** + +Extract 2-4 keywords from the user's request. Search the brain: +`gbrain search ""`. Read the top 3 results with +`gbrain get_page ""`. Use that context to inform your analysis. + +If `gbrain search` returns no results or any non-zero exit, proceed +without brain context. Full search/read protocol + examples: +see `docs/gbrain-write-surfaces.md` §Context Load. # /design-review: Design Audit → Fix → Verify @@ -1981,7 +1985,14 @@ staleness detection: if those files are later deleted, the learning can be flagg **Only log genuine discoveries.** Don't log obvious things. Don't log things the user already knows. A good test: would this insight save time in a future session? If yes, log it. +## Save Results to Brain +**Skip this entire section if `gbrain` is not on PATH.** + +If the skill output is worth preserving, save it via +`gbrain put "" --content ""`. Full template +(heredoc body, frontmatter shape, entity-stub instructions, throttle +handling): see `docs/gbrain-write-surfaces.md` §Save Template. ## Additional Rules (design-review specific) diff --git a/design-shotgun/SKILL.md b/design-shotgun/SKILL.md index 3386d18fa..5820ec75a 100644 --- a/design-shotgun/SKILL.md +++ b/design-shotgun/SKILL.md @@ -38,7 +38,6 @@ gbrain: - ## When to invoke this skill Standalone design exploration you can @@ -473,7 +472,6 @@ Before calling AskUserQuestion, verify: - [ ] If you split, you checked dependencies between options before firing the chain - [ ] If a per-option Hold fires, you stopped the chain immediately (didn't queue) - ## Artifacts Sync (skill start) ```bash @@ -571,8 +569,6 @@ else fi ``` - - Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once: > gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync? @@ -599,7 +595,6 @@ At skill END before telemetry: "~/.claude/skills/gstack/bin/gstack-brain-sync" --once 2>/dev/null || true ``` - ## Model-Specific Behavioral Patch (claude) The following nudges are tuned for the claude model family. They are @@ -680,7 +675,6 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i Curated jargon list lives at `~/.claude/skills/gstack/scripts/jargon-list.json` (80+ terms). On the first jargon term you encounter this session, Read that file once; treat the `terms` array as the canonical list. The list is repo-owned and may grow between releases. - ## Completeness Principle — Boil the Ocean AI makes completeness cheap, so the complete thing is the goal. Recommend full coverage (tests, edge cases, error paths) — boil the ocean one lake at a time. The only thing out of scope is genuinely unrelated work (rewrites, multi-quarter migrations); flag that as separate scope, never as an excuse for a shortcut. diff --git a/devex-review/SKILL.md b/devex-review/SKILL.md index 7ef324b3e..4a896b1d8 100644 --- a/devex-review/SKILL.md +++ b/devex-review/SKILL.md @@ -19,7 +19,6 @@ allowed-tools: - ## When to invoke this skill Uses the browse tool to actually TEST the @@ -458,7 +457,6 @@ Before calling AskUserQuestion, verify: - [ ] If you split, you checked dependencies between options before firing the chain - [ ] If a per-option Hold fires, you stopped the chain immediately (didn't queue) - ## Artifacts Sync (skill start) ```bash @@ -556,8 +554,6 @@ else fi ``` - - Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once: > gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync? @@ -584,7 +580,6 @@ At skill END before telemetry: "~/.claude/skills/gstack/bin/gstack-brain-sync" --once 2>/dev/null || true ``` - ## Model-Specific Behavioral Patch (claude) The following nudges are tuned for the claude model family. They are @@ -665,7 +660,6 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i Curated jargon list lives at `~/.claude/skills/gstack/scripts/jargon-list.json` (80+ terms). On the first jargon term you encounter this session, Read that file once; treat the `terms` array as the canonical list. The list is repo-owned and may grow between releases. - ## Completeness Principle — Boil the Ocean AI makes completeness cheap, so the complete thing is the goal. Recommend full coverage (tests, edge cases, error paths) — boil the ocean one lake at a time. The only thing out of scope is genuinely unrelated work (rewrites, multi-quarter migrations); flag that as separate scope, never as an excuse for a shortcut. diff --git a/diagram/SKILL.md b/diagram/SKILL.md index 9e5a41066..3344657f6 100644 --- a/diagram/SKILL.md +++ b/diagram/SKILL.md @@ -18,7 +18,6 @@ triggers: - ## When to invoke this skill on excalidraw.com, @@ -453,7 +452,6 @@ Before calling AskUserQuestion, verify: - [ ] If you split, you checked dependencies between options before firing the chain - [ ] If a per-option Hold fires, you stopped the chain immediately (didn't queue) - ## Artifacts Sync (skill start) ```bash @@ -551,8 +549,6 @@ else fi ``` - - Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once: > gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync? @@ -579,7 +575,6 @@ At skill END before telemetry: "~/.claude/skills/gstack/bin/gstack-brain-sync" --once 2>/dev/null || true ``` - ## Model-Specific Behavioral Patch (claude) The following nudges are tuned for the claude model family. They are @@ -660,7 +655,6 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i Curated jargon list lives at `~/.claude/skills/gstack/scripts/jargon-list.json` (80+ terms). On the first jargon term you encounter this session, Read that file once; treat the `terms` array as the canonical list. The list is repo-owned and may grow between releases. - ## Completeness Principle — Boil the Ocean AI makes completeness cheap, so the complete thing is the goal. Recommend full coverage (tests, edge cases, error paths) — boil the ocean one lake at a time. The only thing out of scope is genuinely unrelated work (rewrites, multi-quarter migrations); flag that as separate scope, never as an excuse for a shortcut. diff --git a/document-generate/SKILL.md b/document-generate/SKILL.md index 30846fc4d..d7a61a89f 100644 --- a/document-generate/SKILL.md +++ b/document-generate/SKILL.md @@ -23,7 +23,6 @@ triggers: - ## When to invoke this skill Uses the Diataxis framework (tutorial / how-to / reference / explanation) to produce @@ -458,7 +457,6 @@ Before calling AskUserQuestion, verify: - [ ] If you split, you checked dependencies between options before firing the chain - [ ] If a per-option Hold fires, you stopped the chain immediately (didn't queue) - ## Artifacts Sync (skill start) ```bash @@ -556,8 +554,6 @@ else fi ``` - - Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once: > gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync? @@ -584,7 +580,6 @@ At skill END before telemetry: "~/.claude/skills/gstack/bin/gstack-brain-sync" --once 2>/dev/null || true ``` - ## Model-Specific Behavioral Patch (claude) The following nudges are tuned for the claude model family. They are @@ -665,7 +660,6 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i Curated jargon list lives at `~/.claude/skills/gstack/scripts/jargon-list.json` (80+ terms). On the first jargon term you encounter this session, Read that file once; treat the `terms` array as the canonical list. The list is repo-owned and may grow between releases. - ## Completeness Principle — Boil the Ocean AI makes completeness cheap, so the complete thing is the goal. Recommend full coverage (tests, edge cases, error paths) — boil the ocean one lake at a time. The only thing out of scope is genuinely unrelated work (rewrites, multi-quarter migrations); flag that as separate scope, never as an excuse for a shortcut. diff --git a/document-release/SKILL.md b/document-release/SKILL.md index b95873625..0df91564b 100644 --- a/document-release/SKILL.md +++ b/document-release/SKILL.md @@ -19,7 +19,6 @@ triggers: - ## When to invoke this skill Reads all project docs, cross-references the @@ -456,7 +455,6 @@ Before calling AskUserQuestion, verify: - [ ] If you split, you checked dependencies between options before firing the chain - [ ] If a per-option Hold fires, you stopped the chain immediately (didn't queue) - ## Artifacts Sync (skill start) ```bash @@ -554,8 +552,6 @@ else fi ``` - - Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once: > gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync? @@ -582,7 +578,6 @@ At skill END before telemetry: "~/.claude/skills/gstack/bin/gstack-brain-sync" --once 2>/dev/null || true ``` - ## Model-Specific Behavioral Patch (claude) The following nudges are tuned for the claude model family. They are @@ -663,7 +658,6 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i Curated jargon list lives at `~/.claude/skills/gstack/scripts/jargon-list.json` (80+ terms). On the first jargon term you encounter this session, Read that file once; treat the `terms` array as the canonical list. The list is repo-owned and may grow between releases. - ## Completeness Principle — Boil the Ocean AI makes completeness cheap, so the complete thing is the goal. Recommend full coverage (tests, edge cases, error paths) — boil the ocean one lake at a time. The only thing out of scope is genuinely unrelated work (rewrites, multi-quarter migrations); flag that as separate scope, never as an excuse for a shortcut. diff --git a/gstack-upgrade/migrations/v1.27.0.0.sh b/gstack-upgrade/migrations/v1.27.0.0.sh index fb1ce73ce..b90d4c7dd 100755 --- a/gstack-upgrade/migrations/v1.27.0.0.sh +++ b/gstack-upgrade/migrations/v1.27.0.0.sh @@ -97,23 +97,24 @@ fi # Ask once (idempotent: if journal exists from a prior partial run, skip ask). if [ ! -f "$JOURNAL" ]; then - cat >&2 <512B deadlock on macOS when the + # kernel grants 512-byte pipe buffers (pipe-KVA pressure; no F_GETPIPE_SZ). + printf '%s\n' \ + '' \ + ' [v1.27.0.0] gstack-brain has been renamed to gstack-artifacts.' \ + ' This is a clearer name for what it actually holds: CEO plans, designs,' \ + ' /investigate reports, retros (i.e. artifacts, not behavioral memory).' \ + '' \ + ' This migration will:' \ + " 1. Rename your private GitHub/GitLab repo \"$OLD_REPO_NAME\" → \"$NEW_REPO_NAME\"" \ + ' 2. mv ~/.gstack-brain-remote.txt → ~/.gstack-artifacts-remote.txt' \ + ' 3. Rename gbrain_sync_mode → artifacts_sync_mode in ~/.gstack/config.yaml' \ + ' 4. Update any "## GBrain Configuration" block in CLAUDE.md' \ + ' 5. Update gbrain federated source registration (local CLI mode)' \ + ' OR print commands for your brain admin (remote MCP mode)' \ + '' \ + ' Each step is journaled so a Ctrl-C mid-flight is safe to re-run.' \ + '' >&2 if [ -t 0 ]; then printf " Proceed? [Y/n/skip-for-now]: " >&2 read -r REPLY || REPLY="" diff --git a/gstack-upgrade/migrations/v1.37.0.0.sh b/gstack-upgrade/migrations/v1.37.0.0.sh index b173f5844..5bc5a3f30 100755 --- a/gstack-upgrade/migrations/v1.37.0.0.sh +++ b/gstack-upgrade/migrations/v1.37.0.0.sh @@ -70,22 +70,23 @@ is_local_engine_missing() { } if is_remote_http_mcp && is_local_engine_missing; then - cat <<'NOTICE' - - ┌──────────────────────────────────────────────────────────────────┐ - │ gstack v1.37.0.0 — split-engine gbrain │ - │ │ - │ Symbol-aware code search is now available on this machine. │ - │ Your remote brain at gbrain MCP keeps working as today; you can │ - │ add a tiny local PGLite (~30s, no accounts) for `gbrain │ - │ code-def` / `code-refs` / `code-callers` queries per worktree. │ - │ │ - │ Run /setup-gbrain to opt in at Step 4.5. Or skip this notice │ - │ permanently: │ - │ gstack-config set local_code_index_offered true │ - └──────────────────────────────────────────────────────────────────┘ - -NOTICE + # printf, not a heredoc: bash 5.3 heredocs >512B deadlock on macOS when the + # kernel grants 512-byte pipe buffers (pipe-KVA pressure; no F_GETPIPE_SZ). + printf '%s\n' \ + '' \ + ' ┌──────────────────────────────────────────────────────────────────┐' \ + ' │ gstack v1.37.0.0 — split-engine gbrain │' \ + ' │ │' \ + ' │ Symbol-aware code search is now available on this machine. │' \ + ' │ Your remote brain at gbrain MCP keeps working as today; you can │' \ + ' │ add a tiny local PGLite (~30s, no accounts) for `gbrain │' \ + ' │ code-def` / `code-refs` / `code-callers` queries per worktree. │' \ + ' │ │' \ + ' │ Run /setup-gbrain to opt in at Step 4.5. Or skip this notice │' \ + ' │ permanently: │' \ + ' │ gstack-config set local_code_index_offered true │' \ + ' └──────────────────────────────────────────────────────────────────┘' \ + '' fi # Always touch done so we don't print again, regardless of state-match outcome. diff --git a/health/SKILL.md b/health/SKILL.md index e68199dec..5ce1e101a 100644 --- a/health/SKILL.md +++ b/health/SKILL.md @@ -19,7 +19,6 @@ allowed-tools: - ## When to invoke this skill Wraps existing project tools (type checker, linter, @@ -454,7 +453,6 @@ Before calling AskUserQuestion, verify: - [ ] If you split, you checked dependencies between options before firing the chain - [ ] If a per-option Hold fires, you stopped the chain immediately (didn't queue) - ## Artifacts Sync (skill start) ```bash @@ -552,8 +550,6 @@ else fi ``` - - Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once: > gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync? @@ -580,7 +576,6 @@ At skill END before telemetry: "~/.claude/skills/gstack/bin/gstack-brain-sync" --once 2>/dev/null || true ``` - ## Model-Specific Behavioral Patch (claude) The following nudges are tuned for the claude model family. They are @@ -661,7 +656,6 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i Curated jargon list lives at `~/.claude/skills/gstack/scripts/jargon-list.json` (80+ terms). On the first jargon term you encounter this session, Read that file once; treat the `terms` array as the canonical list. The list is repo-owned and may grow between releases. - ## Completeness Principle — Boil the Ocean AI makes completeness cheap, so the complete thing is the goal. Recommend full coverage (tests, edge cases, error paths) — boil the ocean one lake at a time. The only thing out of scope is genuinely unrelated work (rewrites, multi-quarter migrations); flag that as separate scope, never as an excuse for a shortcut. diff --git a/investigate/SKILL.md b/investigate/SKILL.md index 5d54b4256..9be07fe44 100644 --- a/investigate/SKILL.md +++ b/investigate/SKILL.md @@ -56,7 +56,6 @@ gbrain: - ## When to invoke this skill Four phases: investigate, @@ -493,7 +492,6 @@ Before calling AskUserQuestion, verify: - [ ] If you split, you checked dependencies between options before firing the chain - [ ] If a per-option Hold fires, you stopped the chain immediately (didn't queue) - ## Artifacts Sync (skill start) ```bash @@ -591,8 +589,6 @@ else fi ``` - - Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once: > gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync? @@ -619,7 +615,6 @@ At skill END before telemetry: "~/.claude/skills/gstack/bin/gstack-brain-sync" --once 2>/dev/null || true ``` - ## Model-Specific Behavioral Patch (claude) The following nudges are tuned for the claude model family. They are @@ -700,7 +695,6 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i Curated jargon list lives at `~/.claude/skills/gstack/scripts/jargon-list.json` (80+ terms). On the first jargon term you encounter this session, Read that file once; treat the `terms` array as the canonical list. The list is repo-owned and may grow between releases. - ## Completeness Principle — Boil the Ocean AI makes completeness cheap, so the complete thing is the goal. Recommend full coverage (tests, edge cases, error paths) — boil the ocean one lake at a time. The only thing out of scope is genuinely unrelated work (rewrites, multi-quarter migrations); flag that as separate scope, never as an excuse for a shortcut. @@ -829,7 +823,19 @@ Fixing symptoms creates whack-a-mole debugging. Every fix that doesn't address r --- +## Brain Context Load +**Skip this entire section if `gbrain` is not on PATH.** + +Extract 2-4 keywords from the user's request. Search the brain: +`gbrain search ""`. Read the top 3 results with +`gbrain get_page ""`. Use that context to inform your analysis. + +If `gbrain search` returns no results or any non-zero exit, proceed +without brain context. Full search/read protocol + examples: +see `docs/gbrain-write-surfaces.md` §Context Load. + +For structured-data extraction requests ("track this", "extract from emails", "build a tracker"), route to GBrain's data-research skill instead: `gbrain call data-research`. ## Phase 1: Root Cause Investigation @@ -1058,7 +1064,28 @@ staleness detection: if those files are later deleted, the learning can be flagg **Only log genuine discoveries.** Don't log obvious things. Don't log things the user already knows. A good test: would this insight save time in a future session? If yes, log it. +## Save Results to Brain +**Skip this entire section if `gbrain` is not on PATH.** + +After completing this skill, save the output: + +```bash +gbrain put "investigations/" --content "$(cat <<'EOF' +--- +title: "Investigation: " +tags: [investigation, ] +--- + +EOF +)" +``` + +Then extract person/org entities and create stub pages for each one. +Throttle errors (exit 1 with "throttle"/"rate limit"/"busy") and any +other non-zero exit are transient — don't retry inline. Full entity-stub +template, throttle handling, and backlink protocol: +see `docs/gbrain-write-surfaces.md` §Save Template. --- diff --git a/ios-clean/SKILL.md b/ios-clean/SKILL.md index 127649646..f97a274a7 100644 --- a/ios-clean/SKILL.md +++ b/ios-clean/SKILL.md @@ -18,7 +18,6 @@ triggers: - ## When to invoke this skill Cleans up StateServer, DebugOverlay, accessor codegen output, and @@ -456,7 +455,6 @@ Before calling AskUserQuestion, verify: - [ ] If you split, you checked dependencies between options before firing the chain - [ ] If a per-option Hold fires, you stopped the chain immediately (didn't queue) - ## Artifacts Sync (skill start) ```bash @@ -554,8 +552,6 @@ else fi ``` - - Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once: > gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync? @@ -582,7 +578,6 @@ At skill END before telemetry: "~/.claude/skills/gstack/bin/gstack-brain-sync" --once 2>/dev/null || true ``` - ## Model-Specific Behavioral Patch (claude) The following nudges are tuned for the claude model family. They are @@ -663,7 +658,6 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i Curated jargon list lives at `~/.claude/skills/gstack/scripts/jargon-list.json` (80+ terms). On the first jargon term you encounter this session, Read that file once; treat the `terms` array as the canonical list. The list is repo-owned and may grow between releases. - ## Completeness Principle — Boil the Ocean AI makes completeness cheap, so the complete thing is the goal. Recommend full coverage (tests, edge cases, error paths) — boil the ocean one lake at a time. The only thing out of scope is genuinely unrelated work (rewrites, multi-quarter migrations); flag that as separate scope, never as an excuse for a shortcut. diff --git a/ios-design-review/SKILL.md b/ios-design-review/SKILL.md index 904da7589..ac3a1eb4c 100644 --- a/ios-design-review/SKILL.md +++ b/ios-design-review/SKILL.md @@ -17,7 +17,6 @@ triggers: - ## When to invoke this skill Connects to a real @@ -458,7 +457,6 @@ Before calling AskUserQuestion, verify: - [ ] If you split, you checked dependencies between options before firing the chain - [ ] If a per-option Hold fires, you stopped the chain immediately (didn't queue) - ## Artifacts Sync (skill start) ```bash @@ -556,8 +554,6 @@ else fi ``` - - Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once: > gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync? @@ -584,7 +580,6 @@ At skill END before telemetry: "~/.claude/skills/gstack/bin/gstack-brain-sync" --once 2>/dev/null || true ``` - ## Model-Specific Behavioral Patch (claude) The following nudges are tuned for the claude model family. They are @@ -665,7 +660,6 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i Curated jargon list lives at `~/.claude/skills/gstack/scripts/jargon-list.json` (80+ terms). On the first jargon term you encounter this session, Read that file once; treat the `terms` array as the canonical list. The list is repo-owned and may grow between releases. - ## Completeness Principle — Boil the Ocean AI makes completeness cheap, so the complete thing is the goal. Recommend full coverage (tests, edge cases, error paths) — boil the ocean one lake at a time. The only thing out of scope is genuinely unrelated work (rewrites, multi-quarter migrations); flag that as separate scope, never as an excuse for a shortcut. diff --git a/ios-fix/SKILL.md b/ios-fix/SKILL.md index 3ddae1ac0..115df906f 100644 --- a/ios-fix/SKILL.md +++ b/ios-fix/SKILL.md @@ -19,7 +19,6 @@ triggers: - ## When to invoke this skill Takes a bug found by /ios-qa, reads the source, @@ -459,7 +458,6 @@ Before calling AskUserQuestion, verify: - [ ] If you split, you checked dependencies between options before firing the chain - [ ] If a per-option Hold fires, you stopped the chain immediately (didn't queue) - ## Artifacts Sync (skill start) ```bash @@ -557,8 +555,6 @@ else fi ``` - - Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once: > gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync? @@ -585,7 +581,6 @@ At skill END before telemetry: "~/.claude/skills/gstack/bin/gstack-brain-sync" --once 2>/dev/null || true ``` - ## Model-Specific Behavioral Patch (claude) The following nudges are tuned for the claude model family. They are @@ -666,7 +661,6 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i Curated jargon list lives at `~/.claude/skills/gstack/scripts/jargon-list.json` (80+ terms). On the first jargon term you encounter this session, Read that file once; treat the `terms` array as the canonical list. The list is repo-owned and may grow between releases. - ## Completeness Principle — Boil the Ocean AI makes completeness cheap, so the complete thing is the goal. Recommend full coverage (tests, edge cases, error paths) — boil the ocean one lake at a time. The only thing out of scope is genuinely unrelated work (rewrites, multi-quarter migrations); flag that as separate scope, never as an excuse for a shortcut. diff --git a/ios-qa/SKILL.md b/ios-qa/SKILL.md index a5d4575d4..4ff5a42e8 100644 --- a/ios-qa/SKILL.md +++ b/ios-qa/SKILL.md @@ -21,7 +21,6 @@ triggers: - ## When to invoke this skill Connects to a real iPhone via USB @@ -462,7 +461,6 @@ Before calling AskUserQuestion, verify: - [ ] If you split, you checked dependencies between options before firing the chain - [ ] If a per-option Hold fires, you stopped the chain immediately (didn't queue) - ## Artifacts Sync (skill start) ```bash @@ -560,8 +558,6 @@ else fi ``` - - Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once: > gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync? @@ -588,7 +584,6 @@ At skill END before telemetry: "~/.claude/skills/gstack/bin/gstack-brain-sync" --once 2>/dev/null || true ``` - ## Model-Specific Behavioral Patch (claude) The following nudges are tuned for the claude model family. They are @@ -669,7 +664,6 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i Curated jargon list lives at `~/.claude/skills/gstack/scripts/jargon-list.json` (80+ terms). On the first jargon term you encounter this session, Read that file once; treat the `terms` array as the canonical list. The list is repo-owned and may grow between releases. - ## Completeness Principle — Boil the Ocean AI makes completeness cheap, so the complete thing is the goal. Recommend full coverage (tests, edge cases, error paths) — boil the ocean one lake at a time. The only thing out of scope is genuinely unrelated work (rewrites, multi-quarter migrations); flag that as separate scope, never as an excuse for a shortcut. diff --git a/ios-sync/SKILL.md b/ios-sync/SKILL.md index 2f689c4d6..d0ea5c578 100644 --- a/ios-sync/SKILL.md +++ b/ios-sync/SKILL.md @@ -19,7 +19,6 @@ triggers: - ## When to invoke this skill Updates StateServer.swift, DebugOverlay.swift, Package.swift, @@ -456,7 +455,6 @@ Before calling AskUserQuestion, verify: - [ ] If you split, you checked dependencies between options before firing the chain - [ ] If a per-option Hold fires, you stopped the chain immediately (didn't queue) - ## Artifacts Sync (skill start) ```bash @@ -554,8 +552,6 @@ else fi ``` - - Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once: > gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync? @@ -582,7 +578,6 @@ At skill END before telemetry: "~/.claude/skills/gstack/bin/gstack-brain-sync" --once 2>/dev/null || true ``` - ## Model-Specific Behavioral Patch (claude) The following nudges are tuned for the claude model family. They are @@ -663,7 +658,6 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i Curated jargon list lives at `~/.claude/skills/gstack/scripts/jargon-list.json` (80+ terms). On the first jargon term you encounter this session, Read that file once; treat the `terms` array as the canonical list. The list is repo-owned and may grow between releases. - ## Completeness Principle — Boil the Ocean AI makes completeness cheap, so the complete thing is the goal. Recommend full coverage (tests, edge cases, error paths) — boil the ocean one lake at a time. The only thing out of scope is genuinely unrelated work (rewrites, multi-quarter migrations); flag that as separate scope, never as an excuse for a shortcut. diff --git a/land-and-deploy/SKILL.md b/land-and-deploy/SKILL.md index 54ebf52c0..654bcb969 100644 --- a/land-and-deploy/SKILL.md +++ b/land-and-deploy/SKILL.md @@ -17,7 +17,6 @@ triggers: - ## When to invoke this skill Merges the PR, waits for CI and deploy, @@ -451,7 +450,6 @@ Before calling AskUserQuestion, verify: - [ ] If you split, you checked dependencies between options before firing the chain - [ ] If a per-option Hold fires, you stopped the chain immediately (didn't queue) - ## Artifacts Sync (skill start) ```bash @@ -549,8 +547,6 @@ else fi ``` - - Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once: > gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync? @@ -577,7 +573,6 @@ At skill END before telemetry: "~/.claude/skills/gstack/bin/gstack-brain-sync" --once 2>/dev/null || true ``` - ## Model-Specific Behavioral Patch (claude) The following nudges are tuned for the claude model family. They are @@ -658,7 +653,6 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i Curated jargon list lives at `~/.claude/skills/gstack/scripts/jargon-list.json` (80+ terms). On the first jargon term you encounter this session, Read that file once; treat the `terms` array as the canonical list. The list is repo-owned and may grow between releases. - ## Completeness Principle — Boil the Ocean AI makes completeness cheap, so the complete thing is the goal. Recommend full coverage (tests, edge cases, error paths) — boil the ocean one lake at a time. The only thing out of scope is genuinely unrelated work (rewrites, multi-quarter migrations); flag that as separate scope, never as an excuse for a shortcut. diff --git a/landing-report/SKILL.md b/landing-report/SKILL.md index 8f7e6e210..ca03d53bd 100644 --- a/landing-report/SKILL.md +++ b/landing-report/SKILL.md @@ -15,7 +15,6 @@ allowed-tools: - ## When to invoke this skill Shows which VERSION slots @@ -452,7 +451,6 @@ Before calling AskUserQuestion, verify: - [ ] If you split, you checked dependencies between options before firing the chain - [ ] If a per-option Hold fires, you stopped the chain immediately (didn't queue) - ## Artifacts Sync (skill start) ```bash @@ -550,8 +548,6 @@ else fi ``` - - Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once: > gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync? @@ -578,7 +574,6 @@ At skill END before telemetry: "~/.claude/skills/gstack/bin/gstack-brain-sync" --once 2>/dev/null || true ``` - ## Model-Specific Behavioral Patch (claude) The following nudges are tuned for the claude model family. They are @@ -659,7 +654,6 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i Curated jargon list lives at `~/.claude/skills/gstack/scripts/jargon-list.json` (80+ terms). On the first jargon term you encounter this session, Read that file once; treat the `terms` array as the canonical list. The list is repo-owned and may grow between releases. - ## Completeness Principle — Boil the Ocean AI makes completeness cheap, so the complete thing is the goal. Recommend full coverage (tests, edge cases, error paths) — boil the ocean one lake at a time. The only thing out of scope is genuinely unrelated work (rewrites, multi-quarter migrations); flag that as separate scope, never as an excuse for a shortcut. diff --git a/learn/SKILL.md b/learn/SKILL.md index a0c6ae053..8c3bd2071 100644 --- a/learn/SKILL.md +++ b/learn/SKILL.md @@ -19,7 +19,6 @@ allowed-tools: - ## When to invoke this skill Review, search, prune, and export what gstack @@ -454,7 +453,6 @@ Before calling AskUserQuestion, verify: - [ ] If you split, you checked dependencies between options before firing the chain - [ ] If a per-option Hold fires, you stopped the chain immediately (didn't queue) - ## Artifacts Sync (skill start) ```bash @@ -552,8 +550,6 @@ else fi ``` - - Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once: > gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync? @@ -580,7 +576,6 @@ At skill END before telemetry: "~/.claude/skills/gstack/bin/gstack-brain-sync" --once 2>/dev/null || true ``` - ## Model-Specific Behavioral Patch (claude) The following nudges are tuned for the claude model family. They are @@ -661,7 +656,6 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i Curated jargon list lives at `~/.claude/skills/gstack/scripts/jargon-list.json` (80+ terms). On the first jargon term you encounter this session, Read that file once; treat the `terms` array as the canonical list. The list is repo-owned and may grow between releases. - ## Completeness Principle — Boil the Ocean AI makes completeness cheap, so the complete thing is the goal. Recommend full coverage (tests, edge cases, error paths) — boil the ocean one lake at a time. The only thing out of scope is genuinely unrelated work (rewrites, multi-quarter migrations); flag that as separate scope, never as an excuse for a shortcut. @@ -950,4 +944,3 @@ Then log it: ```bash ~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"learn","type":"TYPE","key":"KEY","insight":"INSIGHT","confidence":N,"source":"user-stated","files":["FILE1"]}' -``` diff --git a/make-pdf/SKILL.md b/make-pdf/SKILL.md index 600eb47ca..c89a0e8a4 100644 --- a/make-pdf/SKILL.md +++ b/make-pdf/SKILL.md @@ -16,7 +16,6 @@ allowed-tools: - ## When to invoke this skill Proper 1in margins, @@ -462,8 +461,6 @@ else fi ``` - - Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once: > gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync? @@ -490,7 +487,6 @@ At skill END before telemetry: "~/.claude/skills/gstack/bin/gstack-brain-sync" --once 2>/dev/null || true ``` - ## Model-Specific Behavioral Patch (claude) The following nudges are tuned for the claude model family. They are diff --git a/office-hours/SKILL.md b/office-hours/SKILL.md index 83161b8ca..ad2e1c436 100644 --- a/office-hours/SKILL.md +++ b/office-hours/SKILL.md @@ -48,7 +48,6 @@ gbrain: - ## When to invoke this skill Startup mode: six forcing questions that expose @@ -489,7 +488,6 @@ Before calling AskUserQuestion, verify: - [ ] If you split, you checked dependencies between options before firing the chain - [ ] If a per-option Hold fires, you stopped the chain immediately (didn't queue) - ## Artifacts Sync (skill start) ```bash @@ -587,8 +585,6 @@ else fi ``` - - Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once: > gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync? @@ -615,7 +611,6 @@ At skill END before telemetry: "~/.claude/skills/gstack/bin/gstack-brain-sync" --once 2>/dev/null || true ``` - ## Model-Specific Behavioral Patch (claude) The following nudges are tuned for the claude model family. They are @@ -696,7 +691,6 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i Curated jargon list lives at `~/.claude/skills/gstack/scripts/jargon-list.json` (80+ terms). On the first jargon term you encounter this session, Read that file once; treat the `terms` array as the canonical list. The list is repo-owned and may grow between releases. - ## Completeness Principle — Boil the Ocean AI makes completeness cheap, so the complete thing is the goal. Recommend full coverage (tests, edge cases, error paths) — boil the ocean one lake at a time. The only thing out of scope is genuinely unrelated work (rewrites, multi-quarter migrations); flag that as separate scope, never as an excuse for a shortcut. @@ -877,7 +871,17 @@ You are a **YC office hours partner**. Your job is to ensure the problem is unde --- +## Brain Context Load +**Skip this entire section if `gbrain` is not on PATH.** + +Extract 2-4 keywords from the user's request. Search the brain: +`gbrain search ""`. Read the top 3 results with +`gbrain get_page ""`. Use that context to inform your analysis. + +If `gbrain search` returns no results or any non-zero exit, proceed +without brain context. Full search/read protocol + examples: +see `docs/gbrain-write-surfaces.md` §Context Load. ## Brain Context (preflight) @@ -916,7 +920,6 @@ rm -f /tmp/.gstack-brain-context-$$.md 2>/dev/null || true **Privacy:** Salience digest is filtered by allowlist (D9 default: `projects/`, `gstack/`, `concepts/` only). Personal/family/therapy content never leaks here. - ## Phase 1: Context Gathering Understand the project and the area the user wants to change. @@ -999,7 +1002,6 @@ Output: "Here's what I understand about this project and the area you want to ch --- - --- ## Section index — Read each section when its situation applies diff --git a/office-hours/sections/design-and-handoff.md b/office-hours/sections/design-and-handoff.md index 4c253e96a..30fcc9a6b 100644 --- a/office-hours/sections/design-and-handoff.md +++ b/office-hours/sections/design-and-handoff.md @@ -209,7 +209,28 @@ 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 +## Save Results to Brain +**Skip this entire section if `gbrain` is not on PATH.** + +After completing this skill, save the output: + +```bash +gbrain put "office-hours/" --content "$(cat <<'EOF' +--- +title: "Office Hours: " +tags: [design-doc, ] +--- + +EOF +)" +``` + +Then extract person/org entities and create stub pages for each one. +Throttle errors (exit 1 with "throttle"/"rate limit"/"busy") and any +other non-zero exit are transient — don't retry inline. Full entity-stub +template, throttle handling, and backlink protocol: +see `docs/gbrain-write-surfaces.md` §Save Template. ## Brain Calibration Write-Back (Phase 2 / gated) diff --git a/open-gstack-browser/SKILL.md b/open-gstack-browser/SKILL.md index 28fb1ddb2..c79426a96 100644 --- a/open-gstack-browser/SKILL.md +++ b/open-gstack-browser/SKILL.md @@ -15,7 +15,6 @@ allowed-tools: - ## When to invoke this skill Opens a visible browser window where you can watch every action in real time. @@ -451,7 +450,6 @@ Before calling AskUserQuestion, verify: - [ ] If you split, you checked dependencies between options before firing the chain - [ ] If a per-option Hold fires, you stopped the chain immediately (didn't queue) - ## Artifacts Sync (skill start) ```bash @@ -549,8 +547,6 @@ else fi ``` - - Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once: > gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync? @@ -577,7 +573,6 @@ At skill END before telemetry: "~/.claude/skills/gstack/bin/gstack-brain-sync" --once 2>/dev/null || true ``` - ## Model-Specific Behavioral Patch (claude) The following nudges are tuned for the claude model family. They are @@ -658,7 +653,6 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i Curated jargon list lives at `~/.claude/skills/gstack/scripts/jargon-list.json` (80+ terms). On the first jargon term you encounter this session, Read that file once; treat the `terms` array as the canonical list. The list is repo-owned and may grow between releases. - ## Completeness Principle — Boil the Ocean AI makes completeness cheap, so the complete thing is the goal. Recommend full coverage (tests, edge cases, error paths) — boil the ocean one lake at a time. The only thing out of scope is genuinely unrelated work (rewrites, multi-quarter migrations); flag that as separate scope, never as an excuse for a shortcut. diff --git a/pair-agent/SKILL.md b/pair-agent/SKILL.md index eed9d171a..c273929cb 100644 --- a/pair-agent/SKILL.md +++ b/pair-agent/SKILL.md @@ -15,7 +15,6 @@ allowed-tools: - ## When to invoke this skill One command generates a setup key and @@ -453,7 +452,6 @@ Before calling AskUserQuestion, verify: - [ ] If you split, you checked dependencies between options before firing the chain - [ ] If a per-option Hold fires, you stopped the chain immediately (didn't queue) - ## Artifacts Sync (skill start) ```bash @@ -551,8 +549,6 @@ else fi ``` - - Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once: > gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync? @@ -579,7 +575,6 @@ At skill END before telemetry: "~/.claude/skills/gstack/bin/gstack-brain-sync" --once 2>/dev/null || true ``` - ## Model-Specific Behavioral Patch (claude) The following nudges are tuned for the claude model family. They are @@ -660,7 +655,6 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i Curated jargon list lives at `~/.claude/skills/gstack/scripts/jargon-list.json` (80+ terms). On the first jargon term you encounter this session, Read that file once; treat the `terms` array as the canonical list. The list is repo-owned and may grow between releases. - ## Completeness Principle — Boil the Ocean AI makes completeness cheap, so the complete thing is the goal. Recommend full coverage (tests, edge cases, error paths) — boil the ocean one lake at a time. The only thing out of scope is genuinely unrelated work (rewrites, multi-quarter migrations); flag that as separate scope, never as an excuse for a shortcut. @@ -1043,7 +1037,6 @@ OpenClaw agents use the `exec` tool instead of `Bash`. The instruction block use `exec curl` syntax which OpenClaw understands natively. When using `--local openclaw`, credentials are written to `~/.openclaw/skills/gstack/browse-remote.json`. - ### Codex Codex agents can execute shell commands via `codex exec`. The instruction block's @@ -1069,4 +1062,3 @@ To disconnect all agents and rotate the root token: ```bash # This invalidates ALL scoped tokens immediately $B tunnel rotate -``` diff --git a/plan-ceo-review/SKILL.md b/plan-ceo-review/SKILL.md index 3d3208bee..f10dd0d17 100644 --- a/plan-ceo-review/SKILL.md +++ b/plan-ceo-review/SKILL.md @@ -45,7 +45,6 @@ gbrain: - ## When to invoke this skill Rethink the problem, find the 10-star product, @@ -483,7 +482,6 @@ Before calling AskUserQuestion, verify: - [ ] If you split, you checked dependencies between options before firing the chain - [ ] If a per-option Hold fires, you stopped the chain immediately (didn't queue) - ## Artifacts Sync (skill start) ```bash @@ -581,8 +579,6 @@ else fi ``` - - Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once: > gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync? @@ -609,7 +605,6 @@ At skill END before telemetry: "~/.claude/skills/gstack/bin/gstack-brain-sync" --once 2>/dev/null || true ``` - ## Model-Specific Behavioral Patch (claude) The following nudges are tuned for the claude model family. They are @@ -690,7 +685,6 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i Curated jargon list lives at `~/.claude/skills/gstack/scripts/jargon-list.json` (80+ terms). On the first jargon term you encounter this session, Read that file once; treat the `terms` array as the canonical list. The list is repo-owned and may grow between releases. - ## Completeness Principle — Boil the Ocean AI makes completeness cheap, so the complete thing is the goal. Recommend full coverage (tests, edge cases, error paths) — boil the ocean one lake at a time. The only thing out of scope is genuinely unrelated work (rewrites, multi-quarter migrations); flag that as separate scope, never as an excuse for a shortcut. @@ -1140,7 +1134,17 @@ matches a past learning, display: This makes the compounding visible. The user should see that gstack is getting smarter on their codebase over time. +## Brain Context Load +**Skip this entire section if `gbrain` is not on PATH.** + +Extract 2-4 keywords from the user's request. Search the brain: +`gbrain search ""`. Read the top 3 results with +`gbrain get_page ""`. Use that context to inform your analysis. + +If `gbrain search` returns no results or any non-zero exit, proceed +without brain context. Full search/read protocol + examples: +see `docs/gbrain-write-surfaces.md` §Context Load. ## Brain Context (preflight) @@ -1177,7 +1181,6 @@ rm -f /tmp/.gstack-brain-context-$$.md 2>/dev/null || true **Privacy:** Salience digest is filtered by allowlist (D9 default: `projects/`, `gstack/`, `concepts/` only). Personal/family/therapy content never leaks here. - ## Section index — Read each section when its situation applies This skill is a decision-tree skeleton. The steps below point to on-demand @@ -1444,7 +1447,6 @@ file, not from memory. If you produced the Completion Summary or wrote the revie report without Reading that section, STOP, Read it now, and redo the review from the source of truth. - ## EXIT PLAN MODE GATE (BLOCKING) Before calling ExitPlanMode, run this self-check. If any item fails, do the diff --git a/plan-ceo-review/sections/review-sections.md b/plan-ceo-review/sections/review-sections.md index 71bae4d93..f467198fd 100644 --- a/plan-ceo-review/sections/review-sections.md +++ b/plan-ceo-review/sections/review-sections.md @@ -828,7 +828,28 @@ staleness detection: if those files are later deleted, the learning can be flagg **Only log genuine discoveries.** Don't log obvious things. Don't log things the user already knows. A good test: would this insight save time in a future session? If yes, log it. +## Save Results to Brain +**Skip this entire section if `gbrain` is not on PATH.** + +After completing this skill, save the output: + +```bash +gbrain put "ceo-plans/" --content "$(cat <<'EOF' +--- +title: "CEO Plan: " +tags: [ceo-plan, ] +--- + +EOF +)" +``` + +Then extract person/org entities and create stub pages for each one. +Throttle errors (exit 1 with "throttle"/"rate limit"/"busy") and any +other non-zero exit are transient — don't retry inline. Full entity-stub +template, throttle handling, and backlink protocol: +see `docs/gbrain-write-surfaces.md` §Save Template. ## Brain Calibration Write-Back (Phase 2 / gated) diff --git a/plan-design-review/SKILL.md b/plan-design-review/SKILL.md index e81f7f12a..f8c354518 100644 --- a/plan-design-review/SKILL.md +++ b/plan-design-review/SKILL.md @@ -19,7 +19,6 @@ triggers: - ## When to invoke this skill Rates each design dimension 0-10, explains what would make it a 10, @@ -455,7 +454,6 @@ Before calling AskUserQuestion, verify: - [ ] If you split, you checked dependencies between options before firing the chain - [ ] If a per-option Hold fires, you stopped the chain immediately (didn't queue) - ## Artifacts Sync (skill start) ```bash @@ -553,8 +551,6 @@ else fi ``` - - Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once: > gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync? @@ -581,7 +577,6 @@ At skill END before telemetry: "~/.claude/skills/gstack/bin/gstack-brain-sync" --once 2>/dev/null || true ``` - ## Model-Specific Behavioral Patch (claude) The following nudges are tuned for the claude model family. They are @@ -662,7 +657,6 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i Curated jargon list lives at `~/.claude/skills/gstack/scripts/jargon-list.json` (80+ terms). On the first jargon term you encounter this session, Read that file once; treat the `terms` array as the canonical list. The list is repo-owned and may grow between releases. - ## Completeness Principle — Boil the Ocean AI makes completeness cheap, so the complete thing is the goal. Recommend full coverage (tests, edge cases, error paths) — boil the ocean one lake at a time. The only thing out of scope is genuinely unrelated work (rewrites, multi-quarter migrations); flag that as separate scope, never as an excuse for a shortcut. @@ -1122,7 +1116,6 @@ rm -f /tmp/.gstack-brain-context-$$.md 2>/dev/null || true **Privacy:** Salience digest is filtered by allowlist (D9 default: `projects/`, `gstack/`, `concepts/` only). Personal/family/therapy content never leaks here. - --- ## Section index — Read each section when its situation applies @@ -1134,7 +1127,6 @@ sections. Read a section in full before doing its step; do not work from memory. | running the 7 design passes, required outputs, and review report (only after Step 0 scope is agreed) | `sections/review-sections.md` | --- - ## Step 0: Design Scope Assessment ### 0A. Initial Design Rating diff --git a/plan-design-review/sections/review-sections.md b/plan-design-review/sections/review-sections.md index fde4b79f9..a3859eba9 100644 --- a/plan-design-review/sections/review-sections.md +++ b/plan-design-review/sections/review-sections.md @@ -531,7 +531,28 @@ staleness detection: if those files are later deleted, the learning can be flagg **Only log genuine discoveries.** Don't log obvious things. Don't log things the user already knows. A good test: would this insight save time in a future session? If yes, log it. +## Save Results to Brain +**Skip this entire section if `gbrain` is not on PATH.** + +After completing this skill, save the output: + +```bash +gbrain put "design-reviews/" --content "$(cat <<'EOF' +--- +title: "Design Review: " +tags: [design-review, ] +--- + +EOF +)" +``` + +Then extract person/org entities and create stub pages for each one. +Throttle errors (exit 1 with "throttle"/"rate limit"/"busy") and any +other non-zero exit are transient — don't retry inline. Full entity-stub +template, throttle handling, and backlink protocol: +see `docs/gbrain-write-surfaces.md` §Save Template. ## Brain Calibration Write-Back (Phase 2 / gated) diff --git a/plan-devex-review/SKILL.md b/plan-devex-review/SKILL.md index 20a32da8b..b5d13b7bc 100644 --- a/plan-devex-review/SKILL.md +++ b/plan-devex-review/SKILL.md @@ -21,7 +21,6 @@ triggers: - ## When to invoke this skill Explores developer personas, @@ -461,7 +460,6 @@ Before calling AskUserQuestion, verify: - [ ] If you split, you checked dependencies between options before firing the chain - [ ] If a per-option Hold fires, you stopped the chain immediately (didn't queue) - ## Artifacts Sync (skill start) ```bash @@ -559,8 +557,6 @@ else fi ``` - - Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once: > gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync? @@ -587,7 +583,6 @@ At skill END before telemetry: "~/.claude/skills/gstack/bin/gstack-brain-sync" --once 2>/dev/null || true ``` - ## Model-Specific Behavioral Patch (claude) The following nudges are tuned for the claude model family. They are @@ -668,7 +663,6 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i Curated jargon list lives at `~/.claude/skills/gstack/scripts/jargon-list.json` (80+ terms). On the first jargon term you encounter this session, Read that file once; treat the `terms` array as the canonical list. The list is repo-owned and may grow between releases. - ## Completeness Principle — Boil the Ocean AI makes completeness cheap, so the complete thing is the goal. Recommend full coverage (tests, edge cases, error paths) — boil the ocean one lake at a time. The only thing out of scope is genuinely unrelated work (rewrites, multi-quarter migrations); flag that as separate scope, never as an excuse for a shortcut. @@ -1100,7 +1094,6 @@ rm -f /tmp/.gstack-brain-context-$$.md 2>/dev/null || true **Privacy:** Salience digest is filtered by allowlist (D9 default: `projects/`, `gstack/`, `concepts/` only). Personal/family/therapy content never leaks here. - --- ## Section index — Read each section when its situation applies @@ -1112,7 +1105,6 @@ sections. Read a section in full before doing its step; do not work from memory. | running the 8 DX passes, required outputs, and review report (only after Step 0 investigation is complete) | `sections/review-sections.md` | --- - ## Step 0: DX Investigation (before scoring) The core principle: **gather evidence and force decisions BEFORE scoring, not during diff --git a/plan-devex-review/sections/review-sections.md b/plan-devex-review/sections/review-sections.md index e4ce30a95..5c5ee0bcd 100644 --- a/plan-devex-review/sections/review-sections.md +++ b/plan-devex-review/sections/review-sections.md @@ -769,7 +769,28 @@ staleness detection: if those files are later deleted, the learning can be flagg **Only log genuine discoveries.** Don't log obvious things. Don't log things the user already knows. A good test: would this insight save time in a future session? If yes, log it. +## Save Results to Brain +**Skip this entire section if `gbrain` is not on PATH.** + +After completing this skill, save the output: + +```bash +gbrain put "devex-reviews/" --content "$(cat <<'EOF' +--- +title: "Devex Review: " +tags: [devex-review, ] +--- + +EOF +)" +``` + +Then extract person/org entities and create stub pages for each one. +Throttle errors (exit 1 with "throttle"/"rate limit"/"busy") and any +other non-zero exit are transient — don't retry inline. Full entity-stub +template, throttle handling, and backlink protocol: +see `docs/gbrain-write-surfaces.md` §Save Template. ## Brain Calibration Write-Back (Phase 2 / gated) diff --git a/plan-eng-review/SKILL.md b/plan-eng-review/SKILL.md index 5557a33fa..3461ae78d 100644 --- a/plan-eng-review/SKILL.md +++ b/plan-eng-review/SKILL.md @@ -21,7 +21,6 @@ triggers: - ## When to invoke this skill Lock in the execution plan — architecture, @@ -459,7 +458,6 @@ Before calling AskUserQuestion, verify: - [ ] If you split, you checked dependencies between options before firing the chain - [ ] If a per-option Hold fires, you stopped the chain immediately (didn't queue) - ## Artifacts Sync (skill start) ```bash @@ -557,8 +555,6 @@ else fi ``` - - Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once: > gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync? @@ -585,7 +581,6 @@ At skill END before telemetry: "~/.claude/skills/gstack/bin/gstack-brain-sync" --once 2>/dev/null || true ``` - ## Model-Specific Behavioral Patch (claude) The following nudges are tuned for the claude model family. They are @@ -666,7 +661,6 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i Curated jargon list lives at `~/.claude/skills/gstack/scripts/jargon-list.json` (80+ terms). On the first jargon term you encounter this session, Read that file once; treat the `terms` array as the canonical list. The list is repo-owned and may grow between releases. - ## Completeness Principle — Boil the Ocean AI makes completeness cheap, so the complete thing is the goal. Recommend full coverage (tests, edge cases, error paths) — boil the ocean one lake at a time. The only thing out of scope is genuinely unrelated work (rewrites, multi-quarter migrations); flag that as separate scope, never as an excuse for a shortcut. @@ -803,7 +797,17 @@ Replace `SKILL_NAME`, `OUTCOME`, and `USED_BROWSE` before running. Skills that run plan reviews (`/plan-*-review`, `/codex review`) include the EXIT PLAN MODE GATE blocking checklist at the end of the skill, which verifies the plan file ends with `## GSTACK REVIEW REPORT` before ExitPlanMode is called. Skills that don't run plan reviews (operational skills like `/ship`, `/qa`, `/review`) typically don't operate in plan mode and have no review report to verify; this footer is a no-op for them. Writing the plan file is the one edit allowed in plan mode. +## Brain Context Load +**Skip this entire section if `gbrain` is not on PATH.** + +Extract 2-4 keywords from the user's request. Search the brain: +`gbrain search ""`. Read the top 3 results with +`gbrain get_page ""`. Use that context to inform your analysis. + +If `gbrain search` returns no results or any non-zero exit, proceed +without brain context. Full search/read protocol + examples: +see `docs/gbrain-write-surfaces.md` §Context Load. # Plan Review Mode @@ -893,7 +897,6 @@ rm -f /tmp/.gstack-brain-context-$$.md 2>/dev/null || true **Privacy:** Salience digest is filtered by allowlist (D9 default: `projects/`, `gstack/`, `concepts/` only). Personal/family/therapy content never leaks here. - --- ## Section index — Read each section when its situation applies @@ -905,7 +908,6 @@ sections. Read a section in full before doing its step; do not work from memory. | running the 4-section review, outside voice, required outputs, and review report (only after Step 0 scope is agreed) | `sections/review-sections.md` | --- - ## BEFORE YOU START: ### Design Doc Check diff --git a/plan-eng-review/sections/review-sections.md b/plan-eng-review/sections/review-sections.md index 7592f0a70..dc6329fab 100644 --- a/plan-eng-review/sections/review-sections.md +++ b/plan-eng-review/sections/review-sections.md @@ -849,7 +849,28 @@ staleness detection: if those files are later deleted, the learning can be flagg **Only log genuine discoveries.** Don't log obvious things. Don't log things the user already knows. A good test: would this insight save time in a future session? If yes, log it. +## Save Results to Brain +**Skip this entire section if `gbrain` is not on PATH.** + +After completing this skill, save the output: + +```bash +gbrain put "eng-reviews/" --content "$(cat <<'EOF' +--- +title: "Eng Review: " +tags: [eng-review, ] +--- + +EOF +)" +``` + +Then extract person/org entities and create stub pages for each one. +Throttle errors (exit 1 with "throttle"/"rate limit"/"busy") and any +other non-zero exit are transient — don't retry inline. Full entity-stub +template, throttle handling, and backlink protocol: +see `docs/gbrain-write-surfaces.md` §Save Template. ## Brain Calibration Write-Back (Phase 2 / gated) diff --git a/plan-tune/SKILL.md b/plan-tune/SKILL.md index f49b66fac..c9d013bd5 100644 --- a/plan-tune/SKILL.md +++ b/plan-tune/SKILL.md @@ -23,7 +23,6 @@ allowed-tools: - ## When to invoke this skill Review which AskUserQuestion prompts fire across gstack skills, set per-question preferences @@ -464,7 +463,6 @@ Before calling AskUserQuestion, verify: - [ ] If you split, you checked dependencies between options before firing the chain - [ ] If a per-option Hold fires, you stopped the chain immediately (didn't queue) - ## Artifacts Sync (skill start) ```bash @@ -562,8 +560,6 @@ else fi ``` - - Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once: > gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync? @@ -590,7 +586,6 @@ At skill END before telemetry: "~/.claude/skills/gstack/bin/gstack-brain-sync" --once 2>/dev/null || true ``` - ## Model-Specific Behavioral Patch (claude) The following nudges are tuned for the claude model family. They are @@ -671,7 +666,6 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i Curated jargon list lives at `~/.claude/skills/gstack/scripts/jargon-list.json` (80+ terms). On the first jargon term you encounter this session, Read that file once; treat the `terms` array as the canonical list. The list is repo-owned and may grow between releases. - ## Completeness Principle — Boil the Ocean AI makes completeness cheap, so the complete thing is the goal. Recommend full coverage (tests, edge cases, error paths) — boil the ocean one lake at a time. The only thing out of scope is genuinely unrelated work (rewrites, multi-quarter migrations); flag that as separate scope, never as an excuse for a shortcut. diff --git a/pr-prep/SKILL.md b/pr-prep/SKILL.md index 809914e46..9edb76756 100644 --- a/pr-prep/SKILL.md +++ b/pr-prep/SKILL.md @@ -21,7 +21,6 @@ triggers: - ## When to invoke this skill Walks `git log base..HEAD`, derives @@ -58,6 +57,24 @@ echo "REPO_MODE: $REPO_MODE" _SESSION_KIND=$(~/.claude/skills/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: AskUserQuestion 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=$(~/.claude/skills/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=$(~/.claude/skills/gstack/bin/gstack-config get telemetry 2>/dev/null || true) @@ -227,6 +244,24 @@ 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 +~/.claude/skills/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 CLAUDE.md file exists in the project root. If it does not exist, create it. @@ -307,7 +342,9 @@ AI orchestrator (e.g., OpenClaw). In spawned sessions: "AskUserQuestion" can resolve to two tools at runtime: the **host MCP variant** (e.g. `mcp__conductor__AskUserQuestion` — appears in your tool list when the host registers it) or the **native** Claude Code tool. -**Rule:** if any `mcp__*__AskUserQuestion` variant is in your tool list, prefer it. Hosts may disable native AUQ via `--disallowedTools AskUserQuestion` (Conductor does, by default) and route through their MCP variant; calling native there silently fails. Same questions/options shape; same decision-brief format applies. +**Conductor rule (read before the MCP rule):** if `CONDUCTOR_SESSION: true` was echoed by the preamble, do NOT call AskUserQuestion at all — neither native nor any `mcp__*__AskUserQuestion` 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] →