plan-schema

A reference for the Markdown format used to describe implementation plans in `.claude/plans/` files.

In plain words
What is it for?
Use it when creating, editing, or validating plans for features, bug fixes, or code-quality work.
Why use it?
It keeps plans structured so other tools can execute them directly or convert them into task lists or Beads issues. Beads is a git-backed issue tracker.

Skill for Claude CodeCodex

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods
npx agentmods add skills/gantisstorm/essentials-claude-code/plan-schema
Any agent
npx skills add GantisStorm/essentials-claude-code --skill plan-schema
Clone the repo
git clone --depth 1 https://github.com/GantisStorm/essentials-claude-code

Made for: Claude Code, Codex.

Per session 29 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.
When invoked 2,976 The whole file, excluding the scripts and references it only reads on demand.
Security scan A 0 findings. Scan, not verified.
Origin original No closer match found in the catalogue.
Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

ModelPer sessionOnce invoked
Fable 5 $0.00029 $0.02976
Opus 5 $0.00015 $0.01488
Sonnet 5 $0.00006 $0.00595
Haiku 4.5 $0.00003 $0.00298

Measured 2d ago against content hash d166d22e37df, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade A, and why

plan-schema scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 2d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

essentials/skills/plan-schema/SKILL.md · 347 lines

How it starts

The opening of the file, as written. The whole thing — 347 lines — stays where its author put it; the contents beside it link to each section on GitHub.

Plan file schema reference for architectural plans created by /plan-creator, /bug-plan-creator, and /code-quality-plan-creator. Use this when creating, editing, or reviewing .claude/plans/*-plan.md files.

When to Use

Invoke /plan-schema before manually editing any plan file. Invoke /plan-schema validate <path> to check an existing plan.

Core Concepts

Plans are markdown files in .claude/plans/ that specify HOW to implement a feature, fix, or improvement. They are consumed by:

  • /plan-loop and /plan-swarm — execute plans directly
  • /tasks-converter — converts to prd.json for /tasks-loop, /tasks-swarm, or RalphTUI
  • /beads-converter — converts to beads for /beads-loop, /beads-swarm, or RalphTUI

Conversion Pipeline

Plans are the intermediate representation between creators and executors:

/plan-creator (or /bug-plan-creator, /code-quality-plan-creator)
    ↓ writes
.claude/plans/{slug}-{hash5}-plan.md
    ↓ consumed by (choose one)
    ├─ /plan-loop or /plan-swarm        → executes plan directly
    ├─ /tasks-converter <plan-path>     → .claude/prd/<slug>.json
    │       ↓ executed by
    │       /tasks-loop or /tasks-swarm or ralph-tui
    └─ /beads-converter <plan-path>     → .beads/ (bd CLI issues)
            ↓ executed by
            /beads-loop or /beads-swarm or ralph-tui

Direct execution (/plan-loop, /plan-swarm) reads the plan file and implements each file entry in dependency order. No intermediate format needed.

Converted execution (/tasks-converter, /beads-converter) transforms the plan into prd.json or beads. Each task/bead gets a 100% self-contained description — the executor agent receives only the task description, never the source plan. All code, requirements, and verification commands are copied verbatim from the plan.

File Naming

.claude/plans/{slug}-{hash5}-plan.md
Creator Pattern Example
/plan-creator {feature-slug}-{hash5}-plan.md oauth2-authentication-a3f9e-plan.md
/bug-plan-creator bug-plan-creator-{identifier}-{hash5}-plan.md bug-plan-creator-auth-null-pointer-4k2m7-plan.md
/code-quality-plan-creator code-quality-{filename}-{hash5}-plan.md code-quality-auth_service-3m8k5-plan.md

Read the full file on GitHub · 347 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

  1. 2d ago First seen · 347 lines · 29 tokens per session scan A d166d22e37df

Subscribe to this mod's changes

plan-schema is a skill published in the GitHub repository GantisStorm/essentials-claude-code (91 stars, last pushed 6mo ago), licensed Unlicense. It adds 29 tokens to every session and 2,976 once invoked, about $0.0001 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.

Related

Other skills, from other repositories

rulesync

Generates and syncs AI rule configuration files (.cursorrules, CLAUDE.md, copilot-instructions.md) across 20+ coding tools from a single source. Use when syncing AI rules, running rulesync commands, importing or generating rule files, or managing shared AI coding configurations.

dyoshikawa/rulesync · 64 tokens

establishing-project-context

Use when the user asks to establish shared project language, or project work exposes a conflicting, renamed, or deprecated domain term that needs active semantic modeling. Routine small tasks stay on the fast path.

GanyuanRan/Aegis · 45 tokens

autoprompt

Explicit-only useful-first orchestration. Invoke /autoprompt to turn a mission into one executable roadmap, build dependency-safe lanes, and verify the result with independent reviewers. Never infer invocation from ordinary requests. Never resume from leftover artifacts without an explicit resume instruction.

Spielewoy/autoprompt-skill · 56 tokens

office-hours

YC Office Hours — two modes. Startup mode: six forcing questions that expose demand reality, status quo, desperate specificity, narrowest wedge, observation, and future-fit. Builder mode: design thinking brainstorming for side projects, hackathons, learning, and open source. Saves a design doc. Use when asked to…

GCWing/BitFun · 168 tokens

memstack-business-gdpr

Use this skill when the user says 'GDPR', 'data protection', 'privacy compliance', 'DPA', 'DSAR', 'data subject request', 'cookie consent', 'privacy audit', 'CCPA', or asks 'do I need GDPR for this repo'. Scans the repository to detect what personal data is collected, classifies sensitivity, determines whether GDPR…

cwinvestments/memstack · 121 tokens

echo

Use when the user references past sessions, asks 'what did we do', 'do you remember', 'last session', 'recall', or 'continue from'.

cwinvestments/memstack · 35 tokens