CalvinBackup/gstack
1
0
Fork 0
mirror of https://github.com/garrytan/gstack.git synced 2026-05-02 03:35:09 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs(CHANGELOG): correct session-state location — home dir by default, git only on opt-in

Browse Source 
User correction: "wait is our session management really checked into
git? i don't think that's right, isn't it just saved in your home
dir?" Right. I had the location wrong. The default session-save
mechanism (`/context-save` + `/context-restore`) writes markdown
files to `~/.gstack/projects/$SLUG/checkpoints/` — HOME, not git.
Continuous checkpoint mode (opt-in) is what writes git commits.
Previous copy conflated the two and implied "lives in git" as the
default state, which is wrong.

Every affected location updated:

- Headline: "lives in git, not a black box" → "becomes files you
  can grep, not a black box." Removes the false implication that
  session state lands in git by default.
- Lead paragraph: now explicitly names the two separate mechanisms.
  `/context-save` writes plaintext markdown to `~/.gstack/projects/
  $SLUG/checkpoints/` (the default). Continuous checkpoint mode
  (opt-in) additionally drops WIP: commits into the git log.
- Numbers table row: "Session state format" now reads "markdown in
  `~/.gstack/` by default, plus WIP: git commits if you opt into
  continuous mode (parallel track)." Tells the truth about which
  path is default vs opt-in.
- "Most striking" row interpretation: now names both paths. Default
  path = markdown files in home dir. Opt-in continuous mode = WIP:
  commits in project git log. Either way, plain text the user owns.
- "What this means" closer: similarly names both paths explicitly.
  "markdown files in your home directory by default, plus git
  commits if you opt into continuous mode."
- Continuous checkpoint mode Added bullet: clarifies the commits
  land in "your project's git log" (not implied to be the default),
  and notes it runs alongside BOTH Claude Code's built-in session
  management AND the default `/context-save` markdown flow.

No other bullets or sections touched. No content clobbered.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Garry Tan
2026-04-19 14:04:28 +08:00
parent 07bae6cd8d
commit 4a9781f7ec
1 changed files with 6 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CHANGELOG.md
+6 -6
View File
@@ -3,9 +3,9 @@
## [1.3.0.0] - 2026-04-19
## **Your design skills learn your taste.**
## **Your session state lives in git, not a black box.**
## **Your session state becomes files you can grep, not a black box.**
v1.3 is about the things you do every day. `/design-shotgun` now remembers which fonts, colors, and layouts you approve across sessions, so the next round of variants leans toward your actual taste instead of resetting to Inter every time. `/design-consultation` has a "would a human designer be embarrassed by this?" self-gate in Phase 5 and a "what's the one thing someone will remember?" forcing question in Phase 1, AI-slop output gets discarded before it reaches you. Continuous checkpoint mode (flip it on with `gstack-config set checkpoint_mode continuous`) writes session state to git as `WIP:` commits with structured bodies you can grep, review, and restore explicitly. Claude Code already manages its own session state, this is a parallel track you control, portable across tools and branches instead of tied to one agent's internal format.
v1.3 is about the things you do every day. `/design-shotgun` now remembers which fonts, colors, and layouts you approve across sessions, so the next round of variants leans toward your actual taste instead of resetting to Inter every time. `/design-consultation` has a "would a human designer be embarrassed by this?" self-gate in Phase 5 and a "what's the one thing someone will remember?" forcing question in Phase 1, AI-slop output gets discarded before it reaches you. `/context-save` and `/context-restore` write session state to plaintext markdown in `~/.gstack/projects/$SLUG/checkpoints/`, you can read and edit and move between machines. Flip on continuous checkpoint mode (`gstack-config set checkpoint_mode continuous`) and it also drops `WIP:` commits with structured `[gstack-context]` bodies into your git log. Claude Code already manages its own session state, this is a parallel track you control, in formats you own.
### The numbers that matter
@@ -16,15 +16,15 @@ Setup: these come from the v1.3 feature surface. Reproducible via `grep "Generat
| **Design-variant convergence gate** | no requirement | **3 axes required** (font + palette + layout must differ) | **+3** |
| **AI-slop font blacklist** | ~8 fonts | **10+** (added Space Grotesk, system-ui as primary) | **+2+** |
| **Taste memory across `/design-shotgun` rounds** | none | **per-project JSON, 5%/wk decay** | **new** |
| **Session state format** | Claude Code's opaque session store | **git commits + `[gstack-context]` bodies + markdown** (parallel track) | **new** |
| **Session state format** | Claude Code's opaque session store | **markdown in `~/.gstack/` by default, plus `WIP:` git commits if you opt into continuous mode** (parallel track) | **new** |
| **`/context-restore` sources** | markdown files only | **markdown + `[gstack-context]` from WIP commits** | **+1** |
| **Models with behavioral overlays** | 1 (Claude implicit) | **5** (claude, gpt, gpt-5.4, gemini, o-series) | **+4** |
The single most striking row: session state stops being a black box. Claude Code's built-in session management works fine on its own terms, but you can't `grep` it, you can't review it, you can't hand it to a different tool. Continuous mode writes `WIP:` commits with `[gstack-context]` bodies (decisions made, remaining work, failed approaches) that any tool reading git can see. `git log --grep "WIP:"` shows the whole thread. You're in control, not locked in.
The single most striking row: session state stops being a black box. Claude Code's built-in session management works fine on its own terms, but you can't `grep` it, you can't read it, you can't hand it to a different tool. `/context-save` writes markdown to `~/.gstack/projects/$SLUG/checkpoints/` you can open in any editor. Continuous mode (opt-in) also drops `WIP:` commits with structured `[gstack-context]` bodies into your git log, so `git log --grep "WIP:"` shows the whole thread. Either way, plain text you own, not a proprietary store.
### What this means for gstack users
If you're a solo builder or founder shipping a product one sprint at a time, `/design-shotgun` stops handing you the same four variants every time and starts learning which ones you pick. `/design-consultation` stops defaulting to Inter + gray + rounded-corners and forces itself to answer "what's memorable?" before it finishes. Continuous checkpoint mode gives you a parallel, inspectable, portable record of session state that lives alongside Claude Code's own session store rather than replacing it, so when you need to hand work off to a different tool or review what your agent actually decided, it's right there in `git log`. Run `/gstack-upgrade`, try `/design-shotgun` on your next landing page, and approve a variant so the taste engine has a starting signal.
If you're a solo builder or founder shipping a product one sprint at a time, `/design-shotgun` stops handing you the same four variants every time and starts learning which ones you pick. `/design-consultation` stops defaulting to Inter + gray + rounded-corners and forces itself to answer "what's memorable?" before it finishes. `/context-save` and `/context-restore` give you a parallel, inspectable record of session state that lives alongside Claude Code's own, markdown files in your home directory by default, plus git commits if you opt into continuous mode. When you need to hand work off to a different tool or just review what your agent actually decided, you open a file or read `git log`. Run `/gstack-upgrade`, try `/design-shotgun` on your next landing page, and approve a variant so the taste engine has a starting signal.
### Itemized changes
@@ -37,7 +37,7 @@ If you're a solo builder or founder shipping a product one sprint at a time, `/d
#### Session state you can see, grep, and move
- **Continuous checkpoint mode (opt-in, local by default).** Flip it on with `gstack-config set checkpoint_mode continuous` and skills auto-commit your work with `WIP: <description>` prefix and a structured `[gstack-context]` body (decisions made, remaining work, failed approaches). This runs alongside Claude Code's built-in session management, not instead of it, and gives you a git-native track you can `grep`, review, share across tools, and restore explicitly. Push is opt-in via `checkpoint_push=true`, default is local-only so you don't accidentally trigger CI on every WIP commit.
- **Continuous checkpoint mode (opt-in, local by default).** Flip it on with `gstack-config set checkpoint_mode continuous` and skills auto-commit your work with `WIP: <description>` prefix and a structured `[gstack-context]` body (decisions made, remaining work, failed approaches) directly into your project's git log. Runs alongside Claude Code's built-in session management and alongside the default `/context-save` markdown files in `~/.gstack/`. The git-based track is useful when you want `git log --grep "WIP:"` to show you the whole reasoning thread on a branch, or when you want to review what your agent did without opening a file. Push is opt-in via `checkpoint_push=true`, default is local-only so you don't accidentally trigger CI on every WIP commit.
- **`/context-restore` reads WIP commits.** In addition to the markdown saved-context files, `/context-restore` now parses `[gstack-context]` blocks from WIP commits on the current branch. When you want to pick up where you left off with structured decisions and remaining-work in view, it's right there.
- **`/ship` non-destructively squashes WIP commits** before creating the PR. Uses `git rebase --autosquash` scoped to WIP commits only. Non-WIP commits on the branch are preserved. Aborts on conflict with a `BLOCKED` status instead of destroying real work. So you can go wild with `WIP:` commits all week and still ship a clean bisectable PR.