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.

```js
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.

```js
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:**
```bash
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

```js
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.

```js
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.

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

After it stops, review the tag then:
```bash
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.