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](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).

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](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
  under `tooling-cli/` (e.g. `tooling-cli/redmine/`). Invoked on-demand via
  `docker run --env-file ~/.creds/<service>.env <image> <command>`, not as long-running services.

## Crush Configuration

LSP and MCP instances are configured in `crush.json`:

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

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

## Git Hooks

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

```bash
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](README.md) - Project overview, server inventory, installation, usage
- [STATUS.md](STATUS.md) - Server operational status and issues
- [docs/SDLC.md](docs/SDLC.md) - Software Development Lifecycle requirements
- [JOURNAL.md](JOURNAL.md) - Development journal and ADRs