Create or update a structured plan directory with a master PLAN.md index and numbered task files (001-*.md). Each task file includes goal, dependencies, scope, checklist, tests, and completion criteria. Use when scaffolding a repeatable project plan in markdown, especially when the user wants a master index plus per-task files with checkboxes that are checked off as work completes.
Creates a structured plan directory with a master PLAN.md index and numbered task files (001-*.md) containing goals, dependencies, checklists, tests, and completion criteria. Use when scaffolding repeatable project plans in markdown, especially for multi-step work that benefits from a master index plus per-task checkboxes that track progress as work completes.
/plugin marketplace add DiversioTeam/agent-skills-marketplace/plugin install plan-directory@diversiotechThis skill is limited to using the following tools:
Do not use this skill for ad-hoc todo lists, single-file notes, or when the user explicitly wants a different format.
Before writing any files, gather these inputs. If any are missing, ask the user for them explicitly.
| Input | Required | Description |
|---|---|---|
| Plan title | Yes | Human-readable name (e.g., "User Authentication Overhaul") |
| Plan slug | Yes | Hyphenated directory/file slug (e.g., user-auth-overhaul) |
| Target location | No | Directory path; defaults to docs/plans/<slug>/ or plans/<slug>/ |
| Task list | Yes | List of tasks with short names and scopes |
| Locked decisions | No | Key constraints or choices that must not change |
| Testing expectations | No | Commands, subsets, or manual QA requirements |
When updating an existing plan, read the current PLAN.md first to understand
context before modifying.
PLAN.md is the index, not the content. It contains only the purpose, usage instructions, locked decisions, and a task index with checkboxes. Detailed steps live in individual task files.
Task files use 3-digit numbering. Format: NNN-<slug>.md where NNN
is zero-padded (001, 002, ..., 999) and <slug> is hyphenated lowercase.
Every task file has six sections. Goal, Scope, Checklist, Tests, Completion Criteria, and Dependencies. All are required (use "None" for Dependencies if truly independent, "N/A" for Tests only with justification).
Checkboxes are the only status markers. Do not add "Status: Done"
fields, emoji indicators, or separate progress sections. Check - [x]
when complete, leave - [ ] when pending.
Mirror completion in PLAN.md. When all checklist items in a task file are checked, check the corresponding task in PLAN.md.
Do not renumber existing tasks. Once a task number is assigned and work has started, it is permanent. Append new tasks at the end.
Keep task files self-contained. A reader should understand the task from the file alone without reading other task files.
Track blockers explicitly. When a task is blocked, add a ## Blockers
section describing what's blocking and link to the blocking task or issue.
PLAN.md already exists. Read it, understand the current
state, and make targeted modifications.For new plans:
PLAN.md with the master index.001-*.md, 002-*.md, etc.).For updates:
PLAN.md and relevant task files.Keep it minimal. Include only:
Each task file must include:
As work completes:
| Scenario | Rule |
|---|---|
| Adding tasks | Append at the end with the next number |
| Removing tasks | Mark as "[REMOVED]" in PLAN.md; delete file only if user requests |
| Renaming tasks | Update both the task file and PLAN.md index entry |
| Reordering tasks | Do not renumber; use dependencies or notes to indicate order changes |
| Splitting tasks | Create new task files; mark original as "[SPLIT]" pointing to new tasks |
# <Plan Title> - Master Plan
## Purpose
- <Why this plan exists>
- <What it delivers when complete>
## How to Use
1. Work tasks in order unless dependencies indicate otherwise.
2. Check items in task files as they are completed.
3. This file is the index only; details live in task files.
## Decisions (Locked)
- <Key constraint or choice that should not change>
- <Another locked decision>
## Task Index
- [ ] 001 - <Task Name> (`001-<slug>.md`)
- [ ] 002 - <Task Name> (`002-<slug>.md`)
- [ ] 003 - <Task Name> (`003-<slug>.md`)
## Completion
- [ ] All tasks in the index are checked.
- [ ] All tests listed in task files pass.
- [ ] <Any additional project-specific completion criteria>
# NNN - <Task Name>
## Goal
<Single sentence describing the outcome of this task.>
## Dependencies
- Requires: 001, 002 (or "None" if independent)
- Blocks: 004, 005 (tasks waiting on this one)
## Scope
**In scope:**
- <What this task covers>
- <Another in-scope item>
**Out of scope:**
- <What this task explicitly does not cover>
## Checklist
- [ ] <Concrete implementation step with verifiable outcome>
- [ ] <Another concrete step>
- [ ] <Another concrete step>
## Tests
- [ ] Run `<test command>` and verify all pass
- [ ] Manual QA: <specific verification step>
## Completion Criteria
- [ ] <Measurable definition of done>
- [ ] <Another measurable definition>
## Notes
- <Optional: constraints, references, links, or warnings>
When a task is blocked, add a ## Blockers section immediately after Dependencies:
## Blockers
- **Blocked by:** External API not yet available (ETA: 2024-02-15)
- **Blocked by:** Waiting on 003 to complete first
- **Action needed:** Contact platform team for API access
Remove the Blockers section when the task is unblocked.
Before delivering a plan, verify:
NNN-<slug>.md with 3-digit padding.Some tasks can run concurrently if they have no dependencies on each other. Indicate this in PLAN.md using a parallel block notation:
## Task Index
- [ ] 001 - Database setup (`001-db-setup.md`)
- [ ] 002 - Frontend scaffolding (`002-frontend-scaffold.md`) [parallel: 001]
- [ ] 003 - API design (`003-api-design.md`) [parallel: 001, 002]
- [ ] 004 - Integration (`004-integration.md`) [after: 001, 002, 003]
The [parallel: NNN] tag means "can run at the same time as task NNN".
The [after: NNN] tag means "must wait for NNN to complete".
When working a plan:
[after: ...] tasks when all listed dependencies are checked.User prompt:
"Create a plan for adding user authentication to my app. Use JWT tokens, store users in PostgreSQL, and include password reset flow."
Expected behavior:
docs/plans/user-auth/ (or user-specified location).PLAN.md with the task index.001-user-model.md - Create User model and migrations002-jwt-setup.md - Configure JWT authentication003-login-endpoint.md - Implement login/logout endpoints004-password-reset.md - Implement password reset flow005-integration-tests.md - Write integration testsOutput structure:
docs/plans/user-auth/
PLAN.md
001-user-model.md
002-jwt-setup.md
003-login-endpoint.md
004-password-reset.md
005-integration-tests.md
User prompt:
"Add a new task to the user-auth plan for implementing OAuth with Google."
Expected behavior:
PLAN.md to understand current state.006-google-oauth.md with the standard sections.User prompt:
"I've completed the JWT setup task in the user-auth plan."
Expected behavior:
002-jwt-setup.md.PLAN.md to check the 002 - JWT Setup entry.Here's a fully filled-out task file for reference:
# 003 - Login Endpoint
## Goal
Implement JWT-based login and logout endpoints that authenticate users and
return tokens.
## Dependencies
- Requires: 001, 002
- Blocks: 004, 005
## Scope
**In scope:**
- POST /api/auth/login endpoint accepting email/password
- POST /api/auth/logout endpoint invalidating tokens
- Token refresh endpoint
- Rate limiting on login attempts
**Out of scope:**
- OAuth/social login (separate task 006)
- Password reset flow (task 004)
- User registration (task 001 handles this)
## Checklist
- [ ] Create LoginSerializer with email and password fields
- [ ] Implement login view returning access and refresh tokens
- [ ] Implement logout view that blacklists the refresh token
- [ ] Add rate limiting: max 5 failed attempts per 15 minutes
- [ ] Return appropriate error codes (401 for bad credentials, 429 for rate limit)
- [ ] Log authentication attempts with user ID and IP (no passwords)
## Tests
- [ ] Run `pytest apps/auth/tests/test_login.py -v` - all pass
- [ ] Run `pytest apps/auth/tests/test_logout.py -v` - all pass
- [ ] Manual QA: Verify login with valid credentials returns token
- [ ] Manual QA: Verify 5 failed attempts triggers rate limit
## Completion Criteria
- [ ] Login endpoint returns valid JWT on correct credentials
- [ ] Logout endpoint invalidates the refresh token
- [ ] Rate limiting activates after 5 failed attempts
- [ ] All automated tests pass
- [ ] No security warnings from `bandit` scan
## Notes
- Use `djangorestframework-simplejwt` for token handling
- Token expiry: access = 15 min, refresh = 7 days
- See RFC 6749 for OAuth2 token response format reference
When all tasks are checked:
## Completed section at the top of PLAN.md with the date:
## Completed
**Date:** 2024-02-15
**Duration:** 3 weeks
**Notes:** All tasks completed successfully. OAuth added as follow-up plan.
docs/plans/archive/<slug>/ or
add an [ARCHIVED] prefix to the directory name.For significant plans, add a RETROSPECTIVE.md in the plan directory:
# <Plan Title> - Retrospective
## What Went Well
- <Positive outcomes and practices>
## What Could Be Improved
- <Issues encountered and lessons learned>
## Follow-up Actions
- <New tasks or plans spawned from this work>
Complete 003-login-endpoint: implement JWT login/logoutplan/user-auth/003-login-endpoint.When a task is too complex to fit in a single task file (even after splitting), spawn a nested sub-plan:
In the parent task file, add a note:
## Notes
- **Sub-plan:** See `../user-auth-oauth/PLAN.md` for detailed OAuth implementation
Create the sub-plan in a sibling directory:
docs/plans/
user-auth/
PLAN.md
003-oauth-integration.md # References sub-plan
user-auth-oauth/ # Sub-plan for complex OAuth work
PLAN.md
001-google-oauth.md
002-github-oauth.md
Link the sub-plan completion to the parent task:
- [ ] Sub-plan user-auth-oauth is fully completeWhen the sub-plan completes:
This keeps individual task files focused while allowing complex work to be properly structured.
This skill is designed to work with both Claude Code and OpenAI Codex. The plan directory format is agent-agnostic markdown that any LLM can read, update, and execute.
For Codex users:
--repo DiversioTeam/agent-skills-marketplace --path plugins/plan-directory/skills/plan-directory.$skill plan-directory to invoke.For Claude Code users:
/plugin install plan-directory@diversiotech./plan-directory:plan to invoke.Master defensive Bash programming techniques for production-grade scripts. Use when writing robust shell scripts, CI/CD pipelines, or system utilities requiring fault tolerance and safety.