neovim-dots/.opencode/astronvim-v6-migration-orchestrator-execution-prompt.md

# Orchestrator Execution Prompt: AstroNvim v6 migration

## Purpose

This prompt teaches the orchestrator how to interpret and execute the authoritative migration plan:

```text
.opencode/astronvim-v6-neovim-0-12-treesitter-migration-atomic-git-plan.md
```

The plan file is law. The orchestrator must treat it as the source of truth for scope, order, constraints, branch strategy, atomic commits, testing, and rollback behavior.

This execution prompt does not replace the plan. It explains how to operationalize it safely with subagents and atomic git operations.

## Prime directive

Before doing any implementation, the orchestrator must read:

```text
.opencode/astronvim-v6-neovim-0-12-treesitter-migration-atomic-git-plan.md
```

Then execute that plan in order.

If this prompt and the plan conflict, the plan wins.

If runtime observations conflict with the plan, stop and ask the user before deviating, unless the change is clearly non-destructive diagnostic work.

## Mission summary

Migrate the user's modified AstroNvim v5-based Neovim dotfiles to an AstroNvim v6-compatible configuration to fix Neovim 0.12 Tree-sitter crashes, while preserving the user's commits and using atomic git operations on a dedicated migration branch.

Known root issue:

```text
Neovim 0.12 + AstroNvim v5 + old nvim-treesitter master/snapshot = incompatible
```

Supported target:

```text
Neovim 0.12 + AstroNvim v6 + nvim-treesitter main-compatible snapshot
```

## Non-negotiable constraints

1. Work on a dedicated branch:

   ```text
   migrate/astronvim-v6-nvim-0.12
   ```

2. Do not work directly on `main` except to inspect or when the user explicitly asks.

3. The user will merge back to `main` manually when satisfied.

4. Use atomic commits. Each commit should represent one logical step.

5. Preserve current WIP before changing it.

6. Do not edit Lazy plugin checkouts directly:

   ```text
   ~/.local/share/nvim/lazy/AstroNvim
   ~/.local/share/nvim/lazy/nvim-treesitter
   ```

7. Do not merge `AstroNvim/AstroNvim` upstream history into the user's dotfiles repo.

8. Consume AstroNvim updates through Lazy and `lazy-lock.json`.

9. Do not use force operations unless the user explicitly approves.

10. Do not hide lockfile weirdness. Inspect and report it.

11. Do not commit a known-bad `nvim-treesitter` state where the lockfile says `branch = "main"` but still points to old commit `42fc28ba...`, except in the initial checkpoint commit whose purpose is to preserve pre-migration state.

12. If branch already exists, stop and ask before reusing, resetting, or creating a suffixed branch.

## Required orchestration paradigm

Use this loop for implementation:

```text
worker -> reviewer -> commit-worker if pass
```

### Worker

The worker performs one atomic implementation unit only.

Examples:

- create/check out migration branch
- checkpoint current WIP
- change AstroNvim version constraint
- migrate Tree-sitter config to AstroCore style
- run Lazy sync and capture results
- refresh lockfile
- perform one follow-up fix if tests reveal an issue

The worker should return:

- files changed
- exact diff summary
- commands run
- outputs/errors
- whether it believes the unit is complete
- whether review is needed before commit

### Reviewer

The reviewer checks the worker's changes before committing.

Reviewer must verify:

- changes match the plan
- only intended files changed
- no Lazy plugin checkout files were modified
- no unrelated source edits slipped in
- lockfile changes are expected for the current phase
- config syntax/startup checks pass where applicable
- Tree-sitter migration uses AstroCore v6 style, not old `nvim-treesitter.configs` style
- commit message matches the atomic unit

Reviewer should return one of:

```text
PASS
PASS_WITH_NOTES
FAIL
```

If FAIL, explain exactly what must be fixed.

### Commit-worker

Only after reviewer PASS or user-approved PASS_WITH_NOTES, the commit-worker stages the precise files for that atomic unit and commits them.

Commit-worker must:

- run `git status --short --branch` before staging
- stage only intended files
- run `git diff --cached --stat`
- run `git diff --cached` if needed for sanity
- create the commit with the planned message
- run `git status --short --branch` after commit

Do not use `git add -A` except for the initial checkpoint commit, where preserving current WIP exactly is intentional.

## Parallelization strategy

Parallelize read-only audits and research. Do not parallelize state-changing steps that depend on git branch, file contents, Lazy lockfile state, or plugin runtime state.

Good parallel tasks:

- Search for v6-renamed plugin repository names.
- Search for removed plugin references.
- Inspect AstroLSP config for v6-breaking patterns.
- Inspect Mason/tree-sitter-cli assumptions.
- Inspect AstroCommunity imports.
- Research/update docs if uncertainty appears.

Do not parallelize:

- branch creation/check out
- commits
- Lazy sync/update
- lockfile refresh
- edits to the same file
- cleanup of runtime/plugin folders

## Subagent templates

### Worker subagent template

Use this when asking a worker to perform a single atomic unit:

```text
You are a worker subagent. Execute exactly one atomic unit from the authoritative plan.

Authoritative plan:
.opencode/astronvim-v6-neovim-0-12-treesitter-migration-atomic-git-plan.md

Current atomic unit:
<describe unit>

Constraints:
- Follow the plan exactly.
- Do not modify Lazy plugin checkouts under ~/.local/share/nvim/lazy/.
- Do not touch unrelated files.
- Do not commit unless explicitly instructed that you are the commit-worker.
- Report commands run, files changed, diff summary, and any blockers.

Expected output:
- status: complete/blocked
- files changed
- commands run
- concise diff summary
- tests/checks run
- recommended next step
```

### Reviewer subagent template

Use this before every commit:

```text
You are a reviewer subagent. Review the current uncommitted changes against the authoritative plan.

Authoritative plan:
.opencode/astronvim-v6-neovim-0-12-treesitter-migration-atomic-git-plan.md

Atomic unit under review:
<describe unit>

Check:
- Does the diff match the plan?
- Are only intended files changed?
- Are there unrelated lockfile/source changes?
- Are Lazy plugin checkouts untouched?
- Are tests/checks sufficient for this unit?
- Is the proposed commit message accurate?

Return exactly one verdict: PASS, PASS_WITH_NOTES, or FAIL.
Then provide concise rationale and required fixes if any.
```

### Commit-worker template

Use only after review passes:

```text
You are the commit-worker. Commit exactly the reviewed atomic unit.

Authoritative plan:
.opencode/astronvim-v6-neovim-0-12-treesitter-migration-atomic-git-plan.md

Reviewed atomic unit:
<describe unit>

Files to stage:
<explicit file list>

Commit message:
<exact commit message>

Rules:
- Run git status before staging.
- Stage only listed files, unless this is the initial checkpoint commit.
- Show cached diff/stat before committing.
- Commit with the exact message.
- Show git status after committing.
- Do not amend, reset, rebase, or force push.
```

## Ordered execution phases

The orchestrator must follow the phases from the plan. Summary below; use the actual plan file for details.

### Phase 1: Inspect and create migration branch

Commands:

```bash
cd /home/kbot/.config/nvim
git status --short --branch
git log --oneline --decorate -8
git switch -c migrate/astronvim-v6-nvim-0.12
```

If branch exists, ask user before proceeding.

### Phase 2: Checkpoint current WIP

If dirty:

```bash
git add -A
git commit -m "checkpoint: preserve pre AstroNvim v6 migration state"
```

This is the only phase where `git add -A` is acceptable by default.

### Phase 3: Migrate AstroNvim version constraint

File:

```text
lua/lazy_setup.lua
```

Change:

```lua
version = "^5"
```

to:

```lua
version = "^6"
```

Keep `pin_plugins = nil`.

Commit message:

```text
chore: migrate AstroNvim constraint to v6
```

### Phase 4: Migrate Tree-sitter config to AstroCore

File:

```text
lua/plugins/treesitter.lua
```

Final shape should configure `AstroNvim/astrocore`, not direct old-style `nvim-treesitter` opts:

```lua
-- Customize Treesitter through AstroCore for AstroNvim v6

---@type LazySpec
return {
  {
    "AstroNvim/astrocore",
    ---@type AstroCoreOpts
    opts = {
      treesitter = {
        ensure_installed = {
          "lua",
          "vim",
          "vimdoc",
          "markdown",
          "markdown_inline",
        },
        highlight = true,
        indent = true,
      },
    },
  },
}
```

Commit message:

```text
refactor: migrate treesitter config to AstroCore
```

### Phase 5: Audit plugin rename/removal references

Read-only searches first. Only edit if active source references are found.

Renamed plugin names:

```text
Saghen/blink.cmp                  -> saghen/blink.cmp
echasnovski/mini.icons            -> nvim-mini/mini.icons
williamboman/mason.nvim           -> mason-org/mason.nvim
williamboman/mason-lspconfig.nvim -> mason-org/mason-lspconfig.nvim
```

Removed plugin refs:

```text
JoosepAlviste/nvim-ts-context-commentstring
folke/neoconf.nvim
kevinhwang91/nvim-ufo
RRethy/vim-illuminate
```

Planning audit found no active source edits needed. Confirm anyway.

### Phase 6: Audit AstroLSP

Planning audit found no changes likely needed. Confirm no active root-level `capabilities`, root-level `flags`, old default handlers, `require("lspconfig")`, or `require("astrolsp").lsp_opts`.

Only edit if current code proves otherwise.

### Phase 7: Review Mason tree-sitter-cli

Planning audit found `tree-sitter-cli` in Mason config. Keep unless health checks prove it wrong.

Do not remove proactively.

### Phase 8: Lazy sync/update

Run through Neovim/Lazy, not by editing plugin checkouts.

Preferred interactive commands:

```vim
:Lazy sync
:TSUpdate
:checkhealth nvim-treesitter
:checkhealth vim.lsp
```

Headless alternative if appropriate:

```bash
nvim --headless "+Lazy! sync" +qa
nvim --headless "+TSUpdate" +qa
```

Do not run `:Lazy restore` unless rolling back.

### Phase 9: Commit lockfile refresh

Inspect first:

```bash
git diff -- lazy-lock.json
rg '"nvim-treesitter"|"AstroNvim"|"astrocore"|"astrolsp"|"nvim-treesitter-textobjects"|"nvim-ts-autotag"' lazy-lock.json
```

Verify old `nvim-treesitter` commit `42fc28ba...` is gone after successful sync.

Commit message:

```text
chore: refresh lazy lockfile for AstroNvim v6
```

### Phase 10: Verification

Minimum checks:

```bash
nvim --headless +'lua print("startup ok")' +qa
nvim --headless '+checkhealth nvim-treesitter' +qa
```

Manual markdown fenced-code test:

````markdown
# Tree-sitter crash test

```lua
print("hello")
```

```bash
echo hello
```
````

Open with:

```bash
nvim /tmp/treesitter-crash-test.md
```

Confirm no `range()` nil crash.

Also check:

```vim
:checkhealth vim.lsp
:Lazy show nvim-treesitter
```

## Optimal execution notes

1. Start with local diagnostics; do not assume branch/dirty state from prior conversation.
2. Create branch first, then checkpoint WIP.
3. Make source migration commits before running Lazy sync.
4. Keep lockfile refresh as its own commit.
5. Use reviewers before each commit.
6. Use parallel read-only audits after source commits but before Lazy sync if uncertainty remains.
7. Treat unexpected Lazy/plugin changes as review events, not automatic success.
8. Prefer fixing config source over manually mutating lockfile unless the plan explicitly says otherwise.
9. If Neovim startup crashes after v6 constraint change, inspect error and fix config source; do not edit plugin checkout.
10. Keep the repo on the migration branch when done so the user can inspect and merge manually.

## Done criteria

The orchestrator may report the migration ready for user review only when:

- branch is `migrate/astronvim-v6-nvim-0.12`
- working tree is clean
- commits are atomic
- `lua/lazy_setup.lua` tracks AstroNvim `^6`
- Tree-sitter config uses AstroCore v6 style
- `lazy-lock.json` has been refreshed by Lazy
- `nvim-treesitter` is not locked to old `42fc28ba...`
- startup check passes
- Tree-sitter health is acceptable or documented
- markdown fenced-code test no longer triggers the `range()` nil crash
- user has a clear merge command

## User handoff message template

When done, report:

```text
Migration branch ready: migrate/astronvim-v6-nvim-0.12

Summary:
- <commit 1>
- <commit 2>
- <commit 3>

Verification:
- startup: pass/fail
- nvim-treesitter health: pass/warnings
- markdown fenced code crash reproduction: pass/fail
- vim.lsp health: pass/warnings

Remaining notes:
- <anything the user should know>

To merge when satisfied:
  git switch main
  git merge --ff-only migrate/astronvim-v6-nvim-0.12
```

## Rollback/remediation rules

If something fails:

1. Stop and report exact failing phase.
2. Do not force reset unless user approves.
3. Keep branch state inspectable.
4. If on migration branch, returning to `main` is enough to leave source changes behind.
5. Runtime/plugin state may still have changed due to Lazy sync; if the user needs to restore v5 runtime, ask before cleaning or restoring runtime directories.

Supported compatibility fallback:

```text
AstroNvim v5 + Neovim 0.11.x
```

Supported target:

```text
AstroNvim v6 + Neovim 0.12.x
```