AI Assistance Guide

Audiences: AI, Owner

This guide provides context for AI agents (like Claude Code) assisting with this project.

Critical Rules

These are non-negotiable for AI agents working in this repo:

Run mise run ai-docs at session start — Review project documentation
Never commit secrets — The repo may be public
Wait for user review before deploying — Create PRs, don't auto-deploy
Never merge PRs without explicit request — The user merges after review

Full rules are in the repo's AGENTS.md. See agent-change-process for the C0/C1/C2 change classification methodology — C0 (direct to main), C1 (feature branch + PR), C2 (Mikado Branch Invariant).

Workflow Conventions

Branching

Branching depends on change classification (see agent-change-process):

C0 (Quick Fix): Commit directly to main — no branch or PR needed
C1/C2: Feature branch required:

git checkout main && git pull
git checkout -b feature/descriptive-name
# ... make changes ...
git commit -m "Description"

Pull Requests

Use the forge's tea CLI:

tea pr create --title "Title" --description "$(cat <<'EOF'
## Summary
- Change 1
- Change 2

## Testing
- [ ] Test step
EOF
)"

Changelog Fragments

Add a fragment for user-visible changes:

# C1/C2: use branch name
echo "Description" > docs/changelog.d/branch-name.feature.md

# C0: use orphan prefix (no branch to name after)
echo "Description" > docs/changelog.d/+descriptive-slug.feature.md

Types (file suffix): .feature, .bugfix, .infra, .doc, .ai, .misc

Wiki-Link Formatting

Use simple wiki-links without alternate text or extra spaces:

Prefer [[borgmatic]] over [[borgmatic|Borgmatic]]
Only use alternate text when grammatically warranted
No spaces around the pipe: [[path|Text]] not [[ path|Text ]]

When editing documentation, rewrite links to follow this convention as you encounter them.

Mise Tasks

Run mise tasks to list all available tasks.

Task	When to Use
`ai-docs`	At session start — review project documentation
`changelog-check`	Validate that changelog fragments are flat files in `docs/changelog.d/`
`docs-check-frontmatter`	Check required frontmatter fields across docs
`docs-preview`	Preview a released docs tarball locally
`docs-mikado`	View active Mikado dependency chains for C2 changes
`docs-mikado --resume`	Resume a C2 chain: detect branch, show state and next steps
`pr-comments`	Check unresolved PR comments during review
`runner-logs`	Inspect recent Forgejo Actions runs or fetch logs for a job
`docs-check-links`	Validate wiki-links in documentation (includes orphan detection)
`docs-check-index`	Check every doc is referenced in its category index
`docs-check-filenames`	Check for duplicate doc filenames

Repository Tooling

This project ships two Forgejo workflows:

build.yaml runs on pushes and pull requests targeting main, executes prek run --all-files, and then runs an optional project hook at .forgejo/scripts/build when present.
release.yaml is a manual workflow that computes the next version, optionally builds CHANGELOG.md from fragments, packages Quartz docs via Dagger, runs an optional .forgejo/scripts/release hook for extra assets, creates the Forgejo release, and pushes changelog updates back to main when fragments were consumed.
TODO: Rename .dagger/src/project_template_ci/ and the exported Dagger class during first-time setup.

Common Pitfalls

Pitfall	Correct Approach
Deploying without review	Create PR first, wait for user approval
Re-explaining reference material	Link to reference cards instead
Committing to main without classifying	Classify as C0/C1/C2 first — only C0 goes to main

3.9 KiB Raw Blame History