ai4kanban 0.7.0 → 0.8.0

package/README.md

@@ -65,17 +65,12 @@ akb skill install    # add it, or bring an older copy up to date
 That writes one file into `.claude/skills/kanban/` (Claude Code) and
 `.agents/skills/kanban/` (Codex): `SKILL.md`, a short note telling a coding agent the board
 is here and that `akb` owns it. The board app does the same thing from a button:
-**Configuration → Agent setup**.
+**Configuration → General**.
 
 Nothing else is copied in. The flows ship inside the command (`akb guide`), so a newer
-command is newer flows in every project at once — and the command itself stays where npm put
-it, so a project's git history never carries 350 kB of it.
-
-An agent that finds no `akb` on the PATH doesn't stop: the note's first section says what to
-run instead — the copy in this project where there is one, and otherwise `npx --yes
-ai4kanban@<the version that wrote the note>`, pinned so the rules match the board. A run
-started from the app or the CLI is told the same thing in its own words, and `akb skill`
-says it to you at the moment the note lands.
+command is newer flows in every project at once, and a project's git history never carries
+350 kB of it. An agent that finds no `akb` on the PATH doesn't stop: the note names what to
+run instead, pinned to the version that wrote it so the rules match the board.
 
 ## Update
 
@@ -86,15 +81,11 @@ npm install -g ai4kanban@latest   # a newer command
 akb update                        # a repaired board, from the project root
 ```
 
-`akb update` refreshes a skill folder that is already there — it never adds one, since not
-having it is an ordinary state now — adds whatever an older release never wrote to the
-board, clears out what it no longer writes, and prints which version you moved from and to
-with a link to everything that changed in between. Your cards, config, and memory are never
-touched.
-
-It can't do the first line to itself — replacing the file that is running is how you get
-half a command — so it checks npm and names that line when it is behind, rather than
-reporting success a release late.
+`akb update` refreshes a skill folder that is already there — it never adds one — adds
+whatever an older release never wrote to the board, clears out what it no longer writes, and
+prints which version you moved from and to with a link to everything that changed in between.
+Your cards, config, and memory are never touched. It can't do the first line to itself, so it
+checks npm and names that line when it is behind.
 
 ## Put an agent to work
 
@@ -103,7 +94,8 @@ card can be built from a terminal, over ssh, or from a script, without a chat se
 without a browser.
 
 ```bash
-akb implement 12              # build the card
+akb implement 12              # build the card, then review what was built
+akb review 12                 # judge the delivery in flight on it again
 akb refine 12                 # sharpen it until it is ready to build
 akb create "add dark mode"    # write the card(s) for it
 akb propose                   # write the next tasks
@@ -118,11 +110,10 @@ point at, and the command that closes the job.
 akb implement 12 --print      # the steps, for whoever is asking
 ```
 
-That is the mode for an agent already in a session: it does the job in the conversation
-it is already in, rather than paying for a second agent to do the job it is sitting there
-to do. Start a run when you want the work to happen on its own. `akb help runs` carries
-the whole rule, beside the commands it applies to. An agent working inside a run the board
-started always gets the printed flow, so a run can't spawn a copy of itself.
+That is the mode for an agent already in a session: it does the job where it is, rather than
+paying for a second agent to do it. Start a run when you want the work to happen on its own.
+An agent working inside a run always gets the printed flow, so a run can't spawn a copy of
+itself. `akb help runs` carries the whole rule.
 
 The run keeps working after the command returns. Watch it, or stop it, from anywhere —
 including from the board app, which drives its buttons through these same commands:
@@ -134,7 +125,7 @@ akb stop 3f2a1b04             # end one
 akb resume 3f2a1b04           # continue one that failed
 ```
 
-Which agent runs them — Claude Code, Codex, Cursor, OpenCode or DeepSeek Harness — and
+Which agent runs them — Claude Code, Codex, Cursor, OpenCode, DeepSeek Harness or ZCode — and
 what it is set to:
 
 ```bash
@@ -153,6 +144,35 @@ An API key is the one thing to leave to the user. Hand them the line rather than
 for them: a key an agent types lands in its transcript and in the shell history, and a
 saved key is never read back.
 
+## Talk to it about the board
+
+Sometimes the answer is a conversation, not a job. `akb chat` opens one about the whole
+board; `akb chat <id>` opens one about that card. It answers, and it does the board work
+you settle on in it.
+
+```bash
+akb chat "what should I build next, and why?"
+akb chat 12 "what is still unclear about this card?"
+akb chat 12 "put this in v1 and drop the last todo"   # it makes the change
+akb chat "start a build on 12"                        # it starts the run
+akb chat 12                   # the conversation so far
+akb chat 12 --clear           # forget it and start fresh
+```
+
+Chat is the kanban skill in a persistent agent session — the first prompt is only the skill
+invocation and your message, and the skill reads the current board itself. It prints the
+board-specific flow and does the work in the conversation by default; ask for a background run
+when you want another agent to take it independently.
+
+Every message is its own command, so a conversation is picked up from any terminal and
+survives closing one. The board's conversation and each card's are separate, both under
+`docs/kanban/.chats/`, on your machine and out of git.
+
+A chat is not a run: it never shows in `akb runs` and never holds a card. A change to a card a
+run is already working on is refused, and the refusal names the card and what that run is
+doing. Only an agent whose command can take a second message into its own session can hold a
+conversation; on any other, chat says so and names the agents that can.
+
 ## The manual
 
 `akb help runs` is what a coding agent reads: every command it may call — the card work,
@@ -164,19 +184,16 @@ The flows are `akb guide`:
 ```bash
 akb guide                     # every flow, one line each
 akb guide board               # how the board works: card format, layout, memory
-akb guide refine              # one card, vague to ready
+akb guide qa-loop             # settle one card's planning gaps
 akb guide plan-release        # fill a release from its goal
 ```
 
-A printed flow already carries the ones its action needs, in full, so this is for the
-rest.
+A printed flow already carries the ones its action needs, in full, so this is for the rest.
 
-A run that writes or changes a card is followed by `akb refine` on that card, started as a
-run of its own once the first one ends — so `akb create "…"`, `akb revise`, `akb resolve`,
-`akb propose` and `akb plan-release` all come back with their cards refined. Archiving or
-rejecting a card does the same for every card it was blocking that now has nothing left in
-its way. Each one is an ordinary run: it shows in `akb runs`, has its own log, and
-`akb stop` ends it.
+A run that writes or changes a card is followed by `akb refine` on that card, as a run of its
+own — so `akb create`, `akb revise`, `akb resolve`, `akb propose` and `akb plan-release` all
+come back with their cards refined. Archiving or rejecting a card does the same for every card
+it was blocking that now has nothing left in its way.
 
 ## What it won't do
 

package/bin/ai4kanban.mjs

@@ -68,12 +68,23 @@ const PROGRAM = (() => {
   if (/[\\/](_npx|dlx)[\\/]/.test(entry)) return `npx --yes ${NAME}@${VERSION}`
   const base = path.basename(entry).toLowerCase().replace(/\.(cmd|ps1|exe)$/, '')
   if (base === 'akb' || base === NAME) return 'akb'
-  // Relative to where it was typed when that is shorter and still runs — a checkout says
-  // `node cli/bin/ai4kanban.mjs`, which reads inside a sentence; an absolute path doesn't.
-  const near = path.relative(process.cwd(), entry)
-  return `node ${near && !near.startsWith('..') ? near : entry}`
+  return `node ${nearPath(entry)}`
 })()
 
+// How a path is spelled in something a person is meant to paste back.
+//
+// Relative when it is a short hop down from where the command was typed — a checkout says
+// `node cli/bin/ai4kanban.mjs`, which reads inside a sentence and is what the project's own
+// notes spell. Absolute otherwise, and absolute is the safe answer: run from `/`, a
+// relative path is the whole absolute one with its leading slash quietly removed
+// (`node Users/me/…/ai4kanban.mjs`), which runs from that one folder and nowhere else and
+// reads to everyone else like a typo.
+function nearPath(file) {
+  const near = path.relative(process.cwd(), file)
+  const shortHop = near && !near.startsWith('..') && !path.isAbsolute(near) && near.split(/[\\/]/).length <= 3
+  return shortHop ? near : file
+}
+
 // One line, when this copy isn't `akb`, for the text that spells it `akb` throughout — the
 // help, and the flows a `--print` hands over. Cheaper than rewriting either, and it holds
 // for the lines inside them that this command never wrote.
@@ -177,6 +188,13 @@ async function placeSkill(root, mode) {
   const result = installSkill(root, mode === 'update' ? 'present' : undefined, PROGRAM)
   for (const w of result.wrote) did.push(`${w.refreshed ? 'refreshed' : 'wrote'} ${w.path}/ — ${w.files} (${w.agent})`)
   for (const s of result.skipped) notes.push(`${s.path} — ${s.why}`)
+  // The commit guard (#324), which goes in wherever the skill does. The FIRST write says
+  // so, so a user who ran `akb update` for something else learns it is there before a
+  // commit refuses; a rewrite of the board's own copy is silent, the way a refresh is.
+  if (result.hook?.wrote && !result.hook.wrote.refreshed) {
+    did.push(`wrote ${result.hook.wrote.path} — refuses a commit on the branch a delivery is landing on (\`--no-verify\` gets past it)`)
+  }
+  if (result.hook?.note) notes.push(result.hook.note)
   // A project that has one agent's folder but not the other's. Update never writes a folder
   // that isn't there — a plugin install keeps the skill in a read-only cache, and a board
   // installed today has no folder at all until someone asks for one. Say the line that adds
@@ -359,6 +377,7 @@ async function cmdSkill(root, mode) {
     say(`ai4kanban ${VERSION} — the coding agent skill in ${root}`)
     say('')
     for (const folder of state.folders) say(`  ${folder.path}/ — ${sayFolder(folder)} (${folder.agent})`)
+    await sayHookState(root)
     say('')
     if (!state.installed) say(`Not installed. \`${PROGRAM} skill install\` writes it, and so does the board UI's button.`)
     else if (state.outdated) say(`Older than this command. \`${PROGRAM} skill install\` brings it up to date.`)
@@ -400,6 +419,16 @@ async function sayPathState() {
   say(`    ${GET_LINE}`)
 }
 
+// Where the commit guard stands (#324), said next to the folders an agent reads. A project
+// that is not a git repository has no hook to have, and gets no line about one.
+async function sayHookState(root) {
+  const { readCommitHook, sayCommitHook } = await rules()
+  if (typeof readCommitHook !== 'function' || typeof sayCommitHook !== 'function') return
+  const hook = readCommitHook(root)
+  if (hook.state === 'no-git') return
+  say(`  ${hook.path} — ${sayCommitHook(hook.state)}`)
+}
+
 function sayFolder(folder) {
   if (folder.state === 'absent') return 'not installed'
   if (folder.state === 'linked') return 'a symlink into a source checkout — never written over'
@@ -523,7 +552,8 @@ ${INTRO}
   akb install [--tracks a,b,c]   scaffold docs/kanban/ — the board, and nothing else
   akb skill                      whether a coding agent can drive this board
   akb skill install              add the skill: SKILL.md into .claude/skills/kanban/
-                                 and .agents/skills/kanban/
+                                 and .agents/skills/kanban/, plus the commit guard in
+                                 .git/hooks/pre-commit
   akb skill refresh              rewrite a skill that is already here, and write none
                                  that isn't — how the note learns a new spelling of the
                                  command
@@ -557,8 +587,8 @@ Put an agent to work on the board:
   akb agent                      which agent runs them, and how it is set up
 
 A run keeps working after the command returns. Add \`--print\` to any of the first four and
-nothing starts: it prints what to do instead, filled in for this board — which is how an
-agent already in a session does the job itself rather than starting a second one.
+nothing starts: it prints what to do instead, filled in for this board — which is how the
+agent you are already talking to does the job itself rather than starting a run of its own.
 
 \`akb help runs\` is the whole of it — every command a coding agent may call, and when.
 \`akb agent\` is where you pick the agent, its model and its key.
@@ -615,6 +645,10 @@ async function cmdBoard(args) {
 // command line is the command's own.
 const RUN_COMMANDS = new Set([
   'implement',
+  // The two runs a delivery makes after its build (#302). The board starts each itself;
+  // typed by hand they put a stopped delivery back in motion.
+  'review',
+  'correct',
   'run',
   'refine',
   'resolve',
@@ -622,6 +656,9 @@ const RUN_COMMANDS = new Set([
   'create',
   'propose',
   'plan-release',
+  // Write a closed version's changelog into its summary file (#232) — the run the board
+  // UI's close starts, and the one a terminal close names.
+  'changelog',
   // Finish setting the board up (#173) — the steps that read the repo and think, as one
   // run. It is a run like the rest: the board UI's button starts exactly this.
   'setup',
@@ -630,10 +667,25 @@ const RUN_COMMANDS = new Set([
   // Put a spec agent on a card — a named agent that fills one part of its spec (#187).
   'spec',
   'runs',
+  // Talking to the agent about the board, or about one card (#240). Not a run: it holds a
+  // conversation here, in this process, and starts nothing.
+  'chat',
   'log',
   'stop',
   'resume',
+  // End the DELIVERY in flight on a card and hand the card back (#301). `stop` ends one
+  // run of it; this ends the job.
+  'cancel',
+  // Throw a delivery's worktree and branch away (#303). Cancel leaves them where they are;
+  // this is the only thing that removes one.
+  'discard',
+  // Sign off the tree a delivery would land (#308), on a board that requires it. It ends
+  // nothing and starts nothing — it lets a delivery already waiting carry on.
+  'approve',
   'agent',
+  // Which account this MACHINE is signed in to Cloud as (#326). Like `guide`, it needs no
+  // board: the sign-in belongs to the machine, not to any one project.
+  'cloud',
   // The board's flows, shipped with this command rather than copied into each project.
   'guide',
   // What a started run's watcher is spawned as. Never typed by a person.