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.

```diff
@@
 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

```diff
@@
+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`.

```diff
@@
   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.

```diff
@@
+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.

```diff
@@
+# 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:

```bash
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`.