Forge Engine

How to use Forge well (no project needed) — the propose→adopt flow, that proposals/deletes are PENDING until the owner adopts on the web, what counts as a System (vs code infra), token-efficient reading, and sign-in/billing. Call this when unsure how something works or when the user asks.

DESIGN MEMORY — the recorded WHY. Queries the project's accumulated history: build decisions (report_build_status `decisions`), activity/log entries, owner rejections, and spec changelogs — every entry carries source/who/when so answers can CITE real records. Call it BEFORE changing a system's direction ("why is it designed this way?"). An empty result means there IS no recorded decision — say so, never invent a rationale. Filter by `system` (id or exact name) and/or `query` keyword.

List the project's PENDING Inbox items — the same triage queue the owner sees: proposals not yet adopted (discovered systems, new milestones, Intent updates, reported task progress, screen status, proposed UI elements / flow links). Call this BEFORE proposing so you don't duplicate something already waiting (proposing is write-only otherwise). Read-only — the owner adopts/flags in Forge; you cannot adopt.

Get ONE milestone's full detail by id (preferred) or exact name — goal, week estimate, difficulty, the systems it builds, and every task (id / name / done, plus optional status & effort). Use after list_milestones to read a specific milestone without pulling the whole project.

FULL design dump — LARGE (often exceeds the token cap on a real project). NOT the entry point: orient with get_project_meta, browse with list_*, drill in with get_system / get_milestone / get_screen, or jump to a thing with search. Use only when you truly need everything at once.

START HERE. Tiny project overview — id, name, version, last-updated, members, entity counts, current task `claims` (who is building what right now — check before you start), and forge_workflow_version. Then browse with list_* and drill in with get_* — far cheaper than get_project_context.

The DECLINED list — check at session START. Each entry = your build diverged from the owner's design; follow its `guidance` (revert to the kept spec / drop the out-of-scope thing / don't delete what they kept), then call resolve_rejection(title). Resolved items drop off automatically.

ONE screen's full layout — kind (screen/popup + parent), purpose, canvas `resolution` (place coords on THIS, don't assume 1920×1080), reference-image flag, every element (id/label/type/x/y/w/h/placed), its flow links, and its popups. The ONLY compact way to read a layout (even get_project_context omits element positions). Read this before update_element or adding onto an existing screen.

Get ONE system's full spec by name (Goal / Boundary / Acceptance + the raw markdown + sources + status). Use after get_project_context to read a specific system in detail without pulling the whole project.

Run this FIRST on a new repo/session (no project needed). Returns: (1) a first-connect greeting routine (read project status + Inbox, tell the user), and (2) the 'Forge working agreement' block for the repo's AGENTS.md / CLAUDE.md so EVERY future session keeps using Forge (read design before building, report progress, propose discoveries, log work). ADD the block for the user right away (create/replace; tell them in one line; remove it if they object) — don't wait to be asked.

ONE-COMMAND import of an EXISTING codebase — run when the user wants Forge to reflect their code. Returns the full recipe + a batch id: you read the repo and propose one Context overview + one System per real module (all batch-tagged; the owner adopts the import in one click). Reflects only what EXISTS today; non-destructive.

The project's CHANGE HISTORY — compact rows {who, change, entity, kind, when}, newest first; filter by kind / who / query (keyword). Answers 'what changed recently / who touched X'. (For who's building what RIGHT NOW, read `claims` in get_project_meta.)

List the project's milestones COMPACTLY — id, name, week estimate, order, and task counts (done/total) only, no goals or task names. Tiny payload: use this to browse the plan or grab a milestone id WITHOUT pulling the whole project (get_project_context can be large). Drill into one with get_milestone.

List the Forge projects YOU can access (with an account key) — each with id, name, and your role. Use this to discover which project to work on, then pass its id as `project_id` to any tool to switch (no need to re-add the connector). A project-scoped key returns just its one project.

List the project's screens COMPACTLY — id, name, 1-line purpose, and build status. Tiny payload: browse screens or grab an id without pulling the whole project.

List the project's systems COMPACTLY — id, name, status, and a 1-line goal only (no full Goal/Boundary/Acceptance). Tiny payload: browse systems or grab an id WITHOUT pulling the whole project. Drill into one with get_system.

Append a build-log entry to the project's Activity feed — record what you built / a key decision / where you diverged (like a commit note), so the team + the design can see your work. Non-destructive, attributed to you. Use as you work (the milestone tick is report_milestone_progress; this is the narrative).

Propose a Balance Lab BOARD (a node canvas) → Inbox to Adopt. `nodes` = blocks {kind: const|formula|item|sheet|loadout|picker|pool|process|note|frame, name, …kind fields}; formulas reference other blocks by NAME (name-magic). Omit x/y and the server auto-layouts topologically. Adopting REPLACES a same-named board.

Propose a Balance Lab stat-doc TABLE (an entity catalog: Weapons, Monsters, Skills…) → Inbox to Adopt. Pass `csv` (header row; `key%` marks a percent value column; first column doubles as name) OR `schema`+`rows` JSON. Generated/drafted stat docs land here for review — never a silent write. Adopting REPLACES a same-named table (re-propose = update).

Propose a new/updated Context (Idea) note → Inbox. Title-matches an existing section (shows as a diff) or adds a new note. Use when the build changes something the upstream idea should reflect — keeps the source-of-truth in sync. Send the complete revised text, not a delta. Non-destructive.

Propose the Project DNA (north star: what it is · who it's for · pillars · non-goals) and/or Tech Notes (stack, key libraries, database, infra, constraints) → Inbox to Adopt. At least one of `dna` / `tech_notes` required. Non-destructive.

SECONDARY (user-driven UI). Propose a UI element onto a screen → Inbox to Adopt. The screen may be adopted OR still pending from this batch (they adopt together). ALWAYS pass x/y/w/h — px on the SCREEN'S canvas (`resolution` from get_screen; for a new set confirm the aspect with the user, don't assume 1920×1080 landscape). Omitting coords dumps it in an unplaced pile the human must hand-arrange. `system` = the System it serves; `note` = designer note. Non-destructive.

SECONDARY (user-driven UI — not the core build loop; only when the USER wants to map screen flow). Propose a navigation link between two EXISTING screens (screen → screen) → Inbox to Adopt. Use screen names from get_project_context. Non-destructive (connection only, no layout).

Propose a NEW milestone (with optional tasks) → Inbox to Adopt. Non-destructive.

SECONDARY (user-driven UI). Propose a NEW screen (a HUD + its flow node) → Inbox to Adopt. `parent` makes it a POPUP overlaying that screen; `purpose` (one line) grounds later element suggestions. Generating a whole UI? Run design_ui_from_systems first — elements/edges may reference still-pending screens from the same batch and adopt together. Non-destructive.

Propose a NEW system spec → Inbox (non-destructive; the owner adopts). spec = ## Goal / ## Boundary (Owns · Doesn't own) / ## Acceptance, consistent with existing systems. Check list_systems/search first — if it already exists, use update_system instead. (Alias: create_proposal.)

Rename an existing screen IN PLACE — applies DIRECTLY to the design (live; not a proposal; safe & reversible). Flow links + elements follow automatically (they reference the screen by id, not name). Identify it by its current name. Use names from list_screens / get_project_context.

Reorder milestones, a milestone's tasks, or a screen's elements — applies DIRECTLY (safe & reversible). `order` = ids in the new order (milestone names also work); omitted entries keep their relative order at the end. kind=tasks also needs milestone_id/milestone; kind=elements also needs screen.

Report how far a SYSTEM is built — live badge (todo | in-progress | implemented), shows immediately (NOT an Inbox item). ALWAYS pass `files` = the paths that implement it (the system→code map; re-send the full list — it replaces): a non-todo system with no files shows done-but-EMPTY to the owner. `decisions` = prose notes (never in files).

Flag CODE DRIFT on a system — its system→code map (from get_build_region) no longer matches the repo: mapped files deleted, moved, or rewritten away from the spec. Advisory only (blocks nothing): the flag shows on the owner's Dashboard and in get_build_region until someone re-maps the system with a fresh report_build_status (which clears it). Pass the stale paths in `missing_files` (+ optional `note` for drift that isn't a missing file).

Mark tasks of an EXISTING milestone as done (e.g. work already finished) → Inbox progress card to Adopt (ticks them). Use exact milestone + task names from get_project_context. Non-destructive.

Report a SCREEN's build status (todo | in-progress | implemented) → Inbox for the owner to Adopt onto the System Flow node. Use as you build out a screen. Identify the screen by name (from list_screens / get_project_context). Non-destructive — the owner adopts it.

Tell the owner you've REVERTED a declined change (from get_rejections) — your build now matches the design again. Pass the rejection's `title`. This unlocks the owner's 'Clear' button for that item (they verify, then remove it); without it the item stays open. Call it right after you bring the build back in line.

Keyword search across the project (case-insensitive) — find a milestone, task, system, screen, context section, or open question (and its id) without scanning the whole context. Returns compact hits {kind, id, name, …} with a snippet for body matches. Optionally limit with `kinds`.

Move / resize / relabel / retype an EXISTING element in place — applies DIRECTLY (live; safe & reversible — the content was already adopted; don't delete+re-propose). Identify by `element_id` (from get_screen; preferred) or `screen`+`label` (label must be unique on that screen). Passing x+y also pulls an unplaced ('to place') element onto the canvas.

Edit a milestone's goal / weeks / difficulty / name IN PLACE — applies DIRECTLY (live). Use `new_name` to RENAME (never delete+recreate — that mints a new id). Identify by id (preferred) or exact unique name.

Propose an UPDATE to an existing system → Inbox as a reviewable diff (owner adopts). Read get_system first, then send the FULL revised spec. `new_title` renames in the same card. If the upstream idea shifted too, pass `context_title`+`context` to bundle that update. Non-destructive.

Edit a task (name / done / status / effort) or CLAIM it (assignee) by task id — applies DIRECTLY. CLAIM before you build: assignee:"me" + status:"in-progress" marks the task yours (listed in get_project_meta claims, so others don't collide); it ERRORS if someone else holds it — override a stale claim with force:true. done:true (or assignee:"") releases the claim. (To report progress for human review instead, use report_milestone_progress.)

Withdraw YOUR OWN still-pending Inbox item (a propose_* / delete_entity you made by mistake) — removes it before the owner adopts. Pass the `id` from the propose call's response or get_inbox. Only items you authored and only while pending.