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 |
|
Fiona-Assistant LLM Agent Rules
- 1. Overview
- 2. Basic Rules (MANDATORY)
- 3. Environment Setup (MANDATORY)
- 4. Python Development Rules
- 5. Repository Structure Rules
- 6. Testing Rules
- 7. Code Quality Rules
- 8. Version Control Rules
- 9. Workflow Rules
- 10. Frontmatter Rules
- 11. Error Handling Rules
- 12. Communication Rules
- 13. Priority Rules
- 14. Anti-Patterns
- 15. Override Rules
- 16. Quick Reference
- 17. Enforcement
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.pyand make sure everything is passing on every loop - After Modifying the repo, make sure
python src/run_sanity.py --non-interactivepasses 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.
- When documentation is changed (e.g.,
- 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; usewon't dofor 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.
- Always use the logging module to log things, relevant to the script runtime.
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.mdwhen adding new concepts - Always append to
src/llm-wiki/wiki/log.mdfor every action
6. Testing Rules
6.1 Testing Requirements
All code changes MUST be tested following TDD principles:
- Write failing tests first (Red phase)
- Write minimal code to pass (Green phase)
- 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_*.pyor*_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-covfor 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:
-
Setup Environment (MANDATORY)
source bootstrap --env <env_name>On Windows, dot-source the PowerShell script instead:
. .\bootstrap.ps1 --env <env_name> -
Load Appropriate Skill (if applicable)
- Python tasks: Load
python-tddskill - Wiki tasks: Load
llm-wikiskill
- Python tasks: Load
-
Read the Spec
- Read SPEC for the feature being changed
- Confirm the change matches the specified requirements and acceptance criteria
-
Follow TDD for Code Changes
- Write tests first
- Implement minimal code
- Refactor
-
Validate
- Run tests
- Run linters
-
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
versionfield 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:
- User's explicit request (highest priority)
- TDD requirements (tests before implementation)
- Code quality (linting, formatting)
- Documentation (docstrings, README)
- Refactoring (improving existing code)
- 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:
- Explicit user instruction (e.g., "skip tests this time")
- Higher-priority AGENTS.md in a subdirectory
- 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:
- Reported to the user
- Blocked if possible
- Logged in
llm-wiki/wiki/log.md