* feat(gsd-tools): add history-digest, atomic state operations, and summary variants Adds new performance-focused commands to gsd-tools and introduces specialized summary templates to reduce context tax: - history-digest: Compiles phase summaries into structured JSON for JIT loading - state get/patch: Enables atomic STATE.md operations instead of full rewrites - template select: Automatically chooses optimal summary template based on plan complexity - Adds minimal, standard, and complex summary templates Part of the "Hydra" architecture for GSD context optimization. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * chore: add project config * docs: define v1 requirements * docs: create roadmap (6 phases) * feat(history-digest): fix nested YAML parsing and add tests - Fix extractFrontmatter() to handle nested YAML structures like dependency-graph.provides, tech-stack.added using stack-based parsing - Add test infrastructure with Node test runner (npm test) - Update gsd-planner to use digest fields directly instead of reading full SUMMARY.md files - Add 6 schema validation tests covering nested fields, merging, malformed files, and backward compatibility Closes: HIST-01, HIST-02, HIST-03, HIST-04 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix(planner): use digest for selection, full SUMMARY for understanding The previous commit went too far by eliminating full SUMMARY reads. The digest is an index for smart selection, not a replacement for understanding what actually happened. Two-step approach: 1. Digest to score/select relevant phases (2-4 typically) 2. Full SUMMARY read for selected phases (implementation details) 3. Digest-level context retained for unselected phases Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * feat(gsd-tools): add phases, roadmap, and phase commands TDD implementation of three new commands to replace repetitive bash: phases list [--type plans|summaries] [--phase N] - Lists phase directories sorted numerically (handles decimals) - Filter by file type or specific phase - Replaces: ls -d .planning/phases/*/ | sort -V (22 occurrences) roadmap get-phase <N> - Extracts phase section from ROADMAP.md - Returns name, goal, full section content - Replaces: grep -A20 "Phase X:" ROADMAP.md (19 occurrences) phase next-decimal <N> - Calculates next decimal phase (06 → 06.1, 06.2 → 06.3) - Handles gaps, normalizes input - Replaces: complex bash math in insert-phase (3 occurrences) 16 new tests, all passing. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * refactor: migrate agents/workflows to use gsd-tools commands Replace inline bash patterns with centralized gsd-tools commands: phases list: - audit-milestone.md: ls -d .planning/phases/*/ | sort -V - plan-milestone-gaps.md: ls -d ... | sort -V | tail -1 roadmap get-phase: - plan-phase.md: grep -A5 "Phase X:" ROADMAP.md (2 occurrences) - research-phase.md: grep patterns (2 occurrences) - verify-phase.md: grep -A5 pattern - gsd-verifier.md: grep -A5 pattern - gsd-plan-checker.md: grep -A10 pattern - commands/gsd/research-phase.md: grep patterns (2 occurrences) phase next-decimal: - insert-phase.md: complex bash decimal calculation - decimal-phase-calculation.md: reference doc rewritten phase-argument-parsing.md: updated to reference gsd-tools Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
2.4 KiB
2.4 KiB
GSD Context Optimization
What This Is
Optimizing GSD's context loading so agents start lean and stay in their peak quality zone. Reduces prompt bloat through lazy loading, tiered prompts, and compiled artifacts while preserving instructional density.
Core Value
Agents execute at peak quality by starting at 8-12% context instead of 15-25%.
Requirements
Validated
(None yet — ship to validate)
Active
- History loads as structured digest instead of full SUMMARY.md files
- Summary templates match plan complexity (minimal/standard/complex)
- State operations are atomic patches, not full file read/write cycles
- Executor loads references on-demand based on task type
- Planner loads extensions based on planning mode
- Plans can be pre-compiled before execution
Out of Scope
- Enhanced semantic queries (Phase 4) — defer unless Phases 1-3 prove insufficient
- Compressing instructional content — core methodology must remain intact
- Complex cache invalidation — simple mtime checks are sufficient
Context
Problem: Claude's quality degrades predictably with context load:
- 0-30% context: Peak quality
- 30-50%: Good, occasional shortcuts
- 50-70%: Degrading, efficiency mode
- 70%+: Poor, rushed, misses requirements
Complex phases currently start agents at 15-25% context from prompt loading alone—before any codebase reading.
Prior work: v1.12.x shipped compound init commands (4,245 net line reduction), proving the direction works.
Target state: Agents start at 8-12% context, preserving peak quality zone for execution.
Constraints
- Instructional density: Teaching content cannot be compressed—it's GSD's value
- Adaptive intelligence: Agents must still handle mid-execution surprises
- Maintainability: Clear separation between core and extensions
- Debuggability: Easy to trace which modules loaded for any execution
- TDD: Use test-driven development for gsd-tools.js changes — write tests first, then implementation
Key Decisions
| Decision | Rationale | Outcome |
|---|---|---|
| Lazy loading over railroad architecture | Preserves adaptive intelligence while reducing context | — Pending |
| Build on compound-init foundation | v1.12.x proved the pattern works | — Pending |
| Three-phase implementation | Incremental, reversible changes | — Pending |
Last updated: 2025-02-07 after initialization