ssd-ai copilot-instructions.md

[byterover-mcp]

# GitHub Copilot instructions — ssd-ai (byterover MCP)

**Elevator pitch:** A TypeScript/Node.js collection of MCP server components and AI-assistant tools (memory, prompt, reasoning). Designed for testable, small utilities and extensible transport plugins.

**Tech stack:** TypeScript 5 (ES2022), Node.js, Vitest, Biome (formatter), Model Context Protocol (MCP).

## Required quick actions
- ALWAYS run `byterover-retrieve-knowledge` at the start of any non-trivial task.
- Run `byterover-store-knowledge` when you discover reusable patterns, fixes, or architecture rules.

## Quick repo orientation
- Entrypoint: `src/index.ts` — public exports for consumers.
- Main areas:
  - `src/lib/` — core domain libraries (ContextCompressor, MemoryManager, taskManager)
  - `src/tools/` — assistant tools (`prompt/`, `memory/`, `convention/`, `semantic/`, `thinking/`)
  - `src/transports/` — transport implementations (`http.ts`)
  - `src/__tests__/` — unit tests and fixtures (Vitest)
  - `docs/` — developer docs and server reference

## Build / Run / Test (copy-and-paste)
- Build: `npm run build` (runs `tsc`)
- Dev (stdio): `npm run dev:stdio` or `npm run dev` (use CLI flags: `--transport=stdio`)
- Start HTTP server: `npm run start:http` (script uses CLI flags: `--transport=http --port=3000 --hostname=localhost`)
- Run all tests: `npm run test` (Vitest)
- Run a single test file: `npx vitest run <path/to/testfile>` (example: `npx vitest run src/__tests__/taskManager.test.ts`)
- Type-check only: `tsc --noEmit`
- Format: `npx biome format --apply`
- Lint / checks: `npx biome check`

Notes: For Smithery compatibility add optional npm scripts to `package.json`:
- `dev:smithery`: `npx smithery dev` (interactive playground)
- `build:http`: `npx smithery build` (Smithery HTTP build)
- `start:http:smithery`: `node .smithery/index.cjs` (run the Smithery-built HTTP bundle)

## Automation & resources
- MCP inspector / runtime: use `npm run start:http` for integration testing of transports.
- Smithery notes: Export a default `createServer({ config })` function and an optional `configSchema` (zod) from `src/index.ts` for automatic Smithery HTTP deployments. Ensure `package.json` has a `module` field pointing to `src/index.ts` and consider adding `smithery` scripts (`dev:smithery`, `build:http`, `start:http:smithery`).
- Semantic helpers: `src/tools/semantic/findReferences.ts`, `findSymbol.ts` — use them before global renames.
- Look for scripts under `package.json` and `scripts/` (if present) for repo automation.

## Code & style conventions (repository-specific)
- Prefer explicit return types on exported functions and small focused functions.
- Filenames: `camelCase.ts`; exported types/classes: `PascalCase` (no `I` prefix).
- Avoid `any`; accept `unknown` and narrow.
- Error handling: prefer domain errors (e.g., `McpError`) and rethrow typed errors; use `instanceof Error` for message access.
- Logging: **no** `console.log` in library code; `console.error` only at entrypoints/failures.
- Naming & exports: prefer named exports; keep public API surface small and explicit.
- Scan for `TODO`/`HACK` comments — prefer documenting or creating issues for long-lived workarounds.

## Tests & PR checklist (must-do)
- Add unit tests in `src/__tests__/` for new/critical behavior; follow existing test patterns.
- If adding a public API, export it from `src/index.ts` and add tests and docs.
- Run: `tsc --noEmit`, `npm run test`, `npx biome format --apply`, `npx biome check` before creating a PR.
- Update `README.md` or `docs/` when changing contract or behavior; add changelog entry for user-facing changes.

## Semantic & navigation helpers
- Use `src/tools/semantic/*` to find references and symbols before renames.
- Search for `McpError`, `byterover-*`, `saveMemory`, `MemoryManager`, or `TODO` to find important patterns.

## Integration points & patterns to watch
- Memory tools: `src/tools/memory/*` implement session persistence and recall; add tests when changing behavior.