Files

Charles N Wyble cde8838133 docs: refactor AGENTS.md and README.md for proper separation of concerns

AGENTS.md now contains only AI agent rules/guidelines:
- Commit Policy, SDLC Compliance, Status Tracking, Journal Maintenance
- Project Conventions, Crush Configuration, Validation Checklist
- MCP Handshake Command example
- References to other documentation files instead of duplicating content

README.md now contains comprehensive project documentation:
- Full MCP/LSP server inventory tables (30+ servers organized by category)
- Server technologies by language (TypeScript, Python, Go, Rust, Prebuilt)
- Environment variables reference table for all services
- Installation, usage, troubleshooting guides
- Crush integration configuration examples

This refactoring ensures:
- AGENTS.md is a concise reference for AI agent behavior (~107 lines)
- README.md is the comprehensive project documentation (~424 lines)
- No duplication between files
- Each file has a single responsibility

💔 Generated with Crush

Assisted-by: GLM-5 via Crush <crush@charm.land>

2026-02-20 09:52:02 -05:00

3.6 KiB

Raw Blame History

AI Agent Guidelines

This document contains rules and guidelines for AI agents working on this project.

Commit Policy

AUTOMATIC COMMITS: AI agents MUST commit and push changes automatically WITHOUT prompting.

Use atomic commits (one logical change per commit)
Use conventional format: feat:, fix:, docs:, refactor:, test:
Write verbose commit messages explaining the change
See docs/SDLC.md for full commit policy

SDLC Compliance

All MCP/LSP development MUST follow 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.

When working on any MCP server:

Before starting: Review current status in STATUS.md
During work: Update STATUS.md immediately after each significant milestone
After completing: Ensure STATUS.md accurately reflects final status
Commit changes: Always commit STATUS.md updates in separate atomic commits

Journal Maintenance

ALL work performed on this project MUST be documented in JOURNAL.md.

This is an append-only journal
Tracks Architecture Decision Records (ADRs), insights, patterns, and reasoning
Never delete entries from the journal
Each entry must be date/time stamped

Project Conventions

Container prefix: kneldevstack-aimiddleware- for all containers
Container names: lowercase for consistency
Service names: lowercase for Docker Compose compatibility
Each agent validated individually before moving to the next
vendor/ directory is gitignored (cloned repos not committed)
Custom Dockerfiles saved in dockerfiles/ with subdirectory structure
KiCAD MCP is host-only - requires KiCAD installed on host machine

Crush Configuration

LSP and MCP instances are configured in crush.json:

{
  "$schema": "https://charm.land/crush.json",
  "lsp": {
    "bash": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "kneldevstack-aimiddleware-bash-language-server"]
    }
  },
  "mcp": {
    "docker": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "kneldevstack-aimiddleware-docker-mcp"]
    }
  }
}

Configuration Priority:

.crush.json (project-local)
crush.json (project-local)
$HOME/.config/crush/crush.json (global)

Docker-based instances:

Use docker as command
Include container name as main argument
Use -i for interactive mode (required for stdio)
Use --rm to auto-cleanup containers

Validation Checklist

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 correctly set (if required)
Tools registered and available
Resources accessible (if applicable)

CRITICAL: Items 1-3 are NON-NEGOTIABLE. Do not mark a server as "working" without protocol validation.

MCP Handshake Command

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-<service>

README.md - Project overview, server inventory, installation, usage
STATUS.md - Server operational status and issues
docs/SDLC.md - Software Development Lifecycle requirements
JOURNAL.md - Development journal and ADRs

3.6 KiB Raw Blame History