devtools

README

devtools

Shared agent tooling for tbhb repositories. The repo provides Go command-line tools for agent harnesses, plus the shared APM package of agent primitives.

APM package

Repositories across tbhb install the shared primitives with the APM CLI:

apm install tbhb-dev/devtools/packages/agents/claude#v0.10.0
apm install tbhb-dev/devtools/packages/agents/common#v0.10.0

The package deploys these primitives from sub-packages under packages/agents/: claude contains the skills below plus the guard-markdown hook declaration, and common contains the harness-neutral worktree-wip instructions.

Primitive	Type	Purpose
commit	skill	Group changes into one atomic commit, draft the message in COMMIT_AGENTMSG, review it, lint it, confirm it, then commit and rebase.
review-commit-message	skill	Review a drafted message against the staged diff as an independent agent, for what linting can't see.
worktree-wip	instructions	Stash and work-in-progress rules for repos that run more than one agent worktree session.
guard-markdown	hook	PreToolUse gate on Write and Edit that refuses Markdown whose paragraphs span more than one line.

Pinning the bare repo (apm install tbhb-dev/devtools#v0.10.0) resolves the root workspace manifest, whose dependencies on the four sub-packages under packages/agents/ are local paths that a remote consumer's apm resolves transitively, filtering each sub-package by its own targets. For a claude-only consumer, the bare pin gives exactly what the claude and common pins deliver. The codex and agy scaffolds skip on target intersection. This repo installs its own package the way a consumer does: apm install deploys the primitives into the local harness layout, and CI rejects drift between the packages/agents/*/.apm/ sources and the deployed copies.

Checks

A check is one rule enforced everywhere it matters. Because all three callers run the same binary, the rule can't drift between them:

Caller	Invocation
Claude PreToolUse	guard-markdown --hook reads the payload on stdin and denies the Write or Edit
pre-commit	guard-markdown FILES reports the offending line ranges and exits nonzero
verification stack	the same command from a mise task, alongside the other linters

.pre-commit-hooks.yaml publishes the pre-commit leg:

repos:
  - repo: https://github.com/tbhb-dev/devtools
    rev: v0.10.0
    hooks:
      - id: guard-markdown

Note that the two legs install separately. prek builds its own copy from language: golang. The Claude hook instead resolves guard-markdown on PATH, which comes from go install. A consumer wanting both adds the hook and runs the install.

Pass --fix to collapse paragraphs someone already wrapped.

Go tools

Each tool under cmd/ builds as a standalone binary:

• agenthooks manages shared agent hooks.
• agentstore stores shared agent state.
• agentcontext assembles shared agent context.
• guard-markdown refuses Markdown whose paragraphs span more than one line.

Install one directly:

go install github.com/tbhb-dev/devtools/cmd/agenthooks@latest

Or build everything from a checkout:

mise run build

Development

mise pins the toolchain and runs the workflow: mise run bootstrap sets up a fresh clone, mise run lint runs the full lint suite, mise run test runs the tests, and mise run build compiles the binaries into bin/. On a machine with no mise, the committed shim at tools/mise-bootstrap runs in place of mise and installs the pinned release on first use. The pins live in mise.toml and the drop-ins under .config/mise/conf.d/, locked by digest in the committed mise.lock files. See AGENTS.md for the agent-facing contributor guide.

Releases

cocogitto cuts vX.Y.Z tags from the Conventional Commit history. One tag serves both consumer paths, with APM installs pinning tbhb-dev/devtools#vX.Y.Z and Go installs pinning @vX.Y.Z.

Python

packages/devtools holds the Python side, which is deliberately small for now. Its gates run through mise run lint-py-all and mise run cover-py, which enforce ruff at its full ruleset, pyrefly's strict preset, and 100% branch coverage. uv sync provisions everything from uv.lock.

License

Apache-2.0. See LICENSE.