bvandeusen
f7742173aa
Audit of the plugin + MCP surface after milestone-as-plan (T3): every path that could still create a kind=plan task or describe the old plan-task model is now aligned with the hard-retire decision. - create_task (MCP + REST POST /api/tasks): reject kind=plan with a message pointing to start_planning. The 'plan' enum value stays valid so legacy plan-tasks remain readable; update paths never touch kind, so they round-trip. - create_task / get_task docstrings: 'plan' dropped from creatable kinds; get_task's rules-augmentation noted as legacy-only (get_milestone for new plans). - skills/writing-plans: rewritten for milestone-as-plan (body = design, steps = child tasks, get_milestone to read back). - skills/using-scribe: "plans live in milestones via start_planning", not kind=plan. - TaskEditorView Kind selector: offers Work/Issue; "Plan (legacy)" shown only when the loaded task is already kind=plan (display round-trip). - test: create_task rejects kind=plan. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2.8 KiB
name, description
| name | description |
|---|---|
| writing-plans | 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. |
Writing plans
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
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:
- The design/intent goes in the milestone
body— edit it withupdate_milestone(milestone_id, body=...). - Each step is its own task under the milestone — create it with
create_task(milestone_id=<that milestone>)and track it with status +add_task_log. Steps are first-class tasks, not checkboxes in the body. - Read the whole plan back with
get_milestone(body + its step-tasks).
Do not write plans or specs to local .md files — the milestone is the
record, not a file on disk. (The old kind=plan task is retired; start_planning
no longer creates one.)
Before designing from scratch, recall: search Scribe for a related prior
plan or decision. Often the thinking (or half of it) already exists.
What a good plan contains
- Goal — what "done" looks like, and why, in a sentence or two (milestone body).
- Approach — the key design decisions and the trade-offs you chose, briefly (milestone body).
- Steps — an ordered set of step-tasks under the milestone, each small enough to verify on its own; note which files/areas each touches.
- Verification — how you'll know it actually works (a test, CI, an observable behavior), not just "it's written."
While executing
- Keep the plan honest: drive each step-task's status (todo →
in_progress → done) as it lands; record decisions, findings, and pivots with
add_task_logon the relevant step rather than silently rewriting the body. - If reality diverges from the plan, update the milestone body — a design that no longer matches what you're doing is worse than none. Add or re-scope step-tasks as the work changes.
- Mark the milestone
donewhen its steps are complete.
Match depth to the work
A two-step change deserves a two-line plan; a multi-day effort deserves a fleshed-out milestone body and several step-tasks. Don't over-plan the trivial, and don't under-plan something that will sprawl. The point is a shared, reviewable intent — not ceremony.