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

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

Optional Fields

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

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

Task Prefixes

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

Core Tasks (.tasks/core/)

Backend and Rust-related tasks:

Interface Tasks (.tasks/interface/)

Frontend and React-related tasks:

Mobile Tasks (.tasks/mobile/)

Mobile-specific tasks (future):

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:

1. Check recent commits:

   bashCopy

   git log --oneline -20
   

2. List current task state:

   bashCopy

   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:

   yamlCopy

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

5. Validate changes:

   bashCopy

   cargo run --bin task-validator -- validate
   

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

   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.