Files
2026-09-29 10:04:57 +02:00

14 KiB

name, version, title, type, created, updated, tags, sources
name version title type created updated tags sources
Fiona-Assistant Agent Rules 1.3.2 LLM Agent Rules summary 2025-09-23 2026-09-29
agents
rules
guidelines
llm
ai

Fiona-Assistant LLM Agent Rules

1. Overview

This document defines the rules and guidelines for LLM Agents (including AI assistants, hives, and automated tools) when interacting with the Fiona-Assistant repository.

1.1 Rule References

Refer to rules in this file as project agent rule N.M (e.g. project agent rule 1.1) to differentiate them from rules in other AGENTS.md files (e.g. the llm-wiki template's src/llm-wiki/AGENTS.md).


2. Basic Rules (MANDATORY)

2.1 Testing

  • For testing scripts always run python src/run_tests.py and make sure everything is passing on every loop
  • After Modifying the repo, make sure python src/run_sanity.py --non-interactive passes before finalizing.

2.2 Documentation

  • Before changing any functionality, read SPEC (the project spec sheet) so the change follows the specified requirements and acceptance criteria.
    • When documentation is changed (e.g., SPEC.md, especially the table of contents section), double-check that all references to it are unbroken.
    • Always link via markdownlink for connectivity.
  • Whenever a change alters behavior, adds a feature, or changes a requirement, update SPEC in the same task so the spec stays in sync (adjust section status: planned -> partial -> implemented; use won't do for rejected features).

2.3 Commit

  • NEVER commit without explicit permission!

3. Environment Setup (MANDATORY)

3.1 Always Use Bootstrap for Environment

BEFORE any testing or development work, you MUST load the bootstrap script

Linux / macOS (bash, must be sourced):

# Bare minimum - always run this first
source bootstrap

# For a specific environment name
source bootstrap --env fiona_env

# With Python version
source bootstrap --env <env_name> --python <version>

# With cleanup flag
source bootstrap --env <env_name> -c

Windows (PowerShell, must be dot-sourced). This creates a repo-local venv at .venvs\<name> with the Python launcher. It does not install pyenv.

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
. .\bootstrap.ps1
. .\bootstrap.ps1 --env fiona_env
. .\bootstrap.ps1 --env <env_name> --python <version>
. .\bootstrap.ps1 --env <env_name> -c

Rationale: The bootstrap script sets up the Python virtual environment, installs dependencies, and ensures a consistent development environment. All testing and development MUST happen within this environment.

Violation: Operating outside the bootstrapped environment may lead to dependency conflicts, incorrect Python versions, or missing packages.


4. Python Development Rules

4.1 Load Python TDD Skill for Python Tasks

When modifying or creating Python scripts, the Python TDD Skill MUST be loaded

SKILL: python-tdd
PATH: llm-wiki/utils/skills/python-tdd/SKILL.md
  • Project Rules:
    • Always use the logging module to log things, relevant to the script runtime.
      • Use print only for relevant Human and LLM data that needs reading and further processing.

Required Practices from Python TDD Skill:

  • Strictly follow Test-Driven Development (TDD) - Red-Green-Refactor cycle
  • Use pytest for testing
  • Follow OOP principles and SOLID design patterns
  • Write minimal, maintainable code (KISS, DRY, YAGNI)
  • Use type hints for all public functions
  • Write Google-style or NumPy-style docstrings
  • Use PEP 8 compliance (snake_case, 4-space indents)
  • 100% test coverage for critical paths

Applicability: Any task involving Python code, including:

  • Creating new Python modules
  • Modifying existing Python scripts
  • Debugging Python code
  • Refactoring Python code

Exception: Read-only operations (listing files, viewing code) do not require the TDD skill.


5. Repository Structure Rules

5.1 Respect Directory Boundaries

The repository has the following structure with specific permissions:

fiona-assistant/
├── src/                      # Source code
│   ├── llm-wiki/             # Packaged llm-wiki template (data only)
│   │                         # Structure source of truth:
│   │                         # `src/llm-wiki/wiki/schema.md`
│   ├── fiona/                # Main CLI package
│   ├── librarian/            # Wiki content management
│   ├── mdoctor/              # Markdown diagnosis
│   ├── python_ruff/          # Python code linting
│   ├── wiki/                 # Wiki lifecycle modules (init, update)
│   ├── tests/                # Unit tests
│   ├── run_tests.py          # Test runner
│   ├── run_sanity.py         # Sanity runner (tests + linters)
│   ├── settings_dev.json     # Development settings
│   ├── utils.sh              # Shell utilities
│   └── install_packages.sh   # Dependency installer
│
├── pyproject.toml            # Project configuration
├── bootstrap                 # Environment setup (bash; source it)
├── bootstrap.ps1             # Environment setup (PowerShell; dot-source it)
└── README.md                 # Project documentation

The llm-wiki directory structure is not duplicated here: src/llm-wiki/wiki/schema.md is the final source of truth for the llm-wiki directory structure.

General Rules:

  • /personal/ directories are STRICTLY READ-ONLY - Never create, edit, or delete
  • /raw/ directories are READ-ONLY - Never edit archived source materials
  • /wiki/concepts/ is READ-WRITE - Place synthesized content here
  • /ingest/ is for input processing - Parse files dropped here
  • Always update src/llm-wiki/wiki/index.md when adding new concepts
  • Always append to src/llm-wiki/wiki/log.md for every action

6. Testing Rules

6.1 Testing Requirements

All code changes MUST be tested following TDD principles:

  1. Write failing tests first (Red phase)
  2. Write minimal code to pass (Green phase)
  3. Refactor while keeping tests passing

Test Execution:

# Run all tests
python src/run_tests.py

# Run with pytest directly
python -m pytest

# Run with coverage
python -m pytest --cov=src

# Run specific test file
python -m pytest src/tests/test_md_frontmatter.py -v

Test File Structure:

  • Test files must be named test_*.py or *_test.py
  • Tests must be in a tests/ directory
  • Each module should have its own test file
  • Test functions must start with test_

Coverage Requirement:

  • Aim for 100% coverage on critical code paths
  • Minimum 80% coverage for all production code
  • Use pytest-cov for coverage reporting

7. Code Quality Rules

7.1 Linting and Formatting

Before committing any Python code:

# Lint markdown files
mdoctor chklint src/

# Lint Python files
python-ruff chklint src/

# Or use fiona-assistant CLI
fiona-assistant mdoctor chklint src/
fiona-assistant python-ruff chklint src/

Requirements:

  • All Python code must pass Ruff linting
  • All markdown files must pass PyMarkdown linting
  • No linting errors may be committed to the repository

8. Version Control Rules

8.1 Git Operations

Commit Messages:

  • Use semantic commit format
  • Prefix with type: feat:, fix:, docs:, refactor:, test:, chore:
  • Keep messages concise and descriptive

Examples:

git commit -m "feat: add md_frontmatter module for version control"
git commit -m "fix: handle empty frontmatter delimiters in parser"
git commit -m "test: add TDD tests for name/version extraction"

Required before PR:

  • All tests pass
  • All linting passes
  • Code coverage maintained or improved
  • Documentation updated

9. Workflow Rules

9.1 Development Workflow

Standard Workflow:

  1. Setup Environment (MANDATORY)

    source bootstrap --env <env_name>
    

    On Windows, dot-source the PowerShell script instead:

    . .\bootstrap.ps1 --env <env_name>
    
  2. Load Appropriate Skill (if applicable)

    • Python tasks: Load python-tdd skill
    • Wiki tasks: Load llm-wiki skill
  3. Read the Spec

    • Read SPEC for the feature being changed
    • Confirm the change matches the specified requirements and acceptance criteria
  4. Follow TDD for Code Changes

    • Write tests first
    • Implement minimal code
    • Refactor
  5. Validate

    • Run tests
    • Run linters
  6. Document

    • Update docstrings
    • Update README if needed
    • Update SPEC if the change affects any specified feature or requirement

10. Frontmatter Rules

10.1 MD File Frontmatter

All markdown files in llm-wiki/ MUST have YAML frontmatter with the required name and version fields. All other fields are optional:

---
name: Document Name        # required
version: 1.0.0             # required (bump when editing)
title: Page Title          # optional
created: YYYY-MM-DD        # optional
updated: YYYY-MM-DD        # optional (bump when editing)
type: entity | concept | comparison | query | summary | toc
sources: [raw/articles/source-name.md]  # optional
tags: [from taxonomy]      # optional
# Optional quality signals:
confidence: trusted | high | medium | low | zero
contested: true
contradictions: [other-page-slug]
---

Version Tracking:

  • The version field is used for source control and change detection
  • Always increment version when making significant changes
  • Use semantic versioning (MAJOR.MINOR.PATCH)

This is the single canonical frontmatter schema; wiki/schema.md documents the same schema for the wiki template (see SPEC 4.2.1).


11. Error Handling Rules

11.1 Report, Don't Fail Silently

When errors occur:

  • DO raise appropriate exceptions with clear messages
  • DO validate inputs before processing
  • DON'T silently ignore errors
  • DON'T return None/empty without explanation

12. Communication Rules

12.1 AI/Human Friendly Output

All tool outputs MUST be formatted for easy parsing by both humans and AI.

Requirements:

  • Use consistent indentation (2 or 4 spaces)
  • Use clear section headers
  • Include summaries at the end
  • Use tables for structured data when appropriate

13. Priority Rules

13.1 Task Prioritization

When multiple tasks are possible, prioritize in this order:

  1. User's explicit request (highest priority)
  2. TDD requirements (tests before implementation)
  3. Code quality (linting, formatting)
  4. Documentation (docstrings, README)
  5. Refactoring (improving existing code)
  6. New features (lowest priority)

14. Anti-Patterns

14.1 Things to Never Do

  • Never modify /personal/ or /raw/ directories
  • Never commit code without tests
  • Never commit code that fails linting
  • Never ignore AGENTS.md rules without explicit user override
  • Never assume user intent - always ask for clarification
  • Never make changes without a clear purpose
  • Never leave broken tests in the repository

15. Override Rules

15.1 When Rules Can Be Broken

These rules CAN be overridden by:

  1. Explicit user instruction (e.g., "skip tests this time")
  2. Higher-priority AGENTS.md in a subdirectory
  3. Emergency fixes for critical issues

16. Quick Reference

Task Required Action
Any Python work Load python-tdd skill
Before testing source bootstrap (Windows: . .\bootstrap.ps1)
Changing functionality Read SPEC first
Modifying code Write tests first (TDD)
Before commit Run tests + linters
After behavior change Update SPEC to stay in sync
Wiki changes Update index.md + log.md
Frontmatter Include name, version, title, dates
Errors Raise exceptions, don't fail silently

17. Enforcement

These rules are ENFORCED at the system level and will be checked.

Violations will be:

  1. Reported to the user
  2. Blocked if possible
  3. Logged in llm-wiki/wiki/log.md