plan-tree 0.2.1

package/README.md

@@ -0,0 +1,156 @@
+# Plan Tree
+
+[中文说明](README.zh-CN.md)
+
+![Plan Tree](assets/plan-tree.jpg)
+
+> 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.
+- 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 notes for solution maps, boundaries, risks, and acceptance criteria.
+- Implementation status and handoff notes.
+- Historical verification and checkpoint evidence.
+
+Default shape:
+
+```text
+docs/plantree/
+  README.md
+  baseline/
+  plans/<plan-name>/
+    README.md
+    roadmap.md
+    implementation-status.md
+    open-questions.md
+    topics/
+    decisions/
+    history/
+  ideas/inbox.md
+```
+
+Mature existing planning trees do not need to be forced into `docs/plantree/`. They can be registered, bridged, and migrated gradually.
+
+## 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 main usage pattern is to add this English memory rule to `AGENTS.md`, team memory, or agent memory. Providers can then invoke `plan-tree` automatically whenever planning, clarification, progress tracking, or plan-to-execution coordination is involved.
+
+```md
+## 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.
+
+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.
+
+`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 PyPI or npm, then install the skill for your provider:
+
+```bash
+python -m pip install seemseam-plan-tree
+plan-tree install --provider claude
+```
+
+```bash
+npm install -g plan-tree
+plan-tree install --provider opencode
+```
+
+Supported providers:
+
+```bash
+plan-tree install --provider claude
+plan-tree install --provider opencode
+plan-tree install --provider codex
+plan-tree install --provider all
+```
+
+The installer copies only the skill payload: `SKILL.md`, `VERSION`, README files, `references/`, `assets/`, and Codex/OpenAI metadata when installing for Codex. It does not install `.ccb/`, git state, logs, generated artifacts, or project runtime files.
+
+For local development or offline installation, point the installer at this repository:
+
+```bash
+plan-tree install --provider claude --source /path/to/plan-tree
+```
+
+You can also clone this repository directly into your skill directory:
+
+```bash
+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:
+
+```bash
+git clone https://github.com/SeemSeam/plan-tree.git /path/to/skills/plan-tree
+```
+
+## Repository Contents
+
+```text
+VERSION
+SKILL.md
+pyproject.toml
+package.json
+bin/plan-tree.js
+agents/openai.yaml
+references/maintenance-patterns.md
+references/legacy-migration.md
+assets/plan-tree.jpg
+README.md
+README.zh-CN.md
+```

package/README.zh-CN.md

@@ -0,0 +1,156 @@
+# Plan Tree
+
+[English](README.md)
+
+![Plan Tree](assets/plan-tree.jpg)
+
+> 把短期 plans 变成一棵长期稳定、结构化的树。
+
+`plan-tree` 是一个通用的 AI planning skill，用于长期保存项目规划状态。它把临时 provider plans、讨论、决策、开放问题、交接状态和验证证据沉淀成一棵 Markdown 规划树，让项目跨会话、跨 agent 推进时不漂移。
+
+## 核心思想
+
+Provider 自带的 `plan` 通常是短期的、会话内的、任务级的。它能安排“下一步做什么”，但很难长期保存“为什么这么做、哪些方案被排除、哪些问题未决、当前进度到哪里、下一次应该从哪里继续”。结果是：计划用后即丢，项目越推进越容易漂移。
+
+AI 让这个问题更明显。过去很多项目接近 `10% 规划 + 90% 实施`：实现本身很慢，开发者有足够长的反馈周期边做边修正方向。AI 时代实现速度被大幅压缩，复杂项目更接近 `90% 规划 + 10% 实施`。这个比例不是精确工时，而是工作重心变化：质量越来越取决于前置方案是否充分、边界是否稳定、验收是否清楚、状态源是否统一。
+
+因此工作流也必须改变：不要继续“小规划 + 小推进 + 边落盘边想”。`plan-tree` 推荐大循环模式：先充分讨论、澄清、形成可落地方案图谱，再让 AI 批量执行；执行完成后，再把进度、证据和剩余问题回写到规划树。
+
+## Plan Tree 的意义
+
+结构化 plans 比结构化代码更好维护，是因为 plan 的结构主要约束表达和协作；代码结构还必须承载可执行行为、历史兼容、性能、依赖、失败和变化。Roadmap、Status、Decision、Open Questions、Risks、History 这些 plan 节点是稳定的语义槽位，新信息通常可以归类进去，不必改变树的结构。代码里的模块、类、函数、接口则是可执行边界；部分校验、用户配置、失败恢复、多租户、后台重试、老数据、第三方失败和性能压力都会穿透原来的边界。
+
+从这个角度看，`plan-tree` 是代码演化的意图空间和控制平面。代码库是实现空间；规划树是意图、约束、评价和投影空间。比如“parser 与 storage 必须解耦”不是代码，但它是作用在代码状态上的观察和约束。大部分实现变化都应该能投影回 plan：`Done`、`Blocked`、`Risk reduced`、`Decision changed` 或 `Question opened`。长期没有投影回 plan 的变化，就会变成不可见的漂移。
+
+Plan 的漂移更容易看见：`Next` 里全是已完成事项，`Open Questions` 里有已决问题，roadmap 和 status 对不上，两个文件重复表达同一个决策。代码漂移更隐蔽：程序还能跑、测试还能过，但模块职责变宽，抽象不再贴合现实，公共工具变成杂物间，层与层之间互相知道太多。
+
+设计和维护原则：
+
+- 保持节点类型稳定且语义化：roadmap、status、decisions、open questions、topics、history、ideas。
+- 分离意图、决策、当前状态、未解决问题、执行证据和历史细节。
+- 实现中发现新事实时，先更新 plan，避免它沉淀成无记录的架构变化。
+- 用链接关联文件，不要在多个地方重复同一条规则。
+- 把旧证据归档，让活跃 roadmap 和 handoff 保持短小。
+- 只有当 artifact、decision 或 verification 存在时，才把事项标为 done。
+- Open questions 只放未解决问题，不要当任务列表使用。
+
+## Plan Tree 保存什么
+
+一棵成熟的 planning tree 通常保存这些长期状态：
+
+- 规划入口和阅读路径：从哪里读、哪个文件说了算。
+- Roadmap 和当前进度：什么完成了、什么正在做、下一步是什么。
+- Decisions：稳定决策、上下文和后果。
+- Open questions：仍未解决的问题，而不是隐藏任务。
+- Topics：方案图谱，包括业务流程、架构边界、验收标准、风险和执行门禁。
+- Implementation status：当前交接、活跃 TODO、blockers、最近验证。
+- History：旧验证、检查点和过期证据，避免污染活跃状态。
+
+默认结构可以是：
+
+```text
+docs/plantree/
+  README.md
+  baseline/
+  plans/<plan-name>/
+    README.md
+    roadmap.md
+    implementation-status.md
+    open-questions.md
+    topics/
+    decisions/
+    history/
+  ideas/inbox.md
+```
+
+已有成熟规划树不必强行迁移到 `docs/plantree/`。可以先注册、桥接，再逐步整理。
+
+## 版本管理
+
+`plan-tree` 使用语义化版本管理公开发布：
+
+- `MAJOR`：skill 契约或默认树模型出现不兼容变化。
+- `MINOR`：新增 work modes、文档角色、模板或 provider metadata，且保持兼容。
+- `PATCH`：措辞修正、小型文档更新和兼容性安全的细节优化。
+
+当前版本写在 `VERSION` 文件中。发布 tag 使用 `vX.Y.Z` 格式，例如 `v0.1.0`。
+
+## 使用方式
+
+最重要的使用方式不是记命令，而是把下面英文规则写进项目记忆文件，例如 `AGENTS.md`、团队 memory 或 agent memory。之后 provider 会在相关任务中自动使用 `plan-tree`。
+
+```md
+## 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.
+
+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.
+
+`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.
+```
+
+## 安装
+
+先从 PyPI 或 npm 安装轻量 installer，再用 installer 安装 skill：
+
+```bash
+python -m pip install seemseam-plan-tree
+plan-tree install --provider claude
+```
+
+```bash
+npm install -g plan-tree
+plan-tree install --provider opencode
+```
+
+支持的 provider：
+
+```bash
+plan-tree install --provider claude
+plan-tree install --provider opencode
+plan-tree install --provider codex
+plan-tree install --provider all
+```
+
+installer 只复制 skill payload：`SKILL.md`、`VERSION`、README 文件、`references/`、`assets/`，以及安装到 Codex 时需要的 Codex/OpenAI metadata。它不会安装 `.ccb/`、git 状态、日志、生成物或项目运行态文件。
+
+本地开发或离线安装时，可以显式指定当前仓库：
+
+```bash
+plan-tree install --provider claude --source /path/to/plan-tree
+```
+
+也可以直接把仓库克隆到你的 skill 目录：
+
+```bash
+mkdir -p "$SKILLS_HOME"
+git clone https://github.com/SeemSeam/plan-tree.git "$SKILLS_HOME/plan-tree"
+```
+
+将 `SKILLS_HOME` 设置为你的 provider 使用的 skill 根目录。也可以直接克隆到明确路径：
+
+```bash
+git clone https://github.com/SeemSeam/plan-tree.git /path/to/skills/plan-tree
+```
+
+## 仓库内容
+
+```text
+VERSION
+SKILL.md
+pyproject.toml
+package.json
+bin/plan-tree.js
+agents/openai.yaml
+references/maintenance-patterns.md
+references/legacy-migration.md
+assets/plan-tree.jpg
+README.md
+README.zh-CN.md
+```

package/VERSION

@@ -0,0 +1 @@
+0.2.1

package/bin/plan-tree.js

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const PACKAGE_VERSION = "0.2.1";
+const REPO_URL = "https://github.com/SeemSeam/plan-tree.git";
+const SKILL_NAME = "plan-tree";
+
+const CORE_FILES = ["SKILL.md", "VERSION", "README.md", "README.zh-CN.md"];
+const CORE_DIRS = ["references", "assets"];
+
+const PROVIDER_TARGETS = {
+  claude: () => path.join(os.homedir(), ".claude", "skills", SKILL_NAME),
+  opencode: () => path.join(os.homedir(), ".config", "opencode", "skill", SKILL_NAME),
+  codex: () => path.join(process.env.CODEX_HOME || path.join(os.homedir(), ".codex"), "skills", SKILL_NAME)
+};
+
+function main(argv) {
+  const [command, ...rest] = argv;
+  if (command === "version") {
+    console.log(PACKAGE_VERSION);
+    return 0;
+  }
+  if (command === "install") {
+    return install(parseInstallArgs(rest));
+  }
+  usage();
+  return 2;
+}
+
+function usage() {
+  console.log("Use `plan-tree install --provider claude|opencode|codex`.");
+}
+
+function parseInstallArgs(args) {
+  const options = {
+    provider: "claude",
+    target: null,
+    source: null,
+    version: PACKAGE_VERSION,
+    force: false,
+    dryRun: false
+  };
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--provider") options.provider = requireValue(args, ++i, arg);
+    else if (arg === "--target") options.target = requireValue(args, ++i, arg);
+    else if (arg === "--source") options.source = requireValue(args, ++i, arg);
+    else if (arg === "--version") options.version = requireValue(args, ++i, arg);
+    else if (arg === "--force") options.force = true;
+    else if (arg === "--dry-run") options.dryRun = true;
+    else if (arg === "--help" || arg === "-h") {
+      usage();
+      process.exit(0);
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+
+  const allowed = [...Object.keys(PROVIDER_TARGETS), "all"];
+  if (!allowed.includes(options.provider)) {
+    throw new Error(`--provider must be one of: ${allowed.join(", ")}`);
+  }
+  if (options.target && options.provider === "all") {
+    throw new Error("--target cannot be combined with --provider all");
+  }
+  return options;
+}
+
+function requireValue(args, index, flag) {
+  const value = args[index];
+  if (!value || value.startsWith("--")) {
+    throw new Error(`${flag} requires a value`);
+  }
+  return value;
+}
+
+function install(options) {
+  const providers = options.provider === "all" ? Object.keys(PROVIDER_TARGETS) : [options.provider];
+  const source = options.source ? path.resolve(options.source) : cloneSource(options.version);
+
+  validateSource(source);
+  for (const provider of providers) {
+    const target = path.resolve(expandHome(options.target || PROVIDER_TARGETS[provider]()));
+    installToProvider(source, target, provider, options.force, options.dryRun);
+  }
+  return 0;
+}
+
+function cloneSource(version) {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "plan-tree-"));
+  const target = path.join(tmp, "source");
+  const result = spawnSync("git", ["clone", "--depth=1", "--branch", `v${version}`, REPO_URL, target], {
+    stdio: "inherit"
+  });
+  if (result.status !== 0) {
+    throw new Error("Failed to clone plan-tree. Install git or use --source /path/to/plan-tree.");
+  }
+  return target;
+}
+
+function validateSource(source) {
+  const missing = [];
+  for (const item of CORE_FILES) {
+    if (!fs.existsSync(path.join(source, item))) missing.push(item);
+  }
+  for (const item of CORE_DIRS) {
+    if (!fs.existsSync(path.join(source, item))) missing.push(item);
+  }
+  if (missing.length > 0) {
+    throw new Error(`${source} is not a valid plan-tree source; missing: ${missing.join(", ")}`);
+  }
+}
+
+function installToProvider(source, target, provider, force, dryRun) {
+  const planned = [...CORE_FILES, ...CORE_DIRS];
+  if (provider === "codex" && fs.existsSync(path.join(source, "agents"))) {
+    planned.push("agents");
+  }
+
+  console.log(`Installing plan-tree for ${provider} -> ${target}`);
+  if (dryRun) {
+    for (const item of planned) console.log(`  would copy ${item}`);
+    return;
+  }
+
+  if (fs.existsSync(target)) {
+    if (!force) throw new Error(`${target} already exists. Use --force to replace it.`);
+    fs.rmSync(target, { recursive: true, force: true });
+  }
+  fs.mkdirSync(target, { recursive: true });
+
+  for (const item of planned) {
+    copyPath(path.join(source, item), path.join(target, item));
+  }
+
+  console.log(`Installed plan-tree ${readVersion(target)}`);
+}
+
+function copyPath(source, target) {
+  const stat = fs.statSync(source);
+  if (stat.isDirectory()) {
+    fs.cpSync(source, target, { recursive: true });
+  } else {
+    fs.copyFileSync(source, target);
+  }
+}
+
+function readVersion(target) {
+  const versionPath = path.join(target, "VERSION");
+  if (fs.existsSync(versionPath)) {
+    return `v${fs.readFileSync(versionPath, "utf8").trim()}`;
+  }
+  return "unknown version";
+}
+
+function expandHome(value) {
+  if (value === "~") return os.homedir();
+  if (value.startsWith("~/")) return path.join(os.homedir(), value.slice(2));
+  return value;
+}
+
+try {
+  process.exitCode = main(process.argv.slice(2));
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "plan-tree",
+  "version": "0.2.1",
+  "description": "Installer for the portable plan-tree AI planning skill.",
+  "homepage": "https://github.com/SeemSeam/plan-tree",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SeemSeam/plan-tree.git"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "skills",
+    "planning",
+    "plan-tree"
+  ],
+  "bin": {
+    "plan-tree": "bin/plan-tree.js"
+  },
+  "files": [
+    "bin/plan-tree.js",
+    "README.md",
+    "README.zh-CN.md",
+    "VERSION"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "UNLICENSED"
+}