FazAI Agentic Developer

This skill transforms you into a specialized developer for the FazAI-NG codebase, leveraging its unique agentic architecture with Qdrant vector search, GenAIScript automation, and local LLM inference.

When to Use This Skill

• •Working on FazAI-NG codebase (TypeScript/Node.js)
• •Applying patches or implementing features
• •Tasks requiring context from multiple files (use Qdrant first!)
• •Complex multi-step operations needing task decomposition
• •Running or creating GenAIScript agents
• •Integrating with Qdrant collections
• •Linux system administration automation

Core Principles

1. Qdrant First - Token Economy

CRITICAL: Before using Read/Grep/Glob to explore code, ALWAYS query Qdrant first.

How to query (use the script to avoid shell escaping issues):

# Use the helper script (recommended - avoids $() escaping bug)
./scripts/qdrant-search.sh "how does circuit breaker work" source

# Collections: source, learning, kb, memory, personality, inference
./scripts/qdrant-search.sh "error patterns" learning
./scripts/qdrant-search.sh "chats anteriores" personality

Alternative (two-step, avoids subshell):

# Step 1: Generate embedding to temp file
# Uses OLLAMA_BASE_URL from environment or defaults to localhost
curl -s -X POST "${OLLAMA_BASE_URL:-http://localhost:11434}/api/embeddings" \
  -d '{"model":"nomic-embed-text","prompt":"circuit breaker"}' \
  | jq -c '.embedding' > /tmp/embed.json

# Step 2: Search with the embedding
curl -s -X POST 'http://localhost:6333/collections/fazai_source/points/search' \
  -H 'Content-Type: application/json' \
  -d '{"vector":'$(cat /tmp/embed.json)',"limit":5,"with_payload":true}' \
  | jq '.result[] | {path: .payload.path, score: .score}'

Collections available:

2. Task Decomposition for Complex Operations

For any task with 3+ steps, decompose into subtasks with dependencies:

{
  "subtasks": [
    {
      "id": "task-1",
      "description": "Verify prerequisites",
      "dependencies": [],
      "verificationCommand": "which node && node --version"
    },
    {
      "id": "task-2",
      "description": "Apply patch to config.ts",
      "dependencies": ["task-1"],
      "command": "patch -p1 < .1-config.ts.diff",
      "verificationCommand": "grep -q 'getLocalInferenceModel' src/config.ts"
    }
  ],
  "executionPlan": "Sequential with verification at each step"
}

3. GenAIScript for Automation

FazAI uses GenAIScript (v2.5.1) for agentic automation. Key scripts:

Reflect modes:

• •mode=reflect (default): Retrospective analysis using Claude
• •mode=plan: Proactive Maestro planning using local model (Phi-3/Llama)

4. Local-First AI (Phi-3 / Llama)

For planning and simple tasks, prefer local models to save costs.

Ollama endpoint: Configured via OLLAMA_BASE_URL (default: http://localhost:11434)

5. External Sources (Context7)

When local knowledge is insufficient, consult external sources:

1. •First: Qdrant (local knowledge)
2. •Then: GenAIScript tools
3. •Finally: External sources (Context7, web search)

Reflexao de Mudancas (Change Reflection)

REGRA DE OURO: Toda alteracao no codigo deve refletir nos artefatos relacionados.

Checklist Obrigatorio

Comando Mental

Ao finalizar qualquer tarefa, pergunte-se:

"Essa mudanca afeta como o usuario INSTALA, USA, CONFIGURA ou VISUALIZA o FazAI?"

Se sim -> Atualize os artefatos correspondentes.

How to Use

Applying Patches (EXEC Mode)

Process:

1. •Check git status (must be clean)
2. •Query Qdrant for current implementation context
3. •Decompose into subtasks with dependencies
4. •Apply each patch with verification
5. •Run npm run build to validate
6. •Smoke test with genaiscript run reflect --help
7. •Update CHANGELOG.md and other affected artifacts
8. •Commit with exact message provided

Implementing Features

Process:

1. •Query Qdrant for existing patterns
2. •Analyze patterns from search results
3. •Decompose implementation into subtasks
4. •Test locally with Phi-3 before cloud models
5. •Verify with npm run build
6. •Reflect changes to CHANGELOG, README, help if needed

Instructions

1. Context Gathering (Qdrant First!)

Before ANY code exploration, query Qdrant semantic search. Only use Read/Grep after Qdrant search if:

• •Search returns no relevant results
• •You need complete file context (rare)
• •Modifying specific line numbers

2. Task Planning (Decompose)

For complex tasks, create execution plan with:

• •Prerequisite checks
• •Context gathering via Qdrant
• •Implementation steps
• •Verification steps
• •Reflection (update artifacts)
• •Commit

3. Verification Workflow

After any code change:

1. •npm run build (type check)
2. •genaiscript run reflect --help (if touched genaisrc/)
3. •git diff --stat

4. Commit Standards

Format: type(scope): description Types: feat, fix, refactor, docs, test, chore

Architecture Reference

Project Structure

fazai-ng/
├── src/
│   ├── config.ts              # Centralized config
│   ├── system-info.ts         # Linux introspection
│   ├── logger.ts              # Structured logging
│   ├── agentic/               # Task decomposer, DAG executor
│   └── services/              # Embeddings, indexer, qdrant-pool
├── genaisrc/                  # GenAIScript agents
├── web/                       # Next.js dashboard
├── systemd/                   # Service files
├── scripts/                   # Bash completion, helpers
├── install.sh                 # Installation script
├── CHANGELOG.md               # Version history
└── README.md                  # Documentation

Key Patterns

ECOA (Semantic Deduplication):

• •All embeddings normalized to 1536 dimensions
• •Fusion scoring with weights

Circuit Breaker (Qdrant):

• •CLOSED -> OPEN -> HALF_OPEN states

Agentic Loop (5 iterations max): Query -> Qdrant Search -> Reflect -> Generate Insight -> Upsert -> Respond

Examples

Example 1: Applying V2.1 Patches

1. •git status (verify clean)
2. •Apply patches in order with verification
3. •npm run build
4. •Smoke test
5. •Update CHANGELOG.md
6. •Commit with exact message

Example 2: Finding Implementation Details

1. •Query Qdrant first
2. •Explain based on chunks
3. •Only Read full file if needed

Related Skills/Agents