# AI Agent Start Here

This file is the project-local entry point for AI agents working with RepoKey.
Read it before scanning the project or running tools.

## Project Variables

Replace these values after copying this file into a project:

```text
PROJECT_ROOT={{PROJECT_ROOT}}
REPOKEY_ROOT={{REPOKEY_ROOT}}
AI_STACK_ROOT={{AI_STACK_ROOT}}
VIVADO_PATH={{VIVADO_PATH}}
VITIS_PATH={{VITIS_PATH}}
VIVADO_CONTEXT_SRC={{VIVADO_CONTEXT_SRC}}
VITIS_MCP_CONFIG={{VITIS_MCP_CONFIG}}
PL_QOR_MCP_CONFIG={{PL_QOR_MCP_CONFIG}}
AMD_DOC_MCP_ENDPOINT={{AMD_DOC_MCP_ENDPOINT}}
```

## First Rule

Tools provide evidence. AI makes engineering decisions within evidence and
safety boundaries. Humans authorize design-intent changes.

## Tool Routing

Use the tool that owns the fact:

- RepoKey Vivado MCP: Vivado project, BD/IP/OOC, ILA/VIO, bitstream/LTX,
  Hardware Manager, PL evidence.
- PL-PS Handoff: PS-facing PL control delivery artifacts.
- PL QoR MCP: timing, fanout, utilization, QoR baseline, decision records, QoR
  comparison, reviewed experiment Tcl generation.
- Vitis MCP: Vitis build/run, XSCT, PS `test_mode`, RF front-end runtime/config,
  PS-side handoff consumption.
- AMD Doc MCP: official Vivado/Vitis/XDC/HLS/IP semantics.

## PL-PS Handoff

Use this when the task is to explain PL controls to PS, generate a handoff table,
compare an old Excel register map, or prepare PS delivery.

Generate the default handoff:

```powershell
{{REPOKEY_ROOT}}\repokey-client.cmd handoff pl2ps {{PROJECT_ROOT}} --output {{PROJECT_ROOT}}\pl_ps_handoff --summary-json
```

Expected outputs:

```text
pl_ps_handoff/
  control_handoff.xlsx
  control_handoff.json
  control_handoff.md
  ps_delivery.xlsx
  evidence.md
  ai_reading_guide.md
```

Use `control_handoff.xlsx` as the PL engineer review workbook. Use
`ps_delivery.xlsx` as the PS-facing delivery workbook.

Compare legacy Excel:

```powershell
{{REPOKEY_ROOT}}\repokey-client.cmd handoff compare-legacy {{PROJECT_ROOT}}\pl_ps_handoff\control_handoff.json <legacy.xlsx> --output {{PROJECT_ROOT}}\pl_ps_handoff\legacy_compare.json
{{REPOKEY_ROOT}}\repokey-client.cmd handoff merge-template {{PROJECT_ROOT}}\pl_ps_handoff\legacy_compare.json --output {{PROJECT_ROOT}}\pl_ps_handoff\merge_decision.json
```

Apply reviewed semantics:

```powershell
{{REPOKEY_ROOT}}\repokey-client.cmd handoff apply-feedback {{PROJECT_ROOT}}\pl_ps_handoff\control_handoff.json feedback_patch.json --output {{PROJECT_ROOT}}\pl_ps_handoff_patched --summary-json
{{REPOKEY_ROOT}}\repokey-client.cmd handoff delivery-from-review {{PROJECT_ROOT}}\pl_ps_handoff\control_handoff.json {{PROJECT_ROOT}}\pl_ps_handoff\control_handoff.xlsx --output {{PROJECT_ROOT}}\pl_ps_delivery_reviewed --summary-json
```

Handoff may write delivery artifacts. It must not modify Vivado RTL, XDC, XCI,
BD, or implementation outputs.

## PL QoR

Use PL QoR MCP when it is registered and visible. If the MCP namespace is not
visible, use the CLI adapter as the supported fallback and say that PL QoR MCP
registration is optional for this package.

QoR evidence belongs to the Vivado project, not the RepoKey tool directory.
Write QoR output under:

```text
{{PROJECT_ROOT}}\.vivado_ai_mcp\qor
```

本包不附带 pl_optimizer_compat 脚本。PL QoR 能力请使用已注册的 PL QoR MCP 工具：
`pl_qor_probe` / `pl_qor_collect_baseline` / `pl_qor_decide` / `pl_qor_compare` /
`pl_qor_make_experiment`。

Do not run optimization experiments automatically. `make-experiment` only
generates reviewed Tcl/manifest files.

## Vitis / PS

Use Vitis MCP or project-local Vitis helpers for PS runtime evidence only when
this project actually has PS/Vitis collateral. For PL-only projects, skip Vitis
checks and say they are not applicable.

For PS-side code understanding and PL/PS linkage, prefer the Vitis MCP
`ps_context_summary` tool before broad source reading. It writes:

```text
{{PROJECT_ROOT}}\.vivado_ai_mcp\ps_context\project_summary.json
{{PROJECT_ROOT}}\.vivado_ai_mcp\ps_context\agent_summary.md
```

Use it to find PS interrupt consumers, AXI register consumers, and driver entry
points. It does not modify PS code, run XSCT, or parse PL.

Preferred checks when the files exist:

```powershell
python {{PROJECT_ROOT}}\tools\vitis\debug_status.py
python {{PROJECT_ROOT}}\tools\vitis\handoff_consume_check.py
```

Use live PS/JTAG commands only when the board is powered and the user expects
hardware access.

## AMD Official Docs

Use AMD Doc MCP when official tool semantics matter:

```text
{{AMD_DOC_MCP_ENDPOINT}}
```

Required before recommending or applying:

- false path or multicycle constraints.
- clock/reset/CDC/RDC interpretation.
- Vivado implementation strategy changes.
- Vitis/XSCT behavior whose semantics are uncertain.
- Vitis HLS pragma/interface changes.
- AMD/Xilinx IP parameter interpretation.

AMD Doc MCP is not local project evidence. Pair it with RepoKey/Vitis evidence.

## Red Lines

Do not automatically do these:

- Modify RTL, XDC, XCI, BD, or Tcl project files.
- Manually edit Vivado run metadata such as `.vivado.begin.rst`,
  `.vivado.end.rst`, `.synth_design.begin.rst`, or `.synth_design.end.rst`.
  If run metadata looks stale or inconsistent, use a RepoKey repair tool
  (repair_run_metadata) and record evidence; RepoKey has no debug hub recovery
  path. Do not patch these files by hand.
- Execute PL optimization experiments.
- Add false path or multicycle path constraints.
- Change latency, AXI/stream protocol, CDC/RDC, clock/reset architecture.
- Change PS/PL handoff register semantics or address maps.
- Change RF front-end data alignment or behavior.

When any red line is involved, stop and ask for explicit human authorization.

## Smoke Tests

After setup, run the stack smoke test only if the script exists:

```powershell
if (Test-Path "{{AI_STACK_ROOT}}\scripts\smoke_test_mcp_stack.py") { python {{AI_STACK_ROOT}}\scripts\smoke_test_mcp_stack.py } else { Write-Host "RepoKey stack smoke script not packaged; skip optional smoke test." }
```

Expected result:

```text
ok: true
vitis_mcp_import: OK
pl_qor_mcp_import: OK
vitis_debug_status: OK
pl_qor_probe: OK
```
