Add task manager for AI agents

Implemented a dependency-aware task tracker inspired by beads: - Task
CRUD operations (create, list, update, ready) - Dependency tracking
and ready work detection - JSONL storage with git sync via hooks -
Export/import for cross-machine synchronization - Short base62-encoded
task IDs (e.g., t-1ky7gJ2)

Added comprehensive AGENTS.md documentation: - Task manager usage and
workflows - Development tools (bild, lint, repl.sh) - Git-branchless
workflow guidelines - Coding conventions

Integrated with git hooks for auto-sync: - post-merge/post-checkout:
import tasks - pre-commit/pre-push: export tasks

Also includes beads design analysis document for reference.

Completed tasks: - t-a1b2c3: Show help text when invoked without args
- t-d4e5f6: Move dev instructions to AGENTS.md - t-g7h8i9: Implement
shorter task IDs - t-p6q7r8: Add git-branchless workflow docs

https: //ampcode.com/threads/T-85f4ee29-a529-4f59-ac6f-6ffec75b6a56
Co-authored-by: Amp <amp@ampcode.com> Amp-Thread-ID:
https://ampcode.com/threads/T-85f4ee29-a529-4f59-ac6f-6ffec75b6a56

1 files changed, 391 insertions, 0 deletions

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..e30b01a
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,391 @@
+# Task Manager for AI Agents
+
+This document describes the task tracking system for AI coding agents working in this codebase.
+
+## Overview
+
+The task manager is a dependency-aware issue tracker inspired by beads. It uses:
+- **Storage**: Local JSONL file (`.tasks/tasks.jsonl`)
+- **Sync**: Git-tracked (automatically synced across machines)
+- **Dependencies**: Tasks can block other tasks
+- **Ready work detection**: Automatically finds unblocked tasks
+
+## Quick Reference
+
+### Create a Task
+```bash
+task create "<title>" <project> [--deps=<ids>]
+```
+
+Examples:
+```bash
+task create "Add authentication" auth-system
+task create "Write tests" auth-system --deps=t-20241108120000
+```
+
+### List Tasks
+```bash
+task list [--project=<project>]
+```
+
+Examples:
+```bash
+task list                      # All tasks
+task list --project=auth       # Filter by project
+```
+
+### Get Ready Work
+```bash
+task ready
+```
+
+Shows all tasks that are:
+- Not closed
+- Not blocked by incomplete dependencies
+
+### Update Task Status
+```bash
+task update <id> <status>
+```
+
+Status values: `open`, `in-progress`, `done`
+
+Examples:
+```bash
+task update t-20241108120000 in-progress
+task update t-20241108120000 done
+```
+
+### View Dependencies
+```bash
+task deps <id>
+```
+
+Shows the dependency tree for a task.
+
+### Export Tasks
+```bash
+task export [--flush]
+```
+
+Consolidates and exports tasks to `.tasks/tasks.jsonl`, removing duplicates. The `--flush` flag forces immediate export (used by git hooks).
+
+### Import Tasks
+```bash
+task import -i <file>
+```
+
+Imports tasks from a JSONL file, merging with existing tasks. Newer tasks (based on `updatedAt` timestamp) take precedence.
+
+Examples:
+```bash
+task import -i .tasks/tasks.jsonl
+task import -i /path/to/backup.jsonl
+```
+
+### Initialize (First Time)
+```bash
+task init
+```
+
+Creates `.tasks/` directory and `tasks.jsonl` file.
+
+## Common Workflows
+
+### Starting New Work
+
+1. **Find what's ready to work on:**
+   ```bash
+   task ready
+   ```
+
+2. **Pick a task and mark it in progress:**
+   ```bash
+   task update t-20241108120000 in-progress
+   ```
+
+3. **When done, mark it complete:**
+   ```bash
+   task update t-20241108120000 done
+   ```
+
+### Creating Dependent Tasks
+
+When you discover work that depends on other work:
+
+```bash
+# Create the blocking task first
+task create "Design API" api-layer
+
+# Note the ID (e.g., t-20241108120000)
+
+# Create dependent task
+task create "Implement API client" api-layer --deps=t-20241108120000
+```
+
+The dependent task won't show up in `task ready` until the blocker is marked `done`.
+
+### Working on a Project
+
+```bash
+# See all tasks for a project
+task list --project=auth-system
+
+# Create related tasks
+task create "Design login flow" auth-system
+task create "Implement OAuth" auth-system
+task create "Add password reset" auth-system
+```
+
+### Breaking Down Large Work
+
+```bash
+# Create parent task
+task create "Complete authentication system" auth-system
+# Note ID: t-20241108120000
+
+# Create subtasks that depend on planning
+task create "Backend auth service" auth-system --deps=t-20241108120000
+task create "Frontend login UI" auth-system --deps=t-20241108120000
+task create "Integration tests" auth-system --deps=t-20241108120000
+```
+
+## Agent Best Practices
+
+### 1. Always Check Ready Work First
+Before asking what to do, check `task ready` to see unblocked tasks.
+
+### 2. Create Tasks for Discovered Work
+When you encounter work during implementation:
+```bash
+task create "Fix type error in auth module" auth-system
+task create "Add missing test coverage" testing
+```
+
+### 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" testing --deps=t-20241108120000
+```
+
+### 4. Use Descriptive Titles
+Good: `"Add JWT token validation to auth middleware"`
+Bad: `"Fix auth"`
+
+### 5. Keep Projects Organized
+Use consistent project names:
+- `auth-system` not `auth`, `authentication`, `auth-system-v2`
+- `api-layer` not `api`, `API`, `backend-api`
+
+## Task Lifecycle
+
+```
+[open] ──update in-progress──> [in-progress] ──update done──> [done]
+  │                                   │
+  └─────────update open───────────────┘
+```
+
+States:
+- **open**: Not started, available for work (if not blocked)
+- **in-progress**: Currently being worked on
+- **done**: Completed
+
+## Dependency Rules
+
+- A task is **blocked** if any of its dependencies are not `done`
+- A task is **ready** if all its dependencies are `done` (or it has no dependencies)
+- `task ready` only shows tasks with status `open` or `in-progress` that are not blocked
+
+## File Structure
+
+```
+.tasks/
+├── tasks.jsonl    # Git-tracked, source of truth
+```
+
+Each line in `tasks.jsonl` is a JSON object representing a task.
+
+## Example Session
+
+```bash
+# First time setup
+task init
+
+# Create some work
+task create "Design task manager schema" core-system
+task create "Implement JSONL storage" core-system
+task create "Add dependency tracking" core-system
+
+# See what's ready (all of them, no blockers yet)
+task ready
+
+# Start working
+task update t-20241108120000 in-progress
+
+# Discover dependent work
+task create "Write storage tests" testing --deps=t-20241108120000
+
+# Complete first task
+task update t-20241108120000 done
+
+# Now the test task is unblocked
+task ready
+# Shows: "Write storage tests"
+```
+
+## Build and Test Commands
+
+Build the task manager:
+```bash
+bild --time 0 Omni/Task.hs
+```
+
+Run tests:
+```bash
+task test
+```
+
+## Integration with Git
+
+The `.tasks/tasks.jsonl` file is git-tracked. When you:
+- Create/update tasks locally
+- Commit and push
+- Other machines/agents get the updates on `git pull`
+
+**Important**: Add to `.gitignore`:
+```
+.tasks/*.db
+.tasks/*.db-journal
+.tasks/*.sock
+```
+
+But **do** track:
+```
+!.tasks/
+!.tasks/tasks.jsonl
+```
+
+## Troubleshooting
+
+### "Task not found"
+- Check the task ID is correct with `task list`
+- Ensure you've run `task init`
+
+### "Database not initialized"
+Run: `task init`
+
+### Dependencies not working
+- Verify dependency IDs exist: `task list`
+- Check dependency tree: `task deps <id>`
+
+## Development Tools
+
+### bild
+
+`bild` is the universal build tool. It can build and test everything in the repo.
+
+Examples:
+```bash
+bild --test Omni/Bild.hs         # Build and test a namespace
+bild --time 0 Omni/Cloud.nix     # Build with no timeout
+bild --plan Omni/Test.hs         # Analyze build without building
+```
+
+### lint
+
+Universal lint and formatting tool. Errors if lints fail or code is not formatted properly.
+
+Examples:
+```bash
+lint Omni/Cli.hs                 # Lint a namespace
+lint --fix **/*.py               # Lint and fix all Python files
+```
+
+### repl.sh
+
+Like `nix-shell` but specific to this repo. Analyzes the namespace, pulls dependencies, and starts a shell or repl.
+
+Examples:
+```bash
+repl.sh Omni/Bild.hs            # Start Haskell repl with namespace loaded
+repl.sh --bash Omni/Log.py      # Start bash shell for namespace
+```
+
+## 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`
+
+## Git Workflow
+
+### Use git-branchless
+
+This repository uses **git-branchless** for a patch-based workflow instead of traditional branch-based git.
+
+Key concepts:
+- Work with **patches** (commits) directly rather than branches
+- Use **stacking** to organize related changes
+- Leverage **smartlog** to visualize commit history
+
+### Common git-branchless Commands
+
+**View commit graph:**
+```bash
+git smartlog
+```
+
+**Create a new commit:**
+```bash
+# Make your changes
+git add .
+git commit -m "Your commit message"
+```
+
+**Amend the current commit:**
+```bash
+# Make additional changes
+git add .
+git commit --amend --no-edit
+```
+
+**Move/restack commits:**
+```bash
+git move -s <source> -d <destination>
+git restack
+```
+
+**Submit changes:**
+```bash
+# After commits are ready
+git submit
+```
+
+### When to Record Changes in Git
+
+**DO record in git:**
+- Completed features or bug fixes
+- Working code that passes tests and linting
+- Significant milestones in task completion
+
+**DO NOT record in git:**
+- Work in progress (unless specifically requested)
+- Broken or untested code
+- Temporary debugging changes
+
+### Workflow Best Practices
+
+1. **Make small, focused commits** - Each commit should represent one logical change
+2. **Write descriptive commit messages** - Explain what and why, not just what
+3. **Rebase and clean up history** - Use `git commit --amend` and `git restack` to keep history clean
+4. **Test before committing** - Run `bild --test` and `lint` on affected namespaces
+
+## Future Enhancements
+
+Planned features (not yet implemented):
+- Task priorities
+- Due dates
+- Task labels/tags
+- Search/filter capabilities
+- Assignees
+- Multi-repo support