Projects, spec tasks, and the board
The core mental model. What a project is, what a spec task is, and how the Kanban board organises work.
Projects
A project is a workspace that links a set of repositories to a set of spec tasks and a configured agent. Everything in Helix — code intelligence, agent configuration, task history — is scoped to a project.
Think of a project as the intersection of:
- What you're building (the repositories)
- How you're building it (the agent configuration)
- What's in progress (the spec tasks on the board)
One project per product area or service is a common starting point. Teams with strong monorepo discipline often use one project per repo.
Spec tasks
A spec task is a discrete unit of work. You describe the desired outcome; the agent plans and implements. The task is the contract between you and the agent.
A well-formed spec task has:
- A clear, testable outcome ("the login form validates email format before submission")
- A bounded scope (one feature, one fix, one change — not "improve the whole auth flow")
- No implementation instructions — those are the agent's job
Spec tasks are not the same as tickets. Tickets track intent; spec tasks track execution. Many teams write tickets in GitHub Issues or Jira and use Helix's Optimus automation to draft spec tasks from them.
The Kanban board
Spec tasks move through stages:
| Stage | Meaning |
|---|---|
| Draft | Task written, not yet sent to the agent |
| Planning | Agent is preparing the execution plan |
| Planned | Plan ready, waiting for approval |
| Approved | Plan approved, agent about to start |
| Implementing | Agent is working in the sandbox |
| Review | Implementation done, pull request open |
| Done | PR merged |
The board gives you the status of all in-flight work at a glance. Multiple tasks can be in Planning or Implementing simultaneously.
The spec branch
When a task enters Planning, the agent pushes its plan to a helix-specs branch in your primary repository. The plan is a Markdown file — human-readable, reviewable, and versioned in git.
This branch also accumulates implementation artifacts: notes, scratch outputs, anything the agent wants to persist across sessions. The branch is never merged to main.
Agent configuration on a project
Each project has one agent configuration: which runtime (Claude Code, Goose, Qwen, Zed), which model and provider, and any runtime-specific settings (Goose recipes, for example).
The agent configuration is stored in the project YAML alongside the spec tasks. Changing the agent configuration affects new tasks; tasks already in progress continue with the agent they started with.
See Choose and configure a code agent for the runtime options.
Optimus: automated backlog management
Optimus is an optional agent you can enable on a project. When enabled, it watches your GitHub Issues on a schedule and drafts new spec tasks from them — so issues flow into the board without manual triage.
Optimus is also available interactively: ask it to plan the next sprint, estimate task complexity, or review a draft spec for completeness.