Files

Charles N Wyble 1526af86d8 fix(agents): add mandatory task completion checklist and tracked git hooks

Root cause fix for AI agent failing to commit/push automatically:

1. Added Task Completion Checklist to AGENTS.md with mandatory items:
   - All requested work implemented
   - Changes staged (git add)
   - Changes committed (conventional format)
   - Changes pushed (git push)
   - STATUS.md updated (if applicable)
   - JOURNAL.md updated (if applicable)

2. Added pre-push hook in .githooks/ (tracked, not .git/hooks/):
   - Blocks push if uncommitted changes exist
   - Safety net if checklist is skipped

3. Fixed .gitignore: changed "vendor/" to "vendor" to also ignore symlink

After cloning, run: git config core.hooksPath .githooks

💘 Generated with Crush

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

2026-02-20 12:08:43 -05:00

4.5 KiB

Raw Permalink 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>

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.

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

4.5 KiB Raw Permalink Blame History