Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
137 lines (110 loc) · 6.15 KB

ARCHITECTURE.md

File metadata and controls

137 lines (110 loc) · 6.15 KB

Architecture

How the AI-Driven Dev Framework composes inside Claude Code.

High-level

---
title: aidd-framework composition
---
flowchart TB
  subgraph User
    Editor["Claude Code session"]
  end

  subgraph Marketplace["Marketplace (this repo)"]
    Manifest[".claude-plugin/marketplace.json"]
    PluginsDir["plugins/"]
  end

  subgraph Plugins["Plugins (composable units)"]
    Context["aidd-context"]
    Dev["aidd-dev"]
    Vcs["aidd-vcs"]
    Pm["aidd-pm"]
    Orchestrator["aidd-orchestrator"]
    Refine["aidd-refine"]
  end

  subgraph SkillUnit["A plugin may ship (Claude Code surfaces)"]
    Skills["skills/ (SKILL.md + actions + assets)"]
    Agents["agents/"]
    Commands["commands/"]
    Hooks["hooks/ (hooks.json)"]
    Rules["rules/"]
    Mcp[".mcp.json (MCP servers)"]
  end

  Editor -->|"/plugin marketplace add"| Manifest
  Manifest -->|lists| PluginsDir
  PluginsDir --> Plugins
  Context --> SkillUnit
  Dev --> SkillUnit
  Vcs --> SkillUnit
  Pm --> SkillUnit
  Orchestrator --> SkillUnit
  Refine --> SkillUnit
  Editor -->|"/plugin install"| Plugins
  Editor -->|invokes| Skills
Loading

Anatomy of a plugin

Every plugin under plugins/<plugin>/ follows the same shape:

plugins/<plugin>/
├── .claude-plugin/
│   └── plugin.json        # manifest (name, version, description, skills[], $schema)
├── README.md              # human-facing landing page
├── CATALOG.md             # per-plugin auto-generated index
├── CHANGELOG.md           # release-please-managed
├── skills/                # router-based skills
│   └── <NN>-<name>/
│       ├── SKILL.md        # contract (name, description, actions table)
│       ├── README.md       # human-facing skill landing
│       ├── actions/        # atomic actions invoked by the router
│       ├── assets/         # templates and static files
│       └── references/     # extended docs the skill links into
├── agents/                 # named AI agents          (optional)
├── commands/               # slash commands           (optional)
├── hooks/hooks.json        # lifecycle hooks          (optional)
├── rules/                  # coding rules             (optional)
└── .mcp.json               # MCP server configuration (optional)

A plugin bundles any subset of the Claude Code surfaces (skills, agents, commands, hooks, rules, MCP servers); only skills/ and the manifest are universal. Browse the plugins to see which surfaces each one ships.

The plugin.json is validated against claude-code-plugin-manifest by the lefthook pre-commit hook (when the JSON-schema validator, pipx/check-jsonschema, is available); the same hook validates marketplace.json against claude-code-marketplace. The validate workflow re-runs the hooks on every push and PR.

Plugin concerns and layers

Every capability lives in exactly one plugin, chosen by concern. This taxonomy decides placement; it is only implicit in each plugin.json, so it is canonical here.

Plugin Concern Layer
aidd-context Knowledge production Knowledge
aidd-pm Product management Knowledge
aidd-refine Meta-cognition Knowledge
aidd-dev Code transformation Execution
aidd-vcs Version control External
aidd-orchestrator Orchestration Coordination

Three rules follow:

  • Knowledge vs execution is a firewall. Knowledge plugins produce artifacts you read (docs, plans, memory) and never write or run application source - aidd-context's bootstrap deliberately creates no package.json or source files. Real code belongs to aidd-dev or an orchestrator's own setup actions.
  • Concern decides placement, not existence. A missing capability goes in the plugin whose concern owns it, then the caller delegates. Never reimplement it in the calling plugin because the right home lacks it today.
  • Orchestration = sequencing across multiple concerns with little domain logic. Any skill may delegate a sub-step (Cross-plugin orthogonality); doing so once does not make it an orchestrator. The orchestrator owns only glue and delegates the depth, handing off through a seam artifact (e.g. an INSTALL.md one plugin produces and another consumes).

Skills are routers

A skill's SKILL.md is a manifest plus an actions table. Claude Code loads the SKILL.md when the skill is invoked; the body decides which action(s) to run.

---
title: skill router pattern
---
flowchart LR
  User["User: 'Use skill aidd-X:NN-name'"]
  Skill["SKILL.md (router)"]
  Action1["actions/01-step.md"]
  Action2["actions/02-step.md"]
  ActionN["actions/NN-step.md"]
  Out["Outputs: files, labels, PRs, audit logs"]

  User --> Skill
  Skill -->|"choose 1..N"| Action1
  Skill -->|"choose 1..N"| Action2
  Skill -->|"choose 1..N"| ActionN
  Action1 --> Out
  Action2 --> Out
  ActionN --> Out
Loading

Each action is a self-contained markdown file with inputs, outputs, depends-on, process steps, and a test checklist. Actions can call other skills via the Skill tool, so a skill discovers a capability it needs at runtime (by matching skill descriptions, never by hardcoded plugin name) and delegates to it.

Cross-plugin orthogonality

Plugins do not reference each other by name. When skill A needs a capability owned by skill B, it discovers a candidate at runtime through description matching. This rule keeps the marketplace forkable, the plugins swappable, and the docs maintainable.

The rule is enforced both socially (PR template checklist) and mechanically (lefthook hooks could be extended to grep for cross-plugin literal references).

See also