Plugin template¶
horae-dev/template-plugin is a GitHub
template repository for a new Horae plugin written with horae-sdk.
"Use this template" gives a repository whose CI passes unchanged; you then rename the example
with scripts/rename.py (its CI still passes) and write your own tools.
What it holds¶
- An example plugin (
src/example_plugin/): an MCP stdio server with one source,example.inbox, that proposes atask.createper message. The message subject is untrusted and reaches the title only throughintents.task_create, which escapes it for Obsidian Tasks (threat model T02, schemas decision 50). The service client is aProtocol: the plugin ships with a stand-in, the tests use a fake one with synthetic data. plugin.yaml, written bypython -m example_plugin --manifestand checked in a test by the SDK's manifest helpers (horae_sdk.manifest), both as written on disk and against the code's registered tools andPermissions. It declares only thetask.createintent.- Recorded-input tests:
tests/recordings/*.jsonreplayed through MCP withhorae_sdk.testing.replay_all(including a hostile subject), and a test that starts the plugin over stdio as the plugin host does. - CI (
.github/workflows/ci.yml):uv lock --check, ruff, mypy strict, pytest with an 85% coverage gate, gitleaks over the full history, and an aggregate CI OK check; actions pinned by commit,permissions: contents: read, no persisted credentials. In the template repository only, a Template copy jobgit archives the commit into a fresh repository, renames it withscripts/rename.pyand runs the same checks on the copy, so a renamed repository is known to pass; downstream copies skip it and CI OK counts that skip as a pass. scripts/rename.py <dist-name> <package> <plugin-name>(standard library only): renames the package and every reference to the example (distribution name, imports, the plugin'sNAME, which namespaces its refs and fingerprints, the recordings, docstrings, titles), runsuv lock, regeneratesplugin.yaml, re-records the recordings outside CI and fails if a reference is left.graft.yamlandAGENTS.md: the same review policy and working rules as the core (plugin.yaml, workflows,auth/,pyproject.toml,uv.lock,.pre-commit-config.yamlandrenovate.jsonare sensitive), plus.pre-commit-config.yaml(ruff, gitleaks),renovate.json(7-day minimum release age) and a pull request template.
Using it¶
The template's README has
the steps: create the repository, run scripts/rename.py (the README also lists the manual
rename, which must include uv lock and re-recording), write the tools and their
permissions, regenerate plugin.yaml, record fixtures (HORAE_SDK_RECORD=1 uv run pytest,
refused in CI) and run the CI commands locally.
Commits carry Graft trailers (git commit --trailer ...). Work done in one repository for an
issue of another, such as this page for a template issue, writes the task as
Graft-Task: <owner>/<repo>#<n> (for example horae-dev/template-plugin#2) rather than #<n>.
horae-sdk before PyPI¶
Until horae-sdk is published, the template takes it from this repository's main branch
in [tool.uv.sources] (branch = "main", subdirectory = "sdk"), and its uv.lock pins the
exact commit, so CI's uv lock --check and every install use the same SDK until the lock
changes. Renovate's weekly lock file maintenance moves the lock to the latest main (a git
commit has no release date, so the 7-day age cannot apply: review that pull request like any
dependency bump). Installing from git clones this repository, so it must stay public. After
the first Release SDK run (sdk-v<version> tag), remove the git source from the template so
the requirement resolves from PyPI.
Nothing here checks the template against an SDK change yet: before changing the SDK's public
API, run the template's tests against it by hand (in a template checkout, point
[tool.uv.sources] at the branch with the change, uv lock, then uv run pytest). A follow-up should add a core CI job that does this on every SDK change.