ssd-ai: Instructions file for Codex

AGENTS.md — Guidance for automated coding agents

Build / Run / Test commands

• 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 passes CLI flags --transport=http --port=3000 --hostname=localhost)
• Run all tests: npm run test (uses Vitest)
• Run single test file: npx vitest run <path/to/testfile> or npm run test -- <path/to/testfile> (example: npx vitest run src/__tests__/taskManager.test.ts)
• Watch tests: npm run test:watch; UI: npm run test:ui; Coverage: npm run test:coverage
• Type-check only: tsc --noEmit
• Lint/format: npx biome check and npx biome format (use npx biome format --apply to rewrite files)

Code style & conventions (follow existing code style)

• Formatting: use Biome as source of truth (single quotes, semicolons, consistent spacing).
• Imports: external packages first, blank line, internal modules, then relative imports; keep grouped and minimal deep relative paths.
• Filenames: use camelCase for .ts files (match existing code like MemoryManager.ts).
• Naming: camelCase for variables/functions, PascalCase for types/classes/interfaces (no I prefix).
• Types: prefer explicit return types on exported functions, avoid any — use unknown for untrusted input and narrow/cast.
• Error handling: catch errors, prefer domain errors (e.g. McpError) and rethrow typed errors; use instanceof Error when reading message.
• Logging: avoid console.log in library code; use console.error only for entrypoints and failures.

Repo rules

• Copilot: see .github/copilot-instructions.md (present, currently empty) — respect project privacy and review suggestions.
• Cursor rules: no .cursor or .cursorrules found in repository.

If you need me to run tests, lint, or adjust these rules, tell me which command to run.

src/ — Source layout & conventions

Overview

• src/ is the main TypeScript source tree; entry point is src/index.ts. It contains core libraries, helpers, transports, shared types, and unit tests.

Directory breakdown

• src/index.ts — public exports/entrypoint
• src/lib/ — core domain libraries & services (ContextCompressor.ts, MemoryManager.ts, ProjectCache.ts, PythonParser.ts, taskManager.ts)
• src/tools/browser/ — Browser automation and inspection tools (browserUtils.ts: general browser utilities, inspectNetworkRequests.ts: monitors HTTP requests, monitorConsoleLogs.ts: captures console output for debugging)
• src/tools/convention/ — Code quality and convention enforcement (analyzeComplexity.ts: measures code complexity, applyQualityRules.ts: applies coding standards, checkCouplingCohesion.ts: analyzes module dependencies, getCodingGuide.ts: retrieves coding guidelines, suggestImprovements.ts: proposes code enhancements, validateCodeQuality.ts: checks code against quality metrics)
• src/tools/memory/ — Session and context memory management (autoSaveContext.ts: automatically saves session state, deleteMemory.ts: removes stored memories, listMemories.ts: displays saved memories, prioritizeMemory.ts: ranks memories by importance, recallMemory.ts: retrieves specific memories, restoreSessionContext.ts: restores previous sessions, saveMemory.ts: stores new memories, searchMemories.ts: queries stored memories, startSession.ts: initializes memory sessions, updateMemory.ts: modifies existing memories)
• src/tools/planning/ — Project planning and requirements analysis (analyzeRequirements.ts: breaks down project needs, createUserStories.ts: generates user stories, featureRoadmap.ts: creates development roadmaps, generatePrd.ts: produces product requirement documents)
• src/tools/prompt/ — AI prompt analysis and enhancement tools (analyzePrompt.ts: evaluates prompt effectiveness, browserDevelopment.ts: aids in browser-related prompts, codeConventions.ts: enforces prompt coding standards, codeReview.ts: assists with code review prompts, debugAssistant.ts: helps with debugging prompts, documentation.ts: improves documentation prompts, enhancePrompt.ts: refines prompts for better AI responses, enhancePromptGemini.ts: Gemini-specific prompt enhancements, memoryManagement.ts: manages prompt memory, projectPlanning.ts: supports planning prompts, promptEnhancement.ts: general prompt improvement, reasoningFramework.ts: applies reasoning to prompts, semanticAnalysis.ts: analyzes prompt semantics, sequentialThinking.ts: enables step-by-step prompt processing, specGeneration.ts: generates specifications from prompts, testing.ts: aids in testing prompts, timeUtilities.ts: handles time-related prompts, uiPreview.ts: previews UI from prompts)
• src/tools/reasoning/ — Reasoning framework application (applyReasoningFramework.ts: implements structured reasoning processes)
• src/tools/resources/ — Resource and capability management (capabilities.ts: defines system capabilities, readme.ts: handles README generation)
• src/tools/semantic/ — Code semantic analysis (findReferences.ts: locates code references, findSymbol.ts: searches for symbols, README.md: documentation for semantic tools)
• src/tools/thinking/ — Problem-solving and thinking aids (analyzeProblem.ts: breaks down problems, breakDownProblem.ts: decomposes complex issues, createThinkingChain.ts: builds reasoning chains, formatAsPlan.ts: structures thoughts as plans, stepByStepAnalysis.ts: provides incremental analysis, thinkAloudProcess.ts: simulates thinking aloud)
• src/tools/time/ — Time-related utilities (getCurrentTime.ts: retrieves current time)
• src/tools/ui/ — User interface preview tools (previewUiAscii.ts: renders UI in ASCII format)
• src/transports/ — transport implementations (http.ts)
• src/types/ — shared DTOs and type definitions (pagination.ts, prompt.ts, resource.ts, task.ts, tool.ts)
• src/tests/ — unit tests (taskManager.test.ts, pagination.test.ts)