Project Onboarding

Project Onboarding Skill

Quickly onboard a new project into the agentic workspace with RAG collections, routing rules, and baseline knowledge.

Overview

When starting work on a new project, this skill provides a systematic approach to:

• Create project-specific RAG collections
• Register semantic routing rules
• Ingest existing documentation as baseline knowledge
• Set up credentials and configuration
• Validate the setup

Prerequisites

• Workspace with RAG server running
• Router server running
• Access to the project's source code or documentation

Onboarding Steps

Step 1: Gather Project Information

Before onboarding, collect:

project:
  name: "project-slug"           # Lowercase, hyphenated
  display_name: "Project Name"   # Human-readable
  code_path: "/path/to/code"     # Absolute path to source
  description: "Brief description of the project"

  # Optional
  tech_stack:
    - python
    - fastapi
    - postgresql

  docs_paths:
    - README.md
    - docs/
    - ARCHITECTURE.md

Step 2: Create RAG Collections

Create isolated collections for different content types:

# Collection naming convention: {project}_{content_type}
collections = [
    f"{project_name}_docs",      # Documentation, READMEs
    f"{project_name}_code",      # Code snippets, patterns
    f"{project_name}_decisions", # ADRs, architectural decisions
    f"{project_name}_research",  # Research findings, notes
]

# Create via RAG server
for collection in collections:
    await rag.create_collection(collection)

Recommended collection structure:

Step 3: Ingest Baseline Documentation

#!/bin/bash
# scripts/onboard-docs.sh

PROJECT=$1
CODE_PATH=$2

# Ingest README
if [ -f "$CODE_PATH/README.md" ]; then
    /ingest --collection "${PROJECT}_docs" \
            --source "readme" \
            --file "$CODE_PATH/README.md"
fi

# Ingest docs directory
if [ -d "$CODE_PATH/docs" ]; then
    find "$CODE_PATH/docs" -name "*.md" -exec \
        /ingest --collection "${PROJECT}_docs" \
                --source "docs" \
                --file {} \;
fi

# Ingest architecture docs
for doc in ARCHITECTURE.md DESIGN.md CONTRIBUTING.md; do
    if [ -f "$CODE_PATH/$doc" ]; then
        /ingest --collection "${PROJECT}_decisions" \
                --source "architecture" \
                --file "$CODE_PATH/$doc"
    fi
done

Step 4: Register Routing Rules

Add project-specific routing so queries get directed appropriately:

# routing/routes/project-{name}.yaml
routes:
  - name: "{project}_code_search"
    utterances:
      - "find code in {project}"
      - "search {project} for"
      - "how does {project} implement"
      - "{project} code pattern"
    action:
      type: rag_search
      collection: "{project}_code"

  - name: "{project}_docs_search"
    utterances:
      - "{project} documentation"
      - "how to use {project}"
      - "{project} setup"
      - "{project} guide"
    action:
      type: rag_search
      collection: "{project}_docs"

  - name: "{project}_decisions"
    utterances:
      - "why did {project}"
      - "{project} architecture"
      - "{project} design decision"
    action:
      type: rag_search
      collection: "{project}_decisions"

Step 5: Create Project Configuration

# config/projects/{project}.yaml
project:
  name: "{project}"
  display_name: "{Project Display Name}"
  code_path: "/path/to/code"

collections:
  docs: "{project}_docs"
  code: "{project}_code"
  decisions: "{project}_decisions"
  research: "{project}_research"

credentials:
  # Reference to .env variables
  api_key: "{PROJECT}_API_KEY"
  database_url: "{PROJECT}_DATABASE_URL"

defaults:
  search_collection: "{project}_docs"
  search_results: 5

Step 6: Create Code Symlink

# Link project code into workspace
ln -sf /path/to/actual/code ./code/{project}

Step 7: Validate Setup

#!/usr/bin/env python3
"""Validate project onboarding."""

import asyncio
from pathlib import Path

async def validate_onboarding(project: str):
    errors = []

    # Check collections exist
    collections = await rag.list_collections()
    expected = [f"{project}_docs", f"{project}_code",
                f"{project}_decisions", f"{project}_research"]

    for coll in expected:
        if coll not in [c["name"] for c in collections]:
            errors.append(f"Missing collection: {coll}")

    # Check config exists
    config_path = Path(f"config/projects/{project}.yaml")
    if not config_path.exists():
        errors.append(f"Missing config: {config_path}")

    # Check code symlink
    code_path = Path(f"code/{project}")
    if not code_path.exists():
        errors.append(f"Missing code symlink: {code_path}")

    # Check routing rules
    route_path = Path(f"routing/routes/project-{project}.yaml")
    if not route_path.exists():
        errors.append(f"Missing routes: {route_path}")

    # Test search works
    try:
        results = await rag.search(
            query="project overview",
            collection=f"{project}_docs",
            n_results=1
        )
        if not results["results"]:
            errors.append("No documents in docs collection")
    except Exception as e:
        errors.append(f"Search failed: {e}")

    return errors

if __name__ == "__main__":
    import sys
    project = sys.argv[1]
    errors = asyncio.run(validate_onboarding(project))

    if errors:
        print("❌ Onboarding validation failed:")
        for e in errors:
            print(f"  - {e}")
        sys.exit(1)
    else:
        print(f"✅ Project '{project}' onboarded successfully!")

Quick Onboarding Script

#!/bin/bash
# scripts/onboard-project.sh

set -e

PROJECT=$1
CODE_PATH=$2
DISPLAY_NAME=${3:-$PROJECT}

if [ -z "$PROJECT" ] || [ -z "$CODE_PATH" ]; then
    echo "Usage: onboard-project.sh <project-slug> <code-path> [display-name]"
    exit 1
fi

echo "🚀 Onboarding project: $PROJECT"

# Step 1: Create collections
echo "📦 Creating RAG collections..."
for type in docs code decisions research; do
    curl -X POST "http://localhost:8100/create_collection" \
        -d "{\"name\": \"${PROJECT}_${type}\"}"
done

# Step 2: Create config
echo "⚙️ Creating project config..."
cat > "config/projects/${PROJECT}.yaml" << EOF
project:
  name: "${PROJECT}"
  display_name: "${DISPLAY_NAME}"
  code_path: "${CODE_PATH}"

collections:
  docs: "${PROJECT}_docs"
  code: "${PROJECT}_code"
  decisions: "${PROJECT}_decisions"
  research: "${PROJECT}_research"
EOF

# Step 3: Create code symlink
echo "🔗 Creating code symlink..."
mkdir -p code
ln -sf "$CODE_PATH" "code/${PROJECT}"

# Step 4: Ingest docs
echo "📚 Ingesting documentation..."
./scripts/onboard-docs.sh "$PROJECT" "$CODE_PATH"

# Step 5: Create routing rules
echo "🔀 Creating routing rules..."
cat > "routing/routes/project-${PROJECT}.yaml" << EOF
routes:
  - name: "${PROJECT}_search"
    utterances:
      - "${PROJECT}"
      - "search ${PROJECT}"
      - "${PROJECT} code"
      - "${PROJECT} docs"
    action:
      type: rag_search
      collection: "${PROJECT}_docs"
EOF

# Step 6: Validate
echo "✅ Validating..."
python scripts/validate-onboarding.py "$PROJECT"

echo "🎉 Project '$PROJECT' onboarded successfully!"

Usage Examples

# Onboard a Python project
./scripts/onboard-project.sh my-api ~/projects/my-api "My API Service"

# Onboard with just slug and path
./scripts/onboard-project.sh client-portal ~/work/client-portal

# Validate existing project
python scripts/validate-onboarding.py my-api

Post-Onboarding

After onboarding:

1. Ingest more content as you work:

   /ingest --collection my-api_research --content "Found that..."
   

2. Refine routing rules based on actual usage patterns

3. Add project-specific workflows in workflows/definitions/

Troubleshooting

Refinement Notes

Add notes here as you onboard projects and discover improvements.

• Initial implementation
• Tested with real project
• Automated script working
• Routing integration verified