Forge Engine

Owner's DECLINED list — check at session start; follow each entry's guidance, then resolve_rejection(title).

ONE screen's layout: canvas `resolution` (use THESE px), elements x/y/w/h, links, popups. Read before editing a screen. has_reference_image:true → get_screen_image shows you the actual image.

A screen's reference image (HUD background) as an actual IMAGE you can see — reads the stored file inline (signed-URL fallback past 4MB).

What has drifted between the Idea lane and the System Specs — the design's own out-of-sync list, computed deterministically (no AI, no tokens). Three kinds: Idea notes edited since the systems were generated from them (with the systems each one touches), Idea notes whose prose the systems have moved past, and specs whose stamped source fingerprint no longer matches. Read this before assuming the design is coherent; fix the first kind with resync_from_idea.

ONE system's full spec (Goal/Boundary/Acceptance, markdown, sources, status) + pending Inbox changes touching it.

Run FIRST in a new repo (no project): first-connect routine + the working-agreement block to ADD to AGENTS.md/CLAUDE.md now (tell the user in one line; remove if they object).

One-command codebase import: recipe + batch id — propose one Context overview + one System per real module; the owner adopts all at once.

Change history {who, change, entity, kind, when}, newest first; filter kind/who/query.

All milestones, compact: id, name, weeks, order, done/total.

Projects your key reaches (id, name, role); pass an id as project_id to switch.

All screens, compact: id, name, purpose, status.

All systems, compact: id, name, status, 1-line goal.

DISPATCHER (multi-agent): atomically pick + claim the next task to build — walks milestones in order, skips human-only tasks and any task whose systems share code files with a task another agent already holds or is actively touching, so parallel agents spread out instead of colliding. Returns the claimed task + systems, or why none is free. dry_run:true peeks without claiming.

Append a build-log entry to Activity — what you built/decided (commit-note style).

Propose a node board → Inbox. Kinds const|formula|item|sheet|loadout|picker|pool|process|note|frame; formulas reference blocks by NAME; omit x/y = auto-layout. Adopting REPLACES same-named.

Propose a stat-doc TABLE → Inbox. csv (header; `key%` = percent; first column = name) OR schema+rows. Adopting REPLACES same-named.

Propose a new/updated Idea note → Inbox. Title-match to update; send the COMPLETE revised text. Set resync:true ONLY when you rewrote the note FROM the current systems (get_stale lists notes the systems have moved past) — it stops the adopted note from immediately nagging to re-generate the systems it was just written from.

Propose Project DNA and/or Tech Notes → Inbox (at least one).

SECONDARY (user-driven UI): propose an element onto a screen → Inbox. ALWAYS pass x/y/w/h (px on the screen's `resolution` from get_screen); no coords = unplaced pile.

SECONDARY (user-driven UI): propose a link between two existing screens → Inbox.

Propose a NEW milestone (+ optional tasks) → Inbox.

SECONDARY (user-driven UI): propose a NEW screen → Inbox. parent = popup over that screen; purpose grounds AI suggestions. Whole UI? design_ui_from_systems first.

Propose a NEW system → Inbox. spec = ## Goal / ## Boundary (Owns · Doesn't own) / ## Acceptance. Exists? use update_system. (Alias: create_proposal.)

Rename a screen IN PLACE — DIRECT; links/elements follow (id-referenced).

Reorder milestones / tasks / elements — DIRECT. order = ids in new order; omitted keep relative order.

Report a SYSTEM's status (todo|in-progress|implemented) — DIRECT, live. ALWAYS pass files (full list — it REPLACES); non-todo with no files shows done-but-EMPTY. 'implemented' counts as VERIFIED only when every UNIT-TESTABLE ## Acceptance bullet is backed via evidence[{criterion,proof}]; a bullet tagged [manual]/[e2e]/[ui]/[wip] is EXEMPT (verified by manual/e2e). Otherwise it's a CLAIM (verified:false) and the response names the unbacked criteria. TWO tiers: VERIFIED = a test is NAMED; GREEN (guarantee) = you RAN the test and reported `passed:true` on the evidence — green goes stale after 21 …

Flag CODE DRIFT — mapped files no longer match the repo. Advisory; a fresh report_build_status clears it.

Mark existing-milestone tasks done → Inbox progress card (owner adopts the ticks).

Report a SCREEN's status (todo|in-progress|implemented) → Inbox.

Report you REVERTED a declined change (unlocks the owner's Clear). Call after realigning the build.

The recipe for re-syncing ONE changed Idea note into the specs that depend on it — the same scoped job the app's "Re-sync N systems" button does, minus the button. Returns the note, the affected specs in full, and exactly how to send the result back. You do the writing; it lands in the owner's Inbox to ADOPT. CRUCIAL: send updates with `resync:true`, or the owner adopts your fix and the design still reports it as stale.

Keyword search — compact hits {kind, id, name} + snippet.

Write the Design Document's Overview — the human-readable page a new team member reads first. WRITES DIRECTLY (no Inbox): it is a derived, clearly-labelled AI summary, not design truth, and the owner can clear or rewrite it in one click. HARD RULES, same as the in-app button: use ONLY facts stated in the design (call get_design_document with for_summary:true first); invent no mechanics, numbers or names; describe, never evaluate; write in the design's dominant language. Structure: `### What this is` · `### The core loop` · `### How the systems fit` (which system feeds which — the part a raw sp…

SECONDARY (user-driven UI): turn a screen's REFERENCE IMAGE into placed elements. Returns the image itself plus the recipe — the canvas resolution, the fraction→pixel conversion that stops coordinates landing wrong, and what is already on the screen so a second pass updates instead of duplicating. You look at the picture and send back propose_element / update_element with x/y/w/h; it all lands in the owner's Inbox. Use when the user wants the wireframe to match a screenshot or mockup they uploaded.

Move/resize/relabel an element — DIRECT, live. element_id (preferred) or screen+label; x+y also places an unplaced one.

Edit milestone goal/weeks/difficulty/name — DIRECT. new_name renames (never delete+recreate).

Propose a system UPDATE → Inbox diff. get_system first; send the FULL revised spec. new_title renames; context_title+context bundles the Idea update. Set resync:true ONLY when you rewrote this spec FROM its upstream Idea (see resync_from_idea) — it re-stamps the staleness signal on adopt.

Edit a task or CLAIM it — DIRECT. assignee:"me"+status:"in-progress" claims (errors if held; force:true for stale); done:true or assignee:"" releases.

Remove YOUR OWN still-pending Inbox item (id from the propose response / get_inbox).