feat: Composable Config Architecture - Restructure for atomic components and profiles

[aRustyDev]

Overview

Restructure the ai repository to support a composable configuration architecture where atomic, schema'd components can be dynamically assembled into tool-specific configs based on machine profiles.

Context

This repo serves as the shareable source of truth for AI-related configurations (rules, skills, commands, hooks, context). The dotfiles repo will consume this as a submodule and handle deployment.

Workflow

Project .claude/  ──promote──▶  ai/ (source)  ──build──▶  global (~/.claude/)
                                    │
                                    ▼
                              dotfiles/
                          (deployment layer)

Target Directory Structure

ai/
├── components/                  ← Atomic, reusable pieces
│   ├── rules/                   ← Schema'd JSON rule objects
│   │   ├── git-workflow.rule.json
│   │   ├── security-review.rule.json
│   │   └── ...
│   ├── skills/                  ← Skill definitions (SKILL.md + supporting files)
│   ├── commands/                ← Slash command templates
│   ├── hooks/                   ← Hook definitions
│   └── context/                 ← Shared context fragments (CLAUDE.md pieces)
│
├── profiles/                    ← Machine/use-case profiles
│   ├── personal.profile.json   ← "include these rules, exclude those"
│   ├── work.profile.json
│   ├── server.profile.json
│   └── minimal.profile.json
│
├── tools/                       ← Tool-specific output schemas
│   ├── claude-code/
│   │   └── schema.json         ← How to compile for Claude Code
│   ├── zed/
│   │   └── schema.json
│   ├── claude-desktop/
│   │   └── schema.json
│   └── vscode/
│       └── schema.json
│
├── mcp/                         ← MCP server definitions
│   ├── global/                  ← Remote/shared MCP configs (HTTP-based)
│   │   ├── memory.mcp.json
│   │   └── github.mcp.json
│   └── local/                   ← Project-scoped MCP templates (filesystem access)
│       └── filesystem.mcp.json
│
├── schemas/                     ← JSON schemas for validation
│   ├── rule.schema.json
│   ├── skill.schema.json
│   ├── profile.schema.json
│   └── mcp.schema.json
│
├── build/                       ← Build tooling
│   ├── compile.py              ← Compiles components → tool configs
│   ├── validate.py             ← Schema validation
│   ├── diff.py                 ← Compare profiles/versions
│   └── promote.py              ← Extract from project → components
│
├── dist/                        ← Generated output (gitignored)
│   ├── claude-code/
│   │   └── personal/
│   │       ├── commands/
│   │       ├── skills/
│   │       └── rules/
│   └── zed/
│       └── personal/
│
└── legacy/                      ← Current content during migration
    ├── agents/
    ├── commands/
    ├── rules/
    └── ...

Component Schema Design (Future)

Rule Component Example

{
  "$schema": "../schemas/rule.schema.json",
  "id": "git-workflow",
  "version": "1.0.0",
  "tags": ["git", "workflow", "commits"],
  "priority": 100,
  "conflicts_with": [],
  "depends_on": [],
  "content": {
    "title": "Git Workflow Rules",
    "sections": [
      {
        "heading": "Branch Strategy",
        "instructions": [
          "Use feature branches for all development",
          "Never commit directly to main/master"
        ]
      }
    ]
  },
  "output": {
    "claude-code": "markdown",
    "zed": "markdown",
    "cursor": "markdown"
  }
}

Profile Example

{
  "name": "personal",
  "description": "Personal development machines",
  "extends": ["minimal"],
  "rules": {
    "include": ["git-workflow", "security-*", "clean-code"],
    "exclude": ["enterprise-*"]
  },
  "skills": {
    "include": ["homebrew-formula", "github-actions-ci"]
  },
  "mcp": {
    "global": ["memory", "github", "context7"],
    "local_templates": ["filesystem"]
  },
  "variables": {
    "github_user": "arustydev",
    "default_branch": "main"
  }
}

MCP Config Classes

Two classes of MCP configurations:

Class	Access	Hosting	Use Case
Global	Shared across machines	Remote HTTP	Memory, GitHub, Context7
Local	Project-scoped	Local process	Filesystem, project-specific

The build system will:

1. Compile MCP configs from templates
2. Resolve op://vault/item/key references at deploy time
3. Generate tool-specific formats (Claude Code, Zed, etc.)

Implementation Phases

Phase 1: Structure (Current Focus)

• Create new directory structure
• Move existing content to legacy/
• Update README with new architecture
• Add as submodule to dotfiles

Phase 2: Basic Workflow

• Create promote-component script (simple copy for now)
• Create basic justfile recipes
• Migrate one component type as proof of concept

Phase 3: Schema & Compilation

• Define JSON schemas for all component types
• Build compile.py for tool-specific output
• Add schema validation to CI
• Migrate components to schema'd format

Phase 4: Profiles & Dynamic MCP

• Define profile schema with inheritance
• Implement profile-based filtering in build
• Add MCP config generation
• Add op:// secret resolution at deploy time

Design Goals

1. Atomic Components: Each rule, skill, command is a self-contained unit
2. Schema Validation: JSON schemas ensure consistency and enable tooling
3. Profile Composition: Machines get tailored configs via profile selection
4. Tool Agnostic: Same components compile to different tool formats
5. Shareable: This repo can be shared publicly or with teams
6. Experimentable: Structured data enables A/B testing of prompts/rules

Related

• dotfiles repo: will consume this as submodule
• See .ai/plans/ai-config-sync-options.md in homebrew-tap for full analysis

Labels

• enhancement
• architecture