Workspace Builder Skill

Master specification for building the agentic workflow system. This skill is reference documentation - use component-specific skills for building.

Overview

This workspace provides a reusable, multi-project automation system with:

• Semantic routing for intelligent resource selection

• RAG (vector search) with project isolation

• Modular agents, skills, and commands

• Template-based architecture for cloning to new projects

Architecture

┌─────────────────────────────────────────────────────────────────┐ │ USER QUERY │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ SEMANTIC ROUTER │ │ Tier 1: Category (command | agent | skill | workflow) │ │ Tier 2: Specific resource (e.g., "researcher" agent) │ └─────────────────────────────────────────────────────────────────┘ │ ┌───────────────┼───────────────┐ ▼ ▼ ▼ ┌─────────┐ ┌─────────┐ ┌─────────┐ │Commands │ │ Agents │ │Workflows│ └─────────┘ └─────────┘ └─────────┘ │ ▼ ┌─────────────────┐ │ RAG Server │ │ (Qdrant) │ └─────────────────┘

Component Build Order

Build in this sequence for incremental testing:

Phase 1: Foundation

• Directory structure ✅

• CLAUDE.md ✅

• Config files (base.yaml, .env.template)

• Setup scripts (setup.sh, init-project.sh)

Phase 2: Core Services

• RAG Server → See skills/rag-builder/SKILL.md

• Router → See skills/router-builder/SKILL.md

Phase 3: Interface Layer

• Slash Commands (research, code-review, daily-standup)

• MCP Config (wire up servers)

Phase 4: Agents

• Sub-agents → See skills/agent-builder/SKILL.md

• Orchestrator (ties everything together)

Phase 5: Automation

• Workflows (YAML definitions + executor)

• Service management (start/stop scripts)

Key Technical Decisions

Vector Database: Qdrant

Why Qdrant:

- High performance vector search

- Production-ready with persistence

- REST and gRPC APIs

- Excellent filtering capabilities

from qdrant_client import QdrantClient client = QdrantClient(url="http://localhost:6333")

Collections managed via MCP server with COLLECTION_NAME env var

Embeddings: all-MiniLM-L6-v2

Shared across RAG and Router

- Fast (384 dimensions)

- Good quality

- Runs locally

from sentence_transformers import SentenceTransformer model = SentenceTransformer('all-MiniLM-L6-v2')

Routing: Semantic Router

Why Semantic Router:

- ~10ms decisions (not LLM calls)

- Scales to 1000s of resources

- Same embeddings as RAG

from semantic_router import Route, RouteLayer

Configuration Strategy

Layered Config

config/base.yaml # Defaults (version controlled) config/local.yaml # Overrides (git-ignored) .env # Secrets (git-ignored)

Multi-Project Pattern

Clone template

git clone <repo> project-alpha cd project-alpha

Initialize project

./scripts/init-project.sh project-alpha

Creates:

- .env.project-alpha (credentials)

- config/profiles/project-alpha.yaml

- Isolated RAG collections

File Templates

Slash Command Template

Command Name

You are executing the command-name command.

Instructions

1. First step
2. Second step
3. Output format

Output

Describe expected output format.

Agent Prompt Template

Agent Name

You are a specialized Agent Name focused on [domain].

Core Capabilities

1. Capability one
2. Capability two

Tools Available

• tool_name: Description

Operating Principles

• Principle one
• Principle two

Output Standards

• Standard one
• Standard two

Route Definition Template

routes:

• name: resource-name utterances:
  • "example phrase one"
  • "example phrase two"
  • "variation three"
  • "variation four"
  • "at least 5-10 examples" metadata: file: "path/to/resource" description: "What this resource does"

Testing Strategy

Incremental Testing

Test RAG server

python -c "from rag.server import RAGServer; print('RAG OK')"

Test router

python -c "from routing.router import route; print(route('test query'))"

Test full flow

python -c " from routing.router import route result = route('research quantum computing') print(f'Routed to: {result.category}/{result.resource_name}') "

Integration Test

Start all services

./scripts/start-services.sh

Test via MCP

(use Claude Code to interact)

Refinement Process

As we build, update docs when:

• Implementation differs from spec

• Better patterns emerge

• Edge cases are discovered

After implementing a component:

1. Test it works

2. Update relevant SKILL.md with actual code

3. Update CLAUDE.md status

4. Commit with descriptive message

Dependencies

requirements.txt

pyyaml>=6.0 python-dotenv>=1.0.0 mcp>=1.0.0 qdrant-client>=1.7.0 sentence-transformers>=2.2.0 semantic-router>=0.1.0 aiofiles>=23.0.0 httpx>=0.25.0

Next Action

To start building, use one of the component skills:

• view skills/rag-builder/SKILL.md

• Build RAG server first

• view skills/router-builder/SKILL.md

• Build semantic router

• view skills/agent-builder/SKILL.md

• Build sub-agents