Skip to Content
Software FactoryProjects & Bug Loop

Projects and the Bug Loop

New. The bug loop (investigate → hypotheses → fix) shipped in v1.236. Projects and work items are older; their web pages sit behind the projects feature flag (on by default). The shep project, item, cycle and intake commands are always available.

A project is a list of work items, like a lightweight issue tracker inside Shep. Work items are where tracker issues land (tracker sync), where built opportunities land, and what the bug loop investigates.

Projects and work items

shep project new --name "Payments" --prefix PAY --repo ~/src/pay shep item new PAY --title "Refund fails for guest orders" --priority urgent \ --description "Refunding a guest order returns 500 since 4.12." shep item ls PAY

--repo links the project to a repository (registered with Shep if it isn’t yet). The bug loop and autopilot use it as the project’s default repository, and it decides which space the project’s work items count toward. Work items get keys from the prefix: PAY-1, PAY-2, …

Run shep project new or shep item new <project> without options to be prompted.

CommandDoes
shep project new [-n <name>] [-p <PREFIX>] [-d <text>] [-r <path>]Create a project. The prefix is 1–5 uppercase letters
shep project ls / show <slug> / del <slug> [-f]List, show, delete
shep item new <project> [-t <title>] [-p none|low|medium|high|urgent] [-d <text>] [--parent <KEY>]Create a work item; --parent makes it a sub-item
shep item ls <project>List a project’s work items (project slug or key prefix)
shep item relate <source> <target> [-t blocking|relates-to|duplicate|starts-before|finishes-before]Relate two work items (prompts for the type if omitted)
shep item export <project> [-c <columns>] [-o <file>]Export work items as CSV

In the browser, open Projects in the sidebar (/projects). Each work item has its own page with the Investigation panel described below.

Work items are also reachable from MCP clients (list_projects, list_work_items, get_work_item, create_work_item, update_work_item, delete_work_item); see MCP.

Cycles and intake

Cycles are time boxes for a project’s work items:

shep cycle new payments --name "Sprint 12" --start 2026-11-02 --end 2026-11-13 shep cycle ls payments shep cycle add-items <cycle-id> <work-item-id> [<work-item-id>...] shep cycle transfer <cycle-id> [<next-cycle-id>] # move unfinished items on, or out of the cycle shep cycle show <cycle-id>

add-items takes work item ids, not keys such as PAY-42.

Intake is a project’s triage queue. shep intake ls <project> [-s Pending|Accepted|Declined|Duplicate] lists its items, shep intake accept <id> turns one into a work item, and shep intake decline <id> [-r <reason>] declines it.

The bug loop

When a bug is a work item — typed in Shep or synced from Linear or Jira — an agent can read the code before anyone touches it, rank the likely root causes, and start a fix that proves the cause with a failing test first.

1. Investigate

On the work item page, pick the repository in the Investigation panel and press Investigate. From the terminal:

shep item investigate PAY-42 --repo ~/src/pay shep item investigate PAY-42 --agent codex-cli # another agent than your default
  • The agent works in a throwaway copy. Shep makes a detached git worktree of the repository’s current commit under your Shep home. Your checkout, its branch and uncommitted work are not touched, and the copy is deleted when the investigation ends.
  • It is read-only by instruction and, for Claude Code, by tools. Claude Code gets only Read, Grep and Glob. Other agents are told not to change anything; anything they change anyway stays in the throwaway copy.
  • It runs under the repository’s space: its Claude and GitHub logins and its allowed agents apply. If the space doesn’t allow the agent, nothing runs and Shep says why.
  • Repository. Without --repo, Shep uses the repository of the item’s last investigation, then the project’s repository. If it knows neither, it asks you to pick one.
  • Time. An investigation usually takes a few minutes and is stopped after 20. Only one investigation of an item runs at a time. shep item investigate waits and prints the result; the web panel updates by itself.

2. Read the hypotheses

The agent returns up to five hypotheses, most likely first. Each has:

PartMeaning
Root causeWhat goes wrong, in terms of the code
ConfidenceHigh when the code shows the defect directly, Medium when it fits the report but isn’t confirmed, Low when the evidence is thin
EvidenceFiles and lines the agent read, with what each shows
Failing testThe test that would fail today because of this cause
FixThe smallest change that fixes it
shep item hypotheses PAY-42 # print the latest investigation again

If the agent can’t match the report to the code, the investigation fails and its summary says why. Try another repository or add detail to the work item.

3. Fix

Press Fix this on a hypothesis, or:

shep item fix PAY-42 1 # Fast mode shep item fix PAY-42 1 --spec # the full spec-driven pipeline shep item fix PAY-42 2 --agent claude-code

Shep creates a feature named Fix PAY-42: <hypothesis title> in the investigated repository. Its agent is told to:

  1. write the failing test first and confirm it fails for the diagnosed reason — and if the test passes, stop and report instead of changing code;
  2. make the fix;
  3. run the tests.

From there it is an ordinary feature: worktree, approval gates, CI and pull request as you have them configured. The fix uses the investigating agent unless you pass --agent.

The work item moves to its project’s Started state. If the item came from a two-way sync rule, the Linear or Jira issue follows at the next sync.

One hypothesis per investigation becomes a fix. To try another cause, investigate again.

Autopilot can run steps 1 and 3 on its own for Urgent work items when you turn it on for a space.

See also