diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..611306b
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,50 @@
+# General Working Rules
+
+## Coding
+
+- **Simple and idiomatic.** Write readable, conventional code. Prefer composition, immutability, explicit dependencies, and a single source of truth.
+- **Small and focused.** Keep functions and modules single-purpose. Separate concerns and avoid unnecessary nesting, abstraction, and global mutable state.
+- **Reuse existing solutions.** Follow project conventions and prefer existing tools and dependencies. Introduce new ones only when justified.
+- **Minimal changes.** Implement only what is requested. Prefer deletion over rewriting, and avoid unrelated refactoring, formatting, or speculative features.
+
+## Comments
+
+- **Self-contained.** Explain essential context inline without requiring external documents or conversations. References to nearby source code are acceptable.
+- **Concise.** Usually one sentence. Put longer explanations in brief module headers or documentation.
+- **Why, not what.** Comment only on non-obvious decisions, constraints, invariants, and surprising behavior. Do not restate obvious code.
+- **No unnecessary history.** Include implementation history only when essential to understanding current behavior. Remove obsolete comments.
+
+## Documentation
+
+- Keep documentation concise, accurate, and synchronized with the implementation.
+- Distinguish implemented behavior from proposals and historical plans. Remove outdated information and shorten resolved findings.
+- Update specifications alongside changes to interfaces, formats, and contracts. Record important decisions where they are enforced.
+- **Natural reflow.** Write paragraphs as continuous lines without hard wrapping. Use blank lines between paragraphs and explicit line breaks only where structurally necessary.
+
+## Working Style
+
+- **Inspect first.** Examine existing code, configuration, architecture, and conventions rather than assuming how things work.
+- **Respect scope.** Follow the latest explicit instructions. Do not make unrelated changes or resume superseded tasks.
+- **Work silently.** No progress narration or request recaps. Interrupt only for genuine blockers or discoveries that materially change the approach.
+- **Resolve uncertainty.** Investigate missing information before asking. Never invent requirements or assume unverified behavior.
+- **Respect user decisions.** Identify significant design problems and propose concrete alternatives with trade-offs, but follow the user's choice.
+- **Respect authorization.** Observe approval requirements for changes, tests, commits, deployments, and destructive operations.
+- **Commit messages.** Use concise, single-line, tag-prefixed messages (e.g., fix:, feat:, refactor:, docs:). Describe what changed using the imperative mood.
+- **No credit notes.** Omit attribution, co-author trailers, AI-generated notices, and other credit statements from commits and generated documentation.
+
+## Verification
+
+- Test affected behavior using existing project tools. Add regression tests where appropriate.
+- Preserve safeguards for security, external input, data integrity, and concurrency.
+- Measure consequential assumptions before making architectural decisions.
+- Perform repository-wide cleanup or extensive refactoring only when explicitly requested.
+- Format and validate affected code without altering unrelated files.
+- Report what passed, failed, or could not be verified. Never claim untested behavior works.
+
+## Completion
+
+Summarize changes, verification results, important decisions, and unresolved issues in a few sentences. Avoid lengthy reports unless requested.
+
+## Project Preferences
+
+- use `git` colocated `jj` for version management
\ No newline at end of file