` → **Save** - `/context-save list` → **List** If the user provides a title after the command (e.g., `/context-save auth refactor`), use it as the title. Otherwise, infer a title from the current work. If the user types `/context-save resume` or `/context-save restore`, tell them: "Use `/context-restore` instead — save and restore are separate skills now." --- ## Save flow ### Step 1: Gather state ```bash eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" && mkdir -p ~/.gstack/projects/$SLUG ``` Collect the current working state: ```bash echo "=== BRANCH ===" git rev-parse --abbrev-ref HEAD 2>/dev/null echo "=== STATUS ===" git status --short 2>/dev/null echo "=== DIFF STAT ===" git diff --stat 2>/dev/null echo "=== STAGED DIFF STAT ===" git diff --cached --stat 2>/dev/null echo "=== RECENT LOG ===" git log --oneline -10 2>/dev/null ``` ### Step 2: Summarize context Using the gathered state plus your conversation history, produce a summary covering: 1. **What's being worked on** — the high-level goal or feature 2. **Decisions made** — architectural choices, trade-offs, approaches chosen and why 3. **Remaining work** — concrete next steps, in priority order 4. **Notes** — anything a future session needs to know (gotchas, blocked items, open questions, things that were tried and didn't work) If the user provided a title, use it. Otherwise, infer a concise title (3-6 words) from the work being done. ### Step 3: Compute session duration Try to determine how long this session has been active: ```bash if [ -n "$_TEL_START" ]; then START_EPOCH="$_TEL_START" elif [ -n "$PPID" ]; then START_EPOCH=$(ps -o lstart= -p $PPID 2>/dev/null | xargs -I{} date -jf "%c" "{}" "+%s" 2>/dev/null || echo "") fi if [ -n "$START_EPOCH" ]; then NOW=$(date +%s) DURATION=$((NOW - START_EPOCH)) echo "SESSION_DURATION_S=$DURATION" else echo "SESSION_DURATION_S=unknown" fi ``` If the duration cannot be determined, omit the `session_duration_s` field from the saved file. ### Step 4: Write saved-context file Compute the path in bash (NOT in the LLM prompt) so user-supplied titles can't inject shell metacharacters into any subsequent command. The sanitizer is an allowlist: only `a-z 0-9 - .` survive. ```bash eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" && mkdir -p ~/.gstack/projects/$SLUG eval "$(~/.claude/skills/gstack/bin/gstack-paths)" CHECKPOINT_DIR="$GSTACK_STATE_ROOT/projects/$SLUG/checkpoints" mkdir -p "$CHECKPOINT_DIR" TIMESTAMP=$(date +%Y%m%d-%H%M%S) # Bash-side title sanitize. Pass the raw title as $1 when running this block. # Example: TITLE_RAW="wintermute progress" bash -c '...' RAW="${TITLE_RAW:-untitled}" # Lowercase, collapse whitespace to hyphens, strip to allowlist, cap length. TITLE_SLUG=$(printf '%s' "$RAW" | tr '[:upper:]' '[:lower:]' | tr -s ' \t' '-' | tr -cd 'a-z0-9.-' | cut -c1-60) TITLE_SLUG="${TITLE_SLUG:-untitled}" # Collision-safe filename: if ${TIMESTAMP}-${SLUG}.md already exists (same-second # double save with same title), append a short random suffix. Filenames are # append-only — never overwrite. FILE="${CHECKPOINT_DIR}/${TIMESTAMP}-${TITLE_SLUG}.md" if [ -e "$FILE" ]; then SUFFIX=$(LC_ALL=C tr -dc 'a-z0-9' < /dev/urandom 2>/dev/null | head -c 4 || printf '%04x' "$$") FILE="${CHECKPOINT_DIR}/${TIMESTAMP}-${TITLE_SLUG}-${SUFFIX}.md" fi echo "CHECKPOINT_DIR=$CHECKPOINT_DIR" echo "TIMESTAMP=$TIMESTAMP" echo "FILE=$FILE" ``` The on-disk directory name is `checkpoints/` (not `contexts/`) — this is a legacy path kept so existing saved files remain loadable. Users never see it. Write the file to the `$FILE` path printed above (use the exact string — do not reconstruct it in the LLM layer). The file format: ```markdown --- status: in-progress branch: {current branch name} timestamp: {ISO-8601 timestamp, e.g. 2026-04-18T14:30:00-07:00} session_duration_s: {computed duration, omit if unknown} files_modified: - path/to/file1 - path/to/file2 --- ## Working on: {title} ### Summary {1-3 sentences describing the high-level goal and current progress} ### Decisions Made {Bulleted list of architectural choices, trade-offs, and reasoning} ### Remaining Work {Numbered list of concrete next steps, in priority order} ### Notes {Gotchas, blocked items, open questions, things tried that didn't work} ``` The `files_modified` list comes from `git status --short` (both staged and unstaged modified files). Use relative paths from the repo root. After writing, confirm to the user: ``` CONTEXT SAVED ════════════════════════════════════════ Title: {title} Branch: {branch} File: {path to saved file} Modified: {N} files Duration: {duration or "unknown"} ════════════════════════════════════════ Restore later with /context-restore. ``` --- ## List flow ### Step 1: Gather saved contexts ```bash eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" && mkdir -p ~/.gstack/projects/$SLUG eval "$(~/.claude/skills/gstack/bin/gstack-paths)" CHECKPOINT_DIR="$GSTACK_STATE_ROOT/projects/$SLUG/checkpoints" if [ -d "$CHECKPOINT_DIR" ]; then echo "CHECKPOINT_DIR=$CHECKPOINT_DIR" # Use find + sort instead of ls -1t: filename YYYYMMDD-HHMMSS prefix is the # canonical order (stable across copies/rsync; mtime is not), and empty-result # behavior is clean (no files → no output, no "lists cwd" fallback). find "$CHECKPOINT_DIR" -maxdepth 1 -name "*.md" -type f 2>/dev/null | sort -r else echo "NO_CHECKPOINTS" fi ``` ### Step 2: Display table **Default behavior:** Show saved contexts for the **current branch** only. If the user passes `--all` (e.g., `/context-save list --all`), show contexts from **all branches**. Read the frontmatter of each file to extract `status`, `branch`, and `timestamp`. Parse the title from the filename (the part after the timestamp). Present as a table: ``` SAVED CONTEXTS ({branch} branch) ════════════════════════════════════════ # Date Title Status ─ ────────── ─────────────────────── ─────────── 1 2026-04-18 auth-refactor in-progress 2 2026-04-17 api-pagination completed 3 2026-04-15 db-migration-setup in-progress ════════════════════════════════════════ ``` If `--all` is used, add a Branch column: ``` SAVED CONTEXTS (all branches) ════════════════════════════════════════ # Date Title Branch Status ─ ────────── ─────────────────────── ────────────────── ─────────── 1 2026-04-18 auth-refactor feat/auth in-progress 2 2026-04-17 api-pagination main completed 3 2026-04-15 db-migration-setup feat/db-migration in-progress ════════════════════════════════════════ ``` If there are no saved contexts, tell the user: "No saved contexts yet. Run `/context-save` to save your current working state." --- ## Important Rules - **Never modify code.** This skill only reads state and writes the context file. - **Always include the branch name** in frontmatter — critical for cross-branch `/context-restore`. - **Saved files are append-only.** Never overwrite or delete existing files. Each save creates a new file. - **Infer, don't interrogate.** Use git state and conversation context to fill in the file. Only use AskUserQuestion if the title genuinely cannot be inferred. - **This is a gstack skill, not a Claude Code built-in.** When the user types `/context-save`, invoke this skill via the Skill tool. The old `/checkpoint` name collided with Claude Code's native `/rewind` alias — the rename fixed that. </article></body></html>

--- name: context-save preamble-tier: 2 version: 1.0.0 description: Save working context. (gstack) allowed-tools: - Bash - Read - Write - Glob - Grep - AskUserQuestion triggers: - save progress - save state - save my work - context save --- ## 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 _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 _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":"context-save","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":"context-save","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`. 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] →