Merge branch 'main' of github.com:peancharoen/lcbp3

.agent/rules/00-project-specs.md

@@ -4,75 +4,59 @@ trigger: always_on
 
 # Project Specifications & Context Protocol
 
-Description: Enforces strict adherence to the project's documentation structure for all agent activities.
-Globs: \*
+Description: Enforces strict adherence to the project's documentation structure (specs/00-06) for all agent activities.
+Globs: *
 
 ---
 
 ## Agent Role
-
 You are a Principal Engineer and Architect strictly bound by the project's documentation. You do not improvise outside of the defined specifications.
 
 ## The Context Loading Protocol
-
 Before generating code or planning a solution, you MUST conceptually load the context in this specific order:
 
-1.  **📖 PROJECT CONTEXT (`specs/00-Overview/`)**
-    - _Action:_ Align with the high-level goals and domain language described here.
+1.  **🎯 ACTIVE TASK (`specs/06-tasks/`)**
+    - Identify the current active task file.
+    - *Action:* Determine the immediate scope. Do NOT implement features not listed here.
 
-2.  **✅ REQUIREMENTS (`specs/01-Requirements/`)**
-    - _Action:_ Verify that your plan satisfies the functional requirements and user stories.
-    - _Constraint:_ If a requirement is ambiguous, stop and ask.
+2.  **📖 PROJECT CONTEXT (`specs/00-overview/`)**
+    - *Action:* Align with the high-level goals and domain language described here.
 
-3.  **🏗 ARCHITECTURE & DECISIONS (`specs/02-Architecture/` & `specs/06-Decision-Records/`)**
-    - _Action:_ Adhere to the defined system design.
-    - _Crucial:_ Check `specs/06-Decision-Records/` (ADRs) to ensure you do not violate previously agreed-upon technical decisions.
+3.  **✅ REQUIREMENTS (`specs/01-requirements/`)**
+    - *Action:* Verify that your plan satisfies the functional requirements and user stories.
+    - *Constraint:* If a requirement is ambiguous, stop and ask.
 
-4.  **💾 DATABASE & SCHEMA (`specs/03-Data-and-Storage/`)**
-    - _Action:_
-      - **Read `specs/03-Data-and-Storage/lcbp3-v1.8.0-schema-02-tables.sql`** for exact table structures and constraints. (Schema split: `01-drop`, `02-tables`, `03-views-indexes`)
-      - **Consult `specs/03-Data-and-Storage/03-01-data-dictionary.md`** for field meanings and business rules.
-      - **Check `specs/03-Data-and-Storage/lcbp3-v1.8.0-seed-basic.sql`** to understand initial data states.
-      - **Check `specs/03-Data-and-Storage/lcbp3-v1.8.0-seed-permissions.sql`** to understand initial permissions states.
-      - **Check `specs/03-Data-and-Storage/03-04-legacy-data-migration.md`** for migration context (ADR-017).
-      - **Check `specs/03-Data-and-Storage/03-05-n8n-migration-setup-guide.md`** for n8n workflow setup.
-    - _Constraint:_ NEVER invent table names or columns. Use ONLY what is defined here.
+4.  **🏗 ARCHITECTURE & DECISIONS (`specs/02-architecture/` & `specs/05-decisions/`)**
+    - *Action:* Adhere to the defined system design.
+    - *Crucial:* Check `specs/05-decisions/` (ADRs) to ensure you do not violate previously agreed-upon technical decisions.
 
-5.  **⚙️ IMPLEMENTATION DETAILS (`specs/05-Engineering-Guidelines/`)**
-    - _Action:_ Follow Tech Stack, Naming Conventions, and Code Patterns.
+5.  **💾 DATABASE & SCHEMA (`specs/07-databasee/`)**
+    - *Action:* - **Read `specs/07-database/lcbp3-v1.5.1-schema.sql`** (or relevant `.sql` files) for exact table structures and constraints.
+        - **Consult `specs/database/data-dictionary-v1.5.1.md`** for field meanings and business rules.
+        - **Check `specs/database/lcbp3-v1.5.1-seed.sql`** to understand initial data states.
+    - *Constraint:* NEVER invent table names or columns. Use ONLY what is defined here.
 
-6.  **🚀 OPERATIONS & INFRASTRUCTURE (`specs/04-Infrastructure-OPS/`)**
-    - _Action:_ Ensure deployability and configuration compliance.
-    - _Constraint:_ Ensure deployment paths, port mappings, and volume mounts are consistent with this documentation.
+6.  **⚙️ IMPLEMENTATION DETAILS (`specs/03-implementation/`)**
+    - *Action:* Follow Tech Stack, Naming Conventions, and Code Patterns.
+
+7.  **🚀 OPERATIONS (`specs/04-operations/`)**
+    - *Action:* Ensure deployability and configuration compliance.
 
 ## Execution Rules
 
 ### 1. Citation Requirement
-
 When proposing a change or writing code, you must explicitly reference the source of truth:
-
-> "Implementing feature X per `specs/01-Requirements/` using pattern defined in `specs/05-Engineering-Guidelines/`."
+> "Implementing feature X per `specs/01-requirements/README.md` and `specs/01-requirements/**.md` using pattern defined in `specs/03-implementation/**.md`."
 
 ### 2. Conflict Resolution
-
 - **Spec vs. Training Data:** The `specs/` folder ALWAYS supersedes your general training data.
-- **Spec vs. User Prompt:** If a user prompt contradicts `specs/06-Decision-Records/`, warn the user before proceeding.
+- **Spec vs. User Prompt:** If a user prompt contradicts `specs/05-decisions/`, warn the user before proceeding.
 
 ### 3. File Generation
+- Do not create new files outside of the structure defined.
+- Keep the code style consistent with `specs/03-implementation/`.
 
-- Do not create new files outside of the established project structure:
-  - Backend: `backend/src/modules/<name>/`, `backend/src/common/`
-  - Frontend: `frontend/app/`, `frontend/components/`, `frontend/hooks/`, `frontend/lib/`
-  - Specs: `specs/` subdirectories only
-- Keep the code style consistent with `specs/05-Engineering-Guidelines/`.
-- New modules MUST follow the workflow in `.agents/workflows/create-backend-module.md` or `.agents/workflows/create-frontend-page.md`.
-
-### 4. Schema Changes
-
-- **DO NOT** create or run TypeORM migration files.
-- Modify the schema directly in `specs/03-Data-and-Storage/lcbp3-v1.8.0-schema-02-tables.sql` (or `01-drop`/`03-views-indexes` as appropriate).
-- Update `specs/03-Data-and-Storage/03-01-data-dictionary.md` if adding/changing columns.
-- Notify the user so they can apply the SQL change to the live database manually.
-- **AI Isolation (ADR-018):** Ollama runs on ASUSTOR only. AI has NO direct DB access, NO write access to uploads. All writes go through DMS API.
+### 4. Data Migration
+- Do not migrate. The schema can be modified directly.
 
 ---

.agent/rules/01-code-execution.md

@@ -1,38 +1,20 @@
 ---
 trigger: always_on
+---
+
+---
+
 description: Control which shell commands the agent may run automatically.
-allowAuto:
-  - 'pnpm test:watch'
-  - 'pnpm test:debug'
-  - 'pnpm test:e2e'
-  - 'git status'
-  - 'git log --oneline'
-  - 'git diff'
-  - 'git branch'
-  - 'tsc --noEmit'
-denyAuto:
-  - 'rm -rf'
-  - 'Remove-Item'
-  - 'git push --force'
-  - 'git reset --hard'
-  - 'git clean -fd'
-  - 'curl | bash'
-  - 'docker compose down'
-  - 'DROP TABLE'
-  - 'TRUNCATE'
-  - 'DELETE FROM'
+allowAuto: ["pnpm test:watch", "pnpm test:debug", "pnpm test:e2e", "git status"]
+denyAuto: ["rm -rf", "Remove-Item", "git push --force", "curl | bash"]
 alwaysReview: true
-scopes:
-  - 'backend/src/**'
-  - 'backend/test/**'
-  - 'frontend/app/**'
+scopes: ["backend/src/**", "backend/test/**", "frontend/app/**"]
+
 ---
 
 # Execution Rules
 
 - Only auto-execute commands that are explicitly listed in `allowAuto`.
-- Commands in `denyAuto` must always be blocked, even if manually requested.
-- All shell operations that create, modify, or delete files in `backend/src/`, `backend/test/`, or `frontend/app/` require human review.
-- Alert before running any SQL that modifies data (INSERT/UPDATE/DELETE/DROP/TRUNCATE).
-- Alert if environment variables related to DB connection or secrets (DATABASE_URL, JWT_SECRET, passwords) would be displayed or logged.
-- Never auto-execute commands that expose sensitive credentials via MCP tools or shell output.
+- Commands in denyAuto must always be blocked, even if manually requested.
+- All shell operations that create, modify, or delete files in `backend/src/` or `backend/test/` or `frontend/app/`require human review.
+- Alert if environment variables related to DB connection or secrets would be displayed or logged.

.agents/README.md

@@ -1,257 +0,0 @@
-# 🚀 Spec-Kit: Antigravity Skills & Workflows
-
-> **The Event Horizon of Software Quality.**
-> _Adapted for Google Antigravity IDE from [github/spec-kit](https://github.com/github/spec-kit)._
-> _Version: 1.1.0_
-
----
-
-## 🌟 Overview
-
-Welcome to the **Antigravity Edition** of Spec-Kit. This system is architected to empower your AI pair programmer (Antigravity) to drive the entire Software Development Life Cycle (SDLC) using two powerful mechanisms: **Workflows** and **Skills**.
-
-### 🔄 Dual-Mode Intelligence
-
-In this edition, Spec-Kit commands have been split into two interactive layers:
-
-1.  **Workflows (`/command`)**: High-level orchestrations that guide the agent through a series of logical steps. **The easiest way to run a skill is by typing its corresponding workflow command.**
-2.  **Skills (`@speckit.name`)**: Packaged agentic capabilities. Mentions of a skill give the agent immediate context and autonomous "know-how" to execute the specific toolset associated with that phase.
-
-> **To understand the power of Skills in Antigravity, read the docs here:**
-> [https://antigravity.google/docs/skills](https://antigravity.google/docs/skills)
-
----
-
-## 🛠️ Installation
-
-To enable these agent capabilities in your project:
-
-1.  **Add the folder**: Drop the `.agents/` folder into the root of your project workspace.
-2.  **That's it!** Antigravity automatically detects the `.agents/skills` and `.agents/workflows` directories. It will instantly gain the ability to perform Spec-Driven Development.
-
-> **💡 Compatibility Note:** This toolkit is compatible with multiple AI coding agents. To use with Claude Code, rename the `.agents` folder to `.claude`. The skills and workflows will function identically.
-
-### Prerequisites (Optional)
-
-Some skills and scripts reference a `.specify/` directory for templates and project memory. If you want the full Spec-Kit experience (template-driven spec/plan creation), create this structure at repo root:
-
-```text
-.specify/
-├── templates/
-│   ├── spec-template.md          # Template for /speckit.specify
-│   ├── plan-template.md          # Template for /speckit.plan
-│   ├── tasks-template.md         # Template for /speckit.tasks
-│   └── agent-file-template.md    # Template for update-agent-context.sh
-└── memory/
-    └── constitution.md           # Project governance rules (/speckit.constitution)
-```
-
-> **Note:** If `.specify/` is absent, skills will still function — they'll create blank files instead of using templates. The constitution workflow (`/speckit.constitution`) will create this structure for you on first run.
-
----
-
-## 🏗️ The Architecture
-
-The toolkit is organized into modular components that provide both the logic (Scripts) and the structure (Templates) for the agent.
-
-```text
-.agents/
-├── skills/                        # @ Mentions (Agent Intelligence)
-│   ├── nestjs-best-practices/     # NestJS Architecture Patterns
-│   ├── next-best-practices/       # Next.js App Router Patterns
-│   ├── speckit.analyze/           # Consistency Checker
-│   ├── speckit.checker/           # Static Analysis Aggregator
-│   ├── speckit.checklist/         # Requirements Validator
-│   ├── speckit.clarify/           # Ambiguity Resolver
-│   ├── speckit.constitution/      # Governance Manager
-│   ├── speckit.diff/              # Artifact Comparator
-│   ├── speckit.implement/         # Code Builder (Anti-Regression)
-│   ├── speckit.migrate/           # Legacy Code Migrator
-│   ├── speckit.plan/              # Technical Planner
-│   ├── speckit.quizme/            # Logic Challenger (Red Team)
-│   ├── speckit.reviewer/          # Code Reviewer
-│   ├── speckit.security-audit/    # Security Auditor (OWASP/CASL/ClamAV)
-│   ├── speckit.specify/           # Feature Definer
-│   ├── speckit.status/            # Progress Dashboard
-│   ├── speckit.tasks/             # Task Breaker
-│   ├── speckit.taskstoissues/     # Issue Tracker Syncer (GitHub + Gitea)
-│   ├── speckit.tester/            # Test Runner & Coverage
-│   └── speckit.validate/          # Implementation Validator
-│
-├── workflows/                     # / Slash Commands (Orchestration)
-│   ├── 00-speckit.all.md          # Full Pipeline (10 steps: Specify → Validate)
-│   ├── 01–11-speckit.*.md         # Individual phase workflows
-│   ├── speckit.prepare.md         # Prep Pipeline (5 steps: Specify → Analyze)
-│   ├── schema-change.md           # DB Schema Change (ADR-009)
-│   ├── create-backend-module.md   # NestJS Module Scaffolding
-│   ├── create-frontend-page.md    # Next.js Page Scaffolding
-│   ├── deploy.md                  # Deployment via Gitea CI/CD
-│   └── util-speckit.*.md          # Utilities (checklist, diff, migrate, etc.)
-│
-└── scripts/
-    ├── bash/                      # Bash Core (Kinetic logic)
-    │   ├── common.sh              # Shared utilities & path resolution
-    │   ├── check-prerequisites.sh # Prerequisite validation
-    │   ├── create-new-feature.sh  # Feature branch creation
-    │   ├── setup-plan.sh          # Plan template setup
-    │   ├── update-agent-context.sh # Agent file updater (main)
-    │   ├── plan-parser.sh         # Plan data extraction (module)
-    │   ├── content-generator.sh   # Language-specific templates (module)
-    │   └── agent-registry.sh      # 17-agent type registry (module)
-    ├── powershell/                 # PowerShell Equivalents (Windows-native)
-    │   ├── common.ps1             # Shared utilities & prerequisites
-    │   └── create-new-feature.ps1 # Feature branch creation
-    ├── fix_links.py               # Spec link fixer
-    ├── verify_links.py            # Spec link verifier
-    └── start-mcp.js               # MCP server launcher
-```
-
----
-
-## 🗺️ Mapping: Commands to Capabilities
-
-| Phase             | Workflow Trigger              | Antigravity Skill         | Role                                                    |
-| :---------------- | :---------------------------- | :------------------------ | :------------------------------------------------------ |
-| **Full Pipeline** | `/00-speckit.all`             | N/A                       | Runs full SDLC pipeline (10 steps: Specify → Validate). |
-| **Governance**    | `/01-speckit.constitution`    | `@speckit.constitution`   | Establishes project rules & principles.                 |
-| **Definition**    | `/02-speckit.specify`         | `@speckit.specify`        | Drafts structured `spec.md`.                            |
-| **Ambiguity**     | `/03-speckit.clarify`         | `@speckit.clarify`        | Resolves gaps post-spec.                                |
-| **Architecture**  | `/04-speckit.plan`            | `@speckit.plan`           | Generates technical `plan.md`.                          |
-| **Decomposition** | `/05-speckit.tasks`           | `@speckit.tasks`          | Breaks plans into atomic tasks.                         |
-| **Consistency**   | `/06-speckit.analyze`         | `@speckit.analyze`        | Cross-checks Spec vs Plan vs Tasks.                     |
-| **Execution**     | `/07-speckit.implement`       | `@speckit.implement`      | Builds implementation with safety protocols.            |
-| **Quality**       | `/08-speckit.checker`         | `@speckit.checker`        | Runs static analysis (Linting, Security, Types).        |
-| **Testing**       | `/09-speckit.tester`          | `@speckit.tester`         | Runs test suite & reports coverage.                     |
-| **Review**        | `/10-speckit.reviewer`        | `@speckit.reviewer`       | Performs code review (Logic, Perf, Style).              |
-| **Validation**    | `/11-speckit.validate`        | `@speckit.validate`       | Verifies implementation matches Spec requirements.      |
-| **Preparation**   | `/speckit.prepare`            | N/A                       | Runs Specify → Analyze prep sequence (5 steps).         |
-| **Schema**        | `/schema-change`              | N/A                       | DB schema changes per ADR-009 (no migrations).          |
-| **Security**      | N/A                           | `@speckit.security-audit` | OWASP Top 10 + CASL + ClamAV audit.                     |
-| **Checklist**     | `/util-speckit.checklist`     | `@speckit.checklist`      | Generates feature checklists.                           |
-| **Diff**          | `/util-speckit.diff`          | `@speckit.diff`           | Compares artifact versions.                             |
-| **Migration**     | `/util-speckit.migrate`       | `@speckit.migrate`        | Port existing code to Spec-Kit.                         |
-| **Red Team**      | `/util-speckit.quizme`        | `@speckit.quizme`         | Challenges logical flaws.                               |
-| **Status**        | `/util-speckit.status`        | `@speckit.status`         | Shows feature completion status.                        |
-| **Tracking**      | `/util-speckit.taskstoissues` | `@speckit.taskstoissues`  | Syncs tasks to GitHub/Gitea issues.                     |
-
----
-
-## 🛡️ The Quality Assurance Pipeline
-
-The following skills are designed to work together as a comprehensive defense against regression and poor quality. Run them in this order:
-
-| Step            | Skill               | Core Question                     | Focus                                                                                                                                                 |
-| :-------------- | :------------------ | :-------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **1. Checker**  | `@speckit.checker`  | _"Is the code compliant?"_        | **Syntax & Security**. Runs compilation, linting (ESLint/GolangCI), and vulnerability scans (npm audit/govulncheck). Catches low-level errors first.  |
-| **2. Tester**   | `@speckit.tester`   | _"Does it work?"_                 | **Functionality**. Executes your test suite (Jest/Pytest/Go Test) to ensure logic performs as expected and tests pass.                                |
-| **3. Reviewer** | `@speckit.reviewer` | _"Is the code written well?"_     | **Quality & Maintainability**. Analyzes code structure for complexity, performance bottlenecks, and best practices, acting as a senior peer reviewer. |
-| **4. Validate** | `@speckit.validate` | _"Did we build the right thing?"_ | **Requirements**. Semantically compares the implementation against the defined `spec.md` and `plan.md` to ensure all feature requirements are met.    |
-
-> **🤖 Power User Tip:** You can amplify this pipeline by creating a custom **MCP Server** or subagent that delegates heavy reasoning to a dedicated LLM.
->
-> - **Use Case:** Bind the `@speckit.validate` and `@speckit.reviewer` steps to a large-context model.
-> - **Benefit:** Large-context models (1M+ tokens) excel at analyzing the full project context against the Spec, finding subtle logical flaws that smaller models miss.
-> - **How:** Create a wrapper script `scripts/gemini-reviewer.sh` that pipes the `tasks.md` and codebase to an LLM, then expose this as a tool.
-
----
-
-## 🏗️ The Design & Management Pipeline
-
-These workflows function as the "Control Plane" of the project, managing everything from idea inception to status tracking.
-
-| Step               | Workflow                                            | Core Question         | Focus                                                                                                                                                        |
-| :----------------- | :-------------------------------------------------- | :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **1. Preparation** | `/speckit.prepare`                                  | _"Are we ready?"_     | **The Macro-Workflow**. Runs Skills 02–06 (Specify $\to$ Clarify $\to$ Plan $\to$ Tasks $\to$ Analyze) in one sequence to go from "Idea" to "Ready to Code". |
-| **2. Migration**   | `/util-speckit.migrate`                             | _"Can we import?"_    | **Onboarding**. Reverse-engineers existing code into `spec.md`, `plan.md`, and `tasks.md`.                                                                   |
-| **3. Red Team**    | `/util-speckit.quizme`                              | _"What did we miss?"_ | **Hardening**. Socratic questioning to find logical gaps in your specification before you plan.                                                              |
-| **4. Export**      | `/util-speckit.taskstoissues`                       | _"Who does what?"_    | **Handoff**. Converts your `tasks.md` into GitHub or Gitea issues with labels and milestones.                                                                |
-| **5. Status**      | `/util-speckit.status`                              | _"Are we there yet?"_ | **Tracking**. Scans all artifacts to report feature completion percentage.                                                                                   |
-| **6. Utilities**   | `/util-speckit.diff` <br> `/util-speckit.checklist` | _"What changed?"_     | **Support**. View artifact diffs or generate quick acceptance checklists.                                                                                    |
-
-### 🔄 The Design Sequence
-
-**Stage 1: Inception**
-
-- _Legacy Project?_ $\to$ Run **`/util-speckit.migrate`**.
-- _New Feature?_ $\to$ Run **`/speckit.prepare`**.
-
-**Stage 2: Hardening**
-
-- Run **`/util-speckit.quizme`** to catch edge cases.
-- Run **`/speckit.prepare`** again to regenerate the Plan based on restricted specs.
-
-**Stage 3: Handoff**
-
-- Run **`/util-speckit.taskstoissues`** to sync with your board.
-
----
-
-## 🚀 Getting Started in Antigravity
-
-Once the `.agents` folder is present, you can talk to your agent as a partner. You can trigger a full process using a slash command or reference a specific capability using a skill mention.
-
-**Example Conversation:**
-
-> **Developer**: "**/02-speckit.specify** Add a real-time notification system using WebSockets."
->
-> **Antigravity**: "Understood. Executing the **@speckit.specify** skill. Creating feature branch `005-notifications` and drafting the initial specification..."
-> _(Antigravity creates branch, drafts spec.md)_
->
-> **Antigravity**: "Specification ready. I've identified some ambiguity in the reconnection strategy. Should I use **@speckit.clarify** to resolve this?"
->
-> **Developer**: "Yes, use **@speckit.clarify**."
-> _(Antigravity executes the skill logic, interviewing the developer and updating the spec)_
->
-> **Antigravity**: "The spec is now robust. I'm ready to trigger **/04-speckit.plan** and **/05-speckit.tasks** to prepare for implementation."
-
----
-
-## 🏆 Best Practices for Antigravity
-
-To get the most out of this system, follow these **Spec-Driven Development (SDD)** rules:
-
-### 1. The Constitution is King 👑
-
-**Never skip `/01-speckit.constitution`.**
-
-- This file is the "Context Window Anchor" for the AI.
-- It prevents hallucinations about tech stack (e.g., "Don't use jQuery" or "Always use TypeScript strict mode").
-- **Tip:** If Antigravity makes a style mistake, don't just fix the code—update the Constitution so it never happens again.
-
-### 2. The Layered Defense 🛡️
-
-Don't rush to code. The workflow exists to catch errors _cheaply_ before they become expensive bugs.
-
-- **Ambiguity Layer**: `/03-speckit.clarify` catches misunderstandings.
-- **Logic Layer**: `/util-speckit.quizme` catches edge cases.
-- **Consistency Layer**: `/06-speckit.analyze` catches gaps between Spec and Plan.
-
-### 3. The 15-Minute Rule ⏱️
-
-When generating `tasks.md` (Skill 05), ensure tasks are **atomic**.
-
-- **Bad Task**: "Implement User Auth" (Too big, AI will get lost).
-- **Good Task**: "Create `User` Mongoose schema with email validation" (Perfect).
-- **Rule of Thumb**: If a task takes Antigravity more than 3 tool calls to finish, it's too big. Break it down.
-
-### 4. "Refine, Don't Rewind" ⏩
-
-If you change your mind mid-project:
-
-1.  Don't just edit the code.
-2.  Edit the `spec.md` to reflect the new requirement.
-3.  Run `/util-speckit.diff` to see the drift.
-4.  This keeps your documentation alive and truthful.
-
----
-
-## 🧩 Adaptation Notes
-
-- **Skill-Based Autonomy**: Mentions like `@speckit.plan` trigger the agent's internalized understanding of how to perform that role.
-- **Shared Script Core**: Logic resides in `.agents/scripts/bash` (modular) with PowerShell equivalents in `scripts/powershell/` for Windows-native execution.
-- **Agent-Native**: Designed to be invoked via Antigravity tool calls and reasoning rather than just terminal strings.
-- **LCBP3-DMS Specific**: Includes project-specific skills (`nestjs-best-practices`, `next-best-practices`, `speckit.security-audit`) and workflows (`/schema-change`, `/create-backend-module`, `/deploy`).
-
----
-
-_Built with logic from [Spec-Kit](https://github.com/github/spec-kit). Powered by Antigravity._

.agents/scripts/bash/agent-registry.sh

@@ -1,95 +0,0 @@
-#!/usr/bin/env bash
-# Agent registry — maps agent types to file paths and display names
-# Extracted from update-agent-context.sh for modularity
-#
-# Usage:
-#   source agent-registry.sh
-#   init_agent_registry "$REPO_ROOT"
-#   get_agent_file "claude"    # → /path/to/CLAUDE.md
-#   get_agent_name "claude"    # → "Claude Code"
-
-# Initialize agent file paths (call after REPO_ROOT is set)
-init_agent_registry() {
-    local repo_root="$1"
-
-    # Agent type → file path mapping
-    declare -gA AGENT_FILES=(
-        [claude]="$repo_root/CLAUDE.md"
-        [gemini]="$repo_root/GEMINI.md"
-        [copilot]="$repo_root/.github/agents/copilot-instructions.md"
-        [cursor-agent]="$repo_root/.cursor/rules/specify-rules.mdc"
-        [qwen]="$repo_root/QWEN.md"
-        [opencode]="$repo_root/AGENTS.md"
-        [codex]="$repo_root/AGENTS.md"
-        [windsurf]="$repo_root/.windsurf/rules/specify-rules.md"
-        [kilocode]="$repo_root/.kilocode/rules/specify-rules.md"
-        [auggie]="$repo_root/.augment/rules/specify-rules.md"
-        [roo]="$repo_root/.roo/rules/specify-rules.md"
-        [codebuddy]="$repo_root/CODEBUDDY.md"
-        [qoder]="$repo_root/QODER.md"
-        [amp]="$repo_root/AGENTS.md"
-        [shai]="$repo_root/SHAI.md"
-        [q]="$repo_root/AGENTS.md"
-        [bob]="$repo_root/AGENTS.md"
-    )
-
-    # Agent type → display name mapping
-    declare -gA AGENT_NAMES=(
-        [claude]="Claude Code"
-        [gemini]="Gemini CLI"
-        [copilot]="GitHub Copilot"
-        [cursor-agent]="Cursor IDE"
-        [qwen]="Qwen Code"
-        [opencode]="opencode"
-        [codex]="Codex CLI"
-        [windsurf]="Windsurf"
-        [kilocode]="Kilo Code"
-        [auggie]="Auggie CLI"
-        [roo]="Roo Code"
-        [codebuddy]="CodeBuddy CLI"
-        [qoder]="Qoder CLI"
-        [amp]="Amp"
-        [shai]="SHAI"
-        [q]="Amazon Q Developer CLI"
-        [bob]="IBM Bob"
-    )
-
-    # Template file path
-    TEMPLATE_FILE="$repo_root/.specify/templates/agent-file-template.md"
-}
-
-# Get file path for an agent type
-get_agent_file() {
-    local agent_type="$1"
-    echo "${AGENT_FILES[$agent_type]:-}"
-}
-
-# Get display name for an agent type
-get_agent_name() {
-    local agent_type="$1"
-    echo "${AGENT_NAMES[$agent_type]:-}"
-}
-
-# Get all registered agent types
-get_all_agent_types() {
-    echo "${!AGENT_FILES[@]}"
-}
-
-# Check if an agent type is valid
-is_valid_agent() {
-    local agent_type="$1"
-    [[ -n "${AGENT_FILES[$agent_type]:-}" ]]
-}
-
-# Get supported agent types as a pipe-separated string (for error messages)
-get_supported_agents_string() {
-    local result=""
-    for key in "${!AGENT_FILES[@]}"; do
-        if [[ -n "$result" ]]; then
-            result="$result|$key"
-        else
-            result="$key"
-        fi
-    done
-    echo "$result"
-}

.agents/scripts/bash/check-prerequisites.sh

@@ -1,166 +0,0 @@
-#!/usr/bin/env bash
-
-# Consolidated prerequisite checking script
-#
-# This script provides unified prerequisite checking for Spec-Driven Development workflow.
-# It replaces the functionality previously spread across multiple scripts.
-#
-# Usage: ./check-prerequisites.sh [OPTIONS]
-#
-# OPTIONS:
-#   --json              Output in JSON format
-#   --require-tasks     Require tasks.md to exist (for implementation phase)
-#   --include-tasks     Include tasks.md in AVAILABLE_DOCS list
-#   --paths-only        Only output path variables (no validation)
-#   --help, -h          Show help message
-#
-# OUTPUTS:
-#   JSON mode: {"FEATURE_DIR":"...", "AVAILABLE_DOCS":["..."]}
-#   Text mode: FEATURE_DIR:... \n AVAILABLE_DOCS: \n ✓/✗ file.md
-#   Paths only: REPO_ROOT: ... \n BRANCH: ... \n FEATURE_DIR: ... etc.
-
-set -e
-
-# Parse command line arguments
-JSON_MODE=false
-REQUIRE_TASKS=false
-INCLUDE_TASKS=false
-PATHS_ONLY=false
-
-for arg in "$@"; do
-    case "$arg" in
-        --json)
-            JSON_MODE=true
-            ;;
-        --require-tasks)
-            REQUIRE_TASKS=true
-            ;;
-        --include-tasks)
-            INCLUDE_TASKS=true
-            ;;
-        --paths-only)
-            PATHS_ONLY=true
-            ;;
-        --help|-h)
-            cat << 'EOF'
-Usage: check-prerequisites.sh [OPTIONS]
-
-Consolidated prerequisite checking for Spec-Driven Development workflow.
-
-OPTIONS:
-  --json              Output in JSON format
-  --require-tasks     Require tasks.md to exist (for implementation phase)
-  --include-tasks     Include tasks.md in AVAILABLE_DOCS list
-  --paths-only        Only output path variables (no prerequisite validation)
-  --help, -h          Show this help message
-
-EXAMPLES:
-  # Check task prerequisites (plan.md required)
-  ./check-prerequisites.sh --json
-  
-  # Check implementation prerequisites (plan.md + tasks.md required)
-  ./check-prerequisites.sh --json --require-tasks --include-tasks
-  
-  # Get feature paths only (no validation)
-  ./check-prerequisites.sh --paths-only
-  
-EOF
-            exit 0
-            ;;
-        *)
-            echo "ERROR: Unknown option '$arg'. Use --help for usage information." >&2
-            exit 1
-            ;;
-    esac
-done
-
-# Source common functions
-SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-source "$SCRIPT_DIR/common.sh"
-
-# Get feature paths and validate branch
-eval $(get_feature_paths)
-check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
-
-# If paths-only mode, output paths and exit (support JSON + paths-only combined)
-if $PATHS_ONLY; then
-    if $JSON_MODE; then
-        # Minimal JSON paths payload (no validation performed)
-        printf '{"REPO_ROOT":"%s","BRANCH":"%s","FEATURE_DIR":"%s","FEATURE_SPEC":"%s","IMPL_PLAN":"%s","TASKS":"%s"}\n' \
-            "$REPO_ROOT" "$CURRENT_BRANCH" "$FEATURE_DIR" "$FEATURE_SPEC" "$IMPL_PLAN" "$TASKS"
-    else
-        echo "REPO_ROOT: $REPO_ROOT"
-        echo "BRANCH: $CURRENT_BRANCH"
-        echo "FEATURE_DIR: $FEATURE_DIR"
-        echo "FEATURE_SPEC: $FEATURE_SPEC"
-        echo "IMPL_PLAN: $IMPL_PLAN"
-        echo "TASKS: $TASKS"
-    fi
-    exit 0
-fi
-
-# Validate required directories and files
-if [[ ! -d "$FEATURE_DIR" ]]; then
-    echo "ERROR: Feature directory not found: $FEATURE_DIR" >&2
-    echo "Run /speckit.specify first to create the feature structure." >&2
-    exit 1
-fi
-
-if [[ ! -f "$IMPL_PLAN" ]]; then
-    echo "ERROR: plan.md not found in $FEATURE_DIR" >&2
-    echo "Run /speckit.plan first to create the implementation plan." >&2
-    exit 1
-fi
-
-# Check for tasks.md if required
-if $REQUIRE_TASKS && [[ ! -f "$TASKS" ]]; then
-    echo "ERROR: tasks.md not found in $FEATURE_DIR" >&2
-    echo "Run /speckit.tasks first to create the task list." >&2
-    exit 1
-fi
-
-# Build list of available documents
-docs=()
-
-# Always check these optional docs
-[[ -f "$RESEARCH" ]] && docs+=("research.md")
-[[ -f "$DATA_MODEL" ]] && docs+=("data-model.md")
-
-# Check contracts directory (only if it exists and has files)
-if [[ -d "$CONTRACTS_DIR" ]] && [[ -n "$(ls -A "$CONTRACTS_DIR" 2>/dev/null)" ]]; then
-    docs+=("contracts/")
-fi
-
-[[ -f "$QUICKSTART" ]] && docs+=("quickstart.md")
-
-# Include tasks.md if requested and it exists
-if $INCLUDE_TASKS && [[ -f "$TASKS" ]]; then
-    docs+=("tasks.md")
-fi
-
-# Output results
-if $JSON_MODE; then
-    # Build JSON array of documents
-    if [[ ${#docs[@]} -eq 0 ]]; then
-        json_docs="[]"
-    else
-        json_docs=$(printf '"%s",' "${docs[@]}")
-        json_docs="[${json_docs%,}]"
-    fi
-    
-    printf '{"FEATURE_DIR":"%s","AVAILABLE_DOCS":%s}\n' "$FEATURE_DIR" "$json_docs"
-else
-    # Text output
-    echo "FEATURE_DIR:$FEATURE_DIR"
-    echo "AVAILABLE_DOCS:"
-    
-    # Show status of each potential document
-    check_file "$RESEARCH" "research.md"
-    check_file "$DATA_MODEL" "data-model.md"
-    check_dir "$CONTRACTS_DIR" "contracts/"
-    check_file "$QUICKSTART" "quickstart.md"
-    
-    if $INCLUDE_TASKS; then
-        check_file "$TASKS" "tasks.md"
-    fi
-fi

.agents/scripts/bash/common.sh

@@ -1,156 +0,0 @@
-#!/usr/bin/env bash
-# Common functions and variables for all scripts
-
-# Get repository root, with fallback for non-git repositories
-get_repo_root() {
-    if git rev-parse --show-toplevel >/dev/null 2>&1; then
-        git rev-parse --show-toplevel
-    else
-        # Fall back to script location for non-git repos
-        local script_dir="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-        (cd "$script_dir/../../.." && pwd)
-    fi
-}
-
-# Get current branch, with fallback for non-git repositories
-get_current_branch() {
-    # First check if SPECIFY_FEATURE environment variable is set
-    if [[ -n "${SPECIFY_FEATURE:-}" ]]; then
-        echo "$SPECIFY_FEATURE"
-        return
-    fi
-
-    # Then check git if available
-    if git rev-parse --abbrev-ref HEAD >/dev/null 2>&1; then
-        git rev-parse --abbrev-ref HEAD
-        return
-    fi
-
-    # For non-git repos, try to find the latest feature directory
-    local repo_root=$(get_repo_root)
-    local specs_dir="$repo_root/specs"
-
-    if [[ -d "$specs_dir" ]]; then
-        local latest_feature=""
-        local highest=0
-
-        for dir in "$specs_dir"/*; do
-            if [[ -d "$dir" ]]; then
-                local dirname=$(basename "$dir")
-                if [[ "$dirname" =~ ^([0-9]{3})- ]]; then
-                    local number=${BASH_REMATCH[1]}
-                    number=$((10#$number))
-                    if [[ "$number" -gt "$highest" ]]; then
-                        highest=$number
-                        latest_feature=$dirname
-                    fi
-                fi
-            fi
-        done
-
-        if [[ -n "$latest_feature" ]]; then
-            echo "$latest_feature"
-            return
-        fi
-    fi
-
-    echo "main"  # Final fallback
-}
-
-# Check if we have git available
-has_git() {
-    git rev-parse --show-toplevel >/dev/null 2>&1
-}
-
-check_feature_branch() {
-    local branch="$1"
-    local has_git_repo="$2"
-
-    # For non-git repos, we can't enforce branch naming but still provide output
-    if [[ "$has_git_repo" != "true" ]]; then
-        echo "[specify] Warning: Git repository not detected; skipped branch validation" >&2
-        return 0
-    fi
-
-    if [[ ! "$branch" =~ ^[0-9]{3}- ]]; then
-        echo "ERROR: Not on a feature branch. Current branch: $branch" >&2
-        echo "Feature branches should be named like: 001-feature-name" >&2
-        return 1
-    fi
-
-    return 0
-}
-
-get_feature_dir() { echo "$1/specs/$2"; }
-
-# Find feature directory by numeric prefix instead of exact branch match
-# This allows multiple branches to work on the same spec (e.g., 004-fix-bug, 004-add-feature)
-find_feature_dir_by_prefix() {
-    local repo_root="$1"
-    local branch_name="$2"
-    local specs_dir="$repo_root/specs"
-
-    # Extract numeric prefix from branch (e.g., "004" from "004-whatever")
-    if [[ ! "$branch_name" =~ ^([0-9]{3})- ]]; then
-        # If branch doesn't have numeric prefix, fall back to exact match
-        echo "$specs_dir/$branch_name"
-        return
-    fi
-
-    local prefix="${BASH_REMATCH[1]}"
-
-    # Search for directories in specs/ that start with this prefix
-    local matches=()
-    if [[ -d "$specs_dir" ]]; then
-        for dir in "$specs_dir"/"$prefix"-*; do
-            if [[ -d "$dir" ]]; then
-                matches+=("$(basename "$dir")")
-            fi
-        done
-    fi
-
-    # Handle results
-    if [[ ${#matches[@]} -eq 0 ]]; then
-        # No match found - return the branch name path (will fail later with clear error)
-        echo "$specs_dir/$branch_name"
-    elif [[ ${#matches[@]} -eq 1 ]]; then
-        # Exactly one match - perfect!
-        echo "$specs_dir/${matches[0]}"
-    else
-        # Multiple matches - this shouldn't happen with proper naming convention
-        echo "ERROR: Multiple spec directories found with prefix '$prefix': ${matches[*]}" >&2
-        echo "Please ensure only one spec directory exists per numeric prefix." >&2
-        echo "$specs_dir/$branch_name"  # Return something to avoid breaking the script
-    fi
-}
-
-get_feature_paths() {
-    local repo_root=$(get_repo_root)
-    local current_branch=$(get_current_branch)
-    local has_git_repo="false"
-
-    if has_git; then
-        has_git_repo="true"
-    fi
-
-    # Use prefix-based lookup to support multiple branches per spec
-    local feature_dir=$(find_feature_dir_by_prefix "$repo_root" "$current_branch")
-
-    cat <<EOF
-REPO_ROOT='$repo_root'
-CURRENT_BRANCH='$current_branch'
-HAS_GIT='$has_git_repo'
-FEATURE_DIR='$feature_dir'
-FEATURE_SPEC='$feature_dir/spec.md'
-IMPL_PLAN='$feature_dir/plan.md'
-TASKS='$feature_dir/tasks.md'
-RESEARCH='$feature_dir/research.md'
-DATA_MODEL='$feature_dir/data-model.md'
-QUICKSTART='$feature_dir/quickstart.md'
-CONTRACTS_DIR='$feature_dir/contracts'
-EOF
-}
-
-check_file() { [[ -f "$1" ]] && echo "  ✓ $2" || echo "  ✗ $2"; }
-check_dir() { [[ -d "$1" && -n $(ls -A "$1" 2>/dev/null) ]] && echo "  ✓ $2" || echo "  ✗ $2"; }
-

.agents/scripts/bash/content-generator.sh

@@ -1,40 +0,0 @@
-#!/usr/bin/env bash
-# Content generation functions for update-agent-context
-# Extracted from update-agent-context.sh for modularity
-
-# Get project directory structure based on project type
-get_project_structure() {
-    local project_type="$1"
-
-    if [[ "$project_type" == *"web"* ]]; then
-        echo "backend/\\nfrontend/\\ntests/"
-    else
-        echo "src/\\ntests/"
-    fi
-}
-
-# Get build/test commands for a given language
-get_commands_for_language() {
-    local lang="$1"
-
-    case "$lang" in
-        *"Python"*)
-            echo "cd src && pytest && ruff check ."
-            ;;
-        *"Rust"*)
-            echo "cargo test && cargo clippy"
-            ;;
-        *"JavaScript"*|*"TypeScript"*)
-            echo "npm test \\&\\& npm run lint"
-            ;;
-        *)
-            echo "# Add commands for $lang"
-            ;;
-    esac
-}
-
-# Get language-specific conventions string
-get_language_conventions() {
-    local lang="$1"
-    echo "$lang: Follow standard conventions"
-}

.agents/scripts/bash/create-new-feature.sh

@@ -1,297 +0,0 @@
-#!/usr/bin/env bash
-
-set -e
-
-JSON_MODE=false
-SHORT_NAME=""
-BRANCH_NUMBER=""
-ARGS=()
-i=1
-while [ $i -le $# ]; do
-    arg="${!i}"
-    case "$arg" in
-        --json) 
-            JSON_MODE=true 
-            ;;
-        --short-name)
-            if [ $((i + 1)) -gt $# ]; then
-                echo 'Error: --short-name requires a value' >&2
-                exit 1
-            fi
-            i=$((i + 1))
-            next_arg="${!i}"
-            # Check if the next argument is another option (starts with --)
-            if [[ "$next_arg" == --* ]]; then
-                echo 'Error: --short-name requires a value' >&2
-                exit 1
-            fi
-            SHORT_NAME="$next_arg"
-            ;;
-        --number)
-            if [ $((i + 1)) -gt $# ]; then
-                echo 'Error: --number requires a value' >&2
-                exit 1
-            fi
-            i=$((i + 1))
-            next_arg="${!i}"
-            if [[ "$next_arg" == --* ]]; then
-                echo 'Error: --number requires a value' >&2
-                exit 1
-            fi
-            BRANCH_NUMBER="$next_arg"
-            ;;
-        --help|-h) 
-            echo "Usage: $0 [--json] [--short-name <name>] [--number N] <feature_description>"
-            echo ""
-            echo "Options:"
-            echo "  --json              Output in JSON format"
-            echo "  --short-name <name> Provide a custom short name (2-4 words) for the branch"
-            echo "  --number N          Specify branch number manually (overrides auto-detection)"
-            echo "  --help, -h          Show this help message"
-            echo ""
-            echo "Examples:"
-            echo "  $0 'Add user authentication system' --short-name 'user-auth'"
-            echo "  $0 'Implement OAuth2 integration for API' --number 5"
-            exit 0
-            ;;
-        *) 
-            ARGS+=("$arg") 
-            ;;
-    esac
-    i=$((i + 1))
-done
-
-FEATURE_DESCRIPTION="${ARGS[*]}"
-if [ -z "$FEATURE_DESCRIPTION" ]; then
-    echo "Usage: $0 [--json] [--short-name <name>] [--number N] <feature_description>" >&2
-    exit 1
-fi
-
-# Function to find the repository root by searching for existing project markers
-find_repo_root() {
-    local dir="$1"
-    while [ "$dir" != "/" ]; do
-        if [ -d "$dir/.git" ] || [ -d "$dir/.specify" ]; then
-            echo "$dir"
-            return 0
-        fi
-        dir="$(dirname "$dir")"
-    done
-    return 1
-}
-
-# Function to get highest number from specs directory
-get_highest_from_specs() {
-    local specs_dir="$1"
-    local highest=0
-    
-    if [ -d "$specs_dir" ]; then
-        for dir in "$specs_dir"/*; do
-            [ -d "$dir" ] || continue
-            dirname=$(basename "$dir")
-            number=$(echo "$dirname" | grep -o '^[0-9]\+' || echo "0")
-            number=$((10#$number))
-            if [ "$number" -gt "$highest" ]; then
-                highest=$number
-            fi
-        done
-    fi
-    
-    echo "$highest"
-}
-
-# Function to get highest number from git branches
-get_highest_from_branches() {
-    local highest=0
-    
-    # Get all branches (local and remote)
-    branches=$(git branch -a 2>/dev/null || echo "")
-    
-    if [ -n "$branches" ]; then
-        while IFS= read -r branch; do
-            # Clean branch name: remove leading markers and remote prefixes
-            clean_branch=$(echo "$branch" | sed 's/^[* ]*//; s|^remotes/[^/]*/||')
-            
-            # Extract feature number if branch matches pattern ###-*
-            if echo "$clean_branch" | grep -q '^[0-9]\{3\}-'; then
-                number=$(echo "$clean_branch" | grep -o '^[0-9]\{3\}' || echo "0")
-                number=$((10#$number))
-                if [ "$number" -gt "$highest" ]; then
-                    highest=$number
-                fi
-            fi
-        done <<< "$branches"
-    fi
-    
-    echo "$highest"
-}
-
-# Function to check existing branches (local and remote) and return next available number
-check_existing_branches() {
-    local specs_dir="$1"
-
-    # Fetch all remotes to get latest branch info (suppress errors if no remotes)
-    git fetch --all --prune 2>/dev/null || true
-
-    # Get highest number from ALL branches (not just matching short name)
-    local highest_branch=$(get_highest_from_branches)
-
-    # Get highest number from ALL specs (not just matching short name)
-    local highest_spec=$(get_highest_from_specs "$specs_dir")
-
-    # Take the maximum of both
-    local max_num=$highest_branch
-    if [ "$highest_spec" -gt "$max_num" ]; then
-        max_num=$highest_spec
-    fi
-
-    # Return next number
-    echo $((max_num + 1))
-}
-
-# Function to clean and format a branch name
-clean_branch_name() {
-    local name="$1"
-    echo "$name" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/-\+/-/g' | sed 's/^-//' | sed 's/-$//'
-}
-
-# Resolve repository root. Prefer git information when available, but fall back
-# to searching for repository markers so the workflow still functions in repositories that
-# were initialised with --no-git.
-SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-
-if git rev-parse --show-toplevel >/dev/null 2>&1; then
-    REPO_ROOT=$(git rev-parse --show-toplevel)
-    HAS_GIT=true
-else
-    REPO_ROOT="$(find_repo_root "$SCRIPT_DIR")"
-    if [ -z "$REPO_ROOT" ]; then
-        echo "Error: Could not determine repository root. Please run this script from within the repository." >&2
-        exit 1
-    fi
-    HAS_GIT=false
-fi
-
-cd "$REPO_ROOT"
-
-SPECS_DIR="$REPO_ROOT/specs"
-mkdir -p "$SPECS_DIR"
-
-# Function to generate branch name with stop word filtering and length filtering
-generate_branch_name() {
-    local description="$1"
-    
-    # Common stop words to filter out
-    local stop_words="^(i|a|an|the|to|for|of|in|on|at|by|with|from|is|are|was|were|be|been|being|have|has|had|do|does|did|will|would|should|could|can|may|might|must|shall|this|that|these|those|my|your|our|their|want|need|add|get|set)$"
-    
-    # Convert to lowercase and split into words
-    local clean_name=$(echo "$description" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/ /g')
-    
-    # Filter words: remove stop words and words shorter than 3 chars (unless they're uppercase acronyms in original)
-    local meaningful_words=()
-    for word in $clean_name; do
-        # Skip empty words
-        [ -z "$word" ] && continue
-        
-        # Keep words that are NOT stop words AND (length >= 3 OR are potential acronyms)
-        if ! echo "$word" | grep -qiE "$stop_words"; then
-            if [ ${#word} -ge 3 ]; then
-                meaningful_words+=("$word")
-            elif echo "$description" | grep -q "\b${word^^}\b"; then
-                # Keep short words if they appear as uppercase in original (likely acronyms)
-                meaningful_words+=("$word")
-            fi
-        fi
-    done
-    
-    # If we have meaningful words, use first 3-4 of them
-    if [ ${#meaningful_words[@]} -gt 0 ]; then
-        local max_words=3
-        if [ ${#meaningful_words[@]} -eq 4 ]; then max_words=4; fi
-        
-        local result=""
-        local count=0
-        for word in "${meaningful_words[@]}"; do
-            if [ $count -ge $max_words ]; then break; fi
-            if [ -n "$result" ]; then result="$result-"; fi
-            result="$result$word"
-            count=$((count + 1))
-        done
-        echo "$result"
-    else
-        # Fallback to original logic if no meaningful words found
-        local cleaned=$(clean_branch_name "$description")
-        echo "$cleaned" | tr '-' '\n' | grep -v '^$' | head -3 | tr '\n' '-' | sed 's/-$//'
-    fi
-}
-
-# Generate branch name
-if [ -n "$SHORT_NAME" ]; then
-    # Use provided short name, just clean it up
-    BRANCH_SUFFIX=$(clean_branch_name "$SHORT_NAME")
-else
-    # Generate from description with smart filtering
-    BRANCH_SUFFIX=$(generate_branch_name "$FEATURE_DESCRIPTION")
-fi
-
-# Determine branch number
-if [ -z "$BRANCH_NUMBER" ]; then
-    if [ "$HAS_GIT" = true ]; then
-        # Check existing branches on remotes
-        BRANCH_NUMBER=$(check_existing_branches "$SPECS_DIR")
-    else
-        # Fall back to local directory check
-        HIGHEST=$(get_highest_from_specs "$SPECS_DIR")
-        BRANCH_NUMBER=$((HIGHEST + 1))
-    fi
-fi
-
-# Force base-10 interpretation to prevent octal conversion (e.g., 010 → 8 in octal, but should be 10 in decimal)
-FEATURE_NUM=$(printf "%03d" "$((10#$BRANCH_NUMBER))")
-BRANCH_NAME="${FEATURE_NUM}-${BRANCH_SUFFIX}"
-
-# GitHub enforces a 244-byte limit on branch names
-# Validate and truncate if necessary
-MAX_BRANCH_LENGTH=244
-if [ ${#BRANCH_NAME} -gt $MAX_BRANCH_LENGTH ]; then
-    # Calculate how much we need to trim from suffix
-    # Account for: feature number (3) + hyphen (1) = 4 chars
-    MAX_SUFFIX_LENGTH=$((MAX_BRANCH_LENGTH - 4))
-    
-    # Truncate suffix at word boundary if possible
-    TRUNCATED_SUFFIX=$(echo "$BRANCH_SUFFIX" | cut -c1-$MAX_SUFFIX_LENGTH)
-    # Remove trailing hyphen if truncation created one
-    TRUNCATED_SUFFIX=$(echo "$TRUNCATED_SUFFIX" | sed 's/-$//')
-    
-    ORIGINAL_BRANCH_NAME="$BRANCH_NAME"
-    BRANCH_NAME="${FEATURE_NUM}-${TRUNCATED_SUFFIX}"
-    
-    >&2 echo "[specify] Warning: Branch name exceeded GitHub's 244-byte limit"
-    >&2 echo "[specify] Original: $ORIGINAL_BRANCH_NAME (${#ORIGINAL_BRANCH_NAME} bytes)"
-    >&2 echo "[specify] Truncated to: $BRANCH_NAME (${#BRANCH_NAME} bytes)"
-fi
-
-if [ "$HAS_GIT" = true ]; then
-    git checkout -b "$BRANCH_NAME"
-else
-    >&2 echo "[specify] Warning: Git repository not detected; skipped branch creation for $BRANCH_NAME"
-fi
-
-FEATURE_DIR="$SPECS_DIR/$BRANCH_NAME"
-mkdir -p "$FEATURE_DIR"
-
-TEMPLATE="$REPO_ROOT/.specify/templates/spec-template.md"
-SPEC_FILE="$FEATURE_DIR/spec.md"
-if [ -f "$TEMPLATE" ]; then cp "$TEMPLATE" "$SPEC_FILE"; else touch "$SPEC_FILE"; fi
-
-# Set the SPECIFY_FEATURE environment variable for the current session
-export SPECIFY_FEATURE="$BRANCH_NAME"
-
-if $JSON_MODE; then
-    printf '{"BRANCH_NAME":"%s","SPEC_FILE":"%s","FEATURE_NUM":"%s"}\n' "$BRANCH_NAME" "$SPEC_FILE" "$FEATURE_NUM"
-else
-    echo "BRANCH_NAME: $BRANCH_NAME"
-    echo "SPEC_FILE: $SPEC_FILE"
-    echo "FEATURE_NUM: $FEATURE_NUM"
-    echo "SPECIFY_FEATURE environment variable set to: $BRANCH_NAME"
-fi

.agents/scripts/bash/plan-parser.sh

@@ -1,72 +0,0 @@
-#!/usr/bin/env bash
-# Plan parsing functions for update-agent-context
-# Extracted from update-agent-context.sh for modularity
-
-# Extract a field value from plan.md by pattern
-# Usage: extract_plan_field "Language/Version" "/path/to/plan.md"
-extract_plan_field() {
-    local field_pattern="$1"
-    local plan_file="$2"
-
-    grep "^\*\*${field_pattern}\*\*: " "$plan_file" 2>/dev/null | \
-        head -1 | \
-        sed "s|^\*\*${field_pattern}\*\*: ||" | \
-        sed 's/^[ \t]*//;s/[ \t]*$//' | \
-        grep -v "NEEDS CLARIFICATION" | \
-        grep -v "^N/A$" || echo ""
-}
-
-# Parse plan.md and set global variables: NEW_LANG, NEW_FRAMEWORK, NEW_DB, NEW_PROJECT_TYPE
-parse_plan_data() {
-    local plan_file="$1"
-
-    if [[ ! -f "$plan_file" ]]; then
-        log_error "Plan file not found: $plan_file"
-        return 1
-    fi
-
-    if [[ ! -r "$plan_file" ]]; then
-        log_error "Plan file is not readable: $plan_file"
-        return 1
-    fi
-
-    log_info "Parsing plan data from $plan_file"
-
-    NEW_LANG=$(extract_plan_field "Language/Version" "$plan_file")
-    NEW_FRAMEWORK=$(extract_plan_field "Primary Dependencies" "$plan_file")
-    NEW_DB=$(extract_plan_field "Storage" "$plan_file")
-    NEW_PROJECT_TYPE=$(extract_plan_field "Project Type" "$plan_file")
-
-    # Log what we found
-    if [[ -n "$NEW_LANG" ]]; then
-        log_info "Found language: $NEW_LANG"
-    else
-        log_warning "No language information found in plan"
-    fi
-
-    [[ -n "$NEW_FRAMEWORK" ]] && log_info "Found framework: $NEW_FRAMEWORK"
-    [[ -n "$NEW_DB" && "$NEW_DB" != "N/A" ]] && log_info "Found database: $NEW_DB"
-    [[ -n "$NEW_PROJECT_TYPE" ]] && log_info "Found project type: $NEW_PROJECT_TYPE"
-}
-
-# Format technology stack string from language and framework
-format_technology_stack() {
-    local lang="$1"
-    local framework="$2"
-    local parts=()
-
-    [[ -n "$lang" && "$lang" != "NEEDS CLARIFICATION" ]] && parts+=("$lang")
-    [[ -n "$framework" && "$framework" != "NEEDS CLARIFICATION" && "$framework" != "N/A" ]] && parts+=("$framework")
-
-    if [[ ${#parts[@]} -eq 0 ]]; then
-        echo ""
-    elif [[ ${#parts[@]} -eq 1 ]]; then
-        echo "${parts[0]}"
-    else
-        local result="${parts[0]}"
-        for ((i=1; i<${#parts[@]}; i++)); do
-            result="$result + ${parts[i]}"
-        done
-        echo "$result"
-    fi
-}

.agents/scripts/bash/setup-plan.sh

@@ -1,61 +0,0 @@
-#!/usr/bin/env bash
-
-set -e
-
-# Parse command line arguments
-JSON_MODE=false
-ARGS=()
-
-for arg in "$@"; do
-    case "$arg" in
-        --json) 
-            JSON_MODE=true 
-            ;;
-        --help|-h) 
-            echo "Usage: $0 [--json]"
-            echo "  --json    Output results in JSON format"
-            echo "  --help    Show this help message"
-            exit 0 
-            ;;
-        *) 
-            ARGS+=("$arg") 
-            ;;
-    esac
-done
-
-# Get script directory and load common functions
-SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-source "$SCRIPT_DIR/common.sh"
-
-# Get all paths and variables from common functions
-eval $(get_feature_paths)
-
-# Check if we're on a proper feature branch (only for git repos)
-check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
-
-# Ensure the feature directory exists
-mkdir -p "$FEATURE_DIR"
-
-# Copy plan template if it exists
-TEMPLATE="$REPO_ROOT/.specify/templates/plan-template.md"
-if [[ -f "$TEMPLATE" ]]; then
-    cp "$TEMPLATE" "$IMPL_PLAN"
-    echo "Copied plan template to $IMPL_PLAN"
-else
-    echo "Warning: Plan template not found at $TEMPLATE"
-    # Create a basic plan file if template doesn't exist
-    touch "$IMPL_PLAN"
-fi
-
-# Output results
-if $JSON_MODE; then
-    printf '{"FEATURE_SPEC":"%s","IMPL_PLAN":"%s","SPECS_DIR":"%s","BRANCH":"%s","HAS_GIT":"%s"}\n' \
-        "$FEATURE_SPEC" "$IMPL_PLAN" "$FEATURE_DIR" "$CURRENT_BRANCH" "$HAS_GIT"
-else
-    echo "FEATURE_SPEC: $FEATURE_SPEC"
-    echo "IMPL_PLAN: $IMPL_PLAN" 
-    echo "SPECS_DIR: $FEATURE_DIR"
-    echo "BRANCH: $CURRENT_BRANCH"
-    echo "HAS_GIT: $HAS_GIT"
-fi
-

.agents/scripts/bash/update-agent-context.sh

@@ -1,805 +0,0 @@
-#!/usr/bin/env bash
-
-# Update agent context files with information from plan.md
-#
-# This script maintains AI agent context files by parsing feature specifications
-# and updating agent-specific configuration files with project information.
-#
-# MAIN FUNCTIONS:
-# 1. Environment Validation
-#    - Verifies git repository structure and branch information
-#    - Checks for required plan.md files and templates
-#    - Validates file permissions and accessibility
-#
-# 2. Plan Data Extraction
-#    - Parses plan.md files to extract project metadata
-#    - Identifies language/version, frameworks, databases, and project types
-#    - Handles missing or incomplete specification data gracefully
-#
-# 3. Agent File Management
-#    - Creates new agent context files from templates when needed
-#    - Updates existing agent files with new project information
-#    - Preserves manual additions and custom configurations
-#    - Supports multiple AI agent formats and directory structures
-#
-# 4. Content Generation
-#    - Generates language-specific build/test commands
-#    - Creates appropriate project directory structures
-#    - Updates technology stacks and recent changes sections
-#    - Maintains consistent formatting and timestamps
-#
-# 5. Multi-Agent Support
-#    - Handles agent-specific file paths and naming conventions
-#    - Supports: Claude, Gemini, Copilot, Cursor, Qwen, opencode, Codex, Windsurf, Kilo Code, Auggie CLI, Roo Code, CodeBuddy CLI, Qoder CLI, Amp, SHAI, or Amazon Q Developer CLI
-#    - Can update single agents or all existing agent files
-#    - Creates default Claude file if no agent files exist
-#
-# Usage: ./update-agent-context.sh [agent_type]
-# Agent types: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|shai|q|bob|qoder
-# Leave empty to update all existing agent files
-
-set -e
-
-# Enable strict error handling
-set -u
-set -o pipefail
-
-#==============================================================================
-# Configuration and Global Variables
-#==============================================================================
-
-# Get script directory and load common functions
-SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-source "$SCRIPT_DIR/common.sh"
-
-# Load modular components (extracted for maintainability)
-# See each file for documentation of the functions it provides
-source "$SCRIPT_DIR/plan-parser.sh"        # extract_plan_field, parse_plan_data, format_technology_stack
-source "$SCRIPT_DIR/content-generator.sh"  # get_project_structure, get_commands_for_language, get_language_conventions
-source "$SCRIPT_DIR/agent-registry.sh"     # init_agent_registry, get_agent_file, get_agent_name, etc.
-
-# Get all paths and variables from common functions
-eval $(get_feature_paths)
-
-NEW_PLAN="$IMPL_PLAN"  # Alias for compatibility with existing code
-AGENT_TYPE="${1:-}"
-
-# Agent-specific file paths
-CLAUDE_FILE="$REPO_ROOT/CLAUDE.md"
-GEMINI_FILE="$REPO_ROOT/GEMINI.md"
-COPILOT_FILE="$REPO_ROOT/.github/agents/copilot-instructions.md"
-CURSOR_FILE="$REPO_ROOT/.cursor/rules/specify-rules.mdc"
-QWEN_FILE="$REPO_ROOT/QWEN.md"
-AGENTS_FILE="$REPO_ROOT/AGENTS.md"
-WINDSURF_FILE="$REPO_ROOT/.windsurf/rules/specify-rules.md"
-KILOCODE_FILE="$REPO_ROOT/.kilocode/rules/specify-rules.md"
-AUGGIE_FILE="$REPO_ROOT/.augment/rules/specify-rules.md"
-ROO_FILE="$REPO_ROOT/.roo/rules/specify-rules.md"
-CODEBUDDY_FILE="$REPO_ROOT/CODEBUDDY.md"
-QODER_FILE="$REPO_ROOT/QODER.md"
-AMP_FILE="$REPO_ROOT/AGENTS.md"
-SHAI_FILE="$REPO_ROOT/SHAI.md"
-Q_FILE="$REPO_ROOT/AGENTS.md"
-BOB_FILE="$REPO_ROOT/AGENTS.md"
-
-# Template file
-TEMPLATE_FILE="$REPO_ROOT/.specify/templates/agent-file-template.md"
-
-# Global variables for parsed plan data
-NEW_LANG=""
-NEW_FRAMEWORK=""
-NEW_DB=""
-NEW_PROJECT_TYPE=""
-
-#==============================================================================
-# Utility Functions
-#==============================================================================
-
-log_info() {
-    echo "INFO: $1"
-}
-
-log_success() {
-    echo "✓ $1"
-}
-
-log_error() {
-    echo "ERROR: $1" >&2
-}
-
-log_warning() {
-    echo "WARNING: $1" >&2
-}
-
-# Cleanup function for temporary files
-cleanup() {
-    local exit_code=$?
-    rm -f /tmp/agent_update_*_$$
-    rm -f /tmp/manual_additions_$$
-    exit $exit_code
-}
-
-# Set up cleanup trap
-trap cleanup EXIT INT TERM
-
-#==============================================================================
-# Validation Functions
-#==============================================================================
-
-validate_environment() {
-    # Check if we have a current branch/feature (git or non-git)
-    if [[ -z "$CURRENT_BRANCH" ]]; then
-        log_error "Unable to determine current feature"
-        if [[ "$HAS_GIT" == "true" ]]; then
-            log_info "Make sure you're on a feature branch"
-        else
-            log_info "Set SPECIFY_FEATURE environment variable or create a feature first"
-        fi
-        exit 1
-    fi
-
-    # Check if plan.md exists
-    if [[ ! -f "$NEW_PLAN" ]]; then
-        log_error "No plan.md found at $NEW_PLAN"
-        log_info "Make sure you're working on a feature with a corresponding spec directory"
-        if [[ "$HAS_GIT" != "true" ]]; then
-            log_info "Use: export SPECIFY_FEATURE=your-feature-name or create a new feature first"
-        fi
-        exit 1
-    fi
-
-    # Check if template exists (needed for new files)
-    if [[ ! -f "$TEMPLATE_FILE" ]]; then
-        log_warning "Template file not found at $TEMPLATE_FILE"
-        log_warning "Creating new agent files will fail"
-    fi
-}
-
-#==============================================================================
-# Plan Parsing Functions
-#==============================================================================
-
-extract_plan_field() {
-    local field_pattern="$1"
-    local plan_file="$2"
-
-    grep "^\*\*${field_pattern}\*\*: " "$plan_file" 2>/dev/null | \
-        head -1 | \
-        sed "s|^\*\*${field_pattern}\*\*: ||" | \
-        sed 's/^[ \t]*//;s/[ \t]*$//' | \
-        grep -v "NEEDS CLARIFICATION" | \
-        grep -v "^N/A$" || echo ""
-}
-
-parse_plan_data() {
-    local plan_file="$1"
-
-    if [[ ! -f "$plan_file" ]]; then
-        log_error "Plan file not found: $plan_file"
-        return 1
-    fi
-
-    if [[ ! -r "$plan_file" ]]; then
-        log_error "Plan file is not readable: $plan_file"
-        return 1
-    fi
-
-    log_info "Parsing plan data from $plan_file"
-
-    NEW_LANG=$(extract_plan_field "Language/Version" "$plan_file")
-    NEW_FRAMEWORK=$(extract_plan_field "Primary Dependencies" "$plan_file")
-    NEW_DB=$(extract_plan_field "Storage" "$plan_file")
-    NEW_PROJECT_TYPE=$(extract_plan_field "Project Type" "$plan_file")
-
-    # Log what we found
-    if [[ -n "$NEW_LANG" ]]; then
-        log_info "Found language: $NEW_LANG"
-    else
-        log_warning "No language information found in plan"
-    fi
-
-    if [[ -n "$NEW_FRAMEWORK" ]]; then
-        log_info "Found framework: $NEW_FRAMEWORK"
-    fi
-
-    if [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]]; then
-        log_info "Found database: $NEW_DB"
-    fi
-
-    if [[ -n "$NEW_PROJECT_TYPE" ]]; then
-        log_info "Found project type: $NEW_PROJECT_TYPE"
-    fi
-}
-
-format_technology_stack() {
-    local lang="$1"
-    local framework="$2"
-    local parts=()
-
-    # Add non-empty parts
-    [[ -n "$lang" && "$lang" != "NEEDS CLARIFICATION" ]] && parts+=("$lang")
-    [[ -n "$framework" && "$framework" != "NEEDS CLARIFICATION" && "$framework" != "N/A" ]] && parts+=("$framework")
-
-    # Join with proper formatting
-    if [[ ${#parts[@]} -eq 0 ]]; then
-        echo ""
-    elif [[ ${#parts[@]} -eq 1 ]]; then
-        echo "${parts[0]}"
-    else
-        # Join multiple parts with " + "
-        local result="${parts[0]}"
-        for ((i=1; i<${#parts[@]}; i++)); do
-            result="$result + ${parts[i]}"
-        done
-        echo "$result"
-    fi
-}
-
-#==============================================================================
-# Template and Content Generation Functions
-#==============================================================================
-
-get_project_structure() {
-    local project_type="$1"
-
-    if [[ "$project_type" == *"web"* ]]; then
-        echo "backend/\\nfrontend/\\ntests/"
-    else
-        echo "src/\\ntests/"
-    fi
-}
-
-get_commands_for_language() {
-    local lang="$1"
-
-    case "$lang" in
-        *"Python"*)
-            echo "cd src && pytest && ruff check ."
-            ;;
-        *"Rust"*)
-            echo "cargo test && cargo clippy"
-            ;;
-        *"JavaScript"*|*"TypeScript"*)
-            echo "npm test \\&\\& npm run lint"
-            ;;
-        *)
-            echo "# Add commands for $lang"
-            ;;
-    esac
-}
-
-get_language_conventions() {
-    local lang="$1"
-    echo "$lang: Follow standard conventions"
-}
-
-create_new_agent_file() {
-    local target_file="$1"
-    local temp_file="$2"
-    local project_name="$3"
-    local current_date="$4"
-
-    if [[ ! -f "$TEMPLATE_FILE" ]]; then
-        log_error "Template not found at $TEMPLATE_FILE"
-        return 1
-    fi
-
-    if [[ ! -r "$TEMPLATE_FILE" ]]; then
-        log_error "Template file is not readable: $TEMPLATE_FILE"
-        return 1
-    fi
-
-    log_info "Creating new agent context file from template..."
-
-    if ! cp "$TEMPLATE_FILE" "$temp_file"; then
-        log_error "Failed to copy template file"
-        return 1
-    fi
-
-    # Replace template placeholders
-    local project_structure
-    project_structure=$(get_project_structure "$NEW_PROJECT_TYPE")
-
-    local commands
-    commands=$(get_commands_for_language "$NEW_LANG")
-
-    local language_conventions
-    language_conventions=$(get_language_conventions "$NEW_LANG")
-
-    # Perform substitutions with error checking using safer approach
-    # Escape special characters for sed by using a different delimiter or escaping
-    local escaped_lang=$(printf '%s\n' "$NEW_LANG" | sed 's/[\[\.*^$()+{}|]/\\&/g')
-    local escaped_framework=$(printf '%s\n' "$NEW_FRAMEWORK" | sed 's/[\[\.*^$()+{}|]/\\&/g')
-    local escaped_branch=$(printf '%s\n' "$CURRENT_BRANCH" | sed 's/[\[\.*^$()+{}|]/\\&/g')
-
-    # Build technology stack and recent change strings conditionally
-    local tech_stack
-    if [[ -n "$escaped_lang" && -n "$escaped_framework" ]]; then
-        tech_stack="- $escaped_lang + $escaped_framework ($escaped_branch)"
-    elif [[ -n "$escaped_lang" ]]; then
-        tech_stack="- $escaped_lang ($escaped_branch)"
-    elif [[ -n "$escaped_framework" ]]; then
-        tech_stack="- $escaped_framework ($escaped_branch)"
-    else
-        tech_stack="- ($escaped_branch)"
-    fi
-
-    local recent_change
-    if [[ -n "$escaped_lang" && -n "$escaped_framework" ]]; then
-        recent_change="- $escaped_branch: Added $escaped_lang + $escaped_framework"
-    elif [[ -n "$escaped_lang" ]]; then
-        recent_change="- $escaped_branch: Added $escaped_lang"
-    elif [[ -n "$escaped_framework" ]]; then
-        recent_change="- $escaped_branch: Added $escaped_framework"
-    else
-        recent_change="- $escaped_branch: Added"
-    fi
-
-    local substitutions=(
-        "s|\[PROJECT NAME\]|$project_name|"
-        "s|\[DATE\]|$current_date|"
-        "s|\[EXTRACTED FROM ALL PLAN.MD FILES\]|$tech_stack|"
-        "s|\[ACTUAL STRUCTURE FROM PLANS\]|$project_structure|g"
-        "s|\[ONLY COMMANDS FOR ACTIVE TECHNOLOGIES\]|$commands|"
-        "s|\[LANGUAGE-SPECIFIC, ONLY FOR LANGUAGES IN USE\]|$language_conventions|"
-        "s|\[LAST 3 FEATURES AND WHAT THEY ADDED\]|$recent_change|"
-    )
-
-    for substitution in "${substitutions[@]}"; do
-        if ! sed -i.bak -e "$substitution" "$temp_file"; then
-            log_error "Failed to perform substitution: $substitution"
-            rm -f "$temp_file" "$temp_file.bak"
-            return 1
-        fi
-    done
-
-    # Convert \n sequences to actual newlines
-    newline=$(printf '\n')
-    sed -i.bak2 "s/\\\\n/${newline}/g" "$temp_file"
-
-    # Clean up backup files
-    rm -f "$temp_file.bak" "$temp_file.bak2"
-
-    return 0
-}
-
-
-
-
-update_existing_agent_file() {
-    local target_file="$1"
-    local current_date="$2"
-
-    log_info "Updating existing agent context file..."
-
-    # Use a single temporary file for atomic update
-    local temp_file
-    temp_file=$(mktemp) || {
-        log_error "Failed to create temporary file"
-        return 1
-    }
-
-    # Process the file in one pass
-    local tech_stack=$(format_technology_stack "$NEW_LANG" "$NEW_FRAMEWORK")
-    local new_tech_entries=()
-    local new_change_entry=""
-
-    # Prepare new technology entries
-    if [[ -n "$tech_stack" ]] && ! grep -q "$tech_stack" "$target_file"; then
-        new_tech_entries+=("- $tech_stack ($CURRENT_BRANCH)")
-    fi
-
-    if [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]] && [[ "$NEW_DB" != "NEEDS CLARIFICATION" ]] && ! grep -q "$NEW_DB" "$target_file"; then
-        new_tech_entries+=("- $NEW_DB ($CURRENT_BRANCH)")
-    fi
-
-    # Prepare new change entry
-    if [[ -n "$tech_stack" ]]; then
-        new_change_entry="- $CURRENT_BRANCH: Added $tech_stack"
-    elif [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]] && [[ "$NEW_DB" != "NEEDS CLARIFICATION" ]]; then
-        new_change_entry="- $CURRENT_BRANCH: Added $NEW_DB"
-    fi
-
-    # Check if sections exist in the file
-    local has_active_technologies=0
-    local has_recent_changes=0
-
-    if grep -q "^## Active Technologies" "$target_file" 2>/dev/null; then
-        has_active_technologies=1
-    fi
-
-    if grep -q "^## Recent Changes" "$target_file" 2>/dev/null; then
-        has_recent_changes=1
-    fi
-
-    # Process file line by line
-    local in_tech_section=false
-    local in_changes_section=false
-    local tech_entries_added=false
-    local changes_entries_added=false
-    local existing_changes_count=0
-    local file_ended=false
-
-    while IFS= read -r line || [[ -n "$line" ]]; do
-        # Handle Active Technologies section
-        if [[ "$line" == "## Active Technologies" ]]; then
-            echo "$line" >> "$temp_file"
-            in_tech_section=true
-            continue
-        elif [[ $in_tech_section == true ]] && [[ "$line" =~ ^##[[:space:]] ]]; then
-            # Add new tech entries before closing the section
-            if [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
-                printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
-                tech_entries_added=true
-            fi
-            echo "$line" >> "$temp_file"
-            in_tech_section=false
-            continue
-        elif [[ $in_tech_section == true ]] && [[ -z "$line" ]]; then
-            # Add new tech entries before empty line in tech section
-            if [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
-                printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
-                tech_entries_added=true
-            fi
-            echo "$line" >> "$temp_file"
-            continue
-        fi
-
-        # Handle Recent Changes section
-        if [[ "$line" == "## Recent Changes" ]]; then
-            echo "$line" >> "$temp_file"
-            # Add new change entry right after the heading
-            if [[ -n "$new_change_entry" ]]; then
-                echo "$new_change_entry" >> "$temp_file"
-            fi
-            in_changes_section=true
-            changes_entries_added=true
-            continue
-        elif [[ $in_changes_section == true ]] && [[ "$line" =~ ^##[[:space:]] ]]; then
-            echo "$line" >> "$temp_file"
-            in_changes_section=false
-            continue
-        elif [[ $in_changes_section == true ]] && [[ "$line" == "- "* ]]; then
-            # Keep only first 2 existing changes
-            if [[ $existing_changes_count -lt 2 ]]; then
-                echo "$line" >> "$temp_file"
-                ((existing_changes_count++))
-            fi
-            continue
-        fi
-
-        # Update timestamp
-        if [[ "$line" =~ \*\*Last\ updated\*\*:.*[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9] ]]; then
-            echo "$line" | sed "s/[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]/$current_date/" >> "$temp_file"
-        else
-            echo "$line" >> "$temp_file"
-        fi
-    done < "$target_file"
-
-    # Post-loop check: if we're still in the Active Technologies section and haven't added new entries
-    if [[ $in_tech_section == true ]] && [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
-        printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
-        tech_entries_added=true
-    fi
-
-    # If sections don't exist, add them at the end of the file
-    if [[ $has_active_technologies -eq 0 ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
-        echo "" >> "$temp_file"
-        echo "## Active Technologies" >> "$temp_file"
-        printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
-        tech_entries_added=true
-    fi
-
-    if [[ $has_recent_changes -eq 0 ]] && [[ -n "$new_change_entry" ]]; then
-        echo "" >> "$temp_file"
-        echo "## Recent Changes" >> "$temp_file"
-        echo "$new_change_entry" >> "$temp_file"
-        changes_entries_added=true
-    fi
-
-    # Move temp file to target atomically
-    if ! mv "$temp_file" "$target_file"; then
-        log_error "Failed to update target file"
-        rm -f "$temp_file"
-        return 1
-    fi
-
-    return 0
-}
-#==============================================================================
-# Main Agent File Update Function
-#==============================================================================
-
-update_agent_file() {
-    local target_file="$1"
-    local agent_name="$2"
-
-    if [[ -z "$target_file" ]] || [[ -z "$agent_name" ]]; then
-        log_error "update_agent_file requires target_file and agent_name parameters"
-        return 1
-    fi
-
-    log_info "Updating $agent_name context file: $target_file"
-
-    local project_name
-    project_name=$(basename "$REPO_ROOT")
-    local current_date
-    current_date=$(date +%Y-%m-%d)
-
-    # Create directory if it doesn't exist
-    local target_dir
-    target_dir=$(dirname "$target_file")
-    if [[ ! -d "$target_dir" ]]; then
-        if ! mkdir -p "$target_dir"; then
-            log_error "Failed to create directory: $target_dir"
-            return 1
-        fi
-    fi
-
-    if [[ ! -f "$target_file" ]]; then
-        # Create new file from template
-        local temp_file
-        temp_file=$(mktemp) || {
-            log_error "Failed to create temporary file"
-            return 1
-        }
-
-        if create_new_agent_file "$target_file" "$temp_file" "$project_name" "$current_date"; then
-            if mv "$temp_file" "$target_file"; then
-                log_success "Created new $agent_name context file"
-            else
-                log_error "Failed to move temporary file to $target_file"
-                rm -f "$temp_file"
-                return 1
-            fi
-        else
-            log_error "Failed to create new agent file"
-            rm -f "$temp_file"
-            return 1
-        fi
-    else
-        # Update existing file
-        if [[ ! -r "$target_file" ]]; then
-            log_error "Cannot read existing file: $target_file"
-            return 1
-        fi
-
-        if [[ ! -w "$target_file" ]]; then
-            log_error "Cannot write to existing file: $target_file"
-            return 1
-        fi
-
-        if update_existing_agent_file "$target_file" "$current_date"; then
-            log_success "Updated existing $agent_name context file"
-        else
-            log_error "Failed to update existing agent file"
-            return 1
-        fi
-    fi
-
-    return 0
-}
-
-#==============================================================================
-# Agent Selection and Processing
-#==============================================================================
-
-update_specific_agent() {
-    local agent_type="$1"
-
-    case "$agent_type" in
-        claude)
-            update_agent_file "$CLAUDE_FILE" "Claude Code"
-            ;;
-        gemini)
-            update_agent_file "$GEMINI_FILE" "Gemini CLI"
-            ;;
-        copilot)
-            update_agent_file "$COPILOT_FILE" "GitHub Copilot"
-            ;;
-        cursor-agent)
-            update_agent_file "$CURSOR_FILE" "Cursor IDE"
-            ;;
-        qwen)
-            update_agent_file "$QWEN_FILE" "Qwen Code"
-            ;;
-        opencode)
-            update_agent_file "$AGENTS_FILE" "opencode"
-            ;;
-        codex)
-            update_agent_file "$AGENTS_FILE" "Codex CLI"
-            ;;
-        windsurf)
-            update_agent_file "$WINDSURF_FILE" "Windsurf"
-            ;;
-        kilocode)
-            update_agent_file "$KILOCODE_FILE" "Kilo Code"
-            ;;
-        auggie)
-            update_agent_file "$AUGGIE_FILE" "Auggie CLI"
-            ;;
-        roo)
-            update_agent_file "$ROO_FILE" "Roo Code"
-            ;;
-        codebuddy)
-            update_agent_file "$CODEBUDDY_FILE" "CodeBuddy CLI"
-            ;;
-        qoder)
-            update_agent_file "$QODER_FILE" "Qoder CLI"
-            ;;
-        amp)
-            update_agent_file "$AMP_FILE" "Amp"
-            ;;
-        shai)
-            update_agent_file "$SHAI_FILE" "SHAI"
-            ;;
-        q)
-            update_agent_file "$Q_FILE" "Amazon Q Developer CLI"
-            ;;
-        bob)
-            update_agent_file "$BOB_FILE" "IBM Bob"
-            ;;
-        *)
-            log_error "Unknown agent type '$agent_type'"
-            log_error "Expected: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|amp|shai|q|bob|qoder"
-            exit 1
-            ;;
-    esac
-}
-
-update_all_existing_agents() {
-    local found_agent=false
-
-    # Check each possible agent file and update if it exists
-    if [[ -f "$CLAUDE_FILE" ]]; then
-        update_agent_file "$CLAUDE_FILE" "Claude Code"
-        found_agent=true
-    fi
-
-    if [[ -f "$GEMINI_FILE" ]]; then
-        update_agent_file "$GEMINI_FILE" "Gemini CLI"
-        found_agent=true
-    fi
-
-    if [[ -f "$COPILOT_FILE" ]]; then
-        update_agent_file "$COPILOT_FILE" "GitHub Copilot"
-        found_agent=true
-    fi
-
-    if [[ -f "$CURSOR_FILE" ]]; then
-        update_agent_file "$CURSOR_FILE" "Cursor IDE"
-        found_agent=true
-    fi
-
-    if [[ -f "$QWEN_FILE" ]]; then
-        update_agent_file "$QWEN_FILE" "Qwen Code"
-        found_agent=true
-    fi
-
-    if [[ -f "$AGENTS_FILE" ]]; then
-        update_agent_file "$AGENTS_FILE" "Codex/opencode"
-        found_agent=true
-    fi
-
-    if [[ -f "$WINDSURF_FILE" ]]; then
-        update_agent_file "$WINDSURF_FILE" "Windsurf"
-        found_agent=true
-    fi
-
-    if [[ -f "$KILOCODE_FILE" ]]; then
-        update_agent_file "$KILOCODE_FILE" "Kilo Code"
-        found_agent=true
-    fi
-
-    if [[ -f "$AUGGIE_FILE" ]]; then
-        update_agent_file "$AUGGIE_FILE" "Auggie CLI"
-        found_agent=true
-    fi
-
-    if [[ -f "$ROO_FILE" ]]; then
-        update_agent_file "$ROO_FILE" "Roo Code"
-        found_agent=true
-    fi
-
-    if [[ -f "$CODEBUDDY_FILE" ]]; then
-        update_agent_file "$CODEBUDDY_FILE" "CodeBuddy CLI"
-        found_agent=true
-    fi
-
-    if [[ -f "$SHAI_FILE" ]]; then
-        update_agent_file "$SHAI_FILE" "SHAI"
-        found_agent=true
-    fi
-
-    if [[ -f "$QODER_FILE" ]]; then
-        update_agent_file "$QODER_FILE" "Qoder CLI"
-        found_agent=true
-    fi
-
-    if [[ -f "$Q_FILE" ]]; then
-        update_agent_file "$Q_FILE" "Amazon Q Developer CLI"
-        found_agent=true
-    fi
-
-    if [[ -f "$BOB_FILE" ]]; then
-        update_agent_file "$BOB_FILE" "IBM Bob"
-        found_agent=true
-    fi
-
-    # If no agent files exist, create a default Claude file
-    if [[ "$found_agent" == false ]]; then
-        log_info "No existing agent files found, creating default Claude file..."
-        update_agent_file "$CLAUDE_FILE" "Claude Code"
-    fi
-}
-print_summary() {
-    echo
-    log_info "Summary of changes:"
-
-    if [[ -n "$NEW_LANG" ]]; then
-        echo "  - Added language: $NEW_LANG"
-    fi
-
-    if [[ -n "$NEW_FRAMEWORK" ]]; then
-        echo "  - Added framework: $NEW_FRAMEWORK"
-    fi
-
-    if [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]]; then
-        echo "  - Added database: $NEW_DB"
-    fi
-
-    echo
-
-    log_info "Usage: $0 [claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|codebuddy|shai|q|bob|qoder]"
-}
-
-#==============================================================================
-# Main Execution
-#==============================================================================
-
-main() {
-    # Validate environment before proceeding
-    validate_environment
-
-    log_info "=== Updating agent context files for feature $CURRENT_BRANCH ==="
-
-    # Parse the plan file to extract project information
-    if ! parse_plan_data "$NEW_PLAN"; then
-        log_error "Failed to parse plan data"
-        exit 1
-    fi
-
-    # Process based on agent type argument
-    local success=true
-
-    if [[ -z "$AGENT_TYPE" ]]; then
-        # No specific agent provided - update all existing agent files
-        log_info "No agent specified, updating all existing agent files..."
-        if ! update_all_existing_agents; then
-            success=false
-        fi
-    else
-        # Specific agent provided - update only that agent
-        log_info "Updating specific agent: $AGENT_TYPE"
-        if ! update_specific_agent "$AGENT_TYPE"; then
-            success=false
-        fi
-    fi
-
-    # Print summary
-    print_summary
-
-    if [[ "$success" == true ]]; then
-        log_success "Agent context update completed successfully"
-        exit 0
-    else
-        log_error "Agent context update completed with errors"
-        exit 1
-    fi
-}
-
-# Execute main function if script is run directly
-if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
-    main "$@"
-fi
-

.agents/scripts/fix_links.py

@@ -1,135 +0,0 @@
-import os
-import re
-import sys
-from pathlib import Path
-
-# Configuration - default base directory, can be overridden via CLI argument
-DEFAULT_BASE_DIR = Path(__file__).resolve().parent.parent.parent / "specs"
-
-DIRECTORIES = [
-    "00-Overview",
-    "01-Requirements",
-    "02-Architecture",
-    "03-Data-and-Storage",
-    "04-Infrastructure-OPS",
-    "05-Engineering-Guidelines",
-    "06-Decision-Records"
-]
-
-LINK_PATTERN = re.compile(r'(\[([^\]]+)\]\(([^)]+)\))')
-
-def get_file_map(base_dir: Path):
-    """Builds a map of {basename}.md -> {prefixed_name}.md across all dirs."""
-    file_map = {}
-    for dir_name in DIRECTORIES:
-        directory = base_dir / dir_name
-        if not directory.exists():
-            continue
-        for file_path in directory.glob("*.md"):
-            actual_name = file_path.name
-            low_name = actual_name.lower()
-
-            # 1. Map actual name
-            file_map[low_name] = f"{dir_name}/{actual_name}"
-
-            # 2. Try to strip prefixes to find base names
-            strip_patterns = [
-                r'^\d+-\d+\.?\d*-?(.*)', # 01-03.1- or 01-01-
-                r'^\d+-(.*)',           # 04-
-                r'^ADR-\d+-(.*)',       # ADR-001-
-            ]
-
-            for pattern in strip_patterns:
-                match = re.match(pattern, actual_name)
-                if match:
-                    base_name = match.group(1).lower()
-                    if base_name:
-                        file_map[base_name] = f"{dir_name}/{actual_name}"
-
-                    # Also map partials like "03.1-project-management.md"
-                    # if the original was "01-03.1-project-management.md"
-                    if pattern == r'^\d+-\d+\.?\d*-?(.*)':
-                        secondary_match = re.match(r'^\d+-(.*)', actual_name)
-                        if secondary_match:
-                            secondary_base = secondary_match.group(1).lower()
-                            if secondary_base:
-                                file_map[secondary_base] = f"{dir_name}/{actual_name}"
-
-    return file_map
-
-def fix_links(base_dir: Path):
-    file_map = get_file_map(base_dir)
-    changes_made = 0
-
-    for dir_name in DIRECTORIES:
-        directory = base_dir / dir_name
-        if not directory.exists():
-            continue
-
-        for file_path in directory.glob("*.md"):
-            with open(file_path, "r", encoding="utf-8") as f:
-                content = f.read()
-
-            new_content = content
-            original_links = LINK_PATTERN.findall(content)
-
-            for full_match, label, target in original_links:
-                if target.startswith("http") or target.startswith("#"):
-                    continue
-
-                # Check if broken
-                target_path = target.split("#")[0]
-                if not target_path:
-                    continue
-
-                # Special case: file:/// absolute paths
-                clean_target_path = re.sub(
-                    r'^file:///[a-zA-Z]:[/\\].*?specs[/\\]',
-                    '',
-                    target_path
-                )
-
-                resolved_locally = (file_path.parent / target_path).resolve()
-                if resolved_locally.exists() and resolved_locally.is_file():
-                    continue # Not broken
-
-                # It's broken, try to fix it
-                target_filename = Path(clean_target_path).name.lower()
-                if target_filename in file_map:
-                    correct_relative_to_specs = file_map[target_filename]
-                    # Calculate relative path from current file's parent to the correct file
-                    correct_abs = (base_dir / correct_relative_to_specs).resolve()
-
-                    try:
-                        new_relative_path = os.path.relpath(correct_abs, file_path.parent).replace(os.sep, "/")
-                        # Re-add anchor if it was there
-                        anchor = target.split("#")[1] if "#" in target else ""
-                        new_target = new_relative_path + (f"#{anchor}" if anchor else "")
-
-                        # Replace in content
-                        old_link = f"({target})"
-                        new_link = f"({new_target})"
-                        new_content = new_content.replace(old_link, new_link)
-                        print(f"Fixed in {file_path.name}: {target} -> {new_target}")
-                    except ValueError:
-                        print(f"Error calculating relpath for {correct_abs} from {file_path.parent}")
-
-            if new_content != content:
-                with open(file_path, "w", encoding="utf-8") as f:
-                    f.write(new_content)
-                changes_made += 1
-
-    print(f"\nTotal files updated: {changes_made}")
-
-if __name__ == "__main__":
-    if len(sys.argv) > 1:
-        base_dir = Path(sys.argv[1])
-    else:
-        base_dir = DEFAULT_BASE_DIR
-
-    if not base_dir.exists():
-        print(f"Error: Directory not found: {base_dir}", file=sys.stderr)
-        sys.exit(1)
-
-    print(f"Scanning specs directory: {base_dir}")
-    fix_links(base_dir)

.agents/scripts/powershell/common.ps1

@@ -1,157 +0,0 @@
-# PowerShell equivalents for key .agents bash scripts
-# These provide Windows-native alternatives for the most commonly used functions
-
-<#
-.SYNOPSIS
-    Common utility functions for Spec-Kit PowerShell scripts.
-.DESCRIPTION
-    PowerShell equivalent of .agents/scripts/bash/common.sh
-    Provides repository root detection, branch identification, and feature path resolution.
-#>
-
-function Get-RepoRoot {
-    try {
-        $root = git rev-parse --show-toplevel 2>$null
-        if ($LASTEXITCODE -eq 0) { return $root.Trim() }
-    } catch {}
-    # Fallback: navigate up from script location
-    return (Resolve-Path "$PSScriptRoot\..\..\..").Path
-}
-
-function Get-CurrentBranch {
-    # Check environment variable first
-    if ($env:SPECIFY_FEATURE) { return $env:SPECIFY_FEATURE }
-
-    try {
-        $branch = git rev-parse --abbrev-ref HEAD 2>$null
-        if ($LASTEXITCODE -eq 0) { return $branch.Trim() }
-    } catch {}
-
-    # Fallback: find latest feature directory
-    $repoRoot = Get-RepoRoot
-    $specsDir = Join-Path $repoRoot "specs"
-    if (Test-Path $specsDir) {
-        $latest = Get-ChildItem -Path $specsDir -Directory |
-            Where-Object { $_.Name -match '^\d{3}-' } |
-            Sort-Object Name -Descending |
-            Select-Object -First 1
-        if ($latest) { return $latest.Name }
-    }
-    return "main"
-}
-
-function Test-HasGit {
-    try {
-        git rev-parse --show-toplevel 2>$null | Out-Null
-        return $LASTEXITCODE -eq 0
-    } catch { return $false }
-}
-
-function Test-FeatureBranch {
-    param([string]$Branch, [bool]$HasGit)
-    if (-not $HasGit) {
-        Write-Warning "[specify] Git repository not detected; skipped branch validation"
-        return $true
-    }
-    if ($Branch -notmatch '^\d{3}-') {
-        Write-Error "Not on a feature branch. Current branch: $Branch"
-        Write-Error "Feature branches should be named like: 001-feature-name"
-        return $false
-    }
-    return $true
-}
-
-function Find-FeatureDir {
-    param([string]$RepoRoot, [string]$BranchName)
-    $specsDir = Join-Path $RepoRoot "specs"
-
-    if ($BranchName -match '^(\d{3})-') {
-        $prefix = $Matches[1]
-        $matches = Get-ChildItem -Path $specsDir -Directory -Filter "$prefix-*" -ErrorAction SilentlyContinue
-        if ($matches.Count -eq 1) { return $matches[0].FullName }
-        if ($matches.Count -gt 1) {
-            Write-Warning "Multiple spec dirs with prefix '$prefix': $($matches.Name -join ', ')"
-        }
-    }
-    return Join-Path $specsDir $BranchName
-}
-
-function Get-FeaturePaths {
-    $repoRoot = Get-RepoRoot
-    $branch = Get-CurrentBranch
-    $hasGit = Test-HasGit
-    $featureDir = Find-FeatureDir -RepoRoot $repoRoot -BranchName $branch
-
-    return [PSCustomObject]@{
-        RepoRoot     = $repoRoot
-        Branch       = $branch
-        HasGit       = $hasGit
-        FeatureDir   = $featureDir
-        FeatureSpec  = Join-Path $featureDir "spec.md"
-        ImplPlan     = Join-Path $featureDir "plan.md"
-        Tasks        = Join-Path $featureDir "tasks.md"
-        Research     = Join-Path $featureDir "research.md"
-        DataModel    = Join-Path $featureDir "data-model.md"
-        Quickstart   = Join-Path $featureDir "quickstart.md"
-        ContractsDir = Join-Path $featureDir "contracts"
-    }
-}
-
-<#
-.SYNOPSIS
-    Check prerequisites for Spec-Kit workflows.
-.DESCRIPTION
-    PowerShell equivalent of .agents/scripts/bash/check-prerequisites.sh
-.PARAMETER RequireTasks
-    Require tasks.md to exist (for implementation phase)
-.PARAMETER IncludeTasks
-    Include tasks.md in available docs list
-.PARAMETER PathsOnly
-    Only output paths, no validation
-.EXAMPLE
-    .\common.ps1
-    $result = Check-Prerequisites -RequireTasks
-#>
-function Check-Prerequisites {
-    param(
-        [switch]$RequireTasks,
-        [switch]$IncludeTasks,
-        [switch]$PathsOnly
-    )
-
-    $paths = Get-FeaturePaths
-    $valid = Test-FeatureBranch -Branch $paths.Branch -HasGit $paths.HasGit
-    if (-not $valid) { throw "Not on a feature branch" }
-
-    if ($PathsOnly) { return $paths }
-
-    # Validate required files
-    if (-not (Test-Path $paths.FeatureDir)) {
-        throw "Feature directory not found: $($paths.FeatureDir). Run /speckit.specify first."
-    }
-    if (-not (Test-Path $paths.ImplPlan)) {
-        throw "plan.md not found. Run /speckit.plan first."
-    }
-    if ($RequireTasks -and -not (Test-Path $paths.Tasks)) {
-        throw "tasks.md not found. Run /speckit.tasks first."
-    }
-
-    # Build available docs list
-    $docs = @()
-    if (Test-Path $paths.Research)  { $docs += "research.md" }
-    if (Test-Path $paths.DataModel) { $docs += "data-model.md" }
-    if ((Test-Path $paths.ContractsDir) -and (Get-ChildItem $paths.ContractsDir -ErrorAction SilentlyContinue)) {
-        $docs += "contracts/"
-    }
-    if (Test-Path $paths.Quickstart) { $docs += "quickstart.md" }
-    if ($IncludeTasks -and (Test-Path $paths.Tasks)) { $docs += "tasks.md" }
-
-    return [PSCustomObject]@{
-        FeatureDir    = $paths.FeatureDir
-        AvailableDocs = $docs
-        Paths         = $paths
-    }
-}
-
-# Export functions when dot-sourced
-Export-ModuleMember -Function * -ErrorAction SilentlyContinue 2>$null

.agents/scripts/powershell/create-new-feature.ps1

@@ -1,138 +0,0 @@
-<#
-.SYNOPSIS
-    Create a new feature branch and spec directory.
-.DESCRIPTION
-    PowerShell equivalent of .agents/scripts/bash/create-new-feature.sh
-    Creates a numbered feature branch and initializes the spec directory.
-.PARAMETER Description
-    Natural language description of the feature.
-.PARAMETER ShortName
-    Optional custom short name for the branch (2-4 words).
-.PARAMETER Number
-    Optional manual branch number (overrides auto-detection).
-.EXAMPLE
-    .\create-new-feature.ps1 -Description "Add user authentication" -ShortName "user-auth"
-#>
-param(
-    [Parameter(Mandatory = $true, Position = 0)]
-    [string]$Description,
-
-    [string]$ShortName,
-    [int]$Number = 0
-)
-
-$ErrorActionPreference = "Stop"
-
-# Load common functions
-. "$PSScriptRoot\common.ps1"
-
-$repoRoot = Get-RepoRoot
-$hasGit = Test-HasGit
-$specsDir = Join-Path $repoRoot "specs"
-if (-not (Test-Path $specsDir)) { New-Item -ItemType Directory -Path $specsDir | Out-Null }
-
-# Stop words for smart branch name generation
-$stopWords = @('i','a','an','the','to','for','of','in','on','at','by','with','from',
-               'is','are','was','were','be','been','being','have','has','had',
-               'do','does','did','will','would','should','could','can','may','might',
-               'must','shall','this','that','these','those','my','your','our','their',
-               'want','need','add','get','set')
-
-function ConvertTo-BranchName {
-    param([string]$Text)
-    $Text.ToLower() -replace '[^a-z0-9]', '-' -replace '-+', '-' -replace '^-|-$', ''
-}
-
-function Get-SmartBranchName {
-    param([string]$Desc)
-    $words = ($Desc.ToLower() -replace '[^a-z0-9]', ' ').Split(' ', [StringSplitOptions]::RemoveEmptyEntries)
-    $meaningful = $words | Where-Object { $_ -notin $stopWords -and $_.Length -ge 3 } | Select-Object -First 3
-    if ($meaningful.Count -gt 0) { return ($meaningful -join '-') }
-    return ConvertTo-BranchName $Desc
-}
-
-function Get-HighestNumber {
-    param([string]$Dir)
-    $highest = 0
-    if (Test-Path $Dir) {
-        Get-ChildItem -Path $Dir -Directory | ForEach-Object {
-            if ($_.Name -match '^(\d+)-') {
-                $num = [int]$Matches[1]
-                if ($num -gt $highest) { $highest = $num }
-            }
-        }
-    }
-    return $highest
-}
-
-# Generate branch suffix
-if ($ShortName) {
-    $branchSuffix = ConvertTo-BranchName $ShortName
-} else {
-    $branchSuffix = Get-SmartBranchName $Description
-}
-
-# Determine branch number
-if ($Number -gt 0) {
-    $branchNumber = $Number
-} else {
-    $highestSpec = Get-HighestNumber $specsDir
-    $highestBranch = 0
-    if ($hasGit) {
-        try {
-            git fetch --all --prune 2>$null | Out-Null
-            $branches = git branch -a 2>$null
-            foreach ($b in $branches) {
-                $clean = $b.Trim('* ') -replace '^remotes/[^/]+/', ''
-                if ($clean -match '^(\d{3})-') {
-                    $num = [int]$Matches[1]
-                    if ($num -gt $highestBranch) { $highestBranch = $num }
-                }
-            }
-        } catch {}
-    }
-    $branchNumber = [Math]::Max($highestSpec, $highestBranch) + 1
-}
-
-$featureNum = "{0:D3}" -f $branchNumber
-$branchName = "$featureNum-$branchSuffix"
-
-# Truncate if exceeding GitHub's 244-byte limit
-if ($branchName.Length -gt 244) {
-    $maxSuffix = 244 - 4  # 3 digits + 1 hyphen
-    $branchSuffix = $branchSuffix.Substring(0, $maxSuffix).TrimEnd('-')
-    Write-Warning "Branch name truncated to 244 bytes"
-    $branchName = "$featureNum-$branchSuffix"
-}
-
-# Create git branch
-if ($hasGit) {
-    git checkout -b $branchName
-} else {
-    Write-Warning "Git not detected; skipped branch creation for $branchName"
-}
-
-# Create feature directory and spec file
-$featureDir = Join-Path $specsDir $branchName
-New-Item -ItemType Directory -Path $featureDir -Force | Out-Null
-
-$templateFile = Join-Path $repoRoot ".specify" "templates" "spec-template.md"
-$specFile = Join-Path $featureDir "spec.md"
-if (Test-Path $templateFile) {
-    Copy-Item $templateFile $specFile
-} else {
-    New-Item -ItemType File -Path $specFile -Force | Out-Null
-}
-
-$env:SPECIFY_FEATURE = $branchName
-
-# Output
-[PSCustomObject]@{
-    BranchName = $branchName
-    SpecFile   = $specFile
-    FeatureNum = $featureNum
-}
-
-Write-Host "BRANCH_NAME: $branchName"
-Write-Host "SPEC_FILE: $specFile"
-Write-Host "FEATURE_NUM: $featureNum"

.agents/scripts/start-mcp.js

@@ -1,32 +0,0 @@
-// scripts/start-mcp.js
-const { spawn } = require('child_process');
-const path = require('path');
-const os = require('os');
-
-// Resolve the external config file (outside the repo)
-const configPath = path.resolve(os.homedir(), '.gemini', 'antigravity', 'mcp_config.json');
-
-// Load the JSON config (will throw if invalid)
-const config = require(configPath);
-
-function runServer(name, command, args, env = {}) {
-  console.log(`▶️ Starting ${name}…`);
-  const fullCmd = process.platform === 'win32' ? `${command}.cmd` : command;
-  const proc = spawn(fullCmd, args, {
-    stdio: 'inherit',
-    env: { ...process.env, ...env },
-    cwd: process.cwd(),
-    shell: true,
-  });
-  proc.on('close', (code) => {
-    if (code !== 0) {
-      console.error(`❌ ${name} exited with code ${code}`);
-    } else {
-      console.log(`✅ ${name} finished`);
-    }
-  });
-}
-
-Object.entries(config.mcpServers).forEach(([name, srv]) => {
-  runServer(name, srv.command, srv.args, srv.env);
-});

.agents/scripts/verify_links.py

@@ -1,101 +0,0 @@
-import os
-import re
-import sys
-from pathlib import Path
-
-# Configuration - default base directory, can be overridden via CLI argument
-DEFAULT_BASE_DIR = Path(__file__).resolve().parent.parent.parent / "specs"
-
-DIRECTORIES = [
-    "00-Overview",
-    "01-Requirements",
-    "02-Architecture",
-    "03-Data-and-Storage",
-    "04-Infrastructure-OPS",
-    "05-Engineering-Guidelines",
-    "06-Decision-Records"
-]
-
-# Regex for Markdown links: [label](path)
-# Handles relative paths, absolute file paths, and anchors
-LINK_PATTERN = re.compile(r'\[([^\]]+)\]\(([^)]+)\)')
-
-def verify_links(base_dir: Path):
-    results = {
-        "total_links": 0,
-        "broken_links": []
-    }
-
-    for dir_name in DIRECTORIES:
-        directory = base_dir / dir_name
-        if not directory.exists():
-            print(f"Directory not found: {directory}")
-            continue
-
-        for file_path in directory.glob("*.md"):
-            with open(file_path, "r", encoding="utf-8") as f:
-                content = f.read()
-                links = LINK_PATTERN.findall(content)
-
-                for label, target in links:
-                    # Ignore external links (http/https)
-                    if target.startswith("http"):
-                        continue
-
-                    # Ignore anchors within the same file
-                    if target.startswith("#"):
-                        continue
-
-                    results["total_links"] += 1
-
-                    # Process target path
-                    # 1. Handle file:/// Absolute paths if any
-                    if target.startswith("file:///"):
-                        clean_target = Path(target.replace("file:///", "").replace("/", os.sep))
-                    else:
-                        # 2. Handle relative paths
-                        # Remove anchor if present
-                        clean_target_str = target.split("#")[0]
-                        if not clean_target_str:
-                            continue
-
-                        # Resolve path relative to current file
-                        clean_target = (file_path.parent / clean_target_str).resolve()
-
-                    # Verify existence
-                    if not clean_target.exists():
-                        results["broken_links"].append({
-                            "source": str(file_path),
-                            "label": label,
-                            "target": target,
-                            "resolved": str(clean_target)
-                        })
-
-    return results
-
-if __name__ == "__main__":
-    if len(sys.argv) > 1:
-        base_dir = Path(sys.argv[1])
-    else:
-        base_dir = DEFAULT_BASE_DIR
-
-    if not base_dir.exists():
-        print(f"Error: Directory not found: {base_dir}", file=sys.stderr)
-        sys.exit(1)
-
-    print(f"Starting link verification in {base_dir}...")
-    audit_results = verify_links(base_dir)
-
-    print(f"\nAudit Summary:")
-    print(f"Total Internal Links Scanned: {audit_results['total_links']}")
-    print(f"Total Broken Links Found: {len(audit_results['broken_links'])}")
-
-    if audit_results['broken_links']:
-        print("\nBroken Links Detail:")
-        for idx, link in enumerate(audit_results['broken_links'], 1):
-            print(f"{idx}. Source: {link['source']}")
-            print(f"   Link: [{link['label']}]({link['target']})")
-            print(f"   Resolved Path: {link['resolved']}")
-            print("-" * 20)
-    else:
-        print("\nNo broken links found! 🎉")

.agents/skills/VERSION

@@ -1,18 +0,0 @@
-# Speckit Skills Version
-
-version: 1.1.0
-release_date: 2026-01-24
-
-## Changelog
-
-### 1.1.0 (2026-01-24)
-- New QA skills: tester, reviewer, checker
-- tester: Execute tests, measure coverage, report results
-- reviewer: Code review with severity levels and suggestions
-- checker: Static analysis aggregation (lint, types, security)
-
-### 1.0.0 (2026-01-24)
-- Initial versioned release
-- Core skills: specify, clarify, plan, tasks, implement, analyze, checklist, constitution, quizme, taskstoissues
-- New skills: diff, validate, migrate, status
-- All workflows enhanced with error handling and relative paths

.agents/skills/nestjs-best-practices/.github/workflows/branch-protection.yml

@@ -1,24 +0,0 @@
-name: Branch Protection
-
-on:
-  pull_request:
-    branches: [main]
-
-jobs:
-  check-branch:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Block docs branch merge to main
-        if: github.head_ref == 'docs'
-        run: |
-          echo "::error::Merging 'docs' branch into 'main' is not allowed."
-          echo ""
-          echo "The 'docs' branch contains the documentation website which should"
-          echo "remain separate from the main skill files to keep installations lightweight."
-          echo ""
-          echo "If you need to sync changes, cherry-pick specific commits instead."
-          exit 1
-
-      - name: Branch check passed
-        if: github.head_ref != 'docs'
-        run: echo "Branch check passed - not merging from docs branch"

.agents/skills/nestjs-best-practices/.github/workflows/deploy.yml

@@ -1,61 +0,0 @@
-name: Deploy to GitHub Pages
-
-on:
-  push:
-    branches: [docs]
-    paths:
-      - 'website/**'
-  workflow_dispatch:
-
-permissions:
-  contents: read
-  pages: write
-  id-token: write
-
-concurrency:
-  group: pages
-  cancel-in-progress: false
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Setup Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          cache: npm
-          cache-dependency-path: website/package-lock.json
-
-      - name: Setup Pages
-        uses: actions/configure-pages@v4
-
-      - name: Install dependencies
-        run: npm ci
-        working-directory: website
-
-      - name: Build
-        run: npm run build
-        working-directory: website
-
-      - name: Copy index.html to 404.html for SPA routing
-        run: cp website/dist/index.html website/dist/404.html
-
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
-        with:
-          path: website/dist
-
-  deploy:
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    runs-on: ubuntu-latest
-    needs: build
-    steps:
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v4

.agents/skills/nestjs-best-practices/.gitignore

@@ -1,29 +0,0 @@
-# Dependencies
-node_modules/
-
-# Website (lives on docs branch)
-website/
-
-# Build outputs
-dist/
-*.js
-*.d.ts
-*.js.map
-
-# IDE
-.idea/
-.vscode/
-*.swp
-*.swo
-
-# OS
-.DS_Store
-Thumbs.db
-
-# Logs
-*.log
-npm-debug.log*
-
-# Environment
-.env
-.env.local

.agents/skills/nestjs-best-practices/README.md

@@ -1,163 +0,0 @@
-# NestJS Best Practices
-
-📖 [For Humans <3](https://kadajett.github.io/agent-nestjs-skills/)
-
-A structured repository for creating and maintaining NestJS Best Practices optimized for agents and LLMs.
-
-## Installation
-
-Install this skill using [skills](https://github.com/vercel-labs/skills):
-
-```bash
-# GitHub shorthand
-npx skills add Kadajett/agent-nestjs-skills
-
-# Install globally (available across all projects)
-npx skills add Kadajett/agent-nestjs-skills --global
-
-# Install for specific agents
-npx skills add Kadajett/agent-nestjs-skills -a claude-code -a cursor
-```
-
-### Supported Agents
-
-- Claude Code
-- OpenCode
-- Codex
-- Cursor
-- Antigravity
-- Roo Code
-
-## Structure
-
-- `rules/` - Individual rule files (one per rule)
-  - `_sections.md` - Section metadata (titles, impacts, descriptions)
-  - `_template.md` - Template for creating new rules
-  - `area-description.md` - Individual rule files
-- `scripts/` - Build scripts and utilities
-- `metadata.json` - Document metadata (version, organization, abstract)
-- __`AGENTS.md`__ - Compiled output (generated)
-
-## Getting Started
-
-1. Install dependencies:
-   ```bash
-   cd scripts && npm install
-   ```
-
-2. Build AGENTS.md from rules:
-   ```bash
-   npm run build
-   # or
-   ./scripts/build.sh
-   ```
-
-## Creating a New Rule
-
-1. Copy `rules/_template.md` to `rules/area-description.md`
-2. Choose the appropriate area prefix:
-   - `arch-` for Architecture (Section 1)
-   - `di-` for Dependency Injection (Section 2)
-   - `error-` for Error Handling (Section 3)
-   - `security-` for Security (Section 4)
-   - `perf-` for Performance (Section 5)
-   - `test-` for Testing (Section 6)
-   - `db-` for Database & ORM (Section 7)
-   - `api-` for API Design (Section 8)
-   - `micro-` for Microservices (Section 9)
-   - `devops-` for DevOps & Deployment (Section 10)
-3. Fill in the frontmatter and content
-4. Ensure you have clear examples with explanations
-5. Run the build script to regenerate AGENTS.md
-
-## Rule File Structure
-
-Each rule file should follow this structure:
-
-```markdown
----
-title: Rule Title Here
-impact: MEDIUM
-impactDescription: Optional description
-tags: tag1, tag2, tag3
----
-
-## Rule Title Here
-
-Brief explanation of the rule and why it matters.
-
-**Incorrect (description of what's wrong):**
-
-```typescript
-// Bad code example
-```
-
-**Correct (description of what's right):**
-
-```typescript
-// Good code example
-```
-
-Optional explanatory text after examples.
-
-Reference: [NestJS Documentation](https://docs.nestjs.com)
-
-
-## File Naming Convention
-
-- Files starting with `_` are special (excluded from build)
-- Rule files: `area-description.md` (e.g., `arch-avoid-circular-deps.md`)
-- Section is automatically inferred from filename prefix
-- Rules are sorted alphabetically by title within each section
-- IDs (e.g., 1.1, 1.2) are auto-generated during build
-
-## Impact Levels
-
-| Level | Description |
-|-------|-------------|
-| CRITICAL | Violations cause runtime errors, security vulnerabilities, or architectural breakdown |
-| HIGH | Significant impact on reliability, security, or maintainability |
-| MEDIUM-HIGH | Notable impact on quality and developer experience |
-| MEDIUM | Moderate impact on code quality and best practices |
-| LOW-MEDIUM | Minor improvements for consistency and maintainability |
-
-## Scripts
-
-- `npm run build` (in scripts/) - Compile rules into AGENTS.md
-
-## Contributing
-
-When adding or modifying rules:
-
-1. Use the correct filename prefix for your section
-2. Follow the `_template.md` structure
-3. Include clear bad/good examples with explanations
-4. Add appropriate tags
-5. Run the build script to regenerate AGENTS.md
-6. Rules are automatically sorted by title - no need to manage numbers!
-
-## Documentation Website
-
-The documentation website source code lives on the [`docs` branch](https://github.com/Kadajett/agent-nestjs-skills/tree/docs/website). This separation keeps the skill installation lightweight while maintaining the full documentation site.
-
-To contribute to the website:
-
-```bash
-git checkout docs
-cd website
-npm install
-npm run dev
-```
-
-## Acknowledgments
-
-- Inspired by the [Vercel React Best Practices](https://github.com/vercel-labs/agent-skills) skill structure
-- Compatible with [skills](https://github.com/vercel-labs/skills) for easy installation across coding agents
-
-## Compatible Agents
-
-These NestJS skills work with:
-
-- [Claude Code](https://claude.ai/code) - Anthropic's official CLI
-- [AdaL](https://sylph.ai/adal) - Self-evolving AI coding agent with MCP support
-

.agents/skills/nestjs-best-practices/SKILL.md

@@ -1,130 +0,0 @@
----
-name: nestjs-best-practices
-description: NestJS best practices and architecture patterns for building production-ready applications. This skill should be used when writing, reviewing, or refactoring NestJS code to ensure proper patterns for modules, dependency injection, security, and performance.
-license: MIT
-metadata:
-  author: Kadajett
-  version: "1.1.0"
----
-
-# NestJS Best Practices
-
-Comprehensive best practices guide for NestJS applications. Contains 40 rules across 10 categories, prioritized by impact to guide automated refactoring and code generation.
-
-## When to Apply
-
-Reference these guidelines when:
-
-- Writing new NestJS modules, controllers, or services
-- Implementing authentication and authorization
-- Reviewing code for architecture and security issues
-- Refactoring existing NestJS codebases
-- Optimizing performance or database queries
-- Building microservices architectures
-
-## Rule Categories by Priority
-
-| Priority | Category | Impact | Prefix |
-|----------|----------|--------|--------|
-| 1 | Architecture | CRITICAL | `arch-` |
-| 2 | Dependency Injection | CRITICAL | `di-` |
-| 3 | Error Handling | HIGH | `error-` |
-| 4 | Security | HIGH | `security-` |
-| 5 | Performance | HIGH | `perf-` |
-| 6 | Testing | MEDIUM-HIGH | `test-` |
-| 7 | Database & ORM | MEDIUM-HIGH | `db-` |
-| 8 | API Design | MEDIUM | `api-` |
-| 9 | Microservices | MEDIUM | `micro-` |
-| 10 | DevOps & Deployment | LOW-MEDIUM | `devops-` |
-
-## Quick Reference
-
-### 1. Architecture (CRITICAL)
-
-- `arch-avoid-circular-deps` - Avoid circular module dependencies
-- `arch-feature-modules` - Organize by feature, not technical layer
-- `arch-module-sharing` - Proper module exports/imports, avoid duplicate providers
-- `arch-single-responsibility` - Focused services over "god services"
-- `arch-use-repository-pattern` - Abstract database logic for testability
-- `arch-use-events` - Event-driven architecture for decoupling
-
-### 2. Dependency Injection (CRITICAL)
-
-- `di-avoid-service-locator` - Avoid service locator anti-pattern
-- `di-interface-segregation` - Interface Segregation Principle (ISP)
-- `di-liskov-substitution` - Liskov Substitution Principle (LSP)
-- `di-prefer-constructor-injection` - Constructor over property injection
-- `di-scope-awareness` - Understand singleton/request/transient scopes
-- `di-use-interfaces-tokens` - Use injection tokens for interfaces
-
-### 3. Error Handling (HIGH)
-
-- `error-use-exception-filters` - Centralized exception handling
-- `error-throw-http-exceptions` - Use NestJS HTTP exceptions
-- `error-handle-async-errors` - Handle async errors properly
-
-### 4. Security (HIGH)
-
-- `security-auth-jwt` - Secure JWT authentication
-- `security-validate-all-input` - Validate with class-validator
-- `security-use-guards` - Authentication and authorization guards
-- `security-sanitize-output` - Prevent XSS attacks
-- `security-rate-limiting` - Implement rate limiting
-
-### 5. Performance (HIGH)
-
-- `perf-async-hooks` - Proper async lifecycle hooks
-- `perf-use-caching` - Implement caching strategies
-- `perf-optimize-database` - Optimize database queries
-- `perf-lazy-loading` - Lazy load modules for faster startup
-
-### 6. Testing (MEDIUM-HIGH)
-
-- `test-use-testing-module` - Use NestJS testing utilities
-- `test-e2e-supertest` - E2E testing with Supertest
-- `test-mock-external-services` - Mock external dependencies
-
-### 7. Database & ORM (MEDIUM-HIGH)
-
-- `db-use-transactions` - Transaction management
-- `db-avoid-n-plus-one` - Avoid N+1 query problems
-- `db-use-migrations` - Use migrations for schema changes
-
-### 8. API Design (MEDIUM)
-
-- `api-use-dto-serialization` - DTO and response serialization
-- `api-use-interceptors` - Cross-cutting concerns
-- `api-versioning` - API versioning strategies
-- `api-use-pipes` - Input transformation with pipes
-
-### 9. Microservices (MEDIUM)
-
-- `micro-use-patterns` - Message and event patterns
-- `micro-use-health-checks` - Health checks for orchestration
-- `micro-use-queues` - Background job processing
-
-### 10. DevOps & Deployment (LOW-MEDIUM)
-
-- `devops-use-config-module` - Environment configuration
-- `devops-use-logging` - Structured logging
-- `devops-graceful-shutdown` - Zero-downtime deployments
-
-## How to Use
-
-Read individual rule files for detailed explanations and code examples:
-
-```
-rules/arch-avoid-circular-deps.md
-rules/security-validate-all-input.md
-rules/_sections.md
-```
-
-Each rule file contains:
-- Brief explanation of why it matters
-- Incorrect code example with explanation
-- Correct code example with explanation
-- Additional context and references
-
-## Full Compiled Document
-
-For the complete guide with all rules expanded: `AGENTS.md`

.agents/skills/nestjs-best-practices/rules/api-use-dto-serialization.md

@@ -1,182 +0,0 @@
----
-title: Use DTOs and Serialization for API Responses
-impact: MEDIUM
-impactDescription: Response DTOs prevent accidental data exposure and ensure consistency
-tags: api, dto, serialization, class-transformer
----
-
-## Use DTOs and Serialization for API Responses
-
-Never return entity objects directly from controllers. Use response DTOs with class-transformer's `@Exclude()` and `@Expose()` decorators to control exactly what data is sent to clients. This prevents accidental exposure of sensitive fields and provides a stable API contract.
-
-**Incorrect (returning entities directly or manual spreading):**
-
-```typescript
-// Return entities directly
-@Controller('users')
-export class UsersController {
-  @Get(':id')
-  async findOne(@Param('id') id: string): Promise<User> {
-    return this.usersService.findById(id);
-    // Returns: { id, email, passwordHash, ssn, internalNotes, ... }
-    // Exposes sensitive data!
-  }
-}
-
-// Manual object spreading (error-prone)
-@Get(':id')
-async findOne(@Param('id') id: string) {
-  const user = await this.usersService.findById(id);
-  return {
-    id: user.id,
-    email: user.email,
-    name: user.name,
-    // Easy to forget to exclude sensitive fields
-    // Hard to maintain across endpoints
-  };
-}
-```
-
-**Correct (use class-transformer with @Exclude and response DTOs):**
-
-```typescript
-// Enable class-transformer globally
-async function bootstrap() {
-  const app = await NestFactory.create(AppModule);
-  app.useGlobalInterceptors(new ClassSerializerInterceptor(app.get(Reflector)));
-  await app.listen(3000);
-}
-
-// Entity with serialization control
-@Entity()
-export class User {
-  @PrimaryGeneratedColumn('uuid')
-  id: string;
-
-  @Column()
-  email: string;
-
-  @Column()
-  name: string;
-
-  @Column()
-  @Exclude() // Never include in responses
-  passwordHash: string;
-
-  @Column({ nullable: true })
-  @Exclude()
-  ssn: string;
-
-  @Column({ default: false })
-  @Exclude({ toPlainOnly: true }) // Exclude from response, allow in requests
-  isAdmin: boolean;
-
-  @CreateDateColumn()
-  createdAt: Date;
-
-  @Column()
-  @Exclude()
-  internalNotes: string;
-}
-
-// Now returning entity is safe
-@Controller('users')
-export class UsersController {
-  @Get(':id')
-  async findOne(@Param('id') id: string): Promise<User> {
-    return this.usersService.findById(id);
-    // Returns: { id, email, name, createdAt }
-    // Sensitive fields excluded automatically
-  }
-}
-
-// For different response shapes, use explicit DTOs
-export class UserResponseDto {
-  @Expose()
-  id: string;
-
-  @Expose()
-  email: string;
-
-  @Expose()
-  name: string;
-
-  @Expose()
-  @Transform(({ obj }) => obj.posts?.length || 0)
-  postCount: number;
-
-  constructor(partial: Partial<User>) {
-    Object.assign(this, partial);
-  }
-}
-
-export class UserDetailResponseDto extends UserResponseDto {
-  @Expose()
-  createdAt: Date;
-
-  @Expose()
-  @Type(() => PostResponseDto)
-  posts: PostResponseDto[];
-}
-
-// Controller with explicit DTOs
-@Controller('users')
-export class UsersController {
-  @Get()
-  @SerializeOptions({ type: UserResponseDto })
-  async findAll(): Promise<UserResponseDto[]> {
-    const users = await this.usersService.findAll();
-    return users.map(u => plainToInstance(UserResponseDto, u));
-  }
-
-  @Get(':id')
-  async findOne(@Param('id') id: string): Promise<UserDetailResponseDto> {
-    const user = await this.usersService.findByIdWithPosts(id);
-    return plainToInstance(UserDetailResponseDto, user, {
-      excludeExtraneousValues: true,
-    });
-  }
-}
-
-// Groups for conditional serialization
-export class UserDto {
-  @Expose()
-  id: string;
-
-  @Expose()
-  name: string;
-
-  @Expose({ groups: ['admin'] })
-  email: string;
-
-  @Expose({ groups: ['admin'] })
-  createdAt: Date;
-
-  @Expose({ groups: ['admin', 'owner'] })
-  settings: UserSettings;
-}
-
-@Controller('users')
-export class UsersController {
-  @Get()
-  @SerializeOptions({ groups: ['public'] })
-  async findAllPublic(): Promise<UserDto[]> {
-    // Returns: { id, name }
-  }
-
-  @Get('admin')
-  @UseGuards(AdminGuard)
-  @SerializeOptions({ groups: ['admin'] })
-  async findAllAdmin(): Promise<UserDto[]> {
-    // Returns: { id, name, email, createdAt }
-  }
-
-  @Get('me')
-  @SerializeOptions({ groups: ['owner'] })
-  async getProfile(@CurrentUser() user: User): Promise<UserDto> {
-    // Returns: { id, name, settings }
-  }
-}
-```
-
-Reference: [NestJS Serialization](https://docs.nestjs.com/techniques/serialization)

.agents/skills/nestjs-best-practices/rules/api-use-interceptors.md

@@ -1,202 +0,0 @@
----
-title: Use Interceptors for Cross-Cutting Concerns
-impact: MEDIUM-HIGH
-impactDescription: Interceptors provide clean separation for cross-cutting logic
-tags: api, interceptors, logging, caching
----
-
-## Use Interceptors for Cross-Cutting Concerns
-
-Interceptors can transform responses, add logging, handle caching, and measure performance without polluting your business logic. They wrap the route handler execution, giving you access to both the request and response streams.
-
-**Incorrect (logging and transformation in every method):**
-
-```typescript
-// Logging in every controller method
-@Controller('users')
-export class UsersController {
-  @Get()
-  async findAll(): Promise<User[]> {
-    const start = Date.now();
-    this.logger.log('findAll called');
-
-    const users = await this.usersService.findAll();
-
-    this.logger.log(`findAll completed in ${Date.now() - start}ms`);
-    return users;
-  }
-
-  @Get(':id')
-  async findOne(@Param('id') id: string): Promise<User> {
-    const start = Date.now();
-    this.logger.log(`findOne called with id: ${id}`);
-
-    const user = await this.usersService.findOne(id);
-
-    this.logger.log(`findOne completed in ${Date.now() - start}ms`);
-    return user;
-  }
-  // Repeated in every method!
-}
-
-// Manual response wrapping
-@Get()
-async findAll(): Promise<{ data: User[]; meta: Meta }> {
-  const users = await this.usersService.findAll();
-  return {
-    data: users,
-    meta: { timestamp: new Date(), count: users.length },
-  };
-}
-```
-
-**Correct (use interceptors for cross-cutting concerns):**
-
-```typescript
-// Logging interceptor
-@Injectable()
-export class LoggingInterceptor implements NestInterceptor {
-  private readonly logger = new Logger('HTTP');
-
-  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
-    const request = context.switchToHttp().getRequest();
-    const { method, url, body } = request;
-    const now = Date.now();
-
-    return next.handle().pipe(
-      tap({
-        next: (data) => {
-          const response = context.switchToHttp().getResponse();
-          this.logger.log(
-            `${method} ${url} ${response.statusCode} - ${Date.now() - now}ms`,
-          );
-        },
-        error: (error) => {
-          this.logger.error(
-            `${method} ${url} ${error.status || 500} - ${Date.now() - now}ms`,
-            error.stack,
-          );
-        },
-      }),
-    );
-  }
-}
-
-// Response transformation interceptor
-@Injectable()
-export class TransformInterceptor<T> implements NestInterceptor<T, Response<T>> {
-  intercept(context: ExecutionContext, next: CallHandler): Observable<Response<T>> {
-    return next.handle().pipe(
-      map((data) => ({
-        data,
-        meta: {
-          timestamp: new Date().toISOString(),
-          path: context.switchToHttp().getRequest().url,
-        },
-      })),
-    );
-  }
-}
-
-// Timeout interceptor
-@Injectable()
-export class TimeoutInterceptor implements NestInterceptor {
-  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
-    return next.handle().pipe(
-      timeout(5000),
-      catchError((err) => {
-        if (err instanceof TimeoutError) {
-          throw new RequestTimeoutException('Request timed out');
-        }
-        throw err;
-      }),
-    );
-  }
-}
-
-// Apply globally or per-controller
-@Module({
-  providers: [
-    { provide: APP_INTERCEPTOR, useClass: LoggingInterceptor },
-    { provide: APP_INTERCEPTOR, useClass: TransformInterceptor },
-  ],
-})
-export class AppModule {}
-
-// Or per-controller
-@Controller('users')
-@UseInterceptors(LoggingInterceptor)
-export class UsersController {
-  @Get()
-  async findAll(): Promise<User[]> {
-    // Clean business logic only
-    return this.usersService.findAll();
-  }
-}
-
-// Custom cache interceptor with TTL
-@Injectable()
-export class HttpCacheInterceptor implements NestInterceptor {
-  constructor(
-    private cacheManager: Cache,
-    private reflector: Reflector,
-  ) {}
-
-  async intercept(context: ExecutionContext, next: CallHandler): Promise<Observable<any>> {
-    const request = context.switchToHttp().getRequest();
-
-    // Only cache GET requests
-    if (request.method !== 'GET') {
-      return next.handle();
-    }
-
-    const cacheKey = this.generateKey(request);
-    const ttl = this.reflector.get<number>('cacheTTL', context.getHandler()) || 300;
-
-    const cached = await this.cacheManager.get(cacheKey);
-    if (cached) {
-      return of(cached);
-    }
-
-    return next.handle().pipe(
-      tap((response) => {
-        this.cacheManager.set(cacheKey, response, ttl);
-      }),
-    );
-  }
-
-  private generateKey(request: Request): string {
-    return `cache:${request.url}:${JSON.stringify(request.query)}`;
-  }
-}
-
-// Usage with custom TTL
-@Get()
-@SetMetadata('cacheTTL', 600)
-@UseInterceptors(HttpCacheInterceptor)
-async findAll(): Promise<User[]> {
-  return this.usersService.findAll();
-}
-
-// Error mapping interceptor
-@Injectable()
-export class ErrorMappingInterceptor implements NestInterceptor {
-  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
-    return next.handle().pipe(
-      catchError((error) => {
-        if (error instanceof EntityNotFoundError) {
-          throw new NotFoundException(error.message);
-        }
-        if (error instanceof QueryFailedError) {
-          if (error.message.includes('duplicate')) {
-            throw new ConflictException('Resource already exists');
-          }
-        }
-        throw error;
-      }),
-    );
-  }
-}
-```
-
-Reference: [NestJS Interceptors](https://docs.nestjs.com/interceptors)

.agents/skills/nestjs-best-practices/rules/api-use-pipes.md

@@ -1,205 +0,0 @@
----
-title: Use Pipes for Input Transformation
-impact: MEDIUM
-impactDescription: Pipes ensure clean, validated data reaches your handlers
-tags: api, pipes, validation, transformation
----
-
-## Use Pipes for Input Transformation
-
-Use built-in pipes like `ParseIntPipe`, `ParseUUIDPipe`, and `DefaultValuePipe` for common transformations. Create custom pipes for business-specific transformations. Pipes separate validation/transformation logic from controllers.
-
-**Incorrect (manual type parsing in handlers):**
-
-```typescript
-// Manual type parsing in handlers
-@Controller('users')
-export class UsersController {
-  @Get(':id')
-  async findOne(@Param('id') id: string): Promise<User> {
-    // Manual validation in every handler
-    const uuid = id.trim();
-    if (!isUUID(uuid)) {
-      throw new BadRequestException('Invalid UUID');
-    }
-    return this.usersService.findOne(uuid);
-  }
-
-  @Get()
-  async findAll(
-    @Query('page') page: string,
-    @Query('limit') limit: string,
-  ): Promise<User[]> {
-    // Manual parsing and defaults
-    const pageNum = parseInt(page) || 1;
-    const limitNum = parseInt(limit) || 10;
-    return this.usersService.findAll(pageNum, limitNum);
-  }
-}
-
-// Type coercion without validation
-@Get()
-async search(@Query('price') price: string): Promise<Product[]> {
-  const priceNum = +price; // NaN if invalid, no error
-  return this.productsService.findByPrice(priceNum);
-}
-```
-
-**Correct (use built-in and custom pipes):**
-
-```typescript
-// Use built-in pipes for common transformations
-@Controller('users')
-export class UsersController {
-  @Get(':id')
-  async findOne(@Param('id', ParseUUIDPipe) id: string): Promise<User> {
-    // id is guaranteed to be a valid UUID
-    return this.usersService.findOne(id);
-  }
-
-  @Get()
-  async findAll(
-    @Query('page', new DefaultValuePipe(1), ParseIntPipe) page: number,
-    @Query('limit', new DefaultValuePipe(10), ParseIntPipe) limit: number,
-  ): Promise<User[]> {
-    // Automatic defaults and type conversion
-    return this.usersService.findAll(page, limit);
-  }
-
-  @Get('by-status/:status')
-  async findByStatus(
-    @Param('status', new ParseEnumPipe(UserStatus)) status: UserStatus,
-  ): Promise<User[]> {
-    return this.usersService.findByStatus(status);
-  }
-}
-
-// Custom pipe for business logic
-@Injectable()
-export class ParseDatePipe implements PipeTransform<string, Date> {
-  transform(value: string): Date {
-    const date = new Date(value);
-    if (isNaN(date.getTime())) {
-      throw new BadRequestException('Invalid date format');
-    }
-    return date;
-  }
-}
-
-@Get('reports')
-async getReports(
-  @Query('from', ParseDatePipe) from: Date,
-  @Query('to', ParseDatePipe) to: Date,
-): Promise<Report[]> {
-  return this.reportsService.findBetween(from, to);
-}
-
-// Custom transformation pipes
-@Injectable()
-export class NormalizeEmailPipe implements PipeTransform<string, string> {
-  transform(value: string): string {
-    if (!value) return value;
-    return value.trim().toLowerCase();
-  }
-}
-
-// Parse comma-separated values
-@Injectable()
-export class ParseArrayPipe implements PipeTransform<string, string[]> {
-  transform(value: string): string[] {
-    if (!value) return [];
-    return value.split(',').map((v) => v.trim()).filter(Boolean);
-  }
-}
-
-@Get('products')
-async findProducts(
-  @Query('ids', ParseArrayPipe) ids: string[],
-  @Query('email', NormalizeEmailPipe) email: string,
-): Promise<Product[]> {
-  // ids is already an array, email is normalized
-  return this.productsService.findByIds(ids);
-}
-
-// Sanitize HTML input
-@Injectable()
-export class SanitizeHtmlPipe implements PipeTransform<string, string> {
-  transform(value: string): string {
-    if (!value) return value;
-    return sanitizeHtml(value, { allowedTags: [] });
-  }
-}
-
-// Global validation pipe with transformation
-app.useGlobalPipes(
-  new ValidationPipe({
-    whitelist: true, // Strip non-DTO properties
-    transform: true, // Auto-transform to DTO types
-    transformOptions: {
-      enableImplicitConversion: true, // Convert query strings to numbers
-    },
-    forbidNonWhitelisted: true, // Throw on extra properties
-  }),
-);
-
-// DTO with transformation decorators
-export class FindProductsDto {
-  @IsOptional()
-  @Type(() => Number)
-  @IsInt()
-  @Min(1)
-  page?: number = 1;
-
-  @IsOptional()
-  @Type(() => Number)
-  @IsInt()
-  @Min(1)
-  @Max(100)
-  limit?: number = 10;
-
-  @IsOptional()
-  @Transform(({ value }) => value?.toLowerCase())
-  @IsString()
-  search?: string;
-
-  @IsOptional()
-  @Transform(({ value }) => value?.split(','))
-  @IsArray()
-  @IsString({ each: true })
-  categories?: string[];
-}
-
-@Get()
-async findAll(@Query() dto: FindProductsDto): Promise<Product[]> {
-  // dto is already transformed and validated
-  return this.productsService.findAll(dto);
-}
-
-// Pipe error customization
-@Injectable()
-export class CustomParseIntPipe extends ParseIntPipe {
-  constructor() {
-    super({
-      exceptionFactory: (error) =>
-        new BadRequestException(`${error} must be a valid integer`),
-    });
-  }
-}
-
-// Or use options on built-in pipes
-@Get(':id')
-async findOne(
-  @Param(
-    'id',
-    new ParseIntPipe({
-      errorHttpStatusCode: HttpStatus.NOT_ACCEPTABLE,
-      exceptionFactory: () => new NotAcceptableException('ID must be numeric'),
-    }),
-  )
-  id: number,
-): Promise<Item> {
-  return this.itemsService.findOne(id);
-}
-```
-
-Reference: [NestJS Pipes](https://docs.nestjs.com/pipes)

.agents/skills/nestjs-best-practices/rules/api-versioning.md

@@ -1,191 +0,0 @@
----
-title: Use API Versioning for Breaking Changes
-impact: MEDIUM
-impactDescription: Versioning allows you to evolve APIs without breaking existing clients
-tags: api, versioning, breaking-changes, compatibility
----
-
-## Use API Versioning for Breaking Changes
-
-Use NestJS built-in versioning when making breaking changes to your API. Choose a versioning strategy (URI, header, or media type) and apply it consistently. This allows old clients to continue working while new clients use updated endpoints.
-
-**Incorrect (breaking changes without versioning):**
-
-```typescript
-// Breaking changes without versioning
-@Controller('users')
-export class UsersController {
-  @Get(':id')
-  async findOne(@Param('id') id: string): Promise<User> {
-    // Original response: { id, name, email }
-    // Later changed to: { id, firstName, lastName, emailAddress }
-    // Old clients break!
-    return this.usersService.findOne(id);
-  }
-}
-
-// Manual versioning in routes
-@Controller('v1/users')
-export class UsersV1Controller {}
-
-@Controller('v2/users')
-export class UsersV2Controller {}
-// Inconsistent, error-prone, hard to maintain
-```
-
-**Correct (use NestJS built-in versioning):**
-
-```typescript
-// Enable versioning in main.ts
-async function bootstrap() {
-  const app = await NestFactory.create(AppModule);
-
-  // URI versioning: /v1/users, /v2/users
-  app.enableVersioning({
-    type: VersioningType.URI,
-    defaultVersion: '1',
-  });
-
-  // Or header versioning: X-API-Version: 1
-  app.enableVersioning({
-    type: VersioningType.HEADER,
-    header: 'X-API-Version',
-    defaultVersion: '1',
-  });
-
-  // Or media type: Accept: application/json;v=1
-  app.enableVersioning({
-    type: VersioningType.MEDIA_TYPE,
-    key: 'v=',
-    defaultVersion: '1',
-  });
-
-  await app.listen(3000);
-}
-
-// Version-specific controllers
-@Controller('users')
-@Version('1')
-export class UsersV1Controller {
-  @Get(':id')
-  async findOne(@Param('id') id: string): Promise<UserV1Response> {
-    const user = await this.usersService.findOne(id);
-    // V1 response format
-    return {
-      id: user.id,
-      name: user.name,
-      email: user.email,
-    };
-  }
-}
-
-@Controller('users')
-@Version('2')
-export class UsersV2Controller {
-  @Get(':id')
-  async findOne(@Param('id') id: string): Promise<UserV2Response> {
-    const user = await this.usersService.findOne(id);
-    // V2 response format with breaking changes
-    return {
-      id: user.id,
-      firstName: user.firstName,
-      lastName: user.lastName,
-      emailAddress: user.email,
-      createdAt: user.createdAt,
-    };
-  }
-}
-
-// Per-route versioning - different versions for different routes
-@Controller('users')
-export class UsersController {
-  @Get()
-  @Version('1')
-  findAllV1(): Promise<UserV1Response[]> {
-    return this.usersService.findAllV1();
-  }
-
-  @Get()
-  @Version('2')
-  findAllV2(): Promise<UserV2Response[]> {
-    return this.usersService.findAllV2();
-  }
-
-  @Get(':id')
-  @Version(['1', '2']) // Same handler for multiple versions
-  findOne(@Param('id') id: string): Promise<User> {
-    return this.usersService.findOne(id);
-  }
-
-  @Post()
-  @Version(VERSION_NEUTRAL) // Available in all versions
-  create(@Body() dto: CreateUserDto): Promise<User> {
-    return this.usersService.create(dto);
-  }
-}
-
-// Shared service with version-specific logic
-@Injectable()
-export class UsersService {
-  async findOne(id: string, version: string): Promise<any> {
-    const user = await this.repo.findOne({ where: { id } });
-
-    if (version === '1') {
-      return this.toV1Response(user);
-    }
-    return this.toV2Response(user);
-  }
-
-  private toV1Response(user: User): UserV1Response {
-    return {
-      id: user.id,
-      name: `${user.firstName} ${user.lastName}`,
-      email: user.email,
-    };
-  }
-
-  private toV2Response(user: User): UserV2Response {
-    return {
-      id: user.id,
-      firstName: user.firstName,
-      lastName: user.lastName,
-      emailAddress: user.email,
-      createdAt: user.createdAt,
-    };
-  }
-}
-
-// Controller extracts version
-@Controller('users')
-export class UsersController {
-  @Get(':id')
-  async findOne(
-    @Param('id') id: string,
-    @Headers('X-API-Version') version: string = '1',
-  ): Promise<any> {
-    return this.usersService.findOne(id, version);
-  }
-}
-
-// Deprecation strategy - mark old versions as deprecated
-@Controller('users')
-@Version('1')
-@UseInterceptors(DeprecationInterceptor)
-export class UsersV1Controller {
-  // All V1 routes will include deprecation warning
-}
-
-@Injectable()
-export class DeprecationInterceptor implements NestInterceptor {
-  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
-    const response = context.switchToHttp().getResponse();
-    response.setHeader('Deprecation', 'true');
-    response.setHeader('Sunset', 'Sat, 1 Jan 2025 00:00:00 GMT');
-    response.setHeader('Link', '</v2/users>; rel="successor-version"');
-
-    return next.handle();
-  }
-}
-```
-
-Reference: [NestJS Versioning](https://docs.nestjs.com/techniques/versioning)

.agents/skills/nestjs-best-practices/rules/arch-avoid-circular-deps.md

@@ -1,80 +0,0 @@
----
-title: Avoid Circular Dependencies
-impact: CRITICAL
-impactDescription: "#1 cause of runtime crashes"
-tags: architecture, modules, dependencies
----
-
-## Avoid Circular Dependencies
-
-Circular dependencies occur when Module A imports Module B, and Module B imports Module A (directly or transitively). NestJS can sometimes resolve these through forward references, but they indicate architectural problems and should be avoided. This is the #1 cause of runtime crashes in NestJS applications.
-
-**Incorrect (circular module imports):**
-
-```typescript
-// users.module.ts
-@Module({
-  imports: [OrdersModule], // Orders needs Users, Users needs Orders = circular
-  providers: [UsersService],
-  exports: [UsersService],
-})
-export class UsersModule {}
-
-// orders.module.ts
-@Module({
-  imports: [UsersModule], // Circular dependency!
-  providers: [OrdersService],
-  exports: [OrdersService],
-})
-export class OrdersModule {}
-```
-
-**Correct (extract shared logic or use events):**
-
-```typescript
-// Option 1: Extract shared logic to a third module
-// shared.module.ts
-@Module({
-  providers: [SharedService],
-  exports: [SharedService],
-})
-export class SharedModule {}
-
-// users.module.ts
-@Module({
-  imports: [SharedModule],
-  providers: [UsersService],
-})
-export class UsersModule {}
-
-// orders.module.ts
-@Module({
-  imports: [SharedModule],
-  providers: [OrdersService],
-})
-export class OrdersModule {}
-
-// Option 2: Use events for decoupled communication
-// users.service.ts
-@Injectable()
-export class UsersService {
-  constructor(private eventEmitter: EventEmitter2) {}
-
-  async createUser(data: CreateUserDto) {
-    const user = await this.userRepo.save(data);
-    this.eventEmitter.emit('user.created', user);
-    return user;
-  }
-}
-
-// orders.service.ts
-@Injectable()
-export class OrdersService {
-  @OnEvent('user.created')
-  handleUserCreated(user: User) {
-    // React to user creation without direct dependency
-  }
-}
-```
-
-Reference: [NestJS Circular Dependency](https://docs.nestjs.com/fundamentals/circular-dependency)

.agents/skills/nestjs-best-practices/rules/arch-feature-modules.md

@@ -1,82 +0,0 @@
----
-title: Organize by Feature Modules
-impact: CRITICAL
-impactDescription: "3-5x faster onboarding and development"
-tags: architecture, modules, organization
----
-
-## Organize by Feature Modules
-
-Organize your application into feature modules that encapsulate related functionality. Each feature module should be self-contained with its own controllers, services, entities, and DTOs. Avoid organizing by technical layer (all controllers together, all services together). This enables 3-5x faster onboarding and feature development.
-
-**Incorrect (technical layer organization):**
-
-```typescript
-// Technical layer organization (anti-pattern)
-src/
-├── controllers/
-│   ├── users.controller.ts
-│   ├── orders.controller.ts
-│   └── products.controller.ts
-├── services/
-│   ├── users.service.ts
-│   ├── orders.service.ts
-│   └── products.service.ts
-├── entities/
-│   ├── user.entity.ts
-│   ├── order.entity.ts
-│   └── product.entity.ts
-└── app.module.ts  // Imports everything directly
-```
-
-**Correct (feature module organization):**
-
-```typescript
-// Feature module organization
-src/
-├── users/
-│   ├── dto/
-│   │   ├── create-user.dto.ts
-│   │   └── update-user.dto.ts
-│   ├── entities/
-│   │   └── user.entity.ts
-│   ├── users.controller.ts
-│   ├── users.service.ts
-│   ├── users.repository.ts
-│   └── users.module.ts
-├── orders/
-│   ├── dto/
-│   ├── entities/
-│   ├── orders.controller.ts
-│   ├── orders.service.ts
-│   └── orders.module.ts
-├── shared/
-│   ├── guards/
-│   ├── interceptors/
-│   ├── filters/
-│   └── shared.module.ts
-└── app.module.ts
-
-// users.module.ts
-@Module({
-  imports: [TypeOrmModule.forFeature([User])],
-  controllers: [UsersController],
-  providers: [UsersService, UsersRepository],
-  exports: [UsersService], // Only export what others need
-})
-export class UsersModule {}
-
-// app.module.ts
-@Module({
-  imports: [
-    ConfigModule.forRoot(),
-    TypeOrmModule.forRoot(),
-    UsersModule,
-    OrdersModule,
-    SharedModule,
-  ],
-})
-export class AppModule {}
-```
-
-Reference: [NestJS Modules](https://docs.nestjs.com/modules)

.agents/skills/nestjs-best-practices/rules/arch-module-sharing.md

@@ -1,141 +0,0 @@
----
-title: Use Proper Module Sharing Patterns
-impact: CRITICAL
-impactDescription: Prevents duplicate instances, memory leaks, and state inconsistency
-tags: architecture, modules, sharing, exports
----
-
-## Use Proper Module Sharing Patterns
-
-NestJS modules are singletons by default. When a service is properly exported from a module and that module is imported elsewhere, the same instance is shared. However, providing a service in multiple modules creates separate instances, leading to memory waste, state inconsistency, and confusing behavior. Always encapsulate services in dedicated modules, export them explicitly, and import the module where needed.
-
-**Incorrect (service provided in multiple modules):**
-
-```typescript
-// StorageService provided directly in multiple modules - WRONG
-// storage.service.ts
-@Injectable()
-export class StorageService {
-  private cache = new Map(); // Each instance has separate state!
-
-  store(key: string, value: any) {
-    this.cache.set(key, value);
-  }
-}
-
-// app.module.ts
-@Module({
-  providers: [StorageService], // Instance #1
-  controllers: [AppController],
-})
-export class AppModule {}
-
-// videos.module.ts
-@Module({
-  providers: [StorageService], // Instance #2 - different from AppModule!
-  controllers: [VideosController],
-})
-export class VideosModule {}
-
-// Problems:
-// 1. Two separate StorageService instances exist
-// 2. cache.set() in VideosModule doesn't affect AppModule's cache
-// 3. Memory wasted on duplicate instances
-// 4. Debugging nightmares when state doesn't sync
-```
-
-**Correct (dedicated module with exports):**
-
-```typescript
-// storage/storage.module.ts
-@Module({
-  providers: [StorageService],
-  exports: [StorageService], // Make available to importers
-})
-export class StorageModule {}
-
-// videos/videos.module.ts
-@Module({
-  imports: [StorageModule], // Import the module, not the service
-  controllers: [VideosController],
-  providers: [VideosService],
-})
-export class VideosModule {}
-
-// channels/channels.module.ts
-@Module({
-  imports: [StorageModule], // Same instance shared
-  controllers: [ChannelsController],
-  providers: [ChannelsService],
-})
-export class ChannelsModule {}
-
-// app.module.ts
-@Module({
-  imports: [
-    StorageModule, // Only if AppModule itself needs StorageService
-    VideosModule,
-    ChannelsModule,
-  ],
-})
-export class AppModule {}
-
-// Now all modules share the SAME StorageService instance
-```
-
-**When to use @Global() (sparingly):**
-
-```typescript
-// ONLY for truly cross-cutting concerns
-@Global()
-@Module({
-  providers: [ConfigService, LoggerService],
-  exports: [ConfigService, LoggerService],
-})
-export class CoreModule {}
-
-// Import once in AppModule
-@Module({
-  imports: [CoreModule], // Registered globally, available everywhere
-})
-export class AppModule {}
-
-// Other modules don't need to import CoreModule
-@Module({
-  controllers: [UsersController],
-  providers: [UsersService], // Can inject ConfigService without importing
-})
-export class UsersModule {}
-
-// WARNING: Don't make everything global!
-// - Hides dependencies (can't see what a module needs from imports)
-// - Makes testing harder
-// - Reserve for: config, logging, database connections
-```
-
-**Module re-exporting pattern:**
-
-```typescript
-// common.module.ts - shared utilities
-@Module({
-  providers: [DateService, ValidationService],
-  exports: [DateService, ValidationService],
-})
-export class CommonModule {}
-
-// core.module.ts - re-exports common for convenience
-@Module({
-  imports: [CommonModule, DatabaseModule],
-  exports: [CommonModule, DatabaseModule], // Re-export for consumers
-})
-export class CoreModule {}
-
-// feature.module.ts - imports CoreModule, gets both
-@Module({
-  imports: [CoreModule], // Gets CommonModule + DatabaseModule
-  controllers: [FeatureController],
-})
-export class FeatureModule {}
-```
-
-Reference: [NestJS Modules](https://docs.nestjs.com/modules#shared-modules)

.agents/skills/nestjs-best-practices/rules/arch-single-responsibility.md

@@ -1,106 +0,0 @@
----
-title: Single Responsibility for Services
-impact: CRITICAL
-impactDescription: "40%+ improvement in testability"
-tags: architecture, services, single-responsibility
----
-
-## Single Responsibility for Services
-
-Each service should have a single, well-defined responsibility. Avoid "god services" that handle multiple unrelated concerns. If a service name includes "And" or handles more than one domain concept, it likely violates single responsibility. This reduces complexity and improves testability by 40%+.
-
-**Incorrect (god service anti-pattern):**
-
-```typescript
-// God service anti-pattern
-@Injectable()
-export class UserAndOrderService {
-  constructor(
-    private userRepo: UserRepository,
-    private orderRepo: OrderRepository,
-    private mailer: MailService,
-    private payment: PaymentService,
-  ) {}
-
-  async createUser(dto: CreateUserDto) {
-    const user = await this.userRepo.save(dto);
-    await this.mailer.sendWelcome(user);
-    return user;
-  }
-
-  async createOrder(userId: string, dto: CreateOrderDto) {
-    const order = await this.orderRepo.save({ userId, ...dto });
-    await this.payment.charge(order);
-    await this.mailer.sendOrderConfirmation(order);
-    return order;
-  }
-
-  async calculateOrderStats(userId: string) {
-    // Stats logic mixed in
-  }
-
-  async validatePayment(orderId: string) {
-    // Payment logic mixed in
-  }
-}
-```
-
-**Correct (focused services with single responsibility):**
-
-```typescript
-// Focused services with single responsibility
-@Injectable()
-export class UsersService {
-  constructor(private userRepo: UserRepository) {}
-
-  async create(dto: CreateUserDto): Promise<User> {
-    return this.userRepo.save(dto);
-  }
-
-  async findById(id: string): Promise<User> {
-    return this.userRepo.findOneOrFail({ where: { id } });
-  }
-}
-
-@Injectable()
-export class OrdersService {
-  constructor(private orderRepo: OrderRepository) {}
-
-  async create(userId: string, dto: CreateOrderDto): Promise<Order> {
-    return this.orderRepo.save({ userId, ...dto });
-  }
-
-  async findByUser(userId: string): Promise<Order[]> {
-    return this.orderRepo.find({ where: { userId } });
-  }
-}
-
-@Injectable()
-export class OrderStatsService {
-  constructor(private orderRepo: OrderRepository) {}
-
-  async calculateForUser(userId: string): Promise<OrderStats> {
-    // Focused stats calculation
-  }
-}
-
-// Orchestration in controller or dedicated orchestrator
-@Controller('orders')
-export class OrdersController {
-  constructor(
-    private orders: OrdersService,
-    private payment: PaymentService,
-    private notifications: NotificationService,
-  ) {}
-
-  @Post()
-  async create(@CurrentUser() user: User, @Body() dto: CreateOrderDto) {
-    const order = await this.orders.create(user.id, dto);
-    await this.payment.charge(order);
-    await this.notifications.sendOrderConfirmation(order);
-    return order;
-  }
-}
-```
-
-Reference: [NestJS Providers](https://docs.nestjs.com/providers)

.agents/skills/nestjs-best-practices/rules/arch-use-events.md

@@ -1,108 +0,0 @@
----
-title: Use Event-Driven Architecture for Decoupling
-impact: MEDIUM-HIGH
-impactDescription: Enables async processing and modularity
-tags: architecture, events, decoupling
----
-
-## Use Event-Driven Architecture for Decoupling
-
-Use `@nestjs/event-emitter` for intra-service events and message brokers for inter-service communication. Events allow modules to react to changes without direct dependencies, improving modularity and enabling async processing.
-
-**Incorrect (direct service coupling):**
-
-```typescript
-// Direct service coupling
-@Injectable()
-export class OrdersService {
-  constructor(
-    private inventoryService: InventoryService,
-    private emailService: EmailService,
-    private analyticsService: AnalyticsService,
-    private notificationService: NotificationService,
-    private loyaltyService: LoyaltyService,
-  ) {}
-
-  async createOrder(dto: CreateOrderDto): Promise<Order> {
-    const order = await this.repo.save(dto);
-
-    // Tight coupling - OrdersService knows about all consumers
-    await this.inventoryService.reserve(order.items);
-    await this.emailService.sendConfirmation(order);
-    await this.analyticsService.track('order_created', order);
-    await this.notificationService.push(order.userId, 'Order placed');
-    await this.loyaltyService.addPoints(order.userId, order.total);
-
-    // Adding new behavior requires modifying this service
-    return order;
-  }
-}
-```
-
-**Correct (event-driven decoupling):**
-
-```typescript
-// Use EventEmitter for decoupling
-import { EventEmitter2 } from '@nestjs/event-emitter';
-
-// Define event
-export class OrderCreatedEvent {
-  constructor(
-    public readonly orderId: string,
-    public readonly userId: string,
-    public readonly items: OrderItem[],
-    public readonly total: number,
-  ) {}
-}
-
-// Service emits events
-@Injectable()
-export class OrdersService {
-  constructor(
-    private eventEmitter: EventEmitter2,
-    private repo: Repository<Order>,
-  ) {}
-
-  async createOrder(dto: CreateOrderDto): Promise<Order> {
-    const order = await this.repo.save(dto);
-
-    // Emit event - no knowledge of consumers
-    this.eventEmitter.emit(
-      'order.created',
-      new OrderCreatedEvent(order.id, order.userId, order.items, order.total),
-    );
-
-    return order;
-  }
-}
-
-// Listeners in separate modules
-@Injectable()
-export class InventoryListener {
-  @OnEvent('order.created')
-  async handleOrderCreated(event: OrderCreatedEvent): Promise<void> {
-    await this.inventoryService.reserve(event.items);
-  }
-}
-
-@Injectable()
-export class EmailListener {
-  @OnEvent('order.created')
-  async handleOrderCreated(event: OrderCreatedEvent): Promise<void> {
-    await this.emailService.sendConfirmation(event.orderId);
-  }
-}
-
-@Injectable()
-export class AnalyticsListener {
-  @OnEvent('order.created')
-  async handleOrderCreated(event: OrderCreatedEvent): Promise<void> {
-    await this.analyticsService.track('order_created', {
-      orderId: event.orderId,
-      total: event.total,
-    });
-  }
-}
-```
-
-Reference: [NestJS Events](https://docs.nestjs.com/techniques/events)

.agents/skills/nestjs-best-practices/rules/arch-use-repository-pattern.md

@@ -1,97 +0,0 @@
----
-title: Use Repository Pattern for Data Access
-impact: HIGH
-impactDescription: Decouples business logic from database
-tags: architecture, repository, data-access
----
-
-## Use Repository Pattern for Data Access
-
-Create custom repositories to encapsulate complex queries and database logic. This keeps services focused on business logic, makes testing easier with mock repositories, and allows changing database implementations without affecting business code.
-
-**Incorrect (complex queries in services):**
-
-```typescript
-// Complex queries in services
-@Injectable()
-export class UsersService {
-  constructor(
-    @InjectRepository(User) private repo: Repository<User>,
-  ) {}
-
-  async findActiveWithOrders(minOrders: number): Promise<User[]> {
-    // Complex query logic mixed with business logic
-    return this.repo
-      .createQueryBuilder('user')
-      .leftJoinAndSelect('user.orders', 'order')
-      .where('user.isActive = :active', { active: true })
-      .andWhere('user.deletedAt IS NULL')
-      .groupBy('user.id')
-      .having('COUNT(order.id) >= :min', { min: minOrders })
-      .orderBy('user.createdAt', 'DESC')
-      .getMany();
-  }
-
-  // Service becomes bloated with query logic
-}
-```
-
-**Correct (custom repository with encapsulated queries):**
-
-```typescript
-// Custom repository with encapsulated queries
-@Injectable()
-export class UsersRepository {
-  constructor(
-    @InjectRepository(User) private repo: Repository<User>,
-  ) {}
-
-  async findById(id: string): Promise<User | null> {
-    return this.repo.findOne({ where: { id } });
-  }
-
-  async findByEmail(email: string): Promise<User | null> {
-    return this.repo.findOne({ where: { email } });
-  }
-
-  async findActiveWithMinOrders(minOrders: number): Promise<User[]> {
-    return this.repo
-      .createQueryBuilder('user')
-      .leftJoinAndSelect('user.orders', 'order')
-      .where('user.isActive = :active', { active: true })
-      .andWhere('user.deletedAt IS NULL')
-      .groupBy('user.id')
-      .having('COUNT(order.id) >= :min', { min: minOrders })
-      .orderBy('user.createdAt', 'DESC')
-      .getMany();
-  }
-
-  async save(user: User): Promise<User> {
-    return this.repo.save(user);
-  }
-}
-
-// Clean service with business logic only
-@Injectable()
-export class UsersService {
-  constructor(private usersRepo: UsersRepository) {}
-
-  async getActiveUsersWithOrders(): Promise<User[]> {
-    return this.usersRepo.findActiveWithMinOrders(1);
-  }
-
-  async create(dto: CreateUserDto): Promise<User> {
-    const existing = await this.usersRepo.findByEmail(dto.email);
-    if (existing) {
-      throw new ConflictException('Email already registered');
-    }
-
-    const user = new User();
-    user.email = dto.email;
-    user.name = dto.name;
-    return this.usersRepo.save(user);
-  }
-}
-```
-
-Reference: [Repository Pattern](https://martinfowler.com/eaaCatalog/repository.html)

.agents/skills/nestjs-best-practices/rules/db-avoid-n-plus-one.md

@@ -1,139 +0,0 @@
----
-title: Avoid N+1 Query Problems
-impact: HIGH
-impactDescription: N+1 queries are one of the most common performance killers
-tags: database, n-plus-one, queries, performance
----
-
-## Avoid N+1 Query Problems
-
-N+1 queries occur when you fetch a list of entities, then make an additional query for each entity to load related data. Use eager loading with `relations`, query builder joins, or DataLoader to batch queries efficiently.
-
-**Incorrect (lazy loading in loops causes N+1):**
-
-```typescript
-// Lazy loading in loops causes N+1
-@Injectable()
-export class OrdersService {
-  async getOrdersWithItems(userId: string): Promise<Order[]> {
-    const orders = await this.orderRepo.find({ where: { userId } });
-    // 1 query for orders
-
-    for (const order of orders) {
-      // N additional queries - one per order!
-      order.items = await this.itemRepo.find({ where: { orderId: order.id } });
-    }
-
-    return orders;
-  }
-}
-
-// Accessing lazy relations without loading
-@Controller('users')
-export class UsersController {
-  @Get()
-  async findAll(): Promise<User[]> {
-    const users = await this.userRepo.find();
-    // If User.posts is lazy-loaded, serializing triggers N queries
-    return users; // Each user.posts access = 1 query
-  }
-}
-```
-
-**Correct (use relations for eager loading):**
-
-```typescript
-// Use relations option for eager loading
-@Injectable()
-export class OrdersService {
-  async getOrdersWithItems(userId: string): Promise<Order[]> {
-    // Single query with JOIN
-    return this.orderRepo.find({
-      where: { userId },
-      relations: ['items', 'items.product'],
-    });
-  }
-}
-
-// Use QueryBuilder for complex joins
-@Injectable()
-export class UsersService {
-  async getUsersWithPostCounts(): Promise<UserWithPostCount[]> {
-    return this.userRepo
-      .createQueryBuilder('user')
-      .leftJoin('user.posts', 'post')
-      .select('user.id', 'id')
-      .addSelect('user.name', 'name')
-      .addSelect('COUNT(post.id)', 'postCount')
-      .groupBy('user.id')
-      .getRawMany();
-  }
-
-  async getActiveUsersWithPosts(): Promise<User[]> {
-    return this.userRepo
-      .createQueryBuilder('user')
-      .leftJoinAndSelect('user.posts', 'post')
-      .leftJoinAndSelect('post.comments', 'comment')
-      .where('user.isActive = :active', { active: true })
-      .andWhere('post.status = :status', { status: 'published' })
-      .getMany();
-  }
-}
-
-// Use find options for specific fields
-async getOrderSummaries(userId: string): Promise<OrderSummary[]> {
-  return this.orderRepo.find({
-    where: { userId },
-    relations: ['items'],
-    select: {
-      id: true,
-      total: true,
-      status: true,
-      items: {
-        id: true,
-        quantity: true,
-        price: true,
-      },
-    },
-  });
-}
-
-// Use DataLoader for GraphQL to batch and cache queries
-import DataLoader from 'dataloader';
-
-@Injectable({ scope: Scope.REQUEST })
-export class PostsLoader {
-  constructor(private postsService: PostsService) {}
-
-  readonly batchPosts = new DataLoader<string, Post[]>(async (userIds) => {
-    // Single query for all users' posts
-    const posts = await this.postsService.findByUserIds([...userIds]);
-
-    // Group by userId
-    const postsMap = new Map<string, Post[]>();
-    for (const post of posts) {
-      const userPosts = postsMap.get(post.userId) || [];
-      userPosts.push(post);
-      postsMap.set(post.userId, userPosts);
-    }
-
-    // Return in same order as input
-    return userIds.map((id) => postsMap.get(id) || []);
-  });
-}
-
-// In resolver
-@ResolveField()
-async posts(@Parent() user: User): Promise<Post[]> {
-  // DataLoader batches multiple calls into single query
-  return this.postsLoader.batchPosts.load(user.id);
-}
-
-// Enable query logging in development to detect N+1
-TypeOrmModule.forRoot({
-  logging: ['query', 'error'],
-  logger: 'advanced-console',
-});
-```
-
-Reference: [TypeORM Relations](https://typeorm.io/relations)

.agents/skills/nestjs-best-practices/rules/db-use-migrations.md

@@ -1,129 +0,0 @@
----
-title: Use Database Migrations
-impact: HIGH
-impactDescription: Enables safe, repeatable database schema changes
-tags: database, migrations, typeorm, schema
----
-
-## Use Database Migrations
-
-Never use `synchronize: true` in production. Use migrations for all schema changes. Migrations provide version control for your database, enable safe rollbacks, and ensure consistency across all environments.
-
-**Incorrect (using synchronize or manual SQL):**
-
-```typescript
-// Use synchronize in production
-TypeOrmModule.forRoot({
-  type: 'postgres',
-  synchronize: true, // DANGEROUS in production!
-  // Can drop columns, tables, or data
-});
-
-// Manual SQL in production
-@Injectable()
-export class DatabaseService {
-  async addColumn(): Promise<void> {
-    await this.dataSource.query('ALTER TABLE users ADD COLUMN age INT');
-    // No version control, no rollback, inconsistent across envs
-  }
-}
-
-// Modify entities without migration
-@Entity()
-export class User {
-  @Column()
-  email: string;
-
-  @Column() // Added without migration
-  newField: string; // Will crash in production if synchronize is false
-}
-```
-
-**Correct (use migrations for all schema changes):**
-
-```typescript
-// Configure TypeORM for migrations
-// data-source.ts
-export const dataSource = new DataSource({
-  type: 'postgres',
-  host: process.env.DB_HOST,
-  port: parseInt(process.env.DB_PORT),
-  username: process.env.DB_USERNAME,
-  password: process.env.DB_PASSWORD,
-  database: process.env.DB_NAME,
-  entities: ['dist/**/*.entity.js'],
-  migrations: ['dist/migrations/*.js'],
-  synchronize: false, // Always false in production
-  migrationsRun: true, // Run migrations on startup
-});
-
-// app.module.ts
-TypeOrmModule.forRootAsync({
-  inject: [ConfigService],
-  useFactory: (config: ConfigService) => ({
-    type: 'postgres',
-    host: config.get('DB_HOST'),
-    synchronize: config.get('NODE_ENV') === 'development', // Only in dev
-    migrations: ['dist/migrations/*.js'],
-    migrationsRun: true,
-  }),
-});
-
-// migrations/1705312800000-AddUserAge.ts
-import { MigrationInterface, QueryRunner } from 'typeorm';
-
-export class AddUserAge1705312800000 implements MigrationInterface {
-  name = 'AddUserAge1705312800000';
-
-  public async up(queryRunner: QueryRunner): Promise<void> {
-    // Add column with default to handle existing rows
-    await queryRunner.query(`
-      ALTER TABLE "users" ADD "age" integer DEFAULT 0
-    `);
-
-    // Add index for frequently queried columns
-    await queryRunner.query(`
-      CREATE INDEX "IDX_users_age" ON "users" ("age")
-    `);
-  }
-
-  public async down(queryRunner: QueryRunner): Promise<void> {
-    // Always implement down for rollback
-    await queryRunner.query(`DROP INDEX "IDX_users_age"`);
-    await queryRunner.query(`ALTER TABLE "users" DROP COLUMN "age"`);
-  }
-}
-
-// Safe column rename (two-step)
-export class RenameNameToFullName1705312900000 implements MigrationInterface {
-  public async up(queryRunner: QueryRunner): Promise<void> {
-    // Step 1: Add new column
-    await queryRunner.query(`
-      ALTER TABLE "users" ADD "full_name" varchar(255)
-    `);
-
-    // Step 2: Copy data
-    await queryRunner.query(`
-      UPDATE "users" SET "full_name" = "name"
-    `);
-
-    // Step 3: Add NOT NULL constraint
-    await queryRunner.query(`
-      ALTER TABLE "users" ALTER COLUMN "full_name" SET NOT NULL
-    `);
-
-    // Step 4: Drop old column (after verifying app works)
-    await queryRunner.query(`
-      ALTER TABLE "users" DROP COLUMN "name"
-    `);
-  }
-
-  public async down(queryRunner: QueryRunner): Promise<void> {
-    await queryRunner.query(`ALTER TABLE "users" ADD "name" varchar(255)`);
-    await queryRunner.query(`UPDATE "users" SET "name" = "full_name"`);
-    await queryRunner.query(`ALTER TABLE "users" DROP COLUMN "full_name"`);
-  }
-}
-```
-
-Reference: [TypeORM Migrations](https://typeorm.io/migrations)

.agents/skills/nestjs-best-practices/rules/db-use-transactions.md

@@ -1,140 +0,0 @@
----
-title: Use Transactions for Multi-Step Operations
-impact: HIGH
-impactDescription: Ensures data consistency in multi-step operations
-tags: database, transactions, typeorm, consistency
----
-
-## Use Transactions for Multi-Step Operations
-
-When multiple database operations must succeed or fail together, wrap them in a transaction. This prevents partial updates that leave your data in an inconsistent state. Use TypeORM's transaction APIs or the DataSource query runner for complex scenarios.
-
-**Incorrect (multiple saves without transaction):**
-
-```typescript
-// Multiple saves without transaction
-@Injectable()
-export class OrdersService {
-  async createOrder(userId: string, items: OrderItem[]): Promise<Order> {
-    // If any step fails, data is inconsistent
-    const order = await this.orderRepo.save({ userId, status: 'pending' });
-
-    for (const item of items) {
-      await this.orderItemRepo.save({ orderId: order.id, ...item });
-      await this.inventoryRepo.decrement({ productId: item.productId }, 'stock', item.quantity);
-    }
-
-    await this.paymentService.charge(order.id);
-    // If payment fails, order and inventory are already modified!
-
-    return order;
-  }
-}
-```
-
-**Correct (use DataSource.transaction for automatic rollback):**
-
-```typescript
-// Use DataSource.transaction() for automatic rollback
-@Injectable()
-export class OrdersService {
-  constructor(private dataSource: DataSource) {}
-
-  async createOrder(userId: string, items: OrderItem[]): Promise<Order> {
-    return this.dataSource.transaction(async (manager) => {
-      // All operations use the same transactional manager
-      const order = await manager.save(Order, { userId, status: 'pending' });
-
-      for (const item of items) {
-        await manager.save(OrderItem, { orderId: order.id, ...item });
-        await manager.decrement(
-          Inventory,
-          { productId: item.productId },
-          'stock',
-          item.quantity,
-        );
-      }
-
-      // If this throws, everything rolls back
-      await this.paymentService.chargeWithManager(manager, order.id);
-
-      return order;
-    });
-  }
-}
-
-// QueryRunner for manual transaction control
-@Injectable()
-export class TransferService {
-  constructor(private dataSource: DataSource) {}
-
-  async transfer(fromId: string, toId: string, amount: number): Promise<void> {
-    const queryRunner = this.dataSource.createQueryRunner();
-    await queryRunner.connect();
-    await queryRunner.startTransaction();
-
-    try {
-      // Debit source account
-      await queryRunner.manager.decrement(
-        Account,
-        { id: fromId },
-        'balance',
-        amount,
-      );
-
-      // Verify sufficient funds
-      const source = await queryRunner.manager.findOne(Account, {
-        where: { id: fromId },
-      });
-      if (source.balance < 0) {
-        throw new BadRequestException('Insufficient funds');
-      }
-
-      // Credit destination account
-      await queryRunner.manager.increment(
-        Account,
-        { id: toId },
-        'balance',
-        amount,
-      );
-
-      // Log the transaction
-      await queryRunner.manager.save(TransactionLog, {
-        fromId,
-        toId,
-        amount,
-        timestamp: new Date(),
-      });
-
-      await queryRunner.commitTransaction();
-    } catch (error) {
-      await queryRunner.rollbackTransaction();
-      throw error;
-    } finally {
-      await queryRunner.release();
-    }
-  }
-}
-
-// Repository method with transaction support
-@Injectable()
-export class UsersRepository {
-  constructor(
-    @InjectRepository(User) private repo: Repository<User>,
-    private dataSource: DataSource,
-  ) {}
-
-  async createWithProfile(
-    userData: CreateUserDto,
-    profileData: CreateProfileDto,
-  ): Promise<User> {
-    return this.dataSource.transaction(async (manager) => {
-      const user = await manager.save(User, userData);
-      await manager.save(Profile, { ...profileData, userId: user.id });
-      return user;
-    });
-  }
-}
-```
-
-Reference: [TypeORM Transactions](https://typeorm.io/transactions)

.agents/skills/nestjs-best-practices/rules/devops-graceful-shutdown.md

@@ -1,222 +0,0 @@
----
-title: Implement Graceful Shutdown
-impact: MEDIUM-HIGH
-impactDescription: Proper shutdown handling ensures zero-downtime deployments
-tags: devops, graceful-shutdown, lifecycle, kubernetes
----
-
-## Implement Graceful Shutdown
-
-Handle SIGTERM and SIGINT signals to gracefully shutdown your NestJS application. Stop accepting new requests, wait for in-flight requests to complete, close database connections, and clean up resources. This prevents data loss and connection errors during deployments.
-
-**Incorrect (ignoring shutdown signals):**
-
-```typescript
-// Ignore shutdown signals
-async function bootstrap() {
-  const app = await NestFactory.create(AppModule);
-  await app.listen(3000);
-  // App crashes immediately on SIGTERM
-  // In-flight requests fail
-  // Database connections are abruptly closed
-}
-
-// Long-running tasks without cancellation
-@Injectable()
-export class ProcessingService {
-  async processLargeFile(file: File): Promise<void> {
-    // No way to interrupt this during shutdown
-    for (let i = 0; i < file.chunks.length; i++) {
-      await this.processChunk(file.chunks[i]);
-      // May run for minutes, blocking shutdown
-    }
-  }
-}
-```
-
-**Correct (enable shutdown hooks and handle cleanup):**
-
-```typescript
-// Enable shutdown hooks in main.ts
-async function bootstrap() {
-  const app = await NestFactory.create(AppModule);
-
-  // Enable shutdown hooks
-  app.enableShutdownHooks();
-
-  // Optional: Add timeout for forced shutdown
-  const server = await app.listen(3000);
-  server.setTimeout(30000); // 30 second timeout
-
-  // Handle graceful shutdown
-  const signals = ['SIGTERM', 'SIGINT'];
-  signals.forEach((signal) => {
-    process.on(signal, async () => {
-      console.log(`Received ${signal}, starting graceful shutdown...`);
-
-      // Stop accepting new connections
-      server.close(async () => {
-        console.log('HTTP server closed');
-        await app.close();
-        process.exit(0);
-      });
-
-      // Force exit after timeout
-      setTimeout(() => {
-        console.error('Forced shutdown after timeout');
-        process.exit(1);
-      }, 30000);
-    });
-  });
-}
-
-// Lifecycle hooks for cleanup
-@Injectable()
-export class DatabaseService implements OnApplicationShutdown {
-  private readonly connections: Connection[] = [];
-
-  async onApplicationShutdown(signal?: string): Promise<void> {
-    console.log(`Database service shutting down on ${signal}`);
-
-    // Close all connections gracefully
-    await Promise.all(
-      this.connections.map((conn) => conn.close()),
-    );
-
-    console.log('All database connections closed');
-  }
-}
-
-// Queue processor with graceful shutdown
-@Injectable()
-export class QueueService implements OnApplicationShutdown, OnModuleDestroy {
-  private isShuttingDown = false;
-
-  onModuleDestroy(): void {
-    this.isShuttingDown = true;
-  }
-
-  async onApplicationShutdown(): Promise<void> {
-    // Wait for current jobs to complete
-    await this.queue.close();
-  }
-
-  async processJob(job: Job): Promise<void> {
-    if (this.isShuttingDown) {
-      throw new Error('Service is shutting down');
-    }
-    await this.doWork(job);
-  }
-}
-
-// WebSocket gateway cleanup
-@WebSocketGateway()
-export class EventsGateway implements OnApplicationShutdown {
-  @WebSocketServer()
-  server: Server;
-
-  async onApplicationShutdown(): Promise<void> {
-    // Notify all connected clients
-    this.server.emit('shutdown', { message: 'Server is shutting down' });
-
-    // Close all connections
-    this.server.disconnectSockets();
-  }
-}
-
-// Health check integration
-@Injectable()
-export class ShutdownService {
-  private isShuttingDown = false;
-
-  startShutdown(): void {
-    this.isShuttingDown = true;
-  }
-
-  isShutdown(): boolean {
-    return this.isShuttingDown;
-  }
-}
-
-@Controller('health')
-export class HealthController {
-  constructor(private shutdownService: ShutdownService) {}
-
-  @Get('ready')
-  @HealthCheck()
-  readiness(): Promise<HealthCheckResult> {
-    // Return 503 during shutdown - k8s stops sending traffic
-    if (this.shutdownService.isShutdown()) {
-      throw new ServiceUnavailableException('Shutting down');
-    }
-
-    return this.health.check([
-      () => this.db.pingCheck('database'),
-    ]);
-  }
-}
-
-// Integrate with shutdown
-@Injectable()
-export class AppShutdownService implements OnApplicationShutdown {
-  constructor(private shutdownService: ShutdownService) {}
-
-  async onApplicationShutdown(): Promise<void> {
-    // Mark as unhealthy first
-    this.shutdownService.startShutdown();
-
-    // Wait for k8s to update endpoints
-    await this.sleep(5000);
-
-    // Then proceed with cleanup
-  }
-}
-
-// Request tracking for in-flight requests
-@Injectable()
-export class RequestTracker implements NestMiddleware, OnApplicationShutdown {
-  private activeRequests = 0;
-  private isShuttingDown = false;
-  private shutdownPromise: Promise<void> | null = null;
-  private resolveShutdown: (() => void) | null = null;
-
-  use(req: Request, res: Response, next: NextFunction): void {
-    if (this.isShuttingDown) {
-      res.status(503).send('Service Unavailable');
-      return;
-    }
-
-    this.activeRequests++;
-
-    res.on('finish', () => {
-      this.activeRequests--;
-      if (this.isShuttingDown && this.activeRequests === 0 && this.resolveShutdown) {
-        this.resolveShutdown();
-      }
-    });
-
-    next();
-  }
-
-  async onApplicationShutdown(): Promise<void> {
-    this.isShuttingDown = true;
-
-    if (this.activeRequests > 0) {
-      console.log(`Waiting for ${this.activeRequests} requests to complete`);
-      this.shutdownPromise = new Promise((resolve) => {
-        this.resolveShutdown = resolve;
-      });
-
-      // Wait with timeout
-      await Promise.race([
-        this.shutdownPromise,
-        new Promise((resolve) => setTimeout(resolve, 30000)),
-      ]);
-    }
-
-    console.log('All requests completed');
-  }
-}
-```
-
-Reference: [NestJS Lifecycle Events](https://docs.nestjs.com/fundamentals/lifecycle-events)

.agents/skills/nestjs-best-practices/rules/devops-use-config-module.md

@@ -1,167 +0,0 @@
----
-title: Use ConfigModule for Environment Configuration
-impact: LOW-MEDIUM
-impactDescription: Proper configuration prevents deployment failures
-tags: devops, configuration, environment, validation
----
-
-## Use ConfigModule for Environment Configuration
-
-Use `@nestjs/config` for environment-based configuration. Validate configuration at startup to fail fast on misconfigurations. Use namespaced configuration for organization and type safety.
-
-**Incorrect (accessing process.env directly):**
-
-```typescript
-// Access process.env directly
-@Injectable()
-export class DatabaseService {
-  constructor() {
-    // No validation, can fail at runtime
-    this.connection = new Pool({
-      host: process.env.DB_HOST,
-      port: parseInt(process.env.DB_PORT), // NaN if missing
-      password: process.env.DB_PASSWORD, // undefined if missing
-    });
-  }
-}
-
-// Scattered env access
-@Injectable()
-export class EmailService {
-  sendEmail() {
-    // Different services access env differently
-    const apiKey = process.env.SENDGRID_API_KEY || 'default';
-    // Typos go unnoticed: process.env.SENDGRID_API_KY
-  }
-}
-```
-
-**Correct (use @nestjs/config with validation):**
-
-```typescript
-// Setup validated configuration
-import { ConfigModule, ConfigService, registerAs } from '@nestjs/config';
-import * as Joi from 'joi';
-
-// config/database.config.ts
-export const databaseConfig = registerAs('database', () => ({
-  host: process.env.DB_HOST,
-  port: parseInt(process.env.DB_PORT, 10),
-  username: process.env.DB_USERNAME,
-  password: process.env.DB_PASSWORD,
-  database: process.env.DB_NAME,
-}));
-
-// config/app.config.ts
-export const appConfig = registerAs('app', () => ({
-  port: parseInt(process.env.PORT, 10) || 3000,
-  environment: process.env.NODE_ENV || 'development',
-  apiPrefix: process.env.API_PREFIX || 'api',
-}));
-
-// config/validation.schema.ts
-export const validationSchema = Joi.object({
-  NODE_ENV: Joi.string()
-    .valid('development', 'production', 'test')
-    .default('development'),
-  PORT: Joi.number().default(3000),
-  DB_HOST: Joi.string().required(),
-  DB_PORT: Joi.number().default(5432),
-  DB_USERNAME: Joi.string().required(),
-  DB_PASSWORD: Joi.string().required(),
-  DB_NAME: Joi.string().required(),
-  JWT_SECRET: Joi.string().min(32).required(),
-  REDIS_URL: Joi.string().uri().required(),
-});
-
-// app.module.ts
-@Module({
-  imports: [
-    ConfigModule.forRoot({
-      isGlobal: true, // Available everywhere without importing
-      load: [databaseConfig, appConfig],
-      validationSchema,
-      validationOptions: {
-        abortEarly: true, // Stop on first error
-        allowUnknown: true, // Allow other env vars
-      },
-    }),
-    TypeOrmModule.forRootAsync({
-      inject: [ConfigService],
-      useFactory: (config: ConfigService) => ({
-        type: 'postgres',
-        host: config.get('database.host'),
-        port: config.get('database.port'),
-        username: config.get('database.username'),
-        password: config.get('database.password'),
-        database: config.get('database.database'),
-        autoLoadEntities: true,
-      }),
-    }),
-  ],
-})
-export class AppModule {}
-
-// Type-safe configuration access
-export interface AppConfig {
-  port: number;
-  environment: 'development' | 'production' | 'test';
-  apiPrefix: string;
-}
-
-export interface DatabaseConfig {
-  host: string;
-  port: number;
-  username: string;
-  password: string;
-  database: string;
-}
-
-// Type-safe access
-@Injectable()
-export class AppService {
-  constructor(private config: ConfigService) {}
-
-  getPort(): number {
-    // Type-safe with generic
-    return this.config.get<number>('app.port');
-  }
-
-  getDatabaseConfig(): DatabaseConfig {
-    return this.config.get<DatabaseConfig>('database');
-  }
-}
-
-// Inject namespaced config directly
-@Injectable()
-export class DatabaseService {
-  constructor(
-    @Inject(databaseConfig.KEY)
-    private dbConfig: ConfigType<typeof databaseConfig>,
-  ) {
-    // Full type inference!
-    const host = this.dbConfig.host; // string
-    const port = this.dbConfig.port; // number
-  }
-}
-
-// Environment files support
-ConfigModule.forRoot({
-  envFilePath: [
-    `.env.${process.env.NODE_ENV}.local`,
-    `.env.${process.env.NODE_ENV}`,
-    '.env.local',
-    '.env',
-  ],
-});
-
-// .env.development
-// DB_HOST=localhost
-// DB_PORT=5432
-
-// .env.production
-// DB_HOST=prod-db.example.com
-// DB_PORT=5432
-```
-
-Reference: [NestJS Configuration](https://docs.nestjs.com/techniques/configuration)

.agents/skills/nestjs-best-practices/rules/devops-use-logging.md

@@ -1,232 +0,0 @@
----
-title: Use Structured Logging
-impact: MEDIUM-HIGH
-impactDescription: Structured logging enables effective debugging and monitoring
-tags: devops, logging, structured-logs, pino
----
-
-## Use Structured Logging
-
-Use NestJS Logger with structured JSON output in production. Include contextual information (request ID, user ID, operation) to trace requests across services. Avoid console.log and implement proper log levels.
-
-**Incorrect (using console.log in production):**
-
-```typescript
-// Use console.log in production
-@Injectable()
-export class UsersService {
-  async createUser(dto: CreateUserDto): Promise<User> {
-    console.log('Creating user:', dto);
-    // Not structured, no levels, lost in production logs
-
-    try {
-      const user = await this.repo.save(dto);
-      console.log('User created:', user.id);
-      return user;
-    } catch (error) {
-      console.log('Error:', error); // Using log for errors
-      throw error;
-    }
-  }
-}
-
-// Log sensitive data
-console.log('Login attempt:', { email, password }); // SECURITY RISK!
-
-// Inconsistent log format
-logger.log('User ' + userId + ' created at ' + new Date());
-// Hard to parse, no structure
-```
-
-**Correct (use structured logging with context):**
-
-```typescript
-// Configure logger in main.ts
-async function bootstrap() {
-  const app = await NestFactory.create(AppModule, {
-    logger:
-      process.env.NODE_ENV === 'production'
-        ? ['error', 'warn', 'log']
-        : ['error', 'warn', 'log', 'debug', 'verbose'],
-  });
-}
-
-// Use NestJS Logger with context
-@Injectable()
-export class UsersService {
-  private readonly logger = new Logger(UsersService.name);
-
-  async createUser(dto: CreateUserDto): Promise<User> {
-    this.logger.log('Creating user', { email: dto.email });
-
-    try {
-      const user = await this.repo.save(dto);
-      this.logger.log('User created', { userId: user.id });
-      return user;
-    } catch (error) {
-      this.logger.error('Failed to create user', error.stack, {
-        email: dto.email,
-      });
-      throw error;
-    }
-  }
-}
-
-// Custom logger for JSON output
-@Injectable()
-export class JsonLogger implements LoggerService {
-  log(message: string, context?: object): void {
-    console.log(
-      JSON.stringify({
-        level: 'info',
-        timestamp: new Date().toISOString(),
-        message,
-        ...context,
-      }),
-    );
-  }
-
-  error(message: string, trace?: string, context?: object): void {
-    console.error(
-      JSON.stringify({
-        level: 'error',
-        timestamp: new Date().toISOString(),
-        message,
-        trace,
-        ...context,
-      }),
-    );
-  }
-
-  warn(message: string, context?: object): void {
-    console.warn(
-      JSON.stringify({
-        level: 'warn',
-        timestamp: new Date().toISOString(),
-        message,
-        ...context,
-      }),
-    );
-  }
-
-  debug(message: string, context?: object): void {
-    console.debug(
-      JSON.stringify({
-        level: 'debug',
-        timestamp: new Date().toISOString(),
-        message,
-        ...context,
-      }),
-    );
-  }
-}
-
-// Request context logging with ClsModule
-import { ClsModule, ClsService } from 'nestjs-cls';
-
-@Module({
-  imports: [
-    ClsModule.forRoot({
-      global: true,
-      middleware: {
-        mount: true,
-        generateId: true,
-      },
-    }),
-  ],
-})
-export class AppModule {}
-
-// Middleware to set request context
-@Injectable()
-export class RequestContextMiddleware implements NestMiddleware {
-  constructor(private cls: ClsService) {}
-
-  use(req: Request, res: Response, next: NextFunction): void {
-    const requestId = req.headers['x-request-id'] || randomUUID();
-    this.cls.set('requestId', requestId);
-    this.cls.set('userId', req.user?.id);
-
-    res.setHeader('x-request-id', requestId);
-    next();
-  }
-}
-
-// Logger that includes request context
-@Injectable()
-export class ContextLogger {
-  constructor(private cls: ClsService) {}
-
-  log(message: string, data?: object): void {
-    console.log(
-      JSON.stringify({
-        level: 'info',
-        timestamp: new Date().toISOString(),
-        requestId: this.cls.get('requestId'),
-        userId: this.cls.get('userId'),
-        message,
-        ...data,
-      }),
-    );
-  }
-
-  error(message: string, error: Error, data?: object): void {
-    console.error(
-      JSON.stringify({
-        level: 'error',
-        timestamp: new Date().toISOString(),
-        requestId: this.cls.get('requestId'),
-        userId: this.cls.get('userId'),
-        message,
-        error: error.message,
-        stack: error.stack,
-        ...data,
-      }),
-    );
-  }
-}
-
-// Pino integration for high-performance logging
-import { LoggerModule } from 'nestjs-pino';
-
-@Module({
-  imports: [
-    LoggerModule.forRoot({
-      pinoHttp: {
-        level: process.env.NODE_ENV === 'production' ? 'info' : 'debug',
-        transport:
-          process.env.NODE_ENV !== 'production'
-            ? { target: 'pino-pretty' }
-            : undefined,
-        redact: ['req.headers.authorization', 'req.body.password'],
-        serializers: {
-          req: (req) => ({
-            method: req.method,
-            url: req.url,
-            query: req.query,
-          }),
-          res: (res) => ({
-            statusCode: res.statusCode,
-          }),
-        },
-      },
-    }),
-  ],
-})
-export class AppModule {}
-
-// Usage with Pino
-@Injectable()
-export class UsersService {
-  constructor(private logger: PinoLogger) {
-    this.logger.setContext(UsersService.name);
-  }
-
-  async findOne(id: string): Promise<User> {
-    this.logger.info({ userId: id }, 'Finding user');
-    // Pino uses first arg for data, second for message
-  }
-}
-```
-
-Reference: [NestJS Logger](https://docs.nestjs.com/techniques/logger)

.agents/skills/nestjs-best-practices/rules/di-avoid-service-locator.md

@@ -1,104 +0,0 @@
----
-title: Avoid Service Locator Anti-Pattern
-impact: HIGH
-impactDescription: Hides dependencies and breaks testability
-tags: dependency-injection, anti-patterns, testing
----
-
-## Avoid Service Locator Anti-Pattern
-
-Avoid using `ModuleRef.get()` or global containers to resolve dependencies at runtime. This hides dependencies, makes code harder to test, and breaks the benefits of dependency injection. Use constructor injection instead.
-
-**Incorrect (service locator anti-pattern):**
-
-```typescript
-// Use ModuleRef to get dependencies dynamically
-@Injectable()
-export class OrdersService {
-  constructor(private moduleRef: ModuleRef) {}
-
-  async createOrder(dto: CreateOrderDto): Promise<Order> {
-    // Dependencies are hidden - not visible in constructor
-    const usersService = this.moduleRef.get(UsersService);
-    const inventoryService = this.moduleRef.get(InventoryService);
-    const paymentService = this.moduleRef.get(PaymentService);
-
-    const user = await usersService.findOne(dto.userId);
-    // ... rest of logic
-  }
-}
-
-// Global singleton container
-class ServiceContainer {
-  private static instance: ServiceContainer;
-  private services = new Map<string, any>();
-
-  static getInstance(): ServiceContainer {
-    if (!this.instance) {
-      this.instance = new ServiceContainer();
-    }
-    return this.instance;
-  }
-
-  get<T>(key: string): T {
-    return this.services.get(key);
-  }
-}
-```
-
-**Correct (constructor injection with explicit dependencies):**
-
-```typescript
-// Use constructor injection - dependencies are explicit
-@Injectable()
-export class OrdersService {
-  constructor(
-    private usersService: UsersService,
-    private inventoryService: InventoryService,
-    private paymentService: PaymentService,
-  ) {}
-
-  async createOrder(dto: CreateOrderDto): Promise<Order> {
-    const user = await this.usersService.findOne(dto.userId);
-    const inventory = await this.inventoryService.check(dto.items);
-    // Dependencies are clear and testable
-  }
-}
-
-// Easy to test with mocks
-describe('OrdersService', () => {
-  let service: OrdersService;
-
-  beforeEach(async () => {
-    const module = await Test.createTestingModule({
-      providers: [
-        OrdersService,
-        { provide: UsersService, useValue: mockUsersService },
-        { provide: InventoryService, useValue: mockInventoryService },
-        { provide: PaymentService, useValue: mockPaymentService },
-      ],
-    }).compile();
-
-    service = module.get(OrdersService);
-  });
-});
-
-// VALID: Factory pattern for dynamic instantiation
-@Injectable()
-export class HandlerFactory {
-  constructor(private moduleRef: ModuleRef) {}
-
-  getHandler(type: string): Handler {
-    switch (type) {
-      case 'email':
-        return this.moduleRef.get(EmailHandler);
-      case 'sms':
-        return this.moduleRef.get(SmsHandler);
-      default:
-        return this.moduleRef.get(DefaultHandler);
-    }
-  }
-}
-```
-
-Reference: [NestJS Module Reference](https://docs.nestjs.com/fundamentals/module-ref)

.agents/skills/nestjs-best-practices/rules/di-interface-segregation.md

@@ -1,165 +0,0 @@
----
-title: Apply Interface Segregation Principle
-impact: HIGH
-impactDescription: Reduces coupling and improves testability by 30-50%
-tags: dependency-injection, interfaces, solid, isp
----
-
-## Apply Interface Segregation Principle
-
-Clients should not be forced to depend on interfaces they don't use. In NestJS, this means keeping interfaces small and focused on specific capabilities rather than creating "fat" interfaces that bundle unrelated methods. When a service only needs to send emails, it shouldn't depend on an interface that also includes SMS, push notifications, and logging. Split large interfaces into role-based ones.
-
-**Incorrect (fat interface forcing unused dependencies):**
-
-```typescript
-// Fat interface - forces all consumers to depend on everything
-interface NotificationService {
-  sendEmail(to: string, subject: string, body: string): Promise<void>;
-  sendSms(phone: string, message: string): Promise<void>;
-  sendPush(userId: string, notification: PushPayload): Promise<void>;
-  sendSlack(channel: string, message: string): Promise<void>;
-  logNotification(type: string, payload: any): Promise<void>;
-  getDeliveryStatus(id: string): Promise<DeliveryStatus>;
-  retryFailed(id: string): Promise<void>;
-  scheduleNotification(dto: ScheduleDto): Promise<string>;
-}
-
-// Consumer only needs email, but must mock everything for tests
-@Injectable()
-export class OrdersService {
-  constructor(
-    private notifications: NotificationService, // Depends on 8 methods, uses 1
-  ) {}
-
-  async confirmOrder(order: Order): Promise<void> {
-    await this.notifications.sendEmail(
-      order.customer.email,
-      'Order Confirmed',
-      `Your order ${order.id} has been confirmed.`,
-    );
-  }
-}
-
-// Testing is painful - must mock unused methods
-const mockNotificationService = {
-  sendEmail: jest.fn(),
-  sendSms: jest.fn(),           // Never used, but required
-  sendPush: jest.fn(),          // Never used, but required
-  sendSlack: jest.fn(),         // Never used, but required
-  logNotification: jest.fn(),   // Never used, but required
-  getDeliveryStatus: jest.fn(), // Never used, but required
-  retryFailed: jest.fn(),       // Never used, but required
-  scheduleNotification: jest.fn(), // Never used, but required
-};
-```
-
-**Correct (segregated interfaces by capability):**
-
-```typescript
-// Segregated interfaces - each focused on one capability
-interface EmailSender {
-  sendEmail(to: string, subject: string, body: string): Promise<void>;
-}
-
-interface SmsSender {
-  sendSms(phone: string, message: string): Promise<void>;
-}
-
-interface PushSender {
-  sendPush(userId: string, notification: PushPayload): Promise<void>;
-}
-
-interface NotificationLogger {
-  logNotification(type: string, payload: any): Promise<void>;
-}
-
-interface NotificationScheduler {
-  scheduleNotification(dto: ScheduleDto): Promise<string>;
-}
-
-// Implementation can implement multiple interfaces
-@Injectable()
-export class NotificationService implements EmailSender, SmsSender, PushSender {
-  async sendEmail(to: string, subject: string, body: string): Promise<void> {
-    // Email implementation
-  }
-
-  async sendSms(phone: string, message: string): Promise<void> {
-    // SMS implementation
-  }
-
-  async sendPush(userId: string, notification: PushPayload): Promise<void> {
-    // Push implementation
-  }
-}
-
-// Or separate implementations
-@Injectable()
-export class SendGridEmailService implements EmailSender {
-  async sendEmail(to: string, subject: string, body: string): Promise<void> {
-    // SendGrid-specific implementation
-  }
-}
-
-// Consumer depends only on what it needs
-@Injectable()
-export class OrdersService {
-  constructor(
-    @Inject(EMAIL_SENDER) private emailSender: EmailSender, // Minimal dependency
-  ) {}
-
-  async confirmOrder(order: Order): Promise<void> {
-    await this.emailSender.sendEmail(
-      order.customer.email,
-      'Order Confirmed',
-      `Your order ${order.id} has been confirmed.`,
-    );
-  }
-}
-
-// Testing is simple - only mock what's used
-const mockEmailSender: EmailSender = {
-  sendEmail: jest.fn(),
-};
-
-// Module registration with tokens
-export const EMAIL_SENDER = Symbol('EMAIL_SENDER');
-export const SMS_SENDER = Symbol('SMS_SENDER');
-
-@Module({
-  providers: [
-    { provide: EMAIL_SENDER, useClass: SendGridEmailService },
-    { provide: SMS_SENDER, useClass: TwilioSmsService },
-  ],
-  exports: [EMAIL_SENDER, SMS_SENDER],
-})
-export class NotificationModule {}
-```
-
-**Combining interfaces when needed:**
-
-```typescript
-// Sometimes a consumer legitimately needs multiple capabilities
-interface EmailAndSmsSender extends EmailSender, SmsSender {}
-
-// Or use intersection types
-type MultiChannelSender = EmailSender & SmsSender & PushSender;
-
-// Consumer that genuinely needs multiple channels
-@Injectable()
-export class AlertService {
-  constructor(
-    @Inject(MULTI_CHANNEL_SENDER)
-    private sender: EmailSender & SmsSender,
-  ) {}
-
-  async sendCriticalAlert(user: User, message: string): Promise<void> {
-    await Promise.all([
-      this.sender.sendEmail(user.email, 'Critical Alert', message),
-      this.sender.sendSms(user.phone, message),
-    ]);
-  }
-}
-```
-
-Reference: [Interface Segregation Principle](https://en.wikipedia.org/wiki/Interface_segregation_principle)

.agents/skills/nestjs-best-practices/rules/di-liskov-substitution.md

@@ -1,221 +0,0 @@
----
-title: Honor Liskov Substitution Principle
-impact: HIGH
-impactDescription: Ensures implementations are truly interchangeable without breaking callers
-tags: dependency-injection, inheritance, solid, lsp
----
-
-## Honor Liskov Substitution Principle
-
-Subtypes must be substitutable for their base types without altering program correctness. In NestJS with dependency injection, this means any implementation of an interface or abstract class must honor the contract completely. A mock payment service used in tests must behave like a real payment service (return similar shapes, handle errors the same way). Violating LSP causes subtle bugs when swapping implementations.
-
-**Incorrect (implementation violates the contract):**
-
-```typescript
-// Base interface with clear contract
-interface PaymentGateway {
-  /**
-   * Charges the specified amount.
-   * @returns PaymentResult on success
-   * @throws PaymentFailedException on payment failure
-   */
-  charge(amount: number, currency: string): Promise<PaymentResult>;
-}
-
-// Production implementation - follows the contract
-@Injectable()
-export class StripeService implements PaymentGateway {
-  async charge(amount: number, currency: string): Promise<PaymentResult> {
-    const response = await this.stripe.charges.create({ amount, currency });
-    return { success: true, transactionId: response.id, amount };
-  }
-}
-
-// Mock that violates LSP - different behavior!
-@Injectable()
-export class MockPaymentService implements PaymentGateway {
-  async charge(amount: number, currency: string): Promise<PaymentResult> {
-    // VIOLATION 1: Throws for valid input (contract says return PaymentResult)
-    if (amount > 1000) {
-      throw new Error('Mock does not support large amounts');
-    }
-
-    // VIOLATION 2: Returns null instead of PaymentResult
-    if (currency !== 'USD') {
-      return null as any; // Real service would convert or reject properly
-    }
-
-    // VIOLATION 3: Missing required field
-    return { success: true } as PaymentResult; // Missing transactionId!
-  }
-}
-
-// Consumer trusts the contract
-@Injectable()
-export class OrdersService {
-  constructor(@Inject(PAYMENT_GATEWAY) private payment: PaymentGateway) {}
-
-  async checkout(order: Order): Promise<void> {
-    const result = await this.payment.charge(order.total, order.currency);
-    // These fail with MockPaymentService:
-    await this.saveTransaction(result.transactionId); // undefined!
-    await this.sendReceipt(result); // might be null!
-  }
-}
-```
-
-**Correct (implementations honor the contract):**
-
-```typescript
-// Well-defined interface with documented behavior
-interface PaymentGateway {
-  /**
-   * Charges the specified amount.
-   * @param amount - Amount in smallest currency unit (cents)
-   * @param currency - ISO 4217 currency code
-   * @returns PaymentResult with transactionId, success status, and amount
-   * @throws PaymentFailedException if charge is declined
-   * @throws InvalidCurrencyException if currency is not supported
-   */
-  charge(amount: number, currency: string): Promise<PaymentResult>;
-
-  /**
-   * Refunds a previous charge.
-   * @throws TransactionNotFoundException if transactionId is invalid
-   */
-  refund(transactionId: string, amount?: number): Promise<RefundResult>;
-}
-
-// Production implementation
-@Injectable()
-export class StripeService implements PaymentGateway {
-  async charge(amount: number, currency: string): Promise<PaymentResult> {
-    try {
-      const response = await this.stripe.charges.create({ amount, currency });
-      return {
-        success: true,
-        transactionId: response.id,
-        amount: response.amount,
-      };
-    } catch (error) {
-      if (error.type === 'card_error') {
-        throw new PaymentFailedException(error.message);
-      }
-      throw error;
-    }
-  }
-
-  async refund(transactionId: string, amount?: number): Promise<RefundResult> {
-    // Implementation...
-  }
-}
-
-// Mock that honors LSP - same contract, same behavior shape
-@Injectable()
-export class MockPaymentService implements PaymentGateway {
-  private transactions = new Map<string, PaymentResult>();
-
-  async charge(amount: number, currency: string): Promise<PaymentResult> {
-    // Honor the contract: validate currency like real service would
-    if (!['USD', 'EUR', 'GBP'].includes(currency)) {
-      throw new InvalidCurrencyException(`Unsupported currency: ${currency}`);
-    }
-
-    // Simulate decline for specific test scenarios
-    if (amount === 99999) {
-      throw new PaymentFailedException('Card declined (test scenario)');
-    }
-
-    // Return same shape as production
-    const result: PaymentResult = {
-      success: true,
-      transactionId: `mock_${Date.now()}_${Math.random().toString(36)}`,
-      amount,
-    };
-
-    this.transactions.set(result.transactionId, result);
-    return result;
-  }
-
-  async refund(transactionId: string, amount?: number): Promise<RefundResult> {
-    // Honor the contract: throw if transaction not found
-    if (!this.transactions.has(transactionId)) {
-      throw new TransactionNotFoundException(transactionId);
-    }
-
-    return {
-      success: true,
-      refundId: `refund_${transactionId}`,
-      amount: amount ?? this.transactions.get(transactionId)!.amount,
-    };
-  }
-}
-
-// Consumer can swap implementations safely
-@Injectable()
-export class OrdersService {
-  constructor(@Inject(PAYMENT_GATEWAY) private payment: PaymentGateway) {}
-
-  async checkout(order: Order): Promise<Order> {
-    try {
-      const result = await this.payment.charge(order.total, order.currency);
-      // Works with both StripeService and MockPaymentService
-      order.transactionId = result.transactionId;
-      order.status = 'paid';
-      return order;
-    } catch (error) {
-      if (error instanceof PaymentFailedException) {
-        order.status = 'payment_failed';
-        return order;
-      }
-      throw error;
-    }
-  }
-}
-```
-
-**Testing LSP compliance:**
-
-```typescript
-// Shared test suite that any implementation must pass
-function testPaymentGatewayContract(
-  createGateway: () => PaymentGateway,
-) {
-  describe('PaymentGateway contract', () => {
-    let gateway: PaymentGateway;
-
-    beforeEach(() => {
-      gateway = createGateway();
-    });
-
-    it('returns PaymentResult with all required fields', async () => {
-      const result = await gateway.charge(1000, 'USD');
-      expect(result).toHaveProperty('success');
-      expect(result).toHaveProperty('transactionId');
-      expect(result).toHaveProperty('amount');
-      expect(typeof result.transactionId).toBe('string');
-    });
-
-    it('throws InvalidCurrencyException for unsupported currency', async () => {
-      await expect(gateway.charge(1000, 'INVALID'))
-        .rejects.toThrow(InvalidCurrencyException);
-    });
-
-    it('throws TransactionNotFoundException for invalid refund', async () => {
-      await expect(gateway.refund('nonexistent'))
-        .rejects.toThrow(TransactionNotFoundException);
-    });
-  });
-}
-
-// Run against all implementations
-describe('StripeService', () => {
-  testPaymentGatewayContract(() => new StripeService(mockStripeClient));
-});
-
-describe('MockPaymentService', () => {
-  testPaymentGatewayContract(() => new MockPaymentService());
-});
-```
-
-Reference: [Liskov Substitution Principle](https://en.wikipedia.org/wiki/Liskov_substitution_principle)

.agents/skills/nestjs-best-practices/rules/di-prefer-constructor-injection.md

@@ -1,86 +0,0 @@
----
-title: Prefer Constructor Injection
-impact: CRITICAL
-impactDescription: Required for proper DI and testing
-tags: dependency-injection, constructor, testing
----
-
-## Prefer Constructor Injection
-
-Always use constructor injection over property injection. Constructor injection makes dependencies explicit, enables TypeScript type checking, ensures dependencies are available when the class is instantiated, and improves testability. This is required for proper DI, testing, and TypeScript support.
-
-**Incorrect (property injection with hidden dependencies):**
-
-```typescript
-// Property injection - avoid unless necessary
-@Injectable()
-export class UsersService {
-  @Inject()
-  private userRepo: UserRepository; // Hidden dependency
-
-  @Inject('CONFIG')
-  private config: ConfigType; // Also hidden
-
-  async findAll() {
-    return this.userRepo.find();
-  }
-}
-
-// Problems:
-// 1. Dependencies not visible in constructor
-// 2. Service can be instantiated without dependencies in tests
-// 3. TypeScript can't enforce dependency types at instantiation
-```
-
-**Correct (constructor injection with explicit dependencies):**
-
-```typescript
-// Constructor injection - explicit and testable
-@Injectable()
-export class UsersService {
-  constructor(
-    private readonly userRepo: UserRepository,
-    @Inject('CONFIG') private readonly config: ConfigType,
-  ) {}
-
-  async findAll(): Promise<User[]> {
-    return this.userRepo.find();
-  }
-}
-
-// Testing is straightforward
-describe('UsersService', () => {
-  let service: UsersService;
-  let mockRepo: jest.Mocked<UserRepository>;
-
-  beforeEach(() => {
-    mockRepo = {
-      find: jest.fn(),
-      save: jest.fn(),
-    } as any;
-
-    service = new UsersService(mockRepo, { dbUrl: 'test' });
-  });
-
-  it('should find all users', async () => {
-    mockRepo.find.mockResolvedValue([{ id: '1', name: 'Test' }]);
-    const result = await service.findAll();
-    expect(result).toHaveLength(1);
-  });
-});
-
-// Only use property injection for optional dependencies
-@Injectable()
-export class LoggingService {
-  @Optional()
-  @Inject('ANALYTICS')
-  private analytics?: AnalyticsService;
-
-  log(message: string) {
-    console.log(message);
-    this.analytics?.track('log', message); // Optional enhancement
-  }
-}
-```
-
-Reference: [NestJS Providers](https://docs.nestjs.com/providers)

.agents/skills/nestjs-best-practices/rules/di-scope-awareness.md

@@ -1,94 +0,0 @@
----
-title: Understand Provider Scopes
-impact: CRITICAL
-impactDescription: Prevents data leaks and performance issues
-tags: dependency-injection, scopes, request-context
----
-
-## Understand Provider Scopes
-
-NestJS has three provider scopes: DEFAULT (singleton), REQUEST (per-request instance), and TRANSIENT (new instance for each injection). Most providers should be singletons. Request-scoped providers have performance implications as they bubble up through the dependency tree. Understanding scopes prevents memory leaks and incorrect data sharing.
-
-**Incorrect (wrong scope usage):**
-
-```typescript
-// Request-scoped when not needed (performance hit)
-@Injectable({ scope: Scope.REQUEST })
-export class UsersService {
-  // This creates a new instance for EVERY request
-  // All dependencies also become request-scoped
-  async findAll() {
-    return this.userRepo.find();
-  }
-}
-
-// Singleton with mutable request state
-@Injectable() // Default: singleton
-export class RequestContextService {
-  private userId: string; // DANGER: Shared across all requests!
-
-  setUser(userId: string) {
-    this.userId = userId; // Overwrites for all concurrent requests
-  }
-
-  getUser() {
-    return this.userId; // Returns wrong user!
-  }
-}
-```
-
-**Correct (appropriate scope for each use case):**
-
-```typescript
-// Singleton for stateless services (default, most common)
-@Injectable()
-export class UsersService {
-  constructor(private readonly userRepo: UserRepository) {}
-
-  async findById(id: string): Promise<User> {
-    return this.userRepo.findOne({ where: { id } });
-  }
-}
-
-// Request-scoped ONLY when you need request context
-@Injectable({ scope: Scope.REQUEST })
-export class RequestContextService {
-  private userId: string;
-
-  setUser(userId: string) {
-    this.userId = userId;
-  }
-
-  getUser(): string {
-    return this.userId;
-  }
-}
-
-// Better: Use NestJS built-in request context
-import { REQUEST } from '@nestjs/core';
-import { Request } from 'express';
-
-@Injectable({ scope: Scope.REQUEST })
-export class AuditService {
-  constructor(@Inject(REQUEST) private request: Request) {}
-
-  log(action: string) {
-    console.log(`User ${this.request.user?.id} performed ${action}`);
-  }
-}
-
-// Best: Use ClsModule for async context (no scope bubble-up)
-import { ClsService } from 'nestjs-cls';
-
-@Injectable() // Stays singleton!
-export class AuditService {
-  constructor(private cls: ClsService) {}
-
-  log(action: string) {
-    const userId = this.cls.get('userId');
-    console.log(`User ${userId} performed ${action}`);
-  }
-}
-```
-
-Reference: [NestJS Injection Scopes](https://docs.nestjs.com/fundamentals/injection-scopes)

.agents/skills/nestjs-best-practices/rules/di-use-interfaces-tokens.md

@@ -1,101 +0,0 @@
----
-title: Use Injection Tokens for Interfaces
-impact: HIGH
-impactDescription: Enables interface-based DI at runtime
-tags: dependency-injection, tokens, interfaces
----
-
-## Use Injection Tokens for Interfaces
-
-TypeScript interfaces are erased at compile time and can't be used as injection tokens. Use string tokens, symbols, or abstract classes when you want to inject implementations of interfaces. This enables swapping implementations for testing or different environments.
-
-**Incorrect (interface can't be used as token):**
-
-```typescript
-// Interface can't be used as injection token
-interface PaymentGateway {
-  charge(amount: number): Promise<PaymentResult>;
-}
-
-@Injectable()
-export class StripeService implements PaymentGateway {
-  charge(amount: number) { /* ... */ }
-}
-
-@Injectable()
-export class OrdersService {
-  // This WON'T work - PaymentGateway doesn't exist at runtime
-  constructor(private payment: PaymentGateway) {}
-}
-```
-
-**Correct (symbol tokens or abstract classes):**
-
-```typescript
-// Option 1: String/Symbol tokens (most flexible)
-export const PAYMENT_GATEWAY = Symbol('PAYMENT_GATEWAY');
-
-export interface PaymentGateway {
-  charge(amount: number): Promise<PaymentResult>;
-}
-
-@Injectable()
-export class StripeService implements PaymentGateway {
-  async charge(amount: number): Promise<PaymentResult> {
-    // Stripe implementation
-  }
-}
-
-@Injectable()
-export class MockPaymentService implements PaymentGateway {
-  async charge(amount: number): Promise<PaymentResult> {
-    return { success: true, id: 'mock-id' };
-  }
-}
-
-// Module registration
-@Module({
-  providers: [
-    {
-      provide: PAYMENT_GATEWAY,
-      useClass: process.env.NODE_ENV === 'test'
-        ? MockPaymentService
-        : StripeService,
-    },
-  ],
-  exports: [PAYMENT_GATEWAY],
-})
-export class PaymentModule {}
-
-// Injection
-@Injectable()
-export class OrdersService {
-  constructor(
-    @Inject(PAYMENT_GATEWAY) private payment: PaymentGateway,
-  ) {}
-
-  async createOrder(dto: CreateOrderDto) {
-    await this.payment.charge(dto.amount);
-  }
-}
-
-// Option 2: Abstract class (carries runtime type info)
-export abstract class PaymentGateway {
-  abstract charge(amount: number): Promise<PaymentResult>;
-}
-
-@Injectable()
-export class StripeService extends PaymentGateway {
-  async charge(amount: number): Promise<PaymentResult> {
-    // Implementation
-  }
-}
-
-// No @Inject needed with abstract class
-@Injectable()
-export class OrdersService {
-  constructor(private payment: PaymentGateway) {}
-}
-```
-
-Reference: [NestJS Custom Providers](https://docs.nestjs.com/fundamentals/custom-providers)

.agents/skills/nestjs-best-practices/rules/error-handle-async-errors.md

@@ -1,125 +0,0 @@
----
-title: Handle Async Errors Properly
-impact: HIGH
-impactDescription: Prevents process crashes from unhandled rejections
-tags: error-handling, async, promises
----
-
-## Handle Async Errors Properly
-
-NestJS automatically catches errors from async route handlers, but errors from background tasks, event handlers, and manually created promises can crash your application. Always handle async errors explicitly and use global handlers as a safety net.
-
-**Incorrect (fire-and-forget without error handling):**
-
-```typescript
-// Fire-and-forget without error handling
-@Injectable()
-export class UsersService {
-  async createUser(dto: CreateUserDto): Promise<User> {
-    const user = await this.repo.save(dto);
-
-    // Fire and forget - if this fails, error is unhandled!
-    this.emailService.sendWelcome(user.email);
-
-    return user;
-  }
-}
-
-// Unhandled promise in event handler
-@Injectable()
-export class OrdersService {
-  @OnEvent('order.created')
-  handleOrderCreated(event: OrderCreatedEvent) {
-    // This returns a promise but it's not awaited!
-    this.processOrder(event);
-    // Errors will crash the process
-  }
-
-  private async processOrder(event: OrderCreatedEvent): Promise<void> {
-    await this.inventoryService.reserve(event.items);
-    await this.notificationService.send(event.userId);
-  }
-}
-
-// Missing try-catch in scheduled tasks
-@Cron('0 0 * * *')
-async dailyCleanup(): Promise<void> {
-  await this.cleanupService.run();
-  // If this throws, no error handling
-}
-```
-
-**Correct (explicit async error handling):**
-
-```typescript
-// Handle fire-and-forget with explicit catch
-@Injectable()
-export class UsersService {
-  private readonly logger = new Logger(UsersService.name);
-
-  async createUser(dto: CreateUserDto): Promise<User> {
-    const user = await this.repo.save(dto);
-
-    // Explicitly catch and log errors
-    this.emailService.sendWelcome(user.email).catch((error) => {
-      this.logger.error('Failed to send welcome email', error.stack);
-      // Optionally queue for retry
-    });
-
-    return user;
-  }
-}
-
-// Properly handle async event handlers
-@Injectable()
-export class OrdersService {
-  private readonly logger = new Logger(OrdersService.name);
-
-  @OnEvent('order.created')
-  async handleOrderCreated(event: OrderCreatedEvent): Promise<void> {
-    try {
-      await this.processOrder(event);
-    } catch (error) {
-      this.logger.error('Failed to process order', { event, error });
-      // Don't rethrow - would crash the process
-      await this.deadLetterQueue.add('order.created', event);
-    }
-  }
-}
-
-// Safe scheduled tasks
-@Injectable()
-export class CleanupService {
-  private readonly logger = new Logger(CleanupService.name);
-
-  @Cron('0 0 * * *')
-  async dailyCleanup(): Promise<void> {
-    try {
-      await this.cleanupService.run();
-      this.logger.log('Daily cleanup completed');
-    } catch (error) {
-      this.logger.error('Daily cleanup failed', error.stack);
-      // Alert or retry logic
-    }
-  }
-}
-
-// Global unhandled rejection handler in main.ts
-async function bootstrap() {
-  const app = await NestFactory.create(AppModule);
-  const logger = new Logger('Bootstrap');
-
-  process.on('unhandledRejection', (reason, promise) => {
-    logger.error('Unhandled Rejection at:', promise, 'reason:', reason);
-  });
-
-  process.on('uncaughtException', (error) => {
-    logger.error('Uncaught Exception:', error);
-    process.exit(1);
-  });
-
-  await app.listen(3000);
-}
-```
-
-Reference: [Node.js Unhandled Rejections](https://nodejs.org/api/process.html#event-unhandledrejection)

.agents/skills/nestjs-best-practices/rules/error-throw-http-exceptions.md

@@ -1,114 +0,0 @@
----
-title: Throw HTTP Exceptions from Services
-impact: HIGH
-impactDescription: Keeps controllers thin and simplifies error handling
-tags: error-handling, exceptions, services
----
-
-## Throw HTTP Exceptions from Services
-
-It's acceptable (and often preferable) to throw `HttpException` subclasses from services in HTTP applications. This keeps controllers thin and allows services to communicate appropriate error states. For truly layer-agnostic services, use domain exceptions that map to HTTP status codes.
-
-**Incorrect (return error objects instead of throwing):**
-
-```typescript
-// Return error objects instead of throwing
-@Injectable()
-export class UsersService {
-  async findById(id: string): Promise<{ user?: User; error?: string }> {
-    const user = await this.repo.findOne({ where: { id } });
-    if (!user) {
-      return { error: 'User not found' }; // Controller must check this
-    }
-    return { user };
-  }
-}
-
-@Controller('users')
-export class UsersController {
-  @Get(':id')
-  async findOne(@Param('id') id: string) {
-    const result = await this.usersService.findById(id);
-    if (result.error) {
-      throw new NotFoundException(result.error);
-    }
-    return result.user;
-  }
-}
-```
-
-**Correct (throw exceptions directly from service):**
-
-```typescript
-// Throw exceptions directly from service
-@Injectable()
-export class UsersService {
-  constructor(private readonly repo: UserRepository) {}
-
-  async findById(id: string): Promise<User> {
-    const user = await this.repo.findOne({ where: { id } });
-    if (!user) {
-      throw new NotFoundException(`User #${id} not found`);
-    }
-    return user;
-  }
-
-  async create(dto: CreateUserDto): Promise<User> {
-    const existing = await this.repo.findOne({
-      where: { email: dto.email },
-    });
-    if (existing) {
-      throw new ConflictException('Email already registered');
-    }
-    return this.repo.save(dto);
-  }
-
-  async update(id: string, dto: UpdateUserDto): Promise<User> {
-    const user = await this.findById(id); // Throws if not found
-    Object.assign(user, dto);
-    return this.repo.save(user);
-  }
-}
-
-// Controller stays thin
-@Controller('users')
-export class UsersController {
-  @Get(':id')
-  findOne(@Param('id') id: string): Promise<User> {
-    return this.usersService.findById(id);
-  }
-
-  @Post()
-  create(@Body() dto: CreateUserDto): Promise<User> {
-    return this.usersService.create(dto);
-  }
-}
-
-// For layer-agnostic services, use domain exceptions
-export class EntityNotFoundException extends Error {
-  constructor(
-    public readonly entity: string,
-    public readonly id: string,
-  ) {
-    super(`${entity} with ID "${id}" not found`);
-  }
-}
-
-// Map to HTTP in exception filter
-@Catch(EntityNotFoundException)
-export class EntityNotFoundFilter implements ExceptionFilter {
-  catch(exception: EntityNotFoundException, host: ArgumentsHost) {
-    const ctx = host.switchToHttp();
-    const response = ctx.getResponse<Response>();
-
-    response.status(404).json({
-      statusCode: 404,
-      message: exception.message,
-      entity: exception.entity,
-      id: exception.id,
-    });
-  }
-}
-```
-
-Reference: [NestJS Exception Filters](https://docs.nestjs.com/exception-filters)

.agents/skills/nestjs-best-practices/rules/error-use-exception-filters.md

@@ -1,140 +0,0 @@
----
-title: Use Exception Filters for Error Handling
-impact: HIGH
-impactDescription: Consistent, centralized error handling
-tags: error-handling, exception-filters, consistency
----
-
-## Use Exception Filters for Error Handling
-
-Never catch exceptions and manually format error responses in controllers. Use NestJS exception filters to handle errors consistently across your application. Create custom exception filters for specific error types and a global filter for unhandled exceptions.
-
-**Incorrect (manual error handling in controllers):**
-
-```typescript
-// Manual error handling in controllers
-@Controller('users')
-export class UsersController {
-  @Get(':id')
-  async findOne(@Param('id') id: string, @Res() res: Response) {
-    try {
-      const user = await this.usersService.findById(id);
-      if (!user) {
-        return res.status(404).json({
-          statusCode: 404,
-          message: 'User not found',
-        });
-      }
-      return res.json(user);
-    } catch (error) {
-      console.error(error);
-      return res.status(500).json({
-        statusCode: 500,
-        message: 'Internal server error',
-      });
-    }
-  }
-}
-```
-
-**Correct (exception filters with consistent handling):**
-
-```typescript
-// Use built-in and custom exceptions
-@Controller('users')
-export class UsersController {
-  @Get(':id')
-  async findOne(@Param('id') id: string): Promise<User> {
-    const user = await this.usersService.findById(id);
-    if (!user) {
-      throw new NotFoundException(`User #${id} not found`);
-    }
-    return user;
-  }
-}
-
-// Custom domain exception
-export class UserNotFoundException extends NotFoundException {
-  constructor(userId: string) {
-    super({
-      statusCode: 404,
-      error: 'Not Found',
-      message: `User with ID "${userId}" not found`,
-      code: 'USER_NOT_FOUND',
-    });
-  }
-}
-
-// Custom exception filter for domain errors
-@Catch(DomainException)
-export class DomainExceptionFilter implements ExceptionFilter {
-  catch(exception: DomainException, host: ArgumentsHost) {
-    const ctx = host.switchToHttp();
-    const response = ctx.getResponse<Response>();
-    const request = ctx.getRequest<Request>();
-
-    const status = exception.getStatus?.() || 400;
-
-    response.status(status).json({
-      statusCode: status,
-      code: exception.code,
-      message: exception.message,
-      timestamp: new Date().toISOString(),
-      path: request.url,
-    });
-  }
-}
-
-// Global exception filter for unhandled errors
-@Catch()
-export class AllExceptionsFilter implements ExceptionFilter {
-  constructor(private readonly logger: Logger) {}
-
-  catch(exception: unknown, host: ArgumentsHost) {
-    const ctx = host.switchToHttp();
-    const response = ctx.getResponse<Response>();
-    const request = ctx.getRequest<Request>();
-
-    const status =
-      exception instanceof HttpException
-        ? exception.getStatus()
-        : HttpStatus.INTERNAL_SERVER_ERROR;
-
-    const message =
-      exception instanceof HttpException
-        ? exception.message
-        : 'Internal server error';
-
-    this.logger.error(
-      `${request.method} ${request.url}`,
-      exception instanceof Error ? exception.stack : exception,
-    );
-
-    response.status(status).json({
-      statusCode: status,
-      message,
-      timestamp: new Date().toISOString(),
-      path: request.url,
-    });
-  }
-}
-
-// Register globally in main.ts
-app.useGlobalFilters(
-  new AllExceptionsFilter(app.get(Logger)),
-  new DomainExceptionFilter(),
-);
-
-// Or via module
-@Module({
-  providers: [
-    {
-      provide: APP_FILTER,
-      useClass: AllExceptionsFilter,
-    },
-  ],
-})
-export class AppModule {}
-```
-
-Reference: [NestJS Exception Filters](https://docs.nestjs.com/exception-filters)

.agents/skills/nestjs-best-practices/rules/micro-use-health-checks.md

@@ -1,226 +0,0 @@
----
-title: Implement Health Checks for Microservices
-impact: MEDIUM-HIGH
-impactDescription: Health checks enable orchestrators to manage service lifecycle
-tags: microservices, health-checks, terminus, kubernetes
----
-
-## Implement Health Checks for Microservices
-
-Implement liveness and readiness probes using `@nestjs/terminus`. Liveness checks determine if the service should be restarted. Readiness checks determine if the service can accept traffic. Proper health checks enable Kubernetes and load balancers to route traffic correctly.
-
-**Incorrect (simple ping that doesn't check dependencies):**
-
-```typescript
-// Simple ping that doesn't check dependencies
-@Controller('health')
-export class HealthController {
-  @Get()
-  check(): string {
-    return 'OK'; // Service might be unhealthy but returns OK
-  }
-}
-
-// Health check that blocks on slow dependencies
-@Controller('health')
-export class HealthController {
-  @Get()
-  async check(): Promise<string> {
-    // If database is slow, health check times out
-    await this.userRepo.findOne({ where: { id: '1' } });
-    await this.redis.ping();
-    await this.externalApi.healthCheck();
-    return 'OK';
-  }
-}
-```
-
-**Correct (use @nestjs/terminus for comprehensive health checks):**
-
-```typescript
-// Use @nestjs/terminus for comprehensive health checks
-import {
-  HealthCheckService,
-  HttpHealthIndicator,
-  TypeOrmHealthIndicator,
-  HealthCheck,
-  DiskHealthIndicator,
-  MemoryHealthIndicator,
-} from '@nestjs/terminus';
-
-@Controller('health')
-export class HealthController {
-  constructor(
-    private health: HealthCheckService,
-    private http: HttpHealthIndicator,
-    private db: TypeOrmHealthIndicator,
-    private disk: DiskHealthIndicator,
-    private memory: MemoryHealthIndicator,
-  ) {}
-
-  // Liveness probe - is the service alive?
-  @Get('live')
-  @HealthCheck()
-  liveness() {
-    return this.health.check([
-      // Basic checks only
-      () => this.memory.checkHeap('memory_heap', 200 * 1024 * 1024), // 200MB
-    ]);
-  }
-
-  // Readiness probe - can the service handle traffic?
-  @Get('ready')
-  @HealthCheck()
-  readiness() {
-    return this.health.check([
-      () => this.db.pingCheck('database'),
-      () =>
-        this.http.pingCheck('redis', 'http://redis:6379', { timeout: 1000 }),
-      () =>
-        this.disk.checkStorage('disk', { path: '/', thresholdPercent: 0.9 }),
-    ]);
-  }
-
-  // Deep health check for debugging
-  @Get('deep')
-  @HealthCheck()
-  deepCheck() {
-    return this.health.check([
-      () => this.db.pingCheck('database'),
-      () => this.memory.checkHeap('memory_heap', 200 * 1024 * 1024),
-      () => this.memory.checkRSS('memory_rss', 300 * 1024 * 1024),
-      () =>
-        this.disk.checkStorage('disk', { path: '/', thresholdPercent: 0.9 }),
-      () =>
-        this.http.pingCheck('external-api', 'https://api.example.com/health'),
-    ]);
-  }
-}
-
-// Custom indicator for business-specific health
-@Injectable()
-export class QueueHealthIndicator extends HealthIndicator {
-  constructor(private queueService: QueueService) {
-    super();
-  }
-
-  async isHealthy(key: string): Promise<HealthIndicatorResult> {
-    const queueStats = await this.queueService.getStats();
-
-    const isHealthy = queueStats.failedCount < 100;
-    const result = this.getStatus(key, isHealthy, {
-      waiting: queueStats.waitingCount,
-      active: queueStats.activeCount,
-      failed: queueStats.failedCount,
-    });
-
-    if (!isHealthy) {
-      throw new HealthCheckError('Queue unhealthy', result);
-    }
-
-    return result;
-  }
-}
-
-// Redis health indicator
-@Injectable()
-export class RedisHealthIndicator extends HealthIndicator {
-  constructor(@InjectRedis() private redis: Redis) {
-    super();
-  }
-
-  async isHealthy(key: string): Promise<HealthIndicatorResult> {
-    try {
-      const pong = await this.redis.ping();
-      return this.getStatus(key, pong === 'PONG');
-    } catch (error) {
-      throw new HealthCheckError('Redis check failed', this.getStatus(key, false));
-    }
-  }
-}
-
-// Use custom indicators
-@Get('ready')
-@HealthCheck()
-readiness() {
-  return this.health.check([
-    () => this.db.pingCheck('database'),
-    () => this.redis.isHealthy('redis'),
-    () => this.queue.isHealthy('job-queue'),
-  ]);
-}
-
-// Graceful shutdown handling
-@Injectable()
-export class GracefulShutdownService implements OnApplicationShutdown {
-  private isShuttingDown = false;
-
-  isShutdown(): boolean {
-    return this.isShuttingDown;
-  }
-
-  async onApplicationShutdown(signal: string): Promise<void> {
-    this.isShuttingDown = true;
-    console.log(`Shutting down on ${signal}`);
-
-    // Wait for in-flight requests
-    await new Promise((resolve) => setTimeout(resolve, 5000));
-  }
-}
-
-// Health check respects shutdown state
-@Get('ready')
-@HealthCheck()
-readiness() {
-  if (this.shutdownService.isShutdown()) {
-    throw new ServiceUnavailableException('Shutting down');
-  }
-
-  return this.health.check([
-    () => this.db.pingCheck('database'),
-  ]);
-}
-```
-
-### Kubernetes Configuration
-
-```yaml
-# Kubernetes deployment with probes
-apiVersion: apps/v1
-kind: Deployment
-metadata:
-  name: api-service
-spec:
-  template:
-    spec:
-      containers:
-        - name: api
-          image: api-service:latest
-          ports:
-            - containerPort: 3000
-          livenessProbe:
-            httpGet:
-              path: /health/live
-              port: 3000
-            initialDelaySeconds: 30
-            periodSeconds: 10
-            timeoutSeconds: 5
-            failureThreshold: 3
-          readinessProbe:
-            httpGet:
-              path: /health/ready
-              port: 3000
-            initialDelaySeconds: 5
-            periodSeconds: 5
-            timeoutSeconds: 3
-            failureThreshold: 3
-          startupProbe:
-            httpGet:
-              path: /health/live
-              port: 3000
-            initialDelaySeconds: 0
-            periodSeconds: 5
-            failureThreshold: 30
-```
-
-Reference: [NestJS Terminus](https://docs.nestjs.com/recipes/terminus)

.agents/skills/nestjs-best-practices/rules/micro-use-patterns.md

@@ -1,167 +0,0 @@
----
-title: Use Message and Event Patterns Correctly
-impact: MEDIUM
-impactDescription: Proper patterns ensure reliable microservice communication
-tags: microservices, message-pattern, event-pattern, communication
----
-
-## Use Message and Event Patterns Correctly
-
-NestJS microservices support two communication patterns: request-response (MessagePattern) and event-based (EventPattern). Use MessagePattern when you need a response, and EventPattern for fire-and-forget notifications. Understanding the difference prevents communication bugs.
-
-**Incorrect (using wrong pattern for use case):**
-
-```typescript
-// Use @MessagePattern for fire-and-forget
-@Controller()
-export class NotificationsController {
-  @MessagePattern('user.created')
-  async handleUserCreated(data: UserCreatedEvent) {
-    // This WAITS for response, blocking the sender
-    await this.emailService.sendWelcome(data.email);
-    // If email fails, sender gets an error (coupling!)
-  }
-}
-
-// Use @EventPattern expecting a response
-@Controller()
-export class OrdersController {
-  @EventPattern('inventory.check')
-  async checkInventory(data: CheckInventoryDto) {
-    const available = await this.inventory.check(data);
-    return available; // This return value is IGNORED with @EventPattern!
-  }
-}
-
-// Tight coupling in client
-@Injectable()
-export class UsersService {
-  async createUser(dto: CreateUserDto): Promise<User> {
-    const user = await this.repo.save(dto);
-
-    // Blocks until notification service responds
-    await this.client.send('user.created', user).toPromise();
-    // If notification service is down, user creation fails!
-
-    return user;
-  }
-}
-```
-
-**Correct (use MessagePattern for request-response, EventPattern for fire-and-forget):**
-
-```typescript
-// MessagePattern: Request-Response (when you NEED a response)
-@Controller()
-export class InventoryController {
-  @MessagePattern({ cmd: 'check_inventory' })
-  async checkInventory(data: CheckInventoryDto): Promise<InventoryResult> {
-    const result = await this.inventoryService.check(data.productId, data.quantity);
-    return result; // Response sent back to caller
-  }
-}
-
-// Client expects response
-@Injectable()
-export class OrdersService {
-  async createOrder(dto: CreateOrderDto): Promise<Order> {
-    // Check inventory - we NEED this response to proceed
-    const inventory = await firstValueFrom(
-      this.inventoryClient.send<InventoryResult>(
-        { cmd: 'check_inventory' },
-        { productId: dto.productId, quantity: dto.quantity },
-      ),
-    );
-
-    if (!inventory.available) {
-      throw new BadRequestException('Insufficient inventory');
-    }
-
-    return this.repo.save(dto);
-  }
-}
-
-// EventPattern: Fire-and-Forget (for notifications, side effects)
-@Controller()
-export class NotificationsController {
-  @EventPattern('user.created')
-  async handleUserCreated(data: UserCreatedEvent): Promise<void> {
-    // No return value needed - just process the event
-    await this.emailService.sendWelcome(data.email);
-    await this.analyticsService.track('user_signup', data);
-    // If this fails, it doesn't affect the sender
-  }
-}
-
-// Client emits event without waiting
-@Injectable()
-export class UsersService {
-  async createUser(dto: CreateUserDto): Promise<User> {
-    const user = await this.repo.save(dto);
-
-    // Fire and forget - doesn't block, doesn't wait
-    this.eventClient.emit('user.created', {
-      userId: user.id,
-      email: user.email,
-      timestamp: new Date(),
-    });
-
-    return user; // User creation succeeds regardless of event handling
-  }
-}
-
-// Hybrid pattern for critical events
-@Injectable()
-export class OrdersService {
-  async createOrder(dto: CreateOrderDto): Promise<Order> {
-    const order = await this.repo.save(dto);
-
-    // Critical: inventory reservation (use MessagePattern)
-    const reserved = await firstValueFrom(
-      this.inventoryClient.send({ cmd: 'reserve_inventory' }, {
-        orderId: order.id,
-        items: dto.items,
-      }),
-    );
-
-    if (!reserved.success) {
-      await this.repo.delete(order.id);
-      throw new BadRequestException('Could not reserve inventory');
-    }
-
-    // Non-critical: notifications (use EventPattern)
-    this.eventClient.emit('order.created', {
-      orderId: order.id,
-      userId: dto.userId,
-      total: dto.total,
-    });
-
-    return order;
-  }
-}
-
-// Error handling patterns
-// MessagePattern errors propagate to caller
-@MessagePattern({ cmd: 'get_user' })
-async getUser(userId: string): Promise<User> {
-  const user = await this.repo.findOne({ where: { id: userId } });
-  if (!user) {
-    throw new RpcException('User not found'); // Received by caller
-  }
-  return user;
-}
-
-// EventPattern errors should be handled locally
-@EventPattern('order.created')
-async handleOrderCreated(data: OrderCreatedEvent): Promise<void> {
-  try {
-    await this.processOrder(data);
-  } catch (error) {
-    // Log and potentially retry - don't throw
-    this.logger.error('Failed to process order event', error);
-    await this.deadLetterQueue.add(data);
-  }
-}
-```
-
-Reference: [NestJS Microservices](https://docs.nestjs.com/microservices/basics)

.agents/skills/nestjs-best-practices/rules/micro-use-queues.md

@@ -1,252 +0,0 @@
----
-title: Use Message Queues for Background Jobs
-impact: MEDIUM-HIGH
-impactDescription: Queues enable reliable background processing
-tags: microservices, queues, bullmq, background-jobs
----
-
-## Use Message Queues for Background Jobs
-
-Use `@nestjs/bullmq` for background job processing. Queues decouple long-running tasks from HTTP requests, enable retry logic, and distribute workload across workers. Use them for emails, file processing, notifications, and any task that shouldn't block user requests.
-
-**Incorrect (long-running tasks in HTTP handlers):**
-
-```typescript
-// Long-running tasks in HTTP handlers
-@Controller('reports')
-export class ReportsController {
-  @Post()
-  async generate(@Body() dto: GenerateReportDto): Promise<Report> {
-    // This blocks the request for potentially minutes
-    const data = await this.fetchLargeDataset(dto);
-    const report = await this.processData(data); // Slow!
-    await this.sendEmail(dto.email, report); // Can fail!
-    return report; // Client times out
-  }
-}
-
-// Fire-and-forget without retry
-@Injectable()
-export class EmailService {
-  async sendWelcome(email: string): Promise<void> {
-    // If this fails, email is never sent
-    await this.mailer.send({ to: email, template: 'welcome' });
-    // No retry, no tracking, no visibility
-  }
-}
-
-// Use setInterval for scheduled tasks
-setInterval(async () => {
-  await cleanupOldRecords();
-}, 60000); // No error handling, memory leaks
-```
-
-**Correct (use BullMQ for background processing):**
-
-```typescript
-// Configure BullMQ
-import { BullModule } from '@nestjs/bullmq';
-
-@Module({
-  imports: [
-    BullModule.forRoot({
-      connection: {
-        host: 'localhost',
-        port: 6379,
-      },
-      defaultJobOptions: {
-        removeOnComplete: 1000,
-        removeOnFail: 5000,
-        attempts: 3,
-        backoff: {
-          type: 'exponential',
-          delay: 1000,
-        },
-      },
-    }),
-    BullModule.registerQueue(
-      { name: 'email' },
-      { name: 'reports' },
-      { name: 'notifications' },
-    ),
-  ],
-})
-export class QueueModule {}
-
-// Producer: Add jobs to queue
-@Injectable()
-export class ReportsService {
-  constructor(
-    @InjectQueue('reports') private reportsQueue: Queue,
-  ) {}
-
-  async requestReport(dto: GenerateReportDto): Promise<{ jobId: string }> {
-    // Return immediately, process in background
-    const job = await this.reportsQueue.add('generate', dto, {
-      priority: dto.urgent ? 1 : 10,
-      delay: dto.scheduledFor ? Date.parse(dto.scheduledFor) - Date.now() : 0,
-    });
-
-    return { jobId: job.id };
-  }
-
-  async getJobStatus(jobId: string): Promise<JobStatus> {
-    const job = await this.reportsQueue.getJob(jobId);
-    return {
-      status: await job.getState(),
-      progress: job.progress,
-      result: job.returnvalue,
-    };
-  }
-}
-
-// Consumer: Process jobs
-@Processor('reports')
-export class ReportsProcessor {
-  private readonly logger = new Logger(ReportsProcessor.name);
-
-  @Process('generate')
-  async generateReport(job: Job<GenerateReportDto>): Promise<Report> {
-    this.logger.log(`Processing report job ${job.id}`);
-
-    // Update progress
-    await job.updateProgress(10);
-
-    const data = await this.fetchData(job.data);
-    await job.updateProgress(50);
-
-    const report = await this.processData(data);
-    await job.updateProgress(90);
-
-    await this.saveReport(report);
-    await job.updateProgress(100);
-
-    return report;
-  }
-
-  @OnQueueActive()
-  onActive(job: Job) {
-    this.logger.log(`Processing job ${job.id}`);
-  }
-
-  @OnQueueCompleted()
-  onCompleted(job: Job, result: any) {
-    this.logger.log(`Job ${job.id} completed`);
-  }
-
-  @OnQueueFailed()
-  onFailed(job: Job, error: Error) {
-    this.logger.error(`Job ${job.id} failed: ${error.message}`);
-  }
-}
-
-// Email queue with retry
-@Processor('email')
-export class EmailProcessor {
-  @Process('send')
-  async sendEmail(job: Job<SendEmailDto>): Promise<void> {
-    const { to, template, data } = job.data;
-
-    try {
-      await this.mailer.send({
-        to,
-        template,
-        context: data,
-      });
-    } catch (error) {
-      // BullMQ will retry based on job options
-      throw error;
-    }
-  }
-}
-
-// Usage
-@Injectable()
-export class NotificationService {
-  constructor(@InjectQueue('email') private emailQueue: Queue) {}
-
-  async sendWelcome(user: User): Promise<void> {
-    await this.emailQueue.add(
-      'send',
-      {
-        to: user.email,
-        template: 'welcome',
-        data: { name: user.name },
-      },
-      {
-        attempts: 5,
-        backoff: { type: 'exponential', delay: 5000 },
-      },
-    );
-  }
-}
-
-// Scheduled jobs
-@Injectable()
-export class ScheduledJobsService implements OnModuleInit {
-  constructor(@InjectQueue('maintenance') private queue: Queue) {}
-
-  async onModuleInit(): Promise<void> {
-    // Clean up old reports daily at midnight
-    await this.queue.add(
-      'cleanup',
-      {},
-      {
-        repeat: { cron: '0 0 * * *' },
-        jobId: 'daily-cleanup', // Prevent duplicates
-      },
-    );
-
-    // Send digest every hour
-    await this.queue.add(
-      'digest',
-      {},
-      {
-        repeat: { every: 60 * 60 * 1000 },
-        jobId: 'hourly-digest',
-      },
-    );
-  }
-}
-
-@Processor('maintenance')
-export class MaintenanceProcessor {
-  @Process('cleanup')
-  async cleanup(): Promise<void> {
-    await this.cleanupOldReports();
-    await this.cleanupExpiredSessions();
-  }
-
-  @Process('digest')
-  async sendDigest(): Promise<void> {
-    const users = await this.getUsersForDigest();
-    for (const user of users) {
-      await this.emailQueue.add('send', { to: user.email, template: 'digest' });
-    }
-  }
-}
-
-// Queue monitoring with Bull Board
-import { BullBoardModule } from '@bull-board/nestjs';
-import { BullMQAdapter } from '@bull-board/api/bullMQAdapter';
-
-@Module({
-  imports: [
-    BullBoardModule.forRoot({
-      route: '/admin/queues',
-      adapter: ExpressAdapter,
-    }),
-    BullBoardModule.forFeature({
-      name: 'email',
-      adapter: BullMQAdapter,
-    }),
-    BullBoardModule.forFeature({
-      name: 'reports',
-      adapter: BullMQAdapter,
-    }),
-  ],
-})
-export class AdminModule {}
-```
-
-Reference: [NestJS Queues](https://docs.nestjs.com/techniques/queues)

.agents/skills/nestjs-best-practices/rules/perf-async-hooks.md

@@ -1,109 +0,0 @@
----
-title: Use Async Lifecycle Hooks Correctly
-impact: HIGH
-impactDescription: Improper async handling blocks application startup
-tags: performance, lifecycle, async, hooks
----
-
-## Use Async Lifecycle Hooks Correctly
-
-NestJS lifecycle hooks (`onModuleInit`, `onApplicationBootstrap`, etc.) support async operations. However, misusing them can block application startup or cause race conditions. Understand the lifecycle order and use hooks appropriately.
-
-**Incorrect (fire-and-forget async without await):**
-
-```typescript
-// Fire-and-forget async without await
-@Injectable()
-export class DatabaseService implements OnModuleInit {
-  onModuleInit() {
-    // This runs but doesn't block - app starts before DB is ready!
-    this.connect();
-  }
-
-  private async connect() {
-    await this.pool.connect();
-    console.log('Database connected');
-  }
-}
-
-// Heavy blocking operations in constructor
-@Injectable()
-export class ConfigService {
-  private config: Config;
-
-  constructor() {
-    // BLOCKS entire module instantiation synchronously
-    this.config = fs.readFileSync('config.json');
-  }
-}
-```
-
-**Correct (return promises from async hooks):**
-
-```typescript
-// Return promise from async hooks
-@Injectable()
-export class DatabaseService implements OnModuleInit {
-  private pool: Pool;
-
-  async onModuleInit(): Promise<void> {
-    // NestJS waits for this to complete before continuing
-    await this.pool.connect();
-    console.log('Database connected');
-  }
-
-  async onModuleDestroy(): Promise<void> {
-    // Clean up resources on shutdown
-    await this.pool.end();
-    console.log('Database disconnected');
-  }
-}
-
-// Use onApplicationBootstrap for cross-module dependencies
-@Injectable()
-export class CacheWarmerService implements OnApplicationBootstrap {
-  constructor(
-    private cache: CacheService,
-    private products: ProductsService,
-  ) {}
-
-  async onApplicationBootstrap(): Promise<void> {
-    // All modules are initialized, safe to warm cache
-    const products = await this.products.findPopular();
-    await this.cache.warmup(products);
-  }
-}
-
-// Heavy init in async hooks, not constructor
-@Injectable()
-export class ConfigService implements OnModuleInit {
-  private config: Config;
-
-  constructor() {
-    // Keep constructor synchronous and fast
-  }
-
-  async onModuleInit(): Promise<void> {
-    // Async loading in lifecycle hook
-    this.config = await this.loadConfig();
-  }
-
-  private async loadConfig(): Promise<Config> {
-    const file = await fs.promises.readFile('config.json');
-    return JSON.parse(file.toString());
-  }
-
-  get<T>(key: string): T {
-    return this.config[key];
-  }
-}
-
-// Enable shutdown hooks in main.ts
-async function bootstrap() {
-  const app = await NestFactory.create(AppModule);
-  app.enableShutdownHooks(); // Enable SIGTERM/SIGINT handling
-  await app.listen(3000);
-}
-```
-
-Reference: [NestJS Lifecycle Events](https://docs.nestjs.com/fundamentals/lifecycle-events)

.agents/skills/nestjs-best-practices/rules/perf-lazy-loading.md

@@ -1,121 +0,0 @@
----
-title: Use Lazy Loading for Large Modules
-impact: MEDIUM
-impactDescription: Improves startup time for large applications
-tags: performance, lazy-loading, modules, optimization
----
-
-## Use Lazy Loading for Large Modules
-
-NestJS supports lazy-loading modules, which defers initialization until first use. This is valuable for large applications where some features are rarely used, serverless deployments where cold start time matters, or when certain modules have heavy initialization costs.
-
-**Incorrect (loading everything eagerly):**
-
-```typescript
-// Load everything eagerly in a large app
-@Module({
-  imports: [
-    UsersModule,
-    OrdersModule,
-    PaymentsModule,
-    ReportsModule, // Heavy, rarely used
-    AnalyticsModule, // Heavy, rarely used
-    AdminModule, // Only admins use this
-    LegacyModule, // Migration module, rarely used
-    BulkImportModule, // Used once a month
-  ],
-})
-export class AppModule {}
-
-// All modules initialize at startup, even if never used
-// Slow cold starts in serverless
-// Memory wasted on unused modules
-```
-
-**Correct (lazy load rarely-used modules):**
-
-```typescript
-// Use LazyModuleLoader for optional modules
-import { LazyModuleLoader } from '@nestjs/core';
-
-@Injectable()
-export class ReportsService {
-  constructor(private lazyModuleLoader: LazyModuleLoader) {}
-
-  async generateReport(type: string): Promise<Report> {
-    // Load module only when needed
-    const { ReportsModule } = await import('./reports/reports.module');
-    const moduleRef = await this.lazyModuleLoader.load(() => ReportsModule);
-
-    const reportsService = moduleRef.get(ReportsGeneratorService);
-    return reportsService.generate(type);
-  }
-}
-
-// Lazy load admin features with caching
-@Injectable()
-export class AdminService {
-  private adminModule: ModuleRef | null = null;
-
-  constructor(private lazyModuleLoader: LazyModuleLoader) {}
-
-  private async getAdminModule(): Promise<ModuleRef> {
-    if (!this.adminModule) {
-      const { AdminModule } = await import('./admin/admin.module');
-      this.adminModule = await this.lazyModuleLoader.load(() => AdminModule);
-    }
-    return this.adminModule;
-  }
-
-  async runAdminTask(task: string): Promise<void> {
-    const moduleRef = await this.getAdminModule();
-    const taskRunner = moduleRef.get(AdminTaskRunner);
-    await taskRunner.run(task);
-  }
-}
-
-// Reusable lazy loader service
-@Injectable()
-export class ModuleLoaderService {
-  private loadedModules = new Map<string, ModuleRef>();
-
-  constructor(private lazyModuleLoader: LazyModuleLoader) {}
-
-  async load<T>(
-    key: string,
-    importFn: () => Promise<{ default: Type<T> } | Type<T>>,
-  ): Promise<ModuleRef> {
-    if (!this.loadedModules.has(key)) {
-      const module = await importFn();
-      const moduleType = 'default' in module ? module.default : module;
-      const moduleRef = await this.lazyModuleLoader.load(() => moduleType);
-      this.loadedModules.set(key, moduleRef);
-    }
-    return this.loadedModules.get(key)!;
-  }
-}
-
-// Preload modules in background after startup
-@Injectable()
-export class ModulePreloader implements OnApplicationBootstrap {
-  constructor(private lazyModuleLoader: LazyModuleLoader) {}
-
-  async onApplicationBootstrap(): Promise<void> {
-    setTimeout(async () => {
-      await this.preloadModule(() => import('./reports/reports.module'));
-    }, 5000); // 5 seconds after startup
-  }
-
-  private async preloadModule(importFn: () => Promise<any>): Promise<void> {
-    try {
-      const module = await importFn();
-      const moduleType = module.default || Object.values(module)[0];
-      await this.lazyModuleLoader.load(() => moduleType);
-    } catch (error) {
-      console.warn('Failed to preload module', error);
-    }
-  }
-}
-```
-
-Reference: [NestJS Lazy Loading Modules](https://docs.nestjs.com/fundamentals/lazy-loading-modules)

.agents/skills/nestjs-best-practices/rules/perf-optimize-database.md

@@ -1,131 +0,0 @@
----
-title: Optimize Database Queries
-impact: HIGH
-impactDescription: Database queries are typically the largest source of latency
-tags: performance, database, queries, optimization
----
-
-## Optimize Database Queries
-
-Select only needed columns, use proper indexes, avoid over-fetching relations, and consider query performance when designing your data access. Most API slowness traces back to inefficient database queries.
-
-**Incorrect (over-fetching data and missing indexes):**
-
-```typescript
-// Select everything when you need few fields
-@Injectable()
-export class UsersService {
-  async findAllEmails(): Promise<string[]> {
-    const users = await this.repo.find();
-    // Fetches ALL columns for ALL users
-    return users.map((u) => u.email);
-  }
-
-  async getUserSummary(id: string): Promise<UserSummary> {
-    const user = await this.repo.findOne({
-      where: { id },
-      relations: ['posts', 'posts.comments', 'posts.comments.author', 'followers'],
-    });
-    // Over-fetches massive relation tree
-    return { name: user.name, postCount: user.posts.length };
-  }
-}
-
-// No indexes on frequently queried columns
-@Entity()
-export class Order {
-  @Column()
-  userId: string; // No index - full table scan on every lookup
-
-  @Column()
-  status: string; // No index - slow status filtering
-}
-```
-
-**Correct (select only needed data with proper indexes):**
-
-```typescript
-// Select only needed columns
-@Injectable()
-export class UsersService {
-  async findAllEmails(): Promise<string[]> {
-    const users = await this.repo.find({
-      select: ['email'], // Only fetch email column
-    });
-    return users.map((u) => u.email);
-  }
-
-  // Use QueryBuilder for complex selections
-  async getUserSummary(id: string): Promise<UserSummary> {
-    return this.repo
-      .createQueryBuilder('user')
-      .select('user.name', 'name')
-      .addSelect('COUNT(post.id)', 'postCount')
-      .leftJoin('user.posts', 'post')
-      .where('user.id = :id', { id })
-      .groupBy('user.id')
-      .getRawOne();
-  }
-
-  // Fetch relations only when needed
-  async getFullProfile(id: string): Promise<User> {
-    return this.repo.findOne({
-      where: { id },
-      relations: ['posts'], // Only immediate relation
-      select: {
-        id: true,
-        name: true,
-        email: true,
-        posts: {
-          id: true,
-          title: true,
-        },
-      },
-    });
-  }
-}
-
-// Add indexes on frequently queried columns
-@Entity()
-@Index(['userId'])
-@Index(['status'])
-@Index(['createdAt'])
-@Index(['userId', 'status']) // Composite index for common query pattern
-export class Order {
-  @PrimaryGeneratedColumn('uuid')
-  id: string;
-
-  @Column()
-  userId: string;
-
-  @Column()
-  status: string;
-
-  @CreateDateColumn()
-  createdAt: Date;
-}
-
-// Always paginate large datasets
-@Injectable()
-export class OrdersService {
-  async findAll(page = 1, limit = 20): Promise<PaginatedResult<Order>> {
-    const [items, total] = await this.repo.findAndCount({
-      skip: (page - 1) * limit,
-      take: limit,
-      order: { createdAt: 'DESC' },
-    });
-
-    return {
-      items,
-      meta: {
-        page,
-        limit,
-        total,
-        totalPages: Math.ceil(total / limit),
-      },
-    };
-  }
-}
-```
-
-Reference: [TypeORM Query Builder](https://typeorm.io/select-query-builder)

.agents/skills/nestjs-best-practices/rules/perf-use-caching.md

@@ -1,128 +0,0 @@
----
-title: Use Caching Strategically
-impact: HIGH
-impactDescription: Dramatically reduces database load and response times
-tags: performance, caching, redis, optimization
----
-
-## Use Caching Strategically
-
-Implement caching for expensive operations, frequently accessed data, and external API calls. Use NestJS CacheModule with appropriate TTLs and cache invalidation strategies. Don't cache everything - focus on high-impact areas.
-
-**Incorrect (no caching or caching everything):**
-
-```typescript
-// No caching for expensive, repeated queries
-@Injectable()
-export class ProductsService {
-  async getPopular(): Promise<Product[]> {
-    // Runs complex aggregation query EVERY request
-    return this.productsRepo
-      .createQueryBuilder('p')
-      .leftJoin('p.orders', 'o')
-      .select('p.*, COUNT(o.id) as orderCount')
-      .groupBy('p.id')
-      .orderBy('orderCount', 'DESC')
-      .limit(20)
-      .getMany();
-  }
-}
-
-// Cache everything without thought
-@Injectable()
-export class UsersService {
-  @CacheKey('users')
-  @CacheTTL(3600)
-  @UseInterceptors(CacheInterceptor)
-  async findAll(): Promise<User[]> {
-    // Caching user list for 1 hour is wrong if data changes frequently
-    return this.usersRepo.find();
-  }
-}
-```
-
-**Correct (strategic caching with proper invalidation):**
-
-```typescript
-// Setup caching module
-@Module({
-  imports: [
-    CacheModule.registerAsync({
-      imports: [ConfigModule],
-      inject: [ConfigService],
-      useFactory: (config: ConfigService) => ({
-        stores: [
-          new KeyvRedis(config.get('REDIS_URL')),
-        ],
-        ttl: 60 * 1000, // Default 60s
-      }),
-    }),
-  ],
-})
-export class AppModule {}
-
-// Manual caching for granular control
-@Injectable()
-export class ProductsService {
-  constructor(
-    @Inject(CACHE_MANAGER) private cache: Cache,
-    private productsRepo: ProductRepository,
-  ) {}
-
-  async getPopular(): Promise<Product[]> {
-    const cacheKey = 'products:popular';
-
-    // Try cache first
-    const cached = await this.cache.get<Product[]>(cacheKey);
-    if (cached) return cached;
-
-    // Cache miss - fetch and cache
-    const products = await this.fetchPopularProducts();
-    await this.cache.set(cacheKey, products, 5 * 60 * 1000); // 5 min TTL
-    return products;
-  }
-
-  // Invalidate cache on changes
-  async updateProduct(id: string, dto: UpdateProductDto): Promise<Product> {
-    const product = await this.productsRepo.save({ id, ...dto });
-    await this.cache.del('products:popular'); // Invalidate
-    return product;
-  }
-}
-
-// Decorator-based caching with auto-interceptor
-@Controller('categories')
-@UseInterceptors(CacheInterceptor)
-export class CategoriesController {
-  @Get()
-  @CacheTTL(30 * 60 * 1000) // 30 minutes - categories rarely change
-  findAll(): Promise<Category[]> {
-    return this.categoriesService.findAll();
-  }
-
-  @Get(':id')
-  @CacheTTL(60 * 1000) // 1 minute
-  @CacheKey('category')
-  findOne(@Param('id') id: string): Promise<Category> {
-    return this.categoriesService.findOne(id);
-  }
-}
-
-// Event-based cache invalidation
-@Injectable()
-export class CacheInvalidationService {
-  constructor(@Inject(CACHE_MANAGER) private cache: Cache) {}
-
-  @OnEvent('product.created')
-  @OnEvent('product.updated')
-  @OnEvent('product.deleted')
-  async invalidateProductCaches(event: ProductEvent) {
-    await Promise.all([
-      this.cache.del('products:popular'),
-      this.cache.del(`product:${event.productId}`),
-    ]);
-  }
-}
-```
-
-Reference: [NestJS Caching](https://docs.nestjs.com/techniques/caching)

.agents/skills/nestjs-best-practices/rules/security-auth-jwt.md

@@ -1,146 +0,0 @@
----
-title: Implement Secure JWT Authentication
-impact: CRITICAL
-impactDescription: Essential for secure APIs
-tags: security, jwt, authentication, tokens
----
-
-## Implement Secure JWT Authentication
-
-Use `@nestjs/jwt` with `@nestjs/passport` for authentication. Store secrets securely, use appropriate token lifetimes, implement refresh tokens, and validate tokens properly. Never expose sensitive data in JWT payloads.
-
-**Incorrect (insecure JWT implementation):**
-
-```typescript
-// Hardcode secrets
-@Module({
-  imports: [
-    JwtModule.register({
-      secret: 'my-secret-key', // Exposed in code
-      signOptions: { expiresIn: '7d' }, // Too long
-    }),
-  ],
-})
-export class AuthModule {}
-
-// Store sensitive data in JWT
-async login(user: User): Promise<{ accessToken: string }> {
-  const payload = {
-    sub: user.id,
-    email: user.email,
-    password: user.password, // NEVER include password!
-    ssn: user.ssn, // NEVER include sensitive data!
-    isAdmin: user.isAdmin, // Can be tampered if not verified
-  };
-  return { accessToken: this.jwtService.sign(payload) };
-}
-
-// Skip token validation
-@Injectable()
-export class JwtStrategy extends PassportStrategy(Strategy) {
-  constructor() {
-    super({
-      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
-      secretOrKey: 'my-secret',
-    });
-  }
-
-  async validate(payload: any): Promise<any> {
-    return payload; // No validation of user existence
-  }
-}
-```
-
-**Correct (secure JWT with refresh tokens):**
-
-```typescript
-// Secure JWT configuration
-@Module({
-  imports: [
-    JwtModule.registerAsync({
-      imports: [ConfigModule],
-      inject: [ConfigService],
-      useFactory: (config: ConfigService) => ({
-        secret: config.get<string>('JWT_SECRET'),
-        signOptions: {
-          expiresIn: '15m', // Short-lived access tokens
-          issuer: config.get<string>('JWT_ISSUER'),
-          audience: config.get<string>('JWT_AUDIENCE'),
-        },
-      }),
-    }),
-    PassportModule.register({ defaultStrategy: 'jwt' }),
-  ],
-})
-export class AuthModule {}
-
-// Minimal JWT payload
-@Injectable()
-export class AuthService {
-  async login(user: User): Promise<TokenResponse> {
-    // Only include necessary, non-sensitive data
-    const payload: JwtPayload = {
-      sub: user.id,
-      email: user.email,
-      roles: user.roles,
-      iat: Math.floor(Date.now() / 1000),
-    };
-
-    const accessToken = this.jwtService.sign(payload);
-    const refreshToken = await this.createRefreshToken(user.id);
-
-    return { accessToken, refreshToken, expiresIn: 900 };
-  }
-
-  private async createRefreshToken(userId: string): Promise<string> {
-    const token = randomBytes(32).toString('hex');
-    const hashedToken = await bcrypt.hash(token, 10);
-
-    await this.refreshTokenRepo.save({
-      userId,
-      token: hashedToken,
-      expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000), // 7 days
-    });
-
-    return token;
-  }
-}
-
-// Proper JWT strategy with validation
-@Injectable()
-export class JwtStrategy extends PassportStrategy(Strategy) {
-  constructor(
-    private config: ConfigService,
-    private usersService: UsersService,
-  ) {
-    super({
-      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
-      secretOrKey: config.get<string>('JWT_SECRET'),
-      ignoreExpiration: false,
-      issuer: config.get<string>('JWT_ISSUER'),
-      audience: config.get<string>('JWT_AUDIENCE'),
-    });
-  }
-
-  async validate(payload: JwtPayload): Promise<User> {
-    // Verify user still exists and is active
-    const user = await this.usersService.findById(payload.sub);
-
-    if (!user || !user.isActive) {
-      throw new UnauthorizedException('User not found or inactive');
-    }
-
-    // Verify token wasn't issued before password change
-    if (user.passwordChangedAt) {
-      const tokenIssuedAt = new Date(payload.iat * 1000);
-      if (tokenIssuedAt < user.passwordChangedAt) {
-        throw new UnauthorizedException('Token invalidated by password change');
-      }
-    }
-
-    return user;
-  }
-}
-```
-
-Reference: [NestJS Authentication](https://docs.nestjs.com/security/authentication)

.agents/skills/nestjs-best-practices/rules/security-rate-limiting.md

@@ -1,125 +0,0 @@
----
-title: Implement Rate Limiting
-impact: HIGH
-impactDescription: Protects against abuse and ensures fair resource usage
-tags: security, rate-limiting, throttler, protection
----
-
-## Implement Rate Limiting
-
-Use `@nestjs/throttler` to limit request rates per client. Apply different limits for different endpoints - stricter for auth endpoints, more relaxed for read operations. Consider using Redis for distributed rate limiting in clustered deployments.
-
-**Incorrect (no rate limiting on sensitive endpoints):**
-
-```typescript
-// No rate limiting on sensitive endpoints
-@Controller('auth')
-export class AuthController {
-  @Post('login')
-  async login(@Body() dto: LoginDto): Promise<TokenResponse> {
-    // Attackers can brute-force credentials
-    return this.authService.login(dto);
-  }
-
-  @Post('forgot-password')
-  async forgotPassword(@Body() dto: ForgotPasswordDto): Promise<void> {
-    // Can be abused to spam users with emails
-    return this.authService.sendResetEmail(dto.email);
-  }
-}
-
-// Same limits for all endpoints
-@UseGuards(ThrottlerGuard)
-@Controller('api')
-export class ApiController {
-  @Get('public-data')
-  async getPublic() {} // Should allow more requests
-
-  @Post('process-payment')
-  async payment() {} // Should be more restrictive
-}
-```
-
-**Correct (configured throttler with endpoint-specific limits):**
-
-```typescript
-// Configure throttler globally with multiple limits
-import { ThrottlerModule, ThrottlerGuard } from '@nestjs/throttler';
-
-@Module({
-  imports: [
-    ThrottlerModule.forRoot([
-      {
-        name: 'short',
-        ttl: 1000, // 1 second
-        limit: 3, // 3 requests per second
-      },
-      {
-        name: 'medium',
-        ttl: 10000, // 10 seconds
-        limit: 20, // 20 requests per 10 seconds
-      },
-      {
-        name: 'long',
-        ttl: 60000, // 1 minute
-        limit: 100, // 100 requests per minute
-      },
-    ]),
-  ],
-  providers: [
-    {
-      provide: APP_GUARD,
-      useClass: ThrottlerGuard,
-    },
-  ],
-})
-export class AppModule {}
-
-// Override limits per endpoint
-@Controller('auth')
-export class AuthController {
-  @Post('login')
-  @Throttle({ short: { limit: 5, ttl: 60000 } }) // 5 attempts per minute
-  async login(@Body() dto: LoginDto): Promise<TokenResponse> {
-    return this.authService.login(dto);
-  }
-
-  @Post('forgot-password')
-  @Throttle({ short: { limit: 3, ttl: 3600000 } }) // 3 per hour
-  async forgotPassword(@Body() dto: ForgotPasswordDto): Promise<void> {
-    return this.authService.sendResetEmail(dto.email);
-  }
-}
-
-// Skip throttling for certain routes
-@Controller('health')
-export class HealthController {
-  @Get()
-  @SkipThrottle()
-  check(): string {
-    return 'OK';
-  }
-}
-
-// Custom throttle per user type
-@Injectable()
-export class CustomThrottlerGuard extends ThrottlerGuard {
-  protected async getTracker(req: Request): Promise<string> {
-    // Use user ID if authenticated, IP otherwise
-    return req.user?.id || req.ip;
-  }
-
-  protected async getLimit(context: ExecutionContext): Promise<number> {
-    const request = context.switchToHttp().getRequest();
-
-    // Higher limits for authenticated users
-    if (request.user) {
-      return request.user.isPremium ? 1000 : 200;
-    }
-
-    return 50; // Anonymous users
-  }
-}
-```
-
-Reference: [NestJS Throttler](https://docs.nestjs.com/security/rate-limiting)

.agents/skills/nestjs-best-practices/rules/security-sanitize-output.md

@@ -1,139 +0,0 @@
----
-title: Sanitize Output to Prevent XSS
-impact: HIGH
-impactDescription: XSS vulnerabilities can compromise user sessions and data
-tags: security, xss, sanitization, html
----
-
-## Sanitize Output to Prevent XSS
-
-While NestJS APIs typically return JSON (which browsers don't execute), XSS risks exist when rendering HTML, storing user content, or when frontend frameworks improperly handle API responses. Sanitize user-generated content before storage and use proper Content-Type headers.
-
-**Incorrect (storing raw HTML without sanitization):**
-
-```typescript
-// Store raw HTML from users
-@Injectable()
-export class CommentsService {
-  async create(dto: CreateCommentDto): Promise<Comment> {
-    // User can inject: <script>steal(document.cookie)</script>
-    return this.repo.save({
-      content: dto.content, // Raw, unsanitized
-      authorId: dto.authorId,
-    });
-  }
-}
-
-// Return HTML without sanitization
-@Controller('pages')
-export class PagesController {
-  @Get(':slug')
-  @Header('Content-Type', 'text/html')
-  async getPage(@Param('slug') slug: string): Promise<string> {
-    const page = await this.pagesService.findBySlug(slug);
-    // If page.content contains user input, XSS is possible
-    return `<html><body>${page.content}</body></html>`;
-  }
-}
-
-// Reflect user input in errors
-@Get(':id')
-async findOne(@Param('id') id: string): Promise<User> {
-  const user = await this.repo.findOne({ where: { id } });
-  if (!user) {
-    // XSS if id contains malicious content and error is rendered
-    throw new NotFoundException(`User ${id} not found`);
-  }
-  return user;
-}
-```
-
-**Correct (sanitize content and use proper headers):**
-
-```typescript
-// Sanitize HTML content before storage
-import * as sanitizeHtml from 'sanitize-html';
-
-@Injectable()
-export class CommentsService {
-  private readonly sanitizeOptions: sanitizeHtml.IOptions = {
-    allowedTags: ['b', 'i', 'em', 'strong', 'a', 'p', 'br'],
-    allowedAttributes: {
-      a: ['href', 'title'],
-    },
-    allowedSchemes: ['http', 'https', 'mailto'],
-  };
-
-  async create(dto: CreateCommentDto): Promise<Comment> {
-    return this.repo.save({
-      content: sanitizeHtml(dto.content, this.sanitizeOptions),
-      authorId: dto.authorId,
-    });
-  }
-}
-
-// Use validation pipe to strip HTML
-import { Transform } from 'class-transformer';
-
-export class CreatePostDto {
-  @IsString()
-  @MaxLength(1000)
-  @Transform(({ value }) => sanitizeHtml(value, { allowedTags: [] }))
-  title: string;
-
-  @IsString()
-  @Transform(({ value }) =>
-    sanitizeHtml(value, {
-      allowedTags: ['p', 'br', 'b', 'i', 'a'],
-      allowedAttributes: { a: ['href'] },
-    }),
-  )
-  content: string;
-}
-
-// Set proper Content-Type headers
-@Controller('api')
-export class ApiController {
-  @Get('data')
-  @Header('Content-Type', 'application/json')
-  async getData(): Promise<DataResponse> {
-    // JSON response - browser won't execute scripts
-    return this.service.getData();
-  }
-}
-
-// Sanitize error messages
-@Get(':id')
-async findOne(@Param('id', ParseUUIDPipe) id: string): Promise<User> {
-  const user = await this.repo.findOne({ where: { id } });
-  if (!user) {
-    // UUID validation ensures safe format
-    throw new NotFoundException('User not found');
-  }
-  return user;
-}
-
-// Use Helmet for CSP headers
-import helmet from 'helmet';
-
-async function bootstrap() {
-  const app = await NestFactory.create(AppModule);
-
-  app.use(
-    helmet({
-      contentSecurityPolicy: {
-        directives: {
-          defaultSrc: ["'self'"],
-          scriptSrc: ["'self'"],
-          styleSrc: ["'self'", "'unsafe-inline'"],
-          imgSrc: ["'self'", 'data:', 'https:'],
-        },
-      },
-    }),
-  );
-
-  await app.listen(3000);
-}
-```
-
-Reference: [OWASP XSS Prevention](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html)

.agents/skills/nestjs-best-practices/rules/security-use-guards.md

@@ -1,135 +0,0 @@
----
-title: Use Guards for Authentication and Authorization
-impact: HIGH
-impactDescription: Enforces access control before handlers execute
-tags: security, guards, authentication, authorization
----
-
-## Use Guards for Authentication and Authorization
-
-Guards determine whether a request should be handled based on authentication state, roles, permissions, or other conditions. They run after middleware but before pipes and interceptors, making them ideal for access control. Use guards instead of manual checks in controllers.
-
-**Incorrect (manual auth checks in every handler):**
-
-```typescript
-// Manual auth checks in every handler
-@Controller('admin')
-export class AdminController {
-  @Get('users')
-  async getUsers(@Request() req) {
-    if (!req.user) {
-      throw new UnauthorizedException();
-    }
-    if (!req.user.roles.includes('admin')) {
-      throw new ForbiddenException();
-    }
-    return this.adminService.getUsers();
-  }
-
-  @Delete('users/:id')
-  async deleteUser(@Request() req, @Param('id') id: string) {
-    if (!req.user) {
-      throw new UnauthorizedException();
-    }
-    if (!req.user.roles.includes('admin')) {
-      throw new ForbiddenException();
-    }
-    return this.adminService.deleteUser(id);
-  }
-}
-```
-
-**Correct (guards with declarative decorators):**
-
-```typescript
-// JWT Auth Guard
-@Injectable()
-export class JwtAuthGuard implements CanActivate {
-  constructor(
-    private jwtService: JwtService,
-    private reflector: Reflector,
-  ) {}
-
-  async canActivate(context: ExecutionContext): Promise<boolean> {
-    // Check for @Public() decorator
-    const isPublic = this.reflector.getAllAndOverride<boolean>('isPublic', [
-      context.getHandler(),
-      context.getClass(),
-    ]);
-    if (isPublic) return true;
-
-    const request = context.switchToHttp().getRequest();
-    const token = this.extractToken(request);
-
-    if (!token) {
-      throw new UnauthorizedException('No token provided');
-    }
-
-    try {
-      request.user = await this.jwtService.verifyAsync(token);
-      return true;
-    } catch {
-      throw new UnauthorizedException('Invalid token');
-    }
-  }
-
-  private extractToken(request: Request): string | undefined {
-    const [type, token] = request.headers.authorization?.split(' ') ?? [];
-    return type === 'Bearer' ? token : undefined;
-  }
-}
-
-// Roles Guard
-@Injectable()
-export class RolesGuard implements CanActivate {
-  constructor(private reflector: Reflector) {}
-
-  canActivate(context: ExecutionContext): boolean {
-    const requiredRoles = this.reflector.getAllAndOverride<Role[]>('roles', [
-      context.getHandler(),
-      context.getClass(),
-    ]);
-
-    if (!requiredRoles) return true;
-
-    const { user } = context.switchToHttp().getRequest();
-    return requiredRoles.some((role) => user.roles?.includes(role));
-  }
-}
-
-// Decorators
-export const Public = () => SetMetadata('isPublic', true);
-export const Roles = (...roles: Role[]) => SetMetadata('roles', roles);
-
-// Register guards globally
-@Module({
-  providers: [
-    { provide: APP_GUARD, useClass: JwtAuthGuard },
-    { provide: APP_GUARD, useClass: RolesGuard },
-  ],
-})
-export class AppModule {}
-
-// Clean controller
-@Controller('admin')
-@Roles(Role.Admin) // Applied to all routes
-export class AdminController {
-  @Get('users')
-  getUsers(): Promise<User[]> {
-    return this.adminService.getUsers();
-  }
-
-  @Delete('users/:id')
-  deleteUser(@Param('id') id: string): Promise<void> {
-    return this.adminService.deleteUser(id);
-  }
-
-  @Public() // Override: no auth required
-  @Get('health')
-  health() {
-    return { status: 'ok' };
-  }
-}
-```
-
-Reference: [NestJS Guards](https://docs.nestjs.com/guards)

.agents/skills/nestjs-best-practices/rules/security-validate-all-input.md

@@ -1,150 +0,0 @@
----
-title: Validate All Input with DTOs and Pipes
-impact: HIGH
-impactDescription: First line of defense against attacks
-tags: security, validation, dto, pipes
----
-
-## Validate All Input with DTOs and Pipes
-
-Always validate incoming data using class-validator decorators on DTOs and the global ValidationPipe. Never trust user input. Validate all request bodies, query parameters, and route parameters before processing.
-
-**Incorrect (trust raw input without validation):**
-
-```typescript
-// Trust raw input without validation
-@Controller('users')
-export class UsersController {
-  @Post()
-  create(@Body() body: any) {
-    // body could contain anything - SQL injection, XSS, etc.
-    return this.usersService.create(body);
-  }
-
-  @Get()
-  findAll(@Query() query: any) {
-    // query.limit could be "'; DROP TABLE users; --"
-    return this.usersService.findAll(query.limit);
-  }
-}
-
-// DTOs without validation decorators
-export class CreateUserDto {
-  name: string;    // No validation
-  email: string;   // Could be "not-an-email"
-  age: number;     // Could be "abc" or -999
-}
-```
-
-**Correct (validated DTOs with global ValidationPipe):**
-
-```typescript
-// Enable ValidationPipe globally in main.ts
-async function bootstrap() {
-  const app = await NestFactory.create(AppModule);
-
-  app.useGlobalPipes(
-    new ValidationPipe({
-      whitelist: true,              // Strip unknown properties
-      forbidNonWhitelisted: true,   // Throw on unknown properties
-      transform: true,              // Auto-transform to DTO types
-      transformOptions: {
-        enableImplicitConversion: true,
-      },
-    }),
-  );
-
-  await app.listen(3000);
-}
-
-// Create well-validated DTOs
-import {
-  IsString,
-  IsEmail,
-  IsInt,
-  Min,
-  Max,
-  IsOptional,
-  MinLength,
-  MaxLength,
-  Matches,
-  IsNotEmpty,
-} from 'class-validator';
-import { Transform, Type } from 'class-transformer';
-
-export class CreateUserDto {
-  @IsString()
-  @IsNotEmpty()
-  @MinLength(2)
-  @MaxLength(100)
-  @Transform(({ value }) => value?.trim())
-  name: string;
-
-  @IsEmail()
-  @Transform(({ value }) => value?.toLowerCase().trim())
-  email: string;
-
-  @IsInt()
-  @Min(0)
-  @Max(150)
-  age: number;
-
-  @IsString()
-  @MinLength(8)
-  @MaxLength(100)
-  @Matches(/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)/, {
-    message: 'Password must contain uppercase, lowercase, and number',
-  })
-  password: string;
-}
-
-// Query DTO with defaults and transformation
-export class FindUsersQueryDto {
-  @IsOptional()
-  @IsString()
-  @MaxLength(100)
-  search?: string;
-
-  @IsOptional()
-  @Type(() => Number)
-  @IsInt()
-  @Min(1)
-  @Max(100)
-  limit: number = 20;
-
-  @IsOptional()
-  @Type(() => Number)
-  @IsInt()
-  @Min(0)
-  offset: number = 0;
-}
-
-// Param validation
-export class UserIdParamDto {
-  @IsUUID('4')
-  id: string;
-}
-
-@Controller('users')
-export class UsersController {
-  @Post()
-  create(@Body() dto: CreateUserDto): Promise<User> {
-    // dto is guaranteed to be valid
-    return this.usersService.create(dto);
-  }
-
-  @Get()
-  findAll(@Query() query: FindUsersQueryDto): Promise<User[]> {
-    // query.limit is a number, query.search is sanitized
-    return this.usersService.findAll(query);
-  }
-
-  @Get(':id')
-  findOne(@Param() params: UserIdParamDto): Promise<User> {
-    // params.id is a valid UUID
-    return this.usersService.findById(params.id);
-  }
-}
-```
-
-Reference: [NestJS Validation](https://docs.nestjs.com/techniques/validation)

.agents/skills/nestjs-best-practices/rules/test-e2e-supertest.md

@@ -1,178 +0,0 @@
----
-title: Use Supertest for E2E Testing
-impact: HIGH
-impactDescription: Validates the full request/response cycle
-tags: testing, e2e, supertest, integration
----
-
-## Use Supertest for E2E Testing
-
-End-to-end tests use Supertest to make real HTTP requests against your NestJS application. They test the full stack including middleware, guards, pipes, and interceptors. E2E tests catch integration issues that unit tests miss.
-
-**Incorrect (no proper E2E setup or teardown):**
-
-```typescript
-// Only unit test controllers
-describe('UsersController', () => {
-  it('should return users', async () => {
-    const service = { findAll: jest.fn().mockResolvedValue([]) };
-    const controller = new UsersController(service as any);
-
-    const result = await controller.findAll();
-
-    expect(result).toEqual([]);
-    // Doesn't test: routes, guards, pipes, serialization
-  });
-});
-
-// E2E tests without proper setup/teardown
-describe('Users API', () => {
-  it('should create user', async () => {
-    const app = await NestFactory.create(AppModule);
-    // No proper initialization
-    // No cleanup after test
-    // Hits real database
-  });
-});
-```
-
-**Correct (proper E2E setup with Supertest):**
-
-```typescript
-// Proper E2E test setup
-import { Test, TestingModule } from '@nestjs/testing';
-import { INestApplication, ValidationPipe } from '@nestjs/common';
-import * as request from 'supertest';
-import { AppModule } from '../src/app.module';
-
-describe('UsersController (e2e)', () => {
-  let app: INestApplication;
-
-  beforeAll(async () => {
-    const moduleFixture: TestingModule = await Test.createTestingModule({
-      imports: [AppModule],
-    }).compile();
-
-    app = moduleFixture.createNestApplication();
-
-    // Apply same config as production
-    app.useGlobalPipes(
-      new ValidationPipe({
-        whitelist: true,
-        transform: true,
-        forbidNonWhitelisted: true,
-      }),
-    );
-
-    await app.init();
-  });
-
-  afterAll(async () => {
-    await app.close();
-  });
-
-  describe('/users (POST)', () => {
-    it('should create a user', () => {
-      return request(app.getHttpServer())
-        .post('/users')
-        .send({ name: 'John', email: 'john@test.com' })
-        .expect(201)
-        .expect((res) => {
-          expect(res.body).toHaveProperty('id');
-          expect(res.body.name).toBe('John');
-          expect(res.body.email).toBe('john@test.com');
-        });
-    });
-
-    it('should return 400 for invalid email', () => {
-      return request(app.getHttpServer())
-        .post('/users')
-        .send({ name: 'John', email: 'invalid-email' })
-        .expect(400)
-        .expect((res) => {
-          expect(res.body.message).toContain('email');
-        });
-    });
-  });
-
-  describe('/users/:id (GET)', () => {
-    it('should return 404 for non-existent user', () => {
-      return request(app.getHttpServer())
-        .get('/users/non-existent-id')
-        .expect(404);
-    });
-  });
-});
-
-// Testing with authentication
-describe('Protected Routes (e2e)', () => {
-  let app: INestApplication;
-  let authToken: string;
-
-  beforeAll(async () => {
-    const moduleFixture = await Test.createTestingModule({
-      imports: [AppModule],
-    }).compile();
-
-    app = moduleFixture.createNestApplication();
-    app.useGlobalPipes(new ValidationPipe({ whitelist: true }));
-    await app.init();
-
-    // Get auth token
-    const loginResponse = await request(app.getHttpServer())
-      .post('/auth/login')
-      .send({ email: 'test@test.com', password: 'password' });
-
-    authToken = loginResponse.body.accessToken;
-  });
-
-  it('should return 401 without token', () => {
-    return request(app.getHttpServer())
-      .get('/users/me')
-      .expect(401);
-  });
-
-  it('should return user profile with valid token', () => {
-    return request(app.getHttpServer())
-      .get('/users/me')
-      .set('Authorization', `Bearer ${authToken}`)
-      .expect(200)
-      .expect((res) => {
-        expect(res.body.email).toBe('test@test.com');
-      });
-  });
-});
-
-// Database isolation for E2E tests
-describe('Orders API (e2e)', () => {
-  let app: INestApplication;
-  let dataSource: DataSource;
-
-  beforeAll(async () => {
-    const moduleFixture = await Test.createTestingModule({
-      imports: [
-        ConfigModule.forRoot({
-          envFilePath: '.env.test', // Test database config
-        }),
-        AppModule,
-      ],
-    }).compile();
-
-    app = moduleFixture.createNestApplication();
-    dataSource = moduleFixture.get(DataSource);
-    await app.init();
-  });
-
-  beforeEach(async () => {
-    // Clean database between tests
-    await dataSource.synchronize(true);
-  });
-
-  afterAll(async () => {
-    await dataSource.destroy();
-    await app.close();
-  });
-});
-```
-
-Reference: [NestJS E2E Testing](https://docs.nestjs.com/fundamentals/testing#end-to-end-testing)

.agents/skills/nestjs-best-practices/rules/test-mock-external-services.md

@@ -1,179 +0,0 @@
----
-title: Mock External Services in Tests
-impact: HIGH
-impactDescription: Ensures fast, reliable, deterministic tests
-tags: testing, mocking, external-services, jest
----
-
-## Mock External Services in Tests
-
-Never call real external services (APIs, databases, message queues) in unit tests. Mock them to ensure tests are fast, deterministic, and don't incur costs. Use realistic mock data and test edge cases like timeouts and errors.
-
-**Incorrect (calling real APIs and databases):**
-
-```typescript
-// Call real APIs in tests
-describe('PaymentService', () => {
-  it('should process payment', async () => {
-    const service = new PaymentService(new StripeClient(realApiKey));
-    // Hits real Stripe API!
-    const result = await service.charge('tok_visa', 1000);
-    // Slow, costs money, flaky
-  });
-});
-
-// Use real database
-describe('UsersService', () => {
-  beforeEach(async () => {
-    await connection.query('DELETE FROM users'); // Modifies real DB
-  });
-
-  it('should create user', async () => {
-    const user = await service.create({ email: 'test@test.com' });
-    // Side effects on shared database
-  });
-});
-
-// Incomplete mocks
-const mockHttpService = {
-  get: jest.fn().mockResolvedValue({ data: {} }),
-  // Missing error scenarios, missing other methods
-};
-```
-
-**Correct (mock all external dependencies):**
-
-```typescript
-// Mock HTTP service properly
-describe('WeatherService', () => {
-  let service: WeatherService;
-  let httpService: jest.Mocked<HttpService>;
-
-  beforeEach(async () => {
-    const module = await Test.createTestingModule({
-      providers: [
-        WeatherService,
-        {
-          provide: HttpService,
-          useValue: {
-            get: jest.fn(),
-            post: jest.fn(),
-          },
-        },
-      ],
-    }).compile();
-
-    service = module.get(WeatherService);
-    httpService = module.get(HttpService);
-  });
-
-  it('should return weather data', async () => {
-    const mockResponse = {
-      data: { temperature: 72, humidity: 45 },
-      status: 200,
-      statusText: 'OK',
-      headers: {},
-      config: {},
-    };
-
-    httpService.get.mockReturnValue(of(mockResponse));
-
-    const result = await service.getWeather('NYC');
-
-    expect(result).toEqual({ temperature: 72, humidity: 45 });
-  });
-
-  it('should handle API timeout', async () => {
-    httpService.get.mockReturnValue(
-      throwError(() => new Error('ETIMEDOUT')),
-    );
-
-    await expect(service.getWeather('NYC')).rejects.toThrow('Weather service unavailable');
-  });
-
-  it('should handle rate limiting', async () => {
-    httpService.get.mockReturnValue(
-      throwError(() => ({
-        response: { status: 429, data: { message: 'Rate limited' } },
-      })),
-    );
-
-    await expect(service.getWeather('NYC')).rejects.toThrow(TooManyRequestsException);
-  });
-});
-
-// Mock repository instead of database
-describe('UsersService', () => {
-  let service: UsersService;
-  let repo: jest.Mocked<Repository<User>>;
-
-  beforeEach(async () => {
-    const mockRepo = {
-      find: jest.fn(),
-      findOne: jest.fn(),
-      save: jest.fn(),
-      delete: jest.fn(),
-      createQueryBuilder: jest.fn(),
-    };
-
-    const module = await Test.createTestingModule({
-      providers: [
-        UsersService,
-        { provide: getRepositoryToken(User), useValue: mockRepo },
-      ],
-    }).compile();
-
-    service = module.get(UsersService);
-    repo = module.get(getRepositoryToken(User));
-  });
-
-  it('should find user by id', async () => {
-    const mockUser = { id: '1', name: 'John', email: 'john@test.com' };
-    repo.findOne.mockResolvedValue(mockUser);
-
-    const result = await service.findById('1');
-
-    expect(result).toEqual(mockUser);
-    expect(repo.findOne).toHaveBeenCalledWith({ where: { id: '1' } });
-  });
-});
-
-// Create mock factory for complex SDKs
-function createMockStripe(): jest.Mocked<Stripe> {
-  return {
-    paymentIntents: {
-      create: jest.fn(),
-      retrieve: jest.fn(),
-      confirm: jest.fn(),
-      cancel: jest.fn(),
-    },
-    customers: {
-      create: jest.fn(),
-      retrieve: jest.fn(),
-    },
-  } as any;
-}
-
-// Mock time for time-dependent tests
-describe('TokenService', () => {
-  beforeEach(() => {
-    jest.useFakeTimers();
-    jest.setSystemTime(new Date('2024-01-15'));
-  });
-
-  afterEach(() => {
-    jest.useRealTimers();
-  });
-
-  it('should expire token after 1 hour', async () => {
-    const token = await service.createToken();
-
-    // Fast-forward time
-    jest.advanceTimersByTime(61 * 60 * 1000);
-
-    expect(await service.isValid(token)).toBe(false);
-  });
-});
-```
-
-Reference: [Jest Mocking](https://jestjs.io/docs/mock-functions)

.agents/skills/nestjs-best-practices/rules/test-use-testing-module.md

@@ -1,153 +0,0 @@
----
-title: Use Testing Module for Unit Tests
-impact: HIGH
-impactDescription: Enables proper isolated testing with mocked dependencies
-tags: testing, unit-tests, mocking, jest
----
-
-## Use Testing Module for Unit Tests
-
-Use `@nestjs/testing` module to create isolated test environments with mocked dependencies. This ensures your tests run fast, don't depend on external services, and properly test your business logic in isolation.
-
-**Incorrect (manual instantiation bypassing DI):**
-
-```typescript
-// Instantiate services manually without DI
-describe('UsersService', () => {
-  it('should create user', async () => {
-    // Manual instantiation bypasses DI
-    const repo = new UserRepository(); // Real repo!
-    const service = new UsersService(repo);
-
-    const user = await service.create({ name: 'Test' });
-    // This hits the real database!
-  });
-});
-
-// Test implementation details
-describe('UsersController', () => {
-  it('should call service', async () => {
-    const service = { create: jest.fn() };
-    const controller = new UsersController(service as any);
-
-    await controller.create({ name: 'Test' });
-
-    expect(service.create).toHaveBeenCalled(); // Tests implementation, not behavior
-  });
-});
-```
-
-**Correct (use Test.createTestingModule with mocked dependencies):**
-
-```typescript
-// Use Test.createTestingModule for proper DI
-import { Test, TestingModule } from '@nestjs/testing';
-
-describe('UsersService', () => {
-  let service: UsersService;
-  let repo: jest.Mocked<UserRepository>;
-
-  beforeEach(async () => {
-    const module: TestingModule = await Test.createTestingModule({
-      providers: [
-        UsersService,
-        {
-          provide: UserRepository,
-          useValue: {
-            save: jest.fn(),
-            findOne: jest.fn(),
-            find: jest.fn(),
-          },
-        },
-      ],
-    }).compile();
-
-    service = module.get<UsersService>(UsersService);
-    repo = module.get(UserRepository);
-  });
-
-  afterEach(() => {
-    jest.clearAllMocks();
-  });
-
-  describe('create', () => {
-    it('should save and return user', async () => {
-      const dto = { name: 'John', email: 'john@test.com' };
-      const expectedUser = { id: '1', ...dto };
-
-      repo.save.mockResolvedValue(expectedUser);
-
-      const result = await service.create(dto);
-
-      expect(result).toEqual(expectedUser);
-      expect(repo.save).toHaveBeenCalledWith(dto);
-    });
-
-    it('should throw on duplicate email', async () => {
-      repo.findOne.mockResolvedValue({ id: '1', email: 'test@test.com' });
-
-      await expect(
-        service.create({ name: 'Test', email: 'test@test.com' }),
-      ).rejects.toThrow(ConflictException);
-    });
-  });
-
-  describe('findById', () => {
-    it('should return user when found', async () => {
-      const user = { id: '1', name: 'John' };
-      repo.findOne.mockResolvedValue(user);
-
-      const result = await service.findById('1');
-
-      expect(result).toEqual(user);
-    });
-
-    it('should throw NotFoundException when not found', async () => {
-      repo.findOne.mockResolvedValue(null);
-
-      await expect(service.findById('999')).rejects.toThrow(NotFoundException);
-    });
-  });
-});
-
-// Testing guards and interceptors
-describe('RolesGuard', () => {
-  let guard: RolesGuard;
-  let reflector: Reflector;
-
-  beforeEach(async () => {
-    const module = await Test.createTestingModule({
-      providers: [RolesGuard, Reflector],
-    }).compile();
-
-    guard = module.get<RolesGuard>(RolesGuard);
-    reflector = module.get<Reflector>(Reflector);
-  });
-
-  it('should allow when no roles required', () => {
-    const context = createMockExecutionContext({ user: { roles: [] } });
-    jest.spyOn(reflector, 'getAllAndOverride').mockReturnValue(undefined);
-
-    expect(guard.canActivate(context)).toBe(true);
-  });
-
-  it('should allow admin for admin-only route', () => {
-    const context = createMockExecutionContext({ user: { roles: ['admin'] } });
-    jest.spyOn(reflector, 'getAllAndOverride').mockReturnValue(['admin']);
-
-    expect(guard.canActivate(context)).toBe(true);
-  });
-});
-
-function createMockExecutionContext(request: Partial<Request>): ExecutionContext {
-  return {
-    switchToHttp: () => ({
-      getRequest: () => request,
-    }),
-    getHandler: () => jest.fn(),
-    getClass: () => jest.fn(),
-  } as ExecutionContext;
-}
-```
-
-Reference: [NestJS Testing](https://docs.nestjs.com/fundamentals/testing)

.agents/skills/nestjs-best-practices/scripts/build-agents.ts

@@ -1,299 +0,0 @@
-#!/usr/bin/env npx ts-node
-
-/**
- * Build script for generating AGENTS.md from individual rule files
- *
- * Usage: npx ts-node scripts/build-agents.ts
- *
- * This script:
- * 1. Reads all rule files from the rules/ directory
- * 2. Parses YAML frontmatter for metadata
- * 3. Groups rules by category based on filename prefix
- * 4. Generates a consolidated AGENTS.md file
- */
-
-import * as fs from 'fs';
-import * as path from 'path';
-import { fileURLToPath } from 'url';
-import { dirname } from 'path';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-// Category definitions with ordering and metadata
-const CATEGORIES = [
-  { prefix: 'arch-', name: 'Architecture', impact: 'CRITICAL', section: 1 },
-  { prefix: 'di-', name: 'Dependency Injection', impact: 'CRITICAL', section: 2 },
-  { prefix: 'error-', name: 'Error Handling', impact: 'HIGH', section: 3 },
-  { prefix: 'security-', name: 'Security', impact: 'HIGH', section: 4 },
-  { prefix: 'perf-', name: 'Performance', impact: 'HIGH', section: 5 },
-  { prefix: 'test-', name: 'Testing', impact: 'MEDIUM-HIGH', section: 6 },
-  { prefix: 'db-', name: 'Database & ORM', impact: 'MEDIUM-HIGH', section: 7 },
-  { prefix: 'api-', name: 'API Design', impact: 'MEDIUM', section: 8 },
-  { prefix: 'micro-', name: 'Microservices', impact: 'MEDIUM', section: 9 },
-  { prefix: 'devops-', name: 'DevOps & Deployment', impact: 'LOW-MEDIUM', section: 10 },
-];
-
-interface RuleFrontmatter {
-  title: string;
-  impact: string;
-  impactDescription: string;
-  tags: string[];
-}
-
-interface Rule {
-  filename: string;
-  frontmatter: RuleFrontmatter;
-  content: string;
-  category: string;
-  categorySection: number;
-}
-
-function parseFrontmatter(content: string): { frontmatter: RuleFrontmatter | null; body: string } {
-  const frontmatterRegex = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/;
-  const match = content.match(frontmatterRegex);
-
-  if (!match) {
-    return { frontmatter: null, body: content };
-  }
-
-  const frontmatterStr = match[1];
-  const body = match[2];
-
-  // Simple YAML parsing for our expected format
-  const frontmatter: Partial<RuleFrontmatter> = {};
-  const lines = frontmatterStr.split('\n');
-  let currentKey = '';
-  let inArray = false;
-  const arrayItems: string[] = [];
-
-  for (const line of lines) {
-    if (line.match(/^[a-zA-Z]+:/)) {
-      // Save previous array if we were collecting one
-      if (inArray && currentKey === 'tags') {
-        frontmatter.tags = arrayItems;
-      }
-      inArray = false;
-      arrayItems.length = 0;
-
-      const [key, ...valueParts] = line.split(':');
-      const value = valueParts.join(':').trim();
-      currentKey = key.trim();
-
-      if (value === '') {
-        // Might be start of array
-        inArray = true;
-      } else {
-        (frontmatter as any)[currentKey] = value;
-      }
-    } else if (inArray && line.trim().startsWith('-')) {
-      arrayItems.push(line.trim().replace(/^-\s*/, ''));
-    }
-  }
-
-  // Save final array if needed
-  if (inArray && currentKey === 'tags') {
-    frontmatter.tags = arrayItems;
-  }
-
-  return {
-    frontmatter: frontmatter as RuleFrontmatter,
-    body: body.trim()
-  };
-}
-
-function getCategoryForFile(filename: string): { name: string; section: number } | null {
-  for (const cat of CATEGORIES) {
-    if (filename.startsWith(cat.prefix)) {
-      return { name: cat.name, section: cat.section };
-    }
-  }
-  return null;
-}
-
-function readMetadata(): any {
-  const metadataPath = path.join(__dirname, '..', 'metadata.json');
-  return JSON.parse(fs.readFileSync(metadataPath, 'utf-8'));
-}
-
-function readRules(): Rule[] {
-  const rulesDir = path.join(__dirname, '..', 'rules');
-  const files = fs.readdirSync(rulesDir)
-    .filter(f => f.endsWith('.md') && !f.startsWith('_'));
-
-  const rules: Rule[] = [];
-
-  for (const file of files) {
-    const filePath = path.join(rulesDir, file);
-    const content = fs.readFileSync(filePath, 'utf-8');
-    const { frontmatter, body } = parseFrontmatter(content);
-
-    if (!frontmatter) {
-      console.warn(`Warning: No frontmatter found in ${file}`);
-      continue;
-    }
-
-    const category = getCategoryForFile(file);
-    if (!category) {
-      console.warn(`Warning: Unknown category for ${file}`);
-      continue;
-    }
-
-    rules.push({
-      filename: file,
-      frontmatter,
-      content: body,
-      category: category.name,
-      categorySection: category.section
-    });
-  }
-
-  return rules;
-}
-
-function generateTableOfContents(rulesByCategory: Map<string, Rule[]>): string {
-  let toc = '## Table of Contents\n\n';
-
-  for (const cat of CATEGORIES) {
-    const rules = rulesByCategory.get(cat.name);
-    if (!rules || rules.length === 0) continue;
-
-    // Section anchor format: #1-architecture
-    const sectionAnchor = `${cat.section}-${cat.name.toLowerCase().replace(/[^a-z0-9]+/g, '-')}`;
-    toc += `${cat.section}. [${cat.name}](#${sectionAnchor}) — **${cat.impact}**\n`;
-
-    for (let i = 0; i < rules.length; i++) {
-      const rule = rules[i];
-      // Rule anchor format: #11-rule-title
-      const ruleNum = `${cat.section}${i + 1}`;
-      const anchor = `${ruleNum}-${rule.frontmatter.title.toLowerCase().replace(/[^a-z0-9]+/g, '-')}`;
-      toc += `   - ${cat.section}.${i + 1} [${rule.frontmatter.title}](#${anchor})\n`;
-    }
-  }
-
-  return toc;
-}
-
-function generateAgentsMd(rules: Rule[], metadata: any): string {
-  // Group rules by category
-  const rulesByCategory = new Map<string, Rule[]>();
-
-  for (const rule of rules) {
-    if (!rulesByCategory.has(rule.category)) {
-      rulesByCategory.set(rule.category, []);
-    }
-    rulesByCategory.get(rule.category)!.push(rule);
-  }
-
-  // Sort rules within each category alphabetically
-  for (const [category, categoryRules] of rulesByCategory) {
-    categoryRules.sort((a, b) => a.filename.localeCompare(b.filename));
-  }
-
-  // Build document
-  let doc = `# NestJS Best Practices
-
-**Version ${metadata.version}**
-${metadata.organization}
-${metadata.date}
-
-> **Note:**
-> This document is mainly for agents and LLMs to follow when maintaining,
-> generating, or refactoring NestJS codebases. Humans may also find it
-> useful, but guidance here is optimized for automation and consistency
-> by AI-assisted workflows.
-
----
-
-## Abstract
-
-${metadata.abstract}
-
----
-
-`;
-
-  // Add table of contents
-  doc += generateTableOfContents(rulesByCategory);
-  doc += '\n---\n\n';
-
-  // Add rules by category
-  for (const cat of CATEGORIES) {
-    const categoryRules = rulesByCategory.get(cat.name);
-    if (!categoryRules || categoryRules.length === 0) continue;
-
-    doc += `## ${cat.section}. ${cat.name}\n\n`;
-    doc += `**Section Impact: ${cat.impact}**\n\n`;
-
-    for (let i = 0; i < categoryRules.length; i++) {
-      const rule = categoryRules[i];
-      const ruleNumber = `${cat.section}.${i + 1}`;
-
-      // Add rule header with number (anchor will be auto-generated as #11-title)
-      doc += `### ${ruleNumber} ${rule.frontmatter.title}\n\n`;
-      doc += `**Impact: ${rule.frontmatter.impact}** — ${rule.frontmatter.impactDescription}\n\n`;
-
-      // Add rule content (skip the first header since we already added it)
-      let ruleContent = rule.content;
-      // Remove the first h1 or h2 header if it matches the title
-      ruleContent = ruleContent.replace(/^#{1,2}\s+.*\n+/, '');
-      // Remove the impact line if present (we already added it)
-      ruleContent = ruleContent.replace(/^\*\*Impact:.*\*\*.*\n+/, '');
-
-      doc += ruleContent;
-      doc += '\n\n---\n\n';
-    }
-  }
-
-  // Add references footer
-  doc += `## References
-
-`;
-  for (const ref of metadata.references) {
-    doc += `- ${ref}\n`;
-  }
-
-  doc += `
----
-
-*Generated by build-agents.ts on ${new Date().toISOString().split('T')[0]}*
-`;
-
-  return doc;
-}
-
-function main() {
-  console.log('Building AGENTS.md...\n');
-
-  const metadata = readMetadata();
-  console.log(`Version: ${metadata.version}`);
-  console.log(`Organization: ${metadata.organization}\n`);
-
-  const rules = readRules();
-  console.log(`Found ${rules.length} rules\n`);
-
-  // Count by category
-  const counts = new Map<string, number>();
-  for (const rule of rules) {
-    counts.set(rule.category, (counts.get(rule.category) || 0) + 1);
-  }
-
-  console.log('Rules by category:');
-  for (const cat of CATEGORIES) {
-    const count = counts.get(cat.name) || 0;
-    if (count > 0) {
-      console.log(`  ${cat.name}: ${count}`);
-    }
-  }
-  console.log('');
-
-  const agentsMd = generateAgentsMd(rules, metadata);
-
-  const outputPath = path.join(__dirname, '..', 'AGENTS.md');
-  fs.writeFileSync(outputPath, agentsMd);
-
-  console.log(`Generated AGENTS.md (${agentsMd.length} bytes)`);
-  console.log(`Output: ${outputPath}`);
-}
-
-main();

.agents/skills/nestjs-best-practices/scripts/build.sh

@@ -1,16 +0,0 @@
-#!/bin/bash
-
-# Build script for generating AGENTS.md
-# Usage: ./build.sh
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-cd "$SCRIPT_DIR"
-
-# Check if ts-node is available
-if command -v npx &> /dev/null; then
-    echo "Running build with ts-node..."
-    npx ts-node build-agents.ts
-else
-    echo "Error: npx not found. Please install Node.js."
-    exit 1
-fi

.agents/skills/nestjs-best-practices/scripts/package.json

@@ -1,15 +0,0 @@
-{
-  "name": "nestjs-best-practices-scripts",
-  "version": "1.0.0",
-  "type": "module",
-  "description": "Build scripts for NestJS Best Practices skillset",
-  "scripts": {
-    "build": "npx ts-node build-agents.ts",
-    "build:watch": "npx nodemon --watch ../rules --ext md --exec 'npx ts-node build-agents.ts'"
-  },
-  "devDependencies": {
-    "typescript": "^5.0.0",
-    "ts-node": "^10.9.0",
-    "@types/node": "^20.0.0"
-  }
-}

.agents/skills/next-best-practices/SKILL.md

@@ -1,153 +0,0 @@
----
-name: next-best-practices
-description: Next.js best practices - file conventions, RSC boundaries, data patterns, async APIs, metadata, error handling, route handlers, image/font optimization, bundling
-user-invocable: false
----
-
-# Next.js Best Practices
-
-Apply these rules when writing or reviewing Next.js code.
-
-## File Conventions
-
-See [file-conventions.md](./file-conventions.md) for:
-- Project structure and special files
-- Route segments (dynamic, catch-all, groups)
-- Parallel and intercepting routes
-- Middleware rename in v16 (middleware → proxy)
-
-## RSC Boundaries
-
-Detect invalid React Server Component patterns.
-
-See [rsc-boundaries.md](./rsc-boundaries.md) for:
-- Async client component detection (invalid)
-- Non-serializable props detection
-- Server Action exceptions
-
-## Async Patterns
-
-Next.js 15+ async API changes.
-
-See [async-patterns.md](./async-patterns.md) for:
-- Async `params` and `searchParams`
-- Async `cookies()` and `headers()`
-- Migration codemod
-
-## Runtime Selection
-
-See [runtime-selection.md](./runtime-selection.md) for:
-- Default to Node.js runtime
-- When Edge runtime is appropriate
-
-## Directives
-
-See [directives.md](./directives.md) for:
-- `'use client'`, `'use server'` (React)
-- `'use cache'` (Next.js)
-
-## Functions
-
-See [functions.md](./functions.md) for:
-- Navigation hooks: `useRouter`, `usePathname`, `useSearchParams`, `useParams`
-- Server functions: `cookies`, `headers`, `draftMode`, `after`
-- Generate functions: `generateStaticParams`, `generateMetadata`
-
-## Error Handling
-
-See [error-handling.md](./error-handling.md) for:
-- `error.tsx`, `global-error.tsx`, `not-found.tsx`
-- `redirect`, `permanentRedirect`, `notFound`
-- `forbidden`, `unauthorized` (auth errors)
-- `unstable_rethrow` for catch blocks
-
-## Data Patterns
-
-See [data-patterns.md](./data-patterns.md) for:
-- Server Components vs Server Actions vs Route Handlers
-- Avoiding data waterfalls (`Promise.all`, Suspense, preload)
-- Client component data fetching
-
-## Route Handlers
-
-See [route-handlers.md](./route-handlers.md) for:
-- `route.ts` basics
-- GET handler conflicts with `page.tsx`
-- Environment behavior (no React DOM)
-- When to use vs Server Actions
-
-## Metadata & OG Images
-
-See [metadata.md](./metadata.md) for:
-- Static and dynamic metadata
-- `generateMetadata` function
-- OG image generation with `next/og`
-- File-based metadata conventions
-
-## Image Optimization
-
-See [image.md](./image.md) for:
-- Always use `next/image` over `<img>`
-- Remote images configuration
-- Responsive `sizes` attribute
-- Blur placeholders
-- Priority loading for LCP
-
-## Font Optimization
-
-See [font.md](./font.md) for:
-- `next/font` setup
-- Google Fonts, local fonts
-- Tailwind CSS integration
-- Preloading subsets
-
-## Bundling
-
-See [bundling.md](./bundling.md) for:
-- Server-incompatible packages
-- CSS imports (not link tags)
-- Polyfills (already included)
-- ESM/CommonJS issues
-- Bundle analysis
-
-## Scripts
-
-See [scripts.md](./scripts.md) for:
-- `next/script` vs native script tags
-- Inline scripts need `id`
-- Loading strategies
-- Google Analytics with `@next/third-parties`
-
-## Hydration Errors
-
-See [hydration-error.md](./hydration-error.md) for:
-- Common causes (browser APIs, dates, invalid HTML)
-- Debugging with error overlay
-- Fixes for each cause
-
-## Suspense Boundaries
-
-See [suspense-boundaries.md](./suspense-boundaries.md) for:
-- CSR bailout with `useSearchParams` and `usePathname`
-- Which hooks require Suspense boundaries
-
-## Parallel & Intercepting Routes
-
-See [parallel-routes.md](./parallel-routes.md) for:
-- Modal patterns with `@slot` and `(.)` interceptors
-- `default.tsx` for fallbacks
-- Closing modals correctly with `router.back()`
-
-## Self-Hosting
-
-See [self-hosting.md](./self-hosting.md) for:
-- `output: 'standalone'` for Docker
-- Cache handlers for multi-instance ISR
-- What works vs needs extra setup
-
-## Debug Tricks
-
-See [debug-tricks.md](./debug-tricks.md) for:
-- MCP endpoint for AI-assisted debugging
-- Rebuild specific routes with `--debug-build-paths`
-

.agents/skills/next-best-practices/async-patterns.md

@@ -1,87 +0,0 @@
-# Async Patterns
-
-In Next.js 15+, `params`, `searchParams`, `cookies()`, and `headers()` are asynchronous.
-
-## Async Params and SearchParams
-
-Always type them as `Promise<...>` and await them.
-
-### Pages and Layouts
-
-```tsx
-type Props = { params: Promise<{ slug: string }> }
-
-export default async function Page({ params }: Props) {
-  const { slug } = await params
-}
-```
-
-### Route Handlers
-
-```tsx
-export async function GET(
-  request: Request,
-  { params }: { params: Promise<{ id: string }> }
-) {
-  const { id } = await params
-}
-```
-
-### SearchParams
-
-```tsx
-type Props = {
-  params: Promise<{ slug: string }>
-  searchParams: Promise<{ query?: string }>
-}
-
-export default async function Page({ params, searchParams }: Props) {
-  const { slug } = await params
-  const { query } = await searchParams
-}
-```
-
-### Synchronous Components
-
-Use `React.use()` for non-async components:
-
-```tsx
-import { use } from 'react'
-
-type Props = { params: Promise<{ slug: string }> }
-
-export default function Page({ params }: Props) {
-  const { slug } = use(params)
-}
-```
-
-### generateMetadata
-
-```tsx
-type Props = { params: Promise<{ slug: string }> }
-
-export async function generateMetadata({ params }: Props): Promise<Metadata> {
-  const { slug } = await params
-  return { title: slug }
-}
-```
-
-## Async Cookies and Headers
-
-```tsx
-import { cookies, headers } from 'next/headers'
-
-export default async function Page() {
-  const cookieStore = await cookies()
-  const headersList = await headers()
-
-  const theme = cookieStore.get('theme')
-  const userAgent = headersList.get('user-agent')
-}
-```
-
-## Migration Codemod
-
-```bash
-npx @next/codemod@latest next-async-request-api .
-```

.agents/skills/next-best-practices/bundling.md

@@ -1,180 +0,0 @@
-# Bundling
-
-Fix common bundling issues with third-party packages.
-
-## Server-Incompatible Packages
-
-Some packages use browser APIs (`window`, `document`, `localStorage`) and fail in Server Components.
-
-### Error Signs
-
-```
-ReferenceError: window is not defined
-ReferenceError: document is not defined
-ReferenceError: localStorage is not defined
-Module not found: Can't resolve 'fs'
-```
-
-### Solution 1: Mark as Client-Only
-
-If the package is only needed on client:
-
-```tsx
-// Bad: Fails - package uses window
-import SomeChart from 'some-chart-library'
-
-export default function Page() {
-  return <SomeChart />
-}
-
-// Good: Use dynamic import with ssr: false
-import dynamic from 'next/dynamic'
-
-const SomeChart = dynamic(() => import('some-chart-library'), {
-  ssr: false,
-})
-
-export default function Page() {
-  return <SomeChart />
-}
-```
-
-### Solution 2: Externalize from Server Bundle
-
-For packages that should run on server but have bundling issues:
-
-```js
-// next.config.js
-module.exports = {
-  serverExternalPackages: ['problematic-package'],
-}
-```
-
-Use this for:
-- Packages with native bindings (sharp, bcrypt)
-- Packages that don't bundle well (some ORMs)
-- Packages with circular dependencies
-
-### Solution 3: Client Component Wrapper
-
-Wrap the entire usage in a client component:
-
-```tsx
-// components/ChartWrapper.tsx
-'use client'
-
-import { Chart } from 'chart-library'
-
-export function ChartWrapper(props) {
-  return <Chart {...props} />
-}
-
-// app/page.tsx (server component)
-import { ChartWrapper } from '@/components/ChartWrapper'
-
-export default function Page() {
-  return <ChartWrapper data={data} />
-}
-```
-
-## CSS Imports
-
-Import CSS files instead of using `<link>` tags. Next.js handles bundling and optimization.
-
-```tsx
-// Bad: Manual link tag
-<link rel="stylesheet" href="/styles.css" />
-
-// Good: Import CSS
-import './styles.css'
-
-// Good: CSS Modules
-import styles from './Button.module.css'
-```
-
-## Polyfills
-
-Next.js includes common polyfills automatically. Don't load redundant ones from polyfill.io or similar CDNs.
-
-Already included: `Array.from`, `Object.assign`, `Promise`, `fetch`, `Map`, `Set`, `Symbol`, `URLSearchParams`, and 50+ others.
-
-```tsx
-// Bad: Redundant polyfills
-<script src="https://polyfill.io/v3/polyfill.min.js?features=fetch,Promise,Array.from" />
-
-// Good: Next.js includes these automatically
-```
-
-## ESM/CommonJS Issues
-
-### Error Signs
-
-```
-SyntaxError: Cannot use import statement outside a module
-Error: require() of ES Module
-Module not found: ESM packages need to be imported
-```
-
-### Solution: Transpile Package
-
-```js
-// next.config.js
-module.exports = {
-  transpilePackages: ['some-esm-package', 'another-package'],
-}
-```
-
-## Common Problematic Packages
-
-| Package | Issue | Solution |
-|---------|-------|----------|
-| `sharp` | Native bindings | `serverExternalPackages: ['sharp']` |
-| `bcrypt` | Native bindings | `serverExternalPackages: ['bcrypt']` or use `bcryptjs` |
-| `canvas` | Native bindings | `serverExternalPackages: ['canvas']` |
-| `recharts` | Uses window | `dynamic(() => import('recharts'), { ssr: false })` |
-| `react-quill` | Uses document | `dynamic(() => import('react-quill'), { ssr: false })` |
-| `mapbox-gl` | Uses window | `dynamic(() => import('mapbox-gl'), { ssr: false })` |
-| `monaco-editor` | Uses window | `dynamic(() => import('@monaco-editor/react'), { ssr: false })` |
-| `lottie-web` | Uses document | `dynamic(() => import('lottie-react'), { ssr: false })` |
-
-## Bundle Analysis
-
-Analyze bundle size with the built-in analyzer (Next.js 16.1+):
-
-```bash
-next experimental-analyze
-```
-
-This opens an interactive UI to:
-- Filter by route, environment (client/server), and type
-- Inspect module sizes and import chains
-- View treemap visualization
-
-Save output for comparison:
-
-```bash
-next experimental-analyze --output
-# Output saved to .next/diagnostics/analyze
-```
-
-Reference: https://nextjs.org/docs/app/guides/package-bundling
-
-## Migrating from Webpack to Turbopack
-
-Turbopack is the default bundler in Next.js 15+. If you have custom webpack config, migrate to Turbopack-compatible alternatives:
-
-```js
-// next.config.js
-module.exports = {
-  // Good: Works with Turbopack
-  serverExternalPackages: ['package'],
-  transpilePackages: ['package'],
-
-  // Bad: Webpack-only - migrate away from this
-  webpack: (config) => {
-    // custom webpack config
-  },
-}
-```
-
-Reference: https://nextjs.org/docs/app/building-your-application/upgrading/from-webpack-to-turbopack

.agents/skills/next-best-practices/data-patterns.md

@@ -1,297 +0,0 @@
-# Data Patterns
-
-Choose the right data fetching pattern for each use case.
-
-## Decision Tree
-
-```
-Need to fetch data?
-├── From a Server Component?
-│   └── Use: Fetch directly (no API needed)
-│
-├── From a Client Component?
-│   ├── Is it a mutation (POST/PUT/DELETE)?
-│   │   └── Use: Server Action
-│   └── Is it a read (GET)?
-│       └── Use: Route Handler OR pass from Server Component
-│
-├── Need external API access (webhooks, third parties)?
-│   └── Use: Route Handler
-│
-└── Need REST API for mobile app / external clients?
-    └── Use: Route Handler
-```
-
-## Pattern 1: Server Components (Preferred for Reads)
-
-Fetch data directly in Server Components - no API layer needed.
-
-```tsx
-// app/users/page.tsx
-async function UsersPage() {
-  // Direct database access - no API round-trip
-  const users = await db.user.findMany();
-
-  // Or fetch from external API
-  const posts = await fetch('https://api.example.com/posts').then(r => r.json());
-
-  return (
-    <ul>
-      {users.map(user => <li key={user.id}>{user.name}</li>)}
-    </ul>
-  );
-}
-```
-
-**Benefits**:
-- No API to maintain
-- No client-server waterfall
-- Secrets stay on server
-- Direct database access
-
-## Pattern 2: Server Actions (Preferred for Mutations)
-
-Server Actions are the recommended way to handle mutations.
-
-```tsx
-// app/actions.ts
-'use server';
-
-import { revalidatePath } from 'next/cache';
-
-export async function createPost(formData: FormData) {
-  const title = formData.get('title') as string;
-
-  await db.post.create({ data: { title } });
-
-  revalidatePath('/posts');
-}
-
-export async function deletePost(id: string) {
-  await db.post.delete({ where: { id } });
-
-  revalidateTag('posts');
-}
-```
-
-```tsx
-// app/posts/new/page.tsx
-import { createPost } from '@/app/actions';
-
-export default function NewPost() {
-  return (
-    <form action={createPost}>
-      <input name="title" required />
-      <button type="submit">Create</button>
-    </form>
-  );
-}
-```
-
-**Benefits**:
-- End-to-end type safety
-- Progressive enhancement (works without JS)
-- Automatic request handling
-- Integrated with React transitions
-
-**Constraints**:
-- POST only (no GET caching semantics)
-- Internal use only (no external access)
-- Cannot return non-serializable data
-
-## Pattern 3: Route Handlers (APIs)
-
-Use Route Handlers when you need a REST API.
-
-```tsx
-// app/api/posts/route.ts
-import { NextRequest, NextResponse } from 'next/server';
-
-// GET is cacheable
-export async function GET(request: NextRequest) {
-  const posts = await db.post.findMany();
-  return NextResponse.json(posts);
-}
-
-// POST for mutations
-export async function POST(request: NextRequest) {
-  const body = await request.json();
-  const post = await db.post.create({ data: body });
-  return NextResponse.json(post, { status: 201 });
-}
-```
-
-**When to use**:
-- External API access (mobile apps, third parties)
-- Webhooks from external services
-- GET endpoints that need HTTP caching
-- OpenAPI/Swagger documentation needed
-
-**When NOT to use**:
-- Internal data fetching (use Server Components)
-- Mutations from your UI (use Server Actions)
-
-## Avoiding Data Waterfalls
-
-### Problem: Sequential Fetches
-
-```tsx
-// Bad: Sequential waterfalls
-async function Dashboard() {
-  const user = await getUser();        // Wait...
-  const posts = await getPosts();      // Then wait...
-  const comments = await getComments(); // Then wait...
-
-  return <div>...</div>;
-}
-```
-
-### Solution 1: Parallel Fetching with Promise.all
-
-```tsx
-// Good: Parallel fetching
-async function Dashboard() {
-  const [user, posts, comments] = await Promise.all([
-    getUser(),
-    getPosts(),
-    getComments(),
-  ]);
-
-  return <div>...</div>;
-}
-```
-
-### Solution 2: Streaming with Suspense
-
-```tsx
-// Good: Show content progressively
-import { Suspense } from 'react';
-
-async function Dashboard() {
-  return (
-    <div>
-      <Suspense fallback={<UserSkeleton />}>
-        <UserSection />
-      </Suspense>
-      <Suspense fallback={<PostsSkeleton />}>
-        <PostsSection />
-      </Suspense>
-    </div>
-  );
-}
-
-async function UserSection() {
-  const user = await getUser(); // Fetches independently
-  return <div>{user.name}</div>;
-}
-
-async function PostsSection() {
-  const posts = await getPosts(); // Fetches independently
-  return <PostList posts={posts} />;
-}
-```
-
-### Solution 3: Preload Pattern
-
-```tsx
-// lib/data.ts
-import { cache } from 'react';
-
-export const getUser = cache(async (id: string) => {
-  return db.user.findUnique({ where: { id } });
-});
-
-export const preloadUser = (id: string) => {
-  void getUser(id); // Fire and forget
-};
-```
-
-```tsx
-// app/user/[id]/page.tsx
-import { getUser, preloadUser } from '@/lib/data';
-
-export default async function UserPage({ params }) {
-  const { id } = await params;
-
-  // Start fetching early
-  preloadUser(id);
-
-  // Do other work...
-
-  // Data likely ready by now
-  const user = await getUser(id);
-  return <div>{user.name}</div>;
-}
-```
-
-## Client Component Data Fetching
-
-When Client Components need data:
-
-### Option 1: Pass from Server Component (Preferred)
-
-```tsx
-// Server Component
-async function Page() {
-  const data = await fetchData();
-  return <ClientComponent initialData={data} />;
-}
-
-// Client Component
-'use client';
-function ClientComponent({ initialData }) {
-  const [data, setData] = useState(initialData);
-  // ...
-}
-```
-
-### Option 2: Fetch on Mount (When Necessary)
-
-```tsx
-'use client';
-import { useEffect, useState } from 'react';
-
-function ClientComponent() {
-  const [data, setData] = useState(null);
-
-  useEffect(() => {
-    fetch('/api/data')
-      .then(r => r.json())
-      .then(setData);
-  }, []);
-
-  if (!data) return <Loading />;
-  return <div>{data.value}</div>;
-}
-```
-
-### Option 3: Server Action for Reads (Works But Not Ideal)
-
-Server Actions can be called from Client Components for reads, but this is not their intended purpose:
-
-```tsx
-'use client';
-import { getData } from './actions';
-import { useEffect, useState } from 'react';
-
-function ClientComponent() {
-  const [data, setData] = useState(null);
-
-  useEffect(() => {
-    getData().then(setData);
-  }, []);
-
-  return <div>{data?.value}</div>;
-}
-```
-
-**Note**: Server Actions always use POST, so no HTTP caching. Prefer Route Handlers for cacheable reads.
-
-## Quick Reference
-
-| Pattern | Use Case | HTTP Method | Caching |
-|---------|----------|-------------|---------|
-| Server Component fetch | Internal reads | Any | Full Next.js caching |
-| Server Action | Mutations, form submissions | POST only | No |
-| Route Handler | External APIs, webhooks | Any | GET can be cached |
-| Client fetch to API | Client-side reads | Any | HTTP cache headers |

.agents/skills/next-best-practices/debug-tricks.md

@@ -1,105 +0,0 @@
-# Debug Tricks
-
-Tricks to speed up debugging Next.js applications.
-
-## MCP Endpoint (Dev Server)
-
-Next.js exposes a `/_next/mcp` endpoint in development for AI-assisted debugging via MCP (Model Context Protocol).
-
-- **Next.js 16+**: Enabled by default, use `next-devtools-mcp`
-- **Next.js < 16**: Requires `experimental.mcpServer: true` in next.config.js
-
-Reference: https://nextjs.org/docs/app/guides/mcp
-
-**Important**: Find the actual port of the running Next.js dev server (check terminal output or `package.json` scripts). Don't assume port 3000.
-
-### Request Format
-
-The endpoint uses JSON-RPC 2.0 over HTTP POST:
-
-```bash
-curl -X POST http://localhost:<port>/_next/mcp \
-  -H "Content-Type: application/json" \
-  -H "Accept: application/json, text/event-stream" \
-  -d '{
-    "jsonrpc": "2.0",
-    "id": "1",
-    "method": "tools/call",
-    "params": {
-      "name": "<tool-name>",
-      "arguments": {}
-    }
-  }'
-```
-
-### Available Tools
-
-#### `get_errors`
-Get current errors from dev server (build errors, runtime errors with source-mapped stacks):
-```json
-{ "name": "get_errors", "arguments": {} }
-```
-
-#### `get_routes`
-Discover all routes by scanning filesystem:
-```json
-{ "name": "get_routes", "arguments": {} }
-// Optional: { "name": "get_routes", "arguments": { "routerType": "app" } }
-```
-Returns: `{ "appRouter": ["/", "/api/users/[id]", ...], "pagesRouter": [...] }`
-
-#### `get_project_metadata`
-Get project path and dev server URL:
-```json
-{ "name": "get_project_metadata", "arguments": {} }
-```
-Returns: `{ "projectPath": "/path/to/project", "devServerUrl": "http://localhost:3000" }`
-
-#### `get_page_metadata`
-Get runtime metadata about current page render (requires active browser session):
-```json
-{ "name": "get_page_metadata", "arguments": {} }
-```
-Returns segment trie data showing layouts, boundaries, and page components.
-
-#### `get_logs`
-Get path to Next.js development log file:
-```json
-{ "name": "get_logs", "arguments": {} }
-```
-Returns path to `<distDir>/logs/next-development.log`
-
-#### `get_server_action_by_id`
-Locate a Server Action by ID:
-```json
-{ "name": "get_server_action_by_id", "arguments": { "actionId": "<action-id>" } }
-```
-
-### Example: Get Errors
-
-```bash
-curl -X POST http://localhost:<port>/_next/mcp \
-  -H "Content-Type: application/json" \
-  -H "Accept: application/json, text/event-stream" \
-  -d '{"jsonrpc":"2.0","id":"1","method":"tools/call","params":{"name":"get_errors","arguments":{}}}'
-```
-
-## Rebuild Specific Routes (Next.js 16+)
-
-Use `--debug-build-paths` to rebuild only specific routes instead of the entire app:
-
-```bash
-# Rebuild a specific route
-next build --debug-build-paths "/dashboard"
-
-# Rebuild routes matching a glob
-next build --debug-build-paths "/api/*"
-
-# Dynamic routes
-next build --debug-build-paths "/blog/[slug]"
-```
-
-Use this to:
-- Quickly verify a build fix without full rebuild
-- Debug static generation issues for specific pages
-- Iterate faster on build errors

.agents/skills/next-best-practices/directives.md

@@ -1,73 +0,0 @@
-# Directives
-
-## React Directives
-
-These are React directives, not Next.js specific.
-
-### `'use client'`
-
-Marks a component as a Client Component. Required for:
-- React hooks (`useState`, `useEffect`, etc.)
-- Event handlers (`onClick`, `onChange`)
-- Browser APIs (`window`, `localStorage`)
-
-```tsx
-'use client'
-
-import { useState } from 'react'
-
-export function Counter() {
-  const [count, setCount] = useState(0)
-  return <button onClick={() => setCount(count + 1)}>{count}</button>
-}
-```
-
-Reference: https://react.dev/reference/rsc/use-client
-
-### `'use server'`
-
-Marks a function as a Server Action. Can be passed to Client Components.
-
-```tsx
-'use server'
-
-export async function submitForm(formData: FormData) {
-  // Runs on server
-}
-```
-
-Or inline within a Server Component:
-
-```tsx
-export default function Page() {
-  async function submit() {
-    'use server'
-    // Runs on server
-  }
-  return <form action={submit}>...</form>
-}
-```
-
-Reference: https://react.dev/reference/rsc/use-server
-
----
-
-## Next.js Directive
-
-### `'use cache'`
-
-Marks a function or component for caching. Part of Next.js Cache Components.
-
-```tsx
-'use cache'
-
-export async function getCachedData() {
-  return await fetchData()
-}
-```
-
-Requires `cacheComponents: true` in `next.config.ts`.
-
-For detailed usage including cache profiles, `cacheLife()`, `cacheTag()`, and `updateTag()`, see the `next-cache-components` skill.
-
-Reference: https://nextjs.org/docs/app/api-reference/directives/use-cache

.agents/skills/next-best-practices/error-handling.md

@@ -1,227 +0,0 @@
-# Error Handling
-
-Handle errors gracefully in Next.js applications.
-
-Reference: https://nextjs.org/docs/app/getting-started/error-handling
-
-## Error Boundaries
-
-### `error.tsx`
-
-Catches errors in a route segment and its children:
-
-```tsx
-'use client'
-
-export default function Error({
-  error,
-  reset,
-}: {
-  error: Error & { digest?: string }
-  reset: () => void
-}) {
-  return (
-    <div>
-      <h2>Something went wrong!</h2>
-      <button onClick={() => reset()}>Try again</button>
-    </div>
-  )
-}
-```
-
-**Important:** `error.tsx` must be a Client Component.
-
-### `global-error.tsx`
-
-Catches errors in root layout:
-
-```tsx
-'use client'
-
-export default function GlobalError({
-  error,
-  reset,
-}: {
-  error: Error & { digest?: string }
-  reset: () => void
-}) {
-  return (
-    <html>
-      <body>
-        <h2>Something went wrong!</h2>
-        <button onClick={() => reset()}>Try again</button>
-      </body>
-    </html>
-  )
-}
-```
-
-**Important:** Must include `<html>` and `<body>` tags.
-
-## Server Actions: Navigation API Gotcha
-
-**Do NOT wrap navigation APIs in try-catch.** They throw special errors that Next.js handles internally.
-
-Reference: https://nextjs.org/docs/app/api-reference/functions/redirect#behavior
-
-```tsx
-'use server'
-
-import { redirect } from 'next/navigation'
-import { notFound } from 'next/navigation'
-
-// Bad: try-catch catches the navigation "error"
-async function createPost(formData: FormData) {
-  try {
-    const post = await db.post.create({ ... })
-    redirect(`/posts/${post.id}`)  // This throws!
-  } catch (error) {
-    // redirect() throw is caught here - navigation fails!
-    return { error: 'Failed to create post' }
-  }
-}
-
-// Good: Call navigation APIs outside try-catch
-async function createPost(formData: FormData) {
-  let post
-  try {
-    post = await db.post.create({ ... })
-  } catch (error) {
-    return { error: 'Failed to create post' }
-  }
-  redirect(`/posts/${post.id}`)  // Outside try-catch
-}
-
-// Good: Re-throw navigation errors
-async function createPost(formData: FormData) {
-  try {
-    const post = await db.post.create({ ... })
-    redirect(`/posts/${post.id}`)
-  } catch (error) {
-    if (error instanceof Error && error.message === 'NEXT_REDIRECT') {
-      throw error  // Re-throw navigation errors
-    }
-    return { error: 'Failed to create post' }
-  }
-}
-```
-
-Same applies to:
-- `redirect()` - 307 temporary redirect
-- `permanentRedirect()` - 308 permanent redirect
-- `notFound()` - 404 not found
-- `forbidden()` - 403 forbidden
-- `unauthorized()` - 401 unauthorized
-
-Use `unstable_rethrow()` to re-throw these errors in catch blocks:
-
-```tsx
-import { unstable_rethrow } from 'next/navigation'
-
-async function action() {
-  try {
-    // ...
-    redirect('/success')
-  } catch (error) {
-    unstable_rethrow(error) // Re-throws Next.js internal errors
-    return { error: 'Something went wrong' }
-  }
-}
-```
-
-## Redirects
-
-```tsx
-import { redirect, permanentRedirect } from 'next/navigation'
-
-// 307 Temporary - use for most cases
-redirect('/new-path')
-
-// 308 Permanent - use for URL migrations (cached by browsers)
-permanentRedirect('/new-url')
-```
-
-## Auth Errors
-
-Trigger auth-related error pages:
-
-```tsx
-import { forbidden, unauthorized } from 'next/navigation'
-
-async function Page() {
-  const session = await getSession()
-
-  if (!session) {
-    unauthorized() // Renders unauthorized.tsx (401)
-  }
-
-  if (!session.hasAccess) {
-    forbidden() // Renders forbidden.tsx (403)
-  }
-
-  return <Dashboard />
-}
-```
-
-Create corresponding error pages:
-
-```tsx
-// app/forbidden.tsx
-export default function Forbidden() {
-  return <div>You don't have access to this resource</div>
-}
-
-// app/unauthorized.tsx
-export default function Unauthorized() {
-  return <div>Please log in to continue</div>
-}
-```
-
-## Not Found
-
-### `not-found.tsx`
-
-Custom 404 page for a route segment:
-
-```tsx
-export default function NotFound() {
-  return (
-    <div>
-      <h2>Not Found</h2>
-      <p>Could not find the requested resource</p>
-    </div>
-  )
-}
-```
-
-### Triggering Not Found
-
-```tsx
-import { notFound } from 'next/navigation'
-
-export default async function Page({ params }: { params: Promise<{ id: string }> }) {
-  const { id } = await params
-  const post = await getPost(id)
-
-  if (!post) {
-    notFound()  // Renders closest not-found.tsx
-  }
-
-  return <div>{post.title}</div>
-}
-```
-
-## Error Hierarchy
-
-Errors bubble up to the nearest error boundary:
-
-```
-app/
-├── error.tsx           # Catches errors from all children
-├── blog/
-│   ├── error.tsx       # Catches errors in /blog/*
-│   └── [slug]/
-│       ├── error.tsx   # Catches errors in /blog/[slug]
-│       └── page.tsx
-└── layout.tsx          # Errors here go to global-error.tsx
-```

.agents/skills/next-best-practices/file-conventions.md

@@ -1,140 +0,0 @@
-# File Conventions
-
-Next.js App Router uses file-based routing with special file conventions.
-
-## Project Structure
-
-Reference: https://nextjs.org/docs/app/getting-started/project-structure
-
-```
-app/
-├── layout.tsx          # Root layout (required)
-├── page.tsx            # Home page (/)
-├── loading.tsx         # Loading UI
-├── error.tsx           # Error UI
-├── not-found.tsx       # 404 UI
-├── global-error.tsx    # Global error UI
-├── route.ts            # API endpoint
-├── template.tsx        # Re-rendered layout
-├── default.tsx         # Parallel route fallback
-├── blog/
-│   ├── page.tsx        # /blog
-│   └── [slug]/
-│       └── page.tsx    # /blog/:slug
-└── (group)/            # Route group (no URL impact)
-    └── page.tsx
-```
-
-## Special Files
-
-| File | Purpose |
-|------|---------|
-| `page.tsx` | UI for a route segment |
-| `layout.tsx` | Shared UI for segment and children |
-| `loading.tsx` | Loading UI (Suspense boundary) |
-| `error.tsx` | Error UI (Error boundary) |
-| `not-found.tsx` | 404 UI |
-| `route.ts` | API endpoint |
-| `template.tsx` | Like layout but re-renders on navigation |
-| `default.tsx` | Fallback for parallel routes |
-
-## Route Segments
-
-```
-app/
-├── blog/               # Static segment: /blog
-├── [slug]/             # Dynamic segment: /:slug
-├── [...slug]/          # Catch-all: /a/b/c
-├── [[...slug]]/        # Optional catch-all: / or /a/b/c
-└── (marketing)/        # Route group (ignored in URL)
-```
-
-## Parallel Routes
-
-```
-app/
-├── @analytics/
-│   └── page.tsx
-├── @sidebar/
-│   └── page.tsx
-└── layout.tsx          # Receives { analytics, sidebar } as props
-```
-
-## Intercepting Routes
-
-```
-app/
-├── feed/
-│   └── page.tsx
-├── @modal/
-│   └── (.)photo/[id]/  # Intercepts /photo/[id] from /feed
-│       └── page.tsx
-└── photo/[id]/
-    └── page.tsx
-```
-
-Conventions:
-- `(.)` - same level
-- `(..)` - one level up
-- `(..)(..)` - two levels up
-- `(...)` - from root
-
-## Private Folders
-
-```
-app/
-├── _components/        # Private folder (not a route)
-│   └── Button.tsx
-└── page.tsx
-```
-
-Prefix with `_` to exclude from routing.
-
-## Middleware / Proxy
-
-### Next.js 14-15: `middleware.ts`
-
-```ts
-// middleware.ts (root of project)
-import { NextResponse } from 'next/server';
-import type { NextRequest } from 'next/server';
-
-export function middleware(request: NextRequest) {
-  // Auth, redirects, rewrites, etc.
-  return NextResponse.next();
-}
-
-export const config = {
-  matcher: ['/dashboard/:path*', '/api/:path*'],
-};
-```
-
-### Next.js 16+: `proxy.ts`
-
-Renamed for clarity - same capabilities, different names:
-
-```ts
-// proxy.ts (root of project)
-import { NextResponse } from 'next/server';
-import type { NextRequest } from 'next/server';
-
-export function proxy(request: NextRequest) {
-  // Same logic as middleware
-  return NextResponse.next();
-}
-
-export const proxyConfig = {
-  matcher: ['/dashboard/:path*', '/api/:path*'],
-};
-```
-
-| Version | File | Export | Config |
-|---------|------|--------|--------|
-| v14-15 | `middleware.ts` | `middleware()` | `config` |
-| v16+ | `proxy.ts` | `proxy()` | `proxyConfig` |
-
-**Migration**: Run `npx @next/codemod@latest upgrade` to auto-rename.
-
-## File Conventions Reference
-
-Reference: https://nextjs.org/docs/app/api-reference/file-conventions

.agents/skills/next-best-practices/font.md

@@ -1,245 +0,0 @@
-# Font Optimization
-
-Use `next/font` for automatic font optimization with zero layout shift.
-
-## Google Fonts
-
-```tsx
-// app/layout.tsx
-import { Inter } from 'next/font/google'
-
-const inter = Inter({ subsets: ['latin'] })
-
-export default function RootLayout({ children }: { children: React.ReactNode }) {
-  return (
-    <html lang="en" className={inter.className}>
-      <body>{children}</body>
-    </html>
-  )
-}
-```
-
-## Multiple Fonts
-
-```tsx
-import { Inter, Roboto_Mono } from 'next/font/google'
-
-const inter = Inter({
-  subsets: ['latin'],
-  variable: '--font-inter',
-})
-
-const robotoMono = Roboto_Mono({
-  subsets: ['latin'],
-  variable: '--font-roboto-mono',
-})
-
-export default function RootLayout({ children }: { children: React.ReactNode }) {
-  return (
-    <html lang="en" className={`${inter.variable} ${robotoMono.variable}`}>
-      <body>{children}</body>
-    </html>
-  )
-}
-```
-
-Use in CSS:
-```css
-body {
-  font-family: var(--font-inter);
-}
-
-code {
-  font-family: var(--font-roboto-mono);
-}
-```
-
-## Font Weights and Styles
-
-```tsx
-// Single weight
-const inter = Inter({
-  subsets: ['latin'],
-  weight: '400',
-})
-
-// Multiple weights
-const inter = Inter({
-  subsets: ['latin'],
-  weight: ['400', '500', '700'],
-})
-
-// Variable font (recommended) - includes all weights
-const inter = Inter({
-  subsets: ['latin'],
-  // No weight needed - variable fonts support all weights
-})
-
-// With italic
-const inter = Inter({
-  subsets: ['latin'],
-  style: ['normal', 'italic'],
-})
-```
-
-## Local Fonts
-
-```tsx
-import localFont from 'next/font/local'
-
-const myFont = localFont({
-  src: './fonts/MyFont.woff2',
-})
-
-// Multiple files for different weights
-const myFont = localFont({
-  src: [
-    {
-      path: './fonts/MyFont-Regular.woff2',
-      weight: '400',
-      style: 'normal',
-    },
-    {
-      path: './fonts/MyFont-Bold.woff2',
-      weight: '700',
-      style: 'normal',
-    },
-  ],
-})
-
-// Variable font
-const myFont = localFont({
-  src: './fonts/MyFont-Variable.woff2',
-  variable: '--font-my-font',
-})
-```
-
-## Tailwind CSS Integration
-
-```tsx
-// app/layout.tsx
-import { Inter } from 'next/font/google'
-
-const inter = Inter({
-  subsets: ['latin'],
-  variable: '--font-inter',
-})
-
-export default function RootLayout({ children }) {
-  return (
-    <html lang="en" className={inter.variable}>
-      <body>{children}</body>
-    </html>
-  )
-}
-```
-
-```js
-// tailwind.config.js
-module.exports = {
-  theme: {
-    extend: {
-      fontFamily: {
-        sans: ['var(--font-inter)'],
-      },
-    },
-  },
-}
-```
-
-## Preloading Subsets
-
-Only load needed character subsets:
-
-```tsx
-// Latin only (most common)
-const inter = Inter({ subsets: ['latin'] })
-
-// Multiple subsets
-const inter = Inter({ subsets: ['latin', 'latin-ext', 'cyrillic'] })
-```
-
-## Display Strategy
-
-Control font loading behavior:
-
-```tsx
-const inter = Inter({
-  subsets: ['latin'],
-  display: 'swap', // Default - shows fallback, swaps when loaded
-})
-
-// Options:
-// 'auto' - browser decides
-// 'block' - short block period, then swap
-// 'swap' - immediate fallback, swap when ready (recommended)
-// 'fallback' - short block, short swap, then fallback
-// 'optional' - short block, no swap (use if font is optional)
-```
-
-## Don't Use Manual Font Links
-
-Always use `next/font` instead of `<link>` tags for Google Fonts.
-
-```tsx
-// Bad: Manual link tag (blocks rendering, no optimization)
-<link href="https://fonts.googleapis.com/css2?family=Inter" rel="stylesheet" />
-
-// Bad: Missing display and preconnect
-<link href="https://fonts.googleapis.com/css2?family=Inter" rel="stylesheet" />
-
-// Good: Use next/font (self-hosted, zero layout shift)
-import { Inter } from 'next/font/google'
-
-const inter = Inter({ subsets: ['latin'] })
-```
-
-## Common Mistakes
-
-```tsx
-// Bad: Importing font in every component
-// components/Button.tsx
-import { Inter } from 'next/font/google'
-const inter = Inter({ subsets: ['latin'] }) // Creates new instance each time!
-
-// Good: Import once in layout, use CSS variable
-// app/layout.tsx
-const inter = Inter({ subsets: ['latin'], variable: '--font-inter' })
-
-// Bad: Using @import in CSS (blocks rendering)
-/* globals.css */
-@import url('https://fonts.googleapis.com/css2?family=Inter');
-
-// Good: Use next/font (self-hosted, no network request)
-import { Inter } from 'next/font/google'
-
-// Bad: Loading all weights when only using a few
-const inter = Inter({ subsets: ['latin'] }) // Loads all weights
-
-// Good: Specify only needed weights (for non-variable fonts)
-const inter = Inter({ subsets: ['latin'], weight: ['400', '700'] })
-
-// Bad: Missing subset - loads all characters
-const inter = Inter({})
-
-// Good: Always specify subset
-const inter = Inter({ subsets: ['latin'] })
-```
-
-## Font in Specific Components
-
-```tsx
-// For component-specific fonts, export from a shared file
-// lib/fonts.ts
-import { Inter, Playfair_Display } from 'next/font/google'
-
-export const inter = Inter({ subsets: ['latin'], variable: '--font-inter' })
-export const playfair = Playfair_Display({ subsets: ['latin'], variable: '--font-playfair' })
-
-// components/Heading.tsx
-import { playfair } from '@/lib/fonts'
-
-export function Heading({ children }) {
-  return <h1 className={playfair.className}>{children}</h1>
-}
-```

.agents/skills/next-best-practices/functions.md

@@ -1,108 +0,0 @@
-# Functions
-
-Next.js function APIs.
-
-Reference: https://nextjs.org/docs/app/api-reference/functions
-
-## Navigation Hooks (Client)
-
-| Hook | Purpose | Reference |
-|------|---------|-----------|
-| `useRouter` | Programmatic navigation (`push`, `replace`, `back`, `refresh`) | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-router) |
-| `usePathname` | Get current pathname | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-pathname) |
-| `useSearchParams` | Read URL search parameters | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-search-params) |
-| `useParams` | Access dynamic route parameters | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-params) |
-| `useSelectedLayoutSegment` | Active child segment (one level) | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-selected-layout-segment) |
-| `useSelectedLayoutSegments` | All active segments below layout | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-selected-layout-segments) |
-| `useLinkStatus` | Check link prefetch status | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-link-status) |
-| `useReportWebVitals` | Report Core Web Vitals metrics | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-report-web-vitals) |
-
-## Server Functions
-
-| Function | Purpose | Reference |
-|----------|---------|-----------|
-| `cookies` | Read/write cookies | [Docs](https://nextjs.org/docs/app/api-reference/functions/cookies) |
-| `headers` | Read request headers | [Docs](https://nextjs.org/docs/app/api-reference/functions/headers) |
-| `draftMode` | Enable preview of unpublished CMS content | [Docs](https://nextjs.org/docs/app/api-reference/functions/draft-mode) |
-| `after` | Run code after response finishes streaming | [Docs](https://nextjs.org/docs/app/api-reference/functions/after) |
-| `connection` | Wait for connection before dynamic rendering | [Docs](https://nextjs.org/docs/app/api-reference/functions/connection) |
-| `userAgent` | Parse User-Agent header | [Docs](https://nextjs.org/docs/app/api-reference/functions/userAgent) |
-
-## Generate Functions
-
-| Function | Purpose | Reference |
-|----------|---------|-----------|
-| `generateStaticParams` | Pre-render dynamic routes at build time | [Docs](https://nextjs.org/docs/app/api-reference/functions/generate-static-params) |
-| `generateMetadata` | Dynamic metadata | [Docs](https://nextjs.org/docs/app/api-reference/functions/generate-metadata) |
-| `generateViewport` | Dynamic viewport config | [Docs](https://nextjs.org/docs/app/api-reference/functions/generate-viewport) |
-| `generateSitemaps` | Multiple sitemaps for large sites | [Docs](https://nextjs.org/docs/app/api-reference/functions/generate-sitemaps) |
-| `generateImageMetadata` | Multiple OG images per route | [Docs](https://nextjs.org/docs/app/api-reference/functions/generate-image-metadata) |
-
-## Request/Response
-
-| Function | Purpose | Reference |
-|----------|---------|-----------|
-| `NextRequest` | Extended Request with helpers | [Docs](https://nextjs.org/docs/app/api-reference/functions/next-request) |
-| `NextResponse` | Extended Response with helpers | [Docs](https://nextjs.org/docs/app/api-reference/functions/next-response) |
-| `ImageResponse` | Generate OG images | [Docs](https://nextjs.org/docs/app/api-reference/functions/image-response) |
-
-## Common Examples
-
-### Navigation
-
-Use `next/link` for internal navigation instead of `<a>` tags.
-
-```tsx
-// Bad: Plain anchor tag
-<a href="/about">About</a>
-
-// Good: Next.js Link
-import Link from 'next/link'
-
-<Link href="/about">About</Link>
-```
-
-Active link styling:
-
-```tsx
-'use client'
-
-import Link from 'next/link'
-import { usePathname } from 'next/navigation'
-
-export function NavLink({ href, children }) {
-  const pathname = usePathname()
-
-  return (
-    <Link href={href} className={pathname === href ? 'active' : ''}>
-      {children}
-    </Link>
-  )
-}
-```
-
-### Static Generation
-
-```tsx
-// app/blog/[slug]/page.tsx
-export async function generateStaticParams() {
-  const posts = await getPosts()
-  return posts.map((post) => ({ slug: post.slug }))
-}
-```
-
-### After Response
-
-```tsx
-import { after } from 'next/server'
-
-export async function POST(request: Request) {
-  const data = await processRequest(request)
-
-  after(async () => {
-    await logAnalytics(data)
-  })
-
-  return Response.json({ success: true })
-}
-```

.agents/skills/next-best-practices/hydration-error.md

@@ -1,91 +0,0 @@
-# Hydration Errors
-
-Diagnose and fix React hydration mismatch errors.
-
-## Error Signs
-
-- "Hydration failed because the initial UI does not match"
-- "Text content does not match server-rendered HTML"
-
-## Debugging
-
-In development, click the hydration error to see the server/client diff.
-
-## Common Causes and Fixes
-
-### Browser-only APIs
-
-```tsx
-// Bad: Causes mismatch - window doesn't exist on server
-<div>{window.innerWidth}</div>
-
-// Good: Use client component with mounted check
-'use client'
-import { useState, useEffect } from 'react'
-
-export function ClientOnly({ children }: { children: React.ReactNode }) {
-  const [mounted, setMounted] = useState(false)
-  useEffect(() => setMounted(true), [])
-  return mounted ? children : null
-}
-```
-
-### Date/Time Rendering
-
-Server and client may be in different timezones:
-
-```tsx
-// Bad: Causes mismatch
-<span>{new Date().toLocaleString()}</span>
-
-// Good: Render on client only
-'use client'
-const [time, setTime] = useState<string>()
-useEffect(() => setTime(new Date().toLocaleString()), [])
-```
-
-### Random Values or IDs
-
-```tsx
-// Bad: Random values differ between server and client
-<div id={Math.random().toString()}>
-
-// Good: Use useId hook
-import { useId } from 'react'
-
-function Input() {
-  const id = useId()
-  return <input id={id} />
-}
-```
-
-### Invalid HTML Nesting
-
-```tsx
-// Bad: Invalid - div inside p
-<p><div>Content</div></p>
-
-// Bad: Invalid - p inside p
-<p><p>Nested</p></p>
-
-// Good: Valid nesting
-<div><p>Content</p></div>
-```
-
-### Third-party Scripts
-
-Scripts that modify DOM during hydration.
-
-```tsx
-// Good: Use next/script with afterInteractive
-import Script from 'next/script'
-
-export default function Page() {
-  return (
-    <Script
-      src="https://example.com/script.js"
-      strategy="afterInteractive"
-    />
-  )
-}
-```

.agents/skills/next-best-practices/image.md

@@ -1,173 +0,0 @@
-# Image Optimization
-
-Use `next/image` for automatic image optimization.
-
-## Always Use next/image
-
-```tsx
-// Bad: Avoid native img
-<img src="/hero.png" alt="Hero" />
-
-// Good: Use next/image
-import Image from 'next/image'
-<Image src="/hero.png" alt="Hero" width={800} height={400} />
-```
-
-## Required Props
-
-Images need explicit dimensions to prevent layout shift:
-
-```tsx
-// Local images - dimensions inferred automatically
-import heroImage from './hero.png'
-<Image src={heroImage} alt="Hero" />
-
-// Remote images - must specify width/height
-<Image src="https://example.com/image.jpg" alt="Hero" width={800} height={400} />
-
-// Or use fill for parent-relative sizing
-<div style={{ position: 'relative', width: '100%', height: 400 }}>
-  <Image src="/hero.png" alt="Hero" fill style={{ objectFit: 'cover' }} />
-</div>
-```
-
-## Remote Images Configuration
-
-Remote domains must be configured in `next.config.js`:
-
-```js
-// next.config.js
-module.exports = {
-  images: {
-    remotePatterns: [
-      {
-        protocol: 'https',
-        hostname: 'example.com',
-        pathname: '/images/**',
-      },
-      {
-        protocol: 'https',
-        hostname: '*.cdn.com', // Wildcard subdomain
-      },
-    ],
-  },
-}
-```
-
-## Responsive Images
-
-Use `sizes` to tell the browser which size to download:
-
-```tsx
-// Full-width hero
-<Image
-  src="/hero.png"
-  alt="Hero"
-  fill
-  sizes="100vw"
-/>
-
-// Responsive grid (3 columns on desktop, 1 on mobile)
-<Image
-  src="/card.png"
-  alt="Card"
-  fill
-  sizes="(max-width: 768px) 100vw, 33vw"
-/>
-
-// Fixed sidebar image
-<Image
-  src="/avatar.png"
-  alt="Avatar"
-  width={200}
-  height={200}
-  sizes="200px"
-/>
-```
-
-## Blur Placeholder
-
-Prevent layout shift with placeholders:
-
-```tsx
-// Local images - automatic blur hash
-import heroImage from './hero.png'
-<Image src={heroImage} alt="Hero" placeholder="blur" />
-
-// Remote images - provide blurDataURL
-<Image
-  src="https://example.com/image.jpg"
-  alt="Hero"
-  width={800}
-  height={400}
-  placeholder="blur"
-  blurDataURL="data:image/jpeg;base64,/9j/4AAQSkZJRg..."
-/>
-
-// Or use color placeholder
-<Image
-  src="https://example.com/image.jpg"
-  alt="Hero"
-  width={800}
-  height={400}
-  placeholder="empty"
-  style={{ backgroundColor: '#e0e0e0' }}
-/>
-```
-
-## Priority Loading
-
-Use `priority` for above-the-fold images (LCP):
-
-```tsx
-// Hero image - loads immediately
-<Image src="/hero.png" alt="Hero" fill priority />
-
-// Below-fold images - lazy loaded by default (no priority needed)
-<Image src="/card.png" alt="Card" width={400} height={300} />
-```
-
-## Common Mistakes
-
-```tsx
-// Bad: Missing sizes with fill - downloads largest image
-<Image src="/hero.png" alt="Hero" fill />
-
-// Good: Add sizes for proper responsive behavior
-<Image src="/hero.png" alt="Hero" fill sizes="100vw" />
-
-// Bad: Using width/height for aspect ratio only
-<Image src="/hero.png" alt="Hero" width={16} height={9} />
-
-// Good: Use actual display dimensions or fill with sizes
-<Image src="/hero.png" alt="Hero" fill sizes="100vw" style={{ objectFit: 'cover' }} />
-
-// Bad: Remote image without config
-<Image src="https://untrusted.com/image.jpg" alt="Image" width={400} height={300} />
-// Error: Invalid src prop, hostname not configured
-
-// Good: Add hostname to next.config.js remotePatterns
-```
-
-## Static Export
-
-When using `output: 'export'`, use `unoptimized` or custom loader:
-
-```tsx
-// Option 1: Disable optimization
-<Image src="/hero.png" alt="Hero" width={800} height={400} unoptimized />
-
-// Option 2: Global config
-// next.config.js
-module.exports = {
-  output: 'export',
-  images: { unoptimized: true },
-}
-
-// Option 3: Custom loader (Cloudinary, Imgix, etc.)
-const cloudinaryLoader = ({ src, width, quality }) => {
-  return `https://res.cloudinary.com/demo/image/upload/w_${width},q_${quality || 75}/${src}`
-}
-
-<Image loader={cloudinaryLoader} src="sample.jpg" alt="Sample" width={800} height={400} />
-```

.agents/skills/next-best-practices/metadata.md

@@ -1,301 +0,0 @@
-# Metadata
-
-Add SEO metadata to Next.js pages using the Metadata API.
-
-## Important: Server Components Only
-
-The `metadata` object and `generateMetadata` function are **only supported in Server Components**. They cannot be used in Client Components.
-
-If the target page has `'use client'`:
-1. Remove `'use client'` if possible, move client logic to child components
-2. Or extract metadata to a parent Server Component layout
-3. Or split the file: Server Component with metadata imports Client Components
-
-## Static Metadata
-
-```tsx
-import type { Metadata } from 'next'
-
-export const metadata: Metadata = {
-  title: 'Page Title',
-  description: 'Page description for search engines',
-}
-```
-
-## Dynamic Metadata
-
-```tsx
-import type { Metadata } from 'next'
-
-type Props = { params: Promise<{ slug: string }> }
-
-export async function generateMetadata({ params }: Props): Promise<Metadata> {
-  const { slug } = await params
-  const post = await getPost(slug)
-  return { title: post.title, description: post.description }
-}
-```
-
-## Avoid Duplicate Fetches
-
-Use React `cache()` when the same data is needed for both metadata and page:
-
-```tsx
-import { cache } from 'react'
-
-export const getPost = cache(async (slug: string) => {
-  return await db.posts.findFirst({ where: { slug } })
-})
-```
-
-## Viewport
-
-Separate from metadata for streaming support:
-
-```tsx
-import type { Viewport } from 'next'
-
-export const viewport: Viewport = {
-  width: 'device-width',
-  initialScale: 1,
-  themeColor: '#000000',
-}
-
-// Or dynamic
-export function generateViewport({ params }): Viewport {
-  return { themeColor: getThemeColor(params) }
-}
-```
-
-## Title Templates
-
-In root layout for consistent naming:
-
-```tsx
-export const metadata: Metadata = {
-  title: { default: 'Site Name', template: '%s | Site Name' },
-}
-```
-
-## Metadata File Conventions
-
-Reference: https://nextjs.org/docs/app/getting-started/project-structure#metadata-file-conventions
-
-Place these files in `app/` directory (or route segments):
-
-| File | Purpose |
-|------|---------|
-| `favicon.ico` | Favicon |
-| `icon.png` / `icon.svg` | App icon |
-| `apple-icon.png` | Apple app icon |
-| `opengraph-image.png` | OG image |
-| `twitter-image.png` | Twitter card image |
-| `sitemap.ts` / `sitemap.xml` | Sitemap (use `generateSitemaps` for multiple) |
-| `robots.ts` / `robots.txt` | Robots directives |
-| `manifest.ts` / `manifest.json` | Web app manifest |
-
-## SEO Best Practice: Static Files Are Often Enough
-
-For most sites, **static metadata files provide excellent SEO coverage**:
-
-```
-app/
-├── favicon.ico
-├── opengraph-image.png     # Works for both OG and Twitter
-├── sitemap.ts
-├── robots.ts
-└── layout.tsx              # With title/description metadata
-```
-
-**Tips:**
-- A single `opengraph-image.png` covers both Open Graph and Twitter (Twitter falls back to OG)
-- Static `title` and `description` in layout metadata is sufficient for most pages
-- Only use dynamic `generateMetadata` when content varies per page
-
----
-
-# OG Image Generation
-
-Generate dynamic Open Graph images using `next/og`.
-
-## Important Rules
-
-1. **Use `next/og`** - not `@vercel/og` (it's built into Next.js)
-2. **No searchParams** - OG images can't access search params, use route params instead
-3. **Avoid Edge runtime** - Use default Node.js runtime
-
-```tsx
-// Good
-import { ImageResponse } from 'next/og'
-
-// Bad
-// import { ImageResponse } from '@vercel/og'
-// export const runtime = 'edge'
-```
-
-## Basic OG Image
-
-```tsx
-// app/opengraph-image.tsx
-import { ImageResponse } from 'next/og'
-
-export const alt = 'Site Name'
-export const size = { width: 1200, height: 630 }
-export const contentType = 'image/png'
-
-export default function Image() {
-  return new ImageResponse(
-    (
-      <div
-        style={{
-          fontSize: 128,
-          background: 'white',
-          width: '100%',
-          height: '100%',
-          display: 'flex',
-          alignItems: 'center',
-          justifyContent: 'center',
-        }}
-      >
-        Hello World
-      </div>
-    ),
-    { ...size }
-  )
-}
-```
-
-## Dynamic OG Image
-
-```tsx
-// app/blog/[slug]/opengraph-image.tsx
-import { ImageResponse } from 'next/og'
-
-export const alt = 'Blog Post'
-export const size = { width: 1200, height: 630 }
-export const contentType = 'image/png'
-
-type Props = { params: Promise<{ slug: string }> }
-
-export default async function Image({ params }: Props) {
-  const { slug } = await params
-  const post = await getPost(slug)
-
-  return new ImageResponse(
-    (
-      <div
-        style={{
-          fontSize: 48,
-          background: 'linear-gradient(to bottom, #1a1a1a, #333)',
-          color: 'white',
-          width: '100%',
-          height: '100%',
-          display: 'flex',
-          flexDirection: 'column',
-          alignItems: 'center',
-          justifyContent: 'center',
-          padding: 48,
-        }}
-      >
-        <div style={{ fontSize: 64, fontWeight: 'bold' }}>{post.title}</div>
-        <div style={{ marginTop: 24, opacity: 0.8 }}>{post.description}</div>
-      </div>
-    ),
-    { ...size }
-  )
-}
-```
-
-## Custom Fonts
-
-```tsx
-import { ImageResponse } from 'next/og'
-import { join } from 'path'
-import { readFile } from 'fs/promises'
-
-export default async function Image() {
-  const fontPath = join(process.cwd(), 'assets/fonts/Inter-Bold.ttf')
-  const fontData = await readFile(fontPath)
-
-  return new ImageResponse(
-    (
-      <div style={{ fontFamily: 'Inter', fontSize: 64 }}>
-        Custom Font Text
-      </div>
-    ),
-    {
-      width: 1200,
-      height: 630,
-      fonts: [{ name: 'Inter', data: fontData, style: 'normal' }],
-    }
-  )
-}
-```
-
-## File Naming
-
-- `opengraph-image.tsx` - Open Graph (Facebook, LinkedIn)
-- `twitter-image.tsx` - Twitter/X cards (optional, falls back to OG)
-
-## Styling Notes
-
-ImageResponse uses Flexbox layout:
-- Use `display: 'flex'`
-- No CSS Grid support
-- Styles must be inline objects
-
-## Multiple OG Images
-
-Use `generateImageMetadata` for multiple images per route:
-
-```tsx
-// app/blog/[slug]/opengraph-image.tsx
-import { ImageResponse } from 'next/og'
-
-export async function generateImageMetadata({ params }) {
-  const images = await getPostImages(params.slug)
-  return images.map((img, idx) => ({
-    id: idx,
-    alt: img.alt,
-    size: { width: 1200, height: 630 },
-    contentType: 'image/png',
-  }))
-}
-
-export default async function Image({ params, id }) {
-  const images = await getPostImages(params.slug)
-  const image = images[id]
-  return new ImageResponse(/* ... */)
-}
-```
-
-## Multiple Sitemaps
-
-Use `generateSitemaps` for large sites:
-
-```tsx
-// app/sitemap.ts
-import type { MetadataRoute } from 'next'
-
-export async function generateSitemaps() {
-  // Return array of sitemap IDs
-  return [{ id: 0 }, { id: 1 }, { id: 2 }]
-}
-
-export default async function sitemap({
-  id,
-}: {
-  id: number
-}): Promise<MetadataRoute.Sitemap> {
-  const start = id * 50000
-  const end = start + 50000
-  const products = await getProducts(start, end)
-
-  return products.map((product) => ({
-    url: `https://example.com/product/${product.id}`,
-    lastModified: product.updatedAt,
-  }))
-}
-```
-
-Generates `/sitemap/0.xml`, `/sitemap/1.xml`, etc.

.agents/skills/next-best-practices/parallel-routes.md

@@ -1,287 +0,0 @@
-# Parallel & Intercepting Routes
-
-Parallel routes render multiple pages in the same layout. Intercepting routes show a different UI when navigating from within your app vs direct URL access. Together they enable modal patterns.
-
-## File Structure
-
-```
-app/
-├── @modal/                    # Parallel route slot
-│   ├── default.tsx            # Required! Returns null
-│   ├── (.)photos/             # Intercepts /photos/*
-│   │   └── [id]/
-│   │       └── page.tsx       # Modal content
-│   └── [...]catchall/         # Optional: catch unmatched
-│       └── page.tsx
-├── photos/
-│   └── [id]/
-│       └── page.tsx           # Full page (direct access)
-├── layout.tsx                 # Renders both children and @modal
-└── page.tsx
-```
-
-## Step 1: Root Layout with Slot
-
-```tsx
-// app/layout.tsx
-export default function RootLayout({
-  children,
-  modal,
-}: {
-  children: React.ReactNode;
-  modal: React.ReactNode;
-}) {
-  return (
-    <html>
-      <body>
-        {children}
-        {modal}
-      </body>
-    </html>
-  );
-}
-```
-
-## Step 2: Default File (Critical!)
-
-**Every parallel route slot MUST have a `default.tsx`** to prevent 404s on hard navigation.
-
-```tsx
-// app/@modal/default.tsx
-export default function Default() {
-  return null;
-}
-```
-
-Without this file, refreshing any page will 404 because Next.js can't determine what to render in the `@modal` slot.
-
-## Step 3: Intercepting Route (Modal)
-
-The `(.)` prefix intercepts routes at the same level.
-
-```tsx
-// app/@modal/(.)photos/[id]/page.tsx
-import { Modal } from '@/components/modal';
-
-export default async function PhotoModal({
-  params
-}: {
-  params: Promise<{ id: string }>
-}) {
-  const { id } = await params;
-  const photo = await getPhoto(id);
-
-  return (
-    <Modal>
-      <img src={photo.url} alt={photo.title} />
-    </Modal>
-  );
-}
-```
-
-## Step 4: Full Page (Direct Access)
-
-```tsx
-// app/photos/[id]/page.tsx
-export default async function PhotoPage({
-  params
-}: {
-  params: Promise<{ id: string }>
-}) {
-  const { id } = await params;
-  const photo = await getPhoto(id);
-
-  return (
-    <div className="full-page">
-      <img src={photo.url} alt={photo.title} />
-      <h1>{photo.title}</h1>
-    </div>
-  );
-}
-```
-
-## Step 5: Modal Component with Correct Closing
-
-**Critical: Use `router.back()` to close modals, NOT `router.push()` or `<Link>`.**
-
-```tsx
-// components/modal.tsx
-'use client';
-
-import { useRouter } from 'next/navigation';
-import { useCallback, useEffect, useRef } from 'react';
-
-export function Modal({ children }: { children: React.ReactNode }) {
-  const router = useRouter();
-  const overlayRef = useRef<HTMLDivElement>(null);
-
-  // Close on escape key
-  useEffect(() => {
-    function onKeyDown(e: KeyboardEvent) {
-      if (e.key === 'Escape') {
-        router.back(); // Correct
-      }
-    }
-    document.addEventListener('keydown', onKeyDown);
-    return () => document.removeEventListener('keydown', onKeyDown);
-  }, [router]);
-
-  // Close on overlay click
-  const handleOverlayClick = useCallback((e: React.MouseEvent) => {
-    if (e.target === overlayRef.current) {
-      router.back(); // Correct
-    }
-  }, [router]);
-
-  return (
-    <div
-      ref={overlayRef}
-      onClick={handleOverlayClick}
-      className="fixed inset-0 bg-black/50 flex items-center justify-center z-50"
-    >
-      <div className="bg-white rounded-lg p-6 max-w-2xl w-full mx-4">
-        <button
-          onClick={() => router.back()} // Correct!
-          className="absolute top-4 right-4"
-        >
-          Close
-        </button>
-        {children}
-      </div>
-    </div>
-  );
-}
-```
-
-### Why NOT `router.push('/')` or `<Link href="/">`?
-
-Using `push` or `Link` to "close" a modal:
-1. Adds a new history entry (back button shows modal again)
-2. Doesn't properly clear the intercepted route
-3. Can cause the modal to flash or persist unexpectedly
-
-`router.back()` correctly:
-1. Removes the intercepted route from history
-2. Returns to the previous page
-3. Properly unmounts the modal
-
-## Route Matcher Reference
-
-Matchers match **route segments**, not filesystem paths:
-
-| Matcher | Matches | Example |
-|---------|---------|---------|
-| `(.)` | Same level | `@modal/(.)photos` intercepts `/photos` |
-| `(..)` | One level up | `@modal/(..)settings` from `/dashboard/@modal` intercepts `/settings` |
-| `(..)(..)` | Two levels up | Rarely used |
-| `(...)` | From root | `@modal/(...)photos` intercepts `/photos` from anywhere |
-
-**Common mistake**: Thinking `(..)` means "parent folder" - it means "parent route segment".
-
-## Handling Hard Navigation
-
-When users directly visit `/photos/123` (bookmark, refresh, shared link):
-- The intercepting route is bypassed
-- The full `photos/[id]/page.tsx` renders
-- Modal doesn't appear (expected behavior)
-
-If you want the modal to appear on direct access too, you need additional logic:
-
-```tsx
-// app/photos/[id]/page.tsx
-import { Modal } from '@/components/modal';
-
-export default async function PhotoPage({ params }) {
-  const { id } = await params;
-  const photo = await getPhoto(id);
-
-  // Option: Render as modal on direct access too
-  return (
-    <Modal>
-      <img src={photo.url} alt={photo.title} />
-    </Modal>
-  );
-}
-```
-
-## Common Gotchas
-
-### 1. Missing `default.tsx` → 404 on Refresh
-
-Every `@slot` folder needs a `default.tsx` that returns `null` (or appropriate content).
-
-### 2. Modal Persists After Navigation
-
-You're using `router.push()` instead of `router.back()`.
-
-### 3. Nested Parallel Routes Need Defaults Too
-
-If you have `@modal` inside a route group, each level needs its own `default.tsx`:
-
-```
-app/
-├── (marketing)/
-│   ├── @modal/
-│   │   └── default.tsx     # Needed!
-│   └── layout.tsx
-└── layout.tsx
-```
-
-### 4. Intercepted Route Shows Wrong Content
-
-Check your matcher:
-- `(.)photos` intercepts `/photos` from the same route level
-- If your `@modal` is in `app/dashboard/@modal`, use `(.)photos` to intercept `/dashboard/photos`, not `/photos`
-
-### 5. TypeScript Errors with `params`
-
-In Next.js 15+, `params` is a Promise:
-
-```tsx
-// Correct
-export default async function Page({ params }: { params: Promise<{ id: string }> }) {
-  const { id } = await params;
-}
-```
-
-## Complete Example: Photo Gallery Modal
-
-```
-app/
-├── @modal/
-│   ├── default.tsx
-│   └── (.)photos/
-│       └── [id]/
-│           └── page.tsx
-├── photos/
-│   ├── page.tsx           # Gallery grid
-│   └── [id]/
-│       └── page.tsx       # Full photo page
-├── layout.tsx
-└── page.tsx
-```
-
-Links in the gallery:
-
-```tsx
-// app/photos/page.tsx
-import Link from 'next/link';
-
-export default async function Gallery() {
-  const photos = await getPhotos();
-
-  return (
-    <div className="grid grid-cols-3 gap-4">
-      {photos.map(photo => (
-        <Link key={photo.id} href={`/photos/${photo.id}`}>
-          <img src={photo.thumbnail} alt={photo.title} />
-        </Link>
-      ))}
-    </div>
-  );
-}
-```
-
-Clicking a photo → Modal opens (intercepted)
-Direct URL → Full page renders
-Refresh while modal open → Full page renders

.agents/skills/next-best-practices/route-handlers.md

@@ -1,146 +0,0 @@
-# Route Handlers
-
-Create API endpoints with `route.ts` files.
-
-## Basic Usage
-
-```tsx
-// app/api/users/route.ts
-export async function GET() {
-  const users = await getUsers()
-  return Response.json(users)
-}
-
-export async function POST(request: Request) {
-  const body = await request.json()
-  const user = await createUser(body)
-  return Response.json(user, { status: 201 })
-}
-```
-
-## Supported Methods
-
-`GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`
-
-## GET Handler Conflicts with page.tsx
-
-**A `route.ts` and `page.tsx` cannot coexist in the same folder.**
-
-```
-app/
-├── api/
-│   └── users/
-│       └── route.ts    # /api/users
-└── users/
-    ├── page.tsx        # /users (page)
-    └── route.ts        # Warning: Conflicts with page.tsx!
-```
-
-If you need both a page and an API at the same path, use different paths:
-
-```
-app/
-├── users/
-│   └── page.tsx        # /users (page)
-└── api/
-    └── users/
-        └── route.ts    # /api/users (API)
-```
-
-## Environment Behavior
-
-Route handlers run in a **Server Component-like environment**:
-
-- Yes: Can use `async/await`
-- Yes: Can access `cookies()`, `headers()`
-- Yes: Can use Node.js APIs
-- No: Cannot use React hooks
-- No: Cannot use React DOM APIs
-- No: Cannot use browser APIs
-
-```tsx
-// Bad: This won't work - no React DOM in route handlers
-import { renderToString } from 'react-dom/server'
-
-export async function GET() {
-  const html = renderToString(<Component />)  // Error!
-  return new Response(html)
-}
-```
-
-## Dynamic Route Handlers
-
-```tsx
-// app/api/users/[id]/route.ts
-export async function GET(
-  request: Request,
-  { params }: { params: Promise<{ id: string }> }
-) {
-  const { id } = await params
-  const user = await getUser(id)
-
-  if (!user) {
-    return Response.json({ error: 'Not found' }, { status: 404 })
-  }
-
-  return Response.json(user)
-}
-```
-
-## Request Helpers
-
-```tsx
-export async function GET(request: Request) {
-  // URL and search params
-  const { searchParams } = new URL(request.url)
-  const query = searchParams.get('q')
-
-  // Headers
-  const authHeader = request.headers.get('authorization')
-
-  // Cookies (Next.js helper)
-  const cookieStore = await cookies()
-  const token = cookieStore.get('token')
-
-  return Response.json({ query, token })
-}
-```
-
-## Response Helpers
-
-```tsx
-// JSON response
-return Response.json({ data })
-
-// With status
-return Response.json({ error: 'Not found' }, { status: 404 })
-
-// With headers
-return Response.json(data, {
-  headers: {
-    'Cache-Control': 'max-age=3600',
-  },
-})
-
-// Redirect
-return Response.redirect(new URL('/login', request.url))
-
-// Stream
-return new Response(stream, {
-  headers: { 'Content-Type': 'text/event-stream' },
-})
-```
-
-## When to Use Route Handlers vs Server Actions
-
-| Use Case | Route Handlers | Server Actions |
-|----------|----------------|----------------|
-| Form submissions | No | Yes |
-| Data mutations from UI | No | Yes |
-| Third-party webhooks | Yes | No |
-| External API consumption | Yes | No |
-| Public REST API | Yes | No |
-| File uploads | Both work | Both work |
-
-**Prefer Server Actions** for mutations triggered from your UI.
-**Use Route Handlers** for external integrations and public APIs.

.agents/skills/next-best-practices/rsc-boundaries.md

@@ -1,159 +0,0 @@
-# RSC Boundaries
-
-Detect and prevent invalid patterns when crossing Server/Client component boundaries.
-
-## Detection Rules
-
-### 1. Async Client Components Are Invalid
-
-Client components **cannot** be async functions. Only Server Components can be async.
-
-**Detect:** File has `'use client'` AND component is `async function` or returns `Promise`
-
-```tsx
-// Bad: async client component
-'use client'
-export default async function UserProfile() {
-  const user = await getUser() // Cannot await in client component
-  return <div>{user.name}</div>
-}
-
-// Good: Remove async, fetch data in parent server component
-// page.tsx (server component - no 'use client')
-export default async function Page() {
-  const user = await getUser()
-  return <UserProfile user={user} />
-}
-
-// UserProfile.tsx (client component)
-'use client'
-export function UserProfile({ user }: { user: User }) {
-  return <div>{user.name}</div>
-}
-```
-
-```tsx
-// Bad: async arrow function client component
-'use client'
-const Dashboard = async () => {
-  const data = await fetchDashboard()
-  return <div>{data}</div>
-}
-
-// Good: Fetch in server component, pass data down
-```
-
-### 2. Non-Serializable Props to Client Components
-
-Props passed from Server → Client must be JSON-serializable.
-
-**Detect:** Server component passes these to a client component:
-- Functions (except Server Actions with `'use server'`)
-- `Date` objects
-- `Map`, `Set`, `WeakMap`, `WeakSet`
-- Class instances
-- `Symbol` (unless globally registered)
-- Circular references
-
-```tsx
-// Bad: Function prop
-// page.tsx (server)
-export default function Page() {
-  const handleClick = () => console.log('clicked')
-  return <ClientButton onClick={handleClick} />
-}
-
-// Good: Define function inside client component
-// ClientButton.tsx
-'use client'
-export function ClientButton() {
-  const handleClick = () => console.log('clicked')
-  return <button onClick={handleClick}>Click</button>
-}
-```
-
-```tsx
-// Bad: Date object (silently becomes string, then crashes)
-// page.tsx (server)
-export default async function Page() {
-  const post = await getPost()
-  return <PostCard createdAt={post.createdAt} /> // Date object
-}
-
-// PostCard.tsx (client) - will crash on .getFullYear()
-'use client'
-export function PostCard({ createdAt }: { createdAt: Date }) {
-  return <span>{createdAt.getFullYear()}</span> // Runtime error!
-}
-
-// Good: Serialize to string on server
-// page.tsx (server)
-export default async function Page() {
-  const post = await getPost()
-  return <PostCard createdAt={post.createdAt.toISOString()} />
-}
-
-// PostCard.tsx (client)
-'use client'
-export function PostCard({ createdAt }: { createdAt: string }) {
-  const date = new Date(createdAt)
-  return <span>{date.getFullYear()}</span>
-}
-```
-
-```tsx
-// Bad: Class instance
-const user = new UserModel(data)
-<ClientProfile user={user} /> // Methods will be stripped
-
-// Good: Pass plain object
-const user = await getUser()
-<ClientProfile user={{ id: user.id, name: user.name }} />
-```
-
-```tsx
-// Bad: Map/Set
-<ClientComponent items={new Map([['a', 1]])} />
-
-// Good: Convert to array/object
-<ClientComponent items={Object.fromEntries(map)} />
-<ClientComponent items={Array.from(set)} />
-```
-
-### 3. Server Actions Are the Exception
-
-Functions marked with `'use server'` CAN be passed to client components.
-
-```tsx
-// Valid: Server Action can be passed
-// actions.ts
-'use server'
-export async function submitForm(formData: FormData) {
-  // server-side logic
-}
-
-// page.tsx (server)
-import { submitForm } from './actions'
-export default function Page() {
-  return <ClientForm onSubmit={submitForm} /> // OK!
-}
-
-// ClientForm.tsx (client)
-'use client'
-export function ClientForm({ onSubmit }: { onSubmit: (data: FormData) => Promise<void> }) {
-  return <form action={onSubmit}>...</form>
-}
-```
-
-## Quick Reference
-
-| Pattern | Valid? | Fix |
-|---------|--------|-----|
-| `'use client'` + `async function` | No | Fetch in server parent, pass data |
-| Pass `() => {}` to client | No | Define in client or use server action |
-| Pass `new Date()` to client | No | Use `.toISOString()` |
-| Pass `new Map()` to client | No | Convert to object/array |
-| Pass class instance to client | No | Pass plain object |
-| Pass server action to client | Yes | - |
-| Pass `string/number/boolean` | Yes | - |
-| Pass plain object/array | Yes | - |

.agents/skills/next-best-practices/runtime-selection.md

@@ -1,39 +0,0 @@
-# Runtime Selection
-
-## Use Node.js Runtime by Default
-
-Use the default Node.js runtime for new routes and pages. Only use Edge runtime if the project already uses it or there's a specific requirement.
-
-```tsx
-// Good: Default - no runtime config needed (uses Node.js)
-export default function Page() { ... }
-
-// Caution: Only if already used in project or specifically required
-export const runtime = 'edge'
-```
-
-## When to Use Each
-
-### Node.js Runtime (Default)
-
-- Full Node.js API support
-- File system access (`fs`)
-- Full `crypto` support
-- Database connections
-- Most npm packages work
-
-### Edge Runtime
-
-- Only for specific edge-location latency requirements
-- Limited API (no `fs`, limited `crypto`)
-- Smaller cold start
-- Geographic distribution needs
-
-## Detection
-
-**Before adding `runtime = 'edge'`**, check:
-1. Does the project already use Edge runtime?
-2. Is there a specific latency requirement?
-3. Are all dependencies Edge-compatible?
-
-If unsure, use Node.js runtime.

.agents/skills/next-best-practices/scripts.md

@@ -1,141 +0,0 @@
-# Scripts
-
-Loading third-party scripts in Next.js.
-
-## Use next/script
-
-Always use `next/script` instead of native `<script>` tags for better performance.
-
-```tsx
-// Bad: Native script tag
-<script src="https://example.com/script.js"></script>
-
-// Good: Next.js Script component
-import Script from 'next/script'
-
-<Script src="https://example.com/script.js" />
-```
-
-## Inline Scripts Need ID
-
-Inline scripts require an `id` attribute for Next.js to track them.
-
-```tsx
-// Bad: Missing id
-<Script dangerouslySetInnerHTML={{ __html: 'console.log("hi")' }} />
-
-// Good: Has id
-<Script id="my-script" dangerouslySetInnerHTML={{ __html: 'console.log("hi")' }} />
-
-// Good: Inline with id
-<Script id="show-banner">
-  {`document.getElementById('banner').classList.remove('hidden')`}
-</Script>
-```
-
-## Don't Put Script in Head
-
-`next/script` should not be placed inside `next/head`. It handles its own positioning.
-
-```tsx
-// Bad: Script inside Head
-import Head from 'next/head'
-import Script from 'next/script'
-
-<Head>
-  <Script src="/analytics.js" />
-</Head>
-
-// Good: Script outside Head
-<Head>
-  <title>Page</title>
-</Head>
-<Script src="/analytics.js" />
-```
-
-## Loading Strategies
-
-```tsx
-// afterInteractive (default) - Load after page is interactive
-<Script src="/analytics.js" strategy="afterInteractive" />
-
-// lazyOnload - Load during idle time
-<Script src="/widget.js" strategy="lazyOnload" />
-
-// beforeInteractive - Load before page is interactive (use sparingly)
-// Only works in app/layout.tsx or pages/_document.js
-<Script src="/critical.js" strategy="beforeInteractive" />
-
-// worker - Load in web worker (experimental)
-<Script src="/heavy.js" strategy="worker" />
-```
-
-## Google Analytics
-
-Use `@next/third-parties` instead of inline GA scripts.
-
-```tsx
-// Bad: Inline GA script
-<Script src="https://www.googletagmanager.com/gtag/js?id=G-XXXXX" />
-<Script id="ga-init">
-  {`window.dataLayer = window.dataLayer || [];
-    function gtag(){dataLayer.push(arguments);}
-    gtag('js', new Date());
-    gtag('config', 'G-XXXXX');`}
-</Script>
-
-// Good: Next.js component
-import { GoogleAnalytics } from '@next/third-parties/google'
-
-export default function Layout({ children }) {
-  return (
-    <html>
-      <body>{children}</body>
-      <GoogleAnalytics gaId="G-XXXXX" />
-    </html>
-  )
-}
-```
-
-## Google Tag Manager
-
-```tsx
-import { GoogleTagManager } from '@next/third-parties/google'
-
-export default function Layout({ children }) {
-  return (
-    <html>
-      <GoogleTagManager gtmId="GTM-XXXXX" />
-      <body>{children}</body>
-    </html>
-  )
-}
-```
-
-## Other Third-Party Scripts
-
-```tsx
-// YouTube embed
-import { YouTubeEmbed } from '@next/third-parties/google'
-
-<YouTubeEmbed videoid="dQw4w9WgXcQ" />
-
-// Google Maps
-import { GoogleMapsEmbed } from '@next/third-parties/google'
-
-<GoogleMapsEmbed
-  apiKey="YOUR_API_KEY"
-  mode="place"
-  q="Brooklyn+Bridge,New+York,NY"
-/>
-```
-
-## Quick Reference
-
-| Pattern | Issue | Fix |
-|---------|-------|-----|
-| `<script src="...">` | No optimization | Use `next/script` |
-| `<Script>` without id | Can't track inline scripts | Add `id` attribute |
-| `<Script>` inside `<Head>` | Wrong placement | Move outside Head |
-| Inline GA/GTM scripts | No optimization | Use `@next/third-parties` |
-| `strategy="beforeInteractive"` outside layout | Won't work | Only use in root layout |

.agents/skills/next-best-practices/self-hosting.md

@@ -1,371 +0,0 @@
-# Self-Hosting Next.js
-
-Deploy Next.js outside of Vercel with confidence.
-
-## Quick Start: Standalone Output
-
-For Docker or any containerized deployment, use standalone output:
-
-```js
-// next.config.js
-module.exports = {
-  output: 'standalone',
-};
-```
-
-This creates a minimal `standalone` folder with only production dependencies:
-
-```
-.next/
-├── standalone/
-│   ├── server.js          # Entry point
-│   ├── node_modules/      # Only production deps
-│   └── .next/             # Build output
-└── static/                # Must be copied separately
-```
-
-## Docker Deployment
-
-### Dockerfile
-
-```dockerfile
-FROM node:20-alpine AS base
-
-# Install dependencies
-FROM base AS deps
-WORKDIR /app
-COPY package.json package-lock.json* ./
-RUN npm ci
-
-# Build
-FROM base AS builder
-WORKDIR /app
-COPY --from=deps /app/node_modules ./node_modules
-COPY . .
-RUN npm run build
-
-# Production
-FROM base AS runner
-WORKDIR /app
-
-ENV NODE_ENV=production
-
-# Create non-root user
-RUN addgroup --system --gid 1001 nodejs
-RUN adduser --system --uid 1001 nextjs
-
-# Copy standalone output
-COPY --from=builder /app/.next/standalone ./
-COPY --from=builder /app/.next/static ./.next/static
-COPY --from=builder /app/public ./public
-
-USER nextjs
-
-EXPOSE 3000
-ENV PORT=3000
-ENV HOSTNAME="0.0.0.0"
-
-CMD ["node", "server.js"]
-```
-
-### Docker Compose
-
-```yaml
-version: '3.8'
-
-services:
-  web:
-    build: .
-    ports:
-      - "3000:3000"
-    environment:
-      - NODE_ENV=production
-    restart: unless-stopped
-    healthcheck:
-      test: ["CMD", "wget", "-q", "--spider", "http://localhost:3000/api/health"]
-      interval: 30s
-      timeout: 10s
-      retries: 3
-```
-
-## PM2 Deployment
-
-For traditional server deployments:
-
-```js
-// ecosystem.config.js
-module.exports = {
-  apps: [{
-    name: 'nextjs',
-    script: '.next/standalone/server.js',
-    instances: 'max',
-    exec_mode: 'cluster',
-    env: {
-      NODE_ENV: 'production',
-      PORT: 3000,
-    },
-  }],
-};
-```
-
-```bash
-npm run build
-pm2 start ecosystem.config.js
-```
-
-## ISR and Cache Handlers
-
-### The Problem
-
-ISR (Incremental Static Regeneration) uses filesystem caching by default. This **breaks with multiple instances**:
-
-- Instance A regenerates page → saves to its local disk
-- Instance B serves stale page → doesn't see Instance A's cache
-- Load balancer sends users to random instances → inconsistent content
-
-### Solution: Custom Cache Handler
-
-Next.js 14+ supports custom cache handlers for shared storage:
-
-```js
-// next.config.js
-module.exports = {
-  cacheHandler: require.resolve('./cache-handler.js'),
-  cacheMaxMemorySize: 0, // Disable in-memory cache
-};
-```
-
-#### Redis Cache Handler Example
-
-```js
-// cache-handler.js
-const Redis = require('ioredis');
-
-const redis = new Redis(process.env.REDIS_URL);
-const CACHE_PREFIX = 'nextjs:';
-
-module.exports = class CacheHandler {
-  constructor(options) {
-    this.options = options;
-  }
-
-  async get(key) {
-    const data = await redis.get(CACHE_PREFIX + key);
-    if (!data) return null;
-
-    const parsed = JSON.parse(data);
-    return {
-      value: parsed.value,
-      lastModified: parsed.lastModified,
-    };
-  }
-
-  async set(key, data, ctx) {
-    const cacheData = {
-      value: data,
-      lastModified: Date.now(),
-    };
-
-    // Set TTL based on revalidate option
-    if (ctx?.revalidate) {
-      await redis.setex(
-        CACHE_PREFIX + key,
-        ctx.revalidate,
-        JSON.stringify(cacheData)
-      );
-    } else {
-      await redis.set(CACHE_PREFIX + key, JSON.stringify(cacheData));
-    }
-  }
-
-  async revalidateTag(tags) {
-    // Implement tag-based invalidation
-    // This requires tracking which keys have which tags
-  }
-};
-```
-
-#### S3 Cache Handler Example
-
-```js
-// cache-handler.js
-const { S3Client, GetObjectCommand, PutObjectCommand } = require('@aws-sdk/client-s3');
-
-const s3 = new S3Client({ region: process.env.AWS_REGION });
-const BUCKET = process.env.CACHE_BUCKET;
-
-module.exports = class CacheHandler {
-  async get(key) {
-    try {
-      const response = await s3.send(new GetObjectCommand({
-        Bucket: BUCKET,
-        Key: `cache/${key}`,
-      }));
-      const body = await response.Body.transformToString();
-      return JSON.parse(body);
-    } catch (err) {
-      if (err.name === 'NoSuchKey') return null;
-      throw err;
-    }
-  }
-
-  async set(key, data, ctx) {
-    await s3.send(new PutObjectCommand({
-      Bucket: BUCKET,
-      Key: `cache/${key}`,
-      Body: JSON.stringify({
-        value: data,
-        lastModified: Date.now(),
-      }),
-      ContentType: 'application/json',
-    }));
-  }
-};
-```
-
-## What Works vs What Needs Setup
-
-| Feature | Single Instance | Multi-Instance | Notes |
-|---------|----------------|----------------|-------|
-| SSR | Yes | Yes | No special setup |
-| SSG | Yes | Yes | Built at deploy time |
-| ISR | Yes | Needs cache handler | Filesystem cache breaks |
-| Image Optimization | Yes | Yes | CPU-intensive, consider CDN |
-| Middleware | Yes | Yes | Runs on Node.js |
-| Edge Runtime | Limited | Limited | Some features Node-only |
-| `revalidatePath/Tag` | Yes | Needs cache handler | Must share cache |
-| `next/font` | Yes | Yes | Fonts bundled at build |
-| Draft Mode | Yes | Yes | Cookie-based |
-
-## Image Optimization
-
-Next.js Image Optimization works out of the box but is CPU-intensive.
-
-### Option 1: Built-in (Simple)
-
-Works automatically, but consider:
-- Set `deviceSizes` and `imageSizes` in config to limit variants
-- Use `minimumCacheTTL` to reduce regeneration
-
-```js
-// next.config.js
-module.exports = {
-  images: {
-    minimumCacheTTL: 60 * 60 * 24, // 24 hours
-    deviceSizes: [640, 750, 1080, 1920], // Limit sizes
-  },
-};
-```
-
-### Option 2: External Loader (Recommended for Scale)
-
-Offload to Cloudinary, Imgix, or similar:
-
-```js
-// next.config.js
-module.exports = {
-  images: {
-    loader: 'custom',
-    loaderFile: './lib/image-loader.js',
-  },
-};
-```
-
-```js
-// lib/image-loader.js
-export default function cloudinaryLoader({ src, width, quality }) {
-  const params = ['f_auto', 'c_limit', `w_${width}`, `q_${quality || 'auto'}`];
-  return `https://res.cloudinary.com/demo/image/upload/${params.join(',')}${src}`;
-}
-```
-
-## Environment Variables
-
-### Build-time vs Runtime
-
-```js
-// Available at build time only (baked into bundle)
-NEXT_PUBLIC_API_URL=https://api.example.com
-
-// Available at runtime (server-side only)
-DATABASE_URL=postgresql://...
-API_SECRET=...
-```
-
-### Runtime Configuration
-
-For truly dynamic config, don't use `NEXT_PUBLIC_*`. Instead:
-
-```tsx
-// app/api/config/route.ts
-export async function GET() {
-  return Response.json({
-    apiUrl: process.env.API_URL,
-    features: process.env.FEATURES?.split(','),
-  });
-}
-```
-
-## OpenNext: Serverless Without Vercel
-
-[OpenNext](https://open-next.js.org/) adapts Next.js for AWS Lambda, Cloudflare Workers, etc.
-
-```bash
-npx create-sst@latest
-# or
-npx @opennextjs/aws build
-```
-
-Supports:
-- AWS Lambda + CloudFront
-- Cloudflare Workers
-- Netlify Functions
-- Deno Deploy
-
-## Health Check Endpoint
-
-Always include a health check for load balancers:
-
-```tsx
-// app/api/health/route.ts
-export async function GET() {
-  try {
-    // Optional: check database connection
-    // await db.$queryRaw`SELECT 1`;
-
-    return Response.json({ status: 'healthy' }, { status: 200 });
-  } catch (error) {
-    return Response.json({ status: 'unhealthy' }, { status: 503 });
-  }
-}
-```
-
-## Pre-Deployment Checklist
-
-1. **Build locally first**: `npm run build` - catch errors before deploy
-2. **Test standalone output**: `node .next/standalone/server.js`
-3. **Set `output: 'standalone'`** for Docker
-4. **Configure cache handler** for multi-instance ISR
-5. **Set `HOSTNAME="0.0.0.0"`** for containers
-6. **Copy `public/` and `.next/static/`** - not included in standalone
-7. **Add health check endpoint**
-8. **Test ISR revalidation** after deployment
-9. **Monitor memory usage** - Node.js defaults may need tuning
-
-## Testing Cache Handler
-
-**Critical**: Test your cache handler on every Next.js upgrade:
-
-```bash
-# Start multiple instances
-PORT=3001 node .next/standalone/server.js &
-PORT=3002 node .next/standalone/server.js &
-
-# Trigger ISR revalidation
-curl http://localhost:3001/api/revalidate?path=/posts
-
-# Verify both instances see the update
-curl http://localhost:3001/posts
-curl http://localhost:3002/posts
-# Should return identical content
-```

.agents/skills/next-best-practices/suspense-boundaries.md

@@ -1,67 +0,0 @@
-# Suspense Boundaries
-
-Client hooks that cause CSR bailout without Suspense boundaries.
-
-## useSearchParams
-
-Always requires Suspense boundary in static routes. Without it, the entire page becomes client-side rendered.
-
-```tsx
-// Bad: Entire page becomes CSR
-'use client'
-
-import { useSearchParams } from 'next/navigation'
-
-export default function SearchBar() {
-  const searchParams = useSearchParams()
-  return <div>Query: {searchParams.get('q')}</div>
-}
-```
-
-```tsx
-// Good: Wrap in Suspense
-import { Suspense } from 'react'
-import SearchBar from './search-bar'
-
-export default function Page() {
-  return (
-    <Suspense fallback={<div>Loading...</div>}>
-      <SearchBar />
-    </Suspense>
-  )
-}
-```
-
-## usePathname
-
-Requires Suspense boundary when route has dynamic parameters.
-
-```tsx
-// In dynamic route [slug]
-// Bad: No Suspense
-'use client'
-import { usePathname } from 'next/navigation'
-
-export function Breadcrumb() {
-  const pathname = usePathname()
-  return <nav>{pathname}</nav>
-}
-```
-
-```tsx
-// Good: Wrap in Suspense
-<Suspense fallback={<BreadcrumbSkeleton />}>
-  <Breadcrumb />
-</Suspense>
-```
-
-If you use `generateStaticParams`, Suspense is optional.
-
-## Quick Reference
-
-| Hook | Suspense Required |
-|------|-------------------|
-| `useSearchParams()` | Yes |
-| `usePathname()` | Yes (dynamic routes) |
-| `useParams()` | No |
-| `useRouter()` | No |

.agents/skills/speckit.checker/SKILL.md

@@ -1,154 +0,0 @@
----
-name: speckit.checker
-description: Run static analysis tools and aggregate results.
-version: 1.0.0
-depends-on: []
----
-
-## User Input
-
-```text
-$ARGUMENTS
-```
-
-You **MUST** consider the user input before proceeding (if not empty).
-
-## Role
-
-You are the **Antigravity Static Analyzer**. Your role is to run all applicable static analysis tools and provide a unified report of issues.
-
-## Task
-
-### Outline
-
-Auto-detect available tools, run them, and aggregate results into a prioritized report.
-
-### Execution Steps
-
-1. **Detect Project Type and Tools**:
-   ```bash
-   # Check for config files
-   ls -la | grep -E "(package.json|pyproject.toml|go.mod|Cargo.toml|pom.xml)"
-   
-   # Check for linter configs
-   ls -la | grep -E "(eslint|prettier|pylint|golangci|rustfmt)"
-   ```
-
-   | Config | Tools to Run |
-   |--------|-------------|
-   | `package.json` | ESLint, TypeScript, npm audit |
-   | `pyproject.toml` | Pylint/Ruff, mypy, bandit |
-   | `go.mod` | golangci-lint, go vet |
-   | `Cargo.toml` | clippy, cargo audit |
-   | `pom.xml` | SpotBugs, PMD |
-
-2. **Run Linting**:
-   
-   | Stack | Command |
-   |-------|---------|
-   | Node/TS | `npx eslint . --format json 2>/dev/null` |
-   | Python | `ruff check . --output-format json 2>/dev/null || pylint --output-format=json **/*.py` |
-   | Go | `golangci-lint run --out-format json` |
-   | Rust | `cargo clippy --message-format=json` |
-
-3. **Run Type Checking**:
-   
-   | Stack | Command |
-   |-------|---------|
-   | TypeScript | `npx tsc --noEmit 2>&1` |
-   | Python | `mypy . --no-error-summary 2>&1` |
-   | Go | `go build ./... 2>&1` (types are built-in) |
-
-4. **Run Security Scanning**:
-   
-   | Stack | Command |
-   |-------|---------|
-   | Node | `npm audit --json` |
-   | Python | `bandit -r . -f json 2>/dev/null || safety check --json` |
-   | Go | `govulncheck ./... 2>&1` |
-   | Rust | `cargo audit --json` |
-
-5. **Aggregate and Prioritize**:
-   
-   | Category | Priority |
-   |----------|----------|
-   | Security (Critical/High) | 🔴 P1 |
-   | Type Errors | 🟠 P2 |
-   | Security (Medium/Low) | 🟡 P3 |
-   | Lint Errors | 🟡 P3 |
-   | Lint Warnings | 🟢 P4 |
-   | Style Issues | ⚪ P5 |
-
-6. **Generate Report**:
-   ```markdown
-   # Static Analysis Report
-   
-   **Date**: [timestamp]
-   **Project**: [name from package.json/pyproject.toml]
-   **Status**: CLEAN | ISSUES FOUND
-   
-   ## Tools Run
-   
-   | Tool | Status | Issues |
-   |------|--------|--------|
-   | ESLint | ✅ | 12 |
-   | TypeScript | ✅ | 3 |
-   | npm audit | ⚠️ | 2 vulnerabilities |
-   
-   ## Summary by Priority
-   
-   | Priority | Count |
-   |----------|-------|
-   | 🔴 P1 Critical | X |
-   | 🟠 P2 High | X |
-   | 🟡 P3 Medium | X |
-   | 🟢 P4 Low | X |
-   
-   ## Issues
-   
-   ### 🔴 P1: Security Vulnerabilities
-   
-   | Package | Severity | Issue | Fix |
-   |---------|----------|-------|-----|
-   | lodash | HIGH | Prototype Pollution | Upgrade to 4.17.21 |
-   
-   ### 🟠 P2: Type Errors
-   
-   | File | Line | Error |
-   |------|------|-------|
-   | src/api.ts | 45 | Type 'string' is not assignable to type 'number' |
-   
-   ### 🟡 P3: Lint Issues
-   
-   | File | Line | Rule | Message |
-   |------|------|------|---------|
-   | src/utils.ts | 12 | no-unused-vars | 'foo' is defined but never used |
-   
-   ## Quick Fixes
-   
-   ```bash
-   # Fix security issues
-   npm audit fix
-   
-   # Auto-fix lint issues
-   npx eslint . --fix
-   ```
-   
-   ## Recommendations
-   
-   1. **Immediate**: Fix P1 security issues
-   2. **Before merge**: Fix P2 type errors
-   3. **Tech debt**: Address P3/P4 lint issues
-   ```
-
-7. **Output**:
-   - Display report
-   - Exit with non-zero if P1 or P2 issues exist
-
-## Operating Principles
-
-- **Run Everything**: Don't skip tools, aggregate all results
-- **Be Fast**: Run tools in parallel when possible
-- **Be Actionable**: Every issue should have a clear fix path
-- **Don't Duplicate**: Dedupe issues found by multiple tools
-- **Respect Configs**: Honor project's existing linter configs

.agents/skills/speckit.checklist/templates/checklist-template.md

@@ -1,40 +0,0 @@
-# [CHECKLIST TYPE] Checklist: [FEATURE NAME]
-
-**Purpose**: [Brief description of what this checklist covers]
-**Created**: [DATE]
-**Feature**: [Link to spec.md or relevant documentation]
-
-**Note**: This checklist is generated by the `/speckit.checklist` command based on feature context and requirements.
-
-<!-- 
-  ============================================================================
-  IMPORTANT: The checklist items below are SAMPLE ITEMS for illustration only.
-  
-  The /speckit.checklist command MUST replace these with actual items based on:
-  - User's specific checklist request
-  - Feature requirements from spec.md
-  - Technical context from plan.md
-  - Implementation details from tasks.md
-  
-  DO NOT keep these sample items in the generated checklist file.
-  ============================================================================
--->
-
-## [Category 1]
-
-- [ ] CHK001 First checklist item with clear action
-- [ ] CHK002 Second checklist item
-- [ ] CHK003 Third checklist item
-
-## [Category 2]
-
-- [ ] CHK004 Another category item
-- [ ] CHK005 Item with specific criteria
-- [ ] CHK006 Final item in this category
-
-## Notes
-
-- Check items off as completed: `[x]`
-- Add comments or findings inline
-- Link to relevant resources or documentation
-- Items are numbered sequentially for easy reference

.agents/skills/speckit.diff/SKILL.md

@@ -1,81 +0,0 @@
----
-name: speckit.diff
-description: Compare two versions of a spec or plan to highlight changes.
-version: 1.0.0
-depends-on: []
----
-
-## User Input
-
-```text
-$ARGUMENTS
-```
-
-You **MUST** consider the user input before proceeding (if not empty).
-
-## Role
-
-You are the **Antigravity Diff Analyst**. Your role is to compare specification/plan versions and produce clear, actionable change summaries.
-
-## Task
-
-### Outline
-
-Compare two versions of a specification artifact and produce a structured diff report.
-
-### Execution Steps
-
-1. **Parse Arguments**:
-   - If user provides two file paths: Compare those files directly
-   - If user provides one file path: Compare current version with git HEAD
-   - If no arguments: Use `check-prerequisites.sh` to find current feature's spec.md and compare with HEAD
-
-2. **Load Files**:
-   ```bash
-   # For git comparison
-   git show HEAD:<relative-path> > /tmp/old_version.md
-   ```
-   - Read both versions into memory
-
-3. **Semantic Diff Analysis**:
-   Analyze changes by section:
-   - **Added**: New sections, requirements, or criteria
-   - **Removed**: Deleted content
-   - **Modified**: Changed wording or values
-   - **Moved**: Reorganized content (same meaning, different location)
-
-4. **Generate Report**:
-   ```markdown
-   # Diff Report: [filename]
-   
-   **Compared**: [version A] → [version B]
-   **Date**: [timestamp]
-   
-   ## Summary
-   - X additions, Y removals, Z modifications
-   
-   ## Changes by Section
-   
-   ### [Section Name]
-   
-   | Type | Content | Impact |
-   |------|---------|--------|
-   | + Added | [new text] | [what this means] |
-   | - Removed | [old text] | [what this means] |
-   | ~ Modified | [before] → [after] | [what this means] |
-   
-   ## Risk Assessment
-   - Breaking changes: [list any]
-   - Scope changes: [list any]
-   ```
-
-5. **Output**:
-   - Display report in terminal (do NOT write to file unless requested)
-   - Offer to save report to `FEATURE_DIR/diffs/[timestamp].md`
-
-## Operating Principles
-
-- **Be Precise**: Quote exact text changes
-- **Highlight Impact**: Explain what each change means for implementation
-- **Flag Breaking Changes**: Any change that invalidates existing work
-- **Ignore Whitespace**: Focus on semantic changes, not formatting

.agents/skills/speckit.implement/SKILL.md

@@ -1,248 +0,0 @@
----
-name: speckit.implement
-description: Execute the implementation plan by processing and executing all tasks defined in tasks.md (with Ironclad Anti-Regression Protocols)
-version: 1.0.0
-depends-on:
-  - speckit.tasks
----
-
-## User Input
-
-```text
-$ARGUMENTS
-```
-
-You **MUST** consider the user input before proceeding (if not empty).
-
-## Role
-
-You are the **Antigravity Master Builder**. Your role is to execute the implementation plan with precision, processing tasks from `tasks.md` and ensuring that the final codebase aligns perfectly with the specification, plan, and quality standards.
-
-**CORE OBJECTIVE:** Fix bugs and implement features with **ZERO REGRESSION**.
-**YOUR MOTTO:** "Measure twice, cut once. If you can't prove it's broken, don't fix it."
-
----
-
-## 🛡️ IRONCLAD PROTOCOLS (Non-Negotiable)
-
-These protocols MUST be followed for EVERY task before any production code modification:
-
-### Protocol 1: Blast Radius Analysis
-
-**BEFORE** writing a single line of production code modification, you MUST:
-
-1.  **Read**: Read the target file(s) to understand current implementation.
-2.  **Trace**: Use `grep` or search tools to find ALL other files importing or using the function/class you intend to modify.
-3.  **Report**: Output a precise list:
-    ```
-    🔍 BLAST RADIUS ANALYSIS
-    ─────────────────────────
-    Modifying: `[Function/Class X]` in `[file.ts]`
-    Affected files: [A.ts, B.ts, C.ts]
-    Risk Level: [LOW (<3 files) | MEDIUM (3-5 files) | HIGH (>5 files)]
-    ```
-4.  **Decide**: If > 2 files are affected, **DO NOT MODIFY inline**. Trigger **Protocol 2 (Strangler Pattern)**.
-
-### Protocol 2: Strangler Pattern (Immutable Core)
-
-If a file is critical, complex, or has high dependencies (>2 affected files):
-
-1.  **DO NOT EDIT** the existing function inside the old file.
-2.  **CREATE** a new file/module (e.g., `feature_v2.ts` or `utils_patch.ts`).
-3.  **IMPLEMENT** the improved logic there.
-4.  **SWITCH** the imports in the consuming files one by one.
-5.  **ANNOUNCE**: "Applying Strangler Pattern to avoid regression."
-
-*Benefit: If it breaks, we simply revert the import, not the whole logic.*
-
-### Protocol 3: Reproduction Script First (TDD)
-
-You are **FORBIDDEN** from fixing a bug or implementing a feature without evidence:
-
-1.  Create a temporary script `repro_task_[id].ts` (or .js/.py/.go based on stack).
-2.  This script MUST:
-    - For bugs: **FAIL** when run against the current code (demonstrating the bug).
-    - For features: **FAIL** when run against current code (feature doesn't exist).
-3.  Run it and show the failure output.
-4.  **ONLY THEN**, implement the fix/feature.
-5.  Run the script again to prove it passes.
-6.  Delete the temporary script OR convert it to a permanent test.
-
-### Protocol 4: Context Anchoring
-
-At the start of execution and after every 3 modifications:
-
-1.  Run `tree -L 2` (or equivalent) to visualize the file structure.
-2.  Update `ARCHITECTURE.md` if it exists, or create it to reflect the current reality.
-
----
-
-## Task Execution
-
-### Outline
-
-1. Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\\''m Groot' (or double-quote if possible: "I'm Groot").
-
-2. **Check checklists status** (if FEATURE_DIR/checklists/ exists):
-   - Scan all checklist files in the checklists/ directory
-   - For each checklist, count:
-     - Total items: All lines matching `- [ ]` or `- [X]` or `- [x]`
-     - Completed items: Lines matching `- [X]` or `- [x]`
-     - Incomplete items: Lines matching `- [ ]`
-   - Create a status table:
-
-     ```text
-     | Checklist | Total | Completed | Incomplete | Status |
-     |-----------|-------|-----------|------------|--------|
-     | ux.md     | 12    | 12        | 0          | ✓ PASS |
-     | test.md   | 8     | 5         | 3          | ✗ FAIL |
-     | security.md | 6   | 6         | 0          | ✓ PASS |
-     ```
-
-   - Calculate overall status:
-     - **PASS**: All checklists have 0 incomplete items
-     - **FAIL**: One or more checklists have incomplete items
-
-   - **If any checklist is incomplete**:
-     - Display the table with incomplete item counts
-     - **STOP** and ask: "Some checklists are incomplete. Do you want to proceed with implementation anyway? (yes/no)"
-     - Wait for user response before continuing
-     - If user says "no" or "wait" or "stop", halt execution
-     - If user says "yes" or "proceed" or "continue", proceed to step 3
-
-   - **If all checklists are complete**:
-     - Display the table showing all checklists passed
-     - Automatically proceed to step 3
-
-3. Load and analyze the implementation context:
-   - **REQUIRED**: Read tasks.md for the complete task list and execution plan
-   - **REQUIRED**: Read plan.md for tech stack, architecture, and file structure
-   - **IF EXISTS**: Read data-model.md for entities and relationships
-   - **IF EXISTS**: Read contracts/ for API specifications and test requirements
-   - **IF EXISTS**: Read research.md for technical decisions and constraints
-   - **IF EXISTS**: Read quickstart.md for integration scenarios
-
-4. **Context Anchoring (Protocol 4)**:
-   - Run `tree -L 2` to visualize the current file structure
-   - Document the initial state before any modifications
-
-5. **Project Setup Verification**:
-   - **REQUIRED**: Create/verify ignore files based on actual project setup:
-
-   **Detection & Creation Logic**:
-   - Check if the following command succeeds to determine if the repository is a git repo (create/verify .gitignore if so):
-
-     ```sh
-     git rev-parse --git-dir 2>/dev/null
-     ```
-
-   - Check if Dockerfile* exists or Docker in plan.md → create/verify .dockerignore
-   - Check if .eslintrc* exists → create/verify .eslintignore
-   - Check if eslint.config.* exists → ensure the config's `ignores` entries cover required patterns
-   - Check if .prettierrc* exists → create/verify .prettierignore
-   - Check if .npmrc or package.json exists → create/verify .npmignore (if publishing)
-   - Check if terraform files (*.tf) exist → create/verify .terraformignore
-   - Check if .helmignore needed (helm charts present) → create/verify .helmignore
-
-   **If ignore file already exists**: Verify it contains essential patterns, append missing critical patterns only
-   **If ignore file missing**: Create with full pattern set for detected technology
-
-   **Common Patterns by Technology** (from plan.md tech stack):
-   - **Node.js/JavaScript/TypeScript**: `node_modules/`, `dist/`, `build/`, `*.log`, `.env*`
-   - **Python**: `__pycache__/`, `*.pyc`, `.venv/`, `venv/`, `dist/`, `*.egg-info/`
-   - **Java**: `target/`, `*.class`, `*.jar`, `.gradle/`, `build/`
-   - **C#/.NET**: `bin/`, `obj/`, `*.user`, `*.suo`, `packages/`
-   - **Go**: `*.exe`, `*.test`, `vendor/`, `*.out`
-   - **Ruby**: `.bundle/`, `log/`, `tmp/`, `*.gem`, `vendor/bundle/`
-   - **PHP**: `vendor/`, `*.log`, `*.cache`, `*.env`
-   - **Rust**: `target/`, `debug/`, `release/`, `*.rs.bk`, `*.rlib`, `*.prof*`, `.idea/`, `*.log`, `.env*`
-   - **Kotlin**: `build/`, `out/`, `.gradle/`, `.idea/`, `*.class`, `*.jar`, `*.iml`, `*.log`, `.env*`
-   - **C++**: `build/`, `bin/`, `obj/`, `out/`, `*.o`, `*.so`, `*.a`, `*.exe`, `*.dll`, `.idea/`, `*.log`, `.env*`
-   - **C**: `build/`, `bin/`, `obj/`, `out/`, `*.o`, `*.a`, `*.so`, `*.exe`, `Makefile`, `config.log`, `.idea/`, `*.log`, `.env*`
-   - **Swift**: `.build/`, `DerivedData/`, `*.swiftpm/`, `Packages/`
-   - **R**: `.Rproj.user/`, `.Rhistory`, `.RData`, `.Ruserdata`, `*.Rproj`, `packrat/`, `renv/`
-   - **Universal**: `.DS_Store`, `Thumbs.db`, `*.tmp`, `*.swp`, `.vscode/`, `.idea/`
-
-   **Tool-Specific Patterns**:
-   - **Docker**: `node_modules/`, `.git/`, `Dockerfile*`, `.dockerignore`, `*.log*`, `.env*`, `coverage/`
-   - **ESLint**: `node_modules/`, `dist/`, `build/`, `coverage/`, `*.min.js`
-   - **Prettier**: `node_modules/`, `dist/`, `build/`, `coverage/`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`
-   - **Terraform**: `.terraform/`, `*.tfstate*`, `*.tfvars`, `.terraform.lock.hcl`
-   - **Kubernetes/k8s**: `*.secret.yaml`, `secrets/`, `.kube/`, `kubeconfig*`, `*.key`, `*.crt`
-
-6. Parse tasks.md structure and extract:
-   - **Task phases**: Setup, Tests, Core, Integration, Polish
-   - **Task dependencies**: Sequential vs parallel execution rules
-   - **Task details**: ID, description, file paths, parallel markers [P]
-   - **Execution flow**: Order and dependency requirements
-
-7. **Execute implementation following the task plan with Ironclad Protocols**:
-
-   **For EACH task**, follow this sequence:
-   
-   a. **Blast Radius Analysis (Protocol 1)**:
-      - Identify all files that will be modified
-      - Run `grep` to find all dependents
-      - Report the blast radius
-   
-   b. **Strategy Decision**:
-      - If LOW risk (≤2 affected files): Proceed with inline modification
-      - If MEDIUM/HIGH risk (>2 files): Apply Strangler Pattern (Protocol 2)
-   
-   c. **Reproduction Script (Protocol 3)**:
-      - Create `repro_task_[ID].ts` that demonstrates expected behavior
-      - Run it to confirm current state (should fail for new features, or fail for bugs)
-   
-   d. **Implementation**:
-      - Execute the task according to plan
-      - **Phase-by-phase execution**: Complete each phase before moving to the next
-      - **Respect dependencies**: Run sequential tasks in order, parallel tasks [P] can run together
-      - **Follow TDD approach**: Execute test tasks before their corresponding implementation tasks
-      - **File-based coordination**: Tasks affecting the same files must run sequentially
-   
-   e. **Verification**:
-      - Run the reproduction script again (should now pass)
-      - Run existing tests to ensure no regression
-      - If any test fails: **STOP** and report the regression
-   
-   f. **Cleanup**:
-      - Delete temporary repro scripts OR convert to permanent tests
-      - Mark task as complete `[X]` in tasks.md
-
-8. **Progress tracking and error handling**:
-   - Report progress after each completed task with this format:
-     ```
-     ✅ TASK [ID] COMPLETE
-     ─────────────────────
-     Modified files: [list]
-     Tests passed: [count]
-     Blast radius: [LOW/MEDIUM/HIGH]
-     ```
-   - Halt execution if any non-parallel task fails
-   - For parallel tasks [P], continue with successful tasks, report failed ones
-   - Provide clear error messages with context for debugging
-   - Suggest next steps if implementation cannot proceed
-   - **IMPORTANT** For completed tasks, make sure to mark the task off as [X] in the tasks file.
-
-9. **Context Re-anchoring (every 3 tasks)**:
-   - Run `tree -L 2` to verify file structure
-   - Update ARCHITECTURE.md if structure has changed
-
-10. **Completion validation**:
-    - Verify all required tasks are completed
-    - Check that implemented features match the original specification
-    - Validate that tests pass and coverage meets requirements
-    - Confirm the implementation follows the technical plan
-    - Report final status with summary of completed work
-
----
-
-## 🚫 Anti-Hallucination Rules
-
-1.  **No Magic Imports:** Never import a library or file without checking `ls` or `package.json` first.
-2.  **Strict Diff-Only:** When modifying existing files, use minimal edits.
-3.  **Stop & Ask:** If you find yourself editing more than 3 files for a "simple fix," **STOP**. You are likely cascading a regression. Ask for strategic guidance.
-
----
-
-Note: This command assumes a complete task breakdown exists in tasks.md. If tasks are incomplete or missing, suggest running `/speckit.tasks` first to regenerate the task list.

.agents/skills/speckit.migrate/SKILL.md

@@ -1,106 +0,0 @@
----
-name: speckit.migrate
-description: Migrate existing projects into the speckit structure by generating spec.md, plan.md, and tasks.md from existing code.
-version: 1.0.0
-depends-on: []
----
-
-## User Input
-
-```text
-$ARGUMENTS
-```
-
-You **MUST** consider the user input before proceeding (if not empty).
-
-## Role
-
-You are the **Antigravity Migration Specialist**. Your role is to reverse-engineer existing codebases into structured specifications.
-
-## Task
-
-### Outline
-
-Analyze an existing codebase and generate speckit artifacts (spec.md, plan.md, tasks.md) that document what currently exists.
-
-### Execution Steps
-
-1. **Parse Arguments**:
-   - `--path <dir>`: Directory to analyze (default: current repo root)
-   - `--feature <name>`: Feature name for output directory
-   - `--depth <n>`: Analysis depth (1=overview, 2=detailed, 3=exhaustive)
-
-2. **Codebase Discovery**:
-   ```bash
-   # Get project structure
-   tree -L 3 --dirsfirst -I 'node_modules|.git|dist|build' > /tmp/structure.txt
-   
-   # Find key files
-   find . -name "*.md" -o -name "package.json" -o -name "*.config.*" | head -50
-   ```
-
-3. **Analyze Architecture**:
-   - Identify framework/stack from config files
-   - Map directory structure to components
-   - Find entry points (main, index, app)
-   - Identify data models/entities
-   - Map API endpoints (if applicable)
-
-4. **Generate spec.md** (reverse-engineered):
-   ```markdown
-   # [Feature Name] - Specification (Migrated)
-   
-   > This specification was auto-generated from existing code.
-   > Review and refine before using for future development.
-   
-   ## Overview
-   [Inferred from README, comments, and code structure]
-   
-   ## Functional Requirements
-   [Extracted from existing functionality]
-   
-   ## Key Entities
-   [From data models, schemas, types]
-   ```
-
-5. **Generate plan.md** (reverse-engineered):
-   ```markdown
-   # [Feature Name] - Technical Plan (Migrated)
-   
-   ## Current Architecture
-   [Documented from codebase analysis]
-   
-   ## Technology Stack
-   [From package.json, imports, configs]
-   
-   ## Component Map
-   [Directory → responsibility mapping]
-   ```
-
-6. **Generate tasks.md** (completion status):
-   ```markdown
-   # [Feature Name] - Tasks (Migrated)
-   
-   All tasks marked [x] represent existing implemented functionality.
-   Tasks marked [ ] are inferred gaps or TODOs found in code.
-   
-   ## Existing Implementation
-   - [x] [Component A] - Implemented in `src/componentA/`
-   - [x] [Component B] - Implemented in `src/componentB/`
-   
-   ## Identified Gaps
-   - [ ] [Missing tests for X]
-   - [ ] [TODO comment at Y]
-   ```
-
-7. **Output**:
-   - Create feature directory: `.specify/features/[feature-name]/`
-   - Write all three files
-   - Report summary with confidence scores
-
-## Operating Principles
-
-- **Don't Invent**: Only document what exists, mark uncertainties as [INFERRED]
-- **Preserve Intent**: Use code comments and naming to understand purpose
-- **Flag TODOs**: Any TODO/FIXME/HACK in code becomes an open task
-- **Be Conservative**: When unsure, ask rather than assume

.agents/skills/speckit.plan/templates/agent-file-template.md

@@ -1,28 +0,0 @@
-# [PROJECT NAME] Development Guidelines
-
-Auto-generated from all feature plans. Last updated: [DATE]
-
-## Active Technologies
-
-[EXTRACTED FROM ALL PLAN.MD FILES]
-
-## Project Structure
-
-```text
-[ACTUAL STRUCTURE FROM PLANS]
-```
-
-## Commands
-
-[ONLY COMMANDS FOR ACTIVE TECHNOLOGIES]
-
-## Code Style
-
-[LANGUAGE-SPECIFIC, ONLY FOR LANGUAGES IN USE]
-
-## Recent Changes
-
-[LAST 3 FEATURES AND WHAT THEY ADDED]
-
-<!-- MANUAL ADDITIONS START -->
-<!-- MANUAL ADDITIONS END -->

.agents/skills/speckit.plan/templates/plan-template.md

@@ -1,104 +0,0 @@
-# Implementation Plan: [FEATURE]
-
-**Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link]
-**Input**: Feature specification from `/specs/[###-feature-name]/spec.md`
-
-**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/commands/plan.md` for the execution workflow.
-
-## Summary
-
-[Extract from feature spec: primary requirement + technical approach from research]
-
-## Technical Context
-
-<!--
-  ACTION REQUIRED: Replace the content in this section with the technical details
-  for the project. The structure here is presented in advisory capacity to guide
-  the iteration process.
--->
-
-**Language/Version**: [e.g., Python 3.11, Swift 5.9, Rust 1.75 or NEEDS CLARIFICATION]  
-**Primary Dependencies**: [e.g., FastAPI, UIKit, LLVM or NEEDS CLARIFICATION]  
-**Storage**: [if applicable, e.g., PostgreSQL, CoreData, files or N/A]  
-**Testing**: [e.g., pytest, XCTest, cargo test or NEEDS CLARIFICATION]  
-**Target Platform**: [e.g., Linux server, iOS 15+, WASM or NEEDS CLARIFICATION]
-**Project Type**: [single/web/mobile - determines source structure]  
-**Performance Goals**: [domain-specific, e.g., 1000 req/s, 10k lines/sec, 60 fps or NEEDS CLARIFICATION]  
-**Constraints**: [domain-specific, e.g., <200ms p95, <100MB memory, offline-capable or NEEDS CLARIFICATION]  
-**Scale/Scope**: [domain-specific, e.g., 10k users, 1M LOC, 50 screens or NEEDS CLARIFICATION]
-
-## Constitution Check
-
-*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
-
-[Gates determined based on constitution file]
-
-## Project Structure
-
-### Documentation (this feature)
-
-```text
-specs/[###-feature]/
-├── plan.md              # This file (/speckit.plan command output)
-├── research.md          # Phase 0 output (/speckit.plan command)
-├── data-model.md        # Phase 1 output (/speckit.plan command)
-├── quickstart.md        # Phase 1 output (/speckit.plan command)
-├── contracts/           # Phase 1 output (/speckit.plan command)
-└── tasks.md             # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
-```
-
-### Source Code (repository root)
-<!--
-  ACTION REQUIRED: Replace the placeholder tree below with the concrete layout
-  for this feature. Delete unused options and expand the chosen structure with
-  real paths (e.g., apps/admin, packages/something). The delivered plan must
-  not include Option labels.
--->
-
-```text
-# [REMOVE IF UNUSED] Option 1: Single project (DEFAULT)
-src/
-├── models/
-├── services/
-├── cli/
-└── lib/
-
-tests/
-├── contract/
-├── integration/
-└── unit/
-
-# [REMOVE IF UNUSED] Option 2: Web application (when "frontend" + "backend" detected)
-backend/
-├── src/
-│   ├── models/
-│   ├── services/
-│   └── api/
-└── tests/
-
-frontend/
-├── src/
-│   ├── components/
-│   ├── pages/
-│   └── services/
-└── tests/
-
-# [REMOVE IF UNUSED] Option 3: Mobile + API (when "iOS/Android" detected)
-api/
-└── [same as backend above]
-
-ios/ or android/
-└── [platform-specific structure: feature modules, UI flows, platform tests]
-```
-
-**Structure Decision**: [Document the selected structure and reference the real
-directories captured above]
-
-## Complexity Tracking
-
-> **Fill ONLY if Constitution Check has violations that must be justified**
-
-| Violation | Why Needed | Simpler Alternative Rejected Because |
-|-----------|------------|-------------------------------------|
-| [e.g., 4th project] | [current need] | [why 3 projects insufficient] |
-| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient] |

.agents/skills/speckit.quizme/SKILL.md

@@ -1,67 +0,0 @@
----
-name: speckit.quizme
-description: Challenge the specification with Socratic questioning to identify logical gaps, unhandled edge cases, and robustness issues.
-version: 1.0.0
-handoffs:
-  - label: Clarify Spec Requirements
-    agent: speckit.clarify
-    prompt: Clarify specification requirements
----
-
-## User Input
-
-```text
-$ARGUMENTS
-```
-
-You **MUST** consider the user input before proceeding (if not empty).
-
-## Role
-
-You are the **Antigravity Red Teamer**. Your role is to play the "Socratic Teacher" and challenge specifications for logical fallacies, naive assumptions, and happy-path bias. You find the edge cases that others miss and force robustness into the design.
-
-## Task
-
-### Outline
-
-Goal: Act as a "Red Team" or "Socratic Teacher" to challenge the current feature specification. Unlike `speckit.clarify` (which looks for missing definitions), `speckit.quizme` looks for logical fallacies, race conditions, naive assumptions, and "happy path" bias.
-
-Execution steps:
-
-1. **Setup**: Run `../scripts/bash/check-prerequisites.sh --json` from repo root and parse FEATURE_DIR.
-
-2. **Load Spec**: Read `spec.md` and `plan.md` (if exists).
-
-3. **Analyze for Weaknesses** (Internal Thought Process):
-   - Identify "Happy Path" assumptions (e.g., "User clicks button and saves").
-   - Look for temporal/state gaps (e.g., "What if the user clicks twice?", "What if the network fails mid-save?").
-   - Challenge business logic (e.g., "You allow deleting users, but what happens to their data?").
-   - Challenge security (e.g., "You rely on client-side validation here, but what if I curl the API?").
-
-4. **The Quiz Loop**:
-   - Present 3-5 challenging scenarios _one by one_.
-   - Format:
-
-     > **Scenario**: [Describe a plausible edge case or failure]
-     > **Current Spec**: [Quote where the spec implies behavior or is silent]
-     > **The Quiz**: What should the system do here?
-
-   - Wait for user answer.
-   - Critique the answer:
-     - If user says "It errors", ask "What error? To whom? Logged where?"
-     - If user says "It shouldn't happen", ask "How do you prevent it?"
-
-5. **Capture & Refine**:
-   - For each resolved scenario, generate a new requirement or edge case bullet.
-   - Ask user for permission to add it to `spec.md`.
-   - On approval, append to `Edge Cases` or `Requirements` section.
-
-6. **Completion**:
-   - Report number of scenarios covered.
-   - List new requirements added.
-
-## Operating Principles
-
-- **Be a Skeptic**: Don't assume the happy path works.
-- **Focus on "When" and "If"**: When high load, If network drops, When concurrent edits.
-- **Don't be annoying**: Focus on _critical_ flaws, not nitpicks.

.agents/skills/speckit.reviewer/SKILL.md

@@ -1,136 +0,0 @@
----
-name: speckit.reviewer
-description: Perform code review with actionable feedback and suggestions.
-version: 1.0.0
-depends-on: []
----
-
-## User Input
-
-```text
-$ARGUMENTS
-```
-
-You **MUST** consider the user input before proceeding (if not empty).
-
-## Role
-
-You are the **Antigravity Code Reviewer**. Your role is to perform thorough code reviews, identify issues, and provide constructive, actionable feedback.
-
-## Task
-
-### Outline
-
-Review code changes and provide structured feedback with severity levels.
-
-### Execution Steps
-
-1. **Determine Review Scope**:
-   - If user provides file paths: Review those files
-   - If user says "staged" or no args: Review git staged changes
-   - If user says "branch": Compare current branch to main/master
-
-   ```bash
-   # Get staged changes
-   git diff --cached --name-only
-   
-   # Get branch changes
-   git diff main...HEAD --name-only
-   ```
-
-2. **Load Files for Review**:
-   - Read each file in scope
-   - For diffs, focus on changed lines with context
-
-3. **Review Categories**:
-
-   | Category | What to Check |
-   |----------|--------------|
-   | **Correctness** | Logic errors, off-by-one, null handling |
-   | **Security** | SQL injection, XSS, secrets in code |
-   | **Performance** | N+1 queries, unnecessary loops, memory leaks |
-   | **Maintainability** | Complexity, duplication, naming |
-   | **Best Practices** | Error handling, logging, typing |
-   | **Style** | Consistency, formatting (if no linter) |
-
-4. **Analyze Each File**:
-   For each file, check:
-   - Does the code do what it claims?
-   - Are edge cases handled?
-   - Is error handling appropriate?
-   - Are there security concerns?
-   - Is the code testable?
-   - Is the naming clear and consistent?
-
-5. **Severity Levels**:
-
-   | Level | Meaning | Block Merge? |
-   |-------|---------|--------------|
-   | 🔴 CRITICAL | Security issue, data loss risk | Yes |
-   | 🟠 HIGH | Bug, logic error | Yes |
-   | 🟡 MEDIUM | Code smell, maintainability | Maybe |
-   | 🟢 LOW | Style, minor improvement | No |
-   | 💡 SUGGESTION | Nice-to-have, optional | No |
-
-6. **Generate Review Report**:
-   ```markdown
-   # Code Review Report
-   
-   **Date**: [timestamp]
-   **Scope**: [files reviewed]
-   **Overall**: APPROVE | REQUEST CHANGES | NEEDS DISCUSSION
-   
-   ## Summary
-   
-   | Severity | Count |
-   |----------|-------|
-   | 🔴 Critical | X |
-   | 🟠 High | X |
-   | 🟡 Medium | X |
-   | 🟢 Low | X |
-   | 💡 Suggestions | X |
-   
-   ## Findings
-   
-   ### 🔴 CRITICAL: SQL Injection Risk
-   **File**: `src/db/queries.ts:45`
-   **Code**:
-   ```typescript
-   const query = `SELECT * FROM users WHERE id = ${userId}`;
-   ```
-   **Issue**: User input directly concatenated into SQL query
-   **Fix**: Use parameterized queries:
-   ```typescript
-   const query = 'SELECT * FROM users WHERE id = $1';
-   await db.query(query, [userId]);
-   ```
-   
-   ### 🟡 MEDIUM: Complex Function
-   **File**: `src/auth/handler.ts:120`
-   **Issue**: Function has cyclomatic complexity of 15
-   **Suggestion**: Extract into smaller functions
-   
-   ## What's Good
-   
-   - Clear naming conventions
-   - Good test coverage
-   - Proper TypeScript types
-   
-   ## Recommended Actions
-   
-   1. **Must fix before merge**: [critical/high items]
-   2. **Should address**: [medium items]
-   3. **Consider for later**: [low/suggestions]
-   ```
-
-7. **Output**:
-   - Display report
-   - If CRITICAL or HIGH issues: Recommend blocking merge
-
-## Operating Principles
-
-- **Be Constructive**: Every criticism should have a fix suggestion
-- **Be Specific**: Quote exact code, provide exact line numbers
-- **Be Balanced**: Mention what's good, not just what's wrong
-- **Prioritize**: Focus on real issues, not style nitpicks
-- **Be Educational**: Explain WHY something is an issue

.agents/skills/speckit.security-audit/SKILL.md

@@ -1,199 +0,0 @@
----
-name: speckit.security-audit
-description: Perform a security-focused audit of the codebase against OWASP Top 10, CASL authorization, and LCBP3-DMS security requirements.
-version: 1.0.0
-depends-on:
-  - speckit.checker
----
-
-## Role
-
-You are the **Antigravity Security Sentinel**. Your mission is to identify security vulnerabilities, authorization gaps, and compliance issues specific to the LCBP3-DMS project before they reach production.
-
-## Task
-
-Perform a comprehensive security audit covering OWASP Top 10, CASL permission enforcement, file upload safety, and project-specific security rules defined in `specs/06-Decision-Records/ADR-016-security.md`.
-
-## Context Loading
-
-Before auditing, load the security context:
-
-1. Read `specs/06-Decision-Records/ADR-016-security.md` for project security decisions
-2. Read `specs/05-Engineering-Guidelines/05-02-backend-guidelines.md` for backend security patterns
-3. Read `specs/03-Data-and-Storage/lcbp3-v1.7.0-seed-permissions.sql` for CASL permission definitions
-4. Read `GEMINI.md` for security rules (Section: Security & Integrity Rules)
-
-## Execution Steps
-
-### Phase 1: OWASP Top 10 Scan
-
-Scan the `backend/src/` directory for each OWASP category:
-
-| #   | OWASP Category            | What to Check                                                                            | Files to Scan                                     |
-| --- | ------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------- |
-| A01 | Broken Access Control     | Missing `@UseGuards(JwtAuthGuard, CaslAbilityGuard)` on controllers, unprotected routes  | `**/*.controller.ts`                              |
-| A02 | Cryptographic Failures    | Hardcoded secrets, weak hashing, missing HTTPS enforcement                               | `**/*.ts`, `docker-compose*.yml`                  |
-| A03 | Injection                 | Raw SQL queries, unsanitized user input in TypeORM queries, template literals in queries | `**/*.service.ts`, `**/*.repository.ts`           |
-| A04 | Insecure Design           | Missing rate limiting on auth endpoints, no idempotency checks on mutations              | `**/*.controller.ts`, `**/*.guard.ts`             |
-| A05 | Security Misconfiguration | Missing Helmet.js, CORS misconfiguration, debug mode in production                       | `main.ts`, `app.module.ts`, `docker-compose*.yml` |
-| A06 | Vulnerable Components     | Outdated dependencies with known CVEs                                                    | `package.json`, `pnpm-lock.yaml`                  |
-| A07 | Auth Failures             | Missing brute-force protection, weak password policy, JWT misconfiguration               | `auth/`, `**/*.strategy.ts`                       |
-| A08 | Data Integrity            | Missing input validation, unvalidated file types, missing CSRF protection                | `**/*.dto.ts`, `**/*.interceptor.ts`              |
-| A09 | Logging Failures          | Missing audit logs for security events, sensitive data in logs                           | `**/*.service.ts`, `**/*.interceptor.ts`          |
-| A10 | SSRF                      | Unrestricted outbound requests, user-controlled URLs                                     | `**/*.service.ts`                                 |
-
-### Phase 2: CASL Authorization Audit
-
-1. **Load permission matrix** from `specs/03-Data-and-Storage/lcbp3-v1.7.0-seed-permissions.sql`
-2. **Scan all controllers** for `@UseGuards(CaslAbilityGuard)` coverage:
-
-   ```bash
-   # Find controllers without CASL guard
-   grep -rL "CaslAbilityGuard" backend/src/modules/*/\*.controller.ts
-   ```
-
-3. **Verify 4-Level RBAC enforcement**:
-   - Level 1: System Admin (full access)
-   - Level 2: Project Admin (project-scoped)
-   - Level 3: Department Lead (department-scoped)
-   - Level 4: User (own-records only)
-
-4. **Check ability definitions** — ensure every endpoint has:
-   - `@CheckPolicies()` or `@Can()` decorator
-   - Correct action (`read`, `create`, `update`, `delete`, `manage`)
-   - Correct subject (entity class, not string)
-
-5. **Cross-reference with routes** — verify:
-   - No public endpoints that should be protected
-   - No endpoints with broader permissions than required (principle of least privilege)
-   - Query scoping: users can only query their own records (unless admin)
-
-### Phase 3: File Upload Security (ClamAV)
-
-Check LCBP3-DMS-specific file handling per ADR-016:
-
-1. **Two-Phase Storage verification**:
-   - Upload goes to temp directory first → scanned by ClamAV → moved to permanent
-   - Check for direct writes to permanent storage (violation)
-
-2. **ClamAV integration**:
-   - Verify ClamAV service is configured in `docker-compose*.yml`
-   - Check that file upload endpoints call ClamAV scan before commit
-   - Verify rejection flow for infected files
-
-3. **File type validation**:
-   - Check allowed MIME types against whitelist
-   - Verify file extension validation exists
-   - Check for double-extension attacks (e.g., `file.pdf.exe`)
-
-4. **File size limits**:
-   - Verify upload size limits are enforced
-   - Check for path traversal in filenames (`../`, `..\\`)
-
-### Phase 4: LCBP3-DMS-Specific Checks
-
-1. **Idempotency** — verify all POST/PUT/PATCH endpoints check `Idempotency-Key` header:
-
-   ```bash
-   # Find mutation endpoints without idempotency
-   grep -rn "@Post\|@Put\|@Patch" backend/src/modules/*/\*.controller.ts
-   # Cross-reference with idempotency guard usage
-   grep -rn "IdempotencyGuard\|Idempotency-Key" backend/src/
-   ```
-
-2. **Optimistic Locking** — verify document entities use `@VersionColumn()`:
-
-   ```bash
-   grep -rn "VersionColumn" backend/src/modules/*/entities/*.entity.ts
-   ```
-
-3. **Redis Redlock** — verify document numbering uses distributed locks:
-
-   ```bash
-   grep -rn "Redlock\|redlock\|acquireLock" backend/src/
-   ```
-
-4. **Password Security** — verify bcrypt with 12+ salt rounds:
-
-   ```bash
-   grep -rn "bcrypt\|saltRounds\|genSalt" backend/src/
-   ```
-
-5. **Rate Limiting** — verify throttle guard on auth endpoints:
-
-   ```bash
-   grep -rn "ThrottlerGuard\|@Throttle" backend/src/modules/auth/
-   ```
-
-6. **Environment Variables** — ensure no `.env` files for production:
-   - Check for `.env` files committed to git
-   - Verify Docker compose uses `environment:` section, not `env_file:`
-
-## Severity Classification
-
-| Severity       | Description                                           | Response                |
-| -------------- | ----------------------------------------------------- | ----------------------- |
-| 🔴 **Critical** | Exploitable vulnerability, data exposure, auth bypass | Immediate fix required  |
-| 🟠 **High**     | Missing security control, potential escalation path   | Fix before next release |
-| 🟡 **Medium**   | Best practice violation, defense-in-depth gap         | Plan fix in sprint      |
-| 🟢 **Low**      | Informational, minor hardening opportunity            | Track in backlog        |
-
-## Report Format
-
-Generate a structured report:
-
-```markdown
-# 🔒 Security Audit Report
-
-**Date**: <date>
-**Scope**: <backend/frontend/both>
-**Auditor**: Antigravity Security Sentinel
-
-## Summary
-
-| Severity   | Count |
-| ---------- | ----- |
-| 🔴 Critical | X     |
-| 🟠 High     | X     |
-| 🟡 Medium   | X     |
-| 🟢 Low      | X     |
-
-## Findings
-
-### [SEV-001] <Title> — 🔴 Critical
-
-**Category**: OWASP A01 / CASL / ClamAV / LCBP3-Specific
-**File**: `<path>:<line>`
-**Description**: <what is wrong>
-**Impact**: <what could happen>
-**Recommendation**: <how to fix>
-**Code Example**:
-\`\`\`typescript
-// Before (vulnerable)
-...
-// After (fixed)
-...
-\`\`\`
-
-## CASL Coverage Matrix
-
-| Module | Controller      | Guard? | Policies? | Level        |
-| ------ | --------------- | ------ | --------- | ------------ |
-| auth   | AuthController  | ✅      | ✅         | N/A (public) |
-| users  | UsersController | ✅      | ✅         | L1-L4        |
-| ...    | ...             | ...    | ...       | ...          |
-
-## Recommendations Priority
-
-1. <Critical fix 1>
-2. <Critical fix 2>
-   ...
-```
-
-## Operating Principles
-
-- **Read-Only**: This skill only reads and reports. Never modify code.
-- **Evidence-Based**: Every finding must include the exact file path and line number.
-- **No False Confidence**: If a check is inconclusive, mark it as "⚠️ Needs Manual Review" rather than passing.
-- **LCBP3-Specific**: Prioritize project-specific rules (idempotency, ClamAV, Redlock) over generic checks.
-- **Frontend Too**: If scope includes frontend, also check for XSS in React components, unescaped user data, and exposed API keys.

.agents/skills/speckit.specify/SKILL.md

@@ -1,264 +0,0 @@
----
-name: speckit.specify
-description: Create or update the feature specification from a natural language feature description.
-version: 1.0.0
-handoffs:
-  - label: Build Technical Plan
-    agent: speckit.plan
-    prompt: Create a plan for the spec. I am building with...
-  - label: Clarify Spec Requirements
-    agent: speckit.clarify
-    prompt: Clarify specification requirements
-    send: true
----
-
-## User Input
-
-```text
-$ARGUMENTS
-```
-
-You **MUST** consider the user input before proceeding (if not empty).
-
-## Role
-
-You are the **Antigravity Domain Scribe**. Your role is to translate natural language feature descriptions into highly structured, high-quality feature specifications (`spec.md`). You ensure clarity, testability, and alignment with the project's success criteria.
-
-## Task
-
-### Outline
-
-The text the user typed after `/speckit.specify` in the triggering message **is** the feature description. Assume you always have it available in this conversation even if `{{args}}` appears literally below. Do not ask the user to repeat it unless they provided an empty command.
-
-Given that feature description, do this:
-
-1. **Generate a concise short name** (2-4 words) for the branch:
-   - Analyze the feature description and extract the most meaningful keywords
-   - Create a 2-4 word short name that captures the essence of the feature
-   - Use action-noun format when possible (e.g., "add-user-auth", "fix-payment-bug")
-   - Preserve technical terms and acronyms (OAuth2, API, JWT, etc.)
-   - Keep it concise but descriptive enough to understand the feature at a glance
-   - Examples:
-     - "I want to add user authentication" → "user-auth"
-     - "Implement OAuth2 integration for the API" → "oauth2-api-integration"
-     - "Create a dashboard for analytics" → "analytics-dashboard"
-     - "Fix payment processing timeout bug" → "fix-payment-timeout"
-
-2. **Check for existing branches before creating new one**:
-
-   a. First, fetch all remote branches to ensure we have the latest information:
-
-   ```bash
-   git fetch --all --prune
-   ```
-
-   b. Find the highest feature number across all sources for the short-name:
-   - Remote branches: `git ls-remote --heads origin | grep -E 'refs/heads/[0-9]+-<short-name>$'`
-   - Local branches: `git branch | grep -E '^[* ]*[0-9]+-<short-name>$'`
-   - Specs directories: Check for directories matching `specs/[0-9]+-<short-name>`
-
-   c. Determine the next available number:
-   - Extract all numbers from all three sources
-   - Find the highest number N
-   - Use N+1 for the new branch number
-
-   d. Run the script `../scripts/bash/create-new-feature.sh --json "{{args}}"` with the calculated number and short-name:
-   - Pass `--number N+1` and `--short-name "your-short-name"` along with the feature description
-   - Bash example: `.specify/scripts/bash/create-new-feature.sh --json "{{args}}" --json --number 5 --short-name "user-auth" "Add user authentication"`
-   - PowerShell example: `.specify/scripts/bash/create-new-feature.sh --json "{{args}}" -Json -Number 5 -ShortName "user-auth" "Add user authentication"`
-
-   **IMPORTANT**:
-   - Check all three sources (remote branches, local branches, specs directories) to find the highest number
-   - Only match branches/directories with the exact short-name pattern
-   - If no existing branches/directories found with this short-name, start with number 1
-   - You must only ever run this script once per feature
-   - The JSON is provided in the terminal as output - always refer to it to get the actual content you're looking for
-   - The JSON output will contain BRANCH_NAME and SPEC_FILE paths
-   - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\\''m Groot' (or double-quote if possible: "I'm Groot")
-
-3. Load `templates/spec-template.md` to understand required sections.
-
-4. Follow this execution flow:
-   1. Parse user description from Input
-      If empty: ERROR "No feature description provided"
-   2. Extract key concepts from description
-      Identify: actors, actions, data, constraints
-   3. For unclear aspects:
-      - Make informed guesses based on context and industry standards
-      - Only mark with [NEEDS CLARIFICATION: specific question] if:
-        - The choice significantly impacts feature scope or user experience
-        - Multiple reasonable interpretations exist with different implications
-        - No reasonable default exists
-      - **LIMIT: Maximum 3 [NEEDS CLARIFICATION] markers total**
-      - Prioritize clarifications by impact: scope > security/privacy > user experience > technical details
-   4. Fill User Scenarios & Testing section
-      If no clear user flow: ERROR "Cannot determine user scenarios"
-   5. Generate Functional Requirements
-      Each requirement must be testable
-      Use reasonable defaults for unspecified details (document assumptions in Assumptions section)
-   6. Define Success Criteria
-      Create measurable, technology-agnostic outcomes
-      Include both quantitative metrics (time, performance, volume) and qualitative measures (user satisfaction, task completion)
-      Each criterion must be verifiable without implementation details
-   7. Identify Key Entities (if data involved)
-   8. Return: SUCCESS (spec ready for planning)
-
-5. Write the specification to SPEC_FILE using the template structure, replacing placeholders with concrete details derived from the feature description (arguments) while preserving section order and headings.
-
-6. **Specification Quality Validation**: After writing the initial spec, validate it against quality criteria:
-
-   a. **Create Spec Quality Checklist**: Generate a checklist file at `FEATURE_DIR/checklists/requirements.md` using the checklist template structure with these validation items:
-
-   ```markdown
-   # Specification Quality Checklist: [FEATURE NAME]
-
-   **Purpose**: Validate specification completeness and quality before proceeding to planning
-   **Created**: [DATE]
-   **Feature**: [Link to spec.md]
-
-   ## Content Quality
-
-   - [ ] No implementation details (languages, frameworks, APIs)
-   - [ ] Focused on user value and business needs
-   - [ ] Written for non-technical stakeholders
-   - [ ] All mandatory sections completed
-
-   ## Requirement Completeness
-
-   - [ ] No [NEEDS CLARIFICATION] markers remain
-   - [ ] Requirements are testable and unambiguous
-   - [ ] Success criteria are measurable
-   - [ ] Success criteria are technology-agnostic (no implementation details)
-   - [ ] All acceptance scenarios are defined
-   - [ ] Edge cases are identified
-   - [ ] Scope is clearly bounded
-   - [ ] Dependencies and assumptions identified
-
-   ## Feature Readiness
-
-   - [ ] All functional requirements have clear acceptance criteria
-   - [ ] User scenarios cover primary flows
-   - [ ] Feature meets measurable outcomes defined in Success Criteria
-   - [ ] No implementation details leak into specification
-
-   ## Notes
-
-   - Items marked incomplete require spec updates before `/speckit.clarify` or `/speckit.plan`
-   ```
-
-   b. **Run Validation Check**: Review the spec against each checklist item:
-   - For each item, determine if it passes or fails
-   - Document specific issues found (quote relevant spec sections)
-
-   c. **Handle Validation Results**:
-   - **If all items pass**: Mark checklist complete and proceed to step 6
-
-   - **If items fail (excluding [NEEDS CLARIFICATION])**:
-     1. List the failing items and specific issues
-     2. Update the spec to address each issue
-     3. Re-run validation until all items pass (max 3 iterations)
-     4. If still failing after 3 iterations, document remaining issues in checklist notes and warn user
-
-   - **If [NEEDS CLARIFICATION] markers remain**:
-     1. Extract all [NEEDS CLARIFICATION: ...] markers from the spec
-     2. **LIMIT CHECK**: If more than 3 markers exist, keep only the 3 most critical (by scope/security/UX impact) and make informed guesses for the rest
-     3. For each clarification needed (max 3), present options to user in this format:
-
-        ```markdown
-        ## Question [N]: [Topic]
-
-        **Context**: [Quote relevant spec section]
-
-        **What we need to know**: [Specific question from NEEDS CLARIFICATION marker]
-
-        **Suggested Answers**:
-
-        | Option | Answer                    | Implications                          |
-        | ------ | ------------------------- | ------------------------------------- |
-        | A      | [First suggested answer]  | [What this means for the feature]     |
-        | B      | [Second suggested answer] | [What this means for the feature]     |
-        | C      | [Third suggested answer]  | [What this means for the feature]     |
-        | Custom | Provide your own answer   | [Explain how to provide custom input] |
-
-        **Your choice**: _[Wait for user response]_
-        ```
-
-     4. **CRITICAL - Table Formatting**: Ensure markdown tables are properly formatted:
-        - Use consistent spacing with pipes aligned
-        - Each cell should have spaces around content: `| Content |` not `|Content|`
-        - Header separator must have at least 3 dashes: `|--------|`
-        - Test that the table renders correctly in markdown preview
-     5. Number questions sequentially (Q1, Q2, Q3 - max 3 total)
-     6. Present all questions together before waiting for responses
-     7. Wait for user to respond with their choices for all questions (e.g., "Q1: A, Q2: Custom - [details], Q3: B")
-     8. Update the spec by replacing each [NEEDS CLARIFICATION] marker with the user's selected or provided answer
-     9. Re-run validation after all clarifications are resolved
-
-   d. **Update Checklist**: After each validation iteration, update the checklist file with current pass/fail status
-
-7. Report completion with branch name, spec file path, checklist results, and readiness for the next phase (`/speckit.clarify` or `/speckit.plan`).
-
-**NOTE:** The script creates and checks out the new branch and initializes the spec file before writing.
-
-## General Guidelines
-
-## Quick Guidelines
-
-- Focus on **WHAT** users need and **WHY**.
-- Avoid HOW to implement (no tech stack, APIs, code structure).
-- Written for business stakeholders, not developers.
-- DO NOT create any checklists that are embedded in the spec. That will be a separate command.
-
-### Section Requirements
-
-- **Mandatory sections**: Must be completed for every feature
-- **Optional sections**: Include only when relevant to the feature
-- When a section doesn't apply, remove it entirely (don't leave as "N/A")
-
-### For AI Generation
-
-When creating this spec from a user prompt:
-
-1. **Make informed guesses**: Use context, industry standards, and common patterns to fill gaps
-2. **Document assumptions**: Record reasonable defaults in the Assumptions section
-3. **Limit clarifications**: Maximum 3 [NEEDS CLARIFICATION] markers - use only for critical decisions that:
-   - Significantly impact feature scope or user experience
-   - Have multiple reasonable interpretations with different implications
-   - Lack any reasonable default
-4. **Prioritize clarifications**: scope > security/privacy > user experience > technical details
-5. **Think like a tester**: Every vague requirement should fail the "testable and unambiguous" checklist item
-6. **Common areas needing clarification** (only if no reasonable default exists):
-   - Feature scope and boundaries (include/exclude specific use cases)
-   - User types and permissions (if multiple conflicting interpretations possible)
-   - Security/compliance requirements (when legally/financially significant)
-
-**Examples of reasonable defaults** (don't ask about these):
-
-- Data retention: Industry-standard practices for the domain
-- Performance targets: Standard web/mobile app expectations unless specified
-- Error handling: User-friendly messages with appropriate fallbacks
-- Authentication method: Standard session-based or OAuth2 for web apps
-- Integration patterns: RESTful APIs unless specified otherwise
-
-### Success Criteria Guidelines
-
-Success criteria must be:
-
-1. **Measurable**: Include specific metrics (time, percentage, count, rate)
-2. **Technology-agnostic**: No mention of frameworks, languages, databases, or tools
-3. **User-focused**: Describe outcomes from user/business perspective, not system internals
-4. **Verifiable**: Can be tested/validated without knowing implementation details
-
-**Good examples**:
-
-- "Users can complete checkout in under 3 minutes"
-- "System supports 10,000 concurrent users"
-- "95% of searches return results in under 1 second"
-- "Task completion rate improves by 40%"
-
-**Bad examples** (implementation-focused):
-
-- "API response time is under 200ms" (too technical, use "Users see results instantly")
-- "Database can handle 1000 TPS" (implementation detail, use user-facing metric)
-- "React components render efficiently" (framework-specific)
-- "Redis cache hit rate above 80%" (technology-specific)

.agents/skills/speckit.specify/templates/spec-template.md

@@ -1,115 +0,0 @@
-# Feature Specification: [FEATURE NAME]
-
-**Feature Branch**: `[###-feature-name]`  
-**Created**: [DATE]  
-**Status**: Draft  
-**Input**: User description: "$ARGUMENTS"
-
-## User Scenarios & Testing *(mandatory)*
-
-<!--
-  IMPORTANT: User stories should be PRIORITIZED as user journeys ordered by importance.
-  Each user story/journey must be INDEPENDENTLY TESTABLE - meaning if you implement just ONE of them,
-  you should still have a viable MVP (Minimum Viable Product) that delivers value.
-  
-  Assign priorities (P1, P2, P3, etc.) to each story, where P1 is the most critical.
-  Think of each story as a standalone slice of functionality that can be:
-  - Developed independently
-  - Tested independently
-  - Deployed independently
-  - Demonstrated to users independently
--->
-
-### User Story 1 - [Brief Title] (Priority: P1)
-
-[Describe this user journey in plain language]
-
-**Why this priority**: [Explain the value and why it has this priority level]
-
-**Independent Test**: [Describe how this can be tested independently - e.g., "Can be fully tested by [specific action] and delivers [specific value]"]
-
-**Acceptance Scenarios**:
-
-1. **Given** [initial state], **When** [action], **Then** [expected outcome]
-2. **Given** [initial state], **When** [action], **Then** [expected outcome]
-
----
-
-### User Story 2 - [Brief Title] (Priority: P2)
-
-[Describe this user journey in plain language]
-
-**Why this priority**: [Explain the value and why it has this priority level]
-
-**Independent Test**: [Describe how this can be tested independently]
-
-**Acceptance Scenarios**:
-
-1. **Given** [initial state], **When** [action], **Then** [expected outcome]
-
----
-
-### User Story 3 - [Brief Title] (Priority: P3)
-
-[Describe this user journey in plain language]
-
-**Why this priority**: [Explain the value and why it has this priority level]
-
-**Independent Test**: [Describe how this can be tested independently]
-
-**Acceptance Scenarios**:
-
-1. **Given** [initial state], **When** [action], **Then** [expected outcome]
-
----
-
-[Add more user stories as needed, each with an assigned priority]
-
-### Edge Cases
-
-<!--
-  ACTION REQUIRED: The content in this section represents placeholders.
-  Fill them out with the right edge cases.
--->
-
-- What happens when [boundary condition]?
-- How does system handle [error scenario]?
-
-## Requirements *(mandatory)*
-
-<!--
-  ACTION REQUIRED: The content in this section represents placeholders.
-  Fill them out with the right functional requirements.
--->
-
-### Functional Requirements
-
-- **FR-001**: System MUST [specific capability, e.g., "allow users to create accounts"]
-- **FR-002**: System MUST [specific capability, e.g., "validate email addresses"]  
-- **FR-003**: Users MUST be able to [key interaction, e.g., "reset their password"]
-- **FR-004**: System MUST [data requirement, e.g., "persist user preferences"]
-- **FR-005**: System MUST [behavior, e.g., "log all security events"]
-
-*Example of marking unclear requirements:*
-
-- **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]
-- **FR-007**: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified]
-
-### Key Entities *(include if feature involves data)*
-
-- **[Entity 1]**: [What it represents, key attributes without implementation]
-- **[Entity 2]**: [What it represents, relationships to other entities]
-
-## Success Criteria *(mandatory)*
-
-<!--
-  ACTION REQUIRED: Define measurable success criteria.
-  These must be technology-agnostic and measurable.
--->
-
-### Measurable Outcomes
-
-- **SC-001**: [Measurable metric, e.g., "Users can complete account creation in under 2 minutes"]
-- **SC-002**: [Measurable metric, e.g., "System handles 1000 concurrent users without degradation"]
-- **SC-003**: [User satisfaction metric, e.g., "90% of users successfully complete primary task on first attempt"]
-- **SC-004**: [Business metric, e.g., "Reduce support tickets related to [X] by 50%"]

.agents/skills/speckit.status/SKILL.md

@@ -1,107 +0,0 @@
----
-name: speckit.status
-description: Display a dashboard showing feature status, completion percentage, and blockers.
-version: 1.0.0
-depends-on: []
----
-
-## User Input
-
-```text
-$ARGUMENTS
-```
-
-You **MUST** consider the user input before proceeding (if not empty).
-
-## Role
-
-You are the **Antigravity Status Reporter**. Your role is to provide clear, actionable status updates on project progress.
-
-## Task
-
-### Outline
-
-Generate a dashboard view of all features and their completion status.
-
-### Execution Steps
-
-1. **Discover Features**:
-   ```bash
-   # Find all feature directories
-   find .specify/features -maxdepth 1 -type d 2>/dev/null || echo "No features found"
-   ```
-
-2. **For Each Feature, Gather Metrics**:
-
-   | Artifact | Check | Metric |
-   |----------|-------|--------|
-   | spec.md | Exists? | Has [NEEDS CLARIFICATION]? |
-   | plan.md | Exists? | All sections complete? |
-   | tasks.md | Exists? | Count [x] vs [ ] vs [/] |
-   | checklists/*.md | All items checked? | Checklist completion % |
-
-3. **Calculate Completion**:
-   ```
-   Phase 1 (Specify): spec.md exists & no clarifications needed
-   Phase 2 (Plan): plan.md exists & complete
-   Phase 3 (Tasks): tasks.md exists
-   Phase 4 (Implement): tasks.md completion %
-   Phase 5 (Validate): validation-report.md exists with PASS
-   ```
-
-4. **Identify Blockers**:
-   - [NEEDS CLARIFICATION] markers
-   - [ ] tasks with no progress
-   - Failed checklist items
-   - Missing dependencies
-
-5. **Generate Dashboard**:
-   ```markdown
-   # Speckit Status Dashboard
-   
-   **Generated**: [timestamp]
-   **Total Features**: X
-   
-   ## Overview
-   
-   | Feature | Phase | Progress | Blockers | Next Action |
-   |---------|-------|----------|----------|-------------|
-   | auth-system | Implement | 75% | 0 | Complete remaining tasks |
-   | payment-flow | Plan | 40% | 2 | Resolve clarifications |
-   
-   ## Feature Details
-   
-   ### [Feature Name]
-   
-   ```
-   Spec:  ████████░░ 80%
-   Plan:  ██████████ 100%
-   Tasks: ██████░░░░ 60%
-   ```
-   
-   **Blockers**:
-   - [ ] Clarification needed: "What payment providers?"
-   
-   **Recent Activity**:
-   - Last modified: [date]
-   - Files changed: [list]
-   
-   ---
-   
-   ## Summary
-   
-   - Features Ready for Implementation: X
-   - Features Blocked: Y
-   - Overall Project Completion: Z%
-   ```
-
-6. **Output**:
-   - Display in terminal
-   - Optionally write to `.specify/STATUS.md`
-
-## Operating Principles
-
-- **Be Current**: Always read latest file state
-- **Be Visual**: Use progress bars and tables
-- **Be Actionable**: Every status should have a "next action"
-- **Be Fast**: Cache nothing, always recalculate

.agents/skills/speckit.tasks/templates/tasks-template.md

@@ -1,251 +0,0 @@
----
-
-description: "Task list template for feature implementation"
----
-
-# Tasks: [FEATURE NAME]
-
-**Input**: Design documents from `/specs/[###-feature-name]/`
-**Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/
-
-**Tests**: The examples below include test tasks. Tests are OPTIONAL - only include them if explicitly requested in the feature specification.
-
-**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.
-
-## Format: `[ID] [P?] [Story] Description`
-
-- **[P]**: Can run in parallel (different files, no dependencies)
-- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3)
-- Include exact file paths in descriptions
-
-## Path Conventions
-
-- **Single project**: `src/`, `tests/` at repository root
-- **Web app**: `backend/src/`, `frontend/src/`
-- **Mobile**: `api/src/`, `ios/src/` or `android/src/`
-- Paths shown below assume single project - adjust based on plan.md structure
-
-<!-- 
-  ============================================================================
-  IMPORTANT: The tasks below are SAMPLE TASKS for illustration purposes only.
-  
-  The /speckit.tasks command MUST replace these with actual tasks based on:
-  - User stories from spec.md (with their priorities P1, P2, P3...)
-  - Feature requirements from plan.md
-  - Entities from data-model.md
-  - Endpoints from contracts/
-  
-  Tasks MUST be organized by user story so each story can be:
-  - Implemented independently
-  - Tested independently
-  - Delivered as an MVP increment
-  
-  DO NOT keep these sample tasks in the generated tasks.md file.
-  ============================================================================
--->
-
-## Phase 1: Setup (Shared Infrastructure)
-
-**Purpose**: Project initialization and basic structure
-
-- [ ] T001 Create project structure per implementation plan
-- [ ] T002 Initialize [language] project with [framework] dependencies
-- [ ] T003 [P] Configure linting and formatting tools
-
----
-
-## Phase 2: Foundational (Blocking Prerequisites)
-
-**Purpose**: Core infrastructure that MUST be complete before ANY user story can be implemented
-
-**⚠️ CRITICAL**: No user story work can begin until this phase is complete
-
-Examples of foundational tasks (adjust based on your project):
-
-- [ ] T004 Setup database schema and migrations framework
-- [ ] T005 [P] Implement authentication/authorization framework
-- [ ] T006 [P] Setup API routing and middleware structure
-- [ ] T007 Create base models/entities that all stories depend on
-- [ ] T008 Configure error handling and logging infrastructure
-- [ ] T009 Setup environment configuration management
-
-**Checkpoint**: Foundation ready - user story implementation can now begin in parallel
-
----
-
-## Phase 3: User Story 1 - [Title] (Priority: P1) 🎯 MVP
-
-**Goal**: [Brief description of what this story delivers]
-
-**Independent Test**: [How to verify this story works on its own]
-
-### Tests for User Story 1 (OPTIONAL - only if tests requested) ⚠️
-
-> **NOTE: Write these tests FIRST, ensure they FAIL before implementation**
-
-- [ ] T010 [P] [US1] Contract test for [endpoint] in tests/contract/test_[name].py
-- [ ] T011 [P] [US1] Integration test for [user journey] in tests/integration/test_[name].py
-
-### Implementation for User Story 1
-
-- [ ] T012 [P] [US1] Create [Entity1] model in src/models/[entity1].py
-- [ ] T013 [P] [US1] Create [Entity2] model in src/models/[entity2].py
-- [ ] T014 [US1] Implement [Service] in src/services/[service].py (depends on T012, T013)
-- [ ] T015 [US1] Implement [endpoint/feature] in src/[location]/[file].py
-- [ ] T016 [US1] Add validation and error handling
-- [ ] T017 [US1] Add logging for user story 1 operations
-
-**Checkpoint**: At this point, User Story 1 should be fully functional and testable independently
-
----
-
-## Phase 4: User Story 2 - [Title] (Priority: P2)
-
-**Goal**: [Brief description of what this story delivers]
-
-**Independent Test**: [How to verify this story works on its own]
-
-### Tests for User Story 2 (OPTIONAL - only if tests requested) ⚠️
-
-- [ ] T018 [P] [US2] Contract test for [endpoint] in tests/contract/test_[name].py
-- [ ] T019 [P] [US2] Integration test for [user journey] in tests/integration/test_[name].py
-
-### Implementation for User Story 2
-
-- [ ] T020 [P] [US2] Create [Entity] model in src/models/[entity].py
-- [ ] T021 [US2] Implement [Service] in src/services/[service].py
-- [ ] T022 [US2] Implement [endpoint/feature] in src/[location]/[file].py
-- [ ] T023 [US2] Integrate with User Story 1 components (if needed)
-
-**Checkpoint**: At this point, User Stories 1 AND 2 should both work independently
-
----
-
-## Phase 5: User Story 3 - [Title] (Priority: P3)
-
-**Goal**: [Brief description of what this story delivers]
-
-**Independent Test**: [How to verify this story works on its own]
-
-### Tests for User Story 3 (OPTIONAL - only if tests requested) ⚠️
-
-- [ ] T024 [P] [US3] Contract test for [endpoint] in tests/contract/test_[name].py
-- [ ] T025 [P] [US3] Integration test for [user journey] in tests/integration/test_[name].py
-
-### Implementation for User Story 3
-
-- [ ] T026 [P] [US3] Create [Entity] model in src/models/[entity].py
-- [ ] T027 [US3] Implement [Service] in src/services/[service].py
-- [ ] T028 [US3] Implement [endpoint/feature] in src/[location]/[file].py
-
-**Checkpoint**: All user stories should now be independently functional
-
----
-
-[Add more user story phases as needed, following the same pattern]
-
----
-
-## Phase N: Polish & Cross-Cutting Concerns
-
-**Purpose**: Improvements that affect multiple user stories
-
-- [ ] TXXX [P] Documentation updates in docs/
-- [ ] TXXX Code cleanup and refactoring
-- [ ] TXXX Performance optimization across all stories
-- [ ] TXXX [P] Additional unit tests (if requested) in tests/unit/
-- [ ] TXXX Security hardening
-- [ ] TXXX Run quickstart.md validation
-
----
-
-## Dependencies & Execution Order
-
-### Phase Dependencies
-
-- **Setup (Phase 1)**: No dependencies - can start immediately
-- **Foundational (Phase 2)**: Depends on Setup completion - BLOCKS all user stories
-- **User Stories (Phase 3+)**: All depend on Foundational phase completion
-  - User stories can then proceed in parallel (if staffed)
-  - Or sequentially in priority order (P1 → P2 → P3)
-- **Polish (Final Phase)**: Depends on all desired user stories being complete
-
-### User Story Dependencies
-
-- **User Story 1 (P1)**: Can start after Foundational (Phase 2) - No dependencies on other stories
-- **User Story 2 (P2)**: Can start after Foundational (Phase 2) - May integrate with US1 but should be independently testable
-- **User Story 3 (P3)**: Can start after Foundational (Phase 2) - May integrate with US1/US2 but should be independently testable
-
-### Within Each User Story
-
-- Tests (if included) MUST be written and FAIL before implementation
-- Models before services
-- Services before endpoints
-- Core implementation before integration
-- Story complete before moving to next priority
-
-### Parallel Opportunities
-
-- All Setup tasks marked [P] can run in parallel
-- All Foundational tasks marked [P] can run in parallel (within Phase 2)
-- Once Foundational phase completes, all user stories can start in parallel (if team capacity allows)
-- All tests for a user story marked [P] can run in parallel
-- Models within a story marked [P] can run in parallel
-- Different user stories can be worked on in parallel by different team members
-
----
-
-## Parallel Example: User Story 1
-
-```bash
-# Launch all tests for User Story 1 together (if tests requested):
-Task: "Contract test for [endpoint] in tests/contract/test_[name].py"
-Task: "Integration test for [user journey] in tests/integration/test_[name].py"
-
-# Launch all models for User Story 1 together:
-Task: "Create [Entity1] model in src/models/[entity1].py"
-Task: "Create [Entity2] model in src/models/[entity2].py"
-```
-
----
-
-## Implementation Strategy
-
-### MVP First (User Story 1 Only)
-
-1. Complete Phase 1: Setup
-2. Complete Phase 2: Foundational (CRITICAL - blocks all stories)
-3. Complete Phase 3: User Story 1
-4. **STOP and VALIDATE**: Test User Story 1 independently
-5. Deploy/demo if ready
-
-### Incremental Delivery
-
-1. Complete Setup + Foundational → Foundation ready
-2. Add User Story 1 → Test independently → Deploy/Demo (MVP!)
-3. Add User Story 2 → Test independently → Deploy/Demo
-4. Add User Story 3 → Test independently → Deploy/Demo
-5. Each story adds value without breaking previous stories
-
-### Parallel Team Strategy
-
-With multiple developers:
-
-1. Team completes Setup + Foundational together
-2. Once Foundational is done:
-   - Developer A: User Story 1
-   - Developer B: User Story 2
-   - Developer C: User Story 3
-3. Stories complete and integrate independently
-
----
-
-## Notes
-
-- [P] tasks = different files, no dependencies
-- [Story] label maps task to specific user story for traceability
-- Each user story should be independently completable and testable
-- Verify tests fail before implementing
-- Commit after each task or logical group
-- Stop at any checkpoint to validate story independently
-- Avoid: vague tasks, same file conflicts, cross-story dependencies that break independence