spacedrive/.tasks/Claude.md

Task Tracking Cheatsheet

Hi Claude, Claude here. Your owner has pointed you here with absolutely no context. This document is your prompt.

This directory tracks the complete development of Spacedrive. Tasks are always kept up-to-date, though some may need updating based on recent work. Your job is to check git history for changes, validate completed tasks against the instructions below, and update their status accordingly.

Quick Start

When asked to review and update tasks, follow this process:

1. List Current Tasks

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

This shows all tasks grouped by status (Completed, Done, In Progress, To Do).

2. Review Recent Commits

git log --oneline -20

Look for feature implementations, major refactors, or completed work that might correspond to tasks.

3. Cross-Reference Work with Tasks

For each recent feature/change:

• Read the task file directly from .tasks/TASK-ID-name.md
• Read the acceptance criteria carefully - this is your checklist
• Read all implementation files mentioned in the task (they're usually listed in an "Implementation Files" section)
• Check core/tests/ for integration tests that validate the feature
• Verify each acceptance criterion is actually met in the code

4. Update Task Status

When updating a task's status, edit the YAML front matter:

---
id: TASK-000
title: Task Title
status: Done # Changed from "To Do" or "In Progress"
assignee: james
priority: High
tags: [core, feature]
last_updated: 2025-10-14 # Update this date
---

Status Levels:

• To Do - Not started
• In Progress - Actively being worked on
• Done - Complete and merged
• Completed - Same as Done (legacy)

5. Validate Changes

Before committing task updates, validate them:

cargo run --bin task-validator -- validate

This checks that your YAML front matter matches the schema.

Task Status Guidelines

Mark as "Done" when:

• All acceptance criteria are met
• Code is merged to main
• Tests pass (if applicable)
• Feature is actually usable

Keep "In Progress" when:

• ️ Partially implemented
• ️ Core work done but rough edges remain
• ️ Actively being iterated on

Keep "To Do" when:

• Not started
• Only design/planning done
• Mentioned in docs but no code exists

Pro Tips

1. Read implementation files directly - Open and read the actual source files mentioned in the task.

2. Always check core/tests/ for integration tests that validate the feature works end-to-end.

3. Check recent file changes:

   git diff --name-only HEAD~10
   

4. Search commits by keyword:

   git log --oneline --grep="volume\|cloud" -i
   

5. Filter tasks by criteria:

   # Show only "In Progress" tasks
   cargo run --bin task-validator -- list --status "In Progress"
   
   # Show tasks by priority
   cargo run --bin task-validator -- list --priority High
   

Common Pitfalls

Don't mark tasks done if:

• Implementation exists but doesn't work
• Only scaffolding/types are defined
• Tests are failing
• Feature is behind a feature flag and disabled

Do mark tasks done if:

• All acceptance criteria are genuinely met
• Implementation is production-ready
• Code demonstrates the feature working

Example Workflow

# 1. See current state
cargo run --bin task-validator -- list --sort-by status

# 2. Check what's been done recently
git log --oneline -15

# 3. Found "feat: implement cloud volume support" commit
#    Let's check CLOUD-003 task

Now use the Read tool to thoroughly verify:

# 4. Read the task file
Read .tasks/CLOUD-003-cloud-volume.md

# 5. Read every implementation file listed in the task
Read core/src/volume/backend/mod.rs
Read core/src/volume/backend/cloud.rs
Read core/src/ops/volumes/add_cloud/mod.rs
... (read all mentioned files)

# 6. Check for integration tests
Glob core/tests/**/*.rs
Read core/tests/test_cloud_volume.rs  # if it exists

# 7. Verify each acceptance criterion:
#    - [x] User can add S3 bucket? Check add_cloud action code
#    - [x] Cloud volume can be indexed? Check indexer integration
#    - [ ] Files can be copied to/from cloud? Search for copy implementation
#
# If ALL criteria met → mark "Done"
# If SOME criteria met → keep "In Progress"
# If implementation looks complete → Update status and last_updated date

# 8. Validate before committing
```bash
cargo run --bin task-validator -- validate

Task Schema Reference

Required fields in YAML front matter:

• id - Unique identifier (e.g., CORE-001)
• title - Human-readable title
• status - One of: To Do, In Progress, Done, Completed
• assignee - Who's working on it (or "james")
• priority - Critical, High, Medium, or Low
• tags - Array of relevant tags

Optional fields:

• parent - Parent epic/task ID
• whitepaper - Reference to design docs
• last_updated - ISO date of last update
• related_tasks - Array of related task IDs

---

Remember: The task tracker is only useful if it's honest. Be rigorous about what "Done" means. When in doubt, leave it as "In Progress" and document what's left.

— Past Claude, trying to help Future Claude (that's you!)