> ## Documentation Index
> Fetch the complete documentation index at: https://prof-lee.zikun.me/llms.txt
> Use this file to discover all available pages before exploring further.

# The sprint pipeline

> How the 47 skills compose into one continuous flow. Design doc, CEO plan, eng plan, implementation, review, QA, ship, deploy, canary, retro.

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

```mermaid theme={null}
flowchart TD
    A["/office-hours"] -->|design doc| B["/plan-ceo-review"]
    B -->|ceo plan| C["/plan-eng-review"]
    C -->|test plan| D[Implementation]
    D --> E["/review"]
    E -->|review log| F["/qa"]
    F --> G["/ship"]
    G -->|eng review clear| H["/land-and-deploy"]
    H --> I["/canary"]
    I --> J["/retro"]

    C -.test plan read by.-> F

    classDef think fill:#FEF3C7,stroke:#D97706,color:#78350F
    classDef plan fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A
    classDef build fill:#E0E7FF,stroke:#4F46E5,color:#312E81
    classDef test fill:#FAE8FF,stroke:#A855F7,color:#581C87
    classDef ship fill:#D1FAE5,stroke:#0D9488,color:#064E3B
    classDef reflect fill:#FEE2E2,stroke:#EF4444,color:#7F1D1D

    class A think
    class B,C plan
    class D,E build
    class F test
    class G,H,I ship
    class J reflect
```

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

<CardGroup cols={2}>
  <Card title="The design doc" icon="file-pen">
    `~/.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`.
  </Card>

  <Card title="The CEO plan" icon="crown">
    `~/.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.
  </Card>

  <Card title="The test plan" icon="clipboard-list">
    `~/.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.
  </Card>

  <Card title="The review log" icon="square-check">
    `~/.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.
  </Card>
</CardGroup>

## 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.

```text theme={null}
+====================================================================+
|                    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                                 |
+====================================================================+
```

<Info>
  **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.
</Info>

## What each handoff looks like in practice

<AccordionGroup>
  <Accordion title="/office-hours to /plan-ceo-review" icon="arrow-right">
    `/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.
  </Accordion>

  <Accordion title="/plan-eng-review to /qa" icon="arrow-right">
    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.
  </Accordion>

  <Accordion title="/review and /codex to cross-model overlap analysis" icon="arrow-right">
    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).
  </Accordion>

  <Accordion title="/ship to /document-release to PR body" icon="arrow-right">
    `/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.
  </Accordion>

  <Accordion title="/land-and-deploy to /canary to /retro" icon="arrow-right">
    `/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.
  </Accordion>
</AccordionGroup>

## 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.

```text Learning entry (JSONL line) theme={null}
{
  "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"
}
```

<Tip>
  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.
</Tip>

## 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.

<CardGroup cols={2}>
  <Card title="bin/gstack-next-version" icon="hash">
    Queries `gh pr list` plus sibling worktree VERSION files, finds the next unclaimed four-digit slot, returns JSON. `/ship` calls this in Step 12.
  </Card>

  <Card title="bin/gstack-pr-title-rewrite.sh" icon="text-cursor">
    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.
  </Card>

  <Card title="/landing-report" icon="layout-dashboard">
    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.
  </Card>

  <Card title="Continuous checkpoint mode" icon="circle-dot">
    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.
  </Card>
</CardGroup>

Continue to the [verbatim prompts](/prompts) to see the exact instructions inside the biggest specialists, or jump to [philosophy](/philosophy) for the principles that shape every recommendation.