Skip to main content

Documentation Index

Fetch the complete documentation index at: https://zikun.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

gstack runs as a phase model. Think, then Plan, then Build, then Review, then Test, then Ship, then Reflect. Each phase writes an artifact to disk that the next phase reads automatically. No CLI flags. No copy-paste between skills. The hand-off is the filesystem.

​
The full pipeline

Solid arrows are sequential. The dashed arrow shows a file read that crosses phases (the test plan that /plan-eng-review writes is the same file that /qa reads later, without any direct handoff between them). The next sections describe what flows through each arrow.

​
Where the artifacts live

The design doc

~/.gstack/projects/$SLUG/$USER-$BRANCH-design-$DATETIME.md. Written by /office-hours at the end of Phase 5. Auto-discovered by /plan-ceo-review and /plan-eng-review via ls -t.

The CEO plan

~/.gstack/projects/$SLUG/ceo-plans/{date}-{feature-slug}.md. Written by /plan-ceo-review after the user picks Expansion or Selective Expansion mode. Promotable to docs/designs/ in the repo for team visibility.

The test plan

~/.gstack/projects/$SLUG/*-test-plan-*.md. Written by /plan-eng-review at the end of Section 3 (test review). Auto-discovered by /qa and /qa-only before they fall back to git-diff heuristics.

The review log

~/.gstack/projects/$SLUG/*-reviews.jsonl. Appended by every plan-review skill and by /review itself. Powers the Review Readiness Dashboard that /ship reads as a gate.

​
The Review Readiness Dashboard

At the end of every plan-review skill the model renders a dashboard table. /ship reads the same data to decide whether to block, warn, or proceed. 
+====================================================================+
|                    REVIEW READINESS DASHBOARD                       |
+====================================================================+
| Review          | Runs | Last Run            | Status    | Required |
|-----------------|------|---------------------|-----------|----------|
| Eng Review      |  1   | 2026-03-16 15:00    | CLEAR     | YES      |
| CEO Review      |  1   | 2026-03-16 14:30    | CLEAR     | no       |
| Design Review   |  0   | -                   | -         | no       |
+--------------------------------------------------------------------+
| VERDICT. CLEARED. Eng Review passed                                 |
+====================================================================+
Engineering review is the only required gate. CEO and Design reviews are informational. Recommended for product changes and UI changes respectively, but /ship will not block on their absence. Disable the Eng-review gate entirely with gstack-config set skip_eng_review true if your team has its own.

​
What each handoff looks like in practice

/office-hours ends Phase 5 with a Write call to ~/.gstack/projects/$SLUG/$USER-$BRANCH-design-$DATETIME.md. Then it tells the user. “Design doc saved to: {full path}. Other skills (/plan-ceo-review, /plan-eng-review) will find it automatically.”/plan-ceo-review runs ls -t ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md | head -1 at the start of its PRE-REVIEW SYSTEM AUDIT. If a doc is found, the model reads it and uses it as the source of truth for the problem statement, constraints, and chosen approach. If the doc has a Supersedes: field, the model also reads the prior version to understand what changed.
When /plan-eng-review finishes Section 3 (Test Review), it writes a test plan artifact named ~/.gstack/projects/$SLUG/$USER-$BRANCH-test-plan-$DATETIME.md containing the test diagram, failure modes registry, and per-codepath coverage gaps./qa checks for that artifact before falling back to git-diff heuristics. If found, the model reads it and uses the listed test cases as the QA plan. The eng review’s test diagram becomes the QA’s checklist.
Both /review (Claude’s perspective) and /codex (OpenAI’s perspective via the Codex CLI) log their findings to ~/.gstack/projects/$SLUG/*-reviews.jsonl with a fingerprint per finding (sha256 of category:file:line).When both have run on the same commit, the next invocation of either produces a cross-model overlap table. Which findings both caught (high confidence). Which were unique to Claude (different blind spot). Which were unique to Codex (different training).
/ship Step 18 dispatches /document-release as a subagent after the code is pushed but before the PR is created. The subagent reads every .md in the repo, cross-references the diff, updates README, ARCHITECTURE, CONTRIBUTING, CLAUDE.md as needed, commits the doc updates, and returns a JSON object with documentation_section. Markdown to embed in the PR body.Step 19 then creates the PR in one call with the complete body baked in, including the documentation section. No create-then-edit dance.
/land-and-deploy merges the PR, waits for CI, waits for the deploy platform to report success, then runs /canary against the production URL for an initial smoke check./canary keeps running on a loop (configurable duration, default 10 minutes) and writes per-cycle results to .gstack/canary-reports/. Anomalies (new console errors, p95 latency regressions, page failures) surface as alerts./retro reads ~/.gstack/projects/$SLUG/$BRANCH-reviews.jsonl for ship metrics, plus ~/.gstack/projects/$SLUG/timeline.jsonl for session events, plus git log for commit data, and produces the weekly retrospective.

​
Learnings compound across sessions

Every tier-2-or-higher skill ends with a {{LEARNINGS_LOG}} block that instructs the model to write a structured learning entry to ~/.gstack/projects/$SLUG/learnings.jsonl. The entry has a key, an insight, a confidence score, a source (“observed”, “inferred”, “user-confirmed”), and the list of files it references. Future skill invocations run {{LEARNINGS_SEARCH}} at the appropriate point in the prompt. /investigate searches by hypothesis keyword. /qa searches by component name. /ship searches by feature noun. When a relevant prior learning surfaces, the model is instructed to say “Prior learning applied: …” before making the recommendation.
Learning entry (JSONL line)
{
  "skill": "investigate",
  "type": "investigation",
  "key": "auth-cookie-domain-mismatch",
  "insight": "Cross-subdomain cookies require explicit domain=.example.com",
  "confidence": 9,
  "source": "observed",
  "files": ["src/auth/middleware.ts", "src/auth/cookies.ts"],
  "ts": "2026-03-16T14:30:00Z"
}
This is the mechanism by which the system gets smarter on a specific codebase over time. A bug fixed in March creates a learning. A similar bug in May surfaces the same learning before any code is written. /learn is the user-facing way to review, prune, or export these.

​
Parallel sprints

gstack is designed for 10 to 15 parallel sprints. The mechanism is git worktrees plus a queue-aware version-bumping utility. bin/gstack-next-version queries open PRs and active sibling worktree VERSION files, then assigns the next free slot when /ship runs.

bin/gstack-next-version

Queries gh pr list plus sibling worktree VERSION files, finds the next unclaimed four-digit slot, returns JSON. /ship calls this in Step 12.

bin/gstack-pr-title-rewrite.sh

Enforces that every PR title starts with v$NEW_VERSION. Single source of truth for the format rule. Idempotent. Running it on an already-correct title is a no-op.

/landing-report

Read-only dashboard of which VERSION slots are claimed by open PRs and which sibling worktrees have WIP. Useful before kicking off a new sprint to know what slot you will land in.

Continuous checkpoint mode

Opt-in via gstack-config set checkpoint_mode continuous. Skills auto-commit work-in-progress with a WIP: prefix and a structured [gstack-context] body. /ship filter-squashes WIP commits before opening the PR.
Continue to the verbatim prompts to see the exact instructions inside the biggest specialists, or jump to philosophy for the principles that shape every recommendation.