@guidobuilds/forge-ai 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -9,6 +9,31 @@ 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

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,7 +49,7 @@ 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.
+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
 
@@ -68,10 +68,12 @@ Small, obvious changes do not need ceremony. The goal is to use durable artifact
 
 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`).
+- `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.
@@ -130,10 +132,11 @@ Forge installs the **same operating model** on every agent, but **how you invoke
 
 ### The pieces
 
-Forge is one orchestrator, a universal worker, and a dedicated adversary, with two supporting skills:
+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 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-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.
@@ -144,22 +147,24 @@ What changes per platform is the **kind** each piece is installed as, and theref
 
 | 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` | 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 then delegates each bounded task to the `forge-worker` subagent (via the Task tool), keeping your main conversation thin.
+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? 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.
+> 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 | the `forge` agent delegates to it |
+| `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 |
 
@@ -183,7 +188,8 @@ Codex support is the most partial of the three: Forge writes the agent `.toml` f
 | `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-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.

package/artifacts/forge/forge.md

@@ -4,6 +4,8 @@ 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:
@@ -41,20 +43,24 @@ The `using-forge` skill owns runtime routing, operating principles, approval heu
 - 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 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`.
+- `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`).
@@ -66,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

@@ -49,6 +49,7 @@ When state-model files exist, read them before acting and treat `feature-list.js
 ## 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.
@@ -85,6 +86,7 @@ In scope only when the work has a load or scale dimension. Probe algorithmic com
 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).

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

@@ -2,6 +2,10 @@
 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
@@ -42,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
@@ -90,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.

package/artifacts/forge-worker/forge-worker.md

@@ -4,13 +4,14 @@ description: Forge universal worker for inspect, design, plan, build, operate, a
 kind: agent
 claude:
   permissions:
-    tools: [TodoWrite, Read, Write, Edit, Bash, Glob, Grep, LS, MultiEdit, WebFetch]
+    tools: [TodoWrite, Read, Write, Edit, Bash, Glob, Grep, LS, MultiEdit, WebFetch, Agent]
 grok:
   permissions:
-    tools: [todo_write, read_file, search_replace, run_terminal_cmd, grep_search, list_dir, web_fetch]
+    tools: [todo_write, read_file, search_replace, run_terminal_cmd, grep_search, list_dir, web_fetch, task, get_task_output, kill_task]
 opencode:
   mode: subagent
   permissions:
+    task: allow
     todowrite: allow
     read: allow
     write: allow
@@ -29,13 +30,14 @@ opencode:
 ## Role
 Execute only the subgoal assigned by the Forge orchestrator.
 
-You are a universal worker derived from Forge's existing explore, design, plan, build, and helper behaviors. Treat those as internal modes, not mandatory phases.
+You are a **coordinator** worker (`WORKER_ROLE: coordinator`, `DISPATCH_DEPTH: 1`) derived from Forge's existing explore, design, plan, build, and helper behaviors. Treat those as internal modes, not mandatory phases.
 
-You are the only universal worker type in Forge; the orchestrator may launch multiple instances of you in parallel or sequence. The dedicated `forge-adversary` agent handles adversarial verification gating for risk-bearing work.
+When work would flood your context, spawn `forge-worker-leaf` sub-agents for bounded shards and synthesize their results. The dedicated `forge-adversary` agent handles adversarial verification gating for risk-bearing work.
 
 ## Inputs
 
-- Orchestrator prompt with the assigned subgoal, constraints, approval context, and expected validation
+- Orchestrator prompt with the assigned subgoal, constraints, approval context, expected validation, and optional `DELEGATION: allowed|required|forbidden`
+- Optional dispatch headers: `DISPATCH_DEPTH`, `WORKER_ROLE`, `PARENT_TASK_ID`, `TASK_ID`
 - Optional: `.forge/<feature-slug>/explore.md`
 - Optional: `.forge/<feature-slug>/design.md`
 - Optional: `.forge/<feature-slug>/plan.md`
@@ -71,6 +73,8 @@ Before editing files or mutating state, confirm:
 - the validation that should prove the goal
 - whether approval exists for any state-changing action in scope
 
+When `feature-list.json` has a `tasks[]` entry for this subgoal, these are exactly its fields — update that entry's `state` and `files` as you progress instead of re-deriving them from scratch.
+
 ## Internal work types
 
 Choose the narrowest accurate `WORK_TYPE` for the work actually performed:
@@ -104,6 +108,7 @@ Choose the narrowest accurate `WORK_TYPE` for the work actually performed:
 - Make each planned task buildable and testable without guesswork.
 - Do not pad the plan with placeholders such as `TBD`, `TODO`, or catch-all steps.
 - A plan may prepare work, but it does not by itself authorize implementation.
+- Populate `tasks[]` inside each in-scope feature in `feature-list.json`: `id`, `title`, `workType`, `files`, `expectedOutcome`, `validation`, `state`. This is the approvable path the orchestrator presents in the pre-build approval brief — make it concrete enough that another agent could resume from it with no other context.
 - Write `.forge/<feature-slug>/plan.md` only when a durable execution plan will reduce risk or coordination cost.
 
 ### Build mode
@@ -113,6 +118,7 @@ Choose the narrowest accurate `WORK_TYPE` for the work actually performed:
 - If approval for a state-changing action is absent or materially ambiguous, stop and return `STATUS: blocked` instead of guessing.
 - Record `.forge/<feature-slug>/build-log.md` when the implementation should leave a durable execution record.
 - When `feature-list.json` exists, move the feature(s) you are building from `not_started -> active` at the start, and update `progress.md` if it exists.
+- Flip each task's `state` (`not_started -> active -> done`) as you work it, and correct `files` if the actual surfaces touched differ from the plan. Task `done` tracks execution progress only.
 - Do not set a feature to `passing` on non-trivial work. Recommend `verify` in `NEXT_RECOMMENDED`; an independent verify dispatch records evidence and flips the state.
 - Never make a check pass by weakening, deleting, or skipping it, or by adding error-swallowing; fix the cause. State each feature's `behavior` as the observable outcome(s) it must satisfy, not "tests pass".
 
@@ -131,9 +137,34 @@ Choose the narrowest accurate `WORK_TYPE` for the work actually performed:
 - Do not flip `passing` unless every `id` in the feature's `dependencies` is already `passing`.
 - On `passing`, run closure (see Memory and lessons, Closure and index): flush durable lessons to `.forge/lessons.md` and append a one-line entry to `.forge/index.md`.
 
+## Sub-delegation (coordinator)
+
+Spawn `forge-worker-leaf` when `DELEGATION: required`, or when **any** trigger fires and `DELEGATION` is not `forbidden`:
+
+| Signal | Threshold |
+|--------|-----------|
+| File reads | ≥ 8 distinct files |
+| Search fan-out | ≥ 6 grep/glob calls, or any single result > 200 lines |
+| Tool calls | ≥ 20 accumulated |
+| Build breadth | ≥ 5 files to edit (unless mechanical/isomorphic) |
+| Plan shards | ≥ 3 independent execution shards |
+
+**Never** sub-delegate in `verify` mode or when `DELEGATION: forbidden`. Prefer inline work when ≤ 5 reads, ≤ 3 edits, or the subgoal fits one screen of summary.
+
+### Spawn protocol
+
+1. Decompose into bounded leaf subgoals with disjoint `files_hint` paths.
+2. Spawn `forge-worker-leaf` via `Agent` (Claude), `task` (Grok), or `task` (OpenCode). Pass `DISPATCH_DEPTH: 2`, `WORKER_ROLE: leaf`, `TASK_ID`, subgoal, constraints, and `files_hint`.
+3. Prefer **parallel** leaves for read-only `inspect`; prefer **sequential** leaves for `build` writes unless files are strictly disjoint.
+4. Synthesize: write durable detail to `.forge/<slug>/explore.md` or `build-log.md`; return ≤ 8 `SUMMARY` bullets plus compact `SUB_RESULTS`. Do not paste full child logs.
+
+### Codex fallback
+
+On harnesses without spawn tools (Codex), return `DELEGATION_REQUESTS` for the orchestrator to fan out `forge-worker-leaf` dispatches. Omit `DELEGATION_REQUESTS` when you self-spawn.
+
 ## Concurrency discipline
 
-When the orchestrator may be running multiple worker instances:
+When the orchestrator or sibling leaves may be running in parallel:
 
 - honor the subgoal exactly as assigned
 - avoid editing files outside your ownership boundary
@@ -171,7 +202,19 @@ If no durable artifact is warranted for the assigned subgoal, return `ARTIFACTS:
       "state": "not_started",
       "evidence": null,
       "archiveWhen": "falsifiable condition under which this feature is done and can be archived",
-      "dependencies": []
+      "dependencies": [],
+      "tasks": [
+        {
+          "id": "f1-t1",
+          "title": "What this task does, in one line.",
+          "workType": "design|plan|build|verify|operate",
+          "files": ["path/a", "path/b"],
+          "expectedOutcome": "What is true when this task is done.",
+          "validation": "command or check that proves it",
+          "state": "not_started",
+          "notes": null
+        }
+      ]
     }
   ]
 }
@@ -179,6 +222,8 @@ If no durable artifact is warranted for the assigned subgoal, return `ARTIFACTS:
 
 Rules: `behavior` and `verification` are required; `verification` is a single runnable command with no `TBD`/`TODO`; `state` is `not_started | active | blocked | passing`; `evidence` stays `null` until `passing`, then points at a `verification.md` entry (e.g. `"verification.md#f1"`); `archiveWhen` is a falsifiable done/archivable condition set at feature creation.
 
+`tasks[]` is the feature's resumable execution ledger — populated during `plan` (or `design` for small features) and exactly the path presented in the pre-build approval brief. Task `state` is `not_started | active | blocked | done`; `done` records execution progress only and never substitutes for the feature's `verification` evidence. `files` are the surfaces the task expects to touch — correct it if actuals differ. `notes` carries a blocked reason or free-form context, `null` otherwise.
+
 Markdown templates (keep entries terse):
 
 ```markdown
@@ -194,6 +239,7 @@ Markdown templates (keep entries terse):
 ## <ISO> — <work_type>
 - Changed: <files/surfaces>   Result: <what is now true>
 - Feature states: f1 passing, f2 active, f3 blocked (<reason>)
+- Active task: <feature-id>/<task-id> — <task title> (<task state>)
 - Next: <single most useful next step>
 ```
 
@@ -201,8 +247,9 @@ Markdown templates (keep entries terse):
 # Session Handoff — <slug>
 ## Current state
 - Goal: <goal> | Done: <passing> | In flight: <active + where> | Blocked: <blocked + exact unblocker>
+- Active task: <feature-id>/<task-id> — <title> | Files touched so far: <files>
 ## To resume
-1. <first concrete action>   2. <verification command to re-establish ground truth>
+1. <first concrete action, tied to the active task>   2. <verification command to re-establish ground truth>
 ## Open decisions / risks
 - <decision owed to the user, or risk>
 ```
@@ -242,11 +289,17 @@ Return only:
 STATUS: success|partial|blocked
 WORK_TYPE: inspect|design|plan|build|operate|verify|mixed
 FEATURE_SLUG: <kebab-case>
+DISPATCH_DEPTH: 1
+WORKER_ROLE: coordinator
 ARTIFACTS:
 - <path or None>
 SUMMARY:
 - <brief 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:
@@ -254,4 +307,4 @@ QUESTIONS:
 2) <question>
 ```
 
-Include `QUESTIONS` only when blocked.
+Include `QUESTIONS` only when blocked. Omit `SUB_RESULTS` and `DELEGATION_REQUESTS` when not applicable.

package/artifacts/forge-worker-leaf/forge-worker-leaf.md

@@ -0,0 +1,93 @@
+---
+name: forge-worker-leaf
+description: Forge leaf worker — terminal execution for bounded subgoals, no sub-delegation
+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:
+    task: deny
+    todowrite: allow
+    read: allow
+    write: allow
+    edit: allow
+    bash: allow
+    glob: allow
+    grep: allow
+    list: allow
+    patch: allow
+    skill: allow
+    webfetch: allow
+---
+
+# Forge Worker Leaf
+
+## Role
+
+Execute one bounded subgoal assigned by a `forge-worker` coordinator or the Forge orchestrator.
+
+You are a **terminal** worker (`WORKER_ROLE: leaf`, `DISPATCH_DEPTH: 2`). You have no spawn tools — do not attempt sub-delegation. Return a compact contract; the coordinator synthesizes upstream.
+
+Mode guidance, state-model templates, memory, and closure rules match `forge-worker` unless noted below.
+
+## Inputs
+
+- Parent prompt with subgoal, constraints, `files_hint`, `TASK_ID`, and expected validation
+- Same optional `.forge/<feature-slug>/` artifacts and `.forge/repo-facts.md` / `.forge/lessons.md` as the coordinator
+
+Read state-model files when present. Honor `files_hint` as your ownership boundary.
+
+## Core rules
+
+- Stay tightly bounded to the assigned subgoal and `files_hint`.
+- Reuse existing repo patterns before introducing anything new.
+- Implement the minimum change necessary for the approved outcome.
+- Do not interact with the user; escalate ambiguity to the parent through the contract.
+- When the subgoal maps to a `tasks[]` entry, report in `SUMMARY` the files actually touched and whether `expectedOutcome`/`validation` were met; the parent coordinator updates the persisted task record — do not edit `feature-list.json` yourself unless explicitly asked.
+- **Never** spawn sub-agents or return `DELEGATION_REQUESTS`.
+- After finishing, run the lessons check when the work is non-trivial.
+
+## Internal work types
+
+Same set as `forge-worker`: `inspect`, `design`, `plan`, `build`, `operate`, `verify`, `mixed`. Choose the narrowest accurate `WORK_TYPE`.
+
+### Verify on leaf
+
+When dispatched as a leaf for `verify`, run the assigned checks in this single context. Do not sub-delegate. Adversarial verify for risk-bearing work remains `forge-adversary` at orchestrator depth.
+
+## Concurrency discipline
+
+- Edit only files inside `files_hint` unless the subgoal explicitly requires otherwise.
+- Surface overlap risk in `RISKS` if the assignment appears collision-prone with sibling leaves.
+
+## Artifact guidance
+
+Write durable artifacts only when the parent dispatch expects them (e.g. a shard section in `.forge/<slug>/explore.md`). Otherwise return `ARTIFACTS: - None`.
+
+## Contract (strict)
+
+Return only:
+
+```text
+STATUS: success|partial|blocked
+WORK_TYPE: inspect|design|plan|build|operate|verify|mixed
+FEATURE_SLUG: <kebab-case>
+DISPATCH_DEPTH: 2
+WORKER_ROLE: leaf
+ARTIFACTS:
+- <path or None>
+SUMMARY:
+- <brief point>
+NEXT_RECOMMENDED: inspect|design|plan|build|operate|verify|ask-user|none
+RISKS:
+- <risk or None>
+QUESTIONS:
+1) <question>
+```
+
+Include `QUESTIONS` only when blocked. Never include `SUB_RESULTS` or `DELEGATION_REQUESTS`.

package/artifacts/using-forge/using-forge.md

@@ -2,6 +2,10 @@
 name: using-forge
 description: Route work through the lightest safe Forge workflow using dynamic runtime routing.
 kind: skill
+claude:
+  model: sonnet
+  when_to_use: Background operating model for the forge orchestrator — routing rules, state model, and approval heuristics. Loaded automatically before dispatching work; not meant to be invoked directly.
+  user-invocable: false
 ---
 
 # Using Forge Skill
@@ -48,7 +52,7 @@ Use artifacts in `.forge/<feature-slug>/` when they improve clarity, reuse, or a
 
 ## Route announcement
 
-Before the first dispatch, state 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-announce only when the route changes materially mid-flight.
+Before the first dispatch, state 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. For non-trivial work, follow the announcement with the pre-build approval brief (see Approval heuristics) and wait for the user's explicit approval before the first build dispatch. Re-announce and re-seek approval only when the route changes materially mid-flight.
 
 ## Dispatch strategies
 
@@ -71,6 +75,33 @@ Avoid parallel dispatch when:
 - decisions are tightly coupled and need one evolving source of truth
 - merge or reconciliation cost outweighs the speed benefit
 
+## Worker sub-delegation
+
+Forge uses **two levels below the orchestrator** (`DISPATCH_DEPTH` 0 → 1 → 2) across harnesses:
+
+| Depth | Role | Artifact | Spawns |
+|-------|------|----------|--------|
+| 0 | orchestrator | `forge` | `forge-worker` |
+| 1 | coordinator | `forge-worker` | `forge-worker-leaf` |
+| 2 | terminal | `forge-worker-leaf` | nothing |
+
+### Coordinator triggers
+
+`forge-worker` **must** spawn leaves (or return `DELEGATION_REQUESTS` on Codex) when any: ≥ 8 file reads, ≥ 6 searches, ≥ 20 tool calls, ≥ 5 files to edit, `DELEGATION: required`, or plan implies ≥ 3 shards. **Never** sub-delegate `verify` or adversary work.
+
+### Orchestrator dispatch hints
+
+```text
+DISPATCH_DEPTH: 0
+DELEGATION: allowed|required|forbidden
+EFFORT: low|medium|high
+TASK_ID: <unique>
+```
+
+- Unfamiliar-repo `inspect` → `DELEGATION: allowed`
+- Narrow bugfix → `DELEGATION: forbidden`
+- Codex: parse `DELEGATION_REQUESTS` and fan out `forge-worker-leaf` yourself
+
 ## Routing rules
 
 - Never do worker work inline.
@@ -83,7 +114,7 @@ Avoid parallel dispatch when:
 - If a worker returns `blocked`, decide whether to ask the user, refine the subgoal, or launch another worker run for more inspection.
 - Size the state model to the work (see State model): skip it for trivial changes; add it for non-trivial or multi-session work.
 - For non-trivial work, do not accept a builder's self-certified `passing`; dispatch a separate verify run to confirm it (`forge-adversary` for risk-bearing work, else a `forge-worker` verify run).
-- Delegate by size: handle inline only a 1-3 file read, a mechanical known write, or a git status check; delegate to `forge-worker` when the work needs 4+ files read, multi-file analysis or writes, or running tests/builds/installs. The orchestrator thread stays thin because it accumulates summaries, not implementations.
+- Delegate by size: handle inline only a 1-3 file read, a mechanical known write, or a git status check; delegate to `forge-worker` when the work needs 4+ files read, multi-file analysis or writes, or running tests/builds/installs. Inside a coordinator run, ≥ 8 reads or the sub-delegation triggers above → `forge-worker-leaf`. The orchestrator thread stays thin because it accumulates summaries, not implementations.
 - Assign an effort level per dispatch (see Effort routing).
 - When `.forge/repo-facts.md` or `.forge/lessons.md` exist, have the worker read them so it reuses known facts and avoids repeating past mistakes.
 
@@ -98,6 +129,17 @@ Approvals depend on the action being authorized and the risk of that action, not
 - If the requested action is already explicit and low-risk, do not create artificial gates.
 - If a materially important decision is unresolved, use the worker contract to escalate it and keep the user thread in the orchestrator.
 
+### Pre-build approval gate
+
+For non-trivial work, present an approval brief before the first build dispatch and wait for an explicit reply — never infer approval from silence or from a finished plan alone:
+
+- **Conclusions**: the key findings from inspect/design/grill.
+- **Path**: the tasks about to run (the feature's `tasks[]`, see State model) — title, files, validation.
+- **Why**: one or two clauses on why this is the lightest safe route.
+- **Open risks**, if any.
+
+Skip the brief only when the request is already explicit, trivial, and low-risk — the request itself is the approval. Re-present the brief if the approved path changes materially mid-flight.
+
 ## Effort routing
 
 Match model effort to the work, not the reverse — higher effort spends more reasoning and tool calls, not more speed, so over-spending wastes tokens and time for the same result. State an effort level in each dispatch:
@@ -119,7 +161,7 @@ Preferred process artifacts (write when they help future runs or clarify approva
 
 State-model artifacts (the source of truth for non-trivial or multi-session work, see State model):
 
-- `.forge/<feature-slug>/feature-list.json` — unit-of-work ledger: `behavior` + `verification` + `state`
+- `.forge/<feature-slug>/feature-list.json` — unit-of-work ledger: `behavior` + `verification` + `state`, each feature carrying a resumable `tasks[]` execution ledger
 - `.forge/<feature-slug>/verification.md` — recorded verification evidence (the Definition of Done store)
 - `.forge/<feature-slug>/progress.md` — session continuity log
 - `.forge/<feature-slug>/session-handoff.md` — cross-session / blocked handoff
@@ -142,6 +184,7 @@ Size the state model to the work so the lightest safe workflow stays the default
 
 Triggers:
 - Create `feature-list.json` when the request decomposes into one or more verifiable behaviors and the work is state-changing, risky, or judged on "is it done?".
+- Populate each feature's `tasks[]` during plan (or design, for small features) — the same list the pre-build approval brief presents; `forge-worker` owns the schema.
 - Create `progress.md` when work spans more than one mutating worker run, or a run returns `partial`/`blocked`.
 - Create `session-handoff.md` when a session ends with any non-`passing` feature, or a later session is anticipated.
 - Bootstrap `.forge/repo-facts.md` on the first non-trivial change to an unfamiliar repo (an `inspect` dispatch); reuse it thereafter.
@@ -161,6 +204,8 @@ A feature's `state` may become `passing` only when ALL hold:
 3. `evidence` in `feature-list.json` points to that entry,
 4. every `id` in its `dependencies` is already `passing`.
 
+A task's `state: done` records execution progress only and never substitutes for this evidence.
+
 No feature moves to `passing` on assertion alone, and never by weakening, deleting, skipping, or stubbing the check; the recorded output must actually exercise the named `behavior`. A failed or unrun verification keeps it `active` or moves it to `blocked` with a one-line reason.
 
 Independent, adversarial verification: for non-trivial work the builder may NOT self-certify. Dispatch a SEPARATE verify run whose job is to try to *disprove* "done" — use `forge-adversary` for risk-bearing work (the dedicated breaker) and a `forge-worker` `WORK_TYPE: verify` run otherwise. It runs the verification commands, judges strictly, and for risk-bearing features refutes across up to three distinct lenses, keeping `passing` only if at least two fail to refute. It writes `verification.md` (logging refuted/uncertain candidates too) and flips states. Build and verify are different instances. Trivial-tier work is exempt.
@@ -173,15 +218,21 @@ Every worker response must use the Forge worker contract exactly:
 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>
 ```
 
-Use `QUESTIONS` only when blocked.
+Use `QUESTIONS` only when blocked. `SUB_RESULTS` / `DELEGATION_REQUESTS` optional. Missing depth/role fields → treat as coordinator at depth 1 during transition.

package/dist/src/adapters/claude-known.js

@@ -9,6 +9,7 @@ export const knownClaudeTools = new Set([
     'Grep',
     'LS',
     'Task',
+    'Agent',
     'TodoWrite',
     'WebFetch',
     'WebSearch',

package/dist/src/adapters/claude.js

@@ -29,6 +29,16 @@ export function renderClaudeAgent(artifact) {
 export function renderClaudeSkill(artifact) {
     const diagnostics = [];
     const fm = { name: artifact.name, description: artifact.description };
+    if (artifact.claude?.when_to_use)
+        fm.when_to_use = artifact.claude.when_to_use;
+    if (artifact.claude?.model) {
+        fm.model = artifact.claude.model;
+        if (!isKnownClaudeModel(artifact.claude.model)) {
+            diagnostics.push(diagnostic('warning', 'CLAUDE_UNKNOWN_MODEL', `Unknown Claude model "${artifact.claude.model}" for ${artifact.name}`, { platform: 'claude' }));
+        }
+    }
+    if (artifact.claude?.['user-invocable'] !== undefined)
+        fm['user-invocable'] = artifact.claude['user-invocable'];
     const permissions = artifact.claude?.permissions;
     const allowedTools = isRecord(permissions) ? patternList(permissions['allowed-tools']) : undefined;
     if (allowedTools) {
@@ -38,7 +48,5 @@ export function renderClaudeSkill(artifact) {
     else if (permissions !== undefined) {
         diagnostics.push(diagnostic('info', 'CLAUDE_SKILL_PERMISSIONS_IGNORED', `Claude skill permissions are not emitted for ${artifact.name}`, { platform: 'claude' }));
     }
-    if (artifact.claude?.model)
-        diagnostics.push(diagnostic('info', 'CLAUDE_SKILL_MODEL_IGNORED', `Claude skill model is not emitted for ${artifact.name}`, { platform: 'claude' }));
     return { content: `${stringifyYaml(fm)}${artifact.body}\n`, diagnostics };
 }

package/dist/src/processor.js

@@ -15,10 +15,11 @@ const platformKeys = new Set(['claude', 'opencode', 'codex', 'grok']);
 const allowedTopLevel = new Set(['name', 'description', 'kind', 'claude', 'opencode', 'codex', 'grok']);
 const allowedProductKeys = new Set(['permissions', 'model', 'kind']);
 const allowedOpenCodeKeys = new Set([...allowedProductKeys, 'mode']);
+const allowedClaudeKeys = new Set([...allowedProductKeys, 'when_to_use', 'user-invocable']);
 const openCodeModes = new Set(['primary', 'subagent', 'all']);
 const artifactKinds = new Set(['agent', 'skill']);
 const defaultBodyBudget = 200;
-const bodyLineBudgets = { forge: 90, 'using-forge': 220, 'forge-worker': 300, 'forge-grill': 120, 'forge-adversary': 200 };
+const bodyLineBudgets = { forge: 90, 'using-forge': 240, 'forge-worker': 340, 'forge-worker-leaf': 280, 'forge-grill': 120, 'forge-adversary': 200 };
 export function resolvePlatforms(platform) {
     return platform === 'all' ? platforms : [platform];
 }
@@ -81,7 +82,7 @@ function convertSource(source, sourceRoot) {
         }
         const record = config;
         for (const key of Object.keys(record)) {
-            const allowedKeys = platform === 'opencode' ? allowedOpenCodeKeys : allowedProductKeys;
+            const allowedKeys = platform === 'opencode' ? allowedOpenCodeKeys : platform === 'claude' ? allowedClaudeKeys : allowedProductKeys;
             if (!allowedKeys.has(key))
                 diagnostics.push(diagnostic('error', 'UNSUPPORTED_PLATFORM_FIELD', `${platform}.${key} is not supported in the MVP`, { sourcePath: source.sourcePath, platform: platform }));
         }
@@ -91,6 +92,12 @@ function convertSource(source, sourceRoot) {
         if ('kind' in record && !artifactKinds.has(record.kind)) {
             diagnostics.push(diagnostic('error', 'INVALID_PLATFORM_KIND', `${platform}.kind must be one of agent, skill`, { sourcePath: source.sourcePath, platform: platform }));
         }
+        if (platform === 'claude' && 'when_to_use' in record && typeof record.when_to_use !== 'string') {
+            diagnostics.push(diagnostic('error', 'INVALID_CLAUDE_WHEN_TO_USE', 'claude.when_to_use must be a string', { sourcePath: source.sourcePath, platform: 'claude' }));
+        }
+        if (platform === 'claude' && 'user-invocable' in record && typeof record['user-invocable'] !== 'boolean') {
+            diagnostics.push(diagnostic('error', 'INVALID_CLAUDE_USER_INVOCABLE', 'claude.user-invocable must be a boolean', { sourcePath: source.sourcePath, platform: 'claude' }));
+        }
         if (platform === 'opencode' && 'mode' in record) {
             if (!openCodeModes.has(record.mode)) {
                 diagnostics.push(diagnostic('error', 'INVALID_OPENCODE_MODE', 'opencode.mode must be one of primary, subagent, all', { sourcePath: source.sourcePath, platform: 'opencode' }));
@@ -137,7 +144,9 @@ function convertSource(source, sourceRoot) {
     };
 }
 function productConfig(value) {
-    return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : undefined;
 }
 function renderFile(platform, kind, artifact, options, diagnostics) {
     const rendered = kind === 'agent'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guidobuilds/forge-ai",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Forge AI framework",
   "license": "MIT",
   "type": "module",