Villa Knowledge Base

Agent integration

Properties1
tagsagents, cursor, tooling, workflow

3 min read

Agent integration

How to wire an AI agent into this vault so it reads before working and writes after fixing. The goal is that an agent picking up a Villa ticket next month starts from what we already learned rather than from zero.

Get the vault locally

Agents should work against a clone, not the website — ripgrep over local markdown is faster than fetching pages, works offline, and is the same content.

KB=~/stacks/villa-knowledge-base
[ -d "$KB" ] || git clone git@github.com:villa-market/villa-knowledge-base.git "$KB"
git -C "$KB" pull --rebase --quiet

Always pull first. A stale clone is how an agent confidently reports a fix that was reverted last week.

Search patterns

Frontmatter is the index — filter on it before reading bodies.

rg -i "always nationwide" content -l          # the reporter's wording
rg -l "systems:.*villacoupon3" content        # everything touching one service
rg -l "^type: runbook" content                # procedures only
rg -l "^status: open" content                 # unfinished work
rg -l "tags:.*service-worker" content         # by theme

Search symptoms before causes. Testers report behaviour (“no discount”), and symptoms: exists so their wording matches an old incident even when the underlying fault is described in entirely different terms.

Cursor

A global rule at ~/.cursor/rules/villa-knowledge-base.mdc (alwaysApply: true) tells every Cursor agent to search the vault before touching Villa systems and to write findings back. Each Villa service repo also carries a short .cursor/rules/knowledge-base.mdc pointing here, so the instruction survives even if the global rule is missing on a fresh machine.

Keep both concise. Rules compete for attention with the actual task; a rule nobody can act on in one step gets skipped.

Other harnesses

Claude Code, Codex and similar tools read AGENTS.md from the repo root, which already contains the schema and writing rules. For agents that only accept a system prompt, this is the minimum that works:

Before debugging Villa Market systems, search ~/stacks/villa-knowledge-base/content with ripgrep — by the reporter’s exact words first, then by system. After fixing anything, add or update a note there and push.

Writing back

The write-back step is the one that gets dropped under time pressure, and it is the only reason the vault stays useful. Do it in the same session as the fix, while the detail is still in context.

What goes where is in AGENTS.md; in short, incidents are a dated record and are never rewritten, while systems, references and runbooks describe current reality and should read as if written today.

Publish and push together — the site and the repo should never disagree:

cd ~/stacks/villa-knowledge-base
AWS_PROFILE=villaai ./infra/publish.sh
git add -A && git commit -m "..." && git push

A mistyped wikilink renders as plain text rather than failing the build, so nothing tells you it broke:

python3 - <<'PY'
import re, pathlib
notes = {p.stem for p in pathlib.Path('content').rglob('*.md')}
for p in pathlib.Path('content').rglob('*.md'):
    for m in re.finditer(r'\[\[([^\]|#]+)', p.read_text()):
        if m.group(1).strip() not in notes:
            print('broken:', m.group(1).strip(), '<-', p)
PY

What not to write

No secrets, API keys or customer data. Account IDs, ARNs and distribution IDs are fine and genuinely useful — “the Lambda” is meaningless in six months when there are four of them.

Don’t paste raw console dumps. Quote the response field or log line that settles the question and cut the rest.

Don’t create a near-duplicate note because editing an existing one feels intrusive. Two half-right notes on the same system are worse than one that has been corrected.

Graph View

Backlinks