project-template/AGENTS.md

AGENTS.md

Guidance for Claude Code working in this repository. See also ai-assistance-guide.

Overview

${REPO_NAME} — ${REPO_DESCRIPTION}

First-Time Setup

This repository is a Forgejo template. Most customization points are auto-resolved by Forgejo's template variable expansion when a new repo is created. The remaining manual steps are:

1. Set baseUrl in docs/quartz.config.ts — this is the hosted docs domain, not the repo URL. localhost if not hosted.
2. Rename .dagger/src/project_template_ci/ directory to match your project, and update the class names inside
3. Fill in project structure in the AGENTS.md Project Structure section
4. Fill in license info in README.md
5. When all TODOs are resolved: delete this "First-Time Setup" section entirely from AGENTS.md — it is only needed once

Rules

1. Always run mise run ai-docs at session start This will refresh your context with important information you will be assumed to know and follow. Read the full output — never truncate, pipe to head/tail, or skip sections.
2. Classify the change as C0/C1/C2 before starting (see below) — this determines branching and PR requirements
3. Feature branches + PRs for C1/C2 — checkout main, pull, create branch, open PR via tea pr create. C0 goes direct to main.
4. Add changelog fragments (all change levels) — docs/changelog.d/<name>.<type>.md Types: feature, bugfix, infra, doc, ai, misc
   • C1/C2: Use branch name: <branch>.<type>.md
   • C0: Use orphan prefix: +<descriptive-slug>.<type>.md
5. Never commit secrets

Change Classification

Before starting work, classify the change:

Class	Name	When to use	Key trait
C0	Quick Fix	Small, low-risk, fix-forward safe	Direct to main, no PR
C1	Human Review	Moderate complexity or risk	Feature branch + PR, docs-first
C2	Mikado Chain	Multi-phase, multi-session, high complexity	Mikado Branch Invariant

C0 — commit directly to main. No branch or PR needed. Fix forward if problems arise.

C1 — feature branch with early PR. Search related docs first, write documentation changes before code. Upgrade to C2 if complexity spirals.

C2 — branch mikado/<chain-stem> governed by the Mikado Branch Invariant: all card commits first, then code progress, then card closures. Commits use C2(<chain>): plan/impl/close/finalize convention. Reset the branch when new prerequisites are discovered. Resume with mise run docs-mikado --resume.

See agent-change-process for the full methodology.

Project Structure

./docs/                 # documentation (Diataxis, Quartz)
./docs/changelog.d/     # towncrier fragments
./.dagger/              # dagger pipelines
./.forgejo/             # forgejo-runner actions and workflows
./mise-tasks/           # scripts via `mise run`

Other code paths will be listed via ai-docs. When you encounter wiki-links ([[like-this]]) it is referring to docs/ cards.