From dfc08488318d9e871fe7f9e0aadd0098f2923b95 Mon Sep 17 00:00:00 2001 From: TreeWork Development Date: Wed, 12 Aug 2026 21:49:48 +0800 Subject: [PATCH 1/8] Add standalone TreeWork Manual skill --- AGENTS.md | 3 + README.md | 22 +++ README.zh-CN.md | 19 +++ RELEASE-NOTES.md | 6 +- skills/treework-manual/SKILL.md | 276 ++++++++++++++++++++++++++++++++ 5 files changed, 325 insertions(+), 1 deletion(-) create mode 100644 skills/treework-manual/SKILL.md diff --git a/AGENTS.md b/AGENTS.md index 640029f..5793537 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -21,6 +21,9 @@ adapter, and the shared source used to maintain both. documents. - `adapters/pi/` is the focused Pi host surface. Reuse the shared Skill, CLI, transactions, and MCP server; do not fork their state or semantics. +- `skills/treework-manual/` is the standalone manual variant. Keep its working + contract in one `SKILL.md` and do not make it depend on the CLI, hooks, + schemas, Git worktrees, fixed coding stages, or Project Map. - Agent references explain how to use TreeWork. Do not put Rust modules, API internals, migration plans, or frontend architecture there. - `project-map-ui/` is source; `plugins/treework/assets/graph-panel/` diff --git a/README.md b/README.md index 88c0c74..fc1459d 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,23 @@ structure, branch state, Specs, progress, findings, and verification outside the model context so work can resume without reconstructing the project from scratch. +## Choose The Right Form + +- **Full TreeWork** is the coding-agent system documented below. It adds + Alignment, Specs, declarative Tree transactions, isolated Git worktrees, + protected completion, Recall, and Project Map through the Codex plugin or Pi + adapter. +- **[TreeWork Manual](skills/treework-manual/SKILL.md)** is a standalone, + single-file Agent Skill for writing, research, notes, planning, creative work, + and other long-running tasks. It keeps the original TreeWork mental model and + Markdown state documents without requiring a CLI, fixed stages, Git, hooks, + or Project Map. + +Use the full system when coding work needs deterministic state and isolation. +Use the Manual Skill when a capable Agent only needs a durable way to locate +itself, work inside one branch, checkpoint reality, and move through a project +Tree. + ## First Install TreeWork currently targets Codex and Pi on macOS and Linux. Native Windows @@ -239,11 +256,16 @@ The Pi package manifest and focused extension live under MCP server. TreeWork stores project state under `.TreeWork/`; neither host adapter creates a second source of truth. +The standalone [`skills/treework-manual`](skills/treework-manual) directory +contains only the Manual Skill. Agent Skills-compatible hosts can install or +load that directory directly without the coding runtime. + ## Repository Layout ```text plugins/treework/ Installable Codex plugin and shared runtime adapters/pi/ Focused Pi extension, tests, and host docs +skills/treework-manual/ Standalone manual TreeWork Skill project-map-ui/ React/D3/SVG Project Map source docs/product/ Product behavior and UX contracts docs/architecture/ Runtime and transaction contracts diff --git a/README.zh-CN.md b/README.zh-CN.md index b00c6f2..ba92de2 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -19,6 +19,20 @@ TreeWork 是一套面向 Coding Agent 的**树引导开发系统**，同时提 TreeWork 将已接受的项目结构、branch 状态、Spec、进度、结论和验证记录保存在 模型上下文之外，让长期任务不必每次从头重建项目就能继续。 +## 选择合适的形态 + +- **完整 TreeWork** 是下文介绍的 Coding Agent 系统。它通过 Codex 插件或 Pi + adapter 提供 Alignment、Spec、声明式 Tree transaction、隔离 Git worktree、 + completion 保护、Recall 和 Project Map。 +- **[TreeWork Manual](skills/treework-manual/SKILL.md)** 是一份独立、单文件的 + Agent Skill，适用于写作、研究、笔记、规划、创作及其他长期任务。它保留原始 + TreeWork 的工作心智模型和 Markdown 状态文档，不依赖 CLI、固定阶段、Git、 + Hooks 或 Project Map。 + +Coding 工作需要确定性状态与隔离时使用完整系统。一个有能力的 Agent 只需要知道 +自己在哪里、在一条 branch 内工作、留下可恢复现实并沿项目 Tree 移动时，使用 +Manual Skill。 + ## 首次安装 TreeWork 当前面向 macOS 和 Linux 上的 Codex 与 Pi。原生 Windows 支持尚未 @@ -218,11 +232,16 @@ Pi package manifest 和聚焦的扩展位于 [`adapters/pi`](adapters/pi)，并 同一份 Skill、运行时和 MCP 服务。TreeWork 将项目状态保存在 `.TreeWork/` 下； 两个 host adapter 都不会创建第二事实源。 +独立的 [`skills/treework-manual`](skills/treework-manual) 目录只包含 Manual +Skill。兼容 Agent Skills 的 host 可以直接安装或加载这个目录，不需要 coding +runtime。 + ## 仓库结构 ```text plugins/treework/ 可安装的 Codex 插件及共享运行时 adapters/pi/ 聚焦的 Pi 扩展、测试与 host 文档 +skills/treework-manual/ 独立的手动 TreeWork Skill project-map-ui/ React/D3/SVG Project Map 源码 docs/product/ 产品行为和交互契约 docs/architecture/ 运行时和 transaction 契约 diff --git a/RELEASE-NOTES.md b/RELEASE-NOTES.md index 37d4566..63b0dbd 100644 --- a/RELEASE-NOTES.md +++ b/RELEASE-NOTES.md @@ -1,7 +1,11 @@ # Release Notes -## Unreleased - Pi Host Adapter +## Unreleased +- Adds `treework-manual`, a standalone single-file Agent Skill that preserves + TreeWork's root-to-branch mental model and Markdown project state for writing, + research, notes, planning, and other non-coding work without the CLI or + Project Map. - Adds a focused Pi package that directly reuses TreeWork's Skill, Rust runtime, and read-only MCP server without introducing a second project-state model. - Keeps Pi's always-active Agent-tool surface to one deferred loader for Recall, diff --git a/skills/treework-manual/SKILL.md b/skills/treework-manual/SKILL.md new file mode 100644 index 0000000..68bc794 --- /dev/null +++ b/skills/treework-manual/SKILL.md @@ -0,0 +1,276 @@ +--- +name: treework-manual +description: Use TreeWork Manual to keep long-running, multi-part work oriented through a Markdown project tree. Trigger for writing, research, note systems, planning, creative work, operations, or other evolving work where an Agent must preserve global direction, local progress, discoveries, and an exact restart point across interruptions or handoffs without relying on TreeWork CLI, Git worktrees, fixed development stages, or Project Map. +--- + +# TreeWork Manual + +TreeWork Manual is a way of working, not a command system. Treat the work as a +tree of owned scopes instead of a flat task list or a conversation the Agent is +expected to remember. The root supplies the global map. Each branch owns one +coherent line of work. Move through that tree deliberately so another Agent, or +the same Agent after context loss, can recover the work from files rather than +reconstructing it from fragments. + +```text +Start at the root +-> locate the right branch +-> work within that branch +-> leave a recoverable state +-> return to the root +-> choose the next branch +``` + +A branch is a work scope, not necessarily a Git branch. Depending on the work, +branches may be chapters, themes, research questions, note collections, +deliverables, phases, modules, clients, or any other useful decomposition. + +## Core Mental Model + +1. **Locate before acting.** Route each meaningful request to the root, the + current branch, another existing branch, or a genuinely new branch before + doing the work. +2. **Keep global and local state separate.** Keep the root concise and + navigational. Keep details inside the branch that owns them. +3. **Move instead of jumping.** When attention must move elsewhere, first leave + the current branch in a state that can be resumed without conversation + history. +4. **Let reality correct the documents.** Plans express intent; Progress records + what is actually true. When artifacts, user direction, and older documents + disagree, investigate and synchronize them instead of preserving a stale + story. +5. **Grow the Tree only as needed.** Sketch enough structure to orient the work, + then refine it as understanding improves. Do not invent a large branch + hierarchy merely to appear organized. + +User requests may arrive in a jumpy order. Treat them as routing signals, not +permission to teleport between unrelated work. If the request belongs to +another branch, checkpoint the current branch, return to the root view, and +then enter the target branch. + +## State Documents + +Use this default layout: + +```text +.TreeWork/ + PROJECT.md + task_plan.md + progress.md + findings.md + branches/ + / + task_plan.md + progress.md + findings.md + / + task_plan.md + progress.md + findings.md + / + task_plan.md + progress.md + findings.md +``` + +These four document roles are the minimum shared language of TreeWork: + +- **`PROJECT.md` answers "What is this work and how is it organized?"** Keep the + purpose, durable constraints, Tree map, and branch meanings here. Do not turn + it into a status dashboard or detailed work log. +- **`task_plan.md` answers "What do we intend to do?"** Keep desired outcomes, + ordered steps, dependencies, boundaries, and checklists here. A Plan is not + evidence that the work happened. +- **`progress.md` answers "What is actually true now?"** Keep current reality, + completed and open work, blockers, and the exact restart point here. Record + meaningful state changes, not a diary of every action or command. +- **`findings.md` answers "What did we learn that should survive?"** Keep + conclusions, decisions and reasons, useful evidence, source notes, changed + assumptions, and risks here. Do not use Findings as another to-do list. + +The root has all four documents. A branch normally has Plan, Progress, and +Findings; its identity and place in the whole live in root `PROJECT.md`. A +parent branch may also contain child branches when a local area needs its own +map. + +Use existing artifacts in their natural locations. A writing branch should +point to its draft, a research branch to evidence, and a note branch to its +source material. Do not copy whole artifacts into `.TreeWork/` merely to make +the state directory look complete. + +## Minimal Document Shape + +Use these headings as a starting point, not as a rigid schema. Add or remove +sections when the domain genuinely needs a different shape. + +Root `PROJECT.md`: + +```md +# Project + +## Purpose + +## Durable Direction + +## Tree +- `` - what this branch owns. + - `` - what this child owns. + +## Global Constraints +``` + +Root or branch `task_plan.md`: + +```md +# Plan + +## Outcome + +## Steps +- [ ] A meaningful work item. + +## Dependencies And Boundaries +``` + +Root or branch `progress.md`. Keep the `Current branch` line at the root and +omit it inside a branch: + +```md +# Progress + +Current branch: `` + +## Current Reality + +## Completed + +## Open Or Blocked + +## Resume From +``` + +Root or branch `findings.md`: + +```md +# Findings + +## Decisions And Reasons + +## Learned + +## Risks And Unknowns + +## References +``` + +Prefer numbered lists for order and reasoning, checklists for work that can be +completed, and bullets for facts. Mark an item complete only when the relevant +outcome exists, not merely because the Agent touched it. + +## Starting Or Adopting Work + +1. Inspect the user's request, existing artifacts, and existing organization + before creating TreeWork files. +2. Create `.TreeWork/` only when the work is long-running, has multiple scopes, + is likely to be interrupted or handed off, or is already becoming hard to + hold in one context. +3. Write root `PROJECT.md`, Plan, Progress, and Findings from what is currently + known. Do not fabricate certainty to fill headings. +4. Create only the first useful branches. It is valid to work at the root when + the work has one coherent scope. +5. Choose branch boundaries that future Agents can recognize without guessing. + Prefer an existing branch whenever it can own the work coherently. + +Create a branch when the scope has its own outcome, materials, continuation +state, or likely future follow-up. Split a branch when it has become too broad +to understand or resume locally. Do not create a branch for every small request, +temporary thought, or checklist item. + +## Working Along The Tree + +### Enter a branch + +1. Read root `PROJECT.md` and root `progress.md` to recover global direction. +2. Read the target branch's Plan, Progress, and Findings. +3. Inspect only the linked artifacts and ancestor context needed for this + branch. +4. Restate internally what this branch owns, what is already true, and what the + next meaningful action is. + +Do not load every branch into context. The Tree exists so the Agent can recover +the relevant path without rereading the whole project. + +### Work inside a branch + +- Keep effort inside the branch's declared scope. +- Update the Plan when intended work changes. +- Update Progress when reality materially changes or the restart point moves. +- Update Findings when a conclusion, decision, source, risk, or corrected + assumption should survive the current context. +- Update root documents immediately when a local discovery changes global + direction, another branch, or the Tree itself. + +The Agent may decide local execution details while working. It must not silently +change the user's goal, durable constraints, branch ownership, or cross-branch +direction. Surface those changes and synchronize the relevant documents. + +### Leave or switch branches + +Before moving away: + +1. Reconcile the branch Plan with what remains intended. +2. Record current reality and an exact restart point in branch Progress. +3. Preserve durable conclusions in branch Findings. +4. Update root `PROJECT.md` if the Tree or a branch meaning changed. +5. Update root Progress with the new current location; update root Plan or + Findings only with information that matters globally. +6. Return mentally to the root, then route to the next branch. + +Do not perform empty document maintenance after every minor action. Synchronize +when meaning, reality, direction, ownership, or the continuation point changes, +and always before leaving a branch or ending a long session. + +### Finish or retire a branch + +Treat a branch as finished when its intended outcome is actually present and +its remaining work is either resolved or deliberately moved elsewhere. Record +the result and where it lives, then update the root Tree. If work is abandoned +or superseded, preserve the reason and any reusable Findings instead of merely +deleting the branch. + +TreeWork Manual does not require a fixed lifecycle vocabulary. Use plain states +appropriate to the domain when a status helps the root map, such as `active`, +`paused`, `done`, or `dropped`; do not create lifecycle ceremony that does not +improve recovery. + +## Recovery And Handoff + +To continue after interruption, compaction, or Agent handoff: + +1. Read root `PROJECT.md`. +2. Read root `progress.md` and identify the current branch. +3. Follow the Tree path to that branch. +4. Read its Plan, Progress, and Findings. +5. Inspect the linked working artifacts to confirm the recorded reality. +6. Continue from `Resume From`, correcting the documents first if they have + drifted. + +This is state recovery, not historical retrieval. The goal is not to remember +every past action. The goal is to recover the accepted structure, current +reality, durable knowledge, and next viable movement. + +## Boundaries + +- Do not require CLI commands, hooks, Git branches, Git worktrees, transactions, + schemas, fixed stages, verification machinery, or a visual Project Map. +- Do not force software-development concepts such as Requirements or Specs onto + writing, notes, research, or creative work. Add domain documents only when + they genuinely help that branch. +- Do not duplicate information across root and branch documents. Promote only + information whose effect crosses branch boundaries. +- Do not let document upkeep become the work. Keep every file concise enough to + recover direction quickly. +- If `.TreeWork/state/`, `.TreeWork/events.jsonl`, or `tree.yaml` indicates a + full runtime-managed TreeWork project, do not edit machine-owned state or mix + manual conventions into it. Use the full TreeWork workflow unless the user + explicitly requests a migration. From 373187c15a312aa8c76c322cc7b4beb6807218c7 Mon Sep 17 00:00:00 2001 From: TreeWork Development Date: Wed, 12 Aug 2026 22:18:38 +0800 Subject: [PATCH 2/8] Refine Manual skill activation and introduction --- skills/treework-manual/SKILL.md | 31 +++++++++++++++++++++---------- 1 file changed, 21 insertions(+), 10 deletions(-) diff --git a/skills/treework-manual/SKILL.md b/skills/treework-manual/SKILL.md index 68bc794..4da5056 100644 --- a/skills/treework-manual/SKILL.md +++ b/skills/treework-manual/SKILL.md @@ -1,16 +1,16 @@ --- name: treework-manual -description: Use TreeWork Manual to keep long-running, multi-part work oriented through a Markdown project tree. Trigger for writing, research, note systems, planning, creative work, operations, or other evolving work where an Agent must preserve global direction, local progress, discoveries, and an exact restart point across interruptions or handoffs without relying on TreeWork CLI, Git worktrees, fixed development stages, or Project Map. +description: Use TreeWork Manual when long-running work has multiple related branches and an Agent needs to preserve where it is, what each branch owns, what is planned, what is actually true, and what has been learned across interruptions or handoffs using Markdown only. Trigger when requests jump between scopes, work must continue across sessions or Agents, plans and reality may drift, or the user asks for TreeWork without the full CLI/runtime system. Do not use for short single-scope tasks or projects already managed by the full TreeWork runtime. --- # TreeWork Manual -TreeWork Manual is a way of working, not a command system. Treat the work as a -tree of owned scopes instead of a flat task list or a conversation the Agent is -expected to remember. The root supplies the global map. Each branch owns one -coherent line of work. Move through that tree deliberately so another Agent, or -the same Agent after context loss, can recover the work from files rather than -reconstructing it from fragments. +TreeWork Manual gives an Agent a sense of place in long-running work. Instead +of treating every new request as the next item in a flat queue, first locate it +in the project Tree. The root shows how the whole work is organized. Each +branch is a local worksite with a clear responsibility. The Agent works inside +one branch, leaves its reality recoverable, returns to the root, and then moves +to the next branch. ```text Start at the root @@ -21,9 +21,20 @@ Start at the root -> choose the next branch ``` -A branch is a work scope, not necessarily a Git branch. Depending on the work, -branches may be chapters, themes, research questions, note collections, -deliverables, phases, modules, clients, or any other useful decomposition. +The Tree provides direction; the documents provide continuity: + +```text +PROJECT shows the global map. +Plan points toward intended work. +Progress records present reality. +Findings preserve what the work has taught us. +``` + +This is a working mental model, not a fixed workflow. A branch is simply a +coherent work scope, not necessarily a Git branch. The Tree may follow chapters, +themes, research questions, note collections, deliverables, phases, modules, +clients, or another structure that fits the actual work. It may begin shallow +and grow as understanding improves. ## Core Mental Model From dc761ae89d4e25c3b5d3a0a3e5c686527d06cdd8 Mon Sep 17 00:00:00 2001 From: TreeWork Development Date: Wed, 12 Aug 2026 22:25:37 +0800 Subject: [PATCH 3/8] Position TreeWork Manual as an independent edition --- README.md | 57 +++++++++++++++++---------------- README.zh-CN.md | 48 ++++++++++++++------------- RELEASE-NOTES.md | 8 ++--- skills/treework-manual/SKILL.md | 49 ++++++++++++++++------------ 4 files changed, 88 insertions(+), 74 deletions(-) diff --git a/README.md b/README.md index fc1459d..52330dc 100644 --- a/README.md +++ b/README.md @@ -10,36 +10,40 @@ # TreeWork -TreeWork is a **tree-guided development system for coding agents**. It ships as -a Codex plugin and a focused Pi host adapter. TreeWork helps agents organize -complex projects as branches, prepare the important design before coding, and -move through long-running work without losing direction. - -Code inspection shows what exists and retrieval memory recalls fragments, but -neither reliably tells an Agent what the project has accepted, where work -stands, or why it stopped. TreeWork therefore keeps the accepted project -structure, branch state, Specs, progress, findings, and verification outside -the model context so work can resume without reconstructing the project from -scratch. +TreeWork is a **tree-guided working model for Agents**. It externalizes evolving +work as a persistent Tree, gives every line of effort a branch, and teaches an +Agent to move from the root into one branch and back instead of chasing requests +as a flat queue. Plans, progress, and findings keep each location recoverable +across interruptions, context resets, and handoffs. + +This repository provides two independently installable editions. They share the +same root-to-branch mental model, but each defines its own state and operating +contract. -## Choose The Right Form +## TreeWork Editions -- **Full TreeWork** is the coding-agent system documented below. It adds +- **TreeWork for Coding Agents** is a runtime-backed development system. It adds Alignment, Specs, declarative Tree transactions, isolated Git worktrees, protected completion, Recall, and Project Map through the Codex plugin or Pi adapter. - **[TreeWork Manual](skills/treework-manual/SKILL.md)** is a standalone, single-file Agent Skill for writing, research, notes, planning, creative work, - and other long-running tasks. It keeps the original TreeWork mental model and - Markdown state documents without requiring a CLI, fixed stages, Git, hooks, - or Project Map. + operations, and other evolving work. The Agent maintains the Tree and its + project state directly in Markdown. + +Choose an edition from the user's needs and the actual work rather than treating +one as a fallback for the other. Do not combine both state models inside one +project without an explicit migration. + +## Installation + +### TreeWork Manual -Use the full system when coding work needs deterministic state and isolation. -Use the Manual Skill when a capable Agent only needs a durable way to locate -itself, work inside one branch, checkpoint reality, and move through a project -Tree. +Install or load [`skills/treework-manual`](skills/treework-manual) as a normal +Agent Skill. The directory is self-contained and consists of one `SKILL.md`; +it does not install the Coding Agent runtime. -## First Install +### TreeWork For Coding Agents TreeWork currently targets Codex and Pi on macOS and Linux. Native Windows support has not been release-tested. @@ -47,7 +51,7 @@ support has not been release-tested. Runtime prerequisites: Git, Bash, Python 3, Rust, and Cargo. The Project Map frontend is bundled; Node.js is needed only for frontend development. -### Pi +#### Pi Install the focused Pi package directly from this repository: @@ -63,7 +67,7 @@ and stop-check guardrails, and provides explicit `/treework-enter` and sessions. See [TreeWork for Pi](adapters/pi/README.md) for the complete install, use, verification, and rollback contract. -### Codex guided install +#### Codex guided install Give the following prompt to a Codex Agent with terminal access: @@ -103,7 +107,7 @@ inside the current project until I explicitly approve it. new one. Leave project initialization to the new Codex task after I choose. ``` -### Codex manual install +#### Codex manual install ```bash codex plugin marketplace add https://github.com/Johnny-xuan/TreeWork @@ -256,9 +260,8 @@ The Pi package manifest and focused extension live under MCP server. TreeWork stores project state under `.TreeWork/`; neither host adapter creates a second source of truth. -The standalone [`skills/treework-manual`](skills/treework-manual) directory -contains only the Manual Skill. Agent Skills-compatible hosts can install or -load that directory directly without the coding runtime. +The independently installable [`skills/treework-manual`](skills/treework-manual) +edition contains one self-contained Agent Skill. ## Repository Layout diff --git a/README.zh-CN.md b/README.zh-CN.md index ba92de2..4e93806 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -10,30 +10,35 @@ # TreeWork -TreeWork 是一套面向 Coding Agent 的**树引导开发系统**，同时提供 Codex 插件 -和聚焦的 Pi host adapter。它帮助 Agent 把复杂项目组织成一棵 branch 树，在 -编码前完成重要设计，并在长期开发中沿着树移动而不失去方向。 +TreeWork 是一种面向 Agent 的**树引导工作模型**。它把持续演化的工作外化成一棵 +持久的 Tree，让每条工作线归属一个 branch，并让 Agent 从根进入 branch、完成 +局部工作后返回根，而不是把不断到来的请求当成一条扁平队列。Plan、Progress 和 +Findings 让每个位置在中断、上下文重置或 Agent 交接后仍然可以恢复。 -代码检查能够看到已经实现了什么，检索型记忆能够找回历史片段，但两者都不能 -稳定回答项目已经接受了什么、工作进行到哪里，以及上一个 Agent 为什么停下。 -TreeWork 将已接受的项目结构、branch 状态、Spec、进度、结论和验证记录保存在 -模型上下文之外，让长期任务不必每次从头重建项目就能继续。 +本仓库提供两个可以独立安装的版本。它们共享从根到 branch 的工作心智模型， +但各自拥有独立的状态模型和运行契约。 -## 选择合适的形态 +## TreeWork 版本 -- **完整 TreeWork** 是下文介绍的 Coding Agent 系统。它通过 Codex 插件或 Pi +- **TreeWork for Coding Agents** 是带运行时的开发系统。它通过 Codex 插件或 Pi adapter 提供 Alignment、Spec、声明式 Tree transaction、隔离 Git worktree、 completion 保护、Recall 和 Project Map。 - **[TreeWork Manual](skills/treework-manual/SKILL.md)** 是一份独立、单文件的 - Agent Skill，适用于写作、研究、笔记、规划、创作及其他长期任务。它保留原始 - TreeWork 的工作心智模型和 Markdown 状态文档，不依赖 CLI、固定阶段、Git、 - Hooks 或 Project Map。 + Agent Skill，适用于写作、研究、笔记、规划、创作、运营及其他持续演化的工作。 + Agent 直接在 Markdown 中维护 Tree 与项目状态。 -Coding 工作需要确定性状态与隔离时使用完整系统。一个有能力的 Agent 只需要知道 -自己在哪里、在一条 branch 内工作、留下可恢复现实并沿项目 Tree 移动时，使用 -Manual Skill。 +根据用户需要和实际工作选择版本，不要把其中一个视为另一个的 fallback。同一个 +项目不能在没有显式迁移的情况下混用两套状态模型。 -## 首次安装 +## 安装 + +### TreeWork Manual + +将 [`skills/treework-manual`](skills/treework-manual) 作为普通 Agent Skill 安装 +或加载即可。该目录是独立完整的，只包含一份 `SKILL.md`，不会安装 Coding Agent +运行时。 + +### TreeWork for Coding Agents TreeWork 当前面向 macOS 和 Linux 上的 Codex 与 Pi。原生 Windows 支持尚未 经过发布测试。 @@ -41,7 +46,7 @@ TreeWork 当前面向 macOS 和 Linux 上的 Codex 与 Pi。原生 Windows 支 运行依赖包括 Git、Bash、Python 3、Rust 和 Cargo。Project Map 前端已经打包； 只有开发前端时才需要 Node.js。 -### Pi +#### Pi 直接从本仓库安装 Pi package： @@ -56,7 +61,7 @@ pi install git:github.com/Johnny-xuan/TreeWork worktree。完整安装、使用、验证与回滚方式见 [TreeWork for Pi](adapters/pi/README.md)。 -### Codex 引导安装 +#### Codex 引导安装 把下面这段 prompt 直接交给一个能够使用终端的 Codex Agent： @@ -90,7 +95,7 @@ TreeWork。 后，再进行项目初始化。 ``` -### Codex 手动安装 +#### Codex 手动安装 ```bash codex plugin marketplace add https://github.com/Johnny-xuan/TreeWork @@ -232,9 +237,8 @@ Pi package manifest 和聚焦的扩展位于 [`adapters/pi`](adapters/pi)，并 同一份 Skill、运行时和 MCP 服务。TreeWork 将项目状态保存在 `.TreeWork/` 下； 两个 host adapter 都不会创建第二事实源。 -独立的 [`skills/treework-manual`](skills/treework-manual) 目录只包含 Manual -Skill。兼容 Agent Skills 的 host 可以直接安装或加载这个目录，不需要 coding -runtime。 +可独立安装的 [`skills/treework-manual`](skills/treework-manual) 版本只包含一份 +自包含的 Agent Skill。 ## 仓库结构 diff --git a/RELEASE-NOTES.md b/RELEASE-NOTES.md index 63b0dbd..65ff6a2 100644 --- a/RELEASE-NOTES.md +++ b/RELEASE-NOTES.md @@ -2,10 +2,10 @@ ## Unreleased -- Adds `treework-manual`, a standalone single-file Agent Skill that preserves - TreeWork's root-to-branch mental model and Markdown project state for writing, - research, notes, planning, and other non-coding work without the CLI or - Project Map. +- Adds `treework-manual`, an independently installable single-file TreeWork + edition for writing, research, notes, planning, creative work, operations, + and other evolving projects. Agents maintain its Tree and project state + directly in Markdown. - Adds a focused Pi package that directly reuses TreeWork's Skill, Rust runtime, and read-only MCP server without introducing a second project-state model. - Keeps Pi's always-active Agent-tool surface to one deferred loader for Recall, diff --git a/skills/treework-manual/SKILL.md b/skills/treework-manual/SKILL.md index 4da5056..60a34c4 100644 --- a/skills/treework-manual/SKILL.md +++ b/skills/treework-manual/SKILL.md @@ -1,16 +1,21 @@ --- name: treework-manual -description: Use TreeWork Manual when long-running work has multiple related branches and an Agent needs to preserve where it is, what each branch owns, what is planned, what is actually true, and what has been learned across interruptions or handoffs using Markdown only. Trigger when requests jump between scopes, work must continue across sessions or Agents, plans and reality may drift, or the user asks for TreeWork without the full CLI/runtime system. Do not use for short single-scope tasks or projects already managed by the full TreeWork runtime. +description: Use TreeWork Manual when the user asks to work with TreeWork, or when the Agent judges from the situation that organizing work as a persistent Markdown Tree would improve direction, continuity, recovery, or handoff. Adapt the Tree's depth and document detail to the user's needs and domain instead of applying a fixed task-size threshold. Suitable for writing, research, notes, planning, creative work, operations, and other evolving work; the Agent maintains its state directly in Markdown. --- # TreeWork Manual -TreeWork Manual gives an Agent a sense of place in long-running work. Instead -of treating every new request as the next item in a flat queue, first locate it -in the project Tree. The root shows how the whole work is organized. Each -branch is a local worksite with a clear responsibility. The Agent works inside -one branch, leaves its reality recoverable, returns to the root, and then moves -to the next branch. +TreeWork gives an Agent a durable sense of place in ongoing work. It externalizes +the work as a Tree: the root holds the whole project, each branch owns one +coherent line of effort, and documents at the root and branches preserve intent, +reality, and durable knowledge. Direction no longer depends on the current +conversation remaining intact. + +The Agent's unit of movement is not the next message; it is the current branch. +A new request is first located in the Tree. The Agent then works from the root +into the branch that owns the work, leaves that branch recoverable, returns to +the root, and chooses the next branch. Requests may arrive in any order, but the +work still moves through the Tree. ```text Start at the root @@ -27,14 +32,15 @@ The Tree provides direction; the documents provide continuity: PROJECT shows the global map. Plan points toward intended work. Progress records present reality. -Findings preserve what the work has taught us. +Findings preserve what the work has taught the Agent. ``` -This is a working mental model, not a fixed workflow. A branch is simply a -coherent work scope, not necessarily a Git branch. The Tree may follow chapters, -themes, research questions, note collections, deliverables, phases, modules, -clients, or another structure that fits the actual work. It may begin shallow -and grow as understanding improves. +TreeWork is a working mental model rather than a prescribed sequence. A branch +may be a chapter, theme, research question, note collection, deliverable, phase, +module, client, or another coherent scope that fits the project. The Tree may +begin shallow and grow as understanding improves. The Agent maintains this +topology and its state directly in Markdown so that people and other Agents can +inspect, correct, and continue the same work. ## Core Mental Model @@ -182,10 +188,12 @@ outcome exists, not merely because the Agent touched it. 1. Inspect the user's request, existing artifacts, and existing organization before creating TreeWork files. -2. Create `.TreeWork/` only when the work is long-running, has multiple scopes, - is likely to be interrupted or handed off, or is already becoming hard to - hold in one context. -3. Write root `PROJECT.md`, Plan, Progress, and Findings from what is currently +2. Decide from the user's request and the actual situation whether an explicit + Tree will make the work easier to locate, continue, inspect, or hand off. + An explicit user request is sufficient; otherwise use judgment rather than a + fixed size, duration, or branch-count threshold. +3. When TreeWork is appropriate, create `.TreeWork/` and write root `PROJECT.md`, + Plan, Progress, and Findings from what is currently known. Do not fabricate certainty to fill headings. 4. Create only the first useful branches. It is valid to work at the root when the work has one coherent scope. @@ -281,7 +289,6 @@ reality, durable knowledge, and next viable movement. information whose effect crosses branch boundaries. - Do not let document upkeep become the work. Keep every file concise enough to recover direction quickly. -- If `.TreeWork/state/`, `.TreeWork/events.jsonl`, or `tree.yaml` indicates a - full runtime-managed TreeWork project, do not edit machine-owned state or mix - manual conventions into it. Use the full TreeWork workflow unless the user - explicitly requests a migration. +- If another TreeWork edition already manages the project, do not silently mix + its state model with this one. Follow the user's explicit choice of edition, + or agree on a migration before changing the existing TreeWork state. From e9cb39262fd9f84fef073a6620d4c86e6bdaeffb Mon Sep 17 00:00:00 2001 From: TreeWork Development Date: Thu, 13 Aug 2026 11:09:08 +0800 Subject: [PATCH 4/8] Make Manual skill boundaries self-contained --- skills/treework-manual/SKILL.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/skills/treework-manual/SKILL.md b/skills/treework-manual/SKILL.md index 60a34c4..1abc3e5 100644 --- a/skills/treework-manual/SKILL.md +++ b/skills/treework-manual/SKILL.md @@ -1,6 +1,6 @@ --- name: treework-manual -description: Use TreeWork Manual when the user asks to work with TreeWork, or when the Agent judges from the situation that organizing work as a persistent Markdown Tree would improve direction, continuity, recovery, or handoff. Adapt the Tree's depth and document detail to the user's needs and domain instead of applying a fixed task-size threshold. Suitable for writing, research, notes, planning, creative work, operations, and other evolving work; the Agent maintains its state directly in Markdown. +description: Use TreeWork Manual when the user asks for it, or when the Agent judges that organizing ongoing, multi-part work as a persistent Markdown Tree would improve direction, continuity, recovery, or handoff. Adapt the Tree's depth and document detail to the user's needs, domain, and situation rather than a fixed threshold. --- # TreeWork Manual @@ -280,8 +280,6 @@ reality, durable knowledge, and next viable movement. ## Boundaries -- Do not require CLI commands, hooks, Git branches, Git worktrees, transactions, - schemas, fixed stages, verification machinery, or a visual Project Map. - Do not force software-development concepts such as Requirements or Specs onto writing, notes, research, or creative work. Add domain documents only when they genuinely help that branch. @@ -289,6 +287,8 @@ reality, durable knowledge, and next viable movement. information whose effect crosses branch boundaries. - Do not let document upkeep become the work. Keep every file concise enough to recover direction quickly. -- If another TreeWork edition already manages the project, do not silently mix - its state model with this one. Follow the user's explicit choice of edition, - or agree on a migration before changing the existing TreeWork state. +- Do not invent extra process, files, or bookkeeping merely to make the Tree + look complete. Add structure only when it improves orientation or recovery. +- Treat an existing `.TreeWork/` as user data. If its structure differs from + the one described here, inspect and preserve it, then ask before adopting, + reorganizing, or replacing it. From 0d0e217cf18ab5e30ebedd4544b82dac29205a7c Mon Sep 17 00:00:00 2001 From: TreeWork Development Date: Thu, 13 Aug 2026 11:51:32 +0800 Subject: [PATCH 5/8] Remove cross-edition terminology from Manual boundaries --- skills/treework-manual/SKILL.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/skills/treework-manual/SKILL.md b/skills/treework-manual/SKILL.md index 1abc3e5..2452aec 100644 --- a/skills/treework-manual/SKILL.md +++ b/skills/treework-manual/SKILL.md @@ -280,9 +280,6 @@ reality, durable knowledge, and next viable movement. ## Boundaries -- Do not force software-development concepts such as Requirements or Specs onto - writing, notes, research, or creative work. Add domain documents only when - they genuinely help that branch. - Do not duplicate information across root and branch documents. Promote only information whose effect crosses branch boundaries. - Do not let document upkeep become the work. Keep every file concise enough to From 28f7ced586d7033de0d256ea9cac78e5d9002927 Mon Sep 17 00:00:00 2001 From: TreeWork Development Date: Thu, 13 Aug 2026 11:52:41 +0800 Subject: [PATCH 6/8] Clarify the purpose of Manual state documents --- skills/treework-manual/SKILL.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/skills/treework-manual/SKILL.md b/skills/treework-manual/SKILL.md index 2452aec..91a962c 100644 --- a/skills/treework-manual/SKILL.md +++ b/skills/treework-manual/SKILL.md @@ -282,8 +282,9 @@ reality, durable knowledge, and next viable movement. - Do not duplicate information across root and branch documents. Promote only information whose effect crosses branch boundaries. -- Do not let document upkeep become the work. Keep every file concise enough to - recover direction quickly. +- Do not maintain documents as ceremony. Their purpose is to preserve the + work's current state, the Agent's project understanding, and the context + needed for later work to recover direction and continue correctly. - Do not invent extra process, files, or bookkeeping merely to make the Tree look complete. Add structure only when it improves orientation or recovery. - Treat an existing `.TreeWork/` as user data. If its structure differs from From eea1a5dbec6f3751114875fe49c8fb5c4d3101a2 Mon Sep 17 00:00:00 2001 From: TreeWork Development Date: Thu, 13 Aug 2026 12:39:52 +0800 Subject: [PATCH 7/8] Prepare dual-edition TreeWork v0.1.8 release --- README.md | 14 ++- README.zh-CN.md | 13 ++- RELEASE-NOTES.md | 2 +- docs/releasing.md | 6 +- plugins/treework/.codex-plugin/plugin.json | 2 +- plugins/treework/Cargo.lock | 2 +- .../treework/crates/treework-cli/Cargo.toml | 2 +- project-map-ui/package-lock.json | 4 +- project-map-ui/package.json | 2 +- scripts/package_release_assets.py | 102 +++++++++++++++--- 10 files changed, 124 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 7f243f0..bf35e75 100644 --- a/README.md +++ b/README.md @@ -53,6 +53,18 @@ The same independently installable source is available at TreeWork for Coding Agents currently targets Codex on macOS and Linux. Native Windows support has not been release-tested. +The matching GitHub Release also provides +`TreeWork-Coding-Agents-vX.Y.Z.zip`. After extracting it, the +`treework-coding-agents/` directory is a self-contained local Codex marketplace: + +```bash +codex plugin marketplace add /path/to/treework-coding-agents +codex plugin add treework@treework +``` + +The Git marketplace installation below is recommended when normal GitHub access +is available because Codex can update it directly from the repository. + Runtime prerequisites: Git, Bash, Python 3, Rust, and Cargo. The Project Map frontend is bundled; Node.js is needed only for frontend development. @@ -302,7 +314,7 @@ make validate ## Status -`v0.1.7` is the current Coding Agents edition version. Alignment, declarative Tree +`v0.1.8` is the current Coding Agents edition version. Alignment, declarative Tree construction, hierarchy-aligned branch documents, protected branch traversal, Recall, Project Map, and Replay form a usable end-to-end loop. TreeWork Manual is released independently from the same repository and tag. Project Map diff --git a/README.zh-CN.md b/README.zh-CN.md index bdab2b7..af6607f 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -47,6 +47,17 @@ host 的 Skills 目录。对于 Codex，安装到 `$CODEX_HOME/skills/`（通常 TreeWork for Coding Agents 当前面向 macOS 和 Linux 上的 Codex。原生 Windows 支持尚未经过发布测试。 +对应的 GitHub Release 同时提供 `TreeWork-Coding-Agents-vX.Y.Z.zip`。解压后， +`treework-coding-agents/` 目录就是一个自包含的本地 Codex marketplace： + +```bash +codex plugin marketplace add /path/to/treework-coding-agents +codex plugin add treework@treework +``` + +如果能够正常访问 GitHub，更推荐使用下面的 Git marketplace 安装方式，因为 Codex +可以直接从仓库更新。 + 运行依赖包括 Git、Bash、Python 3、Rust 和 Cargo。Project Map 前端已经打包； 只有开发前端时才需要 Node.js。 @@ -274,7 +285,7 @@ make validate ## 当前状态 -`v0.1.7` 是当前 Coding Agents 版本。Alignment、声明式 Tree 构建、与 Tree 层级一致的 +`v0.1.8` 是当前 Coding Agents 版本。Alignment、声明式 Tree 构建、与 Tree 层级一致的 branch 文档、受保护的 branch 移动、Recall、Project Map 和 Replay 已经形成 可用的端到端闭环。TreeWork Manual 从同一仓库和 tag 独立发布。Project Map 的 交互设计仍会持续演化。 diff --git a/RELEASE-NOTES.md b/RELEASE-NOTES.md index bb2be7b..72e4ded 100644 --- a/RELEASE-NOTES.md +++ b/RELEASE-NOTES.md @@ -1,6 +1,6 @@ # Release Notes -## Unreleased +## v0.1.8 - Two Independent Editions - Adds `treework-manual`, an independently installable single-file TreeWork edition for writing, research, notes, planning, creative work, operations, diff --git a/docs/releasing.md b/docs/releasing.md index 39dad31..b77d1b8 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -24,10 +24,10 @@ make package Packaging produces three local forms: - `dist/treework/` is the unpacked Coding Agents plugin candidate; -- `dist/releases/TreeWork-Coding-Agents-vX.Y.Z.zip` is the independently - installable Coding Agents release asset; +- `dist/releases/TreeWork-Coding-Agents-vX.Y.Z.zip` contains a self-contained + local Codex marketplace rooted at `treework-coding-agents/`; - `dist/releases/TreeWork-Manual-vX.Y.Z.zip` is the independently installable - single-file Manual release asset. + single-file Manual release asset rooted at `treework-manual/`. Both ZIP assets come from the same committed `HEAD` and share the release tag, but users install them independently. diff --git a/plugins/treework/.codex-plugin/plugin.json b/plugins/treework/.codex-plugin/plugin.json index 2fcce74..c1e8c8b 100644 --- a/plugins/treework/.codex-plugin/plugin.json +++ b/plugins/treework/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "treework", - "version": "0.1.7", + "version": "0.1.8", "description": "State-native project memory for long-running coding agents.", "author": { "name": "Zhongxuan Song", diff --git a/plugins/treework/Cargo.lock b/plugins/treework/Cargo.lock index f17f4ec..b94c8cf 100644 --- a/plugins/treework/Cargo.lock +++ b/plugins/treework/Cargo.lock @@ -975,7 +975,7 @@ dependencies = [ [[package]] name = "treework-cli" -version = "0.1.7" +version = "0.1.8" dependencies = [ "axum", "clap", diff --git a/plugins/treework/crates/treework-cli/Cargo.toml b/plugins/treework/crates/treework-cli/Cargo.toml index 8b1904a..3852b6c 100644 --- a/plugins/treework/crates/treework-cli/Cargo.toml +++ b/plugins/treework/crates/treework-cli/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "treework-cli" -version = "0.1.7" +version = "0.1.8" edition = "2021" authors = ["Zhongxuan Song "] description = "TreeWork state, transaction, and Project Map runtime" diff --git a/project-map-ui/package-lock.json b/project-map-ui/package-lock.json index cfdacd7..a4b15c9 100644 --- a/project-map-ui/package-lock.json +++ b/project-map-ui/package-lock.json @@ -1,12 +1,12 @@ { "name": "@treework/project-map-ui", - "version": "0.1.7", + "version": "0.1.8", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@treework/project-map-ui", - "version": "0.1.7", + "version": "0.1.8", "license": "MIT", "dependencies": { "@fontsource/fraunces": "5.3.0", diff --git a/project-map-ui/package.json b/project-map-ui/package.json index cf29cb8..b3bf091 100644 --- a/project-map-ui/package.json +++ b/project-map-ui/package.json @@ -1,6 +1,6 @@ { "name": "@treework/project-map-ui", - "version": "0.1.7", + "version": "0.1.8", "private": true, "type": "module", "license": "MIT", diff --git a/scripts/package_release_assets.py b/scripts/package_release_assets.py index a5d680e..922fe88 100644 --- a/scripts/package_release_assets.py +++ b/scripts/package_release_assets.py @@ -6,6 +6,7 @@ import argparse import hashlib import json +import re import shutil import stat import subprocess @@ -20,16 +21,26 @@ RELEASE_ROOT = REPOSITORY_ROOT / "dist" / "releases" EDITIONS = { "Coding-Agents": { - "source": Path("plugins/treework"), - "directory": "treework", + "sources": [ + (Path("plugins/treework"), Path("plugins/treework")), + ], + "files": [ + ( + Path(".agents/plugins/marketplace.json"), + Path(".agents/plugins/marketplace.json"), + ), + ], + "directory": "treework-coding-agents", "required": { - ".codex-plugin/plugin.json", - ".mcp.json", - "skills/treework/SKILL.md", + ".agents/plugins/marketplace.json", + "plugins/treework/.codex-plugin/plugin.json", + "plugins/treework/.mcp.json", + "plugins/treework/skills/treework/SKILL.md", }, }, "Manual": { - "source": Path("skills/treework-manual"), + "sources": [(Path("skills/treework-manual"), Path("."))], + "files": [], "directory": "treework-manual", "required": {"SKILL.md"}, }, @@ -52,10 +63,30 @@ def git_bytes(*args: str) -> bytes: return result.stdout -def source_version(commit: str) -> str: - raw = git_bytes( - "show", f"{commit}:plugins/treework/.codex-plugin/plugin.json" +def committed_file(commit: str, path: Path) -> bytes: + return git_bytes("show", f"{commit}:{path.as_posix()}") + + +def toml_package_version(raw: bytes, name: str) -> str | None: + package = raw.decode().split("[package]", 1) + if len(package) != 2: + return None + match = re.search(r'^version\s*=\s*"([^"]+)"', package[1], re.MULTILINE) + return match.group(1) if match else None + + +def lock_package_version(raw: bytes, package_name: str) -> str | None: + pattern = re.compile( + rf'\[\[package\]\]\s+name\s*=\s*"{re.escape(package_name)}"\s+' + r'version\s*=\s*"([^"]+)"', + re.MULTILINE, ) + matches = pattern.findall(raw.decode()) + return matches[0] if len(matches) == 1 else None + + +def source_version(commit: str) -> str: + raw = committed_file(commit, Path("plugins/treework/.codex-plugin/plugin.json")) try: manifest = json.loads(raw) version = manifest["version"] @@ -63,6 +94,30 @@ def source_version(commit: str) -> str: raise SystemExit("committed plugin manifest has no valid version") from error if not isinstance(version, str) or not version: raise SystemExit("committed plugin version must be a non-empty string") + + versions = { + "plugin manifest": version, + "treework-cli": toml_package_version( + committed_file( + commit, Path("plugins/treework/crates/treework-cli/Cargo.toml") + ), + "treework-cli", + ), + "Cargo.lock treework-cli": lock_package_version( + committed_file(commit, Path("plugins/treework/Cargo.lock")), + "treework-cli", + ), + "Project Map": json.loads( + committed_file(commit, Path("project-map-ui/package.json")) + ).get("version"), + } + mismatched = { + name: value for name, value in versions.items() if value != version + } + if mismatched: + raise SystemExit( + f"committed release versions do not match {version}: {mismatched}" + ) return version @@ -147,6 +202,23 @@ def validate_edition(name: str, root: Path, required: set[str]) -> None: ) +def build_candidate( + commit: str, + candidate: Path, + sources: list[tuple[Path, Path]], + files: list[tuple[Path, Path]], +) -> None: + candidate.mkdir() + for source, relative_destination in sources: + destination = candidate / relative_destination + destination.mkdir(parents=True, exist_ok=True) + extract_commit_path(commit, source, destination) + for source, relative_destination in files: + destination = candidate / relative_destination + destination.parent.mkdir(parents=True, exist_ok=True) + destination.write_bytes(committed_file(commit, source)) + + def zip_info(name: str, mode: int) -> zipfile.ZipInfo: info = zipfile.ZipInfo(name, date_time=(1980, 1, 1, 0, 0, 0)) info.create_system = 3 @@ -211,7 +283,7 @@ def main() -> None: raise SystemExit("run package_release_assets.py from the TreeWork repository") commit = git_bytes("rev-parse", "HEAD").decode().strip() version = source_version(commit) - license_bytes = git_bytes("show", f"{commit}:LICENSE") + license_bytes = committed_file(commit, Path("LICENSE")) expected_tag = f"v{version}" if args.tag and args.tag != expected_tag: raise SystemExit( @@ -230,11 +302,15 @@ def main() -> None: for name, config in EDITIONS.items(): directory = str(config["directory"]) candidate = temporary_root / directory - candidate.mkdir() - extract_commit_path(commit, config["source"], candidate) + build_candidate( + commit, + candidate, + config["sources"], + config["files"], + ) validate_edition(name, candidate, config["required"]) archive_path = RELEASE_ROOT / f"TreeWork-{name}-v{version}.zip" - extras = {"LICENSE": license_bytes} if name == "Manual" else None + extras = {"LICENSE": license_bytes} write_reproducible_zip(candidate, archive_path, extras) verify_zip(archive_path, directory, candidate, extras) built.append(archive_path) From 54f7a9e4ba6ff4266ac20fd4b992739c8857f958 Mon Sep 17 00:00:00 2001 From: TreeWork Development Date: Thu, 13 Aug 2026 12:45:20 +0800 Subject: [PATCH 8/8] Clarify atomic dual-edition release flow --- docs/releasing.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/releasing.md b/docs/releasing.md index b77d1b8..65617e1 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -58,7 +58,7 @@ git push origin main git push origin vX.Y.Z ``` -Create a GitHub release from the matching section of `RELEASE-NOTES.md`. Do not -move an existing release tag. Do not publish from a dirty worktree or from -uncommitted `dist/` contents. The tag workflow validates that `vX.Y.Z` matches -the committed plugin version and uploads both edition ZIPs to the same release. +The tag workflow validates that `vX.Y.Z` matches the committed plugin version, +creates one GitHub Release, and uploads both edition ZIPs together. Do not move +an existing release tag. Do not publish from a dirty worktree or from +uncommitted `dist/` contents.