diff --git a/.gitignore b/.gitignore index 59066f5..1319dad 100644 --- a/.gitignore +++ b/.gitignore @@ -34,6 +34,11 @@ apm_modules/ .claude/skills/ .claude/agents/ +# APM MCP deployment output — `apm install` writes the repo-root .mcp.json from +# the MCP servers its dependencies declare, and regenerates it on every install. +# It is apm's output, not repo content; nothing here is hand-authored. +/.mcp.json + # APM hook deployment output — `apm install` copies each package's referenced # hook scripts here and tracks its own settings.json entries in the sidecar. # Regenerated on every install; the authoring source is diff --git a/.mcp.json b/.mcp.json deleted file mode 100644 index 7aa9712..0000000 --- a/.mcp.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "mcpServers": { - "obsidian": { - "args": [ - "@bitbonsai/mcpvault@0.15.0", - "docs/" - ], - "command": "npx", - "type": "stdio" - } - } -} diff --git a/README.md b/README.md index 6c5fcc6..14491b7 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ Content ships as six installable plugins, each an apm (Agent Package Manager) pa | Path | What it holds | | --- | --- | -| `plugins/` | Six apm packages — `bin`, `core`, `git`, `gitea`, `kyberforge`, `lint` — each carrying skills, and where relevant agents, hooks, MCP servers, and bundled assets | +| `plugins/` | Six apm packages — `bin`, `core`, `git`, `gitea`, `kyberforge`, `lint` — each carrying skills, and where relevant agents, hooks, and bundled assets | | `providers/claude-code/` | Claude Code adapter, deployed to `~/.claude/` via `scripts/install.sh` | | `core/` | Provider-agnostic always-on content — `core/AGENTS.md` and `core/instructions/` | | `docs/` | Specs (`docs/spec/`), architectural decisions (`docs/adr/`), governance, research, and notes | @@ -52,7 +52,7 @@ apm install pre-commit install -t pre-commit -t commit-msg -t pre-push ``` -**`apm install`** deploys the six plugins into `.claude/skills/` and `.claude/agents/`. Both are gitignored install output, *not* authoring source — `plugins//.apm/` remains the only place to edit. It needs the network, materializes `apm_modules/` (which stays gitignored), and also configures the `obsidian` MCP server into the repo's `.mcp.json`. +**`apm install`** deploys the six plugins into `.claude/skills/` and `.claude/agents/`. Both are gitignored install output, *not* authoring source — `plugins//.apm/` remains the only place to edit. It needs the network and materializes `apm_modules/` (which stays gitignored). **Git hooks** must be wired for **all three stages**. This repo's `.pre-commit-config.yaml` has no `default_install_hook_types`, so a plain `pre-commit install` silently skips `commit-msg` (Conventional Commits) and `pre-push` (the full gate) — the `-t` flags above are not optional. The `pc-run` skill handles this and the troubleshooting around it, if you would rather not remember the flags. @@ -95,7 +95,7 @@ See [`docs/spec/gates.md`](docs/spec/gates.md) for what each hook enforces and w ## Editing plugin content -`plugins//.apm/` is the only hand-edited source for plugin content — the root `marketplace.json` manifest is generated by `apm pack`, and a hand-edit there is reported as drift by `apm-pack-check-clean`. Hand-authored material that is not an `.apm/` primitive (`README.md`, `docs/`, `bin/`, `sources.md`, `.mcp.json`) lives at the plugin root instead. +`plugins//.apm/` is the only hand-edited source for plugin content — the root `marketplace.json` manifest is generated by `apm pack`, and a hand-edit there is reported as drift by `apm-pack-check-clean`. Hand-authored material that is not an `.apm/` primitive (`README.md`, `docs/`, `bin/`, `sources.md`) lives at the plugin root instead. Full model, including what's exempt and why: [`docs/spec/architecture.md`](docs/spec/architecture.md). diff --git a/docs/adr/0011-gitea-skill-deep-modules.md b/docs/adr/0011-gitea-skill-deep-modules.md index 971cc35..992b8c1 100644 --- a/docs/adr/0011-gitea-skill-deep-modules.md +++ b/docs/adr/0011-gitea-skill-deep-modules.md @@ -67,6 +67,14 @@ than being wired into the plugin manifest. This means the gitea plugin is not ye standalone via `claude plugin install gitea@holocron` without manual MCP setup. A follow-up Gitea issue tracks closing this gap. +**Correction (2026-09-14):** this gap is now closed by removal rather than by wiring. ADR-0024 +made apm the only supported install path, so `claude plugin install gitea@holocron` is no longer +a route this repo supports, and the per-plugin manifests it needed are gone. Because apm reads a +plugin-root `.mcp.json` only on the marketplace-plugin code path, that file became unreadable; +every `plugins/*/.mcp.json` was deleted, including this one. A plugin that needs an MCP server +declares it in `dependencies.mcp` in its `apm.yml` — the supported mechanism, which this repo has +never used. The follow-up issue this paragraph anticipates is moot. + **Research backfill.** The existing research docs (`plugins/gitea/docs/research/docs/gitea/`) are 100% code-derived from gitea-mcp source with zero external/best-practice content (the original docs.gitea.com fetch timed out and was never diff --git a/docs/adr/0018-repo-consumes-its-own-plugins-through-apm.md b/docs/adr/0018-repo-consumes-its-own-plugins-through-apm.md index 44fe717..1edc752 100644 --- a/docs/adr/0018-repo-consumes-its-own-plugins-through-apm.md +++ b/docs/adr/0018-repo-consumes-its-own-plugins-through-apm.md @@ -5,6 +5,16 @@ authored `.apm/` tree discoverable by hosts that install natively. Both are abou marketplace. This ADR is about consuming it: how the plugins get onto the machine this repo is worked on. +**Correction (2026-09-14): the flat content mirror named above no longer exists.** ADR-0017 is +superseded by ADR-0024, and commit `718c79a` deleted the mirror +(`plugins//{skills,agents,hooks}/`) along with its generator, its test suite and its pre-push +gate; native `claude plugin install` is no longer a supported path, so there are no longer "hosts +that install natively" for it to serve. Nothing this ADR decides depends on the mirror — it appears +here only as the other half of "producing the marketplace", and once more under "Install output is +gitignored" below, where the two copies of plugin content ADR-0017 governed are now one, `.apm/` +itself, and committing the deployed skills would make a second rather than a third. Read both +mentions as historical. + **Status: executed (2026-08-14).** All six packages are installed into `/root/ai-development` by `apm install`; the six native project-scope installs (`claude plugin uninstall @holocron --scope project`) are gone and `.claude/settings.json`'s `enabledPlugins` block is empty. @@ -121,6 +131,19 @@ unprompted. The `gitea` and `context7` servers were never plugin-provided — th apm's "contributed no entries to claude settings; skipped" warning on `kyberforge` and `lint` is accurate and harmless. +**Correction (2026-09-14): the MCP propagation above stopped operating, and the files it read are +deleted.** It ran on one code path only — `apm_cli/deps/plugin_parser.py` maps a plugin-root +`.mcp.json` onto `.apm/.mcp.json` for packages apm treats as *marketplace plugins*. Commit +`718c79a` (ADR-0024) deleted every `plugins/*/.claude-plugin/plugin.json` and +`plugins/*/.github/plugin/plugin.json`, so each package is now a plain apm package and that path no +longer runs. The supported declaration was never in use either: `plugins/bin/apm.yml` has +`dependencies.mcp: []`. That left the six plugin-root `.mcp.json` files dead config — five of them +empty stubs, only `plugins/bin`'s carrying the `obsidian` server — and all six are now deleted along +with the server itself, which is not wanted. The repo-root `.mcp.json` was apm's own generated +output that happened to be tracked; it is deleted and gitignored, on the same reasoning as +`.claude/skills/`. The rest of this paragraph is unaffected: `gitea` and `context7` were never +plugin-provided, and the hooks claim never depended on any of this. + **A `.apm/` edit now needs a round trip.** The dependency resolves from the remote, so an edit is invisible to the running session until it is pushed and the install is refreshed. Under the native install with `autoUpdate` the shape was the same; it was more noticeable here at first because the diff --git a/docs/spec/architecture.md b/docs/spec/architecture.md index 1b8e366..f448177 100644 --- a/docs/spec/architecture.md +++ b/docs/spec/architecture.md @@ -48,7 +48,7 @@ One compiler produces the generated content in the tree: apm is the only supported install path. A flat `skills/`, `agents/`, `hooks/` mirror used to be compiled to each plugin root so Claude Code's installer could convention-scan it, alongside a per-plugin `.claude-plugin/plugin.json` and `.github/plugin/plugin.json`; both are gone, together with native `claude plugin install` support. apm reads `plugins//apm.yml` and deploys from `.apm/` directly, and never probed those manifests. -`.apm/` is the sole hand-edited authoring source for plugin content. Hand-authored material that is not an `.apm/` primitive — `README.md`, `docs/`, `bin/`, `sources.md`, `.mcp.json`, and per-plugin extras such as `plugins/gitea/references/` and `plugins/bin/evals/` — lives at the plugin **root**. A hand-edit to the generated `.claude-plugin/marketplace.json` is reported as drift by the `apm-pack-check-clean` pre-push hook. +`.apm/` is the sole hand-edited authoring source for plugin content. Hand-authored material that is not an `.apm/` primitive — `README.md`, `docs/`, `bin/`, `sources.md`, and per-plugin extras such as `plugins/gitea/references/` and `plugins/bin/evals/` — lives at the plugin **root**. A hand-edit to the generated `.claude-plugin/marketplace.json` is reported as drift by the `apm-pack-check-clean` pre-push hook. Plugin-root documentation belongs in `docs/`. That convention is older than the mirror's removal: a hand-written `README.md` placed inside a mirrored directory used to be destroyed by the next sync with no drift report, which cost the repo one document — `plugins/kyberforge/hooks/README.md`, since restored to `plugins/kyberforge/docs/hooks.md`. diff --git a/plugins/bin/.mcp.json b/plugins/bin/.mcp.json deleted file mode 100644 index 7aa9712..0000000 --- a/plugins/bin/.mcp.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "mcpServers": { - "obsidian": { - "args": [ - "@bitbonsai/mcpvault@0.15.0", - "docs/" - ], - "command": "npx", - "type": "stdio" - } - } -} diff --git a/plugins/core/.mcp.json b/plugins/core/.mcp.json deleted file mode 100644 index da39e4f..0000000 --- a/plugins/core/.mcp.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "mcpServers": {} -} diff --git a/plugins/git/.mcp.json b/plugins/git/.mcp.json deleted file mode 100644 index da39e4f..0000000 --- a/plugins/git/.mcp.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "mcpServers": {} -} diff --git a/plugins/gitea/.mcp.json b/plugins/gitea/.mcp.json deleted file mode 100644 index da39e4f..0000000 --- a/plugins/gitea/.mcp.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "mcpServers": {} -} diff --git a/plugins/kyberforge/.mcp.json b/plugins/kyberforge/.mcp.json deleted file mode 100644 index da39e4f..0000000 --- a/plugins/kyberforge/.mcp.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "mcpServers": {} -} diff --git a/plugins/lint/.mcp.json b/plugins/lint/.mcp.json deleted file mode 100644 index da39e4f..0000000 --- a/plugins/lint/.mcp.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "mcpServers": {} -}