Erich Blume
c1f7b2a9a3
## Summary - Introduce C0/C1/C2 change classification based on the Mikado method, where documentation cards serve as persistent context for agents across sessions - Add `docs-mikado` mise task to visualize active Mikado dependency chains from `status: active` and `requires` frontmatter fields - Rename `zk-docs` task to `ai-docs` ## Changes - **New:** `docs/how-to/agent-change-process.md` — methodology card - **New:** `mise-tasks/docs-mikado` — Python uv script for dependency graph visualization - **Renamed:** `mise-tasks/zk-docs` → `mise-tasks/ai-docs` - **Updated:** `CLAUDE.md` — added Change Classification section, updated references - **Updated:** `ai-assistance-guide.md`, `exploring-the-docs.md`, `how-to.md` — updated references and index ## Verification - [x] `mise run ai-docs` works - [x] `mise run docs-mikado` runs (no active chains yet, as expected) - [x] `docs-check-links` — all valid - [x] `docs-check-index` — all indexed - [x] `docs-check-frontmatter` — all valid - [x] All pre-commit hooks pass 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/225
135 lines
4.7 KiB
Markdown
135 lines
4.7 KiB
Markdown
---
|
|
title: AI Assistance Guide
|
|
modified: 2026-02-09
|
|
tags:
|
|
- tutorials
|
|
- ai
|
|
---
|
|
|
|
# AI Assistance Guide
|
|
|
|
> **Audiences:** AI, Owner
|
|
|
|
This guide provides context for AI agents (like Claude Code) assisting with BlumeOps operations, and helps Erich understand how to work effectively with AI assistance.
|
|
|
|
## Critical Rules
|
|
|
|
These are non-negotiable for AI agents working in this repo:
|
|
|
|
1. **Always use `--context=minikube-indri` with kubectl** - Work contexts exist that must never be touched
|
|
2. **Run `mise run ai-docs` at session start** - Review current infrastructure state
|
|
3. **Never commit secrets** - The repo is public at github.com/eblume/blumeops
|
|
4. **Wait for user review before deploying** - Create PRs, don't auto-deploy
|
|
5. **Never merge PRs without explicit request** - The user merges after review
|
|
|
|
Full rules are in the repo's `CLAUDE.md`. See [[agent-change-process]] for the C0/C1/C2 change classification methodology.
|
|
|
|
## Workflow Conventions
|
|
|
|
### Feature Branches
|
|
|
|
All work happens on feature branches:
|
|
```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
|
|
|
|
## Deployment and Testing
|
|
- [ ] Test step
|
|
EOF
|
|
)"
|
|
```
|
|
|
|
### Changelog Fragments
|
|
|
|
Add a fragment for user-visible changes:
|
|
```bash
|
|
echo "Description" > docs/changelog.d/branch-name.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 (e.g., `[[cluster|Kubernetes]]` reads better than `[[cluster]]`)
|
|
- No spaces around the pipe: `[[path|Text]]` not `[[ path|Text ]]`
|
|
|
|
When editing documentation, rewrite links to follow this convention as you encounter them.
|
|
|
|
## Service Locations
|
|
|
|
Understanding where services run helps target changes correctly:
|
|
|
|
| Location | Services | Management |
|
|
|----------|----------|------------|
|
|
| [[indri]] (native) | Forgejo, Zot, Jellyfin, Caddy | Ansible |
|
|
| [[cluster|Kubernetes]] | Everything else | ArgoCD |
|
|
|
|
## Mise Tasks
|
|
|
|
BlumeOps operations are driven by mise tasks. Run `mise tasks` to list all available tasks.
|
|
|
|
| Task | When to Use |
|
|
|------|-------------|
|
|
| `ai-docs` | At session start - review infrastructure documentation |
|
|
| `docs-mikado` | View active Mikado dependency chains for C1/C2 changes |
|
|
| `provision-indri` | Deploy changes to [[indri]]-hosted services via Ansible |
|
|
| `services-check` | After deployments - verify all services are healthy |
|
|
| `pr-comments` | Check unresolved PR comments during review |
|
|
| `blumeops-tasks` | Find pending tasks from Todoist |
|
|
| `container-list` | View available container images and tags |
|
|
| `container-tag-and-release` | Release a new container image version |
|
|
| `dns-preview` | Preview DNS changes before applying |
|
|
| `dns-up` | Apply DNS changes via Pulumi |
|
|
| `tailnet-preview` | Preview Tailscale ACL changes |
|
|
| `tailnet-up` | Apply Tailscale ACL changes via Pulumi |
|
|
| `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 |
|
|
| `docs-review-stale` | Report docs by last-modified date, highlight stale ones |
|
|
| `docs-review-tags` | Print frontmatter tag inventory across all docs |
|
|
| `docs-review` | Review the most stale doc by last-reviewed date |
|
|
| `indri-runner-logs` | View Forgejo workflow logs from local runner |
|
|
|
|
For ArgoCD operations, use the `argocd` CLI directly:
|
|
- `argocd app diff <service>` - Preview changes
|
|
- `argocd app sync <service>` - Deploy changes
|
|
|
|
## Reference Navigation
|
|
|
|
For AI agents building context:
|
|
|
|
- [[reference|Reference]] - Entry point for technical details
|
|
- [[hosts|Host Inventory]] - What hardware exists
|
|
- [[apps|ArgoCD Apps]] - What's deployed in Kubernetes
|
|
- [[routing|Routing]] - How services are exposed
|
|
|
|
## Credential Access
|
|
|
|
Credentials live in 1Password. Never retrieve them directly - use existing patterns:
|
|
- Ansible `pre_tasks` gather secrets at playbook start
|
|
- [[external-secrets]] syncs to Kubernetes
|
|
- Scripts use `op` CLI with user biometric prompts
|
|
|
|
## Common Pitfalls
|
|
|
|
| Pitfall | Correct Approach |
|
|
|---------|------------------|
|
|
| Missing kubectl context | Always add `--context=minikube-indri` |
|
|
| Deploying without review | Create PR first, wait for user approval |
|
|
| Re-explaining reference material | Link to reference cards instead |
|
|
| Committing to main | Use feature branches |
|
|
| Guessing at credentials | Ask user or check 1Password patterns |
|