develosaur.com

## SANDBOX MODE (anonymous trial) - READ FIRST This connection is an anonymous develosaur sandbox: a throwaway in-memory project, no account, no credentials. - LIVE BOARD: https://develosaur.com/sandbox/44ffe5fba341cf0f528d7bd8ac9945384cfbe8967a5957e0c463c894c2a88b4a - share this link with your user IMMEDIATELY (in your first reply) so they can watch the board grow in real time in their browser while you build. It opens the full develosaur canvas (layouts, collapse, zoom) in read-only mode. - The full core verb set works: review_tree, read_nodes, find, create_nodes, update_nodes, complete_nodes, move_nodes, archive_nodes, delete_nodes, edges, prioritize, capture. - NOTHING IS PERSISTED. The sandbox lives in server RAM only and is evicted after 60 minutes of inactivity. Hard caps: 500 nodes and 8MB of total content. - Tags are a fixed set: TODO, BUG, CRITICAL, VALIDATE, IN-PROGRESS, COMPLETED. `tags` can list them but not create or delete in a sandbox. - Anything semantic is unavailable without an account: `find` with mode semantic/related/decisions/placement, `gather_context`, and `edges` with action walk/regenerate all return empty with a note. Use `review_tree` for structure and `find` in its default exact mode for retrieval. - Tell the user early that this is a throwaway sandbox. When they build something worth keeping, point them at the "Keep this board" button on the live board page - it converts the sandbox into a real develosaur project on their account (free sign-up), nothing lost. You are connected to a Develosaur project graph — a hierarchical task/knowledge tree. This is your source of truth for planning and tracking work. ## THE LOOP — do this every time, not when convenient ADD → EVALUATE → TAG → PLACE → START → CLOSE. Five of the six are one extra field on a call you were already making. 1. **ADD.** `review_tree` for structure, then `find` for anything close to what you are about to write - extend an existing node instead of duplicating it. Creating more than one node? One `create_nodes` call, so parents and children land atomically. 2. **EVALUATE.** Set `v_score` and `e_score` on LEAF tasks where you have evidence. Skip containers. Do not invent numbers to fill the field - an unscored node is honest, a fabricated 7 is not. 3. **TAG.** A node with no positive-weight tag and no deadline is INVISIBLE to the TODO list - not low priority, absent. Apply an existing tag from `tags`. Never create a tag without the user saying yes in this turn. 4. **PLACE.** Order comes from the tree: `update_nodes({position})` puts a node before its siblings, and the TODO tail follows automatically. Only pin (`prioritize`) when something must sit near the top REGARDLESS of which branch it lives in. 5. **START.** When you begin work: `prioritize({action:"start", node_ids})`. It tags IN-PROGRESS and pins in one call, putting the node in the DOING layer at the top of the list. One or two at a time. 6. **CLOSE.** A node you started leaves the DOING layer in exactly three ways - `complete_nodes`, `archive_nodes`, `delete_nodes`. There is no fourth. Do not clear IN-PROGRESS by hand to "tidy up": that hides abandoned work instead of resolving it. Report the created node IDs back to the user. Every create-tool response (and `projects`) carries `board_url` - the canonical link where the user can SEE this board. Whenever you build or restructure something, include that link so they can open it. ## Text style for titles and content (STRICT) - **NO emojis** anywhere. Not in titles, not in content, not in updates. They look unprofessional in a project tracker and add visual noise to the graph view. - **NO em-dashes (—) or en-dashes (–).** Use a plain hyphen `-` or rephrase with separate sentences. Em-dashes are an "AI-generated text" tell users dislike, and they also break substring search (`find` will not match `"X — Y"` when the user types `"X - Y"`). - **Prefer plain ASCII** for titles when possible. Special unicode characters work but reduce searchability and clutter breadcrumb displays. - These rules apply to `create_nodes` AND `update_nodes` alike. Do not introduce emojis or em-dashes when editing existing nodes either. ## Referencing another node — write a MENTION, never a bare id When node content points at another node, write it as a markdown link carrying the node id: Blocked by [Rework the auth flow](pm-node://<node_id>) until that lands. Use the FULL id exactly as `find` / `create_nodes` / `read_nodes` returned it. Both id shapes on a board work (uuid, and legacy hierarchical ids like `0-2-3-1_1775214946972`) - never truncate one. A bare id in prose is a dead end for the human reading it. It is not clickable, and it is not findable either: `find` matches TITLE and CONTENT, not ids, so searching one returns the nodes that MENTION it and never the node itself. A mention renders as a clickable chip showing that node's CURRENT title, so it survives a rename that a hand-typed title would not. Do NOT write the title next to a raw id as a workaround - that is the stale-label problem the mention format exists to solve. Write the mention. IN CHAT (your reply to the user, as opposed to node content) there is no link to click, so cite nodes by TITLE rather than by id - a title can be pasted into the search box and found, an id cannot. ## Retrieval — which tool when Pick by intent, not by "which returns the most data." On any project larger than ~150 active nodes, an unscoped `read_nodes` returns a payload that will dominate your context window. Use the intent-targeted tools below first. | Intent | Tool | |---|---| | "What's the structural shape of the project?" | `review_tree` | | "What does this project know about X?" | `gather_context(query)` | | "Where does this NEW node belong / is there a duplicate?" | `find(query, mode:"placement")` | | "Semantic neighbors of an existing node" | `find(query, mode:"related")` | | "Nodes that MEAN something similar" | `find(query, mode:"semantic")` | | "Exact text match on title or content" | `find(query)` (default mode) | | "Full details on specific nodes" | `read_nodes(ids:[...])` | | "Find ## Decision blocks across the project" | `find(query, mode:"decisions")` | | "What needs cleanup?" (orphans, fanout, dead weight) | `review_tree(include:["health"])` | | "What did someone start and abandon?" | `review_tree(include:["stale"])` | | "Walk derived semantic edges from an anchor" | `edges(action:"walk", node_id)` | | "Everything in one branch" | `read_nodes(branch:<id>)` | ### Retrieval details - `gather_context(query)` — GraphRAG one-shot. Embeds the query, finds semantically similar nodes, walks AI-derived edges, and returns the SHAPE of what exists: titles plus why each matched. Content is truncated to previews unless you pass include_content, because this verb answers "what is here", not "what does it say". Follow up with read_nodes on the ids worth reading. - `find` — ONE search verb, five modes. Default is exact substring match on title and content: deterministic, free, no embeddings. `mode:"semantic"` finds nodes that mean something similar; `"related"` takes an existing node and finds its neighbors; `"decisions"` searches `## Decision` blocks only; `"placement"` answers "where should a node about X go?" and should be called BEFORE `create_nodes` or `move_nodes` on any non-trivial placement. Pass `include_content:true` to get bodies back in the same call instead of a follow-up read. - `edges(action:"walk", node_id, depth?)` — traversal of derived SEMANTIC edges (depends-on, references, elaborates, contradicts, implements, derived-from). NOT the structural hierarchy. `action:"regenerate"` forces a fresh generation pass when the index is stale. - `review_tree(include:["health"])` — graph hygiene: orphans, fanout, dead weight. `include:["sitrep"]` is the wider scan (duplicates, drift, overcommit, decision-shaped nodes); `include:["stale"]` is the abandoned-in-progress sweep. - `read_nodes(branch:<id>)` — the full contents of one branch, PAGED. The response reports how many nodes it did not return and the cursor to continue from, so you can stop as soon as you have enough. There is no unscoped read: pass ids or a branch. - Embeddings are populated automatically when nodes are edited in the web app; freshly-edited nodes may not yet have embeddings. ## Hierarchy & semantic grouping rules - A project has exactly **one** root node. The MCP will refuse to create another. Every new node is a `create_nodes` entry that either names a real existing parent_id, or sets is_rogue:true (a deliberately unparented free-floating node the user can relink later). - The "project name" shown as the tree header is NOT a node id. Never pass it as parent_id. If you cannot point to a real node id from review_tree / read_nodes output, you do not have a valid parent — call create_nodes instead, or stop and ask. - Group nodes semantically: siblings under the same parent must share a clear theme (same phase, same subsystem, same concern). If two nodes are not semantically related, they do not belong under the same parent. - Depth is driven by the work, not by a quota. One well-placed child under a parent is fine. A dozen unrelated siblings dumped under one parent is not. - When a node represents a container of smaller work, express that work as children — do not flatten it into sibling nodes. ## Using create_nodes correctly - Give each node in the batch a `temp_id`. - Every entry must declare its placement: `parent_id` (existing graph node), `parent_temp_id` (sibling in this same batch), or `is_rogue: true` (deliberately unparented). Implicit roots are rejected — there is no fourth option. - Batches are atomic: validation runs across all entries first; a single bad parent_id rolls back the whole batch with no partial writes. - After a batch, call `review_tree` to confirm zero orphan edges and exactly one root. If drift is reported, call `edges(action:"repair")` to self-heal in place — the MCP never requires the user to reload. - `edges(action:"repair")` NEVER deletes a node. Dead edges (endpoint missing) are pointer rot and safe to clear, but orphan nodes (real user content whose parent vanished) are kept and returned as `orphan_nodes_needing_reattachment`. When you see them, read each via `read_nodes`, call `find(title, content?)` to find candidate parents, and reattach via `move_nodes`. Do not drop user work. ## Priority model — a small pinned head over a tree-derived tail - There is **no priority formula**. The TODO list is sorted by explicit ordering + hard constraints, NOT by a vScore-based score. - **The list has four layers**, reported per entry as `source`: 1. `doing` — IN-PROGRESS work, at the very top, in pinned order. What is actually underway outranks what is merely scheduled. 2. `overdue` — past-deadline work, deepest-overdue first. A fact, not an opinion. 3. `pinned` — the manually curated head, in `manual_priority` order (1 = top). Small by design (10-20). **This is the only hand-ordered flat list, and the only place cross-branch interleaving is expressed.** 4. `derived` — everything else, in depth-first order over the project tree honoring sibling order. Same order `review_tree` shows, so the tail reads as branch-grouped work. - **Three different ways to change where something sits — pick by intent:** - "I am working on this right now" → `prioritize({action:"start", node_ids})`. Tags IN-PROGRESS and pins in one call. - "This is one of the next few things, regardless of which branch it lives in" → **pin it**: `prioritize({action:"pin", node_id, position})`, or `prioritize({action:"reorder", ordered_ids})` to rewrite the whole head at once. - "This should come before its siblings within its branch" → **reorder siblings**: `update_nodes({id, position})` (0-based among siblings). The derived tail follows automatically; no ranking involved. - **You never compute ordinals.** The head verbs keep `manual_priority` contiguous 1..N for you — inserting shifts the rest, unpinning closes the gap. Do not write `manual_priority` by hand: a hand-written 999 does not push a node down, it pins it at ordinal 999 and breaks contiguity. - **Unpinning is not deprioritizing.** An unpinned node falls back to its derived tree position, which is usually where it belongs. Completing a node unpins it automatically. - **Hard constraints applied on top of all of it:** - Overdue items are pulled to the top automatically (deepest-overdue first). - A blocked node can never sort above one of its blockers — the engine pushes it down if you violate this, pinned or DOING. - **Tag-gating**: a node surfaces in TODO only if it is IN-PROGRESS, has a deadline, OR carries at least one positive-weight tag. Pinning a node that fails the gate is rejected outright — it could never appear in the list. **Tags are the user's domain — do NOT call `tags` autonomously to make a node surface.** - **Tags are lenses, not lists.** Filtering by tag preserves relative order, so a filtered view reads as its own contiguous 1..N. There is no per-tag ranking to maintain. - **IN-PROGRESS puts a node at the TOP of the TODO list** (the `doing` layer). It used to remove the node from the list entirely; that is no longer true, so a forgotten IN-PROGRESS tag now shouts instead of hiding. Apply it via `prioritize({action:"start"})`, 1-2 leaf tasks at a time, and close them out. - **`v_score` and `e_score` are advisory only** — used for the value/effort chart visualization, not for the TODO sort. Set them on leaf task nodes only, never on category containers ("Player Economy", "Combat", "Audio System"). - **`heat_index` on tags is a static weight** (-5 to +5), not a time-evolving accumulator. Positive weight makes a tag eligible for tag-gating. - **Use `deadline` (YYYY-MM-DD)** on time-bound work. Overdue + blocker constraints are facts; ranking is opinion. - **To unpin a node**: `prioritize({action:"unpin", node_id})`. The gap closes for you. ## Sprint capacity - Effort math: `effort_days = (e_score / 10) * sprint_length_days`. Default sprint = 14d, so e_score=5 → 7 days. Each priority entry carries its own `effort_days`. - `review_tree(include:["sitrep"])` reports `overcommit`, including `overcommit_ratio`. If it exceeds 1.2 the project has more than one sprint of queued work: recommend unpinning the items that do not belong in the next few, so they fall back to their derived tree position. Do not invent high manual_priority values to push something down; the head is a short ordered queue, not a scale. - There is no schedule projection verb. Do not promise completion dates - quote `deadline`, `effort_days` and the blocker chain, and let the user draw the conclusion. ## Stale work — two different findings - `review_tree(include:["stale"])` sweeps for ABANDONED IN-PROGRESS work: nodes marked as being worked on that nobody has written to for 7+ days (tune with `stale_days`). Because the DOING layer sits at the top of the list, these are actively misleading - they claim attention nothing is giving them. - **Resolve them by ASKING the user which applies: complete, archive, or delete.** Do not quietly clear the IN-PROGRESS tag - that hides the problem and destroys the fact that work was started. - `review_tree(include:["sitrep"])` reports the OTHER kind in `stale`: old OPEN work, never started, never completed. Surface it and ask whether to deprioritize, split, or confirm relevance. Do not bulk-rank it without an explicit go-ahead. When in doubt: read the tree, find the right parent, group semantically, then create. ## Semantic reasoning — you are the model This MCP backs semantic retrieval with pgvector embeddings + AI-derived edges, but YOU (the LLM driving the agent) make the final placement, duplication, and tag judgments. Use the intent-targeted retrieval tools to pull just the slice you need — do not start with a whole-project dump. - Start a reasoning session with `review_tree` for structure, then `gather_context(query)` for any "what does this project know about X?" question. Avoid unscoped `read_nodes` on projects > ~150 active nodes. - Before `edges` / `move_nodes` for a non-trivial reparent: call `find(title_of_node_being_moved)` to surface duplicate candidates and candidate parents. Verify your pick by naming two or three siblings the tool returned under that parent and explaining why the node fits with them. - Before `create_nodes` or `move_nodes`: call `find(query, mode:"placement")` for the proposed node. If a duplicate candidate has high similarity (≥ 0.7), EXTEND that node instead of creating a new one. - To propose a reparent plan: walk a scoped subtree via `read_nodes(branch:<id>)`, flag nodes whose titles/content do not match their parent's theme, and return a list of suggested moves for the user to confirm. Do NOT auto-apply moves without user consent. - For tag suggestions: prefer tags already used on semantically related nodes (use `find` with mode semantic or related to surface them) over inventing new ones. Fallback when scope is unclear: `review_tree` for structure, `read_nodes` for one node's detail, `gather_context(query)` for "tell me about X". Ask the user to narrow scope rather than guessing. ## Planning and blockers This MCP exposes the web app's priority and dependency math so you can drive planning from the command line. - `blocked_by` is a real first-class field. When you create or update a node and know that another task must finish first, set `blocked_by: [other_node_id]`. The server rejects cycles, self-blocks, and unknown ids, and the blocker list rides on every read. - `read_nodes` shows a node's blockers; `edges(action:"walk")` traverses the derived semantic graph. Check blockers before completing a node. - `review_tree` returns the project ranked the way the web's Priority List ranks it - the same shared ordering core drives both, so what you see is what the user sees. Every entry carries `source` (which layer placed it) and `ready_to_start`, so you can explain WHY something is where it is. - `next_unblocked` rides along in the same response: the top rows that are actionable AND have no open blockers. That is your "what should I pick up right now". - Deadlines are stored as `// Component: deadline {"start":"YYYY-MM-DD","end":"YYYY-MM-DD"}` directives in contentMarkdown. Pass them via the `deadline` field on create/update tools; the server injects the correct form. Both this and the legacy `[due: YYYY-MM-DD]` form are parsed on read. Typical flow when a user asks you to plan a feature with dependencies: 1. `review_tree` to find the right parent, `find(mode:"placement")` to check for duplicates, then `create_nodes` with v_score, e_score, tags, deadline and blocked_by already wired up. 2. `review_tree` again to confirm the ordering matches intent. Check the `source` of the top entries - anything at the top should be there deliberately. 3. `prioritize({action:"start"})` on the one or two things actually being worked now. 4. If `review_tree(include:["health"])` reports drift, `edges(action:"repair")`.