Initial commit

.living_spec/README.md

@@ -0,0 +1,93 @@
+# 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:** Make a local feature branch for the story. 
+
+### 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. Move to `stories/archive/`. Tell the user they should commit (this gives them the chance to exclude files via .gitignore if necessary)
+
+
+---
+
+## 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.  **Scaffold:** Run commands to create the `specs/` and `stories/` folders.
+3.  **Draft Context:** Write `specs/00_CONTEXT.md` based on the user's answer.
+4.  **Draft Stack:** Write `specs/tech/STACK.md` based on best practices for that language.
+5.  **Wait:** Ask the user for "Story #1".

.living_spec/specs/00_CONTEXT.md

@@ -0,0 +1,33 @@
+# Project Context
+
+## High-Level Goal
+To build a standalone **Agentic AI Code Assistant** application using Tauri. The assistant will facilitate a "Story-Driven Spec Workflow" (SDSW) for software development. Unlike a passive chat interface, this assistant acts as an **Agent**, capable of using tools to read the filesystem, execute shell commands, manage git repositories, and modify code directly to implement features.
+
+## Core Features
+1.  **Chat Interface:** A conversational UI for the user to interact with the AI assistant.
+2.  **Agentic Tool Bridge:** A robust system mapping LLM "Tool Calls" to native Rust functions.
+    *   **Filesystem:** Read/Write access (scoped to the target project).
+    *   **Search:** High-performance file searching (ripgrep-style) and content retrieval.
+    *   **Shell Integration:** Ability to execute approved commands (e.g., `cargo`, `npm`, `git`) to run tests, linters, and version control.
+3.  **Workflow Management:** Specialized tools to manage the SDSW lifecycle:
+    *   Ingesting stories.
+    *   Updating specs.
+    *   Implementing code.
+    *   Verifying results (running tests).
+4.  **LLM Integration:** Connection to an LLM backend to drive the intelligence and tool selection.
+    *   **Remote:** Support for major APIs (Anthropic Claude, Google Gemini, OpenAI, etc).
+    *   **Local:** Support for local inference via Ollama.
+
+## Domain Definition
+*   **User:** A software engineer using the assistant to build a project.
+*   **Target Project:** The local software project the user is working on.
+*   **Agent:** The AI entity that receives prompts and decides which **Tools** to invoke to solve the problem.
+*   **Tool:** A discrete function exposed to the Agent (e.g., `run_shell_command`, `write_file`, `search_project`).
+*   **Story:** A unit of work defining a change (Feature Request).
+*   **Spec:** A persistent documentation artifact defining the current truth of the system.
+
+## Glossary
+*   **SDSW:** Story-Driven Spec Workflow.
+*   **Tauri:** The framework used to build this assistant (Rust backend + Web frontend).
+*   **Living Spec:** The collection of Markdown files in `.living_spec/` that define the project.
+*   **Tool Call:** A structured request from the LLM to execute a specific native function.

.living_spec/specs/README.md

@@ -0,0 +1,17 @@
+# Project Specs
+
+This folder contains the "Living Specification" for the project. It serves as the source of truth for all AI sessions.
+
+## Structure
+
+*   **00_CONTEXT.md**: The high-level overview, goals, domain definition, and glossary. Start here.
+*   **tech/**: Implementation details, including the Tech Stack, Architecture, and Constraints.
+    *   **STACK.md**: The technical "Constitution" (Languages, Libraries, Patterns).
+*   **functional/**: Domain logic and behavior descriptions, platform-agnostic.
+    *   **01_CORE.md**: Core functional specifications.
+
+## Usage for LLMs
+
+1.  **Always read 00_CONTEXT.md** and **tech/STACK.md** at the beginning of a session.
+2.  Before writing code, ensure the spec in this folder reflects the desired reality.
+3.  If a Story changes behavior, update the spec *first*, get approval, then write code.

.living_spec/specs/functional/PROJECT_MANAGEMENT.md

@@ -0,0 +1,27 @@
+# Functional Spec: Project Management
+
+## 1. Project Lifecycle State Machine
+The application operates in two primary states regarding project context:
+
+1.  **Idle (No Project):**
+    *   The user cannot chat about code.
+    *   The only available primary action is "Open Project".
+2.  **Active (Project Loaded):**
+    *   A valid local directory path is stored in the Session State.
+    *   Tool execution (read/write/shell) is enabled, scoped to this path.
+
+## 2. Selection Logic
+*   **Trigger:** User initiates "Open Project".
+*   **Mechanism:** Native OS Directory Picker (via `tauri-plugin-dialog`).
+*   **Validation:**
+    *   The backend receives the selected path.
+    *   The backend verifies:
+        1.  Path exists.
+        2.  Path is a directory.
+        3.  Path is readable.
+    *   If valid -> State transitions to **Active**.
+    *   If invalid -> Error returned to UI, State remains **Idle**.
+
+## 3. Security Boundaries
+*   Once a project is selected, the `SessionState` struct in Rust locks onto this path.
+*   All subsequent file operations must validate that their target path is a descendant of this Root Path.

.living_spec/specs/tech/STACK.md

@@ -0,0 +1,90 @@
+# Tech Stack & Constraints
+
+## Overview
+This project is a desktop application built with **Tauri**. It functions as an **Agentic Code Assistant** capable of safely executing tools on the host system.
+
+## Core Stack
+*   **Backend:** Rust (Tauri Core)
+    *   **MSRV:** Stable (latest)
+    *   **Framework:** Tauri v2
+*   **Frontend:** TypeScript + React
+    *   **Build Tool:** Vite
+    *   **Styling:** CSS Modules or Tailwind (TBD - Defaulting to CSS Modules)
+    *   **State Management:** React Context / Hooks
+    *   **Chat UI:** Rendered Markdown with syntax highlighting.
+
+## Agent Architecture
+The application follows a **Tool-Use (Function Calling)** architecture:
+1.  **Frontend:** Collects user input and sends it to the LLM.
+2.  **LLM:** Decides to generate text OR request a **Tool Call** (e.g., `execute_shell`, `read_file`).
+3.  **Tauri Backend (The "Hand"):**
+    *   Intercepts Tool Calls.
+    *   Validates the request against the **Safety Policy**.
+    *   Executes the native code (File I/O, Shell Process, Search).
+    *   Returns the output (stdout/stderr/file content) to the LLM.
+
+## LLM Provider Abstraction
+To support both Remote and Local models, the system implements a `ModelProvider` abstraction layer.
+
+*   **Strategy:**
+    *   Abstract the differences between API formats (OpenAI-compatible vs Anthropic vs Gemini).
+    *   Normalize "Tool Use" definitions, as each provider handles function calling schemas differently.
+*   **Supported Providers:**
+    *   **Anthropic:** Focus on Claude 3.5 Sonnet for coding tasks.
+    *   **Google:** Gemini 1.5 Pro for massive context windows.
+    *   **Ollama:** Local inference (e.g., Llama 3, DeepSeek Coder) for privacy and offline usage.
+*   **Configuration:**
+    *   Provider selection is runtime-configurable by the user.
+    *   API Keys must be stored securely (using OS native keychain where possible).
+
+## Tooling Capabilities
+
+### 1. Filesystem (Native)
+*   **Scope:** Strictly limited to the user-selected `project_root`.
+*   **Operations:** Read, Write, List, Delete.
+*   **Constraint:** Modifications to `.git/` are strictly forbidden via file APIs (use Git tools instead).
+
+### 2. Shell Execution
+*   **Library:** `tokio::process` for async execution.
+*   **Constraint:** We do **not** run an interactive shell (repl). We run discrete, stateless commands.
+*   **Allowlist:** The agent may only execute specific binaries:
+    *   `git`
+    *   `cargo`, `rustc`, `rustfmt`, `clippy`
+    *   `npm`, `node`, `yarn`, `pnpm`, `bun`
+    *   `ls`, `find`, `grep` (if not using internal search)
+    *   `mkdir`, `rm`, `touch`, `mv`, `cp`
+
+### 3. Search & Navigation
+*   **Library:** `ignore` (by BurntSushi) + `grep` logic.
+*   **Behavior:**
+    *   Must respect `.gitignore` files automatically.
+    *   Must be performant (parallel traversal).
+
+## Coding Standards
+
+### Rust
+*   **Style:** `rustfmt` standard.
+*   **Error Handling:** Custom `AppError` type deriving `thiserror`. All Commands return `Result<T, AppError>`.
+*   **Concurrency:** Heavy tools (Search, Shell) must run on `tokio` threads to avoid blocking the UI.
+
+### TypeScript / React
+*   **Style:** Prettier / ESLint standard.
+*   **Types:** Shared types with Rust (via `tauri-specta` or manual interface matching) are preferred to ensure type safety across the bridge.
+
+## Libraries (Approved)
+*   **Rust:**
+    *   `serde`, `serde_json`: Serialization.
+    *   `ignore`: Fast recursive directory iteration respecting gitignore.
+    *   `tokio`: Async runtime.
+    *   `reqwest`: For LLM API calls (if backend-initiated).
+    *   `tauri-plugin-dialog`: Native system dialogs.
+*   **JavaScript:**
+    *   `@tauri-apps/api`: Tauri Bridge.
+    *   `@tauri-apps/plugin-dialog`: Dialog API.
+    *   `react-markdown`: For rendering chat responses.
+
+## Safety & Sandbox
+1.  **Project Scope:** The application must strictly enforce that it does not read/write outside the `project_root` selected by the user.
+2.  **Human in the Loop:**
+    *   Shell commands that modify state (non-readonly) should ideally require a UI confirmation (configurable).
+    *   File writes must be confirmed or revertible.

.living_spec/stories/01_project_selection.md

@@ -0,0 +1,18 @@
+# Story: Project Selection & Read Verification
+
+## User Story
+**As a** User
+**I want to** select a local folder on my computer as the "Target Project"
+**So that** the assistant knows which codebase to analyze and work on.
+
+## Acceptance Criteria
+*   [ ] UI has an "Open Project" button.
+*   [ ] Clicking the button opens the native OS folder picker.
+*   [ ] Upon selection, the UI displays the selected path.
+*   [ ] The system verifies the folder exists and is readable.
+*   [ ] The application state persists the "Current Project" (in memory is fine for now).
+
+## Out of Scope
+*   Persisting the selection across app restarts (save that for later).
+*   Scanning the file tree (just verify the root exists).
+*   Git validation (we'll assume any folder is valid for now).