fix(bootstrap): stabilize system prompt prefix (#329)

Author: marcusrbrown

src/index.ts

@@ -43,6 +43,9 @@ const getPackageVersion = (): string => {
 
 const SystematicPlugin: Plugin = async ({ client, directory }) => {
   const config = loadConfig(directory)
+  // Snapshot bootstrap once per plugin init so the cached system prefix stays
+  // stable across requests. Custom bootstrap file edits take effect on restart.
+  const bootstrapContent = getBootstrapContent(config, { bundledSkillsDir })
 
   const configHandler = createConfigHandler({
     directory,
@@ -106,9 +109,8 @@ const SystematicPlugin: Plugin = async ({ client, directory }) => {
         return
       }
 
-      const content = getBootstrapContent(config, { bundledSkillsDir })
-      if (content) {
-        applyBootstrapContent(output, content)
+      if (bootstrapContent) {
+        applyBootstrapContent(output, bootstrapContent)
       }
     },
   }

src/lib/bootstrap.ts

@@ -19,7 +19,7 @@ export interface BootstrapDeps {
   bundledSkillsDir: string
 }
 
-function getToolMappingTemplate(bundledSkillsDir: string): string {
+function getToolMappingTemplate(): string {
   return `**Tool Mapping for OpenCode:**
 When skills reference tools you don't have, substitute OpenCode equivalents:
 - \`TodoWrite\` → \`todowrite\`
@@ -37,7 +37,7 @@ When skills reference tools you don't have, substitute OpenCode equivalents:
 - Use the native \`skill\` tool for non-Systematic skills
 
 **Skills location:**
-Bundled skills are in \`${bundledSkillsDir}/\``
+Bundled skills ship with the Systematic plugin and are discoverable via \`systematic_skill\`.`
 }
 
 export function getBootstrapContent(
@@ -66,7 +66,7 @@ export function getBootstrapContent(
   const fullContent = fs.readFileSync(usingSystematicPath, 'utf8')
   const { body } = parseFrontmatter(fullContent)
   const content = body.trim()
-  const toolMapping = getToolMappingTemplate(bundledSkillsDir)
+  const toolMapping = getToolMappingTemplate()
 
   return `<SYSTEMATIC_WORKFLOWS>
 You have access to structured engineering workflows via the systematic plugin.

tests/unit/bootstrap.test.ts

@@ -194,7 +194,10 @@ describe('getBootstrapContent', () => {
     const content = getBootstrapContent(config, { bundledSkillsDir })
 
     expect(content).not.toBeNull()
-    expect(content).toContain(bundledSkillsDir)
+    expect(content).not.toContain(bundledSkillsDir)
+    expect(content).toContain(
+      'Bundled skills ship with the Systematic plugin and are discoverable via `systematic_skill`.',
+    )
   })
 })
 

tests/unit/plugin.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from 'bun:test'
 import fs from 'node:fs'
+import os from 'node:os'
 import path from 'node:path'
 import { pathToFileURL } from 'node:url'
 
@@ -24,6 +25,61 @@ describe('plugin loading', () => {
     expect(pluginModule.SystematicPlugin).toBeUndefined()
   })
 
+  test('plugin snapshots bootstrap content at init instead of re-reading files per transform', async () => {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'systematic-plugin-'))
+    const opencodeDir = path.join(tempDir, '.opencode')
+    const bootstrapPath = path.join(tempDir, 'bootstrap.md')
+    const configPath = path.join(opencodeDir, 'systematic.json')
+
+    fs.mkdirSync(opencodeDir, { recursive: true })
+    fs.writeFileSync(bootstrapPath, 'INITIAL bootstrap content')
+    fs.writeFileSync(
+      configPath,
+      JSON.stringify({
+        bootstrap: {
+          enabled: true,
+          file: bootstrapPath,
+        },
+      }),
+    )
+
+    try {
+      const pluginPath = path.join(SRC_DIR, 'index.ts')
+      const pluginModule = (await import(pathToFileURL(pluginPath).href)) as {
+        default: (args: {
+          client: { app: { log: (entry: unknown) => Promise<void> } }
+          directory: string
+        }) => Promise<{
+          'experimental.chat.system.transform': (
+            input: unknown,
+            output: { system: string[] },
+          ) => Promise<void>
+        }>
+      }
+
+      const plugin = await pluginModule.default({
+        client: {
+          app: {
+            log: async () => {},
+          },
+        },
+        directory: tempDir,
+      })
+
+      fs.writeFileSync(bootstrapPath, 'UPDATED bootstrap content')
+
+      const output = { system: ['Existing system prompt'] }
+      await plugin['experimental.chat.system.transform']({}, output)
+
+      expect(output.system).toEqual([
+        'Existing system prompt\n\nINITIAL bootstrap content',
+      ])
+      expect(output.system[0]).not.toContain('UPDATED bootstrap content')
+    } finally {
+      fs.rmSync(tempDir, { recursive: true, force: true })
+    }
+  })
+
   test('CI smoke test validates the workflow plugin export and registry drift contract', () => {
     const workflowPath = path.join(ROOT_DIR, '.github/workflows/main.yaml')
     const workflow = fs.readFileSync(workflowPath, 'utf8')