Skip to main content

Onboard Welcome Hook

Version: 1.0.0 Type: Session Start Hook Status: Production Last Updated: December 11, 2025

Purpose​

Automatically detect new users or unconfigured projects and offer guided onboarding. Creates a welcoming first experience without being intrusive.

Trigger Conditions​

This hook activates when ALL of the following are true:

  1. New Session Start - Beginning of a Claude Code session
  2. No CODITECT Config - .coditect/ directory does not exist
  3. No Claude Symlink - .claude symlink does not exist
  4. Not Suppressed - User hasn't disabled onboarding prompts

Hook Configuration​

# hooks/onboard-welcome.yaml
name: onboard-welcome
version: 1.0.0
trigger: session_start

conditions:
  - type: file_not_exists
    path: .coditect/
  - type: file_not_exists
    path: .claude
  - type: env_not_set
    var: CODITECT_SKIP_ONBOARD

action:
  type: prompt
  message: |
    Welcome! This looks like a new project without CODITECT configuration.

    Would you like me to help you get started?
    This takes about 10 minutes and sets up:
    - Project structure with proper documentation folders
    - AI Command Router for easy command discovery
    - Your first agent invocation

  options:
    - label: "Yes, guide me through setup"
      action: run_command
      command: "/onboard"

    - label: "Quick setup (use defaults)"
      action: run_command
      command: "/onboard --quick"

    - label: "Not now (remind me later)"
      action: set_flag
      flag: "remind_onboard_later"

    - label: "Never ask again for this project"
      action: create_file
      path: ".coditect/.skip-onboard"
      content: "Onboarding skipped by user choice"

Detection Logic​

def should_trigger_onboard_welcome() -> bool:
    """Determine if onboard welcome should trigger."""
    import os
    from pathlib import Path

    cwd = Path.cwd()

    # Check for existing configuration
    has_coditect = (cwd / ".coditect").exists()
    has_claude = (cwd / ".claude").exists()

    # Check for skip flags
    skip_env = os.environ.get("CODITECT_SKIP_ONBOARD", "").lower() == "true"
    skip_file = (cwd / ".coditect/.skip-onboard").exists()

    # Trigger if no config and not suppressed
    return not has_coditect and not has_claude and not skip_env and not skip_file

Welcome Message​

┌─────────────────────────────────────────────────────────────┐
│                                                             │
│   Welcome to CODITECT!                                      │
│                                                             │
│   This looks like a new project. Would you like help        │
│   getting started? (~10 minutes)                            │
│                                                             │
│   What I'll help you with:                                  │
│   ✓ Create proper project structure                         │
│   ✓ Set up AI Command Router (never memorize commands)      │
│   ✓ Your first agent invocation                             │
│   ✓ Session management for continuity                       │
│                                                             │
│   [1] Yes, guide me through setup                           │
│   [2] Quick setup (use smart defaults)                      │
│   [3] Not now                                               │
│   [4] Never ask again for this project                      │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Response Actions​

Option 1: Full Guided Setup​

/onboard

Launches interactive dialog-driven onboarding with consultant persona.

Option 2: Quick Setup​

/onboard --quick

Uses smart defaults:

  • Intermediate experience level
  • Project-first goal
  • Auto-configures shell aliases
  • Creates project in current directory

Option 3: Not Now​

Sets remind_onboard_later flag. Will prompt again next session.

Option 4: Never Ask​

Creates .coditect/.skip-onboard file. Permanently disables for this project.

Reminder Logic​

If user selects "Not now":

reminder:
  trigger: next_session_start
  max_reminders: 3
  reminder_message: |
    Reminder: This project doesn't have CODITECT configuration yet.
    Run /onboard when you're ready to set up.

    (This is reminder {count}/3. After 3 reminders, I won't ask again.)

Integration with Existing Projects​

For projects that already have some structure but no CODITECT config:

existing_project_detection:
  indicators:
    - package.json
    - requirements.txt
    - Cargo.toml
    - go.mod
    - pom.xml

  modified_message: |
    I see this is an existing project. Would you like to add CODITECT
    configuration without changing your current structure?

    This will add:
    - .coditect/ configuration directory
    - .claude symlink for Claude Code
    - CLAUDE.md for AI context

    Your existing files won't be modified.

Suppression Methods​

Environment Variable​

export CODITECT_SKIP_ONBOARD=true

Skip File​

mkdir -p .coditect && touch .coditect/.skip-onboard

Command Flag​

claude --no-hooks

Hook Implementation​

# hooks/onboard_welcome.py

def on_session_start(context: dict) -> dict:
    """Handle session start event for onboarding."""
    from pathlib import Path
    import os

    cwd = Path(context.get("working_directory", "."))

    # Check conditions
    has_coditect = (cwd / ".coditect").exists()
    has_claude = (cwd / ".claude").exists()
    skip_env = os.environ.get("CODITECT_SKIP_ONBOARD", "").lower() == "true"
    skip_file = (cwd / ".coditect/.skip-onboard").exists()

    if has_coditect or has_claude or skip_env or skip_file:
        return {"action": "continue", "triggered": False}

    # Check for existing project indicators
    existing_indicators = [
        "package.json", "requirements.txt", "Cargo.toml",
        "go.mod", "pom.xml", "build.gradle"
    ]
    is_existing_project = any((cwd / ind).exists() for ind in existing_indicators)

    return {
        "action": "prompt",
        "triggered": True,
        "is_existing_project": is_existing_project,
        "prompt_type": "onboard_welcome"
    }
  • Agent: agents/coditect-onboarding.md
  • Skill: skills/coditect-onboarding/SKILL.md
  • Command: commands/onboard.md
  • Script: scripts/onboard-wizard.py

Metrics​

Target Behavior:

  • Trigger rate for new projects: 100%
  • User acceptance rate: > 60%
  • False positive rate (existing CODITECT projects): 0%
  • Annoyance reports: < 5%

Author: CODITECT Framework Team Framework: CODITECT v1.0