# TODO.md - TODO Subsystem (Embedded)
**Authority:** subsystem (REAL)
**Layer:** Operational
**Binding:** No
**Quick Reference:**
| `decapod todo add "title" --priority high` | Create task |
| `decapod todo list` | List all tasks |
| `decapod todo done --id <id>` | Mark complete / closeout |
| `decapod todo archive --id <id>` | Optional archival (policy-gated) |
---
## CLI Surface
```bash
decapod todo add "<title>" [--priority high|medium|low] [--tags <tags>] [--owner <owner>]
decapod todo list [--status open|done|archived] [--scope <scope>] [--tags <tags>]
decapod todo get --id <id>
decapod todo done --id <id>
decapod todo archive --id <id>
decapod todo comment --id <id> --comment "<text>"
decapod todo edit --id <id> [--title <title>] [--description <desc>] [--owner <owner>] [--category <name>]
decapod todo claim --id <id> [--agent <agent-id>] [--mode exclusive|shared]
decapod todo release --id <id>
decapod todo rebuild
decapod todo categories
decapod todo register-agent --agent <agent-id> --category <name> [--category <name>]
decapod todo ownerships [--category <name>] [--agent <agent-id>]
decapod todo heartbeat [--agent <agent-id>] [--autoclaim] [--max-claims <n>]
decapod todo presence [--agent <agent-id>]
decapod todo worker-run [--agent <agent-id>] [--task-id <id>] [--max-tasks <n>] [--lesson] [--autoclose]
decapod todo handoff --id <id> --to <agent-id> [--from <agent-id>] --summary "<handoff summary>"
decapod todo add-owner --id <id> --agent <agent-id> [--claim-type primary|secondary|watcher]
decapod todo remove-owner --id <id> --agent <agent-id>
decapod todo list-owners --id <id>
decapod todo register-expertise --category <name> [--agent <agent-id>] [--level beginner|intermediate|advanced|expert]
decapod todo expertise [--agent <agent-id>] [--category <name>]
decapod data schema --subsystem todo # JSON schema for programmatic use
```
## Task Lifecycle & Agent Obligations
All tasks track three timestamps:
- **created_at**: When the task was created
- **completed_at**: When the task was marked done (via `decapod todo done`)
- **closed_at**: When the task was archived (via `decapod todo archive`)
### Agent Requirement: Close Completed Tickets
**As an AI agent, you MUST close out tickets you complete.**
When you finish work on a task:
1. Mark it done: `decapod todo done --id <task-id>`
2. Archive only if explicitly required by policy/workflow: `decapod todo archive --id <task-id>`
Done state is the default closeout state. Archive is optional and may require approval in some repos.
### Command Strictness (Avoid Invalid Subcommands)
- Use only the explicit TODO commands shown above.
- Do **not** call `decapod complete`, `decapod close`, `decapod todo close`, or `decapod todo complete` (these are not valid CLI surfaces).
- Always pass the task id explicitly: `--id <task-id>`.
### Workflow
```bash
# 1. Create a task (from AGENTS.md §)
decapod todo add "Implement feature X" --priority high
# 2. Do the work...
# ... implementation ...
# 3. Mark as done (sets completed_at)
decapod todo done --id docs_a1b2c3d4e5f6g7h8
# 4. Optional archive (sets closed_at) when required/approved
decapod todo archive --id code_a1b2c3d4e5f6g7h8
```
**Rule**: Use `todo done --id` for normal closeout. Use `todo archive --id` only when the workflow requires archival and approvals are satisfied.
---
## Multi-Agent Coordination
The TODO subsystem coordinates multiple agents using category ownership plus heartbeats.
### Ownership model
- Agents claim category ownership via `decapod todo register-agent`.
- Category ownership is durable and queryable via `decapod todo ownerships`.
- New tasks auto-assign to the active owner of their inferred category.
### Presence model
- Agents publish liveness via `decapod todo heartbeat`.
- Presence state is visible via `decapod todo presence`.
- Ownership checks treat missing/stale presence as inactive.
- Decapod auto-clocks liveness on normal command invocation (invocation heartbeat).
### Heartbeat execution assist
- `decapod todo heartbeat --autoclaim --max-claims <n>` can claim eligible open tasks for the active agent.
- This is the manual control-plane hook for command-driven worker loops when needed.
### Timeout eviction (30 minutes)
- If category owner heartbeat is stale for more than 30 minutes, another agent can claim work in that category.
- On successful claim, ownership transfers to the claiming agent.
- This prevents abandoned ownership from blocking progress.
---
## Pre-TODO Audit Requirement
**Binding: Yes**
Before creating or modifying any TODO (via `decapod todo add`, `decapod todo done`, `decapod todo archive`, or any TODO mutation), agents MUST:
1. Run `decapod validate` to audit system state
2. Review validation results for any failures
3. Address critical issues before proceeding with TODO operations
4. Document any intentional exceptions in the TODO description
**Rationale:** TODO operations mutate shared state. System audits ensure integrity before mutations occur, preventing corrupted state from being propagated through the task lifecycle.
---
## State Transition Validation
Every lifecycle enum must have an explicit transition table. Invalid transitions must be rejected with an error, not silently ignored.
### Valid Transitions
```
pending → active (start work)
pending → archived (skip/cancel)
active → done (complete work)
active → pending (revert/reassign)
done → archived (close out)
```
All other transitions are invalid and must produce an error.
### Transition Discipline
1. **Explicit transition tables**: Every state enum must define `can_transition_to()` with an exhaustive match.
2. **Reject invalid transitions**: Return an error with the current state, target state, and valid alternatives — never silently ignore.
3. **Transition history**: Every state change must be recorded in the event log with a `reason` field. The reason should explain *why* the transition happened, not just *what* changed.
4. **Bounded history**: Cap transition history at a reasonable limit (e.g., 200 entries per task) to prevent unbounded growth.
---
**See also:** `core/PLUGINS.md` for subsystem registry and truth labels.
---
## Links
### Core Router
- `core/DECAPOD.md` - **Router and navigation charter (START HERE)**
### Authority (Constitution Layer)
- `specs/INTENT.md` - **Methodology contract (READ FIRST)**
- `specs/SYSTEM.md` - System definition and authority doctrine
- `specs/SECURITY.md` - Security contract
### Registry (Core Indices)
- `core/PLUGINS.md` - Subsystem registry
- `core/INTERFACES.md` - Interface contracts index
- `core/METHODOLOGY.md` - Methodology guides index
### Contracts (Interfaces Layer)
- `interfaces/CONTROL_PLANE.md` - Sequencing patterns
- `interfaces/TODO_SCHEMA.md` - TODO schema definition
- `interfaces/STORE_MODEL.md` - Store semantics
### Practice (Methodology Layer)
- `methodology/SOUL.md` - Agent identity
### Operations (Plugins Layer - This Subsystem)
- `plugins/VERIFY.md` - Validation subsystem
- `plugins/MANIFEST.md` - Canonical vs derived vs state
- `plugins/EMERGENCY_PROTOCOL.md` - Emergency protocols