Contributing

Audience: developer who wants to contribute code, documentation, or bug reports to Cortex.

Cortex is the open-source core of the Arka platform. See the full CONTRIBUTING.md in the repository for the canonical reference.

Before you start

Read the Architecture documentation. Cortex is strict about hexagonal layering — domain code must not import from adapters. PRs that violate this will be sent back.
Open an issue first for anything beyond a typo or a clearly localised bug fix. Align on direction before writing code.
One thing per PR. A bug fix and a refactor in the same PR will be asked to be split.

Development setup

git clone https://github.com/arka-labs/arka-cortex.git
cd arka-cortex
cp .env.example .env
docker compose -f docker-compose.example.yml up -d
npm install
npm test

Requirements: Node >= 20, Docker >= 24, ~4 GB free for the local stack.

What we accept

Category	Notes
Bug fixes	Always. Include a regression test.
New ports / adapters	Welcome — must keep domain untouched. Discuss in an issue first.
Performance improvements	Welcome with before/after benchmarks.
Documentation	Welcome. Match the existing tone.
New core features	Discuss in an issue first. The engine should remain small.

What we do not accept

Code that adds a dependency without an issue discussing why.
Features that belong in a downstream product rather than the engine.
Reformatting / style PRs unrelated to a substantive change.
Anything that breaks the public REST / MCP API without a clear migration path documented in the PR.

Coding standards

TypeScript strict mode. No any without an explanatory comment.
One file = one responsibility. Split when a file starts mixing concerns.
Tests next to code in __tests__/ directories. Aim for >= 90% coverage on domain services. Vitest is the runner.
Conventional Commits: feat:, fix:, chore:, docs:, refactor:, test:, perf: — optional scope in parentheses.
No emojis in code or commit messages.
Comments: explain why, not what.

Hexagonal rule (enforced)

domain/        # No import from adapters/. Pure logic.
ports/         # Interfaces. Both inbound (use-cases) and outbound (boundaries).
adapters/      # May import from domain/. Never the reverse.
config/        # Wires adapters into ports at startup.

A pre-commit hook checks this with a static dependency rule. Run npm run lint:arch locally to verify before pushing.

Sending a pull request

Fork, create a branch named feat/short-description or fix/....
Write your change. Add or update tests.
Run npm run check (lint + typecheck + tests + arch rule).
Open the PR against main. Fill in the template.
Be patient. Maintainers review within ~1 week.

By submitting a PR you confirm your contribution is offered under the Apache License 2.0.

Security

Do not open public issues for security vulnerabilities. See SECURITY.md for the responsible disclosure process.

License

Cortex is licensed under Apache 2.0. By contributing, you agree that your contributions will be licensed under the same terms.