Contextual Instructions Reference

HelseCLI enables high-fidelity logic tuning and behavioral customization through a multi-layered system of contextual instructions. This system is essential for enforcing organizational coding standards, providing architectural context, and defining specific technical personas.

Instruction Precedence Hierarchy

HelseCLI aggregates and prioritizes instructions from three distinct levels:

1. Project-Specific Layer (Local)

Instructions localized to the current working directory.

• .helsecli.yaml: Manifest for defining repository-specific rules and parameters under the custom_instructions key.
• AGENTS.md: A dedicated technical context file used to provide deep architectural knowledge and standard operating procedures (SOPs) for the AI assistant.

2. User-Specific Layer (Global)

Instructions persisted within the user's home directory (~/.helsecli_config.json).

• These rules are applied globally to all HelseCLI sessions.
• Recommended for personal developmental preferences (e.g., "Enforce functional programming patterns" or "Prioritize concise responses").

3. Session-Specific Layer (Volatile)

Instructions injected dynamically during an active session via the /init command.

• The system performs a recursive analysis of the project structure to synthesize a localized AGENTS.md context.

Implementation of AGENTS.md

The AGENTS.md file serves as the primary technical context provider for the HelseCLI engine. Recommended content includes:

# Architectural Context: System Alpha
Project Core: Distributed data processing engine utilizing Python 3.11.

## Developmental Standards:
- Mandatory type-hinting for all functional signatures.
- Utilization of `pytest` for all unit and integration validation.
- Documentation compliant with Google Python Style Guides.

## Component Map:
- Orchestration logic: `src/core/assistant.py`.
- Tool interface modules: `src/tools/`.

Upon session initialization, HelseCLI injects this context directly into the system prompt to ensure alignment with project-specific architecture.

Instruction Templates

Architectural Persona

"Assume the role of a Senior Systems Architect. Prioritize security, horizontal scalability, and maintainability. Precede implementation with an architectural assessment of the proposed changes."

TDD (Test-Driven Development) Protocol

"Mandatory Test-Driven Development (TDD) workflow: Synthesize unit tests prior to functional implementation. Definition of task completion requires a successful validation pass within the sandboxed environment."

Documentation Standards

"Enforce comprehensive docstring coverage for all new modules. Utilize descriptive nomenclature for all variables and constants. Maintain a minimum comment-to-code ratio of 1:5."

Parameter Overrides

To execute a session while bypassing global configuration layers, set the following environmental flag: HELSE_IGNORE_GLOBAL_CONFIG=1