# Gzship

> Use when building a feature end-to-end, taking an idea or product request from a BDD scenario through to shipped code, or doing BDD/TDD feature work on a feature branch.

- **Type:** Skill
- **Install:** `agentstack add skill-gzaripov-agent-skills-gzship`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [gzaripov](https://agentstack.voostack.com/s/gzaripov)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [gzaripov](https://github.com/gzaripov)
- **Source:** https://github.com/gzaripov/agent-skills/tree/main/skills/gzship

## Install

```sh
agentstack add skill-gzaripov-agent-skills-gzship
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

Carry one feature from a BDD scenario, through architecture and design, into a staged TDD implementation on a feature branch. Outside-in: behavior first, architecture second, code last.

## Prerequisites

- The `critique-loop` skill is installed — it is the review engine for every gate.
- The `plannotator` CLI is installed and runnable (`plannotator --help`) — it runs the developer-review gates.
- The working directory is a git repository on a feature branch (not `main`/`master`).
- `d2` is optional; see **D2 handling** for the fallback when it is absent.

## Core principle

**Every phase produces exactly one artifact, and no phase advances until both the navigator (cross-model review) and the developer have approved that artifact.**

Violating the letter of a gate is violating the spirit of the process — a navigator APPROVE is never a substitute for developer approval. They are two separate, both-required gates.

## The 8 phases

### Phase 0 — Frame & track
Derive a kebab-case `` from the request. Create `docs/features//`. Confirm the working directory is a git repo on a feature branch (not `main`/`master`). Create a Task/Todo list with one entry per phase **and per gate** — the developer watches this list.

### Phase 1 — Discovery & Scenarios (BDD)
**REQUIRED BACKGROUND:** `references/scenarios.md` — read before writing scenarios.

Dispatch parallel `Explore` subagents to survey where the feature lands and what it touches. Before drafting any scenario, grep prior PRDs for canonical domain terms (`grep -l "^## Domain Terms" docs/features/*/prd.md`) and reuse them — see `references/scenarios.md` § *Before you write*. Synthesize the survey. Write `docs/features//scenarios.md` — declarative `Given/When/Then`, ubiquitous language, one observable behavior per scenario, plus a "How it lands in the product" section.

### Phase 2 — PRD Synthesis
**REQUIRED BACKGROUND:** `references/prd.md` — read before writing the PRD.

Synthesize the conversation, the survey, and `scenarios.md` into `docs/features//prd.md`. Do **not** re-interview the developer in this phase; surface gaps as Open Questions for the gate.

The PRD must include **all** of these required sections (see `references/prd.md` for format detail):

- **`## Stakeholders Consulted`** — one line per voice that actually shaped this PRD. *"Primary developer (solo)"* is a valid entry; the rule is honesty, not breadth.
- **`## Quality Targets`** — numeric NFRs (latency p95, RPS, data volume, availability %, durability class), tied to scenarios where applicable. Adjectives like "fast" or "scalable" without numbers are rejected at the gate.
- **`## Constraints`** — explicit rails the design must respect (stack, deadline, regulatory, budget, team).
- **`## Domain Terms`** — canonical vocabulary for every domain concept the feature touches, with rejected aliases under `_Avoid_:`. If deliberately redefining a term from a prior PRD, list it in **`## Aliased Terms`** with the prior PRD's path.

Each User Story is tagged with the scenarios in `scenarios.md` that verify it.

### Phase 3 — Product Review Gate (two approvals)
**REQUIRED SUB-SKILL:** `critique-loop` (review-only flow).

Reviews `scenarios.md` and `prd.md` together — they are one product framing, gated as one.

1. **Navigator review** — run `critique-loop`'s review-only flow against both files with slug `-product` (see **Calling critique-loop**). Resolve code/scope asks directly; surface product asks to the developer.
2. **Developer review** — run `plannotator annotate docs/features//scenarios.md` and `plannotator annotate docs/features//prd.md`. Address **every** returned annotation on each. An inline chat message is not this gate.
3. Advance to Phase 4 only after both an APPROVE verdict and **explicit** developer approval on both files.

### Phase 4 — Architecture & Design
**REQUIRED BACKGROUND:** `references/architecture.md` — read before surveying, diagramming, or considering ADRs.

Dispatch parallel subagents to survey the existing architecture, and skim any existing entries in `docs/adr/` that touch this area. Draft the architecture diagram in **both D2 and Mermaid**, render each, **look at both renders and keep whichever reads more clearly** (never embed a diagram you have not looked at) — see `references/architecture.md`. Embed the chosen diagram in `design.md`: a ` ```mermaid ` block (GitHub renders it inline) or the rendered D2 SVGs.

Write `docs/features//design.md`. It must include **all** of these required sections (see `references/architecture.md` § *The design document* for format detail):

- **`## System Analysis`** — the as-is: modules in the path, key flow as-is, current load vs. PRD Quality Targets, prior art.
- **`## Components & interfaces`** + **`## Data flow`** — the to-be.
- **`## Integration & Data Ownership`** — per cross-module call: sync REST / async event / streaming / shared DB and *why*; per entity: owner, projections, consistency model.
- **`## Alternatives considered`** (incl. "do nothing") and **`## Tradeoffs`**.
- **`## Risks`** — table linking each risk to the scenario it threatens, the Quality Target it hits, and a mitigation (or an explicit *accept-as-is*).

The implementation slice breakdown does **not** live here — it is the Phase 6 deliverable (`plan.md`). The design feeds the plan; the plan does not feed back into the design.

For any decision that meets **all three** ADR criteria — hard-to-reverse, surprising-without-context, the result of a real trade-off — write a new entry under `docs/adr/NNNN-.md` (sequential numbering; lazily create `docs/adr/` if missing). Most design decisions do not warrant an ADR; offer one only when all three are true. The tight 1–3-sentence template is the default; add the optional **Revisit conditions** section when the trigger to reopen the decision is nameable. See `references/architecture.md` § *Architecture Decision Records*.

ADRs and `design.md` are **bidirectionally linked**: each new ADR's header carries an `Originating feature: docs/features//` backlink, and `design.md` gains an `## ADRs produced` section listing every ADR this feature wrote. ADRs are committed alongside `design.md` in the same `docs:` commit; both directions of the link land together and are reviewed at the Phase 5 gate.

### Phase 5 — Design Review Gate (two approvals)
Same shape as Phase 3:
1. **Navigator review** — `critique-loop` review-only flow on `design.md` (and any new ADRs) with slug `-design` (see **Calling critique-loop**). Resolve code/scope asks directly; surface architecture and product tradeoffs to the developer.
2. **Developer review** — `plannotator annotate docs/features//design.md`; address every annotation.
3. Advance to Phase 6 only after both an APPROVE verdict and explicit developer approval.

### Phase 6 — Plan Synthesis
**REQUIRED BACKGROUND:** `references/plan.md` — read before decomposing into slices.

Decompose the approved `design.md` into **vertical-slice tracer bullets** and write `docs/features//plan.md`. Each slice cuts every layer the feature touches (schema → API → logic → UI → tests) and is independently demoable. Per slice: title, AFK/HITL tag, blocked-by, stories covered (from `prd.md`), risks addressed (from `design.md` § Risks), behavioral description, and acceptance criteria as a checklist. The **first slice is the tracer bullet** — the thinnest end-to-end path that proves the system wires up. Subsequent slices thicken behavior along that path.

Horizontal slicing — "all schema first, then all API, then all UI" — is explicitly forbidden; see `references/plan.md` for the rationale.

### Phase 7 — Plan Review Gate (two approvals)
Same shape as Phase 5:
1. **Navigator review** — `critique-loop` review-only flow on `plan.md` with slug `-plan` (see **Calling critique-loop**). Resolve code/scope asks directly; surface ordering and HITL-resolution asks to the developer.
2. **Developer review** — `plannotator annotate docs/features//plan.md`; address every annotation.
3. Advance to Phase 8 only after both an APPROVE verdict and explicit developer approval.

### Phase 8 — Staged Implementation
**REQUIRED BACKGROUND:** `references/implementation.md` — read before the first slice.

For each slice in `plan.md`, run the double-loop TDD cycle:
1. **Tests first** — acceptance test (outer loop, RED) anchored to the slice's acceptance criteria, then unit tests (inner loop, RED).
2. **Code** — minimal code to green, then refactor.
3. **Review** — `critique-loop` review-only flow on the slice diff with slug `-slice-N`; resolve asks. This is a navigator-only review, **not** a phase gate — it has no Plannotator developer-review leg.
4. **Proceed** — tick the slice's acceptance-criteria boxes in `plan.md`, mark the task done, move on.

After the final slice, run one `critique-loop` review of the whole feature diff with slug `-final`. Handle its verdict exactly as the flowchart dictates — resolve `CHANGES_REQUESTED`, surface `BLOCK`. On APPROVE, produce a summary report: the feature branch is then ready for the developer to open a PR or merge. Opening and merging the PR is out of scope — see `babysit-pr`.

## Gate-decision flowchart

After any navigator verdict, do not advance on your own judgement — follow this:

```dot
digraph gate {
  rankdir=TB; node [shape=box];
  verdict   [label="Navigator VERDICT"];
  changes   [label="CHANGES_REQUESTED:\nresolve asks, re-review"];
  block     [label="BLOCK:\nsurface to developer, stop"];
  plannot   [label="APPROVE:\nopen artifact in Plannotator\n(plannotator annotate)"];
  address   [label="Address every annotation"];
  wait      [label="Wait for EXPLICIT\ndeveloper approval"];
  advance   [label="Advance to next phase"];
  verdict -> changes [label="CHANGES_REQUESTED"];
  verdict -> block   [label="BLOCK"];
  verdict -> plannot [label="APPROVE"];
  plannot -> address -> wait -> advance;
  changes -> verdict [label="re-review"];
}
```

The APPROVE path never goes straight to "advance" — it always passes through Plannotator and explicit developer approval first.

## Rationalization table

| Excuse | Reality |
|---|---|
| "The navigator already signed off." | Navigator review and developer approval are two separate, both-required gates. One does not satisfy the other. |
| "We're behind schedule — don't wait." | Gates are how you stay fast. The developer gate is the cheaper half; skipping it risks a full rework loop later. It is NOT an invented extra review cycle — it is part of the defined process. |
| "The code is already worked out in my head." | Tests-first defines what the code *should* do; writing code first lets tests describe what it *does*. Write the tests first. |
| "It's the same file — might as well do slice 4 now." | Scope is fixed by the approved plan. Note the observation, defer it, stay scoped to the current slice. |
| "I'll just confirm the artifact in chat." | The developer-review gate runs through `plannotator annotate` on the artifact. An inline chat message is not the gate. |

## Red flags — STOP

If you catch yourself thinking any of these, a gate is about to be skipped:

- "The navigator signed off, so I can advance." → STOP. Open the artifact in Plannotator and wait for explicit developer approval.
- "I'll add tests after the code." → STOP. Write the failing tests first.
- "While I'm in here I'll also…" → STOP. Note it, defer it, stay scoped to the current slice.
- "I'll just confirm in chat." → STOP. Run `plannotator annotate` on the artifact.
- "Don't wait on anything else." → STOP. The developer gate is part of the process, not a delay.

## Artifacts & commits

```
docs/features//
  scenarios.md                      # Phase 1
  prd.md                            # Phase 2 — Stakeholders, Quality Targets, Constraints, Domain Terms (+ Aliased Terms when redefining)
  design.md                         # Phase 4 — System Analysis, Components, Integration & Data Ownership, Risks
  plan.md                           # Phase 6 — vertical-slice tracer bullets with AFK/HITL, acceptance criteria
  diagrams/architecture.d2          # current + proposed states in one file
  diagrams/architecture-current.svg
  diagrams/architecture-proposed.svg

docs/adr/                           # Phase 4 — lazily created when the first ADR is needed
  NNNN-.md                    # sequentially numbered
```

Commit artifacts with `docs:` conventional commits. ADRs created in Phase 4 are committed together with `design.md` in the same commit. `critique-loop`'s `.critique-loop/` scratch stays gitignored.

## Calling critique-loop

`gzship` invokes `critique-loop`'s review-only flow several times on one branch. `critique-loop` names its session and artifact files from a slug — by default the branch name. If every call reused the branch name, each review would overwrite the previous one's files. So pass a **distinct slug** to each invocation:

| Call | Slug |
|---|---|
| Phase 3 — product (scenarios + PRD) review | `-product` |
| Phase 5 — design (and any new ADRs) review | `-design` |
| Phase 7 — plan review | `-plan` |
| Phase 8 — slice N review | `-slice-N` |
| Phase 8 — final whole-diff review | `-final` |

Each slug gets its own `critique-loop` session, so reviews stay independent and their artifacts do not collide.

## D2 handling

Run `d2 --version`. If present, render each `.d2` to `.svg`. If missing, offer `brew install d2` (or the official install script). If the developer declines, commit the `.d2` source only and embed it as a fenced code block in `design.md`.

## Escalation

If `plan.md` has **5 or more slices**, dispatch each slice to its own fresh subagent in Phase 8 to keep the main context lean.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [gzaripov](https://github.com/gzaripov)
- **Source:** [gzaripov/agent-skills](https://github.com/gzaripov/agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-gzaripov-agent-skills-gzship
- Seller: https://agentstack.voostack.com/s/gzaripov
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.