feat: add prompt classification and rewriting pipeline

[avoidwork]

Description

Adds a pre-processing pipeline that classifies user prompts by intent, domain, and complexity, then rewrites them into optimized format before reaching the React agent graph. Includes full implementation, config schema support, unit tests, and OpenSpec design artifacts.

Type of Change

• Bugfix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactor (no functional changes)
• Performance improvement
• CI / build / tooling

Testing

• Unit tests added in tests/unit/promptPipeline.test.js (392 lines) covering all pipeline categories, classification logic, and rewriting behavior.
• Tests verify intent detection, domain routing, complexity scoring, and prompt optimization.

Coverage

• Line coverage maintained

Checklist

• npm run lint passes
• Tests pass with maintained line coverage
• No forbidden patterns used
• Conventional Commit style applied

[avoidwork]

Audit Report: PR #475 vs Issue #467

1. Original Issue Requirements

#	Requirement	Status	Evidence
1	Add pre-processing pipeline that classifies user prompts (intent, domain, complexity)	✅ Delivered	src/agent/promptPipeline/index.js:13 — classifyPrompt() returns { intent, domain, complexity }
2	Rewrite prompts into structured, optimized format	✅ Delivered	src/agent/promptPipeline/index.js:51 — rewritePrompt() returns optimized prompt string
3	Two-stage LLM pipeline: Classify → Rewrite	✅ Delivered	src/agent/promptPipeline/index.js:82-93 — processPrompt() calls classifyPrompt() then rewritePrompt() sequentially
4	Pipeline sits between user input and main agent graph as transparent pre-processing step	✅ Delivered	src/agent/react.js:161-171 — intercepts in callReactAgent() before new HumanMessage(processedMessage) at line 173
5	Composable module toggleable via configuration	✅ Delivered	src/config/schemas.js:192-196 — agent.promptRewrite.enabled (default: false); src/agent/react.js:163 — gated behind config check

2. Spec Requirements

Requirement: Pipeline classifies user prompts into structured metadata

Scenario	Status	Evidence
Valid prompt classification	✅	tests/unit/promptPipeline.test.js:245-252 — tests valid JSON response parsing
Question prompt classification	✅	tests/unit/promptPipeline.test.js:274-280 — tests markdown code block handling with question intent
Creative prompt classification	✅	tests/unit/promptPipeline.test.js:282-288 — tests creative/writing/moderate classification
Classification error fallback	✅	tests/unit/promptPipeline.test.js:254-258 — tests LLM failure returns DEFAULT_METADATA; tests/unit/promptPipeline.test.js:260-264 — tests invalid JSON returns defaults; tests/unit/promptPipeline.test.js:266-272 — tests invalid categories returns defaults

Requirement: Pipeline rewrites user prompts into optimized format

Scenario	Status	Evidence
Valid prompt rewriting	✅	tests/unit/promptPipeline.test.js:292-301 — tests rewritten prompt returned correctly
Rewriting preserves original intent	✅	src/agent/promptPipeline/prompts.js:75 — prompt template instructs "Preserve the original intent"; tests/unit/promptPipeline.test.js:323-331 — tests string content passthrough
Rewriting error fallback	✅	tests/unit/promptPipeline.test.js:303-311 — tests LLM failure returns original prompt

Requirement: Pipeline integrates into agent flow before message construction

Scenario	Status	Evidence
Pipeline executes before HumanMessage construction	✅	src/agent/react.js:161-171 — processPrompt() called at line 165, result assigned to processedMessage at line 166, then new HumanMessage(processedMessage) at line 173
Agent graph receives same message format	✅	Line 173 — new HumanMessage(processedMessage) — same HumanMessage constructor, same structure, only content differs

Requirement: Pipeline is configurable and toggleable

Scenario	Status	Evidence
Pipeline disabled by default	✅	src/config/schemas.js:194 — enabled: z.boolean().default(false); src/config/schemas.js:196 — .default({ enabled: false })
Pipeline enabled via config	✅	src/agent/react.js:163 — if (config?.agent?.promptRewrite?.enabled && agent?._model) — executes when enabled
Pipeline disabled does not affect agent flow	✅	src/agent/react.js:162 — let processedMessage = message; — when disabled, original message passes through unchanged

Requirement: Pipeline modules are composable and testable

Scenario	Status	Evidence
Classification function independently testable	✅	tests/unit/promptPipeline.test.js:244-289 — classifyPrompt() tested in isolation with mock model
Rewriting function independently testable	✅	tests/unit/promptPipeline.test.js:291-332 — rewritePrompt() tested in isolation with mock model
Prompt templates are configurable	✅	src/agent/promptPipeline/prompts.js — templates are separate functions (createClassificationPrompt, createRewritingPrompt) that can be modified without changing pipeline logic

3. Audit Findings from Issue #467

Finding	Status	Evidence
callReactAgent() is the integration point	✅	src/agent/react.js:158 — pipeline intercepts at line 161, before HumanMessage construction at line 173
Configuration gate (config.agent.promptRewrite.enabled)	✅	src/config/schemas.js:192-196 — schema defined; src/agent/react.js:163 — gate applied
No existing prompt preprocessing (greenfield)	✅	Confirmed — no prior preprocessing existed; this is a new module

4. Code Quality Checks

Check	Status	Evidence
JSDoc comments on public APIs	✅	All three functions (classifyPrompt, rewritePrompt, processPrompt) have @param and @returns
Error handling with safe defaults	✅	Classification returns DEFAULT_METADATA on failure; rewriting returns original prompt on failure
Cascading failure handling	✅	tests/unit/promptPipeline.test.js:347-361 — tests classification failure + successful rewrite
Tests mock LLM calls	✅	All tests use createMockModel, createMockModelReject, createMockModelSequence — no real API calls
Tests pass	✅	1248 pass, 0 fail
Lint passes	✅	oxlint and oxfmt clean

5. Gaps / Notes

Item	Status	Notes
Task 5.3: Custom prompt templates via config	⚠️ Deferred	Per design doc: "Should classification and rewriting prompt templates be stored in config.yaml or as separate files? (Current design: separate file prompts.js for maintainability)" — intentionally deferred
TUI-specific integration	⚠️ Out of scope	Issue explicitly states "TUI-specific integration or UI feedback during classification/rewriting" is a non-goal
Telemetry/metrics for pipeline usage	⚠️ Out of scope	Design doc notes: "Out of scope for v1, but should be considered for future iterations"

6. Verdict

✅ Issue #467 is fully delivered.

All requirements from the original issue are implemented. All spec requirements are met with corresponding tests. The pipeline is:

• Two-stage (classify → rewrite) as specified
• Transparent (same HumanMessage format, gated by config)
• Fail-safe (defaults on classification failure, original prompt on rewriting failure)
• Composable (separate functions, separate files for templates and categories)
• Testable (392 lines of unit tests, all mocking LLM calls)

The only deferred item (custom prompt templates via config) was intentionally excluded per the design doc's decision to keep templates in prompts.js for maintainability.

Fixes #467

[avoidwork]

Update: External Prompt Templates (Task 5.3)

Implemented external prompt templates loaded by intent classification.

Changes

• Created intent-specific rewrite templates in ./prompts/:

  • rewrite-question.md — Guidelines for question intent
  • rewrite-task.md — Guidelines for task intent
  • rewrite-creative.md — Guidelines for creative intent
  • rewrite-analysis.md — Guidelines for analysis intent
  • rewrite-other.md — Guidelines for other intent

• Updated prompts.js to:

  • Load external templates from ./prompts/ based on classification intent
  • Replace placeholders ({{userPrompt}}, {{intent}}, {{domain}}, {{complexity}}) with actual values
  • Fall back to rewrite-other.md for unknown intents
  • Fall back to inline default template if external files are missing

• Added tests for:

  • Loading intent-specific templates for each category
  • Placeholder replacement with metadata values
  • Fallback behavior for unknown intents

Template Structure

Each template uses {{placeholder}} syntax:

**Original prompt:** "{{userPrompt}}"
**Classification metadata:**
- Intent: {{intent}}
- Domain: {{domain}}
- Complexity: {{complexity}}

This allows templates to be edited independently without code changes.

Files Changed

• ./prompts/rewrite-question.md (new)
• ./prompts/rewrite-task.md (new)
• ./prompts/rewrite-creative.md (new)
• ./prompts/rewrite-analysis.md (new)
• ./prompts/rewrite-other.md (new)
• src/agent/promptPipeline/prompts.js (updated)
• tests/unit/promptPipeline.test.js (updated)
• openspec/changes/prompt-classification-rewriting-pipeline/tasks.md (updated)