mirror of
https://github.com/garrytan/gstack.git
synced 2026-07-01 22:15:43 +02:00
Garry Tan
11de390be1
* feat: first-run activation — project-aware scaffold, router front door, onboarding nudges Adds the activation system that drives a new install toward a concrete first move: - bin/gstack-first-task-detect: local-git+filesystem repo classifier emitting one validated enum bucket (greenfield/code_<lang>/branch_ahead/dirty_default/clean_default), portable timeouts, fail-safe empty output. - generate-first-run-guidance.ts: unified preamble section — first-run project-aware scaffold + returning-session plan->review->ship tip, gated on a persistent .activated marker and never run in headless. Detection wired lazily in generate-preamble-bash.ts. - SKILL.md.tmpl: top-level gstack skill is now a pure router (browse body removed; it lives in /browse), routing any request and sending browser/QA work to /browse. - setup: first-move nudge on first install. office-hours: closing handoff that launches the next review via the Skill tool. - telemetry-ingest: accept onboarding/first_task_scaffold_shown/handoff/route event types. * test: cover first-run detection + repoint browse-content assertions to /browse - New unit tests for every detection bucket, the eval-safe enum contract, and the first-run gating (test/preamble-first-task-scaffold.test.ts); periodic E2E that runs the detector through the real harness (test/skill-e2e-first-task-scaffold.test.ts). - Repoint browse-content assertions (gen-skill-docs, audit-compliance, skill-validation, LLM-judge eval) from the root skill to browse/SKILL.md following the router split; add a regression pinning that the router carries no browse body. - Register first-task-scaffold touchfiles + periodic tier; bump parity/carve size caps ~1-2KB per skill for the shared first-run-guidance preamble section. - Refresh ship golden fixtures for the preamble addition. * chore: regenerate SKILL.md + llms.txt for first-run activation * chore: bump version and changelog (v1.58.5.0) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(test): repoint bws skillmd-* setup-block assertions to browse/SKILL.md The skillmd-setup-discovery / -no-local-binary / -outside-git E2E tests extracted the `## SETUP`→`## IMPORTANT` browse binary-discovery block from the root SKILL.md. P2 moved that block to browse/SKILL.md (end anchor is now `## Core QA Patterns`), so the slice came back empty and the `browse/dist/browse` guard failed. Repoint to browse/SKILL.md. Verified: 7/7 e2e-browse pass locally. * fix(test): tolerate skill-discovery race in PTY plan-mode smoke The e2e-pty-plan-smoke suite (office-hours / plan-mode-no-op) failed in CI with `Unknown command: /office-hours` (claude exited ~10s) while passing locally. Root cause: a cold CI container's overlay-FS scan of the symlinked ~/.claude/skills registry finishes AFTER the runner's 8s boot grace, so the first `/skill` send reaches claude before the skill is indexed and is rejected as unknown. The runner gave up on the first "Unknown command:" line. runPlanSkillObservation now re-sends the skill command up to 3x (6s apart), re-marking the buffer each time so stale scrollback can't re-trip the check, before concluding the skill is genuinely unregistered. A real dangling-symlink / missing-skill still surfaces as 'exited' (after retries), preserving the original diagnostic. Pure-helper contract unchanged: 95/95 unit tests pass. This is a pre-existing harness bug (fails identically on #2077's own branch, which introduced the suite) surfaced while shipping the activation feature. * debug(ci): temporarily instrument pty-smoke skill discovery Capture claude version, env, registry tree, and a claude -p discovery probe to pin why /office-hours isn't discovered in CI (retries proved it's not a race). Temporary — revert once the registry fix is identified. * chore: revert pty-smoke harness experiments (race-retry + CI debug step) Diagnosis is conclusive and the experiments aren't the fix, so restore the harness to its original state (net-zero diff vs main for both files). What the CI debug step proved: `claude -p` returns READY — claude v2.1.187 fully DISCOVERS /office-hours from the symlinked registry. Only the interactive PTY TUI rejects it as "Unknown command" (and it received the full command text). So the e2e-pty-plan-smoke failure is a claude 2.1.187 interactive-TUI regression (skills discovered by `claude -p` aren't exposed as TUI slash commands), pre-existing in the #2077 harness and failing identically on its own origin branch — unrelated to this activation PR. The race-retry can't help (the TUI genuinely lacks the command); the debug step also tripped actionlint (shellcheck SC2012). Both reverted. * fix(ci): copy SKILL.md as real files in pty-smoke registry (cross-mount symlink) The e2e-pty-plan-smoke suite failed with "Unknown command: /office-hours" in CI while passing locally. Root cause (proven, not guessed): claude 2.1.187's interactive-TUI skill scanner does not follow the /github/home -> /__w cross-mount symlink the registry used for per-skill SKILL.md. Evidence: a CI debug step showed `claude -p` discovered the skill (printed READY), and a local macOS repro with the identical symlinked registry recognized /office-hours — isolating the failure to the container's cross-mount symlink, not registration content, claude version, duplicate names, or a race. Fix: register the per-skill SKILL.md + sections as REAL copies (same mount as $HOME) so the TUI reads them directly. The gstack root stays a symlink — the preamble's runtime bash resolves bin/* and sections/* through it and bash follows cross-mount symlinks fine. * fix(ci): guard rm expansion in pty-smoke registry (shellcheck SC2115) * fix(ci): also register pty-smoke skills project-scoped (cwd/.claude/skills) The real-file user-dir registration still left the TUI rejecting /office-hours in the container. claude's interactive TUI surfaces /slash commands from the PROJECT dir (<cwd>/.claude/skills); the smokes run with cwd=$REPO whose .claude/skills is gitignored (absent on a fresh CI checkout), so the user-dir registry feeds `claude -p` (READY) but not the TUI. Populate $REPO/.claude/skills with real SKILL.md + sections copies (no gstack symlink there — it would point at its own parent; runtime paths use the user-dir gstack symlink). --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
92 lines
5.5 KiB
Cheetah
92 lines
5.5 KiB
Cheetah
---
|
|
name: gstack
|
|
preamble-tier: 1
|
|
version: 1.2.0
|
|
description: |
|
|
Router for the gstack skill suite. Sends any gstack request to the right skill
|
|
(planning, review, QA, shipping, debugging, docs, security, design). For browser/QA
|
|
and dogfooding it points you at /browse. Use when you invoke gstack without a specific
|
|
skill, or ask "which gstack skill fits this?". (gstack)
|
|
allowed-tools:
|
|
- Bash
|
|
- Read
|
|
- AskUserQuestion
|
|
triggers:
|
|
- gstack
|
|
- which gstack skill
|
|
- route this with gstack
|
|
|
|
---
|
|
|
|
{{PREAMBLE}}
|
|
|
|
## Route first
|
|
|
|
This is the gstack router. Its one job is to send the request to the right skill.
|
|
|
|
1. If the request is about a browser, QA, dogfooding, screenshots, or inspecting a page
|
|
(open a site, test a deploy, take a screenshot, check a flow visually) → invoke `/browse`.
|
|
2. Otherwise, route by the rules below. If nothing matches, answer directly.
|
|
|
|
Best-effort, record which way you routed (never block on it). Set `ROUTE_OUTCOME` to
|
|
`browse` (sent to /browse), `routed` (sent to another skill), or `direct` (answered
|
|
directly, no skill matched):
|
|
```bash
|
|
~/.claude/skills/gstack/bin/gstack-telemetry-log --event-type route --skill gstack --outcome ROUTE_OUTCOME --session-id "$_SESSION_ID" 2>/dev/null || true
|
|
```
|
|
|
|
If `PROACTIVE` is `false`: do NOT proactively invoke or suggest other gstack skills during
|
|
this session. Only run skills the user explicitly invokes. This preference persists across
|
|
sessions via `gstack-config`.
|
|
|
|
If `PROACTIVE` is `true` (default): **invoke the Skill tool** when the user's request
|
|
matches a skill's purpose. Do NOT answer directly when a skill exists for the task.
|
|
Use the Skill tool to invoke it. The skill has specialized workflows, checklists, and
|
|
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`
|
|
- User asks to review design of a plan → invoke `/plan-design-review`
|
|
- User asks about developer experience of a plan, API/CLI/SDK design → invoke `/plan-devex-review`
|
|
- User wants all reviews done automatically, "review everything" → invoke `/autoplan`
|
|
- User reports a bug, error, broken behavior, "why is this broken", "this doesn't work", "wtf", "something's wrong" → invoke `/investigate`
|
|
- User asks to test the site, find bugs, QA, "does this work", "check the deploy" → invoke `/qa`
|
|
- User asks to just report bugs without fixing → invoke `/qa-only`
|
|
- User asks to review code, check the diff, pre-landing review, "look at my changes" → invoke `/review`
|
|
- User asks about visual polish, design audit of a live site, "this looks off" → invoke `/design-review`
|
|
- User asks to audit the live developer experience, time-to-hello-world → invoke `/devex-review`
|
|
- User asks to ship, deploy, push, create a PR, "let's land this", "send it" → invoke `/ship`
|
|
- User asks to merge + deploy + verify as one flow → invoke `/land-and-deploy`
|
|
- User asks to configure deployment for the project → invoke `/setup-deploy`
|
|
- User asks to monitor prod after shipping, post-deploy checks → invoke `/canary`
|
|
- User asks to update docs after shipping → invoke `/document-release`
|
|
- User asks to write docs from scratch, generate documentation, "document this feature/module" → invoke `/document-generate`
|
|
- User asks for a weekly retro, what did we ship, "how'd we do" → invoke `/retro`
|
|
- User asks for a second opinion, codex review → invoke `/codex`
|
|
- User asks for safety mode, careful mode → invoke `/careful` or `/guard`
|
|
- User asks to restrict edits to a directory → invoke `/freeze` or `/unfreeze`
|
|
- User asks to upgrade gstack → invoke `/gstack-upgrade`
|
|
- User asks to save progress, checkpoint, "save my work" → invoke `/context-save`
|
|
- User asks to resume, restore, "where was I" → invoke `/context-restore`
|
|
- User asks about security, OWASP, vulnerabilities, "is this secure" → invoke `/cso`
|
|
- User asks to make a PDF, document, publication → invoke `/make-pdf`
|
|
- User asks to launch a real browser for QA, "open the browser" → invoke `/open-gstack-browser`
|
|
- User asks to import cookies for authenticated testing → invoke `/setup-browser-cookies`
|
|
- User asks about page speed, performance regression, benchmarks → invoke `/benchmark`
|
|
- User asks what gstack has learned, "show learnings" → invoke `/learn`
|
|
- User asks to tune question sensitivity, "stop asking me that" → invoke `/plan-tune`
|
|
- User asks for code quality dashboard, "health check" → invoke `/health`
|
|
|
|
**When in doubt, invoke the skill.** A false positive (invoking a skill that wasn't
|
|
needed) is cheaper than a false negative (answering ad-hoc when a structured workflow
|
|
exists). The skill provides multi-step workflows, checklists, and quality gates that
|
|
always produce better results than an ad-hoc answer. If no skill matches, answer
|
|
directly as usual.
|
|
|
|
If the user opts out of suggestions, run `gstack-config set proactive false`.
|
|
If they opt back in, run `gstack-config set proactive true`.
|