chore: centralize agent instructions

.agent/PROCESS.md

@@ -0,0 +1,90 @@
+# Modern Resume Development Process & Rules
+
+This document defines the core philosophy, technical standards, and rules of engagement for AI agents and human developers working across the Modern Resume project suite.
+
+## 1. Rules of Engagement (Agent-User Collaboration)
+
+### **Conversation Kick-off**
+
+- When starting a new work conversation, the agent **MUST** notify the user that it has loaded the centralized development process into the current context and is aware of the team-specific guidelines.
+- Always reference the document using its public URL: `https://github.com/coderbunker/modern-resume-env/blob/main/.agent/PROCESS.md` (not the local file path).
+
+### **No Automatic Commits or Pushes**
+
+The AI agent **MUST NOT** automatically execute `git commit` or `git push` commands.
+
+- **Stage changes only**: The agent may use `git add` to prepare changes if requested, but should generally leave this to the user.
+- **Inform the user**: After making file modifications, the agent should inform the user which files were changed and suggest the next steps (e.g., running tests, reviewing diffs).
+- **User control**: The final decision to commit and push code belongs to the user. The agent should only provide the command for the user to run or wait for explicit confirmation to run it on their behalf.
+- **Conditional Permissions**: The user may grant the agent temporary permission to commit/push (e.g., for batch fixes). However, the agent MUST only exercise this permission within the scope of a well-defined, already agreed-upon, and documented task list.
+- **Feature Branches**: All changes MUST be made on specialized feature branches (e.g., `feat/`, `fix/`, `chore/`).
+  - **Synchronization**: Before starting work and before proposing changes, ensure the current feature branch is up-to-date with the `main` branch (e.g., via `git merge main` or `git rebase main`).
+
+### **Proactive but Respectful**
+
+- The agent should be proactive in exploring the codebase and proposing solutions.
+  - Request approval via an `implementation_plan.md` artifact before execution.
+- **Proactive Document Maintenance**: When new general guidelines or technical standards are established during a task, the agent should proactively update this `PROCESS.md` file to ensure the centralized knowledge remains current.
+- **Documentation & Tests**: Every significant change MUST be accompanied by:
+  - Updates to relevant documentation (READMEs, `docs/`, etc.).
+  - **Unit Tests**: Fast, isolated tests with no external dependencies.
+  - **Integration Tests**: Tests that verify interaction with infrastructure services (DB, Gateway, etc.).
+- **Quality Enforcement**: Proactively run linting (Biome) and type-checking before proposing changes. Ensure all new code adheres to project standards.
+
+## 2. Technical Stack & Philosophy
+
+### **Core Technologies**
+
+- **Language**: TypeScript (Strict usage, avoid `any`).
+- **Runtime**: **Bun** (Preferred over Node.js/npm). Use `bun install`, `bun run`.
+- **Environment**: **Nix** (via `flake.nix` and `direnv`). Use `nix develop` for portable environments.
+- **Frontend**: Vue 3 (Composition API with `<script setup>`) or **Next.js** for main apps, Vite for building.
+- **Backend**: Bun-based APIs, Orval/hey-api for SDK generation.
+- **Code Quality**: Biome for linting and formatting (Preferred over ESLint/Prettier).
+
+### **Best Practices**
+
+- **Knowledge Discovery**: Always check existing **Knowledge Items (KIs)** before starting new research.
+- **Terminal Optimization**: Minimize frequent `cd` commands to avoid repetitive `direnv` initialization overhead. Use absolute paths or run from the repo root.
+- **Internationalization**: Use `vue-i18n` for all user-facing text.
+- **Schema Validation**: Use **Zod** for runtime data validation.
+
+## 3. Workflow & Infrastructure
+
+### **Secret Management**
+
+- **SOPS**: Prefer SOPS-encrypted files for secrets. Use `sops --set` for efficient updates.
+
+### **Testing & Quality**
+
+- Use **Vitest** for unit/integration tests and **Puppeteer/Playwright** for browser-based integration tests.
+- **Test Hierarchy**:
+  - **Unit**: Fast, no external network or file system dependencies (stubs/mocks).
+  - **Integration**: Verifies interaction between components or with infrastructure (Docker-backed).
+- **Quality Gates**: Always run `bun run check` (Biome lint + format) before finishing a task.
+
+### **Shell Usage & Scripting**
+
+- **Complex Operations**: For complex or multi-step shell operations, prefer creating a shell script in `scripts/` or `/tmp/` rather than execution long strings in the terminal.
+- **User Choice**: Present the script to the user and offer them the choice to run it themselves or have the agent execute it.
+- **Subshell Awareness**: Be extremely careful with environment variables and directory changes in subshells; ensure they propagate correctly or are explicitly handled.
+
+### **Docker Compose & Profiles**
+
+- **Orchestration**: Use `docker-compose.yml` in `modern-resume-env` or individual repos to manage the stack.
+- **Profiles**: Utilize Docker Compose **profiles** to bring up specific parts of the stack (e.g., `db-only`, `api-only`, `frontend-only`) or to run tests in an isolated environment.
+- **Standard Command**: `docker compose --profile <profile> up -d`.
+
+## 4. Repository Structure
+
+The project consists of several specialized repositories:
+
+- `modern-resume`: Main user frontend.
+- `modern-resume-admin`: Admin frontend.
+- `modern-resume-backend`: Core API.
+- `modern-resume-admin-backend`: Admin-specific API.
+- `modern-resume-env`: Shared environment and CI/CD configurations.
+- `modern-resume-infra`: Infrastructure and deployment (K8s, Flux).
+
+---
+*For repository-specific details, refer to the local `README.md` or `docs/` folder in each repository.*

.agent/rules/no-auto-commit.md

@@ -1,10 +1,7 @@
----
-description: Prevent agents from automatically committing and pushing code.
----
+# Avoid Automatic Git Commits and Pushes
 
-# 🛑 NO AUTO COMMIT OR PUSH
+The agent MUST NOT automatically execute `git commit` or `git push` commands.
 
-**CRITICAL RULE:**
-You MUST NOT run `git add`, `git commit`, or `git push` automatically.
-Always leave unstaged and uncommitted changes for the USER to review, stage, commit, and push themselves.
-You may only run these commands if the USER explicitly issues a direct instruction to do so in the current prompt (e.g., "please commit and push these changes").
+See the centralized development process in
+[PROCESS.md](https://github.com/coderbunker/modern-resume-env/blob/main/.agent/PROCESS.md) for
+full details on rules of engagement.

docs/proposed/2026-03-17-centralize-agent-instructions.md

@@ -0,0 +1,36 @@
+# Proposal: Centralize Agent Instructions
+
+**Date**: 2026-03-17
+**Status**: In Progress
+**Repository**: `modern-resume-env` (Central), all others (Referencing)
+
+## Motivation
+
+Currently, development instructions and rules of engagement (such as no-auto-commit rules, tech stack explanations, and best practices) are scattered across multiple `.agent` directories in various repositories. This lead to:
+
+- Redundancy and duplication of information.
+- Risk of inconsistency when rules are updated in one place but not others.
+- Higher maintenance overhead for keeping agent context accurate.
+- Confusion for new agents/developers on which set of rules takes precedence.
+
+## Technical Plan
+
+1. **Centralize**: Create a single `PROCESS.md` in `modern-resume-env/.agent/` that contains all shared rules, philosophy, and tech stack information.
+2. **Reference**: Update all other repositories to remove their redundant local rules and instead point to the centralized `PROCESS.md`.
+3. **Standardize**: Add a `centralized-process.md` rule in each repo's `.agent/rules/` that explicitly tells agents to read the central document.
+4. **Refactor**: Update `AGENTS.md` (where it exists) to act as a high-level overview that redirects to the centralized process for detail.
+
+## Timeline & Progress
+
+- **2026-03-17**:
+  - Initial research of `.agent` directories across 6 repositories.
+  - Identified redundant files (`no-auto-commit.md`, `prefer-bun.md`, etc.).
+  - Created centralized `PROCESS.md` in `modern-resume-env`.
+  - Received user feedback to include documentation process and 'next' (Next.js) in the tech stack.
+  - Updated `PROCESS.md` and created this proposal document.
+  - **Final updates**: Incorporated rules for commit permissions scope, testing hierarchy (unit/integration), shell scripting best practices, subshell awareness, and Docker Compose profile usage.
+
+## Issues Encountered
+
+- **Inconsistent Paming**: Some repos had `.agent/rules/no-auto-commit.md` while others had slightly different versions or names.
+- **Redundant AGENTS.md**: `modern-resume` had a very detailed `AGENTS.md` which was effectively the source of truth, while others were lagging behind.