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
{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
=== 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
- 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:
-
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
.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]
---
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:
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
- [ ] 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)"
git log --oneline --grep="CLOUD-003"
Troubleshooting
Validation Errors
Invalid YAML:
Error: Failed to parse YAML in CORE-001-entry-centric-model.md
---
Missing Required Field:
Error: Missing required field 'priority' in CORE-001
Error: Invalid status 'Complete' in CORE-001. Must be one of: To Do, In Progress, Done
Duplicate IDs
Each task ID must be unique. If validation reports duplicates:
# Find all task IDs
grep "^id:" .tasks/*.md | sort
Orphaned Tasks
Tasks with parent fields referencing non-existent tasks:
cargo run --bin task-validator -- validate
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. 