Task Tracking - Spacedrive

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

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

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

Never mark a task as Done if implementation is partial, tests are failing, or the feature doesn’t work as specified.

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:

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:

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

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:

Check recent commits:
git log --oneline -20

List current task state:

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

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

Update task status: Edit the YAML frontmatter in the task file:

---
status: Done  # Changed from "In Progress"
last_updated: 2025-12-02  # Update date
---

Validate changes:

cargo run --bin task-validator -- validate

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.

Creating New Tasks

Choose appropriate subdirectory (core/, interface/, or mobile/)
Choose appropriate prefix based on domain
Find next available number (e.g., if EXPL-002 exists, use EXPL-003)
Create file with pattern: .tasks/{subdirectory}/{PREFIX}-{NUMBER}-{slug}.md
Add YAML frontmatter with all required fields
Write task description and acceptance criteria

Validate:

cargo run --bin task-validator -- validate

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

---
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):

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

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

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

## Dependencies

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

Whitepaper References

Link tasks to design documentation:

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:

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

Bad:

- [ ] 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:

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

This creates a searchable link between tasks and implementation:

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:

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

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

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

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

​Overview

​Directory Structure

​Task Schema

​Required Fields

​Optional Fields

​Task Statuses

​To Do

​In Progress

​Done

​Task Prefixes

​Core Tasks (.tasks/core/)

​Interface Tasks (.tasks/interface/)

​Mobile Tasks (.tasks/mobile/)

​Task Validator CLI

​List Tasks

​Filter Tasks

​Validate Schema

​Workflow

​Reviewing Task Status

​Creating New Tasks

​Updating Task Status

​Common Patterns

​Epic Tasks

​Task Dependencies

​Whitepaper References

​Best Practices

​Task Granularity

​Acceptance Criteria

​Status Accuracy

​Git Integration

​Troubleshooting

​Validation Errors

​Duplicate IDs

​Orphaned Tasks

​Examples

​Complete Epic with Subtasks

​Integration with Development

Overview

Directory Structure

Task Schema

Required Fields

Optional Fields

Task Statuses

To Do

In Progress

Done

Task Prefixes

Core Tasks (`.tasks/core/`)

Interface Tasks (`.tasks/interface/`)

Mobile Tasks (`.tasks/mobile/`)

Task Validator CLI

List Tasks

Filter Tasks

Validate Schema

Workflow

Reviewing Task Status

Creating New Tasks

Updating Task Status

Common Patterns

Epic Tasks

Task Dependencies

Whitepaper References

Best Practices

Task Granularity

Acceptance Criteria

Status Accuracy

Git Integration

Troubleshooting

Validation Errors

Duplicate IDs

Orphaned Tasks

Examples

Complete Epic with Subtasks

Integration with Development