Contributions to protoWorkstacean are welcome. This section covers how to get started, where the key entry points are, and the conventions the codebase follows.

Key entry points

File / Directory	What it is
src/index.ts	Application bootstrap — wires all plugins, starts the HTTP server
src/executor/	Executor layer: IExecutor, ExecutorRegistry, SkillDispatcherPlugin, executor implementations
src/plugins/	Built-in plugins (CeremonyPlugin, AgentFleetHealth, alert/ceremony skill executors)
src/router/	RouterPlugin + SkillResolver + ProjectEnricher
src/agent-runtime/	AgentRuntimePlugin, AgentDefinitionLoader (registers DeepAgentExecutor instances)
src/api/	HTTP route modules (one per concern)
lib/plugins/	Integration plugins (Discord, GitHub, Linear, Google, scheduler, HITL, etc.)
lib/	Shared types (BusMessage, Plugin, EventBus) and utilities
workspace/	Runtime configuration (YAML files, not TypeScript)
test/	Integration tests
__tests__/	Unit tests co-located with source

Where to start for common tasks

Add a new plugin: create the file under src/plugins/ or lib/plugins/, implement Plugin, wire it into src/index.ts. See explanation/plugin-system.md for the interface.

Add a new executor type: implement IExecutor in src/executor/executors/, export it, register it in the appropriate registrar plugin's install().

Change the HTTP API: routes are defined in src/api/. Each module exports createRoutes(ctx). Add the new module to src/api/index.ts.

Add a scheduled task: drop a yaml in workspace/crons/ (generic time-based trigger) or workspace/ceremonies/ (named, observable, can also be on-demand).

Development setup

See development.md for install instructions, running tests, and the test structure.

Code style

• TypeScript strict mode (tsconfig.json has "strict": true)
• No default exports in .ts files — named exports only (exception: _meta.ts files use default export)
• JSDoc comments on public interfaces and complex functions
• Tests use bun:test — describe, test, expect

Pull request expectations

• Every new plugin should have at least a basic install/uninstall test
• New executor types should have a unit test with a mock SkillRequest
• Changes to YAML schemas should update docs/reference/workspace-files.md
• Changes to HTTP endpoints should update docs/reference/http-api.md