Gcp Fullstack

Planning Protocol (MANDATORY — execute before ANY action)

Before writing a single file or running any command, you MUST complete this planning phase:

1. Understand the request. Restate what the user wants in your own words. Identify any ambiguities. If the request is vague (e.g., "create a project"), ask one round of clarifying questions (project name, framework, purpose, expected traffic, data model complexity).

2. Survey the environment. Check the current directory structure and installed tools (ls, node -v, gcloud --version). Verify the target directory is empty or does not exist yet. Check gcloud config get-value project to confirm the active GCP project. Do NOT read, open, or inspect any .env, .env.local, or credential files.

3. Choose the right GCP services. Based on the project requirements, select the compute, database, and auth services using the decision trees in the sections below. Document your reasoning.

4. Build an execution plan. Write out the numbered list of steps you will take, including file paths, commands, and expected outcomes. Present this plan to yourself (in your reasoning) before executing.

5. Identify risks. Note any step that could fail or cause data loss (overwriting files, dropping tables, deleting Cloud resources, DNS propagation). For each risk, define the mitigation (backup, dry-run, confirmation).

6. Execute sequentially. Follow the plan step by step. After each step, verify it succeeded before moving to the next. If a step fails, diagnose the issue, update the plan, and continue.

7. Summarize. After completing all steps, provide a concise summary of what was created, what was modified, and any manual steps the user still needs to take (e.g., enabling APIs in Console, configuring OAuth consent screen).

Do NOT skip this protocol. Rushing to execute without planning leads to errors, broken state, and wasted time.

Migration Guide: v1.x → v2.0.0

Version 2.0.0 is a major rewrite that consolidates the GCP development lifecycle into a single skill. If you are upgrading from v1.x, note the following breaking changes:

Breaking Changes

1. Consolidated skill: v1.x was a collection of separate skills (scaffold, deploy, database). v2.0.0 merges everything into one skill with workflow stages. You no longer need to install multiple GCP skills.
2. New Planning Protocol: The mandatory planning phase is new in v2.0. The agent will now survey the environment and build an execution plan before any action.
3. QA Gate separation: Pre-production validation has been extracted into a dedicated qa-gate-gcp skill. In v1.x, basic validation was inline.
4. Environment variables: OPENROUTER_API_KEY is now optional (only for LLM-based QA evaluation). The core skill functions without it.
5. Docker requirement: v2.0.0 requires Docker for Cloud Run container builds. v1.x supported Cloud Functions without Docker.

How to Upgrade

1. Remove any v1.x GCP-related skills from your workspace.
2. Install gcp-fullstack v2.0.0 and qa-gate-gcp v1.0.0.
3. Ensure Docker is installed and running (docker info).
4. Review your environment variables against the updated claw.json requirements.
5. Existing projects created with v1.x are fully compatible — no code changes needed in your app.

Skill Modules

This skill is modularized into focused sub-documents. Each module contains decision trees, code templates, command references, and safety checks for a specific phase of the development lifecycle.

Module 1: Project Scaffolding

Framework detection and project initialization. Covers framework selection (Next.js, Nuxt, SvelteKit, Remix, Astro), dependency installation, directory structure setup, and .env.example generation. Read this when starting a new GCP project.

Module 2: Compute Service Selection

Decision tree for selecting the right compute service (Cloud Run, Cloud Functions, App Engine, Cloud Storage + CDN). Detailed deployment instructions for each service, including Dockerfile examples, environment configuration, health checks, and revision management. Read this before deploying any backend code.

Module 3: Database Setup

Database decision tree and configuration for Firestore and Cloud SQL (PostgreSQL). Includes initialization, client helpers, security rules, indexing, Prisma schema examples, and connection strings. Read this when setting up data persistence.

Module 4: Authentication

Firebase Auth and Identity Platform setup. Covers basic consumer auth (email/password, social logins), enterprise SSO, multi-tenancy, and tenant-aware token verification. Read this when implementing user authentication.

Module 5: Feature Generation

Complete workflow for building vertical slices autonomously. Covers schema-first design, data access layers, API routes, Server Actions, UI components, toast notifications, and comprehensive testing. Read this when implementing new features.

Module 6: Testing & Quality

Unit, integration, and E2E testing patterns. Framework detection, test organization, mocking strategies, failure analysis, linting, type checking, and quality gates. Read this when writing or running tests.

Module 7: Deployment & Monitoring

Pre-deploy checklist, Cloud Run deployment flow, GitHub integration, CI/CD with Cloud Build, Cloud Storage for assets, Secret Manager, monitoring, and logging. Read this when deploying to production or setting up monitoring.

Module 8: Cloudflare DNS, CDN & Security

Cloudflare API integration for DNS, CDN, SSL/TLS, rate limiting, cache purging, and bot protection. Includes standard setup checklist for new projects. Read this when configuring DNS and security infrastructure.

Part 1: Service Selection Guide

The agent MUST use these decision trees to pick the right services. Always document the reasoning.

Compute Decision Tree

When in doubt, default to Cloud Run — it is the most versatile.

Database Decision Tree

For most web apps, Firestore or Cloud SQL (PostgreSQL) covers 90% of use cases.

Auth Decision Tree

Firebase Auth and Identity Platform share the same API surface. Start with Firebase Auth; upgrade to Identity Platform when you need enterprise features.

Module Loading

When executing any workflow stage, the agent MUST read the relevant sub-document from the docs/ directory before proceeding. For example:

• Scaffolding a new project → read docs/01-scaffolding.md
• Choosing compute services → read docs/02-compute.md
• Setting up a database → read docs/03-database.md
• Implementing authentication → read docs/04-auth.md
• Building a feature → read docs/05-features.md
• Writing tests → read docs/06-testing.md
• Deploying to production → read docs/07-deploy.md
• Configuring Cloudflare → read docs/08-cloudflare.md

Never skip reading the module documentation. Each module contains critical decision trees, code templates, and safety checks.

Part 16: Pre-Production QA Gate

Before deploying to production, execute a comprehensive validation sweep. This replaces the need for a separate qa-gate skill. The agent generates a test plan, runs all validations, and produces a go/no-go report.

QA Workflow

1. Generate test plan          → qa-reports/test-plan.json
2. Run existing test suite     → npx vitest run + npx playwright test
3. Generate validation tests   → qa-tests/**/*.validation.test.ts
4. Run API validations         → qa-tests/api/
5. Run UI/toast validations    → qa-tests/ui/
6. Run auth flow validations   → qa-tests/auth/
7. Run LLM quality checks      → qa-tests/llm/ (if app has LLM features)
8. Run GCP infra health checks → qa-tests/infra/
9. Aggregate results           → qa-reports/go-no-go-report.json
10. Generate human report      → qa-reports/go-no-go-report.md

Test Plan Schema

Save to qa-reports/test-plan.json:

{
  "project": "project-name",
  "version": "x.y.z",
  "date": "ISO-8601",
  "validator": "gcp-fullstack",
  "surfaces": {
    "api_routes": [],
    "server_actions": [],
    "ui_pages": [],
    "toast_notifications": [],
    "auth_flows": [],
    "llm_features": [],
    "database_integrity": [],
    "gcp_infrastructure": []
  }
}

Surface Discovery

• API routes: scan src/app/api/**/route.ts (Next.js) or equivalent
• Server Actions: grep for "use server"
• UI pages: scan src/app/**/page.tsx
• Toast notifications: grep for toast library usage (sonner, react-hot-toast, shadcn toast)
• Auth flows: check Firebase auth setup, middleware
• LLM features: grep for OpenAI/OpenRouter/Anthropic API calls
• Database: read Firestore rules (firestore.rules) or Prisma schema (prisma/schema.prisma)
• GCP infra: check Cloud Run services, Cloud SQL instances, Secret Manager secrets

API Validation Template

// qa-tests/api/entities.validation.test.ts
const BASE_URL = process.env.VALIDATION_BASE_URL || "http://localhost:3000";

describe("API Validation: /api/entities", () => {
  it("returns 200 for authenticated GET", async () => {
    const res = await fetch(`${BASE_URL}/api/entities`, {
      headers: { Authorization: `Bearer ${process.env.TEST_AUTH_TOKEN}` },
    });
    expect(res.status).toBe(200);
  });

  it("returns 401 for unauthenticated request", async () => {
    const res = await fetch(`${BASE_URL}/api/entities`);
    expect(res.status).toBe(401);
  });

  it("response matches expected schema", async () => {
    const res = await fetch(`${BASE_URL}/api/entities`, {
      headers: { Authorization: `Bearer ${process.env.TEST_AUTH_TOKEN}` },
    });
    const data = await res.json();
    expect(Array.isArray(data)).toBe(true);
  });

  it("returns 405 for unsupported methods", async () => {
    const res = await fetch(`${BASE_URL}/api/entities`, { method: "DELETE" });
    expect(res.status).toBe(405);
  });
});

Toast Validation Template

// qa-tests/ui/toasts.validation.spec.ts
import { test, expect } from "@playwright/test";

test.describe("Toast Validation", () => {
  test("success toast on entity creation", async ({ page }) => {
    await page.goto("/entities/new");
    await page.fill('[name="name"]', "Test Entity");
    await page.click('button[type="submit"]');
    const toast = page.locator('[data-sonner-toast], [role="status"], .Toastify__toast');
    await expect(toast).toBeVisible({ timeout: 5000 });
    await expect(toast).toContainText(/created|success/i);
  });

  test("error toast on failure", async ({ page }) => {
    await page.route("**/api/entities", (route) =>
      route.fulfill({ status: 500, body: JSON.stringify({ error: "Failed" }) })
    );
    await page.goto("/entities/new");
    await page.fill('[name="name"]', "Test");
    await page.click('button[type="submit"]');
    const toast = page.locator('[data-sonner-toast][data-type="error"], [role="alert"]');
    await expect(toast).toBeVisible({ timeout: 5000 });
  });

  test("no duplicate toasts on rapid clicks", async ({ page }) => {
    await page.goto("/entities/new");
    await page.fill('[name="name"]', "Test");
    await page.click('button[type="submit"]');
    await page.click('button[type="submit"]');
    const toasts = page.locator('[data-sonner-toast], [role="status"]');
    expect(await toasts.count()).toBeLessThanOrEqual(1);
  });
});

GCP Infrastructure Health Checks

# Cloud Run service status
gcloud run services describe <service-name> --region $GCP_REGION --format="value(status.conditions[0].status)"

# Cloud Run health endpoint
SERVICE_URL=$(gcloud run services describe <service-name> --region $GCP_REGION --format 'value(status.url)')
curl -sf "$SERVICE_URL/api/health" | jq .

# Cloud SQL instance status
gcloud sql instances describe <instance-name> --format="value(state)"

# Cloud SQL backup check
gcloud sql backups list --instance=<instance-name> --limit=1 --format="value(status)"

# Cloud SQL SSL enforcement
gcloud sql instances describe <instance-name> --format="value(settings.ipConfiguration.requireSsl)"

# Firestore security rules deployed
gcloud firestore operations list --limit=1

# Secret Manager — all required secrets exist
for SECRET in "firebase-config" "cloudflare-token" "cross-app-secret"; do
  gcloud secrets describe $SECRET --format="value(name)" 2>/dev/null && echo "$SECRET: OK" || echo "$SECRET: MISSING"
done

All gcloud commands during QA are READ-ONLY (describe, list). NEVER run create, update, or delete during validation.

LLM Output Quality Validation (two-layer)

Layer 1: Rule-Based Checks

export function runRuleBasedChecks(output: { content: string; tokens_used: number; latency_ms: number }, config: {
  minLength?: number;
  maxLength?: number;
  maxTokens?: number;
  maxLatencyMs?: number;
  forbiddenPatterns?: RegExp[];
  requiredFormat?: "json" | "markdown" | "plain";
}): { rule: string; passed: boolean; details: string }[] {
  const results = [];

  if (config.minLength) {
    results.push({ rule: "min_length", passed: output.content.length >= config.minLength,
      details: `Length: ${output.content.length}, min: ${config.minLength}` });
  }
  if (config.maxLatencyMs) {
    results.push({ rule: "latency", passed: output.latency_ms <= config.maxLatencyMs,
      details: `Latency: ${output.latency_ms}ms, max: ${config.maxLatencyMs}ms` });
  }
  if (config.forbiddenPatterns) {
    for (const p of config.forbiddenPatterns) {
      const match = p.exec(output.content);
      results.push({ rule: `forbidden:${p.source}`, passed: !match,
        details: match ? `Found: "${match[0]}"` : "Clean" });
    }
  }
  if (config.requiredFormat === "json") {
    try { JSON.parse(output.content); results.push({ rule: "valid_json", passed: true, details: "OK" });
    } catch { results.push({ rule: "valid_json", passed: false, details: "Invalid JSON" }); }
  }
  results.push({ rule: "not_empty", passed: output.content.trim().length > 0, details: "" });
  results.push({ rule: "not_truncated", passed: !output.content.endsWith("..."), details: "" });

  return results;
}

Layer 2: LLM-as-Judge (via OpenRouter)

export async function llmJudge(output: string, prompt: string, criteria: {
  relevance?: boolean; accuracy?: boolean; completeness?: boolean; tone?: boolean; safety?: boolean;
}): Promise<{ overall_score: number; issues: string[]; recommendation: "pass" | "review" | "fail" }> {
  const OPENROUTER_API_KEY = process.env.OPENROUTER_API_KEY;
  if (!OPENROUTER_API_KEY) {
    return { overall_score: 0, issues: ["OPENROUTER_API_KEY not set — skipping"], recommendation: "review" };
  }

  const response = await fetch("https://openrouter.ai/api/v1/chat/completions", {
    method: "POST",
    headers: { Authorization: `Bearer ${OPENROUTER_API_KEY}`, "Content-Type": "application/json" },
    body: JSON.stringify({
      model: "google/gemini-flash-1.5",
      messages: [{ role: "user", content: `Evaluate this LLM output...\nPROMPT: ${prompt}\nOUTPUT: ${output}\nScore 1-5 on: ${Object.keys(criteria).join(", ")}. JSON response.` }],
      temperature: 0.1,
      response_format: { type: "json_object" },
    }),
  });

  const data = await response.json();
  return JSON.parse(data.choices[0].message.content);
}

Always run rule-based checks BEFORE LLM-as-judge (cheaper, faster). If OPENROUTER_API_KEY is not set, skip LLM judge and mark as "review".

Go/No-Go Report

After all validations, generate qa-reports/go-no-go-report.json:

{
  "project": "project-name",
  "version": "x.y.z",
  "date": "ISO-8601",
  "verdict": "GO | NO-GO | CONDITIONAL",
  "summary": {
    "total_checks": 45,
    "passed": 42,
    "failed": 2,
    "skipped": 1,
    "pass_rate": "93.3%"
  },
  "sections": {
    "api_routes": { "status": "PASS", "checks_run": 12, "checks_passed": 12 },
    "ui_pages": { "status": "PASS", "checks_run": 8, "checks_passed": 8 },
    "toast_notifications": { "status": "FAIL", "failures": [] },
    "auth_flows": { "status": "PASS" },
    "llm_quality": { "rule_based": {}, "llm_judge": {} },
    "database_integrity": { "status": "PASS" },
    "gcp_infrastructure": {
      "cloud_run": "READY",
      "cloud_sql": "RUNNING",
      "cloud_sql_ssl": true,
      "cloud_sql_backup": "SUCCESSFUL",
      "firestore_rules": "DEPLOYED",
      "secret_manager": "ALL_PRESENT"
    }
  },
  "blockers": [],
  "warnings": []
}

Verdict Logic

• GO: All checks pass, no blockers, no high-severity failures.
• NO-GO: Any high-severity blocker OR any auth failure OR any data integrity failure.
• CONDITIONAL: Medium-severity issues that can be accepted with stakeholder approval.

Also generate qa-reports/go-no-go-report.md (human-readable version).

NEVER auto-deploy after a CONDITIONAL or NO-GO verdict. NEVER delete test data from production databases. Redact API keys from reports before writing to disk.