tests — prompts

tests — prompts

This document describes the tests/prompts/workflow-rules.test.ts module, which is responsible for verifying the integrity and content of the workflow rules prompt block used by the AI agent.

Module: tests/prompts/workflow-rules.test.ts

Purpose

The primary purpose of workflow-rules.test.ts is to ensure that the getWorkflowRulesBlock() function consistently generates a prompt block that meets the strict structural and semantic requirements of the AI agent. This block contains critical instructions and protocols that guide the agent's planning, execution, and self-correction processes.

By thoroughly testing this output, we guarantee that the agent receives the expected directives, preventing misinterpretations or failures in its operational workflow.

Module Under Test: getWorkflowRulesBlock()

This test module focuses exclusively on the getWorkflowRulesBlock() function, imported from ../../src/prompts/workflow-rules.js.

getWorkflowRulesBlock() is a pure function designed to return a string containing a set of predefined rules and guidelines. These rules are injected directly into the agent's prompt, serving as its foundational operating instructions. Because it's a pure function, it requires no external dependencies, file system access, or mocks, making its testing straightforward and reliable.

Test Coverage

The tests in this module are categorized to cover both the basic functionality and the critical content requirements of the workflow rules block.

1. Basic Functionality Checks

These tests ensure the getWorkflowRulesBlock() function behaves as expected at a fundamental level:

• Non-empty String: Verifies that the function returns a valid, non-empty string.
• No Throws: Confirms that calling the function does not result in any unhandled exceptions.
• Idempotency: Ensures that multiple calls to getWorkflowRulesBlock() return the exact same string, confirming its deterministic nature and immutability of the generated block.

2. Structural Integrity: Required Sections

The AI agent relies on specific headings within the workflow rules block to parse and understand different categories of instructions. These tests assert the presence of all six mandatory sections:

• When to Plan
• Auto-Correction
• Verification Contract
• Uncertainty Protocol
• Elegance Gate
• Subagent

The absence of any of these sections would likely lead to the agent failing to correctly apply its operational protocols.

3. Semantic Integrity: Concrete Keywords

Beyond just the section headings, the agent is trained to recognize and act upon specific keywords and patterns within the workflow rules. These tests ensure that these crucial semantic markers are present:

• 3+ action verb trigger: A key indicator for the agent to initiate planning when multiple actions are required.
• npx tsc --noEmit: The specific command used for TypeScript verification, ensuring the agent uses the correct tool for type checking.
• task_verify: References the tool the agent should use for task verification.
• Assumption: pattern: The expected prefix for assumptions made under the "Uncertainty Protocol."
• lessons_add: References the tool for adding new lessons to the agent's knowledge base, crucial for its self-improvement loop.
• lessons_search: References the tool for searching existing lessons, enabling pre-task lookup and learning from past experiences.

Importance to Agent Behavior

This test module is critical for the stability and predictability of the AI agent. The getWorkflowRulesBlock() function generates a core part of the agent's system prompt. Any deviation from the expected structure or content, especially regarding the concrete keywords, could lead to:

• Incorrect Planning: Agent fails to plan effectively or misinterprets planning triggers.
• Failed Verification: Agent uses the wrong tools or methods for verifying its work.
• Suboptimal Self-Correction: Agent cannot properly identify or learn from uncertainties and failures.
• Inconsistent Tool Usage: Agent fails to use task_verify, lessons_add, or lessons_search as intended.

By maintaining these tests, we ensure that changes to getWorkflowRulesBlock() do not inadvertently break the agent's fundamental operational logic.

Contribution Guidelines

When modifying src/prompts/workflow-rules.js or the content generated by getWorkflowRulesBlock():

1. Run Existing Tests: Always run npm test tests/prompts/workflow-rules.test.ts to ensure no regressions are introduced.
2. Update Tests for Changes: If you intentionally change a section heading or a concrete keyword that the agent relies on, you must update the corresponding test cases in workflow-rules.test.ts to reflect the new expected output.
3. Add New Tests for New Requirements: If new sections or critical keywords are added to the workflow rules, create new it() blocks to assert their presence and correct format.
4. Consult Agent Behavior: Before making significant changes, consider the impact on the agent's training and fine-tuning. Changes to these core rules might require retraining or careful adjustment of the agent's prompt engineering.