/scaffold

name: scaffold
description: >
  Generate the complete file set for a new integration, endpoint, or feature
  flag following established project patterns. Use when adding a new
  integration (like Jira, CodeRabbit, Google Drive), creating a new API
  endpoint with full stack, or setting up a new feature flag. Triggers on:
  "new integration", "add an integration", "scaffold", "create endpoint",
  "add a new provider", "wire up a new service". Always includes a feature
  flag. Follows the Jira integration pattern.

Scaffold

Generate the complete file set for a new integration, endpoint, or feature flag.

Usage

/scaffold integration <name>    # Full integration scaffold
/scaffold endpoint <name>       # API endpoint scaffold
/scaffold feature-flag <name>   # Feature flag scaffold (delegates to /unleash-flag)

User Input

$ARGUMENTS

Parse the scaffold type and name from `$ARGUMENTS`. If ambiguous, ask the user.

Integration Scaffold

Based on the established integration pattern (Jira, CodeRabbit, Google Drive), generate the full file set.

Backend Files

| File | Purpose | Template | |------|---------|----------| | `components/backend/handlers/{provider}_auth.go` | Auth handlers + K8s Secret CRUD | Follow `jira_auth.go` pattern | | `components/backend/handlers/integration_validation.go` | Add validation + test endpoint | Add `Validate{Provider}` function | | `components/backend/handlers/integrations_status.go` | Add to unified status | Add provider to status aggregation | | `components/backend/handlers/runtime_credentials.go` | Session credential fetch with RBAC | Add `fetch{Provider}Credentials` | | `components/backend/routes.go` | Register endpoints | Add route group with auth middleware |

Frontend Files

| File | Purpose | Template | |------|---------|----------| | `components/frontend/src/components/integrations/{provider}-connection-card.tsx` | Integration card UI | Follow existing integration card (e.g., Jira) | | `components/frontend/src/services/api/{provider}-auth.ts` | API client | Follow existing auth service pattern | | `components/frontend/src/services/queries/use-{provider}.ts` | React Query hooks | Follow existing query hook pattern | | `components/frontend/src/app/api/auth/{provider}/route.ts` | Next.js proxy route | Follow existing auth proxy | | `components/frontend/src/components/integrations/IntegrationsClient.tsx` | Add card import | Update imports + render | | `components/frontend/src/components/integrations/integrations-panel.tsx` | Add to panel | Update panel |

> **Note:** Before scaffolding, verify the reference files exist by checking `components/frontend/src/components/integrations/` and `components/frontend/src/services/`. File names may differ from examples above.

Runner Files

| File | Purpose | Template | |------|---------|----------| | `components/runners/ambient-runner/src/auth.py` | Add `fetch_{provider}_credentials()` | Follow `fetch_jira_credentials` pattern |

Feature Flag

| File | Purpose | |------|---------| | `components/manifests/base/core/flags.json` | Add `integration.{provider}.enabled` |

Checklist

After scaffolding, verify:

• [ ] All backend handlers use `GetK8sClientsForRequest` for user operations
• [ ] Credentials stored in K8s Secret with OwnerReferences
• [ ] Frontend uses React Query hooks (no manual fetch)
• [ ] Frontend uses Shadcn UI components
• [ ] Feature flag gates the integration card
• [ ] Tests mock the feature flag hook
• [ ] Runner credential fetch is added to `populate_runtime_credentials()`

Endpoint Scaffold

For adding a new API endpoint with full-stack support.

Files to Create/Modify

| Layer | File | Action | |-------|------|--------| | Backend handler | `components/backend/handlers/{resource}.go` | Create | | Backend routes | `components/backend/routes.go` | Add routes | | Backend types | `components/backend/types/{resource}.go` | Create if needed | | Frontend API | `components/frontend/src/services/api/{resource}.ts` | Create | | Frontend queries | `components/frontend/src/services/queries/{resource}.ts` | Create | | Frontend proxy | `components/frontend/src/app/api/{resource}/route.ts` | Create |

Backend Handler Template

func List{Resource}(c *gin.Context) {
    projectName := c.Param("projectName")

    reqK8s, reqDyn := GetK8sClientsForRequest(c)
    if reqK8s == nil || reqDyn == nil {
        c.JSON(http.StatusUnauthorized, gin.H{"error": "Invalid or missing token"})
        return
    }

    // RBAC check
    // List operation with reqDyn
    // Return response
}

Frontend Query Template

export function use{Resource}(projectName: string) {
  return useQuery({
    queryKey: ["{resource}", projectName],
    queryFn: () => {resource}Api.list(projectName),
  })
}

Feature Flag Scaffold

Delegates to the `/unleash-flag` skill for the full feature flag workflow.

Run `/unleash-flag` with the flag name and follow its checklist.