@jamie-tam/forge 6.0.0 → 6.1.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
+- **13 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** — 13 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,46 @@ 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)
+/parallel   (parallel)        quality-code-review
+/status                       quality-test-plan
+/resume                       quality-test-execution               References (load on demand)
+/forge-evolve                 quality-security-audit               ----------------------------
+/validate                     quality-uiux                         common/
+                              deliver-deploy     [Phase 7]           agent-coordination
+                              deliver-db-migration                   io-protocol
+Work Manifests (v6)           deliver-onboarding                     skill-authoring
+-------------------           discover-requirements                  skill-compliance
+.forge/work/                  discover-codebase-analysis             phases (canonical vocab)
+  {type}/                     plan-brainstorm                        coding-standards
+    {name}/                   plan-architecture                      quality-gates
+      manifest.yaml           plan-design-system                     feature-tracking
+        schema_version: "6"   plan-task-decompose                  typescript/  python/  react/
+        phase_plan: {…}       support-system-guide                   [extensible]
+        phases: {…}           support-debug
+        slice_graph: {…}      support-gotcha                       Protocols (read on demand)
+        artifacts: {…}        support-wiki-lint                    --------------------------
+                              support-wiki-bootstrap               protocols/codex.md
+aiwiki/ (knowledge layer)     support-dream                        protocols/graphify.md
+-------------------------     support-parallel
+  decisions/                  support-runtime-reachability         Hooks
+  gotchas/                    support-skill-validator              ------
+  conventions/                                                     gate-enforcer
+  architecture/                                                    wiki-lint
+  sessions/                                                        session-start / pre-compact
+  raw/                                                             telemetry
+  proposed/  (dream queue)
+  schemas/
+  CLAUDE.md  (usage rules)
 ```
 
 ---
@@ -188,15 +195,19 @@ 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 |
+| `/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 +221,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 +268,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 +283,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,10 @@ 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. **Refresh session file (PreCompact only, conditional)** — for `aiwiki/sessions/{current}.md`:
+   - **Check first**: does `aiwiki/sessions/{current}.md` exist? Session-checkpoint hooks (SessionStart create + PostToolUse append) are currently **deferred** per `templates/aiwiki/schemas/session.md`. If the file does NOT exist, SKIP this step entirely — no failure, no fresh-write. Proceed with raw + typed page consolidation only.
+   - If it DOES exist: read it (the hook-maintained event log), consolidate the event log into the schema sections (Files touched, Decisions made, Gotchas surfaced, Open questions, Next steps), and write the refined version to `aiwiki/proposed/{dream_id}/sessions/{current}.md`.
+   - DO NOT recreate the file if missing — that would generate speculation (`templates/aiwiki/CLAUDE.md.template:76` forbids it). The skip-if-missing branch handles the deferred-hooks state cleanly.
 
 ### Phase 4: Prune & index
 
@@ -94,7 +93,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/{current}.md` if it doesn't exist — session-checkpoint hooks are currently deferred per `templates/aiwiki/schemas/session.md`; SKIP session-file refinement instead (no failure, no speculation-write)
 - Any file outside `aiwiki/proposed/{dream_id}/`
 
 ## Provider Mode (for `anthropic-managed` only)

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,28 @@ 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
 
 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/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
 
@@ -219,7 +261,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.

package/commands/note.md

@@ -0,0 +1,64 @@
+---
+name: note
+description: "Append a one-off research note, brainstorm, or insight to aiwiki/raw/{date}.md with a timestamp. Zero schema, zero friction — capture first, dream consolidates later. Use during Phase 1-2 research, ad-hoc exploration, or any thought worth remembering that doesn't yet fit a typed page (decision/gotcha/convention)."
+---
+
+# /note — Capture to aiwiki/raw
+
+Append the user-supplied text to `aiwiki/raw/{YYYY-MM-DD}.md` under a timestamped header. No schema, no judgment — just capture. The wiki-lint hook fires automatically on save (no-op for raw/ since raw has no schema). `support-dream` consolidates raw entries at phase-close and PreCompact (~85% context), promoting anything that matches a typed schema to `aiwiki/proposed/{dream_id}/` for review.
+
+## Steps
+
+1. **Note text** = everything after `/note ` in the user's invocation. If the argument is empty, ask the user what they'd like to capture and wait for the reply.
+2. **Today's date** = `$(date +%Y-%m-%d)`.
+3. **Target file** = `aiwiki/raw/{date}.md`. Create the directory if needed: `mkdir -p aiwiki/raw`.
+4. **If the file doesn't exist**, start it with: `# Raw notes — {date}` followed by a blank line.
+5. **Append a section**:
+   - Header: `## {HH:MM} — {first ~60 chars of the note, no trailing punctuation}`
+   - Blank line
+   - The full note body
+   - Blank line
+6. **Confirm to the user**: "Captured to `aiwiki/raw/{date}.md`."
+
+## Example
+
+User: `/note Considering Tailwind v4 — oxide engine fast but plugin ecosystem still broken in 2026; revisit in Q3`
+
+Resulting `aiwiki/raw/2026-05-15.md`:
+
+```markdown
+# Raw notes — 2026-05-15
+
+## 14:23 — Considering Tailwind v4 — oxide engine fast but plugin ecosystem
+
+Considering Tailwind v4 — oxide engine fast but plugin ecosystem still broken in 2026; revisit in Q3
+```
+
+## When to use
+
+- During **Phase 1 (concept)** or **Phase 2 (wireframe)** when research or brainstorm yields an insight worth remembering — neither phase auto-captures to aiwiki, so `/note` is the manual hook.
+- During any phase when a thought doesn't yet fit a typed page (it's not yet a decision, not yet a confirmed gotcha, not yet an established convention).
+- When deferring a decision: "considered X, need more info before committing."
+
+## When NOT to use
+
+- The content is a **decision** → write to `aiwiki/decisions/` directly using the decision schema. Future agents read that folder for ADRs; raw notes there won't be retrieved predictably.
+- The content is a **confirmed gotcha** (with reproducible failure mode) → write to `aiwiki/gotchas/` directly so gotcha-hunter can find it.
+- The content is an **established convention** → write to `aiwiki/conventions/` so harden and code-reviewer can enforce it.
+
+`/note` is for the in-between — research, hypotheses, half-formed thoughts that haven't earned a typed page yet. Dream consolidation will promote anything that matures into a typed shape.
+
+## I/O Contract
+
+| Field | Value |
+|---|---|
+| **Requires** | `aiwiki/` directory (scaffolded by `/setup`) |
+| **Produces** | New or appended `aiwiki/raw/{YYYY-MM-DD}.md` |
+| **Triggers** | `wiki-lint` PostToolUse hook (no-op for raw/) |
+| **Feeds into** | `support-dream` at phase-close and PreCompact — raw entries that match typed schemas get promoted to `aiwiki/proposed/{dream_id}/` for user review |
+
+## Do NOT
+
+- Do NOT edit prior entries. The point is append-only history. If a note turned out wrong, append a correction with the new timestamp.
+- Do NOT structure the note. Plain prose. Schema-fitting is dream's job, not yours.
+- Do NOT use `/note` for things that already fit a typed schema — write the typed page directly instead.