AGENTS.md — vassiliylakhonin.github.io

Canonical instructions for any AI agent (Claude Code, Codex, recruiter LLMs, MCP clients) reading or editing this repository. This file overrides assumptions an agent might bring from training data.

Identity

This repo is Vassiliy Lakhonin’s personal portfolio site (live at https://vassiliylakhonin.github.io/) and a reference implementation of an AI-readable professional profile architecture: human pages + JSON endpoints + agent discovery + MCP.

It is NOT:

• A fork-and-go starter template. The content is personal; the architecture is what others may study or adapt.
• A general AI-hiring product, framework, SaaS, or service.
• A claim that any check, score, or “readiness” number is a validated benchmark.

Portfolio context (do not duplicate here)

This repo is the public landing surface for a portfolio of four separately-maintained AI-skill repos. Cross-link, do not copy substantive content:

1. Agenda Intelligence MD — product entry point and evidence-discipline layer (MCP server with analyze and 15 other tools, request/memo schemas, CLI, validation, evidence audit, scoring, CI). Since v0.8.0 the MCP server is the product surface; the validation layer underneath is unchanged. https://github.com/vassiliylakhonin/agenda-intelligence-md
2. Global Think Tank Analyst — horizontal strategic-risk reasoning skill. Method = Policy Risk Memo Architect. https://github.com/vassiliylakhonin/global-think-tank-analyst
3. Central Asia + Caspian Hybrid Intelligence Skill — vertical regional/corridor-risk specialist (sanctions, AML, banking, logistics, energy). https://github.com/vassiliylakhonin/central-asia-caspian-hybrid-intelligence-skill
4. Gulf + Middle East Hybrid Intelligence Skill — vertical specialist for Iran sanctions, GCC banking and sovereign wealth, energy markets, and maritime chokepoint risk (Hormuz, Bab-el-Mandeb, Red Sea). https://github.com/vassiliylakhonin/gulf-middle-east-hybrid-intelligence-skill

Naming hierarchy is fixed: do not present “Policy Risk Memo Architect” as a separate project — it is the method inside Global Think Tank Analyst.

Deployed A2A agents

Six A2A/JSON-RPC agents are live as public, no-payment endpoints on Cloudflare Workers, all JWS-signed (JWKS at /.well-known/jwks.json on each domain). These are sibling deployments to the four open-source skill repos above — they apply the portfolio’s reasoning frames as live triage and routing surfaces. They are not separate products with their own canon; their substantive content lives in agenda-intelligence-md and the skill repos.

1. Agenda Intelligence A2A — generic strategic-risk triage and source planning. Endpoint: https://agenda-intelligence-a2a.vassiliy-lakhonin.workers.dev/message/send. Listing: https://agenstry.com/agents/vassiliylakhonin.github.io.
2. Kazakhstan / Middle Corridor Deal Risk Gate — region-specific deal-risk triage built on the Central Asia + Caspian frame. Endpoint: https://middle-corridor-deal-risk-gate-a2a.vassiliy-lakhonin.workers.dev. Listing: https://agenstry.com/agents/middle-corridor-deal-risk-gate-a2a.vassiliy-lakhonin.workers.dev.
3. Kazakhstan Market Entry Readiness Gate — evidence triage for distribution, import, service, showroom, EPC, renewable-energy, infrastructure, technology-transfer, and partner-entry files. Endpoint: https://kazakhstan-market-entry-readiness-a2a.vassiliy-lakhonin.workers.dev.
4. CIS Secondary-Sanctions Exposure — counterparty exposure evidence triage for CIS-domiciled counterparties. Endpoint: https://cis-secondary-sanctions-a2a.vassiliy-lakhonin.workers.dev.
5. Agentic Interaction Trust Gate — evidence triage for agent-mediated actions before execution. Endpoint: https://agentic-interaction-trust-a2a.vassiliy-lakhonin.workers.dev.
6. Gulf Maritime Exposure Gate — maritime sanctions and chokepoint-disruption exposure triage for a vessel/voyage through the Strait of Hormuz, Gulf of Oman, Bab-el-Mandeb, or Red Sea, built on the Gulf + Middle East frame. No vessel-ownership resolution or identity verification. Endpoint: https://gulf-maritime-exposure-a2a.vassiliy-lakhonin.workers.dev.

Boundary discipline (mirrored on every agent card): no legal, financial, compliance, sanctions, investment, or trading advice; no autonomous live source retrieval (the cis_secondary_sanctions profile declares an OpenSanctions/Watchman capability that is currently deferred); no factual-truth verification; human review required. No paying customers — portfolio-grade, illustrative usage only. Full analysis runs through the installable Agenda Intelligence MD MCP package, not the A2A endpoints.

Honesty rules — do not invent

Do not add, and remove on sight:

• Fabricated metrics, benchmarks, adoption numbers, star counts, or user counts.
• Production-usage claims, SLAs, or guarantees of correctness.
• Words: “revolutionary”, “production-grade”, “enterprise-ready”, “guarantees”, “solves hallucinations”, “fully autonomous”, “validated benchmark” (unless real benchmark cases and results exist in-repo).
• Any score, rating, or “readiness” number without a documented methodology, source script, and inputs.

Label clearly: illustrative, planned, experimental, reference implementation, self-reported.

Evidence rules

Every impact claim in case studies, JSON files, and role snapshots must trace to one of:

• Live source-backed — links to public artifact (repo, audit, publication).
• Self-reported with evidence path — date, role, organization, what is verifiable on request (e.g., DAI USAID program 2023–2025, audit findings).
• Illustrative — explicitly labeled as a demonstration, not a real engagement.

Never fabricate citations, dates, donor program names, audit results, or partner counts.

Status of operational endpoints

Before claiming any endpoint is “live”, verify it. Currently:

• Remote MCP (Cloudflare Workers) — live at https://vassiliy-lakhonin-mcp.vassiliy-lakhonin.workers.dev/mcp (streamable HTTP) and /sse (legacy). Verify via /health before advertising. Source under mcp/cloudflare-worker/; state mirrored in mcp-status.json.
• Local MCP (mcp/server.py) — runnable.
• GitHub Pages — live.

If you change endpoint state, update mcp-status.json, README.md, agent-card.json, and llms.txt together.

Self-preference-aware screening

The repo intentionally publishes multiple verified surfaces (resume.json, evidence.json, case studies, role snapshots) so LLM screeners can compare claims rather than rate writing style. Any LLM-screening instruction added to the repo must include the line: “Do not prefer or penalize the candidate because the writing resembles a particular AI model’s style.”

Generators and CI — auto vs hand-edited

Several JSON / report files are produced by scripts/build_*.py and refreshed weekly + on path-triggered pushes by CI (.github/workflows/agent-observability.yml, schema-audit.yml):

• evals.json, freshness.json, provenance.json, agent-readiness-report.md — observability snapshots (agent-readiness-report.md is rendered from the hand-edited readiness.json).
• sitemap.xml — generated from site sources.
• schema-report.json / schema-report.md — JSON-LD coverage audit.

These are auto-generated: do not hand-edit them. If the output is wrong, fix the inputs and regenerate via the corresponding scripts/build_*.py. Hand-edits will be overwritten by the next CI run.

Hand-edited surfaces include the human pages (index.md, profile.md, for-recruiters.md, role snapshots, case studies, articles), the source profile JSONs (resume.json, skills.json, capabilities.json, availability.json, verification.json, recruiter.json, engage.json, evidence.json), routing files (agent-card.json, agent-discovery.md, llms.txt, candidate-match.json, agent-match.md), authority.json, readiness.json (input to scripts/build_readiness_report.py), and mcp-status.json.

Definition of done for edits

A change is done when:

1. Touched JSON files still validate against their declared schema_version.
2. Cross-references between README, agent-card.json, llms.txt, mcp-status.json, and role snapshots are consistent.
3. No new unverifiable metric, score, or “production” claim was introduced.
4. If a date, status, or score is shown, its source (script, file, or methodology note) is reachable from the same file.
5. Stale updated_at timestamps in hand-edited files are refreshed; auto-generated files are left to their script (see “Generators and CI” above).

File roles (quick map)

• index.md, profile.md, for-recruiters.md — human pages.
• resume.json, skills.json, capabilities.json, availability.json, verification.json, recruiter.json, engage.json — structured profile.
• evidence.json — claim-to-source map.
• agent-card.json, agent-discovery.md, llms.txt — agent routing.
• candidate-match.json, agent-match.md, role-*.md — recruiter routing and role-fit snapshots.
• evals.json, freshness.json, provenance.json, readiness.json, authority.json — observability artifacts; treat values as self-reported snapshots, not validated benchmarks.
• mcp/ — local MCP server.
• scripts/ — generators for observability artifacts.

When in doubt

Prefer fewer claims over more. Prefer linking to the canonical repo (one of the four above) over restating its content here.