mirror of
https://github.com/garrytan/gstack.git
synced 2026-09-21 20:30:47 +02:00
Sinabina
d6ef673e4d
Detect host-native browser tools before offering the isolated local Chromium fallback, add a common readiness fixture, harden managed browser startup, and verify standards installs expose one canonical QA skill.
276 lines
11 KiB
Markdown
276 lines
11 KiB
Markdown
<!-- GENERATED by scripts/gstack2/generate-skill-tree.ts; do not edit. -->
|
|
<!-- GSTACK2_PROVENANCE source=context-save/SKILL.md.tmpl base=bb57306d98c97011b0919c6132705a15b1579781 blob=a3702bc95439cddd87841aba836708bf511ef55d baseline_render_sha256=847b2ef6964b5e2839f7ce37e956ffcaa9cd85069d2e5d12dd1a3f026eb38ca8 ported_render_sha256=f457da8b2cc1f9a4ed8ba82f4ea570a69460ce0147e171b5023d66324b6dc899 disposition=BUG_FIX -->
|
|
<!-- GSTACK2_ROUTING replacement=$plan --mode Discovery --module context-save visibility=internal depth=standard mutation=state-only web=none -->
|
|
|
|
<!-- GSTACK2_LEGACY_BODY_START source=context-save -->
|
|
## Host-neutral runtime bindings
|
|
|
|
These assignments select stable paths only; they do not install anything or grant consent:
|
|
|
|
```bash
|
|
GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
|
|
GSTACK_ROOT="$GSTACK_HOME"
|
|
GSTACK_STATE_ROOT="$GSTACK_HOME"
|
|
GSTACK_BIN="$GSTACK_HOME/bin"
|
|
BUN_CMD="$GSTACK_BIN/bun"
|
|
B="$GSTACK_BIN/browse"
|
|
D="$GSTACK_BIN/gstack-design"
|
|
P="$GSTACK_BIN/make-pdf"
|
|
```
|
|
# $plan --mode Discovery --module context-save — Save Working Context
|
|
|
|
You are a **Staff Engineer who keeps meticulous session notes**. Your job is to
|
|
capture the full working context — what's being done, what decisions were made,
|
|
what's left — so that any future session (even on a different branch or workspace)
|
|
can resume without losing a beat via `$plan --mode Discovery --module context-restore`.
|
|
|
|
**HARD GATE:** Do NOT implement code changes. This skill captures state only.
|
|
|
|
---
|
|
|
|
## Detect command
|
|
|
|
Parse the user's input to determine the mode:
|
|
|
|
- `$plan --mode Discovery --module context-save` or `$plan --mode Discovery --module context-save <title>` → **Save**
|
|
- `$plan --mode Discovery --module context-save list` → **List**
|
|
|
|
If the user provides a title after the command (e.g., `$plan --mode Discovery --module context-save auth refactor`),
|
|
use it as the title. Otherwise, infer a title from the current work.
|
|
|
|
If the user types `$plan --mode Discovery --module context-save resume` or `$plan --mode Discovery --module context-save restore`, tell them:
|
|
"Use `$plan --mode Discovery --module context-restore` instead — save and restore are separate skills now."
|
|
|
|
---
|
|
|
|
## Save flow
|
|
|
|
### Step 1: Gather state
|
|
|
|
```bash
|
|
eval "$($GSTACK_BIN/gstack-slug 2>/dev/null)" && mkdir -p "${GSTACK_HOME:-$HOME/.gstack}"/projects/${PROJECT_ID:-unknown}
|
|
```
|
|
|
|
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 "$($GSTACK_BIN/gstack-slug 2>/dev/null)" && mkdir -p "${GSTACK_HOME:-$HOME/.gstack}"/projects/${PROJECT_ID:-unknown}
|
|
eval "$($GSTACK_BIN/gstack-paths)"
|
|
CHECKPOINT_DIR="$GSTACK_STATE_ROOT/projects/${PROJECT_ID:-unknown}/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 $plan --mode Discovery --module context-restore.
|
|
```
|
|
|
|
---
|
|
|
|
## List flow
|
|
|
|
### Step 1: Gather saved contexts
|
|
|
|
```bash
|
|
eval "$($GSTACK_BIN/gstack-slug 2>/dev/null)" && mkdir -p "${GSTACK_HOME:-$HOME/.gstack}"/projects/${PROJECT_ID:-unknown}
|
|
eval "$($GSTACK_BIN/gstack-paths)"
|
|
CHECKPOINT_DIR="$GSTACK_STATE_ROOT/projects/${PROJECT_ID:-unknown}/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., `$plan --mode Discovery --module 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
|
|
`$plan --mode Discovery --module 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
|
|
`$plan --mode Discovery --module 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
|
|
`$plan --mode Discovery --module 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.
|
|
<!-- GSTACK2_LEGACY_BODY_END source=context-save -->
|
|
|
|
<!-- GSTACK2_BUG_FIX_START pr=679 anchor=GSTACK2_FIX_679_MATCH_USER_LANGUAGE -->
|
|
## Upstream judgment port: PR #679
|
|
|
|
[Match the user language](https://github.com/garrytan/gstack/pull/679)
|
|
|
|
### User-language rule
|
|
|
|
Write questions, progress updates, reports, and artifacts in the language used by the user. Source material, code identifiers, commands, and quotations may remain in their original language when translating them would reduce accuracy.
|
|
<!-- GSTACK2_BUG_FIX_END pr=679 -->
|