@shepai/cli 1.156.0-pr487.27d2745 → 1.156.0-pr489.56abb36

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (160) hide show
  1. package/README.md +258 -161
  2. package/package.json +1 -1
  3. package/web/.next/BUILD_ID +1 -1
  4. package/web/.next/build-manifest.json +2 -2
  5. package/web/.next/fallback-build-manifest.json +2 -2
  6. package/web/.next/prerender-manifest.json +3 -3
  7. package/web/.next/required-server-files.js +1 -1
  8. package/web/.next/required-server-files.json +1 -1
  9. package/web/.next/server/app/(dashboard)/@drawer/adopt/page/server-reference-manifest.json +28 -28
  10. package/web/.next/server/app/(dashboard)/@drawer/adopt/page.js.nft.json +1 -1
  11. package/web/.next/server/app/(dashboard)/@drawer/adopt/page_client-reference-manifest.js +1 -1
  12. package/web/.next/server/app/(dashboard)/@drawer/chat/page/server-reference-manifest.json +26 -26
  13. package/web/.next/server/app/(dashboard)/@drawer/chat/page.js.nft.json +1 -1
  14. package/web/.next/server/app/(dashboard)/@drawer/chat/page_client-reference-manifest.js +1 -1
  15. package/web/.next/server/app/(dashboard)/@drawer/create/page/server-reference-manifest.json +29 -29
  16. package/web/.next/server/app/(dashboard)/@drawer/create/page.js.nft.json +1 -1
  17. package/web/.next/server/app/(dashboard)/@drawer/create/page_client-reference-manifest.js +1 -1
  18. package/web/.next/server/app/(dashboard)/@drawer/feature/[featureId]/[tab]/page/server-reference-manifest.json +36 -36
  19. package/web/.next/server/app/(dashboard)/@drawer/feature/[featureId]/[tab]/page.js.nft.json +1 -1
  20. package/web/.next/server/app/(dashboard)/@drawer/feature/[featureId]/[tab]/page_client-reference-manifest.js +1 -1
  21. package/web/.next/server/app/(dashboard)/@drawer/feature/[featureId]/page/server-reference-manifest.json +36 -36
  22. package/web/.next/server/app/(dashboard)/@drawer/feature/[featureId]/page.js.nft.json +1 -1
  23. package/web/.next/server/app/(dashboard)/@drawer/feature/[featureId]/page_client-reference-manifest.js +1 -1
  24. package/web/.next/server/app/(dashboard)/@drawer/repository/[repositoryId]/[tab]/page/server-reference-manifest.json +26 -26
  25. package/web/.next/server/app/(dashboard)/@drawer/repository/[repositoryId]/[tab]/page.js.nft.json +1 -1
  26. package/web/.next/server/app/(dashboard)/@drawer/repository/[repositoryId]/[tab]/page_client-reference-manifest.js +1 -1
  27. package/web/.next/server/app/(dashboard)/@drawer/repository/[repositoryId]/page/server-reference-manifest.json +26 -26
  28. package/web/.next/server/app/(dashboard)/@drawer/repository/[repositoryId]/page.js.nft.json +1 -1
  29. package/web/.next/server/app/(dashboard)/@drawer/repository/[repositoryId]/page_client-reference-manifest.js +1 -1
  30. package/web/.next/server/app/(dashboard)/chat/page/server-reference-manifest.json +26 -26
  31. package/web/.next/server/app/(dashboard)/chat/page.js.nft.json +1 -1
  32. package/web/.next/server/app/(dashboard)/chat/page_client-reference-manifest.js +1 -1
  33. package/web/.next/server/app/(dashboard)/create/page/server-reference-manifest.json +29 -29
  34. package/web/.next/server/app/(dashboard)/create/page.js.nft.json +1 -1
  35. package/web/.next/server/app/(dashboard)/create/page_client-reference-manifest.js +1 -1
  36. package/web/.next/server/app/(dashboard)/feature/[featureId]/[tab]/page/server-reference-manifest.json +36 -36
  37. package/web/.next/server/app/(dashboard)/feature/[featureId]/[tab]/page.js.nft.json +1 -1
  38. package/web/.next/server/app/(dashboard)/feature/[featureId]/[tab]/page_client-reference-manifest.js +1 -1
  39. package/web/.next/server/app/(dashboard)/feature/[featureId]/page/server-reference-manifest.json +36 -36
  40. package/web/.next/server/app/(dashboard)/feature/[featureId]/page.js.nft.json +1 -1
  41. package/web/.next/server/app/(dashboard)/feature/[featureId]/page_client-reference-manifest.js +1 -1
  42. package/web/.next/server/app/(dashboard)/page/server-reference-manifest.json +26 -26
  43. package/web/.next/server/app/(dashboard)/page.js.nft.json +1 -1
  44. package/web/.next/server/app/(dashboard)/page_client-reference-manifest.js +1 -1
  45. package/web/.next/server/app/(dashboard)/repository/[repositoryId]/[tab]/page/server-reference-manifest.json +26 -26
  46. package/web/.next/server/app/(dashboard)/repository/[repositoryId]/[tab]/page.js.nft.json +1 -1
  47. package/web/.next/server/app/(dashboard)/repository/[repositoryId]/[tab]/page_client-reference-manifest.js +1 -1
  48. package/web/.next/server/app/(dashboard)/repository/[repositoryId]/page/server-reference-manifest.json +26 -26
  49. package/web/.next/server/app/(dashboard)/repository/[repositoryId]/page.js.nft.json +1 -1
  50. package/web/.next/server/app/(dashboard)/repository/[repositoryId]/page_client-reference-manifest.js +1 -1
  51. package/web/.next/server/app/_global-error.html +2 -2
  52. package/web/.next/server/app/_global-error.rsc +1 -1
  53. package/web/.next/server/app/_global-error.segments/__PAGE__.segment.rsc +1 -1
  54. package/web/.next/server/app/_global-error.segments/_full.segment.rsc +1 -1
  55. package/web/.next/server/app/_global-error.segments/_head.segment.rsc +1 -1
  56. package/web/.next/server/app/_global-error.segments/_index.segment.rsc +1 -1
  57. package/web/.next/server/app/_global-error.segments/_tree.segment.rsc +1 -1
  58. package/web/.next/server/app/_not-found/page/server-reference-manifest.json +5 -5
  59. package/web/.next/server/app/_not-found/page.js.nft.json +1 -1
  60. package/web/.next/server/app/_not-found/page_client-reference-manifest.js +1 -1
  61. package/web/.next/server/app/settings/page/server-reference-manifest.json +8 -8
  62. package/web/.next/server/app/settings/page.js.nft.json +1 -1
  63. package/web/.next/server/app/settings/page_client-reference-manifest.js +1 -1
  64. package/web/.next/server/app/skills/page/server-reference-manifest.json +10 -10
  65. package/web/.next/server/app/skills/page.js.nft.json +1 -1
  66. package/web/.next/server/app/skills/page_client-reference-manifest.js +1 -1
  67. package/web/.next/server/app/tools/page/server-reference-manifest.json +10 -10
  68. package/web/.next/server/app/tools/page.js.nft.json +1 -1
  69. package/web/.next/server/app/tools/page_client-reference-manifest.js +1 -1
  70. package/web/.next/server/app/version/page/server-reference-manifest.json +5 -5
  71. package/web/.next/server/app/version/page.js.nft.json +1 -1
  72. package/web/.next/server/app/version/page_client-reference-manifest.js +1 -1
  73. package/web/.next/server/chunks/[root-of-the-server]__a402b567._.js +1 -1
  74. package/web/.next/server/chunks/ssr/744ca_web_components_common_control-center-drawer_create-drawer-client_tsx_5e26fc0a._.js +1 -1
  75. package/web/.next/server/chunks/ssr/744ca_web_components_common_control-center-drawer_create-drawer-client_tsx_5e26fc0a._.js.map +1 -1
  76. package/web/.next/server/chunks/ssr/744ca_web_components_common_control-center-drawer_feature-drawer-client_tsx_e9755fc8._.js +2 -2
  77. package/web/.next/server/chunks/ssr/744ca_web_components_common_control-center-drawer_feature-drawer-client_tsx_e9755fc8._.js.map +1 -1
  78. package/web/.next/server/chunks/ssr/[root-of-the-server]__17ed7ed1._.js +1 -1
  79. package/web/.next/server/chunks/ssr/[root-of-the-server]__17ed7ed1._.js.map +1 -1
  80. package/web/.next/server/chunks/ssr/[root-of-the-server]__28d0d265._.js +2 -2
  81. package/web/.next/server/chunks/ssr/[root-of-the-server]__357d99f9._.js +1 -1
  82. package/web/.next/server/chunks/ssr/[root-of-the-server]__42bf1807._.js +1 -1
  83. package/web/.next/server/chunks/ssr/[root-of-the-server]__42bf1807._.js.map +1 -1
  84. package/web/.next/server/chunks/ssr/[root-of-the-server]__56b70465._.js +1 -1
  85. package/web/.next/server/chunks/ssr/[root-of-the-server]__56b70465._.js.map +1 -1
  86. package/web/.next/server/chunks/ssr/[root-of-the-server]__88f7e8e6._.js +1 -1
  87. package/web/.next/server/chunks/ssr/[root-of-the-server]__88f7e8e6._.js.map +1 -1
  88. package/web/.next/server/chunks/ssr/[root-of-the-server]__8b0aac03._.js +1 -1
  89. package/web/.next/server/chunks/ssr/[root-of-the-server]__c30f1f82._.js +1 -1
  90. package/web/.next/server/chunks/ssr/[root-of-the-server]__c30f1f82._.js.map +1 -1
  91. package/web/.next/server/chunks/ssr/[root-of-the-server]__f80bfc75._.js +1 -1
  92. package/web/.next/server/chunks/ssr/[root-of-the-server]__f80bfc75._.js.map +1 -1
  93. package/web/.next/server/chunks/ssr/[root-of-the-server]__f8dd4422._.js +1 -1
  94. package/web/.next/server/chunks/ssr/[root-of-the-server]__f8dd4422._.js.map +1 -1
  95. package/web/.next/server/chunks/ssr/_05c23ad9._.js +1 -1
  96. package/web/.next/server/chunks/ssr/_05c23ad9._.js.map +1 -1
  97. package/web/.next/server/chunks/ssr/_16eb4fec._.js +1 -1
  98. package/web/.next/server/chunks/ssr/_16eb4fec._.js.map +1 -1
  99. package/web/.next/server/chunks/ssr/{_06d729d4._.js → _179cf1be._.js} +2 -2
  100. package/web/.next/server/chunks/ssr/{_06d729d4._.js.map → _179cf1be._.js.map} +1 -1
  101. package/web/.next/server/chunks/ssr/_3a0b989f._.js +2 -2
  102. package/web/.next/server/chunks/ssr/_3a0b989f._.js.map +1 -1
  103. package/web/.next/server/chunks/ssr/_56b9d60f._.js +1 -1
  104. package/web/.next/server/chunks/ssr/_56b9d60f._.js.map +1 -1
  105. package/web/.next/server/chunks/ssr/_5f69c13f._.js +1 -1
  106. package/web/.next/server/chunks/ssr/_5f69c13f._.js.map +1 -1
  107. package/web/.next/server/chunks/ssr/{_c2d7b7db._.js → _77182425._.js} +2 -2
  108. package/web/.next/server/chunks/ssr/{_c2d7b7db._.js.map → _77182425._.js.map} +1 -1
  109. package/web/.next/server/chunks/ssr/_7c5b97c6._.js +1 -1
  110. package/web/.next/server/chunks/ssr/_7c5b97c6._.js.map +1 -1
  111. package/web/.next/server/chunks/ssr/_82c57f10._.js +1 -1
  112. package/web/.next/server/chunks/ssr/_82c57f10._.js.map +1 -1
  113. package/web/.next/server/chunks/ssr/_9495d50b._.js +1 -1
  114. package/web/.next/server/chunks/ssr/_9495d50b._.js.map +1 -1
  115. package/web/.next/server/chunks/ssr/_a0e3f7e4._.js +1 -1
  116. package/web/.next/server/chunks/ssr/_a0e3f7e4._.js.map +1 -1
  117. package/web/.next/server/chunks/ssr/_ac4a3873._.js +1 -1
  118. package/web/.next/server/chunks/ssr/_ac4a3873._.js.map +1 -1
  119. package/web/.next/server/chunks/ssr/_ca0aa7f0._.js +1 -1
  120. package/web/.next/server/chunks/ssr/_ca0aa7f0._.js.map +1 -1
  121. package/web/.next/server/chunks/ssr/_cb5a021e._.js +1 -1
  122. package/web/.next/server/chunks/ssr/_cb5a021e._.js.map +1 -1
  123. package/web/.next/server/chunks/ssr/{_324b80d9._.js → _ce8c6f41._.js} +2 -2
  124. package/web/.next/server/chunks/ssr/{_324b80d9._.js.map → _ce8c6f41._.js.map} +1 -1
  125. package/web/.next/server/chunks/ssr/_d86175ae._.js +1 -1
  126. package/web/.next/server/chunks/ssr/_d86175ae._.js.map +1 -1
  127. package/web/.next/server/chunks/ssr/_d8bedf13._.js +1 -1
  128. package/web/.next/server/chunks/ssr/_d8bedf13._.js.map +1 -1
  129. package/web/.next/server/chunks/ssr/_fa7efce3._.js +2 -2
  130. package/web/.next/server/chunks/ssr/_fa7efce3._.js.map +1 -1
  131. package/web/.next/server/chunks/ssr/b1a17_presentation_web_components_features_settings_settings-page-client_tsx_6ed9d5f8._.js +1 -1
  132. package/web/.next/server/chunks/ssr/b1a17_presentation_web_components_features_settings_settings-page-client_tsx_6ed9d5f8._.js.map +1 -1
  133. package/web/.next/server/chunks/ssr/src_presentation_web__next-internal_server_app_skills_page_actions_cdc632e3.js +1 -1
  134. package/web/.next/server/chunks/ssr/src_presentation_web__next-internal_server_app_skills_page_actions_cdc632e3.js.map +1 -1
  135. package/web/.next/server/chunks/ssr/src_presentation_web__next-internal_server_app_tools_page_actions_39ca0924.js +1 -1
  136. package/web/.next/server/chunks/ssr/src_presentation_web__next-internal_server_app_tools_page_actions_39ca0924.js.map +1 -1
  137. package/web/.next/server/chunks/ssr/src_presentation_web_app_actions_open-ide_ts_baaca5d5._.js +1 -1
  138. package/web/.next/server/chunks/ssr/src_presentation_web_components_357e3eb0._.js +1 -1
  139. package/web/.next/server/chunks/ssr/src_presentation_web_components_357e3eb0._.js.map +1 -1
  140. package/web/.next/server/chunks/ssr/src_presentation_web_components_features_control-center_7ac3562e._.js +1 -1
  141. package/web/.next/server/chunks/ssr/src_presentation_web_components_features_control-center_7ac3562e._.js.map +1 -1
  142. package/web/.next/server/pages/500.html +2 -2
  143. package/web/.next/server/server-reference-manifest.js +1 -1
  144. package/web/.next/server/server-reference-manifest.json +45 -45
  145. package/web/.next/static/chunks/{d7dc5e69935dd50a.js → 0848dd3a984c5e86.js} +1 -1
  146. package/web/.next/static/chunks/{451b739f780a1316.js → 1d8e83c00fb843ee.js} +1 -1
  147. package/web/.next/static/chunks/{11f9d194a808e762.js → 221a86cb04bffcaf.js} +1 -1
  148. package/web/.next/static/chunks/{b270cd01d6c84cc3.js → 2de20e03dad5a7f0.js} +2 -2
  149. package/web/.next/static/chunks/{519efb70d16e58e1.js → 4bb7992ddb78c6a1.js} +1 -1
  150. package/web/.next/static/chunks/{67796fc8bc518eb9.js → 5dc5f99c7d5debc1.js} +1 -1
  151. package/web/.next/static/chunks/{dda3b05bd1c7d22e.js → 5f84b6ed5c5b48da.js} +2 -2
  152. package/web/.next/static/chunks/{79224190c8193749.js → 6d2af83c6b7f6020.js} +1 -1
  153. package/web/.next/static/chunks/{7c3c90336df83f48.js → 76ca017cf58215a0.js} +3 -3
  154. package/web/.next/static/chunks/{6d8e30b4c0d6489f.js → 89b93f12718f58e0.js} +1 -1
  155. package/web/.next/static/chunks/{4a808ad7b2ee7e06.js → a358cdad9fe8d6bc.js} +1 -1
  156. package/web/.next/static/chunks/fa5d319be3df7071.js +1 -0
  157. package/web/.next/static/chunks/2a409a06c9f8e1f2.js +0 -1
  158. /package/web/.next/static/{YJAjXJ0PmVhoQ7S_uBBDz → KB8KOezkUq0uueUEtffWG}/_buildManifest.js +0 -0
  159. /package/web/.next/static/{YJAjXJ0PmVhoQ7S_uBBDz → KB8KOezkUq0uueUEtffWG}/_clientMiddlewareManifest.json +0 -0
  160. /package/web/.next/static/{YJAjXJ0PmVhoQ7S_uBBDz → KB8KOezkUq0uueUEtffWG}/_ssgManifest.js +0 -0
package/README.md CHANGED
@@ -1,259 +1,356 @@
1
1
  <div align="center">
2
2
 
3
- # Shep AI
3
+ <h1>
4
+ <picture>
5
+ <source media="(prefers-color-scheme: dark)" srcset="src/presentation/web/public/favicon-light.svg">
6
+ <source media="(prefers-color-scheme: light)" srcset="src/presentation/web/public/favicon-dark.svg">
7
+ <img src="src/presentation/web/public/favicon-light.svg" alt="Shep logo" width="28" valign="middle" />
8
+ </picture>
9
+ Shep
10
+ </h1>
4
11
 
5
- ### One command. Full lifecycle. Merged PR.
12
+ ### Run multiple AI agents in parallel. Each in its own worktree.
6
13
 
7
- _Describe a feature in plain English Shep researches, plans, codes, tests, and opens a PR. You approve when you want to, or let it run hands-free._
14
+ _Manage 10 features at onceisolated branches, automatic commits, CI watching, and PRs from a dashboard or the terminal._
8
15
 
9
16
  [![CI](https://github.com/shep-ai/cli/actions/workflows/ci.yml/badge.svg)](https://github.com/shep-ai/cli/actions/workflows/ci.yml)
10
17
  [![npm version](https://img.shields.io/npm/v/@shepai/cli.svg?color=cb3837&logo=npm)](https://www.npmjs.com/package/@shepai/cli)
11
18
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
12
- [![TypeScript](https://img.shields.io/badge/TypeScript-5.3+-3178c6.svg?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
13
- [![Node.js](https://img.shields.io/badge/Node.js-≥18-339933.svg?logo=node.js&logoColor=white)](https://nodejs.org/)
14
- [![pnpm](https://img.shields.io/badge/pnpm-≥8-f69220.svg?logo=pnpm&logoColor=white)](https://pnpm.io/)
15
- [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/shep-ai/cli/pulls)
16
- [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-fe5196.svg?logo=conventionalcommits&logoColor=white)](https://conventionalcommits.org)
17
19
 
18
- <br />
19
-
20
- [Features](#features) · [Quick Start](#quick-start) · [CLI Reference](#cli-reference) · [Architecture](#architecture) · [Contributing](#contributing)
20
+ [Quick Start](#quick-start) · [How It Works](#how-it-works) · [Features](#features) · [Trust & Safety](#trust--safety) · [FAQ](#faq)
21
21
 
22
22
  <br />
23
23
 
24
- <img src="docs/screenshots/cover.png" alt="Shep AI" width="900" />
24
+ <img src="docs/screenshots/cover.png" alt="Shep — Parallel AI Agent Sessions" width="900" />
25
25
 
26
26
  </div>
27
27
 
28
28
  ---
29
29
 
30
+ ## Why Shep?
31
+
32
+ You're already using AI coding agents. The problem isn't the coding — it's everything around it.
33
+
34
+ Switching branches. Stashing changes. Watching CI. Assembling PRs. Losing context when you juggle three things at once. One agent session is fine. Five is chaos.
35
+
36
+ **Shep gives each feature its own isolated world** — a git worktree, a branch, an agent session — and handles the boring parts: committing, pushing, opening PRs, watching CI, and fixing failures. You manage it all from one dashboard or the CLI.
37
+
38
+ ```bash
39
+ shep feat new "add stripe payments" --push --pr
40
+ shep feat new "add dark mode toggle" --push --pr
41
+ shep feat new "fix login redirect bug" --push --pr
42
+ # Three agents running in parallel. Zero branch conflicts. You monitor from one place.
43
+ ```
44
+
45
+ ---
46
+
30
47
  ## Quick Start
31
48
 
49
+ ### Prerequisites
50
+
51
+ - **Node.js 22+** and **npm** (or install via `nvm`)
52
+ - **Git** and **GitHub CLI** (`gh`) — [install guide](https://cli.github.com/)
53
+ - **An AI coding agent**, authenticated and ready:
54
+ - **Claude Code**: `claude` · **Cursor CLI**: `cursor` · **Gemini CLI**: `gemini`
55
+ - If prompted to log in, complete auth first — Shep can't authenticate on your behalf.
56
+
57
+ > **Sandbox mode note:** Some agents restrict network access by default. If operations like `npm install` fail, configure allowed hosts in your agent's settings or disable sandbox for Shep features. See [Agent Permissions](#agent-permissions).
58
+
59
+ ### Install and run
60
+
32
61
  ```bash
33
62
  # Try it instantly — no install needed
34
63
  npx @shepai/cli
35
64
 
36
65
  # Or install globally
37
66
  npm i -g @shepai/cli
67
+
68
+ # Start Shep — opens the web dashboard at localhost:4050
38
69
  shep
70
+ ```
71
+
72
+ ### Your first feature
39
73
 
40
- # Browser opens at http://localhost:4050 — you're in
74
+ ```bash
75
+ cd ~/projects/my-app # Any git repo. Shep uses the repo you're in.
76
+ shep feat new "add a /health endpoint that returns uptime and version" --push --pr
77
+
78
+ # Shep creates a worktree, runs your agent, commits, pushes, and opens a PR.
41
79
  ```
42
80
 
43
- ---
81
+ Not in a git repo? Shep initializes one for you — `git init`, creates a branch, and starts working.
44
82
 
45
- ## Features
83
+ ### Go parallel
46
84
 
47
85
  ```bash
48
- shep feat new "add stripe payments" --allow-all --push --pr
49
- # PRD research plan code → tests → PR → CI watch — done.
86
+ shep feat new "add stripe payments" --push --pr
87
+ shep feat new "add dark mode toggle" --push --pr
88
+ shep feat new "refactor auth middleware" --push --pr
89
+ # All three run simultaneously in the same repo. Each in its own worktree.
50
90
  ```
51
91
 
52
- - **Full lifecycle in one shot** — From idea to merged PR: requirements, technical research, implementation plan, code with tests, PR creation, and CI fix loop
53
- - **Approve or go hands-free** — Three review gates (PRD, Plan, Merge) you can enable, disable, or skip entirely with `--allow-all`
54
- - **Run 10 features in parallel** — Each gets its own git worktree — switch context instantly, no stashing, no branch juggling, no conflicts
55
- - **Pick your agent** — Claude Code, Cursor CLI, or Gemini CLI — swap per feature, per repo, anytime
56
- - **Live dashboard** — Interactive graph of every repo and feature — review diffs, approve merges, launch dev servers, all in-browser
57
- - **100% local, zero signup** — SQLite in `~/.shep/`, nothing leaves your machine, no account needed
92
+ Or work across multiple repos:
58
93
 
59
- > **[See the full Features Guide with screenshots →](./docs/FEATURES.md)**
94
+ ```bash
95
+ shep feat new "add payments" --repo ~/projects/backend --push --pr
96
+ shep feat new "add checkout UI" --repo ~/projects/frontend --push --pr
97
+ ```
60
98
 
61
99
  ---
62
100
 
63
- ## CLI Reference
101
+ ## How It Works
64
102
 
65
- ### Daemon
103
+ The default flow is simple: **prompt → implement → commit → push → PR**.
66
104
 
67
105
  ```
68
- shep Start daemon + onboarding (first run)
69
- shep start [--port <number>] Start web UI daemon (background, default port 4050)
70
- shep stop Stop the running daemon
71
- shep restart Restart the daemon
72
- shep status Show daemon status and live metrics
73
- shep ui [--port] [--no-open] Start the web UI in the foreground
106
+ You describe Agent codes Shep commits Shep pushes Shep opens
107
+ a feature → in a worktree → the changes → to remote → a PR
108
+ ```
109
+
110
+ Shep creates an isolated git worktree, hands your prompt to the agent, and handles everything after: committing, pushing, and opening a PR. If CI fails, Shep reads the logs, fixes the issue, and retries (configurable).
111
+
112
+ ### Configure everything
113
+
114
+ Every step of the pipeline is configurable. Turn things on or off per feature or set defaults:
115
+
116
+ | Flag | What it does | Default |
117
+ |------|-------------|---------|
118
+ | `--push` | Auto-push after implementation | off |
119
+ | `--pr` | Auto-create PR after push | off |
120
+ | `--fast` | Skip spec-driven phases, go straight to coding | on |
121
+ | `--allow-merge` | Auto-merge the PR after CI passes | off |
122
+ | `--allow-all` | Enable all automations | off |
123
+ | `--model` | Choose which AI model to use | agent default |
124
+ | `--attach` | Attach reference files for context | — |
125
+
126
+ Use `shep settings workflow` to set your defaults so you don't repeat flags.
127
+
128
+ ### Optional: Spec-Driven Development
129
+
130
+ For complex features, enable the full structured pipeline with requirements, research, and planning phases:
131
+
132
+ ```bash
133
+ # Disable --fast to get the full pipeline
134
+ shep feat new "redesign the payment system" --no-fast --push --pr
74
135
  ```
75
136
 
76
- ### Feature Management
137
+ This adds **approval gates** where Shep pauses for your review:
77
138
 
78
139
  ```
79
- shep feat new <description> Create a new feature
80
- [--repo] [--push] [--pr]
81
- [--allow-prd] [--allow-plan] [--allow-merge] [--allow-all]
82
- [--parent] [--fast] [--model] [--attach]
83
- shep feat ls [--repo] List features
84
- shep feat show <id> Show feature details
85
- shep feat del <id> Delete a feature
86
- shep feat resume <id> Resume a paused feature
87
- shep feat review <id> Review a feature
88
- shep feat approve <id> [--comments] Approve a feature
89
- shep feat reject <id> [--feedback] Reject a feature
90
- shep feat logs <id> View feature logs
140
+ Prompt → Requirements → Research → Plan → Implement → Commit → PR
141
+ ▲ ▲ ▲
142
+ Gate 1: PRD Gate 2: Plan Gate 3: Merge
91
143
  ```
92
144
 
93
- ### Agent Management
145
+ Each gate produces a YAML artifact you can read, edit, and approve before the agent continues. Use `--allow-prd` and `--allow-plan` to auto-approve individual gates, or keep them manual for full control.
146
+
147
+ > **[Spec-Driven Development guide →](./docs/development/spec-driven-workflow.md)**
148
+
149
+ ---
150
+
151
+ ## Features
152
+
153
+ ### Parallel Sessions
154
+
155
+ Run multiple features at once. Each gets its own git worktree — isolated branch, isolated files, zero conflicts. Monitor all of them from one dashboard.
156
+
157
+ ### Prompt to PR
158
+
159
+ One command: `shep feat new "do X" --push --pr`. Agent implements, Shep commits, pushes, opens a PR. Done.
160
+
161
+ ### Agent-Agnostic
162
+
163
+ Use Claude Code, Cursor CLI, or Gemini CLI. Swap per feature, per repo, anytime. If it runs in a terminal, Shep can orchestrate it.
164
+
165
+ ### Web Dashboard + CLI
166
+
167
+ Two ways to manage everything. The dashboard at `localhost:4050` shows a visual graph of all repos and features with real-time status, diff review, and interactive chat. The CLI gives you the same control from the terminal.
168
+
169
+ ### CI Watch & Auto-Fix
170
+
171
+ Shep watches your CI pipeline after push. If it fails, the agent reads the logs, diagnoses the problem, and pushes a fix. Retries are configurable (default: 3). Works best when CI produces clear error messages.
172
+
173
+ ### Everything Configurable
174
+
175
+ Push, PR, merge, CI watch, CI fix retries, timeouts, model selection, agent type — configure per feature with flags or set global defaults with `shep settings`. Nothing is hardcoded.
176
+
177
+ ### 100% Local
178
+
179
+ All data lives in `~/.shep/` as SQLite. No cloud, no account, no tracking. Your code is only sent to whichever AI agent you configure, under that agent's own terms.
180
+
181
+ ### Optional: Spec-Driven Development
182
+
183
+ When you need more structure — requirements, technical research, implementation plans with approval gates. Produces versioned YAML artifacts you review before any code is written. Enable per feature with `--no-fast`.
184
+
185
+ ---
186
+
187
+ ## What Happens When Things Go Wrong
188
+
189
+ - **CI fails.** Shep reads the logs, diagnoses the problem, and pushes a fix. Retries up to 3 times (configurable), then pauses and asks you.
190
+ - **Agent gets stuck.** The feature enters a `Blocked` state. You get notified and can provide feedback or restart from a checkpoint.
191
+ - **You need to stop immediately.** Run `shep agent stop <id>` or hit the stop button in the dashboard. The worktree is preserved — resume or take over manually.
192
+ - **You want to take over.** The code lives in a standard git worktree on a named branch. Open it in your IDE at any point.
193
+ - **Too many features in flight.** Each feature is independent. Stop, pause, or delete any of them without affecting the others.
194
+
195
+ ---
196
+
197
+ ## Trust & Safety
198
+
199
+ Shep runs entirely on your machine.
200
+
201
+ | Concern | How Shep handles it |
202
+ |---------|-------------------|
203
+ | **Data stays local** | All data in `~/.shep/` as SQLite. Nothing sent to Shep servers — there are none. |
204
+ | **Agent permissions** | Shep runs your agent with permission-bypass flags to avoid blocking the automated pipeline. See [Agent Permissions](#agent-permissions) below. |
205
+ | **Git isolation** | Every feature runs in its own worktree branched from main. Your working directory is never modified. |
206
+ | **No credential access** | Shep never reads, stores, or transmits your API keys. |
207
+ | **Agent mistakes** | Shep creates a draft PR. Your CI, linters, and security scanners run before any merge. Shep does not merge code that fails CI. |
208
+ | **Review before merge** | Unless you pass `--allow-merge`, no code is merged without your approval. |
209
+ | **Full audit trail** | Every action and state transition is logged. View with `shep feat logs <id>`. |
210
+
211
+ ### Agent Permissions
212
+
213
+ Shep runs your agent non-interactively — it can't pause for "allow this command?" prompts mid-pipeline. By default, it passes permission-bypass flags (e.g., `--dangerously-skip-permissions` for Claude Code — each agent has an equivalent).
214
+
215
+ **Your safety net is three layers deep:**
216
+ 1. **Worktree isolation** — the agent works on a copy, not your checkout
217
+ 2. **Draft PRs** — you review the diff before anything is merged
218
+ 3. **CI pipeline** — your tests, linters, and security scanners run before merge
219
+
220
+ The skip-permissions flag is a default, not a requirement. Configure your agent's permission model independently if you need tighter control.
221
+
222
+ **What Shep does NOT protect you from:** If your CI doesn't catch a vulnerability, Shep won't either. Shep is an orchestration layer, not a security scanner.
223
+
224
+ ---
225
+
226
+ ## Supported Agents & Tools
227
+
228
+ | Category | Supported |
229
+ |----------|-----------|
230
+ | **AI Agents** | Claude Code, Cursor CLI, Gemini CLI |
231
+ | **IDEs** | VS Code, Cursor, Zed, Windsurf, and more |
232
+ | **Required** | Git, GitHub CLI (`gh`) |
233
+
234
+ ---
235
+
236
+ ## CLI Reference
237
+
238
+ ### Core Commands
94
239
 
95
240
  ```
96
- shep agent ls List agents
97
- shep agent show <id> Show agent details
98
- shep agent stop <id> Stop a running agent
99
- shep agent logs <id> View agent logs
100
- shep agent delete <id> Delete an agent
101
- shep agent approve <id> Approve an agent action
102
- shep agent reject <id> Reject an agent action
241
+ shep Start daemon + onboarding (first run)
242
+ shep feat new <description> Create a new feature
243
+ [--push] [--pr] [--fast] [--model] [--attach]
244
+ [--allow-prd] [--allow-plan] [--allow-merge] [--allow-all]
245
+ shep feat ls List features
246
+ shep feat show <id> Show feature details
247
+ shep feat resume <id> Resume a paused feature
248
+ shep feat approve <id> Approve current phase (spec-driven mode)
249
+ shep feat reject <id> --feedback Reject with feedback (spec-driven mode)
250
+ shep feat logs <id> View feature logs
103
251
  ```
104
252
 
105
- ### Repository & Session Management
253
+ ### Stopping a Feature
106
254
 
107
255
  ```
108
- shep repo ls List repositories
109
- shep repo show <id> Show repository details
110
- shep session ls List sessions
111
- shep session show <id> Show session details
256
+ shep agent stop <id> Stop a running agent immediately
257
+ shep agent ls Find the agent ID for a feature
112
258
  ```
113
259
 
114
- ### Settings
260
+ The web dashboard also has a stop button on every in-progress feature.
261
+
262
+ ### Daemon & Dashboard
115
263
 
116
264
  ```
117
- shep settings Launch setup wizard
118
- shep settings show Display current configuration
119
- shep settings init Initialize settings
120
- shep settings agent Configure AI coding agent
121
- shep settings ide Configure IDE
122
- shep settings workflow Configure workflow
123
- shep settings model Configure model
265
+ shep start [--port] Start web daemon (default: 4050)
266
+ shep stop Stop the daemon
267
+ shep status Show daemon status and metrics
268
+ shep ui Start web UI in foreground
124
269
  ```
125
270
 
126
- ### Tools
271
+ ### Settings & Configuration
127
272
 
128
273
  ```
129
- shep tools list List tools with install status
130
- shep install <tool> [--how] Install a dev tool
131
- shep ide-open [--ide] [--dir] Open IDE in directory
274
+ shep settings Launch setup wizard
275
+ shep settings workflow Configure default flags (push, pr, ci watch, etc.)
276
+ shep settings agent Configure AI coding agent
277
+ shep settings ide Configure IDE
278
+ shep settings model Configure default model
132
279
  ```
133
280
 
134
- ### Other
281
+ ### Agent & Repo Management
135
282
 
136
283
  ```
137
- shep version Show version info
138
- shep upgrade Upgrade to latest version
139
- shep run <agent> [-p prompt] [-r repo] [-s] Run an agent directly
284
+ shep agent ls List agent runs
285
+ shep agent stop <id> Stop a running agent
286
+ shep agent logs <id> View agent logs
287
+ shep repo ls List repositories
140
288
  ```
141
289
 
290
+ > **[Full CLI reference →](./docs/cli/architecture.md)**
291
+
142
292
  ---
143
293
 
144
- ## Architecture
294
+ ## FAQ
145
295
 
146
- Clean Architecture with four layers. Dependencies point inward domain has zero external deps.
296
+ **How is this different from just using an AI coding agent directly?**
147
297
 
148
- ```mermaid
149
- flowchart TB
150
- P["<b>Presentation</b><br/>CLI · Web UI · TUI"]
151
- A["<b>Application</b><br/>Use Cases · Orchestration · Ports"]
152
- D["<b>Domain</b><br/>Entities · Value Objects · Services"]
153
- I["<b>Infrastructure</b><br/>SQLite · LangGraph · DI"]
298
+ Your agent writes the code. Shep manages the session: creating the worktree, committing, pushing, opening PRs, watching CI, and retrying failures. The difference is most obvious when you're running 3-5 features in parallel — Shep keeps them organized and isolated while you focus on what matters.
154
299
 
155
- P --> A --> D
156
- I --> A
300
+ **How is this different from Superset?**
157
301
 
158
- style P fill:#dbeafe,stroke:#3b82f6,color:#1e3a5f
159
- style A fill:#fef3c7,stroke:#f59e0b,color:#78350f
160
- style D fill:#d1fae5,stroke:#10b981,color:#064e3b
161
- style I fill:#ede9fe,stroke:#8b5cf6,color:#4c1d95
162
- ```
302
+ Superset is a terminal multiplexer for agents — it runs them in parallel tabs. Shep manages the development lifecycle: worktrees, commits, pushes, PRs, CI. They're complementary. Use Superset for the execution environment, Shep for the workflow.
163
303
 
164
- | Layer | Path | Responsibility |
165
- | -------------- | ----------------------------------- | ------------------------------------------------- |
166
- | Domain | `packages/core/src/domain/` | Business logic, TypeSpec-generated types |
167
- | Application | `packages/core/src/application/` | Use cases, output port interfaces |
168
- | Infrastructure | `packages/core/src/infrastructure/` | SQLite repos, LangGraph agents, DI (tsyringe) |
169
- | Presentation | `src/presentation/` | CLI (Commander), TUI (Inquirer), Web UI (Next.js) |
304
+ **What happens if the agent writes bad code?**
170
305
 
171
- ### Feature Lifecycle
306
+ Shep creates a draft PR. Your CI runs. If tests fail, the agent reads the logs and attempts a fix (up to 3 retries, configurable). If that fails, the feature pauses and you're notified. The agent never merges code that fails CI.
172
307
 
173
- Every feature progresses through a structured SDLC pipeline with 9 states:
308
+ **What about agent sandbox / permission modes?**
174
309
 
175
- ```
176
- Started -> Analyze -> Requirements -> Research -> Planning -> Implementation -> Review -> Maintain
177
- |
178
- (Blocked)
179
- ```
310
+ Shep runs the agent with permission-bypass flags by default so the pipeline isn't blocked by interactive prompts. Your protection is worktree isolation, draft PRs, and your CI pipeline. See [Agent Permissions](#agent-permissions).
180
311
 
181
- Human approval gates are configurable at PRD, Plan, and Merge phases. In `--allow-all` mode the agent handles everything autonomously.
312
+ **Does this work on large codebases?**
182
313
 
183
- ### Tech Stack
314
+ Yes. The practical limit is the underlying agent's context window, not Shep. If your agent handles your repo well directly, Shep will too. For monorepos, scope features to specific packages with `--repo`.
184
315
 
185
- | Component | Technology |
186
- | --------------- | ------------------------------------------------------------------------- |
187
- | Language | TypeScript (ES2022) |
188
- | Package Manager | pnpm |
189
- | CLI Framework | Commander |
190
- | TUI Framework | [@inquirer/prompts](https://github.com/SBoudrias/Inquirer.js) |
191
- | Web UI | Next.js 16 + React 19 + shadcn/ui + Tailwind CSS 4 |
192
- | Graph Viz | React Flow (XYFlow) 12 |
193
- | Design System | Storybook 8.x |
194
- | Build Tool | tsc + tsc-alias (prod), tsx (CLI dev), Next.js (web dev) |
195
- | Database | SQLite (better-sqlite3, per-repo) |
196
- | Domain Models | TypeSpec -> generated TypeScript |
197
- | Agent System | [LangGraph](https://www.langchain.com/langgraph) (`@langchain/langgraph`) |
198
- | DI Container | tsyringe |
199
- | Testing | Vitest (unit/integration) + Playwright (e2e) |
200
- | Methodology | TDD (Red-Green-Refactor) |
316
+ **Can I use this on a team?**
201
317
 
202
- ### Supported Tools
318
+ Shep runs locally on your git repo. Multiple team members can run Shep independently. Features are just branches and PRs — your existing review process applies.
203
319
 
204
- Shep can detect, install, and manage the following tools:
320
+ **Is my code sent anywhere?**
205
321
 
206
- | Category | Tools |
207
- | ---------- | --------------------------------------------------------------------------------- |
208
- | IDEs | Alacritty, Antigravity, Cursor, iTerm2, Kitty, TMux, VS Code, Warp, Windsurf, Zed |
209
- | CLI Agents | Claude Code, Cursor CLI, Gemini CLI |
210
- | Dev Tools | Git, GitHub CLI |
322
+ Not by Shep. Your code is sent to whichever AI agent you configure, under that agent's own privacy terms. Shep stores everything locally and makes no network calls.
211
323
 
212
- ### Web UI
324
+ **What's the spec-driven mode?**
213
325
 
214
- The web dashboard runs at `http://localhost:4050` and provides:
326
+ An optional structured pipeline that adds requirements, research, and planning phases with approval gates before any code is written. Useful for complex features where you want to review the approach first. Enable with `--no-fast`. [Learn more →](./docs/development/spec-driven-workflow.md)
215
327
 
216
- - **Dashboard canvas** Interactive React Flow graph with feature and repository nodes
217
- - **Feature drawer** — Tabs for overview, activity, approval, rejection, PR info, deployment, and timeline
218
- - **Create feature form** — Start new features from the UI
219
- - **Settings, Tools, Skills, and Version pages**
220
- - **Real-time updates** via Server-Sent Events (SSE)
328
+ **How do I stop a feature that's running?**
221
329
 
222
- ### Data Model
330
+ CLI: `shep agent stop <id>`. Dashboard: click the stop button. The worktree is preserved — resume with `shep feat resume <id>` or work on it manually.
223
331
 
224
- ```
225
- Repository --+-- Feature --+-- Plan --+-- Task -- ActionItem
226
- | | +-- Artifact
227
- | +-- Requirement -- Research
228
- ```
332
+ ---
229
333
 
230
- All data lives locally in `~/.shep/`. Per-repo SQLite databases. No cloud dependency.
334
+ ## Architecture
231
335
 
232
- ---
336
+ Shep follows Clean Architecture with four layers. For contributors and the curious:
337
+
338
+ | Layer | Responsibility |
339
+ |-------|---------------|
340
+ | **Domain** | Business logic, TypeSpec-generated types |
341
+ | **Application** | Use cases, port interfaces |
342
+ | **Infrastructure** | SQLite, LangGraph agents, DI |
343
+ | **Presentation** | CLI, Web UI |
233
344
 
234
- ## Documentation
235
-
236
- | Document | Description |
237
- | -------------------------------------------------- | ------------------------------------------ |
238
- | [Features Guide](./docs/FEATURES.md) | Full features overview with screenshots |
239
- | [Competitive Landscape](./docs/competitors/) | How Shep fits in the AI dev tool ecosystem |
240
- | [CLAUDE.md](./CLAUDE.md) | Guidance for Claude Code instances |
241
- | [AGENTS.md](./AGENTS.md) | Agent system architecture |
242
- | [CONTRIBUTING-AGENTS.md](./CONTRIBUTING-AGENTS.md) | AI agent contribution guidelines |
243
- | [Architecture](./docs/architecture/) | System design and patterns |
244
- | [Concepts](./docs/concepts/) | Core domain concepts |
245
- | [UI](./docs/ui/) | Web UI architecture and design system |
246
- | [Guides](./docs/guides/) | User guides and tutorials |
247
- | [Development](./docs/development/) | Contributing and development setup |
248
- | [API Reference](./docs/api/) | Interface and model documentation |
345
+ > **[Full architecture docs →](./docs/architecture/overview.md)**
346
+
347
+ ---
249
348
 
250
349
  ## Contributing
251
350
 
252
- We welcome contributions from humans and AI agents alike.
351
+ See [CONTRIBUTING.md](./CONTRIBUTING.md) for humans and [CONTRIBUTING-AGENTS.md](./CONTRIBUTING-AGENTS.md) for AI agents.
253
352
 
254
- - **Humans**: See [CONTRIBUTING.md](./CONTRIBUTING.md)
255
- - **AI Agents**: See [CONTRIBUTING-AGENTS.md](./CONTRIBUTING-AGENTS.md)
256
- - **Spec-driven workflow**: All features start with `/shep-kit:new-feature` — see [Spec-Driven Workflow](./docs/development/spec-driven-workflow.md)
353
+ ---
257
354
 
258
355
  ## License
259
356
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@shepai/cli",
3
- "version": "1.156.0-pr487.27d2745",
3
+ "version": "1.156.0-pr489.56abb36",
4
4
  "description": "Autonomous AI Native SDLC Platform - Automate the development cycle from idea to deploy",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -1 +1 @@
1
- YJAjXJ0PmVhoQ7S_uBBDz
1
+ KB8KOezkUq0uueUEtffWG
@@ -7,8 +7,8 @@
7
7
  "static/chunks/a6dad97d9634a72d.js"
8
8
  ],
9
9
  "lowPriorityFiles": [
10
- "static/YJAjXJ0PmVhoQ7S_uBBDz/_ssgManifest.js",
11
- "static/YJAjXJ0PmVhoQ7S_uBBDz/_buildManifest.js"
10
+ "static/KB8KOezkUq0uueUEtffWG/_ssgManifest.js",
11
+ "static/KB8KOezkUq0uueUEtffWG/_buildManifest.js"
12
12
  ],
13
13
  "rootMainFiles": [
14
14
  "static/chunks/40b6bcf1a2de4a0f.js",
@@ -5,8 +5,8 @@
5
5
  "devFiles": [],
6
6
  "polyfillFiles": [],
7
7
  "lowPriorityFiles": [
8
- "static/YJAjXJ0PmVhoQ7S_uBBDz/_ssgManifest.js",
9
- "static/YJAjXJ0PmVhoQ7S_uBBDz/_buildManifest.js"
8
+ "static/KB8KOezkUq0uueUEtffWG/_ssgManifest.js",
9
+ "static/KB8KOezkUq0uueUEtffWG/_buildManifest.js"
10
10
  ],
11
11
  "rootMainFiles": []
12
12
  }
@@ -29,8 +29,8 @@
29
29
  "dynamicRoutes": {},
30
30
  "notFoundRoutes": [],
31
31
  "preview": {
32
- "previewModeId": "1d451a3c2e243cb27e5eece34a79805d",
33
- "previewModeSigningKey": "001b187ba6b4dce6523b730adb690cf965e808029d0bf1bd1ef75820a00b3923",
34
- "previewModeEncryptionKey": "0491450cae0a1ed19ad10f052db346a5f5f0980fbf5636b5505a1ad85f678c30"
32
+ "previewModeId": "afb097a152698f92f1d18b2232664fc4",
33
+ "previewModeSigningKey": "ff5f87535773ce01b078c0f91ac62ec9e1bee6b7ea3661e12713cd2f3143d9fa",
34
+ "previewModeEncryptionKey": "30799d8c52838aa7a943d545dfed8280ec09dde1062d6940041c8a5078e925d6"
35
35
  }
36
36
  }
@@ -6,7 +6,7 @@ self.__SERVER_FILES_MANIFEST={
6
6
  "NEXT_PUBLIC_SHEP_PACKAGE_NAME": "@shepai/cli",
7
7
  "NEXT_PUBLIC_SHEP_DESCRIPTION": "Autonomous AI Native SDLC Platform - Automate the development cycle from idea to deploy",
8
8
  "NEXT_PUBLIC_SHEP_BRANCH": "HEAD",
9
- "NEXT_PUBLIC_SHEP_COMMIT": "27d274531164a8f64cf59159a496e4cfcc651ad9",
9
+ "NEXT_PUBLIC_SHEP_COMMIT": "56abb369ad9bca4bbc6f0fafee246c2aff87bc6d",
10
10
  "NEXT_PUBLIC_SHEP_INSTANCE_PATH": "/home/runner/work/cli/cli/src/presentation/web"
11
11
  },
12
12
  "webpack": null,
@@ -6,7 +6,7 @@
6
6
  "NEXT_PUBLIC_SHEP_PACKAGE_NAME": "@shepai/cli",
7
7
  "NEXT_PUBLIC_SHEP_DESCRIPTION": "Autonomous AI Native SDLC Platform - Automate the development cycle from idea to deploy",
8
8
  "NEXT_PUBLIC_SHEP_BRANCH": "HEAD",
9
- "NEXT_PUBLIC_SHEP_COMMIT": "27d274531164a8f64cf59159a496e4cfcc651ad9",
9
+ "NEXT_PUBLIC_SHEP_COMMIT": "56abb369ad9bca4bbc6f0fafee246c2aff87bc6d",
10
10
  "NEXT_PUBLIC_SHEP_INSTANCE_PATH": "/home/runner/work/cli/cli/src/presentation/web"
11
11
  },
12
12
  "webpack": null,