@sayansr26/agent-os 0.6.0 → 0.6.2

package/plugins/auto-handoff/tests/seed-row.test.tsx

@@ -0,0 +1,58 @@
+import { test, expect } from 'claude-code/testing'
+import { linkify } from '../hooks/config.ts'
+
+const PLUGIN = 'auto-handoff'
+const PATH = '/home/me/.claude/state/auto-handoff/dbd019e5-410b-4d91-8db9-6755b2924e48.md'
+const URL = 'http://100.85.122.99:3846/dbd019e5-410b-4d91-8db9-6755b2924e48.html'
+const SEED = `[auto-handoff] ↪ Handoff from session dbd019e5. The previous session hit its context limit and was cleared. Read the brief at ${PATH} before doing anything else (readable copy: ${URL}) and follow its Instructions section. Open your first reply with the line "↪ Handoff from session dbd019e5".`
+
+const row = (text: string, origin: Record<string, unknown>) => ({
+  component: 'UserMessage' as const,
+  props: { text, origin, isExpanded: false } as never,
+})
+
+test('linkify turns the brief path and viewer URL into markdown links', async () => {
+  const out = linkify(SEED)
+  expect(out).toContain(`[dbd019e5-410b-4d91-8db9-6755b2924e48.md](file://${PATH})`)
+  expect(out).toContain(`[${URL}](${URL})`)
+  // Everything else stays as written.
+  expect(out.startsWith('[auto-handoff] ↪ Handoff from session dbd019e5.')).toBe(true)
+  expect(out).toContain('follow its Instructions section.')
+})
+
+test('linkify leaves a seed with no viewer link alone except for the path', async () => {
+  const text = `[auto-handoff] ↪ Handoff from session abc. Read the brief at ${PATH} before doing anything else and follow its Instructions section.`
+  const out = linkify(text)
+  expect(out).toContain(`(file://${PATH})`)
+  expect(out).not.toContain('http')
+})
+
+test('the seed row draws as a Markdown with clickable links on every surface', async $ => {
+  for (const surface of ['terminal', 'desktop', 'vscode', 'mobile'] as const) {
+    const ui = await $.ui.mount({ plugin: PLUGIN, surface, ...row(SEED, { kind: 'plugin', name: PLUGIN }) })
+    const md = await ui.find({ type: 'Markdown' })
+    expect(md).toBeDefined()
+    expect(md?.text).toContain(`(file://${PATH})`)
+    expect(md?.text).toContain(`[${URL}](${URL})`)
+    await ui.unmount()
+  }
+})
+
+test('rows from other plugins or the person are left to the engine', async ($, on) => {
+  // Stands for the engine's own drawing beneath the plugin: a plain Text of the row.
+  on('ui.render', { component: 'UserMessage' }, async ($, e) => {
+    const { Text } = $.ui.resolve(e)
+    return <Text>{e.props.text}</Text>
+  })
+  const cases: Array<[string, Record<string, unknown>]> = [
+    [SEED, { kind: 'plugin', name: 'some-other-plugin' }],
+    [SEED, { kind: 'composer' }],
+    ['[auto-handoff] Not run: the context is past the handoff threshold.', { kind: 'plugin', name: PLUGIN }],
+  ]
+  for (const [text, origin] of cases) {
+    const ui = await $.ui.mount({ plugin: PLUGIN, surface: 'terminal', ...row(text, origin) })
+    expect(await ui.find({ type: 'Markdown' })).toBeUndefined()
+    expect((await ui.find({ type: 'Text' }))?.text).toBe(text)
+    await ui.unmount()
+  }
+})

package/plugins/auto-handoff/tests/viewer.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, test } from 'claude-code/testing'
+import { chainOf, parseBrief, renderPage, sections, viewerLink, withHeader } from '../hooks/viewer.ts'
+import { SERVER_JS } from '../hooks/server.ts'
+
+describe('viewer', () => {
+  test('parseBrief extracts header and body', () => {
+    const brief = `---
+from: abc123
+to: def456
+chain: main-chain
+tokens: 150000
+at: 2026-10-04T12:00:00Z
+cwd: /home/user/project
+---
+## Work in Progress
+Building the viewer.
+
+## Next Step
+Test it.`
+    const { header, body } = parseBrief(brief)
+    expect(header.from).toBe('abc123')
+    expect(header.chain).toBe('main-chain')
+    expect(body).toContain('## Work in Progress')
+  })
+
+  test('parseBrief handles briefs with no header', () => {
+    const brief = `## Work in Progress\nDoing stuff`
+    const { header, body } = parseBrief(brief)
+    expect(header).toEqual({})
+    expect(body).toBe(brief)
+  })
+
+  test('withHeader round-trips a brief', () => {
+    const header = { from: 'abc', to: 'def', tokens: '150000' }
+    const body = '## Work\nStuff'
+    const result = withHeader(header, body)
+    const { header: h2, body: b2 } = parseBrief(result)
+    expect(h2.from).toBe('abc')
+    expect(h2.to).toBe('def')
+    expect(b2).toBe(body)
+  })
+
+  test('viewerLink is the short served link, or the local file with no server', () => {
+    expect(viewerLink({ host: '100.64.0.1', port: '3846' }, '/pages', 'abc12345')).toBe('http://100.64.0.1:3846/abc12345')
+    expect(viewerLink(undefined, '/pages', 'abc12345')).toBe('file:///pages/abc12345.html')
+    expect(viewerLink(undefined, 'C:\\Users\\x/.claude/pages', 'abc12345')).toBe('file:///C:/Users/x/.claude/pages/abc12345.html')
+  })
+
+  test('renderPage links the chain and escapes a brief that tries to close the script tag', () => {
+    const a = { id: 'aaaaaaaa-1', header: { chain: 'aaaaaaaa-1', at: '2026-10-04T00:00:00Z', to: 'bbbbbbbb-2' }, body: '## Work in Progress\nFirst.' }
+    const b = { id: 'bbbbbbbb-2', header: { chain: 'aaaaaaaa-1', from: 'aaaaaaaa-1', at: '2026-10-04T01:00:00Z' }, body: '## Next Step\n</script><b>x</b>' }
+    const page = renderPage(b, [a, b])
+    expect(page).toContain('href="aaaaaaaa-1.html"')
+    expect(page).toContain('Handoff Chain')
+    expect(page).not.toContain('</script><b>')
+  })
+
+  test('previous and next follow the chain, even where a header lost its from', () => {
+    const e = (id: string, at: string, header: Record<string, string>) => ({ id, header: { at, ...header }, body: '' })
+    const a = e('aaaaaaaa-1', '1', { to: 'bbbbbbbb-2' })
+    const b = e('bbbbbbbb-2', '2', { to: 'cccccccc-3' }) // a reload dropped its from
+    const c = e('cccccccc-3', '3', { from: 'bbbbbbbb-2', to: 'dddddddd-4' })
+    const mid = renderPage(b, [a, b, c])
+    expect(mid).toContain('<a href="aaaaaaaa-1.html">← previous</a>')
+    expect(mid).toContain('<a href="cccccccc-3.html">next →</a>')
+    const last = renderPage(c, [a, b, c])
+    expect(last).toContain('next: dddddddd, still running')
+    expect(last).not.toContain('href="dddddddd-4.html"')
+    expect(renderPage(a, [a, b, c])).not.toContain('← previous')
+  })
+
+  test('sections extracts visible sections', () => {
+    const body = `## Work in Progress
+Doing X
+
+## Instructions
+Don't read this
+
+## Next Step
+Do Y
+
+## How to Use This Brief
+Also don't read`
+    const visible = sections(body)
+    expect(visible.length).toBe(2)
+    expect(visible[0]).toContain('Work in Progress')
+    expect(visible[1]).toContain('Next Step')
+  })
+
+  test('chainOf joins a run whose chain id broke partway, through from/to links', () => {
+    const e = (id: string, at: string, header: Record<string, string>) => ({ id, header: { at, ...header }, body: '' })
+    const entries = [
+      e('a', '1', { chain: 'a', to: 'b' }),
+      e('b', '2', { chain: 'a', from: 'a', to: 'c' }),
+      e('c', '3', { chain: 'c', to: 'd' }), // the reload lost its from
+      e('d', '4', { chain: 'c', from: 'c' }),
+      e('x', '5', { chain: 'x' }),
+    ]
+    expect(chainOf(entries, 'd').map(x => x.id)).toEqual(['a', 'b', 'c', 'd'])
+    expect(chainOf(entries, 'a').map(x => x.id)).toEqual(['a', 'b', 'c', 'd'])
+    expect(chainOf(entries, 'x').map(x => x.id)).toEqual(['x'])
+  })
+
+  // A second session finds the port taken. Its child used to die with an unhandled EADDRINUSE
+  // stack trace in the log; it now says so in one line and exits 0. (Run live: see the 0.8.2 commit.)
+  test('the server exits quietly when the port is taken', () => {
+    expect(SERVER_JS).toContain("err.code === 'EADDRINUSE'")
+    expect(SERVER_JS).toContain('process.exit(0)')
+    expect(SERVER_JS.indexOf(".on('error'")).toBeLessThan(SERVER_JS.indexOf('.listen('))
+  })
+})

package/plugins/auto-handoff/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "./.claude-plugin/types/tsconfig.json",
+  "compilerOptions": { "allowImportingTsExtensions": true, "noEmit": true }
+}

package/plugins/auto-route/.claude-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "auto-route",
+  "version": "0.1.0",
+  "description": "Picks the model and effort level for each turn from what the prompt asks for",
+  "types": "./types/index.d.ts",
+  "author": {
+    "name": "Sayan Choudhury",
+    "email": "sayan.choudhury.in@gmail.com"
+  },
+  "homepage": "https://github.com/sayansr26/agent-os",
+  "repository": "https://github.com/sayansr26/agent-os",
+  "license": "MIT",
+  "keywords": [
+    "model-routing",
+    "effort",
+    "mod"
+  ]
+}

package/plugins/auto-route/hooks/hooks.json

@@ -0,0 +1 @@
+{ "modules": ["./register.ts"] }

package/plugins/auto-route/hooks/register.ts

@@ -0,0 +1,143 @@
+import { atom, read, update } from 'claude-code'
+import type { ModelEffort, Register } from 'claude-code'
+
+import type { Mode, Route, Tier } from '../types'
+
+// Edit this table to change what each tier runs on.
+const TIERS: Record<Tier, { model: string; effort: ModelEffort }> = {
+  light: { model: 'claude-haiku-5-5', effort: 'low' },
+  standard: { model: 'claude-sonnet-5-5', effort: 'medium' },
+  deep: { model: 'claude-opus-5-5', effort: 'high' },
+  max: { model: 'claude-opus-5-5', effort: 'max' },
+}
+
+// Checked top to bottom; the first tier whose pattern matches wins.
+const RULES: { tier: Tier; reason: string; pattern: RegExp }[] = [
+  {
+    tier: 'max',
+    reason: 'asked to think hard',
+    pattern: /\b(ultrathink|think (really )?hard|think harder|deep dive)\b/i,
+  },
+  {
+    tier: 'max',
+    reason: 'security or concurrency',
+    pattern:
+      /\b(security (audit|review)|vulnerabilit|race condition|deadlock|memory leak|incident|data loss)/i,
+  },
+  {
+    tier: 'deep',
+    reason: 'design or debugging',
+    pattern:
+      /\b(architect|design|refactor|migrat|debug|root cause|investigate|why (is|does|doesn't|isn't)|plan|implement|build (a|the|an)|new feature|end[- ]to[- ]end|across|whole (repo|codebase|app)|optimi[sz]e|performance|review)/i,
+  },
+  {
+    tier: 'light',
+    reason: 'small or lookup task',
+    pattern:
+      /^(what|which|where|who|when|is|are|does|do|can|show|list|print|explain briefly|rename|fix (the )?typo|format|lint|bump|commit message|thanks|thank you|ok|yes|no)\b/i,
+  },
+]
+
+export const classify = (text: string): Route => {
+  const words = text.trim().split(/\s+/).filter(Boolean).length
+  const rule = RULES.find(one => one.pattern.test(text))
+
+  if (rule && !(rule.tier === 'light' && words > 40)) {
+    return { tier: rule.tier, reason: rule.reason }
+  }
+
+  if (words > 150) {
+    return { tier: 'deep', reason: 'long, detailed prompt' }
+  }
+
+  return words <= 8
+    ? { tier: 'light', reason: 'short prompt' }
+    : { tier: 'standard', reason: 'regular coding task' }
+}
+
+const MODES: readonly Mode[] = ['auto', 'off', 'light', 'standard', 'deep', 'max']
+
+const mode = atom({ plugin: 'auto-route', key: 'mode' } as const, 'auto')
+const route = atom({ plugin: 'auto-route', key: 'route' } as const, null)
+
+const describe = (current: Mode, last: Route | null) => {
+  if (current === 'off') {
+    return 'auto-route: off'
+  }
+
+  const pinned = current === 'auto' ? '' : ' (pinned)'
+  const tier = current === 'auto' ? last?.tier : current
+
+  if (!tier) {
+    return 'auto-route: waiting for a prompt'
+  }
+
+  const { model, effort } = TIERS[tier]
+
+  return `auto-route: ${tier}${pinned} · ${model.replace(/^claude-/, '')} / ${effort}`
+}
+
+export const register: Register = on => {
+  on('session.start', async ($, e, next) => {
+    await $.command.register({
+      name: 'route',
+      description: 'Auto model routing: auto, off, or pin light | standard | deep | max',
+    })
+
+    return next(e)
+  })
+
+  on('command.run', { command: 'route' }, async ($, e) => {
+    const asked = e.args.trim().toLowerCase()
+
+    if (asked !== '') {
+      const next = MODES.find(one => one === asked)
+
+      if (!next) {
+        return { text: `auto-route: unknown mode "${asked}". Use ${MODES.join(', ')}.` }
+      }
+
+      await update($, mode, () => next)
+    }
+
+    const text = describe(await read($, mode), await read($, route))
+    $.ui.status(text)
+
+    return { text: text.replace(/^auto-route: /, '') }
+  })
+
+  on('prompt.submit', async ($, e, next) => {
+    // A prompt delivered into a running turn keeps that turn's route.
+    const current = await read($, mode)
+    const isRouted = e.turnId === undefined && !e.command && current === 'auto'
+    $.ui.log(`auto-route: prompt.submit mode=${current} turnId=${e.turnId ?? '-'} command=${e.command ? 'yes' : 'no'} routed=${isRouted}`)
+
+    if (isRouted) {
+      const picked = classify(e.text)
+      await update($, route, () => picked)
+      $.ui.status(describe('auto', picked))
+    }
+
+    return next(e)
+  }).catch(($, e, next) => {
+    $.ui.log('auto-route: prompt.submit hook failed')
+
+    return next(e)
+  })
+
+  on('turn.step', async function* ($, e, next) {
+    const current = await read($, mode)
+    const last = await read($, route)
+    const tier = current === 'auto' ? last?.tier : current === 'off' ? undefined : current
+
+    // Subagents choose their own model; leave their requests alone.
+    if (e.agentId !== undefined || !tier) {
+      return yield* next(e)
+    }
+
+    const { model, effort } = TIERS[tier]
+    $.ui.log(`auto-route: turn.step ${e.model}/${e.effort ?? '-'} -> ${model}/${effort}`)
+
+    return yield* next({ ...e, model, effort })
+  })
+}

package/plugins/auto-route/tests/route.test.ts

@@ -0,0 +1,87 @@
+import { expect, test } from 'claude-code/testing'
+import type { HookStream, TurnStepChunk, TurnStepInput, TurnStepResult } from 'claude-code'
+
+import { classify } from '../hooks/register'
+
+const STEP: TurnStepInput = {
+  turnId: 't1',
+  index: 0,
+  model: 'claude-opus-5-5',
+  effort: 'high',
+  messageCount: 1,
+}
+
+const ORIGIN = { kind: 'composer' } as const
+
+const prompt = (text: string) => ({ text, wait: false, origin: ORIGIN })
+
+const route = (args: string) => ({
+  command: 'route',
+  args,
+  origin: ORIGIN,
+  presentation: { isFullscreen: false, columns: 120 },
+})
+
+// Reads the request's stream to its end, as the engine would.
+type Steps = { turn: { step: (e: TurnStepInput) => HookStream<TurnStepChunk, TurnStepResult> } }
+
+const step = async ($: Steps, e: TurnStepInput) => {
+  const stream = $.turn.step(e)
+  for await (const _ of stream) {
+  }
+  return stream.result
+}
+
+test('prompts land in the expected tier', async () => {
+  expect(classify('what does this function return?').tier).toBe('light')
+  expect(classify('ok').tier).toBe('light')
+  expect(
+    classify('add a loading spinner to the submit button on the ask form and disable it while saving').tier,
+  ).toBe('standard')
+  expect(classify('refactor the fix ranking so it weighs environment matches').tier).toBe('deep')
+  expect(classify('debug why the MCP search is slow').tier).toBe('deep')
+  expect(classify('ultrathink about the verification model').tier).toBe('max')
+  expect(classify('is there a race condition in the release watcher?').tier).toBe('max')
+})
+
+test('the routed model and effort reach the request, subagents untouched', async ($, on) => {
+  const sent: TurnStepInput[] = []
+  on('ui.status', () => ({ value: undefined }))
+  on('prompt.submit', (_, e) => ({ text: e.text }))
+  on('turn.step', async function* (_, e) {
+    sent.push(e)
+    return { turnId: e.turnId, index: e.index, answer: '', toolUses: [], stopReason: 'end_turn', usage: null }
+  })
+
+  await $.prompt.submit(prompt('what is in package.json?'))
+  await step($, STEP)
+  await step($, { ...STEP, agentId: 'a1' })
+
+  expect(sent[0]?.model).toBe('claude-haiku-5-5')
+  expect(sent[0]?.effort).toBe('low')
+  expect(sent[1]?.model).toBe('claude-opus-5-5')
+  expect(sent[1]?.effort).toBe('high')
+})
+
+test('/route pins a tier and off stops routing', async ($, on) => {
+  const sent: TurnStepInput[] = []
+  on('command.register', () => ({ value: { command: 'route' } }))
+  on('session.start', (_, e) => ({ cwd: e.cwd }))
+  on('ui.status', () => ({ value: undefined }))
+  on('prompt.submit', (_, e) => ({ text: e.text }))
+  on('turn.step', async function* (_, e) {
+    sent.push(e)
+    return { turnId: e.turnId, index: e.index, answer: '', toolUses: [], stopReason: 'end_turn', usage: null }
+  })
+
+  await $.session.start({ cwd: '/', surface: 'terminal', isInteractive: true })
+  await $.command.run(route('max'))
+  await $.prompt.submit(prompt('ok'))
+  await step($, STEP)
+  expect(sent[0]?.effort).toBe('max')
+
+  await $.command.run(route('off'))
+  await step($, { ...STEP, model: 'claude-sonnet-5-5', effort: 'medium' })
+  expect(sent[1]?.model).toBe('claude-sonnet-5-5')
+  expect(sent[1]?.effort).toBe('medium')
+})

package/plugins/auto-route/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "./.claude-plugin/types/tsconfig.json"
+}

package/plugins/auto-route/types/index.d.ts

@@ -0,0 +1,12 @@
+export type Tier = 'light' | 'standard' | 'deep' | 'max'
+
+// 'auto' classifies each prompt; a tier pins it; 'off' leaves the session's own.
+export type Mode = 'auto' | 'off' | Tier
+
+export type Route = { tier: Tier; reason: string }
+
+declare module 'claude-code' {
+  interface PluginState {
+    'auto-route': { mode: Mode; route: Route | null }
+  }
+}

package/src/cli.mjs

@@ -5,7 +5,7 @@ import { join } from "node:path";
 import { detect, summarise, TOOLS } from "./detect.mjs";
 import { load, write, readIfExists, matches, BANNER, DIR } from "./source.mjs";
 import { adopt } from "./adopt.mjs";
-import { ensurePlugin, MARKETPLACE_NAME, PLUGIN } from "./plugin.mjs";
+import { ensurePlugin, MARKETPLACE_NAME, PLUGIN, PLUGINS } from "./plugin.mjs";
 import { setupState, describeState } from "../plugins/agent-os/skills/init/scripts/state.mjs";
 import { applyScope, describe } from "./claude-setup.mjs";
 import { createInterface } from "node:readline/promises";
@@ -33,7 +33,11 @@ Options
   --root <dir>   project directory (default: cwd)
   --dry-run      print what would change, write nothing
   --force        overwrite files agent-os did not generate (it refuses by default)
-  --no-plugin    skip installing or updating the Claude Code plugin during init
+  --no-plugin    skip installing or updating the Claude Code plugins during init
+  --no-auto-route
+                 init: leave out the auto-route model router
+  --no-auto-handoff
+                 init: leave out the auto-handoff session handoff
   --global       init: also write ~/.claude settings without asking
   --no-global    init: leave ~/.claude alone
 `;
@@ -265,19 +269,25 @@ Pick one:
     }
 
     if (cmd === "init" && targets.includes("claude-code") && !argv.includes("--no-plugin")) {
-      console.log(`\n${bold("Claude Code plugin")} ${dim(`${PLUGIN}@${MARKETPLACE_NAME}`)}\n`);
-      const r = ensurePlugin({ root, dry });
-      for (const line of r.done) console.log(`  ${dim(line)}`);
-      if (r.ok) console.log({
-        installed: `\n  installed ${r.to || ""} at project scope ${dim("— .claude/settings.json, so it travels with the repo")}`,
-        updated: `\n  updated ${r.from} → ${r.to}`,
-        current: `\n  already the latest (${r.to})`,
-        "dry-run": `\n  ${dim(r.from ? `installed: ${r.from} — would refresh and update` : "not installed — would install")}`,
-      }[r.reason]);
-      for (const line of r.hint) console.log(`  ${r.ok ? dim(line) : line}`);
-      if (r.reason === "installed" || r.reason === "updated")
-        console.log(`  ${dim("restart Claude Code, or /reload-plugins, to load it")}`);
-      console.log(`\n  ${dim("--no-plugin skips this")}`);
+      // All come from the same marketplace, so it is added or refreshed once:
+      // by the first plugin whose run gets that far.
+      let refresh = true;
+      for (const plugin of PLUGINS.filter((p) => p === PLUGIN || !argv.includes(`--no-${p}`))) {
+        console.log(`\n${bold("Claude Code plugin")} ${dim(`${plugin}@${MARKETPLACE_NAME}`)}\n`);
+        const r = ensurePlugin({ root, dry, plugin, refresh });
+        if (r.done.length || r.reason === "no-cli") refresh = false;
+        for (const line of r.done) console.log(`  ${dim(line)}`);
+        if (r.ok) console.log({
+          installed: `\n  installed ${r.to || ""} at project scope ${dim("— .claude/settings.json, so it travels with the repo")}`,
+          updated: `\n  updated ${r.from} → ${r.to}`,
+          current: `\n  already the latest (${r.to})`,
+          "dry-run": `\n  ${dim(r.from ? `installed: ${r.from} — would refresh and update` : "not installed — would install")}`,
+        }[r.reason]);
+        for (const line of r.hint) console.log(`  ${r.ok ? dim(line) : line}`);
+        if (r.reason === "installed" || r.reason === "updated")
+          console.log(`  ${dim("restart Claude Code, or /reload-plugins, to load it")}`);
+      }
+      console.log(`\n  ${dim("--no-plugin skips this; --no-auto-route / --no-auto-handoff skip one mod")}`);
     }
 
     if (cmd === "init" && !dry) {

package/src/plugin.mjs

@@ -2,8 +2,11 @@
  * Install or update the Claude Code half of agent-os during `init`.
  *
  * The CLI compiles rules for every tool. Claude Code additionally gets the
- * agents, skills, per-agent memory and hooks, which ship as a plugin. `init`
- * brings that plugin to the latest version whatever state it finds:
+ * agents, skills, per-agent memory and hooks, which ship as a plugin; plus two
+ * mods: auto-route, which picks the model and effort per turn, and
+ * auto-handoff, which hands a full session to a fresh one instead of
+ * compacting. All three live in this repo's marketplace. `init` brings each to the latest version whatever
+ * state it finds:
  *
  *   not installed        marketplace add + install, at project scope
  *   installed, disabled  enable
@@ -19,18 +22,25 @@
  * on. The rules are the part that must not depend on this.
  */
 import { spawnSync } from "node:child_process";
-import { realpathSync } from "node:fs";
-import { bundledVersion, cmpVersion } from "../plugins/agent-os/skills/init/scripts/state.mjs";
+import { readFileSync, realpathSync } from "node:fs";
+import { cmpVersion } from "../plugins/agent-os/skills/init/scripts/state.mjs";
 
 export const MARKETPLACE = "sayansr26/agent-os";
 export const MARKETPLACE_NAME = "sayan-plugins";
 export const PLUGIN = "agent-os";
-const ID = `${PLUGIN}@${MARKETPLACE_NAME}`;
+// Installed by `init` in this order; each can be skipped with --no-<name>.
+export const PLUGINS = [PLUGIN, "auto-route", "auto-handoff"];
+const idOf = (plugin) => `${plugin}@${MARKETPLACE_NAME}`;
 
 const run = (args, cwd) =>
   spawnSync("claude", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 120000 });
 const json = (r) => { try { return JSON.parse(r.stdout); } catch { return null; } };
 const real = (p) => { try { return realpathSync(p); } catch { return p; } };
+/** The version this package ships for a plugin, from its plugin.json. */
+const bundled = (plugin) => {
+  try { return JSON.parse(readFileSync(new URL(`../plugins/${plugin}/.claude-plugin/plugin.json`, import.meta.url), "utf8")).version || null; }
+  catch { return null; }
+};
 const tail = (r) => (r.stderr || r.stdout || String(r.error || "")).trim().split("\n").slice(-3);
 
 /** Is the Claude Code CLI usable from here? */
@@ -39,40 +49,46 @@ export function claudeAvailable() {
   return !r.error && r.status === 0;
 }
 
-/** This project's install of the plugin, per `claude plugin list --json`, or null. */
-export function installed(root) {
+/** This project's install of a plugin, per `claude plugin list --json`, or null. */
+export function installed(root, plugin = PLUGIN) {
   const list = json(run(["plugin", "list", "--json"], root));
   if (!Array.isArray(list)) return null;
-  const mine = list.filter((p) => p.id === ID &&
+  const mine = list.filter((p) => p.id === idOf(plugin) &&
     (p.scope === "user" || (p.projectPath && real(p.projectPath) === real(root))));
   return mine.find((p) => p.scope === "project" || p.scope === "local") || mine[0] || null;
 }
 
 /**
- * Bring the plugin to the latest version for this project.
+ * Bring a plugin to the latest version for this project.
  * Returns { ok, reason, from, to, done, hint } with reason one of
  * "installed" | "updated" | "current" | "dry-run" | "no-cli" | "failed".
+ * `refresh: false` skips the marketplace step when an earlier call this run
+ * already added or updated it.
  */
-export function ensurePlugin({ root = process.cwd(), dry = false, scope = "project" } = {}) {
+export function ensurePlugin({ root = process.cwd(), dry = false, scope = "project", plugin = PLUGIN, refresh = true } = {}) {
+  const ID = idOf(plugin);
   if (!claudeAvailable())
     return {
       ok: false, reason: "no-cli", done: [],
       hint: [
-        "The `claude` CLI is not on PATH, so the plugin was not installed or updated.",
-        "Inside Claude Code, run:",
-        `  /plugin marketplace add ${MARKETPLACE}`,
+        ...(refresh ? [
+          "The `claude` CLI is not on PATH, so the plugin was not installed or updated.",
+          "Inside Claude Code, run:",
+          `  /plugin marketplace add ${MARKETPLACE}`,
+        ] : []),
         `  /plugin install ${ID}     (or /plugin update ${ID} if it is already there)`,
       ],
     };
 
-  const before = installed(root);
-  const markets = json(run(["plugin", "marketplace", "list", "--json"], root));
-  const haveMarket = Array.isArray(markets) && markets.some((m) => m.name === MARKETPLACE_NAME);
-
+  const before = installed(root, plugin);
   const steps = [];
-  steps.push(haveMarket
-    ? ["plugin", "marketplace", "update", MARKETPLACE_NAME]
-    : ["plugin", "marketplace", "add", MARKETPLACE, "--scope", scope]);
+  if (refresh) {
+    const markets = json(run(["plugin", "marketplace", "list", "--json"], root));
+    const haveMarket = Array.isArray(markets) && markets.some((m) => m.name === MARKETPLACE_NAME);
+    steps.push(haveMarket
+      ? ["plugin", "marketplace", "update", MARKETPLACE_NAME]
+      : ["plugin", "marketplace", "add", MARKETPLACE, "--scope", scope]);
+  }
   if (!before) steps.push(["plugin", "install", ID, "--scope", scope, "--yes"]);
   else {
     if (before.enabled === false) steps.push(["plugin", "enable", ID, "--scope", before.scope]);
@@ -99,14 +115,14 @@ export function ensurePlugin({ root = process.cwd(), dry = false, scope = "proje
     done.push(`claude ${args.join(" ")}`);
   }
 
-  const after = installed(root);
+  const after = installed(root, plugin);
   const to = after?.version || null;
   const from = before?.version || null;
-  const want = bundledVersion();
+  const want = bundled(plugin);
   const hint = [];
   // The marketplace serves what is pushed to GitHub; this package may be newer.
   if (to && want && cmpVersion(to, want) < 0)
-    hint.push(`Marketplace still serves ${to}; this agent-os ships ${want}. It updates once ${MARKETPLACE} is pushed.`);
+    hint.push(`Marketplace still serves ${plugin} ${to}; this agent-os ships ${want}. It updates once ${MARKETPLACE} is pushed.`);
   return {
     ok: true,
     reason: !before ? "installed" : from !== to ? "updated" : "current",

package/src/selftest.mjs

@@ -101,6 +101,15 @@ try {
     ok(pi.stdout.includes("SETUP  FRESH"), "init on an empty project reports a fresh setup");
     ok(/marketplace add sayansr26\/agent-os|plugin marketplace add|not on PATH/.test(pi.stdout),
        "init names the marketplace step or says why it could not run it");
+    ok(pi.stdout.includes("auto-route@sayan-plugins"), "init sets up auto-route by default");
+    ok(pi.stdout.includes("auto-handoff@sayan-plugins"), "init sets up auto-handoff by default");
+    ok((pi.stdout.match(/marketplace add/g) || []).length <= 1, "the marketplace is added once, not per plugin");
+    const na = cli(["init", "--dry-run", "--no-auto-route"], r4);
+    ok(!/install auto-route@sayan-plugins/.test(na.stdout) && /install agent-os@sayan-plugins/.test(na.stdout),
+       "--no-auto-route keeps agent-os and skips auto-route");
+    const nh = cli(["init", "--dry-run", "--no-auto-handoff"], r4);
+    ok(!/install auto-handoff@sayan-plugins/.test(nh.stdout) && /install auto-route@sayan-plugins/.test(nh.stdout),
+       "--no-auto-handoff skips only auto-handoff");
     rmSync(r4, { recursive: true, force: true });
 
     // A hand-written file at a generated path must survive a sync.