diff --git a/AGENTS.md b/AGENTS.md index 161e31798..a3d1fdb48 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -21,6 +21,7 @@ Invoke them by name (e.g., `/office-hours`). | `/plan-tune` | Self-tune AskUserQuestion sensitivity per question. | | `/autoplan` | One command runs CEO → design → eng → DX review. | | `/design-consultation` | Build a complete design system from scratch. | +| `/spec` | Turn vague intent into a precise, executable spec in five phases. Files a GitHub issue, optionally spawns a Claude Code agent in a fresh worktree, and lets `/ship` close the source issue on merge. | ### Implementation + review diff --git a/CHANGELOG.md b/CHANGELOG.md index a126d4c13..d0051169e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,124 @@ # Changelog +## [1.47.0.0] - 2026-05-26 + +## **`/spec` ships: turn vague intent into a precise, executable spec in five phases.** Pipe the spec into a spawned Claude Code agent, dedupe against existing issues, archive locally for the team corpus, and let `/ship` close the source issue on merge. + +A precise spec collapses an agent's clarification roundtrips from N to zero. `/spec` is the verb that turns thoughts into commits: five strict phases (why, scope, technical with mandatory code-reading, draft, file), a codex quality gate before file, archive to `$GSTACK_STATE_ROOT/projects/$SLUG/specs/`, and optional pipeline-mode spawn into a fresh worktree. Plan-mode aware: in plan mode `/spec` files the issue and loads the spec into your active plan file; in execution mode it files the issue and spawns `claude -p` in a fresh worktree by default. `/ship` reads the archive frontmatter and auto-closes the source issue on full delivery. Adapted from a community-contributed `/issue` skill (PR #1698 by @jayzalowitz) with rename, race+security hardening, and DX polish. + +`/spec` is the first skill registered against the v1.46 eval-first floor (`test/skill-coverage-matrix.ts`), passing all six structural floor checks plus 37 deterministic invariant assertions specific to `/spec`'s contract. Skill catalog count: 51 → 52. + +### The numbers that matter + +Source: 1 contributor commit + 8 follow-on bundled fixes/expansions on this branch (`git log v1.46.0.0..HEAD --oneline`). Template at `spec/SKILL.md.tmpl` (404 → ~750 lines after expansions), 4 new test files (37 deterministic scenarios + 2 periodic-tier stubs). + +| Capability | Without `/spec` | With `/spec` | +|---|---|---| +| Author backlog-ready issue | freehand prose, sloppy AC, no file refs, 10-15 min per issue | 5-phase interrogation with hard-grep Phase 3, file-refs at `path:line`, quantified impact, ~4 min | +| Spec → agent execution | copy-paste into new `claude -p` session, ~30s context-switch friction | `--execute` spawns automatically in fresh worktree `spec/-$$`, zero hand-off | +| Catch ambiguity before file | none (you find out when the implementer asks) | codex quality gate scores 0-10, blocks below 7, lists ambiguities, up to 3 iterations | +| Secret leakage to second-AI judge | possible if spec contains pasted secret | fail-closed redaction blocks dispatch on AWS/GitHub/Anthropic key patterns + private key blocks | +| Concurrent `/spec` runs | branch/archive collisions on same second | unique `spec/-$$` branches, atomic `.tmp/mv` archive write, PID-suffixed filenames | +| Linked issue closure | manual `Closes #N` in PR body | `/ship` auto-adds when archive present AND full spec delivered | + +### What this means for builders + +Type `/spec` on a vague bug; four minutes later you have a filed GitHub issue with file refs and a Claude Code agent already executing it in a fresh worktree. When `/ship` lands the PR, the source issue auto-closes. The corpus of past specs in `$GSTACK_STATE_ROOT/projects/$SLUG/specs/` is mineable by `gbrain` for cross-session pattern recall. `--no-gate`, `--no-execute`, `--file-only`, and `--plan-file ` are escape hatches when the defaults don't fit; `--audit` routes to the Audit/Cleanup template structure. + +### Itemized changes + +#### Added +- `/spec` skill (renamed from contributor's `/issue`): five-phase interrogation producing backlog-ready specs. Lives at `spec/SKILL.md.tmpl`. +- `--dedupe` flag (default ON): `gh issue list --search` before drafting, surfaces near-duplicates via AskUserQuestion; graceful skip on `gh` missing/unauthed/rate-limited. +- `--execute` flag (default ON in execution mode): spawns `claude -p` in a fresh Conductor worktree on branch `spec/-$$`, with dirty-worktree gate, TOCTOU re-check after AskUserQuestion answer, SHA pin via `git rev-parse HEAD`, and mandatory final-confirm gate. +- Quality-score gate (default ON): codex adversarial dispatch with hard `<<>>` delimiter + instruction boundary, score 0-10, blocks at <7, up to 3 iterations, AskUserQuestion escape on persistent <7 (ship anyway / save draft / one more try). +- Fail-closed redaction in quality gate: regex match against AWS access keys (`AKIA...`), GitHub tokens (`ghp_/gho_/ghs_`), Anthropic keys (`sk-ant-...`), OpenAI keys, `.env`-style `KEY=value`, and `-----BEGIN ... PRIVATE KEY-----` blocks → block dispatch entirely. Raw spec never persisted to archive or transcript on block. +- `--audit` flag routes Phase 5 to the Audit/Cleanup template structure. +- `--file-only` / `--no-execute` / `--plan-file ` overrides for plan-mode-aware Phase 5 default. +- `--sync-archive` opt-in for cross-machine spec sync (archives stay local by default; `/specs/` excluded from artifacts-sync allowlist). +- Spec archive: writes to `$GSTACK_STATE_ROOT/projects/$SLUG/specs/--.md` via existing `gstack-paths` resolver (handles `GSTACK_HOME`, `CLAUDE_PLUGIN_DATA`, Windows fallback). Atomic `.tmp/mv` write prevents collision on concurrent runs. +- `GSTACK_PLAN_MODE` env var: emitted by `{{PREAMBLE}}` based on `CLAUDE_PLAN_FILE` presence. Skills can branch behavior on plan-mode state without parsing system reminders. +- `/spec` entry in the gstack routing block injected into project CLAUDE.md. +- `/ship` PR body integration: reads `spec_issue_number` from archive frontmatter and adds `Closes #N` when the spec is fully delivered per the existing plan-completion gate. Partial delivery emits a "Linked to #N (not auto-closing)" notice instead. +- `/spec` entry in `test/skill-coverage-matrix.ts` (52nd skill, eval-first floor compliance per v1.46 contract). + +#### Tests +- `test/spec-template-invariants.test.ts`: 35 deterministic invariants covering Phase 1 hard gate, Phase 3 hard-grep mandate, `--dedupe` graceful-skip paths, `--execute` race + security hardening (TOCTOU re-check, SHA pin, unique branch), quality-gate redaction patterns and BLOCKED path, archive atomic write + sync exclusion, plan-mode-aware Phase 5 dispatch. +- `test/spec-template-sync.test.ts`: regenerates `spec/SKILL.md` and asserts byte-identical output (prevents template-vs-generated drift). +- `test/skill-e2e-spec-execute.test.ts` (periodic-tier): full `/spec --execute` pipeline scaffold registered in `E2E_TIERS`. +- `test/skill-llm-eval-spec.test.ts` (periodic-tier): authored-spec quality eval against the 14-Quality-Standards rubric. + +#### Fixed +- Duplicate analytics block in `spec/SKILL.md.tmpl` (was bypassing the `_TEL != "off"` opt-out gate; `{{PREAMBLE}}` already emits the analytics write with the guard). + +#### For contributors +- Community contribution: PR #1698 by @jayzalowitz (Jay Zalowitz) lands as the foundation commit with original authorship preserved. Contributor's 5 phases, 14 Quality Standards, and Standard/Epic/Audit templates carried forward intact; expansions are additive. +- Plan reviewed across `/plan-ceo-review` (SCOPE EXPANSION, 5 of 6 expansions accepted), `/plan-eng-review` (race + security hardening), and `/plan-devex-review` (persona, magical moment, error-message Tier 1, plan-mode-aware Phase 5). +- 28 codex adversarial findings across 3 review rounds, 23 accepted. + +## [1.46.0.0] - 2026-05-26 + +## **gstack v2 foundation lands. Catalog tokens drop 56%, eval-first floor covers all 51 skills, hard token + dollar caps gate every PR.** + +The always-loaded skill catalog — what every Claude Code session pays for at startup before any real work begins — went from ~9,319 tokens to ~4,045 tokens. That's a 56.6% cut to the surface gstack has been criticized for (third-party review, May 2026: "10K+ tokens before any real code is written"). Heavyweight skills like `/ship`, `/plan-ceo-review`, `/office-hours` still ship their full content, but their frontmatter descriptions trim to one sentence each; the routing prose lives in a new "## When to invoke" body section, and a per-run `scripts/proactive-suggestions.json` registry holds the voice-trigger + proactive-suggest text so agents can pull guidance on demand instead of always-loaded. + +This is the v2 foundation release. The architectural break — `sections/*.md.tmpl` pattern, mechanical Read enforcement, eval-coverage annotations — lands in v2.0.0.0 as a coordinated launch. v1.46 absorbs every low-risk win, ships the eval-first floor every future skill must pass, and locks in the v1.44.1 reference baseline so reviewers can audit v1→v2 numbers against a real file (`test/fixtures/parity-baseline-v1.44.1.json`). + +### The numbers that matter + +Source: `bun run scripts/capture-baseline.ts --tag v1.46.0.0` vs the locked v1.44.1 baseline at `test/fixtures/parity-baseline-v1.44.1.json`. Reproduce locally with `bun test test/skill-size-budget.test.ts`. + +| Metric | v1.44.1 | v1.46.0.0 | Δ | +|---|---|---|---| +| Catalog tokens (always-loaded system prompt) | ~9,319 | ~4,045 | **−56.6%** | +| Total SKILL.md corpus | 2,847 KB | 2,813 KB | −1.2% | +| ship.md | 160 KB | 159 KB | −0.5% | +| plan-ceo-review.md | 128 KB | 127 KB | −0.7% | +| office-hours.md | 108 KB | 108 KB | −0.8% | +| Skills with gate-tier eval coverage | 32 of 51 | **51 of 51** | floor achieved | +| Cathedral parity invariants pinned | 0 | **10** | structural + content | +| Token & dollar budget regressions caught at CI | (none) | **5 new test files** | per-skill, corpus, catalog, eval-cost gate, eval-cost periodic | + +The corpus barely moved because the catalog trim MOVES routing prose from frontmatter to a body section — it doesn't delete it. The always-loaded surface drops by more than half because catalog text is what Claude Code reads on every session start; body content only loads when the skill is invoked. + +### What this means for you + +If you use any gstack skill, every session starts ~5,000 tokens lighter before you type anything. Heavyweight invocations like `/ship` cost about the same as before, but session startup feels snappier. If you've been on the fence about installing gstack because of the "fat" reputation, this is the release that addresses it directly: the always-loaded surface is now competitive with stripped-down skill packs while every skill keeps its full body content. + +If you contribute skills, the eval-first floor means a new SKILL.md without an entry in `test/skill-coverage-matrix.ts` fails CI. The minimum entry is one line referencing `test/skill-coverage-floor.test.ts` (the free structural-compliance smoke test). Behavioral E2E coverage gets layered on top per skill. + +If you run gstack in CI, the new `EVALS_BUDGET_HARD_CAP=$30` cap (per-suite: gate $25 / periodic $70) stops runaway eval costs from a model price change or infinite-retry bug. Override path exists for legit-need-more cases: `EVALS_BUDGET_OVERRIDE_REASON="why this is OK"` logs to `~/.gstack/analytics/spend-overrides.jsonl` for audit. + +### Itemized changes + +**Added** +- `scripts/capture-baseline.ts` + `test/helpers/capture-parity-baseline.ts` — captures per-skill SKILL.md sizes, token estimates, frontmatter description lengths, and eval coverage flags. Writes JSON snapshots used by the parity and size-budget gates. Locks `test/fixtures/parity-baseline-v1.44.1.json` as the v1→v2 reference. +- `test/helpers/parity-harness.ts` + `test/parity-suite.test.ts` — cathedral parity-eval suite floor. `PARITY_INVARIANTS` registry pins must-preserve phrases per skill family (cso: OWASP/STRIDE; plan-ceo: SCOPE EXPANSION / HOLD SCOPE; ship: VERSION/CHANGELOG/PR) so future compression can't silently strip load-bearing prose. +- `test/skill-coverage-matrix.ts` + `test/skill-coverage-matrix.test.ts` — single source of truth mapping each skill to gate + periodic tests; CI gate asserts every skill has at least one gate-tier entry. 51 skills, 51 entries. +- `test/skill-coverage-floor.test.ts` — per-skill structural-compliance smoke test (file-IO, free). Verifies frontmatter shape, generated header, body non-trivial, no leaked `{{TEMPLATE}}` placeholders, catalog-trim contract on description. 309 assertions across 51 skills. +- `test/skill-size-budget.test.ts` — per-skill SKILL.md byte budget (×1.05 default ratio), total corpus budget, catalog token budget (≤7000 for v1.46). Caught regressions get a per-skill breakdown + override path. +- `test/cso-preserved.test.ts` — pins cso's must-not-strip security guidance phrases (OWASP, STRIDE, daily/comprehensive mode discipline, confidence scoring, active verification). Future compression that hits cso fails CI here. +- `test/helpers/budget-override.ts` — audit-trail logger for `GSTACK_SIZE_BUDGET_OVERRIDE_REASON` and `EVALS_BUDGET_OVERRIDE_REASON`. Append-only JSONL at `~/.gstack/analytics/spend-overrides.jsonl` with timestamp + scope + reason + CI provenance. +- `scripts/proactive-suggestions.json` — per-run registry of routing prose + voice triggers extracted from skill frontmatter during catalog trim. Agents pull on demand instead of paying for it always-loaded. +- `--catalog-mode=full` build flag — restores v1.44 legacy multi-line catalog descriptions. Use when debugging routing regressions or when shipping skills to hosts that depend on the legacy fat catalog. +- `--explain-level=terse` build flag — opt-in compression of `## Writing Style` + `## Completeness Principle` + `## Confusion Protocol` + `## Context Health` preamble sections. Default build keeps the runtime-conditional behavior intact (the model still skips when `EXPLAIN_LEVEL: terse` appears in the preamble echo); terse build makes the compression structural. +- `EVALS_BUDGET_HARD_CAP` environment variable (umbrella $30 default) + per-suite `EVALS_BUDGET_HARD_CAP_GATE=$25`, `EVALS_BUDGET_HARD_CAP_PERIODIC=$70`. Build fails if a single run exceeds; `EVALS_BUDGET_OVERRIDE_REASON` env unblocks + audit-logs. + +**Changed** +- Skill frontmatter `description:` blocks across 51 skills trimmed to a single lead sentence + `(gstack)` tag. Routing prose ("Use when asked to...", "Proactively suggest...") and voice triggers moved to a `## When to invoke` body section in each SKILL.md. Always-loaded catalog cost drops ~56%. +- Jargon list (`scripts/jargon-list.json`, 80 terms) no longer inlined into every tier-2+ skill. `## Writing Style` now references the JSON path; agents Read it once per session on first jargon term encountered. Saves ~70 KB of duplicated text across the corpus. +- `ResolverEntry` union type in `scripts/resolvers/types.ts` + `unwrapResolver` helper. Resolvers can now be either bare functions (current behavior) or `{ resolve, appliesTo? }` gated entries. `scripts/gen-skill-docs.ts:444` checks the gate before invocation. Infrastructure for future per-skill resolver gating; all current resolvers stay bare functions and work unchanged. +- `TemplateContext` gains an optional `explainLevel: 'default' | 'terse'` field threaded from the `--explain-level` build flag. + +**Fixed** +- Catalog descriptions no longer collide with adjacent YAML fields (initial implementation produced `description: ... (gstack)allowed-tools:` with no newline; fixed by appending `\n` to the replacement). + +**For contributors** +- New skills require an entry in `test/skill-coverage-matrix.ts` — at minimum referencing `test/skill-coverage-floor.test.ts` in `gate[]`. The CI gate at `test/skill-coverage-matrix.test.ts` fails fast on missing entries. +- New must-preserve invariants for a skill family go in `PARITY_INVARIANTS` in `test/helpers/parity-harness.ts`. Adding invariants is additive; removing one is a deliberate scope decision. +- The `scripts/jargon-list.json` is the canonical glossary. Add terms there; gen-skill-docs picks them up automatically on next regen. +- `test/fixtures/parity-baseline-v1.44.1.json` is the locked v1→v2 reference. Do not modify; capture new snapshots at later tags via `bun run scripts/capture-baseline.ts --tag `. + ## [1.45.0.0] - 2026-05-25 ## **Design boards now live 24 hours, not 10 minutes. One daemon hosts every board, one tab survives the whole day.** diff --git a/CLAUDE.md b/CLAUDE.md index b34f038f9..a002c124b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -111,6 +111,7 @@ gstack/ ├── land-and-deploy/ # /land-and-deploy skill (merge → deploy → canary verify) ├── office-hours/ # /office-hours skill (YC Office Hours — startup diagnostic + builder brainstorm) ├── investigate/ # /investigate skill (systematic root-cause debugging) +├── spec/ # /spec skill (five-phase spec → GitHub issue, optional agent spawn, /ship auto-closes) ├── retro/ # Retrospective skill (includes /retro global cross-project mode) ├── bin/ # CLI utilities (gstack-repo-mode, gstack-slug, gstack-config, etc.) ├── document-release/ # /document-release skill (post-ship doc updates + Diataxis coverage map) diff --git a/README.md b/README.md index 0551a9d37..a0d9c40e3 100644 --- a/README.md +++ b/README.md @@ -204,6 +204,7 @@ Each skill feeds into the next. `/office-hours` writes a design doc that `/plan- | `/browse` | **QA Engineer** | Give the agent eyes. Real Chromium browser, real clicks, real screenshots. ~100ms per command. `/open-gstack-browser` launches GStack Browser with sidebar, anti-bot stealth, and auto model routing. | | `/setup-browser-cookies` | **Session Manager** | Import cookies from your real browser (Chrome, Arc, Brave, Edge) into the headless session. Test authenticated pages. | | `/autoplan` | **Review Pipeline** | One command, fully reviewed plan. Runs CEO → design → eng review automatically with encoded decision principles. Surfaces only taste decisions for your approval. | +| `/spec` | **Spec Author** | Turn vague intent into a precise, executable spec in five phases (why, scope, technical with mandatory code-reading, draft, file). Codex quality gate before file (blocks below 7/10), fail-closed secret redaction, dedupe against existing issues, archive to `$GSTACK_STATE_ROOT/projects/$SLUG/specs/` for team-corpus recall. `--execute` spawns `claude -p` in a fresh worktree; `/ship` auto-closes the source issue on merge. Plan-mode aware. | | `/learn` | **Memory** | Manage what gstack learned across sessions. Review, search, prune, and export project-specific patterns, pitfalls, and preferences. Learnings compound across sessions so gstack gets smarter on your codebase over time. | ### Which review should I use? diff --git a/SKILL.md b/SKILL.md index c6441014c..569350e37 100644 --- a/SKILL.md +++ b/SKILL.md @@ -2,11 +2,7 @@ name: gstack preamble-tier: 1 version: 1.1.0 -description: | - Fast headless browser for QA testing and site dogfooding. Navigate pages, interact with - elements, verify state, diff before/after, take annotated screenshots, test responsive - layouts, forms, uploads, dialogs, and capture bug evidence. Use when asked to open or - test a site, verify a deployment, dogfood a user flow, or file a bug with screenshots. (gstack) +description: Fast headless browser for QA testing and site dogfooding. (gstack) allowed-tools: - Bash - Read @@ -21,6 +17,14 @@ triggers: + +## When to invoke this skill + +Navigate pages, interact with +elements, verify state, diff before/after, take annotated screenshots, test responsive +layouts, forms, uploads, dialogs, and capture bug evidence. Use when asked to open or +test a site, verify a deployment, dogfood a user flow, or file a bug with screenshots. + ## Preamble (run first) ```bash @@ -98,6 +102,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -229,6 +246,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` @@ -486,6 +504,7 @@ quality gates that produce better results than answering inline. **Routing rules — when you see these patterns, INVOKE the skill via the Skill tool:** - User describes a new idea, asks "is this worth building", brainstorms, pitches a concept → invoke `/office-hours` +- User asks to spec something out, file an issue, write up a ticket, "turn this into a GitHub issue", "backlog item" → invoke `/spec` - User asks about strategy, scope, ambition, "think bigger", "what should we build" → invoke `/plan-ceo-review` - User asks to review architecture, lock in the plan, "does this design make sense" → invoke `/plan-eng-review` - User asks about design system, brand, visual identity, "how should this look" → invoke `/design-consultation` diff --git a/SKILL.md.tmpl b/SKILL.md.tmpl index d382863a4..2b19817e9 100644 --- a/SKILL.md.tmpl +++ b/SKILL.md.tmpl @@ -32,6 +32,7 @@ quality gates that produce better results than answering inline. **Routing rules — when you see these patterns, INVOKE the skill via the Skill tool:** - User describes a new idea, asks "is this worth building", brainstorms, pitches a concept → invoke `/office-hours` +- User asks to spec something out, file an issue, write up a ticket, "turn this into a GitHub issue", "backlog item" → invoke `/spec` - User asks about strategy, scope, ambition, "think bigger", "what should we build" → invoke `/plan-ceo-review` - User asks to review architecture, lock in the plan, "does this design make sense" → invoke `/plan-eng-review` - User asks about design system, brand, visual identity, "how should this look" → invoke `/design-consultation` diff --git a/TODOS.md b/TODOS.md index 72e3d023e..2833f1262 100644 --- a/TODOS.md +++ b/TODOS.md @@ -1768,6 +1768,49 @@ Shipped in v0.6.5. TemplateContext in gen-skill-docs.ts bakes skill name into pr **Priority:** P2 **Depends on:** CDP patches proving the value of anti-bot stealth first +## /spec follow-ups (deferred from v1.47.0.0 via /plan-ceo-review SCOPE EXPANSION) + +### P2: `/spec --epic` mode (parent issue + child issues + dependency graph) + +**Priority:** P2 + +**What:** Add `--epic` flag that produces an Epic issue (parent) plus N child issues with explicit dependency graph and topological order. Emits multiple `gh issue create` calls with parent linkage in child bodies. + +**Why:** Multi-week initiatives often span 3-5 specs that share context but ship sequentially. Today `/spec --epic` would let users author the full initiative in one session and file all linked issues atomically. The Epic template already exists in `spec/SKILL.md.tmpl` (carried over from PR #1698); only the flag routing + multi-issue `gh` orchestration is missing. + +**Pros:** +- Closes the multi-issue workflow gap that `/spec` v1 doesn't cover. +- Parent + child linkage means project boards show the full initiative at-a-glance. +- Composes cleanly with existing `--execute` (spawn an agent on the parent epic; agent files children as it works). + +**Cons:** +- More gh API surface (one create per child, parent-link edit pass). +- Dependency-graph rendering in markdown is fiddly across GitHub vs GitLab renderers. + +**Context:** Considered in `/plan-ceo-review` SCOPE EXPANSION (D5), deferred 2026-05-25 in favor of shipping the 5 critical-path expansions (--execute, --dedupe, archive, quality gate, --audit). Re-evaluate once v1.47 ships and we see how often users hit "this should be 3 issues" in real /spec sessions. + +**Depends on:** v1.47.0.0 `/spec` lands first; need real usage data to calibrate the multi-issue surface. + +### P3: `/spec --dedupe` semantic matching (LLM-based) for v1.1 + +**Priority:** P3 + +**What:** Upgrade `--dedupe`'s string match against `gh issue list --search` to LLM-based semantic similarity. Today's v1 picks string overlap on title keywords; semantic match would catch "the sidebar terminal flakes on reload" matching an existing issue titled "PTY reconnect fails after extension restart" where keyword overlap is zero. + +**Why:** String match has high precision but low recall — it misses near-duplicates with different vocabulary. LLM semantic match catches more dupes but costs ~$0.01-0.05 per spec dispatch and adds 5-10s latency. + +**Pros:** +- Catches dupes string match misses. +- One more reason `/spec` is more useful than freehand authoring. + +**Cons:** +- Paid + slower. Most v1 users probably don't hit enough false-negatives to justify the cost. +- Adds another LLM-judged decision to a skill that already has the quality gate. + +**Context:** Considered in `/plan-ceo-review` build-time decisions; chose string match for v1 to keep the dedupe path free + fast. Revisit if v1 produces a meaningful false-negative rate in real use. + +**Depends on:** v1.47.0.0 ships; gather real false-negative data from the v1 string matcher. + ## Completed ### Slim preamble + real-PTY plan-mode E2E harness (v1.13.1.0) diff --git a/VERSION b/VERSION index 94cf8fed1..d074bee30 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -1.45.0.0 +1.47.0.0 diff --git a/autoplan/SKILL.md b/autoplan/SKILL.md index ddf458fbb..0e77d8196 100644 --- a/autoplan/SKILL.md +++ b/autoplan/SKILL.md @@ -2,16 +2,7 @@ name: autoplan preamble-tier: 3 version: 1.0.0 -description: | - Auto-review pipeline — reads the full CEO, design, eng, and DX review skills from disk - and runs them sequentially with auto-decisions using 6 decision principles. Surfaces - taste decisions (close approaches, borderline scope, codex disagreements) at a final - approval gate. One command, fully reviewed plan out. - Use when asked to "auto review", "autoplan", "run all reviews", "review this plan - automatically", or "make the decisions for me". - Proactively suggest when the user has a plan file and wants to run the full review - gauntlet without answering 15-30 intermediate questions. (gstack) - Voice triggers (speech-to-text aliases): "auto plan", "automatic review". +description: Auto-review pipeline — reads the full CEO, design, eng, and DX review skills from disk and runs them sequentially with auto-decisions using 6 decision principles. (gstack) benefits-from: [office-hours] triggers: - run all reviews @@ -30,6 +21,19 @@ allowed-tools: + +## When to invoke this skill + +Surfaces +taste decisions (close approaches, borderline scope, codex disagreements) at a final +approval gate. One command, fully reviewed plan out. +Use when asked to "auto review", "autoplan", "run all reviews", "review this plan +automatically", or "make the decisions for me". +Proactively suggest when the user has a plan file and wants to run the full review +gauntlet without answering 15-30 intermediate questions. + +Voice triggers (speech-to-text aliases): "auto plan", "automatic review". + ## Preamble (run first) ```bash @@ -107,6 +111,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -238,6 +255,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` @@ -588,84 +606,7 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i - User-turn override wins: if the current message asks for terse / no explanations / just the answer, skip this section. - Terse mode (EXPLAIN_LEVEL: terse): no glosses, no outcome-framing layer, shorter responses. -Jargon list, gloss on first use if the term appears: -- idempotent -- idempotency -- race condition -- deadlock -- cyclomatic complexity -- N+1 -- N+1 query -- backpressure -- memoization -- eventual consistency -- CAP theorem -- CORS -- CSRF -- XSS -- SQL injection -- prompt injection -- DDoS -- rate limit -- throttle -- circuit breaker -- load balancer -- reverse proxy -- SSR -- CSR -- hydration -- tree-shaking -- bundle splitting -- code splitting -- hot reload -- tombstone -- soft delete -- cascade delete -- foreign key -- composite index -- covering index -- OLTP -- OLAP -- sharding -- replication lag -- quorum -- two-phase commit -- saga -- outbox pattern -- inbox pattern -- optimistic locking -- pessimistic locking -- thundering herd -- cache stampede -- bloom filter -- consistent hashing -- virtual DOM -- reconciliation -- closure -- hoisting -- tail call -- GIL -- zero-copy -- mmap -- cold start -- warm start -- green-blue deploy -- canary deploy -- feature flag -- kill switch -- dead letter queue -- fan-out -- fan-in -- debounce -- throttle (UI) -- hydration mismatch -- memory leak -- GC pause -- heap fragmentation -- stack overflow -- null pointer -- dangling pointer -- buffer overflow +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 Lake diff --git a/benchmark-models/SKILL.md b/benchmark-models/SKILL.md index 47050855b..38baa8851 100644 --- a/benchmark-models/SKILL.md +++ b/benchmark-models/SKILL.md @@ -2,14 +2,7 @@ name: benchmark-models preamble-tier: 1 version: 1.0.0 -description: | - Cross-model benchmark for gstack skills. Runs the same prompt through Claude, - GPT (via Codex CLI), and Gemini side-by-side — compares latency, tokens, cost, - and optionally quality via LLM judge. Answers "which model is actually best - for this skill?" with data instead of vibes. Separate from /benchmark, which - measures web page performance. Use when: "benchmark models", "compare models", - "which model is best for X", "cross-model comparison", "model shootout". (gstack) - Voice triggers (speech-to-text aliases): "compare models", "model shootout", "which model is best". +description: Cross-model benchmark for gstack skills. (gstack) triggers: - cross model benchmark - compare claude gpt gemini @@ -23,6 +16,18 @@ allowed-tools: + +## When to invoke this skill + +Runs the same prompt through Claude, +GPT (via Codex CLI), and Gemini side-by-side — compares latency, tokens, cost, +and optionally quality via LLM judge. Answers "which model is actually best +for this skill?" with data instead of vibes. Separate from /benchmark, which +measures web page performance. Use when: "benchmark models", "compare models", +"which model is best for X", "cross-model comparison", "model shootout". + +Voice triggers (speech-to-text aliases): "compare models", "model shootout", "which model is best". + ## Preamble (run first) ```bash @@ -100,6 +105,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -231,6 +249,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` diff --git a/benchmark/SKILL.md b/benchmark/SKILL.md index b6dc81373..d2b54a2c4 100644 --- a/benchmark/SKILL.md +++ b/benchmark/SKILL.md @@ -2,13 +2,7 @@ name: benchmark preamble-tier: 1 version: 1.0.0 -description: | - Performance regression detection using the browse daemon. Establishes - baselines for page load times, Core Web Vitals, and resource sizes. - Compares before/after on every PR. Tracks performance trends over time. - Use when: "performance", "benchmark", "page speed", "lighthouse", "web vitals", - "bundle size", "load time". (gstack) - Voice triggers (speech-to-text aliases): "speed test", "check performance". +description: Performance regression detection using the browse daemon. (gstack) triggers: - performance benchmark - check page speed @@ -23,6 +17,17 @@ allowed-tools: + +## When to invoke this skill + +Establishes +baselines for page load times, Core Web Vitals, and resource sizes. +Compares before/after on every PR. Tracks performance trends over time. +Use when: "performance", "benchmark", "page speed", "lighthouse", "web vitals", +"bundle size", "load time". + +Voice triggers (speech-to-text aliases): "speed test", "check performance". + ## Preamble (run first) ```bash @@ -100,6 +105,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -231,6 +249,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` diff --git a/browse/SKILL.md b/browse/SKILL.md index 6a4f5c269..99e5add79 100644 --- a/browse/SKILL.md +++ b/browse/SKILL.md @@ -2,13 +2,7 @@ name: browse preamble-tier: 1 version: 1.1.0 -description: | - Fast headless browser for QA testing and site dogfooding. Navigate any URL, interact with - elements, verify page state, diff before/after actions, take annotated screenshots, check - responsive layouts, test forms and uploads, handle dialogs, and assert element states. - ~100ms per command. Use when you need to test a feature, verify a deployment, dogfood a - user flow, or file a bug with evidence. Use when asked to "open in browser", "test the - site", "take a screenshot", or "dogfood this". (gstack) +description: Fast headless browser for QA testing and site dogfooding. (gstack) triggers: - browse a page - headless browser @@ -22,6 +16,16 @@ allowed-tools: + +## When to invoke this skill + +Navigate any URL, interact with +elements, verify page state, diff before/after actions, take annotated screenshots, check +responsive layouts, test forms and uploads, handle dialogs, and assert element states. +~100ms per command. Use when you need to test a feature, verify a deployment, dogfood a +user flow, or file a bug with evidence. Use when asked to "open in browser", "test the +site", "take a screenshot", or "dogfood this". + ## Preamble (run first) ```bash @@ -99,6 +103,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -230,6 +247,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` diff --git a/canary/SKILL.md b/canary/SKILL.md index b3149ad7e..2693319be 100644 --- a/canary/SKILL.md +++ b/canary/SKILL.md @@ -2,12 +2,7 @@ name: canary preamble-tier: 2 version: 1.0.0 -description: | - Post-deploy canary monitoring. Watches the live app for console errors, - performance regressions, and page failures using the browse daemon. Takes - periodic screenshots, compares against pre-deploy baselines, and alerts - on anomalies. Use when: "monitor deploy", "canary", "post-deploy check", - "watch production", "verify deploy". (gstack) +description: Post-deploy canary monitoring. (gstack) allowed-tools: - Bash - Read @@ -22,6 +17,15 @@ triggers: + +## When to invoke this skill + +Watches the live app for console errors, +performance regressions, and page failures using the browse daemon. Takes +periodic screenshots, compares against pre-deploy baselines, and alerts +on anomalies. Use when: "monitor deploy", "canary", "post-deploy check", +"watch production", "verify deploy". + ## Preamble (run first) ```bash @@ -99,6 +103,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -230,6 +247,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` @@ -580,84 +598,7 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i - User-turn override wins: if the current message asks for terse / no explanations / just the answer, skip this section. - Terse mode (EXPLAIN_LEVEL: terse): no glosses, no outcome-framing layer, shorter responses. -Jargon list, gloss on first use if the term appears: -- idempotent -- idempotency -- race condition -- deadlock -- cyclomatic complexity -- N+1 -- N+1 query -- backpressure -- memoization -- eventual consistency -- CAP theorem -- CORS -- CSRF -- XSS -- SQL injection -- prompt injection -- DDoS -- rate limit -- throttle -- circuit breaker -- load balancer -- reverse proxy -- SSR -- CSR -- hydration -- tree-shaking -- bundle splitting -- code splitting -- hot reload -- tombstone -- soft delete -- cascade delete -- foreign key -- composite index -- covering index -- OLTP -- OLAP -- sharding -- replication lag -- quorum -- two-phase commit -- saga -- outbox pattern -- inbox pattern -- optimistic locking -- pessimistic locking -- thundering herd -- cache stampede -- bloom filter -- consistent hashing -- virtual DOM -- reconciliation -- closure -- hoisting -- tail call -- GIL -- zero-copy -- mmap -- cold start -- warm start -- green-blue deploy -- canary deploy -- feature flag -- kill switch -- dead letter queue -- fan-out -- fan-in -- debounce -- throttle (UI) -- hydration mismatch -- memory leak -- GC pause -- heap fragmentation -- stack overflow -- null pointer -- dangling pointer -- buffer overflow +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 Lake diff --git a/careful/SKILL.md b/careful/SKILL.md index 91a5776e3..678d66c16 100644 --- a/careful/SKILL.md +++ b/careful/SKILL.md @@ -1,12 +1,7 @@ --- name: careful version: 0.1.0 -description: | - Safety guardrails for destructive commands. Warns before rm -rf, DROP TABLE, - force-push, git reset --hard, kubectl delete, and similar destructive operations. - User can override each warning. Use when touching prod, debugging live systems, - or working in a shared environment. Use when asked to "be careful", "safety mode", - "prod mode", or "careful mode". (gstack) +description: Safety guardrails for destructive commands. (gstack) triggers: - be careful - warn before destructive @@ -25,6 +20,15 @@ hooks: + +## When to invoke this skill + +Warns before rm -rf, DROP TABLE, +force-push, git reset --hard, kubectl delete, and similar destructive operations. +User can override each warning. Use when touching prod, debugging live systems, +or working in a shared environment. Use when asked to "be careful", "safety mode", +"prod mode", or "careful mode". + # /careful — Destructive Command Guardrails Safety mode is now **active**. Every bash command will be checked for destructive diff --git a/codex/SKILL.md b/codex/SKILL.md index 5215dc6a9..24331dde3 100644 --- a/codex/SKILL.md +++ b/codex/SKILL.md @@ -2,13 +2,7 @@ name: codex preamble-tier: 3 version: 1.0.0 -description: | - OpenAI Codex CLI wrapper — three modes. Code review: independent diff review via - codex review with pass/fail gate. Challenge: adversarial mode that tries to break - your code. Consult: ask codex anything with session continuity for follow-ups. - The "200 IQ autistic developer" second opinion. Use when asked to "codex review", - "codex challenge", "ask codex", "second opinion", or "consult codex". (gstack) - Voice triggers (speech-to-text aliases): "code x", "code ex", "get another opinion". +description: OpenAI Codex CLI wrapper — three modes. (gstack) triggers: - codex review - second opinion @@ -24,6 +18,17 @@ allowed-tools: + +## When to invoke this skill + +Code review: independent diff review via +codex review with pass/fail gate. Challenge: adversarial mode that tries to break +your code. Consult: ask codex anything with session continuity for follow-ups. +The "200 IQ autistic developer" second opinion. Use when asked to "codex review", +"codex challenge", "ask codex", "second opinion", or "consult codex". + +Voice triggers (speech-to-text aliases): "code x", "code ex", "get another opinion". + ## Preamble (run first) ```bash @@ -101,6 +106,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -232,6 +250,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` @@ -582,84 +601,7 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i - User-turn override wins: if the current message asks for terse / no explanations / just the answer, skip this section. - Terse mode (EXPLAIN_LEVEL: terse): no glosses, no outcome-framing layer, shorter responses. -Jargon list, gloss on first use if the term appears: -- idempotent -- idempotency -- race condition -- deadlock -- cyclomatic complexity -- N+1 -- N+1 query -- backpressure -- memoization -- eventual consistency -- CAP theorem -- CORS -- CSRF -- XSS -- SQL injection -- prompt injection -- DDoS -- rate limit -- throttle -- circuit breaker -- load balancer -- reverse proxy -- SSR -- CSR -- hydration -- tree-shaking -- bundle splitting -- code splitting -- hot reload -- tombstone -- soft delete -- cascade delete -- foreign key -- composite index -- covering index -- OLTP -- OLAP -- sharding -- replication lag -- quorum -- two-phase commit -- saga -- outbox pattern -- inbox pattern -- optimistic locking -- pessimistic locking -- thundering herd -- cache stampede -- bloom filter -- consistent hashing -- virtual DOM -- reconciliation -- closure -- hoisting -- tail call -- GIL -- zero-copy -- mmap -- cold start -- warm start -- green-blue deploy -- canary deploy -- feature flag -- kill switch -- dead letter queue -- fan-out -- fan-in -- debounce -- throttle (UI) -- hydration mismatch -- memory leak -- GC pause -- heap fragmentation -- stack overflow -- null pointer -- dangling pointer -- buffer overflow +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 Lake diff --git a/context-restore/SKILL.md b/context-restore/SKILL.md index 5b1588af1..22e499dd2 100644 --- a/context-restore/SKILL.md +++ b/context-restore/SKILL.md @@ -2,14 +2,7 @@ name: context-restore preamble-tier: 2 version: 1.0.0 -description: | - Restore working context saved earlier by /context-save. Loads the most recent - saved state (across all branches by default) so you can pick up where you - left off — even across Conductor workspace handoffs. - Use when asked to "resume", "restore context", "where was I", or - "pick up where I left off". Pair with /context-save. - Formerly /checkpoint resume — renamed because Claude Code treats /checkpoint - as a native rewind alias in current environments. (gstack) +description: Restore working context saved earlier by /context-save. (gstack) allowed-tools: - Bash - Read @@ -26,6 +19,17 @@ triggers: + +## When to invoke this skill + +Loads the most recent +saved state (across all branches by default) so you can pick up where you +left off — even across Conductor workspace handoffs. +Use when asked to "resume", "restore context", "where was I", or +"pick up where I left off". Pair with /context-save. +Formerly /checkpoint resume — renamed because Claude Code treats /checkpoint +as a native rewind alias in current environments. + ## Preamble (run first) ```bash @@ -103,6 +107,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -234,6 +251,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` @@ -584,84 +602,7 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i - User-turn override wins: if the current message asks for terse / no explanations / just the answer, skip this section. - Terse mode (EXPLAIN_LEVEL: terse): no glosses, no outcome-framing layer, shorter responses. -Jargon list, gloss on first use if the term appears: -- idempotent -- idempotency -- race condition -- deadlock -- cyclomatic complexity -- N+1 -- N+1 query -- backpressure -- memoization -- eventual consistency -- CAP theorem -- CORS -- CSRF -- XSS -- SQL injection -- prompt injection -- DDoS -- rate limit -- throttle -- circuit breaker -- load balancer -- reverse proxy -- SSR -- CSR -- hydration -- tree-shaking -- bundle splitting -- code splitting -- hot reload -- tombstone -- soft delete -- cascade delete -- foreign key -- composite index -- covering index -- OLTP -- OLAP -- sharding -- replication lag -- quorum -- two-phase commit -- saga -- outbox pattern -- inbox pattern -- optimistic locking -- pessimistic locking -- thundering herd -- cache stampede -- bloom filter -- consistent hashing -- virtual DOM -- reconciliation -- closure -- hoisting -- tail call -- GIL -- zero-copy -- mmap -- cold start -- warm start -- green-blue deploy -- canary deploy -- feature flag -- kill switch -- dead letter queue -- fan-out -- fan-in -- debounce -- throttle (UI) -- hydration mismatch -- memory leak -- GC pause -- heap fragmentation -- stack overflow -- null pointer -- dangling pointer -- buffer overflow +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 Lake diff --git a/context-save/SKILL.md b/context-save/SKILL.md index 6a6c05732..f41551d78 100644 --- a/context-save/SKILL.md +++ b/context-save/SKILL.md @@ -2,14 +2,7 @@ name: context-save preamble-tier: 2 version: 1.0.0 -description: | - Save working context. Captures git state, decisions made, and remaining work - so any future session can pick up without losing a beat. - Use when asked to "save progress", "save state", "context save", or - "save my work". Pair with /context-restore to resume later. - Formerly /checkpoint — renamed because Claude Code treats /checkpoint as a - native rewind alias in current environments, which was shadowing this skill. - (gstack) +description: Save working context. (gstack) allowed-tools: - Bash - Read @@ -26,6 +19,16 @@ triggers: + +## When to invoke this skill + +Captures git state, decisions made, and remaining work +so any future session can pick up without losing a beat. +Use when asked to "save progress", "save state", "context save", or +"save my work". Pair with /context-restore to resume later. +Formerly /checkpoint — renamed because Claude Code treats /checkpoint as a +native rewind alias in current environments, which was shadowing this skill. + ## Preamble (run first) ```bash @@ -103,6 +106,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -234,6 +250,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` @@ -584,84 +601,7 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i - User-turn override wins: if the current message asks for terse / no explanations / just the answer, skip this section. - Terse mode (EXPLAIN_LEVEL: terse): no glosses, no outcome-framing layer, shorter responses. -Jargon list, gloss on first use if the term appears: -- idempotent -- idempotency -- race condition -- deadlock -- cyclomatic complexity -- N+1 -- N+1 query -- backpressure -- memoization -- eventual consistency -- CAP theorem -- CORS -- CSRF -- XSS -- SQL injection -- prompt injection -- DDoS -- rate limit -- throttle -- circuit breaker -- load balancer -- reverse proxy -- SSR -- CSR -- hydration -- tree-shaking -- bundle splitting -- code splitting -- hot reload -- tombstone -- soft delete -- cascade delete -- foreign key -- composite index -- covering index -- OLTP -- OLAP -- sharding -- replication lag -- quorum -- two-phase commit -- saga -- outbox pattern -- inbox pattern -- optimistic locking -- pessimistic locking -- thundering herd -- cache stampede -- bloom filter -- consistent hashing -- virtual DOM -- reconciliation -- closure -- hoisting -- tail call -- GIL -- zero-copy -- mmap -- cold start -- warm start -- green-blue deploy -- canary deploy -- feature flag -- kill switch -- dead letter queue -- fan-out -- fan-in -- debounce -- throttle (UI) -- hydration mismatch -- memory leak -- GC pause -- heap fragmentation -- stack overflow -- null pointer -- dangling pointer -- buffer overflow +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 Lake diff --git a/cso/SKILL.md b/cso/SKILL.md index 0ffec24af..3e39ce4c5 100644 --- a/cso/SKILL.md +++ b/cso/SKILL.md @@ -2,14 +2,7 @@ name: cso preamble-tier: 2 version: 2.0.0 -description: | - Chief Security Officer mode. Infrastructure-first security audit: secrets archaeology, - dependency supply chain, CI/CD pipeline security, LLM/AI security, skill supply chain - scanning, plus OWASP Top 10, STRIDE threat modeling, and active verification. - Two modes: daily (zero-noise, 8/10 confidence gate) and comprehensive (monthly deep - scan, 2/10 bar). Trend tracking across audit runs. - Use when: "security audit", "threat model", "pentest review", "OWASP", "CSO review". (gstack) - Voice triggers (speech-to-text aliases): "see-so", "see so", "security review", "security check", "vulnerability scan", "run security". +description: Chief Security Officer mode. (gstack) allowed-tools: - Bash - Read @@ -27,6 +20,18 @@ triggers: + +## When to invoke this skill + +Infrastructure-first security audit: secrets archaeology, +dependency supply chain, CI/CD pipeline security, LLM/AI security, skill supply chain +scanning, plus OWASP Top 10, STRIDE threat modeling, and active verification. +Two modes: daily (zero-noise, 8/10 confidence gate) and comprehensive (monthly deep +scan, 2/10 bar). Trend tracking across audit runs. +Use when: "security audit", "threat model", "pentest review", "OWASP", "CSO review". + +Voice triggers (speech-to-text aliases): "see-so", "see so", "security review", "security check", "vulnerability scan", "run security". + ## Preamble (run first) ```bash @@ -104,6 +109,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -235,6 +253,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` @@ -585,84 +604,7 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i - User-turn override wins: if the current message asks for terse / no explanations / just the answer, skip this section. - Terse mode (EXPLAIN_LEVEL: terse): no glosses, no outcome-framing layer, shorter responses. -Jargon list, gloss on first use if the term appears: -- idempotent -- idempotency -- race condition -- deadlock -- cyclomatic complexity -- N+1 -- N+1 query -- backpressure -- memoization -- eventual consistency -- CAP theorem -- CORS -- CSRF -- XSS -- SQL injection -- prompt injection -- DDoS -- rate limit -- throttle -- circuit breaker -- load balancer -- reverse proxy -- SSR -- CSR -- hydration -- tree-shaking -- bundle splitting -- code splitting -- hot reload -- tombstone -- soft delete -- cascade delete -- foreign key -- composite index -- covering index -- OLTP -- OLAP -- sharding -- replication lag -- quorum -- two-phase commit -- saga -- outbox pattern -- inbox pattern -- optimistic locking -- pessimistic locking -- thundering herd -- cache stampede -- bloom filter -- consistent hashing -- virtual DOM -- reconciliation -- closure -- hoisting -- tail call -- GIL -- zero-copy -- mmap -- cold start -- warm start -- green-blue deploy -- canary deploy -- feature flag -- kill switch -- dead letter queue -- fan-out -- fan-in -- debounce -- throttle (UI) -- hydration mismatch -- memory leak -- GC pause -- heap fragmentation -- stack overflow -- null pointer -- dangling pointer -- buffer overflow +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 Lake diff --git a/design-consultation/SKILL.md b/design-consultation/SKILL.md index 5edb13eec..235026d2f 100644 --- a/design-consultation/SKILL.md +++ b/design-consultation/SKILL.md @@ -2,14 +2,7 @@ name: design-consultation preamble-tier: 3 version: 1.0.0 -description: | - Design consultation: understands your product, researches the landscape, proposes a - complete design system (aesthetic, typography, color, layout, spacing, motion), and - generates font+color preview pages. Creates DESIGN.md as your project's design source - of truth. For existing sites, use /plan-design-review to infer the system instead. - Use when asked to "design system", "brand guidelines", or "create DESIGN.md". - Proactively suggest when starting a new project's UI with no existing - design system or DESIGN.md. (gstack) +description: Design consultation: understands your product, researches the landscape, proposes a complete design system (aesthetic, typography, color, layout, spacing, motion), and generates font+color preview... (gstack) allowed-tools: - Bash - Read @@ -50,6 +43,15 @@ gbrain: + +## When to invoke this skill + +Creates DESIGN.md as your project's design source +of truth. For existing sites, use /plan-design-review to infer the system instead. +Use when asked to "design system", "brand guidelines", or "create DESIGN.md". +Proactively suggest when starting a new project's UI with no existing +design system or DESIGN.md. + ## Preamble (run first) ```bash @@ -127,6 +129,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -258,6 +273,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` @@ -608,84 +624,7 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i - User-turn override wins: if the current message asks for terse / no explanations / just the answer, skip this section. - Terse mode (EXPLAIN_LEVEL: terse): no glosses, no outcome-framing layer, shorter responses. -Jargon list, gloss on first use if the term appears: -- idempotent -- idempotency -- race condition -- deadlock -- cyclomatic complexity -- N+1 -- N+1 query -- backpressure -- memoization -- eventual consistency -- CAP theorem -- CORS -- CSRF -- XSS -- SQL injection -- prompt injection -- DDoS -- rate limit -- throttle -- circuit breaker -- load balancer -- reverse proxy -- SSR -- CSR -- hydration -- tree-shaking -- bundle splitting -- code splitting -- hot reload -- tombstone -- soft delete -- cascade delete -- foreign key -- composite index -- covering index -- OLTP -- OLAP -- sharding -- replication lag -- quorum -- two-phase commit -- saga -- outbox pattern -- inbox pattern -- optimistic locking -- pessimistic locking -- thundering herd -- cache stampede -- bloom filter -- consistent hashing -- virtual DOM -- reconciliation -- closure -- hoisting -- tail call -- GIL -- zero-copy -- mmap -- cold start -- warm start -- green-blue deploy -- canary deploy -- feature flag -- kill switch -- dead letter queue -- fan-out -- fan-in -- debounce -- throttle (UI) -- hydration mismatch -- memory leak -- GC pause -- heap fragmentation -- stack overflow -- null pointer -- dangling pointer -- buffer overflow +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 Lake diff --git a/design-html/SKILL.md b/design-html/SKILL.md index 48f1c8873..70b87ff7e 100644 --- a/design-html/SKILL.md +++ b/design-html/SKILL.md @@ -2,16 +2,7 @@ name: design-html preamble-tier: 2 version: 1.0.0 -description: | - Design finalization: generates production-quality Pretext-native HTML/CSS. - Works with approved mockups from /design-shotgun, CEO plans from /plan-ceo-review, - design review context from /plan-design-review, or from scratch with a user - description. Text actually reflows, heights are computed, layouts are dynamic. - 30KB overhead, zero deps. Smart API routing: picks the right Pretext patterns - for each design type. Use when: "finalize this design", "turn this into HTML", - "build me a page", "implement this design", or after any planning skill. - Proactively suggest when user has approved a design or has a plan ready. (gstack) - Voice triggers (speech-to-text aliases): "build the design", "code the mockup", "make it real". +description: Design finalization: generates production-quality Pretext-native HTML/CSS. (gstack) triggers: - build the design - code the mockup @@ -29,6 +20,19 @@ allowed-tools: + +## When to invoke this skill + +Works with approved mockups from /design-shotgun, CEO plans from /plan-ceo-review, +design review context from /plan-design-review, or from scratch with a user +description. Text actually reflows, heights are computed, layouts are dynamic. +30KB overhead, zero deps. Smart API routing: picks the right Pretext patterns +for each design type. Use when: "finalize this design", "turn this into HTML", +"build me a page", "implement this design", or after any planning skill. +Proactively suggest when user has approved a design or has a plan ready. + +Voice triggers (speech-to-text aliases): "build the design", "code the mockup", "make it real". + ## Preamble (run first) ```bash @@ -106,6 +110,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -237,6 +254,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` @@ -587,84 +605,7 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i - User-turn override wins: if the current message asks for terse / no explanations / just the answer, skip this section. - Terse mode (EXPLAIN_LEVEL: terse): no glosses, no outcome-framing layer, shorter responses. -Jargon list, gloss on first use if the term appears: -- idempotent -- idempotency -- race condition -- deadlock -- cyclomatic complexity -- N+1 -- N+1 query -- backpressure -- memoization -- eventual consistency -- CAP theorem -- CORS -- CSRF -- XSS -- SQL injection -- prompt injection -- DDoS -- rate limit -- throttle -- circuit breaker -- load balancer -- reverse proxy -- SSR -- CSR -- hydration -- tree-shaking -- bundle splitting -- code splitting -- hot reload -- tombstone -- soft delete -- cascade delete -- foreign key -- composite index -- covering index -- OLTP -- OLAP -- sharding -- replication lag -- quorum -- two-phase commit -- saga -- outbox pattern -- inbox pattern -- optimistic locking -- pessimistic locking -- thundering herd -- cache stampede -- bloom filter -- consistent hashing -- virtual DOM -- reconciliation -- closure -- hoisting -- tail call -- GIL -- zero-copy -- mmap -- cold start -- warm start -- green-blue deploy -- canary deploy -- feature flag -- kill switch -- dead letter queue -- fan-out -- fan-in -- debounce -- throttle (UI) -- hydration mismatch -- memory leak -- GC pause -- heap fragmentation -- stack overflow -- null pointer -- dangling pointer -- buffer overflow +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 Lake diff --git a/design-review/SKILL.md b/design-review/SKILL.md index ca5f0f148..33c43ceb5 100644 --- a/design-review/SKILL.md +++ b/design-review/SKILL.md @@ -2,14 +2,7 @@ name: design-review preamble-tier: 4 version: 2.0.0 -description: | - Designer's eye QA: finds visual inconsistency, spacing issues, hierarchy problems, - AI slop patterns, and slow interactions — then fixes them. Iteratively fixes issues - in source code, committing each fix atomically and re-verifying with before/after - screenshots. For plan-mode design review (before implementation), use /plan-design-review. - Use when asked to "audit the design", "visual QA", "check if it looks good", or "design polish". - Proactively suggest when the user mentions visual inconsistencies or - wants to polish the look of a live site. (gstack) +description: Designer's eye QA: finds visual inconsistency, spacing issues, hierarchy problems, AI slop patterns, and slow interactions — then fixes them. (gstack) allowed-tools: - Bash - Read @@ -27,6 +20,16 @@ triggers: + +## When to invoke this skill + +Iteratively fixes issues +in source code, committing each fix atomically and re-verifying with before/after +screenshots. For plan-mode design review (before implementation), use /plan-design-review. +Use when asked to "audit the design", "visual QA", "check if it looks good", or "design polish". +Proactively suggest when the user mentions visual inconsistencies or +wants to polish the look of a live site. + ## Preamble (run first) ```bash @@ -104,6 +107,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -235,6 +251,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` @@ -585,84 +602,7 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i - User-turn override wins: if the current message asks for terse / no explanations / just the answer, skip this section. - Terse mode (EXPLAIN_LEVEL: terse): no glosses, no outcome-framing layer, shorter responses. -Jargon list, gloss on first use if the term appears: -- idempotent -- idempotency -- race condition -- deadlock -- cyclomatic complexity -- N+1 -- N+1 query -- backpressure -- memoization -- eventual consistency -- CAP theorem -- CORS -- CSRF -- XSS -- SQL injection -- prompt injection -- DDoS -- rate limit -- throttle -- circuit breaker -- load balancer -- reverse proxy -- SSR -- CSR -- hydration -- tree-shaking -- bundle splitting -- code splitting -- hot reload -- tombstone -- soft delete -- cascade delete -- foreign key -- composite index -- covering index -- OLTP -- OLAP -- sharding -- replication lag -- quorum -- two-phase commit -- saga -- outbox pattern -- inbox pattern -- optimistic locking -- pessimistic locking -- thundering herd -- cache stampede -- bloom filter -- consistent hashing -- virtual DOM -- reconciliation -- closure -- hoisting -- tail call -- GIL -- zero-copy -- mmap -- cold start -- warm start -- green-blue deploy -- canary deploy -- feature flag -- kill switch -- dead letter queue -- fan-out -- fan-in -- debounce -- throttle (UI) -- hydration mismatch -- memory leak -- GC pause -- heap fragmentation -- stack overflow -- null pointer -- dangling pointer -- buffer overflow +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 Lake diff --git a/design-shotgun/SKILL.md b/design-shotgun/SKILL.md index af93ebabd..71f1a0256 100644 --- a/design-shotgun/SKILL.md +++ b/design-shotgun/SKILL.md @@ -2,13 +2,7 @@ name: design-shotgun preamble-tier: 2 version: 1.0.0 -description: | - Design shotgun: generate multiple AI design variants, open a comparison board, - collect structured feedback, and iterate. Standalone design exploration you can - run anytime. Use when: "explore designs", "show me options", "design variants", - "visual brainstorm", or "I don't like how this looks". - Proactively suggest when the user describes a UI feature but hasn't seen - what it could look like. (gstack) +description: Design shotgun: generate multiple AI design variants, open a comparison board, collect structured feedback, and iterate. (gstack) triggers: - explore design variants - show me design options @@ -44,6 +38,15 @@ gbrain: + +## When to invoke this skill + +Standalone design exploration you can +run anytime. Use when: "explore designs", "show me options", "design variants", +"visual brainstorm", or "I don't like how this looks". +Proactively suggest when the user describes a UI feature but hasn't seen +what it could look like. + ## Preamble (run first) ```bash @@ -121,6 +124,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -252,6 +268,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` @@ -602,84 +619,7 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i - User-turn override wins: if the current message asks for terse / no explanations / just the answer, skip this section. - Terse mode (EXPLAIN_LEVEL: terse): no glosses, no outcome-framing layer, shorter responses. -Jargon list, gloss on first use if the term appears: -- idempotent -- idempotency -- race condition -- deadlock -- cyclomatic complexity -- N+1 -- N+1 query -- backpressure -- memoization -- eventual consistency -- CAP theorem -- CORS -- CSRF -- XSS -- SQL injection -- prompt injection -- DDoS -- rate limit -- throttle -- circuit breaker -- load balancer -- reverse proxy -- SSR -- CSR -- hydration -- tree-shaking -- bundle splitting -- code splitting -- hot reload -- tombstone -- soft delete -- cascade delete -- foreign key -- composite index -- covering index -- OLTP -- OLAP -- sharding -- replication lag -- quorum -- two-phase commit -- saga -- outbox pattern -- inbox pattern -- optimistic locking -- pessimistic locking -- thundering herd -- cache stampede -- bloom filter -- consistent hashing -- virtual DOM -- reconciliation -- closure -- hoisting -- tail call -- GIL -- zero-copy -- mmap -- cold start -- warm start -- green-blue deploy -- canary deploy -- feature flag -- kill switch -- dead letter queue -- fan-out -- fan-in -- debounce -- throttle (UI) -- hydration mismatch -- memory leak -- GC pause -- heap fragmentation -- stack overflow -- null pointer -- dangling pointer -- buffer overflow +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 Lake diff --git a/devex-review/SKILL.md b/devex-review/SKILL.md index 945259f60..a15ed7879 100644 --- a/devex-review/SKILL.md +++ b/devex-review/SKILL.md @@ -2,15 +2,7 @@ name: devex-review preamble-tier: 3 version: 1.0.0 -description: | - Live developer experience audit. Uses the browse tool to actually TEST the - developer experience: navigates docs, tries the getting started flow, times - TTHW, screenshots error messages, evaluates CLI help text. Produces a DX - scorecard with evidence. Compares against /plan-devex-review scores if they - exist (the boomerang: plan said 3 minutes, reality says 8). Use when asked to - "test the DX", "DX audit", "developer experience test", or "try the - onboarding". Proactively suggest after shipping a developer-facing feature. (gstack) - Voice triggers (speech-to-text aliases): "dx audit", "test the developer experience", "try the onboarding", "developer experience test". +description: Live developer experience audit. (gstack) triggers: - live dx audit - test developer experience @@ -27,6 +19,19 @@ allowed-tools: + +## When to invoke this skill + +Uses the browse tool to actually TEST the +developer experience: navigates docs, tries the getting started flow, times +TTHW, screenshots error messages, evaluates CLI help text. Produces a DX +scorecard with evidence. Compares against /plan-devex-review scores if they +exist (the boomerang: plan said 3 minutes, reality says 8). Use when asked to +"test the DX", "DX audit", "developer experience test", or "try the +onboarding". Proactively suggest after shipping a developer-facing feature. + +Voice triggers (speech-to-text aliases): "dx audit", "test the developer experience", "try the onboarding", "developer experience test". + ## Preamble (run first) ```bash @@ -104,6 +109,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -235,6 +253,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` @@ -585,84 +604,7 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i - User-turn override wins: if the current message asks for terse / no explanations / just the answer, skip this section. - Terse mode (EXPLAIN_LEVEL: terse): no glosses, no outcome-framing layer, shorter responses. -Jargon list, gloss on first use if the term appears: -- idempotent -- idempotency -- race condition -- deadlock -- cyclomatic complexity -- N+1 -- N+1 query -- backpressure -- memoization -- eventual consistency -- CAP theorem -- CORS -- CSRF -- XSS -- SQL injection -- prompt injection -- DDoS -- rate limit -- throttle -- circuit breaker -- load balancer -- reverse proxy -- SSR -- CSR -- hydration -- tree-shaking -- bundle splitting -- code splitting -- hot reload -- tombstone -- soft delete -- cascade delete -- foreign key -- composite index -- covering index -- OLTP -- OLAP -- sharding -- replication lag -- quorum -- two-phase commit -- saga -- outbox pattern -- inbox pattern -- optimistic locking -- pessimistic locking -- thundering herd -- cache stampede -- bloom filter -- consistent hashing -- virtual DOM -- reconciliation -- closure -- hoisting -- tail call -- GIL -- zero-copy -- mmap -- cold start -- warm start -- green-blue deploy -- canary deploy -- feature flag -- kill switch -- dead letter queue -- fan-out -- fan-in -- debounce -- throttle (UI) -- hydration mismatch -- memory leak -- GC pause -- heap fragmentation -- stack overflow -- null pointer -- dangling pointer -- buffer overflow +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 Lake diff --git a/docs/designs/v2_PLAN.md b/docs/designs/v2_PLAN.md new file mode 100644 index 000000000..bd684df0d --- /dev/null +++ b/docs/designs/v2_PLAN.md @@ -0,0 +1,755 @@ +# gstack v2 — the lightest opinionated skill pack + +## Context + +gstack has an externally documented reputation for being "fat." Third-party reviews (dev.to, May 2026) explicitly say gstack "can feel bloated when all roles are turned on... potentially consuming 10K+ tokens before any real code is written, and daily usage burns through tokens fast... making even straightforward tasks feel sluggish and redundant." Anthropic's own canonical Skills guidance prescribes the "progressive disclosure" pattern (`SKILL.md` skeleton + `references/` loaded on demand) — gstack diverges from this. + +The numbers back the criticism: + +- 31 skills, 2.1MB total generated SKILL.md corpus +- 28 of 31 skills exceed the 40KB soft ceiling (~10K tokens each) +- ship.md is 164KB (~41K tokens); ship.md.tmpl is only 48KB — **115KB is resolver-injected**, the highest-leverage compression target +- Catalog in always-loaded system prompt: 50+ skills × multi-paragraph descriptions, voice triggers, proactive-suggest paragraphs + +This plan ships gstack v2 in two coordinated releases: v1.45.0.0 lands the foundation + low-risk wins, then v2.0.0.0 ships the architectural break + marketing-grade repositioning 2-4 weeks later. The split came out of cross-model review: Codex argued v2 looks like posturing without real breakage; the hybrid shape gives the genuinely-breaking sections/ pattern the major bump it earns, while letting the risk-free wins ship immediately. + +## Release shape + +``` +v1.45.0.0 (Foundation Release) v2.0.0.0 (gstack v2 Launch) +───────────────────────────── ───────────────────────────── +~1-2 weeks of CC work 2-4 weeks later, coordinated + +Phase 0: Eval coverage matrix Phase B: sections/ pattern + gate + periodic for all 31 skills on 5 heavyweights + (ship, plan-ceo, office-hours, +Phase A: Build-time compression plan-eng, plan-design) + conditional resolver injection + jargon dedup Phase C: Eval annotations + terse-mode actually compresses + CI orphan check (WARN→FAIL) + +Catalog trim (Codex high-leverage win) Lighter-touch migration + one-line skill descriptions release note + auto-regenerate + drop voice triggers/proactive blocks on /gstack-upgrade + +Hard token budgets defined Marketing-grade CHANGELOG + enforced via budget-regression v1 vs v2 numbers table + README v2 banner +Normal release voice "lightest opinionated skill pack" +``` + +## Premise check (Step 0A findings) + +1. **Is this the right problem?** YES — externally validated. The bloat criticism is quotable and represents real user pain (token cost, sluggish sessions). Doing nothing means losing users to Cursor/Codex for their "lighter touch" reputation. +2. **Doing nothing:** the criticism compounds. Recent releases (v1.38 → v1.44) all added features; no release has gone the other direction. Without an explicit reversal, the reputation calcifies. +3. **Risk of acting:** the lazy-section pattern introduces silent-behavior-loss as a new failure class. Mitigated by the eval-first foundation + mechanical enforcement + canary rollout (see Phase B integrity section). + +## What already exists (reuse-first audit) + +| Asset | Reuse | +|---|---| +| `scripts/gen-skill-docs.ts` lines 439-450 | Already does string substitution and per-host suppression; extend with `appliesTo` resolver gate (~15 LOC) | +| `scripts/resolvers/types.ts` | Add `ResolverEntry` union type | +| `scripts/resolvers/preamble.ts` | Already does tier-gated composition (1-4); add per-resolver gating | +| `scripts/jargon-list.json` | Already a single file; just stop inlining it 37× | +| `test/skill-e2e-budget-regression.test.ts` (existing gate-tier) | Extend with per-skill hard budgets | +| Real-PTY harness from v1.13.2.0 | Reuse for behavioral-contract evals (~$0.50/eval) | +| SDK harness | Reuse for cheap shape evals (~$0/eval where possible) | +| `gstack-upgrade/migrations/` | Pattern exists for state-format migrations; reuse for v2 auto-regenerate | +| `~/.gstack/analytics/skill-usage.jsonl` | Already collected; powers deferred `gstack budget` CLI | + +We are catching up to Anthropic's canonical Skills pattern, not inventing one. + +## Dream state delta + +``` +TODAY v1.45.0.0 v2.0.0.0 +────── ───────── ──────── +2.1MB corpus ~1.3MB corpus (-40%) ~700KB corpus (-67%) +ship.md: 164KB ship.md: ~80KB (-50%) ship.md: ~15KB skeleton + + 5×~5KB sections +28/31 over 40KB ceiling ~10/31 over ceiling ~3/31 over ceiling + (cso, document-release, + design-consultation + kept as monoliths) +Catalog: multi-paragraph Catalog: one-line per skill Catalog: one-line per skill +descriptions, voice triggers (~70% catalog cut) (same) +No eval coverage matrix Every skill: ≥1 gate eval Section-level eval + + ≥1 periodic eval annotations + CI orphan check +"Fat" reputation in third-party "Compressed, eval-protected" "Lightest opinionated skill +reviews internally measured pack" externally measured +``` + +## Phase 0 — Eval coverage matrix (v1.45.0.0) + +**Goal:** every skill in gstack ships with at least one gate-tier eval AND one periodic-tier eval that asserts a must-have behavior. The eval suite becomes the design spec. This is the load-bearing claim of the plan — must come first. + +**Cross-model tension noted:** Codex argued this is a procrastination trap and shape-asserts are shallow. User explicitly chose full tiered coverage anyway (D9 = A), with rationale: "the eval suite IS the design spec; that commitment is the load-bearing claim of the whole plan." We accept the larger upfront investment. + +**Mitigation of Codex's "shape vs quality" critique:** for orchestration/judgment skills (plan-ceo, office-hours, autoplan), the must-have isn't deterministic output — it's structural compliance (does it call AskUserQuestion in the right shape? does it follow the section order? does it persist artifacts?). Eval design must capture structural contracts, not output content. Where structural eval is impossible, that section is explicitly noted as "judgment-dependent, not eval-protected" — Codex's #2 critique is honored by NOT then stripping unprotected judgment prose. + +**Skills currently lacking dedicated E2E coverage** (eval-writing target): + +| Skill | Gate eval (target) | Periodic eval (target) | Est. cost/run | +|---|---|---|---| +| qa-only | report-only flag triggers | full QA flow with fix-loop disabled | $0.30 / $1.50 | +| retro | weekly aggregate runs without error | full retro produces ranked output | $0.20 / $2.00 | +| document-release | reads CHANGELOG, produces Diataxis map | full post-ship doc update | $0.30 / $1.80 | +| document-generate | generates 4 doc types from prompt | E2E generation passes quality bar | $0.30 / $2.00 | +| context-save | persists state to expected path | round-trip restore preserves context | $0.10 / $0.50 | +| context-restore | reads latest save, applies to session | cross-workspace restore works | $0.10 / $0.50 | +| gstack-upgrade | detects install type, runs upgrade | full upgrade + migration round-trip | $0.20 / $1.00 | +| sync-gbrain | refreshes index without error | full sync produces searchable corpus | $0.20 / $1.50 | +| setup-gbrain | path 1-4 detection works | end-to-end setup for each path | $0.20 / $2.00 | +| setup-browser-cookies | picker UI loads without error | cookie import round-trip | $0.20 / $1.00 | +| setup-deploy | detects config, writes expected files | full deploy config setup | $0.20 / $1.00 | +| design-consultation | DESIGN.md template renders | full design system generation | $0.30 / $2.50 | +| design-shotgun | variants generated and saved | full multi-variant exploration | $0.30 / $2.00 | +| open-gstack-browser | launches browser without error | sidebar attaches and shows activity | $0.20 / $0.80 | +| pair-agent | setup key generated, instructions printed | full pair flow with second agent | $0.20 / $1.50 | +| land-and-deploy | merge gates check correctly | full merge → deploy → canary | $0.30 / $3.00 | +| canary | post-deploy loop runs, exits cleanly | full canary cycle with alert simulation | $0.20 / $1.50 | +| benchmark | runs and produces score | full regression detection | $0.20 / $2.00 | +| plan-devex-review | mode routing works | full DX review with scoring | $0.40 / $3.00 | +| devex-review | live DX audit produces scorecard | E2E DX measurement vs plan baseline | $0.40 / $2.50 | + +Estimated added CI cost: **~$5/run gate, ~$30/run periodic.** Combined with existing E2E suite (~$15/gate, ~$30/periodic), total: ~$20/gate (every PR), ~$60/periodic (weekly). Acceptable. + +**Eval matrix lives at:** `test/helpers/skill-coverage-matrix.ts` — a single source of truth mapping each skill to its gate + periodic eval test files. CI check in `test/skill-coverage-matrix.test.ts` fails the build if any skill is missing an entry. + +**Critical files to add:** +- `test/skill-coverage-matrix.ts` — registry mapping skill → eval paths +- `test/skill-e2e-*.test.ts` — 20 new test files (gate-tier subset starts in gate config, periodic-tier subset in periodic config) +- `test/helpers/touchfiles.ts` — register new tests for diff-based selection + +## Phase A — Build-time compression (v1.45.0.0) + +**A.1 Conditional resolver injection** — extend `scripts/gen-skill-docs.ts` and `scripts/resolvers/`: + +```ts +// scripts/resolvers/types.ts +export type ResolverFn = (ctx: TemplateContext, args?: string[]) => string; +export type ResolverEntry = ResolverFn | { + resolve: ResolverFn; + appliesTo?: (ctx: TemplateContext) => boolean; +}; +``` + +```ts +// scripts/resolvers/index.ts — gate the heavy ones +QUESTION_TUNING: { + resolve: generateQuestionTuning, + appliesTo: (ctx) => ['plan-ceo-review','plan-eng-review','office-hours'].includes(ctx.skillName), +}, +REVIEW_ARMY: { + resolve: generateReviewArmy, + appliesTo: (ctx) => ['ship','review'].includes(ctx.skillName), +}, +REVIEW_DASHBOARD: { + resolve: generateReviewDashboard, + appliesTo: (ctx) => ['ship','plan-ceo-review','plan-eng-review','plan-design-review','plan-devex-review','devex-review'].includes(ctx.skillName), +}, +// ... audit all 21 resolvers, gate per actual usage +``` + +```ts +// scripts/gen-skill-docs.ts (~line 444) — check the gate +const entry = RESOLVERS[resolverName]; +const resolver = typeof entry === 'function' ? entry : entry.resolve; +const gate = typeof entry === 'function' ? undefined : entry.appliesTo; +if (gate && !gate(ctx)) return ''; +return args.length > 0 ? resolver(ctx, args) : resolver(ctx); +``` + +**A.2 Jargon-list dedup** — currently `scripts/resolvers/preamble/generate-writing-style.ts` inlines the full 1.8KB jargon glossary into 37 skills. Replace inline with a reference: "For the canonical jargon list, Read `~/.claude/skills/gstack/scripts/jargon-list.json` on first use." Saves ~66KB total corpus. + +**A.3 Terse-mode actually compresses** — read `~/.gstack/config.yaml` once in `gen-skill-docs.ts`, pass `explainLevel` into `TemplateContext`, and have `generate-writing-style.ts` / `generate-completeness.ts` / `generate-confusion-protocol.ts` / `generate-context-health.ts` return `''` when terse. Today the bytes ship regardless of config — the flag only changes runtime model behavior. Add `--explain-level=terse` build flag for benchmarking. + +**A.4 Catalog trim** (moved up per Codex #6) — shorten skill descriptions in the always-loaded system prompt to one line per skill. Voice triggers move from catalog descriptions into in-skill content. Proactive-suggest paragraphs move to a separate `~/.claude/skills/gstack/scripts/proactive-suggestions.json` loaded only when the agent needs routing guidance. Per-skill description format: + +``` +- : (gstack) +``` + +Estimated catalog cut: ~70% (largest single always-loaded reduction). + +**A.5 cso/ targeted compression** (Codex #9) — cso gets resolver dedup + catalog trim. Security guidance prose stays uncompressed monolithically until Phase B audit shows specific sections can safely move to sections/ with eval coverage. Not "exempt" — just sequenced last. + +**A.6 Hard token budgets** (Codex #10) — define and enforce in `test/skill-e2e-budget-regression.test.ts`: + +| Budget | v1.44 actual | v1.45 target | v2.0 target | +|---|---|---|---| +| Max system-prompt catalog tokens | ~25K | ~8K | ~6K | +| Max per-skill SKILL.md size | 164KB (ship) | 100KB | 30KB (heavyweights) | +| Max corpus total | 2.1MB | 1.3MB | 700KB | +| Max first-invocation latency (heavyweight) | ~immediate | ~immediate | <500ms section reads | + +CI fails if any budget exceeded. Tracked over time via existing budget-regression jsonl. + +## Phase B — sections/ pattern for heavyweights (v2.0.0.0) + +Convert 5 heavyweights to Anthropic-canon skeleton + `sections/*.md`: + +``` +ship/ +├── SKILL.md # 12-15KB decision-tree skeleton + section manifest +├── SKILL.md.tmpl # source for the skeleton +├── sections/ +│ ├── manifest.json # NEW: structured section registry (Codex #3 mitigation) +│ ├── version-bump.md +│ ├── changelog.md +│ ├── review-army.md +│ ├── todos-cleanup.md +│ ├── pr-body.md +│ └── ... +``` + +**Silent-behavior-loss mitigations** (Codex #3) — layered defense, not just self-check: + +1. **Section manifest** (`sections/manifest.json`) — structured registry: `{section_file, applies_when, required_for}`. Decision-tree skeleton references entries by ID, not free-form prose. +2. **Imperative skeleton phrasing** — "STOP. Read `sections/version-bump.md` before computing the bump." Not "see ... for details." +3. **Top-of-file section index table** — situation → section file mapping. +4. **End-of-skill self-check** — "Confirm you Read every section your decision tree pointed to. List them." (weakest layer, kept as fallback.) +5. **Eval harness `requiredReads` declaration** — E2E test asserts which sections must appear in transcript Read calls for a given fixture. Mechanical enforcement at the test layer, not just prompt layer. +6. **Transcript inspection in canary cohort** — first week post-ship, log which sections actually get read by real sessions; alert on Read-miss for marked-required sections. + +**Conversion order** (one at a time, validate each before next): +1. `ship/` — most invocations, biggest cost, riskiest. Land alone, observe 1 week. +2. `plan-ceo-review/` — conversational; risk of breaking flow. Land second, observe carefully. +3. `office-hours/` — most conversational. Land third only if 1+2 went clean. +4. `plan-eng-review/` and `plan-design-review/` — bundle, similar shape. + +**Do not convert** unless explicitly approved later: `autoplan` (orchestrator that already chains skills), `design-review` (UI flow already tight), `qa` (single-purpose), `investigate` (single-purpose). + +## Phase C — Eval annotations + CI orphan check (v2.0.0.0) + +Per Codex #4 — warn-before-fail progression, not immediate strict gate. + +```md + + +``` + +Annotations include **coverage semantics** (what behavior is protected) per Codex #5, not just paths. Path-only would be false confidence. + +CI check in `gen-skill-docs.ts` walker: +- v2.0.0.0 ships in WARN mode — orphans logged to PR summary but build passes +- v2.1.0.0 (or 2 release cycles after v2.0): WARN escalates to FAIL +- Waiver: `` + +This avoids "maintenance theater" of mandatory annotations with no semantics, and gives users a transition window. + +## Migration approach (v2.0.0.0, lighter touch per D11) + +- Release note in v2.0.0.0 CHANGELOG explains the sections/ format change and concrete user impact: forks/copy-pasted SKILL.md files need re-fetch; first-invocation of heavyweight skills has ~200-500ms section-read latency added. +- `/gstack-upgrade` auto-regenerates on next invocation. No interactive migration prompts. +- Vendored installs get a single one-line warning at session start on first v2 contact (re-use existing vendored-install warning pattern in skill preamble). +- `gstack-upgrade --explain-v2` flag for users who want the full explanation on demand. + +## Forks / customization compatibility (Codex #11) + +Documented in v2.0.0.0 release note: + +- Anyone who reads/copies/edits a heavyweight SKILL.md file directly: the file is now a skeleton; behavior lives in `sections/*.md`. They need to either treat the skill as a black box (recommended) or fork the full `skill/` directory including `sections/`. +- Anyone with local SKILL.md.tmpl edits in a fork: the templates are smaller; conflicts likely on regenerate. Fork docs updated with migration guidance. +- Anyone with docs/blog posts linking to specific lines of a generated SKILL.md: line numbers will shift; recommend linking to template + section name instead. + +## Rollout strategy (Codex #12) + +v1.45.0.0: +- Land in one PR; existing budget-regression test catches any per-skill size regression; eval matrix CI check catches any skill missing its evals. +- Dogfood: 1 week active use across all of Garry's workspaces before announcing. + +v2.0.0.0: +- **Canary cohort**: ship to dogfood users (Garry + active agents) first via a v2.0.0-rc.1 tag. Real-PTY harness logs section Reads for top 5 workflows (`/ship`, `/qa`, `/review`, `/plan-ceo-review`, `/autoplan`); alert on Read-miss for required sections. +- **Manual verification**: top 5 workflows manually run before tagging v2.0.0.0 final, with before/after transcripts saved as eval baselines. +- **Regression dashboard**: existing `bun run eval:summary` extended with v1 vs v2 per-skill token + behavioral compliance comparison. +- **Rollback**: revert PR + `bun run gen:skill-docs` regenerates old shape. Documented in CONTRIBUTING.md. + +## Review-section findings (Sections 1-11, condensed) + +| Section | Findings | Status | +|---|---|---| +| 1. Architecture | Lazy-section silent-loss risk; mitigated via 6-layer defense above | Findings addressed in plan | +| 2. Errors/Rescues | gen-skill-docs gate-fail loud; missing sections fall back to skeleton; CI orphan check loud | Findings addressed | +| 3. Security | cso targeted dedup not blanket exemption (Codex #9); migration script runs at user-shell trust boundary, same as existing migrations | Findings addressed | +| 4. Data/UX edge cases | v1→v2 muscle-memory break warned in release note; vendored installs get one-line warning; concurrent dev-symlink sessions risk is existing CLAUDE.md caveat | Findings addressed | +| 5. Code quality | ~150 LOC additive across gen-skill-docs/types/index; ~20 new eval test files; sections/ extraction is mechanical | OK | +| 6. Tests | Phase 0 IS the test plan. Coverage matrix CI gate enforces every skill has its evals | Findings addressed | +| 7. Performance | Build time <2× current; runtime adds 200-500ms first-invocation for sectioned heavyweights; catalog trim reduces always-loaded prompt size on every session | Documented | +| 8. Observability | budget-regression test already exists; canary cohort transcript logging in Phase B; migration outcome logged to ~/.gstack/analytics/migrations.jsonl | Findings addressed | +| 9. Deployment | Two-release split + warn-before-fail eval annotations + rollback via revert | Findings addressed | +| 10. Long-term trajectory | Reversibility 3/5; sections/ pattern becomes template for future skills; deferred TODOs extend v2 narrative for v2.1+ | OK | +| 11. Design/UX | README v2 banner + CHANGELOG numbers table land in v2.0.0.0; concrete numbers, gstack voice, no AI slop | OK | + +## NOT in scope + +- **Skill removals.** User said "keep all functions." qa-only, design-shotgun, pair-agent, open-gstack-browser all stay. They get evals + catalog trim like everyone else. +- **Skill renames.** No `qa` → `qa-fix` collapses. Keep CLI surface stable. +- **gstack lite/pro install profiles.** Deferred to TODOS for post-v2. +- **gstack budget CLI.** Deferred to TODOS for post-v2. +- **Per-skill eval coverage badge in README.** Deferred to TODOS. +- **Cross-tool portability test/demo (Codex/Cursor compat).** Deferred to TODOS. +- **Token-cost preview on invocation.** Deferred to TODOS. +- **Skill autoload telemetry.** Deferred to TODOS. +- **gstack diff PR comment.** Deferred to TODOS. + +## TODOS.md updates (deferred items, recommend bulk-add post-merge) + +| TODO | Priority | Effort (human / CC) | Depends on | +|---|---|---|---| +| `gstack lite` install profile (5-skill core) | P2 | 2 days / 3-4 hrs | v2.0.0.0 | +| `gstack pro` opt-in upgrade path | P2 | 1 day / 1 hr | gstack lite | +| `gstack budget` CLI (per-skill token usage telemetry) | P2 | 1 day / 1 hr | v1.45.0.0 | +| Per-skill eval coverage badge in `gstack-skills list` + README | P3 | 1 day / 1 hr | Phase 0 | +| Cross-tool portability test/demo (Codex CLI, Cursor) | P3 | 2 days / 2 hrs | v2.0.0.0 | +| Token-cost preview on skill invocation | P3 | 1 day / 1 hr | gstack budget CLI | +| Skill autoload telemetry (dead-weight detection) | P3 | 2 days / 2 hrs | v1.45.0.0 | +| `gstack diff` PR comment (per-PR budget delta) | P3 | 1 day / 1 hr | budget-regression extended | +| Section-level eval annotations visible to user (confidence signal) | P3 | half day / 30 min | Phase C | + +## Critical files + +| Path | Change | Phase | +|---|---|---| +| `scripts/gen-skill-docs.ts` | Add resolver gate check (~line 444); read explain_level from config; add CI orphan walker | A, C | +| `scripts/resolvers/types.ts` | Add `ResolverEntry` union type | A | +| `scripts/resolvers/index.ts` | Wrap heavy resolvers with `appliesTo` predicates (audit all 21) | A | +| `scripts/resolvers/preamble/generate-writing-style.ts` | Replace inline jargon; return `''` on terse | A | +| `scripts/resolvers/preamble/generate-completeness.ts` | Return `''` on terse | A | +| `scripts/resolvers/preamble/generate-confusion-protocol.ts` | Return `''` on terse | A | +| `scripts/resolvers/preamble/generate-context-health.ts` | Return `''` on terse | A | +| `scripts/skill-catalog.ts` (new or in gen-skill-docs) | One-line catalog generator + voice-triggers JSON splitter | A.4 | +| `scripts/proactive-suggestions.json` (new) | Voice triggers + proactive suggestions, loaded on demand | A.4 | +| `test/skill-coverage-matrix.ts` (new) | Single-source-of-truth eval registry | Phase 0 | +| `test/skill-coverage-matrix.test.ts` (new) | CI gate: every skill has entries | Phase 0 | +| `test/skill-e2e-*.test.ts` (~20 new files) | New evals for skills currently lacking coverage | Phase 0 | +| `test/skill-e2e-budget-regression.test.ts` | Extend with per-skill hard budgets | A.6 | +| `test/helpers/touchfiles.ts` | Register new tests for diff-based selection | Phase 0 | +| `ship/SKILL.md.tmpl` → `ship/sections/manifest.json` + `ship/sections/*.md` | Skeleton extraction | B | +| `plan-ceo-review/SKILL.md.tmpl` → sections/ | Skeleton extraction | B | +| `office-hours/SKILL.md.tmpl` → sections/ | Skeleton extraction | B | +| `plan-eng-review/SKILL.md.tmpl` → sections/ | Skeleton extraction | B | +| `plan-design-review/SKILL.md.tmpl` → sections/ | Skeleton extraction | B | +| `gstack-upgrade/migrations/v2.0.0.0.sh` (new) | Auto-regenerate + vendored-install warning | B | +| `CHANGELOG.md` | v1.45.0.0 entry (normal), v2.0.0.0 entry (marketing-grade w/ numbers table) | A, B | +| `README.md` | v2.0.0.0 banner; "lightest opinionated skill pack" positioning | B | +| `CONTRIBUTING.md` | Document sections/ pattern + rollback procedure | B | + +## Verification + +**v1.45.0.0:** +1. `bun run gen:skill-docs` succeeds with no errors +2. `bun test` passes (skill-validation, gen-skill-docs.test.ts, browse integration, NEW skill-coverage-matrix.test.ts) +3. `bun run test:evals` passes — all new gate evals green; no regression on existing evals +4. `bun run test:evals:periodic` passes — all new periodic evals green +5. Catalog system-prompt size measured: target ≤8K tokens (vs ~25K current). Capture before/after in PR body. +6. Total SKILL.md corpus byte count: target ≤1.3MB (vs 2.1MB). Capture in PR body. +7. Top 3 heaviest skills under 100KB. +8. Manual smoke: invoke `/ship`, `/plan-ceo-review`, `/office-hours` in fresh Claude Code sessions; confirm no missing behavior. Save transcripts as v1.45 baselines. + +**v2.0.0.0:** +1. All v1.45 checks pass +2. Sectioned skills: total corpus ≤700KB; heavyweight skeletons ≤30KB each +3. `test/skill-e2e-ship-section-loading.test.ts` (new): asserts `/ship` Reads expected sections per decision tree +4. Canary cohort: 1 week dogfood at v2.0.0-rc.1 with transcript logging; zero Read-miss for marked-required sections +5. Top 5 workflows manually verified; transcripts compared against v1.45 baselines +6. Migration: `gstack-upgrade` on a v1.45 install successfully regenerates without prompts; vendored-install warning appears once +7. CHANGELOG numbers table matches measured reality +8. WARN-mode orphan check: PR summary shows orphan list; build passes + +## Cross-model agreements baked in + +Items from Codex's review accepted and integrated above: + +- #4 Warn-before-fail eval annotations (Phase C) +- #5 Coverage semantics in annotation comments, not just paths +- #6 Catalog trim moved up to Phase A (was buried after sections/) +- #9 cso gets resolver dedup + catalog trim (not blanket exempt) +- #10 Hard token budgets defined + enforced (Phase A.6) +- #11 Forks/customization compatibility documented (Migration section) +- #12 Rollout strategy with canary cohort + manual top-5-workflows verification (Rollout section) + +Items from Codex's review explicitly rejected by user (D9, D10): +- #1 Eval-first scope: user kept full tiered coverage. Mitigated by structural-eval guidance (not output-content) for orphan/judgment skills. +- #7 v2.0.0.0 vs v1.x: user chose HYBRID. v1.45 absorbs low-risk wins; v2.0.0.0 carries the genuinely-breaking sections/ change. + +Item where user accepted Codex over original pick: +- #8 Migration approach: user moved from hard-cut (D7) to lighter touch (D11) once v1.45 absorbed the low-risk work. + +## Implementation Tasks + +Synthesized from this review's findings. Each task derives from a specific phase/finding above. T1-T8 land in v1.45.0.0; T9-T16 land in v2.0.0.0. + +- [ ] **T1 (P1, human: ~3 days / CC: ~7 hours)** — Phase 0 / coverage matrix — write gate+periodic evals for all 20 skills lacking coverage + - Surfaced by: Phase 0 section + - Files: `test/skill-coverage-matrix.ts`, `test/skill-coverage-matrix.test.ts`, ~20 new `test/skill-e2e-*.test.ts`, `test/helpers/touchfiles.ts` + - Verify: `bun test test/skill-coverage-matrix.test.ts` and `bun run test:evals` both pass with new evals +- [ ] **T2 (P1, human: ~1 day / CC: ~1 hour)** — A.1 conditional resolver injection — add `appliesTo` gate + - Surfaced by: Phase A section, Codex #10 (measurement before architecture) + - Files: `scripts/resolvers/types.ts`, `scripts/gen-skill-docs.ts:444`, `scripts/resolvers/index.ts` + - Verify: `bun run gen:skill-docs` produces smaller SKILL.md files; `bun test` passes +- [ ] **T3 (P1, human: ~half day / CC: ~30 min)** — A.2 + A.3 jargon dedup + terse-mode gen-time compression + - Surfaced by: Phase A section + - Files: `scripts/resolvers/preamble/generate-writing-style.ts`, `generate-completeness.ts`, `generate-confusion-protocol.ts`, `generate-context-health.ts` + - Verify: jargon-list no longer appears inlined in generated SKILL.md; `gstack-config set explain_level terse && bun run gen:skill-docs` produces shorter files +- [ ] **T4 (P1, human: ~1 day / CC: ~2 hours)** — A.4 catalog trim — one-line skill descriptions; voice triggers + proactive paragraphs moved to JSON + - Surfaced by: Codex #6 (highest-leverage), Phase A.4 + - Files: `scripts/skill-catalog.ts` (new), `scripts/proactive-suggestions.json` (new), per-skill SKILL.md.tmpl frontmatter for one-line description field + - Verify: catalog system-prompt size <8K tokens; voice-triggered invocation still works +- [ ] **T5 (P1, human: ~half day / CC: ~30 min)** — A.6 hard token budgets in budget-regression + - Surfaced by: Codex #10 + - Files: `test/skill-e2e-budget-regression.test.ts` + - Verify: budget-regression fails when artificially inflated test SKILL.md exceeds budget +- [ ] **T6 (P1, human: ~1 day / CC: ~1 hour)** — A.5 cso resolver dedup + catalog trim (NOT broader compression) + - Surfaced by: Codex #9 + - Files: `cso/SKILL.md.tmpl` (no structural change, only resolver gate audit) + - Verify: cso SKILL.md size drops 20-30%; cso E2E evals still pass +- [ ] **T7 (P1, human: ~1 day / CC: ~1 hour)** — Regenerate all SKILL.md atomically + measure + - Surfaced by: Phase A + - Files: all `*/SKILL.md` regenerated + - Verify: PR body includes before/after corpus size, top 10 skill sizes, catalog size; budget-regression confirms targets met +- [ ] **T8 (P2, human: ~half day / CC: ~30 min)** — v1.45.0.0 CHANGELOG entry (normal voice; note that Phase 0 + Phase A landed) + - Surfaced by: Release shape section + - Files: `CHANGELOG.md`, `VERSION` + - Verify: CHANGELOG lints clean; reverse-chrono order preserved; entry covers the diff + +- [ ] **T9 (P1, human: ~2 days / CC: ~3 hours)** — Phase B.1 convert ship/ to skeleton + sections/ + - Surfaced by: Phase B section + - Files: `ship/SKILL.md.tmpl` → skeleton; `ship/sections/manifest.json` + `ship/sections/*.md` + - Verify: new `test/skill-e2e-ship-section-loading.test.ts` asserts expected Reads per decision tree; existing ship evals pass; ship.md skeleton <15KB +- [ ] **T10 (P1, human: ~1 day / CC: ~1 hour)** — Canary cohort for ship/ (1 week dogfood at v2.0.0-rc.1) + - Surfaced by: Rollout strategy section, Codex #12 + - Files: `test/helpers/transcript-section-logger.ts` (new) + - Verify: zero Read-miss on marked-required sections in dogfood transcripts +- [ ] **T11 (P1, human: ~2 days / CC: ~3 hours)** — Phase B.2 convert plan-ceo-review/ (after ship/ proven) + - Surfaced by: Phase B section + - Files: `plan-ceo-review/SKILL.md.tmpl` + `plan-ceo-review/sections/` + - Verify: section-loading test green; plan-ceo evals pass +- [ ] **T12 (P2, human: ~3 days / CC: ~4 hours)** — Phase B.3 + B.4 convert office-hours/ + plan-eng-review/ + plan-design-review/ + - Surfaced by: Phase B section + - Files: respective `SKILL.md.tmpl` + `sections/` directories + - Verify: section-loading tests green; respective evals pass +- [ ] **T13 (P1, human: ~1 day / CC: ~1 hour)** — Phase C eval annotations + WARN-mode CI orphan check + - Surfaced by: Phase C section, Codex #4 + #5 + - Files: `scripts/gen-skill-docs.ts` (orphan walker), all `sections/*.md` (annotations with coverage semantics) + - Verify: orphan check reports correctly in PR summary; build still passes in WARN mode +- [ ] **T14 (P1, human: ~half day / CC: ~30 min)** — `gstack-upgrade/migrations/v2.0.0.0.sh` lighter-touch auto-regenerate + - Surfaced by: Migration approach section + - Files: `gstack-upgrade/migrations/v2.0.0.0.sh` + - Verify: upgrade from v1.45 install produces clean v2 state without prompts; vendored install gets one-line warning +- [ ] **T15 (P1, human: ~half day / CC: ~1 hour)** — v2.0.0.0 marketing-grade CHANGELOG with v1 vs v2 numbers table + - Surfaced by: D5, Release shape, Codex #7 (real breakage documented) + - Files: `CHANGELOG.md`, `VERSION`, `README.md` (v2 banner) + - Verify: numbers table matches measured corpus; release note documents concrete breakage (sections/ format change, first-invocation latency, vendored-install deprecation); positioning past-tenses bloat reputation +- [ ] **T16 (P2, human: ~1 day / CC: ~1 hour)** — Bulk-add 9 deferred TODOS to TODOS.md (gstack lite, gstack budget, etc.) + - Surfaced by: TODOS.md updates section + - Files: `TODOS.md` + - Verify: TODOS format matches `.claude/skills/review/TODOS-format.md` + +## Failure Modes Registry + +| Codepath | Failure mode | Rescued? | Test? | User sees | Logged | +|---|---|---|---|---|---| +| gen-skill-docs.ts gate check | resolver `appliesTo` throws | Y — try/catch logs + skips resolver | Y (test/gen-skill-docs.test.ts extended) | "resolver X errored, skipped" in build output | stderr | +| sections/ Read at runtime | section file missing | Y — agent falls back to skeleton-only behavior | Y (test/skill-e2e-ship-section-loading.test.ts) | warning in agent prose | session transcript | +| CI orphan walker | sections/*.md missing eval annotation | WARN mode v2.0; FAIL v2.1+ | Y (test/skill-coverage-matrix.test.ts) | PR summary lists orphans | PR comment | +| Migration script v2.0.0.0.sh | regenerate fails on damaged install | Y — script aborts, prints repair steps | Y (migration test) | clear error + repair steps | ~/.gstack/analytics/migrations.jsonl | +| Catalog one-line generator | skill missing one-line description in frontmatter | Y — gen-skill-docs fails build loudly | Y (gen-skill-docs.test.ts extended) | build error | stderr | +| Canary section-Read logger | logger missing for a heavyweight skill | Y — silently skipped, gap visible in dashboard | Y (transcript-logger test) | none directly; surfaced in canary dashboard | ~/.gstack/analytics/section-reads.jsonl | + +No critical gaps — every failure mode has a rescue, a test, and visibility. + +## Diagrams + +System architecture (build pipeline): +``` + CONFIG (~/.gstack/config.yaml) + | + v + +-----------------+ +--------------------+ + | gen-skill-docs | <--- | resolvers/*.ts | + | (with gate) | | (w/ appliesTo) | + +-----------------+ +--------------------+ + | + v + +--------------------------+ + | SKILL.md.tmpl per skill | + | + sections/manifest.json | (heavyweights only, v2) + | + sections/*.md | (heavyweights only, v2) + +--------------------------+ + | + v + +--------------------+ +--------------------------+ + | generated SKILL.md | <-----> | scripts/jargon-list.json | + | (skeleton for | | (referenced, not inlined)| + | heavyweights v2) | +--------------------------+ + +--------------------+ + | + v + +-------------------+ +----------------------+ + | catalog (system | <--- | proactive-suggestions| + | prompt, one-line | | .json (loaded on | + | per skill) | | demand only) | + +-------------------+ +----------------------+ +``` + +Section-Read flow (v2 runtime): +``` + USER /ship + | + v + +-----------------------+ + | ship/SKILL.md | + | (12-15KB skeleton) | + | reads: | + | - manifest.json | + | - decision tree | + +-----------------------+ + | + v Agent walks decision tree, identifies which sections apply + | + +-----> Read sections/version-bump.md (if bumping) + +-----> Read sections/changelog.md (if writing entry) + +-----> Read sections/review-army.md (if pre-ship review) + +-----> ... only sections that apply + | + v + +-------------------------+ + | end-of-skill self-check | + | "list sections I read" | + +-------------------------+ + | + v Canary cohort: transcript-section-logger compares + | actual Reads vs manifest's required_for declarations + | alerts on miss +``` + +## Stale diagram audit + +ASCII diagrams in CLAUDE.md / ARCHITECTURE.md that this plan affects: + +| Diagram | File | Still accurate post-v2? | +|---|---|---| +| Sidebar message flow | `docs/designs/SIDEBAR_MESSAGE_FLOW.md` | YES (unrelated subsystem) | +| Dual-listener tunnel architecture | `ARCHITECTURE.md` | YES (unrelated) | +| Unicode sanitization at server egress | `ARCHITECTURE.md` | YES (unrelated) | +| (none for skill build pipeline) | — | New diagrams above are NEW, not updates | + +No stale diagrams to fix. + +## Completion summary + +``` ++====================================================================+ +| MEGA PLAN REVIEW — COMPLETION SUMMARY | ++====================================================================+ +| Mode selected | SCOPE EXPANSION | +| System Audit | bloat externally documented; prior design | +| | doc unrelated; budget-regression infra exists| +| Step 0 | EXPANSION + Approach C + eval-first + | +| | hybrid v1.45/v2.0 split + lighter migration | +| Section 1 (Arch) | 1 finding — silent-loss risk, 6-layer mit | +| Section 2 (Errors) | 6 failure modes mapped, 0 CRITICAL GAPS | +| Section 3 (Security)| cso targeted dedup (Codex #9 absorbed) | +| Section 4 (Data/UX) | v1→v2 muscle memory warned, vendored noted | +| Section 5 (Quality) | ~150 LOC additive, mechanical extraction | +| Section 6 (Tests) | Phase 0 IS the test plan | +| Section 7 (Perf) | <2× build time; +200-500ms first-invoke v2 | +| Section 8 (Observ) | budget-regression + canary + migrations.log | +| Section 9 (Deploy) | 2-release split + warn-before-fail + revert | +| Section 10 (Future) | Reversibility 3/5; sections/ becomes template| +| Section 11 (Design) | README banner + numbers table | ++--------------------------------------------------------------------+ +| NOT in scope | written (9 items deferred) | +| What already exists | written (9 reuse points) | +| Dream state delta | written (TODAY / v1.45 / v2.0) | +| Error/rescue registry| 6 modes, 0 CRITICAL GAPS | +| Failure modes | covered in registry | +| TODOS.md updates | 9 items, bulk-add post-merge | +| Scope proposals | 3 surfaced, 1 accepted (launch positioning) | +| CEO plan | this plan IS the CEO plan | +| Outside voice | ran (codex); 3 tensions surfaced | +| Lake Score | 11/11 recommendations chose complete option | +| Diagrams produced | 2 (build pipeline, section-read flow) | +| Stale diagrams found | 0 | +| Unresolved decisions | 0 | ++====================================================================+ +``` + +## Eng-review additions (from /plan-eng-review session) + +### Architectural decisions locked in + +- **D1 (manifest format):** `sections/manifest.json` is the structured per-heavyweight registry (JSON, machine-readable for gen-skill-docs CI checks). SKILL.md skeleton is markdown headers + imperative prose blocks ("STOP. If X, Read `sections/Y.md`"). Matches Anthropic's documented `references/` style. No invented DSL. +- **D2 (drift control):** `sections/*.md.tmpl` is the source of truth; `sections/*.md` is generated. gen-skill-docs walks `/sections/*.tmpl` and writes `/sections/*.md` using the same resolver pipeline as SKILL.md. Cost: ~30 LOC in `scripts/gen-skill-docs.ts`. Eliminates the drift class that `test/ship-version-sync.test.ts` already suffers from (TODOS:1120). +- **D3 (CI cost cap):** `EVALS_BUDGET_HARD_CAP=$30` env var enforced by `test/skill-e2e-budget-regression.test.ts`; build fails if a single run exceeds. Section-loading tests (Phase B) use minimal-bash fixtures (~$0.30 each) because they assert STRUCTURAL behavior (was the right file Read?) not output quality. + +### Adjacent TODOS surfaced (informational, not blocking) + +- **TODOS:161** — planned "resolver injection at session start" for browser-skills (P2). Has architectural overlap with this plan's `appliesTo` predicate. Decision: keep separate for now — browser-skill resolver injection is runtime (session-start hostname matching); our `appliesTo` is build-time (gen-skill-docs.ts). Different lifecycles, different concerns. Revisit only if the browser-skills work needs the same predicate shape. +- **TODOS:1120** — `test/ship-version-sync.test.ts` reimplements ship/SKILL.md.tmpl Step 12 bash. D2 (sections/*.md.tmpl pipeline) is the structural fix. Phase B work obviates this TODO; mark as resolved when ship/ extraction lands. +- **TODOS:1136** — `git show` fallback in ship/SKILL.md.tmpl Step 12 line 409. Phase B touches this; bundle the `git rev-parse --verify` fix into the version-bump section extraction. + +### Test plan artifact + +Test plan written to `~/.gstack/projects/garrytan-gstack/garrytan-garrytan-slim-skill-tokens-eng-review-test-plan-.md`. `/qa` and `/qa-only` consume this as primary test input. Covers: per-phase test coverage targets, fixture design for section-loading tests, CI budget enforcement check, migration round-trip test. + +### Failure modes additions + +Adding to the registry from §Failure Modes (already complete; new rows): + +| Codepath | Failure mode | Rescued? | Test? | User sees | Logged | +|---|---|---|---|---|---| +| sections/*.md.tmpl generator | template references missing resolver | Y — gen-skill-docs fails build loudly | Y (gen-skill-docs.test.ts extended) | build error | stderr | +| Manifest ↔ filesystem consistency | manifest references section file that doesn't exist | Y — CI check fails | Y (new `test/section-manifest-consistency.test.ts`) | build error | PR summary | +| Manifest ↔ filesystem consistency | section file exists but not in manifest (orphan) | WARN v2.0; FAIL v2.1+ | Y (same test) | PR summary | PR comment | +| Budget cap exceeded | single test or aggregate exceeds `EVALS_BUDGET_HARD_CAP` | Y — CI fails | Y (budget-regression extended) | build error w/ cost breakdown | stderr | + +Still 0 critical gaps. All new failure modes have rescue + test + visibility. + +### Execution sequencing (sequential v1.45, integration-branch v2.0) + +v1.45 runs **sequentially** in a single branch, T1 → T8. The parallelization map was reconsidered after codex's second-pass critique flagged that T2 (gen-skill-docs.ts TemplateContext changes) and T4 (catalog frontmatter additions) almost certainly touch each other at compile time — both branches passing alone, failing at integration. Sequential lands cleaner and avoids 3-way merge surprise. AI compression makes the wall-clock cost of sequential acceptable. + +| Step | Modules touched | Depends on | +|---|---|---| +| T1 Phase 0 evals (~20 files) | `test/skill-e2e-*.test.ts`, `test/skill-coverage-matrix.ts`, `test/helpers/touchfiles.ts` | — | +| T2 conditional resolver gate | `scripts/gen-skill-docs.ts`, `scripts/resolvers/types.ts`, `scripts/resolvers/index.ts` | T1 | +| T3 jargon dedup + terse compression | `scripts/resolvers/preamble/*` | T2 | +| T4 catalog trim | `scripts/skill-catalog.ts`, `scripts/proactive-suggestions.json`, all SKILL.md.tmpl frontmatter | T2 | +| T5 hard token budgets + override path | `test/skill-e2e-budget-regression.test.ts` (per-suite caps + `EVALS_BUDGET_OVERRIDE_REASON`) | T1 | +| T6 cso targeted dedup | `cso/SKILL.md.tmpl` | T2, T3 | +| T7 regenerate all SKILL.md atomically | all `*/SKILL.md` | T1-T6 | +| T8 v1.45 CHANGELOG | `CHANGELOG.md`, `VERSION` | T7 | +| **— v1.45.0.0 ship boundary —** | | | +| T9 ship/ sections/ extraction | `ship/SKILL.md.tmpl`, `ship/sections/*`, gen-skill-docs (sections pipeline w/ TemplateContext contract) | T8 + sections-pipeline (T2/D2) | +| T10 ship/ canary cohort | `test/helpers/transcript-section-logger.ts` | T9 | +| T11 plan-ceo-review sections/ | `plan-ceo-review/SKILL.md.tmpl` + sections | T10 (ship/ proven) | +| T12 office-hours + plan-eng + plan-design sections/ | respective directories | T11 | +| T13 Phase C eval annotations + 3-tier orphan check | gen-skill-docs.ts orphan walker, all sections/*.md | T9-T12 | +| T14 migration script | `gstack-upgrade/migrations/v2.0.0.0.sh` | T13 | +| T15 v2.0.0.0 CHANGELOG + README banner | `CHANGELOG.md`, `README.md`, `VERSION` | T14 | +| T16 TODOS bulk-add | `TODOS.md` | — anytime | + +**Execution recommendation:** single-worktree sequential for both v1.45 (T1→T8) and v2.0 (T9→T15). T16 lands whenever. The CC speedup comes from per-step compression (each step is ~1 hour vs human-days), not from parallel branches. + +## Codex consult additions (second pass, post eng-review) + +### Cathedral parity-eval suite (Phase 0 add-on, expanded to "11") + +User said "do it like 11, not just 10. max it out and then some." Maxed-out scope: + +- **ALL 31 skills** get golden-baseline transcripts (not just top 5) +- **Multiple fixtures per skill** (3-5 representative invocation paths each) +- **Quantitative + qualitative scoring:** LLM-as-judge similarity score (1-10) AND transcript-diff highlights (added/removed sections, missing nuance) +- **Token-efficiency ratio measured:** quality-per-token = judge_score / tokens_consumed (forces v2 to be measurably MORE efficient, not just smaller) +- **"Quality budget" alongside "token budget":** both enforced in CI. A v2 skill that compressed to half size but dropped from 9/10 quality to 6/10 fails the gate. +- **Side-by-side PR comment:** every PR that touches a heavyweight skill auto-posts a v1.45-baseline vs current parity comparison in the PR summary +- **Public benchmark page:** `gstack.benchmarks.md` (new), continuously updated. Quotable: "v2 average parity score: 9.2/10, average token reduction: 67%." +- **Continuous monitoring:** parity suite runs weekly on main; alerts if any skill drifts below baseline (Discord webhook or similar) +- **Baseline-capture script:** `test/helpers/capture-parity-baseline.ts` — run once at v1.44 HEAD to lock in golden transcripts before any Phase A work lands + +Effort: human ~3-4 days / CC ~6-8 hours one-time + ~$30/week ongoing for continuous monitoring. Cost is justified — this is the ONLY mechanism that catches "looks green, feels worse" silent regression that section-loading and budget tests both miss. Adds new tasks T0a (baseline capture) and T0b (parity eval harness) BEFORE T1. + +### Absorbed refinements from codex consult (no further user decision needed) + +1. **TemplateContext contract for sections pipeline (codex D2 critique):** explicit spec required in T9. Section generation uses the SAME `TemplateContext` as SKILL.md generation — same `skillName`, same host suppression, same `explainLevel`, same tier gating. Documented in code comments + asserted by `test/template-context-parity.test.ts` (new). +2. **3-tier orphan classification (codex orphan-semantics critique):** the CI check (T13) distinguishes: + - **Generated orphan** (`sections/foo.md` exists, no `sections/foo.md.tmpl`) → FAIL immediately, every release + - **Manifest orphan** (`sections/foo.md.tmpl` exists, not in `manifest.json`) → WARN in v2.0, FAIL in v2.1+ + - **Hand-edited generated file** (`sections/foo.md` diverges from what regen would produce) → FAIL immediately, with "this file is generated, edit `.tmpl` instead" message +3. **Budget cap override path (codex D3 critique):** `EVALS_BUDGET_HARD_CAP=$30` becomes the default; per-suite caps via `EVALS_BUDGET_HARD_CAP_GATE=$25`, `EVALS_BUDGET_HARD_CAP_PERIODIC=$70`; override path `EVALS_BUDGET_OVERRIDE_REASON=""` env required to exceed cap (CI prints the reason in build output for audit trail); daily org-level spend alert via existing analytics (`~/.gstack/analytics/skill-usage.jsonl` aggregator). +4. **Manifest as passive data (codex D1 critique):** `manifest.json` fields are IDs, file paths, and human-readable trigger text ONLY. No `applies_when` predicate. The skill skeleton's decision-tree prose is the ONLY place "when to read X" is decided. Avoids inventing a fourth condition language alongside tier-gating + `appliesTo` + `requiredReads`. +5. **T7 as integration-branch flow (codex parallelization critique, now obviated by sequential):** sequential execution means T7 is just "atomic regenerate within the single v1.45 branch." Integration-branch dance not needed. The critique's intent (no 3-way merge surprise) is honored by collapsing to sequential. + +### New failure modes (additions to registry) + +| Codepath | Failure mode | Rescued? | Test? | User sees | Logged | +|---|---|---|---|---|---| +| Sections pipeline TemplateContext | sections generated with divergent ctx (e.g. wrong skillName) | Y — parity test fails | Y (`test/template-context-parity.test.ts`) | build error | stderr | +| Hand-edited generated section | user edits `sections/foo.md` directly instead of `.tmpl` | Y — CI fails with explicit message | Y (orphan-check 3-tier classification) | "this file is generated, edit `.tmpl` instead" | PR summary | +| Quality budget exceeded | v2 skill compressed but dropped >2 points on LLM-judge parity | Y — CI fails | Y (parity-eval suite) | "v2 X.md dropped from 9.2 to 6.4 vs v1.45 baseline" | PR comment with diff | +| Budget cap override audit | EVALS_BUDGET_OVERRIDE_REASON used | N (intentional escape valve) | Y (audit-log test) | reason printed in CI output, logged to spend-audit jsonl | analytics/spend-overrides.jsonl | +| Parity baseline drift on main | weekly continuous monitor detects regression | Y — Discord alert + ticket | Y (continuous-monitor test) | alert in team channel | analytics/parity-drift.jsonl | + +Still 0 critical gaps. + +## v2 launch copy specs (from /plan-devex-review) + +These drafts become the source of truth for v2.0.0.0 launch tone. T15 implements them verbatim (unless workshopping at ship time produces a measurably better take, in which case update both plan and implementation in lockstep). + +### JUST_UPGRADED notice (Persona A — existing user upgrading) + +Triggered by `gstack-update-check` showing `JUST_UPGRADED v1.x v2.0.0.0`. Replaces the generic v1 "Running gstack v{to} (just updated!)" with persona-A-aware copy that names the perceived speed win AND signals "your muscle memory still works." + +``` +Running gstack v2.0.0.0 (just updated!) — your sessions are now ~67% lighter. +Heavyweight skills load only the sections they need; the catalog dropped to +one line per skill. Everything still works the same way — your /ship, /qa, +/review commands haven't changed. Run `/gstack-upgrade --explain-v2` for the +full migration story, or just keep working. +``` + +Voice rules honored: lead with the win ("67% lighter"); concrete numbers; reassurance that workflows are unchanged ("everything still works the same way"); escape hatch (`--explain-v2`). No em dashes. Aimed at a 5-second read. + +Implementation: update `~/.claude/skills/gstack/gstack-upgrade/SKILL.md.tmpl` Inline upgrade flow with v2-aware message; existing `JUST_UPGRADED ` detection in skill preamble fires it. + +### CHANGELOG numbers table (Persona A's magical moment + Persona B's evaluation evidence) + +Lands in `## [v2.0.0.0]` entry of CHANGELOG.md, immediately under the headline. Compare measured v1.44 actuals (baseline captured by `test/helpers/capture-parity-baseline.ts` BEFORE Phase A starts) vs v2.0.0.0 measured. Numbers must be REAL, not estimated; replace placeholders during T15. + +| Metric | v1.44.1 (baseline) | v2.0.0.0 (measured) | Δ | +|---|---|---|---| +| Total SKILL.md corpus | 2.1 MB | ~700 KB | **−67%** | +| ship.md (heaviest) | 164 KB | ~15 KB skeleton + 5×~5 KB sections | **−76% first-Read** | +| plan-ceo-review.md | 131 KB | ~12 KB skeleton + sections on demand | **−68% first-Read** | +| office-hours.md | 111 KB | ~10 KB skeleton + sections on demand | **−71% first-Read** | +| Catalog tokens (always-loaded system prompt) | ~25K tokens | ~6K tokens | **−76%** | +| Per-invocation tokens (typical /ship session) | ~41K | ~14K skeleton + on-demand sections | **~60% drop** | +| Eval coverage (skills with E2E protection) | ~16 of 31 | **31 of 31 + parity baselines** | quality gate enabled | +| Parity score vs v1.44 baseline (LLM judge, all 31 skills) | — | **≥9.0/10 floor** | (CI-enforced; see parity-eval suite) | + +Below the table, one paragraph in gstack voice: "v1 was the heaviest opinionated skill pack. v2 is the lightest. The compression isn't free — every skill ships with both gate-tier and periodic-tier E2E evals, and a continuous parity-monitor catches silent quality regressions. The numbers above are measured against `test/helpers/parity-baseline-v1.44.1/` and reproduced by `bun run eval:parity`." + +### README v2 banner + +Placement: top of README.md, immediately under the existing Karpathy pull-quote, above "When I heard Karpathy say this..." Stays in place for 60 days post-launch, then collapses to a one-line "v2 released May 2026" entry in the Quick start section. + +```markdown +> **gstack v2.0.0.0 — the lightest opinionated skill pack (May 2026)** +> +> Heavyweight skills now load only the sections they need. Total SKILL.md +> corpus dropped from 2.1 MB to ~700 KB. Every skill ships with E2E eval +> protection and a continuous parity-monitor against v1.44 baselines. +> See the [v2.0.0.0 release notes](CHANGELOG.md) for per-skill numbers and +> the migration story. Existing users: `/gstack-upgrade` auto-regenerates. +``` + +Voice rules honored: lead with the position ("lightest opinionated skill pack"); concrete numbers (2.1 MB → 700 KB); proof of rigor (eval protection + parity monitor); migration path explicit. No em dashes. Aimed at a 10-second read. + +### Implementation notes (for T15) + +- Lock the actual v1.44 baseline numbers into `test/helpers/parity-baseline-v1.44.1/` BEFORE Phase A regeneration starts. The "v1 vs v2" delta only quotes accurately if v1.44 was measured in the same units (token count via `tiktoken`, byte count via `wc -c`, eval coverage via `test/skill-coverage-matrix.ts`). +- If the measured v2 numbers come in LESS impressive than the drafts above (e.g., ship.md ends up at 25 KB instead of 15 KB), update the drafts to reflect reality. Never invent numbers; the marketing-grade ship moment dies the moment readers find a number they can disprove with `wc -c`. +- The JUST_UPGRADED notice fires automatically via existing `gstack-upgrade` detection — no new mechanism required. +- The README banner placement above the existing Karpathy quote is intentional: persona B (new evaluator) sees the v2 win BEFORE the Karpathy framing, anchoring "this is May 2026's most-current gstack." + +## GSTACK REVIEW REPORT + +| Review | Trigger | Why | Runs | Status | Findings | +|---|---|---|---|---|---| +| CEO Review | `/plan-ceo-review` | Scope & strategy | 1 | CLEAR | SCOPE_EXPANSION mode; 3 expansion proposals (1 accepted: v2 launch positioning; 2 deferred: gstack lite, gstack budget); 11/11 sections reviewed; 0 critical gaps | +| Codex Review | `/codex review` | Independent 2nd opinion (outside voice) | 1 | issues_found | 12 challenges surfaced; 7 absorbed into plan (#4, #5, #6, #9, #10, #11, #12); 3 surfaced as user-decision (#1 user kept original pick, #7 hybrid split adopted, #8 user accepted codex) | +| Eng Review | `/plan-eng-review` | Architecture & tests (required) | 1 | CLEAR | 3 architectural decisions locked (D1 JSON manifest, D2 sections/*.md.tmpl pipeline, D3 CI cost cap); 4 new failure modes added (all rescued+tested); test plan artifact written; parallelization map produced (3 lanes parallel in v1.45, sequential in v2.0); 0 critical gaps; 0 unresolved decisions | +| Codex Consult (2nd pass) | `/codex` (consult on eng-review additions) | Independent challenge of D1/D2/D3 + parallelization | 1 | issues_found | 7 additional findings on eng-review additions; 5 absorbed (TemplateContext contract, 3-tier orphan classification, budget cap override path, manifest as passive data not predicates, T7 as integration-flow obviated by sequential); 2 surfaced as user-decision (attention-architecture risk → cathedral parity-eval suite added at "11"; parallelization collapsed to sequential v1.45 per codex critique) | +| Design Review | `/plan-design-review` | UI/UX gaps | 0 | — | not required (no significant UI scope; README/CHANGELOG only) | +| DX Review | `/plan-devex-review` | Developer experience gaps | 1 | CLEAR | DX POLISH mode; product type = Claude Code Skill; 2 personas tracked equally (existing-user upgrader + new-user evaluator); initial 7.9/10 → 9.0/10 after launch-copy specs added to plan (JUST_UPGRADED notice, CHANGELOG numbers table, README v2 banner all drafted as T15 deliverables); all 8 passes evaluated; skill DX checklist passes | + +**CODEX:** First pass (CEO): 12 findings, 7 absorbed, 3 cross-model user-decided, 2 baked into tasks. Second pass (post eng-review): 7 findings on the new D1/D2/D3 additions, 5 absorbed, 2 user-decided. Both passes preserved as audit trail. 19 total codex findings → 12 absorbed without friction, 5 user-decided across both passes, 2 quality-of-life refinements baked into tasks. DX review skipped fresh codex pass (3 prior passes already covered structural blind spots; remaining DX work is copy-craft, where codex adds less value than user taste). + +**CROSS-MODEL:** Strong agreement on (a) phasing (catalog trim early, sections/ later), (b) measurement-first (hard token budgets + override audit trail), (c) forks/rollout-strategy gaps. Tensions resolved across all passes: eval-first scope (user kept), v2 vs v1.x (HYBRID adopted), migration heaviness (lighter touch adopted), parallelization (user accepted codex's sequential critique), attention-architecture risk (user expanded scope to cathedral parity-eval suite covering ALL 31 skills with quality budget alongside token budget), launch copy artifacts (user drafted all three in plan vs deferring to T15 implementation). + +**UNRESOLVED:** 0 decisions outstanding across all 5 reviews. + +**VERDICT:** CEO + ENG + CODEX×2 + DX CLEARED — ready to implement. The hybrid v1.45/v2.0 split de-risks the bloat-reputation fix; the sections/*.md.tmpl pipeline (D2) prevents drift; the CI cost cap with override audit (D3 + codex absorbed refinement) prevents runaway eval spend; the cathedral parity-eval suite (codex 2nd pass) catches silent attention-architecture regressions that section-loading + budget tests alone would miss; sequential v1.45 execution (codex absorbed) trades wall-clock for integration safety; v2 launch copy specs (DX review) make the marketing-grade ship moment land for both persona A (existing upgrader) and persona B (new evaluator). Plan is now executable. diff --git a/document-generate/SKILL.md b/document-generate/SKILL.md index d48bf8b5d..cb89b4ee5 100644 --- a/document-generate/SKILL.md +++ b/document-generate/SKILL.md @@ -2,13 +2,7 @@ name: document-generate preamble-tier: 2 version: 1.0.0 -description: | - Generate missing documentation from scratch for a feature, module, or entire project. - Uses the Diataxis framework (tutorial / how-to / reference / explanation) to produce - complete, structured documentation. Can be invoked standalone or called by - /document-release when it finds coverage gaps. Use when asked to "write docs", - "generate documentation", "document this feature", "create a tutorial", or - "explain this module". (gstack) +description: Generate missing documentation from scratch for a feature, module, or entire project. (gstack) allowed-tools: - Bash - Read @@ -29,6 +23,15 @@ triggers: + +## When to invoke this skill + +Uses the Diataxis framework (tutorial / how-to / reference / explanation) to produce +complete, structured documentation. Can be invoked standalone or called by +/document-release when it finds coverage gaps. Use when asked to "write docs", +"generate documentation", "document this feature", "create a tutorial", or +"explain this module". + ## Preamble (run first) ```bash @@ -106,6 +109,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -237,6 +253,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` @@ -587,84 +604,7 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i - User-turn override wins: if the current message asks for terse / no explanations / just the answer, skip this section. - Terse mode (EXPLAIN_LEVEL: terse): no glosses, no outcome-framing layer, shorter responses. -Jargon list, gloss on first use if the term appears: -- idempotent -- idempotency -- race condition -- deadlock -- cyclomatic complexity -- N+1 -- N+1 query -- backpressure -- memoization -- eventual consistency -- CAP theorem -- CORS -- CSRF -- XSS -- SQL injection -- prompt injection -- DDoS -- rate limit -- throttle -- circuit breaker -- load balancer -- reverse proxy -- SSR -- CSR -- hydration -- tree-shaking -- bundle splitting -- code splitting -- hot reload -- tombstone -- soft delete -- cascade delete -- foreign key -- composite index -- covering index -- OLTP -- OLAP -- sharding -- replication lag -- quorum -- two-phase commit -- saga -- outbox pattern -- inbox pattern -- optimistic locking -- pessimistic locking -- thundering herd -- cache stampede -- bloom filter -- consistent hashing -- virtual DOM -- reconciliation -- closure -- hoisting -- tail call -- GIL -- zero-copy -- mmap -- cold start -- warm start -- green-blue deploy -- canary deploy -- feature flag -- kill switch -- dead letter queue -- fan-out -- fan-in -- debounce -- throttle (UI) -- hydration mismatch -- memory leak -- GC pause -- heap fragmentation -- stack overflow -- null pointer -- dangling pointer -- buffer overflow +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 Lake diff --git a/document-release/SKILL.md b/document-release/SKILL.md index b4c5caa65..3fc606e8a 100644 --- a/document-release/SKILL.md +++ b/document-release/SKILL.md @@ -2,14 +2,7 @@ name: document-release preamble-tier: 2 version: 1.0.0 -description: | - Post-ship documentation update. Reads all project docs, cross-references the - diff, builds a Diataxis coverage map (reference/how-to/tutorial/explanation), - updates README/ARCHITECTURE/CONTRIBUTING/CLAUDE.md to match what shipped, - detects architecture diagram drift, polishes CHANGELOG voice with a sell-test - rubric, cleans up TODOS, and optionally bumps VERSION. Surfaces documentation - debt in the PR body. Use when asked to "update the docs", "sync documentation", - or "post-ship docs". Proactively suggest after a PR is merged or code is shipped. (gstack) +description: Post-ship documentation update. (gstack) allowed-tools: - Bash - Read @@ -26,6 +19,17 @@ triggers: + +## When to invoke this skill + +Reads all project docs, cross-references the +diff, builds a Diataxis coverage map (reference/how-to/tutorial/explanation), +updates README/ARCHITECTURE/CONTRIBUTING/CLAUDE.md to match what shipped, +detects architecture diagram drift, polishes CHANGELOG voice with a sell-test +rubric, cleans up TODOS, and optionally bumps VERSION. Surfaces documentation +debt in the PR body. Use when asked to "update the docs", "sync documentation", +or "post-ship docs". Proactively suggest after a PR is merged or code is shipped. + ## Preamble (run first) ```bash @@ -103,6 +107,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -234,6 +251,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` @@ -584,84 +602,7 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i - User-turn override wins: if the current message asks for terse / no explanations / just the answer, skip this section. - Terse mode (EXPLAIN_LEVEL: terse): no glosses, no outcome-framing layer, shorter responses. -Jargon list, gloss on first use if the term appears: -- idempotent -- idempotency -- race condition -- deadlock -- cyclomatic complexity -- N+1 -- N+1 query -- backpressure -- memoization -- eventual consistency -- CAP theorem -- CORS -- CSRF -- XSS -- SQL injection -- prompt injection -- DDoS -- rate limit -- throttle -- circuit breaker -- load balancer -- reverse proxy -- SSR -- CSR -- hydration -- tree-shaking -- bundle splitting -- code splitting -- hot reload -- tombstone -- soft delete -- cascade delete -- foreign key -- composite index -- covering index -- OLTP -- OLAP -- sharding -- replication lag -- quorum -- two-phase commit -- saga -- outbox pattern -- inbox pattern -- optimistic locking -- pessimistic locking -- thundering herd -- cache stampede -- bloom filter -- consistent hashing -- virtual DOM -- reconciliation -- closure -- hoisting -- tail call -- GIL -- zero-copy -- mmap -- cold start -- warm start -- green-blue deploy -- canary deploy -- feature flag -- kill switch -- dead letter queue -- fan-out -- fan-in -- debounce -- throttle (UI) -- hydration mismatch -- memory leak -- GC pause -- heap fragmentation -- stack overflow -- null pointer -- dangling pointer -- buffer overflow +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 Lake diff --git a/freeze/SKILL.md b/freeze/SKILL.md index 87f8506ca..fc82b1bea 100644 --- a/freeze/SKILL.md +++ b/freeze/SKILL.md @@ -1,12 +1,7 @@ --- name: freeze version: 0.1.0 -description: | - Restrict file edits to a specific directory for the session. Blocks Edit and - Write outside the allowed path. Use when debugging to prevent accidentally - "fixing" unrelated code, or when you want to scope changes to one module. - Use when asked to "freeze", "restrict edits", "only edit this folder", - or "lock down edits". (gstack) +description: Restrict file edits to a specific directory for the session. (gstack) triggers: - freeze edits to directory - lock editing scope @@ -31,6 +26,15 @@ hooks: + +## When to invoke this skill + +Blocks Edit and +Write outside the allowed path. Use when debugging to prevent accidentally +"fixing" unrelated code, or when you want to scope changes to one module. +Use when asked to "freeze", "restrict edits", "only edit this folder", +or "lock down edits". + # /freeze — Restrict Edits to a Directory Lock file edits to a specific directory. Any Edit or Write operation targeting diff --git a/gstack-upgrade/SKILL.md b/gstack-upgrade/SKILL.md index 81bb1228c..9f0f2f7ea 100644 --- a/gstack-upgrade/SKILL.md +++ b/gstack-upgrade/SKILL.md @@ -1,11 +1,7 @@ --- name: gstack-upgrade version: 1.1.0 -description: | - Upgrade gstack to the latest version. Detects global vs vendored install, - runs the upgrade, and shows what's new. Use when asked to "upgrade gstack", - "update gstack", or "get latest version". - Voice triggers (speech-to-text aliases): "upgrade the tools", "update the tools", "gee stack upgrade", "g stack upgrade". +description: Upgrade gstack to the latest version. triggers: - upgrade gstack - update gstack version @@ -19,6 +15,15 @@ allowed-tools: + +## When to invoke this skill + +Detects global vs vendored install, +runs the upgrade, and shows what's new. Use when asked to "upgrade gstack", +"update gstack", or "get latest version". + +Voice triggers (speech-to-text aliases): "upgrade the tools", "update the tools", "gee stack upgrade", "g stack upgrade". + # /gstack-upgrade Upgrade gstack to the latest version and show what's new. diff --git a/gstack/llms.txt b/gstack/llms.txt index bb9b816b9..3ac54bcd8 100644 --- a/gstack/llms.txt +++ b/gstack/llms.txt @@ -61,6 +61,7 @@ Conventions: - [/setup-gbrain](setup-gbrain/SKILL.md): Set up gbrain for this coding agent: install the CLI, initialize a local PGLite or Supabase brain, register MCP, capture per-remote trust policy. - [/ship](ship/SKILL.md): Ship workflow: detect + merge base branch, run tests, review diff, bump VERSION, update CHANGELOG, commit, push, create PR. - [/skillify](skillify/SKILL.md): Codify the most recent successful /scrape flow into a permanent browser-skill on disk. +- [/spec](spec/SKILL.md): Turn vague intent into a precise, executable spec in five phases. - [/sync-gbrain](sync-gbrain/SKILL.md): Keep gbrain current with this repo's code and refresh agent search guidance in CLAUDE.md. - [/unfreeze](unfreeze/SKILL.md): Clear the freeze boundary set by /freeze, allowing edits to all directories again. diff --git a/guard/SKILL.md b/guard/SKILL.md index 36216ac16..8d4a57448 100644 --- a/guard/SKILL.md +++ b/guard/SKILL.md @@ -1,12 +1,7 @@ --- name: guard version: 0.1.0 -description: | - Full safety mode: destructive command warnings + directory-scoped edits. - Combines /careful (warns before rm -rf, DROP TABLE, force-push, etc.) with - /freeze (blocks edits outside a specified directory). Use for maximum safety - when touching prod or debugging live systems. Use when asked to "guard mode", - "full safety", "lock it down", or "maximum safety". (gstack) +description: Full safety mode: destructive command warnings + directory-scoped edits. (gstack) triggers: - full safety mode - guard against mistakes @@ -36,6 +31,14 @@ hooks: + +## When to invoke this skill + +Combines /careful (warns before rm -rf, DROP TABLE, force-push, etc.) with +/freeze (blocks edits outside a specified directory). Use for maximum safety +when touching prod or debugging live systems. Use when asked to "guard mode", +"full safety", "lock it down", or "maximum safety". + # /guard — Full Safety Mode Activates both destructive command warnings and directory-scoped edit restrictions. diff --git a/health/SKILL.md b/health/SKILL.md index 70ffb4b53..ef63acaf6 100644 --- a/health/SKILL.md +++ b/health/SKILL.md @@ -2,12 +2,7 @@ name: health preamble-tier: 2 version: 1.0.0 -description: | - Code quality dashboard. Wraps existing project tools (type checker, linter, - test runner, dead code detector, shell linter), computes a weighted composite - 0-10 score, and tracks trends over time. Use when: "health check", - "code quality", "how healthy is the codebase", "run all checks", - "quality score". (gstack) +description: Code quality dashboard. (gstack) triggers: - code health check - quality dashboard @@ -24,6 +19,15 @@ allowed-tools: + +## When to invoke this skill + +Wraps existing project tools (type checker, linter, +test runner, dead code detector, shell linter), computes a weighted composite +0-10 score, and tracks trends over time. Use when: "health check", +"code quality", "how healthy is the codebase", "run all checks", +"quality score". + ## Preamble (run first) ```bash @@ -101,6 +105,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -232,6 +249,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` @@ -582,84 +600,7 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i - User-turn override wins: if the current message asks for terse / no explanations / just the answer, skip this section. - Terse mode (EXPLAIN_LEVEL: terse): no glosses, no outcome-framing layer, shorter responses. -Jargon list, gloss on first use if the term appears: -- idempotent -- idempotency -- race condition -- deadlock -- cyclomatic complexity -- N+1 -- N+1 query -- backpressure -- memoization -- eventual consistency -- CAP theorem -- CORS -- CSRF -- XSS -- SQL injection -- prompt injection -- DDoS -- rate limit -- throttle -- circuit breaker -- load balancer -- reverse proxy -- SSR -- CSR -- hydration -- tree-shaking -- bundle splitting -- code splitting -- hot reload -- tombstone -- soft delete -- cascade delete -- foreign key -- composite index -- covering index -- OLTP -- OLAP -- sharding -- replication lag -- quorum -- two-phase commit -- saga -- outbox pattern -- inbox pattern -- optimistic locking -- pessimistic locking -- thundering herd -- cache stampede -- bloom filter -- consistent hashing -- virtual DOM -- reconciliation -- closure -- hoisting -- tail call -- GIL -- zero-copy -- mmap -- cold start -- warm start -- green-blue deploy -- canary deploy -- feature flag -- kill switch -- dead letter queue -- fan-out -- fan-in -- debounce -- throttle (UI) -- hydration mismatch -- memory leak -- GC pause -- heap fragmentation -- stack overflow -- null pointer -- dangling pointer -- buffer overflow +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 Lake diff --git a/investigate/SKILL.md b/investigate/SKILL.md index 71dd355ec..f1d12dd1e 100644 --- a/investigate/SKILL.md +++ b/investigate/SKILL.md @@ -2,14 +2,7 @@ name: investigate preamble-tier: 2 version: 1.0.0 -description: | - Systematic debugging with root cause investigation. Four phases: investigate, - analyze, hypothesize, implement. Iron Law: no fixes without root cause. - Use when asked to "debug this", "fix this bug", "why is this broken", - "investigate this error", or "root cause analysis". - Proactively invoke this skill (do NOT debug directly) when the user reports - errors, 500 errors, stack traces, unexpected behavior, "it was working - yesterday", or is troubleshooting why something stopped working. (gstack) +description: Systematic debugging with root cause investigation. (gstack) allowed-tools: - Bash - Read @@ -63,6 +56,17 @@ gbrain: + +## When to invoke this skill + +Four phases: investigate, +analyze, hypothesize, implement. Iron Law: no fixes without root cause. +Use when asked to "debug this", "fix this bug", "why is this broken", +"investigate this error", or "root cause analysis". +Proactively invoke this skill (do NOT debug directly) when the user reports +errors, 500 errors, stack traces, unexpected behavior, "it was working +yesterday", or is troubleshooting why something stopped working. + ## Preamble (run first) ```bash @@ -140,6 +144,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -271,6 +288,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` @@ -621,84 +639,7 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i - User-turn override wins: if the current message asks for terse / no explanations / just the answer, skip this section. - Terse mode (EXPLAIN_LEVEL: terse): no glosses, no outcome-framing layer, shorter responses. -Jargon list, gloss on first use if the term appears: -- idempotent -- idempotency -- race condition -- deadlock -- cyclomatic complexity -- N+1 -- N+1 query -- backpressure -- memoization -- eventual consistency -- CAP theorem -- CORS -- CSRF -- XSS -- SQL injection -- prompt injection -- DDoS -- rate limit -- throttle -- circuit breaker -- load balancer -- reverse proxy -- SSR -- CSR -- hydration -- tree-shaking -- bundle splitting -- code splitting -- hot reload -- tombstone -- soft delete -- cascade delete -- foreign key -- composite index -- covering index -- OLTP -- OLAP -- sharding -- replication lag -- quorum -- two-phase commit -- saga -- outbox pattern -- inbox pattern -- optimistic locking -- pessimistic locking -- thundering herd -- cache stampede -- bloom filter -- consistent hashing -- virtual DOM -- reconciliation -- closure -- hoisting -- tail call -- GIL -- zero-copy -- mmap -- cold start -- warm start -- green-blue deploy -- canary deploy -- feature flag -- kill switch -- dead letter queue -- fan-out -- fan-in -- debounce -- throttle (UI) -- hydration mismatch -- memory leak -- GC pause -- heap fragmentation -- stack overflow -- null pointer -- dangling pointer -- buffer overflow +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 Lake diff --git a/ios-clean/SKILL.md b/ios-clean/SKILL.md index 4a89e0a3e..f925bc948 100644 --- a/ios-clean/SKILL.md +++ b/ios-clean/SKILL.md @@ -2,15 +2,7 @@ name: ios-clean preamble-tier: 3 version: 1.0.0 -description: | - Remove the DebugBridge SPM package and all #if DEBUG wiring from an iOS - app. Cleans up StateServer, DebugOverlay, accessor codegen output, and - app-side hooks installed by /ios-qa. This is a convenience wrapper — - the structural Release-build guard (Package.swift conditional + CI - swift build -c release check) is the safety-critical path. - Use when asked to "clean the iOS debug bridge", "remove DebugBridge", - or "strip the gstack iOS instrumentation". (gstack) - Voice triggers (speech-to-text aliases): "clean the iOS debug bridge", "remove DebugBridge", "strip the gstack iOS instrumentation". +description: Remove the DebugBridge SPM package and all #if DEBUG wiring from an iOS app. (gstack) allowed-tools: - Bash - Read @@ -26,6 +18,18 @@ triggers: + +## When to invoke this skill + +Cleans up StateServer, DebugOverlay, accessor codegen output, and +app-side hooks installed by /ios-qa. This is a convenience wrapper — +the structural Release-build guard (Package.swift conditional + CI +swift build -c release check) is the safety-critical path. +Use when asked to "clean the iOS debug bridge", "remove DebugBridge", +or "strip the gstack iOS instrumentation". + +Voice triggers (speech-to-text aliases): "clean the iOS debug bridge", "remove DebugBridge", "strip the gstack iOS instrumentation". + ## Preamble (run first) ```bash @@ -103,6 +107,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -234,6 +251,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` @@ -584,84 +602,7 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i - User-turn override wins: if the current message asks for terse / no explanations / just the answer, skip this section. - Terse mode (EXPLAIN_LEVEL: terse): no glosses, no outcome-framing layer, shorter responses. -Jargon list, gloss on first use if the term appears: -- idempotent -- idempotency -- race condition -- deadlock -- cyclomatic complexity -- N+1 -- N+1 query -- backpressure -- memoization -- eventual consistency -- CAP theorem -- CORS -- CSRF -- XSS -- SQL injection -- prompt injection -- DDoS -- rate limit -- throttle -- circuit breaker -- load balancer -- reverse proxy -- SSR -- CSR -- hydration -- tree-shaking -- bundle splitting -- code splitting -- hot reload -- tombstone -- soft delete -- cascade delete -- foreign key -- composite index -- covering index -- OLTP -- OLAP -- sharding -- replication lag -- quorum -- two-phase commit -- saga -- outbox pattern -- inbox pattern -- optimistic locking -- pessimistic locking -- thundering herd -- cache stampede -- bloom filter -- consistent hashing -- virtual DOM -- reconciliation -- closure -- hoisting -- tail call -- GIL -- zero-copy -- mmap -- cold start -- warm start -- green-blue deploy -- canary deploy -- feature flag -- kill switch -- dead letter queue -- fan-out -- fan-in -- debounce -- throttle (UI) -- hydration mismatch -- memory leak -- GC pause -- heap fragmentation -- stack overflow -- null pointer -- dangling pointer -- buffer overflow +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 Lake diff --git a/ios-design-review/SKILL.md b/ios-design-review/SKILL.md index d6a8135ff..76f9629f9 100644 --- a/ios-design-review/SKILL.md +++ b/ios-design-review/SKILL.md @@ -2,17 +2,7 @@ name: ios-design-review preamble-tier: 3 version: 1.0.0 -description: | - Visual design audit for iOS apps on real hardware. Connects to a real - iPhone via the same StateServer as /ios-qa, screenshots every screen, - evaluates against Apple HIG, DESIGN.md, and design best practices. Scores - each dimension 0-10 with "what would make it a 10" framing — mirrors - /plan-design-review for browser. For plan-stage design review (before - implementation), use /plan-design-review. For live web visual audits, use - /design-review. - Use when asked to "review the iOS design", "audit the iPhone app's - visuals", or "design QA the iOS app". (gstack) - Voice triggers (speech-to-text aliases): "review the iOS design", "audit the iPhone app's visuals", "design QA the iPhone app". +description: Visual design audit for iOS apps on real hardware. (gstack) allowed-tools: - Bash - Read @@ -27,6 +17,21 @@ triggers: + +## When to invoke this skill + +Connects to a real +iPhone via the same StateServer as /ios-qa, screenshots every screen, +evaluates against Apple HIG, DESIGN.md, and design best practices. Scores +each dimension 0-10 with "what would make it a 10" framing — mirrors +/plan-design-review for browser. For plan-stage design review (before +implementation), use /plan-design-review. For live web visual audits, use +/design-review. +Use when asked to "review the iOS design", "audit the iPhone app's +visuals", or "design QA the iOS app". + +Voice triggers (speech-to-text aliases): "review the iOS design", "audit the iPhone app's visuals", "design QA the iPhone app". + ## Preamble (run first) ```bash @@ -104,6 +109,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -235,6 +253,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` @@ -585,84 +604,7 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i - User-turn override wins: if the current message asks for terse / no explanations / just the answer, skip this section. - Terse mode (EXPLAIN_LEVEL: terse): no glosses, no outcome-framing layer, shorter responses. -Jargon list, gloss on first use if the term appears: -- idempotent -- idempotency -- race condition -- deadlock -- cyclomatic complexity -- N+1 -- N+1 query -- backpressure -- memoization -- eventual consistency -- CAP theorem -- CORS -- CSRF -- XSS -- SQL injection -- prompt injection -- DDoS -- rate limit -- throttle -- circuit breaker -- load balancer -- reverse proxy -- SSR -- CSR -- hydration -- tree-shaking -- bundle splitting -- code splitting -- hot reload -- tombstone -- soft delete -- cascade delete -- foreign key -- composite index -- covering index -- OLTP -- OLAP -- sharding -- replication lag -- quorum -- two-phase commit -- saga -- outbox pattern -- inbox pattern -- optimistic locking -- pessimistic locking -- thundering herd -- cache stampede -- bloom filter -- consistent hashing -- virtual DOM -- reconciliation -- closure -- hoisting -- tail call -- GIL -- zero-copy -- mmap -- cold start -- warm start -- green-blue deploy -- canary deploy -- feature flag -- kill switch -- dead letter queue -- fan-out -- fan-in -- debounce -- throttle (UI) -- hydration mismatch -- memory leak -- GC pause -- heap fragmentation -- stack overflow -- null pointer -- dangling pointer -- buffer overflow +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 Lake diff --git a/ios-fix/SKILL.md b/ios-fix/SKILL.md index 0f2da0548..11d7a3f1b 100644 --- a/ios-fix/SKILL.md +++ b/ios-fix/SKILL.md @@ -2,16 +2,7 @@ name: ios-fix preamble-tier: 3 version: 1.0.0 -description: | - Autonomous iOS bug fixer. Takes a bug found by /ios-qa, reads the source, - writes the fix, rebuilds, redeploys, and verifies the fix on the real - device. Closes the loop: find bug → fix bug → confirm fix — zero human - intervention. Captures the pre-bug state snapshot as a regression test - fixture, so the bug can never recur silently. - Use when /ios-qa reports a bug and you want it fixed automatically, or - when asked to "fix this iOS bug", "patch the iPhone app", or "auto-fix - the iOS issue". (gstack) - Voice triggers (speech-to-text aliases): "fix the iOS bug", "patch the iPhone app", "auto-fix the iOS issue". +description: Autonomous iOS bug fixer. (gstack) allowed-tools: - Bash - Read @@ -28,6 +19,20 @@ triggers: + +## When to invoke this skill + +Takes a bug found by /ios-qa, reads the source, +writes the fix, rebuilds, redeploys, and verifies the fix on the real +device. Closes the loop: find bug → fix bug → confirm fix — zero human +intervention. Captures the pre-bug state snapshot as a regression test +fixture, so the bug can never recur silently. +Use when /ios-qa reports a bug and you want it fixed automatically, or +when asked to "fix this iOS bug", "patch the iPhone app", or "auto-fix +the iOS issue". + +Voice triggers (speech-to-text aliases): "fix the iOS bug", "patch the iPhone app", "auto-fix the iOS issue". + ## Preamble (run first) ```bash @@ -105,6 +110,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -236,6 +254,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` @@ -586,84 +605,7 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i - User-turn override wins: if the current message asks for terse / no explanations / just the answer, skip this section. - Terse mode (EXPLAIN_LEVEL: terse): no glosses, no outcome-framing layer, shorter responses. -Jargon list, gloss on first use if the term appears: -- idempotent -- idempotency -- race condition -- deadlock -- cyclomatic complexity -- N+1 -- N+1 query -- backpressure -- memoization -- eventual consistency -- CAP theorem -- CORS -- CSRF -- XSS -- SQL injection -- prompt injection -- DDoS -- rate limit -- throttle -- circuit breaker -- load balancer -- reverse proxy -- SSR -- CSR -- hydration -- tree-shaking -- bundle splitting -- code splitting -- hot reload -- tombstone -- soft delete -- cascade delete -- foreign key -- composite index -- covering index -- OLTP -- OLAP -- sharding -- replication lag -- quorum -- two-phase commit -- saga -- outbox pattern -- inbox pattern -- optimistic locking -- pessimistic locking -- thundering herd -- cache stampede -- bloom filter -- consistent hashing -- virtual DOM -- reconciliation -- closure -- hoisting -- tail call -- GIL -- zero-copy -- mmap -- cold start -- warm start -- green-blue deploy -- canary deploy -- feature flag -- kill switch -- dead letter queue -- fan-out -- fan-in -- debounce -- throttle (UI) -- hydration mismatch -- memory leak -- GC pause -- heap fragmentation -- stack overflow -- null pointer -- dangling pointer -- buffer overflow +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 Lake diff --git a/ios-qa/SKILL.md b/ios-qa/SKILL.md index 1f03d1623..1080896c5 100644 --- a/ios-qa/SKILL.md +++ b/ios-qa/SKILL.md @@ -2,17 +2,7 @@ name: ios-qa preamble-tier: 3 version: 1.0.0 -description: | - Live-device iOS QA for SwiftUI apps. Connects to a real iPhone via USB - CoreDevice IPv6 tunnel, reads Swift source to understand every screen, then - runs a vision-driven agent loop: screenshot → analyze → decide → act → - verify → repeat. All interaction happens via HTTP to an embedded - StateServer in the app under test. Optionally exposes the device over - Tailscale so remote agents (OpenClaw, Codex, any HTTP-capable agent) can - run iOS QA from anywhere without touching the hardware. - Use when asked to "ios qa", "test my iPhone app", "find bugs on the device", - or "qa the iOS app". (gstack) - Voice triggers (speech-to-text aliases): "iOS quality check", "test the iPhone app", "run iOS QA". +description: Live-device iOS QA for SwiftUI apps. (gstack) allowed-tools: - Bash - Read @@ -31,6 +21,21 @@ triggers: + +## When to invoke this skill + +Connects to a real iPhone via USB +CoreDevice IPv6 tunnel, reads Swift source to understand every screen, then +runs a vision-driven agent loop: screenshot → analyze → decide → act → +verify → repeat. All interaction happens via HTTP to an embedded +StateServer in the app under test. Optionally exposes the device over +Tailscale so remote agents (OpenClaw, Codex, any HTTP-capable agent) can +run iOS QA from anywhere without touching the hardware. +Use when asked to "ios qa", "test my iPhone app", "find bugs on the device", +or "qa the iOS app". + +Voice triggers (speech-to-text aliases): "iOS quality check", "test the iPhone app", "run iOS QA". + ## Preamble (run first) ```bash @@ -108,6 +113,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -239,6 +257,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` @@ -589,84 +608,7 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i - User-turn override wins: if the current message asks for terse / no explanations / just the answer, skip this section. - Terse mode (EXPLAIN_LEVEL: terse): no glosses, no outcome-framing layer, shorter responses. -Jargon list, gloss on first use if the term appears: -- idempotent -- idempotency -- race condition -- deadlock -- cyclomatic complexity -- N+1 -- N+1 query -- backpressure -- memoization -- eventual consistency -- CAP theorem -- CORS -- CSRF -- XSS -- SQL injection -- prompt injection -- DDoS -- rate limit -- throttle -- circuit breaker -- load balancer -- reverse proxy -- SSR -- CSR -- hydration -- tree-shaking -- bundle splitting -- code splitting -- hot reload -- tombstone -- soft delete -- cascade delete -- foreign key -- composite index -- covering index -- OLTP -- OLAP -- sharding -- replication lag -- quorum -- two-phase commit -- saga -- outbox pattern -- inbox pattern -- optimistic locking -- pessimistic locking -- thundering herd -- cache stampede -- bloom filter -- consistent hashing -- virtual DOM -- reconciliation -- closure -- hoisting -- tail call -- GIL -- zero-copy -- mmap -- cold start -- warm start -- green-blue deploy -- canary deploy -- feature flag -- kill switch -- dead letter queue -- fan-out -- fan-in -- debounce -- throttle (UI) -- hydration mismatch -- memory leak -- GC pause -- heap fragmentation -- stack overflow -- null pointer -- dangling pointer -- buffer overflow +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 Lake diff --git a/ios-sync/SKILL.md b/ios-sync/SKILL.md index 69d03a30b..2e0f703af 100644 --- a/ios-sync/SKILL.md +++ b/ios-sync/SKILL.md @@ -2,14 +2,7 @@ name: ios-sync preamble-tier: 3 version: 1.0.0 -description: | - Regenerate the iOS debug bridge against the latest upstream gstack - templates. Updates StateServer.swift, DebugOverlay.swift, Package.swift, - and the typed @Observable state accessors. Use after you upgrade gstack - or add new ViewModels/properties that need accessor coverage. - Use when asked to "resync the iOS debug bridge", "regenerate iOS - accessors", or "update the gstack iOS instrumentation". (gstack) - Voice triggers (speech-to-text aliases): "resync the iOS debug bridge", "regenerate iOS accessors", "update the gstack iOS instrumentation". +description: Regenerate the iOS debug bridge against the latest upstream gstack templates. (gstack) allowed-tools: - Bash - Read @@ -26,6 +19,17 @@ triggers: + +## When to invoke this skill + +Updates StateServer.swift, DebugOverlay.swift, Package.swift, +and the typed @Observable state accessors. Use after you upgrade gstack +or add new ViewModels/properties that need accessor coverage. +Use when asked to "resync the iOS debug bridge", "regenerate iOS +accessors", or "update the gstack iOS instrumentation". + +Voice triggers (speech-to-text aliases): "resync the iOS debug bridge", "regenerate iOS accessors", "update the gstack iOS instrumentation". + ## Preamble (run first) ```bash @@ -103,6 +107,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -234,6 +251,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` @@ -584,84 +602,7 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i - User-turn override wins: if the current message asks for terse / no explanations / just the answer, skip this section. - Terse mode (EXPLAIN_LEVEL: terse): no glosses, no outcome-framing layer, shorter responses. -Jargon list, gloss on first use if the term appears: -- idempotent -- idempotency -- race condition -- deadlock -- cyclomatic complexity -- N+1 -- N+1 query -- backpressure -- memoization -- eventual consistency -- CAP theorem -- CORS -- CSRF -- XSS -- SQL injection -- prompt injection -- DDoS -- rate limit -- throttle -- circuit breaker -- load balancer -- reverse proxy -- SSR -- CSR -- hydration -- tree-shaking -- bundle splitting -- code splitting -- hot reload -- tombstone -- soft delete -- cascade delete -- foreign key -- composite index -- covering index -- OLTP -- OLAP -- sharding -- replication lag -- quorum -- two-phase commit -- saga -- outbox pattern -- inbox pattern -- optimistic locking -- pessimistic locking -- thundering herd -- cache stampede -- bloom filter -- consistent hashing -- virtual DOM -- reconciliation -- closure -- hoisting -- tail call -- GIL -- zero-copy -- mmap -- cold start -- warm start -- green-blue deploy -- canary deploy -- feature flag -- kill switch -- dead letter queue -- fan-out -- fan-in -- debounce -- throttle (UI) -- hydration mismatch -- memory leak -- GC pause -- heap fragmentation -- stack overflow -- null pointer -- dangling pointer -- buffer overflow +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 Lake diff --git a/land-and-deploy/SKILL.md b/land-and-deploy/SKILL.md index 588467ebc..8bfec441c 100644 --- a/land-and-deploy/SKILL.md +++ b/land-and-deploy/SKILL.md @@ -2,11 +2,7 @@ name: land-and-deploy preamble-tier: 4 version: 1.0.0 -description: | - Land and deploy workflow. Merges the PR, waits for CI and deploy, - verifies production health via canary checks. Takes over after /ship - creates the PR. Use when: "merge", "land", "deploy", "merge and verify", - "land it", "ship it to production". (gstack) +description: Land and deploy workflow. (gstack) allowed-tools: - Bash - Read @@ -21,6 +17,14 @@ triggers: + +## When to invoke this skill + +Merges the PR, waits for CI and deploy, +verifies production health via canary checks. Takes over after /ship +creates the PR. Use when: "merge", "land", "deploy", "merge and verify", +"land it", "ship it to production". + ## Preamble (run first) ```bash @@ -98,6 +102,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -229,6 +246,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` @@ -579,84 +597,7 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i - User-turn override wins: if the current message asks for terse / no explanations / just the answer, skip this section. - Terse mode (EXPLAIN_LEVEL: terse): no glosses, no outcome-framing layer, shorter responses. -Jargon list, gloss on first use if the term appears: -- idempotent -- idempotency -- race condition -- deadlock -- cyclomatic complexity -- N+1 -- N+1 query -- backpressure -- memoization -- eventual consistency -- CAP theorem -- CORS -- CSRF -- XSS -- SQL injection -- prompt injection -- DDoS -- rate limit -- throttle -- circuit breaker -- load balancer -- reverse proxy -- SSR -- CSR -- hydration -- tree-shaking -- bundle splitting -- code splitting -- hot reload -- tombstone -- soft delete -- cascade delete -- foreign key -- composite index -- covering index -- OLTP -- OLAP -- sharding -- replication lag -- quorum -- two-phase commit -- saga -- outbox pattern -- inbox pattern -- optimistic locking -- pessimistic locking -- thundering herd -- cache stampede -- bloom filter -- consistent hashing -- virtual DOM -- reconciliation -- closure -- hoisting -- tail call -- GIL -- zero-copy -- mmap -- cold start -- warm start -- green-blue deploy -- canary deploy -- feature flag -- kill switch -- dead letter queue -- fan-out -- fan-in -- debounce -- throttle (UI) -- hydration mismatch -- memory leak -- GC pause -- heap fragmentation -- stack overflow -- null pointer -- dangling pointer -- buffer overflow +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 Lake diff --git a/landing-report/SKILL.md b/landing-report/SKILL.md index 8ea669181..442c28d7f 100644 --- a/landing-report/SKILL.md +++ b/landing-report/SKILL.md @@ -1,12 +1,7 @@ --- name: landing-report version: 0.1.0 -description: | - Read-only queue dashboard for workspace-aware ship. Shows which VERSION slots - are currently claimed by open PRs, which sibling Conductor workspaces have - WIP work likely to ship soon, and what slot /ship would pick next. No - mutations — just a snapshot. Use when asked to "landing report", "what's in - the queue", "show me open PRs", or "which version do I claim next". (gstack) +description: Read-only queue dashboard for workspace-aware ship. (gstack) triggers: - landing report - version queue @@ -20,6 +15,15 @@ allowed-tools: + +## When to invoke this skill + +Shows which VERSION slots +are currently claimed by open PRs, which sibling Conductor workspaces have +WIP work likely to ship soon, and what slot /ship would pick next. No +mutations — just a snapshot. Use when asked to "landing report", "what's in +the queue", "show me open PRs", or "which version do I claim next". + # /landing-report — Version Queue Dashboard ## Preamble (run first) @@ -99,6 +103,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -230,6 +247,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` @@ -580,84 +598,7 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i - User-turn override wins: if the current message asks for terse / no explanations / just the answer, skip this section. - Terse mode (EXPLAIN_LEVEL: terse): no glosses, no outcome-framing layer, shorter responses. -Jargon list, gloss on first use if the term appears: -- idempotent -- idempotency -- race condition -- deadlock -- cyclomatic complexity -- N+1 -- N+1 query -- backpressure -- memoization -- eventual consistency -- CAP theorem -- CORS -- CSRF -- XSS -- SQL injection -- prompt injection -- DDoS -- rate limit -- throttle -- circuit breaker -- load balancer -- reverse proxy -- SSR -- CSR -- hydration -- tree-shaking -- bundle splitting -- code splitting -- hot reload -- tombstone -- soft delete -- cascade delete -- foreign key -- composite index -- covering index -- OLTP -- OLAP -- sharding -- replication lag -- quorum -- two-phase commit -- saga -- outbox pattern -- inbox pattern -- optimistic locking -- pessimistic locking -- thundering herd -- cache stampede -- bloom filter -- consistent hashing -- virtual DOM -- reconciliation -- closure -- hoisting -- tail call -- GIL -- zero-copy -- mmap -- cold start -- warm start -- green-blue deploy -- canary deploy -- feature flag -- kill switch -- dead letter queue -- fan-out -- fan-in -- debounce -- throttle (UI) -- hydration mismatch -- memory leak -- GC pause -- heap fragmentation -- stack overflow -- null pointer -- dangling pointer -- buffer overflow +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 Lake diff --git a/learn/SKILL.md b/learn/SKILL.md index 8025868e6..3eb54e696 100644 --- a/learn/SKILL.md +++ b/learn/SKILL.md @@ -2,12 +2,7 @@ name: learn preamble-tier: 2 version: 1.0.0 -description: | - Manage project learnings. Review, search, prune, and export what gstack - has learned across sessions. Use when asked to "what have we learned", - "show learnings", "prune stale learnings", or "export learnings". - Proactively suggest when the user asks about past patterns or wonders - "didn't we fix this before?" +description: Manage project learnings. triggers: - show learnings - what have we learned @@ -24,6 +19,15 @@ allowed-tools: + +## When to invoke this skill + +Review, search, prune, and export what gstack +has learned across sessions. Use when asked to "what have we learned", +"show learnings", "prune stale learnings", or "export learnings". +Proactively suggest when the user asks about past patterns or wonders +"didn't we fix this before?" + ## Preamble (run first) ```bash @@ -101,6 +105,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -232,6 +249,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` @@ -582,84 +600,7 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i - User-turn override wins: if the current message asks for terse / no explanations / just the answer, skip this section. - Terse mode (EXPLAIN_LEVEL: terse): no glosses, no outcome-framing layer, shorter responses. -Jargon list, gloss on first use if the term appears: -- idempotent -- idempotency -- race condition -- deadlock -- cyclomatic complexity -- N+1 -- N+1 query -- backpressure -- memoization -- eventual consistency -- CAP theorem -- CORS -- CSRF -- XSS -- SQL injection -- prompt injection -- DDoS -- rate limit -- throttle -- circuit breaker -- load balancer -- reverse proxy -- SSR -- CSR -- hydration -- tree-shaking -- bundle splitting -- code splitting -- hot reload -- tombstone -- soft delete -- cascade delete -- foreign key -- composite index -- covering index -- OLTP -- OLAP -- sharding -- replication lag -- quorum -- two-phase commit -- saga -- outbox pattern -- inbox pattern -- optimistic locking -- pessimistic locking -- thundering herd -- cache stampede -- bloom filter -- consistent hashing -- virtual DOM -- reconciliation -- closure -- hoisting -- tail call -- GIL -- zero-copy -- mmap -- cold start -- warm start -- green-blue deploy -- canary deploy -- feature flag -- kill switch -- dead letter queue -- fan-out -- fan-in -- debounce -- throttle (UI) -- hydration mismatch -- memory leak -- GC pause -- heap fragmentation -- stack overflow -- null pointer -- dangling pointer -- buffer overflow +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 Lake diff --git a/make-pdf/SKILL.md b/make-pdf/SKILL.md index 045e31516..229f082cf 100644 --- a/make-pdf/SKILL.md +++ b/make-pdf/SKILL.md @@ -2,13 +2,7 @@ name: make-pdf preamble-tier: 1 version: 1.0.0 -description: | - Turn any markdown file into a publication-quality PDF. Proper 1in margins, - intelligent page breaks, page numbers, cover pages, running headers, curly - quotes and em dashes, clickable TOC, diagonal DRAFT watermark. Not a draft - artifact — a finished artifact. Use when asked to "make a PDF", "export to - PDF", "turn this markdown into a PDF", or "generate a document". (gstack) - Voice triggers (speech-to-text aliases): "make this a pdf", "make it a pdf", "export to pdf", "turn this into a pdf", "turn this markdown into a pdf", "generate a pdf", "make a pdf from", "pdf this markdown". +description: Turn any markdown file into a publication-quality PDF. (gstack) triggers: - markdown to pdf - generate pdf @@ -22,6 +16,17 @@ allowed-tools: + +## When to invoke this skill + +Proper 1in margins, +intelligent page breaks, page numbers, cover pages, running headers, curly +quotes and em dashes, clickable TOC, diagonal DRAFT watermark. Not a draft +artifact — a finished artifact. Use when asked to "make a PDF", "export to +PDF", "turn this markdown into a PDF", or "generate a document". + +Voice triggers (speech-to-text aliases): "make this a pdf", "make it a pdf", "export to pdf", "turn this into a pdf", "turn this markdown into a pdf", "generate a pdf", "make a pdf from", "pdf this markdown". + ## Preamble (run first) ```bash @@ -99,6 +104,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -266,6 +284,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` diff --git a/office-hours/SKILL.md b/office-hours/SKILL.md index 66a5cb8f1..bfa14d6bd 100644 --- a/office-hours/SKILL.md +++ b/office-hours/SKILL.md @@ -2,18 +2,7 @@ name: office-hours preamble-tier: 3 version: 2.0.0 -description: | - YC Office Hours — two modes. Startup mode: six forcing questions that expose - demand reality, status quo, desperate specificity, narrowest wedge, observation, - and future-fit. Builder mode: design thinking brainstorming for side projects, - hackathons, learning, and open source. Saves a design doc. - Use when asked to "brainstorm this", "I have an idea", "help me think through - this", "office hours", or "is this worth building". - Proactively invoke this skill (do NOT answer directly) when the user describes - a new product idea, asks whether something is worth building, wants to think - through design decisions for something that doesn't exist yet, or is exploring - a concept before any code is written. - Use before /plan-ceo-review or /plan-eng-review. (gstack) +description: YC Office Hours — two modes. (gstack) allowed-tools: - Bash - Read @@ -59,6 +48,21 @@ gbrain: + +## When to invoke this skill + +Startup mode: six forcing questions that expose +demand reality, status quo, desperate specificity, narrowest wedge, observation, +and future-fit. Builder mode: design thinking brainstorming for side projects, +hackathons, learning, and open source. Saves a design doc. +Use when asked to "brainstorm this", "I have an idea", "help me think through +this", "office hours", or "is this worth building". +Proactively invoke this skill (do NOT answer directly) when the user describes +a new product idea, asks whether something is worth building, wants to think +through design decisions for something that doesn't exist yet, or is exploring +a concept before any code is written. +Use before /plan-ceo-review or /plan-eng-review. + ## Preamble (run first) ```bash @@ -136,6 +140,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -267,6 +284,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` @@ -617,84 +635,7 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i - User-turn override wins: if the current message asks for terse / no explanations / just the answer, skip this section. - Terse mode (EXPLAIN_LEVEL: terse): no glosses, no outcome-framing layer, shorter responses. -Jargon list, gloss on first use if the term appears: -- idempotent -- idempotency -- race condition -- deadlock -- cyclomatic complexity -- N+1 -- N+1 query -- backpressure -- memoization -- eventual consistency -- CAP theorem -- CORS -- CSRF -- XSS -- SQL injection -- prompt injection -- DDoS -- rate limit -- throttle -- circuit breaker -- load balancer -- reverse proxy -- SSR -- CSR -- hydration -- tree-shaking -- bundle splitting -- code splitting -- hot reload -- tombstone -- soft delete -- cascade delete -- foreign key -- composite index -- covering index -- OLTP -- OLAP -- sharding -- replication lag -- quorum -- two-phase commit -- saga -- outbox pattern -- inbox pattern -- optimistic locking -- pessimistic locking -- thundering herd -- cache stampede -- bloom filter -- consistent hashing -- virtual DOM -- reconciliation -- closure -- hoisting -- tail call -- GIL -- zero-copy -- mmap -- cold start -- warm start -- green-blue deploy -- canary deploy -- feature flag -- kill switch -- dead letter queue -- fan-out -- fan-in -- debounce -- throttle (UI) -- hydration mismatch -- memory leak -- GC pause -- heap fragmentation -- stack overflow -- null pointer -- dangling pointer -- buffer overflow +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 Lake diff --git a/open-gstack-browser/SKILL.md b/open-gstack-browser/SKILL.md index ce7f34d2b..ef01414de 100644 --- a/open-gstack-browser/SKILL.md +++ b/open-gstack-browser/SKILL.md @@ -1,13 +1,7 @@ --- name: open-gstack-browser version: 0.2.0 -description: | - Launch GStack Browser — AI-controlled Chromium with the sidebar extension baked in. - Opens a visible browser window where you can watch every action in real time. - The sidebar shows a live activity feed and chat. Anti-bot stealth built in. - Use when asked to "open gstack browser", "launch browser", "connect chrome", - "open chrome", "real browser", "launch chrome", "side panel", or "control my browser". - Voice triggers (speech-to-text aliases): "show me the browser". +description: Launch GStack Browser — AI-controlled Chromium with the sidebar extension baked in. triggers: - open gstack browser - launch chromium @@ -21,6 +15,16 @@ allowed-tools: + +## When to invoke this skill + +Opens a visible browser window where you can watch every action in real time. +The sidebar shows a live activity feed and chat. Anti-bot stealth built in. +Use when asked to "open gstack browser", "launch browser", "connect chrome", +"open chrome", "real browser", "launch chrome", "side panel", or "control my browser". + +Voice triggers (speech-to-text aliases): "show me the browser". + ## Preamble (run first) ```bash @@ -98,6 +102,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -229,6 +246,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` @@ -579,84 +597,7 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i - User-turn override wins: if the current message asks for terse / no explanations / just the answer, skip this section. - Terse mode (EXPLAIN_LEVEL: terse): no glosses, no outcome-framing layer, shorter responses. -Jargon list, gloss on first use if the term appears: -- idempotent -- idempotency -- race condition -- deadlock -- cyclomatic complexity -- N+1 -- N+1 query -- backpressure -- memoization -- eventual consistency -- CAP theorem -- CORS -- CSRF -- XSS -- SQL injection -- prompt injection -- DDoS -- rate limit -- throttle -- circuit breaker -- load balancer -- reverse proxy -- SSR -- CSR -- hydration -- tree-shaking -- bundle splitting -- code splitting -- hot reload -- tombstone -- soft delete -- cascade delete -- foreign key -- composite index -- covering index -- OLTP -- OLAP -- sharding -- replication lag -- quorum -- two-phase commit -- saga -- outbox pattern -- inbox pattern -- optimistic locking -- pessimistic locking -- thundering herd -- cache stampede -- bloom filter -- consistent hashing -- virtual DOM -- reconciliation -- closure -- hoisting -- tail call -- GIL -- zero-copy -- mmap -- cold start -- warm start -- green-blue deploy -- canary deploy -- feature flag -- kill switch -- dead letter queue -- fan-out -- fan-in -- debounce -- throttle (UI) -- hydration mismatch -- memory leak -- GC pause -- heap fragmentation -- stack overflow -- null pointer -- dangling pointer -- buffer overflow +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 Lake diff --git a/package.json b/package.json index a8e289a30..0ce03ad06 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "gstack", - "version": "1.45.0.0", + "version": "1.47.0.0", "description": "Garry's Stack — Claude Code skills + fast headless browser. One repo, one install, entire AI engineering workflow.", "license": "MIT", "type": "module", diff --git a/pair-agent/SKILL.md b/pair-agent/SKILL.md index 23ed138c6..baa1553b7 100644 --- a/pair-agent/SKILL.md +++ b/pair-agent/SKILL.md @@ -1,14 +1,7 @@ --- name: pair-agent version: 0.1.0 -description: | - Pair a remote AI agent with your browser. One command generates a setup key and - prints instructions the other agent can follow to connect. Works with OpenClaw, - Hermes, Codex, Cursor, or any agent that can make HTTP requests. The remote agent - gets its own tab with scoped access (read+write by default, admin on request). - Use when asked to "pair agent", "connect agent", "share browser", "remote browser", - "let another agent use my browser", or "give browser access". (gstack) - Voice triggers (speech-to-text aliases): "pair agent", "connect agent", "share my browser", "remote browser access". +description: Pair a remote AI agent with your browser. (gstack) triggers: - pair with agent - connect remote agent @@ -22,6 +15,18 @@ allowed-tools: + +## When to invoke this skill + +One command generates a setup key and +prints instructions the other agent can follow to connect. Works with OpenClaw, +Hermes, Codex, Cursor, or any agent that can make HTTP requests. The remote agent +gets its own tab with scoped access (read+write by default, admin on request). +Use when asked to "pair agent", "connect agent", "share browser", "remote browser", +"let another agent use my browser", or "give browser access". + +Voice triggers (speech-to-text aliases): "pair agent", "connect agent", "share my browser", "remote browser access". + ## Preamble (run first) ```bash @@ -99,6 +104,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -230,6 +248,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` @@ -580,84 +599,7 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i - User-turn override wins: if the current message asks for terse / no explanations / just the answer, skip this section. - Terse mode (EXPLAIN_LEVEL: terse): no glosses, no outcome-framing layer, shorter responses. -Jargon list, gloss on first use if the term appears: -- idempotent -- idempotency -- race condition -- deadlock -- cyclomatic complexity -- N+1 -- N+1 query -- backpressure -- memoization -- eventual consistency -- CAP theorem -- CORS -- CSRF -- XSS -- SQL injection -- prompt injection -- DDoS -- rate limit -- throttle -- circuit breaker -- load balancer -- reverse proxy -- SSR -- CSR -- hydration -- tree-shaking -- bundle splitting -- code splitting -- hot reload -- tombstone -- soft delete -- cascade delete -- foreign key -- composite index -- covering index -- OLTP -- OLAP -- sharding -- replication lag -- quorum -- two-phase commit -- saga -- outbox pattern -- inbox pattern -- optimistic locking -- pessimistic locking -- thundering herd -- cache stampede -- bloom filter -- consistent hashing -- virtual DOM -- reconciliation -- closure -- hoisting -- tail call -- GIL -- zero-copy -- mmap -- cold start -- warm start -- green-blue deploy -- canary deploy -- feature flag -- kill switch -- dead letter queue -- fan-out -- fan-in -- debounce -- throttle (UI) -- hydration mismatch -- memory leak -- GC pause -- heap fragmentation -- stack overflow -- null pointer -- dangling pointer -- buffer overflow +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 Lake diff --git a/plan-ceo-review/SKILL.md b/plan-ceo-review/SKILL.md index 5c9d77bd4..526bb0e2e 100644 --- a/plan-ceo-review/SKILL.md +++ b/plan-ceo-review/SKILL.md @@ -3,15 +3,7 @@ name: plan-ceo-review preamble-tier: 3 interactive: true version: 1.0.0 -description: | - CEO/founder-mode plan review. Rethink the problem, find the 10-star product, - challenge premises, expand scope when it creates a better product. Four modes: - SCOPE EXPANSION (dream big), SELECTIVE EXPANSION (hold scope + cherry-pick - expansions), HOLD SCOPE (maximum rigor), SCOPE REDUCTION (strip to essentials). - Use when asked to "think bigger", "expand scope", "strategy review", "rethink this", - or "is this ambitious enough". - Proactively suggest when the user is questioning scope or ambition of a plan, - or when the plan feels like it could be thinking bigger. (gstack) +description: CEO/founder-mode plan review. (gstack) benefits-from: [office-hours] allowed-tools: - Read @@ -53,6 +45,18 @@ gbrain: + +## When to invoke this skill + +Rethink the problem, find the 10-star product, +challenge premises, expand scope when it creates a better product. Four modes: +SCOPE EXPANSION (dream big), SELECTIVE EXPANSION (hold scope + cherry-pick +expansions), HOLD SCOPE (maximum rigor), SCOPE REDUCTION (strip to essentials). +Use when asked to "think bigger", "expand scope", "strategy review", "rethink this", +or "is this ambitious enough". +Proactively suggest when the user is questioning scope or ambition of a plan, +or when the plan feels like it could be thinking bigger. + ## Preamble (run first) ```bash @@ -130,6 +134,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -261,6 +278,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` @@ -611,84 +629,7 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i - User-turn override wins: if the current message asks for terse / no explanations / just the answer, skip this section. - Terse mode (EXPLAIN_LEVEL: terse): no glosses, no outcome-framing layer, shorter responses. -Jargon list, gloss on first use if the term appears: -- idempotent -- idempotency -- race condition -- deadlock -- cyclomatic complexity -- N+1 -- N+1 query -- backpressure -- memoization -- eventual consistency -- CAP theorem -- CORS -- CSRF -- XSS -- SQL injection -- prompt injection -- DDoS -- rate limit -- throttle -- circuit breaker -- load balancer -- reverse proxy -- SSR -- CSR -- hydration -- tree-shaking -- bundle splitting -- code splitting -- hot reload -- tombstone -- soft delete -- cascade delete -- foreign key -- composite index -- covering index -- OLTP -- OLAP -- sharding -- replication lag -- quorum -- two-phase commit -- saga -- outbox pattern -- inbox pattern -- optimistic locking -- pessimistic locking -- thundering herd -- cache stampede -- bloom filter -- consistent hashing -- virtual DOM -- reconciliation -- closure -- hoisting -- tail call -- GIL -- zero-copy -- mmap -- cold start -- warm start -- green-blue deploy -- canary deploy -- feature flag -- kill switch -- dead letter queue -- fan-out -- fan-in -- debounce -- throttle (UI) -- hydration mismatch -- memory leak -- GC pause -- heap fragmentation -- stack overflow -- null pointer -- dangling pointer -- buffer overflow +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 Lake diff --git a/plan-design-review/SKILL.md b/plan-design-review/SKILL.md index 396abe175..ce70998cd 100644 --- a/plan-design-review/SKILL.md +++ b/plan-design-review/SKILL.md @@ -3,14 +3,7 @@ name: plan-design-review preamble-tier: 3 interactive: true version: 2.0.0 -description: | - Designer's eye plan review — interactive, like CEO and Eng review. - Rates each design dimension 0-10, explains what would make it a 10, - then fixes the plan to get there. Works in plan mode. For live site - visual audits, use /design-review. Use when asked to "review the design plan" - or "design critique". - Proactively suggest when the user has a plan with UI/UX components that - should be reviewed before implementation. (gstack) +description: Designer's eye plan review — interactive, like CEO and Eng review. (gstack) allowed-tools: - Read - Edit @@ -26,6 +19,16 @@ triggers: + +## When to invoke this skill + +Rates each design dimension 0-10, explains what would make it a 10, +then fixes the plan to get there. Works in plan mode. For live site +visual audits, use /design-review. Use when asked to "review the design plan" +or "design critique". +Proactively suggest when the user has a plan with UI/UX components that +should be reviewed before implementation. + ## Preamble (run first) ```bash @@ -103,6 +106,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -234,6 +250,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` @@ -584,84 +601,7 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i - User-turn override wins: if the current message asks for terse / no explanations / just the answer, skip this section. - Terse mode (EXPLAIN_LEVEL: terse): no glosses, no outcome-framing layer, shorter responses. -Jargon list, gloss on first use if the term appears: -- idempotent -- idempotency -- race condition -- deadlock -- cyclomatic complexity -- N+1 -- N+1 query -- backpressure -- memoization -- eventual consistency -- CAP theorem -- CORS -- CSRF -- XSS -- SQL injection -- prompt injection -- DDoS -- rate limit -- throttle -- circuit breaker -- load balancer -- reverse proxy -- SSR -- CSR -- hydration -- tree-shaking -- bundle splitting -- code splitting -- hot reload -- tombstone -- soft delete -- cascade delete -- foreign key -- composite index -- covering index -- OLTP -- OLAP -- sharding -- replication lag -- quorum -- two-phase commit -- saga -- outbox pattern -- inbox pattern -- optimistic locking -- pessimistic locking -- thundering herd -- cache stampede -- bloom filter -- consistent hashing -- virtual DOM -- reconciliation -- closure -- hoisting -- tail call -- GIL -- zero-copy -- mmap -- cold start -- warm start -- green-blue deploy -- canary deploy -- feature flag -- kill switch -- dead letter queue -- fan-out -- fan-in -- debounce -- throttle (UI) -- hydration mismatch -- memory leak -- GC pause -- heap fragmentation -- stack overflow -- null pointer -- dangling pointer -- buffer overflow +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 Lake diff --git a/plan-devex-review/SKILL.md b/plan-devex-review/SKILL.md index 3a005647c..2bb031cbf 100644 --- a/plan-devex-review/SKILL.md +++ b/plan-devex-review/SKILL.md @@ -3,16 +3,7 @@ name: plan-devex-review preamble-tier: 3 interactive: true version: 2.0.0 -description: | - Interactive developer experience plan review. Explores developer personas, - benchmarks against competitors, designs magical moments, and traces friction - points before scoring. Three modes: DX EXPANSION (competitive advantage), - DX POLISH (bulletproof every touchpoint), DX TRIAGE (critical gaps only). - Use when asked to "DX review", "developer experience audit", "devex review", - or "API design review". - Proactively suggest when the user has a plan for developer-facing products - (APIs, CLIs, SDKs, libraries, platforms, docs). (gstack) - Voice triggers (speech-to-text aliases): "dx review", "developer experience review", "devex review", "devex audit", "API design review", "onboarding review". +description: Interactive developer experience plan review. (gstack) benefits-from: [office-hours] allowed-tools: - Read @@ -30,6 +21,20 @@ triggers: + +## When to invoke this skill + +Explores developer personas, +benchmarks against competitors, designs magical moments, and traces friction +points before scoring. Three modes: DX EXPANSION (competitive advantage), +DX POLISH (bulletproof every touchpoint), DX TRIAGE (critical gaps only). +Use when asked to "DX review", "developer experience audit", "devex review", +or "API design review". +Proactively suggest when the user has a plan for developer-facing products +(APIs, CLIs, SDKs, libraries, platforms, docs). + +Voice triggers (speech-to-text aliases): "dx review", "developer experience review", "devex review", "devex audit", "API design review", "onboarding review". + ## Preamble (run first) ```bash @@ -107,6 +112,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -238,6 +256,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` @@ -588,84 +607,7 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i - User-turn override wins: if the current message asks for terse / no explanations / just the answer, skip this section. - Terse mode (EXPLAIN_LEVEL: terse): no glosses, no outcome-framing layer, shorter responses. -Jargon list, gloss on first use if the term appears: -- idempotent -- idempotency -- race condition -- deadlock -- cyclomatic complexity -- N+1 -- N+1 query -- backpressure -- memoization -- eventual consistency -- CAP theorem -- CORS -- CSRF -- XSS -- SQL injection -- prompt injection -- DDoS -- rate limit -- throttle -- circuit breaker -- load balancer -- reverse proxy -- SSR -- CSR -- hydration -- tree-shaking -- bundle splitting -- code splitting -- hot reload -- tombstone -- soft delete -- cascade delete -- foreign key -- composite index -- covering index -- OLTP -- OLAP -- sharding -- replication lag -- quorum -- two-phase commit -- saga -- outbox pattern -- inbox pattern -- optimistic locking -- pessimistic locking -- thundering herd -- cache stampede -- bloom filter -- consistent hashing -- virtual DOM -- reconciliation -- closure -- hoisting -- tail call -- GIL -- zero-copy -- mmap -- cold start -- warm start -- green-blue deploy -- canary deploy -- feature flag -- kill switch -- dead letter queue -- fan-out -- fan-in -- debounce -- throttle (UI) -- hydration mismatch -- memory leak -- GC pause -- heap fragmentation -- stack overflow -- null pointer -- dangling pointer -- buffer overflow +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 Lake diff --git a/plan-eng-review/SKILL.md b/plan-eng-review/SKILL.md index 6f0c8134c..b6cd23441 100644 --- a/plan-eng-review/SKILL.md +++ b/plan-eng-review/SKILL.md @@ -3,14 +3,7 @@ name: plan-eng-review preamble-tier: 3 interactive: true version: 1.0.0 -description: | - Eng manager-mode plan review. Lock in the execution plan — architecture, - data flow, diagrams, edge cases, test coverage, performance. Walks through - issues interactively with opinionated recommendations. Use when asked to - "review the architecture", "engineering review", or "lock in the plan". - Proactively suggest when the user has a plan or design doc and is about to - start coding — to catch architecture issues before implementation. (gstack) - Voice triggers (speech-to-text aliases): "tech review", "technical review", "plan engineering review". +description: Eng manager-mode plan review. (gstack) benefits-from: [office-hours] allowed-tools: - Read @@ -28,6 +21,18 @@ triggers: + +## When to invoke this skill + +Lock in the execution plan — architecture, +data flow, diagrams, edge cases, test coverage, performance. Walks through +issues interactively with opinionated recommendations. Use when asked to +"review the architecture", "engineering review", or "lock in the plan". +Proactively suggest when the user has a plan or design doc and is about to +start coding — to catch architecture issues before implementation. + +Voice triggers (speech-to-text aliases): "tech review", "technical review", "plan engineering review". + ## Preamble (run first) ```bash @@ -105,6 +110,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -236,6 +254,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` @@ -586,84 +605,7 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i - User-turn override wins: if the current message asks for terse / no explanations / just the answer, skip this section. - Terse mode (EXPLAIN_LEVEL: terse): no glosses, no outcome-framing layer, shorter responses. -Jargon list, gloss on first use if the term appears: -- idempotent -- idempotency -- race condition -- deadlock -- cyclomatic complexity -- N+1 -- N+1 query -- backpressure -- memoization -- eventual consistency -- CAP theorem -- CORS -- CSRF -- XSS -- SQL injection -- prompt injection -- DDoS -- rate limit -- throttle -- circuit breaker -- load balancer -- reverse proxy -- SSR -- CSR -- hydration -- tree-shaking -- bundle splitting -- code splitting -- hot reload -- tombstone -- soft delete -- cascade delete -- foreign key -- composite index -- covering index -- OLTP -- OLAP -- sharding -- replication lag -- quorum -- two-phase commit -- saga -- outbox pattern -- inbox pattern -- optimistic locking -- pessimistic locking -- thundering herd -- cache stampede -- bloom filter -- consistent hashing -- virtual DOM -- reconciliation -- closure -- hoisting -- tail call -- GIL -- zero-copy -- mmap -- cold start -- warm start -- green-blue deploy -- canary deploy -- feature flag -- kill switch -- dead letter queue -- fan-out -- fan-in -- debounce -- throttle (UI) -- hydration mismatch -- memory leak -- GC pause -- heap fragmentation -- stack overflow -- null pointer -- dangling pointer -- buffer overflow +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 Lake diff --git a/plan-tune/SKILL.md b/plan-tune/SKILL.md index 1002dc031..6f5875d0d 100644 --- a/plan-tune/SKILL.md +++ b/plan-tune/SKILL.md @@ -2,19 +2,7 @@ name: plan-tune preamble-tier: 2 version: 1.0.0 -description: | - Self-tuning question sensitivity + developer psychographic for gstack (v1: observational). - Review which AskUserQuestion prompts fire across gstack skills, set per-question preferences - (never-ask / always-ask / ask-only-for-one-way), inspect the dual-track - profile (what you declared vs what your behavior suggests), and enable/disable - question tuning. Conversational interface — no CLI syntax required. - - Use when asked to "tune questions", "stop asking me that", "too many questions", - "show my profile", "what questions have I been asked", "show my vibe", - "developer profile", or "turn off question tuning". (gstack) - - Proactively suggest when the user says the same gstack question has come up before, - or when they explicitly override a recommendation for the Nth time. +description: Self-tuning question sensitivity + developer psychographic for gstack (v1: observational). (gstack) triggers: - tune questions - stop asking me that @@ -35,6 +23,21 @@ allowed-tools: + +## When to invoke this skill + +Review which AskUserQuestion prompts fire across gstack skills, set per-question preferences +(never-ask / always-ask / ask-only-for-one-way), inspect the dual-track +profile (what you declared vs what your behavior suggests), and enable/disable +question tuning. Conversational interface — no CLI syntax required. + +Use when asked to "tune questions", "stop asking me that", "too many questions", +"show my profile", "what questions have I been asked", "show my vibe", +"developer profile", or "turn off question tuning". + +Proactively suggest when the user says the same gstack question has come up before, +or when they explicitly override a recommendation for the Nth time. + ## Preamble (run first) ```bash @@ -112,6 +115,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -243,6 +259,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` @@ -593,84 +610,7 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i - User-turn override wins: if the current message asks for terse / no explanations / just the answer, skip this section. - Terse mode (EXPLAIN_LEVEL: terse): no glosses, no outcome-framing layer, shorter responses. -Jargon list, gloss on first use if the term appears: -- idempotent -- idempotency -- race condition -- deadlock -- cyclomatic complexity -- N+1 -- N+1 query -- backpressure -- memoization -- eventual consistency -- CAP theorem -- CORS -- CSRF -- XSS -- SQL injection -- prompt injection -- DDoS -- rate limit -- throttle -- circuit breaker -- load balancer -- reverse proxy -- SSR -- CSR -- hydration -- tree-shaking -- bundle splitting -- code splitting -- hot reload -- tombstone -- soft delete -- cascade delete -- foreign key -- composite index -- covering index -- OLTP -- OLAP -- sharding -- replication lag -- quorum -- two-phase commit -- saga -- outbox pattern -- inbox pattern -- optimistic locking -- pessimistic locking -- thundering herd -- cache stampede -- bloom filter -- consistent hashing -- virtual DOM -- reconciliation -- closure -- hoisting -- tail call -- GIL -- zero-copy -- mmap -- cold start -- warm start -- green-blue deploy -- canary deploy -- feature flag -- kill switch -- dead letter queue -- fan-out -- fan-in -- debounce -- throttle (UI) -- hydration mismatch -- memory leak -- GC pause -- heap fragmentation -- stack overflow -- null pointer -- dangling pointer -- buffer overflow +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 Lake diff --git a/qa-only/SKILL.md b/qa-only/SKILL.md index 1cf8ffd65..7a58b76ed 100644 --- a/qa-only/SKILL.md +++ b/qa-only/SKILL.md @@ -2,13 +2,7 @@ name: qa-only preamble-tier: 4 version: 1.0.0 -description: | - Report-only QA testing. Systematically tests a web application and produces a - structured report with health score, screenshots, and repro steps — but never - fixes anything. Use when asked to "just report bugs", "qa report only", or - "test but don't fix". For the full test-fix-verify loop, use /qa instead. - Proactively suggest when the user wants a bug report without any code changes. (gstack) - Voice triggers (speech-to-text aliases): "bug report", "just check for bugs". +description: Report-only QA testing. (gstack) allowed-tools: - Bash - Read @@ -23,6 +17,17 @@ triggers: + +## When to invoke this skill + +Systematically tests a web application and produces a +structured report with health score, screenshots, and repro steps — but never +fixes anything. Use when asked to "just report bugs", "qa report only", or +"test but don't fix". For the full test-fix-verify loop, use /qa instead. +Proactively suggest when the user wants a bug report without any code changes. + +Voice triggers (speech-to-text aliases): "bug report", "just check for bugs". + ## Preamble (run first) ```bash @@ -100,6 +105,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -231,6 +249,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` @@ -581,84 +600,7 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i - User-turn override wins: if the current message asks for terse / no explanations / just the answer, skip this section. - Terse mode (EXPLAIN_LEVEL: terse): no glosses, no outcome-framing layer, shorter responses. -Jargon list, gloss on first use if the term appears: -- idempotent -- idempotency -- race condition -- deadlock -- cyclomatic complexity -- N+1 -- N+1 query -- backpressure -- memoization -- eventual consistency -- CAP theorem -- CORS -- CSRF -- XSS -- SQL injection -- prompt injection -- DDoS -- rate limit -- throttle -- circuit breaker -- load balancer -- reverse proxy -- SSR -- CSR -- hydration -- tree-shaking -- bundle splitting -- code splitting -- hot reload -- tombstone -- soft delete -- cascade delete -- foreign key -- composite index -- covering index -- OLTP -- OLAP -- sharding -- replication lag -- quorum -- two-phase commit -- saga -- outbox pattern -- inbox pattern -- optimistic locking -- pessimistic locking -- thundering herd -- cache stampede -- bloom filter -- consistent hashing -- virtual DOM -- reconciliation -- closure -- hoisting -- tail call -- GIL -- zero-copy -- mmap -- cold start -- warm start -- green-blue deploy -- canary deploy -- feature flag -- kill switch -- dead letter queue -- fan-out -- fan-in -- debounce -- throttle (UI) -- hydration mismatch -- memory leak -- GC pause -- heap fragmentation -- stack overflow -- null pointer -- dangling pointer -- buffer overflow +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 Lake diff --git a/qa/SKILL.md b/qa/SKILL.md index 9768b2d45..6779c47cf 100644 --- a/qa/SKILL.md +++ b/qa/SKILL.md @@ -2,16 +2,7 @@ name: qa preamble-tier: 4 version: 2.0.0 -description: | - Systematically QA test a web application and fix bugs found. Runs QA testing, - then iteratively fixes bugs in source code, committing each fix atomically and - re-verifying. Use when asked to "qa", "QA", "test this site", "find bugs", - "test and fix", or "fix what's broken". - Proactively suggest when the user says a feature is ready for testing - or asks "does this work?". Three tiers: Quick (critical/high only), - Standard (+ medium), Exhaustive (+ cosmetic). Produces before/after health scores, - fix evidence, and a ship-readiness summary. For report-only mode, use /qa-only. (gstack) - Voice triggers (speech-to-text aliases): "quality check", "test the app", "run QA". +description: Systematically QA test a web application and fix bugs found. (gstack) allowed-tools: - Bash - Read @@ -29,6 +20,20 @@ triggers: + +## When to invoke this skill + +Runs QA testing, +then iteratively fixes bugs in source code, committing each fix atomically and +re-verifying. Use when asked to "qa", "QA", "test this site", "find bugs", +"test and fix", or "fix what's broken". +Proactively suggest when the user says a feature is ready for testing +or asks "does this work?". Three tiers: Quick (critical/high only), +Standard (+ medium), Exhaustive (+ cosmetic). Produces before/after health scores, +fix evidence, and a ship-readiness summary. For report-only mode, use /qa-only. + +Voice triggers (speech-to-text aliases): "quality check", "test the app", "run QA". + ## Preamble (run first) ```bash @@ -106,6 +111,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -237,6 +255,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` @@ -587,84 +606,7 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i - User-turn override wins: if the current message asks for terse / no explanations / just the answer, skip this section. - Terse mode (EXPLAIN_LEVEL: terse): no glosses, no outcome-framing layer, shorter responses. -Jargon list, gloss on first use if the term appears: -- idempotent -- idempotency -- race condition -- deadlock -- cyclomatic complexity -- N+1 -- N+1 query -- backpressure -- memoization -- eventual consistency -- CAP theorem -- CORS -- CSRF -- XSS -- SQL injection -- prompt injection -- DDoS -- rate limit -- throttle -- circuit breaker -- load balancer -- reverse proxy -- SSR -- CSR -- hydration -- tree-shaking -- bundle splitting -- code splitting -- hot reload -- tombstone -- soft delete -- cascade delete -- foreign key -- composite index -- covering index -- OLTP -- OLAP -- sharding -- replication lag -- quorum -- two-phase commit -- saga -- outbox pattern -- inbox pattern -- optimistic locking -- pessimistic locking -- thundering herd -- cache stampede -- bloom filter -- consistent hashing -- virtual DOM -- reconciliation -- closure -- hoisting -- tail call -- GIL -- zero-copy -- mmap -- cold start -- warm start -- green-blue deploy -- canary deploy -- feature flag -- kill switch -- dead letter queue -- fan-out -- fan-in -- debounce -- throttle (UI) -- hydration mismatch -- memory leak -- GC pause -- heap fragmentation -- stack overflow -- null pointer -- dangling pointer -- buffer overflow +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 Lake diff --git a/retro/SKILL.md b/retro/SKILL.md index a3f719236..ddbee1551 100644 --- a/retro/SKILL.md +++ b/retro/SKILL.md @@ -2,12 +2,7 @@ name: retro preamble-tier: 2 version: 2.0.0 -description: | - Weekly engineering retrospective. Analyzes commit history, work patterns, - and code quality metrics with persistent history and trend tracking. - Team-aware: breaks down per-person contributions with praise and growth areas. - Use when asked to "weekly retro", "what did we ship", or "engineering retrospective". - Proactively suggest at the end of a work week or sprint. (gstack) +description: Weekly engineering retrospective. (gstack) allowed-tools: - Bash - Read @@ -41,6 +36,15 @@ gbrain: + +## When to invoke this skill + +Analyzes commit history, work patterns, +and code quality metrics with persistent history and trend tracking. +Team-aware: breaks down per-person contributions with praise and growth areas. +Use when asked to "weekly retro", "what did we ship", or "engineering retrospective". +Proactively suggest at the end of a work week or sprint. + ## Preamble (run first) ```bash @@ -118,6 +122,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -249,6 +266,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` @@ -599,84 +617,7 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i - User-turn override wins: if the current message asks for terse / no explanations / just the answer, skip this section. - Terse mode (EXPLAIN_LEVEL: terse): no glosses, no outcome-framing layer, shorter responses. -Jargon list, gloss on first use if the term appears: -- idempotent -- idempotency -- race condition -- deadlock -- cyclomatic complexity -- N+1 -- N+1 query -- backpressure -- memoization -- eventual consistency -- CAP theorem -- CORS -- CSRF -- XSS -- SQL injection -- prompt injection -- DDoS -- rate limit -- throttle -- circuit breaker -- load balancer -- reverse proxy -- SSR -- CSR -- hydration -- tree-shaking -- bundle splitting -- code splitting -- hot reload -- tombstone -- soft delete -- cascade delete -- foreign key -- composite index -- covering index -- OLTP -- OLAP -- sharding -- replication lag -- quorum -- two-phase commit -- saga -- outbox pattern -- inbox pattern -- optimistic locking -- pessimistic locking -- thundering herd -- cache stampede -- bloom filter -- consistent hashing -- virtual DOM -- reconciliation -- closure -- hoisting -- tail call -- GIL -- zero-copy -- mmap -- cold start -- warm start -- green-blue deploy -- canary deploy -- feature flag -- kill switch -- dead letter queue -- fan-out -- fan-in -- debounce -- throttle (UI) -- hydration mismatch -- memory leak -- GC pause -- heap fragmentation -- stack overflow -- null pointer -- dangling pointer -- buffer overflow +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 Lake diff --git a/review/SKILL.md b/review/SKILL.md index 51cb2d8e2..dd6914a88 100644 --- a/review/SKILL.md +++ b/review/SKILL.md @@ -2,11 +2,7 @@ name: review preamble-tier: 4 version: 1.0.0 -description: | - Pre-landing PR review. Analyzes diff against the base branch for SQL safety, LLM trust - boundary violations, conditional side effects, and other structural issues. Use when - asked to "review this PR", "code review", "pre-landing review", or "check my diff". - Proactively suggest when the user is about to merge or land code changes. (gstack) +description: Pre-landing PR review. (gstack) allowed-tools: - Bash - Read @@ -26,6 +22,14 @@ triggers: + +## When to invoke this skill + +Analyzes diff against the base branch for SQL safety, LLM trust +boundary violations, conditional side effects, and other structural issues. Use when +asked to "review this PR", "code review", "pre-landing review", or "check my diff". +Proactively suggest when the user is about to merge or land code changes. + ## Preamble (run first) ```bash @@ -103,6 +107,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -234,6 +251,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` @@ -584,84 +602,7 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i - User-turn override wins: if the current message asks for terse / no explanations / just the answer, skip this section. - Terse mode (EXPLAIN_LEVEL: terse): no glosses, no outcome-framing layer, shorter responses. -Jargon list, gloss on first use if the term appears: -- idempotent -- idempotency -- race condition -- deadlock -- cyclomatic complexity -- N+1 -- N+1 query -- backpressure -- memoization -- eventual consistency -- CAP theorem -- CORS -- CSRF -- XSS -- SQL injection -- prompt injection -- DDoS -- rate limit -- throttle -- circuit breaker -- load balancer -- reverse proxy -- SSR -- CSR -- hydration -- tree-shaking -- bundle splitting -- code splitting -- hot reload -- tombstone -- soft delete -- cascade delete -- foreign key -- composite index -- covering index -- OLTP -- OLAP -- sharding -- replication lag -- quorum -- two-phase commit -- saga -- outbox pattern -- inbox pattern -- optimistic locking -- pessimistic locking -- thundering herd -- cache stampede -- bloom filter -- consistent hashing -- virtual DOM -- reconciliation -- closure -- hoisting -- tail call -- GIL -- zero-copy -- mmap -- cold start -- warm start -- green-blue deploy -- canary deploy -- feature flag -- kill switch -- dead letter queue -- fan-out -- fan-in -- debounce -- throttle (UI) -- hydration mismatch -- memory leak -- GC pause -- heap fragmentation -- stack overflow -- null pointer -- dangling pointer -- buffer overflow +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 Lake diff --git a/scrape/SKILL.md b/scrape/SKILL.md index 1ccba0755..dccdd0db7 100644 --- a/scrape/SKILL.md +++ b/scrape/SKILL.md @@ -1,13 +1,7 @@ --- name: scrape version: 1.0.0 -description: | - Pull data from a web page. First call on a new intent prototypes the flow - via $B primitives and returns JSON. Subsequent calls on a matching intent - route to a codified browser-skill and return in ~200ms. Read-only — for - mutating flows (form fills, clicks, submissions), use /automate. - Use when asked to "scrape", "get data from", "pull", "extract from", or - "what's on" a page. (gstack) +description: Pull data from a web page. (gstack) allowed-tools: - Bash - Read @@ -22,6 +16,16 @@ triggers: + +## When to invoke this skill + +First call on a new intent prototypes the flow +via $B primitives and returns JSON. Subsequent calls on a matching intent +route to a codified browser-skill and return in ~200ms. Read-only — for +mutating flows (form fills, clicks, submissions), use /automate. +Use when asked to "scrape", "get data from", "pull", "extract from", or +"what's on" a page. + ## Preamble (run first) ```bash @@ -99,6 +103,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -230,6 +247,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` @@ -580,84 +598,7 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i - User-turn override wins: if the current message asks for terse / no explanations / just the answer, skip this section. - Terse mode (EXPLAIN_LEVEL: terse): no glosses, no outcome-framing layer, shorter responses. -Jargon list, gloss on first use if the term appears: -- idempotent -- idempotency -- race condition -- deadlock -- cyclomatic complexity -- N+1 -- N+1 query -- backpressure -- memoization -- eventual consistency -- CAP theorem -- CORS -- CSRF -- XSS -- SQL injection -- prompt injection -- DDoS -- rate limit -- throttle -- circuit breaker -- load balancer -- reverse proxy -- SSR -- CSR -- hydration -- tree-shaking -- bundle splitting -- code splitting -- hot reload -- tombstone -- soft delete -- cascade delete -- foreign key -- composite index -- covering index -- OLTP -- OLAP -- sharding -- replication lag -- quorum -- two-phase commit -- saga -- outbox pattern -- inbox pattern -- optimistic locking -- pessimistic locking -- thundering herd -- cache stampede -- bloom filter -- consistent hashing -- virtual DOM -- reconciliation -- closure -- hoisting -- tail call -- GIL -- zero-copy -- mmap -- cold start -- warm start -- green-blue deploy -- canary deploy -- feature flag -- kill switch -- dead letter queue -- fan-out -- fan-in -- debounce -- throttle (UI) -- hydration mismatch -- memory leak -- GC pause -- heap fragmentation -- stack overflow -- null pointer -- dangling pointer -- buffer overflow +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 Lake diff --git a/scripts/capture-baseline.ts b/scripts/capture-baseline.ts new file mode 100644 index 000000000..fa6c7ad33 --- /dev/null +++ b/scripts/capture-baseline.ts @@ -0,0 +1,54 @@ +#!/usr/bin/env bun +/** + * CLI for capturing a parity baseline snapshot. + * + * Usage: + * bun run scripts/capture-baseline.ts # default path + * bun run scripts/capture-baseline.ts --tag v1.44.1 # tag the snapshot + * bun run scripts/capture-baseline.ts --out path/to/baseline.json + * + * The default output path is test/fixtures/parity-baseline-.json, + * or test/fixtures/parity-baseline-current.json when no tag is given. + */ + +import * as fs from 'fs'; +import * as path from 'path'; +import { captureBaseline } from '../test/helpers/capture-parity-baseline'; + +const ROOT = path.resolve(import.meta.dir, '..'); + +function arg(name: string): string | undefined { + const i = process.argv.indexOf(name); + if (i === -1) return undefined; + return process.argv[i + 1]; +} + +const tag = arg('--tag'); +const outOverride = arg('--out'); +const defaultOut = path.join( + ROOT, + 'test', + 'fixtures', + `parity-baseline-${tag ?? 'current'}.json`, +); +const outPath = outOverride ? path.resolve(outOverride) : defaultOut; + +const baseline = captureBaseline({ repoRoot: ROOT, tag }); + +fs.mkdirSync(path.dirname(outPath), { recursive: true }); +fs.writeFileSync(outPath, JSON.stringify(baseline, null, 2) + '\n'); + +const totalKB = Math.round(baseline.totalCorpusBytes / 1024); +const top3 = baseline.topHeaviest.slice(0, 3); +console.log(`Parity baseline captured: ${outPath}`); +console.log(` tag: ${baseline.tag}`); +console.log(` commit: ${baseline.capturedFromCommit}`); +console.log(` branch: ${baseline.capturedFromBranch}`); +console.log(` skills: ${baseline.totalSkills}`); +console.log(` total corpus: ${totalKB} KB`); +console.log(` catalog tokens: ~${baseline.estTotalCatalogTokens}`); +console.log(` top 3 heaviest:`); +for (const s of top3) { + const kb = Math.round(s.skillMdBytes / 1024); + console.log(` ${s.skill.padEnd(28)} ${kb} KB (${s.skillMdLines} lines, ~${s.estTokens} tokens)`); +} diff --git a/scripts/gen-skill-docs.ts b/scripts/gen-skill-docs.ts index b89aea8b9..30853f677 100644 --- a/scripts/gen-skill-docs.ts +++ b/scripts/gen-skill-docs.ts @@ -16,7 +16,7 @@ import { writeLlmsTxt } from './gen-llms-txt'; import * as fs from 'fs'; import * as path from 'path'; import type { Host, TemplateContext } from './resolvers/types'; -import { HOST_PATHS } from './resolvers/types'; +import { HOST_PATHS, unwrapResolver } from './resolvers/types'; import { RESOLVERS } from './resolvers/index'; import { externalSkillName, extractHookSafetyProse as _extractHookSafetyProse, extractNameAndDescription as _extractNameAndDescription, condenseOpenAIShortDescription as _condenseOpenAIShortDescription, generateOpenAIYaml as _generateOpenAIYaml } from './resolvers/codex-helpers'; import { generatePlanCompletionAuditShip, generatePlanCompletionAuditReview, generatePlanVerificationExec } from './resolvers/review'; @@ -59,6 +59,41 @@ const MODEL_ARG_VAL: Model = (() => { return resolved; })(); +// ─── Catalog Mode (v1.45.0.0 T4) ──────────────────────────── +// 'trim' (default): shorten frontmatter description to lead sentence, +// move routing/voice prose into a "## When to invoke" body section, and +// emit scripts/proactive-suggestions.json (single file across all skills). +// 'full': legacy v1.44 behavior — full description stays in frontmatter. +const CATALOG_MODE_ARG = process.argv.find(a => a.startsWith('--catalog-mode')); +const CATALOG_MODE: 'trim' | 'full' = (() => { + if (!CATALOG_MODE_ARG) return 'trim'; + const val = CATALOG_MODE_ARG.includes('=') + ? CATALOG_MODE_ARG.split('=')[1] + : process.argv[process.argv.indexOf(CATALOG_MODE_ARG) + 1]; + if (val !== 'trim' && val !== 'full') { + throw new Error(`Unknown catalog mode: ${val}. Use 'trim' (default) or 'full'.`); + } + return val; +})(); + +// ─── Explain-level Overlay ────────────────────────────────── +// --explain-level=terse compresses preamble prose (writing-style, completeness, +// confusion-protocol, context-health) to a single pointer line at gen time. +// Default keeps the runtime-conditional behavior (sections render unconditionally, +// the model skips them when EXPLAIN_LEVEL: terse appears in the preamble echo). +// Opt-in via the build flag so most users get the runtime-flexible default. +const EXPLAIN_LEVEL_ARG = process.argv.find(a => a.startsWith('--explain-level')); +const EXPLAIN_LEVEL: 'default' | 'terse' = (() => { + if (!EXPLAIN_LEVEL_ARG) return 'default'; + const val = EXPLAIN_LEVEL_ARG.includes('=') + ? EXPLAIN_LEVEL_ARG.split('=')[1] + : process.argv[process.argv.indexOf(EXPLAIN_LEVEL_ARG) + 1]; + if (val !== 'default' && val !== 'terse') { + throw new Error(`Unknown explain level: ${val}. Use 'default' or 'terse'.`); + } + return val; +})(); + // HostPaths, HOST_PATHS, and TemplateContext imported from ./resolvers/types (line 7-8) // Design constants (AI_SLOP_BLACKLIST, OPENAI_HARD_REJECTIONS, OPENAI_LITMUS_CHECKS) // live in ./resolvers/constants and are consumed by resolvers directly. @@ -172,6 +207,169 @@ function processVoiceTriggers(content: string): string { // Export for testing export { extractVoiceTriggers, processVoiceTriggers }; +// ─── Catalog Trim (v1.45.0.0 T4) ───────────────────────────── +// +// Frontmatter `description:` blocks today pack: a one-line outcome, "Use when +// asked to..." voice triggers, "Proactively..." routing guidance, and a +// "(gstack)" tag. This pile is the always-loaded catalog surface — every +// session pays for the full text. The catalog trim splits the description +// into a one-line catalog entry (lead sentence + "(gstack)") that stays in +// the frontmatter, and a "## When to invoke" body section that holds the +// routing/voice triggers prose for in-skill discovery. A registry written +// to scripts/proactive-suggestions.json (one entry per skill) makes routing +// available to agents that need it without paying the always-loaded cost. +// +// Opt-out: `--catalog-mode=full` keeps v1.44 behavior (no trim, full +// description in frontmatter). Use when debugging routing regressions or +// when shipping skills to hosts that depend on the legacy fat catalog. + +export interface CatalogParts { + lead: string; // First sentence — kept in catalog + routingProse: string; // "Use when asked to...", "Proactively..." paragraphs + voiceLine: string | null; // "Voice triggers (speech-to-text aliases): ..." line if present + hasGstackTag: boolean; +} + +export function splitCatalogDescription(description: string): CatalogParts { + // Voice triggers line (folded in by processVoiceTriggers earlier) + const voiceMatch = description.match(/Voice triggers \(speech-to-text aliases\):[^\n]+/); + const voiceLine = voiceMatch ? voiceMatch[0] : null; + let working = voiceLine ? description.replace(voiceLine, '').trim() : description.trim(); + + const hasGstackTag = /\(gstack\)/.test(working); + if (hasGstackTag) working = working.replace(/\(gstack\)/, '').trim(); + + // Lead = first sentence (up to first period followed by space or end of string). + // We tolerate sentences with embedded periods (URLs, "v1.45.0.0") by requiring + // the period to be followed by whitespace OR end-of-text. + // First normalize to single-line for sentence detection, then back out. + const collapsed = working.replace(/\s+/g, ' ').trim(); + const sentenceMatch = collapsed.match(/^([^.!?]*[.!?])(?:\s|$)/); + // sentenceLead is the FULL first sentence (no truncation). We compute routing + // from this position, then optionally truncate the displayed lead afterwards. + // Truncating first then computing routing was the v1.45.0.0 bug — when the + // first sentence exceeded 200 chars, the routing extraction would lose the + // entire tail of the description (design-consultation's "Use when..." + // routing prose silently dropped). + const sentenceLead = sentenceMatch ? sentenceMatch[1].trim() : collapsed.split(/\s/).slice(0, 20).join(' '); + + // Routing prose: everything AFTER the first sentence boundary in the collapsed view. + const leadInCollapsed = collapsed.indexOf(sentenceLead); + const routingCollapsed = leadInCollapsed >= 0 + ? collapsed.slice(leadInCollapsed + sentenceLead.length).trim() + : ''; + + // Now produce the displayed lead — truncated if too long. The original + // sentenceLead is preserved for routing extraction below. + let lead = sentenceLead; + if (lead.length > 200) { + const trunc = lead.slice(0, 197); + const lastSpace = trunc.lastIndexOf(' '); + lead = (lastSpace > 60 ? trunc.slice(0, lastSpace) : trunc) + '...'; + } + // Restore line breaks for routing prose by mapping back to original layout. + // Use original whitespace structure where possible; fall back to collapsed. + // Anchor recovery on sentenceLead (the untruncated first sentence) — not + // `lead` (which may have a "..." suffix and won't substring-match `working`). + let routingProse = routingCollapsed; + const collapsedLeadIdx = working.replace(/\s+/g, ' ').indexOf(sentenceLead); + if (collapsedLeadIdx >= 0) { + let consumed = 0; + let cut = 0; + for (let i = 0; i < working.length && consumed < collapsedLeadIdx + sentenceLead.length; i++) { + if (/\s/.test(working[i])) { + if (i === 0 || /\s/.test(working[i - 1])) continue; + consumed += 1; + } else { + consumed += 1; + } + cut = i + 1; + } + const tail = working.slice(cut).trim(); + if (tail.length > 0) routingProse = tail; + } + + return { lead, routingProse, voiceLine, hasGstackTag }; +} + +/** Build the catalog-trimmed `description:` block. */ +export function buildTrimmedDescription(parts: CatalogParts): string { + const lead = parts.lead.trim(); + const suffix = parts.hasGstackTag ? ' (gstack)' : ''; + return `${lead}${suffix}`; +} + +/** Build the body section that holds the routing/voice prose. */ +export function buildWhenToInvokeSection(parts: CatalogParts): string { + const lines: string[] = ['## When to invoke this skill', '']; + if (parts.routingProse) { + lines.push(parts.routingProse); + lines.push(''); + } + if (parts.voiceLine) { + lines.push(parts.voiceLine); + lines.push(''); + } + return lines.join('\n'); +} + +/** + * Apply catalog trim to a SKILL.md body: + * - shorten frontmatter `description:` to lead + (gstack) + * - insert "## When to invoke" body section AFTER the generated header + * (so it lands near the top of body content, where routing guidance + * belongs) + * + * Returns the rewritten content plus the parts (used for proactive-suggestions + * JSON aggregation at the end of the run). + */ +export function applyCatalogTrim(content: string, skillName: string): { content: string; parts: CatalogParts } | null { + // Locate description block in frontmatter + if (!content.startsWith('---\n')) return null; + const fmEnd = content.indexOf('\n---', 4); + if (fmEnd === -1) return null; + const frontmatter = content.slice(4, fmEnd); + + // Match `description: |` block + indented body lines + const descMatch = frontmatter.match(/^description:\s*\|?\s*\n((?:\s{2,}.*(?:\n|$))+)/m) + || frontmatter.match(/^description:\s+(.+)$/m); + if (!descMatch) return null; + + // Extract full description text + let descText: string; + if (descMatch[0].startsWith('description: |') || /^description:\s*\|/.test(descMatch[0])) { + descText = descMatch[1].split('\n').map(l => l.replace(/^\s{2}/, '')).join('\n').trim(); + } else { + descText = descMatch[1].trim(); + } + + // Skip skills with very short descriptions (already trimmed or no routing prose). + // Below ~120 chars, splitting adds no value. + if (descText.length < 120) return null; + + const parts = splitCatalogDescription(descText); + // If lead + (gstack) is already most of the text, no trim needed. + const trimmedLen = buildTrimmedDescription(parts).length; + if (trimmedLen >= descText.length - 20) return null; + + // Replace description in frontmatter — keep trailing newline so the next + // YAML field doesn't collide on the same line as the description value. + const newDesc = buildTrimmedDescription(parts); + const newFrontmatter = frontmatter.replace(descMatch[0], `description: ${newDesc}\n`); + let newContent = '---\n' + newFrontmatter + content.slice(fmEnd); + + // Insert body section after frontmatter (after the closing ---\n and any + // existing GENERATED header). We insert before the first non-comment line. + const bodyStart = newContent.indexOf('\n---\n') + 5; + const whenToInvoke = '\n' + buildWhenToInvokeSection(parts).trim() + '\n'; + // Skip past the generated header if present (it lives after frontmatter close) + const headerMatch = newContent.slice(bodyStart).match(/^(\s*\n)+/); + const insertAt = bodyStart + (headerMatch ? headerMatch[0].length : 0); + newContent = newContent.slice(0, insertAt) + whenToInvoke + '\n' + newContent.slice(insertAt); + + return { content: newContent, parts }; +} + const OPENAI_SHORT_DESCRIPTION_LIMIT = 120; function condenseOpenAIShortDescription(description: string): string { @@ -401,7 +599,7 @@ function processExternalHost( return { content: result, outputPath, outputDir, symlinkLoop }; } -function processTemplate(tmplPath: string, host: Host = 'claude'): { outputPath: string; content: string; symlinkLoop?: boolean } { +function processTemplate(tmplPath: string, host: Host = 'claude'): { outputPath: string; content: string; symlinkLoop?: boolean; catalogParts?: CatalogParts | null } { const tmplContent = fs.readFileSync(tmplPath, 'utf-8'); const relTmplPath = path.relative(ROOT, tmplPath); let outputPath = tmplPath.replace(/\.tmpl$/, ''); @@ -430,7 +628,7 @@ function processTemplate(tmplPath: string, host: Host = 'claude'): { outputPath: const interactiveMatch = tmplContent.match(/^interactive:\s*(true|false)\s*$/m); const interactive = interactiveMatch ? interactiveMatch[1] === 'true' : undefined; - const ctx: TemplateContext = { skillName, tmplPath, benefitsFrom, host, paths: HOST_PATHS[host], preambleTier, model: MODEL_ARG_VAL, interactive }; + const ctx: TemplateContext = { skillName, tmplPath, benefitsFrom, host, paths: HOST_PATHS[host], preambleTier, model: MODEL_ARG_VAL, interactive, explainLevel: EXPLAIN_LEVEL }; // Replace placeholders (supports parameterized: {{NAME:arg1:arg2}}) // Config-driven: suppressedResolvers return empty string for this host @@ -441,9 +639,11 @@ function processTemplate(tmplPath: string, host: Host = 'claude'): { outputPath: const resolverName = parts[0]; const args = parts.slice(1); if (suppressed.has(resolverName)) return ''; - const resolver = RESOLVERS[resolverName]; - if (!resolver) throw new Error(`Unknown placeholder {{${resolverName}}} in ${relTmplPath}`); - return args.length > 0 ? resolver(ctx, args) : resolver(ctx); + const entry = RESOLVERS[resolverName]; + if (!entry) throw new Error(`Unknown placeholder {{${resolverName}}} in ${relTmplPath}`); + const { resolve, appliesTo } = unwrapResolver(entry); + if (appliesTo && !appliesTo(ctx)) return ''; + return args.length > 0 ? resolve(ctx, args) : resolve(ctx); }); // Check for any remaining unresolved placeholders @@ -483,7 +683,17 @@ function processTemplate(tmplPath: string, host: Host = 'claude'): { outputPath: content = header + content; } - return { outputPath, content, symlinkLoop }; + // Catalog trim (Claude only — external hosts have their own frontmatter shapes) + let catalogParts: CatalogParts | null = null; + if (host === 'claude' && CATALOG_MODE === 'trim') { + const trimmed = applyCatalogTrim(content, skillName); + if (trimmed) { + content = trimmed.content; + catalogParts = trimmed.parts; + } + } + + return { outputPath, content, symlinkLoop, catalogParts }; } // ─── Main ─────────────────────────────────────────────────── @@ -503,6 +713,14 @@ for (const currentHost of hostsToRun) { let hasChanges = false; const tokenBudget: Array<{ skill: string; lines: number; tokens: number }> = []; + // T4 catalog trim: collect routing/voice parts across all Claude skills, + // then write scripts/proactive-suggestions.json once per gen-skill-docs run. + const proactiveAggregate: Record = {}; + const currentHostConfig = getHostConfig(currentHost); for (const tmplPath of findTemplates()) { const dir = path.basename(path.dirname(tmplPath)); @@ -516,7 +734,24 @@ for (const currentHost of hostsToRun) { if (currentHostConfig.generation.skipSkills.includes(dir)) continue; } - const { outputPath, content, symlinkLoop } = processTemplate(tmplPath, currentHost); + const { outputPath, content, symlinkLoop, catalogParts } = processTemplate(tmplPath, currentHost); + if (catalogParts) { + // Root-skill detection: when the template lives at ROOT/SKILL.md.tmpl, + // path.basename(path.dirname(tmplPath)) returns the repo's directory + // name (e.g. "seville-v3" in a Conductor worktree, "gstack" on CI). + // That's non-deterministic across machines and breaks CI freshness + // checks. Use the frontmatter `name` field as the registry key — the + // root SKILL.md.tmpl declares `name: gstack` explicitly. For all other + // skills, `dir` matches the directory name which matches the + // frontmatter name by convention. + const isRoot = path.dirname(tmplPath) === ROOT; + const key = isRoot ? 'gstack' : dir; + proactiveAggregate[key] = { + lead: catalogParts.lead, + routing: catalogParts.routingProse, + voice_line: catalogParts.voiceLine, + }; + } const relOutput = path.relative(ROOT, outputPath); if (symlinkLoop) { @@ -620,6 +855,40 @@ The orchestrator will persist the plan link to its own memory/knowledge store. failures.push({ host: currentHost, error: new Error('Stale files detected') }); } + // T4 catalog trim: write aggregated proactive-suggestions.json (Claude only). + // The JSON registry lets agents pull voice triggers / routing prose for any + // skill on demand instead of paying for it always-loaded in the catalog. + // + // No timestamp field — keeps the file content-deterministic across runs so + // CI dry-run freshness checks don't flap on regen. If a per-run timestamp + // is ever needed for debugging, write it to a separate `.gen-stamp` file. + if (currentHost === 'claude' && CATALOG_MODE === 'trim' && Object.keys(proactiveAggregate).length > 0 && !DRY_RUN) { + const proactivePath = path.join(ROOT, 'scripts', 'proactive-suggestions.json'); + // Sort keys alphabetically so the serialized JSON is identical across + // machines regardless of filesystem-iteration order. Without this, CI + // freshness checks fail when the local dev machine and CI runner + // discover templates in different orders. + const sortedSkills: typeof proactiveAggregate = {}; + for (const key of Object.keys(proactiveAggregate).sort()) { + sortedSkills[key] = proactiveAggregate[key]; + } + const payload = { + $schema: 'https://gstack.dev/schemas/proactive-suggestions.json', + catalog_mode: 'trim', + note: 'Routing / voice-trigger prose extracted from SKILL.md frontmatter descriptions during catalog trim. Loaded on demand when routing guidance is needed.', + skills: sortedSkills, + }; + const serialized = JSON.stringify(payload, null, 2) + '\n'; + // Only write if content actually changed — prevents needless touches that + // would flap CI freshness checks. Read existing file, compare, skip write + // when identical. + let existing = ''; + try { existing = fs.readFileSync(proactivePath, 'utf-8'); } catch { /* first run */ } + if (existing !== serialized) { + fs.writeFileSync(proactivePath, serialized); + } + } + // Print token budget summary if (!DRY_RUN && tokenBudget.length > 0) { tokenBudget.sort((a, b) => b.lines - a.lines); diff --git a/scripts/proactive-suggestions.json b/scripts/proactive-suggestions.json new file mode 100644 index 000000000..6d4301fec --- /dev/null +++ b/scripts/proactive-suggestions.json @@ -0,0 +1,272 @@ +{ + "$schema": "https://gstack.dev/schemas/proactive-suggestions.json", + "catalog_mode": "trim", + "note": "Routing / voice-trigger prose extracted from SKILL.md frontmatter descriptions during catalog trim. Loaded on demand when routing guidance is needed.", + "skills": { + "autoplan": { + "lead": "Auto-review pipeline — reads the full CEO, design, eng, and DX review skills from disk and runs them sequentially with auto-decisions using 6 decision principles.", + "routing": "Surfaces\ntaste decisions (close approaches, borderline scope, codex disagreements) at a final\napproval gate. One command, fully reviewed plan out.\nUse when asked to \"auto review\", \"autoplan\", \"run all reviews\", \"review this plan\nautomatically\", or \"make the decisions for me\".\nProactively suggest when the user has a plan file and wants to run the full review\ngauntlet without answering 15-30 intermediate questions.", + "voice_line": "Voice triggers (speech-to-text aliases): \"auto plan\", \"automatic review\"." + }, + "benchmark": { + "lead": "Performance regression detection using the browse daemon.", + "routing": "Establishes\nbaselines for page load times, Core Web Vitals, and resource sizes.\nCompares before/after on every PR. Tracks performance trends over time.\nUse when: \"performance\", \"benchmark\", \"page speed\", \"lighthouse\", \"web vitals\",\n\"bundle size\", \"load time\".", + "voice_line": "Voice triggers (speech-to-text aliases): \"speed test\", \"check performance\"." + }, + "benchmark-models": { + "lead": "Cross-model benchmark for gstack skills.", + "routing": "Runs the same prompt through Claude,\nGPT (via Codex CLI), and Gemini side-by-side — compares latency, tokens, cost,\nand optionally quality via LLM judge. Answers \"which model is actually best\nfor this skill?\" with data instead of vibes. Separate from /benchmark, which\nmeasures web page performance. Use when: \"benchmark models\", \"compare models\",\n\"which model is best for X\", \"cross-model comparison\", \"model shootout\".", + "voice_line": "Voice triggers (speech-to-text aliases): \"compare models\", \"model shootout\", \"which model is best\"." + }, + "browse": { + "lead": "Fast headless browser for QA testing and site dogfooding.", + "routing": "Navigate any URL, interact with\nelements, verify page state, diff before/after actions, take annotated screenshots, check\nresponsive layouts, test forms and uploads, handle dialogs, and assert element states.\n~100ms per command. Use when you need to test a feature, verify a deployment, dogfood a\nuser flow, or file a bug with evidence. Use when asked to \"open in browser\", \"test the\nsite\", \"take a screenshot\", or \"dogfood this\".", + "voice_line": null + }, + "canary": { + "lead": "Post-deploy canary monitoring.", + "routing": "Watches the live app for console errors,\nperformance regressions, and page failures using the browse daemon. Takes\nperiodic screenshots, compares against pre-deploy baselines, and alerts\non anomalies. Use when: \"monitor deploy\", \"canary\", \"post-deploy check\",\n\"watch production\", \"verify deploy\".", + "voice_line": null + }, + "careful": { + "lead": "Safety guardrails for destructive commands.", + "routing": "Warns before rm -rf, DROP TABLE,\nforce-push, git reset --hard, kubectl delete, and similar destructive operations.\nUser can override each warning. Use when touching prod, debugging live systems,\nor working in a shared environment. Use when asked to \"be careful\", \"safety mode\",\n\"prod mode\", or \"careful mode\".", + "voice_line": null + }, + "codex": { + "lead": "OpenAI Codex CLI wrapper — three modes.", + "routing": "Code review: independent diff review via\ncodex review with pass/fail gate. Challenge: adversarial mode that tries to break\nyour code. Consult: ask codex anything with session continuity for follow-ups.\nThe \"200 IQ autistic developer\" second opinion. Use when asked to \"codex review\",\n\"codex challenge\", \"ask codex\", \"second opinion\", or \"consult codex\".", + "voice_line": "Voice triggers (speech-to-text aliases): \"code x\", \"code ex\", \"get another opinion\"." + }, + "context-restore": { + "lead": "Restore working context saved earlier by /context-save.", + "routing": "Loads the most recent\nsaved state (across all branches by default) so you can pick up where you\nleft off — even across Conductor workspace handoffs.\nUse when asked to \"resume\", \"restore context\", \"where was I\", or\n\"pick up where I left off\". Pair with /context-save.\nFormerly /checkpoint resume — renamed because Claude Code treats /checkpoint\nas a native rewind alias in current environments.", + "voice_line": null + }, + "context-save": { + "lead": "Save working context.", + "routing": "Captures git state, decisions made, and remaining work\nso any future session can pick up without losing a beat.\nUse when asked to \"save progress\", \"save state\", \"context save\", or\n\"save my work\". Pair with /context-restore to resume later.\nFormerly /checkpoint — renamed because Claude Code treats /checkpoint as a\nnative rewind alias in current environments, which was shadowing this skill.", + "voice_line": null + }, + "cso": { + "lead": "Chief Security Officer mode.", + "routing": "Infrastructure-first security audit: secrets archaeology,\ndependency supply chain, CI/CD pipeline security, LLM/AI security, skill supply chain\nscanning, plus OWASP Top 10, STRIDE threat modeling, and active verification.\nTwo modes: daily (zero-noise, 8/10 confidence gate) and comprehensive (monthly deep\nscan, 2/10 bar). Trend tracking across audit runs.\nUse when: \"security audit\", \"threat model\", \"pentest review\", \"OWASP\", \"CSO review\".", + "voice_line": "Voice triggers (speech-to-text aliases): \"see-so\", \"see so\", \"security review\", \"security check\", \"vulnerability scan\", \"run security\"." + }, + "design-consultation": { + "lead": "Design consultation: understands your product, researches the landscape, proposes a complete design system (aesthetic, typography, color, layout, spacing, motion), and generates font+color preview...", + "routing": "Creates DESIGN.md as your project's design source\nof truth. For existing sites, use /plan-design-review to infer the system instead.\nUse when asked to \"design system\", \"brand guidelines\", or \"create DESIGN.md\".\nProactively suggest when starting a new project's UI with no existing\ndesign system or DESIGN.md.", + "voice_line": null + }, + "design-html": { + "lead": "Design finalization: generates production-quality Pretext-native HTML/CSS.", + "routing": "Works with approved mockups from /design-shotgun, CEO plans from /plan-ceo-review,\ndesign review context from /plan-design-review, or from scratch with a user\ndescription. Text actually reflows, heights are computed, layouts are dynamic.\n30KB overhead, zero deps. Smart API routing: picks the right Pretext patterns\nfor each design type. Use when: \"finalize this design\", \"turn this into HTML\",\n\"build me a page\", \"implement this design\", or after any planning skill.\nProactively suggest when user has approved a design or has a plan ready.", + "voice_line": "Voice triggers (speech-to-text aliases): \"build the design\", \"code the mockup\", \"make it real\"." + }, + "design-review": { + "lead": "Designer's eye QA: finds visual inconsistency, spacing issues, hierarchy problems, AI slop patterns, and slow interactions — then fixes them.", + "routing": "Iteratively fixes issues\nin source code, committing each fix atomically and re-verifying with before/after\nscreenshots. For plan-mode design review (before implementation), use /plan-design-review.\nUse when asked to \"audit the design\", \"visual QA\", \"check if it looks good\", or \"design polish\".\nProactively suggest when the user mentions visual inconsistencies or\nwants to polish the look of a live site.", + "voice_line": null + }, + "design-shotgun": { + "lead": "Design shotgun: generate multiple AI design variants, open a comparison board, collect structured feedback, and iterate.", + "routing": "Standalone design exploration you can\nrun anytime. Use when: \"explore designs\", \"show me options\", \"design variants\",\n\"visual brainstorm\", or \"I don't like how this looks\".\nProactively suggest when the user describes a UI feature but hasn't seen\nwhat it could look like.", + "voice_line": null + }, + "devex-review": { + "lead": "Live developer experience audit.", + "routing": "Uses the browse tool to actually TEST the\ndeveloper experience: navigates docs, tries the getting started flow, times\nTTHW, screenshots error messages, evaluates CLI help text. Produces a DX\nscorecard with evidence. Compares against /plan-devex-review scores if they\nexist (the boomerang: plan said 3 minutes, reality says 8). Use when asked to\n\"test the DX\", \"DX audit\", \"developer experience test\", or \"try the\nonboarding\". Proactively suggest after shipping a developer-facing feature.", + "voice_line": "Voice triggers (speech-to-text aliases): \"dx audit\", \"test the developer experience\", \"try the onboarding\", \"developer experience test\"." + }, + "document-generate": { + "lead": "Generate missing documentation from scratch for a feature, module, or entire project.", + "routing": "Uses the Diataxis framework (tutorial / how-to / reference / explanation) to produce\ncomplete, structured documentation. Can be invoked standalone or called by\n/document-release when it finds coverage gaps. Use when asked to \"write docs\",\n\"generate documentation\", \"document this feature\", \"create a tutorial\", or\n\"explain this module\".", + "voice_line": null + }, + "document-release": { + "lead": "Post-ship documentation update.", + "routing": "Reads all project docs, cross-references the\ndiff, builds a Diataxis coverage map (reference/how-to/tutorial/explanation),\nupdates README/ARCHITECTURE/CONTRIBUTING/CLAUDE.md to match what shipped,\ndetects architecture diagram drift, polishes CHANGELOG voice with a sell-test\nrubric, cleans up TODOS, and optionally bumps VERSION. Surfaces documentation\ndebt in the PR body. Use when asked to \"update the docs\", \"sync documentation\",\nor \"post-ship docs\". Proactively suggest after a PR is merged or code is shipped.", + "voice_line": null + }, + "freeze": { + "lead": "Restrict file edits to a specific directory for the session.", + "routing": "Blocks Edit and\nWrite outside the allowed path. Use when debugging to prevent accidentally\n\"fixing\" unrelated code, or when you want to scope changes to one module.\nUse when asked to \"freeze\", \"restrict edits\", \"only edit this folder\",\nor \"lock down edits\".", + "voice_line": null + }, + "gstack": { + "lead": "Fast headless browser for QA testing and site dogfooding.", + "routing": "Navigate pages, interact with\nelements, verify state, diff before/after, take annotated screenshots, test responsive\nlayouts, forms, uploads, dialogs, and capture bug evidence. Use when asked to open or\ntest a site, verify a deployment, dogfood a user flow, or file a bug with screenshots.", + "voice_line": null + }, + "gstack-upgrade": { + "lead": "Upgrade gstack to the latest version.", + "routing": "Detects global vs vendored install,\nruns the upgrade, and shows what's new. Use when asked to \"upgrade gstack\",\n\"update gstack\", or \"get latest version\".", + "voice_line": "Voice triggers (speech-to-text aliases): \"upgrade the tools\", \"update the tools\", \"gee stack upgrade\", \"g stack upgrade\"." + }, + "guard": { + "lead": "Full safety mode: destructive command warnings + directory-scoped edits.", + "routing": "Combines /careful (warns before rm -rf, DROP TABLE, force-push, etc.) with\n/freeze (blocks edits outside a specified directory). Use for maximum safety\nwhen touching prod or debugging live systems. Use when asked to \"guard mode\",\n\"full safety\", \"lock it down\", or \"maximum safety\".", + "voice_line": null + }, + "health": { + "lead": "Code quality dashboard.", + "routing": "Wraps existing project tools (type checker, linter,\ntest runner, dead code detector, shell linter), computes a weighted composite\n0-10 score, and tracks trends over time. Use when: \"health check\",\n\"code quality\", \"how healthy is the codebase\", \"run all checks\",\n\"quality score\".", + "voice_line": null + }, + "investigate": { + "lead": "Systematic debugging with root cause investigation.", + "routing": "Four phases: investigate,\nanalyze, hypothesize, implement. Iron Law: no fixes without root cause.\nUse when asked to \"debug this\", \"fix this bug\", \"why is this broken\",\n\"investigate this error\", or \"root cause analysis\".\nProactively invoke this skill (do NOT debug directly) when the user reports\nerrors, 500 errors, stack traces, unexpected behavior, \"it was working\nyesterday\", or is troubleshooting why something stopped working.", + "voice_line": null + }, + "ios-clean": { + "lead": "Remove the DebugBridge SPM package and all #if DEBUG wiring from an iOS app.", + "routing": "Cleans up StateServer, DebugOverlay, accessor codegen output, and\napp-side hooks installed by /ios-qa. This is a convenience wrapper —\nthe structural Release-build guard (Package.swift conditional + CI\nswift build -c release check) is the safety-critical path.\nUse when asked to \"clean the iOS debug bridge\", \"remove DebugBridge\",\nor \"strip the gstack iOS instrumentation\".", + "voice_line": "Voice triggers (speech-to-text aliases): \"clean the iOS debug bridge\", \"remove DebugBridge\", \"strip the gstack iOS instrumentation\"." + }, + "ios-design-review": { + "lead": "Visual design audit for iOS apps on real hardware.", + "routing": "Connects to a real\niPhone via the same StateServer as /ios-qa, screenshots every screen,\nevaluates against Apple HIG, DESIGN.md, and design best practices. Scores\neach dimension 0-10 with \"what would make it a 10\" framing — mirrors\n/plan-design-review for browser. For plan-stage design review (before\nimplementation), use /plan-design-review. For live web visual audits, use\n/design-review.\nUse when asked to \"review the iOS design\", \"audit the iPhone app's\nvisuals\", or \"design QA the iOS app\".", + "voice_line": "Voice triggers (speech-to-text aliases): \"review the iOS design\", \"audit the iPhone app's visuals\", \"design QA the iPhone app\"." + }, + "ios-fix": { + "lead": "Autonomous iOS bug fixer.", + "routing": "Takes a bug found by /ios-qa, reads the source,\nwrites the fix, rebuilds, redeploys, and verifies the fix on the real\ndevice. Closes the loop: find bug → fix bug → confirm fix — zero human\nintervention. Captures the pre-bug state snapshot as a regression test\nfixture, so the bug can never recur silently.\nUse when /ios-qa reports a bug and you want it fixed automatically, or\nwhen asked to \"fix this iOS bug\", \"patch the iPhone app\", or \"auto-fix\nthe iOS issue\".", + "voice_line": "Voice triggers (speech-to-text aliases): \"fix the iOS bug\", \"patch the iPhone app\", \"auto-fix the iOS issue\"." + }, + "ios-qa": { + "lead": "Live-device iOS QA for SwiftUI apps.", + "routing": "Connects to a real iPhone via USB\nCoreDevice IPv6 tunnel, reads Swift source to understand every screen, then\nruns a vision-driven agent loop: screenshot → analyze → decide → act →\nverify → repeat. All interaction happens via HTTP to an embedded\nStateServer in the app under test. Optionally exposes the device over\nTailscale so remote agents (OpenClaw, Codex, any HTTP-capable agent) can\nrun iOS QA from anywhere without touching the hardware.\nUse when asked to \"ios qa\", \"test my iPhone app\", \"find bugs on the device\",\nor \"qa the iOS app\".", + "voice_line": "Voice triggers (speech-to-text aliases): \"iOS quality check\", \"test the iPhone app\", \"run iOS QA\"." + }, + "ios-sync": { + "lead": "Regenerate the iOS debug bridge against the latest upstream gstack templates.", + "routing": "Updates StateServer.swift, DebugOverlay.swift, Package.swift,\nand the typed @Observable state accessors. Use after you upgrade gstack\nor add new ViewModels/properties that need accessor coverage.\nUse when asked to \"resync the iOS debug bridge\", \"regenerate iOS\naccessors\", or \"update the gstack iOS instrumentation\".", + "voice_line": "Voice triggers (speech-to-text aliases): \"resync the iOS debug bridge\", \"regenerate iOS accessors\", \"update the gstack iOS instrumentation\"." + }, + "land-and-deploy": { + "lead": "Land and deploy workflow.", + "routing": "Merges the PR, waits for CI and deploy,\nverifies production health via canary checks. Takes over after /ship\ncreates the PR. Use when: \"merge\", \"land\", \"deploy\", \"merge and verify\",\n\"land it\", \"ship it to production\".", + "voice_line": null + }, + "landing-report": { + "lead": "Read-only queue dashboard for workspace-aware ship.", + "routing": "Shows which VERSION slots\nare currently claimed by open PRs, which sibling Conductor workspaces have\nWIP work likely to ship soon, and what slot /ship would pick next. No\nmutations — just a snapshot. Use when asked to \"landing report\", \"what's in\nthe queue\", \"show me open PRs\", or \"which version do I claim next\".", + "voice_line": null + }, + "learn": { + "lead": "Manage project learnings.", + "routing": "Review, search, prune, and export what gstack\nhas learned across sessions. Use when asked to \"what have we learned\",\n\"show learnings\", \"prune stale learnings\", or \"export learnings\".\nProactively suggest when the user asks about past patterns or wonders\n\"didn't we fix this before?\"", + "voice_line": null + }, + "make-pdf": { + "lead": "Turn any markdown file into a publication-quality PDF.", + "routing": "Proper 1in margins,\nintelligent page breaks, page numbers, cover pages, running headers, curly\nquotes and em dashes, clickable TOC, diagonal DRAFT watermark. Not a draft\nartifact — a finished artifact. Use when asked to \"make a PDF\", \"export to\nPDF\", \"turn this markdown into a PDF\", or \"generate a document\".", + "voice_line": "Voice triggers (speech-to-text aliases): \"make this a pdf\", \"make it a pdf\", \"export to pdf\", \"turn this into a pdf\", \"turn this markdown into a pdf\", \"generate a pdf\", \"make a pdf from\", \"pdf this markdown\"." + }, + "office-hours": { + "lead": "YC Office Hours — two modes.", + "routing": "Startup mode: six forcing questions that expose\ndemand reality, status quo, desperate specificity, narrowest wedge, observation,\nand future-fit. Builder mode: design thinking brainstorming for side projects,\nhackathons, learning, and open source. Saves a design doc.\nUse when asked to \"brainstorm this\", \"I have an idea\", \"help me think through\nthis\", \"office hours\", or \"is this worth building\".\nProactively invoke this skill (do NOT answer directly) when the user describes\na new product idea, asks whether something is worth building, wants to think\nthrough design decisions for something that doesn't exist yet, or is exploring\na concept before any code is written.\nUse before /plan-ceo-review or /plan-eng-review.", + "voice_line": null + }, + "open-gstack-browser": { + "lead": "Launch GStack Browser — AI-controlled Chromium with the sidebar extension baked in.", + "routing": "Opens a visible browser window where you can watch every action in real time.\nThe sidebar shows a live activity feed and chat. Anti-bot stealth built in.\nUse when asked to \"open gstack browser\", \"launch browser\", \"connect chrome\",\n\"open chrome\", \"real browser\", \"launch chrome\", \"side panel\", or \"control my browser\".", + "voice_line": "Voice triggers (speech-to-text aliases): \"show me the browser\"." + }, + "pair-agent": { + "lead": "Pair a remote AI agent with your browser.", + "routing": "One command generates a setup key and\nprints instructions the other agent can follow to connect. Works with OpenClaw,\nHermes, Codex, Cursor, or any agent that can make HTTP requests. The remote agent\ngets its own tab with scoped access (read+write by default, admin on request).\nUse when asked to \"pair agent\", \"connect agent\", \"share browser\", \"remote browser\",\n\"let another agent use my browser\", or \"give browser access\".", + "voice_line": "Voice triggers (speech-to-text aliases): \"pair agent\", \"connect agent\", \"share my browser\", \"remote browser access\"." + }, + "plan-ceo-review": { + "lead": "CEO/founder-mode plan review.", + "routing": "Rethink the problem, find the 10-star product,\nchallenge premises, expand scope when it creates a better product. Four modes:\nSCOPE EXPANSION (dream big), SELECTIVE EXPANSION (hold scope + cherry-pick\nexpansions), HOLD SCOPE (maximum rigor), SCOPE REDUCTION (strip to essentials).\nUse when asked to \"think bigger\", \"expand scope\", \"strategy review\", \"rethink this\",\nor \"is this ambitious enough\".\nProactively suggest when the user is questioning scope or ambition of a plan,\nor when the plan feels like it could be thinking bigger.", + "voice_line": null + }, + "plan-design-review": { + "lead": "Designer's eye plan review — interactive, like CEO and Eng review.", + "routing": "Rates each design dimension 0-10, explains what would make it a 10,\nthen fixes the plan to get there. Works in plan mode. For live site\nvisual audits, use /design-review. Use when asked to \"review the design plan\"\nor \"design critique\".\nProactively suggest when the user has a plan with UI/UX components that\nshould be reviewed before implementation.", + "voice_line": null + }, + "plan-devex-review": { + "lead": "Interactive developer experience plan review.", + "routing": "Explores developer personas,\nbenchmarks against competitors, designs magical moments, and traces friction\npoints before scoring. Three modes: DX EXPANSION (competitive advantage),\nDX POLISH (bulletproof every touchpoint), DX TRIAGE (critical gaps only).\nUse when asked to \"DX review\", \"developer experience audit\", \"devex review\",\nor \"API design review\".\nProactively suggest when the user has a plan for developer-facing products\n(APIs, CLIs, SDKs, libraries, platforms, docs).", + "voice_line": "Voice triggers (speech-to-text aliases): \"dx review\", \"developer experience review\", \"devex review\", \"devex audit\", \"API design review\", \"onboarding review\"." + }, + "plan-eng-review": { + "lead": "Eng manager-mode plan review.", + "routing": "Lock in the execution plan — architecture,\ndata flow, diagrams, edge cases, test coverage, performance. Walks through\nissues interactively with opinionated recommendations. Use when asked to\n\"review the architecture\", \"engineering review\", or \"lock in the plan\".\nProactively suggest when the user has a plan or design doc and is about to\nstart coding — to catch architecture issues before implementation.", + "voice_line": "Voice triggers (speech-to-text aliases): \"tech review\", \"technical review\", \"plan engineering review\"." + }, + "plan-tune": { + "lead": "Self-tuning question sensitivity + developer psychographic for gstack (v1: observational).", + "routing": "Review which AskUserQuestion prompts fire across gstack skills, set per-question preferences\n(never-ask / always-ask / ask-only-for-one-way), inspect the dual-track\nprofile (what you declared vs what your behavior suggests), and enable/disable\nquestion tuning. Conversational interface — no CLI syntax required.\n\nUse when asked to \"tune questions\", \"stop asking me that\", \"too many questions\",\n\"show my profile\", \"what questions have I been asked\", \"show my vibe\",\n\"developer profile\", or \"turn off question tuning\". \n\nProactively suggest when the user says the same gstack question has come up before,\nor when they explicitly override a recommendation for the Nth time.", + "voice_line": null + }, + "qa": { + "lead": "Systematically QA test a web application and fix bugs found.", + "routing": "Runs QA testing,\nthen iteratively fixes bugs in source code, committing each fix atomically and\nre-verifying. Use when asked to \"qa\", \"QA\", \"test this site\", \"find bugs\",\n\"test and fix\", or \"fix what's broken\".\nProactively suggest when the user says a feature is ready for testing\nor asks \"does this work?\". Three tiers: Quick (critical/high only),\nStandard (+ medium), Exhaustive (+ cosmetic). Produces before/after health scores,\nfix evidence, and a ship-readiness summary. For report-only mode, use /qa-only.", + "voice_line": "Voice triggers (speech-to-text aliases): \"quality check\", \"test the app\", \"run QA\"." + }, + "qa-only": { + "lead": "Report-only QA testing.", + "routing": "Systematically tests a web application and produces a\nstructured report with health score, screenshots, and repro steps — but never\nfixes anything. Use when asked to \"just report bugs\", \"qa report only\", or\n\"test but don't fix\". For the full test-fix-verify loop, use /qa instead.\nProactively suggest when the user wants a bug report without any code changes.", + "voice_line": "Voice triggers (speech-to-text aliases): \"bug report\", \"just check for bugs\"." + }, + "retro": { + "lead": "Weekly engineering retrospective.", + "routing": "Analyzes commit history, work patterns,\nand code quality metrics with persistent history and trend tracking.\nTeam-aware: breaks down per-person contributions with praise and growth areas.\nUse when asked to \"weekly retro\", \"what did we ship\", or \"engineering retrospective\".\nProactively suggest at the end of a work week or sprint.", + "voice_line": null + }, + "review": { + "lead": "Pre-landing PR review.", + "routing": "Analyzes diff against the base branch for SQL safety, LLM trust\nboundary violations, conditional side effects, and other structural issues. Use when\nasked to \"review this PR\", \"code review\", \"pre-landing review\", or \"check my diff\".\nProactively suggest when the user is about to merge or land code changes.", + "voice_line": null + }, + "scrape": { + "lead": "Pull data from a web page.", + "routing": "First call on a new intent prototypes the flow\nvia $B primitives and returns JSON. Subsequent calls on a matching intent\nroute to a codified browser-skill and return in ~200ms. Read-only — for\nmutating flows (form fills, clicks, submissions), use /automate.\nUse when asked to \"scrape\", \"get data from\", \"pull\", \"extract from\", or\n\"what's on\" a page.", + "voice_line": null + }, + "setup-browser-cookies": { + "lead": "Import cookies from your real Chromium browser into the headless browse session.", + "routing": "Opens an interactive picker UI where you select which cookie domains to import.\nUse before QA testing authenticated pages. Use when asked to \"import cookies\",\n\"login to the site\", or \"authenticate the browser\".", + "voice_line": null + }, + "setup-deploy": { + "lead": "Configure deployment settings for /land-and-deploy.", + "routing": "Detects your deploy\nplatform (Fly.io, Render, Vercel, Netlify, Heroku, GitHub Actions, custom),\nproduction URL, health check endpoints, and deploy status commands. Writes\nthe configuration to CLAUDE.md so all future deploys are automatic.\nUse when: \"setup deploy\", \"configure deployment\", \"set up land-and-deploy\",\n\"how do I deploy with gstack\", \"add deploy config\".", + "voice_line": null + }, + "setup-gbrain": { + "lead": "Set up gbrain for this coding agent: install the CLI, initialize a local PGLite or Supabase brain, register MCP, capture per-remote trust policy.", + "routing": "One command from zero to \"gbrain is running, and this agent\ncan call it.\" Use when: \"setup gbrain\", \"connect gbrain\", \"start\ngbrain\", \"install gbrain\", \"configure gbrain for this machine\".", + "voice_line": null + }, + "ship": { + "lead": "Ship workflow: detect + merge base branch, run tests, review diff, bump VERSION, update CHANGELOG, commit, push, create PR.", + "routing": "Use when asked to \"ship\", \"deploy\",\n\"push to main\", \"create a PR\", \"merge and push\", or \"get it deployed\".\nProactively invoke this skill (do NOT push/PR directly) when the user says code\nis ready, asks about deploying, wants to push code up, or asks to create a PR.", + "voice_line": null + }, + "skillify": { + "lead": "Codify the most recent successful /scrape flow into a permanent browser-skill on disk.", + "routing": "Future /scrape calls with the same intent run\nthe codified script in ~200ms instead of re-driving the page. Walks\nback through the conversation, synthesizes script.ts + script.test.ts\n+ fixture, runs the test in a temp dir, and asks before committing.\nUse when asked to \"skillify\", \"codify\", \"save this scrape\", or\n\"make this permanent\".", + "voice_line": null + }, + "spec": { + "lead": "Turn vague intent into a precise, executable spec in five phases.", + "routing": "Files the issue,\noptionally spawns a Claude Code agent in a fresh worktree, and lets /ship close\nthe source issue on merge. Use when asked to \"spec this out\", \"file an issue\",\n\"write up a ticket\", \"make this a GitHub issue\", or \"turn this into a backlog item\".", + "voice_line": null + }, + "sync-gbrain": { + "lead": "Keep gbrain current with this repo's code and refresh agent search guidance in CLAUDE.md. Wraps the gstack-gbrain-sync orchestrator with state", + "routing": "probing, native code-surface registration, capability checks,\nand a verdict block. Re-runnable, idempotent. Use when: \"sync gbrain\",\n\"refresh gbrain\", \"re-index this repo\", \"gbrain search isn't finding\nthings\".", + "voice_line": null + }, + "unfreeze": { + "lead": "Clear the freeze boundary set by /freeze, allowing edits to all directories again.", + "routing": "Use when you want to widen edit scope without ending the session.\nUse when asked to \"unfreeze\", \"unlock edits\", \"remove freeze\", or\n\"allow all edits\".", + "voice_line": null + } + } +} diff --git a/scripts/resolvers/index.ts b/scripts/resolvers/index.ts index c5cbd0445..6502960f9 100644 --- a/scripts/resolvers/index.ts +++ b/scripts/resolvers/index.ts @@ -1,9 +1,20 @@ /** - * RESOLVERS record — maps {{PLACEHOLDER}} names to generator functions. + * RESOLVERS record — maps {{PLACEHOLDER}} names to generator functions + * or gated entries. + * * Each resolver takes a TemplateContext and returns the replacement string. + * Resolvers may be either a bare function (always fires) or a gated entry + * ({ resolve, appliesTo }) where appliesTo can return false to skip the + * resolver for a given skill. See ./types.ts: ResolverEntry. + * + * Most resolvers don't need a gate — the {{NAME}} placeholder system is + * already conditional at the template level (the resolver only fires for + * skills that reference it). Use a gate when you want a structural + * guardrail that says "this placeholder is meaningful only in skills X, Y, Z" + * even if someone later adds {{NAME}} to skill W. */ -import type { TemplateContext, ResolverFn } from './types'; +import type { TemplateContext, ResolverFn, ResolverValue } from './types'; // Domain modules import { generatePreamble } from './preamble'; @@ -24,7 +35,7 @@ import { generateQuestionPreferenceCheck, generateQuestionLog, generateInlineTun import { generateMakePdfSetup } from './make-pdf'; import { generateTasksSectionEmit, generateTasksSectionAggregate } from './tasks-section'; -export const RESOLVERS: Record = { +export const RESOLVERS: Record = { SLUG_EVAL: generateSlugEval, SLUG_SETUP: generateSlugSetup, COMMAND_REFERENCE: generateCommandReference, diff --git a/scripts/resolvers/preamble.ts b/scripts/resolvers/preamble.ts index 97698bfcf..cc3045174 100644 --- a/scripts/resolvers/preamble.ts +++ b/scripts/resolvers/preamble.ts @@ -109,10 +109,10 @@ export function generatePreamble(ctx: TemplateContext): string { ...(tier >= 2 ? [ generateContextRecovery(ctx), generateWritingStyle(ctx), - generateCompletenessSection(), - generateConfusionProtocol(), + generateCompletenessSection(ctx), + generateConfusionProtocol(ctx), generateContinuousCheckpoint(), - generateContextHealth(), + generateContextHealth(ctx), generateQuestionTuning(ctx), ] : []), ...(tier >= 3 ? [generateRepoModeSection(), generateSearchBeforeBuildingSection(ctx)] : []), diff --git a/scripts/resolvers/preamble/generate-completeness-section.ts b/scripts/resolvers/preamble/generate-completeness-section.ts index e64dc0cd1..ba9a874bd 100644 --- a/scripts/resolvers/preamble/generate-completeness-section.ts +++ b/scripts/resolvers/preamble/generate-completeness-section.ts @@ -1,6 +1,7 @@ +import type { TemplateContext } from '../types'; - -export function generateCompletenessSection(): string { +export function generateCompletenessSection(ctx?: TemplateContext): string { + if (ctx?.explainLevel === 'terse') return ''; return `## Completeness Principle — Boil the Lake AI makes completeness cheap. Recommend complete lakes (tests, edge cases, error paths); flag oceans (rewrites, multi-quarter migrations). diff --git a/scripts/resolvers/preamble/generate-confusion-protocol.ts b/scripts/resolvers/preamble/generate-confusion-protocol.ts index eb3e820fd..fcbecb75b 100644 --- a/scripts/resolvers/preamble/generate-confusion-protocol.ts +++ b/scripts/resolvers/preamble/generate-confusion-protocol.ts @@ -1,4 +1,7 @@ -export function generateConfusionProtocol(): string { +import type { TemplateContext } from '../types'; + +export function generateConfusionProtocol(ctx?: TemplateContext): string { + if (ctx?.explainLevel === 'terse') return ''; return `## Confusion Protocol For high-stakes ambiguity (architecture, data model, destructive scope, missing context), STOP. Name it in one sentence, present 2-3 options with tradeoffs, and ask. Do not use for routine coding or obvious changes.`; diff --git a/scripts/resolvers/preamble/generate-context-health.ts b/scripts/resolvers/preamble/generate-context-health.ts index 019d200d3..88b058406 100644 --- a/scripts/resolvers/preamble/generate-context-health.ts +++ b/scripts/resolvers/preamble/generate-context-health.ts @@ -1,6 +1,7 @@ +import type { TemplateContext } from '../types'; - -export function generateContextHealth(): string { +export function generateContextHealth(ctx?: TemplateContext): string { + if (ctx?.explainLevel === 'terse') return ''; return `## Context Health (soft directive) During long-running skill sessions, periodically write a brief \`[PROGRESS]\` summary: done, next, surprises. diff --git a/scripts/resolvers/preamble/generate-preamble-bash.ts b/scripts/resolvers/preamble/generate-preamble-bash.ts index 18b6cca5d..2bf5fc182 100644 --- a/scripts/resolvers/preamble/generate-preamble-bash.ts +++ b/scripts/resolvers/preamble/generate-preamble-bash.ts @@ -90,6 +90,19 @@ _CHECKPOINT_MODE=$(${ctx.paths.binDir}/gstack-config get checkpoint_mode 2>/dev/ _CHECKPOINT_PUSH=$(${ctx.paths.binDir}/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "\${CLAUDE_PLAN_FILE:-}\${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "\${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true${ctx.host === 'gbrain' || ctx.host === 'hermes' ? ` if command -v gbrain &>/dev/null; then _BRAIN_JSON=$(gbrain doctor --fast --json 2>/dev/null || echo '{}') diff --git a/scripts/resolvers/preamble/generate-routing-injection.ts b/scripts/resolvers/preamble/generate-routing-injection.ts index 9fe0d070e..cea16d8ad 100644 --- a/scripts/resolvers/preamble/generate-routing-injection.ts +++ b/scripts/resolvers/preamble/generate-routing-injection.ts @@ -33,6 +33,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec \`\`\` Then commit the change: \`git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"\` diff --git a/scripts/resolvers/preamble/generate-writing-style.ts b/scripts/resolvers/preamble/generate-writing-style.ts index 02701943c..812571ce2 100644 --- a/scripts/resolvers/preamble/generate-writing-style.ts +++ b/scripts/resolvers/preamble/generate-writing-style.ts @@ -1,25 +1,24 @@ -import * as fs from 'fs'; -import * as path from 'path'; import type { TemplateContext } from '../types'; -function loadJargonList(): string[] { - const jargonPath = path.join(__dirname, '..', '..', 'jargon-list.json'); - try { - const raw = fs.readFileSync(jargonPath, 'utf-8'); - const data = JSON.parse(raw); - if (Array.isArray(data?.terms)) return data.terms.filter((t: unknown): t is string => typeof t === 'string'); - } catch { - // Missing or malformed: fall back to empty list. Writing Style block still fires, - // but with no terms to gloss — graceful degradation. +/** + * Writing Style preamble section. + * + * v1.45.0.0 changes (T3): + * - Jargon list is referenced by path, not inlined. The 80-term list was + * duplicated into every tier-2+ skill (~1.5-2 KB × 48 skills = ~80 KB + * across the corpus). The pointer asks the agent to Read the JSON on + * first jargon term encountered — one extra Read per session, but the + * per-corpus payload is ~30 bytes. + * - When `ctx.explainLevel === 'terse'`, the entire section is replaced + * with a one-line pointer. Saves ~1.5 KB per tier-2+ skill in the + * opt-in terse build. + */ +export function generateWritingStyle(ctx: TemplateContext): string { + if (ctx.explainLevel === 'terse') { + return `## Writing Style\n\nTerse mode (build-time): skip jargon glossing, outcome-framing layer, and decision-impact closers. Lead with the answer.\n`; } - return []; -} -export function generateWritingStyle(_ctx: TemplateContext): string { - const terms = loadJargonList(); - const jargonBlock = terms.length > 0 - ? `Jargon list, gloss on first use if the term appears:\n${terms.map(t => `- ${t}`).join('\n')}` - : `Jargon list unavailable. Skip jargon glossing until \`scripts/jargon-list.json\` is restored.`; + const jargonPath = `${ctx.paths.skillRoot}/scripts/jargon-list.json`; return `## Writing Style (skip entirely if \`EXPLAIN_LEVEL: terse\` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output) @@ -32,6 +31,6 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i - User-turn override wins: if the current message asks for terse / no explanations / just the answer, skip this section. - Terse mode (EXPLAIN_LEVEL: terse): no glosses, no outcome-framing layer, shorter responses. -${jargonBlock} +Curated jargon list lives at \`${jargonPath}\` (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. `; } diff --git a/scripts/resolvers/types.ts b/scripts/resolvers/types.ts index c8a44425b..40afed160 100644 --- a/scripts/resolvers/types.ts +++ b/scripts/resolvers/types.ts @@ -62,7 +62,56 @@ export interface TemplateContext { preambleTier?: number; // 1-4, controls which preamble sections are included model?: Model; // model family for behavioral overlay. Omitted/undefined → no overlay. interactive?: boolean; // true → emit plan-mode handshake in preamble. Generator-only, not written to SKILL.md. + /** + * Build-time compression mode. Defaults to 'default'. + * + * - 'default': full preamble prose ships as today (writing style, completeness, + * confusion protocol, context health are all present). + * - 'terse': writing-style + completeness + confusion-protocol + context-health + * sections are compressed to a one-line pointer at gen time. Saves ~3-5 KB + * per tier-2+ skill. Opt-in via `--explain-level=terse` build flag for + * users who want shipped skills to match their runtime preference and + * avoid the per-session terse-mode prose. + * + * Default builds keep the runtime-conditional behavior intact (Writing Style + * section says "skip entirely if EXPLAIN_LEVEL: terse appears in preamble echo"). + * Terse builds make the compression structural — bytes never ship in the first place. + */ + explainLevel?: 'default' | 'terse'; } /** Resolver function signature. args is populated for parameterized placeholders like {{INVOKE_SKILL:name}}. */ export type ResolverFn = (ctx: TemplateContext, args?: string[]) => string; + +/** + * Optional gated resolver. When the gate returns false, the resolver is + * skipped (substituted with empty string) — same effect as the placeholder + * not being referenced. Use when a resolver's output is only meaningful for + * a known subset of skills, so future template authors get a structural + * guardrail instead of relying on social knowledge. + * + * Most resolvers don't need this — the {{NAME}} placeholder system is + * already conditional at the template level. Use only when a resolver + * lives inside another resolver (e.g. via preamble composition) AND must + * be conditionalized, or when a top-level resolver has a small, well-defined + * audience. + */ +export interface ResolverEntry { + resolve: ResolverFn; + appliesTo?: (ctx: TemplateContext) => boolean; +} + +/** Anything the RESOLVERS map accepts — either a bare function or a gated entry. */ +export type ResolverValue = ResolverFn | ResolverEntry; + +/** + * Type-narrowing helper for the gen-skill-docs lookup. + * Returns (resolverFn, gate) so callers can do gate?.(ctx) before invoking. + */ +export function unwrapResolver(entry: ResolverValue): { + resolve: ResolverFn; + appliesTo?: (ctx: TemplateContext) => boolean; +} { + if (typeof entry === 'function') return { resolve: entry }; + return { resolve: entry.resolve, appliesTo: entry.appliesTo }; +} diff --git a/setup-browser-cookies/SKILL.md b/setup-browser-cookies/SKILL.md index 8b80fd58b..2f91f4d68 100644 --- a/setup-browser-cookies/SKILL.md +++ b/setup-browser-cookies/SKILL.md @@ -2,11 +2,7 @@ name: setup-browser-cookies preamble-tier: 1 version: 1.0.0 -description: | - Import cookies from your real Chromium browser into the headless browse session. - Opens an interactive picker UI where you select which cookie domains to import. - Use before QA testing authenticated pages. Use when asked to "import cookies", - "login to the site", or "authenticate the browser". (gstack) +description: Import cookies from your real Chromium browser into the headless browse session. (gstack) triggers: - import browser cookies - login to test site @@ -19,6 +15,13 @@ allowed-tools: + +## When to invoke this skill + +Opens an interactive picker UI where you select which cookie domains to import. +Use before QA testing authenticated pages. Use when asked to "import cookies", +"login to the site", or "authenticate the browser". + ## Preamble (run first) ```bash @@ -96,6 +99,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -227,6 +243,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` diff --git a/setup-deploy/SKILL.md b/setup-deploy/SKILL.md index 0bed79734..3e69b015d 100644 --- a/setup-deploy/SKILL.md +++ b/setup-deploy/SKILL.md @@ -2,13 +2,7 @@ name: setup-deploy preamble-tier: 2 version: 1.0.0 -description: | - Configure deployment settings for /land-and-deploy. Detects your deploy - platform (Fly.io, Render, Vercel, Netlify, Heroku, GitHub Actions, custom), - production URL, health check endpoints, and deploy status commands. Writes - the configuration to CLAUDE.md so all future deploys are automatic. - Use when: "setup deploy", "configure deployment", "set up land-and-deploy", - "how do I deploy with gstack", "add deploy config". +description: Configure deployment settings for /land-and-deploy. triggers: - configure deploy - setup deployment @@ -25,6 +19,16 @@ allowed-tools: + +## When to invoke this skill + +Detects your deploy +platform (Fly.io, Render, Vercel, Netlify, Heroku, GitHub Actions, custom), +production URL, health check endpoints, and deploy status commands. Writes +the configuration to CLAUDE.md so all future deploys are automatic. +Use when: "setup deploy", "configure deployment", "set up land-and-deploy", +"how do I deploy with gstack", "add deploy config". + ## Preamble (run first) ```bash @@ -102,6 +106,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -233,6 +250,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` @@ -583,84 +601,7 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i - User-turn override wins: if the current message asks for terse / no explanations / just the answer, skip this section. - Terse mode (EXPLAIN_LEVEL: terse): no glosses, no outcome-framing layer, shorter responses. -Jargon list, gloss on first use if the term appears: -- idempotent -- idempotency -- race condition -- deadlock -- cyclomatic complexity -- N+1 -- N+1 query -- backpressure -- memoization -- eventual consistency -- CAP theorem -- CORS -- CSRF -- XSS -- SQL injection -- prompt injection -- DDoS -- rate limit -- throttle -- circuit breaker -- load balancer -- reverse proxy -- SSR -- CSR -- hydration -- tree-shaking -- bundle splitting -- code splitting -- hot reload -- tombstone -- soft delete -- cascade delete -- foreign key -- composite index -- covering index -- OLTP -- OLAP -- sharding -- replication lag -- quorum -- two-phase commit -- saga -- outbox pattern -- inbox pattern -- optimistic locking -- pessimistic locking -- thundering herd -- cache stampede -- bloom filter -- consistent hashing -- virtual DOM -- reconciliation -- closure -- hoisting -- tail call -- GIL -- zero-copy -- mmap -- cold start -- warm start -- green-blue deploy -- canary deploy -- feature flag -- kill switch -- dead letter queue -- fan-out -- fan-in -- debounce -- throttle (UI) -- hydration mismatch -- memory leak -- GC pause -- heap fragmentation -- stack overflow -- null pointer -- dangling pointer -- buffer overflow +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 Lake diff --git a/setup-gbrain/SKILL.md b/setup-gbrain/SKILL.md index 861e4e7b9..12d8e2ce1 100644 --- a/setup-gbrain/SKILL.md +++ b/setup-gbrain/SKILL.md @@ -2,12 +2,7 @@ name: setup-gbrain preamble-tier: 2 version: 1.0.0 -description: | - Set up gbrain for this coding agent: install the CLI, initialize a - local PGLite or Supabase brain, register MCP, capture per-remote trust - policy. One command from zero to "gbrain is running, and this agent - can call it." Use when: "setup gbrain", "connect gbrain", "start - gbrain", "install gbrain", "configure gbrain for this machine". (gstack) +description: Set up gbrain for this coding agent: install the CLI, initialize a local PGLite or Supabase brain, register MCP, capture per-remote trust policy. (gstack) triggers: - setup gbrain - install gbrain @@ -26,6 +21,13 @@ allowed-tools: + +## When to invoke this skill + +One command from zero to "gbrain is running, and this agent +can call it." Use when: "setup gbrain", "connect gbrain", "start +gbrain", "install gbrain", "configure gbrain for this machine". + ## Preamble (run first) ```bash @@ -103,6 +105,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -234,6 +249,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` @@ -584,84 +600,7 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i - User-turn override wins: if the current message asks for terse / no explanations / just the answer, skip this section. - Terse mode (EXPLAIN_LEVEL: terse): no glosses, no outcome-framing layer, shorter responses. -Jargon list, gloss on first use if the term appears: -- idempotent -- idempotency -- race condition -- deadlock -- cyclomatic complexity -- N+1 -- N+1 query -- backpressure -- memoization -- eventual consistency -- CAP theorem -- CORS -- CSRF -- XSS -- SQL injection -- prompt injection -- DDoS -- rate limit -- throttle -- circuit breaker -- load balancer -- reverse proxy -- SSR -- CSR -- hydration -- tree-shaking -- bundle splitting -- code splitting -- hot reload -- tombstone -- soft delete -- cascade delete -- foreign key -- composite index -- covering index -- OLTP -- OLAP -- sharding -- replication lag -- quorum -- two-phase commit -- saga -- outbox pattern -- inbox pattern -- optimistic locking -- pessimistic locking -- thundering herd -- cache stampede -- bloom filter -- consistent hashing -- virtual DOM -- reconciliation -- closure -- hoisting -- tail call -- GIL -- zero-copy -- mmap -- cold start -- warm start -- green-blue deploy -- canary deploy -- feature flag -- kill switch -- dead letter queue -- fan-out -- fan-in -- debounce -- throttle (UI) -- hydration mismatch -- memory leak -- GC pause -- heap fragmentation -- stack overflow -- null pointer -- dangling pointer -- buffer overflow +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 Lake diff --git a/ship/SKILL.md b/ship/SKILL.md index 45898d4fc..9611072f7 100644 --- a/ship/SKILL.md +++ b/ship/SKILL.md @@ -2,12 +2,7 @@ name: ship preamble-tier: 4 version: 1.0.0 -description: | - Ship workflow: detect + merge base branch, run tests, review diff, bump VERSION, - update CHANGELOG, commit, push, create PR. Use when asked to "ship", "deploy", - "push to main", "create a PR", "merge and push", or "get it deployed". - Proactively invoke this skill (do NOT push/PR directly) when the user says code - is ready, asks about deploying, wants to push code up, or asks to create a PR. (gstack) +description: Ship workflow: detect + merge base branch, run tests, review diff, bump VERSION, update CHANGELOG, commit, push, create PR. (gstack) allowed-tools: - Bash - Read @@ -27,6 +22,14 @@ triggers: + +## When to invoke this skill + +Use when asked to "ship", "deploy", +"push to main", "create a PR", "merge and push", or "get it deployed". +Proactively invoke this skill (do NOT push/PR directly) when the user says code +is ready, asks about deploying, wants to push code up, or asks to create a PR. + ## Preamble (run first) ```bash @@ -104,6 +107,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -235,6 +251,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` @@ -585,84 +602,7 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i - User-turn override wins: if the current message asks for terse / no explanations / just the answer, skip this section. - Terse mode (EXPLAIN_LEVEL: terse): no glosses, no outcome-framing layer, shorter responses. -Jargon list, gloss on first use if the term appears: -- idempotent -- idempotency -- race condition -- deadlock -- cyclomatic complexity -- N+1 -- N+1 query -- backpressure -- memoization -- eventual consistency -- CAP theorem -- CORS -- CSRF -- XSS -- SQL injection -- prompt injection -- DDoS -- rate limit -- throttle -- circuit breaker -- load balancer -- reverse proxy -- SSR -- CSR -- hydration -- tree-shaking -- bundle splitting -- code splitting -- hot reload -- tombstone -- soft delete -- cascade delete -- foreign key -- composite index -- covering index -- OLTP -- OLAP -- sharding -- replication lag -- quorum -- two-phase commit -- saga -- outbox pattern -- inbox pattern -- optimistic locking -- pessimistic locking -- thundering herd -- cache stampede -- bloom filter -- consistent hashing -- virtual DOM -- reconciliation -- closure -- hoisting -- tail call -- GIL -- zero-copy -- mmap -- cold start -- warm start -- green-blue deploy -- canary deploy -- feature flag -- kill switch -- dead letter queue -- fan-out -- fan-in -- debounce -- throttle (UI) -- hydration mismatch -- memory leak -- GC pause -- heap fragmentation -- stack overflow -- null pointer -- dangling pointer -- buffer overflow +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 Lake @@ -3032,6 +2972,39 @@ you missed it.> +## Linked Spec +-$$, the spawned worktree IS where /ship runs). + SPEC_FILE=$(grep -l "^spec_branch: $CURRENT_BRANCH$" "$SPEC_ARCHIVES"/*.md 2>/dev/null | head -1) + [ -z "$SPEC_FILE" ] && exit # no spec; omit this section entirely + SPEC_ISSUE=$(grep "^spec_issue_number:" "$SPEC_FILE" | cut -d' ' -f2) + [ -z "$SPEC_ISSUE" ] && exit # spec archive exists but no issue number; omit + + # CONDITIONAL Closes #N (codex F4): only add when Plan Completion above is "complete". + # If the plan completion gate from Step 8 reports any deferred or failed items, emit: + # "Linked to #$SPEC_ISSUE (partial delivery — NOT auto-closing; close manually after follow-up)" + # If Plan Completion is fully complete, emit: + # "Closes #$SPEC_ISSUE" + # and include the Closes #N line in the PR body so GitHub auto-closes on merge.> + + + + This PR delivers the spec at . + Spec filed: > + + (partial delivery — not auto-closing). + Deferred items: . + Close # manually after follow-up lands.> + + + ## Verification Results diff --git a/ship/SKILL.md.tmpl b/ship/SKILL.md.tmpl index 5a7c34661..304bd6a1d 100644 --- a/ship/SKILL.md.tmpl +++ b/ship/SKILL.md.tmpl @@ -865,6 +865,39 @@ you missed it.> +## Linked Spec +-$$, the spawned worktree IS where /ship runs). + SPEC_FILE=$(grep -l "^spec_branch: $CURRENT_BRANCH$" "$SPEC_ARCHIVES"/*.md 2>/dev/null | head -1) + [ -z "$SPEC_FILE" ] && exit # no spec; omit this section entirely + SPEC_ISSUE=$(grep "^spec_issue_number:" "$SPEC_FILE" | cut -d' ' -f2) + [ -z "$SPEC_ISSUE" ] && exit # spec archive exists but no issue number; omit + + # CONDITIONAL Closes #N (codex F4): only add when Plan Completion above is "complete". + # If the plan completion gate from Step 8 reports any deferred or failed items, emit: + # "Linked to #$SPEC_ISSUE (partial delivery — NOT auto-closing; close manually after follow-up)" + # If Plan Completion is fully complete, emit: + # "Closes #$SPEC_ISSUE" + # and include the Closes #N line in the PR body so GitHub auto-closes on merge.> + + + + This PR delivers the spec at . + Spec filed: > + + (partial delivery — not auto-closing). + Deferred items: . + Close # manually after follow-up lands.> + + + ## Verification Results diff --git a/skillify/SKILL.md b/skillify/SKILL.md index 47a7e61da..8b81f1ce8 100644 --- a/skillify/SKILL.md +++ b/skillify/SKILL.md @@ -1,14 +1,7 @@ --- name: skillify version: 1.0.0 -description: | - Codify the most recent successful /scrape flow into a permanent - browser-skill on disk. Future /scrape calls with the same intent run - the codified script in ~200ms instead of re-driving the page. Walks - back through the conversation, synthesizes script.ts + script.test.ts - + fixture, runs the test in a temp dir, and asks before committing. - Use when asked to "skillify", "codify", "save this scrape", or - "make this permanent". (gstack) +description: Codify the most recent successful /scrape flow into a permanent browser-skill on disk. (gstack) allowed-tools: - Bash - Read @@ -23,6 +16,16 @@ triggers: + +## When to invoke this skill + +Future /scrape calls with the same intent run +the codified script in ~200ms instead of re-driving the page. Walks +back through the conversation, synthesizes script.ts + script.test.ts ++ fixture, runs the test in a temp dir, and asks before committing. +Use when asked to "skillify", "codify", "save this scrape", or +"make this permanent". + ## Preamble (run first) ```bash @@ -100,6 +103,19 @@ _CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode _CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" [ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true ``` @@ -231,6 +247,7 @@ Key routing rules: - Ship/deploy/PR → invoke /ship or /land-and-deploy - Save progress → invoke /context-save - Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec ``` Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` @@ -581,84 +598,7 @@ Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format i - User-turn override wins: if the current message asks for terse / no explanations / just the answer, skip this section. - Terse mode (EXPLAIN_LEVEL: terse): no glosses, no outcome-framing layer, shorter responses. -Jargon list, gloss on first use if the term appears: -- idempotent -- idempotency -- race condition -- deadlock -- cyclomatic complexity -- N+1 -- N+1 query -- backpressure -- memoization -- eventual consistency -- CAP theorem -- CORS -- CSRF -- XSS -- SQL injection -- prompt injection -- DDoS -- rate limit -- throttle -- circuit breaker -- load balancer -- reverse proxy -- SSR -- CSR -- hydration -- tree-shaking -- bundle splitting -- code splitting -- hot reload -- tombstone -- soft delete -- cascade delete -- foreign key -- composite index -- covering index -- OLTP -- OLAP -- sharding -- replication lag -- quorum -- two-phase commit -- saga -- outbox pattern -- inbox pattern -- optimistic locking -- pessimistic locking -- thundering herd -- cache stampede -- bloom filter -- consistent hashing -- virtual DOM -- reconciliation -- closure -- hoisting -- tail call -- GIL -- zero-copy -- mmap -- cold start -- warm start -- green-blue deploy -- canary deploy -- feature flag -- kill switch -- dead letter queue -- fan-out -- fan-in -- debounce -- throttle (UI) -- hydration mismatch -- memory leak -- GC pause -- heap fragmentation -- stack overflow -- null pointer -- dangling pointer -- buffer overflow +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 Lake diff --git a/spec/SKILL.md b/spec/SKILL.md new file mode 100644 index 000000000..a125a8792 --- /dev/null +++ b/spec/SKILL.md @@ -0,0 +1,2076 @@ +--- +name: spec +version: 0.1.0 +description: Turn vague intent into a precise, executable spec in five phases. (gstack) +allowed-tools: + - Bash + - Read + - Grep + - Glob + - AskUserQuestion +triggers: + - spec this out + - file an issue + - write up a ticket + - turn this into an issue + - make this a github issue + - turn this into a backlog item +--- + + + + +## When to invoke this skill + +Files the issue, +optionally spawns a Claude Code agent in a fresh worktree, and lets /ship close +the source issue on merge. Use when asked to "spec this out", "file an issue", +"write up a ticket", "make this a GitHub issue", or "turn this into a backlog item". + +## Preamble (run first) + +```bash +_UPD=$(~/.claude/skills/gstack/bin/gstack-update-check 2>/dev/null || .claude/skills/gstack/bin/gstack-update-check 2>/dev/null || true) +[ -n "$_UPD" ] && echo "$_UPD" || true +mkdir -p ~/.gstack/sessions +touch ~/.gstack/sessions/"$PPID" +_SESSIONS=$(find ~/.gstack/sessions -mmin -120 -type f 2>/dev/null | wc -l | tr -d ' ') +find ~/.gstack/sessions -mmin +120 -type f -exec rm {} + 2>/dev/null || true +_PROACTIVE=$(~/.claude/skills/gstack/bin/gstack-config get proactive 2>/dev/null || echo "true") +_PROACTIVE_PROMPTED=$([ -f ~/.gstack/.proactive-prompted ] && echo "yes" || echo "no") +_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown") +echo "BRANCH: $_BRANCH" +_SKILL_PREFIX=$(~/.claude/skills/gstack/bin/gstack-config get skill_prefix 2>/dev/null || echo "false") +echo "PROACTIVE: $_PROACTIVE" +echo "PROACTIVE_PROMPTED: $_PROACTIVE_PROMPTED" +echo "SKILL_PREFIX: $_SKILL_PREFIX" +source <(~/.claude/skills/gstack/bin/gstack-repo-mode 2>/dev/null) || true +REPO_MODE=${REPO_MODE:-unknown} +echo "REPO_MODE: $REPO_MODE" +_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) +_TEL_PROMPTED=$([ -f ~/.gstack/.telemetry-prompted ] && echo "yes" || echo "no") +_TEL_START=$(date +%s) +_SESSION_ID="$$-$(date +%s)" +echo "TELEMETRY: ${_TEL:-off}" +echo "TEL_PROMPTED: $_TEL_PROMPTED" +_EXPLAIN_LEVEL=$(~/.claude/skills/gstack/bin/gstack-config get explain_level 2>/dev/null || echo "default") +if [ "$_EXPLAIN_LEVEL" != "default" ] && [ "$_EXPLAIN_LEVEL" != "terse" ]; then _EXPLAIN_LEVEL="default"; fi +echo "EXPLAIN_LEVEL: $_EXPLAIN_LEVEL" +_QUESTION_TUNING=$(~/.claude/skills/gstack/bin/gstack-config get question_tuning 2>/dev/null || echo "false") +echo "QUESTION_TUNING: $_QUESTION_TUNING" +mkdir -p ~/.gstack/analytics +if [ "$_TEL" != "off" ]; then +echo '{"skill":"spec","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true +fi +for _PF in $(find ~/.gstack/analytics -maxdepth 1 -name '.pending-*' 2>/dev/null); do + if [ -f "$_PF" ]; then + if [ "$_TEL" != "off" ] && [ -x "~/.claude/skills/gstack/bin/gstack-telemetry-log" ]; then + ~/.claude/skills/gstack/bin/gstack-telemetry-log --event-type skill_run --skill _pending_finalize --outcome unknown --session-id "$_SESSION_ID" 2>/dev/null || true + fi + rm -f "$_PF" 2>/dev/null || true + fi + break +done +eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true +_LEARN_FILE="${GSTACK_HOME:-$HOME/.gstack}/projects/${SLUG:-unknown}/learnings.jsonl" +if [ -f "$_LEARN_FILE" ]; then + _LEARN_COUNT=$(wc -l < "$_LEARN_FILE" 2>/dev/null | tr -d ' ') + echo "LEARNINGS: $_LEARN_COUNT entries loaded" + if [ "$_LEARN_COUNT" -gt 5 ] 2>/dev/null; then + ~/.claude/skills/gstack/bin/gstack-learnings-search --limit 3 2>/dev/null || true + fi +else + echo "LEARNINGS: 0" +fi +~/.claude/skills/gstack/bin/gstack-timeline-log '{"skill":"spec","event":"started","branch":"'"$_BRANCH"'","session":"'"$_SESSION_ID"'"}' 2>/dev/null & +_HAS_ROUTING="no" +if [ -f CLAUDE.md ] && grep -q "## Skill routing" CLAUDE.md 2>/dev/null; then + _HAS_ROUTING="yes" +fi +_ROUTING_DECLINED=$(~/.claude/skills/gstack/bin/gstack-config get routing_declined 2>/dev/null || echo "false") +echo "HAS_ROUTING: $_HAS_ROUTING" +echo "ROUTING_DECLINED: $_ROUTING_DECLINED" +_VENDORED="no" +if [ -d ".claude/skills/gstack" ] && [ ! -L ".claude/skills/gstack" ]; then + if [ -f ".claude/skills/gstack/VERSION" ] || [ -d ".claude/skills/gstack/.git" ]; then + _VENDORED="yes" + fi +fi +echo "VENDORED_GSTACK: $_VENDORED" +echo "MODEL_OVERLAY: claude" +_CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode 2>/dev/null || echo "explicit") +_CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") +echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" +echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" +[ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true +``` + +## Plan Mode Safe Operations + +In plan mode, allowed because they inform the plan: `$B`, `$D`, `codex exec`/`codex review`, writes to `~/.gstack/`, writes to the plan file, and `open` for generated artifacts. + +## Skill Invocation During Plan Mode + +If the user invokes a skill in plan mode, the skill takes precedence over generic plan mode behavior. **Treat the skill file as executable instructions, not reference.** Follow it step by step starting from Step 0; the first AskUserQuestion is the workflow entering plan mode, not a violation of it. AskUserQuestion (any variant — `mcp__*__AskUserQuestion` or native; see "AskUserQuestion Format → Tool resolution") satisfies plan mode's end-of-turn requirement. If no variant is callable, the skill is BLOCKED — stop and report `BLOCKED — AskUserQuestion unavailable` per the AskUserQuestion Format rule. At a STOP point, stop immediately. Do not continue the workflow or call ExitPlanMode there. Commands marked "PLAN MODE EXCEPTION — ALWAYS RUN" execute. Call ExitPlanMode only after the skill workflow completes, or if the user tells you to cancel the skill or leave plan mode. + +If `PROACTIVE` is `"false"`, do not auto-invoke or proactively suggest skills. If a skill seems useful, ask: "I think /skillname might help here — want me to run it?" + +If `SKILL_PREFIX` is `"true"`, suggest/invoke `/gstack-*` names. Disk paths stay `~/.claude/skills/gstack/[skill-name]/SKILL.md`. + +If output shows `UPGRADE_AVAILABLE `: read `~/.claude/skills/gstack/gstack-upgrade/SKILL.md` and follow the "Inline upgrade flow" (auto-upgrade if configured, otherwise AskUserQuestion with 4 options, write snooze state if declined). + +If output shows `JUST_UPGRADED `: print "Running gstack v{to} (just updated!)". If `SPAWNED_SESSION` is true, skip feature discovery. + +Feature discovery, max one prompt per session: +- Missing `~/.claude/skills/gstack/.feature-prompted-continuous-checkpoint`: AskUserQuestion for Continuous checkpoint auto-commits. If accepted, run `~/.claude/skills/gstack/bin/gstack-config set checkpoint_mode continuous`. Always touch marker. +- Missing `~/.claude/skills/gstack/.feature-prompted-model-overlay`: inform "Model overlays are active. MODEL_OVERLAY shows the patch." Always touch marker. + +After upgrade prompts, continue workflow. + +If `WRITING_STYLE_PENDING` is `yes`: ask once about writing style: + +> v1 prompts are simpler: first-use jargon glosses, outcome-framed questions, shorter prose. Keep default or restore terse? + +Options: +- A) Keep the new default (recommended — good writing helps everyone) +- B) Restore V0 prose — set `explain_level: terse` + +If A: leave `explain_level` unset (defaults to `default`). +If B: run `~/.claude/skills/gstack/bin/gstack-config set explain_level terse`. + +Always run (regardless of choice): +```bash +rm -f ~/.gstack/.writing-style-prompt-pending +touch ~/.gstack/.writing-style-prompted +``` + +Skip if `WRITING_STYLE_PENDING` is `no`. + +If `LAKE_INTRO` is `no`: say "gstack follows the **Boil the Lake** principle — do the complete thing when AI makes marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean" Offer to open: + +```bash +open https://garryslist.org/posts/boil-the-ocean +touch ~/.gstack/.completeness-intro-seen +``` + +Only run `open` if yes. Always run `touch`. + +If `TEL_PROMPTED` is `no` AND `LAKE_INTRO` is `yes`: ask telemetry once via AskUserQuestion: + +> Help gstack get better. Share usage data only: skill, duration, crashes, stable device ID. No code, file paths, or repo names. + +Options: +- A) Help gstack get better! (recommended) +- B) No thanks + +If A: run `~/.claude/skills/gstack/bin/gstack-config set telemetry community` + +If B: ask follow-up: + +> Anonymous mode sends only aggregate usage, no unique ID. + +Options: +- A) Sure, anonymous is fine +- B) No thanks, fully off + +If B→A: run `~/.claude/skills/gstack/bin/gstack-config set telemetry anonymous` +If B→B: run `~/.claude/skills/gstack/bin/gstack-config set telemetry off` + +Always run: +```bash +touch ~/.gstack/.telemetry-prompted +``` + +Skip if `TEL_PROMPTED` is `yes`. + +If `PROACTIVE_PROMPTED` is `no` AND `TEL_PROMPTED` is `yes`: ask once: + +> Let gstack proactively suggest skills, like /qa for "does this work?" or /investigate for bugs? + +Options: +- A) Keep it on (recommended) +- B) Turn it off — I'll type /commands myself + +If A: run `~/.claude/skills/gstack/bin/gstack-config set proactive true` +If B: run `~/.claude/skills/gstack/bin/gstack-config set proactive false` + +Always run: +```bash +touch ~/.gstack/.proactive-prompted +``` + +Skip if `PROACTIVE_PROMPTED` is `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. + +Use AskUserQuestion: + +> gstack works best when your project's CLAUDE.md includes skill routing rules. + +Options: +- A) Add routing rules to CLAUDE.md (recommended) +- B) No thanks, I'll invoke skills manually + +If A: Append this section to the end of CLAUDE.md: + +```markdown + +## Skill routing + +When the user's request matches an available skill, invoke it via the Skill tool. When in doubt, invoke the skill. + +Key routing rules: +- Product ideas/brainstorming → invoke /office-hours +- Strategy/scope → invoke /plan-ceo-review +- Architecture → invoke /plan-eng-review +- Design system/plan review → invoke /design-consultation or /plan-design-review +- Full review pipeline → invoke /autoplan +- Bugs/errors → invoke /investigate +- QA/testing site behavior → invoke /qa or /qa-only +- Code review/diff check → invoke /review +- Visual polish → invoke /design-review +- Ship/deploy/PR → invoke /ship or /land-and-deploy +- Save progress → invoke /context-save +- Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec +``` + +Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` + +If B: run `~/.claude/skills/gstack/bin/gstack-config set routing_declined true` and say they can re-enable with `gstack-config set routing_declined false`. + +This only happens once per project. Skip if `HAS_ROUTING` is `yes` or `ROUTING_DECLINED` is `true`. + +If `VENDORED_GSTACK` is `yes`, warn once via AskUserQuestion unless `~/.gstack/.vendoring-warned-$SLUG` exists: + +> This project has gstack vendored in `.claude/skills/gstack/`. Vendoring is deprecated. +> Migrate to team mode? + +Options: +- A) Yes, migrate to team mode now +- B) No, I'll handle it myself + +If A: +1. Run `git rm -r .claude/skills/gstack/` +2. Run `echo '.claude/skills/gstack/' >> .gitignore` +3. Run `~/.claude/skills/gstack/bin/gstack-team-init required` (or `optional`) +4. Run `git add .claude/ .gitignore CLAUDE.md && git commit -m "chore: migrate gstack from vendored to team mode"` +5. Tell the user: "Done. Each developer now runs: `cd ~/.claude/skills/gstack && ./setup --team`" + +If B: say "OK, you're on your own to keep the vendored copy up to date." + +Always run (regardless of choice): +```bash +eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true +touch ~/.gstack/.vendoring-warned-${SLUG:-unknown} +``` + +If marker exists, skip. + +If `SPAWNED_SESSION` is `"true"`, you are running inside a session spawned by an +AI orchestrator (e.g., OpenClaw). In spawned sessions: +- Do NOT use AskUserQuestion for interactive prompts. Auto-choose the recommended option. +- Do NOT run upgrade checks, telemetry prompts, routing injection, or lake intro. +- Focus on completing the task and reporting results via prose output. +- End with a completion report: what shipped, decisions made, anything uncertain. + +## AskUserQuestion Format + +### Tool resolution (read first) + +"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. + +**If no AskUserQuestion variant appears in your tool list, this skill is BLOCKED.** Stop, report `BLOCKED — AskUserQuestion unavailable`, and wait for the user. Do not write decisions to the plan file as a substitute, do not emit them as prose and stop, and do not silently auto-decide (only `/plan-tune` AUTO_DECIDE opt-ins authorize auto-picking). + +### Format + +Every AskUserQuestion is a decision brief and must be sent as tool_use, not prose. + +``` +D — +Project/branch/task: <1 short grounding sentence using _BRANCH> +ELI10: +Stakes if we pick wrong: +Recommendation: because +Completeness: A=X/10, B=Y/10 (or: Note: options differ in kind, not coverage — no completeness score) +Pros / cons: +A)