From 72a924ebd7abdfa2c51f8c00b3cbd130b059ca3e Mon Sep 17 00:00:00 2001 From: Ben Sima Date: Sat, 22 Nov 2025 14:04:50 -0500 Subject: feat: implement t-1o2bkufixnc Refactored `AGENTS.md` to be a concise cheat sheet by: 1. Moving detailed examples of "Forbidden Patterns" and "Bug Discovery" to `Omni/Task/README.md`. 2. Moving "Coding Conventions" (Always include tests, No TODOs, Fast typechecking) to `README.md`. 3. Removing "About Omnirepo" and "Source Layout" sections from `AGENTS.md` as they are duplicative of `README.md`. 4. Condensing `AGENTS.md` to contain only Critical Rules, a short Session Checklist/Cheat Sheet, and pointers to the detailed READMEs (`Omni/Task/README.md`, `Omni/Bild/README.md`, `Omni/Ide/README.md`, `README.md`). Verified that detailed documentation exists in the respective namespaces and passed linting. --- Omni/Task/README.md | 59 +++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 55 insertions(+), 4 deletions(-) (limited to 'Omni/Task') diff --git a/Omni/Task/README.md b/Omni/Task/README.md index db42737..8e8670e 100644 --- a/Omni/Task/README.md +++ b/Omni/Task/README.md @@ -231,6 +231,24 @@ task create "Fix type error in auth module" --discovered-from=t-abc123 --json task create "Add missing test coverage" --discovered-from=t-abc123 --json ``` +**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= --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" + **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 @@ -242,24 +260,57 @@ task create "Add missing test coverage" --discovered-from=t-abc123 --json **NEVER ignore bugs or unexpected behavior.** File a task for it immediately. -### 3. Track Dependencies +### 3. 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= --json +``` + +### 4. 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 --json ``` -### 4. Use Descriptive Titles +### 5. Use Descriptive Titles Good: `"Add JWT token validation to auth middleware"` Bad: `"Fix auth"` -### 5. Use Epics for Organization +### 6. Use Epics for Organization Organize related work using epics: - Create an epic for larger features: `task create "Feature Name" --type=epic --json` - Add tasks to the epic using `--parent=` - Use `--discovered-from` to track work found during implementation -### 6. ALWAYS Store AI Planning Docs in `_/llm` Directory +### 7. 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 - **You MUST use a dedicated directory for these ephemeral files** -- cgit v1.2.3