990441dfc1
Implemented Story 8: Collapsible Tool Outputs - Tool outputs now render in <details>/<summary> elements, collapsed by default - Summary shows tool name with key argument (e.g., ▶ read_file(src/main.rs)) - Added arrow rotation animation and scrollable content (max 300px) - Enhanced tool_calls display to show arguments inline - Added CSS styling for dark theme consistency Fixed: LLM autonomous coding behavior - Strengthened system prompt with explicit examples and directives - Implemented triple-reinforcement system (primary prompt + reminder + message prefixes) - Improved tool descriptions to be more explicit and action-oriented - Increased MAX_TURNS from 10 to 30 for complex agentic workflows - Added debug logging for Ollama requests/responses - Result: GPT-OSS (gpt-oss:20b) now successfully uses write_file autonomously Documentation improvements - Created MODEL_SELECTION.md guide with recommendations - Updated PERSONA.md spec to emphasize autonomous agent behavior - Updated UI_UX.md spec with collapsible tool output requirements - Updated SDSW workflow: LLM archives stories and performs squash merge Cleanup - Removed unused ToolTester.tsx component
98 lines
4.6 KiB
Markdown
98 lines
4.6 KiB
Markdown
# The Story-Driven Spec Workflow (SDSW)
|
|
|
|
**Target Audience:** Large Language Models (LLMs) acting as Senior Engineers.
|
|
**Goal:** To maintain long-term project coherence, prevent context window exhaustion, and ensure high-quality, testable code generation in large software projects.
|
|
|
|
---
|
|
|
|
## 1. The Philosophy
|
|
|
|
We treat the codebase as the implementation of a **"Living Specification."**
|
|
Instead of ephemeral chat prompts ("Fix this", "Add that"), we work through persistent artifacts.
|
|
* **Stories** define the *Change*.
|
|
* **Specs** define the *Truth*.
|
|
* **Code** defines the *Reality*.
|
|
|
|
**The Golden Rule:** You are not allowed to write code until the Spec reflects the new reality requested by the Story.
|
|
|
|
---
|
|
|
|
## 2. Directory Structure
|
|
|
|
When initializing a new project under this workflow, create the following structure immediately:
|
|
|
|
```text
|
|
project_root/
|
|
.living_spec
|
|
|-- README.md # This document
|
|
├── stories/ # The "Inbox" of feature requests.
|
|
├── specs/ # The "Brain" of the project.
|
|
│ ├── README.md # Explains this workflow to future sessions.
|
|
│ ├── 00_CONTEXT.md # High-level goals, domain definition, and glossary.
|
|
│ ├── tech/ # Implementation details (Stack, Architecture, Constraints).
|
|
│ │ └── STACK.md # The "Constitution" (Languages, Libs, Patterns).
|
|
│ └── functional/ # Domain logic (Platform-agnostic behavior).
|
|
│ ├── 01_CORE.md
|
|
│ └── ...
|
|
└── src/ # The Code.
|
|
```
|
|
|
|
---
|
|
|
|
## 3. The Cycle (The "Loop")
|
|
|
|
When the user asks for a feature, follow this 4-step loop strictly:
|
|
|
|
### Step 1: The Story (Ingest)
|
|
* **User Input:** "I want the robot to dance."
|
|
* **Action:** Create a file `stories/XX_robot_dance.md`.
|
|
* **Content:**
|
|
* **User Story:** "As a user, I want..."
|
|
* **Acceptance Criteria:** Bullet points of observable success.
|
|
* **Out of scope:** Things that are out of scope so that the LLM doesn't go crazy
|
|
* **Git:** The Assistant initiates a new local feature branch (e.g., `feature/story-name`) immediately.
|
|
|
|
### Step 2: The Spec (Digest)
|
|
* **Action:** Update the files in `specs/`.
|
|
* **Logic:**
|
|
* Does `specs/functional/LOCOMOTION.md` exist? If no, create it.
|
|
* Add the "Dance" state to the state machine definition in the spec.
|
|
* Check `specs/tech/STACK.md`: Do we have an approved animation library? If no, propose adding one to the Stack or reject the feature.
|
|
* **Output:** Show the user the diff of the Spec. **Wait for approval.**
|
|
|
|
### Step 3: The Implementation (Code)
|
|
* **Action:** Write the code to match the *Spec* (not just the Story).
|
|
* **Constraint:** adhere strictly to `specs/tech/STACK.md` (e.g., if it says "No `unwrap()`", you must not use `unwrap()`).
|
|
|
|
### Step 4: Verification (Close)
|
|
* **Action:** Write a test case that maps directly to the Acceptance Criteria in the Story.
|
|
* **Action:** Run compilation and make sure it succeeds without errors. Fix warnings if possible. Run tests and make sure they all pass before proceeding. Ask questions here if needed.
|
|
* **Action:** Ask the user to accept the story.
|
|
* **Action:** When the user accepts, move the story file to `stories/archive/` (e.g., `mv stories/XX_story_name.md stories/archive/`).
|
|
* **Action:** Commit the archive move to the feature branch.
|
|
* **Action:** Tell the user to **Squash Merge** the feature branch (e.g., `git merge --squash feature/story-name`) and commit. This ensures the main history reflects one atomic commit per Story, including the archived story file.
|
|
|
|
|
|
---
|
|
|
|
## 4. Context Reset Protocol
|
|
|
|
When the LLM context window fills up (or the chat gets slow/confused):
|
|
1. **Stop Coding.**
|
|
2. **Instruction:** Tell the user to open a new chat.
|
|
3. **Handoff:** The only context the new LLM needs is in the `specs/` folder.
|
|
* *Prompt for New Session:* "I am working on Project X. Read `specs/00_CONTEXT.md` and `specs/tech/STACK.md`. Then look at `stories/` to see what is pending."
|
|
|
|
---
|
|
|
|
## 5. Setup Instructions (For the LLM)
|
|
|
|
If a user hands you this document and says "Apply this process to my project":
|
|
|
|
1. **Analyze the Request:** Ask for the high-level goal ("What are we building?") and the tech preferences ("Rust or Python?").
|
|
2. **Git Check:** Check if the directory is a git repository (`git status`). If not, run `git init`.
|
|
3. **Scaffold:** Run commands to create the `specs/` and `stories/` folders.
|
|
4. **Draft Context:** Write `specs/00_CONTEXT.md` based on the user's answer.
|
|
5. **Draft Stack:** Write `specs/tech/STACK.md` based on best practices for that language.
|
|
6. **Wait:** Ask the user for "Story #1".
|