Features & Tasks
Everything Shep does is organized around two ideas: features and tasks.
Features
A feature is one unit of work — anything from “fix the login button color” to “add user authentication.” You describe it in plain English; Shep runs an agent on it.
Every feature has:
- An ID — a UUID. Commands accept the full ID or any unique prefix of it (e.g.
1a2b). - A name and description — Shep derives a short name from your prompt.
- A branch — created automatically (e.g.
feat/add-health-endpoint). - A worktree — under
~/.shep/repos/<repo-hash>/wt/<branch-slug>, so it never touches your main checkout. - A repository, and possibly an app — the repo it runs in. Features created inside an app’s folder belong to that app.
- A lifecycle phase — where the feature is in its lifecycle.
- An agent run — the agent process working on it, with its own activity state.
- Pinned settings — the agent, model, reasoning effort, gates and git options it was created with.
Creating features
From the CLI:
shep feat new "add a /health endpoint that returns uptime and version"From the web UI, click + New on a repository in the Control Center (or the round + button), describe the feature and click Create Feature. You can also ask for one in Chat.
Common flags
shep feat new "add stripe checkout" --push --pr --allow-merge| Flag | Effect |
|---|---|
--push | Push the branch when implementation finishes. |
--pr | Open a draft pull request (implies --push). |
--no-pr | Skip the PR even if your default workflow opens one. |
--fast | Implement straight from the prompt. Default. |
--no-fast | Run the spec-driven phases with approval gates. |
--explore | Start an exploration (prototype) session — see below. |
--allow-prd | Auto-approve the requirements gate (spec-driven only). |
--allow-plan | Auto-approve the plan gate (spec-driven only). |
--allow-merge | Auto-approve the merge gate: Shep merges once CI is green. |
--allow-all | Auto-approve all three gates. Push and PR are still controlled by --push / --pr. |
--model <id> | Model for this feature. |
--effort <level> | Reasoning effort (low … max). Only Claude Code uses it. |
--attach <path> | Attach a file (design, code sample, spec). Repeatable. |
--repo <path> | Run against another local repo without cd. |
--remote <url> | A GitHub URL or owner/repo. Shep clones it into your clone directory (~/repos by default), forks it first if you can’t push to it, and opens the PR upstream. Can’t be combined with --repo. |
--parent <id> | Create a child feature. It waits (lifecycle Blocked) until its parent’s work lands, then starts on top of it. |
--pending | Create the feature without starting the agent. Start it later with shep feat start <id>. |
Run shep feat new --help for the full list, including --no-rebase, --inject-skills / --no-inject-skills, and the self-learning --explore-harness option.
Managing features
shep feat ls # list features (-r <path> to filter, --show-archived)
shep feat show <id> # full detail: status, settings, PR, worktree
shep feat status <id> # what the agent is doing right now, and why
shep feat wait <id> # block until the agent needs you or stops
shep feat logs <id> -f # follow the agent's log
shep feat approve [id] # approve the gate it's waiting at
shep feat reject [id] --reason "…" # send it back with feedback
shep feat start <id> # start a pending feature
shep feat resume <id> # resume a stopped or failed run
shep feat archive <id> # hide it from the canvas
shep feat unarchive <id> # bring it back
shep feat del <id> # delete it — see belowFor approve, reject and review the ID is optional: without it, Shep picks the one feature in the current repo that is waiting for approval (and asks you to name it if there are several).
shep feat del <id> asks for confirmation, then removes the worktree, the local branch and the remote branch, and closes the open PR. Use --no-cleanup to keep the worktree and branches, --no-close-pr to leave the PR open, or --force to skip the prompts.
More commands — adopting an existing branch, PR review comments, checkpoints — are in the CLI Reference.
Parallel features
Each feature runs in its own worktree with its own branch and agent process:
shep feat new "add user authentication" --pr
shep feat new "migrate database to postgres" --pr
shep feat new "add rate limiting to the API" --prAll three run at once unless you’ve set a parallel limit, in which case extra features queue as Pending. See Fleet management.
When a feature is done
Once a feature reaches Maintain (merged or completed), Shep archives it automatically after 10 minutes so the canvas stays tidy. Change the delay, or set it to 0 to turn it off, in Settings → Workflow.
Tasks
Tasks are the steps inside a feature. In spec-driven mode (--no-fast), Shep produces a plan made of tasks — each one a discrete, reviewable step like “write the controller,” “add the route,” “write tests.” The Plan tab shows their progress.
In fast mode (the default) there are no explicit tasks — the agent implements the prompt directly. Fast mode is right for most work; spec-driven mode is for larger features where you want a plan to review before any code is written. See Spec-Driven Mode.
Exploration mode
shep feat new "…" --explore starts a prototyping session instead of a normal run. The agent builds a prototype (shown in the Prototype tab), you iterate on it with shep feat feedback <id> "make the header sticky", and when you like it you turn it into a real feature with shep feat promote <id> (add --fast to skip the spec phases).
What’s next
- SDLC Lifecycle — the phases a feature moves through.
- Agent activity & states — what
shep feat statustells you. - Spec-Driven Mode — when to add approval gates and tasks.