features/llm-understandings - VS Code extension, REST API, core value types and refactors

.ai-dev/project.json

@@ -0,0 +1,4 @@
+{
+  "projectSlug": "ai-dev",
+  "apiPort": 5191
+}

.gitignore

@@ -407,6 +407,11 @@ MigrationBackup/
 # Fody - auto-generated XML schema
 FodyWeavers.xsd
 
+# VS Code extension — generated backend binaries (produced by npm run package:*)
+ai-dev-vscode/bin/
+# *.vsix build artefacts
+ai-dev-vscode/*.vsix
+
 # VS Code files for those working on multiple tools
 .vscode/*
 !.vscode/settings.json

.vscode/launch.json

@@ -26,6 +26,33 @@
             "type": "dotnet",
             "request": "launch",
             "projectPath": "${workspaceFolder}/ai-dev-net.AppHost/ai-dev-net.AppHost.csproj"
+        },
+        {
+            "name": "Run Extension",
+            "type": "extensionHost",
+            "request": "launch",
+            "args": [
+                "--extensionDevelopmentPath=${workspaceFolder}/ai-dev-vscode",
+                "${workspaceFolder}"
+            ],
+            "outFiles": [
+                "${workspaceFolder}/ai-dev-vscode/dist/**/*.js"
+            ],
+            "preLaunchTask": "build-extension"
+        },
+        {
+            "name": "ai-dev.api",
+            "type": "dotnet",
+            "request": "launch",
+            "projectPath": "${workspaceFolder}/ai-dev.api/ai-dev.api.csproj",
+            "launchSettingsProfile": "http"
+        }
+    ],
+    "compounds": [
+        {
+            "name": "API + Extension",
+            "configurations": ["ai-dev.api", "Run Extension"],
+            "stopAll": true
         }
     ]
 }

.vscode/settings.json

@@ -2,5 +2,16 @@
     "chat.tools.terminal.autoApprove": {
         "dotnet test": true,
         "dotnet list": true
+    },
+    "files.watcherExclude": {
+        "**/node_modules/**": true,
+        "**/dist/**": true
+    },
+    "files.exclude": {
+        "**/node_modules": true
+    },
+    "search.exclude": {
+        "**/node_modules": true,
+        "**/dist": true
     }
 }

.vscode/tasks.json

@@ -29,6 +29,16 @@
             ],
             "problemMatcher": "$msCompile",
             "group": "build"
+        },
+        {
+            "label": "build-extension",
+            "type": "shell",
+            "command": "npm run build",
+            "options": {
+                "cwd": "${workspaceFolder}/ai-dev-vscode"
+            },
+            "problemMatcher": ["$tsc"],
+            "group": "build"
         }
     ]
 }

CLAUDE.md

@@ -0,0 +1,123 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+### .NET (run from repo root)
+
+```bash
+# Build solution
+dotnet build ai-dev-net.slnx
+
+# Run all unit tests
+dotnet test ai-dev-net.tests.unit/ai-dev-net.tests.unit.csproj
+
+# Run a single test class or method
+dotnet test ai-dev-net.tests.unit/ai-dev-net.tests.unit.csproj --filter "FullyQualifiedName~AgentSlugTests"
+
+# Run integration tests
+dotnet test ai-dev-net.tests.integration/ai-dev-net.tests.integration.csproj
+
+# Run the Aspire host (starts all services)
+dotnet run --project ai-dev-net.AppHost
+
+# Run just the API
+dotnet run --project ai-dev.api
+
+# Run the WinUI desktop app (requires Windows, x64)
+dotnet run --project ai-dev.ui.winui -p:Platform=x64
+```
+
+### VS Code Extension (run from `ai-dev-vscode/`)
+
+```bash
+npm run build      # one-shot bundle
+npm run watch      # incremental rebuild
+npm test           # Jest unit tests
+npm run package    # produce .vsix for sideloading
+```
+
+### CI mirrors
+
+CI runs `dotnet restore ai-dev-net.slnx`, then `dotnet build` with `-c Release -p:Platform=x64`, then the unit tests. `Directory.Build.props` sets `TreatWarningsAsErrors=true` globally — the build will fail on any warning.
+
+---
+
+## Architecture
+
+This is a multi-agent AI orchestration platform. The .NET backend manages projects, agents, tasks (a Kanban board), decisions, and planning sessions. A WinUI 3 desktop app and an ASP.NET Core web app provide UI. A VS Code extension surfaces agent activity in the editor sidebar.
+
+### Layer map
+
+```
+ai-dev-net.AppHost          Aspire orchestration host — entry point for dev/deploy
+ai-dev.api                  ASP.NET Core Minimal API + SignalR hub; consumed by the VS Code extension
+ai-dev.ui.winui             WinUI 3 desktop app (Windows App SDK 1.8), x86/x64/ARM64
+ai-dev.core                 Domain: entities, value types, service contracts, domain events
+ai-dev.core.local           Local orchestration: planning sessions, transcript compaction, progressive context discovery
+ai-dev.mcp                  Model Context Protocol server — workspace tools (file I/O, git, journal) exposed to LLMs
+ai-dev.executor.*           Six pluggable LLM backends (Anthropic, Claude CLI, Ollama, LM Studio, GitHub Models, Copilot CLI)
+ai-dev-net.ServiceDefaults  Shared DI/service configuration used by all host projects
+ai-dev-vscode               VS Code extension: React 19 webviews, SignalR client, backend process manager
+```
+
+### How the pieces connect
+
+- **Executors** implement a common contract in `ai-dev.core` and are registered via their own `Add*Executor()` extension methods. The `ModelResolver` and `AgentRunnerService` in `ai-dev.core` select and invoke them.
+- **`ai-dev.core.local`** sits above `ai-dev.core` and handles the stateful session lifecycle: building prompts (`AgentPromptBuilder`), compacting transcripts (`RuleBasedContextCompactor`), running progressive discovery (`ProgressiveDiscoveryEngine`), and routing tool calls (`LocalToolBroker`).
+- **`ai-dev.mcp`** exposes workspace tools (file reads, git ops, journal writes) as MCP tools. Executors that support MCP (Anthropic, Claude CLI) call these tools; the responses are routed back through the session.
+- **`ai-dev.api`** is a thin HTTP layer over `ai-dev.core` services. It also hosts a SignalR hub (`ProjectStateHub`) that pushes `ProjectStateChangedEvent` domain events to connected clients (the VS Code extension).
+- **`ai-dev.ui.winui`** uses the same `ai-dev.core` services directly (in-process) via DI. View models are MVVM Community Toolkit `ObservableObject` partials.
+- **`ai-dev-vscode`** connects to `ai-dev.api` via REST + SignalR. `WorkspaceDetector` discovers projects by watching for `.ai-dev/project.json` files across open workspace folders; `BackendProcessManager` spawns the API process from the bundled binaries.
+
+### Workspace layout on disk
+
+```
+<workspace-root>/
+  .ai-dev/
+    workspaces.json           project registry (slug → name)
+    studio-settings.json
+    <project-slug>/
+      project.json            project metadata (codebasePath, codebaseInitialized, …)
+      agents/
+      board/
+      decisions/
+      kb/
+      playbooks/
+      sessions/
+```
+
+`WorkspacePaths` in `ai-dev.core` is the single source of truth for all path resolution. Every service resolves paths through it — never string-concatenate paths directly.
+
+The VS Code extension discovers a project via `<codebase>/.ai-dev/project.json` (fields: `projectSlug`, `apiPort`). This file is separate from the studio workspace storage above.
+
+### Domain model
+
+See `docs/UBIQUITOUS_LANGUAGE.md` for the canonical glossary. Key terms:
+
+- **Agent** — an autonomous LLM worker with a slug, executor, and inbox. Runs one session at a time.
+- **Task / BoardTask** — a Kanban card. Assigned to an agent via `TaskAssigned` domain event.
+- **Decision** — a pending question surfaced by an agent; resolved by a human or another agent.
+- **Planning Session** — a multi-turn LLM conversation that produces a structured plan before execution.
+- **Executor** — the runtime backend that sends prompts to an LLM and streams tool calls back.
+
+### Value types
+
+All domain identifiers are strongly-typed immutable records (`AgentSlug`, `ProjectSlug`, `TaskId`, `ColumnId`, `DecisionId`, …) defined in `ai-dev.core/Models/Types/`. Each has:
+- Constructor validation (throws `ArgumentException` on bad input)
+- A companion `*JsonConverter` registered at the serializer level
+- `TryParse()` for safe deserialization
+
+Do not use raw `string` for any domain identifier. Add a new value type if one is missing.
+
+### Result pattern
+
+`Result<T>` (in `ai-dev.core/Models/Result.cs`) is used instead of exceptions for recoverable errors. Use `Result.Ok(value)` / `Result.Fail(reason)` and the extension methods in `ResultExtensions`. Do not throw from service methods that can legitimately fail.
+
+### Testing conventions
+
+- Framework: xUnit 3, Shouldly assertions, NSubstitute mocks.
+- All global usings are declared in `GlobalUsings.cs` — no per-file `using` for the standard set.
+- Tests use temp directories (`Path.GetTempPath() + Guid`) for any file I/O — never relative paths.
+- Value type tests follow the pattern in `AgentSlugTests.cs`: constructor validation, round-trip serialisation, equality, `TryParse`.

Directory.Build.props

@@ -0,0 +1,5 @@
+<Project>
+  <PropertyGroup>
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+  </PropertyGroup>
+</Project>

ai-dev-net.AppHost/AppHost.cs

@@ -1,16 +1,18 @@
 var builder = DistributedApplication.CreateBuilder(args);
 
-var workspaceRoot = Path.GetFullPath(Path.Combine(
-    AppContext.BaseDirectory,
-    "..",
-    "..",
-    "..",
-    "..",
-    "workspaces"));
+// WORKSPACE_ROOT must be set in the developer's environment to the managed project directory
+// (e.g. M:\ai-dev-net). The API and MCP will walk up from there to find .ai-dev/project.json.
+var workspaceRoot = Environment.GetEnvironmentVariable("WORKSPACE_ROOT")
+    ?? throw new InvalidOperationException(
+        "WORKSPACE_ROOT environment variable is not set. " +
+        "Set it to the managed project directory (e.g. M:\\ai-dev-net).");
 
 builder.AddProject<Projects.ai_dev_mcp>("ai-dev-mcp")
     .WithEnvironment("WORKSPACE_ROOT", workspaceRoot);
 
+builder.AddProject<Projects.ai_dev_api>("ai-dev-api")
+    .WithEnvironment("WORKSPACE_ROOT", workspaceRoot);
+
 builder.AddProject<Projects.ai_dev_ui_winui>("ai-dev-winui");
 
 builder.Build().Run();

ai-dev-net.AppHost/ai-dev-net.AppHost.csproj

@@ -11,6 +11,7 @@
   <ItemGroup>
     <ProjectReference Include="..\ai-dev.mcp\ai-dev.mcp.csproj" />
     <ProjectReference Include="..\ai-dev.ui.winui\ai-dev.ui.winui.csproj" />
+    <ProjectReference Include="..\ai-dev.api\ai-dev.api.csproj" />
   </ItemGroup>
 
 </Project>

ai-dev-net.slnx

@@ -40,6 +40,7 @@
   <Project Path="ai-dev-net.ServiceDefaults/ai-dev-net.ServiceDefaults.csproj" />
   <Project Path="ai-dev-net.tests.integration/ai-dev-net.tests.integration.csproj" />
   <Project Path="ai-dev-net.tests.unit/ai-dev-net.tests.unit.csproj" />
+  <Project Path="ai-dev.api/ai-dev.api.csproj" />
   <Project Path="ai-dev.core.local/ai-dev.core.local.csproj" />
   <Project Path="ai-dev.core/ai-dev.core.csproj" Id="c5884869-1690-4cc5-b2d5-fba00997cf78" />
   <Project Path="ai-dev.executor.anthropic/ai-dev.executor.anthropic.csproj" />

ai-dev-net.tests.integration/ConsistencyUiAndDetectionIntegrationTests.cs

@@ -12,6 +12,7 @@ namespace AiDevNet.Tests.Integration;
 public class ConsistencyUiAndDetectionIntegrationTests : IDisposable
 {
     private readonly string _rootPath;
+    private readonly ActiveWorkspaceHolder _holder;
     private readonly WorkspacePaths _paths;
     private readonly AtomicFileWriter _fileWriter = new();
     private readonly ProjectMutationCoordinator _coordinator = new();
@@ -20,7 +21,9 @@ public ConsistencyUiAndDetectionIntegrationTests()
     {
         _rootPath = Path.Combine(Path.GetTempPath(), $"consistency-ui-{Guid.NewGuid():N}");
         Directory.CreateDirectory(_rootPath);
-        _paths = new WorkspacePaths(new RootDir(_rootPath));
+        _holder = new ActiveWorkspaceHolder();
+        _holder.Activate(_rootPath);
+        _paths = _holder.Paths;
     }
 
     public void Dispose()
@@ -32,8 +35,8 @@ public void Dispose()
     [Fact]
     public async Task CheckProjectAsync_WhenRawBoardHasDuplicateTaskReference_ReportsRawFinding()
     {
-        var workspaceService = new WorkspaceService(_paths, _fileWriter);
-        workspaceService.CreateProject("demo-project", "Demo Project", null).ShouldBeOfType<Ok<Unit>>();
+        var workspaceService = new WorkspaceService(_holder, _fileWriter);
+        workspaceService.CreateProject(_rootPath, "demo-project", "Demo Project", null).ShouldBeOfType<Ok<Unit>>();
         var projectSlug = new ProjectSlug("demo-project");
         var boardPath = _paths.BoardPath(projectSlug);
         _fileWriter.WriteAllText(boardPath, "{\"columns\":[{\"id\":\"backlog\",\"title\":\"Backlog\",\"taskIds\":[\"task-1\"]},{\"id\":\"review\",\"title\":\"Review\",\"taskIds\":[\"task-1\"]}],\"tasks\":{\"task-1\":{\"id\":\"task-1\",\"title\":\"Investigate failure\",\"priority\":\"normal\"}}}");

ai-dev-net.tests.integration/ProductionReadinessIntegrationTests.cs

@@ -17,21 +17,28 @@ namespace AiDevNet.Tests.Integration;
 public class ProductionReadinessIntegrationTests : IDisposable
 {
     private readonly string _rootPath;
+    private readonly ActiveWorkspaceHolder _holder;
     private readonly WorkspacePaths _paths;
     private readonly AtomicFileWriter _fileWriter = new();
     private readonly ProjectMutationCoordinator _coordinator = new();
+    private readonly string _templatesDir;
 
     public ProductionReadinessIntegrationTests()
     {
         _rootPath = Path.Combine(Path.GetTempPath(), $"prod-ready-{Guid.NewGuid():N}");
         Directory.CreateDirectory(_rootPath);
-        _paths = new WorkspacePaths(new RootDir(_rootPath));
+        _holder = new ActiveWorkspaceHolder();
+        _holder.Activate(_rootPath);
+        _paths = _holder.Paths;
+        _templatesDir = Path.Combine(Path.GetTempPath(), $"templates-{Guid.NewGuid():N}");
     }
 
     public void Dispose()
     {
         if (Directory.Exists(_rootPath))
             Directory.Delete(_rootPath, recursive: true);
+        if (Directory.Exists(_templatesDir))
+            Directory.Delete(_templatesDir, recursive: true);
     }
 
     [Fact]
@@ -135,14 +142,14 @@ public void AtomicFileWriter_WhenOverwritingFile_ReplacesContent()
     [Fact]
     public void WorkspaceService_CreateProject_UsesAtomicWritesForArtifacts()
     {
-        var service = new WorkspaceService(_paths, _fileWriter);
+        var service = new WorkspaceService(_holder, _fileWriter);
 
-        var result = service.CreateProject("demo-project", "Demo Project", "Main app");
+        var result = service.CreateProject(_rootPath, "demo-project", "Demo Project", "Main app");
 
         result.ShouldBeOfType<Ok<Unit>>();
         File.Exists(_paths.ProjectJsonPath(new ProjectSlug("demo-project"))).ShouldBeTrue();
         File.Exists(_paths.BoardPath(new ProjectSlug("demo-project"))).ShouldBeTrue();
-        File.Exists(_paths.RegistryPath).ShouldBeTrue();
+        File.Exists(GlobalPaths.RegistryFile).ShouldBeTrue();
     }
 
     [Fact]
@@ -153,20 +160,19 @@ public void AgentService_CreateAgent_WritesFilesAtomically()
         modelRegistry.GetModelsForExecutor(Arg.Any<AgentExecutorName>()).Returns([]);
         var service = new AgentService(
             _paths,
-            new AgentTemplatesService(_paths),
+            new AgentTemplatesService(_templatesDir),
             _fileWriter,
             _coordinator,
             modelRegistry,
             NullLogger<AgentService>.Instance);
         var projectSlug = new ProjectSlug("demo-project");
-        var workspaceService = new WorkspaceService(_paths, _fileWriter);
-        workspaceService.CreateProject(projectSlug.Value, "Demo Project", null).ShouldBeOfType<Ok<Unit>>();
+        var workspaceService = new WorkspaceService(_holder, _fileWriter);
+        workspaceService.CreateProject(_rootPath, projectSlug.Value, "Demo Project", null).ShouldBeOfType<Ok<Unit>>();
 
-        var templateJsonPath = _paths.SafeTemplatePath("generic-standard", ".json")!;
-        var templateMdPath = _paths.SafeTemplatePath("generic-standard", ".md")!;
-        Directory.CreateDirectory(Path.GetDirectoryName(templateJsonPath.Value)!);
-        File.WriteAllText(templateJsonPath.Value, "{\"slug\":\"generic-standard\",\"name\":\"Generic\",\"role\":\"Implement features\",\"model\":\"sonnet\",\"description\":\"Generalist\",\"content\":\"\"}");
-        File.WriteAllText(templateMdPath.Value, "# Generic\n\nYou build features.");
+        Directory.CreateDirectory(_templatesDir);
+        File.WriteAllText(Path.Combine(_templatesDir, "generic-standard.json"),
+            "{\"slug\":\"generic-standard\",\"name\":\"Generic\",\"role\":\"Implement features\",\"model\":\"sonnet\",\"description\":\"Generalist\",\"content\":\"\"}");
+        File.WriteAllText(Path.Combine(_templatesDir, "generic-standard.md"), "# Generic\n\nYou build features.");
 
         var result = service.CreateAgent(projectSlug, "backend-dev", "Backend Dev", "generic-standard");
 
@@ -179,8 +185,8 @@ public void AgentService_CreateAgent_WritesFilesAtomically()
     public void KbAndPlaybookServices_SaveAtomically()
     {
         var projectSlug = new ProjectSlug("demo-project");
-        var workspaceService = new WorkspaceService(_paths, _fileWriter);
-        workspaceService.CreateProject(projectSlug.Value, "Demo Project", null).ShouldBeOfType<Ok<Unit>>();
+        var workspaceService = new WorkspaceService(_holder, _fileWriter);
+        workspaceService.CreateProject(_rootPath, projectSlug.Value, "Demo Project", null).ShouldBeOfType<Ok<Unit>>();
 
         var kbService = new KbService(_paths, _fileWriter, _coordinator);
         var playbookService = new PlaybookService(_paths, _fileWriter, _coordinator);