Contributing AI agent guide

This guide is for AI agents (Claude, Codex, Gemini, etc.) contributing code to arka-deck via CLI or integrated editor. It gathers the working rules to follow so contributions are clean and safe.

Human contributors can also read it — the rules apply universally.

Base rules

Respect the requested scope. If the task says “modify core/use-cases/projects/”, don’t touch adapters/inbound/web/ui/. If you legitimately need to go beyond, document it first.
Shared worktree. An arka-deck repo in progress may have uncommitted changes from other contributors. Never revert what you did not create. Changes unrelated to your task stay as-is.
Read before writing. Before modifying a file, read its content and context. Code is not interchangeable content — it has history and dependencies.
One PR = one intent. No mixing “refactor + new feature + linter fix”. Split.
No opportunism. No “while I’m here let me clean this file”. The PR scope is defined by the task, not your mood.

Required reading

Before touching code, read:

The architecture: ../architecture/overview
The event bus: ../architecture/event-bus
Relevant ADRs: ../../adr/README.en.md
The touched module (addon sheet or domain reference)

For non-trivial modifications, also read existing tests — they document expected behavior.

Import boundaries

ESLint enforces strict boundaries (ADR 0001):

Source	Forbidden to import
`core/**`	`adapters/`, `composition/`, `addons/`, `providers/`
`core/domain/**`	`core/use-cases/**`
`adapters/inbound/**`	`adapters/outbound/**`
`adapters/**`	`addons/**`

A violation = lint failure = red CI. Don’t try to bypass.

Commit conventions

Conventional commits: <type>(arka-deck): <short description> (docs, feat, fix, refactor, ci, style, chore).
DCO sign-off: git commit -s (adds Signed-off-by:).
Precise description: active verbs, focus on WHY not just WHAT.

Example:

docs(arka-deck): doc refactor — product/dev split, strict bilingual

Refactors docs/ into two distinct entry doors to clarify
PM vs dev contributor audience.

Required tests

For any code modification:

Add or update tests in the touched perimeter.
npm test must pass locally.
For HTTP routes, add a test in adapters/inbound/web/server/src/__tests__/.
For security modifications (URL, secrets), direct unit tests on the policy.

Anti-patterns to avoid

Globally mock `fs` or `node:fs`

❌ Use InMemoryFilesystem injected in deps.

Write to `.claude/settings.json`

❌ arka-deck never mutates .claude/settings.json (Claude Code user settings). See the Materializer pattern.

Reference `.input/`

❌ The .input/ folder is internal (gitignored). Never cite it in a versioned file.

Unfulfilled promises

❌ Don’t write “active third-party marketplace” or “Tauri available” while it’s not true in production. Future promises go in ROADMAP.md.

Log a secret

❌ No logger.info('instance created', instance) if instance can contain a key. Log only the id.

Self-check before submitting

The task is complete (no partial implementation).
Existing tests pass (npm test).
New behaviors are tested.
npm run lint passes.
npm run typecheck passes.
Import boundaries respected (lint).
No .input/ or internal file referenced.
DCO-signed commit (git commit -s).
Clear WHY in the commit description.