Files

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

4.0 KiB

Raw Blame History

GSD Performance Architecture: The "Hydra" Engine

Objective: Transition GSD from a context-taxed "Prompt-Driven" system to a "Software-Engineered" Agentic Framework.

1. The Core Philosophy: "Attention Density"

In LLM systems, Context is Noise. Every irrelevant line of TDD instruction loaded during a simple documentation task isn't just a "token cost"—it is attention dilution. The "Hydra" architecture ensures that for any given turn, the LLM has 100% relevance density.

2. Structural Synthesis: The Three Pillars

Pillar I: The "Railroad" Spine (Deterministic Logic)

We will move workflow management out of the LLM's head and into gsd-tools.js.

The Shift: Instead of an Agent reading a 300-line execute-phase.md to figure out what to do next, it calls gsd-tools next-step.
The Result: The LLM's context window is freed from "Process Overhead" and reserved entirely for "Task Logic."

Pillar II: "Lazy-Load" Context (The JIT Memory)

We will implement Just-In-Time (JIT) injection for all instructional content.

Tiered Agents: gsd-planner-core (The what) + gsd-planner-tdd (The how, loaded only when code changes are detected).
Frontmatter Digests: Instead of reading 10 full summaries (20KB), the Agent reads a single JSON digest (2KB) of dependencies and patterns.
Compiled Plans: Plans are "pre-baked" by gsd-tools to strip unused protocols (e.g., removing Checkpoint rules if the plan has no checkpoints).

Pillar III: Chained Execution (Context Flushing)

We will move away from monolithic sessions.

Micro-Agents: Break new-project into: Interviewer → Architect → Roadmapper.
Hand-offs: Each agent performs its task, writes to disk, and terminates. The next agent starts with a clean context window, reading only the necessary outputs from the previous step. This eliminates "Transcript Bloat."

3. The Target State Execution Flow

Example: Running gsd execute-phase

State Check: gsd-tools reads .planning/state.json.
Context Assembly:
- Loads gsd-executor-core.md (Base identity).
- Detects "TDD" flag in task: Injects references/tdd.md.
- Detects "API" change: Injects history-digest.json filtered for "API" tags.
Execution: Agent executes the task with < 15% context usage.
Atomic Update: Agent reports success. gsd-tools patches STATE.md and SUMMARY.md via deterministic code, not LLM rewriting.

4. Implementation Roadmap (The 4-Phase Sprint)

Phase 1: The "Low-Hanging" Pruning (Quick Wins)

Action: Implement gsd-tools history-digest and gsd-tools state patch.
Impact: Immediate 40% reduction in history/state overhead.
Timeline: 1 Day.

Phase 2: The "Lazy-Load" Restructuring

Action: Split gsd-executor and gsd-planner into -core and -ext modules.
Action: Update wrapper scripts to dynamically assemble prompts based on task metadata.
Impact: Massive reduction in "Instructional Noise."
Timeline: 3 Days.

Phase 3: The "Railroad" Migration

Action: Convert workflows/*.md logic into a JSON-based state machine in gsd-tools.
Action: Implement the next-step pattern.
Impact: Elimination of "Process Hallucination" and workflow skipping.
Timeline: 5 Days.

Phase 4: Semantic Intelligence (The MCP Layer)

Action: Extend gsd-memory MCP to index summaries.
Action: Replace grep searches with semantic queries.
Impact: Precise, noise-free context retrieval for large codebases.
Timeline: 7 Days.

5. Risk Assessment: "The Instruction Guardrail"

You noted that instructional content is crucial.

Mitigation: We do not "slim" the instructions; we modularize them.
Example: The TDD protocol remains exactly as detailed as it is today, but it simply does not exist in the LLM's mind when it is renaming a file or updating a README. This actually improves TDD fidelity because the LLM isn't distracted by other protocols.

4.0 KiB Raw Blame History