planmode

Publishing Guide

Share your plans, rules, and prompts with the community. Publishing a package makes it available in the public registry for anyone to install.

1. Initialize your package

mkdir my-awesome-plan && cd my-awesome-plan
git init
planmode init

The init command prompts you for the package name, type, description, author, license, tags, and category. It creates two files:

  • planmode.yaml — the package manifest
  • A stub content file (plan.md, rule.md, or prompt.md)

2. Write your content

Edit the content file with your plan, rule, or prompt. For plans, write clear, ordered steps. For rules, write concise guidelines. For prompts, use Handlebars templates for variables.

Plan example

# Set Up Authentication

1. Install NextAuth.js: `npm install next-auth`
2. Create `app/api/auth/[...nextauth]/route.ts`
3. Configure providers (Google, GitHub)
4. Add session provider to root layout
5. Create login/signup pages
6. Add middleware for protected routes

Rule example

- Always use strict TypeScript mode
- Prefer `unknown` over `any`
- Use explicit return types on exported functions
- Enable noUncheckedIndexedAccess

Templated prompt example

Generate a complete REST API for the {{resource}} resource
using {{framework}}. Include CRUD endpoints, input validation,
error handling, and TypeScript types.

3. Configure variables (optional)

If your package uses templates, define variables in planmode.yaml:

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

4. Add dependencies (optional)

Plans and rules can depend on other packages:

dependencies:
  rules:
    - typescript-strict@^1.0.0
    - tailwind-best-practices
  plans:
    - prisma-setup@~2.0.0

5. Authenticate

# Option A: provide a token directly
planmode login --token ghp_xxxxx

# Option B: use the GitHub CLI
planmode login --gh

6. Push to GitHub

Create a GitHub repository and push your package:

git add .
git commit -m "Initial package"
git remote add origin git@github.com:username/my-awesome-plan.git
git push -u origin main

7. Publish

planmode publish

This will:

  • Validate your planmode.yaml
  • Check that the version doesn't already exist
  • Create a git tag v<version>
  • Fork the planmode/registry repo
  • Submit a PR with your package entry

Once the PR is reviewed and merged, your package will be available in the public registry.

Updating your package

To publish a new version:

  • Bump the version field in planmode.yaml
  • Update your content
  • Commit, push, and run planmode publish again

Private packages

Not everything needs to be public. For private packages, push to a private GitHub repo with the same format as the public registry — a packages/ directory with planmode.yaml and content files. Configure the private source in ~/.planmode/config: 

# ~/.planmode/config
registries:
  mycompany: github.com/mycompany/planmode-packages

Then install scoped packages from it:

planmode install @mycompany/deploy-playbook