@guidobuilds/forge-ai 0.2.0 → 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,107 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Versions prior to 0.3.0 are not reconstructed here; see git history for earlier changes.
+
+## [Unreleased]
+
+## [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
+
+- Unified canonical **artifact** model: all sources live under `artifacts/<name>/<name>.md` and declare `kind: agent | skill` in frontmatter. Each per-platform block can override `kind`, so one artifact renders as an agent on one platform and a skill on another.
+- `forge` orchestrator installs as a Claude Code **skill** (`/forge`) on Claude Code, while remaining a primary agent on OpenCode and Codex. This fixes the previous setup where `forge` was installed as a Claude subagent and could not delegate to `forge-worker` (Claude subagents cannot call `Task`).
+- Installer **classifies each destination** as one of `new`, `managed-unmodified`, `managed-modified`, or `foreign`, and prints the status next to each file (`[refresh]`, `[overwrite, backup -> …]`, `[foreign overwrite]`, `[new]`).
+- **Automatic backups** of user-edited Forge files before overwrite or prune, stored under `~/.forge-ai/backups/<scope>/<ISO-timestamp>/<relative-path>`. A single timestamp directory groups all backups from one run.
+- **Combined confirmation prompt** in interactive mode listing every file that needs the user's decision (edited overwrites, edited deletions, foreign overwrites) with the destination backup directory.
+- Non-interactive installs refuse with exit code 1 when there are edited or foreign files and neither `--yes` nor `--force` is set, instead of silently overwriting.
+- New diagnostic codes: `MANAGED_FILE_OVERWRITE`, `FOREIGN_FILE_OVERWRITE`, `MISSING_KIND`, `INVALID_KIND`, `INVALID_PLATFORM_KIND`, `OPENCODE_MODE_ON_SKILL`, `SUPPORT_FILES_NOT_COPIED`.
+- Claude tool and model validation (`src/adapters/claude-known.ts`): unknown tools/models in agent frontmatter emit warnings instead of being silently accepted.
+- Skill source directories now allow sibling files (groundwork for future support-file bundling); detected files emit an `info` diagnostic noting that copying is not yet implemented.
+
+### Changed
+
+- Source layout: `agents/` and `skills/` directories are gone; everything moved to `artifacts/<name>/<name>.md`.
+- `forge-worker` agent and `forge-worker` skill (previously two files with the same name in separate namespaces) merged into a **single** `forge-worker` artifact rendered as a subagent on every platform. The artificial "thin agent loads a skill" indirection is removed.
+- `package.json` `files` now ships `artifacts/` instead of `agents/` + `skills/`.
+- Refreshing a managed-unmodified file is **silent** — no warning emitted. Previously every existing destination produced an indiscriminate `OVERWRITE_FORCED`.
+- Stale-managed files the user edited are now **backed up and deleted** during `update` (when `--yes`/`--force`); previously they were left on disk with a `CHECKSUM_MISMATCH` warning. Interactive runs prompt before backing up + deleting.
+- OpenCode `permissions` keys switched from boolean (`true`/`false`) to explicit strings (`allow`/`deny`); orchestrator now explicitly denies file/code operations.
+- Adapters consume a unified `CanonicalArtifact` type (with `body` field) instead of separate `CanonicalAgent`/`CanonicalSkill` types.
+- Frontmatter parsing now uses the `yaml` library (replaces the hand-rolled parser), with stricter spec compliance and better edge-case handling (colons in descriptions, horizontal rules in bodies, BOM, CRLF).
+- Claude agent `tools` and skill `allowed-tools` are emitted as comma-separated strings (matches Claude Code's native format).
+- Development tooling migrated from npm to **pnpm**: `packageManager: "pnpm@11.1.1"` pinned via Corepack (no global install needed); `pnpm.onlyBuiltDependencies: []` allowlist is explicit so postinstall script blocking is documented behavior. The published package is unaffected — consumers still install via `npx`.
+
+### Removed
+
+- `CanonicalAgent` and `CanonicalSkill` types (replaced by `CanonicalArtifact`).
+- `agents/` and `skills/` source directories.
+- `DESTINATION_EXISTS` error and `OVERWRITE_FORCED` warning (replaced by status-aware `MANAGED_FILE_OVERWRITE` and `FOREIGN_FILE_OVERWRITE`).
+- `CHECKSUM_MISMATCH` warning during prune (the file is now backed up and deleted on consent).
+- `package-lock.json` (replaced by `pnpm-lock.yaml`).
+
+### Fixed
+
+- `forge` orchestrator deployment to Claude Code now actually works: it is installed as a `/forge` skill in the main thread, which retains the `Task` tool and can delegate to the `forge-worker` subagent. The previous subagent install was inert because Claude subagents cannot call `Task`.
+- Installer no longer raises spurious overwrite warnings for files Forge installed itself and that have not been edited.
+
+### Security
+
+- Migrated the development workflow to pnpm. pnpm 10+ **blocks postinstall scripts by default** (`onlyBuiltDependencies` allowlist), enforces strict `node_modules` (no phantom dependencies), and uses an auditable text lockfile (`pnpm-lock.yaml`). The npm registry is the same, but install-time defaults are hardened.
+- User edits to Forge-managed files are **always backed up** before being overwritten or deleted, eliminating silent data loss when running `update` against a customized install.
+
+### Migration from 0.2.0
+
+- Run `npx @guidobuilds/forge-ai update` (not `install`) after upgrading. `update` prunes the now-orphaned `.claude/agents/forge.md` and the old standalone `forge-worker` skill from the previous layout. Local edits to any of those files are backed up automatically to `~/.forge-ai/backups/`.
+- `install` (without `update`) will leave the orphaned files on disk. They are harmless but unmanaged.

package/README.md

@@ -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.
+
 ## Durable Context
 
 When a task benefits from persistent context, Forge writes notes under `.forge/<feature-slug>/`.
@@ -62,6 +64,21 @@ 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`).
+- `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.
+
+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 +86,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,13 +124,104 @@ 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 universal worker, 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 worker. It does the inspect / design / plan / build / operate / verify work in its own context and reports back. This is what keeps the orchestrator's context clean.
+- **`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 | type `/forge` in the prompt |
+| `forge-grill` | skill | type `/forge-grill` |
+| `using-forge` | skill | `/using-forge` (usually pulled in by `/forge`) |
+| `forge-worker` | subagent | the main thread delegates to it; or say "use the forge-worker subagent" |
+| `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 then delegates each bounded task to the `forge-worker` subagent (via the Task tool), keeping your main conversation thin.
+
+> Why a skill and not an agent on Claude? A Claude Code subagent cannot itself spawn subagents (it has no Task tool), so the orchestrator has to live in the main thread — and the way you inject behavior into the main thread is a skill. The trade-off: the "delegate, never do worker work inline" discipline is followed by instruction, not enforced by tool restrictions, because a skill cannot remove tools from the main thread.
+
+### OpenCode
+
+| Piece | Installed as | How you invoke it |
+|---|---|---|
+| `forge` | primary agent | switch your active agent to `forge` |
+| `forge-worker` | subagent | the `forge` agent delegates to it |
+| `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 | the main thread delegates to it via the `task` tool |
+| `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.
+
 From a local checkout:
 
 ```sh
-npm install
-npm run build
+pnpm install
+pnpm run build
 node bin/forge-ai.mjs install --source . --platform all --scope user
 ```
 
@@ -124,16 +233,28 @@ 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.
 
 Forge records installed files in manifests under `~/.forge-ai/` so updates can safely remove files that are no longer bundled. `update` prunes stale managed files by default only when the current file still matches the recorded checksum; use `--no-prune` to keep stale managed files. `--dry-run` previews writes and deletes without changing files or manifests.
 
+Forge now routes a single canonical artifact to the right artifact kind per agent: the orchestrator installs as a Claude Code skill (`/forge`) but as an agent on OpenCode and Codex. If you installed an earlier version, run `update` (not `install`) so Forge prunes the now-stale `forge` agent and standalone `forge-worker` skill left by the previous layout.
+
 ## Uninstalling
 
 Remove Forge from the agent configuration directories for OpenCode, Codex, or Claude Code by deleting the installed Forge agent and skill entries.

package/artifacts/forge/forge.md

@@ -0,0 +1,84 @@
+---
+name: forge
+description: Forge orchestrator with dynamic runtime routing and a single worker type
+kind: agent
+claude:
+  kind: skill
+grok:
+  kind: skill
+opencode:
+  mode: primary
+  permissions:
+    task: allow
+    question: allow
+    todowrite: allow
+    read: deny
+    write: deny
+    edit: deny
+    bash: deny
+    glob: deny
+    grep: deny
+    list: deny
+    patch: deny
+    skill: allow
+    webfetch: deny
+---
+
+# Role
+You are Forge, the Forge orchestrator.
+
+Load and follow the `using-forge` skill before routing work.
+
+You are a coordinator, not an executor.
+
+The `using-forge` skill owns runtime routing, operating principles, approval heuristics, artifact conventions, concurrency guidance, and shared definitions.
+
+## Orchestrator rules
+- Never do worker work inline.
+- Never do non-development execution work inline.
+- 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).
+- 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 universal worker type; route all build and operational work to it.
+- `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`.
+- 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.
+
+## 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.
+- 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:
+
+```text
+STATUS: success|partial|blocked
+WORK_TYPE: inspect|design|plan|build|operate|verify|mixed
+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>
+```
+
+`QUESTIONS` appears only when `STATUS: blocked`.
+
+If output is malformed:
+1) request one reformat retry with same task_id
+2) if malformed again, stop with actionable error

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

@@ -0,0 +1,122 @@
+---
+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`.
+- **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.
+- 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/{skills/forge-grill/SKILL.md → artifacts/forge-grill/forge-grill.md}

@@ -1,19 +1,21 @@
 ---
 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
 ---
 
 # 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.