Contributor Onboarding

Produces a single onboarding document tailored to the role. The doc is meant to be read once on day one and revisited a few times in week one — it is not a manual replacement for the codebase.

Output: production/onboarding/[role]-[date].md

Purpose / When to Run

Run when:

• A new contributor is joining the project
• An existing contributor is moving from one role to another (e.g., backend → mobile)
• The user wants a "what would I tell someone new about this project" snapshot

Do not run when no concept doc exists — onboarding without context is a tour of an empty room. Direct the user to /start first.

Inputs

• Role argument (required)
• Optional --name <person> for personalization
• All design, architecture, production artifacts on disk

Outputs

• production/onboarding/[role]-[YYYY-MM-DD].md

Phase 1: Resolve Role

If no role argument was passed, ask:

• Prompt: "Which role is the onboarding for?"
• Options:
  • Engineer (mobile) — implements stories, writes tests
  • Designer (UX/visual) — authors UX specs and the design bible
  • PM / producer — owns sprint plans, scope, milestones
  • QA / tester — runs test plans, files bugs, gates releases
  • Data scientist / analytics — instrumentation, metrics
  • Other — describe in free text

Capture the role as a kebab-case slug for the filename (engineer, designer, pm, qa, analytics, or whatever the user gives).

If --name <person> is included, the doc personalizes the welcome.

Phase 2: Gather Project Context

Read what exists. If a file is missing, note it as "not yet authored" — never invent content.

Always read:

• design/concept.md
• .claude/docs/technical-preferences.md
• design/systems-index.md (if present)
• production/session-state/active.md (if present)

Role-specific reads:

Phase 3: Build Role-Specific Sections

The doc has a fixed shell, but content varies by role.

Common header (every role)

• Welcome (personalized if --name given)
• One-paragraph description of the app pulled from concept.md Section 1 + 3
• Target user (Section 2)
• Primary metric (Section 5)
• Current stage (run the same logic as /project-stage-detect Phase 2 but inline; do not actually invoke that skill)

Engineer-specific

• Framework: name + version + LLM-knowledge-cutoff risk if known
• Architecture overview: top-level layers from architecture.md
• Key Accepted ADRs: list the 5-10 most-referenced ADRs by ID, title, and one-sentence decision
• Coding conventions: pulled from .claude/docs/coding-standards.md
• Control manifest highlights: top 5 forbidden patterns and top 5 required patterns
• Repo layout: src/, tests/, the framework-specific dirs (ios/, android/, lib/, etc.)
• First tasks: pull 2-3 stories with Status: Ready and Layer: Foundation or Core from current sprint. List file paths.
• Tooling: build command, test command, lint command (read from package.json, pubspec.yaml, or Makefile)

Designer-specific

• Design Bible status: token coverage + open sections
• PRD inventory: which systems have specs, which are stubs
• UX coverage: which screens have UX specs, which are missing
• Conventions: platform target (iOS HIG / Material 3 / both), accessibility floor (WCAG 2.2 AA)
• First tasks: missing UX specs for in-flight epics; PRDs with UI Requirements but no matching UX spec
• Reference apps: from concept.md Section 6

PM / producer-specific

• Current sprint: name, dates, story count by status
• Current milestone: name, target date, completion %
• Risk register: open blockers from production/session-state/active.md
• Recent retros: takeaways from the last 1-2 retrospectives
• Cadences in use: sprint length, gate skills the team uses, review-mode setting
• First tasks: review the active sprint plan, run /sprint-status, talk to engineering lead about one named blocker

QA-specific

• Test framework (from technical preferences)
• Test counts: unit / integration / manual evidence
• Story type distribution in the current sprint
• Open bugs: count + severity from production/qa/bugs/
• First tasks: run smoke check; read 3 specific stories due for QA hand-off

Analytics-specific

• North Star metric (from concept.md)
• Instrumentation status: any analytics PRD or ADR
• Tools: analytics provider if pinned (Amplitude, Mixpanel, Firebase, etc.)
• First tasks: define the event schema for the in-flight epic; align metric definitions with PM

Other

If the user described their role in free text, structure the doc with:

• Purpose of the role on this project
• Stakeholders they will interact with
• Files most-relevant to their work
• An open question for them to bring back to the team

Phase 4: Sketch the First-Week Plan

Tail the doc with a "First week" section covering 5 work-days. Be concrete:

• Day 1: read these files in this order
• Day 2: shadow [contact] / pair with [contact] on [task]
• Day 3: take ownership of [specific story or PRD]
• Day 4: run [skill] for the first time
• Day 5: present what you learned in a 30-min review

If team contacts are not known, leave them as [name TBD] — do not invent.

Phase 5: Write the Doc

Build the file content, then ask:

• "May I write this to production/onboarding/[role]-[date].md?"

If the user wants edits, capture them, redraft, ask again.

After writing:

• Update production/session-state/active.md if it is being maintained
• Print: "Doc written. Open it before [contributor]'s first day, share the path, and let them flag missing context — onboarding docs need updating after every cycle."

Examples

/onboard engineer --name Priya

• Reads concept doc, framework ref, architecture, control manifest, current sprint
• Picks 3 Ready stories from Foundation/Core layers as first tasks
• Surfaces the most-relevant ADRs (state management, networking, navigation)
• Writes production/onboarding/engineer-2026-05-03.md

/onboard pm

• Reads sprint plans, milestone, active.md
• Tail-section recommends running /sprint-status and /scope-check in week one
• Lists stale stories that need re-triage

Quality Gates

• The doc must list at least one specific first task with a file path. Vague advice ("get familiar with the codebase") is a failure mode.
• If a critical artifact is missing (no concept doc, no framework pin), the skill must surface that as a blocker rather than write a doc full of [TBD].
• The doc never invents people, ADRs, sprints, or tasks.

Constraints

• One file output, one role per run. To onboard multiple roles, run multiple times.
• Do not duplicate /help's job. /help answers "what should I do right now?" — /onboard answers "what does this project look like to my role?"