writing-plans

What it does

writing-plans is one 204-line file that prescribes a plan the way other skills prescribe code. Every plan must open with a fixed header (goal, architecture, tech stack, the spec it implements), a Global Constraints section carrying the spec’s exact values, and a Review Focus section: the five input classes or failure modes the spec implies but no task’s tests exercise, written down once, each with a test pinned to the task that owns the code.

Below the header, work is decomposed into tasks sized to “the smallest unit that carries its own test cycle and is worth a fresh reviewer’s gate”. Each task states its files, and — the detail that does the most work — an Interfaces block: what the task consumes from earlier tasks and what it produces, with exact function names, parameter and return types, because “a task’s implementer sees only their own task”. Steps are checkboxed, one action each, cycling write-the-failing-test, run it, implement, run it, commit. The skill is equally specific about what a step may not contain: “Lines that decide nothing (‘TBD’, ‘handle edge cases’, ‘add appropriate validation’, ‘write tests for the above’) are the opposite failure” of a plan that transcribes the whole program.

It closes with a five-point self-review (spec coverage, step scan, type consistency, review focus, proportion) and a hard stop: the plan is linked for the human to read, and implementation waits until they have reviewed it and chosen how to execute.

How the live test went

We ran one brief twice — plan an email/password login with server-side sessions for a small Flask app whose users table exists but is unused, for handover to a developer who has never seen the code. Both plans are published in full with this review.

The baseline is genuinely good. In 90 lines it covers the database work, names werkzeug for hashing, lists the cookie flags, insists on generic login errors, and puts tests and security in their own sections. Most teams would accept it. But read it as the receiving developer: the model functions are named, never signed — every interface gets invented at the keyboard, by whoever writes that task, possibly inconsistently across tasks. Testing is one closing section. There is exactly one commit instruction, in the final sentence.

The with-skill plan is 324 lines and leaves the receiving developer almost nothing to invent. The unused users table gets a pinned schema and a stated decision — drop and recreate it if it differs, because it holds no data. Session expiry is a number (604800 seconds) used identically in the database and the cookie. The identical-failure requirement is not a principle in a checklist; it is a test asserting unknown.data == wrong.data. Fourteen tests exist as code, eleven steps give a command and the output that means it worked, and each of the five tasks ends in its own commit. The Review Focus section earns its place: of its five failure modes, two (expired-token cleanup, forged-cookie handling) are things the baseline plan mentions nowhere.

Where it falls short

Start with the trigger: the description has no when-not boundary, so the only thing standing between a two-line fix and a five-section planning ceremony is the phrase “multi-step task”. Second, ecosystem lock-in is baked into the output itself — every plan’s header instructs the executor to use superpowers:subagent-driven-development or superpowers:executing-plans, which is dead weight (or an unmet dependency) outside the Superpowers plugin. Third, thin inputs expose a seam: Global Constraints demands values “copied verbatim from the spec”, but our brief was one paragraph, so the plan pinned values the spec never contained — 604800 seconds, the session_id cookie name — without marking which values came from the spec and which the planner chose. The decisions are good ones. A reader still cannot tell them apart from requirements. Finally, our with-skill run added a task the brief never asked for (protecting item creation) — hedged with an explicit fallback, but the skill’s Scope Check only guards against specs that are too big, not plans that quietly grow.