logistics
From idea to merge-ready PR on autopilot: an AI engineering team in your terminal, with spec-driven planning, right-sized models and smart gates that only stop you when it matters.
logistics is a set of Claude Code skills and subagents that take a feature idea, or a bug report, to a reviewed pull request, using Spec Kit for the spec, plan and tasks.
/brief "<idea>"interviews you about a feature and writes a short brief./feat <brief>(its path or short name) specifies, plans, reviews the design, breaks it into tasks, implements, reviews the code, then commits, pushes and opens a PR on its own branch./fix #N(or/fix "<symptom>") assesses a bug, fixes it, has a different agent verify the fix, reviews it and opens a PR withFixes #N./tiny "<change>"(or/tiny #N) makes a trivial change, a typo, a docs edit or an obvious fix, in one session with no subagent: a tiny brief (optionally an issue on your board), the edit, your checks, a reread of the diff, then the PR. It hands off to/briefor/fixwhen the work turns out bigger./feat rebase(or/fix rebase) keeps a shipped run’s PR on the current main once another PR merges: it rebases it, resolves the conflicts and pushes it; only real decisions stop for you.
You decide at a few gates (the brief, the spec when it leaves a question open, which review findings to fix); everything else runs on its own, and nothing is ever merged for you. Each phase runs in its own subagent on a model and effort sized to the job: Sonnet at medium effort for most of a small feature, Opus at higher effort where a large one needs it. The session you type in only coordinates, which keeps token use down on a plan with a usage limit.
Quick start
You need Claude Code, git, the
GitHub CLI logged in (gh auth login) and
uv.
uv tool install apm-cli # the package manager that installs logistics
uv tool install specify-cli # Spec Kit
apm install -g pdemagny/logistics -t claude # skills, agents and the skills they use
cd ~/your-project
specify init --here --integration claude # once per project
specify extension add bug # once per project, for /fix
claudeThen, in Claude Code:
/brief "let users export a report as CSV"
/clear
/feat specs/briefs/<name>.md/clear starts the build with a fresh context, so the interview isn’t
carried into every later step. For a bug: /fix #42 or /fix "export drops the last row". For a typo, a docs edit or an obvious fix: /tiny "fix the install link", in one session.
Prefer a Claude Code plugin, or working from a clone? Both, and a command
that checks your setup, are in docs/install.md. Claude
Code only: the workflow needs its subagents with a model and effort per
call, and EnterWorktree.
How it works
Agents do the work, each phase in a fresh one. Solid orange arrows are gates where the run always waits for you; dashed ones wait only when something needs your call. The spec stops only on an open question; otherwise you see its summary at the plan and design review gate. A large feature also stops after the plan, the design review, the tasks, each story and the code review.
Each artifact is checked before the next one is built from it. Shown for medium and large features, with one reviewer per lens; a small feature runs one design reviewer and two code reviewers covering the same lenses.
- Design review (phase 4) looks at security, cost, and clarity and fit: that last lens reads spec and plan as someone new to the project would, paraphrases them for you to check, and flags what is unclear, what the code contradicts and what already exists.
- Code review (phase 7) looks at correctness against the spec, security, performance, over-engineering and readability. Each finding comes with a recommendation, applied for you; it stops only for a judgement call, a security finding or an unmet criterion (always on large).
- A huge idea is split into a capability map first: one brief, one run and one PR per capability.
/fixruns the same way on Spec Kit’s bug extension: assess, fix, test by a different agent, code review, ship./tinyskips the pipeline for work too small to need it: one session, no Spec Kit, no subagent unless the change touches a contract other files read; it hands off to/briefor/fixwhen it isn’t tiny.
Every phase, gate and model: docs/workflow.md.
Documentation
Also on the website: pdemagny.github.io/logistics.
| Doc | What’s in it |
|---|---|
| docs/install.md | Prerequisites, the three ways to install, the setup check, board tracking, update, uninstall |
| docs/usage.md | Brief, build, fix a bug, make a trivial change, answer gates, resume, change the size, tune models and effort |
| docs/workflow.md | Every phase, gate and agent: the size × phase matrix, what runs when and how |
| docs/measure.md | Measure what your /feat and /fix runs cost from your transcripts: running measure.py, reading its figures, weights and prices |
| docs/design.md | Why it is built this way: Claude Code mechanics, rejected alternatives |
| Roadmap | Known bugs and what is planned |
| CONTRIBUTING.md | Reporting bugs, proposing changes, working on logistics |
| SECURITY.md | Reporting a vulnerability privately |
Status
Version 0.14.0. Tested with Claude Code 2.1.308 and Spec Kit (specify-cli) 1.2.x. See CHANGELOG.md.
License
MIT, see LICENSE. Some review checklists and prompts are adapted
from addyosmani/agent-skills, mattpocock/skills, dietrichgebert/ponytail
(MIT) and google/elephant-goldfish-model (Apache-2.0), and the .specify/
files come from Spec Kit (MIT). Credits and license texts are in
THIRD_PARTY_NOTICES.md. The third-party skills
that get installed keep their own licenses.