# Prompt — Migrate an existing repo to MeshKore

Use this when the repo already has docs / tasks / credentials in some
ad-hoc layout (`_rjj/`, `_docs/`, `notes/`, `tasks.md`, anything) and
the operator says **"apply the MeshKore Standard to this repo"**.

The agent's job is to do this in one pass without asking the operator
to compose the procedure. Ask only the four questions in §1; everything
else is mechanical.

> Canonical URL: <https://meshkore.com/reference/prompts/migrate-existing-repo.md>
> Companion: <https://meshkore.com/reference/prompts/project-from-scratch.md>
> Standard:  <https://meshkore.com/standard>

---

## 1 · Ask the operator (always, before doing anything)

### Q1 — Where is the legacy content?

```
Default detection (in order):
  1. ./_rjj/         (the most common previous convention)
  2. ./_docs/
  3. ./docs/         (only if no .meshkore/docs/ exists yet)
  4. ./notes/
  5. ./tasks.md      (single file)
  6. "tell me where"
```

Look for any of these folders / files. If multiple, ask the operator
which is the source of truth.

### Q2 — Module layout

Show the operator the project's top-level code folders (`ls -1d */ |
grep -v node_modules`). Propose **one module per code folder** that
has meaningful work (typical: `api`, `webapp`, `extension`, `worker`,
`mobile`). Plus a `general` module for cross-cutting tasks. Confirm
or edit the list with the operator.

### Q3 — Existing credentials

If the legacy folder contains an `.env` or `credentials/`, ask:
*"Move these to `.meshkore/credentials/` with mode 0600 (recommended)
or leave in place?"* Default: move.

### Q4 — Backup the legacy folder?

Default: **yes**, tarball to `.meshkore/_archive/<folder>-<YYYYMMDD>.tar.gz`
so nothing is lost. Confirm the operator wants this (uses disk space
proportional to the legacy folder size).

Don't proceed past Q4 without explicit confirmation of the plan.

---

## 2 · Map legacy → canonical

Common mappings from `_rjj/`-style layouts:

| Legacy path | Canonical path | Notes |
|---|---|---|
| `_rjj/context/`               | `.meshkore/docs/architecture/`     | add §5 frontmatter |
| `_rjj/product/` / `_rjj/strategy/` | `.meshkore/docs/product/`     | add §5 frontmatter |
| `_rjj/conventions/`           | `.meshkore/docs/conventions/`      | add §5 frontmatter |
| `_rjj/deploy/`                | `.meshkore/docs/deploy/`           | add §5 frontmatter |
| `_rjj/security/`              | `.meshkore/docs/security/`         | add §5 frontmatter |
| `_rjj/ops/` / `_rjj/runbooks/` | `.meshkore/docs/ops/`             | add §5 frontmatter |
| `_rjj/tasklist/INDEX.md`      | `.meshkore/modules/<id>/tasks/`    | run `migrate-tasklist.py` |
| `_rjj/tasklist/<id>.md`       | `.meshkore/modules/<id>/tasks/`    | add §4 frontmatter |
| `_rjj/credentials/`           | `.meshkore/credentials/` (mode 0600) | NEVER commit |
| `_rjj/.env`                   | `.meshkore/credentials/<provider>.env` | NEVER commit |
| `_rjj/_backup/`               | `.meshkore/_archive/<name>.tar.gz` | tarball; gitignored |
| `_rjj/logs/` / `_rjj/daily/`  | `.meshkore/log/<YYYY-MM-DD>.md`    | one prose file per day |

Files without an obvious mapping go to `.meshkore/docs/ops/` with a
`status: draft` flag and a TODO comment. Never silently drop content.

---

## 3 · Execute (deterministic, in order)

### 3.1 Scaffold `.meshkore/` (standard §2)

```bash
cd <repo-root>
mkdir -p .meshkore/{public,docs,modules,credentials,log,timeline,protocols/log,_archive}
echo 6 > .meshkore/STANDARD_VERSION
```

### 3.2 Backup the legacy folder

```bash
LEGACY=_rjj   # or whatever Q1 resolved to
tar -czf .meshkore/_archive/${LEGACY}-$(date +%Y%m%d).tar.gz "${LEGACY}"
```

### 3.3 Write `.meshkore/public/cluster.yaml`

Pull the dev template:

```bash
curl -fsSL https://meshkore.com/reference/cluster/templates/cluster.yaml.dev \
  -o .meshkore/public/cluster.yaml
```

Fill `{{placeholders}}`, then add the `modules:` block from Q2:

```yaml
modules:
  - id: <module>
    kind: code
    path: <folder>/
    description: "<one line>"
  # repeat per module
  - id: general
    kind: area
    description: "Project-wide work without a specific module yet."
```

### 3.4 Migrate task lists

If the legacy folder has a tasklist INDEX, use the canonical script:

```bash
curl -fsSL https://meshkore.com/reference/cluster/scripts/migrate-tasklist.py \
  -o .meshkore/scripts/migrate-tasklist.py
python3 .meshkore/scripts/migrate-tasklist.py \
  ${LEGACY}/tasklist/INDEX.md .meshkore/
```

This writes one `.md` per task under `.meshkore/modules/<id>/{tasks,log}/`
with valid frontmatter.

If tasks live as scattered `.md` files (no INDEX), copy them per the
mapping table above and add frontmatter manually using the `task_frontmatter`
schema from <https://meshkore.com/standard.json>.

### 3.5 Migrate docs

For every doc under `${LEGACY}/<category>/*.md`:

1. Copy to `.meshkore/docs/<category>/<file>.md` (categories per §5).
2. Prepend §5 frontmatter (title, category, updated, owner, status).
3. Check the file is ≤ 200 lines (R2). If not, split or mark
   `status: draft` and tell the operator.

The `enrich-frontmatter.py` script automates step 2:

```bash
curl -fsSL https://meshkore.com/reference/cluster/scripts/enrich-frontmatter.py \
  -o .meshkore/scripts/enrich-frontmatter.py
python3 .meshkore/scripts/enrich-frontmatter.py .meshkore/docs/
```

### 3.6 Move credentials

If Q3 said "move":

```bash
mkdir -p .meshkore/credentials
[ -f "${LEGACY}/.env" ] && mv "${LEGACY}/.env" .meshkore/credentials/$(basename "${LEGACY}").env
chmod -R 0600 .meshkore/credentials
```

### 3.7 Update `.gitignore`

```bash
cat >> .gitignore <<'EOF'

# MeshKore — commit only the public bootstrap, the version marker,
# and the protocols playbook. Run logs stay per-machine.
.meshkore/*
!.meshkore/public/
!.meshkore/STANDARD_VERSION
!.meshkore/protocols/
.meshkore/protocols/log/
EOF
```

### 3.8 Drop the editor boot block

Pick the operator's primary editor:

```bash
curl -fsSL https://meshkore.com/reference/cluster/editor-rules/CLAUDE.md \
  -o ./CLAUDE.md    # or .cursorrules / .windsurfrules
```

`CLAUDE.md` already starts with `# MeshKore Standard` (the
self-identifying header) so future operators recognise the file at a
glance.

### 3.9 Download the daemon

```bash
mkdir -p .meshkore/scripts
curl -fsSL https://meshkore.com/reference/cluster/scripts/daemon.py \
  -o .meshkore/scripts/daemon.py
```

### 3.10 Verify

```bash
curl -fsSL https://meshkore.com/reference/cluster/scripts/verify.py \
  -o .meshkore/scripts/verify.py
python3 .meshkore/scripts/verify.py
```

The script checks: folder layout matches §2 · `public/cluster.yaml`
validates · every task / doc has the required frontmatter · gitignore
contract present · `STANDARD_VERSION` matches the published version.
Abort and tell the operator if it returns non-zero.

### 3.11 Start the daemon

```bash
python3 .meshkore/scripts/daemon.py
```

Confirm the printed port + bearer token. The architect at
<https://architect.meshkore.com> auto-discovers the daemon.

### 3.12 Report

```
Done. Migrated <N> docs and <M> tasks from `<legacy>/` to .meshkore/.
The legacy folder is tarballed at .meshkore/_archive/<name>.tar.gz.
Daemon listening on http://localhost:<port>.
Open https://architect.meshkore.com — the architect will pick it up.

Run /standard/CHANGELOG.md before the next session to catch up on any
standard updates since today.
```

---

## 4 · Failure modes — what to do

- **Catalog unreachable** (`curl` to `meshkore.com/reference/...` fails):
  tell the operator the daemon needs an online catalog for first-time
  install. Suggest they download `daemon.py` manually from
  <https://meshkore.com/reference/cluster/scripts/> when reachable.
- **Legacy folder is huge** (> 100 MB): warn before tarballing. The
  archive lands at `.meshkore/_archive/` which is gitignored, but local
  disk space is real.
- **Doc over 200 lines** (R2): set `status: draft` in frontmatter and
  add a `TODO: split per R2` comment at the top. Don't silently truncate.
- **Existing `.meshkore/` folder**: do not overwrite. Ask the operator
  whether to merge into the existing one or start fresh after a backup.
- **Operator says "don't tarball the legacy"**: skip step 3.2 but leave
  the legacy folder in place — never delete unilaterally.

---

## 5 · Things you must NEVER do

- Delete the legacy folder without an explicit operator confirmation.
- Commit `.meshkore/credentials/` or anything outside `.meshkore/public/`.
- Push to `origin` without asking the operator.
- Invent module IDs the operator didn't approve.
- Skip §3.10 verify — that's the only end-to-end check that the
  migration actually conforms to the standard.

---

## See also

- [Project-from-scratch wizard](https://meshkore.com/reference/prompts/project-from-scratch.md)
  (for empty repos)
- [Standard, §2 folder layout](https://meshkore.com/standard#2-folder-layout)
- [Standard, §5 docs frontmatter](https://meshkore.com/standard#5-doc-frontmatter)
- [Standard CHANGELOG](https://meshkore.com/standard/CHANGELOG.md)
- [Cluster install (human page)](https://meshkore.com/cluster/install)