@starlove/orbit 1.0.2 → 1.0.3

package/README.md

@@ -37,6 +37,7 @@ From the repo you want a board for:
 cd path/to/your-app
 orbit init            # creates .orbit/board.db + SKILL-ORBIT.md + AGENTS.md
 orbit init --example  # optional: add onboarding example tickets
+orbit init --no-ai    # optional: create or update the board with AI disabled
 ```
 
 Start one runtime and keep using it:
@@ -67,9 +68,9 @@ Wipe a single board and start over with `orbit reset` (deletes `.orbit/`, `SKILL
 
 ## Use with AI
 
-Orbit ships with everything an agent needs to claim work, read tickets, and write back implementation notes — but it stays out of your way until you turn it on.
+Orbit ships with everything an agent needs to claim work, read tickets, and write back implementation notes. New boards have AI collaboration enabled by default; pass `orbit init --no-ai` or turn off **Enable AI** in Settings → AI if you want a human-only board.
 
-1. **Enable AI on the board.** Open Settings (gear icon) → **AI** tab → toggle **Enable AI**. Orbit provisions the `AI Ready`, `In Progress`, and `Review` lanes if they're missing, surfaces the agent-context fields, and reveals the MCP setup snippet.
+1. **Confirm AI is enabled.** Open Settings (gear icon) → **AI** tab → toggle **Enable AI** if needed. Orbit provisions the `AI Ready`, `In Progress`, and `Review` lanes if they're missing, surfaces the agent-context fields, and reveals the MCP setup snippet.
 2. **Fill in agent context.** Settings → AI → *Agent Instructions* is the project-level briefing every agent reads before touching a ticket. Describe what the project is, who it serves, the stack, and any rules of the road.
 3. **Register the MCP server with your agent.** The AI tab generates copy-pasteable snippets for Claude Code, Cursor, Codex, OpenCode, OpenClaw, and other MCP-capable clients — pick your OS + client and paste the command into your agent's MCP config.
 4. **Restart the agent.** On its next boot it discovers the Orbit MCP tools (`board_claim_next`, `board_get_ticket_context`, `board_update_ticket`, etc.).
@@ -80,7 +81,7 @@ If you initialized with `--example`, ticket #12 (`Try Orbit MCP on this ticket`)
 ## Vocabulary
 
 - **Board** — one repo's planning surface. Each board carries its own `agent_instructions`, lanes, tickets, and memory entries.
-- **Lane** — a column. Lanes are user-defined and freely named/reordered. The seed gives you `Backlog`, `Todo`, `In Progress`, `Review`, `Done`, `Cancelled`; turning on AI also pins `AI Ready`, `In Progress`, and `Review` as anchor lanes the agent flow keys off.
+- **Lane** — a column. Lanes are user-defined and freely named/reordered. The default seed gives you `Backlog`, `Todo`, `AI Ready`, `In Progress`, `Review`, `Done`, `Cancelled`; `AI Ready`, `In Progress`, and `Review` are anchor lanes the agent flow keys off. `AI Ready` is inserted between `Todo` and `In Progress` when AI is enabled.
 - **Ticket types**:
   - `epic` — index card for a multi-feature initiative. Owns child tickets via `parent_ticket_id`.
   - `feature` — a standalone capability or new behavior.
@@ -101,7 +102,7 @@ Bun is not used as the Orbit runtime because Orbit depends on Node's built-in `n
 
 Each repo gets its own board database. Orbit keeps a small central registry that maps repo paths to their board files; the CLI, web app, and MCP server use explicit project roots when provided, then fall back to walking upward to find `.orbit/board.db`.
 
-- **Per-repo board** — `.orbit/board.db` lives in the repo it tracks. `orbit init` creates it, drops `SKILL-ORBIT.md` at the repo root, and creates/updates `AGENTS.md` with a terse pointer so agents load the full Orbit protocol only when relevant. Add `--example` to create onboarding cards.
+- **Per-repo board** — `.orbit/board.db` lives in the repo it tracks. `orbit init` creates it, drops `SKILL-ORBIT.md` at the repo root, and creates/updates `AGENTS.md` with a terse pointer so agents load the full Orbit protocol only when relevant. Add `--example` to create onboarding cards, or `--no-ai` to disable AI collaboration for the board.
 - **Central registry** — `registry.db` records each board's path, slug, and last-active timestamp. Host `orbit serve` uses `~/.orbit`; `orbit docker` uses `<repo>/.orbit/docker-data`. Keep one mode unless you intentionally share `DATA_DIR`, re-register boards, or import snapshots.
 - **Project-root discovery** — `orbit serve`, `orbit mcp`, and MCP-attached agents resolve a board from an explicit `--cwd` / `PROJECT_ROOT` first, then fall back to walking up from process cwd to find `.orbit/board.db`. Persistent MCP configs should use an explicit root so the right board attaches even when the agent launches elsewhere.
 - **Two channels for AI** — `AGENTS.md` is the auto-loaded briefing, with an Orbit-managed pointer to `SKILL-ORBIT.md`; the *MCP config* tells the agent runtime how to launch Orbit's MCP server for the right project. The briefing travels with the repo; the MCP registration is per-agent-install.
@@ -167,7 +168,7 @@ A copy-editable client config lives at [docs/mcp-client.example.json](docs/mcp-c
 - **Board**: name from `BOARD_NAME` env var, otherwise inferred from `package.json` `name` or the repo folder name. Slug from `BOARD_SLUG` or derived from the name.
 - **Repo metadata**: `REPO_URL` env var or `git config --get remote.origin.url`; `SYSTEM_PATH` env var or the repo path passed to `orbit init`.
 - **Default branch**: `DEFAULT_BRANCH` env var, otherwise the current git branch.
-- **Lanes (6)**: `Backlog`, `Todo` (default), `In Progress`, `Review`, `Done`, `Cancelled`.
+- **Lanes (7)**: `Backlog`, `Todo` (default), `AI Ready`, `In Progress`, `Review`, `Done`, `Cancelled`. Pass `--no-ai` to seed without `AI Ready` and leave AI collaboration disabled.
 - **Labels (7)**: `human-only`, `needs-human-input`, `needs-decomposition`, `needs-followup`, `tech-debt`, `security`, `onboarding`.
 - **Onboarding cards (optional)**: pass `--example` to create an epic `#1` plus children `#2`, `#3`, and `#12 — Try Orbit MCP on this ticket`.
 - **Free-form fields**: `project_notes` (Notes tab) and `agent_instructions` (AI tab) get placeholder text you should replace.

package/dist/full/version.json

@@ -1,6 +1,6 @@
 {
   "name": "@starlove/orbit",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "edition": "full",
-  "builtAt": "2026-05-19T05:18:31.299Z"
+  "builtAt": "2026-05-19T05:38:00.174Z"
 }

package/docs/MCP_SETUP.md

@@ -13,7 +13,7 @@ Orbit generates neutral template paths for Windows, macOS, and Linux. Replace th
 
 Board data lives under each tracked repo at `.orbit/board.db` (flat file or `.orbit/boards/<slug>/` for extra boards)—not beside the MCP script.
 
-After installing Orbit as a package, run **`orbit init`** in (or with `--cwd` pointing at) the repo where you want `.orbit/`, **`AGENTS.md`**, and a copy of **`SKILL-ORBIT.md`** so agents and MCP line up with that tree. Add `--ai` to enable the AI Ready / In Progress / Review agent lanes immediately, and add `--example` if you want the onboarding example tickets.
+After installing Orbit as a package, run **`orbit init`** in (or with `--cwd` pointing at) the repo where you want `.orbit/`, **`AGENTS.md`**, and a copy of **`SKILL-ORBIT.md`** so agents and MCP line up with that tree. Orbit enables the AI Ready / In Progress / Review agent lanes by default. Add `--no-ai` if you want AI collaboration disabled, and add `--example` if you want the onboarding example tickets.
 
 The generated format changes by app:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starlove/orbit",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Starscape Orbit — SQLite-backed, agent-first task board (Starscape suite).",
   "license": "MIT",
   "type": "module",

package/src/cli/orbit.js

@@ -23,7 +23,7 @@ Options (init / reset / serve / docker / mcp):
   --cwd <dir>           Project root (default: process.cwd())
 
 Options (init only):
-  --ai                  Enable AI collaboration lanes
+  --no-ai               Create the board with AI collaboration disabled
   --example             Create example onboarding tickets
   --refresh-agents-md   Overwrite SKILL-ORBIT.md and refresh Orbit section in AGENTS.md
 
@@ -135,22 +135,30 @@ function syncAgentsMd(projectRoot, options) {
   console.log(`Appended Orbit instructions to ${agentsPath}`);
 }
 
-function enableAiIfRequested(options, registryRow, core) {
+function enableAiIfEnabled(options, registryRow, core) {
   if (!options.ai || !registryRow) return;
   const { enableAiCollaboration, openConnection } = core;
   const db = openConnection(registryRow.db_path);
-  enableAiCollaboration(db, registryRow.id, { stageOnboardingTicket: options.example, actor: "orbit init --ai" });
+  enableAiCollaboration(db, registryRow.id, { stageOnboardingTicket: options.example, actor: "orbit init" });
   const suffix = options.example ? "; example ticket #12 is staged in AI Ready." : ".";
   console.log(`AI collaboration enabled — AI Ready, In Progress, and Review lanes are present${suffix}`);
 }
 
+function disableAiIfRequested(options, registryRow, core) {
+  if (options.ai || !registryRow) return;
+  const { openConnection } = core;
+  const db = openConnection(registryRow.db_path);
+  db.prepare("UPDATE boards SET ai_enabled = 0, updated_at = ? WHERE id = ?").run(new Date().toISOString(), registryRow.id);
+  console.log("AI collaboration disabled for this board.");
+}
+
 function parseArgs(argv) {
   const args = {
     command: null,
     cwd: process.env.PROJECT_ROOT ? resolve(process.env.PROJECT_ROOT) : process.cwd(),
     cwdProvided: false,
     refreshAgentsMd: false,
-    ai: false,
+    ai: true,
     example: false,
     port: null,
     image: "starscape-orbit:local",
@@ -169,7 +177,7 @@ function parseArgs(argv) {
   for (let i = 1; i < rest.length; i++) {
     const a = rest[i];
     if (a === "--refresh-agents-md") args.refreshAgentsMd = true;
-    else if (a === "--ai") args.ai = true;
+    else if (a === "--no-ai") args.ai = false;
     else if (a === "--example") args.example = true;
     else if (a === "--cwd" && rest[i + 1]) {
       args.cwdProvided = true;
@@ -217,7 +225,7 @@ async function runInit(options) {
   mkdirSync(DATA_DIR, { recursive: true });
   createRegistrySchema();
 
-  const result = provisionRepoBoard(projectRoot, { includeExamples: options.example });
+  const result = provisionRepoBoard(projectRoot, { enableAi: options.ai, includeExamples: options.example });
   const skillSrc = resolve(ROOT_DIR, "SKILL-ORBIT.md");
   const skillDest = resolve(projectRoot, "SKILL-ORBIT.md");
 
@@ -235,7 +243,8 @@ async function runInit(options) {
     syncAgentsMd(projectRoot, options);
   }
 
-  enableAiIfRequested(options, result.registryRow, core);
+  enableAiIfEnabled(options, result.registryRow, core);
+  disableAiIfRequested(options, result.registryRow, core);
 
   if (result.message && result.status === "skipped") {
     console.log(result.message);
@@ -254,7 +263,7 @@ ${mcpLine}
 --- Next: agent prompt (from this repo) ---
 Read AGENTS.md in this repository, then use the Orbit MCP tools. Use board_list, board_set_active, and ticket context tools per docs/AGENT_PROTOCOL.md before claiming or updating work.
 
-${options.example ? (options.ai ? "Example ticket #12 is \"Try Orbit MCP on this ticket\" in AI Ready — good first exercise after MCP is connected." : "Example tickets were created. Add `--ai` to also create AI collaboration lanes and stage ticket #12 in AI Ready.") : "No example tickets were created. Rerun on a fresh board with `orbit init --example` if you want the onboarding examples."}
+${options.example ? (options.ai ? "Example ticket #12 is \"Try Orbit MCP on this ticket\" in AI Ready — good first exercise after MCP is connected." : "Example tickets were created. AI collaboration was disabled with `--no-ai`, so ticket #12 remains in Backlog.") : "No example tickets were created. Rerun on a fresh board with `orbit init --example` if you want the onboarding examples."}
 `);
 
   if (result.registryRow) {

package/src/core/boards.js

@@ -1,5 +1,5 @@
 import { getRegistry, tx } from "./db.js";
-import { boardById } from "./queries.js";
+import { boardById, compactStatePositions } from "./queries.js";
 import {
   computeNewBoardDbPath,
   ensureBoardDbFileAndSchema,
@@ -33,14 +33,23 @@ export function createBoard(body, ctx) {
   const time = now();
   const sniff = buildBoardFromRepo(repoPath);
 
-  const defaultStates = body.states || [
+  const aiEnabled = body.ai_enabled === undefined ? true : Boolean(body.ai_enabled);
+  const defaultStates = body.states || (aiEnabled ? [
     ["Backlog", null],
     ["Todo", null],
+    ["AI Ready", "ai_ready"],
     ["In Progress", "in_progress"],
     ["Review", "review"],
     ["Done", "done"],
     ["Cancelled", null]
-  ];
+  ] : [
+    ["Backlog", null],
+    ["Todo", null],
+    ["In Progress", "in_progress"],
+    ["Review", "review"],
+    ["Done", "done"],
+    ["Cancelled", null]
+  ]);
 
   // Board row + lanes + creation event land atomically in the board DB. The
   // registry insert below is a different database (can't share this
@@ -49,8 +58,8 @@ export function createBoard(body, ctx) {
   tx(db, () => {
     db.prepare(
       `INSERT INTO boards
-       (id, slug, name, repo_url, system_path, default_branch, created_at, updated_at)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`
+       (id, slug, name, repo_url, system_path, default_branch, ai_enabled, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`
     ).run(
       boardId,
       slug,
@@ -58,6 +67,7 @@ export function createBoard(body, ctx) {
       body.repo_url || sniff.repoUrl || "",
       repoPath,
       body.default_branch || sniff.defaultBranch || "main",
+      aiEnabled ? 1 : 0,
       time,
       time
     );
@@ -70,6 +80,7 @@ export function createBoard(body, ctx) {
       ).run(id(), boardId, stateName, position, stateName === "Todo" ? 1 : 0, role || null, time);
     });
 
+    if (aiEnabled) ensureAgentLanes(db, boardId);
     recordEvent(db, boardId, "board_created", null, actor.name, { board_id: boardId, slug });
   });
 
@@ -95,24 +106,58 @@ const AGENT_LANES = [
   { name: "Review", role: "review" }
 ];
 
-/** Ensure the three role-bearing lanes that agent flow depends on
- *  (ai_ready / in_progress / review) exist on the board. Missing lanes are
- *  appended at the end of the lane order. Idempotent. */
+function desiredAgentLanePosition(db, boardId, role) {
+  if (role === "ai_ready") {
+    const todo = db.prepare("SELECT position FROM states WHERE board_id = ? AND name = 'Todo'").get(boardId);
+    if (todo) return Number(todo.position) + 1;
+    const inProgress = db.prepare("SELECT position FROM states WHERE board_id = ? AND role = 'in_progress'").get(boardId);
+    if (inProgress) return Number(inProgress.position);
+  }
+  const maxPosition = db
+    .prepare("SELECT MAX(position) AS value FROM states WHERE board_id = ?")
+    .get(boardId).value;
+  return Number(maxPosition ?? -1) + 1;
+}
+
+function openStateSlot(db, boardId, position, exceptStateId = null) {
+  db.prepare(
+    `UPDATE states
+     SET position = position + 1
+     WHERE board_id = ?
+       AND position >= ?
+       AND (? IS NULL OR id != ?)`
+  ).run(boardId, position, exceptStateId, exceptStateId);
+}
+
+/** Ensure the role-bearing lanes that agent flow depends on exist on the
+ *  board. AI Ready is kept directly after Todo so claim-next has a predictable
+ *  handoff column. Idempotent. */
 export function ensureAgentLanes(db, boardId) {
   const time = now();
   for (const lane of AGENT_LANES) {
     const existing = db
-      .prepare("SELECT id FROM states WHERE board_id = ? AND role = ?")
+      .prepare("SELECT id, position FROM states WHERE board_id = ? AND role = ?")
       .get(boardId, lane.role);
-    if (existing) continue;
-    const maxPosition = db
-      .prepare("SELECT MAX(position) AS value FROM states WHERE board_id = ?")
-      .get(boardId).value;
+    if (existing) {
+      if (lane.role === "ai_ready") {
+        let desiredPosition = desiredAgentLanePosition(db, boardId, lane.role);
+        if (Number(existing.position) !== desiredPosition) {
+          db.prepare("UPDATE states SET position = -1 WHERE id = ?").run(existing.id);
+          compactStatePositions(db, boardId);
+          desiredPosition = desiredAgentLanePosition(db, boardId, lane.role);
+          openStateSlot(db, boardId, desiredPosition, existing.id);
+          db.prepare("UPDATE states SET position = ? WHERE id = ?").run(desiredPosition, existing.id);
+        }
+      }
+      continue;
+    }
+    const position = desiredAgentLanePosition(db, boardId, lane.role);
+    openStateSlot(db, boardId, position);
     db.prepare(
       `INSERT INTO states
        (id, board_id, name, position, is_default, role, created_at)
        VALUES (?, ?, ?, ?, 0, ?, ?)`
-    ).run(id(), boardId, lane.name, Number(maxPosition || 0) + 1, lane.role, time);
+    ).run(id(), boardId, lane.name, position, lane.role, time);
   }
 }
 

package/src/core/provision-repo-board.js

@@ -45,7 +45,10 @@ export function provisionRepoBoard(repoPathRaw, options = {}) {
 
   const db = openConnection(dbPath);
   createBoardSchema(db);
-  const seeded = seedIfEmpty(db, repoRoot, { includeExamples: options.includeExamples });
+  const seeded = seedIfEmpty(db, repoRoot, {
+    enableAi: options.enableAi,
+    includeExamples: options.includeExamples
+  });
   if (!seeded) {
     const boardMeta = readBoardMetaFromSqlite(db);
     if (!boardMeta) {
@@ -60,7 +63,10 @@ export function provisionRepoBoard(repoPathRaw, options = {}) {
 function provisionExistingDbFile(repoRoot, dbPath, options = {}) {
   const db = openConnection(dbPath);
   createBoardSchema(db);
-  const seeded = seedIfEmpty(db, repoRoot, { includeExamples: options.includeExamples });
+  const seeded = seedIfEmpty(db, repoRoot, {
+    enableAi: options.enableAi,
+    includeExamples: options.includeExamples
+  });
   if (seeded) {
     return insertAfterSeed(repoRoot, dbPath, db, seeded, "repaired");
   }

package/src/core/seed.js

@@ -23,8 +23,8 @@ export function seedIfEmpty(db, repoPath, options = {}) {
     db.prepare(
       `INSERT INTO boards
        (id, slug, name, repo_url, system_path, default_branch,
-        project_notes, agent_instructions, created_at, updated_at)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+        project_notes, agent_instructions, ai_enabled, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
     ).run(
       boardId,
       seed.boardSlug,
@@ -34,17 +34,26 @@ export function seedIfEmpty(db, repoPath, options = {}) {
       seed.defaultBranch,
       seed.projectNotes,
       seed.agentInstructions,
+      options.enableAi === false ? 0 : 1,
       time,
       time
     );
 
-    const states = [
+    const states = options.enableAi === false ? [
       ["Backlog", null],
       ["Todo", null],
       ["In Progress", "in_progress"],
       ["Review", "review"],
       ["Done", "done"],
       ["Cancelled", null]
+    ] : [
+      ["Backlog", null],
+      ["Todo", null],
+      ["AI Ready", "ai_ready"],
+      ["In Progress", "in_progress"],
+      ["Review", "review"],
+      ["Done", "done"],
+      ["Cancelled", null]
     ];
     const stateIds = new Map();
     states.forEach(([name, role], position) => {