Skip to Content
Core ConceptsFeatures & Tasks

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
FlagEffect
--pushPush the branch when implementation finishes.
--prOpen a draft pull request (implies --push).
--no-prSkip the PR even if your default workflow opens one.
--fastImplement straight from the prompt. Default.
--no-fastRun the spec-driven phases with approval gates.
--exploreStart an exploration (prototype) session — see below.
--allow-prdAuto-approve the requirements gate (spec-driven only).
--allow-planAuto-approve the plan gate (spec-driven only).
--allow-mergeAuto-approve the merge gate: Shep merges once CI is green.
--allow-allAuto-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.
--pendingCreate 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 below

For 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" --pr

All 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