---
description: Forge system structure — skills (prefix-grouped), commands (orchestrate skills), .forge/ directory layout, aiwiki/ knowledge layer, context recovery. Auto-loaded every session so agents know the system they're operating in.
---

# Forge System

This project uses **forge** as its development workflow. Every session should follow it.

## Skills (prefix-grouped)

| Prefix | Purpose | Examples |
|--------|---------|---------|
| `discover-` | Understand inputs and codebase | requirements, codebase-analysis |
| `plan-` | Design before building | brainstorm, architecture, task-decompose, design-system |
| `build-` | Write code and manage git | scaffold, tdd, pr-workflow, wireframe, prototype |
| `quality-` | Review, test, audit | code-review, test-plan, test-execution, security-audit, uiux |
| `deliver-` | Ship and migrate | deploy, db-migration, onboarding |
| `support-` | Maintain and learn | system-guide, debug, gotcha, skill-validator |

The prototype-driven phases add: concept-slides, build-wireframe, build-prototype, iterate-prototype, harden.

## Commands (orchestrate skills)

| Command | When to use |
|---------|------------|
| `/discover` | One-screen discovery — installed capabilities, active work, suggested next |
| `/setup` | Detect stack, install matching language rules, and fill the project profile |
| `/feature` | Full feature development |
| `/greenfield` | New project from zero |
| `/bugfix` | Fix a bug |
| `/refactor` | Improve existing code |
| `/hotfix` | Emergency production fix |
| `/note <text>` | Capture an ad-hoc research note or brainstorm to `aiwiki/raw/{date}.md` |
| `/forge-evolve` | Improve the forge system itself |
| `/validate` | Check skill consistency |

## .forge/ Directory

```
.forge/
  work/                        # Per-work-item artifacts, one subdir per type
    feature/{name}/            # manifest, requirements, architecture, tasks, test plan/results
    bugfix/{name}/             # manifest, debug notes, regression tests
    refactor/{name}/           # manifest, codebase analysis, tasks, test results
    hotfix/{name}/             # manifest, minimal debug, smoke tests
    greenfield/{name}/         # manifest + full project scaffold artifacts
  state/                       # Runtime state (telemetry, dream history). Per-session handoff lives in aiwiki/sessions/ — see below.
```

The `.forge/` directory retains operational state only (manifests, telemetry, dream history). Project knowledge lives in `aiwiki/` (next section).

Work items are identified by `{type}/{name}` — names may collide across types.

## aiwiki/ (knowledge layer — optional)

`aiwiki/` accumulates lasting project knowledge — separate from `.forge/` which is operational state. Subagents read these pages to inform their work, so the typed pages have schemas enforced by `wiki-lint`.

**Opt-in.** The layer is enabled via `project.aiwiki_enabled: true` in `.claude/CLAUDE.md`, set during `/setup` Step 4. Default is `true` for production/greenfield projects and `false` for prototype projects — the user can override either way. When `aiwiki_enabled: false`, the `aiwiki/` directory does not exist and downstream skills (`support-gotcha`, `harden`, `iterate-prototype` capture, `support-dream`, `/note`, `/wrap`) surface a one-line upgrade hint ("would have written {description} to aiwiki/…; re-run `/setup` and pick Y to enable") instead of writing typed pages. The rest of the skill continues — disabling the layer never halts a workflow, only suppresses the capture leg.

| Page type | Purpose | Written by |
|---|---|---|
| `decisions/` | ADRs — architecture decisions + rationale | `plan-brainstorm`, `harden`, manual |
| `gotchas/` | Recurring failure modes with reproducible fixes | `iterate-prototype`, `quality-code-review`, manual |
| `conventions/` | Established patterns in this codebase | `iterate-prototype`, `harden`, manual |
| `architecture/` | Component maps, sequence diagrams | `harden`, manual |
| `sessions/` | Per-session handoff: `## Checkpoints` event log (pre-compact, /dream) + index sections (Files touched, Decisions, Gotchas, Open questions, Next steps) filled by `/wrap`. Filename `{date}-{session_id_short}.md`. Lazy-created by first writer in the session. | `hooks/scripts/pre-compact.sh`, `/wrap`, `/dream`, `harden` |
| `oracles/` | Prototype behavior snapshots that Phase 6 production code must reproduce (setup → trigger → assertions) | `harden` (Step 2.5) |
| `raw/` | Append-only research/brainstorm capture (no schema) | `/note <text>`, manual |

**Auto-capture during phases.** `iterate-prototype` (Phase 4) writes gotchas and conventions surfaced during prototype iteration. Phases 1 (concept) and 2 (wireframe) have **no auto-capture** — use `/note <text>` to land research/brainstorm in `aiwiki/raw/{date}.md`.

**Lint** (`wiki-lint` PostToolUse hook). Fires on every `aiwiki/**.md` write (Edit/Write/MultiEdit). Validates frontmatter, required H2 sections, line caps, citation hash drift, and possible-secret patterns in cited content against the page's schema. Skips `aiwiki/raw/` (no schema) and `aiwiki/proposed/` (lint runs there separately at dream-complete). Findings surface on stderr — non-blocking, but the next edit should address them.

**Dream** (`support-dream` skill). Async consolidation:
- **PreCompact** (~85% context): consolidates `aiwiki/raw/` + recently-touched typed pages before lossy compaction. Also refines the active session file's `## Checkpoints` event log (if it exceeds ~10 entries) and pre-populates index sections from git diff. The pre-compact hook itself writes an unconsumed dream directive to the session file's checkpoints; the post-compact agent reads it and dispatches this skill.
- **Phase-close** (Phase 4/5/6/7 lock): promotes phase outputs into curated wiki state. The next phase **blocks** until the user reviews the proposed dream.
- **Manual `/dream`**: user-driven cleanup.

Dream outputs to `aiwiki/proposed/{dream_id}/` — input store is never modified. User atomically accepts (swap) or rejects (discard) via `forge wiki accept` / `reject`.

### When the AI should write to aiwiki

The discipline is **selectivity, not abstention.** AI writes happen routinely — `support-gotcha`, `iterate-prototype` (via `prototype-builder`), and `harden` all write to typed pages directly during their normal operation, and the pre-compact hook + `/wrap` write to `aiwiki/sessions/`. Wiki-lint validates schema on every write; the user can edit or delete any page after the fact. The rule is what content qualifies — not whether AI can write.

Per-folder discipline:

| Folder | Who writes | Gate |
|---|---|---|
| `raw/` | **User only**, via `/note <text>` | The user is the gate. AI does NOT decide to write conversational asides to raw on its own. |
| `decisions/` `gotchas/` `conventions/` `architecture/` `oracles/` | AI writes directly via `support-gotcha`, `iterate-prototype`, `harden`, code-review subagents | Schema (enforced by wiki-lint) + durability test (below). User can edit/delete after-the-fact. |
| `sessions/` | `pre-compact.sh` (Checkpoints) + `/wrap` (index sections) + `harden` (codify-time session entry) | Schema. `/wrap` confirms with user before setting `status: done`. |
| `proposed/` | `dreamer` subagent only (via `support-dream`) | User reviews each proposal via `forge wiki ui` / `forge wiki review` and atomically accepts or rejects. |

Three durability rules that override any temptation to over-capture:

1. **Never write speculation, conversation history, or "we might want to revisit this" notes.** This is the strongest rule. Wiki pages answer recurring questions; conversational asides do not. Speculation goes to raw via `/note` (user-gated), not to typed pages.
2. **Typed pages need durable, reusable knowledge.** ADRs go to `decisions/` only when the choice is finalized AND hard-to-reverse (architectural, public-surface, security, schema). Gotchas to `gotchas/` only when the failure mode is reproducible with a concrete fix. Conventions to `conventions/` only when the pattern is established across multiple sites. If the knowledge isn't yet durable, it doesn't belong in a typed page.
3. **Raw is `/note`-only.** Ad-hoc research, half-formed thoughts, deferred decisions, comparison notes all go to `aiwiki/raw/` — and ONLY when the user explicitly invokes `/note <text>`. The AI does not autonomously decide what becomes raw content.

When a typed-page-worthy insight emerges mid-conversation (e.g., "this is a real gotcha"), write it to the correct typed page if it meets that page's durability test. When the durability is uncertain, ask the user instead of speculating.

**Session-end handoff.** Forge provides `/wrap` for explicit session-end capture. Run it at a natural session boundary: it fills the active session file's index sections (Files touched / Decisions made / Gotchas surfaced / Open questions / Next steps) and sets `status: done`. The next `SessionStart` hook surfaces the latest session's focus and any unconsumed `## Checkpoints` directives. If `/wrap` isn't invoked, the session file (if pre-compact created one) stays `status: active` — `SessionStart` will surface it as unfinalized so the next session can pick up. The AI should OFFER to run `/wrap` before a long break or context shift; never silently fabricate a session summary.

## Context Recovery

On session start or after compaction, recovery state lives in **two places**, in priority order:

1. **`aiwiki/sessions/{date}-{session_id_short}.md`** — the per-session handoff file. Read this FIRST.
   - The `## Checkpoints` section is an append-only event log. Any entry with header `**Dream directive (unconsumed):**` is an action item for the current agent (typically: invoke `support-dream`). After acting, change the header from `(unconsumed)` to `(consumed at {ISO-timestamp})`. The `session-start.sh` hook counts active directives by matching the bold header literally — flipping the header is what makes the count accurate (dogfood-validated 2026-05-18).
   - The index sections (`## Files touched` / `## Decisions made` / `## Gotchas surfaced` / `## Open questions` / `## Next steps`) describe the prior session's work. If `status: done`, the file was `/wrap`'d. If `status: active`, the prior session didn't run `/wrap` — surface the file as in-progress context.
2. **The active manifest** (`.forge/work/*/*/manifest.yaml` with `status: in-progress`). Read after the session file to anchor on the work item's current phase and gate state.

`SessionStart` hook (`hooks/scripts/session-start.sh`) automatically surfaces the latest session file's focus + any unconsumed checkpoints on stderr. The agent should still re-read the file's full content when acting on a directive.

**Notepad deprecated.** Session recovery state lives in `aiwiki/sessions/{date}-{session_id_short}.md`. Earlier installs may have a legacy `.forge/state/notepad.md` — it's safe to delete; nothing reads or writes it anymore.

## Rules

Rules in `.claude/rules/` are always-on constraints. Common rules apply to all projects. Language-specific rules layer on top.