workshop-harness: Instructions file for Codex

AGENTS.md - Agent Instructions for Workshop Harness

Standard AI Agent Context & Instructions Specification (https://agents.md/)

This repository provides seamless integration for all AI Coding Agents including Google Antigravity, Gemini CLI, Anthropic Claude Code, OpenAI Codex / ChatGPT, Aider, and Cursor / Windsurf.

🎯 Repository Overview & Purpose

workshop-harness is an AI Agent Harness, Skill Suite, and CLI Automation Toolkit for technical workshops (Build with AI, DevFest, community coding labs).

• CLI Automation: python3 harness_cli.py
• 21 Agent Skills: Located under skills/*/SKILL.md
• Document Templates: Located under templates/doc-templates/

🤖 Natural Language Prompt ➔ Autonomous Skill Execution Rules

CRITICAL RULES FOR ALL AI CODING AGENTS (Antigravity, Claude Code, Codex, Cursor, Aider):

1. 🌐 Mandatory Autonomous Pre-Flight Web Search (workshop-web-researcher):
   • NEVER rely solely on LLM internal parametric training data when generating workshop curriculum, code samples, Colab notebooks, or setup guides. Parametric weights contain outdated/deprecated APIs and retired model tags.
   • You MUST AUTONOMOUSLY execute live web searches (search_web / web search) BEFORE writing any code or documentation to verify the newest SDK syntax (e.g. google-genai >= 2.30.1 SDK, @google/genai >= 2.29.1, google-adk, google-agents-cli, com.google.genai:google-genai-kotlin-android, google_generative_ai, genui), current model tags (e.g. gemini-4-argon, gemini-3.8-flash, gemini-3.8-live, gemini-nano-banana-2.1, gemini-omni-1.1-flash, claude-sonnet-5.5, claude-opus-5.5, gpt-6-astra, gpt-6.1-sol, gemma4, qwen3.6), and breaking changes.
2. 🌍 Developer-Friendly Terminology & Bilingual Technical Term Notation (영어 원문 병기 & 직역 금지):
   • When authoring or localizing documentation, .md files, slide decks, setup guides, runbooks, or code comments into Korean (KR), Japanese (JA), or Chinese (ZH), NEVER perform awkward literal / word-for-word machine translations.
   • Always pair localized developer-friendly terms with the original English technical term in parentheses (개발자 친화적 용어 (English Original)):
     • Korean (KO) + English Original: Use natural IT developer terminology with English original notation, e.g., 핸즈온 랩 (Hands-on Lab), 스캐폴딩 (Scaffolding), 런북 (Runbook), 프롬프트 엔지니어링 (Prompt Engineering), 구조화 출력 (Structured Outputs), 툴 콜링 / 함수 호출 (Tool Calling / Function Calling), 검색 증강 생성 (RAG, Retrieval-Augmented Generation), 임베딩 (Embedding), 양자화 (Quantization), 추론 예산 (Thinking Budget), 멀티 에이전트 오케스트레이션 (Multi-Agent Orchestration), 서브 에이전트 위임 (Sub-Agent Delegation), 궤적 평가 (Trajectory Evaluation), 의존성 주입 (Dependency Injection), 폴백 (Fallback). Never use awkward literal phrasing (e.g., ❌ "손으로 하는 실험실", ❌ "달리는 책", ❌ "발판 설치", ❌ "생각 예산", ❌ "도구 부르기").
     • Japanese (JA) + English Original: Use standard developer Katakana / technical terms paired with English (e.g., 「ハンズオンラボ (Hands-on Lab)」, 「スキャフォールディング (Scaffolding)」, 「構造化出力 (Structured Outputs)」, 「量子化 (Quantization)」, 「ランブック (Runbook)」).
     • Chinese (ZH) + English Original: Use Chinese tech community terminology paired with English (e.g., 「实战工作坊/动手实验 (Hands-on Lab)」, 「脚手架 (Scaffolding)」, 「结构化输出 (Structured Outputs)」, 「量化 (Quantization)」, 「演练手册 (Runbook)」).
     • Code Comments & Identifiers: Keep all SDK symbols, class/function names, and CLI flags in their exact English form (root_agent, LlmAgent, FunctionTool, thinking_budget, response_schema), and write comments using developer-friendly terminology with English terms in parentheses. See docs/agents-spec/terminology-and-style-guide.md.
3. 🚫 Typography Rule (No Em Dash in Markdown & Documentation):
   • NEVER generate em dash characters (\u2014) in any generated documentation, .md files, code comments, slide decks, setup guides, or runbooks.
   • Always use standard hyphens (-), colons (:), or parentheses () instead.
   • Enforce and auto-sanitize via python3 harness_cli.py audit-typography --target <dir> --fix (verified as a hard gate by python3 harness_cli.py test --target <dir>).
4. 🚫 No Emojis in Documentation (Default: Clean Professional Text):
   • Do NOT include emojis in generated documentation, slide decks, setup guides, code comments, or runbooks by default.
   • Only use emojis if the user explicitly requests them in their prompt (e.g., "use emojis in headings").
5. 🗣️ Natural Language Autonomy:
   • Users communicate via natural language chat prompts. Do NOT instruct users to run Python commands themselves.
   • When a user requests a task, you MUST autonomously read the relevant skills/*/SKILL.md and execute the appropriate harness CLI command or generate the code artifacts on behalf of the user.