From 30fbf7b117bb5449fe2a513070300bacc0935879 Mon Sep 17 00:00:00 2001 From: Bryan Van Deusen Date: Thu, 28 May 2026 18:25:38 -0400 Subject: [PATCH] docs(mcp): add conceptual primer (what each entity is for) to MCP instructions --- src/fabledassistant/mcp/server.py | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/src/fabledassistant/mcp/server.py b/src/fabledassistant/mcp/server.py index 561b93d..f9443ad 100644 --- a/src/fabledassistant/mcp/server.py +++ b/src/fabledassistant/mcp/server.py @@ -11,6 +11,23 @@ store. You (Claude) are the assistant. Hierarchy: Project -> Milestone -> Task/Note. +What each part is for, and when to reach for it: +- Project: the top-level container for a body of work. +- Milestone: groups related tasks within a project toward a goal (status + active/done). Use one when a chunk of work needs its own arc. +- Task: a unit of actionable work with a lifecycle (status + todo/in_progress/done/cancelled, optional priority). A task is a note with a + status — reach for one when there is something to DO. Record progress over + time with work-logs (add_task_log) rather than rewriting the body. +- Plan: a task with kind=plan — HOW you'll execute a chunk of work. The body + holds the design + step checklist; work-logs record progress. Start one with + start_planning when beginning non-trivial work, before writing code. +- Note: durable free-form knowledge — reference material, decisions, dev-logs. + No lifecycle, not actionable. Reach for one to CAPTURE something worth keeping. +- Typed entities (person/place/list): structured records about people, places, + and checklists. + +Mechanics: - Notes and Tasks share a model; tasks are notes with is_task=True. - Use the *_note tools for notes, the *_task tools for tasks. Don't mix them. - Typed entities (person, place, list) are notes with a non-default note_type