# Guidelines

> Development guidelines - security, code quality, git workflow, Docker rules

- Skill: `eron1703/guidelines` (Agent Skill)
- Install (CLI): `npx skillmds@latest add eron1703/guidelines`
- Raw SKILL.md: https://api.skillmd.com/api/skills/eron1703/guidelines/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: eron1703 (https://skillmd.com/u/eron1703)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/eron1703/guidelines

---


# Development Guidelines

## Skill Scoping Rules

**CRITICAL: Generic skills and project-specific skills are NOT the same.**

### Generic Infrastructure Skills (apply to ALL projects)
- ports, databases, servers, repos, cicd, credentials, environment, guidelines, save, project, supervisor, testing
- These describe the local development environment, shared infrastructure, and general workflows

### Project-Specific Skills (apply ONLY to their project)
- `flowmaster-*` skills apply ONLY when working on FlowMaster (`~/projects/flowmaster/`)
- Do NOT use FlowMaster skills when working on other projects
- Do NOT confuse project-specific databases, ports, or env vars with generic infrastructure config

### Override Rules
- Project-specific skills override generic skills where they conflict
- Generic skills still apply for shared infrastructure (Docker rules, git workflow, security)

---

## 1. Security Rules

### Credentials Management
- NEVER hardcode credentials in source code
- Use environment variables for all secrets
- Use `.env` files with `.env.example` templates
- All `.env` files must be in `.gitignore`

### Input Validation & Injection Prevention
- Parameterized queries for all database operations
- Validate all user input at system boundaries
- Never trust external API responses - validate schemas

### Data Protection
- Hash passwords with bcrypt or argon2
- Never log sensitive data
- Use HTTPS for all external communications
- Implement CORS properly - whitelist specific origins

## 2. Code Quality Standards

### Development Approach
- Implement only what's requested - no over-engineering
- No scope creep
- Delete unused code immediately
- STRICTLY FORBIDDEN: No mock functionality
- Self-documenting code with clear names

### Type Safety
- Type hints on all Python functions
- TypeScript interfaces/types for all components
- Use Pydantic models for FastAPI validation
- Never use `any` in TypeScript

### Code Organization
- Small focused functions (single responsibility, max 50 lines)
- Max 3 levels of nesting
- Named constants for magic numbers/strings

## 3. Architecture Patterns

### Python/FastAPI Backend
- Use async/await for all I/O
- Dependency injection via Depends()
- Structured logging with context
- Consistent error response format
- Pydantic models for validation
- Version APIs explicitly (/api/v1/)

### React/TypeScript Frontend
- Functional components only
- React Query for server state
- No inline styles
- Custom hooks for reusable logic

### API Design
- RESTful conventions
- Consistent JSON response: `{success, data, error}`
- Proper HTTP status codes
- Pagination for list endpoints

## 4. Docker/Container Rules

- NEVER shut down Docker/OrbStack globally
- Check container status before operations
- Use named volumes for persistent data
- Health checks for all services
- Specific image tags (not latest)
- Multi-stage builds, non-root user
- Check port availability: `lsof -i :PORT`

## 5. Git & Version Control

### Commit Practices
- Atomic commits, conventional commit messages
- Never force push to main/master
- PR reviews required

### Branch Strategy
- main (production), develop (integration), feature/*, bugfix/*, docs/*

## 6. Error Handling
- Let exceptions bubble up to framework handlers
- Structured logging with context (user_id, request_id)
- Consistent error format to clients
- Never log sensitive data

## 7. Testing Strategy
- Unit tests: individual functions in isolation
- Integration tests: multiple components together
- E2E tests: full user workflows
- 80%+ coverage, 100% on critical paths

---

## 8. UI Design Rules (CRITICAL — ENFORCED)

These rules are non-negotiable for all FlowMaster frontend work. Violations must be fixed before deployment.

### ❌ NO Dashboards
- Do NOT build dashboard-style layouts (KPI card grids, metric panels, summary widgets)
- Dashboards are explicitly banned — they waste space and add no functional value
- Exception: only if a dashboard is explicitly requested by the user by name

### ❌ NO Meaningless Colors
- Only use colors with a **defined semantic meaning** from the design token system:
  - `--success` / green = pass, active, healthy
  - `--warning` / amber = warn, pending, degraded
  - `--danger` / red = fail, error, critical
  - `--brand` / `--brand-accent` = primary actions, active navigation
  - `--text`, `--text-secondary`, `--text-muted` = text hierarchy
  - `--bg`, `--bg-subtle`, `--bg-hover` = backgrounds
- **NEVER** use arbitrary hex colors, ad-hoc Tailwind color classes (e.g. `text-purple-500`, `bg-teal-100`) without explicit semantic justification
- If a color has no clear defined meaning in the token system, **do not use it**

### ❌ NO Theme Deviation
- Always use the defined theme token variables — never hardcode colors
- In Tailwind: use semantic classes only (`text-gray-900`, `border-gray-200` are acceptable as they map to theme tokens); no decorative colors
- Dark mode must use the `dark:` variant consistently — no light-only implementations
- Do not introduce new color schemes, gradients, or decorative palette choices

### ❌ NO Icons Unless Requested
- Do NOT add icons to UI elements unless the user explicitly asks for them
- Icons already present in existing code may be kept; do not add new ones
- Exception: navigation/sidebar icons are part of the established structure and may remain
- When in doubt: **text is better than an icon**

---

**Note:** Project-specific rules (CLAUDE.md) override these global guidelines.