writing-plans

Converts approved designs into executable OpenSpec task checklists or Beads work contracts.

Updated Aug 2, 2026
One-click install
npx skills add https://github.com/leonardoacosta/skills --skill writing-plans-leonardoacosta
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: writing-plans
Source: https://github.com/leonardoacosta/skills/tree/main/leo-core/skills/writing-plans
Command: npx skills add https://github.com/leonardoacosta/skills --skill writing-plans-leonardoacosta

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Engineers and subagents often receive vague feature specs and must guess at file paths, test commands, and task ordering, which causes rework and failed handoffs. This Skill turns an approved design into a complete, zero-context execution contract with exact files, code, commands, and verification steps. ## Core Features & Use Cases - Canonical Task Authoring: Writes bite-sized tasks (write failing test, verify failure, implement, verify pass, commit) directly into the repository's OpenSpec tasks.md or a single Beads issue, never a side ledger. - Anti-Pattern Enforcement: Bans placeholders like "TBD" and "add error handling", and scans for vague acceptance criteria, missing rollback notes, hidden reverse dependencies, and mismatched test frameworks. - Self-Review and Optional Subagent Review: Provides a three-step self-review checklist (spec coverage, anti-pattern scan, type consistency) plus a dispatch template for an independent plan-document reviewer subagent. - Use Case: After a design is approved for a new API endpoint, use this Skill to produce an OpenSpec change whose tasks an engineer with zero codebase context can execute step by step, then hand off to the apply execution lane. ## Quick Start Ask the agent to use the writing-plans skill to turn the approved design spec into an executable OpenSpec task breakdown before any code is written.

Frequently Asked Questions about writing-plans

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write an implementation plan from a design spec?

Map the file structure first, then decompose the work into atomic tasks following the write-test, verify-fail, implement, verify-pass, commit pattern. Each step must contain exact file paths, complete code, and commands with expected output so an engineer with zero context can execute it.

How granular should tasks be in an implementation plan?

Each step should be one atomic action taking roughly 2-5 minutes. Subagent-driven or interrupted execution resumes at any arbitrary step, so every step must stand alone without depending on memory of previous steps.

Where should the implementation plan be stored?

Plans live in the repository's canonical workflow artifact: the OpenSpec change's tasks.md for proposal-lane work, or a single enriched Beads issue for ad-hoc work. Standalone plan documents and duplicate checklists are explicitly prohibited.

What are common implementation plan anti-patterns to avoid?

Avoid placeholders like TBD, vague acceptance criteria, missing rollback notes on schema or infrastructure tasks, hidden reverse dependencies in task ordering, and test instructions naming frameworks the codebase does not use. The references directory lists each with rationale.

When should a plan get an independent subagent review?

Self-review is sufficient for most plans. Dispatch a fresh reviewer subagent for larger or higher-risk plans that span many tasks or multiple subsystems, using the provided plan-document-reviewer-prompt template with its Approved or Issues Found output format.