Initial commit

.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.