# 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?"
    
    ```bash
    # Agent calls:
    node gsd-tools.js next-step --workflow new-project --state-file .planning/state.json
    ```

    **Tool Returns:**
    ```json
    {
      "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) |