@nklisch/pi-agile-workflow 0.15.3

package/skills/autopilot/SKILL.md

@@ -0,0 +1,330 @@
+---
+name: autopilot
+description: >
+  Goal-statement or direct-invocation queue driver for agile-workflow. Use when a harness goal or user
+  request says to run autopilot, drain ready work, finish an epic, continue through .work/active/, or
+  make autonomous progress on the substrate. Reads .work/active/, picks ready items by depends_on and
+  stage, delegates to design, implement, and review skills, commits transitions, and repeats until the
+  scope is done or blocked. Before reporting complete, runs a final peer-review/fresh-context
+  completion pass and fixes or files accepted findings. No /loop or --resume mechanics; the harness
+  goal/continuation feature owns long-running persistence. Epic-scoped by default; --all drains all
+  active work; free-text scope directives are allowed.
+---
+
+# Autopilot
+
+Autopilot is the queue policy that runs inside a harness goal. It can also be
+called directly as a skill. It does not schedule watchdog loops, manage timers,
+or maintain a progress file. The substrate is the state, and the harness
+goal/continuation feature is responsible for carrying long-running work across
+compaction or continuation turns.
+
+Agents may invoke this skill when the active goal statement or user request asks
+for autonomous substrate progress. The user can still invoke it directly.
+
+## Goal Contract
+
+The cleanest invocation is a goal statement that names autopilot:
+
+> Use agile-workflow autopilot to drain `<scope>` until all in-scope active
+> items are done or blocked.
+
+When an active goal exists, treat the goal statement as the invocation surface
+and run this skill inside that goal. Do not create a nested goal. If no active
+goal exists, run the same queue policy inline for the direct invocation.
+
+Only create a new harness goal when the caller explicitly asks the agent to
+create/start one and the harness exposes that API. Otherwise, attach to the
+active goal or run inline.
+
+Use `.work/active/` as the resume point. Do not call `/loop`, do not create
+watchdog schedules, and do not support `--resume`; those are legacy mechanics.
+
+When running under a harness goal, mark/report the goal outcome this way. When
+running inline, use the same categories in the final summary:
+
+- **Complete** when no in-scope active item remains at `drafting`,
+  `implementing`, or `review`.
+- **Blocked** when in-scope items remain but none are ready, an item has a hard
+  blocker, or the review circuit-breaker escalated unresolved work.
+- **Interrupted** when the user stops the run. Finish the current safe
+  transition, commit if anything changed, summarize the remaining queue, and
+  let the harness/user decide whether to continue the goal later.
+
+## Arguments
+
+- `autopilot <epic-id>` - drain items under `<epic-id>` transitively via the
+  parent chain until the scoped queue is done or blocked.
+- `autopilot --all` - drain all `.work/active/` items.
+- `autopilot <free-text>` - interpret as a scope directive, such as "finish the
+  dangling work", "wrap up phase 14", or "drain everything tagged refactor".
+  Log the interpretation in the run summary. When scope is ambiguous, prefer the
+  broader active-work interpretation. `.work/backlog/` is always out of scope.
+
+## Prerequisites
+
+Two gates, with different timing:
+
+1. **Before anything:** `.work/CONVENTIONS.md` exists. If not, halt: "No substrate found. Run
+   `/agile-workflow:convert` first."
+2. **After Phase 1 resolves the scope** (the check is route-aware, so it runs against the
+   resolved work set): foundation docs exist (`docs/VISION.md` or `docs/SPEC.md`) — required
+   when the scope contains **any** item that routes to the design family (`epic-design` /
+   `feature-design` / `refactor-design` / `perf-design`), which read foundation docs as their
+   design anchor. *(Design family = skills that read foundation docs as their design anchor; a
+   deployment adding such a skill extends this list.)* If absent in that case, halt the whole
+   run with a clear message **before delegating any item** — including in a mixed scope: do not
+   partially drain the non-design-family items, a partial drain leaves the queue in a state the
+   goal statement didn't describe. A scope with no design-family routes — drafting items that
+   all route cross-plugin to `agentic-research:research-orchestrator` (`[research]` items anchor
+   on the commissioning item body + the research substrate, not VISION/SPEC), and/or
+   `implementing`/`review` items only — runs without foundation docs.
+
+These are hard halts because the queue has no reliable substrate or design
+anchor without them.
+
+## Workflow
+
+### Phase 1: Resolve Scope
+
+Build the scope from the argument:
+
+- Epic id: include the epic plus descendants through `parent` links.
+- `--all`: include every item in `.work/active/{epics,features,stories}/`.
+- Free text: inspect item ids, tags, parents, titles, and bodies; select the
+  matching active subset and record the interpretation.
+
+Only active items are candidates. Backlog items must be promoted through
+`scope` before autopilot can touch them.
+
+**Settle the implementation tier once, here at kickoff** — don't let it default
+silently per wave. If the goal/args/user named a tier (or the project fixes one
+in `.work/CONVENTIONS.md`), honor it. Otherwise, when the goal permits
+interaction, ask once for a capability tier — **baseline**, **raised**, or
+**highest** — and lock it for the whole run. The host resolves that capability to
+its available generic subagent model/effort at dispatch time. Under an autonomous
+goal contract that forbids mid-run questions, use the `implement-orchestrator`
+default and **state the tier in the run summary** so a cheap-tier drain is never
+a silent surprise. Pass the settled tier down in the Phase 4 caller note so
+`implement-orchestrator` does not re-ask.
+
+### Phase 2: Build The Queue
+
+Filter candidates to `stage` in `{drafting, implementing, review}`.
+
+An item is ready when every `depends_on` entry is terminal:
+
+- `stage: done`, or
+- already moved to `.work/releases/` or `.work/archive/`.
+
+Use `.work/bin/work-view` when it can answer the query; otherwise read
+frontmatter directly.
+
+**`[scan]`-tagged items are never queued.** `work-view --ready`/`--blocked` exclude
+them by construction — they are engagement-owned scan-campaign scaffold driven by
+`/agile-workflow:deep-code-scan`, not ordinary work. (If you fall back to reading
+frontmatter directly because `work-view` is unavailable, replicate this: skip any
+item whose `tags` contain `scan`.) The remediation a scan produces is a separate
+`fix-<goal>` epic with normal routing tags — that drains here as usual.
+
+### Phase 3: Pick The Next Item
+
+Sort ready candidates by:
+
+1. `depends_on` count ascending
+2. `created` ascending
+
+Pop the first item. If there are no ready candidates, evaluate the stop rules.
+
+For `stage: implementing`, the picked item is only an anchor. Hand the whole
+in-scope implementing band to `implement-orchestrator`; do not pre-bundle it
+yourself.
+
+### Phase 4: Delegate Work
+
+Invoke the relevant skill through `Skill` or the local skill mechanism. Include
+this caller note in every delegated prompt:
+
+> Delegated by an active agile-workflow autopilot goal for `<scope>`. Resolve
+> ambiguities with judgment, log rationale in the item body, and do not ask
+> strategic questions unless a hard halt condition applies. Implementation tier
+> for this run: `<settled tier>` — use it for worker dispatch; do not re-ask. For large or risky
+> design decisions, use the cross-model advisory review policy from
+> `principles/SKILL.md` (Part IV) only when a different model class is available;
+> peer failures are non-blocking. For deep or complex design work, use **two
+> different model classes** if available, paired across the advisory→adversarial
+> phases in `principles/references/models.md`. A top-tier reasoning peer may take
+> 10 to 30 minutes for a large review; lack of output after a few minutes does
+> not mean it has hung. For subagent role names, load
+> `principles/references/subagents.md`. When hosted in Pi, use only the
+> supported agile-workflow Pi roles for this adapter; whether a reviewer run is
+> cross-model depends on the model/provider selected at spawn time.
+
+Routing:
+
+- `stage: drafting`, `kind: epic` -> `epic-design` (an epic carrying `[research]` is a
+  research-program epic — it routes here as normal epic decomposition; its children are
+  `[research]` features each carrying their own `research_dials:` registration; the tag at
+  epic level signals program decomposition, never an epic-level registration)
+- `stage: drafting`, feature with `tags: [refactor]` -> `refactor-design`
+- `stage: drafting`, feature with `tags: [perf]` -> `perf-design`
+- `stage: drafting`, feature with `tags: [prose]` -> `prose-author`
+- `stage: drafting`, feature with `tags: [research]` -> `agentic-research:research-orchestrator`
+  (**cross-plugin**; the orchestrator runs the grounded engagement end-to-end — verification
+  gates fire inline, there is no separate implement step, and it never binds to a release.
+  Requires the `agentic-research` plugin; without it, treat as a plain feature.)
+- `stage: drafting`, other feature -> `feature-design`
+- `stage: implementing`, epic -> skip direct implementation; children are the
+  work targets
+- `stage: implementing`, non-epic with `tags: [prose]` -> `implement <id>`
+  (inline — single stride, no orchestration; prose does not need parallel
+  coordination)
+- `stage: implementing`, non-epic with `tags: [research]` -> `agentic-research:research-orchestrator`
+  (resume/continue the engagement; research never flows through `implement-orchestrator` or
+  `release-deploy` — a single-pass research engagement may be a story that skips `drafting`.
+  Requires the `agentic-research` plugin; without it, treat as a plain implementing item ->
+  `implement-orchestrator`, mirroring the drafting row's degrade.)
+- `stage: implementing`, non-epic (and NOT `tags: [prose]` or `[research]`) -> `implement-orchestrator <scope>`
+- `stage: review` -> `review <id>` (review self-selects its lane: a **story**
+  fast-advances on `implement`'s verification with no peer pass; a **feature** or
+  **epic** gets a fresh-context deep review — cross-model via peeragent when a
+  different class is reachable (two classes paired across the advisory→adversarial
+  phases for deep/complex scope; see `principles/references/models.md`), else a
+  generic sub-agent prompted as a reviewer from `principles/references/subagents.md`
+  with the strongest appropriate model available (cross-model only if that model
+  is a different class), else a fresh top-class sub-agent)
+
+The delegated skill owns its internal workflow and stage transition. After it
+returns, rebuild the queue from disk rather than relying on cached state.
+
+If a delegated skill reports a hard blocker without a stage transition, append
+a `## Blocker` section to the item body, commit that note, and continue with
+other ready items. The final goal outcome is blocked if unresolved blockers
+remain in scope.
+
+### Phase 5: Review Circuit-Breaker
+
+Track per-item review bounces during the run:
+
+```text
+bounces[<item-id>] = times this item has gone implementing -> review -> implementing
+```
+
+If an item bounces back to `implementing` twice:
+
+1. Append `## Stuck at review` with the latest blockers and the two-pass note.
+2. Leave the item at `review`.
+3. Log it as escalated.
+4. Continue draining other ready work.
+
+Escalated items make the final goal outcome blocked unless the user resolves
+them before the run ends.
+
+### Phase 6: Refactor Cadence (`--all` Only)
+
+Every 5 items advanced to `done` in `--all` mode, delegate a conservative
+discovery pass to `refactor-design` over files touched by those items:
+
+1. Collect touched paths from the commits associated with those item ids.
+2. Invoke `refactor-design <path...>` in discovery mode.
+3. Let `refactor-design` classify and emit any follow-up items.
+4. Rebuild the queue; newly emitted items are picked up naturally.
+
+Never invoke `bold-refactor` from autopilot. It is too aggressive for autonomous
+queue driving.
+
+### Phase 7: Stop Rules
+
+After each queue rebuild:
+
+- If no in-scope active items remain at `drafting`, `implementing`, or `review`,
+  run Phase 8 (Final Peer Review Loop) before reporting completion.
+- If in-scope active items remain but none are ready, the goal is blocked on
+  dependencies or unresolved blockers. Report the blocking ids.
+- If the user interrupts, stop at the next safe boundary and report remaining
+  state without claiming completion.
+- Otherwise pick the next item and continue.
+
+Do not stop because of elapsed time, context size, or "long run" concerns. The
+harness owns continuation. Your job is to keep applying the queue policy until a
+real stop rule fires.
+
+### Phase 8: Final Peer Review Loop
+
+This is the last step before reporting `complete`. It runs in addition to any
+design-time cross-model advisory passes from delegated skills.
+
+When the scoped queue appears drained:
+
+1. Build a concise completion bundle:
+   - scope interpretation
+   - items advanced during this run
+   - final state of in-scope epics/features/stories
+   - commits associated with advanced items
+   - notable design decisions, implementation deviations, blockers resolved,
+     and verification results reported by delegated skills
+2. Run the completion review as the two-phase design-review order from
+   `principles/SKILL.md` Part IV (advisory/completeness, then adversarial). If
+   `peer-review` is available with a different model class, use it; for a deep or
+   complex completion bundle, **use two different model classes** if available,
+   one per phase. Ask for bugs, missed acceptance criteria, unreviewed risks,
+   foundation-doc drift, and substrate-state inconsistencies that would make
+   "complete" premature. A top-tier reasoning peer may take 10 to 30 minutes for a
+   large completion review; do not classify a quiet, still-running process as
+   hung after only a few minutes.
+3. If peeragent would use the same model class, do not use `peer-review`; spawn
+   a generic sub-agent prompted as a reviewer from
+   `principles/references/subagents.md` when available, with the strongest
+   appropriate model. Record it as cross-model only if that spawned model is a
+   different class; otherwise record same-harness fresh-context.
+4. If peer-review is unavailable, use that same generic reviewer-subagent path
+   when available, otherwise the local inline review fallback.
+   If the selected final-review path fails, do not report completion; mark the
+   run blocked on final review and include the failure reason. Do not invent a
+   pass.
+5. For every substantive accepted finding:
+   - Small and clearly safe fix: fix it immediately, run verification, commit,
+     and rebuild the queue.
+   - Needs tracked work: create or update a substrate item at the right stage
+     (`drafting` for design gaps, `implementing` for concrete fixes), commit,
+     and rebuild the queue.
+   - Invalid or lower-value finding: reject it with a one-line rationale in the
+     final review summary.
+6. If rebuilding the queue finds new or regressed `drafting`, `implementing`, or
+   `review` items in scope, return to Phase 2 and drain them. Completion is not
+   allowed while accepted final-review findings remain active.
+7. Once the final review path succeeds, produces no accepted
+   blocking/substantive findings, and the queue is still empty, report the goal
+   as complete.
+
+Record the final review in the autopilot final summary. Do not paste the full
+peer transcript into item bodies; summarize accepted/rejected points where they
+affect specific items.
+
+## Output
+
+Narrate briefly as items advance. Final summary:
+
+- Goal scope and interpretation
+- Items advanced to done
+- Items reviewed and approved
+- Items reviewed and bounced
+- Escalated or blocked item ids
+- Refactor cadences run (`--all` only)
+- Implement-orchestrator bundle summary, if reported
+- Final peer-review status: cross-model, local fallback, skipped, or failed;
+  include accepted findings fixed/filed and rejected findings summary
+- Goal outcome: complete, blocked, or interrupted
+
+## Guardrails
+
+- Never use structured question tool while an autopilot goal is actively driving the
+  delegated work. Resolve with judgment and log rationale.
+- Do not report `complete` until Phase 8 has run successfully and all accepted
+  final-review findings have been fixed or filed back into the queue.
+- Commit after every item state change or blocker note.
+- Do not push, force-push, or release; the user controls publication.
+- Do not touch `.work/backlog/` except to report that backlog items are out of
+  scope.
+- The substrate is the resume point. No `PROGRESS.md`, no watchdog loops, no
+  `--resume`.

package/skills/autopilot/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Autopilot"
+  short_description: "Use Autopilot for repo workflows"
+  default_prompt: "Use $autopilot for this repository."
+policy:
+  allow_implicit_invocation: true

package/skills/board/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: board
+description: >
+  Launch and open the agile-workflow interactive substrate board for a project. Use when the user asks
+  to open, view, serve, inspect, or launch the .work board, substrate board, kanban board, dependency
+  board, or `work-view board`. Requires an existing agile-workflow `.work/` substrate, a compiled
+  board-capable `.work/bin/work-view` binary, and a full terminal session that can keep the
+  long-running local server alive.
+---
+
+# Board
+
+Launch and open the live local board for the current project's `.work/`
+substrate. The board is served by the compiled `work-view` binary and reads the
+substrate directly; it does not generate a static HTML file.
+
+This skill is for **opening the UI for the user**, not merely printing a command.
+Run it in a full terminal / PTY session that stays attached while the local
+server runs. Do not launch it from a short-lived noninteractive shell that exits
+after the first line of output, because that kills the board server.
+
+## Workflow
+
+1. From the project root or a descendant directory, start the board in a full
+   terminal session:
+
+   ```bash
+   .work/bin/work-view board
+   ```
+
+   Leave that terminal session running. By default, `work-view board` opens the
+   browser after it binds. Do not add `--no-open` or `--print` unless the user
+   asks for URL-only/headless behavior or the environment has no desktop browser.
+
+2. Pass user-supplied arguments through to `work-view board` when present. If
+   the user asks for a specific port but still wants the UI opened, keep browser
+   opening enabled:
+
+   ```bash
+   .work/bin/work-view board --port 8181
+   ```
+
+   Use `--no-open` / `--print` only for explicit URL-only runs:
+
+   ```bash
+   .work/bin/work-view board --port 8181 --no-open
+   ```
+
+3. Report the printed localhost URL to the user after the server starts. The
+   command binds to `127.0.0.1`, scans upward when the requested port is busy,
+   then opens a browser when a desktop session is available. In headless
+   sessions it prints the URL and keeps serving.
+
+## Failure Handling
+
+- If no `.work/CONVENTIONS.md` exists in the current directory or an ancestor,
+  stop and tell the user to run `$agile-workflow:convert` first.
+- If `.work/bin/work-view` is missing or does not support `board`, tell the
+  user that the interactive board requires a compiled board-capable `work-view`
+  binary for this project.
+- For compatibility with older invocations, `plugins/agile-workflow/scripts/work-board.sh`
+  is only a shim. Prefer `.work/bin/work-view board` for all new usage.

package/skills/board/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Board"
+  short_description: "Launch the agile-workflow board"
+  default_prompt: "Use $board to open the live agile-workflow board for this project."
+policy:
+  allow_implicit_invocation: false

package/skills/bold-refactor/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: bold-refactor
+description: >
+  Find beautiful code abstractions and cross-cutting simplifications. Applies conceptual lenses
+  (elimination, unification, inversion, algebraic, declarative, domain crystallization) to surface
+  bold architectural reconceptions, then produces a refactor EPIC with child features tagged
+  [refactor] and declared depends_on chains. The epic and its children land in .work/active/ — the
+  actual refactor work then flows through /agile-workflow:refactor-design and
+  /agile-workflow:implement. User-invocable only — too aggressive for auto-trigger.
+---
+
+# Bold-Refactor
+
+You are not an LLM doing safe refactoring. You are a master architect who has
+spent a week studying this codebase and is now ready to tell the team what
+they've been doing wrong — and what a beautiful version of this code actually
+looks like.
+
+LLMs default to timid, incremental refactoring: extract a helper here, add an
+interface there, rename for clarity. That's housekeeping, not architecture. You
+do something fundamentally different. You look at a subsystem and ask: **what
+single elegant idea, if it existed, would make half of this code unnecessary?**
+
+You think in reconceptions, not cleanups. You find the abstractions that are
+*screaming* to exist but haven't been named yet. You spot five things that look
+different but are secretly the same thing. You see the 500-line module that could
+be 50 lines if you inverted one assumption.
+
+This is the code equivalent of "stop using Inter and a purple gradient." Stop
+extracting helpers. Start reimagining.
+
+## What this is NOT
+
+- **Cosmetic changes** (variable naming, early returns) — handled inline by
+  refactor-conventions or `/agile-workflow:refactor-design`
+- **File reorganization** (folder layout, module boundaries) — handled by
+  `/agile-workflow:refactor-design`
+- **Safe incremental dedup** (extracting shared functions) — handled by
+  `/agile-workflow:refactor-design`
+- **Performance work** — `/agile-workflow:perf-design`
+- **Implementation** — you produce an epic + child features, you don't write code
+
+## Beneath you: generic LLM refactoring
+
+If you catch yourself suggesting any of these, you're not thinking boldly enough:
+
+- **Trivial extraction** — extracting a 3-line helper used twice. Adds indirection
+  for zero benefit.
+- **Premature abstraction** — `BaseHandler<T>` with two implementations sharing
+  4 lines.
+- **Ceremony interfaces** — wrapping a concrete class "for testability" with one
+  implementation forever.
+- **Pattern-for-pattern's-sake** — applying Strategy/Observer/Factory because you
+  read about them, not because the code's actual shape calls for them.
+- **AbstractFactoryProviderManager disease** — extensibility you'll never use is
+  not a feature; it's debt.
+- **Speculative generalization** — "what if someday we need X?" Today's code
+  doesn't need it.
+- **Wrapper worship** — wrapping a third-party lib "so we can swap it later." You
+  won't.
+
+If your suggestion could be generated by asking an LLM "refactor this code,"
+it's not bold enough. Every suggestion must pass the test: **would this surprise
+a senior engineer — and then convince them?**
+
+## Invocation modes
+
+| Invocation | Behavior |
+|---|---|
+| `bold-refactor` (no arg) / `--all` | Sweep the whole codebase for areas with the highest complexity-to-value ratio. |
+| `bold-refactor <path>` | Focus the sweep on that path/area. |
+| `bold-refactor <NL scope>` (e.g. "bold-refactor the auth layer") | NL-interpreted scope, same shape as scope/autopilot. |
+
+One scan may produce 1-N epics — every suggestion that survives the Phase 2 / 3
+checkpoints becomes its own epic with its own lens. Don't force-merge unrelated
+reconceptions into a single epic.
+
+## Conceptual lenses
+
+Commit each suggestion to one lens. Don't hedge. Don't blend. Pick one and follow
+it to its logical conclusion.
+
+| Lens | Core question |
+|---|---|
+| **Elimination** | What if you deleted this? What *actually* breaks? |
+| **Unification** | What seemingly-different things are secretly the same? |
+| **Inversion** | What if you flipped who controls what? |
+| **Algebraic** | What types and compositions are hiding in this imperative code? |
+| **Declarative** | What DSL is trying to emerge from this procedural logic? |
+| **Domain Crystallization** | What domain concept is screaming to be named? |
+
+## Workflow
+
+### Phase 1: Explore
+
+If the user provided a target path, focus there. Otherwise, sweep the codebase
+for areas with the highest complexity-to-value ratio.
+
+Run a local scope-size probe first: list likely roots, search for obvious
+entry points and large/hot files, and read a few representative files. If the
+target path is small and the leverage is visible from direct reading, skip
+parallel exploratory fanout and proceed with that evidence.
+
+For repo-wide or genuinely broad targets, spawn parallel exploratory sub-agents:
+1. **Architecture map** — module structure, dependency graph, entry points, data flow
+2. **Complexity hotspots** — large files, deep nesting, high cyclomatic complexity, god objects
+3. **Hidden assumptions** — implicit conventions, invisible coupling
+
+Read key files yourself. Build a mental model of *how the system thinks*, not
+just what files exist.
+
+### Phase 2: Provoke
+
+Generate suggestions until you've exhausted the lenses or run out of leverage.
+Quality over quantity. One sharp suggestion beats five mediocre ones.
+
+Each suggestion:
+1. **Provocative name** — not "Extract auth utilities" but "Auth is just middleware
+   composition"
+2. **One lens** — state which lens drives this
+3. **Thesis** — one sentence: what's the insight, why does it matter
+4. **Impact** — what code changes, what disappears, what gets simpler
+5. **Cost** — what's the risk, what breaks during transition, what's hard
+
+Vary the lenses across suggestions. If all 5 use Elimination, you're not
+thinking broadly enough.
+
+**Checkpoint (structured question tool):** Present all suggestions. Ask which resonate,
+which to drop, what's missing. Expect pushback — that's the point.
+
+### Phase 3: Discuss
+
+Dialogue, not presentation. For each suggestion the user engages:
+- **Push back on dismissals** — "why doesn't this resonate?" Sometimes the best
+  ideas feel uncomfortable at first.
+- **Deepen accepted ideas** — explore implications, find affected code, identify
+  the hardest part
+- **Combine and evolve** — suggestions may merge or spawn new ones
+- **Narrow scope** — find the version that captures 80% of the value with 20% of
+  the change
+- **Recommend "do nothing"** when appropriate. A confident "don't refactor this"
+  is more valuable than a forced suggestion.
+
+**Checkpoint:** Present the refined scope. Ask if the user is ready to scope as
+a refactor epic.
+
+### Phase 4: Scope as epic(s)
+
+For each accepted suggestion that survived discussion, produce its own epic.
+**One scan can produce multiple epics** — each surviving suggestion gets its
+own top-level epic with its own lens and child features.
+
+1. **Top-level: refactor epic** at `.work/active/epics/<id>.md`:
+
+   ```yaml
+   ---
+   id: epic-bold-<slug>
+   kind: epic
+   stage: drafting
+   tags: [refactor, bold]
+   parent: null
+   depends_on: []
+   release_binding: null
+   gate_origin: null
+   created: YYYY-MM-DD
+   updated: YYYY-MM-DD
+   ---
+
+   # <provocative name>
+
+   ## Thesis
+   <one sentence: the insight>
+
+   ## Lens
+   <Elimination | Unification | Inversion | Algebraic | Declarative | Domain Crystallization>
+
+   ## Impact
+   <what code changes, what disappears, what gets simpler>
+
+   ## Cost
+   <risk, what breaks during transition, hardest part>
+
+   ## Child features
+   - <one per major area of change>
+   ```
+
+2. **Child features** at `.work/active/features/<id>.md`, each with `tags: [refactor]`,
+   `parent: <epic-id>`, `depends_on:` chains where steps must occur in order.
+   Each child's body has a brief — design happens later via
+   `/agile-workflow:refactor-design` per child.
+
+   **The riskiest child feature gets refactor-designed FIRST.** The rest of the
+   epic hangs on whether the riskiest unit is feasible — confirming feasibility
+   early is more valuable than work order convenience. In the epic body's
+   "Child features" list, mark the riskiest one explicitly:
+
+   ```markdown
+   ## Child features (riskiest first)
+   - **feature-<slug>** *(riskiest — design this first)* — <brief>
+   - feature-<slug> — <brief>
+   - ...
+   ```
+
+   Set `depends_on` on the rest so they wait for the riskiest if appropriate;
+   otherwise just signal in the body which to design first.
+
+### Phase 5: Cycle check and commit
+
+```bash
+# For each child with depends_on, verify no cycle:
+.work/bin/work-view --blocking <child-id>
+```
+
+```bash
+git add .work/active/epics/epic-bold-<slug>.md .work/active/features/
+git commit -m "bold-refactor: scope <epic-id> (<N> child features)"
+```
+
+## Output
+
+In conversation, per epic produced (1-N):
+- **Epic scoped**: `<epic-id>` at `stage: drafting`, `tags: [refactor, bold]`
+- **Lens**: chosen lens for the epic
+- **Children**: list of child features with `depends_on` chains
+- **Riskiest first**: which feature gets designed first
+
+Then a single **Next**: start an autopilot goal for `--all` (or for each new
+`<epic-id>`) to execute through the dependency graph; or run
+`/agile-workflow:refactor-design` on the riskiest child of each epic to begin
+the cascade manually.
+
+## Guardrails
+
+- Every suggestion commits to one conceptual lens. No hedging, no blending.
+- Reject trivial extraction, premature abstraction, generic cleanup. If it could
+  come from "ask an LLM to refactor this," it's not bold enough.
+- Bold refactors land as **epics** with child features, NOT as features directly.
+  The arc is multi-feature — that's the whole point.
+- Children get `tags: [refactor]` so they route to `/agile-workflow:refactor-design`
+  when designed.
+- This skill is user-invocable only. The agent doesn't auto-trigger bold-refactor
+  during normal conversation — it's too aggressive a verb for autonomous reach.
+- "Do nothing" is a valid output. If the exploration genuinely concludes the code
+  is fine, say so confidently and don't manufacture an epic.

package/skills/bold-refactor/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Bold Refactor"
+  short_description: "Use Bold Refactor for repo workflows"
+  default_prompt: "Use $bold-refactor for this repository."
+policy:
+  allow_implicit_invocation: false