roll-onboard

name	roll-onboard
license	MIT
description	Interactive onboarding for legacy projects. Reads existing code, understands the project, asks 9 questions in 3 groups (cognition / scope / privacy), and writes .roll/onboard-plan.yaml as the contract for `roll init --apply` to execute.

Roll Onboard

Follows the Architecture Constraints, Development Discipline, and Engineering Common Sense defined in the project AGENTS.md.

Interactive onboarding flow for legacy projects: existing code that needs to adopt the Roll convention without disrupting how the team already works.

Trigger

This skill runs when:

• roll init detected a legacy project (≥10 source files, no AGENTS.md)
• The CLI told the user to open an AI agent and run $roll-onboard
• The user has now invoked you here

Hard responsibility boundary

You are the 认知 (cognition) layer. Your job ends with writing a plan file.

You do	You do NOT
Read project code, infer type/domains/modules	Modify any source file
Call roll-doc --dry-run to get a gap report	Call roll-doc (write mode)
Ask the user 9 questions across 3 groups	Decide for the user
Produce .roll/onboard-plan.yaml	Write .gitignore
Produce .roll/onboard-plan.yaml	Run roll init --apply

Hard constraint: AI cannot create files in the user's project other than .roll/onboard-plan.yaml. Anything else is bash's job (roll init --apply).

Inputs you must read

1. The repository tree (use the project's own structure to infer technologies)
2. Any existing README.md / package.json / pyproject.toml / Cargo.toml / go.mod etc. as evidence
3. roll-doc --dry-run output → identifies what documentation gaps exist
4. The path-audit pattern: scan for legacy structure markers (BACKLOG.md, docs/features/, etc.) — if any are present, REFUSE and tell the user to run roll migrate first

Workflow

Step 0 — Pre-flight

1. Check that you're in a legacy project root (no AGENTS.md, has source code)
2. If BACKLOG.md or docs/features/ already present → STOP, tell user to run roll migrate first (this is a partial-migration project, not legacy)
3. Check .roll/onboard-plan.yaml doesn't already exist; if it does, ask user whether to overwrite

Step 1 — Read code, build understanding

Walk the repo. Identify:

• type: one of backend-service / frontend-only / fullstack / cli
• description: 1-2 sentence summary of what this project does
• domains: top business/technical domains (e.g., "auth", "billing", "search")
• key_modules: top 3-5 modules that hold most of the logic

Step 2 — Get gap report

Run roll-doc --dry-run (READ-ONLY mode). This reports:

• Which standard Roll artifacts (BACKLOG, features, domain models) are missing
• Which existing docs Roll could include rather than regenerate

Step 3 — Three groups of nine questions

Present these in chat. Aim for total time ≤ 3 minutes. Group 1 confirms your understanding; group 2 scopes the work; group 3 handles privacy and next steps.

Group 1 — Project cognition check

1. I see this is a [type] project doing [description] — correct?
2. The main business domains look like [domain A, domain B, …] — anything to add or correct?
3. The key modules are [X, Y, Z] — any missed or mis-identified?

Group 2 — Generation scope

4. Which artifacts should I generate? Multi-select:
   • backlog — initial BACKLOG with seeded stories
   • features — features index + per-feature spec stubs
   • domain — DDD context map
   • briefs — directory for $roll-brief outputs
5. Of these existing docs, which should I include rather than regenerate?
   • (list candidates: README.md, docs/architecture.md, etc.)
6. Put drafts inside .roll/? (default: yes; "no" means use the legacy docs/ layout — not recommended for new adoption)

Group 3 — Privacy & next steps

7. Add .roll/ to .gitignore? (yes = keep project management private; no = commit it like Roll itself does)
8. Sync Roll conventions to which AI tools? Multi-select from detected agents (claude / cursor / codex / kimi / deepseek / pi / opencode / gemini / trae)
9. Enable roll loop autonomous execution after init?

Step 4 — Write plan file

Write .roll/onboard-plan.yaml with this exact schema (validated by lib/roll-plan-validate.py):

version: 1
generated_at: "2026-05-19T14:30:00+08:00"   # current ISO 8601, your timezone OK

project_understanding:
  type: cli                                  # one of: backend-service / frontend-only / fullstack / cli
  description: "..."
  domains: [...]
  key_modules: [...]

scope:
  approved: [backlog, features, domain]      # user's Q4 multi-select
  declined: [briefs]                         # what they said no to

include_existing:
  - README.md                                # user's Q5 selections
  - docs/architecture.md

privacy:
  gitignore_dot_roll: true                   # user's Q7

sync_targets: [claude, cursor]               # user's Q8
enable_loop: false                            # user's Q9

Then tell the user:

Onboard conversation done. Plan saved to .roll/onboard-plan.yaml. Return to your terminal and run:

roll init --apply

The plan expires in 24 hours.

Step 5 — Stop

Do NOT run roll init --apply yourself. Do NOT modify other project files. Your job is done.

When NOT to use

• Not a legacy project: empty dir or fresh project → use plain roll init instead
• Has BACKLOG.md or docs/features/: this is a pre-2.0 Roll project → run roll migrate first
• Has .roll/ already: already onboarded → don't re-run

Failure modes

• User aborts mid-conversation → don't write partial plan; tell user to re-run from scratch
• User answers contradict the gap report (e.g., declines features but has lots of code) → ask the contradictory question once more before accepting; if they confirm, respect the choice
• You can't read enough code to fill project_understanding (e.g., binary repo) → write a placeholder plan but ask user to fill in type and description manually before applying