From c85adcaa204822b7a43f2ce39c4b704d28bdf834 Mon Sep 17 00:00:00 2001
From: Ricky Ng-Adam <rngadam@gmail.com>
Date: Tue, 17 Mar 2026 18:31:26 -0400
Subject: [PATCH 1/4] chore: centralize agent instructions

---
 .agent/PROCESS.md                             | 90 +++++++++++++++++++
 .agent/rules/no-auto-commit.md                | 13 ++-
 ...026-03-17-centralize-agent-instructions.md | 36 ++++++++
 3 files changed, 131 insertions(+), 8 deletions(-)
 create mode 100644 .agent/PROCESS.md
 create mode 100644 docs/proposed/2026-03-17-centralize-agent-instructions.md

diff --git a/.agent/PROCESS.md b/.agent/PROCESS.md
new file mode 100644
index 0000000..2c40c06
--- /dev/null
+++ b/.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.*
diff --git a/.agent/rules/no-auto-commit.md b/.agent/rules/no-auto-commit.md
index 42c4b9c..9ff004f 100644
--- a/.agent/rules/no-auto-commit.md
+++ b/.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.
diff --git a/docs/proposed/2026-03-17-centralize-agent-instructions.md b/docs/proposed/2026-03-17-centralize-agent-instructions.md
new file mode 100644
index 0000000..9c49542
--- /dev/null
+++ b/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.

From f0f77615f7a997cac05e5bfcb13ec776751a12fd Mon Sep 17 00:00:00 2001
From: Ricky Ng-Adam <rngadam@gmail.com>
Date: Tue, 17 Mar 2026 23:50:14 -0400
Subject: [PATCH 2/4] chore: optimize shell and nix performance

---
 .agent/PROCESS.md                             |  4 +-
 USAGE.md                                      | 26 ++++++++++++
 ...26-03-17-shell-performance-optimization.md | 41 +++++++++++++++++++
 scripts/setup-hooks.sh                        |  6 ++-
 4 files changed, 74 insertions(+), 3 deletions(-)
 create mode 100644 docs/proposed/2026-03-17-shell-performance-optimization.md

diff --git a/.agent/PROCESS.md b/.agent/PROCESS.md
index 2c40c06..f9eafd3 100644
--- a/.agent/PROCESS.md
+++ b/.agent/PROCESS.md
@@ -45,7 +45,9 @@ The AI agent **MUST NOT** automatically execute `git commit` or `git push` comma
 ### **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.
+- **Terminal Optimization**: Minimize frequent `cd` commands to avoid repetitive `direnv` initialization overhead.
+  - **Absolute Paths**: Use absolute paths for all file operations to avoid `cd` entirely where possible.
+  - **Direnv Exec**: For non-interactive commands, prefer `direnv exec /absolute/path/to/repo <command>` over `cd <repo> && <command>`. This bypasses shell hook execution and prompt evaluations.
 - **Internationalization**: Use `vue-i18n` for all user-facing text.
 - **Schema Validation**: Use **Zod** for runtime data validation.
 
diff --git a/USAGE.md b/USAGE.md
index 6dc158c..0b492a7 100644
--- a/USAGE.md
+++ b/USAGE.md
@@ -65,3 +65,29 @@ Or if you use `direnv`, create an `.envrc` file:
 ```bash
 use flake github:coderbunker/modern-resume-env
 ```
+
+## 4. Shell Performance Optimization
+
+To avoid the overhead of Nix flake re-evaluations on every directory change, it is highly recommended to use **`nix-direnv`**.
+
+### Install `nix-direnv`
+
+Follow the instructions at [nix-direnv](https://github.com/nix-community/nix-direnv) to install it. Once installed, `direnv` will cache the Nix environment, making shell loads instantaneous.
+
+### Pinning Nixpkgs
+
+To avoid network lookups during evaluation, pin your `nixpkgs` input in the local registry:
+
+```bash
+nix registry add nixpkgs github:NixOS/nixpkgs/$(nix flake metadata --json | jq -r '.inputs.nixpkgs.locked.rev')
+```
+
+### Agent Optimization
+
+For AI agents and automation, prefer **`direnv exec`** over `cd`:
+
+```bash
+direnv exec /path/to/repo <command>
+```
+
+This bypasses interactive shell hooks and prompt evaluations entirely.
diff --git a/docs/proposed/2026-03-17-shell-performance-optimization.md b/docs/proposed/2026-03-17-shell-performance-optimization.md
new file mode 100644
index 0000000..a96c571
--- /dev/null
+++ b/docs/proposed/2026-03-17-shell-performance-optimization.md
@@ -0,0 +1,41 @@
+# Proposed: Shell & Nix Performance Optimization (2026-03-17)
+
+The current development environment suffers from high overhead due to frequent Nix flake re-evaluations during directory changes and shell initialization. This affects both human productivity and AI agent response times.
+
+## 1. Motivation
+
+Every time an AI agent or developer changes directories or runs a command in a multi-repo setup, `direnv` triggers a Nix evaluation. Without persistent caching, this adds seconds of latency to every interaction. Additionally, the `shellHook` in `modern-resume-env` performs repetitive tasks like patching git hooks, which contributes to the slowdown.
+
+## 2. Technical Plan
+
+### A. Nix-Direnv Integration
+
+Recommend the installation and use of `nix-direnv` for persistent caching of Nix shells.
+
+- **Benefit**: Reduces shell load time from seconds to milliseconds after the first evaluation.
+- **Action**: Update `USAGE.md` with setup instructions for `nix-direnv`.
+
+### B. Agent Terminal Optimization (PROCESS.md)
+
+Update `PROCESS.md` to formalize the use of `direnv exec` as a standard practice for AI agents.
+
+- **Benefit**: Bypasses the overhead of interactive shell hooks and prompt evaluations entirely.
+- **Action**: Add "Agent Terminal Optimization" section to `PROCESS.md`.
+
+### C. Lazy Hook Loading
+
+Optimize `modern-resume-env/scripts/setup-hooks.sh` to only perform work when necessary.
+
+- **Action**: Add checks to avoid re-patching git hooks if they already have the `direnv` loader.
+
+### D. Flake Registry Pinning
+
+Document and recommend pinning the `nixpkgs` input in the local registry.
+
+- **Action**: `nix registry add nixpkgs github:NixOS/nixpkgs/<rev>`
+
+## 3. Verification Plan
+
+- Measure latency of `cd <repo>` before and after `nix-direnv` setup.
+- Verify that `direnv exec <repo> <cmd>` works accurately without the shell hook latency.
+- Confirm all tools (`gh`, `bun`, `tofu`) remain fully functional.
diff --git a/scripts/setup-hooks.sh b/scripts/setup-hooks.sh
index 97a5359..c20c199 100755
--- a/scripts/setup-hooks.sh
+++ b/scripts/setup-hooks.sh
@@ -3,14 +3,16 @@ set -e
 
 # Install hooks if not already installed
 if [ -d ".git" ] && command -v pre-commit >/dev/null 2>&1; then
-	pre-commit install >/dev/null 2>&1
+	if [ ! -f ".git/hooks/pre-commit" ]; then
+		pre-commit install >/dev/null 2>&1
+	fi
 
 	# Patch the hook to use direnv if available
 	HOOK_FILE=".git/hooks/pre-commit"
 	if [ -f "$HOOK_FILE" ]; then
 		# Check if we already patched it
 		if ! grep -q "direnv export bash" "$HOOK_FILE"; then
-			# We want to insert the direnv loader after the shebang
+			echo "Checking if .git/hooks/pre-commit needs patching..."
 			# but before the "start templated" block if possible, or just at the top.
 			# actually, pre-commit hooks are often overwritten by `pre-commit install`.
 			# however, `pre-commit` itself generates a script that calls the actual hook executable.

From 2be0670dab8536cae5b871155c974595fdc4e34b Mon Sep 17 00:00:00 2001
From: Ricky Ng-Adam <rngadam@gmail.com>
Date: Wed, 18 Mar 2026 00:00:01 -0400
Subject: [PATCH 3/4] chore: optimize CI workflows with paths-ignore

---
 .github/workflows/lint.yml              | 12 ++++++++++++
 .github/workflows/repolinter-caller.yml | 12 ++++++++++++
 .github/workflows/test-buns.yml         | 12 ++++++++++++
 3 files changed, 36 insertions(+)

diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index a77673b..412c081 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -3,7 +3,19 @@ name: Lint
 on:
   push:
     branches: ["main"]
+    paths-ignore:
+      - "README.md"
+      - "docs/**"
+      - ".agent/**"
+      - "LICENSE"
+      - ".gitignore"
   pull_request:
+    paths-ignore:
+      - "README.md"
+      - "docs/**"
+      - ".agent/**"
+      - "LICENSE"
+      - ".gitignore"
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
diff --git a/.github/workflows/repolinter-caller.yml b/.github/workflows/repolinter-caller.yml
index 5cce8f7..77ed1b5 100644
--- a/.github/workflows/repolinter-caller.yml
+++ b/.github/workflows/repolinter-caller.yml
@@ -3,7 +3,19 @@ name: Repolinter Self-Lint
 on:
   push:
     branches: ["main", "develop"]
+    paths-ignore:
+      - "README.md"
+      - "docs/**"
+      - ".agent/**"
+      - "LICENSE"
+      - ".gitignore"
   pull_request:
+    paths-ignore:
+      - "README.md"
+      - "docs/**"
+      - ".agent/**"
+      - "LICENSE"
+      - ".gitignore"
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
diff --git a/.github/workflows/test-buns.yml b/.github/workflows/test-buns.yml
index 36de7fe..c445b13 100644
--- a/.github/workflows/test-buns.yml
+++ b/.github/workflows/test-buns.yml
@@ -3,8 +3,20 @@ name: Test Buns Script
 on:
   push:
     branches: [ main, master ]
+    paths-ignore:
+      - "README.md"
+      - "docs/**"
+      - ".agent/**"
+      - "LICENSE"
+      - ".gitignore"
   pull_request:
     branches: [ main, master ]
+    paths-ignore:
+      - "README.md"
+      - "docs/**"
+      - ".agent/**"
+      - "LICENSE"
+      - ".gitignore"
 
 jobs:
   test:

From 750a931625f2e5a09ab072d2a49a3706ee0020b8 Mon Sep 17 00:00:00 2001
From: Ricky Ng-Adam <rngadam@gmail.com>
Date: Wed, 18 Mar 2026 00:15:21 -0400
Subject: [PATCH 4/4] chore: CI workflow optimization

---
 .../2026-03-17-ci-workflow-optimization.md    | 60 +++++++++++++++++++
 1 file changed, 60 insertions(+)
 create mode 100644 docs/proposed/2026-03-17-ci-workflow-optimization.md

diff --git a/docs/proposed/2026-03-17-ci-workflow-optimization.md b/docs/proposed/2026-03-17-ci-workflow-optimization.md
new file mode 100644
index 0000000..99380e5
--- /dev/null
+++ b/docs/proposed/2026-03-17-ci-workflow-optimization.md
@@ -0,0 +1,60 @@
+# Proposed: CI Workflow Optimization (2026-03-17)
+
+Documentation and agent instruction updates are currently triggering full release builds (including Docker builds and versioning) across multiple repositories. This is inefficient and causes unnecessary delays.
+
+## 1. Motivation
+
+Recent PRs for centralizing agent instructions triggered:
+
+- `modern-resume-backend`: Release workflow (Docker Build, Versioning)
+- `modern-resume`: Release workflow
+- `modern-resume-admin`: Release workflow
+
+These changes were exclusively to `.md` files and `.agent/` directories, which do not affect the compiled application or container images.
+
+## 2. Technical Plan
+
+Implement `paths-ignore` for the `on: push` and `on: pull_request` triggers in major application workflows.
+
+### Standard Exclusion List
+
+```yaml
+paths-ignore:
+  - "README.md"
+  - "docs/**"
+  - ".agent/**"
+  - "LICENSE"
+  - ".gitignore"
+```
+
+### Targets
+
+Separated by repository:
+
+#### modern-resume
+
+- `.github/workflows/release.yml`
+
+#### modern-resume-admin
+
+- `.github/workflows/release.yml`
+
+#### modern-resume-backend
+
+- `.github/workflows/release.yml`
+- `.github/workflows/ci-external.yml`
+
+#### modern-resume-admin-backend
+
+- `.github/workflows/release.yml` (Update existing filters to include `.agent/**`)
+
+#### modern-resume-env
+
+- `.github/workflows/lint.yml` (If applicable)
+
+## 3. Verification Plan
+
+- Manually trigger a documentation-only change (e.g., update a README) on a feature branch.
+- Verify that the release workflows are NOT triggered.
+- Manually trigger a code change (e.g., update a `.ts` file).
+- Verify that the release workflows ARE triggered as expected.