Skip to content
Cinatra Docs

Contributing to Cinatra

Thanks for your interest. Cinatra is an open-source collaborative intelligence platform, and external contributions — bug reports, agent packages, connectors, documentation, code — are welcome.

This document covers how to contribute. For the developer setup itself, see Installation.

Ways to contribute

Section titled “Ways to contribute”

Reporting bugs

Section titled “Reporting bugs”

Open a GitHub issue with:

  • What you expected to happen
  • What actually happened
  • The minimum reproduction (steps, sample input, environment)
  • Versions: Node, pnpm, Docker, and the commit hash of the Cinatra working tree

For security issues, do not open a public issue. See Security for the private disclosure path.

Proposing features

Section titled “Proposing features”

Open a GitHub issue with the use case first. Explain the user problem and the shape of the solution; we will discuss the design before any implementation. Large feature work without prior alignment tends to require significant rework.

Submitting code

Section titled “Submitting code”

Pull requests are welcome. Before working on a PR:

  • For a bug fix: open an issue first only if the bug is non-obvious or you need clarification.
  • For a feature or refactor: open an issue or discussion first. We will agree on the approach before you invest time.

PRs should:

  • Pass pnpm typecheck and pnpm lint cleanly.
  • Touch the smallest surface that achieves the goal. Bundle related changes; do not bundle unrelated changes.
  • Update or add documentation when the change affects what an external user sees.
  • Include tests when the change touches code that already has tests in its directory.

Adding an agent package

Section titled “Adding an agent package”

Cinatra is designed to host third-party agent packages. To publish one:

  1. Author the agent as an OAS Flow file under agents/<vendor>/<slug>/cinatra/oas.json.
  2. Add a package.json with your namespace, version, and Cinatra metadata.
  3. Test locally by installing into your dev instance.
  4. Publish to the hosted public registry (or your private one). See Building packages and Developing agents for the authoring conventions.

Agent packages do not need to live in this repository — the platform installs from any compatible npm-style registry. Contributing a package to this repository is the right move only if it is broadly useful and you are willing to maintain it.

Working on the codebase

Section titled “Working on the codebase”

Setup

Section titled “Setup”

See Installation.

After the platform is running, verify the toolchain:

Terminal window
pnpm typecheck      # fast type check via tsgo
pnpm lint           # ESLint
pnpm build          # production build

Code style

Section titled “Code style”

The codebase follows the conventions documented in AGENTS.md at the repository root. Highlights:

  • TypeScript first. Strict mode is on (noImplicitAny: false). Always use import type for type-only imports.
  • Kebab-case file names. PascalCase types and components; camelCase functions and variables.
  • Packages communicate through capability surfaces, not by importing each other’s internals. If you need functionality from another package, call its MCP primitives through the deterministic client.
  • Server actions live next to the surface that uses them. Never split a server action into a separate package just to “share” it; if it is shared, expose it through an MCP primitive.
  • UI uses shadcn/ui components. Do not introduce raw HTML elements where a shadcn component exists. Do not hardcode Tailwind palette colors — use semantic tokens.

Page layout

Section titled “Page layout”

Every full-page screen wraps in the standard three-component shell (Main, PageHeader, PageContent). Do not bypass this with raw <div> wrappers; the layout primitives enforce visual consistency across the platform.

Tests

Section titled “Tests”

Each package owns its tests in __tests__/ or tests/ subdirectories. Run them with pnpm --filter <package> test.

There is no global test runner currently — tests are package-local.

Commits

Section titled “Commits”
  • Commit messages describe the why, not just the what.
  • Atomic commits are preferred over large bundles.
  • Branch off main. The default branch protection requires linear history.

Pull requests

Section titled “Pull requests”

PR titles should be short and descriptive. PR bodies should include:

  • Summary — what changed and why
  • Testing — what you did to verify it works
  • Screenshots — for UI changes, before and after

Avoid merging your own PRs without review. Wait for a maintainer.

Communication

Section titled “Communication”
  • GitHub issues for bugs, feature requests, and design discussions
  • GitHub discussions (when enabled on the repo) for open-ended questions
  • Pull requests for code changes
  • Email for private security disclosure (Security)

We aim to triage issues and PRs within a few business days. If something has been quiet for over a week, a polite ping is welcome.

License

Section titled “License”

Cinatra is licensed under the Apache License 2.0 — see the LICENSE file at the repository root. By contributing, you agree that your contributions will be licensed under those same terms.