docs(plans): add openclaw analysis and rollout checklists

2026-02-12 22:47:28 -08:00
parent 6e8984f788
commit 3472a0b926
13 changed files with 2090 additions and 0 deletions
@@ -0,0 +1,179 @@
+# 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`.