{"_id":"@citadelcloud/saas-factory","name":"@citadelcloud/saas-factory","dist-tags":{"latest":"3.1.0"},"versions":{"3.1.0":{"name":"@citadelcloud/saas-factory","version":"3.1.0","description":"Universal Full-Stack SaaS Production Framework — 265 Autonomous Business Agents, Multi-Model Routing, Cross-IDE Support","author":{"name":"Citadel Cloud Management","email":"info@citadelcloudmanagement.com"},"license":"MIT","homepage":"https://github.com/Citadel-Cloud-Management/citadel-saas-factory","repository":{"type":"git","url":"git+https://github.com/Citadel-Cloud-Management/citadel-saas-factory.git"},"bugs":{"url":"https://github.com/Citadel-Cloud-Management/citadel-saas-factory/issues"},"keywords":["saas","framework","agents","ai-agents","multi-model","claude","cursor","fastapi","nextjs","kubernetes","gitops","devops","scaffold","boilerplate","llm","mcp"],"bin":{"citadel-factory":"bin/cli.js"},"engines":{"node":">=18.0.0"},"gitHead":"533e298b3fdb0b77ff05abe62e74dd121ff612a9","_id":"@citadelcloud/saas-factory@3.1.0","_nodeVersion":"25.1.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-NNqWA6bbc8xLIDeLb4+1Iskw5mTBlMQtEcoB5XM3EAy9NlE9KZytQQmLZpfVyqGOlUu6U8sYahWMwoP+RIu2/w==","shasum":"ff5709159ef76d262835415df8ab9c3be70be0a0","tarball":"https://registry.npmjs.org/@citadelcloud/saas-factory/-/saas-factory-3.1.0.tgz","fileCount":51,"unpackedSize":222705,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIDbrTJHahXVhbWnScsLVNddzKeIOs2BSTFq46/NhJPSBAiEAoKIl/iyJNSUvXrX/iw7y6gm0e9tXV/hF53VNHSPBuY4="}]},"_npmUser":{"name":"citadelcloud","email":"kogunlowo@gmail.com"},"directories":{},"maintainers":[{"name":"citadelcloud","email":"kogunlowo@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/saas-factory_3.1.0_1776447793691_0.4966750584081705"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-17T17:43:13.619Z","3.1.0":"2026-04-17T17:43:13.826Z","modified":"2026-04-17T17:43:14.022Z"},"maintainers":[{"name":"citadelcloud","email":"kogunlowo@gmail.com"}],"description":"Universal Full-Stack SaaS Production Framework — 265 Autonomous Business Agents, Multi-Model Routing, Cross-IDE Support","homepage":"https://github.com/Citadel-Cloud-Management/citadel-saas-factory","keywords":["saas","framework","agents","ai-agents","multi-model","claude","cursor","fastapi","nextjs","kubernetes","gitops","devops","scaffold","boilerplate","llm","mcp"],"repository":{"type":"git","url":"git+https://github.com/Citadel-Cloud-Management/citadel-saas-factory.git"},"author":{"name":"Citadel Cloud Management","email":"info@citadelcloudmanagement.com"},"bugs":{"url":"https://github.com/Citadel-Cloud-Management/citadel-saas-factory/issues"},"license":"MIT","readme":"# Citadel SaaS Factory\n\n**Universal Full-Stack SaaS Production Framework — 265 Autonomous Business Agents**\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE) [![Claude Code](https://img.shields.io/badge/Claude_Code-Ready-blueviolet)](https://claude.ai/code) [![Agents](https://img.shields.io/badge/Agents-265-orange)](.claude/agents/_registry.yaml) [![Free Tools](https://img.shields.io/badge/Tools-$0/month-brightgreen)](#free-toolchain) [![Infrastructure](https://img.shields.io/badge/Infrastructure-Any-blue)](#infrastructure-agnostic) [![Multi-Model](https://img.shields.io/badge/Models-9_Providers-purple)](models/catalog.yaml) [![Cross-IDE](https://img.shields.io/badge/IDEs-8_Supported-blue)](#cross-ide-support)\n\n**Clone. Configure. Deploy. Any infrastructure. Zero software cost.**\n\n---\n\n## Quick Start\n\n```bash\ngit clone https://github.com/Citadel-Cloud-Management/citadel-saas-factory.git\ncd citadel-saas-factory\ncp .env.example .env          # Set your API keys (at minimum one provider)\n./scripts/parallel-bootstrap.sh   # Parallel install: models, MCP, hooks, agents\n./scripts/verify-install.sh       # Green/red verification report\nclaude                            # Or open in Cursor, Antigravity, Copilot, Codex, Jules...\n```\n\n### Alternative: Just\n\n```bash\njust bootstrap   # Same as parallel-bootstrap.sh\njust status      # System health check\njust eval        # Run model evaluations\n```\n\n---\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│                        CLIENTS                                  │\n│              Browser / Mobile / API Consumers                   │\n└──────────────────────────┬──────────────────────────────────────┘\n                           │\n┌──────────────────────────▼──────────────────────────────────────┐\n│                     REVERSE PROXY                               │\n│                  Traefik (TLS, Routing)                          │\n└──────────┬───────────────┬───────────────┬──────────────────────┘\n           │               │               │\n┌──────────▼───┐  ┌────────▼───┐  ┌────────▼──────────┐\n│   FRONTEND   │  │  BACKEND   │  │    AUTH GATEWAY    │\n│  Next.js 14  │  │  FastAPI   │  │   Keycloak 24      │\n│  TypeScript  │  │ Python 3.12│  │ OAuth2/RBAC/MFA    │\n└──────────────┘  └─────┬──────┘  └────────────────────┘\n                        │\n        ┌───────────────┼───────────────┐\n        │               │               │\n┌───────▼───┐  ┌────────▼───┐  ┌───────▼────────┐\n│ DATABASE  │  │   CACHE    │  │   MESSAGING    │\n│ Postgres  │  │  Redis 7   │  │   RabbitMQ     │\n│    16     │  │            │  │                │\n└───────────┘  └────────────┘  └────────────────┘\n        │\n┌───────▼───────────────────────────────────────────────┐\n│                    STORAGE & SECRETS                    │\n│          MinIO (S3-compatible)  |  HashiCorp Vault      │\n└───────────────────────────────────────────────────────┘\n        │\n┌───────▼───────────────────────────────────────────────┐\n│                   ORCHESTRATION                        │\n│     K3s + ArgoCD (GitOps) | Linkerd (mTLS mesh)       │\n└───────────────────────────────────────────────────────┘\n        │\n┌───────▼───────────────────────────────────────────────┐\n│                    OBSERVABILITY                       │\n│       Prometheus | Grafana | Loki | Tempo | Falco     │\n└───────────────────────────────────────────────────────┘\n```\n\n### Tech Stack\n\n| Layer | Technology | Purpose |\n|-------|-----------|---------|\n| Backend | FastAPI (Python 3.12) | REST/GraphQL API, business logic |\n| Frontend | Next.js 14 (TypeScript) | SSR/SSG UI, React components |\n| Database | PostgreSQL 16 | Primary data store, RLS, pgvector |\n| Cache | Redis 7 | Session cache, rate limiting, pub/sub |\n| Auth | Keycloak 24 | OAuth2, RBAC, MFA, SSO |\n| Storage | MinIO | S3-compatible object storage |\n| Messaging | RabbitMQ | Async messaging, event bus, DLQ |\n| Orchestration | K3s + ArgoCD | Lightweight K8s, GitOps deployment |\n| Reverse Proxy | Traefik | TLS termination, routing, middleware |\n| Service Mesh | Linkerd | mTLS, traffic policies, observability |\n| Secrets | HashiCorp Vault | Secret management, rotation, encryption |\n| Monitoring | Prometheus + Grafana + Loki | Metrics, dashboards, log aggregation |\n\n---\n\n## Multi-Model Support\n\nAgents reference model **tiers**, not specific models. Swap providers by changing one env var.\n\n| Tier | Primary | Fallbacks | Use Case |\n|------|---------|-----------|----------|\n| `reasoning_deep` | Claude Opus 4.6 | Gemini 3 Pro, DeepSeek R1, GPT-5 | Architecture, critical decisions |\n| `reasoning_fast` | Claude Sonnet 4.6 | Gemini 3 Pro, GPT-5, DeepSeek V3.1 | Default coding tasks |\n| `cheap_fast` | Claude Haiku 4.5 | Gemini 3 Flash, GPT-5 Mini | Completion, boilerplate |\n| `long_context` | Gemini 3.1 Pro | Gemini 3 Pro, Claude Opus, GPT-4.1 | Full codebase analysis (2M tokens) |\n| `code_specialist` | Codestral 25 | Qwen 2.5 Coder, DeepSeek V3.1 | Code generation and review |\n| `vision` | Claude Opus 4.6 | Gemini 3 Pro, GPT-5 | Screenshot/design to code |\n| `local_only` | Llama 3.3 70B | DeepSeek V3.1, Qwen 2.5 Coder | Air-gapped, zero cost |\n\n**9 providers**: Anthropic, OpenAI, Google, xAI, DeepSeek, Mistral, Cohere, Meta, Alibaba\n**8 gateways**: OpenRouter, LiteLLM, Groq, Together, Fireworks, Cerebras, Bedrock, Vertex\n**5 local runtimes**: Ollama, vLLM, llama.cpp, LocalAI, LM Studio\n\nSee [`models/catalog.yaml`](models/catalog.yaml), [`models/routing.yaml`](models/routing.yaml), [`models/embeddings.yaml`](models/embeddings.yaml).\n\n---\n\n## Cross-IDE Support\n\nThis repo is recognized as a first-class project by every major AI coding tool:\n\n| Tool | Config File | Status |\n|------|-------------|--------|\n| Claude Code | `.claude/CLAUDE.md` | Native |\n| Cursor | `.cursor/rules/`, `AGENT.md` | Native |\n| GitHub Copilot | `.github/copilot-instructions.md` | Native |\n| OpenAI Codex | `.codex/config.toml`, `AGENTS.md` | Native |\n| Google Jules | `.jules/config.yml`, `GEMINI.md` | Native |\n| Antigravity | `.antigravity/rules.md` | Native |\n| Windsurf/Codeium | `.windsurf/rules/` | Native |\n| Continue.dev | `.continue/config.json` | Native |\n| Devin | `.devin/config.yml` | Ready |\n| CodeRabbit | `.coderabbit.yml` | Ready |\n| Factory AI | `.factory/droids.yml` | Ready |\n| OpenHands | `openhands/config.toml` | Ready |\n\n---\n\n## Infrastructure Agnostic\n\nRuns on any Linux server with SSH and Docker. No cloud vendor lock-in.\n\n- Any VPS provider (Hetzner, DigitalOcean, Linode, Vultr)\n- Bare metal servers\n- On-premises infrastructure\n- Edge deployments\n- Home lab\n\n---\n\n## `.claude/` Directory Structure\n\n```\n.claude/\n├── CLAUDE.md                          # Master intelligence file\n├── settings.json                      # Claude Code configuration\n├── memory/\n│   ├── MEMORY.md                      # Auto-memory (persists across sessions)\n│   ├── project_citadel_saas_factory.md\n│   └── adrs/                          # Architecture Decision Records\n├── agents/\n│   ├── _registry.yaml                 # Master agent registry (265 agents)\n│   ├── executive/                     # 12 executive & strategy agents\n│   ├── marketing/                     # 22 marketing & growth agents\n│   ├── sales/                         # 18 sales & revenue agents\n│   ├── customer-success/              # 15 customer success agents\n│   ├── design/                        # 20 product & UI/UX agents\n│   ├── engineering/                   # 25 engineering agents\n│   ├── frontend/                      # 18 frontend agents\n│   ├── devops/                        # 28 DevOps agents\n│   ├── security/                      # 22 security agents\n│   ├── data/                          # 18 data & analytics agents\n│   ├── qa/                            # 22 QA & testing agents\n│   ├── hr/                            # 12 HR & people agents\n│   ├── finance/                       # 15 finance & billing agents\n│   ├── legal/                         # 8 legal & governance agents\n│   └── content/                       # 10 content & comms agents\n├── hooks/\n│   ├── pre-commit.sh                  # Secret scanning, lint, format\n│   ├── post-commit.sh                 # Coverage check, changelog update\n│   ├── pre-push.sh                    # Security scan, test run\n│   ├── pre-tool-use.sh                # Parameter validation\n│   ├── post-tool-use.sh               # Auto-format, checks\n│   ├── pre-deploy.sh                  # Image scan, smoke test\n│   ├── post-deploy.sh                 # Health check, notification\n│   ├── pre-rollback.sh                # State snapshot\n│   ├── post-rollback.sh               # Verification, alerting\n│   └── stop.sh                        # Final verification on session end\n├── rules/\n│   ├── accessibility.md               # WCAG 2.1 AA compliance\n│   ├── api-design.md                  # RESTful conventions, OpenAPI\n│   ├── architecture.md                # Clean architecture, DDD\n│   ├── code-quality.md                # Immutability, small files\n│   ├── database.md                    # Migrations, RLS, indexes\n│   ├── dependencies.md                # Lock files, audits\n│   ├── devops.md                      # GitOps, immutable infra\n│   ├── documentation.md               # API docs, ADRs\n│   ├── error-handling.md              # Structured errors, retry\n│   ├── frontend.md                    # Components, a11y, perf\n│   ├── git.md                         # Conventional commits\n│   ├── monitoring.md                  # Structured logging, RED\n│   ├── naming.md                      # snake_case, camelCase\n│   ├── performance.md                 # Caching, lazy loading\n│   ├── review.md                      # PR process, checklists\n│   ├── secrets.md                     # Vault, rotation, scanning\n│   ├── security.md                    # Input validation, XSS, CSRF\n│   └── testing.md                     # TDD, 80% coverage\n├── commands/\n│   ├── deploy.md                      # Deploy to environment\n│   ├── rollback.md                    # Emergency rollback\n│   ├── scaffold.md                    # Code generation\n│   ├── audit.md                       # Security & quality audit\n│   ├── status.md                      # System & agent status\n│   ├── migrate.md                     # Database migrations\n│   ├── seed.md                        # Seed data\n│   ├── test.md                        # Run test suites\n│   ├── lint.md                        # Run linters\n│   ├── format.md                      # Run formatters\n│   ├── build.md                       # Build artifacts\n│   ├── release.md                     # Create release\n│   ├── backup.md                      # Database backup\n│   ├── restore.md                     # Database restore\n│   ├── monitor.md                     # View dashboards\n│   ├── logs.md                        # View logs\n│   ├── secrets.md                     # Manage secrets\n│   ├── certs.md                       # Manage TLS certs\n│   ├── scale.md                       # Scale services\n│   └── perf.md                        # Performance profiling\n├── templates/\n│   ├── api-endpoint.py                # FastAPI endpoint template\n│   ├── model.py                       # SQLAlchemy model template\n│   ├── schema.py                      # Pydantic schema template\n│   ├── service.py                     # Service layer template\n│   ├── repository.py                  # Repository template\n│   ├── migration.py                   # Alembic migration template\n│   ├── test-unit.py                   # Unit test template\n│   ├── test-integration.py            # Integration test template\n│   ├── test-e2e.py                    # E2E test template\n│   ├── component.tsx                  # React component template\n│   ├── page.tsx                       # Next.js page template\n│   ├── form.tsx                       # Form component template\n│   ├── table.tsx                      # Data table template\n│   ├── hook.ts                        # Custom hook template\n│   ├── store.ts                       # Zustand store template\n│   ├── dockerfile                     # Multi-stage Dockerfile\n│   ├── helm-chart/                    # Helm chart template\n│   ├── github-action.yml              # CI/CD workflow template\n│   ├── kyverno-policy.yaml            # Admission policy template\n│   └── grafana-dashboard.json         # Dashboard template\n├── skills/\n│   ├── api-patterns.md                # API design patterns\n│   ├── auth-patterns.md               # Authentication flows\n│   ├── cache-patterns.md              # Caching strategies\n│   ├── db-patterns.md                 # Database patterns\n│   ├── event-patterns.md              # Event-driven architecture\n│   ├── frontend-patterns.md           # React/Next.js patterns\n│   ├── k8s-patterns.md               # Kubernetes patterns\n│   ├── security-patterns.md           # Security patterns\n│   ├── testing-patterns.md            # Testing strategies\n│   ├── monitoring-patterns.md         # Observability patterns\n│   ├── gitops-patterns.md             # GitOps workflows\n│   ├── multi-tenant-patterns.md       # Multi-tenancy patterns\n│   ├── migration-patterns.md          # Zero-downtime migrations\n│   ├── performance-patterns.md        # Performance optimization\n│   └── deployment-patterns.md         # Deployment strategies\n└── mcp/\n    ├── github.json                    # GitHub MCP server config\n    ├── filesystem.json                # Filesystem MCP server config\n    ├── postgres.json                  # PostgreSQL MCP server config\n    ├── docker.json                    # Docker MCP server config\n    ├── kubernetes.json                # Kubernetes MCP server config\n    ├── ruflo.json                     # Ruflo swarm MCP server config\n    ├── graphify.json                  # Graphify knowledge graph config\n    └── context7.json                  # Context7 docs MCP server config\n```\n\n---\n\n## All 265 Agents — 15 Domains\n\n### Domain 1: Executive & Strategy (12 Agents)\n\n| # | Agent ID | Name | Description |\n|---|----------|------|-------------|\n| 1 | `exec-ceo-strategist` | CEO Strategist | Business strategy, OKR generation, competitive analysis, board decks |\n| 2 | `exec-coo-operations` | COO Operations | Process optimization, cross-department coordination, resource allocation |\n| 3 | `exec-cfo-finance` | CFO Finance | Financial modeling, revenue forecasting, burn rate, unit economics |\n| 4 | `exec-cto-technology` | CTO Technology | Tech stack decisions, architecture reviews, build vs buy, tech debt |\n| 5 | `exec-cmo-marketing` | CMO Marketing | Marketing strategy, brand positioning, channel mix, growth planning |\n| 6 | `exec-cpo-product` | CPO Product | Product vision, roadmap, feature prioritization (RICE/ICE), market fit |\n| 7 | `exec-vp-engineering` | VP Engineering | Engineering velocity, team structure, hiring plans, incident escalation |\n| 8 | `exec-vp-sales` | VP Sales | Sales strategy, pipeline analysis, territory planning, quota setting |\n| 9 | `exec-okr-tracker` | OKR Tracker | Company/team OKR tracking, progress reports, at-risk identification |\n| 10 | `exec-board-reporter` | Board Reporter | Board reports, investor updates, KPI dashboards, milestone tracking |\n| 11 | `exec-competitive-intel` | Competitive Intel | Competitor monitoring, market trends, competitive battle cards |\n| 12 | `exec-decision-logger` | Decision Logger | Strategic decision recording with context, rationale, and outcomes |\n\n### Domain 2: Marketing & Growth (22 Agents)\n\n| # | Agent ID | Name | Description |\n|---|----------|------|-------------|\n| 1 | `mktg-seo-strategist` | SEO Strategist | Keyword research, on-page optimization, technical SEO, content gaps |\n| 2 | `mktg-content-writer` | Content Writer | Blog posts, landing pages, emails, case studies, whitepapers |\n| 3 | `mktg-social-media` | Social Media | Post scheduling, captions, hashtags, engagement analysis |\n| 4 | `mktg-email-marketer` | Email Marketer | Campaigns, subject lines, segmentation, A/B testing, flows |\n| 5 | `mktg-ppc-manager` | PPC Manager | Ad copy, bid strategy, audience targeting, ROAS optimization |\n| 6 | `mktg-analytics` | Marketing Analytics | UTM tracking, attribution, funnel analysis, conversion optimization |\n| 7 | `mktg-landing-page` | Landing Page | High-conversion page design and copy, CTA optimization |\n| 8 | `mktg-brand-voice` | Brand Voice | Brand consistency, tone guidelines, style guide enforcement |\n| 9 | `mktg-pr-outreach` | PR Outreach | Press releases, journalist pitching, media lists, coverage tracking |\n| 10 | `mktg-influencer` | Influencer Agent | Influencer ID, outreach scripts, partnership terms, ROI tracking |\n| 11 | `mktg-video-scripting` | Video Scriptwriter | YouTube scripts, social hooks, demo scripts, webinar outlines |\n| 12 | `mktg-podcast` | Podcast Producer | Episode outlines, show notes, guest research, transcripts |\n| 13 | `mktg-community` | Community Manager | Community engagement, UGC curation, feedback collection |\n| 14 | `mktg-growth-hacker` | Growth Hacker | Viral loops, referral programs, PLG mechanics, activation experiments |\n| 15 | `mktg-ab-tester` | A/B Test Designer | Hypothesis generation, stat significance, result analysis |\n| 16 | `mktg-competitor` | Competitor Monitor | Competitor marketing moves, pricing changes, feature launches |\n| 17 | `mktg-newsletter` | Newsletter Agent | Content curation, subject lines, send time optimization |\n| 18 | `mktg-webinar` | Webinar Planner | Planning, registration copy, follow-up sequences, engagement |\n| 19 | `mktg-affiliate` | Affiliate Manager | Program setup, commissions, partner recruitment, payouts |\n| 20 | `mktg-product-launch` | Product Launch | Launch playbook, announcement copy, drip campaigns, press |\n| 21 | `mktg-persona` | Persona Builder | ICP definition, buyer personas, jobs-to-be-done analysis |\n| 22 | `mktg-retention` | Retention Agent | Churn signals, re-engagement campaigns, NPS follow-up |\n\n### Domain 3: Sales & Revenue (18 Agents)\n\n| # | Agent ID | Name | Description |\n|---|----------|------|-------------|\n| 1 | `sales-lead-qualifier` | Lead Qualifier | Lead scoring, data enrichment, ICP matching, routing |\n| 2 | `sales-outbound-writer` | Outbound Writer | Cold emails, LinkedIn messages, follow-ups, objection handling |\n| 3 | `sales-proposal-gen` | Proposal Generator | Custom proposals, SOWs, pricing tables, ROI calculations |\n| 4 | `sales-crm-updater` | CRM Updater | Deal stage updates, activity logging, pipeline hygiene |\n| 5 | `sales-demo-prepper` | Demo Prepper | Pre-demo research, custom scripts, competitive positioning |\n| 6 | `sales-contract-drafter` | Contract Drafter | MSA and order forms, redline tracking, approval routing |\n| 7 | `sales-forecast` | Forecast Analyst | Pipeline forecasting, deal velocity, revenue prediction |\n| 8 | `sales-win-loss` | Win/Loss Analyst | Post-deal analysis, pattern identification, CI extraction |\n| 9 | `sales-pricing` | Pricing Optimizer | Pricing models, discount impact, WTP estimation, tier optimization |\n| 10 | `sales-territory` | Territory Planner | Territory mapping, account distribution, quota allocation |\n| 11 | `sales-upsell` | Upsell Detector | Expansion opportunities, usage triggers, health signals |\n| 12 | `sales-scheduler` | Meeting Scheduler | Calendar coordination, timezone handling, no-show follow-up |\n| 13 | `sales-objection` | Objection Handler | Objection responses, battle cards, value proposition framing |\n| 14 | `sales-referral` | Referral Agent | Referral program, ask timing, reward fulfillment, tracking |\n| 15 | `sales-partner` | Partner Manager | Deal registration, co-selling, partner enablement content |\n| 16 | `sales-call-analyzer` | Call Analyzer | Transcript analysis, talk ratio, next-step extraction |\n| 17 | `sales-pipeline-cleaner` | Pipeline Cleaner | Stale deal ID, missing data alerts, stage-appropriate actions |\n| 18 | `sales-commission` | Commission Calculator | Commission calculation, plan modeling, quota attainment |\n\n### Domain 4: Customer Success (15 Agents)\n\n| # | Agent ID | Name | Description |\n|---|----------|------|-------------|\n| 1 | `cs-onboarding` | Onboarding Agent | Welcome sequences, setup guides, milestone tracking, TTV |\n| 2 | `cs-ticket-router` | Ticket Router | Auto-categorize, prioritize, route support tickets |\n| 3 | `cs-response-drafter` | Response Drafter | Draft support responses from knowledge base, tone consistency |\n| 4 | `cs-escalation` | Escalation Agent | Escalation signals, senior routing, escalation summaries |\n| 5 | `cs-churn-predictor` | Churn Predictor | Usage analysis, engagement scoring, risk flagging, save offers |\n| 6 | `cs-health-scorer` | Health Scorer | Account health scoring (usage, tickets, NPS, adoption) |\n| 7 | `cs-nps` | NPS Collector | Survey distribution, response collection, follow-up automation |\n| 8 | `cs-knowledge` | Knowledge Builder | FAQ generation, help articles, KB maintenance, search |\n| 9 | `cs-chatbot` | Chatbot Trainer | Support chatbot training, intent refinement, accuracy |\n| 10 | `cs-feedback` | Feedback Analyzer | Categorize feedback, trends, route feature requests |\n| 11 | `cs-renewal` | Renewal Manager | Renewal tracking, pricing prep, contract generation |\n| 12 | `cs-qbr` | QBR Generator | QBR deck generation with usage data and ROI metrics |\n| 13 | `cs-adoption` | Adoption Tracker | Feature adoption, usage depth, enablement gaps |\n| 14 | `cs-sla` | SLA Monitor | SLA compliance, breach alerts, response time monitoring |\n| 15 | `cs-voc` | Voice of Customer | Aggregate feedback across channels into actionable insights |\n\n### Domain 5: Product & UI/UX Design (20 Agents)\n\n| # | Agent ID | Name | Description |\n|---|----------|------|-------------|\n| 1 | `design-ui` | UI Designer | Component design, layout, spacing/typography, visual hierarchy |\n| 2 | `design-ux-research` | UX Researcher | Interview scripts, surveys, usability tests, persona refinement |\n| 3 | `design-wireframe` | Wireframer | Lo-fi wireframes, user flows, information architecture |\n| 4 | `design-prototype` | Prototype Builder | Interactive prototype specs, click-through flows |\n| 5 | `design-system` | Design System | Token management, component library, pattern docs |\n| 6 | `design-a11y` | Accessibility | WCAG 2.1 AA audit, contrast, screen reader, ARIA |\n| 7 | `design-responsive` | Responsive Design | Breakpoints, mobile-first, touch targets, viewport |\n| 8 | `design-color` | Color Palette | Color theory, palette generation, dark/light theming |\n| 9 | `design-typography` | Typography | Font pairing, type scale, readability, web font perf |\n| 10 | `design-icon` | Icon System | Icon library, SVG optimization, consistent metaphors |\n| 11 | `design-animation` | Animation | Micro-interactions, transitions, loading, skeletons |\n| 12 | `design-illustration` | Illustration | Brand illustration style, spot illustrations, empty states |\n| 13 | `design-data-viz` | Data Visualization | Chart selection, dashboard layout, data storytelling |\n| 14 | `design-user-flow` | User Flow | Task flow mapping, happy path, error states, edge cases |\n| 15 | `design-heuristic` | Heuristic Eval | Nielsen heuristics, usability scoring, recommendations |\n| 16 | `design-onboarding` | Onboarding UX | First-run experience, progressive disclosure, tooltips |\n| 17 | `design-form` | Form UX | Form optimization, validation, multi-step, autofill |\n| 18 | `design-search` | Search UX | Search interface, filters, autocomplete, results display |\n| 19 | `design-notification` | Notification UX | Notification design, frequency, channels, preferences |\n| 20 | `design-mobile` | Mobile UX | Native patterns, gestures, thumb-zone, offline states |\n\n### Domain 6: Engineering (25 Agents)\n\n| # | Agent ID | Name | Description |\n|---|----------|------|-------------|\n| 1 | `eng-api-designer` | API Designer | REST/GraphQL design, OpenAPI spec, versioning |\n| 2 | `eng-model-builder` | Model Builder | ORM models, relationships, constraints, indexes |\n| 3 | `eng-schema-builder` | Schema Builder | Pydantic schemas, validation, serialization |\n| 4 | `eng-service-builder` | Service Builder | Business logic, service layer patterns, DI |\n| 5 | `eng-repo-builder` | Repository Builder | Data access, query builders, pagination, filtering |\n| 6 | `eng-migration-gen` | Migration Generator | Schema migrations, safe rollback, zero-downtime |\n| 7 | `eng-middleware` | Middleware Builder | Auth, rate limit, CORS, logging, metrics, headers |\n| 8 | `eng-event-handler` | Event Handler | Event-driven, message bus, async, saga patterns |\n| 9 | `eng-worker-builder` | Worker Builder | Background jobs, retry logic, DLQ, scheduling |\n| 10 | `eng-auth-builder` | Auth Builder | JWT, OAuth2, RBAC, permission guards |\n| 11 | `eng-cache-builder` | Cache Builder | Cache strategies, invalidation, TTL management |\n| 12 | `eng-search-builder` | Search Builder | Full-text, vector (pgvector), hybrid ranking |\n| 13 | `eng-webhook` | Webhook Builder | Dispatch, retry, signature verification, logging |\n| 14 | `eng-email` | Email Builder | Transactional email, templates, queue, tracking |\n| 15 | `eng-file-handler` | File Handler | Upload validation, scanning, storage, signed URLs |\n| 16 | `eng-pagination` | Pagination Agent | Cursor/offset pagination, ordering, optimization |\n| 17 | `eng-rate-limiter` | Rate Limiter | Per-endpoint/user limits, sliding window, token bucket |\n| 18 | `eng-health` | Health Builder | Liveness, readiness, startup probes, dep checks |\n| 19 | `eng-websocket` | WebSocket Builder | Real-time, rooms, broadcast, heartbeat, reconnect |\n| 20 | `eng-graphql` | GraphQL Builder | Schema, resolvers, dataloaders, subscriptions |\n| 21 | `eng-multi-tenant` | Multi-Tenant | RLS, tenant middleware, data isolation |\n| 22 | `eng-error-handler` | Error Handler | Structured errors, exception hierarchy, codes |\n| 23 | `eng-logging` | Logging Agent | JSON logging, correlation IDs, PII redaction |\n| 24 | `eng-config` | Config Manager | Env config, feature flags, dynamic config |\n| 25 | `eng-code-reviewer` | Code Reviewer | PR review, patterns, complexity, security checks |\n\n### Domain 7: Frontend (18 Agents)\n\n| # | Agent ID | Name | Description |\n|---|----------|------|-------------|\n| 1 | `fe-component` | Component Builder | React scaffolding, props typing, composition |\n| 2 | `fe-page` | Page Builder | Next.js pages, SSR/SSG, metadata, routing |\n| 3 | `fe-layout` | Layout Builder | Navigation, sidebar, responsive shell |\n| 4 | `fe-form` | Form Builder | RHF and Zod, multi-step, validation, errors |\n| 5 | `fe-table` | Table Builder | Data tables, sorting, filtering, pagination, export |\n| 6 | `fe-chart` | Chart Builder | Recharts/D3 visualizations, real-time updates |\n| 7 | `fe-auth` | Auth Flow | Login, signup, reset, MFA, session management |\n| 8 | `fe-state` | State Manager | Zustand stores, selectors, middleware |\n| 9 | `fe-api-client` | API Client | TanStack Query hooks, errors, loading, optimistic |\n| 10 | `fe-a11y` | A11y Auditor | axe-core, ARIA, keyboard nav, focus management |\n| 11 | `fe-responsive` | Responsive | Mobile-first, breakpoints, touch, viewports |\n| 12 | `fe-i18n` | i18n Agent | Translations, locale, RTL, date/number format |\n| 13 | `fe-seo` | SEO Agent | Meta tags, structured data, sitemap, Open Graph |\n| 14 | `fe-performance` | Performance | Bundle analysis, code splitting, lazy load, CWV |\n| 15 | `fe-testing` | Frontend Testing | Vitest, Playwright E2E, visual regression |\n| 16 | `fe-animation` | Animation Builder | CSS transitions, Framer Motion, scroll animations |\n| 17 | `fe-error-boundary` | Error Boundary | Error boundaries, fallbacks, reporting, recovery |\n| 18 | `fe-pwa` | PWA Builder | Service worker, offline, push notifications |\n\n### Domain 8: DevOps (28 Agents)\n\n| # | Agent ID | Name | Description |\n|---|----------|------|-------------|\n| 1 | `devops-ci` | CI Orchestrator | GitHub Actions pipeline, caching, stages |\n| 2 | `devops-cd` | CD Deployer | Deployment execution, promotion, health |\n| 3 | `devops-gitops` | GitOps Sync | ArgoCD management, sync policy, drift |\n| 4 | `devops-image-build` | Image Builder | Multi-stage Docker, layer optimization, hardening |\n| 5 | `devops-image-scan` | Image Scanner | Trivy/Grype CVE scanning, base image updates |\n| 6 | `devops-image-sign` | Image Signer | Cosign signing, SBOM generation (Syft) |\n| 7 | `devops-helm` | Helm Manager | Chart creation, values, release lifecycle |\n| 8 | `devops-terraform` | Terraform Ops | Plan, apply, state, modules, drift detection |\n| 9 | `devops-ansible` | Ansible Runner | Playbooks, roles, inventory management |\n| 10 | `devops-k8s` | K8s Manager | Deployments, services, configmaps, secrets |\n| 11 | `devops-scaler` | K8s Scaler | HPA tuning, VPA, cluster autoscaler |\n| 12 | `devops-debugger` | K8s Debugger | Pod diagnostics, log analysis, crash analysis |\n| 13 | `devops-canary` | Canary Manager | Progressive rollout 10/30/60/100 percent |\n| 14 | `devops-rollback` | Rollback Agent | Emergency rollback, version pinning, state restore |\n| 15 | `devops-release` | Release Manager | Semantic versioning, changelog, tags |\n| 16 | `devops-cert` | Cert Manager | TLS lifecycle, auto-renewal, ACME |\n| 17 | `devops-dns` | DNS Manager | DNS records, health checks, failover |\n| 18 | `devops-backup` | Backup Agent | DB backup, object storage backup, retention |\n| 19 | `devops-restore` | Restore Agent | Backup validation, restore, DR testing |\n| 20 | `devops-monitoring` | Monitoring Setup | Prometheus, Grafana, Loki, Tempo deployment |\n| 21 | `devops-alerts` | Alert Builder | Alert rules, routing, escalation, silencing |\n| 22 | `devops-logs` | Log Manager | Promtail/Loki pipeline, retention, format |\n| 23 | `devops-mesh` | Service Mesh | Linkerd deployment, mTLS, traffic policies |\n| 24 | `devops-ingress` | Ingress Manager | Traefik/NGINX, routing, rate limits, headers |\n| 25 | `devops-storage` | Storage Manager | PV/PVC, MinIO, backup storage |\n| 26 | `devops-queue` | Queue Manager | RabbitMQ/NATS, depth monitoring, DLQ |\n| 27 | `devops-cost` | Cost Analyzer | Utilization analysis, rightsizing recommendations |\n| 28 | `devops-capacity` | Capacity Planner | Growth forecasting, resource planning |\n\n### Domain 9: Security (22 Agents)\n\n| # | Agent ID | Name | Description |\n|---|----------|------|-------------|\n| 1 | `sec-sast` | SAST Scanner | Semgrep static analysis, vulnerability finding |\n| 2 | `sec-sca` | SCA Scanner | Trivy dependency scanning, CVE, license |\n| 3 | `sec-dast` | DAST Scanner | OWASP ZAP dynamic testing, API fuzzing |\n| 4 | `sec-secret` | Secret Scanner | TruffleHog detection, pre-commit, prevention |\n| 5 | `sec-container` | Container Scanner | Image CVE scanning, base image audit |\n| 6 | `sec-iac` | IaC Scanner | Checkov Terraform/K8s scanning |\n| 7 | `sec-runtime` | Runtime Monitor | Falco anomaly detection, container escapes |\n| 8 | `sec-policy` | Policy Enforcer | Kyverno admission, OPA/Rego rules |\n| 9 | `sec-incident` | Incident Responder | IR automation, evidence, containment |\n| 10 | `sec-vuln` | Vuln Prioritizer | CVSS, exploitability, risk prioritization |\n| 11 | `sec-patch` | Patch Manager | Security patching, dep updates, rollout |\n| 12 | `sec-access` | Access Reviewer | IAM audit, permission review, least privilege |\n| 13 | `sec-rbac` | RBAC Manager | Role definitions, permissions, grants |\n| 14 | `sec-encryption` | Encryption Agent | At-rest/transit encryption, key rotation |\n| 15 | `sec-audit` | Audit Logger | Immutable audit log, compliance reporting |\n| 16 | `sec-compliance` | Compliance Checker | SOC2, HIPAA, GDPR, PCI, ISO 27001 |\n| 17 | `sec-pentest` | Pentest Runner | Automated pentesting, Nuclei, validation |\n| 18 | `sec-threat` | Threat Hunter | Proactive detection, IOC, SIGMA rules |\n| 19 | `sec-network` | Network Segmenter | NetworkPolicies, micro-segmentation, zero-trust |\n| 20 | `sec-waf` | WAF Manager | WAF rules, DDoS protection, bot detection |\n| 21 | `sec-pii` | PII Detector | PII in logs/data, classification, masking |\n| 22 | `sec-supply-chain` | Supply Chain | SBOM analysis, provenance, Cosign verification |\n\n### Domain 10: Data & Analytics (18 Agents)\n\n| # | Agent ID | Name | Description |\n|---|----------|------|-------------|\n| 1 | `data-schema` | Schema Designer | DB schema, normalization, relationships |\n| 2 | `data-migration` | Migration Builder | Safe DDL, zero-downtime, rollback |\n| 3 | `data-index` | Index Optimizer | Query plans, index recs, bloat detection |\n| 4 | `data-query` | Query Optimizer | Slow queries, N+1, rewriting |\n| 5 | `data-rls` | RLS Manager | Row-level security, tenant isolation |\n| 6 | `data-backup` | Backup Validator | Integrity checks, restore testing |\n| 7 | `data-etl` | ETL Builder | Data pipelines, transformations |\n| 8 | `data-analytics` | Analytics Builder | Business metrics, KPI calculation |\n| 9 | `data-vector` | Vector Manager | pgvector embeddings, similarity search |\n| 10 | `data-warehouse` | Warehouse Builder | Star schema, materialized views |\n| 11 | `data-report` | Report Generator | Automated reports, PDF, scheduling |\n| 12 | `data-dashboard` | Dashboard Builder | Grafana/Metabase dashboards, drill-down |\n| 13 | `data-events` | Event Tracker | Event schema, tracking, funnels |\n| 14 | `data-cohort` | Cohort Analyzer | Retention curves, behavioral segmentation |\n| 15 | `data-ab` | A/B Analyzer | Statistical significance, sample size |\n| 16 | `data-forecast` | Forecast Model | Time series, trends, seasonality |\n| 17 | `data-anomaly` | Anomaly Detector | Metric anomalies, baseline deviation |\n| 18 | `data-privacy` | Privacy Agent | Anonymization, retention, GDPR |\n\n### Domain 11: QA & Testing (22 Agents)\n\n| # | Agent ID | Name | Description |\n|---|----------|------|-------------|\n| 1 | `qa-unit` | Unit Test Writer | Unit tests, assertions, edge cases, mocks |\n| 2 | `qa-integration` | Integration Writer | DB/cache integration, fixtures |\n| 3 | `qa-e2e` | E2E Writer | Playwright/Cypress E2E, user flows |\n| 4 | `qa-api` | API Tester | REST/GraphQL testing, contract validation |\n| 5 | `qa-load` | Load Tester | k6/Locust load tests, breakpoints |\n| 6 | `qa-performance` | Perf Tester | Regression detection, benchmarks |\n| 7 | `qa-security` | Security Tester | Auth bypass, injection, fuzzing |\n| 8 | `qa-a11y` | A11y Tester | WCAG compliance, screen reader |\n| 9 | `qa-visual` | Visual Regression | Screenshot diff, CSS regression |\n| 10 | `qa-coverage` | Coverage Analyzer | Gaps, uncovered branches, dead code |\n| 11 | `qa-mutation` | Mutation Tester | Mutation testing, test quality |\n| 12 | `qa-contract` | Contract Tester | Consumer-driven contracts, Pact |\n| 13 | `qa-chaos` | Chaos Tester | Failure injection, resilience |\n| 14 | `qa-fixture` | Fixture Builder | Test data factories, fake data |\n| 15 | `qa-mock` | Mock Builder | Mock/stub generation, service virtualization |\n| 16 | `qa-regression` | Regression Hunter | Git bisect, regression ID, fix validation |\n| 17 | `qa-flaky` | Flaky Detector | Flaky test ID, root cause, stabilization |\n| 18 | `qa-prioritizer` | Test Prioritizer | Risk-based ordering, impact analysis |\n| 19 | `qa-smoke` | Smoke Tester | Post-deploy smoke, critical paths |\n| 20 | `qa-compat` | Compat Tester | Browser/device compatibility |\n| 21 | `qa-data` | Data Validator | Data integrity, migration validation |\n| 22 | `qa-reporter` | Test Reporter | Results, trends, quality metrics |\n\n### Domain 12: HR & People (12 Agents)\n\n| # | Agent ID | Name | Description |\n|---|----------|------|-------------|\n| 1 | `hr-job-writer` | Job Writer | Role descriptions, requirements, inclusive language |\n| 2 | `hr-resume` | Resume Screener | Parsing, skill matching, scoring |\n| 3 | `hr-interview` | Interview Prepper | Questions, scorecards, competencies |\n| 4 | `hr-offer` | Offer Drafter | Offer letters, comp benchmarking, equity |\n| 5 | `hr-onboarding` | Onboarding Manager | 30-60-90, checklists, buddy assignment |\n| 6 | `hr-performance` | Perf Reviewer | Review templates, goals, feedback |\n| 7 | `hr-engagement` | Engagement Survey | Pulse surveys, sentiment, action plans |\n| 8 | `hr-policy` | Policy Writer | Handbook, PTO, remote work guidelines |\n| 9 | `hr-comp` | Comp Analyst | Salary benchmarking, pay equity, bands |\n| 10 | `hr-org-chart` | Org Chart Builder | Structure, reporting lines, span |\n| 11 | `hr-training` | Training Planner | Learning paths, skill gaps, calendar |\n| 12 | `hr-offboarding` | Offboarding Agent | Exit checklist, knowledge transfer, access revocation |\n\n### Domain 13: Finance & Billing (15 Agents)\n\n| # | Agent ID | Name | Description |\n|---|----------|------|-------------|\n| 1 | `fin-billing` | Billing Agent | Stripe integration, subscription mgmt, invoices |\n| 2 | `fin-payment` | Payment Processor | Payment flow, retry, dunning, refunds |\n| 3 | `fin-subscription` | Subscription Manager | Plan changes, proration, trials, cancellation |\n| 4 | `fin-usage` | Usage Metering | Usage tracking, metered billing, overage |\n| 5 | `fin-invoice` | Invoice Generator | PDF invoices, tax, multi-currency |\n| 6 | `fin-revenue` | Revenue Recognizer | ASC 606, deferred revenue, MRR/ARR |\n| 7 | `fin-expense` | Expense Tracker | Infra costs, vendor payments, budgets |\n| 8 | `fin-tax` | Tax Calculator | Sales tax, VAT, GST by jurisdiction |\n| 9 | `fin-reports` | Financial Reporter | P&L, cash flow, SaaS metrics (LTV, CAC) |\n| 10 | `fin-budget` | Budget Planner | Budgets, variance, forecast vs actual |\n| 11 | `fin-ar` | AR Agent | Outstanding invoices, collections, aging |\n| 12 | `fin-pricing` | Pricing Modeler | Pricing pages, tiers, feature gating |\n| 13 | `fin-fraud` | Fraud Detector | Payment fraud, velocity checks, risk |\n| 14 | `fin-audit` | Audit Preparer | Financial audit prep, documentation |\n| 15 | `fin-runway` | Runway Calculator | Burn rate, runway projection, scenarios |\n\n### Domain 14: Legal & Governance (8 Agents)\n\n| # | Agent ID | Name | Description |\n|---|----------|------|-------------|\n| 1 | `legal-tos` | ToS Writer | Terms, privacy policy, acceptable use, cookies |\n| 2 | `legal-dpa` | DPA Drafter | Data processing agreements, sub-processors |\n| 3 | `legal-contract` | Contract Reviewer | Clause analysis, risk flagging, redlines |\n| 4 | `legal-ip` | IP Protector | License compliance, OSS audit, trademarks |\n| 5 | `legal-gdpr` | GDPR Agent | Data subject requests, consent, retention |\n| 6 | `legal-soc2` | SOC2 Preparer | Control docs, evidence, gap analysis |\n| 7 | `legal-sla` | SLA Drafter | SLA docs, uptime commitments, penalties |\n| 8 | `legal-incident` | Incident Notifier | Breach notifications, regulatory timelines |\n\n### Domain 15: Content & Comms (10 Agents)\n\n| # | Agent ID | Name | Description |\n|---|----------|------|-------------|\n| 1 | `content-tech-writer` | Tech Writer | API docs, guides, tutorials, SDK docs |\n| 2 | `content-blog` | Blog Writer | SEO blogs, thought leadership, industry |\n| 3 | `content-docs` | Docs Builder | MkDocs/Docusaurus site, nav, search |\n| 4 | `content-changelog` | Changelog Writer | User-facing changelogs, release notes |\n| 5 | `content-presentation` | Presentations | Slide decks, pitch decks, training |\n| 6 | `content-internal` | Internal Comms | All-hands updates, newsletters, decisions |\n| 7 | `content-status` | Status Writer | Incident updates, maintenance windows |\n| 8 | `content-editor` | Copy Editor | Grammar, style, brand voice, proofing |\n| 9 | `content-case-study` | Case Study Writer | Customer success stories, ROI metrics |\n| 10 | `content-readme` | README Generator | Repo READMEs, quickstart, badges |\n\n---\n\n## Ruflo — Multi-Agent Swarm Orchestration\n\n[github.com/ruvnet/ruflo](https://github.com/ruvnet/ruflo)\n\n```bash\ncurl -fsSL https://cdn.jsdelivr.net/gh/ruvnet/ruflo@main/scripts/install.sh | bash\nruflo init\n```\n\n### Key Features\n\n- **Mesh topology** — Agents communicate peer-to-peer, no central bottleneck\n- **314 MCP tools** — Pre-built tool integrations for Claude Code\n- **Hive-mind intelligence** — Shared context and memory across all agents\n- **Self-learning neural routing** — Automatic task-to-agent matching\n- **CYCLE_INTERVAL=0** — Zero-latency agent activation\n- **Swarm orchestration** — Coordinate multiple agents on complex tasks\n- **Memory persistence** — Agent learnings persist across sessions\n\n---\n\n## Graphify — Codebase Knowledge Graph\n\n[github.com/safishamsi/graphify](https://github.com/safishamsi/graphify)\n\n```bash\npip install graphifyy\ngraphify install\ngraphify index .\n```\n\n### Key Features\n\n- **Tree-sitter AST parsing** — 20 language support\n- **Knowledge graph** — Queryable code relationships\n- **Symbol resolution** — Cross-file dependency tracking\n- **Impact analysis** — Understand change propagation\n- **Architecture visualization** — Generate dependency diagrams\n- **Semantic search** — Find code by meaning, not just text\n\n---\n\n## LLM Wiki — Brain Memory (Karpathy Pattern)\n\nCitadel's agent fleet uses Andrej Karpathy's [LLM Wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) as persistent brain memory. Instead of re-deriving knowledge from scratch on every session, the LLM maintains a **compiled wiki** that compounds across all 265 agents.\n\n### Three layers\n\n```\ndocs/vault/\n├── raw/        # Layer 1: immutable source documents\n│               #   (articles, papers, transcripts, architecture docs,\n│               #    meeting notes, customer feedback, incidents,\n│               #    Obsidian Web Clipper output)\n│               #   LLM reads, never modifies.\n│\n├── wiki/       # Layer 2: LLM-maintained compiled knowledge\n│   ├── index.md         — content-oriented catalog (first lookup)\n│   ├── log.md           — append-only chronological log\n│   ├── overview.md      — evolving synthesis of everything\n│   ├── entities/        — one page per agent, service, tool, component\n│   ├── concepts/        — cross-cutting topics (multi-tenancy, canary-deploys, ...)\n│   ├── sources/         — one summary per ingested raw source\n│   ├── comparisons/     — analysis pages generated from queries\n│   ├── contradictions/  — flagged conflicts between sources\n│   └── knowledge-graph/ — Graphify AST output, feeds entity/concept pages\n│\n└── SCHEMA.md   # Layer 3: governance, co-evolved between human and LLM\n```\n\n### The three operations\n\n| Operation | Command | What it does |\n|-----------|---------|--------------|\n| **Ingest** | `/project:wiki-ingest raw/<path>` | Read a raw source, write summary page, update 10–15 entity/concept/index/log pages in one pass, flag contradictions |\n| **Query** | `/project:wiki-query <question>` | Consult `wiki/index.md` first, synthesize an answer with wiki citations, file valuable answers back as new pages so explorations compound |\n| **Lint** | `/project:wiki-lint` | Health-check for orphans, stale claims, missing cross-references, concept gaps, and data gaps; suggest new questions and sources |\n\n### Integration points\n\n- **Obsidian graph view** — open `docs/vault/` as a vault; the graph is color-coded by layer (raw=gray, wiki=blue, SCHEMA=gold) and by agent domain. Dataview plugin enabled for querying YAML frontmatter across wiki pages.\n- **Graphify feeds the wiki** — `graphify . --obsidian-dir docs/vault/wiki/knowledge-graph` produces backlinked wiki pages from AST-parsed code structure. The `wiki-curator` agent cross-links these into the entity and concept pages.\n- **Agent sessions file back** — every valuable output from any of the 265 agents can be folded into the wiki via `/project:wiki-ingest`, so knowledge compounds across the whole fleet instead of dying with the chat session.\n- **PreToolUse hook** — the harness reminds Claude to consult `wiki/index.md` before grepping raw files, same pattern as the Graphify knowledge-graph hook.\n- **`wiki-curator` subagent** — owns the wiki layer entirely. Can touch 15 files in one pass without getting bored.\n\n### Make targets\n\n| Target | Purpose |\n|--------|---------|\n| `make wiki-ingest FILE=raw/<path>` | Ingest a raw source into the wiki |\n| `make wiki-lint` | Run a health check on the wiki |\n| `make wiki-sync` | Refresh Graphify output + run wiki lint |\n\nSee [`.claude/skills/llm-wiki/SKILL.md`](.claude/skills/llm-wiki/SKILL.md), [`.claude/rules/llm-wiki.md`](.claude/rules/llm-wiki.md), [`.claude/agents/wiki-curator.md`](.claude/agents/wiki-curator.md), and [`docs/vault/SCHEMA.md`](docs/vault/SCHEMA.md) for details.\n\n---\n\n## Obsidian Vault Integration\n\nEvery file in this repository is cross-referenced through Obsidian `[[wikilinks]]`. The vault at `docs/vault/` is a complete, navigable knowledge graph of the entire 265-agent architecture.\n\n### What lives in the vault\n\n```\ndocs/vault/\n├── _index.md                — vault home / Map of Content\n├── SCHEMA.md                — LLM Wiki governance (co-evolved)\n├── .obsidian/               — Obsidian config (graph view, Dataview, templates)\n├── raw/                     — immutable source documents (LLM Wiki layer 1)\n├── wiki/                    — LLM-maintained compiled knowledge (LLM Wiki layer 2)\n├── agents/                  — one note per agent (265 total) + per-domain indexes\n├── architecture/            — ADR notes, tech stack, system component notes\n├── runbooks/                — operational runbooks linked to agents/services\n├── memory/                  — mirrors of .claude/memory/ (project context, decisions, learnings…)\n└── knowledge-graph/         — Graphify-generated entity, god-node, community, surprising-connection notes\n```\n\n### Open the vault in Obsidian\n\n1. Install [Obsidian](https://obsidian.md/).\n2. Open `docs/vault/` as a vault.\n3. Press `Ctrl/Cmd+G` to launch the graph view — every agent, ADR, runbook, and service appears as a node, color-coded by domain.\n4. Click any node and use the **Backlinks pane** to navigate to everything that references it.\n\n### Automatic backlinking\n\n- **Rule** — [`.claude/rules/obsidian-backlinks.md`](.claude/rules/obsidian-backlinks.md) requires every new `.md` file in the repo to include a `## Vault Links` section.\n- **Skill** — [`.claude/skills/obsidian-linker/SKILL.md`](.claude/skills/obsidian-linker/SKILL.md) scans new files, finds related vault notes by keyword and domain, and inserts bidirectional `[[wikilinks]]`.\n- **Slash command** — `/project:vault-link <file>` regenerates backlinks for any file on demand.\n- **Curator agent** — [`.claude/agents/obsidian-curator.md`](.claude/agents/obsidian-curator.md) audits the vault for orphan notes, broken wikilinks, and missing frontmatter.\n- **PostToolUse hook** — Every write to `docs/vault/*.md` triggers `scripts/vault-autolink.py`, which auto-inserts backlinks into the file's `<!-- linked-notes -->` block.\n\n### Graphify produces backlinked notes\n\n`scripts/bootstrap.sh` runs `graphify . --obsidian-dir docs/vault/knowledge-graph` during setup, so the entire codebase knowledge graph is immediately available as backlinked Obsidian notes — every entity, god node, community cluster, and surprising connection becomes a vault note linked into the rest of the graph.\n\n### Make targets\n\n| Target | Purpose |\n|--------|---------|\n| `make vault-generate` | Regenerate the 265 agent notes from `.claude/agents/_registry.yaml` |\n| `make vault-sync` | Refresh Graphify knowledge graph + memory mirrors |\n| `make vault-audit` | Invoke the obsidian-curator agent to check vault integrity |\n\n---\n\n## MCP Servers\n\n| Server | Purpose | Capabilities |\n|--------|---------|-------------|\n| `github` | GitHub integration | Repos, PRs, issues, Actions, GHCR |\n| `filesystem` | Local file access | Read, write, search, watch files |\n| `postgres` | Database access | Query, schema inspection, migrations |\n| `docker` | Container management | Build, run, inspect, logs |\n| `kubernetes` | Cluster management | Deployments, pods, services, logs |\n| `ruflo` | Swarm orchestration | Agent spawning, memory, routing |\n\n---\n\n## Free Toolchain\n\nTotal monthly software cost: **$0**\n\n| Name | License | Replaces |\n|------|---------|----------|\n| ArgoCD | Apache-2.0 | Spinnaker, Harness ($$$) |\n| K3s | Apache-2.0 | EKS, GKE, AKS ($75-300/mo) |\n| Traefik | MIT | AWS ALB, Cloudflare ($20+/mo) |\n| Linkerd | Apache-2.0 | Istio, AWS App Mesh |\n| Keycloak | Apache-2.0 | Auth0 ($23-240/mo), Okta ($2/user) |\n| HashiCorp Vault | BUSL-1.1 | AWS Secrets Manager ($0.40/secret) |\n| Prometheus | Apache-2.0 | Datadog ($15/host/mo) |\n| Grafana | AGPL-3.0 | Datadog dashboards ($15/host/mo) |\n| Loki | AGPL-3.0 | Splunk ($150+/GB), Datadog Logs |\n| Tempo | AGPL-3.0 | Jaeger SaaS, Datadog APM |\n| Falco | Apache-2.0 | Sysdig ($$$), Aqua Security |\n| Kyverno | Apache-2.0 | OPA Gatekeeper, Styra DAS |\n| Semgrep | LGPL-2.1 | SonarQube ($150+/mo), Snyk Code |\n| Trivy | Apache-2.0 | Snyk Container ($25+/mo) |\n| OWASP ZAP | Apache-2.0 | Burp Suite Pro ($449/yr) |\n| Flagsmith | BSD-3 | LaunchDarkly ($10/seat/mo) |\n| Grafana OnCall | AGPL-3.0 | PagerDuty ($21/user/mo) |\n| Velero | Apache-2.0 | Kasten K10, Portworx Backup |\n| MinIO | AGPL-3.0 | AWS S3 ($0.023/GB/mo) |\n| Ansible | GPL-3.0 | Puppet, Chef, SaltStack |\n| Certbot | Apache-2.0 | Commercial TLS certs ($100+/yr) |\n| TruffleHog | AGPL-3.0 | GitGuardian ($30/dev/mo) |\n\n---\n\n## Docker Compose — Local Development\n\n```bash\ndocker compose up -d\n```\n\n| Service | Port | Description |\n|---------|------|-------------|\n| PostgreSQL 16 | 5432 | Primary database |\n| Redis 7 | 6379 | Cache and session store |\n| Keycloak 24 | 8080 | Auth server (admin console) |\n| MinIO | 9000 / 9001 | Object storage / console |\n| RabbitMQ | 5672 / 15672 | Message broker / management |\n| Mailpit | 1025 / 8025 | Local email capture / web UI |\n| Traefik | 80 / 443 / 8082 | Proxy / TLS / dashboard |\n\n---\n\n## Token Setup\n\n### Required\n\n| Token | Source | Purpose |\n|-------|--------|---------|\n| `ANTHROPIC_API_KEY` | [console.anthropic.com](https://console.anthropic.com) | Powers Claude Code, Ruflo, and Graphify |\n| `GITHUB_TOKEN` | [github.com/settings/tokens](https://github.com/settings/tokens) | GitHub CLI, GHCR, Actions, MCP server |\n\n### Optional\n\n| Token | Source | Purpose |\n|-------|--------|---------|\n| `STRIPE_SECRET_KEY` | [dashboard.stripe.com](https://dashboard.stripe.com) | Payment processing (billing agents) |\n| `SENDGRID_API_KEY` | [sendgrid.com](https://sendgrid.com) | Transactional email delivery |\n| `SENTRY_DSN` | [sentry.io](https://sentry.io) | Error tracking and monitoring |\n| `SLACK_WEBHOOK_URL` | [api.slack.com](https://api.slack.com) | Deployment and alert notifications |\n\n```bash\ncp .env.example .env\n# Edit .env with your tokens\n```\n\n---\n\n## Hallucination Prevention\n\nEvery LLM call in Citadel SaaS Factory routes through a **Guardrails AI** validation layer. No agent output reaches users or downstream agents without passing through guardrails. Paired with **confident-ai/deepeval** for hallucination rate evaluation and **NVIDIA NeMo-Guardrails** for conversational and agent-level guardrails.\n\n### Quick Install\n\n```bash\n./scripts/setup-guardrails.sh\n```\n\nThis installs `guardrails-ai` and `deepeval`, configures the guardrails CLI, and installs the core Hub validators (`hallucination_free`, `provenance_llm`, `toxic_language`, `detect_pii`).\n\n### Validation Flow\n\n```\nAgent Output\n    ↓\nGuardrails Validator\n    ↓\nSchema Check (structured output enforcement)\n    ↓\nHallucination Score (threshold 0.85)\n    ↓\nFactuality Check (against source data / RAG context)\n    ↓\nProvenance Verification (RAG grounding validators)\n    ↓\n[PASS] → Validated Output\n[FAIL] → Retry with grounding (max 3) → Reject if still failing\n```\n\n### Problem → Solution Matrix\n\n| Problem | Solution |\n|---------|----------|\n| Model makes things up | Validates against rules and source data |\n| No grounding | RAG provenance validators |\n| Inconsistent answers | Schema enforcement with deterministic outputs |\n| Unsafe agent behavior | Pre/post execution guardrails |\n\n### Minimal Usage Example\n\n```python\nfrom guardrails import Guard\nfrom guardrails.hub import HallucinationFree, ProvenanceLLM\n\nguard = Guard.from_rail_string(\"\"\"\n<rail version=\"0.1\">\n<output>\n  <string name=\"answer\" description=\"Factual answer grounded in sources\" />\n</output>\n<prompt>\n  Answer the question using ONLY the provided sources.\n  Question: ${question}\n  Sources: ${sources}\n</prompt>\n</rail>\n\"\"\").use_many(\n    HallucinationFree(on_fail=\"reask\"),\n    ProvenanceLLM(validation_method=\"sentence\", on_fail=\"reask\"),\n)\n\nvalidated = guard(\n    llm_api=openai.chat.completions.create,\n    prompt_params={\"question\": query, \"sources\": rag_docs},\n)\n# validated.validation_passed → True/False\n# validated.validated_output → structured, hallucination-free answer\n```\n\nIn the backend, all LLM calls go through `backend/app/middleware/guardrails.py`:\n\n```python\nfrom app.middleware.guardrails import guard_llm_call\n\nanswer = await guard_llm_call(\n    llm.complete,\n    prompt=user_query,\n    source_context=rag_docs,\n    schema={\"type\": \"object\", \"properties\": {\"answer\": {\"type\": \"string\"}}},\n)\n```\n\n### Integrated Stack\n\n| Tool | Purpose |\n|------|---------|\n| **guardrails-ai** | Structured output, hallucination detection, schema enforcement |\n| **deepeval** | Hallucination rate evaluation, LLM test suite, CI/CD integration |\n| **NVIDIA NeMo-Guardrails** | Conversational and agent-level guardrails |\n\n### Configuration\n\n- **Hub validators**: see `security/guardrails/validators.yaml`\n- **Backend middleware**: `backend/app/middleware/guardrails.py`\n- **Validator subagent**: `.claude/agents/guardrails-validator.md`\n- **Skill**: `.claude/skills/guardrails/SKILL.md`\n- **Rules**: `.claude/rules/guardrails.md`\n\n---\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feat/your-feature`\n3. Write tests first (TDD mandatory)\n4. Ensure 80%+ code coverage\n5. Run security scan: `make security`\n6. Run linter: `make lint`\n7. Commit with conventional format: `feat: add user auth`\n8. Open a pull request\n9. Wait for CI to pass (lint, test, security scan)\n10. Get 1 approval minimum before merge\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n---\n\n## License\n\nMIT License. See [LICENSE](LICENSE) for full terms.\n\nCopyright (c) Citadel Cloud Management\n\n---\n\nCitadel Cloud Management | [citadelcloudmanagement.com](https://citadelcloudmanagement.com)\n","readmeFilename":"README.md","_rev":"1-15670bb411bbbd3a95969f7b1b4f3243"}