gsd-pi 0.1.0

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 (128) hide show
  1. package/README.md +341 -0
  2. package/dist/app-paths.d.ts +4 -0
  3. package/dist/app-paths.js +6 -0
  4. package/dist/cli.d.ts +1 -0
  5. package/dist/cli.js +35 -0
  6. package/dist/loader.d.ts +2 -0
  7. package/dist/loader.js +69 -0
  8. package/dist/modes/interactive/theme/dark.json +85 -0
  9. package/dist/modes/interactive/theme/light.json +84 -0
  10. package/dist/modes/interactive/theme/theme-schema.json +335 -0
  11. package/dist/modes/interactive/theme/theme.d.ts +78 -0
  12. package/dist/modes/interactive/theme/theme.d.ts.map +1 -0
  13. package/dist/modes/interactive/theme/theme.js +949 -0
  14. package/dist/modes/interactive/theme/theme.js.map +1 -0
  15. package/dist/resource-loader.d.ts +22 -0
  16. package/dist/resource-loader.js +48 -0
  17. package/dist/wizard.d.ts +20 -0
  18. package/dist/wizard.js +132 -0
  19. package/package.json +39 -0
  20. package/pkg/dist/modes/interactive/theme/dark.json +85 -0
  21. package/pkg/dist/modes/interactive/theme/light.json +84 -0
  22. package/pkg/dist/modes/interactive/theme/theme-schema.json +335 -0
  23. package/pkg/dist/modes/interactive/theme/theme.d.ts +78 -0
  24. package/pkg/dist/modes/interactive/theme/theme.d.ts.map +1 -0
  25. package/pkg/dist/modes/interactive/theme/theme.js +949 -0
  26. package/pkg/dist/modes/interactive/theme/theme.js.map +1 -0
  27. package/pkg/package.json +8 -0
  28. package/scripts/postinstall.js +10 -0
  29. package/src/resources/AGENTS.md +204 -0
  30. package/src/resources/GSD-WORKFLOW.md +661 -0
  31. package/src/resources/agents/researcher.md +29 -0
  32. package/src/resources/agents/scout.md +56 -0
  33. package/src/resources/agents/worker.md +31 -0
  34. package/src/resources/extensions/ask-user-questions.ts +200 -0
  35. package/src/resources/extensions/bg-shell/index.ts +2554 -0
  36. package/src/resources/extensions/browser-tools/BROWSER-TOOLS-V2-PROPOSAL.md +1277 -0
  37. package/src/resources/extensions/browser-tools/core.js +1057 -0
  38. package/src/resources/extensions/browser-tools/index.ts +4916 -0
  39. package/src/resources/extensions/browser-tools/package.json +20 -0
  40. package/src/resources/extensions/context7/index.ts +428 -0
  41. package/src/resources/extensions/context7/package.json +11 -0
  42. package/src/resources/extensions/get-secrets-from-user.ts +352 -0
  43. package/src/resources/extensions/gsd/activity-log.ts +48 -0
  44. package/src/resources/extensions/gsd/auto.ts +2032 -0
  45. package/src/resources/extensions/gsd/commands.ts +292 -0
  46. package/src/resources/extensions/gsd/crash-recovery.ts +85 -0
  47. package/src/resources/extensions/gsd/dashboard-overlay.ts +516 -0
  48. package/src/resources/extensions/gsd/docs/preferences-reference.md +103 -0
  49. package/src/resources/extensions/gsd/doctor.ts +683 -0
  50. package/src/resources/extensions/gsd/files.ts +730 -0
  51. package/src/resources/extensions/gsd/gitignore.ts +104 -0
  52. package/src/resources/extensions/gsd/guided-flow.ts +800 -0
  53. package/src/resources/extensions/gsd/index.ts +418 -0
  54. package/src/resources/extensions/gsd/metrics.ts +372 -0
  55. package/src/resources/extensions/gsd/observability-validator.ts +408 -0
  56. package/src/resources/extensions/gsd/package.json +11 -0
  57. package/src/resources/extensions/gsd/paths.ts +308 -0
  58. package/src/resources/extensions/gsd/preferences.ts +600 -0
  59. package/src/resources/extensions/gsd/prompt-loader.ts +50 -0
  60. package/src/resources/extensions/gsd/prompts/complete-milestone.md +25 -0
  61. package/src/resources/extensions/gsd/prompts/complete-slice.md +27 -0
  62. package/src/resources/extensions/gsd/prompts/discuss.md +151 -0
  63. package/src/resources/extensions/gsd/prompts/doctor-heal.md +29 -0
  64. package/src/resources/extensions/gsd/prompts/execute-task.md +64 -0
  65. package/src/resources/extensions/gsd/prompts/guided-complete-slice.md +1 -0
  66. package/src/resources/extensions/gsd/prompts/guided-discuss-milestone.md +3 -0
  67. package/src/resources/extensions/gsd/prompts/guided-discuss-slice.md +59 -0
  68. package/src/resources/extensions/gsd/prompts/guided-execute-task.md +1 -0
  69. package/src/resources/extensions/gsd/prompts/guided-plan-milestone.md +23 -0
  70. package/src/resources/extensions/gsd/prompts/guided-plan-slice.md +1 -0
  71. package/src/resources/extensions/gsd/prompts/guided-research-slice.md +11 -0
  72. package/src/resources/extensions/gsd/prompts/guided-resume-task.md +1 -0
  73. package/src/resources/extensions/gsd/prompts/plan-milestone.md +47 -0
  74. package/src/resources/extensions/gsd/prompts/plan-slice.md +63 -0
  75. package/src/resources/extensions/gsd/prompts/queue.md +85 -0
  76. package/src/resources/extensions/gsd/prompts/reassess-roadmap.md +48 -0
  77. package/src/resources/extensions/gsd/prompts/replan-slice.md +39 -0
  78. package/src/resources/extensions/gsd/prompts/research-milestone.md +37 -0
  79. package/src/resources/extensions/gsd/prompts/research-slice.md +28 -0
  80. package/src/resources/extensions/gsd/prompts/run-uat.md +109 -0
  81. package/src/resources/extensions/gsd/prompts/system.md +220 -0
  82. package/src/resources/extensions/gsd/session-forensics.ts +487 -0
  83. package/src/resources/extensions/gsd/skill-discovery.ts +137 -0
  84. package/src/resources/extensions/gsd/state.ts +439 -0
  85. package/src/resources/extensions/gsd/templates/context.md +76 -0
  86. package/src/resources/extensions/gsd/templates/decisions.md +8 -0
  87. package/src/resources/extensions/gsd/templates/milestone-summary.md +73 -0
  88. package/src/resources/extensions/gsd/templates/plan.md +133 -0
  89. package/src/resources/extensions/gsd/templates/preferences.md +15 -0
  90. package/src/resources/extensions/gsd/templates/project.md +31 -0
  91. package/src/resources/extensions/gsd/templates/reassessment.md +28 -0
  92. package/src/resources/extensions/gsd/templates/requirements.md +81 -0
  93. package/src/resources/extensions/gsd/templates/research.md +46 -0
  94. package/src/resources/extensions/gsd/templates/roadmap.md +118 -0
  95. package/src/resources/extensions/gsd/templates/slice-context.md +58 -0
  96. package/src/resources/extensions/gsd/templates/slice-summary.md +99 -0
  97. package/src/resources/extensions/gsd/templates/state.md +19 -0
  98. package/src/resources/extensions/gsd/templates/task-plan.md +52 -0
  99. package/src/resources/extensions/gsd/templates/task-summary.md +57 -0
  100. package/src/resources/extensions/gsd/templates/uat.md +54 -0
  101. package/src/resources/extensions/gsd/types.ts +159 -0
  102. package/src/resources/extensions/gsd/unit-runtime.ts +162 -0
  103. package/src/resources/extensions/gsd/workspace-index.ts +203 -0
  104. package/src/resources/extensions/gsd/worktree.ts +182 -0
  105. package/src/resources/extensions/plan-mode/README.md +65 -0
  106. package/src/resources/extensions/plan-mode/index.ts +521 -0
  107. package/src/resources/extensions/plan-mode/utils.ts +168 -0
  108. package/src/resources/extensions/search-the-web/cache.ts +70 -0
  109. package/src/resources/extensions/search-the-web/format.ts +134 -0
  110. package/src/resources/extensions/search-the-web/http.ts +147 -0
  111. package/src/resources/extensions/search-the-web/index.ts +46 -0
  112. package/src/resources/extensions/search-the-web/tool-fetch-page.ts +374 -0
  113. package/src/resources/extensions/search-the-web/tool-search.ts +424 -0
  114. package/src/resources/extensions/search-the-web/url-utils.ts +91 -0
  115. package/src/resources/extensions/shared/interview-ui.ts +613 -0
  116. package/src/resources/extensions/shared/next-action-ui.ts +197 -0
  117. package/src/resources/extensions/shared/progress-widget.ts +282 -0
  118. package/src/resources/extensions/shared/thinking-widget.ts +107 -0
  119. package/src/resources/extensions/shared/ui.ts +400 -0
  120. package/src/resources/extensions/shared/wizard-ui.ts +551 -0
  121. package/src/resources/extensions/slash-commands/audit.ts +88 -0
  122. package/src/resources/extensions/slash-commands/create-extension.ts +297 -0
  123. package/src/resources/extensions/slash-commands/create-slash-command.ts +234 -0
  124. package/src/resources/extensions/slash-commands/gsd-run.ts +34 -0
  125. package/src/resources/extensions/slash-commands/index.ts +12 -0
  126. package/src/resources/extensions/subagent/agents.ts +126 -0
  127. package/src/resources/extensions/subagent/index.ts +1021 -0
  128. package/src/resources/extensions/worktree/index.ts +420 -0
package/README.md ADDED
@@ -0,0 +1,341 @@
1
+ <div align="center">
2
+
3
+ # GSD
4
+
5
+ **The evolution of [Get Shit Done](https://github.com/glittercowboy/get-shit-done) — now a real coding agent.**
6
+
7
+ The original GSD went viral as a prompt framework for Claude Code. It worked, but it was fighting the tool — injecting prompts through slash commands, hoping the LLM would follow instructions, with no actual control over context windows, sessions, or execution.
8
+
9
+ This version is different. GSD is now a standalone CLI built on the [Pi SDK](https://github.com/nicholasgasior/pi-coding-agent), which gives it direct TypeScript access to the agent harness itself. That means GSD can actually *do* what v1 could only *ask* the LLM to do: clear context between tasks, inject exactly the right files at dispatch time, manage git branches, track cost and tokens, detect stuck loops, recover from crashes, and auto-advance through an entire milestone without human intervention.
10
+
11
+ One command. Walk away. Come back to a built project with clean git history.
12
+
13
+ ```bash
14
+ npm install -g @glittercowboy/gsd
15
+ gsd
16
+ ```
17
+
18
+ </div>
19
+
20
+ ---
21
+
22
+ ## What Changed From v1
23
+
24
+ The original GSD was a collection of markdown prompts installed into `~/.claude/commands/`. It relied entirely on the LLM reading those prompts and doing the right thing. That worked surprisingly well — but it had hard limits:
25
+
26
+ - **No context control.** The LLM accumulated garbage over a long session. Quality degraded.
27
+ - **No real automation.** "Auto mode" was the LLM calling itself in a loop, burning context on orchestration overhead.
28
+ - **No crash recovery.** If the session died mid-task, you started over.
29
+ - **No observability.** No cost tracking, no progress dashboard, no stuck detection.
30
+
31
+ GSD v2 solves all of these because it's not a prompt framework anymore — it's a TypeScript application that *controls* the agent session.
32
+
33
+ | | v1 (Prompt Framework) | v2 (Agent Application) |
34
+ |---|---|---|
35
+ | Runtime | Claude Code slash commands | Standalone CLI via Pi SDK |
36
+ | Context management | Hope the LLM doesn't fill up | Fresh session per task, programmatic |
37
+ | Auto mode | LLM self-loop | State machine reading `.gsd/` files |
38
+ | Crash recovery | None | Lock files + session forensics |
39
+ | Git strategy | LLM writes git commands | Programmatic branch-per-slice, squash merge |
40
+ | Cost tracking | None | Per-unit token/cost ledger with dashboard |
41
+ | Stuck detection | None | Retry once, then stop with diagnostics |
42
+ | Timeout supervision | None | Soft/idle/hard timeouts with recovery steering |
43
+ | Context injection | "Read this file" | Pre-inlined into dispatch prompt |
44
+ | Roadmap reassessment | Manual | Automatic after each slice completes |
45
+ | Skill discovery | None | Auto-detect and install relevant skills during research |
46
+
47
+ ---
48
+
49
+ ## How It Works
50
+
51
+ GSD structures work into a hierarchy:
52
+
53
+ ```
54
+ Milestone → a shippable version (4-10 slices)
55
+ Slice → one demoable vertical capability (1-7 tasks)
56
+ Task → one context-window-sized unit of work
57
+ ```
58
+
59
+ The iron rule: **a task must fit in one context window.** If it can't, it's two tasks.
60
+
61
+ ### The Loop
62
+
63
+ Each slice flows through phases automatically:
64
+
65
+ ```
66
+ Research → Plan → Execute (per task) → Complete → Reassess Roadmap → Next Slice
67
+ ```
68
+
69
+ **Research** scouts the codebase and relevant docs. **Plan** decomposes the slice into tasks with must-haves (mechanically verifiable outcomes). **Execute** runs each task in a fresh context window with only the relevant files pre-loaded. **Complete** writes the summary, UAT script, marks the roadmap, and commits. **Reassess** checks if the roadmap still makes sense given what was learned.
70
+
71
+ ### `/gsd auto` — The Main Event
72
+
73
+ This is what makes GSD different. Run it, walk away, come back to built software.
74
+
75
+ ```
76
+ /gsd auto
77
+ ```
78
+
79
+ Auto mode is a state machine driven by files on disk. It reads `.gsd/STATE.md`, determines the next unit of work, creates a fresh agent session, injects a focused prompt with all relevant context pre-inlined, and lets the LLM execute. When the LLM finishes, auto mode reads disk state again and dispatches the next unit.
80
+
81
+ **What happens under the hood:**
82
+
83
+ 1. **Fresh session per unit** — Every task, every research phase, every planning step gets a clean 200k-token context window. No accumulated garbage. No "I'll be more concise now."
84
+
85
+ 2. **Context pre-loading** — The dispatch prompt includes inlined task plans, slice plans, prior task summaries, dependency summaries, roadmap excerpts, and decisions register. The LLM starts with everything it needs instead of spending tool calls reading files.
86
+
87
+ 3. **Git branch-per-slice** — Each slice gets its own branch (`gsd/M001/S01`). Tasks commit atomically on the branch. When the slice completes, it's squash-merged to main as one clean commit.
88
+
89
+ 4. **Crash recovery** — A lock file tracks the current unit. If the session dies, the next `/gsd auto` reads the surviving session file, synthesizes a recovery briefing from every tool call that made it to disk, and resumes with full context.
90
+
91
+ 5. **Stuck detection** — If the same unit dispatches twice (the LLM didn't produce the expected artifact), it retries once with a deep diagnostic. If it fails again, auto mode stops with the exact file it expected.
92
+
93
+ 6. **Timeout supervision** — Soft timeout warns the LLM to wrap up. Idle watchdog detects stalls. Hard timeout pauses auto mode. Recovery steering nudges the LLM to finish durable output before giving up.
94
+
95
+ 7. **Cost tracking** — Every unit's token usage and cost is captured, broken down by phase, slice, and model. The dashboard shows running totals and projections. Budget ceilings can pause auto mode before overspending.
96
+
97
+ 8. **Adaptive replanning** — After each slice completes, the roadmap is reassessed. If the work revealed new information that changes the plan, slices are reordered, added, or removed before continuing.
98
+
99
+ 9. **Escape hatch** — Press Escape to pause. The conversation is preserved. Interact with the agent, inspect what happened, or just `/gsd auto` to resume from disk state.
100
+
101
+ ### The `/gsd` Wizard
102
+
103
+ When you're not in auto mode, `/gsd` reads disk state and shows contextual options:
104
+
105
+ - **No `.gsd/` directory** → Start a new project. Discussion flow captures your vision, constraints, and preferences.
106
+ - **Milestone exists, no roadmap** → Discuss or research the milestone.
107
+ - **Roadmap exists, slices pending** → Plan the next slice, or jump straight to auto.
108
+ - **Mid-task** → Resume from where you left off.
109
+
110
+ The wizard is the on-ramp. Auto mode is the highway.
111
+
112
+ ---
113
+
114
+ ## Getting Started
115
+
116
+ ### Install
117
+
118
+ ```bash
119
+ npm install -g @glittercowboy/gsd
120
+ ```
121
+
122
+ Requires Node.js ≥ 20.6.0. Installs Chromium via Playwright for browser-based verification (non-fatal if it fails).
123
+
124
+ ### First Run
125
+
126
+ ```bash
127
+ cd your-project
128
+ gsd
129
+ ```
130
+
131
+ On first launch, GSD prompts for optional API keys:
132
+ - **Brave Search** — for web research during planning
133
+ - **Context7** — for up-to-date library documentation
134
+ - **Jina** — for web page content extraction
135
+
136
+ All optional. Press Enter to skip any. Keys are stored in `~/.gsd/agent/auth.json` and loaded automatically on subsequent launches.
137
+
138
+ ### Start Building
139
+
140
+ The wizard walks you through describing what you want to build. Once you approve the roadmap:
141
+
142
+ ```
143
+ /gsd auto
144
+ ```
145
+
146
+ Walk away. GSD will research, plan, execute, verify, commit, and advance through every slice until the milestone is complete.
147
+
148
+ ### Commands
149
+
150
+ | Command | What it does |
151
+ |---------|-------------|
152
+ | `/gsd` | Contextual wizard — reads state, shows what's next |
153
+ | `/gsd auto` | Start auto mode (fresh session per unit, loops until done) |
154
+ | `/gsd stop` | Stop auto mode gracefully |
155
+ | `/gsd status` | Progress dashboard overlay |
156
+ | `/gsd queue` | Queue future milestones (safe during auto mode) |
157
+ | `/gsd discuss` | Discuss implementation decisions before planning |
158
+ | `/gsd prefs` | Manage skill preferences (global/project) |
159
+ | `/gsd doctor` | Validate `.gsd/` integrity, find and fix issues |
160
+ | `Ctrl+Alt+G` | Toggle dashboard overlay |
161
+
162
+ ---
163
+
164
+ ## What GSD Manages For You
165
+
166
+ ### Context Engineering
167
+
168
+ Every dispatch is carefully constructed. The LLM never wastes tool calls on orientation.
169
+
170
+ | Artifact | Purpose |
171
+ |----------|---------|
172
+ | `PROJECT.md` | Living doc — what the project is right now |
173
+ | `DECISIONS.md` | Append-only register of architectural decisions |
174
+ | `STATE.md` | Quick-glance dashboard — always read first |
175
+ | `M001-ROADMAP.md` | Milestone plan with slice checkboxes, risk levels, dependencies |
176
+ | `M001-CONTEXT.md` | User decisions from the discuss phase |
177
+ | `M001-RESEARCH.md` | Codebase and ecosystem research |
178
+ | `S01-PLAN.md` | Slice task decomposition with must-haves |
179
+ | `T01-PLAN.md` | Individual task plan with verification criteria |
180
+ | `T01-SUMMARY.md` | What happened — YAML frontmatter + narrative |
181
+ | `S01-UAT.md` | Human test script derived from slice outcomes |
182
+
183
+ ### Git Strategy
184
+
185
+ Branch-per-slice with squash merge. Fully automated.
186
+
187
+ ```
188
+ main:
189
+ feat(M001/S03): auth and session management
190
+ feat(M001/S02): API endpoints and middleware
191
+ feat(M001/S01): data model and type system
192
+
193
+ gsd/M001/S01 (preserved):
194
+ feat(S01/T03): file writer with round-trip fidelity
195
+ feat(S01/T02): markdown parser for plan files
196
+ feat(S01/T01): core types and interfaces
197
+ ```
198
+
199
+ One commit per slice on main. Per-task history preserved on branches. Git bisect works. Individual slices are revertable.
200
+
201
+ ### Verification
202
+
203
+ Every task has must-haves — mechanically checkable outcomes:
204
+
205
+ - **Truths** — Observable behaviors ("User can sign up with email")
206
+ - **Artifacts** — Files that must exist with real implementation, not stubs
207
+ - **Key Links** — Imports and wiring between artifacts
208
+
209
+ The verification ladder: static checks → command execution → behavioral testing → human review (only when the agent genuinely can't verify itself).
210
+
211
+ ### Dashboard
212
+
213
+ `Ctrl+Alt+G` or `/gsd status` opens a real-time overlay showing:
214
+
215
+ - Current milestone, slice, and task progress
216
+ - Auto mode elapsed time and phase
217
+ - Per-unit cost and token breakdown by phase, slice, and model
218
+ - Cost projections based on completed work
219
+ - Completed and in-progress units
220
+
221
+ ---
222
+
223
+ ## Configuration
224
+
225
+ ### Preferences
226
+
227
+ GSD preferences live in `~/.gsd/preferences.md` (global) or `.gsd/preferences.md` (project). Manage with `/gsd prefs`.
228
+
229
+ ```yaml
230
+ ---
231
+ version: 1
232
+ models:
233
+ research: claude-sonnet-4-6
234
+ planning: claude-opus-4-6
235
+ execution: claude-sonnet-4-6
236
+ completion: claude-sonnet-4-6
237
+ skill_discovery: suggest
238
+ auto_supervisor:
239
+ soft_timeout_minutes: 20
240
+ idle_timeout_minutes: 10
241
+ hard_timeout_minutes: 30
242
+ budget_ceiling: 50.00
243
+ ---
244
+ ```
245
+
246
+ **Key settings:**
247
+
248
+ | Setting | What it controls |
249
+ |---------|-----------------|
250
+ | `models.*` | Per-phase model selection (Opus for planning, Sonnet for execution, etc.) |
251
+ | `skill_discovery` | `auto` / `suggest` / `off` — how GSD finds and applies skills |
252
+ | `auto_supervisor.*` | Timeout thresholds for auto mode supervision |
253
+ | `budget_ceiling` | USD ceiling — auto mode pauses when reached |
254
+ | `uat_dispatch` | Enable automatic UAT runs after slice completion |
255
+ | `always_use_skills` | Skills to always load when relevant |
256
+ | `skill_rules` | Situational rules for skill routing |
257
+
258
+ ### Bundled Tools
259
+
260
+ GSD ships with 11 extensions, all loaded automatically:
261
+
262
+ | Extension | What it provides |
263
+ |-----------|-----------------|
264
+ | **GSD** | Core workflow engine, auto mode, commands, dashboard |
265
+ | **Browser Tools** | Playwright-based browser for UI verification |
266
+ | **Search the Web** | Brave Search + Jina page extraction |
267
+ | **Context7** | Up-to-date library/framework documentation |
268
+ | **Background Shell** | Long-running process management with readiness detection |
269
+ | **Subagent** | Delegated tasks with isolated context windows |
270
+ | **Plan Mode** | Structured planning before execution |
271
+ | **Slash Commands** | Custom command creation |
272
+ | **Worktree** | Git worktree management |
273
+ | **Ask User Questions** | Structured user input with single/multi-select |
274
+ | **Secure Env Collect** | Masked secret collection without manual .env editing |
275
+
276
+ ### Bundled Agents
277
+
278
+ Three specialized subagents for delegated work:
279
+
280
+ | Agent | Role |
281
+ |-------|------|
282
+ | **Scout** | Fast codebase recon — returns compressed context for handoff |
283
+ | **Researcher** | Web research — finds and synthesizes current information |
284
+ | **Worker** | General-purpose execution in an isolated context window |
285
+
286
+ ---
287
+
288
+ ## Architecture
289
+
290
+ GSD is a TypeScript application that embeds the Pi coding agent SDK.
291
+
292
+ ```
293
+ gsd (CLI binary)
294
+ └─ loader.ts Sets PI_PACKAGE_DIR, GSD env vars, dynamic-imports cli.ts
295
+ └─ cli.ts Wires SDK managers, loads extensions, starts InteractiveMode
296
+ ├─ wizard.ts First-run API key collection (Brave/Context7/Jina)
297
+ ├─ app-paths.ts ~/.gsd/agent/, ~/.gsd/sessions/, auth.json
298
+ ├─ resource-loader.ts Syncs bundled extensions + agents to ~/.gsd/agent/
299
+ └─ src/resources/
300
+ ├─ extensions/gsd/ Core GSD extension (auto, state, commands, ...)
301
+ ├─ extensions/... 10 supporting extensions
302
+ ├─ agents/ scout, researcher, worker
303
+ ├─ AGENTS.md Agent routing instructions
304
+ └─ GSD-WORKFLOW.md Manual bootstrap protocol
305
+ ```
306
+
307
+ **Key design decisions:**
308
+
309
+ - **`pkg/` shim directory** — `PI_PACKAGE_DIR` points here (not project root) to avoid Pi's theme resolution collision with our `src/` directory. Contains only `piConfig` and theme assets.
310
+ - **Two-file loader pattern** — `loader.ts` sets all env vars with zero SDK imports, then dynamic-imports `cli.ts` which does static SDK imports. This ensures `PI_PACKAGE_DIR` is set before any SDK code evaluates.
311
+ - **Always-overwrite sync** — `npm update -g` takes effect immediately. Bundled extensions and agents are synced to `~/.gsd/agent/` on every launch, not just first run.
312
+ - **State lives on disk** — `.gsd/` is the source of truth. Auto mode reads it, writes it, and advances based on what it finds. No in-memory state survives across sessions.
313
+
314
+ ---
315
+
316
+ ## Requirements
317
+
318
+ - **Node.js** ≥ 20.6.0
319
+ - **Anthropic API key** — handled by Pi's built-in auth flow on first launch
320
+ - **Git** — initialized automatically if missing
321
+
322
+ Optional:
323
+ - Brave Search API key (web research)
324
+ - Context7 API key (library docs)
325
+ - Jina API key (page extraction)
326
+
327
+ ---
328
+
329
+ ## License
330
+
331
+ MIT
332
+
333
+ ---
334
+
335
+ <div align="center">
336
+
337
+ **The original GSD showed what was possible. This version delivers it.**
338
+
339
+ **`npm install -g @glittercowboy/gsd && gsd`**
340
+
341
+ </div>
@@ -0,0 +1,4 @@
1
+ export declare const appRoot: string;
2
+ export declare const agentDir: string;
3
+ export declare const sessionsDir: string;
4
+ export declare const authFilePath: string;
@@ -0,0 +1,6 @@
1
+ import { homedir } from 'os';
2
+ import { join } from 'path';
3
+ export const appRoot = join(homedir(), '.gsd');
4
+ export const agentDir = join(appRoot, 'agent');
5
+ export const sessionsDir = join(appRoot, 'sessions');
6
+ export const authFilePath = join(agentDir, 'auth.json');
package/dist/cli.d.ts ADDED
@@ -0,0 +1 @@
1
+ export {};
package/dist/cli.js ADDED
@@ -0,0 +1,35 @@
1
+ import { AuthStorage, ModelRegistry, SettingsManager, SessionManager, createAgentSession, InteractiveMode, } from '@mariozechner/pi-coding-agent';
2
+ import { agentDir, sessionsDir, authFilePath } from './app-paths.js';
3
+ import { buildResourceLoader, initResources } from './resource-loader.js';
4
+ import { loadStoredEnvKeys, runWizardIfNeeded } from './wizard.js';
5
+ const authStorage = AuthStorage.create(authFilePath);
6
+ loadStoredEnvKeys(authStorage);
7
+ await runWizardIfNeeded(authStorage);
8
+ const modelRegistry = new ModelRegistry(authStorage);
9
+ const settingsManager = SettingsManager.create(agentDir);
10
+ // GSD always uses quiet startup — the gsd extension renders its own branded header
11
+ if (!settingsManager.getQuietStartup()) {
12
+ settingsManager.setQuietStartup(true);
13
+ }
14
+ // Collapse changelog by default — avoid wall of text on updates
15
+ if (!settingsManager.getCollapseChangelog()) {
16
+ settingsManager.setCollapseChangelog(true);
17
+ }
18
+ const sessionManager = SessionManager.create(process.cwd(), sessionsDir);
19
+ initResources(agentDir);
20
+ const resourceLoader = buildResourceLoader(agentDir);
21
+ await resourceLoader.reload();
22
+ const { session, extensionsResult } = await createAgentSession({
23
+ authStorage,
24
+ modelRegistry,
25
+ settingsManager,
26
+ sessionManager,
27
+ resourceLoader,
28
+ });
29
+ if (extensionsResult.errors.length > 0) {
30
+ for (const err of extensionsResult.errors) {
31
+ process.stderr.write(`[gsd] Extension load error: ${err.error}\n`);
32
+ }
33
+ }
34
+ const interactiveMode = new InteractiveMode(session);
35
+ await interactiveMode.run();
@@ -0,0 +1,2 @@
1
+ #!/usr/bin/env node
2
+ export {};
package/dist/loader.js ADDED
@@ -0,0 +1,69 @@
1
+ #!/usr/bin/env node
2
+ import { fileURLToPath } from 'url';
3
+ import { dirname, resolve, join } from 'path';
4
+ import { readFileSync } from 'fs';
5
+ import { agentDir } from './app-paths.js';
6
+ // pkg/ is a shim directory: contains gsd's piConfig (package.json) and pi's
7
+ // theme assets (dist/modes/interactive/theme/) without a src/ directory.
8
+ // This allows config.js to:
9
+ // 1. Read piConfig.name → "gsd" (branding)
10
+ // 2. Resolve themes via dist/ (no src/ present → uses dist path)
11
+ const pkgDir = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'pkg');
12
+ // MUST be set before any dynamic import of pi SDK fires — this is what config.js
13
+ // reads to determine APP_NAME and CONFIG_DIR_NAME
14
+ process.env.PI_PACKAGE_DIR = pkgDir;
15
+ process.title = 'gsd';
16
+ // GSD_CODING_AGENT_DIR — tells pi's getAgentDir() to return ~/.gsd/agent/ instead of ~/.pi/agent/
17
+ process.env.GSD_CODING_AGENT_DIR = agentDir;
18
+ // NODE_PATH — make gsd's own node_modules available to extensions loaded via jiti.
19
+ // Without this, extensions (e.g. browser-tools) can't resolve dependencies like
20
+ // `playwright` because jiti resolves modules from pi-coding-agent's location, not gsd's.
21
+ // Prepending gsd's node_modules to NODE_PATH fixes this for all extensions.
22
+ const gsdRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
23
+ const gsdNodeModules = join(gsdRoot, 'node_modules');
24
+ process.env.NODE_PATH = process.env.NODE_PATH
25
+ ? `${gsdNodeModules}:${process.env.NODE_PATH}`
26
+ : gsdNodeModules;
27
+ // Force Node to re-evaluate module search paths with the updated NODE_PATH.
28
+ // Must happen synchronously before cli.js imports → extension loading.
29
+ // eslint-disable-next-line @typescript-eslint/no-require-imports
30
+ const { Module } = await import('module');
31
+ Module._initPaths?.();
32
+ // GSD_VERSION — expose package version so extensions can display it
33
+ try {
34
+ const gsdPkg = JSON.parse(readFileSync(join(gsdRoot, 'package.json'), 'utf-8'));
35
+ process.env.GSD_VERSION = gsdPkg.version || '0.0.0';
36
+ }
37
+ catch {
38
+ process.env.GSD_VERSION = '0.0.0';
39
+ }
40
+ // GSD_BIN_PATH — absolute path to this loader (dist/loader.js), used by patched subagent
41
+ // to spawn gsd instead of pi when dispatching workflow tasks
42
+ process.env.GSD_BIN_PATH = process.argv[1];
43
+ // GSD_WORKFLOW_PATH — absolute path to bundled GSD-WORKFLOW.md, used by patched gsd extension
44
+ // when dispatching workflow prompts (dist/loader.js → ../src/resources/GSD-WORKFLOW.md)
45
+ const resourcesDir = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'src', 'resources');
46
+ process.env.GSD_WORKFLOW_PATH = join(resourcesDir, 'GSD-WORKFLOW.md');
47
+ // GSD_BUNDLED_EXTENSION_PATHS — colon-joined list of all bundled extension entry point absolute
48
+ // paths, used by patched subagent to pass --extension <path> to spawned gsd processes.
49
+ // IMPORTANT: paths point to agentDir (~/.gsd/agent/extensions/) NOT src/resources/extensions/.
50
+ // initResources() syncs bundled extensions to agentDir before any extension loading occurs,
51
+ // so these paths are always valid at runtime. Using agentDir paths matches what buildResourceLoader
52
+ // discovers (it scans agentDir), so pi's deduplication works correctly and extensions are not
53
+ // double-loaded in subagent child processes.
54
+ // Note: shared/ is NOT included — it's a library imported by gsd and ask-user-questions, not an entry point.
55
+ process.env.GSD_BUNDLED_EXTENSION_PATHS = [
56
+ join(agentDir, 'extensions', 'gsd', 'index.ts'),
57
+ join(agentDir, 'extensions', 'bg-shell', 'index.ts'),
58
+ join(agentDir, 'extensions', 'browser-tools', 'index.ts'),
59
+ join(agentDir, 'extensions', 'context7', 'index.ts'),
60
+ join(agentDir, 'extensions', 'search-the-web', 'index.ts'),
61
+ join(agentDir, 'extensions', 'slash-commands', 'index.ts'),
62
+ join(agentDir, 'extensions', 'subagent', 'index.ts'),
63
+ join(agentDir, 'extensions', 'worktree', 'index.ts'),
64
+ join(agentDir, 'extensions', 'plan-mode', 'index.ts'),
65
+ join(agentDir, 'extensions', 'ask-user-questions.ts'),
66
+ join(agentDir, 'extensions', 'get-secrets-from-user.ts'),
67
+ ].join(':');
68
+ // Dynamic import defers ESM evaluation — config.js will see PI_PACKAGE_DIR above
69
+ await import('./cli.js');
@@ -0,0 +1,85 @@
1
+ {
2
+ "$schema": "https://raw.githubusercontent.com/badlogic/pi-mono/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
3
+ "name": "dark",
4
+ "vars": {
5
+ "cyan": "#00d7ff",
6
+ "blue": "#5f87ff",
7
+ "green": "#b5bd68",
8
+ "red": "#cc6666",
9
+ "yellow": "#ffff00",
10
+ "gray": "#808080",
11
+ "dimGray": "#666666",
12
+ "darkGray": "#505050",
13
+ "accent": "#8abeb7",
14
+ "selectedBg": "#3a3a4a",
15
+ "userMsgBg": "#343541",
16
+ "toolPendingBg": "#282832",
17
+ "toolSuccessBg": "#283228",
18
+ "toolErrorBg": "#3c2828",
19
+ "customMsgBg": "#2d2838"
20
+ },
21
+ "colors": {
22
+ "accent": "accent",
23
+ "border": "blue",
24
+ "borderAccent": "cyan",
25
+ "borderMuted": "darkGray",
26
+ "success": "green",
27
+ "error": "red",
28
+ "warning": "yellow",
29
+ "muted": "gray",
30
+ "dim": "dimGray",
31
+ "text": "",
32
+ "thinkingText": "gray",
33
+
34
+ "selectedBg": "selectedBg",
35
+ "userMessageBg": "userMsgBg",
36
+ "userMessageText": "",
37
+ "customMessageBg": "customMsgBg",
38
+ "customMessageText": "",
39
+ "customMessageLabel": "#9575cd",
40
+ "toolPendingBg": "toolPendingBg",
41
+ "toolSuccessBg": "toolSuccessBg",
42
+ "toolErrorBg": "toolErrorBg",
43
+ "toolTitle": "",
44
+ "toolOutput": "gray",
45
+
46
+ "mdHeading": "#f0c674",
47
+ "mdLink": "#81a2be",
48
+ "mdLinkUrl": "dimGray",
49
+ "mdCode": "accent",
50
+ "mdCodeBlock": "green",
51
+ "mdCodeBlockBorder": "gray",
52
+ "mdQuote": "gray",
53
+ "mdQuoteBorder": "gray",
54
+ "mdHr": "gray",
55
+ "mdListBullet": "accent",
56
+
57
+ "toolDiffAdded": "green",
58
+ "toolDiffRemoved": "red",
59
+ "toolDiffContext": "gray",
60
+
61
+ "syntaxComment": "#6A9955",
62
+ "syntaxKeyword": "#569CD6",
63
+ "syntaxFunction": "#DCDCAA",
64
+ "syntaxVariable": "#9CDCFE",
65
+ "syntaxString": "#CE9178",
66
+ "syntaxNumber": "#B5CEA8",
67
+ "syntaxType": "#4EC9B0",
68
+ "syntaxOperator": "#D4D4D4",
69
+ "syntaxPunctuation": "#D4D4D4",
70
+
71
+ "thinkingOff": "darkGray",
72
+ "thinkingMinimal": "#6e6e6e",
73
+ "thinkingLow": "#5f87af",
74
+ "thinkingMedium": "#81a2be",
75
+ "thinkingHigh": "#b294bb",
76
+ "thinkingXhigh": "#d183e8",
77
+
78
+ "bashMode": "green"
79
+ },
80
+ "export": {
81
+ "pageBg": "#18181e",
82
+ "cardBg": "#1e1e24",
83
+ "infoBg": "#3c3728"
84
+ }
85
+ }
@@ -0,0 +1,84 @@
1
+ {
2
+ "$schema": "https://raw.githubusercontent.com/badlogic/pi-mono/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
3
+ "name": "light",
4
+ "vars": {
5
+ "teal": "#5a8080",
6
+ "blue": "#547da7",
7
+ "green": "#588458",
8
+ "red": "#aa5555",
9
+ "yellow": "#9a7326",
10
+ "mediumGray": "#6c6c6c",
11
+ "dimGray": "#767676",
12
+ "lightGray": "#b0b0b0",
13
+ "selectedBg": "#d0d0e0",
14
+ "userMsgBg": "#e8e8e8",
15
+ "toolPendingBg": "#e8e8f0",
16
+ "toolSuccessBg": "#e8f0e8",
17
+ "toolErrorBg": "#f0e8e8",
18
+ "customMsgBg": "#ede7f6"
19
+ },
20
+ "colors": {
21
+ "accent": "teal",
22
+ "border": "blue",
23
+ "borderAccent": "teal",
24
+ "borderMuted": "lightGray",
25
+ "success": "green",
26
+ "error": "red",
27
+ "warning": "yellow",
28
+ "muted": "mediumGray",
29
+ "dim": "dimGray",
30
+ "text": "",
31
+ "thinkingText": "mediumGray",
32
+
33
+ "selectedBg": "selectedBg",
34
+ "userMessageBg": "userMsgBg",
35
+ "userMessageText": "",
36
+ "customMessageBg": "customMsgBg",
37
+ "customMessageText": "",
38
+ "customMessageLabel": "#7e57c2",
39
+ "toolPendingBg": "toolPendingBg",
40
+ "toolSuccessBg": "toolSuccessBg",
41
+ "toolErrorBg": "toolErrorBg",
42
+ "toolTitle": "",
43
+ "toolOutput": "mediumGray",
44
+
45
+ "mdHeading": "yellow",
46
+ "mdLink": "blue",
47
+ "mdLinkUrl": "dimGray",
48
+ "mdCode": "teal",
49
+ "mdCodeBlock": "green",
50
+ "mdCodeBlockBorder": "mediumGray",
51
+ "mdQuote": "mediumGray",
52
+ "mdQuoteBorder": "mediumGray",
53
+ "mdHr": "mediumGray",
54
+ "mdListBullet": "green",
55
+
56
+ "toolDiffAdded": "green",
57
+ "toolDiffRemoved": "red",
58
+ "toolDiffContext": "mediumGray",
59
+
60
+ "syntaxComment": "#008000",
61
+ "syntaxKeyword": "#0000FF",
62
+ "syntaxFunction": "#795E26",
63
+ "syntaxVariable": "#001080",
64
+ "syntaxString": "#A31515",
65
+ "syntaxNumber": "#098658",
66
+ "syntaxType": "#267F99",
67
+ "syntaxOperator": "#000000",
68
+ "syntaxPunctuation": "#000000",
69
+
70
+ "thinkingOff": "lightGray",
71
+ "thinkingMinimal": "#767676",
72
+ "thinkingLow": "blue",
73
+ "thinkingMedium": "teal",
74
+ "thinkingHigh": "#875f87",
75
+ "thinkingXhigh": "#8b008b",
76
+
77
+ "bashMode": "green"
78
+ },
79
+ "export": {
80
+ "pageBg": "#f8f8f8",
81
+ "cardBg": "#ffffff",
82
+ "infoBg": "#fffae6"
83
+ }
84
+ }