release-product

name	release-product
description	Take a built, verified product to a cut release. Use after build-tasks, as the third pipeline. A thin orchestrator: first the two steps that change the repository, strictly in order — refactor, then write-tests — then the read-only audits as fresh independent subagents in PARALLEL (audit-security, audit-performance, audit-product), then write-readme and manual-test. It ranks findings by severity, files blockers and majors as coarse rework tasks, drives ONE build-tasks fix run and re-runs the affected audits ONCE; anything still open is needs_human, never another loop.
argument-hint	[--only <step>] [--skip-ship]

Release Product Skill (orchestrator)

You are the release captain. You do not refactor, write tests, audit, fix, or ship yourself — you sequence the focused sub-skills, collect and rank what they find, route fixes through the build pipeline, and — only when the system is clean — invoke cut-release. The findings docs and the backlog are the source of truth, so you can be killed and resumed.

The chain:

1. refactor            (refactorer agent — alone, first: plan → human approval → execute; everything downstream reads the cleaned tree)
2. write-tests         (test-writer agent — alone, second: the audits should run against the real net)
3. audit-security · audit-performance · audit-product   ← fresh agents, IN PARALLEL (read-only)
4. write-readme        (the handover document — refreshed against the tree as it now stands)
5. manual-test         (read-only briefing for the human)
   → collect findings → rank (severity-rubric) → file 🔴/🟡 as rework tasks
   → ONE build-tasks run → re-run ONLY the affected audits, ONCE
   → still open?  → needs_human, surface it, stop
   → no open 🔴?  → cut-release (version + changelog + notes + tag + PR, always confirmed)
   → build .dev-skills/release/release-summary.md

Why that order. The first two steps mutate the working tree, so they run sequentially and alone — a refactor moving code under a running audit is how a release phase produces nonsense. The audits mutate nothing, so they fan out: this is the one place the workflow parallelizes where the build phase deliberately did not. manual-test runs last because its briefing should describe the tree the human will actually open. Dynamic audits that drive the running stack (audit-performance, audit-product) acquire the env lease themselves (../_shared/build-pipeline/env-access.md), so they self-serialize on the one running stack while the static ones run freely.

Audits only audit. They never edit product code and never install or configure anything — tooling belongs to setup-dev-environment, production capabilities to setup-production-environment. An audit that needs something that does not exist records it as a finding.

Language & git

Respond and reason in the user's language. Each sub-skill follows the same rule on its own. Never translate code, identifiers, commands, or file paths. (Commit messages are always English — the commit skill, invoked by cut-release, enforces that.)

Workflow vocabulary follows ../_shared/glossary.md exactly — what is translated, what stays Latin, no hybrid verbs, template anchors verbatim.

One branch — the current one, normally main. Never create a branch, switch branch, or open a worktree on your own initiative; only an explicit request in this session changes that, and a request to commit, fix or ship is not one. Full rule: ../_shared/git-workflow.md.

Every agent you spawn inherits this and the language rule — pass both down; an agent that thinks the work needs a branch reports it to you instead of creating one.

Modes

Read .dev-skills/release/.release-config.md for mode and the enabled steps. If absent, ask once (defaults: interactive + all applicable) and write it. Full rules: ../_shared/release-pipeline/release-config.md. The audit machine, severity, and report shapes: ../_shared/release-pipeline/audit-method.md, severity-rubric.md, report-template.md.

• interactive — present the chain and confirm; stop at each 🔴, before filing rework, and before cut-release. The refactor plan always comes back to you and waits for the human's approval, in both modes.
• autopilot — run the chain back-to-back without stopping; except the three things that always stop: the refactor plan's approval, an open finding after the single fix round (needs_human), and cut-release itself.

Procedure

- [ ] Step 0: Intake — confirm the build is complete; read the spec contracts + .release-config.md (write if absent); detect resume
- [ ] Step 1: Repo steps, in order and alone — refactorer agent (plan → approval → execute), then test-writer agent
- [ ] Step 2: Audits — spawn audit-security · audit-performance · audit-product in parallel (fresh agents)
- [ ] Step 3: Handover + briefing — /write-readme, then /manual-test for the human's hands-on pass
- [ ] Step 4: Triage — rank all findings; file 🔴/🟡 as rework tasks (plan-development amend); ⚪ logged only
- [ ] Step 5: One fix round — build-tasks fixes the rework → re-run ONLY the affected audits, once → still open = needs_human
- [ ] Step 6: Cut — no open 🔴 → invoke cut-release (always confirmed); honor --skip-ship
- [ ] Done: build release-summary.md; refresh the project documentation map; report the verdict, the filed tasks, and the handoff

Step 0: Intake + resume

Confirm the build phase is done (.dev-skills/build-plan/board.md shows no ready/in_progress feature tasks left, or the user says so). Read the contracts the steps need (.dev-skills/project-spec/architecture.research.md, design-decisions.research.md, user-flows.research.md) and .dev-skills/project-setup/verification.md (how to bring the stack up and drive it). Read .release-config.md (write it if absent). Detect resume: an existing .dev-skills/release/*.md with a clean verdict need not re-run unless its tasks changed; open rework tasks left by a killed run resume where they are. Honor --only <step> (run just that one) and --skip-ship (everything except the cut).

Step 1: The repo steps (sequential, alone)

Run refactor and, when it is finished, write-tests — each inside its own named agent, one at a time, never in parallel with anything. Both change the working tree; the audits must see the settled tree. The agents exist so the two longest autonomous runs of the release don't fill the conductor's context: each preloads its procedure skill, works in isolation, and hands back a report.

• Refactor runs as two spawns of the refactorer agent (subagent_type: refactorer). First spawn it in plan phase: it checks the safety net (it refuses to work on a red suite — if it stops there, fix that first, a run-task job, before continuing the chain), measures, writes the "before" signals into .dev-skills/release/refactor.md and returns the ranked plan without executing anything. Show that plan to the human and wait for approval in both modes — do not try to pre-approve it for the user. Then spawn the agent again in execute phase with the approved items; a large plan may be split across several sequential execute spawns, one batch each. It applies them one at a time with the gate after each and finishes the record.
• Spawn the test-writer agent once (subagent_type: test-writer). It may finish with the suite red — that is a result, not a failure: it found a real bug and filed a task rather than quietly patching the product. Treat those tasks as findings in Step 4, and do not let a red suite from a filed bug be mistaken for a broken run. Its prune proposals (tests worth deleting) come back in its report — surface them to the human; nothing is deleted silently.

Step 2: Audits (parallel fan-out)

Spawn each enabled audit as a fresh subagent: they are independent and read-only → launch them together. Each reads its contract, probes, proves, ranks, writes .dev-skills/release/<noun>-audit.md, and returns its verdict (clean / N blockers / N majors). A sub-skill not yet available in this collection is a stop condition regardless of mode: report it and let the user decide whether to skip that step or build the skill first.

Step 3: Handover document, then the human's briefing

Invoke /write-readme first. It writes or refreshes README.md against the tree as it now stands — the verified way another person clones this and gets it running, what deploying actually takes today, what they must bring themselves, and how to reach a clean seeded state. It is read-only on product code and every command in it is verified against the repo rather than recalled. No README, or one that has drifted a release behind, is the most common reason a finished product cannot be handed to anyone.

Then invoke /manual-test. It proves nothing and changes nothing — it writes .dev-skills/release/manual-test-brief.md so the human can check by hand what no machine decides, starting with everything accepted as review: auto. Its output is a handoff, not a gate: it never blocks the cut, but it is always surfaced in the summary.

Step 4: Triage

Collect every findings doc. The audits (and refactor / write-tests for what they found and did not fix) already filed 🔴/🟡 as rework tasks (type: rework, via plan-development's amend mode) and ranked per severity-rubric.md; you reconcile and present the combined picture.

Reconcile the grain too. Each step grouped its own findings into coarse tasks (../_shared/build-pipeline/planning-method.md), but they cannot see each other: two audits often file separate tasks for the same surface or the same cause. Merge those into one before the fix run — keeping every finding as its own acceptance entry — and keep each 🔴 in its own task. If the merged backlog still exceeds 15 open tasks, say so and confirm the count with the human rather than handing build-tasks a wall of one-finding tasks. In interactive, confirm before the fix run; before any destructive backlog change (cancelling or reopening a done task) always stop, in both modes.

A finding that says production is missing a capability — no hard spend cap, no error tracking, no rate limit configured — is not a rework task for the code: it goes to /setup-production-environment. Name it as such in the summary rather than filing it against a developer.

Step 5: One fix round (no loop)

1. Fix — invoke build-tasks once to drive the open rework tasks. You fix nothing yourself.
2. Re-run — re-run only the steps whose findings were addressed, as fresh agents, to confirm the contract now holds (proven, not assumed).
3. Then decide. Anything still open after that single round is needs_human — surface it and stop, in both modes. There is no iteration counter and no second round: a finding that survives a targeted fix is a signal about the product, not something more rounds resolve. This is the same rule the build loop follows (../_shared/build-pipeline/verification-method.md). Open 🟡 do not block; record them for the human's call.

Step 6: Cut (the only outward-facing step)

When no open 🔴 remains (and --skip-ship was not set), invoke cut-release. It confirms the tree is clean and no blocker is open, then updates docs + version + changelog + release notes, tags, commits, and opens the PR — always with explicit confirmation, in both modes. It stops before production. If cut-release is not yet available, report that the release is audit-clean and ready to cut by hand.

Done: summary + handoff

Build .dev-skills/release/release-summary.md (report-template.md) — decisions-first: the verdict, open blockers and any waivers (the human's action list), the rework filed, every step run with its verdict, the hands-on briefing, and what shipped if cut-release ran. Do not re-derive — roll up each step's verdict plus the cut result. Then refresh the project documentation map block in the root CLAUDE.md — idempotent, only between the markers, per ../_shared/agent-guide.md (this is the release phase's primary map refresh; it runs even under --skip-ship). Finally, hand off the two things that are the human's: the hands-on pass from manual-test, and — when the product is going live — /setup-production-environment, which is never auto-run from here.

Rules

1. Conduct, don't duplicate. Never refactor, test, audit, fix, or ship yourself — spawn the named agents and the audit subagents, invoke build-tasks for fixes and cut-release for the cut.
2. Repo steps sequentially and alone; audits in parallel. refactor then write-tests, each in its own agent and finished before the next starts; the read-only audits fan out together.
3. Audits never fix and never install. They file findings. Code is fixed by build-tasks; tooling by setup-dev-environment; production capabilities by setup-production-environment.
4. One fix round, then a decision. Re-run only what was addressed, once; whatever is still open is needs_human. No loop, no counter.
5. Only a 🔴 blocks the cut. Majors are filed, not blocking; minors are logged. Severity follows the shared rubric, against the contract — not taste.
6. The cut always stops for the human, in both modes, and stops before production.
7. Putting the product live is not part of this run — setup-production-environment is invoked by hand, deliberately.
8. Resume, don't restart. Reuse a clean verdict and in-flight rework; never re-run a settled step or rebuild a finished fix without reason.
9. release-summary.md is always rolled up from the step outputs and the cut result; never hand-authored from scratch.
10. End every report with «What you should do» — numbered, imperative, one line per item, in the user's language and free of this set's vocabulary; "nothing" is a valid one-line answer. Timings, where reported, must reconcile with their total. ../_shared/build-pipeline/report-format.md.