# Superteam Writing Plans

> Create structured implementation plans with machine-parseable task blocks

- Skill: `diegosouzapw/superteam-writing-plans` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add diegosouzapw/superteam-writing-plans`
- Raw SKILL.md: https://api.skillmd.com/api/skills/diegosouzapw/superteam-writing-plans/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: diegosouzapw (https://skillmd.com/u/diegosouzapw)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/diegosouzapw/superteam-writing-plans

---


# Writing Plans

## Structure

A good plan has:
1. **Goal** — what are we building and why
2. **Constraints** — technical limitations, dependencies, requirements
3. **Tasks** — ordered, independent, testable units of work
4. **Task block** — machine-parseable task list for automation

## Task Block Format

Include a `superteam-tasks` fenced block for automated task tracking:

````markdown
```superteam-tasks
- title: Create data models
  description: Define TypeScript types and validation for User and Post entities
  files: [src/models/user.ts, src/models/post.ts]
- title: Implement API endpoints
  description: REST endpoints for CRUD operations on User and Post
  files: [src/routes/users.ts, src/routes/posts.ts]
- title: Add authentication middleware
  description: JWT validation middleware for protected routes
  files: [src/middleware/auth.ts]
```
````

### Task Properties
- **title**: Short, action-oriented (verb + noun)
- **description**: What to implement and any key decisions
- **files**: Expected files to create or modify

## Task Guidelines

### Good Tasks
- ✅ "Create user model with email validation" — clear, testable, small
- ✅ "Add JWT authentication middleware" — focused, independent
- ✅ "Implement pagination for list endpoints" — specific feature

### Bad Tasks
- ❌ "Set up the project" — too vague
- ❌ "Implement the entire backend" — too large
- ❌ "Fix bugs" — not specific enough

## Task Ordering

1. Data models and types first (foundation)
2. Core business logic (depends on models)
3. API/UI layer (depends on business logic)
4. Integration and cross-cutting concerns (auth, logging, etc.)
5. Polish and optimization (last)

## Size Guidelines

- **Ideal task**: 1-3 files, 50-200 lines of code + tests
- **Too small**: Renaming a variable (just do it)
- **Too large**: "Implement the auth system" (break into subtasks)
- **Splitting rule**: If you can't describe it in one sentence, split it