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:

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

Rules

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.
Classify the change as C0/C1/C2 before starting (see below) — this determines branching and PR requirements
Generated repos use feature branches + PRs for C1/C2 — checkout main, pull, create branch, open PR via tea pr create. This template source repo usually stays C0/direct-to-main so it remains clean and templatable.
Use changelog fragments in generated repos, not as template residue — docs/changelog.d/<name>.<type>.md Types: feature, bugfix, infra, doc, ai, misc
- Generated repos: add fragments for noteworthy changes
- This template repo: keep docs/changelog.d/ empty except for .gitkeep
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 — in generated repos, use a feature branch with an early PR. In this template source repo, prefer direct cleanups unless the user explicitly wants branch-based review. 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/                 # Diataxis docs, Quartz config, and release content
./docs/changelog.d/     # keep only .gitkeep in the template; generated repos add towncrier fragments here
./.dagger/              # Dagger module; rename src/project_template_ci/ when forking
./.forgejo/workflows/   # generic build and release workflows for generated repos
./.forgejo/scripts/     # optional per-project build/release hooks consumed by the workflows
./mise-tasks/           # repo automation 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.

3.5 KiB Raw Blame History