Agent-driven onboard: research-interview-customize cycle

[codevibesmatter]

Summary

Rewrite the onboard mode as an agent-driven research → interview → customize cycle that produces project-tailored config and templates.

Problem

• Current onboard mode asks generic questions but doesn't research the codebase
• Templates are identical across all projects regardless of framework/architecture
• Step instructions say "search for relevant files" instead of referencing actual project patterns
• Interview questions are generic (UI design questions for a CLI tool)

Proposed design

Two-step setup:

1. kata setup — creates skeleton with seed templates copied from package (usable immediately)
2. kata enter onboard — agent researches project, interviews user, customizes seed files

Onboard phases:

• P0: Research — explore codebase, detect stack (Next.js? Express? CLI?), read package.json, directory structure, key source files, existing configs
• P1: Interview — targeted questions based on research findings (not generic)
• P2: Customize — patch seed templates/config with project-specific content:
  • Rewrite step instructions to reference actual project files and patterns
  • Tailor interview categories to the domain
  • Add project-specific global_rules and per-mode rules
  • Fill in project.* fields from detected values
• P3: GitHub — gh CLI, auth, labels
• P4: Validate — kata doctor to verify everything works

Key principle: Agent customizes EXISTING seed templates, does not generate from scratch. Modifies behavioral parts (instructions, rules) while leaving structural parts (phases, dependencies, step ids) untouched. This preserves upstream merge compatibility — kata update can merge structural improvements while preserving the agent's customizations.

Example output

For a Next.js + tRPC + Drizzle project, the agent would customize:

• global_rules with "This project uses pnpm", "Run pnpm build after changes — route types generated at build time"
• Template instructions with "Check src/server/routers/ for existing router patterns"
• Interview architecture questions with "Which services does this touch? (Gateway / Auth / Multi-service)"
• No UI design interview category for a headless API project

Depends on

• Consolidated config: unified kata.yaml, simplified setup, upstream merge #35 (consolidated config — kata.yaml schema, simplified setup)

Research

See planning/research/2026-03-31-setup-overhaul-upstream-merging.md