checkpoint: preserve pre AstroNvim v6 migration state
This commit is contained in:
Krishna Ayyalasomayajula
@@ -0,0 +1,542 @@
|
||||
# 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
|
||||
```
|
||||
Reference in New Issue
Block a user