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:

Collection	Content	Metadata
{project}_docs	README, guides, API docs	type: doc, source: file
{project}_code	Reusable patterns, examples	type: code, language: python
{project}_decisions	ADRs, design docs	type: decision, status: accepted
{project}_research	Research notes, findings	type: research, topic: x

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

Issue	Solution
Collections not created	Check RAG server is running
Search returns nothing	Verify documents were ingested
Routing not working	Reload router embeddings
Code symlink broken	Check absolute path is correct

Refinement Notes

Add notes here as you onboard projects and discover improvements.

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