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:

1. Run mise run ai-docs at session start — Review project documentation
2. Never commit secrets — The repo may be public
3. Wait for user review before deploying — Create PRs, don’t auto-deploy
4. 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
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
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

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