108 lines
5.5 KiB
Markdown
108 lines
5.5 KiB
Markdown
# 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.
|