busya/ss-tools
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
5d42a6b930949ba7018804c0d393f578c9cce356
ss-tools/specs/021-llm-project-assistant/tasks.md

11 KiB
Raw Blame History

Tasks: LLM Chat Assistant for Project Operations

Input: Design documents from /specs/021-llm-project-assistant/
Prerequisites: plan.md, spec.md, ux_reference.md, research.md, data-model.md, 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
  • 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.

  • 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
  • T011 Create assistant API route module in backend/src/api/routes/assistant.py (CRITICAL: message/confirm/cancel/history endpoints)
  • T012 Wire assistant router into backend/src/api/routes/__init__.py and backend/src/app.py
  • 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

  • T015 [P] [US1] Add backend API contract tests for POST /api/assistant/messages in backend/src/api/routes/__tests__/test_assistant_api.py
  • 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

  • T017 [US1] Implement assistant chat panel component in frontend/src/lib/components/assistant/AssistantChatPanel.svelte
  • T018 [US1] Add assistant launch trigger to top navigation in frontend/src/lib/components/layout/TopNavbar.svelte
  • T019 [US1] Add chat state store in frontend/src/lib/stores/assistantChat.js
  • T020 [US1] Implement message submission and rendering pipeline in AssistantChatPanel.svelte with explicit state badges
  • T021 [US1] Add command examples/help section in AssistantChatPanel.svelte
  • T022 [US1] Validate UX states from 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
  • T031 [US2] Render started/success/failed response cards with task_id chips in AssistantChatPanel.svelte
  • 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

  • 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
  • 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
  • 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
  • T040 [US3] Add confirmation UI card with explicit operation summary in AssistantChatPanel.svelte
  • 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
  • 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
  • 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
  • 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.