claude-plugins/negocio/skills/saas/SKILL.md

name, description, author, version, quality_score, user_invocable, desk_task, allowed-tools

name	description	author	version	quality_score	user_invocable	desk_task	allowed-tools
saas	Skill especializada em arquitectura e desenvolvimento de produtos SaaS (Software as a Service), cobrindo multi-tenancy, billing, onboarding e métricas.	Descomplicar® Crescimento Digital	2.0.0	55	true	null	Task

Skill /saas - SaaS Architecture & Strategy

Skill especializada em arquitectura e desenvolvimento de produtos SaaS (Software as a Service), cobrindo multi-tenancy, billing, onboarding e métricas.

Sintaxe

/saas [operacao] [contexto]

Operações:

• arquitectura - Design multi-tenant, isolamento dados, escalabilidade
• pricing - Modelos de preços e packaging de features
• onboarding - Flow de activação e time-to-value
• billing - Integração Stripe, trial, upgrades/downgrades
• metricas - Dashboard MRR, churn, LTV, CAC

Quando Usar

• Planear novo produto SaaS
• Migrar aplicação tradicional para SaaS
• Optimizar onboarding ou reduzir churn
• Implementar billing e subscriptions
• Arquitectura multi-tenant

---

Protocolo de Execução

1. Discovery de Produto

Questões chave:

Modelo de negócio:
- [ ] B2B, B2C ou B2B2C?
- [ ] Self-service ou sales-led?
- [ ] PLG (product-led growth)?

Utilizadores:
- [ ] Quantos users por tenant?
- [ ] Diferentes roles/permissões?
- [ ] Colaboração entre users?

Dados:
- [ ] Volume de dados por tenant?
- [ ] Regulamentações (GDPR, HIPAA)?
- [ ] Backup e disaster recovery?

Integrações:
- [ ] APIs third-party necessárias?
- [ ] SSO/SAML enterprise?
- [ ] Webhooks para partners?

2. Arquitectura Multi-tenant

Estratégias de Isolamento:

┌─────────────────────────────────────────────────┐
│ 1. DATABASE PER TENANT (Isolamento Máximo)     │
├─────────────────────────────────────────────────┤
│ Prós: Segurança total, restore independente     │
│ Contras: Custo, complexidade gestão             │
│ Usar quando: Enterprise, regulamentações        │
│ Exemplo: AWS RDS + Aurora Serverless            │
└─────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────┐
│ 2. SCHEMA PER TENANT (Equilíbrio)              │
├─────────────────────────────────────────────────┤
│ Prós: Bom isolamento, gestão simplificada       │
│ Contras: Limites BD (PostgreSQL ~10k schemas)   │
│ Usar quando: B2B médio porte                    │
│ Exemplo: PostgreSQL schemas dinâmicos           │
└─────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────┐
│ 3. SHARED DB + ROW-LEVEL SECURITY (Económico)  │
├─────────────────────────────────────────────────┤
│ Prós: Mais barato, fácil escalar                │
│ Contras: tenant_id em tudo, RLS obrigatório     │
│ Usar quando: B2C, SMB self-service              │
│ Exemplo: PostgreSQL RLS policies                │
└─────────────────────────────────────────────────┘

Implementação Row-Level Security (PostgreSQL):

-- 1. Adicionar tenant_id a todas as tabelas
ALTER TABLE users ADD COLUMN tenant_id UUID NOT NULL;
ALTER TABLE projects ADD COLUMN tenant_id UUID NOT NULL;
ALTER TABLE documents ADD COLUMN tenant_id UUID NOT NULL;

-- 2. Activar RLS
ALTER TABLE users ENABLE ROW LEVEL SECURITY;
ALTER TABLE projects ENABLE ROW LEVEL SECURITY;
ALTER TABLE documents ENABLE ROW LEVEL SECURITY;

-- 3. Criar policy de isolamento
CREATE POLICY tenant_isolation ON users
    USING (tenant_id = current_setting('app.tenant_id')::uuid);

CREATE POLICY tenant_isolation ON projects
    USING (tenant_id = current_setting('app.tenant_id')::uuid);

-- 4. No início de cada request (backend)
-- SET app.tenant_id = 'uuid-do-tenant-autenticado';

Checklist Segurança Multi-tenant:

[ ] tenant_id em TODAS as tabelas
[ ] RLS policies activas
[ ] Indexes em tenant_id (performance)
[ ] Validação tenant_id no auth middleware
[ ] Logs de acesso cross-tenant
[ ] Testes de isolamento (tenant A não vê tenant B)

3. Modelos de Pricing

Modelo	Descrição	Exemplo	Quando Usar
Flat Rate	Preço fixo mensal	29€/mês	Simplicidade, previsibilidade
Per Seat	Por utilizador	10€/user/mês	B2B, equipas
Usage Based	Pay-as-you-go	0.01€/API call	Variação alta de uso
Tiered	Planos com limites	Free/Pro/Enterprise	Upsell natural
Hybrid	Base + usage	20€ + 0.001€/email	Receita previsível + escala

Recomendação Descomplicar:

B2B (equipas 5-50 users): PER SEAT
B2C (individual): TIERED
API/Infra (desenvolvedores): USAGE BASED
SaaS tradicional: HYBRID (base + usage caps)

Exemplo de Tiers:

┌─────────────────────────────────────────────────┐
│ FREE                                    0€/mês  │
├─────────────────────────────────────────────────┤
│ ✓ 1 user                                        │
│ ✓ 100 records/mês                               │
│ ✓ 1 GB storage                                  │
│ ✗ Integrações                                   │
│ ✗ API access                                    │
│ ✗ Suporte prioritário                           │
└─────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────┐
│ PRO                                    29€/mês  │
├─────────────────────────────────────────────────┤
│ ✓ 5 users                                       │
│ ✓ 10.000 records/mês                            │
│ ✓ 50 GB storage                                 │
│ ✓ Integrações básicas                           │
│ ✓ API access (10k calls/mês)                    │
│ ✓ Email support (24h)                           │
└─────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────┐
│ ENTERPRISE                           Custom     │
├─────────────────────────────────────────────────┤
│ ✓ Users ilimitados                              │
│ ✓ Records ilimitados                            │
│ ✓ Storage dedicado                              │
│ ✓ Todas as integrações                          │
│ ✓ API ilimitado                                 │
│ ✓ Suporte 24/7 + Account Manager                │
│ ✓ SSO/SAML                                      │
│ ✓ SLA 99.9%                                     │
└─────────────────────────────────────────────────┘

4. Stack Técnica Recomendada

Frontend:

Framework: Next.js 14+ (App Router)
Styling: Tailwind CSS + shadcn/ui
State: Zustand / Jotai
Forms: React Hook Form + Zod

Backend:

API: Next.js API Routes / tRPC
Database: PostgreSQL (Supabase / Railway)
ORM: Prisma
Queue: BullMQ / Inngest (background jobs)
Cache: Redis (Upstash)

Auth & Billing:

Auth: Clerk / Auth0 / NextAuth.js
Billing: Stripe Billing (subscriptions)
Email: Resend / SendGrid
Analytics: PostHog / Mixpanel

Hosting:

Frontend: Vercel
Backend: Railway / Fly.io
Database: Supabase / Neon
CDN: Cloudflare

5. Onboarding Flow (Time-to-Value)

Objectivo: Levar user de signup a "aha moment" em < 5 minutos.

┌────────────────────────────────────────────────┐
│ 1. SIGNUP                                      │
│    Email + Password (ou OAuth Google)          │
│    ↓ < 30 segundos                              │
├────────────────────────────────────────────────┤
│ 2. WELCOME                                     │
│    Vídeo 30s: "O que vais conseguir"           │
│    ↓ Skip disponível                            │
├────────────────────────────────────────────────┤
│ 3. QUICK SETUP                                 │
│    3-5 campos essenciais (restantes opcional)   │
│    Progress bar: "2/3 completo"                 │
│    ↓ < 2 minutos                                │
├────────────────────────────────────────────────┤
│ 4. FIRST ACTION                                │
│    Criar primeiro [projecto/documento/etc]      │
│    Usar template pré-preenchido                 │
│    ↓ < 2 minutos                                │
├────────────────────────────────────────────────┤
│ 5. AHA MOMENT                                  │
│    Ver resultado imediato (export, share, etc)  │
│    Celebrar: "Parabéns! Criaste o teu 1º X"    │
│    ↓                                            │
├────────────────────────────────────────────────┤
│ 6. NEXT STEPS                                  │
│    Checklist guiada: "3 passos para dominar"   │
│    Invite team, integração, etc                 │
└────────────────────────────────────────────────┘

Métricas de Onboarding:

- Signup → Email verified: > 80%
- Email verified → Setup complete: > 60%
- Setup → First action: > 70%
- First action → Aha moment: > 90%
- Activation rate (signup → aha): > 40%

6. Billing com Stripe

Setup Básico:

// 1. Criar produtos e preços no Stripe Dashboard
// Free: price_free (0€)
// Pro: price_pro (29€/mês)
// Enterprise: price_enterprise (custom)

// 2. Criar subscription no signup
import Stripe from 'stripe';
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);

const subscription = await stripe.subscriptions.create({
  customer: customerId,
  items: [{ price: 'price_free' }],
  trial_period_days: 14, // Trial 14 dias
  payment_behavior: 'default_incomplete',
  expand: ['latest_invoice.payment_intent']
});

// 3. Webhooks para sincronizar estado
// - customer.subscription.created
// - customer.subscription.updated
// - customer.subscription.deleted
// - invoice.payment_succeeded
// - invoice.payment_failed

// 4. Verificar feature access
const canUseFeature = (user: User, feature: string) => {
  if (user.subscription.status !== 'active') return false;
  return PLAN_FEATURES[user.subscription.plan].includes(feature);
};

Trial → Paid Conversion:

Trial 14 dias (sem cartão)
  │
  ├─ Dia 7: Email "Metade do trial"
  ├─ Dia 12: Email "2 dias restantes + valor criado"
  ├─ Dia 14: Soft paywall (pedir cartão)
  │
  ▼
Converteu? → Pro (29€/mês)
Não converteu? → Free (downgrade features)

---

Métricas SaaS (KPIs)

Receita

Métrica	Fórmula	Target
MRR	Monthly Recurring Revenue	Crescimento mês/mês
ARR	MRR × 12	> 100k€ para sustainable
ARPU	MRR / Total customers	Sector-dependent
NRR	(MRR início + expansion - churn - contraction) / MRR início	> 100%

Crescimento

Métrica	Fórmula	Target
New MRR	Novos clientes × preço médio	+20%/mês (early)
Expansion MRR	Upsells + Add-ons	> 10% do MRR
Churn MRR	Cancelamentos valor	< 5%/mês

Aquisição

Métrica	Fórmula	Target
CAC	Custo marketing+sales / Novos clientes	< 1/3 LTV
LTV	ARPU × (1 / Churn Rate) - CAC	> 3× CAC
Payback Period	CAC / ARPU	< 12 meses

Produto

Métrica	Target
Activation Rate	> 40% (signup → aha moment)
DAU/MAU	> 20% (stickiness)
Time to Value	< 10 minutos
Feature Adoption	> 30% users usam feature nova (30 dias)

Retenção

Métrica	Fórmula	Target
Logo Churn	Clientes cancelaram / Total	< 5%/mês
Revenue Churn	MRR perdido / MRR total	< 5%/mês
Cohort Retention	Clientes mês X activos em X+6	> 50%

---

Feature Flags por Plano

// config/features.ts
export const PLAN_FEATURES = {
  free: [
    'basic_dashboard',
    'limited_records',
    'email_support'
  ],
  pro: [
    'basic_dashboard',
    'unlimited_records',
    'api_access',
    'integrations_basic',
    'priority_support',
    'export_csv'
  ],
  enterprise: [
    '*', // todas as features
    'sso_saml',
    'audit_logs',
    'custom_domain',
    'dedicated_support',
    'sla_guarantee'
  ]
};

// middleware verificação
export function requireFeature(feature: string) {
  return async (req, res, next) => {
    const user = req.user;
    const plan = user.subscription.plan;

    if (!PLAN_FEATURES[plan].includes(feature) &&
        !PLAN_FEATURES[plan].includes('*')) {
      return res.status(403).json({
        error: 'Upgrade required',
        feature: feature,
        current_plan: plan,
        upgrade_to: 'pro'
      });
    }

    next();
  };
}

// Uso no route
app.get('/api/export',
  requireAuth,
  requireFeature('export_csv'),
  async (req, res) => {
    // ...
  }
);

---

Consultar Datasets Dify

SEMPRE antes de arquitectar solução:

Dataset	ID	Query Exemplo
Estratégia	7d1d1d21-bc05-43d8-ab8f-6b7b90dafc28	"saas pricing modelo subscription"
Gestão	22799925-8dc5-4a1f-92b9-233468a5048b	"metricas saas mrr churn ltv"
Desenvolvimento Software	52c29c6b-7f76-42fe-ad4b-0bf8ff05cc73	"arquitectura multitenancy postgresql"

Como Consultar

// Modelos de pricing
mcp__notebooklm__notebook_query, mcp__dify-kb__dify_kb_retrieve_segments({
  dataset_id: "7d1d1d21-bc05-43d8-ab8f-6b7b90dafc28",
  query: "saas pricing tiers feature packaging",
  retrieval_mode: "hybrid_search",
  top_k: 5
});

// Métricas e KPIs
mcp__dify-kb__dify_kb_retrieve_segments({
  dataset_id: "22799925-8dc5-4a1f-92b9-233468a5048b",
  query: "metricas saas cohort retention churn",
  retrieval_mode: "hybrid_search",
  top_k: 5
});

---

MCPs Utilizados

mcp__desk-crm-v3__*                  # Gestão projectos SaaS
mcp__dify-kb__dify_kb_retrieve_segments  # Conhecimento estratégico

---

Exemplos de Uso

1. Planeamento Novo SaaS

/saas arquitectura
→ Discovery interactivo
→ Consulta Dify KB (best practices)
→ Recomendação multi-tenancy
→ Stack técnica
→ Roadmap MVP

2. Optimização Pricing

/saas pricing
→ Análise competidores
→ Modelação LTV/CAC
→ Proposta tiers
→ Feature packaging

3. Dashboard Métricas

/saas metricas
→ Definir KPIs prioritários
→ Queries SQL para MRR/Churn
→ Setup PostHog/Mixpanel
→ Dashboards Grafana

---

Agentes Recomendados

// Arquitectura técnica
Task({
  subagent_type: "software-architect",
  model: "sonnet",
  prompt: "Design multi-tenant SaaS architecture. PostgreSQL RLS + Next.js."
});

// Estratégia produto
Task({
  subagent_type: "software-project-planner",
  model: "sonnet",
  prompt: "SaaS onboarding flow. Time-to-value < 5min. B2B productivity tool."
});

---

Instrumentação Automática

Query para Gravar (executar no final)

INSERT INTO tblskill_agent_metrics (
  type, name, duration_ms, status, staff_id,
  kb_consulted, kb_cache_hit, tool_calls, project_id
) VALUES (
  'skill', '/saas', {DURACAO_MS}, '{STATUS}', 25,
  {KB_CONSULTADO}, {CACHE_HIT}, {TOOL_CALLS}, {PROJECT_ID}
);

---

Versão: 2.0.0 | Data: 2026-02-03 | Autor: Descomplicar® Instrumentação: Activa