faceted-prompting CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

npm run build          # TypeScript compile (tsc) → dist/
npm run test           # Run all tests (vitest)
npm run test -- src/__tests__/compose.test.ts  # Run a single test file
npm run test:watch     # Watch mode
npm run lint           # ESLint on src/

Architecture

This is a TypeScript ESM library ("type": "module") that implements the Faceted Prompting pattern — structured prompt composition for LLMs. It is designed to be consumed as an npm package (faceted-prompting). All public API is re-exported from src/index.ts.

Core Concept: Facets

Prompts are decomposed into five facet kinds (FacetKind), each with a defined role and placement:

Facet	Placement	Purpose
Persona	System prompt	WHO — agent identity
Policy	User message	HOW — rules/standards
Knowledge	User message	WHAT TO KNOW — domain context
Instruction	User message	WHAT TO DO — the task
Output contracts	User message	HOW TO ANSWER — output/report format

Key Modules

• compose.ts — Core composition: takes a FacetSet + ComposeOptions → ComposedPrompt (systemPrompt + userMessage). Default user-message order is knowledge → instructions → output-contracts → policies. Policy and knowledge are truncated via truncation.ts when exceeding contextMaxChars.
• data-engine.ts — DataEngine interface for facet retrieval. FileDataEngine resolves {root}/{kind}/{key}.md. CompositeDataEngine chains engines with first-match-wins.
• resolve.ts — Facet reference resolution: resolves names/paths/inline content from candidate directories and section maps. Supports ~, ./, ../, / path prefixes and .md extension detection.
• scope.ts — @{owner}/{repo}/{facet-name} scope reference parsing/validation for repertoire packages.
• template.ts — Minimal template engine: {{variable}} substitution and {{#if var}}...{{else}}...{{/if}} conditionals (no nesting).
• truncation.ts — Trims content to char limit, appends truncation markers and source-path metadata.
• escape.ts — Escapes {} to full-width Unicode equivalents to prevent template injection.