Always include user instruction in every run

[oshorefueled]

Centralise Evaluation Instructions in Directive

Summary

Moves evaluation instructions from individual rule presets into a centralised directive, reducing duplication and simplifying prompt maintenance.

Problem

The previous approach had evaluation instructions duplicated across multiple files:

• Each bundled preset (ai-pattern.md, pseudo-advice.md, repetition.md) contained its own ## INSTRUCTION section
• The built-in directive was verbose with 13+ instruction points
• This caused token waste and made updates harder (changes needed in multiple places)

Solution

Centralised Directive — Rewrites the directive with a structured Role/Task/Instructions format that all rules share.

Simplified Presets — Removes redundant ## INSTRUCTION sections from bundled presets. Rules now focus only on defining criteria.

Style Guide Always Runs — Changes the style guide evaluation from fallback-only to always running alongside matched rules.

Changes

Area	Files Changed
Directive	Rewrote with Role/Task/Instructions structure
Bundled Presets	Removed INSTRUCTION sections from 3 preset files
Orchestrator	Style guide now runs alongside rules (not fallback-only)
Tests	Fixed zero-config test expectation for empty runRules array
Cleanup	Removed obsolete AGENTS.md architectural document

Breaking Changes

None. Output format remains backward compatible.

Summary by CodeRabbit

Release Notes

• Configuration: Shifted from style guides to user instructions; init command now generates VECTORLINT.md as the primary configuration file
• Evaluation: Restructured evaluation system to integrate user instructions throughout processing
• Presets: Simplified preset configurations by removing procedural steps and adopting a cleaner criteria-based format
• Documentation: Updated guides with current workflow information

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR systematically replaces the style-guide system with a user-instruction system throughout the codebase. It removes zero-config behavior, eliminates the style-guide-loader module, creates a new user-instruction-loader module, renames related constants, and updates all CLI commands, orchestration logic, and tests to reference the new user-instruction paradigm. Preset files are simplified by removing procedural INSTRUCTION blocks.

Changes

Cohort / File(s)	Summary
Preset INSTRUCTION block removals presets/VectorLint/ai-pattern.md, presets/VectorLint/pseudo-advice.md, presets/VectorLint/repetition.md	Removed procedural INSTRUCTION blocks; repetition.md restructured to shift from procedural steps to criteria-driven evaluation with explicit examples and exceptions.
Config constants and loader refactoring src/config/constants.ts, src/boundaries/config-loader.ts	Renamed STYLE_GUIDE_FILENAME → USER_INSTRUCTION_FILENAME and STYLE_GUIDE_TOKEN_WARNING_THRESHOLD → USER_INSTRUCTION_TOKEN_WARNING_THRESHOLD; removed ZERO_CONFIG_PACK_NAME and ZERO_CONFIG_PROMPT_ID; updated config-loader to use new constant and set runRules to empty list for zero-config.
Module replacement src/boundaries/style-guide-loader.ts, src/boundaries/user-instruction-loader.ts	Removed entire style-guide-loader.ts module; created new user-instruction-loader.ts with UserInstructionResult interface, estimateTokens(), and loadUserInstructions() function mirroring prior style-guide functionality.
CLI command updates src/cli/commands.ts, src/cli/init-command.ts	Replaced style-guide loading with user-instruction loading; removed createStyleGuidePrompt() helper and zero-config auto-generation; updated init command to create/reference USER_INSTRUCTION_FILENAME; adjusted prompt construction and logging.
Orchestration and types src/cli/orchestrator.ts, src/cli/types.ts	Added userInstructionContent optional property to EvaluationOptions; implemented user-instruction injection as a prompt entry with empty pack ('') when content provided; added pack filtering to treat empty-pack prompts as always active.
Request builder src/providers/request-builder.ts	Renamed private member from styleGuide to userInstructions; reordered prompt assembly to prepend directive and user-instructions sections before body (previously appended style-guide).
Directive and prompt structure src/prompts/directive-loader.ts	Updated default directive content to use Role/Task structure and new evaluation format; removed step-by-step reporting requirements and CRITICAL RULES block.
Test updates tests/style-guide/zero-config.test.ts, tests/config-loader-error.test.ts, tests/request-builder.test.ts, tests/style-guide/init-command.test.ts	Replaced STYLE_GUIDE_FILENAME with USER_INSTRUCTION_FILENAME across all test files; updated assertions to expect empty runRules for zero-config; adjusted directive test expectations to reflect prepend order; updated test content headers and file operations.
Documentation CLAUDE.md	Added sections on chunking, scoring, presets, and zero-config workflow; added Gemini provider, removed Perplexity; updated init flow documentation and bundled presets guidance; removed legacy directory structure references.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• feat: add zero-config style guide support with VECTORLINT.md #51: Directly reverses and renames the zero-config style-guide work—modifies the same core files (style-guide loader, config-loader, constants, request-builder, CLI) but removes/renames STYLE_GUIDE features into USER_INSTRUCTION equivalents.
• feat: implement bundled rule packs (presets) #32: Modifies the same preset rule files (ai-pattern.md, pseudo-advice.md, repetition.md) that this PR updates, directly related to preset content changes.
• docs: update documentation to reflect optional RulesPath #48: Modifies init-command.ts initialization messaging and next-step output wording alongside other architectural changes.

Suggested reviewers

• ayo6706

Poem

🐰 A rabbit hopped through the code with glee,
Swapped style guides for instructions, wild and free!
Zero-config gone, the paths now clear,
New user-prompts shall guide us here! 🎯

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly reflects the main objective: the PR centralizes and always includes user instructions in evaluation runs, replacing the previous fallback-only style guide model.
Docstring Coverage	✅ Passed	Docstring coverage is 85.71% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch simple_zeroconfig

---

No actionable comments were generated in the recent review. 🎉

🧹 Recent nitpick comments

tests/request-builder.test.ts (1)

4-9: Consider adding a test case for the userInstructions parameter.

DefaultRequestBuilder now accepts a second userInstructions argument that is also prepended (after the directive, before the body). This file has no coverage for that path. A quick additional case would lock in the ordering contract:

it('prepends both directive and user instructions before body', () => {
  const b = new DefaultRequestBuilder('DIR', 'USR');
  const out = b.buildPromptBodyForStructured('P');
  expect(out).toBe('DIR\n\nUSR\n\nP');
});

Tip

Issue Planner is now in beta. Read the docs and try it out! Share your feedback on Discord.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

tests/style-guide/zero-config.test.ts (1)

6-37: ⚠️ Potential issue | 🟠 Major

Fix zero-config test: STYLE_GUIDE_FILENAME is removed (runtime failure).

STYLE_GUIDE_FILENAME is no longer exported, so it’s undefined at runtime and causes the observed “path argument must be a string” failures. Switch to USER_INSTRUCTION_FILENAME in the import and usage.

🛠️ Suggested fix

-import { DEFAULT_CONFIG_FILENAME, STYLE_GUIDE_FILENAME } from '../../src/config/constants';
+import { DEFAULT_CONFIG_FILENAME, USER_INSTRUCTION_FILENAME } from '../../src/config/constants';
@@
-        // Create only the style guide
-        writeFileSync(path.join(tempDir, STYLE_GUIDE_FILENAME), '# My Style Guide');
+        // Create only the user instructions
+        writeFileSync(path.join(tempDir, USER_INSTRUCTION_FILENAME), '# My Instructions');
@@
-        writeFileSync(path.join(tempDir, STYLE_GUIDE_FILENAME), '# My Style Guide');
+        writeFileSync(path.join(tempDir, USER_INSTRUCTION_FILENAME), '# My Instructions');

🧹 Nitpick comments (4)

src/cli/orchestrator.ts (2)

805-817: Consider scoping “always-run” to the user-instruction prompt only.

Right now any prompt with pack === '' bypasses RunRules. If the intent is to always run only VECTORLINT.md, consider narrowing the condition to avoid future empty-pack prompts unintentionally running for every file.

♻️ Possible tightening

-      if (p.pack === '') return true;
+      if (p.pack === '' && p.filename === USER_INSTRUCTION_FILENAME) return true;

---

825-840: Align comment with behavior (user instruction runs whenever provided).

The code injects the prompt whenever userInstructionContent is set, not only when no rules match. Update the comment (or add a guard) to reflect the actual behavior.

📝 Comment tweak

-  // If no rules matched but VECTORLINT.md exists, run an evaluation using it.
-  // The LLM will use the VECTORLINT.md content from the system prompt.
+  // Run user-instruction evaluation alongside matched rules when VECTORLINT.md is provided.
+  // The LLM uses the VECTORLINT.md content from the system prompt.

src/boundaries/user-instruction-loader.ts (2)

1-61: Indentation uses 4 spaces instead of 2.

The coding guidelines specify 2-space indentation, but this file uses 4-space indentation throughout. As per coding guidelines: "Use 2-space indentation; avoid trailing whitespace".

🔧 Suggested fix to use 2-space indentation

 export interface UserInstructionResult {
-    content: string | null;
-    tokenEstimate: number;
-    path: string | null;
+  content: string | null;
+  tokenEstimate: number;
+  path: string | null;
 }

Apply similar 4→2 space changes throughout the file.

---

15-17: Defensive null check is redundant given the type signature.

The function signature declares text: string, but the implementation uses text?.length ?? 0 which guards against null/undefined. In strict TypeScript, a string parameter cannot be null or undefined. Consider either:

1. Removing the defensive check since the type guarantees a string
2. Changing the signature to text: string | null | undefined if null inputs are expected

Option 1: Simplify to match type signature

 export function estimateTokens(text: string): number {
-    return Math.ceil((text?.length ?? 0) / 4);
+  return Math.ceil(text.length / 4);
 }

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@tests/request-builder.test.ts`:
- Around line 5-9: The test description is inaccurate:
DefaultRequestBuilder.buildPromptBodyForStructured actually prepends the
directive before the structured body, so change the test title to reflect that
behavior (e.g., "prepends directive to structured prompts without extra builder
text") and leave the assertion expect(out).toBe('DIR\n\nP') unchanged; update
only the string description in the it(...) call.

🧹 Nitpick comments (2)

tests/style-guide/zero-config.test.ts (1)

21-23: Stale comment refers to "style guide" instead of "user instruction".

The comment on line 22 still says "Create only the style guide" but the file being created is now the user instruction file (USER_INSTRUCTION_FILENAME). Consider updating for consistency:

-        // Create only the style guide
+        // Create only the user instruction file

tests/style-guide/init-command.test.ts (1)

74-76: Stale comment refers to "style guide" instead of "user instruction".

-        // Create a pre-existing style guide
+        // Create a pre-existing user instruction file