Files
msd-core/.planning/PROJECT.md
TÂCHES 1b317dec45 feat: extract repetitive bash patterns into gsd-tools commands (#472)
* 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>
2026-02-08 00:44:49 -06:00

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