Imported from ARUP-CAS/aiscr-webamcr-help (AGENTS.md). Install upstream with npx skills add ARUP-CAS/aiscr-webamcr-help. Copyright stays with the author.

AGENTS.md — Instructions for AI Agents

This file defines the rules, scope and workflows for AI agents (Claude Code, GitHub Copilot, Cursor, etc.) working in this repository.

Rules in this file apply to the entire repository. A nested AGENTS.md in a subdirectory takes precedence for that subtree.

Repository Overview

Repository: ARUP-CAS/aiscr-webamcr-help
Type: Static documentation site (Quarto / R)
Published at: https://amcr-help.aiscr.cz/
Content licence: CC-BY-NC-4.0
Version: v1.1.0 (September 2025)

This repository contains the user documentation for the AMČR system
(Archaeological Map of the Czech Republic), part of AIS CR.

It is a static documentation project — it contains no backend application code.

Repository Orientation (Mandatory First Step)

Before starting any work, agents must gather repository context.

Always read the following files first:

These files contain context accumulated across previous sessions.
Reading them prevents duplicated work and helps maintain continuity between review sessions.

For technical review sessions also read:

.agents/prompts/review_codebase.md

Shared rules (mandatory)

Before substantive edits, read and follow the rules in .agents/rules/:

These rules are the shared source of truth for all agents; local IDE config (e.g. .cursor/) may point to them but must not replace them.

Resolving Inconsistencies

If content in .agents/ contradicts high-level repository rules or governance defined in this document (AGENTS.md), CONTRIBUTING.md, or other authoritative project documentation, agents must treat those higher-level documents as the source of truth.

In such cases agents should:

1. Prefer the high-level governance rules defined in:
   • AGENTS.md
   • CONTRIBUTING.md
   • repository documentation standards
2. Adapt or update affected files in .agents/ to align with those rules.
3. Record the adjustment in the review history (for example review_cache.json or refactoring_backlog.md) when relevant.

This ensures long-running AI review artefacts remain consistent with current repository governance.

Documentation governance

Which file owns what:

• CONTRIBUTING.md — Branch naming, PR process, Quarto/freeze, commit messages, AI-assisted contributing. Canonical for human contributors.
• AGENTS.md — Agent scope, orientation, verification URLs, branch/PR rules for agents, .agents structure, key files. Canonical for AI agents.
• .agents/rules/ — Shared agent rules (no-edit-generated, project-conventions, pre-pr-check, subagents). Single source of truth for those rules; do not duplicate them in full elsewhere — use cross-references.

Avoid duplicating the same rule in multiple files; prefer a short pointer to the canonical file or section.

AI-Generated Content

All artefacts produced by AI agents belong in the .agents/ directory.

Examples include:

• audit reports
• analysis JSON files
• review state updates
• prompt evolution notes

Agent work should be committed to a dedicated branch:

agents/<agent-name>/<topic>

Examples:

agents/claude/review-content-structure
agents/copilot/fix-broken-links

These branches must always target main.

AI-generated artefacts must remain clearly separated from documentation content.

Goal

Keep changes small, safe and easy to review, in line with:

• CONTRIBUTING.md
• CI workflows
• Quarto documentation structure

Agents must avoid large unrelated refactors.

Agent Behaviour

Agents must follow these behavioural rules:

1. Always gather context first (see Repository Orientation).
2. Do not repeat work already recorded in .agents/.
3. Prefer small incremental changes over large edits.
4. When identifying issues, record them in:
   • .agents/reports/bugs.md
   • .agents/reports/refactoring_backlog.md
5. If new insights about agent workflows arise, suggest updates to this file.

Recommended Skills

Specialised agent capabilities that may help with repository maintenance.

Skills are optional helpers and should be used when they improve efficiency or quality of work.

• doc — reviewing and editing documentation artefacts, including .qmd files, navigation structure, terminology and content accuracy
• gh-fix-ci — diagnosing and fixing CI failures in GitHub Actions and Quarto build pipelines
• gh-address-comments — incorporating pull request review comments

⚠️ Critical Requirement: Work Against the Documented Live Applications

This repository documents real, live applications.

Documentation changes must always be verified against the current
state of the documented systems.

Never assume the repository content reflects the current application state.

Mandatory Context Sources

Before editing documentation, agents must verify information using
the following sources.

Live Websites

Source Code Repositories

Source code is authoritative for:

• module names
• entity naming
• workflow behaviour

Technical Documentation

This documentation is authoritative for:

• architecture
• configuration
• system behaviour
• data models

Why Verification Is Critical

Documentation must describe how the system actually works today.

Screenshots, terminology and workflows may change over time.

Incorrect documentation can mislead users and create operational problems,
because AMČR has methodological and legal implications for archaeologists.

Specific Instructions

Before editing documentation:

1. Verify the workflow in the live application.
2. Verify terminology against AMČR UI and amcr-info.aiscr.cz.
3. When unsure, verify in source code.
4. Record discrepancies in:

.agents/reports/bugs.md

Scope

In Scope

• .qmd documentation pages
• _quarto.yml
• soucasti.yml
• CSS/SCSS themes
• GitHub workflows
• Quarto extensions
• bibliographic references

Out of Scope

Do not edit:

_freeze/
_site/

These directories contain generated artefacts.

Binary files in:

figs/
fonts/

should not be modified automatically.

Tech Stack

This repository contains:

• Quarto documentation
• R runtime for some documents
• SCSS/CSS themes
• GitHub Actions CI
• GitHub Pages hosting

It does not contain:

• backend code
• databases
• Docker infrastructure
• APIs

Branch and PR Rules

This repository uses a single-branch workflow.

Rules:

• All work targets main
• Never push directly to main
• Always open a Pull Request

Branch naming:

agents/<agent-name>/<topic>
docs/<topic>
fix/<topic>
chore/<topic>

Changes to .agents/ always require human review.

.agents Structure

.agents/
├── README.md
├── rules/
│   ├── no-edit-generated.md
│   ├── project-conventions.md
│   ├── pre-pr-check.md
│   └── subagents.md
├── scripts/
│   └── quarto-render-check.ps1
├── prompts/
│   ├── review_codebase.md
│   └── prompt_evolution/
├── config/
│   ├── review_config.yaml
│   └── review_cache.json
├── analysis/
│   ├── repository_map.json
│   ├── dependency_graph.json
│   ├── cicd_analysis.json
│   └── frontend_analysis.json
└── reports/
    ├── review_reports/
    ├── bugs.md
    └── refactoring_backlog.md

For this documentation repository only:

• analysis/cicd_analysis.json
• analysis/frontend_analysis.json

are typically relevant.

Key Files

Repository Context in AIS CR