systematic copilot-instructions.md

Copilot Instructions for Systematic

Read AGENTS.md at the repository root before writing any code. It is the canonical source for project structure, conventions, and command reference.

Stack

• Runtime: Bun (not Node.js, not Deno)
• Language: TypeScript 5.7+ with strict: true
• Modules: ESM only ("type": "module" in package.json)
• Linter: Biome — not ESLint, not Prettier
• Tests: bun:test with describe/it — not Jest, not Vitest
• Package manager: Bun — not npm, not pnpm, not yarn

Verification Commands

Run these before marking work complete:

bun run build        # Build to dist/
bun run typecheck    # TypeScript strict mode
bun run lint         # Biome linter
bun test             # Unit and integration tests

All four must pass. Do not skip any.

Do / Don't

Imports

// ✅ Do: node: protocol for builtins
import { readFile } from 'node:fs/promises'
import { join } from 'node:path'

// ✅ Do: .js extension on relative imports (ESM requirement)
import { parseFrontmatter } from './frontmatter.js'

// ✅ Do: import type for type-only imports
import type { SkillConfig } from './types.js'

// ❌ Don't: bare builtin imports
import { readFile } from 'fs/promises'

// ❌ Don't: missing .js extension
import { parseFrontmatter } from './frontmatter'

Type Safety

// ✅ Do: unknown + type guards
function processInput(value: unknown): string {
  if (typeof value !== 'string') {
    throw new TypeError(`Expected string, got ${typeof value}`)
  }
  return value
}

// ✅ Do: explicit return types on exports
export function findSkills(dir: string): Promise<SkillDefinition[]> { ... }

// ❌ Don't: any, @ts-ignore, @ts-expect-error, non-null assertions (!)
function processInput(value: any) { ... }
// @ts-ignore
someCall()!

Architecture

// ✅ Do: functions — this codebase has zero classes
export function createHandler(config: Config): Handler { ... }

// ❌ Don't: classes
class Handler { ... }