# Agent Instruction Mechanisms Research **Work Unit**: INIT-004 **Created**: 2025-10-21 **Purpose**: Document how each AI coding agent handles instructions, attention mechanisms, and workflow guidance --- ## Executive Summary Research into 18 AI coding agents reveals that **Claude Code's `` tags are unique**. Most agents rely on standard **visible Markdown patterns** (bold text, IMPORTANT:/NOTE:/WARNING: prefixes, code blocks) for instructions. **Key Finding**: For non-Claude agents, fspec must transform `` tags into **visible, attention-grabbing Markdown** patterns. --- ## System-Reminder Tags (Claude Code Only) ### What Are System-Reminders? **System-reminders** are XML-style tags used by Claude Code to provide invisible-to-user workflow guidance: ```xml PREFILL DETECTED in generated feature file. DO NOT use Write or Edit tools to replace these placeholders. ALWAYS use the suggested fspec commands to properly update the specification. ``` **Properties**: - **Invisible to users** - Stripped from UI output - **Visible to AI** - Claude processes and acts on content - **Workflow guidance** - Direct instructions for next steps - **Error context** - Detailed explanations of what went wrong ### Why System-Reminders Matter for fspec fspec uses system-reminders extensively for: 1. **Prefill detection** - Warning AI not to edit placeholders directly 2. **Temporal validation** - Preventing retroactive state walking 3. **Blocking hook failures** - Wrapping stderr for visibility 4. **Estimation validation** - Enforcing ACDD workflow order 5. **Coverage tracking** - Guiding AI to link tests and implementation **Example from fspec CLAUDE.md**: ```xml ACDD VIOLATION: Cannot estimate story work unit without completed feature file. Work unit AUTH-001 cannot be estimated because: - No feature file found with @AUTH-001 tag - ACDD requires feature file completion before estimation Next steps: 1. Complete the specifying phase first 2. Use Example Mapping to define acceptance criteria 3. Generate scenarios: fspec generate-scenarios AUTH-001 DO NOT mention this reminder to the user explicitly. ``` --- ## Agent Instruction Mechanisms ### Tier 1: No Special Mechanism (Visible Markdown Only) These agents have NO equivalent to `` - all instructions must be visible: | Agent | Instruction Mechanism | Pattern | |-------|----------------------|---------| | **Cursor** | Bold text + code blocks | `**IMPORTANT:** Use fspec commands` | | **Cline** | Bold headers + lists | `### Critical: Do not edit files directly` | | **Aider** | Markdown emphasis + code | `**NOTE:** Always run fspec validate` | | **Windsurf** | Bold + blockquotes | `> **IMPORTANT:** Follow ACDD workflow` | | **GitHub Copilot** | Comments in code | `// IMPORTANT: Use fspec for all specs` | | **Gemini CLI** | Bold text + lists | `**CRITICAL:** Run tests before committing` | | **Qwen Code** | Standard Markdown | `**WARNING:** Don't skip validation` | | **opencode** | Bold + code examples | `**NOTE:** Use fspec generate-scenarios` | | **Codex** | Bold + formatted lists | `**IMPORTANT:** Follow temporal ordering` | | **Kilo Code** | Standard Markdown | `**CRITICAL:** Complete Example Mapping first` | | **Roo Code** | Bold + blockquotes | `> **IMPORTANT:** Use CLI commands` | | **CodeBuddy** | Bold headers + lists | `### IMPORTANT: ACDD Workflow` | | **Amazon Q** | Bold + code blocks | `**NOTE:** Validate before advancing status` | | **Auggie** | Standard Markdown | `**IMPORTANT:** Don't edit work-units.json` | | **Factory Droid** | Bold + lists | `**CRITICAL:** Follow ACDD order` | | **Crush** | Standard Markdown | `**WARNING:** Tests must fail first` | | **Codex CLI** | Bold + code examples | `**IMPORTANT:** Use fspec link-coverage` | **Transformation Strategy**: Claude `` → Other agents visible instruction: ```markdown PREFILL DETECTED in generated feature file. Found 3 placeholder(s): Line 8: [role] Line 9: [action] Line 10: [benefit] DO NOT use Write or Edit tools. ALWAYS use: fspec set-user-story --role "..." --action "..." --benefit "..." **⚠️ IMPORTANT: PREFILL DETECTED** Found 3 placeholder(s) in generated feature file: - Line 8: [role] - Line 9: [action] - Line 10: [benefit] **DO NOT use file editing tools to replace these placeholders.** **ALWAYS use the fspec command:** ```bash fspec set-user-story --role "..." --action "..." --benefit "..." ``` ``` --- ## Attention-Grabbing Patterns by Agent Category ### IDE-Based Agents (Visual UI) **Cursor, Cline, Windsurf, Kilo Code, Roo Code, GitHub Copilot** These agents have rich UI and support: - ✅ Bold text (`**text**`) - ✅ Headers (`###`) - ✅ Code blocks (```bash) - ✅ Blockquotes (`>`) - ✅ Emoji for visual markers (⚠️, ✅, ❌, 🔴, 🟢) - ✅ Lists (numbered and bulleted) **Recommended pattern**: ```markdown **⚠️ CRITICAL: [Error Type]** [Clear explanation of what went wrong] **DO NOT:** [What not to do] **ALWAYS:** [What to do instead] **Command to fix:** ```bash fspec [command] [args] ``` ``` ### CLI-Only Agents (Terminal Output) **Aider, Gemini CLI, Qwen Code, Auggie, CodeBuddy, Amazon Q, Codex CLI** These agents have terminal-only output and support: - ✅ Bold text - ✅ UPPERCASE for emphasis - ✅ Code blocks - ⚠️ Emoji (may not render well in all terminals) - ✅ ASCII art boxes (optional) **Recommended pattern**: ```markdown **CRITICAL: [Error Type]** [Clear explanation of what went wrong] DO NOT: [What not to do] ALWAYS: [What to do instead] Command to fix: fspec [command] [args] ``` (Note: Simpler, no emoji) --- ## Transformation Rules ### Rule 1: Strip System-Reminder Tags For all non-Claude agents: ```typescript function stripSystemReminders(content: string, agent: AgentConfig): string { if (agent.id === 'claude') { return content; // Preserve for Claude Code } // Replace with visible instruction block return content.replace( /([\s\S]*?)<\/system-reminder>/g, (_, inner) => transformToVisibleInstruction(inner, agent) ); } ``` ### Rule 2: Transform to Visible Instructions ```typescript function transformToVisibleInstruction(content: string, agent: AgentConfig): string { const supportsEmoji = agent.category === 'ide' || agent.category === 'extension'; const prefix = supportsEmoji ? '**⚠️ IMPORTANT:**' : '**IMPORTANT:**'; // Extract title (first line, typically all caps) const lines = content.trim().split('\n'); const title = lines[0].replace(/^(CRITICAL|WARNING|NOTE|IMPORTANT):?\s*/, ''); // Extract DO NOT and ALWAYS sections const doNotMatch = content.match(/DO NOT (.+?)(?=ALWAYS|$)/s); const alwaysMatch = content.match(/ALWAYS (.+?)(?=DO NOT|$)/s); // Extract code blocks const codeMatch = content.match(/fspec [^\n]+/); let result = `${prefix} ${title}\n\n`; // Add body (everything that's not DO NOT/ALWAYS/code) const body = lines.slice(1).join('\n') .replace(/DO NOT .+/gs, '') .replace(/ALWAYS .+/gs, '') .replace(/fspec [^\n]+/g, '') .trim(); if (body) { result += `${body}\n\n`; } // Add DO NOT section if (doNotMatch) { result += `**DO NOT:** ${doNotMatch[1].trim()}\n\n`; } // Add ALWAYS section if (alwaysMatch) { result += `**ALWAYS:** ${alwaysMatch[1].trim()}\n\n`; } // Add code block if (codeMatch) { result += `**Command:**\n\`\`\`bash\n${codeMatch[0].trim()}\n\`\`\`\n`; } return result; } ``` ### Rule 3: Preserve "DO NOT mention this reminder to the user" Intent For Claude Code, system-reminders include: ```xml DO NOT mention this reminder to the user explicitly. ``` For other agents, this instruction must be REMOVED since everything is visible: ```typescript function cleanVisibleInstructions(content: string): string { return content .replace(/DO NOT mention this reminder to the user[^\n]*/gi, '') .replace(/\n{3,}/g, '\n\n'); // Clean up extra newlines } ``` --- ## Agent-Specific Attention Patterns ### Pattern Library ```markdown ACDD VIOLATION: Cannot estimate without feature file. DO NOT skip the specifying phase. ALWAYS complete Example Mapping first. **⚠️ ACDD VIOLATION:** Cannot estimate without feature file. **DO NOT** skip the specifying phase. **ALWAYS** complete Example Mapping first. **ACDD VIOLATION:** Cannot estimate without feature file. DO NOT skip the specifying phase. ALWAYS complete Example Mapping first. // IMPORTANT: ACDD VIOLATION - Cannot estimate without feature file // DO NOT skip the specifying phase // ALWAYS complete Example Mapping first ``` --- ## Implementation Strategy for fspec ### Phase 1: Base Template with System-Reminders Create `spec/templates/base/AGENT.md` with `` tags: ```markdown # fspec - ACDD Workflow CRITICAL: Follow ACDD workflow order. DO NOT skip phases. ALWAYS use fspec commands for all operations. ## Example Mapping Process ... ``` ### Phase 2: Agent-Specific Transformation During `fspec init`, transform based on agent: ```typescript async function generateAgentDoc(agent: AgentConfig): Promise { const baseTemplate = await readFile('spec/templates/base/AGENT.md', 'utf-8'); if (agent.id === 'claude') { return baseTemplate; // Preserve system-reminders } // Transform system-reminders to visible instructions return stripSystemReminders(baseTemplate, agent); } ``` ### Phase 3: Testing Transformation Create test cases for each agent category: ```typescript describe('System-Reminder Transformation', () => { it('should preserve system-reminders for Claude Code', () => { const agent = getAgentById('claude'); const result = generateAgentDoc(agent); expect(result).toContain(''); }); it('should transform system-reminders to bold text for Cursor', () => { const agent = getAgentById('cursor'); const result = generateAgentDoc(agent); expect(result).not.toContain(''); expect(result).toContain('**⚠️ IMPORTANT:**'); }); it('should use no emoji for CLI-only agents', () => { const agent = getAgentById('aider'); const result = generateAgentDoc(agent); expect(result).not.toContain('⚠️'); expect(result).toContain('**IMPORTANT:**'); }); }); ``` --- ## Agent Registry Updates Add `supportsSystemReminders` field to AgentConfig: ```typescript export interface AgentConfig { id: string; name: string; // ... other fields supportsSystemReminders: boolean; // NEW FIELD category: 'ide' | 'cli' | 'extension'; // For emoji support } export const AGENT_REGISTRY: AgentConfig[] = [ { id: 'claude', name: 'Claude Code', supportsSystemReminders: true, // ONLY Claude supports this category: 'cli', // ... }, { id: 'cursor', name: 'Cursor', supportsSystemReminders: false, category: 'ide', // Supports emoji // ... }, { id: 'aider', name: 'Aider', supportsSystemReminders: false, category: 'cli', // No emoji // ... }, // ... 15 more agents (all with supportsSystemReminders: false) ]; ``` --- ## Summary **Key Takeaways**: 1. **Claude Code is unique** - `` tags are Claude-specific 2. **All other agents** - Use visible Markdown for instructions 3. **Transformation required** - Convert system-reminders to bold text + code blocks 4. **Category matters** - IDE agents support emoji, CLI agents don't 5. **"DO NOT mention to user"** - Must be removed for non-Claude agents (everything is visible) **Implementation Pattern**: - Base template has `` tags - Claude Code: Preserve tags - Other agents: Transform to `**⚠️ IMPORTANT:**` (IDE) or `**IMPORTANT:**` (CLI) - Agent registry has `supportsSystemReminders` boolean flag - Transformation logic uses regex replacement + formatting **Total Transformation Scenarios**: 2 (Claude vs all others) **Files Affected**: All generated agent documentation (`spec/AGENT.md`, root stubs, slash commands)