feat(agents): modernize AGENTS.md for 2025-2026 agentic coding

[vlobachev]

User description

Phase 1 Complete: AGENTS.md Modernization + Multi-Agent Compatibility

Changes:

1. Updated root AGENTS.md to 2025-2026 standards:

   • Added executable setup commands section
   • Added comprehensive repository map
   • Added "How to Work Safely" guidelines
   • Modernized supported tools (Claude Code, GitHub Copilot, MCP)
   • Added agent-loop pattern and self-correction workflow
   • Updated security guidelines for template projects
   • Improved tool-specific notes with 2025-2026 tools

2. Modernized templates/AGENTS.md.hbs:

   • Shorter, more actionable format
   • Executable commands based on package manager
   • Repository map for generated projects
   • Agent-loop pattern included
   • 2025-2026 tool support

3. Created AGENTS_MD_SSOT.md documentation:

   • Explains AGENTS.md as single source of truth
   • Documents relationship between AGENTS.md and tool configs
   • Provides migration strategy for tool-specific configs
   • Includes best practices for avoiding duplication

4. Updated README.md supported tools:

   • Added Claude Code (primary support)
   • Added GitHub Copilot Agent Mode
   • Added Cline
   • Updated for 2025-2026

Benefits:

• AGENTS.md is now the primary, cross-tool interface
• Clear structure: setup → map → safety → permissions → style
• Agent-loop friendly (run, observe, fix, repeat)
• Reduced duplication across tool configs
• Ready for modern AI coding agents

Next: Phase 2 - GitHub Copilot agent mode support

AI-Generated: Yes
Reviewed-by: Claude Code

---

PR Type

Enhancement, Documentation, Tests

---

Description

Core Features:

• Modernized AGENTS.md for 2025-2026 agentic coding standards with executable setup commands, repository maps, and comprehensive safety guidelines

• Implemented MCP (Model Context Protocol) memory server with SQLite backend for persistent agent memory storage

• Added comprehensive test suite for memory store with full CRUD operation coverage

• Created GitHub Copilot agent mode integration guide with best practices and workflow patterns

• Established AGENTS.md as single source of truth (SSOT) for cross-tool agent configuration

Documentation & Guides:

• New guides: COPILOT_AGENT_MODE.md, MCP.md, AGENTS_MD_SSOT.md, and contract-first development pattern example

• Agent-optimized issue templates for features, bugs, and refactoring tasks

• Agent task checklist template for complex multi-step workflows

• Agent-optimized pull request template with validation evidence sections

• Comprehensive MCP memory server implementation documentation

Code Quality & Configuration:

• Added ESLint configuration (flat config format for v9+) with custom overrides

• Added Prettier configuration with markdown prose wrapping at 80 characters

• Updated package.json with new validation pipeline (lint, format:check, test)

• Reformatted setup.js and test-setup.js for code style consistency

• Applied consistent markdown formatting across all documentation files

Dependencies:

• Added better-sqlite3@9.6.0 for SQLite database support

• Added ESLint v9 dependencies: @eslint/js@9.39.2 and globals@17.0.0

• Added native module build dependencies for better-sqlite3

Template Modernization:

• Completely restructured templates/AGENTS.md.hbs with 2025-2026 standards

• Added executable commands with package manager conditionals

• Expanded tool support for Claude Code, GitHub Copilot, Windsurf, Roo Code, KiloCode, Cline

• Included agent-loop pattern and self-correction workflow guidance

---

Diagram Walkthrough

flowchart LR
  A["AGENTS.md<br/>Single Source of Truth"] -->|"guides"| B["Tool Configs<br/>Claude, Copilot, Windsurf"]
  A -->|"templates"| C["AGENTS.md.hbs<br/>Generated Projects"]
  D["MCP Memory Server<br/>SQLite Backend"] -->|"provides"| E["Memory Tools<br/>add, search, get, list, delete"]
  E -->|"enables"| F["Agent Loop<br/>run, observe, fix, repeat"]
  G["Documentation<br/>Guides & Examples"] -->|"supports"| F
  H["Issue & PR Templates<br/>Agent-Optimized"] -->|"structure"| F
  I["Code Quality<br/>ESLint, Prettier"] -->|"validates"| J["Validation Pipeline<br/>lint, format, test"]

Loading

[qodo-code-review]

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
⚪	Missing access control Description: The JSON-RPC stdio transport accepts and processes requests without any authentication/authorization, so any process able to write to the server’s stdin can add/search/list/delete all stored memories (e.g., deleteMemory), which may enable unauthorized data access or tampering in environments where the MCP server is shared or proxied. index.js [37-120] Referred Code // Setup stdio transport const input = process.stdin; const output = process.stdout; // Handle incoming JSON-RPC messages let buffer = ''; input.on('data', chunk => { buffer += chunk.toString(); // Process complete JSON-RPC messages (newline-delimited) const lines = buffer.split('\n'); buffer = lines.pop(); // Keep incomplete line in buffer for (const line of lines) { if (line.trim()) { try { const request = JSON.parse(line); handleRequest(request); } catch (error) { sendError(null, -32700, 'Parse error', { message: error.message }); ... (clipped 63 lines)
	Unbounded input buffering Description: The stdin buffering logic appends arbitrary input to buffer with no size limit and only flushes on newline, enabling a trivial memory exhaustion/DoS by sending an extremely large line (or never sending a newline). index.js [41-60] Referred Code // Handle incoming JSON-RPC messages let buffer = ''; input.on('data', chunk => { buffer += chunk.toString(); // Process complete JSON-RPC messages (newline-delimited) const lines = buffer.split('\n'); buffer = lines.pop(); // Keep incomplete line in buffer for (const line of lines) { if (line.trim()) { try { const request = JSON.parse(line); handleRequest(request); } catch (error) { sendError(null, -32700, 'Parse error', { message: error.message }); } } }
Ticket Compliance
⚪	🎫 No ticket provided Create ticket/issue
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
🔴	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: No audit logging: Critical actions that create/read/delete stored memories are performed without any audit trail fields (e.g., actor/user ID, timestamped log entry, outcome), making post-incident reconstruction impossible. Referred Code async handleMethod(method, params = {}) { switch (method) { case 'initialize': return this.handleInitialize(params); case 'tools/list': return this.handleToolsList(); case 'tools/call': return this.handleToolsCall(params); case 'resources/list': return this.handleResourcesList(); case 'resources/read': return this.handleResourcesRead(params); default: throw new Error(`Unknown method: ${method}`); } } ... (clipped 202 lines) Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: Missing request validation: Incoming JSON-RPC requests are processed without validating required fields/types (e.g., method, id, params shape), so malformed inputs can trigger runtime errors and inconsistent error handling. Referred Code input.on('data', chunk => { buffer += chunk.toString(); // Process complete JSON-RPC messages (newline-delimited) const lines = buffer.split('\n'); buffer = lines.pop(); // Keep incomplete line in buffer for (const line of lines) { if (line.trim()) { try { const request = JSON.parse(line); handleRequest(request); } catch (error) { sendError(null, -32700, 'Parse error', { message: error.message }); } } } }); input.on('end', () => { store.close(); ... (clipped 19 lines) Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: Leaks error details: Uncaught exceptions and unhandled rejections are printed to stderr with full error objects (often including stack traces) and error messages are returned in JSON-RPC error.data, which can expose internal details to clients. Referred Code } catch (error) { sendError(id, -32603, 'Internal error', { message: error.message, stack: process.env.NODE_ENV === 'development' ? error.stack : undefined }); } } /** * Send JSON-RPC success response */ function sendResponse(id, result) { const response = { jsonrpc: '2.0', id, result }; output.write(JSON.stringify(response) + '\n'); } /** ... (clipped 22 lines) Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: Unstructured sensitive logs: The server logs unstructured messages to stderr including raw error objects and the database path, which may expose sensitive runtime and filesystem details and is not structured for auditing. Referred Code process.on('uncaughtException', error => { console.error('Uncaught exception:', error); sendError(null, -32603, 'Internal error', { message: error.message }); process.exit(1); }); process.on('unhandledRejection', (reason, _promise) => { console.error('Unhandled rejection:', reason); sendError(null, -32603, 'Internal error', { message: String(reason) }); }); // Startup message (to stderr, not to interfere with JSON-RPC) console.error('MCP Memory Server started'); console.error(`Database: ${store.dbPath}`); console.error('Waiting for JSON-RPC messages on stdin...'); Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: No input sanitization: External inputs (e.g., content, tags, metadata, dbPath, and FTS query) are accepted and persisted without type/size validation or sanitization, increasing risk of malformed data, runtime failures, and unsafe filesystem usage. Referred Code constructor(options = {}) { this.dbPath = options.dbPath || './mcp-memory.db'; // Ensure database directory exists const dir = dirname(this.dbPath); if (!existsSync(dir)) { mkdirSync(dir, { recursive: true }); } // Open database this.db = new Database(this.dbPath); this.db.pragma('journal_mode = WAL'); // Better concurrency // Initialize schema this.initializeSchema(); } /** * Initialize database schema */ initializeSchema() { ... (clipped 154 lines) Learn more about managing compliance generic rules or creating your own custom rules
Update

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

[qodo-code-review]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
High-level	Consider using an existing MCP server Instead of building and maintaining a custom MCP memory server, consider using an existing open-source implementation. This would reduce complexity and allow the project to focus on its core blueprint features. Examples: src/mcp-memory/mcp-server.js [1-398] src/mcp-memory/memory-store.js [1-217] Solution Walkthrough: Before: // src/mcp-memory/mcp-server.js export class MCPServer { constructor(options) { this.store = options.store; this.tools = { addMemory, searchMemories, ... }; } async handleMethod(method, params) { ... } toolAddMemory(args) { return this.store.addMemory(...); } // ... other tool implementations } // src/mcp-memory/memory-store.js export class MemoryStore { constructor(options) { this.db = new Database(options.dbPath); this.initializeSchema(); // Creates tables, FTS index, triggers } addMemory(...) { ... } searchMemories(...) { ... } // ... other CRUD operations } After: // package.json (conceptual) { "scripts": { "start:memory-server": "some-mcp-server-cli --db ./mcp-memory.db" }, "devDependencies": { "some-mcp-server-cli": "^1.2.3" } } // docs/guides/MCP.md (updated content) /* ## Quick Start ### 1. Install the recommended MCP Server npm install -g some-mcp-server-cli ### 2. Run the Server some-mcp-server-cli --database ./project-memory.db ... */ // The entire `src/mcp-memory/` directory would be removed. Suggestion importance[1-10]: 9 __ Why: This is a critical architectural suggestion that correctly identifies the high maintenance cost of a custom MCP server, proposing a valid alternative that better aligns with the project's "blueprint" philosophy.	High
Possible issue	Fix incorrect tag filtering logic Fix the flawed tag filtering logic, which uses LIKE and can cause false positives, by implementing a custom SQLite function for exact tag matching within the JSON array. src/mcp-memory/memory-store.js [121-125] if (tags && tags.length > 0) { + if (!this.db.function('all_tags_match')) { + this.db.function('all_tags_match', { varargs: true }, (jsonTags, ...searchTags) => { + if (!jsonTags) return 0; + try { + const storedTags = JSON.parse(jsonTags); + if (!Array.isArray(storedTags)) return 0; + const tagSet = new Set(storedTags); + return searchTags.every(tag => tagSet.has(tag)) ? 1 : 0; + } catch (e) { + return 0; + } + }); + } + // Filter by tags (must contain all specified tags) - query += ` WHERE ${tags.map(() => 'tags LIKE ?').join(' AND ')}`; - params.push(...tags.map(tag => `%"${tag}"%`)); + query += ` WHERE all_tags_match(tags, ${tags.map(() => '?').join(', ')})`; + params.push(...tags); } [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 8 __ Why: The suggestion correctly identifies a functional bug in the tag filtering logic where LIKE would lead to partial matches, and provides a robust and correct solution using a custom SQLite function.	Medium
	Include all tests in test script Update the test script in package.json to run tests for the entire project, not just the mcp-memory subdirectory, to prevent regressions. package.json [14] -"test": "node --test src/mcp-memory/test/**/*.test.js" +"test": "node --test test/**/*.test.js && node --test src/mcp-memory/test/**/*.test.js" [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 8 __ Why: This suggestion correctly identifies a critical regression where the test script's scope was narrowed, and provides a valid fix to ensure all tests are run.	Medium
	Exit process on unhandled promise rejections Add process.exit(1) to the unhandledRejection handler to ensure the application terminates on unhandled promise rejections, matching the behavior of the uncaughtException handler and preventing a corrupt state. src/mcp-memory/index.js [110-119] process.on('uncaughtException', error => { console.error('Uncaught exception:', error); sendError(null, -32603, 'Internal error', { message: error.message }); process.exit(1); }); process.on('unhandledRejection', (reason, _promise) => { console.error('Unhandled rejection:', reason); sendError(null, -32603, 'Internal error', { message: String(reason) }); + process.exit(1); }); [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 7 __ Why: The suggestion correctly points out that not exiting on an unhandledRejection can leave the application in an inconsistent state and proposes a valid improvement for robustness.	Medium
	Expose available tools and resources Update the handleInitialize method to expose the names of available tools and resources in the capabilities object, rather than returning empty objects. src/mcp-memory/mcp-server.js [161-174] handleInitialize(_params) { return { protocolVersion: '1.0', serverInfo: { name: this.name, version: this.version, description: this.description }, capabilities: { - tools: {}, - resources: {} + tools: Object.keys(this.tools), + resources: Object.keys(this.resources) } }; } [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 7 __ Why: The suggestion correctly notes that the initialize method should return the server's capabilities, and the proposed change correctly implements this, improving compliance with the MCP specification.	Medium
	Re-add templates directory to lint Update the lint script in package.json to re-include the templates/ directory, ensuring code style is checked across all relevant source files. package.json [15] -"lint": "eslint src/" +"lint": "eslint src/ templates/" [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 7 __ Why: The suggestion correctly identifies that the lint script's scope was narrowed, which is a regression, and proposes restoring the previous, wider scope.	Medium
	Correct an invalid example link Correct an invalid relative link in a documentation example to ensure it points to the correct root-level file. docs/guides/AGENTS_MD_SSOT.md [186-196] ### 3. Avoiding Duplication **Use links instead of copying**: ```markdown <!-- ✅ GOOD --> For validation requirements, see -[AGENTS.md - How to Work Safely](../AGENTS.md#how-to-work-safely). +[AGENTS.md - How to Work Safely](../../AGENTS.md#how-to-work-safely). <!-- ❌ BAD --> Apply / Chat Suggestion importance[1-10]: 4 __ Why: The suggestion correctly identifies and fixes an incorrect path in a code example, which improves the accuracy and usefulness of the documentation.	Low
General	Remove pre-filled success validation output Replace the pre-filled successful make validate output in the PR template with a placeholder instruction to prevent merging unvalidated code. .github/PULL_REQUEST_TEMPLATE/agent-pr.md [18-24] **Proof that validation passed**: ```bash -# Output of make validate -$ make validate -✓ All validation checks passed +# Paste the output of 'make validate' here - [ ] **Apply / Chat** <!-- /improve --apply_suggestion=7 --> <details><summary>Suggestion importance[1-10]: 7</summary> __ Why: The suggestion correctly identifies that a pre-filled success message in a PR template is misleading and improves the template to require actual validation output. </details></details></td><td align=center>Medium </td></tr> <tr><td align="center" colspan="2"> - [ ] Update <!-- /improve_multi --more_suggestions=true --> </td><td></td></tr></tbody></table>