# Sequences

> >

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

## Install

```sh
agentstack add skill-genkovich-sdd-sequences
```

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

## About

# Skill: sequences

Draws the **runtime view** of an already-designed feature: for each critical flow it produces a Mermaid `sequenceDiagram` block — generic participants, happy path plus the error branches the spec demands — and writes them into `docs/features//sad.md §6`. One flow at a time, user confirms each. The diagrams are the bridge between the static design (§5 building blocks) and the data layer: every persist/read step you draw becomes a hint for the indexes `data-model` will need.

This skill keeps only its own machinery. Question phrasing is **shared** → [`../_shared/ask-style.md`](../_shared/ask-style.md). **Flow count is driven by the spec, not a cap** — every §4 user story / §5 acceptance criterion is covered (size may collapse *detail*, never *coverage*) → [`../_shared/size-matrix.md`](../_shared/size-matrix.md). Each diagram is **confirmed in prose, never as raw Mermaid** → [`../_shared/diagram-presentation.md`](../_shared/diagram-presentation.md); whether each flow is confirmed per-diagram or written-and-summarized follows the interview-depth setting → [`../_shared/interview-depth.md`](../_shared/interview-depth.md).

## Owner

Tech Lead (drives the runtime decomposition). The PM confirms that each drawn flow matches a real user story; a backend engineer flags persist steps that imply a new index.

## Inputs

- `` — same feature slug used by every earlier stage.
- **Gate (hard-refuse if missing):** `docs/features//sad.md`. The §5 building-block view names the participants; §6 is where flows are written. If `sad.md` is absent → STOP and point: «run `design ` first — sequences are written into its §6».
- (Expected) `sad.md` frontmatter `target_surfaces` — picks the participant vocabulary (UI-driven flows for a UI surface). **Absent or empty → warn** («surfaces undeclared — re-run `design`, or proceeding as `backend-service`») **and treat as `[backend-service]`** (→ [`../_shared/surfaces.md`](../_shared/surfaces.md)); never silently guess a UI surface.
- **Strongly expected:** `docs/features//spec.md` — §4 user stories tell you *which* flows exist; §5 acceptance criteria are the **coverage floor** — every AC must be shown by a flow, a branch, or an explicit non-runtime N/A (the step-7 coverage check). Present by this stage in the normal pipeline; if genuinely absent, fall back to §6/§5 of `sad.md` for the flow list and note that AC-coverage can't be verified.
- (Optional) `docs/features//.size` — depth hint for *detail* (XS/S may collapse a flow's internal steps), never for *coverage*. Absent → default to M **and say so loudly in the handoff** — «size M (default — no `.size`; run `/sdd:classify-size `)».
- (Optional) `.claude/sdd.local.md` `interview_depth` (else medium) — governs only the diagram-confirmation UX (per-diagram prose+ask vs. write+summarize-and-proceed); `sequences` does **not** open its own depth question (it honors the setting, or a `--depth=` arg if passed).

## Protocol

1. **Gate.** `test -f docs/features//sad.md` → fail = refuse with the pointer above. Then read §5 (participants) and §6 (any flows already drawn — this skill is additive, never rewrite an existing block).
2. **Pick the flows — spec-driven, no cap.** List the flows from `spec.md` **§4 user stories + §5 acceptance criteria** (absent the spec, from §6 itself): **one flow per critical user story / distinct runtime path**. There is **no fixed cap** — draw as many flows as the user stories and ACs need (the old "3–5" cap silently under-covered). Then **plan AC coverage**: map every §5 AC to where it will be shown — a **dedicated flow**, an **`alt`/`else` branch** inside the relevant flow, or **explicitly non-runtime** (e.g. a middleware-enforced 401, a build-time check) with a one-line reason. Size only collapses *detail* (XS/S may show fewer internal steps per flow), never *coverage*. Confirm the flow list **and the AC→flow map** with one `AskUserQuestion` before drawing — phrasing per [`../_shared/ask-style.md`](../_shared/ask-style.md).
3. **Map participants — generic only.** For each flow, draw participants from a fixed generic vocabulary: ``, ``, ``, ``, ``, ``. Do **not** invent concrete service or technology names — those are `design`/`data-model` decisions, not runtime-view ones. **When `sad.md` frontmatter `target_surfaces` declares a UI surface** (`web-frontend` / `mobile-app` / `desktop-app`), draw the flows it touches as **UI-driven** — `` (actor) → `` → `` → `` — so the user-visible step is shown, not just the service call (→ [`../_shared/surfaces.md`](../_shared/surfaces.md)). A backend-only / `cli` / `worker` feature keeps the service-level vocabulary (no ``). `` stays generic, like every other participant — never a framework or component name. If a flow needs a participant §5 never declared, note it («flow needs ``, not in §5 — flag for design») and still draw it.
4. **Sync vs async.** If the spec describes a webhook, scheduled job, queued/event-driven step, or any third-party callback → async: add an idempotency-key check as the handler's first step, a retry note (`Note over ,: retry N times with backoff`), and a dead-letter branch in an `alt` after N failures. Otherwise → sync (request → response).
5. **Draft each flow** from [`./templates/sequence.md`](./templates/sequence.md): a precondition note, the happy-path messages, an `alt`/`else` for the error branches the spec's acceptance criteria require, and a postcondition note. Mark every write as a generic persist note — `Note over ,: persists ` — so `data-model` sees what to index. Keep messages verb-first and free of HTTP verbs / status numbers / SQL.
6. **Present + confirm each flow, one at a time — in prose, never raw Mermaid.** Per [`../_shared/diagram-presentation.md`](../_shared/diagram-presentation.md): for each drafted flow, **write the block into §6** under a `### ` heading (so Obsidian renders it), **validate** it parses per [`../_shared/mermaid-check.md`](../_shared/mermaid-check.md), then **describe it in prose** — the happy path plus every `alt`/`else` branch in plain words. **Never paste the raw `sequenceDiagram` source as the question.** Confirm by prose, governed by the interview-depth setting: at **medium/hard**, one `AskUserQuestion` per flow with the 4-state actions from [`../_shared/ask-style.md`](../_shared/ask-style.md) (Accept / Fix / Save-as-OQ / Drop) — on **Fix**, regenerate + overwrite that one block, re-validate, re-describe (one round, second answer final); on **Drop**, remove the block again. At **easy**, write + a one-line prose summary into the assumptions ledger and proceed (no per-flow question). Never touch a flow already present in §6. Maintain the edits-log per [`../_shared/socratic-loop.md`](../_shared/socratic-loop.md).
7. **Use-case + AC → flow coverage check (before finalizing).** Two passes, surfaced as one coverage table:
   - **Use-case pass (§4).** List **every §4 user story** and the flow(s) that realize it. Every retained user story maps to **≥1 flow** (a US with no flow is a gap — draft + confirm one, or de-scope it back through `specify`/`clarify`, never silently skip). `specify` already guarantees every §4 US carries ≥1 AC and `clarify` re-catches a US with none, so this pass is the runtime-view echo of that floor — both ends now checked, not just transitively assumed.
   - **AC pass (§5).** List **every §5 AC** and where it is now shown — a **dedicated flow**, an **`alt`/`else` branch**, or an **explicit non-runtime N/A** (with its one-line reason, e.g. «AC-7: middleware-enforced 401, not a runtime flow»).
   If a `Drop`/`Save-as-OQ` during step 6 left a user story or an AC uncovered, draft + confirm the missing flow or branch (the step 5–6 mini-loop) before proceeding, or record the explicit N/A with the user. **No §4 user story and no §5 AC may be silently uncovered.** (Completeness is independent of depth + size; this gate holds even at easy/XS.)
8. **Finalize: order, validate, propose commit.** Order the §6 blocks to match §4. **Re-validate every `sequenceDiagram` block per [`../_shared/mermaid-check.md`](../_shared/mermaid-check.md)** as the backstop (balanced `alt`/`else`/`end`, declared participants; fix any that don't parse before committing). Append any flagged items (new participants, decisions worth an ADR) as a short note at the end of §6 — flag only, never auto-write an ADR. Propose commit `sequences:  runtime flows`. Then **emit the stage-handoff block** per [`../_shared/handoff.md`](../_shared/handoff.md) — *What I did* + *Review* (`sad.md` §6) + *Run next* (`/clear`, then `/sdd:data-model `, which uses the persist notes to choose indexes; **for XS/S with no schema change** — no new entity/column/index in any drawn flow — **add the fast-lane alternative** `↳ or /sdd:api `, per the [size-matrix fast lane](../_shared/size-matrix.md)).

## Definition of Done

- `sad.md §6` holds a Mermaid `sequenceDiagram` for **every** critical user story / distinct runtime path — **no fixed cap**; size may collapse a flow's internal detail, never its coverage.
- **Every §4 user story maps to ≥1 flow, and every §5 AC maps to a flow, an `alt`/`else` branch, or an explicit non-runtime N/A** — the step-7 coverage check passed on both passes (use-case + AC); nothing is silently uncovered (holds at every depth + size).
- Each flow was **confirmed in prose** (medium/hard) or **written + summarized** (easy) — never by pasting raw `sequenceDiagram` source as the question.
- Every block uses **only** generic participants (`` / `` / `` / `` / `` / ``) — no concrete technology or service names. A declared UI surface uses `` in a UI-driven flow (`` → `` → `` → ``); a backend-only feature omits it.
- Each flow shows the error branches its spec acceptance criteria require, not happy-path only; every mutating step carries a generic persist note for `data-model`.
- Every async flow has an idempotency-key step, a retry note, and a dead-letter branch.
- Pre-existing §6 blocks are untouched; new participants / ADR-worthy decisions are flagged, not silently added.

## Anti-patterns

- **Concrete participants.** `Postgres`, `content-api`, a specific broker — the legacy trap. Participants stay generic; naming the tech is the job of `design`/`data-model`.
- **Capping the flow count** (the old "3–5") and silently under-covering. Flow count is driven by §4/§5 — every AC is shown by a flow, a branch, or an explicit N/A. A dogfood run that drew only 2 flows for a spec with 6 ACs is the exact failure this skill now forbids.
- **Pasting raw Mermaid as the confirmation.** `sequenceDiagram` source in the terminal is unreadable — the user approves blind. Confirm in prose; let Obsidian render the written block (per [`../_shared/diagram-presentation.md`](../_shared/diagram-presentation.md)).
- **Happy path only** when the spec lists explicit error acceptance criteria. Each flow gets happy + the demanded error branches.
- **One mega-diagram** for the whole feature. Split per flow; a cross-cutting flow gets its own `### Cross-cutting: ` heading.
- **Auto-writing ADRs.** This skill only flags decisions (idempotency strategy, retry shape, sync-vs-async); ADRs come from `decide-adr` or a human.
- **Rewriting an existing §6 block.** Additive only — editing a drawn flow is a deliberate manual diff.
- **Inventing a participant §5 never declared without flagging it.** §5 is the source of truth; the flag lets `design` reconcile it.

## References & template

- [`../_shared/ask-style.md`](../_shared/ask-style.md) — canonical question/option phrasing for steps 2 and 6.
- [`../_shared/diagram-presentation.md`](../_shared/diagram-presentation.md) — how each flow is confirmed (write → validate → prose-describe → confirm/proceed); never raw Mermaid as the question.
- [`../_shared/interview-depth.md`](../_shared/interview-depth.md) — the depth setting that governs per-flow ask vs. write-and-summarize (read from settings; sequences asks no depth question of its own).
- [`../_shared/mermaid-check.md`](../_shared/mermaid-check.md) — parse-validation run on each block at step 6 and again as the step-8 backstop.
- [`../_shared/size-matrix.md`](../_shared/size-matrix.md) — collapses a flow's *detail* for XS/S (never its *coverage* — every AC is still shown).
- [`../_shared/surfaces.md`](../_shared/surfaces.md) — a declared UI surface adds `` to the vocabulary and draws UI-driven flows; read from `sad.md` `target_surfaces`.
- [`./templates/sequence.md`](./templates/sequence.md) — generic-participant `sequenceDiagram` scaffold (sync + async), embedded inline in sad.md §6.

## Source & license

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

- **Author:** [genkovich](https://github.com/genkovich)
- **Source:** [genkovich/sdd](https://github.com/genkovich/sdd)
- **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-genkovich-sdd-sequences
- Seller: https://agentstack.voostack.com/s/genkovich
- 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%.