Skip to content

Feature Specification: FEAT-009 — Team Onboarding Workflow

Source identity (from 01-frame/features/FEAT-009-team-onboarding.md):

ddx:
  id: FEAT-009
  depends_on:
    - helix.prd
    - FEAT-007
    - FEAT-008

Feature Specification: FEAT-009 — Team Onboarding Workflow

Feature ID: FEAT-009 Status: Draft Priority: P1 Owner: HELIX maintainers

Overview

HELIX must be teachable without its creator present. This feature defines the onboarding experience for new team members: a getting-started guide, a guided first-project template, and self-documenting prompts that explain why each bead exists and what context it draws from.

Transferability is a critical risk identified in the product vision. If HELIX only works when its creator is present to explain the methodology, it cannot scale to teams or serve as a consultable product.

Problem Statement

  • Current situation: The methodology is documented across Vision, PRD, feature specs, workflow actions, and AGENTS.md. A new user must piece together the mental model from scattered sources. There is no guided onboarding path.
  • Pain points:
    1. New users don’t know where to start or in what order to read docs.
    2. Without guided practice, users misuse HELIX as a prompt library or skip the planning artifacts entirely.
    3. The connection between artifacts (vision → specs → beads → code) is not obvious without explanation.
    4. Beads don’t explain themselves — a new user looking at a bead doesn’t understand why it exists or what upstream context governs it.

Functional Requirements

FR-1: Getting-Started Guide

A structured guide (in the microsite and as a standalone markdown) that walks a new user through:

  1. Installing HELIX (plugin mode or DDx install).
  2. Understanding the artifact hierarchy at a conceptual level.
  3. Running helix frame to initialize a project.
  4. Creating a first bead with helix triage.
  5. Running helix run to see the autopilot in action.
  6. Intervening directly (editing a spec, steering the tracker).

FR-2: Guided First-Project Template

A template project (e.g., a simple CLI tool or web app) pre-populated with:

  • A starter Vision and PRD.
  • One or two feature specs with acceptance criteria.
  • A concerns file with a common tech stack.
  • Pre-created beads ready for helix run.
  • Commentary explaining each artifact’s purpose and how they connect.

The template must be initializable via helix frame --template quickstart or similar.

FR-3: Self-Documenting Beads

When HELIX generates a bead (via helix triage, helix evolve, or helix polish), the bead description must include a brief explanation of:

  • Why this bead exists (which upstream artifact or user action created it).
  • What context it draws from (which specs, designs, and concerns govern it).
  • How it connects to other beads (dependencies, parent epic).

This is partially addressed by the context digest (FEAT-006) but should be human-readable, not just agent-optimized.

FR-4: Methodology Overview Page

A single-page methodology overview suitable for the microsite that covers:

  • The double-helix metaphor.
  • The progressive abstraction layers.
  • The activities (Discover → Frame → Plan → Build/Iterate → Polish).
  • The multi-directional workflow (changes can enter at any layer).
  • When to use which command.

Non-Functional Requirements

NFR-1: Time to Productivity

A developer familiar with Git and AI coding tools should be able to initialize a project, create beads, and run helix run within 30 minutes of starting the getting-started guide.

NFR-2: No Creator Dependency

The onboarding materials must be sufficient for a new user to become productive without live coaching from the HELIX creator.

Acceptance Criteria

  1. Getting-started guide exists in the microsite and covers install through first helix run.
  2. Guided first-project template initializable via helix frame.
  3. Beads generated by triage/evolve/polish include human-readable context (not just machine context digests).
  4. Methodology overview page exists on the microsite.
  5. A new developer can follow the getting-started guide and have a working HELIX project within 30 minutes (validated by user testing).

Constraints

  • Must work with the existing plugin packaging (FEAT-004).
  • Template project must not depend on external APIs or services.

Out of Scope

  • Video tutorials (future work — complement the asciinema demos).
  • Structured pairing protocol (defer to documentation for now).