From 6eedb0f6b955d99975d607bdb56b3371ecbd8968 Mon Sep 17 00:00:00 2001 From: Bryan Van Deusen Date: Fri, 31 Jul 2026 20:39:20 -0400 Subject: [PATCH] fix(instructions): stop mandating a milestone for every non-trivial task MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Four product surfaces told the agent to call start_planning FIRST for any "non-trivial" work, while a fifth — the milestone bullet four lines up in the same file — had the criterion right: use one when the work has an arc. The loudest surface won, so sessions wrapped bug fixes and one-file changes in milestones that never meant anything. Mandating one project shape is what rule #115 forbids: some projects are milestone-shaped, others are a flat task list and always will be. Now the arc test is stated ONCE in full, in writing-plans, along with what to do when there is no arc (a task, driven by status and work-logs). The other surfaces name it and defer: - writing-plans/SKILL.md gains a "first decide whether this work wants a plan" section; its frontmatter trigger is the arc, not "non-trivial" - using-scribe reflex #4 points at the skill instead of restating it - server.py's Plan bullet adopts the milestone bullet's own criterion - server.py's planning paragraph drops from 11 lines to 6: it keeps the claim MCP instructions should make (a plan's HOME is a milestone, not a local .md) and drops the how, which the skill carries - start_planning's docstring gains the when Also removed "call start_planning FIRST — before any brainstorming, design, or plan-writing skill runs." That was the server asserting priority over the skill layer. Tools describe what they do; skills decide when they apply. The structural point outlasts the wording: a surface that restates a rule is a surface that will eventually contradict it, and nothing checks prose against prose. Closes #2322. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01UaYUaouG9jjhATyuxCKrQs --- plugin/skills/using-scribe/SKILL.md | 12 ++++++----- plugin/skills/writing-plans/SKILL.md | 30 ++++++++++++++++++++++------ src/scribe/mcp/server.py | 29 ++++++++++++--------------- src/scribe/mcp/tools/tasks.py | 6 ++++++ 4 files changed, 50 insertions(+), 27 deletions(-) diff --git a/plugin/skills/using-scribe/SKILL.md b/plugin/skills/using-scribe/SKILL.md index fab80e1..43184ea 100644 --- a/plugin/skills/using-scribe/SKILL.md +++ b/plugin/skills/using-scribe/SKILL.md @@ -64,11 +64,13 @@ Two constraints on *how* that's achieved: 3. **Update over duplicate.** When recording, prefer updating an existing note/rule/task over creating a new one. Search first; revise what's there. -4. **Plans live in Scribe.** For non-trivial work call `start_planning(project_id, - title)` FIRST — it creates a milestone whose `body` holds the design; each - step is its own task under that milestone (`create_task(milestone_id=...)`), - progress goes in work-logs (`add_task_log`). Read it back with `get_milestone`. - Do not write plans/specs to local `.md` files. +4. **When you plan, plan in Scribe.** Work with an *arc* — several steps toward + one goal — gets a plan, and a plan is a milestone: `start_planning(project_id, + title)` creates one whose `body` holds the design, each step is its own task + under it (`create_task(milestone_id=...)`), progress goes in work-logs + (`add_task_log`). Work without an arc (a fix, a one-file change, a question) + is just a task — don't wrap it in a milestone. Either way, do not write + plans/specs to local `.md` files. See the **writing-plans** skill. 5. **Keep state honest.** Set a task `in_progress` when you start it, `done` the moment it's complete; log progress as you go. diff --git a/plugin/skills/writing-plans/SKILL.md b/plugin/skills/writing-plans/SKILL.md index 8ef8d80..67bf6f7 100644 --- a/plugin/skills/writing-plans/SKILL.md +++ b/plugin/skills/writing-plans/SKILL.md @@ -1,6 +1,6 @@ --- name: writing-plans -description: Use before starting any non-trivial or multi-step piece of work — produce a clear plan BEFORE diving in. Triggers when the user asks you to plan, design an approach, scope an effort, or tackle work big enough to need ordered steps. The plan lives in a Scribe milestone (via start_planning), not a local file. +description: Use when a piece of work has an arc — several steps toward one goal, worth tracking as a unit — and you want the approach reviewable before you start. Triggers when the user asks you to plan, design an approach, or scope an effort, or when work is about to sprawl across several steps. Not for single-step work. The plan lives in a Scribe milestone (via start_planning), not a local file. --- # Writing plans @@ -9,12 +9,30 @@ A plan is **how** you'll execute a chunk of work — the design plus an ordered set of steps — written *before* you start, so the approach is reviewable and the work stays trackable. -## Start the plan in Scribe, not a file +## First decide whether this work wants a plan -For non-trivial work, call **`start_planning(project_id, title)` FIRST** — -before any design or implementation. It creates a **milestone** (the plan -container) seeded with a design template and returns the milestone id plus the -project's applicable rules. The plan lives in that milestone: +A plan lives in a milestone, and **a milestone earns its place when the work has +an arc**: several steps, one shared goal, a beginning and an end worth tracking +as a unit. That is the whole test, and it is a judgment about the *shape* of the +work — not about its size, difficulty, or importance. + +Plenty of real work has no arc. A bug fix, a one-file change, a question +answered, a setting changed. For those, a milestone is a container with one +thing in it: the ceremony costs more than it records, and it leaves the project +with milestones that never meant anything. **Use a task instead** — set it +`in_progress`, record what you find with `add_task_log`, set it `done`. That is +a complete, honest record of work that didn't need a plan. + +Some projects are milestone-shaped and some are a flat task list. Read the +project you are in rather than imposing a shape on it. + +## When it does: start the plan in Scribe, not a file + +Call **`start_planning(project_id, title)`** before designing or implementing — +so the milestone exists to write into, rather than being backfilled from work +already done. It creates a **milestone** (the plan container) seeded with a +design template and returns the milestone id plus the project's applicable +rules. The plan lives in that milestone: - The **design/intent** goes in the milestone `body` — edit it with `update_milestone(milestone_id, body=...)`. diff --git a/src/scribe/mcp/server.py b/src/scribe/mcp/server.py index a7f1633..79886dd 100644 --- a/src/scribe/mcp/server.py +++ b/src/scribe/mcp/server.py @@ -33,11 +33,12 @@ What each part is for, and when to reach for it: - Plan: a MILESTONE acting as a plan container — HOW you'll execute a chunk of work. The design/intent lives in the milestone `body`; each step is its own child task (create_task(milestone_id=...)), tracked with status + work-logs — - NOT a checkbox buried in the body. Start one with start_planning when - beginning non-trivial work, before you dive in; read it back with - get_milestone (body + steps). (The old kind=plan task is retired — some - historical plan-tasks still exist and remain readable, but don't create new - ones.) + NOT a checkbox buried in the body. Create one with start_planning when the + work has an arc (same test as a milestone, above) and you want the approach + reviewable before you start; read it back with get_milestone (body + steps). + Work without an arc is a task, not a plan. (The old kind=plan task is retired + — some historical plan-tasks still exist and remain readable, but don't + create new ones.) - Note: durable free-form knowledge — reference material, decisions, logs of what happened. No lifecycle, not actionable. Reach for one to CAPTURE something worth keeping. @@ -184,17 +185,13 @@ adopting or creating — never do either silently, and never guess a project int existence. Once a project is in scope, the enter_project handshake and the host-memory pointer step above both apply. -A plan is a MILESTONE, and Scribe is the canonical home for it. When you begin -non-trivial work, call start_planning(project_id, title) FIRST — before any -brainstorming, design, or plan-writing skill runs. start_planning creates the -milestone, seeds its `body` with the design template, returns the project's -applicable_rules, and gives you the milestone id you'll write into. Put the -design/intent in the milestone body via update_milestone(milestone_id, body=...); -create each step as a child task with create_task(milestone_id=...) and track it -with status + add_task_log — do NOT list steps as checkboxes in the body. Read -the plan back with get_milestone (body + steps). If a habit tells you to save a -plan or spec to a local `.md` file, that's superseded here: the milestone is the -record, not a local file. +When work DOES get a plan, Scribe is the plan's canonical home: it is a +milestone (see the Plan entry above), created with start_planning and written +into with update_milestone + child tasks. If a habit tells you to save a plan or +spec to a local `.md` file, that's superseded here — the milestone is the +record, not a file on disk. Whether a given piece of work wants a plan at all is +a separate question, answered by the arc test above and by the writing-plans +skill; these instructions do not mandate one. Deletes are recoverable: every delete_* tool moves the entity (and its descendants) to the trash and returns a deleted_batch_id. Use list_trash() to diff --git a/src/scribe/mcp/tools/tasks.py b/src/scribe/mcp/tools/tasks.py index ffbcb2a..8d633f0 100644 --- a/src/scribe/mcp/tools/tasks.py +++ b/src/scribe/mcp/tools/tasks.py @@ -276,6 +276,12 @@ async def add_task_log(task_id: int, content: str) -> dict: async def start_planning(project_id: int, title: str) -> dict: """Begin a plan in Scribe (the preferred home for plans — not a local .md file). + Reach for this when the work has an ARC — several steps toward one goal, + worth tracking as a unit. Work without one (a fix, a one-file change, a + question answered) is a task, not a plan: create_task, drive its status, and + record progress with add_task_log. A milestone holding a single step is + ceremony, and it leaves the project with a plan that never meant anything. + Creates a MILESTONE that IS the plan: its `body` is seeded with a design template (Goal/Approach/Verification) under the given project, and the call returns it together with the project's applicable Rulebook rules and brief