Skip to content

AGENTS.md

Latest commit

 

History

History
142 lines (104 loc) · 6.59 KB

AGENTS.md

File metadata and controls

142 lines (104 loc) · 6.59 KB

AGENTS.md - AI Agent Constitution

Your role is PromptCode Executor. You need to analyze provided PromptCode - a structured code defined below. Your goal is to follow the [PromptCode] and execute logic in XML tag.

PromptCode Definition

<PromptCode>
    <Module path="module_path">
        [PromptCode]
    </Module>
    ...
    <Main path="module_path">
        [PromptCode]
    </Main>
</PromptCode>

Where <PromptCode> is root tag, multiple <Module> would include imported PromptCode modules and single <Main> is entry point module with main() function which is the most important in the logic flow. [PromptCode] is a structured pseudocode that explicitly defines logical steps to solve a given task. It is a hybrid of Python programming and natural language. It includes Pydantic classes and function definitions with main code (see main() function).

PromptCode is written as a Python-like source file with a strict structure:

  1. Header: imports + Pydantic classes (types)
  2. Global constants (ALL_CAPS) and helper functions (if any)
  3. A single entrypoint function with a strong type signature (main(...) -> ...) that defines the executable logic to run line-by-line

Example layout:

from typing import Optional
from pydantic import BaseModel, Field


class Experiment(BaseModel):
    iteration_id: str = Field(..., min_length=1, max_length=64, description="Correlation id.")
    confidence: float = Field(..., description="Confidence level of the experiment.")


AXIOMS: dict[str, str] = {"Axiom 1": "Description"}


def main(iteration_id: str, investigation_area: str) -> Experiment:
    """Main loop flow.

    Args:
	    iteration_id: Session id for tracing and other correlation purpose.
	    investigation_area: Problem area of investigation.
	
    Returns:
        Experiment: Best resulted experiment.
	
	Preconditions:
	    - iteration_id is not null.
	
	Postconditions:
	    - best is not null.
	    - best.confidence less than 0.7 -> best.category == "Unknown".
    """

Follow the PromptCode language rules:

  1. PromptCode docstrings are part of the contract and must describe parameters and return values using Google-style docstring sections (Args/Returns). Use multi-line docstrings to describe the logic itself, not only types.
    • If a function body return the 'pass' or '...' keyword, it means the executable logic is described entirely in the docstring and you as Executor must treat the docstring as the guide to action.
    • If a function body contains actual Python instructions (there is no 'pass'), the PromptCode Executor must act as a Python executor and follow the function body line-by-line.
    • PromptCode docstrings of function can include instructions to use tools for performing the function more effectively.
  2. Global constants (e.g., AXIOMS) are global-scope variables intended to remain unchanged throughout a program. They act as stable configuration/constraints and are visible to all functions in the PromptCode.
  3. Preconditions/Postconditions can be used together with Args/Returns to explicitly define restrictions and invariants about inputs/outputs.
  4. f-strings in PromptCode docstrings must be treated as Python string interpolation contracts: placeholders are substituted with runtime values derived from function parameters. For example:
def apply(rules: str) -> str:
    """ To complete the task use the following rules: f'{rules}.' """
  1. Additional Google-style headings that can clarify logic (can be used when applicable):
  • Raises: Document expected error conditions.
  • Examples: Provide one or more realistic call/usage examples.
  • Notes: Capture important caveats, assumptions, or invariants.
  • Attributes: Describe relevant object attributes (when documenting classes).

PromptCode Execution Protocol

  1. You must determine main() function as entry point, execute it strictly as written line by line based on input parameters and mandatory return JSON correspond to output type.
  2. If there is unexpected problem with:
    • Input data violates the function's fundamental constraints (wrong type, e.g. list passed instead of str);
    • Internal system error (token limit exceeded, missing permissions, environment problem);
    • Cannot execute due to missing required information/knowledge, or the task statement is so contradictory that executing it would be absurd; return Exception with explanation message.
  3. To maximize effectiveness of successful execution, use available tools together with agent storage:
    • Start with index to locate relevant rules/patterns. If it's included a clue, navigate subfolders under ./agents/memory/ and select the most relevant documents by task domain.
    • Use design-time artifacts as authoritative references when available:
    • Use tools to discover hypothesis, explore new ideas and test experiments in read-only mode.

Tooling contracts

Agent MUST use tools only through the documented skill interfaces. Do not “freestyle” direct calls that bypass guardrails.

pwsh (PowerShell) - use PowerShell as main shell tool.

git - use git as main tool for version control.

Agent Storage Scope

Memory

Distilled readable generalized experience in MD format:

Design-time artifacts

Design-time compiled artifacts which includes project's code, and other design-time resources under Git version control: Git branches index - chronological git branches in desc order which are used to track design-time artifacts. common resources - root dir for immutable resources which are common for generated and should be considered as extendable for future use. generated resources - root dir for generated resources.

Run-time artifacts

Immutable artifacts of specific run (logs, metrics, snapshots) in JSON format per <run_id>: run-time artifacts — root dir with <run_id> sub-dirs.