diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 2b2ef364..5311c2cd 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -192,7 +192,25 @@ gen-skill-docs.ts (reads source code metadata) SKILL.md (committed, auto-generated sections) ``` -Templates contain the workflows, tips, and examples that require human judgment. The `{{COMMAND_REFERENCE}}` and `{{SNAPSHOT_FLAGS}}` placeholders are filled from `commands.ts` and `snapshot.ts` at build time. This is structurally sound — if a command exists in code, it appears in docs. If it doesn't exist, it can't appear. +Templates contain the workflows, tips, and examples that require human judgment. Placeholders are filled from source code at build time: + +| Placeholder | Source | What it generates | +|-------------|--------|-------------------| +| `{{COMMAND_REFERENCE}}` | `commands.ts` | Categorized command table | +| `{{SNAPSHOT_FLAGS}}` | `snapshot.ts` | Flag reference with examples | +| `{{PREAMBLE}}` | `gen-skill-docs.ts` | Startup block: update check, session tracking, contributor mode, AskUserQuestion format | +| `{{BROWSE_SETUP}}` | `gen-skill-docs.ts` | Binary discovery + setup instructions | + +This is structurally sound — if a command exists in code, it appears in docs. If it doesn't exist, it can't appear. + +### The preamble + +Every skill starts with a `{{PREAMBLE}}` block that runs before the skill's own logic. It handles four things in a single bash command: + +1. **Update check** — calls `gstack-update-check`, reports if an upgrade is available. +2. **Session tracking** — touches `~/.gstack/sessions/$PPID` and counts active sessions (files modified in the last 2 hours). When 3+ sessions are running, all skills enter "ELI16 mode" — every question re-grounds the user on context because they're juggling windows. +3. **Contributor mode** — reads `gstack_contributor` from config. When true, the agent files casual field reports to `~/.gstack/contributor-logs/` when gstack itself misbehaves. +4. **AskUserQuestion format** — universal format: context, question, `RECOMMENDATION: Choose X because ___`, lettered options. Consistent across all skills. ### Why committed, not generated at runtime? diff --git a/CHANGELOG.md b/CHANGELOG.md index 9ae6b4fb..44980dcc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,20 @@ # Changelog +## 0.4.1 — 2026-03-16 + +### For users + +- **Contributor mode.** Run `gstack-config set gstack_contributor true` and gstack starts filing field reports when it hits its own bugs. You'll see a casual "hey gstack team, this didn't work" note appear in `~/.gstack/contributor-logs/` — open your fork and fix it. +- **Session awareness.** If you're running 3+ gstack sessions at once, every question now re-grounds you: project, branch, what you're working on, what it's asking. No more "wait, which window is this?" +- **Consistent recommendations.** Every question gstack asks you now ends with a clear `RECOMMENDATION: Choose X because ___` before the options. Same format everywhere. +- **Enum completeness checks in /review.** New critical review category that traces new enum values, status strings, and type constants through every consumer outside the diff. Catches the "added a value but forgot to handle it in the switch statement" class of bugs. + +### For contributors + +- Renamed `{{UPDATE_CHECK}}` placeholder to `{{PREAMBLE}}` across all skill templates — single startup block now handles update check, session tracking, contributor mode, and question formatting. +- DRY'd plan-ceo-review and plan-eng-review question formatting to reference the preamble baseline. +- Added vendored symlink awareness docs to CLAUDE.md. + ## 0.4.0 — 2026-03-16 ### Added diff --git a/VERSION b/VERSION index 1d0ba9ea..267577d4 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.4.0 +0.4.1 diff --git a/qa-only/SKILL.md b/qa-only/SKILL.md index 8d6f2b11..438b7826 100644 --- a/qa-only/SKILL.md +++ b/qa-only/SKILL.md @@ -15,15 +15,63 @@ allowed-tools: -## Update Check (run first) +## 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 -delete 2>/dev/null || true +_CONTRIB=$(~/.claude/skills/gstack/bin/gstack-config get gstack_contributor 2>/dev/null || true) ``` 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 `JUST_UPGRADED `: tell user "Running gstack v{to} (just updated!)" and continue. +## AskUserQuestion Format + +**ALWAYS follow this structure for every AskUserQuestion call:** +1. Context: project name, current branch, what we're working on (1-2 sentences) +2. The specific question or decision point +3. `RECOMMENDATION: Choose [X] because [one-line reason]` +4. Lettered options: `A) ... B) ... C) ...` + +If `_SESSIONS` is 3 or more: the user is juggling multiple gstack sessions and context-switching heavily. **ELI16 mode** — they may not remember what this conversation is about. Every AskUserQuestion MUST re-ground them: state the project, the branch, the current plan/task, then the specific problem, THEN the recommendation and options. Be extra clear and self-contained — assume they haven't looked at this window in 20 minutes. + +Per-skill instructions may add additional formatting rules on top of this baseline. + +## Contributor Mode + +If `_CONTRIB` is `true`: you are in **contributor mode**. When you hit friction with **gstack itself** (not the user's app), file a field report. Think: "hey, I was trying to do X with gstack and it didn't work / was confusing / was annoying. Here's what happened." + +**gstack issues:** browse command fails/wrong output, snapshot missing elements, skill instructions unclear or misleading, binary crash/hang, unhelpful error message, any rough edge or annoyance — even minor stuff. +**NOT gstack issues:** user's app bugs, network errors to user's URL, auth failures on user's site. + +**To file:** write `~/.gstack/contributor-logs/{slug}.md` with this structure: + +``` +# {Title} + +Hey gstack team — ran into this while using /{skill-name}: + +**What I was trying to do:** {what the user/agent was attempting} +**What happened instead:** {what actually happened} +**How annoying (1-5):** {1=meh, 3=friction, 5=blocker} + +## Steps to reproduce +1. {step} + +## Raw output +(wrap any error messages or unexpected output in a markdown code block) + +**Date:** {YYYY-MM-DD} | **Version:** {gstack version} | **Skill:** /{skill} +``` + +Then run: `mkdir -p ~/.gstack/contributor-logs && open ~/.gstack/contributor-logs/{slug}.md` + +Slug: lowercase, hyphens, max 60 chars (e.g. `browse-snapshot-ref-gap`). Skip if file already exists. Max 3 reports per session. File inline and continue — don't stop the workflow. Tell user: "Filed gstack field report: {title}" + # /qa-only: Report-Only QA Testing You are a QA engineer. Test web applications like a real user — click everything, fill every form, check every state. Produce a structured report with evidence. **NEVER fix anything.** diff --git a/qa-only/SKILL.md.tmpl b/qa-only/SKILL.md.tmpl index 7ad936bb..5d49e201 100644 --- a/qa-only/SKILL.md.tmpl +++ b/qa-only/SKILL.md.tmpl @@ -13,7 +13,7 @@ allowed-tools: - AskUserQuestion --- -{{UPDATE_CHECK}} +{{PREAMBLE}} # /qa-only: Report-Only QA Testing