input-kanban 0.0.16 → 0.0.18

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', 'install-skill']);
 const delay = ms => new Promise(resolve => setTimeout(resolve, ms));
 const STATUS_TEXT = {
   created: '已创建', planning: '拆分中', plan_failed: '拆分失败', plan_empty: '拆分为空', planned: '已拆分',
@@ -167,6 +167,33 @@ 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 parseInstallSkillArgs(argv) {
+  const args = { provider: undefined, targetDir: undefined, force: false, dryRun: false, json: false, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    const next = () => argv[++i];
+    if (arg === '--help' || arg === '-h') args.help = true;
+    else if (arg === '--json' || arg === '-j') args.json = true;
+    else if (arg === '--target-dir') args.targetDir = next();
+    else if (arg === '--force') args.force = true;
+    else if (arg === '--dry-run') args.dryRun = true;
+    else if (!arg.startsWith('-') && !args.provider) args.provider = arg;
+    else throw new Error(`unknown install-skill 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 +261,8 @@ Usage:
   input-kanban [options]
   input-kanban serve [options]
   input-kanban submit [options]
+  input-kanban guide [options]
+  input-kanban install-skill codex [options]
   input-kanban --version
   input-kanban runs [options]
   input-kanban status [runId] [options]
@@ -241,6 +270,11 @@ 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
+  input-kanban install-skill codex
+                               Install bundled input-kanban-prepare skill for Codex
+
 Serve options:
   --host <host>              Host to bind, default 127.0.0.1
   -p, --port <port>          Port to bind, default 8787
@@ -283,6 +317,12 @@ Stop options:
   --reason <text>            Stop reason stored in run state
   -j, --json                 Emit JSON output instead of human text
 
+Install skill options:
+  --target-dir <path>        Codex skills root, default $CODEX_SKILLS_DIR or ~/.codex/skills
+  --dry-run                  Print the planned install target without copying files
+  --force                    Replace an existing installed skill directory
+  -j, --json                 Emit JSON output instead of human text
+
 Submit options:
   --workspace <path>         Target workspace, default current directory
   -r, --repo <path>          Alias for --workspace
@@ -427,6 +467,94 @@ Options:
 `);
 }
 
+function printInstallSkillHelp() {
+  console.log(`input-kanban install-skill
+
+Usage:
+  input-kanban install-skill codex
+  input-kanban install-skill codex --target-dir ~/.codex/skills
+  input-kanban install-skill codex --dry-run
+  input-kanban --json install-skill codex
+
+Options:
+  --target-dir <path>        Codex skills root, default $CODEX_SKILLS_DIR or ~/.codex/skills
+  --dry-run                  Print the planned install target without copying files
+  --force                    Replace an existing installed skill directory
+  -j, --json                 Emit JSON output instead of human text
+`);
+}
+
+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.',
+    'If the task came from an external chat, prepare a structured `task.md` first.',
+    '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,
+      handoffSections: ['Goal', 'Acceptance Criteria', 'Expected Artifacts', 'Context References', 'Risks'],
+      skillInstall: 'input-kanban install-skill codex',
+      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
+
+Preparation before submit:
+  - Goal
+  - Acceptance Criteria
+  - Expected Artifacts
+  - Context References
+  - Risks
+
+Install bundled prepare skill:
+  input-kanban install-skill codex
+
+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];
@@ -679,6 +807,55 @@ async function copyToClipboard(text) {
   throw new Error(`无法复制到剪贴板：${lastError?.message || '未找到可用剪贴板命令'}`);
 }
 
+function homeDir() {
+  if (process.env.HOME) return process.env.HOME;
+  if (process.env.USERPROFILE) return process.env.USERPROFILE;
+  if (process.env.HOMEDRIVE && process.env.HOMEPATH) return `${process.env.HOMEDRIVE}${process.env.HOMEPATH}`;
+  return '';
+}
+
+function defaultCodexSkillsDir() {
+  if (process.env.CODEX_SKILLS_DIR) return path.resolve(process.env.CODEX_SKILLS_DIR);
+  const home = homeDir();
+  if (!home) throw new Error('cannot determine home directory; pass --target-dir');
+  return path.join(home, '.codex', 'skills');
+}
+
+async function pathExists(filePath) {
+  try { await fsp.access(filePath); return true; }
+  catch { return false; }
+}
+
+async function installSkill(args) {
+  const provider = String(args.provider || '').toLowerCase();
+  if (!provider) throw new Error('install-skill requires a provider, currently: codex');
+  if (provider !== 'codex') throw new Error(`unsupported skill provider: ${args.provider}; expected codex`);
+  const sourceDir = fileURLToPath(new URL('../skills/input-kanban-prepare', import.meta.url));
+  const skillsRoot = args.targetDir ? path.resolve(args.targetDir) : defaultCodexSkillsDir();
+  const targetDir = path.join(skillsRoot, 'input-kanban-prepare');
+  const exists = await pathExists(targetDir);
+  const payload = { ok: true, command: 'install-skill', provider, skill: 'input-kanban-prepare', sourceDir, skillsRoot, targetDir, dryRun: !!args.dryRun, installed: false, replaced: false };
+  if (args.dryRun) {
+    if (args.json) { printJson(payload); return; }
+    console.log(`Skill: input-kanban-prepare`);
+    console.log(`Provider: codex`);
+    console.log(`Source: ${sourceDir}`);
+    console.log(`Target: ${targetDir}`);
+    console.log('Dry run: no files copied');
+    return;
+  }
+  if (exists && !args.force) throw new Error(`skill already exists: ${targetDir}; pass --force to replace it`);
+  await fsp.mkdir(skillsRoot, { recursive: true });
+  if (exists && args.force) await fsp.rm(targetDir, { recursive: true, force: true });
+  await fsp.cp(sourceDir, targetDir, { recursive: true });
+  payload.installed = true;
+  payload.replaced = exists && !!args.force;
+  if (args.json) { printJson(payload); return; }
+  console.log(`已安装 Codex skill: input-kanban-prepare`);
+  console.log(`位置: ${targetDir}`);
+  console.log('在 Codex 对话中可尝试使用：use input-kanban-prepare skill');
+}
+
 async function result(args) {
   applyRuntimeEnv(args);
   const runId = args.runId || await latestRunId();
@@ -778,6 +955,16 @@ 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 === 'install-skill') {
+    const args = parseInstallSkillArgs(rest);
+    args.json = args.json || globals.json;
+    if (args.help) { printInstallSkillHelp(); process.exit(0); }
+    await installSkill(args);
   } else if (command === 'runs') {
     const args = parseRunsArgs(rest);
     args.json = args.json || globals.json;

package/docs/input-kanban-cli-README.md

@@ -0,0 +1,41 @@
+# Input Kanban CLI Usage
+
+This page is only the entry point.
+
+Before using `input-kanban` from another project, read:
+
+- `docs/input-kanban-cli-skill.md`
+- `docs/input-kanban-prepare.md` when the task comes from an external Agent conversation
+
+## What this is for
+
+- Controlled execution through the `input-kanban` CLI
+- Structured handoff from external Agent conversations
+- Status checks, retry handling, result retrieval, and stop control
+- Agent usage in a project that needs stable task execution
+
+## What this is not for
+
+- Task decomposition
+- Final acceptance decisions
+- Replacing external gate checks
+
+## Install the bundled prepare skill
+
+```bash
+input-kanban install-skill codex
+```
+
+Use `--target-dir` if your Codex skills root is not `~/.codex/skills`:
+
+```bash
+input-kanban install-skill codex --target-dir /path/to/codex/skills
+```
+
+## Quick rule
+
+- Use `submit` for a new task identity
+- Use `retry` for the same task definition with a new attempt
+- Use `status` before state-dependent actions
+- Use `result` for final confirmation
+- Use `stop` only with an explicit `runId`

package/docs/input-kanban-cli-skill.md

@@ -0,0 +1,241 @@
+# Input Kanban CLI Skill Draft
+
+## Purpose
+
+Use the `input-kanban` CLI as the execution tool for tasks that have already been decomposed and accepted externally. This skill is for controlled execution, status checks, retry handling, and result retrieval. It is not responsible for task decomposition or final acceptance decisions.
+
+## Core Principles
+
+- Treat `input-kanban` as the execution surface, not the source of truth for decomposition or acceptance.
+- Prefer updating or retrying an existing run instead of creating a new run when the task definition is the same.
+- Keep task identity stable and use attempts to represent re-execution.
+- Use `status`, `result`, and `stop` for observation and control.
+- Do not rely on the model alone to declare completion.
+
+## Before `submit`: Prepare the Handoff
+
+If the task came from an external Agent conversation, prepare a structured `task.md` first. Prefer these sections:
+
+- `Goal`
+- `Acceptance Criteria`
+- `Expected Artifacts`
+- `Context References`
+- `Risks`
+
+Use `skills/input-kanban-prepare/SKILL.md` when an Agent needs a stricter preparation workflow.
+
+## When to Use `submit`
+
+Use `submit` only when a new task identity is needed.
+
+Examples:
+
+- The task goal changed.
+- The workspace or scope changed materially.
+- You intentionally want to start a new run with a clean history.
+
+Recommended forms:
+
+```bash
+input-kanban submit --task "..."
+input-kanban submit --task-file task.md
+input-kanban submit --task-file task.md --plan-approval
+```
+
+## When to Use `retry`
+
+Use `retry` when the task is the same, but the previous execution did not pass a gate or failed to complete correctly.
+
+Examples:
+
+- Planner output was invalid.
+- A worker failed or was marked unknown.
+- The final judge needs another attempt after a blocking issue is resolved.
+
+Recommended forms:
+
+```bash
+input-kanban retry <runId>
+input-kanban retry <runId> <taskId>
+```
+
+Retry should be treated as a new execution attempt for the same task definition, not as an overwrite of the prior attempt.
+
+## When to Use `status`
+
+Use `status` whenever you need to know the current state before acting.
+
+Recommended forms:
+
+```bash
+input-kanban status <runId>
+input-kanban status <runId> --watch
+input-kanban --json status <runId>
+```
+
+Use `--json` when another tool or agent needs structured output.
+
+## When to Use `result`
+
+Use `result` only after the run reaches a terminal state or when a final outcome is needed for review.
+
+Recommended forms:
+
+```bash
+input-kanban result <runId>
+input-kanban --json result <runId>
+input-kanban result <runId> --copy
+```
+
+Prefer the persisted judge result over the model's own summary.
+
+## When to Use `stop`
+
+Use `stop` when execution should halt immediately.
+
+Recommended form:
+
+```bash
+input-kanban stop <runId>
+```
+
+Only stop an explicitly named run. Never stop by guesswork.
+
+## Suggested Control Loop
+
+1. Discover active work:
+
+```bash
+input-kanban --json runs --active
+```
+
+2. Inspect a run:
+
+```bash
+input-kanban --json status <runId>
+```
+
+3. If blocked or failed, decide whether to retry or stop.
+4. If retry is appropriate, call `retry` on the same run.
+5. If the task is complete, fetch the final result:
+
+```bash
+input-kanban --json result <runId>
+```
+
+## Decision Rules
+
+- Use `submit` only for a new task identity.
+- Use `retry` for the same task definition with a new execution attempt.
+- Use `status` before any action that depends on current state.
+- Use `result` for final confirmation.
+- Use `stop` only with a known `runId`.
+
+## Safety Rules
+
+- Do not create a new run just to recover from a failed attempt if the task definition has not changed.
+- Do not treat a failed execution as a successful result.
+- Do not let the model self-approve completion without external evidence.
+- Prefer preserving history and attempt lineage.
+
+## Practical Guidance
+
+- If the task is still the same, keep the task identity stable and create a new attempt.
+- If the task meaning changed, start a new run.
+- If the run is blocked, surface the warning and wait for external intervention or a retry decision.
+- If the run is already terminal, do not mutate it in place.
+
+## Example Patterns
+
+### New task
+
+```bash
+input-kanban submit --task "Refactor the task scheduler to support gates" --label "Scheduler gate refactor"
+```
+
+### Retry the same task
+
+```bash
+input-kanban retry run_1234567890
+```
+
+### Check progress
+
+```bash
+input-kanban status run_1234567890 --watch
+```
+
+### Get final outcome
+
+```bash
+input-kanban result run_1234567890 --copy
+```
+
+## Example Templates
+
+### 1. Submit a new task from inline text
+
+```bash
+input-kanban submit --task "Implement the new gate workflow" --label "gate-workflow"
+```
+
+### 2. Submit a task from a file
+
+```bash
+input-kanban submit --task-file task.md
+```
+
+### 3. Submit with plan approval enabled
+
+```bash
+input-kanban submit --task-file task.md --plan-approval
+```
+
+### 4. Submit detached for background execution
+
+```bash
+input-kanban submit --task-file task.md --detach
+```
+
+### 5. Check a run once
+
+```bash
+input-kanban status run_1234567890
+```
+
+### 6. Watch a run until it changes
+
+```bash
+input-kanban status run_1234567890 --watch
+```
+
+### 7. Inspect the final result
+
+```bash
+input-kanban result run_1234567890
+```
+
+### 8. Copy the final result for handoff
+
+```bash
+input-kanban result run_1234567890 --copy
+```
+
+### 9. Retry the whole run
+
+```bash
+input-kanban retry run_1234567890
+```
+
+### 10. Stop a known run immediately
+
+```bash
+input-kanban stop run_1234567890
+```
+
+## Notes for Agent Behavior
+
+- Prefer stable task identity over repeated recreation.
+- Prefer attempt lineage over overwriting history.
+- Treat gates as external decisions, not as assumptions.
+- When in doubt, ask for clarification before creating a new run.

package/docs/input-kanban-prepare.md

@@ -0,0 +1,93 @@
+# Preparing Tasks for Input Kanban
+
+Use this guide when a task starts in an external Agent conversation and should be handed off to `input-kanban` for execution.
+
+The goal is not to make Input Kanban do all planning from a vague prompt. The goal is to give it a clear execution contract so the planner, workers, and final judge have better inputs.
+
+## Recommended Flow
+
+1. Use the external Agent conversation to clarify the goal, scope, risks, and acceptance criteria.
+2. Convert the discussion into a structured `task.md`.
+3. Submit the task with plan approval:
+
+```bash
+input-kanban submit --task-file task.md --plan-approval
+```
+
+4. Review the generated plan before dispatching workers.
+5. Use `status`, `result`, `retry`, and `stop` to control execution.
+
+## Minimal `task.md` Structure
+
+```markdown
+# Task
+
+## Goal
+
+Describe the desired outcome in one or two concrete paragraphs.
+
+## Non-Goals
+
+- List what should not be changed.
+
+## Acceptance Criteria
+
+- [ ] Criterion that can be tested, inspected, or verified.
+- [ ] Another criterion.
+
+## Expected Artifacts
+
+- Path: `relative/or/absolute/path`
+  Verify: command, inspection step, or expected content.
+
+## Context References
+
+- `path/to/spec.md`
+- `path/to/relevant/file.ts`
+
+## Execution Hints
+
+### Suggested Batches
+
+- Batch: first safe step
+  Reason: why this is an execution barrier
+  Max parallel: 1
+  Tasks:
+    - concrete worker instruction
+
+## Risks and Assumptions
+
+- Known risk, assumption, or unresolved detail.
+```
+
+## Good Handoff Checklist
+
+- The goal is specific.
+- The scope is bounded.
+- Acceptance criteria are checkable.
+- Expected artifacts include verification methods.
+- Context references point to real material.
+- Batch hints explain dependencies or safety reasons.
+- Risks and assumptions are visible.
+
+## Skill Template
+
+A reusable skill draft is available at:
+
+```text
+skills/input-kanban-prepare/SKILL.md
+```
+
+After installing the npm package, you can install the bundled skill for Codex:
+
+```bash
+input-kanban install-skill codex
+```
+
+Use `--target-dir` if your Codex skills root is custom:
+
+```bash
+input-kanban install-skill codex --target-dir /path/to/codex/skills
+```
+
+Use it in external Agent tools when you want the Agent to prepare a better `task.md` before invoking Input Kanban.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "input-kanban",
-  "version": "0.0.16",
+  "version": "0.0.18",
   "type": "module",
   "bin": {
     "input-kanban": "bin/input-kanban.js"
@@ -15,6 +15,8 @@
     "bin",
     "src",
     "public",
+    "docs",
+    "skills",
     "README.md",
     "README.en.md",
     "RELEASE_NOTES.md",