Structural review: is ai-config developing reasonably?

[d-morrison]

Context

Asked Claude to assess whether this repo's structure is reasonable, since there's no single canonical standard for "portable AI agent config" projects. This issue records that assessment for future reference — not a bug report or a task, just a structural review to revisit periodically.

Verdict

Yes — the structure is reasonable, and arguably more rigorous than most comparable personal AI-config repos, which typically amount to a loose CLAUDE.md with no validation and no self-maintenance loop.

What's actually there

Layout — clean separation of concerns at the repo root:

Dir	Role
skills/ (146 dirs)	One SKILL.md per skill, consistent frontmatter (name, description, user-invocable, allowed-tools)
memories/	3 topic files (preferences.md, tools.md, debugging.md) + MEMORY.md index registering each
shared/	workflow/, coding/, writing/, vendored/ — single-topic fragments pulled into CLAUDE.md via @shared/... includes, shared with the UCD-SERG lab manual repo
codex-skills/	Generated thin wrappers (146, 1:1 with skills/) so Codex can read the same canonical skills, guarded by a CI drift check
commands/, .claude/agents/	Slash commands (deliberately thin — 1 file) and read-only custom subagents
docs/, *.qmd + _quarto.yml	A published Quarto reference site (setup, skills index, workflow guide, agents)
scripts/	validate-skills.py, check-links.py, check-vendored-drift.py, sync-codex-skill-wrappers.py, inventory.sh
tool-mappings.yml/.md	Maps skill-named operations (e.g. COMMENT_PR) to each consumer model's actual tool, so skills stay usable by non-Claude agents

Real governance, not just prose conventions. CI (validate.yml) runs schema validation, link checking, vendored-fragment drift checking, and markdownlint on every push/PR. .pre-commit-config.yaml adds gitleaks secret scanning plus structural gates.

Explicit anti-entropy mechanisms — the most notable design choice. Because the corpus grows organically from lived session experience, it has a real sprawl risk. The repo answers that with dedicated skills rather than hoping discipline holds:

• skill-builder enforces "extend before create" (Step 0: search for an existing skill to extend before scaffolding a new one).
• find-overlap / consolidate-skills / consolidate-memory do periodic dedup sweeps across skills and memories.
• heal-skill repairs a skill after it misfires.
• ums (update-memories-and-skills) is the standing checkpoint that runs before /clear and after every merged PR, so lessons get folded in immediately rather than lost.

Deliberate portability design. Three consumption modes (local symlink bootstrap, generated Codex wrappers, Claude Code plugin marketplace for use from other repos' web sessions), plus the tool-mappings abstraction so a skill written in terms of gh/git still resolves correctly for a model without that CLI.

Benchmarked against peers, not ad hoc. scout-peers explicitly surveys comparable open-source projects (cc-skills, claude-code-plugins-plus-skills, dotfiles-claude, awesome-claude-code-toolkit), and CREDITS.md records which conventions were adapted from where, with license checks.

Low visible debt markers. Only 3 files repo-wide contain TODO/FIXME/XXX. The skills/↔codex-skills/ duplication is an intentional generated pairing guarded by CI, not accidental drift.

Things worth watching (not action items yet)

• Scale. 146 skills and a 1,639-line memories/tools.md is a lot of surface area for one person to hold a mental map of. Worth periodically confirming find-overlap sweeps are actually catching things.
• CLAUDE.md length. 399 lines of standing directives is substantial for a model to reliably apply on every turn. There's precedent for trimming (e.g. a "Dedupe two literal restatements in memories/" commit), but no dedicated periodic "prune CLAUDE.md itself" skill the way there is for skills//memories/.
• No CHANGELOG.md. Despite very active churn, change rationale lives only in git history and inline "Learned on gha#N" / "ai-config#N" citations. Workable for a single maintainer who reads every PR, but not skimmable without walking git log.
• Process weight vs. team size. The full issue-first → PR → ARDI review loop (with an AI bot reviewer) is applied even to what is, in practice, a single-maintainer repo. Likely deliberate — the repo doubles as a testbed for the AI-driven dev workflow it documents — but worth naming as a conscious tradeoff (velocity/ceremony) in case it stops paying for itself.