Create Plugin

Create plugin

A plugin is a separate Python package whose get_spec() returns a PluginSpec (the same declaration built-in services use) and whose templates render into a project on aegis add <name>. Much of what a plugin contributes needs no wiring: the project finds a module of a known name in every service package on disk.

When to use

Use when the work is a new optional capability shipped outside this repo: an integration (a source for the research service, a scraper), or a service a project opts into by installing a package.

Do NOT use for a capability that ships with the framework itself (use the add-service or add-component skill), or for changing the plugin system in this repo (that is ordinary work in aegis/core/plugins/).

Files that change

In the plugin repository (created by aegis plugins create <name>):

• pyproject.toml: the aegis.plugins entry point, keywords (aegis-stack-plugin lists it in the directory), the aegis-stack floor.
• src/aegis_stack_<name>/plugin.py: get_spec(): required_services / required_components, files=FileManifest(primary=[...]), wiring= only for what a convention module does not cover, migrations= only if it owns tables.
• src/aegis_stack_<name>/templates/{{ project_slug }}/: the files a project receives. Convention modules in app/services/<service>/:
  • models.py (or models/): tables, picked up by the model registry.
  • change_types.py: changes a model proposes and a user approves.
  • scheduled_jobs.py: JOBS, a tuple of ServiceJob (app.core.schedule).
  • tools.py: register_tool(...) calls (app.core.tools), for agents and MCP clients.
  • sources.py: register_source(...) (app.services.research.registry), for a research source.
• src/aegis_stack_<name>/templates/{{ project_slug }}/tests/: the template's tests, which run inside a generated project.
• tests/test_plugin.py: tests that pin the spec.
• README.md, LICENSE.

In this repo, only when a plugin needs a hook no convention covers: the convention's discovery in the template (app/core/discovery.py import_modules_named) and docs/plugins/creating.md's convention table.

Procedure

1. Scaffold: aegis plugins create <name> -d <parent> --author "..." --description "...".
2. Pick the convention modules the plugin needs; prefer them over wiring=, which a project only honours for the hooks PluginWiring declares.
3. Record real third-party responses as fixtures under the template's tests/fixtures/<name>/ before writing any mapping code; build the model from what the API actually returns.
4. Write the template's failing tests first (against the fixtures, with an httpx.MockTransport or a module-level _transport seam, never the network).
5. Write the template modules and declare every owned path in files=FileManifest(primary=[...]).
6. Install the plugin into the aegis environment that renders it: uv pip install -e <plugin>; confirm with aegis plugins list.
7. Generate a project without the plugin's dependencies, run aegis add <name>, and run the template's tests there under the project's gate: uv run pytest <tests> --queryspy-strict --queryspy-baseline .queryspy-baseline.json.
8. Run the plugin for real against the live service once, through the project's CLI or API.
9. Copy back anything the project's make fix reformatted in the rendered files, so the template matches what a project receives.
10. In the plugin repo, make check; then create the repository with the aegis-stack-plugin topic and push. Publishing to PyPI is the separate step in docs/plugins/publishing.md.