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

Quickstart: LLM Chat Assistant for Project Operations

Purpose

Implement and validate assistant-driven project operations defined in:

• Spec: spec.md
• UX reference: ux_reference.md
• Plan: plan.md
• Data model: data-model.md
• Contracts: contracts/modules.md, contracts/assistant-api.openapi.yaml

1) Backend implementation flow

1. Add assistant route module (/api/assistant/*).
2. Implement intent parser service (hybrid deterministic + LLM fallback).
3. Implement security guard and confirmation token workflow.
4. Implement execution adapter mapping intents to existing Git/migration/backup/LLM/tasks operations.
5. Add structured assistant audit logging.

2) Frontend implementation flow

1. Add assistant chat panel component and open/close controls in main layout.
2. Add assistant API client using existing frontend API wrapper.
3. Render assistant response states (needs_confirmation, started, denied, etc.).
4. Add confirm/cancel actions and task tracking chips linking to Task Drawer/reports.
5. Add i18n keys for RU/EN assistant labels and status texts.

3) Safety checks (must pass)

• Unauthorized command execution is denied.
• Dangerous operations require confirmation and do not auto-run.
• Expired/cancelled confirmation never executes.
• Confirm endpoint is idempotent (single execution).

4) UX conformance checks (must pass)

• Chat interaction available in app shell.
• Immediate "started" response with task_id for long jobs.
• Clear clarification prompt on ambiguous commands.
• Clear error text and recovery guidance on failed dispatch.

5) Contract checks (must pass)

• Assistant endpoints conform to assistant-api.openapi.yaml.
• Response states always included and valid enum values.
• Confirmation flow returns deterministic machine-readable output.

6) Suggested validation commands

Backend tests:

cd backend && .venv/bin/python3 -m pytest

Frontend tests:

cd frontend && npm test

Targeted assistant tests (when implemented):

cd backend && .venv/bin/python3 -m pytest tests -k assistant
cd frontend && npm test -- assistant

7) Done criteria for planning handoff

• All planning artifacts for 021 exist and are mutually consistent.
• Risk confirmation and RBAC enforcement are explicit in spec and contracts.
• Task-tracking integration through existing Task Drawer/reports is reflected in contracts and tasks.
• Ready for implementation via tasks.md.

8) Validation Log (2026-02-23)

Frontend

• cd frontend && npx vitest run src/lib/components/assistant/__tests__/assistant_chat.integration.test.js src/lib/components/assistant/__tests__/assistant_confirmation.integration.test.js src/lib/stores/__tests__/assistantChat.test.js
  • Result: PASS (11 passed)
• cd frontend && npm run build
  • Result: PASS (build successful; project has pre-existing non-blocking a11y warnings outside assistant scope)

Backend

• python3 -m py_compile backend/src/api/routes/assistant.py backend/src/models/assistant.py backend/src/api/routes/__tests__/test_assistant_api.py backend/src/api/routes/__tests__/test_assistant_authz.py
  • Result: PASS
• cd backend && .venv/bin/python -m pytest -q src/api/routes/__tests__/test_assistant_api.py src/api/routes/__tests__/test_assistant_authz.py
  • Result: BLOCKED in current env (runtime hang during request execution after heavy app bootstrap; collection succeeds)

Semantics

• python3 generate_semantic_map.py
  • Result: PASS (updated semantic artifacts: .ai/PROJECT_MAP.md, .ai/MODULE_MAP.md, semantics/semantic_map.json)