Skip to content

experimental-plugin.md

Latest commit

 

History

History
86 lines (65 loc) · 3.76 KB

experimental-plugin.md

File metadata and controls

86 lines (65 loc) · 3.76 KB
Raw

Experimental Codex Plugin

Back to TreeWork · 中文

The main TreeWork Skill is a single Markdown file. This optional plugin explores the same tree-guided working model with a runtime that validates project-state changes, manages isolated workspaces, and exposes visual projections.

Use the standalone Skill to work directly in Markdown. Choose the plugin when you want its enforced state contract and are prepared to install the runtime. They are independent installations; do not load both into the same project or reuse one edition's .TreeWork/ as the other's without a reviewed migration.

What It Adds

  • Alignment and Specs: investigate intent and agree on Requirements and technical design before implementation.
  • Declarative Tree: author hierarchy, order, Spec references, and dependencies in .TreeWork/tree.yaml; Apply validates and publishes the accepted structure as a transaction.
  • Isolated work: tw enter prepares a branch-bound Git worktree. The agent moves its tools there, implements from Spec and Plan, verifies, records the result, and returns to the control workspace after a lifecycle transition.
  • Protected transitions: pending, in progress, paused, complete, and aborted are tracked separately from verification.
  • Recall: recover a branch's accepted state and relevant records.
  • Project Map: read-only Map, Dependency, and Replay views. After the first successful Tree Apply, the agent opens the panel in Codex's in-app browser. Replay follows accepted state transitions, not code diffs or shell history.

Project Map interaction design is still evolving. Focused improvements and real-project feedback are welcome.

Install

The plugin currently targets Codex on macOS and Linux. Native Windows support has not been release-tested. Prerequisites: Git, Bash, Python 3, Rust, and Cargo. Node.js is only needed to develop the frontend; Project Map assets are bundled.

For a first installation with the Codex CLI:

codex plugin marketplace add https://github.com/Johnny-xuan/TreeWork
codex plugin add treework@treework

For an existing installation, inspect codex plugin marketplace list --json and codex plugin list --json first rather than registering a duplicate. Start a new Codex task to load the Skill, hooks, and MCP server, then ask:

Use the TreeWork plugin to align this project, design its Specs,
build the Tree, and work branch by branch.

The first tw invocation compiles the Rust runtime. Cargo may need network access to download uncached dependencies. Installing the plugin does not itself initialize a project; agree on the target project before asking the agent to begin.

Release Archive

An alternative is TreeWork-Coding-Agents-vX.Y.Z.zip from a matching release. Extract the archive, then register its local marketplace:

codex plugin marketplace add /path/to/treework-coding-agents
codex plugin add treework@treework

The existing archive name and plugin identifier are retained for installation compatibility. The plugin is optional regardless of the archive name.

Local State and Development

The plugin stores project state under .TreeWork/ and serves Project Map on loopback. It has no telemetry; the local service rejects non-loopback browser hosts and origins. Your agent host's own data handling is separate.

Source lives in plugins/treework/. Agent-facing instructions live in its Skill; product and runtime contracts live under docs/.

Development · Release process · Project Map contract · Transaction architecture