task: sync database

1 files changed, 158 insertions, 22 deletions

diff --git a/AGENTS.md b/AGENTS.md
index 5b37334..d19ecf5 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -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