input-kanban 0.0.16 → 0.0.17

package/README.en.md

@@ -56,6 +56,8 @@ input-kanban submit --task "Fix the login issue and add regression tests" --labe
 
 `submit` creates a run, starts planning, dispatches all batches, and starts the final judge after all workers finish by default. The default workspace is the current directory. If `--label` is omitted, the run label is generated from the task text. It uses the same runs directory, so CLI-created runs are visible in the Web dashboard on port 8787 as long as the dashboard uses the same `--runs-dir`.
 
+If your Agent can only call the CLI, run `input-kanban guide` or `input-kanban --help` to get a friendlier execution template and control loop.
+
 `input-kanban serve` starts a lightweight background scheduler that keeps refreshing and advancing unfinished runs: it dispatches batches when a plan is ready, starts the next serial batch after the previous one completes, and starts the final judge after all batches complete. CLI `submit --auto` / `input-kanban auto <runId>` and the Web server share the same orchestrator auto-advance path, so progress no longer depends on whether a browser page is open or refreshed.
 
 To return immediately and let a background supervisor continue the auto loop, pass `-d` / `--detach`:

package/README.md

@@ -56,6 +56,8 @@ input-kanban submit --task "修复登录问题，并补充回归测试" --label
 
 `submit` 默认会创建任务批次、发起拆分、自动派发所有批次，并在全部完成后自动发起最终验收。默认 workspace 是当前目录；如果不传 `--label`，任务批次名称会从任务内容自动生成。它使用同一个 runs 目录，所以只要 8787 Web 看板也使用相同的 `--runs-dir`，CLI 创建的任务会在 Web 界面里可见。
 
+如果你的 Agent 只能调用 CLI，可以直接运行 `input-kanban guide` 或 `input-kanban --help`，拿到一版更友好的执行模板和控制循环。
+
 如果希望 Planner 拆分完成后先看一眼计划，再放行执行，可以加计划确认 Gate：
 
 ```bash

package/RELEASE_NOTES.md

@@ -1,5 +1,19 @@
 # Release Notes
 
+## v0.0.17
+
+### Highlights
+
+- Add a friendly `input-kanban guide` CLI entry that prints an agent-oriented control loop, decision rules, and ready-to-copy execution templates.
+- Extend `input-kanban --help` with a visible agent guide entry point so CLI-only agents can discover the execution flow without reading repository docs.
+- Add a small `docs/input-kanban-cli-README.md` entry page and a reusable `docs/input-kanban-cli-skill.md` execution guide for external-project reuse.
+
+### Verification
+
+- `node --test test/cli-submit.test.js` passed locally.
+- `git diff --check` passed locally.
+- Windows-native validation passed on `zhangxing_win` with `npm run check` in the Windows release-candidate working tree.
+
 ## v0.0.16
 
 ### Highlights

package/bin/input-kanban.js

@@ -7,7 +7,7 @@ import { fileURLToPath } from 'node:url';
 const PACKAGE_VERSION = JSON.parse(await fsp.readFile(new URL('../package.json', import.meta.url), 'utf8')).version;
 const VALID_RUNNERS = ['headless', 'tmux'];
 const VALID_SANDBOXES = ['read-only', 'workspace-write', 'danger-full-access'];
-const COMMANDS = new Set(['serve', 'submit', 'runs', 'status', 'result', 'retry', 'stop', 'auto']);
+const COMMANDS = new Set(['serve', 'submit', 'runs', 'status', 'result', 'retry', 'stop', 'auto', 'guide']);
 const delay = ms => new Promise(resolve => setTimeout(resolve, ms));
 const STATUS_TEXT = {
   created: '已创建', planning: '拆分中', plan_failed: '拆分失败', plan_empty: '拆分为空', planned: '已拆分',
@@ -167,6 +167,17 @@ function parseAutoArgs(argv) {
   return args;
 }
 
+function parseGuideArgs(argv) {
+  const args = { json: false, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') args.help = true;
+    else if (arg === '--json' || arg === '-j') args.json = true;
+    else throw new Error(`unknown guide argument: ${arg}`);
+  }
+  return args;
+}
+
 function parseSubmitArgs(argv) {
   const args = {
     host: '127.0.0.1', port: 8787, workspace: undefined, repo: undefined, runsDir: undefined, codexBin: undefined,
@@ -234,6 +245,7 @@ Usage:
   input-kanban [options]
   input-kanban serve [options]
   input-kanban submit [options]
+  input-kanban guide [options]
   input-kanban --version
   input-kanban runs [options]
   input-kanban status [runId] [options]
@@ -241,6 +253,9 @@ Usage:
   input-kanban retry <runId> [taskId] [options]
   input-kanban stop <runId> [options]
 
+Agent guide:
+  input-kanban guide           Print a friendly agent-oriented control loop and templates
+
 Serve options:
   --host <host>              Host to bind, default 127.0.0.1
   -p, --port <port>          Port to bind, default 8787
@@ -427,6 +442,64 @@ Options:
 `);
 }
 
+function printAgentGuide(json = false) {
+  const quickStart = [
+    'Use `input-kanban` as the execution tool.',
+    'Treat `submit` as a new task identity.',
+    'Treat `retry` as a new attempt for the same task.',
+    'Use `status` before any state-dependent action.',
+    'Use `result` for the final outcome.',
+    'Use `stop` only with a known `runId`.'
+  ];
+  const templates = [
+    'input-kanban submit --task "Implement the new gate workflow" --label "gate-workflow"',
+    'input-kanban submit --task-file task.md',
+    'input-kanban submit --task-file task.md --plan-approval',
+    'input-kanban submit --task-file task.md --detach',
+    'input-kanban status run_1234567890',
+    'input-kanban status run_1234567890 --watch',
+    'input-kanban result run_1234567890',
+    'input-kanban result run_1234567890 --copy',
+    'input-kanban retry run_1234567890',
+    'input-kanban stop run_1234567890'
+  ];
+  if (json) {
+    printJson({
+      ok: true,
+      command: 'guide',
+      title: 'Input Kanban Agent Guide',
+      quickStart,
+      templates,
+      rules: [
+        'submit = new task identity',
+        'retry = same task definition, new attempt',
+        'status = inspect before acting',
+        'result = final confirmation',
+        'stop = only with explicit runId'
+      ]
+    });
+    return;
+  }
+  console.log(`Input Kanban Agent Guide
+
+Quick start:
+${quickStart.map(item => `  - ${item}`).join('\n')}
+
+Core commands:
+  submit   Create a new run for a new task identity
+  retry    Re-attempt the same task definition with a new attempt
+  status   Inspect current progress before acting
+  result   Read the final outcome
+  stop     Halt a known run
+
+Example templates:
+${templates.map((item, index) => `  ${String(index + 1).padStart(2, '0')}. ${item}`).join('\n')}
+
+See also:
+  input-kanban --help
+`);
+}
+
 function openBrowser(url) {
   const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open';
   const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
@@ -778,6 +851,11 @@ try {
     args.json = args.json || globals.json;
     if (args.help) { printSubmitHelp(); process.exit(0); }
     await submit(args);
+  } else if (command === 'guide') {
+    const args = parseGuideArgs(rest);
+    args.json = args.json || globals.json;
+    if (args.help) { printAgentGuide(args.json); process.exit(0); }
+    printAgentGuide(args.json);
   } else if (command === 'runs') {
     const args = parseRunsArgs(rest);
     args.json = args.json || globals.json;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "input-kanban",
-  "version": "0.0.16",
+  "version": "0.0.17",
   "type": "module",
   "bin": {
     "input-kanban": "bin/input-kanban.js"