hephaestus/docs/tutorials/ai-assistance-guide.md

---
title: AI Assistance Guide
modified: 2026-04-19
tags:
  - tutorials
  - ai
---

# 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:
```bash
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:
```bash
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:
```bash
# 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.

The Dagger module lives at `.dagger/src/hephaestus_ci/` and exports the `HephaestusCi` class.

## 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 |