path: root/AGENTS.md

# Omni

The Omni project is to leverage automation and asymmetries to create wealth. The
target of the wealth is Bitcoin. The means: write everything down, first
in English, then in code.

This document describes how AI agents should interact with this repo, the "omnirepo".

## Important Rules for AI Agents

**CRITICAL**: This project uses `task` for ALL issue tracking. You MUST follow these rules:

- ✅ Use `task` for ALL task/TODO tracking
- ✅ Always use `--json` flag for programmatic operations
- ✅ Link discovered work with `--discovered-from=<parent-id>`
- ✅ File bugs IMMEDIATELY when you discover unexpected behavior
- ✅ Run `task ready` before asking "what should I work on?"
- ✅ Store AI planning docs in `_/llm` directory (NEVER in repo root)
- ✅ Run `task sync` at end of session to commit changes locally
- ❌ Do NOT use `todo_write` tool
- ❌ Do NOT create markdown TODO lists or task checklists
- ❌ Do NOT put TODO/FIXME comments in code
- ❌ Do NOT use external issue trackers
- ❌ Do NOT duplicate tracking systems
- ❌ Do NOT clutter repo root with planning documents

### Session Checklist

**First time in this repo?**
```bash
task init --quiet  # Non-interactive initialization
```

**Standard workflow:**
```bash
# 1. Find ready work
task ready --json

# 2. Claim a task
task update <id> in-progress --json

# 3. During work: create discovered issues
task create "Fix type error found" --discovered-from=<current-id> --json

# 4. Complete the task
task update <id> done --json

# 5. End of session: sync to git (local commit only)
task sync
```

### Bug Discovery Pattern

**When you discover a bug or unexpected behavior:**
```bash
# CORRECT: Immediately file a task
task create "Command X fails when Y" --discovered-from=<current-task-id> --json

# WRONG: Ignoring it and moving on
# WRONG: Leaving a TODO comment
# WRONG: Mentioning it but not filing a task
```

**Examples of bugs you MUST file:**
- "Expected `--flag value` to work but only `--flag=value` works"
- "Documentation says X but actual behavior is Y"
- "Combining two flags causes parsing error"
- "Feature is missing that would be useful"

### Forbidden Patterns

**Markdown checklist (NEVER do this):**
```markdown
❌ Wrong:
- [ ] Refactor auth module
- [ ] Add tests
- [ ] Update docs

✅ Correct:
task create "Refactor auth module" -p 2 --json
task create "Add tests for auth" -p 2 --json
task create "Update auth docs" -p 3 --json
```

**todo_write tool (NEVER do this):**
```
❌ Wrong: todo_write({todos: [{content: "Fix bug", ...}]})
✅ Correct: task create "Fix bug in parser" -p 1 --json
```

**Inline code comments (NEVER do this):**
```python
❌ Wrong:
# TODO: write tests for this function
# FIXME: handle edge case

✅ Correct:
# Create task instead:
task create "Write tests for parse_config" -p 2 --namespace="Omni/Config" --json
task create "Handle edge case in parser" -p 1 --discovered-from=<current-id> --json
```

## About Omnirepo

Resources defined in the repo can be used to quickly create and release
products. New technology shall be prototyped and developed as needed.

### Source Layout

The source tree maps to the module namespace, and roughly follows the Haskell
namespace hierarchy. This is true of all languages: Python, Scheme, Rust, C,
etc.

Namespaces are formatted either as file paths, like `Omni/Dev`, or
dot-separated, like `Omni.Dev`. Parts of the namespace should always be
capitalized.

The namespace for all products that we own is `Biz`, this includes proprietary
applications, products, and related infrastructure.

The `Omni` namespace is used for internal development tooling and infrastructure
that are shared between all other projects.

Stuff that can be open sourced or otherwise externalized should be outside of
`Biz` or `Omni`.

Related code should be kept close together. This means that you should start
with small namespaces: use `Omni/Thing.hs` before `Omni/Thing/Service.hs`. Try
to keep all related code in one spot for as long as possible.

Re-use code from the `Omni/` namespace as much as possible. For example, use
`Omni/Cli.hs` or `Omni/Test.py` instead of trying to roll your own code for cli
parsing or running test suites. If the the namespace doesn't have the feature
you need, then add the feature.

Boundaries and interfaces between namespaces should be singular and
well-defined. Likewise, the functionality and purpose of a particular
namespace should be singular and well-defined. Follow the unix principle
of "do one thing and do it well."

Namespaces are always capitalized. In Scheme and Python this actually translates
quite well and helps distinguish between types/classes/modules and values.

## Coding Conventions

1. **Test interface**: Every program must accept `test` as a first argument to run its test suite
2. **Entrypoint naming**: The entrypoint for every program shall be called `main`
3. **Always include tests**: Every new feature and bug fix must include tests. No code should be committed without corresponding test coverage
4. **No TODO/FIXME comments**: Instead of leaving TODO or FIXME comments in code, create a task with `task create` to track the work properly
5. **Fast typechecking**: Use `Omni/Ide/typecheck.sh <file>` for quick Python typechecking instead of `bild --test` when you only need to check types

## Documentation

Detailed documentation has been moved to the respective namespaces:

*   **Task Manager**: [`Omni/Task/README.md`](Omni/Task/README.md) - Usage, workflows, and best practices for the task tracker.
*   **Build Tool (Bild)**: [`Omni/Bild/README.md`](Omni/Bild/README.md) - How to use `bild` and manage dependencies.
*   **Development Tools & Git Workflow**: [`Omni/Ide/README.md`](Omni/Ide/README.md) - `run.sh`, `lint`, `repl.sh`, git-branchless workflow, and commit guidelines.