kyro-ai 3.3.2 → 3.4.1

package/docs/release-3.4.0.md

@@ -0,0 +1,42 @@
+# Kyro AI 3.4.0 Release Notes
+
+## Summary
+
+Kyro 3.4.0 stabilizes the adapter harness v1 release. It adds concrete OpenCode and Codex adapter projections, keeps Claude plugin support first-class, and hardens sync/uninstall behavior around managed files, shared config, drift, prune, purge, and dry-run safety.
+
+## Highlights
+
+- Adapter harness v1 for `standard`, `opencode`, and `codex`.
+- `kyro detect` and adapter inventory through `kyro doctor --adapters`.
+- OpenCode native skills, `/kyro/*` command files, and a Kyro-owned `agent.kyro-orchestrator` overlay.
+- Codex command skills plus a managed root `AGENTS.md` block.
+- Global runtime under `~/.agents/kyro/versions/{version}` with `current` symlink.
+- Project-local state under `.agents/kyro/`.
+- `kyro sync` refreshes installed adapters without silently adding `standard`.
+- `kyro sync --prune` removes stale runtime versions and obsolete Kyro-owned adapter entrypoints.
+- Shared config such as `~/.config/opencode/opencode.json` is preserved and reported separately.
+- `kyro uninstall --purge-adapter-assets` explicitly removes adapter entrypoints while preserving shared config.
+- Dry-run behavior is covered for prune and purge paths.
+- Pipeline rollback and managed block/JSON merge behavior are covered by fixtures.
+
+## Non-Goals
+
+- No generic adapter is provided.
+- Cursor remains planned until concrete projection behavior is defined.
+- Claude plugin support is not replaced by the CLI adapter path.
+- MCP remains modeled but inactive until there is a concrete Kyro MCP server contract.
+
+## Validation
+
+```bash
+npm run build
+npm run check
+npm run check:adapters
+npm_config_cache=/tmp/kyro-npm-cache npm pack --dry-run
+```
+
+Additional smoke coverage was run with an isolated `HOME` and workspace under `/tmp`, covering install, doctor, sync dry-run, prune dry-run, uninstall, purge, and host binary detection for OpenCode and Codex.
+
+## Notes
+
+`doctor --adapters` now treats the global runtime as the files under `~/.agents/kyro/`. Adapter entrypoints are validated through installed adapter projection checks, so purging adapter assets after uninstall does not make the preserved global runtime appear broken.

package/docs/release-agent-platform-v2.md

@@ -0,0 +1,21 @@
+# Agent Platform V2 Release Notes
+
+This scope expands Kyro from adapter harness v1 into a host-aware agent platform slice.
+
+Added:
+
+- Cursor workspace adapter at `.cursor/rules/kyro-ai.mdc`
+- Claude CLI-native workspace skills under `.claude/skills/kyro-*`
+- `kyro adapter matrix` and `kyro adapter matrix --json`
+- `kyro doctor --migration` and `kyro doctor --migration --json`
+- JSON output for install/sync planning
+- read-only `kyro mcp serve`
+- `npm run smoke:adapters`
+- adapter, migration, MCP, and smoke test docs
+
+Safety behavior:
+
+- Normal install/sync does not enable MCP host config.
+- Cursor uninstall removes only the Kyro-owned rule file.
+- Claude CLI-native install does not modify `.claude-plugin/`.
+- `sync --prune` preserves shared host config.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kyro-ai",
-  "version": "3.3.2",
+  "version": "3.4.1",
   "description": "Portable sprint workflow kit for AI coding agents, with markdown artifacts, adapter guides, and formal debt tracking",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -16,7 +16,8 @@
     "check:tokens": "node dist/cli.js doctor --tokens",
     "check:artifacts": "node dist/cli.js doctor --artifacts",
     "check:artifact-fixtures": "node scripts/check-artifact-fixtures.mjs",
-    "check:adapters": "node scripts/check-adapter-fixtures.mjs"
+    "check:adapters": "node scripts/check-adapter-fixtures.mjs",
+    "smoke:adapters": "node scripts/smoke-adapters.mjs"
   },
   "keywords": [
     "ai-agents",

package/scripts/check-adapter-fixtures.mjs

@@ -70,6 +70,8 @@ function cliOptions(overrides = {}) {
     json: false,
     purgeAdapterAssets: false,
     prune: false,
+    migration: false,
+    enableMcp: false,
     ...overrides,
   };
 }
@@ -113,11 +115,15 @@ function assertStandardCommandSkills(plan, name) {
 const standardPlan = dryRunPlan('standard');
 const openCodePlan = dryRunPlan('opencode');
 const codexPlan = dryRunPlan('codex');
-const combinedPlan = dryRunPlan('standard,opencode,codex');
+const cursorPlan = dryRunPlan('cursor');
+const claudePlan = dryRunPlan('claude');
+const combinedPlan = dryRunPlan('standard,opencode,codex,cursor,claude');
 
 assertCommonPlan(standardPlan, 'standard');
 assertCommonPlan(openCodePlan, 'opencode');
 assertCommonPlan(codexPlan, 'codex');
+assertCommonPlan(cursorPlan, 'cursor');
+assertCommonPlan(claudePlan, 'claude');
 assertCommonPlan(combinedPlan, 'combined');
 assertStandardCommandSkills(standardPlan, 'standard');
 assertStandardCommandSkills(codexPlan, 'codex');
@@ -127,10 +133,15 @@ assert(!standardPlan.includes('- upsert-block AGENTS.md # agents-md'), 'standard
 assert(!openCodePlan.includes('- upsert-block AGENTS.md # agents-md'), 'opencode: should not manage AGENTS.md block');
 assert(codexPlan.includes('- upsert-block AGENTS.md # agents-md'), 'codex: should manage AGENTS.md block');
 assert(combinedPlan.includes('- upsert-block AGENTS.md # agents-md'), 'combined: should manage AGENTS.md block once');
+assert(cursorPlan.includes('- write .cursor/rules/kyro-ai.mdc'), 'cursor: missing workspace rule projection');
+assert(claudePlan.includes('- write .claude/skills/kyro-forge/SKILL.md'), 'claude: missing CLI-native skill projection');
+assert(!claudePlan.includes('.claude-plugin'), 'claude: CLI-native projection should not touch .claude-plugin');
 
 assert(standardPlan.includes('- standard: status=implemented;'), 'standard: missing preflight status');
 assert(openCodePlan.includes('- opencode: status=implemented;'), 'opencode: missing preflight status');
 assert(codexPlan.includes('- codex: status=implemented;'), 'codex: missing preflight status');
+assert(cursorPlan.includes('- cursor: status=implemented;'), 'cursor: missing preflight status');
+assert(claudePlan.includes('- claude: status=implemented;'), 'claude: missing preflight status');
 assert(openCodePlan.includes('- write ~/.config/opencode/skills/kyro-forge/SKILL.md'), 'opencode: missing native forge skill projection');
 assert(openCodePlan.includes('- write ~/.config/opencode/commands/kyro/forge.md'), 'opencode: missing native forge command projection');
 assert(openCodePlan.includes('- merge-json ~/.config/opencode/opencode.json'), 'opencode: missing native settings overlay');
@@ -138,20 +149,6 @@ assert(!openCodePlan.includes('- write ~/.agents/skills/kyro-forge/SKILL.md'), '
 assert(countIncludes(combinedPlan, '- write ~/.agents/skills/kyro-forge/SKILL.md') === 1, 'combined: forge skill should be projected once');
 assert(countIncludes(combinedPlan, '- upsert-block AGENTS.md # agents-md') === 1, 'combined: AGENTS.md block should be projected once');
 
-withWorkspace('kyro-adapter-preflight-', () => {
-  const { parseAgent } = require(join(repo, 'dist/cli/options.js'));
-  const { install } = require(join(repo, 'dist/cli/commands/install.js'));
-  let failed = false;
-  try {
-    captureLogs(() => install(cliOptions({ agents: [parseAgent('claude')], dryRun: true })));
-  } catch (error) {
-    failed = true;
-    assert(String(error).includes('not implemented yet: claude'), 'preflight: planned adapter failure should name claude');
-    assert(String(error).includes('native projection'), 'preflight: planned adapter failure should mention native projection');
-  }
-  assert(failed, 'preflight: expected planned adapter install to fail');
-});
-
 {
   const { mergeJsonObjectContent } = require(join(repo, 'dist/cli/injectors/json-merge.js'));
   const merged = mergeJsonObjectContent(`{
@@ -268,9 +265,11 @@ withWorkspace('kyro-adapter-contract-', (cwd) => {
   assert(byAgent.codex.mcpStrategy() === 'toml-file', 'codex: unexpected MCP strategy');
   assert(byAgent.codex.detect({ homeDir, envPath: '' }).configFound === true, 'codex: expected config detection');
 
-  assert(byAgent.claude.status === 'planned', 'claude: expected planned status');
+  assert(byAgent.claude.status === 'implemented', 'claude: expected implemented status');
+  assert(byAgent.claude.capabilities().includes('command-skills'), 'claude: missing command skill capability');
   assert(byAgent.claude.paths(homeDir).subAgentsDir.endsWith('/.claude/agents'), 'claude: unexpected sub-agent path');
-  assert(byAgent.cursor.status === 'planned', 'cursor: expected planned status');
+  assert(byAgent.cursor.status === 'implemented', 'cursor: expected implemented status');
+  assert(byAgent.cursor.capabilities().includes('system-prompt'), 'cursor: missing rule/system prompt capability');
   assert(byAgent.cursor.systemPromptStrategy() === 'instructions-file', 'cursor: unexpected system prompt strategy');
 });
 
@@ -309,10 +308,65 @@ withWorkspace('kyro-adapter-install-', (installDir) => {
   assert(agentsText.includes('Keep this user content.'), 'uninstall: user AGENTS.md content was not preserved');
 });
 
+withWorkspace('kyro-adapter-cursor-install-', (installDir) => {
+  const { parseAgent } = require(join(repo, 'dist/cli/options.js'));
+  const { install, sync } = require(join(repo, 'dist/cli/commands/install.js'));
+  const { uninstall } = require(join(repo, 'dist/cli/commands/uninstall.js'));
+  const { doctor } = require(join(repo, 'dist/cli/commands/doctor.js'));
+  const cursor = parseAgent('cursor');
+  const userRulePath = join(installDir, '.cursor', 'rules', 'user-owned.mdc');
+  mkdirSync(join(installDir, '.cursor', 'rules'), { recursive: true });
+  writeFileSync(userRulePath, '# User rule\n\nKeep this rule.\n', 'utf-8');
+
+  const dryRun = captureLogs(() => install(cliOptions({ agents: [cursor], dryRun: true })));
+  assert(dryRun.includes('- write .cursor/rules/kyro-ai.mdc'), 'cursor dry-run: missing Kyro rule write');
+  assert(!existsSync(join(installDir, '.cursor', 'rules', 'kyro-ai.mdc')), 'cursor dry-run: should not write Kyro rule');
+
+  captureLogs(() => install(cliOptions({ agents: [cursor] })));
+  const kyroRulePath = join(installDir, '.cursor', 'rules', 'kyro-ai.mdc');
+  assert(existsSync(kyroRulePath), 'cursor install: missing Kyro rule');
+  assert(readFileSync(kyroRulePath, 'utf-8').includes('~/.agents/kyro/current'), 'cursor install: rule should reference global runtime');
+  assert(readFileSync(userRulePath, 'utf-8').includes('Keep this rule.'), 'cursor install: user rule should be preserved');
+
+  const doctorOutput = captureLogs(() => doctor(cliOptions({ adapters: true })));
+  assert(doctorOutput.includes('[PASS] Cursor adapter'), 'cursor doctor: adapter should pass after install');
+
+  captureLogs(() => sync(cliOptions({ agents: [cursor] })));
+  assert(readFileSync(userRulePath, 'utf-8').includes('Keep this rule.'), 'cursor sync: user rule should be preserved');
+
+  captureLogs(() => uninstall(cliOptions({ purgeAdapterAssets: true })));
+  assert(!existsSync(kyroRulePath), 'cursor uninstall purge: Kyro rule should be removed');
+  assert(existsSync(userRulePath), 'cursor uninstall purge: user rule should be preserved');
+});
+
+withWorkspace('kyro-adapter-claude-install-', (installDir) => {
+  const { parseAgent } = require(join(repo, 'dist/cli/options.js'));
+  const { install } = require(join(repo, 'dist/cli/commands/install.js'));
+  const { uninstall } = require(join(repo, 'dist/cli/commands/uninstall.js'));
+  const claude = parseAgent('claude');
+  const pluginPath = join(installDir, '.claude-plugin', 'plugin.json');
+  mkdirSync(join(installDir, '.claude-plugin'), { recursive: true });
+  writeFileSync(pluginPath, '{ "name": "user-plugin-fixture" }\n', 'utf-8');
+
+  captureLogs(() => install(cliOptions({ agents: [claude] })));
+  for (const command of ['forge', 'status', 'wrap-up']) {
+    const skillPath = join(installDir, '.claude', 'skills', `kyro-${command}`, 'SKILL.md');
+    assert(existsSync(skillPath), `claude install: missing CLI-native skill ${command}`);
+  }
+  assert(readFileSync(pluginPath, 'utf-8').includes('user-plugin-fixture'), 'claude install: .claude-plugin should be untouched');
+
+  captureLogs(() => uninstall(cliOptions({ purgeAdapterAssets: true })));
+  for (const command of ['forge', 'status', 'wrap-up']) {
+    assert(!existsSync(join(installDir, '.claude', 'skills', `kyro-${command}`, 'SKILL.md')), `claude uninstall purge: skill ${command} should be removed`);
+  }
+  assert(readFileSync(pluginPath, 'utf-8').includes('user-plugin-fixture'), 'claude uninstall purge: .claude-plugin should be untouched');
+});
+
 withWorkspace('kyro-adapter-opencode-install-', (installDir) => {
   const { parseAgent } = require(join(repo, 'dist/cli/options.js'));
   const { install, sync } = require(join(repo, 'dist/cli/commands/install.js'));
   const { uninstall } = require(join(repo, 'dist/cli/commands/uninstall.js'));
+  const { doctor } = require(join(repo, 'dist/cli/commands/doctor.js'));
   const opencode = parseAgent('opencode');
   const home = join(installDir, '.home');
   const settingsPath = join(home, '.config', 'opencode', 'opencode.json');
@@ -397,6 +451,10 @@ withWorkspace('kyro-adapter-opencode-install-', (installDir) => {
   }
   assert(!existsSync(join(home, '.config', 'opencode', 'commands', 'kyro')), 'opencode purge: empty command namespace still present');
   assert(existsSync(join(home, '.config', 'opencode')), 'opencode purge: shared OpenCode config directory should remain');
+
+  const doctorAfterPurgeOutput = captureLogs(() => doctor(cliOptions({ adapters: true })));
+  assert(doctorAfterPurgeOutput.includes('[PASS] global runtime'), 'opencode purge doctor: global runtime should remain valid after purging adapter assets');
+  assert(!doctorAfterPurgeOutput.includes('[FAIL]'), 'opencode purge doctor: should not fail after purging adapter assets');
 });
 
 withWorkspace('kyro-pipeline-rollback-', (cwd) => {
@@ -455,7 +513,6 @@ withWorkspace('kyro-adapter-doctor-', () => {
     assert(output.includes(`adapter inventory: ${agent}`), `doctor --adapters: missing ${agent}`);
   }
   assert(output.includes('status=implemented'), 'doctor --adapters: missing implemented status');
-  assert(output.includes('status=planned'), 'doctor --adapters: missing planned status');
   assert(output.includes('capabilities=command-skills'), 'doctor --adapters: missing command-skills capability');
   assert(output.includes('workspace-agents-block'), 'doctor --adapters: missing workspace AGENTS block capability');
 });
@@ -574,7 +631,9 @@ withWorkspace('kyro-sync-shared-config-only-', (cwd) => {
 
 withWorkspace('kyro-adapter-detect-', () => {
   const { parseAgent } = require(join(repo, 'dist/cli/options.js'));
+  const { adapterMatrix } = require(join(repo, 'dist/cli/commands/adapter.js'));
   const { detect } = require(join(repo, 'dist/cli/commands/detect.js'));
+  const { doctor } = require(join(repo, 'dist/cli/commands/doctor.js'));
 
   const textOutput = captureLogs(() => detect(cliOptions()));
   for (const agent of ['standard', 'opencode', 'codex', 'claude', 'cursor']) {
@@ -590,6 +649,17 @@ withWorkspace('kyro-adapter-detect-', () => {
   assert(payload.adapters[0].agent === 'codex', 'detect --json: expected codex adapter');
   assert(payload.adapters[0].systemPromptStrategy === 'managed-block', 'detect --json: missing codex system prompt strategy');
   assert(payload.adapters[0].mcpStrategy === 'toml-file', 'detect --json: missing codex MCP strategy');
+
+  const matrixOutput = captureLogs(() => adapterMatrix(cliOptions({ json: true })));
+  const matrixPayload = JSON.parse(matrixOutput);
+  assert(matrixPayload.schemaVersion === 1, 'adapter matrix --json: missing schema version');
+  assert(matrixPayload.adapters.some((adapter) => adapter.agent === 'cursor' && adapter.installable === true), 'adapter matrix --json: missing installable cursor');
+  assert(matrixPayload.adapters.some((adapter) => adapter.agent === 'claude' && adapter.systemPromptStrategy === 'instructions-file'), 'adapter matrix --json: missing claude strategy');
+
+  const migrationOutput = captureLogs(() => doctor(cliOptions({ migration: true, json: true })));
+  const migrationPayload = JSON.parse(migrationOutput);
+  assert(migrationPayload.schemaVersion === 1, 'doctor --migration --json: missing schema version');
+  assert(migrationPayload.migration.availableAdapters.includes('cursor'), 'doctor --migration --json: missing cursor availability');
 });
 
 console.log('Adapter fixtures passed');

package/scripts/smoke-adapters.mjs

@@ -0,0 +1,144 @@
+import { createRequire } from 'node:module';
+import { existsSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const repo = resolve(new URL('..', import.meta.url).pathname);
+const distRoot = join(repo, 'dist');
+const require = createRequire(import.meta.url);
+const requestedAgents = parseAgents(process.argv.slice(2));
+const agents = requestedAgents.length > 0 ? requestedAgents : ['standard', 'opencode', 'codex', 'cursor', 'claude'];
+const hostBinaryByAgent = {
+  standard: null,
+  opencode: 'opencode',
+  codex: 'codex',
+  cursor: 'cursor',
+  claude: 'claude',
+};
+
+if (!existsSync(join(distRoot, 'cli.js'))) {
+  throw new Error('dist/cli.js not found. Run npm run build before npm run smoke:adapters.');
+}
+
+const results = [];
+
+for (const agentName of agents) {
+  const workspace = mkdtempSync(join(tmpdir(), `kyro-smoke-${agentName}-`));
+  const previousCwd = process.cwd();
+  const previousHome = process.env.HOME;
+  try {
+    process.chdir(workspace);
+    process.env.HOME = join(workspace, '.home');
+    clearDistCache();
+
+    const { parseAgent } = require(join(distRoot, 'cli', 'options.js'));
+    const { install, sync } = require(join(distRoot, 'cli', 'commands', 'install.js'));
+    const { doctor } = require(join(distRoot, 'cli', 'commands', 'doctor.js'));
+    const { uninstall } = require(join(distRoot, 'cli', 'commands', 'uninstall.js'));
+    const agent = parseAgent(agentName);
+
+    captureLogs(() => install(options({ agents: [agent], dryRun: true })));
+    captureLogs(() => install(options({ agents: [agent] })));
+    captureLogs(() => doctor(options({ adapters: true })));
+    captureLogs(() => sync(options({ agents: [agent], dryRun: true })));
+    const syncJson = captureLogs(() => sync(options({ agents: [agent], prune: true, dryRun: true, json: true })));
+    assert(JSON.parse(syncJson).command === 'sync', `${agentName}: sync --json did not return sync payload`);
+    captureLogs(() => uninstall(options({ dryRun: true })));
+    captureLogs(() => uninstall(options({ purgeAdapterAssets: true, dryRun: true })));
+
+    const hostBinary = hostBinaryByAgent[agentName];
+    const hostStatus = hostBinary ? checkHostBinary(hostBinary) : 'skipped:no-host-binary';
+    results.push({ agent: agentName, status: 'pass', hostStatus });
+  } catch (error) {
+    results.push({ agent: agentName, status: 'fail', detail: error instanceof Error ? error.message : String(error) });
+  } finally {
+    process.chdir(previousCwd);
+    if (previousHome === undefined) {
+      delete process.env.HOME;
+    } else {
+      process.env.HOME = previousHome;
+    }
+    clearDistCache();
+    rmSync(workspace, { recursive: true, force: true });
+  }
+}
+
+for (const result of results) {
+  if (result.status === 'pass') {
+    console.log(`[PASS] ${result.agent}: lifecycle ok; host=${result.hostStatus}`);
+  } else {
+    console.log(`[FAIL] ${result.agent}: ${result.detail}`);
+  }
+}
+
+if (results.some((result) => result.status === 'fail')) process.exit(1);
+
+function options(overrides = {}) {
+  return {
+    agents: [],
+    scope: 'workspace',
+    dryRun: false,
+    yes: true,
+    help: false,
+    tokens: false,
+    artifacts: false,
+    adapters: false,
+    kyroScope: null,
+    json: false,
+    purgeAdapterAssets: false,
+    prune: false,
+    migration: false,
+    enableMcp: false,
+    ...overrides,
+  };
+}
+
+function captureLogs(callback) {
+  const logs = [];
+  const originalLog = console.log;
+  try {
+    console.log = (...args) => logs.push(args.join(' '));
+    callback();
+  } finally {
+    console.log = originalLog;
+  }
+  return `${logs.join('\n')}\n`;
+}
+
+function clearDistCache() {
+  for (const key of Object.keys(require.cache)) {
+    if (key.startsWith(distRoot)) delete require.cache[key];
+  }
+}
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+function parseAgents(args) {
+  const agentArgIndex = args.findIndex((arg) => arg === '--agent' || arg === '--agents');
+  if (agentArgIndex >= 0) {
+    return (args[agentArgIndex + 1] ?? '').split(',').map((agent) => agent.trim()).filter(Boolean);
+  }
+  const inlineArg = args.find((arg) => arg.startsWith('--agent=') || arg.startsWith('--agents='));
+  if (inlineArg) {
+    return inlineArg.slice(inlineArg.indexOf('=') + 1).split(',').map((agent) => agent.trim()).filter(Boolean);
+  }
+  return [];
+}
+
+function checkHostBinary(binary) {
+  try {
+    const command = process.platform === 'win32' ? 'where' : 'command';
+    const args = process.platform === 'win32' ? [binary] : ['-v', binary];
+    const found = spawnSync(command, args, { encoding: 'utf-8', shell: process.platform !== 'win32' });
+    if (found.error || found.status !== 0) return 'skipped:not-installed';
+
+    const version = spawnSync(binary, ['--version'], { encoding: 'utf-8' });
+    if (version.error || version.status !== 0) return 'detected:version-check-unavailable';
+    return `detected:${version.stdout.trim() || version.stderr.trim() || 'version-ok'}`;
+  } catch {
+    return 'skipped:host-probe-unavailable';
+  }
+}