Skip to content

CRED Way of Working — Meta SOP

Version: 1.0 · February 2026
Owner: Tom Dwyer
Applies to: Everyone — read this once before reading your role doc

Resources

The Four Mindset Shifts

These are not suggestions. If you find yourself working against any of these, stop.

1. Everyone Is Full-Stack. Full Stop.

There are no front-end engineers. No back-end engineers. No "I don't do that" engineers. Everyone builds the full feature — UI, API, database — end to end.

AI handles the parts you don't know. If you're stuck on something outside your comfort zone, the answer is ask Cursor, not hand it off. The only specialist roles are DE and DS — data engineering and data science require domain expertise that genuinely can't be agentic-coded away. Everything else is fair game.

2. No Figma Unless Cursor Can't Build It First.

Figma is not a starting point. It is a last resort for net-new components that don't exist in Storybook and cannot be achieved by iterating with Claude.

Claude first → iterate → if genuinely blocked → then Figma.

Opening Figma before trying Claude means handoffs, review cycles, and re-implementation. Build it. Iterate it. Escalate to Figma only when you're truly stuck.

3. No Human Publishes AI Slop.

No AI-generated content meant for another human to consume gets published without manual review. Tickets, docs, PRs, Slack messages — if a human will read it, a human must review it first. Read it. Trim the filler. Sharpen the language. If it reads like a machine wrote it, rewrite it until it doesn't.

4. GitHub Is the System of Record. Fix First, Document After.

Do not write documentation before you have working code. Do not create tickets for problems you can fix right now.

Fix it, then record it if it matters.

GitHub history, merged PRs, and Linear are the record of what happened. A spec that exists before the code is a story you told yourself. Build the thing. Documentation follows.

How We Work

Kanban, Not Sprints

There are no sprints. Every developer has a personal backlog managed by their PM. You pick up the next highest-priority item, work it to completion, and move on. This is a Kanban-style workflow — continuous flow, not time-boxed iterations.

Pods

Work is organised into pods. Each pod has a PM, engineers, and shared access to Design and QA. Your PM runs daily/bi-weekly pod calls to keep work moving, unblock issues, and reprioritise as needed.

Merge Confidently — Medium to Large PRs

Don't break work into artificially small commits. AI quality is high enough to support medium and large PRs, and CI automation handles conflicts and code review comments automatically. Every merge should still be protected by a feature flag so incomplete work never reaches customers.

Always merge to develop rather than keeping long-lived branches. Long-lived branches diverge and cause painful conflicts. The only exception is when a change fundamentally restructures a layout and cannot be feature-flagged — in that case, keep it as an open PR and message Tom before merging.

Deployment Cadence

Day What Happens
Friday develop is promoted to staging. Merges to develop continue as normal.
Monday–Tuesday QA tests on the staging environment. Bugs found in staging are fixed via PRs that target the staging branch. These PRs should be squash-merged so each fix is a single commit. That commit is then cherry-picked back into develop to keep it in sync.
Wednesday staging is promoted to production after QA sign-off.

This creates a buffer to catch regressions before they hit customers. Staging only receives bug fixes — no new feature work lands there directly.

Feature Flags & Analytics

Every customer-facing feature ships behind a PostHog feature flag. Every feature has PostHog analytics events wired before merge. No exceptions.

The rollout lifecycle:

Flag created (0% rollout)
    → Internal only (CRED workspaces)
    → Alpha (select customer workspaces)
    → Beta (broader rollout)
    → GA (100%)
    → Flag removed from code and PostHog

Dead flags are tech debt. Remove them at GA.

Local development: All feature flags return true by default. PostHog runs in debug mode and logs all calls to the browser console. Override specific flags via DEV_FLAG_OVERRIDES in the FE repo.

Review apps: Test with the flag both on and off before merging. Confirm the feature is fully hidden when the flag is off and works end-to-end when the flag is on.

Reference: Full implementation details are in the PostHog Guide. The posthog-analytics Cursor skill in web-commercial provides code patterns for event enums, capture calls, flag utilities, and gating.

Concurrent Workflow: Local + Cloud Agents

Use cloud agents as the default for parallel execution — they let you work across multiple branches without switching locally.

The workflow:

  1. Plan locally in Cursor (Plan Mode with cred-wiki context)
  2. Cloud agents execute the plan in a new PR
  3. Test via review apps — verify the output in the deployed review app
  4. If many issues, bring local — pull the branch for focused iteration

Cloud agents should use the same configured environment as local — same .env, same repo config, same tool setup — so output matches what you'd get locally.

For local side-by-side comparison (e.g., reviewing a PR while coding on another branch), use git worktrees instead.

All Design Reviews via Localhost

All design reviews and presentations are done via localhost, not Figma. Run your branch locally and walk through the live UI during review calls.

Always Use the Top-Performing Model

Use the highest-ranked model for web development as measured by the Code Arena Leaderboard. At the time of writing, this is Claude Opus 4.6.

Check the leaderboard periodically — the top model changes. Always configure Cursor to use whatever is currently #1 for code/web development. Using a weaker model when a better one is available means slower work and worse output.

Architecture Primer

The Five Repos

Repo What It Is Language
cred-web-commercial Product UI — what customers see React / TypeScript
cred-api-commercial Customer-facing GraphQL API. User data, accounts, collections, Salesforce Node.js / GraphQL
cred-model-api CRED data GraphQL API. Enrichment data — companies, people, brand interactions, scoring Node.js / GraphQL
cred-dbt Data transformation layer. BigQuery tables that feed cred-model-api via Postgres SQL / dbt
cred-wiki Internal architecture documentation. Always open in your Cursor workspace. Markdown

Commercial vs Model — The Simple Rule

Commercial = customer data. User accounts, workspace settings, collections, Salesforce, transcripts.
Model = our data. CRED's enrichment pipeline — companies, people, LinkedIn signals, brand interactions, scoring.

How Data Flows

Enrichment (CRED data):
  Sources → BigQuery (raw) → dbt (transform) → Postgres sync → cred-model-api ──┐
                                                                                  ├→ Supergraph API → cred-web-commercial
Commercial (customer data):                                                       │
  Postgres ───────────────────────────────────────────→ cred-api-commercial ──────┘

cred-web-commercial talks to the Supergraph API (api.credplatform.com/graphql), which federates both cred-model-api and cred-api-commercial into a single GraphQL endpoint. The front-end never calls the sub-APIs directly.

When to Involve DE / DS

New data pipelines, external source integrations, scoring model changes, or significant BigQuery restructuring. Flag to Tom before any BE work in these areas.

Using Git Worktrees

Git worktrees let you check out multiple branches simultaneously in separate directories without cloning the repo again. Use worktrees when you need to compare or review branches locally side by side. For parallel feature execution, use cloud agents instead — they are faster and don't require local branch management.

Each worktree is an isolated working directory with its own branch, but they all share the same .git object store — no duplicate downloads, much faster than git stash / git checkout cycling.

Create a worktree to compare or review a branch:

# From the repo root, create a worktree for the branch you want to review
git worktree add .worktrees/pr-review origin/feature-branch

Set up the worktree (dependencies and env files are not shared):

cd .worktrees/pr-review
cp ../../.env .env

# For cred-web-commercial (uses Bun)
bun install

# For cred-api-commercial / cred-model-api (use npm)
npm install

Open the worktree in its own Cursor window (File → Open Folder) and run localhost on a different port to compare side by side with your main checkout. Example for cred-web-commercial:

PORT=8002 bun run dev   # In your main checkout
PORT=8003 bun run dev   # In the worktree

Useful commands:

git worktree list                            # See all active worktrees
git worktree remove .worktrees/pr-review     # Clean up after review

Important: Add .worktrees/ to your .gitignore so worktree directories are not tracked. Each worktree has its own node_modules, so clean up worktrees you are no longer using to free disk space.

When to use worktrees:

  • Reviewing a PR while you have uncommitted work on another branch
  • Comparing behaviour between branches side by side
  • Running a long build/test on one branch while coding on another

For parallel feature execution, use cloud agents — not worktrees.

Prerequisites — Do This Before Anything Else

Complete every item below before your first piece of certified work.

1. Clone All Five Repos

git clone git@github.com:credinvest/cred-web-commercial.git
git clone git@github.com:credinvest/cred-api-commercial.git
git clone git@github.com:credinvest/cred-model-api.git
git clone git@github.com:credinvest/cred-dbt.git
git clone git@github.com:credinvest/cred-wiki.git

Open all five as a Cursor Workspace (File → Add Folder to Workspace for each). cred-wiki must be in every session — this is not optional.

2. Install Local Tools

Tool Purpose Install
Cursor AI IDE — primary coding environment cursor.sh
Docker Desktop Required for cred-api-commercial and cred-model-api locally docker.com
DB Beaver (Community) Postgres desktop client dbeaver.io
1Password Secrets management — .env files, DB credentials, 2FA Team signup
Node.js (LTS) Required for cred-web-commercial nodejs.org

Local Development Tips

  • Chrome side-by-side: Run Google Chrome with your code editor and localhost windows side by side for ~5x faster iteration speed.
  • Incognito for cache issues: If you're not seeing your changes on localhost, open an incognito tab. Browser cache is almost always the issue.
  • Cursor Design Mode: Toggle in the bottom-right corner of Cursor (first icon from the right). Select any component to see its style properties. Tweak visually — border color, line height, spacing, colors — click "Apply" to generate a prompt. Say "apply this to all components that use this" to cascade changes. This is the Figma-like experience inside Cursor.

3. Configure .env Files — Every Repo

Every repo requires a correctly populated env file. This is the most common reason local environments fail.

  1. 1Password → search repo name → download the .env file
  2. Copy the contents into the correct file for each repo:
    • cred-web-commercial → .env.local (this is the active env file for this repo)
    • cred-api-commercial → .env
    • cred-model-api → .env
    • cred-dbt → .env
  3. Delete the downloaded file from the repo root if it doesn't match the expected name — do not leave stray env files
  4. The .env.example file in each repo is a template with placeholder values — do not use it as your active env file
  5. If download fails: ask Alex to share in Slack, copy it, ask Alex to delete the message immediately
  6. Verify every key variable is non-empty before starting the server
Repo Variables to Check
cred-model-api API_TOKEN, Postgres host/port/password, Elasticsearch node
cred-api-commercial Database connection string, Salesforce credentials
cred-web-commercial API endpoint URLs (cred-model-api + cred-api-commercial)
cred-dbt BigQuery project ID and credentials

Never commit .env files to GitHub. They are in .gitignore — do not override this.

4. Install MCPs in Cursor

Open Cursor Settings → MCP and install and enable the following:

MCP Purpose Enable State
bigquery Agent reads schemas, runs SQL, creates jobs Enabled — 9 tools
dbt Agent triggers builds, checks status, switches branches Enabled — 46 tools. ⚠️ Select BigQuery model project only during auth
figma Agent reads component specs Installed — disable during BE-only work
gcloud Agent runs GCP jobs directly Enabled — 1 tool
gcp-observability Agent reads workflow logs and execution status Enabled — 13 tools
gcp-storage Agent reads GCP storage and job config Enabled — 17 tools
github Agent reads PRs, fixes conflicts, opens PRs Enabled — 40 tools, 2 prompts
linear Agent creates and updates tickets Enabled — 39 tools
vercel Agent reads build/deploy errors Enabled — 12 tools, 12 prompts
circleci Agent reads CI pipeline status, build logs, and test results Enabled
shadcn-ui Agent references correct ShadCN/Radix UI base components by name Enabled
stitch (Google Stitch) Agent generates UI screens from text, extracts design DNA (fonts, colors, layout) Enabled
@21st-dev/magic Agent pulls pre-built 3D/reactive React components from curated library Enabled

⚠️ GCP permissions required first: Text Alex with your Google email and ask for Cloud Workflows Viewer + Cloud Scheduler Job Runner before your first session.

Tool limit: If Cursor complains about too many tools, disable MCPs not in use. Expected behaviour.

5. Install Cursor Skills

Add the following skills to Cursor so the agent has the right context for design and product work. Run this prompt in Cursor:

/create-skill Help me create this skill for Cursor: 
@frontend-design-SKILL.md @product-self-knowledge-SKILL.md
Skill Purpose
frontend-design Generates distinctive, production-grade frontend interfaces that avoid generic AI aesthetics. Covers typography, colour, motion, spatial composition, and visual details.
product-self-knowledge Ensures accurate answers about Anthropic products (Claude API, Claude Code, Claude.ai) by routing to official docs instead of guessing.
nano-banana-2 Generates high-fidelity UI mockups, product shots, and design assets via Gemini 3 Pro.
ui-ux-pro-max Searchable design intelligence database — 50 styles, 21 palettes, 50 font pairings. Auto-generates design systems.

Download the skill files from 1Password under Cursor Skills and place them in your Downloads folder before running the prompt.

Design Power Stack Setup (Cursor)

Everyone does FE. Set up these four tools in Cursor — they form the design-to-code pipeline.

Prerequisites check:

node --version    # Need v18+
python3 --version # Need 3.8+

You also need: Google Cloud CLI (brew install --cask google-cloud-sdk), a Gemini API key from Google AI Studio, and a 21st.dev API key from the 21st.dev Magic Console.

1. Google Stitch MCP

gcloud auth login
gcloud projects create my-stitch-project --name="Stitch Design"
gcloud config set project my-stitch-project
gcloud auth application-default set-quota-project my-stitch-project
gcloud beta services mcp enable stitch.googleapis.com --project=my-stitch-project

Enable billing at console.cloud.google.com/billing (Stitch API itself is free). Then add to Cursor: Settings → MCP → Add New Server with command npx and args @_davideast/stitch-mcp proxy. Or add to .cursor/mcp.json:

{ "mcpServers": { "stitch": { "command": "npx", "args": ["@_davideast/stitch-mcp", "proxy"] } } }

2. Nano Banana 2 (Image Generation Skill)

mkdir -p ~/tools && cd ~/tools
git clone https://github.com/kingbootoshi/nano-banana-2-skill.git nano-banana-2
cd nano-banana-2 && npm install
echo 'export GEMINI_API_KEY="your-gemini-api-key-here"' >> ~/.zshrc
source ~/.zshrc
mkdir -p ~/.local/bin
printf '#!/bin/sh\nexec npx ts-node ~/tools/nano-banana-2/src/cli.ts "$@"\n' > ~/.local/bin/nano-banana && chmod +x ~/.local/bin/nano-banana
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Install as a Cursor skill: copy SKILL.md to .cursor/skills/nano-banana-2/SKILL.md in your workspace. For transparent backgrounds: brew install ffmpeg imagemagick.

3. UI/UX Pro Max Skill

npm install -g uipro-cli
uipro init --ai cursor

Or manually: clone from GitHub and copy to .cursor/skills/ui-ux-pro-max/.

4. 21st.dev Magic MCP

Get your API key from the 21st.dev Magic Console. Add to Cursor: Settings → MCP → Add New Server with command npx, args -y @21st-dev/magic@latest, and env API_KEY=your-key. Or add to .cursor/mcp.json:

{ "mcpServers": { "@21st-dev/magic": { "command": "npx", "args": ["-y", "@21st-dev/magic@latest"], "env": { "API_KEY": "your-21st-dev-api-key" } } } }

6. DBT Account Setup

Credentials in 1Password under DBT dev account. Log in at cloud.getdbt.com. Use 1Password for 2FA. One person logged in at a time — coordinate with the team.

⚠️ First login requires one-time BigQuery credential linking. Message Alex if you see a credential error.

7. Confirm Permissions

Tool What You Need Who Grants It
GitHub Write access to all five repos Cherry
Linear Member + ability to create issues Cherry
BigQuery BigQuery Data Viewer + BigQuery Job User Alex
GCP Cloud Scheduler Cloud Scheduler Job Runner Alex
GCP Workflows Cloud Workflows Viewer Alex
DBT Cloud Shared dev account (1Password) Cherry
Vercel Member of CRED Investments org Cherry
Figma Member of CRED workspace Cherry
PostHog Member of CRED project Cherry
1Password Self-serve signup Self-serve

8. Certification

Complete the enablement session (planning, FE, BE, API) before working independently. Contact Tom to book.

Cursor Rules — Add These to Your Settings

Add the following rules to Cursor Settings → Rules so the agent produces correct output for every FE task. Everyone must add these.

Component naming rule:

When doing front-end work, always reference the ShadCN MCP for base components and use Storybook for the CRED-styled version. Use exact component names (e.g., "InputGroup", "Badge", "Accordion") — do not say "input box" or "dropdown". If Cursor invents a component that doesn't exist, correct it by name. Reference component.gallery for component name discovery.

Restyle rule:

When restyling existing components, always retain all event logic. Only change visual styling. Do not replace a component with a ShadCN primitive — this will break event bindings.

Design tokens rule:

When prompting for FE work, use design token names (e.g., "use accent-foreground for the text color") instead of describing colors. If a token is missing from CSS, add it.

Design system rule (maintained by Design team):

Use sidebar panels for all action/input flows. Use tab bars for sub-views within a page. Radio buttons for single-select, checkboxes for multi-select. Use the existing breadcrumb component for navigation hierarchy. Always use only existing Storybook components — if a component doesn't exist in Storybook, flag it rather than creating a one-off styled component.

Role SOPs

Once prerequisites are done, go to your role doc: