Writing Plans Plus

Overview

This skill extends superpowers:writing-plans with structured task definitions that are machine-readable and provide explicit completion tracking. Use this when you want plans that can be easily parsed, executed programmatically, or tracked with explicit pass/fail status.

Key additions over writing-plans:

• Structured task format (JSON/YAML compatible)

• Required fields for each task (id, title, description, steps, passes)

• Explicit completion tracking via passes field

• Support for validation criteria per task (strongly recommended)

Announce at start: "I'm using the writing-plans-plus skill to create a structured implementation plan."

Context: This should be run in a dedicated worktree (created by brainstorming skill).

Save plans to: docs/plans/YYYY-MM-DD-<feature-name>.json

Note: Only save .md file when user explicitly requests a human-readable plan document. Default to JSON-only. When Markdown format is requested, read references/markdown-format.md for format requirements and examples.

Compatibility and Dependencies

This skill references other skills in the superpowers:* ecosystem.

• If superpowers:writing-plans is available, read and follow it first.

• If it is not available, proceed anyway and apply these principles directly:

• Keep tasks small and verifiable

• Use exact file paths

• Prefer objective validation steps before marking tasks complete

This repository does not bundle superpowers:* skills. Install them separately if you want the full workflow.

Required Reading First

If superpowers:writing-plans is available, read and follow it first.

This skill builds on top of writing-plans - all principles from that skill apply:

• Bite-sized tasks (2-5 minutes each)

• Exact file paths

• Complete code in plan

• TDD approach

• Frequent commits

The following sections ONLY document what is ADDED or CHANGED in writing-plans-plus.

Structured Task Format

Each task MUST be defined with the following fields:

Required Fields

Field Type Description

id

number/string Unique identifier for the task (1, 2, 3... or "T1", "T2"...)

title

string Brief, actionable title (imperative mood)

description

string Clear description of what this task accomplishes

steps

array List of specific, verifiable steps to complete

passes

boolean Completion status - false by default, true when done

Optional Fields

Field Type Description

files

object Files to create/modify: { create: [...], modify: [...], test: [...] }

depends_on

array<number/string> IDs of tasks that must complete before this one

validation_criteria

array Specific criteria to verify task completion (strongly recommended)

skills

array Skills the executing agent should load (see Recommended Skills below; default: ["executing-single-task"] )

issue

array Cross-validation issues: List of problems found during task review (see Task Cross-Validation Protocol)

completed_at

string ISO timestamp when task was completed

completed_by

string Who completed the task

notes

string Additional notes about completion. If passes is changed from true to false , do NOT describe problems in notes —use issue (you may preserve prior completion notes for audit trail)

Schema Compliance Rules

• Do NOT add extra fields beyond the schema above (e.g., status , superseded_by , audit , gaps , risk , review ).

• If issue is present, then passes MUST be false .

• If passes is true , then issue MUST NOT be present.

• When changing passes from true to false , problems MUST be described in issue (non-empty); do not use notes to describe problems.

• When changing passes from false to true , remove issue entirely (do not keep it with an empty array).

Example Structured Task

JSON Format (Machine-Readable, Recommended)

{ "id": 3, "title": "Supabase Client Setup", "description": "Create server-side and client-side Supabase clients with proper middleware", "steps": [ "Create server client with service role", "Create browser client for components", "Create middleware for session refresh", "Update root middleware.ts to use Supabase middleware" ], "passes": false, "files": { "create": [ "lib/supabase/server.ts", "lib/supabase/client.ts", "lib/supabase/middleware.ts" ], "modify": [ "middleware.ts" ] }, "validation_criteria": [ "Server client can query database", "Browser client initializes without errors", "Middleware refreshes expired sessions" ], "skills": ["executing-single-task", "test-driven-development"] }

Complete Plan Example

JSON Output (Default): docs/plans/2024-01-15-user-auth.json

{ "project": "User Authentication", "description": "Implement complete user authentication with email/password using Supabase", "goal": "Implement complete user authentication with email/password using Supabase", "architecture": "Use Supabase Auth with server-side sessions. Create reusable auth components and protect routes via middleware.", "tech_stack": ["Next.js 14", "Supabase Auth", "TypeScript", "Tailwind CSS"], "created_at": "2024-01-15", "tasks": [ { "id": 1, "title": "Project Setup", "description": "Configure project dependencies and environment", "steps": [ "Install Supabase packages: @supabase/supabase-js, @supabase/ssr", "Create .env.example with placeholder values (do not commit real secrets)" ], "passes": false, "files": { "create": [".env.example"], "modify": ["package.json"] }, "validation_criteria": [ "All packages installed without errors", "Environment variable placeholders are documented", "Can initialize Supabase client" ], "skills": ["executing-single-task"] } ... (additional tasks) ] }

Task Update Protocol

When updating task status during execution:

Update JSON file - Only update .json file by default

Set passes: true only when ALL validation criteria pass

Add completion metadata:

{ "passes": true, "completed_at": "2024-01-15T10:30:00Z", "completed_by": "Claude", "notes": "All validation criteria passed" }

Markdown only when requested: If .md file exists (user requested it), keep it in sync with JSON. See references/markdown-format.md for Markdown format examples.

Task Cross-Validation Protocol

When reviewing a task that was previously marked as completed (passes: true ), you must validate the implementation and update the task status if issues are found.

When to Perform Cross-Validation

Cross-validation should be performed:

• After task execution but before claiming completion

• When reviewing another agent's work

• When resuming work on a previously completed plan

• When verification-before-completion skill is used

Common Issues to Check For

Issue Category Examples

Implementation mismatch Code doesn't match task description, missing functionality, incorrect approach

Test coverage No unit tests, tests don't cover key scenarios, tests missing assertions

Test failures Existing tests fail, new tests fail, flaky tests

Quality issues Code doesn't follow standards, missing error handling, security vulnerabilities

When Issues Are Found

If any issues are discovered during review:

• Set passes: false

• Roll back the completion status

• Add issue field - REQUIRED. Non-empty array of strings describing each problem found

• Keep completion metadata - Preserve completed_at , completed_by for audit trail (optional)

• Update task description if needed - If task description was ambiguous or incorrect, update it to match what should have been implemented

• Do not use notes to describe issues - When changing passes from true to false , explain problems in issue (not notes )

Example: Task with issues found during review

{ "id": 3, "title": "Supabase Client Setup", "description": "Create server-side and client-side Supabase clients with proper middleware", "steps": [ "Create server client with service role", "Create browser client for components", "Create middleware for session refresh", "Update root middleware.ts to use Supabase middleware" ], "passes": false, "issue": [ "No unit tests for client initialization", "Middleware doesn't handle token refresh edge cases", "Server client is exposed to browser code", "Tests exist but have no assertions" ], "files": { "create": [ "lib/supabase/server.ts", "lib/supabase/client.ts", "lib/supabase/middleware.ts" ], "modify": [ "middleware.ts" ] }, "validation_criteria": [ "Server client can query database", "Browser client initializes without errors", "Middleware refreshes expired sessions" ], "completed_at": "2024-01-15T10:30:00Z", "completed_by": "Claude", "notes": "Initial implementation completed" }

When Issues Are Fixed

After the issues have been resolved:

• Remove the issue field - Do NOT keep it with an empty array

• Set passes: true

• Mark the task as completed again

• Update task description if necessary - Ensure description matches the actual implementation

• Update completion metadata - Set new completed_at and completed_by

• Add notes about the fix - Document what was changed

Example: Task after issues are fixed

{ "id": 3, "title": "Supabase Client Setup", "description": "Create server-side and client-side Supabase clients with proper middleware and test coverage", "steps": [ "Create server client with service role", "Create browser client for components", "Create middleware for session refresh", "Update root middleware.ts to use Supabase middleware", "Add unit tests for all clients and middleware" ], "passes": true, "files": { "create": [ "lib/supabase/server.ts", "lib/supabase/client.ts", "lib/supabase/middleware.ts", "lib/supabase/server.test.ts", "lib/supabase/client.test.ts", "lib/supabase/middleware.test.ts" ], "modify": [ "middleware.ts" ] }, "validation_criteria": [ "Server client can query database", "Browser client initializes without errors", "Middleware refreshes expired sessions", "All unit tests pass with meaningful assertions" ], "completed_at": "2024-01-15T14:45:00Z", "completed_by": "Claude", "notes": "Fixed issues: Added comprehensive tests, secured server client, improved middleware error handling" }

Recommended Skills

When specifying the skills field, use this guide to select appropriate skills. When in doubt, use ["executing-single-task"] .

Core Skills

Skill Description When to Use

executing-single-task

Execute exactly one structured task and update its status Default choice for tasks[].skills when executing tasks one-by-one

using-superpowers

Enforce skill discovery + “invoke skills before responding” protocol At the start of a session to establish the workflow (not a per-task skill)

brainstorming

Turn ideas into an approved design before implementation Before any creative work (new feature, behavior change, non-trivial change)

writing-plans

Create a detailed implementation plan before touching code When you have requirements/spec and need a multi-step plan (pre-implementation)

executing-plans

Execute an existing plan in batches with review checkpoints When executing a written plan in a separate session (batch + feedback loop)

subagent-driven-development

Execute a plan in this session using subagents + per-task reviews When tasks are mostly independent and you want fast iteration without context switching

dispatching-parallel-agents

Run 2+ independent investigations/threads concurrently When you have multiple independent problem domains that can be worked in parallel

Development Skills

Skill Description When to Use

test-driven-development

Enforce RED → GREEN → REFACTOR workflow Before writing implementation code for features, bugfixes, refactors, behavior changes

systematic-debugging

Find root cause before proposing fixes Any bug, test failure, build failure, or unexpected behavior (before fixes)

verification-before-completion

Require evidence before any “done/fixed/passing” claim Before marking tasks complete, committing, or creating PRs; run verification and cite output

Code Quality & Review

Skill Description When to Use

requesting-code-review

Request review to catch issues early After major tasks/features, before merging, and after each task in subagent-driven workflows

receiving-code-review

Evaluate feedback rigorously before implementing When you receive review feedback (especially if unclear or technically questionable)

Git & Workflow

Skill Description When to Use

using-git-worktrees

Create an isolated workspace and verify clean baseline Before starting feature work that needs isolation, or before executing an implementation plan

finishing-a-development-branch

Verify tests and present structured integrate/cleanup options When implementation is complete, tests pass, and you need to merge/PR/keep/discard

Skill Development

Skill Description When to Use

skill-creator

Create/modify skills and iterate with evals When authoring or improving skills and you want a full test/eval loop

writing-skills

Apply TDD-style methodology to skill authoring When creating/editing/verifying skills before deployment

Example Usage

{ "skills": ["executing-single-task", "test-driven-development"] }

{ "skills": ["executing-single-task", "brainstorming", "writing-plans-plus"] }

{ "skills": ["executing-single-task", "systematic-debugging", "verification-before-completion"] }

Validation Checklist

Before marking any plan complete, verify:

• Every task has all Required Fields

• Every task has passes: false initially

• Task IDs are unique and sequential

• File paths use exact relative paths

• Steps are specific and verifiable

• If present, validation criteria are objective (pass/fail)

• JSON output is saved

Cross-Validation Checklist

When reviewing completed tasks:

• Implementation matches task description

• Tests exist and cover key scenarios

• All tests pass

• Tests have meaningful assertions (not just empty tests)

• If issues found: passes is false AND issue array exists with clear descriptions

• If issues fixed: issue field is REMOVED (not empty array) AND passes is true

• Task description updated if implementation differs from original plan

Integration with Executing Plans

When this plan is executed via superpowers:executing-plans :

• Execution order follows task IDs by default

• Dependency resolution: Tasks with depends_on must wait for dependencies

• Status updates: After each task, update passes in JSON file

• Validation: Run validation criteria before marking passes: true

• Checkpointing: Each completed task is a checkpoint - can resume from any point

Summary of Differences from writing-plans

Aspect writing-plans writing-plans-plus

Task format Markdown free-form Structured with required fields

Completion tracking Implicit Explicit via passes field

Machine readable No Yes (JSON output)

Validation criteria Optional Strongly recommended

File outputs .md only .json (default), .md (optional on request)

Dependencies Implied Explicit via depends_on

Skill guidance No Explicit via skills field

Issue tracking No Explicit via issue field for cross-validation

Audit trail No completed_at , completed_by for completion history

Quick Reference: Required Fields Checklist

For each task, ensure you have:

id: number or string (unique) title: string (imperative mood) description: string (what it accomplishes) steps: array of strings (specific actions) passes: boolean (false by default)

Plus optional fields as needed

Remember: Read superpowers:writing-plans SKILL first, then apply this structured format on top.