requirements-box
A requirements box: one page where the user writes down what they want done, a scheduled task that wakes the agent to work through it, and a report by mail per round — so asking for something does not cost a conversation, and nothing gets lost between them.
user files a request on the page
│
├─ status=new … the page keeps it, the schedule waits
▼
every <period> the agent wakes, reads the list, marks each item doing, and works through up to three
│
├─ done → committed, gated, shipped; item archived, one mail per round
├─ blocked → the question it could not answer, mailed to the user
└─ rejected → why not, in the same mail
What's inside
| Piece | What it is |
|---|---|
kit/requirements.mjs | The whole service: a JSON store with atomic writes, the keyed API (list/create/read/patch, the patrol cadence, and the do-it-now trigger), and it serves the page. Node standard library only — no build step, no dependency tree. |
kit/requirements.html | The page: file a request, edit or withdraw one, select several and act in bulk, schedule an item, pause the patrol or change its cadence, see which commits are not released or not on the live server yet, and a "do it now" button. |
kit/serve.mjs | A standalone server for the box alone, so it can run on its own port without touching anything else already on the machine. |
kit/patrol.md | The protocol the scheduled round follows: take work, mark it doing before touching it, triage, gate, ship, mail, archive — and the red lines. |
kit/install.mjs | Lays the files down, generates the key, writes box.config.json, writes the schedule, and prints the two commands left to run. |
Why it exists
- Asking is not a conversation. The user's own words are on the page; the agent reads them when it wakes, not when it happens to be listening.
- No dependency tree for a form. One Node file, one JSON store — nothing to install, nothing to upgrade, and the whole state is a file you can read.
- The schedule is a file, not a black box. The round is a
.tomlthe platform re-reads; the cadence, the on/off switch and the "do it now" button all write that one file. - You can see what is not out yet. The page carries a "commit sync" card: the commits after the last
release tag, what the live server is actually running (asked of its own
/api/version, not read off disk), whether an update is installed but not restarted yet, and the released commits the running server has not picked up. All four come frombox.config.json(repoDir/serverUrl/serverTokenFile/installDir), which the installer works out for you; anything it cannot work out is reported as "not configured" rather than guessed. The token file stays in this process and never reaches the browser. - Doing it now is one click. Waiting for the next tick is the common complaint, so the page can start a session immediately, and can do it for just the items the user selected.
Install
node <skill dir>/kit/install.mjs --dir ~/requirements-box --workspace ~/my-project --port 3007 --period 2h
Then start node ~/requirements-box/serve.mjs and open the printed URL (the key rides in ?key= once and
the page remembers it). Everything machine-specific lives in the generated box.config.json; environment
variables override it.
Notes
- The key is the ability to make the agent work. It lives in
key.txt(0600) and must not reach a commit, a log or a mail body. - The page is meant to be reachable by one person, not published: bind
127.0.0.1unless the user asked for a wider listen, and never expose it without the key. - The patrol protocol is deliberately in one markdown file the user can rewrite — the flow is theirs to change.