ss-tools/specs/021-llm-project-assistant/plan.md

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
Input: Feature specification from /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)	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)

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)

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 for message, intent, confirmation, and audit entities.
3. Produce module contracts in contracts/modules.md with PRE/POST + UX states.
4. Produce API contract in contracts/assistant-api.openapi.yaml.
5. Produce quickstart.md with validation flow.
6. Decompose to execution tasks in 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
Dangerous operation confirmation	CRITICAL	assistant_command_prod_deploy_confirmation	spec.md
Task status query resolution	STANDARD	assistant_status_query	spec.md

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