msd-core/optimisation-ideas/gemini.md

The "Railroad" Architecture: GSD Framework Evolution

Executive Summary

This document outlines the strategic evolution of the Get Shit Done (GSD) framework from a "Prompt Engineering" reliance to a "Software Engineering" foundation. The core objective is to reduce token consumption ("context tax") and increase reliability by shifting workflow logic from LLM context to deterministic code.

1. The Core Shift: "Railroad" State Machine

Current State

Currently, the LLM acts as the Workflow Engine. It reads a verbose Markdown file (e.g., new-project.md) containing logic like:

"If the user says X, then ask Y. If they say Z, execute tool A."

This relies on "soft state management" where the LLM must perfectly recall and adhere to written instructions.

Proposed State ("Railroad")

The LLM becomes an Intelligent Worker, while gsd-tools becomes the Workflow Engine.

• Logic in Code: Complex branching logic is moved to gsd-tools.

• The "Next Step" Pattern: Instead of reading a map, the Agent simply asks: "What is next?"

  # Agent calls:
  node gsd-tools.js next-step --workflow new-project --state-file .planning/state.json
  

  Tool Returns:

  {
    "action": "ask_user",
    "prompt": "What do you want to build?",
    "context_files": []
  }
  

• Benefit: The Agent needs zero knowledge of the overall workflow. It focuses 100% of its attention on executing the single, immediate task. It cannot "skip" steps because it doesn't know they exist until the tool assigns them.

2. Just-in-Time (JIT) Context Loading

Current State

We load all templates, references, and instructions at the start of a session.

• Example: new-project loads questioning.md, project.md template, requirements.md template, etc.

Proposed State

Context is injected only when needed for the specific step.

• Step 1 (Questioning): Load questioning.md. Do NOT load requirements.md template.
• Step 2 (Requirements): Unload questioning.md. Load requirements.md template.
• Step 3 (Roadmap): Load ROADMAP.md template.

Mechanism: The gsd-tools next-step response includes a context_files array. The wrapper script or system prompt dynamically reads these files into the context window for that turn only.

3. Native Interventions (Bypassing the LLM)

Current State

The LLM acts as a text-based menu system.

"User, please choose: 1. YOLO Mode, 2. Interactive Mode."

This burns tokens on input tokens (instructions on how to ask), output tokens (asking the question), and input tokens (processing the user's "1").

Proposed State

Standardize discrete choices into CLI interactions managed by gsd-tools or the wrapper.

• Configuration Wizard: gsd-tools init new-project runs an interactive CLI wizard (using inquirer or readline) to gather mode, depth, parallelization preferences before the LLM is even invoked.
• Structured Output: The LLM receives the result as a finalized JSON configuration, not a conversation transcript.

4. Micro-Agents & Chained Execution

Current State

Monolithic workflows (new-project) maintain a single context window that grows indefinitely. By the time the agent reaches "Roadmap Creation" (Step 9), the context is polluted with "Questioning" (Step 3) transcripts.

Proposed State

Break workflows into atomic, chainable units.

1. Process: gsd:new-project
2. Chain:
   • Agent A (Scope): Interviews user \rightarrow Outputs PROJECT.md \rightarrow Exits.
   • Context Flush
   • Agent B (Research): Reads PROJECT.md \rightarrow Outputs research/ \rightarrow Exits.
   • Context Flush
   • Agent C (Roadmap): Reads PROJECT.md + research/ \rightarrow Outputs ROADMAP.md.

Implementation: The gsd-tools utility manages the hand-off. When Agent A finishes, it returns a specific exit code or signal. The outer loop detects this, clears context, and spawns Agent B with the specific inputs generated by A.

Implementation Roadmap

1. Expand gsd-tools:
   • Implement next-step state machine logic.
   • Add interactive CLI prompts for configuration.
2. Refactor Workflows:
   • Strip workflows/*.md to bare essentials (or remove them entirely in favor of code definitions).
3. Update Agent Definitions:
   • Direct agents to rely on gsd-tools for guidance rather than internal reasoning about the process.

Summary of Benefits

Metric	Current	Railroad Architecture
Context Usage	High (Full workflow + History)	Minimal (Current Step + Immediate Inputs)
Reliability	Variable (LLM can hallucinate process)	Deterministic (Code enforces process)
Speed	Slower (Reading/generating verbose text)	Faster (Code execution + concise LLM tasks)
Maintenance	Distributed (Markdown files)	Centralized (JS Logic)