Perch Planner

Perch Planner CLI

The plan CLI is the primary interface for creating and managing architectural plans in Perch. Plans are hierarchical trees of nodes — areas, decisions, open questions, and future work — with built-in review, versioning, and export.

Binary Location

The CLI lives at agent-sidecar/.bin/plan relative to the Perch repo root. If not on $PATH, use the full path or build it:

cd /path/to/perch && go build -o agent-sidecar/.bin/plan ./cmd/plan

Quick Start

# Set up
plan new "My Project"
plan use "My Project"

# Build the tree
plan area add "Authentication"
plan add auth "Use OAuth2 with PKCE" --decision --rationale "Industry standard for SPAs"
plan add auth "Session storage strategy" --open
plan add auth "Token refresh mechanism" --future

# Read back
plan show auth
plan export

Active Project

Most commands operate on the active project. Set it once per session:

plan use "Project Name"

The active project is stored in ~/.config/perch/plan-active-project. Override with PLAN_ACTIVE_PROJECT env var.

Retrieving a Plan by Name

# List all projects
plan list

# Show project details (ID, slug, revision, areas)
plan show-project "Project Name"

# Set as active and explore
plan use "Project Name"
plan show auth                    # Show a specific area/node
plan show auth/session-strategy   # Show nested node
plan export                       # Full plan as Markdown
plan export --depth 2             # Top 2 levels only
plan export --facet security      # Only security-tagged nodes

Path System

Nodes are addressed by slash-separated slugs:

• auth — a root area named "Authentication" (slugified)
• auth/session-strategy — a child under auth
• auth/session-strategy/oauth2 — deeper nesting

Slugs are auto-generated from node content: lowercase, alphanumeric + dashes, max 80 chars. Collisions among siblings get -1, -2, etc. appended automatically.

plan resolve auth/session-strategy   # Print the node's short ID (e.g., pn-a1b2c3d4)

Short IDs

All entities use human-friendly short IDs with typed prefixes:

All commands accept both short IDs and full UUIDs. Output always shows short IDs when available.

Commands Reference

Project Lifecycle

Tree Building

Node Types

• detail (default) — regular planning content
• decision — architectural/strategic choice, typically has a rationale
• open_question — unresolved question needing discussion
• future — speculative work, excluded from export by default

Node Statuses

• draft (default) — in progress
• accepted — approved, ready for implementation
• needs_review — awaiting feedback
• superseded — replaced by another node

Facets

Cross-cutting concern tags. Valid facets: product, data, security, privacy, reliability, operability, cost, compliance, ux.

plan tag auth/oauth2 --facet security
plan untag auth/oauth2 --facet security

Inputs

Attach external context references to a project:

plan input add --type repository --name "perch" --uri "github.com/marcus/perch"
plan input add --type skill --name "sveltekit-latest" --description "Svelte 5 patterns"
plan input add --type document --name "RFC 7636" --uri "https://tools.ietf.org/html/rfc7636"
plan inputs                     # List all inputs
plan input rm <input-id>        # Remove an input

Valid input types: repository, guideline, skill, document, api, design_system.

Reviews

Reviews let an agent (or human) propose changes to a subtree, then apply or reject them as a batch.

# Create a review scoped to a subtree
plan review start auth --lens security
plan review start auth --lens reliability --depth 2

# Agent adds proposals
plan review add-proposal <review-id> \
  --kind edit_node \
  --target auth/oauth2 \
  --content "Updated content" \
  --rationale "Clarify token rotation"

plan review add-proposal <review-id> \
  --kind add_child \
  --parent auth \
  --content "Rate limiting strategy" \
  --rationale "Missing from current plan"

plan review add-proposal <review-id> \
  --kind add_open_question \
  --parent auth \
  --content "Should we support SSO?"

plan review add-proposal <review-id> \
  --kind status_change \
  --target auth/session-strategy \
  --status accepted

# Complete the review
plan review complete <review-id> --summary "Added rate limiting, clarified OAuth"

# Show and apply
plan review show <review-id>
plan review apply <review-id>                        # Apply all proposals
plan review apply <review-id> --proposal <prop-id>   # Apply one
plan review reject <review-id>                       # Reject all

Proposal kinds: edit_node, add_child, add_open_question, add_future, status_change

Stale detection: Proposals become stale if the target node was modified or deleted since the review was created. Stale proposals are skipped during apply.

Snapshots & Versioning

plan snapshot "Before refactor"       # Create immutable snapshot
plan diff <snapshot-id>               # Compare snapshot to current tree

Export & Validation

plan export                           # Full Markdown export
plan export --depth 3                 # Limit depth
plan export --facet security          # Filter by facet
plan export --future true             # Include future nodes
plan validate                         # Check for structural issues

Common Agent Workflows

Retrieve and understand an existing plan

plan use "Project Name"
plan export                           # Get the full picture
plan show <area>                      # Drill into specific areas
plan show <area> --open               # Find open questions

Build a plan from scratch

plan new "API Redesign"
plan use "API Redesign"

# Define areas
plan area add "Data Model"
plan area add "API Endpoints"
plan area add "Authentication"
plan area add "Migration Strategy"

# Add details, decisions, questions
plan add data-model "Use PostgreSQL with JSONB for flexible schemas" --decision \
  --rationale "Team already has PG expertise, JSONB handles evolving requirements"
plan add data-model "How to handle schema versioning?" --open
plan add api-endpoints "REST with OpenAPI spec" --decision
plan add migration-strategy "Zero-downtime migration plan" --future

# Tag with facets
plan tag data-model --facet data
plan tag authentication --facet security

# Add external references
plan input add --type repository --name "api-service" --uri "github.com/org/api"
plan input add --type document --name "Migration runbook" --uri "notion.so/..."

Run a review pass

plan use "Project Name"
plan review start api-endpoints --lens security
# ... add proposals ...
plan review complete <id> --summary "Security review complete"
plan review apply <id>

Snapshot before major changes

plan snapshot "Pre-review baseline"
# ... make changes ...
plan diff <snapshot-id>               # See what changed

Database Location

Resolution order:

1. PLAN_DB environment variable
2. Perch config DataDir + "/planner.db"
3. Default: ~/.openclaw/workspace/data/planner.db

Optimistic Concurrency

Every node has a revision counter. Content edits require the current revision to match (enforced automatically by the CLI via read-then-write). The project itself has a project_revision that increments on every mutation, used for conflict detection in reviews.