diff --git a/AGENTS.md b/AGENTS.md index a8b0d09..907915e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,6 +2,10 @@ This document tracks the AI agents and MCP servers configured in this project. +> **🔴 AUTOMATIC COMMITS**: AI agents MUST commit and push changes automatically WITHOUT prompting. Use atomic commits (one logical change per commit), conventional format (`feat:`, `fix:`, `docs:`), and verbose messages. See [docs/SDLC.md](docs/SDLC.md) for full commit policy. + +> **📋 SDLC Compliance**: All MCP/LSP development MUST follow [docs/SDLC.md](docs/SDLC.md). Key rule: **Protocol handshake is NON-NEGOTIABLE** - build + start + protocol validation ALL required before marking a server as "working". + > **Status Tracking**: Current operational status of all MCP servers is maintained in [STATUS.md](STATUS.md). Please refer to that file for the latest status of each server. > **Journal Maintenance**: ALL work performed on this project MUST be documented in [JOURNAL.md](JOURNAL.md). This is an append-only journal that tracks Architecture Decision Records (ADRs), insights, patterns, and the reasoning behind all work done. Never delete entries from the journal. Each entry must be date/time stamped. @@ -180,6 +184,23 @@ docker compose stop ## Development Notes +### SDLC Compliance (REQUIRED) + +**Read [docs/SDLC.md](docs/SDLC.md) before working on any MCP/LSP server.** + +The SDLC defines the mandatory validation workflow: +1. **BUILD**: Container must build without errors +2. **START**: Container must start without immediate crash +3. **PROTOCOL**: Must receive valid JSON-RPC response to handshake + +Without ALL THREE, a server is NOT "working". + +MCP handshake command: +```bash +echo '{"jsonrpc":"2.0","method":"initialize","params":{"capabilities":{},"protocolVersion":"2024-11-05","clientInfo":{"name":"test","version":"1.0.0"}},"id":1}' | \ + timeout 10 docker run --rm -i kneldevstack-aimiddleware- +``` + ### Critical: STATUS.md Maintenance **STATUS.md MUST always be kept fully up to date** as it is the single source of truth for operational status of all MCP servers in this project. @@ -235,15 +256,17 @@ All LSP and MCP instances must be configured in `crush.json` for Crush to use th ## Validation Checklist -For each agent, verify: +For each agent, verify in order: - [ ] Container builds successfully - [ ] Container starts without errors +- [ ] **Protocol handshake returns valid response** (MANDATORY - see SDLC) - [ ] Logs show proper initialization - [ ] Environment variables are correctly set (if required) -- [ ] MCP protocol handshake completes - [ ] Tools are registered and available - [ ] Resources are accessible (if applicable) +> **⚠️ CRITICAL**: Items 1-3 are NON-NEGOTIABLE. Do not mark a server as "working" without protocol validation. + ## References - [Model Context Protocol](https://modelcontextprotocol.io/)