Agent Spec — Custom Hybrid v1.0

thiscode 의 모든 skill + command 는 .agents/<name>.yaml 파일 1개로 정의됩니다. 본 문서는 spec 구조를 설명합니다.

5 Block 구조

YAML 은 의미 단위로 5 block 으로 나뉩니다.

Block A — agentskills.io base (cross-tool compat)

name, description, version, license, homepage — Claude / Cursor / Aider 모두 인식 가능한 portable metadata.

name: bootstrap
description: Plugin first-run bootstrap — verifies tools, registers vault_root, prints status table ...
version: 1.0.0
license: MIT
homepage: https://github.com/treylom/ThisCode

Block B — Hermes provides_* (lifecycle registration)

플러그인이 호스트에 어떤 tool/hook/command 를 등록할지 명시.

provides_tools: [claude_discode_bootstrap]
provides_hooks: [on_session_start]
provides_commands: [/thiscode:setup]

Block C — thiscode extension (classroom policy)

외부 배포 사용 시 사용자가 안전하게 쓸 수 있도록 release tier + model 권장 + 허용 도구를 명시.

tier: external          # external (학생) | internal (운영) | experimental (PoC) | deprecated (graduate inverse)
model: opus[1m]
allowedTools: [Bash, Read, Glob, Grep, mcp__vault-search__*]

Block D — Dynamic gates (verification before release)

PR 머지 전 강제 검증 식. benchmark 결과 또는 측정값으로 평가. evaluator 두 가지 지원 (Round 3 CC1 Hybrid).

gates:
  - id: latency-p95
    expr: "latency_ms_p95 < 2000"
    evaluator: simple       # 단순 비교 식 — 자체 mini parser
  - id: complex-check
    expr: "results.filter(r => r.kg_depth > 2).length > 5"
    evaluator: cel          # 복잡 식 — CEL fallback (Common Expression Language)

evaluator: simple cheatsheet (5-7 예시)

# 비교
expr: "latency_ms < 2000"
expr: "recall_at_5 > 0.5"
expr: "count == 20"

# 논리
expr: "latency_ms < 2000 && recall_at_5 > 0.5"
expr: "tier == 1 || tier == 4"

# 괄호 그룹
expr: "(latency_ms < 1000 || recall_at_5 > 0.8) && cost_tokens < 1000"

simple parser 가 지원하는 연산: <, >, <=, >=, ==, !=, &&, ||, (). 변수는 benchmark 결과 column 명 (latency_ms_p95, recall_at_5, cost_tokens, setup_time_min, kg_depth).

evaluator: cel (Common Expression Language)

CEL spec: https://github.com/google/cel-spec — array traversal, string regex, time window 등 복잡한 식에 사용. v1.0에서는 거의 사용 안 함 — v1.1 에서 본격 도입 예정.

Block E — Benchmark integration

benchmark/ 디렉토리와 연결되는 fixture / axes / baseline 명시.

benchmark:
  fixtures: benchmark/fixtures/queries.yaml
  axes: [latency_ms, recall_at_k, cost_tokens, setup_time_min, kg_depth]
  baseline_tier: 4

새 agent 추가 가이드

1. .agents/<your-agent>.yaml 신규 생성 — 위 5 block 모두 포함 (Block D/E 는 optional, 단 external tier 는 권장)
2. npm run validate 또는 bash scripts/validate-agents.sh — JSON Schema 통과 확인
3. npm run index — agents.yaml index 갱신
4. PR 생성 — .github/workflows/validate-agents.yml 가 자동 검증

thiscode-model-router

검색 결과 받은 후 응답 생성 시 task complexity 따라 LLM 모델 선택:

• 단순 query → Haiku (Claude) / gpt-5.5 (Codex)
• 중간 query → Sonnet / gpt-5.5-codex
• 종합 query → Opus[1m] / gpt-5.5-codex-spark

scripts/route-model.mjs heuristic. user override --model haiku|sonnet|opus.

Tier 순서

ThisCode의 로컬 검색 도구용 스크립트는 scripts/install-*.sh에 있습니다. km 플러그인의 /km:search fallback은 GraphRAG → Obsidian CLI → Obsidian MCP → text search 순서로 실행하며, ThisCode의 vault-search MCP 설치기는 이 순서와 별개입니다. /km:setup은 km 설정 위저드이며 검색 도구를 설치하지 않습니다.

Tier 의미 (Round 2 outcome — 4개 enum)

관련 파일

• schemas/agent-spec.json — JSON Schema (validator source of truth, draft 2019-09)
• agents.yaml — index (auto-generated by scripts/generate-agents-index.mjs --apply)
• scripts/validate-agents.sh — pre-commit + CI
• scripts/check-agents-index.mjs — index roundtrip check
• hermes-plugin/plugin.yaml — plugin-level aggregation (each plugin provides_tools entry must be declared by .agents/*.yaml)

산업 reference

• agentskills.io — Claude/Cursor/Aider portable skill format
• Hermes Agent plugin — NousResearch lifecycle registration pattern
• LangChain agent-protocol — spec evolution (semver + deprecation timeline)
• Anthropic MCP tools/list — protocol version + capability negotiation
• Kubernetes CEL — 1억+ 프로덕션 사용, gates expression DSL 참고