CLI UX improvements: task/tasks aliases, project completion, task status management

[vishalg0wda]

Summary

While using granary 0.5.1 for a multi-project initiative, I encountered several CLI UX friction points that made the workflow less intuitive.

Issues Encountered

1. task vs tasks subcommand confusion

Command tried: granary project <id> task create "Task name"
Error: error: unrecognized subcommand 'task'
Correct command: granary project <id> tasks create "Task name"

Suggestion: Accept singular task as an alias for tasks - this is a common pattern and more natural to type.

2. Missing add alias for tasks create

Command tried: granary project <id> tasks add "Task name"
Error: error: unrecognized subcommand 'add'
Correct command: granary project <id> tasks create "Task name"

Suggestion: Add add as an alias for create - "add a task" is more intuitive than "create a task" for many users.

3. No way to mark projects as complete

Commands tried:

• granary project <id> complete
• granary project <id> set-status done

Error: Both commands unrecognized

Suggestion: Add ability to mark projects as done/complete, e.g.:

• granary project <id> complete
• granary project <id> status done

4. Task status management unclear

Issue: Created tasks show Status: draft but there's no obvious way to:

• Mark a task as in_progress
• Mark a task as done
• Transition task states

The initiative summary showed 0.0% progress even after completing all work because I couldn't figure out how to mark tasks complete.

Suggestion: Add clear task status commands, e.g.:

• granary task <id> start (draft → in_progress)
• granary task <id> done (→ done)
• granary task <id> status <state>

Environment

• granary version: 0.5.1
• Platform: Fedora Linux 43
• Installation: Claude Code plugin

Context

I was using granary through Claude Code to manage a "Homelab Media Stack Operations" initiative with 5 projects. The CLI worked well for creating initiatives, projects, tasks, and setting up dependencies. The friction was primarily around marking work as complete.

Thanks for building granary - the project/task/dependency model is really useful for managing complex work!

[vishalg0wda]

Additional Gaps Found (granary 0.7.0)

5. No delete subcommand for projects

Command tried: granary project delete <id> --force
Error: error: unexpected argument '<id>' found

There's no delete subcommand - only archive exists. While archiving is useful, sometimes you want to permanently remove test/scratch projects.

Suggestion: Add granary project <id> delete for permanent removal, keeping archive for soft-delete.

6. --force flag not recognized on archive

Command tried: granary project <id> archive --force
What worked: granary project <id> archive (no confirmation needed anyway)

Minor issue - the archive command doesn't require confirmation, so --force isn't needed, but the flag should either be accepted (as a no-op for scripting consistency) or documented.

---

Still on v0.7.0, still loving the project/task model for managing complex work!

[danielkov]

Thank you for raising this!

1. This is a great suggestion and something I have on the roadmap!
2. I'll group this under 1. other similar sub-command would be new.
3. I intend to make project completion implicit (with an explicit option):
   • Completing the final task in a project marks it as complete or done
   • Adding a new non-complete task in a complete project throws it back to active
   • granary project <project id> done --complete-tasks to mark project and tasks as done
4. This might help:

granary task --help
Work with a specific task

Usage: granary task [OPTIONS] <ID> [COMMAND]

Commands:
  update     Update task
  ready      Mark a draft task as ready (transition Draft -> Todo)
  start      Start working on task
  done       Mark task as done
  block      Block task
  unblock    Unblock task
  claim      Claim task with a lease
  heartbeat  Extend lease (heartbeat)
  release    Release claim on task
  deps       Manage dependencies
  tasks      List or create subtasks
  comments   List or create comments
  artifacts  List or manage artifacts
  help       Print this message or the help of the given subcommand(s)

5. This is intentional. I might revisit in the future, but as a design choice, I opted to avoid destructive / non-recoverable actions. Low-end models, such as Claude Haiku routinely freak out and mass delete projects when they get confused. They're also less likely to use checkpoints. It's best to allow for simple and transparent recovery.
6. Think the missing piece here is granary project <project id> unarchive to correct accidental archives.

[danielkov]

Completed in #11