# Prompt — Audit a repo for MeshKore readiness

Use this to audit an existing repository: is it set up correctly? Are
there gaps? What needs migrating? The agent reports a punch list. **It
does not modify anything.**

---

## 1 · Ask the user (one question)

### Q1 — Audit scope

```
1. quick   — check basics (.meshkore/ exists, gitignore, cluster.yaml valid)
2. full    — quick + frontmatter validation + protocol reachability + agents
3. deep    — full + cross-reference all docs, find dead links, suggest cleanups
```

Default: 2 (full). Most useful starting point.

If the user says "just tell me if it's broken" → quick. If they say
"give me a remediation plan" → full or deep.

---

## 2 · Run the checks

### 2.1 Repo basics (always)

- `git status` runs without error → git repo present.
- Working tree clean? Note dirty paths if any.
- Default branch from `git rev-parse --abbrev-ref HEAD`.
- Remote configured? `git remote -v`.

### 2.2 `.meshkore/` presence (always)

- `.meshkore/public/cluster.yaml` exists and is valid YAML.
- `.gitignore` contains `.meshkore/*` and `!.meshkore/public/`.
- Legacy `.meshkore` JSON file present (pre-2026-05)? → flag for migration.
- Daemon runtime files in `.meshkore/.runtime/` (any active daemon)?

### 2.3 Cluster spec compliance (full + deep)

Validate `cluster.yaml` against the schema:

```
curl -fsS https://meshkore.com/reference/cluster/schemas/cluster.v1.json
```

Fields to check: `version`, `id`, `type`, `name`, `transport.endpoint`.
Try the transport endpoint with HTTP HEAD (it should respond 200 or
upgrade to WS).

### 2.4 Bootstrap URLs (full + deep)

For each URL in `cluster.yaml.bootstrap`, do a `curl -I`:
- `hub.meshkore.com` → 200
- `meshkore.com/cluster/install` → 200
- `meshkore.com/standard/spec` → 200 (or 404 if not yet deployed)

Report any 4xx/5xx.

### 2.5 Daemon readiness (full + deep)

- `python3 --version` ≥ `3.8`? (stdlib-only Python daemon needs nothing else)
- `.meshkore/scripts/daemon.py` present? (or downloadable from
  `https://meshkore.com/reference/cluster/scripts/daemon.py`)
- `curl -fsS http://localhost:5570/health` → 200? If yes, capture
  `implementation`, `features[]`, and `cluster_id` from the response.
  If the port is busy, scan `5570–5589` (the daemon picks the first free).
- If a daemon is up, `GET /info` returns the daemon version and paths —
  compare against `cluster.yaml.min_daemon_version` (if set).

### 2.6 Agent identities (full + deep)

- `.meshkore/agents/` populated? At least one for `dev` clusters.
- Each `agents/<id>.yaml` references a `credentials:` file that exists
  in `.meshkore/credentials/`.
- All `.meshkore/credentials/*` files are gitignored.

### 2.7 Roadmap and docs (full + deep)

- `.meshkore/roadmap/` exists.
- `python3 .meshkore/scripts/roadmap-build.py --validate` exits 0.
- Number of tasks per status (counts).
- `.meshkore/docs/` follows the seven-category taxonomy:
  `architecture/, product/, conventions/, modules/, deploy/, security/, ops/`.
- Frontmatter present on every `.md` (except `INDEX.md`, `README.md`,
  `governance.md`).

### 2.8 Portal (full + deep)

- `.meshkore/portal/index.html` present? Non-empty?
- If a daemon is running, `curl http://localhost:5570/health` returns 200.

### 2.9 Cross-references (deep only)

- Every `related:` path in doc frontmatter points to an existing file.
- No `[link](path.md)` in markdown is broken.
- No file >200 lines (R2 violation) — list them.
- No two files claim the same canonical topic (R3 violation, harder to
  detect — heuristic: same H1 title in different categories).

---

## 3 · Output format

```
MESHKORE AUDIT — <repo-name> — <date>

✓ Done items
   .meshkore/ present
   gitignore correctly configured
   cluster.yaml v1 valid
   …

✗ Missing items   (with the exact remediation step)
   No agent identity declared.
     → Create .meshkore/agents/$(hostname)-claude-code.yaml with:
         id: $(hostname)-claude-code
         kind: claude-code
         role: developer
         permissions: edits

⚠ Warnings        (non-blocking but worth noting)
   3 docs over 200 lines:  modules/relay.md (180), deploy/INFRA-PROPOSAL... (233), …
     → Consider splitting per R2.

VERDICT: READY-WITH-WARNINGS
```

Verdicts:
- **READY** — all checks pass, nothing actionable.
- **READY-WITH-WARNINGS** — works fine but has lint-level issues.
- **NEEDS-ATTENTION** — failing checks, won't run cleanly.
- **NEEDS-MIGRATION** — legacy structure detected (`_rjj/`, single
  `.meshkore` JSON file, etc.); refer to migration plan.

---

## 4 · Things you must NEVER do

- Modify any file. This is read-only.
- Run `meshcore` mutating commands (init, start, etc.). Only diagnostics.
- Commit anything.
- Skip Q1 — let the user pick the depth.

---

## See also

- [`/reference/prompts/project-from-scratch.md`](https://meshkore.com/reference/prompts/project-from-scratch.md) — install if missing
- [`/standard/spec`](https://meshkore.com/standard/spec) — formal spec