plan-tree

name	plan-tree
description	Incrementally builds a recursive tree of implementation-plan files under docs/plans/<root-topic>/, one node at a time, fully user-paced. Each node's plan is produced by an internal Claude<->Codex cross-review and written in the full gen-plan format (Goal, Acceptance Criteria with TDD tests, Path Boundaries, Feasibility Hints, Dependencies, Task Breakdown, Claude-Codex Deliberation, Pending User Decisions). A node can be generated from a spec/design file of any text format, a draft co-written in discussion, or pure discussion with no file. The root stays high-level; detail lives in children. There is no loop, no Stop hook, no cron, no budget, no auto-progression -- the user pushes each step. Use to grow a structured plan hierarchy where every node is independently cross-reviewed. Triggers on "plan tree", "plan-tree", "build a plan tree", "decompose this plan into sub-plans", "add a sub-plan", "grow the plan tree", or requests to recursively break a design into cross-reviewed plan files.
user-invocable	true
argument-hint	<create|decompose|refine|show|next> [topic] [--from <spec-path>]

Plan Tree

Grow a recursive tree of implementation plans under docs/plans/<root-topic>/. Each node is a full-format plan, produced by an internal cross-review between Claude and Codex, and linked into its parent. The tree is built one node at a time, entirely user-driven -- this skill never loops, never schedules, never auto-advances. You ask for one node; the skill generates it and stops.

Mental Model

• A node is one plan file. The root frames the whole effort at a high level; each child frames one slice in more detail. Every node uses the same full format (see references/plan-template.md).
• The tree mirrors decomposition: when a topic is simple it is a leaf (a lone plan-<topic>.md in its parent folder); when it grows sub-parts it becomes a folder holding plan-<topic>.md plus children.
• No status markers anywhere. Titles are clean plan titles. A parent's ## Sub-plans list is only links + one-line descriptions. The user tracks progress mentally.

File Tree And Naming (strict)

• Root location: docs/plans/<root-topic>/ (relative to the repo where the user is working). The <root-topic> segment is a slug of the root topic.
• Only the root main plan is named plan.md. Every other node is plan-<localtopic>.md, using the local topic only, with no lineage prefix (e.g. plan-stripe.md, never plan-payments-stripe.md).
• No numeric or order prefixes on any file or folder.
• A leaf topic is a single file plan-<topic>.md in its parent's folder. Do not create a folder for a single md file.
• A topic that decomposes into multiple sub-plans is a folder <topic>/ containing plan-<topic>.md plus its children. When a previously-leaf topic later needs children, promote it: move plan-<topic>.md into a new <topic>/ folder, then add children there.

Example layout:

docs/plans/checkout-revamp/
  plan.md
  plan-cart.md
  payments/
    plan-payments.md
    plan-stripe.md
    refunds/
      plan-refunds.md
      plan-api.md

Naming and the leaf->folder move are handled by the helper so the invariants are never reconstructed by hand:

SH="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/skills/plan-tree}/references/tree-path.sh"
# (when run outside a plugin, point SH at this skill's references/tree-path.sh)
bash "$SH" slug "Payments / Stripe"          # -> payments-stripe
bash "$SH" leaf-file "Cart"                   # -> plan-cart.md
bash "$SH" folder-files "Refunds API"         # -> refunds-api/ , refunds-api/plan-refunds-api.md
bash "$SH" root-init --root <repo>/docs/plans "Checkout Revamp"   # -> .../checkout-revamp/plan.md
bash "$SH" promote --root <parent-dir> "Stripe"                  # leaf -> folder, prints new main-file path

The full plan format lives in references/plan-template.md; copy it as the starting skeleton for every node.

Operations

All operations are manual and user-paced. Pick the one matching the user's request. Generate exactly the node(s) the user asked for, then stop.

create -- start a new tree

Use when there is no tree yet, or the user wants a new root topic.

1. Intake the source for the root node (see Input Intake). The root is the high-level framing of the whole effort; keep its acceptance criteria and task breakdown at the level of major components, deferring detail to future children.
2. Compute the root path: ROOT_PLAN=$(bash "$SH" root-init --root <repo>/docs/plans "<root topic>"). This creates docs/plans/<root-slug>/ and yields the plan.md path. If the tree already exists, tell the user and switch to decompose/refine instead of overwriting.
3. Run the Cross-Review Pipeline for the root node.
4. Write the full-format plan to ROOT_PLAN. Its ## Sub-plans section starts empty (no children yet).
5. Report the path and a one-line summary. Stop.

decompose -- add children to a node

Use when a node should be broken into sub-plans, or the user names a child topic to add under an existing node.

1. Identify the parent node file and its directory PARENT_DIR (the folder the parent's main plan sits in).
2. Promote the parent if it is currently a leaf. If the parent is PARENT_DIR/plan-<p>.md and you are giving it children, run bash "$SH" promote --root <grandparent-dir> "<p>"; the parent's main file moves to <p>/plan-<p>.md and PARENT_DIR becomes that new <p>/ folder. The root (plan.md) is already a folder and never needs promotion.
3. For each child topic the user asked for (one node per request is the normal cadence): a. Decide leaf vs folder. Default to leaf: a child starts as PARENT_DIR/plan-<child>.md (bash "$SH" leaf-file "<child>"). Only make it a folder immediately if the user already wants grandchildren under it. b. Run Input Intake for the child's source. c. Run the Cross-Review Pipeline for the child node. d. Write the child's full-format plan at the computed path. e. Link it into the parent. Append a bullet to the parent main plan's ## Sub-plans section: - [<child topic>](<relative-path>) - <one-liner>. The relative path is from the parent main file to the child file (a sibling leaf is just plan-<child>.md; a child folder's main file is <child>/plan-<child>.md).
4. Report what was added and stop. Do not continue to grandchildren unless asked.

refine -- re-review or edit a node

Use when an existing node needs to change (new requirements, a resolved decision, a flawed criterion).

• For a substantive change, re-run the Cross-Review Pipeline for that node using the updated source/discussion, then rewrite the node file in place. Preserve its ## Sub-plans links and any still-relevant resolved decisions.
• For a small edit (fix a typo, mark a DEC-N as decided, reword one AC), edit the node file directly; a full cross-review is not required.
• Never rename or move a node during refine unless the user is decomposing it (that is decompose). Refine does not change tree structure.

show / next -- render the tree and point at the next node

Use when the user wants to see the tree or asks "what's next".

1. Render the tree from the filesystem (structure only, no status):

# Substitute ROOT_DIR for the actual tree root before running:
ROOT_DIR="$PWD/docs/plans/<root-slug>"   # <root-slug> = slug of the root topic
find "$ROOT_DIR" -type f -name '*.md' | sort

Present it as an indented outline: the root plan.md first, then each child by folder nesting, each line showing the node's plan title (read the # H1) and its one-line description from the parent's ## Sub-plans entry. 2. For next, do not invent progress state. Instead surface candidate nodes to work on by reading the tree: list leaf nodes whose plans still contain unresolved DEC-N (Decision Status: PENDING) or partially_converged convergence status, and any ## Sub-plans one-liners that describe work not yet broken out into a child file. Recommend one focus node and explain why, but let the user choose. This is advisory only -- there is no automatic progression.

Input Intake

A node can be generated from any of these; a draft is not required. When the user passes --from <path>, that path is the spec/design file for this node -- read it per the first bullet below and record it under Source:

• A spec/design file of any text format -- .md, .txt, .rst, .org, source code, etc. Read it with the Read tool. Reference it by path in the node's ## Implementation Notes -> Source; do not paste large files inline.
• A draft co-written with the user through discussion -- capture the agreed points. If short, inline the draft verbatim under Source so the node is self-contained; if it grew large, save it as a file first and reference it.
• Pure discussion with no file -- record the discussion's substance under Source as "discussion-only" and inline the key points.

Confirm the source with the user only if it is ambiguous which input drives the node. Do not require a file when discussion suffices.

Cross-Review Pipeline (per node)

This is a self-contained reimplementation of a Claude<->Codex cross-review. It does not call the humanize gen-plan flow. Run it once per node, in order.

Scope guard: this pipeline only produces a plan document for the node. It must not implement tasks, modify source code, or make commits. The only file written is the node's plan (plus, in decompose, the one-line link appended to the parent's ## Sub-plans).

1. Input intake

Resolve the node's source per Input Intake above (spec file / discussion draft / pure discussion). Assemble a compact context block: the node's topic, its place in the tree (root vs which parent), the source content (or a faithful summary plus the file path), and the repo context relevant to this node.

2. Codex first-pass analysis (headless)

Ask Codex, non-interactively, to critique the source before Claude drafts. Use codex exec in read-only sandbox (the review must never modify files) and capture only its final message:

CODEX_OUT="$(mktemp)"
codex exec \
  -m gpt-5.5 -c model_reasoning_effort=high \
  -s read-only --skip-git-repo-check \
  -C <repo-root> \
  -o "$CODEX_OUT" - <<'PROMPT'
You are doing a first-pass planning analysis for ONE node of a recursive
implementation-plan tree. Do not write code. Critique assumptions, find missing
requirements, and propose stronger directions for THIS node's scope only.

<inject: node topic, tree position, source content or summary + path, repo context>

Respond using exactly these labelled sections:
CORE_RISKS:            highest-risk assumptions and failure modes
MISSING_REQUIREMENTS:  likely-omitted requirements or edge cases
TECHNICAL_GAPS:        feasibility or architecture gaps
ALTERNATIVE_DIRECTIONS: viable alternatives with tradeoffs
QUESTIONS_FOR_USER:    questions needing explicit human decisions
CANDIDATE_CRITERIA:    candidate acceptance criteria for this node
PROMPT
# Read the analysis:  cat "$CODEX_OUT"

Substitute the heredoc body and <repo-root> for the real values (build the prompt as a normal string; the <<'PROMPT' form just shows structure). Preserve the result as Codex Analysis v1.

Codex availability: if codex exec fails (missing CLI, non-zero exit, timeout), use AskUserQuestion to let the user choose: retry, or proceed Claude-only and explicitly record reduced cross-review confidence in the node's ## Claude-Codex Deliberation -> Convergence Status.

Alternative path: the codex-plugin-cc /codex:review / /codex:adversarial-review commands review git diffs (--uncommitted / --base) and are well-suited to reviewing already-written code, not a free-form plan draft. For node planning, the direct codex exec call above is the cleaner self-contained choice. If those commands are installed and the user prefers them, they are an acceptable substitute for the convergence rounds.

3. Claude candidate plan v1

Using the source + Codex Analysis v1, draft the node's plan in the full format. Investigate the codebase with Explore subagents (Task tool, subagent_type: "Explore") for components, files, patterns, and dependencies this node touches. Keep root-level nodes high-level and push detail into prospective children. Draft every section of references/plan-template.md, including TDD positive/negative tests per AC and coding/analyze tags per task.

4. Convergence loop (Claude <-> Codex, max 3 rounds)

Repeat, feeding the current candidate plan back to Codex with the same headless codex exec invocation (read-only), prompting for this exact format:

AGREE:               points accepted as reasonable
DISAGREE:            points considered unreasonable, with why
REQUIRED_CHANGES:    must-fix items before convergence
OPTIONAL_IMPROVEMENTS: non-blocking improvements
UNRESOLVED:          opposite opinions needing a user decision

Each round: include the current candidate plan and the list of prior disagreements / unresolved items. Then Claude revises the plan to address REQUIRED_CHANGES, recording accepted/rejected suggestions with rationale, and updates a convergence matrix (Topic | Claude position | Codex position | Resolution status resolved/needs_user_decision/deferred | round delta).

Stop when any holds:

• No REQUIRED_CHANGES remain and no high-impact DISAGREE remains.
• Two consecutive rounds produce no material plan changes.
• 3 rounds reached.

Set PLAN_CONVERGENCE_STATUS=converged when the convergence conditions are met, else partially_converged; carry any unresolved opposite opinions to step 5.

5. Resolve user decisions

Consolidate all user-facing questions into ## Pending User Decisions:

• QUESTIONS_FOR_USER from Codex Analysis v1, plus convergence-matrix items marked needs_user_decision (use the last round's state). Deduplicate by topic; drop only items with clear evidence they were resolved during refinement.
• Quantitative metrics: scan the source for numeric thresholds (latency, size, counts, percentages). For each, use AskUserQuestion to confirm whether it is a hard requirement or an optimization trend/direction -- this changes how the AC is written. Record the answer.
• For remaining open disagreements, use AskUserQuestion to let the user decide. Record each as DEC-N with Claude Position, Codex Position, Tradeoff Summary, and Decision Status (PENDING until the user decides). Open questions with no opposing position use Codex Position: N/A - open question.

6. Write the node and link it

1. Write the full-format plan to the computed node path (create -> the plan.md from root-init; decompose -> the leaf/folder path from the helper). Fill ## Claude-Codex Deliberation (Agreements, Resolved Disagreements, Convergence Status + rounds executed) and ## Pending User Decisions from the steps above. Record the source path under ## Implementation Notes -> Source.
2. Link into the parent (decompose only): append one bullet to the parent main plan's ## Sub-plans section -- - [<topic>](<relative-path>) - <one-liner> -- with no status marker.
3. Read the finished node back once and check internal consistency (ACs vs tasks vs boundaries; no contradictions). Fix with Edit if needed.

Guardrails

• Manual only. One node (or the small set the user named) per invocation, then stop. Never loop, schedule a cron, install a Stop hook, set a budget, or auto-progress to children.
• No status markers in titles, the tree listing, or ## Sub-plans.
• Naming is strict. Root file is plan.md; all others plan-<localtopic>.md with the local topic only and no numeric prefix; leaf = lone file, decomposed = folder. Always go through references/tree-path.sh for paths and promotion.
• Plan generation does not write code. The only writes are node plan files and the parent's link line.
• Codex is required for a true cross-review. If it is unavailable, proceed Claude-only only with the user's consent and record the reduced confidence in the node.
• This host is headless (SSH, no display/audio); all skill output is terminal text and the plan files themselves -- no desktop notifications.