SPEC-4 — superpowers-native lifecycle (role-per-phase skill bundles, /fleet Lifecycle view, /fleet-implement)

docs/SPEC-4-smoke-checklist.md

@@ -0,0 +1,26 @@
+# SPEC-4 — term-driven smoke checklist
+
+Run after publishing `v0.4.0` (install the package into pi, `/reload`).
+
+| # | Row | Action | Expected |
+|---|-----|--------|----------|
+| 1 | install | add `"npm:@getpipher/armory-fleet@0.4.0"` to `~/.pi/agent/settings.json` packages, `/reload` | pi loads the extension, no EditorTheme crash |
+| 2 | /fleet | open panel, `tab` to Lifecycle | Lifecycle tab renders (between Fleet + Agents), empty list (no runs yet) |
+| 3 | Run lifecycle | press `r`, type a trivial task, submit; lifecycle name blank→default | row appears with ▶ status, phase advances, phase index N/5 updates |
+| 4 | checkpoint | at a checkpoint (brainstorm/plan/review), the `c:Continue v:Revise a:Abort` submenu shows | `c` advances; `v` opens the feedback Input → submit re-runs the phase; `a` reverts the todo + aborts |
+| 5 | completion | let it finish | row shows ✓, todo marked done in armory-todo (check `/todo`) |
+| 6 | i:Info | select a lifecycle row, press `i` | phase-timeline detail pane renders ([x]/[~]/[ ] markers + artifact paths), `esc` returns |
+| 7 | /fleet-implement <task> | run the slash | lifecycle starts, row appears in Lifecycle view, notify on completion |
+| 8 | --auto | `/fleet-implement trivial --auto` | runs end-to-end (no checkpoints), ✓ on done |
+| 9 | --lifecycle | `/fleet-implement x --lifecycle default` | selects the named lifecycle; bad name → actionable error notify |
+| 10 | agent tool | the model calls `subagent({ task, lifecycle: "default" })` | runs end-to-end (auto), returns a phase summary as the tool result |
+| 11 | failure | force a failing task (e.g. impossible request) | lifecycle status ✗ failed; todo stays open; row shows ✗ |
+| 12 | smoke script | `node --import tsx scripts/spec-4-smoke.mts` | real Ollama pi lifecycle runs end-to-end, `SMOKE PASSED ✅` |
+
+## Notes
+- RECTOR's `claude` CLI OAuth is expired — CC-phase backend rows skip gracefully (per the SPEC-3
+  smoke pattern); re-auth `claude` first to exercise a per-phase `backend: claude` lifecycle.
+- The Lifecycle view is a `ctx.ui.custom()` panel → threads the factory `Theme` arg; the
+  EditorTheme gotcha (§9.5) is a `setEditorComponent` concern and does not bite the read-only
+  lifecycle view. A live-theme-switch mid-panel is a refinement (recorded); the panel caches
+  `theme` from the factory, which is fine for v0.4.

docs/superpowers/plans/2026-07-24-scratch-hello.md

@@ -0,0 +1,78 @@
+# scratch-hello Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add a `hello()` function to `scripts/scratch-hello.ts` that returns the string `'hello from fleet'`.
+
+**Architecture:** Single-file library-style module. One named export, no imports, no side effects. The file lives outside `tsconfig.json`'s include scope and `package.json`'s `files` array — it is not typechecked, tested, or published.
+
+**Tech Stack:** TypeScript (raw `.ts` via tsx at runtime), ESM (`"type": "module"`).
+
+## Global Constraints
+
+- File extension: `.ts` (not `.mts`)
+- Export style: named export (`export function hello`)
+- Return type: explicit `: string` (strict mode convention)
+- Return value: string literal `'hello from fleet'`
+- No imports, no side effects, no `main()`, no `console.log`
+- No test file — scratch file is outside CI gate per design spec
+- 2-space indentation, trailing semicolons (match project convention)
+
+---
+
+### Task 1: Create scripts/scratch-hello.ts with hello() function
+
+**Files:**
+- Create: `scripts/scratch-hello.ts`
+
+**Interfaces:**
+- Consumes: nothing (zero imports)
+- Produces: `export function hello(): string` — returns `'hello from fleet'`
+
+- [ ] **Step 1: Create the file with the hello() function**
+
+Create `scripts/scratch-hello.ts` with exactly this content:
+
+```ts
+export function hello(): string {
+  return 'hello from fleet';
+}
+```
+
+- [ ] **Step 2: Verify the file was created correctly**
+
+Run: `cat scripts/scratch-hello.ts`
+
+Expected output:
+```
+export function hello(): string {
+  return 'hello from fleet';
+}
+```
+
+- [ ] **Step 3: Verify the function works at runtime**
+
+Run: `node --import tsx --eval "import { hello } from './scripts/scratch-hello.ts'; console.log(hello());"`
+
+Expected output:
+```
+hello from fleet
+```
+
+- [ ] **Step 4: Verify no side effects on import**
+
+Run: `node --import tsx --eval "import './scripts/scratch-hello.ts'; console.log('no side effects');"`
+
+Expected output:
+```
+no side effects
+```
+
+(If any output appears before "no side effects", the file has unintended side effects.)
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add scripts/scratch-hello.ts
+git commit -m "feat: add scratch-hello.ts with hello() function"
+```

docs/superpowers/reviews/2026-07-24-scratch-hello-review.md

@@ -0,0 +1,84 @@
+# Code Review: scratch-hello.ts
+
+**Date:** 2026-07-24
+**Reviewer:** Inline (pi — no subagent dispatch available)
+**Base SHA:** d031fc7
+**Head SHA:** a4209d2
+**Files reviewed:** `scripts/scratch-hello.ts`
+
+---
+
+## Review Methodology
+
+Diff examined against:
+- Design spec: `docs/superpowers/specs/2026-07-24-scratch-hello-design.md`
+- Implementation plan: `docs/superpowers/plans/2026-07-24-scratch-hello.md`
+- Project conventions: `tsconfig.json`, `package.json`, existing `src/` files
+
+---
+
+## Diff
+
+```
++export function hello(): string {
++  return 'hello from fleet';
++}
+```
+
+Single new file, 3 lines, no modifications to existing code.
+
+---
+
+## Spec Compliance Checklist
+
+| Requirement | Spec says | Implementation | Status |
+|---|---|---|---|
+| File path | `scripts/scratch-hello.ts` | `scripts/scratch-hello.ts` | ✅ |
+| Extension | `.ts` | `.ts` | ✅ |
+| Export style | Named export `hello` | `export function hello` | ✅ |
+| Return type | Explicit `: string` | `: string` | ✅ |
+| Return value | `'hello from fleet'` | `'hello from fleet'` | ✅ |
+| Imports | None | None | ✅ |
+| Side effects | None | None (verified at runtime) | ✅ |
+| No `main()` | Yes | No `main()` | ✅ |
+| No `console.log` | Yes | No `console.log` | ✅ |
+| No test file | Out of scope | No test file created | ✅ |
+| 2-space indent | Project convention | 2-space indent | ✅ |
+| Trailing semicolons | Project convention | Semicolon present | ✅ |
+
+All spec requirements met.
+
+---
+
+## Findings
+
+### Strengths
+
+1. **Exact spec match** — The implementation is identical to the design spec's code snippet. No deviation.
+2. **Clean diff** — Single new file, 3 lines, zero modifications to existing code. No collateral damage.
+3. **Verified at runtime** — Import + call produces `hello from fleet`; bare import produces no side effects.
+4. **Correct isolation** — File is outside `tsconfig.json` include scope (`src`, `test` only) and `package.json` `files` array. Will not be typechecked, tested, or published. Matches design intent.
+5. **No trailing newline** — Consistent with project convention (checked 6 existing `src/` files; all end without trailing newline).
+
+### Issues
+
+**Minor — Quote style inconsistency:**
+- The file uses single quotes (`'hello from fleet'`).
+- The project predominantly uses double quotes (e.g., `"fl-"` in `run-registry.ts`, all import paths in `run-lifecycle.ts`).
+- No `.eslintrc` or `.prettierrc` enforces a style — this is convention only.
+- The design spec itself specifies single quotes in the code snippet, so the implementation correctly follows the spec.
+- **Verdict:** Non-blocking. Scratch file, not published, not typechecked. Convention drift is cosmetic.
+
+### TDD Considerations
+
+The TDD skill mandates "NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST." This file has no test. However:
+- The design spec explicitly classifies this as a scratch/throwaway file, outside CI gate and tsconfig scope.
+- The TDD skill has an exception for "Throwaway prototypes" (with partner approval).
+- The plan includes runtime verification steps (import + call, bare import) that serve as manual verification gates.
+- **Verdict:** Acceptable per the design spec's explicit decision. No test file is the correct outcome here.
+
+---
+
+## Assessment
+
+**Ready to proceed.** No Critical or Important issues. One Minor issue (quote style) is cosmetic, non-enforced, and consistent with the design spec. The implementation is a faithful, verified execution of the plan.

docs/superpowers/specs/2026-07-24-scratch-hello-design.md

@@ -0,0 +1,50 @@
+# Design: scratch-hello.ts
+
+**Date:** 2026-07-24
+**Status:** Approved
+**Scope:** Single scratch file — `scripts/scratch-hello.ts`
+
+## Purpose
+
+Add a `hello()` function to a scratch file that returns the string `'hello from fleet'`. This is a throwaway utility stub — not part of the published package surface, not imported by `src/`, and not part of the CI test gate.
+
+## Approach
+
+**Chosen: Plain export, no side effects.**
+
+A scratch file should be minimal and importable. No `main()`, no `console.log`, no self-test assertion. Just the function.
+
+### Alternatives considered
+
+- **Export + self-invoking main** — Adds a runnable entry point (`node --import tsx scripts/scratch-hello.ts` prints output). Rejected: unnecessary for a scratch stub; the function is the deliverable, not a CLI.
+- **Export + inline self-test** — Combines function with an assertion. Rejected: over-engineered for a throwaway file.
+
+## Specification
+
+### File: `scripts/scratch-hello.ts`
+
+```ts
+export function hello(): string {
+  return 'hello from fleet';
+}
+```
+
+- **Extension:** `.ts` (per task specification; matches project's raw-TS-via-tsx convention)
+- **Export:** Named export `hello`
+- **Return type:** Explicit `: string` (strict mode, project convention)
+- **Return value:** String literal `'hello from fleet'`
+- **Imports:** None
+- **Side effects:** None
+
+### Out of scope
+
+- No test file (`test/*.test.mts`) — scratch file, not CI-gated
+- No `package.json` script entry — not a runnable target
+- No import from `src/` — standalone stub
+- No JSDoc — single-line function is self-documenting
+
+## Non-goals
+
+- This file is NOT part of the published package (`package.json` `files` array excludes `scripts/`)
+- This file is NOT covered by `tsconfig.json` (only `src` and `test` are included)
+- This file will NOT be typechecked by `pnpm typecheck` or tested by `pnpm test:run`

lifecycles/default.md

@@ -0,0 +1,54 @@
+---
+name: default
+description: The superpowers-native 5-phase lifecycle (brainstorm→plan→implement→review→finish).
+backend: pi
+phases:
+  - name: brainstorm
+    skills: [brainstorming]
+    agent: general-purpose
+    checkpoint: true
+  - name: plan
+    skills: [writing-plans]
+    agent: general-purpose
+    checkpoint: true
+  - name: implement
+    skills: [executing-plans, test-driven-development, verification-before-completion]
+    agent: general-purpose
+    checkpoint: false
+  - name: review
+    skills: [requesting-code-review, receiving-code-review]
+    agent: general-purpose
+    checkpoint: true
+  - name: finish
+    skills: [finishing-a-development-branch]
+    agent: general-purpose
+---
+
+## brainstorm
+You are the **brainstorm** phase of a superpowers lifecycle. Use the brainstorming skill.
+Task: {{task}}
+{% if prev %}Previous phase ({{prev.name}}) produced: {{prev.summary}}
+Artifacts to read: {{prev.paths}}{% endif %}
+Explore the task, produce a design doc per the brainstorming skill. End your response with an
+`Artifacts:` block (YAML) listing the produced file paths + a kind.
+
+## plan
+You are the **plan** phase. Use writing-plans. Read the brainstorm phase's design artifact.
+{% if prev %}Previous phase: {{prev.summary}} | Artifacts: {{prev.paths}}{% endif %}
+{% if feedback %}Human feedback on a prior attempt: {{feedback}}{% endif %}
+Write the implementation plan per writing-plans. End with an `Artifacts:` block.
+
+## implement
+You are the **implement** phase. Use executing-plans + test-driven-development + verification-before-completion.
+Read the plan artifact. Implement it, run tests, verify before claiming done.
+End with an `Artifacts:` block (files changed).
+
+## review
+You are the **review** phase. Use requesting-code-review + receiving-code-review.
+Review the implementation against the plan + design. Produce review findings.
+End with an `Artifacts:` block (review notes path).
+
+## finish
+You are the **finish** phase. Use finishing-a-development-branch.
+Decide merge/PR/cleanup per the skill and execute it. End with an `Artifacts:` block
+(or omit on a merge/PR with no further file artifact — terminal-phase exemption).