Skip to content

cogni-dao/cogni / .claude/skills/node-setup

node-setup

Verified

Agentic node setup for Cogni forks. Orchestrates the full lifecycle: DAO formation, payment activation, repo identity, infrastructure provisioning, and deploy verification. Delegates to guide docs for step-by-step details.

Node Setup — Agentic Fork Onboarding

You are an infrastructure setup agent. Your job: take a fresh Cogni fork from clone to successful preview and production deployments. Prompt the user only for credentials that require their browser.

References (read these — they own the details)

⚠️ Parts of this skill predate the k3s + Akash split (it references retired paths); verify against cicd-e2e-required-sequence before trusting a step.

Pre-flight

Verify: gh auth status, tofu --version, pnpm --version. Detect repo name from git remote get-url origin.

Node Lifecycle State Machine

clone → formation → local env → activation → infra → deploy
         (pending)    (dev:infra)   (active)

Check payments.status in .cogni/repo-spec.yaml to determine current state.

Phase 0: Formation (payments.status missing or no repo-spec)

Goal: DAO deployed on-chain, repo-spec generated.

  1. Direct user to https://cognidao.org/setup/dao
  2. User copies generated YAML into .cogni/repo-spec.yaml
  3. Follow Node Formation Guide for details
  4. Gate: .cogni/repo-spec.yaml has valid governance.chain_id and payments.status: pending_activation

Phase 1: Repo Identity

Goal: All template references point to this fork.

Derive REPO_SLUG (e.g., my-cogni-node) and REPO_SNAKE (e.g., my_cogni_node) from the repo name. Update:

  • package.json → name
  • .cogni/repo-spec.yaml → intent.name, activity_sources.github.source_refs
  • sonar-project.properties → sonar.projectKey, sonar.projectName
  • .github/workflows/ci.yaml → DB names (REPO_SNAKE_test)
  • .env.local.example, .env.test.example → DB names

Gate: required CI (unit, component, static, manifest) is green on the PR.

Phase 2: Local Environment

Goal: .env.local configured, dev stack running, database provisioned.

  1. Copy .env.local.example → .env.local, update DB names and COGNI_REPO_URL

  2. Prompt user for credentials they must create (see SETUP_DESIGN.md for full list):

    SecretWhere to create
    CHERRY_AUTH_TOKENhttps://portal.cherryservers.com/settings/api-keys
    OPENROUTER_API_KEYhttps://openrouter.ai/settings/keys
    EVM_RPC_URLhttps://dashboard.alchemy.com/apps (Base Mainnet)
    GHCR_DEPLOY_TOKENhttps://github.com/settings/tokens/new — Classic PAT, read:packages scope
    GIT_READ_TOKENhttps://github.com/settings/personal-access-tokens/new — Fine-grained, Contents: Read
  3. Auto-generate: LITELLM_MASTER_KEY, AUTH_SECRET via openssl rand

  4. Start dev infrastructure: pnpm dev:infra

  5. Provision database + run migrations: pnpm dev:setup

  6. Start dev server: pnpm dev

Gate: required CI (unit, component, static, manifest) is green on the PR. App boots at http://localhost:3000 without DB errors.

Phase 3: Payment Activation (payments.status: pending_activation)

Goal: Split contract deployed, payments active.

  1. User adds operator_wallet.address to repo-spec (provision via Privy if needed — see Payment Activation Guide)
  2. Restart dev server to pick up repo-spec changes
  3. User navigates to http://localhost:3000/setup/dao/payments and deploys Split contract via browser wallet
  4. User pastes the output payments_in + payments.status: active into repo-spec

Gate: payments.status: active in repo-spec, payments_in.credits_topup.receiving_address populated.

Phase 4: Infrastructure (preview first, then production)

Goal: VMs provisioned, SSH keys generated and stored.

Follow INFRASTRUCTURE_SETUP.md for detailed steps. Key points:

  1. Generate SSH keypairs, commit public keys
  2. Discover Cherry project ID via API (never hardcode)
  3. Create tfvars (plan: B1-4-4gb-80s-shared minimum)
  4. tofu init && tofu apply
  5. Wait for cloud-init (~3 min), verify Docker is running

Gate: SSH into VM succeeds, docker version works.

Phase 5: GitHub Secrets

Goal: All secrets set for CI/CD deployment.

Follow the secret list in SETUP_DESIGN.md. Three categories:

  1. Auto-generated per env — DB creds, service tokens, Temporal creds (use openssl rand)
  2. From .env.local — shared credentials (OpenRouter, EVM RPC, PostHog, etc.)
  3. Repo-level — CHERRY_AUTH_TOKEN, GHCR_DEPLOY_TOKEN, GIT_READ_TOKEN

Set DOMAIN as both variable and secret per environment. Ask user for domain names.

Gate: gh secret list --env preview shows all required secrets.

Phase 6: DNS

Goal: Domain records point to VMs.

Ask user to create A records. Verify with dig +short <domain>.

Phase 7: Deploy & Verify

Goal: Green CI run, app responding.

  1. Merge to main to trigger canary promotion workflow
  2. Monitor: gh run view <id> --json status,conclusion,jobs
  3. On failure: check logs, fix, rerun
  4. Checkpoint: Preview green → repeat Phases 4-7 for production

Gate: curl -I https://<domain>/readyz returns 200.

Done

  • Preview deployment green
  • Production deployment green
  • DNS resolves for both environments
  • /readyz returns 200 on both domains

Anti-patterns

  1. NEVER source .env.local — use grep extraction for individual vars
  2. NEVER use fine-grained PATs for GHCR — only Classic PATs work
  3. NEVER use 2GB VMs — full stack requires 4GB minimum
  4. NEVER hardcode cogni-template names — derive from repo name
  5. NEVER trust /v1/regions for auth verification — it's public; use /v1/teams
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 318kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 117kUpdated Claude CodeCodexVerifiedInstall