From 3bf1691f4e32235f84f5cff9d6e4a3fdb9a57ffc Mon Sep 17 00:00:00 2001 From: Ben Sima Date: Sat, 8 Nov 2025 16:13:29 -0500 Subject: 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-Thread-ID: https://ampcode.com/threads/T-85f4ee29-a529-4f59-ac6f-6ffec75b6a56 --- AGENTS.md | 391 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 391 insertions(+) create mode 100644 AGENTS.md (limited to 'AGENTS.md') 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 "" <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 -- cgit v1.2.3