holocron/plugins/kyberforge/skills/agent-audit/scripts/validate.sh

#!/usr/bin/env bash
set -euo pipefail

usage() {
  cat <<EOF
Usage: validate.sh <agent-file>

Validate a Claude Code or Copilot agent file pair against the agent definition spec.

Arguments:
  agent-file  Path to either the Claude Code .md or Copilot .agent.md agent file.

Exit codes:
  0  All checks passed (may include SUGGESTIONs)
  1  One or more checks failed
  2  Script error (unrecognized file extension or missing field-inventory.md)
EOF
}

if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
  usage
  exit 0
fi

if [[ $# -lt 1 ]]; then
  echo "Error: agent-file is required." >&2
  echo "" >&2
  usage >&2
  exit 1
fi

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

python3 -u - "$1" "$SCRIPT_DIR" <<'PYTHON'
import sys
import os
import re

agent_file = os.path.abspath(sys.argv[1])
script_dir = sys.argv[2]

fname = os.path.basename(agent_file)

# --- Detect provider (check .agent.md before .md) ---
if fname.endswith('.agent.md'):
    provider = 'copilot'
    name_stem = fname[:-len('.agent.md')]
elif fname.endswith('.md'):
    provider = 'claude-code'
    name_stem = fname[:-len('.md')]
else:
    print(f"Error: unrecognized extension '{fname}' — expected .md or .agent.md", file=sys.stderr)
    sys.exit(2)

# --- Load field-inventory.md ---
inv_path = os.path.normpath(os.path.join(script_dir, '..', 'references', 'field-inventory.md'))
if not os.path.isfile(inv_path):
    print(f"Error: field-inventory.md not found at {inv_path}", file=sys.stderr)
    sys.exit(2)

with open(inv_path) as f:
    inv_content = f.read()

def parse_section_tokens(content, section_name):
    lines = content.splitlines()
    for i, line in enumerate(lines):
        if line.strip() == f'## {section_name}':
            for j in range(i + 1, len(lines)):
                stripped = lines[j].strip()
                if stripped and not stripped.startswith('#') and not stripped.startswith('---'):
                    return set(stripped.split())
    return set()

cc_only_fields = parse_section_tokens(inv_content, 'claude-code-only-fields')
copilot_only_fields = parse_section_tokens(inv_content, 'copilot-only-fields')
plugin_ignored_fields = parse_section_tokens(inv_content, 'plugin-silently-ignored-fields')

# Tools the runtime withholds from subagents regardless of the tools field
SUBAGENT_UNAVAILABLE_TOOLS = {
    'AskUserQuestion', 'EnterPlanMode', 'ExitPlanMode', 'ScheduleWakeup', 'WaitForMcpServers',
}

# Copilot body length limit (chars) — content beyond this is silently truncated
COPILOT_BODY_LIMIT = 30000

# --- Detect scope ---
def detect_scope(start_dir):
    current = os.path.abspath(start_dir)
    while True:
        if (os.path.isfile(os.path.join(current, 'plugin.json')) or
                os.path.isfile(os.path.join(current, '.claude-plugin', 'plugin.json'))):
            return 'plugin', current
        if os.path.isdir(os.path.join(current, '.git')):
            return 'project', current
        parent = os.path.dirname(current)
        if parent == current:
            return 'user', os.path.expanduser('~')
        current = parent

agent_dir = os.path.dirname(agent_file)
scope, scope_root = detect_scope(agent_dir)

# --- Derive counterpart path ---
if scope == 'plugin':
    if provider == 'copilot':
        counterpart = os.path.join(agent_dir, name_stem + '.md')
        counterpart_provider = 'claude-code'
    else:
        counterpart = os.path.join(agent_dir, name_stem + '.agent.md')
        counterpart_provider = 'copilot'
elif scope == 'project':
    if provider == 'claude-code':
        counterpart = os.path.join(scope_root, '.github', 'agents', name_stem + '.agent.md')
        counterpart_provider = 'copilot'
    else:
        counterpart = os.path.join(scope_root, '.claude', 'agents', name_stem + '.md')
        counterpart_provider = 'claude-code'
else:  # user
    home = os.path.expanduser('~')
    if provider == 'claude-code':
        counterpart = os.path.join(home, '.copilot', 'agents', name_stem + '.agent.md')
        counterpart_provider = 'copilot'
    else:
        counterpart = os.path.join(home, '.claude', 'agents', name_stem + '.md')
        counterpart_provider = 'claude-code'

# --- Helpers ---
failed = False
suggestions = []

def fail(msg):
    global failed
    failed = True
    print(f"FAIL  {msg}")

def suggest(msg):
    suggestions.append(msg)

PLACEHOLDER_RE = re.compile(r'(?<!`)FILL IN:[^`\n]')

def parse_frontmatter(content):
    m = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
    if not m:
        return None, content
    return m.group(1), content[m.end():]

def extract_field(fm, field):
    m = re.search(rf'^{re.escape(field)}:\s*(.+)', fm, re.MULTILINE)
    return m.group(1).strip() if m else None

def get_frontmatter_keys(fm):
    keys = set()
    for line in fm.splitlines():
        m = re.match(r'^([a-zA-Z][a-zA-Z0-9_-]*):', line)
        if m:
            keys.add(m.group(1))
    return keys

def extract_tools_list(fm):
    """Extract tool names from the tools frontmatter field (space or comma separated)."""
    val = extract_field(fm, 'tools')
    if not val:
        return set()
    return set(re.split(r'[\s,]+', val.strip()))

def is_copilot_cloud_ide(fpath):
    """True if the file is a cloud/IDE Copilot agent (name is optional for these)."""
    return '.github/copilot/agents' in os.path.abspath(fpath).replace(os.sep, '/')

def check_file(fpath, file_provider, is_plugin_scope):
    local_fname = os.path.basename(fpath)
    with open(fpath) as f:
        content = f.read()

    fm, body = parse_frontmatter(content)
    if fm is None:
        fail(f"no valid YAML frontmatter (---...---) — {local_fname}")
        return

    # name — required for CC and Copilot CLI; optional for Copilot cloud/IDE agents
    cloud_ide = (file_provider == 'copilot' and is_copilot_cloud_ide(fpath))
    name_val = extract_field(fm, 'name')
    if not cloud_ide:
        if not name_val:
            fail(f"name field is missing or empty — {local_fname}")
        else:
            if not re.match(r'^[a-z0-9]+(-[a-z0-9]+)*$', name_val):
                fail(f"name '{name_val}' is not kebab-case — {local_fname}")
            # Stem check applies to Copilot CLI only; CC docs say filename need not match name
            if file_provider == 'copilot':
                stem = local_fname[:-len('.agent.md')]
                if name_val != stem:
                    fail(f"name '{name_val}' does not match filename stem '{stem}' — {local_fname}")
    elif name_val and not re.match(r'^[a-z0-9]+(-[a-z0-9]+)*$', name_val):
        # cloud/IDE: name is optional, but if present it must be valid
        fail(f"name '{name_val}' is not kebab-case — {local_fname}")

    # description
    desc_val = extract_field(fm, 'description')
    if not desc_val:
        fail(f"description field is missing or empty — {local_fname}")
    else:
        if PLACEHOLDER_RE.search(desc_val):
            fail(f"description contains unfilled FILL IN: placeholder — {local_fname}")

    # body
    if not body.strip():
        fail(f"system prompt body is empty — {local_fname}")
    else:
        if PLACEHOLDER_RE.search(body):
            fail(f"body contains unfilled FILL IN: placeholder — {local_fname}")
        # Copilot body length limit
        if file_provider == 'copilot' and len(body) > COPILOT_BODY_LIMIT:
            suggest(f"body exceeds {COPILOT_BODY_LIMIT:,} characters ({len(body):,} chars) — content beyond the limit is silently truncated by the Copilot runtime — {local_fname}")

    # CC-only fields in Copilot file
    if file_provider == 'copilot':
        fm_keys = get_frontmatter_keys(fm)
        for key in sorted(fm_keys):
            if key in cc_only_fields:
                fail(f"CC-only field '{key}' present in Copilot file — {local_fname}")

    # Copilot-only fields in CC file
    if file_provider == 'claude-code':
        fm_keys = get_frontmatter_keys(fm)
        for key in sorted(fm_keys):
            if key in copilot_only_fields:
                fail(f"Copilot-only field '{key}' present in CC file — {local_fname}")

    # Silently-ignored fields in plugin-scope CC file
    if file_provider == 'claude-code' and is_plugin_scope:
        fm_keys = get_frontmatter_keys(fm)
        for key in sorted(fm_keys):
            if key in plugin_ignored_fields:
                fail(f"plugin-silently-ignored field '{key}' present in plugin-scope CC file — {local_fname}")

    # Subagent-unavailable tools listed in tools field
    tools = extract_tools_list(fm)
    unavailable = tools & SUBAGENT_UNAVAILABLE_TOOLS
    for tool in sorted(unavailable):
        suggest(f"'{tool}' is listed in tools but is never available to subagents — the runtime withholds it regardless — {local_fname}")

# --- Check counterpart exists ---
if not os.path.isfile(counterpart):
    fail(f"counterpart file not found: {counterpart}")
    sys.exit(1)

# --- Check both files ---
is_plugin = (scope == 'plugin')
check_file(agent_file, provider, is_plugin)
check_file(counterpart, counterpart_provider, is_plugin)

for s in suggestions:
    print(f"SUGGESTION  {s}")

sys.exit(1 if failed else 0)
PYTHON