From 071dbb6e18f7a8d1d73e6bcfa4269326e26f84ee Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Sat, 6 Jun 2026 11:53:44 +0200 Subject: [PATCH] docs(framework): add plugin concern taxonomy and skill placement rules Document the concern/layer taxonomy as the canonical reference in ARCHITECTURE.md, add a 'concern decides placement, not existence' rule and an orchestration criterion, and a CREATE_PLUGIN section on placing/numbering a skill in an existing plugin. Tighten CLAUDE.md to point at the canonical home instead of restating it. Co-Authored-By: Claude Opus 4.8 (1M context) Signed-off-by: alexsoyes --- CLAUDE.md | 2 ++ docs/ARCHITECTURE.md | 19 +++++++++++++++++++ docs/CREATE_PLUGIN.md | 9 +++++++++ 3 files changed, 30 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index a9f9fd08..bf7514c5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -16,6 +16,8 @@ All instructions and information above are willing to be up to date, but always ## Technical guidelines - Do not commit or push yourself unless I ask you to. +- For every plugin change, think hard about where responsibility belongs; follow the placement and orchestration rules in `docs/ARCHITECTURE.md`. +- Never duplicate across docs - link to the canonical home. ### Answering Guidelines diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 35ad270a..b64644a3 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -79,6 +79,25 @@ A plugin bundles **any subset** of the Claude Code surfaces (skills, agents, com The `plugin.json` is validated against [`claude-code-plugin-manifest`](https://www.schemastore.org/claude-code-plugin-manifest.json) 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`](https://www.schemastore.org/claude-code-marketplace.json). 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](#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. diff --git a/docs/CREATE_PLUGIN.md b/docs/CREATE_PLUGIN.md index 85d04be4..a24af98a 100644 --- a/docs/CREATE_PLUGIN.md +++ b/docs/CREATE_PLUGIN.md @@ -4,6 +4,15 @@ This guide walks through building a new plugin for the AI-Driven Dev marketplace For broader OSS contribution rules (commit scopes, release flow), see [`../CONTRIBUTING.md`](../CONTRIBUTING.md). For the framework's architecture, see [`ARCHITECTURE.md`](ARCHITECTURE.md). +## Adding a skill to an existing plugin + +Most contributions add a *skill* to an existing plugin, not a new plugin. Decide two things first: + +- **Which plugin** - the owning concern decides; see the [concern taxonomy](ARCHITECTURE.md#plugin-concerns-and-layers). A capability owned by another concern goes in that plugin and you delegate to it. A skill that sequences across several concerns goes in `aidd-orchestrator`. +- **Which number** - `-` encodes the plugin's logical pipeline order, not a next-free counter. Inserting mid-flow means renumbering downstream folders, their `skills[]` entries, and every `:-name` invocation token - so weigh appending against inserting. + +The rest of this guide applies to the skill directory; skip the plugin-registration steps (the plugin already exists - you only edit its `plugin.json` `skills[]`). + ## Prerequisites The same toolchain as any framework contribution: