Files
fiona-assistant/AGENTS.md
T
2026-10-06 11:27:26 +02:00

18 KiB

name, version, title, type, created, updated, tags, sources
name version title type created updated tags sources
Fiona-Assistant Development Agent Rules 1.9.3 Agents summary 2025-09-23 2026-10-06
agents
rules
guidelines
llm
ai

Agents

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/fiona/data/llm_wiki/AGENTS.md).


2. Basic Rules (MANDATORY)

2.1 Development Lifecycle

Every change that alters behavior, adds a feature, or changes a requirement follows these five steps, in order. Finish a step before starting the next. A read-only question skips this lifecycle.

Before step 2, load the environment (project agent rule 3.1).

  1. Write or check the spec. Read SPEC for the area this task will change.
    • When the requirement or its *acceptance* is missing, write both in SPEC before any test or code. Follow SPEC 1.1 and set the section status.
    • When the requirement exists, confirm the task matches that text. That text is the behavior to build.
  2. Write tests. Add tests that fail for that acceptance (project agent rule 6.1). Leave production code unchanged in this step.
  3. Implement, TDD style. Load the python-tdd skill (project agent rule 4.1).
    • Red: run the new tests and confirm they fail.
    • Green: write the smallest change that makes them pass.
    • Refactor while those tests stay green.
  4. Verify the spec. Re-read the requirement and each acceptance this task touched. The code and the tests satisfy that text.
    • When they disagree, update SPEC in this same task. Move status along Planned -> Partially Implemented -> Implemented, or set Won't Do when the requirement is rejected.
    • Run python scripts/run_tests.py, then python scripts/run_sanity.py --non-interactive. Both pass (project agent rule 2.2).
  5. Bump versions. On each markdown file this task edited, bump frontmatter version and set updated to the edit date (project agent rule 10.1).
    • Semver: patch for a clarification, minor for a new rule or requirement, major for a breaking contract change.
    • Bump SPEC when step 1 or step 4 changed it.
    • Python and shell files have no version tag yet (SPEC 7.3.2.1). Leave them untagged.

A documentation edit that does not change product behavior still bumps versions (step 5). It skips the test and implementation steps.

2.2 Testing

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

2.3 Documentation

  • Product behavior is specified in SPEC. The order for reading it, writing it, and checking it after the code is project agent rule 2.1.
  • When documentation changes (for example SPEC, especially the table of contents), confirm every reference to it still resolves.
  • Always link with a markdown link.

2.4 Commit

  • NEVER commit without explicit permission!
  • This rule covers this repository only. A deployed wiki commits after each ingest cycle and housekeeping pass (SPEC 3.3.3).

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

# This checkout as a normal package (not editable)
source bootstrap --local

# Current user, no virtual environment
source bootstrap --local --no-env

Windows (PowerShell). A virtual-environment install must be dot-sourced. This creates a repo-local venv at .venvs\<name> with the Python launcher. It does not install pyenv. --no-env skips that venv and may be executed with -File. --local installs this repository with pip install . (not editable, no dev extra). --no-env installs with pip install --user, so fiona-assistant runs without activating an environment. The two flags combine.

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
. .\bootstrap.ps1 --local
powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1 --local --no-env

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: src/fiona/data/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:

  • Step 3 of project agent rule 2.1 is this cycle. The spec and the failing tests already exist before implementation starts.
  • 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/fiona/                # The only installable package
│   ├── __main__.py           # CLI entry point
│   ├── librarian/            # Wiki content management
│   ├── mdoctor/              # Markdown diagnosis
│   ├── customlinter/         # Frontmatter, markdown, Python, JSON linters
│   ├── python_ruff/          # Ruff wrapper
│   ├── gittool/              # Git operations
│   ├── sanity_runner/        # Shared sanity engine
│   ├── wiki/                 # Wiki lifecycle (init, update, sanity, graph)
│   ├── data/llm_wiki/        # Packaged template (data only)
│   ├── run_tests.py          # Test runner module
│   └── run_sanity.py         # Sanity runner module
├── tests/                    # Unit tests (not installed)
├── scripts/                  # Repo tooling, not package source
│   ├── run_tests.py          # Launcher for fiona.run_tests
│   ├── run_sanity.py         # Launcher for fiona.run_sanity
│   ├── 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/fiona/data/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/fiona/data/llm_wiki/wiki/index.md when adding new concepts
  • Always append to src/fiona/data/llm_wiki/wiki/log.md for every action

6. Testing Rules

6.1 Testing Requirements

Steps 2 and 3 of project agent rule 2.1. 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 scripts/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 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

The development lifecycle is project agent rule 2.1. Do those five steps in order: write or check the spec, write tests, implement TDD-style, verify the spec, bump versions.

Before step 2 of that lifecycle:

  1. Set up the environment (project agent rule 3.1).
  2. Load the skill when the task needs one (project agent rule 4.1). Python tasks load the python-tdd skill. Wiki tasks load the Fiona skill unless src/fiona/data/llm_wiki/AGENTS.md already loaded it.

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. Every page under wiki/ also requires the quality signals confidence, llm, contested, and contradictions. How to set them is section 15 of the Fiona skill. All other fields are optional. fmlint enforces name and version only.

---
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
# quality signals (required on pages under wiki/):
confidence: trusted | high | medium | low | zero
llm:
  - model: none            # required; model that last edited the page
  - reasoning: high        # when the model reports a level
contested: true
contradictions: [other-page-slug]
# written by wiki ingest (SPEC 7.1.5), optional:
status: raw | refined
source_meta: {author: Name}   # metadata read from the source
ingest:                       # provenance; every key always present
  origin: https://host/path   # URL or file path of the source
  origin_kind: url | file
  final_url: null             # URL after redirects
  fetched: YYYY-MM-DDTHH:MM:SSZ
  media_type: text/html
  size_bytes: 0
  sha256: <64 lowercase hex>  # of the raw copy; never hand-edited
  raw_reused: false
  converter: html             # converter name, or agent
  conversion: complete | partial
  warnings: []
  tool: fiona-assistant <version>
---

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 6.2).


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. Development lifecycle (project agent rule 2.1): spec, then tests, then 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 write production code before the spec states the requirement and a failing test exists (project agent rule 2.1)
  • 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
Development project agent rule 2.1, in order
Any Python work Load the python-tdd skill
Before testing source bootstrap (Windows: . .\bootstrap.ps1)
Local install, no venv bootstrap --local --no-env
Step 1 Write or check SPEC
Step 2 and 3 Failing tests, then the smallest change
Step 4 Re-read the spec; tests and sanity pass
Step 5 Bump version and updated on edited markdown
Before commit Run tests + linters
Wiki changes Load the Fiona skill; update index.md + log.md
Frontmatter name and version on every file; on wiki/ pages also confidence, llm, contested, contradictions
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