diff options
Diffstat (limited to 'AGENTS.md')
| -rw-r--r-- | AGENTS.md | 121 |
1 files changed, 87 insertions, 34 deletions
@@ -14,16 +14,40 @@ The task manager is a dependency-aware issue tracker inspired by beads. It uses: ### Create a Task ```bash -task create "<title>" <project> [--deps=<ids>] [--namespace=<ns>] +task create "<title>" [--type=<type>] [--parent=<id>] [--deps=<ids>] [--dep-type=<type>] [--discovered-from=<id>] [--namespace=<ns>] ``` Examples: ```bash -task create "Add authentication" auth-system -task create "Write tests" auth-system --deps=t-a1b2c3 -task create "Fix type errors" task-manager --namespace="Omni/Task" +# 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 @@ -118,39 +142,60 @@ When you discover work that depends on other work: ```bash # Create the blocking task first -task create "Design API" api-layer +task create "Design API" --type=task # Note the ID (e.g., t-20241108120000) -# Create dependent task -task create "Implement API client" api-layer --deps=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`. -### Working on a Project +### 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 -# See all tasks for a project -task list --project=auth-system +# Create an epic for a larger feature +task create "User Authentication System" --type=epic +# Note ID: t-abc123 -# Create related tasks -task create "Design login flow" auth-system -task create "Implement OAuth" auth-system -task create "Add password reset" auth-system +# 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 task -task create "Complete authentication system" auth-system +# 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" auth-system --deps=t-20241108120000 -task create "Frontend login UI" auth-system --deps=t-20241108120000 -task create "Integration tests" auth-system --deps=t-20241108120000 +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 @@ -161,25 +206,26 @@ 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 +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" testing --deps=t-20241108120000 +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. Keep Projects Organized -Use consistent project names: -- `auth-system` not `auth`, `authentication`, `auth-system-v2` -- `api-layer` not `api`, `API`, `backend-api` +### 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 @@ -215,10 +261,14 @@ Each line in `tasks.jsonl` is a JSON object representing a task. # 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 +# 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 @@ -226,15 +276,18 @@ task ready # Start working task update t-20241108120000 in-progress -# Discover dependent work -task create "Write storage tests" testing --deps=t-20241108120000 +# 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 +# Now the test task is unblocked (discovered work was already unblocked) task ready -# Shows: "Write storage tests" +# Shows: "Write storage tests" and "Fix edge case in ID generation" ``` ## Build and Test Commands |