systematic: Instructions file for GitHub Copilot

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[]> { ... }

// ✅ Do: let Zod schema builders infer their return type
export function createConfigSchema(opts: Options) {
  return z.object({ ... })
}

// ❌ Don't: annotate a schema builder's return type — it erases the parsed shape
export function createConfigSchema(opts: Options): z.ZodObject<z.core.$ZodLooseShape> { ... }

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