by alongkornonline2019
Design source-of-truth for AI coding agents to read a project's systems and propose changes back.
Design source-of-truth for AI coding agents to read a project's systems and propose changes back.
Captured live from the server via tools/list.
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.
Parameters
No parameters.
{
"type": "object",
"properties": {},
"additionalProperties": false
}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.
Parameters
No parameters.
{
"type": "object",
"properties": {},
"additionalProperties": false
}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.
| project_id | string | optional | Project id (from list_projects) to act on; omit = the connector URL's project. |
{
"type": "object",
"properties": {
"project_id": {
"type": "string",
"description": "Project id (from list_projects) to act on; omit = the connector URL's project."
}
},
"additionalProperties": false
}ONE-PASS recipe to design the UI from the spec'd Systems — run when the user asks to generate screens / flow / a prototype. Returns the full recipe + a batch id: confirm the canvas aspect FIRST, then propose screens + PLACED elements (x/y/w/h) + pop-ups + flow edges in one batch; the owner adopts the whole UI at once. Non-destructive.
| project_id | string | optional | Project id (from list_projects) to act on; omit = the connector URL's project. |
{
"type": "object",
"properties": {
"project_id": {
"type": "string",
"description": "Project id (from list_projects) to act on; omit = the connector URL's project."
}
},
"additionalProperties": false
}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).
| text | string | required | What you did / decided (one or two sentences). |
| entity | string | optional | Optional — the system/screen/milestone name this is about. |
| version | string | optional | Optional — the build/app version this entry belongs to (e.g. "0.379.0"), stamped into the feed so the log anchors to a concrete build. |
| project_id | string | optional | Project id (from list_projects) to act on; omit = the connector URL's project. |
{
"type": "object",
"properties": {
"text": {
"type": "string",
"description": "What you did / decided (one or two sentences)."
},
"entity": {
"type": "string",
"description": "Optional — the system/screen/milestone name this is about."
},
"version": {
"type": "string",
"description": "Optional — the build/app version this entry belongs to (e.g. \"0.379.0\"), stamped into the feed so the log anchors to a concrete build."
},
"project_id": {
"type": "string",
"description": "Project id (from list_projects) to act on; omit = the connector URL's project."
}
},
"required": [
"text"
],
"additionalProperties": false
}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.
| project_id | string | optional | Project id (from list_projects) to act on; omit = the connector URL's project. |
{
"type": "object",
"properties": {
"project_id": {
"type": "string",
"description": "Project id (from list_projects) to act on; omit = the connector URL's project."
}
},
"additionalProperties": false
}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.
Parameters
No parameters.
{
"type": "object",
"properties": {},
"additionalProperties": false
}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), `working_now` (who's actively touching which entity, last 45 min of activity — softer than claims; avoid colliding with them), and forge_workflow_version. Then browse with list_* and drill in with get_* — far cheaper than get_project_context.
| project_id | string | optional | Project id (from list_projects) to act on; omit = the connector URL's project. |
{
"type": "object",
"properties": {
"project_id": {
"type": "string",
"description": "Project id (from list_projects) to act on; omit = the connector URL's project."
}
},
"additionalProperties": false
}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.
| id | string | optional | System id from get_project_context (preferred) |
| name | string | optional | Exact system name (if no id) |
| project_id | string | optional | Project id (from list_projects) to act on; omit = the connector URL's project. |
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "System id from get_project_context (preferred)"
},
"name": {
"type": "string",
"description": "Exact system name (if no id)"
},
"project_id": {
"type": "string",
"description": "Project id (from list_projects) to act on; omit = the connector URL's project."
}
},
"required": [],
"additionalProperties": false
}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.
| project_id | string | optional | Project id (from list_projects) to act on; omit = the connector URL's project. |
{
"type": "object",
"properties": {
"project_id": {
"type": "string",
"description": "Project id (from list_projects) to act on; omit = the connector URL's project."
}
},
"additionalProperties": false
}The system→code MAP: for each system that's been built, the files that implement it + its build status (todo | in-progress | implemented) — fed by report_build_status. Use it to find WHERE a system lives in the codebase before you edit it (so you change the right files), or to see what's already built. VERIFY as you use it: if mapped files no longer exist in the repo (deleted/moved), call report_drift on that system so the map can't rot. Includes any `drift` flag. Only returns systems with a status, files, or drift; empty if nothing has been reported yet.
| project_id | string | optional | Project id (from list_projects) to act on; omit = the connector URL's project. |
{
"type": "object",
"properties": {
"project_id": {
"type": "string",
"description": "Project id (from list_projects) to act on; omit = the connector URL's project."
}
},
"additionalProperties": false
}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).
| id | string | optional | System id (preferred) |
| name | string | optional | Exact system name (if no id) |
| missing_files | array | optional | Mapped paths that no longer exist / moved (from get_build_region) |
| note | string | optional | Optional — what drifted, e.g. 'file rewritten; no longer covers acceptance #2' |
| project_id | string | optional | Project id (from list_projects) to act on; omit = the connector URL's project. |
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "System id (preferred)"
},
"name": {
"type": "string",
"description": "Exact system name (if no id)"
},
"missing_files": {
"type": "array",
"items": {
"type": "string"
},
"description": "Mapped paths that no longer exist / moved (from get_build_region)"
},
"note": {
"type": "string",
"description": "Optional — what drifted, e.g. 'file rewritten; no longer covers acceptance #2'"
},
"project_id": {
"type": "string",
"description": "Project id (from list_projects) to act on; omit = the connector URL's project."
}
},
"required": [],
"additionalProperties": false
}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.
| system | string | optional | System id or exact name — history touching this system |
| query | string | optional | Keyword filter (matches entity + text) |
| limit | number | optional | Max entries (default 30, max 100) |
| project_id | string | optional | Project id (from list_projects) to act on; omit = the connector URL's project. |
{
"type": "object",
"properties": {
"system": {
"type": "string",
"description": "System id or exact name — history touching this system"
},
"query": {
"type": "string",
"description": "Keyword filter (matches entity + text)"
},
"limit": {
"type": "number",
"description": "Max entries (default 30, max 100)"
},
"project_id": {
"type": "string",
"description": "Project id (from list_projects) to act on; omit = the connector URL's project."
}
},
"required": [],
"additionalProperties": false
}BLAST RADIUS for one system — run BEFORE changing or building against it. Deterministic (provenance edges + the system→code map; no AI): the upstream Context it derives from, sibling systems fed by the same note, dependent screens & milestones (with open-task counts), its mapped files, systems whose mapped code OVERLAPS yours (shared files = coupling), pending Inbox items already touching it, and who touched it recently. A change that ignores this list is how teams build the wrong thing in parallel.
| id | string | optional | System id (preferred) |
| name | string | optional | Exact system name (if no id) |
| project_id | string | optional | Project id (from list_projects) to act on; omit = the connector URL's project. |
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "System id (preferred)"
},
"name": {
"type": "string",
"description": "Exact system name (if no id)"
},
"project_id": {
"type": "string",
"description": "Project id (from list_projects) to act on; omit = the connector URL's project."
}
},
"required": [],
"additionalProperties": false
}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.
| project_id | string | optional | Project id (from list_projects) to act on; omit = the connector URL's project. |
{
"type": "object",
"properties": {
"project_id": {
"type": "string",
"description": "Project id (from list_projects) to act on; omit = the connector URL's project."
}
},
"additionalProperties": false
}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.
| title | string | required | The declined item's title, exactly as get_rejections returned it. |
| project_id | string | optional | Project id (from list_projects) to act on; omit = the connector URL's project. |
{
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "The declined item's title, exactly as get_rejections returned it."
},
"project_id": {
"type": "string",
"description": "Project id (from list_projects) to act on; omit = the connector URL's project."
}
},
"required": [
"title"
],
"additionalProperties": false
}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.
| project_id | string | optional | Project id (from list_projects) to act on; omit = the connector URL's project. |
{
"type": "object",
"properties": {
"project_id": {
"type": "string",
"description": "Project id (from list_projects) to act on; omit = the connector URL's project."
}
},
"additionalProperties": false
}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.
| id | string | optional | Screen id (preferred) |
| name | string | optional | Exact screen name (if no id) |
| project_id | string | optional | Project id (from list_projects) to act on; omit = the connector URL's project. |
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Screen id (preferred)"
},
"name": {
"type": "string",
"description": "Exact screen name (if no id)"
},
"project_id": {
"type": "string",
"description": "Project id (from list_projects) to act on; omit = the connector URL's project."
}
},
"required": [],
"additionalProperties": false
}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.
| element_id | string | optional | Element id (preferred, from get_screen) |
| screen | string | optional | Screen name (with `label`, if no element_id) |
| label | string | optional | Current element label on that screen (must be unique there) |
| x | number | optional | New left px (optional) |
| y | number | optional | New top px (optional) |
| w | number | optional | New width px (optional) |
| h | number | optional | New height px (optional) |
| new_label | string | optional | Rename the element (optional) |
| type | string | optional | New type hint, e.g. button/bar/panel (optional) |
| note | string | optional | New designer note (optional; "" clears) |
| system | string | optional | The System it serves (optional) |
| project_id | string | optional | Project id (from list_projects) to act on; omit = the connector URL's project. |
{
"type": "object",
"properties": {
"element_id": {
"type": "string",
"description": "Element id (preferred, from get_screen)"
},
"screen": {
"type": "string",
"description": "Screen name (with `label`, if no element_id)"
},
"label": {
"type": "string",
"description": "Current element label on that screen (must be unique there)"
},
"x": {
"type": "number",
"description": "New left px (optional)"
},
"y": {
"type": "number",
"description": "New top px (optional)"
},
"w": {
"type": "number",
"description": "New width px (optional)"
},
"h": {
"type": "number",
"description": "New height px (optional)"
},
"new_label": {
"type": "string",
"description": "Rename the element (optional)"
},
"type": {
"type": "string",
"description": "New type hint, e.g. button/bar/panel (optional)"
},
"note": {
"type": "string",
"description": "New designer note (optional; \"\" clears)"
},
"system": {
"type": "string",
"description": "The System it serves (optional)"
},
"project_id": {
"type": "string",
"description": "Project id (from list_projects) to act on; omit = the connector URL's project."
}
},
"required": [],
"additionalProperties": false
}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.
| id | string | required | The pending item's id (from the propose response / get_inbox) |
| project_id | string | optional | Project id (from list_projects) to act on; omit = the connector URL's project. |
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The pending item's id (from the propose response / get_inbox)"
},
"project_id": {
"type": "string",
"description": "Project id (from list_projects) to act on; omit = the connector URL's project."
}
},
"required": [
"id"
],
"additionalProperties": false
}PROPOSE deleting ONE design entity → Forge Inbox; the OWNER adopts to perform it (nothing is deleted immediately). kind = system | context | screen | milestone | task | element | flow_edge. Identify by `id` (preferred — task/element/edge ids go here too) or exact `name`; a flow_edge may instead use `from`+`to` screen names. A system's response includes its blast radius.
| kind | string | required | What to delete |
| id | string | optional | Entity id (preferred; task tk_… / element / edge ids too) |
| name | string | optional | Exact name/title (if no id) |
| from | string | optional | flow_edge only — source screen name (with `to`) |
| to | string | optional | flow_edge only — destination screen name (with `from`) |
| project_id | string | optional | Project id (from list_projects) to act on; omit = the connector URL's project. |
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"system",
"context",
"screen",
"milestone",
"task",
"element",
"flow_edge"
],
"description": "What to delete"
},
"id": {
"type": "string",
"description": "Entity id (preferred; task tk_… / element / edge ids too)"
},
"name": {
"type": "string",
"description": "Exact name/title (if no id)"
},
"from": {
"type": "string",
"description": "flow_edge only — source screen name (with `to`)"
},
"to": {
"type": "string",
"description": "flow_edge only — destination screen name (with `from`)"
},
"project_id": {
"type": "string",
"description": "Project id (from list_projects) to act on; omit = the connector URL's project."
}
},
"required": [
"kind"
],
"additionalProperties": false
}Remove DUPLICATE entries, keeping the first of each — applies DIRECTLY (destructive). kind=milestones (duplicate-named milestones) or elements (duplicate-labelled elements on `screen`).
| kind | string | required | What to dedupe |
| screen | string | optional | elements only — the screen to clean |
| project_id | string | optional | Project id (from list_projects) to act on; omit = the connector URL's project. |
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"milestones",
"elements"
],
"description": "What to dedupe"
},
"screen": {
"type": "string",
"description": "elements only — the screen to clean"
},
"project_id": {
"type": "string",
"description": "Project id (from list_projects) to act on; omit = the connector URL's project."
}
},
"required": [
"kind"
],
"additionalProperties": false
}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.
| kind | string | required | What to reorder |
| order | array | required | Ids in the new order |
| milestone_id | string | optional | tasks only — milestone id (preferred) |
| milestone | string | optional | tasks only — milestone name (if no id) |
| screen | string | optional | elements only — screen name |
| project_id | string | optional | Project id (from list_projects) to act on; omit = the connector URL's project. |
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"milestones",
"tasks",
"elements"
],
"description": "What to reorder"
},
"order": {
"type": "array",
"items": {
"type": "string"
},
"description": "Ids in the new order"
},
"milestone_id": {
"type": "string",
"description": "tasks only — milestone id (preferred)"
},
"milestone": {
"type": "string",
"description": "tasks only — milestone name (if no id)"
},
"screen": {
"type": "string",
"description": "elements only — screen name"
},
"project_id": {
"type": "string",
"description": "Project id (from list_projects) to act on; omit = the connector URL's project."
}
},
"required": [
"kind",
"order"
],
"additionalProperties": false
}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.
| project_id | string | optional | Project id (from list_projects) to act on; omit = the connector URL's project. |
{
"type": "object",
"properties": {
"project_id": {
"type": "string",
"description": "Project id (from list_projects) to act on; omit = the connector URL's project."
}
},
"additionalProperties": false
}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.
| id | string | optional | Milestone id from list_milestones / get_project_context (preferred) |
| name | string | optional | Exact milestone name (if no id; must be unique) |
| project_id | string | optional | Project id (from list_projects) to act on; omit = the connector URL's project. |
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Milestone id from list_milestones / get_project_context (preferred)"
},
"name": {
"type": "string",
"description": "Exact milestone name (if no id; must be unique)"
},
"project_id": {
"type": "string",
"description": "Project id (from list_projects) to act on; omit = the connector URL's project."
}
},
"required": [],
"additionalProperties": false
}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.)
| query | string | optional | Keyword to match in the change/entity (optional) |
| kind | string | optional | Filter by kind: system | context | milestone | screen (optional) |
| who | string | optional | Filter by author (email substring, optional) |
| limit | number | optional | Max rows (default 30, max 200) |
| project_id | string | optional | Project id (from list_projects) to act on; omit = the connector URL's project. |
{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Keyword to match in the change/entity (optional)"
},
"kind": {
"type": "string",
"description": "Filter by kind: system | context | milestone | screen (optional)"
},
"who": {
"type": "string",
"description": "Filter by author (email substring, optional)"
},
"limit": {
"type": "number",
"description": "Max rows (default 30, max 200)"
},
"project_id": {
"type": "string",
"description": "Project id (from list_projects) to act on; omit = the connector URL's project."
}
},
"required": [],
"additionalProperties": false
}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.
| project_id | string | optional | Project id (from list_projects) to act on; omit = the connector URL's project. |
{
"type": "object",
"properties": {
"project_id": {
"type": "string",
"description": "Project id (from list_projects) to act on; omit = the connector URL's project."
}
},
"additionalProperties": false
}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`.
| query | string | required | Text to search for |
| kinds | array | optional | Limit to these kinds (optional): system | context | milestone | task | screen | proposal |
| project_id | string | optional | Project id (from list_projects) to act on; omit = the connector URL's project. |
{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Text to search for"
},
"kinds": {
"type": "array",
"items": {
"type": "string"
},
"description": "Limit to these kinds (optional): system | context | milestone | task | screen | proposal"
},
"project_id": {
"type": "string",
"description": "Project id (from list_projects) to act on; omit = the connector URL's project."
}
},
"required": [
"query"
],
"additionalProperties": false
}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.)
| title | string | required | System name (Title Case, in English) |
| spec | string | required | Markdown spec: ## Goal / ## Boundary (Owns, Doesn't own) / ## Acceptance |
| files | array | optional | Optional — the source file paths that IMPLEMENT this system (clean repo-relative, one per entry, e.g. 'src/auth/login.ts'). Stored as the system→code map (get_build_region) so the design links back to the real code — give the files you read for this module. |
| batch | string | optional | Optional — the import batch id from import_from_code. Pass the SAME value on every proposal of one codebase import so the owner can Adopt them all as one group. |
| acknowledge_rejection | boolean | optional | Only when a previous call bounced with 'the owner DECLINED this': pass true AFTER asking the user (owner changed their mind, or it's a genuinely different thing sharing the title). Never pass it just to get past the gate. |
| project_id | string | optional | Project id (from list_projects) to act on; omit = the connector URL's project. |
{
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "System name (Title Case, in English)"
},
"spec": {
"type": "string",
"description": "Markdown spec: ## Goal / ## Boundary (Owns, Doesn't own) / ## Acceptance"
},
"files": {
"type": "array",
"items": {
"type": "string"
},
"description": "Optional — the source file paths that IMPLEMENT this system (clean repo-relative, one per entry, e.g. 'src/auth/login.ts'). Stored as the system→code map (get_build_region) so the design links back to the real code — give the files you read for this module."
},
"batch": {
"type": "string",
"description": "Optional — the import batch id from import_from_code. Pass the SAME value on every proposal of one codebase import so the owner can Adopt them all as one group."
},
"acknowledge_rejection": {
"type": "boolean",
"description": "Only when a previous call bounced with 'the owner DECLINED this': pass true AFTER asking the user (owner changed their mind, or it's a genuinely different thing sharing the title). Never pass it just to get past the gate."
},
"project_id": {
"type": "string",
"description": "Project id (from list_projects) to act on; omit = the connector URL's project."
}
},
"required": [
"title",
"spec"
],
"additionalProperties": false
}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.
| title | string | required | Context section title — match an existing one to update it, or a new title to add a note (Title Case, English). |
| content | string | required | The full context/idea text (markdown). For an update, send the complete revised section, not just the delta. |
| batch | string | optional | Optional — the import batch id from import_from_code. Pass the SAME value on every proposal of one codebase import so the owner can Adopt them all as one group. |
| acknowledge_rejection | boolean | optional | Only when a previous call bounced with 'the owner DECLINED this': pass true AFTER asking the user. Never pass it just to get past the gate. |
| project_id | string | optional | Project id (from list_projects) to act on; omit = the connector URL's project. |
{
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Context section title — match an existing one to update it, or a new title to add a note (Title Case, English)."
},
"content": {
"type": "string",
"description": "The full context/idea text (markdown). For an update, send the complete revised section, not just the delta."
},
"batch": {
"type": "string",
"description": "Optional — the import batch id from import_from_code. Pass the SAME value on every proposal of one codebase import so the owner can Adopt them all as one group."
},
"acknowledge_rejection": {
"type": "boolean",
"description": "Only when a previous call bounced with 'the owner DECLINED this': pass true AFTER asking the user. Never pass it just to get past the gate."
},
"project_id": {
"type": "string",
"description": "Project id (from list_projects) to act on; omit = the connector URL's project."
}
},
"required": [
"title",
"content"
],
"additionalProperties": false
}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.
| dna | string | optional | Project DNA as markdown (what it is, who it's for, pillars, non-goals). Omit to leave DNA unchanged. |
| tech_notes | string | optional | Tech Notes as markdown (stack/engine, key libraries, database, infra, constraints). Omit to leave Tech Notes unchanged. |
| batch | string | optional | Optional — the import batch id from import_from_code, so it adopts with the same group. |
| project_id | string | optional | Project id (from list_projects) to act on; omit = the connector URL's project. |
{
"type": "object",
"properties": {
"dna": {
"type": "string",
"description": "Project DNA as markdown (what it is, who it's for, pillars, non-goals). Omit to leave DNA unchanged."
},
"tech_notes": {
"type": "string",
"description": "Tech Notes as markdown (stack/engine, key libraries, database, infra, constraints). Omit to leave Tech Notes unchanged."
},
"batch": {
"type": "string",
"description": "Optional — the import batch id from import_from_code, so it adopts with the same group."
},
"project_id": {
"type": "string",
"description": "Project id (from list_projects) to act on; omit = the connector URL's project."
}
},
"required": [],
"additionalProperties": false
}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.
| id | string | optional | System id from get_project_context (preferred) |
| name | string | optional | Exact existing system name (if no id) |
| spec | string | required | Full revised spec markdown (## Goal / ## Boundary / ## Acceptance) |
| new_title | string | optional | Optional — also RENAME this system to this title in the same update card (e.g. to fix a wrong/changed name on a re-import). Omit to keep the current name. |
| context_title | string | optional | Optional — to ALSO update the upstream Idea: the Context section title to match (Title Case, English). Pair with `context`. Find it via get_system (`sources`) / search. |
| context | string | optional | Optional — the full revised Idea/Context text (markdown) for `context_title`, sent in the same call to keep source-of-truth in sync. Requires `context_title`. |
| acknowledge_rejection | boolean | optional | Only when a previous call bounced with 'the owner DECLINED this': pass true AFTER asking the user. Never pass it just to get past the gate. |
| project_id | string | optional | Project id (from list_projects) to act on; omit = the connector URL's project. |
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "System id from get_project_context (preferred)"
},
"name": {
"type": "string",
"description": "Exact existing system name (if no id)"
},
"spec": {
"type": "string",
"description": "Full revised spec markdown (## Goal / ## Boundary / ## Acceptance)"
},
"new_title": {
"type": "string",
"description": "Optional — also RENAME this system to this title in the same update card (e.g. to fix a wrong/changed name on a re-import). Omit to keep the current name."
},
"context_title": {
"type": "string",
"description": "Optional — to ALSO update the upstream Idea: the Context section title to match (Title Case, English). Pair with `context`. Find it via get_system (`sources`) / search."
},
"context": {
"type": "string",
"description": "Optional — the full revised Idea/Context text (markdown) for `context_title`, sent in the same call to keep source-of-truth in sync. Requires `context_title`."
},
"acknowledge_rejection": {
"type": "boolean",
"description": "Only when a previous call bounced with 'the owner DECLINED this': pass true AFTER asking the user. Never pass it just to get past the gate."
},
"project_id": {
"type": "string",
"description": "Project id (from list_projects) to act on; omit = the connector URL's project."
}
},
"required": [
"spec"
],
"additionalProperties": false
}Read the project's Balance Lab: stat-doc TABLES (schema = per-column stat definitions, rows = the entities), node BOARDS with EVALUATED values (sheets, loadouts, pools, process odds — same engine as the web), and saved scenarios. Use it to reason about game balance before proposing changes.
| board | string | optional | Optional — a board name or id to evaluate just that board (omit = all boards). |
| include_rows | boolean | optional | Include table rows (default true; first 200 per table). Pass false for a schema-only view. |
| project_id | string | optional | Project id (from list_projects) to act on; omit = the connector URL's project. |
{
"type": "object",
"properties": {
"board": {
"type": "string",
"description": "Optional — a board name or id to evaluate just that board (omit = all boards)."
},
"include_rows": {
"type": "boolean",
"description": "Include table rows (default true; first 200 per table). Pass false for a schema-only view."
},
"project_id": {
"type": "string",
"description": "Project id (from list_projects) to act on; omit = the connector URL's project."
}
},
"required": [],
"additionalProperties": false
}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).
| title | string | required | Table name (e.g. "Weapons") |
| csv | string | optional | CSV text: header row + data rows. `atk` = flat value, `atk%` = percent value, non-numeric columns become info. |
| schema | array | optional | Column definitions [{key, mode: flat|pct|text, base, min, max, desc}] (alternative to csv). A `name` text column is guaranteed. |
| rows | array | optional | Row values [{name: "blade", atk: 350, …}] (with `schema`). |
| registry | boolean | optional | true = this is the shared Stats registry (rows are stat definitions). |
| project_id | string | optional | Project id (from list_projects) to act on; omit = the connector URL's project. |
{
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Table name (e.g. \"Weapons\")"
},
"csv": {
"type": "string",
"description": "CSV text: header row + data rows. `atk` = flat value, `atk%` = percent value, non-numeric columns become info."
},
"schema": {
"type": "array",
"items": {
"type": "object"
},
"description": "Column definitions [{key, mode: flat|pct|text, base, min, max, desc}] (alternative to csv). A `name` text column is guaranteed."
},
"rows": {
"type": "array",
"items": {
"type": "object"
},
"description": "Row values [{name: \"blade\", atk: 350, …}] (with `schema`)."
},
"registry": {
"type": "boolean",
"description": "true = this is the shared Stats registry (rows are stat definitions)."
},
"project_id": {
"type": "string",
"description": "Project id (from list_projects) to act on; omit = the connector URL's project."
}
},
"required": [
"title"
],
"additionalProperties": false
}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.
| name | string | required | Board name (e.g. "Combat", "Economy") |
| nodes | array | required | Blocks. Examples: {kind:"const",name:"baseAtk",value:1000} · {kind:"formula",name:"dmg",formula:"atk - mdef"} · {kind:"sheet",name:"stats",base:{atk:1000}} · {kind:"picker",name:"monster",tableId,rowId} · {kind:"pool",name:"gold",inflow:"…",outflow:"…"} · {kind:"process",name:"refine",levels:[{p,fail,cost}],baseCost}. |
| project_id | string | optional | Project id (from list_projects) to act on; omit = the connector URL's project. |
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Board name (e.g. \"Combat\", \"Economy\")"
},
"nodes": {
"type": "array",
"items": {
"type": "object"
},
"description": "Blocks. Examples: {kind:\"const\",name:\"baseAtk\",value:1000} · {kind:\"formula\",name:\"dmg\",formula:\"atk - mdef\"} · {kind:\"sheet\",name:\"stats\",base:{atk:1000}} · {kind:\"picker\",name:\"monster\",tableId,rowId} · {kind:\"pool\",name:\"gold\",inflow:\"…\",outflow:\"…\"} · {kind:\"process\",name:\"refine\",levels:[{p,fail,cost}],baseCost}."
},
"project_id": {
"type": "string",
"description": "Project id (from list_projects) to act on; omit = the connector URL's project."
}
},
"required": [
"name",
"nodes"
],
"additionalProperties": false
}Propose a NEW milestone (with optional tasks) → Inbox to Adopt. Non-destructive.
| name | string | required | Milestone name |
| goal | string | optional | One-line goal (optional) |
| tasks | array | optional | Task names (optional) |
| acknowledge_rejection | boolean | optional | Only when a previous call bounced with 'the owner DECLINED this': pass true AFTER asking the user. Never pass it just to get past the gate. |
| project_id | string | optional | Project id (from list_projects) to act on; omit = the connector URL's project. |
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Milestone name"
},
"goal": {
"type": "string",
"description": "One-line goal (optional)"
},
"tasks": {
"type": "array",
"items": {
"type": "string"
},
"description": "Task names (optional)"
},
"acknowledge_rejection": {
"type": "boolean",
"description": "Only when a previous call bounced with 'the owner DECLINED this': pass true AFTER asking the user. Never pass it just to get past the gate."
},
"project_id": {
"type": "string",
"description": "Project id (from list_projects) to act on; omit = the connector URL's project."
}
},
"required": [
"name"
],
"additionalProperties": false
}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.
| id | string | optional | Milestone id from get_project_context (preferred) |
| milestone | string | optional | Existing milestone name (if no id) |
| done_tasks | array | required | Task names that are done |
| project_id | string | optional | Project id (from list_projects) to act on; omit = the connector URL's project. |
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Milestone id from get_project_context (preferred)"
},
"milestone": {
"type": "string",
"description": "Existing milestone name (if no id)"
},
"done_tasks": {
"type": "array",
"items": {
"type": "string"
},
"description": "Task names that are done"
},
"project_id": {
"type": "string",
"description": "Project id (from list_projects) to act on; omit = the connector URL's project."
}
},
"required": [
"done_tasks"
],
"additionalProperties": false
}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).
| id | string | optional | System id (preferred), from get_project_context / list_systems. |
| name | string | optional | Exact system name (if no id). |
| status | string | required | todo | in-progress | implemented |
| files | array | optional | Optional — the file PATHS that implement this system (the system->code map). ONE file per array entry; you MAY append its key function/class after the path, e.g. "Assets/Scripts/StatSystem/StatService.cs — StatService.recompute". Each entry = file + (optional) function ONLY. Do NOT put a comma-separated list, prose, test counts, or split one file across multiple entries. |
| decisions | array | optional | Optional — key build decisions / divergences from the design (this is where prose/notes go, NOT in files). |
| version | string | optional | Optional — the build/app version at which this system reached this status (e.g. "0.379.0"); shown in get_build_region + get_history so decisions anchor to a concrete build. |
| project_id | string | optional | Project id (from list_projects) to act on; omit = the connector URL's project. |
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "System id (preferred), from get_project_context / list_systems."
},
"name": {
"type": "string",
"description": "Exact system name (if no id)."
},
"status": {
"type": "string",
"description": "todo | in-progress | implemented"
},
"files": {
"type": "array",
"items": {
"type": "string"
},
"description": "Optional — the file PATHS that implement this system (the system->code map). ONE file per array entry; you MAY append its key function/class after the path, e.g. \"Assets/Scripts/StatSystem/StatService.cs — StatService.recompute\". Each entry = file + (optional) function ONLY. Do NOT put a comma-separated list, prose, test counts, or split one file across multiple entries."
},
"decisions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Optional — key build decisions / divergences from the design (this is where prose/notes go, NOT in files)."
},
"version": {
"type": "string",
"description": "Optional — the build/app version at which this system reached this status (e.g. \"0.379.0\"); shown in get_build_region + get_history so decisions anchor to a concrete build."
},
"project_id": {
"type": "string",
"description": "Project id (from list_projects) to act on; omit = the connector URL's project."
}
},
"required": [
"status"
],
"additionalProperties": false
}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).
| from | string | required | Source screen name |
| to | string | required | Destination screen name |
| label | string | optional | Transition label, e.g. 'Press Start' (optional) |
| project_id | string | optional | Project id (from list_projects) to act on; omit = the connector URL's project. |
{
"type": "object",
"properties": {
"from": {
"type": "string",
"description": "Source screen name"
},
"to": {
"type": "string",
"description": "Destination screen name"
},
"label": {
"type": "string",
"description": "Transition label, e.g. 'Press Start' (optional)"
},
"project_id": {
"type": "string",
"description": "Project id (from list_projects) to act on; omit = the connector URL's project."
}
},
"required": [
"from",
"to"
],
"additionalProperties": false
}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.
| screen | string | required | Existing screen name |
| label | string | required | Element label / role, e.g. 'HP bar', 'Skill slots' |
| type | string | optional | Element type hint, e.g. button/bar/panel/text (optional, default box) |
| x | number | optional | Optional — left position in px on the screen's canvas (place the element). |
| y | number | optional | Optional — top position in px (place the element). |
| w | number | optional | Optional — width in px (default 120). |
| h | number | optional | Optional — height in px (default 40). |
| note | string | optional | Optional — a note for AI / the designer about this element. |
| system | string | optional | Name of the System this element serves (optional) — recorded for traceability, e.g. 'Inventory System'. |
| project_id | string | optional | Project id (from list_projects) to act on; omit = the connector URL's project. |
{
"type": "object",
"properties": {
"screen": {
"type": "string",
"description": "Existing screen name"
},
"label": {
"type": "string",
"description": "Element label / role, e.g. 'HP bar', 'Skill slots'"
},
"type": {
"type": "string",
"description": "Element type hint, e.g. button/bar/panel/text (optional, default box)"
},
"x": {
"type": "number",
"description": "Optional — left position in px on the screen's canvas (place the element)."
},
"y": {
"type": "number",
"description": "Optional — top position in px (place the element)."
},
"w": {
"type": "number",
"description": "Optional — width in px (default 120)."
},
"h": {
"type": "number",
"description": "Optional — height in px (default 40)."
},
"note": {
"type": "string",
"description": "Optional — a note for AI / the designer about this element."
},
"system": {
"type": "string",
"description": "Name of the System this element serves (optional) — recorded for traceability, e.g. 'Inventory System'."
},
"project_id": {
"type": "string",
"description": "Project id (from list_projects) to act on; omit = the connector URL's project."
}
},
"required": [
"screen",
"label"
],
"additionalProperties": false
}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.
| name | string | required | Screen name (e.g. 'Inventory', 'Login') — Title Case, English. |
| purpose | string | optional | Optional — the note for AI: a one-line 'what this screen is for', used to ground element suggestions. |
| parent | string | optional | Optional — make this a POPUP overlaying this existing screen (its exact name). Omit for a normal full screen. |
| project_id | string | optional | Project id (from list_projects) to act on; omit = the connector URL's project. |
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Screen name (e.g. 'Inventory', 'Login') — Title Case, English."
},
"purpose": {
"type": "string",
"description": "Optional — the note for AI: a one-line 'what this screen is for', used to ground element suggestions."
},
"parent": {
"type": "string",
"description": "Optional — make this a POPUP overlaying this existing screen (its exact name). Omit for a normal full screen."
},
"project_id": {
"type": "string",
"description": "Project id (from list_projects) to act on; omit = the connector URL's project."
}
},
"required": [
"name"
],
"additionalProperties": false
}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.
| screen | string | required | Screen name (from list_screens). |
| status | string | required | todo | in-progress | implemented |
| project_id | string | optional | Project id (from list_projects) to act on; omit = the connector URL's project. |
{
"type": "object",
"properties": {
"screen": {
"type": "string",
"description": "Screen name (from list_screens)."
},
"status": {
"type": "string",
"description": "todo | in-progress | implemented"
},
"project_id": {
"type": "string",
"description": "Project id (from list_projects) to act on; omit = the connector URL's project."
}
},
"required": [
"screen",
"status"
],
"additionalProperties": false
}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.
| name | string | required | Exact CURRENT screen name. |
| new_name | string | required | New screen name (must not collide with another screen). |
| project_id | string | optional | Project id (from list_projects) to act on; omit = the connector URL's project. |
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Exact CURRENT screen name."
},
"new_name": {
"type": "string",
"description": "New screen name (must not collide with another screen)."
},
"project_id": {
"type": "string",
"description": "Project id (from list_projects) to act on; omit = the connector URL's project."
}
},
"required": [
"name",
"new_name"
],
"additionalProperties": false
}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.
| id | string | optional | Milestone id from get_project_context (preferred — unambiguous) |
| name | string | optional | Exact CURRENT milestone name (selects it, if no id; must be unique) |
| goal | string | optional | New goal text (optional) |
| weeks | number | optional | New week estimate (optional) |
| new_name | string | optional | New milestone name — rename in place (optional; must not collide with another milestone) |
| difficulty | string | optional | How hard this milestone is — a LABEL only, never part of the done count (optional; "" clears it) |
| project_id | string | optional | Project id (from list_projects) to act on; omit = the connector URL's project. |
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Milestone id from get_project_context (preferred — unambiguous)"
},
"name": {
"type": "string",
"description": "Exact CURRENT milestone name (selects it, if no id; must be unique)"
},
"goal": {
"type": "string",
"description": "New goal text (optional)"
},
"weeks": {
"type": "number",
"description": "New week estimate (optional)"
},
"new_name": {
"type": "string",
"description": "New milestone name — rename in place (optional; must not collide with another milestone)"
},
"difficulty": {
"type": "string",
"enum": [
"easy",
"medium",
"hard",
""
],
"description": "How hard this milestone is — a LABEL only, never part of the done count (optional; \"\" clears it)"
},
"project_id": {
"type": "string",
"description": "Project id (from list_projects) to act on; omit = the connector URL's project."
}
},
"required": [],
"additionalProperties": false
}Add a task to an existing milestone — applies DIRECTLY (in place, not a proposal). Identify the milestone by id (preferred) or unique name. Pass assignee:"me" to claim it as you create it.
| milestone_id | string | optional | Milestone id (preferred) |
| milestone | string | optional | Milestone name (if no id; must be unique) |
| name | string | required | Task name |
| done | boolean | optional | Mark it done on creation (optional, default false) |
| status | string | optional | Work-status LABEL — never part of the done count (optional) |
| effort | string | optional | Effort estimate (optional) |
| assignee | string | optional | Claim it on creation — "me" = you (optional) |
| project_id | string | optional | Project id (from list_projects) to act on; omit = the connector URL's project. |
{
"type": "object",
"properties": {
"milestone_id": {
"type": "string",
"description": "Milestone id (preferred)"
},
"milestone": {
"type": "string",
"description": "Milestone name (if no id; must be unique)"
},
"name": {
"type": "string",
"description": "Task name"
},
"done": {
"type": "boolean",
"description": "Mark it done on creation (optional, default false)"
},
"status": {
"type": "string",
"enum": [
"in-progress",
"blocked"
],
"description": "Work-status LABEL — never part of the done count (optional)"
},
"effort": {
"type": "string",
"enum": [
"S",
"M",
"L"
],
"description": "Effort estimate (optional)"
},
"assignee": {
"type": "string",
"description": "Claim it on creation — \"me\" = you (optional)"
},
"project_id": {
"type": "string",
"description": "Project id (from list_projects) to act on; omit = the connector URL's project."
}
},
"required": [
"name"
],
"additionalProperties": false
}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.)
| task_id | string | required | Task id (tk_…) from get_milestone |
| name | string | optional | New task name (optional) |
| done | boolean | optional | New done state (optional; true releases any claim) |
| status | string | optional | Work-status LABEL — never part of the done count (optional; "" clears) |
| effort | string | optional | Effort estimate (optional; "" clears) |
| assignee | string | optional | Claim/release: "me" = you; "" releases (optional) |
| force | boolean | optional | Take over another holder's claim (only when it's stale) |
| project_id | string | optional | Project id (from list_projects) to act on; omit = the connector URL's project. |
{
"type": "object",
"properties": {
"task_id": {
"type": "string",
"description": "Task id (tk_…) from get_milestone"
},
"name": {
"type": "string",
"description": "New task name (optional)"
},
"done": {
"type": "boolean",
"description": "New done state (optional; true releases any claim)"
},
"status": {
"type": "string",
"enum": [
"in-progress",
"blocked",
""
],
"description": "Work-status LABEL — never part of the done count (optional; \"\" clears)"
},
"effort": {
"type": "string",
"enum": [
"S",
"M",
"L",
""
],
"description": "Effort estimate (optional; \"\" clears)"
},
"assignee": {
"type": "string",
"description": "Claim/release: \"me\" = you; \"\" releases (optional)"
},
"force": {
"type": "boolean",
"description": "Take over another holder's claim (only when it's stale)"
},
"project_id": {
"type": "string",
"description": "Project id (from list_projects) to act on; omit = the connector URL's project."
}
},
"required": [
"task_id"
],
"additionalProperties": false
}The living design doc your AI coding agents read from — and write back to.
Your agent doesn't have a drift problem. Your plan does — it lives in your head and a doc no agent ever reads. Forge makes the plan machine-readable: structured Systems (Goal / Boundary / Acceptance) + milestones that agents read over MCP before they build, then propose changes back to — non-destructively. Design and build stay in sync, and your team stays aligned while agents work in parallel.
This repository is the public home of Forge's MCP connector — its registry manifest (
server.json) and connection docs. The Forge application itself is developed in a separate private repository.
Forge exposes your project's design to AI clients over the Model Context Protocol. An agent can read your Systems, milestones, and vision, then propose changes back to your Inbox — non-destructively, for you to adopt.
https://mmvdabzadclebfxyzudg.supabase.co/functions/v1/forge-mcpforge_sk_ account keyapp.forgeengine/forge on the official MCP RegistryAdd it as a custom connector pointing at the endpoint above, or install via the
official MCP registry entry (app.forgeengine/forge) once your client supports it.
// example: custom MCP connector
{
"forge": {
"url": "https://mmvdabzadclebfxyzudg.supabase.co/functions/v1/forge-mcp"
}
}
server.jsonHosted server - connect over the network, no local install.
https://mmvdabzadclebfxyzudg.supabase.co/functions/v1/forge-mcpclaude_desktop_config.json
{
"mcpServers": {
"forge": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://mmvdabzadclebfxyzudg.supabase.co/functions/v1/forge-mcp"
]
}
}
}Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.