KNEL-AIMiddleware/AGENTS.md

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:

1. Before starting: Review current status in STATUS.md
2. During work: Update STATUS.md immediately after each significant milestone
3. After completing: Ensure STATUS.md accurately reflects final status
4. 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
• Keep the host clean: only docker and tea (Gitea CLI) commands run directly on the host. Everything else lives in containers. No host installs of runtimes, CLIs, or packages.
• Custom images: publish to the Gitea container registry at git.knownelement.com/reachableceo/<image>:<tag> (Docker is pre-authenticated).
• Standalone CLI tools: containerized CLI tools (not MCP/LSP servers) live in their own top-level directory (e.g. redmine-cli/). Invoked on-demand via docker run --env-file .env <image> <command>, not as long-running services.

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:

1. .crush.json (project-local)
2. crush.json (project-local)
3. $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.

Honest Status Reporting (MANDATORY)

AI agents MUST distinguish between these distinct states and never blur them:

State	Meaning	Example
Built	Image/container compiles or assembles without errors	docker build exits 0
Structural test passed	Binary runs, --help works, error paths return correct codes	CLI prints usage, missing-env exits 2
Validated / Working	A live interaction against a real external system succeeded	whoami returns real user data from the live API

A structural test is NOT validation. Building + --help does not make a tool "validated" or "working".

Rules

1. Never use the words "validated", "working", "done", or "complete" for any service that depends on external credentials or a live endpoint until you have:

   • Obtained the real credentials / endpoint (not placeholder/dummy values).
   • Executed at least one live read or write operation against the real system.
   • Observed a successful response with real data.

2. Never claim validation is impossible then state the tool is done. If you lack credentials, say "blocked — needs credentials to validate" and obtain them. Do not imply completion by omission.

3. Todo list honesty: A todo item may only be marked completed when its acceptance criterion has actually been met. "Build and test" requires a passing test, not a successful build alone.

4. When blocked on validation: Stop, state the exact blocker (e.g. "need DISCOURSE_API_KEY to run live whoami test"), and obtain it before proceeding or declaring the task done.

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>

Git Hooks

This project uses tracked git hooks stored in .githooks/. After cloning, run:

git config core.hooksPath .githooks

Available Hooks

• pre-push - Blocks push if uncommitted changes exist (safety net for AI agents)

Task Completion Checklist

MANDATORY: Before declaring ANY task complete, AI agents MUST verify ALL applicable items:

• All requested work is implemented and functional
• Changes are staged: git add <files>
• Changes are committed with conventional format (feat:, fix:, docs:, etc.)
• Changes are pushed to remote: git push
• STATUS.md updated (if MCP/LSP server status changed)
• JOURNAL.md updated (if significant decision or insight)

DO NOT STOP WORKING until ALL applicable items are complete.

If you cannot complete an item (e.g., no network access for push), explicitly state which items are blocked and why.

One Server At A Time (MANDATORY)

AI agents MUST work on exactly one MCP/LSP server at a time, end-to-end before starting the next one. This includes:

1. Build the container
2. Run the container and validate the protocol handshake
3. Spin up a live Crush or bash session and actually invoke the server through the real client pipeline
4. Observe a successful real tool call (not just a handshake — an actual tool invocation that returns real data or completes a real action)
5. Update STATUS.md and JOURNAL.md for that server
6. Commit and push before moving on

NEVER attempt to build/validate multiple MCP servers in parallel or batch them. NEVER skip from "built" to the next server without completing steps 3-4 (real client invocation with real data).

The pattern of "build all, then validate all" leads to incomplete work that never finishes. One server, fully done, then the next.

Related Documentation

• 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