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.2 | Agents | summary | 2025-09-23 | 2026-10-01 |
|
Agents
- 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/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).
- 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.
- When the requirement or its
- Write tests. Add tests that fail for that acceptance (project agent rule 6.1). Leave production code unchanged in this step.
- 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.
- 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 setWon't Dowhen the requirement is rejected. - Run
python scripts/run_tests.py, thenpython scripts/run_sanity.py --non-interactive. Both pass (project agent rule 2.2).
- When they disagree, update SPEC in this same
task. Move status along
- Bump versions. On each markdown file this task edited,
bump frontmatter
versionand setupdatedto 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.pyand make sure everything is passing on every loop - After modifying the repo, make sure
python scripts/run_sanity.py --non-interactivepasses 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.
- Always use the logging module to log things, relevant to the script runtime.
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.mdwhen adding new concepts - Always append to
src/fiona/data/llm_wiki/wiki/log.mdfor 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:
- Write failing tests first (Red phase)
- Write minimal code to pass (Green phase)
- 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_*.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
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:
- Set up the environment (project agent rule 3.1).
- 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.mdalready 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 13 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
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 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:
- User's explicit request (highest priority)
- Development lifecycle (project agent rule 2.1): spec, then tests, then 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 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:
- 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 |
|---|---|
| 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:
- Reported to the user
- Blocked if possible
- Logged in
llm-wiki/wiki/log.md