diff --git a/.claude/onboarding/step0_preparation/01_code_conventions.md b/.claude/onboarding/step0_preparation/01_code_conventions.md new file mode 100644 index 00000000..fb8b7290 --- /dev/null +++ b/.claude/onboarding/step0_preparation/01_code_conventions.md @@ -0,0 +1,76 @@ +# Step 0 — Code Conventions & Rules + +Documentation of the rules and code conventions configured during the +Claude Code workspace setup (Step 0). + +## Context +- **Project:** MiroFish — Multi-Agent Swarm Intelligence Prediction Engine +- **Stack:** Python (Flask, uv) backend + Vue 3 / Vite frontend +- **Date applied:** 2026-05-06 + +## What Was Configured + +### 1. `.claude/settings.json` — Permissions +**Always allow (bash):** +- `cd:*` +- `ls:*` +- `find:*` +- `cat:*` +- `mkdir:*` + +**Always deny (Read / Write / Edit):** +- `*/.env*` +- `*/secrets/*` + +**Always deny (bash):** +- `rm -f*` +- `rm -rf*` +- `git push -f*` +- `git push --force*` + +This protects secrets and forbids destructive Git / filesystem +operations while allowing safe navigation and inspection commands. + +### 2. `.claude/rules/` — Rule Files + +| File | Purpose | +|------|---------| +| `markdown.md` | Adhere to standard Markdown syntax (markdownguide.org). | +| `file-paths.md` | Always wrap file paths in quotes; use a generic placeholder path in docs/examples. | +| `commits.md` | Conventional Commits standard; never add `Co-Authored-By:` watermarks. | +| `error-handling.md` | When an error occurs, offer to save it as a rule. | +| `dev-guidelines.md` | Salestech Products Development Guidelines (live source on Notion). | + +### 3. Salestech Development Guidelines +- **Notion source (authoritative):** https://candylabs.notion.site/development-guidelines +- A summary snapshot is stored in `.claude/rules/dev-guidelines.md`. +- Always consult the live document via the Notion MCP server for the + latest version. +- Snapshot covers: formatting & style, naming, comments, + Git workflow, React & TypeScript, Tailwind 4, folder structure, + accessibility, environments / secrets / dependencies, security, + infrastructure, enforcement. + +### 4. Commit Watermarks +- `Co-Authored-By:` blocks must **never** be added to commits + (matches §4.2 of the dev guidelines: *"Avoid 'watermarks' like + 'co-authored by Claude'"*). + +## Manual Setup Items (Not Automated) +The following items in Step 0 are user / environment setup and are +**not** performed by this onboarding pass — they must be completed by +the developer: + +1. **Claude Code clients** + - Claude Desktop, Claude Code CLI, VSCode extension +2. **MCP servers** (run from terminal, not from inside Claude) + - Notion: `claude mcp add --transport http notion https://mcp.notion.com/mcp` + - Atlassian: `claude mcp add --transport http atlassian https://mcp.atlassian.com/v1/mcp` + - Figma: `claude mcp add --transport http figma-remote-mcp https://mcp.figma.com/mcp` + - Authenticate each via `/mcp` in Claude after restart. +3. **Basics** + - Node.js (https://nodejs.org/en) — required for CC-SDD. + - Git + GitHub CLI (`gh auth login`) — required for PRs. + +## Next +- Step 1: Prepare the codebase (CLAUDE.md, README.md, structure) diff --git a/.claude/rules/commits.md b/.claude/rules/commits.md new file mode 100644 index 00000000..fbced959 --- /dev/null +++ b/.claude/rules/commits.md @@ -0,0 +1,47 @@ +# Commit Rules + +Whenever committing, use the **Conventional Commits** standard. + +## Format +``` +(): + + + + +``` + +## Types +- `feat` — A new feature +- `fix` — A bug fix +- `docs` — Documentation only changes +- `style` — Changes that do not affect meaning (whitespace, formatting) +- `refactor` — Code change that neither fixes a bug nor adds a feature +- `test` — Adding or correcting tests +- `chore` — Build process, tooling, configuration +- `ci` — CI / CD configuration changes +- `perf` — Performance improvement + +## Rules +- **Type** is required and must be lowercase. +- **Summary** must be lowercase, in imperative mood, max 72 characters, + no trailing period. +- **Body** (if present) explains *what* and *why*, not *how*. +- **Footer** can reference tickets (e.g., `Closes PROJ-1234`). +- **Never** add a `Co-Authored-By:` block (no Claude/AI watermarks). +- Avoid mixing unrelated changes in a single commit. +- Never commit secrets, credentials, or environment files. + +## Examples +``` +feat(auth): add two-factor authentication flow + +Implements TOTP-based 2FA using the authenticator app. +Users can enable/disable 2FA from their security settings. + +Closes PROJ-1234 +``` + +``` +fix(cart): prevent duplicate items on rapid clicks +``` diff --git a/.claude/rules/dev-guidelines.md b/.claude/rules/dev-guidelines.md new file mode 100644 index 00000000..83152cab --- /dev/null +++ b/.claude/rules/dev-guidelines.md @@ -0,0 +1,131 @@ +# Salestech Products Development Guidelines + +Always obey the **Salestech Products Development Guidelines**. These are +enforceable rules — non-compliant code will be rejected during review. + +## Source +- Notion (Live, authoritative): https://candylabs.notion.site/development-guidelines +- Connect via Notion MCP server (HTTP requires JS, so MCP is the only reliable way). +- Always consult the live document for the latest version. + +## Summary (snapshot — refer to live doc for authority) + +### 1. Code Formatting & Style +- 4 spaces indentation (JS/TS and Python). No tabs. +- Max **120 chars** per line. +- No trailing whitespace; files end with a single newline. +- JS/TS: no semicolons (`semi: false`), single quotes, trailing commas + where valid in ES5, omit parens around single arrow params. +- Python: double quotes for strings. +- Tools: Prettier + ESLint (JS/TS, npm); Ruff (Python, uv). + +### 2. Naming +- JS/TS: `camelCase` vars/funcs, `PascalCase` classes/types/enums, + `UPPER_SNAKE_CASE` constants, `kebab-case` filenames, boolean prefixes + `is`/`has`/`should`. +- Python: `snake_case` vars/funcs/files, `PascalCase` classes, + `UPPER_SNAKE_CASE` constants, `_leading_underscore` private. +- No abbreviations (except `id`, `url`, `http`). +- No single-letter vars (except short lambda / loop indices). +- No Hungarian notation. + +### 3. Comments & Documentation +- Don't comment the obvious — comment the *why*. +- `TODO:` / `FIXME:` must include a ticket reference. +- JS/TS: JSDoc on all exported functions, classes, interfaces. +- Python: Google-style docstrings on all public funcs/classes/modules. + +### 4. Git Workflow +- Branch: `/-` (`feat`, `fix`, + `chore`, `docs`, `hotfix`). +- Commits: **Conventional Commits**, lowercase, imperative, max 72 chars, + no period, no `Co-Authored-By:` watermarks. +- PRs: linked to a ticket, ≥1 human approval, all CI checks pass, + squash-merge feature branches, delete source branch after merge. +- Never commit directly to `main` / `dev`; never force-push shared + branches; never commit secrets. + +### 5. React & TypeScript +- Component file order: imports → types → constants → helpers → + component. +- Named exports only; function declarations for components. +- Props types named `Props`; never `React.FC`. +- Hooks start with `use`; never call hooks conditionally. +- React Router v7: file/config-based routes (don't mix), use + `loader`/`action`, `useNavigate`, `useSearchParams`, ``, + ``. +- TanStack Query: centralized query key factories, never `fetch`/`axios` + in components, always handle loading/success/error, prefer + `invalidateQueries` over manual cache. +- State priority: URL → TanStack Query → component state → Context. + Never duplicate server state into local state. + +### 6. Tailwind 4 (CSS-only config) +- Component styles inline as Tailwind classes; no separate CSS modules + per component. +- Use `clsx` for dynamic classes. +- Mobile-first responsive prefixes. +- `prettier-plugin-tailwindcss` ordering required. +- No `!important` (Tailwind `!`) without justification + comment. +- `main.css` only for `@import`, `@theme`, global base styles, third- + party overrides. + +### 7. Folder Structure +- Layer-based for frontend (`api/`, `components/`, `hooks/`, + `pages/`, `queries/`, `routes/`, `types/`, `utils/`). +- FastAPI: `routers/`, `models/`, `schemas/`, `services/`; Pydantic + `BaseSettings`; business logic in services not routers. +- Django: `config/`, `apps//`, `common/`; one app per domain; + business logic in `services.py`; max one migration per app per PR; + custom User model from day 1. +- Django templates: `snake_case.html` in `templates//`, + partials prefixed `_`, `{% extends %}` mandatory, DjHTML formatter, + `{% url %}` for all URLs. +- Root directory: configuration files only. +- README.md mandatory (setup, env vars, run/test). + +### 8. Accessibility +- WCAG 2.1 Level AA. +- Semantic HTML; one `

` per page; no skipped heading levels. +- All images need `alt`; decorative use `alt=""`. +- 4.5:1 / 3:1 contrast minimums. +- Every form input: visible `