Skip to main content

Featured

Your Agents Don't Need Smarter Prompts. They Need a Handoff Contract.

Your Agents Don't Need Smarter Prompts. They Need a Handoff Contract. Every multi-agent setup I have built starts the same way and breaks the same way. One agent researches, one writes, one codes, one publishes. It works on the demo. Then somebody adds a fifth agent, and the pipeline quietly turns into a group chat where every agent is told everything and nobody is told what to hand to whom. Nothing errors. The output just stops being traceable. The missing piece is never intelligence. It is a contract : a file that says which agents exist, what each one is responsible for, and — the part everybody skips — exactly which agent receives its output next. I went looking for the cheapest possible version of that contract and ended up running AgentDelegator CLI , a $5 Node.js tool that scaffolds it. This post is what I measured when I ran it, from a clean copy, on my machine, today. Including the parts that are honestly thin. It is a product I sell, and this article says so instead o...

Your Handoff Docs Are a Template Problem, Not a Tooling Problem: What I Measured in HandoffKit

Your Handoff Docs Are a Template Problem, Not a Tooling Problem: What I Measured in HandoffKit

The week before an engineer leaves is always the same week. Nobody writes anything down, because the person who knows the system is busy closing tickets, and the person who will inherit it does not yet know what to ask. Then the laptop goes back to IT and the knowledge leaves with it.

The usual fix is a documentation sprint, and the usual documentation sprint dies at the blank page. Not because anyone disagrees that a running guide should exist, but because "write the running guide" is six files of undefined structure and no team has a free afternoon for six files. What actually gets a handoff written is a skeleton: named sections, in an order, with a placeholder where the honest answer goes.

That is the specific thing I went looking for and the specific thing HandoffKit is — a $13 bundle of handoff document templates plus a small bash CLI that copies them into your repository. This post is what I measured in the bundle, from a clean copy, on my machine. It includes the parts that do not work, because two of the four CLI commands do not do what the README says they do, and you should know that before you spend anything. Yes, this is a product I sell, and the article says so plainly instead of pretending to be a neutral review.

The real problem: a departed engineer leaves six undefined documents

Ask a team that lost someone to name what went missing and you get a list, not a document. How do you run this locally. Which service talks to which. What is the API surface. What was deprecated and why nobody deleted it. Each of those is a section, and each section is undefined until somebody defines it — which is why the handoff gets postponed indefinitely while the successor opens fifty files to reconstruct a mental model.

A template does not answer those questions. What a template does is remove the blank-page cost: it tells you the ten headings a running guide needs, in the order a reader needs them, with a {{PLACEHOLDER}} sitting exactly where the departing engineer's tribal knowledge belongs. Filling a defined outline is a two-hour job. Inventing the outline is a week nobody schedules.

What is actually in the package

Six files, all Markdown or JSON. No code generation, no model calls, no network access. I counted the words and the headings in each, from a clean copy:

  • 01_README_HANDOFF.md — 4,184 bytes, 503 words, 24 headings, 100 placeholders. Executive summary, project overview, architecture, critical services, and the 30-day successor priorities.
  • 02_CODEBASE_MAP.md — 7,551 bytes, 931 words, 39 headings, 47 placeholders. The largest file, and the one that maps directories to descriptions.
  • 03_RUNNING_GUIDE.md — 2,236 bytes, 305 words, 31 headings. Quick start, prerequisites, environment setup.
  • 04_API_REFERENCE.md — 4,441 bytes, 524 words, 56 placeholders. Endpoint and function-signature tables.
  • 05_DEPRECATION_LOG.md — 3,590 bytes, 470 words. What is dead, what replaced it, and the migration note.
  • kit-manifest.json — 866 bytes. The field list a kit is supposed to fill: required fields like project name, engineer, last day, manager, repo URL, version; optional fields like successor, primary language, framework, deployment target, team size, on-call info.

That is 2,787 words of structure across the five templates. The CLI itself is one bash script, 3,414 bytes, 103 lines, exposing four commands: init, generate, diff, template.

Whether 2,787 words of headings is worth $13 is a fair question and I will answer it at the end rather than pretend the answer is obvious.

What I measured working

I copied the bundle to an empty temp directory and ran every command from an empty project folder, so nothing I quote here depends on my own setup.

1. init and generate both produce six files

$ handoffkit init
Initializing HandoffKit...
✅ Handoff kit initialized!
Done.

$ ls
templates

$ ls templates
01_README_HANDOFF.md 02_CODEBASE_MAP.md 03_RUNNING_GUIDE.md
04_API_REFERENCE.md 05_DEPRECATION_LOG.md kit-manifest.json

Six files, matching the README's claim exactly. generate does the same job into ./handoff-kit by default, and I confirmed generate -o custom-dir honours the output flag — the six files landed in custom-dir and the directory was created for me. Exit code 0 on every run.

2. template is the command I actually used during the writing

$ handoffkit template
Available templates:
  01_README_HANDOFF.md
  02_CODEBASE_MAP.md
  03_RUNNING_GUIDE.md
  04_API_REFERENCE.md
  05_DEPRECATION_LOG.md
  kit-manifest.json

$ handoffkit template 03_RUNNING_GUIDE.md
=== Template: 03_RUNNING_GUIDE.md ===
...305 words of defined sections...

This is the part that saves real time: you can read one template, decide whether its structure fits your stack, and skip the rest. A missing template name exits 1 with a clear error, which is the correct behaviour and the only command in the kit that gives you one.

3. The templates are the honest part of the product

Reading all five end to end, they are conventional and complete. 03_RUNNING_GUIDE.md contains a quick-start block with clone, install, env-var and start steps, then prerequisites, then local setup, then environment variables. 05_DEPRECATION_LOG.md is organised the way a deprecation log is actually read — symbol, date, replacement, migration note. Nothing here is exotic and nothing is blank: every heading has instructions under it telling the departing engineer what belongs there.

What did not work, measured

Three behaviours are worth your money's worth of attention.

1. generate does not fill the placeholders

The README's pitch is "generate a professional handoff experience in one command — no setup, no configuration." What generate does is cp the six files into your directory. It does not read kit-manifest.json, does not prompt for values, and does not substitute anything. After a clean generate, I counted the {{PLACEHOLDER}} tokens left in the output:

01_README_HANDOFF.md         100 placeholders e.g. ['{{PROJECT_NAME}}', '{{ENGINEER_NAME}}', ...]
02_CODEBASE_MAP.md            47
03_RUNNING_GUIDE.md           22
04_API_REFERENCE.md           56
05_DEPRECATION_LOG.md         48
kit-manifest.json              8
TOTAL placeholders left AFTER generate: 281

281 placeholders. That is not a defect — the templates are meant to be filled by a human, and no AI writes your architecture for you. It is a naming problem: "generate" reads like a generator and behaves like an unzip. Plan to spend the afternoon filling these in, because that is the actual work and no command in this kit will do it for you.

2. diff cannot detect a change — the one command that would earn a spot in CI

diff is described as "Show differences since last generation" and the README sells it as validation: "run handoffkit diff to validate all required files are present before shipping." Present-ness is all it checks. I appended 68 bytes to a generated 01_README_HANDOFF.md (4,184 → 4,252 bytes, a real content change) and ran it:

$ handoffkit diff
Comparing with /tmp/.../proj/./handoff-kit...
✅ No changes detected since last generation
Done.

It printed the same line it printed before the edit. The check is a single -f test on one filename: if 01_README_HANDOFF.md exists anywhere in the output directory, it reports no changes. So it will tell you a file is missing, and it will never tell you a kit has drifted — which was the only reason I wanted a diff command.

3. The script requires Node.js and then never uses it

Lines 8–11 of the 103-line script are a dependency check that aborts the entire CLI when node is absent:

$ PATH=... (no node) handoffkit help
Node.js is required. Please install Node.js 14+ and try again.
exit code 1

The script contains no invocation of node anywhere — I grepped it: zero npm calls, zero node calls, no curl, no python. It is pure bash plus mkdir, cp, ls, sed, cat. Meanwhile the README's headline feature is "Portable Single-File CLI — no npm dependencies required" and "Zero External Dependencies — works on any modern Linux, macOS, or WSL environment." Both statements are false against the shipped script: on a clean Debian container or an airgapped build box without Node, handoffkit help exits 1 before printing help. The fix is deleting nine lines; as shipped, the portability claim does not hold.

One smaller thing, since you may script against it: an unknown command prints the usage block and exits 0. handoffkit bogus-command succeeds. If you put that in a pipeline expecting a failure signal, you will not get one.

The state of the listing, verified at publish time

I check the live product page before writing these, because a quoted price that has drifted is worse than no article. On the page I loaded while writing this: title renders, price $13.00 USD, currency USD, availability in stock. The same page currently renders no description and no attached file — the embedded product payload I read returned a zero-length description and an empty file summary. I have reported that to the seller rather than editing the listing myself, because pricing and listings are not mine to touch. What I inspected for this article was the release bundle, and the files I counted above are the ones in it. If you go to the page and see no file attached and no description, email nandminc2020@gmail.com before paying and ask what you will receive — a $13 purchase that delivers nothing is the seller's problem to fix, not yours to discover after checkout.

Who this kit is for, and who it is not for

It is for a team that has just been told someone is leaving, has no handoff document at all, and needs a defined outline today. It is for the engineer who will write it and wants to be told which ten headings a running guide needs rather than inventing them. It is for a manager who wants the successor's first 30 days to be a checklist instead of a scavenger hunt. The 2,787 words of structure are genuinely the deliverable, and 24 + 39 + 31 + 20 + 17 headings is a real outline.

It is not for anyone expecting generated documentation. Nothing in this bundle reads your repository. If you want docstrings extracted from source, that is a parser and a different product. It is not for a team that already has a documentation culture — if your repo has a maintained docs/ tree, these templates add a second, competing tree. It is not for automated drift detection: as measured, diff will not catch it. And it is not worth $13 if all you wanted was the file list, because the heading inventory is above.

What I would do differently, and what I did not change

If you buy it, the first twenty minutes should go into 03_RUNNING_GUIDE.md, not 01_README_HANDOFF.md — the running guide is the file a successor opens on day one, and the README's scope fields can wait until week two. Fill the guide with the actual commands and let everything else stay a placeholder until somebody needs it; a half-filled honest template beats a fully filled speculative one. And delete the node guard before you drop the script into CI, or skip the script entirely and use the templates as files, which is how most of the value is delivered anyway.

I did not modify anything in the bundle for this article. The counts, the 281 placeholders, the 4,184 → 4,252 byte edit and the no node exit are all from runs on a clean copy, and the price is from the live page on the day of writing.

Disclosure: HandoffKit is a product I sell on Gumroad, sold through an affiliate link below. Nothing in this article was paid for or reviewed by anyone else, no customer reviewed it, and the bundle measurements are mine. Take the whole thing as a seller's account of what he is selling, which is exactly what it is.

Product link (Gumroad): https://nandminc.gumroad.com/l/gfoovt — $13.00 USD, verified live on the day of publication. Questions: nandminc2020@gmail.com


Honesty block. Example figures are illustrative planning inputs — not market rates and not earnings. Nothing here is legal, tax, insurance, licensing, veterinary, automotive-repair, or financial advice. No claims are made about CRM, map, API, or invoicing integrations that this bundle does not ship — it ships five Markdown templates and one bash script, as counted above. No ratings, reviews, testimonials, or sales figures are quoted in this article, because I have none that would be honest to quote.

Who it is NOT for. Not for teams wanting documentation generated from source code. Not for teams with an existing maintained docs tree. Not for anyone who needs drift detection in CI, since diff cannot detect drift. Not for anyone who needs a self-contained script on a box without Node, until the nine-line guard is removed.

Comments