diff --git a/.agents/hooks/scripts/check-agent-doc-clean.sh b/.agents/hooks/scripts/check-agent-doc-clean.sh new file mode 100755 index 00000000..6d322be6 --- /dev/null +++ b/.agents/hooks/scripts/check-agent-doc-clean.sh @@ -0,0 +1,15 @@ +#!/usr/bin/env bash +set -euo pipefail + +if [[ "$#" -eq 0 ]]; then + set -- AGENTS.md frontend/AGENTS.md backend/AGENTS.md docs/agents +fi + +pattern='/dev/null; then + echo "BLOCK: generated agent catalog markers found" >&2 + exit 1 +fi + +echo "CONTINUE: no generated agent catalog markers found" diff --git a/.agents/hooks/scripts/enforce-agent-doc-branch.sh b/.agents/hooks/scripts/enforce-agent-doc-branch.sh new file mode 100755 index 00000000..6311d863 --- /dev/null +++ b/.agents/hooks/scripts/enforce-agent-doc-branch.sh @@ -0,0 +1,30 @@ +#!/usr/bin/env bash +set -euo pipefail + +branch="$(git branch --show-current 2>/dev/null || true)" + +if [[ "$branch" == "docs/concise-agents-md" ]]; then + exit 0 +fi + +if [[ "$branch" == agents/* ]]; then + exit 0 +fi + +protected_regex='(^|/)(AGENTS\.md)$|^docs/agents/|^\.agents/hooks/' + +changed="$(git diff --name-only --cached 2>/dev/null; git diff --name-only 2>/dev/null)" + +if printf '%s\n' "$changed" | grep -E "$protected_regex" >/dev/null; then + cat >&2 < branch. + +Current branch: ${branch:-unknown} + +Protected files require a separate self-learning branch and PR: +- AGENTS.md files +- docs/agents/** +- .agents/hooks/** +EOF + exit 1 +fi diff --git a/.agents/hooks/scripts/read-agents.sh b/.agents/hooks/scripts/read-agents.sh new file mode 100755 index 00000000..7481dc98 --- /dev/null +++ b/.agents/hooks/scripts/read-agents.sh @@ -0,0 +1,57 @@ +#!/usr/bin/env bash +# read-agents.sh — Session-start hook that guarantees the agent sees root +# AGENTS.md followed by machine-local agent preferences. +# +# Default output is JSON with hookSpecificOutput.additionalContext for +# cross-platform compatibility (Claude Code, VS Code, Cursor, Codex, Pi). +# Use --plain for raw text output (direct execution, OpenCode plugin). +set -euo pipefail + +script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +agents_dir="$(cd "$script_dir/../.." && pwd)" +project_root="$(cd "$agents_dir/.." && pwd)" + +sections=() + +# 1. Root AGENTS.md — sibling of .agents/, guarantee the agent reads it +root_agents="$project_root/AGENTS.md" +if [[ -f "$root_agents" ]]; then + sections+=("$(cat "$root_agents")") +fi + +# 2. Local agent preferences — inside .agents/local/ +local_agents="$agents_dir/local/AGENTS.local.md" +if [[ -f "$local_agents" ]]; then + sections+=("--- BEGIN .agents/local/AGENTS.local.md --- +$(cat "$local_agents") +--- END .agents/local/AGENTS.local.md ---") +fi + +if [[ ${#sections[@]} -eq 0 ]]; then + exit 0 +fi + +output="" +for i in "${!sections[@]}"; do + if [[ $i -gt 0 ]]; then + output+=$'\n\n' + fi + output+="${sections[$i]}" +done + +# Plain text mode +if [[ "${1:-}" == "--plain" ]]; then + printf '%s\n' "$output" + exit 0 +fi + +# JSON output for hook platforms +if command -v jq &>/dev/null; then + escaped=$(printf '%s' "$output" | jq -Rs .) +elif command -v python3 &>/dev/null; then + escaped=$(python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))' <<< "$output") +else + escaped="\"$(printf '%s' "$output" | sed 's/\\/\\\\/g; s/"/\\"/g; s/$/\\n/' | tr -d '\n')\"" +fi + +printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":%s}}\n' "$escaped" diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 00000000..78316921 --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,15 @@ +{ + "hooks": { + "SessionStart": [ + { + "matcher": "startup", + "hooks": [ + { + "type": "command", + "command": "${CLAUDE_PROJECT_DIR}/.agents/hooks/scripts/read-agents.sh" + } + ] + } + ] + } +} diff --git a/.codex/hooks.json b/.codex/hooks.json new file mode 100644 index 00000000..1596d86c --- /dev/null +++ b/.codex/hooks.json @@ -0,0 +1,15 @@ +{ + "hooks": { + "SessionStart": [ + { + "matcher": "startup|resume", + "hooks": [ + { + "type": "command", + "command": ".agents/hooks/scripts/read-agents.sh" + } + ] + } + ] + } +} diff --git a/.cursor/hooks.json b/.cursor/hooks.json new file mode 100644 index 00000000..64e989da --- /dev/null +++ b/.cursor/hooks.json @@ -0,0 +1,10 @@ +{ + "version": 1, + "hooks": { + "sessionStart": [ + { + "command": ".agents/hooks/scripts/read-agents.sh" + } + ] + } +} diff --git a/.gitignore b/.gitignore index 5848ec3d..5cd6116f 100644 --- a/.gitignore +++ b/.gitignore @@ -59,6 +59,7 @@ pids # npm cache .npm +.pi/npm/ # eslint cache .eslintcache @@ -84,6 +85,9 @@ plans/ # .agent-workspace/ files are tracked so samples/artifacts survive across sessions .agent/ +# Machine-local agent preferences +.agents/local/ + @@ -93,7 +97,7 @@ plans/ .secrets.baseline # Cursor -.cursor/ +.cursor/* # Environment files (catch-all) .env @@ -150,13 +154,16 @@ supabase/.env !backend/pyrightconfig.json !backend/tests/**/assets/*.json !frontend/.fallowrc.json +!.claude/settings.json +!.codex/hooks.json # Upload directories uploads/ temp-uploads/ # Cursor -.cursor/ +.cursor/* +!.cursor/hooks.json # Votecatcher data files (contain sensitive batch/API data) Votecatcher/ diff --git a/.opencode/plugins/local-agents.js b/.opencode/plugins/local-agents.js new file mode 100644 index 00000000..0c4b63b9 --- /dev/null +++ b/.opencode/plugins/local-agents.js @@ -0,0 +1,24 @@ +export const LocalAgentsPlugin = async ({ $, client }) => { + return { + event: async ({ event }) => { + if (event.type !== "session.created") return + + try { + const result = await $`.agents/hooks/scripts/read-agents.sh --plain` + const output = (await result.text()).trim() + if (!output) return + + await client.app.log({ + body: { + service: "read-agents", + level: "info", + message: "AGENTS.md and local preferences loaded. See hook output for details.", + extra: { content: output }, + }, + }) + } catch { + // Script not found — silent exit + } + }, + } +} diff --git a/.pi/hook/hooks.yaml b/.pi/hook/hooks.yaml new file mode 100644 index 00000000..8811b0ec --- /dev/null +++ b/.pi/hook/hooks.yaml @@ -0,0 +1,4 @@ +hooks: + - event: session.created + actions: + - bash: .agents/hooks/scripts/read-agents.sh diff --git a/AGENTS.md b/AGENTS.md index a0a6636d..7e2622c7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,608 +1,94 @@ -This is EXTREMELY IMPORTANT: +# VoteCatcher -- Don't flatter me. Be charming and nice, but very honest. Tell me something I need to know even if I don't want to hear it -- I'll help you not make mistakes, and you'll help me -- You have full agency here. Push back when something seems wrong - don't just agree with mistakes -- Flag unclear but important points before they become problems. Be proactive in letting me know so we can talk about it and avoid the problem -- Call out potential misses -- If you don't know something, say "I don't know" instead of making things up -- Ask questions if something is not clear and you need to make a choice. Don't choose randomly if it's important for what we're doing -- When you show me a potential error or miss, start your response with❗️emoji +Open source ballot signature recognition for grassroots campaigns. -## Active Work +Stack: Python/FastAPI backend, SvelteKit 5 frontend, SQLModel/Alembic data layer, Docker/just for local workflow. -**`.crosslink/handover.md`** — single source of truth for session handoff. Read this first when starting a new session. +## Agent Contract -## Version Bumping +- Be honest and direct. Push back when something seems wrong. +- Flag unclear but important choices before making them. +- Say `I don't know` when evidence is missing. +- Start with `❗️` when calling out a likely error, miss, or risk. +- Do not invent project facts. Read the source or docs first. -Version is stored in two files and must stay in sync: +## First Reads -- `backend/pyproject.toml` → `project.version` -- `frontend/package.json` → `version` +- After reading this file, run `.agents/hooks/scripts/read-agents.sh --plain` to load any machine-local preferences from `.agents/local/AGENTS.local.md`. +- For project overview, read `README.md`. +- For setup and commands, read `docs/development/README.md` and `docs/running-locally.md`. +- For architecture changes, read `docs/architecture/README.md` and relevant ADRs in `docs/architecture/decisions/`. +- For project layout, read `docs/architecture/project-structure.md`. -### Commands +## Core Commands -| Command | Purpose | -|---------|---------| -| `just version` | Show current version | -| `just version-set ` | Set version in all files (e.g. `just version-set 1.0.0-alpha.3`) | -| `just release` | Auto-bump via commitizen (conventional commits since last tag) | -| `just release-force ` | Force bump (patch/minor/major) | -| `just release-prerelease` | Bump prerelease suffix (alpha → beta → rc) | -| `just release-stable` | Drop prerelease suffix for stable release | +- List tasks: `just` +- Install dependencies: `just install` +- Run all tests: `just test` +- Lint: `just lint` +- Typecheck: `just typecheck` +- Local CI simulation: `just ci-sim` -### Workflow +Prefer narrower package commands while iterating, then run the broader check before claiming completion. -1. Set version: `just version-set 1.0.0-alpha.3` -2. Verify: `just version` and check both files -3. Commit: `git commit -am "chore: bump version to 1.0.0-alpha.3"` -4. CI auto-detects version change on `main` push, creates git tag, triggers release workflow (`release.yml`) +## Sources Of Truth -### Changelog +| Topic | Source | +| --- | --- | +| Product overview | `README.md` | +| Local development | `docs/development/README.md`, `docs/running-locally.md` | +| Architecture | `docs/architecture/` | +| Project structure | `docs/architecture/project-structure.md` | +| API contract | `backend/openapi.yaml`, `backend/app/routers/` | +| Database schema | `docs/database/`, `backend/alembic/` | +| Testing | `docs/development/testing.md` | +| Versioning | `docs/development/versioning.md` | -Changelogs are generated by **git-cliff** (`cliff.toml` in project root). Commitizen handles version bumping only (`update_changelog_on_bump = false`). +## Agent-Specific Guidance -| Command | Purpose | -|---------|---------| -| `just changelog` | Generate raw changelog from conventional commits → `CHANGELOG.md` | -| `just changelog-range v1..v2` | Preview changelog for a tag range | -| `just changelog-preview` | Preview unreleased changes | +- Code quality: `docs/agents/code-quality.md` +- Version and changelog work: `docs/agents/versioning.md` +- Frontend/Svelte MCP: `docs/agents/svelte-mcp.md` +- Local preferences: `docs/agents/local-preferences.md`; loaded by `.agents/hooks/scripts/read-agents.sh` when `.agents/local/AGENTS.local.md` exists. -**Agent summarization** — When an agent runs a release, after `just release` + `just changelog`: -1. Read the raw `CHANGELOG.md` (git-cliff output, grouped by commit type) -2. For each version section, rewrite with thematic grouping: - - Collapse related commits into narrative entries (e.g., "Added crop image feature with lightbox, thumbnails, and progressive reveal") - - Keep technical scope prefixes for precision - - Use user-facing language where possible -3. Write summarized `CHANGELOG.md` -4. Commit: `git commit -am "docs: summarize changelog for "` +Read these only when relevant to the current task. -This step is optional — humans can use raw git-cliff output directly. +## Skills -### Version Files +`find-skills` is a core project skill. Use it when specialized help may exist. -When adding a new package to the repo, ensure its version is added to the `version-set` recipe in `justfile`. +- Search: `npx skills find ` or `bunx skills find ` +- Inspect options before installing. +- Install project skills for Universal: + `npx skills add --skill -a universal -y` -## Code Quality +Do not embed generated skill catalogs in `AGENTS.md`. -Project-wide standards for readability, testing, and refactoring. Every session, every language, every epic. +## Self-Learning -### Readability-First Python (PEP 20 / Hitchhiker's Guide) +At task end, if you discovered a durable project-specific rule, pitfall, command, convention, or stale instruction, propose a learning update. -Apply these patterns when reading or writing Python in this project: +Strict filter: +- Keep durable project knowledge likely useful across future sessions. +- Skip task trivia, temporary state, one-off debugging notes, and generic coding advice. -- **Flat over nested** — Guard clauses and early returns over deep if/else nesting. -- **`filter(None, ...) + join`** — `' '.join(filter(None, [first, last]))` is idiomatic for building delimited strings from optional parts. Prefer over imperative append loops. -- **Extract before duplicating** — When you see the same 5-line block twice, extract a shared helper. Don't wait for a third occurrence. -- **Ternary for two-branch defaults** — `value if condition else default` over 4-line if/else. Reserve if/else for branches with side effects or complex logic. -- **Dead wrappers are dead weight** — If a method just delegates to another with no added logic, remove it and call the target directly. -- **Constants over inline literals** — Class-level constants over repeated inline lists/strings. Named constants are searchable, DRY, and self-documenting. +Before editing learning docs: +1. Ask the user first. +2. Create a separate branch named `agents/`. +3. Open a separate PR for the AGENTS/docs-agent update. +4. Do not mix self-learning changes into feature branches. -### Legacy Refactoring +## Agent Hook Contract -When touching existing code, apply small safe cleanups in the same commit. Don't expand scope — only refactor what's already being modified. Leave the neighbourhood cleaner than you found it. Specific techniques: +Agent hook scripts live in `.agents/hooks/scripts/`. -- Flatten nested ifs to guards/ternary -- Replace `isinstance` chains with dispatched helpers -- Extract repeated conditionals into shared functions -- Remove dead wrappers and unused imports +Agents must treat these scripts as project contracts. Individual platforms should configure their hook/plugin systems to call the scripts directly. -### Test Discipline +If changing `AGENTS.md` or `docs/agents/**`, branch name must start with `agents/` unless this is the initial approved rewrite branch. -Tests assert **behavioral contracts** (what), not **implementation details** (how): +## Worktree Safety -- No asserting specific internal method calls (e.g., `yield_per(1000)` mock) -- No `repr(type(...))` string checks -- No coupling to return type structure beyond the public contract (iterable vs tuple vs generator is irrelevant if it yields the same values) -- Prefer asserting "X must not happen" (e.g., `.all()` never called) over "X must happen via method Y" - -### Nesting Watch - -Watch for deeply nested if/else in loops. Prefer ternary, guard, or early-return patterns. When you see 3+ levels of nesting in a loop body, pause and flatten before continuing. Re-check after any refactoring that changes loop structure. - - - -## Available Skills - - - -When users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively. Skills provide specialized capabilities and domain knowledge. - -How to use skills: -- Invoke: `npx openskills read ` (run in your shell) - - For multiple: `npx openskills read skill-one,skill-two` -- The skill content will load with detailed instructions on how to complete the task -- Base directory provided in output for resolving bundled resources (references/, scripts/, assets/) - -Usage notes: -- Only use skills listed in below -- Do not invoke a skill that is already loaded in your context -- Each skill invocation is stateless - - - - - -accessibility-compliance -Implement WCAG 2.2 compliant interfaces with mobile accessibility, inclusive design patterns, and assistive technology support. Use when auditing accessibility, implementing ARIA patterns, building for screen readers, or ensuring inclusive user experiences. -project - - - -api-design-principles -Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers. Use when designing new APIs, reviewing API specifications, or establishing API design standards. -project - - - -architecture-decision-records -Write and maintain Architecture Decision Records (ADRs) following best practices for technical decision documentation. Use when documenting significant technical decisions, reviewing past architectural choices, or establishing decision processes. -project - - - -architecture-patterns -Implement proven backend architecture patterns including Clean Architecture, Hexagonal Architecture, and Domain-Driven Design. Use when architecting complex backend systems or refactoring existing applications for better maintainability. -project - - - -attack-tree-construction -Build comprehensive attack trees to visualize threat paths. Use when mapping attack scenarios, identifying defense gaps, or communicating security risks to stakeholders. -project - - - -auth-implementation-patterns -Master authentication and authorization patterns including JWT, OAuth2, session management, and RBAC to build secure, scalable access control systems. Use when implementing auth systems, securing APIs, or debugging security issues. -project - - - -bash-defensive-patterns -Master defensive Bash programming techniques for production-grade scripts. Use when writing robust shell scripts, CI/CD pipelines, or system utilities requiring fault tolerance and safety. -project - - - -bats-testing-patterns -Master Bash Automated Testing System (Bats) for comprehensive shell script testing. Use when writing tests for shell scripts, CI/CD pipelines, or requiring test-driven development of shell utilities. -project - - - -brainstorming -"You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation." -project - - - -changelog-automation -Automate changelog generation from commits, PRs, and releases following Keep a Changelog format. Use when setting up release workflows, generating release notes, or standardizing commit conventions. -project - - - -code-review-excellence -Master effective code review practices to provide constructive feedback, catch bugs early, and foster knowledge sharing while maintaining team morale. Use when reviewing pull requests, establishing review standards, or mentoring developers. -project - - - -context-driven-development ->- -project - - - -data-storytelling -Transform data into compelling narratives using visualization, context, and persuasive structure. Use when presenting analytics to stakeholders, creating data reports, or building executive presentations. -project - - - -debugging-strategies -Master systematic debugging techniques, profiling tools, and root cause analysis to efficiently track down bugs across any codebase or technology stack. Use when investigating bugs, performance issues, or unexpected behavior. -project - - - -dependency-upgrade -Manage major dependency version upgrades with compatibility analysis, staged rollout, and comprehensive testing. Use when upgrading framework versions, updating major dependencies, or managing breaking changes in libraries. -project - - - -deployment-pipeline-design -Design multi-stage CI/CD pipelines with approval gates, security checks, and deployment orchestration. Use when architecting deployment workflows, setting up continuous delivery, or implementing GitOps practices. -project - - - -design-system-patterns -Build scalable design systems with design tokens, theming infrastructure, and component architecture patterns. Use when creating design tokens, implementing theme switching, building component libraries, or establishing design system foundations. -project - - - -detect-language -Use when starting work on a project to detect the primary programming language and tooling. Use before running build, test, or lint commands. -project - - - -dispatching-parallel-agents -Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies -project - - - -doc-coauthoring -Guide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. -project - - - -e2e-testing-patterns -Master end-to-end testing with Playwright and Cypress to build reliable test suites that catch bugs, improve confidence, and enable fast deployment. Use when implementing E2E tests, debugging flaky tests, or establishing testing standards. -project - - - -error-handling-patterns -Master error handling patterns across languages including exceptions, Result types, error propagation, and graceful degradation to build resilient applications. Use when implementing error handling, designing APIs, or improving application reliability. -project - - - -executing-plans -Use when you have a written implementation plan to execute in a separate session with review checkpoints -project - - - -finishing-a-development-branch -Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanup -project - - - -git-advanced-workflows -Master advanced Git workflows including rebasing, cherry-picking, bisect, worktrees, and reflog to maintain clean history and recover from any situation. Use when managing complex Git histories, collaborating on feature branches, or troubleshooting repository issues. -project - - - -github-actions-templates -Create production-ready GitHub Actions workflows for automated testing, building, and deploying applications. Use when setting up CI/CD with GitHub Actions, automating development workflows, or creating reusable workflow templates. -project - - - -interaction-design -Design and implement microinteractions, motion design, transitions, and user feedback patterns. Use when adding polish to UI interactions, implementing loading states, or creating delightful user experiences. -project - - - -memory-safety-patterns -Implement memory-safe programming with RAII, ownership, smart pointers, and resource management across Rust, C++, and C. Use when writing safe systems code, managing resources, or preventing memory bugs. -project - - - -monorepo-management -Master monorepo management with Turborepo, Nx, and pnpm workspaces to build efficient, scalable multi-package repositories with optimized builds and dependency management. Use when setting up monorepos, optimizing builds, or managing shared dependencies. -project - - - -multi-reviewer-patterns -Coordinate parallel code reviews across multiple quality dimensions with finding deduplication, severity calibration, and consolidated reporting. Use this skill when organizing multi-reviewer code reviews, calibrating finding severity, or consolidating review results. -project - - - -parallel-debugging -Debug complex issues using competing hypotheses with parallel investigation, evidence collection, and root cause arbitration. Use this skill when debugging bugs with multiple potential causes, performing root cause analysis, or organizing parallel investigation workflows. -project - - - -parallel-feature-development -Coordinate parallel feature development with file ownership strategies, conflict avoidance rules, and integration patterns for multi-agent implementation. Use this skill when decomposing features for parallel development, establishing file ownership boundaries, or managing integration between parallel work streams. -project - - - -python-core -Use when working with Python projects, setting up Python development environments, or needing guidance on modern Python practices (3.13+), package management with uv, type hints, or tooling configuration. -project - - - -python-linting -Use when encountering linting errors, code quality issues, style violations, or needing to configure ruff/flake8/pylint. Essential for maintaining code consistency and catching potential bugs early. -project - - - -python-pytest -Use when writing Python tests, encountering test failures, setting up pytest, configuring fixtures, parametrization, mocking, coverage, or organizing test suites. Essential for TDD and test-driven development. -project - - - -python-type-checking -Use when encountering type errors, setting up type checking, configuring basedpyright/mypy/pyright, or needing guidance on type hints, generics, protocols, or gradual typing adoption strategies. -project - - - -risk-metrics-calculation -Calculate portfolio risk metrics including VaR, CVaR, Sharpe, Sortino, and drawdown analysis. Use when measuring portfolio risk, implementing risk limits, or building risk monitoring systems. -project - - - -sast-configuration -Configure Static Application Security Testing (SAST) tools for automated vulnerability detection in application code. Use when setting up security scanning, implementing DevSecOps practices, or automating code vulnerability detection. -project - - - -secrets-management -Implement secure secrets management for CI/CD pipelines using Vault, AWS Secrets Manager, or native platform solutions. Use when handling sensitive credentials, rotating secrets, or securing CI/CD environments. -project - - - -security-auth -Use when implementing authentication or authorization. Covers OAuth, JWT, session management, password handling, MFA, and access control patterns. -project - - - -security-core -Use when writing or modifying code. Apply OWASP secure coding principles automatically. This skill is always active. -project - - - -security-crypto -Use when implementing encryption, hashing, or cryptographic operations. Covers symmetric/asymmetric encryption, hashing, TLS, certificates, and key management. -project - - - -security-dependencies -Use when managing dependencies or checking for vulnerabilities. Covers dependency scanning, CVE management, supply chain security, and update strategies. -project - - - -security-requirement-extraction -Derive security requirements from threat models and business context. Use when translating threats into actionable requirements, creating security user stories, or building security test cases. -project - - - -security-review -Use when reviewing code for security vulnerabilities or performing security audits. -project - - - -security-secrets -Use when handling API keys, passwords, tokens, or other sensitive credentials. Covers secrets management, environment variables, vaults, and rotation strategies. -project - - - -security-testing -Use when testing code for security vulnerabilities. Covers SAST, DAST, dependency scanning, fuzzing, and penetration testing. -project - - - -shellcheck-configuration -Master ShellCheck static analysis configuration and usage for shell script quality. Use when setting up linting infrastructure, fixing code issues, or ensuring script portability. -project - - - -skill-creator -Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, update or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. -project - - - -stride-analysis-patterns -Apply STRIDE methodology to systematically identify threats. Use when analyzing system security, conducting threat modeling sessions, or creating security documentation. -project - - - -subagent-driven-development -Use when executing implementation plans with independent tasks in the current session -project - - - -systematic-debugging -Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes -project - - - -test-driven-development -Use when implementing any feature or bugfix, before writing implementation code -project - - - -theme-factory -Toolkit for styling artifacts with a theme. These artifacts can be slides, docs, reportings, HTML landing pages, etc. There are 10 pre-set themes with colors/fonts that you can apply to any artifact that has been creating, or can generate a new theme on-the-fly. -project - - - -threat-mitigation-mapping -Map identified threats to appropriate security controls and mitigations. Use when prioritizing security investments, creating remediation plans, or validating control effectiveness. -project - - - -using-git-worktrees -Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification -project - - - -using-superpowers -Use when starting any conversation - establishes how to find and use skills, requiring Skill tool invocation before ANY response including clarifying questions -project - - - -uv-package-manager -Master the uv package manager for fast Python dependency management, virtual environments, and modern Python project workflows. Use when setting up Python projects, managing dependencies, or optimizing Python development workflows with uv. -project - - - -verification-before-completion -Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always -project - - - -webapp-testing -Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs. -project - - - -writing-plans -Use when you have a spec or requirements for a multi-step task, before touching code -project - - - -writing-skills -Use when creating new skills, editing existing skills, or verifying skills work before deployment -project - - - -design-an-interface -Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice". -project - - - -edit-article -Edit and improve articles by restructuring sections, improving clarity, and tightening prose. Use when user wants to edit, revise, or improve an article draft. -project - - - -git-guardrails-claude-code -Set up Claude Code hooks to block dangerous git commands (push, reset --hard, clean, branch -D, etc.) before they execute. Use when user wants to prevent destructive git operations, add git safety hooks, or block git push/reset in Claude Code. -project - - - -grill-me -Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me". -project - - - -improve-codebase-architecture -Explore a codebase to find opportunities for architectural improvement, focusing on making the codebase more testable by deepening shallow modules. Use when user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more AI-navigable. -project - - - -migrate-to-shoehorn -Migrate test files from `as` type assertions to @total-typescript/shoehorn. Use when user mentions shoehorn, wants to replace `as` in tests, or needs partial test data. -project - - - -obsidian-vault -Search, create, and manage notes in the Obsidian vault with wikilinks and index notes. Use when user wants to find, create, or organize notes in Obsidian. -project - - - -prd-to-issues -Break a PRD into independently-grabbable GitHub issues using tracer-bullet vertical slices. Use when user wants to convert a PRD to issues, create implementation tickets, or break down a PRD into work items. -project - - - -prd-to-plan -Turn a PRD into a multi-phase implementation plan using tracer-bullet vertical slices, saved as a local Markdown file in ./plans/. Use when user wants to break down a PRD, create an implementation plan, plan phases from a PRD, or mentions "tracer bullets". -project - - - -qa -Interactive QA session where user reports bugs or issues conversationally, and the agent files GitHub issues. Explores the codebase in the background for context and domain language. Use when user wants to report bugs, do QA, file issues conversationally, or mentions "QA session". -project - - - -request-refactor-plan -Create a detailed refactor plan with tiny commits via user interview, then file it as a GitHub issue. Use when user wants to plan a refactor, create a refactoring RFC, or break a refactor into safe incremental steps. -project - - - -scaffold-exercises -Create exercise directory structures with sections, problems, solutions, and explainers that pass linting. Use when user wants to scaffold exercises, create exercise stubs, or set up a new course section. -project - - - -setup-pre-commit -Set up Husky pre-commit hooks with lint-staged (Prettier), type checking, and tests in the current repo. Use when user wants to add pre-commit hooks, set up Husky, configure lint-staged, or add commit-time formatting/typechecking/testing. -project - - - -tdd -Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development. -project - - - -triage-issue -Triage a bug or issue by exploring the codebase to find root cause, then create a GitHub issue with a TDD-based fix plan. Use when user reports a bug, wants to file an issue, mentions "triage", or wants to investigate and plan a fix for a problem. -project - - - -ubiquitous-language -Extract a DDD-style ubiquitous language glossary from the current conversation, flagging ambiguities and proposing canonical terms. Saves to UBIQUITOUS_LANGUAGE.md. Use when user wants to define domain terms, build a glossary, harden terminology, create a ubiquitous language, or mentions "domain model" or "DDD". -project - - - -write-a-prd -Create a PRD through user interview, codebase exploration, and module design, then submit as a GitHub issue. Use when user wants to write a PRD, create a product requirements document, or plan a new feature. -project - - - -write-a-skill -Create new agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, or build a new skill. -project - - - - - - +- You may be in a dirty worktree. Do not revert or overwrite changes you did not make. +- Check `git status --short --branch` before edits and before commits. +- Create focused branches for non-trivial work. +- Commit only when the user asks. diff --git a/backend/AGENTS.md b/backend/AGENTS.md index 76f59b10..c296135e 100644 --- a/backend/AGENTS.md +++ b/backend/AGENTS.md @@ -1,160 +1,64 @@ -# AGENTS - - - -## Available Skills - - - -When users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively. Skills provide specialized capabilities and domain knowledge. - -How to use skills: -- Invoke: `npx openskills read ` (run in your shell) - - For multiple: `npx openskills read skill-one,skill-two` -- The skill content will load with detailed instructions on how to complete the task -- Base directory provided in output for resolving bundled resources (references/, scripts/, assets/) - -Usage notes: -- Only use skills listed in below -- Do not invoke a skill that is already loaded in your context -- Each skill invocation is stateless - - - - - -async-python-patterns -Master Python asyncio, concurrent programming, and async/await patterns for high-performance applications. Use when building async APIs, concurrent systems, or I/O-bound applications requiring non-blocking operations. -project - - - -cqrs-implementation -Implement Command Query Responsibility Segregation for scalable architectures. Use when separating read and write models, optimizing query performance, or building event-sourced systems. -project - - - -database-migration -Execute database migrations across ORMs and platforms with zero-downtime strategies, data transformation, and rollback procedures. Use when migrating databases, changing schemas, performing data transformations, or implementing zero-downtime deployment strategies. -project - - - -fastapi-templates -Create production-ready FastAPI projects with async patterns, dependency injection, and comprehensive error handling. Use when building new FastAPI applications or setting up backend API projects. -project - - - -memory-safety-patterns -Implement memory-safe programming with RAII, ownership, smart pointers, and resource management across Rust, C++, and C. Use when writing safe systems code, managing resources, or preventing memory bugs. -project - - - -postgresql -Design a PostgreSQL-specific schema. Covers best-practices, data types, indexing, constraints, performance patterns, and advanced features -project - - - -python-anti-patterns -Common Python anti-patterns to avoid. Use as a checklist when reviewing code, before finalizing implementations, or when debugging issues that might stem from known bad practices. -project - - - -python-background-jobs -Python background job patterns including task queues, workers, and event-driven architecture. Use when implementing async task processing, job queues, long-running operations, or decoupling work from request/response cycles. -project - - - -python-code-style -Python code style, linting, formatting, naming conventions, and documentation standards. Use when writing new code, reviewing style, configuring linters, writing docstrings, or establishing project standards. -project - - - -python-configuration -Python configuration management via environment variables and typed settings. Use when externalizing config, setting up pydantic-settings, managing secrets, or implementing environment-specific behavior. -project - - - -python-design-patterns -Python design patterns including KISS, Separation of Concerns, Single Responsibility, and composition over inheritance. Use when making architecture decisions, refactoring code structure, or evaluating when abstractions are appropriate. -project - - - -python-error-handling -Python error handling patterns including input validation, exception hierarchies, and partial failure handling. Use when implementing validation logic, designing exception strategies, handling batch processing failures, or building robust APIs. -project - - - -python-observability -Python observability patterns including structured logging, metrics, and distributed tracing. Use when adding logging, implementing metrics collection, setting up tracing, or debugging production systems. -project - - - -python-packaging -Create distributable Python packages with proper project structure, setup.py/pyproject.toml, and publishing to PyPI. Use when packaging Python libraries, creating CLI tools, or distributing Python code. -project - - - -python-performance-optimization -Profile and optimize Python code using cProfile, memory profilers, and performance best practices. Use when debugging slow Python code, optimizing bottlenecks, or improving application performance. -project - - - -python-project-structure -Python project organization, module architecture, and public API design. Use when setting up new projects, organizing modules, defining public interfaces with __all__, or planning directory layouts. -project - - - -python-resilience -Python resilience patterns including automatic retries, exponential backoff, timeouts, and fault-tolerant decorators. Use when adding retry logic, implementing timeouts, building fault-tolerant services, or handling transient failures. -project - - - -python-resource-management -Python resource management with context managers, cleanup patterns, and streaming. Use when managing connections, file handles, implementing cleanup logic, or building streaming responses with accumulated state. -project - - - -python-testing-patterns -Implement comprehensive testing strategies with pytest, fixtures, mocking, and test-driven development. Use when writing Python tests, setting up test suites, or implementing testing best practices. -project - - - -python-type-safety -Python type safety with type hints, generics, protocols, and strict type checking. Use when adding type annotations, implementing generic classes, defining structural interfaces, or configuring mypy/pyright. -project - - - -sql-optimization-patterns -Master SQL query optimization, indexing strategies, and EXPLAIN analysis to dramatically improve database performance and eliminate slow queries. Use when debugging slow queries, designing database schemas, or optimizing application performance. -project - - - -temporal-python-testing -Test Temporal workflows with pytest, time-skipping, and mocking strategies. Covers unit testing, integration testing, replay testing, and local development setup. Use when implementing Temporal workflow tests or debugging test failures. -project - - - - - - +# VoteCatcher Backend + +FastAPI backend for OCR processing, signature validation, matching, campaigns, and persistence. + +This file is a backend-specific overlay. Follow `../AGENTS.md` first, including its local-preference hook. + +## Read When Relevant + +- Project-wide agent rules: `../AGENTS.md` +- Backend setup: `../docs/running-locally.md#backend-setup` +- Architecture or persistence changes: `../docs/architecture/README.md`, `../docs/architecture/decisions/`, `../docs/database/` +- Testing patterns: `../docs/development/testing.md` +- Broad refactors or Python-heavy changes: `../docs/agents/code-quality.md` + +## Structure + +- `app/routers/`: FastAPI routes; keep handlers thin. +- `app/services/`: business workflows and integration logic. +- `app/domain/`: domain value objects and pure rules. +- `app/repositories/` and `app/data/`: persistence and database access. +- `app/matching/`: fuzzy matching and voter data adaptation. +- `app/regions/`: JSON5 regional field specs. +- `alembic/`: schema migrations. +- `tests/`: unit and integration tests. + +## Commands + +From repo root for quality gates: + +- Tests: `just test-backend` +- Lint: `just lint-backend` +- Typecheck: `just typecheck-backend` +- Broad local CI: `just ci-sim` + +From `backend/` for focused iteration: + +- Install: `uv sync --dev` +- Run API locally: `uv run python main.py --env local` +- Tests: `uv run pytest tests/ -v` +- Single test file or case: `uv run pytest tests/path/to/test_file.py::test_name -v` +- Lint: `uv run ruff check app tests` +- Format: `uv run ruff format app tests` +- Typecheck: `uv run basedpyright app` +- Run migrations: `uv run alembic upgrade head` + +## Conventions + +- Keep route handlers thin; put business logic in services/domain modules. +- Type annotate public functions and new service/domain helpers. +- Keep API contract changes aligned with `openapi.yaml` and `app/routers/`. +- Add or update Alembic migrations in `alembic/` for schema changes. +- Prefer behavior-focused tests over implementation-detail mocks. +- Use approval tests for large rendered outputs, score matrices, and config/spec snapshots. + +## Boundaries + +- Do not commit `.env*`, local databases, generated `.received.txt` approval files, or OCR/API secrets. +- Do not put business logic in route handlers; add or reuse a service/domain function instead. +- Do not change schema models without an Alembic migration and relevant tests. +- Do not embed generated skill catalogs or broad reference docs here; link to focused docs instead. + +## Skills + +Use backend-specific skills only when relevant. Follow the project skill rules in `../AGENTS.md` and `../docs/agents/skills.md`. diff --git a/docs/agents/code-quality.md b/docs/agents/code-quality.md new file mode 100644 index 00000000..6ac1afa7 --- /dev/null +++ b/docs/agents/code-quality.md @@ -0,0 +1,29 @@ +# Agent Code Quality Notes + +Use this when changing Python, refactoring legacy code, or writing tests. + +## Python Readability + +- Prefer guard clauses and early returns over deep nesting. +- Use `' '.join(filter(None, parts))` for delimited strings built from optional parts. +- Extract repeated blocks when duplication is already obvious; do not invent abstractions for one-off code. +- Use ternaries for simple two-branch defaults. Use full `if` blocks when branches have side effects or complex logic. +- Remove dead wrappers that only delegate without adding behavior. +- Use named constants for repeated literals that carry domain meaning. + +## Legacy Refactoring + +- Clean only the code you are already touching unless the user asks for a broader refactor. +- Prefer small safe cleanups: flatten conditionals, remove unused imports, extract repeated conditionals, replace long `isinstance` chains with clearer dispatch. +- Preserve behavior first. Add tests before changing risky logic. + +## Test Discipline + +- Assert behavioral contracts: what the system must do, not how it happens internally. +- Avoid asserting internal method calls unless the call is the public contract. +- Avoid fragile checks like `repr(type(...))` strings. +- Prefer negative contract assertions when useful, such as proving `.all()` is not called for streaming queries. + +## Nesting Watch + +When loop bodies reach three or more nested levels, pause and flatten with guards, extracted helpers, or clearer condition order. diff --git a/docs/agents/hooks.md b/docs/agents/hooks.md new file mode 100644 index 00000000..14f5c615 --- /dev/null +++ b/docs/agents/hooks.md @@ -0,0 +1,115 @@ +# Agent Hooks + +Agent hooks provide deterministic guardrails around agent behavior. Use them for rules that should not rely on prompt-following alone. + +## Project Contract + +- Canonical hook scripts live in `.agents/hooks/scripts/`. +- Agents must treat these scripts as project contracts. +- Platform-specific hook configs call these scripts directly. +- Review hook scripts before enabling them. Hooks run with local user permissions. + +## AGENTS Bootstrap + +At session start, the hook script outputs root `AGENTS.md` followed by any machine-local preferences from `.agents/local/AGENTS.local.md`: + +```bash +.agents/hooks/scripts/read-agents.sh +``` + +The script outputs JSON by default (for hook platforms). Use `--plain` for direct execution. + +## Self-Learning Branch Guard + +Any branch that changes `AGENTS.md` or files under `docs/agents/` must be named `agents/`. + +This keeps self-learning updates separate from feature work and makes review intent clear. + +Expected script: + +```bash +.agents/hooks/scripts/enforce-agent-doc-branch.sh +``` + +The script should fail when staged or modified agent instruction files are present and the current branch does not start with `agents/`. + +## Portable Pattern + +There is no single hook config schema that all agents consume. Hook behavior is portable through shared scripts, not shared JSON. + +Use this pattern: + +1. Put enforcement logic in `.agents/hooks/scripts/`. +2. Configure each agent platform to call the shared scripts from its own hook mechanism. +3. If a platform is not covered here, consult that platform's hook/plugin documentation and set up equivalent calls to the same scripts. +4. If a platform does not support hooks, agents must manually run the relevant script before editing protected files. + +## Platform Configs + +Default hook configs ship in the repo so each platform loads root `AGENTS.md` and local agent preferences at session start: + +| Platform | Config file | Event | +| --- | --- | --- | +| Claude Code | `.claude/settings.json` | `SessionStart` | +| VS Code | `.claude/settings.json` (shared) | `SessionStart` | +| Cursor | `.cursor/hooks.json` | `sessionStart` | +| Codex | `.codex/hooks.json` | `SessionStart` | +| OpenCode | `.opencode/plugins/local-agents.js` | `session.created` | +| Pi | `.pi/hook/hooks.yaml` | `session.created` | + +All platform hooks call `.agents/hooks/scripts/read-agents.sh`, which outputs root `AGENTS.md` plus local preferences as JSON for cross-platform compatibility. + +Platform hook documentation: + +- Claude Code: https://code.claude.com/docs/en/hooks +- VS Code: https://code.visualstudio.com/docs/agent-customization/hooks +- Cursor: https://cursor.com/docs/hooks +- Codex: https://developers.openai.com/codex/hooks +- OpenCode: https://opencode.ai/docs/plugins/ +- Pi: https://pi.dev/packages/pi-yaml-hooks + +Do not add a generic `.agents/hooks.json`; project-owned behavior lives in scripts, not a shared manifest. + +## Branch Guard Adapter Example + +To enforce the self-learning branch rule, wire `enforce-agent-doc-branch.sh` into each platform's pre-edit hook. Example for Claude Code: + +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Edit|Write|MultiEdit", + "hooks": [ + { + "type": "command", + "command": "${CLAUDE_PROJECT_DIR}/.agents/hooks/scripts/enforce-agent-doc-branch.sh" + } + ] + } + ] + } +} +``` + +## Manual Fallback + +If hook integration is unavailable, agents must run the AGENTS bootstrap script immediately after reading root `AGENTS.md`: + +```bash +.agents/hooks/scripts/read-agents.sh --plain +``` + +Agents must also run this before editing or committing agent instruction files: + +```bash +.agents/hooks/scripts/enforce-agent-doc-branch.sh +``` + +Protected files: + +- `AGENTS.md` +- `frontend/AGENTS.md` +- `backend/AGENTS.md` +- `docs/agents/**` +- `.agents/hooks/**` diff --git a/docs/agents/local-preferences.md b/docs/agents/local-preferences.md new file mode 100644 index 00000000..f55f706b --- /dev/null +++ b/docs/agents/local-preferences.md @@ -0,0 +1,32 @@ +# Local Agent Preferences + +VoteCatcher supports optional machine-local agent preferences at: + +```text +.agents/local/AGENTS.local.md +``` + +This path is gitignored. It is for local workstation preferences that should not affect the team or CI. + +## Required Agent Behavior + +Immediately after reading root `AGENTS.md`, run: + +```bash +.agents/hooks/scripts/read-agents.sh --plain +``` + +The script outputs root `AGENTS.md` followed by `.agents/local/AGENTS.local.md` if it exists. Because `.agents/local/` is gitignored, use CLI/file-search tools rather than relying on tracked file lists. + +If the local file exists, treat its output as machine-local agent preferences before starting active work. + +## Appropriate Content + +Keep local preferences limited to machine-specific or user-specific details: + +- Preferred local commands or aliases. +- Local service ports. +- Machine-specific paths. +- Personal editor or terminal preferences. + +Do not put project-wide conventions, security-sensitive secrets, or durable team knowledge here. Project-wide lessons belong in `AGENTS.md` or `docs/agents/` through the self-learning PR process. diff --git a/docs/agents/self-learning.md b/docs/agents/self-learning.md new file mode 100644 index 00000000..818b6202 --- /dev/null +++ b/docs/agents/self-learning.md @@ -0,0 +1,37 @@ +# Agent Self-Learning + +VoteCatcher uses a hybrid self-learning loop. `AGENTS.md` stays concise, while durable project-specific lessons live in `docs/agents/`. + +## When To Propose A Learning Update + +At task end, propose a learning update when you discovered a durable project-specific rule, pitfall, command, convention, or stale instruction. + +Use a strict filter. + +Keep: +- Durable project knowledge likely useful across future sessions. +- Repeated pitfalls or commands that are easy to forget. +- Corrections to stale agent instructions. +- Team-specific conventions not obvious from code. + +Skip: +- Task trivia. +- Temporary state. +- One-off debugging notes. +- Generic coding advice. +- Personal preferences that are not project conventions. + +## Required Workflow + +Before editing learning docs: + +1. Ask the user first. +2. Create a separate branch named `agents/`. +3. Open a separate PR for the AGENTS/docs-agent update. +4. Do not mix self-learning changes into feature branches. + +## Where Lessons Go + +- `AGENTS.md` - only high-level routing and mandatory contracts. +- `docs/agents/*.md` - detailed agent-only guidance. +- `README.md` or `docs/development/*.md` - human-facing project behavior. diff --git a/docs/agents/skills.md b/docs/agents/skills.md new file mode 100644 index 00000000..68778935 --- /dev/null +++ b/docs/agents/skills.md @@ -0,0 +1,20 @@ +# Agent Skills + +`find-skills` is a core project skill. Use it when specialized help may exist. + +For more information about the skills CLI and installable skills, see [`vercel-labs/skills`](https://github.com/vercel-labs/skills). + +## Commands + +- Search: `npx skills find ` +- Search with Bun if preferred: `bunx skills find ` +- List installed skills: `npx skills list` +- Inspect repository skills without installing: `npx skills add --list` +- Install project skills for Universal: `npx skills add --skill -a universal -y` + +## Rules + +- Do not embed generated skill catalogs in `AGENTS.md`. +- Prefer project installs with `-a universal` so skills land under `.agents/skills/`. +- Inspect skill quality before installing: source reputation, install count, repository health, and relevance. +- Ask before installing new skills unless the user explicitly requested installation. diff --git a/docs/agents/svelte-mcp.md b/docs/agents/svelte-mcp.md new file mode 100644 index 00000000..00b3b385 --- /dev/null +++ b/docs/agents/svelte-mcp.md @@ -0,0 +1,19 @@ +# Svelte MCP Workflow + +Use this when working in `frontend/` on Svelte or SvelteKit code and the Svelte MCP server is available. + +## Documentation Lookup + +1. Call `list-sections` first for Svelte/SvelteKit tasks. +2. Inspect returned titles, paths, and `use_cases`. +3. Call `get-documentation` for every relevant section before writing code. + +## Code Validation + +- Run `svelte-autofixer` on changed Svelte code. +- Keep applying fixes until it reports no issues or suggestions. + +## Playground Links + +- Ask before creating a playground link. +- Do not create playground links for code already written to project files. diff --git a/docs/agents/versioning.md b/docs/agents/versioning.md new file mode 100644 index 00000000..4c5a4414 --- /dev/null +++ b/docs/agents/versioning.md @@ -0,0 +1,38 @@ +# Agent Versioning And Changelog Notes + +Use this only for version bumps, release prep, or changelog work. + +Human-facing versioning source: `docs/development/versioning.md`. + +## Version Files + +Keep these in sync: + +- `.cz.toml` +- `backend/pyproject.toml` +- `frontend/package.json` + +When adding a new package, update Commitizen `version_files` in `.cz.toml` and any related `justfile` recipes. + +## Commands + +- Show version: `just version` +- Set exact version: `just version-set ` +- Auto-bump from conventional commits: `just release` +- Force bump: `just release-force ` +- Bump prerelease suffix: `just release-prerelease` +- Drop prerelease suffix: `just release-stable` +- Generate changelog: `just changelog` +- Preview unreleased changelog: `just changelog-preview` +- Preview range: `just changelog-range v1..v2` + +## Agent Changelog Workflow + +After `just release` and `just changelog`: + +1. Read raw `CHANGELOG.md` generated by git-cliff. +2. Group related commits into concise narrative entries. +3. Keep technical scope prefixes when they improve precision. +4. Use user-facing language where possible. +5. Do not invent changes not present in commits. +6. Commit only if the user asked for a commit. diff --git a/docs/development/versioning.md b/docs/development/versioning.md index 21167805..21286102 100644 --- a/docs/development/versioning.md +++ b/docs/development/versioning.md @@ -97,6 +97,18 @@ git push --tags just release-stable ``` +## Changelog + +VoteCatcher uses git-cliff for changelog generation. + +```bash +just changelog # regenerate CHANGELOG.md +just changelog-preview # preview unreleased changes +just changelog-range v1..v2 +``` + +Raw changelog entries come from conventional commits. Keep commit messages specific enough that generated release notes are useful. + ## Workflow Example ```text diff --git a/frontend/AGENTS.md b/frontend/AGENTS.md index e1cff758..ca402810 100644 --- a/frontend/AGENTS.md +++ b/frontend/AGENTS.md @@ -1,161 +1,51 @@ -You are able to use the Svelte MCP server, where you have access to comprehensive Svelte 5 and SvelteKit documentation. Here's how to use the available tools effectively: +# VoteCatcher Frontend -## Available MCP Tools: +SvelteKit 2 / Svelte 5 application for VoteCatcher. -### 1. list-sections +## First Reads -Use this FIRST to discover all available documentation sections. Returns a structured list with titles, use_cases, and paths. -When asked about Svelte or SvelteKit topics, ALWAYS use this tool at the start of the chat to find relevant sections. +- Frontend overview and scripts: `frontend/README.md` +- Project-wide agent rules: `../AGENTS.md` +- Svelte MCP workflow: `../docs/agents/svelte-mcp.md` +- Local development: `../docs/development/README.md` -### 2. get-documentation +## Commands -Retrieves full documentation content for specific sections. Accepts single or multiple sections. -After calling the list-sections tool, you MUST analyze the returned documentation sections (especially the use_cases field) and then use the get-documentation tool to fetch ALL documentation sections that are relevant for the user's task. +- Install: `bun install` +- Dev server: `bun run dev` +- Build: `bun run build` +- Unit tests: `bun run test:unit` +- E2E tests: `bun run test:e2e` +- All tests: `bun run test` +- Lint: `bun run lint` +- Fix lint: `bun run lint:fix` +- Format: `bun run fmt` +- Check format: `bun run fmt:check` +- Typecheck: `bun run check` -### 3. svelte-autofixer +## Tooling -Analyzes Svelte code and returns issues and suggestions. -You MUST use this tool whenever writing Svelte code before sending it to the user. Keep calling it until no issues or suggestions are returned. +- Prefer Bun in `frontend/`: `bun install`, `bun run - - -``` - -With the following `frontend.tsx`: - -```tsx#frontend.tsx -import React from "react"; -import { createRoot } from "react-dom/client"; - -// import .css files directly and it works -import './index.css'; - -const root = createRoot(document.body); - -export default function Frontend() { - return

Hello, world!

; -} - -root.render(); -``` - -Then, run index.ts - -```sh -bun --hot ./index.ts -``` - -For more information, read the Bun API docs in `node_modules/bun-types/docs/**.mdx`.