Copilot instructions

1---
2applyTo: '**/*.tsx'
3description: Prompt-TSX coding guidelines
4---
5 
6Guidelines for TSX files using [prompt-tsx](https://github.com/microsoft/vscode-prompt-tsx) focusing on specific patterns and token budget management for AI prompt engineering.
7 
8## Component Structure
9 
10### Base Pattern
11- Extend `PromptElement<Props>` or `PromptElement<Props, State>` for all prompt components
12- Props interfaces must extend `BasePromptElementProps`
13 
14```tsx
15interface MyPromptProps extends BasePromptElementProps {
16	readonly userQuery: string;
17}
18 
19class MyPrompt extends PromptElement<MyPromptProps> {
20	render() {
21		return (
22			<>
23				<SystemMessage priority={1000}>...</SystemMessage>
24				<UserMessage priority={900}>{this.props.userQuery}</UserMessage>
25			</>
26		);
27	}
28}
29```
30 
31### Async Components
32- The `render` method can be async for components that need to perform async operations
33- All async work should be done directly in the `render` method
34 
35```tsx
36class FileContextPrompt extends PromptElement<FileContextProps> {
37	async render() {
38		const fileContent = await readFileAsync(this.props.filePath);
39		return (
40			<>
41				<SystemMessage priority={1000}>File content:</SystemMessage>
42				<UserMessage priority={900}>{fileContent}</UserMessage>
43			</>
44		);
45	}
46}
47```
48 
49## Prompt-Specific JSX
50 
51### Line Breaks
52- **CRITICAL**: Use `<br />` for line breaks - newlines are NOT preserved in JSX
53- Never rely on whitespace or string literal newlines
54 
55```tsx
56// ✅ Correct
57<SystemMessage>
58	You are an AI assistant.<br />
59	Follow these guidelines.<br />
60</SystemMessage>
61 
62// ❌ Wrong - newlines will be collapsed
63<SystemMessage>
64	You are an AI assistant.
65	Follow these guidelines.
66</SystemMessage>
67```
68 
69## Priority System
70 
71### Priority Values
72- Higher numbers = higher priority (like z-index)
73- Use consistent ranges:
74  - System messages: 1000
75  - User queries: 900
76  - Recent history: 700-800
77  - Context/attachments: 600-700
78  - Background info: 0-500
79 
80```tsx
81<SystemMessage priority={1000}>...</SystemMessage>
82<UserMessage priority={900}>{query}</UserMessage>
83<HistoryMessages priority={700} />
84<ContextualData priority={500} />
85```
86 
87### Flex Properties for Token Budget
88- `flexGrow={1}` - expand to fill remaining token space
89- `flexReserve` - reserve tokens before rendering
90- `passPriority` - pass-through containers that don't affect child priorities
91 
92```tsx
93<FileContext priority={70} flexGrow={1} files={this.props.files} />
94<History passPriority older={0} newer={80} flexGrow={2} flexReserve="/5" />
95```
96 
97## Content Handling
98 
99### TextChunk for Truncation
100- Use `TextChunk` for content that may exceed token budget
101- Set `breakOn` patterns for intelligent truncation
102 
103```tsx
104<TextChunk breakOnWhitespace priority={100}>
105	{longUserQuery}
106</TextChunk>
107 
108<TextChunk breakOn=" " priority={80}>
109	{documentContent}
110</TextChunk>
111```
112 
113### Tag Component for Structured Content
114- Use `Tag` for XML-like structured content with attributes
115- Validates tag names and properly formats attributes
116 
117```tsx
118<Tag name="attachments" attrs={{ id: variableName, type: "file" }}>
119	{content}
120</Tag>
121```
122 
123## References and Metadata
124 
125### Prompt References
126- Use `<references>` for tracking variable usage
127- Use `<meta>` for metadata that survives pruning
128 
129```tsx
130<references value={[new PromptReference({ variableName })]} />
131<meta value={new ToolResultMetadata(id, result)} />
132```
133 
134### Keep-With Pattern
135- Use `useKeepWith()` for content that should be pruned together
136 
137```tsx
138const KeepWith = useKeepWith();
139return (
140	<>
141		<KeepWith priority={2}>
142			<ToolCallRequest>...</ToolCallRequest>
143		</KeepWith>
144		<KeepWith priority={1}>
145			<ToolCallResponse>...</ToolCallResponse>
146		</KeepWith>
147	</>
148);
149```
150 
151## Token Budget Management
152 
153### Sizing-Aware Rendering
154- Use `PromptSizing` parameter for budget-aware content generation
155- Implement cooperative token usage
156 
157```tsx
158async render(sizing: PromptSizing): Promise<PromptPiece> {
159	const content = await this.generateContent(sizing.tokenBudget);
160	return <>{content}</>;
161}
162```
163 
164### Performance
165- Avoid expensive work in `render` methods when possible
166- Cache computations when appropriate
167- Use async `render` for all async operations
168