ENHANCEMENT: Cascading of defaults adds model & vendor fields

PredictabilityAtScale · PredictabilityAtScale · commit c3b1812f647a · 2026-04-20T09:16:13.000-07:00
diff --git a/README.md b/README.md
@@ -15,7 +15,7 @@ Provider adapters for OpenAI, Anthropic, Gemini, and OpenRouter produce a ready-
 - **Centralized, not scattered** — each prompt is a single Markdown file that captures prompt text, model config, tool bindings, and context rules together.
 - **Operational, not just templated** — model name, temperature, reasoning effort, tools, and response format are declared alongside the prompt they govern.
 - **Reusable, not duplicated** — `includes` lets you define shared tone, policy, or safety instructions once and compose them into any prompt.
-- **Layered defaults, not repetition** — `defaults.md` in any folder sets shared `metadata` and `# System instructions` for that subtree, with nearest-folder override behavior.
+- **Layered defaults, not repetition** — `defaults.md` in any folder sets shared `provider`, `model`, `metadata`, and `# System instructions` for that subtree, with nearest-folder override behavior.
 - **Release-aware, not ad hoc** — environment and tier overrides swap models and parameters without forking prompt files.
 - **Provider-portable** — write once, render for OpenAI, Anthropic, Gemini, or OpenRouter with correct body shapes.
 - **Validate early** — Zod schema validation, Levenshtein-based "did you mean?" suggestions for typos, and variable usage checks catch mistakes before runtime.
@@ -40,6 +40,7 @@ This creates:
 
 ```
 prompts/
+├── defaults.md         # Folder-level defaults (provider, model, metadata, system instructions)
 ├── hello.md            # Sample prompt with variables
 ├── hello.test.yaml     # Test sidecar with sample inputs
 └── shared/
@@ -107,7 +108,7 @@ const response = await fetch('https://api.openai.com/v1/chat/completions', {
 - **Prompts as Markdown** — YAML front matter for settings, H1 headings for sections (`# System instructions`, `# Prompt template`, `# Notes`)
 - **Variable interpolation** — `{{ variable }}` syntax with strict and permissive modes
 - **Composition** — `includes` to share system instructions across prompts, with circular detection
-- **Folder defaults** — `defaults.md` inheritance for shared metadata and system instructions
+- **Folder defaults** — `defaults.md` inheritance for shared provider, model, metadata, and system instructions
 - **Overrides** — Environment and tier-based overrides (base → env → tier → runtime)
 - **4 provider adapters** — OpenAI, Anthropic, Gemini, OpenRouter — body-only output
 - **Validation** — Zod schema validation, Levenshtein-based "did you mean?" for typos, variable usage checks
@@ -221,6 +222,7 @@ Handle support requests carefully.
 
 Define a `defaults.md` file in `prompts/` (and optional subfolders) to provide inherited defaults for prompts:
 
+- Shared `provider` and `model` in front matter
 - Shared `metadata` defaults in front matter
 - Shared `# System instructions` in body
 - Nearest subfolder `defaults.md` overrides parent defaults
diff --git a/docs/cli.md b/docs/cli.md
@@ -22,7 +22,7 @@ Creates:
 
 ```
 prompts/
-├── defaults.md         # Folder-level defaults (metadata + system instructions)
+├── defaults.md         # Folder-level defaults (provider, model, metadata, system instructions)
 ├── hello.md            # Sample prompt with variables
 ├── hello.test.yaml     # Test sidecar with sample inputs
 └── shared/
@@ -50,7 +50,7 @@ Checks:
 - Unknown front matter keys with Levenshtein-based "did you mean?" suggestions
 - Variable usage — used but undeclared, declared but unused
 - Include resolution — missing files, circular includes
-- Folder defaults inheritance from `defaults.md` (metadata + system instructions)
+- Folder defaults inheritance from `defaults.md` (provider, model, metadata, system instructions)
 
 Output per file:
 ```
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -18,7 +18,7 @@ This creates:
 
 ```
 prompts/
-├── defaults.md         # Folder-level defaults (metadata + system instructions)
+├── defaults.md         # Folder-level defaults (provider, model, metadata, system instructions)
 ├── hello.md            # Sample prompt with variables
 ├── hello.test.yaml     # Test sidecar with sample inputs
 └── shared/
diff --git a/docs/prompt-format.md b/docs/prompt-format.md
@@ -52,14 +52,18 @@ You can define shared defaults for an entire prompt tree by adding a `defaults.m
 
 Supported default fields:
 
-- `metadata` (front matter)
-- `# System instructions` (body section)
+- `provider` (front matter) — default provider for the folder
+- `model` (front matter) — default model for the folder
+- `metadata` (front matter) — merged with prompt-local metadata
+- `# System instructions` (body section) — used when the prompt has none
+
+This lets you configure app-wide settings like `provider` and `model` in a single place. Individual prompts only need to declare what's unique to them.
 
 Example:
 
 ```text
 prompts/
-├── defaults.md          # global metadata + system instructions
+├── defaults.md          # global settings, metadata + system instructions
 └── support/
     ├── defaults.md      # overrides for support/*
     └── reply.md         # inherits from support/defaults.md
@@ -69,6 +73,8 @@ prompts/
 
 ```markdown
 ---
+provider: openai
+model: gpt-5.4
 metadata:
   owner: platform
   review_required: true
@@ -93,6 +99,8 @@ Use support tone and escalation policy.
 ```
 
 `prompts/support/reply.md` (no local `metadata.owner` and no local system section) will use:
+- `provider: openai` (inherited from root defaults)
+- `model: gpt-5.4` (inherited from root defaults)
 - `metadata.owner: support` (nearest override)
 - `metadata.review_required: true` (inherited from parent defaults)
 - system instructions from `support/defaults.md`
diff --git a/docs/schema.md b/docs/schema.md
@@ -29,6 +29,8 @@ Prompt files use YAML front matter. This page documents every supported field.
 
 | Field | Type | Description |
 |-------|------|-------------|
+| `provider` | `enum` | Default provider (`openai`, `anthropic`, `google`, `gemini`, `openrouter`, `any`) |
+| `model` | `string` | Default model identifier |
 | `metadata` | `object` | Same as the prompt `metadata` block (`owner`, `tags`, `review_required`, `stable`) |
 | `# System instructions` | section | System instructions inherited by prompts in this folder |
 
diff --git a/fixtures/compiled/.gitkeep b/fixtures/compiled/.gitkeep
diff --git a/fixtures/compiled/hello.json b/fixtures/compiled/hello.json
@@ -0,0 +1,23 @@
+{
+  "id": "hello",
+  "schema_version": 1,
+  "context": {
+    "inputs": [
+      "name",
+      "app_context"
+    ]
+  },
+  "sections": {
+    "system_instructions": "You are a friendly assistant helping in {{ app_context }}.",
+    "prompt_template": "Say hello to {{ name }}."
+  },
+  "source": {
+    "file_path": "fixtures\\prompts\\hello.md"
+  },
+  "provider": "openai",
+  "model": "gpt-5.4",
+  "metadata": {
+    "owner": "platform-team",
+    "review_required": true
+  }
+}
diff --git a/fixtures/compiled/shared/tone.json b/fixtures/compiled/shared/tone.json
@@ -0,0 +1,16 @@
+{
+  "id": "shared.tone",
+  "schema_version": 1,
+  "sections": {
+    "system_instructions": "Always be polite, professional, and concise. Avoid jargon unless the user uses it first."
+  },
+  "source": {
+    "file_path": "fixtures\\prompts\\shared\\tone.md"
+  },
+  "provider": "openai",
+  "model": "gpt-5.4",
+  "metadata": {
+    "owner": "platform-team",
+    "review_required": true
+  }
+}
diff --git a/fixtures/compiled/support/reply.json b/fixtures/compiled/support/reply.json
@@ -0,0 +1,63 @@
+{
+  "id": "support.reply",
+  "schema_version": 1,
+  "provider": "openai",
+  "model": "gpt-5.4",
+  "fallback_models": [
+    "gpt-5.4-mini"
+  ],
+  "reasoning": {
+    "effort": "medium"
+  },
+  "sampling": {
+    "temperature": 0.7,
+    "max_output_tokens": 2048
+  },
+  "response": {
+    "format": "text"
+  },
+  "tools": [
+    "get_account_status"
+  ],
+  "context": {
+    "inputs": [
+      "user_message",
+      "account_summary",
+      "app_context"
+    ],
+    "history": {
+      "max_items": 8
+    }
+  },
+  "environments": {
+    "dev": {
+      "model": "gpt-5.4-mini",
+      "reasoning": {
+        "effort": "low"
+      }
+    },
+    "prod": {
+      "model": "gpt-5.4"
+    }
+  },
+  "tiers": {
+    "free": {
+      "model": "gpt-5.4-mini"
+    },
+    "pro": {
+      "model": "gpt-5.4"
+    }
+  },
+  "metadata": {
+    "owner": "support-platform",
+    "review_required": true,
+    "stable": true
+  },
+  "sections": {
+    "system_instructions": "Always be polite, professional, and concise. Avoid jargon unless the user uses it first.\n\nYou are a careful support assistant. Follow refund policy exactly.\nCurrent app context: {{ app_context }}.",
+    "prompt_template": "Customer message:\n{{ user_message }}\n\nAccount summary:\n{{ account_summary }}"
+  },
+  "source": {
+    "file_path": "fixtures\\prompts\\support\\reply.md"
+  }
+}
diff --git a/fixtures/prompts/defaults.md b/fixtures/prompts/defaults.md
@@ -1,4 +1,6 @@
 ---
+provider: openai
+model: gpt-5.4
 metadata:
   owner: platform-team
   review_required: true
diff --git a/fixtures/prompts/hello.md b/fixtures/prompts/hello.md
@@ -1,8 +1,5 @@
 ---
 id: hello
-schema_version: 1
-provider: openai
-model: gpt-5.4
 context:
   inputs:
     - name
diff --git a/src/cli/commands/init.ts b/src/cli/commands/init.ts
@@ -13,9 +13,6 @@ Options:
 
 const HELLO_PROMPT = `---
 id: hello
-schema_version: 1
-provider: openai
-model: gpt-5.4
 context:
   inputs:
     - name
@@ -50,6 +47,8 @@ Always be polite, professional, and concise. Avoid jargon unless the user uses i
 `.trimStart();
 
 const DEFAULTS = `---
+provider: openai
+model: gpt-5.4
 metadata:
   owner: my-team
   review_required: true
diff --git a/src/cli/commands/skill.ts b/src/cli/commands/skill.ts
@@ -200,16 +200,21 @@ folder:
 
 \`\`\`text
 prompts/
-├── defaults.md          # global metadata + system instructions
+├── defaults.md          # global provider, model, metadata + system instructions
 └── support/
     ├── defaults.md      # overrides for support/*
     └── reply.md         # inherits from support/defaults.md
 \`\`\`
 
 Supported default fields:
+- \`provider\` (front matter) — default provider for the folder
+- \`model\` (front matter) — default model for the folder
 - \`metadata\` (front matter) — merged with prompt-local metadata
 - \`# System instructions\` (body section) — used when the prompt has none
 
+This lets you configure app-wide settings like \`provider\` and \`model\`
+in a single root \`defaults.md\`, so individual prompts only declare what\u2019s unique to them.
+
 Rules:
 - Nearest subfolder \`defaults.md\` overrides parent defaults
 - Prompt-local values always take precedence over defaults
@@ -390,14 +395,14 @@ Hello {{ name }}
 ## Conventions to follow
 
 1. **One prompt per file** — each \`.md\` file is a single prompt asset
-2. **Always set \`id\` and \`schema_version: 1\`** in front matter
+2. **Always set \`id\` and \`schema_version: 1\`** in front matter (or inherit \`schema_version\` from \`defaults.md\`)
 3. **Declare all variables** in \`context.inputs\` that appear in templates
 4. **Use includes** for shared system instructions (tone, safety, formatting)
 5. **Keep prompt templates focused** — compose behavior via includes, not duplication
 6. **Use environment overrides** for dev/staging/prod model differences
 7. **Add test sidecars** (\`.test.yaml\`) for critical prompts
 8. **Run \`promptopskit validate\`** before committing changes
-9. **Use \`defaults.md\`** to share metadata and system instructions across a folder
+9. **Use \`defaults.md\`** to share provider, model, metadata, and system instructions across a folder
 10. **Variable names** should be \`snake_case\`
 11. **Prompt file names** should be \`kebab-case.md\`
 `.trimEnd();
diff --git a/src/parser/loader.ts b/src/parser/loader.ts
@@ -85,6 +85,8 @@ function parseDefaults(content: string): PromptDefaults {
 
 function mergeDefaults(base: PromptDefaults, local: PromptDefaults): PromptDefaults {
   return {
+    provider: local.provider ?? base.provider,
+    model: local.model ?? base.model,
     metadata: {
       ...(base.metadata ?? {}),
       ...(local.metadata ?? {}),
@@ -99,9 +101,11 @@ function mergeDefaults(base: PromptDefaults, local: PromptDefaults): PromptDefau
 function applyDefaults(asset: ParseResult['asset'], defaults: PromptDefaults): ParseResult['asset'] {
   const hasDefaultMetadata = defaults.metadata && Object.keys(defaults.metadata).length > 0;
   const hasDefaultSystem = !!defaults.sections?.system_instructions;
+  const hasDefaultScalars = defaults.provider !== undefined
+    || defaults.model !== undefined;
 
   // Short-circuit: nothing to merge
-  if (!hasDefaultMetadata && !hasDefaultSystem) {
+  if (!hasDefaultMetadata && !hasDefaultSystem && !hasDefaultScalars) {
     return asset;
   }
 
@@ -121,6 +125,8 @@ function applyDefaults(asset: ParseResult['asset'], defaults: PromptDefaults): P
 
   return {
     ...asset,
+    provider: asset.provider ?? defaults.provider,
+    model: asset.model ?? defaults.model,
     metadata,
     sections,
   };
diff --git a/src/parser/sections.ts b/src/parser/sections.ts
@@ -16,7 +16,7 @@ const SECTION_MAP: Record<string, keyof Sections> = {
  * If no H1 headings are found, the entire body is treated as prompt_template.
  */
 export function extractSections(body: string): Sections {
-  const lines = body.split('\n');
+  const lines = body.split(/\r?\n/);
   const sections: Sections = {};
 
   let currentKey: keyof Sections | null = null;
diff --git a/src/schema/schema.ts b/src/schema/schema.ts
@@ -106,6 +106,8 @@ export const SectionsSchema = z.object({
 // --- Defaults files (folder-level inheritance) ---
 
 export const PromptDefaultsSchema = z.object({
+  provider: z.enum(['openai', 'anthropic', 'google', 'gemini', 'openrouter', 'any']).optional(),
+  model: z.string().optional(),
   metadata: MetadataSchema.optional(),
   sections: z.object({
     system_instructions: z.string().optional(),
diff --git a/tests/sections.test.ts b/tests/sections.test.ts
@@ -87,4 +87,11 @@ Some content.
     expect(sections.system_instructions).toBe('Be helpful.');
     // Unknown heading content is lost (by design — warn in validation)
   });
+
+  it('handles CRLF line endings', () => {
+    const body = '# System instructions\r\n\r\nBe helpful.\r\n\r\n# Prompt template\r\n\r\nHello {{ name }}.\r\n';
+    const sections = extractSections(body);
+    expect(sections.system_instructions).toBe('Be helpful.');
+    expect(sections.prompt_template).toBe('Hello {{ name }}.');
+  });
 });
diff --git a/website/index.html b/website/index.html
@@ -157,7 +157,7 @@ <h3>Composable shared instructions</h3>
           </article>
           <article class="card">
             <h3>Folder-level defaults</h3>
-            <p>Add <code>defaults.md</code> to any prompt folder to define shared <code>metadata</code> and <code># System instructions</code>. Subfolders can override parent defaults, and prompt-local values still take priority.</p>
+            <p>Add <code>defaults.md</code> to any prompt folder to define shared <code>provider</code>, <code>model</code>, <code>metadata</code>, and <code># System instructions</code>. Subfolders can override parent defaults, and prompt-local values still take priority.</p>
           </article>
           <article class="card">
             <h3>Render for any provider</h3>
