7d5bf63b2d
* docs: add context optimization design spec, implementation plan, and pi-layer research - Spec: 6-change design for GSD extension context optimization - Plan: 9-task TDD implementation plan with exact file paths and code - Pi-layer doc: 10 infrastructure opportunities (research only, not planned) Part of #3171, #3406, #3452, #3433. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * feat(context): add observation masking for auto-mode sessions Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * feat(context): add phase handoff anchors for auto-mode Introduces PhaseAnchor read/write utilities so downstream agents can inherit decisions, blockers, and intent written at phase boundaries without re-inferring from conversation history. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * feat(context): add capability-aware model routing and context management preferences Implement ADR-004 Phase 2 capability scoring with 7-dimension model profiles, task requirement vectors, and weighted scoring. Add ContextManagementConfig preferences for observation masking thresholds. Wire capability scoring into auto-model-selection dispatch path. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * feat(context): wire observation masking, phase anchors, and tool truncation Register observation masker in before_provider_request hook to replace old tool results with placeholders during auto-mode. Add tool result truncation (configurable via context_management.tool_result_max_chars). Inject phase handoff anchors into prompt builders so downstream phases inherit decisions from research/planning. Write anchors after successful phase completion. Update ADR-004 status to Implemented. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * chore: remove internal planning artifacts from PR Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs: add capability routing, observation masking, and context management Update dynamic-model-routing.md with capability-aware scoring section. Update token-optimization.md with observation masking, tool truncation, and phase handoff anchor documentation. Update configuration.md with context_management preference block and capability_routing flag. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Merge branch 'main' into feat/gsd-context-optimization * fix: add context_management to known keys and prevent tool truncation state corruption - Add missing 'context_management' to KNOWN_PREFERENCE_KEYS set so users don't get spurious unknown-key warnings when configuring it. - Replace in-place mutation of tool result content with immutable spread to prevent corrupting shared conversation message objects. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: add stop and backtrack to triage-ui classification labels The Classification type gained stop and backtrack variants from main but triage-ui.ts was not updated, causing a TypeScript build failure. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: context masker and tool truncation operate on correct pi-ai message format The observation masker and tool result truncation in before_provider_request were checking m.type === "toolResult" but the actual pi-ai payload uses m.role === "toolResult" with content as TextContent[] arrays (not strings). bashExecution messages are converted to {role:"user"} by convertToLlm before the hook fires, so checking m.type === "bashExecution" was a no-op. - Fix context-masker to match on role, handle array content, detect bash results by their "Ran `" prefix - Fix register-hooks truncation to operate on role:"toolResult" with array content blocks - Update tests to use correct pi-ai LLM payload format Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com> |
||
|---|---|---|
| .. | ||
| building-coding-agents | ||
| context-and-hooks | ||
| extending-pi | ||
| pi-ui-tui | ||
| proposals | ||
| superpowers | ||
| what-is-pi | ||
| ADR-001-branchless-worktree-architecture.md | ||
| ADR-003-pipeline-simplification.md | ||
| ADR-004-capability-aware-model-routing.md | ||
| agent-knowledge-index.md | ||
| architecture.md | ||
| auto-mode.md | ||
| captures-triage.md | ||
| ci-cd-pipeline.md | ||
| commands.md | ||
| configuration.md | ||
| cost-management.md | ||
| custom-models.md | ||
| dynamic-model-routing.md | ||
| FILE-SYSTEM-MAP.md | ||
| FRONTIER-TECHNIQUES.md | ||
| getting-started.md | ||
| git-strategy.md | ||
| migration.md | ||
| node-lts-macos.md | ||
| parallel-orchestration.md | ||
| pi-context-optimization-opportunities.md | ||
| PRD-branchless-worktree-architecture.md | ||
| README.md | ||
| remote-questions.md | ||
| skills.md | ||
| token-optimization.md | ||
| troubleshooting.md | ||
| visualizer.md | ||
| web-interface.md | ||
| working-in-teams.md | ||
GSD Documentation
Welcome to the GSD documentation. This covers everything from getting started to advanced configuration, auto-mode internals, and extending GSD with the Pi SDK.
User Documentation
| Guide | Description |
|---|---|
| Getting Started | Installation, first run, and basic usage |
| Auto Mode | How autonomous execution works — the state machine, crash recovery, and steering |
| Commands Reference | All commands, keyboard shortcuts, and CLI flags |
| Remote Questions | Discord and Slack integration for headless auto-mode |
| Configuration | Preferences, model selection, git settings, and token profiles |
| Custom Models | Add custom providers (Ollama, vLLM, LM Studio, proxies) via models.json |
| Token Optimization | Token profiles, context compression, complexity routing, and adaptive learning (v2.17) |
| Dynamic Model Routing | Complexity-based model selection, cost tables, escalation, and budget pressure (v2.19) |
| Captures & Triage | Fire-and-forget thought capture during auto-mode with automated triage (v2.19) |
| Workflow Visualizer | Interactive TUI overlay for progress, dependencies, metrics, and timeline (v2.19) |
| Cost Management | Budget ceilings, cost tracking, projections, and enforcement modes |
| Git Strategy | Worktree isolation, branching model, and merge behavior |
| Parallel Orchestration | Run multiple milestones simultaneously with worker isolation and coordination |
| Working in Teams | Unique milestone IDs, .gitignore setup, and shared planning artifacts |
| Skills | Bundled skills, skill discovery, and custom skill authoring |
| Migration from v1 | Migrating .planning directories from the original GSD |
| Troubleshooting | Common issues, /gsd doctor (real-time visibility v2.40), /gsd forensics (full debugger v2.40), and recovery procedures |
| Web Interface | Browser-based project management with gsd --web (v2.41) |
| VS Code Extension | Chat participant, sidebar dashboard, and RPC integration for VS Code |
Architecture & Internals
| Guide | Description |
|---|---|
| Architecture Overview | System design, extension model, state-on-disk, and dispatch pipeline |
| Native Engine | Rust N-API modules for performance-critical operations |
| ADR-001: Branchless Worktree Architecture | Decision record for the v2.14 git architecture |
| ADR-003: Pipeline Simplification | Research merged into planning, mechanical completion (v2.30) |
| ADR-004: Capability-Aware Model Routing | Extend routing from tier/cost selection to task-capability matching |
Pi SDK Documentation
These guides cover the underlying Pi SDK that GSD is built on. Useful if you want to extend GSD or build your own agent application.
| Guide | Description |
|---|---|
| What is Pi | Core concepts — modes, agent loop, sessions, tools, providers |
| Extending Pi | Building extensions — tools, commands, UI, events, state |
| Context & Hooks | Context pipeline, hook reference, inter-extension communication |
| Pi UI / TUI | Terminal UI components, theming, keyboard input, rendering |
Research
| Guide | Description |
|---|---|
| Building Coding Agents | Research notes on agent design — decomposition, context engineering, cost/quality tradeoffs |