relicario/docs/superpowers/RELEASE-WORKFLOW.md

Release Workflow

Unified lifecycle workflow at .claude/workflows/release.js.
Invoke from any Claude Code session via the Workflow tool.

---

Actions at a glance

Action	When	Mode
develop	Implement plan tasks	single (phone/remote) or multi (PC, supervised)
verify	Check tests pass	—
debug	Fix a failing test or broken feature	— (always sequential)
release	Cut and tag a version	—

---

Add features / implement a plan

Single-agent (phone-friendly, fire-and-forget)

One agent works through all plan tasks sequentially. Kick off and check the progress tree later.

Workflow({
  name: 'release',
  args: { action: 'develop', mode: 'single', release: 'v0.5.0' }
})

What happens:

1. Discovers all plan files matching v0.5.0
2. PM agent reads plans, orders tasks respecting dependencies
3. One dev agent per task runs sequentially
4. Full cargo test + cargo build + cargo clippy verify pass
5. Updates STATUS.md

Multi-agent (PC, supervised by PM)

PM reads the plans, decides N dev streams, writes kickoff prompt files. You open the terminals.

Workflow({
  name: 'release',
  args: { action: 'develop', mode: 'multi', release: 'v0.5.0' }
})

What happens:

1. Discovers plans
2. PM agent assigns tasks to N dev streams
3. Generates PM + N dev prompt files in docs/superpowers/coordination/
4. Prints terminal-open instructions

Then you:

cd tools/relay && ./start.sh          # start relay server
# open N+1 terminal windows
# PM window:    paste coordination/v0.5.0-pm-prompt.md
# Dev-A window: paste coordination/v0.5.0-dev-a-prompt.md
# Dev-B window: paste coordination/v0.5.0-dev-b-prompt.md

The PM supervises devs in real time via the relay. You watch all terminals.

---

Run tests only

Workflow({ name: 'release', args: { action: 'verify' } })

Runs cargo test, cargo build --all-targets, cargo clippy. Returns pass/fail summary.

---

Debug iteration

After you find a broken test or unexpected behavior, hand the failure context to the debug action. It loops up to 5 times: hypothesize → read code → fix → verify → commit.

Workflow({
  name: 'release',
  args: {
    action: 'debug',
    context: 'cargo test output:\n...<paste failing test output here>...'
  }
})

Returns { status: "fixed", iterations: N } when clean, or { status: "max-iterations" } if it needs your eyes.

---

Cut a release

Runs verify first; blocked if tests fail.
Writes CHANGELOG, updates STATUS + ROADMAP, creates annotated tag.
Stops before pushing — you confirm manually.

Workflow({
  name: 'release',
  args: { action: 'release', release: 'v0.5.0' }
})

After it stops, review the tag then:

git push && git push --tags

---

Full lifecycle example

1. DEVELOP features
   Workflow({ name:"release", args:{ action:"develop", mode:"single", release:"v0.6.0" } })

2. VERIFY manually (you run the extension in browser, test your flows)

3. DEBUG any failures you find
   Workflow({ name:"release", args:{ action:"debug", context:"<paste failure>" } })
   # repeat as needed

4. VERIFY again to confirm clean
   Workflow({ name:"release", args:{ action:"verify" } })

5. RELEASE
   Workflow({ name:"release", args:{ action:"release", release:"v0.6.0" } })
   # review tag, then: git push && git push --tags

---

Phone vs PC

Scenario	Recipe
Kick off a release from your phone / remote session	develop + mode:"single" — fires in background, check /workflows
At your PC, want to supervise and intervene	develop + mode:"multi" — generates prompts, open terminals
Quick sanity check	verify
Fixing a bug you found while testing	debug with failure context
Cutting and tagging	release — always confirms before push

---

Plan file discovery

The develop action scans docs/superpowers/plans/ for files whose filename or opening lines reference the release label. To be explicit, pass plan paths directly (not yet wired — add args.plans if needed).

---

Relay server roles

The relay at localhost:7331 supports roles: pm, dev-a, dev-b, dev-c.
Start it before opening terminal sessions: cd tools/relay && ./start.sh
See docs/superpowers/coordination/RELAY.md for protocol details.