stacklok / stacklok/mecatl

mecatui: `/migrate` — render the arrival report in the zero state, and offer to finish the job conversationally

Open
#414 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement tui ui ux
Dominant language
Go
Stars
152
Forks
16
Avg merge
14h 48m
Merged PRs (30d)
536

Description

mecatui: /migrate — render the arrival report in the zero state, and offer to finish the job conversationally

Sub-issue of the portability epic (#410). Depends on sub-issue A (the scan/report); this issue is
presentation plus one follow-up-session seam, and should add no discovery logic of its own.

Problem

A developer's first contact with mecatl is mecatui's zero state. If they arrived from Claude
Code, that is precisely the moment their existing setup is invisible to them — and the moment
a CLI subcommand they've never heard of cannot help.

Proposal

  • First-run hint. When ~/.claude (or a workspace CLAUDE.md/.claude/) exists and no
    mecatl-native config does, the zero state
    (cmd/mecatui/ui/zerostate*) surfaces a single line offering the report.
    Once dismissed, it stays dismissed — this is a hint, not a wizard.
  • /migrate slash command. Registered in the caps-gated palette alongside
    /mcp, /agents, /skills (see docs/tui.md — the built-in command list is locked by a
    test, so that test moves with this change). Renders sub-issue A's three buckets as a
    scrollable overlay, same modal discipline as the existing /agents and /skills views.
  • Follow-up session seam. An action on the overlay opens a new session seeded with the
    "not supported / needs a flag" lines as its prompt, so the agent itself walks the user
    through the remainder — Codex's follow-up-thread trick, and the one part of their flow worth
    copying wholesale. The seeded prompt is text the user can read and edit before sending, not
    an auto-run.

Non-goals

  • No discovery, resolution or bucket logic — it consumes A's result. If the TUI and the CLI can
    disagree about what was found, that's the defect.
  • No writes from the overlay in v1. Enabling a flag or copying skills stays a deliberate CLI
    action; the overlay tells the user the exact command.
  • No onboarding wizard, no multi-step flow, no blocking modal on startup.

Acceptance

  • With a fixture ~/.claude present, the zero state shows the hint; with none, it does not, and
    the zero state is byte-identical to today's.
  • /migrate renders every bucket from A, scrolls, and dismisses like the other overlays; the
    locked built-in-command test is updated to include it.
  • The follow-up session is seeded with an editable prompt and is not auto-submitted.
  • The overlay writes nothing (asserted by test).
  • docs/tui.md updated: the command list, the palette table, and the overlay's key handling.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in cmd/mecatui/ui/zerostate* and compare the existing /agents and /skills overlays, then review docs/tui.md and the locked built-in-command test. Use sub-issue A's three-bucket result as the input. Done means the zero-state hint, scrollable /migrate overlay, editable unsent follow-up prompt, updated command and key-handling documentation, and tests proving no writes.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
cli, documentation, testing
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.