@gonxped31/agent-kit 0.0.0-stage → 0.2.0

package/lib/ui.mjs

@@ -0,0 +1,127 @@
+// How agk prints: colors, symbols and a spinner, with plain fallbacks.
+// - Color is on for a terminal, unless NO_COLOR is set or TERM is dumb. FORCE_COLOR=1 forces it
+//   on, FORCE_COLOR=0 off.
+// - Symbols are Unicode where the terminal can show them, ASCII elsewhere. On Windows that's only
+//   in Windows Terminal, VS Code and the like: an old console lacks the glyphs, and a pipe may be
+//   decoded with an old code page.
+// - The spinner moves only in a terminal. Elsewhere (a pipe, Claude Code) each step prints one
+//   line when it's done.
+
+const env = process.env;
+const tty = Boolean(process.stdout.isTTY) && env.TERM !== "dumb";
+
+function colorOn(stream) {
+  if (env.FORCE_COLOR) return env.FORCE_COLOR !== "0";
+  return Boolean(stream.isTTY) && !env.NO_COLOR && env.TERM !== "dumb";
+}
+
+const modernWindowsTerminal = Boolean(
+  env.WT_SESSION || env.TERM_PROGRAM === "vscode" || env.TERMINAL_EMULATOR === "JetBrains-JediTerm" || env.ConEmuTask,
+);
+const unicode = process.platform === "win32" ? tty && modernWindowsTerminal : env.TERM !== "linux";
+
+const sym = unicode
+  ? { ok: "✔", fail: "✖", warn: "▲", more: "…", frames: ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"] }
+  : { ok: "+", fail: "x", warn: "!", more: "...", frames: ["-", "\\", "|", "/"] };
+
+function palette(on) {
+  const wrap = (open, close) => (s) => (on ? `\x1b[${open}m${s}\x1b[${close}m` : String(s));
+  return { bold: wrap(1, 22), dim: wrap(2, 22), red: wrap(31, 39), green: wrap(32, 39), yellow: wrap(33, 39), cyan: wrap(36, 39) };
+}
+/** Styles for stdout, and for stderr (failures). */
+export const out = palette(colorOn(process.stdout));
+const err = palette(colorOn(process.stderr));
+
+const say = (text = "") => process.stdout.write(`${text}\n`);
+export const blank = () => say();
+/** A line indented under the header. */
+export const line = (text) => say(`  ${text}`);
+export const ok = (text) => line(`${out.green(sym.ok)} ${text}`);
+export const warn = (text) => line(`${out.yellow(sym.warn)} ${text}`);
+/** The items of the line above, indented under it (the first 8 of them). */
+export const details = (items) => {
+  for (const item of clip(items)) line(`    ${item}`);
+};
+/** "1 file", "2 files". */
+export const count = (n, noun) => `${n} ${noun}${n === 1 ? "" : "s"}`;
+
+export function header(version, subtitle) {
+  blank();
+  line(`${out.bold(out.cyan("agk"))} ${out.dim(`v${version}`)}${subtitle ? `  ${subtitle}` : ""}`);
+  blank();
+}
+
+/** A numbered list under a bold title. An item's later lines are dimmed, as its explanation. */
+export function list(title, items) {
+  blank();
+  line(out.bold(title));
+  items.forEach((item, i) => {
+    const [first, ...rest] = item.split("\n");
+    line(`  ${out.cyan(`${i + 1}.`)} ${first}`);
+    for (const r of rest) line(`     ${out.dim(r)}`);
+  });
+  blank();
+}
+
+/** What went wrong, for the user: a message, the lines that show it, and what to do next. */
+export class Failure extends Error {
+  constructor(message, { details = [], hint = "" } = {}) {
+    super(message);
+    this.details = details;
+    this.hint = hint;
+  }
+}
+
+export function showFailure(e) {
+  const lines = [`  ${err.red(sym.fail)} ${err.bold(e.message)}`, ...e.details.map((d) => `      ${d}`)];
+  if (e.hint) lines.push(...e.hint.split("\n").map((h) => `    ${h}`));
+  process.stderr.write(`${lines.join("\n")}\n\n`);
+}
+
+/** Up to `max` items, then "... and N more". */
+export function clip(items, max = 8) {
+  return items.length <= max ? items : [...items.slice(0, max), `${sym.more} and ${items.length - max} more`];
+}
+
+let cursorHidden = false;
+function showCursor() {
+  if (cursorHidden) process.stdout.write("\x1b[?25h");
+  cursorHidden = false;
+}
+process.on("exit", showCursor);
+process.on("SIGINT", () => {
+  if (tty) process.stdout.write("\r\x1b[2K");
+  showCursor();
+  process.exit(130);
+});
+
+/**
+ * Runs `work` (async) behind a spinner, then marks the step done with the text `work` returns,
+ * or `text`. If `work` throws, the spinner is cleared and the error goes on.
+ */
+export async function step(text, work) {
+  if (!tty) {
+    ok((await work()) ?? text);
+    return;
+  }
+  let frame = 0;
+  const draw = () => process.stdout.write(`\r\x1b[2K  ${out.cyan(sym.frames[frame++ % sym.frames.length])} ${text}${out.dim(sym.more)}`);
+  process.stdout.write("\x1b[?25l");
+  cursorHidden = true;
+  draw();
+  const timer = setInterval(draw, 80);
+  const stop = () => {
+    clearInterval(timer);
+    process.stdout.write("\r\x1b[2K");
+    showCursor();
+  };
+  let done;
+  try {
+    done = await work();
+  } catch (e) {
+    stop();
+    throw e;
+  }
+  stop();
+  ok(done ?? text);
+}

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "@gonxped31/agent-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Sets up git repos for Claude Code, and keeps them up to date: a short CLAUDE.md, git and todo skills, hooks and checks.",
+  "license": "MIT",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "agents",
+    "git-hooks",
+    "cli"
+  ],
+  "bin": {
+    "agk": "bin/agk.mjs"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "template/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/kit.test.mjs"
+  }
+}

package/template/.gitattributes

@@ -0,0 +1,5 @@
+* text=auto
+# sh can't run a hook with CRLF line endings, so hooks stay LF on every OS.
+.githooks/* text eol=lf
+# Two branches that both finish todos keep both archive lines.
+todo-archive.md merge=union

package/template/.githooks/pre-commit

@@ -0,0 +1,8 @@
+#!/bin/sh
+# Refuses commits on main (except a repo's very first commit), then runs the fast checks.
+# Turned on once per clone: git config core.hooksPath .githooks
+if git rev-parse -q --verify HEAD >/dev/null && [ "$(git symbolic-ref --short -q HEAD)" = "main" ]; then
+  echo "pre-commit: no commits on main. Work on a branch; main moves through node scripts/merge.mjs (git skill)." >&2
+  exit 1
+fi
+exec node scripts/check.mjs --fast

package/template/BOOTSTRAP.md

@@ -0,0 +1,103 @@
+# Bootstrap: set up this repo for agents
+
+agent-kit's `agk setup` copied this file and the setup files into the repo, and ran
+`git init` if it wasn't one yet. Where the repo had one of those files already, it left
+that file as it was and put the kit's version next to it, as `<file>.kit`. Follow these
+steps once, in order. Step 6 deletes this file.
+
+## 1. Look before asking
+
+Find out on your own:
+- Does it have commits (`git log --oneline -3`)? If so, its main branch must be called
+  `main` (the hook and `scripts/merge.mjs` assume it). If it's called something else,
+  ask the user before renaming it.
+- Remotes (`git remote -v`). None is fine: the `git` skill handles both.
+  `agk setup --github` adds an empty GitHub repo as `origin`.
+- The stack, from what's there: `package.json`, `pyproject.toml`, `go.mod`,
+  `Cargo.toml`, a README.
+- Uncommitted work (`git status --short`) in `scripts/`, `docs/` or `.claude/` that
+  isn't the kit's (`.claude/agk.json` lists the kit's files): step 6 stages those
+  folders whole, so ask the user to commit it first.
+- Git hooks of its own (`git config core.hooksPath`, `.husky/`): step 5 points git at
+  `.githooks/` instead, which turns them off. Ask the user; to keep both,
+  `.githooks/pre-commit` can run theirs.
+
+## 2. Ask, in one message
+
+Ask only what step 1 didn't answer. "Don't know yet" is a good answer: it becomes a
+todo (step 4), never a guess.
+
+1. The project's name, and what it is in 2-3 sentences.
+2. The stack, if it's chosen: language, framework, how to test and lint.
+3. Does `main` deploy anywhere when it changes?
+4. What must never break?
+5. What do you need to see before a change counts as done (tests, screenshots, a demo)?
+6. Is there anything agents must never read or change (large data, secrets, generated files)?
+
+## 3. Fill in the setup
+
+- Each `<file>.kit` (`node scripts/doctor.mjs` lists them) is the kit's version of a
+  file the repo had. Merge it into that file: keep what the repo has, add what the
+  kit's brings (for `CLAUDE.md` its sections, for `.claude/settings.json` its hooks
+  and rules), and ask the user where they conflict. Then delete the `.kit` file.
+- `CLAUDE.md`: replace every `{{...}}`. Write only the rules the user gave, one bullet
+  each. Keep it short: it's in context on every turn.
+- If `main` deploys, add to "Working here": "`main` deploys to <where> on every merge."
+- Never read or change → `deny` rules in `.claude/settings.json`, e.g.
+  `Read(./data/**)` and `Edit(./data/**)`.
+- If the stack is known, do the "stack chosen" row of step 4 now instead of adding it.
+
+## 4. Add a todo for everything deferred
+
+`T` stands for `node .claude/skills/todo/scripts/todo.mjs`. One todo per deferred
+part. Its detail holds the trigger, what to do and why, and must stand alone: this
+file will be gone.
+
+    T add 'Stack chosen: checks, ignores, deny rules' -p 1 --tag setup
+    T detail <ID> 'Trigger: ... Do: ... Why: ...'
+
+Single quotes, not double: the `todo` skill says why, and what to do about apostrophes.
+
+| Trigger | Do |
+| :--- | :--- |
+| The stack is chosen | Add its checks to `scripts/check.json` (`{ "name": "test", "run": "npm test", "slow": true }`; `slow` steps skip the pre-commit hook but run in `check` and `merge`). Add a `.gitignore`, `deny` reads of dependency and build folders, and allow the check commands in `.claude/settings.json`. |
+| The first screen exists (if there's a UI) | A skill that screenshots it at phone and desktop sizes and flags overflow and console errors. |
+| A remote is added (or `agk setup --github` added one) | CI that runs `node scripts/check.mjs`. |
+| A "don't know yet" from step 2 | Ask again then. |
+
+Add any others the answers suggest, e.g. large data files coming: `deny` reads of
+them, and a script that queries them with short output.
+
+## 5. Turn on the hooks and check
+
+    git config core.hooksPath .githooks
+    node scripts/check.mjs
+
+Fix whatever `check` reports (it runs `doctor`) until it prints OK.
+
+## 6. Delete this file and commit
+
+1. Delete `BOOTSTRAP.md`.
+2. Stage by name, adding `todos` if step 4 added any and `.gitignore` if you wrote one:
+
+       git add CLAUDE.md .claude/settings.json .claude/skills .claude/agk.json .githooks scripts docs .gitattributes
+       git add --chmod=+x .githooks/pre-commit
+
+   Not all of `.claude`: Claude Code may keep the user's personal `settings.local.json`
+   there, and a machine's git ignore can miss it. `.claude/agk.json` records the kit's
+   files, for `agk update`. The `--chmod` line is for Windows, which doesn't record the
+   executable bit.
+3. If the repo had no commits, commit on `main`: the hook allows a repo's first commit
+   there. Otherwise `git switch -c agent-setup`, commit, and merge with
+   `node scripts/merge.mjs` once the user approves.
+   Message: `Agent setup: <what was set up>`.
+4. If there's a remote (`git remote`), push `main` once the user agrees:
+   `git push -u origin main`.
+
+## 7. Report
+
+In a few lines: what was set up, the todos added (`T list`), and two notes for the user:
+- The git hooks are turned on per clone. After cloning this repo elsewhere, run
+  `git config core.hooksPath .githooks` (`doctor` says so when they're off).
+- Personal habits that hold in every repo belong in `~/.claude/CLAUDE.md`, not here.
+- `agk update` brings in the kit's later changes.

package/template/CLAUDE.template.md

@@ -0,0 +1,36 @@
+# {{NAME}}
+
+{{WHAT IT IS, in 2-3 sentences}}
+
+This file holds what must stay true on **every** change. Everything else loads on
+demand: skills by their descriptions, a folder's rules from its own `CLAUDE.md`, and
+the docs below.
+
+| Need | Where |
+| :--- | :--- |
+| Session habits: one task per session, `/clear`, reading narrowly | `docs/workflow.md` |
+
+## Always true
+
+{{RULES: what must never break, one bullet each. Remove this section if there are none yet.}}
+
+## Working here
+
+- **Every task starts on its own branch.** `main` moves only through
+  `node scripts/merge.mjs`, after the user approves (`git` skill).
+- **Deferred work is a todo with its trigger** ("when X happens, do Y"), never a note
+  in chat (`todo` skill).
+- **Before finishing a task, check the todos**
+  (`node .claude/skills/todo/scripts/todo.mjs list --all`) for items the work
+  triggers: do them, or tell the user they're due.
+- **New rules, skills, hooks or docs for agents** follow the `agent-setup` skill: a
+  check beats a written rule, and nothing is written twice.
+
+## Commands
+
+| Command | What it does |
+| :--- | :--- |
+| `node scripts/check.mjs` | Every check in `scripts/check.json`: only what failed, then OK or FAIL (`--verbose` for full output) |
+| `node scripts/doctor.mjs` | The agent setup: size limits, dead paths, hooks turned on |
+
+**Before calling a change done:** `node scripts/check.mjs` passes.

package/template/docs/workflow.md

@@ -0,0 +1,15 @@
+# Session workflow
+
+Habits that keep sessions cheap and focused.
+
+- **One task per session.** `todo next`, finish it, `todo done`, stop.
+- **`/clear` between unrelated tasks.** Old context costs tokens on every turn.
+- **`/compact` with a focus** when a long task must go on, e.g.
+  `/compact keep the failing test names and the files changed`.
+- **`/context` and `/cost`** show what's using the window, and the money, before you
+  guess.
+- **Change `CLAUDE.md` and MCP config between sessions**, not in the middle of one:
+  either change breaks prompt caching for the rest of the session.
+- **Read narrowly.** Grep, or Read with `offset` and `limit`; a hook refuses
+  whole-file reads over 1500 lines.
+- **Run `node scripts/check.mjs`** instead of reading raw test or lint output.

package/template/dot-claude/settings.json

@@ -0,0 +1,40 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(node .claude/skills/todo/scripts/todo.mjs:*)",
+      "Bash(node scripts/check.mjs:*)",
+      "Bash(node scripts/doctor.mjs:*)"
+    ],
+    "deny": [
+      "Read(./todos/**)",
+      "Edit(./todos/**)",
+      "Write(./todos/**)",
+      "Read(./todo-archive.md)",
+      "Edit(./todo-archive.md)",
+      "Write(./todo-archive.md)",
+      "Read(./*.log)"
+    ]
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/scripts/hooks/block-big-read.mjs\""
+          }
+        ]
+      },
+      {
+        "matcher": "Bash|PowerShell",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/scripts/hooks/guard-commands.mjs\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/template/dot-claude/skills/agent-setup/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: agent-setup
+description: Where agent knowledge goes (CLAUDE.md, skills, hooks, scripts, docs, todos) and its size limits. Use when adding or changing any of them, or after a repeated mistake.
+---
+
+# Agent setup: where knowledge goes
+
+## 1. Pick the cheapest place that works
+
+| The knowledge is... | Put it in | Costs |
+| :--- | :--- | :--- |
+| A rule a machine can check | A lint rule, a git hook (`.githooks/`), a permission in `.claude/settings.json`, or a Claude hook in `scripts/hooks/` | Nothing |
+| Mechanical work done often | A script with short output: one line per problem, then OK or FAIL | Its output |
+| True for every change | The root `CLAUDE.md` | Every turn |
+| True for one folder | That folder's `CLAUDE.md` | When the agent works there |
+| A procedure for one kind of task | A skill | Its description every session; the body when used |
+| Long reference (specs, formulas, data formats) | `docs/`, listed in the root `CLAUDE.md`'s table | When read |
+| Work for later, or for when something happens | A todo with its trigger (`todo` skill) | Nothing |
+| Why a change was made | The commit message | Nothing |
+| Your own habits, true in every repo | `~/.claude/CLAUDE.md` | Every turn, in every repo |
+
+Prefer the top of the table. A written rule is a request; a check is a guarantee. When
+a rule becomes a check, keep at most one line saying why.
+
+## 2. When to add something
+
+- The same mistake twice: a rule. If a machine can check it: a check instead.
+- The same procedure explained in two sessions: a skill.
+- A command run often, with long output: a wrapper script.
+- Not before. A guardrail for something that hasn't happened yet is a todo with a
+  trigger.
+
+## 3. Size limits
+
+`node scripts/doctor.mjs` enforces them (`check` runs it).
+
+| What | Limit |
+| :--- | :--- |
+| The root `CLAUDE.md` | 800 words |
+| A folder's `CLAUDE.md` | 400 words |
+| A skill's description | 30 words, saying when to use it ("Use when ...") |
+| A `SKILL.md` | 100 lines; longer reference goes in files next to it |
+
+Change a limit in `scripts/doctor.mjs` only with the reason in the commit.
+
+## 4. Adding a skill
+
+1. Look in `.claude/skills/` first: extend a skill rather than add a near-duplicate.
+2. Write `.claude/skills/<name>/SKILL.md` with frontmatter `name` (the folder's name)
+   and `description` (what it covers, then "Use when ..."). The body is procedure:
+   steps, commands, gotchas. No history, and nothing `CLAUDE.md` already says.
+3. A script goes in the skill's `scripts/` folder. Allow it in `.claude/settings.json`
+   (`Bash(node .claude/skills/<name>/scripts/<file>:*)`), merging into the list.
+4. Don't list skills in `CLAUDE.md`: their descriptions are already in context.
+5. Run `node scripts/doctor.mjs`.
+
+## 5. Never
+
+- `@`-imports in `CLAUDE.md`: they load the whole file on every turn. Name the path in
+  backticks instead, so it's read only when needed.
+- The same fact in two places. Point to its source (the code, a doc) instead of
+  copying it: copies go stale.
+
+## 6. The kit's files
+
+agent-kit wrote the files listed in `.claude/agk.json`; change them as the repo needs.
+`agk update` brings in the kit's later changes. Where the repo changed a file, it puts
+the kit's version next to it as `<file>.kit`: merge what's new into the file, keeping
+the repo's changes, then delete the `.kit` file (`doctor` reports it until then).

package/template/dot-claude/skills/git/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: git
+description: Branching, committing, rebasing and merging. Use when starting a task, committing, or merging into main. One branch per task, files staged by name, main only with approval.
+---
+
+# Git: a branch per task, main only with approval
+
+`main` moves only through `node scripts/merge.mjs`, after the user approves. The
+pre-commit hook refuses commits on `main` and runs `node scripts/check.mjs --fast`. A
+Claude hook refuses `--no-verify` and bulk staging, and asks before merges, pushes and
+commands that discard work.
+
+## 1. Start every task on a new branch
+
+- `git switch -c <branch> main`. Names are short kebab-case `<area>-<topic>`, with the
+  todo ID first when there is one (`t-k7q3-route-cost`).
+- Follow-ups to the same task stay on its branch.
+- If the checkout is on a branch that isn't yours, or has changes you didn't make,
+  don't switch it. Work in a worktree in a sibling folder:
+  `git worktree add ../<repo>-<branch> -b <branch> main`.
+  - A worktree has no installed dependencies: install them there. Never link them
+    from the main checkout: removing the worktree deletes what the link points to.
+
+## 2. Commit
+
+1. `git branch --show-current` must print your branch. If it doesn't, someone switched
+   the checkout: stop and tell the user.
+2. `git status --short`, then stage what you changed **by name**. Leave out files you
+   didn't touch, and mention them.
+3. One logical change per commit. Todo changes go in the same commit as the work.
+4. If the hook fails, fix what it reports. Never get around it.
+
+Message:
+
+    <Area>: <what is now true, or what changed> (T-xxxx)
+
+    Why it was needed, and what a reader can't see in the diff.
+    Say what wasn't verified, when that matters.
+
+## 3. Stay on top of main
+
+After each commit: `git rebase main`. On a conflict, resolve it if both sides' intent
+is clear, rerun `node scripts/check.mjs`, then `git rebase --continue`. Otherwise
+`git rebase --abort` and ask.
+
+## 4. Merge into main: only with approval
+
+1. The branch is rebased onto `main`, and `node scripts/check.mjs` passes.
+2. Ask the user, stating the branch, its commits (`git log --oneline main..HEAD`) and
+   the checks run.
+3. Once approved, from the branch's checkout: `node scripts/merge.mjs <branch>`. It
+   refuses unless the tree is clean, the branch is on top of `main` and the checks
+   pass. Then it fast-forwards `main` and deletes the branch. From a worktree, it
+   prints how to remove the worktree instead.
+
+## With a remote
+
+Only if `git remote` prints one:
+- Branch from and rebase onto `origin/main`, after a `git fetch`.
+- Push your branch after each rebase: `git push -u origin <branch>` the first time,
+  then `git push --force-with-lease` (your branch only, never `main`).
+- After a merge, push `main` once the user agrees: `git push origin main`.
+
+## Never, without asking
+
+- `reset --hard`, `clean`, `checkout -- <file>`, `restore <file>`, `stash drop`,
+  `branch -D`. Undo committed work with `git revert`.
+- Rewrite `main` or force-push it.

package/template/dot-claude/skills/todo/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: todo
+description: The work queue, kept by a script. Use when working on, adding or reviewing todos, on "next todo", or when work must wait for a trigger.
+---
+
+# Todos: the queue, through its script
+
+`todos/` and `todo-archive.md` are the script's data. **Never read or edit them
+directly** (the settings deny it): go through the script, so the queue costs almost no
+tokens.
+
+## 1. Commands
+
+`T` stands for `node .claude/skills/todo/scripts/todo.mjs`, run from the repo root.
+
+| Command | What it does |
+| :--- | :--- |
+| `T next` | The best eligible item as its raw line, or `none` |
+| `T list [-p N] [--tag X] [--all]` | Eligible items; `--all` adds blocked ones, marked `*` |
+| `T show T-XXX` | The item's line, then its detail text if any |
+| `T add "text" [-p 1-3] [--dep T-A,T-B] [--size S\|M\|L] [--tag a,b]` | Creates an item; prints only the new ID |
+| `T set T-XXX [-p 1-3] [--dep T-A,T-B\|-] [--size S\|M\|L\|-]` | Changes priority, deps or size |
+| `T edit T-XXX "new text"` | Replaces the one-line description |
+| `T tag T-XXX a,b` | Replaces the tags (`-` clears them) |
+| `T detail T-XXX 'text'` or `--file path` (`-`: stdin) [`--append`] | Sets the detail text (replaces it unless `--append`) |
+| `T done T-XXX` | Archives it; prints `unblocked: ...` for items it freed |
+| `T rm T-XXX` | Removes it without archiving (obsolete) |
+| `T stats`, `T graph`, `T html [--out file]` | Counts, dependency tree, an HTML board |
+
+Line format: `ID | P | dep | size | tags | description`.
+
+- **Deps**: one ID, several comma-separated, or `-`. An item is eligible once none of
+  its deps are still open. Cycles are refused.
+- **IDs** are random, `T-` plus 4 characters (`T-k7q3`), never reused. Typing them is
+  case-insensitive.
+- **Tags**: lowercase, comma-separated, `-` for none. Use the project's own areas
+  (`setup`, `ui`, `data`...).
+- **Detail text** is deleted with the item by `done` and `rm`; the archive keeps only
+  the line. Put anything worth keeping in the code or the commit.
+- `next` picks the lowest P, then the oldest item.
+- Output is plain when piped, which is how Claude gets it: don't pass color flags.
+- **Quote text with single quotes.** Inside double quotes, Bash runs text between
+  backticks as a command, and PowerShell drops the backticks. For text with an
+  apostrophe, send it on stdin: `T detail <ID> --file - <<'EOF'`, the text, then `EOF`
+  (Bash); in PowerShell, write each apostrophe twice inside single quotes.
+
+## 2. Working a todo
+
+1. `T next`, then `T show <id>` if it may have detail text.
+2. If its size is L, or the description is vague, outline a plan and confirm it with
+   the user before editing.
+3. Do the work, focused on that one todo.
+4. `T done <id>`.
+5. `T add ...` for any follow-up work found, instead of growing the task.
+6. Report in 1-2 sentences, then stop. Don't start the next todo unless the user asked
+   for a batch.
+
+## 3. Deferred work
+
+Work that waits on something ("when X ships, do Y") is a todo, not a note in chat:
+
+    T add '<what>' --tag <area>
+    T detail <ID> 'Trigger: <X>. Do: <Y>. Why: <reason>.'
+
+The detail must stand alone: whoever picks it up won't have this conversation. Before
+finishing any task, `T list --all` and look for todos the work just triggered.
+
+## 4. Parallel worktrees
+
+The queue is built for several agents in their own worktrees. Each todo is its own file
+and IDs need no shared counter, so branches that touch different todos merge cleanly.
+`todo-archive.md` only grows, and `.gitattributes` merges it with `merge=union`, so
+both branches' `done` lines stay. The same todo changed on both sides is a real
+conflict: keep the right version by hand.