@jamie-tam/forge 6.0.0 → 6.2.0

package/README.md

@@ -2,9 +2,11 @@
 
 **A production-grade `.claude` harness for prototype-driven AI development**
 
-<!-- Badges -->
-<!-- [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) -->
-<!-- [![Claude Code](https://img.shields.io/badge/Claude%20Code-compatible-blue.svg)](#) -->
+Source: [github.com/lps-ai/forge](https://github.com/lps-ai/forge) · Changelog: [CHANGELOG.md](CHANGELOG.md) · License: [MIT](LICENSE)
+
+---
+
+> ⚠️ **Experimental — early access.** This npm package is still experimental and needs a lot of adjustment. It was published to npm for convenience (so `npx @jamie-tam/forge init` works), but forge is **not feature-complete and not well-tested yet**. Expect breaking changes between versions, rough edges, half-finished commands, and gaps that dogfooding hasn't surfaced. Names, command surfaces, manifest schemas, and skill boundaries are all still in motion. If you try it: pin a version, expect to update often, and please file issues at [github.com/lps-ai/forge/issues](https://github.com/lps-ai/forge/issues) — every real-world signal helps stabilize the next release.
 
 ---
 
@@ -25,10 +27,10 @@ The v6 schema (`templates/manifests/v6/SCHEMA.md`) adds `phase_plan:` at the top
 
 ## Key Features
 
-- **30 skills** spanning the prototype-driven pipeline plus production-grade quality gates
-- **13 commands** for discovery, setup, workflows, evolution, and validation
-- **17 specialized agents** with explicit phase-context (prototype-builder for Phase 4, builder for Phase 6, plus architects, reviewers, hunters, dreamers)
-- **8 common rules** tiered by phase (always-on safety floor + phase-conditional from codify onward) + **7 common references** for skill authoring, agent coordination, and workflow protocol
+- **31 skills** spanning the prototype-driven pipeline plus production-grade quality gates
+- **15 commands** for discovery, setup, workflows, knowledge capture, evolution, and validation
+- **17 specialized agents** with explicit phase-context (prototype-builder for Phase 3-4, builder for Phase 6, plus architects, reviewers, hunters, dreamers)
+- **8 common rules** auto-loaded every session (one — `testing.md` — is paths-conditional, loading only on test files and source code) + **8 common references** for skill authoring, agent coordination, and workflow protocol
 - **Work manifests** with `phase_plan` (preflight intent), `phases` (gate state), `slice_graph` (build decomposition), and `artifacts` (phase outputs + lock signals)
 - **`aiwiki/` typed pages** with LINT on every write + async dream consolidation
 - **Quality gates** at the prototype-to-production transition where they catch real bugs, not premature plan-phase gates
@@ -43,9 +45,9 @@ npx @jamie-tam/forge init
 ```
 
 This installs everything into your project's `.claude/` directory:
-- **Rules** — phase-tiered (always-on safety floor + phase-conditional standards from codify onward)
-- **Skills** — 30 atomic skills covering the prototype-driven pipeline + production gates
-- **Commands** — 8 slash commands for setup, workflows, evolution, and validation
+- **Rules** — 8 common rules auto-loaded every session (one is paths-conditional) + language-specific rules layered per detected stack
+- **Skills** — 31 atomic skills covering the prototype-driven pipeline + production gates
+- **Commands** — 15 slash commands for discovery, setup, workflows, knowledge capture, evolution, and validation
 - **Agents** — 17 specialized subagents with MCP server access (context7, playwright)
 - **Hooks** — gate-enforcer, wiki-lint, telemetry, state preservation, session checkpoints
 - **CLAUDE.md** — project configuration template
@@ -145,41 +147,48 @@ Forge detects these tools automatically and offers integration when available. W
 ## Architecture
 
 ```
-Commands (workflows)          Skills (prefix-grouped)              Rules (phase-tiered)
----------------------         -----------------------              --------------------
-/forge   (discovery)          concept-slides     [Phase 1]         Always-on (safety floor):
-/setup                        build-wireframe    [Phase 2]           common/security
-/feature                      build-prototype    [Phase 3]           common/guardrails
-/greenfield                   iterate-prototype  [Phase 4]           common/verification
-/bugfix                       harden             [Phase 5]           common/skill-selection
-/refactor                     build-scaffold                       Phase-conditional (from codify):
-/hotfix                       build-tdd          [Phase 6]            common/testing
-/evolve                       build-pr-workflow                       common/quality-gates
-/validate                     quality-code-review                     common/git-workflow
-                              quality-test-plan
-Work Manifests (v6)           quality-test-execution               References (load on demand)
--------------------           quality-security-audit               ----------------------------
-.forge/work/                  quality-uiux                         common/
-  {type}/                     deliver-deploy     [Phase 7]           agent-coordination
-    {name}/                   deliver-db-migration                   io-protocol
-      manifest.yaml           deliver-onboarding                     skill-authoring
-        schema_version: "6"   discover-requirements                  skill-compliance
-        phase_plan: {…}       discover-codebase-analysis             phases (canonical vocab)
-        phases: {…}           plan-brainstorm                        coding-standards
-        slice_graph: {…}      plan-architecture                    typescript/  python/  react/
-        artifacts: {…}        plan-design-system                     [extensible]
-                              plan-task-decompose
-aiwiki/ (knowledge layer)     support-system-guide                 Protocols (read on demand)
--------------------------     support-debug                        --------------------------
-  decisions/                  support-gotcha                       protocols/codex.md
-  gotchas/                    support-wiki-lint                    protocols/graphify.md
-  conventions/                support-runtime-reachability
-  architecture/               support-dream                        Hooks
-  sessions/                   support-skill-validator              ------
-  raw/                                                             gate-enforcer
-  proposed/  (dream queue)                                         wiki-lint
-  schemas/                                                         session-start / pre-compact
-  CLAUDE.md  (usage rules)                                         telemetry
+Commands (workflows)          Skills (prefix-grouped)              Rules (auto-loaded)
+---------------------         -----------------------              -------------------
+/discover   (discovery)       concept-slides     [Phase 1]         common/forge-system
+/setup                        build-wireframe    [Phase 2]         common/security
+/feature                      build-prototype    [Phase 3]         common/guardrails
+/greenfield                   iterate-prototype  [Phase 4]         common/verification
+/bugfix                       harden             [Phase 5]         common/skill-selection
+/refactor                     build-scaffold                       common/quality-gates
+/hotfix                       build-tdd          [Phase 6]         common/git-workflow
+/note       (capture)         build-pr-workflow                    common/testing (paths-conditional)
+/dream      (capture)         quality-code-review
+/wrap       (capture)         quality-test-plan
+/parallel   (parallel)        quality-test-execution               References (load on demand)
+/status                       quality-security-audit               ----------------------------
+/resume                       quality-uiux                         common/
+/forge-evolve                 deliver-deploy     [Phase 7]             agent-coordination
+/validate                     deliver-db-migration                     io-protocol
+                              deliver-onboarding                       skill-authoring
+Work Manifests (v6)           discover-requirements                    skill-compliance
+-------------------           discover-codebase-analysis               phases (canonical vocab)
+.forge/work/                  plan-brainstorm                          coding-standards
+  {type}/                     plan-architecture                        quality-gates
+    {name}/                   plan-design-system                       feature-tracking
+      manifest.yaml           plan-task-decompose                    typescript/  python/  react/
+        schema_version: "6"   support-system-guide                     [extensible]
+        phase_plan: {…}       support-debug
+        phases: {…}           support-gotcha                         Protocols (read on demand)
+        slice_graph: {…}      support-wiki-lint                      --------------------------
+        artifacts: {…}        support-wiki-bootstrap                   protocols/codex.md
+                              support-dream                            protocols/graphify.md
+aiwiki/ (knowledge layer)     support-parallel
+-------------------------     support-runtime-reachability           Hooks
+  decisions/                  support-skill-validator                ------
+  gotchas/                                                             gate-enforcer
+  conventions/                                                         wiki-lint
+  architecture/                                                        session-start / pre-compact
+  sessions/  (per-session)                                             telemetry
+  raw/  (free-form notes)
+  oracles/ (prototype contracts)
+  proposed/  (dream queue)
+  schemas/
+  CLAUDE.md  (usage rules)
 ```
 
 ---
@@ -188,15 +197,21 @@ aiwiki/ (knowledge layer)     support-system-guide                 Protocols (re
 
 | Command | Description | When to Use |
 |---------|-------------|-------------|
-| `/forge` | One-screen orientation -- installed capabilities, active work, suggested next | Run this first if you're new, or any time you want an overview |
+| `/discover` | One-screen orientation -- installed capabilities, active work, suggested next | Run this first if you're new, or any time you want an overview |
 | `/setup` | Detect project stack, install matching language rules, and fill the project profile | Right after `npx @jamie-tam/forge init` |
-| `/feature` | Full feature workflow with quality gates at every transition | Adding a feature to an existing codebase |
+| `/feature` | Full feature workflow with quality gates at the codify-to-production transition (Phase 5+) | Adding a feature to an existing codebase |
 | `/greenfield` | New project from zero -- includes scaffolding and onboarding docs | Starting a brand-new project |
 | `/bugfix` | Systematic debug, TDD fix, code review, and PR | Something is broken and needs fixing |
 | `/refactor` | Analyze, plan approach, restructure with tests, PR | Code needs cleanup without new functionality |
 | `/hotfix` | Emergency compressed flow -- debug, minimal test, deploy | Production is down, need a fix now |
-| `/evolve` | Review gotchas, improve skills, validate changes | Improving the system itself after a project cycle |
-| `/validate` | Run 5 consistency checks across all skills, rules, and commands | After customizing skills or running `/evolve` |
+| `/note` | Append an ad-hoc research note or brainstorm to `aiwiki/raw/{date}.md` | Phase 1-2 research, half-formed thoughts, anything that doesn't yet fit a typed page |
+| `/dream` | Manually trigger aiwiki consolidation (merge duplicates, promote raw → typed, prune stale) | After a refactor, branch merge, or whenever `aiwiki/` feels noisy. Auto-fires at phase-close + PreCompact too. |
+| `/wrap` | Capture & finalize the current Claude session — fills `aiwiki/sessions/{date}-{id}.md` with Files touched / Decisions / Gotchas / Open questions / Next steps | At the natural end of a working session, before a long break, or before switching focus mid-day. Next session-start hook reads it. |
+| `/parallel` | Dispatch parallel agents for a punch list of ad-hoc tasks; phase-aware sizing | Multiple independent small tasks to crunch in one pass |
+| `/status` | List in-flight `.forge/work` items and their current phase | Check what's open before starting new work |
+| `/resume` | Continue a paused work item from its current phase | Pick up a `.forge/work` item left mid-flow |
+| `/forge-evolve` | Review gotchas, improve skills, validate changes | Improving the system itself after a project cycle |
+| `/validate` | Run 5 consistency checks across all skills, rules, and commands | After customizing skills or running `/forge-evolve` |
 
 ---
 
@@ -210,7 +225,7 @@ aiwiki/ (knowledge layer)     support-system-guide                 Protocols (re
 | `build-wireframe` | 2 | Single-HTML annotated wireframe with click-through demo and callouts; backend-heavy products get a verification-UI sketch |
 | `build-prototype` | 3 | Vite + React + TS + Tailwind v4 + Zustand v5 scaffold with parallel partition builders |
 | `iterate-prototype` | 4 | Polish loop with feedback file + 5-cycle drift checks; captures gotchas + conventions as side effects |
-| `harden` | 5 | Codifies the locked prototype into architecture files + ADRs (with `/second-opinion` review) + slice graph + tasks |
+| `harden` | 5 | Codifies the locked prototype into architecture files + ADRs (adversarial objections surfaced inline in each ADR `review:` block) + slice graph + tasks |
 
 ### Discover & Plan (fallback for non-prototype work)
 
@@ -257,7 +272,9 @@ aiwiki/ (knowledge layer)     support-system-guide                 Protocols (re
 | `support-debug` | Systematic 4-phase debugging with 3-fix threshold and fact-checking |
 | `support-gotcha` | Self-learning from mistakes — captures lessons to `aiwiki/gotchas/`, auto-promotes after N=3 occurrences |
 | `support-wiki-lint` | Validates `aiwiki/` page schemas + citations on every write (hook-driven); backfills `@<sha7>` citation hashes |
+| `support-wiki-bootstrap` | Scaffold `aiwiki/` (typed-page subdirs, schemas, CLAUDE.md, INDEX) once before workflows write to it |
 | `support-dream` | Async wiki consolidation (merge/promote/prune) at phase-close / pre-compact / manual. Writes to `aiwiki/proposed/` for user review |
+| `support-parallel` | Run parallel agents for a user-supplied punch list; phase-aware crew sizing, command-routing for command-shaped items |
 | `support-runtime-reachability` | Detects orphaned exports (code with no production caller) — the gate that catches "tests pass but feature isn't wired up" |
 | `support-skill-validator` | Validate skill consistency: conflicts, I/O gaps, overlaps, gate coverage, drift |
 
@@ -270,31 +287,32 @@ A standard-size `/feature "add auth"` on an existing prototype-driven codebase f
 ```
 User: /feature "add auth"
   |
-  +-- Step 0: Repo-state detection
+  +-- Preflight 0: Repo-state detection
   |     Prototype mode? → offer redirect to iterate-prototype
   |     Production mode? → proceed
-  +-- Step 0a: Preflight checks (git clean, tests pass)
-  +-- Step 0b: aiwiki/ scaffold if missing
-  +-- Step 1: phase_plan — preflight planner proposes per-phase
+  +-- Preflight 1: Preflight checks (git clean, tests pass)
+  +-- Preflight 2: aiwiki/ scaffold if missing
+  +-- Preflight 3: phase_plan — preflight planner proposes per-phase
   |     active / active-light / skipped status; user confirms
   +-- Create/resume manifest (.forge/work/feature/add-auth/manifest.yaml)
   |
-  +-- Phase 2: [concept-slides] (if active)
+  +-- Phase 1: [concept-slides] (if active)
   |     Low-fidelity deck — what is this feature, where it sits
   |   === GATE: concept locked → artifacts.concept.locked_at ===
   |
-  +-- Phase 3: [build-wireframe] (if active)
+  +-- Phase 2: [build-wireframe] (if active)
   |     Single-HTML mini-wireframe for the feature's screens
   |   === GATE: wireframe locked → artifacts.wireframe.locked_at ===
   |
-  +-- Phase 4: [build-prototype] + [iterate-prototype] (if active)
+  +-- Phase 3-4: [build-prototype] + [iterate-prototype] (if active)
   |     Working prototype skin into existing app; iterate to satisfaction
   |     Side effects: capture gotchas + conventions to aiwiki/
   |   === GATE: prototype locked → artifacts.prototype.locked_at ===
   |
   +-- Phase 5: [harden] (if active)
-  |     Codify prototype → aiwiki/architecture/, ADRs (with /second-opinion),
-  |     slice graph in manifest. Dream consolidates phase 4 captures.
+  |     Codify prototype → aiwiki/architecture/, ADRs (adversarial objections
+  |     in each ADR `review:` block), slice graph in manifest.
+  |     Dream consolidates phase 3-4 captures.
   |   === GATE: codify locked + user approves dream proposal ===
   |
   +-- Phase 6: [build-pr-workflow] worktree → per-slice:

package/agents/dreamer.md

@@ -61,11 +61,14 @@ Apply operations in this order:
 3. **Prune stale** — for each entry whose cited code no longer exists OR whose decision is superseded:
    - Mark for deletion in the manifest's `operations` (`op: prune`)
    - Do NOT write a "tombstone" file; absence in proposed/ means delete on accept
-4. **Refresh session file (PreCompact only)** — for `aiwiki/sessions/{current}.md`:
-   - Read the existing file (the hook-maintained event log)
-   - Consolidate the event log into the schema sections (Files touched, Decisions made, Gotchas surfaced, Open questions, Next steps)
-   - Write the refined version to `aiwiki/proposed/{dream_id}/sessions/{current}.md`
-   - DO NOT recreate the file — it must exist (hook created it). If missing, FAIL with `SESSION_FILE_MISSING`.
+4. **Refine the active session file (PreCompact and phase-close triggers)** — locate `aiwiki/sessions/{date}-{session_id_short}.md`:
+   - **The file is expected to be present.** `hooks/scripts/pre-compact.sh` creates it lazily on first PreCompact fire; `/wrap`, `/dream`, and `harden` also create it lazily if absent. By the time you run, one of those has fired during this session — so the file exists.
+   - **If it is truly missing** (no in-session writer fired before you, no `aiwiki/sessions/{today}-*.md` matches), this is a non-fatal anomaly: log it in the dream manifest's `lint_warnings` as `session_file_missing: true` and proceed with raw + typed page consolidation only. Do NOT fabricate a session file — let the next writer (pre-compact, /wrap, harden) create it cleanly.
+   - **If it exists**: read it. The `## Checkpoints` section is append-only event log written by pre-compact and dream itself. Your refinement work targets:
+     - **Trim `## Checkpoints`**: if more than 10 entries, summarize older ones into a single "## Checkpoint summary {date-range}" entry. Preserve any `Status: unconsumed` entries as-is.
+     - **Pre-populate index sections** (`## Files touched`, `## Decisions made`, `## Gotchas surfaced`, `## Open questions`, `## Next steps`) from git diff + aiwiki writes during this session. Mark each line with a `<!-- dream-suggested -->` HTML comment so `/wrap` knows what dream proposed vs what the user wrote.
+     - **Do NOT set `status: done`** — that's `/wrap`'s responsibility. Leave `status: active`.
+   - Write the refined version to `aiwiki/proposed/{dream_id}/sessions/{date}-{session_id_short}.md`.
 
 ### Phase 4: Prune & index
 
@@ -94,7 +97,7 @@ Apply operations in this order:
 - ANY file in `aiwiki/` (input store untouched)
 - ANY file in `.forge/work/` (operational state, not knowledge)
 - Tombstone files for prunes (manifest's `operations` log records the prune; absence in proposed/ means delete on accept)
-- A fresh `aiwiki/sessions/{current}.md` if the hook-maintained one doesn't exist (FAIL with `SESSION_FILE_MISSING` instead — something is wrong upstream)
+- A fresh `aiwiki/sessions/{date}-{session_id_short}.md` if it doesn't exist — let the next pre-compact / /wrap / harden writer create it cleanly. If it's truly missing when you run, log `session_file_missing: true` in the dream manifest's `lint_warnings` and skip session-file refinement (no failure, no speculation-write)
 - Any file outside `aiwiki/proposed/{dream_id}/`
 
 ## Provider Mode (for `anthropic-managed` only)
@@ -111,7 +114,7 @@ If dispatched with `provider: anthropic-managed`:
 
 | Mistake | Fix |
 |---|---|
-| Recreating `aiwiki/sessions/{current}.md` instead of refining the existing one | The session file MUST exist (hook created it). If absent, FAIL — don't paper over an upstream bug. |
+| Recreating `aiwiki/sessions/{date}-{session_id_short}.md` instead of refining the existing one | The session file is expected to exist (pre-compact / /wrap / harden creates it lazily). If absent when you run, log `session_file_missing: true` in the manifest and skip session refinement — don't fabricate a session file. The next writer will create it cleanly. |
 | Promoting a raw entry that doesn't satisfy the target schema | Validate against schema first; failures go into `lint_warnings`, not into `aiwiki/proposed/{type}/` |
 | Merging unrelated typed pages because they share a keyword | Merge requires shared root cause / topic, not surface-level term overlap |
 | Pruning an entry without checking if the citation still resolves | Re-check the cited file/symbol before marking prune; LINT staleness != prune trigger |

package/agents/gotcha-hunter.md

@@ -98,7 +98,7 @@ If a relevant gotcha has status `promotion-pending`, note it explicitly:
 [!] PROMOTION-PENDING — {title}
   This gotcha was auto-drafted at the 3rd occurrence and is awaiting
   session-start review. The proposed rule targets {target_rule_file}.
-  Resolve at session-start or via /evolve before promoting more lessons.
+  Resolve at session-start or via /forge-evolve before promoting more lessons.
 ```
 
 ### Step 5: Summary

package/agents/prototype-codifier.md

@@ -153,7 +153,7 @@ For every production delta whose answer is non-obvious OR has tradeoffs, draft a
 Each draft has:
 - `status: proposed` (will be changed to `accepted` or dropped after review)
 - All required schema sections (Context, Decision, Alternatives if non-obvious, Consequences, Review)
-- The `review` block is left empty — the harden skill's step 2 fills it via adversarial review (the dedicated `/second-opinion` slash command is *planned, not yet implemented*; until it ships, harden inlines the adversarial pass and writes the resulting objections + verdict into the `review:` block before promoting the ADR to `accepted`)
+- The `review` block is left empty — the harden skill's Step 2 fills it via adversarial review (run inline by Claude, or dispatched to Codex in verify mode if configured) and writes the resulting objections + verdict into the `review:` block before promoting the ADR to `accepted`
 
 DO NOT skip an ADR because the answer "feels obvious." If it's a trigger-list decision, it needs the record.
 
@@ -187,7 +187,7 @@ Nothing. You return the structured proposal. The `harden` skill writes the files
 | Generating architecture by reasoning about what production should look like | Every claim cites a prototype file; if you can't cite, the claim is premature — drop it or mark it as a delta question for the user |
 | One giant architecture.md across all subsystems | Split by topic; multiple <400 line files beat one 1500-line file |
 | Skipping ADRs for "obvious" trigger-list decisions | Trigger list is strict; if it's on the list, the ADR exists regardless of how obvious you find the answer |
-| Pre-filling the ADR `review` block with imagined objections | Leave it empty; the harden skill's Step 2 runs adversarial review (today inline; `/second-opinion` dedicated surface is planned) to populate it |
+| Pre-filling the ADR `review` block with imagined objections | Leave it empty; the harden skill's Step 2 runs adversarial review (inline or via Codex verify mode) to populate it |
 | Slice graph with vague acceptance criteria like "implementation is complete" | Each criterion is testable: "all routes return JSON with the documented error shape", not "errors are handled" |
 | Promoting Phase 4 raw entries to typed pages | Not your job — dream consolidates raw at phase close |
 | Modifying the prototype to fix issues you noticed | The prototype is locked; if there's a real issue, surface it as a finding, do not edit |

package/commands/{forge.md → discover.md}

@@ -1,9 +1,9 @@
 ---
-name: forge
+name: discover
 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
+# /discover — 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).
 
@@ -26,7 +26,7 @@ Read the `## Project Profile` block from `CLAUDE.md` and present its yaml compac
 
 ## 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:
+Glob `.forge/work/*/*/manifest.yaml`. Exclude items whose top-level `status` is `completed` 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 |
@@ -46,7 +46,7 @@ Pick **one** suggestion based on the state observed in sections 2 and 3. Use thi
 | 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`." |
+| 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} — `/resume` to continue, or delete `.forge/work/{type}/{name}/` to drop it." |
 | 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 |
 
@@ -67,26 +67,30 @@ Workflow commands
 State commands
   /status             list in-flight work
   /resume <name>      continue an in-flight item
-  /abort <name>       cancel an in-flight item
+
+Knowledge commands
+  /note <text>        append a research note / brainstorm to aiwiki/raw/{date}.md
+  /dream [scope]      consolidate aiwiki — merge duplicates, promote raw → typed, prune stale
+  /wrap [focus]       capture & finalize current session into aiwiki/sessions/{date}-{id}.md
 
 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
+  /forge-evolve       improve the forge harness itself
+  /parallel <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 invokes `/discover` 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 invoke this on every session start — `support-system-guide` is the auto-triggering orientation skill. `/discover` 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.
 

package/commands/dream.md

@@ -0,0 +1,71 @@
+---
+name: dream
+description: "Manually trigger aiwiki consolidation. Merges duplicate notes, promotes raw → typed pages, prunes stale entries. Output is written to aiwiki/proposed/{dream_id}/ for review — input store is never modified. Use after a major refactor, a long session, or whenever aiwiki/ feels noisy. Optional argument: scope (default = full aiwiki/; alternatives = aiwiki/raw/, aiwiki/gotchas/, etc.)."
+---
+
+# /dream — Consolidate aiwiki
+
+Manual trigger for `support-dream`. Produces a reviewable consolidation proposal in `aiwiki/proposed/{dream_id}/`; you accept or reject via the web view (`forge wiki ui`) or CLI (`forge wiki review {dream_id}`).
+
+This is the user-driven trigger. Dream also fires automatically:
+- **PreCompact** — `hooks/scripts/pre-compact.sh` appends a `**Dream directive (unconsumed)**` block to the active session file's `## Checkpoints` section (`aiwiki/sessions/{date}-{session_id_short}.md`, created lazily). The post-compact agent reads the session file, finds the directive, and invokes `support-dream`.
+- **Phase-close** — `iterate-prototype`, `harden`, `build-pr-workflow`, and `deliver-deploy` dispatch `support-dream` after writing their respective `artifacts.{phase}.locked_at` lock signal.
+
+The manual `/dream` invocation is the escape hatch for between-trigger consolidation.
+
+## Steps
+
+1. **Parse scope** from the user's argument:
+   - No argument → scope is the full `aiwiki/` tree.
+   - One token (`raw`, `gotchas`, `decisions`, `conventions`, `architecture`, `sessions`) → scope is `aiwiki/{token}/`.
+   - Multiple tokens or explicit path → scope is the union of those paths.
+2. **Verify aiwiki exists.** If `aiwiki/` is missing, dispatch `support-wiki-bootstrap` first.
+3. **Check for pending dreams.** If `aiwiki/proposed/{dream_id}/` directories already exist with `review_status: pending` in their manifest, surface them to the user and ask whether to queue a new dream or review the pending ones first. Do not silently overwrite.
+4. **Invoke `support-dream` skill** with the parsed scope and `trigger: manual`. The skill dispatches the `dreamer` subagent and writes the proposed output.
+5. **Report to the user**: new `dream_id`, list of `changed_pages` / `new_pages` / `deleted_pages` counts, lint status, and the path to review:
+   ```
+   Dream complete: 2026-05-18-1742-manual
+     Proposals: aiwiki/proposed/2026-05-18-1742-manual/
+     Changed: 3   New: 1   Deleted: 0   Lint: passed
+     Review: `forge wiki review 2026-05-18-1742-manual` or open `forge wiki ui`
+   ```
+
+## Example
+
+User: `/dream`
+→ Full aiwiki consolidation, dispatched as `trigger: manual`.
+
+User: `/dream raw gotchas`
+→ Scope limited to `aiwiki/raw/` + `aiwiki/gotchas/`.
+
+User: `/dream after the auth refactor`
+→ Free-form description folded into `trigger_detail`; scope defaults to full aiwiki.
+
+## When to use
+
+- After a **major refactor** or **branch merge** brought in lots of new wiki entries.
+- When `aiwiki/raw/` has accumulated unclassified notes from `/note` invocations.
+- When you suspect **duplicate gotchas** across recent debugging sessions.
+- Before **handoff** to a new contributor — get the wiki into curated shape first.
+- When `forge wiki status` shows no pending dreams but the aiwiki feels noisy.
+
+## When NOT to use
+
+- A dream is already pending review (`forge wiki status` lists it). Review the existing one first; queueing a new dream against the same source state produces overlapping proposals.
+- `aiwiki/` has no recent activity — there's nothing to consolidate; the cycle would no-op.
+- You want to **edit a single page**. Edit it directly. Dream is for *merging / promoting / pruning across pages*, not per-page revision.
+
+## I/O Contract
+
+| Field | Value |
+|---|---|
+| **Requires** | `aiwiki/` (scaffolded by `/setup`), `aiwiki/schemas/` |
+| **Produces** | `aiwiki/proposed/{dream_id}/` (mirror structure) + `.dream-manifest.json` |
+| **Dispatches** | `support-dream` skill → `dreamer` subagent |
+| **Review surface** | `forge wiki ui` (web view at 127.0.0.1:8765) or `forge wiki review/accept/reject` CLI |
+
+## Do NOT
+
+- Do NOT modify `aiwiki/` directly inside this flow — that is `support-dream`'s invariant.
+- Do NOT queue a new dream while one is pending review against the same source state.
+- Do NOT skip the lint pass — `support-dream` runs lint on the proposed output before marking the dream complete.

package/commands/feature.md

@@ -58,8 +58,48 @@ If production mode is detected (or the user chose "no continue"), proceed to Ste
 
 REQUIRED SUB-SKILL: Use **support-wiki-bootstrap** to ensure aiwiki/ exists.
 
+## Step 0c: Trivial-Scope Fast Path
+
+Before stepping through phase planning, detect whether the work is bugfix-sized. If so, offer a single-confirmation fast path that collapses Steps 1–6 (planning, discover, concept, wireframe, design-system, prototype, codify) and jumps straight to worktree → production-build → tests → review → PR.
+
+**Detection signals (any one is sufficient):**
+- `--size trivial` flag passed
+- Description matches obvious trivial patterns: "fix typo", "change copy", "tweak <colour|spacing|padding|margin>", "rename X to Y", "bump version", "update dep", "add log line"
+- User has explicitly scoped to a single file path in the description
+
+**If a trivial signal fires, offer:**
+
+```
+This looks like trivial-scope work (signal: <list matched signals>).
+
+Fast path: skip Steps 1–6 (phase planning + discover + concept + wireframe + design-system + prototype + codify) and jump to:
+
+  Step 7   Worktree
+  Step 8   Production-build (build-tdd with --size trivial → focused regression test)
+  Step 9   Test plan + execution (trivial: unit tests for changed code, no E2E/load)
+  Step 10  Final code review
+  Step 11  Create PR
+  Step 13  Gotcha capture (if anything surprising emerged)
+
+Manifest will be created with phase_plan:
+  concept, wireframe, plan-design-system, prototype, iterate, codify,
+  discover-codebase, uiux-review, onboarding: skipped
+  production-build, test-plan, code-review-final, deliver, gotchas: active
+
+Confirm fast path? [Y]es / [n]o use standard /feature flow / [a]bort
+```
+
+User responses:
+- **Y / yes**: create the manifest with the trivial `phase_plan` above, then jump directly to Step 7 (skip Steps 1–6).
+- **n / no**: proceed to Step 1 with the standard flow. User must accept the planning ceremony explicitly.
+- **a / abort**: stop without action.
+
+If no trivial signal fires (or the user chose "no continue"), proceed to Step 1.
+
 ## Step 1: Manifest + Phase Planning
 
+**Skip if Step 0c's fast path was taken** — the manifest was already created with the trivial phase_plan and the flow has jumped to Step 7.
+
 Check if `.forge/work/feature/{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 — surface `successor_path` and ask the user.
@@ -82,17 +122,19 @@ For trivial features, multiple phases collapse — sometimes the entire workflow
 
 User can override any phase decision (e.g. "actually let's do a wireframe — I want to see the layout").
 
-## Step 2: Discover — Codebase Analysis
+## Step 2: Discover — Codebase Analysis — if active
+
+**Skip if** `phase_plan.discover-codebase: skipped` (the Step 0c fast path or explicit user override). For trivial-scope work that touches a single file the user has already named, codebase analysis is overhead; the trivial fast path skips it deliberately.
 
-REQUIRED SUB-SKILL: Use **discover-codebase-analysis**.
+**Otherwise:** REQUIRED SUB-SKILL: Use **discover-codebase-analysis**.
 
-For features on existing codebases, this is non-optional — production code grows from the prototype, and the prototype skins into the existing app. Without codebase analysis, the prototype-builder will reinvent patterns that already exist.
+For non-trivial features on existing codebases, this is non-optional — production code grows from the prototype, and the prototype skins into the existing app. Without codebase analysis, the prototype-builder will reinvent patterns that already exist.
 
 ### GATE: Codebase Analysis Approved
 
 User reviews. Update manifest: `discover.codebase-analysis.{status: complete, gate-passed: true}`.
 
-## Step 3: Concept (Phase 2) — if active
+## Step 3: Concept (Phase 1) — if active
 
 REQUIRED SUB-SKILL: Use **concept-slides**.
 
@@ -102,7 +144,7 @@ For features, often a 1-3 slide mini-deck — what the feature is, where it sits
 
 Update manifest: `artifacts.concept.{deck_path, locked_at}`. Presence of `locked_at` is the lock signal that downstream phases check.
 
-## Step 4: Wireframe (Phase 3) — if active
+## Step 4: Wireframe (Phase 2) — if active
 
 REQUIRED SUB-SKILL: Use **build-wireframe**.
 
@@ -124,7 +166,7 @@ Backend-only features (API endpoints, schema changes, internal refactors) skip t
 
 Update manifest: `artifacts.design-system.{path, approved_at}`.
 
-## Step 5: Prototype (Phase 4) — if active
+## Step 5: Prototype (Phase 3) — if active
 
 REQUIRED SUB-SKILL: Use **build-prototype**, then **iterate-prototype** for polish.
 
@@ -144,7 +186,7 @@ REQUIRED SUB-SKILL: Use **harden**.
 
 For features, often produces an architecture-delta (extending existing `aiwiki/architecture/{topic}.md` rather than creating new), 0-3 ADRs, and a focused slice graph (the production tasks specific to this feature).
 
-For features touching `--size major` complexity (auth, payments, PII, schema changes): adversarial review is mandatory on every ADR. The dedicated `/second-opinion` skill is *planned, not yet implemented* — until it ships, surface adversarial objections inline in the ADR `review:` block during harden Step 2 and have the user sign off explicitly before the ADR is marked `accepted`.
+For features touching `--size major` complexity (auth, payments, PII, schema changes): adversarial review is mandatory on every ADR. Surface adversarial objections inline in the ADR `review:` block during harden Step 2 and have the user sign off explicitly before the ADR is marked `accepted`. If Codex is configured (`protocols/codex.md`), the review pass may be dispatched to Codex in verify mode.
 
 ### GATE: Codified Plan Approved
 
@@ -164,7 +206,12 @@ Execute the slice graph from Phase 5. Per slice:
 2. REQUIRED SUB-SKILL: Use **quality-code-review**
 3. Fix any Critical or Important findings
 4. Per-slice user-confirm
-5. Per-slice dream consolidates slice-scoped wiki updates
+5. **Per-slice dream (auto-fire on slice close).** After the slice's gates pass (`gate-passed: true` on the slice's `code-review` + `runtime-reach`), invoke the **support-dream** skill with:
+   - **scope:** `aiwiki/gotchas/`, `aiwiki/conventions/` (any subfolders the slice's builder + reviewer subagents wrote to; check git diff on `aiwiki/` since the slice started for a precise list)
+   - **trigger:** `phase-close`
+   - **trigger_detail:** `"Phase 6 per-slice — {slice_id}"`
+   Dream output goes to `aiwiki/proposed/{dream_id}/`. Surface the id + review path to the user. The next slice can start while the proposal is pending review (per-slice dreams do NOT block forward motion — only phase-close gates do).
+   **Skip when:** the slice's build wrote nothing to `aiwiki/` (pure code change with no new gotcha or convention). No-op dreams add noise.
 
 For `--size major` features: also escalate to `quality-security-audit` on slices that touch auth/payments/PII.
 
@@ -172,7 +219,7 @@ Optional: `/autopilot production` for Ralph-loop hands-off slice execution *(pla
 
 ### GATE: All Slices Complete
 
-All slices `gate-passed: true`. Update manifest: `artifacts.production-build.locked_at` (the slice terminal state + the production code ARE the production-build artifacts).
+All slices `gate-passed: true`. Update manifest: `artifacts.production-build.locked_at` (the slice terminal state + the production code ARE the production-build artifacts). Any pending per-slice dream proposals from Step 8.5 must be reviewed before Phase 7 (deliver) starts — Phase 7's retrospective dream depends on a consolidated wiki state.
 
 ## Step 9: Test Plan + Execution
 
@@ -219,7 +266,7 @@ REQUIRED SUB-SKILL: Use **deliver-onboarding**.
 ## Step 13: Support — Record Lessons
 
 REQUIRED SUB-SKILL: Use **support-gotcha**.
-Final dream cycle consolidates all Phase 4-12 wiki captures.
+Final dream cycle consolidates all wiki captures from the previous phases.
 
 Update manifest: `status: completed`.
 

package/commands/{evolve.md → forge-evolve.md}

@@ -1,9 +1,9 @@
 ---
-name: evolve
-description: "Review lessons learned and improve the skill system. Run after completing a feature or project."
+name: forge-evolve
+description: "Review lessons learned from accumulated gotchas and improve the forge skill system itself. Run after completing a feature or project. Operates on the forge harness — not on user project code."
 ---
 
-# /evolve — Self-Improvement Review
+# /forge-evolve — Self-Improvement Review
 
 You are reviewing lessons learned and improving the forge skill system itself. This is how the system gets smarter over time. Run this after completing a feature, project, or periodically to process accumulated gotchas.
 

package/commands/greenfield.md

@@ -55,7 +55,7 @@ If the user provided detailed requirements upfront, this step extracts and struc
 
 REQUIRED SUB-SKILL: Use **discover-requirements** (only if user has substantive existing requirements docs).
 
-## Step 3: Concept (Phase 2)
+## Step 3: Concept (Phase 1)
 
 REQUIRED SUB-SKILL: Use **concept-slides**.
 
@@ -65,7 +65,7 @@ Produces a low-fidelity marp deck at `decks/{project-name}/slides.md` with hook,
 
 User reviews the rendered deck (HTML), gives feedback, locks when satisfied. Update manifest: `artifacts.concept.{deck_path, locked_at}`.
 
-## Step 4: Wireframe (Phase 3)
+## Step 4: Wireframe (Phase 2)
 
 REQUIRED SUB-SKILL: Use **build-wireframe**.
 
@@ -85,7 +85,7 @@ Backend-only / CLI projects without a frontend skip this step entirely (no desig
 
 User approves the design tokens written to `DESIGN.md`. Update manifest: `artifacts.design-system.{path, approved_at}`.
 
-## Step 5: Prototype (Phase 4)
+## Step 5: Prototype (Phase 3)
 
 REQUIRED SUB-SKILL: Use **build-prototype** for initial scaffold, then **iterate-prototype** for the polish loop.
 
@@ -105,7 +105,7 @@ 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/decisions/{nnnn}-{slug}.md` — ADRs (adversarial review runs inline at harden Step 2, surfacing objections in each ADR's `review:` block; optionally dispatched to Codex in verify mode when configured)
 - `aiwiki/conventions/` — production-surface conventions
 - `aiwiki/gotchas/` — Phase 4 gotchas with production addenda
 - Slice graph + `tasks.md` in manifest
@@ -144,7 +144,7 @@ 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):
+If the project has a frontend (per Step 1 phase planning):
 
 REQUIRED SUB-SKILL: Use **quality-uiux**.
 Validates production implementation matches the locked wireframe + design tokens.