CODITECT Onboarding Skill

CODITECT Onboarding Skill

When to Use This Skill

Use this skill when implementing coditect onboarding patterns in your codebase.

How to Use This Skill

1. Review the patterns and examples below
2. Apply the relevant patterns to your implementation
3. Follow the best practices outlined in this skill

Version: 1.0.0 Category: Onboarding & Training Status: Production Last Updated: December 11, 2025

---

Purpose

Reusable patterns and automation for guiding new users through CODITECT setup and first project creation. Designed for dialog-driven, consultant-style onboarding.

---

Core Patterns

Pattern 1: First-Run Detection

When to Use: Determine if user needs onboarding guidance.

Detection Logic:

import os

def needs_onboarding(project_path: str) -> dict:
    """Check if project needs onboarding."""
    checks = {
        "has_coditect": os.path.exists(f"{project_path}/.coditect"),
        "has_claude": os.path.exists(f"{project_path}/.claude"),
        "has_docs": os.path.exists(f"{project_path}/docs"),
        "has_git": os.path.exists(f"{project_path}/.git"),
    }

    if not checks["has_coditect"] and not checks["has_claude"]:
        return {"needs_onboarding": True, "type": "fresh_start"}
    elif checks["has_coditect"] and not checks["has_docs"]:
        return {"needs_onboarding": True, "type": "incomplete_setup"}
    else:
        return {"needs_onboarding": False, "type": "configured"}

Response Actions:

• fresh_start → Full onboarding flow
• incomplete_setup → Resume from missing step
• configured → Offer help or skip to project work

---

Pattern 2: Progressive Question Flow

When to Use: Gather user context without overwhelming them.

Question Sequence:

phase_0_assessment:
  - question: "What's your experience level?"
    options:
      - label: "New to software development"
        value: "beginner"
        next_path: "guided_detailed"
      - label: "Some coding experience"
        value: "intermediate"
        next_path: "guided_standard"
      - label: "Professional developer"
        value: "advanced"
        next_path: "fast_track"
      - label: "Already know CODITECT"
        value: "expert"
        next_path: "skip_to_project"

  - question: "What's your goal today?"
    options:
      - label: "Learn CODITECT quickly (30 min)"
        value: "quick_learn"
      - label: "Complete certification (4-6 hours)"
        value: "certification"
      - label: "Start a specific project now"
        value: "project_first"

Branching Matrix:

Experience	Goal	Path
beginner	quick_learn	guided_detailed + quick_start
beginner	certification	training_system_handoff
beginner	project_first	guided_detailed + project_creation
intermediate	quick_learn	guided_standard + quick_start
intermediate	project_first	fast_track + project_creation
advanced	any	fast_track
expert	any	skip_to_project

---

Pattern 3: Environment Verification

When to Use: Before any setup steps.

Check Sequence:

# 1. Git check
git --version  # Expected: git version 2.25+

# 2. Python check
python3 --version  # Expected: Python 3.10+

# 3. Claude Code check
claude --version  # Expected: any version

# 4. CODITECT symlink check (if in project)
ls -la .coditect 2>/dev/null || echo "Not configured"
ls -la .claude 2>/dev/null || echo "Not configured"

Error Recovery Templates:

git_missing:
  message: "Git is not installed."
  fix_macos: "brew install git"
  fix_ubuntu: "sudo apt install git"
  fix_windows: "Download from https://git-scm.com/download/win"

python_wrong_version:
  message: "Python 3.10+ required, found {version}."
  fix_macos: "brew install python@3.11"
  fix_ubuntu: "sudo apt install python3.11"
  fix_any: "Use pyenv: pyenv install 3.11.0 && pyenv global 3.11.0"

claude_missing:
  message: "Claude Code CLI not found."
  fix: "npm install -g @anthropic-ai/claude-code"
  verify: "claude --version"

---

Pattern 4: Shell Alias Setup

When to Use: Enable AI Command Router for new users.

Alias Configuration:

# For ~/.zshrc or ~/.bashrc
alias cr='claude "/suggest-agent"'
alias cri='claude --interactive "/suggest-agent"'

# Alternative with explicit path
alias cr='claude -p /suggest-agent'

Verification Dialog:

After adding the alias and running `source ~/.zshrc`:

Try: cr "I want to create a new component"

Expected output: A suggestion of which agent or command to use.

Did it work?
- Yes → Continue to project creation
- No → Troubleshoot shell config

---

Pattern 5: Project Scaffolding

When to Use: Create user's first CODITECT project.

Standard Structure:

[project-name]/
├── .coditect/                    # CODITECT configuration
│   ├── component-activation-status.json
│   └── settings.local.json
├── .claude -> .coditect          # Claude Code compatibility
├── docs/
│   ├── original-research/        # User's research materials
│   │   └── README.md
│   ├── architecture/             # Technical decisions
│   └── project-management/       # Plans and tasks
├── src/                          # Source code (if applicable)
├── tests/                        # Test files (if applicable)
├── .gitignore
├── README.md
└── CLAUDE.md                     # AI agent context

Creation Command:

/new-project "Build [description] with modern stack"

Post-Creation Verification:

def verify_project_creation(project_path: str) -> dict:
    """Verify project was created correctly."""
    required = [
        ".coditect",
        ".claude",
        "docs/original-research",
        "README.md",
        "CLAUDE.md"
    ]

    results = {}
    for path in required:
        full_path = f"{project_path}/{path}"
        results[path] = os.path.exists(full_path)

    return {
        "success": all(results.values()),
        "details": results
    }

---

Pattern 6: Task Tool Pattern Teaching

When to Use: The critical concept every user must learn.

Teaching Sequence:

1. Concept Introduction:

The Task Tool Pattern is the ONLY verified way to invoke CODITECT agents.
It uses a specific syntax that Claude Code understands.

2. Syntax Demonstration:

# Correct syntax
Task(
    subagent_type="general-purpose",
    prompt="Use [agent-name] subagent to [detailed task description]"
)

3. Common Mistakes:

# WRONG: Agent name in subagent_type
Task(subagent_type="orchestrator", prompt="Create a plan")

# WRONG: Missing "Use X subagent to" prefix
Task(subagent_type="general-purpose", prompt="Create a plan")

# WRONG: Plain text without Task wrapper
"Use orchestrator subagent to create a plan"

4. Hands-On Practice:

# User's first invocation
Task(
    subagent_type="general-purpose",
    prompt="Use orchestrator subagent to create an initial project plan
    for [user's project] with 3-4 phases and key milestones"
)

5. Verification:

Did you receive a project plan with phases and milestones?
- Yes → Pattern mastered, continue
- No → Review syntax, retry

---

Pattern 7: Session Continuity Setup

When to Use: Before user ends their first session.

Essential Commands:

# Quick context save
/cxs

# Major milestone checkpoint
python3 .coditect/scripts/create-checkpoint.py "Session description" --auto-push

Context Explanation:

CODITECT uses a memory system to prevent "catastrophic forgetting."

Without exports, each new session starts fresh with no memory of your work.

With exports:
- Your context is preserved in context-storage/
- You can resume exactly where you left off
- AI agents remember your project decisions

---

Pattern 8: Next Steps Routing

When to Use: After completing initial onboarding.

Path Options:

quick_continue:
  description: "Continue learning (30 min total)"
  actions:
    - "Read: docs/01-getting-started/USER-quick-start.md"
    - "Practice: Invoke 3 more agents"
    - "Complete: Module 1 Assessment"

immediate_build:
  description: "Start building now"
  actions:
    - "Use: cr 'what I want' for suggestions"
    - "Invoke: agents for project phases"
    - "Remember: /cxs before ending"

full_certification:
  description: "Complete certification (4-6 hours)"
  actions:
    - "Start: docs/11-training-certification/CODITECT-OPERATOR-TRAINING-SYSTEM.md"
    - "Goal: Expert Operator certification"
    - "Modules: 5 sequential training modules"

---

Automation Hooks

Auto-Detection Trigger

trigger: session_start
condition: "!exists(.coditect) && !exists(.claude)"
action: prompt_onboarding
message: |
  Welcome! This looks like a new project without CODITECT configuration.
  Would you like me to help you get started? (5-10 minutes)

Progress Tracking

onboarding_progress:
  phases:
    - name: "welcome"
      completed: false
    - name: "environment_check"
      completed: false
    - name: "shell_setup"
      completed: false
    - name: "project_creation"
      completed: false
    - name: "first_agent"
      completed: false
    - name: "session_management"
      completed: false
    - name: "next_steps"
      completed: false

  store_at: ".coditect/onboarding-progress.json"

---

Integration Points

Related Agent:

• agents/coditect-onboarding.md - Consultant persona implementation

Related Command:

• commands/onboard.md - Entry point slash command

Related Script:

• scripts/onboard-wizard.py - Automation for environment checks and scaffolding

Related Hook:

• hooks/onboard-welcome.md - Auto-trigger on new projects

---

Quality Metrics

Success Indicators:

• Environment check pass rate: > 95%
• Project creation success: > 99%
• First agent invocation success: > 90%
• User continues to second session: > 70%

Time Targets:

• Environment check: < 3 minutes
• Project creation: < 3 minutes
• First agent invocation: < 5 minutes
• Total onboarding: < 15 minutes

---

Success Output

When successful, this skill MUST output:

✅ SKILL COMPLETE: coditect-onboarding

Completed:
- [x] Environment verification passed (Git, Python, Claude Code)
- [x] Shell alias configured (cr command)
- [x] Project scaffolded at {project_path}
- [x] .coditect symlink created
- [x] First agent invoked successfully
- [x] Session continuity setup explained
- [x] User routed to next steps ({path})

Outputs:
- Project: {project_path}
- Configuration: .coditect/component-activation-status.json
- Context saved: /cx command explained

User Experience Level: {experience_level}
Onboarding Path: {path_type} (guided_detailed/fast_track/etc.)
Time Elapsed: {minutes} minutes

Completion Checklist

Before marking this skill as complete, verify:

• Git version checked (2.25+)
• Python version checked (3.10+)
• Claude Code CLI accessible
• Shell alias added to .zshrc or .bashrc
• Alias tested successfully (cr command works)
• Project directory created with correct structure
• .coditect symlink created and verified
• .claude symlink created (points to .coditect)
• First agent invocation succeeded (Task Tool Pattern)
• User received agent response
• /cx and /cxs commands explained
• Next steps provided based on user goal
• Onboarding progress saved (.coditect/onboarding-progress.json)

Failure Indicators

This skill has FAILED if:

• ❌ Environment check fails (missing Git/Python/Claude Code)
• ❌ Shell alias not working after configuration
• ❌ Project scaffolding creates incomplete structure
• ❌ .coditect symlink broken or missing
• ❌ First agent invocation returns error or no response
• ❌ User confused about Task Tool Pattern syntax
• ❌ Session continuity commands (/cx, /cxs) not explained
• ❌ User abandoned onboarding before completion
• ❌ Onboarding exceeded 20 minutes (time target missed)

When NOT to Use

Do NOT use this skill when:

• User already has CODITECT configured - Check for .coditect directory first
• Automated CI/CD environment - Use headless setup scripts instead
• Fork/clone of existing CODITECT project - Project already configured
• User wants to explore first - Offer help but don't force onboarding
• Emergency/time-critical task - Skip onboarding, get to work
• Experienced CODITECT user - They know the system already

Use alternative approaches instead:

• Existing project → Run verification check, offer targeted help only
• CI/CD → Use scripts/onboard-headless.sh
• Fork/clone → Verify configuration, update if needed
• Explorer → Provide quick-start link, let them browse
• Emergency → Jump to task, offer post-task onboarding
• Expert → Skip to project work immediately

Anti-Patterns (Avoid)

Anti-Pattern	Problem	Solution
Forcing onboarding on experts	Wastes time, frustrating	Assess experience first, offer skip option
No environment verification	Setup fails later	Always check Git/Python/Claude before proceeding
Skipping alias setup	User can't use cr command	Mandatory step, verify it works
Complex first task	User overwhelmed	First agent invocation should be simple (plan generation)
No hands-on practice	User doesn't learn Task Tool Pattern	Require user to invoke agent themselves
Skipping session continuity	User loses work between sessions	Explain /cx and /cxs before ending
No progress tracking	Can't resume if interrupted	Save onboarding progress to .coditect/onboarding-progress.json
One-size-fits-all path	Wrong pace for user	Branch based on experience level and goal

Principles

This skill embodies CODITECT principles:

• #5 Eliminate Ambiguity - Clear step-by-step progression, explicit verification
• #6 Clear, Understandable, Explainable - Explain "why" for each step (alias enables AI routing, /cx preserves context)
• #8 No Assumptions - Verify environment, test commands, confirm success
• First Principles - Understand user's goal (quick learn vs certification vs project) before choosing path
• Automation - Auto-detect first-run, auto-scaffold project, auto-verify setup
• Progressive Disclosure - Start simple (environment check), gradually introduce concepts (Task Tool Pattern, session continuity)

Related Standards:

• CODITECT-STANDARD-AUTOMATION.md
• CODITECT-STANDARD-SKILLS.md

---

Author: CODITECT Framework Team Framework: CODITECT v1.0