# Tasks: LLM Chat Assistant for Project Operations **Input**: Design documents from [`/specs/021-llm-project-assistant/`](specs/021-llm-project-assistant) **Prerequisites**: [`plan.md`](specs/021-llm-project-assistant/plan.md), [`spec.md`](specs/021-llm-project-assistant/spec.md), [`ux_reference.md`](specs/021-llm-project-assistant/ux_reference.md), [`research.md`](specs/021-llm-project-assistant/research.md), [`data-model.md`](specs/021-llm-project-assistant/data-model.md), [`contracts/`](specs/021-llm-project-assistant/contracts) **Tests**: Include backend contract/integration tests and frontend integration/state tests. **Organization**: Tasks are grouped by user story for independent implementation and validation. ## Format: `[ID] [P?] [Story] Description` --- ## Phase 1: Setup (Shared Infrastructure) **Purpose**: Prepare assistant feature scaffolding and fixtures. - [ ] T001 Create assistant feature folders in `backend/src/services/assistant/`, `frontend/src/lib/components/assistant/`, `frontend/src/lib/api/assistant.js` - [ ] T002 [P] Add backend fixtures for assistant parsing/confirmation in `backend/tests/fixtures/assistant/fixtures_assistant.json` - [ ] T003 [P] Add frontend fixtures for assistant response states in `frontend/src/lib/components/assistant/__tests__/fixtures/assistant.fixtures.js` - [x] T004 [P] Add i18n placeholders for assistant UI in `frontend/src/lib/i18n/locales/en.json` and `frontend/src/lib/i18n/locales/ru.json` --- ## Phase 2: Foundational (Blocking Prerequisites) **Purpose**: Build core assistant architecture required by all stories. - [x] T005 Implement assistant domain models (`AssistantMessage`, `CommandIntent`, `ConfirmationToken`, `AssistantExecutionLog`) in `backend/src/models/assistant.py` - [ ] T006 [P] Implement intent parser service with confidence output in `backend/src/services/assistant/intent_parser.py` - [ ] T007 Implement RBAC + risk guard service in `backend/src/services/assistant/security_guard.py` - [ ] T008 Implement execution adapter to existing operations in `backend/src/services/assistant/execution_adapter.py` - [ ] T009 Implement assistant orchestrator service in `backend/src/services/assistant/orchestrator.py` - [ ] T010 [P] Implement assistant audit logging service/repository in `backend/src/services/assistant/audit_service.py` - [x] T011 Create assistant API route module in `backend/src/api/routes/assistant.py` (CRITICAL: message/confirm/cancel/history endpoints) - [x] T012 Wire assistant router into `backend/src/api/routes/__init__.py` and `backend/src/app.py` - [x] T013 Create frontend assistant API client in `frontend/src/lib/api/assistant.js` - [ ] T014 Verify contracts alignment between `spec.md` and `contracts/modules.md` **Checkpoint**: Foundation complete; user stories can begin. --- ## Phase 3: User Story 1 - Use chat instead of manual UI navigation (Priority: P1) 🎯 MVP **Goal**: Add in-app assistant chat interface with working request/response loop. **Independent Test**: Open assistant panel and complete one command-response interaction. ### Tests for User Story 1 - [x] T015 [P] [US1] Add backend API contract tests for `POST /api/assistant/messages` in `backend/src/api/routes/__tests__/test_assistant_api.py` - [x] T016 [P] [US1] Add frontend integration test for chat panel interaction in `frontend/src/lib/components/assistant/__tests__/assistant_chat.integration.test.js` ### Implementation for User Story 1 - [x] T017 [US1] Implement assistant chat panel component in `frontend/src/lib/components/assistant/AssistantChatPanel.svelte` - [x] T018 [US1] Add assistant launch trigger to top navigation in `frontend/src/lib/components/layout/TopNavbar.svelte` - [x] T019 [US1] Add chat state store in `frontend/src/lib/stores/assistantChat.js` - [x] T020 [US1] Implement message submission and rendering pipeline in `AssistantChatPanel.svelte` with explicit state badges - [x] T021 [US1] Add command examples/help section in `AssistantChatPanel.svelte` - [x] T022 [US1] Validate UX states from [`ux_reference.md`](specs/021-llm-project-assistant/ux_reference.md) **Checkpoint**: US1 independently functional and demo-ready. --- ## Phase 4: User Story 2 - Execute core operations via natural-language commands (Priority: P1) **Goal**: Support command parsing and dispatch for Git/migration/backup/LLM/status operations. **Independent Test**: One command per domain executes correct backend path or returns valid error. ### Tests for User Story 2 - [ ] T023 [P] [US2] Add parser tests for RU/EN command variants in `backend/src/services/assistant/__tests__/test_intent_parser.py` - [ ] T024 [P] [US2] Add execution adapter integration tests in `backend/src/services/assistant/__tests__/test_execution_adapter.py` - [ ] T025 [P] [US2] Add frontend state tests for command result rendering in `frontend/src/lib/components/assistant/__tests__/assistant_states.test.js` ### Implementation for User Story 2 - [ ] T026 [US2] Implement Git command mappings in `execution_adapter.py` (create branch, commit, deploy) - [ ] T027 [US2] Implement migration/backup command mappings in `execution_adapter.py` via existing task creation - [ ] T028 [US2] Implement LLM validation/documentation command mappings in `execution_adapter.py` - [ ] T029 [US2] Implement task/report status query mappings in `execution_adapter.py` - [ ] T030 [US2] Implement confidence gate and clarification responses in `orchestrator.py` - [x] T031 [US2] Render started/success/failed response cards with `task_id` chips in `AssistantChatPanel.svelte` - [x] T032 [US2] Add quick action from `task_id` chip to Task Drawer in `frontend/src/lib/stores/taskDrawer.js` integration points **Checkpoint**: US2 independently functional across requested command domains. --- ## Phase 5: User Story 3 - Safe execution with RBAC and explicit confirmations (Priority: P1) **Goal**: Enforce permissions and confirmation gates for dangerous operations. **Independent Test**: Unauthorized command denied; production deploy requires confirm and executes only after confirm. ### Tests for User Story 3 - [x] T033 [P] [US3] Add backend authorization tests in `backend/src/api/routes/__tests__/test_assistant_authz.py` - [ ] T034 [P] [US3] Add backend confirmation lifecycle tests in `backend/src/services/assistant/__tests__/test_confirmation_flow.py` - [x] T035 [P] [US3] Add frontend confirm/cancel UX tests in `frontend/src/lib/components/assistant/__tests__/assistant_confirmation.integration.test.js` ### Implementation for User Story 3 - [ ] T036 [US3] Implement risk policy matrix in `backend/src/services/assistant/risk_policy.py` - [ ] T037 [US3] Implement confirmation token storage/service in `backend/src/services/assistant/confirmation_service.py` - [x] T038 [US3] Implement confirm/cancel endpoints in `backend/src/api/routes/assistant.py` - [ ] T039 [US3] Enforce one-time token consumption and TTL checks in `confirmation_service.py` - [x] T040 [US3] Add confirmation UI card with explicit operation summary in `AssistantChatPanel.svelte` - [x] T041 [US3] Surface `denied` and `needs_confirmation` assistant states consistently in UI **Checkpoint**: US3 independently functional with enforced safety controls. --- ## Phase 6: User Story 4 - Reliable feedback and progress tracking (Priority: P2) **Goal**: Provide immediate task start feedback and robust status/report follow-up. **Independent Test**: Long operation returns `task_id` immediately and can be tracked via Task Drawer/reports. ### Tests for User Story 4 - [ ] T042 [P] [US4] Add backend tests for started response payload and task linkage in `backend/src/api/routes/__tests__/test_assistant_task_feedback.py` - [ ] T043 [P] [US4] Add frontend integration tests for tracking links/actions in `frontend/src/lib/components/assistant/__tests__/assistant_tracking.integration.test.js` ### Implementation for User Story 4 - [ ] T044 [US4] Add response formatter service for consistent assistant states in `backend/src/services/assistant/response_formatter.py` - [x] T045 [US4] Implement history endpoint pagination in `backend/src/api/routes/assistant.py` - [ ] T046 [US4] Implement history loading and pagination in `frontend/src/lib/stores/assistantChat.js` - [x] T047 [US4] Add open-reports quick action for completed/failed tasks in `AssistantChatPanel.svelte` - [ ] T048 [US4] Add structured error mapping and user guidance messages in `response_formatter.py` and frontend render logic **Checkpoint**: US4 independently functional with complete feedback loop. --- ## Phase 7: Polish & Cross-Cutting Concerns **Purpose**: Final quality, compliance, and operational readiness. - [ ] T049 [P] Add OpenAPI conformance tests against `specs/021-llm-project-assistant/contracts/assistant-api.openapi.yaml` in `backend/src/api/routes/__tests__/test_assistant_openapi_conformance.py` - [ ] T050 [P] Add audit log persistence tests in `backend/src/services/assistant/__tests__/test_audit_service.py` - [ ] T051 [P] Add frontend performance tests for chat rendering with long history in `frontend/src/lib/components/assistant/__tests__/assistant_performance.test.js` - [ ] T052 Update operational docs in `docs/settings.md` and `README.md` for assistant usage and safety confirmations - [x] T053 Run quickstart validation and record results in `specs/021-llm-project-assistant/quickstart.md` - [ ] T054 Run semantic map generation (`python3 generate_semantic_map.py`) and resolve critical issues in assistant modules --- ## Dependencies & Execution Order ### Phase Dependencies - Phase 1 has no dependencies. - Phase 2 depends on Phase 1 and blocks all user stories. - Phases 3-6 depend on Phase 2. - Phase 7 depends on completion of selected user stories. ### User Story Dependency Graph - **US1 (P1)**: MVP chat entrypoint. - **US2 (P1)**: Command execution capabilities. - **US3 (P1)**: Safety and security controls. - **US4 (P2)**: Feedback and tracking depth. Graph: `US1 -> {US2, US3} -> US4` ### Parallel Opportunities - Setup fixture/i18n tasks: T002, T003, T004. - Foundational tasks: T006/T010 can run in parallel after T005 baseline. - Story tests in each phase marked `[P]` can run in parallel. - US2 domain mappings (T026-T029) can be split across developers. --- ## Implementation Strategy ### MVP First (Recommended) 1. Complete Phase 1 + Phase 2. 2. Complete Phase 3 (US1). 3. Complete minimal subset of US2 for one domain (e.g., migration + status) and validate. ### Incremental Delivery 1. Deliver US1 chat shell. 2. Add US2 command domains iteratively. 3. Add US3 confirmation and RBAC hardening. 4. Add US4 history/tracking refinements. 5. Finish Phase 7 compliance and docs. ### UX Preservation Rule No task should degrade clarity or safety defined in [`ux_reference.md`](specs/021-llm-project-assistant/ux_reference.md).