1b317dec45
* 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>
72 lines
4.0 KiB
Markdown
72 lines
4.0 KiB
Markdown
# 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`*
|
|
|
|
1. **State Check:** `gsd-tools` reads `.planning/state.json`.
|
|
2. **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.
|
|
3. **Execution:** Agent executes the task with **< 15% context usage**.
|
|
4. **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. |