crank/AGENTS.md

AGENTS

Purpose

This repository is developed through agent-assisted workflow. Follow the repository documents first, then implement code.

Source of truth

Use the documents in this order when there is ambiguity:

1. docs/architecture.md
2. docs/module-decomposition.md
3. docs/data-model.md
4. docs/database-schema.md
5. docs/admin-api.md
6. docs/mcp-interface.md
7. docs/rust-design.md
8. docs/development-rules.md
9. docs/rust-code-rules.md
10. docs/implementation-plan.md
11. docs/product-editions.md
12. docs/commercial-boundaries.md
13. docs/frontend-roadmap.md
14. docs/refactoring-roadmap.md

If code and docs diverge, update docs first or together with code.

Workflow

• Follow Red -> Green -> Refactor -> Commit.
• Backend changes follow TDD strictly. Frontend layout, copy, and UX cleanup do not require strict TDD, but working frontend behavior should still be verified before commit.
• Large features use their own branch: feat/<feature-name>.
• Commits must be atomic.
• Push periodically after one or more logically complete RGR + commit cycles.
• Do not wait for the whole feature to be finished before pushing.
• Delete merged feature branches both locally and in origin.
• During the current refactoring and small-fix phase, changes are merged directly into main on GitHub without opening PRs by default.

Language rules

• Commit messages must be in English.
• Code identifiers must be in English.
• Code comments are avoided by default.
• If a code comment is truly unavoidable, it must be in English.

Code rules

• Prefer self-documenting code.
• Keep domain logic separate from storage, transport, and orchestration.
• Do not create god-structs or giant services.
• Keep pub surface minimal.
• Avoid unwrap, expect, todo, dbg, and panic in production code.
• unsafe is forbidden by default.

Commands

Use the canonical commands from justfile:

• just fmt
• just fmt-check
• just check
• just clippy
• just test
• just verify

Current execution mode

• Build the Rust workspace first.
• Keep the UI as a separate app outside the Cargo workspace.
• Implement one vertical slice at a time.

Task tracking

• Check TASKS.md before starting a new piece of work.
• Update TASKS.md when a task starts, finishes, or gets blocked.