_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)
_PROACTIVE=$(~/.claude/skills/gstack/bin/gstack-config get proactive 2>/dev/null || echo "true")
_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
echo "BRANCH: $_BRANCH"
echo "PROACTIVE: $_PROACTIVE"
_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"
mkdir -p ~/.gstack/analytics
echo '{"skill":"land-and-deploy","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
for _PF in ~/.gstack/analytics/.pending-*; do [ -f "$_PF" ] && ~/.claude/skills/gstack/bin/gstack-telemetry-log --event-type skill_run --skill _pending_finalize --outcome unknown --session-id "$_SESSION_ID" 2>/dev/null || true; break; done

PROACTIVE

"false"

UPGRADE_AVAILABLE <old> <new>

~/.claude/skills/gstack/gstack-upgrade/SKILL.md

JUST_UPGRADED <from> <to>

LAKE_INTRO

no

open https://garryslist.org/posts/boil-the-ocean
touch ~/.gstack/.completeness-intro-seen

open

touch

TEL_PROMPTED

no

LAKE_INTRO

yes

Help gstack get better! Community mode shares usage data (which skills you use, how long they take, crash info) with a stable device ID so we can track trends and fix bugs faster. No code, file paths, or repo names are ever sent. Change anytime with

gstack-config set telemetry off

.

• A) Help gstack get better! (recommended)
• B) No thanks

~/.claude/skills/gstack/bin/gstack-config set telemetry community

How about anonymous mode? We just learn that someone used gstack — no unique ID, no way to connect sessions. Just a counter that helps us know if anyone's out there.

• A) Sure, anonymous is fine
• B) No thanks, fully off

~/.claude/skills/gstack/bin/gstack-config set telemetry anonymous

~/.claude/skills/gstack/bin/gstack-config set telemetry off

touch ~/.gstack/.telemetry-prompted

TEL_PROMPTED

yes

1. Re-ground: State the project, the current branch (use the

   _BRANCH

   value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
2. Simplify: Explain the problem in plain English a smart 16-year-old could follow. No raw function names, no internal jargon, no implementation details. Use concrete examples and analogies. Say what it DOES, not what it's called.
3. Recommend:

   RECOMMENDATION: Choose [X] because [one-line reason]

   — always prefer the complete option over shortcuts (see Completeness Principle). Include

   Completeness: X/10

   for each option. Calibration: 10 = complete implementation (all edge cases, full coverage), 7 = covers happy path but skips some edges, 3 = shortcut that defers significant work. If both options are 8+, pick the higher; if one is ≤5, flag it.
4. Options: Lettered options:

   A) ... B) ... C) ...

   — when an option involves effort, show both scales:

   (human: ~X / CC: ~Y)

• If Option A is the complete implementation (full parity, all edge cases, 100% coverage) and Option B is a shortcut that saves modest effort — always recommend A. The delta between 80 lines and 150 lines is meaningless with CC+gstack. "Good enough" is the wrong instinct when "complete" costs minutes more.
• Lake vs. ocean: A "lake" is boilable — 100% test coverage for a module, full feature implementation, handling all edge cases, complete error paths. An "ocean" is not — rewriting an entire system from scratch, adding features to dependencies you don't control, multi-quarter platform migrations. Recommend boiling lakes. Flag oceans as out of scope.
• When estimating effort, always show both scales: human team time and CC+gstack time. The compression ratio varies by task type — use this reference:

• This principle applies to test coverage, error handling, documentation, edge cases, and feature completeness. Don't skip the last 10% to "save time" — with AI, that 10% costs seconds.

• BAD: "Choose B — it covers 90% of the value with less code." (If A is only 70 lines more, choose A.)
• BAD: "We can skip edge case handling to save time." (Edge case handling costs minutes with CC.)
• BAD: "Let's defer test coverage to a follow-up PR." (Tests are the cheapest lake to boil.)
• BAD: Quoting only human-team effort: "This would take 2 weeks." (Say: "2 weeks human / ~1 hour CC.")

~/.claude/skills/gstack/ETHOS.md

• Layer 1 (tried and true — in distribution). Don't reinvent the wheel. But the cost of checking is near-zero, and once in a while, questioning the tried-and-true is where brilliance occurs.
• Layer 2 (new and popular — search for these). But scrutinize: humans are subject to mania. Search results are inputs to your thinking, not answers.
• Layer 3 (first principles — prize these above all). Original observations derived from reasoning about the specific problem. The most valuable of all.

jq -n --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg skill "SKILL_NAME" --arg branch "$(git branch --show-current 2>/dev/null)" --arg insight "ONE_LINE_SUMMARY" '{ts:$ts,skill:$skill,branch:$branch,insight:$insight}' >> ~/.gstack/analytics/eureka.jsonl 2>/dev/null || true

1. {step}

• DONE — All steps completed successfully. Evidence provided for each claim.
• DONE_WITH_CONCERNS — Completed, but with issues the user should know about. List each concern.
• BLOCKED — Cannot proceed. State what is blocking and what was tried.
• NEEDS_CONTEXT — Missing information required to continue. State exactly what you need.

• If you have attempted a task 3 times without success, STOP and escalate.
• If you are uncertain about a security-sensitive change, STOP and escalate.
• If the scope of work exceeds what you can verify, STOP and escalate.

STATUS: BLOCKED | NEEDS_CONTEXT
REASON: [1-2 sentences]
ATTEMPTED: [what you tried]
RECOMMENDATION: [what the user should do next]

_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
B=""
[ -n "$_ROOT" ] && [ -x "$_ROOT/.claude/skills/gstack/browse/dist/browse" ] && B="$_ROOT/.claude/skills/gstack/browse/dist/browse"
[ -z "$B" ] && B=~/.claude/skills/gstack/browse/dist/browse
if [ -x "$B" ]; then
  echo "READY: $B"
else
  echo "NEEDS_SETUP"
fi

NEEDS_SETUP

1. Tell the user: "gstack browse needs a one-time build (~10 seconds). OK to proceed?" Then STOP and wait.
2. Run:

   cd <SKILL_DIR> && ./setup

3. If

   bun

   is not installed:

   curl -fsSL https://bun.sh/install | bash

1. Check if a PR already exists for this branch:

   gh pr view --json baseRefName -q .baseRefName

   If this succeeds, use the printed branch name as the base branch.
2. If no PR exists (command fails), detect the repo's default branch:

   gh repo view --json defaultBranchRef -q .defaultBranchRef.name

3. If both commands fail, fall back to

   main

   .

git diff

git log

git fetch

git merge

gh pr create

• /land-and-deploy

  — auto-detect PR from current branch, no post-deploy URL

• /land-and-deploy <url>

  — auto-detect PR, verify deploy at this URL

• /land-and-deploy #123

  — specific PR number

• /land-and-deploy #123 <url>

  — specific PR + verification URL

/land-and-deploy

• Pre-merge readiness gate (Step 3.5) — this is the ONE confirmation before merge
• GitHub CLI not authenticated
• No PR found for this branch
• CI failures or merge conflicts
• Permission denied on merge
• Deploy workflow failure (offer revert)
• Production health issues detected by canary (offer revert)

• Choosing merge method (auto-detect from repo settings)
• Timeout warnings (warn and continue gracefully)

1. Check GitHub CLI authentication:

gh auth status

gh auth login

1. Parse arguments. If the user specified

   #NNN

   , use that PR number. If a URL was provided, save it for canary verification in Step 7.
2. If no PR number specified, detect from current branch:

gh pr view --json number,state,title,url,mergeStateStatus,mergeable,baseRefName,headRefName

1. Validate the PR state:
   • If no PR exists: STOP. "No PR found for this branch. Run

     /ship

     first to create one."
   • If

     state

     is

     MERGED

     : "PR is already merged. Nothing to do."
   • If

     state

     is

     CLOSED

     : "PR is closed (not merged). Reopen it first."
   • If

     state

     is

     OPEN

     : continue.

gh pr checks --json name,state,status,conclusion

1. If any required checks are FAILING: STOP. Show the failing checks.
2. If required checks are PENDING: proceed to Step 3.
3. If all checks pass (or no required checks): skip Step 3, go to Step 4.

gh pr view --json mergeable -q .mergeable

CONFLICTING

~/.claude/skills/gstack/bin/gstack-review-read 2>/dev/null

1. Find the most recent entry within the last 7 days.
2. Extract its

   commit

   field.
3. Compare against current HEAD:

   git rev-list --count STORED_COMMIT..HEAD

• 0 commits since review → CURRENT
• 1-3 commits since review → RECENT (yellow if those commits touch code, not just docs)
• 4+ commits since review → STALE (red — review may not reflect current code)
• No review found → NOT RUN

git log --oneline STORED_COMMIT..HEAD

bun test

bun test 2>&1 | tail -10

ls -t ~/.gstack-dev/evals/*-e2e-*-$(date +%Y-%m-%d)*.json 2>/dev/null | head -20

• Total tests, pass count, fail count
• How long ago the run finished (from file timestamp)
• Total cost
• Names of any failing tests

ls -t ~/.gstack-dev/evals/*-llm-judge-*-$(date +%Y-%m-%d)*.json 2>/dev/null | head -5

gh pr view --json body -q .body

git log --oneline $(gh pr view --json baseRefName -q .baseRefName 2>/dev/null || echo main)..HEAD | head -20

1. Missing features — commits that add significant functionality not mentioned in the PR
2. Stale descriptions — PR body mentions things that were later changed or reverted
3. Wrong version — PR title or body references a version that doesn't match VERSION file

╔══════════════════════════════════════════════════════════╗
║              PRE-MERGE READINESS REPORT                  ║
╠══════════════════════════════════════════════════════════╣
║                                                          ║
║  PR: #NNN — title                                        ║
║  Branch: feature → main                                  ║
║                                                          ║
║  REVIEWS                                                 ║
║  ├─ Eng Review:    CURRENT / STALE (N commits) / —       ║
║  ├─ CEO Review:    CURRENT / — (optional)                ║
║  ├─ Design Review: CURRENT / — (optional)                ║
║  └─ Codex Review:  CURRENT / — (optional)                ║
║                                                          ║
║  TESTS                                                   ║
║  ├─ Free tests:    PASS / FAIL (blocker)                 ║
║  ├─ E2E tests:     52/52 pass (25 min ago) / NOT RUN     ║
║  └─ LLM evals:     PASS / NOT RUN                        ║
║                                                          ║
║  DOCUMENTATION                                           ║
║  ├─ CHANGELOG:     Updated / NOT UPDATED (warning)       ║
║  ├─ VERSION:       0.9.8.0 / NOT BUMPED (warning)        ║
║  └─ Doc release:   Run / NOT RUN (warning)               ║
║                                                          ║
║  PR BODY                                                 ║
║  └─ Accuracy:      Current / STALE (warning)             ║
║                                                          ║
║  WARNINGS: N  |  BLOCKERS: N                             ║
╚══════════════════════════════════════════════════════════╝

• Re-ground: "About to merge PR #NNN (title) from branch X to Y. Here's the readiness report." Show the report above.
• List each warning and blocker explicitly.
• RECOMMENDATION: Choose A if green. Choose B if there are significant warnings. Choose C only if the user understands the risks.
• A) Merge — readiness checks passed (Completeness: 10/10)
• B) Don't merge yet — address the warnings first (Completeness: 10/10)
• C) Merge anyway — I understand the risks (Completeness: 3/10)

• If reviews are stale: "Re-run /plan-eng-review (or /review) to review current code."
• If E2E not run: "Run

  bun run test:e2e

  to verify."
• If docs not updated: "Run /document-release to update documentation."
• If PR body stale: "Update the PR body to reflect current changes."

If `PERSISTED_PLATFORM` and `PERSISTED_URL` were found in CLAUDE.md, use them directly
and skip manual detection. If no persisted config exists, use the auto-detected platform
to guide deploy verification. If nothing is detected, ask the user via AskUserQuestion
in the decision tree below.

If you want to persist deploy settings for future runs, suggest the user run `/setup-deploy`.

Then run `gstack-diff-scope` to classify the changes:

```bash
eval $(~/.claude/skills/gstack/bin/gstack-diff-scope $(gh pr view --json baseRefName -q .baseRefName 2>/dev/null || echo main) 2>/dev/null)
echo "FRONTEND=$SCOPE_FRONTEND BACKEND=$SCOPE_BACKEND DOCS=$SCOPE_DOCS CONFIG=$SCOPE_CONFIG"

1. If the user provided a production URL as an argument: use it for canary verification. Also check for deploy workflows.
2. Check for GitHub Actions deploy workflows:

gh run list --branch <base> --limit 5 --json name,status,conclusion,headSha,workflowName

1. If SCOPE_DOCS is the only scope that's true (no frontend, no backend, no config): skip verification entirely. Output: "PR merged. Documentation-only change — no deploy verification needed." Go to Step 9.
2. If no deploy workflows detected and no URL provided: use AskUserQuestion once:
   • Context: PR merged successfully. No deploy workflow or production URL detected.
   • RECOMMENDATION: Choose B if this is a library/CLI tool. Choose A if this is a web app.
   • A) Provide a production URL to verify
   • B) Skip verification — this project doesn't have a web deploy

conclusion

success

conclusion

failure

• Context: Deploy workflow failed after merging PR.
• RECOMMENDATION: Choose A to investigate before reverting.
• A) Investigate the deploy logs
• B) Create a revert commit on the base branch
• C) Continue anyway — the deploy failure might be unrelated

$B goto

$B goto <url>

$B console --errors

Error

Uncaught

Failed to load

TypeError

ReferenceError

$B perf

$B text

$B snapshot -i -a -o ".gstack/deploy-reports/post-deploy.png"

• Page loads successfully with 200 status → PASS
• No critical console errors → PASS
• Page has real content (not blank or error screen) → PASS
• Loads in under 10 seconds → PASS

• Context: Post-deploy canary detected issues on the production site.
• RECOMMENDATION: Choose based on severity — B for critical (site down), A for minor (console errors).
• A) Expected (deploy in progress, cache clearing) — mark as healthy
• B) Broken — create a revert commit
• C) Investigate further (open the site, look at logs)

• If a production URL was verified: "Run

  /canary <url> --duration 10m

  for extended monitoring."
• If performance data was collected: "Run

  /benchmark <url>

  for a deep performance audit."
• "Run

  /document-release

  to update project documentation."

• Never force push. Use

  gh pr merge

  which is safe.
• Never skip CI. If checks are failing, stop.
• Auto-detect everything. PR number, merge method, deploy strategy, project type. Only ask when information genuinely can't be inferred.
• Poll with backoff. Don't hammer GitHub API. 30-second intervals for CI/deploy, with reasonable timeouts.
• Revert is always an option. At every failure point, offer revert as an escape hatch.
• Single-pass verification, not continuous monitoring.

  /land-and-deploy

  checks once.

  /canary

  does the extended monitoring loop.
• Clean up. Delete the feature branch after merge (via

  --delete-branch

  ).
• The goal is: user says

  /land-and-deploy

  , next thing they see is the deploy report.