diff options
Diffstat (limited to 'AGENTS.md')
| -rw-r--r-- | AGENTS.md | 180 |
1 files changed, 158 insertions, 22 deletions
@@ -6,6 +6,100 @@ 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> --status 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> --status 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 @@ -55,7 +149,18 @@ The task manager is a dependency-aware issue tracker inspired by beads. It uses: - **Dependencies**: Tasks can block other tasks - **Ready work detection**: Automatically finds unblocked tasks -**IMPORTANT**: This project uses `task` for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods. +**IMPORTANT**: You MUST use `task` for ALL issue tracking. NEVER use markdown TODOs, todo_write, task lists, or any other tracking methods. + +### Human Setup vs Agent Usage + +**If you see "database not found" or similar errors:** +```bash +task init --quiet # Non-interactive, auto-setup, no prompts +``` + +**Why `--quiet`?** The regular `task init` may have interactive prompts. The `--quiet` flag makes it fully non-interactive and safe for agent-driven setup. + +**If `task init --quiet` fails:** Ask the human to run `task init` manually, then continue. ### Create a Task ```bash @@ -180,11 +285,15 @@ task import -i /path/to/backup.jsonl ### Initialize (First Time) ```bash -task init +task init --quiet # Non-interactive (recommended for agents) +# OR +task init # Interactive (for humans) ``` Creates `.tasks/` directory and `tasks.jsonl` file. +**Agents MUST use `--quiet` flag** to avoid interactive prompts. + ### Common Workflows #### Starting New Work @@ -255,21 +364,32 @@ task list --type=epic ### Agent Best Practices -#### 1. Always Check Ready Work First -Before asking what to do, check `task ready` to see unblocked tasks. +#### 1. ALWAYS Check Ready Work First +Before asking what to do, you MUST check `task ready --json` to see unblocked tasks. -#### 2. Create Tasks for Discovered Work -When you encounter work during implementation: +#### 2. ALWAYS Create Tasks for Discovered Work +When you encounter work during implementation, you MUST create linked tasks: ```bash -task create "Fix type error in auth module" --discovered-from=t-abc123 -task create "Add missing test coverage" --discovered-from=t-abc123 +task create "Fix type error in auth module" --discovered-from=t-abc123 --json +task create "Add missing test coverage" --discovered-from=t-abc123 --json ``` +**CRITICAL: File bugs immediately when you discover them:** +- If a command doesn't work as documented → create a task +- If a command doesn't work as you expected → create a task +- If behavior is inconsistent or confusing → create a task +- If documentation is wrong or misleading → create a task +- If you find yourself working around a limitation → create a task + +**NEVER leave TODO comments in code.** Create a task instead. + +**NEVER ignore bugs or unexpected behavior.** File a task for it immediately. + #### 3. Track Dependencies If work depends on other work, use `--deps`: ```bash # Can't write tests until implementation is done -task create "Test auth flow" --deps=t-20241108120000 --dep-type=blocks +task create "Test auth flow" --deps=t-20241108120000 --dep-type=blocks --json ``` #### 4. Use Descriptive Titles @@ -278,16 +398,17 @@ Bad: `"Fix auth"` #### 5. Use Epics for Organization Organize related work using epics: -- Create an epic for larger features: `task create "Feature Name" --type=epic` +- Create an epic for larger features: `task create "Feature Name" --type=epic --json` - Add tasks to the epic using `--parent=<epic-id>` - Use `--discovered-from` to track work found during implementation -#### 6. Store AI planning docs in `_/llm` directory +#### 6. ALWAYS Store AI Planning Docs in `_/llm` Directory AI assistants often create planning and design documents during development: - PLAN.md, DESIGN.md, TESTING_GUIDE.md, tmp, and similar files -- **Best Practice: Use a dedicated directory for these ephemeral files.** +- **You MUST use a dedicated directory for these ephemeral files** - Store ALL AI-generated planning/design docs in `_/llm` - The `_` directory is ignored by git and all of our temporary files related to the omnirepo go there +- NEVER commit planning docs to the repo root ### Dependency Rules @@ -400,17 +521,24 @@ task ready # Shows: "Write storage tests" and "Fix edge case in ID generation" ``` -### Important Rules +### Reinforcement: Critical Rules + +Remember these non-negotiable rules: + +- ✅ Use `task` for ALL task tracking (with `--json` flag) +- ✅ Link discovered work with `--discovered-from` dependencies +- ✅ File bugs IMMEDIATELY when you discover unexpected behavior +- ✅ Check `task ready --json` before asking "what should I work on?" +- ✅ Store AI planning docs in `_/llm` directory +- ✅ Run `task sync` at end of every session (commits locally, does NOT push) +- ❌ NEVER use `todo_write` tool +- ❌ NEVER create markdown TODO lists or task checklists +- ❌ NEVER put TODOs or FIXMEs in code comments +- ❌ NEVER use external issue trackers +- ❌ NEVER duplicate tracking systems +- ❌ NEVER clutter repo root with planning documents -- Use `task` for ALL task tracking -- Link discovered work with `discovered-from` dependencies -- Check `task ready` before asking "what should I work on?" -- Store AI planning docs in `_/llm` directory -- Do NOT create markdown TODO lists -- Do NOT put TODOs or FIXMEs in code comments -- Do NOT use external issue trackers -- Do NOT duplicate tracking systems -- Do NOT clutter repo root with planning documents +**If you find yourself about to use todo_write or create a markdown checklist, STOP and use `task create` instead.** ## Development Guide and Tools @@ -574,6 +702,14 @@ git restack - Broken or untested code - Temporary debugging changes +**NEVER do these git operations without explicit user request:** +- ❌ `git push` - NEVER push to remote unless explicitly asked +- ❌ `git pull` - NEVER pull from remote unless explicitly asked +- ❌ Force pushes or destructive operations +- ❌ Branch deletion or remote branch operations + +**Why:** The user maintains control over when code is shared with collaborators. Always ask before syncing with remote repositories. + ### Workflow Best Practices 1. **Make small, focused commits** - Each commit should represent one logical change |