[BUG] Claude md file adherence

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

<img width="829" height="742" alt="Image" src="https://github.com/user-attachments/assets/42975073-3506-40c6-a4ef-0bbdee5c6a0d" />

Claude code it cli vs extension behave way different , claude in terminal adheres better to the claude.md file instruction whre as the vscode extension seems dumber, goes on his own unless reminded.

What Should Happen?

Adhere to claude md rules

Error Messages/Logs

Steps to Reproduce

Create an issue , that requires claude to follow a strict claude md workflow , test how it behaves in extension vs terminal

Claude Model

Opus

Is this a regression?

I don't know

Last Working Version

_No response_

Claude Code Version

2.1.7

Platform

Anthropic API

Operating System

Windows

Terminal/Shell

VS Code integrated terminal

Additional Information

This is my claude md file for reference :

CLAUDE.md - Multi-Tenant CRM SaaS

Commands: npx tsc --noEmit • node scripts/check-security.js • node scripts/check-console-error.js • node scripts/check-react-query-performance.js • .\scripts\regen-types.ps1 MCP: Context7 (library docs) • best-practices (patterns) • Refs: .claude/knowledge.md • .claude/progress.md • .claude/context/* BMAD Lite: /bmad:bmm:agents:[pm|architect|ux-designer] • DB: STAGING xxx • PROD xxx

🚦 TASK ROUTER (Auto-Orchestrate)

⚡ AUTO: Detect route → invoke workflow immediately. Don't ask "should I use BMAD?" — just do it.

| Route | Triggers | Action |
|-------|----------|--------|
| 🔴 A | typo, style, color, padding, single rename | Just do it |
| 🟠 B | "broken", "not working", error, debug | Context7 + best-practices → fix (3+ files → C) |
| 🟡 C (2-4 files) | add field/button/filter, "show X" | Ask 5-7 Qs → EnterPlanMode → /gsd:execute-plan |
| 🟢 D (5-8 files) | "add X management", create page, dashboard | PM → /gsd:plan-phase → /gsd:execute-plan |
| 🔵 E (8+ files) | new module/system, integration, rebuild | PM → Architect → /gsd:plan-phase → execute |
| 🟣 F | "how does X work", "where is", "is it possible" | Explore agents → explain with file refs |
| ⚪ G | "design page", "improve UX", wireframes | /bmad:bmm:agents:ux-designer |
| ⚫ H | refactor, clean up, optimize, extract | 1-2 files: EnterPlanMode / 3+: PM first |

Route C questions: 1) Permissions — who can use? 2) Data/schema — fields, validation? 3) Edge cases — empty, duplicate, max? 4) Cosmos AI — AI access? 5) Dependencies — related features?

Route D/E flow:

D: PM → [AUTO-RESEARCH] → PRD+Epics → [AUTO: convert-to-gsd] → plan-phase → execute-plan → [AUTO-ROUTE]
E: PM → Architect → [AUTO: convert-to-gsd] → plan-phase → execute-plan → [AUTO-ROUTE]

Routing Rules: 1) Announce route 2) Auto-invoke workflow 3) Never skip questions 4) Upgrade if complex 5) Ask if uncertain: "Could be Route C or D..." 6) Skills auto-trigger

Why BMAD? Without requirements: build wrong thing (2-4h wasted). With BMAD: 10-20 min planning, build right ONCE.

🎯 BMAD LITE

| Agent | Command | Research |
|-------|---------|----------|
| PM | /bmad:bmm:agents:pm | Context7 + best-practices + 3-4 Explore |
| Architect | /bmad:bmm:agents:architect | Context7 + best-practices + 4 Explore |
| UX | /bmad:bmm:agents:ux-designer | best-practices + 4-6 Explore |

Shortcuts: MH (menu) • CH (chat) • DA (dismiss)
Auto: Research before agent • BMAD→GSD conversion • Routing between plans • Context file creation
Manual: Answer questions • Review plans • Checkpoints • Type stop to pause
Bridge output: .planning/PROJECT.md, ROADMAP.md, STATE.md, phases/*/CONTEXT.md
Output locations: _bmad-output/planning-artifacts/ • Context: .claude/context/

🔄 GSD COMMANDS

| Command | Purpose |
|---------|---------|
| /gsd:progress | Show position + route next |
| /gsd:new-project | Init .planning/ (from BMAD or scratch) |
| /gsd:plan-phase N | Create PLAN.md (2-3 tasks) |
| /gsd:execute-plan | Execute + atomic commits + auto-route |
| /gsd:plan-fix | Fix plan for UAT issues |
| /gsd:pause-work | Create .continue-here.md |
| /gsd:resume-work | Restore context |
| /gsd:complete-milestone | Archive + route next |
| /bmad:convert-to-gsd | Convert BMAD outputs to GSD (auto-triggered) |

Execution Flow:

BMAD Complete → [AUTO: convert-to-gsd] → .planning/ → plan-phase → execute-plan
  ↓ [AUTO-ROUTE]: More plans? → next plan | Phase done? → next phase | Milestone done? → complete-milestone
  Type 'stop' to pause

Commits: {type}({scope}): {desc} + Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Types: feat, fix, test, refactor, perf, chore, docs

💾 CONTEXT OPTIMIZATION

Problem: 45k autocompact buffer (not configurable). Solution: Use subagents + save to files.

| Operation | Do This |
|-----------|---------|
| Codebase search | Task(Explore) not direct Grep |
| Library docs | Context7 → summarize |
| Important findings | Save to .claude/context/YYYY-MM-DD_[topic].md |

When to save: After research • After BMAD • After debugging • Before compaction
Recovery: Read plan file → identify position → announce → continue
Format: "📋 Reading plan... Current: Phase 2, Step 2.3. Completed: Phase 1 (4/4). Continuing..."

🧠 PLAN MODE

EnterPlanMode = built-in Claude Code tool (not skill/command). Goal: .claude/plans/YYYY-MM-DD_HHMM_[name].md

| Gate | Requirement | ⛔ HALT |
|------|-------------|--------|
| 1 | best-practices + 3+ Explore + Context7 (2+ libs) + WebSearch | No questions |
| 2 | Save to .claude/context/YYYY-MM-DD_[topic].md | Lost on compact |
| 3 | 5-8 questions (goal/data/permissions/edge cases) | No plan file |
| 4 | 2-4 MORE agents based on user answers | Shallow plan |
| 5 | Correct path + Summary/Decisions/Files/Phases + 5-Question Framework | INVALID |

5-Question Framework (answer before TodoWrite):

1. DATA: flows, schema, tables? 2. STATE: server/client/URL/cache? 3. BOUNDARIES: API/actions/edge? 4. FAILURES: what breaks, handling? 5. INTEGRATION: Cosmos/permissions/RLS/cache?

| Pattern | Questions |
|---------|-----------|
| "Add [noun]" | CRUD lifecycle? Archive? |
| "Show [data]" | Pagination? Filters? Real-time? |
| "When [event]" | Sync/async? Queue? Webhook? |
| "Connect to [API]" | Polling? Webhook? OAuth? |
| "Let users [action]" | Permission model? |

🗄️ DATABASE

# Migration (STAGING only)
"C:\Program Files\PostgreSQL\17\bin\psql.exe" "postgresql://postgres.xxx:xxx%40@aws-1-eu-north-1.pooler.supabase.com:xxx/postgres" -f "supabase/migrations/FILE.sql"
# ALWAYS after schema change
npx supabase gen types typescript --project-id xxx> src/lib/types/database.ts

Rules: Files in supabase/migrations/ with timestamp naming • Never push old migrations • Never destructive on PROD

🚨 CRITICAL RULES

1. Error Tracking — ⛔ NEVER console.error/log

• Client: captureClientError(error, context).catch(() => {}) from @/lib/error-reporting/client
• Server: logServerActionError("fn", error, ctx) / logAPIRouteError("METHOD /path", error) from @/lib/utils/error-logger
• Webhooks: withWebhookErrorHandler (auto)

2. JWT — Always getOrganizationIdFromJWT() from @/lib/auth/jwt. Never manual decode.

3. RLS Bootstrap — No org_id in JWT? Use createAdminClient().

4. Validation — Run before EVERY completion:
npx tsc --noEmit • node scripts/check-security.js • node scripts/check-console-error.js • node scripts/check-react-query-performance.js

5. DB Types — After schema change: npx supabase gen types typescript --project-id nzccmdurybujxbqbliok > src/lib/types/database.ts

6. DRY — 3+ files same field → registry (see src/features/leads/field-registry.ts)

7. Multi-Tenant — Never hardcode stages/tags/fields. Use hooks/actions.

8. Cosmos AI — Every feature needs AI tools. See COSMOS section.

9. Permissions — New pages: 1) Add Resource type 2) PermissionsMatrix 3) Permission check 4) Migration

• Entity (leads/clients): checkUserPermissionWithScope() + dataScope filter
• Org-wide: checkUserPermission() only

10. React Query — Tiered caching, no refetch storms:

• Profiles (src/lib/query/cache-profiles.ts): CONFIGURATION/ENTITY (Infinity), STATS (3min), REALTIME (Infinity)
• Mutations (src/lib/query/useOptimisticMutation.ts): Use setQueryData in onMutate, only invalidate for stats
• ❌ Multiple invalidateQueries in onSuccess • ❌ router.refresh() • ❌ useEffect([open, prop1, prop2]) • ❌ Missing refetchType: 'active' • ❌ <Link href={dynamic}> without prefetch={false}

11. Context7 — ⛔ MANDATORY for ALL library work. Check version → query docs → verify API.

12. AI Refresh — Add useAIDataRefresh() hook + type to AIDataMutationType.

13. Best Practices — ⛔ MANDATORY: lookup-best-practices({ feature: "..." })

14. MCP Priority — MCP tools → Dedicated tools → Bash

15. Coverage — Grep to verify ALL occurrences modified.

16. GitHub — Always gh CLI. Never web search.

17. Middleware — JWT may fail silently. Fallback to user.app_metadata.organization_id. See middleware.ts:186-193.

18. Server Components — Call getAuthContext()/cookies()/headers() BEFORE getQueryClient() or crypto.randomUUID().

🔐 SECURITY

Run node scripts/check-security.js — zero critical/high.

| Priority | Issues | Fixes |
|----------|--------|-------|
| P0 | Filter injection, CORS *, SQL injection, webhook no-sig | escapeFilterValue(), corsHeaders, parameterized SQL, HMAC |
| P1 | Missing rate limit, input validation, replay attacks | checkRateLimit(), z.parse(), timestamp validation |
| P2 | Unsafe JSON.parse, PII logging, .passthrough() | try-catch, proper logging, .strict() |

Auto-safe: /admin/* + ADMIN_EMAILS, /cron/* + CRON_SECRET, /webhooks/* + sig, /auth/*/callback, /inngest/*
Bypass-proof: Script strips comments → keywords in comments won't bypass
Allowlist: Edit ALLOWED_EXCEPTIONS in scripts/check-security.js

🏗️ ARCHITECTURE

| Type | Location |
|------|----------|
| Pages | app/(auth)/, app/(dashboard)/ |
| Actions | features/[name]/actions/ |
| Components | features/[name]/components/ |
| Hooks | features/[name]/hooks/ |
| Shared Utils | lib/utils/ |

Component tiers: Primitives (components/ui/ NEVER modify) → Design (components/ui/glass-*.tsx use variants) → Features (compose)
Patterns: Server Components default • <200 lines • Zod on actions • ActionResponse from @/lib/types/actions
Glass: glass (cards) • glass-popover (dropdowns, max 0.15) • glass-interactive (buttons) • glass-input
BANNED: dark:bg-gray-700/800/900 → use dark:bg-white/[0.03] or dark:bg-white/5

🐛 LEARNED PATTERNS

Refetch Storm (Dec 2025): Multiple invalidateQueries → use setQueryData + single invalidation. staleTime 30s → 5 * 60 * 1000 (5min). useEffect deps → only [open], read props inside. router.refresh → queryClient.invalidateQueries. Duplicate invalidation → single source of truth per key.

Prefetch Storm (Jan 2026): 40-60 RSC requests on dashboard. Fix: prefetch={false} on dynamic Links.

// ❌ {leads.map(l => <Link href={`/leads/${l.id}`}>)}
// ✅ {leads.map(l => <Link href={`/leads/${l.id}`} prefetch={false}>)}

CSS filter: Breaks position:fixed (creates new containing block). Fix: Use React Portal.

Platform gotchas: TikTok=Business API (business-api.tiktok.com) + x-lead-region: eu header • Meta=2 OAuth apps (Business + Consumer for Marketing API vs login) • Upstash=raw incr+expire not @upstash/ratelimit (Lua fails free tier) • Dark mode=mounted state guard for hydration

Settings: Never <Link href="/settings/...">. Use inline Popover/Dialog (see PropertyConfigPopover.tsx, CardSettingsButton.tsx, PipelineSettingsButton.tsx).

Scripts: start-session.ps1 (pull+clone+dev) • deploy.ps1 (check+push+sync) • regen-types.ps1 • new-migration.ps1 -Name "x"

🤖 COSMOS AI

Stack: Vercel AI SDK v5 + GPT 5 Nano + Gemini 3 Flash + Semantic Cache

Integration (every feature):

1. lib/ai/tools/operation-registry.ts — Add schema + definition
2. lib/ai/tools/operations/[domain].ts — Create handler
3. lib/ai/tools/operations/index.ts — Export via registerHandler()
4. lib/ai/tools/tool-definitions.ts — Wire in createCRMTools()

| Category | Approval | Rewind | Use For |
|----------|----------|--------|---------|
| read | No | No | Queries, searches |
| safe_write | No | 24h | Create/update single records |
| destructive | Yes | 24h | Bulk operations, deletes |

Domains: leads • clients • whatsapp • email • tasks • deals • analytics • settings

🛡️ SKILLS

| Tier | Skills |
|------|--------|
| Meta | system-design-orchestrator, critical-rules-enforcer |
| Workflow | plan-mode-workflow, plan-compliance-validator, plan-critique-agent, best-practices-library, bmad-research-enforcer |
| Research | research-requirements, question-requirements |
| Task Routing | new-feature, fix-bug, fix-typescript, refactor |
| Feature | cosmos-ai-mandatory, multi-tenant-security, permission-patterns, database-workflow |
| Quality | react-query-patterns, glass-styling-patterns, error-handling-patterns |

🚫 PROHIBITIONS

Planning: Skip Plan Mode/BMAD for non-trivial • Skip GATE 1 (research) • Skip GATE 2 (save context) • <5 questions for C, <8 for D/E (GATE 3) • Skip deep research GATE 4 • Wrong plan path GATE 5 • Skip best-practices/Context7 • Code in planning
BMAD: Skip PM for 5+ files • Code without requirements • Skip Context7/best-practices/Explore
Implementation: Skip checks • Run npm run dev • console.error/log • Manual JWT • Destructive PROD SQL • No Cosmos tools • No AI refresh hook • Refetch storms • Hardcode tenant data
Context: Continue post-compact without plan file • Assume without asking • Web search for GitHub

📋 WORKFLOW

Commit checklist: tsc ✓ • security ✓ • console-error ✓ • react-query ✓ • Context7 ✓ • best-practices ✓ • Cosmos tools ✓ • AI refresh ✓ • Plan updated ✓ • Atomic commits ✓
Session start: Read knowledge.md, progress.md, package.json. Check .continue-here.md.
Doc updates: progress.md MAX 5 lines • knowledge.md MAX 10 lines (architectural only)
Limits: knowledge.md 500-800 (max 900) • progress.md 200-300 (max 400)

📚 PROJECT

Stack: Next.js 15 • React 19 • Supabase RLS • Gemini AI • WhatsApp Business API
Features: Kanban, client mgmt, AI bot, subscriptions, Google Forms
Tables (all org_id + RLS): organizations, organization_members, leads, clients, conversations, whatsapp_sessions, ai_bot_settings, subscriptions
Envs: DEV=cmg-crm-backup+STAGING • PROD=cmg-crm+PRODUCTION (git pull only)
Tools: Context7 (API docs) + Best Practices (patterns) — use BOTH

🆘 WHEN STUCK

Ask before speculating • EnterPlanMode for complex • PM for major features • Fix types before tests • Run supabase gen types • Read plan file • Use gh CLI

🤔 ASK FIRST

New npm deps • Schema changes • 5+ files • Deleting files • Architectural decisions

🔍 BEFORE CREATING

Search first: Glob: "src/components/**/*[pattern]*.tsx" • Grep: "export function [name]"
Decision: CUSTOMIZE existing (90%) vs CREATE new (10%)

---
Full details: .claude/knowledge.md • .claude/steering/*

_No response_