@markstanden/opencode-docs-plugin 0.0.0-stage → 0.1.0

package/CONVENTION.md

@@ -0,0 +1,59 @@
+# Knowledge-doc convention
+
+This plugin owns this convention: it is what the `docs` tool's `add` writes,
+what `check` validates, and what the registered `docs` skill teaches. A
+repository that adopts the plugin takes the convention with it.
+
+## Where knowledge lives
+
+Durable knowledge is one Markdown file per topic under `docs/`, grouped by area:
+`docs/<area>/<name>.md`. The excluded areas — never scanned, never validated —
+are `plans/` (scratch, gitignored, deleted when the work lands),
+`requirements/` and `wiki/` (vendored mirrors).
+
+## Front-matter
+
+Every doc opens with a `---` front-matter block. The fields, in canonical order:
+
+| Field        | Required | Meaning                                                                 |
+| ------------ | -------- | ----------------------------------------------------------------------- |
+| `Area`       | yes      | One path segment under `docs/`; the doc's group.                        |
+| `Keywords`   | yes      | Comma-separated search terms; the second half of the doc's identity.    |
+| `Summary`    | yes      | One self-contained sentence: enough to decide whether to open the file. |
+| `Status`     | no       | `active` (the default) or `superseded`.                                 |
+| `Supersedes` | no       | The doc this one replaces.                                              |
+
+`Date` is **derived, never written**: the file's last git commit date, falling
+back to mtime. A hand-maintained `Date` is a finding, not a field.
+
+The tool serialises the front-matter — never copy it by hand.
+
+## Body
+
+- An `H1` title: the first half of the doc's identity.
+- At least one claim section as an `H2`/`H3` heading — `Facts`, `Inferred`,
+  `Tested`, `Open questions` — so a reader knows how much to rely on each claim.
+  Group claims by section rather than mixing them.
+
+## Identity and duplicates
+
+- A doc's identity is its `H1` plus its `Keywords`, and it must carry a term of
+  at least `MIN_TERM_LENGTH` (3) characters. A shorter identity is too weak to
+  search and is rejected.
+- `check` flags **near-twins**: docs in the same area whose identities overlap.
+  `add` refuses a near-twin write and returns the candidates to reconcile
+  against — edit before add, merge near-twins, split a bloated doc into
+  per-topic files.
+
+## Lifecycle
+
+`Status` and `Supersedes` are load-bearing, not decoration. A doc marked
+`Status: superseded` is flagged `(superseded)` in search results and ranks below
+an active doc on a tie; `check` flags a `Supersedes` that names no doc in the
+tree.
+
+## Adopting it
+
+Run `check` to audit an existing tree, and the gate's `defined comply` before
+proposing a commit. A missing `docs/` tree is not an error: the plugin scans
+what is there and reports per-doc findings for what is not.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Standen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,42 @@
-# Temporary Holding Version
+# opencode-docs-plugin
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An [OpenCode](https://opencode.ai) V2 plugin that gives an agent a knowledge
+tree it can actually use: a `docs` tool and a `/docs` command over a
+repository's `docs/**/*.md`, plus the writing convention those docs follow.
+
+- `docs` (tool) — blank search lists the 10 most recently changed docs
+  (`path — Area — date — Summary`); a search ranks docs over their
+  front-matter, path and body identifiers, falling back to the closest
+  matches rather than a dead end; `add` writes knowledge through a typed DTO;
+  `check` validates the tree against the convention.
+- `/docs` (command) — the same core, driven from the prompt:
+  `search <text>` (bare text searches too), `add <text>`, `check`, `help`.
+- The plugin also registers the `docs` skill, so the convention travels with
+  the tool rather than living in always-loaded prose.
+
+Reading a matched doc stays OpenCode's built-in `read`.
+
+## Status
+
+Standalone extract of the docs tooling, under active development.
+
+## Development
+
+```bash
+npm install
+npm test          # node --test
+npm run typecheck
+npm run lint
+defined comply    # the gate: bootstrap, repair and verify
+```
+
+Tests run the plugin source directly under Node's type-stripping (`noEmit`,
+`erasableSyntaxOnly`), so the file OpenCode loads is the file under test.
+
+`tests/fixtures/docs-corpus.json` is a hand-authored synthetic corpus the
+ranking harness pins behaviour against — edit it directly. It holds invented
+paths and summaries only; never snapshot a real docs tree into it.
+
+## Licence
+
+MIT — see [LICENSE](LICENSE).

package/package.json

@@ -1,6 +1,41 @@
 {
-  "name": "@markstanden/opencode-docs-plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@markstanden/opencode-docs-plugin",
+    "version": "0.1.0",
+    "type": "module",
+    "description": "OpenCode V2 plugin: a `docs` tool and `/docs` command over a repository's knowledge tree, with the writing convention it owns",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/markstanden/opencode-docs-plugin.git"
+    },
+    "exports": {
+        ".": "./src/index.ts"
+    },
+    "files": [
+        "src",
+        "CONVENTION.md",
+        "README.md",
+        "LICENSE"
+    ],
+    "engines": {
+        "node": ">=26"
+    },
+    "scripts": {
+        "test": "node --test 'tests/**/*.test.ts'",
+        "test:watch": "node --test --watch 'tests/**/*.test.ts'",
+        "typecheck": "tsc --noEmit",
+        "lint": "eslint ."
+    },
+    "dependencies": {
+        "@opencode/plugin": "2.0.23",
+        "@opencode/schema": "2.0.23",
+        "effect": "4.0.0-rc.112"
+    },
+    "devDependencies": {
+        "@types/node": "^26.6.4",
+        "eslint": "^10.12.0",
+        "eslint-config-prettier": "^10.1.8",
+        "typescript": "^6.0.3",
+        "typescript-eslint": "^8.71.0"
+    },
+    "license": "MIT"
+}

package/src/SKILL.md

@@ -0,0 +1,86 @@
+# Docs
+
+The repository's durable knowledge lives under `docs/`. This skill covers both
+halves of the loop: **find** (discover with the `docs` tool, read the match) and
+**record** (write or update a doc for the current task).
+
+Call the `docs` tool directly at top level. It is a plugin-registered tool and
+is **not** reachable from the `execute` (Code Mode) catalog — do not try to
+batch it inside `execute`, and do not be misled by the unknown-tool suggestion.
+
+## Find it
+
+Call the `docs` tool:
+
+- **blank `search`** — the most recently changed docs, one line per doc
+  (`path — Area — date — Summary`).
+- **a `search`** — those docs ranked over title, path, keywords, body headings
+  and code spans, area and summary. When no doc contains every term it returns
+  the closest matches under a `Closest matches` header rather than a dead end.
+  A term must appear as a **substring** to match — a typo returns nothing, by
+  design. Terms shorter than `MIN_TERM_LENGTH` (3) are ignored unless they are
+  the whole query, so filler words cannot drag in the catalogue. The shared
+  `docs/` path prefix itself is not searched; real path segments still are.
+- **every call** caps at `MAX_RESULTS` (10), preferring the best matches and
+  then the most recent edits, and ends with `… and N more not shown.` when
+  anything was cut.
+- **exactly `help`** — plain text explaining the weights, the hit qualities and
+  the outcomes, instead of a search.
+
+Then open the match with the built-in `read` tool. The tool only discovers; it
+never returns a doc's body. `/docs [search]` runs the same search into the
+session (`/docs search <text>` is the explicit form).
+
+Every `docs/**/*.md` is covered except the excluded areas — scratch (`plans/`)
+and vendored mirrors (`requirements/`, `wiki/`). `Area` comes from the path,
+`date` from git. A doc marked `Status: superseded` carries a `(superseded)`
+marker in results and ranks below an active doc on a tie.
+
+## Read it
+
+- Consult matching docs before a broad grep: they are the curated knowledge.
+- A `Summary` is a self-contained sentence — enough to decide whether to open
+  the file.
+
+## Record it
+
+Write durable findings and task documentation to `docs/<area>/<title>.md` so the
+next human or agent skips the rediscovery. The convention is this plugin's
+`CONVENTION.md`, restated here.
+
+Before writing:
+
+1. **Read first, never duplicate.** List `docs/**` with the `docs` tool and read
+   the docs relevant to the task: the same `docs/<area>/` neighbourhood, keyword
+   hits on the task's entities (service names, file paths, error strings, class
+   names), or links from touched docs.
+2. **Reconcile, then add.** Edit before add; merge near-twins; split a bloated
+   doc into per-topic files; after any split, merge or move, grep for inbound
+   references and repoint them, leaving a stub if needed.
+
+Then record through the `docs` tool's typed `add`: metadata (`Area`, `Keywords`
+as a list, `Summary`; optionally `Status`/`Supersedes`) plus a body carrying an
+`H1` and the claim sections (`Facts`, `Inferred`, `Tested`, `Open questions`).
+The tool serialises the front-matter — never copy it — and derives
+the target (`docs/<Area>/<slug>.md`) when `path` is omitted; pass `path` to
+update an existing doc, replacing its body wholesale. Its guardrails refuse
+blank metadata, path traversal, a body without an `H1`, and a same-area
+near-twin (returning the candidates to reconcile against). A plan for an
+in-flight effort is scratch, not a doc — `docs/plans/PLAN_<effort>.md`,
+gitignored and deleted when the work lands. `/docs add <text>` runs this record
+loop for a fact supplied inline.
+
+## Check it
+
+To audit the tree instead of writing it, call the tool's `check` (`/docs check`
+runs it into the session): it validates every doc against the convention —
+required front-matter, an `H1`, at least one claim section, no hand-maintained
+`Date`, an `H1`+`Keywords` identity with a term of `MIN_TERM_LENGTH` (3) or
+longer, a `Supersedes` naming a doc in the tree, and same-area near-twins — and
+reports findings per doc. An empty report means compliant. `add` enforces the
+same rules at the trust boundary.
+
+Finally, run the repo's gate (`defined comply` where `.defined.json` exists,
+else what its README documents) before proposing a commit. Fix failures; never
+paper over a red gate with a docs commit. Prepare the commit and **wait for
+explicit approval** — recording findings is not commit approval. Never push.