Skip to content

Documentation Architecture

Where system documentation lives, what is canonical vs legacy, and how to make documentation changes

When to use

When the user asks about documentation structure, where docs live, or how to update system documentation

Directions

Documentation Hierarchy

  1. CLAUDE.md — Agent orientation file. High-level structure, capability registry tables, operational rules. Valid to edit directly for top-level changes.
  2. knowledge/store/*.json — The canonical, queryable documentation store. All detailed subsystem docs, behavioral directions, capability descriptions, and workflow definitions live here. Edit via docs_update, docs_create, docs_delete, docs_move.
  3. CLAUDE.local.md — User-specific behavioral instructions. Not checked into git.

What is DEPRECATED / Legacy

  • work_buddy/*/README.md files — These are legacy documentation from before the knowledge store existed. They are pending extraction and deletion. NEVER edit these files. If you find useful content in them that isn't in the knowledge store, extract it into a knowledge unit via docs_create or docs_update, then mark the README for removal.
  • metacognition/ directory — Fully migrated to the personal knowledge system (knowledge_personal). The directory should not be referenced, edited, or maintained. Pattern detection uses knowledge_personal with category/severity filters.
  • workflows/ directory — Deleted. Workflow DAGs now live in knowledge/store/workflows.json.
  • DEV.md — Deleted. Architecture patterns, design tenets, and import discipline are now in the knowledge store under dev/design-tenets, architecture/mcp-import-discipline, and architecture/workflows.

How to Make Documentation Changes

  1. For knowledge store content: Use docs_update(path, fields) to modify existing units, docs_create(path, ...) to add new ones. Never edit the JSON files directly.
  2. For CLAUDE.md: Edit the file directly — it's the orientation layer, not a knowledge store unit.
  3. For capability descriptions: These are auto-generated by python -m work_buddy.knowledge.build --write. Edit the capability's docstring in registry.py, then rebuild.
  4. For personal knowledge: Use knowledge_mint to create/update vault-backed units.

Common Mistakes to Avoid

  • Editing in-package README.md files instead of knowledge store units
  • Referencing metacognition/ paths instead of using knowledge_personal
  • Referencing workflows/*.md paths instead of knowledge/store/workflows.json
  • Duplicating knowledge store content into CLAUDE.md (keep CLAUDE.md as a summary/pointer layer)
  • Spawning agents to review README files for accuracy (they are legacy and doomed for deletion)