ai4kanban 0.6.0 → 0.7.0

package/README.md

@@ -24,6 +24,11 @@ without a chat session and without a browser.
 
 ## Get the command
 
+The [board app](https://ai4kanban.dev/download) brings `akb` with it — the first open puts
+it on your PATH and it updates when the app does, so if you have the app you have the
+command. Install it on its own where the app can't run — a server, a container, or a Linux
+box, whose AppImage leaves no command behind:
+
 ```bash
 npm install -g ai4kanban
 ```
@@ -60,12 +65,17 @@ 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 → Skill**.
+**Configuration → Agent setup**.
 
 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 runs `npx --yes ai4kanban@latest <command>` instead; the note says so.
+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.
 
 ## Update
 
@@ -124,7 +134,8 @@ akb stop 3f2a1b04             # end one
 akb resume 3f2a1b04           # continue one that failed
 ```
 
-Which agent runs them — Claude Code, Codex, Cursor or OpenCode — and what it is set to:
+Which agent runs them — Claude Code, Codex, Cursor, OpenCode or DeepSeek Harness — and
+what it is set to:
 
 ```bash
 akb agent                     # what runs, and how it is set up

package/bin/ai4kanban.mjs

@@ -4,8 +4,8 @@
 // `npx --yes ai4kanban@latest <command>` runs it without installing anything.
 //
 //   akb install [--tracks a,b,c]   scaffold docs/kanban/
-//   akb skill [install]            add the coding agent skill to this project, or say
-//                                  whether it is there
+//   akb skill [install|refresh]    add the coding agent skill to this project, rewrite the
+//                                  copy it has, or say whether it is there
 //   akb update                     refresh an installed skill, repair the board, and say
 //                                  the one line that puts a newer command on your path
 //   akb board <move>               the board's own bookkeeping — the agent's commands
@@ -44,6 +44,50 @@ const REPO = 'https://github.com/ai4kanban/ai4kanban'
 const GET_LINE = `npm install -g ${NAME}`
 const NEWER_LINE = `npm install -g ${NAME}@latest`
 
+// How this command was reached, spelled so what it prints can be pasted straight back.
+//
+// A global install puts it on the PATH as `akb`, and every example everywhere spells it
+// that way. It is also run as a path — `node cli/bin/ai4kanban.mjs` in a source checkout,
+// the copy inside the desktop app — and printing `akb` to a reader who has none is printing
+// a line that ends in `command not found`. Whoever typed it is right here in argv, so ask
+// that rather than guessing: only the PATH spellings are `akb`, `.mjs` never is.
+//
+// Not what's on the PATH, which is a different question with a different answer: `npx` puts
+// an `akb` on the PATH of THIS process and nothing else, so the reader would still be given
+// a line their own shell can't run. That one is spotted by the cache it runs out of, and
+// answered with the same fetch pinned to this version — never `@latest`, which is how a
+// board comes to be driven by two versions of its own rules.
+//
+// AI4KANBAN_COMMAND is how the desktop app's launcher says what it was typed as. That
+// launcher is reached as `akb` on the PATH and then runs this file by its path, so argv
+// alone would report the copy inside the app — a line no reader can paste.
+const PROGRAM = (() => {
+  const named = (process.env.AI4KANBAN_COMMAND || '').trim()
+  if (named) return named
+  const entry = process.argv[1] || ''
+  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}`
+})()
+
+// 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.
+const SPELLED = PROGRAM === 'akb' ? '' : `This copy isn't on your PATH as \`akb\` — every \`akb\` below is \`${PROGRAM}\` here.`
+
+// How the help opens: what the command is called, plus that line when it isn't called that.
+const INTRO = [
+  'Installed, it is `akb`. Without installing anything, every line below also works as\n' +
+    '`npx --yes ai4kanban@latest <command>` — the same command, fetched each time.',
+  SPELLED,
+]
+  .filter(Boolean)
+  .join('\n\n')
+
 // The memory set used to sit at the board root before it moved into `memory/`.
 const MEMORY_FILES = ['readme.md', 'goal.md', 'decisions.md', 'redesign.md', 'rejected.md']
 
@@ -127,7 +171,10 @@ async function placeSkill(root, mode) {
   for (const folder of before) {
     if (folder.state !== 'absent' && folder.state !== 'linked') rescueSkillConfig(root, path.join(root, folder.path))
   }
-  const result = installSkill(root, mode === 'update' ? 'present' : undefined)
+  // How this command was typed goes into the note: an install run through `npx` is the one
+  // case the rules can't read off the machine, because npx's `akb` is on this process's
+  // PATH and no shell the agent will ever open.
+  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}`)
   // A project that has one agent's folder but not the other's. Update never writes a folder
@@ -282,27 +329,41 @@ function cmdInstall(root, tracks) {
   say('That is the board. Nothing was written outside docs/kanban/.')
   say('')
   say('To drive this board from your coding agent, add the skill — from the button in the')
-  say('board UI (Configuration → Skill), or here:')
+  say('board UI (Configuration → Agent setup), or here:')
   say('')
-  say('    akb skill')
+  say(`    ${PROGRAM} skill`)
 }
 
-// Add the skill to a project, or say where it stands. The whole move belongs to the built
-// rules; this prints what they did.
-async function cmdSkill(root, install) {
+// Add the skill to a project, rewrite the copy it has, or say where it stands. The whole
+// move belongs to the built rules; this prints what they did.
+//
+// `refresh` writes no folder that isn't already there. It is how a note learns a new
+// spelling of the command without a project gaining a skill it never asked for — the
+// desktop app runs it right after putting `akb` on the PATH, so the note stops naming the
+// copy inside the app.
+async function cmdSkill(root, mode) {
   const { readSkillState } = await rules()
   if (typeof readSkillState !== 'function') {
     fail('this copy of the board rules is too old to install the skill — `npm install -g ai4kanban@latest`')
   }
-  if (!install) {
+  if (mode === 'refresh') {
+    const { result } = await placeSkill(root, 'update')
+    sayDid()
+    sayNotes()
+    if (!result.ok && result.error) fail(result.error)
+    if (!result.wrote.length) say('No skill in this project — nothing to rewrite.')
+    return
+  }
+  if (!mode) {
     const state = readSkillState(root)
     say(`ai4kanban ${VERSION} — the coding agent skill in ${root}`)
     say('')
     for (const folder of state.folders) say(`  ${folder.path}/ — ${sayFolder(folder)} (${folder.agent})`)
     say('')
-    if (!state.installed) say('Not installed. `akb skill install` writes it, and so does the board UI\'s button.')
-    else if (state.outdated) say('Older than this command. `akb skill install` brings it up to date.')
+    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.`)
     else say('Up to date. Your coding agent can drive this board.')
+    await sayPathState()
     return
   }
   say(`ai4kanban ${VERSION} — adding the coding agent skill to ${root}`)
@@ -312,14 +373,33 @@ async function cmdSkill(root, install) {
   sayNotes()
   if (!result.ok) fail(result.error || 'nothing was written')
   say('')
-  say('The flows the agent works by ship with the command — `akb guide` — so they upgrade')
-  say('with it and no copy in this repo can fall behind.')
+  say(`The flows the agent works by ship with the command — \`${PROGRAM} guide\` — so they`)
+  say('upgrade with it and no copy in this repo can fall behind.')
+  await sayPathState()
   say('')
   say('Now say this to your coding agent to try it:')
   say('')
   say(`    ${SETUP_INSTRUCTION}`)
 }
 
+// Whether the agent that reads the note it just got will find the command the note tells it
+// to type. Said here, where the skill lands, rather than left for the agent's first board
+// command to discover — that one comes back `command not found`, and an agent that meets
+// that mid-task stops and asks instead of doing the work.
+//
+// The note itself carries the fallback, so nothing is broken either way. This is so the
+// user knows what their agent is about to do, and what one line would spare it.
+async function sayPathState() {
+  const { readCommandState } = await rules()
+  const command = typeof readCommandState === 'function' ? readCommandState() : null
+  if (!command || command.onPath) return
+  say('')
+  say('There is no `akb` on your PATH. The note tells your agent what to run instead — the')
+  say(`copy in this project, or \`npx --yes ${NAME}@${VERSION}\`. One line makes it direct:`)
+  say('')
+  say(`    ${GET_LINE}`)
+}
+
 function sayFolder(folder) {
   if (folder.state === 'absent') return 'not installed'
   if (folder.state === 'linked') return 'a symlink into a source checkout — never written over'
@@ -438,13 +518,15 @@ const HELP = `ai4kanban ${VERSION} — set up and update the AI4Kanban board.
 Get the command:  ${GET_LINE}
 Move to a newer one:  ${NEWER_LINE}
 
-Installed, it is \`akb\`. Without installing anything, every line below also works as
-\`npx --yes ai4kanban@latest <command>\` — the same command, fetched each time.
+${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 and kanban.mjs into
-                                 .claude/skills/kanban/ and .agents/skills/kanban/
+  akb skill install              add the skill: SKILL.md into .claude/skills/kanban/
+                                 and .agents/skills/kanban/
+  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
   akb update                     refresh an installed skill, repair a board written by an
                                  older version, and say if a newer command is out
   akb version                    print this version
@@ -456,7 +538,7 @@ Options
 
 Installing writes the board and nothing outside docs/kanban/. Driving that board from a
 coding agent is a later extra — \`akb skill install\`, or the button in the board UI under
-Configuration → Skill. The flows the agent works by are not copied anywhere either: they
+Configuration → Agent setup. The flows the agent works by are not copied anywhere either: they
 ship inside this command (\`akb guide\`), so updating the command updates every flow in
 every project at once.
 
@@ -522,9 +604,9 @@ function parse(argv) {
 async function cmdBoard(args) {
   const { runBoard } = await rules()
   return runBoard(args, {
-    program: 'akb board',
+    program: `${PROGRAM} board`,
     style: 'board',
-    installHint: '`akb install`',
+    installHint: `\`${PROGRAM} install\``,
   })
 }
 
@@ -545,6 +627,8 @@ const RUN_COMMANDS = new Set([
   'setup',
   'archive',
   'reject',
+  // Put a spec agent on a card — a named agent that fills one part of its spec (#187).
+  'spec',
   'runs',
   'log',
   'stop',
@@ -561,7 +645,7 @@ async function cmdRun(args) {
   if (typeof runAgent !== 'function') {
     fail('this copy of the board rules is too old to run agents — `npm install -g ai4kanban@latest`, then `akb update`')
   }
-  return runAgent(args, { program: 'akb', installHint: '`akb install`' })
+  return runAgent(args, { program: PROGRAM, installHint: `\`${PROGRAM} install\`` })
 }
 
 async function main() {
@@ -601,7 +685,7 @@ async function main() {
     // one on purpose — the same rule the run commands follow, where the move that changes
     // something is asked for by name.
     case 'skill':
-      return cmdSkill(opts.dir, rest[1] === 'install')
+      return cmdSkill(opts.dir, rest[1] === 'install' ? 'install' : rest[1] === 'refresh' ? 'refresh' : null)
     case 'update':
       return cmdUpdate(opts.dir)
     case 'version':