plansm — Plan as a Verifiable State Machine

plansm turns "planning" into a machine-verifiable state machine, preventing LLMs from claiming completion without proof.

Why plansm?

Traditional LLM planning tools use Markdown checklists that can be marked complete without verification. plansm is different:

• Plan is data (plan.json), not documentation
• "Done" is proof-based: machine-checkable verification rules (tests, commands, file checks)
• VERIFIED status written only by verification scripts, never by LLM or manual edit
• Low token cost: LLM reads only current step, not entire plan
• Anti-cheating: Stop hooks + CI gates prevent fake completion

Read Why Markdown Planning Fails for the philosophy.

Core Principles

Markdown Planning	plansm
- [ ] Implement API	{"status": "PENDING", "verify": [...]}
Self-reported completion	Machine-verified proof required
Easy to fake	Hard to fake (tests must pass)
High token cost	Minimal context (current step only)

State Machine

LOCKED    → Dependencies not met
PENDING   → Ready to work on
FAILED    → Verification failed
VERIFIED  → Tests/proofs passed (script-verified only)

Installation

Pure shell script skill - no compilation needed!

# 1. Clone the repository
git clone https://github.com/spytensor/plansm.git

# 2. Copy skill to Claude Code
cd plansm
cp -r .claude/skills/plansm ~/.claude/skills/
# Or for project-local installation: cp -r .claude/skills/plansm .claude/skills/

# 3. Install jq (only dependency)
brew install jq  # macOS
# or: sudo apt-get install jq  # Linux

# That's it! Ready to use in Claude Code with /plansm

What you get:

• Self-contained skill in .claude/skills/plansm/
• Shell-based verification engine (no binaries needed)
• Machine-verifiable proof system with 5 rule types
• Stop hook prevents fake completion
• Zero maintenance (pure shell scripts)

Quick Start

In Claude Code, run:

/plansm

Then describe what you want to build. plansm will:

1. Analyze your requirement and codebase
2. Generate plan.json with all steps and verification rules
3. Auto-execute each step:
   • Implement the code
   • Verify it passes tests
   • Advance to next step
4. Report when all steps are VERIFIED

That's it. No manual planning, no running commands, just results.

Example Usage

User: /plansm
Claude: What would you like to build?
User: Add dark mode toggle to my React app

Claude: Analyzing requirements...
Generating plan with 5 steps...

STEP_001: Create theme context ✓
STEP_002: Create toggle component ✓
STEP_003: Add CSS variables ✓
STEP_004: Integrate in header ✓
STEP_005: Run tests ✓

All steps verified! Dark mode implemented.

Plan File Structure

Each task gets its own plan.json file generated by the skill. This file is gitignored by default since it's task-specific working state.

Note: The repository includes plan.json.example showing the format - actual plan.json files are created per-task and not committed.

{
  "version": 1,
  "current_step": "STEP_001",
  "steps": [
    {
      "id": "STEP_001",
      "objective": "Initialize project skeleton",
      "status": "PENDING",
      "verify": [
        { "type": "command", "cmd": "test -d ." }
      ]
    },
    {
      "id": "STEP_002",
      "objective": "Implement login API",
      "status": "LOCKED",
      "depends_on": ["STEP_001"],
      "verify": [
        { "type": "command", "cmd": "npm test -- login", "expect": { "exit_code": 0 } }
      ]
    }
  ]
}

Statuses: LOCKED | PENDING | FAILED | VERIFIED

Verify rule types:

• command: run bash command, check exit code and optional stdout regex
• file_exists: check if file or directory exists
• file_contains: check if file contains regex pattern
• http: check HTTP response status and optional body pattern
• glob_pattern_check: verify ALL files matching glob contain pattern (fixes sampling verification trap)

Documentation

• Quick Start Guide — Get started in 5 minutes
• Concept — Why Markdown planning fails
• Claude Code Integration — Hooks, commands, workflows
• Examples — Node.js, Python projects

Anti-Cheating Features

1. State Machine Enforcement: Only verification scripts can set VERIFIED status
2. Stop Hook: Claude Code hook prevents stopping until all steps verified
3. CI Verification: Automated verification in CI/CD pipelines
4. Audit Trail: All state changes tracked in git history
5. JSON Schema: Structure validation

Contributing

Contributions welcome! Please read CONTRIBUTING.md.

Development Setup

git clone https://github.com/spytensor/plansm.git
cd plansm

# Test the skill locally
cp -r .claude/skills/plansm ~/.claude/skills/
# Then use /plansm in Claude Code

# Test verification scripts
bash ~/.claude/skills/plansm/scripts/verify.sh --help

Roadmap

• SQLite backend (in addition to JSON)
• Web UI for plan visualization
• More verify rule types (Docker, API contracts)
• Plan templates library
• VS Code extension integration
• Multi-language support for verification rules

License

MIT License - see LICENSE for details.

Credits

Inspired by the discussion on LLM planning failures and the need for verifiable, machine-enforced completion criteria.

---

plansm — Because "looks done" ≠ "is done"