flynn/docs/plans/phase1-pr1-context-level-checklist.md

Phase 1 PR #1 Checklist: Context Levels

Created: 2026-02-12 Owner: Flynn core Status: ready to implement

Goal

Add configurable prompt context levels so Flynn can trade off speed/cost vs depth:

• minimal
• normal (default)
• detailed
• debug

This PR only adds config + prompt assembly behavior. It does not add command routing or runtime switching.

PR Boundary

In scope:

• Schema support for prompt.context_level
• Pass context_level into prompt assembly
• Context-level behavior in assembleSystemPrompt
• Unit tests for parsing and prompt output differences

Out of scope:

• Per-agent overrides
• Slash-command switching (/context ...)
• Adaptive auto-switching by token budget
• Tool-list verbosity tuning inside NativeAgent

File-by-File Diff Plan

1. src/config/schema.ts

• Add enum and default under promptSchema.
• Export type for use by prompt module.

@@
 const promptSchema = z.object({
   search_dirs: z.array(z.string()).default([]),
   extra_sections: z.array(z.object({
     name: z.string(),
     content: z.string(),
   })).default([]),
+  context_level: z.enum(['minimal', 'normal', 'detailed', 'debug']).default('normal'),
 }).default({});
@@
+export type ContextLevel = z.infer<typeof promptSchema.shape.context_level>;
 export type PromptConfig = z.infer<typeof promptSchema>;

2. src/prompt/template.ts

• Accept contextLevel in PromptTemplateConfig.
• Implement level-based assembly behavior:
  • minimal: load SOUL.md + runtime only, skip extra sections
  • normal: current behavior (all templates + runtime)
  • detailed: normal + include extra sections explicitly (same as current, documented)
  • debug: detailed + append loaded file list and directory resolution notes in a debug section

@@
+import type { ContextLevel } from '../config/schema.js';
@@
 export interface PromptTemplateConfig {
   searchDirs: string[];
   extraSections?: Array<{ name: string; content: string }>;
+  contextLevel?: ContextLevel;
 }
@@
-export function assembleSystemPrompt(config: PromptTemplateConfig): PromptTemplateResult {
+export function assembleSystemPrompt(config: PromptTemplateConfig): PromptTemplateResult {
+  const level = config.contextLevel ?? 'normal';
+  const includeAllTemplates = level !== 'minimal';
+  const includeExtraSections = level !== 'minimal';
+  const includeDebugSection = level === 'debug';
   const sections: string[] = [];
   const loadedFiles: string[] = [];
-  for (const { name, section } of PROMPT_FILES) {
+  for (const { name, section } of PROMPT_FILES) {
+    if (!includeAllTemplates && name !== 'SOUL.md') { continue; }
     ...
   }
-  if (config.extraSections) {
+  if (includeExtraSections && config.extraSections) {
     ...
   }
+  if (includeDebugSection) {
+    sections.push(`# Prompt Debug\n\nContext level: ${level}\nLoaded files:\n${loadedFiles.map(f => `- ${f}`).join('\n') || '- none'}`);
+  }
   ...
 }

3. src/daemon/services.ts

• Pass config value through loadSystemPrompt.

@@
   const result = assembleSystemPrompt({
     searchDirs,
     extraSections: config.prompt.extra_sections,
+    contextLevel: config.prompt.context_level,
   });

4. src/prompt/template.test.ts

• Add focused tests for level behavior.

@@
+it('uses normal as default context level', ...)
+it('minimal loads SOUL plus runtime only', ...)
+it('normal keeps current template behavior', ...)
+it('detailed includes extra sections', ...)
+it('debug appends prompt debug section with loaded files', ...)
+it('minimal skips extra sections', ...)

5. config/default.yaml (optional but recommended)

• Add commented prompt block to advertise the new setting.

@@
+# prompt:
+#   search_dirs: []
+#   extra_sections: []
+#   context_level: normal  # minimal | normal | detailed | debug

Implementation Steps

1. Add schema enum + exported type in src/config/schema.ts.
2. Update prompt template types and logic in src/prompt/template.ts.
3. Thread config value in src/daemon/services.ts.
4. Add/adjust tests in src/prompt/template.test.ts.
5. Optionally document setting in config/default.yaml.
6. Run validation commands and fix any regressions.

Validation Commands

Run in this order:

pnpm typecheck
pnpm test:run src/prompt/template.test.ts
pnpm test:run
pnpm lint
pnpm build

Acceptance Criteria

• Config parses with no prompt.context_level set (defaults to normal).
• Invalid context levels are rejected by schema.
• minimal omits AGENTS/IDENTITY/USER/TOOLS sections.
• normal output matches current behavior.
• detailed keeps full prompt and extra sections.
• debug adds an explicit debug section with loaded file paths.
• Existing prompt tests continue to pass.

Risk Notes

• Main risk: prompt regressions from changed assembly order.
• Mitigation: keep normal behavior byte-close to current output and pin tests.

Suggested Commit Message

feat(prompt): add configurable context levels for system prompt assembly

Follow-up PRs

1. Add runtime/session override (/context minimal|normal|detailed|debug).
2. Extend levels to tool-list verbosity and memory injection depth.
3. Add per-agent context_level override in agent_configs.