planmode

Spec Reference

planmode.yaml

Every package has a planmode.yaml manifest file. Here's the complete schema:

# ── Required fields ──
name: nextjs-tailwind-starter        # Unique, lowercase, hyphens only
version: 1.0.0                       # Semver (major.minor.patch)
type: plan                            # "prompt" | "rule" | "plan"

# ── Required for publishing ──
description: "Full-stack Next.js starter"  # Max 200 chars
author: username                      # GitHub username
license: MIT                          # SPDX identifier

# ── Optional fields ──
repository: github.com/username/repo
models:                               # Compatible AI models
  - claude-4
  - claude-3.5
  - gpt-4o
tags:                                 # Max 10 tags
  - nextjs
  - tailwind
category: frontend                    # Primary category

# ── Dependencies (plans and rules only) ──
dependencies:
  rules:
    - tailwind-best-practices
    - typescript-strict@^1.0.0
  plans:
    - prisma-setup@~2.0.0

# ── Variables (for templated packages) ──
variables:
  framework:
    description: "Target framework"
    type: enum
    options: [nextjs, remix, express]
    required: true
    default: nextjs
  project_name:
    description: "Your project name"
    type: string
    required: true

# ── Content ──
# Option A: inline
content: |
  1. Create a new project...
  2. Install dependencies...

# Option B: separate file
content_file: plan.md

Field validation

Field Rule
name /^(@[a-z0-9-]+\/)?[a-z0-9][a-z0-9-]*$/, max 100 chars
version Valid semver (X.Y.Z)
type One of: prompt, rule, plan
description Max 200 chars
tags Max 10, lowercase alphanumeric + hyphens
variables[].type One of: string, number, boolean, enum, resolved
dependencies Only allowed for plan and rule types

Version ranges

Dependencies support npm-style version ranges:

Syntax Meaning
1.2.3 Exact version
^1.2.3 Compatible with 1.x.x (>=1.2.3, <2.0.0)
~1.2.3 Patch-level changes (>=1.2.3, <1.3.0)
>=1.0.0 Any version >= 1.0.0
* Any version (latest)

Package types

Type Location How Claude loads it Lifecycle
plan plans/*.md @import in CLAUDE.md Active during task
rule .claude/rules/*.md Auto-loaded Permanent
prompt prompts/*.md On demand via planmode run Fire once

Categories

Every package belongs to one primary category:

frontendbackenddevopsdatabasetestingmobileai-mldesignsecurityother

Variable types

string

Free-form text input.

project_name:
  type: string
  required: true

number

Numeric value.

port:
  type: number
  default: 3000

boolean

True or false.

use_docker:
  type: boolean
  default: true

enum

One of a fixed set of options.

framework:
  type: enum
  options: [nextjs, remix, express]
  default: nextjs

resolved

Dynamic data fetched at render time. Used for live data injection into prompts.

weather:
  type: resolved
  resolver: url
  source: "https://wttr.in/{{location}}?format=j1"
  extract: "current_condition[0].weatherDesc[0].value"

Lockfile

planmode.lock is created in the project root on first install. It tracks exact installed versions: 

lockfile_version: 1

packages:
  nextjs-tailwind-starter:
    version: 1.1.0
    type: plan
    source: github.com/planmode/nextjs-tailwind-starter
    tag: v1.1.0
    sha: abc123def456
    content_hash: sha256:abcdef1234567890
    installed_to: plans/nextjs-tailwind-starter.md

Global config

Stored at ~/.planmode/config: 

auth:
  github_token: ghp_xxxxx

registries:
  default: github.com/planmode/registry
  mycompany: github.com/mycompany/planmode-packages

cache:
  dir: ~/.planmode/cache
  ttl: 3600