Task Management

Task management in Crucible uses structured markdown files (typically TASKS.md) to track implementation plans. The file format is designed for both human readability and machine parsing.

Overview

TASKS.md files combine:

Frontmatter for project metadata
Phases to organize work into logical stages
Tasks with checkboxes, IDs, and dependencies
Inline metadata for machine parsing

File Format

---
description: Brief description of the project
context_files:
  - path/to/relevant/file.rs
  - path/to/another/file.rs
verify: cargo test --workspace
---

## Phase 1: Phase Name

### 1.1 Section Name

- [ ] Task description [id:: 1.1.1]
  - Implementation details
  - [tests:: test_name_1, test_name_2]

- [ ] Another task [id:: 1.1.2] [deps:: 1.1.1]
  - This task depends on 1.1.1

Frontmatter Fields

Field	Required	Description
`title`	No	Display title for the task list
`description`	No (recommended)	Brief description of what this task list accomplishes
`context_files`	No	List of files relevant to this work (for agent context)
`verify`	No	Command to run to verify completion (e.g., `just test`)

Checkbox Symbols

Standard markdown checkboxes with extended statuses:

Symbol	Status	Description
`[ ]`	pending	Not started
`[x]`	done	Finished successfully (`[X]` also accepted)
`[/]`	in_progress	Currently being worked on
`[-]`	cancelled	Will not be done
`[!]`	blocked	Cannot proceed, needs intervention

Any other symbol inside the brackets is not recognized and the task parses as pending.

Inline Metadata

Metadata is embedded in task lines using [key:: value] syntax (Dataview-compatible):

Key	Description	Example
`id`	Unique task identifier	`[id:: 1.1.1]`
`deps`	Comma-separated dependency IDs	`[deps:: 1.1.1, 1.2.1]`
`tests`	Test names to verify this task	`[tests:: test_foo, test_bar]`
`priority`	Task priority (low/medium/high)	`[priority:: high]`

id and deps drive dependency resolution. Any other key — including tests and priority — parses into the task’s generic metadata map, but nothing consumes it yet; such keys are conventions for human/agent readers.

ID Format

Task IDs follow the pattern: {phase}.{section}.{task}

Phase 1, Section 1, Task 1: 1.1.1
Phase 2, Section 3, Task 2: 2.3.2

CLI Commands

The cru tasks command provides operations on TASKS.md files. The file path is a flag on the parent command (--file, default TASKS.md in the current directory), not a positional argument of the subcommands:

# List all tasks with status
cru tasks list

# Show next available task (respecting dependencies)
cru tasks next

# Mark a task as in-progress
cru tasks pick <task_id>

# Mark a task as completed
cru tasks done <task_id>

# Mark a task as blocked, with an optional reason
cru tasks blocked <task_id> ["reason"]

# Use a custom tasks file
cru tasks --file ~/work/TASKS.md list

Dependency Resolution

Tasks with [deps:: ...] metadata won’t be available until all dependencies are completed:

- [x] Create database schema [id:: 1.1.1]
- [ ] Implement CRUD operations [id:: 1.1.2] [deps:: 1.1.1]  # Available
- [ ] Add caching layer [id:: 1.1.3] [deps:: 1.1.2]          # Not available yet

Context Optimization

TASKS.md serves as more than task tracking—it’s a context management strategy for AI agents.

The Problem: Context Window Bloat

Traditional agent loops accumulate conversation history:

Turn 1: 1k tokens
Turn 2: 2k tokens (includes turn 1)
Turn N: N×k tokens → context explosion

The Solution: File-as-State

TASKS.md follows the “Ralph Wiggum” pattern (named after Geoffrey Huntley’s technique):

State lives in files, not conversation history
Each agent iteration gets a fresh context window
The file is read as part of a cached prefix (system prompt position)
Progress accumulates in the file, not in tokens

Token Economics

Position	Attention	Cost
Start (TASKS.md)	High	Cached (75% cheaper)
Middle (old history)	Low	Full price
End (current query)	High	Full price

TASKS.md in the prefix = high attention + amortized cost across iterations.

Multi-Agent Handoffs

Instead of passing full conversation history between agents:

## Handoff Notes
- agent-A completed auth schema (see task 1.1.1)
- agent-B found edge case: empty password validation

Curated handoffs in the file replace expensive message passing.

Best Practices

Use descriptive IDs: IDs should reflect the phase/section structure
Keep tasks small: Each task should be completable in one focused session
Specify dependencies explicitly: Don’t assume order implies dependency
Include verification steps: Add [tests::] for testable tasks
Group related work: Use phases and sections to organize logically
Use for context optimization: Keep TASKS.md in the cached prefix for efficient multi-turn agent work