Plan Tree

中文说明

Turn short-lived plans into a long-term, stable, structured tree.

plan-tree is a portable AI planning skill for keeping project planning durable. It turns temporary provider plans, discussions, decisions, open questions, handoff state, and verification evidence into a Markdown planning tree that can survive many sessions and many agents.

Core Idea

Provider-native plan features are usually short-term, session-local task plans. They can answer "what should happen next", but they rarely preserve why a direction was chosen, what was rejected, which questions remain open, where progress stands, or where the next session should resume.

AI makes this failure mode sharper. Many older projects looked like 10% planning + 90% implementation: implementation was slow enough that humans could keep correcting direction while coding. In AI-assisted work, implementation is compressed, and complex projects often move closer to 90% planning + 10% implementation. The numbers are not exact accounting; they describe where quality is now won or lost.

That means the workflow must change. Do not keep doing small planning, small execution, and planning while mutating production files. plan-tree favors a larger loop: discuss and clarify first, shape an implementation-ready solution map, then let AI execute in larger batches. After execution, write progress, evidence, and remaining questions back into the planning tree.

Why It Matters

Structured plans are easier to maintain than structured code because they organize expression and collaboration. Structured code must also carry executable behavior, compatibility, performance, dependencies, failures, and change. Plan nodes such as roadmap, status, decisions, open questions, risks, and history are stable semantic slots: new information can usually be classified without changing the tree. Code modules, classes, functions, and interfaces are executable boundaries; real requirements such as partial validation, user configuration, recovery, multi-tenancy, retries, old data, third-party failures, and performance pressure can pierce those boundaries.

In that sense, plan-tree acts as an intent space or control plane for code evolution. The codebase is the implementation space; the planning tree is the space of intent, constraints, evaluation, and projection. A plan item such as "parser and storage must stay decoupled" is not code, but it is a useful observation and constraint over code. Most implementation changes can project back into plan state as Done, Blocked, Risk reduced, Decision changed, or Question opened. Changes that never project back into the plan become invisible drift.

This is why plan drift is easier to see: Next contains completed work, Open Questions contains settled issues, roadmap and status disagree, or two files describe the same decision. Code drift is more hidden: the program may still run and tests may still pass while module ownership widens, abstractions stop matching reality, shared utilities become junk drawers, and layers learn too much about each other.

Design and maintenance principles:

• Keep node types stable and semantic: roadmap, status, decisions, open questions, topics, history, and ideas.
• Separate intent, decision, current state, unresolved uncertainty, execution evidence, and historical detail.
• Treat implementation discoveries as plan updates before they become silent architecture changes.
• Link related files instead of duplicating the same rule in many places.
• Keep summaries short and split details into retrievable capsules, detail shards, evidence, and history.
• Archive old evidence so active roadmap and handoff files stay short.
• Mark work done only when the artifact, decision, or verification exists.
• Use open questions only for unresolved questions, not as a task list.

What It Stores

A mature planning tree keeps durable state such as:

• Entry point and reading path.
• Roadmap and current progress.
• Stable decisions.
• Open questions.
• Topic capsules and detail shards for solution maps, boundaries, risks, and acceptance criteria.
• Implementation status and handoff notes.
• Evidence records, historical verification, and checkpoint archives.

Default shape:

docs/plantree/
  README.md
  baseline/
  plans/001-<plan-name>/
    README.md
    roadmap.md
    implementation-status.md
    open-questions.md
    indexes/
    topics/
      README.md
      <topic>.md
      <topic>/
        contracts.md
        alternatives.md
        edge-cases.md
    decisions/
    evidence/
    history/
  ideas/inbox.md

For a new tree with no local naming convention, Plan roots use lightweight, project-wide IDs such as P001 and flat directories such as plans/001-authentication/. IDs are stable creation references, not priority positions: gaps are valid and IDs are never reused or renumbered.

Roadmap task labels such as T001 are optional and Plan-local. When used, the roadmap remains their only active identity, status, and ordering authority; a parallel task allocation registry is unnecessary. Affected code or product modules belong in Plan metadata such as Affected Modules: authentication, storage, using keys from baseline/module-map.md, not in another physical directory layer. Update canonical state and required entrypoint summaries in the same change, then check IDs, module keys, status, and links.

Mature existing planning trees do not need to be forced into docs/plantree/. They can be registered, bridged, and migrated gradually. Oversized existing trees can also be normalized in place. Create or update a migration map first, then keep short active summaries, move durable detail to detail shards, move verification to evidence, and preserve old reasoning in history or archive-only source notes.

Versioning

plan-tree uses Semantic Versioning for public releases:

• MAJOR: incompatible changes to the skill contract or default tree model.
• MINOR: new work modes, document roles, templates, or provider metadata that remain compatible.
• PATCH: wording fixes, small documentation updates, and compatibility-safe refinements.

The current version is stored in VERSION. Release tags use the vX.Y.Z format, for example v0.1.0.

Usage

The installer now adds a concise provider-specific persistent instruction by default, so new sessions can invoke plan-tree automatically for planning, clarification, progress tracking, and plan-to-execution coordination. For repository-shared policy or a more explicit project-level contract, add the fuller rule below to the project's AGENTS.md, CLAUDE.md, team memory, or agent memory.

## Plan Tree Usage Rule

Any project planning, roadmap discussion, requirement clarification, scope negotiation, implementation strategy, progress tracking, handoff, decision recording, open-question management, or plan-to-execution coordination must use the `plan-tree` skill as the planning authority and state store.

When a request is related to planning or implementation direction, first inspect the relevant plan-tree entrypoint and current plan state when available. If no plan-tree exists and the task needs durable planning state, initialize or propose the minimal `docs/plantree/` structure according to the skill rules.

For new Plan roots without an established project convention, use stable project-wide IDs such as `P001` with flat directories such as `plans/001-authentication/`. Keep optional task IDs in the roadmap as their sole active authority. Treat affected modules as metadata rather than physical Plan-directory parents, and never renumber IDs to express priority or status.

Before the solution is mature enough to implement, stay in planning and clarification mode. Deeply elicit and expand the user's intent into a concrete solution map: goals, non-goals, constraints, options, tradeoffs, risks, dependencies, acceptance criteria, verification path, and rollout or rollback notes. Record durable clarification results, open questions, assumptions, and decisions in plan-tree files when useful.

Do not start formal implementation in the main project surface while the plan still contains unresolved core ambiguity. At most, create a small isolated prototype or sample only when it helps validate the direction, and keep it clearly separate from the production path.

A plan is implementation-ready only when the scope, chosen approach, expected behavior, affected surfaces, acceptance criteria, verification method, and remaining risks are explicit enough that execution should not rely on "figure it out while coding." Once implementation-ready, proceed autonomously with the project changes, then update plan-tree status, decisions, open questions, and handoff notes to reflect the result.

Maintain same-change consistency: update the authoritative Plan Tree file and any required entrypoint summary together, then check IDs, paths, affected module keys, roadmap state, and relative links. Prefer read-only drift detection over watchers, automatic renumbering, or ambiguous repair.

`plan-tree` governs planning documents and execution readiness. It does not by itself authorize commits, pushes, releases, destructive file operations, or broad unrelated refactors unless the user explicitly asks for them.

Installation

Install the lightweight installer from npm, then install the skill for your provider:

npm install -g plan-tree
plan-tree install codex

Common usage:

plan-tree version
plan-tree install claude
plan-tree install opencode
plan-tree install codex
plan-tree install all

You can also install the same plan-tree command from PyPI:

python -m pip install seemseam-plan-tree
plan-tree install claude

The npm package exposes a plan-tree binary through its bin field. Install it globally when you want to run plan-tree directly from any shell. A local install with npm install plan-tree exposes the command only inside npm's local binary path, so run it with npx plan-tree ..., npm exec plan-tree -- ..., or ./node_modules/.bin/plan-tree ....

Supported install targets:

plan-tree install claude
plan-tree install opencode
plan-tree install codex
plan-tree install all

By default, each install also creates or updates one managed Plan Tree block in the provider's official user-global instruction file:

Provider	Persistent instruction file
Claude Code	~/.claude/CLAUDE.md
OpenCode	~/.config/opencode/AGENTS.md
Codex	$CODEX_HOME/AGENTS.md, defaulting to ~/.codex/AGENTS.md

The installer owns only the text between <!-- plan-tree:instructions:start --> and <!-- plan-tree:instructions:end -->. Existing user content and file permissions are preserved, and repeated installs replace only that block. These files are persistent session instructions, not replacements for a provider's built-in system prompt or a security policy.

Use --no-instructions to install only the skill, or --dry-run to inspect both the skill and instruction targets without writing:

plan-tree install codex --no-instructions
plan-tree install all --dry-run

--force replaces an existing skill directory but never replaces the whole instruction file. If managed markers are missing, duplicated, or reversed, installation stops for manual repair before any existing skill is replaced. A custom --target changes only the skill directory; persistent instructions retain the provider's official global path.

The skill payload contains SKILL.md, VERSION, README files, references/, prompts/, assets/, and Codex/OpenAI metadata when installing for Codex. It does not install .ccb/, git state, logs, generated artifacts, or project runtime files. Provider path behavior follows the official Claude Code memory, OpenCode rules, and Codex AGENTS.md documentation.

For local development or offline installation, point the installer at this repository:

plan-tree install claude --source /path/to/plan-tree

You can also clone this repository directly into your skill directory:

mkdir -p "$SKILLS_HOME"
git clone https://github.com/SeemSeam/plan-tree.git "$SKILLS_HOME/plan-tree"

Set SKILLS_HOME to the skill root used by your provider. Or clone directly to an explicit path:

git clone https://github.com/SeemSeam/plan-tree.git /path/to/skills/plan-tree

Direct cloning installs only the skill payload; use the installer when you also want managed persistent instructions.

Repository Contents

VERSION
SKILL.md
pyproject.toml
package.json
bin/plan-tree.js
agents/openai.yaml
prompts/claude.md
prompts/opencode.md
prompts/codex.md
references/maintenance-patterns.md
references/legacy-migration.md
docs/releases/v0.4.0.md
tests/test_plantree_contract.py
tests/test_installer_instructions.py
assets/plan-tree.jpg
README.md
README.zh-CN.md