Arch Driven Release Workflow

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-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)

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.