diff --git a/docs/ADR-001-branchless-worktree-architecture.md b/docs-internal/ADR-001-branchless-worktree-architecture.md similarity index 100% rename from docs/ADR-001-branchless-worktree-architecture.md rename to docs-internal/ADR-001-branchless-worktree-architecture.md diff --git a/docs/ADR-003-pipeline-simplification.md b/docs-internal/ADR-003-pipeline-simplification.md similarity index 100% rename from docs/ADR-003-pipeline-simplification.md rename to docs-internal/ADR-003-pipeline-simplification.md diff --git a/docs/FILE-SYSTEM-MAP.md b/docs-internal/FILE-SYSTEM-MAP.md similarity index 100% rename from docs/FILE-SYSTEM-MAP.md rename to docs-internal/FILE-SYSTEM-MAP.md diff --git a/docs/PRD-branchless-worktree-architecture.md b/docs-internal/PRD-branchless-worktree-architecture.md similarity index 100% rename from docs/PRD-branchless-worktree-architecture.md rename to docs-internal/PRD-branchless-worktree-architecture.md diff --git a/docs/README.md b/docs-internal/README.md similarity index 100% rename from docs/README.md rename to docs-internal/README.md diff --git a/docs/agent-knowledge-index.md b/docs-internal/agent-knowledge-index.md similarity index 100% rename from docs/agent-knowledge-index.md rename to docs-internal/agent-knowledge-index.md diff --git a/docs/architecture.md b/docs-internal/architecture.md similarity index 100% rename from docs/architecture.md rename to docs-internal/architecture.md diff --git a/docs/auto-mode.md b/docs-internal/auto-mode.md similarity index 100% rename from docs/auto-mode.md rename to docs-internal/auto-mode.md diff --git a/docs/building-coding-agents/01-work-decomposition.md b/docs-internal/building-coding-agents/01-work-decomposition.md similarity index 100% rename from docs/building-coding-agents/01-work-decomposition.md rename to docs-internal/building-coding-agents/01-work-decomposition.md diff --git a/docs/building-coding-agents/02-what-to-keep-discard-from-human-engineering.md b/docs-internal/building-coding-agents/02-what-to-keep-discard-from-human-engineering.md similarity index 100% rename from docs/building-coding-agents/02-what-to-keep-discard-from-human-engineering.md rename to docs-internal/building-coding-agents/02-what-to-keep-discard-from-human-engineering.md diff --git a/docs/building-coding-agents/03-state-machine-context-management.md b/docs-internal/building-coding-agents/03-state-machine-context-management.md similarity index 100% rename from docs/building-coding-agents/03-state-machine-context-management.md rename to docs-internal/building-coding-agents/03-state-machine-context-management.md diff --git a/docs/building-coding-agents/04-optimal-storage-for-project-context.md b/docs-internal/building-coding-agents/04-optimal-storage-for-project-context.md similarity index 100% rename from docs/building-coding-agents/04-optimal-storage-for-project-context.md rename to docs-internal/building-coding-agents/04-optimal-storage-for-project-context.md diff --git a/docs/building-coding-agents/05-parallelization-strategy.md b/docs-internal/building-coding-agents/05-parallelization-strategy.md similarity index 100% rename from docs/building-coding-agents/05-parallelization-strategy.md rename to docs-internal/building-coding-agents/05-parallelization-strategy.md diff --git a/docs/building-coding-agents/06-maximizing-agent-autonomy-superpowers.md b/docs-internal/building-coding-agents/06-maximizing-agent-autonomy-superpowers.md similarity index 100% rename from docs/building-coding-agents/06-maximizing-agent-autonomy-superpowers.md rename to docs-internal/building-coding-agents/06-maximizing-agent-autonomy-superpowers.md diff --git a/docs/building-coding-agents/07-system-prompt-llm-vs-deterministic-split.md b/docs-internal/building-coding-agents/07-system-prompt-llm-vs-deterministic-split.md similarity index 100% rename from docs/building-coding-agents/07-system-prompt-llm-vs-deterministic-split.md rename to docs-internal/building-coding-agents/07-system-prompt-llm-vs-deterministic-split.md diff --git a/docs/building-coding-agents/08-speed-optimization.md b/docs-internal/building-coding-agents/08-speed-optimization.md similarity index 100% rename from docs/building-coding-agents/08-speed-optimization.md rename to docs-internal/building-coding-agents/08-speed-optimization.md diff --git a/docs/building-coding-agents/09-top-10-tips-for-a-world-class-agent.md b/docs-internal/building-coding-agents/09-top-10-tips-for-a-world-class-agent.md similarity index 100% rename from docs/building-coding-agents/09-top-10-tips-for-a-world-class-agent.md rename to docs-internal/building-coding-agents/09-top-10-tips-for-a-world-class-agent.md diff --git a/docs/building-coding-agents/10-top-10-pitfalls-to-avoid.md b/docs-internal/building-coding-agents/10-top-10-pitfalls-to-avoid.md similarity index 100% rename from docs/building-coding-agents/10-top-10-pitfalls-to-avoid.md rename to docs-internal/building-coding-agents/10-top-10-pitfalls-to-avoid.md diff --git a/docs/building-coding-agents/11-god-tier-context-engineering.md b/docs-internal/building-coding-agents/11-god-tier-context-engineering.md similarity index 100% rename from docs/building-coding-agents/11-god-tier-context-engineering.md rename to docs-internal/building-coding-agents/11-god-tier-context-engineering.md diff --git a/docs/building-coding-agents/12-handling-ambiguity-contradiction.md b/docs-internal/building-coding-agents/12-handling-ambiguity-contradiction.md similarity index 100% rename from docs/building-coding-agents/12-handling-ambiguity-contradiction.md rename to docs-internal/building-coding-agents/12-handling-ambiguity-contradiction.md diff --git a/docs/building-coding-agents/13-long-running-memory-fidelity.md b/docs-internal/building-coding-agents/13-long-running-memory-fidelity.md similarity index 100% rename from docs/building-coding-agents/13-long-running-memory-fidelity.md rename to docs-internal/building-coding-agents/13-long-running-memory-fidelity.md diff --git a/docs/building-coding-agents/14-multi-agent-semantic-conflict-resolution.md b/docs-internal/building-coding-agents/14-multi-agent-semantic-conflict-resolution.md similarity index 100% rename from docs/building-coding-agents/14-multi-agent-semantic-conflict-resolution.md rename to docs-internal/building-coding-agents/14-multi-agent-semantic-conflict-resolution.md diff --git a/docs/building-coding-agents/15-legacy-code-brownfield-onboarding.md b/docs-internal/building-coding-agents/15-legacy-code-brownfield-onboarding.md similarity index 100% rename from docs/building-coding-agents/15-legacy-code-brownfield-onboarding.md rename to docs-internal/building-coding-agents/15-legacy-code-brownfield-onboarding.md diff --git a/docs/building-coding-agents/16-encoding-taste-aesthetics.md b/docs-internal/building-coding-agents/16-encoding-taste-aesthetics.md similarity index 100% rename from docs/building-coding-agents/16-encoding-taste-aesthetics.md rename to docs-internal/building-coding-agents/16-encoding-taste-aesthetics.md diff --git a/docs/building-coding-agents/17-irreversible-operations-safety-architecture.md b/docs-internal/building-coding-agents/17-irreversible-operations-safety-architecture.md similarity index 100% rename from docs/building-coding-agents/17-irreversible-operations-safety-architecture.md rename to docs-internal/building-coding-agents/17-irreversible-operations-safety-architecture.md diff --git a/docs/building-coding-agents/18-the-handoff-problem-agent-human-maintainability.md b/docs-internal/building-coding-agents/18-the-handoff-problem-agent-human-maintainability.md similarity index 100% rename from docs/building-coding-agents/18-the-handoff-problem-agent-human-maintainability.md rename to docs-internal/building-coding-agents/18-the-handoff-problem-agent-human-maintainability.md diff --git a/docs/building-coding-agents/19-when-to-scrap-and-start-over.md b/docs-internal/building-coding-agents/19-when-to-scrap-and-start-over.md similarity index 100% rename from docs/building-coding-agents/19-when-to-scrap-and-start-over.md rename to docs-internal/building-coding-agents/19-when-to-scrap-and-start-over.md diff --git a/docs/building-coding-agents/20-error-taxonomy-routing.md b/docs-internal/building-coding-agents/20-error-taxonomy-routing.md similarity index 100% rename from docs/building-coding-agents/20-error-taxonomy-routing.md rename to docs-internal/building-coding-agents/20-error-taxonomy-routing.md diff --git a/docs/building-coding-agents/21-cost-quality-tradeoff-model-routing.md b/docs-internal/building-coding-agents/21-cost-quality-tradeoff-model-routing.md similarity index 100% rename from docs/building-coding-agents/21-cost-quality-tradeoff-model-routing.md rename to docs-internal/building-coding-agents/21-cost-quality-tradeoff-model-routing.md diff --git a/docs/building-coding-agents/22-cross-project-learning-reusable-intelligence.md b/docs-internal/building-coding-agents/22-cross-project-learning-reusable-intelligence.md similarity index 100% rename from docs/building-coding-agents/22-cross-project-learning-reusable-intelligence.md rename to docs-internal/building-coding-agents/22-cross-project-learning-reusable-intelligence.md diff --git a/docs/building-coding-agents/23-evolution-across-project-scale.md b/docs-internal/building-coding-agents/23-evolution-across-project-scale.md similarity index 100% rename from docs/building-coding-agents/23-evolution-across-project-scale.md rename to docs-internal/building-coding-agents/23-evolution-across-project-scale.md diff --git a/docs/building-coding-agents/24-security-trust-boundaries.md b/docs-internal/building-coding-agents/24-security-trust-boundaries.md similarity index 100% rename from docs/building-coding-agents/24-security-trust-boundaries.md rename to docs-internal/building-coding-agents/24-security-trust-boundaries.md diff --git a/docs/building-coding-agents/25-designing-for-non-technical-users-vibe-coders.md b/docs-internal/building-coding-agents/25-designing-for-non-technical-users-vibe-coders.md similarity index 100% rename from docs/building-coding-agents/25-designing-for-non-technical-users-vibe-coders.md rename to docs-internal/building-coding-agents/25-designing-for-non-technical-users-vibe-coders.md diff --git a/docs/building-coding-agents/26-cross-cutting-themes-where-all-4-models-converge.md b/docs-internal/building-coding-agents/26-cross-cutting-themes-where-all-4-models-converge.md similarity index 100% rename from docs/building-coding-agents/26-cross-cutting-themes-where-all-4-models-converge.md rename to docs-internal/building-coding-agents/26-cross-cutting-themes-where-all-4-models-converge.md diff --git a/docs/building-coding-agents/README.md b/docs-internal/building-coding-agents/README.md similarity index 100% rename from docs/building-coding-agents/README.md rename to docs-internal/building-coding-agents/README.md diff --git a/docs/captures-triage.md b/docs-internal/captures-triage.md similarity index 100% rename from docs/captures-triage.md rename to docs-internal/captures-triage.md diff --git a/docs/ci-cd-pipeline.md b/docs-internal/ci-cd-pipeline.md similarity index 100% rename from docs/ci-cd-pipeline.md rename to docs-internal/ci-cd-pipeline.md diff --git a/docs/commands.md b/docs-internal/commands.md similarity index 100% rename from docs/commands.md rename to docs-internal/commands.md diff --git a/docs/configuration.md b/docs-internal/configuration.md similarity index 100% rename from docs/configuration.md rename to docs-internal/configuration.md diff --git a/docs/context-and-hooks/01-the-context-pipeline.md b/docs-internal/context-and-hooks/01-the-context-pipeline.md similarity index 100% rename from docs/context-and-hooks/01-the-context-pipeline.md rename to docs-internal/context-and-hooks/01-the-context-pipeline.md diff --git a/docs/context-and-hooks/02-hook-reference.md b/docs-internal/context-and-hooks/02-hook-reference.md similarity index 100% rename from docs/context-and-hooks/02-hook-reference.md rename to docs-internal/context-and-hooks/02-hook-reference.md diff --git a/docs/context-and-hooks/03-context-injection-patterns.md b/docs-internal/context-and-hooks/03-context-injection-patterns.md similarity index 100% rename from docs/context-and-hooks/03-context-injection-patterns.md rename to docs-internal/context-and-hooks/03-context-injection-patterns.md diff --git a/docs/context-and-hooks/04-message-types-and-llm-visibility.md b/docs-internal/context-and-hooks/04-message-types-and-llm-visibility.md similarity index 100% rename from docs/context-and-hooks/04-message-types-and-llm-visibility.md rename to docs-internal/context-and-hooks/04-message-types-and-llm-visibility.md diff --git a/docs/context-and-hooks/05-inter-extension-communication.md b/docs-internal/context-and-hooks/05-inter-extension-communication.md similarity index 100% rename from docs/context-and-hooks/05-inter-extension-communication.md rename to docs-internal/context-and-hooks/05-inter-extension-communication.md diff --git a/docs/context-and-hooks/06-advanced-patterns-from-source.md b/docs-internal/context-and-hooks/06-advanced-patterns-from-source.md similarity index 100% rename from docs/context-and-hooks/06-advanced-patterns-from-source.md rename to docs-internal/context-and-hooks/06-advanced-patterns-from-source.md diff --git a/docs/context-and-hooks/07-the-system-prompt-anatomy.md b/docs-internal/context-and-hooks/07-the-system-prompt-anatomy.md similarity index 100% rename from docs/context-and-hooks/07-the-system-prompt-anatomy.md rename to docs-internal/context-and-hooks/07-the-system-prompt-anatomy.md diff --git a/docs/context-and-hooks/README.md b/docs-internal/context-and-hooks/README.md similarity index 100% rename from docs/context-and-hooks/README.md rename to docs-internal/context-and-hooks/README.md diff --git a/docs/cost-management.md b/docs-internal/cost-management.md similarity index 100% rename from docs/cost-management.md rename to docs-internal/cost-management.md diff --git a/docs/custom-models.md b/docs-internal/custom-models.md similarity index 100% rename from docs/custom-models.md rename to docs-internal/custom-models.md diff --git a/docs/dynamic-model-routing.md b/docs-internal/dynamic-model-routing.md similarity index 100% rename from docs/dynamic-model-routing.md rename to docs-internal/dynamic-model-routing.md diff --git a/docs/extending-pi/01-what-are-extensions.md b/docs-internal/extending-pi/01-what-are-extensions.md similarity index 100% rename from docs/extending-pi/01-what-are-extensions.md rename to docs-internal/extending-pi/01-what-are-extensions.md diff --git a/docs/extending-pi/02-architecture-mental-model.md b/docs-internal/extending-pi/02-architecture-mental-model.md similarity index 100% rename from docs/extending-pi/02-architecture-mental-model.md rename to docs-internal/extending-pi/02-architecture-mental-model.md diff --git a/docs/extending-pi/03-getting-started.md b/docs-internal/extending-pi/03-getting-started.md similarity index 100% rename from docs/extending-pi/03-getting-started.md rename to docs-internal/extending-pi/03-getting-started.md diff --git a/docs/extending-pi/04-extension-locations-discovery.md b/docs-internal/extending-pi/04-extension-locations-discovery.md similarity index 100% rename from docs/extending-pi/04-extension-locations-discovery.md rename to docs-internal/extending-pi/04-extension-locations-discovery.md diff --git a/docs/extending-pi/05-extension-structure-styles.md b/docs-internal/extending-pi/05-extension-structure-styles.md similarity index 100% rename from docs/extending-pi/05-extension-structure-styles.md rename to docs-internal/extending-pi/05-extension-structure-styles.md diff --git a/docs/extending-pi/06-the-extension-lifecycle.md b/docs-internal/extending-pi/06-the-extension-lifecycle.md similarity index 100% rename from docs/extending-pi/06-the-extension-lifecycle.md rename to docs-internal/extending-pi/06-the-extension-lifecycle.md diff --git a/docs/extending-pi/07-events-the-nervous-system.md b/docs-internal/extending-pi/07-events-the-nervous-system.md similarity index 100% rename from docs/extending-pi/07-events-the-nervous-system.md rename to docs-internal/extending-pi/07-events-the-nervous-system.md diff --git a/docs/extending-pi/08-extensioncontext-what-you-can-access.md b/docs-internal/extending-pi/08-extensioncontext-what-you-can-access.md similarity index 100% rename from docs/extending-pi/08-extensioncontext-what-you-can-access.md rename to docs-internal/extending-pi/08-extensioncontext-what-you-can-access.md diff --git a/docs/extending-pi/09-extensionapi-what-you-can-do.md b/docs-internal/extending-pi/09-extensionapi-what-you-can-do.md similarity index 100% rename from docs/extending-pi/09-extensionapi-what-you-can-do.md rename to docs-internal/extending-pi/09-extensionapi-what-you-can-do.md diff --git a/docs/extending-pi/10-custom-tools-giving-the-llm-new-abilities.md b/docs-internal/extending-pi/10-custom-tools-giving-the-llm-new-abilities.md similarity index 100% rename from docs/extending-pi/10-custom-tools-giving-the-llm-new-abilities.md rename to docs-internal/extending-pi/10-custom-tools-giving-the-llm-new-abilities.md diff --git a/docs/extending-pi/11-custom-commands-user-facing-actions.md b/docs-internal/extending-pi/11-custom-commands-user-facing-actions.md similarity index 100% rename from docs/extending-pi/11-custom-commands-user-facing-actions.md rename to docs-internal/extending-pi/11-custom-commands-user-facing-actions.md diff --git a/docs/extending-pi/12-custom-ui-visual-components.md b/docs-internal/extending-pi/12-custom-ui-visual-components.md similarity index 100% rename from docs/extending-pi/12-custom-ui-visual-components.md rename to docs-internal/extending-pi/12-custom-ui-visual-components.md diff --git a/docs/extending-pi/13-state-management-persistence.md b/docs-internal/extending-pi/13-state-management-persistence.md similarity index 100% rename from docs/extending-pi/13-state-management-persistence.md rename to docs-internal/extending-pi/13-state-management-persistence.md diff --git a/docs/extending-pi/14-custom-rendering-controlling-what-the-user-sees.md b/docs-internal/extending-pi/14-custom-rendering-controlling-what-the-user-sees.md similarity index 100% rename from docs/extending-pi/14-custom-rendering-controlling-what-the-user-sees.md rename to docs-internal/extending-pi/14-custom-rendering-controlling-what-the-user-sees.md diff --git a/docs/extending-pi/15-system-prompt-modification.md b/docs-internal/extending-pi/15-system-prompt-modification.md similarity index 100% rename from docs/extending-pi/15-system-prompt-modification.md rename to docs-internal/extending-pi/15-system-prompt-modification.md diff --git a/docs/extending-pi/16-compaction-session-control.md b/docs-internal/extending-pi/16-compaction-session-control.md similarity index 100% rename from docs/extending-pi/16-compaction-session-control.md rename to docs-internal/extending-pi/16-compaction-session-control.md diff --git a/docs/extending-pi/17-model-provider-management.md b/docs-internal/extending-pi/17-model-provider-management.md similarity index 100% rename from docs/extending-pi/17-model-provider-management.md rename to docs-internal/extending-pi/17-model-provider-management.md diff --git a/docs/extending-pi/18-remote-execution-tool-overrides.md b/docs-internal/extending-pi/18-remote-execution-tool-overrides.md similarity index 100% rename from docs/extending-pi/18-remote-execution-tool-overrides.md rename to docs-internal/extending-pi/18-remote-execution-tool-overrides.md diff --git a/docs/extending-pi/19-packaging-distribution.md b/docs-internal/extending-pi/19-packaging-distribution.md similarity index 100% rename from docs/extending-pi/19-packaging-distribution.md rename to docs-internal/extending-pi/19-packaging-distribution.md diff --git a/docs/extending-pi/20-mode-behavior.md b/docs-internal/extending-pi/20-mode-behavior.md similarity index 100% rename from docs/extending-pi/20-mode-behavior.md rename to docs-internal/extending-pi/20-mode-behavior.md diff --git a/docs/extending-pi/21-error-handling.md b/docs-internal/extending-pi/21-error-handling.md similarity index 100% rename from docs/extending-pi/21-error-handling.md rename to docs-internal/extending-pi/21-error-handling.md diff --git a/docs/extending-pi/22-key-rules-gotchas.md b/docs-internal/extending-pi/22-key-rules-gotchas.md similarity index 100% rename from docs/extending-pi/22-key-rules-gotchas.md rename to docs-internal/extending-pi/22-key-rules-gotchas.md diff --git a/docs/extending-pi/23-file-reference-documentation.md b/docs-internal/extending-pi/23-file-reference-documentation.md similarity index 100% rename from docs/extending-pi/23-file-reference-documentation.md rename to docs-internal/extending-pi/23-file-reference-documentation.md diff --git a/docs/extending-pi/24-file-reference-example-extensions.md b/docs-internal/extending-pi/24-file-reference-example-extensions.md similarity index 100% rename from docs/extending-pi/24-file-reference-example-extensions.md rename to docs-internal/extending-pi/24-file-reference-example-extensions.md diff --git a/docs/extending-pi/25-slash-command-subcommand-patterns.md b/docs-internal/extending-pi/25-slash-command-subcommand-patterns.md similarity index 100% rename from docs/extending-pi/25-slash-command-subcommand-patterns.md rename to docs-internal/extending-pi/25-slash-command-subcommand-patterns.md diff --git a/docs/extending-pi/README.md b/docs-internal/extending-pi/README.md similarity index 100% rename from docs/extending-pi/README.md rename to docs-internal/extending-pi/README.md diff --git a/docs/getting-started.md b/docs-internal/getting-started.md similarity index 100% rename from docs/getting-started.md rename to docs-internal/getting-started.md diff --git a/docs/git-strategy.md b/docs-internal/git-strategy.md similarity index 100% rename from docs/git-strategy.md rename to docs-internal/git-strategy.md diff --git a/docs/migration.md b/docs-internal/migration.md similarity index 100% rename from docs/migration.md rename to docs-internal/migration.md diff --git a/docs/node-lts-macos.md b/docs-internal/node-lts-macos.md similarity index 100% rename from docs/node-lts-macos.md rename to docs-internal/node-lts-macos.md diff --git a/docs/parallel-orchestration.md b/docs-internal/parallel-orchestration.md similarity index 100% rename from docs/parallel-orchestration.md rename to docs-internal/parallel-orchestration.md diff --git a/docs/pi-ui-tui/01-the-ui-architecture.md b/docs-internal/pi-ui-tui/01-the-ui-architecture.md similarity index 100% rename from docs/pi-ui-tui/01-the-ui-architecture.md rename to docs-internal/pi-ui-tui/01-the-ui-architecture.md diff --git a/docs/pi-ui-tui/02-the-component-interface-foundation-of-everything.md b/docs-internal/pi-ui-tui/02-the-component-interface-foundation-of-everything.md similarity index 100% rename from docs/pi-ui-tui/02-the-component-interface-foundation-of-everything.md rename to docs-internal/pi-ui-tui/02-the-component-interface-foundation-of-everything.md diff --git a/docs/pi-ui-tui/03-entry-points-how-ui-gets-on-screen.md b/docs-internal/pi-ui-tui/03-entry-points-how-ui-gets-on-screen.md similarity index 100% rename from docs/pi-ui-tui/03-entry-points-how-ui-gets-on-screen.md rename to docs-internal/pi-ui-tui/03-entry-points-how-ui-gets-on-screen.md diff --git a/docs/pi-ui-tui/04-built-in-dialog-methods.md b/docs-internal/pi-ui-tui/04-built-in-dialog-methods.md similarity index 100% rename from docs/pi-ui-tui/04-built-in-dialog-methods.md rename to docs-internal/pi-ui-tui/04-built-in-dialog-methods.md diff --git a/docs/pi-ui-tui/05-persistent-ui-elements.md b/docs-internal/pi-ui-tui/05-persistent-ui-elements.md similarity index 100% rename from docs/pi-ui-tui/05-persistent-ui-elements.md rename to docs-internal/pi-ui-tui/05-persistent-ui-elements.md diff --git a/docs/pi-ui-tui/06-ctx-ui-custom-full-custom-components.md b/docs-internal/pi-ui-tui/06-ctx-ui-custom-full-custom-components.md similarity index 100% rename from docs/pi-ui-tui/06-ctx-ui-custom-full-custom-components.md rename to docs-internal/pi-ui-tui/06-ctx-ui-custom-full-custom-components.md diff --git a/docs/pi-ui-tui/07-built-in-components-the-building-blocks.md b/docs-internal/pi-ui-tui/07-built-in-components-the-building-blocks.md similarity index 100% rename from docs/pi-ui-tui/07-built-in-components-the-building-blocks.md rename to docs-internal/pi-ui-tui/07-built-in-components-the-building-blocks.md diff --git a/docs/pi-ui-tui/08-high-level-components-from-pi-coding-agent.md b/docs-internal/pi-ui-tui/08-high-level-components-from-pi-coding-agent.md similarity index 100% rename from docs/pi-ui-tui/08-high-level-components-from-pi-coding-agent.md rename to docs-internal/pi-ui-tui/08-high-level-components-from-pi-coding-agent.md diff --git a/docs/pi-ui-tui/09-keyboard-input-how-to-handle-keys.md b/docs-internal/pi-ui-tui/09-keyboard-input-how-to-handle-keys.md similarity index 100% rename from docs/pi-ui-tui/09-keyboard-input-how-to-handle-keys.md rename to docs-internal/pi-ui-tui/09-keyboard-input-how-to-handle-keys.md diff --git a/docs/pi-ui-tui/10-line-width-the-cardinal-rule.md b/docs-internal/pi-ui-tui/10-line-width-the-cardinal-rule.md similarity index 100% rename from docs/pi-ui-tui/10-line-width-the-cardinal-rule.md rename to docs-internal/pi-ui-tui/10-line-width-the-cardinal-rule.md diff --git a/docs/pi-ui-tui/11-theming-colors-and-styles.md b/docs-internal/pi-ui-tui/11-theming-colors-and-styles.md similarity index 100% rename from docs/pi-ui-tui/11-theming-colors-and-styles.md rename to docs-internal/pi-ui-tui/11-theming-colors-and-styles.md diff --git a/docs/pi-ui-tui/12-overlays-floating-modals-and-panels.md b/docs-internal/pi-ui-tui/12-overlays-floating-modals-and-panels.md similarity index 100% rename from docs/pi-ui-tui/12-overlays-floating-modals-and-panels.md rename to docs-internal/pi-ui-tui/12-overlays-floating-modals-and-panels.md diff --git a/docs/pi-ui-tui/13-custom-editors-replacing-the-input.md b/docs-internal/pi-ui-tui/13-custom-editors-replacing-the-input.md similarity index 100% rename from docs/pi-ui-tui/13-custom-editors-replacing-the-input.md rename to docs-internal/pi-ui-tui/13-custom-editors-replacing-the-input.md diff --git a/docs/pi-ui-tui/14-tool-rendering-custom-tool-display.md b/docs-internal/pi-ui-tui/14-tool-rendering-custom-tool-display.md similarity index 100% rename from docs/pi-ui-tui/14-tool-rendering-custom-tool-display.md rename to docs-internal/pi-ui-tui/14-tool-rendering-custom-tool-display.md diff --git a/docs/pi-ui-tui/15-message-rendering-custom-message-display.md b/docs-internal/pi-ui-tui/15-message-rendering-custom-message-display.md similarity index 100% rename from docs/pi-ui-tui/15-message-rendering-custom-message-display.md rename to docs-internal/pi-ui-tui/15-message-rendering-custom-message-display.md diff --git a/docs/pi-ui-tui/16-performance-caching-and-invalidation.md b/docs-internal/pi-ui-tui/16-performance-caching-and-invalidation.md similarity index 100% rename from docs/pi-ui-tui/16-performance-caching-and-invalidation.md rename to docs-internal/pi-ui-tui/16-performance-caching-and-invalidation.md diff --git a/docs/pi-ui-tui/17-theme-changes-and-invalidation.md b/docs-internal/pi-ui-tui/17-theme-changes-and-invalidation.md similarity index 100% rename from docs/pi-ui-tui/17-theme-changes-and-invalidation.md rename to docs-internal/pi-ui-tui/17-theme-changes-and-invalidation.md diff --git a/docs/pi-ui-tui/18-ime-support-the-focusable-interface.md b/docs-internal/pi-ui-tui/18-ime-support-the-focusable-interface.md similarity index 100% rename from docs/pi-ui-tui/18-ime-support-the-focusable-interface.md rename to docs-internal/pi-ui-tui/18-ime-support-the-focusable-interface.md diff --git a/docs/pi-ui-tui/19-building-a-complete-component-step-by-step.md b/docs-internal/pi-ui-tui/19-building-a-complete-component-step-by-step.md similarity index 100% rename from docs/pi-ui-tui/19-building-a-complete-component-step-by-step.md rename to docs-internal/pi-ui-tui/19-building-a-complete-component-step-by-step.md diff --git a/docs/pi-ui-tui/20-real-world-patterns-from-examples.md b/docs-internal/pi-ui-tui/20-real-world-patterns-from-examples.md similarity index 100% rename from docs/pi-ui-tui/20-real-world-patterns-from-examples.md rename to docs-internal/pi-ui-tui/20-real-world-patterns-from-examples.md diff --git a/docs/pi-ui-tui/21-common-mistakes-and-how-to-avoid-them.md b/docs-internal/pi-ui-tui/21-common-mistakes-and-how-to-avoid-them.md similarity index 100% rename from docs/pi-ui-tui/21-common-mistakes-and-how-to-avoid-them.md rename to docs-internal/pi-ui-tui/21-common-mistakes-and-how-to-avoid-them.md diff --git a/docs/pi-ui-tui/22-quick-reference-all-ui-apis.md b/docs-internal/pi-ui-tui/22-quick-reference-all-ui-apis.md similarity index 100% rename from docs/pi-ui-tui/22-quick-reference-all-ui-apis.md rename to docs-internal/pi-ui-tui/22-quick-reference-all-ui-apis.md diff --git a/docs/pi-ui-tui/23-file-reference-example-extensions-with-ui.md b/docs-internal/pi-ui-tui/23-file-reference-example-extensions-with-ui.md similarity index 100% rename from docs/pi-ui-tui/23-file-reference-example-extensions-with-ui.md rename to docs-internal/pi-ui-tui/23-file-reference-example-extensions-with-ui.md diff --git a/docs/pi-ui-tui/README.md b/docs-internal/pi-ui-tui/README.md similarity index 100% rename from docs/pi-ui-tui/README.md rename to docs-internal/pi-ui-tui/README.md diff --git a/docs/pr-1530/01-full.png b/docs-internal/pr-1530/01-full.png similarity index 100% rename from docs/pr-1530/01-full.png rename to docs-internal/pr-1530/01-full.png diff --git a/docs/pr-1530/02-small.png b/docs-internal/pr-1530/02-small.png similarity index 100% rename from docs/pr-1530/02-small.png rename to docs-internal/pr-1530/02-small.png diff --git a/docs/pr-1530/03-min.png b/docs-internal/pr-1530/03-min.png similarity index 100% rename from docs/pr-1530/03-min.png rename to docs-internal/pr-1530/03-min.png diff --git a/docs/pr-1530/04-unhealthy.png b/docs-internal/pr-1530/04-unhealthy.png similarity index 100% rename from docs/pr-1530/04-unhealthy.png rename to docs-internal/pr-1530/04-unhealthy.png diff --git a/docs/pr-876/01-index.png b/docs-internal/pr-876/01-index.png similarity index 100% rename from docs/pr-876/01-index.png rename to docs-internal/pr-876/01-index.png diff --git a/docs/pr-876/02-summary.png b/docs-internal/pr-876/02-summary.png similarity index 100% rename from docs/pr-876/02-summary.png rename to docs-internal/pr-876/02-summary.png diff --git a/docs/pr-876/03-progress.png b/docs-internal/pr-876/03-progress.png similarity index 100% rename from docs/pr-876/03-progress.png rename to docs-internal/pr-876/03-progress.png diff --git a/docs/pr-876/04-depgraph.png b/docs-internal/pr-876/04-depgraph.png similarity index 100% rename from docs/pr-876/04-depgraph.png rename to docs-internal/pr-876/04-depgraph.png diff --git a/docs/pr-876/05-metrics.png b/docs-internal/pr-876/05-metrics.png similarity index 100% rename from docs/pr-876/05-metrics.png rename to docs-internal/pr-876/05-metrics.png diff --git a/docs/pr-876/06-changelog.png b/docs-internal/pr-876/06-changelog.png similarity index 100% rename from docs/pr-876/06-changelog.png rename to docs-internal/pr-876/06-changelog.png diff --git a/docs/pr-876/06-timeline.png b/docs-internal/pr-876/06-timeline.png similarity index 100% rename from docs/pr-876/06-timeline.png rename to docs-internal/pr-876/06-timeline.png diff --git a/docs/pr-876/07-changelog.png b/docs-internal/pr-876/07-changelog.png similarity index 100% rename from docs/pr-876/07-changelog.png rename to docs-internal/pr-876/07-changelog.png diff --git a/docs/pr-876/07-knowledge.png b/docs-internal/pr-876/07-knowledge.png similarity index 100% rename from docs/pr-876/07-knowledge.png rename to docs-internal/pr-876/07-knowledge.png diff --git a/docs/pr-876/08-knowledge.png b/docs-internal/pr-876/08-knowledge.png similarity index 100% rename from docs/pr-876/08-knowledge.png rename to docs-internal/pr-876/08-knowledge.png diff --git a/docs/pr-876/09-captures.png b/docs-internal/pr-876/09-captures.png similarity index 100% rename from docs/pr-876/09-captures.png rename to docs-internal/pr-876/09-captures.png diff --git a/docs/pr-876/10-artifacts.png b/docs-internal/pr-876/10-artifacts.png similarity index 100% rename from docs/pr-876/10-artifacts.png rename to docs-internal/pr-876/10-artifacts.png diff --git a/docs/proposals/698-browser-tools-feature-additions.md b/docs-internal/proposals/698-browser-tools-feature-additions.md similarity index 100% rename from docs/proposals/698-browser-tools-feature-additions.md rename to docs-internal/proposals/698-browser-tools-feature-additions.md diff --git a/docs/proposals/rfc-gitops-branching-strategy.md b/docs-internal/proposals/rfc-gitops-branching-strategy.md similarity index 100% rename from docs/proposals/rfc-gitops-branching-strategy.md rename to docs-internal/proposals/rfc-gitops-branching-strategy.md diff --git a/docs/proposals/workflows/README.md b/docs-internal/proposals/workflows/README.md similarity index 100% rename from docs/proposals/workflows/README.md rename to docs-internal/proposals/workflows/README.md diff --git a/docs/proposals/workflows/backmerge.yml b/docs-internal/proposals/workflows/backmerge.yml similarity index 100% rename from docs/proposals/workflows/backmerge.yml rename to docs-internal/proposals/workflows/backmerge.yml diff --git a/docs/proposals/workflows/create-release.yml b/docs-internal/proposals/workflows/create-release.yml similarity index 100% rename from docs/proposals/workflows/create-release.yml rename to docs-internal/proposals/workflows/create-release.yml diff --git a/docs/proposals/workflows/sync-next.yml b/docs-internal/proposals/workflows/sync-next.yml similarity index 100% rename from docs/proposals/workflows/sync-next.yml rename to docs-internal/proposals/workflows/sync-next.yml diff --git a/docs/remote-questions.md b/docs-internal/remote-questions.md similarity index 100% rename from docs/remote-questions.md rename to docs-internal/remote-questions.md diff --git a/docs/skills.md b/docs-internal/skills.md similarity index 100% rename from docs/skills.md rename to docs-internal/skills.md diff --git a/docs/superpowers/plans/2026-03-17-cicd-pipeline.md b/docs-internal/superpowers/plans/2026-03-17-cicd-pipeline.md similarity index 100% rename from docs/superpowers/plans/2026-03-17-cicd-pipeline.md rename to docs-internal/superpowers/plans/2026-03-17-cicd-pipeline.md diff --git a/docs/superpowers/specs/2026-03-17-cicd-pipeline-design.md b/docs-internal/superpowers/specs/2026-03-17-cicd-pipeline-design.md similarity index 100% rename from docs/superpowers/specs/2026-03-17-cicd-pipeline-design.md rename to docs-internal/superpowers/specs/2026-03-17-cicd-pipeline-design.md diff --git a/docs/token-optimization.md b/docs-internal/token-optimization.md similarity index 100% rename from docs/token-optimization.md rename to docs-internal/token-optimization.md diff --git a/docs/troubleshooting.md b/docs-internal/troubleshooting.md similarity index 100% rename from docs/troubleshooting.md rename to docs-internal/troubleshooting.md diff --git a/docs/visualizer.md b/docs-internal/visualizer.md similarity index 100% rename from docs/visualizer.md rename to docs-internal/visualizer.md diff --git a/docs/web-interface.md b/docs-internal/web-interface.md similarity index 100% rename from docs/web-interface.md rename to docs-internal/web-interface.md diff --git a/docs/what-is-pi/01-what-pi-is.md b/docs-internal/what-is-pi/01-what-pi-is.md similarity index 100% rename from docs/what-is-pi/01-what-pi-is.md rename to docs-internal/what-is-pi/01-what-pi-is.md diff --git a/docs/what-is-pi/02-design-philosophy.md b/docs-internal/what-is-pi/02-design-philosophy.md similarity index 100% rename from docs/what-is-pi/02-design-philosophy.md rename to docs-internal/what-is-pi/02-design-philosophy.md diff --git a/docs/what-is-pi/03-the-four-modes-of-operation.md b/docs-internal/what-is-pi/03-the-four-modes-of-operation.md similarity index 100% rename from docs/what-is-pi/03-the-four-modes-of-operation.md rename to docs-internal/what-is-pi/03-the-four-modes-of-operation.md diff --git a/docs/what-is-pi/04-the-architecture-how-everything-fits-together.md b/docs-internal/what-is-pi/04-the-architecture-how-everything-fits-together.md similarity index 100% rename from docs/what-is-pi/04-the-architecture-how-everything-fits-together.md rename to docs-internal/what-is-pi/04-the-architecture-how-everything-fits-together.md diff --git a/docs/what-is-pi/05-the-agent-loop-how-pi-thinks.md b/docs-internal/what-is-pi/05-the-agent-loop-how-pi-thinks.md similarity index 100% rename from docs/what-is-pi/05-the-agent-loop-how-pi-thinks.md rename to docs-internal/what-is-pi/05-the-agent-loop-how-pi-thinks.md diff --git a/docs/what-is-pi/06-tools-how-pi-acts-on-the-world.md b/docs-internal/what-is-pi/06-tools-how-pi-acts-on-the-world.md similarity index 100% rename from docs/what-is-pi/06-tools-how-pi-acts-on-the-world.md rename to docs-internal/what-is-pi/06-tools-how-pi-acts-on-the-world.md diff --git a/docs/what-is-pi/07-sessions-memory-that-branches.md b/docs-internal/what-is-pi/07-sessions-memory-that-branches.md similarity index 100% rename from docs/what-is-pi/07-sessions-memory-that-branches.md rename to docs-internal/what-is-pi/07-sessions-memory-that-branches.md diff --git a/docs/what-is-pi/08-compaction-how-pi-manages-context-limits.md b/docs-internal/what-is-pi/08-compaction-how-pi-manages-context-limits.md similarity index 100% rename from docs/what-is-pi/08-compaction-how-pi-manages-context-limits.md rename to docs-internal/what-is-pi/08-compaction-how-pi-manages-context-limits.md diff --git a/docs/what-is-pi/09-the-customization-stack.md b/docs-internal/what-is-pi/09-the-customization-stack.md similarity index 100% rename from docs/what-is-pi/09-the-customization-stack.md rename to docs-internal/what-is-pi/09-the-customization-stack.md diff --git a/docs/what-is-pi/10-providers-models-multi-model-by-default.md b/docs-internal/what-is-pi/10-providers-models-multi-model-by-default.md similarity index 100% rename from docs/what-is-pi/10-providers-models-multi-model-by-default.md rename to docs-internal/what-is-pi/10-providers-models-multi-model-by-default.md diff --git a/docs/what-is-pi/11-the-interactive-tui.md b/docs-internal/what-is-pi/11-the-interactive-tui.md similarity index 100% rename from docs/what-is-pi/11-the-interactive-tui.md rename to docs-internal/what-is-pi/11-the-interactive-tui.md diff --git a/docs/what-is-pi/12-the-message-queue-talking-while-pi-thinks.md b/docs-internal/what-is-pi/12-the-message-queue-talking-while-pi-thinks.md similarity index 100% rename from docs/what-is-pi/12-the-message-queue-talking-while-pi-thinks.md rename to docs-internal/what-is-pi/12-the-message-queue-talking-while-pi-thinks.md diff --git a/docs/what-is-pi/13-context-files-project-instructions.md b/docs-internal/what-is-pi/13-context-files-project-instructions.md similarity index 100% rename from docs/what-is-pi/13-context-files-project-instructions.md rename to docs-internal/what-is-pi/13-context-files-project-instructions.md diff --git a/docs/what-is-pi/14-the-sdk-rpc-embedding-pi.md b/docs-internal/what-is-pi/14-the-sdk-rpc-embedding-pi.md similarity index 100% rename from docs/what-is-pi/14-the-sdk-rpc-embedding-pi.md rename to docs-internal/what-is-pi/14-the-sdk-rpc-embedding-pi.md diff --git a/docs/what-is-pi/15-pi-packages-the-ecosystem.md b/docs-internal/what-is-pi/15-pi-packages-the-ecosystem.md similarity index 100% rename from docs/what-is-pi/15-pi-packages-the-ecosystem.md rename to docs-internal/what-is-pi/15-pi-packages-the-ecosystem.md diff --git a/docs/what-is-pi/16-why-pi-matters-what-makes-it-different.md b/docs-internal/what-is-pi/16-why-pi-matters-what-makes-it-different.md similarity index 100% rename from docs/what-is-pi/16-why-pi-matters-what-makes-it-different.md rename to docs-internal/what-is-pi/16-why-pi-matters-what-makes-it-different.md diff --git a/docs/what-is-pi/17-file-reference-all-documentation.md b/docs-internal/what-is-pi/17-file-reference-all-documentation.md similarity index 100% rename from docs/what-is-pi/17-file-reference-all-documentation.md rename to docs-internal/what-is-pi/17-file-reference-all-documentation.md diff --git a/docs/what-is-pi/18-quick-reference-commands-shortcuts.md b/docs-internal/what-is-pi/18-quick-reference-commands-shortcuts.md similarity index 100% rename from docs/what-is-pi/18-quick-reference-commands-shortcuts.md rename to docs-internal/what-is-pi/18-quick-reference-commands-shortcuts.md diff --git a/docs/what-is-pi/19-building-branded-apps-on-top-of-pi.md b/docs-internal/what-is-pi/19-building-branded-apps-on-top-of-pi.md similarity index 100% rename from docs/what-is-pi/19-building-branded-apps-on-top-of-pi.md rename to docs-internal/what-is-pi/19-building-branded-apps-on-top-of-pi.md diff --git a/docs/what-is-pi/README.md b/docs-internal/what-is-pi/README.md similarity index 100% rename from docs/what-is-pi/README.md rename to docs-internal/what-is-pi/README.md diff --git a/docs/working-in-teams.md b/docs-internal/working-in-teams.md similarity index 100% rename from docs/working-in-teams.md rename to docs-internal/working-in-teams.md diff --git a/mintlify-docs/docs.json b/mintlify-docs/docs.json new file mode 100644 index 000000000..a100f196a --- /dev/null +++ b/mintlify-docs/docs.json @@ -0,0 +1,101 @@ +{ + "$schema": "https://mintlify.com/docs.json", + "theme": "mint", + "name": "GSD", + "logo": { + "light": "/images/logo.svg", + "dark": "/images/logo.svg", + "href": "https://gsd.build" + }, + "favicon": "/images/favicon.svg", + "colors": { + "primary": "#7dcfff", + "light": "#7dcfff", + "dark": "#1a1b26" + }, + "appearance": { + "default": "dark" + }, + "background": { + "decoration": "gradient" + }, + "fonts": { + "heading": { + "family": "JetBrains Mono", + "weight": 700 + }, + "body": { + "family": "Inter", + "weight": 400 + } + }, + "navbar": { + "links": [ + { + "label": "GitHub", + "href": "https://github.com/gsd-build/gsd-2" + } + ], + "primary": { + "type": "button", + "label": "Install", + "href": "/getting-started" + } + }, + "footer": { + "socials": { + "github": "https://github.com/gsd-build/gsd-2" + } + }, + "navigation": { + "groups": [ + { + "group": "Getting started", + "pages": [ + "introduction", + "getting-started" + ] + }, + { + "group": "Core concepts", + "pages": [ + "guides/auto-mode", + "guides/commands", + "guides/git-strategy" + ] + }, + { + "group": "Configuration", + "pages": [ + "guides/configuration", + "guides/custom-models", + "guides/token-optimization", + "guides/dynamic-model-routing", + "guides/cost-management" + ] + }, + { + "group": "Features", + "pages": [ + "guides/captures-triage", + "guides/parallel-orchestration", + "guides/remote-questions", + "guides/skills", + "guides/visualizer", + "guides/web-interface", + "guides/working-in-teams" + ] + }, + { + "group": "Reference", + "pages": [ + "guides/troubleshooting", + "guides/migration" + ] + } + ] + }, + "search": { + "prompt": "Search GSD docs..." + } +} diff --git a/mintlify-docs/getting-started.mdx b/mintlify-docs/getting-started.mdx new file mode 100644 index 000000000..648f92821 --- /dev/null +++ b/mintlify-docs/getting-started.mdx @@ -0,0 +1,183 @@ +--- +title: "Getting started" +description: "Install GSD, configure your LLM provider, and run your first autonomous session." +--- + +## Install + +```bash +npm install -g gsd-pi +``` + +Requires Node.js 22+ and Git. + + +**`command not found: gsd`?** Your shell may not have npm's global bin directory in `$PATH`. Run `npm prefix -g` to find it, then add `$(npm prefix -g)/bin` to your PATH. See [troubleshooting](/guides/troubleshooting) for details. + + +GSD checks for updates every 24 hours. Update in-session with `/gsd update`. + +## First launch + +```bash +gsd +``` + +On first launch, a setup wizard walks you through: + +1. **LLM provider** — 20+ providers (Anthropic, OpenAI, Google, OpenRouter, GitHub Copilot, Amazon Bedrock, Azure, and more). OAuth handles Claude Max and Copilot subscriptions automatically; otherwise paste an API key. +2. **Tool API keys** (optional) — Brave Search, Context7, Jina, Slack, Discord. Press Enter to skip any. + +Re-run the wizard anytime: + +```bash +gsd config +``` + +### Set up API keys + +For non-Anthropic models, you may need a search API key. Run `/gsd config` to set keys globally — they're saved to `~/.gsd/agent/auth.json` and apply to all projects. + +### Set up MCP servers + +To connect GSD to local or external MCP servers, add project-local config in `.mcp.json` or `.gsd/mcp.json`. See [configuration](/guides/configuration) for examples. + +## Choose a model + +GSD auto-selects a default model after login. Switch anytime: + +``` +/model +``` + +Or configure per-phase models in [preferences](/guides/configuration). + +## Two ways to work + + + + Type `/gsd` inside a session. GSD executes one unit at a time, pausing between each with a wizard showing what completed and what's next. + + - **No `.gsd/` directory** → starts a discussion to capture your project vision + - **Milestone exists, no roadmap** → discuss or research the milestone + - **Roadmap exists, slices pending** → plan the next slice or execute a task + - **Mid-task** → resume where you left off + + + Type `/gsd auto` and walk away. GSD autonomously researches, plans, executes, verifies, commits, and advances through every slice until the milestone is complete. + + ``` + /gsd auto + ``` + + See [auto mode](/guides/auto-mode) for the full details. + + + +## Two terminals, one project + +The recommended workflow: auto mode in one terminal, steering from another. + +**Terminal 1 — let it build:** + +```bash +gsd +/gsd auto +``` + +**Terminal 2 — steer while it works:** + +```bash +gsd +/gsd discuss # talk through architecture decisions +/gsd status # check progress +/gsd queue # queue the next milestone +``` + +Both terminals read and write the same `.gsd/` files. Decisions in terminal 2 are picked up at the next phase boundary automatically. + +## Project structure + +GSD organizes work into a hierarchy: + +``` +Milestone → a shippable version (4-10 slices) + Slice → one demoable vertical capability (1-7 tasks) + Task → one context-window-sized unit of work +``` + +All state lives on disk in `.gsd/`: + + +``` +.gsd/ + PROJECT.md — what the project is right now + REQUIREMENTS.md — requirement contract (active/validated/deferred) + DECISIONS.md — append-only architectural decisions + KNOWLEDGE.md — cross-session rules, patterns, and lessons + RUNTIME.md — runtime context: API endpoints, env vars, services + STATE.md — quick-glance status + milestones/ + M001/ + M001-ROADMAP.md — slice plan with risk levels and dependencies + M001-CONTEXT.md — scope and goals from discussion + slices/ + S01/ + S01-PLAN.md — task decomposition + S01-SUMMARY.md — what happened + S01-UAT.md — human test script + tasks/ + T01-PLAN.md + T01-SUMMARY.md +``` + + +## Resume a session + +```bash +gsd --continue # or gsd -c +``` + +Resumes the most recent session. To pick from all saved sessions: + +```bash +gsd sessions +``` + +## VS Code extension + +GSD is also available as a VS Code extension (publisher: FluxLabs). It provides: + +- **`@gsd` chat participant** — talk to the agent in VS Code Chat +- **Sidebar dashboard** — connection status, model info, token usage, quick actions +- **Full command palette** — start/stop agent, switch models, export sessions + +The CLI (`gsd-pi`) must be installed first — the extension connects to it via RPC. + +## Web interface + +```bash +gsd --web +``` + +A browser-based dashboard with real-time progress and multi-project support. See [web interface](/guides/web-interface) for details. + +## Troubleshooting + +### `gsd` runs `git svn dcommit` instead of GSD + +The [oh-my-zsh git plugin](https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/git) defines `alias gsd='git svn dcommit'`. + +**Option 1** — Remove the alias in `~/.zshrc` (after the `source $ZSH/oh-my-zsh.sh` line): + +```bash +unalias gsd 2>/dev/null +``` + +**Option 2** — Use the alternative binary name: + +```bash +gsd-cli +``` + +Both `gsd` and `gsd-cli` point to the same binary. diff --git a/mintlify-docs/guides/auto-mode.mdx b/mintlify-docs/guides/auto-mode.mdx new file mode 100644 index 000000000..0a49f6c9c --- /dev/null +++ b/mintlify-docs/guides/auto-mode.mdx @@ -0,0 +1,181 @@ +--- +title: "Auto mode" +description: "GSD's autonomous execution engine — run /gsd auto, walk away, come back to built software with clean git history." +--- + +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 with pre-loaded context, and lets the LLM execute. When the LLM finishes, auto mode reads disk state again and dispatches the next unit. + +## The loop + +``` +Plan → Execute (per task) → Complete → Reassess Roadmap → Next Slice + ↓ (all slices done) + Validate → Complete Milestone +``` + +- **Plan** — scouts the codebase, researches docs, decomposes the slice into tasks +- **Execute** — runs each task in a fresh context window +- **Complete** — writes summary, UAT script, marks roadmap, commits +- **Reassess** — checks if the roadmap still makes sense +- **Validate** — reconciliation gate after all slices; catches gaps before sealing the milestone + +## Key properties + +### Fresh session per unit + +Every task, research phase, and planning step gets a clean context window. The dispatch prompt includes everything needed — task plans, prior summaries, dependency context, decisions register — so the LLM starts oriented. + +### Context pre-loading + +| Inlined artifact | Purpose | +|------------------|---------| +| Task plan | What to build | +| Slice plan | Where this task fits | +| Prior task summaries | What's already done | +| Dependency summaries | Cross-slice context | +| Roadmap excerpt | Overall direction | +| Decisions register | Architectural context | + +The amount of context inlined is controlled by your [token profile](/guides/token-optimization). Budget mode inlines minimal context; quality mode inlines everything. + +### Git isolation + +GSD isolates milestone work using one of three modes (configured via `git.isolation` in preferences): + +- **`worktree`** (default) — each milestone runs in its own git worktree. Squash-merged to main on completion. +- **`branch`** — work happens on a `milestone/` branch in the project root. Useful for submodule-heavy repos. +- **`none`** — work happens on your current branch. No isolation. For hot-reload workflows. + +See [git strategy](/guides/git-strategy) for details. + +### Crash recovery + +A lock file tracks the current unit. If the session dies, the next `/gsd auto` synthesizes a recovery briefing from tool calls that made it to disk and resumes with full context. + +**Headless auto-restart:** When running `gsd headless auto`, crashes trigger automatic restart with exponential backoff (5s → 10s → 30s cap, default 3 attempts). Combined with crash recovery, this enables overnight "run until done" execution. + +### Provider error recovery + +| Error type | Examples | Action | +|-----------|----------|--------| +| Rate limit | 429, "too many requests" | Auto-resume after retry-after header or 60s | +| Server error | 500, 502, 503, "overloaded" | Auto-resume after 30s | +| Permanent | "unauthorized", "invalid key" | Pause indefinitely (requires manual resume) | + +### Stuck detection + +A sliding-window analysis detects stuck loops — catching cycles like A→B→A→B as well as single-unit repeats. On detection, GSD retries once with a diagnostic prompt. If it fails again, auto mode stops with the exact file it expected. + +### Timeout supervision + +| Timeout | Default | Behavior | +|---------|---------|----------| +| Soft | 20 min | Warns the LLM to wrap up | +| Idle | 10 min | Detects stalls, intervenes | +| Hard | 30 min | Pauses auto mode | + +Configure in preferences: + +```yaml +auto_supervisor: + soft_timeout_minutes: 20 + idle_timeout_minutes: 10 + hard_timeout_minutes: 30 +``` + +### Incremental memory + +GSD maintains a `KNOWLEDGE.md` file — an append-only register of project-specific rules, patterns, and lessons learned. The agent reads it at the start of every unit and appends when discovering recurring issues or non-obvious patterns. + +### Verification enforcement + +```yaml +verification_commands: + - npm run lint + - npm run test +verification_auto_fix: true +verification_max_retries: 2 +``` + +Failures trigger auto-fix retries — the agent sees the output and attempts to fix issues before advancing. + +### HTML reports + +After milestone completion, GSD auto-generates a self-contained HTML report with progress tree, dependency graph, cost/token metrics, execution timeline, and changelog. + +```yaml +auto_report: true # enabled by default +``` + +Generate manually with `/gsd export --html`, or for all milestones with `/gsd export --html --all`. + +### Reactive task execution + +When `reactive_execution: true` is set, GSD derives a dependency graph from IO annotations in task plans. Tasks that don't conflict are dispatched in parallel via subagents. + +```yaml +reactive_execution: true # disabled by default +``` + +## Controlling auto mode + + + + ``` + /gsd auto + ``` + + + Press **Escape**. The conversation is preserved. You can interact with the agent, inspect state, or resume. + + + ``` + /gsd auto + ``` + Auto mode reads disk state and picks up where it left off. + + + ``` + /gsd stop + ``` + Stops auto mode gracefully. Can be run from a different terminal. + + + +### Steer during execution + +``` +/gsd steer +``` + +Hard-steer plan documents without stopping the pipeline. Changes are picked up at the next phase boundary. + +### Capture thoughts + +``` +/gsd capture "add rate limiting to API endpoints" +``` + +Fire-and-forget thought capture. Triaged automatically between tasks. See [captures and triage](/guides/captures-triage). + +## Dashboard + +`Ctrl+Alt+G` or `/gsd status` shows real-time progress: + +- Current milestone, slice, and task +- Auto mode elapsed time and phase +- Per-unit cost and token breakdown +- Cost projections +- Pending capture count + +## Phase skipping + +Token profiles can skip phases to reduce cost: + +| Phase | `budget` | `balanced` | `quality` | +|-------|----------|------------|-----------| +| Milestone research | Skipped | Runs | Runs | +| Slice research | Skipped | Skipped | Runs | +| Reassess roadmap | Skipped | Runs | Runs | + +See [token optimization](/guides/token-optimization) for details. diff --git a/mintlify-docs/guides/captures-triage.mdx b/mintlify-docs/guides/captures-triage.mdx new file mode 100644 index 000000000..9ac838640 --- /dev/null +++ b/mintlify-docs/guides/captures-triage.mdx @@ -0,0 +1,75 @@ +--- +title: "Captures and triage" +description: "Fire-and-forget thought capture during auto-mode with automated triage." +--- + +Captures let you fire-and-forget thoughts during auto-mode execution. Instead of pausing to steer, capture ideas, bugs, or scope changes and let GSD triage them at natural seams between tasks. + +## Quick start + +While auto-mode is running (or any time): + +``` +/gsd capture "add rate limiting to the API endpoints" +/gsd capture "the auth flow should support OAuth, not just JWT" +``` + +Captures are appended to `.gsd/CAPTURES.md` and triaged automatically between tasks. + +## How it works + +``` +capture → triage → confirm → resolve → resume +``` + + + + `/gsd capture "thought"` appends to `.gsd/CAPTURES.md` with a timestamp and unique ID. + + + At natural seams between tasks, GSD classifies each capture. + + + You're shown the proposed resolution. Plan-modifying resolutions require confirmation. + + + The resolution is applied (task injection, replan trigger, deferral, etc.). + + + Auto-mode continues. + + + +## Classification types + +| Type | Meaning | Resolution | +|------|---------|------------| +| `quick-task` | Small, self-contained fix | Inline quick task executed immediately | +| `inject` | New task needed in current slice | Task injected into the active slice plan | +| `defer` | Important but not urgent | Deferred to roadmap reassessment | +| `replan` | Changes the current approach | Triggers slice replan with capture context | +| `note` | Informational, no action | Acknowledged, no plan changes | + +## Manual triage + +Trigger triage at any time: + +``` +/gsd triage +``` + +Useful when you've accumulated several captures and want to process them before the next natural seam. + +## Dashboard integration + +The progress widget shows a pending capture count badge when captures are waiting for triage. Visible in both the `Ctrl+Alt+G` dashboard and the auto-mode widget. + +## Context injection + +Capture context is automatically injected into: +- **Replan-slice prompts** — so the replan knows what triggered it +- **Reassess-roadmap prompts** — so deferred captures influence roadmap decisions + +## Worktree awareness + +Captures resolve to the **original project root's** `.gsd/CAPTURES.md`, not the worktree's local copy. Captures from a steering terminal are visible to the auto-mode session running in a worktree. diff --git a/mintlify-docs/guides/commands.mdx b/mintlify-docs/guides/commands.mdx new file mode 100644 index 000000000..20122c3d9 --- /dev/null +++ b/mintlify-docs/guides/commands.mdx @@ -0,0 +1,180 @@ +--- +title: "Commands reference" +description: "Every GSD command, keyboard shortcut, and CLI flag." +--- + +## Session commands + +| Command | Description | +|---------|-------------| +| `/gsd` | Step mode — execute one unit at a time, pause between each | +| `/gsd next` | Explicit step mode (same as `/gsd`) | +| `/gsd auto` | Autonomous mode — research, plan, execute, commit, repeat | +| `/gsd quick` | Execute a quick task with GSD guarantees without full planning overhead | +| `/gsd stop` | Stop auto mode gracefully | +| `/gsd pause` | Pause auto mode (preserves state, `/gsd auto` to resume) | +| `/gsd steer` | Hard-steer plan documents during execution | +| `/gsd discuss` | Discuss architecture and decisions (works alongside auto mode) | +| `/gsd status` | Progress dashboard | +| `/gsd widget` | Cycle dashboard widget: full / small / min / off | +| `/gsd queue` | Queue and reorder future milestones (safe during auto mode) | +| `/gsd capture` | Fire-and-forget thought capture (works during auto mode) | +| `/gsd triage` | Manually trigger triage of pending captures | +| `/gsd dispatch` | Dispatch a specific phase directly | +| `/gsd history` | View execution history (supports `--cost`, `--phase`, `--model` filters) | +| `/gsd forensics` | Full-access debugger for auto-mode failures | +| `/gsd cleanup` | Clean up GSD state files and stale worktrees | +| `/gsd visualize` | Open workflow visualizer | +| `/gsd export --html` | Generate self-contained HTML report | +| `/gsd export --html --all` | Generate reports for all milestones | +| `/gsd update` | Update GSD to the latest version in-session | +| `/gsd knowledge` | Add persistent project knowledge | +| `/gsd fast` | Toggle service tier for supported models | +| `/gsd rate` | Rate last unit's model tier (over/ok/under) | +| `/gsd changelog` | Show categorized release notes | +| `/gsd logs` | Browse activity logs, debug logs, and metrics | +| `/gsd remote` | Control remote auto-mode | +| `/gsd help` | Categorized command reference | + +## Configuration and diagnostics + +| Command | Description | +|---------|-------------| +| `/gsd prefs` | Model selection, timeouts, budget ceiling | +| `/gsd mode` | Switch workflow mode (solo/team) | +| `/gsd config` | Re-run the provider setup wizard | +| `/gsd keys` | API key manager — list, add, remove, test, rotate | +| `/gsd doctor` | Runtime health checks with auto-fix | +| `/gsd inspect` | Show SQLite DB diagnostics | +| `/gsd init` | Project init wizard | +| `/gsd setup` | Global setup status and configuration | +| `/gsd skill-health` | Skill lifecycle dashboard | +| `/gsd hooks` | Show configured post-unit and pre-dispatch hooks | +| `/gsd run-hook` | Manually trigger a specific hook | +| `/gsd migrate` | Migrate a v1 `.planning` directory to `.gsd` format | + +## Milestone management + +| Command | Description | +|---------|-------------| +| `/gsd new-milestone` | Create a new milestone | +| `/gsd skip` | Prevent a unit from auto-mode dispatch | +| `/gsd undo` | Revert last completed unit | +| `/gsd undo-task` | Reset a specific task's completion state | +| `/gsd reset-slice` | Reset a slice and all its tasks | +| `/gsd park` | Park a milestone — skip without deleting | +| `/gsd unpark` | Reactivate a parked milestone | + +## Parallel orchestration + +| Command | Description | +|---------|-------------| +| `/gsd parallel start` | Analyze eligibility, confirm, and start workers | +| `/gsd parallel status` | Show all workers with state, progress, and cost | +| `/gsd parallel stop [MID]` | Stop all workers or a specific one | +| `/gsd parallel pause [MID]` | Pause all or a specific worker | +| `/gsd parallel resume [MID]` | Resume paused workers | +| `/gsd parallel merge [MID]` | Merge completed milestones to main | + +## Workflow templates + +| Command | Description | +|---------|-------------| +| `/gsd start` | Start a workflow template (bugfix, spike, feature, hotfix, refactor, etc.) | +| `/gsd start resume` | Resume an in-progress workflow | +| `/gsd templates` | List available workflow templates | +| `/gsd templates info ` | Show detailed template info | + +## Custom workflows + +| Command | Description | +|---------|-------------| +| `/gsd workflow new` | Create a new workflow definition | +| `/gsd workflow run ` | Create a run and start auto-mode | +| `/gsd workflow list` | List workflow runs | +| `/gsd workflow validate ` | Validate a workflow definition | +| `/gsd workflow pause` | Pause custom workflow auto-mode | +| `/gsd workflow resume` | Resume paused custom workflow auto-mode | + +## Extensions + +| Command | Description | +|---------|-------------| +| `/gsd extensions list` | List all extensions and their status | +| `/gsd extensions enable ` | Enable a disabled extension | +| `/gsd extensions disable ` | Disable an extension | +| `/gsd extensions info ` | Show extension details | + +## Keyboard shortcuts + +| Shortcut | Action | +|----------|--------| +| `Ctrl+Alt+G` | Toggle dashboard overlay | +| `Ctrl+Alt+V` | Toggle voice transcription | +| `Ctrl+Alt+B` | Show background shell processes | +| `Ctrl+V` / `Alt+V` | Paste image from clipboard | +| `Escape` | Pause auto mode | + + +In terminals without Kitty keyboard protocol support (macOS Terminal.app, JetBrains IDEs), slash-command fallbacks are shown instead of `Ctrl+Alt` shortcuts. + + +## CLI flags + +| Flag | Description | +|------|-------------| +| `gsd` | Start a new interactive session | +| `gsd --continue` (`-c`) | Resume the most recent session | +| `gsd --model ` | Override the default model | +| `gsd --print "msg"` (`-p`) | Single-shot prompt mode (no TUI) | +| `gsd --mode ` | Output mode for non-interactive use | +| `gsd --list-models [search]` | List available models and exit | +| `gsd --web [path]` | Start browser-based web interface | +| `gsd --worktree` (`-w`) `[name]` | Start session in a git worktree | +| `gsd --no-session` | Disable session persistence | +| `gsd --extension ` | Load an additional extension | +| `gsd --version` (`-v`) | Print version and exit | +| `gsd sessions` | Interactive session picker | +| `gsd config` | Set up global API keys | +| `gsd update` | Update GSD to the latest version | + +## Headless mode + +`gsd headless` runs commands without a TUI — designed for CI, cron jobs, and scripted automation. + +```bash +gsd headless # run auto mode +gsd headless next # run a single unit +gsd headless query # instant JSON snapshot (~50ms, no LLM) +gsd headless --timeout 600000 auto # with timeout +gsd headless new-milestone --context brief.md --auto +``` + +| Flag | Description | +|------|-------------| +| `--timeout N` | Overall timeout in milliseconds (default: 300000) | +| `--max-restarts N` | Auto-restart on crash (default: 3, set 0 to disable) | +| `--json` | Stream events as JSONL to stdout | +| `--model ID` | Override the model | +| `--context ` | Context file for `new-milestone` (use `-` for stdin) | +| `--auto` | Chain into auto-mode after milestone creation | + +**Exit codes:** `0` = complete, `1` = error/timeout, `2` = blocked. + +### `gsd headless query` + +Returns a JSON snapshot of the project state — no LLM session, instant response. + +```bash +gsd headless query | jq '.state.phase' # "executing" +gsd headless query | jq '.next' # next dispatch action +gsd headless query | jq '.cost.total' # total spend +``` + +## MCP server mode + +```bash +gsd --mode mcp +``` + +Runs GSD as a Model Context Protocol server over stdin/stdout, exposing all tools to external AI clients (Claude Desktop, VS Code Copilot, etc.). diff --git a/mintlify-docs/guides/configuration.mdx b/mintlify-docs/guides/configuration.mdx new file mode 100644 index 000000000..dfa920d47 --- /dev/null +++ b/mintlify-docs/guides/configuration.mdx @@ -0,0 +1,306 @@ +--- +title: "Configuration" +description: "Preferences, model selection, MCP servers, hooks, and all settings." +--- + +GSD preferences live in `~/.gsd/preferences.md` (global) or `.gsd/preferences.md` (project-local). Manage interactively with `/gsd prefs`. + +## Preferences commands + +| Command | Description | +|---------|-------------| +| `/gsd prefs` | Open the global preferences wizard | +| `/gsd prefs global` | Global preferences wizard | +| `/gsd prefs project` | Project preferences wizard | +| `/gsd prefs status` | Show current files, merged values, and skill status | + +## Preferences file format + +Preferences use YAML frontmatter in a markdown file: + +```yaml +--- +version: 1 +models: + research: claude-sonnet-4-6 + planning: claude-opus-4-6 + execution: claude-sonnet-4-6 + completion: claude-sonnet-4-6 +skill_discovery: suggest +auto_supervisor: + soft_timeout_minutes: 20 + idle_timeout_minutes: 10 + hard_timeout_minutes: 30 +budget_ceiling: 50.00 +token_profile: balanced +--- +``` + +## Global vs project preferences + +| Scope | Path | Applies to | +|-------|------|-----------| +| Global | `~/.gsd/preferences.md` | All projects | +| Project | `.gsd/preferences.md` | Current project only | + +**Merge behavior:** +- **Scalar fields** — project wins if defined +- **Array fields** — concatenated (global first, then project) +- **Object fields** — shallow-merged, project overrides per-key + +## Global API keys + +Tool API keys are stored globally in `~/.gsd/agent/auth.json`. Set them once with `/gsd config`. + +| Tool | Environment variable | Purpose | +|------|---------------------|---------| +| Tavily Search | `TAVILY_API_KEY` | Web search for non-Anthropic models | +| Brave Search | `BRAVE_API_KEY` | Web search for non-Anthropic models | +| Context7 Docs | `CONTEXT7_API_KEY` | Library documentation lookup | + +Anthropic models have built-in web search — no extra keys needed. + +## MCP servers + +GSD connects to external MCP servers configured in project files: + +- `.mcp.json` — repo-shared config +- `.gsd/mcp.json` — local-only config + + + + ```json + { + "mcpServers": { + "my-server": { + "type": "stdio", + "command": "/absolute/path/to/python3", + "args": ["/absolute/path/to/server.py"], + "env": { + "API_URL": "http://localhost:8000" + } + } + } + } + ``` + + + ```json + { + "mcpServers": { + "my-http-server": { + "url": "http://localhost:8080/mcp" + } + } + } + ``` + + + +Verify from a GSD session: `mcp_servers` → `mcp_discover` → `mcp_call`. + +## Models + +Per-phase model selection: + +```yaml +models: + research: claude-sonnet-4-6 + planning: + model: claude-opus-4-6 + fallbacks: + - openrouter/z-ai/glm-5 + execution: claude-sonnet-4-6 + execution_simple: claude-haiku-4-5-20250414 + completion: claude-sonnet-4-6 + subagent: claude-sonnet-4-6 +``` + +**Phases:** `research`, `planning`, `execution`, `execution_simple`, `completion`, `subagent` + +When a model fails to switch, GSD automatically tries the next model in the `fallbacks` list. + +For custom providers (Ollama, vLLM, LM Studio), see [custom models](/guides/custom-models). + +## All settings + +### `token_profile` + +Coordinates model selection, phase skipping, and context compression. Values: `budget`, `balanced` (default), `quality`. See [token optimization](/guides/token-optimization). + +### `budget_ceiling` + +Maximum USD spend during auto mode: + +```yaml +budget_ceiling: 50.00 +budget_enforcement: pause # warn, pause (default), or halt +``` + +### `auto_supervisor` + +Timeout thresholds: + +```yaml +auto_supervisor: + soft_timeout_minutes: 20 + idle_timeout_minutes: 10 + hard_timeout_minutes: 30 +``` + +### `skill_discovery` + +| Value | Behavior | +|-------|----------| +| `auto` | Skills found and applied automatically | +| `suggest` | Skills identified but not auto-installed (default) | +| `off` | Disabled | + +### Verification + +```yaml +verification_commands: + - npm run lint + - npm run test +verification_auto_fix: true +verification_max_retries: 2 +``` + +### Git + +See [git strategy](/guides/git-strategy) for full git configuration. + +### Notifications + +```yaml +notifications: + enabled: true + on_complete: true + on_error: true + on_budget: true + on_milestone: true + on_attention: true +``` + +### Post-unit hooks + +```yaml +post_unit_hooks: + - name: code-review + after: [execute-task] + prompt: "Review the code changes for quality and security." + model: claude-opus-4-6 + max_cycles: 1 + artifact: REVIEW.md +``` + +### Pre-dispatch hooks + +```yaml +pre_dispatch_hooks: + - name: add-standards + before: [execute-task] + action: modify # modify, skip, or replace + prepend: "Follow our coding standards." +``` + +### Skill routing + +```yaml +always_use_skills: + - debug-like-expert +prefer_skills: + - frontend-design +skill_rules: + - when: task involves authentication + use: [clerk] +``` + +### Custom instructions + +```yaml +custom_instructions: + - "Always use TypeScript strict mode" + - "Prefer functional patterns over classes" +``` + +### Dynamic routing + +See [dynamic model routing](/guides/dynamic-model-routing). + +### Parallel execution + +See [parallel orchestration](/guides/parallel-orchestration). + +## Environment variables + +| Variable | Default | Description | +|----------|---------|-------------| +| `GSD_HOME` | `~/.gsd` | Global GSD directory | +| `GSD_PROJECT_ID` | (auto-hash) | Override project identity hash | +| `GSD_STATE_DIR` | `$GSD_HOME` | Per-project state root | +| `GSD_CODING_AGENT_DIR` | `$GSD_HOME/agent` | Agent directory | + +## Full example + + +```yaml +--- +version: 1 + +models: + research: openrouter/deepseek/deepseek-r1 + planning: + model: claude-opus-4-6 + fallbacks: + - openrouter/z-ai/glm-5 + execution: claude-sonnet-4-6 + execution_simple: claude-haiku-4-5-20250414 + completion: claude-sonnet-4-6 + +token_profile: balanced + +dynamic_routing: + enabled: true + escalate_on_failure: true + budget_pressure: true + +budget_ceiling: 25.00 +budget_enforcement: pause +context_pause_threshold: 80 + +auto_supervisor: + soft_timeout_minutes: 15 + hard_timeout_minutes: 25 + +git: + auto_push: true + merge_strategy: squash + isolation: worktree + commit_docs: true + +skill_discovery: suggest +always_use_skills: + - debug-like-expert +skill_rules: + - when: task involves authentication + use: [clerk] + +notifications: + on_complete: false + on_milestone: true + on_attention: true + +auto_visualize: true +service_tier: priority +forensics_dedup: true +show_token_cost: true + +post_unit_hooks: + - name: code-review + after: [execute-task] + prompt: "Review {sliceId}/{taskId} for quality and security." + artifact: REVIEW.md +--- +``` + diff --git a/mintlify-docs/guides/cost-management.mdx b/mintlify-docs/guides/cost-management.mdx new file mode 100644 index 000000000..52e25e6c8 --- /dev/null +++ b/mintlify-docs/guides/cost-management.mdx @@ -0,0 +1,80 @@ +--- +title: "Cost management" +description: "Budget ceilings, cost tracking, projections, and enforcement modes." +--- + +GSD tracks token usage and cost for every unit of work dispatched during auto mode. This data powers the dashboard, budget enforcement, and cost projections. + +## Cost tracking + +Every unit's metrics are captured automatically: + +- **Token counts** — input, output, cache read, cache write, total +- **Cost** — USD cost per unit +- **Duration** — wall-clock time +- **Tool calls** — number of tool invocations +- **Message counts** — assistant and user messages + +Data is stored in `.gsd/metrics.json` and survives across sessions. + +### Viewing costs + +`Ctrl+Alt+G` or `/gsd status` shows real-time cost breakdown by: + +- Phase (research, planning, execution, completion, reassessment) +- Slice (M001/S01, M001/S02, ...) +- Model (which models consumed the most budget) +- Project totals + +## Budget ceiling + +```yaml +budget_ceiling: 50.00 +``` + +### Enforcement modes + +| Mode | Behavior | +|------|----------| +| `warn` | Log a warning, continue | +| `pause` | Pause auto mode (default when ceiling is set) | +| `halt` | Stop auto mode entirely | + +## Cost projections + +After two or more slices complete, GSD projects the remaining cost: + +``` +Projected remaining: $12.40 ($6.20/slice avg × 2 remaining) +``` + +## Budget pressure and model downgrading + +When approaching the budget ceiling, the [complexity router](/guides/token-optimization) automatically downgrades model assignments: + +| Budget used | Effect | +|------------|--------| +| < 50% | No adjustment | +| 50-75% | Standard tasks → Light | +| 75-90% | More aggressive | +| > 90% | Nearly everything downgrades | + +## Token profiles and cost + +| Profile | Typical savings | How | +|---------|----------------|-----| +| `budget` | 40-60% | Cheaper models, phase skipping, minimal context | +| `balanced` | 10-20% | Default models, skip slice research | +| `quality` | 0% (baseline) | Full models, all phases | + +See [token optimization](/guides/token-optimization) for details. + +## Tips + +- Start with `balanced` and a generous `budget_ceiling` to establish baseline costs +- Check `/gsd status` after a few slices to see per-slice averages +- Switch to `budget` for well-understood, repetitive work +- Use `quality` only for architectural decisions +- Per-phase model selection lets you use Opus for planning while keeping execution on Sonnet +- Enable [dynamic routing](/guides/dynamic-model-routing) for automatic downgrading on simple tasks +- Use `/gsd visualize` → Metrics tab to see where your budget is going diff --git a/mintlify-docs/guides/custom-models.mdx b/mintlify-docs/guides/custom-models.mdx new file mode 100644 index 000000000..02e61ae7d --- /dev/null +++ b/mintlify-docs/guides/custom-models.mdx @@ -0,0 +1,126 @@ +--- +title: "Custom models" +description: "Add custom providers and models (Ollama, vLLM, LM Studio, proxies) via models.json." +--- + +Define custom models and providers in `~/.gsd/agent/models.json`. This lets you add models not in the default registry — self-hosted endpoints, fine-tuned models, proxies, or new provider releases. + +The file reloads each time you open `/model` — no restart needed. + +## Minimal example + +For local models (Ollama, LM Studio, vLLM): + +```json +{ + "providers": { + "ollama": { + "baseUrl": "http://localhost:11434/v1", + "api": "openai-completions", + "apiKey": "ollama", + "models": [ + { "id": "llama3.1:8b" }, + { "id": "qwen2.5-coder:7b" } + ] + } + } +} +``` + +The `apiKey` is required but Ollama ignores it — any value works. + +## Supported APIs + +| API | Description | +|-----|-------------| +| `openai-completions` | OpenAI Chat Completions (most compatible) | +| `openai-responses` | OpenAI Responses API | +| `anthropic-messages` | Anthropic Messages API | +| `google-generative-ai` | Google Generative AI | + +## Provider configuration + +| Field | Description | +|-------|-------------| +| `baseUrl` | API endpoint URL | +| `api` | API type | +| `apiKey` | API key (supports shell commands, env vars, or literals) | +| `headers` | Custom headers | +| `authHeader` | Set `true` to add `Authorization: Bearer` automatically | +| `models` | Array of model configurations | +| `modelOverrides` | Per-model overrides for built-in models | + +### Value resolution + +The `apiKey` and `headers` fields support three formats: + +```json +"apiKey": "!security find-generic-password -ws 'anthropic'" // shell command +"apiKey": "MY_API_KEY" // env variable +"apiKey": "sk-..." // literal value +``` + +## Model configuration + +| Field | Required | Default | Description | +|-------|----------|---------|-------------| +| `id` | Yes | — | Model identifier (passed to the API) | +| `name` | No | `id` | Human-readable label | +| `api` | No | provider's `api` | Override per model | +| `reasoning` | No | `false` | Supports extended thinking | +| `input` | No | `["text"]` | `["text"]` or `["text", "image"]` | +| `contextWindow` | No | `128000` | Context window size | +| `maxTokens` | No | `16384` | Maximum output tokens | +| `cost` | No | all zeros | Per-million tokens: `input`, `output`, `cacheRead`, `cacheWrite` | + +## Overriding built-in providers + +Route a built-in provider through a proxy without redefining models: + +```json +{ + "providers": { + "anthropic": { + "baseUrl": "https://my-proxy.example.com/v1" + } + } +} +``` + +All built-in Anthropic models remain available. To add custom models alongside built-in ones, include the `models` array. + +## OpenAI compatibility + +For providers with partial OpenAI compatibility, use the `compat` field at provider or model level: + +```json +{ + "providers": { + "local-llm": { + "baseUrl": "http://localhost:8080/v1", + "api": "openai-completions", + "compat": { + "supportsDeveloperRole": false, + "supportsReasoningEffort": false + }, + "models": [...] + } + } +} +``` + +| Field | Description | +|-------|-------------| +| `supportsDeveloperRole` | Use `developer` vs `system` role | +| `supportsReasoningEffort` | Support for `reasoning_effort` parameter | +| `supportsUsageInStreaming` | Support for `stream_options: { include_usage: true }` | +| `maxTokensField` | `max_completion_tokens` or `max_tokens` | +| `thinkingFormat` | `reasoning_effort`, `zai`, `qwen`, or `qwen-chat-template` | +| `openRouterRouting` | OpenRouter provider selection config | +| `vercelGatewayRouting` | Vercel AI Gateway provider selection | + +## Community provider extensions + +| Extension | Provider | Models | Install | +|-----------|----------|--------|---------| +| [`pi-dashscope`](https://www.npmjs.com/package/pi-dashscope) | Alibaba DashScope | Qwen3, GLM-5, MiniMax M2.5, Kimi K2.5 | `gsd install npm:pi-dashscope` | diff --git a/mintlify-docs/guides/dynamic-model-routing.mdx b/mintlify-docs/guides/dynamic-model-routing.mdx new file mode 100644 index 000000000..d6cb80ed6 --- /dev/null +++ b/mintlify-docs/guides/dynamic-model-routing.mdx @@ -0,0 +1,94 @@ +--- +title: "Dynamic model routing" +description: "Automatically select cheaper models for simple work and reserve expensive models for complex tasks." +--- + +Dynamic model routing classifies each dispatched unit into a complexity tier and selects an appropriate model. This reduces token consumption by 20-50% without sacrificing quality where it matters. + +The key rule: **downgrade-only semantics**. Your configured model is always the ceiling — routing never upgrades beyond what you've configured. + +## Enabling + +```yaml +dynamic_routing: + enabled: true +``` + +## Complexity tiers + +| Tier | Typical work | Default model level | +|------|-------------|-------------------| +| **Light** | Slice completion, UAT, hooks | Haiku-class | +| **Standard** | Research, planning, execution | Sonnet-class | +| **Heavy** | Replanning, roadmap reassessment | Opus-class | + +## Configuration + +```yaml +dynamic_routing: + enabled: true + tier_models: + light: claude-haiku-4-5 + standard: claude-sonnet-4-6 + heavy: claude-opus-4-6 + escalate_on_failure: true # bump tier on task failure + budget_pressure: true # auto-downgrade near budget ceiling + cross_provider: true # consider models from other providers +``` + +### `escalate_on_failure` + +When a task fails at a given tier, the router escalates: Light → Standard → Heavy. Prevents cheap models from burning retries on work that needs more reasoning. + +### `budget_pressure` + +Progressive downgrading as budget ceiling approaches: + +| Budget used | Effect | +|------------|--------| +| < 50% | No adjustment | +| 50-75% | Standard → Light | +| 75-90% | More aggressive | +| > 90% | Nearly everything → Light | + +### `cross_provider` + +The router may select models from providers other than your primary, using a built-in cost table to find the cheapest model at each tier. + +## Task plan analysis + +For `execute-task` units, the classifier analyzes the task plan: + +| Signal | Simple → Light | Complex → Heavy | +|--------|---------------|----------------| +| Step count | ≤ 3 | ≥ 8 | +| File count | ≤ 3 | ≥ 8 | +| Description length | < 500 chars | > 2000 chars | +| Code blocks | — | ≥ 5 | +| Complexity keywords | None | Present | + +## Adaptive learning + +The routing history (`.gsd/routing-history.json`) tracks success/failure per tier per unit type. If a tier's failure rate exceeds 20%, future classifications are bumped up. + +User feedback (`/gsd rate`) is weighted 2x vs automatic outcomes. + +## Cost table + +| Model | Input (per M) | Output (per M) | +|-------|-------|--------| +| claude-haiku-4-5 | $0.80 | $4.00 | +| claude-sonnet-4-6 | $3.00 | $15.00 | +| claude-opus-4-6 | $15.00 | $75.00 | +| gpt-4o-mini | $0.15 | $0.60 | +| gpt-4o | $2.50 | $10.00 | +| gemini-2.0-flash | $0.10 | $0.40 | + +The cost table is for comparison only — actual billing comes from your provider. + +## Interaction with token profiles + +- **Token profiles** control phase skipping and context compression +- **Dynamic routing** controls per-unit model selection within those constraints + +The `budget` profile + dynamic routing provides maximum cost savings. diff --git a/mintlify-docs/guides/git-strategy.mdx b/mintlify-docs/guides/git-strategy.mdx new file mode 100644 index 000000000..6ce804ec1 --- /dev/null +++ b/mintlify-docs/guides/git-strategy.mdx @@ -0,0 +1,150 @@ +--- +title: "Git strategy" +description: "Isolation modes, branching model, and merge behavior for milestone work." +--- + +GSD uses git for milestone isolation and sequential commits. You choose an **isolation mode** that controls where work happens. The strategy is fully automated — no manual branch management needed. + +## Isolation modes + +Configure via the `git.isolation` preference: + +| Mode | Working directory | Branch | Best for | +|------|-------------------|--------|----------| +| `worktree` (default) | `.gsd/worktrees//` | `milestone/` | Most projects — full file isolation | +| `branch` | Project root | `milestone/` | Submodule-heavy repos | +| `none` | Project root | Current branch | Hot-reload workflows | + +### `worktree` mode (default) + +Each milestone gets its own git worktree on a `milestone/` branch. All execution happens inside the worktree. On completion, the worktree is squash-merged to main as one clean commit. The worktree and branch are cleaned up. + +### `branch` mode + +Work happens in the project root on a `milestone/` branch. No worktree is created. On completion, the branch is merged to main. + +### `none` mode + +Work happens directly on your current branch. No worktree, no milestone branch. GSD still commits sequentially with conventional commit messages, but there's no branch isolation. + +## Branching model + +``` +main ───────────────────────────────────────────────────────── + │ ↑ + └── milestone/M001 (worktree) ────────────────────────┘ + commit: feat(S01/T01): core types + commit: feat(S01/T02): markdown parser + commit: feat(S01/T03): file writer + → squash-merged to main as single commit +``` + +### Parallel worktrees + +With [parallel orchestration](/guides/parallel-orchestration) enabled, multiple milestones run in separate worktrees simultaneously: + +``` +main ────────────────────────────────────────────────────────── + │ ↑ ↑ + ├── milestone/M002 (worktree) ─────────┘ │ + │ → squash-merged first │ + │ │ + └── milestone/M003 (worktree) ────────────────────────┘ + → squash-merged second +``` + +Merges happen sequentially to avoid conflicts. + +### Commit format + +Conventional commit format with scope: + +``` +feat(S01/T01): core type definitions +feat(S01/T02): markdown parser for plan files +fix(M001/S03): bug fixes and doc corrections +docs(M001/S04): workflow documentation +``` + +## Workflow modes + +Set `mode` to get sensible defaults: + +```yaml +mode: solo # personal projects +mode: team # shared repos +``` + +| Setting | `solo` | `team` | +|---|---|---| +| `git.auto_push` | `true` | `false` | +| `git.push_branches` | `false` | `true` | +| `git.pre_merge_check` | `false` | `true` | +| `git.merge_strategy` | `"squash"` | `"squash"` | +| `unique_milestone_ids` | `false` | `true` | + +Mode defaults are the lowest priority — any explicit preference overrides them. + +## Git preferences + +```yaml +git: + auto_push: false + push_branches: false + remote: origin + snapshots: false + pre_merge_check: false + commit_type: feat + main_branch: main + merge_strategy: squash # "squash" or "merge" + isolation: worktree # "worktree", "branch", or "none" + commit_docs: true + auto_pr: false + pr_target_branch: develop +``` + +### Automatic pull requests + +For teams using Gitflow or branch-based workflows: + +```yaml +git: + auto_push: true + auto_pr: true + pr_target_branch: develop +``` + +Pushes the milestone branch and creates a PR targeting your specified branch. Requires `gh` CLI installed and authenticated. + +### `commit_docs: false` + +Adds `.gsd/` to `.gitignore` and keeps all planning artifacts local-only. Useful for teams where only some members use GSD. + +## Worktree management + +### Automatic (auto mode) + +1. Milestone starts → worktree created at `.gsd/worktrees//` +2. Planning artifacts copied into the worktree +3. All execution happens inside the worktree +4. Milestone completes → squash-merged to main +5. Worktree and branch cleaned up + +### Manual + +``` +/worktree create +/worktree switch +/worktree merge +/worktree remove +``` + +## Self-healing + +GSD includes automatic recovery for common git issues: + +- **Detached HEAD** — automatically reattaches to the correct branch +- **Stale lock files** — removes `index.lock` files from crashed processes +- **Orphaned worktrees** — detects and offers cleanup + +Run `/gsd doctor` to check git health manually. diff --git a/mintlify-docs/guides/migration.mdx b/mintlify-docs/guides/migration.mdx new file mode 100644 index 000000000..8f4646d79 --- /dev/null +++ b/mintlify-docs/guides/migration.mdx @@ -0,0 +1,47 @@ +--- +title: "Migration from v1" +description: "Migrate .planning directories from the original GSD to GSD-2's .gsd format." +--- + +If you have projects with `.planning` directories from the original Get Shit Done (v1), you can migrate them to GSD-2's `.gsd` format. + +## Running the migration + +```bash +# From within the project directory +/gsd migrate + +# Or specify a path +/gsd migrate ~/projects/my-old-project +``` + +## What gets migrated + +The migration tool: + +- Parses `PROJECT.md`, `ROADMAP.md`, `REQUIREMENTS.md`, phase directories, plans, summaries, and research +- Maps phases → slices, plans → tasks, milestones → milestones +- Preserves completion state (`[x]` phases stay done, summaries carry over) +- Consolidates research files +- Shows a preview before writing anything +- Optionally runs an agent-driven review of the output + +## Supported formats + +The migration handles various v1 format variations: + +- Milestone-sectioned roadmaps with `
` blocks +- Bold phase entries +- Bullet-format requirements +- Decimal phase numbering +- Duplicate phase numbers across milestones + +## Post-migration + +Verify the output: + +``` +/gsd doctor +``` + +This checks `.gsd/` integrity and flags any structural issues. diff --git a/mintlify-docs/guides/parallel-orchestration.mdx b/mintlify-docs/guides/parallel-orchestration.mdx new file mode 100644 index 000000000..830f0d10e --- /dev/null +++ b/mintlify-docs/guides/parallel-orchestration.mdx @@ -0,0 +1,123 @@ +--- +title: "Parallel orchestration" +description: "Run multiple milestones simultaneously in isolated git worktrees." +--- + +Run multiple milestones simultaneously. Each gets its own worker process, branch, and context window — while a coordinator tracks progress, enforces budgets, and keeps everything in sync. + + +Parallel mode is behind `parallel.enabled: false` by default. Opt-in only. + + +## Quick start + +1. Enable in preferences: + +```yaml +parallel: + enabled: true + max_workers: 2 +``` + +2. Start parallel execution: + +``` +/gsd parallel start +``` + +3. Monitor progress: + +``` +/gsd parallel status +``` + +## Architecture + +``` +┌─────────────────────────────────────────────────────┐ +│ Coordinator (your GSD session) │ +│ │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │ Worker 1 │ │ Worker 2 │ │ Worker 3 │ ... │ +│ │ M001 │ │ M003 │ │ M005 │ │ +│ └──────────┘ └──────────┘ └──────────┘ │ +│ │ │ │ │ +│ ▼ ▼ ▼ │ +│ .gsd/worktrees/ .gsd/worktrees/ .gsd/worktrees/ │ +└─────────────────────────────────────────────────────┘ +``` + +### Worker isolation + +| Resource | Isolation method | +|----------|-----------------| +| Filesystem | Git worktree — separate checkout | +| Git branch | `milestone/` per milestone | +| State | `GSD_MILESTONE_LOCK` — each worker sees only its milestone | +| Context | Separate process with its own agent sessions | +| Metrics | Each worktree has its own `metrics.json` | + +## Eligibility analysis + +Before starting, GSD checks which milestones can run concurrently: + +1. **Not complete** — finished milestones are skipped +2. **Dependencies satisfied** — all `dependsOn` entries must be complete +3. **File overlap check** — shared files get a warning (not a blocker) + +## Configuration + +```yaml +parallel: + enabled: false + max_workers: 2 + budget_ceiling: 50.00 + merge_strategy: "per-milestone" # or "per-slice" + auto_merge: "confirm" # "auto", "confirm", or "manual" +``` + +| Key | Default | Description | +|-----|---------|-------------| +| `enabled` | `false` | Master toggle | +| `max_workers` | `2` | Concurrent workers (1-4) | +| `budget_ceiling` | none | Aggregate cost limit across all workers | +| `merge_strategy` | `"per-milestone"` | When to merge back to main | +| `auto_merge` | `"confirm"` | How merge-back is handled | + +## Commands + +| Command | Description | +|---------|-------------| +| `/gsd parallel start` | Analyze, confirm, and start workers | +| `/gsd parallel status` | Show workers with state, progress, cost | +| `/gsd parallel stop [MID]` | Stop all or a specific worker | +| `/gsd parallel pause [MID]` | Pause all or a specific worker | +| `/gsd parallel resume [MID]` | Resume paused workers | +| `/gsd parallel merge [MID]` | Merge completed milestones to main | + +## Merge reconciliation + +- `.gsd/` state files — auto-resolved (accept milestone branch version) +- Code conflicts — merge halts, shows conflicting files. Resolve manually and retry. + +## Budget management + +When `budget_ceiling` is set, aggregate cost is tracked across all workers. Ceiling reached → coordinator signals workers to stop. + +## Troubleshooting + +### "No milestones are eligible" + +All milestones are complete or blocked by dependencies. Check `/gsd queue`. + +### Worker crashed + +Workers persist state to disk. On restart, the coordinator detects dead PIDs. Run `/gsd doctor --fix` to clean up, then `/gsd parallel start` to spawn new workers. + +### Merge conflicts + +``` +/gsd parallel merge # see which milestones conflict +# resolve in .gsd/worktrees// +/gsd parallel merge MID # retry +``` diff --git a/mintlify-docs/guides/remote-questions.mdx b/mintlify-docs/guides/remote-questions.mdx new file mode 100644 index 000000000..a21ac9ea8 --- /dev/null +++ b/mintlify-docs/guides/remote-questions.mdx @@ -0,0 +1,84 @@ +--- +title: "Remote questions" +description: "Discord, Slack, and Telegram integration for headless auto-mode." +--- + +Remote questions allow GSD to ask for user input via Slack, Discord, or Telegram when running in headless auto-mode. When GSD encounters a decision point, it posts the question to your configured channel and polls for a response. + +## Setup + + + + ``` + /gsd remote discord + ``` + + The setup wizard validates your bot token, picks a server and channel, sends a test message, and saves the config. + + **Bot requirements:** + - A Discord bot token from the [Developer Portal](https://discord.com/developers/applications) + - Permissions: Send Messages, Read Message History, Add Reactions, View Channel + + + ``` + /gsd remote slack + ``` + + The setup wizard validates your bot token, picks a channel, sends a test message, and saves the config. + + **Bot requirements:** + - A Slack bot token (`xoxb-...`) from [Slack API](https://api.slack.com/apps) + - Scopes: `chat:write`, `reactions:read`, `reactions:write`, `channels:read`, `groups:read`, `channels:history`, `groups:history` + + + ``` + /gsd remote telegram + ``` + + The setup wizard validates your bot token, prompts for a chat ID, sends a test message, and saves the config. + + **Bot requirements:** + - A bot token from [@BotFather](https://t.me/BotFather) + - Bot must be added to the target group chat + + + +## Configuration + +```yaml +remote_questions: + channel: discord + channel_id: "1234567890123456789" + timeout_minutes: 5 + poll_interval_seconds: 5 +``` + +## How it works + +1. GSD encounters a decision point during auto-mode +2. The question is posted to your channel as a rich embed (Discord) or Block Kit message (Slack) +3. GSD polls for a response at the configured interval +4. You respond by reacting with a number emoji or replying with text +5. GSD picks up the response and continues +6. A check reaction confirms receipt + +### Response formats + +**Single question:** React with a number emoji (1️⃣-5️⃣) or reply with a number. + +**Multiple questions:** Reply with semicolons (`1;2;custom text`) or one answer per line. + +### Timeouts + +If no response within `timeout_minutes`, the LLM makes a conservative default choice or pauses auto-mode. + +## Commands + +| Command | Description | +|---------|-------------| +| `/gsd remote` | Show menu and current status | +| `/gsd remote slack` | Set up Slack | +| `/gsd remote discord` | Set up Discord | +| `/gsd remote telegram` | Set up Telegram | +| `/gsd remote status` | Show current config and last prompt status | +| `/gsd remote disconnect` | Remove configuration | diff --git a/mintlify-docs/guides/skills.mdx b/mintlify-docs/guides/skills.mdx new file mode 100644 index 000000000..66a05b096 --- /dev/null +++ b/mintlify-docs/guides/skills.mdx @@ -0,0 +1,97 @@ +--- +title: "Skills" +description: "Specialized instruction sets that provide domain-specific guidance to the LLM." +--- + +Skills are specialized instruction sets that GSD loads when the task matches. They provide domain-specific guidance — coding patterns, framework idioms, testing strategies, and tool usage. + +## Bundled skills + +GSD ships with these skills, installed to `~/.gsd/agent/skills/`: + +| Skill | Trigger | Description | +|-------|---------|-------------| +| `frontend-design` | Web UI work | Production-grade frontend with high design quality | +| `swiftui` | macOS/iOS apps | Full lifecycle from creation to shipping | +| `debug-like-expert` | Complex debugging | Methodical investigation with evidence gathering | +| `rust-core` | Rust code | Idiomatic, safe, performant Rust patterns | +| `axum-web-framework` | Axum web apps | Complete Axum development guide | +| `tauri` | Tauri v2 desktop apps | Cross-platform desktop development | +| `github-workflows` | GitHub Actions | CI/CD, workflow debugging | +| `security-audit` | Security auditing | Dependency scanning, OWASP | +| `review` | Code review | Diff-aware quality analysis | +| `test` | Test generation | Auto-detects frameworks | +| `lint` | Linting and formatting | ESLint, Biome, Prettier | + +## Skill discovery + +The `skill_discovery` preference controls how GSD finds skills: + +| Mode | Behavior | +|------|----------| +| `auto` | Skills found and applied automatically | +| `suggest` | Skills identified but require confirmation (default) | +| `off` | No skill discovery | + +## Skill preferences + +```yaml +always_use_skills: + - debug-like-expert +prefer_skills: + - frontend-design +avoid_skills: + - security-docker +skill_rules: + - when: task involves Clerk authentication + use: [clerk] + - when: frontend styling work + prefer: [frontend-design] +``` + +### Resolution order + +1. **Bare name** — e.g., `frontend-design` → scans `~/.gsd/agent/skills/` and project skills +2. **Absolute path** — e.g., `/Users/you/.gsd/agent/skills/my-skill/SKILL.md` +3. **Directory path** — looks for `SKILL.md` inside + +User skills take precedence over project skills. + +## Custom skills + +Create a directory with a `SKILL.md` file: + +``` +~/.gsd/agent/skills/my-skill/ + SKILL.md — instructions for the LLM + references/ — optional reference files +``` + +### Project-local skills + +``` +.gsd/agent/skills/my-project-skill/ + SKILL.md +``` + +## Skill health dashboard + +``` +/gsd skill-health # overview table +/gsd skill-health rust-core # detailed view +/gsd skill-health --stale 30 # unused for 30+ days +/gsd skill-health --declining # falling success rates +``` + +The dashboard flags: +- Success rate below 70% over the last 10 uses +- Token usage rising 20%+ +- Skills unused beyond the staleness threshold + +### Staleness detection + +```yaml +skill_staleness_days: 60 # default: 60, set 0 to disable +``` + +Stale skills are excluded from automatic matching but remain invokable explicitly. diff --git a/mintlify-docs/guides/token-optimization.mdx b/mintlify-docs/guides/token-optimization.mdx new file mode 100644 index 000000000..ae79bf525 --- /dev/null +++ b/mintlify-docs/guides/token-optimization.mdx @@ -0,0 +1,175 @@ +--- +title: "Token optimization" +description: "Token profiles, context compression, and complexity-based task routing to reduce costs by 40-60%." +--- + +GSD's token optimization system has three pillars: **token profiles**, **context compression**, and **complexity-based task routing**. + +## Token profiles + +A token profile coordinates model selection, phase skipping, and context compression. Set it in preferences: + +```yaml +token_profile: balanced +``` + +### `budget` — maximum savings (40-60% reduction) + +| Dimension | Setting | +|-----------|---------| +| Planning model | Sonnet | +| Execution model | Sonnet | +| Simple task model | Haiku | +| Completion model | Haiku | +| Milestone research | Skipped | +| Slice research | Skipped | +| Reassessment | Skipped | +| Context level | Minimal | + +Best for: prototyping, small projects, well-understood codebases. + +### `balanced` — smart defaults + +| Dimension | Setting | +|-----------|---------| +| All models | User's default | +| Subagent model | Sonnet | +| Milestone research | Runs | +| Slice research | Skipped | +| Reassessment | Runs | +| Context level | Standard | + +Best for: most projects, day-to-day development. + +### `quality` — full context + +Every phase runs. Every context artifact is inlined. No shortcuts. Best for: complex architectures, greenfield projects, critical production work. + +## Context compression + +Each profile maps to an **inline level** controlling how much context is pre-loaded into dispatch prompts: + +| Profile | Level | What's included | +|---------|-------|-----------------| +| `budget` | Minimal | Task plan, essential prior summaries (truncated). Drops decisions, requirements, templates. | +| `balanced` | Standard | Task plan, prior summaries, slice plan, roadmap excerpt. | +| `quality` | Full | Everything — all plans, summaries, decisions, requirements, templates. | + +### Prompt compression + +GSD can apply deterministic text compression before falling back to section-boundary truncation: + +```yaml +compression_strategy: compress # or "truncate" +``` + +| Strategy | Behavior | Default for | +|----------|----------|------------| +| `truncate` | Drop entire sections at boundaries | `quality` | +| `compress` | Heuristic text compression first, then truncate | `budget`, `balanced` | + +### Context selection + +```yaml +context_selection: smart # or "full" +``` + +| Mode | Behavior | Default for | +|------|----------|------------| +| `full` | Inline entire files | `balanced`, `quality` | +| `smart` | TF-IDF semantic chunking for large files | `budget` | + +## Complexity-based task routing + +GSD classifies each task by complexity and routes it to an appropriate model tier. + + +Dynamic routing requires explicit `models` in your preferences. Without a `models` section, routing is skipped. + + +### Classification signals + +| Signal | Simple | Standard | Complex | +|--------|--------|----------|---------| +| Step count | ≤ 3 | 4-7 | ≥ 8 | +| File count | ≤ 3 | 4-7 | ≥ 8 | +| Description length | < 500 chars | 500-2000 | > 2000 chars | +| Code blocks | — | — | ≥ 5 | +| Complexity keywords | None | Any present | — | + +**Complexity keywords:** `research`, `investigate`, `refactor`, `migrate`, `integrate`, `complex`, `architect`, `redesign`, `security`, `performance`, `concurrent`, `parallel` + +### Budget pressure + +When approaching the budget ceiling, the classifier automatically downgrades tiers: + +| Budget used | Effect | +|------------|--------| +| < 50% | No adjustment | +| 50-75% | Standard → Light | +| 75-90% | More aggressive | +| > 90% | Everything except Heavy → Light | + +## Adaptive learning + +GSD tracks success/failure per tier and adjusts classifications over time. User feedback via `/gsd rate` is weighted 2x: + +``` +/gsd rate over # model was overpowered +/gsd rate ok # appropriate +/gsd rate under # too weak +``` + +## Configuration examples + + + + ```yaml + --- + version: 1 + token_profile: budget + budget_ceiling: 25.00 + models: + execution_simple: claude-haiku-4-5-20250414 + --- + ``` + + + ```yaml + --- + version: 1 + token_profile: balanced + models: + planning: + model: claude-opus-4-6 + fallbacks: + - openrouter/z-ai/glm-5 + execution: claude-sonnet-4-6 + --- + ``` + + + ```yaml + --- + version: 1 + token_profile: quality + models: + planning: claude-opus-4-6 + execution: claude-opus-4-6 + --- + ``` + + + +Per-phase overrides always win over profile defaults: + +```yaml +--- +version: 1 +token_profile: budget +phases: + skip_research: false # keep research despite budget profile +models: + planning: claude-opus-4-6 # use Opus for planning despite budget +--- +``` diff --git a/mintlify-docs/guides/troubleshooting.mdx b/mintlify-docs/guides/troubleshooting.mdx new file mode 100644 index 000000000..7904981a7 --- /dev/null +++ b/mintlify-docs/guides/troubleshooting.mdx @@ -0,0 +1,140 @@ +--- +title: "Troubleshooting" +description: "Common issues, /gsd doctor, /gsd forensics, and recovery procedures." +--- + +## `/gsd doctor` + +The built-in diagnostic tool validates `.gsd/` integrity: + +``` +/gsd doctor +``` + +It checks file structure, referential integrity, completion state consistency, git worktree health, and stale lock files. + +## Common issues + + + + **Cause:** Stale cache after a crash, or the LLM didn't produce the expected artifact. + + **Fix:** Run `/gsd doctor` to repair state, then `/gsd auto`. + + + + **Cause:** A unit failed to produce its expected artifact twice in a row. + + **Fix:** Check the task plan for clarity. Refine it manually, then `/gsd auto`. + + + + **Cause:** npm's global bin directory isn't in `$PATH`. + + **Fix:** + ```bash + npm prefix -g + echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc + source ~/.zshrc + ``` + + **Workaround:** `npx gsd-pi` or `$(npm prefix -g)/bin/gsd` + + + + | Error type | Auto-resume? | Delay | + |-----------|-------------|-------| + | Rate limit (429) | Yes | retry-after or 60s | + | Server error (500, 502, 503) | Yes | 30s | + | Auth/billing | No | Manual resume | + + For transient errors, configure fallback models: + ```yaml + models: + execution: + model: claude-sonnet-4-6 + fallbacks: + - openrouter/minimax/minimax-m2.5 + ``` + + + + Increase `budget_ceiling` in preferences, or switch to `budget` token profile. Resume with `/gsd auto`. + + + + GSD auto-detects stale locks. If automatic recovery fails: + ```bash + rm -f .gsd/auto.lock + rm -rf "$(dirname .gsd)/.gsd.lock" + ``` + + + + GSD auto-resolves conflicts on `.gsd/` runtime files. For code conflicts, the LLM attempts resolution. If that fails, resolve manually. + + + + **Cause:** Antivirus, indexers, or editors briefly locking files during atomic rename. + + **Fix:** Re-run the operation. Close tools holding files open if the error persists. Run `/gsd doctor` to verify repo health. + + + +## `/gsd forensics` + +Full-access debugger for post-mortem analysis: + +``` +/gsd forensics [optional problem description] +``` + +Provides anomaly detection, unit traces, metrics analysis, doctor integration, and LLM-guided investigation. + +## MCP client issues + + + + Verify `.mcp.json` or `.gsd/mcp.json` exists and parses as valid JSON. + + + + Run the configured command outside GSD to confirm the server starts. Check backend URLs and dependencies. + + + + Use absolute paths. Set required environment variables in the MCP config's `env` block. + + + +## Recovery procedures + +### Reset auto mode state + +```bash +rm .gsd/auto.lock +rm .gsd/completed-units.json +``` + +Then `/gsd auto` to restart from current disk state. + +### Reset routing history + +```bash +rm .gsd/routing-history.json +``` + +### Full state rebuild + +``` +/gsd doctor +``` + +Rebuilds `STATE.md` from plan and roadmap files on disk. + +## Getting help + +- **GitHub Issues:** [github.com/gsd-build/GSD-2/issues](https://github.com/gsd-build/gsd-2/issues) +- **Dashboard:** `Ctrl+Alt+G` or `/gsd status` +- **Forensics:** `/gsd forensics` +- **Session logs:** `.gsd/activity/` diff --git a/mintlify-docs/guides/visualizer.mdx b/mintlify-docs/guides/visualizer.mdx new file mode 100644 index 000000000..5ea199621 --- /dev/null +++ b/mintlify-docs/guides/visualizer.mdx @@ -0,0 +1,82 @@ +--- +title: "Workflow visualizer" +description: "Interactive TUI overlay for progress, dependencies, metrics, and timeline." +--- + +The workflow visualizer is a full-screen TUI overlay with four tabs showing project progress, dependencies, cost metrics, and execution timeline. + +## Opening + +``` +/gsd visualize +``` + +Or configure automatic display after milestone completion: + +```yaml +auto_visualize: true +``` + +## Tabs + +Switch tabs with `Tab`, `1`-`4`, or arrow keys. + +### 1. Progress + +A tree view of milestones, slices, and tasks with completion status: + +``` +M001: User Management 3/6 tasks ⏳ + ✅ S01: Auth module 3/3 tasks + ✅ T01: Core types + ✅ T02: JWT middleware + ✅ T03: Login flow + ⏳ S02: User dashboard 1/2 tasks + ✅ T01: Layout component + ⬜ T02: Profile page +``` + +### 2. Dependencies + +ASCII dependency graph showing slice relationships: + +``` +S01 ──→ S02 ──→ S04 + └───→ S03 ──↗ +``` + +### 3. Metrics + +Bar charts showing cost and token usage by phase, slice, and model. + +### 4. Timeline + +Chronological execution history with unit type, timestamps, duration, model, and token counts. + +## Controls + +| Key | Action | +|-----|--------| +| `Tab` | Next tab | +| `Shift+Tab` | Previous tab | +| `1`-`4` | Jump to tab | +| `↑`/`↓` | Scroll | +| `Escape` / `q` | Close | + +The visualizer refreshes from disk every 2 seconds, staying current alongside a running auto-mode session. + +## HTML export + +For shareable reports outside the terminal: + +``` +/gsd export --html +``` + +Generates a self-contained HTML file in `.gsd/reports/` with progress tree, dependency graph (SVG), cost/token charts, execution timeline, and changelog. All CSS and JS are inlined — printable to PDF from any browser. + +```yaml +auto_report: true # auto-generate after milestone completion (default) +``` + +An auto-generated `index.html` shows all reports with progression metrics across milestones. diff --git a/mintlify-docs/guides/web-interface.mdx b/mintlify-docs/guides/web-interface.mdx new file mode 100644 index 000000000..75f769c86 --- /dev/null +++ b/mintlify-docs/guides/web-interface.mdx @@ -0,0 +1,38 @@ +--- +title: "Web interface" +description: "Browser-based project management with real-time progress and multi-project support." +--- + +GSD includes a browser-based web interface for project management, real-time progress monitoring, and multi-project support. + +## Quick start + +```bash +gsd --web +``` + +### CLI flags + +```bash +gsd --web --host 0.0.0.0 --port 8080 --allowed-origins "https://example.com" +``` + +| Flag | Default | Description | +|------|---------|-------------| +| `--host` | `localhost` | Bind address | +| `--port` | `3000` | Port | +| `--allowed-origins` | (none) | Comma-separated CORS origins | + +## Features + +- **Project management** — view milestones, slices, and tasks in a visual dashboard +- **Real-time progress** — server-sent events push status updates during auto-mode +- **Multi-project support** — manage multiple projects from a single tab via `?project=` URL parameter +- **Change project root** — switch directories from the web UI without restarting +- **Onboarding flow** — API key setup and provider configuration through the browser +- **Model selection** — switch models and providers from the web UI + +## Platform notes + +- **macOS/Linux** — full support +- **Windows** — web build is skipped due to Next.js webpack issues. The CLI remains fully functional. diff --git a/mintlify-docs/guides/working-in-teams.mdx b/mintlify-docs/guides/working-in-teams.mdx new file mode 100644 index 000000000..17f6f0c1d --- /dev/null +++ b/mintlify-docs/guides/working-in-teams.mdx @@ -0,0 +1,72 @@ +--- +title: "Working in teams" +description: "Multi-user workflows with unique milestone IDs, push branches, and shared planning artifacts." +--- + +GSD supports multi-user workflows where several developers work on the same repository concurrently. + +## Setup + +### 1. Set team mode + +```yaml +# .gsd/preferences.md (project-level, committed to git) +--- +version: 1 +mode: team +--- +``` + +This enables unique milestone IDs, push branches, and pre-merge checks in one setting. Override individual settings on top of `mode: team` as needed. + +### 2. Configure `.gitignore` + +Share planning artifacts while keeping runtime files local: + +```bash +# Runtime / ephemeral (per-developer) +.gsd/auto.lock +.gsd/completed-units.json +.gsd/STATE.md +.gsd/metrics.json +.gsd/activity/ +.gsd/runtime/ +.gsd/worktrees/ +.gsd/milestones/**/continue.md +.gsd/milestones/**/*-CONTINUE.md +``` + +**Shared** (committed): preferences, PROJECT.md, REQUIREMENTS.md, DECISIONS.md, milestones. + +**Local** (gitignored): lock files, metrics, state cache, worktrees, activity logs. + +### 3. Commit + +```bash +git add .gsd/preferences.md +git commit -m "chore: enable GSD team workflow" +``` + +## `commit_docs: false` + +For teams where only some members use GSD: + +```yaml +git: + commit_docs: false +``` + +Adds `.gsd/` to `.gitignore` entirely. The developer gets structured planning without affecting teammates. + +## Parallel development + +Multiple developers run auto mode simultaneously on different milestones. Each developer gets their own worktree and unique `milestone/` branch. Milestone dependencies can be declared: + +```yaml +# M00X-CONTEXT.md frontmatter +--- +depends_on: [M001-eh88as] +--- +``` + +GSD enforces that dependent milestones complete before starting downstream work. diff --git a/mintlify-docs/images/favicon.svg b/mintlify-docs/images/favicon.svg new file mode 100644 index 000000000..90071ea65 --- /dev/null +++ b/mintlify-docs/images/favicon.svg @@ -0,0 +1,68 @@ + + + + + + + + + + + + + + + + + + + + Terminal + + + + + ~ + $ + npx get-shit-done-cc + + + ██████╗ ███████╗██████╗ + ██╔════╝ ██╔════╝██╔══██╗ + ██║ ███╗███████╗██║ ██║ + ██║ ██║╚════██║██║ ██║ + ╚██████╔╝███████║██████╔╝ + ╚═════╝ ╚══════╝╚═════╝ + + + Get Shit Done v1.0.1 + A meta-prompting, context engineering and spec-driven + development system for Claude Code by TÂCHES. + + + ✓ Installed commands/gsd + ✓ Installed get-shit-done + + + Done! Run /gsd:help to get started. + + + ~ + $ + ▌ + + diff --git a/mintlify-docs/images/logo.png b/mintlify-docs/images/logo.png new file mode 100644 index 000000000..b4584cc6a Binary files /dev/null and b/mintlify-docs/images/logo.png differ diff --git a/mintlify-docs/images/logo.svg b/mintlify-docs/images/logo.svg new file mode 100644 index 000000000..d9f61c16e --- /dev/null +++ b/mintlify-docs/images/logo.svg @@ -0,0 +1,17 @@ + + + + + + + + + + + + + + + diff --git a/mintlify-docs/introduction.mdx b/mintlify-docs/introduction.mdx new file mode 100644 index 000000000..ea30b2d5d --- /dev/null +++ b/mintlify-docs/introduction.mdx @@ -0,0 +1,101 @@ +--- +title: "GSD — Get Shit Done" +description: "An autonomous coding agent that researches, plans, executes, and commits code while you focus on what matters." +--- + +GSD is an autonomous coding agent. Describe what you want built, run `/gsd auto`, and walk away. Come back to working software with clean git history. + +## What GSD does + + + + A state machine reads your project state, dispatches work to an LLM in fresh context windows, and advances through research, planning, execution, and verification — all without manual intervention. + + + Every task produces a conventional commit. Milestones are squash-merged to main. Your `git log` reads like a changelog. + + + Budget ceilings, token profiles, and dynamic model routing keep costs in check. Use Haiku for simple tasks and Opus for architectural work — automatically. + + + Sessions recover from crashes, provider errors auto-retry, and headless mode auto-restarts with exponential backoff. Designed for overnight unattended execution. + + + +## How it works + +GSD organizes work into a hierarchy: + +``` +Milestone → a shippable version (4-10 slices) + Slice → one demoable vertical capability (1-7 tasks) + Task → one context-window-sized unit of work +``` + +The iron rule: **a task must fit in one context window.** If it can't, it's two tasks. + +Auto mode loops through this hierarchy: + +``` +Plan → Execute (per task) → Complete → Reassess Roadmap → Next Slice + ↓ (all slices done) + Validate → Complete Milestone +``` + +Every phase gets a fresh context window with pre-loaded context — no accumulated garbage, no degraded quality. + +## Two ways to work + + + + Type `/gsd` inside a session. GSD executes one unit at a time, pausing between each so you can review. + + ```bash + gsd + /gsd + ``` + + + Type `/gsd auto` and walk away. GSD autonomously researches, plans, executes, verifies, and commits until the milestone is complete. + + ```bash + gsd + /gsd auto + ``` + + + +The recommended workflow: auto mode in one terminal, steering from another. + +**Terminal 1 — let it build:** + +```bash +gsd +/gsd auto +``` + +**Terminal 2 — steer while it works:** + +```bash +gsd +/gsd discuss # talk through architecture decisions +/gsd status # check progress +/gsd capture # fire-and-forget thoughts +``` + +## Next steps + + + + Get up and running in under a minute. + + + How the autonomous execution engine works. + + + Every command, shortcut, and CLI flag. + + + Models, budgets, timeouts, and preferences. + +