Adding Tracks Support

How to implement Agent Tracks support in your AI client.

Overview

Adding tracks support to your client involves three phases:

1. Discovery: Load track metadata at startup
2. Activation: Load full instructions when relevant
3. Execution: Follow instructions and optionally run scripts

Phase 1: Discovery

At startup, scan for TRACK.md files in:

• .haijun/tracks/ in the project root
• User-level tracks directory (~/.config/haijun/tracks/)
• Any directories configured by the user

Parse only the YAML frontmatter to extract name and description. Store these in memory for quick lookup.

Phase 2: Activation

When a user sends a message, compare the task against available track descriptions. Use semantic similarity or keyword matching to determine relevance. When a track matches:

1. Read the full TRACK.md content
2. Add it to the agent's context
3. Optionally load referenced files

Phase 3: Execution

Follow the instructions in the track. If the track references scripts:

1. Resolve the script path relative to the track directory
2. Check that the script is executable
3. Execute with appropriate sandboxing
4. Capture and return output

Configuration options

Option	Type	Default	Description
tracks.enabled	boolean	true	Enable/disable tracks support
tracks.paths	array	[".haijun/tracks"]	Directories to scan for tracks
tracks.maxActive	number	5	Maximum tracks to activate per task
tracks.allowScripts	boolean	true	Allow executing bundled scripts

Resources

• Full specification
• Reference implementation