azos

Architecture
Conventions
- Writing Claude Skills
Gotchas
Key Files
Subnodes

Architecture

Two-tier NixOS/home-manager feature system: azos-core/ (shared submodule) + features/ (machine-specific). Features auto-discovered via import-tree, collected into config.flake.modules.

See azos/architecture for module registration, option namespace, file deployment, and Claude Code wiring.

Conventions

azos-core features belong to the submodule; machine-specific features live in the outer repo
Extensible options follow the pattern established by azos.claude.globalSkills and azos.claude.globalMdSections: attrsets any module can contribute to, deployed by the owning feature
Emacs config is literate org: azos-core/features/editor/emacs/config.org
Emacs base config: azos-core/features/base/emacs/config.org
agent-shell defaults to Claude Code on lauretta via (setq agent-shell-preferred-agent-config 'claude-code) in features/lauretta/emacs/config.org; this symbol skips agent selection entirely (no prompt)
Rebuild command: azos-lauretta-update
Format: nix fmt
Packages in overlay: pkgs.<name> via config.flake.overlayPkgs.<name>
Unstable packages: pkgs.unstable.<package>

Writing Claude Skills

Skill descriptions are routing keys — they determine whether a skill activates. Guidelines (ref: https://stevekinney.com/writing/agent-skills):

Open with TRIGGER on: and numbered conditions so activation is unambiguous
One specific job per skill; overlapping descriptions cause routing competition
Scope exclusions: state what the skill does NOT replace to prevent false positives
Domain-specific language; no generic phrases like "helps with X"

Gotchas

azos-core is a git submodule — git add must be run inside it separately from the outer repo
Nix flakes only evaluate git-tracked files; new files must be staged (git add) before nix build will see them
import-tree auto-discovers features but only sees tracked files — same constraint
The machine name is lauretta; machine config is at _machines/lauretta.nix
postPatch in Nix derivations: alejandra reformats indentation of multiline strings, which can change effective shell script content

Key Files

File	Purpose
`azos-core/features/claude-memory/default.nix`	org-roam MCP server integration
`azos-core/features/claude-skills/default.nix`	global skills + CLAUDE.md deployment
`azos-core/features/claude-skills/skills/todo.md`	per-project TODO management skill
`azos-core/features/claude-skills/skills/project-brain.md`	org-roam second brain skill
`azos/features/claude/default.nix`	installs claude-code, enables claude-memory + claude-skills
`features/lauretta/emacs/config.org`	lauretta-specific Emacs overrides (agent-shell, LLM, beacon, caldav)
`~/.claude/settings.json`	Claude Code global permissions; always-allowed org-roam MCP tools listed here

Subnodes

azos/architecture — module registration, option namespace, file deployment, Claude Code wiring
azos/org-roam — setup, MCP server, SQLite internals, fork details

3.2 KiB Raw Permalink Blame History