docs(framework): add plugin concern taxonomy and skill placement rules

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
 

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.

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** - `<NN>-<name>` encodes the plugin's logical pipeline order, not a next-free counter. Inserting mid-flow means renumbering downstream folders, their `skills[]` entries, and every `<plugin>:<NN>-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: