Development Pipeline

How an idea becomes shipped, traceable code in the Verbara ecosystem. This is the end-to-end flow every change follows — from product intent down to a signed release and a retrospective. New devs: read this after the onboarding checklist; it is the “why” behind the steps you’ll run.

The pipeline answers four questions in order: what is Verbara (vision), what now (roadmap), what to build (spec), and how (plan → implement → ship). Each layer has a canonical template under docs/templates/.

The full pipeline

VISION      docs/vision.md         — what Verbara is, where it's going
   ↓
ROADMAP     docs/roadmap.md        — priorities by quarter; every spec traces to an item
   ↓
PROBLEM     (in the spec)          — what pain we solve, for whom
   ↓
SPEC        OpenSpec + T2          — what to build, RFC 2119 (SHALL/MUST/SHOULD/MAY)
   ↓
PLAN        Claude Code Plan Mode + T3 — how; cross-repo sequence if it spans repos
   ↓
IMPLEMENT   feature branch + worktree  — Subagent-Driven Development, FCM batching
   ↓
VERIFY      tests + CI green + review   — coverage ratchet, i18n parity, AOT checks
   ↓
SHIP        tag → release workflow      — CHANGELOG, cosign, GitHub Release
   ↓
RETRO       T9 (milestones only)        — what we learned; memory cleanup

Product decisions (“what we chose not to build, and why”) are captured out-of-band as PDRs; load-bearing technical decisions as ADRs. Both prevent re-litigating settled questions.

Size tiers — don’t burn process on small changes

A nine-layer pipeline on a one-line bug fix is bureaucracy that kills velocity. Pick the tier by blast radius, not by habit.

Tier	When	Required layers
GRANDE	Cross-repo, > 3 days, or a product decision	Vision → Roadmap → Problem → Spec → Plan → Implement → Verify → Ship → Retro
MEDIANO	One repo, 1–3 days	Roadmap item → Spec → Plan → Implement → Verify → Ship
PEQUEÑO	Bug fix, < 1 day	Spec (light) → Implement → Verify → Ship

The tier lives in the spec frontmatter (tier: GRANDE | MEDIANO | PEQUEÑO), so reviewers can tell at a glance how much rigor to expect.

Step-by-step

1. Spec — what

Run OpenSpec (/opsx:propose "<feature>") to scaffold proposal + specs + design + tasks. The Verbara T2 spec template extends it with product frontmatter (owner / approver / stakeholder / roadmap_ref), a Problem section, and a structured Architectural Risk block (LOW/MEDIUM/HIGH + affected repos + mitigation). Use SHALL/MUST for non-negotiables; write scenarios as GIVEN/WHEN/THEN.

2. Plan — how

Use Claude Code Plan Mode to read the generated specs and produce an implementation plan (T3). If the change spans repos, the plan must include the cross-repo sequence (see the release runbook — always SDK → Pro → Platform → Web). Any architectural decision made here becomes an ADR.

3. Implement — build it

Work on a feature branch (worktree for parallel work). Use Subagent-Driven Development with FCM batching for non-trivial tasks. Honor the hard constraints: Native AOT (no reflection), TreatWarningsAsErrors, no Dapper (use Verbara.Sdk.Data.Npgsql).

4. Verify — prove it

Tests green locally, then CI green: build, unit/functional tests, coverage ratchet, i18n parity (Web), AOT trim checks. All review comments resolved. PRs merge through the merge queue — never a direct push to a protected main.

5. Ship — release it

Bump PackageVersion (the version bump is the release trigger), update CHANGELOG.md before tagging, then let the release workflow create the tag + GitHub Release + signed (cosign) image. Follow the release checklist (T5) and the cross-repo runbook. Never docker push by hand (ADR-0024).

6. Retro — learn (milestones only)

After a milestone, run a retrospective (T9): what shipped, what went well / badly, action items, and memory cleanup (archive closed project-memory entries, move the plan to docs/plans/completed/).

Where each artifact lives

Artifact	Home
Vision / Roadmap	`verbara-meta/docs/{vision,roadmap}.md`
Specs (in-flight)	`<repo>/openspec/changes/<feature>/` then archived
Plans	`<repo>/docs/plans/{active,completed,archived}/`
ADRs (technical)	`<repo>/docs/decisions/` · cross-repo in `verbara-meta/docs/decisions/`
PDRs (product)	`verbara-meta/docs/product-decisions/`
Templates (T1–T10)	`verbara-meta/docs/templates/`
Release runbook	`verbara-meta/docs/workflows/cross-repo-release.md`