Contributing

Shiro’s value is a small set of ownership rules: the engine is long-lived, the runner owns one execution, providers stay thin, and user state stays out of agents. Contributions should preserve that shape.

Before changing code#

1. Name the boundary you are touching (engine, runner, provider, tool, trace, Studio)
2. Decide what new events / spans operators will need
3. Keep vendor-specific code out of @shiro-sdk/core
4. Prefer tests that assert runner-visible behavior over private internals

Good contributions#

• Clearer runtime contracts and types
• Provider adapters and plugins
• Trace exporters
• Studio panels that consume the shared event stream
• Docs examples that compile against public APIs
• Tests for handoff, approval, and validation paths

Review checklist#

• Does the change preserve TypeScript inference for agents / tools / output?
• Does it emit enough trace data to debug a failure?
• Does it avoid coupling core to one vendor?
• Are approvals still explicit runtime events?
• Is there a short docs note if behavior is user-visible?

Documentation#

When you add a concept, answer: what it is, why it exists, when to use it, how it fits, and what to avoid. Skip marketing adjectives. Link related pages.

See Mental Model and Architecture.