Add agent change process (C0/C1/C2) and docs-mikado tool #225

Merged
eblume merged 1 commit from feature/agent-change-process into main 2026-02-20 08:15:20 -08:00
Owner

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

  • mise run ai-docs works
  • mise run docs-mikado runs (no active chains yet, as expected)
  • docs-check-links — all valid
  • docs-check-index — all indexed
  • docs-check-frontmatter — all valid
  • All pre-commit hooks pass

🤖 Generated with Claude Code

## 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)
Introduce a three-tiered change classification (C0/C1/C2) based on the
Mikado method, where documentation cards serve as persistent context for
agents across sessions. Rename zk-docs to ai-docs. Add docs-mikado tool
to visualize active Mikado dependency chains.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@ -0,0 +8,4 @@
# Agent Change Process
> **Audiences:** AI, Owner
Author
Owner

How-to articles don't need explicit audiences, only tutorials

How-to articles don't need explicit audiences, only tutorials
@ -0,0 +35,4 @@
Use the [Mikado method](https://mikadomethod.info/) within a single session:
1. Run `mise run ai-docs` to load context
2. Attempt the change on a feature branch
Author
Owner

This won't work for changes that require commits due to gitops. Instead, encourage the use of amending a single commit, and actually reverting when an error occurs. Same for C2.

This won't work for changes that require commits due to gitops. Instead, encourage the use of amending a single commit, and actually reverting when an error occurs. Same for C2.
@ -0,0 +69,4 @@
---
title: Deploy Authentik
status: active # omit when complete
requires: # explicit dependencies
Author
Owner

Ah, lets add something to the frontmatter doc check. status and requires should only be permitted for docs within docs/how-to.

Ah, lets add something to the frontmatter doc check. `status` and `requires` should only be permitted for docs within `docs/how-to`.
@ -0,0 +92,4 @@
- Single feature branch per C1/C2 change
- Always revert broken working tree changes — don't leave broken code committed
- Broken commits may happen (GitOps requires pushing to test) but must be reverted promptly
Author
Owner

yeah this is what I was talking about above, so you get the idea

yeah this is what I was talking about above, so you get the idea
@ -0,0 +3,4 @@
# requires-python = ">=3.12"
# dependencies = ["pyyaml>=6.0", "rich>=13.0.0", "typer>=0.15.0"]
# ///
#MISE description="View active Mikado dependency chains for C1/C2 changes"
Author
Owner

Check some other scripts, I think MISE has a USAGE hint and maybe others which make it so you don't need -- arg1 arg2 to separate the mise task args.

Check some other scripts, I think MISE has a USAGE hint and maybe others which make it so you don't need ` -- arg1 arg2` to separate the mise task args.
@ -0,0 +46,4 @@
def build_graph() -> dict[str, dict]:
"""Build the dependency graph from all docs."""
Author
Owner

Do we detect circular dependencies here? let's make sure we do. Just a set of all encountered filenames maybe?

Do we detect circular dependencies here? let's make sure we do. Just a set of all encountered filenames maybe?
eblume force-pushed feature/agent-change-process from 2e692549f2 to 6f0a72445f 2026-02-20 08:14:12 -08:00 Compare
eblume merged commit c1f7b2a9a3 into main 2026-02-20 08:15:20 -08:00
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
eblume/blumeops!225
No description provided.