writing-plan-docs

Writing Plan Docs for permit0

When to Use

Use this skill when the user asks you to plan a new integration (e.g. a new agent host like Codex, Cursor, CrewAI), a new pack, a new crate, or any multi-step change that benefits from upfront design before code.

Where to Place Plans

docs/plans/<feature-name>/
  00-overview.md
  01-protocol.md          (if wire format / API contract exists)
  02-implementation.md
  03-configuration.md     (if user-facing setup is needed)
  04-testing.md
  05-limitations.md

• Path: Always under docs/plans/<feature-name>/.
• Numbering: Prefix with 00- through 0N- for reading order.
• Naming: Use lowercase-kebab-case for the feature directory.

Documents to Write

Not every plan needs all six docs. Pick the ones that apply.

00-overview.md (always required)

The entry point. A reader should understand what, why, and how far after reading only this file.

Cover:

1. Goal -- What this feature does, in one paragraph. If it replicates an existing integration, say so and link to the reference implementation.
2. Data flow -- ASCII or mermaid diagram showing the end-to-end path.
3. Comparison table -- If a similar feature exists (e.g. Claude Code integration), a side-by-side table of what is the same and what differs.
4. Scope -- Bullet list of what is in v1 vs deferred to v2+.
5. Crate dependencies -- Which crates are touched and which are not. permit0's architecture makes most features crate-local; call that out.

Header template:

# 00 -- <Feature>: Overview and Architecture

**Status:** Draft
**Depends on:** None
**Blocks:** 01-protocol, 02-implementation

01-protocol.md (when there is a wire format)

Exact schemas for any JSON, TOML, HTTP, or stdin/stdout contract.

Cover:

1. Input schema -- Every field, type, whether always present or optional.
2. Output schema -- Every possible response shape. Show concrete JSON examples for each verdict/outcome.
3. Mapping table -- How permit0 types (Permission, Tier, etc.) map to the external system's values.
4. Error handling matrix -- What happens on crash, timeout, malformed output, transport failure. Table format works well.
5. Session / identity extraction -- Where session IDs come from, fallback chain.
6. Future extensions -- Schemas or hooks that exist in the external system but are not used in v1.