Pynchy Plugin Authoring

Pynchy Plugin Authoring

When To Use

Use this skill when the user asks to:

• Create a new pynchy plugin
• Add a new hook to an existing plugin
• Register/enable plugins in config.toml
• Validate plugin discovery and runtime behavior

Core Rules

1. Keep plugin responsibilities narrow. One plugin can implement multiple hooks, but avoid unrelated concerns in one package.
2. In the plugin repository pyproject.toml (not pynchy/pyproject.toml), define entry points under [project.entry-points."pynchy"].
3. For host runtime/channel code, treat plugin code as high trust and avoid risky side effects in import-time code.
4. For plugin docs, cross-link to pynchy/docs/plugins/* instead of duplicating long explanations.
5. Refer to the quickstart guide for the recommended plugin directory structure.
6. Plugin config models belong in the plugin. Define Pydantic config models inside the plugin's own source file, not in pynchy/src/pynchy/config/models.py. The core config/models.py is for pynchy core settings only.

File Scope Conventions

When this skill mentions config files, use this mapping:

• Host app config: config.toml ([plugins.<name>] entries enable repos)
• Host app package metadata: pyproject.toml
• Plugin package metadata: <plugin-repo>/pyproject.toml (entry points live here)
• Plugin source: <plugin-repo>/src/<plugin_module>/...

Authoring Workflow

Copy this checklist and complete it in order:

Plugin Authoring Checklist
- [ ] Choose plugin scope and hook categories
- [ ] Create plugin directory structure (or update existing plugin)
- [ ] Implement hook methods and runtime logic
- [ ] Add/update tests
- [ ] Configure local pynchy [plugins.<name>] entry
- [ ] Run tests and smoke checks
- [ ] Update docs if behavior is user-visible

Hook Map

• pynchy_create_channel: Host-side channel instance
• pynchy_speech_synthesizer: Shared speech output provider
• pynchy_service_handler: Typed host actions (IPC dispatch)
• pynchy_computer_use_backend: Computer-use provider
• pynchy_action_specs: Semantic action contracts
• pynchy_skill_paths: Skill directories mounted into container
• pynchy_agent_core_info: Agent core implementation metadata
• pynchy_agent_hook_specs: Trusted agent lifecycle hook modules
• pynchy_container_runtime: Host container runtime provider
• pynchy_tunnel: Host tunnel provider
• pynchy_connection_runtime: Long-lived authenticated connection runtime
• pynchy_observer: Host event observer
• pynchy_webhook_routes: Authenticated webhook routes
• pynchy_mcp_server_spec: MCP server template
• pynchy_workspace_spec: Managed workspace definitions
• pynchy_job_specs: Config-backed jobs