Skip to main content

​
Projects

A project is a named container that groups tasks, boards, and releases into a coherent initiative. Projects provide the organizational layer between individual tasks and the overall system.

​
What Projects Do

Projects serve three purposes:
  1. Scope tasks — every task belongs to a project, making it easy to filter and track work per initiative
  2. Scope boards — boards can be project-specific, so different teams use pipelines suited to their workflow
  3. Auto-detection — when you run task commands inside a git repo, the project is detected from the working directory

​
Creating Projects

Projects are created explicitly or auto-detected from repository paths (see the Project CLI reference for all commands): 
genie project create mobile-app --description "iOS and Android app"
When you create a task inside a repo that has no project, one is auto-created from the repository name.

​
Default Project

When running commands outside a git repository, Genie needs to know which project to scope to. Set a default: 
genie project set-default myapp
This default is used for genie task list, genie task create, and other task commands when no repo is detected.

​
Projects and Boards

Each project can have multiple boards. A typical setup: 
Project: myapp
├── Board: Sprint 12     (active — current sprint)
├── Board: Backlog       (incoming work)
└── Board: Bug Triage    (bug-specific pipeline)
Set the active board for a project: 
genie board use "Sprint 12"

​
Projects and Tasks

Tasks reference their project via project_id. When listing tasks, you can filter by project: 
genie task list --project myapp
For scripting, the JSON output includes repoPath for reliable filtering: 
genie task list --all --json > /tmp/tasks.json
jq '.[] | select(.repoPath | test("myapp"))' /tmp/tasks.json

​
Project Stats

View a project’s health at a glance: 
genie project show myapp
This displays task counts by stage, active boards, and overall completion metrics.

​
Database Storage

Projects are stored in the projects table (migration 003) with a reference to the repo path. Task-project relationships are maintained through the tasks.project_id foreign key.

​
Best Practices

Map projects 1:1 with git repositories. This makes auto-detection seamless and keeps task scoping intuitive.
Instead of creating separate projects for features vs. bugs, use different boards within the same project.
If you primarily work on one project, genie project set-default saves typing --project on every command.