path: root/AGENTS.md

# 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