feat(skill): agent first-run experience and the Claude Code live strip

[siddhant573]

Summary

Makes the first agent-driven kane-cli run feel watched instead of waited on. Today the skill launches kane-cli with one blocking call, so a first-time user sees one line and then silence for 30 seconds to several minutes. This change adds a ready check, a run with nothing asked first, a short tour read during the wait, richer result cards, three choices asked once afterwards, and a live status strip for Claude Code.

Everything ships from this repo (skill, scripts shipped with the skill, npm installer). No kane-cli change is needed. The live strip needs kane-cli 0.8.17 or newer.

#194 is merged and main is merged into this branch, so the diff shows only this work.

What changes for the person

1. Ready check. One short preflight script, one card: signed in, credits, Chrome, their own app if it is running locally, and where results will be saved. Full card on the first session, one line afterwards. Every problem is shown at once with its fix. The agent starts browser sign-in itself and never asks for an access key in chat.
2. Run first, ask after. Run one uses detected defaults (browser visible unless there is no display, SSH, or CI). Nothing is asked before the first result.
3. A tour during the wait. Sent with the launch line on the first run only: runs, authoring, replays, assurance, Test Manager, evidence, with links to the user guide. Same wording in every agent.
4. Result cards. The existing emoji table gains credits, evidence, test case and next-move rows, plus cards for didn't start, stopped early, possible product bug, saved test, and suite (with a failed-tests table and cloud grid rows).
5. Three choices, asked once, after the first result: watch mode, where results go, one-off or saved suite. Saved in ~/.testmuai/kaneai/agent-config/config.json, read and written by the agent through the shell. Changing where results go is global, and the question says so.
6. Live strip (Claude Code). One status line that names the current step while a run works. It wraps the person's existing status line, shows only during a run and for five minutes after, shows only in the Claude Code session that started the run (other sessions in the same project stay untouched), reads only local files, and never echoes typed text. It is never on by default: Claude Code asks once, as a recommended choice, after the person's first result in it (in any session, since onboarding may have happened in another agent), and the installer asks the same question only when a person runs it by hand in a terminal. npx @testmuai/kane-cli-skill strip enable turns it on, and strip disable undoes it exactly.

What is in the diff

• Skill (skill-installer/skills/, mirrored byte for byte to .claude/ and .agents/): SKILL.md section 1 rewritten, five new references (ready-check, first-run, agent-config, cards, live-strip), scripts/preflight.sh and preflight.ps1. The agent tag is now inline on every command, because an exported variable does not survive between shell calls in agent hosts.
• References corrected against the real 0.8.17 stream: stream_start, v and ts on every line, credits_consumed (was documented as credits), the saved-test event table (step headings, replay versus authoring), suite log_path and failure, testrun_progress, and "do not pass --stream-members by default". folders list and folders create require --project (the reference said otherwise).
• Installer: prefs, strip enable|disable|status, a welcome at the end of install, seeding of the agent config folder, the strip reader (strip/kane-strip.mjs). Zero dependencies.
• Docs: new docs/user-guide/agents.md, linked from the guide index and the README.
• Kiro: power and steering files mirror the canonical skill, with a new first-run steering file. The strip is noted as Claude Code only.
• CI: a new workflow runs the installer suite on ubuntu, macos and windows with Node 18 and 22, checks the three skill copies are identical, and checks the npm package contents. The publish workflow runs npm test before publishing.
• Test guide: skill-installer/TESTING.md lists what CI covers and gives the manual matrix of hosts, operating systems and numbered cases to walk before a release.

Test plan

• cd skill-installer && npm test: 73 tests pass on macOS and Linux, 63 plus 14 POSIX-only skips on Windows (strip reader, installer helpers, preflight), driven by sanitized captures from kane-cli 0.8.17-beta.1 (run, saved test authored and replayed, two-test suite with a failure)
• Real preflight run: 1.7 s, all sections correct
• Live check against a real headless run: the strip ticked through the steps, ended on ✓ passed · 5 steps · 0:54 · 16 credits, and showed nothing for a different project
• Installer smoke test in a throwaway home: install, seed, welcome, strip enable then strip disable restores settings
• Local first-run test in a real Claude Code session: install, strip enable wrapping an existing custom status line, ready card, tour, named run, result card with evidence viewer and test case links, three choices saved, project change flow (new project and folder created, next run landed in it)
• Session isolation, live: with a run in flight the launching session showed the strip through to passed, while a reader under a different host process showed only the person's own status line
• npm pack --dry-run: lib/, strip/, skills/scripts/ included, tests excluded
• The three skill roots are identical (diff -r)
• preflight.ps1 on real Windows: four Windows-only tests run it under PowerShell against a stand-in kane-cli.cmd in CI, all six OS and Node jobs green
• Installer question in a real pseudo-terminal: n leaves settings untouched and records that the person was asked, Enter turns the strip on with a backup, an unattended install never asks
• Real Codex CLI sessions (later session, then a true first session), read back from Codex's own session log
• The strip in a real Claude Code status bar: seen live with an existing custom status line wrapped, which is how the one-strip-per-session issue was found
• The per-session fix re-checked by eye across several open Claude Code sessions (so far verified by running the reader under two different host processes during a live run)
• Cloud grid stream additions (documented from the CLI design, not from a capture)
• A first-run pass on Gemini CLI, OpenCode and Hermes, and every host on Windows (Codex CLI on macOS is done)

Notes for reviewers

• Two fixes came from running real agents. Codex's question tool posts the questions and returns before the person answers, so the first run now saves its defaults right after the result card and again when answers arrive, and the choices are the last thing in the turn. And because onboarding is shared by every agent while the strip is Claude Code only, the strip question has its own once-only trigger in SKILL.md section 1 instead of riding on the first session.
• Found while testing, needs a kane-cli fix: kane-cli config project <id> and config folder <id> save the new ids but leave the old project_name and folder_name in the config, even after a run. config show then names the wrong location, and so would the ready card. Runs do land in the new project.
• Session isolation relies on ps. On Windows the reader falls back to matching by project folder.
• The strip appears roughly 10 to 30 seconds after launch, once kane-cli has created the session and written its pointer file. Before that the person sees their normal status line.
• The strip has no target chip (chrome, android, ios): the stream does not name the target yet.
• Left for later: a finish notification, a per-repo preferred project, just-in-time hints, and the Kiro hook, which still uses the retired --retry flag.

🤖 Generated with Claude Code

https://claude.ai/code/session_01DAoyR4RZRwM2d81a9MCKuU