feat: evolve plugin as primary install mode with content-aware deployment and cache hygiene

.opencode/opencode-intellisearch.manifest.json

@@ -0,0 +1,45 @@
+{
+  "version": "0.6.0",
+  "files": [
+    {
+      "path": "skills/intellisearch/SKILL.md",
+      "hash": "add0186b3f97ab6b87cec5f403ee50f11902580467c63de5f12bbcc2b42159ca"
+    },
+    {
+      "path": "skills/intellisearch/references/google-search.md",
+      "hash": "7e2512a8fc287a25d73924db5c4eb5a3f8e51fefb4a0bce174a8570e8e58750c"
+    },
+    {
+      "path": "skills/intellisearch/references/workflow.md",
+      "hash": "5ca1b2d917aef3580eb182e0f4d439b825121fad660b2200510b66213986dd76"
+    },
+    {
+      "path": "skills/intellisearch/references/deepwiki-tools.md",
+      "hash": "477a4cf723c416de3a9951d0c52028da8ddb000dfd969197ad33279f0bee0e5d"
+    },
+    {
+      "path": "skills/intellisearch/references/search-workflow.md",
+      "hash": "28b1a88688cd474129ab87785db4df8409fa4431dce1f23f56b4a396af6664b4"
+    },
+    {
+      "path": "skills/intellisearch/references/examples.md",
+      "hash": "c26b76c700cb4d6c9f86b27b94569a128495ac78cf23ce20d173779712ee7411"
+    },
+    {
+      "path": "skills/intellisearch/references/brave-search.md",
+      "hash": "f18136e346eecc4361b86b2814bfe316bf125a7698a58142f60e7826ed5bc118"
+    },
+    {
+      "path": "skills/intellisearch/references/ddg-search.md",
+      "hash": "16c5ac55ce03971be752ff74919d370bc4ed6343d88f402129e7f9a1fefc5a33"
+    },
+    {
+      "path": "skills/intellisearch/references/gh-cli.md",
+      "hash": "c5ef2eb40580aa88541bb20efe6e2e100b44ca02016bdc4d259019feb33b9bf8"
+    },
+    {
+      "path": "commands/search-intelligently.md",
+      "hash": "d3bd05a45e8e8b6ed57b5e2575a8f6daf7e5686dea042acd80f2a4c13c966c65"
+    }
+  ]
+}

AGENTS.md

@@ -43,7 +43,7 @@ When encountering file references (e.g., @references/workflow.md), use Read tool
   </stage>
   <stage name="Package" trigger="cross-project reuse (local file:/// package)">
     - Delegate to `opencode-packager`
-    - Extracts `.opencode/` assets, copies to `assets/`, creates `plugin.ts`, `package.json`, `tsconfig.json`
+    - Extracts `.opencode/` content to package-root `skills/`/`commands/`/`agents/` (no `assets/` wrapper), placed in this workspace (default) or a sibling `../opencode-<name>/` directory; creates `plugin.ts`, `package.json`, `tsconfig.json`
   </stage>
   <stage name="Publish" trigger="public sharing (npm registry)">
     - Delegate to `opencode-publisher`, fed by the packager's output

CHANGELOG.md

@@ -5,6 +5,36 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.8.0] - 2026-10-01
+
+### Added
+
+- Packager deployment-target choice: the packager first establishes the repo root (`git rev-parse --show-toplevel`, never the `.opencode/` directory) and resolves every source and target path from it; a generated package lays down in the current workspace root by default (files merged with consent, structural conflicts routed to `opencode-plugin-engineer`, sibling `../opencode-<name>/` recommended only on explicit request or extensive merges) or in a sibling directory on request
+- Mandatory frontmatter double-quoting (checklist D6): every frontmatter property value in every generated asset — `SKILL.md`, commands, agent definitions — is enclosed in double quotation marks (bare values non-conformant; native booleans/numbers excepted); rule carried in the skills/commands/agents references, the skill-structure template, and the three creator agents
+- Generated packages ship a working CLI surface at packager time: `bin` entry (`<package> → src/cli.ts`), `check`/`test` scripts, `src/installer.ts` + `src/cli.ts` created from templates, `runCli(argv)` export, and an `index.ts` dispatch shim — so every `bunx <package> ...` advisory resolves before any publishing step
+- Promoted-source retirement (checklist D9): after packaging `.opencode/` extensions, the packager establishes a live config reference to the package (surgical `plugin`/`skills.paths` write with consent), triggers and verifies the scope payload, then — with a printed list and explicit user confirmation — removes the promoted originals per item; the end state leaves `.opencode/` holding only the config file plus hook-managed payload and manifests (source `package.json`, lockfile, and `node_modules/` always removed, unrelated extensions untouched), and it never deletes with no reference in place or the whole `.opencode/` directory
+- Packager self-audit gate: before reporting done, the packager verifies the actual tree — exact file inventory (`src/` module split), `plugin.ts` as the thin hook only (monolith pattern is a structural failure), package.json `bin`/`files`/`content`/scripts, single-line byte-for-byte badge row, D6 frontmatter quoting, `bun test` + `bunx tsc --noEmit` green, and the retirement end state — and fixes misses by rebuilding from templates; checklist D7 now fails multi-line or hand-rolled badge rows
+- Generated packages inherit the suite's cache hygiene, self-scoped (checklist A6): the installer template prunes its own `@latest`, `@<version>`, and untagged cache copies on every install (best-effort warn-and-continue, including no-ops); the generated CLI template gains a self-only `clear-cache` subcommand (no `--package`/`--all`); the generated load-time failure advisory suggests `bunx <pkg> clear-cache` instead of manual removal; the conformance checklist, packager, and publisher instructions require generated output to carry it; regression coverage asserts each template behavior
+- `clear-cache` CLI subcommand (manual-only, never invoked at load): with no flags it removes `opencode-architect` and every `opencode-architect@*` copy from OpenCode's package cache (`$XDG_CACHE_HOME/opencode/packages`, falling back to `~/.cache/opencode/packages`). `--package <name>` removes `<name>` and every `<name>@*`; `--all` removes the whole OpenCode cache directory; both broad modes require `--yes`, are mutually exclusive, and unsafe package names (path separators, `..`) are rejected. `--dry-run` lists what any mode would remove without deleting. Idempotent — nothing cached is a success — and removal failures warn without failing the command
+- `install` prunes this package's stale copies from OpenCode's package cache (`$XDG_CACHE_HOME/opencode/packages`, falling back to `~/.cache/opencode/packages`): `opencode-architect`, `opencode-architect@latest`, and `opencode-architect@<installed version>` are removed on every install invocation, including no-ops, so OpenCode re-fetches the just-installed version on next start. Pinned versions and other packages' cache dirs are preserved; removal failures warn without failing the install, and cleared paths are reported
+- Conformance checklist items for the content-based deployment plan (ADR-0008): surgical config writes (B5), zero-write registration no-op (B6), content declaration present and consistent (E1), and binary mode enforcement (E2); E1–E2 and B5–B6 join the hard non-conformance set and the auditor's conformance review covers section E
+- Plugins and config references document the allowed config patterns (including global `config.json`), the repo-root `opencode.jsonc` create-default, and the surgical-writer rule
+
+### Fixed
+
+- `plugin-local.template.txt` read the package version from the parent of the package dir (`${import.meta.dirname}/../package.json`); corrected to the package root, matching plugin.ts's actual location
+
+### Changed
+
+- Packager README badge row is now byte-for-byte the publisher 4b markup: substituting custom badges ("Bun tested", "TypeScript", hand-rolled variants) is explicitly D7 non-conformant
+- **Breaking:** generated packages use package-root content directories — `skills/<name>/`, `commands/`, `agents/` sit at the package root with no `assets/` intermediary (`ASSET_LAYOUT_DIR = "."`), aligning generated repos with skills.sh-style root-`skills/` scanners; legacy `assets/`-wrapper packages remain recognized by the installer, checklist, auditor, and publisher
+- Generated `package.json` `files` lists the shipped content directories (`skills`, `commands`, plus `agents`/`plugins`/`tools`/`src` as present) instead of `assets`
+- **Breaking:** `install` is now a registration manager (plugin install is the only mode for this code-backed package, per [ADR-0008](docs/adr/0008-content-based-deployment-plans.md), superseding ADR-0004): the CLI ensures the `plugin` entry in the target scope's config file via the surgical editor — comments and formatting preserved, unparseable configs abort untouched — and writes a generalized manifest (version, mode, plugin entry, target config file) at the scope base. A matching manifest with the entry present is a zero-write no-op. `--mode copy` is refused with an explanatory error; `--force` now re-registers and rewrites the manifest instead of removing the entry
+- Legacy copy installs migrate automatically on install: the old manifest's file list is removed exactly, with a printed notice, before the plugin entry is added
+- `uninstall` surgically removes the plugin entry (config formatting preserved) plus the manifest and any residual copy payload — manifest-gated, or a known-filenames sweep of `agents/` and `opencode-architect/` when no manifest exists; `status` reports mode, version, and the config file holding the registration
+- Generalized manifest schema covers copy mode too, with a single `content-hash` property (folder-hash) for copy-installed payloads
+- Nothing changes at runtime: the plugin already registers the agents from the package and resolves reference paths at load
+
 ## [0.7.1] - 2026-09-21
 
 ### Fixed

CONTEXT.md

@@ -123,6 +123,11 @@ The install mechanism a package's content dictates, declared in the
 package's package.json: assets-only packages copy-install by default with
 plugin install as the opt-in; code-backed packages always plugin-install.
 
+**Content declaration**:
+The `"content"` field (`assets` or `code`) in a generated package's
+package.json, derived by the packager from its asset inventory and verified
+by the publisher. It is how installers read the deployment plan.
+
 **Plugin install**:
 The mode where the package is listed in a config file's `plugin` array and
 everything registers from the package at load time; the CLI copies nothing.
@@ -135,6 +140,19 @@ and commands) into the scope base, leaving visible, editable files. The
 default install for assets-only packages; mutually exclusive with plugin
 install in the same scope.
 
+**Skills market**:
+The `npx skills add` consumption channel and its skills.sh listing. Two
+distinct requirements compose market compatibility. **Discoverability**: the
+package's skills sit at a market-findable file layout — the market tool scans
+the package for directories containing a frontmatter-valid `SKILL.md`, with
+`skills/<name>/` the canonical container — a property of the produced
+package's structure regardless of install mode. **Install parity**: the copy
+install default for assets-only packages leaves skills as visible, editable
+files, matching the kind of end state the market tool produces. Code-backed
+packages keep discoverability but lose install parity, which is why skill
+collections split into assets-only packages.
+_Avoid_: skills.sh (the listing site, not the channel)
+
 **Payload**:
 What a copy install places in the consumer's project: the package's skills
 and commands.

README.md

@@ -24,13 +24,13 @@ The plugin registers the full agent suite at startup, with self-contained bundle
 
 ### Option 2 — Install with the CLI (bunx or npx)
 
-Copy the agents, references, and templates straight into your OpenCode directories, where you can read and modify every file:
+The CLI registers the package as a plugin: it adds `opencode-architect` to the `plugin` array of your OpenCode config with surgical text editing (comments and formatting elsewhere in the file are preserved), then records the registration in an `opencode-architect.json` manifest at the scope base. Nothing is copied — the agents, references, and templates all load from the package at startup.
 
 ```bash
-# Project scope (default): copies into ./.opencode/
+# Project scope (default): edits the ./.opencode/ or repo-root config
 bunx opencode-architect install
 
-# Global scope: copies into ~/.config/opencode/
+# Global scope: edits the XDG/home config, creating opencode.jsonc if absent
 bunx opencode-architect install --scope global
 ```
 
@@ -39,15 +39,22 @@ bunx opencode-architect install --scope global
 Useful flags and commands:
 
 ```bash
-bunx opencode-architect status                  # show install mode and version for a scope
-bunx opencode-architect uninstall               # remove exactly the files a copy install wrote
-bunx opencode-architect install --force         # overwrite locally modified files, switch a scope from plugin to copy install
+bunx opencode-architect status                  # show mode, version, and the config file holding the entry
+bunx opencode-architect uninstall               # remove the plugin entry, the manifest, and any residual payload
+bunx opencode-architect clear-cache             # remove cached copies of this package from OpenCode's package cache
+bunx opencode-architect clear-cache --all --yes # remove the whole OpenCode cache directory (destructive)
+bunx opencode-architect clear-cache --dry-run   # preview what clear-cache would remove without deleting
+bunx opencode-architect install --force         # re-register and rewrite the manifest even when up to date
 bunx opencode-architect --help                  # full usage
 ```
 
-A copy install writes 10 agents into `agents/`, 9 reference docs into `opencode-architect/references/`, and 9 starter templates into `opencode-architect/templates/` of the scope base, plus an `opencode-architect.json` manifest that tracks versions and file hashes for safe upgrades. Relative reference paths inside agents are rewritten to absolute paths at install time.
+Re-running install when the manifest matches reality is a zero-write no-op. `--mode copy` is refused with an explanatory error: this package is code-backed (it ships agents), and copying cannot express plugin registration.
 
-Plugin install and copy install are mutually exclusive per scope — the CLI refuses to copy over an existing plugin entry unless you pass `--force`.
+Every install — including a no-op — also clears this package's stale copies from OpenCode's package cache (`$XDG_CACHE_HOME/opencode/packages`, falling back to `~/.cache/opencode/packages`): `opencode-architect`, `opencode-architect@latest`, and `opencode-architect@<installed version>`. Pinned copies like `opencode-architect@0.6.0` and other packages' cache dirs are left untouched. This makes OpenCode re-fetch the just-installed version on next start instead of reusing a stale or partial extraction. Removal is best-effort: a failure prints a warning but the install still succeeds.
+
+**Upgrading from a copy install (pre-0.8):** if a previous version copied agents into your scope base, install detects the old manifest, removes exactly the files it lists, prints a notice, and switches the scope to plugin registration in one step. Locally modified files are tracked by hash; uninstall and migration only remove what the manifest recorded.
+
+`clear-cache` is a manual-only command (never invoked at load time) for removing cached copies from OpenCode's package cache (`$XDG_CACHE_HOME/opencode/packages`, falling back to `~/.cache/opencode/packages`). With no flags it removes `opencode-architect` and every `opencode-architect@*` copy. `--package <name>` removes `<name>` and every `<name>@*`; `--all` removes the whole OpenCode cache directory (`$XDG_CACHE_HOME/opencode`, falling back to `~/.cache/opencode`). `--dry-run` lists what any mode would remove without deleting anything, and previews broad modes without `--yes`. Both broad modes require `--yes` to confirm, are mutually exclusive, and package names containing path separators or `..` are rejected. The command is idempotent — running with nothing cached succeeds — and removal failures warn without changing the exit code.
 
 ## What you get: ten specialist OpenCode agents
 

assets/agents/opencode-agent-designer.md

@@ -18,7 +18,7 @@ You create or refine OpenCode agents in `.opencode/agents/` as Markdown with YAM
 
 1. Read `../references/prompt-engineering.md` for prompt-engineering techniques before drafting anything.
 2. Consult `../references/agents.md` for agent fields, modes, tools, and permissions; `../references/tools.md` for tool IDs and behavior; `../references/config.md` for config precedence and defaults.
-3. Write the frontmatter: description (required), mode (primary or subagent - set it explicitly), model (only when the user names one), temperature, maxSteps, tools, permission, hidden, as needed.
+3. Write the frontmatter: description (required), mode (primary or subagent - set it explicitly), model (only when the user names one), temperature, maxSteps, tools, permission, hidden, as needed. Every frontmatter property value is enclosed in double quotation marks (checklist D6) — `mode: "subagent"`, never `mode: subagent` — except values the schema requires as native booleans or numbers.
 4. Write the prompt in this order: role and scope boundaries first, then expected inputs and output format, then direct, specific instructions.
 5. Reinforce the instructions where they fit: structure with headings and lists, critical instructions at the end, examples for ambiguous tasks and output formats, explicit constraints, structured outputs (JSON, XML) where precise parsing is needed, reasoning prompts for multi-step tasks, persistent context and persona for primary agents.
 6. Scope capability to the job: tools block enables or disables specific tools, permission gates edit, bash, or webfetch, permission.task limits which subagents run, and the prompt scans no wider than the job requires.

assets/agents/opencode-architect.md

@@ -61,7 +61,7 @@ After the user creates or updates an extension, or finishes an extraction, sugge
 Run one stage at a time, returning to the user between stages so they review and decide each step:
 
 1. Optionally first, delegate to opencode-extension-auditor for an inventory of `.opencode/` - informed packaging guidance.
-2. Delegate to opencode-packager: "Package extensions from [source path or .opencode/] for local sharing. Target directory: ./opencode-[extension-name]/. Return: summary of created files, included assets, dependencies, and any issues." When the source includes skills, commands, or static assets, list each in the prompt (skill asset files, command files, XML templates or docs) plus the intended package name opencode-{extension-name}.
+2. Delegate to opencode-packager: "Package extensions from [source path or .opencode/] for local sharing. Deployment target: this workspace root by default — lay the package tree (skills/, commands/, agents/, plugin.ts, package.json) at the repo root (git rev-parse --show-toplevel; never relative to .opencode/) — or a sibling directory ../opencode-[extension-name]/ when the user asks or the root already holds a package.json/plugin.ts with extensive merge conflicts. Return: summary of created files, included assets, dependencies, and any issues." When the source includes skills, commands, or static assets, list each in the prompt (skill asset files, command files, XML templates or docs) plus the intended package name opencode-{extension-name}.
 3. Check the packager summary against the package checklist below.
 4. Ask the user about publishing, showing local use: add "file:///path/to/opencode-[name]" to the plugins array in opencode.json.
 5. On yes, delegate to opencode-publisher: "Transform the locally-packaged extension at ./opencode-[name]/ for npm publishing" plus the packager summary and the publisher tasks: extract install logic to src/installer.ts, create src/cli.ts for bunx, expand package.json for npm, verify npm authentication, publish, generate consumer installation instructions.