forge-workflow 0.0.9 → 0.1.0-beta.2

package/README.md

@@ -1,435 +1,343 @@
 # Forge
 
 [![npm version](https://img.shields.io/npm/v/forge-workflow.svg)](https://www.npmjs.com/package/forge-workflow)
-[![npm downloads](https://img.shields.io/npm/dw/forge-workflow.svg)](https://www.npmjs.com/package/forge-workflow)
 [![license](https://img.shields.io/npm/l/forge-workflow.svg)](https://github.com/harshanandak/forge/blob/master/LICENSE)
 [![Tests](https://github.com/harshanandak/forge/actions/workflows/test.yml/badge.svg)](https://github.com/harshanandak/forge/actions/workflows/test.yml)
 [![ESLint](https://github.com/harshanandak/forge/actions/workflows/eslint.yml/badge.svg)](https://github.com/harshanandak/forge/actions/workflows/eslint.yml)
-[![Greptile Quality Gate](https://github.com/harshanandak/forge/actions/workflows/greptile-quality-gate.yml/badge.svg)](https://github.com/harshanandak/forge/actions/workflows/greptile-quality-gate.yml)
-[![Package Size](https://github.com/harshanandak/forge/actions/workflows/size-check.yml/badge.svg)](https://github.com/harshanandak/forge/actions/workflows/size-check.yml)
 [![Coverage](https://img.shields.io/badge/coverage-80%25-brightgreen.svg)](https://github.com/harshanandak/forge)
+[![Package Size](https://github.com/harshanandak/forge/actions/workflows/size-check.yml/badge.svg)](https://github.com/harshanandak/forge/actions/workflows/size-check.yml)
 [![CodeQL](https://github.com/harshanandak/forge/actions/workflows/codeql.yml/badge.svg)](https://github.com/harshanandak/forge/actions/workflows/codeql.yml)
 [![Security Policy](https://img.shields.io/badge/security-policy-blue.svg)](https://github.com/harshanandak/forge/blob/master/SECURITY.md)
 
-Ship features with confidence using a 7-stage TDD-first workflow for AI coding agents.
-
-```
-/plan → /dev → /validate → /ship → /review → /premerge → /verify
-```
-
-✅ **TDD-First**: Write tests before code
-✅ **Design-First**: One-question-at-a-time Q&A captures intent upfront
-✅ **Multi-Agent**: Universal AGENTS.md works with 8 agents
-
----
+## Never lose the thread of AI-assisted work.
 
-## Quick Example
+Coding agents are fast — and forgetful. Sessions break. Context resets. The
+agent forgets what it was doing, issues pile up untracked, and three months
+later you can't reconstruct why a change was made or what's still unfinished.
+Every new agent needs its own setup, and none of them share what the last one
+knew.
 
-**Adding a login button with Forge:**
+**Forge fixes that.** It's an agent-agnostic control plane that gives your
+coding agent — and you — a shared, durable memory of the work: issues,
+dependencies, workflow state, decisions, and validation evidence, all kept in
+your repo. Hand work to any agent, walk away mid-task, come back on another
+machine, and pick up exactly where you left off.
 
 ```bash
-/plan login-button        # Design Q&A → research → branch + task list
-/dev                      # TDD: RED → GREEN → REFACTOR cycles
-/validate                 # Type check + lint + tests + security scan
-/ship                     # Create PR with full documentation
+npx forge setup     # install for your agent (Claude Code, Codex, Cursor, Hermes)
+npx forge init      # configure your workflow gates + change classification
+npx forge status    # one-glance: where you are, what's next, what's ready
 ```
 
-**Result**: Feature shipped with tests, security validated, fully documented.
-
-**Without Forge** (chaotic):
-- Code first, tests later (or never)
-- No research or planning
-- Security issues found in production
-- Documentation forgotten
-
-**With Forge** (systematic):
-- Tests written BEFORE code (TDD)
-- Research-backed decisions
-- OWASP Top 10 analysis in every /plan
-- Documentation at every stage
-
-→ [See complete walkthrough in QUICKSTART.md](QUICKSTART.md)
+**[See what's coming next → ROADMAP.md](ROADMAP.md)**
 
----
+## Why Forge
 
-## Installation
+### 🤝 Works with your agent — whichever it is
 
-```bash
-# Step 1: Install the package (as dev dependency)
-bun add -D forge-workflow
+Claude Code, OpenAI Codex, Cursor, and Hermes today. You maintain **one
+canonical source** — skills, rules, instructions, hook policy, safety
+defaults — and Forge renders it into each agent's **native format**. Switch
+agents, mix agents, onboard a teammate on a different agent: everyone gets the
+same workflow, and nobody rewrites config.
 
-# Step 2: Setup for your AI agent
-bunx forge setup
+```mermaid
+flowchart LR
+    SRC["One canonical source<br/>skills/ · rules/ · AGENTS.md · .forge/"]
+    SRC --> C["Claude Code<br/>skills · settings · hooks · MCP"]
+    SRC --> U["Cursor<br/>skills · rules · hooks · ignore"]
+    SRC --> X["Codex<br/>skills · instructions · hooks"]
+    SRC --> H["Hermes<br/>skills · CLI orientation · hooks"]
 ```
 
-**That's it!** Forge will:
-- Create AGENTS.md (universal instructions)
-- Setup agent-specific files (Claude, Cursor, etc.)
-- Create docs/ folder with guides
+No lock-in, no per-agent reinvention — and no silent drift, because the
+rendered files are generated and drift-checked, never hand-copied.
 
-**Prerequisites**: Node.js, Git, GitHub account
-**Optional tools**: Beads (issue tracking)
+### 🛡️ Enforcement that actually enforces
 
-### Setup Flags
+Most "workflow" tooling is just prompts and hope. Forge wires its TDD gate and
+protected-path policy into **native hooks on all four agents**, so the rules
+hold even when the agent forgets them:
 
-| Flag | Description |
-|------|-------------|
-| `--agents=<list>` | Comma-separated agents to set up (e.g., `--agents=claude,cursor`) |
-| `--all` | Set up all supported agents |
-| `--dry-run` | Preview what setup would do without writing files |
-| `--non-interactive` | Skip all prompts (use defaults). Auto-enabled when `CI=true` |
-| `--symlink` | Create CLAUDE.md as a symlink to AGENTS.md instead of a copy |
-| `--sync` | Enable Beads GitHub sync (scaffolds workflow + PAT) |
-| `--verbose` | Show file-by-file detail instead of summary |
-| `--force` | Overwrite existing files even if content matches |
+- **Claude Code & Cursor** — project-local hooks installed automatically at
+  setup: test-first gating plus protected-path denial (on Cursor, shell writes
+  to protected paths are blocked too).
+- **Codex & Hermes** — those agents read hooks from global config, so Forge
+  never touches it silently: one explicit, consent-guarded command
+  (`forge hooks install --global`, with `--dry-run` preview) merges Forge's
+  hooks in without clobbering anything you already have.
 
-→ [Detailed setup guide for all agents](docs/SETUP.md)
+Git hooks remain the always-on backstop underneath, for any agent — or any
+human.
 
----
+### 🧾 Nothing discussed goes missing
 
-## The 7 Stages
+Every idea, bug, decision, and follow-up raised in a session gets filed to the
+local issue kernel **immediately** — that's a default-on rail, rendered into
+every agent's rules. Three weeks later, "that thing we noticed but didn't fix"
+is a tracked, searchable issue instead of a lost chat message.
 
-| Stage | Command | Purpose |
-|-------|---------|---------|
-| **utility** | `/status` | Ranked issue dashboard with conflict detection |
-| **1. Plan** | `/plan` | Design Q&A → research → branch + task list |
-| **2. Dev** | `/dev` | Subagent TDD per task (spec + quality review) |
-| **3. Validate** | `/validate` | Validate: types, lint, tests, security |
-| **4. Ship** | `/ship` | Create PR with documentation |
-| **5. Review** | `/review` | Address ALL PR feedback (Greptile, reviewers, CI/CD) |
-| **6. Premerge** | `/premerge` | Complete docs on feature branch, hand off PR |
-| **7. Verify** | `/verify` | Post-merge health check (CI on main) |
+Like every Forge rail, it's yours to control:
+`forge gate disable rail.kernel_tracking` turns it off deliberately.
 
-**Full workflow guide**: [AGENTS.md](AGENTS.md)
+### 🧵 Break anywhere, continue anywhere
 
----
+Your project state lives in the repo, not in a chat window. Workflow stage,
+claimed work, issues, memory, and handoff context survive session resets,
+context compaction, and machine switches. Any agent reads the same source of
+truth through `forge status`, `forge prime`, and `forge orient` — so a session
+that dies at 2am resumes cleanly the next morning, on any device, with any
+agent.
 
-## Supported AI Agents
+### 🧹 A lifecycle that cleans up after itself
 
-Works with **8 AI coding agents** via universal AGENTS.md:
+Merged a PR with squash-merge? `forge clean` still knows the worktree is done —
+it detects merges through three tiers (direct ancestry, squash-merge tree
+matching, and merged-PR head refs) instead of leaving "active" ghosts around.
+After merges, your local master is fast-forwarded automatically so the next
+piece of work starts from reality, not from last week.
 
-### Tier 1 (Primary Support)
+### 🔒 Safety by default
 
-| Agent | Features | Setup Time |
-|-------|----------|------------|
-| **Claude Code** | Custom slash commands, .claude/ directory | 30 seconds |
-| **GitHub Copilot** | Enterprise support, .github/copilot-instructions.md | 30 seconds |
-| **Kilo Code** | Auto failure recovery, .kilo.md | 30 seconds |
-| **Cursor** | Native modes (Plan/Ask/Debug), .cursor/rules/ | 30 seconds |
-| **Codex CLI** | OpenAI terminal agent, AGENTS.md | 30 seconds |
+`forge setup` ships safe defaults for each agent's native safety surface: a
+sane tool-permission allowlist for Claude Code (secrets denied, dev commands
+allowed) and a `.cursorignore` secrets boundary for Cursor. Everything is
+merge-preserving — your existing config is respected — and everything can be
+opted out of.
 
-### Tier 2 (Optional Support)
+### 🔎 Never lose track — down to the smallest thing
 
-| Agent | Features | Setup Time |
-|-------|----------|------------|
-| **OpenCode** | Flexible, opencode.json | 30 seconds |
-| **Goose** | Model flexibility, open-source | 30 seconds |
+Forge ships a local issue **kernel** plus a project **memory** system. Capture
+work the moment you spot it, wire up real dependencies, and everything stays
+tracked: what's ready, what's blocked, what's stale, what's done. Searchable and
+recoverable — find work from *months* ago in seconds instead of digging through
+old branches and chat logs.
 
-**Quick setup** (auto-detects agents):
 ```bash
-bunx forge setup
+forge create --title "Fix flaky auth test" --type bug
+forge issue dep add <blocker-id> <blocked-id>   # model real dependencies
+forge ready                                     # what can I pick up right now?
+forge remember "auth uses rotating JWT — see lib/auth.js"   # write memory
+forge recall auth                               # read it back, later, anywhere
 ```
 
-**Setup for specific agent**:
-```bash
-bunx forge setup --agent=copilot     # GitHub Copilot
-bunx forge setup --agent=cursor      # Cursor IDE
-bunx forge setup --agent=kilo        # Kilo Code
-bunx forge setup --agent=codex       # Codex CLI
-```
-
-**Setup for all Tier 1 agents**:
-```bash
-bunx forge setup --all
+### 📋 Honest by construction
+
+Forge keeps a machine-readable capability matrix of exactly what is delivered
+on each agent — and its statuses come from a closed, test-enforced vocabulary,
+so a claim can't quietly outrun the code. What's not delivered yet says
+"not delivered", in the repo, verifiably. See
+[the full per-agent capability reference](docs/reference/AGENT_SKILL_PARITY.md).
+
+## Ready now vs. experimental
+
+**Ready now** — installed and on by default:
+
+| Capability | What you get |
+| --- | --- |
+| Multi-agent rendering | One canonical source → native skills, rules, instructions for Claude Code, Cursor, Codex, Hermes |
+| Native enforcement hooks | TDD gate + protected-path denial on Claude Code and Cursor at setup; opt-in global install for Codex and Hermes |
+| Kernel tracking rail | Everything discussed becomes a tracked issue, default-on, toggleable |
+| Issue kernel | Create, claim, depend, close — local, fast, searchable |
+| Project memory | `forge remember` / `forge recall`, file-backed local store |
+| Lifecycle hygiene | Squash-merge-aware `forge clean`, automatic master fast-forward |
+| Safety defaults | Claude permission allowlist + Cursor secrets ignore, merge-preserving |
+| Quality-gated pushes | `forge push`: branch protection + lint + tests before anything leaves your machine |
+| Verified issue writes | Every kernel write is re-read and confirmed (`verified: true` in the response) — it caught a real bug on its very first run. Opt out with `forge gate disable gate.issue_verify` |
+
+**Experimental / opt-in** — real, shipped, and clearly labeled:
+
+| Capability | How to opt in |
+| --- | --- |
+| Knowledge-graph memory (Graphiti) | `memory.backend: graphiti` in `.forge/config.yaml` — temporal, relational recall ([guide](docs/guides/memory-backends.md)) |
+| Global hooks for Codex/Hermes | `forge hooks install --global` (consent-guarded, `--dry-run` first) |
+| Conditional auto-merge | `forge merge --auto <pr>` — off by default, merges only when configured rules pass |
+
+## A workflow you own
+
+Forge installs a proven **TDD-first** workflow —
+`/plan → /dev → /validate → /ship → /review` by default, with `/verify` added in
+the profiles that need it — but it is *not* a fixed prompt pack. Every stage and
+quality gate is a toggle, not a YAML archaeology project:
+
+```mermaid
+flowchart LR
+    subgraph defaults["Default-on rails and gates"]
+        R1["rail.kernel_tracking"]
+        G1["TDD pre-commit gate"]
+        G2["push quality gates"]
+    end
+    defaults -->|"forge gate disable &lt;id&gt;"| OFF["Deliberately off<br/>(recorded, reversible)"]
+    OFF -->|"forge gate enable &lt;id&gt;"| defaults
 ```
 
-→ [Agent-specific setup instructions](docs/SETUP.md)
-
----
-
-## What Makes Forge Different
-
-### 1. TDD-First Development
-Tests are written **BEFORE** code, every single time:
-- **RED**: Write a failing test
-- **GREEN**: Write minimal code to pass
-- **REFACTOR**: Clean up and commit
-- **REPEAT**: Next feature
-
-No feature ships without tests. Period.
-
-### 2. Research-First Planning
-AI researches best practices before you write a line of code:
-- Web search for latest patterns
-- OWASP Top 10 security analysis
-- Codebase pattern analysis
-- Decisions documented with evidence
+The default makes you productive on day one; the controls are yours from day
+two. Change your change-classification, adapt the stages to how your team
+actually works, and update it as you grow.
 
-Saves hours of debugging and refactoring later.
+## Who it's for
 
-### 3. Universal Compatibility
-One workflow, works with ALL major AI agents:
-- Single `AGENTS.md` file (universal standard)
-- Agent-specific enhancements (slash commands, skills)
-- Git-backed persistence (Beads)
-- No vendor lock-in
+- **Solo builders** using AI agents who are tired of lost handoffs and
+  half-remembered context.
+- **Teams** coordinating multiple agent or developer sessions in one repo.
+- **Quality-conscious engineers** who want agent output they can review, trust,
+  and release — grounded in local evidence, not vibes.
+- **Maintainers** keeping agent-authored work safe enough to resume and ship.
 
-Switch agents anytime without changing your workflow.
-
-### 4. Built-in TDD Enforcement
-Git hooks automatically enforce TDD practices:
-- **Pre-commit**: Blocks source commits without tests
-- **Pre-push**: Runs full test suite before push
-- **Interactive**: Guided recovery when violations occur
-- **CI/CD aware**: Auto-aborts in non-interactive environments
+## Quickstart
 
 ```bash
-# Validation CLI
-forge-preflight status    # Check project prerequisites
-forge-preflight dev       # Validate before /dev stage
-forge-preflight ship      # Validate before /ship stage
-```
+# Add to your project
+bun add -D forge-workflow          # or: npm install --save-dev forge-workflow
 
-### 5. Smart Tool Recommendations
-Curated plugin catalog across 7 workflow stages — plan, dev, validate, ship, review, and more:
-- **Auto-detection**: Scans your project for frameworks, databases, auth, payments, and more
-- **Budget modes**: free, open-source, startup, professional, custom
-- **Portability-first**: MCPs included only when they add clear value over CLI alternatives
-- **Free alternatives**: Every paid tool shows free alternatives
+# Install for your agent(s) and configure the workflow
+bunx forge setup --agents claude --yes
+bunx forge init --profile minimal --classification standard --yes
 
-```bash
-bunx forge recommend                  # Recommendations for your project
-bunx forge recommend --budget free    # Only free tools
+# Orient — for you and your agent
+bunx forge status                  # human one-glance view
+bunx forge prime                   # session-entry orientation for agents
 ```
 
-→ [Validation docs](docs/VALIDATION.md) | [Plugin docs](docs/TOOLCHAIN.md)
-
-### 6. Enhanced Onboarding
-Smart setup that adapts to your project:
-
-**Intelligent File Merging**
-- Preserves your existing AGENTS.md content
-- Adds Forge workflow without overwriting
-- Three options: smart merge, keep, or replace
-```bash
-bunx forge setup --merge=smart    # Intelligent merge
-```
+Prefer a standalone binary (no Node/Bun runtime)? Install it in one line:
 
-**Auto-Detection**
-- Detects framework (Next.js, React, Vue, Express)
-- Detects language (TypeScript, JavaScript)
-- Analyzes git stats and CI/CD setup
-- Infers project stage (new, active, stable)
-- Saves to `.forge/context.json`
-
-**Workflow Profiles** *(planned — not yet wired into setup)*
-- Will adapt workflow based on work type (3-8 stages):
-  - `critical`: Full 8-stage workflow (auth, payments, security-sensitive)
-  - `standard`: 7-stage workflow (typical features)
-  - `refactor`: Behavior-preserving 5-stage workflow
-  - `simple`: Streamlined 4-stage workflow
-  - `hotfix`: Minimal 3-stage workflow (production fixes)
-  - `docs`: Minimal 3-stage workflow (documentation/config)
 ```bash
-bunx forge setup --type=critical    # Set workflow manually
+# macOS / Linux
+curl -fsSL https://raw.githubusercontent.com/harshanandak/forge/master/scripts/install.sh | sh
 ```
 
-**Context Interview** (optional)
-```bash
-bunx forge setup --interview    # Gather project context
+```powershell
+# Windows (PowerShell)
+irm https://raw.githubusercontent.com/harshanandak/forge/master/scripts/install.ps1 | iex
 ```
 
-→ [Enhanced onboarding guide](docs/ENHANCED_ONBOARDING.md)
+See the [installation guide](docs/reference/INSTALL.md) for the supported
+platforms, pinned versions, manual downloads, and the npm/npx alternative.
+
+<details>
+<summary><strong>Per-agent setup notes</strong></summary>
+
+- **Claude Code** — `forge setup --agents claude` installs skills under
+  `.claude/skills/`, a `CLAUDE.md` shim over `AGENTS.md`, native enforcement
+  hooks and safe permission defaults in `.claude/settings.json`, and MCP config.
+- **Cursor** — `forge setup --agents cursor` installs `.cursor/skills/`,
+  policy rules in `.cursor/rules/`, native hooks in `.cursor/hooks.json`, a
+  `.cursorignore` secrets boundary, and MCP config.
+- **Codex** — `forge setup --agents codex` stages skills for the global Codex
+  install and commits a repo-local skills mirror so teammates get discovery on
+  clone. Hooks are global-config only: run `forge hooks install --global
+  --harness codex` when you want them.
+- **Hermes** — Forge-owned skills are projected under `.hermes/skills/` and
+  consumed through `forge orient` / `forge recap`. Hooks:
+  `forge hooks install --global --harness hermes`.
+
+The full, honest per-agent delivery status lives in the
+[capability matrix reference](docs/reference/AGENT_SKILL_PARITY.md).
+
+</details>
+
+Full guides:
+
+- [Quickstart](QUICKSTART.md) — clean first run, step by step
+- [Installation guide](docs/reference/INSTALL.md) — standalone binary + npm/npx
+- [Setup guide](docs/guides/SETUP.md)
+- [Support and troubleshooting](docs/guides/SUPPORT.md)
+- [Command reference](docs/reference/COMMANDS.md)
+- [Workflow templates & customization](docs/guides/WORKFLOW_TEMPLATES.md)
+
+Use `forge init` for the `.forge/` runtime config (gates + classification). Use
+`forge setup` to install agent instructions, skills, and agent-specific files.
+Use `bunx forge ...` (or `npx forge ...`) until the `forge` bin is on your PATH.
+
+### Setup flags
+
+| Flag | Use |
+| --- | --- |
+| `--agents claude,cursor` | Install for specific agents (or `--all` for every harness). |
+| `--quick` | Use sensible defaults with minimal prompts. |
+| `--yes` / `--non-interactive` | Run without prompts; `CI=true` also enables non-interactive behavior. |
+| `--dry-run` | Preview planned writes without touching the repo. |
+| `--symlink` | Link instruction files instead of copying, where supported. |
+| `--merge smart\|preserve\|replace` | Choose how setup handles existing instruction files. |
+| `--sync` | Deprecated. Removes old generated Beads/GitHub sync files; future issue sync belongs to Kernel/server authority. |
+
+## What you get
+
+- **Issue kernel** — `forge create`, `forge ready`, `forge show`, `forge claim`,
+  `forge close`, `forge issue dep`, `forge blocked`, `forge stale`. The Kernel is
+  the default backend; a Beads store can be imported (below) or selected as an
+  opt-out backend with `--issue-backend beads`.
+- **Project memory** — `forge remember` / `forge recall` for durable, searchable
+  notes that outlive the session (no scattered `MEMORY.md` files), with an
+  opt-in knowledge-graph backend for temporal recall
+  ([memory guide](docs/guides/memory-backends.md)).
+- **One-glance state** — `forge status`, `forge board`, `forge orient`,
+  `forge prime`, `forge recap` for humans and agents.
+- **Safe, isolated work** — `forge worktree create <slug>`, squash-merge-aware
+  `forge clean`.
+- **Configurable quality gates** — `forge validate`, `forge push` (branch
+  protection + lint + tests), tuned per project via `forge gate` and
+  `forge init`.
+- **Native agent enforcement** — TDD + protected-path hooks rendered for all
+  four agents; project-local and automatic where the agent allows it, one
+  consent-guarded command where it doesn't.
+- **Ship & recover** — `forge ship`, `forge review`, `forge shepherd` (bounded PR
+  monitor), `forge merge` (opt-in conditional auto-merge, off by default),
+  `forge upgrade` (safe self-heal).
+- **Coming from Beads?** `forge migrate --from beads` imports your existing issue
+  store into the Kernel in one command (`--dry-run` to preview first); the first
+  kernel use also auto-imports a detected store, so nothing is lost.
+
+## Common commands
 
-### 7. Automated Quality Gates 🆕
-Multi-layer quality enforcement before merge:
-
-**Greptile AI Code Review**
-- AI-powered review on every PR
-- Catches bugs, security issues, performance problems
-- Detailed inline feedback with fix suggestions
-- Automatic re-review after changes
 ```bash
-# Branch protection requires Greptile review to pass
-# Typically completes in 1-2 minutes
+forge --help
+forge status                 # where am I, what's next
+forge ready                  # available work
+forge show <issue-id>
+forge claim <issue-id>
+forge remember "<note>"      # write project memory
+forge recall <query>         # read it back
+forge worktree create <slug>
+forge board --json
+forge validate
+forge gate disable <gate-id> # every rail and gate is yours to toggle
 ```
 
-**GitHub Actions Workflows**
-- Greptile Quality Gate: Enforces minimum score (≥4/5)
-- ESLint checks: Code quality validation
-- Test suite: All tests must pass
-
-**Git Hooks (Lefthook)**
-- Pre-commit: TDD enforcement (tests required)
-- Pre-push: Full test suite + lint checks
-- Branch protection: Blocks direct push to main/master
+Stage commands such as `/plan`, `/dev`, `/review`, and `/verify` are agent
+workflow stages installed by `forge setup`. Pre-merge is a documentation-and-
+handoff gate embedded in `/ship` and `/review`, not a separate stage.
 
-→ [Greptile setup guide](docs/GREPTILE_SETUP.md)
+## Documentation map
 
----
+- [Roadmap](ROADMAP.md) — what's shipping next, by theme
+- [Docs index](docs/INDEX.md) — canonical reading order
+- [Migration guide](docs/guides/MIGRATION.md) — moving to the Kernel and current workflow framing
+- [Workflow templates & customization](docs/guides/WORKFLOW_TEMPLATES.md) — the default workflow and how to change it
+- [Skills and command projections](docs/reference/SKILLS.md)
+- [Agent capability matrix](docs/reference/AGENT_SKILL_PARITY.md) — honest per-agent delivery status
+- [Memory backends](docs/guides/memory-backends.md) — local default and the opt-in graph backend
+- [Adapters](docs/reference/ADAPTERS.md) — review adapter contract
+- [Protected state surfaces](docs/reference/protected-state-surfaces.md)
+- [Release reference](docs/reference/RELEASE.md)
 
-## The Toolchain
+## Terms
 
-Forge integrates with powerful tools:
-
-```
-┌──────────────────────────────────────────────┐
-│              FORGE TOOLCHAIN                 │
-├──────────────────────────────────────────────┤
-│                                              │
-│  ┌──────────┐                  ┌──────────┐  │
-│  │  BEADS   │                  │  GITHUB  │  │
-│  │  Issue   │                  │    PR    │  │
-│  │ Tracking │                  │ Workflow │  │
-│  └──────────┘                  └──────────┘  │
-│       │                              │       │
-│       └──────────────────────────────┘       │
-│                      │                       │
-│                ┌─────▼─────┐                 │
-│                │   FORGE   │                 │
-│                │ 7-Stage   │                 │
-│                │ Workflow  │                 │
-│                └───────────┘                 │
-│                                              │
-└──────────────────────────────────────────────┘
-```
-
-**All tools are optional** - Forge works standalone.
-
-**Beads** (optional): Git-backed issue tracking that survives context clearing
-```bash
-bun add -g @beads/bd && bd init
-```
-
-**GitHub CLI** (recommended): Required for PR workflow
-```bash
-gh auth login
-```
+- **Control plane** — local commands, files, and checks that give agents a shared operating surface.
+- **Kernel** — the default local issue-state store, backing `forge` issue commands.
+- **Workflow template** — the default stage path Forge installs (`/plan → /dev → /validate → /ship → /review`, with `/verify` in the profiles that need it), fully configurable.
+- **Harness** — an agent-specific instruction surface. Forge supports Claude Code, Codex, Cursor, and Hermes.
+- **Rail** — a default-on behavior policy (like kernel tracking) rendered into every agent's rules and toggleable with `forge gate`.
+- **Memory** — durable, searchable project notes written with `forge remember` and read with `forge recall`.
+- **Adapter** — an integration boundary for review or issue tools.
+- **Protected state** — files that should be changed through their owning command or API, not by casual edits.
 
-→ [Complete toolchain guide](docs/TOOLCHAIN.md)
+## Package
 
----
+Package name: `forge-workflow`
 
-## Real-World Examples
-
-### Example 1: Simple Feature (20 minutes)
-**Task**: Add a health check endpoint
-
-```bash
-/plan health-check-endpoint      # Design Q&A → research → branch + task list
-/dev                             # 8 min: TDD implementation
-/validate                           # 2 min: All validations pass
-/ship                            # 2 min: PR created
-# → Greptile AI review completes (~2 min)
-/review                          # 3 min: Address Greptile feedback
-/premerge                        # 2 min: Complete docs, hand off PR
-```
-
-### Example 2: Bug Fix with Security (30 minutes)
-**Task**: Fix SQL injection vulnerability
-
-```bash
-/plan sql-injection-fix          # Design Q&A → OWASP research → branch
-/dev                             # 8 min: Fix + tests
-/validate                           # 3 min: Security scan
-/ship                            # 2 min: PR with security notes
-# → Greptile validates security fix (~2 min)
-/review                          # 5 min: Address security feedback
-/premerge                        # 3 min: Complete docs, hand off PR
-```
-
-### Example 3: Architecture Change (2-3 days)
-**Task**: Add authentication system
-
-```bash
-/plan user-authentication        # Design Q&A → deep research → branch
-/dev                             # 1-2 days: TDD implementation
-/validate                           # 30 min: Full validation
-/ship                            # 15 min: PR with docs
-/review                          # Varies: Address feedback
-/premerge                        # 15 min: Complete docs, hand off PR
-/verify                          # 15 min: Post-merge health check
-```
-
-→ [More examples in docs/EXAMPLES.md](docs/EXAMPLES.md)
-
----
-
-## Core Principles
-
-**TDD-First**: Tests before code, always
-**Design-First**: One-question-at-a-time Q&A captures intent before research
-**Security Built-In**: OWASP Top 10 for every feature
-**Documentation Progressive**: Update at each stage
-**Multi-Session**: Work persists across sessions
-
-→ [Read the philosophy in AGENTS.md](AGENTS.md)
-
----
-
-## Next Steps
-
-📚 **New to Forge?**
-→ [QUICKSTART.md](QUICKSTART.md) - Your first feature in 5 minutes
-
-📖 **Learn the workflow**
-→ [AGENTS.md](AGENTS.md) - Complete guide with examples
-
-🛠️ **Setup the toolchain**
-→ [docs/TOOLCHAIN.md](docs/TOOLCHAIN.md) - Beads, GitHub CLI
-
-🎯 **See real examples**
-→ [docs/EXAMPLES.md](docs/EXAMPLES.md) - Real-world use cases
-
-💬 **Have questions?**
-→ [GitHub Discussions](https://github.com/harshanandak/forge/discussions)
-
-🐛 **Found a bug?**
-→ [GitHub Issues](https://github.com/harshanandak/forge/issues)
-
----
-
-## Quick Reference
-
-```bash
-# Forge commands
-/status                    # Check current context
-/plan <feature>            # Design Q&A → research → branch + task list
-/dev                       # TDD development
-/validate                     # Validate everything
-/ship                      # Create PR
-/review <pr>               # Address feedback
-/premerge <pr>             # Complete docs, hand off PR
-/verify                    # Post-merge health check
-
-# Issue commands (via Forge)
-bd init                    # Initialize Beads tracking
-forge ready                # Find ready work
-forge create "title"       # Create issue
-forge update <id> --status X  # Update status
-forge sync                 # Sync Beads state
-```
-
-For advanced Beads operations that Forge does not wrap yet, use `bd` directly for
-`bd comments`, `bd dep`, and `bd dolt`.
-
-Forge is the preferred command surface for routine workflows, but Beads (`bd`)
-remains the underlying source of truth for issue state and IDs.
-
----
+Binary names: `forge`, `forge-workflow`, `forge-preflight`
 
 ## License
 
-MIT © Harsha Nandak
-
----
-
-**Ready to start?**
-
-```bash
-bun add -D forge-workflow
-bunx forge setup
-/status
-```
-
-Then open [QUICKSTART.md](QUICKSTART.md) and ship your first feature! 🚀
+MIT