30b688bee0
* feat: add worktree post-create hook for environment setup (#597) Add git.worktree_post_create preference — a script path that GSD runs after creating any worktree (both auto-mode and manual /worktree). The script receives SOURCE_DIR and WORKTREE_DIR as environment variables, enabling users to copy .env files, symlink asset directories, or run other setup commands that git worktrees don't inherit from the main tree. Implementation: - Add worktree_post_create field to GitPreferences interface - Add validation in validatePreferences (must be non-empty string) - Add runWorktreePostCreateHook() in auto-worktree.ts — resolves relative paths against project root, runs with 30s timeout, failure is non-fatal (warning only) - Integrate hook call in createAutoWorktree() (auto-mode path) - Integrate hook call in worktree-command.ts (manual /worktree path) - Update docs/configuration.md with full usage guide and example hook script - Update preferences-reference.md with field documentation Example configuration: git: worktree_post_create: .gsd/hooks/post-worktree-create Example hook script: #!/bin/bash cp "$SOURCE_DIR/.env" "$WORKTREE_DIR/.env" ln -sf "$SOURCE_DIR/assets" "$WORKTREE_DIR/assets" Closes #597 * fix: use Node.js scripts in hook tests for Windows compatibility Replace bash hook scripts with cross-platform Node.js scripts in worktree-post-create-hook.test.ts. On macOS/Linux, scripts use #!/usr/bin/env node shebang. On Windows, generates batch files that invoke node -e. Fixes windows-portability CI failures. * fix: Windows CI failures in worktree post-create hook tests - Use path.isAbsolute() instead of startsWith("/") to detect absolute paths on Windows (fixes double-path bug like C:\...\C:\...) - Add .bat extension to hook scripts on Windows so they are recognized as executable by cmd.exe - Extract isWin constant and hookPath() helper for consistent platform-aware test setup Fixes 3 failing tests in windows-portability CI job: - executes hook script with correct env vars - supports absolute hook paths - hook can copy files from source to worktree * fix: adopt main's help command and error message in commands.ts The auto-merge missed main's addition of the help handler, showHelp function, and updated description/subcommands array. Added them manually and updated the visualizer help text to reflect 7-tab TUI. * fix: write Windows hook scripts as .bat + companion .js file The previous approach embedded multi-line JavaScript in a node -e "..." argument inside the .bat file. cmd.exe splits on newlines, so each JS line was interpreted as a separate batch command ('const' is not recognized...). Now writes the JS code to a companion .js file and the .bat invokes it with `node "%~dp0<file>.js"`, which works reliably on Windows. --------- Co-authored-by: TÂCHES <afromanguy@me.com> |
||
|---|---|---|
| .. | ||
| building-coding-agents | ||
| context-and-hooks | ||
| extending-pi | ||
| pi-ui-tui | ||
| what-is-pi | ||
| ADR-001-branchless-worktree-architecture.md | ||
| agent-knowledge-index.md | ||
| architecture.md | ||
| auto-mode.md | ||
| captures-triage.md | ||
| commands.md | ||
| configuration.md | ||
| cost-management.md | ||
| dynamic-model-routing.md | ||
| getting-started.md | ||
| git-strategy.md | ||
| migration.md | ||
| PRD-branchless-worktree-architecture.md | ||
| README.md | ||
| remote-questions.md | ||
| skills.md | ||
| token-optimization.md | ||
| troubleshooting.md | ||
| visualizer.md | ||
| working-in-teams.md | ||
GSD Documentation
Welcome to the GSD documentation. This covers everything from getting started to advanced configuration, auto-mode internals, and extending GSD with the Pi SDK.
User Documentation
| Guide | Description |
|---|---|
| Getting Started | Installation, first run, and basic usage |
| Auto Mode | How autonomous execution works — the state machine, crash recovery, and steering |
| Commands Reference | All commands, keyboard shortcuts, and CLI flags |
| Remote Questions | Discord and Slack integration for headless auto-mode |
| Configuration | Preferences, model selection, git settings, and token profiles |
| Token Optimization | Token profiles, context compression, complexity routing, and adaptive learning (v2.17) |
| Dynamic Model Routing | Complexity-based model selection, cost tables, escalation, and budget pressure (v2.19) |
| Captures & Triage | Fire-and-forget thought capture during auto-mode with automated triage (v2.19) |
| Workflow Visualizer | Interactive TUI overlay for progress, dependencies, metrics, and timeline (v2.19) |
| Cost Management | Budget ceilings, cost tracking, projections, and enforcement modes |
| Git Strategy | Worktree isolation, branching model, and merge behavior |
| Working in Teams | Unique milestone IDs, .gitignore setup, and shared planning artifacts |
| Skills | Bundled skills, skill discovery, and custom skill authoring |
| Migration from v1 | Migrating .planning directories from the original GSD |
| Troubleshooting | Common issues, /gsd doctor, and recovery procedures |
Architecture & Internals
| Guide | Description |
|---|---|
| Architecture Overview | System design, extension model, state-on-disk, and dispatch pipeline |
| Native Engine | Rust N-API modules for performance-critical operations |
| ADR-001: Branchless Worktree Architecture | Decision record for the v2.14 git architecture |
Pi SDK Documentation
These guides cover the underlying Pi SDK that GSD is built on. Useful if you want to extend GSD or build your own agent application.
| Guide | Description |
|---|---|
| What is Pi | Core concepts — modes, agent loop, sessions, tools, providers |
| Extending Pi | Building extensions — tools, commands, UI, events, state |
| Context & Hooks | Context pipeline, hook reference, inter-extension communication |
| Pi UI / TUI | Terminal UI components, theming, keyboard input, rendering |
Research
| Guide | Description |
|---|---|
| Building Coding Agents | Research notes on agent design — decomposition, context engineering, cost/quality tradeoffs |