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>" [--type=<type>] [--parent=<id>] [--deps=<ids>] [--dep-type=<type>] [--discovered-from=<id>] [--namespace=<ns>]
```

Examples:
```bash
# Create an epic (container for tasks)
task create "User Authentication System" --type=epic

# Create a task within an epic
task create "Design auth API" --parent=t-abc123

# Create a task with blocking dependency
task create "Write tests" --deps=t-a1b2c3 --dep-type=blocks

# Create work discovered during implementation (shortcut)
task create "Fix memory leak" --discovered-from=t-abc123

# Create related work (doesn't block)
task create "Update documentation" --deps=t-abc123 --dep-type=related

# Associate with a namespace
task create "Fix type errors" --namespace="Omni/Task"
```

**Task Types:**
- `epic` - Container for related tasks (replaces the old "project" concept)
- `task` - Individual work item (default)

**Dependency Types:**
- `blocks` - Hard dependency, blocks ready work queue (default)
- `discovered-from` - Work discovered during other work, doesn't block
- `parent-child` - Epic/subtask relationship, blocks ready work
- `related` - Soft relationship, doesn't block

The `--namespace` option associates the task with a specific namespace in the monorepo (e.g., `Omni/Task`, `Biz/Cloud`). This helps organize tasks by the code they relate to.

### List Tasks
```bash
task list [--type=<type>] [--parent=<id>] [--status=<status>] [--namespace=<ns>]
```

Examples:
```bash
task list                              # All tasks
task list --type=epic                  # All epics
task list --parent=t-abc123            # All tasks in an epic
task list --status=open                # All open tasks
task list --status=done                # All completed tasks
task list --namespace="Omni/Task"      # All tasks for a namespace
task list --parent=t-abc123 --status=open  # Combine filters: open tasks in epic
```

### 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" --type=task

# Note the ID (e.g., t-20241108120000)

# Create dependent task with blocking dependency
task create "Implement API client" --deps=t-20241108120000 --dep-type=blocks
```

The dependent task won't show up in `task ready` until the blocker is marked `done`.

### Discovered Work Pattern

When you find work during implementation, use the `--discovered-from` flag:

```bash
# While working on t-abc123, you discover a bug
task create "Fix memory leak in parser" --discovered-from=t-abc123

# This is equivalent to:
task create "Fix memory leak in parser" --deps=t-abc123 --dep-type=discovered-from
```

The `discovered-from` dependency type maintains context but **doesn't block** the ready work queue. This allows AI agents to track what work was found during other work while still being able to work on it immediately.

### Working with Epics

```bash
# Create an epic for a larger feature
task create "User Authentication System" --type=epic
# Note ID: t-abc123

# Create child tasks within the epic
task create "Design login flow" --parent=t-abc123
task create "Implement OAuth" --parent=t-abc123
task create "Add password reset" --parent=t-abc123

# List all tasks in an epic
task list --parent=t-abc123

# List all epics
task list --type=epic
```

### Breaking Down Large Work

```bash
# Create parent epic
task create "Complete authentication system" --type=epic
# Note ID: t-20241108120000

# Create subtasks that depend on planning
task create "Backend auth service" --parent=t-20241108120000
task create "Frontend login UI" --parent=t-20241108120000
task create "Integration tests" --parent=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" --discovered-from=t-abc123
task create "Add missing test coverage" --discovered-from=t-abc123
```

### 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
```

### 4. Use Descriptive Titles
Good: `"Add JWT token validation to auth middleware"`
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`
- Add tasks to the epic using `--parent=<epic-id>`
- Use `--discovered-from` to track work found during implementation

## 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 an epic for the work
task create "Task Manager Improvements" --type=epic
# Returns: t-abc123

# Create tasks within the epic
task create "Design task manager schema" --parent=t-abc123
task create "Implement JSONL storage" --parent=t-abc123
task create "Add dependency tracking" --parent=t-abc123

# See what's ready (all of them, no blockers yet)
task ready

# Start working
task update t-20241108120000 in-progress

# Discover work during implementation
task create "Fix edge case in ID generation" --discovered-from=t-20241108120000

# Discover dependent work with blocking
task create "Write storage tests" --deps=t-20241108120000 --dep-type=blocks

# Complete first task
task update t-20241108120000 done

# Now the test task is unblocked (discovered work was already unblocked)
task ready
# Shows: "Write storage tests" and "Fix edge case in ID generation"
```

## 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`
3. **Always include tests**: Every new feature and bug fix must include tests. No code should be committed without corresponding test coverage

## 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

### Required Checks Before Completing Tasks

After completing a task, **always** run these commands for the namespace(s) you modified:

```bash
# Run tests
bild --test Omni/YourNamespace.hs

# Run linter
lint Omni/YourNamespace.hs
```

**Fix all reported errors** related to your changes before marking the task as complete. This ensures code quality and prevents breaking the build for other contributors.

## Future Enhancements

Planned features (not yet implemented):
- Task priorities
- Due dates
- Task labels/tags
- Search/filter capabilities
- Assignees
- Multi-repo support