# Implementation Plan: LLM Chat Assistant for Project Operations

**Branch**: `021-llm-project-assistant` | **Date**: 2026-02-23 | **Spec**: [`/home/busya/dev/ss-tools/specs/021-llm-project-assistant/spec.md`](specs/021-llm-project-assistant/spec.md)  
**Input**: Feature specification from [`/specs/021-llm-project-assistant/spec.md`](specs/021-llm-project-assistant/spec.md)

## Summary

Implement an embedded LLM chat assistant that accepts natural-language commands and orchestrates existing `ss-tools` operations across Git, migration/backup, LLM analysis/documentation, and task status flows. The design reuses current backend routes/plugins and task manager, adds intent parsing + safe dispatch layer, enforces existing RBAC checks, and introduces explicit confirmation workflow for risky operations (especially production deploy).

## Technical Context

**Language/Version**: Python 3.9+ (backend), Node.js 18+ (frontend)  
**Primary Dependencies**: FastAPI, existing TaskManager, existing plugin routes/services, SvelteKit chat UI components, configured LLM providers  
**Storage**: Existing DB for auth/tasks/config + new assistant command audit persistence (same backend DB stack)  
**Testing**: pytest (backend), Vitest (frontend), API contract tests for assistant endpoints  
**Target Platform**: Linux backend + browser SPA frontend  
**Project Type**: Web application (backend + frontend)  
**Performance Goals**: Parse/dispatch response under 2s p95 (excluding async task runtime); confirmation round-trip under 1s p95  
**Constraints**: Must not bypass existing permissions; dangerous ops require explicit confirmation; must reuse existing task progress surfaces (Task Drawer/reports)  
**Scale/Scope**: Multi-command operational assistant used by authenticated operators; daily command volume expected in hundreds to low thousands

## Constitution Check

*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

| Gate | Status | Notes |
|---|---|---|
| Semantic Protocol Compliance ([`constitution.md`](.ai/standards/constitution.md)) | PASS | Contracts will define assistant modules with DEF tags and PRE/POST semantics. |
| Plugin/Service Boundaries | PASS | Assistant dispatch layer will call existing routes/services/plugins only; no direct bypass logic. |
| Security & RBAC | PASS | Command dispatch requires existing `has_permission` checks and user context propagation. |
| Async Task Architecture | PASS | Long-running operations stay task-based; assistant returns `task_id` immediately. |
| UX Consistency | PASS | Chat states map to explicit UX states (`needs_confirmation`, `started`, `failed`, etc.). |
| Auditability | PASS | Assistant command audit log added as mandatory trail for execution decisions. |

## Project Structure

### Documentation (this feature)

```text
specs/021-llm-project-assistant/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── ux_reference.md
├── contracts/
│   ├── modules.md
│   └── assistant-api.openapi.yaml
├── checklists/
│   └── requirements.md
└── tasks.md
```

### Source Code (repository root)

```text
backend/
├── src/
│   ├── api/
│   │   └── routes/
│   ├── services/
│   ├── models/
│   └── core/
└── tests/

frontend/
├── src/
│   ├── lib/
│   │   ├── components/
│   │   ├── stores/
│   │   └── api/
│   └── routes/
└── tests/
```

**Structure Decision**: Keep current backend/frontend split and implement assistant as a new bounded feature slice (assistant API route + intent/dispatch service + chat UI components) that integrates into existing auth/task/report ecosystems.

## Phase 0: Research Focus

1. Intent parsing strategy for RU/EN operational commands with deterministic fallback behavior.
2. Risk classification strategy for commands requiring explicit confirmation (e.g., prod deploy, prod migration).
3. Integration mapping from intents to existing operational endpoints/plugins.
4. Confirmation token lifecycle and idempotency guarantees.
5. Audit logging schema and retention alignment with task/audit expectations.

## Phase 1: Design & Contracts Plan

1. Define canonical assistant interaction model (`message -> intent -> decision -> dispatch/result`).
2. Produce [`data-model.md`](specs/021-llm-project-assistant/data-model.md) for message, intent, confirmation, and audit entities.
3. Produce module contracts in [`contracts/modules.md`](specs/021-llm-project-assistant/contracts/modules.md) with PRE/POST + UX states.
4. Produce API contract in [`contracts/assistant-api.openapi.yaml`](specs/021-llm-project-assistant/contracts/assistant-api.openapi.yaml).
5. Produce [`quickstart.md`](specs/021-llm-project-assistant/quickstart.md) with validation flow.
6. Decompose to execution tasks in [`tasks.md`](specs/021-llm-project-assistant/tasks.md) by user stories.

## Complexity Tracking

No constitution violations identified.

## Test Data Reference

| Component | TIER | Fixture Name | Location |
|---|---|---|---|
| Assistant intent parsing | CRITICAL | assistant_command_git_branch | [`spec.md`](specs/021-llm-project-assistant/spec.md) |
| Dangerous operation confirmation | CRITICAL | assistant_command_prod_deploy_confirmation | [`spec.md`](specs/021-llm-project-assistant/spec.md) |
| Task status query resolution | STANDARD | assistant_status_query | [`spec.md`](specs/021-llm-project-assistant/spec.md) |

**Note**: Tester implementation should materialize these fixtures in backend/frontend test suites during `/speckit.tasks` execution.