@agimon-ai/doompi-model-guidance 0.0.1-alpha.63

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vuong Ngo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,94 @@
+# @agimon-ai/doompi-model-guidance
+
+Per-model system prompt guidance for Pi agents, layered across global and repository scope.
+
+A new model release often needs prompt adjustments that older models do not.
+This package keeps those adjustments in one place, keyed by model id, instead of
+spreading them through every package's prompt.
+
+## Configuration
+
+Guidance lives in `model-guidance.yaml`, read from two scopes:
+
+| Scope      | Path                                     |
+| ---------- | ---------------------------------------- |
+| Global     | `~/.pi/.doom/model-guidance.yaml`        |
+| Repository | `<repository>/.doom/model-guidance.yaml` |
+
+```yaml
+modelGuidance:
+  claude-opus-5: |
+    Keep the task focused. Never go off rails.
+  gpt-6-astra: |
+    Prefer fewer, larger tool batches.
+```
+
+### Matching
+
+Model ids match exactly, against the id Pi reports for the active model. Use the
+value shown by `/model`. A model with no entry gets no guidance, which is never
+an error, so missing guidance usually means the id does not match.
+
+Exact matching is deliberate: it keeps the file honest about which model a piece
+of text was written for. The cost is that a provider shipping a new versioned id
+needs a new entry.
+
+### Merge rule
+
+Both scopes apply. A repository entry wins for the model ids it names, and
+global entries for ids the repository does not mention still apply.
+
+| Model id        | Global          | Repository            | Result                |
+| --------------- | --------------- | --------------------- | --------------------- |
+| `claude-opus-5` | "Stay focused." | "Cordis rules apply." | "Cordis rules apply." |
+| `gpt-6-astra`   | "Batch tools."  | absent                | "Batch tools."        |
+| `local-qwen-3`  | absent          | "Short answers only." | "Short answers only." |
+
+A malformed or unreadable guidance file warns on stderr and yields no guidance,
+rather than ending the session.
+
+## Activation
+
+The package ships in the `llm` layer and is optional.
+
+Mode-scoped, in `.doom/modes.yaml`:
+
+```yaml
+layers:
+  llm:
+    packages:
+      - '@agimon-ai/doompi-model-guidance'
+
+majorMode:
+  copilot:
+    layers: [team, ask-user, task, sandbox, llm]
+```
+
+Always on, by listing it in the `default` package list instead:
+
+```yaml
+default:
+  packages:
+    - '@agimon-ai/doompi-model-guidance'
+```
+
+A layer only activates when the selected major mode lists it, so add `llm` to
+every major mode that should carry guidance. The `default` route avoids that but
+makes ordering depend on list position.
+
+## Behaviour
+
+Guidance is appended to the system prompt at the start of each turn, after the
+default packages have contributed and before the profile persona. The file is
+read per turn, so an edit takes effect on the next message with no restart.
+
+## Development
+
+```bash
+pnpm nx run @agimon-ai/doompi-model-guidance:lint
+pnpm nx run @agimon-ai/doompi-model-guidance:typecheck
+pnpm nx run @agimon-ai/doompi-model-guidance:build
+pnpm nx run @agimon-ai/doompi-model-guidance:test
+```
+
+Pi entrypoint: `./dist/extensions/pi.mjs`.

package/dist/adapters/modelGuidanceStore.cjs

@@ -0,0 +1,2 @@
+const e=require("../services/modelGuidance.cjs");let t=require("@agimon-ai/doompi-config/layeredConfig");const n=`model-guidance.yaml`,r=Object.freeze({});function i(i,a){if(!i)return r;try{let r=(0,t.readDoomConfigSources)(n,i,a);return e.mergeModelGuidance(r.map(e=>e.document))}catch(e){let t=e instanceof Error?e.message:String(e);return process.stderr.write(`[doompi-model-guidance] could not read ${n}: ${t}\n`),r}}exports.GUIDANCE_FILE=n,exports.loadModelGuidance=i;
+//# sourceMappingURL=modelGuidanceStore.cjs.map

package/dist/adapters/modelGuidanceStore.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"modelGuidanceStore.cjs","names":["readDoomConfigSources","mergeModelGuidance"],"sources":["../../src/adapters/modelGuidanceStore.ts"],"sourcesContent":["import { readDoomConfigSources } from '@agimon-ai/doompi-config/layeredConfig';\nimport { mergeModelGuidance } from '../services/modelGuidance.ts';\nimport type { ModelGuidanceDocument, ModelGuidanceMap } from '../types/modelGuidance.ts';\n\n/** Layered guidance document, read from the global then the repository `.doom` directory. */\nexport const GUIDANCE_FILE = 'model-guidance.yaml';\n\nconst EMPTY: ModelGuidanceMap = Object.freeze({});\n\n/**\n * Reads and folds the global and repository guidance documents.\n *\n * Fails open. The reader parses YAML without a guard, so a typo in an optional\n * prompt file would otherwise throw on every turn of the session. Degrading to\n * \"no guidance\" is the same outcome as the file being absent, which is why this\n * matches the persona precedent rather than the synchronized-state invariant\n * that governs composition artifacts.\n *\n * `homeDirectory` exists so a test can point the global scope at a temporary\n * directory; production callers omit it and the reader falls back to the real home.\n */\nexport function loadModelGuidance(repositoryRoot: string | undefined, homeDirectory?: string): ModelGuidanceMap {\n  if (!repositoryRoot) return EMPTY;\n\n  try {\n    const sources = readDoomConfigSources<ModelGuidanceDocument>(GUIDANCE_FILE, repositoryRoot, homeDirectory);\n    return mergeModelGuidance(sources.map((source) => source.document));\n  } catch (error) {\n    const reason = error instanceof Error ? error.message : String(error);\n    process.stderr.write(`[doompi-model-guidance] could not read ${GUIDANCE_FILE}: ${reason}\\n`);\n    return EMPTY;\n  }\n}\n"],"mappings":"yGAKA,MAAa,EAAgB,sBAEvB,EAA0B,OAAO,OAAO,CAAC,CAAC,EAchD,SAAgB,EAAkB,EAAoC,EAA0C,CAC9G,GAAI,CAAC,EAAgB,OAAO,EAE5B,GAAI,CACF,IAAM,GAAA,EAAUA,EAAAA,sBAAAA,CAA6C,EAAe,EAAgB,CAAa,EACzG,OAAOC,EAAAA,mBAAmB,EAAQ,IAAK,GAAW,EAAO,QAAQ,CAAC,CACpE,OAAS,EAAO,CACd,IAAM,EAAS,aAAiB,MAAQ,EAAM,QAAU,OAAO,CAAK,EAEpE,OADA,QAAQ,OAAO,MAAM,0CAA0C,EAAc,IAAI,EAAO,GAAG,EACpF,CACT,CACF"}

package/dist/adapters/modelGuidanceStore.d.cts

@@ -0,0 +1,20 @@
+import { ModelGuidanceMap } from "../types/modelGuidance.cjs";
+//#region src/adapters/modelGuidanceStore.d.ts
+/** Layered guidance document, read from the global then the repository `.doom` directory. */
+declare const GUIDANCE_FILE = "model-guidance.yaml";
+/**
+ * Reads and folds the global and repository guidance documents.
+ *
+ * Fails open. The reader parses YAML without a guard, so a typo in an optional
+ * prompt file would otherwise throw on every turn of the session. Degrading to
+ * "no guidance" is the same outcome as the file being absent, which is why this
+ * matches the persona precedent rather than the synchronized-state invariant
+ * that governs composition artifacts.
+ *
+ * `homeDirectory` exists so a test can point the global scope at a temporary
+ * directory; production callers omit it and the reader falls back to the real home.
+ */
+declare function loadModelGuidance(repositoryRoot: string | undefined, homeDirectory?: string): ModelGuidanceMap;
+//#endregion
+export { GUIDANCE_FILE, loadModelGuidance };
+//# sourceMappingURL=modelGuidanceStore.d.cts.map

package/dist/adapters/modelGuidanceStore.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"modelGuidanceStore.d.cts","names":[],"sources":["../../src/adapters/modelGuidanceStore.ts"],"mappings":";;;cAKa;;;;;;;;;;;;;iBAgBG,kBAAkB,oCAAoC,yBAAyB"}

package/dist/adapters/modelGuidanceStore.d.mts

@@ -0,0 +1,20 @@
+import { ModelGuidanceMap } from "../types/modelGuidance.mjs";
+//#region src/adapters/modelGuidanceStore.d.ts
+/** Layered guidance document, read from the global then the repository `.doom` directory. */
+declare const GUIDANCE_FILE = "model-guidance.yaml";
+/**
+ * Reads and folds the global and repository guidance documents.
+ *
+ * Fails open. The reader parses YAML without a guard, so a typo in an optional
+ * prompt file would otherwise throw on every turn of the session. Degrading to
+ * "no guidance" is the same outcome as the file being absent, which is why this
+ * matches the persona precedent rather than the synchronized-state invariant
+ * that governs composition artifacts.
+ *
+ * `homeDirectory` exists so a test can point the global scope at a temporary
+ * directory; production callers omit it and the reader falls back to the real home.
+ */
+declare function loadModelGuidance(repositoryRoot: string | undefined, homeDirectory?: string): ModelGuidanceMap;
+//#endregion
+export { GUIDANCE_FILE, loadModelGuidance };
+//# sourceMappingURL=modelGuidanceStore.d.mts.map

package/dist/adapters/modelGuidanceStore.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"modelGuidanceStore.d.mts","names":[],"sources":["../../src/adapters/modelGuidanceStore.ts"],"mappings":";;;cAKa;;;;;;;;;;;;;iBAgBG,kBAAkB,oCAAoC,yBAAyB"}

package/dist/adapters/modelGuidanceStore.mjs

@@ -0,0 +1,2 @@
+import{mergeModelGuidance as e}from"../services/modelGuidance.mjs";import{readDoomConfigSources as t}from"@agimon-ai/doompi-config/layeredConfig";const n=`model-guidance.yaml`,r=Object.freeze({});function i(i,a){if(!i)return r;try{let r=t(n,i,a);return e(r.map(e=>e.document))}catch(e){let t=e instanceof Error?e.message:String(e);return process.stderr.write(`[doompi-model-guidance] could not read ${n}: ${t}\n`),r}}export{n as GUIDANCE_FILE,i as loadModelGuidance};
+//# sourceMappingURL=modelGuidanceStore.mjs.map

package/dist/adapters/modelGuidanceStore.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"modelGuidanceStore.mjs","names":[],"sources":["../../src/adapters/modelGuidanceStore.ts"],"sourcesContent":["import { readDoomConfigSources } from '@agimon-ai/doompi-config/layeredConfig';\nimport { mergeModelGuidance } from '../services/modelGuidance.ts';\nimport type { ModelGuidanceDocument, ModelGuidanceMap } from '../types/modelGuidance.ts';\n\n/** Layered guidance document, read from the global then the repository `.doom` directory. */\nexport const GUIDANCE_FILE = 'model-guidance.yaml';\n\nconst EMPTY: ModelGuidanceMap = Object.freeze({});\n\n/**\n * Reads and folds the global and repository guidance documents.\n *\n * Fails open. The reader parses YAML without a guard, so a typo in an optional\n * prompt file would otherwise throw on every turn of the session. Degrading to\n * \"no guidance\" is the same outcome as the file being absent, which is why this\n * matches the persona precedent rather than the synchronized-state invariant\n * that governs composition artifacts.\n *\n * `homeDirectory` exists so a test can point the global scope at a temporary\n * directory; production callers omit it and the reader falls back to the real home.\n */\nexport function loadModelGuidance(repositoryRoot: string | undefined, homeDirectory?: string): ModelGuidanceMap {\n  if (!repositoryRoot) return EMPTY;\n\n  try {\n    const sources = readDoomConfigSources<ModelGuidanceDocument>(GUIDANCE_FILE, repositoryRoot, homeDirectory);\n    return mergeModelGuidance(sources.map((source) => source.document));\n  } catch (error) {\n    const reason = error instanceof Error ? error.message : String(error);\n    process.stderr.write(`[doompi-model-guidance] could not read ${GUIDANCE_FILE}: ${reason}\\n`);\n    return EMPTY;\n  }\n}\n"],"mappings":"kJAKA,MAAa,EAAgB,sBAEvB,EAA0B,OAAO,OAAO,CAAC,CAAC,EAchD,SAAgB,EAAkB,EAAoC,EAA0C,CAC9G,GAAI,CAAC,EAAgB,OAAO,EAE5B,GAAI,CACF,IAAM,EAAU,EAA6C,EAAe,EAAgB,CAAa,EACzG,OAAO,EAAmB,EAAQ,IAAK,GAAW,EAAO,QAAQ,CAAC,CACpE,OAAS,EAAO,CACd,IAAM,EAAS,aAAiB,MAAQ,EAAM,QAAU,OAAO,CAAK,EAEpE,OADA,QAAQ,OAAO,MAAM,0CAA0C,EAAc,IAAI,EAAO,GAAG,EACpF,CACT,CACF"}

package/dist/adapters/pi/extension.cjs

@@ -0,0 +1,2 @@
+const e=require("../../services/modelGuidance.cjs"),t=require("../modelGuidanceStore.cjs");let n=require("@agimon-ai/doompi-config"),r=require("@agimon-ai/doompi-extension-contracts/cordis-host");function i(e,{pi:t}){a(t)}function a(r){r.on(`before_agent_start`,(r,i)=>{let a=i.model?.id;if(!a)return;let o=e.guidanceForModel(t.loadModelGuidance((0,n.getHarnessState)().root),a),s=e.applyModelGuidance(r.systemPrompt,o);return s?{systemPrompt:s}:void 0})}async function o(e){let t=await(0,r.connectDoomCordisHost)(e,`@agimon-ai/doompi-model-guidance`),n=t.root.plugin(i,{pi:e});try{await n}catch(e){throw await n.dispose(),await t.dispose(),e}let a;e.on(`session_shutdown`,()=>a??=(async()=>{try{await n.dispose()}finally{await t.dispose()}})())}exports.activateModelGuidanceExtension=o,exports.default=o,exports.registerModelGuidanceHandlers=a;
+//# sourceMappingURL=extension.cjs.map

package/dist/adapters/pi/extension.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension.cjs","names":["guidanceForModel","loadModelGuidance","getHarnessState","applyModelGuidance","connectDoomCordisHost"],"sources":["../../../src/adapters/pi/extension.ts"],"sourcesContent":["import { getHarnessState } from '@agimon-ai/doompi-config';\nimport { connectDoomCordisHost } from '@agimon-ai/doompi-extension-contracts/cordis-host';\nimport type { Context } from '@deepseek-ai/cordis';\nimport type { ExtensionAPI } from '@earendil-works/pi-coding-agent';\nimport { applyModelGuidance, guidanceForModel } from '../../services/modelGuidance.ts';\nimport { loadModelGuidance } from '../modelGuidanceStore.ts';\n\n/**\n * Appends per-model guidance to the system prompt.\n *\n * The guidance map is read straight from the layered `.doom` documents rather\n * than through the session config service: the reader is synchronous and the\n * repository root comes from the harness environment, so there is nothing to\n * wait on and no readiness barrier to deadlock against.\n *\n * The file is read per turn on purpose. Two existence checks and two small\n * reads are nothing beside the model call that follows, and editing guidance\n * takes effect on the next turn, which is what tuning a prompt for a freshly\n * released model actually needs.\n */\nconst PACKAGE_SOURCE = '@agimon-ai/doompi-model-guidance';\n\ninterface ModelGuidancePluginConfig {\n  readonly pi: ExtensionAPI;\n}\n\nfunction modelGuidancePlugin(_cordis: Context, { pi }: ModelGuidancePluginConfig): void {\n  registerModelGuidanceHandlers(pi);\n}\n\nexport function registerModelGuidanceHandlers(pi: ExtensionAPI): void {\n  pi.on('before_agent_start', (event, ctx) => {\n    const modelId = ctx.model?.id;\n    if (!modelId) return undefined;\n\n    const guidance = guidanceForModel(loadModelGuidance(getHarnessState().root), modelId);\n    const systemPrompt = applyModelGuidance(event.systemPrompt, guidance);\n    return systemPrompt ? { systemPrompt } : undefined;\n  });\n}\n\nexport async function activateModelGuidanceExtension(pi: ExtensionAPI): Promise<void> {\n  const connection = await connectDoomCordisHost(pi, PACKAGE_SOURCE);\n  const fiber = connection.root.plugin(modelGuidancePlugin, { pi });\n  try {\n    await fiber;\n  } catch (error) {\n    await fiber.dispose();\n    await connection.dispose();\n    throw error;\n  }\n\n  let disposal: Promise<void> | undefined;\n  pi.on(\n    'session_shutdown',\n    () =>\n      (disposal ??= (async () => {\n        try {\n          await fiber.dispose();\n        } finally {\n          await connection.dispose();\n        }\n      })()),\n  );\n}\n\nexport default activateModelGuidanceExtension;\n"],"mappings":"oMA0BA,SAAS,EAAoB,EAAkB,CAAE,MAAuC,CACtF,EAA8B,CAAE,CAClC,CAEA,SAAgB,EAA8B,EAAwB,CACpE,EAAG,GAAG,sBAAuB,EAAO,IAAQ,CAC1C,IAAM,EAAU,EAAI,OAAO,GAC3B,GAAI,CAAC,EAAS,OAEd,IAAM,EAAWA,EAAAA,iBAAiBC,EAAAA,mBAAAA,EAAkBC,EAAAA,gBAAAA,CAAgB,CAAC,CAAC,IAAI,EAAG,CAAO,EAC9E,EAAeC,EAAAA,mBAAmB,EAAM,aAAc,CAAQ,EACpE,OAAO,EAAe,CAAE,cAAa,EAAI,IAAA,EAC3C,CAAC,CACH,CAEA,eAAsB,EAA+B,EAAiC,CACpF,IAAM,EAAa,MAAA,EAAMC,EAAAA,sBAAAA,CAAsB,EAAI,kCAAc,EAC3D,EAAQ,EAAW,KAAK,OAAO,EAAqB,CAAE,IAAG,CAAC,EAChE,GAAI,CACF,MAAM,CACR,OAAS,EAAO,CAGd,MAFA,MAAM,EAAM,QAAQ,EACpB,MAAM,EAAW,QAAQ,EACnB,CACR,CAEA,IAAI,EACJ,EAAG,GACD,uBAEG,KAAc,SAAY,CACzB,GAAI,CACF,MAAM,EAAM,QAAQ,CACtB,QAAU,CACR,MAAM,EAAW,QAAQ,CAC3B,CACF,EAAA,CAAG,CACP,CACF"}

package/dist/adapters/pi/extension.d.cts

@@ -0,0 +1,6 @@
+import { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+//#region src/adapters/pi/extension.d.ts
+declare function activateModelGuidanceExtension(pi: ExtensionAPI): Promise<void>;
+//#endregion
+export { activateModelGuidanceExtension, activateModelGuidanceExtension as default };
+//# sourceMappingURL=extension.d.cts.map

package/dist/adapters/pi/extension.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension.d.cts","names":[],"sources":["../../../src/adapters/pi/extension.ts"],"mappings":";;iBAyCsB,+BAA+B,IAAI,eAAe"}

package/dist/adapters/pi/extension.d.mts

@@ -0,0 +1,6 @@
+import { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+//#region src/adapters/pi/extension.d.ts
+declare function activateModelGuidanceExtension(pi: ExtensionAPI): Promise<void>;
+//#endregion
+export { activateModelGuidanceExtension, activateModelGuidanceExtension as default };
+//# sourceMappingURL=extension.d.mts.map

package/dist/adapters/pi/extension.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension.d.mts","names":[],"sources":["../../../src/adapters/pi/extension.ts"],"mappings":";;iBAyCsB,+BAA+B,IAAI,eAAe"}

package/dist/adapters/pi/extension.mjs

@@ -0,0 +1,2 @@
+import{applyModelGuidance as e,guidanceForModel as t}from"../../services/modelGuidance.mjs";import{loadModelGuidance as n}from"../modelGuidanceStore.mjs";import{getHarnessState as r}from"@agimon-ai/doompi-config";import{connectDoomCordisHost as i}from"@agimon-ai/doompi-extension-contracts/cordis-host";function a(e,{pi:t}){o(t)}function o(i){i.on(`before_agent_start`,(i,a)=>{let o=a.model?.id;if(!o)return;let s=t(n(r().root),o),c=e(i.systemPrompt,s);return c?{systemPrompt:c}:void 0})}async function s(e){let t=await i(e,`@agimon-ai/doompi-model-guidance`),n=t.root.plugin(a,{pi:e});try{await n}catch(e){throw await n.dispose(),await t.dispose(),e}let r;e.on(`session_shutdown`,()=>r??=(async()=>{try{await n.dispose()}finally{await t.dispose()}})())}export{s as activateModelGuidanceExtension,s as default,o as registerModelGuidanceHandlers};
+//# sourceMappingURL=extension.mjs.map

package/dist/adapters/pi/extension.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension.mjs","names":[],"sources":["../../../src/adapters/pi/extension.ts"],"sourcesContent":["import { getHarnessState } from '@agimon-ai/doompi-config';\nimport { connectDoomCordisHost } from '@agimon-ai/doompi-extension-contracts/cordis-host';\nimport type { Context } from '@deepseek-ai/cordis';\nimport type { ExtensionAPI } from '@earendil-works/pi-coding-agent';\nimport { applyModelGuidance, guidanceForModel } from '../../services/modelGuidance.ts';\nimport { loadModelGuidance } from '../modelGuidanceStore.ts';\n\n/**\n * Appends per-model guidance to the system prompt.\n *\n * The guidance map is read straight from the layered `.doom` documents rather\n * than through the session config service: the reader is synchronous and the\n * repository root comes from the harness environment, so there is nothing to\n * wait on and no readiness barrier to deadlock against.\n *\n * The file is read per turn on purpose. Two existence checks and two small\n * reads are nothing beside the model call that follows, and editing guidance\n * takes effect on the next turn, which is what tuning a prompt for a freshly\n * released model actually needs.\n */\nconst PACKAGE_SOURCE = '@agimon-ai/doompi-model-guidance';\n\ninterface ModelGuidancePluginConfig {\n  readonly pi: ExtensionAPI;\n}\n\nfunction modelGuidancePlugin(_cordis: Context, { pi }: ModelGuidancePluginConfig): void {\n  registerModelGuidanceHandlers(pi);\n}\n\nexport function registerModelGuidanceHandlers(pi: ExtensionAPI): void {\n  pi.on('before_agent_start', (event, ctx) => {\n    const modelId = ctx.model?.id;\n    if (!modelId) return undefined;\n\n    const guidance = guidanceForModel(loadModelGuidance(getHarnessState().root), modelId);\n    const systemPrompt = applyModelGuidance(event.systemPrompt, guidance);\n    return systemPrompt ? { systemPrompt } : undefined;\n  });\n}\n\nexport async function activateModelGuidanceExtension(pi: ExtensionAPI): Promise<void> {\n  const connection = await connectDoomCordisHost(pi, PACKAGE_SOURCE);\n  const fiber = connection.root.plugin(modelGuidancePlugin, { pi });\n  try {\n    await fiber;\n  } catch (error) {\n    await fiber.dispose();\n    await connection.dispose();\n    throw error;\n  }\n\n  let disposal: Promise<void> | undefined;\n  pi.on(\n    'session_shutdown',\n    () =>\n      (disposal ??= (async () => {\n        try {\n          await fiber.dispose();\n        } finally {\n          await connection.dispose();\n        }\n      })()),\n  );\n}\n\nexport default activateModelGuidanceExtension;\n"],"mappings":"+SA0BA,SAAS,EAAoB,EAAkB,CAAE,MAAuC,CACtF,EAA8B,CAAE,CAClC,CAEA,SAAgB,EAA8B,EAAwB,CACpE,EAAG,GAAG,sBAAuB,EAAO,IAAQ,CAC1C,IAAM,EAAU,EAAI,OAAO,GAC3B,GAAI,CAAC,EAAS,OAEd,IAAM,EAAW,EAAiB,EAAkB,EAAgB,CAAC,CAAC,IAAI,EAAG,CAAO,EAC9E,EAAe,EAAmB,EAAM,aAAc,CAAQ,EACpE,OAAO,EAAe,CAAE,cAAa,EAAI,IAAA,EAC3C,CAAC,CACH,CAEA,eAAsB,EAA+B,EAAiC,CACpF,IAAM,EAAa,MAAM,EAAsB,EAAI,kCAAc,EAC3D,EAAQ,EAAW,KAAK,OAAO,EAAqB,CAAE,IAAG,CAAC,EAChE,GAAI,CACF,MAAM,CACR,OAAS,EAAO,CAGd,MAFA,MAAM,EAAM,QAAQ,EACpB,MAAM,EAAW,QAAQ,EACnB,CACR,CAEA,IAAI,EACJ,EAAG,GACD,uBAEG,KAAc,SAAY,CACzB,GAAI,CACF,MAAM,EAAM,QAAQ,CACtB,QAAU,CACR,MAAM,EAAW,QAAQ,CAC3B,CACF,EAAA,CAAG,CACP,CACF"}

package/dist/extensions/pi.cjs

@@ -0,0 +1 @@
+Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:`Module`}});const e=require("../adapters/pi/extension.cjs");exports.activateModelGuidanceExtension=e.activateModelGuidanceExtension,exports.default=e.activateModelGuidanceExtension;

package/dist/extensions/pi.d.cts

@@ -0,0 +1,2 @@
+import { activateModelGuidanceExtension } from "../adapters/pi/extension.cjs";
+export { activateModelGuidanceExtension, activateModelGuidanceExtension as default };

package/dist/extensions/pi.d.mts

@@ -0,0 +1,2 @@
+import { activateModelGuidanceExtension } from "../adapters/pi/extension.mjs";
+export { activateModelGuidanceExtension, activateModelGuidanceExtension as default };

package/dist/extensions/pi.mjs

@@ -0,0 +1 @@
+import{activateModelGuidanceExtension as e}from"../adapters/pi/extension.mjs";export{e as activateModelGuidanceExtension,e as default};

package/dist/index.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./services/modelGuidance.cjs"),t=require("./adapters/modelGuidanceStore.cjs");exports.GUIDANCE_FILE=t.GUIDANCE_FILE,exports.applyModelGuidance=e.applyModelGuidance,exports.guidanceForModel=e.guidanceForModel,exports.loadModelGuidance=t.loadModelGuidance,exports.mergeModelGuidance=e.mergeModelGuidance;

package/dist/index.d.cts

@@ -0,0 +1,4 @@
+import { ModelGuidanceDocument, ModelGuidanceMap } from "./types/modelGuidance.cjs";
+import { GUIDANCE_FILE, loadModelGuidance } from "./adapters/modelGuidanceStore.cjs";
+import { applyModelGuidance, guidanceForModel, mergeModelGuidance } from "./services/modelGuidance.cjs";
+export { GUIDANCE_FILE, type ModelGuidanceDocument, type ModelGuidanceMap, applyModelGuidance, guidanceForModel, loadModelGuidance, mergeModelGuidance };

package/dist/index.d.mts

@@ -0,0 +1,4 @@
+import { ModelGuidanceDocument, ModelGuidanceMap } from "./types/modelGuidance.mjs";
+import { GUIDANCE_FILE, loadModelGuidance } from "./adapters/modelGuidanceStore.mjs";
+import { applyModelGuidance, guidanceForModel, mergeModelGuidance } from "./services/modelGuidance.mjs";
+export { GUIDANCE_FILE, type ModelGuidanceDocument, type ModelGuidanceMap, applyModelGuidance, guidanceForModel, loadModelGuidance, mergeModelGuidance };

package/dist/index.mjs

@@ -0,0 +1 @@
+import{applyModelGuidance as e,guidanceForModel as t,mergeModelGuidance as n}from"./services/modelGuidance.mjs";import{GUIDANCE_FILE as r,loadModelGuidance as i}from"./adapters/modelGuidanceStore.mjs";export{r as GUIDANCE_FILE,e as applyModelGuidance,t as guidanceForModel,i as loadModelGuidance,n as mergeModelGuidance};

package/dist/services/modelGuidance.cjs

@@ -0,0 +1,2 @@
+function e(e){let t={};for(let n of e)for(let[e,r]of Object.entries(n.modelGuidance??{})){if(typeof r!=`string`)continue;let n=r.trim();n&&(t[e]=n)}return t}function t(e,t){if(t)return e[t]}function n(e,t){if(t)return`${e}\n\n${t}`}exports.applyModelGuidance=n,exports.guidanceForModel=t,exports.mergeModelGuidance=e;
+//# sourceMappingURL=modelGuidance.cjs.map

package/dist/services/modelGuidance.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"modelGuidance.cjs","names":[],"sources":["../../src/services/modelGuidance.ts"],"sourcesContent":["import type { ModelGuidanceDocument, ModelGuidanceMap } from '../types/modelGuidance.ts';\n\n/**\n * Folds guidance documents in source order, so a later document overrides one\n * model id at a time.\n *\n * The reader hands back global then repository, so a repository entry wins the\n * ids it names while global entries it does not name survive. That per-id\n * granularity is the point: a personal default stays useful inside a project\n * that only pins one model.\n *\n * Non-string values are dropped rather than rejected, because a guidance file is\n * optional user input and one bad entry must not discard the rest.\n */\nexport function mergeModelGuidance(documents: readonly ModelGuidanceDocument[]): ModelGuidanceMap {\n  const merged: Record<string, string> = {};\n  for (const document of documents) {\n    for (const [modelId, guidance] of Object.entries(document.modelGuidance ?? {})) {\n      if (typeof guidance !== 'string') continue;\n      const trimmed = guidance.trim();\n      if (trimmed) merged[modelId] = trimmed;\n    }\n  }\n  return merged;\n}\n\n/** Exact-match lookup. An unknown or absent model id contributes nothing. */\nexport function guidanceForModel(guidance: ModelGuidanceMap, modelId: string | undefined): string | undefined {\n  if (!modelId) return undefined;\n  return guidance[modelId];\n}\n\n/**\n * Builds the replacement system prompt for one turn.\n *\n * Pi treats a returned `systemPrompt` as a full replacement and chains handlers,\n * so the incoming prompt has to be re-embedded. Returning bare guidance would\n * discard every earlier contribution, including plan mode and the persona.\n * Keeping that in one function leaves a single place for it to be right.\n */\nexport function applyModelGuidance(systemPrompt: string, guidance: string | undefined): string | undefined {\n  if (!guidance) return undefined;\n  return `${systemPrompt}\\n\\n${guidance}`;\n}\n"],"mappings":"AAcA,SAAgB,EAAmB,EAA+D,CAChG,IAAM,EAAiC,CAAC,EACxC,IAAK,IAAM,KAAY,EACrB,IAAK,GAAM,CAAC,EAAS,KAAa,OAAO,QAAQ,EAAS,eAAiB,CAAC,CAAC,EAAG,CAC9E,GAAI,OAAO,GAAa,SAAU,SAClC,IAAM,EAAU,EAAS,KAAK,EAC1B,IAAS,EAAO,GAAW,EACjC,CAEF,OAAO,CACT,CAGA,SAAgB,EAAiB,EAA4B,EAAiD,CACvG,KACL,OAAO,EAAS,EAClB,CAUA,SAAgB,EAAmB,EAAsB,EAAkD,CACpG,KACL,MAAO,GAAG,EAAa,MAAM,GAC/B"}

package/dist/services/modelGuidance.d.cts

@@ -0,0 +1,29 @@
+import { ModelGuidanceDocument, ModelGuidanceMap } from "../types/modelGuidance.cjs";
+//#region src/services/modelGuidance.d.ts
+/**
+ * Folds guidance documents in source order, so a later document overrides one
+ * model id at a time.
+ *
+ * The reader hands back global then repository, so a repository entry wins the
+ * ids it names while global entries it does not name survive. That per-id
+ * granularity is the point: a personal default stays useful inside a project
+ * that only pins one model.
+ *
+ * Non-string values are dropped rather than rejected, because a guidance file is
+ * optional user input and one bad entry must not discard the rest.
+ */
+declare function mergeModelGuidance(documents: readonly ModelGuidanceDocument[]): ModelGuidanceMap;
+/** Exact-match lookup. An unknown or absent model id contributes nothing. */
+declare function guidanceForModel(guidance: ModelGuidanceMap, modelId: string | undefined): string | undefined;
+/**
+ * Builds the replacement system prompt for one turn.
+ *
+ * Pi treats a returned `systemPrompt` as a full replacement and chains handlers,
+ * so the incoming prompt has to be re-embedded. Returning bare guidance would
+ * discard every earlier contribution, including plan mode and the persona.
+ * Keeping that in one function leaves a single place for it to be right.
+ */
+declare function applyModelGuidance(systemPrompt: string, guidance: string | undefined): string | undefined;
+//#endregion
+export { applyModelGuidance, guidanceForModel, mergeModelGuidance };
+//# sourceMappingURL=modelGuidance.d.cts.map

package/dist/services/modelGuidance.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"modelGuidance.d.cts","names":[],"sources":["../../src/services/modelGuidance.ts"],"mappings":";;;;;;;;;;;;;;iBAcgB,mBAAmB,oBAAoB,0BAA0B;;iBAajE,iBAAiB,UAAU,kBAAkB;;;;;;;;;iBAa7C,mBAAmB,sBAAsB"}

package/dist/services/modelGuidance.d.mts

@@ -0,0 +1,29 @@
+import { ModelGuidanceDocument, ModelGuidanceMap } from "../types/modelGuidance.mjs";
+//#region src/services/modelGuidance.d.ts
+/**
+ * Folds guidance documents in source order, so a later document overrides one
+ * model id at a time.
+ *
+ * The reader hands back global then repository, so a repository entry wins the
+ * ids it names while global entries it does not name survive. That per-id
+ * granularity is the point: a personal default stays useful inside a project
+ * that only pins one model.
+ *
+ * Non-string values are dropped rather than rejected, because a guidance file is
+ * optional user input and one bad entry must not discard the rest.
+ */
+declare function mergeModelGuidance(documents: readonly ModelGuidanceDocument[]): ModelGuidanceMap;
+/** Exact-match lookup. An unknown or absent model id contributes nothing. */
+declare function guidanceForModel(guidance: ModelGuidanceMap, modelId: string | undefined): string | undefined;
+/**
+ * Builds the replacement system prompt for one turn.
+ *
+ * Pi treats a returned `systemPrompt` as a full replacement and chains handlers,
+ * so the incoming prompt has to be re-embedded. Returning bare guidance would
+ * discard every earlier contribution, including plan mode and the persona.
+ * Keeping that in one function leaves a single place for it to be right.
+ */
+declare function applyModelGuidance(systemPrompt: string, guidance: string | undefined): string | undefined;
+//#endregion
+export { applyModelGuidance, guidanceForModel, mergeModelGuidance };
+//# sourceMappingURL=modelGuidance.d.mts.map

package/dist/services/modelGuidance.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"modelGuidance.d.mts","names":[],"sources":["../../src/services/modelGuidance.ts"],"mappings":";;;;;;;;;;;;;;iBAcgB,mBAAmB,oBAAoB,0BAA0B;;iBAajE,iBAAiB,UAAU,kBAAkB;;;;;;;;;iBAa7C,mBAAmB,sBAAsB"}

package/dist/services/modelGuidance.mjs

@@ -0,0 +1,2 @@
+function e(e){let t={};for(let n of e)for(let[e,r]of Object.entries(n.modelGuidance??{})){if(typeof r!=`string`)continue;let n=r.trim();n&&(t[e]=n)}return t}function t(e,t){if(t)return e[t]}function n(e,t){if(t)return`${e}\n\n${t}`}export{n as applyModelGuidance,t as guidanceForModel,e as mergeModelGuidance};
+//# sourceMappingURL=modelGuidance.mjs.map

package/dist/services/modelGuidance.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"modelGuidance.mjs","names":[],"sources":["../../src/services/modelGuidance.ts"],"sourcesContent":["import type { ModelGuidanceDocument, ModelGuidanceMap } from '../types/modelGuidance.ts';\n\n/**\n * Folds guidance documents in source order, so a later document overrides one\n * model id at a time.\n *\n * The reader hands back global then repository, so a repository entry wins the\n * ids it names while global entries it does not name survive. That per-id\n * granularity is the point: a personal default stays useful inside a project\n * that only pins one model.\n *\n * Non-string values are dropped rather than rejected, because a guidance file is\n * optional user input and one bad entry must not discard the rest.\n */\nexport function mergeModelGuidance(documents: readonly ModelGuidanceDocument[]): ModelGuidanceMap {\n  const merged: Record<string, string> = {};\n  for (const document of documents) {\n    for (const [modelId, guidance] of Object.entries(document.modelGuidance ?? {})) {\n      if (typeof guidance !== 'string') continue;\n      const trimmed = guidance.trim();\n      if (trimmed) merged[modelId] = trimmed;\n    }\n  }\n  return merged;\n}\n\n/** Exact-match lookup. An unknown or absent model id contributes nothing. */\nexport function guidanceForModel(guidance: ModelGuidanceMap, modelId: string | undefined): string | undefined {\n  if (!modelId) return undefined;\n  return guidance[modelId];\n}\n\n/**\n * Builds the replacement system prompt for one turn.\n *\n * Pi treats a returned `systemPrompt` as a full replacement and chains handlers,\n * so the incoming prompt has to be re-embedded. Returning bare guidance would\n * discard every earlier contribution, including plan mode and the persona.\n * Keeping that in one function leaves a single place for it to be right.\n */\nexport function applyModelGuidance(systemPrompt: string, guidance: string | undefined): string | undefined {\n  if (!guidance) return undefined;\n  return `${systemPrompt}\\n\\n${guidance}`;\n}\n"],"mappings":"AAcA,SAAgB,EAAmB,EAA+D,CAChG,IAAM,EAAiC,CAAC,EACxC,IAAK,IAAM,KAAY,EACrB,IAAK,GAAM,CAAC,EAAS,KAAa,OAAO,QAAQ,EAAS,eAAiB,CAAC,CAAC,EAAG,CAC9E,GAAI,OAAO,GAAa,SAAU,SAClC,IAAM,EAAU,EAAS,KAAK,EAC1B,IAAS,EAAO,GAAW,EACjC,CAEF,OAAO,CACT,CAGA,SAAgB,EAAiB,EAA4B,EAAiD,CACvG,KACL,OAAO,EAAS,EAClB,CAUA,SAAgB,EAAmB,EAAsB,EAAkD,CACpG,KACL,MAAO,GAAG,EAAa,MAAM,GAC/B"}

package/dist/types/modelGuidance.d.cts

@@ -0,0 +1,17 @@
+//#region src/types/modelGuidance.d.ts
+/**
+ * Wire and domain shapes for per-model system prompt guidance.
+ *
+ * Document values are `unknown` rather than `string` because a guidance file is
+ * user-authored YAML: the parser cannot promise a string, so the fold narrows
+ * each value instead of asserting one.
+ */
+/** Raw shape of one `.doom/model-guidance.yaml` document. */
+interface ModelGuidanceDocument {
+  readonly modelGuidance?: Readonly<Record<string, unknown>>;
+}
+/** Model id to guidance text, after the global and repository documents are folded. */
+type ModelGuidanceMap = Readonly<Record<string, string>>;
+//#endregion
+export { ModelGuidanceDocument, ModelGuidanceMap };
+//# sourceMappingURL=modelGuidance.d.cts.map

package/dist/types/modelGuidance.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"modelGuidance.d.cts","names":[],"sources":["../../src/types/modelGuidance.ts"],"mappings":";;;;;;;;;UASiB;WACN,gBAAgB,SAAS;;;KAIxB,mBAAmB,SAAS"}

package/dist/types/modelGuidance.d.mts

@@ -0,0 +1,17 @@
+//#region src/types/modelGuidance.d.ts
+/**
+ * Wire and domain shapes for per-model system prompt guidance.
+ *
+ * Document values are `unknown` rather than `string` because a guidance file is
+ * user-authored YAML: the parser cannot promise a string, so the fold narrows
+ * each value instead of asserting one.
+ */
+/** Raw shape of one `.doom/model-guidance.yaml` document. */
+interface ModelGuidanceDocument {
+  readonly modelGuidance?: Readonly<Record<string, unknown>>;
+}
+/** Model id to guidance text, after the global and repository documents are folded. */
+type ModelGuidanceMap = Readonly<Record<string, string>>;
+//#endregion
+export { ModelGuidanceDocument, ModelGuidanceMap };
+//# sourceMappingURL=modelGuidance.d.mts.map

package/dist/types/modelGuidance.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"modelGuidance.d.mts","names":[],"sources":["../../src/types/modelGuidance.ts"],"mappings":";;;;;;;;;UASiB;WACN,gBAAgB,SAAS;;;KAIxB,mBAAmB,SAAS"}

package/llms.txt

@@ -0,0 +1,11 @@
+# @agimon-ai/doompi-model-guidance
+
+Package-owned guidance for per-model system prompt guidance, layered across global and repository scope
+
+## How to use
+
+- [Use Model Guidance](./src/prompts/doompi-use-model-guidance/SKILL.md): Configure per-model system prompt text and understand how the two scopes merge.
+
+## Resources
+
+- [Package README](./README.md): Installation, development commands, Pi entrypoint, and extension-specific usage.

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "@agimon-ai/doompi-model-guidance",
+  "version": "0.0.1-alpha.63",
+  "description": "Per-model system prompt guidance for Pi agents, layered across global and repository scope.",
+  "keywords": [
+    "ai",
+    "coding-agent",
+    "developer-tools",
+    "doompi",
+    "model-guidance",
+    "pi-coding-agent",
+    "pi-extension",
+    "pi-package",
+    "system-prompt",
+    "typescript"
+  ],
+  "homepage": "https://agimon.ai",
+  "bugs": {
+    "url": "https://github.com/AgiFlow/doompi/issues"
+  },
+  "license": "MIT",
+  "author": "Vuong Ngo",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AgiFlow/doompi.git",
+    "directory": "layers/llm/doompi-model-guidance"
+  },
+  "files": [
+    "dist",
+    "src/prompts",
+    "llms.txt",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.mts",
+  "jsnext:main": "./dist/index.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./extensions/pi": {
+      "types": "./dist/extensions/pi.d.mts",
+      "import": "./dist/extensions/pi.mjs",
+      "require": "./dist/extensions/pi.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@deepseek-ai/cordis": "4.0.2",
+    "@agimon-ai/doompi-extension-contracts": "0.0.1-alpha.63",
+    "@agimon-ai/doompi-config": "0.0.1-alpha.63"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.85.1",
+    "@types/node": "26.4.0",
+    "@vitest/coverage-v8": "5.0.0",
+    "tsdown": "0.22.14",
+    "typescript": "7.0.2",
+    "vitest": "5.0.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "0.85.1"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "pi": {
+    "extensions": [
+      "./dist/extensions/pi.mjs"
+    ]
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest --run",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint . && oxfmt . --check",
+    "fixcode": "oxlint . --fix && oxfmt ."
+  }
+}

package/src/prompts/doompi-use-model-guidance/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: doompi-use-model-guidance
+description: 'Use @agimon-ai/doompi-model-guidance: per-model system prompt guidance, layered across global and repository scope'
+---
+
+# Use Model Guidance
+
+Read the package [README](../../../README.md) for its exact installation, configuration, and behavior.
+
+## Guidance
+
+Write guidance for a model id in either scope:
+
+- Global, applying to every repository: `~/.pi/.doom/model-guidance.yaml`
+- Repository, applying to one project: `<repository>/.doom/model-guidance.yaml`
+
+```yaml
+modelGuidance:
+  claude-opus-5: |
+    Keep the task focused. Never go off rails.
+```
+
+Model ids match exactly. Use the id shown by `/model`, not a family or a
+marketing name. An id that does not match contributes nothing and never errors,
+so a silent absence of guidance usually means the id is wrong.
+
+Both scopes apply. A repository entry replaces the global entry for the model
+ids it names, and global entries for other ids still apply.
+
+Guidance is read per turn, so an edit takes effect on the next message with no
+restart.