@shepai/cli 1.94.0-pr284.29008ae → 1.94.0-pr285.71b2de1

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 (131) hide show
  1. package/README.md +344 -138
  2. package/dist/src/presentation/web/components/common/feature-drawer-tabs/activity-tab.js +1 -1
  3. package/dist/src/presentation/web/components/common/feature-drawer-tabs/activity-tab.stories.d.ts +2 -0
  4. package/dist/src/presentation/web/components/common/feature-drawer-tabs/activity-tab.stories.d.ts.map +1 -1
  5. package/dist/src/presentation/web/components/common/feature-drawer-tabs/activity-tab.stories.js +59 -0
  6. package/dist/tsconfig.build.tsbuildinfo +1 -1
  7. package/package.json +1 -1
  8. package/web/.next/BUILD_ID +1 -1
  9. package/web/.next/build-manifest.json +2 -2
  10. package/web/.next/fallback-build-manifest.json +2 -2
  11. package/web/.next/prerender-manifest.json +3 -3
  12. package/web/.next/required-server-files.js +1 -1
  13. package/web/.next/required-server-files.json +1 -1
  14. package/web/.next/server/app/(dashboard)/@drawer/create/page/server-reference-manifest.json +18 -18
  15. package/web/.next/server/app/(dashboard)/@drawer/create/page.js.nft.json +1 -1
  16. package/web/.next/server/app/(dashboard)/@drawer/create/page_client-reference-manifest.js +1 -1
  17. package/web/.next/server/app/(dashboard)/@drawer/feature/[featureId]/[tab]/page/server-reference-manifest.json +21 -21
  18. package/web/.next/server/app/(dashboard)/@drawer/feature/[featureId]/[tab]/page.js.nft.json +1 -1
  19. package/web/.next/server/app/(dashboard)/@drawer/feature/[featureId]/[tab]/page_client-reference-manifest.js +1 -1
  20. package/web/.next/server/app/(dashboard)/@drawer/feature/[featureId]/page/server-reference-manifest.json +21 -21
  21. package/web/.next/server/app/(dashboard)/@drawer/feature/[featureId]/page.js.nft.json +1 -1
  22. package/web/.next/server/app/(dashboard)/@drawer/feature/[featureId]/page_client-reference-manifest.js +1 -1
  23. package/web/.next/server/app/(dashboard)/@drawer/repository/[repositoryId]/page/server-reference-manifest.json +14 -14
  24. package/web/.next/server/app/(dashboard)/@drawer/repository/[repositoryId]/page.js.nft.json +1 -1
  25. package/web/.next/server/app/(dashboard)/@drawer/repository/[repositoryId]/page_client-reference-manifest.js +1 -1
  26. package/web/.next/server/app/(dashboard)/create/page/server-reference-manifest.json +18 -18
  27. package/web/.next/server/app/(dashboard)/create/page.js.nft.json +1 -1
  28. package/web/.next/server/app/(dashboard)/create/page_client-reference-manifest.js +1 -1
  29. package/web/.next/server/app/(dashboard)/feature/[featureId]/[tab]/page/server-reference-manifest.json +21 -21
  30. package/web/.next/server/app/(dashboard)/feature/[featureId]/[tab]/page.js.nft.json +1 -1
  31. package/web/.next/server/app/(dashboard)/feature/[featureId]/[tab]/page_client-reference-manifest.js +1 -1
  32. package/web/.next/server/app/(dashboard)/feature/[featureId]/page/server-reference-manifest.json +21 -21
  33. package/web/.next/server/app/(dashboard)/feature/[featureId]/page.js.nft.json +1 -1
  34. package/web/.next/server/app/(dashboard)/feature/[featureId]/page_client-reference-manifest.js +1 -1
  35. package/web/.next/server/app/(dashboard)/page/server-reference-manifest.json +14 -14
  36. package/web/.next/server/app/(dashboard)/page.js.nft.json +1 -1
  37. package/web/.next/server/app/(dashboard)/page_client-reference-manifest.js +1 -1
  38. package/web/.next/server/app/(dashboard)/repository/[repositoryId]/page/server-reference-manifest.json +14 -14
  39. package/web/.next/server/app/(dashboard)/repository/[repositoryId]/page.js.nft.json +1 -1
  40. package/web/.next/server/app/(dashboard)/repository/[repositoryId]/page_client-reference-manifest.js +1 -1
  41. package/web/.next/server/app/_global-error.html +2 -2
  42. package/web/.next/server/app/_global-error.rsc +1 -1
  43. package/web/.next/server/app/_global-error.segments/__PAGE__.segment.rsc +1 -1
  44. package/web/.next/server/app/_global-error.segments/_full.segment.rsc +1 -1
  45. package/web/.next/server/app/_global-error.segments/_head.segment.rsc +1 -1
  46. package/web/.next/server/app/_global-error.segments/_index.segment.rsc +1 -1
  47. package/web/.next/server/app/_global-error.segments/_tree.segment.rsc +1 -1
  48. package/web/.next/server/app/_not-found/page/server-reference-manifest.json +1 -1
  49. package/web/.next/server/app/_not-found/page_client-reference-manifest.js +1 -1
  50. package/web/.next/server/app/settings/page/server-reference-manifest.json +5 -5
  51. package/web/.next/server/app/settings/page_client-reference-manifest.js +1 -1
  52. package/web/.next/server/app/skills/page/server-reference-manifest.json +6 -6
  53. package/web/.next/server/app/skills/page_client-reference-manifest.js +1 -1
  54. package/web/.next/server/app/tools/page/server-reference-manifest.json +6 -6
  55. package/web/.next/server/app/tools/page_client-reference-manifest.js +1 -1
  56. package/web/.next/server/app/version/page/server-reference-manifest.json +1 -1
  57. package/web/.next/server/app/version/page_client-reference-manifest.js +1 -1
  58. package/web/.next/server/chunks/ssr/744ca_web_components_common_control-center-drawer_create-drawer-client_tsx_5e26fc0a._.js +1 -1
  59. package/web/.next/server/chunks/ssr/744ca_web_components_common_control-center-drawer_create-drawer-client_tsx_5e26fc0a._.js.map +1 -1
  60. package/web/.next/server/chunks/ssr/8ba4b_server_app_(dashboard)_@drawer_repository_[repositoryId]_page_actions_da7eef33.js +1 -1
  61. package/web/.next/server/chunks/ssr/8ba4b_server_app_(dashboard)_@drawer_repository_[repositoryId]_page_actions_da7eef33.js.map +1 -1
  62. package/web/.next/server/chunks/ssr/8ba4b_server_app_(dashboard)_repository_[repositoryId]_page_actions_0a9251aa.js +1 -1
  63. package/web/.next/server/chunks/ssr/8ba4b_server_app_(dashboard)_repository_[repositoryId]_page_actions_0a9251aa.js.map +1 -1
  64. package/web/.next/server/chunks/ssr/[root-of-the-server]__11033878._.js +1 -1
  65. package/web/.next/server/chunks/ssr/[root-of-the-server]__11033878._.js.map +1 -1
  66. package/web/.next/server/chunks/ssr/[root-of-the-server]__17143953._.js +1 -1
  67. package/web/.next/server/chunks/ssr/[root-of-the-server]__17143953._.js.map +1 -1
  68. package/web/.next/server/chunks/ssr/[root-of-the-server]__357d99f9._.js +1 -1
  69. package/web/.next/server/chunks/ssr/[root-of-the-server]__45aad79d._.js +1 -1
  70. package/web/.next/server/chunks/ssr/[root-of-the-server]__45aad79d._.js.map +1 -1
  71. package/web/.next/server/chunks/ssr/[root-of-the-server]__4be9a9bb._.js +1 -1
  72. package/web/.next/server/chunks/ssr/[root-of-the-server]__5cc4752a._.js +1 -1
  73. package/web/.next/server/chunks/ssr/[root-of-the-server]__5cc4752a._.js.map +1 -1
  74. package/web/.next/server/chunks/ssr/[root-of-the-server]__5d87af2e._.js +1 -1
  75. package/web/.next/server/chunks/ssr/[root-of-the-server]__845a9d2a._.js +1 -1
  76. package/web/.next/server/chunks/ssr/[root-of-the-server]__845a9d2a._.js.map +1 -1
  77. package/web/.next/server/chunks/ssr/[root-of-the-server]__89e8a5cc._.js +2 -2
  78. package/web/.next/server/chunks/ssr/[root-of-the-server]__9de266fa._.js +1 -1
  79. package/web/.next/server/chunks/ssr/[root-of-the-server]__9de266fa._.js.map +1 -1
  80. package/web/.next/server/chunks/ssr/[root-of-the-server]__aad040c0._.js +1 -1
  81. package/web/.next/server/chunks/ssr/[root-of-the-server]__aad040c0._.js.map +1 -1
  82. package/web/.next/server/chunks/ssr/[root-of-the-server]__fdc75809._.js +1 -1
  83. package/web/.next/server/chunks/ssr/[root-of-the-server]__fdc75809._.js.map +1 -1
  84. package/web/.next/server/chunks/ssr/_135edb9c._.js +1 -1
  85. package/web/.next/server/chunks/ssr/_135edb9c._.js.map +1 -1
  86. package/web/.next/server/chunks/ssr/{_775fb008._.js → _2d99d729._.js} +2 -2
  87. package/web/.next/server/chunks/ssr/{_775fb008._.js.map → _2d99d729._.js.map} +1 -1
  88. package/web/.next/server/chunks/ssr/_8dacd1e7._.js +1 -1
  89. package/web/.next/server/chunks/ssr/_8dacd1e7._.js.map +1 -1
  90. package/web/.next/server/chunks/ssr/_cc77a143._.js +1 -1
  91. package/web/.next/server/chunks/ssr/_cc77a143._.js.map +1 -1
  92. package/web/.next/server/chunks/ssr/_df15bd24._.js +1 -1
  93. package/web/.next/server/chunks/ssr/_df15bd24._.js.map +1 -1
  94. package/web/.next/server/chunks/ssr/b1a17_presentation_web_components_features_settings_settings-page-client_tsx_6ed9d5f8._.js +1 -1
  95. package/web/.next/server/chunks/ssr/b1a17_presentation_web_components_features_settings_settings-page-client_tsx_6ed9d5f8._.js.map +1 -1
  96. package/web/.next/server/chunks/ssr/src_presentation_web__next-internal_server_app_(dashboard)_page_actions_021a05f2.js +1 -1
  97. package/web/.next/server/chunks/ssr/src_presentation_web__next-internal_server_app_(dashboard)_page_actions_021a05f2.js.map +1 -1
  98. package/web/.next/server/chunks/ssr/src_presentation_web__next-internal_server_app_skills_page_actions_1fa8042e.js +1 -1
  99. package/web/.next/server/chunks/ssr/src_presentation_web__next-internal_server_app_skills_page_actions_1fa8042e.js.map +1 -1
  100. package/web/.next/server/chunks/ssr/src_presentation_web__next-internal_server_app_tools_page_actions_24684200.js +1 -1
  101. package/web/.next/server/chunks/ssr/src_presentation_web__next-internal_server_app_tools_page_actions_24684200.js.map +1 -1
  102. package/web/.next/server/chunks/ssr/src_presentation_web_c4348b8a._.js +2 -2
  103. package/web/.next/server/chunks/ssr/src_presentation_web_c4348b8a._.js.map +1 -1
  104. package/web/.next/server/chunks/ssr/src_presentation_web_components_bf50c527._.js +1 -1
  105. package/web/.next/server/chunks/ssr/src_presentation_web_components_bf50c527._.js.map +1 -1
  106. package/web/.next/server/chunks/ssr/src_presentation_web_components_de814675._.js +1 -1
  107. package/web/.next/server/chunks/ssr/src_presentation_web_components_de814675._.js.map +1 -1
  108. package/web/.next/server/chunks/ssr/src_presentation_web_components_e599bb8c._.js +1 -1
  109. package/web/.next/server/chunks/ssr/src_presentation_web_components_features_control-center_7ac3562e._.js +1 -1
  110. package/web/.next/server/chunks/ssr/src_presentation_web_components_features_control-center_7ac3562e._.js.map +1 -1
  111. package/web/.next/server/chunks/ssr/src_presentation_web_e4510d10._.js +2 -2
  112. package/web/.next/server/chunks/ssr/src_presentation_web_e4510d10._.js.map +1 -1
  113. package/web/.next/server/pages/500.html +2 -2
  114. package/web/.next/server/server-reference-manifest.js +1 -1
  115. package/web/.next/server/server-reference-manifest.json +28 -28
  116. package/web/.next/static/chunks/{426a8fa52f6cbb29.js → 0aced9b43d8a5183.js} +1 -1
  117. package/web/.next/static/chunks/{e2f35ce4e7d7220a.js → 1c455b0b02ec1950.js} +1 -1
  118. package/web/.next/static/chunks/{13388eebaebbd765.js → 34838846fbea6821.js} +1 -1
  119. package/web/.next/static/chunks/{f9a2483ac3ea86a7.js → 64ae8bc13d9d868a.js} +1 -1
  120. package/web/.next/static/chunks/{fce827d66af7ae8c.js → 798659b83f2c43da.js} +1 -1
  121. package/web/.next/static/chunks/{3f369959cf539e2b.js → 81a329873a9c9771.js} +1 -1
  122. package/web/.next/static/chunks/82944b1392636c27.css +2 -0
  123. package/web/.next/static/chunks/{2b5c09afb6a9d9d2.js → 85ee28a29e053c47.js} +1 -1
  124. package/web/.next/static/chunks/{ec8a6b8d8b504077.js → a4b1fd7daaaaf1d3.js} +1 -1
  125. package/web/.next/static/chunks/{975ffabcff2c7596.js → ac678b32f2fb15ec.js} +1 -1
  126. package/web/.next/static/chunks/{42371631f1b478db.js → afed1539f03a0f6c.js} +1 -1
  127. package/web/.next/static/chunks/{f03e1e09ef60b8c4.js → b03ecb3b9c231d32.js} +1 -1
  128. package/web/.next/static/chunks/39560c01879ac76a.css +0 -2
  129. /package/web/.next/static/{WVz5KLpC5vrF5Ijfky3EH → sUAsNxFnF8yzqQ1KGSMAT}/_buildManifest.js +0 -0
  130. /package/web/.next/static/{WVz5KLpC5vrF5Ijfky3EH → sUAsNxFnF8yzqQ1KGSMAT}/_clientMiddlewareManifest.json +0 -0
  131. /package/web/.next/static/{WVz5KLpC5vrF5Ijfky3EH → sUAsNxFnF8yzqQ1KGSMAT}/_ssgManifest.js +0 -0
package/README.md CHANGED
@@ -2,9 +2,9 @@
2
2
 
3
3
  # Shep AI
4
4
 
5
- ### Autonomous AI Native SDLC Platform
5
+ ### Multi-Session SDLC Control Center for AI Coding Agents
6
6
 
7
- _Run `shep` in any repo to manage features through the full development lifecycle — requirements, planning, implementation, review, and deployment using AI coding agents with human-in-the-loop approval gates._
7
+ _Manage Claude Code, Cursor CLI, or any coding agent across the full development lifecycle — from requirements to deploy with parallel sessions, instant context switching, and human-in-the-loop control_
8
8
 
9
9
  [![CI](https://github.com/shep-ai/cli/actions/workflows/ci.yml/badge.svg)](https://github.com/shep-ai/cli/actions/workflows/ci.yml)
10
10
  [![npm version](https://img.shields.io/npm/v/@shepai/cli.svg?color=cb3837&logo=npm)](https://www.npmjs.com/package/@shepai/cli)
@@ -17,11 +17,15 @@ _Run `shep` in any repo to manage features through the full development lifecycl
17
17
 
18
18
  <br />
19
19
 
20
- [Features](#features) · [Quick Start](#quick-start) · [CLI Reference](#cli-reference) · [Architecture](#architecture) · [Contributing](#contributing)
20
+ [Features](#features) · [Quick Start](#quick-start) · [CLI Reference](#cli) · [Architecture](#architecture) · [Contributing](#contributing)
21
21
 
22
- </div>
22
+ <br />
23
23
 
24
- ---
24
+ <img src="docs/poc/imgs/00-control-center-hero.png" alt="Shep AI Control Center — manage all features across repos from a single canvas" width="100%" />
25
+
26
+ [![Live Demo](https://img.shields.io/badge/Live_Demo-shep--ai.github.io-blue?style=for-the-badge)](https://shep-ai.github.io/cli/poc/)
27
+
28
+ </div>
25
29
 
26
30
  ### Install
27
31
 
@@ -33,118 +37,347 @@ npm i -g @shepai/cli
33
37
 
34
38
  ```bash
35
39
  cd your-project/
36
- shep # First-run onboarding + web UI
37
- shep feat new "Add unit tests" # Create a feature, agent takes over
40
+ shep feat new "Add unit tests for all source files"
38
41
  ```
39
42
 
40
- ---
41
-
42
- ## Features
43
-
44
- - **Full SDLC automation** — AI agents handle requirements gathering, research, planning, implementation, and review
45
- - **Human-in-the-loop gates** — Approval checkpoints at PRD, Plan, and Merge phases (configurable or skip with `--allow-all`)
46
- - **Multi-agent support** — Plug in Claude Code, Cursor CLI, or Gemini CLI as your coding agent
47
- - **Web UI dashboard** — Interactive React Flow canvas showing features and repos as graph nodes with real-time SSE updates
48
- - **Git worktree isolation** — Each feature gets its own worktree, no branch switching or stashing
49
- - **CLI-first workflow** — Full feature management, agent control, settings, and tooling from the terminal
50
- - **TUI onboarding wizard** — Guided setup on first run
51
- - **Per-repo SQLite database** — All data lives locally in `~/.shep/`, no cloud dependency
43
+ <details>
44
+ <summary><b>List features</b> &mdash; <code>shep feat ls</code></summary>
45
+ <br />
52
46
 
53
- ---
47
+ ```
48
+ Features for /home/user/projects/my-app
54
49
 
55
- ## Quick Start
50
+ ID Name Status Branch Created
51
+ 1b0a7969 Add Unit Tests ✓ Completed feat/add-unit-tests 2/13/2026
52
+ ```
56
53
 
57
- ```bash
58
- # 1. Install
59
- npm i -g @shepai/cli
54
+ </details>
60
55
 
61
- # 2. Run Shep — completes setup on first run, then opens the web UI
62
- shep
56
+ <details>
57
+ <summary><b>Show feature detail</b> &mdash; <code>shep feat show 1b0a7969</code></summary>
58
+ <br />
63
59
 
64
- # 3. Browser opens at http://localhost:4050 — you're in
65
60
  ```
61
+ Feature: Add Unit Tests
62
+
63
+ ID 1b0a7969-b420-4754-832f-5c38801b4852
64
+ Slug add-unit-tests
65
+ Description Add comprehensive unit tests for all existing source files
66
+ in the project to ensure code correctness and improve test coverage.
67
+ Repository /home/user/projects/my-app
68
+ Branch feat/add-unit-tests
69
+ Status ✓ Completed
70
+ Worktree ~/.shep/repos/9bbd30de/wt/feat-add-unit-tests
71
+ Spec Dir ~/.shep/repos/9bbd30de/wt/feat-add-unit-tests/specs/001-add-unit-tests
72
+ Agent Run 732a1fc2-a346-4052-a028-dcb1a46b6f2c
73
+
74
+ Timestamps
75
+ Created 2/13/2026, 12:15:08 AM
76
+ Updated 2/13/2026, 12:15:08 AM
77
+ ```
78
+
79
+ </details>
66
80
 
67
- ## CLI Reference
81
+ <details>
82
+ <summary><b>Isolated worktree per feature</b> &mdash; no stashing, no branch switching</summary>
83
+ <br />
68
84
 
69
- ### Daemon
85
+ Each feature gets its own git worktree — fully isolated from your main branch.
70
86
 
71
87
  ```
72
- shep Start daemon + onboarding (first run)
73
- shep start [--port <number>] Start web UI daemon (background, default port 4050)
74
- shep stop Stop the running daemon
75
- shep restart Restart the daemon
76
- shep status Show daemon status and live metrics
77
- shep ui [--port] [--no-open] Start the web UI in the foreground
88
+ ~/.shep/repos/9bbd30de/wt/feat-add-unit-tests/
89
+ ├── .git # linked worktree (not a clone)
90
+ ├── src/
91
+ ├── tests/
92
+ ├── specs/
93
+ │ └── 001-add-unit-tests/
94
+ │ ├── feature.yaml # status tracking
95
+ │ ├── spec.yaml # requirements & scope
96
+ │ ├── research.yaml # technical decisions
97
+ │ ├── plan.yaml # implementation strategy
98
+ │ └── tasks.yaml # task breakdown
99
+ ├── pyproject.toml
100
+ └── README.md
78
101
  ```
79
102
 
80
- ### Feature Management
103
+ </details>
81
104
 
82
- ```
83
- shep feat new <description> Create a new feature
84
- [--repo] [--push] [--pr]
85
- [--allow-prd] [--allow-plan] [--allow-merge] [--allow-all]
86
- [--parent] [--fast] [--model] [--attach]
87
- shep feat ls [--repo] List features
88
- shep feat show <id> Show feature details
89
- shep feat del <id> Delete a feature
90
- shep feat resume <id> Resume a paused feature
91
- shep feat review <id> Review a feature
92
- shep feat approve <id> [--comments] Approve a feature
93
- shep feat reject <id> [--feedback] Reject a feature
94
- shep feat logs <id> View feature logs
95
- ```
105
+ <details>
106
+ <summary><b>Auto-generated spec files</b> &mdash; real output from a single <code>shep feat new</code></summary>
107
+ <br />
96
108
 
97
- ### Agent Management
109
+ > **`spec.yaml`** — requirements & scope
110
+
111
+ ```yaml
112
+ name: add-unit-tests
113
+ oneLiner: Add comprehensive unit tests for all source modules
114
+ summary: >
115
+ Add unit tests for every module in the package. The project currently has
116
+ minimal test coverage (only 7 tests total). This feature adds tests for
117
+ config, agents, flows, tools, observability, and CLI — using pytest with
118
+ mocking to avoid external dependencies.
119
+ sizeEstimate: M
120
+ openQuestions:
121
+ - question: 'Should we set a minimum coverage threshold and enforce it in CI?'
122
+ resolved: true
123
+ answer: >
124
+ Set 70% minimum via --cov-fail-under=70. Achievable and prevents regression.
125
+ ```
98
126
 
127
+ > **`research.yaml`** — technical decisions with rationale
128
+
129
+ ```yaml
130
+ decisions:
131
+ - title: 'Test Framework'
132
+ chosen: 'pytest (already configured)'
133
+ rejected:
134
+ - 'unittest — More verbose, no fixture system'
135
+ - 'nose2 — Unmaintained, no advantage'
136
+ rationale: >
137
+ Already a dev dependency with asyncio and coverage plugins configured.
138
+
139
+ - title: 'Mocking Library'
140
+ chosen: 'unittest.mock (stdlib)'
141
+ rejected:
142
+ - 'pytest-mock — Adds a dependency for marginal convenience'
143
+ rationale: >
144
+ patch() for module-level replacement, MagicMock for spec objects,
145
+ assert_called_with for verification. No new dependency needed.
99
146
  ```
100
- shep agent ls List agents
101
- shep agent show <id> Show agent details
102
- shep agent stop <id> Stop a running agent
103
- shep agent logs <id> View agent logs
104
- shep agent delete <id> Delete an agent
105
- shep agent approve <id> Approve an agent action
106
- shep agent reject <id> Reject an agent action
147
+
148
+ > **`tasks.yaml`** TDD task breakdown
149
+
150
+ ```yaml
151
+ tasks:
152
+ - id: task-1
153
+ title: 'Create conftest.py with shared fixtures'
154
+ dependencies: []
155
+ acceptanceCriteria:
156
+ - 'mock_settings returns a Settings instance with known values'
157
+ - 'mock_llm returns MagicMock(spec=LLM) for agent tests'
158
+ - 'tmp_repo creates a temp dir with git init and one commit'
159
+ tdd:
160
+ red: ['Write test_smoke.py that imports fixtures and asserts properties']
161
+ green: ['Implement conftest.py with all three fixtures']
162
+ refactor: ['Remove smoke test — subsumed by real test files']
163
+
164
+ - id: task-3
165
+ title: 'Test config/llm.py'
166
+ dependencies: [task-1]
167
+ acceptanceCriteria:
168
+ - 'test_create_llm_with_openai_provider: verifies model, temperature, api_key'
169
+ - 'test_create_llm_with_cursor_provider: verifies base_url included'
170
+ - 'test_get_fast_llm: calls create_llm with settings.fast_model'
171
+ tdd:
172
+ red: ['Patch LLM and get_settings, assert constructor kwargs']
173
+ green: ['Tests pass — they verify existing code with mocks']
174
+ refactor: ['Extract common patch decorators if repetitive']
107
175
  ```
108
176
 
109
- ### Repository & Session Management
177
+ > **`feature.yaml`** machine-readable progress (updated continuously)
110
178
 
111
- ```
112
- shep repo ls List repositories
113
- shep repo show <id> Show repository details
114
- shep session ls List sessions
115
- shep session show <id> Show session details
179
+ ```yaml
180
+ feature:
181
+ id: '001-add-unit-tests'
182
+ branch: 'feat/001-add-unit-tests'
183
+ lifecycle: 'research'
184
+
185
+ status:
186
+ phase: 'research'
187
+ progress: { completed: 0, total: 12, percentage: 0 }
188
+ lastUpdatedBy: 'feature-agent'
116
189
  ```
117
190
 
118
- ### Settings
191
+ </details>
119
192
 
120
- ```
121
- shep settings Launch setup wizard
122
- shep settings show Display current configuration
123
- shep settings init Initialize settings
124
- shep settings agent Configure AI coding agent
125
- shep settings ide Configure IDE
126
- shep settings workflow Configure workflow
127
- shep settings model Configure model
128
- ```
193
+ ---
194
+
195
+ Running AI agents is easy. **Managing many of them through a full SDLC is the hard part.** Shep gives you a control center that handles the entire lifecycle — requirements gathering, planning, implementation, QA, and deployment — across multiple agent sessions running in parallel. See what each agent is doing, jump into any session's web preview, code editor, or terminal, approve plans when agents need your input, and let them keep working while you move on. Plug in Claude Code, Cursor CLI, Gemini CLI, or any coding agent. Each feature gets its own isolated worktree and dev environment. You manage the lifecycle, agents do the work.
196
+
197
+ ---
198
+
199
+ ## Features
200
+
201
+ > 🚧 **Under active development** — Web UI screenshots are from the design spec. Core CLI (`feat new`, `feat ls`, `feat show`, `settings`, `ui`, `start`, `stop`, `status`) works today. The `mem` command is still WIP.
202
+
203
+ <table>
204
+ <tr>
205
+ <td width="55%"><img src="docs/poc/imgs/01-features-control-center-overview.png" alt="Feature properties with attachments and metadata" /></td>
206
+ <td width="45%">
207
+
208
+ ### Feature Properties & Attachments
209
+
210
+ - **Rich feature detail panel** with name, description, and metadata
211
+ - **File attachments** — requirements PDFs, mockup images, API specs linked directly to features
212
+ - **Team & metadata** tracking for ownership and collaboration
213
+ - **Dependency mapping** between features across repos
214
+ - **Iterative refinement** — update properties as requirements evolve through the lifecycle
215
+
216
+ </td>
217
+ </tr>
218
+
219
+ <tr>
220
+ <td width="55%"><img src="docs/poc/imgs/02-feature-card-action-toolbar.png" alt="Feature card with action toolbar" /></td>
221
+ <td width="45%">
222
+
223
+ ### Feature Cards with Quick Actions
224
+
225
+ - **One-click dev server** launch directly from any card
226
+ - **Action toolbar** — GitHub, web preview, terminal, code editor at your fingertips
227
+ - **Live progress** tracking with percentage and lifecycle stage badge
228
+ - **Unique IDs** for instant cross-referencing across CLI and UI
229
+
230
+ </td>
231
+ </tr>
129
232
 
130
- ### Tools
233
+ <tr>
234
+ <td width="55%"><img src="docs/poc/imgs/03-requirements-discovery-validation.png" alt="Requirements discovery questionnaire" /></td>
235
+ <td width="45%">
131
236
 
237
+ ### AI-Guided Requirements Discovery
238
+
239
+ - **Smart questionnaires** that surface the right questions for your feature
240
+ - **Categorized inputs** — business, technical, and UX problem classification
241
+ - **Priority tiers** (P1–P3) with clear impact descriptions
242
+ - **Domain tagging** to scope the affected areas of your codebase
243
+ - **Human breakpoint** — agent pauses here until you finalize
244
+
245
+ </td>
246
+ </tr>
247
+
248
+ <tr>
249
+ <td width="55%"><img src="docs/poc/imgs/04-technical-implementation-plan-review.png" alt="Technical plan review with architecture decisions" /></td>
250
+ <td width="45%">
251
+
252
+ ### Technical Plan Review
253
+
254
+ - **AI-generated implementation plans** with full architecture rationale
255
+ - **Technical decision cards** — see the chosen approach and alternatives side-by-side
256
+ - **Architecture pattern selection** (microservices, monolith, serverless) with trade-off analysis
257
+ - **Approve & continue** or send back for revision — you control the direction
258
+
259
+ </td>
260
+ </tr>
261
+
262
+ <tr>
263
+ <td width="55%"><img src="docs/poc/imgs/05-plan-review-tasks-and-artifacts.png" alt="Task breakdown and generated artifacts" /></td>
264
+ <td width="45%">
265
+
266
+ ### Tasks & Generated Artifacts
267
+
268
+ - **Auto-generated documents** — plan.md, tasks.md, data_model.md created from your approved spec
269
+ - **Task breakdown** with dependency tracking and status badges
270
+ - **Artifact browser** — inspect any generated document directly in the panel
271
+ - **Draft indicator** — nothing ships until you explicitly approve
272
+
273
+ </td>
274
+ </tr>
275
+
276
+ <tr>
277
+ <td width="55%"><img src="docs/poc/imgs/06-qa-check-review.png" alt="QA checklist with all checks passing" /></td>
278
+ <td width="45%">
279
+
280
+ ### Quality Assurance Gate
281
+
282
+ - **Automated QA checklist** — functional, performance, compatibility, accessibility
283
+ - **Performance benchmarks** — API response time p95 thresholds
284
+ - **WCAG 2.5** accessibility compliance verification
285
+ - **One-click Pass QA** when all checks are green
286
+
287
+ </td>
288
+ </tr>
289
+
290
+ <tr>
291
+ <td width="55%"><img src="docs/poc/imgs/07-dev-environment-web-preview.png" alt="Integrated web preview in dev environment" /></td>
292
+ <td width="45%">
293
+
294
+ ### Integrated Dev Environment — Web Preview
295
+
296
+ - **Live localhost preview** embedded in the control center
297
+ - **Isolated ports** — each feature runs its own dev server
298
+ - **Server status** indicator with start/stop controls
299
+ - **Open in Browser** for full-screen testing
300
+ - **PR context** — branch, worktree path, and PR link always visible
301
+
302
+ </td>
303
+ </tr>
304
+
305
+ <tr>
306
+ <td width="55%"><img src="docs/poc/imgs/08-dev-environment-vscode-tab.png" alt="Embedded VS Code editor in dev environment" /></td>
307
+ <td width="45%">
308
+
309
+ ### Integrated Dev Environment — Code Editor
310
+
311
+ - **Embedded VS Code** with full editor capabilities
312
+ - **Git worktree isolation** — each feature in its own directory, no branch conflicts
313
+ - **File explorer** with project structure at a glance
314
+ - **PR badge** with commits ahead/behind and changed file count
315
+ - **Zero context-switch** — edit code without leaving the control center
316
+
317
+ </td>
318
+ </tr>
319
+
320
+ <tr>
321
+ <td width="55%"><img src="docs/poc/imgs/09-dev-environment-terminal-tab.png" alt="Terminal tab showing running dev server" /></td>
322
+ <td width="45%">
323
+
324
+ ### Integrated Dev Environment — Terminal
325
+
326
+ - **Full terminal access** inside the feature workspace
327
+ - **Build output, test results, agent logs** in one place
328
+ - **Pre-configured** in the feature's worktree directory
329
+ - **Dev server output** — see Next.js/Vite/Express startup and compile times
330
+ - **Three-tab workflow** — preview, code, and terminal without leaving the UI
331
+
332
+ </td>
333
+ </tr>
334
+ </table>
335
+
336
+ ---
337
+
338
+ ## Quick Start
339
+
340
+ ```bash
341
+ # 1. Install
342
+ npm i -g @shepai/cli
343
+
344
+ # 2. Run Shep — completes setup on first run, then opens the web UI
345
+ shep
346
+
347
+ # 3. Browser opens at http://localhost:4050 — you're in
132
348
  ```
133
- shep tools list List tools with install status
134
- shep install <tool> [--how] Install a dev tool
135
- shep ide-open [--ide] [--dir] Open IDE in directory
349
+
350
+ ## Daemon Management
351
+
352
+ `shep` runs the web UI as a background daemon so your terminal stays free. Use these commands to manage it:
353
+
354
+ ```bash
355
+ shep start # Start (or re-open) the web UI daemon
356
+ shep stop # Gracefully stop the daemon
357
+ shep status # Show live PID, port, uptime, CPU%, and memory
136
358
  ```
137
359
 
138
- ### Other
360
+ ## CLI
139
361
 
140
362
  ```
141
- shep version Show version info
142
- shep upgrade Upgrade to latest version
143
- shep run <agent> [-p prompt] [-r repo] [-s] Run an agent directly
363
+ shep Start daemon (onboarding on first run)
364
+ shep start [--port <number>] Start the web UI as a background daemon
365
+ shep stop Stop the running web UI daemon
366
+ shep status Show daemon status and live metrics
367
+ shep feat new <description> Create a new feature
368
+ shep feat new --interactive Interactive mode with human checkpoints
369
+ shep feat new --allow-all Full autonomous mode
370
+ shep feat ls List features across repos
371
+ shep feat show <id> Show feature details
372
+ shep feat preview <id> Preview feature dev environment
373
+ shep ui Start the web UI in the foreground
374
+ shep settings show Display current configuration
375
+ shep settings agent Configure AI coding agent
376
+ shep mem add <text> --global|--repo Add agent memory
377
+ shep mem ls List memories
378
+ shep version Version info
144
379
  ```
145
380
 
146
- ---
147
-
148
381
  ## Architecture
149
382
 
150
383
  Clean Architecture with four layers. Dependencies point inward — domain has zero external deps.
@@ -154,7 +387,7 @@ flowchart TB
154
387
  P["<b>Presentation</b><br/>CLI · Web UI · TUI"]
155
388
  A["<b>Application</b><br/>Use Cases · Orchestration · Ports"]
156
389
  D["<b>Domain</b><br/>Entities · Value Objects · Services"]
157
- I["<b>Infrastructure</b><br/>SQLite · LangGraph · DI"]
390
+ I["<b>Infrastructure</b><br/>SQLite · LangGraph · LanceDB"]
158
391
 
159
392
  P --> A --> D
160
393
  I --> A
@@ -165,76 +398,48 @@ flowchart TB
165
398
  style I fill:#ede9fe,stroke:#8b5cf6,color:#4c1d95
166
399
  ```
167
400
 
168
- | Layer | Path | Responsibility |
169
- | -------------- | ----------------------------------- | ------------------------------------------------- |
170
- | Domain | `packages/core/src/domain/` | Business logic, TypeSpec-generated types |
171
- | Application | `packages/core/src/application/` | Use cases, output port interfaces |
172
- | Infrastructure | `packages/core/src/infrastructure/` | SQLite repos, LangGraph agents, DI (tsyringe) |
173
- | Presentation | `src/presentation/` | CLI (Commander), TUI (Inquirer), Web UI (Next.js) |
174
-
175
401
  ### Feature Lifecycle
176
402
 
177
- Every feature progresses through a structured SDLC pipeline with 9 states:
403
+ Every feature progresses through a structured SDLC pipeline:
178
404
 
179
405
  ```
180
- Started -> Analyze -> Requirements -> Research -> Planning -> Implementation -> Review -> Maintain
181
- |
182
- (Blocked)
406
+ Requirements Research Review PRD Planning Review Plan → Implementation QA Approval → Live
407
+ ↑ ↑ ↑ ↑ ↑ ↑ ↑ ↑
408
+ Agent Agent Human Agent Human Agent Human Human
409
+ breakpoint breakpoint check gate
183
410
  ```
184
411
 
185
- Human approval gates are configurable at PRD, Plan, and Merge phases. In `--allow-all` mode the agent handles everything autonomously.
412
+ Breakpoints are configurable. In `--allow-all` mode, the agent handles everything autonomously.
186
413
 
187
414
  ### Tech Stack
188
415
 
189
- | Component | Technology |
190
- | --------------- | ------------------------------------------------------------------------- |
191
- | Language | TypeScript (ES2022) |
192
- | Package Manager | pnpm |
193
- | CLI Framework | Commander |
194
- | TUI Framework | [@inquirer/prompts](https://github.com/SBoudrias/Inquirer.js) |
195
- | Web UI | Next.js 16 + React 19 + shadcn/ui + Tailwind CSS 4 |
196
- | Graph Viz | React Flow (XYFlow) 12 |
197
- | Design System | Storybook 8.x |
198
- | Build Tool | tsc + tsc-alias (prod), tsx (CLI dev), Next.js (web dev) |
199
- | Database | SQLite (better-sqlite3, per-repo) |
200
- | Domain Models | TypeSpec -> generated TypeScript |
201
- | Agent System | [LangGraph](https://www.langchain.com/langgraph) (`@langchain/langgraph`) |
202
- | DI Container | tsyringe |
203
- | Testing | Vitest (unit/integration) + Playwright (e2e) |
204
- | Methodology | TDD (Red-Green-Refactor) |
205
-
206
- ### Supported Tools
207
-
208
- Shep can detect, install, and manage the following tools:
209
-
210
- | Category | Tools |
211
- | ---------- | --------------------------------------------------------------------------------- |
212
- | IDEs | Alacritty, Antigravity, Cursor, iTerm2, Kitty, TMux, VS Code, Warp, Windsurf, Zed |
213
- | CLI Agents | Claude Code, Cursor CLI, Gemini CLI |
214
- | Dev Tools | Git, GitHub CLI |
215
-
216
- ### Web UI
217
-
218
- The web dashboard runs at `http://localhost:4050` and provides:
219
-
220
- - **Dashboard canvas** — Interactive React Flow graph with feature and repository nodes
221
- - **Feature drawer** — Tabs for overview, activity, approval, rejection, PR info, deployment, and timeline
222
- - **Create feature form** — Start new features from the UI
223
- - **Settings, Tools, Skills, and Version pages**
224
- - **Real-time updates** via Server-Sent Events (SSE)
416
+ | Component | Technology |
417
+ | --------------- | --------------------------------------------------------------------------------------- |
418
+ | Language | TypeScript |
419
+ | Package Manager | pnpm |
420
+ | CLI Framework | Commander |
421
+ | TUI Framework | [@inquirer/prompts](https://github.com/SBoudrias/Inquirer.js) |
422
+ | Web UI | Next.js 16 + React 19 + shadcn/ui ([@shepai/web](./src/presentation/web/)) |
423
+ | Design System | Storybook |
424
+ | Build Tool | tsc + tsc-alias (prod), tsx (CLI dev), Next.js (web dev) |
425
+ | Database | SQLite |
426
+ | Agent System | [LangGraph](https://www.langchain.com/langgraph) (`@langchain/langgraph`) |
427
+ | Vector DB | [LanceDB](https://lancedb.com/) (file-based) |
428
+ | Embeddings | [Transformers.js](https://huggingface.co/docs/transformers.js) (local, multiple models) |
429
+ | Testing | Vitest (unit/integration) + Playwright (e2e) |
430
+ | Methodology | TDD (Red-Green-Refactor) |
225
431
 
226
432
  ### Data Model
227
433
 
228
434
  ```
229
- Repository --+-- Feature --+-- Plan --+-- Task -- ActionItem
230
- | | +-- Artifact
231
- | +-- Requirement -- Research
435
+ Repository ──┬── Feature ──┬── Plan ──┬── Task ──── ActionItem
436
+ └── Artifact
437
+ └── Requirement ── Research
438
+ └── Analysis docs (cached)
232
439
  ```
233
440
 
234
441
  All data lives locally in `~/.shep/`. Per-repo SQLite databases. No cloud dependency.
235
442
 
236
- ---
237
-
238
443
  ## Documentation
239
444
 
240
445
  | Document | Description |
@@ -248,6 +453,7 @@ All data lives locally in `~/.shep/`. Per-repo SQLite databases. No cloud depend
248
453
  | [Guides](./docs/guides/) | User guides and tutorials |
249
454
  | [Development](./docs/development/) | Contributing and development setup |
250
455
  | [API Reference](./docs/api/) | Interface and model documentation |
456
+ | [POC: Feature Flow](./docs/poc/) | Interactive feature lifecycle demo |
251
457
 
252
458
  ## Contributing
253
459
 
@@ -132,7 +132,7 @@ function LifecycleEventRow({ timing, message, attachments, }) {
132
132
  if (!event)
133
133
  return null;
134
134
  const hasAttachments = attachments && attachments.length > 0;
135
- return (_jsxs("div", { className: `text-xs ${event.colorClass}`, children: [_jsx("span", { children: event.label }), message ? (_jsxs("span", { "data-testid": "rejection-feedback-text", className: "text-muted-foreground ml-2 font-normal italic", children: ["\u2014 ", message] })) : null, hasAttachments ? (_jsx("div", { "data-testid": "rejection-feedback-attachments", className: "mt-1.5 ml-2", children: _jsx(InlineAttachments, { text: "", attachmentPaths: attachments }) })) : null] }));
135
+ return (_jsxs("div", { className: `text-xs ${event.colorClass}`, children: [_jsx("span", { children: event.label }), message || hasAttachments ? (_jsxs("div", { "data-testid": "rejection-feedback-container", className: "mt-1 ml-2 max-h-[120px] overflow-y-auto", children: [message ? (_jsxs("span", { "data-testid": "rejection-feedback-text", className: "text-muted-foreground font-normal italic", children: ["\u2014 ", message] })) : null, hasAttachments ? (_jsx("div", { "data-testid": "rejection-feedback-attachments", className: "mt-1.5", children: _jsx(InlineAttachments, { text: "", attachmentPaths: attachments }) })) : null] })) : null] }));
136
136
  }
137
137
  function NodeTimingRow({ timing, maxDurationMs, }) {
138
138
  const label = timing.phase.includes(':')
@@ -25,6 +25,8 @@ export declare const WithRejection: Story;
25
25
  * Iteration 4: rejected("screenshots broken...") — synthetic
26
26
  */
27
27
  export declare const MultipleRejections: Story;
28
+ /** Long rejection text — demonstrates scrollbar for lengthy feedback. */
29
+ export declare const LongRejectionText: Story;
28
30
  /** Approval wait indicators — phases with approval wait sub-rows. */
29
31
  export declare const WithApprovalWaits: Story;
30
32
  /**
@@ -1 +1 @@
1
- {"version":3,"file":"activity-tab.stories.d.ts","sourceRoot":"","sources":["../../../../../../../src/presentation/web/components/common/feature-drawer-tabs/activity-tab.stories.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAG7C,QAAA,MAAM,IAAI,EAAE,IAAI,CAAC,OAAO,WAAW,CAclC,CAAC;AAEF,eAAe,IAAI,CAAC;AACpB,KAAK,KAAK,GAAG,QAAQ,CAAC,OAAO,WAAW,CAAC,CAAC;AAmK1C,2EAA2E;AAC3E,eAAO,MAAM,OAAO,EAAE,KAMrB,CAAC;AAEF,uDAAuD;AACvD,eAAO,MAAM,YAAY,EAAE,KAM1B,CAAC;AAEF,kEAAkE;AAClE,eAAO,MAAM,YAAY,EAAE,KAM1B,CAAC;AAEF,qEAAqE;AACrE,eAAO,MAAM,OAAO,EAAE,KAMrB,CAAC;AAEF,8CAA8C;AAC9C,eAAO,MAAM,KAAK,EAAE,KAMnB,CAAC;AAEF,0CAA0C;AAC1C,eAAO,MAAM,KAAK,EAAE,KAMnB,CAAC;AAEF,0EAA0E;AAC1E,eAAO,MAAM,aAAa,EAAE,KAsE3B,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,EAAE,KAwEhC,CAAC;AAEF,qEAAqE;AACrE,eAAO,MAAM,iBAAiB,EAAE,KAgC/B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,KAiI3B,CAAC"}
1
+ {"version":3,"file":"activity-tab.stories.d.ts","sourceRoot":"","sources":["../../../../../../../src/presentation/web/components/common/feature-drawer-tabs/activity-tab.stories.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAG7C,QAAA,MAAM,IAAI,EAAE,IAAI,CAAC,OAAO,WAAW,CAclC,CAAC;AAEF,eAAe,IAAI,CAAC;AACpB,KAAK,KAAK,GAAG,QAAQ,CAAC,OAAO,WAAW,CAAC,CAAC;AAmK1C,2EAA2E;AAC3E,eAAO,MAAM,OAAO,EAAE,KAMrB,CAAC;AAEF,uDAAuD;AACvD,eAAO,MAAM,YAAY,EAAE,KAM1B,CAAC;AAEF,kEAAkE;AAClE,eAAO,MAAM,YAAY,EAAE,KAM1B,CAAC;AAEF,qEAAqE;AACrE,eAAO,MAAM,OAAO,EAAE,KAMrB,CAAC;AAEF,8CAA8C;AAC9C,eAAO,MAAM,KAAK,EAAE,KAMnB,CAAC;AAEF,0CAA0C;AAC1C,eAAO,MAAM,KAAK,EAAE,KAMnB,CAAC;AAEF,0EAA0E;AAC1E,eAAO,MAAM,aAAa,EAAE,KAsE3B,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,EAAE,KAwEhC,CAAC;AAEF,yEAAyE;AACzE,eAAO,MAAM,iBAAiB,EAAE,KA0D/B,CAAC;AAEF,qEAAqE;AACrE,eAAO,MAAM,iBAAiB,EAAE,KAgC/B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,KAiI3B,CAAC"}