jons-plan Plugin
A Claude Code plugin inspired by Anthropic's Effective Harnesses for Long-Running Agents blog post for managing complex, multi-session coding tasks.
Prerequisites
- Claude Code v2.1.3+ (the Anthropic CLI tool)
- uv - Python package runner (
curl -LsSf https://astral.sh/uv/install.sh | sh)
- graphviz (optional) - For workflow viewer (
brew install graphviz)
- Codex plugin (optional) - For planning panel and Codex review tasks (
/plugin install codex)
Installation
Install via Claude Code's plugin marketplace:
/plugin marketplace add jonmmease/jons-plan
/plugin install jons-plan@jonmmease-jons-plan
Then restart Claude Code and test with /jons-plan:status.
Overview
When AI agents work on complex projects that span multiple context windows, each new session starts with no memory of what came before. This plugin solves that problem by providing:
- Structured task management with dependencies and status tracking
- Progress logging to orient Claude at the start of each session
- Task-level progress for fine-grained resumption context
- Automatic session resumption when tasks were interrupted
- PreCompact hook to preserve state during context compaction
- Parallel task execution via subagents for independent work
- Workflow-based execution with phase transitions and state machine
- Planning panel — 2-agent parallel planning (Opus + Codex CLI) with senior-architect synthesis
- Artifact system with phase-level and plan-level artifact tracking
- Dead-end tracking to prevent repeating failed approaches
For detailed architecture documentation, see docs/architecture.md.
How It Works
The plugin uses a two-agent architecture:
Planning Agent (/jons-plan:new)
Creates the infrastructure for a new plan:
- Analyzes your request and suggests an appropriate workflow
- Conducts pre-research and records a research brief
- Sets up the plan structure and initial phase
- Creates
request.md with the refined/approved request
Coding Agent (/jons-plan:proceed)
Works incrementally on tasks across sessions:
- Reads progress log to understand current state
- Resumes any
in-progress tasks first
- Handles phase transitions automatically
- Updates task status and logs progress for the next session
Planning Panel
Workflows with planning_panel = true use two independent agents to generate plans in parallel, then a senior synthesis agent reviews both and produces the definitive plan:
- Opus — via Claude Code Task tool
- Codex — via
/codex:rescue skill (background)
- Synthesis — Opus reviews both, investigates disagreements, dismisses weak ideas, and produces the final plan
The synthesis agent has full authority to investigate the codebase, dismiss incorrect concerns, add missing elements, and restructure the plan. It is not a mechanical merger — it is the decision-maker.
Slash Commands
| Command | Purpose |
|---|
/jons-plan:new [topic] | Create new plan (auto-suggests workflow type) |
/jons-plan:plan [feedback] | Refine the active plan |
/jons-plan:proceed | Start/continue implementing tasks |
/jons-plan:switch [name] | Switch to a different plan |
/jons-plan:status | Show all plans and task progress |
/jons-plan:viewer | Open the workflow viewer |
Use --workflow <name> with /new to specify workflow type explicitly.
Workflow Types
| Workflow | Purpose |
|---|
implementation | Build features, fix bugs with research and validation |
direct-implementation | Simple plan-implement-verify for familiar code (no research) |
design | Research, explore, produce design.md |
design-and-implementation | Design first, optionally implement after approval |
deep-implementation | Thorough research + external review before implementation |
dynamic | Research-first, phases generated based on codebase exploration |
iteration | Iterative execute-evaluate-generate loops for long-horizon goals |
review-tour | Generate guided PR review tour from a GitHub PR URL |
code-review | Review code changes + generate PR description |
pr-review | Review existing PR description for quality |
deslop-pr | Detect and remove AI-generated patterns from PR descriptions |
tech-docs | Technical documentation with multi-source research |
tech-docs-review | Review RFCs, design docs, proposals with structured criteria |
Auto-selection: When no --workflow is specified, the plugin analyzes your request and suggests the most appropriate workflow.
Plan Directory Structure
