waterrise#

Plans for a project, kept in the project. Every plan, decision, review and note is a typed TOML file in the repository's planning/ folder, checked like code, and moved through draft/, todo/, in-progress/ and done/ as the work goes. One local service per user turns them into pages, and the pages are where questions get answered and risky steps approved.

Why it exists#

It was written for working with a coding agent. An agent that asks in a chat asks once, and the answer is gone when the session is. With waterrise the agent writes its questions into the plan, each with the facts, the options and a recommendation, and you answer them in the page whenever you get to it. The answers are kept beside the plan, in a file only the service writes.

A step that is hard to undo — a deploy, a release, a push, anything that spends money — carries a gate. Before it acts, the agent runs waterrise gate, which passes only if you approved that step in the page and the step has not changed since. Change the step, and the page asks again.

What it does#

  • waterrise check validates the whole folder: unknown keys, missing fields, a step done before what it needs, a done gate nobody approved.
  • waterrise status says what waits on you and what waits on the agent.
  • waterrise serve starts or joins the service and prints the page's address. The pages update live, show what changed since you last answered, and let you drag plans into the order you want them done.
  • waterrise guide prints the rules for agents and people alike.

Run it#

Python 3.11 or newer and nothing else, on Linux, macOS or Windows:

git clone https://github.com/vaelum/waterrise.git
cd waterrise
python -m waterrise install          # a venv of its own, `waterrise` on PATH
python -m waterrise install --boot   # and the service starting at login

Then, in a repository:

waterrise init         # make planning/ a typed folder
waterrise new plan x   # an item with a fresh id
waterrise serve        # the pages

Read more#

  • Documentation: installing it, the planning folder, the pages, working with an agent, and the commands.
  • Source: the repository on GitHub, with its README and releases.