spacedrive/docs/core/task-tracking.mdx

---
title: Task Tracking
sidebarTitle: Task Tracking
---

The `.tasks/` directory contains a structured task tracking system that manages the entire development lifecycle of Spacedrive. Tasks are defined as markdown files with YAML frontmatter and validated against a JSON schema.

## Overview

Task tracking provides:
- **Hierarchical organization** with epics and subtasks
- **Status tracking** across the development lifecycle
- **Metadata** like priority, assignee, and whitepaper references
- **Validation** via a CLI tool to ensure consistency

### Directory Structure

```
.tasks/
├── core/                         # Backend/Rust tasks
│   ├── CORE-000-vdfs-core.md
│   ├── CORE-001-entry-centric-model.md
│   ├── JOB-000-job-system.md
│   ├── INDEX-*.md
│   ├── LSYNC-*.md
│   └── ...
├── interface/                    # Frontend/React tasks
│   ├── UI-000-interface-v2.md
│   ├── EXPL-000-explorer-epic.md
│   ├── SETS-000-settings-epic.md
│   └── ...
├── mobile/                       # Mobile-specific tasks
│   └── (future tasks)
├── task.schema.json              # JSON schema defining task structure
└── Claude.md                     # Task tracking cheatsheet
```

Tasks follow the naming pattern: `{PREFIX}-{NUMBER}-{slug}.md` and are organized into subdirectories by domain (core, interface, mobile).

## Task Schema

Every task file contains YAML frontmatter that must conform to the schema defined in `task.schema.json`.

### Required Fields

```yaml
---
id: CORE-001
title: Entry-Centric Data Model
status: Done
assignee: james
priority: High
---
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Unique identifier matching pattern `^[A-Z]+-[0-9]+$` |
| `title` | string | Human-readable title (min 5 characters) |
| `status` | enum | One of: `To Do`, `In Progress`, `Done` |
| `assignee` | string | Person responsible for the task |
| `priority` | enum | One of: `High`, `Medium`, `Low` |

### Optional Fields

```yaml
---
parent: CORE-000
tags: [core, database, epic]
whitepaper: Section 4.1
last_updated: 2025-12-02
---
```

| Field | Type | Description |
|-------|------|-------------|
| `parent` | string | Parent task ID for subtask hierarchy |
| `tags` | array | Categorization tags |
| `whitepaper` | string | Reference to design documentation |
| `last_updated` | string | ISO date of last modification |

## Task Statuses

The lifecycle of a task follows three states:

### To Do
Task has not been started. No implementation exists.

### In Progress
Task is actively being worked on. Criteria for this status:
- Some code has been written
- Feature is partially implemented
- Still has rough edges or incomplete functionality

### Done
Task is complete. All acceptance criteria must be met:
- All listed acceptance criteria are implemented
- Code is merged to main branch
- Tests pass (if applicable)
- Feature is production-ready

<Note>
Never mark a task as `Done` if implementation is partial, tests are failing, or the feature doesn't work as specified.
</Note>

## Task Prefixes

Tasks are organized by domain using prefixes. Tasks are further organized into subdirectories:

### Core Tasks (`.tasks/core/`)

Backend and Rust-related tasks:

| Prefix | Domain |
|--------|--------|
| `CORE` | Core architecture and data model |
| `JOB` | Job system and task execution |
| `INDEX` | File indexing and location management |
| `FSYNC` | File synchronization |
| `LSYNC` | Library synchronization |
| `NET` | Networking and P2P |
| `SEARCH` | Search functionality |
| `FILE` | File operations |
| `LOC` | Location management |
| `VOL` | Volume operations |
| `SEC` | Security and privacy |
| `CLI` | Command-line interface |
| `CLOUD` | Cloud integration |
| `AI` | AI and ML features |
| `PLUG` | Plugin system |
| `DEV` | Development tooling |

### Interface Tasks (`.tasks/interface/`)

Frontend and React-related tasks:

| Prefix | Domain |
|--------|--------|
| `UI` | UI primitives and design system |
| `EXPL` | Explorer interface |
| `SETS` | Settings pages |
| `SRCH` | Search UI |
| `TAG` | Tagging interface |
| `MEDIA` | Media viewer |
| `NAV` | Navigation and routing |
| `PERF` | Performance optimizations |
| `A11Y` | Accessibility |

### Mobile Tasks (`.tasks/mobile/`)

Mobile-specific tasks (future):

| Prefix | Domain |
|--------|--------|
| `IOS` | iOS native features |
| `MACOS` | macOS native features |
| `AND` | Android features |

## Task Validator CLI

The `task-validator` binary provides utilities for managing and validating tasks.

### List Tasks

View all tasks sorted by status:

```bash
cargo run --bin task-validator -- list --sort-by status
```

Output groups tasks by status (To Do, In Progress, Done):

```
=== Done ===
CORE-000: Epic: VDFS Core Architecture
CORE-001: Entry-Centric Data Model
JOB-001: Job Manager for Task Scheduling

=== In Progress ===
CLOUD-003: Cloud Volume Support

=== To Do ===
AI-002: Create Fine-tuning Dataset
```

### Filter Tasks

Filter by specific criteria:

```bash
# By status
cargo run --bin task-validator -- list --status "In Progress"

# By priority
cargo run --bin task-validator -- list --priority High

# By assignee
cargo run --bin task-validator -- list --assignee james
```

### Validate Schema

Ensure all task files conform to the schema:

```bash
cargo run --bin task-validator -- validate
```

This checks:
- YAML frontmatter is valid
- All required fields are present
- Field values match allowed enums
- ID pattern is correct
- Parent references exist

Validation runs in CI to prevent invalid tasks from being committed.

## Workflow

### Reviewing Task Status

When code has been merged, tasks should be reviewed and updated:

1. **Check recent commits**:
   ```bash
   git log --oneline -20
   ```

2. **List current task state**:
   ```bash
   cargo run --bin task-validator -- list --sort-by status
   ```

3. **For each potential completed feature**:
   - Read the task file to understand acceptance criteria
   - Read all implementation files mentioned in the task
   - Check `core/tests/` for integration tests
   - Verify each acceptance criterion is met in the code

4. **Update task status**:
   Edit the YAML frontmatter in the task file:
   ```yaml
   ---
   status: Done  # Changed from "In Progress"
   last_updated: 2025-12-02  # Update date
   ---
   ```

5. **Validate changes**:
   ```bash
   cargo run --bin task-validator -- validate
   ```

<Tip>
When unsure if a task is complete, leave it as `In Progress` rather than prematurely marking it `Done`. The tracker is only useful if it's accurate.
</Tip>

### Creating New Tasks

1. Choose appropriate subdirectory (`core/`, `interface/`, or `mobile/`)
2. Choose appropriate prefix based on domain
3. Find next available number (e.g., if `EXPL-002` exists, use `EXPL-003`)
4. Create file with pattern: `.tasks/{subdirectory}/{PREFIX}-{NUMBER}-{slug}.md`
5. Add YAML frontmatter with all required fields
6. Write task description and acceptance criteria
7. Validate:
   ```bash
   cargo run --bin task-validator -- validate
   ```

Example core task file (`.tasks/core/LSYNC-017-realtime-sync.md`):

```markdown
---
id: LSYNC-017
title: Real-time Sync Protocol
status: To Do
assignee: james
parent: LSYNC-000
priority: High
tags: [core, sync, networking]
whitepaper: Section 5.3
---

## Description

Implement a real-time synchronization protocol that pushes changes
immediately rather than relying on polling intervals.

## Implementation Notes

- Use WebSocket or similar bi-directional protocol
- Integrate with existing sync service
- Maintain backward compatibility with polling-based sync

## Acceptance Criteria

- [ ] Changes propagate within 1 second between devices
- [ ] Protocol handles network interruptions gracefully
- [ ] Fallback to polling when real-time unavailable
- [ ] Integration tests demonstrate cross-device sync
```

Example interface task file (`.tasks/interface/EXPL-004-breadcrumbs.md`):

```markdown
---
id: EXPL-004
title: Breadcrumb Navigation
status: To Do
assignee: james
parent: EXPL-000
priority: Medium
tags: [explorer, navigation, ui]
---

## Description

Implement breadcrumb navigation in the Explorer top bar showing the
current path with clickable segments.

## Implementation Notes

- Display full path as clickable segments
- Truncate middle segments if path is too long
- Show dropdown menu for segments with many children
- Keyboard navigation support

## Acceptance Criteria

- [ ] Breadcrumbs show current location path
- [ ] Click segment to navigate to that level
- [ ] Path updates when navigating
- [ ] Works with virtual locations and SD paths
- [ ] Responsive truncation for long paths
```

### Updating Task Status

When updating tasks after completing work:

**DO:**
- Read implementation files thoroughly
- Verify all acceptance criteria are met
- Check for passing integration tests
- Update `last_updated` field
- Be rigorous about what "Done" means

**DON'T:**
- Mark tasks done based on assumptions
- Skip reading the actual code
- Ignore failing tests or partial implementations
- Batch update tasks without verification

## Common Patterns

### Epic Tasks

Epics are high-level tasks that have subtasks:

```yaml
---
id: CORE-000
title: "Epic: VDFS Core Architecture"
status: Done
assignee: james
priority: High
tags: [epic, core, vdfs]
---
```

Subtasks reference their epic via the `parent` field:

```yaml
---
id: CORE-001
title: Entry-Centric Data Model
parent: CORE-000
status: Done
---
```

### Task Dependencies

While not enforced by schema, dependencies can be documented in task descriptions:

```markdown
## Dependencies

This task requires:
- CORE-001 (Entry-Centric Model) - Done
- INDEX-001 (Location Watcher) - In Progress
```

### Whitepaper References

Link tasks to design documentation:

```yaml
whitepaper: Section 4.1
```

This helps trace implementation back to architectural decisions.

## Best Practices

### Task Granularity

- **Epics**: High-level features spanning multiple subtasks
- **Tasks**: Concrete features implementable in focused work
- **Too granular**: Don't create tasks for every file or function

### Acceptance Criteria

Write specific, testable criteria:

**Good:**
```markdown
- [ ] User can add S3 bucket as a cloud volume
- [ ] Cloud volumes appear in volume list
- [ ] Files in cloud volume can be searched
```

**Bad:**
```markdown
- [ ] Implement cloud volume feature
- [ ] Make it work properly
```

### Status Accuracy

The tracker is only valuable if it reflects reality:

- Review and update tasks regularly
- Don't mark tasks done to "clean up" the list
- Keep `In Progress` honest about active work
- Archive or remove truly obsolete tasks

### Git Integration

While not automated, tasks can be referenced in commits:

```bash
git commit -m "feat: implement cloud volume indexing (CLOUD-003)"
```

This creates a searchable link between tasks and implementation:

```bash
git log --oneline --grep="CLOUD-003"
```

## Troubleshooting

### Validation Errors

**Invalid YAML**:
```
Error: Failed to parse YAML in CORE-001-entry-centric-model.md
```
Fix: Check YAML syntax, ensure frontmatter is enclosed in `---`

**Missing Required Field**:
```
Error: Missing required field 'priority' in CORE-001
```
Fix: Add the missing field to frontmatter

**Invalid Status Value**:
```
Error: Invalid status 'Complete' in CORE-001. Must be one of: To Do, In Progress, Done
```
Fix: Use exact status values from schema (case-sensitive)

### Duplicate IDs

Each task ID must be unique. If validation reports duplicates:

```bash
# Find all task IDs
grep "^id:" .tasks/*.md | sort
```

Renumber conflicting tasks and update any parent references.

### Orphaned Tasks

Tasks with `parent` fields referencing non-existent tasks:

```bash
cargo run --bin task-validator -- validate
```

Will report broken parent references. Either remove the parent field or create the missing epic.

## Examples

### Complete Epic with Subtasks

```markdown
# .tasks/SEARCH-000-semantic-search.md
---
id: SEARCH-000
title: "Epic: Semantic Search System"
status: In Progress
assignee: james
priority: High
tags: [epic, search, ai]
whitepaper: Section 6.2
---

## Description

Build a semantic search system using embeddings and vector similarity.

## Subtasks

- SEARCH-001: Async search job infrastructure
- SEARCH-002: Two-stage FTS + semantic reranking
- SEARCH-003: Unified vector repositories
```

```markdown
# .tasks/SEARCH-001-async-searchjob.md
---
id: SEARCH-001
title: Async Search Job
parent: SEARCH-000
status: Done
assignee: james
priority: High
tags: [search, jobs]
last_updated: 2025-11-15
---

## Description

Implement background search job that processes queries asynchronously.

## Acceptance Criteria

- [x] SearchJob implements Job trait
- [x] Queries execute in background thread pool
- [x] Results stream back via events
- [x] Integration test demonstrates full workflow
```

## Integration with Development

The task tracking system complements other development tools:

- **Testing**: Acceptance criteria inform test cases
- **CI/CD**: Schema validation runs in continuous integration
- **Code Review**: Task IDs provide context in pull requests
- **Documentation**: Tasks link to whitepaper design sections
- **Planning**: Status overview shows project progress

By maintaining accurate task status, the team has a real-time view of what's complete, what's in progress, and what's planned.