Conventions

Start with the repository-wide CONTRIBUTING guide for contribution routes, setup, pull request expectations, and licensing. Before editing, read the root CLAUDE.md, the nearest package guide, and every .claude/rules/*.md file whose path scope matches your change.

1. Choose the smallest extension point

Use a Skill for guidance, domain knowledge, or a repeatable workflow built from existing tools. Add a Tool for deterministic processing, authentication, binary or streaming data, or a new execution boundary. Shared types and UI belong in the matching package; app-specific behavior stays in that app.

Do not add MCP plumbing for a capability that belongs in Minara's in-house tool registry.

2. Keep secrets outside prompts and source code

Read credentials from process.env at factory time. Add the declaration to the typed env-docs source and regenerate .env.example plus the public env reference. A skill declares metadata.minara.requires_env; a tool factory returns [] when an optional provider credential is absent.

Never hard-code secrets or accept them as LLM-visible tool arguments. Never include real credentials in tests, fixtures, screenshots, or logs.

3. Preserve safety boundaries

Filesystem tools resolve paths through apps/agent/src/tools/_security/sandbox.ts. Subprocess tools use the existing command guard and OS jail. Do not create parallel helpers that bypass these boundaries.

Every fund-moving tool declares isFundMoving: true and a controlPolicy.confirm preview. The shared tier gate owns confirmation; the handler executes only an already-authorized request. Match the closest existing tool and read the fund-moving rule before changing this surface.

4. Keep TypeScript ESM-compatible

Relative imports use .js extensions in TypeScript source, and type-only imports use import type.

import { createThing } from "./thing.js";
import type { ToolEntry } from "../core/tool-registry.js";

5. Copy Skill IDs from their source

Skill IDs contain historical mixtures of dots, hyphens, and underscores. Never derive an ID from a directory name. Copy metadata.minara.id from the live SKILL.md package.

rg "id:" apps/agent/src/skills/builtin/*/SKILL.md

The builtin loader scans only direct subdirectories of builtin/. Add or remove the ID in apps/agent/tests/unit/skills/builtin-catalog-guard.test.ts with the package change.

6. Keep public contracts and docs in sync

A changed HTTP route updates the route specification and generated API/OpenAPI outputs. A changed CLI or REPL command updates the matching page under reference/cli/. New tools update their tool-set membership and regenerate the tool reference.

REPL commands with missing required arguments guide the user interactively instead of returning a bare usage error. Command names stay flat and hyphenated, such as /agent-run.

Hand-written public docs ship in English, Chinese, Japanese, and Korean. Update all four siblings together. Use locale-relative internal links such as /docs/features/portfolio.

7. Test at the right boundary

Start with a unit test. Use integration tests for SQLite, CLI, gateway, or real local component boundaries. Use E2E tests for complete user flows. Tests must run without production credentials and must isolate local state.

Run the focused test first, then typecheck and the broader affected suite. Do not leave test.only or unstable timing assumptions in a pull request.

8. Respect provenance and licenses

Only submit code, data, prompts, and media you have the right to license under the project terms. Preserve required notices. Treat unknown or missing third-party licenses as blocked until verified.

Do not submit proprietary Minara.AI assets, user trading data, model weights, or generated content whose source and rights you cannot explain.

Keep the change focused

• Do not mix a feature with unrelated cleanup.
• Do not add MCP plumbing for a capability that belongs in the in-house tool registry.
• Do not hard-code secrets or accept them as LLM-visible tool arguments.
• Do not introduce an abstraction without a concrete repeated need.
• Do not write comments that only narrate the code.
• Do not add error handling for conditions that cannot occur.
• Do not add Python to this Node repository.
• Do not commit .env, .minara/, sandbox/, dist/, or local database files.
• Do not add non-OSS content to apps/agent/src/skills/external/.
• Do not edit generated documentation by hand; change its source and regenerate it.