Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
153 lines (111 loc) · 5.45 KB

CONTRIBUTING.md

File metadata and controls

153 lines (111 loc) · 5.45 KB
Raw

Contributing to TreeWork

TreeWork starts from a broader question: how can an agent keep its direction, location, and development trajectory during long-running work?

The repository contains one answer to that question, not the final answer. You do not need to accept the current workflow, use the same files, or write code before contributing.

Start with a Comment

The most useful contribution may be an Issue or a comment describing what happened in a real project:

  • Where did the agent begin to lose the project's direction?
  • Did a context reset, interruption, or handoff make the problem visible?
  • What information did the next agent need but fail to recover?
  • Did TreeWork help, add unnecessary work, or make no difference?
  • What would you try instead?

Use GitHub Issues to share a case, question an assumption, suggest a different approach, or discuss the long-horizon drift problem with other users. You do not need a finished design or implementation.

Ways to Contribute

Improve the workflow method

Try TreeWork on development, research, writing, or another long-running project. Contributions can improve the mental model, branch boundaries, recovery behavior, handoffs, document roles, or the balance between useful state and unnecessary bookkeeping.

Changes to skills/treework/SKILL.md should remain simple enough for an agent to follow and general enough to work outside one particular project.

Build your own "TreeWork"

The persistent work tree is one engineering idea, not a required product shape. You can build a different Skill, state model, visualization, runtime, or domain-specific version. It does not need to use .TreeWork/, Markdown, our branch model, or our commands.

If you publish another approach, open an Issue and link it. Comparing different ways of maintaining direction is more useful than forcing every idea into this repository.

Improve the experimental implementation

The optional Codex plugin is an experimental, runtime-backed interpretation of TreeWork. Contributions may improve the Rust tw CLI, transactions, recovery, Git worktree isolation, Recall, Project Map, Replay, interaction design, accessibility, performance, or adapters for other coding-agent hosts.

The Project Map must remain a read-only projection of accepted plugin state rather than becoming a second source of truth. Host adapters should preserve the plugin's document, transaction, lifecycle, and verification semantics.

Test the idea

Controlled evaluations and honest field reports are welcome. Useful questions include state recovery after context reset, handoff cost, development drift, quality, and operational overhead. Negative results and cases where ordinary prompting works just as well are valuable.

Documentation, examples, translations, installation instructions, packaging, and platform support are also useful contributions.

Before Opening a Code Change

  1. Search existing issues and pull requests.
  2. Reproduce the problem against the latest main.
  3. Decide whether the change belongs to the standalone Skill, experimental plugin guidance, runtime, Project Map, or repository tooling.
  4. Open an issue before introducing a new command, lifecycle state, persisted field, or public document type.

For workflow and research discussions, start with the Issue itself. The steps above are for code and public-contract changes, not a gate for participating in the conversation.

The experimental plugin keeps its Agent-facing surface small. A new CLI command must represent a durable project-state transition or a necessary recovery boundary; convenience alone is not enough.

Development Setup

Standalone Skill edits require no Rust or frontend build. Read the Skill, check its metadata, and test the changed guidance on a realistic task. See the development guide for validation commands.

For runtime or frontend development, required tools are:

  • Rust stable and Cargo
  • Python 3.11 or newer
  • Node.js 22 or newer
  • Git and Bash

Install frontend dependencies:

cd project-map-ui
npm ci
cd ..

Install the validator dependency in an isolated Python environment:

python3 -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements-dev.txt

Run the main checks:

make test
make validate

See docs/development.md for the full matrix.

Documentation Boundaries

  • skills/treework/SKILL.md is the complete standalone Skill; keep it independent of the plugin's CLI and state schema.
  • plugins/treework/skills/.../references/ is for Agents using the experimental plugin.
  • docs/product/ defines user-facing behavior.
  • docs/architecture/ defines implementation contracts for maintainers.
  • Historical design notes are intentionally excluded from the public repository; durable decisions belong in the product or architecture docs.

Do not solve a maintainer documentation need by expanding the installed Skill.

Pull Requests

Keep each pull request focused. Include:

  • the user-visible or maintainer problem;
  • the chosen behavior and important trade-offs;
  • tests or evidence that cover the change;
  • documentation updates when a public contract changes.

Generated Project Map assets under plugins/treework/assets/graph-panel/ must match the project-map-ui/ source. Do not hand-edit the generated bundle.

By contributing, you agree that your contribution is licensed under the MIT License.