Add repository onboarding instructions for Copilot coding agents (#1187)

* Initial plan * Initial plan for repository onboarding instructions Co-authored-by: tankerkiller125 <3457368+tankerkiller125@users.noreply.github.com> * Add comprehensive coding agent instructions for Homebox repository Co-authored-by: tankerkiller125 <3457368+tankerkiller125@users.noreply.github.com> * Optimize instructions to meet 2-page limit while maintaining completeness Co-authored-by: tankerkiller125 <3457368+tankerkiller125@users.noreply.github.com> * Add 4 path-specific instruction files for backend and frontend architecture Co-authored-by: tankerkiller125 <3457368+tankerkiller125@users.noreply.github.com> * Path application for instructions --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: tankerkiller125 <3457368+tankerkiller125@users.noreply.github.com> Co-authored-by: Matt <tankerkiller125@users.noreply.github.com>
2026-01-02 02:57:22 +01:00 · 2025-12-28 15:03:51 -05:00
parent 3c532896f5
commit 7dfaa0298b
17 changed files with 2149 additions and 16 deletions
--- a/.github/instructions/code.instructions.md
+++ b/.github/instructions/code.instructions.md
@@ -0,0 +1,157 @@
+# Homebox Repository Instructions for Coding Agents
+
+## Repository Overview
+
+**Type**: Full-stack home inventory management web app (monorepo)  
+**Size**: ~265 Go files, ~371 TypeScript/Vue files  
+**Build Tool**: Task (Taskfile.yml) - **ALWAYS use `task` commands**  
+**Database**: SQLite (default) or PostgreSQL
+
+### Stack
+- **Backend** (`/backend`): Go 1.24+, Chi router, Ent ORM, port 7745
+- **Frontend** (`/frontend`): Nuxt 4, Vue 3, TypeScript, Tailwind CSS, pnpm 9.1.4+, dev proxies to backend
+
+## Critical Build & Validation Commands
+
+### Initial Setup (Run Once)
+```bash
+task setup  # Installs swag, goose, Go deps, pnpm deps
+```
+
+### Code Generation (Required Before Backend Work)
+```bash
+task generate  # Generates Ent ORM, Swagger docs, TypeScript types
+```
+**ALWAYS run after**: schema changes, API handler changes, before backend server/tests  
+**Note**: "TypeSpecDef is nil" warnings are normal - ignore them
+
+### Backend Commands
+```bash
+task go:build    # Build binary (60-90s)
+task go:test     # Unit tests (5-10s)
+task go:lint     # golangci-lint (6m timeout in CI)
+task go:all      # Tidy + lint + test
+task go:run      # Start server (SQLite)
+task pr          # Full PR validation (3-5 min)
+```
+
+### Frontend Commands
+```bash
+task ui:dev    # Dev server port 3000
+task ui:check  # Type checking
+task ui:fix    # eslint --fix + prettier
+task ui:watch  # Vitest watch mode
+```
+**Lint**: Max 1 warning in CI (`pnpm run lint:ci`)
+
+### Testing
+```bash
+task test:ci            # Integration tests (15-30s + startup)
+task test:e2e           # Playwright E2E (60s+ per shard, needs playwright install)
+task pr                 # Full PR validation: generate + go:all + ui:check + ui:fix + test:ci (3-5 min)
+```
+
+## Project Structure
+
+### Key Root Files
+- `Taskfile.yml` - All commands (always use `task`)
+- `docker-compose.yml`, `Dockerfile*` - Docker configs
+- `CONTRIBUTING.md` - Contribution guidelines
+
+### Backend Structure (`/backend`)
+```
+backend/
+├── app/
+│   ├── api/              # Main API application
+│   │   ├── main.go       # Entry point
+│   │   ├── routes.go     # Route definitions
+│   │   ├── handlers/     # HTTP handlers (v1 API)
+│   │   ├── static/       # Swagger docs, embedded frontend
+│   │   └── providers/    # Service providers
+│   └── tools/
+│       └── typegen/      # TypeScript type generation tool
+├── internal/
+│   ├── core/
+│   │   └── services/     # Business logic layer
+│   ├── data/
+│   │   ├── ent/          # Ent ORM generated code + schemas
+│   │   │   └── schema/   # Schema definitions (edit these)
+│   │   └── repo/         # Repository pattern implementations
+│   ├── sys/              # System utilities (config, validation)
+│   └── web/              # Web middleware
+├── pkgs/                 # Reusable packages
+├── go.mod, go.sum        # Go dependencies
+└── .golangci.yml         # Linter configuration
+```
+
+**Patterns**: Schema/API changes → edit source → `task generate`. Never edit generated code in `ent/`.
+
+### Frontend Structure (`/frontend`)
+```
+frontend/
+├── app.vue               # Root component
+├── nuxt.config.ts        # Nuxt configuration
+├── package.json          # Frontend dependencies
+├── components/           # Vue components (auto-imported)
+├── pages/                # File-based routing
+├── layouts/              # Layout components
+├── composables/          # Vue composables (auto-imported)
+├── stores/               # Pinia state stores
+├── lib/
+│   └── api/
+│       └── types/        # Generated TypeScript API types
+├── locales/              # i18n translations
+├── test/                 # Vitest + Playwright tests
+├── eslint.config.mjs     # ESLint configuration
+└── tailwind.config.js    # Tailwind configuration
+```
+
+**Patterns**: Auto-imports for `components/` and `composables/`. API types auto-generated - never edit manually.
+
+## CI/CD Workflows
+
+PR checks (`.github/workflows/pull-requests.yaml`) on `main`/`vnext`:
+1. **Backend**: Go 1.24, golangci-lint, `task go:build`, `task go:coverage`
+2. **Frontend**: Lint (max 1 warning), typecheck, `task test:ci` (SQLite + PostgreSQL v15-17)
+3. **E2E**: 4 sharded Playwright runs (60min timeout)
+
+All must pass before merge.
+
+## Common Pitfalls
+
+1. **Missing tools**: Run `task setup` first (installs swag, goose, deps)
+2. **Stale generated code**: Always `task generate` after schema/API changes
+3. **Test failures**: Integration tests may fail first run (race condition) - retry
+4. **Port in use**: Backend uses 7745 - kill existing process
+5. **SQLite locked**: Delete `.data/homebox.db-*` files
+6. **Clean build**: `rm -rf build/ backend/app/api/static/public/ frontend/.nuxt`
+
+## Environment Variables
+
+Backend defaults in `Taskfile.yml`:
+- `HBOX_LOG_LEVEL=debug`
+- `HBOX_DATABASE_DRIVER=sqlite3` (or `postgres`)
+- `HBOX_DATABASE_SQLITE_PATH=.data/homebox.db?_pragma=busy_timeout=1000&_pragma=journal_mode=WAL&_fk=1`
+- PostgreSQL: `HBOX_DATABASE_*` vars for username/password/host/port/database
+
+## Validation Checklist
+
+Before PR:
+- [ ] `task generate` after schema/API changes
+- [ ] `task pr` passes (includes lint, test, typecheck)
+- [ ] No build artifacts committed (check `.gitignore`)
+- [ ] Code matches existing patterns
+
+## Quick Reference
+
+**Dev environment**: `task go:run` (terminal 1) + `task ui:dev` (terminal 2)
+
+**API changes**: Edit handlers → add Swagger comments → `task generate` → `task go:build` → `task go:test`
+
+**Schema changes**: Edit `ent/schema/*.go` → `task generate` → update repo methods → `task go:test`
+
+**Specific tests**: `cd backend && go test ./path -v` or `cd frontend && pnpm run test:watch`
+
+## Trust These Instructions
+
+Instructions are validated and current. Only explore further if info is incomplete, incorrect, or you encounter undocumented errors. Use `task --list-all` for all commands.