diff --git a/CLAUDE.md b/CLAUDE.md index ce374c0eb9..8214929ffb 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,8 +2,8 @@ ## GStack 2 canonical contract -The public surface is exactly `/plan`, `/design`, `/qa`, `/debug`, `/review`, -and `/ship`. They are lazy dispatchers over the preserved modules under +The public surface is exactly `/plan`, `/qa`, `/debug`, `/review`, and `/ship`. +They are lazy dispatchers over the preserved modules under `skills/*/references/legacy/`; do not rewrite or summarize away the original question pressure, rubrics, pushback, approval gates, evidence, artifacts, mutation boundaries, recommendations, or voice. Compatibility files under @@ -916,7 +916,6 @@ When the user's request matches an available skill, invoke it via the Skill tool Key routing rules: - Product framing, strategy, scope, architecture, DX, specs, or a full planning pipeline → invoke `/plan` with the preserved specialist mode. -- Design systems, alternatives, coded visual output, plan review, web audit, or HIG audit → invoke `/design`. - Web/device QA, report-only versus fixes, DX journeys, performance, or canaries → invoke `/qa`. - Bugs and unknown failures → invoke `/debug`; prove root cause before mutation. - Diff, security, compatibility, or repository-health review → invoke `/review`. diff --git a/README.md b/README.md index 4ad525c864..3797b5a073 100644 --- a/README.md +++ b/README.md @@ -7,13 +7,12 @@ > `./setup` instructions and the many-command catalog describe the 1.x > compatibility surface. -GStack 2 presents one engineering judgment layer through exactly six public +GStack 2 presents one engineering judgment layer through exactly five public skills: | Skill | Start here when… | |---|---| | `/plan` | The product, scope, architecture, DX, or specification is unsettled. | -| `/design` | You need a visual direction, alternatives, implementation, or design audit. | | `/qa` | You need report-only or fix-and-verify evidence from the local browser or a physical iPhone. | | `/debug` | A failure needs root-cause proof before a fix. | | `/review` | A diff or repository needs correctness, security, compatibility, or health review. | @@ -23,7 +22,7 @@ skills: DX, Specification, and Full chain**. The other dispatchers refine their small public mode set into the preserved specialist modules only after selection. -The specialist judgment was not flattened into six generic prompts. Each +The specialist judgment was not flattened into five generic prompts. Each dispatcher states its mode, depth, mutation boundary, active and skipped modules, and web-context choice, then lazily reads the preserved specialist module. See the complete [old-command mapping](docs/gstack-2/SKILL-MIGRATION.md) @@ -38,7 +37,7 @@ scope, destination paths, updates, removal, and selected-skill installation: npx skills add time-attack/gstack/skills ``` -That installs the six judgment skills. Install a subset with the installer's +That installs the five judgment skills. Install a subset with the installer's `--skill` option, or use `-g` for its global scope. GStack does not silently enroll detected hosts. @@ -94,7 +93,7 @@ tree contains legacy GStack 1 entry points and is not the GStack 2 install surface. The npm package is deliberately not the skill installer and does not contain -the six skill tree or compiled browser/design/PDF payloads. It is the small +the five skill tree or compiled browser/design/PDF payloads. It is the small host-neutral runtime control/bootstrap surface used by release tooling. New users should install skills with `npx skills add time-attack/gstack/skills`; optional capabilities are downloaded by a skill after consent. @@ -132,7 +131,7 @@ I'm [Garry Tan](https://x.com/garrytan), President & CEO of [Y Combinator](https Same person. Different era. The difference is the tooling. -**gstack is how I do it.** It turns an AI coding host into a virtual engineering team — a CEO who rethinks the product, an eng manager who locks architecture, a designer who catches AI slop, a reviewer who finds production bugs, a QA lead who opens a real browser, a security officer who runs OWASP + STRIDE audits, and a release engineer who ships the PR. In GStack 2 those preserved specialists sit behind six lazy dispatchers rather than dozens of default commands. It remains MIT licensed. +**gstack is how I do it.** It turns an AI coding host into a virtual engineering team — a CEO who rethinks the product, an eng manager who locks architecture, a designer who catches AI slop, a reviewer who finds production bugs, a QA lead who opens a real browser, a security officer who runs OWASP + STRIDE audits, and a release engineer who ships the PR. In GStack 2 those preserved specialists sit behind five lazy dispatchers rather than dozens of default commands. It remains MIT licensed. This is my open source software factory. I use it every day. I'm sharing it because these tools should be available to everyone. diff --git a/compat/README.md b/compat/README.md index 4b0c0a496e..a6b7c117a2 100644 --- a/compat/README.md +++ b/compat/README.md @@ -1,7 +1,7 @@ # GStack 2 compatibility aliases -These files preserve all 55 legacy invocation names as internal routing details. They intentionally are not named `SKILL.md`, so only the six dispatcher skills are discoverable. +These files preserve all 47 legacy invocation names as internal routing details. They intentionally are not named `SKILL.md`, so only the five dispatcher skills are discoverable. | Legacy invocation | Replacement | Preserved module | |---|---|---| @@ -19,14 +19,6 @@ These files preserve all 55 legacy invocation names as internal routing details. | `/retro` | `$plan --mode Discovery --module retro` | `skills/plan/references/legacy/retro.md` | | `/setup-gbrain` | `$plan --mode Discovery --module setup-gbrain` | `skills/plan/references/legacy/setup-gbrain.md` | | `/sync-gbrain` | `$plan --mode Discovery --module sync-gbrain` | `skills/plan/references/legacy/sync-gbrain.md` | -| `/design-consultation` | `$design --mode Generate --module design-consultation` | `skills/design/references/legacy/design-consultation.md` | -| `/design-shotgun` | `$design --mode Explore --module design-shotgun` | `skills/design/references/legacy/design-shotgun.md` | -| `/design-html` | `$design --mode Implement --module design-html` | `skills/design/references/legacy/design-html.md` | -| `/plan-design-review` | `$design --mode Critique --module plan-design-review` | `skills/design/references/legacy/plan-design-review.md` | -| `/design-review` | `$design --mode Implement --module design-review` | `skills/design/references/legacy/design-review.md` | -| `/ios-design-review` | `$design --mode Critique --module ios-design-review` | `skills/design/references/legacy/ios-design-review.md` | -| `/diagram` | `$design --mode Generate --module diagram` | `skills/design/references/legacy/diagram.md` | -| `/make-pdf` | `$design --mode Generate --module make-pdf` | `skills/design/references/legacy/make-pdf.md` | | `/qa` | `$qa --mode Fix --module qa` | `skills/qa/references/legacy/qa.md` | | `/qa-only` | `$qa --mode Report --module qa-only` | `skills/qa/references/legacy/qa-only.md` | | `/ios-qa` | `$qa --mode Report --module ios-qa` | `skills/qa/references/legacy/ios-qa.md` | diff --git a/compat/design-consultation.md b/compat/design-consultation.md deleted file mode 100644 index 3300425f53..0000000000 --- a/compat/design-consultation.md +++ /dev/null @@ -1,10 +0,0 @@ - -# Compatibility alias: /design-consultation - -This is not a public/discoverable skill. Route the legacy invocation to `$design --mode Generate --module design-consultation`, then read [the preserved module](../skills/design/references/legacy/design-consultation.md) in full. - -- Tree: `design` -- Public mode: `Generate` -- Legacy internal alias: `consult` -- Dispatcher role: `primary` -- Mandatory specialist input: `true` diff --git a/compat/design-html.md b/compat/design-html.md deleted file mode 100644 index 5d9ab82d98..0000000000 --- a/compat/design-html.md +++ /dev/null @@ -1,10 +0,0 @@ - -# Compatibility alias: /design-html - -This is not a public/discoverable skill. Route the legacy invocation to `$design --mode Implement --module design-html`, then read [the preserved module](../skills/design/references/legacy/design-html.md) in full. - -- Tree: `design` -- Public mode: `Implement` -- Legacy internal alias: `html` -- Dispatcher role: `primary` -- Mandatory specialist input: `true` diff --git a/compat/design-review.md b/compat/design-review.md deleted file mode 100644 index f905e95862..0000000000 --- a/compat/design-review.md +++ /dev/null @@ -1,10 +0,0 @@ - -# Compatibility alias: /design-review - -This is not a public/discoverable skill. Route the legacy invocation to `$design --mode Implement --module design-review`, then read [the preserved module](../skills/design/references/legacy/design-review.md) in full. - -- Tree: `design` -- Public mode: `Implement` -- Legacy internal alias: `live-review` -- Dispatcher role: `primary` -- Mandatory specialist input: `true` diff --git a/compat/design-shotgun.md b/compat/design-shotgun.md deleted file mode 100644 index ab205b73f4..0000000000 --- a/compat/design-shotgun.md +++ /dev/null @@ -1,10 +0,0 @@ - -# Compatibility alias: /design-shotgun - -This is not a public/discoverable skill. Route the legacy invocation to `$design --mode Explore --module design-shotgun`, then read [the preserved module](../skills/design/references/legacy/design-shotgun.md) in full. - -- Tree: `design` -- Public mode: `Explore` -- Legacy internal alias: `alternatives` -- Dispatcher role: `primary` -- Mandatory specialist input: `true` diff --git a/compat/diagram.md b/compat/diagram.md deleted file mode 100644 index 35644da99f..0000000000 --- a/compat/diagram.md +++ /dev/null @@ -1,10 +0,0 @@ - -# Compatibility alias: /diagram - -This is not a public/discoverable skill. Route the legacy invocation to `$design --mode Generate --module diagram`, then read [the preserved module](../skills/design/references/legacy/diagram.md) in full. - -- Tree: `design` -- Public mode: `Generate` -- Legacy internal alias: `diagram` -- Dispatcher role: `internal` -- Mandatory specialist input: `false` diff --git a/compat/ios-design-review.md b/compat/ios-design-review.md deleted file mode 100644 index e1b69171fb..0000000000 --- a/compat/ios-design-review.md +++ /dev/null @@ -1,10 +0,0 @@ - -# Compatibility alias: /ios-design-review - -This is not a public/discoverable skill. Route the legacy invocation to `$design --mode Critique --module ios-design-review`, then read [the preserved module](../skills/design/references/legacy/ios-design-review.md) in full. - -- Tree: `design` -- Public mode: `Critique` -- Legacy internal alias: `ios-review` -- Dispatcher role: `primary` -- Mandatory specialist input: `true` diff --git a/compat/make-pdf.md b/compat/make-pdf.md deleted file mode 100644 index 4511b7d477..0000000000 --- a/compat/make-pdf.md +++ /dev/null @@ -1,10 +0,0 @@ - -# Compatibility alias: /make-pdf - -This is not a public/discoverable skill. Route the legacy invocation to `$design --mode Generate --module make-pdf`, then read [the preserved module](../skills/design/references/legacy/make-pdf.md) in full. - -- Tree: `design` -- Public mode: `Generate` -- Legacy internal alias: `pdf` -- Dispatcher role: `internal` -- Mandatory specialist input: `false` diff --git a/compat/migration-map.json b/compat/migration-map.json index f25ef14535..329c98e74e 100644 --- a/compat/migration-map.json +++ b/compat/migration-map.json @@ -178,102 +178,6 @@ "default_discoverable": false, "judgment_copied_into_alias": false }, - { - "legacy_invocation": "/design-consultation", - "replacement_invocation": "$design --mode Generate --module design-consultation", - "dispatcher": "design", - "public_mode": "Generate", - "internal_alias": "consult", - "preserved_module": "skills/design/references/legacy/design-consultation.md", - "opt_in_alias": "skills/.compat/design-consultation/SKILL.md", - "alias_required": true, - "default_discoverable": false, - "judgment_copied_into_alias": false - }, - { - "legacy_invocation": "/design-shotgun", - "replacement_invocation": "$design --mode Explore --module design-shotgun", - "dispatcher": "design", - "public_mode": "Explore", - "internal_alias": "alternatives", - "preserved_module": "skills/design/references/legacy/design-shotgun.md", - "opt_in_alias": "skills/.compat/design-shotgun/SKILL.md", - "alias_required": true, - "default_discoverable": false, - "judgment_copied_into_alias": false - }, - { - "legacy_invocation": "/design-html", - "replacement_invocation": "$design --mode Implement --module design-html", - "dispatcher": "design", - "public_mode": "Implement", - "internal_alias": "html", - "preserved_module": "skills/design/references/legacy/design-html.md", - "opt_in_alias": "skills/.compat/design-html/SKILL.md", - "alias_required": true, - "default_discoverable": false, - "judgment_copied_into_alias": false - }, - { - "legacy_invocation": "/plan-design-review", - "replacement_invocation": "$design --mode Critique --module plan-design-review", - "dispatcher": "design", - "public_mode": "Critique", - "internal_alias": "plan-review", - "preserved_module": "skills/design/references/legacy/plan-design-review.md", - "opt_in_alias": "skills/.compat/plan-design-review/SKILL.md", - "alias_required": true, - "default_discoverable": false, - "judgment_copied_into_alias": false - }, - { - "legacy_invocation": "/design-review", - "replacement_invocation": "$design --mode Implement --module design-review", - "dispatcher": "design", - "public_mode": "Implement", - "internal_alias": "live-review", - "preserved_module": "skills/design/references/legacy/design-review.md", - "opt_in_alias": "skills/.compat/design-review/SKILL.md", - "alias_required": true, - "default_discoverable": false, - "judgment_copied_into_alias": false - }, - { - "legacy_invocation": "/ios-design-review", - "replacement_invocation": "$design --mode Critique --module ios-design-review", - "dispatcher": "design", - "public_mode": "Critique", - "internal_alias": "ios-review", - "preserved_module": "skills/design/references/legacy/ios-design-review.md", - "opt_in_alias": "skills/.compat/ios-design-review/SKILL.md", - "alias_required": true, - "default_discoverable": false, - "judgment_copied_into_alias": false - }, - { - "legacy_invocation": "/diagram", - "replacement_invocation": "$design --mode Generate --module diagram", - "dispatcher": "design", - "public_mode": "Generate", - "internal_alias": "diagram", - "preserved_module": "skills/design/references/legacy/diagram.md", - "opt_in_alias": "skills/.compat/diagram/SKILL.md", - "alias_required": true, - "default_discoverable": false, - "judgment_copied_into_alias": false - }, - { - "legacy_invocation": "/make-pdf", - "replacement_invocation": "$design --mode Generate --module make-pdf", - "dispatcher": "design", - "public_mode": "Generate", - "internal_alias": "pdf", - "preserved_module": "skills/design/references/legacy/make-pdf.md", - "opt_in_alias": "skills/.compat/make-pdf/SKILL.md", - "alias_required": true, - "default_discoverable": false, - "judgment_copied_into_alias": false - }, { "legacy_invocation": "/qa", "replacement_invocation": "$qa --mode Fix --module qa", diff --git a/compat/plan-design-review.md b/compat/plan-design-review.md deleted file mode 100644 index bd364baa50..0000000000 --- a/compat/plan-design-review.md +++ /dev/null @@ -1,10 +0,0 @@ - -# Compatibility alias: /plan-design-review - -This is not a public/discoverable skill. Route the legacy invocation to `$design --mode Critique --module plan-design-review`, then read [the preserved module](../skills/design/references/legacy/plan-design-review.md) in full. - -- Tree: `design` -- Public mode: `Critique` -- Legacy internal alias: `plan-review` -- Dispatcher role: `primary` -- Mandatory specialist input: `true` diff --git a/design-consultation/SKILL.md b/design-consultation/SKILL.md deleted file mode 100644 index a43fa458fe..0000000000 --- a/design-consultation/SKILL.md +++ /dev/null @@ -1,1232 +0,0 @@ ---- -name: gstack-1-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... (gstack)" -allowed-tools: - - Bash - - Read - - Write - - Edit - - Glob - - Grep - - AskUserQuestion - - WebSearch -triggers: - - design system - - create a brand - - design from scratch -gbrain: - schema: 1 - context_queries: - - id: existing-design-md - kind: filesystem - glob: "DESIGN.md" - tail: 1 - render_as: "## Existing DESIGN.md (if any)" - - id: prior-design-decisions - kind: filesystem - glob: "~/.gstack/projects/{repo_slug}/*-design-*.md" - sort: mtime_desc - limit: 3 - render_as: "## Prior design decisions for this project" - - id: brand-guidelines - kind: list - filter: - type: ceo-plan - tags_contains: "repo:{repo_slug}" - content_contains: "brand" - sort: updated_at_desc - limit: 3 - render_as: "## Brand-related notes from CEO plans" -metadata: - internal: true ---- - - - - -## 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 -_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" -_SESSION_KIND=$(~/.claude/skills/gstack/bin/gstack-session-kind 2>/dev/null || echo "interactive") -case "$_SESSION_KIND" in spawned|headless|interactive) ;; *) _SESSION_KIND="interactive" ;; esac -echo "SESSION_KIND: $_SESSION_KIND" -# Conductor host: AskUserQuestion is unreliable here (native disabled, MCP -# variant flaky), so skills render decisions as prose instead of calling the -# tool. Gated on !headless so an eval/CI run INSIDE Conductor (GSTACK_HEADLESS) -# still BLOCKs rather than rendering prose to nobody. -if [ "$_SESSION_KIND" != "headless" ] && { [ -n "${CONDUCTOR_WORKSPACE_PATH:-}" ] || [ -n "${CONDUCTOR_PORT:-}" ]; }; then - echo "CONDUCTOR_SESSION: true" -fi -_ACTIVATED=$([ -f ~/.gstack/.activated ] && echo "yes" || echo "no") -_FIRST_LOOP_SHOWN=$([ -f ~/.gstack/.first-loop-tip-shown ] && echo "yes" || echo "no") -echo "ACTIVATED: $_ACTIVATED" -echo "FIRST_LOOP_SHOWN: $_FIRST_LOOP_SHOWN" -# First-run project detection: run the detector ONLY on the first-ever skill run -# (ACTIVATED=no, interactive) so it stays off the hot path for every run after. -_FIRST_TASK="" -if [ "$_ACTIVATED" = "no" ] && [ "$_SESSION_KIND" != "headless" ]; then - _FIRST_TASK=$(~/.claude/skills/gstack/bin/gstack-first-task-detect 2>/dev/null || true) -fi -echo "FIRST_TASK: $_FIRST_TASK" -_LAKE_SEEN=$([ -f ~/.gstack/.completeness-intro-seen ] && echo "yes" || echo "no") -echo "LAKE_INTRO: $_LAKE_SEEN" -_TEL=$(~/.claude/skills/gstack/bin/gstack-config get telemetry 2>/dev/null || true) -_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":"design-consultation","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(_repo=$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null | tr -cd 'a-zA-Z0-9._-'); echo "${_repo:-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":"design-consultation","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 AskUserQuestion is unavailable or a call fails, follow the AskUserQuestion Format failure fallback: `headless` → BLOCKED; `interactive` → the prose fallback (also satisfies end-of-turn). 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 Ocean** 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 or file paths. Your repo name is recorded locally only and stripped before any upload. - -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`. - -## First-run guidance (one-time) - -If `ACTIVATED` is `no` (first skill run on this machine) AND the preamble printed a non-empty `FIRST_TASK:` value that is NOT `nongit`: show ONE short, project-specific line mapped from the token, as a heads-up, then CONTINUE with whatever the user actually asked — do NOT halt their task. Map the token: `greenfield` → "Fresh repo — shape it first with `/spec` or `/office-hours`." `code_node`/`code_python`/`code_rust`/`code_go`/`code_ruby`/`code_ios` → "There's code here — `/qa` to see it work, or `/investigate` if something's off." `branch_ahead` → "Unshipped work on this branch — `/review` then `/ship`." `dirty_default` → "Uncommitted changes — `/review` before committing." `clean_default` → "Pick one: `/spec`, `/investigate`, or `/qa`." Then substitute the token you saw for TASK_TOKEN and run (best-effort), and mark activated: -```bash -~/.claude/skills/gstack/bin/gstack-telemetry-log --event-type first_task_scaffold_shown --skill "TASK_TOKEN" --outcome shown 2>/dev/null || true -touch ~/.gstack/.activated 2>/dev/null || true -``` - -If `ACTIVATED` is `no` but `FIRST_TASK:` is empty or `nongit` (headless, non-git, or nothing actionable): show nothing, just run `touch ~/.gstack/.activated 2>/dev/null || true`. - -Else if `ACTIVATED` is `yes` AND `FIRST_LOOP_SHOWN` is `no`: say once as a heads-up (then continue): - -> Tip: gstack pays off when you complete one loop — **plan → review → ship**. A common first loop: `/office-hours` or `/spec` to shape it, `/plan-eng-review` to lock it, then `/ship`. - -Then run `touch ~/.gstack/.first-loop-tip-shown 2>/dev/null || true`. - -Skip this section if `ACTIVATED` and `FIRST_LOOP_SHOWN` are both `yes`. - -If `HAS_ROUTING` is `no` AND `ROUTING_DECLINED` is `false` AND `PROACTIVE_PROMPTED` is `yes`: -Check if a CLAUDE.md file exists in the project root. If it does not exist, create it. - -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. - -**Conductor rule (read before the MCP rule):** if `CONDUCTOR_SESSION: true` was echoed by the preamble, do NOT call AskUserQuestion at all — neither native nor any `mcp__*__AskUserQuestion` variant. Render EVERY decision brief as the **prose form** below and STOP. This is proactive, not a reaction to a failure: Conductor disables native AUQ and its MCP variant is flaky (it returns `[Tool result missing due to internal error]`), so prose is the reliable path. **Auto-decide preferences still apply first:** if a `[plan-tune auto-decide] →