61 lines
3.1 KiB
Markdown
61 lines
3.1 KiB
Markdown
# 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
|
|
|
|
<!-- TODO: Fill in when forking this template -->
|
|
```
|
|
./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.
|