arch-driven-release-workflow

name

arch-driven-release-workflow

description

Use when the user asks for a 'full' or 'end-to-end' release driven by an architecture document — typically a multi-track release landing a substantial product slice (new product line, multi-surface refactor, feature bundle). Triggers: 'design a doc for this system, then plan it, then ship it', 'ultrathink this through to ship', 'do all 10 phases', 'architecture refresh', 'convergence loop the doc, then implement, then push', or any prompt naming 4+ sequential phases ending in push/merge. Meta-skill bundling writing-plans, a peer-review council / codex peer-review, subagent-driven-development, verification-before-completion, gh-release-ship-loop, and blog-post-template.

Architecture-driven release workflow

This is a META-SKILL. It bundles 5–7 existing skills into the canonical 10-phase workflow for shipping a substantial multi-track release whose scope is anchored in a freshly-converged architecture document. Invoking any of the constituent skills alone (gh-release-ship-loop, superpowers:writing-plans, a peer-review council, …) misses the cross-phase failure modes captured below.

When to use

User says any of:

• "design / write an architecture doc for this, then plan it, then ship it"
• "do all the phases — arch → plan → review → implement → e2e → docs → changelog → blog → push"
• "ultrathink this through to ship"
• "architecture refresh"
• "convergence loop the doc, then implement, then push"

Or you yourself recognize that the user's request will sprawl across 4+ sequential phases ending in a push/merge.

Don't use when

• Single-track ship (bump version + one commit + push) — use gh-release-ship-loop directly.
• Single file edit — Edit + commit.
• Exploratory question — superpowers:brainstorming.
• Research claim audit — use a project-local research/paper-drafting skill, if this project has one.
• The work doesn't need an architecture-doc anchor (e.g. simple bug fix sprint) — skip Phase 1-4, go to superpowers:writing-plans directly.

The 10-phase outline

Phase	What	Constituent skill	Failure mode if skipped
1	Draft architecture doc via architect subagent	feature-dev:code-architect (opus)	Doc anchors drift across files; future readers reconstruct from scattered CLAUDE.md fragments
2	Grade via 1-3 graders (Gemini (dead post-2026-06-18 -> use agy/droid) + codex + claude headless)	a peer-review council OR direct CLI dispatch	Architect self-rates 9.7+ on doc with 5 cited accuracy gaps
3	Surgical revision via cycle-N+1 architect	feature-dev:code-architect (opus)	Doc inherits prior cycle's drift
4	Re-grade + repeat 2-3 until converged (4-cycle cap)	Same as 2	Infinite-loop pursuit of 10/10 when graders themselves are flaky
5	Draft implementation plan with pre-flight	superpowers:writing-plans + feature-dev:code-architect	Subagents start writing against drifted doc assumptions
6	Plan peer-review	a peer-review council OR a separate codex/CLI review pass	Hidden cross-track conflicts (migration, env-var, router) discovered post-merge
7	Parallel subagent dispatch (TDD-first)	superpowers:subagent-driven-development + superpowers:test-driven-development	Subagent rework cascades; opus overspend when sonnet would do
8	Combined full test sweep under CI env (W14 discipline)	superpowers:verification-before-completion	W14 test-debt cascade; CI fails at gates local pytest didn't replicate
9	Update /docs, CHANGELOG, blog (technical-writer subagent)	blog-post-template + a project-specific brand-voice skill, if one exists	Public surfaces drift from CHANGELOG.md; public-changelog-sync CI gate hard-fails
10	Commit, push, PR, auto-merge	gh-release-ship-loop + the GitHub CLI	Hand-merging drift; missed --auto lets CI block manually-triggered merges

Phase-by-phase discipline

Phase 1 — Architecture doc draft

• Dispatch feature-dev:code-architect at opus with a comprehensive brief: scope, sections required, length target (1000-2000 lines), diagram count (3-5 Mermaid), appendix targets.
• The subagent should read CLAUDE.md root + per-folder CLAUDE.md files + recent CHANGELOG + relevant *-ops skills.
• Don't ask the subagent to invent novel architecture — document the system as it exists.
• Persist output to docs/architecture/<NAME>.md immediately. Don't leave it in the chat.

Phase 2 — Grade

• Default cycle 1 graders: Gemini flash + claude headless haiku (cheap + fast).
• For high-stakes: add codex gpt-5.5 as the third independent calibration.
• Prompt the grader explicitly: 8 rubric dimensions, scored 1-10, terse format, one-line finding per dimension <10. Cap output length.
• Known grader failure modes (proven 2026-05-19):
  • Gemini (dead post-2026-06-18 -> use agy/droid) can crash at startup on chrome-devtools MCP tool-registration collision. Pattern: Tool with name "mcp_chrome-devtools_*" is already registered. Overwriting. repeated until exit. Workaround: dispatch with no MCP servers active (--no-mcp flag if available) or switch to a different grader.
  • Codex goes into superpowers ceremony detour on prompts that mention skills. Wastes the time-box on Get-Content .../SKILL.md calls. Workaround: tight prompt, explicit time-box 5 minutes + do NOT do file readouts. If it still detours, try haiku as a substitute.
  • Claude haiku is a strict-rubric outlier — may score 6-7 where Gemini/architect score 9-10. NOT a doc-quality signal — it's haiku's scope-expansion bias. Use it for scope-gap detection, not for composite score.
• Multi-grader synthesis rule:
  • All N agree ≥9/10 → ship
  • N-1 agree ≥9 + 1 dissents → investigate the dissenter (may be model artifact OR a real gap)
  • Split (2/2 or wild outliers) → trust the calibrated grader (Gemini > codex > haiku for composite; haiku for scope gaps only)

Phase 3 — Surgical revision

• Dispatch feature-dev:code-architect at opus AGAIN with the union of cycle-N grader findings + explicit instructions to fix them surgically (net line-count delta ±200 lines, NOT a rewrite).
• Explicitly forbid expansion beyond the cited gaps. Subagents will instinctively add 500 more lines if not constrained.
• Return as Edit blocks (OLD STRING / NEW STRING) the orchestrator applies. Subagents typically can't Write, but they can compose precise Edit blocks.

Phase 4 — Re-grade + 4-cycle cap

• Repeat 2-3. After cycle 4, declare convergence regardless of score. Document residuals in the doc's status header.
• Why cap at 4: marginal-gain curve flattens; grader infrastructure degrades; opportunity cost of cycle 5+ is delaying the actual ship.
• Convergence-log header pattern: every doc should carry a "Status:" header with cycle-by-cycle scores + grader names + visible residuals. Future readers can audit the convergence trajectory.

Phase 5 — Implementation plan with pre-flight

• Dispatch feature-dev:code-architect at opus to draft docs/plans/<DATE>-<name>-plan.md.
• Mandatory pre-flight section at top: subagent runs grep/ls/Read against actual code to verify EVERY claim in the architecture doc's Appendix F (or whatever section drives the plan). Catches 2-5 doc-vs-code drifts per release.
• Track structure: each track gets a row in a dispatch matrix — subagent type / tier / read budget / write surface / TDD test / verification step.
• Why tier matters: all-sonnet was right for a past multi-track release; opus would have wasted ~3× tokens. Use opus ONLY when the architectural decision is novel (not "copy this existing pattern").

Phase 6 — Plan peer-review

• Default: an 8-seat peer-review council if the release is cross-cutting.
• Lightweight: single-CLI review via codex or another CLI (~5 min wall).
• Failure mode caught 2026-05-19: Codex went into superpowers ceremony detour and timed out before returning a verdict. If the plan's pre-flight is comprehensive, this is recoverable — proceed with subagent dispatch.

Phase 7 — Parallel subagent dispatch

• Dispatch all parallel tracks in ONE message with multiple Agent tool calls. Sequential dispatch wastes wall time.
• Each subagent's prompt MUST include:
  • The plan's relevant § number (e.g. "§3 of docs/plans/2026-05-19-...md")
  • Pre-flight commands the subagent MUST run BEFORE writing code (grep for existing patterns, verify file paths)
  • TDD discipline (test file first, must fail; then implementation; then verify green)
  • Explicit "DO NOT commit, DO NOT push" so the orchestrator controls the merge
  • Output format (file list, test count, deviations from plan, ready-to-commit y/n)
• Subagent silent-fail recovery (proven multiple times this session):
  • Subagents may claim they edited a file when the Edit tool silently no-op'd (CRLF/whitespace mismatch, no anchor match)
  • Always verify the actual diff: git diff <file> AFTER subagent returns
  • Re-edit yourself if the subagent's edit didn't land
  • This is a known war-story pattern from prior sessions (see this project's CLAUDE.md war-stories log, if it keeps one)

Phase 8 — Combined full test sweep (W14 discipline)

• MANDATORY local pre-push command that replicates CI env EXACTLY:

  MCP_GATEWAY_ENABLED=0 UPSTASH_REDIS_REST_URL=mock \
    DATABASE_URL="sqlite+aiosqlite:///test.db" PYTHONPATH=. \
    python -m pytest <test-root> -q --no-cov -p no:randomly
  

• Why -p no:randomly: pytest-randomly is on by default and surfaces test-order flakes that aren't real bugs. Disable to get a deterministic baseline.
• Why CI env vars: the test job in deploy-api.yml runs with very specific env (mock Redis, SQLite, MCP off) — local default env passes tests that CI fails. Cost of skipping: two consecutive patch releases both failed at the same gate, leaving prod on the prior working version for a couple of hours.
• Also run npm run check-types in <web-app>/ BEFORE commit. The lint-staged hook is stricter than npm run lint and rejects commits without prior local type-check.
• Run black --check --line-length 100 api/app/ api/tests/ + ruff check api/app/ api/tests/. CI lint job blocks deploys; local pytest doesn't catch formatting.
• Re-run the sweep AFTER any version bump. A past deploy failed because a secondary version constant (in a gateway/service config file) wasn't bumped alongside the primary entrypoint's version string — a parity test in the app's test suite caught the mismatch in CI and blocked the deploy. The full sweep ran BEFORE the bump (when both constants still matched) and passed; nothing re-ran after the bump. Rule: bump every version constant in the codebase, THEN run the sweep, THEN commit. Discoverable parity constants are project-specific — e.g. a FastAPI app's version= kwarg, a root-response body version field, a secondary gateway constant, and the web app's package.json:version. Grep git grep -l "<OLD_VERSION>" after the first bump to find every site that needs updating.

Phase 9 — Update /docs + CHANGELOG + blog

• Dispatch technical-writer subagent at sonnet for both the /docs section + blog post. ONE subagent for both keeps voice consistent.
• Discover existing conventions before writing: find the existing blog structure (MDX vs in-page TSX, frontmatter shape, BlogPostLayout component, image conventions). Don't invent a new format.
• CHANGELOG sync gate: if the project has a scripts/check_public_changelog_sync.py style gate, run it locally BEFORE push. Public /changelog page must reflect the new version within 1-ship-lag.
• Anti-AI-slop discipline: apply the project's brand-voice rules (or equivalent) Tier-1/Tier-2 kill-words. NO "dive into", "unlock", "leverage", "robust", "seamless", "elevate", "embark on", etc.
• Verify the writer's diff — they're prone to claiming they edited a file when the [Unreleased] anchor didn't exist where they thought.

Phase 10 — Commit + push + PR + auto-merge

• Use release-ship skill for the standard release ritual (version bumps in API + web).
• For multi-track releases: ONE consolidated commit per major piece (not 3 separate per-track commits unless tracks are truly independent and one might be rolled back without the others).
• Commit-lint discipline: project may enforce conventional-commits (feat: / fix: / docs:) + body-line-length 100. Use HEREDOC + cat <<'EOF' pattern; keep lines ≤100 chars.
• PR auto-merge: gh pr merge <N> --squash --auto --delete-branch enables merge-on-CI-green. Doesn't require manual polling.
• Post-push monitoring: kick off a Monitor task watching for the new version on the production health endpoint:

  until curl -s https://api.example.com/ | grep -q '"version":"X.Y.Z"'; do sleep 30; done && echo "LIVE"
  

Anti-patterns (proven failure modes from a past release session)

Anti-pattern	What happens	Fix
Trust grader output without checking	Codex c1 returned a stub ("done"); subagent thinks doc was graded; cycle 2 dispatched with no real findings	Read every grader output. Stub/format-drift = re-dispatch with tighter prompt or substitute grader.
Dispatch all 3 subagents at opus tier	~3× token spend for no quality gain on copy-the-existing-pattern work	CLAUDE.md tier-down rule: opus only for novel multi-file architecture decisions.
Skip pre-flight in the plan	Subagents start writing against drifted doc assumptions; cascading rework	Plan §0 = pre-flight findings. Required output from architect subagent.
Skip combined CI-env pytest before push	W14 test-debt cascade (two consecutive patch releases stuck at the same gate for a couple of hours)	pytest <root> -p no:randomly under CI env vars BEFORE every push.
Run the sweep BEFORE the version bump, not AFTER	a past deploy failed; a secondary gateway/config version constant missed the bump; parity test caught it in CI but not locally	Bump ALL version constants first (grep git grep -l <OLD_VERSION>), THEN run the sweep, THEN commit.
Run black only as --check	CI lint fails on formatted-by-not-checked files; deploy job skips	black api/app/ api/tests/ (apply, not check) before commit.
Loop on broken graders	Cycle 5+ chasing 10/10 when grader infrastructure is the blocker	4-cycle cap. Ship with residuals documented.
Hand-merge PR	CI might still be running; bypasses required-checks gate	gh pr merge --squash --auto lets CI gate the merge.
Block dev work on operator-action items	Stalled track waiting on a webhook secret or env var	Code can ship clean even when production activation needs operator. Document the operator actions in PR body.
Ask the user for permission inside a loop directive	"should I commit?" / "should I move to track B?" — directive already answered these	Loop directive subsumes per-cycle permission. Default: keep going until convergence or destructive action.

Cross-references

Constituent skills (load by name via Skill tool):

• superpowers:writing-plans — Phase 5 plan structure
• superpowers:test-driven-development — Phase 7 inner discipline
• superpowers:subagent-driven-development — Phase 7 outer pattern
• superpowers:verification-before-completion — Phase 8 + 10 gates
• A peer-review council skill, if this project has one — Phase 6 multi-seat review
• use-gemini (dead post-2026-06-18 -> use agy/droid) or another CLI-delegation skill — Phase 2 + 6 single-CLI grader/reviewer
• gh-release-ship-loop — Phase 10 version bump + deploy ritual
• blog-post-template — Phase 9 blog post discipline + anti-AI-slop checklist
• A project-specific brand-voice skill, if one exists — Phase 9 voice rules
• An explicit prompt/spec drafting pass — recommended before composing any subagent dispatch prompt

Sibling meta-skills:

• A project-local research/paper-drafting skill, if one exists — research-claim authoring (different artifact, same multi-cycle structure)
• A project-local empirical-sweep validation skill, if one exists — different surface, same multi-cycle structure

Validated empirical receipts:

• A past multi-track production release: 10 phases, a 1400+-line architecture doc, 3 parallel sonnet subagents, 2000+ tests, auto-merged to main after full CI green.

Phase decision tree

User request received
   │
   ▼
Does it sprawl ≥4 sequential phases ending in push/merge?
   │
   ├─ NO → Use the single relevant skill (release-ship / writing-plans / etc.)
   │
   └─ YES → Invoke THIS skill
              │
              ▼
       Does an architecture-doc anchor exist or need to be drafted?
              │
              ├─ EXISTS + RECENT → Skip to Phase 5
              │
              ├─ EXISTS + DRIFTED → Phase 1-4 (refresh)
              │
              └─ ABSENT → Phase 1-4 (full)
                          │
                          ▼
                  Cycle through 2-3 until ≥9/10 composite OR 4-cycle cap
                          │
                          ▼
                  Phase 5: plan with pre-flight (mandatory)
                          │
                          ▼
                  Phase 6: peer-review (lightweight OK if plan pre-flight is comprehensive)
                          │
                          ▼
                  Phase 7: parallel dispatch (sonnet by default)
                          │
                          ▼
                  Phase 8: combined CI-env pytest BEFORE push
                          │
                          ▼
                  Phase 9: writer subagent for /docs + CHANGELOG + blog
                          │
                          ▼
                  Phase 10: commit + push + PR --squash --auto
                          │
                          ▼
                  Monitor for live deploy; declare done.

Output contract

When this skill is invoked, the orchestrator should produce in order:

1. Architecture doc (or pointer to existing one + cycle convergence log)
2. Implementation plan with pre-flight section
3. Plan peer-review verdict (or "skipped, pre-flight comprehensive")
4. Per-track ship report (files, tests, deviations from plan)
5. Combined sweep result (test count + pass/fail)
6. /docs + CHANGELOG + blog diff
7. PR URL + merge state
8. Production deploy verification (version string on health endpoint)

Each phase produces concrete on-disk artifacts. The skill is "done" when item 8 lands.