garrytan / garrytan/gstack

[NEW] session-start and session-end skills: session lifecycle management

Open
#2,088 4 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
133k
Forks
19.9k
Avg merge
18h 46m
Merged PRs (30d)
26

Description

## What's missing

gstack covers the full sprint workflow but has no session lifecycle management. Users start sessions without knowing if their state doc is stale, whether the deployed revision matches what they think is live, or what changed in the working tree since they last worked. They end sessions without recording what shipped, what broke, or what the next step is.

The deeper issue (raised in discussion): state doc drift is a symptom. When the agent orchestrates deploy, the deploy step should update the state doc atomically after verify-live — not rely on session-end to reconcile later.

## Proposed skills (layered)

### `/deploy` — primary state writer for deploys

When the agent runs deploy, treat deploy + state update as one flow:

1. test → build → deploy → verify-live (existing gstack pattern)
2. **After verify-live confirms the live revision**, update the state doc with `deployed_version` / revision id
3. If verify fails, neither "deployed" nor the doc gets updated

This prevents the "state doc says v1.2.3 but health endpoint returns v1.2.1" failure mode at the source.

### `/session-start` — reconciliation when deploy wasn't agent-driven

Run at the start of any work session when state may have drifted:

1. Read the canonical state doc (versions, deployed revision, open issues, next up)
2. Run a live check to verify what's actually running matches the doc
3. Check git status and recent commits
4. If the last session didn't end cleanly, reconcile from git history + live checks
5. If the live check disagrees with the state doc, flag it loudly before any work begins

**When this matters:** git push → CI → live with no agent involvement, teammate shipped, manual prod change, or session-end never ran (crash / force-quit).

### `/session-end` — finalization, not the only write point

Run at the end of any significant session:

1. Record durable lessons, close or update open issues, set next steps
2. Targeted edits to stale fields only — not a full rewrite
3. Skip cleanly if nothing significant happened

**Not** the sole point where deploy state gets written. Deploy and other significant events should update state incrementally during the session.

## Why this matters

- **Deploy-owned state** eliminates drift when the agent ships code
- **Session-start verification** catches drift the agent couldn't prevent
- **Incremental writes + session-end finalization** survive crashes and lost connections

## Source

These agents are working and documented in [operating-kit](https://github.com/Sharrmavishal/operating-kit) (`.claude/agents/deploy.md`, `session-start.md`, `session-end.md`). Happy to adapt them to gstack's skill format if this direction is welcome.

Contributor guide

Open the contributing guide

Research direction

Read the linked operating-kit agents (.claude/agents/deploy.md, session-start.md, and session-end.md), then inspect gstack’s existing skill format and deploy flow. Define completion around atomic state updates after verify-live, start-session drift checks, and end-session finalization, with behavior covering failed verification and clean no-op sessions.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
developer-experience, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.