1 files changed, 84 insertions, 0 deletions
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..4958740
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,84 @@
+# Omni
+
+The Omni project is to leverage automation and asymmetries to create wealth.
+
+## Critical Rules for AI Agents
+
+**CRITICAL**: This project uses `jr task` for ALL issue tracking. You MUST follow these rules:
+
+- ✅ Use `jr task` for ALL task/TODO tracking (`jr task create ... --json`)
+- ✅ Link discovered work with `--discovered-from=<parent-id>`
+- ✅ File bugs IMMEDIATELY when you discover unexpected behavior
+- ✅ Add facts to the knowledge base when you learn something useful (`jr facts add ...`)
+- ✅ Run `jr task ready --json` before asking "what should I work on?"
+- ❌ Do NOT create markdown TODO lists or task checklists
+- ❌ Do NOT put TODO/FIXME comments in code
+
+## Cheat Sheet
+
+**Standard workflow:**
+```bash
+# 1. Find ready work
+jr task ready --json
+
+# 2. Claim a task
+jr task update <id> in-progress --json
+
+# 3. During work: create discovered issues
+jr task create "Fix type error found" --discovered-from=<current-id> --json
+
+# 4. Complete the task
+jr task update <id> done --json
+```
+
+**Bug Discovery:**
+```bash
+# Create a task immediately
+jr task create "Command X fails when Y" --discovered-from=<current-task-id> --json
+```
+
+## Directory Structure
+
+- **`_/`** (cabdir) - All ephemeral/generated files. This directory is gitignored.
+  - `_/tmp/` - Temporary files, test databases, scratch data
+- Never create dotfile directories (like `.tasks/`) in the repo root
+
+## Python Conventions
+
+- **Imports**: Use `import X as Y` pattern only. Do NOT use `from X import Y` because `bild` only detects the former.
+- **Module naming**: If you have both `Foo.py` and `Foo/` directory, the build system gets confused. Rename `Foo.py` to `Foo/Core.py` and update imports accordingly.
+
+## Common Commands
+
+**Build:**
+```bash
+bild Omni/Jr.hs              # Build a Haskell namespace
+bild Biz/Cloud/Api.py        # Build a Python namespace
+```
+
+**Lint and Format:**
+```bash
+lint Omni/Cli.hs             # Lint a file (DO NOT use hlint directly)
+lint --fix **/*.py           # Lint and auto-fix Python files
+```
+
+**Type Check:**
+```bash
+typecheck.sh Omni/Bild/Example.py   # Run mypy on Python files
+```
+
+**Test:**
+```bash
+bild --test Omni/Jr.hs       # Build and run tests for a namespace
+```
+
+**Run:**
+```bash
+Omni/Ide/run.sh Omni/Jr.hs   # Build (if needed) and run
+```
+
+## Documentation
+
+- **Project Context**: [README.md](README.md) - Goals, source layout, and coding conventions.
+- **Build Tool (Bild)**: [`Omni/Bild/README.md`](Omni/Bild/README.md) - How to use `bild` and manage dependencies.
+- **Development Tools**: [`Omni/Ide/README.md`](Omni/Ide/README.md) - `run.sh`, `lint`, `repl.sh`, git workflow.