kelocan 0.1.0

package/dist/login.js

@@ -0,0 +1,93 @@
+import { execFile } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+import { platform } from "node:os";
+import { apiBase, readConfig, webBase, writeConfig } from "./config.js";
+import { CliError } from "./errors.js";
+import { errLine, line } from "./output.js";
+const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
+function openBrowser(url) {
+    const cmd = platform() === "darwin" ? "open" : platform() === "win32" ? "cmd" : "xdg-open";
+    const args = platform() === "win32" ? ["/c", "start", "", url] : [url];
+    const child = execFile(cmd, args, () => { });
+    child.unref();
+}
+/** Verify an API key against GET /users/me. Returns the user on success. */
+export async function verifyKey(base, key) {
+    let res;
+    try {
+        res = await fetch(`${base}/users/me`, {
+            headers: { Authorization: `Bearer ${key}` },
+        });
+    }
+    catch (e) {
+        throw new CliError(`Cannot reach Kelocan server at ${base}: ${e instanceof Error ? e.message : e}`, 3);
+    }
+    const body = (await res.json().catch(() => null));
+    if (!res.ok || !body?.data) {
+        const msg = body?.error?.message ?? body?.message ?? res.statusText;
+        if (res.status === 401 || res.status === 403) {
+            throw new CliError(`API key rejected by server: ${msg}`, 2);
+        }
+        throw new CliError(`Login check failed: ${msg}`, res.status >= 500 ? 3 : 1);
+    }
+    return body.data;
+}
+/** Browser loopback flow: serve /callback on 127.0.0.1, open {web}/cli/authorize. */
+export async function browserLogin(name) {
+    const state = randomBytes(24).toString("hex");
+    const result = await new Promise((resolve, reject) => {
+        const server = createServer((req, res) => {
+            const url = new URL(req.url ?? "/", "http://127.0.0.1");
+            if (url.pathname !== "/callback") {
+                res.writeHead(404).end("Not found");
+                return;
+            }
+            const key = url.searchParams.get("key");
+            const cbState = url.searchParams.get("state");
+            if (!key || cbState !== state) {
+                res.writeHead(400, { "Content-Type": "text/html" }).end("<h1>Kelocan CLI</h1><p>Invalid callback (state mismatch). You can close this tab.</p>");
+                return;
+            }
+            res.writeHead(200, { "Content-Type": "text/html" }).end("<h1>Kelocan CLI</h1><p>Authorization complete — you can close this tab and return to the terminal.</p>");
+            resolve({ key });
+            server.close();
+        });
+        server.on("error", (e) => reject(new CliError(`Cannot start local callback server: ${e.message}`, 3)));
+        server.listen(0, "127.0.0.1", () => {
+            const addr = server.address();
+            if (!addr || typeof addr === "string") {
+                reject(new CliError("Cannot determine callback port", 3));
+                return;
+            }
+            const port = addr.port;
+            const authUrl = `${webBase()}/cli/authorize?port=${port}&state=${state}` +
+                `&name=${encodeURIComponent(name)}`;
+            line(`Opening browser to authorize this device...`);
+            line(`If it does not open, visit:\n${authUrl}\n`);
+            openBrowser(authUrl);
+        });
+        setTimeout(() => {
+            server.close();
+            reject(new CliError("Login timed out after 5 minutes", 1));
+        }, LOGIN_TIMEOUT_MS).unref();
+    });
+    return result;
+}
+export async function saveLogin(opts) {
+    // Persist URL settings first so apiBase()/webBase() resolve correctly.
+    const config = readConfig();
+    if (opts.url)
+        config.url = opts.url.replace(/\/+$/, "").replace(/\/api\/v1$/, "");
+    if (opts.webUrl)
+        config.web_url = opts.webUrl;
+    writeConfig(config);
+    const base = apiBase(config);
+    const user = await verifyKey(base, opts.apiKey);
+    config.api_key = opts.apiKey;
+    writeConfig(config);
+    return user;
+}
+export function warnNoKey() {
+    errLine("hint: run `kelocan login` to authenticate");
+}

package/dist/output.js

@@ -0,0 +1,52 @@
+import { flagBool, flagStr } from "./args.js";
+export function outputOpts(args) {
+    const fields = flagStr(args.flags, "fields")
+        ?.split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    return { json: flagBool(args.flags, "json"), fields };
+}
+function pick(item, fields) {
+    if (item === null || typeof item !== "object")
+        return item;
+    const src = item;
+    const out = {};
+    for (const f of fields)
+        out[f] = src[f];
+    return out;
+}
+export function emit(data, opts, text) {
+    if (opts.json) {
+        let out = data;
+        if (opts.fields?.length) {
+            out = Array.isArray(data)
+                ? data.map((d) => pick(d, opts.fields))
+                : pick(data, opts.fields);
+        }
+        process.stdout.write(JSON.stringify(out, null, 2) + "\n");
+        return;
+    }
+    if (opts.fields?.length && data !== null && typeof data === "object") {
+        // --fields without --json: print values, one per line (per item).
+        const items = Array.isArray(data) ? data : [data];
+        for (const item of items) {
+            const src = item;
+            process.stdout.write(opts.fields.map((f) => formatValue(src[f])).join("\t") + "\n");
+        }
+        return;
+    }
+    text();
+}
+export function formatValue(v) {
+    if (v === null || v === undefined)
+        return "";
+    if (typeof v === "object")
+        return JSON.stringify(v);
+    return String(v);
+}
+export function line(s) {
+    process.stdout.write(s + "\n");
+}
+export function errLine(s) {
+    process.stderr.write(s + "\n");
+}

package/dist/resolve.js

@@ -0,0 +1,74 @@
+import { request } from "./api.js";
+import { usageError } from "./errors.js";
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const WORKFLOW_ROLES = ["backlog", "active", "review", "done"];
+export function isUuid(s) {
+    return UUID_RE.test(s);
+}
+/** Resolve a board reference: UUID or (case-insensitive) name. */
+export async function resolveBoard(ref) {
+    if (isUuid(ref)) {
+        return request(`/boards/${ref}`);
+    }
+    const boards = await request("/boards");
+    const matches = boards.filter((b) => b.name.toLowerCase() === ref.toLowerCase());
+    if (matches.length === 1)
+        return request(`/boards/${matches[0].id}`);
+    if (matches.length > 1) {
+        throw usageError(`Ambiguous board name "${ref}". Candidates:\n` +
+            matches.map((b) => `  ${b.id}  ${b.name}`).join("\n") +
+            `\nUse the UUID instead.`);
+    }
+    const names = boards.map((b) => b.name).join(", ") || "(none)";
+    throw usageError(`Board "${ref}" not found. Available boards: ${names}`);
+}
+/** Resolve a column reference inside a board: UUID, name, or workflow role. */
+export function resolveColumn(board, ref) {
+    const columns = board.columns ?? [];
+    if (isUuid(ref)) {
+        const col = columns.find((c) => c.id.toLowerCase() === ref.toLowerCase());
+        if (!col)
+            throw usageError(`Column ${ref} not found on board "${board.name}".`);
+        return col;
+    }
+    const lower = ref.toLowerCase();
+    if (WORKFLOW_ROLES.includes(lower)) {
+        const col = columns.find((c) => c.workflow_role === lower);
+        if (!col) {
+            const roles = columns.map((c) => `${c.name} (${c.workflow_role})`).join(", ");
+            throw usageError(`No column with workflow role "${lower}" on board "${board.name}". Columns: ${roles}`);
+        }
+        return col;
+    }
+    const matches = columns.filter((c) => c.name.toLowerCase() === lower);
+    if (matches.length === 1)
+        return matches[0];
+    if (matches.length > 1) {
+        throw usageError(`Ambiguous column "${ref}". Candidates: ` +
+            matches.map((c) => `${c.id} (${c.workflow_role})`).join(", "));
+    }
+    const names = columns.map((c) => `${c.name} [${c.workflow_role}]`).join(", ");
+    throw usageError(`Column "${ref}" not found on board "${board.name}". Valid columns: ${names}`);
+}
+/** Resolve label refs (name or UUID) to IDs using the board's label list. */
+export async function resolveLabels(boardId, refs) {
+    if (!refs.length)
+        return [];
+    const labels = await request(`/boards/${boardId}/labels`);
+    return refs.map((ref) => {
+        if (isUuid(ref)) {
+            const hit = labels.find((l) => l.id.toLowerCase() === ref.toLowerCase());
+            if (!hit)
+                throw usageError(`Label ${ref} not found on board.`);
+            return hit.id;
+        }
+        const hits = labels.filter((l) => l.name.toLowerCase() === ref.toLowerCase());
+        if (hits.length === 1)
+            return hits[0].id;
+        if (hits.length > 1) {
+            throw usageError(`Ambiguous label "${ref}". Candidates: ${hits.map((l) => l.id).join(", ")}`);
+        }
+        const names = labels.map((l) => l.name).join(", ") || "(none)";
+        throw usageError(`Label "${ref}" not found. Available labels: ${names}`);
+    });
+}

package/dist/setup.js

@@ -0,0 +1,222 @@
+import { createInterface } from "node:readline";
+import { hostname } from "node:os";
+import { agentById, detectAll, } from "./agents.js";
+import { apiKey } from "./config.js";
+import { runDoctor } from "./doctor.js";
+import { usageError } from "./errors.js";
+import { installAgent, installMcpConfig, mcpUrl, probeMcp, uninstallMcpConfig, } from "./install.js";
+import { browserLogin, saveLogin } from "./login.js";
+import { emit, errLine, line, outputOpts } from "./output.js";
+import { flagBool, flagStr } from "./args.js";
+import { request } from "./api.js";
+import { installSkills, removeSkills } from "./skills.js";
+// ---------- small prompt helpers ----------
+function ask(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}
+function isTty() {
+    return Boolean(process.stdin.isTTY && process.stderr.isTTY);
+}
+function parseAgentList(raw) {
+    return raw
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean)
+        .map((s) => agentById(s).id);
+}
+function parseAuth(args, fallback = "oauth") {
+    const a = flagStr(args.flags, "auth");
+    if (!a)
+        return fallback;
+    if (a !== "oauth" && a !== "api-key") {
+        throw usageError(`Invalid --auth "${a}". Valid: oauth | api-key`);
+    }
+    return a;
+}
+function resolveTargets(args, all) {
+    const raw = flagStr(args.flags, "agent");
+    if (!raw) {
+        throw usageError(`Missing --agent <name|all>. Valid agents: ${all.map((d) => d.def.id).join(", ")}, all`);
+    }
+    if (raw === "all")
+        return all;
+    const ids = new Set(parseAgentList(raw));
+    return all.filter((d) => ids.has(d.def.id));
+}
+// ---------- kelocan init ----------
+export async function cmdInit(args) {
+    const nonInteractive = flagStr(args.flags, "agent") !== undefined || !isTty();
+    const authFlag = flagStr(args.flags, "auth");
+    line("Kelocan agent setup — installs the kelocan MCP server + agent skills.\n");
+    // 1. login
+    if (!apiKey()) {
+        const inlineKey = flagStr(args.flags, "api-key");
+        if (inlineKey) {
+            const user = await saveLogin({ apiKey: inlineKey });
+            line(`Logged in as ${user.name}`);
+        }
+        else if (!nonInteractive || flagBool(args.flags, "login")) {
+            if (nonInteractive) {
+                throw usageError("Not authenticated. Run `kelocan login` first (or pass --api-key klc_...).");
+            }
+            const { key } = await browserLogin(flagStr(args.flags, "name") ?? hostname());
+            const user = await saveLogin({ apiKey: key });
+            line(`Logged in as ${user.name}`);
+        }
+        else {
+            throw usageError("Not authenticated. Run `kelocan login` first (or pass --api-key).");
+        }
+    }
+    else {
+        const user = await request("/users/me");
+        line(`Logged in as ${user.name} <${user.email ?? ""}>`);
+    }
+    // 2. pick agents
+    const all = detectAll();
+    let targets;
+    const agentFlag = flagStr(args.flags, "agent");
+    if (agentFlag) {
+        targets = resolveTargets(args, all);
+    }
+    else {
+        const detected = all.filter((d) => d.detected);
+        line("\nDetected agents:");
+        all.forEach((d, i) => {
+            const mark = d.detected ? "*" : " ";
+            line(`  ${mark} ${i + 1}. ${d.def.name.padEnd(14)} ${d.via.join(", ") || "(not found)"}`);
+        });
+        const def = detected.map((d) => all.indexOf(d) + 1).join(",");
+        const answer = await ask(`\nInstall into which agents? comma-separated numbers or 'all' [${def || "none"}]: `);
+        const sel = answer || def;
+        if (!sel || sel === "none") {
+            line("No agents selected — nothing to do.");
+            return;
+        }
+        targets =
+            sel === "all"
+                ? all
+                : sel
+                    .split(",")
+                    .map((s) => parseInt(s.trim(), 10))
+                    .filter((n) => Number.isInteger(n) && n >= 1 && n <= all.length)
+                    .map((n) => all[n - 1]);
+        if (targets.length === 0) {
+            throw usageError("No valid agents selected.");
+        }
+    }
+    // 3. auth mode (one question max)
+    const auth = parseAuth(args, "oauth");
+    line(`\nMCP URL: ${mcpUrl()}`);
+    line(`Auth mode: ${authFlag ?? "default per agent"}`);
+    // 4. install
+    const reports = [];
+    for (const det of targets) {
+        const report = installAgent(det, auth);
+        reports.push(report);
+        for (const w of report.warnings)
+            errLine(`  warning: ${w}`);
+        const cfg = report.config.action === "cli"
+            ? `configured via ${det.def.name} CLI`
+            : report.config.action === "unchanged"
+                ? `MCP already configured`
+                : `MCP written to ${report.config.configPath}` +
+                    (report.config.backup ? ` (backup: ${report.config.backup})` : "");
+        line(`\n${det.def.name}: ${cfg}`);
+        for (const s of report.skills) {
+            for (const r of s.results) {
+                if (r.action !== "unchanged")
+                    line(`  skill ${r.name}: ${r.action} → ${r.path}`);
+            }
+            if (s.results.every((r) => r.action === "unchanged")) {
+                line(`  skills already installed in ${s.dir}`);
+            }
+        }
+    }
+    // 5. verify
+    line("\nVerifying...");
+    const boards = await request("/boards");
+    line(`  API ok — ${boards.length} accessible board(s)`);
+    try {
+        const status = await probeMcp(mcpUrl(), apiKey());
+        line(`  MCP ${status}`);
+    }
+    catch (e) {
+        errLine(`  MCP probe failed: ${e instanceof Error ? e.message : e}`);
+    }
+    line("\nDone. Next steps:");
+    line("  • restart your agent so it picks up the new MCP server");
+    line("  • in the agent, the 'kelocan' skills teach the board workflow");
+    line("  • run `kelocan doctor` anytime to re-check the setup");
+}
+// ---------- non-interactive commands ----------
+export async function cmdMcpInstall(args) {
+    const auth = parseAuth(args);
+    const all = detectAll();
+    const targets = resolveTargets(args, all);
+    const out = [];
+    for (const det of targets) {
+        const res = installAgentMcpOnly(det, auth);
+        out.push(res);
+        if (res.action === "written") {
+            line(`${det.def.id}: wrote ${res.configPath}${res.backup ? ` (backup: ${res.backup})` : ""}`);
+        }
+        else if (res.action === "cli") {
+            line(`${det.def.id}: configured via ${det.def.name} CLI`);
+        }
+        else {
+            line(`${det.def.id}: already configured`);
+        }
+    }
+    emit(out, outputOpts(args), () => { });
+}
+function installAgentMcpOnly(det, auth) {
+    return installMcpConfig(det.def, auth);
+}
+export async function cmdSkillsInstall(args) {
+    const all = detectAll();
+    const targets = resolveTargets(args, all);
+    for (const det of targets) {
+        for (const dir of det.skillDirs) {
+            const results = installSkills(dir);
+            for (const r of results) {
+                line(`${det.def.id}: skill ${r.name} ${r.action} → ${r.path}`);
+            }
+        }
+    }
+}
+export async function cmdUninstall(args) {
+    const all = detectAll();
+    const targets = resolveTargets(args, all);
+    for (const det of targets) {
+        const cfg = uninstallMcpConfig(det.def);
+        const removedSkills = det.skillDirs.flatMap((dir) => removeSkills(dir));
+        line(`${det.def.id}: MCP ${cfg.action}` +
+            (cfg.backup ? ` (backup: ${cfg.backup})` : "") +
+            (removedSkills.length ? `; removed skills: ${removedSkills.join(", ")}` : "; no skills found"));
+    }
+}
+export async function cmdDoctor(args) {
+    const report = await runDoctor();
+    emit(report, outputOpts(args), () => {
+        const icon = { ok: "ok", info: "--", warn: "!!", fail: "XX" };
+        line("Server:");
+        for (const f of report.server) {
+            line(`  [${icon[f.level]}] ${f.message}${f.fix ? `  → ${f.fix}` : ""}`);
+        }
+        for (const a of report.agents) {
+            line(`\n${a.name} (${a.agent}):`);
+            for (const f of a.findings) {
+                line(`  [${icon[f.level]}] ${f.message}${f.fix ? `  → ${f.fix}` : ""}`);
+            }
+        }
+        line(`\n${report.ok ? "All checks passed." : "Some checks failed — see fixes above."}`);
+    });
+    if (!report.ok)
+        process.exitCode = 1;
+}

package/dist/skills.js

@@ -0,0 +1,78 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CliError } from "./errors.js";
+/** Skill names bundled with the package (skills/<name>/SKILL.md at repo root). */
+export const SKILL_NAMES = ["kelocan", "kelocan-review"];
+function packageRoot() {
+    // dist/skills.js -> <pkg>/dist -> <pkg>; src/skills.ts -> <pkg>/src -> <pkg>
+    return dirname(dirname(fileURLToPath(import.meta.url)));
+}
+export function bundledSkillsDir() {
+    return join(packageRoot(), "skills");
+}
+export function bundledSkillSource(name) {
+    const path = join(bundledSkillsDir(), name, "SKILL.md");
+    if (!existsSync(path)) {
+        throw new CliError(`Bundled skill "${name}" not found at ${path}`);
+    }
+    return readFileSync(path, "utf8");
+}
+export function bundledSkillHash(name) {
+    return createHash("sha256").update(bundledSkillSource(name)).digest("hex");
+}
+/** Install all bundled skills into `targetDir` (e.g. ~/.agents/skills). Idempotent. */
+export function installSkills(targetDir) {
+    const results = [];
+    for (const name of SKILL_NAMES) {
+        const dest = join(targetDir, name, "SKILL.md");
+        const src = bundledSkillSource(name);
+        let action = "installed";
+        if (existsSync(dest)) {
+            const cur = readFileSync(dest, "utf8");
+            if (cur === src)
+                action = "unchanged";
+            else
+                action = "updated";
+        }
+        if (action !== "unchanged") {
+            mkdirSync(dirname(dest), { recursive: true });
+            writeFileSync(dest, src);
+        }
+        results.push({ name, path: dest, action });
+    }
+    return results;
+}
+/** Remove only the kelocan skills from `targetDir`. Returns removed paths. */
+export function removeSkills(targetDir) {
+    const removed = [];
+    for (const name of SKILL_NAMES) {
+        const dir = join(targetDir, name);
+        if (existsSync(dir)) {
+            rmSync(dir, { recursive: true });
+            removed.push(dir);
+        }
+    }
+    return removed;
+}
+/** Compare an installed SKILL.md against the bundled copy. */
+export function skillStatus(targetDir, name) {
+    const dest = join(targetDir, name, "SKILL.md");
+    if (!existsSync(dest))
+        return "missing";
+    const cur = readFileSync(dest, "utf8");
+    if (cur === bundledSkillSource(name))
+        return "current";
+    // Differ only by our own version marker? treat as outdated; else modified.
+    return cur.includes("name: " + name) ? "outdated" : "modified";
+}
+/** All skills present under a bundled skills dir (for `npx skills add` parity). */
+export function bundledSkillNames() {
+    const dir = bundledSkillsDir();
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir, { withFileTypes: true })
+        .filter((d) => d.isDirectory() && existsSync(join(dir, d.name, "SKILL.md")))
+        .map((d) => d.name);
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "kelocan",
+  "version": "0.1.0",
+  "description": "Kelocan CLI — thin client & agent workflow commands for the Kelocan kanban board",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "kelocan": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "tsx --test test/*.test.ts",
+    "test:e2e": "npm run build && tsx --test test/e2e.test.ts",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}

package/skills/kelocan/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: kelocan
+description: Work on tasks from a Kelocan kanban board. Use when the user asks to work on a Kelocan task/card, fetch a task's agent prompt, report progress, move cards between columns, manage sub-tasks, or run the agent workflow — via the kelocan MCP server or the `kelocan` CLI.
+---
+
+# Kelocan
+
+Kelocan is a kanban board for orchestrating AI-agent work. You can reach it two ways:
+
+- **MCP server** `kelocan` (streamable HTTP, OAuth 2.1) — installed by `kelocan init`.
+- **CLI** `kelocan` — a thin REST client (`npx kelocan <cmd>`), same capabilities.
+
+Both are equivalent; use whichever is available in this environment. The board,
+task ids and rules below are placeholders — always follow the task's own prompt.
+
+## Golden rule: the task prompt is the source of truth
+
+This skill only teaches the mechanics of reaching the board. **It deliberately
+does not define the work rules** (columns, branching, PRs, review flow). Those
+rules live in the task's rendered agent prompt:
+
+- MCP: call `get_agent_prompt` with the `task_id`.
+- CLI: `kelocan task prompt <task-id>`.
+
+Fetch that prompt first, then follow it **verbatim**. A typical prompt instructs
+the agent to (names may differ per board):
+
+1. `get_board` / `kelocan board show <board>` to learn the columns.
+2. `move_task` → the "active" column, then `start_agent_run` (keep the `run_id`).
+   CLI: `kelocan task move <id> --to active`, `kelocan run start <id> --agent "<name>"`.
+3. Work on the task. Report progress periodically with `add_comment` /
+   `kelocan task comment <id> -m "..."`. Log every bug found as a new task,
+   don't fix out of scope.
+4. On success: open a PR per the prompt's rules, `finish_agent_run`
+   (`succeeded`), then `move_task` → "Review".
+   On blocked: `add_comment` the question, `finish_agent_run` (`failed`), leave
+   the task in place.
+
+## Useful CLI reference
+
+```bash
+kelocan login                      # browser auth (or --api-key klc_...)
+kelocan board show <board>         # columns & task counts
+kelocan task list <board>          # --column / --label / --sprint filters
+kelocan task show <id>             # detail
+kelocan task prompt <id>           # the agent prompt — fetch this first
+kelocan run start <id> --agent N   # prints run_id
+kelocan run finish <run> --outcome succeeded -m "summary"
+kelocan task comment <id> -m "..." # progress report
+kelocan task move <id> --to review # column name, role, or uuid
+kelocan subtask list|toggle
+```
+
+Every command supports `--json` and `--fields a,b,c` for low-token output.

package/skills/kelocan-review/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: kelocan-review
+description: Review tasks sitting in the Review column of a Kelocan board. Use when the user says "review", "review task(s)", or asks to check the work an agent produced on the Kelocan board. Always fetch the official review prompt via get_agent_prompt / `kelocan task prompt` — never invent review rules.
+---
+
+# Kelocan Review
+
+When asked to review Kelocan work:
+
+1. **Find the tasks.** List the board's Review column:
+   - CLI: `kelocan task list <board> --column review`
+   - MCP: `list_tasks` with the review column name.
+   ("Review" without context → review every task in that column, one by one.)
+
+2. **Fetch the official review prompt for each task.** The server renders the
+   *review* variant of the agent prompt automatically when the task sits in a
+   `review`-role column:
+   - MCP: `get_agent_prompt` with the `task_id`.
+   - CLI: `kelocan task prompt <task-id>`.
+
+3. **Execute that prompt verbatim.** It defines the review checklist, how to
+   inspect the PR/evidence, how to write findings as task comments, and where
+   to move the card afterwards (back to active with feedback, or to Done).
+
+4. **One task at a time.** Finish each review (comment + column move) before
+   starting the next. Don't batch-approve.
+
+## What this skill deliberately does NOT contain
+
+Acceptance criteria, code-review checklists, and merge rules belong to the
+task's own prompt and project conventions. If the review prompt is missing or
+unclear, comment on the task asking for clarification instead of guessing.