promptscript: Instructions file for Claude Code

CLAUDE.md

Project

You are an expert TypeScript developer working on PromptScript - a language and toolchain for standardizing AI instructions across enterprise organizations.

PromptScript compiles .prs files to native formats for GitHub Copilot, Claude Code, Cursor, and other AI tools.

You write clean, type-safe, and well-tested code following strict TypeScript practices.

Tech Stack

typescript, Node.js 20+, Nx + pnpm

Architecture

The project is organized as a monorepo with these packages:

flowchart TB
  subgraph packages
    core[core - Types, errors, utilities]
    parser[parser - Chevrotain-based parser]
    resolver[resolver - Inheritance & import resolution]
    validator[validator - AST validation rules]
    compiler[compiler - Pipeline orchestration]
    formatters[formatters - Output formatters]
    cli[cli - Command-line interface]
  end

  cli --> compiler
  cli --> resolver
  compiler --> resolver
  compiler --> validator
  compiler --> formatters
  resolver --> parser
  parser --> core
  resolver --> core
  validator --> core
  formatters --> core

Context

Key Libraries

• Parser: Chevrotain

• CLI: Commander.js

• Testing: Vitest

• Linting: ESLint + Prettier

• Project: PromptScript

Engineering Standards

• Use code-review-graph MCP tools BEFORE Grep/Glob/Read when exploring the codebase
• Exploring code: use semantic_search_nodes or query_graph instead of Grep
• Understanding impact: use get_impact_radius instead of manually tracing imports
• Code review: use detect_changes + get_review_context instead of reading entire files
• Finding relationships: use query_graph with callers_of/callees_of/imports_of/tests_for
• Architecture questions: use get_architecture_overview + list_communities
• Fall back to Grep/Glob/Read only when the graph does not cover what you need
• Strict mode enabled
• Never use any type - use unknown with type guards
• Use unknown with type guards instead of any
• Prefer interface for object shapes
• Use type for unions and intersections
• Named exports only, no default exports
• Explicit return types on public functions
• Files: kebab-case.ts
• Classes: PascalCase
• Interfaces: PascalCase
• Functions: camelCase
• Variables: camelCase
• Constants: UPPER_SNAKE_CASE
• Use custom error classes extending PSError
• Always include location information
• Provide actionable error messages
• Test files: *.spec.ts next to source
• Follow AAA (Arrange, Act, Assert) pattern
• Framework: Vitest
• Target >90% coverage for libraries
• Use fixtures for parser tests
• When refactoring formatter section methods (e.g. splitting context() into project() + techStack() + architecture()), add a test verifying that ALL input block content still appears in the output — not just the newly extracted subsections
• Golden files are snapshots of correct behavior, not correct by definition — before regenerating golden files, verify the diff represents an intentional change, not a regression that golden files would lock in
• keepInSync: when adding or changing block keywords (e.g. @knowledge, @guards), always update BOTH syntax highlighters: (1) TextMate grammar: apps/vscode/syntaxes/promptscript.tmLanguage.json (VS Code and the docs site via Shiki), (2) Playground Monaco language: packages/playground/src/utils/prs-language.ts
• branchStrategy: gitflow — branch from main, never commit to main
• newTask: follow the new-task workflow: branch, atomic commits, full verification pipeline, push, PR, watch CI
• prMonitoring: use gh pr checks --watch to monitor CI status; do not consider work done until all checks pass
• verification: follow the verify workflow after any code change - all eight steps, in order