@jamie-tam/forge 6.0.0

package/commands/forge.md

@@ -0,0 +1,100 @@
+---
+name: forge
+description: "Discovery command — show installed forge capabilities, current project state, in-flight work, and the most useful next action. Run this when you're new to a forge-enabled project, or any time you want a one-screen overview."
+---
+
+# /forge — Discovery
+
+Give the user a single-screen orientation to forge in this project. Five sections, in order. Keep each section terse — drill-downs go to skills (`support-system-guide` for routing) or rules (`.claude/rules/common/forge-system.md` for system structure).
+
+## Section 1 — Installed capabilities
+
+Count what's installed under `.claude/` and report one line:
+
+```bash
+echo "Installed: $(ls .claude/skills 2>/dev/null | wc -l | tr -d ' ') skills · $(ls .claude/commands 2>/dev/null | wc -l | tr -d ' ') commands · $(ls .claude/agents 2>/dev/null | wc -l | tr -d ' ') agents · $(find .claude/rules -name '*.md' 2>/dev/null | wc -l | tr -d ' ') rules"
+```
+
+If `.claude/` doesn't exist: say "forge not installed in this project — run `npx @jamie-tam/forge init` from the project root."
+
+## Section 2 — Project profile
+
+Read the `## Project Profile` block from `CLAUDE.md` and present its yaml compactly. Detect two states:
+
+- **Unfilled** — the block still contains `{detected ...}` placeholders → say "Profile not filled — run `/setup`."
+- **Filled** — show the yaml as-is.
+
+## Section 3 — Active work
+
+Glob `.forge/work/*/*/manifest.yaml`. Exclude items whose top-level `status` is `completed`, `abandoned`, or `escalated`. For each remaining item, infer the current phase from the first phase or gate that is not complete/locked/skipped/not-applicable. Print a compact table:
+
+```markdown
+| Type | Name | Phase | Manifest |
+|---|---|---|---|
+| feature | add-payments | quality.test-execution | .forge/work/feature/add-payments/manifest.yaml |
+```
+
+If nothing's in flight: say "No work items in flight."
+
+## Section 4 — Suggested next
+
+Pick **one** suggestion based on the state observed in sections 2 and 3. Use this priority order (first match wins):
+
+| State | Suggested next |
+|---|---|
+| `.claude/` missing | `npx @jamie-tam/forge init` |
+| Profile has `{detected ...}` placeholders | `/setup` |
+| One in-flight item | `/resume {type}/{name}` (cite the matching item) |
+| Multiple in-flight items, all recent | `/status` (then user picks) |
+| Stale in-flight items (manifest `mtime` older than 30 days AND no commit on `{branch}` in 30 days — check via `git log -1 --since='30 days ago' {branch}`) | Surface them: "Item X has been idle since {date} — consider `/abort {type}/{name}` or `/resume`." |
+| Profile filled, no work items, `pocs/` exists | `/greenfield` (resume the prototype-driven flow) |
+| Profile filled, no work items, no `pocs/` | `/feature <name>` or `/greenfield <name>` — ask the user which |
+
+Present the suggestion as one line: **Suggested next:** `<command>` — `<brief rationale>`.
+
+## Section 5 — Commands at a glance
+
+Print this catalog verbatim. The user can scroll back to it without re-running anything.
+
+```
+Workflow commands
+  /feature <name>     full feature lifecycle (discover → plan → build → quality → deliver)
+  /greenfield <name>  new project from zero (prototype-driven by default)
+  /bugfix <name>      systematic debugging + fix
+  /refactor <name>    restructure without new functionality
+  /hotfix <name>      emergency production fix (expedited gates)
+
+State commands
+  /status             list in-flight work
+  /resume <name>      continue an in-flight item
+  /abort <name>       cancel an in-flight item
+
+System commands
+  /setup              detect stack, fill project profile, scaffold .forge/ + aiwiki/
+  /validate           check skill/rule consistency
+  /evolve             improve the forge harness itself
+  /task-force <list>  parallel agents for a punch list of ad-hoc tasks
+```
+
+End with one drill-down line: **For routing a specific intent or unsure which command to use, invoke the `support-system-guide` skill. For system structure (skills, agents, .forge/ layout), see `.claude/rules/common/forge-system.md`.**
+
+## When to use
+
+- User invokes `/forge` explicitly
+- User asks "what's in this project?", "show me forge", or "what can forge do here?"
+- Periodic check-in — useful at the start of a session to see if anything is in flight before starting new work
+
+## Do NOT
+
+- Do NOT invoke this on every session start — `support-system-guide` is the auto-triggering orientation skill. `/forge` is the explicit on-demand version.
+- Do NOT duplicate the long skill/group descriptions inline — drill-downs to `support-system-guide` keep this command compact.
+- Do NOT modify anything. This is a read-only discovery command.
+
+## I/O Contract
+
+| Field | Value |
+|---|---|
+| **Requires** | `.claude/` (skills, commands, agents, rules); `CLAUDE.md` for profile read; `.forge/work/*/*/manifest.yaml` for active work (optional) |
+| **Produces** | Console output only — no files written |
+| **Updates manifest** | None |
+| **Feeds into** | User's choice of next command |

package/commands/greenfield.md

@@ -0,0 +1,185 @@
+---
+name: greenfield
+description: "Start a new project from scratch using the prototype-driven SDLC: concept slides → wireframe → prototype (iterate) → codify → production build. The full pipeline; phases skip only when explicitly justified."
+argument-hint: "[project-name]"
+---
+
+# /greenfield — New Project From Scratch
+
+You are orchestrating a complete new project build using the prototype-driven workflow. This is for projects that do not yet have a codebase. The default flow is the full pipeline: discover → concept → wireframe → prototype (iterate) → codify → production build → deliver. Phases skip only when explicitly justified — for greenfield, all phases are usually active.
+
+## Execution Protocol
+
+**REQUIRED SUB-SKILL**: load and follow the skill — do not substitute judgment. Step summaries describe outcomes; the loaded skill defines the process.
+
+## Input
+
+Ask the user for:
+1. **Project name**
+2. **Project description** (what does it do, who is it for?)
+3. **Tech stack hints** (frontend product, backend service, library, CLI — affects what the prototype's verification frontend looks like)
+4. **Any existing requirements** (docs, mockups, meeting notes, screenshots)
+
+## Step 0: Preflight Checks
+
+1. **Target directory** is clean or empty
+2. **Required tools** available (Node, package manager, git, optionally Docker)
+3. **User has confirmed** the project scope
+
+## Step 0a: Wiki Bootstrap
+
+REQUIRED SUB-SKILL: Use **support-wiki-bootstrap** to ensure aiwiki/ exists.
+
+## Step 1: Manifest + Phase Planning
+
+Check if `.forge/work/greenfield/{project-name}/manifest.yaml` exists.
+
+**If it exists**: Resume from the last incomplete phase. Skip phases marked `locked` or `skipped`. If `status: escalated` or `status: completed`, do NOT resume.
+
+**If it does not exist**: Create `.forge/work/greenfield/{project-name}/` and the manifest from `.claude/templates/manifests/greenfield.yaml`. Fill placeholders.
+
+**Phase planning** (the v6 flexibility step). Propose `active` / `skip` for each phase based on the project type:
+
+| Project type | Concept | Wireframe | Prototype | Codify | Production |
+|---|---|---|---|---|---|
+| Frontend product (web/mobile UI) | active | active | active | active | active |
+| Backend service / API | active | active (verification UI) | active (frontend = verification surface) | active | active |
+| Library / SDK | active | active (doc site sketch) | active (consumer-test app) | active | active |
+| CLI tool | active | active (terminal-frame mock) | active (working CLI) | active | active |
+
+For greenfield, every phase is typically active. Surface the proposed plan to the user; user can override (e.g. "skip wireframe — I have detailed mockups already" → mark wireframe as `skipped` with reason).
+
+## Step 2: Discover — Requirements (optional)
+
+If the user provided detailed requirements upfront, this step extracts and structures them. If they're starting from a brief paragraph, this step is folded into Step 3 concept slides.
+
+REQUIRED SUB-SKILL: Use **discover-requirements** (only if user has substantive existing requirements docs).
+
+## Step 3: Concept (Phase 2)
+
+REQUIRED SUB-SKILL: Use **concept-slides**.
+
+Produces a low-fidelity marp deck at `decks/{project-name}/slides.md` with hook, 3-5 sub-concepts with sketches, user journey, and out-of-scope. 8-15 slides for full products. The user iterates 1-3 cycles.
+
+### GATE: Concept Locked
+
+User reviews the rendered deck (HTML), gives feedback, locks when satisfied. Update manifest: `artifacts.concept.{deck_path, locked_at}`.
+
+## Step 4: Wireframe (Phase 3)
+
+REQUIRED SUB-SKILL: Use **build-wireframe**.
+
+Produces `pocs/{project-name}-wireframe/index.html` — single-HTML annotated wireframe with click-through demos and gutter callouts. Backend-heavy products still get a wireframe; the frontend is the verification surface during development.
+
+### GATE: Wireframe Locked
+
+User clicks through the rendered HTML, gives feedback, locks when satisfied. Update manifest: `artifacts.wireframe.{html_path, locked_at}`.
+
+## Step 4.5: Design System
+
+REQUIRED SUB-SKILL: Use **plan-design-system** to lock design tokens before architecture.
+
+Backend-only / CLI projects without a frontend skip this step entirely (no design tokens needed). For all other projects, the design tokens captured here feed scaffold, every frontend task spec, and the UI/UX review. The skill self-skips when `DESIGN.md` already exists and is current for this work item.
+
+### GATE: Design Tokens Approved
+
+User approves the design tokens written to `DESIGN.md`. Update manifest: `artifacts.design-system.{path, approved_at}`.
+
+## Step 5: Prototype (Phase 4)
+
+REQUIRED SUB-SKILL: Use **build-prototype** for initial scaffold, then **iterate-prototype** for the polish loop.
+
+Scaffolds `pocs/{project-name}-prototype/` — Vite + React + TS + Tailwind v4 + Zustand v5 + lucide-react + Biome. Multi-instance prototype-builder for multi-track wireframes. User runs `npm run dev`, gives feedback in `pocs/{project-name}-prototype/.forge/feedback.md`.
+
+During iteration: gotchas + conventions get captured to `aiwiki/gotchas/` and `aiwiki/conventions/` (Phase 5 inputs). Wiki-lint validates each write.
+
+### GATE: Prototype Locked
+
+User emits "satisfied" or "LOCKED" after click-through verification. Update manifest: `artifacts.prototype.{path, locked_at}`.
+
+Optional: `/autopilot prototype` for hands-off polish loop *(planned, not yet implemented — see docs/V6-PLAN.md §11; manual `[iterate-prototype]` runs are the only mode today)*.
+
+## Step 6: Codify (Phase 5)
+
+REQUIRED SUB-SKILL: Use **harden**.
+
+Codifies the locked prototype into production-ready plans:
+- `aiwiki/architecture/{topic}.md` — one or more focused architecture files
+- `aiwiki/decisions/{nnnn}-{slug}.md` — ADRs (adversarial review via `/second-opinion` is *planned, not yet implemented* — until that ships, surface objections inline in the ADR `review:` block during harden Step 2)
+- `aiwiki/conventions/` — production-surface conventions
+- `aiwiki/gotchas/` — Phase 4 gotchas with production addenda
+- Slice graph + `tasks.md` in manifest
+- `aiwiki/sessions/` entry indexing everything produced
+
+Triggers a focused dream after writes; user reviews dream output in `aiwiki/proposed/` before phase closes.
+
+### GATE: Codified Plan Approved
+
+User reviews ALL outputs as a unit (architecture + ADRs + slice graph + dream proposal). Approves before Phase 6 starts. Update manifest: `artifacts.codify.locked_at` (no path — the populated slice_graph + aiwiki/architecture/ files ARE the codify artifacts).
+
+## Step 7: Production Build (Phase 6)
+
+Execute the slice graph from Phase 5. Per slice, in dependency order:
+
+1. REQUIRED SUB-SKILL: Use **build-tdd** — strict RED-GREEN-REFACTOR
+2. REQUIRED SUB-SKILL: Use **quality-code-review**
+3. Fix any Critical or Important findings
+4. Per-slice user-confirm
+
+Per-slice dream fires after slice close — consolidates gotchas and slice-scoped wiki updates.
+
+Optional: `/autopilot production` runs slices via Ralph loop until all gates green *(planned, not yet implemented — see docs/V6-PLAN.md §11; per-slice manual dispatch is the only mode today)*.
+
+### GATE: All Slices Complete
+
+All slices have `gate-passed: true` for build-tdd, code-review, runtime-reach. Update manifest: `artifacts.production-build.locked_at` (slice terminal state + production code ARE the production-build artifacts).
+
+## Step 8: Test Plan + Execution
+
+REQUIRED SUB-SKILL: Use **quality-test-plan**, then **quality-test-execution**.
+
+### GATE: Test Results
+
+ALL tests pass. Coverage meets thresholds (minimum 80%, 100% for critical paths).
+
+## Step 8.5: UI/UX Review (if applicable)
+
+If the project has a frontend (per Phase 1 phase planning):
+
+REQUIRED SUB-SKILL: Use **quality-uiux**.
+Validates production implementation matches the locked wireframe + design tokens.
+
+## Step 9: Final Code Review
+
+REQUIRED SUB-SKILL: Use **quality-code-review** for a final pass across all production code (full diff). Fix any Critical or Important findings before deployment.
+
+## Step 10: Deliver (Phase 7)
+
+REQUIRED SUB-SKILL: Use **build-pr-workflow**.
+Optionally: **deliver-deploy** (if deploying), **deliver-onboarding** (always for greenfield).
+
+## Step 11: Support — Record Lessons
+
+REQUIRED SUB-SKILL: Use **support-gotcha**.
+Final dream cycle consolidates all Phase 4-7 captures into the curated wiki state.
+
+Update manifest: `status: completed`.
+
+## Phase Skip Handling
+
+When the user opts to skip a phase during Step 1 phase planning, set the phase_plan entry to `skipped` (object form to capture the reason):
+
+```yaml
+phase_plan:
+  wireframe:
+    status: skipped
+    reason: "User has detailed Figma mockups; converting directly to prototype"
+```
+
+Skipped phases do not run gates. The downstream phase reads from whatever artifact the skipped phase would have produced (e.g. user-provided mockups instead of a wireframe).
+
+If a skipped phase reveals a gap during a later phase, surface the gap to the user and decide together whether to re-open the skipped phase (changing `phase_plan.{phase}` from `skipped` back to `active`) or carry deltas explicitly in the next phase's outputs. The flow does not auto-rewind.
+
+## Gate Checking Logic
+
+Resume rule: skip phases where `artifacts.{phase}.locked_at` is present (already locked) or `phase_plan.{phase}` is `skipped`. Halt and fix any phase whose gate hasn't passed before continuing.

package/commands/hotfix.md

@@ -0,0 +1,98 @@
+---
+name: hotfix
+description: "Emergency production fix. Compressed workflow that gets the fix out fast, then follows up properly."
+argument-hint: "[what is broken]"
+---
+
+# /hotfix — Emergency Production Fix
+
+You are handling a production emergency. Speed matters, but correctness matters more. Get the fix out, then follow up properly.
+
+**Skipped steps**: brainstorm, architecture, full test plan — deferred to follow-up ticket.
+
+## Execution Protocol
+
+**REQUIRED SUB-SKILL**: load and follow the skill — even in an emergency, do not substitute judgment.
+Step summaries describe outcomes; the loaded skill defines the process.
+
+## Input
+
+Ask the user for:
+1. **What is broken** — impact, error messages, affected systems
+2. **Severity** — system down? Data loss? Degraded? Cosmetic?
+3. **When it started** — correlate with recent deploys
+4. **Rollback option** — can we rollback as immediate mitigation?
+
+## Step 0: Triage
+
+Before writing any code:
+1. **Assess rollback** — if correlated with recent deploy, recommend rollback while investigating
+2. **Assess blast radius** — users affected, degradability
+3. **Communicate** — recommend notifying stakeholders
+
+## Step 0.5: Create or Resume Manifest
+
+Derive a name slug from the problem description (e.g., `payment-500-errors`).
+
+Check if `.forge/work/hotfix/{name}/manifest.yaml` exists.
+
+**If it exists**: Read the manifest. Resume from the last incomplete phase. If `status: completed` or `status: escalated`, do NOT resume.
+
+**If it does not exist**: Create the work directory (`.forge/work/hotfix/{name}/`) and manifest using the template at `.claude/templates/manifests/hotfix.yaml`. Fill placeholders `{name}`, `{description}`, `{date}`.
+
+## Step 1: Debug — Compressed Root Cause Analysis
+
+REQUIRED SUB-SKILL: Use **support-debug** in compressed mode.
+Focus on immediate fix. If root cause not identifiable quickly, recommend **rollback**.
+
+## Step 2: Build — Minimal Fix with Test
+
+REQUIRED SUB-SKILL: Use **build-tdd** (minimal scope).
+Reproduce with a test, write the smallest fix, verify. Do not refactor.
+
+## Step 3: Quality — Smoke Tests Only
+
+REQUIRED SUB-SKILL: Use **quality-test-execution** (smoke tests ONLY).
+Bar: existing tests pass + regression test + smoke tests. Full suite deferred to follow-up.
+
+## Step 4: Quality — Quick Code Review
+
+REQUIRED SUB-SKILL: Use **quality-code-review** (critical-pass only).
+Catches injection, secrets, auth bypass. Full review deferred to follow-up.
+
+## Step 5: Deliver — Deploy
+
+REQUIRED SUB-SKILL: Use **deliver-deploy**.
+
+## Step 6: Follow-Up (Critical)
+
+### 6a: Record Gotcha
+REQUIRED SUB-SKILL: Use **support-gotcha**.
+
+Tag the gotcha with `severity: hotfix-workaround`. This tag is surfaced at session start by the forge session hook — it will remind you (or your teammates) about unresolved workarounds until a follow-up resolves them.
+
+### 6b: Record Follow-Up
+Document what needs to happen next. This is NOT optional — the hotfix cannot be marked complete without it.
+
+```
+Follow-up label: {short description, e.g., "payment-null-check-proper-fix"}
+What was deferred: root cause deep dive, comprehensive test coverage, monitoring improvements, architectural review (if band-aid fix)
+Resolved: false
+```
+
+Store in the gotcha file alongside the `hotfix-workaround` tag. When the follow-up is completed (via `/bugfix` or `/feature`):
+- Update `resolved: true` in the gotcha file to clear the session start warning.
+- Set `successor_path: work/{type}/{follow-up-name}` on the hotfix manifest.
+- Leave `status: completed` on the hotfix manifest (not `escalated` — the hotfix deploy itself was complete).
+
+## Explicit Gate Exemptions
+
+| Standard Gate | Hotfix Scope |
+|---|---|
+| Full brainstorm | Skipped |
+| Full architecture | Skipped |
+| Full test plan | Smoke + regression only |
+| Full code review | Critical pass only |
+| Zero test failures (all types) | Existing + smoke pass |
+
+Every skipped gate MUST be addressed in the follow-up ticket (Step 6b).

package/commands/refactor.md

@@ -0,0 +1,147 @@
+---
+name: refactor
+description: "Refactor existing code to improve quality, maintainability, or performance. Ensures no behavior changes via comprehensive testing."
+argument-hint: "[what to refactor]"
+---
+
+# /refactor — Disciplined Refactoring Workflow
+
+You are refactoring existing code. The cardinal rule: **behavior must not change**. Tests are your proof that behavior is preserved. If the scope grows to include new behavior, escalate to `/feature`.
+
+## Execution Protocol
+
+**REQUIRED SUB-SKILL**: load and follow the skill — do not substitute judgment.
+Step summaries describe outcomes; the loaded skill defines the process.
+
+## Input
+
+Ask the user for:
+1. **What to refactor** — which code, module, or pattern
+2. **Why** — tech debt, performance, readability, testability
+3. **Constraints** — areas that must NOT be touched, deadlines
+
+## Step 0: Repo-State Detection & Routing Redirect
+
+Before any other check, detect whether this repo is in **prototype mode** or **production mode** per `rules/common/skill-selection.md` Step 1. Signals (any one is sufficient): path under `pocs/` or `*-prototype/`; `package.json` `"private": true` with no CI; missing `aiwiki/architecture/`; manifest shows prototype-phase active.
+
+**If prototype mode is detected**, stop and offer the redirect:
+
+```
+This looks like prototype iteration, not refactoring of production code (signals: <list matched signals>).
+
+/refactor enforces no-behavior-change with coverage baseline + comprehensive tests as the safety net — appropriate for production code that has those tests, overkill for prototype work where mocks ARE the verification surface.
+
+Redirect to iterate-prototype? [Y]es / [n]o continue with /refactor anyway / [a]bort
+```
+
+User responses:
+- **Y / yes**: invoke `iterate-prototype` with the refactor description as input. Skip the rest of /refactor.
+- **n / no**: proceed to Step 0a. User confirms there IS production-grade test coverage to refactor against.
+- **a / abort**: stop.
+
+If production mode, proceed to Step 0a directly.
+
+## Step 0a: Preflight Checks
+
+1. **Git is clean** — no uncommitted changes
+2. **ALL tests pass** — the test suite is your safety net
+3. **Test coverage baseline** — record current coverage; refactoring must not reduce it
+4. **Branch** — `refactor/{description-slug}`
+
+## Step 0b: Wiki Bootstrap
+
+REQUIRED SUB-SKILL: Use **support-wiki-bootstrap** to ensure aiwiki/ exists.
+
+Refactor decisions and any newly-discovered conventions write to `aiwiki/`.
+
+Check if `.forge/work/refactor/{name}/manifest.yaml` exists.
+
+**If it exists**: Read the manifest. Resume from the last incomplete phase. Report what has already been completed and what remains. If `status: escalated` or `status: completed`, do NOT resume.
+
+**If it does not exist**: Create the work directory (`.forge/work/refactor/{name}/`) and manifest using the template at `.claude/templates/manifests/refactor.yaml`. Fill placeholders `{name}`, `{description}`, `{date}`. Record coverage baseline in `coverage-baseline`.
+
+If this refactor was escalated from a bugfix, set `escalated_from: work/bugfix/{predecessor-name}`.
+
+## Step 1: Discover — Codebase Analysis
+
+REQUIRED SUB-SKILL: Use **discover-codebase-analysis**.
+
+### GATE: Codebase Analysis
+Present the analysis to the user. User must approve before planning begins. Update manifest: `discover.codebase-analysis.status: complete, gate-passed: true`.
+
+## Step 2: Plan — Brainstorm Refactoring Approach
+
+REQUIRED SUB-SKILL: Use **plan-brainstorm** (scoped to refactoring).
+
+### GATE: Brainstorm Approval
+User must explicitly approve the refactoring approach. Update manifest: `plan.brainstorm.status: complete, gate-passed: true`.
+
+## Step 3: Plan — Task Decomposition
+
+REQUIRED SUB-SKILL: Use **plan-task-decompose**.
+
+### GATE: Task Plan Review
+User approves the task breakdown. Update manifest: `plan.task-decompose.status: complete, gate-passed: true`.
+
+## Step 4: Build — Implement Refactoring (Phase Loop)
+
+Execute tasks phase by phase from the task plan. Phases run sequentially. Tasks within a phase run in parallel when `execution.mode` is `subagent`.
+
+For each phase, run full test suite first to confirm baseline passes, then for each task:
+
+1. REQUIRED SUB-SKILL: Use **build-tdd** — write characterization tests first if missing, then refactor, then verify. For subagent execution mode, run with `isolation: "worktree"` so phase tasks parallelize cleanly.
+2. REQUIRED SUB-SKILL: Use **quality-code-review** — fix any Critical or Important findings before the task closes.
+3. Commit: `refactor: {what was improved}` (inline mode) or merge the worktree (`git merge --no-ff`) into the refactor branch (subagent mode).
+
+After every phase completes, re-run the full test suite on the merged result before moving to the next phase.
+
+**If ANY test breaks and you cannot immediately see why, REVERT.** Do not fix the test to match new behavior — that means you changed behavior.
+
+### GATE: Implementation Complete
+All phases complete. All per-task code reviews passed. All tests pass on merged result. Coverage equals or exceeds baseline.
+Update manifest: mark all tasks in `build.tasks` as complete.
+
+## Step 5: Quality — Test Execution
+
+REQUIRED SUB-SKILL: Use **quality-test-execution**.
+Coverage must be equal or higher than baseline.
+
+### GATE: Test Results
+All tests pass. Coverage equals or exceeds baseline recorded in Step 0. Fix failures before proceeding.
+Update manifest: `quality.test-execution.status: complete, gate-passed: true`.
+
+## Step 5.5: Quality — Refactoring Assessment
+
+Produce a before/after summary of what the refactoring improved.
+
+**Quantitative** (from `git diff --stat`):
+- Files changed, lines added/removed
+- Functions/methods before vs after
+
+**Qualitative** — assess which of these improved, stayed the same, or got worse (tradeoffs):
+- Readability, simplicity, consistency
+- Maintainability, testability, debuggability
+- Predictability, correctness
+
+Present the assessment to the user. This feeds into the PR description.
+Update manifest: `quality.assessment.status: complete, gate-passed: true`.
+
+### GATE: Refactoring Assessment
+User has reviewed the before/after assessment. Assessment feeds into the PR description.
+
+## Step 6: Deliver — Create PR
+
+REQUIRED SUB-SKILL: Use **build-pr-workflow**.
+Keep the PR focused — refactoring only, no feature work mixed in.
+
+## Step 7: Support — Record Lessons
+
+REQUIRED SUB-SKILL: Use **support-gotcha**.
+
+## Gate Exemptions
+
+| Standard Gate | Refactor Equivalent | Rationale |
+|---|---|---|
+| quality-test-plan | Skipped | Refactoring preserves behavior — the existing test suite IS the test plan. Characterization tests are added in Step 4 via build-tdd when coverage gaps exist. |
+| requirements → brainstorm | Compressed (discover → brainstorm) | No new requirements — scope is existing code quality. |
+| architecture phase | Skipped | Refactoring operates within existing architecture. If architecture changes are needed, escalate to `/feature`. |

package/commands/resume.md

@@ -0,0 +1,25 @@
+---
+name: resume
+description: "Resume a paused .forge/work item from its current phase."
+argument-hint: "[type/name]"
+---
+
+# /resume — Resume Work Item
+
+Resume a paused work item without restarting completed phases.
+
+## Scope
+
+Resumes an existing in-flight work item by reading its manifest and re-entering its owning command (`/feature`, `/greenfield`, `/bugfix`, `/hotfix`, `/refactor`) at the first unfinished phase. Does NOT create new work items, modify gate state, re-run already-passed gates, or abort/escalate work. Invoke after a session break, after a manifest update, or whenever the user wants to continue paused work.
+
+## Input
+
+Accept `type/name` when provided, such as `feature/add-payments`. If omitted, run `/status` first and ask the user which in-flight item to resume.
+
+## Steps
+
+1. Read `.forge/work/{type}/{name}/manifest.yaml`.
+2. If `status` is `completed`, `abandoned`, or `escalated`, do not resume. Surface the status and any `successor_path`.
+3. Identify the last completed phase and the first incomplete phase using the same gate-skip rules as the owning command.
+4. Invoke the owning command (`/feature`, `/greenfield`, `/bugfix`, `/hotfix`, or `/refactor`) with the work item name and instruct it to resume from the manifest.
+5. Do not recreate manifests, delete files, or rerun phases whose gates already passed.