@kata-sh/cli 0.1.2 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # Kata CLI
 
-A terminal coding agent built on [pi](https://github.com/badlogic/pi-mono) (`@mariozechner/pi-coding-agent`). Kata CLI bundles a curated set of extensions for structured planning, browser automation, web search, subagent orchestration, and more.
+A terminal coding agent built on [pi](https://github.com/badlogic/pi-mono) (`@mariozechner/pi-coding-agent`). Kata CLI bundles a curated set of extensions for structured planning, browser automation, web search, subagent orchestration, MCP server integration, and more.
 
 ## Quick Start
 
@@ -28,7 +28,7 @@ Kata CLI is a thin wrapper around pi-coding-agent. It does not fork pi — it co
 apps/cli/
   src/
     loader.ts              — Entry point: sets KATA_* env vars, imports cli.ts
-    cli.ts                 — Calls pi-coding-agent's main()
+    cli.ts                 — Calls createAgentSession() + InteractiveMode
     app-paths.ts           — ~/.kata-cli/ path constants
     resource-loader.ts     — Syncs bundled resources to ~/.kata-cli/agent/
     wizard.ts              — First-run setup, env key hydration
@@ -47,8 +47,12 @@ apps/cli/
 
 1. `loader.ts` sets `PI_PACKAGE_DIR` to `pkg/` so pi reads Kata's branding config
 2. `loader.ts` sets `KATA_CODING_AGENT_DIR` so pi uses `~/.kata-cli/agent/` instead of `~/.pi/agent/`
-3. `resource-loader.ts` syncs bundled extensions, agents, skills, and `AGENTS.md` to `~/.kata-cli/agent/` on every launch
-4. `cli.ts` calls pi-coding-agent's `main()` — pi handles everything from there
+3. `loader.ts` injects `--mcp-config ~/.kata-cli/agent/mcp.json` into `process.argv` for the MCP adapter
+4. `resource-loader.ts` syncs bundled extensions, agents, skills, and `AGENTS.md` to `~/.kata-cli/agent/` on every launch
+5. `resource-loader.ts` scaffolds a starter `mcp.json` on first launch (never overwrites existing config)
+6. `cli.ts` seeds `npm:pi-mcp-adapter` into settings so pi auto-installs it
+7. `cli.ts` injects the `mcp-config` flag into the extension runtime (required because Kata bypasses pi's `main()` and its two-pass argv parsing)
+8. `cli.ts` calls `createAgentSession()` + `InteractiveMode` — pi handles everything from there
 
 ## Bundled Extensions
 
@@ -64,6 +68,136 @@ apps/cli/
 | `mac-tools/` | macOS-specific utilities |
 | `shared/` | Shared UI components (library, not an entry point) |
 
+## MCP Support
+
+Kata ships with [MCP](https://modelcontextprotocol.io/) (Model Context Protocol) support via [`pi-mcp-adapter`](https://github.com/nicobailon/pi-mcp-adapter), auto-installed on first launch. One proxy `mcp` tool (~200 tokens in context) gives the agent on-demand access to any MCP server's tools without burning context on individual tool definitions.
+
+### How It Works
+
+The MCP integration has three parts:
+
+1. **Package seeding**: `cli.ts` ensures `npm:pi-mcp-adapter` is in the settings packages list on every startup. Pi's package manager auto-installs it globally if missing.
+2. **Config path injection**: `loader.ts` pushes `--mcp-config` into `process.argv` and `cli.ts` sets the flag on `runtime.flagValues` — both are needed because the adapter reads the config path at two different points in its lifecycle.
+3. **Config scaffolding**: `resource-loader.ts` creates a starter `~/.kata-cli/agent/mcp.json` on first launch. Never overwrites existing config.
+
+### Adding MCP Servers
+
+Edit `~/.kata-cli/agent/mcp.json`:
+
+```json
+{
+  "settings": {
+    "toolPrefix": "server",
+    "idleTimeout": 10
+  },
+  "mcpServers": {}
+}
+```
+
+#### Example: Linear (OAuth via mcp-remote)
+
+Many hosted MCP servers (Linear, etc.) use OAuth 2.1 authentication. These require [`mcp-remote`](https://github.com/geelen/mcp-remote) as a stdio proxy that handles the browser-based OAuth flow:
+
+```json
+{
+  "settings": { "toolPrefix": "server", "idleTimeout": 10 },
+  "mcpServers": {
+    "linear": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://mcp.linear.app/mcp"]
+    }
+  }
+}
+```
+
+After adding the config and restarting Kata:
+
+1. Connect the server (opens browser for OAuth):
+   ```
+   mcp({ connect: "linear" })
+   ```
+2. Authorize in the browser when prompted by Linear.
+3. Use tools:
+   ```
+   mcp({ server: "linear" })              — list all Linear tools
+   mcp({ search: "issues" })              — search for issue-related tools
+   mcp({ tool: "linear_list_teams" })     — call a tool
+   ```
+
+Tokens are cached in `~/.mcp-auth/` for subsequent sessions. If you hit errors, clear cached auth with `rm -rf ~/.mcp-auth` and reconnect.
+
+#### Example: Stdio server with env vars
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "npx",
+      "args": ["-y", "some-mcp-server"],
+      "env": {
+        "API_KEY": "${MY_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+Environment variables support `${VAR}` interpolation from `process.env`.
+
+#### Example: HTTP server with bearer token
+
+```json
+{
+  "mcpServers": {
+    "my-api": {
+      "url": "https://api.example.com/mcp",
+      "auth": "bearer",
+      "bearerTokenEnv": "MY_API_KEY"
+    }
+  }
+}
+```
+
+#### Importing existing configs
+
+Pull in your existing Claude Code, Cursor, or VS Code MCP configuration:
+
+```json
+{
+  "imports": ["claude-code", "cursor"],
+  "mcpServers": {}
+}
+```
+
+Supported: `cursor`, `claude-code`, `claude-desktop`, `vscode`, `windsurf`, `codex`.
+
+### Server Lifecycle
+
+| Mode | Behavior |
+|------|----------|
+| `lazy` (default) | Connect on first tool call. Disconnect after idle timeout. Cached metadata keeps search/list working offline. |
+| `eager` | Connect at startup. No auto-reconnect on drop. |
+| `keep-alive` | Connect at startup. Auto-reconnect via health checks. |
+
+### Usage Reference
+
+| Command | Description |
+|---------|-------------|
+| `mcp({ })` | Show server status |
+| `mcp({ server: "name" })` | List tools from a server |
+| `mcp({ search: "query" })` | Search tools (space-separated words OR'd) |
+| `mcp({ describe: "tool_name" })` | Show tool parameters |
+| `mcp({ tool: "name", args: '{}' })` | Call a tool (args is a JSON string) |
+| `mcp({ connect: "name" })` | Force connect/reconnect a server |
+| `/mcp` | Interactive panel (status, tools, reconnect) |
+
+### Known Limitations
+
+- **OAuth servers require `mcp-remote`**: The adapter doesn't implement the MCP OAuth browser flow natively. Use `mcp-remote` as a stdio proxy for OAuth servers.
+- **Figma remote MCP** (`mcp.figma.com`): Blocks dynamic client registration — only whitelisted clients can connect via OAuth. Use Figma's desktop app local MCP server instead (`http://127.0.0.1:3845/mcp`), which requires Dev Mode (paid plan).
+- **Metadata cache**: `pi-mcp-adapter` caches tool metadata to `~/.pi/agent/mcp-cache.json` (hardcoded path, doesn't affect functionality).
+- **OAuth token storage**: `mcp-remote` stores tokens in `~/.mcp-auth/`, separate from Kata's config dir.
+
 ## The /kata Command
 
 The main extension registers `/kata` with subcommands:
@@ -111,8 +245,9 @@ Kata uses `~/.kata-cli/` (not `~/.kata/`) to avoid collision with other Kata app
     agents/              — Synced from src/resources/agents/
     skills/              — Synced from src/resources/skills/
     AGENTS.md            — Synced from src/resources/AGENTS.md
+    mcp.json             — MCP server configuration (scaffolded on first launch, never overwritten)
     auth.json            — API keys
-    settings.json        — User settings
+    settings.json        — User settings (includes packages: ["npm:pi-mcp-adapter"])
     models.json          — Custom model definitions
   sessions/              — Session history
   preferences.md         — Global Kata preferences
@@ -130,6 +265,7 @@ Set by `loader.ts` before pi starts:
 | `KATA_BIN_PATH` | Absolute path to loader, used by subagent |
 | `KATA_WORKFLOW_PATH` | Absolute path to bundled KATA-WORKFLOW.md |
 | `KATA_BUNDLED_EXTENSION_PATHS` | Colon-joined extension entry points for subagent |
+| `KATA_MCP_CONFIG_PATH` | Absolute path to `~/.kata-cli/agent/mcp.json` |
 
 ## Development
 
@@ -143,7 +279,7 @@ npm run copy-themes
 # Run
 node dist/loader.js
 
-# Test
+# Test (37 tests: app smoke, resource sync, MCP integration, package validation)
 npm test
 ```
 

package/dist/cli.js

@@ -36,10 +36,30 @@ if (!settingsManager.getQuietStartup()) {
 if (!settingsManager.getCollapseChangelog()) {
     settingsManager.setCollapseChangelog(true);
 }
+// Ensure pi-mcp-adapter is in the packages list so pi auto-installs it on startup.
+// Bootstrap only when packages have never been configured. If users later remove the
+// adapter from settings.json, that opt-out should persist.
+const MCP_ADAPTER_PACKAGE = 'npm:pi-mcp-adapter';
+const globalSettings = settingsManager.getGlobalSettings();
+const globalPackages = [...(globalSettings.packages ?? [])];
+const hasConfiguredPackages = Object.prototype.hasOwnProperty.call(globalSettings, "packages");
+if (!hasConfiguredPackages && !globalPackages.includes(MCP_ADAPTER_PACKAGE)) {
+    settingsManager.setPackages([...globalPackages, MCP_ADAPTER_PACKAGE]);
+}
+await settingsManager.flush();
 const sessionManager = SessionManager.create(process.cwd(), sessionsDir);
 initResources(agentDir);
 const resourceLoader = buildResourceLoader(agentDir);
 await resourceLoader.reload();
+// Inject --mcp-config flag value into the extension runtime.
+// pi-mcp-adapter reads this via pi.getFlag("mcp-config") at session_start.
+// Kata doesn't call pi's main() which does the two-pass argv parsing that
+// normally populates flagValues, so we must do it manually here.
+const mcpConfigPath = process.env.KATA_MCP_CONFIG_PATH;
+if (mcpConfigPath) {
+    const extResult = resourceLoader.getExtensions();
+    extResult.runtime.flagValues.set('mcp-config', mcpConfigPath);
+}
 const { session, extensionsResult } = await createAgentSession({
     authStorage,
     modelRegistry,

package/dist/loader.js

@@ -91,5 +91,15 @@ process.env.KATA_BUNDLED_EXTENSION_PATHS = [
     join(agentDir, "extensions", "ask-user-questions.ts"),
     join(agentDir, "extensions", "get-secrets-from-user.ts"),
 ].join(":");
+// KATA_MCP_CONFIG_PATH — absolute path to Kata's MCP config file.
+// pi-mcp-adapter reads --mcp-config from process.argv directly (before session_start fires).
+// We inject it here so the adapter uses ~/.kata-cli/agent/mcp.json instead of the
+// default ~/.pi/agent/mcp.json.
+const mcpConfigPath = join(agentDir, "mcp.json");
+process.env.KATA_MCP_CONFIG_PATH = mcpConfigPath;
+const hasMcpConfigArg = process.argv.some((arg) => arg === "--mcp-config" || arg.startsWith("--mcp-config="));
+if (!hasMcpConfigArg) {
+    process.argv.push("--mcp-config", mcpConfigPath);
+}
 // Dynamic import defers ESM evaluation — config.js will see PI_PACKAGE_DIR above
 await import("./cli.js");

package/dist/resource-loader.js

@@ -2,6 +2,19 @@ import { DefaultResourceLoader } from '@mariozechner/pi-coding-agent';
 import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+/**
+ * Starter mcp.json written to agentDir on first launch.
+ * Uses the `imports` field so users can pull in their existing Claude/Cursor config.
+ * mcpServers is intentionally empty — users add their own servers here.
+ */
+const STARTER_MCP_JSON = JSON.stringify({
+    imports: [],
+    settings: {
+        toolPrefix: 'server',
+        idleTimeout: 10,
+    },
+    mcpServers: {},
+}, null, 2) + '\n';
 // Resolves to the bundled src/resources/ inside the npm package at runtime:
 //   dist/resource-loader.js → .. → package root → src/resources/
 const resourcesDir = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'src', 'resources');
@@ -39,6 +52,12 @@ export function initResources(agentDir) {
     if (existsSync(srcAgentsMd)) {
         writeFileSync(destAgentsMd, readFileSync(srcAgentsMd));
     }
+    // Scaffold starter mcp.json — only if it doesn't exist yet.
+    // Never overwrite: preserve the user's MCP server configuration.
+    const mcpConfigPath = join(agentDir, 'mcp.json');
+    if (!existsSync(mcpConfigPath)) {
+        writeFileSync(mcpConfigPath, STARTER_MCP_JSON, 'utf-8');
+    }
 }
 /**
  * Constructs a DefaultResourceLoader with no additionalExtensionPaths.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kata-sh/cli",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Kata CLI coding agent",
   "license": "MIT",
   "private": false,

package/src/resources/AGENTS.md

@@ -9,7 +9,7 @@ Kata CLI is a thin wrapper around pi-coding-agent that provides:
 - **Branded entry point**: `src/loader.ts` sets env vars and launches `src/cli.ts`
 - **Bundled extensions**: `src/resources/extensions/` contains all built-in extensions
 - **Resource syncing**: `src/resource-loader.ts` copies bundled extensions to `~/.kata-cli/agent/` on startup
-- **Config directory**: `~/.kata-cli/` (not `~/.kata-cli/` to avoid collision with other Kata apps)
+- **Config directory**: `~/.kata-cli/` (not `~/.pi/` to avoid collision with other Kata apps)
 - **Package shim**: `pkg/package.json` provides `piConfig` with `name: "kata"` and `configDir: ".kata-cli"`
 
 ## Directory Structure
@@ -18,7 +18,7 @@ Kata CLI is a thin wrapper around pi-coding-agent that provides:
 apps/cli/
   src/
     loader.ts              — Entry point, sets KATA_* env vars, imports cli.ts
-    cli.ts                 — Thin wrapper that calls pi-coding-agent's main()
+    cli.ts                 — Thin wrapper that calls createAgentSession() + InteractiveMode
     app-paths.ts           — Exports appRoot, agentDir, sessionsDir, authFilePath
     resource-loader.ts     — Syncs bundled resources to ~/.kata-cli/agent/
     wizard.ts              — First-run setup, env key hydration
@@ -55,6 +55,7 @@ Kata sets these env vars in `loader.ts` before importing `cli.ts`:
 | `KATA_BIN_PATH` | Absolute path to loader, used by subagent to spawn Kata |
 | `KATA_WORKFLOW_PATH` | Absolute path to bundled KATA-WORKFLOW.md |
 | `KATA_BUNDLED_EXTENSION_PATHS` | Colon-joined list of extension entry points |
+| `KATA_MCP_CONFIG_PATH` | Absolute path to `~/.kata-cli/agent/mcp.json` (also injected as `--mcp-config` argv) |
 
 ## The /kata Command
 
@@ -99,6 +100,156 @@ Kata stores project state in `.kata/` at the project root:
 - **Copy themes**: `npm run copy-themes` (copies theme assets from pi-coding-agent)
 - **Dependencies**: Consumed via npm from `@mariozechner/pi-coding-agent` — never fork
 
+## MCP Support
+
+Kata ships with MCP (Model Context Protocol) support via [`pi-mcp-adapter`](https://github.com/nicobailon/pi-mcp-adapter), auto-installed on first launch. One proxy `mcp` tool (~200 tokens) gives the agent on-demand access to any MCP server's tools without burning context on tool definitions.
+
+### How it works
+
+There are three integration points that make MCP work in Kata:
+
+1. **Package seeding** (`cli.ts`): Seeds `npm:pi-mcp-adapter` into `settingsManager.getPackages()` on every startup. Pi's package manager auto-installs it globally if missing.
+
+2. **Config path injection** (`loader.ts` + `cli.ts`): Kata bypasses pi's `main()` and calls `createAgentSession()` directly, which means pi's two-pass argv parsing (that normally populates `runtime.flagValues`) never runs. Two things compensate:
+   - `loader.ts` pushes `--mcp-config ~/.kata-cli/agent/mcp.json` into `process.argv` — the adapter reads this at extension load time for `directTools` registration.
+   - `cli.ts` manually sets `runtime.flagValues.set('mcp-config', ...)` after `resourceLoader.reload()` — the adapter reads this via `pi.getFlag('mcp-config')` at `session_start` for the main initialization.
+
+3. **Config scaffolding** (`resource-loader.ts`): Creates a starter `~/.kata-cli/agent/mcp.json` on first launch. Never overwrites existing config.
+
+### Configuring MCP servers
+
+Edit `~/.kata-cli/agent/mcp.json` to add servers. Servers can use **stdio** (local process) or **HTTP** (remote endpoint) transport.
+
+#### Stdio servers (local process)
+
+Most MCP servers run as a local process via `npx`:
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "npx",
+      "args": ["-y", "some-mcp-server"],
+      "env": {
+        "API_KEY": "${MY_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+Environment variables support `${VAR}` interpolation from `process.env`.
+
+#### HTTP servers with OAuth (e.g. Linear)
+
+Many hosted MCP servers (Linear, Figma, etc.) use OAuth 2.1 authentication via the MCP spec. These require [`mcp-remote`](https://github.com/geelen/mcp-remote) as a stdio proxy that handles the OAuth browser flow:
+
+```json
+{
+  "mcpServers": {
+    "linear": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://mcp.linear.app/mcp"]
+    }
+  }
+}
+```
+
+On first connection, `mcp-remote` opens a browser window for OAuth consent. Tokens are cached in `~/.mcp-auth/` for subsequent sessions.
+
+**Linear MCP setup (complete example):**
+
+1. Add the server to `~/.kata-cli/agent/mcp.json`:
+   ```json
+   {
+     "settings": { "toolPrefix": "server", "idleTimeout": 10 },
+     "mcpServers": {
+       "linear": {
+         "command": "npx",
+         "args": ["-y", "mcp-remote", "https://mcp.linear.app/mcp"]
+       }
+     }
+   }
+   ```
+
+2. Restart Kata.
+
+3. Connect the server (triggers the OAuth flow in your browser):
+   ```
+   mcp({ connect: "linear" })
+   ```
+
+4. Authorize Kata in the browser when prompted by Linear.
+
+5. Use Linear tools:
+   ```
+   mcp({ server: "linear" })          — list all Linear tools
+   mcp({ search: "issues" })          — search for issue-related tools
+   mcp({ tool: "linear_list_teams" }) — call a specific tool
+   ```
+
+**Troubleshooting OAuth:**
+- If you see `internal server error`, clear cached auth: `rm -rf ~/.mcp-auth` and reconnect.
+- Make sure you're running a recent version of Node.js.
+- Use `/mcp` to check server status interactively.
+
+#### HTTP servers with bearer token auth
+
+For servers that accept API keys or personal access tokens:
+
+```json
+{
+  "mcpServers": {
+    "my-api": {
+      "url": "https://api.example.com/mcp",
+      "auth": "bearer",
+      "bearerTokenEnv": "MY_API_KEY"
+    }
+  }
+}
+```
+
+#### Importing existing configs
+
+Pull in your existing Claude Code, Cursor, or VS Code MCP configuration:
+
+```json
+{
+  "imports": ["claude-code", "cursor"],
+  "mcpServers": {}
+}
+```
+
+Supported sources: `cursor`, `claude-code`, `claude-desktop`, `vscode`, `windsurf`, `codex`.
+
+### Server lifecycle
+
+| Mode | Behavior |
+|------|----------|
+| `lazy` (default) | Connect on first tool call. Disconnect after idle timeout. Cached metadata keeps search/list working offline. |
+| `eager` | Connect at startup. No auto-reconnect on drop. |
+| `keep-alive` | Connect at startup. Auto-reconnect via health checks. |
+
+### Usage
+
+```
+mcp({ })                                 — show server status
+mcp({ server: "linear" })               — list tools from a server
+mcp({ search: "issues create" })         — search tools (space-separated words OR'd)
+mcp({ describe: "linear_save_issue" })   — show tool parameters
+mcp({ tool: "linear_list_teams" })       — call a tool (no args)
+mcp({ tool: "linear_save_issue", args: '{"title": "Bug fix"}' })  — call with args (JSON string)
+mcp({ connect: "linear" })               — force connect/reconnect a server
+/mcp                                      — interactive panel (status, tools, reconnect, OAuth)
+```
+
+### Known limitations
+
+- **OAuth servers require `mcp-remote`**: The adapter doesn't implement the MCP OAuth browser flow natively. Use `mcp-remote` as a stdio proxy for any server that requires OAuth (Linear, Figma remote, etc.).
+- **Figma remote MCP (`mcp.figma.com`)**: Blocks dynamic client registration — only whitelisted clients (Cursor, Claude Code, VS Code) can connect via OAuth. Use the Figma desktop app's local MCP server instead (`http://127.0.0.1:3845/mcp`), which requires Figma desktop with Dev Mode (paid plan).
+- **Metadata cache path**: `pi-mcp-adapter` caches tool metadata to `~/.pi/agent/mcp-cache.json` (hardcoded). This doesn't affect functionality — just means the cache lives outside Kata's config dir.
+- **OAuth token storage**: `mcp-remote` stores tokens in `~/.mcp-auth/`, separate from Kata's config dir.
+
 ## Key Conventions
 
 - All env var names use `KATA_` prefix (not `GSD_` or `PI_`)
@@ -106,3 +257,4 @@ Kata stores project state in `.kata/` at the project root:
 - Extensions are synced from `src/resources/extensions/` to `~/.kata-cli/agent/extensions/` on every launch
 - The `shared/` extension directory is a library, not an entry point — it's imported by other extensions
 - Branch naming for workflow: `kata/M001/S01` (milestone/slice)
+- MCP config lives at `~/.kata-cli/agent/mcp.json` (not `~/.pi/agent/mcp.json`)

package/src/resources/extensions/kata/preferences.ts

@@ -398,8 +398,9 @@ function parseFrontmatterBlock(frontmatter: string): KataPreferences {
     const valuePart = remainder.trim();
 
     if (valuePart === "") {
-      const nextLine = lines[i + 1] ?? "";
-      const nextTrimmed = nextLine.trim();
+      const nextNonEmptyLine =
+        lines.slice(i + 1).find((candidate) => candidate.trim() !== "") ?? "";
+      const nextTrimmed = nextNonEmptyLine.trim();
       if (nextTrimmed.startsWith("- ")) {
         const items: unknown[] = [];
         let j = i + 1;
@@ -481,9 +482,16 @@ function parseFrontmatterBlock(frontmatter: string): KataPreferences {
         current[key] = items;
         i = j - 1;
       } else {
-        const obj: Record<string, unknown> = {};
-        current[key] = obj;
-        stack.push({ indent, value: obj });
+        // Check if the next non-empty line is actually indented deeper (a real nested block).
+        // If not, this key simply has no value — skip it rather than creating an empty object.
+        const nextIndent =
+          nextNonEmptyLine.match(/^\s*/)?.[0].length ?? indent;
+        if (nextIndent > indent) {
+          const obj: Record<string, unknown> = {};
+          current[key] = obj;
+          stack.push({ indent, value: obj });
+        }
+        // else: key with no value and no nested block — leave it undefined
       }
       continue;
     }
@@ -494,9 +502,13 @@ function parseFrontmatterBlock(frontmatter: string): KataPreferences {
   return root as KataPreferences;
 }
 
-function parseScalar(value: string): string | number | boolean {
+function parseScalar(
+  value: string,
+): string | number | boolean | unknown[] | Record<string, never> {
   if (value === "true") return true;
   if (value === "false") return false;
+  if (value === "[]") return [];
+  if (value === "{}") return {};
   if (/^-?\d+$/.test(value)) return Number(value);
   return value.replace(/^['\"]|['\"]$/g, "");
 }

package/src/resources/extensions/kata/tests/preferences-frontmatter.test.mjs

@@ -0,0 +1,53 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const resolveTsHookPath = fileURLToPath(new URL('./resolve-ts.mjs', import.meta.url));
+const preferencesPath = fileURLToPath(new URL('../preferences.ts', import.meta.url));
+
+test('loadEffectiveKataPreferences preserves blank-line-separated skill_rules lists', () => {
+  const tmp = mkdtempSync(join(tmpdir(), 'kata-preferences-frontmatter-'));
+  const kataDir = join(tmp, '.kata');
+  mkdirSync(kataDir, { recursive: true });
+  writeFileSync(
+    join(kataDir, 'preferences.md'),
+    `---
+skill_rules:
+
+  - when: build
+    use:
+      - test-driven-development
+---
+`,
+  );
+
+  const script = `
+    import { loadEffectiveKataPreferences } from ${JSON.stringify(preferencesPath)};
+    const prefs = loadEffectiveKataPreferences();
+    console.log(JSON.stringify(prefs?.preferences.skill_rules ?? null));
+  `;
+
+  const output = execFileSync(
+    'node',
+    ['--import', resolveTsHookPath, '--experimental-strip-types', '-e', script],
+    {
+      cwd: tmp,
+      env: {
+        ...process.env,
+        HOME: tmp,
+      },
+      encoding: 'utf-8',
+    },
+  ).trim();
+
+  assert.deepEqual(JSON.parse(output), [
+    {
+      when: 'build',
+      use: ['test-driven-development'],
+    },
+  ]);
+});