kanbo-cli 0.1.1 → 0.1.2

package/README.md

@@ -14,6 +14,7 @@
 - **Status lines and runs.** Every card says what it is doing right now, and every launch of a card is recorded as a run with an attempt number.
 - **Subtasks, comments, pull request links, sprints** and **column entry rules** (`checklist_complete`, `pull_request_linked`, `ci_green`, `approved`).
 - **Storage you choose.** A board file in the project (`.kanbo/board.db`), or an external Postgres database such as Supabase shared by a team, with `kanban_person` / `kanban_agent` roles.
+- **MCP alone is enough to start.** `kanbo mcp` sends the board's basic rules as MCP server instructions when a client connects, so an agent needs no instruction file for the basics.
 - **One-command project setup.** `kanbo init` binds the project, writes an instruction block into `CLAUDE.md` or `AGENTS.md`, and registers the MCP server with Claude Code, Codex or Cursor.
 - **Board over HTTP.** `kanbo serve` answers a JSON API and serves a board page on `http://127.0.0.1:4318`, loopback-only and token-guarded.
 - **Machine-readable capabilities.** `kanbo capabilities --json` describes every tool, command, rule and limit for an orchestrator to read.

package/dist/cli.cjs

@@ -3083,7 +3083,7 @@ var import_picocolors = /* @__PURE__ */ __toESM((/* @__PURE__ */ __commonJSMin((
 * `package.version`. A build carries it as a literal; running from source
 * (tests, `tsx`) reads the package's own `package.json` instead.
 */
-const KANBO_PACKAGE_VERSION = "0.1.1";
+const KANBO_PACKAGE_VERSION = "0.1.2";
 /**
 * Every exit code this tool promises, and what it means — the capabilities
 * manifest's `exitCodes` reads this rather than naming the codes again. `0` and
@@ -11178,32 +11178,61 @@ async function migrateCards(store, input) {
 	};
 }
 //#endregion
-//#region src/ops/prime.ts
+//#region src/ops/agent-rules.ts
 /**
-* The rules of this board, as an agent needs to hear them.
+* The sentences that tell an agent how to work this board, written once.
+*
+* Four surfaces say them: the text `kanbo prime` returns (`BOARD_RULES`), the
+* block `kanbo init` writes into a project's `CLAUDE.md` / `AGENTS.md`, the
+* `instructions` the `kanbo mcp` server sends when a client connects, and the
+* `kanbo_card_create` tool's description. Each surface adds its own way of
+* doing the thing — a command, a tool name — but the rule itself is read from
+* here, so the four cannot come to say different things.
+*
+* No sentence names a tool or a command: the same text reaches an agent holding
+* MCP tools, one with a command line, and one talking to a server over HTTP.
+*/
+const MOVE_CARD_RULE = "You move the card between columns yourself, at the moment its real state changes. The board never moves a card for you.";
+const STATUS_LINE_RULE = "Write a status line at every step, including before and after anything long-running. One sentence, present tense, about what is happening right now.";
+const WAIT_FOR_PERSON_RULE = "When you need a person, mark the card as waiting for approval and end your turn. You will be told when the answer comes.";
+const PERSON_ONLY_RULE = "Only a person approves a card, and only a person takes one out of waiting. Never do either yourself.";
+const EXECUTION_MODE_RULE = "Each card says where it runs: `worktree` means a separate copy of the project, `main` means the project folder itself. Work in the mode the card names.";
+/** When to split a card at all — said on its own where the surface names the parent its own way. */
+const SUBTASK_WHEN_SENTENCE = "Create subtasks only when the person asks for them, or when a task has parts that can be done and checked separately (different stages, owners or pull requests); do not split small work you will finish in one go.";
+/** How to split one, with the way this surface names the parent card. */
+function subtaskSplitSentence(parentReference) {
+	return `When you do split a card, make the parts subtasks of it (${parentReference}), not separate top-level cards.`;
+}
+const SUBTASK_RULE = `${SUBTASK_WHEN_SENTENCE} ${subtaskSplitSentence("the parent card's id")}`;
+const PULL_REQUEST_RULE = "Opened a pull request? Link it to the card. Its state and CI checks then reach the card as comments on their own — nothing else tells the board a pull request exists.";
+const OWN_SESSION_RULE = "Started the work yourself, not launched by an app that tracks the run for you? Say so when you start the run — `claude:<session id>` from Claude Code, `codex:<session id>` from Codex (the session id Codex prints) — so your own log of it can be found later.";
+/** Said by the `kanbo init` block and the MCP instructions, which name the comment command or tool beside it. */
+const COMMENT_RULE = "Findings, results, decisions and questions go on the card as comments.";
+/**
+* The rules of this board, as `kanbo prime` says them under its column list.
 *
 * They are about the board and nothing else. The board does not hand out a role, a
 * method or a pipeline — that belongs to the instructions the person wrote for
 * their own agent — so the list stops at what the board itself guarantees and
-* expects. No tool is named either: the same text reaches an agent holding MCP
-* tools, one with a command line, and one talking to a server over HTTP, and each
-* of them already knows what it is holding.
+* expects.
 *
-* Exported because it is also the source `buildCapabilitiesManifest` reads its
-* `rules` from — one list, read by the prompt an agent sees and by the manifest
-* an orchestrator reads about the board.
+* Also the source `buildCapabilitiesManifest` reads its `rules` from — one list,
+* read by the prompt an agent sees and by the manifest an orchestrator reads
+* about the board.
 */
 const BOARD_RULES = [
-	"You move the card between columns yourself, at the moment its real state changes. The board never moves a card for you.",
-	"Write a status line at every step, including before and after anything long-running. One sentence, present tense, about what is happening right now.",
-	"When you need a person, mark the card as waiting for approval and end your turn. You will be told when the answer comes.",
-	"Only a person approves a card, and only a person takes one out of waiting. Never do either yourself.",
-	"Each card says where it runs: `worktree` means a separate copy of the project, `main` means the project folder itself. Work in the mode the card names.",
-	"Create subtasks only when the person asks for them, or when a task has parts that can be done and checked separately (different stages, owners or pull requests); do not split small work you will finish in one go. When you do split a card, make the parts subtasks of it (the parent card's id), not separate top-level cards.",
-	"Opened a pull request? Link it to the card. Its state and CI checks then reach the card as comments on their own — nothing else tells the board a pull request exists.",
-	"Started the work yourself, not launched by an app that tracks the run for you? Say so when you start the run — `claude:<session id>` from Claude Code, `codex:<session id>` from Codex (the session id Codex prints) — so your own log of it can be found later.",
+	MOVE_CARD_RULE,
+	STATUS_LINE_RULE,
+	WAIT_FOR_PERSON_RULE,
+	PERSON_ONLY_RULE,
+	EXECUTION_MODE_RULE,
+	SUBTASK_RULE,
+	PULL_REQUEST_RULE,
+	OWN_SESSION_RULE,
 	"Read the column descriptions above before moving a card, and do all of this through the board tools or commands you have — a statement in your reply changes nothing."
 ];
+//#endregion
+//#region src/ops/prime.ts
 /**
 * What the board tells an agent about itself: the columns it has, what each one
 * means, and how a card is expected to travel across them.
@@ -23117,7 +23146,7 @@ const SUBTASK_SENTENCE = "To create a subtask (sub-card) under another card, pas
 const cardCreateTool = defineKanboTool({
 	name: "kanbo_card_create",
 	title: "Create a card",
-	description: `Put a new card on this board. ${SUBTASK_SENTENCE} Create subtasks only when the person asks for them, or when a task has parts that can be done and checked separately (different stages, owners or pull requests); do not split small work you will finish in one go. When you do split a card, make the parts subtasks of it (pass \`parent\`), not separate top-level cards.`,
+	description: `Put a new card on this board. ${SUBTASK_SENTENCE} ${SUBTASK_WHEN_SENTENCE} ${subtaskSplitSentence("pass `parent`")}`,
 	inputSchema: {
 		title: string().optional().describe("What the card is called. Leave it out and the card is titled with its own key; the description then says what the task is."),
 		description: string().optional().describe("What the card is about, spelled out for whoever picks it up."),
@@ -24181,7 +24210,8 @@ const CODEX_TABLE_PATTERN = new RegExp(String.raw`^\s*\[\s*mcp_servers\s*\.\s*(?
 *
 * It says what to run and when, and nothing about how to do the work: the
 * method is the person's own instructions to their agent, and the board only
-* insists on the part that keeps the card honest.
+* insists on the part that keeps the card honest. The rules are the sentences
+* `ops/agent-rules.ts` holds for every surface, with the command beside each.
 */
 const INSTRUCTION_BLOCK = [
 	INSTRUCTION_START,
@@ -24190,12 +24220,13 @@ const INSTRUCTION_BLOCK = [
 	"Work on this project is tracked on a kanbo board. Before starting a task run `kanbo prime` — it prints the board's columns and what each one means.",
 	"",
 	"- Take a card from `kanbo ready`.",
-	"- Move the card yourself (`kanbo card move <id> <column>`) — a card in the wrong column is a lie.",
-	"- Write a status line at every step (`kanbo card status-line <id> --text \"...\"`).",
-	"- Create subtasks only when the person asks for them, or when a task has parts that can be done and checked separately (different stages, owners or pull requests); do not split small work you will finish in one go. When you do split a card, make the parts subtasks of it (the parent card's id), not separate top-level cards. (`kanbo card create --description \"...\" --parent <id>`).",
-	"- Findings, decisions and questions go on the card (`kanbo card comment <id> --content \"...\"`).",
-	"- When you need a person, run `kanbo card wait-approval <id>` and end your turn. Never approve your own work, and never take a card out of a column where it is waiting for a person.",
-	"- Started the work yourself, not launched by an app that tracks the run? Pass your own session to `kanbo run start --session` — `claude:<session id>` from Claude Code, `codex:<session id>` from Codex (the session id Codex prints).",
+	`- ${MOVE_CARD_RULE} (\`kanbo card move <id> <column>\`)`,
+	`- ${STATUS_LINE_RULE} (\`kanbo card status-line <id> --text "..."\`)`,
+	`- ${SUBTASK_RULE} (\`kanbo card create --description "..." --parent <id>\`)`,
+	`- ${COMMENT_RULE} (\`kanbo card comment <id> --content "..."\`)`,
+	`- ${WAIT_FOR_PERSON_RULE} (\`kanbo card wait-approval <id>\`)`,
+	`- ${PERSON_ONLY_RULE}`,
+	`- ${OWN_SESSION_RULE} (\`kanbo run start <id> --agent <name> --session <ref>\`)`,
 	"- Run `kanbo capabilities` for the full list of tools, commands and rules.",
 	INSTRUCTION_END
 ].join("\n");
@@ -40719,6 +40750,36 @@ function registerKanboCapabilitiesResources(server) {
 	}] }));
 }
 //#endregion
+//#region src/mcp/instructions.ts
+/** A tool name as the instructions print it — typed, so a renamed tool fails the build here. */
+function tool(name) {
+	return `\`${name}\``;
+}
+/**
+* What `kanbo mcp` tells a client when it connects — the `instructions` of the
+* MCP initialize result, which a client hands its model before any tool is
+* called. An agent with nothing but this server connected learns from it how
+* to work the board, with no instruction file in the project.
+*
+* Static on purpose: it is sent before any board is resolved, so it says
+* nothing about columns — `kanbo_prime` returns those. The rules are the
+* sentences `ops/agent-rules.ts` holds for every surface, with the tool beside
+* each; the full manifest stays a resource.
+*/
+const KANBO_MCP_INSTRUCTIONS = [
+	"kanbo is a kanban board shared by people and agents; these tools read and change its cards.",
+	"",
+	`- At the start of a session call ${tool("kanbo_prime")} — it returns this board's columns and what each one means.`,
+	`- Take work from ${tool("kanbo_ready")}.`,
+	`- ${MOVE_CARD_RULE} (${tool("kanbo_card_move")})`,
+	`- ${STATUS_LINE_RULE} (${tool("kanbo_status_line")})`,
+	`- ${COMMENT_RULE} (${tool("kanbo_card_comment")})`,
+	`- ${SUBTASK_RULE} (${tool("kanbo_card_create")} with \`parent\`)`,
+	`- ${WAIT_FOR_PERSON_RULE} (${tool("kanbo_wait_approval")})`,
+	`- ${PERSON_ONLY_RULE}`,
+	`- Every tool, rule and canonical string: the resource \`${KANBO_CAPABILITIES_MARKDOWN_RESOURCE_URI}\`.`
+].join("\n");
+//#endregion
 //#region src/mcp/server.ts
 /** The name a client sees this server under. */
 const KANBO_MCP_SERVER_NAME = "kanbo";
@@ -40745,12 +40806,15 @@ function registerKanboTools(server, transport, options) {
 * function: it documents its capabilities its own way, and adding a second
 * `kanbo://` resource namespace to an inventory that is not only the board's
 * is a decision for that server to make, not this one.
+*
+* For the same reason it alone sends `KANBO_MCP_INSTRUCTIONS` in the initialize
+* result: the instructions of a server that is only the board.
 */
 function createKanboMcpServer(transport, options) {
 	const server = new McpServer({
 		name: KANBO_MCP_SERVER_NAME,
 		version: KANBO_MCP_SERVER_VERSION
-	});
+	}, { instructions: KANBO_MCP_INSTRUCTIONS });
 	registerKanboTools(server, transport, options);
 	registerKanboCapabilitiesResources(server);
 	return server;