akanealw/Charon
1
0
Fork 0
Code Issues Pull Requests Actions 9 Packages Projects Releases Wiki Activity
Files
c4e8d6c8ae6efcf90f34b35912d6749c9d125cd1
Charon/CLAUDE.md
GitHub Actions 698ad86d17 chore: structured autonomy commands for planning, generating, and implementing features 
- Create sa-generate.md for generating implementation documentation from plans
- Create sa-implement.md for executing implementation plans step-by-step
- Create sa-plan.md for collaborating with users to design development plans
- Add security scan commands for CodeQL, Docker images, Go vulnerabilities, and GORM
- Implement SQL code review and optimization commands
- Add supply chain vulnerability remediation process
- Introduce backend and frontend test commands with coverage checks
- Update settings.json for command permissions
- Document governance, project overview, code quality rules, and critical architecture rules in CLAUDE.md
- Establish root cause analysis protocol and definition of done for development
2026-03-08 05:45:21 +00:00

205 lines
9.1 KiB
Markdown
Raw Blame History

# Charon — Claude Code Instructions
> **Governance Precedence** (highest → lowest)
> 1. `.github/instructions/**` files — canonical source of truth
> 2. `.claude/agents/**` files — agent-specific overrides
> 3. `SECURITY.md`, `docs/security.md`, `docs/features/**` — operator docs
When conflicts arise, the stricter security requirement always wins. Update downstream docs to match canonical text.
---
## Project Overview
Charon is a self-hosted web app for managing reverse proxy host configurations, aimed at novice users. Everything prioritises simplicity, usability, reliability, and security — delivered as a single binary + static assets with no external dependencies.
- **Backend**: `backend/cmd/api` → loads config, opens SQLite, hands off to `internal/server`
- **Frontend**: React app built to `frontend/dist`, mounted via `attachFrontend`
- **Config**: `internal/config` respects `CHARON_ENV`, `CHARON_HTTP_PORT`, `CHARON_DB_PATH`; creates `data/`
- **Models**: Persistent types in `internal/models`; GORM auto-migrates them
---
## Code Quality Rules
Every session should improve the codebase, not just add to it.
- **MANDATORY**: Before starting any task, read relevant files in `.github/instructions/` for that domain
- **ARCHITECTURE**: Consult `ARCHITECTURE.md` before changing core components, data flow, tech stack, deployment config, or directory structure
- **DRY**: Consolidate duplicate patterns into reusable functions/types after the second occurrence
- **CLEAN**: Delete dead code immediately — unused imports, variables, functions, commented blocks, console logs
- **LEVERAGE**: Use battle-tested packages over custom implementations
- **READABLE**: Maintain comments and clear naming for complex logic
- **CONVENTIONAL COMMITS**: Use `feat:`, `fix:`, `chore:`, `refactor:`, or `docs:` prefixes
---
## Critical Architecture Rules
- **Single Frontend Source**: All frontend code MUST reside in `frontend/`. NEVER create `backend/frontend/` or nested directories
- **Single Backend Source**: All backend code MUST reside in `backend/`
- **No Python**: Go (Backend) + React/TypeScript (Frontend) only
---
## Root Cause Analysis Protocol (MANDATORY)
**Never patch a symptom without tracing the root cause.**
Before any code change, build a mental map of the feature:
1. **Entry Point** — Where does the data enter? (API Route / UI Event)
2. **Transformation** — How is data modified? (Handlers / Middleware)
3. **Persistence** — Where is it stored? (DB Models / Files)
4. **Exit Point** — How is it returned to the user?
The error log is often the *victim*, not the *cause*. Search upstream callers to find the origin.
---
## Backend Workflow
- **Run**: `cd backend && go run ./cmd/api`
- **Test**: `go test ./...`
- **Lint (BLOCKING)**: `make lint-fast` or `make lint-staticcheck-only` — staticcheck errors block commits
- **Full lint** (before PR): `make lint-backend`
- **API Responses**: `gin.H{"error": "message"}` structured errors
- **JSON Tags**: All struct fields exposed to frontend MUST have `json:"snake_case"` tags
- **IDs**: UUIDs (`github.com/google/uuid`), generated server-side
- **Error wrapping**: `fmt.Errorf("context: %w", err)`
- **File paths**: Sanitise with `filepath.Clean`
---
## Frontend Workflow
- **Location**: Always work inside `frontend/`
- **Stack**: React 18 + Vite + TypeScript + TanStack Query
- **State**: `src/hooks/use*.ts` wrapping React Query
- **API Layer**: Typed clients in `src/api/*.ts` wrapping `client.ts`
- **Forms**: Local `useState` → `useMutation` → `invalidateQueries` on success
---
## Cross-Cutting Notes
- **VS Code**: Register new repetitive CLI actions in `.vscode/tasks.json`
- **Sync**: React Query expects exact JSON from GORM tags (snake_case) — keep API and UI aligned
- **Migrations**: When adding models, update `internal/models` AND `internal/api/routes/routes.go` (AutoMigrate)
- **Testing**: All new code MUST include unit tests
- **Ignore files**: Check `.gitignore`, `.dockerignore`, `.codecov.yml` when adding files/folders
---
## Documentation
Update `ARCHITECTURE.md` when changing: system architecture, tech stack, directory structure, deployment, security, integrations.
Update `docs/features.md` when adding capabilities (short marketing-style list only).
---
## CI/CD & Commit Conventions
- `feat:`, `fix:`, `perf:` → trigger Docker builds; `chore:` → skips builds
- `feature/beta-release` branch always builds
- History-rewrite PRs (touching `scripts/history-rewrite/`) MUST include checklist from `.github/PULL_REQUEST_TEMPLATE/history-rewrite.md`
---
## PR Sizing
Prefer smaller, reviewable PRs. Split when changes span backend + frontend + infra, or diff is large.
**Suggested PR sequence**:
1. Foundation PR (types/contracts/refactors, no behaviour change)
2. Backend PR (API/model/service + tests)
3. Frontend PR (UI integration + tests)
4. Hardening PR (security/CI/docs/follow-ups)
Each PR must remain deployable and pass DoD checks.
---
## Definition of Done (MANDATORY — in order)
1. **Playwright E2E** (run first): `cd /projects/Charon && npx playwright test --project=firefox`
- Scope to modified features; fix root cause before proceeding on failure
2. **GORM Security Scan** (conditional — if models/DB changed): `./scripts/scan-gorm-security.sh --check` — zero CRITICAL/HIGH
3. **Local Patch Coverage Preflight**: `bash scripts/local-patch-report.sh` — produces `test-results/local-patch-report.md`
4. **Security Scans** (zero high/critical):
- CodeQL Go: VS Code task "Security: CodeQL Go Scan (CI-Aligned)"
- CodeQL JS: VS Code task "Security: CodeQL JS Scan (CI-Aligned)"
- Trivy: VS Code task "Security: Trivy Scan"
5. **Lefthook**: `lefthook run pre-commit` — fix all errors immediately
6. **Staticcheck (BLOCKING)**: `make lint-fast` — must pass before commit
7. **Coverage (MANDATORY — 85% minimum)**:
- Backend: VS Code task "Test: Backend with Coverage" or `scripts/go-test-coverage.sh`
- Frontend: VS Code task "Test: Frontend with Coverage" or `scripts/frontend-test-coverage.sh`
8. **Type Safety** (frontend): `cd frontend && npm run type-check` — fix all errors
9. **Build verification**: `cd backend && go build ./...` + `cd frontend && npm run build`
10. **All tests pass**: `go test ./...` + `npm test`
11. **Clean up**: No `console.log`, `fmt.Println`, debug statements, or commented-out blocks
---
## Agents
Specialised subagents live in `.claude/agents/`. Invoke with `@agent-name` or let Claude Code route automatically based on task type:
| Agent | Role |
|---|---|
| `management` | Engineering Director — delegates all work, never implements directly |
| `planning` | Principal Architect — research, technical specs, implementation plans |
| `supervisor` | Code Review Lead — PR reviews, quality assurance |
| `backend-dev` | Senior Go Engineer — Gin/GORM/SQLite implementation |
| `frontend-dev` | Senior React/TypeScript Engineer — UI implementation |
| `qa-security` | QA & Security Engineer — testing, vulnerability assessment |
| `doc-writer` | Technical Writer — user-facing documentation |
| `playwright-dev` | E2E Testing Specialist — Playwright test automation |
| `devops` | DevOps Specialist — CI/CD, GitHub Actions, deployments |
## Commands
Slash commands in `.claude/commands/` — invoke with `/command-name`:
| Command | Purpose |
|---|---|
| `/create-implementation-plan` | Draft a structured implementation plan file |
| `/update-implementation-plan` | Update an existing plan |
| `/breakdown-feature` | Break a feature into implementable tasks |
| `/create-technical-spike` | Research a technical question |
| `/create-github-issues` | Generate GitHub issues from an implementation plan |
| `/sa-plan` | Structured Autonomy — planning phase |
| `/sa-generate` | Structured Autonomy — generate phase |
| `/sa-implement` | Structured Autonomy — implement phase |
| `/debug-web-console` | Debug browser console errors |
| `/playwright-explore` | Explore a website with Playwright |
| `/playwright-generate-test` | Generate a Playwright test |
| `/sql-code-review` | Review SQL / stored procedures |
| `/sql-optimization` | Optimise a SQL query |
| `/codecov-patch-fix` | Fix Codecov patch coverage gaps |
| `/supply-chain-remediation` | Remediate supply chain vulnerabilities |
| `/ai-prompt-safety-review` | Review AI prompt for safety/security |
| `/prompt-builder` | Build a structured AI prompt |
## Skills (Docker / Testing / Security)
Skill runner: `.github/skills/scripts/skill-runner.sh <skill-name>`
| Skill | Command |
|---|---|
| Start dev environment | `/docker-start-dev` |
| Stop dev environment | `/docker-stop-dev` |
| Rebuild E2E container | `/docker-rebuild-e2e` |
| Prune Docker resources | `/docker-prune` |
| Run all integration tests | `/integration-test-all` |
| Backend unit tests | `/test-backend-unit` |
| Backend coverage | `/test-backend-coverage` |
| Frontend unit tests | `/test-frontend-unit` |
| Frontend coverage | `/test-frontend-coverage` |
| E2E Playwright tests | `/test-e2e-playwright` |
| CodeQL scan | `/security-scan-codeql` |
| Trivy scan | `/security-scan-trivy` |
| Docker image scan | `/security-scan-docker-image` |
| GORM security scan | `/security-scan-gorm` |
| Go vulnerability scan | `/security-scan-go-vuln` |
Reference in New Issue View Git Blame Copy Permalink