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 handles everything else.

Every feature has:

  • A name — a slug like add-health-endpoint (Shep generates this from your description).
  • A description — the prompt you provided.
  • A branch — created automatically (e.g. feat/add-health-endpoint).
  • A worktree — under ~/.shep/ so it never touches your main checkout.
  • A current phase — where the feature is in its lifecycle.
  • An agent run — the AI agent process implementing it.

Creating features

From the CLI:

shep feat new "add a /health endpoint that returns uptime and version"

From the web dashboard, click + New Feature, type your description, choose your automations, and click Create.

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.
--fastSkip spec-driven phases. Default.
--no-fastUse the full spec-driven pipeline with approval gates.
--allow-prdAuto-approve the PRD gate (only meaningful with --no-fast).
--allow-planAuto-approve the plan gate (only meaningful with --no-fast).
--allow-mergeAuto-merge the PR after CI passes.
--allow-allEnable all automations: push, PR, all gates auto-approved, auto-merge.
--model <id>Override the agent’s model for this feature.
--attach <path>Attach reference files (designs, code samples) to the prompt.
--repo <path>Run against a different repo without cd.
--remote <url>Clone a remote repo and run there (useful for one-off experiments).
--parent <fid>Create this feature as a child of an existing one.

Run shep feat new --help for the full list including --no-rebase, --inject-skills, and --pending.

Managing features

shep feat ls                        # list features in the current repo
shep feat show <id>                 # full detail: status, plan, agent activity
shep feat logs <id>                 # stream logs (agent output + phase changes)
shep feat resume <id>               # resume a paused or interrupted feature
shep feat archive <id>              # hide a feature without deleting it
shep feat unarchive <id>            # bring it back
shep feat del <id>                  # delete the feature and clean up its worktree

You can use the feature ID (feat_abc123) or its slug (add-health-endpoint).

Parallel features

Each feature runs in its own worktree with its own branch and its own agent process. They are completely isolated — start as many as you want:

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 simultaneously. Watch them all in the dashboard or with shep feat ls.

Tasks

Tasks are the steps inside a feature. When Shep runs the spec-driven pipeline (--no-fast), it produces a plan made of tasks — each one a discrete, reviewable step like “write the controller,” “add the route,” “write tests.”

In fast mode (the default), there are no explicit tasks — the agent receives the prompt and implements it 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.

Whether the work is broken into tasks or not, Shep tracks every state change. Use shep feat show <id> or the dashboard to see exactly where the agent is.

What’s next

How Shep WorksSDLC Lifecycle