stim: Instructions file for Codex

AGENTS.md

Instructions for AI coding agents (Claude Code, Cursor, Copilot, etc.) working in this repository.

What this project is

Stim is a DSL for writing AI prompts — slash commands, agent personas, and reusable orchestration harnesses — that compiles to whatever AI tool you target (Claude Code, ChatGPT, Cursor). You write one .stim file; stim parses it, resolves imports and file-references, and emits tool-specific markdown.

It is a compiler, not a runtime. Nothing in .stim "runs" — it compiles to natural-language instructions that an AI tool then interprets.

• Language: TypeScript, run on Bun (not Node).
• Output: a single compiled binary (dist/stim), no runtime dependency.
• Source of truth for the language: docs/Syntax-Reference.md and src/types/index.ts (the AST).

Build, test, run

bun install                      # install deps
bun run dev -- <args>            # run the CLI from source (e.g. bun run dev -- compile f.stim)
bun run build                    # compile single binary → dist/stim
bun run build:all                # cross-platform binaries (scripts/build-all.sh)
bun test                         # full suite (tests/, bun:test) — 300 tests
bun test tests/parser.test.ts    # one file
bun test -t "parses tools"       # tests matching a name

There is no lint or format script and no CI test gate beyond the release workflow. Run bun test yourself before claiming a change works. tsconfig.json is noEmit + strict; type errors surface through bun / the editor, not a build step.

The release workflow is .github/workflows/release.yml (tag-triggered cross-platform build + GitHub release). Do not touch it without being asked.

Repository layout

src/
  main.ts            entry point — calls cli/
  cli/               argument parsing, `compile` subcommand, --lsp dispatch, file I/O
  parser/            .stim source → AST (Declaration)         [PURE]
  resolve/           inline task("file.stim") + parallel bodies [I/O: reads files]
  imports/           resolve `import "x.stim"` → variable scope [I/O: reads files]
  optimize/          AST → AST optimize/sanitize passes + normalizeOutput, opt-in [PURE]
  compiler/          AST → natural-language markdown prompt body, shared by all targets [PURE]
  targets/           one adapter per AI tool
    index.ts         Target type, registry, getTarget, extractFlags, warnDropped
    claude/ chatgpt/ cursor/
  install/           `install` subcommand + bundle install
  add/ remove/ update/   package-manager subcommands
  tokens/            `tokens` subcommand — heuristic token estimator [countTokens is PURE]
  registry/          GitHub package fetching (parseSource, fetchManifest, fetchStimFile)
  lockfile/          stim.lock read/write
  types/             AST type definitions — the contract everything shares
lsp/                 Language Server (diagnostics, completion, hover, symbols, highlighting)
packages/            first-party packages (reviews, gitflow, planning, writing) — each has stim.yaml
engine/              meta-workflow .stim files (annotated commands + topology fragments)
examples/            ready-to-use .stim files (commands and agents)
plugins/             editor integrations: vscode, neovim, zed
docs/                documentation (see "Docs map" below)
tests/               bun:test suite, one file per concern