wave-spec

Files (29)

• README.md
• README.ru.md
• SKILL.md
• hero-dark.svg · assets/
• hero-light.svg · assets/
• ASSUMPTIONS.md.tmpl · assets/templates/
• INTENT.md.tmpl · assets/templates/
• LAUNCH.md.tmpl · assets/templates/
• NEXT_SESSION.md.tmpl · assets/templates/
• NEXT_SESSION_ITER.md.tmpl · assets/templates/
• PLAN.xml.tmpl · assets/templates/
• SPEC.xml.tmpl · assets/templates/
• STATUS.md.tmpl · assets/templates/
• fix-round-brief.md.tmpl · assets/templates/
• iteration-handoff.md.tmpl · assets/templates/
• linear-workflow.md.tmpl · assets/templates/
• premortem-brief.md.tmpl · assets/templates/
• quick-spec.md.tmpl · assets/templates/
• re-dispatch-brief.md.tmpl · assets/templates/
• review-synthesis.md.tmpl · assets/templates/
• worker-brief.md.tmpl · assets/templates/
• glossary.md · references/
• program-maps.md · references/
• vv-portability.md · references/
• worked-examples.md · references/
• test_update_review_packet.py · scripts/
• update_review_packet.py · scripts/
• verify-handoff-payload.sh · scripts/
• verify-spec.sh · scripts/

SKILL.md (first lines)

# wave-spec

**Method:** same as vv-opencode (`vv-spec` → `vv-plan` → approve → exec), but **portable**:
structured XML artifacts in the repo, any orchestrator CLI.

**You (the agent) execute this skill.** The user does not need to invent the pipeline.

> **Positioning (identity):** wave-spec is a **universal plan-gate + lifecycle skill for 1–3 week product waves across any domain** — development, content, skill-port, translation, orchestration, site rebuild.
> It is NOT an SEO costume and NOT gsd-core / gsd-coordinator / vv-opencode runtime — no agentic dispatch, no worktree groups, no structured handoff beyond project-local SESSION_HANDOFF.
> The lifecycle gates below are the contract; full identity and boundaries in [Positioning](#positioning).

## TL;DR (minimum path — 5 минут)

**wave-spec = план-гейт.** Пишет в `waves/<date>-<slug>/`: INTENT → SPEC.xml → PLAN.xml → **approve** → exec → STATUS/handoff. Не для однострочных правок (для них `mode=quick`).

**Прочитай только:** Modes → Hard gate → Pipeline шаги 0–5 → approve. Остальное (NEXT_SESSION/Linear) — по мере возникновения; **LAUNCH.md обязателен для wave/program до dispatch** (см. Шаг 6.0).

**Лестница обучения:** Волна 1 = `mode=quick` (весь цикл за 1 сессию) → Волна 2 = полный `wave` + 1 review → Волна 3+ = `multi-model-orchestration`. Учись деланием, не чтением.

**Роутер:** новый проект → `project-bootstrap` · план спринта → `wave-spec` · 2+ модели → `multi-model-orchestration`.

## Modes

| Mode | Trigger | Output |
|------|---------|--------|
| `quick` | Trivial / пет-проект: **≤1 файл, ≤30 мин, no deploy** | INTENT 5 строк → SPEC 10 строк → approve → apply → archive (1 файл, без LAUNCH/NEXT_SESSION/Linear) |
| `wave` (default) | One sprint 2–7 days / one theme | `waves/<date>-<slug>/…` |
| `task` | Single atomic task inside approved wave | `waves/.../tasks/TNN-*.xml` + worker brief |
| `program` | Multi-wave portfolio (fidelity port, book translation, site rebuild) — редко; см. `references/program-maps.md` | `roadmap/PROGRAM_SPEC.xml` + `roadmap/PROGRAM_PLAN.xml` |

Default: if unclear, start **wave** (or **quick** for trivial). `program` — только для много-волновых портфелей; карты доменов в `references/program-maps.md`.

### Quick mode (mode=quick)

Для мелких правок и пет-проектов, которые не тянут полный lifecycle. Шаблон: `assets/templates/quick-spec.md.tmpl`.

1. **INTENT** — 5 строк (что хочу / успех / out of scope).
2. **SPEC** — 10 строк (goal + 2–3 success criteria + constraints).
3. **approve** — «Ответь approve» (hard gate, как в полном wave).
4. **apply** — выполнить (один исполнитель, без диспетчеризации).
5. **archive** — `mv waves/<date>-<slug> waves/archive/` по завершении.

**Порог:** quick только если ≤1 файл, ≤30 мин, no deploy. Иначе — полный `wave` (с lifecycle gates + review). Quick НЕ отменяет written≠persisted и secret-redaction.

## Installation / SoT

**Source of Truth:** `skills/wave-spec/` in the opencode-skills repo — git-tracked, canonical. All edits go here.

**Install into OpenCode** (active CLI):
```bash
ln -sf <repo>/skills/wave-spec ~/.config/opencode/skills/wave-spec
```

If the repo moves, recreate the symlink above with the new path.
## Hard gate

Until user says **approve / approved / proceed / dig / делай / утверждаю**:

- **Do** write planning artifacts (INTENT/SPEC/PLAN/STATUS templates).
- **Do not** implement site changes, bulk content, deploy, or dispatch workers for execution.
- **Do** research/read repo, AGENTS.md, SESSION_HANDOFF, diagnostics (read-only).

After approve: produce worker briefs and optionally Orca dispatch commands; still do not expand scope beyond PLAN.

> **Lifecycle gates:** before claiming Done or handing off to NEXT product, follow the contract in [Lifecycle Gates](#lifecycle-gates-production-lessons).

---

## Pipeline (run in order)

### 0. Locate workspace

1. Find project root (AGENTS.md or git root).
2. Read if present: `AGENTS.md`, last block of `SESSION_HANDOFF.md`, `plan.md`, `.agents/memory/MEMORY.md`.
3. Detect existing `roadmap/` and `waves/` — never overwrite approved artifacts without asking; version with new date slug instead.

### 1. INTENT (human or draft-for-human)

Path:

- program: `roadmap/INTENT.md`
- wave: `waves/<YYYY-MM-DD>-<slug>/INTENT.md`

If user already pasted free text → save it as INTENT.md (light edit for structure only).

If missing → write a draft INTENT from conversation and ask user to correct:

```markdown
# INTENT
## What I want (freeform)
## Targets (project / repo / site / book — if any)
## Stack / context (if known)
## Constraints (budget, no-deploy, region, language)
## Success in my words
## Out of scope (if known)
## Links to existing research
```

**Stop if INTENT is empty or contradictory** — ask 1–2 clarifying questions only.

### 2. Interview (3–7 questions)

After INTENT + context read:

1. List open issues: ambiguity / contradiction / blocker / risk / assumption.
2. Ask **only** questions that unblock SPEC (max 7). Each question: options + recommended default.
3. Do **not** interview for things already answered in AGENTS/handoff/research.

**Дисциплина интервью (lean):** (a) recommendation-first — каждый вопрос начинай с рекомендуемым ответом по умолчанию и обоснованием (большинство ответов закрывается одним словом); (b) мини-roadmap — перед первым вопросом покажи список открытых вопросов целиком; (c) recap — после интервью одной строкой резюмируй зафиксированные решения, чтобы поймать недопонимание до SPEC.

If user says «решай сам / use defaults» → mark assumptions explicitly: log them via `assets/templates/ASSUMPTIONS.md.tmpl` and record them in the SPEC `<assumptions>` block.

### 2.5 Pre-mortem triage

Дешёвый design check между Interview и SPEC: один review-only dispatch на сессию, который ловит failure surfaces в draft дизайне до формирования final контракта. **НЕ заменяет post-implementation review** (Fidelity Dual Review остаётся обязательным для fidelity ports) и **НЕ отменяет hard gate approve** (шаг 5).

**Trigger (OR — любое одно условие достаточно, чтобы сделать pre-mortem `required`):**

- `migration` — reference→platform, framework, DB migration, schema change

From dimkurilo/opencode-skills, MIT.

More from dimkurilo/opencode-skills