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:

.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:

.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:

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

Supported target:

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

Non-negotiable constraints

1. Work on a dedicated branch:

   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:

   ~/.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:

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:

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:

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:

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:

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:

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:

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:

lua/lazy_setup.lua

Change:

version = "^5"

to:

version = "^6"

Keep pin_plugins = nil.

Commit message:

chore: migrate AstroNvim constraint to v6

Phase 4: Migrate Tree-sitter config to AstroCore

File:

lua/plugins/treesitter.lua

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

-- 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:

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:

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:

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:

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

Headless alternative if appropriate:

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

Do not run :Lazy restore unless rolling back.

Phase 9: Commit lockfile refresh

Inspect first:

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:

chore: refresh lazy lockfile for AstroNvim v6

Phase 10: Verification

Minimum checks:

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

Manual markdown fenced-code test:

# Tree-sitter crash test

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

```bash
echo hello
```

Open with:

nvim /tmp/treesitter-crash-test.md

Confirm no range() nil crash.

Also check:

: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:

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:

AstroNvim v5 + Neovim 0.11.x

Supported target:

AstroNvim v6 + Neovim 0.12.x