# Agent Compatibility

This kit is designed as a local-first onboarding/RAG package that can be used by Codex, Claude Code, Cursor, GitHub Copilot, Gemini, Cline, and other file-aware coding agents.

## Compatibility Matrix

| Agent / Tool | Entry File | Role |
| --- | --- | --- |
| Codex | `AGENTS.md`, `skills/onboarding-buddy/SKILL.md` | Primary operating contract and optional local skill |
| Claude Code | `CLAUDE.md` | Thin adapter to shared kit contracts |
| Cursor | `.cursor/rules/onboarding-kit.mdc` | Project rule that points to shared kit contracts |
| GitHub Copilot | `.github/copilot-instructions.md` | Repository instructions for Copilot Chat / coding assistance |
| Gemini CLI | `GEMINI.md` | Thin adapter to shared kit contracts |
| Cline | `.clinerules` | Project rule that points to shared kit contracts |
| Other agents | `BOOTSTRAP.md` | First-run package warmup prompt |

## Shared Contract

All agent-specific adapters must remain thin. They should not duplicate business process details.

The authoritative shared files are:

- `AGENTS.md`
- `BOOTSTRAP.md`
- `HANDOFF.md`
- `MAINTAINERS.md`
- `.ai/context/`
- `kit.yaml`
- `sources/source-manifest.yaml`

## Standard First Message

```text
请以 BOOTSTRAP.md 的首次包接手模式启动；完成后，后续同一会话回答问题时不要重新全量读取整个包，先检索再打开命中文件。
```

## Standard Question Flow

1. Detect Python first. If Python 3.10+ is available, run `python3 scripts/search_knowledge.py "<question>" --top-k 3`.
2. Open only cited files needed to answer.
3. Check `sources/source-manifest.yaml` before citing source corpus files.
4. If evidence is insufficient, say unresolved and route to the relevant owner.
5. If Python is unavailable, ask before using `bootstrap.ps1` or `sh bootstrap.sh` to install uv, including before Q&A. Read `search/chunks.jsonl` and cited files manually only if the user declines installation or setup is blocked.

## Standard Maintenance Flow

1. Read `MAINTAINERS.md`.
2. Read only the affected module/source/context files.
3. Make scoped edits.
4. Run `python3 scripts/validate_kit.py`, or use user-approved uv bootstrap if Python 3.10+ is unavailable.
5. Run `python3 scripts/index_knowledge.py`.
6. Run `python3 scripts/bootstrap_session.py`.
7. Run `python3 scripts/search_knowledge.py "<representative query>" --top-k 3`.
8. Update `.ai/context/04-state-ledger.md` for meaningful maintenance changes.

## Do Not

- Do not copy full business rules into each adapter file.
- Do not answer from memory when local search can answer.
- Do not hand-edit generated search files.
- Do not store sensitive credentials or raw signed Feishu asset URLs.
