Repository navigation
docs(kilo): add v2 execution plan - #14704
Conversation
![kilo-code-bot[bot]](https://avatars.githubusercontent.com/in/2193792?s=60&v=4){kind=small}
Code Review SummaryStatus: No Issues Found | Recommendation: Merge Incremental review of commit Files Reviewed (2 files)
Previous Review Summaries (3 snapshots, latest commit e9113b2)Current summary above is authoritative. Previous snapshots are kept for context only. Previous review (commit e9113b2)Status: 3 Issues Found | Recommendation: Address before merge Incremental review of commit Overview
Issue Details (click to expand)SUGGESTION
Files Reviewed (1 file)
Fix these issues in Kilo Cloud Previous review (commit 7991d2e)Status: No Issues Found | Recommendation: Merge Incremental review of commit Files Reviewed (1 file)
Previous review (commit f33ae94)Status: 1 Issues Found | Recommendation: Address before merge Overview
Issue Details (click to expand)SUGGESTION
Files Reviewed (1 file)
Reviewed by deepseek-v4.1-flash · Input: 0 · Output: 0 · Cached: 0 |
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
The dependency graph, issue-unit model, and gate acceptance coverage contain unresolved inconsistencies.
Review effort: Balanced
Findings: 7
Open (8)
What changed in this PR
Adds a unified execution plan for completing the Kilo v1-to-v2 migration.
Changes:
- Defines staged G1–G3 cutover decisions and validation.
- Plans upstream synchronization and v1 delta assessment.
- Maps existing and proposed issues into execution phases.
| File | Description |
|---|---|
migration-tracking/plans/kilo-opencode-v2-execution-plan.md |
Adds the migration execution plan, issue register, dependencies, gates, metrics, and risks. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| - **Every issue body has these fields.** N7 adds any that are missing; the existing Outcome / Scope / Current position / Acceptance / Tracking sections stay. | ||
| - Gate: G1, G2, G3, post-cutover, or discovery. | ||
| - Blocked by: real GitHub issue links, not prose or draft numbers. |
| - Kilo-package imports of upstream internals. | ||
|
|
||
| The baseline is the post-N1 measurement, recorded in a new dated `marker-audit/` footprint file. Increases fail unless they state the missing seam. Then run #14381 (marker-disposition sweep) against the new base. | ||
| 3. **N3 — Sync automation.** A Kilo-owned workflow that dry-run-merges each new upstream `v2.*` tag into `kilo-v2` and reports conflicts by owner, plus a real `e2e` lane for `kilo-v2`. Do not edit upstream's `test.yml`. |
There was a problem hiding this comment.
New upstream tags will need to be managed individually, as they come, when created upstream. New issues can be created later, when they happen, and managed by the workflow
| 3. **N3 — Sync automation.** A Kilo-owned workflow that dry-run-merges each new upstream `v2.*` tag into `kilo-v2` and reports conflicts by owner, plus a real `e2e` lane for `kilo-v2`. Do not edit upstream's `test.yml`. | ||
| 4. Start signing/notarization (#14411) now, because of its external lead time. | ||
|
|
||
| ### Phase C — Re-baseline (read-only; starts now, parallel with B) |
| 16. Any #14427/#14428 or #14431/#14432 that discovery attaches to G1. | ||
| 16a. **N12 — TUI picker, dialogs and status/footer**, covering progress-plan rows that have no issue: | ||
| - model picker inline preview and section/search interaction; | ||
| - provider-specific guidance and failure details in the provider/integration dialogs; |
| all ──> N11 (G2) ──> + N4 run ──> #14414 (G2) | ||
|
|
||
| G3: #14420 ──> #14421 ──> #14422, #14423 (needs #14416) ──> #14424 ──> N11 (G3) ──> #14414 (G3) ──> N10 |
| | N3 | TBD | Upstream-tag dry-run workflow and `e2e` lane | B | N1 | New `.github/workflows/kilo-*` files | | ||
| | N4 | TBD | Recurring `main` delta sweep from the cutoff | C, each gate | — | `marker-audit/` | | ||
| | N5 | TBD | v1 reference fixtures for #14371–#14374 | C | — | Test fixtures only | | ||
| | N6 | TBD | Package decisions: import `kilo-docs`/`kilo-jetbrains`, assess `kilo-web-ui` | C | N1 (for the imports) | `packages/kilo-docs`, `packages/kilo-jetbrains` | |
| - Rewrite the import and canary rows for the customer v2 store, re-runnable import, and per-surface canary. | ||
| - Add rows for N1 (scope rename), N4, N8 and N9. | ||
| - Record the v1 assessment cutoff and the adopted upstream tag. | ||
| - Tag every scenario in `test-plans/kilo-opencode-v2-test-plan*.md` with G1, G2, G3 or post-cutover, so that N11 can select scenarios by gate. |
Co-authored-by: kilo-code-bot[bot] <240665456+kilo-code-bot[bot]@users.noreply.github.com>
| - One consolidation merge (N1) goes to the **latest upstream v2 release tag at execution start** (v2.0.20 as of 09-29). | ||
| - After that, merge every upstream v2 release tag, at least weekly. | ||
| - Pins are always release tags. | ||
| 3. **Staged cutover:** G1 CLI/TUI → G2 VS Code (sidebar, tabs, Agent Manager, settings) → G3 JetBrains. Each surface has its own go/no-go. The IDEs keep bundling or pinning a v1 binary until their gate passes. |
There was a problem hiding this comment.
vs code doesn't pin a specific version in contrast to JetBrains or other surfaces.
| | `packages/opencode` on v2 | Kept as a temporary legacy host | Not reconstructed | Same as #13750 | | ||
| | Control of `main` | Ratchets and an ownership manifest (never built) | None | External best-effort soft freeze, plus a v2-owned recurring delta sweep | | ||
| | Upstream v2 intake | Merge regularly | Pinned SHA (in practice, recreated on new tips) | Merge every release tag into `kilo-v2` | | ||
| | Cutover | Single | Single (phase 6) | Staged: G1 → G2 → G3 | |
There was a problem hiding this comment.
we would need a regular release of kilo v2 I guess
There was a problem hiding this comment.
Yes. The tick here is finding the right time when v2 is working "enough" to release and start from there
| - v1 files are never moved or rewritten while any v1 surface ships. | ||
| - Import is opt-in, copies then migrates the copy, and is **re-runnable/idempotent**. Between G1 and G3, history is split between the v2 CLI and the v1 IDEs. | ||
| - Paths are consolidated only after G3. | ||
| 5. **Post-cutover (non-gating):** voice/STT; image generation and Claw; team sharing and incremental share sync; legacy TUI theme/binding extras. **Individual snapshot share/unshare/fork-from-share and the public viewer for v2 messages are G1 gates**, because they are v1 CLI features. Team upload stays refused until team sharing ships. |
There was a problem hiding this comment.
KiloClaw can be left out, we already removed it from the client code. Image generation is still experimental. Most likely it makes sense to have a look which features are gates behind experimental flags first?
There was a problem hiding this comment.
Yeah. I left this all in post-cutover as a group of things that "don't belong in the scope of this first v2 work". Intention is to then pick these, one by one, and decide to toss or keep (and port).
| # Kilo v1 → v2 migration plan | ||
|
|
||
| Finalized 2026-09-30. Base: opus-55. Merged in: upstream-resync rigor, capability handshake and validation rules from deepseek; VS Code blockers, sharing/remote steps, standing rules and metrics from kimi-k3. Status: not started. First actions: | ||
| - Team sign-off on Decisions 3 and 4. |
There was a problem hiding this comment.
SUGGESTION: Decision 5 was dropped from the sign-off list
This reverts the earlier fix: the list now omits Decision 5 (the post-cutover scope cuts), even though the PR description and the reviewer test steps still require sign-off on Decisions 3, 4 and 5. If narrowing the set is intentional, reconcile the PR description and reviewer test steps; otherwise restore Decision 5.
| - Team sign-off on Decisions 3 and 4. | |
| - Team sign-off on Decisions 3, 4 and 5. |
Reply with @kilocode-bot fix it to have Kilo Code address this issue.
| - VS Code ships from `main` and bundles the CLI built from the same commit. It does not pin a CLI version. | ||
| - JetBrains pins a CLI version. | ||
|
|
||
| **G2 and G3 are independent client-surface tracks.** Their work is mainly Kilo-specific client code (`packages/kilo-vscode`, `kilo-ide-ui`, `kilo-ui`, `kilo-jetbrains`) that consumes the v2 core through public contracts. They do not block G1, and G1 does not wait for them. Each track can start once its prerequisites land (N1 for both; #14383 for VS Code) and can run in parallel with G1 under its own owner. |
There was a problem hiding this comment.
SUGGESTION: JetBrains prerequisite conflicts with the dependency order
This sentence says each track starts once its prerequisites land, "(N1 for both; #14383 for VS Code)", but the dependency order gates G3 on N1 and N6b. Since N6b imports kilo-jetbrains for G3, list N6b for JetBrains here as well (or remove it from the G3 gate) so the two statements agree.
Reply with @kilocode-bot fix it to have Kilo Code address this issue.
|
|
||
| Some client-track items touch core, server or protocol, and must be coordinated with core work: | ||
| - #14380, the message-deletion runtime operation; | ||
| - N9, the server side of the capability handshake; |
There was a problem hiding this comment.
SUGGESTION: N9's Touches field omits the server surface named here
This line lists N9 as a client-track item that touches the server ("the server side of the capability handshake"), but N9's Touches value in the new-issues table is only packages/kilo-vscode. The Touches field exists so parallel agents avoid editing the same files, so the server/core path N9 edits should be recorded there too.
Reply with @kilocode-bot fix it to have Kilo Code address this issue.
Add the execution plan to the migration-tracking README and describe each plan document's role under it: the execution plan holds decisions and sequencing, the progress plan holds live status per row, and the working log holds coordinator-written milestones. Resolve the three review suggestions on the execution plan: - include Decision 5 in the pre-execution sign-off list - list N6b as a JetBrains track prerequisite in Decision 3 - add the server side of the handshake to N9's Touches field
Issue
Part of #13750
Exception to "Fixes": #13750 is the migration epic and must stay open. This PR adds the execution plan that the epic's remaining work follows; it does not complete the epic.
Context
kilo-v2has fallen behind on both sides:kilo-v2is based on upstream59b29de4(2026-09-03) and has never had upstreamv2merged into it. Upstream has moved on by at least 1,013 commits, including the npm scope rename from@opencode-ai/*to@opencode/*(#47852). Upstream now publishes v2 on npm as@opencode/cli(latest 2.0.20).main: the v1 source assessment stops atmainf7115470(2026-08-12). Since then, 2,645 commits have landed onmainwithout assessment.This PR adds
migration-tracking/plans/kilo-opencode-v2-execution-plan.md, a single execution plan for finishing the port. It is based on #13750's target-shaped port architecture. Three drafted plans were compared and combined into it, and it was re-checked against the repository, GitHub and npm on 2026-09-29/30.Implementation
The plan is organized around the decisions reviewers need to agree on, then the execution order:
v2release tags intokilo-v2, starting with one consolidation merge that includes the scope-rename codemod.kilo-v2is never recreated again.maincommit up to which v1 behavior has been assessed. A recurring delta sweep moves it forward, which replaces "parity withmain".kilo-opencode-v2-plan-progress.mdremains the live status per capability;kilo-opencode-v2-working-log.mdbecomes the milestone history.Areas that deserve the closest review:
/remoteare G1 gates despite their P2 labels.Screenshots / Video
N/A (documentation only)
How to Test
Manual/local verification
dev/v2tips viagit ls-remote https://github.com/anomalyco/opencode.git;gh api repos/anomalyco/opencode/compare/dev...v2;@opencode/clidist-tags and publish dates from the npm registry;gh release list;a5312e16viagit log.kilo-v2facts:59b29de4is the sole parent of the first Kilo commit047ffd045f;maincommits sincef7115470, viagit rev-list.gh api repos/Kilo-Org/kilocode/issues/<n>/sub_issuesand confirmed that each of the 62 appears in the plan's issue register.git status --shortshows the plan file is the only change.Reviewer test steps
migration-tracking/plans/kilo-opencode-v2-execution-plan.mdand read the Decisions section. Confirm you agree with Decisions 3, 4 and 5, or raise objections on Phased Plan - Port Kilo onto OpenCode V2 #13750.git ls-remote https://github.com/anomalyco/opencode.git refs/heads/dev refs/heads/v2gh api repos/anomalyco/opencode/compare/dev...v2 --jq '{ahead: .ahead_by, behind: .behind_by}'gh api repos/Kilo-Org/kilocode/issues/14017/sub_issues --jq '.[].number', confirm every number appears in the Issue register table.migration-tracking/plans/, updates the README and changes nothing else.Blocked checks and substitute verification
script/check-md-table-padding.ts) exists only onmain, not onkilo-v2, so it could not be run. Substitute: the tables were written in the compact form thatv2-fork-conventions.mdrequires. Per those conventions,prettier --writewas deliberately not run, because it would re-pad the tables.Checklist