wip is a personal, agent-friendly project-management CLI. It tracks real
work — Matters, Stages, Steps — through a verb surface (wip next,
wip plumbing start, wip plumbing finish, …), records every write as an event, and
queues tracker writes in an outbox that only a person approves and
flushes. It is built for a solo developer who works alongside coding
agents: the same verbs serve both, and wip install projects the tool
into each detected agent harness as a generated, stamped skill.
Built on the toolsmith contract
(toolsmith/v1 — the manifest declares it): a single static Go binary
that projects itself into agent harnesses as generated, stamped skills.
The Go implementation lives on main. The original bash implementation is
preserved on bash-final; existing release tags are unchanged. This branch
cutover does not activate the experimental wipd or migrate any WIP store.
Install the binary first, then optionally project it into an agent harness.
Neither binary installation nor wip version opens or migrates a WIP store.
Install the latest release to ~/.local/bin/wip — no checkout or Go toolchain
required. The installer supports Linux amd64 and macOS arm64 and requires
curl plus either sha256sum or shasum.
curl -fsSL https://github.com/procrastivity/wip/releases/latest/download/wip-install.sh -o /tmp/wip-install.sh
sh /tmp/wip-install.shPut the destination on PATH and verify which binary your shell selects:
export PATH="$HOME/.local/bin:$PATH"
hash -r
command -v wip
wip versionKeep the PATH setting in your shell's startup configuration for future sessions.
Re-run the installer to update. Installation replaces an existing wip file
or symlink with the verified binary; it never follows a development-build
symlink or overwrites its target. No separate symlink removal is needed.
This installs only wip, not the experimental wipd, and never activates a
daemon, changes stores, or installs harness skills automatically.
Once the binary is on PATH, install its generated skills separately:
wip install # project into every detected harnesswip install <harness> targets one harness; wip uninstall <harness>
removes exactly what install wrote; wip doctor reports stale or
drifted projections.
Pin a release. WIP_VERSION selects the binary's release tag. To pin both
the installer and the binary, use the same tag in the download URL and the
environment. For example, v0.3.1
publishes both:
curl -fsSL https://github.com/procrastivity/wip/releases/download/v0.3.1/wip-install.sh -o /tmp/wip-install.sh
WIP_VERSION=v0.3.1 sh /tmp/wip-install.shChoose a destination. Set WIP_INSTALL_DIR to override ~/.local/bin.
For a disposable trial without replacing your daily binary:
install_dir=$(mktemp -d)
WIP_INSTALL_DIR="$install_dir" WIP_VERSION=v0.3.1 sh /tmp/wip-install.sh
"$install_dir/wip" versionWIP_BASE_URL selects another trusted GitHub repository with the same release
asset layout. Windows and other architectures are not published by this pipeline.
Download verification. You can inspect /tmp/wip-install.sh before running
it. The installer downloads the selected binary and SHA256SUMS from the same
release and checks the binary before replacing the destination. The script and
checksum file are trusted GitHub/HTTPS inputs: the checksum detects transfer
corruption, not a compromised release or installer.
Nix alternative. Install the same release binary with Nix, then use the same optional harness step above:
nix profile install github:procrastivity/wip/stablestable names the latest release. To pin one release, use its
bin-vX.Y.Z tag, for example
nix profile install github:procrastivity/wip/bin-v0.3.1. Both hold a
generated flake that installs the release's prebuilt binary (Linux amd64,
macOS arm64), so Nix compiles nothing. contrib/promote-stable writes
them after each release. The vX.Y.Z tags build from source, and
github:procrastivity/wip/main builds unreleased work.
direnv allow # or: nix develop
make check # lint + test
make hooks # pre-commit, both stages
Project orbs install the locked Nix development shell and Docker Engine from
.agents/setup. Docker runs as the supervised docker-daemon service declared
in .amp/services.yaml; start or repair it with:
amp orb services ensure
make orb-smoke
make orb-smoke builds and runs two hardened containers on an internal Compose
network with separate named volumes, verifies their byte exchange, and removes
all runtime resources. The smoke refuses bind mounts, Docker-socket mounts,
privileged or host-network containers, inherited credentials, and legacy-store
routes.
Orb files and Docker state are disposable. GitHub commits and Linear roadmap state are the recovery anchors. If dogfooding needs a legacy WIP store, create a fresh orb-local store; never import, mount, copy, or route to a live store from another machine.
Version stamps come from release tags (git describe --match 'v[0-9]*');
pushing an annotated vX.Y.Z tag is the only human release action.
CHANGELOG.md is generated per release, never committed.
The design of record lives in a sidecar planning repository (wip-reboot:
MODEL.md, one workplan per Matter), deliberately outside this repo.
Decisions worth keeping land here as findings on the Matters that made
them; the code and its comments carry the rest.