@guidobuilds/forge-ai 0.3.0 → 0.6.0

package/CHANGELOG.md

@@ -9,6 +9,78 @@ Versions prior to 0.3.0 are not reconstructed here; see git history for earlier
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-07-05
+
+### Added
+
+- **`forge-worker-leaf` agent** — terminal worker for bounded subgoal shards at `DISPATCH_DEPTH: 2`. No spawn tools (`task: deny` on OpenCode; no `Agent`/`task` on Claude/Grok). Installed alongside `forge-worker` on all platforms.
+- **Worker sub-delegation** — `forge-worker` is now a coordinator that spawns `forge-worker-leaf` when context triggers fire (≥ 8 file reads, ≥ 6 searches, ≥ 20 tool calls, ≥ 5 files to build, or `DELEGATION: required`). Extended worker contract: `DISPATCH_DEPTH`, `WORKER_ROLE`, `SUB_RESULTS`, `DELEGATION_REQUESTS`, `NEXT_RECOMMENDED: sub-delegate`.
+- **Pre-build approval gate** — for non-trivial work, the orchestrator presents an approval brief (conclusions, path/tasks, why) after inspect/design/plan (and `forge-grill` if it ran) and waits for the user's explicit approval before the first build dispatch. Trivial, explicit, low-risk requests remain self-approving — no artificial gate is created.
+- **Per-feature `tasks[]` ledger** — each feature in `feature-list.json` can carry a `tasks[]` array (`id`, `title`, `workType`, `files`, `expectedOutcome`, `validation`, `state`) so any agent can resume mid-build knowing what a task was, what it touches, what "done" looks like, and how to validate it. `forge-worker` owns the schema.
+- **Claude Code skill frontmatter** — canonical artifacts can now set `claude.when_to_use`, `claude.model`, and `claude.user-invocable` (Claude Code now supports `model` on skills, not just agents). Applied to the three artifacts that render as Claude Code skills: `forge` and `forge-grill` runs on `opus`, `forge` is the only one left user-invocable; `using-forge` run on `sonnet` and are set (along with `forge-grill`) `user-invocable: false` (Claude still loads them automatically; they no longer appear in the `/` menu or run as standalone commands).
+
+### Changed
+
+- **`forge-worker` frontmatter** — Claude adds `Agent`; Grok adds `task`, `get_task_output`, `kill_task`; OpenCode adds `task: allow`.
+- **README** — corrects outdated claim that Claude subagents cannot spawn subagents. Nested sub-agents are supported since Claude Code v2.1.172 (platform max 5 levels); Forge caps at depth 2 by cross-harness policy.
+- **`using-forge`**, **`forge`**, **`forge-grill`**, **`forge-adversary`** — document two-tier worker model and Codex `DELEGATION_REQUESTS` fan-out fallback.
+- **Route announcement** — for non-trivial work, the announcement is now followed by the pre-build approval brief; re-announcing mid-flight also re-triggers approval.
+- **`forge-worker` plan/build modes** — plan populates `tasks[]`; build flips task `state` (`not_started -> active -> done`) as it works. Task `done` is distinct from feature `state`, which only a verify dispatch can move to `passing`.
+- **`forge-adversary`** — cross-checks that each task's `validation` was actually satisfied, not just the feature's top-level `verification` command.
+- **`progress.md` / `session-handoff.md` templates** — now reference the active `<feature-id>/<task-id>` so a resuming agent finds its place immediately.
+- **`renderClaudeSkill`** — no longer drops the `model` field for Claude Code skills; it now validates it against known Claude models the same way `renderClaudeAgent` does.
+
+### Migration from 0.5.0
+
+- Run `npx @guidobuilds/forge-ai update` to install `forge-worker-leaf` and refresh coordinator artifacts. Requires Claude Code **v2.1.172+** for structural sub-delegation on Claude.
+
+## [0.5.0] - 2026-06-20
+
+### Added
+
+- **Grok Build (`--platform grok`) as a first-class target.** `forge`, `forge-grill`, and `using-forge` install as Grok skills under `.grok/skills/<name>/SKILL.md`; `forge-worker` and `forge-adversary` install as Grok subagents under `.grok/agents/<name>.md`. Grok's built-in tool IDs (`run_terminal_cmd`, `grep_search`, `search_replace`, etc.) are used in the worker and adversary toolsets, replacing the Claude-specific names. Included in `--platform all`. Grok Build v0.2.56+ required.
+
+### Changed
+
+- **Orchestrator route announcement**: before the first dispatch, the orchestrator now states the chosen route to the user — work types joined by arrows (e.g. `build -> verify`, `inspect -> build -> verify`, `inspect -> design -> plan -> build -> verify`), whether a `forge-grill` pass runs before build and an independent verify or `forge-adversary` gate runs after, and one clause on why it is the lightest safe route. Re-announced only when the route changes materially mid-flight.
+- **Proactive `forge-grill`**: the orchestrator now runs `forge-grill` proactively before build for non-trivial, risk-bearing, or multi-step work with unresolved assumptions. Previously grill was effectively opt-in (user-triggered via `/forge-grill`). Trivial, surgical, and read-only work still skips grill.
+
+### Migration from 0.4.0
+
+- Run `npx @guidobuilds/forge-ai update` to add the new `forge-grill` and `using-forge` prompt changes and the Grok Build artifacts. No breaking changes to the CLI, state files, or existing Claude/OpenCode/Codex installs.
+
+## [0.4.0] - 2026-06-16
+
+### Added
+
+- **Adaptive `.forge/<feature-slug>/` state model** for the orchestration harness, sized to task complexity. Trivial work stays on the `build -> verify` path with no artifacts; non-trivial or multi-session work gains a structured state ledger. Documented in `using-forge` (routing tiers + triggers) and `forge-worker` (schema + templates). No distribution-engine change — the state files are runtime-generated by the worker.
+- **`feature-list.json` feature-list primitive**: the unit-of-work ledger where each feature carries the triple `behavior` + `verification` (a runnable command) + `state` (`not_started | active | blocked | passing`), plus `evidence` and `dependencies`.
+- **Definition of Done with verification-evidence gating**: a feature reaches `passing` only after its verification command was actually run and recorded in `verification.md`; never on assertion alone.
+- **Independent verification**: for non-trivial work the builder may not self-certify; the orchestrator dispatches a separate `forge-worker` verify run that re-runs the checks and flips state.
+- **`forge-adversary` agent — dedicated post-build red-team gate.** A new subagent (`kind: agent`; OpenCode subagent, Claude agent) the orchestrator dispatches *after* build to break a worker's output across four lenses (logical/requirements, technical/runtime, security, performance/scale). It writes reproductions under `.forge/<slug>/adversary/`, records every attempt in `verification.md`, and gates the Definition of Done — a confirmed, reproducible break moves the feature to `blocked`; it never edits the implementation under test. Reports `WORK_TYPE: verify`, so the worker contract is unchanged. Complements `forge-grill` (which grills plans/designs *before* build). `forge`, `using-forge`, and `forge-worker` updated to dispatch it for risk-bearing work.
+- **Persisted handoff/progress**: `progress.md` and `session-handoff.md` templates for cross-session continuity, created adaptively when work spans sessions or blocks.
+- `forge-ai self-update` command. Detects how the CLI is installed (pnpm global, npm global, Homebrew npm, npx, or unknown) and runs the right update command with the right flags (`--prefer-online` for pnpm to sidestep its metadata cache). After updating the binary it automatically runs `forge-ai update` to refresh the spec kit. Flags: `--to <version>` to pin a specific version, `--dry-run` to preview, `--skip-spec-update` to only bump the CLI.
+- Background version check on every interactive run. Calls the npm registry (with 1.5s timeout, cached for 1h at `~/.forge-ai/version-check.json`) and prints `forge-ai vX.Y.Z (vA.B.C available — run \`forge-ai self-update\` to upgrade)` when a newer version exists. Silent on failure; never blocks the command.
+- `--no-update-check` CLI flag and `FORGE_NO_UPDATE_CHECK=1` env var to opt out of the version check. Also auto-skipped in CI (`CI=true`) and non-interactive runs.
+- README "How to Use" section explaining how to invoke Forge per platform: `/forge` skill on Claude Code (with `forge-worker` as a delegated subagent), `forge` primary agent on OpenCode, and the partial `.toml` agents on Codex — including the Claude advisory-vs-OpenCode-enforced trade-off.
+- **Feedback ratchet — `.forge/lessons.md`**: a project-scoped, topic-keyed lessons file the worker proactively appends to after each run (decision / non-obvious fix / convention / failure). Reusing a topic-key updates an existing lesson instead of creating a contradictory duplicate, so the harness compounds across sessions instead of repeating mistakes.
+- **Bootstrap repo-facts — `.forge/repo-facts.md`**: a one-time `inspect`-written standing spec (stack, build/test/lint commands, conventions, hard constraints) the worker rereads each dispatch, paying the intent/reconstruction cost once.
+- **Closure + cross-task index — `.forge/index.md` and `.forge/_archive/`**: on `passing`, the verify dispatch flushes lessons and appends a one-line ledger entry; completed slugs may be archived. Each feature carries a falsifiable `archiveWhen` condition set at creation.
+- **Effort routing**: the orchestrator now states an effort level per worker dispatch (low for `inspect`/`verify`/`operate`/routine `build`, medium for most `build`/`plan`, high for `design`/synthesis/novel work) — match effort to difficulty rather than defaulting high.
+- **Inline-vs-delegate threshold**: the orchestrator handles inline only a 1-3 file read / mechanical write / git status, and delegates at 4+ files, multi-file writes, or running tests/builds/installs — keeping the thread thin (summaries, not implementations).
+- **Optional hooks pack** (README): an opt-in Claude Code `settings.json` snippet (Stop + PostToolUse) to *enforce* the verification gate mechanically for unattended runs — kept thin and optional, since strong models honor the gate from the operating model alone.
+- **Harness-content validation**: `validate`/`install` emit a `BODY_OVER_BUDGET` info diagnostic when an artifact body exceeds its soft line budget (keep always-loaded files small). Never an error; does not block installs.
+
+### Changed
+
+- **Independent verification is now adversarial.** The separate `forge-worker` verify dispatch tries to *disprove* "done" rather than confirm it: it refutes risk-bearing features across up to three distinct lenses and keeps `passing` only if at least two fail to refute; confirms the check was not weakened, deleted, skipped, or stubbed and that its output exercises the named `behavior`; logs refuted/uncertain candidates instead of dropping them silently; and escalates instead of looping when the same failure recurs. The Definition of Done in `using-forge` and the verify/build modes in `forge-worker` are updated to match; `feature-list.json` gains an `archiveWhen` field.
+
+### Migration from 0.3.0
+
+- Run `npx @guidobuilds/forge-ai update` (not `install`) to add the new `forge-adversary` agent and refresh the `forge`, `using-forge`, and `forge-worker` artifacts to the adversarial-verification operating model. Local edits to managed files are backed up automatically to `~/.forge-ai/backups/`.
+- No breaking changes to the CLI or distribution layout. The `.forge/<feature-slug>/` state files (`feature-list.json`, `verification.md`, `lessons.md`, `repo-facts.md`, `index.md`, handoff/progress) are runtime-generated by the worker — nothing to migrate by hand.
+- If you installed the CLI globally, `forge-ai self-update` (new in 0.4.0) bumps the binary and then refreshes the spec kit for you.
+
 ## [0.3.0] - 2026-05-15
 
 ### Added

package/README.md

@@ -2,7 +2,7 @@
 
 Forge is a personal project for working with code agents more reliably.
 
-It started as a way to get better results from OpenCode, and now also supports Codex and Claude Code. The idea is to give agents a lightweight operating model for turning vague software requests into smaller, safer, verifiable changes without adding a heavy process around them.
+It started as a way to get better results from OpenCode, and now also supports Claude Code, Codex and Grok Build. The idea is to give agents a lightweight operating model for turning vague software requests into smaller, safer, verifiable changes without adding a heavy process around them.
 
 Forge is experimental. It is shaped by hands-on use, and the workflow may change as I learn what works and what does not.
 
@@ -49,6 +49,8 @@ build -> verify
 
 There is no mandatory lifecycle. Forge tries to choose the lightest safe path based on the task, risk, and available context.
 
+Before delegating, the orchestrator states the chosen route to the user — the work types it plans to run, whether `forge-grill` runs before build, and why it is the lightest safe path for that request. For non-trivial work, it then presents an approval brief — conclusions, planned tasks, why — and waits for an explicit go-ahead before the first build dispatch.
+
 ## Durable Context
 
 When a task benefits from persistent context, Forge writes notes under `.forge/<feature-slug>/`.
@@ -62,6 +64,23 @@ These notes are useful for:
 
 Small, obvious changes do not need ceremony. The goal is to use durable artifacts only when they reduce ambiguity or risk.
 
+### State model for non-trivial work
+
+For non-trivial or multi-session work, Forge keeps a small state model under `.forge/<feature-slug>/`, sized to the task:
+
+- `feature-list.json` — the unit-of-work ledger. Each feature carries the triple `behavior` + `verification` (a runnable command) + `state` (`not_started | active | blocked | passing`), plus a `tasks[]` execution ledger (title, files, expected outcome, validation, state) so any agent can resume mid-build.
+- `verification.md` — recorded verification evidence: the command, its output, and a pass/fail verdict.
+- `progress.md` / `session-handoff.md` — session continuity and handoff, written when work spans sessions or blocks.
+
+Before build starts on non-trivial work, Forge presents an approval brief — conclusions, the planned tasks, and why — and waits for an explicit go-ahead; a finished plan does not authorize build by itself.
+
+Two rules make "done" mean done:
+
+- **Definition of Done.** A feature only reaches `passing` once its verification command was actually run and the evidence is recorded in `verification.md`. No feature is marked done on assertion alone.
+- **Independent verification.** For non-trivial work the builder does not certify its own work. The orchestrator dispatches a separate `forge-worker` verify run that re-runs the checks and flips the state.
+
+Trivial, surgical changes skip all of this and stay on the `build -> verify` path.
+
 ## Supported Agents
 
 Forge currently installs support for:
@@ -69,6 +88,7 @@ Forge currently installs support for:
 - OpenCode
 - Codex
 - Claude Code
+- Grok Build
 
 The same operating model is shared across all supported agents so the workflow stays mostly consistent even when the underlying tool changes.
 
@@ -106,6 +126,99 @@ Validate a local Forge source tree:
 npx @guidobuilds/forge-ai validate --source .
 ```
 
+## How to Use
+
+Forge installs the **same operating model** on every agent, but **how you invoke it differs per platform**, because each agent exposes different primitives (skills, subagents, agent switching). The installer is only step one — this section is how you actually drive Forge once it is installed.
+
+### The pieces
+
+Forge is one orchestrator, a two-tier worker model, and a dedicated adversary, with two supporting skills:
+
+- **`forge`** — the orchestrator. It talks to you, decides how much process a task needs, and delegates the real work. It does not edit code itself.
+- **`forge-worker`** — the coordinator worker. It executes bounded subgoals and spawns `forge-worker-leaf` when context would grow too large (~100k-token peak).
+- **`forge-worker-leaf`** — the terminal worker. It runs one bounded shard with no sub-delegation.
+- **`forge-adversary`** — the breaker. After a build, the orchestrator dispatches it to *try to break* the work — logically and technically (logic/requirements, runtime, security, performance). It gates the Definition of Done: a confirmed, reproducible break keeps the feature out of `passing`. It complements `forge-grill`, which grills plans *before* building.
+- **`using-forge`** — the shared operating-model skill the orchestrator follows.
+- **`forge-grill`** — an orchestrator mode for stress-testing a plan or design before building. The orchestrator invokes it proactively before non-trivial or risk-bearing builds; also available as `/forge-grill` for manual use.
+
+What changes per platform is the **kind** each piece is installed as, and therefore how you trigger it.
+
+### Claude Code
+
+| Piece | Installed as | How you invoke it |
+|---|---|---|
+| `forge` | skill (`model: opus`) | type `/forge` in the prompt — the only Forge skill you invoke directly |
+| `forge-grill` | skill (`model: sonnet`, not user-invocable) | loaded automatically by `forge` before non-trivial or risk-bearing builds |
+| `using-forge` | skill (`model: sonnet`, not user-invocable) | loaded automatically by `forge` before routing work |
+| `forge-worker` | subagent | coordinator; main thread delegates via `Agent` (or legacy `Task`) |
+| `forge-worker-leaf` | subagent | terminal shard; spawned by `forge-worker` (or orchestrator on Codex) |
+| `forge-adversary` | subagent | the orchestrator delegates to it after build to gate risk-bearing work |
+
+Start a session by typing **`/forge`**. That loads the orchestrator role into your main Claude Code thread, which delegates each bounded task to `forge-worker`, which may spawn `forge-worker-leaf` for heavy inspect/build shards. Requires **Claude Code v2.1.172+** for nested sub-agents. `forge-grill` and `using-forge` are marked `user-invocable: false`: Claude still loads and runs them as part of `forge`'s routing, but they no longer appear in the `/` menu or run as standalone commands — `forge` is the single entry point.
+
+> Why a skill and not an agent on Claude? The main thread retains `Agent`/`Task` and can delegate. A skill injects orchestrator behavior without replacing the main agent. The trade-off: "delegate, never do worker work inline" is followed by instruction at the orchestrator layer, not by tool restrictions — but `forge-worker` **can** structurally spawn leaves when given `Agent` in its tool list.
+
+### OpenCode
+
+| Piece | Installed as | How you invoke it |
+|---|---|---|
+| `forge` | primary agent | switch your active agent to `forge` |
+| `forge-worker` | subagent | coordinator; `forge` delegates with `task: allow` |
+| `forge-worker-leaf` | subagent | terminal shard; spawned by coordinator (`task: deny`) |
+| `forge-adversary` | subagent | the `forge` agent delegates to it to gate risk-bearing work after build |
+| `using-forge`, `forge-grill` | skills | loaded by the agent as needed |
+
+Switch your primary agent to **`forge`**. Unlike Claude Code, the orchestrator here is a real agent with file and shell tools **denied**, so it is *structurally* forced to delegate to the `forge-worker` subagent instead of doing the work itself.
+
+### Codex
+
+| Piece | Installed as | Location |
+|---|---|---|
+| `forge`, `forge-worker`, `forge-adversary` | agents (`.toml`) | `~/.codex/agents/` (or `.codex/agents/` per project) |
+| `using-forge`, `forge-grill` | skills | `~/.agents/skills/` (or `.agents/skills/` per project) |
+
+Codex support is the most partial of the three: Forge writes the agent `.toml` files but does not generate `AGENTS.md` or profiles, so wiring them into a Codex run may take manual steps. Treat Codex support as experimental.
+
+### Project vs user scope
+
+### Grok Build
+
+| Piece | Installed as | How you invoke it |
+|---|---|---|
+| `forge` | skill | type `/forge` in the prompt |
+| `forge-grill` | skill | type `/forge-grill` |
+| `using-forge` | skill | `/using-forge` (usually pulled in by `/forge`) |
+| `forge-worker` | subagent | coordinator; main thread delegates via `task` |
+| `forge-worker-leaf` | subagent | terminal shard; spawned by coordinator |
+| `forge-adversary` | subagent | the orchestrator delegates to it after build to gate risk-bearing work |
+
+Start a session by typing **`/forge`**. Like Claude Code, the orchestrator runs as a skill in the main Grok session, which then delegates bounded work to the `forge-worker` subagent. Grok uses its own tool IDs (`run_terminal_cmd`, `grep_search`, `search_replace`, etc.) — the installer translates the worker's toolset automatically.
+
+> **Note:** Grok Build already auto-discovers skills and agents from `~/.claude/` for compatibility. If you have a Claude Code install, Grok may partially pick up those files — but with Claude tool names that Grok doesn't recognize. A native Grok install (`--platform grok`) writes `.grok/`-scoped files with the correct Grok tool IDs.
+
+### Project vs user scope
+
+With `--scope user` (the default) the definitions live under your home directory and apply everywhere. With `--scope project` they live in the repo (`.claude/`, `.opencode/`, `.codex/`, `.agents/`, `.grok/`) and apply only there. Invocation is identical either way.
+
+## Optional: enforce the gate with hooks (Claude Code)
+
+Forge's Definition of Done is followed by instruction, not enforced — strong models honor the gate from the operating model alone. If you want the verification gate enforced *mechanically* on Claude Code (e.g. for unattended runs), add an opt-in hook to your `.claude/settings.json`. Keep it thin: a safety net for the one invariant that must hold, not a compliance layer.
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      { "hooks": [ { "type": "command", "command": "<your project's verification command, e.g. pnpm test --silent>" } ] }
+    ],
+    "PostToolUse": [
+      { "matcher": "Write|Edit", "hooks": [ { "type": "command", "command": "<your fast type/lint check, e.g. pnpm typecheck>" } ] }
+    ]
+  }
+}
+```
+
+The **Stop** hook re-runs your checks when the agent tries to finish, so a failing gate blocks a premature "done"; the **PostToolUse** hook surfaces type/lint errors after each edit for mid-task self-correction. Point the Stop hook at fast unit checks and leave slow suites to CI. This is intentionally optional — reach for it only when you want the gate enforced without you in the room.
+
 ## Local Development
 
 Forge uses [pnpm](https://pnpm.io) for development (pinned via `packageManager` in `package.json`, so `corepack enable` is enough — no global install needed). The published package is still consumed by end users via `npx`/npm, unchanged.
@@ -126,10 +239,20 @@ node bin/forge-ai.mjs install --source . --platform all --scope project --dry-ru
 
 ## Updating
 
-Run the npm updater:
+If you have Forge installed globally, the simplest way is:
 
 ```sh
-npx @guidobuilds/forge-ai update
+forge-ai self-update
+```
+
+This detects how the CLI was installed (pnpm global, npm global, Homebrew npm, etc.) and runs the right upgrade command — including the `--prefer-online` flag that sidesteps pnpm's metadata cache when a new version was just published. After bumping the binary, it automatically runs `forge-ai update` to refresh the spec kit.
+
+Forge also pings the registry on every interactive run and prints a one-line notice when a newer version is available, so you don't have to remember to check.
+
+If you don't have a global install (running via `npx`):
+
+```sh
+npx @guidobuilds/forge-ai@latest update
 ```
 
 Forge replaces its managed agent and skill definitions in your supported agent configuration directories.

package/artifacts/forge/forge.md

@@ -4,6 +4,10 @@ description: Forge orchestrator with dynamic runtime routing and a single worker
 kind: agent
 claude:
   kind: skill
+  model: opus
+  when_to_use: Use for any development or operational task in this repo — build a feature, fix a bug, investigate code, plan work, or verify a change. This is the default entry point; invoke explicitly with /forge or let Claude select it automatically for repo work.
+grok:
+  kind: skill
 opencode:
   mode: primary
   permissions:
@@ -37,14 +41,29 @@ The `using-forge` skill owns runtime routing, operating principles, approval heu
 - Delegate all technical and operational work to Forge workers.
 - Keep one thin thread with the user.
 - Choose the lightest safe routing permitted by the skill.
+- Before the first dispatch, state the chosen route to the user (see `using-forge`: Route announcement).
+- Run `forge-grill` proactively before building non-trivial or risk-bearing work; do not wait for the user to ask (see `using-forge`: Routing rules).
+- For non-trivial work, present the pre-build approval brief (conclusions, path/tasks, why) and wait for the user's explicit approval before the first build dispatch; a finished plan does not by itself authorize build (see `using-forge`: Approval heuristics).
 - Enforce the Forge worker contract strictly.
+- Assign an effort level per dispatch and delegate by size (see `using-forge`: Effort routing, Routing rules).
 
 ## Worker model
-- `forge-worker` is the only worker type in Forge.
+- `forge-worker` is the coordinator worker; route all build and operational work to it at `DISPATCH_DEPTH: 1`.
+- `forge-worker-leaf` is the terminal worker for bounded shards at `DISPATCH_DEPTH: 2`; coordinators spawn it — or you fan out leaves when a coordinator returns `DELEGATION_REQUESTS` (Codex).
+- `forge-adversary` is a dedicated adversarial verification agent: dispatch it as the Definition-of-Done gate for risk-bearing work to break the build before it can reach `passing`. Never sub-delegate verify or adversary work.
 - You may launch one worker instance for a bounded task.
 - You may launch multiple `forge-worker` instances in sequence when one result should shape the next delegation.
 - You may launch multiple `forge-worker` instances in parallel when subgoals are sufficiently independent.
 - Keep each worker invocation narrowly scoped so multiple instances do not collide on the same ownership or files unless deliberate.
+- Tag heavy dispatches with `DELEGATION: allowed|required|forbidden`. Default trivial work to `forbidden`.
+
+## State model
+- Size the state model to the work. Keep trivial, surgical changes light: route `build -> verify` with no state artifacts.
+- For non-trivial or multi-session work, route through the `.forge/<feature-slug>/` state model defined in `using-forge`: maintain `feature-list.json` (behavior + verification + state) and persist `progress.md` / `session-handoff.md` when work spans sessions or blocks.
+- Non-trivial features carry a `tasks[]` ledger (title, files, expected outcome, validation, state) inside `feature-list.json` so any agent can resume mid-build; the builder flips task state as it works, but only verify flips a feature to `passing`.
+- A feature reaches `passing` only via recorded verification evidence (the Definition of Done in `using-forge`).
+- For non-trivial work, dispatch a separate verify run; never accept a builder's self-certified `passing`. Prefer `forge-adversary` for risk-bearing work and a `forge-worker` verify run otherwise — both must be a different instance than the builder.
+- Read `.forge/repo-facts.md` and `.forge/lessons.md` when present, and have the verify dispatch flush lessons and update `.forge/index.md` at closure (see `using-forge`).
 
 ## Contract enforcement
 Each worker response must include:
@@ -53,18 +72,24 @@ Each worker response must include:
 STATUS: success|partial|blocked
 WORK_TYPE: inspect|design|plan|build|operate|verify|mixed
 FEATURE_SLUG: <kebab-case>
+DISPATCH_DEPTH: 0|1|2
+WORKER_ROLE: coordinator|leaf
 ARTIFACTS:
 - <path or None>
 SUMMARY:
 - <point>
-NEXT_RECOMMENDED: inspect|design|plan|build|operate|verify|ask-user|none
+SUB_RESULTS:
+- task_id: <id> | status: success|partial|blocked | work_type: <type> | summary: <one line>
+DELEGATION_REQUESTS:
+- task_id: <id> | work_type: <type> | role: leaf | parallel: true|false | subgoal: <bounded> | files_hint: <paths or None>
+NEXT_RECOMMENDED: inspect|design|plan|build|operate|verify|sub-delegate|ask-user|none
 RISKS:
 - <risk or None>
 QUESTIONS:
 1) <question>
 ```
 
-`QUESTIONS` appears only when `STATUS: blocked`.
+`QUESTIONS` appears only when `STATUS: blocked`. On `DELEGATION_REQUESTS`, fan out `forge-worker-leaf` dispatches (Codex fallback). Trust coordinator `SUB_RESULTS` unless `partial` or `blocked`.
 
 If output is malformed:
 1) request one reformat retry with same task_id

package/artifacts/forge-adversary/forge-adversary.md

@@ -0,0 +1,124 @@
+---
+name: forge-adversary
+description: Forge adversarial breaker — attacks a worker's completed work logically and technically and gates `passing` on recorded evidence.
+kind: agent
+claude:
+  permissions:
+    tools: [TodoWrite, Read, Write, Edit, Bash, Glob, Grep, LS, MultiEdit, WebFetch]
+grok:
+  permissions:
+    tools: [todo_write, read_file, search_replace, run_terminal_cmd, grep_search, list_dir, web_fetch]
+opencode:
+  mode: subagent
+  permissions:
+    todowrite: allow
+    read: allow
+    write: allow
+    edit: allow
+    bash: allow
+    glob: allow
+    grep: allow
+    list: allow
+    patch: allow
+    skill: allow
+    webfetch: allow
+---
+
+# Forge Adversary
+
+## Role
+
+You are the Forge adversary: an independent red-team agent dispatched *after* a `forge-worker` has produced or changed work. Your job is to **break it** — logically and technically — not to confirm it. You did not build it, so you owe it no benefit of the doubt.
+
+You are the gate. A feature does not reach `passing` until you **fail** to break it with recorded evidence.
+
+You are distinct from the two existing adversarial mechanisms:
+- `forge-grill` grills *plans and designs before* build. You attack *built* work.
+- The universal `forge-worker` verify mode is a general check. You are the dedicated, specialized verify/break gate the orchestrator dispatches for risk-bearing work.
+
+## Inputs
+
+- Orchestrator prompt naming the `feature-slug` under attack, the requirement / acceptance criteria, the effort level, and what is out of scope
+- The artifacts the worker produced: code, files, and `.forge/<feature-slug>/` state
+- The `verification` command(s) and the relevant `feature-list.json` entries
+- Optional: `.forge/<feature-slug>/verification.md`, `design.md`, `plan.md`, `build-log.md`
+- Optional: `.forge/repo-facts.md` and `.forge/lessons.md`
+
+When state-model files exist, read them before acting and treat `feature-list.json` as the source of truth for what is in scope and its current state. When `.forge/repo-facts.md` or `.forge/lessons.md` exist, read them first so you reuse known facts and known weaknesses.
+
+## Core rules
+
+- **Independence**: you are a different instance than the builder. Never accept a self-certified `passing`.
+- **No sub-delegation**: run in a single skeptical context; never spawn sub-agents.
+- **Attack, do not repair**: you may write reproductions (failing tests, fuzz scripts, payloads) and state files, but you must NOT edit the implementation under test. Surface the breakage and leave the fix to a build dispatch.
+- **Evidence over assertion**: every claimed break must be reproducible — a command plus the observed failure — and recorded in `verification.md`. No break is real on assertion alone.
+- **Strict judging**: a break counts only if it violates a stated requirement or an invariant a reasonable user expects. Separate real defects from style nits and speculation.
+- **Minimum noise**: report the highest-severity, reproducible breaks first. Do not pad the report to look thorough.
+- **Honor the effort level** stated in the dispatch; escalate only when the surface warrants it.
+
+## Attack lenses
+
+Run the lenses that fit the target. For risk-bearing work cover at least Logical and Technical, then add Security and Performance as the surface warrants.
+
+### Logical / requirements
+
+- Map each stated requirement / acceptance criterion to concrete evidence it is met; flag gaps and over-delivery (scope creep).
+- Hunt contradictions, ambiguous acceptance criteria, and behaviors the build assumes but never states.
+- Enumerate edge cases the build ignores: empty, boundary, ordering, idempotency, repeated invocation, and concurrent intent.
+
+### Technical / runtime
+
+- Run the existing suite first; then craft adversarial inputs: empty, boundary, malformed, oversized, unexpected types and encodings.
+- Probe error handling and silent failures, invalid or partial states, and resource cleanup.
+- Check for regressions in adjacent behavior the change could disturb.
+- Write a failing reproduction test for each confirmed defect.
+
+### Security
+
+In scope only when the change crosses a trust boundary. Probe injection (SQL / command / path / template), input validation and sanitization, authz/authn bypass, secret and credential exposure, unsafe deserialization, and SSRF.
+
+### Performance / scale
+
+In scope only when the work has a load or scale dimension. Probe algorithmic complexity, degenerate and large-volume inputs, unbounded growth, N+1 or repeated work, and resource limits.
+
+## Gate authority
+
+You are the Definition-of-Done gate for the targeted feature(s), per the rules in `using-forge`.
+
+- For each targeted feature in `feature-list.json`, run its `verification` command AND your adversarial attacks.
+- Cross-check that each task's `validation` for the targeted feature was actually satisfied, not just the top-level `verification` command — a task marked `done` with unmet `validation` is a break; record it and flip the feature to `blocked`.
+- A confirmed, reproducible break moves the feature to `blocked` with a one-line reason and an `evidence` pointer.
+- For risk-bearing features, refute across up to three distinct lenses; keep `passing` only if at least two lenses fail to refute.
+- Record EVERY attempt — confirmed, refuted, and uncertain — in `verification.md` (command + output excerpt + verdict + timestamp).
+- Move a feature to `passing` only when your attacks fail to break it AND the Definition of Done in `using-forge` holds. Never weaken, delete, skip, or stub a check to make it pass.
+- You are not the builder: when you confirm breaks, set state, hand back, and recommend a build dispatch to fix. Do not fix it yourself.
+
+## Artifacts
+
+- Write reproductions under `.forge/<feature-slug>/adversary/` (failing tests, fuzz scripts, payloads, repro steps).
+- Record outcomes in `.forge/<feature-slug>/verification.md` — the Definition of Done store defined by `using-forge`.
+- Update `state` and `evidence` in `feature-list.json` only for the features you targeted.
+- At closure, flush durable lessons from confirmed breaks to `.forge/lessons.md` and append a line to `.forge/index.md`.
+
+## Contract (strict)
+
+Return exactly the Forge worker contract. Report `WORK_TYPE: verify` — you are the specialized verify dispatch, so the shared contract and work types stay unchanged.
+
+```text
+STATUS: success|partial|blocked
+WORK_TYPE: verify
+FEATURE_SLUG: <kebab-case>
+ARTIFACTS:
+- <path or None>
+SUMMARY:
+- <point>
+NEXT_RECOMMENDED: inspect|design|plan|build|operate|verify|ask-user|none
+RISKS:
+- <risk or None>
+QUESTIONS:
+1) <question>
+```
+
+`STATUS: success` means you could not break it and it passed the Definition of Done. `STATUS: partial` or `blocked` means you confirmed at least one break; set the feature accordingly and recommend `build` to fix. Use `QUESTIONS` only when `STATUS: blocked` on a decision only the user can resolve.
+
+If your own output is malformed, reformat once on the same task; if malformed again, stop with an actionable error.

package/artifacts/forge-grill/forge-grill.md

@@ -2,19 +2,24 @@
 name: forge-grill
 description: Stress-test a plan or design through Forge orchestration, batching user questions while delegating codebase-answerable work to forge-worker.
 kind: skill
+claude:
+  model: sonnet
+  when_to_use: Invoked by the forge orchestrator itself before non-trivial or risk-bearing build work, not directly by the user — surfaces unresolved assumptions, edge cases, and risks in a plan before implementation starts.
+  user-invocable: false
 ---
 
 # Forge Grill Skill
 
 ## Role
 
-Use this skill when the user wants Forge to stress-test, challenge, or "grill" a plan, design, proposal, or implementation approach.
+Use this skill when the user wants Forge to stress-test, challenge, or "grill" a plan, design, proposal, or implementation approach — or when the orchestrator proactively decides to grill before build (non-trivial, risk-bearing, or multi-step work with unresolved assumptions; see `using-forge`: Routing rules).
 
 You are still the Forge orchestrator: keep the user thread thin, delegate technical and operational work to `forge-worker`, and use the lightest safe workflow that reaches shared understanding.
 
 ## Core behavior
 
 - Build a decision tree for the plan or design under review.
+- If a `.forge/<feature-slug>/feature-list.json` exists, focus the decision tree on features that are not yet `passing`.
 - Resolve dependencies between decisions in an order that prevents rework.
 - Challenge assumptions, edge cases, scope boundaries, sequencing, risks, and validation strategy.
 - Prefer shared understanding over volume: ask the fewest high-leverage questions that close the next meaningful branch.
@@ -41,6 +46,8 @@ Use `forge-worker` for:
 - implementation-plan consistency checks
 - technical risk investigation
 
+Grill inspect workers may return `DELEGATION_REQUESTS`; fan out `forge-worker-leaf` the same way as the main orchestrator.
+
 Keep each worker prompt bounded and explicit about:
 
 - the plan/design branch being tested
@@ -89,5 +96,5 @@ If a worker response is malformed, request one reformat retry for the same task.
 - Be direct and rigorous, but not performative.
 - Explain why each question matters.
 - Include recommendations in actionable language, such as "Recommended: choose A because...".
-- Make unresolved risk visible before moving to build, plan, or approval-seeking work.
+- Make unresolved risk visible before moving to build, plan, or the pre-build approval brief (see `using-forge`: Approval heuristics) — grill findings and the plan's `tasks[]` are exactly what that brief presents.
 - If grilling reveals implementation work is needed, route it through the normal Forge worker model instead of doing it inline.