toolsdevopsai

This cairn is the directory. It points; it does not explain. Each tool we mention is covered in a later cairn (or two), and the linked cairn is where you go for the actual how. If you are setting up your machine for the first time, read this end-to-end, then follow the osprey-strike README exactly. If you are looking for a specific tool, jump to the table.

The required three

There are three tools that change how the team thinks, not just what we type. Without them, the discipline this trail describes does not work — not because they are unique technologies (they are not), but because we have built our practice around them and around each other’s use of them.

beads. A CLI issue tracker that gives an agent persistent memory across sessions. The issue graph syncs over git via the refs/dolt/data ref — versioned next to the code but invisible to PR diffs; the pre-push hook fires bd dolt push alongside git push. Memories (bd remember) are clone-local by design and do not propagate. Required, minimum version 1.0.4. Beads, the Backbone is the deep read.

timbers. A development ledger. After every commit, you (or your agent) writes one entry: what changed, why, and how. Git remembers what; timbers remembers why. Required. Timbers, the Ledger is the deep read.

just. The task runner. Every repo on the team has a justfile that exposes the build, test, lint, and deploy recipes by name. Both humans and agents look there first instead of guessing. Required. Just: One Place to Discover is the deep read.

Key Takeaway

Beads is the agent’s memory. Timbers is the team’s memory. Just is the project’s surface. Anything in this trail that talks about “the loop” assumes all three are installed and working.

The agent harness

A coding agent does the typing this trail keeps referring to. The harness is the thing that gives the agent access to your files, your shell, and your local sandbox. We have a strong preference; we are not strict about it.

Claude Code with Opus 4.7 (1M context). The recommended default. Strong skills ecosystem, mature plugin support, and the 1M context window earns its keep on this codebase. Strongly recommended but not required.

Codex CLI with GPT-5.5. An acceptable alternative. Different priors, different strengths, perfectly capable of doing the same work. Some of us run both — Claude as the daily driver, Codex as a second-opinion lever. Claude Code as Daily Driver covers Claude as a daily driver; Codex as Second Opinion covers Codex as a reviewer.

Other agent harnesses exist. If they wrap Claude or Codex via OAuth, they are plausible; the further you drift from the recommended stack, the more time you will spend wiring your own setup instead of doing the work. That tradeoff is yours to make.

Warning

We use OAuth subscriptions (Claude Pro / Max, Codex equivalents), not API keys. At the level we lean on these agents day-to-day, API-key billing is cost-prohibitive — not a preference, a structural decision. Claude Code as Daily Driver is explicit about this.

Warning

During Claude Code setup, disable Help Claude improve. We do not send Constructured work, prompts, or session transcripts into vendor training or improvement programs. Apply the same posture to any agent harness you use: opt out of telemetry, training, or product-improvement sharing when the tool offers the choice.

The runtime stack

Beneath the agent and the practice tools sits the runtime your code actually runs on. The good news: most of it is pinned in .mise.toml and installs itself.

mise. A polyglot version manager — the modern replacement for nvm, pyenv, goenv, asdf. Reads .mise.toml at the repo root and installs the managed versions of every language and tool the project needs. Required. Install once with curl https://mise.run | sh, then mise installs the rest, including timbers through Strike’s github:gorewood/timbers tool alias. Timbers deliberately floats on latest; the repo keeps that visible with mise run timbers-check, mise run timbers-upgrade, and a daily .envrc stale warning. One caveat: a couple of entries in Strike’s .mise.toml resolve through mise’s cargo: backend (currently just tokei — upstream stopped shipping prebuilt release binaries after 12.x, so the cargo path is the only one that works). If mise install errors with cargo: command not found on a fresh box, install Rust first with mise use rust@latest and rerun mise install. CI doesn’t hit this because GitHub-hosted runners ship with Rust preinstalled.

Go and Node are pinned through mise. Go (currently 1.26.3) covers packages/api and packages/mock; Node covers packages/web (Next.js) and packages/mcp (MCP server). You will not pick the versions; the project does.

direnv. Per-directory environment manager, installed globally through mise with mise use -g direnv@latest. Strike’s env config layers across three files: a deliberately small toolchain baseline (GOFLAGS=-race, NODE_ENV=development) in .mise.toml’s [env] block that loads on cd, the bulk in .envrc (service ports, DATABASE_URL, encryption key, Render and Twilio integration, Keycloak, observability — gitignored, materialized on day one by just setup and trusted with direnv allow), and personal overrides in .envrc.local. Without .envrc, services will not start; just doctor warns when it is missing. Your Box and Your Trust Model covers the trust handshake in detail.

Docker. Required for two things: the local just dev compose stack that brings up Strike’s services, and the api package’s integration tests (the api package uses testcontainers to spin up real Postgres for just api test-integration). Install Docker Desktop or Colima — manual, not via mise.

awscli, opentofu, kubectl, helm are pinned in mise. You will not need them on day one; Your Box and Your Trust Model covers when each becomes relevant.

The PR loop

Two more tools are required to participate in the pull-request workflow. Treat them as part of the required set even though they live outside the practice trio.

gh. GitHub’s CLI. Used for gh pr create, gh pr view, the Q-routine review loop, the API surface that beads talks to. Manual install (Homebrew on macOS, or direct download). When you set up GitHub and Copilot, opt out of GitHub Copilot product-improvement and training data use for the account or organization before doing Constructured work. From Plan to Pull Request walks the daily PR loop end to end, including the one gh api JSON-array gotcha that bites every new agent.The short version: the GitHub repository-dispatch API rejects stringified payloads silently. The fix is to build the body with jq -n and pipe it via gh api --input - rather than using gh api -F. The integration cairn shows the working snippet.

The quality gates. Not a single tool — the umbrella for golangci-lint, ESLint, Prettier, the Go test runner, audit-ci, and the pre-commit hook that ties them together. They are installed by just setup (which runs the per-package setup recipes) and run by just check. Quality Gates: The Contract That Lets You Move Fast is the deep read on exact thresholds and how to live with them.

The optional layer

A few tools are genuinely optional. We mention them so you know they exist; whether you install them is your call.

RTK. A token-cheap proxy for routine commands. The Claude Code hook rewrites things like git status to rtk git status automatically, and you save 60–90% on dev-op token spend over a quarter. Verify with rtk gain once installed. Optional but high value. Quiet Power Tools covers it.

tokf. A per-project token filter. Lighter mention; not heavily used in Strike yet. If you find yourself piping shell output through head -100 to keep an agent from drowning, look at tokf.

dm-work plugins. A set of Claude Code plugins (dm-work:orchestrator, dm-work:subagent, dm-work:worktrees, dm-work:review, etc.) that add skill modules and slash commands tuned for serious agent-assisted work. They live at rbergman/dark-matter-marketplace and are maintained today by one person — which is precisely why a Constructured-specific plugin set is in progress, so the team can collectively contribute to and maintain its own equivalent. Influenced by dm-work but not a copy. We will not commit to a date. When it lands, expect a follow-up cairn.

Where each one comes from

The full table. Treat the Required? column as canonical and the cairn pointers as the place to read more.

Tool Source Required? Where it’s covered
Claude Code Native install (recommended over npm) Strongly recommended Daily Driver
Codex CLI Manual install Optional alternative / second opinion Daily Driver, Second Opinion
beads Manual install (not in mise catalog yet); min 1.0.4 Required Beads, the Backbone
timbers mise (github:gorewood/timbers, floating on latest) Required Timbers, the Ledger
just mise (github:casey/just) Required Just
mise Manual install (curl https://mise.run | sh) Required (it installs the rest) Trust Model
go mise Required (for api work) Trust Model
node mise Required (for web / mcp work) Trust Model
direnv mise global (mise use -g direnv@latest) Required Trust Model
docker Manual install (Docker Desktop or Colima) Required (compose stack + integration tests) Trust Model
awscli, opentofu, kubectl, helm mise Recommended (ops surface) Trust Model
gh Manual install (Homebrew or download) Required (PR workflow) Plan to PR
RTK Manual install Optional but high value Quiet Power Tools
tokf Manual install; not heavily used in Strike yet Optional, lighter mention Quiet Power Tools
dm-work plugins Claude Code plugin marketplace Recommended; constructured-specific set forthcoming Working in Parallel
Tip

Beads may join the mise catalog at some point; today it is still a manual install. Timbers already comes through mise in Strike, but it intentionally floats on latest instead of being lockfile-pinned.

Verifying your box

This is the handoff point. The Workshop names the tools and explains the shape of a healthy environment; the osprey-strike README owns the exact setup and recovery commands. Keep that boundary clean. If this article and the README ever disagree about what to type, follow the README and fix this article.

For a first checkout, the working path is:

  1. Install mise and the remaining manual practice tool. Beads is still a manual bootstrap install; timbers comes through the repo's mise-managed toolchain after you trust the repo config.
  2. Run the README setup sequence from the repo root. That includes mise trust, mise install, global direnv setup, mise run timbers-check, just setup, direnv allow, local services, and database seeding when you need runnable test data.
  3. Check the project surface. just --list should show the available recipes; just doctor should explain any remaining drift.
  4. Check the collaboration tools. bd ready confirms beads can read the issue queue; timbers pending confirms the ledger is reachable; gh auth status confirms GitHub access.
  5. Run the gate. Once just check passes from the project repo root, you have the baseline needed to start contributing.

On a fresh clone, beads may need its embedded database rebuilt before bd ready works. Use the README’s current beads setup and migration notes for that recovery path; they are more specific than this tool map should be.

Summary

  1. The required three: beads, timbers, just. They define our discipline. Cairns 3, 4, and 6 are the deep reads.
  2. The agent harness: Claude Code recommended, Codex acceptable. OAuth subs, not API keys. Claude Code as Daily Driver explains why.
  3. The runtime: mise pins most of it and manages timbers. Install mise once, then run mise install and mise use -g direnv@latest. Most of your project toolchain materializes from .mise.toml; timbers floats on latest by design and has its own stale check. Docker, gh, and beads are manual; Your Box and Your Trust Model covers when each becomes relevant.
  4. The optional layer: RTK, tokf, dm-work plugins. Compound benefits over a quarter; not blockers on day one.
  5. Constructured-specific plugins are coming. No date. When they land, a follow-up cairn will update the recommendation.
  6. Verify your box by following the README setup sequence, then checking mise run timbers-check, just doctor, bd ready, timbers pending, gh auth status, and just check.
  • Is there a tool you currently rely on that you would push to add to this list as required, recommended, or optional? What would it replace, if anything?
  • The remaining "manual install" rows (beads, gh, Docker, and agent harnesses) are the friction points in onboarding. Which of them should stay explicit, and which are worth automating next?
  • Some teams keep their plugin set checked into the repo so it's reproducible per machine; others let each contributor install whatever they want. Which posture should we adopt for the constructured-specific plugins, and why?
  1. How We Build Here — The trail's opening cairn. Read first if the philosophy of "gates over vibes" needs context for any of the tool choices below.
  2. mise — The runtime version manager. Single install, then it manages Go, Node, just, timbers, opentofu, kubectl, helm, and more from .mise.toml; direnv is installed globally with mise use -g direnv@latest.
  3. just — The task runner the team uses for every repo's discovery surface. Just: One Place to Discover covers the practice; this is the upstream reference.
  4. beads on GitHub — The CLI issue tracker. Source code, install instructions, and changelog. Beads, the Backbone covers the practice.
  5. timbers — Public documentation for the development ledger CLI. Timbers, the Ledger covers the practice; this is the upstream reference.
  6. GitHub CLI (gh) — Required for the PR review workflow. Manual install on macOS via Homebrew or direct download.
  7. Docker — Required for the integration test suite (testcontainers). Install Docker Desktop or Colima.